| Samsung Internal API reference 2.0

- Main Page
- Related Pages
- Modules
- Data Structures
- Files

- File List
- Globals

Macros | Functions
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.