algorithm.h File Reference

Asymmetric signature algorithm definitions for the PSA Crypto API. More...

Detailed Description

Asymmetric signature algorithm definitions for the PSA Crypto API.

Author

Armin Wolf wolf..nosp@m.armi.nosp@m.n@mai.nosp@m.lbox.nosp@m..tu-d.nosp@m.resd.nosp@m.en.de

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

Definition in file algorithm.h.

#include "psa/algorithm.h"
#include "psa/hash/algorithm.h"

Include dependency graph for algorithm.h:

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

Go to the source code of this file.

#define	PSA_ALG_CATEGORY_SIGN   ((psa_algorithm_t)0x06000000)
	Category for asymmetric signature algorithms.
#define	PSA_ALG_IS_SIGN(alg)    (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_ASYMMETRIC_SIGNATURE)
	Whether the specified algorithm is an asymmetric signature algorithm, also known as public-key signature algorithm.
#define	PSA_ALG_IS_RSA_PKCS1V15_SIGN(alg)    (((alg) & ~0x000000ff) == 0x06000200)
	Whether the specified algorithm is an RSA PKCS#1 v1.5 signature algorithm.
#define	PSA_ALG_IS_RSA_PSS(alg)    (((alg) & ~0x000000ff) == 0x06000300)
	Whether the specified algorithm is a RSA PSS signature algorithm.
#define	PSA_ALG_IS_RSA_PSS_ANY_SALT(alg)    (((alg) & ~0x000000ff) == 0x06001300)
	Whether the specified algorithm is an RSA PSS signature algorithm that permits any salt length.
#define	PSA_ALG_IS_RSA_PSS_STANDARD_SALT(alg)    (((alg) & ~0x000000ff) == 0x06000300)
	Whether the specified algorithm is an RSA PSS signature algorithm that requires the standard salt length.
#define	PSA_ALG_IS_ECDSA(alg)    (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_SIGN)
	Whether the specified algorithm is ECDSA.
#define	PSA_ALG_IS_DETERMINISTIC_ECDSA(alg)    (((alg) & ~0x000000ff) == 0x06000700)
	Whether the specified algorithm is deterministic ECDSA.
#define	PSA_ALG_IS_RANDOMIZED_ECDSA(alg)    (((alg) & ~0x000000ff) == 0x06000600)
	Whether the specified algorithm is randomized ECDSA.
#define	PSA_ALG_IS_HASH_EDDSA(alg)    (((alg) & ~0x000000ff) == 0x06000900)
	Whether the specified algorithm is HashEdDSA.
#define	PSA_ALG_IS_SIGN_HASH(alg)
	Whether the specified algorithm is a signature algorithm that can be used with psa_sign_hash() and psa_verify_hash().
#define	PSA_ALG_IS_HASH_AND_SIGN(alg)
	Whether the specified algorithm is a hash-and-sign algorithm that signs exactly the hash value.
#define	PSA_ALG_IS_SIGN_MESSAGE(alg)    (PSA_ALG_IS_SIGN_HASH(alg) || (alg) == PSA_ALG_PURE_EDDSA)
	Whether the specified algorithm is a signature algorithm that can be used with psa_sign_message() and psa_verify_message().
#define	PSA_ALG_IS_WILDCARD(alg)    (PSA_ALG_GET_HASH(alg) == PSA_ALG_ANY_HASH)
	Whether the specified algorithm encoding is a wildcard.
#define	PSA_ALG_ANY_HASH   ((psa_algorithm_t)0x020000ff)
	When setting a hash-and-sign algorithm in a key policy, permit any hash algorithm.
#define	PSA_ALG_RSA_PKCS1V15_SIGN(hash_alg)    ((psa_algorithm_t)(0x06000200 | ((hash_alg) & 0x000000ff)))
	The RSA PKCS#1 v1.5 message signature scheme, with hashing.
#define	PSA_ALG_RSA_PKCS1V15_SIGN_RAW   ((psa_algorithm_t)0x06000200)
	The raw RSA PKCS#1 v1.5 signature algorithm, without hashing.
#define	PSA_ALG_RSA_PSS(hash_alg)    ((psa_algorithm_t)(0x06000300 | ((hash_alg) & 0x000000ff)))
	The RSA PSS message signature scheme, with hashing.
#define	PSA_ALG_RSA_PSS_ANY_SALT(hash_alg)    ((psa_algorithm_t)(0x06001300 | ((hash_alg) & 0x000000ff)))
	The RSA PSS message signature scheme, with hashing.
#define	PSA_ALG_ECDSA_BASE   ((psa_algorithm_t)0x06000600)
	Base of ECDSA algorithms.
#define	PSA_ALG_ECDSA(hash_alg)    (PSA_ALG_ECDSA_BASE | ((hash_alg) & PSA_ALG_HASH_MASK))
	The randomized ECDSA signature scheme, with hashing.
#define	PSA_ALG_ECDSA_ANY   PSA_ALG_ECDSA_BASE
	The randomized ECDSA signature scheme, without hashing.
#define	PSA_ALG_DETERMINISTIC_ECDSA(hash_alg)    ((psa_algorithm_t)(0x06000700 | ((hash_alg) & 0x000000ff)))
	Deterministic ECDSA signature scheme, with hashing.
#define	PSA_ALG_PURE_EDDSA   ((psa_algorithm_t)0x06000800)
	Edwards-curve digital signature algorithm without prehashing (PureEdDSA), using standard parameters.
#define	PSA_ALG_ED25519PH   ((psa_algorithm_t)0x0600090B)
	Edwards-curve digital signature algorithm with prehashing (HashEdDSA), using the Edwards25519 curve.
#define	PSA_ALG_ED448PH   ((psa_algorithm_t)0x06000915)
	Edwards-curve digital signature algorithm with prehashing (HashEdDSA), using the Edwards448 curve.

Macro Definition Documentation

PSA_ALG_ANY_HASH

#define PSA_ALG_ANY_HASH   ((psa_algorithm_t)0x020000ff)

When setting a hash-and-sign algorithm in a key policy, permit any hash algorithm.

This value can be used to form the permitted algorithm attribute of a key policy for a signature algorithm that is parametrized by a hash. A key with this policy can then be used to perform operations using the same signature algorithm parametrized with any supported hash. A signature algorithm created using this macro is a wildcard algorithm, and PSA_ALG_IS_WILDCARD() will return true.

This value must not be used to build other algorithms that are parametrized over a hash. For any valid use of this macro to build an algorithm alg, PSA_ALG_IS_HASH_AND_SIGN(alg) is true. This value must not be used to build an algorithm specification to perform an operation. It is only valid for setting the permitted algorithm in a key policy.

Usage: For example, suppose that PSA_xxx_SIGNATURE is one of the following macros:

• PSA_ALG_RSA_PKCS1V15_SIGN
• PSA_ALG_RSA_PSS
• PSA_ALG_RSA_PSS_ANY_SALT
• PSA_ALG_ECDSA
• PSA_ALG_DETERMINISTIC_ECDSA

The following sequence of operations shows how PSA_ALG_ANY_HASH can be used in a key policy:

1. Set the key usage flags using PSA_ALG_ANY_HASH, for example:

   @ref psa_set_key_usage_flags(@p &attributes, @ref PSA_KEY_USAGE_SIGN_MESSAGE);
   // or VERIFY_MESSAGE
   @ref psa_set_key_algorithm(@p &attributes,
   PSA_xxx_SIGNATURE(@ref PSA_ALG_ANY_HASH));

2. Import or generate key material.
3. Call psa_sign_message() or psa_verify_message(), passing an algorithm built from PSA_xxx_SIGNATURE and a specific hash. Each call to sign or verify a message can use a different hash algorithm.

   @ref psa_sign_message(@p key, PSA_xxx_SIGNATURE(@ref PSA_ALG_SHA_256), ...);
   @ref psa_sign_message(@p key, PSA_xxx_SIGNATURE(@ref PSA_ALG_SHA_512), ...);
   @ref psa_sign_message(@p key, PSA_xxx_SIGNATURE(@ref PSA_ALG_SHA3_256), ...);

Definition at line 284 of file algorithm.h.

PSA_ALG_CATEGORY_SIGN

#define PSA_ALG_CATEGORY_SIGN   ((psa_algorithm_t)0x06000000)

Category for asymmetric signature algorithms.

Definition at line 35 of file algorithm.h.

PSA_ALG_DETERMINISTIC_ECDSA

#define PSA_ALG_DETERMINISTIC_ECDSA

(

hash_alg

)

((psa_algorithm_t)(0x06000700 | ((hash_alg) & 0x000000ff)))

Deterministic ECDSA signature scheme, with hashing.

This algorithm can be used with both the message and hash signature functions.

     This is the deterministic ECDSA signature scheme defined by Deterministic Usage of the
     Digital Signature Algorithm (DSA) and Elliptic Curve Digital Signature Algorithm
     (ECDSA) [RFC6979].

     The representation of a signature is the same as with @ref PSA_ALG_ECDSA().

Note

When based on the same hash algorithm, the verification operations for PSA_ALG_ECDSA and PSA_ALG_DETERMINISTIC_ECDSA are identical. A signature created using PSA_ALG_ECDSA can be verified with the same key using either PSA_ALG_ECDSA or PSA_ALG_DETERMINISTIC_ECDSA. Similarly, a signature created using PSA_ALG_DETERMINISTIC_ECDSA can be verified with the same key using either PSA_ALG_ECDSA or PSA_ALG_DETERMINISTIC_ECDSA.

In particular, it is impossible to determine whether a signature was produced with deterministic ECDSA or with randomized ECDSA: it is only possible to verify that a signature was made with ECDSA with the private key corresponding to the public key used for the verification.

Compatible key types

• PSA_KEY_TYPE_ECC_KEY_PAIR(family)
• PSA_KEY_TYPE_ECC_PUBLIC_KEY(family) (signature verification only)

where family is a Weierstrass Elliptic curve family. That is, one of the following values:

• PSA_ECC_FAMILY_SECT_XX
• PSA_ECC_FAMILY_SECP_XX
• PSA_ECC_FAMILY_FRP
• PSA_ECC_FAMILY_BRAINPOOL_P_R1

Parameters

hash_alg

A hash algorithm: a value of type psa_algorithm_t such that PSA_ALG_IS_HASH(hash_alg) is true. This includes PSA_ALG_ANY_HASH when specifying the algorithm in a key policy.

Returns

The corresponding deterministic ECDSA signature algorithm. Unspecified if hash_alg is not a supported hash algorithm.

Definition at line 530 of file algorithm.h.

PSA_ALG_ECDSA

#define PSA_ALG_ECDSA

(

hash_alg

)

(PSA_ALG_ECDSA_BASE | ((hash_alg) & PSA_ALG_HASH_MASK))

The randomized ECDSA signature scheme, with hashing.

This algorithm can be used with both the message and hash signature functions.

     This algorithm is randomized: each invocation returns a different, equally valid
     signature.

Note

When based on the same hash algorithm, the verification operations for PSA_ALG_ECDSA and PSA_ALG_DETERMINISTIC_ECDSA are identical. A signature created using PSA_ALG_ECDSA can be verified with the same key using either PSA_ALG_ECDSA or PSA_ALG_DETERMINISTIC_ECDSA. Similarly, a signature created using PSA_ALG_DETERMINISTIC_ECDSA can be verified with the same key using either PSA_ALG_ECDSA or PSA_ALG_DETERMINISTIC_ECDSA.

In particular, it is impossible to determine whether a signature was produced with deterministic ECDSA or with randomized ECDSA: it is only possible to verify that a signature was made with ECDSA with the private key corresponding to the public key used for the verification.

