.TH "teesl" 3teegris "Sun Oct 28 2018" "Version 2.0" "Samsung Internal API reference" \" -*- nroff -*-
.ad l
.nh
.SH NAME
teesl \- Samsung Internal API
.SS "Modules"

.in +1c
.ti -1c
.RI "\fBLoadable driver API\fP"
.br
.ti -1c
.RI "\fBCustom handler API\fP"
.br
.ti -1c
.RI "\fBContiguous memory API\fP"
.br
.ti -1c
.RI "\fBSPI API\fP"
.br
.ti -1c
.RI "\fBI2C API\fP"
.br
.ti -1c
.RI "\fBTrusted user interface\fP"
.br
.ti -1c
.RI "\fBIntegrity Report System API\fP"
.br
.ti -1c
.RI "\fBMiscellaneous extensions\fP"
.br
.ti -1c
.RI "\fBRPMB API\fP"
.br
.in -1c
.SS "Data Structures"

.in +1c
.ti -1c
.RI "struct \fBrot_t\fP"
.br
.RI "\fIStructure to handle Root of Trust information\&. \fP"
.ti -1c
.RI "struct \fBwrapped_wkth_rek_t\fP"
.br
.RI "\fIStructure for wrapping with REK\&. \fP"
.in -1c
.SS "Macros"

.in +1c
.ti -1c
.RI "#define \fBSO_TAG_LEN\fP   (16)"
.br
.ti -1c
.RI "#define \fBSO_IV_LEN\fP   (16)"
.br
.ti -1c
.RI "#define \fBSO_AC_LEN\fP   (4)"
.br
.ti -1c
.RI "#define \fBSO_MAGIC_NUMBER_LEN\fP   (4)"
.br
.ti -1c
.RI "#define \fBSO_TA_ID_LEN\fP   (16)"
.br
.ti -1c
.RI "#define \fBSO_AUTH_ID_LEN\fP   (16)"
.br
.ti -1c
.RI "#define \fBSO_HEADER_SIZE\fP(delegated)"
.br
.ti -1c
.RI "#define \fBSO_OUT_BUF_SIZE\fP(in_len,  delegated)   ((in_len) + (\fBSO_HEADER_SIZE\fP(delegated)))"
.br
.ti -1c
.RI "#define \fBSHA256_DIGEST_LEN\fP   32"
.br
.RI "\fISHA256_DIGEST_LEN is defined to set size for verified_boot_key of ROOT_OF_TRUST\&. \fP"
.ti -1c
.RI "#define \fBKM_KW_MAX_SALT_LEN\fP   60"
.br
.ti -1c
.RI "#define \fBKM_KW_MAX_IV_LEN\fP   12"
.br
.ti -1c
.RI "#define \fBKM_KW_MAX_AAD_LEN\fP   32"
.br
.ti -1c
.RI "#define \fBKM_KW_MAX_KEY_LEN\fP   32"
.br
.ti -1c
.RI "#define \fBKM_KW_MAX_INPUT_LEN\fP   4096"
.br
.ti -1c
.RI "#define \fBKM_KW_MAX_TAG_LEN\fP   16"
.br
.in -1c
.SS "Typedefs"

.in +1c
.ti -1c
.RI "typedef struct \fBrot_t\fP \fBROOT_OF_TRUST\fP"
.br
.RI "\fIStructure to handle Root of Trust information\&. \fP"
.ti -1c
.RI "typedef struct \fBwrapped_wkth_rek_t\fP \fBWRAP_REK\fP"
.br
.RI "\fIStructure for wrapping with REK\&. \fP"
.in -1c
.SS "Enumerations"

.in +1c
.ti -1c
.RI "enum \fBkw_mode\fP { \fBWRAP\fP, \fBUNWRAP\fP }
.RI "\fIWrapping mode\&. WRAP or UNWRAP\&. \fP""
.br
.in -1c
.SS "Functions"

