IIFAA Decentralized Trusted Authentication Technical Specification

Abstract

This document provides technical specifications for the IIFAA decentralized authentication device security and device-cloud security. It applies to R&D design, deployment, testing, and certification activities related to IIFAA decentralized authentication.

The device security architecture is shown in Figure 1. The device security system is used to build system-level identity asset management services, involving the roles of participants such as TEE manufacturers and OEMs. The device security logic layers include a basic dependency layer, a basic adaptation layer, a DID protocol layer, a functional service layer, etc.

Placeholder for Device Security Architecture — Figure 1 : Device Security Architecture

The wallet application side uses the DID-related capabilities within the device security framework by invoking instructions. The data interaction protocol is as follows:

Example 1

IIFAA_Result IIFAA_DID_InvokeCmd(uint8_t *buf_in, size_t in_len, uint8_t *buf_out, size_t *out_len);

Where,

buf_in is the input buffer, and in_len is the length of the input buffer;
buf_out is the output buffer, out_len is the length pointer of the output buffer.

The form of input buffer is as follows:

command(4 bytes)  params_len(4 bytes)  params_buf

The form of output buffer is as follows:

result_code(4 bytes)  response_len(4 bytes)  response_buf

Among them, the params and response parts use TLV as the basic protocol format. The buffer form of TLV is as follows:

TAG_VALUE  BUFFER_LEN  BUFFER

The meaning of each corresponding field is shown in Table 1:

Table 1: Field Description
Field	Type	Length	Description
TAG_VALUE	uint16_t	2 bytes	A tag indicating the type of node. It specifies that the TAG_VALUE of the leaf node is ≥ 128. The remaining values are non-leaf nodes.
BUFFER_LEN	uint16_t	2 bytes	Payload length of the TLV node.
BUFFER	unsigned char*	Length specified by BUFFER_LEN	Payload of the TLV node. If it is a leaf node, the buffer is the actual load. Otherwise, it is the sum of the loads of each child node.

Note

Note: The data in the TLV node is stored in big-endian mode.

The structure of request message is shown in Figure 2. When the client initiates a DID-related operation that requires IDP authorization, it needs to obtain the corresponding request instruction from the IDP Server. These instructions need to be signed by the IDP key. In the signature, the corresponding certificate applied for using the secondary/tertiary IDP should be placed in the CERT_CHAIN within the request command, allowing the client to perform certificate chain validation. The root certificate of the certificate chain will be embedded in the TA.

Placeholder for Request Message Structure — Figure 2 : Request Message Structure

Table 2: Definition and Description of TAG Values
Field	Value	Description
IDP_REQUEST	0x01	Root node
CERT_ALG_ENCODE	0x6001	Certificate chain encoding format
CERT_CHAIN	0x6002	Certificate chain
SIGN_ALG	0x6003	Signature algorithm, default to one supported by IIFAA TA
SIGNATURE	0x6004	Signature, uniformly call the IIFAA TA interface for cross-TA signature
REQ_PARAMS	0x07	Detailed parameters, non-leaf nodes

The structure of response message is shown in Figure 3. The response result returned by the client needs to be signed with a device certificate/device key to ensure that the result is credible. To sign the IIFAA device key/device certificate chain, the response result needs to place the device certificate in CERT_CHAIN to facilitate the verification of the certificate chain by the server.

Placeholder for Response Message Structure — Figure 3 : Response Message Structure

Table 3: Definition and Description of TAG Values
Field	Value	Description
IDP_RESPONSE	0x02	Root node
CERT_ALG_ENCODE	0x6001	Certificate chain encoding format
CERT_CHAIN	0x6002	Certificate chain
SIGN_ALG	0x6003	Signature algorithm
SIGNATURE	0x6004	Signature
RESP_DATA	0x08	Detailed result data, non-leaf nodes

Based on the specific IDP function instructions, REQ_PARAMS and RESP_DATA need to be further defined and described in accordance with the IDP basic message. The specific instructions involved are shown in Table 4:

Table 4: IDP Function Interface Message
Instruction Name	Instruction ID	Meaning
IIFAA_CMD_DID_GEN_VM	0x01000001	Generate VM: generate VerifyMethod (identity key, etc.)
IIFAA_CMD_DID_IMPORT_DOC	0x01000002	Import DID: import identity documents and establish key alias VMID mapping
IIFAA_CMD_DID_AUTH_Z	0x01000003	Authorize DID: DID identity authorization signature (DID authorization)
IIFAA_CMD_DID_QUERY_LOCAL	0x01000004	Query DID: query local DID identity
IIFAA_CMD_DID_DEREG	0x01000005	Cancel DID: delete local identity documents and related credential data

Functional summary: Generate a key pair based on ASYM_KEY_ALGORITHM, store the private key in SFS, and use the public key as the file name. After DID authorization, according to KEY_TYPE & Security Level, the VM ID is matched, and a new file named with the VMID is generated to replace the original file for storing private keys.

Request message: Based on the IDP request message, add an identity key algorithm (ASYM_ALG) to the request parameter (REQ_PARAMS), with the structure shown in Figure 4.

Placeholder for Request Message Structure (Gen Key) — Figure 4 : Request Message Structure

Table 5: Definition and Description of TAG Values under REQ_PARAMS
Field	Value	Description
CHALLENGE	0x6005	Challenge, used to prevent replay
SECURE_LEVEL	0x600a	Minimum security level required, see the security levels part in 5.3 for details
ASYM_KEY_ALGORITHM	0x6007	Identity key type

