# 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:

`RawData`

`Hmac`

`Derive`

`Aes`

`Des`

`Camellia`

`Arc4`

`Chacha20`

`RsaPublicKey`

`RsaKeyPair`

`EccKeyPair`

`EccPublicKey`

`DhKeyPair`

`DhPublicKey`

### 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.*