Implementation of SAM File Management commands. More...

Collaboration diagram for 04_FileManagement:

Modules
	Defines
	Definitions for SAM File Management commands.

Functions
phStatus_t	phhalHw_Sam_Cmd_SAM_CreateFile (phhalHw_Sam_DataParams_t pDataParams, uint8_t bFileNo, uint8_t bFileType, uint8_t bKeyNoAEK_Read, uint8_t bKeyVAEK_Read, uint8_t bKeyNoAEK_Write, uint8_t bKeyVAEK_Write, uint8_t pFileSize, uint8_t bCRLOptions, uint8_t bCSNSize, uint8_t bCSNSigKey)
	Performs creation of file. More...

phStatus_t	phhalHw_Sam_Cmd_SAM_ReadFile (phhalHw_Sam_DataParams_t pDataParams, uint8_t bOption, uint8_t bFileNo, uint8_t pOffset, uint8_t pLength, uint8_t ppResponse, uint16_t pRespLen)
	Performs reading of data. More...

phStatus_t	phhalHw_Sam_Cmd_SAM_WriteFile (phhalHw_Sam_DataParams_t pDataParams, uint8_t bOption, uint8_t bFileNo, uint16_t wCRLVer, uint8_t pOffset, uint8_t pData, uint8_t pLength)
	Performs writing of data. More...

phStatus_t	phhalHw_Sam_Cmd_SAM_WriteFileOffline (phhalHw_Sam_DataParams_t pDataParams, uint8_t bFileNo, uint16_t wChangeCtr, uint8_t pOfflineCrypto, uint32_t dwOfflineCryptoLen, uint8_t bEnableOfflineAck, uint8_t *ppOfflineAck, uint16_t pOfflineAckLen)
	Performs writing of data offline. More...

phStatus_t	phhalHw_Sam_Cmd_SAM_GetFileSettings (phhalHw_Sam_DataParams_t pDataParams, uint8_t bFileNo, uint8_t ppResponse, uint16_t pRespLen)
	Performs reading the meta-data of a file. More...

phStatus_t	phhalHw_Sam_Cmd_SAM_Format (phhalHw_Sam_DataParams_t *pDataParams)
	Performs deletion of all files. More...

Detailed Description

Implementation of SAM File Management commands.

Function Documentation

◆ phhalHw_Sam_Cmd_SAM_CreateFile()

phStatus_t phhalHw_Sam_Cmd_SAM_CreateFile	(	phhalHw_Sam_DataParams_t *	pDataParams,
		uint8_t	bFileNo,
		uint8_t	bFileType,
		uint8_t	bKeyNoAEK_Read,
		uint8_t	bKeyVAEK_Read,
		uint8_t	bKeyNoAEK_Write,
		uint8_t	bKeyVAEK_Write,
		uint8_t *	pFileSize,
		uint8_t	bCRLOptions,
		uint8_t	bCSNSize,
		uint8_t	bCSNSigKey
	)

Performs creation of file.

The FileType defines if the created file is a regular binary data file (typically used to store certificates), or a CRLFile. A CRLFile is used for certificate revocation. If a CRLFile is targeted, the following additional parameters are present: CRLOptions, CSNSize and , depending on CRLOptions value CSNSigKey. The CRLVersion is initialized to zero.

Returns: Status code

Return values

PH_ERR_SUCCESS	Operation successful.
PH_ERR_INVALID_DATA_PARAMS	pDataParams is NULL.
PH_ERR_INVALID_PARAMETER	pFileSize and pRespLen is NULL.
Other	Depending on implementation and underlaying component.

Parameters

[in]	pDataParams	[In] Pointer to this layer's parameter structure.
[in]	bFileNo	[In] File number to be created. Supported numbers are 00 - 0F
[in]	bFileType	[In] Type of file to create. One of the following, Certificate File CRL File
[in]	bKeyNoAEK_Read	[In] Key reference number of KST access entry key for reading. 0xFE : No access restriction 0x00 - 0x7F: Restricted to specific permanent KST Key Entry
[in]	bKeyVAEK_Read	[In] Key version of KST access entry key for reading.
[in]	bKeyNoAEK_Write	[In] Key reference number of KST access entry key for writing. 0xFE : No access restriction 0x00 - 0x7F: Restricted to specific permanent KST Key Entry
[in]	bKeyVAEK_Write	[In] Key version of KST access entry key for writing.
[in]	pFileSize	[In] File size in bytes for the file to be created. Will be of 3 bytes with LSB first. If size 0x10 need to be created, then the FileSize will be 10 00 00. Supported size ranges from 0x000001 - 0x008000
[in]	bCRLOptions	[In] CRLVersion required to be incremented by 1. Will be exchange if bFileType = CRL File
[in]	bCSNSize	[In] CSN size to use. Supported values are 0x04, 0x07, 0x0A. Will be exchange if bFileType = CRL File
[in]	bCSNSigKey	[In] Targeted ECC Key Entry for CRLSignature validation. Supported values are 0x00 - 0x07. Will be exchange if bFileType = CRL File

