Skip to content

Commit

Permalink
Add cross references to key formats from applicable key types.
Browse files Browse the repository at this point in the history
  • Loading branch information
@athoelke
athoelke committed Sep 4, 2024
1 parent ea1b94a commit 088256c
Show file tree
Hide file tree
Showing 2 changed files with 35 additions and 21 deletions.
54 changes: 33 additions & 21 deletions doc/crypto/api/keys/types.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -117,7 +117,7 @@ Symmetric keys

.. subsection:: Key format

The data format for import and export of the key is the raw bytes of the key.
The default data format for import and export of the key is the raw bytes of the key.

.. subsection:: Key derivation

Expand Down Expand Up @@ -157,7 +157,7 @@ Symmetric keys

.. subsection:: Key format

The data format for import and export of the key is the raw bytes of the key.
The default data format for import and export of the key is the raw bytes of the key.

.. subsection:: Key derivation

Expand Down Expand Up @@ -225,7 +225,7 @@ Symmetric keys

.. subsection:: Key format

The data format for import and export of the key is the raw bytes of the key.
The default data format for import and export of the key is the raw bytes of the key.

.. subsection:: Key derivation

Expand All @@ -250,7 +250,7 @@ Symmetric keys

.. subsection:: Key format

The data format for import and export of the key is the raw bytes of the key.
The default data format for import and export of the key is the raw bytes of the key.

.. subsection:: Key derivation

Expand All @@ -275,7 +275,7 @@ Symmetric keys

.. subsection:: Key format

The data format for import and export of the key is the raw bytes of the key.
The default data format for import and export of the key is the raw bytes of the key.

.. subsection:: Key derivation

Expand Down Expand Up @@ -320,7 +320,7 @@ Symmetric keys

.. subsection:: Key format

The data format for import and export of the key is the raw bytes of the key.
The default data format for import and export of the key is the raw bytes of the key.

.. subsection:: Key derivation

Expand Down Expand Up @@ -365,7 +365,7 @@ Symmetric keys

.. subsection:: Key format

The data format for import and export of the key is the raw bytes of the key.
The default data format for import and export of the key is the raw bytes of the key.

.. subsection:: Key derivation

Expand Down Expand Up @@ -406,7 +406,7 @@ Symmetric keys

.. subsection:: Key format

The data format for import and export of the key is the raw bytes of the key.
The default data format for import and export of the key is the raw bytes of the key.
The parity bits in each 64-bit DES key element must be correct.

.. subsection:: Key derivation
Expand Down Expand Up @@ -459,7 +459,7 @@ Symmetric keys

.. subsection:: Key format

The data format for import and export of the key is the raw bytes of the key.
The default data format for import and export of the key is the raw bytes of the key.

.. subsection:: Key derivation

Expand Down Expand Up @@ -496,7 +496,7 @@ Symmetric keys

.. subsection:: Key format

The data format for import and export of the key is the raw bytes of the key.
The default data format for import and export of the key is the raw bytes of the key.

.. subsection:: Key derivation

Expand All @@ -523,7 +523,7 @@ Symmetric keys

.. subsection:: Key format

The data format for import and export of the key is the raw bytes of the key.
The default data format for import and export of the key is the raw bytes of the key.

.. subsection:: Key derivation

Expand All @@ -550,7 +550,7 @@ Symmetric keys

.. subsection:: Key format

The data format for import and export of the key is the raw bytes of the key.
The default data format for import and export of the key is the raw bytes of the key.

.. subsection:: Key derivation

Expand All @@ -577,7 +577,7 @@ Symmetric keys

.. subsection:: Key format

The data format for import and export of the key is the raw bytes of the key.
The default data format for import and export of the key is the raw bytes of the key.

.. subsection:: Key derivation

Expand Down Expand Up @@ -621,7 +621,7 @@ RSA keys

.. subsection:: Key format

The data format for import and export of a key-pair is the non-encrypted :term:`DER` encoding of the representation defined by in :RFC-title:`8017#A.1.2` as ``RSAPrivateKey``, version ``0``.
The default data format for import and export of a key-pair is the non-encrypted :term:`DER` encoding of the representation defined by in :RFC-title:`8017#A.1.2` as ``RSAPrivateKey``, version ``0``.

.. code-block:: none
Expand All @@ -643,6 +643,9 @@ RSA keys

See `PSA_KEY_TYPE_RSA_PUBLIC_KEY` for the data format used when exporting the public key with `psa_export_public_key()`.

RSA key-pairs can also be imported from and exported using the `PSA_KEY_FORMAT_RSA_PRIVATE_KEY` and `PSA_KEY_FORMAT_ONE_ASYMMETRIC_KEY` key formats.
See :secref:`key-formats`.

.. subsection:: Key generation

A call to `psa_generate_key()` will generate an RSA key-pair with the default public exponent of ``65537``. The modulus :math:`n=pq` is a product of two probabilistic primes :math:`p\ \text{and}\ q`, where :math:`2^{r-1} \le n < 2^r` and :math:`r` is the bit size specified in the attributes.
Expand Down Expand Up @@ -686,14 +689,17 @@ RSA keys

.. subsection:: Key format

The data format for import and export of a public key is the :term:`DER` encoding of the representation defined by :RFC-title:`8017#A.1.1` as ``RSAPublicKey``.
The default data format for import and export of a public key is the :term:`DER` encoding of the representation defined by :RFC-title:`8017#A.1.1` as ``RSAPublicKey``.

.. code-block:: none
RSAPublicKey ::= SEQUENCE {
modulus INTEGER, -- n
publicExponent INTEGER } -- e
RSA public keys can also be imported from and exported using the `PSA_KEY_FORMAT_RSA_PUBLIC_KEY` and `PSA_KEY_FORMAT_SUBJECT_PUBLIC_KEY_INFO` key formats.
See :secref:`key-formats`.

.. macro:: PSA_KEY_TYPE_IS_RSA
:definition: /* specification-defined value */
Expand Down Expand Up @@ -821,7 +827,7 @@ The curve type affects the key format, the key derivation procedure, and the alg

.. subsection:: Key format

The data format for import and export of the key-pair depends on the type of elliptic curve.
The default data format for import and export of the key-pair depends on the type of elliptic curve.
:numref:`tab-ecc-key-pair-format` shows the format for each type of elliptic curve key-pair.

See `PSA_KEY_TYPE_ECC_PUBLIC_KEY` for the data format used when exporting the public key with `psa_export_public_key()`.
Expand Down Expand Up @@ -851,6 +857,9 @@ The curve type affects the key format, the key derivation procedure, and the alg

This is a 32-byte string for Edwards25519, and a 57-byte string for Edwards448.

Elliptic curve key-pairs can also be imported from and exported using the `PSA_KEY_FORMAT_EC_PRIVATE_KEY` and `PSA_KEY_FORMAT_ONE_ASYMMETRIC_KEY` key formats.
See :secref:`key-formats`.

.. subsection:: Key derivation

The key derivation method used when calling `psa_key_derivation_output_key()` depends on the type of elliptic curve.
Expand Down Expand Up @@ -939,7 +948,7 @@ The curve type affects the key format, the key derivation procedure, and the alg

.. subsection:: Key format

The data format for import and export of the public key depends on the type of elliptic curve.
The default data format for import and export of the public key depends on the type of elliptic curve.
:numref:`tab-ecc-public-key-format` shows the format for each type of elliptic curve public key.

.. list-table:: Public key formats for elliptic curve keys
Expand Down Expand Up @@ -970,6 +979,9 @@ The curve type affects the key format, the key derivation procedure, and the alg

This is a 32-byte string for Edwards25519, and a 57-byte string for Edwards448.

Elliptic curve public keys can also be imported from and exported using the `PSA_KEY_FORMAT_SUBJECT_PUBLIC_KEY_INFO` key format.
See :secref:`key-formats`.

.. macro:: PSA_ECC_FAMILY_SECP_K1
:definition: ((psa_ecc_family_t) 0x17)

Expand Down Expand Up @@ -1215,7 +1227,7 @@ Diffie Hellman keys

.. subsection:: Key format

The data format for import and export of the key-pair is the representation of the private key :math:`x` as a big-endian byte string.
The default data format for import and export of the key-pair 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.

See `PSA_KEY_TYPE_DH_PUBLIC_KEY` for the data format used when exporting the public key with `psa_export_public_key()`.
Expand Down Expand Up @@ -1250,7 +1262,7 @@ Diffie Hellman keys

.. subsection:: Key format

The data format for export of the public key is the representation of the public key :math:`y = g^x\!\mod p` as a big-endian byte string.
The default data format for export of the public key 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.

.. macro:: PSA_DH_FAMILY_RFC7919
Expand Down Expand Up @@ -1372,7 +1384,7 @@ SPAKE2+ keys
A SPAKE2+ key-pair consists of the two values :math:`w0` and :math:`w1`, which result from the SPAKE2+ registration phase, see :secref:`spake2p-registration`.
: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.

The data format for import and export of the 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|.
The default data format for import and export of the key-pair is the concatenation of the formatted values for :math:`w0` and :math:`w1`, using the default formats for elliptic curve keys used by the |API|.
For example, for SPAKE2+ over P-256 (secp256r1), the output from :code:`psa_export_key()` would be the concatenation of:

* The P-256 private key :math:`w0`.
Expand Down Expand Up @@ -1431,7 +1443,7 @@ SPAKE2+ keys
:math:`w0` is a scalar in the same range as a elliptic curve private key from the group used as the SPAKE2+ primitive group.
: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.

The data format for import and export of the 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|.
The default data format for import and export of the public key is the concatenation of the formatted values for :math:`w0` and :math:`L`, using the default formats for elliptic curve keys used by the |API|.
For example, for SPAKE2+ over P-256 (secp256r1), the output from :code:`psa_export_public_key()` would be the concatenation of:

* The P-256 private key :math:`w0`.
Expand Down
2 changes: 2 additions & 0 deletions doc/crypto/appendix/history.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,8 @@ Changes to the API
- Added definitions for key formats and and formatting options.
See :secref:`key-formats`.
- Added `psa_import_formatted_key()` to import keys in other formats.
- Added `psa_export_formatted_key()` and `psa_export_formatted_public_key()` to export keys in other formats.
- Added ``PSA_EXPORT_FORMATTED_XXX`` support macros to evaluate buffer sizes for the formatted export functions.

Clarifications and fixes
~~~~~~~~~~~~~~~~~~~~~~~~
Expand Down

0 comments on commit 088256c

Please sign in to comment.