|
Platform Security Architecture — cryptography and keystore interface
beta 2 — 2019-02-22
|
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) |
| #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 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.
| 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.
| [in,out] | generator | The generator to abort. |
| 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.
| handle | Handle 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. | |
| type | Key type (a PSA_KEY_TYPE_XXX value). This must be a symmetric key type. | |
| bits | Key size in bits. | |
| [in,out] | generator | The generator object to read from. |
| PSA_SUCCESS | Success. If the key is persistent, the key material and the key's metadata have been saved to persistent storage. |
| PSA_ERROR_INSUFFICIENT_CAPACITY | There 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_SUPPORTED | The 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_SLOT | There 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_STATE | The 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.
| [in,out] | generator | The generator object to read from. |
| [out] | output | Buffer where the generator output will be written. |
| output_length | Number of bytes to output. |
| PSA_SUCCESS | |
| PSA_ERROR_INSUFFICIENT_CAPACITY | There 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.
| [in] | generator | The generator to query. |
| [out] | capacity | On success, the capacity of the generator. |
| 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.
| [in,out] | generator | The generator object to modify. |
| capacity | The new capacity of the generator. It must be less or equal to the generator's current capacity. |
| PSA_SUCCESS | |
| PSA_ERROR_INVALID_ARGUMENT | capacity is larger than the generator's current capacity. |
| PSA_ERROR_BAD_STATE | |
| PSA_ERROR_COMMUNICATION_FAILURE |
1.8.11