cv_cert.h File Reference

Interface for Card Verifiable Certificates. More...

`#include <eac/objects.h>`
`#include <openssl/asn1.h>`
`#include <openssl/asn1t.h>`
`#include <openssl/bio.h>`

Go to the source code of this file.

## Data Structures

struct | cvc_chat_seq_st
| Certificate Holder Authentication Template. More...
struct | cvc_pubkey_st
| Public key data object which may contain domain parameters. More...
struct | cvc_discretionary_data_template_seq_st
| Discretionary data template, used to encode certificate extensions. More...
struct | cvc_cert_body_seq_st
| The body of the CV certificate (without signature) More...
struct | cvc_cert_seq_st
| The actual certifcate, consisting of the body and a signature. More...
struct | cvc_commcert_seq_st
struct | cvc_certificate_description_st
| This structure holds further information about a card verifiable certificate in human readable form. More...
struct | cvc_cert_request_body_seq_st
| The body of the CV certificate request (without signature) More...
struct | cvc_cert_request_seq_st
| The actual certifcate request, consisting of the body and inner signature. More...
struct | cvc_cert_authentication_request_seq_st
| The authentication request, consisting of the certificate request, certificate authority reference and outer signature. More...

## Macros

#define | ASN1_APP_IMP(stname, field, type, tag) ASN1_EX_TYPE(ASN1_TFLG_IMPTAG|ASN1_TFLG_APPLICATION, tag, stname, field, type)
#define | ASN1_APP_IMP_OPT(stname, field, type, tag) ASN1_EX_TYPE(ASN1_TFLG_IMPTAG|ASN1_TFLG_APPLICATION|ASN1_TFLG_OPTIONAL, tag, stname, field, type)
#define | ASN1_APP_EXP_OPT(stname, field, type, tag) ASN1_EX_TYPE(ASN1_TFLG_EXPTAG|ASN1_TFLG_APPLICATION|ASN1_TFLG_OPTIONAL, tag, stname, field, type)
#define | ASN1_APP_IMP_SEQUENCE_OF_OPT(stname, field, type, tag) ASN1_EX_TYPE(ASN1_TFLG_SEQUENCE_OF|ASN1_TFLG_IMPTAG|ASN1_TFLG_APPLICATION|ASN1_TFLG_OPTIONAL, tag, stname, field, type)
#define | EAC_AT_CHAT_BYTES 5
#define | EAC_AT_CHAT_BITS 38
#define | EAC_IS_CHAT_BYTES 1
#define | EAC_IS_CHAT_BITS 6
#define | EAC_ST_CHAT_BYTES 1
#define | EAC_ST_CHAT_BITS 6
#define | CVC_CERT_dup(x) ASN1_dup_of(CVC_CERT, i2d_CVC_CERT, CVC_d2i_CVC_CERT, x)
| Duplicate a CV certificate.
#define | CVC_PUBKEY_dup(x) ASN1_dup_of(CVC_PUBKEY, i2d_CVC_PUBKEY, d2i_CVC_PUBKEY, x)
| Duplicate a CVC public key.
#define | CVC_CHAT_dup(x) ASN1_dup_of(CVC_CHAT, i2d_CVC_CHAT, d2i_CVC_CHAT, x)
| Duplicate a CHAT.

## Typedefs

