Skip to main content
Skip table of contents

Configure EJBCA for Microchip TrustFLEX and TrustCUSTOM

This outlines how to set up EJBCA to issue X.509 certificates that conform to Atmel/Microchip’s compressed certificate format. For more information on compressed certificates, refer to the Application Note Compressed Certificate Definition.

As an example, this guide explains the steps required to generate Microchip-compliant certificates for Microchip's TrustFLEX and TrustCUSTOM personalization service:

  • Create Crypto Tokens
  • Create Custom Certificate Extensions
  • Create Root CA
  • Create Sub CA
  • Create End Entity
  • Generate a Microchip-compliant certificate

PKI Structure

The objective of the setup is to enable attaching the Microchip factory signer certificates to your wider public key infrastructure (PKI), while not changing the way Microchip issues device certificates and programs them into your secure elements.



The example shows the EJBCA setup with a self-signed Root CA and a Sub CE (SubCA_Microchip) issuing the Microchip Factory signer certificate. The signer certificate will in turn produce the high number of device certificates that Microchip injects into the secure elements to be shipped to your assembly line.

Microchip TrustFLEX and TrustCUSTOM Requirements

Due to the way the certificates are stored/retrieved from the ECC608 device, using Custom certificates will require some knowledge of compressed certificates and certificate templates.

The following requirements need to be taken into account when configuring the SubCA_Microchip and the format for the signer certificate it will produce in EJBCA.

Notes on the Custom Signer Certificate from the Microchip Technology application note documenting the compressed certificate format Compressed Certificate Definition:

  • The issue date only has a resolution of hours. Minutes and seconds are assumed to be zero. Refer to the Compressed Certificate Definition for further details on the compressed certificates.
  • Validity time resolution is only in years. Ie. it is not possible to issue a cert for 6 months only.
  • The custom definition files (.c, .h) being generated assume the length of Organization and Common Names matches with Microchip standard certificates.
  • The Distinguished Names, both for the Issuer and for the Subject in all certificates must be comprised of an Organization Name and a Common Name entry, in that order
  • The Organization Name entered here gets padded and spaces replaced with '_' to match Microchip standard certificate sizes.
  • The Subject Common Name in the Signer certificate resp. the Issuer Common Name in the Device certificate gets padded and spaces replaced with '_' to match Microchip standard certificate sizes.
  • The Signer certificates must contain exactly the following extensions in the same exact order:
    • Key Usage, critical: Digital Signature, Certificate Sign, CRL Sign
    • Basic Constraints, critical: CA: TRUE, PATHLEN: 0
    • Subject Key Identifier
    • Authority Key Identifier
  • The serial number is generated from a hash of the subject public key and encoded dates from the compressed certificate:

    • SHA256(subject public key \[64 bytes\] + encoded dates \[3 bytes\])
    • Two uppermost significant bits are set to 01.

Prerequisites

Before you begin, you need the following:

  • EJBCA Enterprise 8.0 or later

Configure EJBCA

The following sections cover the steps needed to configure EJBCA.

Step 1 - Create Crypto Tokens

Create tokens for the various certificates and label them explicitly.

In EJBCA, cryptographic keys are stored in a crypto token. For more information on crypto tokens and available fields, see the Crypto Tokens Overview. To learn how to create crypto tokens in EJBCA, you can follow the tutorial Create a PKI Hierarchy in EJBCA.

Step 2 - Create Custom Certificate Extensions

EJBCA orders certificate extensions by following its own logic which doesn't comply with Microchip's constraints. In order to comply with Microchip's specific extension ordering, the trick is to use Custom Certificate Extensions instead. These custom extensions will be added following the alphabetic order of the extension name. By naming them adequately, it will be possible to order them the way we want.

Customized extensions are added in the EJBCA System Configuration page and once added, extensions can then be selected for the certificate profile when creating the certificate profile. For more information on EJBCA Custom Certificate Extensions, see Custom Certificate Extensions.

