Platform Security Architecture — cryptography and keystore interface  beta 2 — 2019-02-22
Macros | Typedefs | Functions
Generators

Macros

#define PSA_CRYPTO_GENERATOR_INIT   {0}
 
#define PSA_GENERATOR_UNBRIDLED_CAPACITY   ((size_t)(-1))
 

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_set_generator_capacity (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_handle_t handle, 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

#define PSA_CRYPTO_GENERATOR_INIT   {0}

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

#define PSA_GENERATOR_UNBRIDLED_CAPACITY   ((size_t)(-1))

Use the maximum possible capacity for a generator.

Use this value as the capacity argument when setting up a generator to indicate that the generator should have the maximum possible capacity. The value of the maximum possible capacity depends on the generator algorithm.

Typedef Documentation

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:

  • Set the structure to all-bits-zero, for example:
    1 psa_crypto_generator_t generator;
    2 memset(&generator, 0, sizeof(generator));
  • Initialize the structure to logical zero values, for example:
    1 psa_crypto_generator_t generator = {0};
  • Initialize the structure to the initializer PSA_CRYPTO_GENERATOR_INIT, for example:
    1 psa_crypto_generator_t generator = PSA_CRYPTO_GENERATOR_INIT;
  • Assign the result of the function psa_crypto_generator_init() to the structure, for example:
    1 psa_crypto_generator_t generator;
    2 generator = psa_crypto_generator_init();

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_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_status_t psa_generator_import_key ( psa_key_handle_t  handle,
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
handleHandle to the slot where the key will be stored. It must have been obtained by calling psa_allocate_key() or psa_create_key() and must not contain key material yet.
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. If the key is persistent, the key material and the key's metadata have been saved to persistent storage.
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_HANDLE
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_ERROR_BAD_STATEThe library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.
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_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
psa_status_t psa_set_generator_capacity ( psa_crypto_generator_t generator,
size_t  capacity 
)

Set the maximum capacity of a generator.

Parameters
[in,out]generatorThe generator object to modify.
capacityThe new capacity of the generator. It must be less or equal to the generator's current capacity.
Return values
PSA_SUCCESS
PSA_ERROR_INVALID_ARGUMENTcapacity is larger than the generator's current capacity.
PSA_ERROR_BAD_STATE
PSA_ERROR_COMMUNICATION_FAILURE