S_Mode

Implementation of SAM commands used for MIFARE DUOX communication in S-Mode. More...

Collaboration diagram for S_Mode:

Modules
	Defines
	Definitions for SAM commands used for MIFARE DUOX communication in S-Mode.

Functions
phStatus_t	phhalHw_Sam_Cmd_SAM_MutualAuthEcc_Part1 (phhalHw_Sam_DataParams_t *pDataParams, uint8_t bOption, uint8_t bECCKeyNo_Priv, uint8_t bCertA_FileNo, uint8_t bCertB_Options, uint8_t bECCKeyNo_CA, uint8_t **ppSamResponse, uint16_t *pSamRespLen)
	The SAM_MutualAuthEcc supports in S-mode the ECC-based Mutual and Reader-Unilateral Authentication as implemented by MIFARE DUOX with the ISOGeneralAuthenticate command. More...
phStatus_t	phhalHw_Sam_Cmd_SAM_MutualAuthEcc_Part2 (phhalHw_Sam_DataParams_t *pDataParams, uint8_t bOption, uint8_t *pPiccErrorCode, uint8_t *pCardResponse, uint8_t bCardRespLen, uint8_t **ppSamResponse, uint16_t *pSamRespLen, uint8_t *pPiccRetCode)
	Performs second part, SAM receives the ephemeral public key of the MIFARE DUOX, executes the ephemeral key agreement and returns an encrypted message containing its certificate chain and signature. More...
phStatus_t	phhalHw_Sam_Cmd_SAM_MutualAuthEcc_Part3 (phhalHw_Sam_DataParams_t *pDataParams, uint8_t bOption, uint8_t *pPiccErrorCode, uint8_t *pCardResponse, uint16_t wCardRespLen, uint8_t **ppSamResponse, uint16_t *pSamRespLen, uint8_t *pPiccRetCode)
	Performs second part, the SAM receives the encrypted message from the MIFARE DUOX and, depending on the protocol choice, returns the decrypted OptsB (Reader-Unilateral Authentication) or additionally validates and/or returns the decrypted certificate chain and signature of the MIFARE DUOX. More...
phStatus_t	phhalHw_Sam_Cmd_SAM_UnilatAuthEcc_Part1 (phhalHw_Sam_DataParams_t *pDataParams, uint8_t bOption, uint8_t bECCKeyNo_Priv, uint8_t bECC_CurveNo, uint8_t **ppSamResponse, uint16_t *pSamRespLen)
	The SAM_UnilatAuthEcc supports in S-mode the ECC-based Card-Unilateral Authentication as implemented by MIFARE DUOX with the ISOInternalAuthenticate or VDE_ECDSASign command. More...
phStatus_t	phhalHw_Sam_Cmd_SAM_UnilatAuthEcc_Part2 (phhalHw_Sam_DataParams_t *pDataParams, uint8_t *pPiccErrorCode, uint8_t *pCardResponse, uint8_t bCardRespLen, uint8_t *pPiccRetCode)
	Performs second part, the SAM receives the signature of the MIFARE DUOX, and executes the signature validation. More...
phStatus_t	phhalHw_Sam_Cmd_SAM_BindCertificate_Part1 (phhalHw_Sam_DataParams_t *pDataParams, uint8_t bOption, uint8_t *pMKPParams, uint8_t bMKPParamsLen, uint8_t bECCKeyNo_Priv, uint8_t **ppSamResponse, uint16_t *pSamRespLen)
	The SAM_BindCertificate supports in S-mode a key pair generation on MIFARE DUOX with ManageKeyPair command, followed by a certificate signing by the SAM. More...
phStatus_t	phhalHw_Sam_Cmd_SAM_BindCertificate_Part2 (phhalHw_Sam_DataParams_t *pDataParams, uint8_t bOption, uint8_t *pData, uint16_t wDataLen, uint8_t **ppResponse, uint16_t *pRespLen)
	The SAM processed the ManageKeyPair response coming from MIFARE DUOX, extracts the public key, injects in the to-be-signed certificate. More...
phStatus_t	phhalHw_Sam_Cmd_SAM_ImportEccKeyDUOX (phhalHw_Sam_DataParams_t *pDataParams, uint8_t bECCKeyNo_Priv, uint8_t *pMKPParams, uint8_t bMKPParamsLen, uint8_t **ppMKPCrypto, uint16_t *pMKPCryptoLen)
	The SAM_ImportEccKeyDUOX command supports the procedure to import a private ECC key stored on the SAM into the PICC in S-mode. More...

