Describes about the NTAG X DNA Secure Messaging related commands. More...

Collaboration diagram for Commands_SecureMessaging:

Modules
	Defines
	Macro Definitions for Secure Messaging commands.

	Certificate_Structure
	Structure for NTAG X DNA Host / Device Certificates to be used with the below mentioned interfaces.

Functions
phStatus_t	phalNtagXDna_ISOGeneralAuthenticate (void pDataParams, uint8_t bDeviceCert_Cached, uint8_t bIsHostResponder, uint8_t bCertRepoID, uint8_t bCert_Depth, uint8_t bKeySize, uint16_t wPriv_KeyNo, uint16_t wPriv_KeyPos, uint16_t wPub_KeyNo, uint16_t wPub_KeyPos, uint8_t pExpRspLen, uint8_t bExpRspLen, phalNtagXDna_Cert stHostCert, phalNtagXDna_Cert *pDeviceCert)
	Performs ASymmetric Mutual SIGMA-I authentication. More...

phStatus_t	phalNtagXDna_ISOInternalAuthenticate (void pDataParams, uint8_t bPrivKeyNo, uint8_t bCurveID, uint8_t pPubBKey, uint16_t wPubBKeyLen, uint8_t pOptsA, uint8_t bOptsALen, uint8_t pExpRspLen, uint8_t bExpRspLen)
	Performs Asymmetric Card-Unilateral Authentication. More...

phStatus_t	phalNtagXDna_AuthenticateEv2 (void pDataParams, uint8_t bFirstAuth, uint16_t wOption, uint16_t wKeyNo, uint16_t wKeyVer, uint8_t bKeyNoCard, uint8_t pDivInput, uint8_t bDivLen, uint8_t pPcdCapsIn, uint8_t bLenPcdCapsIn, uint8_t pPcdCapsOut, uint8_t *pPdCapsOut)
	Performs an Ev2 First or Non First Authentication depending upon bFirstAuth Parameter. More...

phStatus_t	phalNtagXDna_ProcessSMApply (void pDataParams, uint8_t bCommMode, uint8_t bOffset, uint8_t bCmdCtrIncr, uint8_t pData, uint8_t bDataLen, uint8_t *ppResponse, uint16_t pRspLen)
	Performs ProcessSM Apply. More...

phStatus_t	phalNtagXDna_ProcessSMRemove (void pDataParams, uint8_t bCommMode, uint8_t pData, uint8_t bDataLen, uint8_t *ppResponse, uint16_t pRspLen)
	Performs ProcessSM Remove. More...

Detailed Description

Describes about the NTAG X DNA Secure Messaging related commands.

Function Documentation

◆ phalNtagXDna_ISOGeneralAuthenticate()

phStatus_t phalNtagXDna_ISOGeneralAuthenticate	(	void *	pDataParams,
		uint8_t	bDeviceCert_Cached,
		uint8_t	bIsHostResponder,
		uint8_t	bCertRepoID,
		uint8_t	bCert_Depth,
		uint8_t	bKeySize,
		uint16_t	wPriv_KeyNo,
		uint16_t	wPriv_KeyPos,
		uint16_t	wPub_KeyNo,
		uint16_t	wPub_KeyPos,
		uint8_t *	pExpRspLen,
		uint8_t	bExpRspLen,
		phalNtagXDna_Cert	stHostCert,
		phalNtagXDna_Cert *	pDeviceCert
	)

Performs ASymmetric Mutual SIGMA-I authentication.

This interfaces performs Cmd.ISOGeneralAuthenticate with Host acts as Initiator or Responder mode based on the information provided in bIsHostResponder parameter.

During ISOGeneralAuthenticate, Ephemeral Key Pair is generated by the Library.
Device End-Leaf Certificate hash and Signature are verified by the Library internally.
Exchange of Abort Tag is not supported by the library.
Interface provides received Device Certificates. The certificate validation is not carried by Library and shall be taken up by the user.
If bDeviceCert_Cached == On, means user has to provide Device End-Leaf certificate only. This will be used for Certificate Hash and Signature Verification received from Device.

Returns: Status code

Return values

