Keys and certificates
Many different keys and certificates are used by all of Fobnail's components. Most of them are automatically generated, but some must be provided by user.
List of keys and certificates used
Refer to architecture doc for description of actors and phases listed below. List items have the following format:
- Name of key or certificate
- Phase during which it is obtained, received or used
- Other details, if any
Note that this list includes possible usages that may not be implemented yet.
Platform Owner
Knows in advance
- Platform Owner key (signing and encryption)
- Fobnail and remote platform provisioning
- used for TLS and for signing certificates
- Platform Owner certificate
- Fobnail and remote platform provisioning
- has to be able to provide whole CA chain
- both Fobnail Token and Platform must trust root CA in this chain
- root CA certificate for EK certificate chain
- remote platform provisioning
Receives
- Fobnail Identity key
- Fobnail provisioning
- Fobnail Encryption key
- Fobnail provisioning
- EK certificate
- remote platform provisioning
- AIK
- remote platform provisioning
Produces
- Fobnail Identity certificate
- Fobnail provisioning
- Fobnail Encryption certificate
- Fobnail provisioning
- AIK certificate
- remote platform provisioning
- simple signature instead of certificate may be sufficient
Fobnail Token
Knows in advance
- root CA certificate for EK certificate chain
- local platform provisioning
- root CA for Platform Owner certificate chain
- Fobnail provisioning
Receives
- Platform Owner certificate chain
- Fobnail provisioning
- saved in flash, used in local platform provisioning and attestation
- Fobnail Identity certificate
- Fobnail provisioning
- signed by Platform Owner
- Fobnail Encryption certificate
- Fobnail provisioning
- signed by Platform Owner
- EK certificate
- local platform provisioning
- AIK
- local platform provisioning
- remote platform provisioning - signed by Platform Owner
- stored in flash and used during attestation
Produces
- Fobnail Identity key (signing and encryption)
- Fobnail provisioning
- key and certificate signed by Platform Owner is stored for later use
- Fobnail Encryption key (encryption)
- Fobnail provisioning
Platform
Knows in advance
- root CA for Platform Owner certificate chain
- remote platform provisioning
- local platform provisioning and attestation - Fobnail Identity key is signed by Platform Owner, so Platform needs a way of verifying trust chain
- Endorsement Key (encryption)
- remote and local platform provisioning
- for this project may be considered immutable persistent key unique to TPM
- EK certificate
- EK is unique so is its certificate
- usually saved in TPM NVRAM
- signed by TPM manufacturer CA
Receives
- Platform Owner certificate chain
- remote platform provisioning - directly from Platform Owner
- local platform provisioning and attestation - from Fobnail Token
- used for identification, TLS and verifying Fobnail Identity certificate
- Fobnail Identity certificate
- local platform provisioning and attestation
- used for identification and TLS
Produces
- Attester Identity Key (signing)
- local and remote platform provisioning
- created by TPM
- trusted based on Make/ActivateCredential and pairing with EK instead of certificate
Platform Owner certificate chain
Platform Owner certificate is used during Fobnail provisioning. Its root CA certificate must be preinstalled on Fobnail Token. Due to limited hardware capabilities of Fobnail Token, following restrictions apply.
Validity checks
Informational checks
-
Maximum certificate chain length
Maximal supported certificate chain consists of 3 CA certificates: root CA (flashed to Fobnail's memory), intermediate CA and final CA that is used to issue certificates for keys generated by Fobnail. Intermediate CA is optional, root and issuing CA aren't. During Fobnail provisioning, Platform Owner generates one additional certificate for Token, but this final certificate doesn't allow for use as a CA.
This limit comes from hardware limitations (in terms of available memory) aggravated by chosen library (Trussed) and its limitations.
-
File format
Certificates are concatenated to a single PEM file. Order of concatenation matters, certificates must be written starting with leaf certificate and moving through intermediate towards root CA certificate. All of them must be present, despite the fact that root CA is already known by Fobnail.
-
Certificate extensions
Trust chain will be traversed based on
X509v3 Authority Key Identifier
extension which is compared againstX509v3 Subject Key Identifier
, so both of them must be included in every certificate (former should be skipped for root CA).X509v3 Basic Constraints
is required for CA certificates.X509v3 Key Usage
must specify that all certificates in Platform Owner chain are able to sign certificates.
Temporal checks
- Validity period
Reference Fobnail Token (nRF52840 dongle) has no timekeeping capabilities. Because of that, validity period cannot be tested without adding another party that Fobnail Token trusts, or by using another dongle for Fobnail Token.
- Certificate revocation
Fobnail Token doesn't have trusted network connection, so it can't access recent (i.e. one that happened after last firmware update) certificate revocation list at run time. Revocations can only be applied during flashing/update, which should be done by Platform Owner. During that process, attempt to use revoked certificates should result in failed provisioning.
Creating Platform Owner certificate chain with OpenSSL
This section describes how to create a certificate chain that conforms to restrictions mentioned earlier. This is just a minimal example showing all required configuration options and commands used in the process, fields listed here may be extended or modified, but should not be removed.
Note that root CA doesn't have to be under Platform Owner's control, but it must issue a certificate that is (either directly or through intermediate issuer). In such cases the issuer may use other form of certificate request or additional mechanisms of proving the identity of the requester than those used by OpenSSL.
Root CA
Root CA certificate is self-signed. This means that signed public and signing
private keys belong to the same pair, and no exchange of data between separate
entities happens. -x509
parameter tells that this is the case and a self-
signed certificate is to be made, instead of CSR (Certificate Signing Request).
Command:
openssl req -newkey rsa:2048 -nodes -keyout $ROOT_PRIV -x509 -days 365 \
-out $ROOT_CERT -config $ROOT_CONFIG
ROOT_PRIV
(out) - newly created private root CA key. Keep it safe.ROOT_CERT
(out) - root CA certificate. This will be hardcoded and marked as trusted by Fobnail Token and Attester.ROOT_CONFIG
(in) - configuration file, e.g.:
[ req ]
distinguished_name = req_distinguished_name
prompt = no
x509_extensions = v3_ext
[ req_distinguished_name ]
C = PL
O = Fobnail
ST = State
CN = Platform Owner root CA certificate
[v3_ext]
basicConstraints = critical, CA:TRUE, pathlen:3
keyUsage = critical, keyCertSign, cRLSign
subjectKeyIdentifier = hash
authorityKeyIdentifier = keyid:always
Intermediate/issuing CA
These certificates aren't self-signed. Creation of such certificates consists of two steps: first one is generating a CSR (Certificate Signing Request) and is done by key creator, second one is creating the certificate itself - this is done by the parent CA. This separation is done to keep private keys secret at all times.
Generating CSR
This is similar to creating root CA with two small but important differences:
-x509
flag is not used in the command linex509_extensions
are not present (those are added by the issuer)
Command:
openssl req -newkey rsa:2048 -nodes -keyout $CA_PRIV -out $CA_CSR \
-config $CA_CONFIG
CA_PRIV
(out) - newly created private intermediate/issuer CA key. Keep it safe.CA_CSR
(out) - intermediate/issuer CA certificate signing request. This file is signed with private intermediate/issuer CA key and sent to higher level CA.CA_CONFIG
(in) - configuration file, e.g.:
[ req ]
distinguished_name = req_distinguished_name
prompt = no
[ req_distinguished_name ]
C = PL
O = Fobnail
ST = State
CN = Platform Owner issuer CA certificate
Generating certificate
Before issuing a certificate, issuer must check if subject is authorized to ask for it. It can't just blindly provide a new certificate to anyone that asks for it, because by creating a signed certificate CA tells others that it trusts its subject. Trust decision can be based on fields of CSR, challenge password, secure and non-public way of conveying CSR to issuer, or other means. This is especially important in this case because subject of each signed certificate is itself a CA and can create certificates for other entities.
Certificate revocation for Fobnail can't be done by means other than firmware updates, so issuing a certificate to untrustworthy subject impacts not only the security of devices provisioned by issuer, but also every device with the same root CA.
openssl ca
can also be used for this purpose, butopenssl x509
is easier to use for single use. On the other hand,openssl ca
better suits the needs of CA after configuration and may do more checks in semi-automatic process thanopenssl x509
.
Command:
openssl x509 -req -in $SUBJECT_CSR -CA $AUTHORITY_CERT -CAkey $AUTHORITY_PRIV \
-CAcreateserial -days 365 -extfile $SUBJECT_EXT -out $SUBJECT_CERT
SUBJECT_CSR
(in) - sent by lower-level CA.AUTHORITY_CERT
andAUTHORITY_PRIV
(in) - those were created by issuer CA earlier.SUBJECT_CERT
(out) - certificate signed withAUTHORITY_PRIV
.SUBJECT_EXT
(in) - file describing certificate extensions, e.g.:
# pathlen = 2 for intermediate, 1 for issuer certificate
basicConstraints = critical, CA:TRUE, pathlen:2
keyUsage = critical, keyCertSign, cRLSign
subjectKeyIdentifier = hash
authorityKeyIdentifier = keyid:always