Detailed Description

Implementation of SAM commands used for MIFARE DUOX communication in S-Mode.

Function Documentation

phhalHw_Sam_Cmd_SAM_MutualAuthEcc_Part1()

phStatus_t phhalHw_Sam_Cmd_SAM_MutualAuthEcc_Part1	(	phhalHw_Sam_DataParams_t *	pDataParams,
		uint8_t	bOption,
		uint8_t	bECCKeyNo_Priv,
		uint8_t	bCertA_FileNo,
		uint8_t	bCertB_Options,
		uint8_t	bECCKeyNo_CA,
		uint8_t **	ppSamResponse,
		uint16_t *	pSamRespLen
	)

The SAM_MutualAuthEcc supports in S-mode the ECC-based Mutual and Reader-Unilateral Authentication as implemented by MIFARE DUOX with the ISOGeneralAuthenticate command.

Generates its ephemeral key pair for the ECDH-based key agreement and returns the public key

Note

• Post calling this interface it's must to call MutualAuthEcc Part2 and MutualAuthEcc Part3 to place SAM into proper completion state if Chaining Status is returned from Library. Otherwise error will be returned by SAM for any subsequent commands.
• If Chaining Status is not returned from Library, no need to call
  • MutualAuthEcc Part2 interface.
  • MutualAuthEcc Part3 interface.

Return values

PH_ERR_SUCCESS_CHAINING	Operation successful with Chaining response.
PH_ERR_INVALID_DATA_PARAMS	pDataParams is NULL.
PH_ERR_INVALID_PARAMETER	pSamRespLen is NULL.
Other	Depending on implementation and underlaying component.

Parameters

[in]	pDataParams	[In] Pointer to this layer's parameter structure.
[in]	bOption	[In] Option to update the P1 information. ASymmetric Mutual Authentication with Certificate.A ASymmetric Mutual Authentication without Certificate.A ASymmetric Reader-Unilateral Authentication with Certificate.A ASymmetric Reader-Unilateral Authentication without Certificate.A
[in]	bECCKeyNo_Priv	[In] ECC key entry holding the private key to be used for signing. Will be 0x00 - 0x0F
[in]	bCertA_FileNo	[In] The file number of the file holding the Cert.A certificate (chain). Present in command frame only if bOption has one of the following, ASymmetric Mutual Authentication with Certificate.A ASymmetric Reader-Unilateral Authentication with Certificate.A
[in]	bCertB_Options	[In] Cert.B processing options. One of the following No Msg.B processing by SAM. Return full Msg.B.Plain Sig.B and (if present) Cert.B certificate (chain) validated by SAM but there is no response from SAM. Sig.B and (if present) Cert.B certificate (chain) validated by SAM and there no response from SAM.
[in]	bECCKeyNo_CA	[In] ECC key entry holding the public key of the targeted CA Root Key for Cert.B validation. Will be 0x00 - 0x0F. Present in command frame only if bOption has one of the following, ASymmetric Mutual Authentication with Certificate.A ASymmetric Reader-Unilateral Authentication with Certificate.A
[out]	ppSamResponse	[Out] Ephemeral public key in uncompressed point representation ( 0x04 || E.Pub.A.x || E.Pub.A.y )
[out]	pSamRespLen	[Out] Length of bytes available in ppSamResponse buffer.

phhalHw_Sam_Cmd_SAM_MutualAuthEcc_Part2()

phStatus_t phhalHw_Sam_Cmd_SAM_MutualAuthEcc_Part2	(	phhalHw_Sam_DataParams_t *	pDataParams,
		uint8_t	bOption,
		uint8_t *	pPiccErrorCode,
		uint8_t *	pCardResponse,
		uint8_t	bCardRespLen,
		uint8_t **	ppSamResponse,
		uint16_t *	pSamRespLen,
		uint8_t *	pPiccRetCode
	)

Performs second part, SAM receives the ephemeral public key of the MIFARE DUOX, executes the ephemeral key agreement and returns an encrypted message containing its certificate chain and signature.

Also the status code of PICC will be returned to the caller in case of error.

Note