This signature scheme is defined by SEC 1: Elliptic Curve Cryptography SEC1, and also by Public Key Cryptography For The Financial Services Industry: The Elliptic Curve Digital Signature Algorithm (ECDSA) [X9-62])(https://standards.globalspec.com/std/1955141/ANSI%20X9.62), with a random per-message secret number k.

The representation of the signature as a byte string consists of the concatenation of the signature values r and s. Each of r and s is encoded as an N-octet string, where N is the length of the base point of the curve in octets. Each value is represented in big-endian order, with the most significant octet first.

Compatible key types

• PSA_KEY_TYPE_ECC_KEY_PAIR(family)
• PSA_KEY_TYPE_ECC_PUBLIC_KEY(family) (signature verification only)

where family is a Weierstrass Elliptic curve family. That is, one of the following values:

• PSA_ECC_FAMILY_SECT_XX
• PSA_ECC_FAMILY_SECP_XX
• PSA_ECC_FAMILY_FRP
• PSA_ECC_FAMILY_BRAINPOOL_P_R1

Parameters

hash_alg

A hash algorithm: a value of type psa_algorithm_t such that PSA_ALG_IS_HASH(hash_alg) is true. This includes PSA_ALG_ANY_HASH when specifying the algorithm in a key policy.

Returns

The corresponding randomized ECDSA signature algorithm. Unspecified if hash_alg is not a supported hash algorithm.

Definition at line 457 of file algorithm.h.

PSA_ALG_ECDSA_ANY

#define PSA_ALG_ECDSA_ANY   PSA_ALG_ECDSA_BASE

The randomized ECDSA signature scheme, without hashing.

This algorithm can be only used with the psa_sign_hash() and psa_verify_hash() functions.

This algorithm is randomized: each invocation returns a different, equally valid signature.

This is the same signature scheme as PSA_ALG_ECDSA(), but without specifying a hash algorithm, and skipping the message hashing operation.

This algorithm is only recommended to sign or verify a sequence of bytes that are an already-calculated hash. Note that the input is padded with zeros on the left or truncated on the right as required to fit the curve size.

Compatible key types

• PSA_KEY_TYPE_ECC_KEY_PAIR(family)
• PSA_KEY_TYPE_ECC_PUBLIC_KEY(family) (signature verification only)

where family is a Weierstrass Elliptic curve family. That is, one of the following values:

• PSA_ECC_FAMILY_SECT_XX
• PSA_ECC_FAMILY_SECP_XX
• PSA_ECC_FAMILY_FRP
• PSA_ECC_FAMILY_BRAINPOOL_P_R1

Definition at line 487 of file algorithm.h.

PSA_ALG_ECDSA_BASE

#define PSA_ALG_ECDSA_BASE   ((psa_algorithm_t)0x06000600)

Base of ECDSA algorithms.

Definition at line 406 of file algorithm.h.

PSA_ALG_ED25519PH

#define PSA_ALG_ED25519PH   ((psa_algorithm_t)0x0600090B)

Edwards-curve digital signature algorithm with prehashing (HashEdDSA), using the Edwards25519 curve.

This algorithm can be used with both the message and hash signature functions.

     This computes the Ed25519ph algorithm as specified in Edwards-Curve Digital Signature
     Algorithm (EdDSA) [RFC8032](https://tools.ietf.org/html/rfc8032.html) §5.1, and
     requires an Edwards25519 curve key. An empty string is used as the context. The prehash
     function is SHA-512.

     @b Usage
     This is a hash-and-sign algorithm. To calculate a signature, use one of the following
     approaches:
     -   Call @ref psa_sign_message() with the message.
     -   Calculate the SHA-512 hash of the message with @ref psa_hash_compute(), or with a
         multi-part hash operation, using the hash algorithm @ref PSA_ALG_SHA_512. Then sign
         the calculated hash with @ref psa_sign_hash().

     Verifying a signature is similar, using @ref psa_verify_message() or
     @ref psa_verify_hash() instead of the signature function.

     @b Compatible @b key @b types
     - @ref PSA_KEY_TYPE_ECC_KEY_PAIR(@ref PSA_ECC_FAMILY_TWISTED_EDWARDS)
     - @ref PSA_KEY_TYPE_ECC_PUBLIC_KEY(@ref PSA_ECC_FAMILY_TWISTED_EDWARDS) (signature
       verification only)

Definition at line 597 of file algorithm.h.

PSA_ALG_ED448PH

#define PSA_ALG_ED448PH   ((psa_algorithm_t)0x06000915)

Edwards-curve digital signature algorithm with prehashing (HashEdDSA), using the Edwards448 curve.

This algorithm can be used with both the message and hash signature functions.

     This computes the Ed448ph algorithm as specified in Edwards-Curve Digital Signature
     Algorithm (EdDSA) [RFC8032](https://tools.ietf.org/html/rfc8032.html) §5.2, and
     requires an Edwards448 curve key. An empty string is used as the context. The prehash
     function is the first 64 bytes of the output from SHAKE256.

     @b Usage
     This is a hash-and-sign algorithm. To calculate a signature, use one of the following
     approaches:
     -   Call @ref psa_sign_message() with the message.
     -   Calculate the first 64 bytes of the SHAKE256 output of the message with
         @ref psa_hash_compute(), or with a multi-part hash operation, using the hash
         algorithm @ref PSA_ALG_SHAKE256_512. Then sign the calculated hash with
         @ref psa_sign_hash().

     Verifying a signature is similar, using @ref psa_verify_message() or
     @ref psa_verify_hash() instead of the signature function.

     @b Compatible @b key @b types
     - @ref PSA_KEY_TYPE_ECC_KEY_PAIR(@ref PSA_ECC_FAMILY_TWISTED_EDWARDS)
     - @ref PSA_KEY_TYPE_ECC_PUBLIC_KEY(@ref PSA_ECC_FAMILY_TWISTED_EDWARDS) (signature
       verification only)

Definition at line 627 of file algorithm.h.

PSA_ALG_IS_DETERMINISTIC_ECDSA

#define PSA_ALG_IS_DETERMINISTIC_ECDSA

(

alg

)

(((alg) & ~0x000000ff) == 0x06000700)

Whether the specified algorithm is deterministic ECDSA.

     See also @ref PSA_ALG_IS_ECDSA() and @ref PSA_ALG_IS_RANDOMIZED_ECDSA().

Parameters

alg	An algorithm identifier: a value of type psa_algorithm_t.

Returns

1 if alg is a deterministic ECDSA algorithm 0 otherwise

Definition at line 129 of file algorithm.h.

PSA_ALG_IS_ECDSA

#define PSA_ALG_IS_ECDSA

(

alg

)

(((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_SIGN)

Whether the specified algorithm is ECDSA.

Parameters

alg	An algorithm identifier: a value of type psa_algorithm_t.

Returns

1 if alg is an ECDSA algorithm 0 otherwise

Definition at line 116 of file algorithm.h.

PSA_ALG_IS_HASH_AND_SIGN

#define PSA_ALG_IS_HASH_AND_SIGN

(

alg

)

Value:

    (PSA_ALG_IS_SIGN_HASH(alg) &&       \
     ((alg) & PSA_ALG_HASH_MASK) != 0)

Whether the specified algorithm is a hash-and-sign algorithm that signs exactly the hash value.

This macro identifies algorithms that can be used with psa_sign_hash() that use the exact message hash value as an input the signature operation. For example, if PSA_ALG_IS_HASH_AND_SIGN(alg) is true, the following call sequence is equivalent to psa_sign_message(key, alg, msg, msg_len, ...):

@ref psa_hash_operation_t op = {0};
uint8_t hash[@ref PSA_HASH_MAX_SIZE];
size_t hash_len;
@ref psa_hash_setup(&op, @ref PSA_ALG_GET_HASH(alg));
@ref psa_hash_update(&op, msg, msg_len);
@ref psa_hash_finish(&op, hash, sizeof(hash), &hash_len);
@ref psa_sign_hash(key, alg, hash, hash_len, ...);

This excludes hash-and-sign algorithms that require a encoded or modified hash for the signature step in the algorithm, such as PSA_ALG_RSA_PKCS1V15_SIGN_RAW. For such algorithms, PSA_ALG_IS_SIGN_HASH() is true but PSA_ALG_IS_HASH_AND_SIGN() is false.

Parameters

alg	An algorithm identifier: a value of type psa_algorithm_t.

Returns

1 if alg is a hash-and-sign algorithm that signs exactly the hash value 0 otherwise A wildcard signature algorithm policy, using PSA_ALG_ANY_HASH, returns the same value as the signature algorithm parameterised with a valid hash algorithm.

Definition at line 207 of file algorithm.h.

PSA_ALG_IS_HASH_EDDSA

#define PSA_ALG_IS_HASH_EDDSA

(

alg

)

(((alg) & ~0x000000ff) == 0x06000900)

Whether the specified algorithm is HashEdDSA.

Parameters

alg	An algorithm identifier: a value of type psa_algorithm_t.

Returns

1 if alg is a HashEdDSA algorithm 0 otherwise

Definition at line 153 of file algorithm.h.

PSA_ALG_IS_RANDOMIZED_ECDSA

#define PSA_ALG_IS_RANDOMIZED_ECDSA

(

alg

)

(((alg) & ~0x000000ff) == 0x06000600)

Whether the specified algorithm is randomized ECDSA.

See also PSA_ALG_IS_ECDSA() and PSA_ALG_IS_DETERMINISTIC_ECDSA().

Parameters

alg	An algorithm identifier: a value of type psa_algorithm_t.

Returns

1 if alg is arandomized ECDSA algorithm 0 otherwise

Definition at line 142 of file algorithm.h.

PSA_ALG_IS_RSA_PKCS1V15_SIGN

#define PSA_ALG_IS_RSA_PKCS1V15_SIGN

(

alg

)

(((alg) & ~0x000000ff) == 0x06000200)

Whether the specified algorithm is an RSA PKCS#1 v1.5 signature algorithm.

Parameters

alg	An algorithm identifier: a value of type psa_algorithm_t.

Returns

1 if alg is a RSA PKCS#1 v1.5 signature algorithm 0 otherwise

Definition at line 57 of file algorithm.h.

PSA_ALG_IS_RSA_PSS

#define PSA_ALG_IS_RSA_PSS

(

alg

)

(((alg) & ~0x000000ff) == 0x06000300)

Whether the specified algorithm is a RSA PSS signature algorithm.

This macro returns 1 for algorithms constructed using either PSA_ALG_RSA_PSS() or PSA_ALG_RSA_PSS_ANY_SALT().

Parameters

alg	An algorithm identifier: a value of type psa_algorithm_t.

Returns

1 if alg is a RSA PSS signature algorithm 0 otherwise

Definition at line 71 of file algorithm.h.

PSA_ALG_IS_RSA_PSS_ANY_SALT

#define PSA_ALG_IS_RSA_PSS_ANY_SALT

(

alg

)

(((alg) & ~0x000000ff) == 0x06001300)

Whether the specified algorithm is an RSA PSS signature algorithm that permits any salt length.

An RSA PSS signature algorithm that permits any salt length is constructed using PSA_ALG_RSA_PSS_ANY_SALT().

See also PSA_ALG_IS_RSA_PSS() and PSA_ALG_IS_RSA_PSS_STANDARD_SALT().

Parameters

alg	An algorithm identifier: a value of type psa_algorithm_t.

Returns

1 if alg is a RSA PSS signature algorithm that permits any salt length 0 otherwise

Definition at line 88 of file algorithm.h.

PSA_ALG_IS_RSA_PSS_STANDARD_SALT

#define PSA_ALG_IS_RSA_PSS_STANDARD_SALT

(

alg

)

(((alg) & ~0x000000ff) == 0x06000300)

Whether the specified algorithm is an RSA PSS signature algorithm that requires the standard salt length.

An RSA PSS signature algorithm that requires the standard salt length is constructed using PSA_ALG_RSA_PSS().

See also PSA_ALG_IS_RSA_PSS() and PSA_ALG_IS_RSA_PSS_ANY_SALT().

Parameters

alg	An algorithm identifier: a value of type psa_algorithm_t.

Returns

1 if alg is an RSA PSS signature algorithm that requires the standard salt length 0 otherwise

Definition at line 105 of file algorithm.h.

PSA_ALG_IS_SIGN

#define PSA_ALG_IS_SIGN

(

alg

)

(((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_ASYMMETRIC_SIGNATURE)

Whether the specified algorithm is an asymmetric signature algorithm, also known as public-key signature algorithm.

Parameters

alg	An algorithm identifier: a value of type psa_algorithm_t.

Returns

1 if alg is an asymmetric signature algorithm algorithm 0 otherwise

Definition at line 46 of file algorithm.h.

PSA_ALG_IS_SIGN_HASH

#define PSA_ALG_IS_SIGN_HASH

(

alg

)

Value:

    (PSA_ALG_IS_RSA_PSS(alg) || PSA_ALG_IS_RSA_PKCS1V15_SIGN(alg) ||    \
     PSA_ALG_IS_ECDSA(alg) || PSA_ALG_IS_HASH_EDDSA(alg))

Whether the specified algorithm is a signature algorithm that can be used with psa_sign_hash() and psa_verify_hash().

This includes all algorithms such that PSA_ALG_IS_HASH_AND_SIGN() is true, as well as signature algorithms for which the input to psa_sign_hash() or psa_verify_hash() is not directly a hash, such as PSA_ALG_IS_RSA_PKCS1V15_SIGN.

Parameters

alg	An algorithm identifier: a value of type psa_algorithm_t.

Returns

1 if alg is a signature algorithm that can be used to sign a hash. 0 if alg is a signature algorithm that can only be used to sign a message. 0 if alg is not a signature algorithm

Definition at line 171 of file algorithm.h.

PSA_ALG_IS_SIGN_MESSAGE

#define PSA_ALG_IS_SIGN_MESSAGE

(

alg

)

(PSA_ALG_IS_SIGN_HASH(alg) || (alg) == PSA_ALG_PURE_EDDSA)

Whether the specified algorithm is a signature algorithm that can be used with psa_sign_message() and psa_verify_message().

Parameters

alg	An algorithm identifier: a value of type psa_algorithm_t.

Returns

1 if alg is a signature algorithm that can be used to sign a message. 0 if alg is a signature algorithm that can only be used to sign an already-calculated hash. 0 if alg is not a signature algorithm.

Definition at line 222 of file algorithm.h.

PSA_ALG_IS_WILDCARD

#define PSA_ALG_IS_WILDCARD

(

alg

)

(PSA_ALG_GET_HASH(alg) == PSA_ALG_ANY_HASH)

Whether the specified algorithm encoding is a wildcard.

Wildcard algorithm values can only be used to set the permitted algorithm field in a key policy, wildcard values cannot be used to perform an operation.

See PSA_ALG_ANY_HASH for example of how a wildcard algorithm can be used in a key policy.

Parameters

alg	An algorithm identifier: a value of type psa_algorithm_t.

Returns

1 if alg is a wildcard algorithm encoding. 0 if alg is a non-wildcard algorithm encoding that is suitable for an operation.

Definition at line 239 of file algorithm.h.

PSA_ALG_PURE_EDDSA

#define PSA_ALG_PURE_EDDSA   ((psa_algorithm_t)0x06000800)

Edwards-curve digital signature algorithm without prehashing (PureEdDSA), using standard parameters.

This algorithm can be only used with the psa_sign_message() and psa_verify_message() functions.

This is the PureEdDSA digital signature algorithm defined by Edwards-Curve Digital Signature Algorithm (EdDSA) RFC8032, using standard parameters.

PureEdDSA requires an elliptic curve key on a twisted Edwards curve. The following curves are supported:

• Edwards25519: the Ed25519 algorithm is computed. The output signature is a 64-byte string: the concatenation of R and S as defined by RFC8032 §5.1.6.
• Edwards448: the Ed448 algorithm is computed with an empty string as the context. The output signature is a 114-byte string: the concatenation of R and S as defined by RFC8032 §5.2.6.

Note

Contexts are not supported in the current version of this specification because there is no suitable signature interface that can take the context as a parameter. A future version of this specification may add suitable functions and extend this algorithm to support contexts.

To sign or verify the pre-computed hash of a message using EdDSA, the HashEdDSA algorithms (PSA_ALG_ED25519PH and PSA_ALG_ED448PH) can be used with psa_sign_hash() and psa_verify_hash(). The signature produced by HashEdDSA is distinct from that produced by PureEdDSA.

Compatible key types

• PSA_KEY_TYPE_ECC_KEY_PAIR(PSA_ECC_FAMILY_TWISTED_EDWARDS)
• PSA_KEY_TYPE_ECC_PUBLIC_KEY(PSA_ECC_FAMILY_TWISTED_EDWARDS) (signature verification only)

Definition at line 568 of file algorithm.h.

PSA_ALG_RSA_PKCS1V15_SIGN

#define PSA_ALG_RSA_PKCS1V15_SIGN

(

hash_alg

)

((psa_algorithm_t)(0x06000200 | ((hash_alg) & 0x000000ff)))

The RSA PKCS#1 v1.5 message signature scheme, with hashing.

This algorithm can be used with both the message and hash signature functions.

     This signature scheme is defined by PKCS #1: RSA Cryptography Specifications Version 2.2
     [RFC8017](https://tools.ietf.org/html/rfc8017.html) §8.2 under the name
     RSASSA-PKCS1-v1_5.

     When used with @ref psa_sign_hash() or @ref psa_verify_hash(), the provided hash
     parameter is used as `H` from step 2 onwards in the message encoding algorithm
     EMSA-PKCS1-V1_5-ENCODE() in [RFC8017](https://tools.ietf.org/html/rfc8017.html) §9.2.
     `H` is usually the message digest, using the @c hash_alg hash algorithm.

     @b Compatible @b key @b types
     - @ref PSA_KEY_TYPE_RSA_KEY_PAIR
     - @ref PSA_KEY_TYPE_RSA_PUBLIC_KEY (signature verification only)

Parameters

hash_alg

A hash algorithm: a value of type psa_algorithm_t such that PSA_ALG_IS_HASH(hash_alg) is true. This includes PSA_ALG_ANY_HASH when specifying the algorithm in a key policy.

Returns

The corresponding RSA PKCS#1 v1.5 signature algorithm. Unspecified if hash_alg is not a supported hash algorithm.

Definition at line 311 of file algorithm.h.

PSA_ALG_RSA_PKCS1V15_SIGN_RAW

#define PSA_ALG_RSA_PKCS1V15_SIGN_RAW   ((psa_algorithm_t)0x06000200)

The raw RSA PKCS#1 v1.5 signature algorithm, without hashing.

This algorithm can be only used with the psa_sign_hash() and psa_verify_hash() functions. This signature scheme is defined by PKCS #1: RSA Cryptography Specifications Version 2.2 RFC8017 §8.2 under the name RSASSA-PKCS1-v1_5.

The hash parameter to psa_sign_hash() or psa_verify_hash() is used as T from step 3 onwards in the message encoding algorithm EMSA-PKCS1-V1_5-ENCODE() in RFC8017 §9.2.0 T is the DER encoding of the DigestInfo structure normally produced by step 2 in the message encoding algorithm.

The wildcard key policy PSA_ALG_RSA_PKCS1V15_SIGN(PSA_ALG_ANY_HASH) also permits a key to be used with the PSA_ALG_RSA_PKCS1V15_SIGN_RAW signature algorithm.

Compatible key types

• PSA_KEY_TYPE_RSA_KEY_PAIR
• PSA_KEY_TYPE_RSA_PUBLIC_KEY (signature verification only)

Definition at line 336 of file algorithm.h.

PSA_ALG_RSA_PSS

#define PSA_ALG_RSA_PSS

(

hash_alg

)

((psa_algorithm_t)(0x06000300 | ((hash_alg) & 0x000000ff)))

The RSA PSS message signature scheme, with hashing.

This algorithm can be used with both the message and hash signature functions.

     This algorithm is randomized: each invocation returns a different, equally valid
     signature.

     This is the signature scheme defined by
     [RFC8017](https://tools.ietf.org/html/rfc8017.html) §8.1 under the name RSASSA-PSS,
     with the following options:
     -   The mask generation function is MGF1 defined by
         [RFC8017](https://tools.ietf.org/html/rfc8017.html) Appendix B.
     -   When creating a signature, the salt length is equal to the length of the hash, or
         the largest possible salt length for the algorithm and key size if that is smaller
         than the hash length.
     -   When verifying a signature, the salt length must be equal to the length of the
         hash, or the largest possible salt length for the algorithm and key size if that is
         smaller than the hash length.
     -   The specified hash algorithm is used to hash the input message, to create the
         salted hash, and for the mask generation.

Note

The PSA_ALG_RSA_PSS_ANY_SALT() algorithm is equivalent to PSA_ALG_RSA_PSS() when creating a signature, but permits any salt length when verifying a signature.

Compatible key types

• PSA_KEY_TYPE_RSA_KEY_PAIR
• PSA_KEY_TYPE_RSA_PUBLIC_KEY (signature verification only)

Definition at line 367 of file algorithm.h.

PSA_ALG_RSA_PSS_ANY_SALT

#define PSA_ALG_RSA_PSS_ANY_SALT

(

hash_alg

)

((psa_algorithm_t)(0x06001300 | ((hash_alg) & 0x000000ff)))

The RSA PSS message signature scheme, with hashing.

This variant permits any salt length for signature verification.

This algorithm can be used with both the message and hash signature functions.

     This algorithm is randomized: each invocation returns a different, equally valid
     signature.

     This is the signature scheme defined by
     [RFC8017](https://tools.ietf.org/html/rfc8017.html) §8.1 under the name RSASSA-PSS,
     with the following options:
     -   The mask generation function is MGF1 defined by
         [RFC8017](https://tools.ietf.org/html/rfc8017.html) Appendix B.
     -   When creating a signature, the salt length is equal to the length of the hash, or
         the largest possible salt length for the algorithm and key size if that is smaller
         than the hash length.
     -   When verifying a signature, any salt length permitted by the RSASSA-PSS signature
         algorithm is accepted.
     -   The specified hash algorithm is used to hash the input message, to create the
         salted hash, and for the mask generation.

Note

The PSA_ALG_RSA_PSS() algorithm is equivalent to PSA_ALG_RSA_PSS_ANY_SALT() when creating a signature, but is strict about the permitted salt length when verifying a signature.

Compatible key types

• PSA_KEY_TYPE_RSA_KEY_PAIR
• PSA_KEY_TYPE_RSA_PUBLIC_KEY (signature verification only)

Definition at line 400 of file algorithm.h.