Follow the steps below to create three custom certificate extensions in the EJBCA System Configuration:

  1. In EJBCA, click System Configuration and select the Custom Certificate Extensions tab.
  2. To add a Basic Constraints extension, specify the following:
    • Object Identifier (OID): "2.5.29.19".
    • Label: "Basic Constraints".
    • Click Add.
    • Click Edit on the added object and specify the following:
    • Encoding: Select the encoding DEROBJECT.
    • Critical: Select to mark the extension as critical in the certificate.
    • Click Save.
  3. To add an Authority Key Identifier extension, specify the following:
    • Object Identifier (OID): "2.5.29.35".
    • Label: "X Authority Key Identifier". (warning) Label the Authority Key Identifier with an X as the first character so that it will be ordered in the third position.
    • Click Add.
  4. To add a Subject Key Identifier extension, specify the following:
    • Object Identifier (OID): "2.5.29.14".
    • Label: "Subject Key Identifier".
    • Click Add.

The following certificate extensions are added and listed:


Step 3 - Create Root CA

Next, create a Root CA in EJBCA. To learn how to set up a Root CA in EJBCA, you can follow the tutorial Create your first Root CA using EJBCA.

To complete the steps in this guide for configuring EJBCA for Microchip TrustFLEX and TrustCUSTOM, it is mandatory to select the following:

  • Type: Root CA.
  • Available Key Algorithms: ECDSA.
  • Available ECDSA curves: P-256 / prime256v1 / secp256r1.
  • Signature Algorithm: SHA256withECDSA.
  • Key Usage: Key certificate sign, at a minimum.

Step 4 - Create Sub CA

Next, create a Subordinate CA (Sub CA) in EJBCA. To learn how to set up a Sub CA in EJBCA, you can follow the steps in the tutorial Create a PKI Hierarchy in EJBCA.

The Sub CA Microchip (SubCA_Microchip) certificate will be used to sign the many certificate signing requests (CSRs) that Microchip will send you to establish the factory signer certificates. To comply with the Microchip list of requirements, it is mandatory to specify the following:

  • Type: Sub CA.
  • Available Key Algorithms: ECDSA.
  • Available ECDSA curves: P-256 / prime256v1 / secp256r1.
  • Signature Algorithm: SHA256withECDSA.

Step 5 - Create End Entity

The Signer CA certificate needs to be generated for the Microchip factory. Microchip sends the certificate signing requests (CSRs) and EJBCA then signs them with the Sub CA (SubCA_Microchip).

In EJBCA, this can be accomplished by creating an End Entity for each CSR to sign (and Signer to issue). An End Entity relies on an End Entity Profile and in order for the End Entity to issue the Signer certificate according to Microchip's requirements, a specific Certificate Profile needs to be created.

Create Certificate Profile

The certificate profile defines the constraints of new certificates, for example, what keys it can use, and what the extensions will be. For an introduction to certificate profiles, see the Certificate Profiles Overview and for information on available Certificate Profiles Fields, see Certificate Profile Fields.

To create a certificate profile, follow these steps:

  1. In EJBCA, under CA Functions, click Certificate Profiles.
  2. Click Clone next to the SUBCA template to use that as a basis for creating your new profile.
  3. Name the new certificate profile and click Create from template.
  4. To edit the profile values to fit your needs, find the newly created profile in the list and click Edit.
  5. On the Edit page, verify that the type is End Entity and update the following:
    • For Available Key Algorithms, select ECDSA to only allow elliptic curve keys.
    • For Available ECDSA curves, select P-256 / prime256v1 / secp256r1
    • For Signature Algorithm, select SHA256WithECDSA.
    • Enable Allow Validity Override.
    • Enable Allow certificate serial number override.
    • Enable Allow Subject DN Override by CSR.
    • For Key Usage, select Critical, Digital Signature, CRL Sign, Key certificate sign.
    • X.509v3 extensions, None.

    • For Other Extensions – used custom certificate extensions, select the following extensions:

      • Basic Constraints.

      • Subject Key Identifier.

      • X Authority Key Identifier.

    • For Available CAs, select your Sub CA SubCA_Microchip.

  6. Click Save to store the certificate profile.

The newly created profile is displayed in the list of certificate profiles.

