Managing CVC CAs

The following sections cover information on handling Card Verifiable Certificate (CVC) CAs and CVC specific operations.

For a feature overview and sections providing information on CVC CAs, see CVC CA.

Creating CVC CAs

When creating a CVC CA there are three CA Reference fields in the standard. In EJBCA, these are mapped to a DN structure to have common handling in EJBCA.

The mapping is:

  • Country = C (ISO 3166-1 2 letter country code)
  • Mnemonic = CN (ISO 8859-1 1-9 letter string)
  • Sequence = certificate serial number (ISO 8859-1 5 letter alphanumeric string)

For example, when creating a Country Verifying Certificate Authority (CVCA), select type CVC in the Create CA page and enter a Subject DN like: C=SE,CN=TESTCVCA.

The sequence should be a pure numeric sequences of 5 characters (00001, 00002, etc), or country code + numeric (SE001, SE002, etc), or country code + alphanumeric (hex) (SEA01, SEB01, SEB0F, etc).

For the CVCA, select Signed by=Self Signed and Certificate Profile=ROOTCA.

Note that EJBCA only validates that country codes consist of two characters with value A-Z to facilitate testing with mock countries.

To create a Document Verifier (DV), select Signed by=Name of CVCCA and Certificate Profile=SUBCA. For more information, see Document Verifiers (DV).

You can import a CVCA certificate from another country as an External CA using Edit Certificate Authorities > Import CA certificate. When a CA has been imported, this CA certificate can authenticate CVC requests from foreign DVs.

Using the WebService API

The EJBCA Web Service (WS) API has several methods to manage DVs and ISs.

  • createExternallySignedCa
  • caCertResponse
  • caRenewCertRequest
  • cvcRequest

The method cvcRequest is used for enrolling and renewing DVs (on a CVCA) and ISs (on a DV).

The following process applies when a CVC request is received through the WS API call:

  1. Look up if there exists a user with the specified username.
  2. If the user exists:
    1. If the user's status is revoked, the request is denied (AuthorizationDeniedException).
    2. See if the user has old certificates.
    • If there are old certificates and the request is an authenticated request (with outer signature):
      • If the request uses the same public key as the old certificate the request is denied (AuthorizationDeniedException).
      • If the old certificate can verify the request but the certificate is not valid we throw a CertificateExpiredException.
      • If the request can be verified using one of the old valid certificates the request is automatically granted, and the user status is set to new and the password set to the given password.
      • If the request cannot be verified at all, the request is denied (AuthorizationDeniedException).
    • If there are no old certificates we try to process the request as a non-authenticated request.
  3. If the user does not exist we try to process the request as a non-authenticated request.
  4. Processing the request as a non-authenticated request means that we try to authenticate using the password given, and that only works if the user status is new.

The Web Service APIs caRenewCertRequest and caCertResponse are useful when used from a SPoC in order to renew DVs for example. For more information, see Creating a DV and Managing the DV Lifecycle using WS.

Importing CVC CAs

For test purposes, you may receive a private key and a CV certificate for the CVCA trust point used by the passport manufacturer when creating specimen passports.

To test your process and inspection systems, if you have a PKCS#8 private key and a CV certificate with the public key, you can import a CVCA (with soft keystore) in EJBCA:

$ bin/ejbca.sh ca importcvca

Example import command using the given CV Certificate:

$ bin/ejbca.sh ca importcvca importcvca1 GO_CVCA_RSA2008.pkcs8 GO_CVCA_RSA2008.cvcert C=SE,CN=IMPCA1

Example import command using the same private/public keys, but generating a new certificate:

$ bin/ejbca.sh ca importcvca importcvca1 GO_CVCA_RSA2008.pkcs8 GO_CVCA_RSA2008.cvcert C=SE,CN=IMPCA1 SHA1WithRSA 365

Creating Document Verifiers (DVs) 

Creating domestic Document Verifiers (DVs) is as straightforward as creating a SubCA to your CVCA, using a SubCA certificate profile.

You can sign foreign DVs by treating them as regular End Entities and create an end entity and choose SubCA certificate profiles when adding the end entity. You can then process the certificate requests received by the foreign DV as a regular end entity certificate request:

  • Using the Public Web GUI
  • Using the WS CLI clientToolBox CvcWsRaCli
  • Using the WS-API cvcRequest method from your own client

