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 BSD library when creating a secure socket.

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.

API documentation

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

Enums

enum modem_key_mgnt_cred_type

Credential types.

Values:

MODEM_KEY_MGMT_CRED_TYPE_CA_CHAIN
MODEM_KEY_MGMT_CRED_TYPE_PUBLIC_CERT
MODEM_KEY_MGMT_CRED_TYPE_PRIVATE_CERT
MODEM_KEY_MGMT_CRED_TYPE_PSK
MODEM_KEY_MGMT_CRED_TYPE_IDENTITY

Functions

int modem_key_mgmt_write(nrf_sec_tag_t sec_tag, enum modem_key_mgnt_cred_type cred_type, const void *buf, u16_t len)

Write or update a credential in persistent storage.

This function will 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
  • [in] sec_tag: Security tag to associate with this credential.

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

  • [in] len: Length of the buffer.

Return Value
  • 0: On success.

  • -EINVAL: Invalid parameters.

  • -ENOBUFS: Internal buffer is too small.

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

  • -EACCES: Th operation failed because the LTE link is active.

  • -ENOENT: The security tag could not be written.

  • -EPERM: Insufficient permissions.

  • -EIO: Internal error.

int modem_key_mgmt_read(nrf_sec_tag_t sec_tag, enum modem_key_mgnt_cred_type cred_type, void *buf, u16_t *len)

Read a credential from persistent storage.

Parameters
  • [in] sec_tag: The crediantial security tag.

  • [in] cred_type: Type of credential being read.

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

  • [inout] len: Length of the buffer.

Return Value
  • 0: On success.

  • -ENOBUFS: Internal buffer is too small.

  • -ENOMEM: If provided buffer is too small for result data. The required buffer size is written to

Parameters
  • len.:

Return Value
  • -ENOENT: No credential associated with the given sec_tag and cred_type.

  • -EPERM: Insufficient permissions.

  • -EIO: Internal error.

int modem_key_mgmt_delete(nrf_sec_tag_t sec_tag, enum modem_key_mgnt_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
  • [in] sec_tag: The credential security tag.

  • [in] cred_type: Type of credential being deleted.

Return Value
  • 0: On success.

  • -ENOBUFS: Internal buffer is too small.

  • -EACCES: The operation failed because the LTE link is active.

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

  • -EPERM: Insufficient permissions.

  • -EIO: Internal error.

int modem_key_mgmt_permission_set(nrf_sec_tag_t sec_tag, enum modem_key_mgnt_cred_type cred_type, u8_t perm_flags)

Set permissions for a credential in persistent storage.

Parameters
  • [in] sec_tag: The credential security tag.

  • [in] cred_type: The credential type.

  • [in] perm_flags: Permission flags. Not yet implemented.

Return Value
  • 0: On success.

  • -ENOBUFS: Internal buffer is too small.

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

  • -EPERM: Insufficient permissions.

  • -EIO: Internal error.

int modem_key_mgmt_exists(nrf_sec_tag_t sec_tag, enum modem_key_mgnt_cred_type cred_type, bool *exists, u8_t *perm_flags)

Check if a credential exists in persistent storage.

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

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

  • [out] perm_flags: The permission flags of the credential. Only valid if the operation is successful and

  • exists: is true. Not yet implemented.

Return Value
  • 0: On success.

  • -ENOBUFS: Internal buffer is too small.

  • -EPERM: Insufficient permissions.

  • -EIO: Internal error.