PH_ERR_SUCCESS	Operation successful.
PH_ERR_INVALID_DATA_PARAMS	If DataParams is null.
PH_ERR_INVALID_PARAMETER	If the buffers are null. Parameter Values not supported for Authentication. If bDeviceCert_Cached == On and Device End-Leaf Certificate is not available. i.e pDeviceCert->wEndLeaf_Len = 0
PH_ERR_PROTOCOL_ERROR	If information received is not proper.
PH_ERR_ABORTED	If Device aborts the authentication.
PHAL_NTAGXDNA_ERR_DEVICE_SIGNATURE_ERROR	Verification of Device Signature combination failed.
PHAL_NTAGXDNA_ERR_DEVICE_LEAF_CERTIFICATE_HASH_ERROR	Verification of Device End-Leaf Certificate Hash failed.
XXXX	Depending on status codes return by PICC. Other Depending on implementation and underlying component.

Parameters

[in]	pDataParams	[In] Pointer to this layer's parameter structure.
[in]	bDeviceCert_Cached	[In] Whether or not the device certificates are cached. If cached, user need to provide End-Leaf certificate for Certificate Hash and Signature verification. Device Certificate(s) are not cached Device Certificate(s) are cached
[in]	bIsHostResponder	[In] Flag to indicate whether Host is Initiator or responder. Will be one of the following values Host as Initiator Host as Responder
[in]	bCertRepoID	[In] Certificate repository Id to use to execute the protocol. Supported values are 0x00 - 0x07
[in]	bCert_Depth	[In] Certificate Depth to exchange. Will be one of the following End-Leaf Only End-Leaf and Parent End-Leaf, Parent and Grand-Parent
[in]	bKeySize	[In] Type of Session Key Size to use. Will be one of the following Session KeySize as AES128 Session KeySize as AES256
[in]	wPriv_KeyNo	[In] Key number in KeyStore to use, known as Initiator's / Responder's Private Key. This will be used to sign the message that will be exchanged, basically sk_init if Host is Initiator or sk_resp if Host is responder. Will be used for one of the following ECC Signature generation Init_ECC_Sig = ECDSA-Sign(sk_init , 0x02 \|\| keySize_init \|\| keySize_resp \|\| yP \|\| xP \|\| AES_CMAC(K_m1, 0x02�\|\| leaf_cert_hash)) Resp_ECC_Sig = ECDSA-Sign(sk_resp, 0x01 \|\| keySize_init \|\| keySize_resp \|\| xP \|\| yP \|\| AES-CMAC(K_m1, 0x01 \|\| leaf_cert _hash))
[in]	wPriv_KeyPos	[In] Key position in KeyStore to use. The position where wPriv_KeyNo is stored.
[in]	wPub_KeyNo	[In] Key number in KeyStore to use, known as Initiator's / Responder's Public Key. This will be used to verify the signature that was received, basically Init_ECC_Sig if Host is Responder or Resp_ECC_Sig if Host is Initiator.
[in]	wPub_KeyPos	[In] Key position in KeyStore to use. The position where wPub_KeyNo is stored.
[in]	pExpRspLen	[In] Length of expected response from Device. This parameter is for exchanging the LE information. If NULL is provided, then the expected Response length will be taken as 0x00 (1 byte) by default. Possible values are NULL, Array consisting of 1 byte or 2 bytes.
[in]	bExpRspLen	[In] Length of bytes available in pExpRspLen buffer.
[in]	stHostCert	[In] Structure holding the Host certificate(s) that will be exchanged to device. The certificate should be filled based on bCert_Depth "Certificate Depth" information.
[in,out]	pDeviceCert	[In, Out] Structure holding the Device certificate(s) received. The certificate should be filled based on bCert_Depth "Certificate Depth" and information. [In]: Provide End-Leaf Certificate if bDeviceCert_Cached == On [Out]: Certificates will be returned if bDeviceCert_Cached == Off

◆ phalNtagXDna_ISOInternalAuthenticate()

phStatus_t phalNtagXDna_ISOInternalAuthenticate	(	void *	pDataParams,
		uint8_t	bPrivKeyNo,
		uint8_t	bCurveID,
		uint8_t *	pPubBKey,
		uint16_t	wPubBKeyLen,
		uint8_t *	pOptsA,
		uint8_t	bOptsALen,
		uint8_t *	pExpRspLen,
		uint8_t	bExpRspLen
	)