◆ phhalHw_Sam_Cmd_SAM_ReadFile()

phStatus_t phhalHw_Sam_Cmd_SAM_ReadFile	(	phhalHw_Sam_DataParams_t *	pDataParams,
		uint8_t	bOption,
		uint8_t	bFileNo,
		uint8_t *	pOffset,
		uint8_t *	pLength,
		uint8_t **	ppResponse,
		uint16_t *	pRespLen
	)

Performs reading of data.

The data to be read is defined by the file number of the targeted file, the offset in the data file where to start the reading and its size in bytes. The file number specifying the file where to read the data from is given by FileNo encoded in P1.
The position byte-wise in the data file where to start to read data is given by Offset. Its valid range is from 0x000000 to FileSize - 1. The data size to be read is given by Length specifying the number of bytes. If Length is equal to 0x000000 then the entire data file has to be read starting from the position specified by the Offset value. Length valid range is 0x000000 to FileSize - Offset.
If the number of bytes to read does not fit into one single APDU response, Chaining Status is provided to user and user should call this interface again with bOption set to Receive Remaining Data.

Returns: Status code

Return values

PH_ERR_SUCCESS	Operation successful.
PH_ERR_SUCCESS_CHAINING	Operation successful with more response data remaining.
PH_ERR_INVALID_DATA_PARAMS	pDataParams is NULL.
PH_ERR_INVALID_PARAMETER	pOffset, pLength and pRespLen is NULL.
Other	Depending on implementation and underlaying component.

Parameters

[in]	pDataParams	[In] Pointer to this layer's parameter structure.
[in]	bOption	[In] Option of reception of data from SAM. One of the following, Exchange command and receive the response. This option means there is no further data to be read from SAM. Receive Remaining Data from SAM. Should be used only when interface returns Chaining Response. Here bFileNo, pOffset and pLength information will not be exchanged to SAM.
[in]	bFileNo	[In] File number of the file to be read. 00 - 0F: User File F0 : Originality Certificate File
[in]	pOffset	[In] The offset from where the data should be read. Will be of 3 bytes. with LSB first. If 0x10 need to be offset, then it will be 10 00 00. 0 to (FileSize - 1): Starting position of Read operation 0xFFFFFFFF : Return CRLFile Meta-Data
[in]	pLength	[In] The number of bytes to be read. Will be of 3 bytes with LSB first. If 0x10 bytes need to be read, then it will be 10 00 00. If complete file need to be read, then it will be 00 00 00.
[out]	ppResponse	[Out] The contents of the File returned by SAM.
[out]	pRespLen	[Out] Length of bytes available in ppResponse buffer.

◆ phhalHw_Sam_Cmd_SAM_WriteFile()

phStatus_t phhalHw_Sam_Cmd_SAM_WriteFile	(	phhalHw_Sam_DataParams_t *	pDataParams,
		uint8_t	bOption,
		uint8_t	bFileNo,
		uint16_t	wCRLVer,
		uint8_t *	pOffset,
		uint8_t *	pData,
		uint8_t *	pLength
	)

Performs writing of data.

The location of data to be written is defined by the file number of the targeted file, the offset in the data file where to start the writing and its size in bytes. The file number specifying the file where to write to is given by FileNo encoded in P1.
The position byte-wise in the data file where to start to write data is given by Offset. Its valid range is from 0x000000 to FileSize - 1. The data size to be written is given by Length specifying the number of bytes.
If the number of bytes to send does not fit into one single APDU response, chaining is applied internally.

Returns: Status code

Return values

PH_ERR_SUCCESS	Operation successful.
PH_ERR_INVALID_DATA_PARAMS	pDataParams is NULL.
PH_ERR_INVALID_PARAMETER	pOffset, pLength and pData are NULL.
Other	Depending on implementation and underlaying component.

Parameters

[in]	pDataParams	[In] Pointer to this layer's parameter structure.
[in]	bOption	[In] Option to exchange CRL Version, One of the following, Do Not Exchange CRL Version Exchange CRL Version
[in]	bFileNo	[In] File number of the file to be read. Bit[7] : Secondary Application Indicator Bit[4-0]: File Number
[in]	wCRLVer	[In] CRLVersion is a 16-bit value encoding the current version of the CRLFile. Valid if targeting CRL File.
[in]	pOffset	[In] The offset from where the data should be written. Will be of 3 bytes. with LSB first. If 0x10 need to be offset, then it will be 10 00 00. 0 to (FileSize - 1): Starting position of Write operation
[in]	pData	[In] The data to be written to the PICC. Complete Data to be provided if not targeting CRL File Complete Data including CRLSignature should be provided if targeting CRF File.
[in]	pLength	[In] The number of bytes to be written. Will be of 3 bytes with LSB first. If 0x10 bytes need to be written, then it will be 10 00 00.

Note

If not targeting CRF File, the length will be as mentioned above.
If targeting CRL file, then the length will be Length of Data + Length of CRL Signature In this case if Data Length is 10 bytes and CRL Signature Length is 64 bytes, then pLength will be (10 + 40) 00 00 => 50 00 00