Create End Entity Profile

To create an end entity profile, follow these steps:

  1. In EJBCA, under RA Functions, click End Entity Profiles.
  2. In the Add Profile field, add a name for the new profile, and click Add profile.
  3. Select the newly created profile and click Edit End Entity Profile to update the profile.
  4. Edit the profile and update the following:
    • For Username, select Auto-generated.
    • For Password (or Enrollment Code): Specify a password.
    • For CN, Common name, verify that Required and Modifiable are selected.
    • Main Certificate Data allows you to map the profile to be used together with default certificate profiles and CAs:
    • Specify Default Token options to define how the key pair generation should be implemented for the certificates:
      • For Available Tokens, select User Generated. User Generated means that the requester generates their own key pair and thus creates and provides a certificate signing request (CSR) for the certificate request to EJBCA.
    • Enable Custom certificate serial number.
    • For Certificate Validity Start Time, select Use, and minutes and seconds set to 0.
    • For Certificate Validity End Time, select Use, and specify Start_Time + n_years; same month, day, hours as the specified Certificate Validity Start Time.
  5. Click Save to store the end entity profile.

The newly created profile is displayed in the list.

Create End Entity

Next, a new end entity can be created based on the end entity profile.

To learn how to add end entities in EJBCA, you can follow the steps in the Tutorial - Issue Matter IoT-compliant certificates with EJBCA.

To create an end entity, follow these steps:

  1. In EJBCA, under RA Functions, click Add End Entity and specify the following:
    • In End Entity Profile, verify that the profile created in Create End Entity Profile is selected and update other settings as required.
  2. To add the end entity, click Add.

The end entity is added.

Step 6 - Generate a Microchip-compliant certificate

The Microchip CSR can now be signed and the resulting Signer certificates downloaded in DER format and uploaded to Microchip TrustFLEX and TrustCUSTOM.

To issue the certificate using the EJBCA:

  1. In EJBCA, click RA Web to access the EJBCA RA UI.
  2. Under Request new certificate, select Make New Request.
  3. For Certificate Type, select your certificate profile created.  
  4. For Key-pair generation, select Provided by user.
  5. Click Upload CSR to upload the CSR provided by Microchip.
  6. Download the certificate.

The resulting certificate should look similar to the following example:

Automate Issuance of Microchip Signer Certificates with Python

The following example code illustrates how to automate the issuance of the many (65 in our case) signer certificates requested by the Microchip TPDS system by using the EJBCA Client Toolbox.

In this example, the CSRs provided by Microchip are grouped into the Keyfactor_CSRs folder and the signed certificates are output into the Keyfactor_Signed folder.

PY
from cryptography import x509
from cryptography.hazmat.primitives import hashes
from cryptography.hazmat.primitives import serialization
import os


## encode cert validity dates in a 3-byte table as per Microchip's spec
def encode_date(issue_year, issue_month, issue_day, issue_hour, expire_years):
    if issue_year < 2000 or issue_year > 2031 or \
       issue_month < 1 or issue_month > 12 or \
       issue_day < 1 or issue_day > 31 or \
       issue_hour < 0 or issue_hour > 23 or \
       expire_years < 0 or expire_years > 31:
        return('error')
    else:
       s = expire_years + 32*(issue_hour + 32*(issue_day + 32*(issue_month + 16*(issue_year-2000))))
       return(bytes([int((s >> 16)& 255), int((s >> 8)& 255), int(s & 255)]))

## convert an array of bytes to a string which can be copied and pasted into an EJBCA field
def convert_bytes2str(b):
    b_str=''
    for x in list(b):
        a = '0'+hex(x)[2:]
        b_str = b_str + a[-2:]
    return(b_str)

