Secure Storage

This document provides a step-by-step guide for an application developer on how to use Secure Storage Services on the IED. Applications installed on the IED can use the Secure Storage Service to store secrets in an encrypted and secure manner, which cannot be accessed on the file system or by other applications.

The secure storage service allows to add the data in the form of key-value pair, change the value for the existing pair, delete them, and retrieve them with their respective keys.

Configurations

• Application container must be connected to a proxy-redirect network or the application must use host network mode (not recommended) to make REST calls to the Secure Storage v2 APIs.
• Host port 9443 is used by the system for this service and cannot be used for applications; if the application installed on the IED uses port 9443, then the application must be updated with a new port.

How to use secure-storage v2.0.0 APIs with an app on IED

The application must use SVID, which is SPIFFE Verifiable Identity Document, to use Secure Storage V2 APIs. They can be as follows:

• X.509-SVID - The X.509-SVID is used to establish mutual TLS secured channels between the Industrial Edge Runtime Time (i.e. edge-iot-core) and the application container.
• JWT-SVID - The JWT-SVID is used as an autherization token.

These SVIDs can be retrieved from the SPIFFE Workload API via the mounted sock path /var/run/edgedevice/edgeapiagent.sock.

SPIFFE supports libraries that allow interaction with the SPIFFE workload API for Go as SPIFFE Go library and Java as SPIFFE Java library. There also exists similar libraries in C, C++, Rust and Python.

Procedure

1. Fetch the API server's SPIFFE ID from the container's EDGE_SPIFFE_ID environment variable and use it as follows

   • To configure mTLS client that will use X.509-SVID. for e.g. in Go,

     authorizer := tlsconfig.AuthorizeID(spiffeid.FromString(os.Getenv("EDGE_SPIFFE_ID")))
     tlsConfig := tlsconfig.MTLSClientConfig(x509Source, x509Source, authorizer)
     

   • As the audience of the JWT-SVID. for e.g. in Go,

     audience:= os.Getenv("EDGE_SPIFFEE_ID")
     svid, err := jwtSource.FetchJWTSVID(ctx, jwtsvid.Params{ Audience: audience,})
     

   For more details on language specific SPIFFE Library Usage refer here.

2. Include the retrieved JWT-SVID in the Authorization header of the REST API call of secure storage with prefix "JWT ", e.g JWT 551e145c-3a06-4d4b-99a3-3d0fd7185174

3. The base API paths, depending on the configuration of the application container, are:

   • When the application connects to the proxy redirect API, the base path URL will be https://edge-iot-core.proxy-redirect:8443/b.service/api/v2/secure-storage

   • When the application connects, it either connects to the host network or has network mode as the host API base path URL will be https://127.0.0.1:9443/b.service/api/v2/secure-storage

Compatibility Matrices

For backward compatibility refer to the following IEDK versions:

API	IE Component	Description
Secure Storage API 1.0.0 Deprecated - (not recommended to use)	IEDK ≥ 1.9.0	APIs for storing data in secure storage in key-value pairs
Secure Storage API 2.0.0	IEDK ≥ 1.19.0	APIs for storing data in secure storage in key-value pairs

Feature compatibilities are shown below:

Version	Network Mode Host Compatibility	Modular Device Integration offering Compatibility	IE State Service
v1
v2

Secure Storage NFRs

Description	Value	Exceeding Values
Maximum number of key-value pairs which can be stored per application	50	If more key-value pairs are being supplied to store, a proper error message is replied in response
Maximum length of the key which can be stored	256 B	If a larger key is supplied, a proper error message is replied in response
Maximum length of the value which can be stored	64 KB	If a larger value is supplied, a proper error message is replied in response