You can also create foreign DVs as external SubCAs. Note however that an advantage of handling foreign DVs as end entities is that you can process and renew them using the same WS-API as you can use for inspection systems.

You can create a DV to be signed by a foreign CVCA by creating a new CA and selecting Signed By=External CA. You need the CVCA certificate of the foreign CVCA to create the request to be sent. When creating this CA a self-signed CV certificate request is created.

You can at any time create a CV certificate request from a DV by going into Edit Certificate Authorities and click Make Certificate Request. This generates a CSR created by the CAs keystore. When receiving the signed certificate back, you can feed that to your IS-system. There is no need (or way) to import it into EJBCA.

You can renew a DV by going into Edit Certificate Authorities and click Renew CA. By uploading the CA certificate supposed to sign the certificate, you can get a new CSR created. You can import the received certificate by clicking Receive Certificate Response. You only have to (or can) import one issued certificate to make your DV operational. If you get a DV signed by multiple CVCAs you can distribute the other than the main DV certificate to the IS's (or AT or ST) by other means. 

By specifying the CA tokens password and enabling Renew Keys, the DV will generate new keys. This works for both soft CA tokens and PKCS#11 CA tokens. The renewal CSR is not signed with the old keys, but that can be done manually.

DVs have short validity periods and it can be useful to have them automatically renewed. You can use the EJBCA service Renew CA Service to automatically renew CAs. For more information, see Renew CA Service.

Creating a DV and Managing the DV Lifecycle using WS

You can create a DV and manage its lifecycle completely using the WS API. The following command sequence can be used:

  • createExternallySignedCa: Create a DV, generating a CSR that will be signed by a CVCA, either an offline domestic CVCA or a foreign CVCA.
  • caCertResponse: Import the received DV certificate, issued by the CVCA, activating the DV.
  • caRenewCertRequest: Renewing the DV, generating new keys and a new CSR to be sent to the CVCA. The old DV key and certificate is still active until the response has been received from the CVCA.
  • caCertResponse: Import the received DV certificate, activating the DVs new signing key and certificate.

There is sample Java code for the DV lifecycle in the test suite of EJBCA. A good example demonstrating the usage of the above commands is for example the test case EjbcaWSCVCTest.test36MultipleDVWithSameDNECC.

DV Naming Conventions

An important feature of Extended Access Control (EAC) PKI is creating DVs for multiple foreign countries. This is the case where one country, in order to read fingerprints from other countries' travel documents, have (one or more) DVs signed by the other countries CVCA. The standards are deliberately open-ended as to how to implement this, and which naming conventions to use.

The recommended way to configure this in EJBCA is to create one DV for each foreign country whose fingerprints should be read. That is, having one DV (SubCA) for each country, signed by that country's CVCA (Root CA).

The following two naming conventions can be used to create DVs in EJBCA, where each DV is signed by an External CA, being the other country's CVCA (Country/Mnemonic/Sequence), where the Mnemonic can be arbitrary.

Distinct Mnemonic for each DV

All DVs set up by your country will have the same country code, but the mnemonic is set to different values to display which country the respective DV is signed by.

This is the recommended naming convention in EJBCA, as it provides a clean separation of DVs that is easy to maintain and hard to get wrong.

Some examples:

  • SE/NDVCA01/GR001 (DV set up in Sweden, to be signed by Greek CVCA)
  • SE/NDVCA02/NO001 (DV set up in Sweden, to be signed by Norwegian CVCA)
  • SE/ESDVCA01/00001 (DV set up in Sweden, to be signed by Spanish CVCA)
  • etc

There is flexibility in the Mnemonic, which can be 1-9 characters long. There is also flexibility in the Sequence, that can use pure numeric sequences of 5 characters (00001, 00002, etc), or country code + numeric (SE001, SE002, etc), or country code + alphanumeric (hex) (SEA01, SEB01, SEB0F, etc). Each DV (SubCA) needs to have a unique combination of country and mnemonic, i.e. C and CN when creating the DV (SubCA).

Same Mnemonic for all DVs

All DVs set up by your country will have the same country code and the same mnemonic. A country code in the key sequence is used to distinguish which country the respective DV is signed by.

This naming convention is used by some countries and supported by EJBCA, albeit we consider it preferable to use different mnemonics for each DV.

