ePass Module

class virtualsmartcard.cards.ePass.PassportSAM(mf)

Bases: virtualsmartcard.SmartcardSAM.SAM

SAM for ICAO ePassport. Implements Basic access control and key derivation for Secure Messaging.

FSdecrypt(data)

Decrypt the given data, using the parameters stored in the SAM. Right now we do not encrypt the data. In memory encryption might or might not be added in a future version.

FSencrypt(data)

Encrypt the given data, using the parameters stored in the SAM. Right now we do not encrypt the data. In memory encryption might or might not be added in a future version.

__computeKeys()

Computes the keys depending on the machine readable zone of the passport according to TR-PKI mrtds ICC read-only access v1.1 annex E.1.

_get_referenced_key(p1, p2)

This method returns the key specified by the p2 parameter. The key may be stored on the cards filesystem.

Parameters

• p1 – Specifies the algorithm to use.

• p2 –

  Specifies a reference to the key to be used for encryption.

  b8	b7	b6	b5	b4	b3	b2	b1	Meaning
  0	0	0	0	0	0	0	0	No information is given
  0								Global reference data(e.g. MF specific key)
  1								Specific reference data(e.g. DF specific key)
  			x	x	x	x	x	Number of the secret

  Any other value RFU

change_reference_data(p1, p2, data)

Change the specified referenced data (e.g. CHV) of the card

static derive_key(seed, c)

Derive a key according to TR-PKI mrtds ICC read-only access v1.1 annex E.1. c is either 1 for encryption or 2 for MAC computation. Returns: Ka + Kb Note: Does not adjust parity. Nobody uses that anyway …

erase_SE(SEID)

Erases a Security Environment stored under SEID from the SAM

external_authenticate(p1, p2, resp_data)

Performs the basic access control protocol as defined in the ICAO MRTD standard

generate_public_key_pair(p1, p2, data)

get_card_number()

get_challenge(p1, p2, data)

Generate a random number of maximum 8 Byte and return it.

internal_authenticate(p1, p2, data)

Authenticate card to terminal. Encrypt the challenge of the terminal to prove key posession

manage_security_environment(p1, p2, data)

mutual_authenticate(p1, p2, mutual_challenge)

Takes an encrypted challenge in the form ‘Terminal Challenge | Card Challenge | Card number’ and checks it for validity. If the challenge is successful the card encrypts ‘Card Challenge | Terminal challenge’ and returns this value

parse_SM_CAPDU(CAPDU, header_authentication)

Parse a command APDU protected by Secure Messaging and return the unprotected command APDU

perform_security_operation(p1, p2, data)

protect_result(sw, unprotected_result)

Protect a plain response APDU by Secure Messaging

restore_SE(SEID)

Restores a Security Environment from the SAM and replaces the current SE with it.

set_MF(mf)

Setter function for the internal reference to the Filesystem. The SAM needs a reference to the filesystem in order to store/retrieve keys.

set_asym_algorithm(cipher, keytype)

Parameters

• cipher – Public/private key object from used for encryption

• keytype – Type of the public key (e.g. RSA, DSA)

store_SE(SEID)

Stores the current Security environment in the secure access module. The SEID is used as a reference to identify the SE.

verify(p1, p2, PIN)

Authenticate the card user. Check if he entered a valid PIN. If the PIN is invalid decrement retry counter. If retry counter equals zero, block the card until reset with correct PUK

class virtualsmartcard.cards.ePass.ePass_SE(MF, SAM, ssc=None)

Bases: virtualsmartcard.SEutils.Security_Environment

This class implements the Security Environment of the ICAO Passports. It is required in order to use the send sequence counter for secure messaging.

_set_SE(p2, data)

Manipulate the current Security Environment. P2 is the tag of a control reference template, data contains control reference objects

compute_cryptographic_checksum(p1, p2, data)

Compute a cryptographic checksum (e.g. MAC) for the given data. The ePass uses a Send Sequence Counter for MAC calculation

compute_digital_signature(p1, p2, data)

Compute a digital signature for the given data. Algorithm and key are specified in the current SE

Parameters

• p1 – Must be 0x9E = Secure Messaging class for digital signatures

• p2 – Must be one of 0x9A, 0xAC, 0xBC. Indicates what kind of data is included in the data field.

decipher(p1, p2, data)

Decipher data using key, algorithm, IV and Padding specified by the current Security environment.

Returns

raw data (no TLV coding). Padding is not removed!!!

encipher(p1, p2, data)

Encipher data using key, algorithm, IV and Padding specified by the current Security environment.

Returns

raw data (no TLV coding).

generate_public_key_pair(p1, p2, data)

The GENERATE PUBLIC-KEY PAIR command either initiates the generation and storing of a key pair, i.e., a public key and a private key, in the card, or accesses a key pair previously generated in the card.

Parameters

• p1 – should be 0x00 (generate new key)

• p2 – ‘00’ (no information provided) or reference of the key to be generated

• data – One or more CRTs associated to the key generation if P1-P2 different from ‘0000’

hash(p1, p2, data)

Hash the given data using the algorithm specified by the current Security environment.

Returns

raw data (no TLV coding).

manage_security_environment(p1, p2, data)

This method is used to store, restore or erase Security Environments or to manipulate the various parameters of the current SE. P1 specifies the operation to perform, p2 is either the SEID for the referred SE or the tag of a control reference template

Parameters

p1 –

Bitmask according to this table

b8	b7	b6	b5	b4	b3	b2	b1	Meaning
			1					Secure messaging in command data field
		1						Secure messaging in response data field
	1							Computation, decipherment, internal authentication and key agreement
1								Verification, encipherment, external authentication and key agreement
				0	0	0	1	SET
1	1	1	1	0	0	1	0	STORE
1	1	1	1	0	0	1	1	RESTORE
1	1	1	1	0	1	0	0	ERASE

parse_SM_CAPDU(CAPDU, authenticate_header)

This methods parses a data field including Secure Messaging objects. SM_header indicates whether or not the header of the message shall be authenticated. It returns an unprotected command APDU

Parameters

• CAPDU – The protected CAPDU to be parsed

• authenticate_header – Whether or not the header should be included in authentication mechanisms

Returns

Unprotected command APDU

perform_security_operation(p1, p2, data)

In the end this command is nothing but a big switch for all the other commands in ISO 7816-8. It will invoke the appropriate command and return its result

protect_response(sw, result)

This method protects a response APDU using secure messaging mechanisms

Returns

the protected data and the SW bytes

verify_certificate(p1, p2, data)

Verify a certificate send by the terminal using the internal trust anchors. This method is currently not implemented.

verify_cryptographic_checksum(p1, p2, data)

Verify the cryptographic checksum contained in the data field. Data field must contain a cryptographic checksum (tag 0x8E) and a plain value (tag 0x80)

verify_digital_signature(p1, p2, data)

Verify the digital signature contained in the data field. Data must contain a data to sign (tag 0x9A, 0xAC or 0xBC) and a digital signature (0x9E)