typedef struct cvc_chat_seq_st | CVC_CHAT_SEQ
| Certificate Holder Authentication Template.
typedef CVC_CHAT_SEQ | CVC_CHAT
| Short name for CVC_CHAT_SEQ.
typedef struct cvc_pubkey_st | CVC_PUBKEY_BODY
| Public key data object which may contain domain parameters.
typedef CVC_PUBKEY_BODY | CVC_PUBKEY
typedef struct cvc_discretionary_data_template_seq_st | CVC_DISCRETIONARY_DATA_TEMPLATE_SEQ
| Discretionary data template, used to encode certificate extensions.
typedef CVC_DISCRETIONARY_DATA_TEMPLATE_SEQ | CVC_DISCRETIONARY_DATA_TEMPLATE
| Short name for CVC_CERT_BODY_SEQ.
typedef struct cvc_cert_body_seq_st | CVC_CERT_BODY_SEQ
| The body of the CV certificate (without signature)
typedef CVC_CERT_BODY_SEQ | CVC_CERT_BODY
| Short name for CVC_CERT_BODY_SEQ.
typedef struct cvc_cert_seq_st | CVC_CERT_SEQ
| The actual certifcate, consisting of the body and a signature.
typedef CVC_CERT_SEQ | CVC_CERT
| Short name for CVC_CERT_SEQ.
typedef struct cvc_commcert_seq_st | CVC_COMMCERT_SEQ
typedef struct cvc_certificate_description_st | CVC_CERTIFICATE_DESCRIPTION
| This structure holds further information about a card verifiable certificate in human readable form.
typedef struct cvc_cert_request_body_seq_st | CVC_CERT_REQUEST_BODY_SEQ
| The body of the CV certificate request (without signature)
typedef CVC_CERT_REQUEST_BODY_SEQ | CVC_CERT_REQUEST_BODY
| Short name for CVC_CERT_REQUEST_BODY_SEQ.
typedef struct cvc_cert_request_seq_st | CVC_CERT_REQUEST_SEQ
| The actual certifcate request, consisting of the body and inner signature.
typedef CVC_CERT_REQUEST_SEQ | CVC_CERT_REQUEST
| Short name for CVC_CERT_REQUEST_SEQ.
typedef struct cvc_cert_authentication_request_seq_st | CVC_CERT_AUTHENTICATION_REQUEST_SEQ
| The authentication request, consisting of the certificate request, certificate authority reference and outer signature.
typedef CVC_CERT_AUTHENTICATION_REQUEST_SEQ | CVC_CERT_AUTHENTICATION_REQUEST
| Short name for CVC_CERT_AUTHENTICATION_REQUEST_SEQ.

## Enumerations

enum | cvc_terminal_role { CVC_Terminal = 0 , CVC_DocVer , CVC_DV , CVC_CVCA }
| Effective role of the certificate holder. More...

## Functions

CVC_CERT * | CVC_d2i_CVC_CERT (CVC_CERT **cert, const unsigned char **in, long len)
| Convert ASN1 formatted CV certificate to the internal structure.
int | i2d_CVC_CERT (CVC_CERT *a, unsigned char **out)
| Convert a CV certificate description to its ASN1 representation.
CVC_CERT * | CVC_CERT_new (void)
| Allocate memory for a CV certificate.
void | CVC_CERT_free (CVC_CERT *a)
| Free a CV certificate.
CVC_CERT * | d2i_CVC_CERT_bio (BIO *bp, CVC_CERT **cvc)
| Load a CV certificate from a BIO object.
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.
CVC_PUBKEY * | CVC_pkey2pubkey (int all_parameters, int protocol, EVP_PKEY *key, BN_CTX *bn_ctx, CVC_PUBKEY *out)
int | certificate_description_print (BIO *bio, const CVC_CERTIFICATE_DESCRIPTION *desc, int indent)
| Print CV certificate description in human readable form.
int | cvc_chat_print (BIO *bio, const CVC_CHAT *chat, int indent)
| Print CHAT in human readable form.
int | cvc_chat_print_authorizations (BIO *bio, const CVC_CHAT *chat, int indent)
| Print the relative authorization contained in a CHAT in human readable form.
int | CVC_print (BIO *bio, const CVC_CERT *cv, int indent)
| Print CV certificate in human readable form.
int | certificate_request_print (BIO *bio, const CVC_CERT_REQUEST *request, int indent)
| Print CV certificate request in human readable form.
int | certificate_authentication_request_print (BIO *bio, const CVC_CERT_AUTHENTICATION_REQUEST *authentication, int indent)
| Print CV certificate authentication request in human readable form.
const CVC_CHAT * | cvc_get_chat (const CVC_CERT *cvc)
| Get the CHAT contained in a CV certifcate.
enum cvc_terminal_role | CVC_get_role (const CVC_CHAT *chat)
| Extract the terminal-type (terminal, DV, CVCA) from the CHAT.
short | CVC_get_profile_identifier (const CVC_CERT *cert)
| Return the profile identifier of a CV certificate as an integer.
char * | CVC_get_car (const CVC_CERT *cert)
| Return the CAR of a CV certificate as a string.
char * | CVC_get_chr (const CVC_CERT *cert)
| Return the CAR of a CV certificate as a string.
char * | CVC_get_effective_date (const CVC_CERT *cert)
| Convert the effective date and expiration date, of a certificate to a string.
char * | CVC_get_expiration_date (const CVC_CERT *cert)
| Convert the expiration date of a certificate to a string.
int | CVC_verify_signature (const CVC_CERT *cert, int protocol, EVP_PKEY *key)
| Verify the signature of a CV certificate using the public key of the certificate issuer.
int | CVC_verify_request_signature (const CVC_CERT_REQUEST *request)
| Verify the inner signature of a CV certificate request.
int | CVC_verify_authentication_request_signatures (struct eac_ctx *ctx, const CVC_CERT_AUTHENTICATION_REQUEST *authentication)
| Verify the inner and outer signature of a CV certificate request.
int | CVC_check_description (const CVC_CERT *cv, const unsigned char *cert_desc_in, const unsigned int cert_desc_in_len)
| Check whether or not the certificate contains the correct hash of the CV certificate description.
BUF_MEM * | CVC_hash_description (const CVC_CERT *cv, const unsigned char *cert_desc, size_t cert_desc_len)
| Create a hash over a certificate's description.

