Modem key management¶
The modem key management library provides functions to manage the credentials stored in the nRF9160 LTE modem. The library uses AT commands (Credential storage management %CMNG) to add, update, and delete credentials.
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.
Important
Security credentials usually exceed the default AT command response length.
Therefore, you must set CONFIG_AT_CMD_RESPONSE_MAX_LEN
to a sufficiently high value when using this 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 nRF9160 DK, it must be in PEM format. The PEM format looks like this:
"-----BEGIN CERTIFICATE-----\n"
"MIIDujCCAqKgAwIBAgILBAAAAAABD4Ym5g0wDQYJKoZIhvcNAQEFBQAwTDEgMB4G\n"
"A1UECxMXR2xvYmFsU2lnbiBSb290IENBIC0gUjIxEzARBgNVBAoTCkdsb2JhbFNp\n"
"Z24xEzARBgNVBAMTCkdsb2JhbFNpZ24wHhcNMDYxMjE1MDgwMDAwWhcNMjExMjE1\n"
"MDgwMDAwWjBMMSAwHgYDVQQLExdHbG9iYWxTaWduIFJvb3QgQ0EgLSBSMjETMBEG\n"
"A1UEChMKR2xvYmFsU2lnbjETMBEGA1UEAxMKR2xvYmFsU2lnbjCCASIwDQYJKoZI\n"
"hvcNAQEBBQADggEPADCCAQoCggEBAKbPJA6+Lm8omUVCxKs+IVSbC9N/hHD6ErPL\n"
"v4dfxn+G07IwXNb9rfF73OX4YJYJkhD10FPe+3t+c4isUoh7SqbKSaZeqKeMWhG8\n"
"eoLrvozps6yWJQeXSpkqBy+0Hne/ig+1AnwblrjFuTosvNYSuetZfeLQBoZfXklq\n"
"tTleiDTsvHgMCJiEbKjNS7SgfQx5TfC4LcshytVsW33hoCmEofnTlEnLJGKRILzd\n"
"C9XZzPnqJworc5HGnRusyMvo4KD0L5CLTfuwNhv2GXqF4G3yYROIXJ/gkwpRl4pa\n"
"zq+r1feqCapgvdzZX99yqWATXgAByUr6P6TqBwMhAo6CygPCm48CAwEAAaOBnDCB\n"
"mTAOBgNVHQ8BAf8EBAMCAQYwDwYDVR0TAQH/BAUwAwEB/zAdBgNVHQ4EFgQUm+IH\n"
"V2ccHsBqBt5ZtJot39wZhi4wNgYDVR0fBC8wLTAroCmgJ4YlaHR0cDovL2NybC5n\n"
"bG9iYWxzaWduLm5ldC9yb290LXIyLmNybDAfBgNVHSMEGDAWgBSb4gdXZxwewGoG\n"
"3lm0mi3f3BmGLjANBgkqhkiG9w0BAQUFAAOCAQEAmYFThxxol4aR7OBKuEQLq4Gs\n"
"J0/WwbgcQ3izDJr86iw8bmEbTUsp9Z8FHSbBuOmDAGJFtqkIk7mpM0sYmsL4h4hO\n"
"291xNBrBVNpGP+DTKqttVCL1OmLNIG+6KYnX3ZHu01yiPqFbQfXf5WRDLenVOavS\n"
"ot+3i9DAgBkcRcAtjOj4LaR0VknFBbVPFd5uRHg5h6h+u/N5GJG79G+dwfCMNYxd\n"
"AfvDbbnvRG15RjF+Cv6pgsH/76tuIMRQyV+dTZsXjAzlAcmgQWpzU/qlULRuJQ/7\n"
"TBj0/VLZjmmx6BEP3ojY+x1J96relc8geMJgEtslQIxq/H5COEBkEveegeGTLg==\n"
"-----END CERTIFICATE-----\n"
Note the \n
at the end of each line.
See the comprehensive tutorial on SSL.com for instructions on how to convert between different certificate formats and encodings.
API documentation¶
include/modem/modem_key_mgmt.h
lib/modem_key_mgmt/
-
group
modem_key_mgmt
Enums
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.
- Returns 0
On success.
- Returns -EINVAL
Invalid parameters.
- Returns -ENOBUFS
Internal buffer is too small.
- Returns -ENOMEM
Not enough memory to store the credential.
- Returns -EACCES
Th operation failed because the LTE link is active.
- Returns -ENOENT
The security tag could not be written.
- Returns -EPERM
Insufficient permissions.
-
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.
- Returns 0
On success.
- Returns -ENOBUFS
Internal buffer is too small.
- Returns -ENOMEM
If provided buffer is too small for result data.
- Returns -ENOENT
No credential associated with the given
sec_tag
andcred_type
.- Returns -EPERM
Insufficient permissions.
-
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.
- Returns 0
If the credentials match.
- Returns 1
If the credentials do not match.
- Returns -ENOBUFS
Internal buffer is too small.
- Returns -ENOENT
No credential associated with the given
sec_tag
andcred_type
.- Returns -EPERM
Insufficient permissions.
-
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.
- Returns 0
On success.
- Returns -ENOBUFS
Internal buffer is too small.
- Returns -EACCES
The operation failed because the LTE link is active.
- Returns -ENOENT
No credential associated with the given
sec_tag
andcred_type
.- Returns -EPERM
Insufficient permissions.
-
int
modem_key_mgmt_permission_set
(nrf_sec_tag_t sec_tag, enum modem_key_mgmt_cred_type cred_type, uint8_t perm_flags)¶ Set permissions for a credential in persistent storage.
- Parameters
sec_tag – [in] The security tag of the credential.
cred_type – [in] The credential type.
perm_flags – [in] Permission flags. Not yet implemented.
- Returns 0
On success.
- Returns -ENOBUFS
Internal buffer is too small.
- Returns -ENOENT
No credential associated with the given
sec_tag
andcred_type
.- Returns -EPERM
Insufficient permissions.
-
int
modem_key_mgmt_exists
(nrf_sec_tag_t sec_tag, enum modem_key_mgmt_cred_type cred_type, bool *exists, uint8_t *perm_flags)¶ 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.
perm_flags – [out] The permission flags of the credential. Not yet implemented.
- Returns 0
On success.
- Returns -ENOBUFS
Internal buffer is too small.
- Returns -EPERM
Insufficient permissions.
-
int