.in +1c
.ti -1c
.RI "TEE_Result \fBerrno_to_tee_error\fP (int error_code)"
.br
.RI "\fITranslate errno to GP TEE errors code\&. \fP"
.ti -1c
.RI "TEE_Result \fBTEES_EnterCritical\fP (void)"
.br
.RI "\fIDisable routing and handling of normal world interrupts\&. \fP"
.ti -1c
.RI "TEE_Result \fBTEES_ExitCritical\fP (void)"
.br
.RI "\fIEnable routing and handling of normal world interrupts\&. \fP"
.ti -1c
.RI "TEE_Result \fBTEES_DeriveKeyKDF\fP (const void *label, uint32_t labelLen, const void *context, uint32_t contextLen, uint32_t outputKeyLen, TEE_ObjectHandle object)"
.br
.RI "\fIKey Derivation Function(KDF) based on device key\&. Internal implementation of KDF depends on the chipset\&. \fP"
.ti -1c
.RI "TEE_Result \fBTEES_DeriveKeySetKDF\fP (const void *label, uint32_t labelLen, const void *context, uint32_t contextLen, uint32_t outputKeyLen, TEE_ObjectHandle object)"
.br
.RI "\fIKey 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\&. \fP"
.ti -1c
.RI "TEE_Result \fBTEES_LockHWCryptoBuf\fP (void)"
.br
.RI "\fILock HW crypto buffer\&. \fP"
.ti -1c
.RI "TEE_Result \fBTEES_UnlockHWCryptoBuf\fP (void)"
.br
.RI "\fIUnock HW crypto buffer\&. \fP"
.ti -1c
.RI "TEE_Result \fBTEES_WrapSecureObject\fP (const unsigned char *in, uint32_t in_len, unsigned char *out, uint32_t *out_len, SO_AccessControlInfoType *ac)"
.br
.RI "\fIEncrypt and sign input data\&. \fP"
.ti -1c
.RI "TEE_Result \fBTEES_UnwrapSecureObject\fP (const unsigned char *in, uint32_t in_len, unsigned char *out, uint32_t *out_len)"
.br
.RI "\fIDecrypt and verify wrapped data\&. \fP"
.ti -1c
.RI "TEE_Result \fBTEES_CheckSecureObjectCreator\fP (const unsigned char *in, uint32_t in_len, SO_AccessControlInfoType *ac)"
.br
.RI "\fICheck UUID and AUTH_ID of creator on wrapped data\&. \fP"
.ti -1c
.RI "TEE_Result \fBTEES_GetRoT\fP (\fBROOT_OF_TRUST\fP *rot)"
.br
.RI "\fIGet RoT information\&. \fP"
.ti -1c
.RI "TEE_Result \fBTEES_WrappedWithREK\fP (\fBWRAP_REK\fP *data)"
.br
.RI "\fIWrapping with REK\&. \fP"
.ti -1c
.RI "TEE_Result \fBTEES_SECCAM_GetStatus\fP (unsigned int *data)"
.br
.RI "\fIGet a status of secure camera\&. \fP"
.in -1c
.SH "Detailed Description"
.PP 

