uFCoder 2.62
Loading...
Searching...
No Matches
Support for NXP SAM (Secure Application Module)

Functions related to interacting with the SAM (Secure Application Module), such as authentication, key entry and more. More...

Functions

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

Detailed Description

Functions related to interacting with the SAM (Secure Application Module), such as authentication, key entry and more.

Function Documentation

◆ 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_keypointer to array containing 16 bytes AES key
key_nrkey reference number (0 - 127)
key_versionkey version (0 - 255)
apdu_swpointer 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_nokey reference number (1 - 127)
keypointer to array containing 16 bytes of 2K3DES key
key_no_CEKreference 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_CEKversion of CEK (future host authentication for change this KST must be with AES key with key_ver_CEK key version)
ref_no_KUCreference number of KUC (Key Usage Counter) (not support jet, unlimited number of authentication ref_no_KUC = 0xFF)
apdu_swpointer 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_nokey reference number (1 - 127)
keypointer to array containing 16 bytes of 2K3DES key
key_no_CEKreference 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_CEKversion of CEK (future host authentication for change this KST must be with AES key with key_ver_CEK key version)
ref_no_KUCreference number of KUC (Key Usage Counter) (not support jet, unlimited number of authentication ref_no_KUC = 0xFF)
apdu_swpointer 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_nokey reference number (1 - 127)
keypointer to array containing 24 bytes of 3K3DES key
key_no_CEKreference 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_CEKversion of CEK (future host authentication for change this KST must be with AES key with key_ver_CEK key version)
ref_no_KUCreference number of KUC (Key Usage Counter) (not support jet, unlimited number of authentication ref_no_KUC = 0xFF)
apdu_swpointer 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_nokey reference number (0 - 127)
aes_key_ver_apointer to array containing 16 bytes of first AES key
ver_akey version of first key (0 - 255)
aes_key_ver_bpointer to array containing 16 bytes of second AES key
ver_bkey version of second key (0 - 255)
aes_key_ver_cpointer to array containing 16 bytes of third AES key
ver_ckey version of third key (0 - 255)
key_no_CEKreference 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_CEKversion of CEK (future host authentication for change this KST must be with AES key with key_ver_CEK key version)
ref_no_KUCreference number of KUC (Key Usage Counter) (not support jet, unlimited number of authentication ref_no_KUC = 0xFF)
sam_lock_unlockSAM 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_hostHost 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_swpointer 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_nokey reference number (1 - 127)
keypointer to array containing 16 bytes of AES key
key_no_CEKreference 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_CEKversion of CEK (future host authentication for change this KST must be with AES key with key_ver_CEK key version)
ref_no_KUCreference number of KUC (Key Usage Counter) (not support jet, unlimited number of authentication ref_no_KUC = 0xFF)
apdu_swpointer 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_nokey reference number (1 - 127)
keypointer to array containing 8 bytes of DES key
key_no_CEKreference 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_CEKversion of CEK (future host authentication for change this KST must be with AES key with key_ver_CEK key version)
ref_no_KUCreference number of KUC (Key Usage Counter) (not support jet, unlimited number of authentication ref_no_KUC = 0xFF)
apdu_swpointer 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_nokey reference number (1 - 127)
keyApointer to array containing 6 bytes Crypto 1 key A
keyBpointer to array containing 6 bytes Crypto 1 key B
key_no_CEKreference 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_CEKversion of CEK (future host authentication for change this KST must be with AES key with key_ver_CEK key version)
ref_no_KUCreference number of KUC (Key Usage Counter) (not support jet, unlimited number of authentication ref_no_KUC = 0xFF)
apdu_swpointer to array containing SW1 and SW2 APDU status bytes
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_nokey reference number (0 - 127)
key_entrypointer to array containing key entry data
key_lengthpointer to key entry length variable
apdu_swpointer to array containing SW1 and SW2 APDU status bytes
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_typepointer to SAM type variable
sam_uidpointer to array containing 7 bytes UID
Returns
Operation status

◆ 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
datapointer to array containing version data
lengthpointer to length variable
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_nokey reference number (0 - 127)
key_verkey version (0 - 255)
aes_keypointer to array containing 16 bytes of AES key
Returns
Operation status