Setup of C-ITS Security PKI

Note

Technical standards: ETSI TS 102 941 v1.3.1, v1.2.1 & ETSI TS 103 097 v1.3.1

Tip

The templates for certificates, certificate requests, CTL and CRL are in the templates folder.

Generate the Root CA certificate

Prerequisite: SeaCat PKI is installed, configured and stopped.

1. Introduce a new tenant

   Add TENANT_ROOT_CA into tenants, pick the descriptive lower-case ASCII only name in etc/seacatpki.conf:

   [tenants]
   ids=TENANT_ROOT_CA
   

2. Specify a SeaCat PKI API base URL

   export ROOT_CA_URL=http://localhost:8080/TENANT_ROOT_CA
   

3. Generate the Root CA private/public key pair

   Select one of the following EC curves:

   Brainpool P-386 (brainpoolP384r1)

   openssl ecparam -name brainpoolP384r1 -genkey -noout -out root-ca-private-key.pem
   

   PKCS#11 variant:

   pkcs11-tool --module ... --login --keypairgen --id 10001 --key-type EC:brainpoolP384r1
   

   Brainpool P-256 (brainpoolP256r1)

   openssl ecparam -name brainpoolP256r1 -genkey -noout -out root-ca-private-key.pem
   

   NIST P-256 (prime256v1, secp256r1)

   openssl ecparam -name prime256v1 -genkey -noout -out root-ca-private-key.pem
   

   Note: You can share the same private key among various versions of C-ITS or even X.509.

4. Add a new private key into the configuration file

   in etc/seacatpki.conf:

   [seacatpki:private_key:TENANT_ROOT_CA_KEY_NAME]
   keyfile=${THIS_DIR}/root-ca-private-key.pem
   tenants=TENANT_ROOT_CA
   

5. Start SeaCat PKI

6. Create self-signed Root CA certificate

   Use the template rootca.json and adjust if needed.

   curl -X PUT "${ROOT_CA_URL}/cits/rca/self-signed?ca_private_key=TENANT_ROOT_CA_KEY_NAME" \
   --header 'Content-Type: application/json' \
   -d @templates/rootca.json
   

   Note the value of pbid attribute from the response, it is a public object ID of a new certificate.

7. Introduce a new tenant for a trust domain

   Note: Trust domain steps could be skipped, if trust domain exists

   Add TENANT_TRUST_DOMAIN into tenants, pick the descriptive lower-case ASCII only name in etc/seacatpki.conf:

   [tenants]
   ids=TENANT_ROOT_CA TENANT_TRUST_DOMAIN
   

8. Setup a trust domain

   in etc/seacatpki.conf:

   EU ECTL TLM L0 trust domain:

   [seacatpki:cits:trust:TENANT_TRUST_DOMAIN]
   tlm_certificate=https://cpoc.jrc.ec.europa.eu/L0/gettlmcertificate/
   

   Example of the empty trust domain:

   [seacatpki:cits:trust:TENANT_TRUST_DOMAIN]
   ; This is empty trust domain
   

9. Configure a new Root CA in SeaCat PKI configuration file

   in etc/seacatpki.conf:

   [seacatpki:cits:ca:TENANT_ROOT_CA]
   certificate=<pbid>
   trust_domain=<TENANT_TRUST_DOMAIN>
   

   Specify the pbid of the newly generated Root CA Certificate from a step above.

10. Restart a SeaCat PKI

11. Create Root CA Certificate Trust List (CTL)

    Use the initial CTL template rootca-ctl-init.json and copy that into templates/rootca-ctl.json.

    IMPORTANT: Adjust the URL of the Root CA DC in the file.

    curl -X PUT --url "${ROOT_CA_URL}/cits/rca/ctl" \
    --header 'Content-Type: application/json' \
    -d @templates/rootca-ctl-init.json.json
    