.SH "Data Structure Documentation"
.PP 
.SH "struct rot_t"
.PP 
Structure to handle Root of Trust information\&. 
.PP
\fBData Fields:\fP
.RS 4
uint32_t \fIdevice_locked\fP 
.br
.PP
uint32_t \fIos_version\fP 
.br
.PP
uint32_t \fIpatch_month_year\fP 
.br
.PP
uint64_t \fIreserved[4]\fP 
.br
.PP
uint8_t \fIverified_boot_key[32]\fP 
.br
.PP
uint32_t \fIverified_boot_state\fP 
.br
.PP
.RE
.PP
.SH "struct wrapped_wkth_rek_t"
.PP 
Structure for wrapping with REK\&. 
.PP
\fBData Fields:\fP
.RS 4
uint8_t \fIaad[32]\fP 
.br
.PP
uint32_t \fIaad_len\fP 
.br
.PP
uint8_t \fIauth_tag[16]\fP 
.br
.PP
uint32_t \fIauth_tag_len\fP 
.br
.PP
uint8_t \fIencrypted_key[4096]\fP 
.br
.PP
uint32_t \fIencrypted_key_len\fP 
.br
.PP
uint8_t \fIiv[12]\fP 
.br
.PP
uint32_t \fIiv_len\fP 
.br
.PP
uint32_t \fIkw_mode\fP 
.br
.PP
uint8_t \fIplaintext_key[4096]\fP 
.br
.PP
uint32_t \fIplaintext_key_len\fP 
.br
.PP
uint8_t \fIsalt[60]\fP 
.br
.PP
uint32_t \fIsalt_len\fP 
.br
.PP
.RE
.PP
.SH "Macro Definition Documentation"
.PP 
.SS "#define KM_KW_MAX_AAD_LEN   32"

.PP
\fC#include <\fBtees_wrapped_with_rek\&.h\fP>\fPLength in bytes of maximum Authenticated data for AES-GCM to wrapped with REK\&. 
.SS "#define KM_KW_MAX_INPUT_LEN   4096"

.PP
\fC#include <\fBtees_wrapped_with_rek\&.h\fP>\fPLength in bytes of maximum input data which is wrapped with REK 
.SS "#define KM_KW_MAX_IV_LEN   12"

.PP
\fC#include <\fBtees_wrapped_with_rek\&.h\fP>\fPLength in bytes of maximum Initial Vector field to wrapped with REK\&. 
.SS "#define KM_KW_MAX_KEY_LEN   32"

.PP
\fC#include <\fBtees_wrapped_with_rek\&.h\fP>\fPLength in bytes of maximum key which wraps input data SW mode only 
.SS "#define KM_KW_MAX_SALT_LEN   60"

.PP
\fC#include <\fBtees_wrapped_with_rek\&.h\fP>\fPLength in bytes of maximum Salt field to wrapped with REK\&. 
.SS "#define KM_KW_MAX_TAG_LEN   16"

.PP
\fC#include <\fBtees_wrapped_with_rek\&.h\fP>\fPLength in bytes of maximum Tag field in wrapped with REK 
.SS "#define SO_AC_LEN   (4)"

.PP
\fC#include <\fBtees_secure_object\&.h\fP>\fPLength in bytes of Access Control field in wrapped object\&. 
.SS "#define SO_AUTH_ID_LEN   (16)"

.PP
\fC#include <\fBtees_secure_object\&.h\fP>\fPLength in bytes of Auth ID field in wrapped object\&. Present only in delegation case\&. 
.SS "#define SO_HEADER_SIZE(delegated)"

.PP
\fC#include <\fBtees_secure_object\&.h\fP>\fP\fBValue:\fP
.PP
.nf
((SO_TAG_LEN) + (SO_IV_LEN) + (SO_AC_LEN) + (SO_MAGIC_NUMBER_LEN) + \
    ((delegated) ? (SO_TA_ID_LEN) + (SO_AUTH_ID_LEN) : 0))
.fi
Get the size of the Secure Object's Header\&. 
.SS "#define SO_IV_LEN   (16)"

.PP
\fC#include <\fBtees_secure_object\&.h\fP>\fPLength in bytes of Input Vector field in wrapped object\&. 
.SS "#define SO_MAGIC_NUMBER_LEN   (4)"

.PP
\fC#include <\fBtees_secure_object\&.h\fP>\fPLength in bytes of magic number\&. 
.SS "#define SO_OUT_BUF_SIZE(in_len, delegated)   ((in_len) + (\fBSO_HEADER_SIZE\fP(delegated)))"

.PP
\fC#include <\fBtees_secure_object\&.h\fP>\fPGet the size of output buffer for Secure Object, accounting Header size\&. 
.SS "#define SO_TA_ID_LEN   (16)"