◆ phhalHw_Sam_Cmd_SAM_WriteFileOffline()

phStatus_t phhalHw_Sam_Cmd_SAM_WriteFileOffline	(	phhalHw_Sam_DataParams_t *	pDataParams,
		uint8_t	bFileNo,
		uint16_t	wChangeCtr,
		uint8_t *	pOfflineCrypto,
		uint32_t	dwOfflineCryptoLen,
		uint8_t	bEnableOfflineAck,
		uint8_t **	ppOfflineAck,
		uint16_t *	pOfflineAckLen
	)

Performs writing of data offline.

User should complete the Offline cryptogram and provide the computed information to this interface.
If the number of bytes to send does not fit into one single APDU response, chaining is applied internally.

Returns: Status code

Return values

PH_ERR_SUCCESS	Operation successful.
PH_ERR_INVALID_DATA_PARAMS	pDataParams is NULL.
PH_ERR_INVALID_PARAMETER	pOffset, pLength and pData are NULL.
Other	Depending on implementation and underlaying component.

Parameters

[in]	pDataParams	[In] Pointer to this layer's parameter structure.
[in]	bFileNo	[In] File number of the file to be read. Bit[7] : Secondary Application Indicator Bit[4-0]: File Number
[in]	wChangeCtr	[In] Change Counter to avoid replay attacks.
[in]	pOfflineCrypto	[In] Offline Cryptogram exchanged to SAM (EncKeyEntry + OfflineMAC) Encrypted Write File data (Kce, WriteFileData [\|\| SAMUID]) where WriteFileData is the command data field parameters, i.e. CRLVersion until CRLSignature (if applicable) in plain. Integrity MAC protection as MACt (Kcm, CLA \|\| INS \|\| P1 \|\| P2 \|\| LC \|\| Change_Ctr \|\| E(Kce, WriteFileData [\|\| SAMUID]))
[in]	dwOfflineCryptoLen	[In] Length of bytes available in pOfflineCrypto buffer
[in]	bEnableOfflineAck	[In] To Enable reception of Offline Acknowledge Disable reception of Offline ACK (LE will not be exchanged) Enable reception of Offline ACK (LE will be exchanged)
[out]	ppOfflineAck	[Out] Offline Acknowledge information received from SAM. Will be based on If bEnableOfflineAck = Disable reception of Offline ACK, buffer will contain NULL. If bEnableOfflineAck = Enable reception of Offline ACK, buffer will contain Offline change acknowledge as MACt (Kcm, 0x90 \|\| 0x00 \|\| INS \|\| Change_Ctr \|\| FileNo \|\| SAMUID).
[out]	pOfflineAckLen	[Out] Length of bytes available in ppOfflineAck buffer

◆ phhalHw_Sam_Cmd_SAM_GetFileSettings()

phStatus_t phhalHw_Sam_Cmd_SAM_GetFileSettings	(	phhalHw_Sam_DataParams_t *	pDataParams,
		uint8_t	bFileNo,
		uint8_t **	ppResponse,
		uint16_t *	pRespLen
	)

Performs reading the meta-data of a file.

FileType, Access Rights and File Size of the targeted file encoded in P1 will be returned.
Additionally, if a CRLFile is targeted the CRLOptions, CSNSize and, if applicable, CSNSigKey will be returned.
If P1 is set to 0xFE, will return the remaining fee user memory that is available for file creation.
If P1 is set to 0xFF, a list of the already created file identifiers will be returned.

Returns: Status code

Return values

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

Parameters

[in]	pDataParams	[In] Pointer to this layer's parameter structure.
[in]	bFileNo	[In] File number of the file to be read. 00 - 0F: User File F0 : Originality Certificate File FE : Free Memory FF : List of file IDs
[out]	ppResponse	[Out] The settings of the File returned by SAM.
[out]	pRespLen	[Out] Length of bytes available in ppResponse buffer.

◆ phhalHw_Sam_Cmd_SAM_Format()

phStatus_t phhalHw_Sam_Cmd_SAM_Format ( phhalHw_Sam_DataParams_t * pDataParams )

Performs deletion of all files.

After successful execution the full user memory for files is again available for file creation.

Returns: Status code

Return values

PH_ERR_SUCCESS	Operation successful.
PH_ERR_INVALID_DATA_PARAMS	pDataParams is NULL.
Other	Depending on implementation and underlaying component.

Parameters

[in] pDataParams [In] Pointer to this layer's parameter structure.

Modules

Functions

Detailed Description

Function Documentation

◆ phhalHw_Sam_Cmd_SAM_CreateFile()

◆ phhalHw_Sam_Cmd_SAM_ReadFile()

◆ phhalHw_Sam_Cmd_SAM_WriteFile()

◆ phhalHw_Sam_Cmd_SAM_WriteFileOffline()

◆ phhalHw_Sam_Cmd_SAM_GetFileSettings()

◆ phhalHw_Sam_Cmd_SAM_Format()