Certificates

Reference·Audience: API consumer·Use: look up the members, types and limits of a certificate object

These objects are sent with install_certificate and delete_certificate, and returned by get_installed_certificates. Default is the value the reader uses when you omit the member. The procedure is in Certificate Management.

Install

installCertPayload

The certDetails object of install_certificate.

Field	Type	Required	Default	Limits	Meaning
name	string	No			A name for the certificate entry. What an install without a name does is not specified
type	certificateType	Yes			Where the certificate is used
authenticationType	authenticationType	Yes			How the reader authenticates to the download server; required even for DIRECT
certSource	enum: HTTP, DIRECT	No			HTTP downloads each component from url; DIRECT takes it inline from certificateBundle. When omitted, the reader uses HTTP
url	array of certificateUrlEntry	No			Download URL for each component. Required, and not empty, when certSource is HTTP
verificationType	verificationType	No			How far the reader verifies the download server's TLS certificate
certificateBundle	object (certificateBundle)	No			Inline certificate content. Required, and not empty, when certSource is DIRECT
caCertificateFileContent	string	No			Inline CA content for authenticating the download server, with certSource HTTP and authenticationType CERTIFICATE. Empty means use an installed filestore certificate
certFormat	enum: PEM, BASE64	No			PEM, or BASE64 for PEM text encoded again in base64. The contract states no default

• The device supports PEM certificates, or PEM encoded again in base64, and private keys must be PKCS1. Certificate content is limited to 4 KB.
• certSource: "HTTP" requires url; without it the reply is code 29. certSource: "DIRECT" requires certificateBundle; without it the reply is code 30.
• caCertificateFileContent applies only with certSource: "HTTP" and authenticationType: "CERTIFICATE".
• A client certificate must be installed with its key; sending one without the other returns code 36.

certificateBundle

Inline content, with certSource: "DIRECT".

Field	Type	Required	Default	Limits	Meaning
ca_cert	string	No			CA certificate content
client_key	string	No			Client private key content, PKCS1
client_cert	string	No			Client certificate content
cert_key_password	string	No			Password for an encrypted client key

certificateUrlEntry

One entry of url, with certSource: "HTTP".

Field	Type	Required	Default	Limits	Meaning
key	certificateComponentKey	No			The certificate component: ca_cert, client_cert, client_key or cert_key_password
value	string	No			The component's download URL; for cert_key_password, the key password itself

Delete

delCertPayload

The certificateInfo object of delete_certificate.

Field	Type	Required	Default	Limits	Meaning
name	string	No			The certificate to delete. When omitted, every certificate of the type is deleted. Whether it matches the install name or a component name is not settled
type	certificateType	Yes			The type of certificate to delete

• Without name, the reader deletes every installed certificate of the given type.
• A certificate installed without a type cannot be deleted. Code 21 means no certificate matched.

Read-Back

installedCerts

The installedCerts object of the get_installed_certificates reply.

Field	Type	Required	Default	Limits	Meaning
certInfo	array of certInfoEntry	No			One entry per installed certificate

certInfoEntry

Field	Type	Required	Default	Limits	Meaning
name	string	No			The certificate's name. The contract's examples carry component names such as ca_cert
type	certificateType	Yes			Where the certificate is used
installTime	string	No			When the certificate was installed. The contract's example omits it
issuerName	string	Yes			The issuer's common name
publicKeyAlg	enum: RSA, RSAMD5, RSA_SHA_1, RSA_SHA_256, RSA_SHA_384, RSA_SHA_512	No			The public-key algorithm
publicKey	string	No			Declared as the public key; every published example carries an algorithm name instead
serial	string	No			The certificate's serial number
subjectName	string	Yes			The subject's name
validFrom	string	Yes			Start of the validity period
validTill	string	Yes			End of the validity period

References

certificateRef

One entry of the certificate list of an Enterprise Wi-Fi profile, sent with set_wifi. An endpoint names its certificates in securityParams; see MQTT Endpoints.

Field	Type	Required	Default	Limits	Meaning
key	certificateComponentKey	No			The certificate component: ca_cert, client_cert, client_key or cert_key_password
value	string	No			The installed certificate's name; for cert_key_password, the key password

The contract does not settle how the names in certificateRef, securityParams and delCertPayload relate to the name sent at install.

Related: 📕 install_certificate · 📕 get_installed_certificates · 📕 delete_certificate · 📕 Enumerations · 📕 Certificate Management