crypto_types.h File Reference

Type definitions for PSA Crypto. More...

Detailed Description

Type definitions for PSA Crypto.

Author

Lena Boeckmann lena..nosp@m.boec.nosp@m.kmann.nosp@m.@haw.nosp@m.-hamb.nosp@m.urg..nosp@m.de

Definition in file crypto_types.h.

#include <stdint.h>

Include dependency graph for crypto_types.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

enum	psa_encrypt_or_decrypt_t { PSA_CRYPTO_DRIVER_DECRYPT , PSA_CRYPTO_DRIVER_ENCRYPT }
	For encrypt-decrypt functions, whether the operation is an encryption or a decryption. More...
typedef uint32_t	psa_algorithm_t
	Encoding of a cryptographic algorithm.
typedef uint8_t	psa_dh_family_t
	The type of PSA finite-field Diffie-Hellman group family identifiers.
typedef uint8_t	psa_ecc_family_t
	The type of PSA elliptic curve family identifiers.
typedef struct psa_key_derivation_operation_s	psa_key_derivation_operation_t
	The type of the state object for key derivation operations.
typedef uint16_t	psa_key_derivation_step_t
	Encoding of the step of a key derivation.
typedef uint32_t	psa_key_id_t
	Key identifier.
typedef uint32_t	psa_key_lifetime_t
	Encoding of key lifetimes.
typedef uint32_t	psa_key_location_t
	Encoding of key location indicators.
typedef uint8_t	psa_key_persistence_t
	Encoding of key persistence levels.
typedef uint16_t	psa_key_type_t
	Encoding of a key type.
typedef uint32_t	psa_key_usage_t
	Encoding of permitted usage on a key.
typedef uint16_t	psa_key_bits_t
	Public interfaces use size_t, but internally we use a smaller type.
typedef struct psa_aead_operation_s	psa_aead_operation_t
	The type of the state object for multi-part AEAD operations.
typedef struct psa_mac_operation_s	psa_mac_operation_t
	The type of the state object for multi-part MAC operations.
typedef int32_t	psa_status_t
	Function return status.
typedef struct psa_hash_operation_s	psa_hash_operation_t
	The type of the state data structure for multipart hash operations.
typedef struct psa_key_attributes_s	psa_key_attributes_t
	The type of an object containing key attributes.
typedef struct psa_cipher_operation_s	psa_cipher_operation_t
	The type of the state object for multi-part cipher operations.

Typedef Documentation

psa_aead_operation_t

typedef struct psa_aead_operation_s psa_aead_operation_t

The type of the state object for multi-part AEAD operations.

Before calling any function on an AEAD operation object, the application must initialize it by any of the following means:

• Set the object to all-bits-zero, for example:

  @ref psa_aead_operation_t operation;
  memset(&operation, 0, sizeof(operation));

• Initialize the object to logical zero values by declaring the object as static or global without an explicit initializer, for example:

  static @ref psa_aead_operation_t operation;

• Initialize the object to the initializer PSA_AEAD_OPERATION_INIT, for example:

  @ref psa_aead_operation_t operation = @ref PSA_AEAD_OPERATION_INIT;

• Assign the result of the function psa_aead_operation_init() to the object, for example:

  @ref psa_aead_operation_t operation;
  operation = @ref psa_aead_operation_init();

This is an implementation-defined type. Applications that make assumptions about the content of this object will result in in implementation-specific behavior, and are non-portable.

Definition at line 289 of file crypto_types.h.

psa_algorithm_t

typedef uint32_t psa_algorithm_t

Encoding of a cryptographic algorithm.

For algorithms that can be applied to multiple key types, this identifier does not encode the key type. For example, for symmetric ciphers based on a block cipher, psa_algorithm_t encodes the block cipher mode and the padding mode while the block cipher itself is encoded via psa_key_type_t.

Definition at line 46 of file crypto_types.h.

psa_cipher_operation_t

typedef struct psa_cipher_operation_s psa_cipher_operation_t

The type of the state object for multi-part cipher operations.

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

• Set the object to all-bits-zero, for example:

  @ref psa_cipher_operation_t operation;
  memset(&operation, 0, sizeof(operation));

• Initialize the object to logical zero values by declaring the object as static or global without an explicit initializer, for example:

  static @ref psa_cipher_operation_t operation;

• Initialize the object to the initializer PSA_CIPHER_OPERATION_INIT, for example:

  @ref psa_cipher_operation_t operation = @ref PSA_CIPHER_OPERATION_INIT;

• Assign the result of the function psa_cipher_operation_init() to the object, for example:

  @ref psa_cipher_operation_t operation;
  operation = @ref psa_cipher_operation_init();

This is an implementation-defined type. Applications that make assumptions about the content of this object will result in in implementation-specific behavior, and are non-portable.

Definition at line 496 of file crypto_types.h.

psa_dh_family_t

typedef uint8_t psa_dh_family_t

The type of PSA finite-field Diffie-Hellman group family identifiers.

The group family identifier is required to create a finite-field Diffie-Hellman key using the PSA_KEY_TYPE_DH_KEY_PAIR() or PSA_KEY_TYPE_DH_PUBLIC_KEY() macros.

The specific Diffie-Hellman group within a family is identified by the key_bits attribute of the key.

Definition at line 58 of file crypto_types.h.

psa_ecc_family_t

typedef uint8_t psa_ecc_family_t

The type of PSA elliptic curve family identifiers.

The curve identifier is required to create an ECC key using the PSA_KEY_TYPE_ECC_KEY_PAIR() or PSA_KEY_TYPE_ECC_PUBLIC_KEY() macros.

The specific ECC curve within a family is identified by the key_bits attribute of the key.

Definition at line 70 of file crypto_types.h.

psa_hash_operation_t

typedef struct psa_hash_operation_s psa_hash_operation_t

The type of the state data structure for multipart hash operations.

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

• Set the structure to all-bits-zero, for example:

  @ref psa_hash_operation_t operation;
  memset(&operation, 0, sizeof(operation));

• Initialize the structure to logical zero values, for example:

  @ref psa_hash_operation_t operation = {0};

• Initialize the structure to the initializer PSA_HASH_OPERATION_INIT, for example:

  @ref psa_hash_operation_t operation = @ref PSA_HASH_OPERATION_INIT;

• Assign the result of the function psa_hash_operation_init() to the structure, for example:

  @ref psa_hash_operation_t operation;
  operation = @ref psa_hash_operation_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.

Definition at line 361 of file crypto_types.h.

psa_key_attributes_t

typedef struct psa_key_attributes_s psa_key_attributes_t

The type of an object containing key attributes.

This is the object that represents the metadata of a key object. Metadata that can be stored in attributes includes:

• The location of the key in storage, indicated by its key identifier and its lifetime.
• The key’s policy, comprising usage flags and a specification of the permitted algorithm(s).
• Information about the key itself: the key type and its size.
• Implementations can define additional attributes.

The actual key material is not considered an attribute of a key. Key attributes do not contain information that is generally considered highly confidential.

Note

Implementations are recommended to define the attribute object as a simple data structure, with fields corresponding to the individual key attributes. In such an implementation, each function psa_set_key_xxx() sets a field and the corresponding function psa_get_key_xxx() retrieves the value of the field. An implementation can report attribute values that are equivalent to the original one, but have a different encoding. For example, an implementation can use a more compact representation for types where many bit-patterns are invalid or not supported, and store all values that it does not support as a special marker value. In such an implementation, after setting an invalid value, the corresponding get function returns an invalid value which might not be the one that was originally stored.

This is an implementation-defined type. Applications that make assumptions about the content of this object will result in in implementation-specific behavior, and are non-portable.

An attribute object can contain references to auxiliary resources, for example pointers to allocated memory or indirect references to pre-calculated values. In order to free such resources, the application must call psa_reset_key_attributes(). As an exception, calling psa_reset_key_attributes() on an attribute object is optional if the object has only been modified by the following functions since it was initialized or last reset with psa_reset_key_attributes():

• psa_set_key_id()
• psa_set_key_lifetime()
• psa_set_key_type()
• psa_set_key_bits()
• psa_set_key_usage_flags()
• psa_set_key_algorithm() Before calling any function on a key attribute object, the application must initialize it by any of the following means:
• Set the object to all-bits-zero, for example:

  @ref psa_key_attributes_t attributes;
  memset(&attributes, 0, sizeof(attributes));

• Initialize the object to logical zero values by declaring the object as static or global without an explicit initializer, for example:

  static @ref psa_key_attributes_t attributes;

• Initialize the object to the initializer PSA_KEY_ATTRIBUTES_INIT, for example:

  @ref psa_key_attributes_t attributes = @ref PSA_KEY_ATTRIBUTES_INIT;

• Assign the result of the function psa_key_attributes_init() to the object, for example:

  @ref psa_key_attributes_t attributes;
  attributes = @ref psa_key_attributes_init();

A freshly initialized attribute object contains the following values:

• lifetime: PSA_KEY_LIFETIME_VOLATILE.
• key identifier: PSA_KEY_ID_NULL — which is not a valid key identifier.
• type: PSA_KEY_TYPE_NONE — meaning that the type is unspecified.
• key size: 0 — meaning that the size is unspecified.
• usage flags: 0 — which allows no usage except exporting a public key.
• algorithm: PSA_ALG_NONE — which does not allow cryptographic usage, but allows exporting.

Usage

A typical sequence to create a key is as follows:

1. Create and initialize an attribute object.
2. If the key is persistent, call psa_set_key_id(). Also call psa_set_key_lifetime() to place the key in a non-default location.
3. Set the key policy with psa_set_key_usage_flags() and psa_set_key_algorithm().
4. Set the key type with psa_set_key_type(). Skip this step if copying an existing key with psa_copy_key().
5. When generating a random key with psa_generate_key() or deriving a key with psa_key_derivation_output_key(), set the desired key size with psa_set_key_bits().
6. Call a key creation function: psa_import_key(), psa_generate_key(), psa_key_derivation_output_key() or psa_copy_key(). This function reads the attribute object, creates a key with these attributes, and outputs an identifier for the newly created key.
7. Optionally call psa_reset_key_attributes(), now that the attribute object is no longer needed. Currently this call is not required as the attributes defined in this specification do not require additional resources beyond the object itself.

A typical sequence to query a key’s attributes is as follows:

1. Call psa_get_key_attributes().
2. Call psa_get_key_xxx() functions to retrieve the required attribute(s).
3. Call psa_reset_key_attributes() to free any resources that can be used by the attribute object.

Once a key has been created, it is impossible to change its attributes.

Definition at line 464 of file crypto_types.h.

psa_key_bits_t

typedef uint16_t psa_key_bits_t

Public interfaces use size_t, but internally we use a smaller type.

Definition at line 256 of file crypto_types.h.

psa_key_derivation_operation_t

typedef struct psa_key_derivation_operation_s psa_key_derivation_operation_t

The type of the state object for key derivation operations.

Before calling any function on a key derivation operation object, the application must initialize it by any of the following means:

• Set the object to all-bits-zero, for example:

  @ref psa_key_derivation_operation_t operation;
  memset(&operation, 0, sizeof(operation));

• Initialize the object to logical zero values by declaring the object as static or global without an explicit initializer, for example:

  static @ref psa_key_derivation_operation_t operation;

• Initialize the object to the initializer PSA_KEY_DERIVATION_OPERATION_INIT, for example:

  @ref psa_key_derivation_operation_t operation =
  @ref PSA_KEY_DERIVATION_OPERATION_INIT;

