Skip to content

Commit ddfed12

Browse files
athoelkeathoelke
committed
Add cross references to key formats from applicable key types.
1 parent cbde370 commit ddfed12

File tree

2 files changed

+35
-21
lines changed

2 files changed

+35
-21
lines changed

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

Lines changed: 33 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -117,7 +117,7 @@ Symmetric keys
117117

118118
.. subsection:: Key format
119119

120-
The data format for import and export of the key is the raw bytes of the key.
120+
The default data format for import and export of the key is the raw bytes of the key.
121121

122122
.. subsection:: Key derivation
123123

@@ -157,7 +157,7 @@ Symmetric keys
157157

158158
.. subsection:: Key format
159159

160-
The data format for import and export of the key is the raw bytes of the key.
160+
The default data format for import and export of the key is the raw bytes of the key.
161161

162162
.. subsection:: Key derivation
163163

@@ -225,7 +225,7 @@ Symmetric keys
225225

226226
.. subsection:: Key format
227227

228-
The data format for import and export of the key is the raw bytes of the key.
228+
The default data format for import and export of the key is the raw bytes of the key.
229229

230230
.. subsection:: Key derivation
231231

@@ -250,7 +250,7 @@ Symmetric keys
250250

251251
.. subsection:: Key format
252252

253-
The data format for import and export of the key is the raw bytes of the key.
253+
The default data format for import and export of the key is the raw bytes of the key.
254254

255255
.. subsection:: Key derivation
256256

@@ -275,7 +275,7 @@ Symmetric keys
275275

276276
.. subsection:: Key format
277277

278-
The data format for import and export of the key is the raw bytes of the key.
278+
The default data format for import and export of the key is the raw bytes of the key.
279279

280280
.. subsection:: Key derivation
281281

@@ -320,7 +320,7 @@ Symmetric keys
320320

321321
.. subsection:: Key format
322322

323-
The data format for import and export of the key is the raw bytes of the key.
323+
The default data format for import and export of the key is the raw bytes of the key.
324324

325325
.. subsection:: Key derivation
326326

@@ -365,7 +365,7 @@ Symmetric keys
365365

366366
.. subsection:: Key format
367367

368-
The data format for import and export of the key is the raw bytes of the key.
368+
The default data format for import and export of the key is the raw bytes of the key.
369369

370370
.. subsection:: Key derivation
371371

@@ -406,7 +406,7 @@ Symmetric keys
406406

407407
.. subsection:: Key format
408408

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

412412
.. subsection:: Key derivation
@@ -459,7 +459,7 @@ Symmetric keys
459459

460460
.. subsection:: Key format
461461

462-
The data format for import and export of the key is the raw bytes of the key.
462+
The default data format for import and export of the key is the raw bytes of the key.
463463

464464
.. subsection:: Key derivation
465465

@@ -496,7 +496,7 @@ Symmetric keys
496496

497497
.. subsection:: Key format
498498

499-
The data format for import and export of the key is the raw bytes of the key.
499+
The default data format for import and export of the key is the raw bytes of the key.
500500

501501
.. subsection:: Key derivation
502502

@@ -523,7 +523,7 @@ Symmetric keys
523523

524524
.. subsection:: Key format
525525

526-
The data format for import and export of the key is the raw bytes of the key.
526+
The default data format for import and export of the key is the raw bytes of the key.
527527

528528
.. subsection:: Key derivation
529529

@@ -550,7 +550,7 @@ Symmetric keys
550550

551551
.. subsection:: Key format
552552

553-
The data format for import and export of the key is the raw bytes of the key.
553+
The default data format for import and export of the key is the raw bytes of the key.
554554

555555
.. subsection:: Key derivation
556556

@@ -577,7 +577,7 @@ Symmetric keys
577577

578578
.. subsection:: Key format
579579

580-
The data format for import and export of the key is the raw bytes of the key.
580+
The default data format for import and export of the key is the raw bytes of the key.
581581

582582
.. subsection:: Key derivation
583583

@@ -621,7 +621,7 @@ RSA keys
621621

622622
.. subsection:: Key format
623623

624-
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``.
624+
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``.
625625

626626
.. code-block:: none
627627
@@ -643,6 +643,9 @@ RSA keys
643643

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