Response message: Based on the IDP response message, add the locally constructed VM content (VM_CONTENT) in the return result (RESP_DATA), with the structure as shown below:

Placeholder for Response Message Structure (Gen Key) — Figure 5 : Request Message Structure

Table 6: Definition and Description of TAG Values under RESP_DATA
Field	Value	Description
PUBLIC_KEY	0x601b	Public key (raw encoding is used by default)
KEY_ALG	0x6007	Public key type, see the public key type part in "Certificate Chain" for details
SECURE_LEVEL	0x600a	Actual key security level, see the security levels part in 5.3 for details
CHALLENGE	0x6005	Challenge, used to prevent replay

The raw encoding format of public key is shown as below:

Example 2

public key of RSA2048/RSA3072: { n_len + n + e_len + e }
+-------------------------------------------------------------+
| n_len |    N                 | e_len |   E             |
+-------------------------------------------------------------+
|4 byte |   n_len byte         | 4 byte |  e len byte     |
+-------------------------------------------------------------+

public key of ECC_p256/SM2: { 0x04 + x + y }
+-------------------------------------------------------------+
| 0x04 |     X                  |    Y                    |
+-------------------------------------------------------------+
|1 byte|     32 byte              |    32 byte                |
+-------------------------------------------------------------+

Functional summary: Get DID_DOCUMENT in the input and store it persistently. The file is named as DID ID.

Request message: Based on the IDP request message, add a DID identity document (DID_DOCUMENT) in the request parameter (REQ_PARAMS), with the structure shown in Figure 6.

Placeholder for Request Message Structure (Import) — Figure 6 : Request Message Structure

Table 7: Definition and Description of TAG Values under REQ_PARAMS
Field	Value	Description
DID_ABSTRACT_INFO	0x6009	DID document summary information (DID identifier, vm_id, and corresponding public key)

Example 3

{
  "did": "",
  "verificationMethods": [
    {
      "id": "123",
      "pubkey": "sfdf"
    },
    {
      "id": "123",
      "pubkey": "sfdf"
    },
    {
      "id": "123",
      "pubkey": "sfdf"
    }
  ]
}

Response message: It is the response content after the DID is successfully imported. It does not need to be encapsulated based on IDP_RESPONSE, and the corresponding DID identifier can be directly returned. An example of a DID identifier is as follows:

Example 4

did:iifaa:2UdYuZagBsinmdRogHNJwPc8QXA4PyXdYXcY1aDaB8wR

Functional summary: Get the data AUTH_DATA to be authorized in the input, sign it using the signature algorithm corresponding to VMID, and return the signature through the SIGNATURE field in IDP_RESPONSE.

Request message: Based on the IDP request message, add the key type (KEY_TYPE), security level (SECURE_LEVEL), and data to be authorized (AUTH_DATA) required for authorization in the request parameter (REQ_PARAMS), with the structure shown in Figure 7.

Placeholder for Request Message Structure (Auth) — Figure 7 : Request Message Structure

Table 8: Definition and Description of TAG Values under REQ_PARAMS
Field	Value	Description
CHALLENGE	0x6005	Challenge, used to prevent replay
KEY_TYPE	0x6006	Public key type, see the public key type section in 11.2.1 "Certificate Chain" for details
SECURE_LEVEL	0x600a	Security level, see T/IIFAA 4002-2025 6.6 "Security Level" for details
AUTH_DATA	0x600b	Data to be authorized (≤ 32 byte)

Response message: Based on the IDP response message, place the data to be signed {challenge + auth_data + vm_id} in respData, use the private key corresponding to vmID to sign resp_data, and place the signing result in [SIGNATURE], with the structure shown in Figure 8.

Placeholder for Response Message Structure (Auth) — Figure 8 : Response Message Structure

Request message: Based on the IDP request message, add a DID identifier (optional) to be queried in the request parameter (REQ_PARAMS), with the structure shown in Figure 9.

Placeholder for Request Message Structure (Query) — Figure 9 : Response Message Structure

Table 9: Definition and Description of TAG Values under REQ_PARAMS
Field	Value	Description
DID_IDENTIFIER	0x600c	DID identifier (optional. If it is empty, all local DID identifiers will be returned, and if it is not empty, the corresponding DID document content will be returned)

Response message: The structure of response message is shown in Figure 10. Based on the IDP response message, the specific return result is put into resp_data:

If a DID identifier is passed in as the input parameter, put the corresponding DID_Document into resp_data;
If no DID identifier is passed in as the input parameter, put the local DID identifier set (DID_IDENTIFIER_LIST) into resp_data.

Placeholder for Response Message Structure (Query) — Figure 10 : Response Message Structure

Table 10: Definition and Description of TAG Values under RESP_DATA
Field	Value	Description
DID_DOCUMENT	0x6009	DID document. For the specific format, please refer to the "DID Document" section in Identity Protocol
DID_IDENTIFIER_LIST	0x600d	DID identifier. If there are multiple ones, separate them with "#".

Note

Note: DID_DOCUMENT and DID_IDENTIFIER_LIST will not be returned at the same time.

Functional summary: Generate a dId + vmid Json string, sign the Json string, then delete the List node, and delete the records in the local file. For the original text of JSON, refer to:

