Keys

WARNING about correct keying

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.

If you do not have the keys, do not ask for help, 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 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 and 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, 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.

👉 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.

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