Samsung Internal API

Modules
	Loadable driver API
	Custom handler API
	Contiguous memory API
	SPI API
	I2C API
	Trusted user interface
	Integrity Report System API
	Miscellaneous extensions
	RPMB API

Data Structures
struct	rot_t
	Structure to handle Root of Trust information. More...
struct	wrapped_wkth_rek_t
	Structure for wrapping with REK. More...

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(delegated)
#define	SO_OUT_BUF_SIZE(in_len, delegated)   ((in_len) + (SO_HEADER_SIZE(delegated)))
#define	SHA256_DIGEST_LEN   32
	SHA256_DIGEST_LEN is defined to set size for verified_boot_key of ROOT_OF_TRUST.
#define	KM_KW_MAX_SALT_LEN   60
#define	KM_KW_MAX_IV_LEN   12
#define	KM_KW_MAX_AAD_LEN   32
#define	KM_KW_MAX_KEY_LEN   32
#define	KM_KW_MAX_INPUT_LEN   4096
#define	KM_KW_MAX_TAG_LEN   16

Typedefs
typedef struct rot_t	ROOT_OF_TRUST
	Structure to handle Root of Trust information.
typedef struct wrapped_wkth_rek_t	WRAP_REK
	Structure for wrapping with REK.

Enumerations
enum	kw_mode { WRAP, UNWRAP }
	Wrapping mode. WRAP or UNWRAP.

Functions
TEE_Result	errno_to_tee_error (int error_code)
	Translate errno to GP TEE errors code. More...
TEE_Result	TEES_EnterCritical (void)
	Disable routing and handling of normal world interrupts. More...
TEE_Result	TEES_ExitCritical (void)
	Enable routing and handling of normal world interrupts. More...
TEE_Result	TEES_DeriveKeyKDF (const void *label, uint32_t labelLen, const void *context, uint32_t contextLen, uint32_t outputKeyLen, TEE_ObjectHandle object)
	Key Derivation Function(KDF) based on device key. Internal implementation of KDF depends on the chipset. More...
TEE_Result	TEES_DeriveKeySetKDF (const void *label, uint32_t labelLen, const void *context, uint32_t contextLen, uint32_t outputKeyLen, TEE_ObjectHandle object)
	Key Derivation Function(KDF) based on device key. This function returns the same kay for the set of TAs of the same authority. Internal implementation of KDF depends on the chipset. More...
TEE_Result	TEES_LockHWCryptoBuf (void)
	Lock HW crypto buffer. More...
TEE_Result	TEES_UnlockHWCryptoBuf (void)
	Unock HW crypto buffer. More...
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...
TEE_Result	TEES_GetRoT (ROOT_OF_TRUST *rot)
	Get RoT information. More...
TEE_Result	TEES_WrappedWithREK (WRAP_REK *data)
	Wrapping with REK. More...
TEE_Result	TEES_SECCAM_GetStatus (unsigned int *data)
	Get a status of secure camera. More...

Detailed Description

---

Data Structure Documentation

struct rot_t

Structure to handle Root of Trust information.

Data Fields
uint32_t	device_locked
uint32_t	os_version
uint32_t	patch_month_year
uint64_t	reserved[4]
uint8_t	verified_boot_key[32]
uint32_t	verified_boot_state

struct wrapped_wkth_rek_t

Structure for wrapping with REK.

Data Fields
uint8_t	aad[32]
uint32_t	aad_len
uint8_t	auth_tag[16]
uint32_t	auth_tag_len
uint8_t	encrypted_key[4096]
uint32_t	encrypted_key_len
uint8_t	iv[12]
uint32_t	iv_len
uint32_t	kw_mode
uint8_t	plaintext_key[4096]
uint32_t	plaintext_key_len
uint8_t	salt[60]
uint32_t	salt_len

Macro Definition Documentation

#define KM_KW_MAX_AAD_LEN   32

#include <tees_wrapped_with_rek.h>

Length in bytes of maximum Authenticated data for AES-GCM to wrapped with REK.

#define KM_KW_MAX_INPUT_LEN   4096

#include <tees_wrapped_with_rek.h>

Length in bytes of maximum input data which is wrapped with REK

#define KM_KW_MAX_IV_LEN   12

#include <tees_wrapped_with_rek.h>

Length in bytes of maximum Initial Vector field to wrapped with REK.

#define KM_KW_MAX_KEY_LEN   32

#include <tees_wrapped_with_rek.h>

Length in bytes of maximum key which wraps input data SW mode only

#define KM_KW_MAX_SALT_LEN   60

#include <tees_wrapped_with_rek.h>

Length in bytes of maximum Salt field to wrapped with REK.

#define KM_KW_MAX_TAG_LEN   16

#include <tees_wrapped_with_rek.h>

Length in bytes of maximum Tag field in wrapped with REK

#define SO_AC_LEN   (4)

#include <tees_secure_object.h>

Length in bytes of Access Control field in wrapped object.

#define SO_AUTH_ID_LEN   (16)