## Calculate cert serial number after Microchip spec
def compute_sn(csr_pem, issue_year, issue_month, issue_day, issue_hour, expire_years):
    csr = x509.load_pem_x509_csr(csr_pem.read()) ## read CSR from .pem
    pub_key = csr.public_key() ## extract public key from CSR
    serialized_pk = pub_key.public_bytes(encoding=serialization.Encoding.DER, format=serialization.PublicFormat.SubjectPublicKeyInfo)
    serialized_pk = serialized_pk[-64:] ## and convert it into an array of bytes
    date = encode_date(issue_year, issue_month, issue_day, issue_hour, expire_years) ## compute the 3 bytes defining cert validity after Microchip spec
    blob = serialized_pk + date ## assemble public key and date array
    digest = hashes.Hash(hashes.SHA256()) ## Hash the blob
    digest.update(blob) ## with SHA256
    sn32 = digest.finalize() ## and retrieve the 32-byte hash
    sn16 = sn32[:16] ## keep the 16 leftmost bytes
    MSB = (sn16[0] & 0x7F) | 0x40 ## set the 2 first bits as 01 as per the Microchip spec
    sn = bytes([MSB]) + sn16[1:]
    sn_string = convert_bytes2str(sn) ## convert byte array to string
    return (sn_string)

## Create date string for EJBCA
def assemble_date(year, month, day, hour):
    y = '000' + str(year)
    y = y[-4:]
    m = '0' + str(month)
    m = m[-2:]
    d = '0' + str(day)
    d = d[-2:]
    h = '0' + str(hour)
    h = h[-2:]
    return('"' + y + '-' + m + '-' + d + ' ' + h + ':00:00+00:00' + '"')
    
## Create End-Entity
def EE_create(CLI_path, user, password, CA, EEP, CP, startdate, stopdate, serial):
    com1 = 'cd ' + CLI_path
    com2 = 'ejbcaClientToolBox.bat EjbcaWsRaCli edituser ' + user + ' ' + password + ' false "O=OEM, CN=' + user + '" NULL NULL ' + CA + ' 1 USERGENERATED NEW ' + EEP + ' ' + CP + ' ' + startdate +  ' ' + stopdate + ' "CERTIFICATESERIALNUMBER=0x' + serial + '"'
    os.system('cmd /k' + '"' + com1 + ' & ' + com2 + '"')
    return()

## Issue certificate
def Cert_create(CLI_path, user, password, csr_path, csr_file, Signed_path):
    com1 = 'cd ' + CLI_path
    com2 = 'ejbcaClientToolBox.bat EjbcaWsRaCli pkcs10req ' + user + ' ' + password + ' ' + csr_path + csr_file + ' PEM NONE ' + Signed_path
    os.system('cmd /k' + '"' + com1 + ' & ' + com2 + '"')
    return()

## CSR path and file name

password = 'KF'
csr_path = 'C:/Users/qwerty/Documents/KeyFactor_CSRs/'
Signed_path = 'C:/Users/qwerty/Documents/KeyFactor_Signed/'
CLI_path = 'C:/Users/qwerty/OneDrive - Keyfactor/Documents/EJBCA/clientToolBox/clientToolBox'
CA = 'CA_IoT_OEM_PKI_SubCA_Microchip'
EEP = 'EEP_IoT_OEM_PKI_MicrochipFactory'
CP = 'CP_IoT_Microchip_TrustFlex'

## Cert desired validity date and expiration
issue_year = 2023
issue_month = 4
issue_day = 1
issue_hour = 8
expire_years = 10

startdate = assemble_date(issue_year, issue_month, issue_day, issue_hour)
stopdate = assemble_date(issue_year + expire_years, issue_month, issue_day, issue_hour)

## Main

for csr_file in os.listdir(csr_path):
    user = csr_file[:-4]
    print(csr_file)
    print(user)

    with open(csr_path+csr_file, 'rb') as csr_pem:
    
        serial = compute_sn(csr_pem, issue_year, issue_month, issue_day, issue_hour, expire_years)
        EE_create(CLI_path, user, password, CA, EEP, CP, startdate, stopdate, serial)
        Cert_create(CLI_path, user, password, csr_path, csr_file, Signed_path)
        

Next steps

This guide has demonstrated how you can issue X.509 certificates that conform to Atmel/Microchip’s compressed certificate format using EJBCA.

For more information about compressed certificates, refer to the Application Note Compressed Certificate Definition.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.