12. Create Root CA Certificate Revocation List (CRL)

    Use the empty initial CRL template rootca-crl-init.json and copy that into templates/rootca-crl.json.

    curl -X PUT --url "${ROOT_CA_URL}/cits/rca/crl" \
    --header 'Content-Type: application/json' \
    -d @templates/rootca-crl-init.json
    

13. Root CA is now configured and available for use.

Generate Enrolment Authority (EA) certificate

1. Introduce a new tenant

   in etc/seacatpki.conf:

   [tenants]
   ids=TENANT_SUBCA
   

   Note: You may reuse existing tenant, e.g. with Root CA. It is not possible to operate more EAs in the single tenant.

2. Specify a SeaCat PKI API base URLs

   export ROOT_CA_URL=http://localhost:8080/TENANT_ROOT_CA
   export EA_URL=http://localhost:8080/TENANT_SUBCA
   

3. Generate Enrolment Authority verification private key

   Choose one of following ECs:

   Brainpool P-386 (brainpoolP384r1)

   openssl ecparam -name brainpoolP384r1 -genkey -noout -out ea-verification-private-key.pem
   

   Brainpool P-256 (brainpoolP256r1)

   openssl ecparam -name brainpoolP256r1 -genkey -noout -out ea-verification-private-key.pem
   

   NIST P-256 (prime256v1, secp256r1)

   openssl ecparam -name prime256v1 -genkey -noout -out ea-verification-private-key.pem
   

4. Generate Enrolment Authority encryption private key

   Choose one of following ECs:

   Brainpool P-256 (brainpoolP256r1)

   openssl ecparam -name brainpoolP256r1 -genkey -noout -out ea-encryption-private-key.pem
   

   NIST P-256 (prime256v1, secp256r1)

   openssl ecparam -name prime256v1 -genkey -noout -out ea-encryption-private-key.pem
   

5. Configure keys in SeaCat PKI

   in etc/seacatpki.conf:

   [seacatpki:private_key:TENANT_SUBCA-verification-key]
   keyfile=${THIS_DIR}/ea-verification-private-key.pem
   tenants=TENANT_SUBCA
   
   [seacatpki:private_key:TENANT_SUBCA-encryption-key]
   keyfile=${THIS_DIR}/ea-encryption-private-key.pem
   tenants=TENANT_SUBCA
   

6. Restart a SeaCat PKI

