grisp_keychain

Common layer to access secrets and identities on GRiSP devices. The app provides a basic module limited to filesystem based handling, but it can be configured to use backends like grisp_cryptoauth.

Build

$ rebar3 compile

Configuration

The grisp_keychain application provides flexible configuration options for TLS certificate and key management. Configuration is done through the application environment (typically in sys.config).

Configuration

The implementation module to use for the keychain API. Defaults to grisp_keychain_filesystem.

{grisp_keychain, [
    {api_module, grisp_keychain_filesystem}
]}

TLS Configuration Options for grisp_keychain_filesystem

tls_use_client_certificate

Type: boolean() Default: true Description: Enable or disable the use of client certificates for TLS connections.

{tls_use_client_certificate, false}

tls_verify

Type: verify_none | verify_peer Default: verify_peer Description: Set the TLS verification mode.

• verify_peer: Verify the server certificate (recommended for production)
• verify_none: Skip server certificate verification (useful for testing)

{tls_verify, verify_peer}

Certificate and Key Paths

client_certs

Type: path_spec() Required: Yes (if tls_use_client_certificate is true) Description: Path to client certificate(s). Can point to a single file or a directory containing multiple certificates.

{client_certs, {priv, my_app, "certs/client.pem"}}

client_key

Type: path_spec() Required: Yes (if tls_use_client_certificate is true) Description: Path to the client private key file.

{client_key, {priv, my_app, "keys/client.key"}}

tls_client_trusted_certs

Type: path_spec() Default: {priv, grisp_keychain, ""} Description: Path to trusted client certificates (CA certificates that can verify the client cert).

{tls_client_trusted_certs, {priv, my_app, "certs/ca"}}

tls_server_trusted_certs

Type: path_spec() Optional Description: Base path to server trusted certificates. When provided with a domain name, the system will look for certificates in <base_path>/<domain_name>.

{tls_server_trusted_certs, {priv, my_app, "certs/servers"}}

Certificate Callback Functions

tls_client_trusted_certs_cb

Type: callback_spec() Optional Description: Callback function that returns additional client trusted certificates.

{tls_client_trusted_certs_cb, {my_module, get_client_certs}}
% or with arguments:
{tls_client_trusted_certs_cb, {my_module, get_certs, [client]}}

tls_server_trusted_certs_cb

Type: callback_spec() Optional Description: Callback function that returns additional server trusted certificates.

{tls_server_trusted_certs_cb, {my_module, get_server_certs}}

Path Specification Format

Paths can be specified in multiple formats:

1. Absolute path as string:

   "/absolute/path/to/cert.pem"

2. Binary path:

   <<"/absolute/path/to/cert.pem">>

3. Tuple format (relative to application directory):

   {priv, AppName, RelativePath}  % Relative to priv directory
   {test, AppName, RelativePath}  % Relative to test directory

Callback Specification Format

Callbacks can be specified as:

1. Module and function:

   {ModuleName, FunctionName}

2. Module, function, and arguments:

   {ModuleName, FunctionName, [Arg1, Arg2, ...]}

The callback function should return a list of certificates in DER format.

API Usage

grisp_keychain:tls_options/1

Get TLS options for a specific domain.

Options = grisp_keychain:tls_options(<<"example.com">>),
ssl:connect("example.com", 443, Options).

The domain parameter can be:

• atom() - e.g., 'example.com'
• string() - e.g., "example.com"
• binary() - e.g., <<"example.com">>
• undefined - disables Server Name Indication

grisp_keychain:read_cert/2

Read the primary client certificate in DER format.

DerCert = grisp_keychain:read_cert(primary, der).

Example Configuration

{grisp_keychain, [
    {api_module, grisp_keychain_filesystem},
    {tls_use_client_certificate, true},
    {tls_verify, verify_peer},
    {client_certs, {priv, my_app, "certs/client.pem"}},
    {client_key, {priv, my_app, "keys/client-key.pem"}},
    {tls_client_trusted_certs, {priv, my_app, "certs/ca"}},
    {tls_server_trusted_certs, {priv, my_app, "certs/servers"}}
]}

Certificate File Formats

• Certificates: PEM format (.pem or .crt extensions)
• Keys: PEM format, unencrypted only
• Directory loading: When a directory path is provided, all .pem and .crt files in that directory will be loaded