Skip to content

Commit cdb6491

Browse files
athoelkeathoelke
committed
Improve readability of key format and derivation
* Add some boilerplate to provide context for the sub-section contents * Improve linkage between key pair and public key formats
1 parent f869c81 commit cdb6491

1 file changed

Lines changed: 55 additions & 49 deletions

File tree

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

Lines changed: 55 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -117,11 +117,11 @@ Symmetric keys
117117

118118
.. subsection:: Key format
119119

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

122122
.. subsection:: Key derivation
123123

124-
Draw :math:`m/8` bytes of output and use these as the key data, where :math:`m` is the bit-size of the key.
124+
A call to `psa_key_derivation_output_key()` will draw :math:`m/8` bytes of output and use these as the key data, where :math:`m` is the bit-size of the key.
125125

126126
.. macro:: PSA_KEY_TYPE_HMAC
127127
:definition: ((psa_key_type_t)0x1100)
@@ -157,11 +157,11 @@ Symmetric keys
157157

158158
.. subsection:: Key format
159159

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

162162
.. subsection:: Key derivation
163163

164-
Draw :math:`m/8` bytes of output and use these as the key data, where :math:`m` is the bit-size of the key.
164+
A call to `psa_key_derivation_output_key()` will draw :math:`m/8` bytes of output and use these as the key data, where :math:`m` is the bit-size of the key.
165165

166166
.. macro:: PSA_KEY_TYPE_DERIVE
167167
:definition: ((psa_key_type_t)0x1200)
@@ -191,11 +191,11 @@ Symmetric keys
191191

192192
.. subsection:: Key format
193193

194-
The key data is the raw bytes of the key.
194+
The data format for import and export of the key is the raw bytes of the key.
195195

196196
.. subsection:: Key derivation
197197

198-
Draw :math:`m/8` bytes of output and use these as the key data, where :math:`m` is the bit-size of the key.
198+
A call to `psa_key_derivation_output_key()` will draw :math:`m/8` bytes of output and use these as the key data, where :math:`m` is the bit-size of the key.
199199

200200
.. macro:: PSA_KEY_TYPE_PASSWORD
201201
:definition: ((psa_key_type_t)0x1203)
@@ -225,11 +225,11 @@ Symmetric keys
225225

226226
.. subsection:: Key format
227227

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

230230
.. subsection:: Key derivation
231231

232-
Draw :math:`m/8` bytes of output and use these as the key data, where :math:`m` is the bit-size of the key.
232+
A call to `psa_key_derivation_output_key()` will draw :math:`m/8` bytes of output and use these as the key data, where :math:`m` is the bit-size of the key.
233233

234234
.. macro:: PSA_KEY_TYPE_PASSWORD_HASH
235235
:definition: ((psa_key_type_t)0x1205)
@@ -250,11 +250,11 @@ Symmetric keys
250250

251251
.. subsection:: Key format
252252

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

255255
.. subsection:: Key derivation
256256

257-
Draw :math:`m/8` bytes of output and use these as the key data, where :math:`m` is the bit-size of the key.
257+
A call to `psa_key_derivation_output_key()` will draw :math:`m/8` bytes of output and use these as the key data, where :math:`m` is the bit-size of the key.
258258

259259
.. macro:: PSA_KEY_TYPE_PEPPER
260260
:definition: ((psa_key_type_t)0x1206)
@@ -275,11 +275,11 @@ Symmetric keys
275275

276276
.. subsection:: Key format
277277

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

280280
.. subsection:: Key derivation
281281

282-
Draw :math:`m/8` bytes of output and use these as the key data, where :math:`m` is the bit-size of the key.
282+
A call to `psa_key_derivation_output_key()` will draw :math:`m/8` bytes of output and use these as the key data, where :math:`m` is the bit-size of the key.
283283

284284
.. macro:: PSA_KEY_TYPE_AES
285285
:definition: ((psa_key_type_t)0x2400)
@@ -320,11 +320,11 @@ Symmetric keys
320320

321321
.. subsection:: Key format
322322

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

325325
.. subsection:: Key derivation
326326

