Support for NXP SAM (Secure Application Module)

Functions
UFR_STATUS DL_API	SAM_get_version_raw (OUT uint8_t *data, VAR uint8_t *length)
UFR_STATUS DL_API	SAM_get_version (VAR SAM_HW_TYPE *sam_type, OUT uint8_t *sam_uid)
UFR_STATUS DL_API	SAM_get_key_entry_raw (uint8_t key_no, OUT uint8_t *key_entry, VAR uint8_t *key_length, OUT uint8_t *apdu_sw)
UFR_STATUS DL_API	SAM_authenticate_host_AV2_plain (IN uint8_t *host_aes_key, uint8_t key_nr, uint8_t key_version, OUT uint8_t *apdu_sw)
UFR_STATUS DL_API	SAM_change_key_entry_mifare_AV2_plain_one_key (uint8_t key_entry_no, IN uint8_t *keyA, IN uint8_t *keyB, uint8_t key_no_CEK, uint8_t key_v_CEK, uint8_t ref_no_KUC, OUT uint8_t *apdu_sw)
UFR_STATUS DL_API	SAM_change_key_entry_AES_AV2_plain_one_key (uint8_t key_entry_no, IN uint8_t *key, uint8_t key_no_CEK, uint8_t key_v_CEK, uint8_t ref_no_KUC, OUT uint8_t *apdu_sw)
UFR_STATUS DL_API	SAM_change_key_entry_3K3DES_AV2_plain_one_key (uint8_t key_entry_no, IN uint8_t *key, uint8_t key_no_CEK, uint8_t key_v_CEK, uint8_t ref_no_KUC, OUT uint8_t *apdu_sw)
UFR_STATUS DL_API	SAM_change_key_entry_2K3DES_ULC_AV2_plain_one_key (uint8_t key_entry_no, IN uint8_t *key, uint8_t key_no_CEK, uint8_t key_v_CEK, uint8_t ref_no_KUC, OUT uint8_t *apdu_sw)
UFR_STATUS DL_API	SAM_change_key_entry_2K3DES_desfire_AV2_plain_one_key (uint8_t key_entry_no, IN uint8_t *key, uint8_t key_no_CEK, uint8_t key_v_CEK, uint8_t ref_no_KUC, OUT uint8_t *apdu_sw)
UFR_STATUS DL_API	SAM_change_key_entry_DES_AV2_plain_one_key (uint8_t key_entry_no, IN uint8_t *key, uint8_t key_no_CEK, uint8_t key_v_CEK, uint8_t ref_no_KUC, OUT uint8_t *apdu_sw)
UFR_STATUS DL_API	SAM_change_key_entry_aes_AV2_plain_host_key (uint8_t key_entry_no, IN uint8_t *aes_key_ver_a, uint8_t ver_a, IN uint8_t *aes_key_ver_b, uint8_t ver_b, IN uint8_t *aes_key_ver_c, uint8_t ver_c, uint8_t key_no_CEK, uint8_t key_v_CEK, uint8_t ref_no_KUC, uint8_t sam_lock_unlock, uint8_t sam_auth_host, OUT uint8_t *apdu_sw)
UFR_STATUS DL_API	WriteSamUnlockKey (uint8_t key_no, uint8_t key_ver, IN uint8_t *aes_key)

Detailed Description

Function Documentation

SAM_get_version_raw()

UFR_STATUS DL_API SAM_get_version_raw	(	OUT uint8_t *	data,
		VAR uint8_t *	length )

Function returns manufacturing related data of the MIFARE SAM. For more information refer to NXP documentation.

Parameters

data	pointer to array containing version data
length	pointer to length variable

Returns

Operation status

SAM_get_version()

UFR_STATUS DL_API SAM_get_version	(	VAR SAM_HW_TYPE *	sam_type,
		OUT uint8_t *	sam_uid )

Function returns manufacturing related data of the MIFARE SAM. For more information refer to NXP documentation.

Parameters