Example 5

{
  "did": "did:iifaa:6VP29YtNfqjdkF3KPJ8Mr46EtNHKMK9zJv8xTj33pmCy",
  "vmId": "04"
}

Request message: Based on the IDP request message, add a challenge, DID to be cancelled, authorized VM type, and VM security level in the request parameter (REQ_PARAMS), with the specific structure shown in Figure 11.

Placeholder for Request Message Structure (Cancel) — Figure 11 : Request Message Structure

Response message: Based on the IDP response message, put the canceled DID identifier, challenge, and authorized VM_ID into resp_data, find the unique VM through input parameters KEY_TYPE + SECURITY_LEVEL, sign the following resp_data as a whole with the corresponding private key, and put the signature result in [SIGNATURE], with the specific structure shown in Figure 12.

Placeholder for Response Message Structure (Cancel) — Figure 12 : Response Message Structure

When the client initiates credential import and other related operations that require ISSUER/IDP authorization, it needs to obtain the corresponding request instruction from the ISSUER/IDP Server. These instructions need to be signed by the ISSUER/IDP certificate key. The ISSUER/IDP certificate is placed in CERT_CHAIN, allowing the client to perform certificate chain validation. The root certificate of the certificate chain will be embedded in the TA. The structure is shown in Figure 13.

Placeholder for Credential Request Message Structure — Figure 13 : Request Message Structure

Table 11: Definition and Description of TAG Values
Field	Value	Description
ISSUER_REQUEST	0x03	Root node
CERT_ALG_ENCODE	0x6001	Certificate chain encoding format
CERT_CHAIN	0x6002	Certificate chain
SIGN_ALG	0x6003	Signature algorithm, default to one supported by IIFAA TA
SIGNATURE	0x6004	Signature, uniformly call the IIFAA TA interface for cross-TA signature
REQ_PARAMS	0x07	Detailed parameters, non-leaf nodes

The response result returned by the client needs to be signed with a device certificate/device key to ensure that the result is credible. To sign the IIFAA device key/device certificate chain, the response result needs to place the device certificate in CERT_CHAIN to facilitate the verification of the certificate chain by the server. The structure is shown in Figure 14.

Placeholder for Credential Response Message Structure — Figure 14 : Response Message Structure

Table 12: Definition and Description of TAG Values
Field	Value	Description
IDP_RESPONSE	0x04	Root node
CERT_ALG_ENCODE	0x6001	Certificate chain encoding format
CERT_CHAIN	0x6002	Certificate chain
SIGN_ALG	0x6003	Signature algorithm
SIGNATURE	0x6004	Signature
RESP_DATA	0x08	Detailed result data, non-leaf nodes

Based on the specific function instructions, REQ_PARAMS and RESP_DATA need to be further defined and described in accordance with the basic message. The specific instructions involving VC/VP are shown in Table 13:

Table 13: Instructions Involving VC/VP
Instruction Name	Instruction ID	Meaning
IIFAA_CMD_CREDENTIAL_IMPORT_VC	0x02000002	Import VCs
IIFAA_CMD_CREDENTIAL_QUERY_VC	0x02000003	Query local VCs
IIFAA_CMD_CREDENTIAL_DISCLOSER_VP	0x02000004	Issue of VPs

Functional description: Import the verifiable certificate (VC) issued by ISSUER for the current DID, encrypt the VC content with the user identity key, and sign the entire message with the ISSUER key.

Request message: Based on the ISSUER request message, add the DID identifier and VC-encrypted envelope data in the request parameter (REQ_PARAMS), with the structure shown in Figure 15.

Placeholder for VC Import Request Message Structure — Figure 15 : Response Message Structure

Table 14: Definition and Description of TAG Values under REQ_PARAMS
Field	Value	Description
DID_IDENTIFIER	0x600C	DID associated with the current VC
ENVELOP_ENCODE	0x600E	Envelope coding type, see the envelope coding part in 11.2.3 "Envelope Encryption Protocol" for details
ENVELOP_ENC_ALG	0x6010	Envelope encryption algorithm, see the algorithm type part in 11.2.3 "Envelope Encryption Protocol" for details
VM_ID	0x600D	DID VM identification (i.e. keyAlias) used for encryption
KEY_CIPHER	0x6011	Symmetric key data encrypted by the user's DID public key
DATA_CIPHER	0x6012	VC data ciphertext encrypted by the symmetric key

Response message: Return IIFAA_Result.IFAA_ERR_SUCCESS if the import is successful, and return the corresponding error code if it fails.

Querying VC may expose the user's sensitive data, for which sufficient access control and query instruction replay restrictions are required. The overall query logic flow chart is shown in Figure 16.

Placeholder for Querying/Deleting VCs Process — Figure 16 : Process of Querying/Deleting VCs

Functional description: Pass in the DID, get the challenge of the trusted device corresponding to the DID, and store {challenge + current timestamp} persistently on the trusted device.

Request message: Request the parameter to pass in a DID, with a data sample as follows:

Example 6

did:iifaa:2UdYuZagBsinmdRogHNJwPc8QXA4PyXdYXcY1aDaB8wR

Response message: Return the challenge of the trusted device, with a data sample as follows:

Example 7

AKHFSJKHSJKAFHDJKHFDJKHJKSJA