327-
Draw :math:`m/8` bytes of output and use these as the key data, where :math:`m` is the bit-size of the key.
327+
A call to `psa_key_derivation_output_key()` will draw :math:`m/8` bytes of output and use these as the key data, where :math:`m` is the bit-size of the key.
328328

329329
.. macro:: PSA_KEY_TYPE_ARIA
330330
:definition: ((psa_key_type_t)0x2406)
@@ -365,11 +365,11 @@ Symmetric keys
365365

366366
.. subsection:: Key format
367367

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

370370
.. subsection:: Key derivation
371371

372-
Draw :math:`m/8` bytes of output and use these as the key data, where :math:`m` is the bit-size of the key.
372+
A call to `psa_key_derivation_output_key()` will draw :math:`m/8` bytes of output and use these as the key data, where :math:`m` is the bit-size of the key.
373373

374374
.. macro:: PSA_KEY_TYPE_DES
375375
:definition: ((psa_key_type_t)0x2301)
@@ -406,19 +406,19 @@ Symmetric keys
406406

407407
.. subsection:: Key format
408408

409-
The key data is the raw bytes of the key.
409+
The 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
413413

414-
To derive a single 64-bit DES key, use the following process:
414+
A call to `psa_key_derivation_output_key()` will construct a single 64-bit DES key using the following process:
415415

416416
1. Draw an 8-byte string.
417417
#. Set/clear the parity bits in each byte.
418418
#. If the result is a forbidden weak key, discard the result and return to step 1.
419419
#. Output the string.
420420

421-
For 2-key 3DES and 3-key 3DES, repeat this process to derive the 2nd and 3rd keys, as required.
421+
For 2-key 3DES and 3-key 3DES, this process is repeated to derive the 2nd and 3rd keys, as required.
422422

423423
.. macro:: PSA_KEY_TYPE_CAMELLIA
424424
:definition: ((psa_key_type_t)0x2403)
@@ -459,11 +459,11 @@ Symmetric keys
459459

460460
.. subsection:: Key format
461461

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

464464
.. subsection:: Key derivation
465465

466-
Draw :math:`m/8` bytes of output and use these as the key data, where :math:`m` is the bit-size of the key.
466+
A call to `psa_key_derivation_output_key()` will draw :math:`m/8` bytes of output and use these as the key data, where :math:`m` is the bit-size of the key.
467467

468468
.. macro:: PSA_KEY_TYPE_SM4
469469
:definition: ((psa_key_type_t)0x2405)
@@ -496,11 +496,11 @@ Symmetric keys
496496

497497
.. subsection:: Key format
498498

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

501501
.. subsection:: Key derivation
502502

503-
Draw :math:`m/8` bytes of output and use these as the key data, where :math:`m` is the bit-size of the key.
503+
A call to `psa_key_derivation_output_key()` will draw :math:`m/8` bytes of output and use these as the key data, where :math:`m` is the bit-size of the key.
504504

505505
.. macro:: PSA_KEY_TYPE_ARC4
506506
:definition: ((psa_key_type_t)0x2002)
@@ -523,11 +523,11 @@ Symmetric keys
523523

524524
.. subsection:: Key format
525525

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

528528
.. subsection:: Key derivation
529529

530-
Draw :math:`m/8` bytes of output and use these as the key data, where :math:`m` is the bit-size of the key.
530+
A call to `psa_key_derivation_output_key()` will draw :math:`m/8` bytes of output and use these as the key data, where :math:`m` is the bit-size of the key.
531531

532532
.. macro:: PSA_KEY_TYPE_CHACHA20
533533
:definition: ((psa_key_type_t)0x2004)
@@ -550,11 +550,11 @@ Symmetric keys
550550

551551
.. subsection:: Key format
552552

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

555555
.. subsection:: Key derivation
556556

557-
Draw 32 bytes of output and use these as the key data.
557+
A call to `psa_key_derivation_output_key()` will draw 32 bytes of output and use these as the key data.
558558

559559
.. macro:: PSA_KEY_TYPE_XCHACHA20
560560
:definition: ((psa_key_type_t)0x2007)
@@ -577,11 +577,11 @@ Symmetric keys
577577