sam_type	pointer to SAM type variable
sam_uid	pointer to array containing 7 bytes UID

Returns

Operation status

SAM_get_key_entry_raw()

UFR_STATUS DL_API SAM_get_key_entry_raw	(	uint8_t	key_no,
		OUT uint8_t *	key_entry,
		VAR uint8_t *	key_length,
		OUT uint8_t *	apdu_sw )

Function allows reading the contents of the key entry specified in the parameter key_no. For more information refer to NXP documentation.

Parameters

key_no	key reference number (0 - 127)
key_entry	pointer to array containing key entry data
key_length	pointer to key entry length variable
apdu_sw	pointer to array containing SW1 and SW2 APDU status bytes

Returns

Operation status

SAM_authenticate_host_AV2_plain()

UFR_STATUS DL_API SAM_authenticate_host_AV2_plain	(	IN uint8_t *	host_aes_key,
		uint8_t	key_nr,
		uint8_t	key_version,
		OUT uint8_t *	apdu_sw )

Function is used to run a mutual 3-pass authentication between the MIFARE SAM AV2 and PC. A host authentication is required to: • Load or update keys into the MIFARE SAM AV2 • Activate the MIFARE SAM AV2 after reset (if configured accordingly in the configuration settings of master key key_no 00h) The communication in this process is plain, so key will be exposed during function execution. Use this function in security environment (disconnect LAN).

Parameters

host_aes_key	pointer to array containing 16 bytes AES key
key_nr	key reference number (0 - 127)
key_version	key version (0 - 255)
apdu_sw	pointer to array containing SW1 and SW2 APDU status bytes

Returns

Operation status

SAM_change_key_entry_mifare_AV2_plain_one_key()

UFR_STATUS DL_API SAM_change_key_entry_mifare_AV2_plain_one_key	(	uint8_t	key_entry_no,
		IN uint8_t *	keyA,
		IN uint8_t *	keyB,
		uint8_t	key_no_CEK,
		uint8_t	key_v_CEK,
		uint8_t	ref_no_KUC,
		OUT uint8_t *	apdu_sw )

Function allows changing KST containing two Crypto 1 keys (KeyA and KeyB) for authentication to Mifare Classic or Mifare Plus card in SL1 mode. The communication in this process is plain, so keys will be exposed during function execution. Use this function in security environment (disconnect LAN).

Parameters

key_entry_no	key reference number (1 - 127)
keyA	pointer to array containing 6 bytes Crypto 1 key A
keyB	pointer to array containing 6 bytes Crypto 1 key B
key_no_CEK	reference number of CEK (Change Entry Key). (future host authentication for change this KST must be with AES key with key_no_CEK key reference number)
key_v_CEK	version of CEK (future host authentication for change this KST must be with AES key with key_ver_CEK key version)
ref_no_KUC	reference number of KUC (Key Usage Counter) (not support jet, unlimited number of authentication ref_no_KUC = 0xFF)
apdu_sw	pointer to array containing SW1 and SW2 APDU status bytes

Returns

Operation status

SAM_change_key_entry_AES_AV2_plain_one_key()

UFR_STATUS DL_API SAM_change_key_entry_AES_AV2_plain_one_key	(	uint8_t	key_entry_no,
		IN uint8_t *	key,
		uint8_t	key_no_CEK,
		uint8_t	key_v_CEK,
		uint8_t	ref_no_KUC,
		OUT uint8_t *	apdu_sw )

Function allows changing KST containing AES key for authentication to Mifare Desfire or Mifare Plus card in SL3 mode. The communication in this process is plain, so keys will be exposed during function execution. Use this function in security environment (disconnect LAN).

Parameters

key_entry_no	key reference number (1 - 127)
key	pointer to array containing 16 bytes of AES key
key_no_CEK	reference number of CEK (Change Entry Key). (future host authentication for change this KST must be with AES key with key_no_CEK key reference number)
key_v_CEK	version of CEK (future host authentication for change this KST must be with AES key with key_ver_CEK key version)
ref_no_KUC	reference number of KUC (Key Usage Counter) (not support jet, unlimited number of authentication ref_no_KUC = 0xFF)
apdu_sw	pointer to array containing SW1 and SW2 APDU status bytes

