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

You need three keys to make use of the card manager with SCP01, SCP02 or SCP03: ENC, MAC and DEK. If you have the actual keys and they are all different, you can specify them with -key-enc, -key-mac and -key-dek on the command line. Alternatively, if there is just a single key (like is assumed by the default test key with the value 40..4F) you can use -key to specify it.

Alternatively, if $GP_KEY_ENC, $GP_KEY_MAC and $GP_KEY_DEK are set in the environment, those values will be used. Specifying keys on the command line overrides the environment.

Diversification

Key diversification is a process of deriving keys from a master key using some card specific unique data. This way each card has different keys.

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

The shorthand options -emv, -visa2 and -kdf3 options are still supported, but deprecated.

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'

Important

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.

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