## Detailed Description

Interface for Card Verifiable Certificates.

Author
  Dominik Oepen oepen.nosp@m.@inf.nosp@m.ormat.nosp@m.ik.h.nosp@m.u-ber.nosp@m.lin..nosp@m.de
  Frank Morgner frank.nosp@m.morg.nosp@m.ner@g.nosp@m.mail.nosp@m..com

Definition in file cv_cert.h.

## Macro Definition Documentation

## ASN1_APP_EXP_OPT

#define ASN1_APP_EXP_OPT | ( |  | stname,
|  |  | field,
|  |  | type,
|  |  | tag
| ) |  | ASN1_EX_TYPE(ASN1_TFLG_EXPTAG|ASN1_TFLG_APPLICATION|ASN1_TFLG_OPTIONAL, tag, stname, field, type)

Application specific, EXPLICIT tagged, optional ASN1 type

Definition at line 70 of file cv_cert.h.

## ASN1_APP_IMP

#define ASN1_APP_IMP | ( |  | stname,
|  |  | field,
|  |  | type,
|  |  | tag
| ) |  | ASN1_EX_TYPE(ASN1_TFLG_IMPTAG|ASN1_TFLG_APPLICATION, tag, stname, field, type)

Application specific, IMPLICIT tagged ASN1 type

Definition at line 62 of file cv_cert.h.

## ASN1_APP_IMP_OPT

#define ASN1_APP_IMP_OPT | ( |  | stname,
|  |  | field,
|  |  | type,
|  |  | tag
| ) |  | ASN1_EX_TYPE(ASN1_TFLG_IMPTAG|ASN1_TFLG_APPLICATION|ASN1_TFLG_OPTIONAL, tag, stname, field, type)

Application specific, IMPLICIT tagged, optional ASN1 type

Definition at line 66 of file cv_cert.h.

## ASN1_APP_IMP_SEQUENCE_OF_OPT

#define ASN1_APP_IMP_SEQUENCE_OF_OPT | ( |  | stname,
|  |  | field,
|  |  | type,
|  |  | tag
| ) |  | ASN1_EX_TYPE(ASN1_TFLG_SEQUENCE_OF|ASN1_TFLG_IMPTAG|ASN1_TFLG_APPLICATION|ASN1_TFLG_OPTIONAL, tag, stname, field, type)

Definition at line 73 of file cv_cert.h.

## EAC_AT_CHAT_BITS

#define EAC_AT_CHAT_BITS 38

Definition at line 92 of file cv_cert.h.

## EAC_AT_CHAT_BYTES

#define EAC_AT_CHAT_BYTES 5

Definition at line 91 of file cv_cert.h.

## EAC_IS_CHAT_BITS

#define EAC_IS_CHAT_BITS 6

Definition at line 94 of file cv_cert.h.

## EAC_IS_CHAT_BYTES

#define EAC_IS_CHAT_BYTES 1

Definition at line 93 of file cv_cert.h.

## EAC_ST_CHAT_BITS

#define EAC_ST_CHAT_BITS 6

Definition at line 96 of file cv_cert.h.

## EAC_ST_CHAT_BYTES

#define EAC_ST_CHAT_BYTES 1

Definition at line 95 of file cv_cert.h.

## Typedef Documentation

## CVC_CERT

typedef CVC_CERT_SEQ CVC_CERT

Short name for CVC_CERT_SEQ.

Definition at line 216 of file cv_cert.h.

## CVC_CERT_AUTHENTICATION_REQUEST

typedef CVC_CERT_AUTHENTICATION_REQUEST_SEQ CVC_CERT_AUTHENTICATION_REQUEST

Short name for CVC_CERT_AUTHENTICATION_REQUEST_SEQ.

Definition at line 317 of file cv_cert.h.