Some examples:

  • FI/TDVCA001/GR001 (DV set up in Finland, to be signed by Greek CVCA, using Country Code + Numeric key sequence format)
  • FI/TDVCA001/NO001 (DV set up in Finland, to be signed by Norwegian CVCA, using Country Code + Numeric key sequence format)
  • FI/TDVCA001/ESFAA (DV set up in Finland, to be signed by Spanish CVCA, using Country Code + AlphaNumeric key sequence format)
  • etc

When using the same mnemonic for each DV there is less flexibility in the Sequence. The sequence can never be the same for two DVs, as they could then be identical (Country+Mnemonic+Sequence). Therefore a sequence format of Country Code + Numeric or AlphaNumeric must be used. Each DV (SubCA) needs to have a unique combination of country, mnemonic and sequence when creating the DV (SubCA).

When using the same mnemonic for two DVs, you must add the OU DN component when creating the CA in EJBCA. An example to create two DVs in the Admin UI (OU components highlighted):

  • Certification Authorities > Create
    • Name: DVCA-FI-SE
      • Type: CVCA
      • Algorithms and crypto token to match the CVCA of Sweden
      • Key Sequence: SE001
      • CA DN: C=FI,CN=TDVCA001,OU=Sweden
      • Signed by: External CA
      • Upload cvca-se.cvcert
      • Make request, download binary file to send to the CVCA of Sweden to be signed, save file FITDVCA001SE001.cvreq
    • Name: DVCA-FI-NO
      • Type: CVCA
      • Algorithms and crypto token to match the CVCA of Norway
      • Key Sequence: NO001
      • CA DN: C=FI,CN=TDVCA001,OU=Norway
      • Signed by: External CA
      • Upload cvca-no.cvcert
      • Make request, download binary file to send to the CVCA of Norway to be signed, save file FITDVCA001NO001.cvreq
  • Import DVCA certificates, to activate DVCAs

    • On DVCA-FI-SE:

      • Certification Authorities->DVCA-FI-SE->Edit CA

      • In the section 'Externally signed CA creation/renewal->Step 2 − Import Certificate'

      • Browse to upload the certificate signed by Swedish CVCA: SECVCA00100000_FITDVCA001SE001.cvcert

      • Click Receive Certificate Response

      • Message should be: Certificate Response received successfully, CA Activated

    • On DVCA-FI-NO:

      • Certification Authorities->DVCA-FI-NO->Edit CA

      • In the section 'Externally signed CA creation/renewal->Step 2 − Import Certificate'

      • Browse to upload the certificate signed by Norwegian CVCA: NOCVCA00100000_FITDVCA001NO001.cvcert

      • Click Receive Certificate Response

      • Message should be: Certificate Response received successfully, CA Activated

Importing DVs

You can also import DVs. Doing that you need a chain with the DV certificate first, and the CVCA certificate second.

# Import the CVCA
$ bin/ejbca.sh ca importcvcca --caname CVCARSA -f CVCARSA.pkcs8 -c SECVCARSA00000_SECVCARSA00000.cacert.pem
# Create the certificate chain PEM file
$ cat SECVCARSA00000_SEDVCARSA00000.cacert.pem SECVCARSA00000_SECVCARSA00000.cacert.pem > chain.pem
# Import the DV
$ bin/ejbca.sh ca importcvcca --caname DVCARSA -f DVCARSA.pkcs8 -c chain.pem 

Creating Authenticated Requests

To sign CV certificate requests by your Country Verifying CA (CVCA), go to Edit Certificate Authorities, select your CVCA and then click Create Authenticated Certificate Signing Request. You can upload the CV certificate request to the CVCA, and get an Authenticated request back. This is required when sending certificate requests from your DVs to other member states.

By renewing a Document Verifier (DV) and sending a request to another member state you can get the request automatically authenticated by signing the request with the DVs old keys. You can do this by creating a CSR for the new DV key, and making an authenticated request signed with the old key. After generating new keys on the Crypto Token, go to Certification Authorities, select the desired DV, and click Edit. Ensure that the sequence is updated, then select to generate a new CSR for the new key in the Externally signed CA creation/renewal section. If it is a renewal, an authenticated request, authenticated with the DVs current key, will be returned (the new key is not yet activated).

