# 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

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

Added 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.

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

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

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

Added 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
          --disable-cvc-verification
                                    Disable verification of CV certificates
                                      (default=off)

    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

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

Added in version 1.0.2: Added `--cvc-dir`

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

Added 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