## CVC_CERT_AUTHENTICATION_REQUEST_SEQ

typedef struct cvc_cert_authentication_request_seq_st CVC_CERT_AUTHENTICATION_REQUEST_SEQ

The authentication request, consisting of the certificate request, certificate authority reference and outer signature.

See also
  TR-03110 C.2.

## CVC_CERT_BODY

typedef CVC_CERT_BODY_SEQ CVC_CERT_BODY

Short name for CVC_CERT_BODY_SEQ.

Definition at line 201 of file cv_cert.h.

## CVC_CERT_BODY_SEQ

typedef struct cvc_cert_body_seq_st CVC_CERT_BODY_SEQ

The body of the CV certificate (without signature)

See also
  TR-03110 C.1.

## CVC_CERT_REQUEST

typedef CVC_CERT_REQUEST_SEQ CVC_CERT_REQUEST

Short name for CVC_CERT_REQUEST_SEQ.

Definition at line 299 of file cv_cert.h.

## CVC_CERT_REQUEST_BODY

typedef CVC_CERT_REQUEST_BODY_SEQ CVC_CERT_REQUEST_BODY

Short name for CVC_CERT_REQUEST_BODY_SEQ.

Definition at line 285 of file cv_cert.h.

## CVC_CERT_REQUEST_BODY_SEQ

typedef struct cvc_cert_request_body_seq_st CVC_CERT_REQUEST_BODY_SEQ

The body of the CV certificate request (without signature)

See also
  TR-03110 C.2.

## CVC_CERT_REQUEST_SEQ

typedef struct cvc_cert_request_seq_st CVC_CERT_REQUEST_SEQ

The actual certifcate request, consisting of the body and inner signature.

See also
  TR-03110 C.2.

## CVC_CERT_SEQ

typedef struct cvc_cert_seq_st CVC_CERT_SEQ

The actual certifcate, consisting of the body and a signature.

See also
  TR-03110 C.1.

## CVC_CERTIFICATE_DESCRIPTION

typedef struct cvc_certificate_description_st CVC_CERTIFICATE_DESCRIPTION

This structure holds further information about a card verifiable certificate in human readable form.

The certificate description is used by a local terminal as part of the user interaction for online authentication of a remote terminal and may be ignored by the MRTD chip.

See also
  TR-03110 C.3.1.

## CVC_CHAT

typedef CVC_CHAT_SEQ CVC_CHAT

Short name for CVC_CHAT_SEQ.

Definition at line 109 of file cv_cert.h.

## CVC_CHAT_SEQ

typedef struct cvc_chat_seq_st CVC_CHAT_SEQ

Certificate Holder Authentication Template.

See also
  TR-03110 C.1.5.

## CVC_DISCRETIONARY_DATA_TEMPLATE

typedef CVC_DISCRETIONARY_DATA_TEMPLATE_SEQ CVC_DISCRETIONARY_DATA_TEMPLATE

Short name for CVC_CERT_BODY_SEQ.

Definition at line 159 of file cv_cert.h.

## CVC_DISCRETIONARY_DATA_TEMPLATE_SEQ

typedef struct cvc_discretionary_data_template_seq_st CVC_DISCRETIONARY_DATA_TEMPLATE_SEQ

Discretionary data template, used to encode certificate extensions.

Consists of an OID and up to two hash values. This data structure is used for both possible certificate extensions.

## CVC_PUBKEY

typedef CVC_PUBKEY_BODY CVC_PUBKEY

Definition at line 138 of file cv_cert.h.

## CVC_PUBKEY_BODY

typedef struct cvc_pubkey_st CVC_PUBKEY_BODY

Public key data object which may contain domain parameters.

This data structure is used for defined public keys (RSA public key, DH public key, EC public key).

See also
  TR-03110 D.3.

## Enumeration Type Documentation

## cvc_terminal_role

enum cvc_terminal_role

Effective role of the certificate holder.

Enumerator
CVC_Terminal | Terminal (inspection system/authentication terminal/signature terminal)
CVC_DocVer | Document Verifier (non-official/foreign)
CVC_DV | Document Verifier (official domestic)
CVC_CVCA | Country Verifying Certificate Authority.

Definition at line 78 of file cv_cert.h.

## Function Documentation

## CVC_check_description()

int CVC_check_description | ( | const CVC_CERT * | cv,
|  | const unsigned char * | cert_desc_in,
|  | const unsigned int | cert_desc_in_len
| ) |  |

