Modem key management

The modem key management library provides functions to manage the credentials stored in the nRF91 Series LTE modem. The library uses credential storage management to add, update, and delete credentials using the %CMNG command. See the Credential storage management %CMNG section in the nRF9160 AT Commands Reference Guide or the same section in the nRF91x1 AT Commands Reference Guide, depending on the SiP you are using.

Each set of keys and certificates that is stored in the modem is identified by a security tag (sec_tag). You specify this tag when adding the credentials and use it when you update or delete them. All related credentials share the same security tag. You can use the library to check if a specific security tag exists.

To establish a connection, pass the security tag to the Modem library when creating a secure socket.

See Security tags for more information about how security tags are used in the Modem library.

Certificates

You can download a certificate for a given server using your web browser. Alternatively, you can obtain it from a dedicated website like SSL Labs.

Certificates come in different formats. To provision the certificate to the nRF91 Series DK, it must be in PEM format. The PEM format looks like this:

-----BEGIN CERTIFICATE-----
MIIDujCCAqKgAwIBAgILBAAAAAABD4Ym5g0wDQYJKoZIhvcNAQEFBQAwTDEgMB4G
A1UECxMXR2xvYmFsU2lnbiBSb290IENBIC0gUjIxEzARBgNVBAoTCkdsb2JhbFNp
Z24xEzARBgNVBAMTCkdsb2JhbFNpZ24wHhcNMDYxMjE1MDgwMDAwWhcNMjExMjE1
MDgwMDAwWjBMMSAwHgYDVQQLExdHbG9iYWxTaWduIFJvb3QgQ0EgLSBSMjETMBEG
A1UEChMKR2xvYmFsU2lnbjETMBEGA1UEAxMKR2xvYmFsU2lnbjCCASIwDQYJKoZI
hvcNAQEBBQADggEPADCCAQoCggEBAKbPJA6+Lm8omUVCxKs+IVSbC9N/hHD6ErPL
v4dfxn+G07IwXNb9rfF73OX4YJYJkhD10FPe+3t+c4isUoh7SqbKSaZeqKeMWhG8
eoLrvozps6yWJQeXSpkqBy+0Hne/ig+1AnwblrjFuTosvNYSuetZfeLQBoZfXklq
tTleiDTsvHgMCJiEbKjNS7SgfQx5TfC4LcshytVsW33hoCmEofnTlEnLJGKRILzd
C9XZzPnqJworc5HGnRusyMvo4KD0L5CLTfuwNhv2GXqF4G3yYROIXJ/gkwpRl4pa
zq+r1feqCapgvdzZX99yqWATXgAByUr6P6TqBwMhAo6CygPCm48CAwEAAaOBnDCB
mTAOBgNVHQ8BAf8EBAMCAQYwDwYDVR0TAQH/BAUwAwEB/zAdBgNVHQ4EFgQUm+IH
V2ccHsBqBt5ZtJot39wZhi4wNgYDVR0fBC8wLTAroCmgJ4YlaHR0cDovL2NybC5n
bG9iYWxzaWduLm5ldC9yb290LXIyLmNybDAfBgNVHSMEGDAWgBSb4gdXZxwewGoG
3lm0mi3f3BmGLjANBgkqhkiG9w0BAQUFAAOCAQEAmYFThxxol4aR7OBKuEQLq4Gs
J0/WwbgcQ3izDJr86iw8bmEbTUsp9Z8FHSbBuOmDAGJFtqkIk7mpM0sYmsL4h4hO
291xNBrBVNpGP+DTKqttVCL1OmLNIG+6KYnX3ZHu01yiPqFbQfXf5WRDLenVOavS
ot+3i9DAgBkcRcAtjOj4LaR0VknFBbVPFd5uRHg5h6h+u/N5GJG79G+dwfCMNYxd
AfvDbbnvRG15RjF+Cv6pgsH/76tuIMRQyV+dTZsXjAzlAcmgQWpzU/qlULRuJQ/7
TBj0/VLZjmmx6BEP3ojY+x1J96relc8geMJgEtslQIxq/H5COEBkEveegeGTLg==
-----END CERTIFICATE-----

See the comprehensive tutorial on SSL.com for instructions on how to convert between different certificate formats and encodings.

