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 channel, you'll need three keys:

• ENC (Encryption key)
• MAC (Message Authentication Code key)
• DEK (Data Encryption 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)

Tip

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 Diversification - which derives unique per-card keys from a master key by incorporating unique card-specific data to each derived key.

GPPro supports a bunch of key diversification methods out of the box. In order to utilize a master key with a Key Deriviation Function (KDF), specify the known KDF name before the key, as such:

gp -key emv:default
# Diversify the default test key using the EMV method with data from INITIALIZE UPDATE response

gp -key emv:404142434445464748494A4B4C4D4E4F
# Same as above, explicitly specifying the default key bytes

gp -key visa2:47454D5850524553534F53414D504C45
# Use the VISA2 method with a 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 (master 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 FF $k $4 $5 $6 $7 $8 $9 0F $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