General

The Public Key Infrastructure (PKI) part consists of creating Root Certificate Authorities for (Advanced) High Assurance Boot use case ((A)HAB CA) and the associated End-Entity certificates issued under those roots.

PKI profiles are provided as templates. Profiles are modified per use case. Generally the "Validity period", "Distinguished Name" are modified.

For (A)HAB CAs the naming must contain SRK{0...3} so that the correct SRK can be selected. By default, the SRK0 will be the first CA. Also the End-Entity Common names must contain IMG{0...3}, CSF{0...3} or SGK{0...3} so that the correct End-Entity is used. The Common name must be empty since it is populated from the product information.

Supported Algorithms¶

Supported Key Algorithms:

RSA
ECDSA
AES

Supported Key Sizes:

2048 & 4096 bits for RSA
ECDSAP224, ECDSAP256, ECDSAP384, ECDSAP521 for ECDSA
128 & 256 bits for AES

CAInfo fields in the product¶

Field	Usage
crlIssueInterval	A fixed interval when CRL will be issued. Duration string is a possibly signed sequence of decimal numbers, each with optional fraction and a unit suffix, such as "300ms", "1.5h" or "2h45m". Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".
crlExpiry	The validity period for generated CRL. Duration string is a possibly signed sequence of decimal numbers, each with optional fraction and a unit suffix, such as "300ms", "1.5h" or "2h45m". Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".
crlDistributionPoints	Array CRL distribution points for a CA. These will override the distribution points in the certificate profile to be issued if present.
policyIdentifiers	Array of Certificate policy identifiers. These will override the policy identifiers in the certificate profile to be issued if present.

Other fields are described in the REST API Documentation.

Certificate Profiles¶

Certificate profiles for different use cases can be created by providing a YAML template to the System. This is done as part of the configuration. Profiles can be specific for a product or shared between multiple products. The templates define the KeyUsage, validities etc. Some of the values can be overridden by the CSR.

Examples of profiles¶

See examples by use case

More examples of profile YAML files are available in the reference client package. Contact support@laavat.io for the package.

Creating a profile to the Solution¶

Adding new profiles are done in the following way:

Identify the use case. If there is an existing profile, use that in the product creation.
If the new profile is needed modify the values in the profile.
Upload the profile to the Solution. The person doing the upload must be in the groups listed for CA Write access.
No Approval is needed.
Make note of the returned profile ID.

Profile structure¶

Name¶

Name of the profile so it can be identified more easily

Name: Initial Device Certificate EndEntity Profile

DN¶

DN specifies the fields which are overwritten from the CSR. In example below the Organization and County are written to the issued certificate.

DN:
  #Organization: Test Comp
  Organization: Laavat
  #OrganizationalUnit: R&D
  #Country: FI
  Country: FI
  #Province:
  #- Something
  # Locality:
  # StreetAddress:
  # PostalCode:
  # SerialNumber
  # CommonName:

Profile Type¶

If creating a ROOT then profile 3 is selected

# EndEntity is 1, Sub CA profile 2 , Root profile 3
ProfileType: 3

Signature Algorithms¶

Must match the selected keytype

# SignatureAlgorithms
#  SHA1WithRSA = 3
#  SHA256WithRSA = 4
#  SHA384WithRSA = 5
#  SHA512WithRSA = 6
#  DSAWithSHA1 = 7
#  DSAWithSHA256 = 8
#  ECDSAWithSHA1 = 9
#  ECDSAWithSHA256 = 10
#  ECDSAWithSHA384 = 11
#  ECDSAWithSHA512 = 12
#  SHA256WithRSAPSS = 13
#  SHA384WithRSAPSS = 14
#  SHA512WithRSAPSS = 15
SignatureAlgorithm: 10

Key Algorithm¶

Must match the selected key.

# KeyAlgorithms
#   RSAAlgorithm = 1
#   ECDSAAlgorithm = 2
KeyAlgorithm: 2

Validity Period¶

Validity of the certificate in duration (max 290 years) or with absolute date in RFC3339 e.g. 9999-12-31T23:59:59Z. Example in absolute date "9999-12-31T23:59:59Z". Example in duration "1h10m10s". Only h, m and/or s are accepted.

ValidityPeriod: 1577846300

Basic Constraints¶

Basic constraints for the certificate

BasicConstraints:
  BasicConstraintsValid: true
  IsCA: false
  ```

### Identifiers

Add Authority Key Indentifier or Subject Key identifier

```yaml
AddSKI: true
AddAKI: true

Key Usages¶

Selects the needed Key Usages

# KeyUsages
#  KeyUsageDigitalSignature = 1
#  KeyUsageContentCommitment = 2
#  KeyUsageKeyEncipherment = 4
#  KeyUsageDataEncipherment = 8
#  KeyUsageKeyAgreement = 16
#  KeyUsageCertSign = 32 
#  KeyUsageCRLSign = 64
#  KeyUsageEncipherOnly = 128
#  KeyUsageDecipherOnly = 256
KeyUsage:
  - 1
  - 16

Extended Key Usage¶

Select the extended key usages

