Site Tools


Starting in IoTivity 1.3, X.509 certificates can be used both for asserting subject UUIDs (identities) and roles. Roles can be used as a grouping mechanism, to specify policy based on possession of a role, instead of provisioning access control for each individual identity.

Certificates will typically be issued to a device when it is newly onboarded, although certificates can be issued at any time. All certificates in IoTivity must use public keys from the NIST secp256r1 elliptic curve, and signatures must be provided using ECDSA with SHA256. All certificates must be X.509 version 3. End-entity identity certificates must contain the Extended Key Usage (EKU), and role certificates must contain the EKU Using the same certificate for both an identity and to assert a role, while possible to construct, is not supported in IoTivity. Separate certificates must be used. Certificates must not have the “anyExtendedKeyUsage” EKU ( It is recommended that Certificate Authorities also have the identity and role certificate EKUs in their certificates to constrain them against issuing certificates for any non-OCF purposes. Certificates must also follow the rules and recommendations of RFC 5280, including the use of standard extensions like Key Usage, Basic Constraints, Subject Key Identifier, and Authority Key Identifier.

See section 9.3.2 of the OCF 1.0 Security Specification for full details on the certificate format.

In OCF, a role is a 2-tuple of the form (authority, roleId), where authority and roleId are each arbitrary strings. The roleId field is required, and the authority field is optional. Roles only match if both the authority and roleId are equal, which includes whether or not the authority field is present. Therefore, a role encoded as (A, X) and a second role encoded as (B, X) are not the same role. Similarly, a role encoded as (A, X) also does not match a second role encoded as (, X) where the authority field is absent.

If a certificate is to be used to assert a role and has the above role EKU, then the certificate must have a Subject Alternative Name extension of the directoryName subtype. The Common Name (CN) component of the Name encodes the roleId. The Organizational Unit (OU) component of the Name, if present, encodes the authority.

For a self-signed root certificate to be accepted by an OCF-compliant device, including IoTivity, its certificate must be stored in the device's credential resource (/oic/sec/cred) with the credusage property set to “oic.sec.cred.trustca”. Certificates will be accepted if the chain ends in a certificate installed as trusted in that way, and the certificate chain follows all the rules of chain validation as defined in RFC 5280. Additionally, leaf certificates must have an EKU; issuer certificates should but are not required to. If issuer certificates have the EKU extension, it must include the EKUs of any certificates it issues.

Certificates issued for identity assertion should be stored in the credential resource with the “oic.sec.cred.cert” certusage. Certificates for role assertion should be stored in the credential resource with the “oic.sec.cred.rolecert” credusage. IoTivity uses these credusage tags to locate certificates it should attempt to use. Role certificates are presented automatically to a remote peer after a secured session has been established.

Although it is possible for the CMS to generate the private key for a certificate and the certificate itself and provision both to a device, the best practice is to allow the device to generate its own key pair and provide the public portion to the CMS, so that the private key never leaves the device. This reduces the potential for leaking of the private key and therefore compromise of credentials belonging to the device. The CSR resource (/oic/sec/csr) was introduced in OCF 1.0 and IoTivity 1.3 to allow a device the opportunity to generate a key pair and provide a Certificate Signing Request (as defined in RFC 2986) to the CMS to aid in certificate issuance.

See section 10.3 of the OCF 1.0 security specification for full details on device authentication with certificates.

Although there is a resource for Certificate Revocation Lists (CRLs) specified in OCF, revocation checking of certificates is not part of OCF 1.0 and is therefore not implemented in IoTivity 1.3.

Sample code for provisioning certificates is available in resource/csdk/security/provisioning/sample/autoprovisioningclient.c. IoTivity also ships with a utility called “certgenerator” whose code is in resource/csdk/security/provisioning/sample/certgenerator.cpp which can generate suitable certificates from the command line.

Relevant APIs:

  • OCProvisionTrustCertChain is used to provision a trust certificate chain to a device.
  • OCGetCSRResource is used to query a device's CSR resource and retrieve the CSR.
  • OCVerifyCSRSignature is used to verify that a CSR's signature is valid for the public key presented.
  • OCProvisionCertificate is used to provision a certificate to the device.

The following helper functions are also provided to make it easier to work with certificates and CSRs:

  • OCGetUuidFromCSR retrieves the requested subject UUID provided by the device. This assumes the device provides a CSR including a subject name in the form of a UUID; if any other arbitrary name is found, this function will fail.
  • OCGetPublicKeyFromCSR retrieves the public key from the CSR.
  • OCGenerateRandomSerialNumber generates a random number suitable for use as a serial number. Recommended best practice is to always use randomly generated serial numbers, and not sequential ones. In our sample code we do not keep a record of what serial numbers have been issued, and the chances of the same random number being generated twice are quite small; however, a CMS operating in a production environment, especially if it issues large numbers of certificates, should be designed to keep track of what serial numbers have been issued, and ensure that the same serial number is not used for two different certificates.
  • OCGenerateIdentityCertificate generates a certificate used to assert an identity, taking as input many of the outputs of the functions above.
  • OCGenerateCACertificate generates a self-signed certificate used for issuing certificates.
  • OCGenerateRoleCertificate generates a certificate used to assert a role.
  • OCGenerateKeyPair generates a new public/private key pair, which is necessary when setting up a CMS's Certificate Authority.
identity_and_role_certificates.txt · Last modified: 2017/07/11 17:26 by kkane