3.3.6. Policies

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

../../_images/policy-types.png

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

  1. 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.

  2. 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.

See

sss_policy_session_u

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

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

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

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

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

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

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

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

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

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

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

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
sss_policy_userid_u pin
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

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