3.3.6. Policies¶
Policies can be used to restrict & control the usage of session or objects.

3.3.6.1. Policies applicable to different objects¶
Object Type |
Applet 3.x |
Applet 6.x |
Applet 7.x |
---|---|---|---|
common |
forbid_All, can_Delete, req_Sm, req_pcr_val |
forbid_All, can_Delete, req_Sm, req_pcr_val |
forbid_All, can_Delete, req_Sm, req_pcr_val, can_Read, can_Write |
symmetric objects |
can_Sign, can_Verify, can_Encrypt, can_Decrypt, can_Import_Export, can_Wrap, can_Desfire_Auth, can_Desfire_Dump, can_KD, can_Write, can_Gen |
can_Sign, can_Verify, can_Encrypt, can_Decrypt, can_Import_Export, forbid_Derived_Output, allow_kdf_ext_rnd, can_Wrap, can_Desfire_Auth, can_Desfire_Dump, can_KD, can_Write, can_Gen |
can_Sign, can_Verify, can_Encrypt, can_Decrypt, can_Import_Export, forbid_Derived_Output, can_TLS_KDF, allow_kdf_ext_rnd, can_TLS_PMS_KD, can_HKDF, can_PBKDF, can_Wrap, can_Desfire_Auth, can_Desfire_Dump, can_Desfire_KD, forbid_external_iv, can_usage_hmac_pepper |
Asymmetric objects |
can_Sign, can_Verify, can_Encrypt, can_Decrypt, can_Import_Export, can_Gen, can_KA, can_Attest, can_Read, can_Write, can_KD, can_Wrap |
can_Sign, can_Verify, can_Encrypt, can_Decrypt, can_Import_Export, forbid_Derived_Output, can_Gen, can_KA, can_Attest, can_Read, can_Write, can_KD, can_Wrap |
can_Sign, can_Verify, can_Encrypt, can_Decrypt, can_Import_Export, forbid_Derived_Output, can_Gen, can_KA, can_Attest, |
User Id |
can_Write |
can_Write |
can_Write |
File policy |
can_Read, can_Write |
can_Read, can_Write |
can_Read, can_Write |
Counter policy |
can_Read, can_Write |
can_Read, can_Write |
can_Read, can_Write |
PCR policy |
can_Read, can_Write |
can_Read, can_Write |
can_Read, can_Write |
Note
can_Read and can_Write polices are moved from symmetric and asymmetric object policy to common policy in applet 7.x. PLEASE UPDATE THE APPLICATIONS ACCORDINGLY.
Invalid policies on objects will be rejected at SSS software layer and only result in warning message.
3.3.6.2. Usage¶
Policy can be declared like below:
/* Policies for key */
const sss_policy_u key_withPol = {
.type = KPolicy_Asym_Key,
/*Authentication object based on SE05X_AUTH*/
.auth_obj_id = EX_LOCAL_OBJ_AUTH_ID,
.policy = {
/*Asymmetric key policy*/
.asymmkey = {
/*Policy for sign*/
.can_Sign = allow_sign,
/*Policy for verify*/
.can_Verify = allow_verify,
/*Policy for encrypt*/
.can_Encrypt = 1,
/*Policy for decrypt*/
.can_Decrypt = 1,
/*Policy for Key Derivation*/
.can_KD = 1,
/*Policy for wrapped object*/
.can_Wrap = 1,
/*Policy to re-write object*/
.can_Write = 1,
/*Policy for reading object*/
.can_Read = 1,
/*Policy to use object for attestation*/
.can_Attest = 1,
}
}
};
/* Common rules */
const sss_policy_u common = {
.type = KPolicy_Common,
/*Authentication object based on SE05X_AUTH*/
.auth_obj_id = EX_LOCAL_OBJ_AUTH_ID,
.policy = {
.common = {
/*Secure Messaging*/
.req_Sm = 0,
/*Policy to Delete object*/
.can_Delete = 1,
/*Forbid all operations on object*/
.forbid_All = 0,
}
}
};
/* create policy set */
sss_policy_t policy_for_ec_key = {
.nPolicies = 2,
.policies = { &key_withPol, &common }
};
To create an object with that policy, usage is as below:
status = sss_key_store_generate_key(
&pCtx->ks,
&object,
ECC_KEY_BIT_LEN,
&policy_for_ec_key);
Note
When creating a policy with KPolicy_Common_PCR_Value, KPolicy_Desfire_Changekey_Auth_Id and KPolicy_Derive_Master_Key_Id, set the policies to sss_policy_t variable in the following order always,
`Common_PCR_Value` , `Desfire_Changekey_Auth_Id` , `Derive_Master_Key_Id`
Example,
const sss_policy_u pcr_val_policy = {
.type = KPolicy_Common_PCR_Value, .auth_obj_id = 0,
.policy = { .common_pcr_value = {} } };
const sss_policy_u desfire_change_key_auth_id_policy = {
.type = KPolicy_Desfire_Changekey_Auth_Id, .auth_obj_id = 0,
.policy = { .desfire_auth_id = {} } };
const sss_policy_u master_key_id_policy = {
.type = KPolicy_Derive_Master_Key_Id, .auth_obj_id = 0,
.policy = { .master_key_id = {} } };
// create policy as,
sss_policy_t key_policy = { .nPolicies = 3,.policies = { &pcr_val_policy, &desfire_change_key_auth_id_policy, &master_key_id_policy } };
// OR
sss_policy_t key_policy = { .nPolicies = 1,.policies = { &desfire_change_key_auth_id_policy } };
// OR
sss_policy_t key_policy = { .nPolicies = 2,.policies = { &pcr_val_policy, &master_key_id_policy } };
3.3.6.3. APIs¶
-
group
sss_policy
Policies to restrict and control sessions and objects.
Enums
-
enum
sss_policy_type_u
Type of policy
Values:
-
KPolicy_None
No policy applied
-
KPolicy_Session
Policy related to session.
-
KPolicy_Sym_Key
Policy related to key.
- See
sss_policy_key_u
-
KPolicy_Asym_Key
-
KPolicy_UserID
-
KPolicy_File
-
KPolicy_Counter
-
KPolicy_PCR
-
KPolicy_Common
-
KPolicy_Common_PCR_Value
-
KPolicy_Desfire_Changekey_Auth_Id
-
KPolicy_Derive_Master_Key_Id
-
-
struct
sss_policy_asym_key_u
- #include <fsl_sss_policy.h>
Policies applicable to Asymmetric KEY
Public Members
-
uint8_t
can_Attest
Allow to attest an object
-
uint8_t
can_Decrypt
Allow decryption
-
uint8_t
can_Encrypt
Allow encryption
-
uint8_t
can_Gen
Allow to (re)generate the object
-
uint8_t
can_Import_Export
Allow to imported or exported
-
uint8_t
can_KA
Allow key agreement
-
uint8_t
can_KD
Allow key derivation
-
uint8_t
can_Read
Allow to read the object
-
uint8_t
can_Sign
Allow signature generation
-
uint8_t
can_Verify
Allow signature verification
-
uint8_t
can_Wrap
Allow key wrapping
-
uint8_t
can_Write
Allow to write the object
-
uint8_t
forbid_Derived_Output
Forbid derived output
-
uint8_t
-
struct
sss_policy_common_pcr_value_u
- #include <fsl_sss_policy.h>
Common PCR Value Policies for all object types
Public Members
-
uint8_t
pcrExpectedValue
[32] Expected value of the PCR
-
uint32_t
pcrObjId
PCR object ID
-
uint8_t
-
struct
sss_policy_common_u
- #include <fsl_sss_policy.h>
Common Policies for all object types
Public Members
-
uint8_t
can_Delete
Allow to delete the object
-
uint8_t
can_Read
Allow to read the object
-
uint8_t
can_Write
Allow to write the object
-
uint8_t
forbid_All
Forbid all operations
-
uint8_t
req_pcr_val
Require PCR value
-
uint8_t
req_Sm
Require having secure messaging enabled with encryption and integrity on the command
-
uint8_t
-
struct
sss_policy_counter_u
- #include <fsl_sss_policy.h>
All policies related to secure object type Counter
Public Members
-
uint8_t
can_Read
Allow to read the object
-
uint8_t
can_Write
Allow to write the object
-
uint8_t
-
struct
sss_policy_desfire_changekey_authId_value_u
- #include <fsl_sss_policy.h>
DESFire ChangeKey - authentication key identifier.
Public Members
-
uint32_t
desfire_authId
DESFire authentication object ID
-
uint32_t
-
struct
sss_policy_file_u
- #include <fsl_sss_policy.h>
All policies related to secure object type File
Public Members
-
uint8_t
can_Read
Allow to read the object
-
uint8_t
can_Write
Allow to write the object
-
uint8_t
-
struct
sss_policy_key_drv_master_keyid_value_u
- #include <fsl_sss_policy.h>
Key Derive - Master key identifier.
Public Members
-
uint32_t
master_keyId
Master key ID
-
uint32_t
-
struct
sss_policy_pcr_u
- #include <fsl_sss_policy.h>
All policies related to secure object type PCR
Public Members
-
uint8_t
can_Read
Allow to read the object
-
uint8_t
can_Write
Allow to write the object
-
uint8_t
-
struct
sss_policy_session_u
- #include <fsl_sss_policy.h>
Policy applicable to a session
Public Members
-
uint8_t
allowRefresh
Whether this session can be refreshed without losing context. And also reset maxDurationOfSession_sec / maxOperationsInSession
-
uint8_t
has_MaxDurationOfSession_sec
Whether maxOperationsInSession is set. This is to ensure ‘0 == maxDurationOfSession_sec’ does not get set by middleware.
-
uint8_t
has_MaxOperationsInSession
Whether maxOperationsInSession is set. This is to ensure ‘0 == maxOperationsInSession’ does not get set by middleware.
-
uint16_t
maxDurationOfSession_sec
Session can be used for this much time, in seconds
-
uint16_t
maxOperationsInSession
Number of operations permitted in a session
-
uint8_t
-
struct
sss_policy_sym_key_u
- #include <fsl_sss_policy.h>
Policies applicable to Symmetric KEY
Public Members
-
uint8_t
allow_kdf_ext_rnd
Allow kdf(prf) external random
-
uint8_t
can_Decrypt
Allow decryption
-
uint8_t
can_Desfire_Auth
Allow to perform DESFire authentication
-
uint8_t
can_Desfire_Dump
Allow to dump DESFire session keys
-
uint8_t
can_Desfire_KD
Allow Desfire key derivation
-
uint8_t
can_Encrypt
Allow encryption
-
uint8_t
can_Gen
Allow to (re)generate the object
-
uint8_t
can_HKDF
Allow HKDF
-
uint8_t
can_Import_Export
Allow to imported or exported
-
uint8_t
can_KD
Allow key derivation
-
uint8_t
can_PBKDF
Allow PBKDF
-
uint8_t
can_Sign
Allow signature generation
-
uint8_t
can_TLS_KDF
Allow TLS PRF key derivation
-
uint8_t
can_TLS_PMS_KD
Allow TLS PMS key derivation
-
uint8_t
can_usage_hmac_pepper
Allow usage as hmac pepper
-
uint8_t
can_Verify
Allow signature verification
-
uint8_t
can_Wrap
Allow key wrapping
-
uint8_t
can_Write
Allow to write the object
-
uint8_t
forbid_Derived_Output
Forbid derived output
-
uint8_t
forbid_external_iv
Forbid External iv
-
uint8_t
-
struct
sss_policy_t
- #include <fsl_sss_policy.h>
An array of policies sss_policy_u
Public Members
-
size_t
nPolicies
Number of policies
-
const sss_policy_u *
policies
[(10)] Array of unique policies, this needs to be allocated based nPolicies
-
size_t
-
struct
sss_policy_u
- #include <fsl_sss_policy.h>
Unique/individual policy. For any operation, you need array of sss_policy_u.
Public Members
-
sss_policy_asym_key_u
asymmkey
-
uint32_t
auth_obj_id
Auth ID for each Object Policy, invalid for session policy type == KPolicy_Session
-
sss_policy_common_u
common
-
sss_policy_common_pcr_value_u
common_pcr_value
-
sss_policy_counter_u
counter
-
sss_policy_desfire_changekey_authId_value_u
desfire_auth_id
-
sss_policy_file_u
file
-
sss_policy_key_drv_master_keyid_value_u
master_key_id
-
sss_policy_pcr_u
pcr
-
union sss_policy_u::[anonymous]
policy
Union of applicable policies based on the type of object
-
sss_policy_session_u
session
-
sss_policy_sym_key_u
symmkey
-
sss_policy_type_u
type
Secure Object Type
-
sss_policy_asym_key_u
-
struct
sss_policy_userid_u
- #include <fsl_sss_policy.h>
All policies related to secure object type UserID
Public Members
-
uint8_t
can_Write
Allow to write the object
-
uint8_t
-
enum