.PP
\fC#include <\fBtees_secure_object\&.h\fP>\fPLength in bytes of TA UUID field in wrapped object\&. Present only in delegation case\&. 
.SS "#define SO_TAG_LEN   (16)"

.PP
\fC#include <\fBtees_secure_object\&.h\fP>\fPLength in bytes of TAG field in wrapped object\&. 
.SH "Function Documentation"
.PP 
.SS "TEE_Result errno_to_tee_error (int error_code)"

.PP
\fC#include <\fBtee_error\&.h\fP>\fP
.PP
Translate errno to GP TEE errors code\&. 
.PP
\fBParameters:\fP
.RS 4
\fIerror_code\fP errno error code\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
TEE errors code\&. 
.RE
.PP

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

.PP
\fC#include <\fBtees_secure_object\&.h\fP>\fP
.PP
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\&.
.PP
\fBParameters:\fP
.RS 4
\fIin\fP Pointer to input buffer\&. 
.br
\fIin_len\fP Length of input buffer\&. 
.br
\fIac\fP Pointer to Access Control struct SO_AccessControlInfoType\&. This is a structure containing access control information\&.
.RE
.PP
\fBReturn values:\fP
.RS 4
\fITEE_SUCCESS\fP successfully checked\&. 
.br
\fITEE_ERROR_XXXX\fP - unsuccessfully checked :
.IP "\(bu" 2
TEE_ERROR_BAD_PARAMETERS - \fCac\fP is NULL or object size less than SO header length;
.IP "\(bu" 2
TEE_ERROR_BAD_FORMAT - SO magic number does not match or Not supported access flag on wrapped data;
.IP "\(bu" 2
TEE_ERROR_SECURITY - TA_ID or AUTH_ID between wrapped data and \fCac\fP does not match\&.
.PP
.RE
.PP
Example: 
.PP
.nf
TEES_CheckSecureObjectCreator((const unsigned char *)key1_str,
                        DATA256K,
                        &ac_info);

.fi
.PP
 
.SS "TEE_Result TEES_DeriveKeyKDF (const void * label, uint32_t labelLen, const void * context, uint32_t contextLen, uint32_t outputKeyLen, TEE_ObjectHandle object)"

.PP
\fC#include <\fBtees_kdf\&.h\fP>\fP
.PP
Key Derivation Function(KDF) based on device key\&. Internal implementation of KDF depends on the chipset\&. 
.PP
\fBParameters:\fP
.RS 4
\fIlabel\fP label (see KDF description at NIST SP 800-108)\&. 
.br
\fIlabelLen\fP label length in bytes\&. 
.br
\fIcontext\fP context (see KDF description at NIST SP 800-108)\&. 
.br
\fIcontextLen\fP context length in bytes\&. 
.br
\fIoutputKeyLen\fP required derived key length in bytes\&. 
.br
\fIobject\fP handle on a cryptographic object of appropriate type and size to hold derived key\&. 
.RE
.PP
\fBReturn values:\fP
.RS 4
\fITEE_SUCCESS\fP in case of success\&. 
.br
\fITEE_ERROR_XXXX\fP in case of failure\&. 
.RE
.PP

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

.PP
\fC#include <\fBtees_kdf\&.h\fP>\fP
.PP
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\&. 
.PP
\fBParameters:\fP
.RS 4
\fIlabel\fP label (see KDF description at NIST SP 800-108)\&. 
.br
\fIlabelLen\fP label length in bytes\&. 
.br
\fIcontext\fP context (see KDF description at NIST SP 800-108)\&. 
.br
\fIcontextLen\fP context length in bytes\&. 
.br
\fIoutputKeyLen\fP required derived key length in bytes\&. 
.br
\fIobject\fP handle on a cryptographic object of appropriate type and size to hold derived key\&. 
.RE
.PP
\fBReturn values:\fP
.RS 4
\fITEE_SUCCESS\fP in case of success\&. 
.br
\fITEE_ERROR_XXXX\fP in case of failure\&. 
.RE
.PP