646+
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.
647+
See :secref:`key-formats`.
648+
646649
.. subsection:: Key derivation
647650

648651
The method used by `psa_key_derivation_output_key()` to derive an RSA key-pair is :term:`implementation defined`.
@@ -669,14 +672,17 @@ RSA keys
669672

670673
.. subsection:: Key format
671674

672-
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``.
675+
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``.
673676

674677
.. code-block:: none
675678
676679
RSAPublicKey ::= SEQUENCE {
677680
modulus INTEGER, -- n
678681
publicExponent INTEGER } -- e
679682
683+
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.
684+
See :secref:`key-formats`.
685+
680686
.. macro:: PSA_KEY_TYPE_IS_RSA
681687
:definition: /* specification-defined value */
682688
@@ -795,7 +801,7 @@ The curve type affects the key format, the key derivation procedure, and the alg
795801

796802
.. subsection:: Key format
797803

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

801807
See `PSA_KEY_TYPE_ECC_PUBLIC_KEY` for the data format used when exporting the public key with `psa_export_public_key()`.
@@ -825,6 +831,9 @@ The curve type affects the key format, the key derivation procedure, and the alg
825831

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

834+
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.
835+
See :secref:`key-formats`.
836+
828837
.. subsection:: Key derivation
829838

830839
The key derivation method used when calling `psa_key_derivation_output_key()` depends on the type of elliptic curve.
@@ -913,7 +922,7 @@ The curve type affects the key format, the key derivation procedure, and the alg
913922

914923
.. subsection:: Key format
915924

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

919928
.. list-table:: Public key formats for elliptic curve keys
@@ -944,6 +953,9 @@ The curve type affects the key format, the key derivation procedure, and the alg
944953

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

956+
Elliptic curve public keys can also be imported from and exported using the `PSA_KEY_FORMAT_SUBJECT_PUBLIC_KEY_INFO` key format.
957+
See :secref:`key-formats`.
958+
947959
.. macro:: PSA_ECC_FAMILY_SECP_K1
948960
:definition: ((psa_ecc_family_t) 0x17)
949961

@@ -1180,7 +1192,7 @@ Diffie Hellman keys
11801192

11811193
.. subsection:: Key format
11821194

1183-
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.
1195+
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.
11841196
The length of the byte string is the private key size in bytes, and leading zeroes are not stripped.
11851197

11861198
See `PSA_KEY_TYPE_DH_PUBLIC_KEY` for the data format used when exporting the public key with `psa_export_public_key()`.
@@ -1215,7 +1227,7 @@ Diffie Hellman keys
12151227

12161228
.. subsection:: Key format
12171229

1218-
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.
1230+
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.
12191231
The length of the byte string is the length of the base prime :math:`p` in bytes.
12201232

12211233
.. macro:: PSA_DH_FAMILY_RFC7919
@@ -1337,7 +1349,7 @@ SPAKE2+ keys
13371349
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`.
13381350
: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.
13391351

1340-
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|.
1352+
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|.
13411353
For example, for SPAKE2+ over P-256 (secp256r1), the output from :code:`psa_export_key()` would be the concatenation of:
13421354

13431355
* The P-256 private key :math:`w0`.
@@ -1396,7 +1408,7 @@ SPAKE2+ keys
13961408
:math:`w0` is a scalar in the same range as a elliptic curve private key from the group used as the SPAKE2+ primitive group.
13971409
: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.
13981410

1399-
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|.
1411+
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|.
14001412
For example, for SPAKE2+ over P-256 (secp256r1), the output from :code:`psa_export_public_key()` would be the concatenation of:
14011413

14021414
* The P-256 private key :math:`w0`.

‎doc/crypto/appendix/history.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,8 @@ Changes to the API
2626
- Added definitions for key formats and and formatting options.
2727
See :secref:`key-formats`.
2828
- Added `psa_import_formatted_key()` to import keys in other formats.
29+
- Added `psa_export_formatted_key()` and `psa_export_formatted_public_key()` to export keys in other formats.
30+
- Added ``PSA_EXPORT_FORMATTED_XXX`` support macros to evaluate buffer sizes for the formatted export functions.
2931

3032
Clarifications and fixes
3133
~~~~~~~~~~~~~~~~~~~~~~~~

0 commit comments

Comments
 (0)