To view the authenticated DV request using the clientToolBox CLI tool, use the following:

$ ./ejbcaClientToolBox.sh CvcWsRaCli cvcprint SEDVCA00100001.pem

To verify the authenticated DV request, you need the whole chain in case of ECDSA, since the EC curve parameters are only present in the CVCA certificate.

$ ./ejbcaClientToolBox.sh CvcWsRaCli cvcprint SEDVCA00100001.pem  SECVCA00100000_SEDVCA00100000.cacert.pem SECVCA00100000_SECVCA00100000.cacert.pem 

To automate renewing of DVCAs using the WS API, use the following:

$ ./ejbcaClientToolBox.sh EjbcaWsRaCli cacertrequest
$ ./ejbcaClientToolBox.sh EjbcaWsRaCli cacertresponse

For more information, see Web Service Interface.

Creating Link Certificates

Issuing a link certificate must be done when a CVCA is renewed. It can be used to switch CA completely, new keys, new algorithms, and new Country/Mnemonic.

When renewing a Country Verifying CA (CVCA) in the EJBCA Admin UI, a link certificate is automatically created. Requirements on link certificates are specified in Common Certificate Policy for the Extended Access Control Infrastructure for Travel and Residence Documents (BSI TR-03139). When renewing a CVCA, the signature algorithm can be changed. Note that the algorithm identifier in the link certificate itself is the new algorithm as the algorithm is tied to the public key, not to the certificate signature and the link certificate itself is signed by the old CVCA certificate, with the algorithm specified on the public key in the old CVCA certificate.

It is also possible to manually create link certificates using the clientToolBox CLI tool.

$ ./ejbcaClientToolBox.sh PKCS11HSMKeyTool linkcert

To create CVCA link certificates, the same approach is used. First renew the CVCA (generating new keys), which creates a new self-signed CVCA certificate internally. Download the new self-signed CVCA certificate (for example from Basic Functions). After this, you can create a link certificate by specifying the CVCAs name in the text field in Edit Certificate Authorities and clicking Sign Certificate Request. Upload the new CVCA certificate and select Use previous key and Create link certificate.

Command Line Interface Commands

The Command Line Client using the WS-API can be used for reference on how to use the WS-API.

The client has the following functions:

  • cvcrequest: Adds a new user and requests a CV Certificate.
  • cvcgetchain: Retrieves the last certificate chain for a user.
  • cvcprint: Used to parse and print CV Certificate and requests.

Enter the command to retrieve usage information:

$ cd dist/clientToolBox
$ dist/clientToolBox> ./ejbcaClientToolBox.sh CvcWsRaCli
Usage: cvcrequest cvcgetchain cvcprint cvcpem
  
$ dist/clientToolBox> ./ejbcaClientToolBox.sh CvcWsRaCli cvcrequest
Usage : cvcrequest <username> <password> <subjectdn> <sequence> <caname> <signatureAlg> ...
...
  
$ dist/clientToolBox> ./ejbcaClientToolBox.sh CvcWsRaCli cvcprint
Usage : cvcprint <filename> [verifycert]
...

CLI Authentication and Privileges

The CLI uses Client Certificate Authentication, enabling performing administrative tasks in EJBCA as long as your client certificate has the correct RA administrator privileges in EJBCA.

To issue certificates for a request, an end entity must first be added in EJBCA. Unauthenticated requests entered using the CLI is authenticated using a one-time password set during entity registration. 

However, authenticated requests are verified, granted or rejected based on the verification of the outer signature on the request. If an end entity already exists, and has a previously issued certificate, the previous certificate can authenticate the request and automatically grant it. 

For DV requests authenticated with a CVCA certificate, the CVCA certificate instead of a previously issued certificate can authenticate the request.

CLI Examples

The CLI is part of the Client Tool Box.

Run the following to build the Client Tool Box (that can be used from any remote computer):

$ ant clientToolBox
$ cd dist/clientToolBox  

Example 1: Receiving request from a Foreign DV

The following displays an example command to receive a request from a foreign DV:

$ ./ejbcaClientToolBox.sh EjbcaWsRaCli edituser dv-de foo123 false "CN=dvca,C=DE" NULL NULL CVCAPK 1 USERGENERATED NEW DV DV  
$ ./ejbcaClientToolBox.sh CvcWsRaCli cvcrequest dv-de foo123 "CN=dvca,C=DE" SE001 SHA256WithRSA 2048 false dedv

