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 authorization token.

These SVIDs can be retrieved from the SPIFFE Workload API via the mounted sock path /var/run/devicemodel/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

Secure Storage NFRs¶