This interface should be called only if MutualAuthEcc Part1 returns Chaining Status.

Returns

Status code

Return values

PH_ERR_SUCCESS_CHAINING	Operation successful with Chaining response.
PHHAL_HW_SAM_ERR_OK_CHAINING_ACTIVE_DUOX	Correct Execution with Cert.A - final frame.
PH_ERR_AUTH_ERROR	Authentication failed: public key validation for E.Pub.B failed.
PH_ERR_INVALID_DATA_PARAMS	pDataParams is NULL.
PH_ERR_INVALID_PARAMETER	pCardResponse and pSamRespLen are NULL.
Other	Depending on implementation and underlaying component.

Parameters

[in]	pDataParams	[In] Pointer to this layer's parameter structure.
[in]	bOption	[In] Buffering options. Default: To buffer the initial command information. Use this flag exchange Ephemeral public key (E.Pub.B) or PICC Status code and start reception of encrypted message (Msg.A.enc). To receive remaining Encrypted Message (Msg.A.enc)
[in]	pPiccErrorCode	[In] Status code returned by the PICC in case of failure. Should be 2 byte in length with LSB first.
[in]	pCardResponse	[In] Ephemeral public key in uncompressed point representation ( 0x04 || E.Pub.B.x || E.Pub. B.y )
[in]	bCardRespLen	[In] Length of bytes available in pCardResponse buffer.
[out]	ppSamResponse	[Out] Enciphered Signature and Certificate (Chain, Options) If AuthMethod = 0x80 or 0x40, Correct execution with Certificate.A. Msg.A.enc = Msg.A.enc.0 || Msg.A.enc.1 || .. || Msg.A.enc.n = E(KSesAuthENC, 0xE0E0 || Cert.A || Sig.A) If AuthMethod = 0xA0 or 0x60, Correct execution without Certificate.A. Msg.A.enc = E(KSesAuthENC, 0xE0E0 || Sig.A)
[out]	pSamRespLen	[Out] Length of bytes available in ppSamResponse buffer.
[out]	pPiccRetCode	[Out] Status code from MIFARE DUOX PICC if available else zero.

phhalHw_Sam_Cmd_SAM_MutualAuthEcc_Part3()

phStatus_t phhalHw_Sam_Cmd_SAM_MutualAuthEcc_Part3	(	phhalHw_Sam_DataParams_t *	pDataParams,
		uint8_t	bOption,
		uint8_t *	pPiccErrorCode,
		uint8_t *	pCardResponse,
		uint16_t	wCardRespLen,
		uint8_t **	ppSamResponse,
		uint16_t *	pSamRespLen,
		uint8_t *	pPiccRetCode
	)

Performs second part, the SAM receives the encrypted message from the MIFARE DUOX and, depending on the protocol choice, returns the decrypted OptsB (Reader-Unilateral Authentication) or additionally validates and/or returns the decrypted certificate chain and signature of the MIFARE DUOX.

Also the status code of PICC will be returned to the caller in case of error.

Note

This interface should be called only if MutualAuthEcc Part1 and MutualAuthEcc Part2 returns Chaining Status.

Returns

Status code

Return values

PH_ERR_SUCCESS	Operation successful.
PH_ERR_SUCCESS_CHAINING	Operation successful with Chaining response.
PH_ERR_AUTH_ERROR	Authentication failed
PH_ERR_INVALID_DATA_PARAMS	pDataParams is NULL.
PH_ERR_INVALID_PARAMETER	pPiccErrorCode, pCardResponse pSamRespLen and pPiccRetCode are NULL.
Other	Depending on implementation and underlaying component.

Parameters

