Keycard provides to developer an hardware implementation of a BIP-32 HD wallet. This means it supports key generation, derivation and signing. It also allows exporting keys defined in the context of EIP-1581.
\nCommunication with the Keycard happens through a simple APDU interface is provided, together with a Secure Channel guaranteeing confidentiality, authentication and integrity of all commands. It supports both NFC and ISO7816 physical interfaces, meaning that it is compatible with any Android phone equipped with NFC and all USB Smartcard readers.
\nThe most obvious case for integration of Keycard is crypto wallets (ETH, BTC, etc), however it can be used in other systems where a BIP-32 key tree is used and/or you perform authentication/identification.
\nTo further simplify integration, we have developed a Java-based API which can be used on both desktop and Android systems. On the desktop it uses the javax.smartcardio to interface with the card, which is compatible with most USB readers. On Android it uses the on-board NFC reader. If you develop in Java or any other language available, this is the easiest way to use the Keycard.
\nRead the documentation by clicking here
\nIf you use a different language, please first refer to the Java SDK documentation for a high level overview of how to perform different tasks with the Keycard. Then, please check the APDU protocol documentation out for the low-level details.
\n","site":{"data":{"menu":{"docs":"/docs/","blog":"https://our.status.im/incubate"},"languages":{"en":"English"},"sidebar":{"api":{"API":{"getting_started":"index.html","java_sdk":"java-sdk.html","apdu":"apdu.html"}}}}},"excerpt":"","more":"Keycard provides to developer an hardware implementation of a BIP-32 HD wallet. This means it supports key generation, derivation and signing. It also allows exporting keys defined in the context of EIP-1581.
\nCommunication with the Keycard happens through a simple APDU interface is provided, together with a Secure Channel guaranteeing confidentiality, authentication and integrity of all commands. It supports both NFC and ISO7816 physical interfaces, meaning that it is compatible with any Android phone equipped with NFC and all USB Smartcard readers.
\nThe most obvious case for integration of Keycard is crypto wallets (ETH, BTC, etc), however it can be used in other systems where a BIP-32 key tree is used and/or you perform authentication/identification.
\nTo further simplify integration, we have developed a Java-based API which can be used on both desktop and Android systems. On the desktop it uses the javax.smartcardio to interface with the card, which is compatible with most USB readers. On Android it uses the on-board NFC reader. If you develop in Java or any other language available, this is the easiest way to use the Keycard.
\nRead the documentation by clicking here
\nIf you use a different language, please first refer to the Java SDK documentation for a high level overview of how to perform different tasks with the Keycard. Then, please check the APDU protocol documentation out for the low-level details.
\n"},{"_content":"# Status Keycard Protocol\n\nThese are the commands supported by the application. When a command has a precondition clause and these are not met the SW 0x6985 is returned. All tagged data structures are encoded in the [BER-TLV format](http://www.cardwerk.com/smartcards/smartcard_standard_ISO7816-4_annex-d.aspx) \n\n## SELECT\n\n* CLA = 0x00\n* INS = 0xA4\n* P1 = 0x04\n* P2 = 0x00\n* Data = the instance AID\n* Response = Application Info Template or ECC public key.\n\nResponse Data format:\n- Tag 0xA4 = Application Info Template\n - Tag 0x8F = Instance UID (16 bytes)\n - Tag 0x80 = ECC public Key\n - Tag 0x02 = Application Version (2 bytes)\n - Tag 0x02 = Number of remaining pairing slots (1 byte)\n - Tag 0x8E = Key UID (0 or 32 bytes)\n\nThe SELECT command is documented in the ISO 7816-4 specifications and is used to select the application on the card, making it the active one. The data field is the AID of the application. The response is the Application Info template which contains the instance UID (which can be used by the client to keep track of multiple cards) and the public key which must be used by the client to establish the Secure Channel. Additionally it contains the version number of the application, formatted on two bytes. The first byte is the major version and the second is the minor version (e.g: version 1.1 is formatted as 0x0101). The number of remaining pairing slots is also included in the response.\n\nThe Key UID can be either empty (when no key is loaded on card) or the SHA-256 hash of the master public key.\n\nWhen the applet is in pre-initializated state, it only returns the ECC public key, BER-TLV encoded with tag 0x80.\n\n## INIT\n* CLA = 0x80\n* INS = 0xFE\n* P1 = 0x00\n* P2 = 0x00\n* Data = EC public key (LV encoded) | IV | encrypted payload\n* Response SW = 0x9000 on success, 0x6D00 if the applet is already initialized, 0x6A80 if the data is invalid\n\nThis command is only available when the applet is in pre-initialized state and successful execution brings the applet in the initialized state. This command is needed to allow securely storing secrets on the applet at a different moment and place than installation is taking place. Currently these are the PIN, PUK and pairing password.\n\nThe client must take the public key received after the SELECT command, generate a random keypair and perform EC-DH to generate an AES key. It must then generate a random IV and encrypt the payload using AES-CBC with ISO/IEC 9797-1 Method 2 padding.\n\nThey payload is the concatenation of the PIN (6 digits/bytes), PUK (12 digits/bytes) and pairing secret (32 bytes).\n\nThis scheme guarantees protection against passive MITM attacks. Since the applet has no \"owner\" before the execution of this command, protection against active MITM cannot be provided at this stage. However since the communication happens locally (either through NFC or contacted interface) the realization of such an attack at this point is unrealistic.\n\nAfter successful execution, this command cannot be executed anymore. The regular SecureChannel (with pairing) is active and PIN and PUK are initialized.\n\n## OPEN SECURE CHANNEL\n* CLA = 0x80\n* INS = 0x10\n* P1 = the pairing index\n* P2 = 0x00\n* Data = An EC-256 public key on the SECP256k1 curve encoded as an uncompressed point.\n* Response Data = A 256-bit salt and a 128-bit seed IV\n* Response SW = 0x9000 on success, 0x6A86 if P1 is invalid, 0x6A80 if the data is not a public key\n\nThis APDU is the first step to establish a Secure Channel session. A session is aborted when the application is deselected, either directly or because of a card reset/tear.\n\nThe card generates a random 256-bit salt which is sent to the client. Both the client and the card do the following for key derivation\n\n1. Use their private key and the counterpart public key to generate a secret using the EC-DH algorithm.\n2. The generated secret, the pairing key and the salt are concatenated and the SHA-512 of the concatenated value is calculated.\n3. The output of the SHA-512 algorithm is split in two parts of 256-bit. The first part is used as the encryption key and the second part is used as the MAC key for further communication.\n\nThe seed IV is used by the client as the IV for the next encrypted APDU.\n\n## MUTUALLY AUTHENTICATE\n\n* CLA = 0x80\n* INS = 0x11\n* P1 = 0x00\n* P2 = 0x00\n* Data = 256-bit random number\n* Response Data = 256-bit random number\n* Response SW = 0x9000 on success, 0x6985 if the previous successfully executed APDU was not OPEN SECURE CHANNEL, 0x6982 if authentication failed or the data is not 256-bit long\n\nThis APDU allows both parties to verify that the keys generated in the OPEN SECURE CHANNEL step are matching and thus guarantee authentication of the counterpart. The data sent by both parties is a 256-bit random number The APDU data is sent encrypted with the keys generated in the OPEN SECURE CHANNEL step. Each party must verify the MAC of the received APDU. If the MAC can be verified, it means that both parties are using the same keys. Only after this step has been executed the secure channel can be considered to be open and other commands can be sent. If the authentication fails the card must respond with 0x6982. In this case the OPEN SECURE CHANNEL command must be repeated to generate new keys.\n\n## PAIR\n\n* CLA = 0x80\n* INS = 0x12\n* P1 = pairing phase\n* P2 = 0x00\n* Data = see below\n* Response Data = see below\n* Response SW = 0x9000 on success, 0x6A80 if the data is in the wrong format, 0x6982 if client cryptogram verification fails, 0x6A84 if all available pairing slot are taken, 0x6A86 if P1 is invalid or is 0x01 but the first phase was not completed, 0x6985 if a secure channel is open\n\nP1:\n* 0x00: First step\n* 0x01: Final step\n\nData:\n* On first step: a 256-bit random client challenge\n* On second step: the client cryptogram as SHA-256(shared secret, card challenge)\n\nResponse Data:\n* On first step: the card cryptogram as SHA-256(shared secret, client challenge) followed by a 256-bit card challenge\n* On second step: the pairing index followed by a 256-bit salt\n\nThis APDU is sent to pair a client. Pairing is performed with two commands which must be sent immediately one after the other. \n\nIn the first phase the client sends a random challenge to the card. The card replies with the SHA-256 hash of the challenge and the shared secret followed by its random challenge. The client is thus able to authenticate the card by verifying the card cryptogram (since the client can generate the same and verify that it matches).\n\nIn the second phase the client sends the client cryptogram which is the SHA-256 hash of the shared secret and the card challenge. The card verifies the cryptogram and thus authenticates the client. On success the card generates a random 256-bit salt which is appended to the shared secret. The SHA-256 hash of the concatenated value is stored in the first available pairing slot and will be further used to derive session keys. The card responds with the pairing index (which the client must send in all OPEN SECURE CHANNEL commands) and the salt used to generate the key, so that the client can generate and store the same key.\n\nThe shared secret is a 256-bit value which must be be known to both parts being paired.\n\n## UNPAIR\n\n* CLA = 0x80\n* INS = 0x13\n* P1 = the index to unpair\n* P2 = 0x00\n* Response SW = 0x9000 on success, 0x6985 if security conditions are not met, 0x6A86 if the index is higher than the\n highest possible pairing index.\n* Preconditions: Secure Channel must be opened, user PIN must be verified\n\nThis APDU is sent to unpair a client. An existing secure channel session must be open. The application implementing this protocol may apply additional restrictions, such as the verification of a user PIN. On success the pairing slot at the given index will be freed and will be made available to pair other clients. If the index is already free nothing will happen.\n\n## GET STATUS\n\n* CLA = 0x80\n* INS = 0xF2\n* P1 = 0x00 for application status, 0x01 for key path status\n* P2 = 0x00\n* Response SW = 0x9000 on success, 0x6A86 on undefined P1\n* Response Data = Application Status Template or Key Path\n* Preconditions: Secure Channel must be opened\n\nResponse Data format:\nif P1 = 0x00:\n- Tag 0xA3 = Application Status Template\n - Tag 0x02 = PIN retry count (1 byte)\n - Tag 0x02 = PUK retry count (1 byte)\n - Tag 0x01 = 0xff if key is initialized, 0 otherwise\n\nif P1 = 0x01:\n- a sequence of 32-bit numbers indicating the current key path. Empty if master key is selected.\n\n## SET NDEF\n\n* CLA = 0x80\n* INS = 0xF3\n* P1 = 0x00\n* P2 = 0x00\n* Data = the data to store\n* Response SW = 0x9000 on success, 0x6A80 on invalid data\n* Preconditions: Secure Channel must be opened, PIN must be verified\n\nUsed to set the content of the data file owned by the NDEF applet. This allows changing the behavior of Android and other clients when tapping the card with no open client. As an example, it could be used to launch a specific wallet software.\n\nThe data is stored as is. A check is made that the first 2 bytes, read as a MSB first short, are equal to the Lc field minus 2 (the length of the field itself). This does not ensure that the NDEF record is valid, but ensures that no out of bound access happens.\n\n## VERIFY PIN\n\n* CLA = 0x80\n* INS = 0x20\n* P1 = 0x00\n* P2 = 0x00\n* Data = the PIN to be verified\n* Response SW = 0x9000 on success, 0x63CX on failure, where X is the number of attempt remaining\n* Preconditions: Secure Channel must be opened\n\nUsed to verify the user PIN. On correct PIN entry the card returns 0x9000, the retry counter is reset and the PIN is marked as authenticated for the entire session (until the application is deselected or the card reset/teared). On error, the number of remaining retries is decreased and the SW 0x63CX, where X is the number of available retries is returned. When the number of remaining retries reaches 0 the PIN is blocked. When the PIN is blocked this command always returns 0x63C0, even if the PIN is inserted correctly.\n\n## CHANGE PIN\n\n* CLA = 0x80\n* INS = 0x21\n* P1 = PIN identifier\n* P2 = 0x00\n* Data = the new PIN\n* Response SW = 0x9000 on success, 0x6A80 if the PIN format is invalid, 0x6A86 if P1 is invalid\n* Preconditions: Secure Channel must be opened, user PIN must be verified\n\nUsed to change a PIN or secret. In case of invalid format, the code 0x6A80 is returned. If the conditions match, the PIN or secret is updated. The no-error SW 0x9000 is returned.\n\nP1:\n* 0x00: User PIN. Must be 6-digits. The updated PIN is authenticated for the rest of the session. \n* 0x01: Applet PUK. Must be 12-digits.\n* 0x02: Pairing secret. Must be 32-bytes long. Existing pairings are not broken, but new pairings will need to use the new secret.\n\n## UNBLOCK PIN\n\n* CLA = 0x80\n* INS = 0x22\n* P1 = 0x00\n* P2 = 0x00\n* Data = the PUK followed by the new PIN\n* Response SW = 0x9000 on success, 0x6A80 if the format is invalid\n* Preconditions: Secure Channel must be opened, user PIN must be blocked\n\nUsed to unblock the user PIN. The data field must contain exactly 18 numeric digits, otherwise SW 0x6A80 is returned. The first 12 digits are the PUK and the last 6 are the new PIN. If the PUK is correct the PIN is changed to the supplied one, it is unblocked and authenticated for the rest of the session. The status code 0x9000 is returned. When the PUK is wrong, the number of remaining retries is decreased and the SW 0x63CX, where X is the number of available retries is returned. When the number of remaining retries reaches 0 the PUK is blocked. When the PUK is blocked this command always returns 0x63C0, even if the PUK is inserted correctly. In this case the wallet is effectively lost.\n\n## LOAD KEY\n\n* CLA = 0x80\n* INS = 0xD0\n* P1 = key type\n* P2 = 0x00\n* Data = the key data\n* Response SW = 0x9000 on success, 0x6A80 if the format is invalid, 0x6A86 if P1 is invalid\n* Response Data = the key UID, defined as the SHA-256 of the public key\n* Preconditions: Secure Channel must be opened, user PIN must be verified\n\nP1:\n* 0x01 = ECC SECP256k1 keypair\n* 0x02 = ECC SECP256k1 extended keypair\n* 0x03 = Binary seed as defined in [BIP39](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki)\n\nData:\n\nIf P1 is 0x01 or 0x02\n- Tag 0xA1 = keypair template\n - Tag 0x80 = ECC public key component (can be omitted)\n - Tag 0x81 = ECC private key component\n - Tag 0x82 = chain code (if P1=0x02)\n \nIf P1 is 0x03 a 64 byte sequence generated according to the BIP39 specifications is expected. The master key will be generated according to the [BIP32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki) specifications. This is only supported if the hardware supports public key derivation.\n\nThis command is used to load or replace the keypair used for signing on the card. This command always aborts open signing sessions, if any. Unless a DERIVE KEY is sent, a subsequent SIGN command will use this keypair for signature.\n\n## DERIVE KEY\n\n* CLA = 0x80\n* INS = 0xD1\n* P1 = derivation options\n* P2 = 0x00\n* Data = a sequence of 32-bit integers (most significant byte first). Empty if the master key must be used.\n* Response SW = 0x9000 on success, 0x6A80 if the format is invalid, 0x6984 if one of the components in the path generates an invalid key, 0x6B00 if derivation from parent keys is selected but no valid parent key is cached.\n* Preconditions: Secure Channel must be opened, user PIN must be verified (if no PIN-less key is defined), an extended keyset must be loaded\n\nThis command is used before a signing session to generate a private key according to the [BIP32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki) specifications. This command always aborts open signing sessions, if any. The generated key is used for all subsequent SIGN sessions. The maximum depth of derivation from the master key is 10. Any attempt to get deeper results in 0x6A80 being returned. The BIP32 specifications define a few checks which must be performed on the derived keys. If these fail, the 0x6984 is returned and the invalid key is discarded. A client should perform a GET STATUS command to get the actual current key path and resume derivation using a different path.\n\nThe ability to start derivation from the parent keys allows to more efficiently switch between children of the same key. Note however that only the immediate parent of the current key is cached so you cannot use this to go back in the hierarchy. If no valid parent key is available the status code 0x6B00 will be returned.\n\nP1:\n* bit 0-5 = reserved\n* bit 7-6:\n - 00 derive from master keys\n - 01 derive from parent keys\n - 10 derive from current keys\n - 11 reserved\n\n## GENERATE MNEMONIC\n\n* CLA = 0x80\n* INS = 0xD2\n* P1 = checksum size (between 4 and 8)\n* P2 = 0x00\n* Response SW = 0x9000 on success. 0x6A86 if P1 is invalid.\n* Response Data = a sequence of 16-bit integers (most significant byte first).\n* Preconditions: Secure Channel must be opened\n\nUsed to generate a mnemonic according to the algorithm specified in [BIP39](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki). The returned data is a list of 16-byte integers which should be used as indexes in a wordlist to generate the human-readable mnemonic. Each integer can have a value from 0 to 2047.\n\n## REMOVE KEY\n\n* CLA = 0x80\n* INS = 0xD3\n* P1 = 0x00\n* P2 = 0x00\n* Response SW = 0x9000 on success.\n* Preconditions: Secure Channel must be opened, user PIN must be verified\n\nRemoves the key from the card, bringing it back to an uninitialized state. No signing operation is possible after this command until a new LOAD KEY command is performed.\n\n## GENERATE KEY\n\n* CLA = 0x80\n* INS = 0xD4\n* P1 = 0x00\n* P2 = 0x00\n* Response SW = 0x9000 on success.\n* Response Data = the key UID, defined as the SHA-256 of the public key\n* Preconditions: Secure Channel must be opened, user PIN must be verified\n\nGenerates and stores keys completely on card. The state of the card after execution is the same as if a LOAD KEY command had been performed.\n\n## DUPLICATE KEY\n\n* CLA = 0x80\n* INS = 0xD5\n* P1 = subcommand\n* P2 = depends on subcommand\n* Data = depends on phase\n* Response SW = 0x9000 on success.\n* Response Data = depends on subcommand\n* Preconditions: depends on subcommand\n\nP1:\n* 0x00: START DUPLICATE\n* 0x01: ADD ENTROPY\n* 0x02: EXPORT DUPLICATE\n* 0x03: IMPORT DUPLICATE\n\n### START DUPLICATE\nThis is the first step to start duplication. Requires an open secure channel and user PIN must be verified. Aborts any on-going duplication session. P2 is the number of entropy pieces to expect in total (including this command). The data contain the first piece of entropy. Returns no data. Must be performed with exactly the same parameters and data on all cards taking part in the duplication.\n\n### ADD ENTROPY\nThis command uses the same one-shot secure channel scheme as defined in the INIT command. P2 is 00. Requires an ongoing duplicate session started with the START DUPLICATE subcommand. Must be performed once per device taking part in the duplication process, for a total number of devices equaling the P2 parameter of the START DUPLICATE subcommand (counting the device which sent the START DUPLICATE command as the first device). The data is a random 256-bit number. The same data must be sent to all the cards taking part in the duplication process.\n\n### EXPORT DUPLICATE\nThis command must be sent to the card which you wish to duplicate. Requires an open secure channel and authenticated PIN. Works only if a duplication session is active and ADD ENTROPY has been performed the required number of times. Returns the encrypted duplicate of the master key and terminates the duplication session for this card. The format is exactly the same as the one defined in the LOAD KEY (TLV) command with omitted public key. It is however prepended by a 16-bytes IV and the entire TLV structure is encrypted.\n\n### IMPORT DUPLICATE\nThis command must be sent to all the cards which are a target for duplication. The Data field must contain the output from the EXPORT DUPLICATE command performed on the source card. Returns the key UID. It follows exactly the same rules as the EXPORT DUPLICATE subcommand.\n\n## SIGN\n\n* CLA = 0x80\n* INS = 0xC0\n* P1 = 0x00\n* P2 = 0x00\n* Data = the hash to sign\n* Response = public key and the signature\n* Response SW = 0x9000 on success, 0x6A80 if the data is not 32-byte long\n* Preconditions: Secure Channel must be opened, user PIN must be verified (or a PIN-less key must be active), a valid keypair must be loaded\n\nResponse Data format:\n- Tag 0xA0 = signature template\n - Tag 0x80 = ECC public key component\n - Tag 0x30 = ECDSA Signature\n - Tag 0x02 = R value\n - Tag 0x02 = S value\n\nReturns the ECDSA signature of the hash. The hash can be calculated using any algorithm, but must be 32-bytes long. The signature is returned in a signature template, containing the public key associated to the signature and the signature itself. For usage on the blockchain, you will need to calculate the recovery ID in addition to extracting R and S. To calculate the recovery ID you need to apply the same algorithm used for public key recovery from a transaction starting with a recovery ID of 0. If the public key matches the one returned in the template, then you have found the recovery ID, otherwise you try again by incrementing the recovery ID.\n\n## SET PINLESS PATH\n\n* CLA = 0x80\n* INS = 0xC1\n* P1 = 0x00\n* P2 = 0x00\n* Data = a sequence of 32-bit integers\n* Response SW = 0x9000 on success, 0x6A80 if data is invalid\n* Preconditions: Secure Channel must be opened, user PIN must be verified\n\nSets the given sequence of 32-bit integers as a PIN-less path. When the current derived key matches this path, SIGN will work even if no PIN authentication has been performed. An empty sequence means that no PIN-less path is defined.\n\n## EXPORT KEY\n\n* CLA = 0x80\n* INS = 0xC2\n* P1 = derivation options\n* P2 = export options\n* Response SW = 0x9000 on success, 0x6A86 if P1 or P2 are wrong\n* Data = a sequence of 32-bit integers (empty if P1=0x00)\n* Response Data = key pair template\n* Response SW = 0x9000 on success, 0x6985 if the private key cannot be exported, 0x6A80 if the path is malformed\n* Preconditions: Secure Channel must be opened, user PIN must be verified\n \nP1:\n0x00 = Current key\n0x01 = Derive\n0x02 = Derive and make current\n\nP2:\n0x00 = private and public key\n0x01 = public key only\n \nResponse Data format:\n- Tag 0xA1 = keypair template\n - Tag 0x80 = ECC public key component (could be omitted)\n - Tag 0x81 = ECC private key component (if P2=0x00)\n \nThis command exports the requested public and private key. The public key can be always exported (P2=0x01), but the private key (P2=0x00) can be exported if and only if the requested key path is in the [EIP-1581](https://eips.ethereum.org/EIPS/eip-1581) subtree. \n\nThe P1 parameter indicates how to the derive the desired key. P1 = 0x00 indicates that the current key must be exported, and no derivation will be performed. P1 = 0x01 derives the path given in the data field without changing the current path of the card. P1 = 0x02 derives the path but also changes the current path of the card. The source for derivation can be set by OR'ing P1 with the constants defined in the DERIVE KEY command. This allows deriving from master, parent or current.\n\nIf the private key is being exported, the card could omit exporting the public key for performance reason. The public key can then be calculate off-card if needed.","source":"api/apdu.md","raw":"# Status Keycard Protocol\n\nThese are the commands supported by the application. When a command has a precondition clause and these are not met the SW 0x6985 is returned. All tagged data structures are encoded in the [BER-TLV format](http://www.cardwerk.com/smartcards/smartcard_standard_ISO7816-4_annex-d.aspx) \n\n## SELECT\n\n* CLA = 0x00\n* INS = 0xA4\n* P1 = 0x04\n* P2 = 0x00\n* Data = the instance AID\n* Response = Application Info Template or ECC public key.\n\nResponse Data format:\n- Tag 0xA4 = Application Info Template\n - Tag 0x8F = Instance UID (16 bytes)\n - Tag 0x80 = ECC public Key\n - Tag 0x02 = Application Version (2 bytes)\n - Tag 0x02 = Number of remaining pairing slots (1 byte)\n - Tag 0x8E = Key UID (0 or 32 bytes)\n\nThe SELECT command is documented in the ISO 7816-4 specifications and is used to select the application on the card, making it the active one. The data field is the AID of the application. The response is the Application Info template which contains the instance UID (which can be used by the client to keep track of multiple cards) and the public key which must be used by the client to establish the Secure Channel. Additionally it contains the version number of the application, formatted on two bytes. The first byte is the major version and the second is the minor version (e.g: version 1.1 is formatted as 0x0101). The number of remaining pairing slots is also included in the response.\n\nThe Key UID can be either empty (when no key is loaded on card) or the SHA-256 hash of the master public key.\n\nWhen the applet is in pre-initializated state, it only returns the ECC public key, BER-TLV encoded with tag 0x80.\n\n## INIT\n* CLA = 0x80\n* INS = 0xFE\n* P1 = 0x00\n* P2 = 0x00\n* Data = EC public key (LV encoded) | IV | encrypted payload\n* Response SW = 0x9000 on success, 0x6D00 if the applet is already initialized, 0x6A80 if the data is invalid\n\nThis command is only available when the applet is in pre-initialized state and successful execution brings the applet in the initialized state. This command is needed to allow securely storing secrets on the applet at a different moment and place than installation is taking place. Currently these are the PIN, PUK and pairing password.\n\nThe client must take the public key received after the SELECT command, generate a random keypair and perform EC-DH to generate an AES key. It must then generate a random IV and encrypt the payload using AES-CBC with ISO/IEC 9797-1 Method 2 padding.\n\nThey payload is the concatenation of the PIN (6 digits/bytes), PUK (12 digits/bytes) and pairing secret (32 bytes).\n\nThis scheme guarantees protection against passive MITM attacks. Since the applet has no \"owner\" before the execution of this command, protection against active MITM cannot be provided at this stage. However since the communication happens locally (either through NFC or contacted interface) the realization of such an attack at this point is unrealistic.\n\nAfter successful execution, this command cannot be executed anymore. The regular SecureChannel (with pairing) is active and PIN and PUK are initialized.\n\n## OPEN SECURE CHANNEL\n* CLA = 0x80\n* INS = 0x10\n* P1 = the pairing index\n* P2 = 0x00\n* Data = An EC-256 public key on the SECP256k1 curve encoded as an uncompressed point.\n* Response Data = A 256-bit salt and a 128-bit seed IV\n* Response SW = 0x9000 on success, 0x6A86 if P1 is invalid, 0x6A80 if the data is not a public key\n\nThis APDU is the first step to establish a Secure Channel session. A session is aborted when the application is deselected, either directly or because of a card reset/tear.\n\nThe card generates a random 256-bit salt which is sent to the client. Both the client and the card do the following for key derivation\n\n1. Use their private key and the counterpart public key to generate a secret using the EC-DH algorithm.\n2. The generated secret, the pairing key and the salt are concatenated and the SHA-512 of the concatenated value is calculated.\n3. The output of the SHA-512 algorithm is split in two parts of 256-bit. The first part is used as the encryption key and the second part is used as the MAC key for further communication.\n\nThe seed IV is used by the client as the IV for the next encrypted APDU.\n\n## MUTUALLY AUTHENTICATE\n\n* CLA = 0x80\n* INS = 0x11\n* P1 = 0x00\n* P2 = 0x00\n* Data = 256-bit random number\n* Response Data = 256-bit random number\n* Response SW = 0x9000 on success, 0x6985 if the previous successfully executed APDU was not OPEN SECURE CHANNEL, 0x6982 if authentication failed or the data is not 256-bit long\n\nThis APDU allows both parties to verify that the keys generated in the OPEN SECURE CHANNEL step are matching and thus guarantee authentication of the counterpart. The data sent by both parties is a 256-bit random number The APDU data is sent encrypted with the keys generated in the OPEN SECURE CHANNEL step. Each party must verify the MAC of the received APDU. If the MAC can be verified, it means that both parties are using the same keys. Only after this step has been executed the secure channel can be considered to be open and other commands can be sent. If the authentication fails the card must respond with 0x6982. In this case the OPEN SECURE CHANNEL command must be repeated to generate new keys.\n\n## PAIR\n\n* CLA = 0x80\n* INS = 0x12\n* P1 = pairing phase\n* P2 = 0x00\n* Data = see below\n* Response Data = see below\n* Response SW = 0x9000 on success, 0x6A80 if the data is in the wrong format, 0x6982 if client cryptogram verification fails, 0x6A84 if all available pairing slot are taken, 0x6A86 if P1 is invalid or is 0x01 but the first phase was not completed, 0x6985 if a secure channel is open\n\nP1:\n* 0x00: First step\n* 0x01: Final step\n\nData:\n* On first step: a 256-bit random client challenge\n* On second step: the client cryptogram as SHA-256(shared secret, card challenge)\n\nResponse Data:\n* On first step: the card cryptogram as SHA-256(shared secret, client challenge) followed by a 256-bit card challenge\n* On second step: the pairing index followed by a 256-bit salt\n\nThis APDU is sent to pair a client. Pairing is performed with two commands which must be sent immediately one after the other. \n\nIn the first phase the client sends a random challenge to the card. The card replies with the SHA-256 hash of the challenge and the shared secret followed by its random challenge. The client is thus able to authenticate the card by verifying the card cryptogram (since the client can generate the same and verify that it matches).\n\nIn the second phase the client sends the client cryptogram which is the SHA-256 hash of the shared secret and the card challenge. The card verifies the cryptogram and thus authenticates the client. On success the card generates a random 256-bit salt which is appended to the shared secret. The SHA-256 hash of the concatenated value is stored in the first available pairing slot and will be further used to derive session keys. The card responds with the pairing index (which the client must send in all OPEN SECURE CHANNEL commands) and the salt used to generate the key, so that the client can generate and store the same key.\n\nThe shared secret is a 256-bit value which must be be known to both parts being paired.\n\n## UNPAIR\n\n* CLA = 0x80\n* INS = 0x13\n* P1 = the index to unpair\n* P2 = 0x00\n* Response SW = 0x9000 on success, 0x6985 if security conditions are not met, 0x6A86 if the index is higher than the\n highest possible pairing index.\n* Preconditions: Secure Channel must be opened, user PIN must be verified\n\nThis APDU is sent to unpair a client. An existing secure channel session must be open. The application implementing this protocol may apply additional restrictions, such as the verification of a user PIN. On success the pairing slot at the given index will be freed and will be made available to pair other clients. If the index is already free nothing will happen.\n\n## GET STATUS\n\n* CLA = 0x80\n* INS = 0xF2\n* P1 = 0x00 for application status, 0x01 for key path status\n* P2 = 0x00\n* Response SW = 0x9000 on success, 0x6A86 on undefined P1\n* Response Data = Application Status Template or Key Path\n* Preconditions: Secure Channel must be opened\n\nResponse Data format:\nif P1 = 0x00:\n- Tag 0xA3 = Application Status Template\n - Tag 0x02 = PIN retry count (1 byte)\n - Tag 0x02 = PUK retry count (1 byte)\n - Tag 0x01 = 0xff if key is initialized, 0 otherwise\n\nif P1 = 0x01:\n- a sequence of 32-bit numbers indicating the current key path. Empty if master key is selected.\n\n## SET NDEF\n\n* CLA = 0x80\n* INS = 0xF3\n* P1 = 0x00\n* P2 = 0x00\n* Data = the data to store\n* Response SW = 0x9000 on success, 0x6A80 on invalid data\n* Preconditions: Secure Channel must be opened, PIN must be verified\n\nUsed to set the content of the data file owned by the NDEF applet. This allows changing the behavior of Android and other clients when tapping the card with no open client. As an example, it could be used to launch a specific wallet software.\n\nThe data is stored as is. A check is made that the first 2 bytes, read as a MSB first short, are equal to the Lc field minus 2 (the length of the field itself). This does not ensure that the NDEF record is valid, but ensures that no out of bound access happens.\n\n## VERIFY PIN\n\n* CLA = 0x80\n* INS = 0x20\n* P1 = 0x00\n* P2 = 0x00\n* Data = the PIN to be verified\n* Response SW = 0x9000 on success, 0x63CX on failure, where X is the number of attempt remaining\n* Preconditions: Secure Channel must be opened\n\nUsed to verify the user PIN. On correct PIN entry the card returns 0x9000, the retry counter is reset and the PIN is marked as authenticated for the entire session (until the application is deselected or the card reset/teared). On error, the number of remaining retries is decreased and the SW 0x63CX, where X is the number of available retries is returned. When the number of remaining retries reaches 0 the PIN is blocked. When the PIN is blocked this command always returns 0x63C0, even if the PIN is inserted correctly.\n\n## CHANGE PIN\n\n* CLA = 0x80\n* INS = 0x21\n* P1 = PIN identifier\n* P2 = 0x00\n* Data = the new PIN\n* Response SW = 0x9000 on success, 0x6A80 if the PIN format is invalid, 0x6A86 if P1 is invalid\n* Preconditions: Secure Channel must be opened, user PIN must be verified\n\nUsed to change a PIN or secret. In case of invalid format, the code 0x6A80 is returned. If the conditions match, the PIN or secret is updated. The no-error SW 0x9000 is returned.\n\nP1:\n* 0x00: User PIN. Must be 6-digits. The updated PIN is authenticated for the rest of the session. \n* 0x01: Applet PUK. Must be 12-digits.\n* 0x02: Pairing secret. Must be 32-bytes long. Existing pairings are not broken, but new pairings will need to use the new secret.\n\n## UNBLOCK PIN\n\n* CLA = 0x80\n* INS = 0x22\n* P1 = 0x00\n* P2 = 0x00\n* Data = the PUK followed by the new PIN\n* Response SW = 0x9000 on success, 0x6A80 if the format is invalid\n* Preconditions: Secure Channel must be opened, user PIN must be blocked\n\nUsed to unblock the user PIN. The data field must contain exactly 18 numeric digits, otherwise SW 0x6A80 is returned. The first 12 digits are the PUK and the last 6 are the new PIN. If the PUK is correct the PIN is changed to the supplied one, it is unblocked and authenticated for the rest of the session. The status code 0x9000 is returned. When the PUK is wrong, the number of remaining retries is decreased and the SW 0x63CX, where X is the number of available retries is returned. When the number of remaining retries reaches 0 the PUK is blocked. When the PUK is blocked this command always returns 0x63C0, even if the PUK is inserted correctly. In this case the wallet is effectively lost.\n\n## LOAD KEY\n\n* CLA = 0x80\n* INS = 0xD0\n* P1 = key type\n* P2 = 0x00\n* Data = the key data\n* Response SW = 0x9000 on success, 0x6A80 if the format is invalid, 0x6A86 if P1 is invalid\n* Response Data = the key UID, defined as the SHA-256 of the public key\n* Preconditions: Secure Channel must be opened, user PIN must be verified\n\nP1:\n* 0x01 = ECC SECP256k1 keypair\n* 0x02 = ECC SECP256k1 extended keypair\n* 0x03 = Binary seed as defined in [BIP39](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki)\n\nData:\n\nIf P1 is 0x01 or 0x02\n- Tag 0xA1 = keypair template\n - Tag 0x80 = ECC public key component (can be omitted)\n - Tag 0x81 = ECC private key component\n - Tag 0x82 = chain code (if P1=0x02)\n \nIf P1 is 0x03 a 64 byte sequence generated according to the BIP39 specifications is expected. The master key will be generated according to the [BIP32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki) specifications. This is only supported if the hardware supports public key derivation.\n\nThis command is used to load or replace the keypair used for signing on the card. This command always aborts open signing sessions, if any. Unless a DERIVE KEY is sent, a subsequent SIGN command will use this keypair for signature.\n\n## DERIVE KEY\n\n* CLA = 0x80\n* INS = 0xD1\n* P1 = derivation options\n* P2 = 0x00\n* Data = a sequence of 32-bit integers (most significant byte first). Empty if the master key must be used.\n* Response SW = 0x9000 on success, 0x6A80 if the format is invalid, 0x6984 if one of the components in the path generates an invalid key, 0x6B00 if derivation from parent keys is selected but no valid parent key is cached.\n* Preconditions: Secure Channel must be opened, user PIN must be verified (if no PIN-less key is defined), an extended keyset must be loaded\n\nThis command is used before a signing session to generate a private key according to the [BIP32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki) specifications. This command always aborts open signing sessions, if any. The generated key is used for all subsequent SIGN sessions. The maximum depth of derivation from the master key is 10. Any attempt to get deeper results in 0x6A80 being returned. The BIP32 specifications define a few checks which must be performed on the derived keys. If these fail, the 0x6984 is returned and the invalid key is discarded. A client should perform a GET STATUS command to get the actual current key path and resume derivation using a different path.\n\nThe ability to start derivation from the parent keys allows to more efficiently switch between children of the same key. Note however that only the immediate parent of the current key is cached so you cannot use this to go back in the hierarchy. If no valid parent key is available the status code 0x6B00 will be returned.\n\nP1:\n* bit 0-5 = reserved\n* bit 7-6:\n - 00 derive from master keys\n - 01 derive from parent keys\n - 10 derive from current keys\n - 11 reserved\n\n## GENERATE MNEMONIC\n\n* CLA = 0x80\n* INS = 0xD2\n* P1 = checksum size (between 4 and 8)\n* P2 = 0x00\n* Response SW = 0x9000 on success. 0x6A86 if P1 is invalid.\n* Response Data = a sequence of 16-bit integers (most significant byte first).\n* Preconditions: Secure Channel must be opened\n\nUsed to generate a mnemonic according to the algorithm specified in [BIP39](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki). The returned data is a list of 16-byte integers which should be used as indexes in a wordlist to generate the human-readable mnemonic. Each integer can have a value from 0 to 2047.\n\n## REMOVE KEY\n\n* CLA = 0x80\n* INS = 0xD3\n* P1 = 0x00\n* P2 = 0x00\n* Response SW = 0x9000 on success.\n* Preconditions: Secure Channel must be opened, user PIN must be verified\n\nRemoves the key from the card, bringing it back to an uninitialized state. No signing operation is possible after this command until a new LOAD KEY command is performed.\n\n## GENERATE KEY\n\n* CLA = 0x80\n* INS = 0xD4\n* P1 = 0x00\n* P2 = 0x00\n* Response SW = 0x9000 on success.\n* Response Data = the key UID, defined as the SHA-256 of the public key\n* Preconditions: Secure Channel must be opened, user PIN must be verified\n\nGenerates and stores keys completely on card. The state of the card after execution is the same as if a LOAD KEY command had been performed.\n\n## DUPLICATE KEY\n\n* CLA = 0x80\n* INS = 0xD5\n* P1 = subcommand\n* P2 = depends on subcommand\n* Data = depends on phase\n* Response SW = 0x9000 on success.\n* Response Data = depends on subcommand\n* Preconditions: depends on subcommand\n\nP1:\n* 0x00: START DUPLICATE\n* 0x01: ADD ENTROPY\n* 0x02: EXPORT DUPLICATE\n* 0x03: IMPORT DUPLICATE\n\n### START DUPLICATE\nThis is the first step to start duplication. Requires an open secure channel and user PIN must be verified. Aborts any on-going duplication session. P2 is the number of entropy pieces to expect in total (including this command). The data contain the first piece of entropy. Returns no data. Must be performed with exactly the same parameters and data on all cards taking part in the duplication.\n\n### ADD ENTROPY\nThis command uses the same one-shot secure channel scheme as defined in the INIT command. P2 is 00. Requires an ongoing duplicate session started with the START DUPLICATE subcommand. Must be performed once per device taking part in the duplication process, for a total number of devices equaling the P2 parameter of the START DUPLICATE subcommand (counting the device which sent the START DUPLICATE command as the first device). The data is a random 256-bit number. The same data must be sent to all the cards taking part in the duplication process.\n\n### EXPORT DUPLICATE\nThis command must be sent to the card which you wish to duplicate. Requires an open secure channel and authenticated PIN. Works only if a duplication session is active and ADD ENTROPY has been performed the required number of times. Returns the encrypted duplicate of the master key and terminates the duplication session for this card. The format is exactly the same as the one defined in the LOAD KEY (TLV) command with omitted public key. It is however prepended by a 16-bytes IV and the entire TLV structure is encrypted.\n\n### IMPORT DUPLICATE\nThis command must be sent to all the cards which are a target for duplication. The Data field must contain the output from the EXPORT DUPLICATE command performed on the source card. Returns the key UID. It follows exactly the same rules as the EXPORT DUPLICATE subcommand.\n\n## SIGN\n\n* CLA = 0x80\n* INS = 0xC0\n* P1 = 0x00\n* P2 = 0x00\n* Data = the hash to sign\n* Response = public key and the signature\n* Response SW = 0x9000 on success, 0x6A80 if the data is not 32-byte long\n* Preconditions: Secure Channel must be opened, user PIN must be verified (or a PIN-less key must be active), a valid keypair must be loaded\n\nResponse Data format:\n- Tag 0xA0 = signature template\n - Tag 0x80 = ECC public key component\n - Tag 0x30 = ECDSA Signature\n - Tag 0x02 = R value\n - Tag 0x02 = S value\n\nReturns the ECDSA signature of the hash. The hash can be calculated using any algorithm, but must be 32-bytes long. The signature is returned in a signature template, containing the public key associated to the signature and the signature itself. For usage on the blockchain, you will need to calculate the recovery ID in addition to extracting R and S. To calculate the recovery ID you need to apply the same algorithm used for public key recovery from a transaction starting with a recovery ID of 0. If the public key matches the one returned in the template, then you have found the recovery ID, otherwise you try again by incrementing the recovery ID.\n\n## SET PINLESS PATH\n\n* CLA = 0x80\n* INS = 0xC1\n* P1 = 0x00\n* P2 = 0x00\n* Data = a sequence of 32-bit integers\n* Response SW = 0x9000 on success, 0x6A80 if data is invalid\n* Preconditions: Secure Channel must be opened, user PIN must be verified\n\nSets the given sequence of 32-bit integers as a PIN-less path. When the current derived key matches this path, SIGN will work even if no PIN authentication has been performed. An empty sequence means that no PIN-less path is defined.\n\n## EXPORT KEY\n\n* CLA = 0x80\n* INS = 0xC2\n* P1 = derivation options\n* P2 = export options\n* Response SW = 0x9000 on success, 0x6A86 if P1 or P2 are wrong\n* Data = a sequence of 32-bit integers (empty if P1=0x00)\n* Response Data = key pair template\n* Response SW = 0x9000 on success, 0x6985 if the private key cannot be exported, 0x6A80 if the path is malformed\n* Preconditions: Secure Channel must be opened, user PIN must be verified\n \nP1:\n0x00 = Current key\n0x01 = Derive\n0x02 = Derive and make current\n\nP2:\n0x00 = private and public key\n0x01 = public key only\n \nResponse Data format:\n- Tag 0xA1 = keypair template\n - Tag 0x80 = ECC public key component (could be omitted)\n - Tag 0x81 = ECC private key component (if P2=0x00)\n \nThis command exports the requested public and private key. The public key can be always exported (P2=0x01), but the private key (P2=0x00) can be exported if and only if the requested key path is in the [EIP-1581](https://eips.ethereum.org/EIPS/eip-1581) subtree. \n\nThe P1 parameter indicates how to the derive the desired key. P1 = 0x00 indicates that the current key must be exported, and no derivation will be performed. P1 = 0x01 derives the path given in the data field without changing the current path of the card. P1 = 0x02 derives the path but also changes the current path of the card. The source for derivation can be set by OR'ing P1 with the constants defined in the DERIVE KEY command. This allows deriving from master, parent or current.\n\nIf the private key is being exported, the card could omit exporting the public key for performance reason. The public key can then be calculate off-card if needed.","date":"2019-01-17T09:53:56.194Z","updated":"2019-01-17T09:53:56.190Z","path":"api/apdu.html","_id":"cjqyxw7i30000p0qe505dwpag","title":"","comments":1,"layout":"page","content":"These are the commands supported by the application. When a command has a precondition clause and these are not met the SW 0x6985 is returned. All tagged data structures are encoded in the BER-TLV format
\nResponse Data format:
\nThe SELECT command is documented in the ISO 7816-4 specifications and is used to select the application on the card, making it the active one. The data field is the AID of the application. The response is the Application Info template which contains the instance UID (which can be used by the client to keep track of multiple cards) and the public key which must be used by the client to establish the Secure Channel. Additionally it contains the version number of the application, formatted on two bytes. The first byte is the major version and the second is the minor version (e.g: version 1.1 is formatted as 0x0101). The number of remaining pairing slots is also included in the response.
\nThe Key UID can be either empty (when no key is loaded on card) or the SHA-256 hash of the master public key.
\nWhen the applet is in pre-initializated state, it only returns the ECC public key, BER-TLV encoded with tag 0x80.
\nThis command is only available when the applet is in pre-initialized state and successful execution brings the applet in the initialized state. This command is needed to allow securely storing secrets on the applet at a different moment and place than installation is taking place. Currently these are the PIN, PUK and pairing password.
\nThe client must take the public key received after the SELECT command, generate a random keypair and perform EC-DH to generate an AES key. It must then generate a random IV and encrypt the payload using AES-CBC with ISO/IEC 9797-1 Method 2 padding.
\nThey payload is the concatenation of the PIN (6 digits/bytes), PUK (12 digits/bytes) and pairing secret (32 bytes).
\nThis scheme guarantees protection against passive MITM attacks. Since the applet has no “owner” before the execution of this command, protection against active MITM cannot be provided at this stage. However since the communication happens locally (either through NFC or contacted interface) the realization of such an attack at this point is unrealistic.
\nAfter successful execution, this command cannot be executed anymore. The regular SecureChannel (with pairing) is active and PIN and PUK are initialized.
\nThis APDU is the first step to establish a Secure Channel session. A session is aborted when the application is deselected, either directly or because of a card reset/tear.
\nThe card generates a random 256-bit salt which is sent to the client. Both the client and the card do the following for key derivation
\nThe seed IV is used by the client as the IV for the next encrypted APDU.
\nThis APDU allows both parties to verify that the keys generated in the OPEN SECURE CHANNEL step are matching and thus guarantee authentication of the counterpart. The data sent by both parties is a 256-bit random number The APDU data is sent encrypted with the keys generated in the OPEN SECURE CHANNEL step. Each party must verify the MAC of the received APDU. If the MAC can be verified, it means that both parties are using the same keys. Only after this step has been executed the secure channel can be considered to be open and other commands can be sent. If the authentication fails the card must respond with 0x6982. In this case the OPEN SECURE CHANNEL command must be repeated to generate new keys.
\nP1:
\nData:
\nResponse Data:
\nThis APDU is sent to pair a client. Pairing is performed with two commands which must be sent immediately one after the other.
\nIn the first phase the client sends a random challenge to the card. The card replies with the SHA-256 hash of the challenge and the shared secret followed by its random challenge. The client is thus able to authenticate the card by verifying the card cryptogram (since the client can generate the same and verify that it matches).
\nIn the second phase the client sends the client cryptogram which is the SHA-256 hash of the shared secret and the card challenge. The card verifies the cryptogram and thus authenticates the client. On success the card generates a random 256-bit salt which is appended to the shared secret. The SHA-256 hash of the concatenated value is stored in the first available pairing slot and will be further used to derive session keys. The card responds with the pairing index (which the client must send in all OPEN SECURE CHANNEL commands) and the salt used to generate the key, so that the client can generate and store the same key.
\nThe shared secret is a 256-bit value which must be be known to both parts being paired.
\nThis APDU is sent to unpair a client. An existing secure channel session must be open. The application implementing this protocol may apply additional restrictions, such as the verification of a user PIN. On success the pairing slot at the given index will be freed and will be made available to pair other clients. If the index is already free nothing will happen.
\nResponse Data format:
if P1 = 0x00:
if P1 = 0x01:
\nUsed to set the content of the data file owned by the NDEF applet. This allows changing the behavior of Android and other clients when tapping the card with no open client. As an example, it could be used to launch a specific wallet software.
\nThe data is stored as is. A check is made that the first 2 bytes, read as a MSB first short, are equal to the Lc field minus 2 (the length of the field itself). This does not ensure that the NDEF record is valid, but ensures that no out of bound access happens.
\nUsed to verify the user PIN. On correct PIN entry the card returns 0x9000, the retry counter is reset and the PIN is marked as authenticated for the entire session (until the application is deselected or the card reset/teared). On error, the number of remaining retries is decreased and the SW 0x63CX, where X is the number of available retries is returned. When the number of remaining retries reaches 0 the PIN is blocked. When the PIN is blocked this command always returns 0x63C0, even if the PIN is inserted correctly.
\nUsed to change a PIN or secret. In case of invalid format, the code 0x6A80 is returned. If the conditions match, the PIN or secret is updated. The no-error SW 0x9000 is returned.
\nP1:
\nUsed to unblock the user PIN. The data field must contain exactly 18 numeric digits, otherwise SW 0x6A80 is returned. The first 12 digits are the PUK and the last 6 are the new PIN. If the PUK is correct the PIN is changed to the supplied one, it is unblocked and authenticated for the rest of the session. The status code 0x9000 is returned. When the PUK is wrong, the number of remaining retries is decreased and the SW 0x63CX, where X is the number of available retries is returned. When the number of remaining retries reaches 0 the PUK is blocked. When the PUK is blocked this command always returns 0x63C0, even if the PUK is inserted correctly. In this case the wallet is effectively lost.
\nP1:
\nData:
\nIf P1 is 0x01 or 0x02
\nIf P1 is 0x03 a 64 byte sequence generated according to the BIP39 specifications is expected. The master key will be generated according to the BIP32 specifications. This is only supported if the hardware supports public key derivation.
\nThis command is used to load or replace the keypair used for signing on the card. This command always aborts open signing sessions, if any. Unless a DERIVE KEY is sent, a subsequent SIGN command will use this keypair for signature.
\nThis command is used before a signing session to generate a private key according to the BIP32 specifications. This command always aborts open signing sessions, if any. The generated key is used for all subsequent SIGN sessions. The maximum depth of derivation from the master key is 10. Any attempt to get deeper results in 0x6A80 being returned. The BIP32 specifications define a few checks which must be performed on the derived keys. If these fail, the 0x6984 is returned and the invalid key is discarded. A client should perform a GET STATUS command to get the actual current key path and resume derivation using a different path.
\nThe ability to start derivation from the parent keys allows to more efficiently switch between children of the same key. Note however that only the immediate parent of the current key is cached so you cannot use this to go back in the hierarchy. If no valid parent key is available the status code 0x6B00 will be returned.
\nP1:
\nUsed to generate a mnemonic according to the algorithm specified in BIP39. The returned data is a list of 16-byte integers which should be used as indexes in a wordlist to generate the human-readable mnemonic. Each integer can have a value from 0 to 2047.
\nRemoves the key from the card, bringing it back to an uninitialized state. No signing operation is possible after this command until a new LOAD KEY command is performed.
\nGenerates and stores keys completely on card. The state of the card after execution is the same as if a LOAD KEY command had been performed.
\nP1:
\nThis is the first step to start duplication. Requires an open secure channel and user PIN must be verified. Aborts any on-going duplication session. P2 is the number of entropy pieces to expect in total (including this command). The data contain the first piece of entropy. Returns no data. Must be performed with exactly the same parameters and data on all cards taking part in the duplication.
\nThis command uses the same one-shot secure channel scheme as defined in the INIT command. P2 is 00. Requires an ongoing duplicate session started with the START DUPLICATE subcommand. Must be performed once per device taking part in the duplication process, for a total number of devices equaling the P2 parameter of the START DUPLICATE subcommand (counting the device which sent the START DUPLICATE command as the first device). The data is a random 256-bit number. The same data must be sent to all the cards taking part in the duplication process.
\nThis command must be sent to the card which you wish to duplicate. Requires an open secure channel and authenticated PIN. Works only if a duplication session is active and ADD ENTROPY has been performed the required number of times. Returns the encrypted duplicate of the master key and terminates the duplication session for this card. The format is exactly the same as the one defined in the LOAD KEY (TLV) command with omitted public key. It is however prepended by a 16-bytes IV and the entire TLV structure is encrypted.
\nThis command must be sent to all the cards which are a target for duplication. The Data field must contain the output from the EXPORT DUPLICATE command performed on the source card. Returns the key UID. It follows exactly the same rules as the EXPORT DUPLICATE subcommand.
\nResponse Data format:
\nReturns the ECDSA signature of the hash. The hash can be calculated using any algorithm, but must be 32-bytes long. The signature is returned in a signature template, containing the public key associated to the signature and the signature itself. For usage on the blockchain, you will need to calculate the recovery ID in addition to extracting R and S. To calculate the recovery ID you need to apply the same algorithm used for public key recovery from a transaction starting with a recovery ID of 0. If the public key matches the one returned in the template, then you have found the recovery ID, otherwise you try again by incrementing the recovery ID.
\nSets the given sequence of 32-bit integers as a PIN-less path. When the current derived key matches this path, SIGN will work even if no PIN authentication has been performed. An empty sequence means that no PIN-less path is defined.
\nP1:
0x00 = Current key
0x01 = Derive
0x02 = Derive and make current
P2:
0x00 = private and public key
0x01 = public key only
Response Data format:
\nThis command exports the requested public and private key. The public key can be always exported (P2=0x01), but the private key (P2=0x00) can be exported if and only if the requested key path is in the EIP-1581 subtree.
\nThe P1 parameter indicates how to the derive the desired key. P1 = 0x00 indicates that the current key must be exported, and no derivation will be performed. P1 = 0x01 derives the path given in the data field without changing the current path of the card. P1 = 0x02 derives the path but also changes the current path of the card. The source for derivation can be set by OR’ing P1 with the constants defined in the DERIVE KEY command. This allows deriving from master, parent or current.
\nIf the private key is being exported, the card could omit exporting the public key for performance reason. The public key can then be calculate off-card if needed.
\n","site":{"data":{"menu":{"docs":"/docs/","blog":"https://our.status.im/incubate"},"languages":{"en":"English"},"sidebar":{"api":{"API":{"getting_started":"index.html","java_sdk":"java-sdk.html","apdu":"apdu.html"}}}}},"excerpt":"","more":"These are the commands supported by the application. When a command has a precondition clause and these are not met the SW 0x6985 is returned. All tagged data structures are encoded in the BER-TLV format
\nResponse Data format:
\nThe SELECT command is documented in the ISO 7816-4 specifications and is used to select the application on the card, making it the active one. The data field is the AID of the application. The response is the Application Info template which contains the instance UID (which can be used by the client to keep track of multiple cards) and the public key which must be used by the client to establish the Secure Channel. Additionally it contains the version number of the application, formatted on two bytes. The first byte is the major version and the second is the minor version (e.g: version 1.1 is formatted as 0x0101). The number of remaining pairing slots is also included in the response.
\nThe Key UID can be either empty (when no key is loaded on card) or the SHA-256 hash of the master public key.
\nWhen the applet is in pre-initializated state, it only returns the ECC public key, BER-TLV encoded with tag 0x80.
\nThis command is only available when the applet is in pre-initialized state and successful execution brings the applet in the initialized state. This command is needed to allow securely storing secrets on the applet at a different moment and place than installation is taking place. Currently these are the PIN, PUK and pairing password.
\nThe client must take the public key received after the SELECT command, generate a random keypair and perform EC-DH to generate an AES key. It must then generate a random IV and encrypt the payload using AES-CBC with ISO/IEC 9797-1 Method 2 padding.
\nThey payload is the concatenation of the PIN (6 digits/bytes), PUK (12 digits/bytes) and pairing secret (32 bytes).
\nThis scheme guarantees protection against passive MITM attacks. Since the applet has no “owner” before the execution of this command, protection against active MITM cannot be provided at this stage. However since the communication happens locally (either through NFC or contacted interface) the realization of such an attack at this point is unrealistic.
\nAfter successful execution, this command cannot be executed anymore. The regular SecureChannel (with pairing) is active and PIN and PUK are initialized.
\nThis APDU is the first step to establish a Secure Channel session. A session is aborted when the application is deselected, either directly or because of a card reset/tear.
\nThe card generates a random 256-bit salt which is sent to the client. Both the client and the card do the following for key derivation
\nThe seed IV is used by the client as the IV for the next encrypted APDU.
\nThis APDU allows both parties to verify that the keys generated in the OPEN SECURE CHANNEL step are matching and thus guarantee authentication of the counterpart. The data sent by both parties is a 256-bit random number The APDU data is sent encrypted with the keys generated in the OPEN SECURE CHANNEL step. Each party must verify the MAC of the received APDU. If the MAC can be verified, it means that both parties are using the same keys. Only after this step has been executed the secure channel can be considered to be open and other commands can be sent. If the authentication fails the card must respond with 0x6982. In this case the OPEN SECURE CHANNEL command must be repeated to generate new keys.
\nP1:
\nData:
\nResponse Data:
\nThis APDU is sent to pair a client. Pairing is performed with two commands which must be sent immediately one after the other.
\nIn the first phase the client sends a random challenge to the card. The card replies with the SHA-256 hash of the challenge and the shared secret followed by its random challenge. The client is thus able to authenticate the card by verifying the card cryptogram (since the client can generate the same and verify that it matches).
\nIn the second phase the client sends the client cryptogram which is the SHA-256 hash of the shared secret and the card challenge. The card verifies the cryptogram and thus authenticates the client. On success the card generates a random 256-bit salt which is appended to the shared secret. The SHA-256 hash of the concatenated value is stored in the first available pairing slot and will be further used to derive session keys. The card responds with the pairing index (which the client must send in all OPEN SECURE CHANNEL commands) and the salt used to generate the key, so that the client can generate and store the same key.
\nThe shared secret is a 256-bit value which must be be known to both parts being paired.
\nThis APDU is sent to unpair a client. An existing secure channel session must be open. The application implementing this protocol may apply additional restrictions, such as the verification of a user PIN. On success the pairing slot at the given index will be freed and will be made available to pair other clients. If the index is already free nothing will happen.
\nResponse Data format:
if P1 = 0x00:
if P1 = 0x01:
\nUsed to set the content of the data file owned by the NDEF applet. This allows changing the behavior of Android and other clients when tapping the card with no open client. As an example, it could be used to launch a specific wallet software.
\nThe data is stored as is. A check is made that the first 2 bytes, read as a MSB first short, are equal to the Lc field minus 2 (the length of the field itself). This does not ensure that the NDEF record is valid, but ensures that no out of bound access happens.
\nUsed to verify the user PIN. On correct PIN entry the card returns 0x9000, the retry counter is reset and the PIN is marked as authenticated for the entire session (until the application is deselected or the card reset/teared). On error, the number of remaining retries is decreased and the SW 0x63CX, where X is the number of available retries is returned. When the number of remaining retries reaches 0 the PIN is blocked. When the PIN is blocked this command always returns 0x63C0, even if the PIN is inserted correctly.
\nUsed to change a PIN or secret. In case of invalid format, the code 0x6A80 is returned. If the conditions match, the PIN or secret is updated. The no-error SW 0x9000 is returned.
\nP1:
\nUsed to unblock the user PIN. The data field must contain exactly 18 numeric digits, otherwise SW 0x6A80 is returned. The first 12 digits are the PUK and the last 6 are the new PIN. If the PUK is correct the PIN is changed to the supplied one, it is unblocked and authenticated for the rest of the session. The status code 0x9000 is returned. When the PUK is wrong, the number of remaining retries is decreased and the SW 0x63CX, where X is the number of available retries is returned. When the number of remaining retries reaches 0 the PUK is blocked. When the PUK is blocked this command always returns 0x63C0, even if the PUK is inserted correctly. In this case the wallet is effectively lost.
\nP1:
\nData:
\nIf P1 is 0x01 or 0x02
\nIf P1 is 0x03 a 64 byte sequence generated according to the BIP39 specifications is expected. The master key will be generated according to the BIP32 specifications. This is only supported if the hardware supports public key derivation.
\nThis command is used to load or replace the keypair used for signing on the card. This command always aborts open signing sessions, if any. Unless a DERIVE KEY is sent, a subsequent SIGN command will use this keypair for signature.
\nThis command is used before a signing session to generate a private key according to the BIP32 specifications. This command always aborts open signing sessions, if any. The generated key is used for all subsequent SIGN sessions. The maximum depth of derivation from the master key is 10. Any attempt to get deeper results in 0x6A80 being returned. The BIP32 specifications define a few checks which must be performed on the derived keys. If these fail, the 0x6984 is returned and the invalid key is discarded. A client should perform a GET STATUS command to get the actual current key path and resume derivation using a different path.
\nThe ability to start derivation from the parent keys allows to more efficiently switch between children of the same key. Note however that only the immediate parent of the current key is cached so you cannot use this to go back in the hierarchy. If no valid parent key is available the status code 0x6B00 will be returned.
\nP1:
\nUsed to generate a mnemonic according to the algorithm specified in BIP39. The returned data is a list of 16-byte integers which should be used as indexes in a wordlist to generate the human-readable mnemonic. Each integer can have a value from 0 to 2047.
\nRemoves the key from the card, bringing it back to an uninitialized state. No signing operation is possible after this command until a new LOAD KEY command is performed.
\nGenerates and stores keys completely on card. The state of the card after execution is the same as if a LOAD KEY command had been performed.
\nP1:
\nThis is the first step to start duplication. Requires an open secure channel and user PIN must be verified. Aborts any on-going duplication session. P2 is the number of entropy pieces to expect in total (including this command). The data contain the first piece of entropy. Returns no data. Must be performed with exactly the same parameters and data on all cards taking part in the duplication.
\nThis command uses the same one-shot secure channel scheme as defined in the INIT command. P2 is 00. Requires an ongoing duplicate session started with the START DUPLICATE subcommand. Must be performed once per device taking part in the duplication process, for a total number of devices equaling the P2 parameter of the START DUPLICATE subcommand (counting the device which sent the START DUPLICATE command as the first device). The data is a random 256-bit number. The same data must be sent to all the cards taking part in the duplication process.
\nThis command must be sent to the card which you wish to duplicate. Requires an open secure channel and authenticated PIN. Works only if a duplication session is active and ADD ENTROPY has been performed the required number of times. Returns the encrypted duplicate of the master key and terminates the duplication session for this card. The format is exactly the same as the one defined in the LOAD KEY (TLV) command with omitted public key. It is however prepended by a 16-bytes IV and the entire TLV structure is encrypted.
\nThis command must be sent to all the cards which are a target for duplication. The Data field must contain the output from the EXPORT DUPLICATE command performed on the source card. Returns the key UID. It follows exactly the same rules as the EXPORT DUPLICATE subcommand.
\nResponse Data format:
\nReturns the ECDSA signature of the hash. The hash can be calculated using any algorithm, but must be 32-bytes long. The signature is returned in a signature template, containing the public key associated to the signature and the signature itself. For usage on the blockchain, you will need to calculate the recovery ID in addition to extracting R and S. To calculate the recovery ID you need to apply the same algorithm used for public key recovery from a transaction starting with a recovery ID of 0. If the public key matches the one returned in the template, then you have found the recovery ID, otherwise you try again by incrementing the recovery ID.
\nSets the given sequence of 32-bit integers as a PIN-less path. When the current derived key matches this path, SIGN will work even if no PIN authentication has been performed. An empty sequence means that no PIN-less path is defined.
\nP1:
0x00 = Current key
0x01 = Derive
0x02 = Derive and make current
P2:
0x00 = private and public key
0x01 = public key only
Response Data format:
\nThis command exports the requested public and private key. The public key can be always exported (P2=0x01), but the private key (P2=0x00) can be exported if and only if the requested key path is in the EIP-1581 subtree.
\nThe P1 parameter indicates how to the derive the desired key. P1 = 0x00 indicates that the current key must be exported, and no derivation will be performed. P1 = 0x01 derives the path given in the data field without changing the current path of the card. P1 = 0x02 derives the path but also changes the current path of the card. The source for derivation can be set by OR’ing P1 with the constants defined in the DERIVE KEY command. This allows deriving from master, parent or current.
\nIf the private key is being exported, the card could omit exporting the public key for performance reason. The public key can then be calculate off-card if needed.
\n"},{"id":"java-sdk","title":"Keycard Java SDK","_content":"\n## Installation\n\nYou can import the SDK in your Gradle or Maven project using [Jitpack.io](https://jitpack.io). If using Gradle, to use\nJitPack all you have to do is insert these lines in you `build.gradle` file\n\n```groovy\nallprojects {\n repositories {\n maven { url 'https://jitpack.io' }\n }\n}\n```\n\nThen, you must import the correct dependency. In case you are building an Android-based project, you need to add this line\n\n```groovy\ndependencies {\n implementation 'com.github.status-im.status-keycard-java:android:2.0.0'\n}\n```\n\nIf you are working on the desktop, then you need this line instead\n\n```groovy\ndependencies {\n implementation 'com.github.status-im.status-keycard-java:desktop:2.0.0'\n}\n```\n\nIn both case, you will have the same SDK, except for the way connection with the card is established.\n\n## Connecting to the card (Android)\n\nOn Android, the NFC connection handling must happen on a thread separate from the UI thread. The SDK provides the class `NFCCardManager` to handle this. This an example activity starting the NFC reader and handling the connection to the card. Refer to the comments in the example for more information.\n\n```java\npublic class MainActivity extends AppCompatActivity {\n private NfcAdapter nfcAdapter;\n private NFCCardManager cardManager;\n\n @Override\n protected void onCreate(Bundle savedInstanceState) {\n super.onCreate(savedInstanceState);\n setContentView(R.layout.activity_main);\n \n // Get the Android NFC default adapter\n nfcAdapter = NfcAdapter.getDefaultAdapter(this);\n \n // Create the NFCCardManager, this class is provided by the Keycard SDK and handles connections to the card\n cardManager = new NFCCardManager();\n\n // The Card Listener receives the connected/disconnected events. These can happen at any time since the user can\n // introduce or remove the card to/from the field at any time. This is where your code goes.\n cardManager.setCardListener(new CardListener() {\n @Override\n public void onConnected(CardChannel cardChannel) {\n // Card is connected. Here you can start working with the Keycard. The CardChannel is what you will use to\n // communicate with the card.\n }\n\n @Override\n public void onDisconnected() {\n // Card is disconnected (was removed from the field). You can perform cleanup here.\n }\n });\n cardManager.start();\n }\n\n @Override\n public void onResume() {\n super.onResume();\n \n // We need to enable the reader on resume.\n if (nfcAdapter != null) {\n nfcAdapter.enableReaderMode(this, this.cardManager, NfcAdapter.FLAG_READER_NFC_A | NfcAdapter.FLAG_READER_SKIP_NDEF_CHECK, null);\n }\n }\n\n @Override\n public void onPause() {\n super.onPause();\n \n // We disable the reader on pause to allow other apps to use it.\n if (nfcAdapter != null) {\n nfcAdapter.disableReaderMode(this);\n }\n }\n}\n```\n\n## Connecting to the card (Desktop)\n\nOn the desktop we use the javax.smartcardio library. There are several ways to handle connections, the important part is getting a CardChannel open. Below is an example of how this can be achieved (assumes that a single smartcard reader is connected).\n\n```java\n// We create a TerminalFactory object\nTerminalFactory tf = TerminalFactory.getDefault();\nCardTerminal cardTerminal;\n\n// We search a terminal with a card inside\nfor (CardTerminal t : tf.terminals().list()) {\nif (t.isCardPresent()) {\n cardTerminal = t;\n break;\n }\n }\n}\n\n// If not found, we throw an exception. Of course you should decide how to handle this situation\nif (cardTerminal == null) {\n throw new RuntimeException(\"No terminal found\");\n}\n\n// If a terminal is found, we connect to it\nCard apduCard = cardTerminal.connect(\"*\");\n\n// We create a PCSCCardChannel, which is an implementation of CardChannel and can be used with the rest of the SDK.\nPCSCCardChannel apduChannel = new PCSCCardChannel(apduCard.getBasicChannel());\n```\n\n## Working with the card\n\nRegardless whether you are on Android or desktop, you should at this point have an implementation of the CardChannel interface (be it NFCCardChannel or PCSCCardChannel). You can now start working with the card. The first thing to do is creating a `KeycardCommandSet` instance. This class gives access to all of the applet functionality, wrapping the low-level APDUs in easy to use methods. All other classes in the SDK are helper to format parameters and parse responses from the card. To create a command set, just do\n\n```java\n// cardChannel is our CardChannel instance\nKeycardCommandSet cmdSet = new KeycardCommandSet(cardChannel);\n```\n\nModern SmartCards can have several applications installed, so after connection with the card you need to select the Keycard applet. This is easily done with\n\n```java\n// The checkOK method can be called on any APDUResponse object to confirm that the\ncmdSet.select().checkOK();\n```\n\nWhile this correctly selects the applet, it discards the card response, which contains information that can be useful to identify this specific card and its state. For this reason we could rewrite this as\n\n```java\nApplicationInfo info = new ApplicationInfo(cmdSet.select().checkOK().getData());\n\n// This method tells if the card is initialized (has a PIN, PUK and pairing password). If it is not, it must be\n// initialized and no other operation is possible. Note that initialization touches only credentials to authenticate\n// the user or the client, but does not touch the creation of a wallet on the card\ninfo.isInitializedCard();\n\n// Returns the instance UID of the applet. This can be used to identify this specific applet instance, very\n// useful when storing instance-specific data on the client (pairing info, cached data, etc).\ninfo.getInstanceUID();\n\n// Returns the version of the applet.\ninfo.getAppVersion();\n\n// Returns the number of free pairing slots. If you are not yet paired with the card, it helps you know if you can still\n// pair or not\ninfo.getFreePairingSlots());\n\n// Tells if the card has a wallet or not. If no wallet is available, you must create once before you can perform most\n// operations on the card\ninfo.hasMasterKey();\n\n// Returns the UID of the master key of the wallet. The UID is value generated starting from the public key and is \n// useful to identify if the card has the expected wallet.\ninfo.getKeyUID();\n```\n\nAfter the applet is selected, you can start working with it. Note that the application remains selected until another applet is explicitly selected, or the card is powered off (for example is removed from the field)\n\n### Initialization\n\nThis step is necessary to bring the initial credentials on the Keycard instance. When the card is not initialized, it cannot perform any operation. Initialization sets the initial PIN, PUK and pairing password and requires no authentication, but still uses a SecureChannel resistant to passive MITM attacks. Once the card is initialized, it cannot be initialized again (but credentials can be different with a different mechanism with previous authentication).\n\nInitialization is done with\n\n```java\n// Usually, you want to check if the card is initialized before trying to initialize it, otherwise you will receive an\n// error.\nif (!info.isInitializedCard()) {\n // The PIN must be 6 digits, the PUK 12 digits and the pairing password can be any password. \n // All parameters are strings\n cmdSet.init(pin, puk, pairingPassword).checkOK();\n}\n```\n\n### Pairing\n\nClients wishing to communicate with the card, need to pair with it first. This allows creating secure channels resistant not only to passive but also to active MITM attacks. Although pairing allows the card and the client to authenticate each other, the card does not grant access to any operation with the wallet until the user is authenticated (by verifying its PIN). To establish the pairing, the client needs to know the pairing password. After it is established, the pairing info (not the password) must be stored as securely as possible on the client for subsequent sessions. You should store the pairing information together with the instance UID to simplify handling of multiple cards.\n\nOnly 5 clients can be paired at once, but it is possible to unpair previously paired clients.\n\nUsing the SDK, pairing is a simple operation\n\n```java\n// pairingPassword is usually provided by the user. This method throws an exception if pairing fails.\ncmdSet.autoPair(pairingPassword);\n// Retrieves the pairing object from the command set. This is what must be persisted (together with the instance UID)\nPairing pairing = cmdSet.getPairing();\n// The pairing object can be serialized by calling\npairing.toByteArray();\n// or the convenience method\npairing.toBase64();\n```\n\nIf you have already paired, you should instead load the persisted pairing information in the command set\n\n```java\n// serializedPairing can be either the byte array or base64 string representation\nPairing pairing = new Pairing(serializedPairing);\n// Sets the pairing info in the command set. This must be done before further operation is possible\ncmdSet.setPairing(pairing);\n```\n\n### Secure Channel\n\nAfter a pairing has been established, a secure channel can be opened. Before opening a secure channel, the card won't allow sending any command. This guarantees secrecy, integrity and authenticity of the commands. Opening a secure channel must be performed every time the applet is selected (this means also after a power loss). After opening it, the SDK handles the secure channel transparently, encrypting and signing all command APDUs and decrypting and verifying the signature of all responses. To open a secure channel all you need to do is\n\n```java\ncmdSet.autoOpenSecureChannel();\n```\n\n### Authenticating the user\n\nMost operations with the card (all involving operations with the wallet or credentials) require authenticating the user. After authentication, the user remains authenticated until the card is powered off or the application is re-selected.\n\nAuthentication is performed by verifying the user PIN. Note that this piece of information is sensitive and must be handled accordingly in the application. PIN verification is done with a single step\n\n```java\n// pin is the user PIN as a string of 6 digits\ntry {\n cmdSet.verifyPIN(pin).checkAuthOK();\n} catch(WrongPINException e) {\n System.out.println(\"Number of remaining attempts: \" + e.getRetryAttempts());\n}\n```\n\nif the PIN is wrong, you will receive an error SW in the format 0x63CX where X is the number of attempts remaining. When the number of remaining attempts is 0, the card is blocked. The user must then enter the PUK and a new PIN to restore access to the card. The maximum number of retries for the PUK is 5. To simplify things, the `APDUResponse.checkAuthOK()` method can be used to verify if the authentication was correct, and if not throw a `WrongPINException` which contains the number of remaining attempts.\n\n```java\ncmdSet.unblockPIN(puk, newPIN).checkAuthOK();\n```\n\n## Creating a wallet\n\nTo actually use the Keycard, it needs to have a wallet. This can be achieved in several different ways, which one you choose depends on your usage scenario. Creating a wallet requires user authentication and is possible even if a wallet already exists on the card (the new wallet replaces the old one). Use the `ApplicationInfo.hasMasterKey()` method to determine if the card already has a wallet or not. Note that the response of the `KeycardCommandSet.loadKey` method contains the key UID of the created wallet. This UID can be stored to keep track of this specific wallet in the client. The UID is tied to the key itself (is derived from the public key) so it will change if the wallet on card is replaced. The key UID is also part of the response of the applet selection command, so the wallet can be identified immediately upon selection.\n\n### Creating a BIP39 mnemonic phrase\n\nThis method is great for interoperability with other wallets. The card can assist in creating the mnemonic phrase, since it features a TRNG. Generating the mnemonic itself does not require user authentication (since it does not modify the card state), but loading the key derived from it does. Example of the entire procedure is below\n\n```java\n// Generates a Mnemonic object from the card. You can choose between generating 12, 15, 18, 21 or 24 words\nMnemonic mnemonic = new Mnemonic(cmdSet.generateMnemonic(KeycardCommandSet.GENERATE_MNEMONIC_12_WORDS).checkOK().getData());\n\n// We need to set a wordlist if we plan using this object to derive the binary seed. We can set our own list or we can\n// fatch the official BIP39 english word list as shown below.\nmnemonic.fetchBIP39EnglishWordlist();\n\n// If we did not verify the PIN before, we can do it now\ncmdSet.verifyPIN(pin).checkOK();\n\n// Loads the key generated from the mnemonic phrase.\ncmdSet.loadKey(mnemonic.toBIP32KeyPair()).checkOK();\n```\n\n### Importing a wallet from BIP39 mnemonic phrase\n\nImporting an existing passphrase requires only the loading step.\n\n```java\n// The passphrase is a string with space separated words. The password can be any non-null string, usually is empty.\ncmdSet.loadKey(Mnemonic.toBinarySeed(passphrase, password)).checkOK();\n```\n\n### Generating keys on-card\n\nThis is the simplest and safest method, because the generated wallet never leaves the card and there is no \"paper backup\" to keep secure. It is possible to create secure duplicates of the wallet on other Keycards, with a mechanism described in later chapters. Using the SDK, you simply do\n\n```java\ncmdSet.generateKey().checkOK();\n```\n\n### Importing an EC keypair\n\nYou can import on the keycard any EC keypair on the SECP256k1 curve, with or without the BIP32 extension. If your import a key without the BIP32 extension, then key derivation will not work, but you will still be able to use the Keycard for signing transactions using the imported key. This scenario can be useful if you are migrating from a wallet not using BIP39 passphrases or for wallets following some custom generation rules. It is however generally preferable to use one of the methods presented above.\n\nAn example of key import is\n\n```java\n// privKey is the S component of the key, as a 32-byte long byte array\n// chainCode is the extension to the keypair defined by BIP32, this is another 32-byte long byte array. Can be null, in\n// which case the created wallet won't be BIP32 compatible.\n// pubKey is the DER encoded, uncompressed public key. Can be null, in which case it is automatically calculated from\n// the private key.\nBIP32KeyPair keypair = new BIP32KeyPair(privKey, chainCode, pubKey);\n\n// Loads the keypair\ncmdSet.loadKey(keypair).checkOK();\n```\n\n## Key derivation\n\nAs mentioned before, the Keycard is a BIP32 compatible wallet. This means that it can perform key derivation as defined by the BIP32 specification in order to create a hierarchical deterministic wallet. When deriving a key, this key becomes active, which means that it will be used for all signing operations until a key with a different path is derived. The active key is persisted across sessions, meaning that a power loss or applet reselection does not reset it.\n\nWhen creating or importing a wallet to the Keycard, the active key is the master key. Unless you imported a non-BIP32 compatible wallet, you usually want to set the active key to a currency account by following the BIP44 specifications for paths. Note that the maximum depth of the key path is 10, excluding the master key.\n\nKey derivation requires user authentication\n\nSince a line of code is worth a thousand words, below is an example of deriving a standard key path\n\n```java\ncmdSet.deriveKey(\"m/44'/0'/0'/0/0\").checkOK();\n```\n\nSince deriving a key is an expensive operation, you usually want to know what the current path is before performing derivation. You can do this with\n\n```java\n// you can then get is as a string with currentPath.toString()\nKeyPath currentPath = new KeyPath(cmdSet.getStatus(KeycardCommandSet.GET_STATUS_P1_KEY_PATH).checkOK().getData());\n```\n\nTo speed up operations, key derivation can be started not only from the master key, but also from the parent or the current key. The path in this case starts respectively with \"../\" and \"./\". You cannot navigate the hierarchy with multiple \"..\" in the paths, because only the direct parent of the current key is cached. Derivation from parent is especially convenient when switching between accounts of the same type. Example\n\n```java\n// Derive the main account\ncmdSet.deriveKey(\"m/44'/0'/0'/0/0\").checkOK();\n\n// switch a secondary account, equivalent to \"m/44'/0'/0'/0/1\" but much faster\ncmdSet.deriveKey(\"../1\").checkOK();\n\n// you can switch back and forth between siblings without limitations.\ncmdSet.deriveKey(\"../0\").checkOK();\n```\n\n## Signing\n\nYour Keycard has been initialized, has a wallet and you have derived the keypath you need. You can now perform transactions by signing them with the card. Since the Keycard has no user input/output capabilities, it would be useless to transfer the entire transaction to the card for signing. You should instead calculate the transaction hash, according to the rules of the cryptocurrency you are handling and send that for signature instead. This also means, that you can handle anything which requires ECDSA signatures over SECP256k1 curve, regardless of the used hashing algorithm (at the condition that it output a 256-bit hash of course). This opens the door to signing transactions for the most common cryptocurrencies, but also makes it usable outside the realm of crypto transactions.\n\nSigning is done as\n\n```java\n// hash is the hash to sign, for example the Keccak-256 hash of an Ethereum transaction\n// the signature object contains r, s, recId and the public key associated to this signature\nRecoverableSignature signature = new RecoverableSignature(hash, cmdSet.sign(hash).checkOK().getData());\n```\n\nSigning requires user authentication.\n\n## Exporting (public or EIP-1581 compliant) keys\n\nSorry for the long title, but let's make it immediately clear: the keys used to sign transactions never leave the card and cannot be exported. You can however export any public key as well as the private key of keypaths defined in the [EIP-1581 specifications](https://eips.ethereum.org/EIPS/eip-1581). Those keys, by design, are not to be used for transactions but are instead usable for operations with lower security concerns where caching or storing the key outside the card might be beneficial from an UX point of view. Of course, exporting a key always requires user authentication.\n\n### Exporting the current key\n\n```java\n// Exports the current public key. This is allowed for any key path\nBIP32KeyPair publicKey = BIP32KeyPair.fromTLV(cmdSet.exportCurrentKey(true).checkOK().getData());\n\n// Exports the entire key pair. This is only allowed for key path following the EIP-1581 definition\nBIP32KeyPair keypair = BIP32KeyPair.fromTLV(cmdSet.exportCurrentKey(false).checkOK().getData());\n```\n\n### Derive & export\n\nThe export command is very powerful, since it allows you to derive & export a key in one step. You have the option to make the derived and exported key active or leave the active key untouched. You can also decide whether to export only the public key or the entire keypair (following the rules defined above).\n\nA very convenient use case is deriving an account key and retrieving the public key in one step. This is faster than doing it with two commands (derive key and export public), because every command processed has some overhead. Example\n\n```java\n// The first parameter is the keypath, the second tells whether that you want to make the derived & exported key active\n// and the third tells that you only want the public key to be exported.\nBIP32KeyPair publicKey = BIP32KeyPair.fromTLV(cmdSet.exportKey(\"m/44'/0'/0'/0/0\", true, true).checkOK().getData());\n\n// The line above is equivalent to\n// cmdSet.deriveKey(\"m/44'/0'/0'/0/0\").checkOK();\n// BIP32KeyPair publicKey = BIP32KeyPair.fromTLV(cmdSet.exportCurrentKey(true).checkOK().getData());\n```\n\nAnother use case, is to export keys defined by EIP-1581 without changing the current active key, since you won't be signing with the exported key using the card\n\n```java\n// Let's assume the current active path is \"m/44'/0'/0'/0/0\"\n\n// The first parameter is the key path, the second tells that you do not want to make it current and the third that you\n// want the entire keypair, not only the public key\nBIP32KeyPair keypair = BIP32KeyPair.fromTLV(cmdSet.exportKey(\"m/43'/60'/1581'/0'/0\", false, false).checkOK().getData());\n\n// At this point, the current active path would still be \"m/44'/0'/0'/0/0\"\n```\n\n## Changing credentials\n\nAll credentials of the Keycard can be changed (PIN, PUK, pairing password). Changing the pairing password does not invalidate existing pairings, but applies to the ones which can be created in the future. Changing credentials, requires user authentication.\n\n```java\n// Changes the user PIN\ncmdSet.changePIN(\"123456\").checkOK();\n\n// Changes the PUK\ncmdSet.changePUK(\"123456123456\").checkOK();\n\n// Changes the pairing password\ncmdSet.changePairingPassword(\"my pairing password\").checkOK();\n```\n\n## Duplication\n\nCard duplication is especially relevant when the keys have been generated on-card, without using BIP39 mnemonic (or when this has been destroyed). To make duplication secure the client must not possess the (full) encryption key. For this reason, a scheme where multiple clients are used and none of them has the full key has been devised. From the user point of view, the duplication process goes like this\n\n1. Take the card to be duplicated (source) and one or more cards to duplicate to (target)\n2. On one of the user's clients initiate the duplication. This involves entering the PIN of each of the involved cards\n3. Tap all cards to one or more additional clients (the amount must be defined before, the order is irrelevant). These clients do not need to be paired or be trusted, so the user can borrow a friend's phone without compromising security. This step does not require entering a PIN\n4. On one of the user's clients, usually the same which initiated the duplication (must be paired, trusted) finalize the duplication by first tapping the source card and then all target cards, again inserting the PIN for each.\n \nAt the end of procedure, each card will have the same master key, but PIN, PUK and pairing key remain unchanged and are independent from each other. A client could propose changing them to be all the same if desired or do this automatically. All cards are fully functional, so at this point there isn't any difference between the source card and the targets.\n\nSince the cards are still protected by the PIN, these can be stored remotely in moderately trusted places to recover from lost or destroyed cards. The duplication has been performed securely since no client ever had the full encryption key and no authentication credentials has been inserted on untrusted clients. For flexibility reason, an arbitrary number of clients can be used. Using a single client could be convenient from an UX point of view, but relies on said client not being compromised. Using 2 or 3 clients greatly increases security. More than 3 clients is probably an overkill.\n\nFrom an implementation point of view, we have two different roles a client can take\n\n1. The trusted client, starting and performing the duplication\n2. The (possibly) untrusted clients, only adding entropy to the encryption key\n\nBoth can be implemented by using the `CardDuplicator` class. On each client, the same instance of the `CardDuplicator` class must be used for the entire duplication process, otherwise duplication will fail.\n\nThe trusted client must also provide an implementation of `DuplicatorCallback`. This is needed to retrieve the Pairing and PIN for each card. Example below\n\n```java\nclass MyDuplicatorCB implements DuplicatorCallback {\n Pairing getPairing(ApplicationInfo applicationInfo) {\n // The Instance UID is the one to use when storing/retrieving pairings\n byte[] uid = applicationInfo.getInstanceUID();\n \n // Using the UID try to retrieve the pairing. The method getSavedPairing is an example and is not part of the SDK,\n // you are responsible of how you store and retrieve pairing data in your app\n Pairing pairing = getSavedPairing(uid);\n \n // Optionally, you could prompt the user and make a new pairing if none if given, but this is an UX decision in\n // your application.\n if (pairing == null) {\n pairing = tryToPair();\n }\n \n // possibly null, in this case the operation requiring pairing is aborted\n return pairing;\n }\n \n String getPIN(ApplicationInfo applicationInfo, int remainingAttempts) {\n // Optionally, you might have a cache of PINs for recently used card, but this should be done carefully as the PIN\n // is sensitive data. You might instead want to just prompt the user each time.\n String pin = getCachedPIN(applicationInfo.getInstanceUID());\n \n if (pin == null) {\n // prompt the user to insert the PIN. You can optionally inform them about how many retry attempts are left.\n // For UX reason you could also use the instance UID to show the user an identifiable name, this is again\n // application specific.\n pin = promptUser(remainingAttempts);\n }\n \n // This must not be null. PIN verification will be performed by the CardDuplicator itself, do no not perform it here!\n return pin;\n }\n}\n```\n\nThe next step to do, is instantiating a CardDuplicator.\n\nFor the trusted client\n\n```java\n// The cmdSet is a KeycardCommandSet instance, duplicatorCallback is an object implementing the DuplicatorCallback\n// interface\ncardDuplicator = new CardDuplicator(cmdSet, duplicatorCallback);\n```\n\nFor the untrusted clients\n\n```java\n// apduChannel is a CardChannel instance. Alternatively the same constructor as for the trusted client can be used,\n// passing null as the second parameter.\ncardDuplicator = new CardDuplicator(apduChannel);\n```\n\nOnce the instance has been created, depending on the role and state the client must perform a specific action every time a new card is presented. The CardDuplicator keeps track of the action performed on any card, so if the user presents the same card twice an `IllegalStateException` exception is thrown.\n\nTo start duplication on a card, for example, you might do\n\n```java\n// Client count is the amount of devices contributing to forming the entire key. This means 1 + the number of clients\n// which will be adding entropy (the untrusted clients)\ncardDuplicator.startDuplication(clientCount);\n```\n\nOn untrusted clients, to add entropy, you do\n\n```java\ncardDuplicator.addEntropy();\n```\n\nWhen the full key has been stored on all cards, you then call the following method on the source card on a trusted client\n\n```java\nbyte[] exportedKey = cardDuplicator.exportKey();\n```\n\nwhereas, from the same client, you invoke on all target cards the following\n\n```java\n// you should then check that the keyUID matches the one of the source card to be sure that the duplication has been\n// performed correctly.\nbyte[] keyUID = cardDuplicator.importKey(exportedKey);\n```\n","source":"api/java-sdk.md","raw":"---\nid: java-sdk\ntitle: Keycard Java SDK\n---\n\n## Installation\n\nYou can import the SDK in your Gradle or Maven project using [Jitpack.io](https://jitpack.io). If using Gradle, to use\nJitPack all you have to do is insert these lines in you `build.gradle` file\n\n```groovy\nallprojects {\n repositories {\n maven { url 'https://jitpack.io' }\n }\n}\n```\n\nThen, you must import the correct dependency. In case you are building an Android-based project, you need to add this line\n\n```groovy\ndependencies {\n implementation 'com.github.status-im.status-keycard-java:android:2.0.0'\n}\n```\n\nIf you are working on the desktop, then you need this line instead\n\n```groovy\ndependencies {\n implementation 'com.github.status-im.status-keycard-java:desktop:2.0.0'\n}\n```\n\nIn both case, you will have the same SDK, except for the way connection with the card is established.\n\n## Connecting to the card (Android)\n\nOn Android, the NFC connection handling must happen on a thread separate from the UI thread. The SDK provides the class `NFCCardManager` to handle this. This an example activity starting the NFC reader and handling the connection to the card. Refer to the comments in the example for more information.\n\n```java\npublic class MainActivity extends AppCompatActivity {\n private NfcAdapter nfcAdapter;\n private NFCCardManager cardManager;\n\n @Override\n protected void onCreate(Bundle savedInstanceState) {\n super.onCreate(savedInstanceState);\n setContentView(R.layout.activity_main);\n \n // Get the Android NFC default adapter\n nfcAdapter = NfcAdapter.getDefaultAdapter(this);\n \n // Create the NFCCardManager, this class is provided by the Keycard SDK and handles connections to the card\n cardManager = new NFCCardManager();\n\n // The Card Listener receives the connected/disconnected events. These can happen at any time since the user can\n // introduce or remove the card to/from the field at any time. This is where your code goes.\n cardManager.setCardListener(new CardListener() {\n @Override\n public void onConnected(CardChannel cardChannel) {\n // Card is connected. Here you can start working with the Keycard. The CardChannel is what you will use to\n // communicate with the card.\n }\n\n @Override\n public void onDisconnected() {\n // Card is disconnected (was removed from the field). You can perform cleanup here.\n }\n });\n cardManager.start();\n }\n\n @Override\n public void onResume() {\n super.onResume();\n \n // We need to enable the reader on resume.\n if (nfcAdapter != null) {\n nfcAdapter.enableReaderMode(this, this.cardManager, NfcAdapter.FLAG_READER_NFC_A | NfcAdapter.FLAG_READER_SKIP_NDEF_CHECK, null);\n }\n }\n\n @Override\n public void onPause() {\n super.onPause();\n \n // We disable the reader on pause to allow other apps to use it.\n if (nfcAdapter != null) {\n nfcAdapter.disableReaderMode(this);\n }\n }\n}\n```\n\n## Connecting to the card (Desktop)\n\nOn the desktop we use the javax.smartcardio library. There are several ways to handle connections, the important part is getting a CardChannel open. Below is an example of how this can be achieved (assumes that a single smartcard reader is connected).\n\n```java\n// We create a TerminalFactory object\nTerminalFactory tf = TerminalFactory.getDefault();\nCardTerminal cardTerminal;\n\n// We search a terminal with a card inside\nfor (CardTerminal t : tf.terminals().list()) {\nif (t.isCardPresent()) {\n cardTerminal = t;\n break;\n }\n }\n}\n\n// If not found, we throw an exception. Of course you should decide how to handle this situation\nif (cardTerminal == null) {\n throw new RuntimeException(\"No terminal found\");\n}\n\n// If a terminal is found, we connect to it\nCard apduCard = cardTerminal.connect(\"*\");\n\n// We create a PCSCCardChannel, which is an implementation of CardChannel and can be used with the rest of the SDK.\nPCSCCardChannel apduChannel = new PCSCCardChannel(apduCard.getBasicChannel());\n```\n\n## Working with the card\n\nRegardless whether you are on Android or desktop, you should at this point have an implementation of the CardChannel interface (be it NFCCardChannel or PCSCCardChannel). You can now start working with the card. The first thing to do is creating a `KeycardCommandSet` instance. This class gives access to all of the applet functionality, wrapping the low-level APDUs in easy to use methods. All other classes in the SDK are helper to format parameters and parse responses from the card. To create a command set, just do\n\n```java\n// cardChannel is our CardChannel instance\nKeycardCommandSet cmdSet = new KeycardCommandSet(cardChannel);\n```\n\nModern SmartCards can have several applications installed, so after connection with the card you need to select the Keycard applet. This is easily done with\n\n```java\n// The checkOK method can be called on any APDUResponse object to confirm that the\ncmdSet.select().checkOK();\n```\n\nWhile this correctly selects the applet, it discards the card response, which contains information that can be useful to identify this specific card and its state. For this reason we could rewrite this as\n\n```java\nApplicationInfo info = new ApplicationInfo(cmdSet.select().checkOK().getData());\n\n// This method tells if the card is initialized (has a PIN, PUK and pairing password). If it is not, it must be\n// initialized and no other operation is possible. Note that initialization touches only credentials to authenticate\n// the user or the client, but does not touch the creation of a wallet on the card\ninfo.isInitializedCard();\n\n// Returns the instance UID of the applet. This can be used to identify this specific applet instance, very\n// useful when storing instance-specific data on the client (pairing info, cached data, etc).\ninfo.getInstanceUID();\n\n// Returns the version of the applet.\ninfo.getAppVersion();\n\n// Returns the number of free pairing slots. If you are not yet paired with the card, it helps you know if you can still\n// pair or not\ninfo.getFreePairingSlots());\n\n// Tells if the card has a wallet or not. If no wallet is available, you must create once before you can perform most\n// operations on the card\ninfo.hasMasterKey();\n\n// Returns the UID of the master key of the wallet. The UID is value generated starting from the public key and is \n// useful to identify if the card has the expected wallet.\ninfo.getKeyUID();\n```\n\nAfter the applet is selected, you can start working with it. Note that the application remains selected until another applet is explicitly selected, or the card is powered off (for example is removed from the field)\n\n### Initialization\n\nThis step is necessary to bring the initial credentials on the Keycard instance. When the card is not initialized, it cannot perform any operation. Initialization sets the initial PIN, PUK and pairing password and requires no authentication, but still uses a SecureChannel resistant to passive MITM attacks. Once the card is initialized, it cannot be initialized again (but credentials can be different with a different mechanism with previous authentication).\n\nInitialization is done with\n\n```java\n// Usually, you want to check if the card is initialized before trying to initialize it, otherwise you will receive an\n// error.\nif (!info.isInitializedCard()) {\n // The PIN must be 6 digits, the PUK 12 digits and the pairing password can be any password. \n // All parameters are strings\n cmdSet.init(pin, puk, pairingPassword).checkOK();\n}\n```\n\n### Pairing\n\nClients wishing to communicate with the card, need to pair with it first. This allows creating secure channels resistant not only to passive but also to active MITM attacks. Although pairing allows the card and the client to authenticate each other, the card does not grant access to any operation with the wallet until the user is authenticated (by verifying its PIN). To establish the pairing, the client needs to know the pairing password. After it is established, the pairing info (not the password) must be stored as securely as possible on the client for subsequent sessions. You should store the pairing information together with the instance UID to simplify handling of multiple cards.\n\nOnly 5 clients can be paired at once, but it is possible to unpair previously paired clients.\n\nUsing the SDK, pairing is a simple operation\n\n```java\n// pairingPassword is usually provided by the user. This method throws an exception if pairing fails.\ncmdSet.autoPair(pairingPassword);\n// Retrieves the pairing object from the command set. This is what must be persisted (together with the instance UID)\nPairing pairing = cmdSet.getPairing();\n// The pairing object can be serialized by calling\npairing.toByteArray();\n// or the convenience method\npairing.toBase64();\n```\n\nIf you have already paired, you should instead load the persisted pairing information in the command set\n\n```java\n// serializedPairing can be either the byte array or base64 string representation\nPairing pairing = new Pairing(serializedPairing);\n// Sets the pairing info in the command set. This must be done before further operation is possible\ncmdSet.setPairing(pairing);\n```\n\n### Secure Channel\n\nAfter a pairing has been established, a secure channel can be opened. Before opening a secure channel, the card won't allow sending any command. This guarantees secrecy, integrity and authenticity of the commands. Opening a secure channel must be performed every time the applet is selected (this means also after a power loss). After opening it, the SDK handles the secure channel transparently, encrypting and signing all command APDUs and decrypting and verifying the signature of all responses. To open a secure channel all you need to do is\n\n```java\ncmdSet.autoOpenSecureChannel();\n```\n\n### Authenticating the user\n\nMost operations with the card (all involving operations with the wallet or credentials) require authenticating the user. After authentication, the user remains authenticated until the card is powered off or the application is re-selected.\n\nAuthentication is performed by verifying the user PIN. Note that this piece of information is sensitive and must be handled accordingly in the application. PIN verification is done with a single step\n\n```java\n// pin is the user PIN as a string of 6 digits\ntry {\n cmdSet.verifyPIN(pin).checkAuthOK();\n} catch(WrongPINException e) {\n System.out.println(\"Number of remaining attempts: \" + e.getRetryAttempts());\n}\n```\n\nif the PIN is wrong, you will receive an error SW in the format 0x63CX where X is the number of attempts remaining. When the number of remaining attempts is 0, the card is blocked. The user must then enter the PUK and a new PIN to restore access to the card. The maximum number of retries for the PUK is 5. To simplify things, the `APDUResponse.checkAuthOK()` method can be used to verify if the authentication was correct, and if not throw a `WrongPINException` which contains the number of remaining attempts.\n\n```java\ncmdSet.unblockPIN(puk, newPIN).checkAuthOK();\n```\n\n## Creating a wallet\n\nTo actually use the Keycard, it needs to have a wallet. This can be achieved in several different ways, which one you choose depends on your usage scenario. Creating a wallet requires user authentication and is possible even if a wallet already exists on the card (the new wallet replaces the old one). Use the `ApplicationInfo.hasMasterKey()` method to determine if the card already has a wallet or not. Note that the response of the `KeycardCommandSet.loadKey` method contains the key UID of the created wallet. This UID can be stored to keep track of this specific wallet in the client. The UID is tied to the key itself (is derived from the public key) so it will change if the wallet on card is replaced. The key UID is also part of the response of the applet selection command, so the wallet can be identified immediately upon selection.\n\n### Creating a BIP39 mnemonic phrase\n\nThis method is great for interoperability with other wallets. The card can assist in creating the mnemonic phrase, since it features a TRNG. Generating the mnemonic itself does not require user authentication (since it does not modify the card state), but loading the key derived from it does. Example of the entire procedure is below\n\n```java\n// Generates a Mnemonic object from the card. You can choose between generating 12, 15, 18, 21 or 24 words\nMnemonic mnemonic = new Mnemonic(cmdSet.generateMnemonic(KeycardCommandSet.GENERATE_MNEMONIC_12_WORDS).checkOK().getData());\n\n// We need to set a wordlist if we plan using this object to derive the binary seed. We can set our own list or we can\n// fatch the official BIP39 english word list as shown below.\nmnemonic.fetchBIP39EnglishWordlist();\n\n// If we did not verify the PIN before, we can do it now\ncmdSet.verifyPIN(pin).checkOK();\n\n// Loads the key generated from the mnemonic phrase.\ncmdSet.loadKey(mnemonic.toBIP32KeyPair()).checkOK();\n```\n\n### Importing a wallet from BIP39 mnemonic phrase\n\nImporting an existing passphrase requires only the loading step.\n\n```java\n// The passphrase is a string with space separated words. The password can be any non-null string, usually is empty.\ncmdSet.loadKey(Mnemonic.toBinarySeed(passphrase, password)).checkOK();\n```\n\n### Generating keys on-card\n\nThis is the simplest and safest method, because the generated wallet never leaves the card and there is no \"paper backup\" to keep secure. It is possible to create secure duplicates of the wallet on other Keycards, with a mechanism described in later chapters. Using the SDK, you simply do\n\n```java\ncmdSet.generateKey().checkOK();\n```\n\n### Importing an EC keypair\n\nYou can import on the keycard any EC keypair on the SECP256k1 curve, with or without the BIP32 extension. If your import a key without the BIP32 extension, then key derivation will not work, but you will still be able to use the Keycard for signing transactions using the imported key. This scenario can be useful if you are migrating from a wallet not using BIP39 passphrases or for wallets following some custom generation rules. It is however generally preferable to use one of the methods presented above.\n\nAn example of key import is\n\n```java\n// privKey is the S component of the key, as a 32-byte long byte array\n// chainCode is the extension to the keypair defined by BIP32, this is another 32-byte long byte array. Can be null, in\n// which case the created wallet won't be BIP32 compatible.\n// pubKey is the DER encoded, uncompressed public key. Can be null, in which case it is automatically calculated from\n// the private key.\nBIP32KeyPair keypair = new BIP32KeyPair(privKey, chainCode, pubKey);\n\n// Loads the keypair\ncmdSet.loadKey(keypair).checkOK();\n```\n\n## Key derivation\n\nAs mentioned before, the Keycard is a BIP32 compatible wallet. This means that it can perform key derivation as defined by the BIP32 specification in order to create a hierarchical deterministic wallet. When deriving a key, this key becomes active, which means that it will be used for all signing operations until a key with a different path is derived. The active key is persisted across sessions, meaning that a power loss or applet reselection does not reset it.\n\nWhen creating or importing a wallet to the Keycard, the active key is the master key. Unless you imported a non-BIP32 compatible wallet, you usually want to set the active key to a currency account by following the BIP44 specifications for paths. Note that the maximum depth of the key path is 10, excluding the master key.\n\nKey derivation requires user authentication\n\nSince a line of code is worth a thousand words, below is an example of deriving a standard key path\n\n```java\ncmdSet.deriveKey(\"m/44'/0'/0'/0/0\").checkOK();\n```\n\nSince deriving a key is an expensive operation, you usually want to know what the current path is before performing derivation. You can do this with\n\n```java\n// you can then get is as a string with currentPath.toString()\nKeyPath currentPath = new KeyPath(cmdSet.getStatus(KeycardCommandSet.GET_STATUS_P1_KEY_PATH).checkOK().getData());\n```\n\nTo speed up operations, key derivation can be started not only from the master key, but also from the parent or the current key. The path in this case starts respectively with \"../\" and \"./\". You cannot navigate the hierarchy with multiple \"..\" in the paths, because only the direct parent of the current key is cached. Derivation from parent is especially convenient when switching between accounts of the same type. Example\n\n```java\n// Derive the main account\ncmdSet.deriveKey(\"m/44'/0'/0'/0/0\").checkOK();\n\n// switch a secondary account, equivalent to \"m/44'/0'/0'/0/1\" but much faster\ncmdSet.deriveKey(\"../1\").checkOK();\n\n// you can switch back and forth between siblings without limitations.\ncmdSet.deriveKey(\"../0\").checkOK();\n```\n\n## Signing\n\nYour Keycard has been initialized, has a wallet and you have derived the keypath you need. You can now perform transactions by signing them with the card. Since the Keycard has no user input/output capabilities, it would be useless to transfer the entire transaction to the card for signing. You should instead calculate the transaction hash, according to the rules of the cryptocurrency you are handling and send that for signature instead. This also means, that you can handle anything which requires ECDSA signatures over SECP256k1 curve, regardless of the used hashing algorithm (at the condition that it output a 256-bit hash of course). This opens the door to signing transactions for the most common cryptocurrencies, but also makes it usable outside the realm of crypto transactions.\n\nSigning is done as\n\n```java\n// hash is the hash to sign, for example the Keccak-256 hash of an Ethereum transaction\n// the signature object contains r, s, recId and the public key associated to this signature\nRecoverableSignature signature = new RecoverableSignature(hash, cmdSet.sign(hash).checkOK().getData());\n```\n\nSigning requires user authentication.\n\n## Exporting (public or EIP-1581 compliant) keys\n\nSorry for the long title, but let's make it immediately clear: the keys used to sign transactions never leave the card and cannot be exported. You can however export any public key as well as the private key of keypaths defined in the [EIP-1581 specifications](https://eips.ethereum.org/EIPS/eip-1581). Those keys, by design, are not to be used for transactions but are instead usable for operations with lower security concerns where caching or storing the key outside the card might be beneficial from an UX point of view. Of course, exporting a key always requires user authentication.\n\n### Exporting the current key\n\n```java\n// Exports the current public key. This is allowed for any key path\nBIP32KeyPair publicKey = BIP32KeyPair.fromTLV(cmdSet.exportCurrentKey(true).checkOK().getData());\n\n// Exports the entire key pair. This is only allowed for key path following the EIP-1581 definition\nBIP32KeyPair keypair = BIP32KeyPair.fromTLV(cmdSet.exportCurrentKey(false).checkOK().getData());\n```\n\n### Derive & export\n\nThe export command is very powerful, since it allows you to derive & export a key in one step. You have the option to make the derived and exported key active or leave the active key untouched. You can also decide whether to export only the public key or the entire keypair (following the rules defined above).\n\nA very convenient use case is deriving an account key and retrieving the public key in one step. This is faster than doing it with two commands (derive key and export public), because every command processed has some overhead. Example\n\n```java\n// The first parameter is the keypath, the second tells whether that you want to make the derived & exported key active\n// and the third tells that you only want the public key to be exported.\nBIP32KeyPair publicKey = BIP32KeyPair.fromTLV(cmdSet.exportKey(\"m/44'/0'/0'/0/0\", true, true).checkOK().getData());\n\n// The line above is equivalent to\n// cmdSet.deriveKey(\"m/44'/0'/0'/0/0\").checkOK();\n// BIP32KeyPair publicKey = BIP32KeyPair.fromTLV(cmdSet.exportCurrentKey(true).checkOK().getData());\n```\n\nAnother use case, is to export keys defined by EIP-1581 without changing the current active key, since you won't be signing with the exported key using the card\n\n```java\n// Let's assume the current active path is \"m/44'/0'/0'/0/0\"\n\n// The first parameter is the key path, the second tells that you do not want to make it current and the third that you\n// want the entire keypair, not only the public key\nBIP32KeyPair keypair = BIP32KeyPair.fromTLV(cmdSet.exportKey(\"m/43'/60'/1581'/0'/0\", false, false).checkOK().getData());\n\n// At this point, the current active path would still be \"m/44'/0'/0'/0/0\"\n```\n\n## Changing credentials\n\nAll credentials of the Keycard can be changed (PIN, PUK, pairing password). Changing the pairing password does not invalidate existing pairings, but applies to the ones which can be created in the future. Changing credentials, requires user authentication.\n\n```java\n// Changes the user PIN\ncmdSet.changePIN(\"123456\").checkOK();\n\n// Changes the PUK\ncmdSet.changePUK(\"123456123456\").checkOK();\n\n// Changes the pairing password\ncmdSet.changePairingPassword(\"my pairing password\").checkOK();\n```\n\n## Duplication\n\nCard duplication is especially relevant when the keys have been generated on-card, without using BIP39 mnemonic (or when this has been destroyed). To make duplication secure the client must not possess the (full) encryption key. For this reason, a scheme where multiple clients are used and none of them has the full key has been devised. From the user point of view, the duplication process goes like this\n\n1. Take the card to be duplicated (source) and one or more cards to duplicate to (target)\n2. On one of the user's clients initiate the duplication. This involves entering the PIN of each of the involved cards\n3. Tap all cards to one or more additional clients (the amount must be defined before, the order is irrelevant). These clients do not need to be paired or be trusted, so the user can borrow a friend's phone without compromising security. This step does not require entering a PIN\n4. On one of the user's clients, usually the same which initiated the duplication (must be paired, trusted) finalize the duplication by first tapping the source card and then all target cards, again inserting the PIN for each.\n \nAt the end of procedure, each card will have the same master key, but PIN, PUK and pairing key remain unchanged and are independent from each other. A client could propose changing them to be all the same if desired or do this automatically. All cards are fully functional, so at this point there isn't any difference between the source card and the targets.\n\nSince the cards are still protected by the PIN, these can be stored remotely in moderately trusted places to recover from lost or destroyed cards. The duplication has been performed securely since no client ever had the full encryption key and no authentication credentials has been inserted on untrusted clients. For flexibility reason, an arbitrary number of clients can be used. Using a single client could be convenient from an UX point of view, but relies on said client not being compromised. Using 2 or 3 clients greatly increases security. More than 3 clients is probably an overkill.\n\nFrom an implementation point of view, we have two different roles a client can take\n\n1. The trusted client, starting and performing the duplication\n2. The (possibly) untrusted clients, only adding entropy to the encryption key\n\nBoth can be implemented by using the `CardDuplicator` class. On each client, the same instance of the `CardDuplicator` class must be used for the entire duplication process, otherwise duplication will fail.\n\nThe trusted client must also provide an implementation of `DuplicatorCallback`. This is needed to retrieve the Pairing and PIN for each card. Example below\n\n```java\nclass MyDuplicatorCB implements DuplicatorCallback {\n Pairing getPairing(ApplicationInfo applicationInfo) {\n // The Instance UID is the one to use when storing/retrieving pairings\n byte[] uid = applicationInfo.getInstanceUID();\n \n // Using the UID try to retrieve the pairing. The method getSavedPairing is an example and is not part of the SDK,\n // you are responsible of how you store and retrieve pairing data in your app\n Pairing pairing = getSavedPairing(uid);\n \n // Optionally, you could prompt the user and make a new pairing if none if given, but this is an UX decision in\n // your application.\n if (pairing == null) {\n pairing = tryToPair();\n }\n \n // possibly null, in this case the operation requiring pairing is aborted\n return pairing;\n }\n \n String getPIN(ApplicationInfo applicationInfo, int remainingAttempts) {\n // Optionally, you might have a cache of PINs for recently used card, but this should be done carefully as the PIN\n // is sensitive data. You might instead want to just prompt the user each time.\n String pin = getCachedPIN(applicationInfo.getInstanceUID());\n \n if (pin == null) {\n // prompt the user to insert the PIN. You can optionally inform them about how many retry attempts are left.\n // For UX reason you could also use the instance UID to show the user an identifiable name, this is again\n // application specific.\n pin = promptUser(remainingAttempts);\n }\n \n // This must not be null. PIN verification will be performed by the CardDuplicator itself, do no not perform it here!\n return pin;\n }\n}\n```\n\nThe next step to do, is instantiating a CardDuplicator.\n\nFor the trusted client\n\n```java\n// The cmdSet is a KeycardCommandSet instance, duplicatorCallback is an object implementing the DuplicatorCallback\n// interface\ncardDuplicator = new CardDuplicator(cmdSet, duplicatorCallback);\n```\n\nFor the untrusted clients\n\n```java\n// apduChannel is a CardChannel instance. Alternatively the same constructor as for the trusted client can be used,\n// passing null as the second parameter.\ncardDuplicator = new CardDuplicator(apduChannel);\n```\n\nOnce the instance has been created, depending on the role and state the client must perform a specific action every time a new card is presented. The CardDuplicator keeps track of the action performed on any card, so if the user presents the same card twice an `IllegalStateException` exception is thrown.\n\nTo start duplication on a card, for example, you might do\n\n```java\n// Client count is the amount of devices contributing to forming the entire key. This means 1 + the number of clients\n// which will be adding entropy (the untrusted clients)\ncardDuplicator.startDuplication(clientCount);\n```\n\nOn untrusted clients, to add entropy, you do\n\n```java\ncardDuplicator.addEntropy();\n```\n\nWhen the full key has been stored on all cards, you then call the following method on the source card on a trusted client\n\n```java\nbyte[] exportedKey = cardDuplicator.exportKey();\n```\n\nwhereas, from the same client, you invoke on all target cards the following\n\n```java\n// you should then check that the keyUID matches the one of the source card to be sure that the duplication has been\n// performed correctly.\nbyte[] keyUID = cardDuplicator.importKey(exportedKey);\n```\n","date":"2019-01-17T08:29:06.583Z","updated":"2019-01-17T08:29:06.580Z","path":"api/java-sdk.html","_id":"cjqyxw7kw0001p0qe8jsu6rxq","comments":1,"layout":"page","content":"You can import the SDK in your Gradle or Maven project using Jitpack.io. If using Gradle, to use
JitPack all you have to do is insert these lines in you build.gradle file
allprojects { |
Then, you must import the correct dependency. In case you are building an Android-based project, you need to add this line
\ndependencies { |
If you are working on the desktop, then you need this line instead
\ndependencies { |
In both case, you will have the same SDK, except for the way connection with the card is established.
\nOn Android, the NFC connection handling must happen on a thread separate from the UI thread. The SDK provides the class NFCCardManager to handle this. This an example activity starting the NFC reader and handling the connection to the card. Refer to the comments in the example for more information.
public class MainActivity extends AppCompatActivity { |
On the desktop we use the javax.smartcardio library. There are several ways to handle connections, the important part is getting a CardChannel open. Below is an example of how this can be achieved (assumes that a single smartcard reader is connected).
\n// We create a TerminalFactory object |
Regardless whether you are on Android or desktop, you should at this point have an implementation of the CardChannel interface (be it NFCCardChannel or PCSCCardChannel). You can now start working with the card. The first thing to do is creating a KeycardCommandSet instance. This class gives access to all of the applet functionality, wrapping the low-level APDUs in easy to use methods. All other classes in the SDK are helper to format parameters and parse responses from the card. To create a command set, just do
// cardChannel is our CardChannel instance |
Modern SmartCards can have several applications installed, so after connection with the card you need to select the Keycard applet. This is easily done with
\n// The checkOK method can be called on any APDUResponse object to confirm that the |
While this correctly selects the applet, it discards the card response, which contains information that can be useful to identify this specific card and its state. For this reason we could rewrite this as
\nApplicationInfo info = new ApplicationInfo(cmdSet.select().checkOK().getData()); |
After the applet is selected, you can start working with it. Note that the application remains selected until another applet is explicitly selected, or the card is powered off (for example is removed from the field)
\nThis step is necessary to bring the initial credentials on the Keycard instance. When the card is not initialized, it cannot perform any operation. Initialization sets the initial PIN, PUK and pairing password and requires no authentication, but still uses a SecureChannel resistant to passive MITM attacks. Once the card is initialized, it cannot be initialized again (but credentials can be different with a different mechanism with previous authentication).
\nInitialization is done with
\n// Usually, you want to check if the card is initialized before trying to initialize it, otherwise you will receive an |
Clients wishing to communicate with the card, need to pair with it first. This allows creating secure channels resistant not only to passive but also to active MITM attacks. Although pairing allows the card and the client to authenticate each other, the card does not grant access to any operation with the wallet until the user is authenticated (by verifying its PIN). To establish the pairing, the client needs to know the pairing password. After it is established, the pairing info (not the password) must be stored as securely as possible on the client for subsequent sessions. You should store the pairing information together with the instance UID to simplify handling of multiple cards.
\nOnly 5 clients can be paired at once, but it is possible to unpair previously paired clients.
\nUsing the SDK, pairing is a simple operation
\n// pairingPassword is usually provided by the user. This method throws an exception if pairing fails. |
If you have already paired, you should instead load the persisted pairing information in the command set
\n// serializedPairing can be either the byte array or base64 string representation |
After a pairing has been established, a secure channel can be opened. Before opening a secure channel, the card won’t allow sending any command. This guarantees secrecy, integrity and authenticity of the commands. Opening a secure channel must be performed every time the applet is selected (this means also after a power loss). After opening it, the SDK handles the secure channel transparently, encrypting and signing all command APDUs and decrypting and verifying the signature of all responses. To open a secure channel all you need to do is
\ncmdSet.autoOpenSecureChannel(); |
Most operations with the card (all involving operations with the wallet or credentials) require authenticating the user. After authentication, the user remains authenticated until the card is powered off or the application is re-selected.
\nAuthentication is performed by verifying the user PIN. Note that this piece of information is sensitive and must be handled accordingly in the application. PIN verification is done with a single step
\n// pin is the user PIN as a string of 6 digits |
if the PIN is wrong, you will receive an error SW in the format 0x63CX where X is the number of attempts remaining. When the number of remaining attempts is 0, the card is blocked. The user must then enter the PUK and a new PIN to restore access to the card. The maximum number of retries for the PUK is 5. To simplify things, the APDUResponse.checkAuthOK() method can be used to verify if the authentication was correct, and if not throw a WrongPINException which contains the number of remaining attempts.
cmdSet.unblockPIN(puk, newPIN).checkAuthOK(); |
To actually use the Keycard, it needs to have a wallet. This can be achieved in several different ways, which one you choose depends on your usage scenario. Creating a wallet requires user authentication and is possible even if a wallet already exists on the card (the new wallet replaces the old one). Use the ApplicationInfo.hasMasterKey() method to determine if the card already has a wallet or not. Note that the response of the KeycardCommandSet.loadKey method contains the key UID of the created wallet. This UID can be stored to keep track of this specific wallet in the client. The UID is tied to the key itself (is derived from the public key) so it will change if the wallet on card is replaced. The key UID is also part of the response of the applet selection command, so the wallet can be identified immediately upon selection.
This method is great for interoperability with other wallets. The card can assist in creating the mnemonic phrase, since it features a TRNG. Generating the mnemonic itself does not require user authentication (since it does not modify the card state), but loading the key derived from it does. Example of the entire procedure is below
\n// Generates a Mnemonic object from the card. You can choose between generating 12, 15, 18, 21 or 24 words |
Importing an existing passphrase requires only the loading step.
\n// The passphrase is a string with space separated words. The password can be any non-null string, usually is empty. |
This is the simplest and safest method, because the generated wallet never leaves the card and there is no “paper backup” to keep secure. It is possible to create secure duplicates of the wallet on other Keycards, with a mechanism described in later chapters. Using the SDK, you simply do
\ncmdSet.generateKey().checkOK(); |
You can import on the keycard any EC keypair on the SECP256k1 curve, with or without the BIP32 extension. If your import a key without the BIP32 extension, then key derivation will not work, but you will still be able to use the Keycard for signing transactions using the imported key. This scenario can be useful if you are migrating from a wallet not using BIP39 passphrases or for wallets following some custom generation rules. It is however generally preferable to use one of the methods presented above.
\nAn example of key import is
\n// privKey is the S component of the key, as a 32-byte long byte array |
As mentioned before, the Keycard is a BIP32 compatible wallet. This means that it can perform key derivation as defined by the BIP32 specification in order to create a hierarchical deterministic wallet. When deriving a key, this key becomes active, which means that it will be used for all signing operations until a key with a different path is derived. The active key is persisted across sessions, meaning that a power loss or applet reselection does not reset it.
\nWhen creating or importing a wallet to the Keycard, the active key is the master key. Unless you imported a non-BIP32 compatible wallet, you usually want to set the active key to a currency account by following the BIP44 specifications for paths. Note that the maximum depth of the key path is 10, excluding the master key.
\nKey derivation requires user authentication
\nSince a line of code is worth a thousand words, below is an example of deriving a standard key path
\ncmdSet.deriveKey(\"m/44'/0'/0'/0/0\").checkOK(); |
Since deriving a key is an expensive operation, you usually want to know what the current path is before performing derivation. You can do this with
\n// you can then get is as a string with currentPath.toString() |
To speed up operations, key derivation can be started not only from the master key, but also from the parent or the current key. The path in this case starts respectively with “../“ and “./“. You cannot navigate the hierarchy with multiple “..” in the paths, because only the direct parent of the current key is cached. Derivation from parent is especially convenient when switching between accounts of the same type. Example
\n// Derive the main account |
Your Keycard has been initialized, has a wallet and you have derived the keypath you need. You can now perform transactions by signing them with the card. Since the Keycard has no user input/output capabilities, it would be useless to transfer the entire transaction to the card for signing. You should instead calculate the transaction hash, according to the rules of the cryptocurrency you are handling and send that for signature instead. This also means, that you can handle anything which requires ECDSA signatures over SECP256k1 curve, regardless of the used hashing algorithm (at the condition that it output a 256-bit hash of course). This opens the door to signing transactions for the most common cryptocurrencies, but also makes it usable outside the realm of crypto transactions.
\nSigning is done as
\n// hash is the hash to sign, for example the Keccak-256 hash of an Ethereum transaction |
Signing requires user authentication.
\nSorry for the long title, but let’s make it immediately clear: the keys used to sign transactions never leave the card and cannot be exported. You can however export any public key as well as the private key of keypaths defined in the EIP-1581 specifications. Those keys, by design, are not to be used for transactions but are instead usable for operations with lower security concerns where caching or storing the key outside the card might be beneficial from an UX point of view. Of course, exporting a key always requires user authentication.
\n// Exports the current public key. This is allowed for any key path |
The export command is very powerful, since it allows you to derive & export a key in one step. You have the option to make the derived and exported key active or leave the active key untouched. You can also decide whether to export only the public key or the entire keypair (following the rules defined above).
\nA very convenient use case is deriving an account key and retrieving the public key in one step. This is faster than doing it with two commands (derive key and export public), because every command processed has some overhead. Example
\n// The first parameter is the keypath, the second tells whether that you want to make the derived & exported key active |
Another use case, is to export keys defined by EIP-1581 without changing the current active key, since you won’t be signing with the exported key using the card
\n// Let's assume the current active path is \"m/44'/0'/0'/0/0\" |
All credentials of the Keycard can be changed (PIN, PUK, pairing password). Changing the pairing password does not invalidate existing pairings, but applies to the ones which can be created in the future. Changing credentials, requires user authentication.
\n// Changes the user PIN |
Card duplication is especially relevant when the keys have been generated on-card, without using BIP39 mnemonic (or when this has been destroyed). To make duplication secure the client must not possess the (full) encryption key. For this reason, a scheme where multiple clients are used and none of them has the full key has been devised. From the user point of view, the duplication process goes like this
\nAt the end of procedure, each card will have the same master key, but PIN, PUK and pairing key remain unchanged and are independent from each other. A client could propose changing them to be all the same if desired or do this automatically. All cards are fully functional, so at this point there isn’t any difference between the source card and the targets.
\nSince the cards are still protected by the PIN, these can be stored remotely in moderately trusted places to recover from lost or destroyed cards. The duplication has been performed securely since no client ever had the full encryption key and no authentication credentials has been inserted on untrusted clients. For flexibility reason, an arbitrary number of clients can be used. Using a single client could be convenient from an UX point of view, but relies on said client not being compromised. Using 2 or 3 clients greatly increases security. More than 3 clients is probably an overkill.
\nFrom an implementation point of view, we have two different roles a client can take
\nBoth can be implemented by using the CardDuplicator class. On each client, the same instance of the CardDuplicator class must be used for the entire duplication process, otherwise duplication will fail.
The trusted client must also provide an implementation of DuplicatorCallback. This is needed to retrieve the Pairing and PIN for each card. Example below
class MyDuplicatorCB implements DuplicatorCallback { |
The next step to do, is instantiating a CardDuplicator.
\nFor the trusted client
\n// The cmdSet is a KeycardCommandSet instance, duplicatorCallback is an object implementing the DuplicatorCallback |
For the untrusted clients
\n// apduChannel is a CardChannel instance. Alternatively the same constructor as for the trusted client can be used, |
Once the instance has been created, depending on the role and state the client must perform a specific action every time a new card is presented. The CardDuplicator keeps track of the action performed on any card, so if the user presents the same card twice an IllegalStateException exception is thrown.
To start duplication on a card, for example, you might do
\n// Client count is the amount of devices contributing to forming the entire key. This means 1 + the number of clients |
On untrusted clients, to add entropy, you do
\ncardDuplicator.addEntropy(); |
When the full key has been stored on all cards, you then call the following method on the source card on a trusted client
\nbyte[] exportedKey = cardDuplicator.exportKey(); |
whereas, from the same client, you invoke on all target cards the following
\n// you should then check that the keyUID matches the one of the source card to be sure that the duplication has been |
You can import the SDK in your Gradle or Maven project using Jitpack.io. If using Gradle, to use
JitPack all you have to do is insert these lines in you build.gradle file
allprojects { |
Then, you must import the correct dependency. In case you are building an Android-based project, you need to add this line
\ndependencies { |
If you are working on the desktop, then you need this line instead
\ndependencies { |
In both case, you will have the same SDK, except for the way connection with the card is established.
\nOn Android, the NFC connection handling must happen on a thread separate from the UI thread. The SDK provides the class NFCCardManager to handle this. This an example activity starting the NFC reader and handling the connection to the card. Refer to the comments in the example for more information.
public class MainActivity extends AppCompatActivity { |
On the desktop we use the javax.smartcardio library. There are several ways to handle connections, the important part is getting a CardChannel open. Below is an example of how this can be achieved (assumes that a single smartcard reader is connected).
\n// We create a TerminalFactory object |
Regardless whether you are on Android or desktop, you should at this point have an implementation of the CardChannel interface (be it NFCCardChannel or PCSCCardChannel). You can now start working with the card. The first thing to do is creating a KeycardCommandSet instance. This class gives access to all of the applet functionality, wrapping the low-level APDUs in easy to use methods. All other classes in the SDK are helper to format parameters and parse responses from the card. To create a command set, just do
// cardChannel is our CardChannel instance |
Modern SmartCards can have several applications installed, so after connection with the card you need to select the Keycard applet. This is easily done with
\n// The checkOK method can be called on any APDUResponse object to confirm that the |
While this correctly selects the applet, it discards the card response, which contains information that can be useful to identify this specific card and its state. For this reason we could rewrite this as
\nApplicationInfo info = new ApplicationInfo(cmdSet.select().checkOK().getData()); |
After the applet is selected, you can start working with it. Note that the application remains selected until another applet is explicitly selected, or the card is powered off (for example is removed from the field)
\nThis step is necessary to bring the initial credentials on the Keycard instance. When the card is not initialized, it cannot perform any operation. Initialization sets the initial PIN, PUK and pairing password and requires no authentication, but still uses a SecureChannel resistant to passive MITM attacks. Once the card is initialized, it cannot be initialized again (but credentials can be different with a different mechanism with previous authentication).
\nInitialization is done with
\n// Usually, you want to check if the card is initialized before trying to initialize it, otherwise you will receive an |
Clients wishing to communicate with the card, need to pair with it first. This allows creating secure channels resistant not only to passive but also to active MITM attacks. Although pairing allows the card and the client to authenticate each other, the card does not grant access to any operation with the wallet until the user is authenticated (by verifying its PIN). To establish the pairing, the client needs to know the pairing password. After it is established, the pairing info (not the password) must be stored as securely as possible on the client for subsequent sessions. You should store the pairing information together with the instance UID to simplify handling of multiple cards.
\nOnly 5 clients can be paired at once, but it is possible to unpair previously paired clients.
\nUsing the SDK, pairing is a simple operation
\n// pairingPassword is usually provided by the user. This method throws an exception if pairing fails. |
If you have already paired, you should instead load the persisted pairing information in the command set
\n// serializedPairing can be either the byte array or base64 string representation |
After a pairing has been established, a secure channel can be opened. Before opening a secure channel, the card won’t allow sending any command. This guarantees secrecy, integrity and authenticity of the commands. Opening a secure channel must be performed every time the applet is selected (this means also after a power loss). After opening it, the SDK handles the secure channel transparently, encrypting and signing all command APDUs and decrypting and verifying the signature of all responses. To open a secure channel all you need to do is
\ncmdSet.autoOpenSecureChannel(); |
Most operations with the card (all involving operations with the wallet or credentials) require authenticating the user. After authentication, the user remains authenticated until the card is powered off or the application is re-selected.
\nAuthentication is performed by verifying the user PIN. Note that this piece of information is sensitive and must be handled accordingly in the application. PIN verification is done with a single step
\n// pin is the user PIN as a string of 6 digits |
if the PIN is wrong, you will receive an error SW in the format 0x63CX where X is the number of attempts remaining. When the number of remaining attempts is 0, the card is blocked. The user must then enter the PUK and a new PIN to restore access to the card. The maximum number of retries for the PUK is 5. To simplify things, the APDUResponse.checkAuthOK() method can be used to verify if the authentication was correct, and if not throw a WrongPINException which contains the number of remaining attempts.
cmdSet.unblockPIN(puk, newPIN).checkAuthOK(); |
To actually use the Keycard, it needs to have a wallet. This can be achieved in several different ways, which one you choose depends on your usage scenario. Creating a wallet requires user authentication and is possible even if a wallet already exists on the card (the new wallet replaces the old one). Use the ApplicationInfo.hasMasterKey() method to determine if the card already has a wallet or not. Note that the response of the KeycardCommandSet.loadKey method contains the key UID of the created wallet. This UID can be stored to keep track of this specific wallet in the client. The UID is tied to the key itself (is derived from the public key) so it will change if the wallet on card is replaced. The key UID is also part of the response of the applet selection command, so the wallet can be identified immediately upon selection.
This method is great for interoperability with other wallets. The card can assist in creating the mnemonic phrase, since it features a TRNG. Generating the mnemonic itself does not require user authentication (since it does not modify the card state), but loading the key derived from it does. Example of the entire procedure is below
\n// Generates a Mnemonic object from the card. You can choose between generating 12, 15, 18, 21 or 24 words |
Importing an existing passphrase requires only the loading step.
\n// The passphrase is a string with space separated words. The password can be any non-null string, usually is empty. |
This is the simplest and safest method, because the generated wallet never leaves the card and there is no “paper backup” to keep secure. It is possible to create secure duplicates of the wallet on other Keycards, with a mechanism described in later chapters. Using the SDK, you simply do
\ncmdSet.generateKey().checkOK(); |
You can import on the keycard any EC keypair on the SECP256k1 curve, with or without the BIP32 extension. If your import a key without the BIP32 extension, then key derivation will not work, but you will still be able to use the Keycard for signing transactions using the imported key. This scenario can be useful if you are migrating from a wallet not using BIP39 passphrases or for wallets following some custom generation rules. It is however generally preferable to use one of the methods presented above.
\nAn example of key import is
\n// privKey is the S component of the key, as a 32-byte long byte array |
As mentioned before, the Keycard is a BIP32 compatible wallet. This means that it can perform key derivation as defined by the BIP32 specification in order to create a hierarchical deterministic wallet. When deriving a key, this key becomes active, which means that it will be used for all signing operations until a key with a different path is derived. The active key is persisted across sessions, meaning that a power loss or applet reselection does not reset it.
\nWhen creating or importing a wallet to the Keycard, the active key is the master key. Unless you imported a non-BIP32 compatible wallet, you usually want to set the active key to a currency account by following the BIP44 specifications for paths. Note that the maximum depth of the key path is 10, excluding the master key.
\nKey derivation requires user authentication
\nSince a line of code is worth a thousand words, below is an example of deriving a standard key path
\ncmdSet.deriveKey(\"m/44'/0'/0'/0/0\").checkOK(); |
Since deriving a key is an expensive operation, you usually want to know what the current path is before performing derivation. You can do this with
\n// you can then get is as a string with currentPath.toString() |
To speed up operations, key derivation can be started not only from the master key, but also from the parent or the current key. The path in this case starts respectively with “../“ and “./“. You cannot navigate the hierarchy with multiple “..” in the paths, because only the direct parent of the current key is cached. Derivation from parent is especially convenient when switching between accounts of the same type. Example
\n// Derive the main account |
Your Keycard has been initialized, has a wallet and you have derived the keypath you need. You can now perform transactions by signing them with the card. Since the Keycard has no user input/output capabilities, it would be useless to transfer the entire transaction to the card for signing. You should instead calculate the transaction hash, according to the rules of the cryptocurrency you are handling and send that for signature instead. This also means, that you can handle anything which requires ECDSA signatures over SECP256k1 curve, regardless of the used hashing algorithm (at the condition that it output a 256-bit hash of course). This opens the door to signing transactions for the most common cryptocurrencies, but also makes it usable outside the realm of crypto transactions.
\nSigning is done as
\n// hash is the hash to sign, for example the Keccak-256 hash of an Ethereum transaction |
Signing requires user authentication.
\nSorry for the long title, but let’s make it immediately clear: the keys used to sign transactions never leave the card and cannot be exported. You can however export any public key as well as the private key of keypaths defined in the EIP-1581 specifications. Those keys, by design, are not to be used for transactions but are instead usable for operations with lower security concerns where caching or storing the key outside the card might be beneficial from an UX point of view. Of course, exporting a key always requires user authentication.
\n// Exports the current public key. This is allowed for any key path |
The export command is very powerful, since it allows you to derive & export a key in one step. You have the option to make the derived and exported key active or leave the active key untouched. You can also decide whether to export only the public key or the entire keypair (following the rules defined above).
\nA very convenient use case is deriving an account key and retrieving the public key in one step. This is faster than doing it with two commands (derive key and export public), because every command processed has some overhead. Example
\n// The first parameter is the keypath, the second tells whether that you want to make the derived & exported key active |
Another use case, is to export keys defined by EIP-1581 without changing the current active key, since you won’t be signing with the exported key using the card
\n// Let's assume the current active path is \"m/44'/0'/0'/0/0\" |
All credentials of the Keycard can be changed (PIN, PUK, pairing password). Changing the pairing password does not invalidate existing pairings, but applies to the ones which can be created in the future. Changing credentials, requires user authentication.
\n// Changes the user PIN |
Card duplication is especially relevant when the keys have been generated on-card, without using BIP39 mnemonic (or when this has been destroyed). To make duplication secure the client must not possess the (full) encryption key. For this reason, a scheme where multiple clients are used and none of them has the full key has been devised. From the user point of view, the duplication process goes like this
\nAt the end of procedure, each card will have the same master key, but PIN, PUK and pairing key remain unchanged and are independent from each other. A client could propose changing them to be all the same if desired or do this automatically. All cards are fully functional, so at this point there isn’t any difference between the source card and the targets.
\nSince the cards are still protected by the PIN, these can be stored remotely in moderately trusted places to recover from lost or destroyed cards. The duplication has been performed securely since no client ever had the full encryption key and no authentication credentials has been inserted on untrusted clients. For flexibility reason, an arbitrary number of clients can be used. Using a single client could be convenient from an UX point of view, but relies on said client not being compromised. Using 2 or 3 clients greatly increases security. More than 3 clients is probably an overkill.
\nFrom an implementation point of view, we have two different roles a client can take
\nBoth can be implemented by using the CardDuplicator class. On each client, the same instance of the CardDuplicator class must be used for the entire duplication process, otherwise duplication will fail.
The trusted client must also provide an implementation of DuplicatorCallback. This is needed to retrieve the Pairing and PIN for each card. Example below
class MyDuplicatorCB implements DuplicatorCallback { |
The next step to do, is instantiating a CardDuplicator.
\nFor the trusted client
\n// The cmdSet is a KeycardCommandSet instance, duplicatorCallback is an object implementing the DuplicatorCallback |
For the untrusted clients
\n// apduChannel is a CardChannel instance. Alternatively the same constructor as for the trusted client can be used, |
Once the instance has been created, depending on the role and state the client must perform a specific action every time a new card is presented. The CardDuplicator keeps track of the action performed on any card, so if the user presents the same card twice an IllegalStateException exception is thrown.
To start duplication on a card, for example, you might do
\n// Client count is the amount of devices contributing to forming the entire key. This means 1 + the number of clients |
On untrusted clients, to add entropy, you do
\ncardDuplicator.addEntropy(); |
When the full key has been stored on all cards, you then call the following method on the source card on a trusted client
\nbyte[] exportedKey = cardDuplicator.exportKey(); |
whereas, from the same client, you invoke on all target cards the following
\n// you should then check that the keyUID matches the one of the source card to be sure that the duplication has been |