Returns

Operation status

SAM_change_key_entry_3K3DES_AV2_plain_one_key()

UFR_STATUS DL_API SAM_change_key_entry_3K3DES_AV2_plain_one_key	(	uint8_t	key_entry_no,
		IN uint8_t *	key,
		uint8_t	key_no_CEK,
		uint8_t	key_v_CEK,
		uint8_t	ref_no_KUC,
		OUT uint8_t *	apdu_sw )

Function allows changing KST containing 3K3DES key for authentication to Mifare Desfire card. The communication in this process is plain, so keys will be exposed during function execution. Use this function in security environment (disconnect LAN).

Parameters

key_entry_no	key reference number (1 - 127)
key	pointer to array containing 24 bytes of 3K3DES key
key_no_CEK	reference number of CEK (Change Entry Key). (future host authentication for change this KST must be with AES key with key_no_CEK key reference number)
key_v_CEK	version of CEK (future host authentication for change this KST must be with AES key with key_ver_CEK key version)
ref_no_KUC	reference number of KUC (Key Usage Counter) (not support jet, unlimited number of authentication ref_no_KUC = 0xFF)
apdu_sw	pointer to array containing SW1 and SW2 APDU status bytes

Returns

Operation status

SAM_change_key_entry_2K3DES_ULC_AV2_plain_one_key()

UFR_STATUS DL_API SAM_change_key_entry_2K3DES_ULC_AV2_plain_one_key	(	uint8_t	key_entry_no,
		IN uint8_t *	key,
		uint8_t	key_no_CEK,
		uint8_t	key_v_CEK,
		uint8_t	ref_no_KUC,
		OUT uint8_t *	apdu_sw )

Function allows changing KST containing 2K3DES key for authentication to Ultralight C card. The communication in this process is plain, so keys will be exposed during function execution. Use this function in security environment (disconnect LAN).

Parameters

key_entry_no	key reference number (1 - 127)
key	pointer to array containing 16 bytes of 2K3DES key
key_no_CEK	reference number of CEK (Change Entry Key). (future host authentication for change this KST must be with AES key with key_no_CEK key reference number)
key_v_CEK	version of CEK (future host authentication for change this KST must be with AES key with key_ver_CEK key version)
ref_no_KUC	reference number of KUC (Key Usage Counter) (not support jet, unlimited number of authentication ref_no_KUC = 0xFF)
apdu_sw	pointer to array containing SW1 and SW2 APDU status bytes

Returns

Operation status

SAM_change_key_entry_2K3DES_desfire_AV2_plain_one_key()

UFR_STATUS DL_API SAM_change_key_entry_2K3DES_desfire_AV2_plain_one_key	(	uint8_t	key_entry_no,
		IN uint8_t *	key,
		uint8_t	key_no_CEK,
		uint8_t	key_v_CEK,
		uint8_t	ref_no_KUC,
		OUT uint8_t *	apdu_sw )

Function allows changing KST containing 2K3DES key for authentication to Mifare Desfire card. The communication in this process is plain, so keys will be exposed during function execution. Use this function in security environment (disconnect LAN).

Parameters

key_entry_no	key reference number (1 - 127)
key	pointer to array containing 16 bytes of 2K3DES key
key_no_CEK	reference number of CEK (Change Entry Key). (future host authentication for change this KST must be with AES key with key_no_CEK key reference number)
key_v_CEK	version of CEK (future host authentication for change this KST must be with AES key with key_ver_CEK key version)
ref_no_KUC	reference number of KUC (Key Usage Counter) (not support jet, unlimited number of authentication ref_no_KUC = 0xFF)
apdu_sw	pointer to array containing SW1 and SW2 APDU status bytes

Returns

Operation status

SAM_change_key_entry_DES_AV2_plain_one_key()