578578
.. subsection:: Key format
579579

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

582582
.. subsection:: Key derivation
583583

584-
Draw 32 bytes of output and use these as the key data.
584+
A call to `psa_key_derivation_output_key()` will draw 32 bytes of output and use these as the key data.
585585

586586
.. _asymmetric-keys:
587587

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

622622
.. subsection:: Key format
623623

624-
The key data is the non-encrypted DER encoding of the representation defined by in :RFC-title:`8017` as ``RSAPrivateKey``, version ``0``.
624+
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``.
625625

626626
.. code-block:: none
627627
@@ -641,9 +641,11 @@ RSA keys
641641

642642
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.
643643

644+
See `PSA_KEY_TYPE_RSA_PUBLIC_KEY` for the data format used when exporting the public key with `psa_export_public_key()`.
645+
644646
.. subsection:: Key derivation
645647

646-
The key derivation method for RSA keys is :term:`implementation defined`.
648+
The method used by `psa_key_derivation_output_key()` to derive an RSA key-pair is :term:`implementation defined`.
647649

648650
.. macro:: PSA_KEY_TYPE_RSA_PUBLIC_KEY
649651
:definition: ((psa_key_type_t)0x4001)
@@ -667,7 +669,7 @@ RSA keys
667669

668670
.. subsection:: Key format
669671

670-
The key data is the DER encoding of the representation defined by :RFC-title:`3279#2.3.1` as ``RSAPublicKey``.
672+
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``.
671673

672674
.. code-block:: none
673675
@@ -793,9 +795,10 @@ The curve type affects the key format, the key derivation procedure, and the alg
793795

794796
.. subsection:: Key format
795797

798+
The data format for import and export of the key-pair depends on the type of elliptic curve.
796799
:numref:`tab-ecc-key-pair-format` shows the format for each type of elliptic curve key-pair.
797-
This is the format used for `psa_import_key()` and `psa_export_key()`.
798-
See `PSA_KEY_TYPE_ECC_PUBLIC_KEY()` for the format used for `psa_export_public_key()`.
800+
801+
See `PSA_KEY_TYPE_ECC_PUBLIC_KEY` for the data format used when exporting the public key with `psa_export_public_key()`.
799802

800803
.. list-table:: Key-pair formats for elliptic curve keys
801804
:name: tab-ecc-key-pair-format
@@ -824,6 +827,7 @@ The curve type affects the key format, the key derivation procedure, and the alg
824827

825828
.. subsection:: Key derivation
826829

830+
The key derivation method used when calling `psa_key_derivation_output_key()` depends on the type of elliptic curve.
827831
:numref:`tab-ecc-key-derivation` shows the derivation method for each type of elliptic curve key.
828832

829833
.. list-table:: Key derivation for elliptic curve keys
@@ -909,6 +913,7 @@ The curve type affects the key format, the key derivation procedure, and the alg
909913

910914
.. subsection:: Key format
911915

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

914919
.. list-table:: Public key formats for elliptic curve keys
@@ -1175,14 +1180,18 @@ Diffie Hellman keys
11751180

11761181
.. subsection:: Key format
11771182

1178-
The key data is the representation of the private key :math:`x` as a big-endian byte string.
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.
11791184
The length of the byte string is the private key size in bytes, and leading zeroes are not stripped.
11801185

1186+
See `PSA_KEY_TYPE_DH_PUBLIC_KEY` for the data format used when exporting the public key with `psa_export_public_key()`.
1187+
11811188
.. subsection:: Key derivation
11821189

1183-
A Diffie-Hellman private key is :math:`x \in [1, p - 1]`, where :math:`p` is the group's prime modulus.
1190+
A call to `psa_key_derivation_output_key()` will use the following process, defined in *Key-Pair Generation by Testing Candidates* in :cite-title:`SP800-56A` §5.6.1.1.4.
11841191

1192+
A Diffie-Hellman private key is :math:`x \in [1, p - 1]`, where :math:`p` is the group's prime modulus.
11851193
Let :math:`m` be the bit size of :math:`p`, such that :math:`2^{m-1} \leq p < 2^m`.
1194+
11861195
This function generates the private key using the following process:
11871196

11881197
1. Draw a byte string of length :math:`\lceil{m/8}\rceil` bytes.
@@ -1191,8 +1200,6 @@ Diffie Hellman keys
11911200
#. If :math:`k > p-2`, discard the result and return to step 1.
11921201
#. Output :math:`x = k + 1` as the private key.
11931202

1194-
This method allows compliance to NIST standards, specifically the methods titled *Key-Pair Generation by Testing Candidates* in :cite-title:`SP800-56A` §5.6.1.1.4.
1195-
11961203
.. macro:: PSA_KEY_TYPE_DH_PUBLIC_KEY
11971204
:definition: /* specification-defined value */
11981205
@@ -1204,11 +1211,12 @@ Diffie Hellman keys
12041211

12051212
.. subsection:: Compatible algorithms
12061213

1207-
None. Finite-field Diffie-Hellman public keys are exported to use in a key agreement algorithm, and the peer key is provided to the `PSA_ALG_FFDH` key agreement algorithm as a buffer of key data.
1214+
None: Finite-field Diffie-Hellman public keys are exported to use in a key agreement algorithm, and the peer key is provided to the `PSA_ALG_FFDH` key agreement algorithm as a buffer of key data.
12081215

12091216
.. subsection:: Key format
12101217

1211-
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.
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.
1219+
The length of the byte string is the length of the base prime :math:`p` in bytes.
12121220

12131221
.. macro:: PSA_DH_FAMILY_RFC7919
12141222
:definition: ((psa_dh_family_t) 0x03)
@@ -1326,22 +1334,22 @@ SPAKE2+ keys
13261334

13271335
.. subsection:: Key format
13281336

1329-
A SPAKE2+ key pair can be exported and imported.
1330-
1331-
The key consists of the two values :math:`w0` and :math:`w1`, which result from the SPAKE2+ registration phase, see :secref:`spake2p-registration`.
1337+
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`.
13321338
: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.
13331339

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

13371343
* The P-256 private key :math:`w0`.
13381344
This is a 32-byte big-endian encoding of the integer :math:`w0`.
13391345
* The P-256 private key :math:`w1`.
13401346
This is a 32-byte big-endian encoding of the integer :math:`w1`.
13411347

1348+
See `PSA_KEY_TYPE_SPAKE2P_PUBLIC_KEY` for the data format used when exporting the public key with `psa_export_public_key()`.
1349+
13421350
.. subsection:: Key derivation
13431351

1344-
The SPAKE2+ key derivation process follows the recommendations for the registration process in :rfc-title:`9383`, and matches the specification of this process in :cite-title:`MATTER`.
1352+
A call to `psa_key_derivation_output_key()` will use the following process, which follows the recommendations for the registration process in :rfc-title:`9383`, and matches the specification of this process in :cite-title:`MATTER`.
13451353

13461354
The derivation of SPAKE2+ keys extracts :math:`\lceil{log_2(p)/8}\rceil+8` bytes from the PBKDF for each of :math:`w0s` and :math:`w1s`, where :math:`p` is the prime factor of the order of the elliptic curve group.
13471355
The following sizes are used for extracting :math:`w0s` and :math:`w1s`, depending on the elliptic curve:
@@ -1384,13 +1392,11 @@ SPAKE2+ keys
13841392

13851393
.. subsection:: Key format
13861394

1387-
A SPAKE2+ public key can be exported and imported, to enable use cases that require offline registration.
1388-
1389-
The public key consists of the two values :math:`w0` and :math:`L`, which result from the SPAKE2+ registration phase, see :secref:`spake2p-registration`.
1395+
A SPAKE2+ public key consists of the two values :math:`w0` and :math:`L`, which result from the SPAKE2+ registration phase, see :secref:`spake2p-registration`.
13901396
:math:`w0` is a scalar in the same range as a elliptic curve private key from the group used as the SPAKE2+ primitive group.
13911397
: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.
13921398

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

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

0 commit comments

Comments
 (0)