.SS "TEE_Result TEES_EnterCritical (void)"

.PP
\fC#include <\fBtees_critical\&.h\fP>\fP
.PP
Disable routing and handling of normal world interrupts\&. 
.PP
\fBReturn values:\fP
.RS 4
\fITEE_SUCCESS\fP on success or error otherwise\&.
.RE
.PP
Example: 
.PP
.nf
TEES_EnterCritical();
// Do some short actions
TEES_ExitCritical();

.fi
.PP
 
.SS "TEE_Result TEES_ExitCritical (void)"

.PP
\fC#include <\fBtees_critical\&.h\fP>\fP
.PP
Enable routing and handling of normal world interrupts\&. 
.PP
\fBReturn values:\fP
.RS 4
\fITEE_SUCCESS\fP on success or error otherwise\&.
.RE
.PP
Example: 
.PP
.nf
TEES_EnterCritical();
// Do some short actions
TEES_ExitCritical();

.fi
.PP
 
.SS "TEE_Result TEES_GetRoT (\fBROOT_OF_TRUST\fP * rot)"

.PP
\fC#include <\fBtees_rot\&.h\fP>\fP
.PP
Get RoT information\&. Function will be used to get RoT information from special SMC\&.
.PP
\fBParameters:\fP
.RS 4
\fIrot\fP Pointer to get RoT information 
.RE
.PP
\fBReturn values:\fP
.RS 4
\fITEE_SUCCESS\fP no error\&. 
.br
\fITEE_ERROR_*\fP on failure
.RE
.PP
Example: 
.PP
.nf
TEES_GetRoT(&rot);

.fi
.PP
 
.SS "TEE_Result TEES_LockHWCryptoBuf (void)"

.PP
\fC#include <\fBtees_hwcrypto_buf\&.h\fP>\fP
.PP
Lock HW crypto buffer\&. Lock HW crypto buffer for special driver TA
.PP
\fBReturn values:\fP
.RS 4
\fITEE_SUCCESS\fP on success 
.br
\fITEE_ERROR_*\fP on error
.IP "\(bu" 2
TEE_ERROR_* is based on error number of \fBopen()\fP or \fBioctl()\fP for crypto driver in secure kernel
.PP
.RE
.PP
Example: 
.PP
.nf
…
TEE_Result res = TEES_LockHWCryptoBuf();
if (res ! = TEE_SUCCESS) {
     printf("TEES_LockHWCryptBuf() is failed\&. res = %d\n", res);
     return res;
}
…

.fi
.PP
 
.SS "TEE_Result TEES_SECCAM_GetStatus (unsigned int * data)"

.PP
\fC#include <\fBtees_seccam\&.h\fP>\fP
.PP
Get a status of secure camera\&. This function is used to check whether the camera is operated with normal or secure mode\&.
.PP
\fBParameters:\fP
.RS 4
\fIdata\fP Pointer to data for secure camera 
.RE
.PP
\fBReturn values:\fP
.RS 4
\fITEE_SUCCESS\fP no error\&. 
.br
\fITEE_ERROR_*\fP on failure
.IP "\(bu" 2
TEE_ERROR_GENERIC - Crypto driver or SMC for secure camera is not supported;
.IP "\(bu" 2
TEE_ERROR_COMMUNICATION - Unable to open the crypto driver;
.PP
.RE
.PP
Example: 
.PP
.nf
…
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");
}
…

.fi
.PP
 
.SS "TEE_Result TEES_UnlockHWCryptoBuf (void)"