Performs Asymmetric Card-Unilateral Authentication.

The following operations are performed using this interface.

Ephemeral Key Pair (E.Pub.A) is generated by the Library.
The Signature (Sig.B) received as part of response is verified using the Key Number provided in wKeyNo_PubKeyB parameter.

Returns: Status code

Return values

PH_ERR_SUCCESS	Operation successful.
PH_ERR_INVALID_DATA_PARAMS	If DataParams is null.
PH_ERR_INVALID_PARAMETER	If the buffers are null.
PH_ERR_PROTOCOL_ERROR	If Tag information is not proper for AuthDOHdr, RndB and Signature.
PH_ERR_VERIFICATION_FAILED	Verification of Message / Signature combination failed.
XXXX	Depending on status codes return by PICC. Other Depending on implementation and underlying component.

Parameters

[in]	pDataParams	[In] Pointer to this layer's parameter structure.
[in]	bPrivKeyNo	[In] Private Key number for signing the response. At PICC level, only one key is supported which is 0x01. At Application level, up to five keys are supported.
[in]	bCurveID	[In] The targeted curve for the public key provided in pPubBKey parameter. Should be one of the below values. P-256 BP-256
[in]	pPubBKey	[In] Public Key (Pub.B) to be used for verification.
[in]	wPubBKeyLen	[In] Length of bytes available in pPubBKey buffer.
[in]	pOptsA	[In] Complete PCD Options in TLV format. NULL in case of Optional scenario
[in]	bOptsALen	[In] Length of bytes available in pOptsA buffer. Zero in case of Optional scenario.
[in]	pExpRspLen	[In] Length of expected response from Device. This parameter is for exchanging the LE information. If NULL is provided, then the expected Response length will be taken as 0x00 (1 byte) by default or 2 bytes based on LC. Possible values are NULL, Array consisting of 1 byte or 2 bytes.
[in]	bExpRspLen	[In] Length of bytes available in pExpRspLen buffer.

◆ phalNtagXDna_AuthenticateEv2()

phStatus_t phalNtagXDna_AuthenticateEv2	(	void *	pDataParams,
		uint8_t	bFirstAuth,
		uint16_t	wOption,
		uint16_t	wKeyNo,
		uint16_t	wKeyVer,
		uint8_t	bKeyNoCard,
		uint8_t *	pDivInput,
		uint8_t	bDivLen,
		uint8_t *	pPcdCapsIn,
		uint8_t	bLenPcdCapsIn,
		uint8_t *	pPcdCapsOut,
		uint8_t *	pPdCapsOut
	)

Performs an Ev2 First or Non First Authentication depending upon bFirstAuth Parameter.

This will be using the AES128 or AES256 keys and will generate and verify the contents based on generic AES algorithm. The Random number generation will be performed by the library.

Returns: Status code

Return values

PH_ERR_SUCCESS	Operation successful.
PH_ERR_INVALID_DATA_PARAMS	If DataParams is null.
PH_ERR_INVALID_PARAMETER	If the buffers are null. For Invalid AuthType (bFirstAuth), Invalid Diversification Options (wOption). If Diversification is higher than Maximum Diversification Length.
PH_ERR_KEY	KeyType is not of AES128.
PH_ERR_PROTOCOL_ERROR	If Response length is not of AES128 Block Size (Single or multiple).
PH_ERR_AUTH_ERROR	If Received RndA do not match.
XXXX	Depending on status codes return by tag. Other Depending on implementation and underlying component.

Parameters

[in]	pDataParams	[In] Pointer to this layer's parameter structure.
[in]	bFirstAuth	[In] Authentication type to perform. One of the below options. First Authentication Following Authentication
[in]	wOption	[In] One of the below options. No Diversification Encryption Method of Diversification CMAC Method of Diversification
[in]	wKeyNo	[In] Key number in KeyStore of software.
[in]	wKeyVer	[In] Key version in the key store of software.
[in]	bKeyNoCard	[In] Key number on card. Valid values are 0x00 - 0x04
[in]	pDivInput	[In] Diversification input to be used for diversifying the key. Can be NULL.
[in]	bDivLen	[In] Length of bytes available in pDivInput buffer.
[in]	pPcdCapsIn	[In] PCD Capabilities. Upto 6 bytes.
[in]	bLenPcdCapsIn	[In] Length of PcdCapsIn. Always zero for NonFirst authentication.
[out]	pPcdCapsOut	[Out] PCD Capabilities. The size of the buffer should be 6 bytes long.
[out]	pPdCapsOut	[Out] PD Capabilities. The size of the buffer should be 6 bytes long.

