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) 184.108.40.206.4.1.44924.1.6, and role certificates must contain the EKU 220.127.116.11.4.1.44924.1.7. 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 (18.104.22.168.0). 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.
The following helper functions are also provided to make it easier to work with certificates and CSRs: