psa_set_key_bits() function

The attribute structure to write to.

The key size in bits. If this is 0, the key size in \p attributes becomes unspecified. Keys of size 0 are not supported.

Set domain parameters for a key. Some key types require additional domain parameters in addition to the key type identifier and the key size. Use this function instead of psa_set_key_type() when you need to specify domain parameters. The format for the required domain parameters varies based on the key type. - For RSA keys (#PSA_KEY_TYPE_RSA_PUBLIC_KEY or #PSA_KEY_TYPE_RSA_KEY_PAIR), the domain parameter data consists of the public exponent, represented as a big-endian integer with no leading zeros. This information is used when generating an RSA key pair. When importing a key, the public exponent is read from the imported key data and the exponent recorded in the attribute structure is ignored. As an exception, the public exponent 65537 is represented by an empty byte string. - For DSA keys (#PSA_KEY_TYPE_DSA_PUBLIC_KEY or #PSA_KEY_TYPE_DSA_KEY_PAIR), the `Dss-Params` format as defined by RFC 3279 §2.3.2. ``` Dss-Params ::= SEQUENCE { p INTEGER, q INTEGER, g INTEGER } ``` - For Diffie-Hellman key exchange keys (#PSA_KEY_TYPE_DH_PUBLIC_KEY(#PSA_DH_FAMILY_CUSTOM) or #PSA_KEY_TYPE_DH_KEY_PAIR(#PSA_DH_FAMILY_CUSTOM)), the `DomainParameters` format as defined by RFC 3279 §2.3.3. ``` DomainParameters ::= SEQUENCE { p INTEGER, -- odd prime, p=jq +1 g INTEGER, -- generator, g q INTEGER, -- factor of p-1 j INTEGER OPTIONAL, -- subgroup factor validationParams ValidationParams OPTIONAL } ValidationParams ::= SEQUENCE { seed BIT STRING, pgenCounter INTEGER } ```

Set the location of a persistent key. To make a key persistent, you must give it a persistent key identifier with psa_set_key_id(). By default, a key that has a persistent identifier is stored in the default storage area identifier by #PSA_KEY_LIFETIME_PERSISTENT. Call this function to choose a storage area, or to explicitly declare the key as volatile. This function does not access storage, it merely stores the given value in the structure. The persistent key will be written to storage when the attribute structure is passed to a key creation function such as psa_import_key(), psa_generate_key(), psa_key_derivation_output_key() or psa_copy_key(). This function may be declared as `static` (i.e. without external linkage). This function may be provided as a function-like macro, but in this case it must evaluate each of its arguments exactly once.

Retrieve the lifetime from key attributes. This function may be declared as `static` (i.e. without external linkage). This function may be provided as a function-like macro, but in this case it must evaluate its argument exactly once.

Declare a key as persistent and set its key identifier. If the attribute structure currently declares the key as volatile (which is the default content of an attribute structure), this function sets the lifetime attribute to #PSA_KEY_LIFETIME_PERSISTENT. This function does not access storage, it merely stores the given value in the structure. The persistent key will be written to storage when the attribute structure is passed to a key creation function such as psa_import_key(), psa_generate_key(), psa_key_derivation_output_key() or psa_copy_key(). This function may be declared as `static` (i.e. without external linkage). This function may be provided as a function-like macro, but in this case it must evaluate each of its arguments exactly once.

Retrieve the key identifier from key attributes. This function may be declared as `static` (i.e. without external linkage). This function may be provided as a function-like macro, but in this case it must evaluate its argument exactly once.

Declare the type of a key. This function overwrites any key type previously set in \p attributes. This function may be declared as `static` (i.e. without external linkage). This function may be provided as a function-like macro, but in this case it must evaluate each of its arguments exactly once.

Retrieve the key type from key attributes. This function may be declared as `static` (i.e. without external linkage). This function may be provided as a function-like macro, but in this case it must evaluate its argument exactly once.

Retrieve the key size from key attributes. This function may be declared as `static` (i.e. without external linkage). This function may be provided as a function-like macro, but in this case it must evaluate its argument exactly once.

Declare usage flags for a key. Usage flags are part of a key's usage policy. They encode what kind of operations are permitted on the key. For more details, refer to the documentation of the type #psa_key_usage_t. This function overwrites any usage flags previously set in \p attributes. This function may be declared as `static` (i.e. without external linkage). This function may be provided as a function-like macro, but in this case it must evaluate each of its arguments exactly once.

Retrieve the usage flags from key attributes. This function may be declared as `static` (i.e. without external linkage). This function may be provided as a function-like macro, but in this case it must evaluate its argument exactly once.

Declare the permitted algorithm policy for a key. The permitted algorithm policy of a key encodes which algorithm or algorithms are permitted to be used with this key. The following algorithm policies are supported: - 0 does not allow any cryptographic operation with the key. The key may be used for non-cryptographic actions such as exporting (if permitted by the usage flags). - An algorithm value permits this particular algorithm. - An algorithm wildcard built from #PSA_ALG_ANY_HASH allows the specified signature scheme with any hash algorithm. - An algorithm built from #PSA_ALG_AT_LEAST_THIS_LENGTH_MAC allows any MAC algorithm from the same base class (e.g. CMAC) which generates/verifies a MAC length greater than or equal to the length encoded in the wildcard algorithm. - An algorithm built from #PSA_ALG_AEAD_WITH_AT_LEAST_THIS_LENGTH_TAG allows any AEAD algorithm from the same base class (e.g. CCM) which generates/verifies a tag length greater than or equal to the length encoded in the wildcard algorithm. This function overwrites any algorithm policy previously set in \p attributes. This function may be declared as `static` (i.e. without external linkage). This function may be provided as a function-like macro, but in this case it must evaluate each of its arguments exactly once.

Retrieve the algorithm policy from key attributes. This function may be declared as `static` (i.e. without external linkage). This function may be provided as a function-like macro, but in this case it must evaluate its argument exactly once.

Declare the enrollment algorithm for a key. An operation on a key may indifferently use the algorithm set with psa_set_key_algorithm() or with this function. \warning Setting an enrollment algorithm is not recommended, because using the same key with different algorithms can allow some attacks based on arithmetic relations between different computations made with the same key, or can escalate harmless side channels into exploitable ones. Use this function only if it is necessary to support a protocol for which it has been verified that the usage of the key with multiple algorithms is safe.

Retrieve the enrollment algorithm policy from key attributes.

Get domain parameters for a key. Get the domain parameters for a key with this function, if any. The format of the domain parameters written to \p data is specified in the documentation for psa_set_key_domain_parameters().

Import a key in binary format. This function supports any output from psa_export_key(). Refer to the documentation of psa_export_public_key() for the format of public keys and to the documentation of psa_export_key() for the format for other key types. The key data determines the key size. The attributes may optionally specify a key size; in this case it must match the size determined from the key data. A key size of 0 in \p attributes indicates that the key size is solely determined by the key data. Implementations must reject an attempt to import a key of size 0. This specification supports a single format for each key type. Implementations may support other formats as long as the standard format is supported. Implementations that support other formats should ensure that the formats are clearly unambiguous so as to minimize the risk that an invalid input is accidentally interpreted according to a different format.

Retrieve the attributes of a key. This function first resets the attribute structure as with psa_reset_key_attributes(). It then copies the attributes of the given key into the given attribute structure.

Reset a key attribute structure to a freshly initialized state. You must initialize the attribute structure as described in the documentation of the type #psa_key_attributes_t before calling this function. Once the structure has been initialized, you may call this function at any time. This function frees any auxiliary resources that the structure may contain.

Make a copy of a key. Copy key material from one location to another. This function is primarily useful to copy a key from one location to another, since it populates a key using the material from another key which may have a different lifetime. This function may be used to share a key with a different party, subject to implementation-defined restrictions on key sharing. The policy on the source key must have the usage flag #PSA_KEY_USAGE_COPY set. This flag is sufficient to permit the copy if the key has the lifetime #PSA_KEY_LIFETIME_VOLATILE or #PSA_KEY_LIFETIME_PERSISTENT. Some secure elements do not provide a way to copy a key without making it extractable from the secure element. If a key is located in such a secure element, then the key must have both usage flags #PSA_KEY_USAGE_COPY and #PSA_KEY_USAGE_EXPORT in order to make a copy of the key outside the secure element. The resulting key may only be used in a way that conforms to both the policy of the original key and the policy specified in the \p attributes parameter: - The usage flags on the resulting key are the bitwise-and of the usage flags on the source policy and the usage flags in \p attributes. - If both allow the same algorithm or wildcard-based algorithm policy, the resulting key has the same algorithm policy. - If either of the policies allows an algorithm and the other policy allows a wildcard-based algorithm policy that includes this algorithm, the resulting key allows the same algorithm. - If the policies do not allow any algorithm in common, this function fails with the status #PSA_ERROR_INVALID_ARGUMENT. The effect of this function on implementation-defined attributes is implementation-defined.

Derive a key from an ongoing key derivation operation. This function calculates output bytes from a key derivation algorithm and uses those bytes to generate a key deterministically. The key's location, usage policy, type and size are taken from \p attributes. If you view the key derivation's output as a stream of bytes, this function destructively reads as many bytes as required from the stream. The operation's capacity decreases by the number of bytes read. If this function returns an error status other than #PSA_ERROR_INSUFFICIENT_DATA, the operation enters an error state and must be aborted by calling psa_key_derivation_abort(). How much output is produced and consumed from the operation, and how the key is derived, depends on the key type and on the key size (denoted \c bits below): - For key types for which the key is an arbitrary sequence of bytes of a given size, this function is functionally equivalent to calling #psa_key_derivation_output_bytes and passing the resulting output to #psa_import_key. However, this function has a security benefit: if the implementation provides an isolation boundary then the key material is not exposed outside the isolation boundary. As a consequence, for these key types, this function always consumes exactly (\c bits / 8) bytes from the operation. The following key types defined in this specification follow this scheme: - #PSA_KEY_TYPE_AES; - #PSA_KEY_TYPE_ARC4; - #PSA_KEY_TYPE_ARIA; - #PSA_KEY_TYPE_CAMELLIA; - #PSA_KEY_TYPE_DERIVE; - #PSA_KEY_TYPE_HMAC. - For ECC keys on a Montgomery elliptic curve (#PSA_KEY_TYPE_ECC_KEY_PAIR(\c curve) where \c curve designates a Montgomery curve), this function always draws a byte string whose length is determined by the curve, and sets the mandatory bits accordingly. That is: - Curve25519 (#PSA_ECC_FAMILY_MONTGOMERY, 255 bits): draw a 32-byte string and process it as specified in RFC 7748 §5. - Curve448 (#PSA_ECC_FAMILY_MONTGOMERY, 448 bits): draw a 56-byte string and process it as specified in RFC 7748 §5. - For key types for which the key is represented by a single sequence of \c bits bits with constraints as to which bit sequences are acceptable, this function draws a byte string of length (\c bits / 8) bytes rounded up to the nearest whole number of bytes. If the resulting byte string is acceptable, it becomes the key, otherwise the drawn bytes are discarded. This process is repeated until an acceptable byte string is drawn. The byte string drawn from the operation is interpreted as specified for the output produced by psa_export_key(). The following key types defined in this specification follow this scheme: - #PSA_KEY_TYPE_DES. Force-set the parity bits, but discard forbidden weak keys. For 2-key and 3-key triple-DES, the three keys are generated successively (for example, for 3-key triple-DES, if the first 8 bytes specify a weak key and the next 8 bytes do not, discard the first 8 bytes, use the next 8 bytes as the first key, and continue reading output from the operation to derive the other two keys). - Finite-field Diffie-Hellman keys (#PSA_KEY_TYPE_DH_KEY_PAIR(\c group) where \c group designates any Diffie-Hellman group) and ECC keys on a Weierstrass elliptic curve (#PSA_KEY_TYPE_ECC_KEY_PAIR(\c curve) where \c curve designates a Weierstrass curve). For these key types, interpret the byte string as integer in big-endian order. Discard it if it is not in the range [0, *N* - 2] where *N* is the boundary of the private key domain (the prime *p* for Diffie-Hellman, the subprime *q* for DSA, or the order of the curve's base point for ECC). Add 1 to the resulting integer and use this as the private key *x*. This method allows compliance to NIST standards, specifically the methods titled "key-pair generation by testing candidates" in NIST SP 800-56A §5.6.1.1.4 for Diffie-Hellman, in FIPS 186-4 §B.1.2 for DSA, and in NIST SP 800-56A §5.6.1.2.2 or FIPS 186-4 §B.4.2 for elliptic curve keys. - For other key types, including #PSA_KEY_TYPE_RSA_KEY_PAIR, the way in which the operation output is consumed is implementation-defined. In all cases, the data that is read is discarded from the operation. The operation's capacity is decreased by the number of bytes read. For algorithms that take an input step #PSA_KEY_DERIVATION_INPUT_SECRET, the input to that step must be provided with psa_key_derivation_input_key(). Future versions of this specification may include additional restrictions on the derived key based on the attributes and strength of the secret key.

Generate a key or key pair. The key is generated randomly. Its location, usage policy, type and size are taken from \p attributes. Implementations must reject an attempt to generate a key of size 0. The following type-specific considerations apply: - For RSA keys (#PSA_KEY_TYPE_RSA_KEY_PAIR), the public exponent is 65537. The modulus is a product of two probabilistic primes between 2^{n-1} and 2^n where n is the bit size specified in the attributes.

Process an authenticated decryption operation.

Set the key for a multipart symmetric encryption operation.

Process an authenticated encryption operation.

Encrypt a message using a symmetric cipher.

Decrypt a message using a symmetric cipher.

Set the key for a multipart symmetric decryption operation.

Import a key in binary format.

Export a key in binary format

Export a public key or the public part of a key pair in binary format.

Generate a key.

Verify the signature a hash or short message using a public key.

Sign a message with a private key. For hash-and-sign algorithms, this includes the hashing step.

Verify the signature of a message with a public key, using a hash-and-sign verification algorithm.

Sign an already-calculated hash with a private key.

Calculate the MAC (message authentication code) of a message using Mbed TLS.

Set up a multipart MAC calculation operation using Mbed TLS.

Set up a multipart MAC verification operation using Mbed TLS.