Platform Security Architecture — cryptography and keystore interface  Working draft
Macros | Typedefs | Functions
Generators

Macros

#define PSA_CRYPTO_GENERATOR_INIT   {0}
 

Typedefs

typedef struct psa_crypto_generator_s psa_crypto_generator_t
 

Functions

psa_status_t psa_get_generator_capacity (const psa_crypto_generator_t *generator, size_t *capacity)
 
psa_status_t psa_generator_read (psa_crypto_generator_t *generator, uint8_t *output, size_t output_length)
 
psa_status_t psa_generator_import_key (psa_key_slot_t key, psa_key_type_t type, size_t bits, psa_crypto_generator_t *generator)
 
psa_status_t psa_generator_abort (psa_crypto_generator_t *generator)
 

Detailed Description

Macro Definition Documentation

◆ PSA_CRYPTO_GENERATOR_INIT

#define PSA_CRYPTO_GENERATOR_INIT   {0}

This macro returns a suitable initializer for a generator object of type psa_crypto_generator_t.

Typedef Documentation

◆ psa_crypto_generator_t

typedef struct psa_crypto_generator_s psa_crypto_generator_t

The type of the state data structure for generators.

Before calling any function on a generator, the application must initialize it by any of the following means:

This is an implementation-defined struct. Applications should not make any assumptions about the content of this structure except as directed by the documentation of a specific implementation.

Function Documentation

◆ psa_generator_abort()

psa_status_t psa_generator_abort ( psa_crypto_generator_t generator)

Abort a generator.

Once a generator has been aborted, its capacity is zero. Aborting a generator frees all associated resources except for the generator structure itself.

This function may be called at any time as long as the generator object has been initialized to PSA_CRYPTO_GENERATOR_INIT, to psa_crypto_generator_init() or a zero value. In particular, it is valid to call psa_generator_abort() twice, or to call psa_generator_abort() on a generator that has not been set up.

Once aborted, the generator object may be called.

Parameters
[in,out]generatorThe generator to abort.
Return values
PSA_SUCCESS
PSA_ERROR_BAD_STATE
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_HARDWARE_FAILURE
PSA_ERROR_TAMPERING_DETECTED

◆ psa_generator_import_key()

psa_status_t psa_generator_import_key ( psa_key_slot_t  key,
psa_key_type_t  type,
size_t  bits,
psa_crypto_generator_t generator 
)

Create a symmetric key from data read from a generator.

This function reads a sequence of bytes from a generator and imports these bytes as a key. The data that is read is discarded from the generator. The generator's capacity is decreased by the number of bytes read.

This function is equivalent to calling psa_generator_read and passing the resulting output to psa_import_key, but if the implementation provides an isolation boundary then the key material is not exposed outside the isolation boundary.

Parameters
keySlot where the key will be stored. This must be a valid slot for a key of the chosen type. It must be unoccupied.
typeKey type (a PSA_KEY_TYPE_XXX value). This must be a symmetric key type.
bitsKey size in bits.
[in,out]generatorThe generator object to read from.
Return values
PSA_SUCCESSSuccess.
PSA_ERROR_INSUFFICIENT_CAPACITYThere were fewer than output_length bytes in the generator. Note that in this case, no output is written to the output buffer. The generator's capacity is set to 0, thus subsequent calls to this function will not succeed, even with a smaller output buffer.
PSA_ERROR_NOT_SUPPORTEDThe key type or key size is not supported, either by the implementation in general or in this particular slot.
PSA_ERROR_BAD_STATE
PSA_ERROR_INVALID_ARGUMENTThe key slot is invalid.
PSA_ERROR_OCCUPIED_SLOTThere is already a key in the specified slot.
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_INSUFFICIENT_STORAGE
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_HARDWARE_FAILURE
PSA_ERROR_TAMPERING_DETECTED

◆ psa_generator_read()

psa_status_t psa_generator_read ( psa_crypto_generator_t generator,
uint8_t *  output,
size_t  output_length 
)

Read some data from a generator.

This function reads and returns a sequence of bytes from a generator. The data that is read is discarded from the generator. The generator's capacity is decreased by the number of bytes read.

Parameters
[in,out]generatorThe generator object to read from.
[out]outputBuffer where the generator output will be written.
output_lengthNumber of bytes to output.
Return values
PSA_SUCCESS
PSA_ERROR_INSUFFICIENT_CAPACITYThere were fewer than output_length bytes in the generator. Note that in this case, no output is written to the output buffer. The generator's capacity is set to 0, thus subsequent calls to this function will not succeed, even with a smaller output buffer.
PSA_ERROR_BAD_STATE
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_HARDWARE_FAILURE
PSA_ERROR_TAMPERING_DETECTED

◆ psa_get_generator_capacity()

psa_status_t psa_get_generator_capacity ( const psa_crypto_generator_t generator,
size_t *  capacity 
)

Retrieve the current capacity of a generator.

The capacity of a generator is the maximum number of bytes that it can return. Reading N bytes from a generator reduces its capacity by N.

Parameters
[in]generatorThe generator to query.
[out]capacityOn success, the capacity of the generator.
Return values
PSA_SUCCESS
PSA_ERROR_BAD_STATE
PSA_ERROR_COMMUNICATION_FAILURE