OpenPACE: eac/eac.h Source File

OpenPACE

eac.h
Go to the documentation of this file.
1 /*
2 * Copyright (c) 2010-2012 Frank Morgner and Dominik Oepen
3 *
4 * This file is part of OpenPACE.
5 *
6 * OpenPACE is free software: you can redistribute it and/or modify it under
7 * the terms of the GNU General Public License as published by the Free
8 * Software Foundation, either version 3 of the License, or (at your option)
9 * any later version.
10 *
11 * OpenPACE is distributed in the hope that it will be useful, but WITHOUT ANY
12 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
13 * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
14 * details.
15 *
16 * You should have received a copy of the GNU General Public License along with
17 * OpenPACE. If not, see <http://www.gnu.org/licenses/>.
18 *
19 * Additional permission under GNU GPL version 3 section 7
20 *
21 * If you modify this Program, or any covered work, by linking or combining it
22 * with OpenSSL (or a modified version of that library), containing
23 * parts covered by the terms of OpenSSL's license, the licensors of
24 * this Program grant you additional permission to convey the resulting work.
25 * Corresponding Source for a non-source form of such a combination shall include
26 * the source code for the parts of OpenSSL used as well as that of the
27 * covered work.
28 *
29 * If you modify this Program, or any covered work, by linking or combining it
30 * with OpenSC (or a modified version of that library), containing
31 * parts covered by the terms of OpenSC's license, the licensors of
32 * this Program grant you additional permission to convey the resulting work.
33 * Corresponding Source for a non-source form of such a combination shall include
34 * the source code for the parts of OpenSC used as well as that of the
35 * covered work.
36 */
37
46 #ifndef EAC_H_
47 #define EAC_H_
48
49 #ifdef __cplusplus
50 extern "C" {
51 #endif
52
53 #include <eac/cv_cert.h>
54 #include <eac/objects.h>
55 #include <openssl/asn1.h>
56 #include <openssl/buffer.h>
57 #include <openssl/cmac.h>
58 #include <openssl/ec.h>
59 #include <openssl/evp.h>
60
81 enum eac_tr_version {
83 EAC_TR_VERSION = 0,
85 EAC_TR_VERSION_2_01,
87 EAC_TR_VERSION_2_02,
88 };
89
95 typedef struct ka_ctx {
97 const EVP_MD * md;
99 ENGINE * md_engine;
101 CMAC_CTX * cmac_ctx;
103 const EVP_CIPHER * cipher;
105 ENGINE * cipher_engine;
107 unsigned char * iv;
109 int mac_keylen;
111 int enc_keylen;
112
121 BUF_MEM * (*generate_key)(EVP_PKEY *key, BN_CTX *bn_ctx);
131 BUF_MEM * (*compute_key)(EVP_PKEY *key, const BUF_MEM *in, BN_CTX *bn_ctx);
132
134 EVP_PKEY *key;
135
137 BUF_MEM *shared_secret;
139 BUF_MEM *k_enc;
141 BUF_MEM *k_mac;
142 } KA_CTX;
143
146 typedef struct pace_ctx {
172 int protocol;
174 unsigned char version;
176 int id;
180 BUF_MEM * (*map_generate_key)(const struct pace_ctx *ctx, BN_CTX *bn_ctx);
184 int (*map_compute_key)(struct pace_ctx * ctx, const BUF_MEM * s,
185 const BUF_MEM * in, BN_CTX *bn_ctx);
186
188 EVP_PKEY *static_key;
190 KA_CTX *ka_ctx;
192 BUF_MEM *nonce;
194 BUF_MEM *my_eph_pubkey;
195 } PACE_CTX;
196
199 typedef struct ri_ctx {
215 int protocol;
217 int id;
219 const EVP_MD * md;
228 BUF_MEM * (*generate_key)(EVP_PKEY *key, BN_CTX *bn_ctx);
238 BUF_MEM * (*compute_key)(EVP_PKEY *key, const BUF_MEM *in, BN_CTX *bn_ctx);
240 EVP_PKEY *static_key;
241 } RI_CTX;
242
244 typedef CVC_CERT * (*CVC_lookup_cvca_cert) (const unsigned char *chr, size_t car_len);
245
247 typedef struct ta_ctx {
249 unsigned char version;
266 int protocol;
268 ENGINE *key_engine;
270 EVP_PKEY *priv_key;
272 EVP_PKEY *pub_key;
274 BUF_MEM *pk_pcd;
276 BUF_MEM *nonce;
278 CVC_CERT *trust_anchor;
280 CVC_CERT *current_cert;
282 CVC_CERT *new_trust_anchor;
288 int flags;
289
297 CVC_lookup_cvca_cert lookup_cvca_cert;
298 } TA_CTX;
299
301 typedef X509_STORE * (*X509_lookup_csca_cert) (unsigned long issuer_name_hash);
302
304 typedef struct ca_ctx {
306 unsigned char version;
319 int protocol;
321 int id;
327 int flags;
329 KA_CTX *ka_ctx;
330
338 X509_lookup_csca_cert lookup_csca_cert;
339 } CA_CTX;
340
342 typedef struct eac_ctx {
344 enum eac_tr_version tr_version;
346 BN_CTX * bn_ctx;
348 EVP_MD_CTX * md_ctx;
350 EVP_CIPHER_CTX * cipher_ctx;
354 PACE_CTX *pace_ctx;
356 STACK_OF(PACE_CTX *) pace_ctxs;
360 RI_CTX *ri_ctx;
362 STACK_OF(RI_CTX *) ri_ctxs;
364 TA_CTX *ta_ctx;
368 CA_CTX *ca_ctx;
370 STACK_OF(CA_CTX *) ca_ctxs;
372 KA_CTX *key_ctx;
374 BIGNUM *ssc;
375 } EAC_CTX;
376
378 #define EAC_AES_MAC_LENGTH 8
379
390 void EAC_init(void);
391
395 void EAC_cleanup(void);
396
401 EAC_CTX *
402 EAC_CTX_new(void);
403
411 void EAC_CTX_clear_free(EAC_CTX *ctx);
412
424 int
425 EAC_CTX_init_pace(EAC_CTX *ctx, int protocol, int curve);
426
439 int
440 EAC_CTX_init_ta(const EAC_CTX *ctx,
441 const unsigned char *privkey, size_t privkey_len,
442 const unsigned char *cvca, size_t cvca_len);
443
455 int EAC_CTX_init_ca(EAC_CTX *ctx, int protocol, int curve);
456
468 int
469 EAC_CTX_init_ri(EAC_CTX *ctx, int protocol, int stnd_dp);
470
481 int EAC_CTX_init_ef_cardaccess(unsigned const char * in, size_t in_len,
482 EAC_CTX *ctx);
483
496 int EAC_CTX_init_ef_cardsecurity(
497 const unsigned char *ef_cardsecurity, size_t ef_cardsecurity_len,
498 EAC_CTX *ctx);
499
508 int EAC_CTX_get_cvca_lookup(const EAC_CTX *ctx, CVC_lookup_cvca_cert *lookup_cvca_cert);
517 int EAC_CTX_set_cvca_lookup(EAC_CTX *ctx, CVC_lookup_cvca_cert lookup_cvca_cert);
529 CVC_lookup_cvca_cert EAC_get_default_cvca_lookup(void);
530
536 void EAC_set_cvc_default_dir(const char *default_dir);
537
546 int EAC_CTX_get_csca_lookup_cert(const EAC_CTX *ctx, X509_lookup_csca_cert *lookup_cvca_cert);
555 int EAC_CTX_set_csca_lookup_cert(EAC_CTX *ctx, X509_lookup_csca_cert lookup_cvca_cert);
564 X509_lookup_csca_cert EAC_get_default_csca_lookup(void);
565
571 void EAC_set_x509_default_dir(const char *default_dir);
572
590 BUF_MEM *
591 EAC_add_iso_pad(const EAC_CTX *ctx, const BUF_MEM * unpadded);
599 BUF_MEM *
600 EAC_remove_iso_pad(const BUF_MEM * padded);
601
609 int EAC_increment_ssc(const EAC_CTX *ctx);
610
618 int EAC_reset_ssc(const EAC_CTX *ctx);
627 int EAC_set_ssc(const EAC_CTX *ctx, unsigned long ssc);
628
639 BUF_MEM *
640 EAC_encrypt(const EAC_CTX *ctx, const BUF_MEM *data);
641
652 BUF_MEM *
653 EAC_decrypt(const EAC_CTX *ctx, const BUF_MEM *data);
654
665 BUF_MEM *
666 EAC_authenticate(const EAC_CTX *ctx, const BUF_MEM *data);
676 int
677 EAC_verify_authentication(const EAC_CTX *ctx, const BUF_MEM *data,
678 const BUF_MEM *mac);
679
689 BUF_MEM *
690 EAC_Comp(const EAC_CTX *ctx, int id, const BUF_MEM *pub);
691
703 BUF_MEM *
704 EAC_hash_certificate_description(const unsigned char *cert_desc,
705 size_t cert_desc_len);
706
708 #define EAC_ID_PACE 0
709
710 #define EAC_ID_CA 1
711
712 #define EAC_ID_TA 2
713
714 #define EAC_ID_EAC 3
715
726 int
727 EAC_CTX_set_encryption_ctx(EAC_CTX *ctx, int id);
728
745 int EAC_CTX_print_private(BIO *out, const EAC_CTX *ctx, int indent);
755 int BUF_MEM_print(BIO *out, const BUF_MEM *buf, int indent);
756
765 void
766 BUF_MEM_clear_free(BUF_MEM *b);
767
769 #ifdef __cplusplus
770 }
771 #endif
772 #endif
ka_ctx::cipher_engine
ENGINE * cipher_engine
Cipher's engine.
Definition: eac.h:105
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.
EAC_CTX_init_ri
int EAC_CTX_init_ri(EAC_CTX *ctx, int protocol, int stnd_dp)
Initialize an EAC context for Restricted Identification.
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.
eac_ctx::ta_ctx
TA_CTX * ta_ctx
Context for the currently selected Terminal Authentication protocol.
Definition: eac.h:364
ka_ctx::md_engine
ENGINE * md_engine
Digest's engine.
Definition: eac.h:99
BUF_MEM_print
int BUF_MEM_print(BIO *out, const BUF_MEM *buf, int indent)
Prints buffer.
EAC_CTX_print_private
int EAC_CTX_print_private(BIO *out, const EAC_CTX *ctx, int indent)
Print EAC context including private data.
EAC_cleanup
void EAC_cleanup(void)
Wrapper to EVP_cleanup()
EAC_set_cvc_default_dir
void EAC_set_cvc_default_dir(const char *default_dir)
Set directory for EAC_get_default_cvca_lookup()
pace_ctx::id
int id
identifier of this PACE context
Definition: eac.h:176
eac_ctx::ca_ctx
CA_CTX * ca_ctx
Context for the currently selected Chip Authentication protocol.
Definition: eac.h:368
EAC_CTX_init_pace
int EAC_CTX_init_pace(EAC_CTX *ctx, int protocol, int curve)
Initialize an EAC context for PACE.
eac_ctx::bn_ctx
BN_CTX * bn_ctx
Context for various operations with BIGNUM objects.
Definition: eac.h:346
EAC_set_x509_default_dir
void EAC_set_x509_default_dir(const char *default_dir)
Set directory for EAC_get_default_csca_lookup()
ta_ctx::trust_anchor
CVC_CERT * trust_anchor
Trust anchor for CV certificate validation.
Definition: eac.h:278
TA_CTX
struct ta_ctx TA_CTX
Context for the Terminal Authentication protocol.
eac_tr_version
eac_tr_version
Identification of the specifications to use.
Definition: eac.h:81
ka_ctx::k_mac
BUF_MEM * k_mac
Symmetric key used for integrity protection. Derived from KA_CTX.shared_secret.
Definition: eac.h:141
ri_ctx
Context for the Restricted Identification protocol.
Definition: eac.h:199
EAC_authenticate
BUF_MEM * EAC_authenticate(const EAC_CTX *ctx, const BUF_MEM *data)
Authenticate data according to TR-03110 F.2.
CA_CTX
struct ca_ctx CA_CTX
Context for the Chip Authentication protocol.
objects.h
Definitions of object identifiers.
eac_ctx::ri_ctx
RI_CTX * ri_ctx
Context for the currently selected Restricted Identification protocol.
Definition: eac.h:360
EAC_increment_ssc
int EAC_increment_ssc(const EAC_CTX *ctx)
Increment the Send Sequence Counter.
EAC_add_iso_pad
BUF_MEM * EAC_add_iso_pad(const EAC_CTX *ctx, const BUF_MEM *unpadded)
Pad a buffer using ISO/IEC 9797-1 padding method 2.
ta_ctx::pk_pcd
BUF_MEM * pk_pcd
PCD's public key extracted from it's CV certificate.
Definition: eac.h:274
PACE_CTX
struct pace_ctx PACE_CTX
Context for the Password Authenticated Connection Establishment protocol.
cvc_cert_seq_st
The actual certifcate, consisting of the body and a signature.
Definition: cv_cert.h:209
EAC_Comp
BUF_MEM * EAC_Comp(const EAC_CTX *ctx, int id, const BUF_MEM *pub)
Compresse a public key according to TR-03110 Table A.2.
pace_ctx::protocol
int protocol
Identifier of the protocol's OID specifying the exact PACE parameters to use.
Definition: eac.h:172
ca_ctx
Context for the Chip Authentication protocol.
Definition: eac.h:304
EAC_get_default_cvca_lookup
CVC_lookup_cvca_cert EAC_get_default_cvca_lookup(void)
Return the default lookup of the country verifying CA.
ca_ctx::version
unsigned char version
(currently unused) Version of the CA protocol, MUST be 1 or 2
Definition: eac.h:306
cv_cert.h
Interface for Card Verifiable Certificates.
eac_ctx::key_ctx
KA_CTX * key_ctx
Context for currently selected secure messaging established with PACE or CA.
Definition: eac.h:372
eac_ctx::ssc
BIGNUM * ssc
Send sequence counter.
Definition: eac.h:374
RI_CTX
struct ri_ctx RI_CTX
Context for the Restricted Identification protocol.
EAC_set_ssc
int EAC_set_ssc(const EAC_CTX *ctx, unsigned long ssc)
Set the Send Sequence Counter.
pace_ctx::version
unsigned char version
(currently unused) Version of the PACE protocol, MUST be 1 or 2
Definition: eac.h:174
EAC_CTX
struct eac_ctx EAC_CTX
Context for the Extended Access Control protocol.
ta_ctx::new_trust_anchor
CVC_CERT * new_trust_anchor
When a complete CV certificate chain has been verified, this will be the new trust anchor.
Definition: eac.h:282
ri_ctx::md
const EVP_MD * md
Digest to use for derivation of I^{sector}_{ID}.
Definition: eac.h:219
ta_ctx::protocol
int protocol
Identifier of the protocol's OID specifying the exact TA parameters to use.
Definition: eac.h:266
eac_ctx::STACK_OF
STACK_OF(PACE_CTX *) pace_ctxs
stack of available Password Authenticated Connection Establishment configurations
EAC_get_default_csca_lookup
X509_lookup_csca_cert EAC_get_default_csca_lookup(void)
Return the default lookup of the country signing CA.
EAC_TR_VERSION_2_02
@ EAC_TR_VERSION_2_02
Perform EAC according to TR-03110 v2.02 and later.
Definition: eac.h:87
ta_ctx::current_cert
CVC_CERT * current_cert
Most recent verified CV certificate in a certificate chain.
Definition: eac.h:280
ca_ctx::flags
int flags
Flags to control some of the behaviour of the CA.
Definition: eac.h:327
EAC_init
void EAC_init(void)
Initializes OpenSSL and the EAC identifier.
pace_ctx
Context for the Password Authenticated Connection Establishment protocol.
Definition: eac.h:146
ka_ctx
Context for a key agreement and subsequent derivation of session keys.
Definition: eac.h:95
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...
EAC_CTX_new
EAC_CTX * EAC_CTX_new(void)
Create a new EAC context.
ka_ctx::k_enc
BUF_MEM * k_enc
Symmetric key used for encryption/decryption. Derived from KA_CTX.shared_secret.
Definition: eac.h:139
eac_ctx::md_ctx
EVP_MD_CTX * md_ctx
Context for various hashing operations.
Definition: eac.h:348
ta_ctx::nonce
BUF_MEM * nonce
PICC's challenge.
Definition: eac.h:276
EAC_TR_VERSION_2_01
@ EAC_TR_VERSION_2_01
Perform EAC according to TR-03110 v2.01.
Definition: eac.h:85
EAC_encrypt
BUF_MEM * EAC_encrypt(const EAC_CTX *ctx, const BUF_MEM *data)
Encrypts data according to TR-03110 F.2.
eac_ctx::pace_ctx
PACE_CTX * pace_ctx
Context for the currently selected Password Authenticated Connection Establishment protocol.
Definition: eac.h:354
KA_CTX
struct ka_ctx KA_CTX
Context for a key agreement and subsequent derivation of session keys.
EAC_TR_VERSION
@ EAC_TR_VERSION
Undefined type, if nothing else matches.
Definition: eac.h:83
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.
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.
BUF_MEM_clear_free
void BUF_MEM_clear_free(BUF_MEM *b)
Frees and wipes a buffer.
EAC_decrypt
BUF_MEM * EAC_decrypt(const EAC_CTX *ctx, const BUF_MEM *data)
Decrypt data according to TR-03110 F.2.
EAC_hash_certificate_description
BUF_MEM * EAC_hash_certificate_description(const unsigned char *cert_desc, size_t cert_desc_len)
Compute the hash of a CV certificate description.
eac_ctx
Context for the Extended Access Control protocol.
Definition: eac.h:342
ca_ctx::protocol
int protocol
Identifier of the protocol's OID specifying the exact CA parameters to use.
Definition: eac.h:319
pace_ctx::my_eph_pubkey
BUF_MEM * my_eph_pubkey
The own ephemeral public key generated in PACe step 3b.
Definition: eac.h:194
ka_ctx::iv
unsigned char * iv
Initialisation vector for encryption/decryption.
Definition: eac.h:107
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.
ri_ctx::static_key
EVP_PKEY * static_key
PICC's static domain parameters.
Definition: eac.h:240
EAC_CTX_clear_free
void EAC_CTX_clear_free(EAC_CTX *ctx)
Free an EAC context.
ri_ctx::id
int id
identifier of this RI context
Definition: eac.h:217
X509_lookup_csca_cert
X509_STORE *(* X509_lookup_csca_cert)(unsigned long issuer_name_hash)
callback for finding the X.509 trust anchor
Definition: eac.h:301
ca_ctx::ka_ctx
KA_CTX * ka_ctx
Key agreement object used with the PICC's private key.
Definition: eac.h:329
ta_ctx::version
unsigned char version
(currently unused) Version of the TA protocol, MUST be 1 or 2
Definition: eac.h:249
ka_ctx::enc_keylen
int enc_keylen
Length of the computed key for the encryption/decryption.
Definition: eac.h:111
EAC_CTX_init_ca
int EAC_CTX_init_ca(EAC_CTX *ctx, int protocol, int curve)
Initialize an EAC context for Chip Authentication.
ri_ctx::protocol
int protocol
Identifier of the hash function to use.
Definition: eac.h:215
eac_ctx::tr_version
enum eac_tr_version tr_version
Perform EAC conforming to this version of TR-03110.
Definition: eac.h:344
ca_ctx::id
int id
identifier of this CA context
Definition: eac.h:321
ka_ctx::shared_secret
BUF_MEM * shared_secret
Shared secret computed during the key agreement protocol.
Definition: eac.h:137
ka_ctx::cipher
const EVP_CIPHER * cipher
Cipher to use for encryption/decryption.
Definition: eac.h:103
ca_ctx::lookup_csca_cert
X509_lookup_csca_cert lookup_csca_cert
callback for finding the X.509 trust anchor
Definition: eac.h:338
ta_ctx::flags
int flags
Flags to control some of the behaviour of the CA.
Definition: eac.h:288
ka_ctx::key
EVP_PKEY * key
Container for the key pair used for key agreement.
Definition: eac.h:134
ka_ctx::mac_keylen
int mac_keylen
Length of the computed key for the message authentication code.
Definition: eac.h:109
EAC_remove_iso_pad
BUF_MEM * EAC_remove_iso_pad(const BUF_MEM *padded)
Remove ISO/IEC 9797-1 padding method 2 from a message.
EAC_verify_authentication
int EAC_verify_authentication(const EAC_CTX *ctx, const BUF_MEM *data, const BUF_MEM *mac)
Verify authenticated data according to TR-03110 F.2.
EAC_reset_ssc
int EAC_reset_ssc(const EAC_CTX *ctx)
Reset the Send Sequence Counter.
ta_ctx::key_engine
ENGINE * key_engine
(currently unused) engine for signing and signature verification
Definition: eac.h:268
ka_ctx::md
const EVP_MD * md
Digest to use for key derivation.
Definition: eac.h:97
pace_ctx::ka_ctx
KA_CTX * ka_ctx
Key agreement object used with the ephemeral domain parameters.
Definition: eac.h:190
pace_ctx::static_key
EVP_PKEY * static_key
PICC's static domain parameters.
Definition: eac.h:188
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.
ta_ctx::priv_key
EVP_PKEY * priv_key
TA private key used for signing the challenge.
Definition: eac.h:270
ka_ctx::cmac_ctx
CMAC_CTX * cmac_ctx
Context for CMAC.
Definition: eac.h:101
ta_ctx::lookup_cvca_cert
CVC_lookup_cvca_cert lookup_cvca_cert
Lookup the CVCA trust anchor.
Definition: eac.h:297
eac_ctx::cipher_ctx
EVP_CIPHER_CTX * cipher_ctx
Context for various cipher operations.
Definition: eac.h:350
ta_ctx
Context for the Terminal Authentication protocol.
Definition: eac.h:247
ta_ctx::pub_key
EVP_PKEY * pub_key
TA public key used for signing the challenge.
Definition: eac.h:272
pace_ctx::map_compute_key
int(* map_compute_key)(struct pace_ctx *ctx, const BUF_MEM *s, const BUF_MEM *in, BN_CTX *bn_ctx)
Points to the implementation of a specific mapping.
Definition: eac.h:184
EAC_CTX_set_encryption_ctx
int EAC_CTX_set_encryption_ctx(EAC_CTX *ctx, int id)
Set the SM context for encryption, decryption and authentication.
CVC_lookup_cvca_cert
CVC_CERT *(* CVC_lookup_cvca_cert)(const unsigned char *chr, size_t car_len)
callback for finding the CVCA trust anchor
Definition: eac.h:244
pace_ctx::nonce
BUF_MEM * nonce
PICC's decrypted challenge generated in PACE step 1.
Definition: eac.h:192