Skip to content

Commit 8fab2a2

Browse files
athoelkeathoelke
authored
Merge pull request #184 from athoelke/crypto-key-details
Reorganise key format and key derivation information
2 parents 18c5e10 + b91894a commit 8fab2a2

File tree

6 files changed

+611
-504
lines changed

6 files changed

+611
-504
lines changed

‎doc/crypto/api/keys/management.rst‎

Lines changed: 6 additions & 193 deletions
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,7 @@ When creating a key, the attributes for the new key are specified in a `psa_key_
5050
.. param:: const uint8_t * data
5151
Buffer containing the key data.
5252
The content of this buffer is interpreted according to the type declared in ``attributes``.
53-
All implementations must support at least the format described in :secref:`key_formats` for the chosen type.
53+
All implementations must support at least the format described in the *Key format* section of the chosen key type.
5454
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.
5555
.. param:: size_t data_length
5656
Size of the ``data`` buffer in bytes.
@@ -88,7 +88,7 @@ When creating a key, the attributes for the new key are specified in a `psa_key_
8888
.. retval:: PSA_ERROR_BAD_STATE
8989
The library requires initializing by a call to `psa_crypto_init()`.
9090

91-
This function supports any output from `psa_export_key()`. Refer to :secref:`key_formats` for the format of keys.
91+
This function supports any output from `psa_export_key()`. Each key type in :secref:`key-types` describes the expected format of keys.
9292

9393
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.
9494

@@ -366,10 +366,9 @@ Key export
366366

367367
The output of this function can be passed to `psa_import_key()` to create an equivalent object.
368368

369-
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 :secref:`key_formats`, not the originally imported representation.
370-
371-
For standard key types, the output format is defined in :secref:`key_formats`.
369+
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 :secref:`key-types`, not the originally imported representation.
372370

371+
For standard key types, the output format is defined in the relevant *Key format* section in :secref:`key-types`.
373372
The policy on the key must have the usage flag `PSA_KEY_USAGE_EXPORT` set.
374373

375374
.. function:: psa_export_public_key
@@ -419,9 +418,9 @@ Key export
419418

420419
The output of this function can be passed to `psa_import_key()` to create an object that is equivalent to the public key.
421420

422-
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 :secref:`key_formats`, not the originally imported representation.
421+
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 :secref:`key-types`, not the originally imported representation.
423422

424-
For standard key types, the output format is defined in :secref:`key_formats`.
423+
For standard key types, the output format is defined in the relevant *Key format* section in :secref:`key-types`.
425424

426425
Exporting a public key object or the public part of a key pair is always permitted, regardless of the key's usage flags.
427426

@@ -530,189 +529,3 @@ Key export
530529
This value must be a sufficient buffer size when calling `psa_export_key()` or `psa_export_public_key()` to export any asymmetric key pair or public key that is supported by the implementation, regardless of the exact key type and key size.
531530

