tees_secure_object.h File Reference

Secure Objects API. More...

Go to the source code of this file.

Macros
#define	SO_TAG_LEN   (16)
#define	SO_IV_LEN   (16)
#define	SO_AC_LEN   (4)
#define	SO_MAGIC_NUMBER_LEN   (4)
#define	SO_TA_ID_LEN   (16)
#define	SO_AUTH_ID_LEN   (16)
#define	SO_HEADER_SIZE_STATIC   ((SO_TAG_LEN) + (SO_IV_LEN) + (SO_AC_LEN) + (SO_MAGIC_NUMBER_LEN))
#define	SO_OUT_BUF_SIZE(in_len, delegated)   ((in_len) + SO_HEADER_SIZE_STATIC + ((delegated) ? (SO_TA_ID_LEN + SO_AUTH_ID_LEN) : 0))

Functions
TEE_Result	TEES_WrapSecureObject (const unsigned char *in, uint32_t in_len, unsigned char *out, uint32_t *out_len, SO_AccessControlInfoType *ac)
	Encrypt and sign input data. More...
TEE_Result	TEES_UnwrapSecureObject (const unsigned char *in, uint32_t in_len, unsigned char *out, uint32_t *out_len)
	Decrypt and verify wrapped data. More...
TEE_Result	TEES_CheckSecureObjectCreator (const unsigned char *in, uint32_t in_len, SO_AccessControlInfoType *ac)
	Check UUID and AUTH_ID of creator on wrapped data. More...

Detailed Description

Secure Objects API.

Copyright

(C) 2012-2019, Samsung Electronics Co., Ltd.

Secure Object APIs provide a TEE service for protecting TA sensitive data.

Secure Object is a wrapped and protected data that only authorized access holder can read. Data is protected by encrypting it with a key that only authorized trusted application can retrieve from the TEE. This process is called wrapping.

Secure Object consists of:

1. Encrypted Data
2. 4 byte Access Control
3. 16 Byte Initialization Vector
4. 16 Byte TAG
5. 16 Byte TA UUID of the creator TA (optional)
6. 16 Byte TA Authority of the creator TA (optional)

Structure of wrapped object:

|<-------------------------------------   Header   ----------------------------------->|<-Encrypted|
|                   |<---------- Access Control (4 byte) ----------->|                 |   Data--->|
|       |     |     |          |delegated|delegated| Auth ID| TA UUID|optional|optional| encrypted |
| MAGIC | TAG | IV  | reserved | AUTH ID | TA UUID | AC bit | AC bit | TA UUID|Auth ID |   image   |
|  4b   | 16b | 16b |  28bit   |  1bit   |  1bit   |  1bit  |  1bit  |  16b   |  16b   |image size |

The following data structures are used for implementing Access Control, based on KDF function:

typedef struct {
    uint32_t access_flags;
    UUID ta_id;
    AUTHORITY auth_id;
} SO_AccessControlInfoType;

access_flags - is a bit-mask indicating the access control restrictions.

• if bit-0 (TA_ID_AC) is set => Current TA Id and Authority are used as input to KDF, therefore Secure Object has to be valid only for this TA.
• if bit-1 (AUTH_ID_AC) is set => Current TA Authority is used as input to KDF, therefore Secure Object has to be valid only for the group of TA Authority.
• if bit-2 (DELEGATED_TA_ID_AC) set => auth_id and ta_id and Current TA Id and Current TA Authority are used as input to KDF. auth_id and ta_id are considered as delegated.
• if bit-3 (DELEGATED_AUTH_ID_AC) set => auth_id and Current TA Id and Current TA Authority are used as input to KDF. auth_id is considered as delegated.

UUID - A Universally Unique IDentifier of another Trusted Application with which the Secure Object needs to be shared. User needs to define this only if the Secure Object is to be shared with another TA and TA_ID_AC is set.

AUTHORITY - This is the name of the TA Authority access group with which the SO may be shared. User needs to define this only if Secure Object needs to be shared with another TA Authority and TA access flag AUTH_ID_AC is set.