[in]	pDataParams	[In] Pointer to this layer's parameter structure.
[in]	bOption	[In] Buffering options. Default: To buffer the initial command information. Use this flag exchange Enciphered response from PICC (Msg.B.enc) and start reception of response. To receive remaining Mutual Authentication response
[in]	pPiccErrorCode	[In] Status code returned by the PICC in case of failure. Should be 2 byte in length with LSB first.
[in]	pCardResponse	[In] Response from PICC. One of the following If no PICC error and AuthMethod = 0x40 or 0x40, Reader-unilateral authentication Enciphered response from PICC (length X = 16): Msg.B.enc = E(K_{SesAuthEN }, 0xE1E1 || OptsB) If no PICC error and AuthMethod = 0x80 or 0xA0 and CertificateB Options == 0x00, Mutual Authentication with no SAM validation. Enciphered response from PICC (no limitation on accumulated length Sum(X)) Msg.B.enc = E(K_{SesAuthEN }, 0xE1E1 || OptsB || Cert.B||Sig.B) If no PICC error and AuthMethod = 0x80 or 0xA0 and CertificateB Options != 0x00, Mutual Authentication with SAM validation. Enciphered response from PICC ( Sum(X) le 960 or 1024 or ... ) Msg.B.enc = E(KSesAuth ENC, 0xE1E1 || OptsB || Cert.B || Sig.B)
[in]	wCardRespLen	[In] Length of bytes available in pCardResponse buffer.
[out]	ppSamResponse	[Out] One of the following, If AuthMethod = 0x80 or 0xA0 and CertificateB Options == 0x00, Mutual Authentication with no SAM validation. Opts.B || Cert.B || Sig.B If AuthMethod = 0x80 or 0xA0 and CertificateB Options == 0x02, Mutual authentication - SAM validation - more data available. Opts.B || TBSCert.B.parent || TBSCert.B.leaf If AuthMethod = 0x80 or 0xA0 and CertificateB Options == 0x01, Mutual authentication - SAM validation - no data returned. Opts.B If AuthMethod = 0x40 or 0x60, Reader-unilateral authentication. Opts.B
[out]	pSamRespLen	[Out] Length of bytes available in ppSamResponse buffer.
[out]	pPiccRetCode	[Out] Status code from MIFARE DUOX PICC if available else zero.

phhalHw_Sam_Cmd_SAM_UnilatAuthEcc_Part1()

phStatus_t phhalHw_Sam_Cmd_SAM_UnilatAuthEcc_Part1	(	phhalHw_Sam_DataParams_t *	pDataParams,
		uint8_t	bOption,
		uint8_t	bECCKeyNo_Priv,
		uint8_t	bECC_CurveNo,
		uint8_t **	ppSamResponse,
		uint16_t *	pSamRespLen
	)

The SAM_UnilatAuthEcc supports in S-mode the ECC-based Card-Unilateral Authentication as implemented by MIFARE DUOX with the ISOInternalAuthenticate or VDE_ECDSASign command.

In the first part the SAM generates and returns a random challenge. The actual protocol choice is provided to the SAM via the P1 (bOpton) parameter

Note

• Post calling this interface it's must to call UnilatAuthEcc Part2 to place SAM into proper completion state if Chaining Status is returned from Library. Otherwise error will be returned by SAM for any subsequent commands.
• If Chaining Status is not returned from Library, no need to call UnilatAuthEcc Part2 interface.

Return values

PH_ERR_SUCCESS_CHAINING	Operation successful with Chaining response.
PH_ERR_INVALID_DATA_PARAMS	pDataParams is NULL.
PH_ERR_INVALID_PARAMETER	pSamRespLen is NULL.
Other	Depending on implementation and underlaying component.

Parameters

[in]	pDataParams	[In] Pointer to this layer's parameter structure.
[in]	bOption	[In] Protocol Option to update the P1 information. ISO Internal Authentication VDE_ECDSA Signature generation
[in]	bECCKeyNo_Priv	[In] The key reference number of the ECC key entry to be used for signature verification. NVM Key: 0x00 - 0x7F RAM Key: 0xE0 - 0xE3
[in]	bECC_CurveNo	[In] The curve reference number of the ECC curve entry to be used for signature verification. Will be 0x00 - 0x03
[out]	ppSamResponse	[Out] Random challenge from SAM
[out]	pSamRespLen	[Out] Length of bytes available in ppSamResponse buffer.

phhalHw_Sam_Cmd_SAM_UnilatAuthEcc_Part2()

phStatus_t phhalHw_Sam_Cmd_SAM_UnilatAuthEcc_Part2	(	phhalHw_Sam_DataParams_t *	pDataParams,
		uint8_t *	pPiccErrorCode,
		uint8_t *	pCardResponse,
		uint8_t	bCardRespLen,
		uint8_t *	pPiccRetCode
	)

Performs second part, the SAM receives the signature of the MIFARE DUOX, and executes the signature validation.

Also the status code of PICC will be returned to the caller in case of error.

