OpenPACE: Data Management and Initialization

OpenPACE

Macros | Functions
Data Management and Initialization

## Macros
#define | CVC_CERT_dup(x) ASN1_dup_of(CVC_CERT, i2d_CVC_CERT, CVC_d2i_CVC_CERT, x)
| Duplicate a CV certificate. More...
#define | CVC_PUBKEY_dup(x) ASN1_dup_of(CVC_PUBKEY, i2d_CVC_PUBKEY, d2i_CVC_PUBKEY, x)
| Duplicate a CVC public key. More...
#define | CVC_CHAT_dup(x) ASN1_dup_of(CVC_CHAT, i2d_CVC_CHAT, d2i_CVC_CHAT, x)
| Duplicate a CHAT. More...

## Functions
void | CA_disable_passive_authentication (EAC_CTX *ctx)
| Disable passive authentication for this EAC_CTX. More...
CVC_CERT * | CVC_d2i_CVC_CERT (CVC_CERT **cert, const unsigned char **in, long len)
| Convert ASN1 formatted CV certificate to the internal structure. More...
int | i2d_CVC_CERT (CVC_CERT *a, unsigned char **out)
| Convert a CV certificate description to its ASN1 representation. More...
CVC_CERT * | CVC_CERT_new (void)
| Allocate memory for a CV certificate. More...
void | CVC_CERT_free (CVC_CERT *a)
| Free a CV certificate. More...
CVC_CERT * | d2i_CVC_CERT_bio (BIO *bp, CVC_CERT **cvc)
| Load a CV certificate from a BIO object. More...
EVP_PKEY * | CVC_pubkey2pkey (const CVC_CERT *cert, BN_CTX *bn_ctx, EVP_PKEY *out)
| Extract the public key from a CV certificate. Since EC domain parameters are only included in CVCA certificates, they must be passed as parameters for DV and terminal certificates. More...
CVC_PUBKEY * | CVC_pkey2pubkey (int all_parameters, int protocol, EVP_PKEY *key, BN_CTX *bn_ctx, CVC_PUBKEY *out)
void | EAC_init (void)
| Initializes OpenSSL and the EAC identifier. More...
void | EAC_cleanup (void)
| Wrapper to `EVP_cleanup()`
EAC_CTX * | EAC_CTX_new (void)
| Create a new EAC context. More...
void | EAC_CTX_clear_free (EAC_CTX *ctx)
| Free an EAC context. More...
int | EAC_CTX_init_pace (EAC_CTX *ctx, int protocol, int curve)
| Initialize an EAC context for PACE. More...
int | EAC_CTX_init_ta (const EAC_CTX *ctx, const unsigned char *privkey, size_t privkey_len, const unsigned char *cvca, size_t cvca_len)
| Initialize an EAC context for TA with the terminal's PKI data. Use either a CV certificate or a known CAR for initialization. More...
int | EAC_CTX_init_ca (EAC_CTX *ctx, int protocol, int curve)
| Initialize an EAC context for Chip Authentication. More...
int | EAC_CTX_init_ri (EAC_CTX *ctx, int protocol, int stnd_dp)
| Initialize an EAC context for Restricted Identification. More...
int | EAC_CTX_init_ef_cardaccess (unsigned const char *in, size_t in_len, EAC_CTX *ctx)
| Initialize an EAC context for PACE, TA and CA from the data given in an `EF.CardAccess`. More...
int | EAC_CTX_init_ef_cardsecurity (const unsigned char *ef_cardsecurity, size_t ef_cardsecurity_len, EAC_CTX *ctx)
| Initialize an EAC context for PACE, TA and CA from the data given in an `EF.CardSecurity`. More...
int | EAC_CTX_get_cvca_lookup (const EAC_CTX *ctx, CVC_lookup_cvca_cert *lookup_cvca_cert)
| Return the EAC context's CVCA lookup callback. More...
int | EAC_CTX_set_cvca_lookup (EAC_CTX *ctx, CVC_lookup_cvca_cert lookup_cvca_cert)
| Set the CVCA lookup callback. More...
CVC_lookup_cvca_cert | EAC_get_default_cvca_lookup (void)
| Return the default lookup of the country verifying CA. More...
void | EAC_set_cvc_default_dir (const char *default_dir)
| Set directory for `EAC_get_default_cvca_lookup()` More...
int | EAC_CTX_get_csca_lookup_cert (const EAC_CTX *ctx, X509_lookup_csca_cert *lookup_cvca_cert)
| Get the CSCA lookup callback. More...
int | EAC_CTX_set_csca_lookup_cert (EAC_CTX *ctx, X509_lookup_csca_cert lookup_cvca_cert)
| Set the CSCA lookup callback. More...
X509_lookup_csca_cert | EAC_get_default_csca_lookup (void)
| Return the default lookup of the country signing CA. More...
void | EAC_set_x509_default_dir (const char *default_dir)
| Set directory for `EAC_get_default_csca_lookup()` More...
void | PACE_SEC_clear_free (PACE_SEC *s)
| Free a PACE secret. More...
PACE_SEC * | PACE_SEC_new (const char *sec, size_t sec_len, enum s_type type)
| Create and initialize a new PACE secret. More...
int | PACE_SEC_print_private (BIO *out, const PACE_SEC *sec, int indent)
| Print PACE_SEC object including private secret. More...
void | RI_CTX_clear_free (RI_CTX *s)
| Frees a `RI_CTX` object and all its components. More...
RI_CTX * | RI_CTX_new (void)
| Creates a new `RI_CTX` object. More...
int | RI_CTX_set_protocol (RI_CTX *ctx, int protocol)
| Initializes a `RI_CTX` object using the protocol OID. This parameter can be found in the RIInfo part of an EF.CardSecurity. More...

