Usage of OpenPACE

Using libeac

OpenPACE is a native C library on top of OpenSSL. If you want to know how to use OpenPACE from C/C++, have a look at our API documentation.

OpenPACE uses SWIG to offer bindings in some more programming languages. The bindings are easily portable to lots of different languages. Currently, native language bindings need to be explicitly turned on with ./configure --enable-...

If you have chosen to install OpenPACE in a non-standard location you have to set up the LD_LIBRARY_PATH environment variable correctly. One way to do this on Linux is:

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/to/libeac

If OpenPACE is compiled for Javascript, it results in a standalone Javascript file that can be used without special requirements.

More details and a number of examples for using the library are covered here:

• Programming with OpenPACE
  • Using OpenPACE in C/C++
  • Using OpenPACE in Python
  • Using OpenPACE in Ruby
  • Using OpenPACE in Go
  • Using OpenPACE in Java

New in version 1.1.2: Added wrappers for OpenSSL’s OBJ_* functions

New in version 1.0: Added support for certificate signing requests (CVC_verify_request_signature(), CVC_verify_authentication_request_signatures(), certificate_request_print(), certificate_authentication_request_print())

Using cvc-create to Create the EAC PKI

Usage: cvc-create [OPTION]...
Create a card verifiable certificate

  -h, --help                 Print help and exit
  -V, --version              Print version and exit
      --out-cert=FILENAME    Where to save the certificate
                               (default=`CHR.cvcert')
      --role=ENUM            The terminal's role  (possible values="cvca",
                               "dv_domestic", "dv_foreign", "terminal")
      --type=STRING          Type of the terminal. Known values are "at"
                               (Authentication Terminal), "is" (Inspection
                               System), "st" (Signature Terminal),
                               "derived_from_signer" (uses the the signer's
                               CVC type), any other value is interpreted as
                               object identifier.
                               (default=`derived_from_signer')
      --chat=HEXSTRING       Raw Card Holder Authorization Template (CHAT).
                               This option will overwrite any terminal specific
                               effective authorization (see options for
                               AT/IS/ST).
      --issued=YYMMDD        Date the certificate was issued  (default=`today')
      --expires=YYMMDD       Date until the certicate is valid
      --sign-with=FILENAME   Private key for signing the new certificate
      --scheme=ENUM          Signature scheme that the new terminal will use
                               (possible values="ECDSA_SHA_1",
                               "ECDSA_SHA_224", "ECDSA_SHA_256",
                               "ECDSA_SHA_384", "ECDSA_SHA_512",
                               "RSA_v1_5_SHA_1", "RSA_v1_5_SHA_256",
                               "RSA_v1_5_SHA_512", "RSA_PSS_SHA_1",
                               "RSA_PSS_SHA_256", "RSA_PSS_SHA_512")

 Mode: csr
  The properties of the certificate are derived from the given signing request.
      --csr=FILENAME         Certificate signing request with the attributes

 Mode: manual
  The properties of the certificate are derived from the command line switches.
      --chr=CCH...HSSSSS     Certificate holder reference (2 characters ISO
                               3166-1 ALPHA-2 country code, 0-9 characters
                               ISO/IEC 8859-1 holder mnemonic, 5 characters
                               ISO/IEC 8859-1 numeric or alphanumeric sequence
                               number)
      --sign-as=FILENAME     CV certificate of the entity signing the new
                               certificate  (default=`self signed')
      --key=FILENAME         Private key of the Terminal  (default=`derived
                               from signer')
      --out-key=FILENAME     Where to save the derived private key
                               (default=`CHR.pkcs8')

Options for an Authentication Terminal (AT):
      --out-desc=FILENAME    Where to save the encoded certificate description
                               (default=`CHR.desc')
      --cert-desc=FILENAME   Terms of usage as part of the certificate
                               description (*.txt, *.html or *.pdf)
      --issuer-name=STRING   Name of the issuer of this certificate
                               (certificate description)
      --issuer-url=URL       URL that points to informations about the issuer
                               of this certificate (certificate description)
      --subject-name=STRING  Name of the holder of this certificate
                               (certificate description)
      --subject-url=URL      URL that points to informations about the subject
                               of this certificate (certificate description)
      --write-dg17           Allow writing DG 17 (Normal Place of Residence)
                               (default=off)
      --write-dg18           Allow writing DG 18 (Community ID)  (default=off)
      --write-dg19           Allow writing DG 19 (Residence Permit I)
                               (default=off)
      --write-dg20           Allow writing DG 20 (Residence Permit II)
                               (default=off)
      --write-dg21           Allow writing DG 21 (Optional Data)  (default=off)
      --at-rfu32             Allow RFU R/W Access bit 32  (default=off)
      --at-rfu31             Allow RFU R/W Access bit 31  (default=off)
      --at-rfu30             Allow RFU R/W Access bit 30  (default=off)
      --at-rfu29             Allow RFU R/W Access bit 29  (default=off)
      --read-dg1             Allow reading DG 1   (Document Type)
                               (default=off)
      --read-dg2             Allow reading DG 2   (Issuing State)
                               (default=off)
      --read-dg3             Allow reading DG 3   (Date of Expiry)
                               (default=off)
      --read-dg4             Allow reading DG 4   (Given Names)  (default=off)
      --read-dg5             Allow reading DG 5   (Family Names)  (default=off)
      --read-dg6             Allow reading DG 6   (Religious/Artistic Name)
                               (default=off)
      --read-dg7             Allow reading DG 7   (Academic Title)
                               (default=off)
      --read-dg8             Allow reading DG 8   (Date of Birth)
                               (default=off)
      --read-dg9             Allow reading DG 9   (Place of Birth)
                               (default=off)
      --read-dg10            Allow reading DG 10  (Nationality)  (default=off)
      --read-dg11            Allow reading DG 11  (Sex)  (default=off)
      --read-dg12            Allow reading DG 12  (Optional Data)
                               (default=off)
      --read-dg13            Allow reading DG 13  (default=off)
      --read-dg14            Allow reading DG 14  (default=off)
      --read-dg15            Allow reading DG 15  (default=off)
      --read-dg16            Allow reading DG 16  (default=off)
      --read-dg17            Allow reading DG 17  (Normal Place of Residence)
                               (default=off)
      --read-dg18            Allow reading DG 18  (Community ID)  (default=off)
      --read-dg19            Allow reading DG 19  (Residence Permit I)
                               (default=off)
      --read-dg20            Allow reading DG 20  (Residence Permit II)
                               (default=off)
      --read-dg21            Allow reading DG 21  (Optional Data)
                               (default=off)
      --install-qual-cert    Allow installing qualified certificate
                               (default=off)
      --install-cert         Allow installing certificate  (default=off)
      --pin-management       Allow PIN management  (default=off)
      --can-allowed          CAN allowed  (default=off)
      --privileged           Privileged terminal  (default=off)
      --rid                  Allow restricted identification  (default=off)
      --verify-community     Allow community ID verification  (default=off)
      --verify-age           Allow age verification  (default=off)

Options for a Signature Terminal (ST):
      --st-rfu5              Allow RFU bit 5  (default=off)
      --st-rfu4              Allow RFU bit 4  (default=off)
      --st-rfu3              Allow RFU bit 3  (default=off)
      --st-rfu2              Allow RFU bit 2  (default=off)
      --gen-qualified-sig    Generate qualified electronic signature
                               (default=off)
      --gen-sig              Generate electronic signature  (default=off)

Options for an Inspection System (IS):
      --read-eid             Read access to eID application (Deprecated)
                               (default=off)
      --is-rfu4              Allow RFU bit 4  (default=off)
      --is-rfu3              Allow RFU bit 3  (default=off)
      --is-rfu2              Allow RFU bit 2  (default=off)
      --read-iris            Read access to ePassport application: DG 4 (Iris)
                               (default=off)
      --read-finger          Read access to ePassport application: DG 3
                               (Fingerprint)  (default=off)

Report bugs to https://github.com/frankmorgner/openpace/issues

Written by Frank Morgner <frankmorgner@gmail.com>

Below you see an example of how to create a certificate chain of CVCA, DVCA and a Terminal:

# Create country verifying CA's private key
openssl ecparam -out ZZATCVCA00001.pem -name prime192v1 -genkey -param_enc explicit
openssl pkcs8 -topk8 -nocrypt -in ZZATCVCA00001.pem -outform DER -out ZZATCVCA00001.pkcs8
# Create self signed country verifying CA certificate
cvc-create --role=cvca --type=at --chr=ZZATCVCA00001 --expires=`date --date="next year" "+%^y%^m%^d"` --sign-with=ZZATCVCA00001.pkcs8 --scheme=ECDSA_SHA_256 --rid

# Create DVCA certificate signed by CVCA and generate its private key
cvc-create --role=dv_domestic --chr=ZZATDVCA00001 --expires=`date --date="next month" "+%^y%^m%^d"` --sign-with=ZZATCVCA00001.pkcs8 --sign-as=ZZATCVCA00001.cvcert --scheme=ECDSA_SHA_256 --rid

# Create plain text description
echo "whatever" > ZZATTERM00001.txt
# Create TERM certificate signed by DVCA along with the description and generate its private key
cvc-create --role=terminal --chr=ZZATTERM00001 --expires=`date --date="next week" "+%^y%^m%^d"` --sign-with=ZZATDVCA00001.pkcs8 --sign-as=ZZATDVCA00001.cvcert --scheme=ECDSA_SHA_256 --rid --cert-desc=ZZATTERM00001.txt --issuer-name=DVCA --subject-name=TERM

The script generate-eac-pki.sh generates a set of authentication terminals and signature terminals for all signature schemes in all standardized elliptic curves.

New in version 1.1.0: Added support for arbitrary terminal types (--type)

New in version 1.1.0: Added support for arbitrary CHATs (--chat)

New in version 1.0: - Added support for certificate signing requests (--csr) - Renamed --out to --out-cert and added --out-desc, --out-key

New in version 0.9: Created cvc-create for generating a EAC PKI of Authentication Terminals, Signature Terminals or Inspection Systems.

Using cvc-print

Usage: cvc-print [OPTION]...
Prints card verifiable certificate and its description

  -h, --help                  Print help and exit
  -V, --version               Print version and exit
  -c, --cvc=FILENAME          Card Verifiable Certificate
  -d, --description=FILENAME  Certificate description
  -r, --csr=FILENAME          Certificate request
      --cvc-dir=DIRECTORY     Directory of trusted CVCs

Report bugs to https://github.com/frankmorgner/openpace/issues

Written by Frank Morgner and Dominik Oepen

Below you see of how to print the certificates created in the example above:

cvc-print --cvc ZZATCVCA00001.cvcert
cvc-print --cvc ZZATDVCA00001.cvcert
cvc-print --cvc ZZATTERM00001.cvcert --description ZZATTERM00001.desc

New in version 1.1.3: Added --disable-cvc-validity-check

New in version 1.0.2: Added --cvc-dir

New in version 1.0: Added support for certificate signing requests (--csr)

New in version 0.8: Created cvc-print for printing card verifiable certificates.

Creating the Document PKI and EF.CardAccess/EF.CardSecurity

The card’s key agreement capabilities can be read by the terminal from EF.CardAccess. The standardized domain parameter for CA (e.g. brainpoolP256r1/0x0D) need to match the key agreement scheme for CA (e.g. ECDH):

asn1=SET:SecurityInfos

[SecurityInfos]
tainfo=SEQUENCE:TerminalAuthenticationInfo
cainfo=SEQUENCE:ChipAuthenticationInfo
chipauthenticationdomainparameterinfo=SEQUENCE:ChipAuthenticationDomainParameterInfo

[TerminalAuthenticationInfo]
# id-TA
protocol=OID:0.4.0.127.0.7.2.2.2
version=INTEGER:0x02

[ChipAuthenticationInfo]
# id-CA-ECDH-AES-CBC-CMAC-128
protocol=OID:0.4.0.127.0.7.2.2.3.2.2
version=INTEGER:0x02

[ChipAuthenticationDomainParameterInfo]
# id-CA-ECDH
protocol=OID:0.4.0.127.0.7.2.2.3.2
aid=SEQUENCE:AlgorithmIdentifier

[AlgorithmIdentifier]
# standardizedDomainParameters
algorithm=OID:0.4.0.127.0.7.1.2
# brainpoolP256r1
parameter=INTEGER:0x0D

The above example can be found in doc/efcardaccess_asn1.conf. OpenSSL can translate this into its ASN.1 represantation, which gives us EF.CardAccess:

openssl asn1parse -genconf efcardaccess_asn1.conf -out efcardaccess.dump

In EF.CardSecurity the data of EF.CardAccess including the CA public key of the chip is signed by the document signer. First we create the CSCA and the document signer:

# Create the country signing CA's private key
openssl ecparam -out csca_key.pem -name brainpoolP256r1 -genkey -param_enc explicit
# Create the country verifying CA's self signed certificate
openssl req -new -x509 -days 5000 -key csca_key.pem -out csca_cert.pem

# Create the document signer's private key
openssl ecparam -out docsigner_key.pem -name brainpoolP256r1 -genkey -param_enc explicit
# Create the document signer's certificate (signing request)
openssl req -new -key docsigner_key.pem -out docsigner.csr
openssl x509 -req -in docsigner.csr -CA csca_cert.pem -CAkey csca_key.pem -CAcreateserial -out docsigner_cert.pem

Now generate the chip’s private key for CA and print its (public) key:

# Create chip's key
openssl ecparam -out card_key.pem -name brainpoolP256r1 -genkey -param_enc explicit
# Print the public key and copy it to the clipboard
openssl ec -in card_key.pem -text

Finally we can create EF.CardSecurity by adding the card’s public key to the last line of our template and signing the content with the document signer’s key:

# Add the public key (without ':' and ' ') to the template for EF.CardSecurity
cp doc/efcardsecurity_templ_asn1.conf efcardsecurity_asn1.conf && vi efcardsecurity_asn1.conf

# Create and sign EF.CardSecurity
openssl asn1parse -genconf efcardsecurity_asn1.conf -out efcardsecurity_content.dump
openssl cms -sign -nodetach -binary -in efcardsecurity_content.dump -inform DER -signer docsigner_cert.pem -inkey docsigner_key.pem -econtent_type 0.4.0.127.0.7.3.2.1 -noattr -outform DER -out efcardsecurity.dump