Functional description: After IDP authorization, query the VC information stored in the device. If VC_ID is not specified, all VC summary information is returned. If VC_ID is specified, the corresponding VC original text is returned.

Request message: Based on the IDP request message, add data such as DID identifier, device challenge, and VC_ID (optional) in the request parameter (REQ_PARAMS), with the structure shown in Figure 17.

Placeholder for VC Query Request Message Structure — Figure 17 : Request Message Structure

Table 15: Definition and Description of TAG Values under REQ_PARAMS
Field	Value	Description
DID_IDENTIFIER	0x600C	DID to be queried
TERMINEL_CHALLENGE	0x6016	Device challenge
VC_ID	0x6013	VC ID to be queried (optional)

Response message: Based on the IDP response message, place the query results in respData. If VC_ID is passed in, the original text of the corresponding VC document is returned. If VC_ID is not passed in, a collection of all VC summary information under the current DID is returned. The structure is shown in Figure 18.

Placeholder for VC Query Response Message Structure — Figure 18 : Response Message Structure

Table 16: Definition and Description of TAG Values under RESP_DATA
Field	Value	Description
VC_DOCUMENT	0x6014	Original text of VC document (only returned when VC_ID is passed in)
VC_BASIC_INFO_LIST	0x6015	VC summary information set (returned when VC_ID is not passed in)

Functional description: After IDP authorization, delete the VC information stored in the device, specify the VC_ID, and then return the corresponding VC summary information.

Request message: Based on the IDP request message, add data such as DID identifier, device challenge, and VC_ID in the request parameter (REQ_PARAMS), with the structure shown in Figure 19.

Placeholder for VC Delete Request Message Structure — Figure 19 : Request Message Structure

Table 17: Definition and Description of TAG Values under REQ_PARAMS
Field	Value	Description
DID_IDENTIFIER	0x600C	DID to be queried
TERMINEL_CHALLENGE	0x6016	Device challenge
VC_ID	0x6013	VC identification to be deleted

Response message: If the deletion is successful, return the summary information of the deleted VC.

Functional description: The user issues a verifiable presentation (VP) that meets the requirements for a specific service provider. The VP content is encrypted using the service provider's identity public key, and the overall message needs to be signed with an institutional identity key. The specific logic is shown in Figure 20.

Placeholder for Presenting VC Functional Description — Figure 20 : Functional Description of Presenting VC (Issuing VP)

Request message: Based on the request message, add the VM type (VM_TYPE) and identity key algorithm (ASYM_ALG) in the request parameter (REQ_PARAMS), with the structure shown in Figure 21.

Placeholder for VP Request Message Structure — Figure 21 : Request Message Structure

Table 18: Definition and Description of TAG Values under REQ_PARAMS
Field	Value	Description
DID_IDENTIFIER	0x600C	DID to be presented
CHALLENGE	0x6005	Challenge, used to prevent replay
VM_TYPE	0x6006	VM Type
SECURE_LEVEL	0x600a	VM security level, see T/IIFAA 4002-2025 6.3 "Security Level" for details
SP_CONFIG	0x6017	SP scenario configuration, to be signed by OPS
USER_SELECTED_ITEMS	0x6018	The data set selected by the user to be presented within the SP scenario configuration range

Response message: Based on the SP response message, place the VP result in respData, with the structure shown in Figure 22.

Placeholder for VP Response Message Structure — Figure 22 : Response Message Structure

Table 19: Definition and Description of TAG Values under RESP_DATA
Field	Value	Description
ENVELOP_ENCODE	0x600E	Envelope coding type, see the envelope coding part in 11.2.3 "Envelope Encryption Protocol" for details
ENVELOP_ENC_ALG	0x6010	Envelope encryption algorithm, see the algorithm type part in 11.2.3 "Envelope Encryption Protocol" for details
VM_ID	0x600D	DID VM identification (i.e. keyAlias) used for encryption
KEY_CIPHER	0x6011	Symmetric key data encrypted by the SP DID public key
DATA_CIPHER	0x6012	VP data ciphertext encrypted by the symmetric key

The specific requirements are as follows:

Persistent storage of DID documents: Store DID documents with DID as the index;
Persistent storage of DID identity keys: Store user identity keys with DID.VMID as the index;
Persistent storage of VCs: Store VCs with VC.ID as the index (TEE to store plaintext, REE to store ciphertext);
Persistent storage of VP presentation records: Store with {DID identifier}_vp_history as the index (TEE to store plaintext, REE to store ciphertext).

The following cryptographic algorithms in Table 20 shall be supported:

Table 20: Cryptographic Algorithms
Algorithm Type	Generation	Encryption	Endorsement	Decryption	Signature Verification	Hash
RSA(2048/3072)	Supported	Supported	Supported	Supported	Supported	-
ECC(secp256r1)	Supported	Supported	Supported	Supported	Supported	-
AES(128/192/256)	Supported	Supported	-	Supported	-	-
SM2	Supported	Supported	Supported	Supported	Supported	-
SM4	Supported	Supported	-	Supported	-	-
SM3/MD5/SHA2	-	-	-	-	-	Supported
Random	Supported	-	-	-	-	-

The specific requirements are as follows:

Trusted UI: For scenarios such as DID identity authorization, users are required to display the authorized DID identity, and a secure and reliable DID authorization page can be provided through TUI.
Trusted geographic location: For some special identity/service credential applications, it is necessary to provide trusted geographic location information for relevant risk prevention and control.
Security camera: Based on the security camera, it can provide more reliable zero-knowledge face recognition capabilities for DID identity authorization.
IIFAA local password-free (fingerprint/face): It provides authorization for the use of identity keys based on fingerprint or face authentication.

The device-cloud security system mainly describes the device-cloud link security mechanism. It involves different participants, including TEE manufacturers and identity service providers.

In a decentralized authentication system, the identity of an institution usually consists of seven roles, including identity service provider, credential issuer, and credential verifier. An institution can assume multiple identity roles at the same time. The specific definitions of institutional roles are shown in Table 21:

Table 21: Definition of Institutional Identity Role
Institution Type	Functional Orientation	Set of Executable Instructions	Remark
CISP	Core Infrastructure Service Platform	Provide core basic services	Institutional certificate revocation
OPS	Operation Service	Provide operation services such as institution entry, scenario configuration, and credential template management	Not interacting directly with the device
WP	Wallet Provider	Provide DID identity wallet services (including business plug-ins and wallet programs)	DID creation, DID import, DID authorization, DID query, VC import, VC query, and VC deletion
ORG IDP	Organization Identity Service Provider	Provide DID identity management services for authoritative institutions	DID creation, DID import, DID cancellation
BIZ IDP	Business Identity Service Provider	Provide DID identity management services for ordinary institutions and users	DID creation, DID import, DID cancellation
ISSUER	Credential Issuer	Provide credential issuance services	VC import
VERIFYER	Credential Verifier (SP)	Provide various business services based on user credentials	VP presentation

To build a trusted device-cloud interaction system, each institution needs to apply for an identity certificate corresponding to its role. The trust root of the certificate is CISP. Institutions with high trust levels can issue certificates for those at the corresponding sub-levels. The specific trust relationship is shown in Figure 23.

Placeholder for Trust Relationship — Figure 23 : Trust Relationship

IIFAA uses a custom certificate format (minimalist): CERT_ENCODE_ALG_IFAA. The certificate structure is of a maximum length of four levels: CISP -> ORG_IDP -> WP/BIZ_IDP/OSP -> SP/ISSUER, where the CISP root certificate is preset on the device, and the longest certificate chain contains three layers of certificate data. The specific certificate chain is shown in Table 22.

Table 22: Certificate Chain
Field Name	CERT_SIZE	CERT_DATA_1	CERT_DATA_2	CERT_DATA_3
Meaning	Certificate level	Level 1 certificate body	Level 2 certificate body	Level 3 certificate body
Length	2 byte	-	-	-

The structure is as follows:

+-------------+-------------+-------------+------------+
| cert_size   | cert data 1 | cert data 2 | cert data 3|
+---2 byte----+-----TLV-----+-----TLV-----+----TLV-----+
+
+-----+--------------+-------------+
|                   |            |
+-----+----+           +----+-----+ +-----+----+
| cert body|         | sign alg | | signature|
+-----+----+             +----------+ +----------+
|
+-------------+---+--------+-----------+------------+
|            |           |          |           |
+----+-----+ +-----+----+ +-----+----+ +----+-----+ +----+-----+
| cert sn  | | org did  | | role type| | pub key  | | key alg  |
+----------+ +----------+ +----------+ +----------+ +----------+

The structure of certificate body is shown in Figure 24.

Placeholder for Certificate Body Structure — Figure 24 : Structure of Certificate Body

Table 23: Definition and Description of Fields
Field	TAG Value	Description
CERT_DATA	0x09	Certificate data
CERT_BODY	0x0a	Certificate body (signed data)
CERT_SN	0x6019	Certificate serial number, a 4-byte unsigned integer used to determine the revocation status, etc.
ORG_DID	0x600c	Institutional DID, optional, not dependent on the DID trusted device side
ROLE_TYPE	0x601a	Identity type of certificate holder
PUBLIC_KEY	0x601b	Public key (raw encoding is used by default)
ASYM_KEY_ALGORITHM	0x6007	Public key type
SIGNATURE	0x6004	Signature
SIGN_ALG	0x6003	Signature algorithm

The raw encoding format of public key is shown as below:

Example 8

public key of RSA2048/RSA3072: { n_len + n + e_len + e }
+-------------------------------------------------------------+
| n_len |    N                 | e_len |   E             |
+-------------------------------------------------------------+
|4 byte |   n_len byte         | 4 byte |  e len byte     |
+-------------------------------------------------------------+

public key of ECC_p256/SM2: { 0x04 + x + y }
+-------------------------------------------------------------+
| 0x04 |     X                  |    Y                    |
+-------------------------------------------------------------+
|1 byte|     32 byte              |    32 byte                |
+-------------------------------------------------------------+

The institutional identity consists of two bytes of data. The bit value identifies whether it has the corresponding role identity authority. Starting from the low bit, it represents such identities as verifyer, issuer, biz_idp, org_idp, ops, and cisp in turn, and bits 8 to 16 are reserved for extension. Examples of institution identity values are shown in Table 24:

Table 24: Example of Institution Identity Value
Bit	1	2	3	4	5	6	7	8~16	Example
Identity Role	VERIFYER	ISSUER	BIZ_IDP	ORG_IDP	WP	OPS	CISP	Reserved
VERIFYER	1	0	0	0	0	0	0	0	1
ISSUER	0	1	0	0	0	0	0	0	2
VERIFYER+ISSUER	1	1	0	0	0	0	0	0	3
ISSUER+BIZ_IDP	0	1	1	0	0	0	0	0	6
BIZ_IDP+WP+OPS	0	0	1	0	1	1	0	0	52
VERIFYER+ISSUER+ BIZ_IDP+WP+OPS	1	1	1	0	1	1	0	0	55
ISSUER+BIZ_IDP+ ORG_IDP+WP+OPS	0	0	1	1	1	1	0	0	60
ORG_DIP+OPS+CISP	0	0	0	1	0	1	1	0	105

User public and private keys generated during registration, where the private key is encrypted and stored by the client. To upload the public key to the server, the types of public and private keys shall be specified. The following key types will be reserved:

Example 9

typedef enum {
    ASYM_KEY_RSA2048 = 1 << 0, // RSA2048 private key
    ASYM_KEY_ECDSA256 = 1 << 1, // ECC256 private key
    ASYM_KEY_SM2 = 1 << 2,     // national encryption algorithm
    ASYM_KEY_RSA3072 = 1 << 3, // RSA3072 private key
    // more here
} IIFAA_AsymmetricKeyType;

Default encoding format (raw):

Example 10

ECC_p256/SM2: { 0x04 + x + y }
+-------------------------------------------------------------+
| 0x04 | X | Y |
+-------------------------------------------------------------+
|1 byte| 32 byte | 32 byte |
+-------------------------------------------------------------+

RSA2048/RSA3072: { n_len + n + e_len + e }
+-------------------------------------------------------------+
| n_len | N | e_len | E |
+-------------------------------------------------------------+
|4 byte | n_len byte | 4 byte | e len byte |
+-------------------------------------------------------------+

The signature algorithm standardizes the signature verification rules for identity confirmation between IFAA Client and IFAA Server. Currently, IFAA reserves the following types of signature algorithms:

Example 11

typedef enum {
    SIGN_ALG_ECDSA_SHA256_RAW = 0x01,  // Raw data of ECDSA+SHA256
    SIGN_ALG_ECDSA_SHA256_DER,  // ECDSA+SHA256 signature in der format
    SIGN_ALG_RSA_SHA256_RAW,  // Raw data of RSA+SHA256
    SIGN_ALG_RSA_SHA256_DER,  // Signature of RSA+SHA256 in DER format
    SIGN_ALG_SM2_SM3_RAW,  // Raw data of SM2+SM3
    SIGN_ALG_SM2_SM3_DER,  // Signature of SM2+SM3 in der format
    SIGN_ALG_SHA256_PKCS7,  // Certificate chain signature in PKCS7 format
    // more here ...
} IIFAA_SignAlgorithm;

During the system initialization phase, each participant needs to complete the registration application for digital certificates according to role classification. Specifically, different roles such as IDP (identity provider), VERIFIER (credential verifier), ISSUER (credential issuer), and operation management organization must apply to the certificate authority center for the institutional identity certificate corresponding to their functions. Each digital certificate shall contain elements such as ID, type, public key, and signature. The specific specifications are shown in Table 25.

Table 25: Definition of Instruction Permission Field
Instruction Name	CMD_ID	Institutional Identity	Supported Algorithms	Remark
Query Version Information	0x00000001	-	-	No signature required
DID creation	0x01000001	WP, BIZ_IDP	RSA, ECC, SM2
Import DID	0x01000002	WP, BIZ_IDP	RSA, ECC, SM2
DID Authorization	0x01000003	VERIFYER	RSA, ECC, SM2
Query DID	0x01000004	WP	RSA, ECC, SM2
Delete DID	0x01000005	WP	RSA, ECC, SM2
VC import	0x02000001	ISSUER	RSA, ECC, SM2
Delete VC	0x02000004	WP	RSA, ECC, SM2
Issuing VP	0x02000003	VERIFYER	RSA, ECC, SM2	Instructions do not need to be signed; SPConfig is signed by OPS, and the result data is encrypted with the VERIFYER public key
Get Device Challenge	0x00000002	-	-	No signature required
Update Certificate Revocation List	0x00000003	CISP

After the instruction is executed, the device key or DID identity key shall be selected according to the instruction type to implement the digital signature, with details shown in Table 26.

Table 26: Definition of Signature Key Type Field
Instruction	Signature Data	Key Type	Supported Algorithms
DID creation	DID identity key and relevant information generated by the device: public key, security level...	Device key	RSA (IIFAA device key), ECC (Huawei certificate chain)
DID Authorization	Information such as business data to be authorized	Specified DID identity key	RSA, ECC, SM2
Delete DID	Cancel result data	Specified DID identity key	RSA, ECC, SM2
Issuing VP	VP data	Specified DID identity key	RSA, ECC, SM2

To ensure the security and trustworthiness of the data transmission process of the device-cloud bidirectional link, a bidirectional signature mechanism is introduced to enhance data tampering resistance and improve the ability to prevent illegal applications from accessing critical infrastructure. The overall process sequence diagram is shown in Figure 25.

Placeholder for Overall Process Sequence Diagram — Figure 25 : Overall Process Sequence Diagram

Through the envelope encryption scheme, dynamic data encryption of the device-cloud bidirectional link is realized to ensure the transmission confidentiality of core business data and improve the link security level. The specific application scenarios are shown in Table 31.