Where

  • your CVCA is called CVCAPK in EJBCA and uses algorithm SHA256WithRSA with 2048 bit keys.
  • an End entity profile, DV, is created with CN and C as required DN fields, and DV as available certificate profiles.
  • a Certificate profile, DV, is created of type SubCA.
  • the received request is stored in a file dedv.cvreq.

The first command adds the end entity in EJBCA and only has to be run the first time. foo123 is the one-time password set to authenticate the request.

If the request is an authenticated request signed by a CVCA and that CVCA has been imported in EJBCA (Edit Certificate Authorities->Import CA certificate), the request will be verified and granted. For authenticated request, the one-time password is not used.

Example 2: Generating Keys and Request for an IS

The following displays an example command to generate keys and a request for an IS using SHA256WithECDSA and secp256r1 curve:

$ ./ejbcaClientToolBox.sh EjbcaWsRaCli edituser issecp foo123 false "CN=ISSECP,C=SE" NULL NULL DVCA 1 USERGENERATED NEW IS IS

This command adds the IS as an end entity in EJBCA. It only has to be done the first time, or if the IS previous certificates expire. When using authenticated requests these are used instead of the one-time password, but if the previous certificate expires, a new one-time password is needed to authenticate the request.

$ ./ejbcaClientToolBox.sh CvcWsRaCli cvcrequest issecp foo123 "C=SE,CN=ISSECP" 00005 SHA256WithECDSA secp256r1 true issecp

Where

  • your DV is called DVCA in EJBCA and uses algorithm SHA256WithECDSA with secp256r1 curve. Where an End entity profile, IS, is created with CN and C as required DN fields, and IS as available certificate profiles.
  • a Certificate profile, IS, is created of type EndEntity.
  • the generated request is stored in a file issecp.cvreq, the generated private key in issecp.pkcs8.

The issued IS certificate is stored in the file issecp.cvcert.

If the request is an authenticated request signed by a CVCA and that CVCA has been imported in EJBCA, the request will be verified and granted.

To create an authenticated request for this user you can issue the following command, which authenticates the new request with the old key and certificate.

$ ./ejbcaClientToolBox.sh CvcWsRaCli cvcrequest issecp foo123 "C=SE,CN=ISSECP" 00006 SHA256WithECDSA secp256r1 true issecpnew issecp.pkcs8 issecp.cvcert

The request will be automatically granted (the password passed will be ignored) and the new certificate will be written to issecpnew.cvcert.

Workflow Example

This gives an overview of a full workflow example of how to create a DV and issue IS certificates.

The commands outlined below are examples and need to be adjusted for your local conditions. The same operations can also be performed in other ways or using the WS API instead of the Admin UI.

Create New DVCA

To create a new DVCA:

  1. On the local DV system, go to Admin UI > Certification Authorities > Create and specify the following:
    • Name: DVCA-SE
    • Type: CVCA
    • Algorithms and crypto token to match the foreign CVCA
    • Key Sequence: FR001
    • CA DN: C=SE,CN=TDVCA001
    • Signed by: External CA
    • Upload CVCA certificate
    • Make certificate request and download the binary file to send to the foreign CVCA

Look at the request and verify that it looks proper:

./ejbcaClientToolBox.sh CvcWsRaCli cvcprint FITDVCA001NO001.cvreq
Printing CV Certificate: FITDVCA001NO001.cvreq
7f21 CV_CERTIFICATE  
   7f4e CERTIFICATE_BODY  
      5f29 PROFILE_IDENTIFIER  0
      42 CA_REFERENCE  NO/CVCA001/00000
      7f49 PUBLIC_KEY  
         6 OID  0.4.0.127.0.7.2.2.2.2.4
         81 MODULUS  FFFFFFFF00000001000000000000000000000000FFFFFFFFFFFFFFFFFFFFFFFF
         82 COEFFICIENT_A  FFFFFFFF00000001000000000000000000000000FFFFFFFFFFFFFFFFFFFFFFFC
         83 COEFFICIENT_B  5AC635D8AA3A93E7B3EBBD55769886BC651D06B0CC53B0F63BCE3C3E27D2604B
         84 BASE_POINT_G  046B17D1F2E12C4247F8BCE6E563A440F277037D812DEB33A0F4A13945D898C2964FE342E2FE1A7F9B8EE7EB4A7C0F9E162BCE33576B315ECECBB6406837BF51F5
         85 BASE_POINT_R_ORDER  FFFFFFFF00000000FFFFFFFFFFFFFFFFBCE6FAADA7179E84F3B9CAC2FC632551
         86 PUBLIC_POINT_Y  049050E37BF9A234418846F75B9F4132A8630626A40276DE5A91C5DDE525B8F86FE369C50C5D7CF74EA7BF851D7D0AB79AF92272B9CC37D845A4AA0220A7DD02BD
         87 COFACTOR_F  1
      5f20 HOLDER_REFERENCE  FI/TDVCA001/NO001
   5f37 SIGNATURE  E7782435454A77E70B2108577BCD83EBBA5A1059A2EF6556E007026D6B81F5330A351D8CA7D5A4DDF2B0A7CE199AEF1445E0267B95691DFA61029A36221FD90C

Make it an Authenticated Request from your Local CVCA

Optionally, create an authenticated request, signed by your local CVCA. If the foreign CVCA trusts your CVCA they can then verify the DV CSR automatically.

To create an authenticated request, signed by your local CVCA:

  1. On the local CVCA system, go to Admin UI > Certification Authorities and:
    1. Select CVCA > Create Authenticated Certificate Signing Request.
    2. Upload the CSR created from the DV above and click Sign Certificate Request.

Import DVCA Certificate to Activate the DVCA

To import DVCA Certificate to Activate the DVCA:

  1. On the local DV system go to Admin UI > Certification Authorities.
    • Select DVCA-SE > Edit CA.
    • In the section Externally signed CA creation/renewal > Step 2 − Import Certificate.
    • Browse to upload the DV certificate received from the foreign CVCA.
    • Click Receive Certificate Response.
    • Message should be: Certificate Response received successfully, CA Activated.

Create Inspection System

Create an IS signed by DVCA-SE (inspection system in SE, reading passports from the country of the foreign CVCA).

  1. On the local DV system go to Admin UI > Add End Entity.
  2. Select End entity profile (IS, created beforehand):
    • Username: TESTISSE1
    • C: FI
    • CN: TESTISSE1
    • Certificate profile: ENDUSER
    • CA: DVCA-SE
    • Token: User Generated

Enroll certificates (match algorithm and keys to DVCA/CVCA):

./ejbcaClientToolBox.sh CvcWsRaCli cvcrequest TESTISSE1 enrollment_code "CN=TESTISSE1,C=FI" 00001 SHA256WithECDSA prime256v1 true TESTISSE1

Look at the issued certificate and verify that it looks proper:

./ejbcaClientToolBox.sh CvcWsRaCli cvcprint TESTISSE1.cvcert
Printing CV Certificate: FITDVCA001NO001.cvreq
Printing CV Certificate: TESTISSE1.cvcert
7f21 CV_CERTIFICATE  
   7f4e CERTIFICATE_BODY  
      5f29 PROFILE_IDENTIFIER  0
      42 CA_REFERENCE  FI/TDVCA001/SE001
      7f49 PUBLIC_KEY  
         6 OID  0.4.0.127.0.7.2.2.2.2.3
         86 PUBLIC_POINT_Y  047CECB7C2ED8C9C76526D9B73EFF734166ACFA6E30DBF92F6C450042B6C108491AD3AB1FA11709E4B3B74A310C6783C9305623C1F3FFA0E468D1140864658B2DC
      5f20 HOLDER_REFERENCE  FI/TESTISSE1/00001
      7f4c HOLDER_AUTH_TEMPLATE  
         6 OID  0.4.0.127.0.7.3.1.2.1
         53 ROLE_AND_ACCESS_RIGHTS  03: IS/DG3+DG4
      5f25 EFFECTIVE_DATE  2020-05-15
      5f24 EXPIRATION_DATE  2022-05-15
   5f37 SIGNATURE  98A7456C771FEC77208180FAF74CCDF0FA649CA23C5E4C98FC0524046C122C5C20CB1DBA8EB66ECBBA51C06E9B9C936B6BED2E4D2AD9B493E1304D0807EE9C3B