532531
See also `PSA_EXPORT_KEY_PAIR_MAX_SIZE`, `PSA_EXPORT_PUBLIC_KEY_MAX_SIZE`, and `PSA_EXPORT_KEY_OUTPUT_SIZE()`.
533-
534-
535-
.. _key_formats:
536-
537-
Key formats
538-
-----------
539-
540-
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 :secref:`key-agreement`.
541-
542-
.. list-table:: Standard key formats
543-
:name: std-key-formats
544-
:class: longtable
545-
:header-rows: 1
546-
:widths: 2,5
547-
548-
* - Key type
549-
- Key type details and format
550-
551-
* - DES
552-
- `PSA_KEY_TYPE_DES`, 64 bits.
553-
554-
The key data consists of 8 bytes. The parity bits must be correct.
555-
556-
* - 2-key 3DES
557-
558-
3-key 3DES
559-
- `PSA_KEY_TYPE_DES`, 128 bits.
560-
561-
`PSA_KEY_TYPE_DES`, 192 bits.
562-
563-
The key data is the concatenation of the two or three DES keys.
564-
565-
* - Other symmetric keys
566-
567-
* AES
568-
* ARC4
569-
* ARIA
570-
* CAMELLIA
571-
* ChaCha20
572-
* HMAC
573-
* SM4
574-
* Secrets for derivation
575-
* Password hashes
576-
577-
- `PSA_KEY_TYPE_AES`
578-
579-
`PSA_KEY_TYPE_ARC4`
580-
581-
`PSA_KEY_TYPE_ARIA`
582-
583-
`PSA_KEY_TYPE_CAMELLIA`
584-
585-
`PSA_KEY_TYPE_CHACHA20`
586-
587-
`PSA_KEY_TYPE_HMAC`
588-
589-
`PSA_KEY_TYPE_SM4`
590-
591-
`PSA_KEY_TYPE_DERIVE`
592-
593-
`PSA_KEY_TYPE_PASSWORD_HASH`
594-
595-
The key data is the raw bytes of the key.
596-
597-
* - RSA key pair
598-
- `PSA_KEY_TYPE_RSA_KEY_PAIR`
599-
600-
The key data is the non-encrypted DER encoding of the representation defined by in :RFC-title:`8017` as ``RSAPrivateKey``, version ``0``.
601-
602-
.. code-block:: none
603-
604-
RSAPrivateKey ::= SEQUENCE {
605-
version INTEGER, -- must be 0
606-
modulus INTEGER, -- n
607-
publicExponent INTEGER, -- e
608-
privateExponent INTEGER, -- d
609-
prime1 INTEGER, -- p
610-
prime2 INTEGER, -- q
611-
exponent1 INTEGER, -- d mod (p-1)
612-
exponent2 INTEGER, -- d mod (q-1)
613-
coefficient INTEGER, -- (inverse of q) mod p
614-
}
615-
616-
.. note::
617-
618-
Although it is possible to define an RSA key pair or private key using a subset of these elements, the output from `psa_export_key()` for an RSA key pair must include all of these elements.
619-
620-
* - RSA public key
621-
- `PSA_KEY_TYPE_RSA_PUBLIC_KEY`
622-
623-
The key data is the DER encoding of the representation defined by :RFC-title:`3279#2.3.1` as ``RSAPublicKey``.
624-
625-
.. code-block:: none
626-
627-
RSAPublicKey ::= SEQUENCE {
628-
modulus INTEGER, -- n
629-
publicExponent INTEGER } -- e
630-
631-
* - Weierstrass Elliptic curve key pair
632-
- :code:`PSA_KEY_TYPE_ECC_KEY_PAIR(ecc_family)`, where ``ecc_family`` designates a Weierstrass curve family.
633-
634-
The key data is the content of the ``privateKey`` field of the ``ECPrivateKey`` format defined by :RFC-title:`5915`.
635-
636-
This is a :math:`\lceil{m/8}\rceil`-byte string in big-endian order, where :math:`m` is the key size in bits.
637-
638-
* - Weierstrass Elliptic curve public key
639-
- :code:`PSA_KEY_TYPE_ECC_PUBLIC_KEY(ecc_family)`, where ``ecc_family`` designates a Weierstrass curve family.
640-
641-
The key data is the uncompressed representation of an elliptic curve point as an octet string defined in :cite-title:`SEC1` §2.3.3.
642-
If :math:`m` is the bit size associated with the curve, i.e. the bit size of :math:`q` for a curve over :math:`\mathbb{F}_q`, then the representation of point :math:`P` consists of:
643-
644-
* The byte ``0x04``;
645-
* :math:`x_P` as a :math:`\lceil{m/8}\rceil`-byte string, big-endian;
646-
* :math:`y_P` as a :math:`\lceil{m/8}\rceil`-byte string, big-endian.
647-
648-
* - Montgomery Elliptic curve key pair
649-
- :code:`PSA_KEY_TYPE_ECC_KEY_PAIR(PSA_ECC_FAMILY_MONTGOMERY)`
650-
651-
The key data is the scalar value of the 'private key' in little-endian order as defined by :RFC-title:`7748#6`. The value must have the forced bits set to zero or one as specified by ``decodeScalar25519()`` and ``decodeScalar448()`` in :RFC:`7748#5`.
652-
653-
This is a :math:`\lceil{m/8}\rceil`-byte string where :math:`m` is the key size in bits. This is 32 bytes for Curve25519, and 56 bytes for Curve448.
654-
655-
* - Montgomery Elliptic curve public key
656-
- :code:`PSA_KEY_TYPE_ECC_PUBLIC_KEY(PSA_ECC_FAMILY_MONTGOMERY)`
657-
658-
The key data is the scalar value of the 'public key' in little-endian order as defined by :RFC-title:`7748#6`. This is a :math:`\lceil{m/8}\rceil`-byte string where :math:`m` is the key size in bits.
659-
660-
* This is 32 bytes for Curve25519, computed as ``X25519(private_key, 9)``.
661-
* This is 56 bytes for Curve448, computed as ``X448(private_key, 5)``.
662-
663-
* - Twisted Edwards Elliptic curve key pair
664-
- :code:`PSA_KEY_TYPE_ECC_KEY_PAIR(PSA_ECC_FAMILY_TWISTED_EDWARDS)`
665-
666-
The key data is the private key, as defined by :RFC-title:`8032`.
667-
668-
This is a 32-byte string for Edwards25519, and a 57-byte string for Edwards448.
669-
670-
* - Twisted Edwards Elliptic curve public key
671-
- :code:`PSA_KEY_TYPE_ECC_PUBLIC_KEY(PSA_ECC_FAMILY_TWISTED_EDWARDS)`
672-
673-
The key data is the public key, as defined by :RFC-title:`8032`.
674-
675-
This is a 32-byte string for Edwards25519, and a 57-byte string for Edwards448.
676-
677-
* - Finite-field Diffie-Hellman key pair
678-
- :code:`PSA_KEY_TYPE_DH_KEY_PAIR(dh_family)` where ``dh_family`` designates any Diffie-Hellman family.
679-
680-
The key data is the representation of the private key :math:`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.
681-
682-
* - Finite-field Diffie-Hellman public key
683-
- :code:`PSA_KEY_TYPE_DH_PUBLIC_KEY(dh_family)` where ``dh_family`` designates any Diffie-Hellman family.
684-
685-
The key data is the representation of the public key :math:`y = g^x\!\mod p` as a big-endian byte string. The length of the byte string is the length of the base prime :math:`p` in bytes.
686-
687-
* - SPAKE2+ key pair
688-
- :code:`PSA_KEY_TYPE_SPAKE2P_KEY_PAIR(ecc_family)` where ``ecc_family`` designates an elliptic curve family.
689-
690-
The key consists of the two values :math:`w0` and :math:`w1`, which result from the SPAKE2+ registration phase, see :secref:`spake2p-registration`.
691-
:math:`w0` and :math:`w1` are scalars in the same range as an elliptic curve private key from the group used as the SPAKE2+ primitive group.
692-
693-
For the |API|, the default format for a SPAKE2+ key pair is the concatenation of the formatted values for :math:`w0` and :math:`w1`, using the standard formats for elliptic curve keys used by the |API|.
694-
For example, for SPAKE2+ over P-256 (secp256r1), the output from :code:`psa_export_key()` would be the concatenation of:
695-
696-
* The P-256 private key :math:`w0`.
697-
This is a 32-byte big-endian encoding of the integer :math:`w0`.
698-
* The P-256 private key :math:`w1`.
699-
This is a 32-byte big-endian encoding of the integer :math:`w1`.
700-
701-
* - SPAKE2+ public key
702-
- :code:`PSA_KEY_TYPE_SPAKE2P_PUBLIC_KEY(ecc_family)` where ``ecc_family`` designates an elliptic curve family.
703-
704-
The public key consists of the two values :math:`w0` and :math:`L`, which result from the SPAKE2+ registration phase, see :secref:`spake2p-registration`.
705-
:math:`w0` is a scalar in the same range as a elliptic curve private key from the group used as the SPAKE2+ primitive group.
706-
:math:`L` is a point on the curve, similar to a public key from the same group, corresponding to the :math:`w1` value in the key pair.
707-
708-
For the |API|, the default format for a SPAKE2+ public key is the concatenation of the formatted values for :math:`w0` and :math:`L`, using the standard formats for elliptic curve keys used by the |API|.
709-
For example, for SPAKE2+ over P-256 (secp256r1), the output from :code:`psa_export_public_key()` would be the concatenation of:
710-
711-
* The P-256 private key :math:`w0`.
712-
This is a 32-byte big-endian encoding of the integer :math:`w0`.
713-
* The P-256 public key :math:`L`.
714-
This is a 65-byte concatenation of:
715-
716-
- The byte ``0x04``.
717-
- The 32-byte big-endian encoding of the x-coordinate of :math:`L`.
718-
- The 32-byte big-endian encoding of the y-coordinate of :math:`L`.

0 commit comments

Comments
 (0)