Check whether or not the certificate contains the correct hash of the CV certificate description.

Parameters

  [in] | cv | CV certificate
  [in] | cert_desc_in | ASN1 representation of the CV certificate description
  [in] | cert_desc_in_len | Length of cvc_desc_in

Returns
  1 if the certificate contains the correct hash, 0 if not or -1 in case of an error.

## CVC_get_car()

char * CVC_get_car | ( | const CVC_CERT * | cert | ) |

Return the CAR of a CV certificate as a string.

Parameters

  [in] | cert | The certificate from which we want to return the CAR

Returns
  CAR string or NULL in case of an error

Note
  Result should be freed with `OpenSSL_free()`

## cvc_get_chat()

const CVC_CHAT * cvc_get_chat | ( | const CVC_CERT * | cvc | ) |

Get the CHAT contained in a CV certifcate.

Parameters

  [in] | cvc | CV certificate

Returns
  Pointer to the CHAT of cvc or NULL in case of an error

## CVC_get_chr()

char * CVC_get_chr | ( | const CVC_CERT * | cert | ) |

Return the CAR of a CV certificate as a string.

Parameters

  [in] | cert | The certificate from which we want to return the CHR

Returns
  CHR string or NULL in case of an error

Note
  Result should be freed with `OpenSSL_free()`

## CVC_get_effective_date()

char * CVC_get_effective_date | ( | const CVC_CERT * | cert | ) |

Convert the effective date and expiration date, of a certificate to a string.

Parameters

  [in] | cert | The certificate

Returns
  Null terminated string representation of the date

Note
  Result should be freed with `OpenSSL_free()`

## CVC_get_expiration_date()

char * CVC_get_expiration_date | ( | const CVC_CERT * | cert | ) |

Convert the expiration date of a certificate to a string.

Parameters

  [in] | cert | The certificate

Returns
  Null terminated string representation of the date or NULL in case of an error

Note
  Result should be freed with `OpenSSL_free()`

## CVC_get_profile_identifier()

short CVC_get_profile_identifier | ( | const CVC_CERT * | cert | ) |

Return the profile identifier of a CV certificate as an integer.

Parameters

  [in] | cert | The certificate from which we want to return the profile identifier

Returns
  The profile identifier or -1 in case of an error

## CVC_get_role()

enum cvc_terminal_role CVC_get_role | ( | const CVC_CHAT * | chat | ) |

Extract the terminal-type (terminal, DV, CVCA) from the CHAT.

Parameters

  [in] | chat | CHAT

Returns
  -1 in case of an error or one of the following values:
  - `CVC_CVCA` (CVCA certificate)
  - `CVC_DV` (DVCA certificate)
  - `CVC_DocVer` (DVCA certificate)
  - `CVC_Terminal` (terminal certificate)

## CVC_hash_description()

BUF_MEM * CVC_hash_description | ( | const CVC_CERT * | cv,
|  | const unsigned char * | cert_desc,
|  | size_t | cert_desc_len
| ) |  |

Create a hash over a certificate's description.

Parameters

  [in] | cv | CV certificate
  [in] | cert_desc_in | ASN1 representation of the CV certificate description
  [in] | cert_desc_in_len | Length of cvc_desc_in

Returns
  hashed description or NULL in case of an error.

## CVC_verify_authentication_request_signatures()

int CVC_verify_authentication_request_signatures | ( | struct eac_ctx * | ctx,
|  | const CVC_CERT_AUTHENTICATION_REQUEST * | authentication
| ) |  |

Verify the inner and outer signature of a CV certificate request.

Parameters

  [in,out] | ctx | EAC context
  [in] | authentication | CV certificate request to verify

Returns
  1 if the signatures were verified, 0 if not and a negative value in case of an error.

## CVC_verify_request_signature()

int CVC_verify_request_signature | ( | const CVC_CERT_REQUEST * | request | ) |

Verify the inner signature of a CV certificate request.

Parameters

  [in] | request | CV certificate request to verify

Returns
  1 if the signature was verified, 0 if not and a negative value in case of an error.

## CVC_verify_signature()

int CVC_verify_signature | ( | const CVC_CERT * | cert,
|  | int | protocol,
|  | EVP_PKEY * | key
| ) |  |

Verify the signature of a CV certificate using the public key of the certificate issuer.

Parameters

  [in] | cert | CV certificate to verify
  [in] | protocol | Mechanism for verification
  [in] | key | Public key used for verification

Returns
  1 if the signature was verified, 0 if not and a negative value in case of an error.