PSA Key Attributes
The attributes are used to fully describe a cryptographic key: its type, size and what is permitted to do with that key.
Some of the algorithms defined here are deprecated and should not be used without a valid reason. It is at the discretion of the system administrator whether those algorithms are permitted or not.
Notice: not all possible attributes are currently supported by Parsec. Please see the Operations Coverage for an overview of what Parsec currently supports. Some of the attributes might not be supported by some providers as it is not in their interface.
KeyAttributes type
A KeyAttributes type contains the following members:
| Name | Type | Description |
|---|---|---|
key_type | KeyType | Intrinsic category and type of a key |
key_bits | Unsigned integer | Size of a key in bits |
key_policy | KeyPolicy | Policy restricting the permitted usage of the key |
KeyType type
A KeyType type can contain one of the following key types:
RawDataHmacDeriveAesDesCamelliaArc4Chacha20RsaPublicKeyRsaKeyPairEccKeyPairEccPublicKeyDhKeyPairDhPublicKey
RawData type
Not a valid key type for any cryptographic operation but can be used to store arbitrary data in the key store.
The bit size of a raw key must be a non-zero multiple of 8.
Hmac type
HMAC key. The key policy determines which underlying hash algorithm the key can be used for.
The bit size of an HMAC key must be a non-zero multiple of 8. An HMAC key is typically the same size as the output of the underlying hash algorithm. An HMAC key that is longer than the block size of the underlying hash algorithm will be hashed before use.
Derive type
A secret key for derivation. The key policy determines which key derivation algorithm the key can be used for.
The bit size of a secret for key derivation must be a non-zero multiple of 8.
Aes type
Key for a cipher, AEAD or MAC algorithm based on the AES block cipher.
The size of the key is related to the AES algorithm variant. For algorithms except the XTS block cipher mode, the following key sizes are used:
- AES-128 uses a 16-byte key:
key_bits= 128 - AES-192 uses a 24-byte key:
key_bits= 192 - AES-256 uses a 32-byte key:
key_bits= 256
For the XTS block cipher mode, the following key sizes are used:
- AES-128-XTS uses two 16-byte keys:
key_bits= 256 - AES-192-XTS uses two 24-byte keys:
key_bits= 384 - AES-256-XTS uses two 32-byte keys:
key_bits= 512
The AES block cipher is defined in FIPS Publication 197: Advanced Encryption Standard (AES)
FIPS197.
Des type
Key for a cipher or MAC algorithm based on DES or 3DES (Triple-DES).
The size of the key determines which DES algorithm is used:
- Single DES uses an 8-byte key:
key_bits= 64 - 2-key 3DES uses a 16-byte key:
key_bits= 128 - 3-key 3DES uses a 24-byte key:
key_bits= 192
Warning: Single DES and 2-key 3DES are weak and strongly deprecated and are only recommended for decrypting legacy data. 3-key 3DES is weak and deprecated and is only recommended for use in legacy protocols.
The DES and 3DES block ciphers are defined in NIST Special Publication 800-67: Recommendation for the Triple Data Encryption Algorithm (TDEA) Block Cipher SP800-67.
Camellia type
Key for a cipher, AEAD or MAC algorithm based on the Camellia block cipher.
The size of the key is related to the Camellia algorithm variant. For algorithms except the XTS block cipher mode, the following key sizes are used:
- Camellia-128 uses a 16-byte key:
key_bits= 128 - Camellia-192 uses a 24-byte key:
key_bits= 192 - Camellia-256 uses a 32-byte key:
key_bits= 256
For the XTS block cipher mode, the following key sizes are used:
- Camellia-128-XTS uses two 16-byte keys:
key_bits= 256 - Camellia-192-XTS uses two 24-byte keys:
key_bits= 384 - Camellia-256-XTS uses two 32-byte keys:
key_bits= 512
The Camellia block cipher is defined in Specification of Camellia — a 128-bit Block Cipher NTT-CAM and also described in A Description of the Camellia Encryption Algorithm RFC3713.
Arc4 type
Key for the RC4 stream cipher.
The ARC4 cipher supports key sizes between 40 and 2048 bits, that are multiples of 8 (5 to 256 bytes).
Use a Cipher algorithm with Stream Cipher variant to use this
key with the ARC4 cipher.
Warning: The RC4 cipher is weak and deprecated and is only recommended for use in legacy protocols.
Chacha20 type
Key for the ChaCha20 stream cipher or the Chacha20-Poly1305 AEAD algorithm.
The ChaCha20 key size is 256 bits (32 bytes).
- Use Cipher algorithm with Stream Cipher variant to use this key with the ChaCha20 cipher for unauthenticated encryption.
- Use Aead algorithm with ChaCha20-Poly1305 variant to use this key with the ChaCha20 cipher and Poly1305 authenticator for AEAD.
RsaPublicKey type
RSA public key.
RsaKeyPair type
RSA key pair: both the private and public key.
EccKeyPair type
Elliptic curve key pair: both the private and public key. Uses one of the ECC curve family supported.
EccPublicKey type
Elliptic curve public key. Uses one of the ECC curve family supported.
DhKeyPair type
Diffie-Hellman key pair: both the private key and public key. Uses one of the Diffie-Hellman group family supported.
DhPublicKey type
Diffie-Hellman public key. Uses one of the Diffie-Hellman group family supported.
Supported ECC curve families
Enumeration of elliptic curve families supported. They are needed to create an ECC key. The specific
curve used for each family is given by the key_bits field of the key attributes.
- SEC Koblitz curves over prime fields. This family comprises the following curves:
- secp192k1:
key_bits= 192 - secp224k1:
key_bits= 225 - secp256k1:
key_bits= 256
- secp192k1:
- SEC random curves over prime fields. This family comprises the following curves:
- secp192r1:
key_bits= 192 - secp224r1:
key_bits= 224 - secp256r1:
key_bits= 256 - secp384r1:
key_bits= 384 - secp521r1:
key_bits= 512
- secp192r1:
- SEC additional random curves over prime fields. This family comprises the following curves:
- secp160r2:
key_bits= 160 (DEPRECATED)
- secp160r2:
- SEC Koblitz curves over binary fields. This family comprises the following curves:
- sect163k1:
key_bits= 163 (DEPRECATED) - sect233k1:
key_bits= 233 - sect239k1:
key_bits= 239 - sect283k1:
key_bits= 283 - sect409k1:
key_bits= 409 - sect571k1:
key_bits= 571
- sect163k1:
- SEC random curves over binary fields. This family comprises the following curves:
- sect163r1:
key_bits= 163 (DEPRECATED) - sect233r1:
key_bits= 233 - sect283r1:
key_bits= 283 - sect409r1:
key_bits= 409 - sect571r1:
key_bits= 571
- sect163r1:
- SEC additional random curves over binary fields. This family comprises the following curves:
- sect163r2 :
key_bits= 163 (DEPRECATED)
- sect163r2 :
- Brainpool P random curves. This family comprises the following curves:
- brainpoolP160r1:
key_bits= 160 (DEPRECATED) - brainpoolP192r1:
key_bits= 192 - brainpoolP224r1:
key_bits= 224 - brainpoolP256r1:
key_bits= 256 - brainpoolP320r1:
key_bits= 320 - brainpoolP384r1:
key_bits= 384 - brainpoolP512r1:
key_bits= 512
- brainpoolP160r1:
- FRP. Curve used primarily in France and elsewhere in Europe. This family comprises one 256-bit
curve:
- FRP256v1:
key_bits= 256
- FRP256v1:
- Montgomery curves. This family comprises the following Montgomery curves:
- Curve25519:
key_bits= 255 - Curve448:
key_bits= 448
- Curve25519:
Supported DH group families
Enumeration of Diffie Hellman group families supported. They are needed to create a DH key. The
specific group used for each family is given by the key_bits field of the key attributes.
- RFC7919. Finite-field Diffie-Hellman groups defined for TLS in RFC 7919. This family includes groups with the following key sizes (in bits): 2048, 3072, 4096, 6144, 8192. Keys is this group can only be used with the FFDH key agreement algorithm.
KeyPolicy type
Definition of the key policy, what is permitted to do with the key. A KeyPolicy type contains the
following members:
| Name | Type | Description |
|---|---|---|
key_usage_flags | UsageFlags | Usage flags for the key |
key_algorithm | Algorithm | Permitted algorithms to be used with the key |
UsageFlags type
Definition of the usage flags. They encode what kind of operations are permitted on the key. A
UsageFlags type contains the following members:
| Name | Type | Description |
|---|---|---|
export | Boolean | Permission to export the key |
copy | Boolean | Permission to copy the key |
cache | Boolean | Permission for the implementation to cache the key |
encrypt | Boolean | Permission to encrypt a message with the key |
decrypt | Boolean | Permission to decrypt a message with the key |
sign_message | Boolean | Permission to sign a message with the key |
verify_message | Boolean | Permission to verify a message with the key |
sign_hash | Boolean | Permission to sign a hash with the key |
verify_hash | Boolean | Permission to verify a hash with the key |
derive | Boolean | Permission to derive other keys from this key |
sign message usage
Permission to sign a message with the key.
This flag allows the key to be used for a MAC calculation operation or for an asymmetric message signature operation, if otherwise permitted by the key’s type and policy. The flag must be present on keys used with the following APIs:
- PsaMacCompute
- PsaSignMessage
For a key pair, this concerns the private key.
verify message usage
Permission to verify a message signature with the key.
This flag allows the key to be used for a MAC verification operation or for an asymmetric message signature verification operation, if otherwise permitted by the key’s type and policy. The flag must be present on keys used with the following APIs:
- PsaMacVerify
- PsaVerifyMessage
For a key pair, this concerns the public key.
sign hash usage
Permission to sign a message hash with the key.
This flag allows the key to be used to sign a message hash as part of an asymmetric signature operation, if otherwise permitted by the key’s type and policy. The flag must be present on keys used when calling PsaSignHash.
This flag automatically sets sign_message: if an application sets the flag sign_hash when
creating a key, then the key always has the permissions conveyed by sign_message. For a key pair,
this concerns the private key.
verify hash usage
Permission to verify a message hash with the key.
This flag allows the key to be used to verify a message hash as part of an asymmetric signature verification operation, if otherwise permitted by the key’s type and policy. The flag must be present on keys used when calling PsaVerifyHash.
This flag automatically sets verify_message: if an application sets the flag verify_hash when
creating a key, then the key always has the permissions conveyed by verify_message.
For a key pair, this concerns the public key.
Copyright 2019 Contributors to the Parsec project.