9.6. Key management functions¶
9.6.1. Key creation¶
New keys can be created in the following ways:
psa_import_key()
creates a key from a data buffer provided by the application.psa_generate_key()
creates a key from randomly generated data.psa_key_derivation_output_key()
creates a key from data generated by a pseudorandom derivation process. See Key derivation.psa_key_agreement()
creates a key from the shared secret result of a key agreement process. See Key agreement.psa_copy_key()
duplicates an existing key with a different lifetime or with a more restrictive usage policy.
When creating a key, the attributes for the new key are specified in a psa_key_attributes_t
object. Each key creation function defines how it uses the attributes.
Note
The attributes for a key are immutable after the key has been created.
The application must set the key algorithm policy and the appropriate key usage flags in the attributes in order for the key to be used in any cryptographic operations.
psa_import_key
(function)¶
Import a key in binary format.
psa_status_t psa_import_key(const psa_key_attributes_t * attributes, const uint8_t * data, size_t data_length, psa_key_id_t * key);
Parameters
attributes
The attributes for the new key. This function uses the attributes as follows:
The key type is required, and determines how the
data
buffer is interpreted.The key size is always determined from the
data
buffer. If the key size inattributes
is nonzero, it must be equal to the size determined fromdata
.The key permitted-algorithm policy is required for keys that will be used for a cryptographic operation, see Permitted algorithms.
The key usage flags define what operations are permitted with the key, see Key usage flags.
The key lifetime and identifier are required for a persistent key.
Note
This is an input parameter: it is not updated with the final key attributes. The final attributes of the new key can be queried by calling
psa_get_key_attributes()
with the key’s identifier.data
Buffer containing the key data. The content of this buffer is interpreted according to the type declared in
attributes
. All implementations must support at least the format described in Key formats for the chosen type. Implementations can support other formats, but be conservative in interpreting the key data: it is recommended that implementations reject content if it might be erroneous, for example, if it is the wrong type or is truncated.data_length
Size of the
data
buffer in bytes.key
On success, an identifier for the newly created key.
PSA_KEY_ID_NULL
on failure.
Returns: psa_status_t
PSA_SUCCESS
Success. If the key is persistent, the key material and the key’s metadata have been saved to persistent storage.
PSA_ERROR_BAD_STATE
The library requires initializing by a call to
psa_crypto_init()
.PSA_ERROR_NOT_PERMITTED
The implementation does not permit creating a key with the specified attributes due to some implementation-specific policy.
PSA_ERROR_ALREADY_EXISTS
This is an attempt to create a persistent key, and there is already a persistent key with the given identifier.
PSA_ERROR_INVALID_ARGUMENT
The following conditions can result in this error:
The key type is invalid.
The key size is nonzero, and is incompatible with the key data in
data
.The key lifetime is invalid.
The key identifier is not valid for the key lifetime.
The key usage flags include invalid values.
The key’s permitted-usage algorithm is invalid.
The key attributes, as a whole, are invalid.
The key data is not correctly formatted for the key type.
PSA_ERROR_NOT_SUPPORTED
The key attributes, as a whole, are not supported, either by the implementation in general or in the specified storage location.
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_INSUFFICIENT_STORAGE
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_DATA_CORRUPT
PSA_ERROR_DATA_INVALID
Description
This function supports any output from psa_export_key()
. Refer to Key formats for the format of keys.
The key data determines the key size. The attributes can optionally specify a key size; in this case it must match the size determined from the key data. A key size of 0
in 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 defines a single format for each key type. Implementations can optionally support other formats in addition to the standard format. It is recommended that implementations that support other formats ensure that the formats are clearly unambiguous, to minimize the risk that an invalid input is accidentally interpreted according to a different format.
Note
The Crypto API does not support asymmetric private key objects outside of a key pair. To import a private key, the attributes
must specify the corresponding key pair type. Depending on the key type, either the import format contains the public key data or the implementation will reconstruct the public key from the private key as needed.
psa_generate_key
(function)¶
Generate a key or key pair.
psa_status_t psa_generate_key(const psa_key_attributes_t * attributes, psa_key_id_t * key);
Parameters
attributes
The attributes for the new key. This function uses the attributes as follows:
The key type is required. It cannot be an asymmetric public key.
The key size is required. It must be a valid size for the key type.
The key permitted-algorithm policy is required for keys that will be used for a cryptographic operation, see Permitted algorithms.
The key usage flags define what operations are permitted with the key, see Key usage flags.
The key lifetime and identifier are required for a persistent key.
Note
This is an input parameter: it is not updated with the final key attributes. The final attributes of the new key can be queried by calling
psa_get_key_attributes()
with the key’s identifier.key
On success, an identifier for the newly created key.
PSA_KEY_ID_NULL
on failure.
Returns: psa_status_t
PSA_SUCCESS
Success. If the key is persistent, the key material and the key’s metadata have been saved to persistent storage.
PSA_ERROR_BAD_STATE
The library requires initializing by a call to
psa_crypto_init()
.PSA_ERROR_NOT_PERMITTED
The implementation does not permit creating a key with the specified attributes due to some implementation-specific policy.
PSA_ERROR_ALREADY_EXISTS
This is an attempt to create a persistent key, and there is already a persistent key with the given identifier.
PSA_ERROR_INVALID_ARGUMENT
The following conditions can result in this error:
The key type is invalid, or is an asymmetric public key type.
The key size is not valid for the key type.
The key lifetime is invalid.
The key identifier is not valid for the key lifetime.
The key usage flags include invalid values.
The key’s permitted-usage algorithm is invalid.
The key attributes, as a whole, are invalid.
PSA_ERROR_NOT_SUPPORTED
The key attributes, as a whole, are not supported, either by the implementation in general or in the specified storage location.
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_INSUFFICIENT_STORAGE
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_DATA_CORRUPT
PSA_ERROR_DATA_INVALID
Description
The key is generated randomly. Its location, policy, type and size are taken from 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.
psa_copy_key
(function)¶
Make a copy of a key.
psa_status_t psa_copy_key(psa_key_id_t source_key, const psa_key_attributes_t * attributes, psa_key_id_t * target_key);
Parameters
source_key
The key to copy. It must permit the usage
PSA_KEY_USAGE_COPY
. If a private or secret key is being copied outside of a secure element it must also permitPSA_KEY_USAGE_EXPORT
.attributes
The attributes for the new key. This function uses the attributes as follows:
The key type and size can be
0
. If either is nonzero, it must match the corresponding attribute of the source key.The key location (the lifetime and, for persistent keys, the key identifier) is used directly.
The key policy (usage flags and permitted algorithm) are combined from the source key and
attributes
so that both sets of restrictions apply, as described in the documentation of this function.
Note
This is an input parameter: it is not updated with the final key attributes. The final attributes of the new key can be queried by calling
psa_get_key_attributes()
with the key’s identifier.target_key
On success, an identifier for the newly created key.
PSA_KEY_ID_NULL
on failure.
Returns: psa_status_t
PSA_SUCCESS
Success. If the new key is persistent, the key material and the key’s metadata have been saved to persistent storage.
PSA_ERROR_BAD_STATE
The library requires initializing by a call to
psa_crypto_init()
.PSA_ERROR_INVALID_HANDLE
source_key
is not a valid key identifier.PSA_ERROR_NOT_PERMITTED
The following conditions can result in this error:
source_key
does not have thePSA_KEY_USAGE_COPY
usage flag.source_key
does not have thePSA_KEY_USAGE_EXPORT
usage flag, and the location oftarget_key
is outside the security boundary of thesource_key
storage location.The implementation does not permit creating a key with the specified attributes due to some implementation-specific policy.
PSA_ERROR_ALREADY_EXISTS
This is an attempt to create a persistent key, and there is already a persistent key with the given identifier.
PSA_ERROR_INVALID_ARGUMENT
The following conditions can result in this error:
attributes
specifies a key type or key size which does not match the attributes ofsource key
.The lifetime or identifier in
attributes
are invalid.The key policies from
source_key
and those specified inattributes
are incompatible.
PSA_ERROR_NOT_SUPPORTED
The following conditions can result in this error:
The
source key
storage location does not support copying to the target key’s storage location.The key attributes, as a whole, are not supported in the target key’s storage location.
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_INSUFFICIENT_STORAGE
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_DATA_CORRUPT
PSA_ERROR_DATA_INVALID
Description
Copy key material from one location to another.
This function is primarily useful to copy a key from one location to another, as it populates a key using the material from another key which can have a different lifetime.
This function can 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 can only be used in a way that conforms to both the policy of the original key and the policy specified in the 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
attributes
.If both permit the same algorithm or wildcard-based algorithm, the resulting key has the same permitted algorithm.
If either of the policies permits an algorithm and the other policy permits a wildcard-based permitted algorithm that includes this algorithm, the resulting key uses this permitted algorithm.
If the policies do not permit 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.
9.6.2. Key destruction¶
psa_destroy_key
(function)¶
Destroy a key.
psa_status_t psa_destroy_key(psa_key_id_t key);
Parameters
key
Identifier of the key to erase. If this is
PSA_KEY_ID_NULL
, do nothing and returnPSA_SUCCESS
.
Returns: psa_status_t
PSA_SUCCESS
Success. If
key
was a valid key identifier, then the key material that it referred to has been erased. Alternatively,key
wasPSA_KEY_ID_NULL
.PSA_ERROR_BAD_STATE
The library requires initializing by a call to
psa_crypto_init()
.PSA_ERROR_INVALID_HANDLE
key
is neither a valid key identifier, norPSA_KEY_ID_NULL
.PSA_ERROR_NOT_PERMITTED
The key cannot be erased because it is read-only, either due to a policy or due to physical restrictions.
PSA_ERROR_COMMUNICATION_FAILURE
There was an failure in communication with the cryptoprocessor. The key material might still be present in the cryptoprocessor.
PSA_ERROR_CORRUPTION_DETECTED
An unexpected condition which is not a storage corruption or a communication failure occurred. The cryptoprocessor might have been compromised.
PSA_ERROR_STORAGE_FAILURE
The storage operation failed. Implementations must make a best effort to erase key material even in this situation, however, it might be impossible to guarantee that the key material is not recoverable in such cases.
PSA_ERROR_DATA_CORRUPT
The storage is corrupted. Implementations must make a best effort to erase key material even in this situation, however, it might be impossible to guarantee that the key material is not recoverable in such cases.
PSA_ERROR_DATA_INVALID
Description
This function destroys a key from both volatile memory and, if applicable, non-volatile storage. Implementations must make a best effort to ensure that that the key material cannot be recovered.
This function also erases any metadata such as policies and frees resources associated with the key.
Destroying the key makes the key identifier invalid, and the key identifier must not be used again by the application.
If a key is currently in use in a multi-part operation, then destroying the key will cause the multi-part operation to fail.
psa_purge_key
(function)¶
Remove non-essential copies of key material from memory.
psa_status_t psa_purge_key(psa_key_id_t key);
Parameters
key
Identifier of the key to purge.
Returns: psa_status_t
PSA_SUCCESS
Success. The key material has been removed from memory, if the key material is not currently required.
PSA_ERROR_BAD_STATE
The library requires initializing by a call to
psa_crypto_init()
.PSA_ERROR_INVALID_HANDLE
key
is not a valid key identifier.PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_DATA_CORRUPT
PSA_ERROR_DATA_INVALID
Description
For keys that have been created with the PSA_KEY_USAGE_CACHE
usage flag, an implementation is permitted to make additional copies of the key material that are not in storage and not for the purpose of ongoing operations.
This function will remove these extra copies of the key material from memory.
This function is not required to remove key material from memory in any of the following situations:
The key is currently in use in a cryptographic operation.
The key is volatile.
See also Managing key material.
9.6.3. Key export¶
psa_export_key
(function)¶
Export a key in binary format.
psa_status_t psa_export_key(psa_key_id_t key, uint8_t * data, size_t data_size, size_t * data_length);
Parameters
key
Identifier of the key to export. It must permit the usage
PSA_KEY_USAGE_EXPORT
, unless it is a public key.data
Buffer where the key data is to be written.
data_size
Size of the
data
buffer in bytes. This must be appropriate for the key:The required output size is
PSA_EXPORT_KEY_OUTPUT_SIZE
(
type
,
bits
)
wheretype
is the key type andbits
is the key size in bits.PSA_EXPORT_KEY_PAIR_MAX_SIZE
evaluates to the maximum output size of any supported key pair.PSA_EXPORT_PUBLIC_KEY_MAX_SIZE
evaluates to the maximum output size of any supported public key.This API defines no maximum size for symmetric keys. Arbitrarily large data items can be stored in the key store, for example certificates that correspond to a stored private key or input material for key derivation.
data_length
On success, the number of bytes that make up the key data.
Returns: psa_status_t
PSA_SUCCESS
Success. The first
(*data_length)
bytes ofdata
contain the exported key.PSA_ERROR_BAD_STATE
The library requires initializing by a call to
psa_crypto_init()
.PSA_ERROR_INVALID_HANDLE
key
is not a valid key identifier.PSA_ERROR_NOT_PERMITTED
The key does not have the
PSA_KEY_USAGE_EXPORT
flag.PSA_ERROR_BUFFER_TOO_SMALL
The size of the
data
buffer is too small.PSA_EXPORT_KEY_OUTPUT_SIZE()
orPSA_EXPORT_KEY_PAIR_MAX_SIZE
can be used to determine a sufficient buffer size.PSA_ERROR_NOT_SUPPORTED
The following conditions can result in this error:
The key’s storage location does not support export of the key.
The implementation does not support export of keys with this key type.
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_DATA_CORRUPT
PSA_ERROR_DATA_INVALID
Description
The output of this function can be passed to psa_import_key()
to create an equivalent object.
If the implementation of psa_import_key()
supports other formats beyond the format specified here, the output from psa_export_key()
must use the representation specified in Key formats, not the originally imported representation.
For standard key types, the output format is defined in Key formats.
The policy on the key must have the usage flag PSA_KEY_USAGE_EXPORT
set.
psa_export_public_key
(function)¶
Export a public key or the public part of a key pair in binary format.
psa_status_t psa_export_public_key(psa_key_id_t key, uint8_t * data, size_t data_size, size_t * data_length);
Parameters
key
Identifier of the key to export.
data
Buffer where the key data is to be written.
data_size
Size of the
data
buffer in bytes. This must be appropriate for the key:The required output size is
PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE
(
type
,
bits
)
wheretype
is the key type andbits
is the key size in bits.PSA_EXPORT_PUBLIC_KEY_MAX_SIZE
evaluates to the maximum output size of any supported public key or public part of a key pair.
data_length
On success, the number of bytes that make up the key data.
Returns: psa_status_t
PSA_SUCCESS
Success. The first
(*data_length)
bytes ofdata
contain the exported public key.PSA_ERROR_BAD_STATE
The library requires initializing by a call to
psa_crypto_init()
.PSA_ERROR_INVALID_HANDLE
key
is not a valid key identifier.PSA_ERROR_BUFFER_TOO_SMALL
The size of the
data
buffer is too small.PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE()
orPSA_EXPORT_PUBLIC_KEY_MAX_SIZE
can be used to determine a sufficient buffer size.PSA_ERROR_INVALID_ARGUMENT
The key is neither a public key nor a key pair.
PSA_ERROR_NOT_SUPPORTED
The following conditions can result in this error:
The key’s storage location does not support export of the key.
The implementation does not support export of keys with this key type.
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_DATA_CORRUPT
PSA_ERROR_DATA_INVALID
Description
The output of this function can be passed to psa_import_key()
to create an object that is equivalent to the public key.
If the implementation of psa_import_key()
supports other formats beyond the format specified here, the output from psa_export_public_key()
must use the representation specified in Key formats, not the originally imported representation.
For standard key types, the output format is defined in Key formats.
Exporting a public key object or the public part of a key pair is always permitted, regardless of the key’s usage flags.
PSA_EXPORT_KEY_OUTPUT_SIZE
(macro)¶
Sufficient output buffer size for psa_export_key()
.
#define PSA_EXPORT_KEY_OUTPUT_SIZE(key_type, key_bits) \ /* implementation-defined value */
Parameters
key_type
A supported key type.
key_bits
The size of the key in bits.
Returns
If the parameters are valid and supported, return a buffer size in bytes that guarantees that psa_export_key()
or psa_export_public_key()
will not fail with PSA_ERROR_BUFFER_TOO_SMALL
. If the parameters are a valid combination that is not supported by the implementation, this macro must return either a sensible size or 0
. If the parameters are not valid, the return value is unspecified.
Description
The following code illustrates how to allocate enough memory to export a key by querying the key type and size at runtime.
psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT; psa_status_t status; status = psa_get_key_attributes(key, &attributes); if (status != PSA_SUCCESS) handle_error(...); psa_key_type_t key_type = psa_get_key_type(&attributes); size_t key_bits = psa_get_key_bits(&attributes); size_t buffer_size = PSA_EXPORT_KEY_OUTPUT_SIZE(key_type, key_bits); psa_reset_key_attributes(&attributes); uint8_t *buffer = malloc(buffer_size); if (buffer == NULL) handle_error(...); size_t buffer_length; status = psa_export_key(key, buffer, buffer_size, &buffer_length); if (status != PSA_SUCCESS) handle_error(...);
See also PSA_EXPORT_KEY_PAIR_MAX_SIZE
and PSA_EXPORT_PUBLIC_KEY_MAX_SIZE
.
PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE
(macro)¶
Sufficient output buffer size for psa_export_public_key()
.
#define PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE(key_type, key_bits) \ /* implementation-defined value */
Parameters
key_type
A public key or key pair key type.
key_bits
The size of the key in bits.
Returns
If the parameters are valid and supported, return a buffer size in bytes that guarantees that psa_export_public_key()
will not fail with PSA_ERROR_BUFFER_TOO_SMALL
. If the parameters are a valid combination that is not supported by the implementation, this macro must return either a sensible size or 0
. If the parameters are not valid, the return value is unspecified.
If the parameters are valid and supported, it is recommended that this macro returns the same result as PSA_EXPORT_KEY_OUTPUT_SIZE
(
PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR
(
key_type
),
key_bits
)
.
Description
The following code illustrates how to allocate enough memory to export a public key by querying the key type and size at runtime.
psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT; psa_status_t status; status = psa_get_key_attributes(key, &attributes); if (status != PSA_SUCCESS) handle_error(...); psa_key_type_t key_type = psa_get_key_type(&attributes); size_t key_bits = psa_get_key_bits(&attributes); size_t buffer_size = PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE(key_type, key_bits); psa_reset_key_attributes(&attributes); uint8_t *buffer = malloc(buffer_size); if (buffer == NULL) handle_error(...); size_t buffer_length; status = psa_export_public_key(key, buffer, buffer_size, &buffer_length); if (status != PSA_SUCCESS) handle_error(...);
See also PSA_EXPORT_PUBLIC_KEY_MAX_SIZE
.
PSA_EXPORT_KEY_PAIR_MAX_SIZE
(macro)¶
Sufficient buffer size for exporting any asymmetric key pair.
#define PSA_EXPORT_KEY_PAIR_MAX_SIZE /* implementation-defined value */
This value must be a sufficient buffer size when calling psa_export_key()
to export any asymmetric key pair that is supported by the implementation, regardless of the exact key type and key size.
See also PSA_EXPORT_KEY_OUTPUT_SIZE()
.
PSA_EXPORT_PUBLIC_KEY_MAX_SIZE
(macro)¶
Sufficient buffer size for exporting any asymmetric public key.
#define PSA_EXPORT_PUBLIC_KEY_MAX_SIZE /* implementation-defined value */
This value must be a sufficient buffer size when calling psa_export_key()
or psa_export_public_key()
to export any asymmetric public key that is supported by the implementation, regardless of the exact key type and key size.
See also PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE()
.
9.6.4. Key formats¶
This section defines the format of the key data that an implementation is required to support when importing and exporting keys. Keys can be imported using psa_import_key()
, and exported using psa_export_key()
or psa_export_public_key()
. The public key formats are also used for the key agreement functions, see Key agreement.
Key type |
Key type details and format |
---|---|
DES |
The key data consists of 8 bytes. The parity bits must be correct. |
2-key 3DES 3-key 3DES |
The key data is the concatenation of the two or three DES keys. |
Other symmetric keys
|
The key data is the raw bytes of the key. |
RSA key pair |
The key data is the non-encrypted DER encoding of the representation defined by in PKCS #1: RSA Cryptography Specifications Version 2.2 [RFC8017] as RSAPrivateKey ::= SEQUENCE {
version INTEGER, -- must be 0
modulus INTEGER, -- n
publicExponent INTEGER, -- e
privateExponent INTEGER, -- d
prime1 INTEGER, -- p
prime2 INTEGER, -- q
exponent1 INTEGER, -- d mod (p-1)
exponent2 INTEGER, -- d mod (q-1)
coefficient INTEGER, -- (inverse of q) mod p
}
Note Although it is possible to define an RSA key pair or private key using a subset of these elements, the output from |
RSA public key |
The key data is the DER encoding of the representation defined by Algorithms and Identifiers for the Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile [RFC3279] §2.3.1 as RSAPublicKey ::= SEQUENCE {
modulus INTEGER, -- n
publicExponent INTEGER } -- e
|
Weierstrass Elliptic curve key pair |
The key data is the content of the This is a \(\lceil{m/8}\rceil\)-byte string in big-endian order, where \(m\) is the key size in bits. |
Weierstrass Elliptic curve public key |
The key data is the uncompressed representation of an elliptic curve point as an octet string defined in SEC 1: Elliptic Curve Cryptography [SEC1] §2.3.3. If \(m\) is the bit size associated with the curve, i.e. the bit size of \(q\) for a curve over \(\mathbb{F}_q\), then the representation of point \(P\) consists of:
|
Montgomery Elliptic curve key pair |
The key data is the scalar value of the ‘private key’ in little-endian order as defined by Elliptic Curves for Security [RFC7748] §6. The value must have the forced bits set to zero or one as specified by This is a \(\lceil{m/8}\rceil\)-byte string where \(m\) is the key size in bits. This is 32 bytes for Curve25519, and 56 bytes for Curve448. |
Montgomery Elliptic curve public key |
The key data is the scalar value of the ‘public key’ in little-endian order as defined by Elliptic Curves for Security [RFC7748] §6. This is a \(\lceil{m/8}\rceil\)-byte string where \(m\) is the key size in bits.
|
Twisted Edwards Elliptic curve key pair |
The key data is the private key, as defined by Edwards-Curve Digital Signature Algorithm (EdDSA) [RFC8032]. This is a 32-byte string for Edwards25519, and a 57-byte string for Edwards448. |
Twisted Edwards Elliptic curve public key |
The key data is the public key, as defined by Edwards-Curve Digital Signature Algorithm (EdDSA) [RFC8032]. This is a 32-byte string for Edwards25519, and a 57-byte string for Edwards448. |
Finite-field Diffie-Hellman key pair |
The key data is the representation of the private key \(x\) as a big-endian byte string. The length of the byte string is the private key size in bytes, and leading zeroes are not stripped. |
Finite-field Diffie-Hellman public key |
The key data is the representation of the public key \(y = g^x\!\mod p\) as a big-endian byte string. The length of the byte string is the length of the base prime \(p\) in bytes. |