◆ phalNtagXDna_ProcessSMApply()

phStatus_t phalNtagXDna_ProcessSMApply	(	void *	pDataParams,
		uint8_t	bCommMode,
		uint8_t	bOffset,
		uint8_t	bCmdCtrIncr,
		uint8_t *	pData,
		uint8_t	bDataLen,
		uint8_t **	ppResponse,
		uint16_t *	pRspLen
	)

Performs ProcessSM Apply.

The ProcessSM_Apply is used for applying secure messaging to a command before sending it to the target device.

Returns: Status code

Return values

PH_ERR_SUCCESS	Operation successful.
PH_ERR_INVALID_DATA_PARAMS	If DataParams is null.
PH_ERR_INVALID_PARAMETER	If the buffers are null.
XXXX	Depending on status codes return by tag. Other Depending on implementation and underlying component.

Parameters

[in]	pDataParams	[In] Pointer to this layer's parameter structure.
[in]	bCommMode	[In] Indicates the protection mode to be applied Plain Mode (0x00) Plain Mode (0x20) MAC Mode Full Mode
[in]	bOffset	[In] Index of the first byte of CmdData in Data field. Only applicable when bCommMode is Full Mode
[in]	bCmdCtrIncr	[In] Command counter increment value. Only applicable when bCommMode is Plain Mode (0x00) Plain Mode (0x20)
[in]	pData	[In] Plain data to protect. One of the following NULL if bCommMode is Plain Mode (0x00) Plain Mode (0x20) The plain data to be protected if bCommMode is MAC Mode Full Mode
[in]	bDataLen	[In] Length of bytes available in pData buffer.
[out]	ppResponse	[Out] Buffer containing the following, NULL if bCommMode is Plain Mode (0x00) or Plain Mode (0x20) 8 bytes MAC if bCommMode is MAC Mode Encrypted data + MAC if bCommMode is Full Mode
[out]	pRspLen	[Out] Length of Bytes available in ppResponse buffer.

◆ phalNtagXDna_ProcessSMRemove()

phStatus_t phalNtagXDna_ProcessSMRemove	(	void *	pDataParams,
		uint8_t	bCommMode,
		uint8_t *	pData,
		uint8_t	bDataLen,
		uint8_t **	ppResponse,
		uint16_t *	pRspLen
	)

Performs ProcessSM Remove.

The ProcessSM_Remove is used for removing and validating secure messaging from a response received from a target device.

Returns: Status code

Return values

PH_ERR_SUCCESS	Operation successful.
PH_ERR_INVALID_DATA_PARAMS	If DataParams is null.
PH_ERR_INVALID_PARAMETER	If the buffers are null.
XXXX	Depending on status codes return by tag. Other Depending on implementation and underlying component.

Parameters

[in]	pDataParams	[In] Pointer to this layer's parameter structure.
[in]	bCommMode	[In] Indicates the protection mode to be applied MAC Mode Full Mode
[in]	pData	[In] Data from which protection to be removed. One of the following If bCommMode is MAC then, input data will be RC [\|\| RespData] \|\| MAC If bCommMode is FULL then, input data will be RC [\|\| Encrypted RespData] \|\| MAC
[in]	bDataLen	[In] Length of bytes available in pData buffer.
[out]	ppResponse	[Out] Buffer containing the following, If bCommMode is MAC then, there will be no response. If bCommMode is FULL then, Plain data will be returned.
[out]	pRspLen	[Out] Length of Bytes available in ppResponse buffer.

Modules

Functions

Detailed Description

Function Documentation

◆ phalNtagXDna_ISOGeneralAuthenticate()

◆ phalNtagXDna_ISOInternalAuthenticate()

◆ phalNtagXDna_AuthenticateEv2()

◆ phalNtagXDna_ProcessSMApply()

◆ phalNtagXDna_ProcessSMRemove()