• Assign the result of the function psa_key_derivation_operation_init() to the object, for example:

  @ref psa_key_derivation_operation_t operation;
  operation = @ref psa_key_derivation_operation_init();

  This is an implementation-defined type. Applications that make assumptions about the content of this object will result in in implementation-specific behavior, and are non-portable.

Definition at line 103 of file crypto_types.h.

psa_key_derivation_step_t

typedef uint16_t psa_key_derivation_step_t

Encoding of the step of a key derivation.

Definition at line 108 of file crypto_types.h.

psa_key_id_t

typedef uint32_t psa_key_id_t

Key identifier.

A key identifier can be a permanent name for a persistent key, or a transient reference to volatile key.

Definition at line 116 of file crypto_types.h.

psa_key_lifetime_t

typedef uint32_t psa_key_lifetime_t

Encoding of key lifetimes.

The lifetime of a key indicates where it is stored and which application and system actions will create and destroy it.

Lifetime values have the following structure:

• Bits[7:0]: Persistence level This value indicates what device management actions can cause it to be destroyed. In particular, it indicates whether the key is volatile or persistent. See psa_key_persistence_t for more information. PSA_KEY_LIFETIME_GET_PERSISTENCE(lifetime) returns the persistence level for a key lifetime value.
• Bits[31:8]: Location indicator This value indicates where the key material is stored (or at least where it is accessible in cleartext) and where operations on the key are performed. See psa_key_location_t for more information. PSA_KEY_LIFETIME_GET_LOCATION(lifetime) returns the location indicator for a key lifetime value.

Volatile keys are automatically destroyed when the application instance terminates or on a power reset of the device. Persistent keys are preserved until the application explicitly destroys them or until an implementation-specific device management event occurs, for example, a factor reset.

Persistent keys have a key identifier of type psa_key_id_t. This identifier remains valid throughout the lifetime of the key, even if the application instance that created the key terminates.

This specification defines two basic lifetime values:

• Keys with the lifetime PSA_KEY_LIFETIME_VOLATILE are volatile. All implementations should support this lifetime.
• Keys with the lifetime PSA_KEY_LIFETIME_PERSISTENT are persistent. All implementations that have access to persistent storage with appropriate security guarantees should support this lifetime.

Definition at line 154 of file crypto_types.h.

psa_key_location_t

typedef uint32_t psa_key_location_t

Encoding of key location indicators.

If an implementation of this API can make calls to external cryptoprocessors such as secure elements, the location of a key indicates which secure element performs the operations on the key. If the key material is not stored persistently inside the secure element, it must be stored in a wrapped form such that only the secure element can access the key material in cleartext.

Note

Key location indicators are 24-bit values. Key management interfaces operate on lifetimes (type psa_key_lifetime_t), and encode the location as the upper 24 bits of a 32-bit value.

Values for location indicators defined by this specification are shown below:

• 0: Primary local storage. All implementations should support this value. The primary local storage is typically the same storage area that contains the key metadata.
• 1: Primary secure element.

  Note

  As of now, this value is not supported by this implementation. Use the vendor-defined location values.

  Implementations should support this value if there is a secure element attached to the operating environment. As a guideline, secure elements may provide higher resistance against side channel and physical attacks than the primary local storage, but may have restrictions on supported key types, sizes, policies and operations and may have different performance characteristics.
• 2–0x7fffff: Other locations defined by a PSA specification. The PSA Cryptography API does not currently assign any meaning to these locations, but future versions of this specification or other PSA specifications may do so.
• 0x800000–0xffffff: Vendor-defined locations. No PSA specification will assign a meaning to locations in this range.

Definition at line 190 of file crypto_types.h.

psa_key_persistence_t

typedef uint8_t psa_key_persistence_t

Encoding of key persistence levels.