## Detailed Description

## Macro Definition Documentation

## ◆ CVC_CERT_dup

#define CVC_CERT_dup | ( |  | x | ) | ASN1_dup_of(CVC_CERT, i2d_CVC_CERT, CVC_d2i_CVC_CERT, x)

Duplicate a CV certificate.

Parameters

  [in] | x | CV certificate to duplicate

Returns
  Duplicated CV certificate or NULL in case of an error

Definition at line 357 of file cv_cert.h.

## ◆ CVC_CHAT_dup

#define CVC_CHAT_dup | ( |  | x | ) | ASN1_dup_of(CVC_CHAT, i2d_CVC_CHAT, d2i_CVC_CHAT, x)

Duplicate a CHAT.

Parameters

  [in] | x | CHAT to duplicate

Returns
  Duplicated CHAT or NULL in case of an error

Definition at line 375 of file cv_cert.h.

## ◆ CVC_PUBKEY_dup

#define CVC_PUBKEY_dup | ( |  | x | ) | ASN1_dup_of(CVC_PUBKEY, i2d_CVC_PUBKEY, d2i_CVC_PUBKEY, x)

Duplicate a CVC public key.

Parameters

  [in] | x | CVC public key to duplicate

Returns
  Duplicated CVC public or NULL in case of an error

Definition at line 366 of file cv_cert.h.

## Function Documentation

## ◆ CA_disable_passive_authentication()

void CA_disable_passive_authentication | ( | EAC_CTX * | ctx | ) |

Disable passive authentication for this EAC_CTX.

Parameters

  ctx | EAC context

## ◆ CVC_CERT_free()

void CVC_CERT_free | ( | CVC_CERT * | a | ) |

Free a CV certificate.

Parameters

  [in] | a | CV certificate to free

## ◆ CVC_CERT_new()

CVC_CERT* CVC_CERT_new | ( | void |  | ) |

Allocate memory for a CV certificate.

Returns
  CHAT or NULL in case of an error

## ◆ CVC_d2i_CVC_CERT()

CVC_CERT* CVC_d2i_CVC_CERT | ( | CVC_CERT ** | cert,
|  | const unsigned char ** | in,
|  | long | len
| ) |  |

Convert ASN1 formatted CV certificate to the internal structure.

Parameters

  [in,out] | cert | (optional) Where to save the CV certificate
  [in] | in | ASN1 formatted CV certificate
  [in] | len | Length of in

Returns
  CV certificate or NULL in case of an error

## ◆ CVC_pubkey2pkey()

EVP_PKEY* CVC_pubkey2pkey | ( | const CVC_CERT * | cert,
|  | BN_CTX * | bn_ctx,
|  | EVP_PKEY * | out
| ) |  |

Extract the public key from a CV certificate. Since EC domain parameters are only included in CVCA certificates, they must be passed as parameters for DV and terminal certificates.

Parameters

  [in] | cert | the certificate containing the public key
  [in] | bn_ctx |
  [in,out] | out | (optional) where to save the extracted key. May contain domain parameters.

Returns
  An EVP_PKEY container with the public key or NULL in case of an error

## ◆ d2i_CVC_CERT_bio()

CVC_CERT* d2i_CVC_CERT_bio | ( | BIO * | bp,
|  | CVC_CERT ** | cvc
| ) |  |

Load a CV certificate from a BIO object.

This function seeks the BIO so that subsequent reads of multiple certificates are possible.

Parameters

  [in,out] | bp | bio object where to read from
  [in,out] | cvc | (optional) CV certificate to use

Returns
  CV certificate read or NULL in case of an error

## ◆ EAC_CTX_clear_free()

void EAC_CTX_clear_free | ( | EAC_CTX * | ctx | ) |

Free an EAC context.