Table 31: Description of Specific Application Scenarios
Instruction	Encrypted Data	Key Type	Supported Algorithms
VC import	VC plaintext data	Specified user DID key	RSA, ECC, SM2
Issuing VP	VP plaintext data	DID identity key of VERIFYER institution	RSA, ECC, SM2

Envelope coding is to format and serialize the encrypted information according to certain rules so that it can be correctly parsed and processed in different devices, systems, or network environments. The specific format is as follows:

Example 12

typedef enum {
    ENVELOP_ENCODE_IIFAA = 1 << 0, // IIFAA custom format
    ENVELOP_ENCODE_PKCS7 = 1 << 1, // PKCS7 envelope format
    // more here...
} ENVELOP_ENCODE_TYPE;

The algorithms supported by the IIFAA custom format include RSA envelope encryption (RSA_AES128_ECB_PKCS5) and SM2_SM4_CBC_PKCS5 (national encryption).

RSA_AES128_ECB_PKCS5

The original data is encrypted using the AES algorithm with a 128-bit key in electronic code book mode (ECB) with PKCS#5 padding. In this process, the symmetric key used for encryption is encrypted with the RSA key. An example of TLV data is shown in Figure 26.

Placeholder for RSA Envelope TLV Data — Figure 26 : Overall Process Sequence Diagram

SM2_SM4_CBC_PKCS5:

Data encryption is to encrypt the original data using the SM4 algorithm in ciphertext block chaining mode (CBC) with PKCS#5 padding. The CBC mode requires an initialization vector (IV) as the input to encrypt the first block. In this process, when symmetric keys are encrypted, the SM4 key and the initialization vector (IV) are encrypted with the SM2 key. The symmetric key and IV are assembled as follows: the ciphertext format of the SM4 key and IV is {Key (16 bytes) + IV (16 bytes)}.

JSON data sample:

Example 13

{
  "algorithm": "SM2_SM4_CBC_PKCS5",
  "keyAlias": "did:iifaa:5o42zmY48hPczeSMfCyjQCupaVnfx1zZJmDciYHvmQGX#key-1",
  "cipher": "Data ciphertext",
  "keyCipher": "SM4 key and IV ciphertext Enc{Key (16 bytes) + IV (16 bytes)}"
}

An example of TLV data is shown in Figure 27.

Placeholder for SM2 Envelope TLV Data — Figure 27 : Overall Process Sequence Diagram

To ensure the data security of the end-cloud bidirectional link and effectively prevent middlemen from caching legitimate instructions or device results, thereby avoiding the threat of replay attacks to business services or DID trusted devices, a bidirectional challenge scheme is introduced. The process sequence diagram is shown in Figure 28.

Placeholder for Bidirectional Challenge Process — Figure 28 : Process Sequence Diagram of Bidirectional Challenge Solution

This chapter specifies the specific security requirements and test verification methods according to Chapter 8 "Safety Requirements" of T/IIFAA 4001-2025 and 10.2 "Operating Environment Safety Test".

Cryptographic algorithms and their applications are described in 8.1 of T/IIFAA 4001-2025. Specific applications shall be based on the specific application scenarios of decentralized authentication, comply with the provisions of relevant laws and regulations, and meet the requirements of relevant national management agencies and relevant national standards and industry standards. This document does not specify specific requirements and verification methods for password application security.

Protocol data security refers to the data security at the DID protocol layer and its underlying data transmission layer. The requirements are as follows:

The data of the DID protocol layer shall be transmitted in an encrypted manner. Attackers other than ISSUER, SP, and user clients cannot obtain the plaintext information of VC and VP.
The DID protocol layer link shall ensure data integrity and prevent data tampering.
The DID protocol layer link shall be bidirectionally authenticated to ensure that both ends of the data transmission are authenticated to prevent illegal access and data leakage.
The data transmission layer shall adopt a secure communication protocol, such as TLS/TLCP, to ensure the security of data transmission.
According to the security requirements of the application scenario, when the DID protocol layer link (such as the link from the client to the SP that presents VP) needs to prevent replay attacks, it shall have the ability to prevent replay attacks.
The VP shall be presented legally. The client that presents the VP must be the client to which the VC is issued. Unauthorized use of VP shall be prevented.

The test method is as follows:

Check whether the fields containing VC and VP (i.e., DATA_CIPHER and KEY_CIPHER) in the data message are encrypted ciphertexts. If so, it meets the requirements; otherwise, it does not meet the requirements.
For any link in the DID protocol layer, the data message must originate from a legitimate sender and remain untampered with. Check whether the receiver accepts the tampered message. If not, it meets the requirements; otherwise, it does not meet the requirements.
For any link in the DID protocol layer, including device-cloud and cloud-cloud links, certificate chain verification and signature verification shall be performed at both ends of the link. Check whether each data link type is signed and verified. If it is signed and verified, it meets the requirements; otherwise, it does not meet the requirements.
Check the protocol of the data transmission layer. If a secure communication protocol is used for interaction and the communication data is encrypted and protected for integrity, it meets the requirements; otherwise, it does not meet the requirements.
When it is necessary to prevent replay attacks, use data messages for the 2nd transmission, i.e. replay, and check whether the receiver accepts the replayed data. If the receiver does not accept the replayed data, it meets the requirements; otherwise, it does not meet the requirements.
On an unauthorized client, present a valid VP that has not been used. If it cannot pass the verification, it meets the requirements; otherwise, it does not meet the requirements.