What distinguishes different persistence levels is which device management events can cause keys to be destroyed. For example, power reset, transfer of device ownership, or a factory reset are device management events that can affect keys at different persistence levels. The specific management events which affect persistent keys at different levels is outside the scope of the PSA Cryptography specification.

Note

Key persistence levels are 8-bit values. Key management interfaces operate on lifetimes (type psa_key_lifetime_t), and encode the persistence value as the lower 8 bits of a 32-bit value.

Values for persistence levels defined by this specification are shown below:

• 0 = PSA_KEY_PERSISTENCE_VOLATILE : Volatile key. A volatile key is automatically destroyed by the implementation when the application instance terminates. In particular, a volatile key is automatically destroyed on a power reset of the device.
• 1 = PSA_KEY_PERSISTENCE_DEFAULT : Persistent key with a default lifetime. Implementations should support this value if they support persistent keys at all. Applications should use this value if they have no specific needs that are only met by implementation-specific features.
• 2–127: Persistent key with a PSA-specified lifetime. The PSA Cryptography specification does not define the meaning of these values, but other PSA specifications may do so.
• 128–254: Persistent key with a vendor-specified lifetime. No PSA specification will define the meaning of these values, so implementations may choose the meaning freely. As a guideline, higher persistence levels should cause a key to survive more management events than lower levels.
• 255 = PSA_KEY_PERSISTENCE_READ_ONLY : Read-only or write-once key. A key with this persistence level cannot be destroyed. Implementations that support such keys may either allow their creation through the PSA Cryptography API, preferably only to applications with the appropriate privilege, or only expose keys created through implementation-specific means such as a factory ROM engraving process.

  Note

  Keys that are read-only due to policy restrictions rather than due to physical limitations should not have this persistence level.

Definition at line 230 of file crypto_types.h.

psa_key_type_t

typedef uint16_t psa_key_type_t

Encoding of a key type.

This is a structured bitfield that identifies the category and type of key. The range of key type values is divided as follows:

• PSA_KEY_TYPE_NONE == 0: Reserved as an invalid key type.
• 0x0001–0x7fff: Specification-defined key types. Key types defined by this standard always have bit 15 clear. Unallocated key type values in this range are reserved for future use.
• 0x8000–0xffff: Implementation-defined key types. Implementations that define additional key types must use an encoding with bit 15 set.

Definition at line 246 of file crypto_types.h.

psa_key_usage_t

typedef uint32_t psa_key_usage_t

Encoding of permitted usage on a key.

Definition at line 251 of file crypto_types.h.

psa_mac_operation_t

typedef struct psa_mac_operation_s psa_mac_operation_t

The type of the state object for multi-part MAC operations.

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

• Set the object to all-bits-zero, for example:

  @ref psa_mac_operation_t operation;
  memset(&operation, 0, sizeof(operation));

• Initialize the object to logical zero values by declaring the object as static or global without an explicit initializer, for example:

  static @ref psa_mac_operation_t operation;

• Initialize the object to the initializer PSA_MAC_OPERATION_INIT, for example:

  @ref psa_mac_operation_t operation = @ref PSA_MAC_OPERATION_INIT;

• Assign the result of the function psa_mac_operation_init() to the object, for example:

  @ref psa_mac_operation_t operation;
  operation = @ref psa_mac_operation_init();

  This is an implementation-defined type. Applications that make assumptions about the content of this object will result in in implementation-specific behavior, and are non-portable.

Definition at line 320 of file crypto_types.h.

psa_status_t

typedef int32_t psa_status_t

Function return status.

This is either PSA_SUCCESS, which is zero, indicating success; or a small negative value indicating that an error occurred. Errors are encoded as one of the PSA_ERROR_xxx values defined here.

Definition at line 329 of file crypto_types.h.

Enumeration Type Documentation

psa_encrypt_or_decrypt_t

enum psa_encrypt_or_decrypt_t

For encrypt-decrypt functions, whether the operation is an encryption or a decryption.

Definition at line 33 of file crypto_types.h.