Sensitive memory is cleared with OPENSSL_cleanse().

Parameters

  [in] | ctx | EAC context to free

## ◆ EAC_CTX_get_csca_lookup_cert()

int EAC_CTX_get_csca_lookup_cert | ( | const EAC_CTX * | ctx,
|  | X509_lookup_csca_cert * | lookup_cvca_cert
| ) |  |

Get the CSCA lookup callback.

Parameters

  [in] | ctx | EAC context
  [in,out] | lookup_cvca_cert | lookup callback

Returns
  1 on success or 0 in case of an error

## ◆ EAC_CTX_get_cvca_lookup()

int EAC_CTX_get_cvca_lookup | ( | const EAC_CTX * | ctx,
|  | CVC_lookup_cvca_cert * | lookup_cvca_cert
| ) |  |

Return the EAC context's CVCA lookup callback.

Parameters

  [in] | ctx | EAC context
  [in,out] | lookup_cvca_cert | lookup callback

Returns
  1 on success or 0 in case of an error

## ◆ EAC_CTX_init_ca()

int EAC_CTX_init_ca | ( | EAC_CTX * | ctx,
|  | int | protocol,
|  | int | curve
| ) |  |

Initialize an EAC context for Chip Authentication.

Parameters

  [in,out] | ctx | EAC context
  [in] | protocol | Identifier of the protocol's OID specifying the exact CA parameters to use
  [in] | curve | Standardized domain parameter identifier

Returns
  1 on success or 0 in case of an error

See also
  CA_CTX.protocol lists possible values for protocol

## ◆ EAC_CTX_init_ef_cardaccess()

int EAC_CTX_init_ef_cardaccess | ( | unsigned const char * | in,
|  | size_t | in_len,
|  | EAC_CTX * | ctx
| ) |  |

Initialize an EAC context for PACE, TA and CA from the data given in an `EF.CardAccess`.

Parameters

  [in] | in | `EF.CardAccess`
  [in] | in_len | Length of in
  [in,out] | ctx | EAC context to initialize

Returns
  1 on success or 0 in case of an error

## ◆ EAC_CTX_init_ef_cardsecurity()

int EAC_CTX_init_ef_cardsecurity | ( | const unsigned char * | ef_cardsecurity,
|  | size_t | ef_cardsecurity_len,
|  | EAC_CTX * | ctx
| ) |  |

Initialize an EAC context for PACE, TA and CA from the data given in an `EF.CardSecurity`.

Performs passive authentication if required.

Parameters

  [in] | ef_cardsecurity | buffer containing the ASN.1 encoded EF.CardSecurity
  [in] | ef_cardsecurity_len | length of ef_cardsecurity
  [in,out] | ctx | EAC context to initialize

Returns
  1 on success or 0 in case of an error

## ◆ EAC_CTX_init_pace()

int EAC_CTX_init_pace | ( | EAC_CTX * | ctx,
|  | int | protocol,
|  | int | curve
| ) |  |

Initialize an EAC context for PACE.

Parameters

  [in,out] | ctx | EAC context to initialize
  [in] | protocol | Identifier of the protocol's OID specifying the exact PACE parameters
  [in] | curve | Standardized domain parameter identifier

Returns
  1 on success or 0 in case of an error

See also
  PACE_CTX.protocol lists possible values for protocol

## ◆ EAC_CTX_init_ri()

int EAC_CTX_init_ri | ( | EAC_CTX * | ctx,
|  | int | protocol,
|  | int | stnd_dp
| ) |  |

Initialize an EAC context for Restricted Identification.

Parameters

  [in,out] | ctx | EAC context
  [in] | protocol | protocol Identifier of the protocol's OID specifying the exact RI parameters to use
  [in] | stnd_dp | Standardized domain parameter identifier

Returns
  1 on success or 0 in case of an error

See also
  RI_CTX.protocol lists possible values for protocol

## ◆ EAC_CTX_init_ta()

int EAC_CTX_init_ta | ( | const EAC_CTX * | ctx,
|  | const unsigned char * | privkey,
|  | size_t | privkey_len,
|  | const unsigned char * | cvca,
|  | size_t | cvca_len
| ) |  |

Initialize an EAC context for TA with the terminal's PKI data. Use either a CV certificate or a known CAR for initialization.

Parameters

  [in,out] | ctx | EAC context
  [in] | privkey | (optional) Private key to the given CV certificate
  [in] | privkey_len | Length of privkey
  [in] | cvca | (optional) CV certificate to use as trust anchor for verification of other CV certificates
  [in] | cvca_len | (optional) Length of cvca

Returns
  1 on success or 0 in case of an error

## ◆ EAC_CTX_new()

EAC_CTX* EAC_CTX_new | ( | void |  | ) |

Create a new EAC context.

Returns
  New EAC context or NULL in case of an error

