Import and export of non-default key formats

doc/crypto/api.db/psa/crypto.h

@@ -10,6 +10,8 @@ typedef /* implementation-defined type */ psa_hash_operation_t;
 typedef /* implementation-defined type */ psa_key_attributes_t;
 typedef /* implementation-defined type */ psa_key_derivation_operation_t;
 typedef uint16_t psa_key_derivation_step_t;
+typedef uint32_t psa_key_format_option_t;
+typedef uint32_t psa_key_format_t;
 typedef uint32_t psa_key_id_t;
 typedef uint32_t psa_key_lifetime_t;
 typedef uint32_t psa_key_location_t;
@@ -224,6 +226,16 @@ typedef struct psa_custom_key_parameters_t {
 #define PSA_ERROR_INSUFFICIENT_ENTROPY ((psa_status_t)-148)
 #define PSA_ERROR_INVALID_PADDING ((psa_status_t)-150)
 #define PSA_EXPORT_ASYMMETRIC_KEY_MAX_SIZE /* implementation-defined value */
+#define PSA_EXPORT_FORMATTED_ASYMMETRIC_KEY_MAX_SIZE \
+    /* implementation-defined value */
+#define PSA_EXPORT_FORMATTED_KEY_OUTPUT_SIZE(format, options, key_type, key_bits) \
+    /* implementation-defined value */
+#define PSA_EXPORT_FORMATTED_KEY_PAIR_MAX_SIZE \
+    /* implementation-defined value */
+#define PSA_EXPORT_FORMATTED_PUBLIC_KEY_MAX_SIZE \
+    /* implementation-defined value */
+#define PSA_EXPORT_FORMATTED_PUBLIC_KEY_OUTPUT_SIZE(format, options, key_type, key_bits) \
+    /* implementation-defined value */
 #define PSA_EXPORT_KEY_OUTPUT_SIZE(key_type, key_bits) \
     /* implementation-defined value */
 #define PSA_EXPORT_KEY_PAIR_MAX_SIZE /* implementation-defined value */
@@ -255,6 +267,19 @@ typedef struct psa_custom_key_parameters_t {
 #define PSA_KEY_DERIVATION_OPERATION_INIT /* implementation-defined value */
 #define PSA_KEY_DERIVATION_UNLIMITED_CAPACITY \
     /* implementation-defined value */
+#define PSA_KEY_FORMAT_DEFAULT ((psa_key_format_t) 0)
+#define PSA_KEY_FORMAT_EC_PRIVATE_KEY /* implementation-defined value */
+#define PSA_KEY_FORMAT_ONE_ASYMMETRIC_KEY /* implementation-defined value */
+#define PSA_KEY_FORMAT_OPTION_DEFAULT ((psa_key_format_option_t) 0)
+#define PSA_KEY_FORMAT_OPTION_EC_POINT_COMPRESSED \
+    /* implementation-defined value */
+#define PSA_KEY_FORMAT_OPTION_PEM /* implementation-defined value */
+#define PSA_KEY_FORMAT_OPTION_SPECIFIED_EC_DOMAIN \
+    /* implementation-defined value */
+#define PSA_KEY_FORMAT_RSA_PRIVATE_KEY /* implementation-defined value */
+#define PSA_KEY_FORMAT_RSA_PUBLIC_KEY /* implementation-defined value */
+#define PSA_KEY_FORMAT_SUBJECT_PUBLIC_KEY_INFO \
+    /* implementation-defined value */
 #define PSA_KEY_ID_NULL ((psa_key_id_t)0)
 #define PSA_KEY_ID_USER_MAX ((psa_key_id_t)0x3fffffff)
 #define PSA_KEY_ID_USER_MIN ((psa_key_id_t)0x00000001)
@@ -499,6 +524,18 @@ psa_status_t psa_copy_key(psa_key_id_t source_key,
                           psa_key_id_t * target_key);
 psa_status_t psa_crypto_init(void);
 psa_status_t psa_destroy_key(psa_key_id_t key);
+psa_status_t psa_export_formatted_key(psa_key_format_t format,
+                                      psa_key_format_option_t options,
+                                      psa_key_id_t key,
+                                      uint8_t * data,
+                                      size_t data_size,
+                                      size_t * data_length);
+psa_status_t psa_export_formatted_public_key(psa_key_format_t format,
+                                             psa_key_format_option_t options,
+                                             psa_key_id_t key,
+                                             uint8_t * data,
+                                             size_t data_size,
+                                             size_t * data_length);
 psa_status_t psa_export_key(psa_key_id_t key,
                             uint8_t * data,
                             size_t data_size,
@@ -558,6 +595,11 @@ psa_status_t psa_hash_update(psa_hash_operation_t * operation,
 psa_status_t psa_hash_verify(psa_hash_operation_t * operation,
                              const uint8_t * hash,
                              size_t hash_length);
+psa_status_t psa_import_formatted_key(const psa_key_attributes_t * attributes,
+                                      psa_key_format_t format,
+                                      const uint8_t * data,
+                                      size_t data_length,
+                                      psa_key_id_t * key);
 psa_status_t psa_import_key(const psa_key_attributes_t * attributes,
                             const uint8_t * data,
                             size_t data_length,

doc/crypto/api/keys/types.rst

@@ -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
 
@@ -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
 
@@ -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
 
@@ -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
 
@@ -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
 
@@ -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
 
@@ -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
 
@@ -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
@@ -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
 
@@ -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
 
@@ -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
 
@@ -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
 
@@ -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
 
@@ -621,7 +621,7 @@ RSA keys
 
     .. subsection:: Key format
 
-        The data format for import and export of a key-pair is the non-encrypted DER encoding of the representation defined by in :RFC-title:`8017` 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
 
@@ -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.
@@ -686,14 +689,17 @@ RSA keys
 
     .. subsection:: Key format
 
-        The data format for import and export of a public key is the DER encoding of the representation defined by :RFC-title:`3279#2.3.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 */
 
@@ -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()`.
@@ -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.
@@ -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
@@ -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)
 
@@ -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()`.
@@ -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
@@ -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`.
@@ -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`.

doc/crypto/api/ops/pake.rst

@@ -2,7 +2,7 @@
 .. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license
 
 .. header:: psa/crypto
-    :seq: 30
+    :seq: 29
 
 .. _pake:
 

doc/crypto/api/ops/signature.rst

@@ -57,7 +57,7 @@ Asymmetric signature algorithms
 
     This signature scheme is defined by :RFC-title:`8017#8.2` under the name RSASSA-PKCS1-v1_5.
 
-    The ``hash`` parameter to `psa_sign_hash()` or `psa_verify_hash()` is used as :math:`T` from step 3 onwards in the message encoding algorithm ``EMSA-PKCS1-V1_5-ENCODE()`` in :RFC:`8017#9.2`. :math:`T` is normally the DER encoding of the *DigestInfo* structure produced by step 2 in the message encoding algorithm, but it can be any byte string within the available length.
+    The ``hash`` parameter to `psa_sign_hash()` or `psa_verify_hash()` is used as :math:`T` from step 3 onwards in the message encoding algorithm ``EMSA-PKCS1-V1_5-ENCODE()`` in :RFC:`8017#9.2`. :math:`T` is normally the :term:`DER` encoding of the *DigestInfo* structure produced by step 2 in the message encoding algorithm, but it can be any byte string within the available length.
 
     The wildcard key policy :code:`PSA_ALG_RSA_PKCS1V15_SIGN(PSA_ALG_ANY_HASH)` also permits a key to be used with the `PSA_ALG_RSA_PKCS1V15_SIGN_RAW` signature algorithm.
 

doc/crypto/appendix/history.rst

@@ -33,6 +33,14 @@ Changes to the API
 
     See :secref:`asymmetric-key-encoding` and :secref:`appendix-specdef-key-values`.
 
+*   Added support for non-default key formats:
+
+    -   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
 ~~~~~~~~~~~~~~~~~~~~~~~~