Skip to main content

Certificate database (database)

The certificate handler (certhandler) provides functionality to create keys, apply certificates, and retrieve info about installed keys and certificates. The keys and certificates can be located on different storages, for example, security device (TPM), file system, etc. In order to support different certificate storages and allow to extend supported ones, handling of certificate storages is done by certificate handler modules (plugins). The certificate handler implements only basic functions such as managing certificate modules, generating CSR, updating DB, whereas creating keys and applying certificates are implemented directly by the appropriate certificate handler module. Currently, the following modules are implemented:

  • swmodule – to create keys and store certificates on a file system
  • tpmmodule – to create keys and store certificates in a TPM device
  • pkcs11module – to create kays and store certificates in PKCS11 cryptographic token

Initialization​

On initialization, the certificate handler creates and initializes configured certificate modules and performs DB synchronization. DB synchronization is required to have up-to-date information about installed certificates and keys in case they were changed outside of IAM scope. For DB synchronization, the certificate handler retrieves information about valid, invalid keys and certificates from each certificate module, and uses this information to update DB.

Owning the storage​

Some security devices (TPM) supports owning procedure. The owning procedure is to lock the device with an owner password. Once the storage is owned, any changes such as creating, deleting keys are allowed only with the owner password. IAM doesn't store the owner password permanently. Thus, an external entity generates the owner password and provides it later for creating a key. In our case, the provisioning script generates the owner password and owns the storage. It sends this password to the cloud. The cloud, in its turn, keeps it encrypted and provides it for renewing the certificates. To disable owning for the storage, Clear API should be used. Clearing the storage removes the owner password as well as removing all created keys and certificates. It is used on system de-provisioning.

Creating key and certificate​

Deploying certificate to the storage consists of two steps:

  • Client sends create key request. The certificate handler creates a key in the selected storage and sends back CSR;
  • Client generates the certificate based on CSR and sends it to the certificate handler. The certificate handler stores the certificate and returns the status.

clientclientcerthandlercerthandlerCreate keyCSRApply certificateStatus

Additionally to the basic CSR payload, the certificate handler adds some extended fields based on the selected module configuration. Extended CSR fields:

  • extendedKeyUsage – indicates it is client certificate, server certificate, or both;
  • alternativeNames – a list of alternative names for the server certificate.

The number of keys and certificates that should be stored on dedicated certificate storage is configured in the module configuration (maxItems). After a new certificate applying, the certificate handler checks if the current certificate count exceeds maxItems, then it removes the oldest (by expiration date) certificates in order to have not more than maxItems certificates stored. The module itself should be capable to store maxItems + 1 key and certificate. It is required because the certificate handler applies a new certificate first and then removes old ones in order to have a valid certificate in case applying the current one fails.

Getting key and certificate​

The certificate handler provides information about the key and certificate location. The client requests the certificate issuer and serial, the certificate handler returns the location of the certificate and corresponding key. To handle different types of storage URL format is used for the location. URL scheme indicates the type of storage, authority, and path indicates the location inside the storage. Currently, the following schemes are supported:

  • tpm – indicates that item is located inside TPM device; the authority indicates the TPM handle in this case: tpm://0x80000001 means that the item is located in TMP and its handle is 0x80000001
  • file – indicates that item is located on a file system, path indicates absolute item path: file://var/crypto/cert.pem means the item is located on the file system with absolute path /var/crypto/cert.pem
  • pkcs11 – indicates that the item is located on a PKCS11 cryptographic token (see PKCS11 URI Scheme)

If issuer and serial are not provided (empty), the certificate manager returns the newest certificate and key from the selected storage.

The PKCS11 module is designed to use secure storage which has PKCS11 Cryptographic Token Interface (see the PKCS11 specification). The module works with the storage using a dedicated C library which matches the above specification. Thus, IAM may work with different HW or SW tokens using one PKCS11 module. For example TPM, TEE.

loading...

IAM uses PKCS11 tokens to generate and store key pairs as well as store certificates.

PKCS11 device consists of slots. The slot is a logical partition of a cryptographic device that potentially contains a cryptographic token (token can be removed).

