Storing items

Storing a single item

The KCM API for storing items is kcm_item_store. This API supports the following item types, represented by the enumerator kcm_item_type_e:

• Private/public key
• Certificates
• Configuration parameters

Warning: Powering down a device, a power failure, or even a drop in power that occurs when you store an item with kcm_item_is_factory set to true can cause corruption of the saved factory item. The kcm_factory_reset API will fail if a factory item is corrupted. Do not power down a device while storing KCM factory items.

Examples of how to store factory items using the kcm_item_store API

kcm_status_e kcm_status;
uint8_t bts_mode = 1;
uint8_t bts_device_private_key[200] = {...}; // Buffer with bootstrap device private key
uint8_t bts_device_certificate[1024] = {...}; // Buffer with bootstrap device certificate data
uint8_t bts_uri = "coap://bootstrap.arm.com"

// Storing the useBootstrap configuration parameter
kcm_status = kcm_item_store((uint8_t*)g_fcc_use_bootstrap_parameter_name,
                            strlen(g_fcc_use_bootstrap_parameter_name),
                            KCM_CONFIG_ITEM,
                            true,
                            bts_mode,
                            sizeof(bts_mode),
                            NULL);
if(kcm_status != KCM_STATUS_SUCCESS) {
    return 1;
}

// Storing bootstrap device private key
kcm_status = kcm_item_store((uint8_t*)g_fcc_bootstrap_device_private_key_name,
                            strlen(g_fcc_bootstrap_device_private_key_name),
                            KCM_PRIVATE_KEY_ITEM,
                            true,
                            bts_device_private_key,
                            sizeof(bts_device_private_key),
                            NULL);
if(kcm_status != KCM_STATUS_SUCCESS) {
    return 1;
}

// Storing bootstrap device certificate
kcm_status = kcm_item_store((uint8_t*)g_fcc_bootstrap_device_certificate_name,
                            strlen(g_fcc_bootstrap_device_certificate_name),
                            KCM_CERTIFICATE_ITEM,
                            true,
                            bts_device_certificate,
                            sizeof(bts_device_certificate),
                            NULL);
if(kcm_status != KCM_STATUS_SUCCESS) {
    return 1;
}

// Storing bootstrap URI
kcm_status = kcm_item_store((uint8_t*)g_fcc_bootstrap_server_uri_name,
                            strlen(g_fcc_bootstrap_server_uri_name),
                            KCM_CONFIG_ITEM,
                            true,
                            bts_uri,
                            strlen(bts_uri) + 1,
                            NULL);
if(kcm_status != KCM_STATUS_SUCCESS) {
    return 1;
}

Storing a certificate chain

The KCM APIs for storing certificate chains are:

• kcm_cert_chain_create
• kcm_cert_chain_add_next
• kcm_cert_chain_close

Note: When an attempt to store a certificate chain fails, the whole chain is deleted.

Note: The maximum certificate chain length is five. The code macro that defines the maximum certificate chain length is KCM_MAX_NUMBER_OF_CERTIFICATES_IN_CHAIN.

Example of how to store a certificate chain

kcm_status_e kcm_status;
kcm_cert_chain_handle cert_chain_handle;
uint8_t bts_device_certificates[3][1024] = { {...} , {...} , {...} }; // Three buffers with bootstrap device certificates data
size_t chain_len = 3;
uint32_t i;

// Storing bootstrap device certificate chain
kcm_status = kcm_cert_chain_create(&cert_chain_handle,
                                   (uint8_t*)g_fcc_bootstrap_device_certificate_name,
                                   strlen(g_fcc_bootstrap_device_certificate_name),
                                   chain_len,
                                   true);
if(kcm_status != KCM_STATUS_SUCCESS) {
    return 1;
}

for (i = 0; i < chain_len; i++) {
    kcm_status = kcm_cert_chain_add_next(cert_chain_handle,
                                         bts_device_certificates[i],
                                         sizeof(bts_device_certificates[i]));
    if(kcm_status != KCM_STATUS_SUCCESS) {
        return 1;
    }
}

kcm_status = kcm_cert_chain_close(cert_chain_handle);
if(kcm_status != KCM_STATUS_SUCCESS) {
    return 1;
}