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:

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

Usage 

The different types of credentials supported by the library are defined by the modem_key_mgmt_cred_type enum.

The following code snippet shows how to write a CA chain certificate to the modem:

int err;
static const char cert[] = {
        #include "YourCert.pem.inc"
};

err = modem_key_mgmt_write(<YOUR_SEC_TAG>, MODEM_KEY_MGMT_CRED_TYPE_CA_CHAIN, cert, sizeof(cert));
if (err) {
        printk("Failed to provision certificate, err %d\n", err);
}

The following code snippet shows how to check if a CA chain certificate exists in the modem:

int err;
bool exists;

err = modem_key_mgmt_exists(<YOUR_SEC_TAG>, MODEM_KEY_MGMT_CRED_TYPE_CA_CHAIN, &exists);
if (err) {
        printk("Failed to check if credential exists\n");
        return;
}

if (exists) {
        printk("Credential exists in the modem\n");
} else {
        printk("Credential does not exist in the modem\n");
}

The following code snippet shows how to check if the CA chain certificate stored in the modem is the same as another CA chain certificate:

int mismatch;
static const char cert[] = {
        #include "YourCert.pem.inc"
};

mismatch = modem_key_mgmt_cmp(<YOUR_SEC_TAG>, MODEM_KEY_MGMT_CRED_TYPE_CA_CHAIN, cert, sizeof(cert));
if (mismatch) {
        printk("Certificate mismatch\n");
} else {
        printk("Certificate match\n");
}

The following code snippet shows how to read a CA chain certificate stored in the modem:

int err;
char cert[CERT_SIZE];

err = modem_key_mgmt_read(<YOUR_SEC_TAG>, MODEM_KEY_MGMT_CRED_TYPE_CA_CHAIN, cert, sizeof(cert));
if (err) {
        printk("Failed to read certificate\n");
}

The following code snippet shows how to delete a CA chain certificate stored in the modem:

int err;

err = modem_key_mgmt_delete(<YOUR_SEC_TAG>, MODEM_KEY_MGMT_CRED_TYPE_CA_CHAIN);
if (err) {
        printk("Failed to delete existing certificate, err %d\n", err);
}

API documentation 

Header file: include/modem/modem_key_mgmt.h

Source files: lib/modem_key_mgmt/

nRF91 Modem Key Management

Modem key management

Certificates

Usage

API documentation

Certificates 

Usage 

API documentation 