Before using, the token should be initialized, user and SO (secure officer) pins should be applied. It is done during the unit provisioning. SO pin is generated by the provisioning script and stored on the cloud. It is provided to the unit in encrypted form when needed. SO pin is required to reinitialize or clear the slot. The user pin is stored as a file on an encrypted partition (see Configuration) or set to the specific value in the case of using TEE identity with OP-TEE PKCS11 TA (OP-TEE PKCS11 TA).

The token can be identified by the index in the list of slots, or by the unique slot ID, or by the token label (see Configuration). The token label can be assigned during the token initialization, thereby if PKCS11 module is configured to use token by label and there is no initialized token with this label, the module will choose the first uninitialized slot and will initialize it with the selected label. Then this token will be used next time after the provisioning.

loading...

The user pin is required to perform different slot operations such as creating keys, storing certificates, performing data decryption etc. Each PKCS11 object (key, certificate) has special PKCS11 attributes which allow identifying objects inside the slot. PKCS11 module uses CKA_ID and CKA_LABEL attributes (see the PKCS11 specification) to manage PKCS11 objects. It assigns the same CKA_ID for private and public keys during keys generation and assigns it for the corresponding certificate when storing the certificate. The keys and the corresponding certificate can be retrieved by the CKA_ID attribute. The CKA_LABEL attribute is set to storage type.

IAM is capable to use a separate slot for one storage type as well as share slots between different storage types. In the case of sharing one slot, CKA_LABEL is used to distinguish different storage objects:

loading...loading...

OP-TEE PKCS11 TA Edit

IAM can use PKCS11 TA provided by OP-TEE to use OP-TEE secure storage capability (https://www.op-tee.org/). To use it, OP-TEE client (OP-TEE Client) with libckteec and PKCS11 TA (OP-TEE OS) should be configured and deployed to the unit. When OP-TEE PKCS11 TA is used it is possible to use TEE identity (see the TEE specification) instead of SO and user PIN. TEE identity allows using Linux user and group authentication to access token objects and operations, accordingly instead of using SO and user password the token can be authorized to be used by the specific Linux user or group (see https://github.com/OP-TEE/optee_os/pull/4222 for information how TEE identity is done in OP-TEE). To use the OP-TEE TEE identity, the CKTEEC_LOGIN_TYPE environment variable should be set to the proper value. It may take the following values:

  • public — any user or group is authorized to access token
  • user — only specific user is authorized to use token (the user ID (UID) is set by user pin during token initialization)
  • group — only a specific group is authorized to use the token (the group ID (GID) is set by user pin during token initialization). The CKTEEC_LOGIN_GID environment variable shall be the set GID.

IAM sets local CKTEEC_LOGIN_TYPE and CKTEEC_LOGIN_GID to the appropriate values depending on the module configuration. Other clients (such as SM) should set these variables before using the PKCS11 OP-TEE token with TEE identity.

The preferred authentication method for units is using OP-TEE PKCS11 TA.

Configuration​

The PKCS11 module is configured with the following parameters (see Identity and Access Manager configuration for detail):

  • library – specifies the path to the PKCS11 library used for this storage
  • slotId – specifies the slot ID used for the storage (only one parameter or slotId or slotIndex or tokenLabel can be set to select token)
  • slotIndex – specifies the slot index used for the storge (only one parameter or slotId or slotIndex or tokenLabel can be set to select token)
  • tokenLabel – specifies the token label used for the storage (only one parameter or slotId or slotIndex or tokenLabel can be set to select token)
  • userPinPath – specifies the path to the file where the user pin is located (should be set in case of user pin is used)
  • teeLoginType – specifies TEE login type: public, user, group (should be set to use OP-TEE TEE identity)
  • uid – specifies user ID (UID) authorized to use the token (should be set if teeLoginType set to user)
  • gid – specifies group ID (GID) authorized to use the token (should be set if teeLoginType set to group)
  • modulePathInURL – indicates if the path to the PKCS11 library should be included in the key/certificate URL as module-path fields (see the PKCS#11 URI scheme)
  • clearHookCmdArgs — specifies shell commands which will be executed additionally to the clear storage operation.