Share via

CertStore_InstallClientCertificate function

  • Article

Header: #include <applibs/certstore.h>

Installs a client certificate that consists of a public certificate and a private key with the specified ID. The ID can then be used to refer to the certificate in other functions. If any type of certificate is already installed with the same ID, it will be replaced with the new certificate.

int CertStore_InstallClientCertificate(const char *identifier, const char *certBlob, size_t certBlobLength, const char *privateKeyBlob, size_t privateKeyBlobLength, const char *privateKeyPassword);

Parameters

  • identifier The ID of the certificate.

  • certBlob A pointer to a blob that contains the public certificate in PEM format. The blob must only contain the content between the -----BEGIN... and -----END... tags. For example, the tags for a certificate are -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----.

  • certBlobLength The length of the certificate blob, not including the null-terminator character.

  • privateKeyBlob A pointer to a blob that contains the private key in PEM format.

  • privateKeyBlobLength The length of the certificate blob, not including the null-terminator character.

  • privateKeyPassword A pointer to a null-terminated character array that contains the private key password. The length of the array must be less than or equal to CERTSTORE_MAX_PRIVATE_KEY_PASSWORD_LENGTH bytes. A password is required if privateKeyBlob is encrypted.

Errors

Returns -1 if an error is encountered and sets errno to the error value.

  • EACCES: the operation isn't allowed because either the CertStore capability isn't set in the application manifest.

  • EAGAIN: the OS certstore component isn't ready yet.

  • EFAULT: the certBlob, identifier, or privateKeyBlob parameter is NULL.

  • EINVAL: the identifier parameter isn't NULL-terminated, the certBlob or privateKeyBlob includes invalid data.

  • ENOSPC: there is not enough space in the certificate storage for this certificate.

  • ERANGE: the certBlobLength or privateKeyBlobLength is zero or greater than CERTSTORE_MAX_CERT_SIZE or the privateKeyPassword length is greater than CERTSTORE_MAX_PRIVATE_KEY_PASSWORD_LENGTH.

Any other errno may also be specified; such errors aren't deterministic and there's no guarantee that the same behavior will be retained through system updates.

Return value

Returns 0 for success, or -1 for failure, in which case errno is set to the error value.

Remarks

A valid identifier must be a unique string from one to CERTSTORE_MAX_IDENTIFIER_LENGTH characters in length. The following characters are valid in an identifer:

  • 'A' to 'Z'
  • 'a' to 'z'
  • '0' to '9'
  • '.' or '-' or '_'

Caution

Because certificate IDs are system-wide, an azsphere command or a function call that adds a new certificate can overwrite a certificate that was added by an earlier command or function call, potentially causing network connection failures. We strongly recommend that you develop clear certificate update procedures and choose certificate IDs carefully.

See Certificate IDs for more information about how Azure Sphere uses certificate IDs.

Application manifest requirements

The application manifest must include the CertStore capability.