ExtendedKeyUsage:
  # ExtendedKeyUsages
  #  ExtKeyUsageAny = 0
  #  ExtKeyUsageServerAuth = 1
  #  ExtKeyUsageClientAuth = 2
  #  ExtKeyUsageCodeSigning = 3
  #  ExtKeyUsageEmailProtection = 4
  #  ExtKeyUsageIPSECEndSystem = 5
  #  ExtKeyUsageIPSECTunnel = 6
  #  ExtKeyUsageIPSECUser = 7
  #  ExtKeyUsageTimeStamping = 8
  #  ExtKeyUsageOCSPSigning = 9
  #  ExtKeyUsageMicrosoftServerGatedCrypto = 10
  #  ExtKeyUsageNetscapeServerGatedCrypto = 11
  #  ExtKeyUsageMicrosoftCommercialCodeSigning = 12
  #  ExtKeyUsageMicrosoftKernelCodeSigning = 13
  - 1
  - 2

Additional fields¶

ExtraExtensions: true
SANUsage: true
# CRLDistributionPoints. List of URI strings.
CRLDistributionPoints:
  - http://crl.company.com/e37f045c.crl

# PolicyIdentifiers. List of ASN1 policy OIDS
PolicyIdentifiers:
  - 1.10.123.432.4.5
  - 2.10.123.432.4.65

Enforcements¶

Version 1 profile¶

Values of options	Behavior
EnforceUniqueDN: false	New certificate is issued every time.
EnforceUniqueDN: true	If certificate has been issued with the same DN from the CA then that certificate is returned. If PublicKey has been used and different DN is requested in the CSR then an error is returned.

Version 2 profile¶

Values of options	Behavior
EnforceUniqueDN: false AND EnforceUniquePublicKey: false	New certificate is issued every time.
EnforceUniqueDN: true AND EnforceUniquePublicKey: false	If certificate has been issued with the same DN from the CA then that certificate is returned. Otherwise a new certificate is returned.
EnforceUniqueDN: false AND EnforceUniquePublicKey: true	If same public key has been used before from that CA an error will be returned. Otherwise a new certificate is issued.
EnforceUniqueDN: true AND EnforceUniquePublicKey: true	If certificate has been issued with the same DN from the CA with the same public key then that found certificate is returned. If public key and DN are new then a new certificate is issued. Otherwise an error is returned.

CDPs and PolicyIdentifiers¶

It is possible to have CA specific CDPs and PolicyIdentifiers that override the ones defined in the profiles.

Field	Usage
crlDistributionPoints	Array CRL distribution points for a CA. These will override the distribution points in the certificate profile to be issued if present.
policyIdentifiers	Array of Certificate policy identifiers. These will override the policy identifiers in the certificate profile to be issued if present.

Example usage with reference client package: add profiles¶

These profiles will be usable by CA trees defined in products. Profile types are ROOT, SUB and END, for Root CA, Intermediate/Sub-CA and End-Entity/Leaf-certificate respectively.

Add a root profile:

(venv) $ ./signing-tool.py -c -t $TOKEN -a https://app.laavat.io/<CustomerName>/api/v1 profile add \
    -N TESTING -T ROOT -F nxp-imx6-habv4-rootca-rsa-4096-SHA256-profile.yaml 
{
    "id": "76de3349-3707-4744-b7d0-93ae7ea349c0",
    "profile_name": "TESTING",
    "profile_type": 3,
    "profile_yaml": "<Redacted for readability>"
}
Profile added. Profile ID: 76de3349-3707-4744-b7d0-93ae7ea349c0

Add a Sub-CA profile:

(venv) $ ./signing-tool.py -c -t $TOKEN -a https://app.laavat.io/<CustomerName>/api/v1 profile add \
    -N TESTINGSUB -T SUB -F nxp-imx6-habv4-subca-rsa-4096-SHA256-profile.yaml 
{
    "id": "f8118cc1-9afd-490f-8783-b2104bf3cb87",
    "profile_name": "TESTINGSUB",
    "profile_type": 2,
    "profile_yaml": "<Redacted for readability>"
}
Profile added. Profile ID: f8118cc1-9afd-490f-8783-b2104bf3cb87

Add an End-Entity profile:

(venv) $ ./signing-tool.py -c -t $TOKEN -a https://app.laavat.io/<CustomerName>/api/v1 profile add \
    -N TESTINGEND -T END -F nxp-imx6-habv4-endentity-rsa-4096-SHA256-profile.yaml 
{
    "id": "60b3ff9e-27f9-403c-b125-e018080a6366",
    "profile_name": "TESTINGEND",
    "profile_type": 1,
    "profile_yaml": "<Redacted for readability>"
}
Profile added. Profile ID: 60b3ff9e-27f9-403c-b125-e018080a6366

Example usage with reference client package: modify profiles¶

After creation, profiles can be modified by updating one, several, or all fields within the data structure as required. Be aware that since profiles may be utilized across multiple products, altering the profile data could potentially cause unintended side effects in some of those products.

Modifying the root profile using reference client. ./prof.yaml has the new profile:

(venv) $ ./signing-tool.py -c -t $TOKEN -a https://app.laavat.io/<CustomerName>/api/v1 profile update \
 -F ./prof.yaml -I 76de3349-3707-4744-b7d0-93ae7ea349c0
Profile updated