Note

This interface should be called only if UnilatAuthEcc Part1 returns Chaining Status.

Returns

Status code

Return values

PH_ERR_SUCCESS	Operation successful.
PH_ERR_AUTH_ERROR	Authentication failed: Sig.B verification failed
PH_ERR_INVALID_DATA_PARAMS	pDataParams is NULL.
PH_ERR_INVALID_PARAMETER	pPiccErrorCode, pCardResponse pSamRespLen and pPiccRetCode are NULL.
Other	Depending on implementation and underlaying component.

Parameters

[in]	pDataParams	[In] Pointer to this layer's parameter structure.
[in]	pPiccErrorCode	[In] Status code returned by the PICC in case of failure. Should be 2 byte in length with LSB first.
[in]	pCardResponse	[In] Response from PICC. One of the following If no PICC error and ProtocolOption = 0x00, 16 byte Random challenge from PICC followed by 64 byte Signature. RndA || Sig.B = ECDSA_Sign(Priv.B, 0xF0F0 [|| OptsA] || RndB || RndA) If no PICC error and ProtocolOption = 0x01, 16 byte Random challenge from PICC followed by 64 byte Signature. RndA || Sig.B = ECDSA_Sign(Priv.B, RA)
[in]	bCardRespLen	[In] Length of bytes available in pCardResponse buffer.
[out]	pPiccRetCode	[Out] Status code from MIFARE DUOX PICC if available else zero.

phhalHw_Sam_Cmd_SAM_BindCertificate_Part1()

phStatus_t phhalHw_Sam_Cmd_SAM_BindCertificate_Part1	(	phhalHw_Sam_DataParams_t *	pDataParams,
		uint8_t	bOption,
		uint8_t *	pMKPParams,
		uint8_t	bMKPParamsLen,
		uint8_t	bECCKeyNo_Priv,
		uint8_t **	ppSamResponse,
		uint16_t *	pSamRespLen
	)

The SAM_BindCertificate supports in S-mode a key pair generation on MIFARE DUOX with ManageKeyPair command, followed by a certificate signing by the SAM.

SAM enables the key pair generation by computing the ManageKeyPair secure messaging. This is equivalent to a SAM_Apply_SM execution. MIFARE DUOX may return an error code during the execution of the protocol, the SAM will accept this also in Part2 and Part3. In that case, the certificate binding is interrupted and the PICC error will be echoed with Resp.ISO90DF

Note

• Post calling this interface it's must to call BindCertificate Part2 to place SAM into proper completion state if Chaining Status is returned from Library. Otherwise error will be returned by SAM for any subsequent commands.
• If Chaining Status is not returned from Library, no need to call BindCertificate Part2 interface.

Return values

PH_ERR_SUCCESS_CHAINING	Operation successful with Chaining response.
PH_ERR_INVALID_DATA_PARAMS	pDataParams is NULL.
PH_ERR_INVALID_PARAMETER	pMKPParams and pSamRespLen are NULL.
Other	Depending on implementation and underlaying component.

Parameters

[in]	pDataParams	[In] Pointer to this layer's parameter structure.
[in]	bOption	[In] Protection mode for ManageKeyPair command towards MIFARE DUOX. CommMode.Plain CommMode.MAC CommMode.Full
[in]	pMKPParams	[In] MIFARE DUOX ManageKeyPair Parameters. One of the following KeyNo: Key number of the key to be managed on MIFARE DUOX Option: Targeted action: Generate Key Pair CurveID: Targeted curve on MIFARE DUOX KeyPolicy: Defines allowed Crypto operations on MIFARE DUOX WriteAccess: Access right and CommMode for further updates on MIFARE DUOX KUCLimit: Defines the key usage limit of the targeted key on MIFARE DUOX
[in]	bMKPParamsLen	[In] Length of bytes available in pMKPParams buffer.
[in]	bECCKeyNo_Priv	[In] ECC key entry holding the private key to be used for certificate signing in Part 2. Will be 0x00 - 0x0F
[out]	ppSamResponse	[Out] MKPMAC: 8 bytes as MACt(KsesAuthMAC, Cmd || MKPParams)
[out]	pSamRespLen	[Out] Length of bytes available in ppSamResponse buffer.

phhalHw_Sam_Cmd_SAM_BindCertificate_Part2()