## ◆ EAC_CTX_set_csca_lookup_cert()

int EAC_CTX_set_csca_lookup_cert | ( | EAC_CTX * | ctx,
|  | X509_lookup_csca_cert | lookup_cvca_cert
| ) |  |

Set the CSCA lookup callback.

Parameters

  [in] | ctx | EAC context
  [in] | lookup_cvca_cert | lookup callback

Returns
  1 on success or 0 in case of an error

## ◆ EAC_CTX_set_cvca_lookup()

int EAC_CTX_set_cvca_lookup | ( | EAC_CTX * | ctx,
|  | CVC_lookup_cvca_cert | lookup_cvca_cert
| ) |  |

Set the CVCA lookup callback.

Parameters

  [in] | ctx | EAC context
  [in] | lookup_cvca_cert | lookup callback

Returns
  1 on success or 0 in case of an error

## ◆ EAC_get_default_csca_lookup()

X509_lookup_csca_cert EAC_get_default_csca_lookup | ( | void |  | ) |

Return the default lookup of the country signing CA.

The default callback looks at /etc/eac/$chr for the CVCA certificate, where $chr is the card holder reference of the CVCA.

Returns
  default lookup of the country verifying CA

## ◆ EAC_get_default_cvca_lookup()

CVC_lookup_cvca_cert EAC_get_default_cvca_lookup | ( | void |  | ) |

Return the default lookup of the country verifying CA.

The default callback looks at /etc/eac/$issuer_name_hash.cer for the CSCA certificate, where $issuer_name_hash is an eight character lower hex value of the CSCA subject name.

Returns
  default lookup of the country verifying CA

See also
  `openssl x509 -in CERTIFICATE.cer -inform DER -hash -noout` to obtain the hash value.

## ◆ EAC_init()

void EAC_init | ( | void |  | ) |

Initializes OpenSSL and the EAC identifier.

See also
  `OpenSSL_add_all_algorithms()`

## ◆ EAC_set_cvc_default_dir()

void EAC_set_cvc_default_dir | ( | const char * | default_dir | ) |

Set directory for `EAC_get_default_cvca_lookup()`

Parameters

  cvc_default_dir |

## ◆ EAC_set_x509_default_dir()

void EAC_set_x509_default_dir | ( | const char * | default_dir | ) |

Set directory for `EAC_get_default_csca_lookup()`

Parameters

  x509_default_dir |

## ◆ i2d_CVC_CERT()

int i2d_CVC_CERT | ( | CVC_CERT * | a,
|  | unsigned char ** | out
| ) |  |

Convert a CV certificate description to its ASN1 representation.

Parameters

  [in] | a | CV certificate description
  [out] | out | Where to write the ASN1 representation of a

Returns
  Number of bytes successfully encoded or a negative value if an error occured.

## ◆ PACE_SEC_clear_free()

void PACE_SEC_clear_free | ( | PACE_SEC * | s | ) |

Free a PACE secret.

Sensitive memory is cleared with OPENSSL_cleanse().

Parameters

  [in] | s | (optional) Object to free

## ◆ PACE_SEC_new()

PACE_SEC* PACE_SEC_new | ( | const char * | sec,
|  | size_t | sec_len,
|  | enum s_type | type
| ) |  |

Create and initialize a new PACE secret.

Parameters

  [in] | sec | Raw secret
  [in] | sec_len | Length of sec
  [in] | type | Type of secret

Returns
  New PACE secret or NULL in case of an error

## ◆ PACE_SEC_print_private()

int PACE_SEC_print_private | ( | BIO * | out,
|  | const PACE_SEC * | sec,
|  | int | indent
| ) |  |

Print PACE_SEC object including private secret.

Parameters

  [in] | out | Where to print the data
  [in] | sec | EAC context to be printed
  [in] | indent | Number of whitespaces used for indenting the output

Returns
  1 on success or 0 in case of an error

## ◆ RI_CTX_clear_free()

void RI_CTX_clear_free | ( | RI_CTX * | s | ) |

Frees a `RI_CTX` object and all its components.

Parameters

  [in] | s | Object to free (optional)

## ◆ RI_CTX_new()

RI_CTX* RI_CTX_new | ( | void |  | ) |

Creates a new `RI_CTX` object.

Returns
  The new object or NULL if an error occurred

## ◆ RI_CTX_set_protocol()

int RI_CTX_set_protocol | ( | RI_CTX * | ctx,
|  | int | protocol
| ) |  |

Initializes a `RI_CTX` object using the protocol OID. This parameter can be found in the RIInfo part of an EF.CardSecurity.

Parameters

  [in,out] | ctx | The `RI_CTX` object to initialize
  [in] | protocol | The NID of the OID

Returns
  1 in case of success, 0 otherwise