#include <tees_secure_object.h>

Length in bytes of Auth ID field in wrapped object. Present only in delegation case.

#define SO_HEADER_SIZE

(

delegated

)

#include <tees_secure_object.h>

Value:

((SO_TAG_LEN) + (SO_IV_LEN) + (SO_AC_LEN) + (SO_MAGIC_NUMBER_LEN) + \
    ((delegated) ? (SO_TA_ID_LEN) + (SO_AUTH_ID_LEN) : 0))

Get the size of the Secure Object's Header.

#define SO_IV_LEN   (16)

#include <tees_secure_object.h>

Length in bytes of Input Vector field in wrapped object.

#define SO_MAGIC_NUMBER_LEN   (4)

#include <tees_secure_object.h>

Length in bytes of magic number.

#define SO_OUT_BUF_SIZE	(		in_len,
			delegated
	)		((in_len) + (SO_HEADER_SIZE(delegated)))

#include <tees_secure_object.h>

Get the size of output buffer for Secure Object, accounting Header size.

#define SO_TA_ID_LEN   (16)

#include <tees_secure_object.h>

Length in bytes of TA UUID field in wrapped object. Present only in delegation case.

#define SO_TAG_LEN   (16)

#include <tees_secure_object.h>

Length in bytes of TAG field in wrapped object.

Function Documentation

TEE_Result errno_to_tee_error

(

int

error_code

)

#include <tee_error.h>

Translate errno to GP TEE errors code.

Parameters

[in]

error_code

errno error code.

Returns

TEE errors code.

TEE_Result TEES_CheckSecureObjectCreator	(	const unsigned char *	in,
		uint32_t	in_len,
		SO_AccessControlInfoType *	ac
	)

#include <tees_secure_object.h>

Check UUID and AUTH_ID of creator on wrapped data.

Function will take a buffer containing wrapped SO and check UUID and AUTH_ID on it.

Parameters

[in]	in	Pointer to input buffer.
[in]	in_len	Length of input buffer.
[in]	ac	Pointer to Access Control struct SO_AccessControlInfoType. This is a structure containing access control information.

Return values

TEE_SUCCESS	successfully checked.
TEE_ERROR_XXXX	- unsuccessfully checked : TEE_ERROR_BAD_PARAMETERS - ac is NULL or object size less than SO header length; TEE_ERROR_BAD_FORMAT - SO magic number does not match or Not supported access flag on wrapped data; TEE_ERROR_SECURITY - TA_ID or AUTH_ID between wrapped data and ac does not match.

Example:

TEES_CheckSecureObjectCreator((const unsigned char *)key1_str,
                        DATA256K,
                        &ac_info);

TEE_Result TEES_DeriveKeyKDF	(	const void *	label,
		uint32_t	labelLen,
		const void *	context,
		uint32_t	contextLen,
		uint32_t	outputKeyLen,
		TEE_ObjectHandle	object
	)

#include <tees_kdf.h>

Key Derivation Function(KDF) based on device key. Internal implementation of KDF depends on the chipset.

Parameters

[in]	label	label (see KDF description at NIST SP 800-108).
[in]	labelLen	label length in bytes.
[in]	context	context (see KDF description at NIST SP 800-108).
[in]	contextLen	context length in bytes.
[in]	outputKeyLen	required derived key length in bytes.
[out]	object	handle on a cryptographic object of appropriate type and size to hold derived key.

Return values

TEE_SUCCESS	in case of success.
TEE_ERROR_XXXX	in case of failure.

TEE_Result TEES_DeriveKeySetKDF	(	const void *	label,
		uint32_t	labelLen,
		const void *	context,
		uint32_t	contextLen,
		uint32_t	outputKeyLen,
		TEE_ObjectHandle	object
	)

#include <tees_kdf.h>

Key Derivation Function(KDF) based on device key. This function returns the same kay for the set of TAs of the same authority. Internal implementation of KDF depends on the chipset.

Parameters

[in]	label	label (see KDF description at NIST SP 800-108).
[in]	labelLen	label length in bytes.
[in]	context	context (see KDF description at NIST SP 800-108).
[in]	contextLen	context length in bytes.
[in]	outputKeyLen	required derived key length in bytes.
[out]	object	handle on a cryptographic object of appropriate type and size to hold derived key.

Return values

TEE_SUCCESS	in case of success.
TEE_ERROR_XXXX	in case of failure.

TEE_Result TEES_EnterCritical

(

void

)

#include <tees_critical.h>

Disable routing and handling of normal world interrupts.

Return values

TEE_SUCCESS

on success or error otherwise.

Example:

TEES_EnterCritical();
// Do some short actions
TEES_ExitCritical();

TEE_Result TEES_ExitCritical

(

void

)

#include <tees_critical.h>

Enable routing and handling of normal world interrupts.

Return values

TEE_SUCCESS

on success or error otherwise.

Example:

TEES_EnterCritical();
// Do some short actions
TEES_ExitCritical();