The security requirements are as follows:

Application security: Applications related to decentralized authentication installed on server devices shall avoid installing unaudited applications, and shall be the latest to ensure the security of the application.
Password and authentication: Password and authentication settings shall be performed for server devices to ensure that only authorized personnel can access the device.
Antivirus software and malware: Antivirus and malware scanners shall be installed and run regularly to ensure that the device is protected from viruses and malware.
The server shall authenticate all requests to ensure that the request comes from a legitimate authorized user or client.
The server shall be able to handle abnormal data messages to avoid server attacks and service interruptions.
The server shall record all access logs and abnormal logs for tracking and analysis.
The server shall establish an emergency response mechanism to deal with security events and threats in a timely manner.

The test verification method is as follows:

Check the version of the application. If it is the latest version, it meets the requirements; otherwise, it does not meet the requirements.
Log in to the system as an unauthorized person. If you cannot access the system, it meets the requirements; otherwise, it does not meet the requirements.
Check whether the system has been installed with antivirus and malware scanners. If so, it meets the requirements; otherwise, it does not meet the requirements.
Initiate a request to the server with an illegal or unauthorized user identity or client software. If the server does not respond to the request, it meets the requirements; otherwise, it does not meet the requirements.
When a large number of abnormal messages are used to attack the server (security testing tools can be used), if the server can maintain uninterrupted service, it meets the requirements; otherwise, it does not meet the requirements.
Check whether the system has access logs and abnormal log records. If so, it meets the requirements; otherwise, it does not meet the requirements.
Check whether the service provider has an emergency response mechanism. If so, it meets the requirements; otherwise, it does not meet the requirements.

The security requirements are as follows:

Data shall be stored securely. The stored data of the device shall be encrypted to ensure that the data will not be accessed and used by unauthorized persons or malware.
Safe update shall be available. It shall be ensured that the operating system and application programs of devices will not be tampered with or replaced by malware during updates, and the update itself is safe.
Trusted identity authentication shall be available to ensure that the user identity authentication on the device is credible, and only authorized users can access the device and data.

The test verification method is as follows:

Check whether the DID key and VC data can be stored safely.
1. Check whether the DID key is stored in a secure environment as stated in the DID document. When the DID document states SE storage, if the DID key is generated and used in the device SE or SIM card security area, it meets the requirements. When the DID document states TEE storage, if the DID key is generated and used in the device TEE, it meets the requirements.
2. Check whether the VC is encrypted and stored. If the VC is encrypted by a cryptographic mechanism and unauthorized persons or malware cannot access the VC plaintext, it meets the requirements.
Check the update process of the operating system and application programs. If there is file source verification and file integrity verification during the update process, it meets the requirements.
Check whether the device has an identity authentication mechanism, including but not limited to password authentication and biometric authentication. If unauthorized users cannot access the relevant data of DID, it meets the requirements.

IIFAA Decentralized Trusted Authentication Technical Specification — Part 3: Security Architecture

Abstract

Status of This Document

1. Scope

2. Normative References

3. Terms and Definitions

4. Abbreviations

5. Device Security

5.1 Device Security Architecture

5.2 Interface

5.3 Identity Management Service

5.3.1 IDP Basic Message

5.3.1.1 Request message

5.3.1.2 Response message

5.3.2 IDP Function Interface Message

5.3.2.1 Definition and description of interface message

5.3.2.2 Initializing DID — generating DID key

5.3.2.3 Initializing DID (importing DID document)

5.3.2.4 DID authorization

5.3.2.5 Querying DID

5.3.2.6 Cancelling DID

5.4 Credential Management Service

5.4.1 Basic Message

5.4.1.1 Request message

5.4.1.2 Response message

5.4.2 Function Interface Message

5.4.2.1 Import VCs

5.4.2.2 Querying/Deleting VCs

Getting trusted device challenge

Querying VCs

Deleting VCs

5.4.2.3 Presenting VC (issuing VP)

5.5 Device Basic Dependencies

5.5.1 Secure Storage

5.5.2 Cryptographic Capabilities

5.5.3 Trusted Hardware

6. Device-Cloud Security

6.1 Overview

6.2 Definition of Institutional Identity

6.2.1 Definition of Institutional Identity Role

6.2.2 Definition of Institutional Identity Certificate

6.2.2.1 Trust relationship

6.2.2.2 Structure and definition of certificate chain

6.2.2.3 Structure and definition of certificate body

Institution type

Public key type

Signature algorithm

6.3 Instruction-Level Access Authentication

6.3.1 Instruction Permission Requirements

6.3.2 Requirements for Signature Key Type

6.4 Device-Cloud Bidirectional Trust

6.4.1 Overall Process Sequence Diagram

6.4.2 Envelope Encryption

6.4.2.1 Specific application scenarios

6.4.2.2 Envelope coding

6.4.2.3 Algorithm type

6.4.3 Bidirectional Challenge Solution

7. Security Requirements and Test Verification Methods

7.1 Overview

7.2 Password Application Security

7.3 Protocol Data Security

7.3.1 Security Requirements

7.3.2 Test Verification Method

7.4 Server Security

7.4.1 Security Requirements

7.4.2 Test Verification Method

7.5 Device Security

7.5.1 Security Requirements

7.5.2 Test Verification Method