Share via

CertStore_InstallRootCACertificate function

  • Article

Header: #include <applibs/certstore.h>

Installs a Root CA certificate that consists of a public certificate in PEM format and assigns an ID to the certificate. 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_InstallRootCACertificate(const char *identifier, const char *certBlob,
                                       size_t certBlobLength);

Parameters

  • identifier The ID of the certificate.

  • certBlob A pointer to a blob that contains the public certificate in PEM format.

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

Errors

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

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

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

  • EFAULT: the certBlob or identifier is NULL.

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

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

  • ERANGE: the certBlobLength is zero or greater than CERTSTORE_MAX_CERT_SIZE.

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.