TEE_Result TEES_GetRoT

(

ROOT_OF_TRUST *

rot

)

#include <tees_rot.h>

Get RoT information.

Function will be used to get RoT information from special SMC.

Parameters

[in,out]

rot

Pointer to get RoT information

Return values

TEE_SUCCESS	no error.
TEE_ERROR_*	on failure

Example:

TEES_GetRoT(&rot);

TEE_Result TEES_LockHWCryptoBuf

(

void

)

#include <tees_hwcrypto_buf.h>

Lock HW crypto buffer.

Lock HW crypto buffer for special driver TA

Return values

TEE_SUCCESS	on success
TEE_ERROR_*	on error TEE_ERROR_* is based on error number of open() or ioctl() for crypto driver in secure kernel

Example:

…
TEE_Result res = TEES_LockHWCryptoBuf();
if (res ! = TEE_SUCCESS) {
     printf("TEES_LockHWCryptBuf() is failed. res = %d\n", res);
     return res;
}
…

TEE_Result TEES_SECCAM_GetStatus

(

unsigned int *

data

)

#include <tees_seccam.h>

Get a status of secure camera.

This function is used to check whether the camera is operated with normal or secure mode.

Parameters

[out]

data

Pointer to data for secure camera

Return values

TEE_SUCCESS	no error.
TEE_ERROR_*	on failure TEE_ERROR_GENERIC - Crypto driver or SMC for secure camera is not supported; TEE_ERROR_COMMUNICATION - Unable to open the crypto driver;

Example:

…
TEE_Result res = TEE_SUCCESS;
unsigned int data;

res = TEES_SECCAM_GetStatus( &data );
if( res != TEE_SUCCESS ){
    printf("ERROR : TEES_SECCAM_GetStatus = %#x\n", res);
    return res;
}
if( data == 0x00 ){
    printf("Normal mode\n");
}
else if( data == 0x01 ){
    printf("Secure mode\n");
}
else{
    printf("undefined mode\n");
}
…

TEE_Result TEES_UnlockHWCryptoBuf

(

void

)

#include <tees_hwcrypto_buf.h>

Unock HW crypto buffer.

Unlock HW crypto buffer for special driver TA

Return values

TEE_SUCCESS	on success
TEE_ERROR_*	on error TEE_ERROR_* is based on error number of open() or ioctl() for crypto driver in secure kernel

Example:

…
TEE_Result res = TEES_UnlockHWCryptoBuf();
if (res ! = TEE_SUCCESS) {
     printf("TEES_UnlockHWCryptBuf() is failed. res = %d\n", res);
     return res;
}
…

TEE_Result TEES_UnwrapSecureObject	(	const unsigned char *	in,
		uint32_t	in_len,
		unsigned char *	out,
		uint32_t *	out_len
	)

#include <tees_secure_object.h>

Decrypt and verify wrapped data.

Function will take a buffer containing wrapped SO and decrypt it to a format understandable by the caller.

Parameters

[in]	in	Pointer to input buffer.
[in]	in_len	Length of input buffer.
[out]	out	Pointer to outdata. Can be set to NULL in combination with *out_len = 0 for getting required output buffer size.
[in,out]	out_len	Maximum/actual size of out buffer.

Return values

TEE_SUCCESS	data was successfully unwrapped.
TEE_ERROR_XXXX	- if unsuccessfully unwrapped.

Example:

TEES_UnwrapSecureObject((const unsigned char *)key1_str,
                        DATA256K,
                        wrapout,
                        &wrapout_len);

TEE_Result TEES_WrappedWithREK

(

WRAP_REK *

data

)

#include <tees_wrapped_with_rek.h>

Wrapping with REK.

Function will be used to wrap a data with REK by special SMC.

Parameters

[in,out]

data

Pointer to wrap/unwrap data with REK

Return values

TEE_SUCCESS	no error.
TEE_ERROR_*	on failure

Example:

TEES_WrappedWithREK(&data);

TEE_Result TEES_WrapSecureObject	(	const unsigned char *	in,
		uint32_t	in_len,
		unsigned char *	out,
		uint32_t *	out_len,
		SO_AccessControlInfoType *	ac
	)

#include <tees_secure_object.h>

Encrypt and sign input data.

Function will be used to create an encrypted or wrapped secure object from an unprotected data.

Parameters

[in]	in	Pointer to input buffer.
[in]	in_len	Input buffer length.
[out]	out	Pointer to outdata. Can be set to NULL in combination with *out_len = 0 for getting required output buffer size.
[in,out]	out_len	Maximum/actual size of out buffer.
[in]	ac	Pointer to Access Control struct SO_AccessControlInfoType. This is a structure containing access control information.

Return values

TEE_SUCCESS	data was successfully wrapped.
TEE_ERROR_XXXX	error ocurred during wapping.

Example:

TEES_WrapSecureObject((const unsigned char *)key1_str,
                      DATA256K,
                      wrapout,
                      &wrapout_len,
                      &ac_info);