Keys

WARNING about correct keying

Caution

Too many tries (usually 3 or 10) with incorrect keys can irreversibly lock (brick) your card!

The gp command line tool (and all command samples) use the 40..4F test key by default (equivalent of specifying -key default from the command line). This is convenient for development and testing, as one does not need to specify the key information repeatedly, which facilitates simple and easy command line usage. For real life cards and real life usage scenarios you probably need to use real, per-card keys.

Warning

If you do not have the keys, do not ask for help on Github, but ask your card vendor for the keys instead. Only the card vendor can help you.

Plaintext keys

In order to interact with the card manager SCP01, SCP02, or SCP03 secure channels, you'll need three keys:

• ENC (Encryption Key)
• MAC (Messange AUthentication Code Key)
• DEK (Decryption Key)

However, if you're in possesion of such keys and they are noticeably different from each other - use the CLI to specify them as such:

• -key-enc
• -key-mac
• -key-dek

If however a single key is used for all three purposes (ie. as is such with the default test key 40..4F), use -key to specify it.

Alternatively set the keys using environment variables:

• $GP_KEY_ENC
• $GP_KEY_MAC
• $GP_KEY_DEK
• $GP_KEY (for a single key)

Environment variables will be overwritten whenever stricly specified by the CLI (as in: -key-enc, -key-mac, -key-dek)

Diversification

In order to ensure robust security features, each card should have different keys. This process is achieved by Key Diversitifcation - which derives unique per-card keys from a derived master key and incorporating unique card-specific data to each element.

GPPro supports a bunch of key diversification methods out of the box. To use a master key with a key derivation function, specify the known KDF before the key:

gp -key emv:default # diversify 40..4F key with EMV method with key derivation data from INITIALIZE UPDATE response
gp -key emv:404142434445464748494a4b4c4d4e4f # same as above. 'default' is shorthand for the default key bytes
gp -key visa2:47454D5850524553534F53414D504C45 # use visa2 diversification with the well-known sample key for Gemalto cards
gp -key kdf3:101112131415161718191a1b1c1d1e1f202122232425262728292a2b2c2d2e2f # use the SCP03 KDF3 method with an AES-256 master key

While INITIALIZE UPDATE command includes key diversification data in the response, unique input can be chosen by card issuer - it could be the full name of the cardholder or something printed onto the card, for example. Similarly, the cryptographic algorithms and methods of shuffling and combining the card-specific data with some key type constants, is not strictly standardised. There are well known methods and also proprietary methods (security through obscurity). Thus, even if you know the master key but not the diversification method, it might not be very useful.

Note

If you do not know the diversification algorithm, do not ask for help, but ask your card vendor for information and specification. Only the card vendor can help you.

Diversification templates (next feature)

Diversification template can contain variables that are expanded based on the key type and diversification data returned by the card and hex literals.

• $0..$f - positional data from the INITIALIZE UPDATE command response (KDD, Key Diversification Data)
• $k - key type indicator (0x01 for ENC, 0x02 for MAC, 0x03 for DEK)
• $l$l - derived key length in bits, on two bytes (SCP03 only)
• $_ - location of 8 bit counter (SCP03 only)
• 0xFF or FF - hex constant

Whitespace and any '0x' in front of literal hex is removed. A valid template that can be provided with --key-kdf looks like this (EMV):

--key-kdf '$4 $5 $6 $7 $8 $9 0xF0 $k $4 $5 $6 $7 $8 $9 0x0F $k'

Tip

Be sure to use single quotes when specifying the KDF template, so that shell would not interpret the $ symbols!

The master key and diversification template can also be set in environment variables $GP_KEY and $GP_KEY_KDF.

These diversification schemes are built into GlobalPlatformPro and can be used by name:

Name	Template
emv	$4 $5 $6 $7 $8 $9 0xF0 $k $4 $5 $6 $7 $8 $9 0x0F $k
visa2	$0 $1 $4 $5 $6 $7 0xF0 $k $0 $1 $4 $5 $6 $7 0x0F $k
visa	$0 $1 $2 $3 $8 $9 0xF0 $k $0 $1 $2 $3 $8 $9 0x0F $k
kdf3	$_ 0x00 0x00 0x00 $k 0x00 $0 $1 $2 $3 $4 $5 $6 $7 $8 $9

Custom key provider

For keeping master keys in a HSM, fetching per-card keys from a database or for implementing custom key diversification methods, subclass GPCardKeys. TODO: using custom providers from command line