API documentation

Header file: include/modem/modem_key_mgmt.h
Source files: lib/modem_key_mgmt/
group modem_key_mgmt

Enums

enum modem_key_mgmt_cred_type

Credential types.

Values:

enumerator MODEM_KEY_MGMT_CRED_TYPE_CA_CHAIN
enumerator MODEM_KEY_MGMT_CRED_TYPE_PUBLIC_CERT
enumerator MODEM_KEY_MGMT_CRED_TYPE_PRIVATE_CERT
enumerator MODEM_KEY_MGMT_CRED_TYPE_PSK
enumerator MODEM_KEY_MGMT_CRED_TYPE_IDENTITY

Functions

int modem_key_mgmt_write(nrf_sec_tag_t sec_tag, enum modem_key_mgmt_cred_type cred_type, const void *buf, size_t len)

Write or update a credential in persistent storage.

Store the credential and associate it with the given security tag, which can later be used to access it.

Note

If used when the LTE link is active, the function will return an error and the key will not be written.

Parameters:

  • sec_tag – [in] Security tag to associate with this credential.

  • cred_type – [in] The credential type.

  • buf – [in] Buffer containing the credential data.

  • len – [in] Length of the buffer.

Return values:

  • 0 – On success.

  • -EINVAL – Invalid parameters.

  • -ENOMEM – Not enough memory to store the credential.

  • -ENOENT – The security tag sec_tag is invalid.

  • -EACCES – Access to credential not allowed.

  • -EALREADY – Credential already exists (and can’t be overwritten).

  • -EPERM – Not permitted when the LTE link is active.

  • -ECANCELED – Canceled because voltage is low (power off warning).

int modem_key_mgmt_delete(nrf_sec_tag_t sec_tag, enum modem_key_mgmt_cred_type cred_type)

Delete a credential from persistent storage.

Note

If used when the LTE link is active, the function will return an error and the key will not be written.

Parameters:

  • sec_tag – [in] The security tag of the credential.

  • cred_type – [in] The credential type.

Return values:

  • 0 – On success.

  • -ENOBUFS – Internal buffer is too small.

  • -ENOENT – No credential associated with the given sec_tag and cred_type.

  • -EACCES – Access to credential not allowed.

  • -EPERM – Not permitted when the LTE link is active.

  • -ECANCELED – Canceled because voltage is low (power off warning).

int modem_key_mgmt_read(nrf_sec_tag_t sec_tag, enum modem_key_mgmt_cred_type cred_type, void *buf, size_t *len)

Read a credential from persistent storage.

Parameters:

  • sec_tag – [in] The security tag of the credential.

  • cred_type – [in] The credential type.

  • buf – [out] Buffer to read the credential into.

  • len – [inout] Length of the buffer, length of the credential.

Return values:

  • 0 – On success.

  • -ENOBUFS – Internal buffer is too small.

  • -ENOMEM – Credential does not fit in buf.

  • -ENOENT – No credential associated with the given sec_tag and cred_type.

  • -EACCES – Access to credential not allowed.

int modem_key_mgmt_cmp(nrf_sec_tag_t sec_tag, enum modem_key_mgmt_cred_type cred_type, const void *buf, size_t len)

Compare a credential with a credential in persistent storage.

Parameters:

  • sec_tag – [in] The security tag of the credential.

  • cred_type – [in] The credential type.

  • buf – [in] Buffer to compare the credential to.

  • len – [in] Length of the buffer.

Return values:

  • 0 – If the credentials match.

  • 1 – If the credentials do not match.

  • -ENOBUFS – Internal buffer is too small.

  • -ENOENT – No credential associated with the given sec_tag and cred_type.

  • -EACCES – Access to credential not allowed.

int modem_key_mgmt_exists(nrf_sec_tag_t sec_tag, enum modem_key_mgmt_cred_type cred_type, bool *exists)

Check if a credential exists in persistent storage.

Parameters:

  • sec_tag – [in] The security tag to search for.

  • cred_type – [in] The credential type.

  • exists – [out] Whether the credential exists. Only valid if the operation is successful.

Return values:

  • 0 – On success.

  • -ENOBUFS – Internal buffer is too small.

  • -EACCES – Access to credential not allowed.