7. Generate a EA CA Certificate Request.

   Use the template ea-cacr.json and adjust. Fill values of verification_key (TENANT_SUBCA-verification-key) and encryption_key (TENANT_SUBCA-encryption-key.

   curl -X PUT ${EA_URL}/cits/ea/ca-certificate-request \
   --header 'Content-Type: application/json' \
   -d @templates/ea-cacr.json
   

   Note the value of pbid attribute from the response, it is a public object ID of a CA certificate request.

8. Download CA Certificate Request from EA

   curl -o ea-cacr.coer ${EA_URL}/sa/<pbid>
   

   Note: If EA and Root CA shares the same tenant, download and upload steps can be skipped.

9. Upload EA CA Certificate Request to Root CA

   curl -X PUT "${ROOT_CA_URL}/sa?family=cits&type=cacr" --upload-file ea-cacr.coer
   

   Note a pbid.

10. Approve EA CA Certificate request in Root CA

    Use the template rootca-ea-cacr-approve.json and adjust. cacr, ca_certificate.

    curl -X PUT --url "${ROOT_CA_URL}/cits/rca/approve-ca-certificate-request" \
    --header 'Content-Type: application/json' \
    -d @templates/rootca-ea-cacr-approve.json
    

    Note a pbid as ea_cert_pbid, it refer to a newly created EA certificate.

11. Download certificates from Root CA

    curl -o ea-cert.coer ${ROOT_CA_URL}/sa/<ea_cert_pbid>
    curl -o rootca-cert.coer ${ROOT_CA_URL}/cits/dc/getcert/<rca_certificate_digest>
    

    The Enrolment Authority certificate is stored in ea-cert.coer file.

    Note: If EA and Root CA shares the same tenant, download and upload steps can be skipped.

12. Upload the certificates into Enrolment Authority

    curl -X PUT "${EA_URL}/sa?family=cits&type=cert" --upload-file rootca-cert.coer
    curl -X PUT "${EA_URL}/sa?family=cits&type=cert" --upload-file ea-cert.coer
    

13. Configure Enrolment Authority

    in etc/seacatpki.conf:

    [seacatpki:cits:ea:TENANT_SUBCA]
    certificate=<ea_certificate_pbid>
    encryption_key=TENANT_SUBCA-encryption-key
    verification_key=TENANT_SUBCA-verification-key
    trust_domain=<trust_domain_tenant>
    

    Use ea_cert_pbid as a reference to a EA certificate from previous steps. encryption_key and verification_key are references to respective private keys configured above.

    Fill (optionally) also a name of tenant that contains trust_domain that this EA should be part of.

14. Add EA into the Root CA CTL

    Use the template rootca-ctl.json or previous CTL template and adjust.

    curl -X PUT --url "${ROOT_CA_URL}/cits/rca/create-certificate-trust-list" \
    --header 'Content-Type: application/json' \
    -d @templates/rootca-ctl.json
    

    Snipplet of what to add on CTL:

    ...
    { "add": { "ea": {
        "eaCertificate": "79C2F0762BC405D9",
        "aaAccessPoint": "http://pki.seacat.io/etsi-plugtest-bp-ea/cits/ea/authorization-validation",
        "itsAccessPoint": "http://pki.seacat.io/etsi-plugtest-bp-ea/cits/ea/enrolment"
    } } }
    ...
    

15. Restart a SeaCat PKI

Generate Authorization Authority (AA) certificate

1. Introduce a new tenant

   in etc/seacatpki.conf:

   [tenants]
   ids=TENANT_SUBCA
   

2. Specify a SeaCat PKI API base URLs

   export ROOT_CA_URL=http://localhost:8080/TENANT_ROOT_CA
   export AA_URL=http://localhost:8080/TENANT_SUBCA
   

3. Generate Authorization Authority verification private key

   Choose one of following ECs:

   Brainpool P-386 (brainpoolP384r1)

   openssl ecparam -name brainpoolP384r1 -genkey -noout -out aa-verification-private-key.pem
   

   Brainpool P-256 (brainpoolP256r1)

   openssl ecparam -name brainpoolP256r1 -genkey -noout -out aa-verification-private-key.pem
   

   NIST P-256 (prime256v1, secp256r1)

   openssl ecparam -name prime256v1 -genkey -noout -out aa-verification-private-key.pem
   

4. Generate Authorization Authority encryption private key

   Choose one of following ECs:

   Brainpool P-256 (brainpoolP256r1)

   openssl ecparam -name brainpoolP256r1 -genkey -noout -out aa-encryption-private-key.pem
   

   NIST P-256 (prime256v1, secp256r1)

   openssl ecparam -name prime256v1 -genkey -noout -out aa-encryption-private-key.pem
   

5. Configure keys in SeaCat PKI

   in etc/seacatpki.conf:

   [seacatpki:private_key:TENANT_SUBCA-verification-key]
   keyfile=./etc/aa-verification-private-key.pem
   tenants=TENANT_SUBCA
   
   [seacatpki:private_key:TENANT_SUBCA-encryption-key]
   keyfile=./etc/aa-encryption-private-key.pem
   tenants=TENANT_SUBCA
   

6. Restart a SeaCat PKI

7. Generate a AA CA Certificate Request.

   Use the template aa-cacr.json and adjust.

   curl -X PUT ${AA_URL}/cits/aa/ca-certificate-request \
   --header 'Content-Type: application/json' \
   -d @templates/aa-cacr.json
   

   Response

   {
       "result": "OK",
       "pbid": "etsi-plugtest-nist-aa2:d09833dafcdb1b7d44614b28500a2ee2eb50c94a918155023b68b65bd1862bb8",
       "fingerprint": "d09833dafcdb1b7d44614b28500a2ee2eb50c94a918155023b68b65bd1862bb8"
   }
   

8. Download CA Certificate Request from AA

   curl -o aa-cacr.coer ${AA_URL}/sa/<pbid>
   

   This stores AA CA Certificate Request in aa-cacr.coer file.

   Note: If AA and Root CA shares the same tenant, download and upload steps can be skipped.

9. Upload CA Certificate Request to Root CA

   curl -X PUT "${ROOT_CA_URL}/sa?family=cits&type=cacr" --upload-file aa-cacr.coer
   

   Response:

   {
       "result": "OK",
       "pbid": "etsi-plugtest-nist-rca:d09833dafcdb1b7d44614b28500a2ee2eb50c94a918155023b68b65bd1862bb8"
   }
   

   Note a pbid as cacr_pbid.

10. Approve AA CA Certificate request at Root CA

    Use the template rootca-aa-cacr-approve.json and adjust.

    curl -X PUT "${ROOT_CA_URL}/cits/rca/approve-ca-certificate-request" \
    --header 'Content-Type: application/json' \
    -d @templates/rootca-aa-cacr-approve.json
    

    Result:

    {
        "result": "OK",
        "pbid": "etsi-plugtest-nist-rca:C7C6182511C8716C"
    }
    

    Note a pbid as aa_certificate_pbid, it refer to a newly created AA certificate.

11. Download certificates from Root CA

    You need to download the new AA certificate (1) and the Root CA certificate (2).

    curl -o cert_aa.coer ${ROOT_CA_URL}/sa/<aa_certificate_pbid>
    curl -o cert_rca.coer ${ROOT_CA_URL}/cits/dc/getcert/<rca_certificate_digest>
    

    The Authorization Authority certificate is stored in cert_aa.coer file. The Root Certificate Authority certificate is stored in cert_rca.coer file.

    Note: If AA and Root CA shares the same tenant, download and upload steps can be skipped.

12. Upload certificates to SeaCat PKI

    curl -X PUT "${AA_URL}/sa?family=cits&type=cert" --upload-file cert_rca.coer
    curl -X PUT "${AA_URL}/sa?family=cits&type=cert" --upload-file cert_aa.coer
    

13. Configure Authorization Authority

    in etc/seacatpki.conf:

    [seacatpki:cits:aa:TENANT_SUBCA]
    certificate=<aa_certificate_pbid>
    encryption_key=TENANT_SUBCA-encryption-key
    verification_key=TENANT_SUBCA-verification-key
    trust_domain=<trust_domain_tenant>
    

    Use aa_certificate_pbid as a reference to a AA certificate from previous steps. encryption_key and verification_key are references to respective private keys configured above.

    Fill (optionally) also a name of tenant that contains trust_domain that this AA should be part of.

14. Add AA into the Root CA CTL

    Use the template rootca-ctl.json or previous CTL template and adjust.

    curl -X PUT --url "${ROOT_CA_URL}/cits/rca/create-certificate-trust-list" \
    --header 'Content-Type: application/json' \
    -d @templates/rootca-ctl.json
    

    A snipplet of that needs to be added to CTL:

    ...
    { "add": { "aa": {
        "aaCertificate": "8476936376DEE4DA",
        "accessPoint": "https://via.teskalabs.com/cits-otenv/v1.3/aa/authorization"
    } } }
    ...
    

15. Restart a SeaCat PKI

Trust List Manager Setup

Prerequisite: SeaCat PKI is installed, configured and stopped.

1. Introduce a new tenant

   in etc/seacatpki.conf:

   [tenants]
   ids=TENANT_TLM
   

2. Specify a SeaCat PKI API base URL

   export TLM_URL=http://localhost:8080/TENANT_TLM
   

3. Generate the TLM private/public key pair

   Select one of the following EC curves:

   Brainpool P-386 (brainpoolP384r1)

   openssl ecparam -name brainpoolP384r1 -genkey -noout -out tlm-private-key.pem
   

   Brainpool P-256 (brainpoolP256r1)

   openssl ecparam -name brainpoolP256r1 -genkey -noout -out tlm-private-key.pem
   

   NIST P-256 (prime256v1, secp256r1)

   openssl ecparam -name prime256v1 -genkey -noout -out tlm-private-key.pem
   

4. Add a new private key into the configuration file

   in etc/seacatpki.conf:

   [seacatpki:private_key:TENANT_TLM]
   keyfile=${THIS_DIR}/tlm-private-key.pem
   tenants=TENANT_TLM
   

5. Start SeaCat PKI

6. Create self-signed TLM certificate

   Use the template tlm.json and adjust if needed.

   curl -X PUT "${TLM_URL}/cits/tlm/self-signed?tlm_private_key=TENANT_TLM" \
   --header 'Content-Type: application/json' \
   -d @templates/tlm.json
   

   Note the value of pbid attribute from the response, it is a public object ID of a new certificate.

7. Configure a new TLM in SeaCat PKI configuration file

   in etc/seacatpki.conf:

   [seacatpki:cits:tlm:TENANT_TLM]
   certificate=<pbid>
   

   Specify the pbid of the newly generated Root CA Certificate from a step above.

8. Restart a SeaCat PKI

9. Create TLM Certificate Trust List

   Use the initial CTL template tlm-ctl-init.json.

   IMPORTANT: Adjust the URL of the TLM in the file.

   curl -X PUT --url "${TLM_URL}/cits/tlm/ectl" \
   --header 'Content-Type: application/json' \
   -d @templates/tlm-ctl-init.json
   

10. TLM is now configured and available for use.

Extending a trust domain with local configurations

You may need to manually extend the trust domain locally by Root CAs, EAs and/or AAs.

Eg. a trust domain of AA can be extended locally to reach EA when TLM is not present or is not yet updated.

Adding a local Root CA

[seacatpki:cits:trust:foobar]
...
local_rca:
    https://via.teskalabs.com/cits-otenv/v1.3/dc/getcert/D817CE980CF1FEC7
    https://via.teskalabs.com/cits-otenv/v1.3/dc

local_rca: the local EA config value has to start with local_rea, e.g. local_rca1 will work as well, which is the way how you can specify more than one locally added Root CAs.

The first line is an URI of the Root CA Certificate. Possible values are HTTP or HTTPS URL, file:// and an absolute file system path. PKI will download the certificate and store that in the trust domain database.

The second line is an URL of the Root CA Distribution Centre (DC), it is optional.

Adding a local EA

[seacatpki:cits:trust:foobar]
...
local_ea:
    https://via.teskalabs.com/cits-otenv/v1.3/dc/getcert/D817CE980CF1FEC7
    https://via.teskalabs.com/cits-otenv/v1.3/ea/authorization-validation
    https://via.teskalabs.com/cits-otenv/v1.3/ea/enrolment

local_ea: the local EA config value has to start with local_ea, e.g. local_ea1 will work as well, which is the way how you can specify more than one locally added EA.

The first line is an URI of the EA Certificate. Possible values are HTTP or HTTPS URL, file:// and an absolute file system path. PKI will download the certificate and store that in the trust domain database.

The second line is an URL of the EA Authorization validation endpoint (AA access point).

The third line is an URL of the EA Enrolment endpoint (ITS access point), it is optional.

Adding a local AA

[seacatpki:cits:trust:foobar]
...
local_aa:
    https://via.teskalabs.com/cits-otenv/v1.3/dc/getcert/D817CE980CF1FEC7
    https://via.teskalabs.com/cits-otenv/v1.3/aa/authorizaion

local_aa: the local AA config value has to start with local_aa, e.g. local_aa1 will work as well, which is the way how you can specify more than one locally added AA.

The first line is an URI of the AA Certificate. Possible values are HTTP or HTTPS URL, file:// and an absolute file system path. PKI will download the certificate and store that in the trust domain database.

The second line is an URL of the AA Authorization endpoint, it is optional.