UFR_STATUS DL_API SAM_change_key_entry_DES_AV2_plain_one_key	(	uint8_t	key_entry_no,
		IN uint8_t *	key,
		uint8_t	key_no_CEK,
		uint8_t	key_v_CEK,
		uint8_t	ref_no_KUC,
		OUT uint8_t *	apdu_sw )

Function allows changing KST containing DES key for authentication to Mifare Desfire card. The communication in this process is plain, so keys will be exposed during function execution. Use this function in security environment (disconnect LAN).

Parameters

key_entry_no	key reference number (1 - 127)
key	pointer to array containing 8 bytes of DES key
key_no_CEK	reference number of CEK (Change Entry Key). (future host authentication for change this KST must be with AES key with key_no_CEK key reference number)
key_v_CEK	version of CEK (future host authentication for change this KST must be with AES key with key_ver_CEK key version)
ref_no_KUC	reference number of KUC (Key Usage Counter) (not support jet, unlimited number of authentication ref_no_KUC = 0xFF)
apdu_sw	pointer to array containing SW1 and SW2 APDU status bytes

Returns

Operation status

SAM_change_key_entry_aes_AV2_plain_host_key()

UFR_STATUS DL_API SAM_change_key_entry_aes_AV2_plain_host_key	(	uint8_t	key_entry_no,
		IN uint8_t *	aes_key_ver_a,
		uint8_t	ver_a,
		IN uint8_t *	aes_key_ver_b,
		uint8_t	ver_b,
		IN uint8_t *	aes_key_ver_c,
		uint8_t	ver_c,
		uint8_t	key_no_CEK,
		uint8_t	key_v_CEK,
		uint8_t	ref_no_KUC,
		uint8_t	sam_lock_unlock,
		uint8_t	sam_auth_host,
		OUT uint8_t *	apdu_sw )

Function allows changing KST (Key Storage Table) containing 3 AES-128 keys, and their versions. The communication in this process is plain, so keys will be exposed during function execution. Use this function in security environment (disconnect LAN).

Parameters

key_entry_no	key reference number (0 - 127)
aes_key_ver_a	pointer to array containing 16 bytes of first AES key
ver_a	key version of first key (0 - 255)
aes_key_ver_b	pointer to array containing 16 bytes of second AES key
ver_b	key version of second key (0 - 255)
aes_key_ver_c	pointer to array containing 16 bytes of third AES key
ver_c	key version of third key (0 - 255)
key_no_CEK	reference number of CEK (Change Entry Key). (future host authentication for change this KST must be with AES key with key_no_CEK key reference number)
key_v_CEK	version of CEK (future host authentication for change this KST must be with AES key with key_ver_CEK key version)
ref_no_KUC	reference number of KUC (Key Usage Counter) (not support jet, unlimited number of authentication ref_no_KUC = 0xFF)
sam_lock_unlock	SAM lock/unlock ability. If key_entry_no = 0 (master key), then the SAM will be locked after power up or reset, and minimal set of commands will be available.
sam_auth_host	Host authentication ability. If key_entry_no = 0 (master key), then the authentication with host key is mandatory after power up or reset, in opposition minimal set of commands will be available.
apdu_sw	pointer to array containing SW1 and SW2 APDU status bytes

Returns

Operation status

WriteSamUnlockKey()

UFR_STATUS DL_API WriteSamUnlockKey	(	uint8_t	key_no,
		uint8_t	key_ver,
		IN uint8_t *	aes_key )

If master key has enabled lock/unlock parameter, then SAM unlock with key with lock/unlock ability is required. uFR reader tries to unlock SAM with key which stored into reader by this function. If internal reader keys locked, then they must be unlocked first, with function ReaderKeysUnlock. The communication in this process is plain, so key will be exposed during function execution. Use this function in security environment (disconnect LAN).

Parameters

key_no	key reference number (0 - 127)
key_ver	key version (0 - 255)
aes_key	pointer to array containing 16 bytes of AES key

Returns

Operation status