phStatus_t phhalHw_Sam_Cmd_SAM_BindCertificate_Part2	(	phhalHw_Sam_DataParams_t *	pDataParams,
		uint8_t	bOption,
		uint8_t *	pData,
		uint16_t	wDataLen,
		uint8_t **	ppResponse,
		uint16_t *	pRespLen
	)

The SAM processed the ManageKeyPair response coming from MIFARE DUOX, extracts the public key, injects in the to-be-signed certificate.

Then it signs the certificate and returns the signed certificate.

Note

This interface should be called only if BindCertificate Part1 returns Chaining Status.

Returns

Status code

Return values

PH_ERR_SUCCESS	Operation successful.
PH_ERR_SUCCESS_CHAINING	Operation successful, chaining ongoing.
PH_ERR_INVALID_DATA_PARAMS	pDataParams is NULL.
PH_ERR_INVALID_PARAMETER	pMessage and pHashLen are NULL
Other	Depending on implementation and underlaying component.

Parameters

[in]	pDataParams	[In] Pointer to this layer's parameter structure.
[in]	bOption	[In] Buffering Options: Default: To buffer the initial command information. Use this flag to exchange MIFARE DUOX ManageKeyPair Parameters, Certificate to be signed and start reception of response. The LFI is set to AFh for reception of remaining data from SAM
[in]	pData	[In] Information to be exchanged to SAM. In case of no PICC error, MIFARE DUOX ManageKeyPair Parameters Comm.MAC : RC || PublicKey || MACt (KSesAuthMAC, RC || CmdCtr || TI || PublicKey) Comm.FULL: RC || E (KSesAuthENC, PublicKey) || MACt (RC || CmdCtr || TI || E (KSesAuthENC, PublicKey)) Certificate to be signed In case of PICC error: 2 byte PICC error
[in]	wDataLen	[In] Length of bytes available in pData buffer.
[out]	ppResponse	[Out] Buffer containing the information received from SAM. Certificate signed by SAM Status code of PICC
[out]	pRespLen	[Out] Length of bytes available in pResponse buffer.

phhalHw_Sam_Cmd_SAM_ImportEccKeyDUOX()

phStatus_t phhalHw_Sam_Cmd_SAM_ImportEccKeyDUOX	(	phhalHw_Sam_DataParams_t *	pDataParams,
		uint8_t	bECCKeyNo_Priv,
		uint8_t *	pMKPParams,
		uint8_t	bMKPParamsLen,
		uint8_t **	ppMKPCrypto,
		uint16_t *	pMKPCryptoLen
	)

The SAM_ImportEccKeyDUOX command supports the procedure to import a private ECC key stored on the SAM into the PICC in S-mode.

The command generates and returns the cryptogram to be sent to the PICC. For the ManageKeyPair response received from the PICC, regular secure messaging processing with SAM_Remove_SM can be applied

Return values

PH_ERR_SUCCESS	Operation successful.
PH_ERR_INVALID_DATA_PARAMS	pDataParams is NULL.
PH_ERR_INVALID_PARAMETER	pMKPParams and pSamRespLen are NULL.
Other	Depending on implementation and underlaying component.

Parameters

[in]	pDataParams	[In] Pointer to this layer's parameter structure.
[in]	bECCKeyNo_Priv	[In] ECC key entry holding the private key to be imported in MIFARE DUOX. Will be 0x00 - 0x0F
[in]	pMKPParams	[In] MIFARE DUOX ManageKeyPair Parameters. One of the following KeyNo: Key number of the key to be managed on MIFARE DUOX Option: Targeted action: Import Key Pair CurveID: Targeted curve on MIFARE DUOX KeyPolicy: Defines allowed crypto operations on MIFARE DUOX WriteAccess: Access right and CommMode for further updates on MIFARE DUOX KUCLimit: Defines the key usage limit of the targeted key on MIFARE DUOX
[in]	bMKPParamsLen	[In] Length of bytes available in pMKPParams buffer.
[out]	ppMKPCrypto	[Out] Cryptogram holding key data: E (KSesAuthENC, Private Key) || MACt (Cmd || CmdCtr || TI || MKPParams || E (KSesAuthENC, PrivateKey))
[out]	pMKPCryptoLen	[Out] Length of bytes available in ppMKPCrypto buffer.