Overview

The PKI module provides the SDK with functions to create, encode and parse, and verify X.509 certificates. Verification does not require a store implementation, since all necessary elements (like trust lists and CRLs) are passed as parameters. Since this API allows public key extraction from X.509 certificates, the implementation has a strong relationship to the key type defined by the crypto module.

Backend Architecture

The API is defined in the header file cert.h. Additional functionality is contained in the header file cert_ex.h. These header files must not be modified. The implementation of this API can vary depending on the used X.509 library. The SDK includes two implementations: based on OpenSSL or mbedTLS.

Cert Type

pki_cert is an opaque handle and points to the backend internal representation of a certificate. The calling code must not assume a specific data type behind this handle.

Functions

Certificate Conversion

A single function for converting a DER encoded certificate into the internal format is provided. The reverse conversion into DER is not available, since DER is the exchange and storage format.

Certificate Creation

The creation function already applies OPC UA specific requirements for X.509 certificates. Created certificates are returned in DER encoded format, ready for sending or storage.

Certificate Content Access

Certificate content is held by two data structures, pki_cert_info and pki_cert_identity. pki_cert_identity holds the subject information, like organization and locality. This structure is also used to define the issuer information during certificate creation. pki_cert_info holds general certificate information, like the validity period and the subject alternate name. Furthermore, a function for retrieving the public key from the certificate is part of the API as well as a function to split a concatenated certificate chain into its elements.

Certificate Verification

The certificate verification verifies a DER (this is the exchange format in which received certificates have to be encoded) encoded certificate. This verification is based on lists of trusted and untrusted certificates and their certificate revocation lists (CRLs), and a set of verification flags, which allow to influence the verification process. With these flags, it is possible to ignore certain errors, like missing CRLs or invalid validity times. The function returns a simple flag that shows whether the certificate is valid, as well as a full set of detailed errors, also showing which errors were ignored. Usually, this function is not called directly, but through the verify function of the PKI store API that applies the context of the store to the verification. The verification process consists of several checks in the following order:

Certificate Structure
Signature
Trust List Check (errors can be ignored by setting PKI_CERT_IGNORE_UNTRUSTED)
Validity Period (errors can be ignored by setting PKI_CERT_IGNORE_TIMEINVALID or PKI_CERT_IGNORE_ISSUERTIMEINVALID)
Find Revocation List (errors can be ignored by setting PKI_CERT_IGNORE_REVOCATIONUNKNOWN or PKI_CERT_IGNORE_ISSUERREVOCATIONUNKNOWN)
Revocation Check (check can be disabled by setting PKI_CERT_DISABLE_CRL_CHECK; errors may not be ignored)

If, for example, a self-signed certificate is untrusted and expired, the returned error must reflect the trust status and not the invalid time. By setting PKI_CERT_CHECK_COMPLETE_CHAIN, the full chain has to be tested and all found errors have to be returned. The tested chain has to be complete, from the tested certificate (leaf) to the root certificate. The certificate is regarded as trusted if at least one certificate in the chain is in the trust folder. This certificate must not be necessarily the root certificate. Missing certificate revocation lists are ignored if the tested certificate is a root (self-signed) certificate.

Table of Contents