.PP
\fC#include <\fBtees_hwcrypto_buf\&.h\fP>\fP
.PP
Unock HW crypto buffer\&. Unlock HW crypto buffer for special driver TA
.PP
\fBReturn values:\fP
.RS 4
\fITEE_SUCCESS\fP on success 
.br
\fITEE_ERROR_*\fP on error
.IP "\(bu" 2
TEE_ERROR_* is based on error number of \fBopen()\fP or \fBioctl()\fP for crypto driver in secure kernel
.PP
.RE
.PP
Example: 
.PP
.nf
…
TEE_Result res = TEES_UnlockHWCryptoBuf();
if (res ! = TEE_SUCCESS) {
     printf("TEES_UnlockHWCryptBuf() is failed\&. res = %d\n", res);
     return res;
}
…

.fi
.PP
 
.SS "TEE_Result TEES_UnwrapSecureObject (const unsigned char * in, uint32_t in_len, unsigned char * out, uint32_t * out_len)"

.PP
\fC#include <\fBtees_secure_object\&.h\fP>\fP
.PP
Decrypt and verify wrapped data\&. Function will take a buffer containing wrapped SO and decrypt it to a format understandable by the caller\&.
.PP
\fBParameters:\fP
.RS 4
\fIin\fP Pointer to input buffer\&. 
.br
\fIin_len\fP Length of input buffer\&. 
.br
\fIout\fP Pointer to outdata\&. Can be set to NULL in combination with *out_len = 0 for getting required output buffer size\&. 
.br
\fIout_len\fP Maximum/actual size of out buffer\&.
.RE
.PP
\fBReturn values:\fP
.RS 4
\fITEE_SUCCESS\fP data was successfully unwrapped\&. 
.br
\fITEE_ERROR_XXXX\fP - if unsuccessfully unwrapped\&.
.RE
.PP
Example: 
.PP
.nf
TEES_UnwrapSecureObject((const unsigned char *)key1_str,
                        DATA256K,
                        wrapout,
                        &wrapout_len);

.fi
.PP
 
.SS "TEE_Result TEES_WrappedWithREK (\fBWRAP_REK\fP * data)"

.PP
\fC#include <\fBtees_wrapped_with_rek\&.h\fP>\fP
.PP
Wrapping with REK\&. Function will be used to wrap a data with REK by special SMC\&.
.PP
\fBParameters:\fP
.RS 4
\fIdata\fP Pointer to wrap/unwrap data with REK 
.RE
.PP
\fBReturn values:\fP
.RS 4
\fITEE_SUCCESS\fP no error\&. 
.br
\fITEE_ERROR_*\fP on failure
.RE
.PP
Example: 
.PP
.nf
TEES_WrappedWithREK(&data);

.fi
.PP
 
.SS "TEE_Result TEES_WrapSecureObject (const unsigned char * in, uint32_t in_len, unsigned char * out, uint32_t * out_len, SO_AccessControlInfoType * ac)"

.PP
\fC#include <\fBtees_secure_object\&.h\fP>\fP
.PP
Encrypt and sign input data\&. Function will be used to create an encrypted or wrapped secure object from an unprotected data\&.
.PP
\fBParameters:\fP
.RS 4
\fIin\fP Pointer to input buffer\&. 
.br
\fIin_len\fP Input buffer length\&. 
.br
\fIout\fP Pointer to outdata\&. Can be set to NULL in combination with *out_len = 0 for getting required output buffer size\&. 
.br
\fIout_len\fP Maximum/actual size of out buffer\&. 
.br
\fIac\fP Pointer to Access Control struct SO_AccessControlInfoType\&. This is a structure containing access control information\&.
.RE
.PP
\fBReturn values:\fP
.RS 4
\fITEE_SUCCESS\fP data was successfully wrapped\&. 
.br
\fITEE_ERROR_XXXX\fP error ocurred during wapping\&.
.RE
.PP
Example: 
.PP
.nf
TEES_WrapSecureObject((const unsigned char *)key1_str,
                      DATA256K,
                      wrapout,
                      &wrapout_len,
                      &ac_info);

.fi
.PP
 
.SH "Author"
.PP 
Generated automatically by Doxygen for Samsung Internal API reference from the source code\&.