Skip to content

Commit 8d23da2

Browse files
smuellerDDJonathan Corbet
smuellerDD
authored and
Jonathan Corbet
committed
crypto: doc - add KPP documentation
Add the KPP API documentation to the kernel crypto API Sphinx documentation. This addition includes the documentation of the ECDH and DH helpers which are needed to create the approrpiate input data for the crypto_kpp_set_secret function. Signed-off-by: Stephan Mueller <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]>
1 parent c30c98d commit 8d23da2

File tree

6 files changed

+227
-3
lines changed

6 files changed

+227
-3
lines changed

‎Documentation/crypto/api-kpp.rst

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
Key-agreement Protocol Primitives (KPP) Cipher Algorithm Definitions
2+
--------------------------------------------------------------------
3+
4+
.. kernel-doc:: include/crypto/kpp.h
5+
:functions: kpp_request
6+
7+
.. kernel-doc:: include/crypto/kpp.h
8+
:functions: crypto_kpp
9+
10+
.. kernel-doc:: include/crypto/kpp.h
11+
:functions: kpp_alg
12+
13+
.. kernel-doc:: include/crypto/kpp.h
14+
:functions: kpp_secret
15+
16+
Key-agreement Protocol Primitives (KPP) Cipher API
17+
--------------------------------------------------
18+
19+
.. kernel-doc:: include/crypto/kpp.h
20+
:doc: Generic Key-agreement Protocol Primitives API
21+
22+
.. kernel-doc:: include/crypto/kpp.h
23+
:functions: crypto_alloc_kpp
24+
25+
.. kernel-doc:: include/crypto/kpp.h
26+
:functions: crypto_free_kpp
27+
28+
.. kernel-doc:: include/crypto/kpp.h
29+
:functions: crypto_kpp_set_secret
30+
31+
.. kernel-doc:: include/crypto/kpp.h
32+
:functions: crypto_kpp_generate_public_key
33+
34+
.. kernel-doc:: include/crypto/kpp.h
35+
:functions: crypto_kpp_compute_shared_secret
36+
37+
.. kernel-doc:: include/crypto/kpp.h
38+
:functions: crypto_kpp_maxsize
39+
40+
Key-agreement Protocol Primitives (KPP) Cipher Request Handle
41+
-------------------------------------------------------------
42+
43+
.. kernel-doc:: include/crypto/kpp.h
44+
:functions: kpp_request_alloc
45+
46+
.. kernel-doc:: include/crypto/kpp.h
47+
:functions: kpp_request_free
48+
49+
.. kernel-doc:: include/crypto/kpp.h
50+
:functions: kpp_request_set_callback
51+
52+
.. kernel-doc:: include/crypto/kpp.h
53+
:functions: kpp_request_set_input
54+
55+
.. kernel-doc:: include/crypto/kpp.h
56+
:functions: kpp_request_set_output
57+
58+
ECDH Helper Functions
59+
---------------------
60+
61+
.. kernel-doc:: include/crypto/ecdh.h
62+
:doc: ECDH Helper Functions
63+
64+
.. kernel-doc:: include/crypto/ecdh.h
65+
:functions: ecdh
66+
67+
.. kernel-doc:: include/crypto/ecdh.h
68+
:functions: crypto_ecdh_key_len
69+
70+
.. kernel-doc:: include/crypto/ecdh.h
71+
:functions: crypto_ecdh_encode_key
72+
73+
.. kernel-doc:: include/crypto/ecdh.h
74+
:functions: crypto_ecdh_decode_key
75+
76+
DH Helper Functions
77+
-------------------
78+
79+
.. kernel-doc:: include/crypto/dh.h
80+
:doc: DH Helper Functions
81+
82+
.. kernel-doc:: include/crypto/dh.h
83+
:functions: dh
84+
85+
.. kernel-doc:: include/crypto/dh.h
86+
:functions: crypto_dh_key_len
87+
88+
.. kernel-doc:: include/crypto/dh.h
89+
:functions: crypto_dh_encode_key
90+
91+
.. kernel-doc:: include/crypto/dh.h
92+
:functions: crypto_dh_decode_key

‎Documentation/crypto/api.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,3 +22,4 @@ the IV. Different IV generators are available.
2222
api-digest
2323
api-rng
2424
api-akcipher
25+
api-kpp

‎Documentation/crypto/architecture.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -161,6 +161,9 @@ applicable to a cipher, it is not displayed:
161161
entry below for the specification of the IV generator type used by
162162
the cipher implementation)
163163

164+
- kpp for a Key-agreement Protocol Primitive (KPP) cipher such as
165+
an ECDH or DH implementation
166+
164167
- blocksize: blocksize of cipher in bytes
165168

166169
- keysize: key size in bytes
@@ -219,6 +222,9 @@ the aforementioned cipher types:
219222
together with an IV generator (see geniv field in the /proc/crypto
220223
listing for the known IV generators)
221224

225+
- CRYPTO_ALG_TYPE_KPP Key-agreement Protocol Primitive (KPP) such as
226+
an ECDH or DH implementation
227+
222228
- CRYPTO_ALG_TYPE_DIGEST Raw message digest
223229

224230
- CRYPTO_ALG_TYPE_HASH Alias for CRYPTO_ALG_TYPE_DIGEST

‎include/crypto/dh.h

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,27 @@
1313
#ifndef _CRYPTO_DH_
1414
#define _CRYPTO_DH_
1515

16+
/**
17+
* DOC: DH Helper Functions
18+
*
19+
* To use DH with the KPP cipher API, the following data structure and
20+
* functions should be used.
21+
*
22+
* To use DH with KPP, the following functions should be used to operate on
23+
* a DH private key. The packet private key that can be set with
24+
* the KPP API function call of crypto_kpp_set_secret.
25+
*/
26+
27+
/**
28+
* struct dh - define a DH private key
29+
*
30+
* @key: Private DH key
31+
* @p: Diffie-Hellman parameter P
32+
* @g: Diffie-Hellman generator G
33+
* @key_size: Size of the private DH key
34+
* @p_size: Size of DH parameter P
35+
* @g_size: Size of DH generator G
36+
*/
1637
struct dh {
1738
void *key;
1839
void *p;
@@ -22,8 +43,45 @@ struct dh {
2243
unsigned int g_size;
2344
};
2445

46+
/**
47+
* crypto_dh_key_len() - Obtain the size of the private DH key
48+
* @params: private DH key
49+
*
50+
* This function returns the packet DH key size. A caller can use that
51+
* with the provided DH private key reference to obtain the required
52+
* memory size to hold a packet key.
53+
*
54+
* Return: size of the key in bytes
55+
*/
2556
int crypto_dh_key_len(const struct dh *params);
57+
58+
/**
59+
* crypto_dh_encode_key() - encode the private key
60+
* @buf: Buffer allocated by the caller to hold the packet DH
61+
* private key. The buffer should be at least crypto_dh_key_len
62+
* bytes in size.
63+
* @len: Length of the packet private key buffer
64+
* @params: Buffer with the caller-specified private key
65+
*
66+
* The DH implementations operate on a packet representation of the private
67+
* key.
68+
*
69+
* Return: -EINVAL if buffer has insufficient size, 0 on success
70+
*/
2671
int crypto_dh_encode_key(char *buf, unsigned int len, const struct dh *params);
72+
73+
/**
74+
* crypto_dh_decode_key() - decode a private key
75+
* @buf: Buffer holding a packet key that should be decoded
76+
* @len: Lenth of the packet private key buffer
77+
* @params: Buffer allocated by the caller that is filled with the
78+
* unpacket DH private key.
79+
*
80+
* The unpacking obtains the private key by pointing @p to the correct location
81+
* in @buf. Thus, both pointers refer to the same memory.
82+
*
83+
* Return: -EINVAL if buffer has insufficient size, 0 on success
84+
*/
2785
int crypto_dh_decode_key(const char *buf, unsigned int len, struct dh *params);
2886

2987
#endif

‎include/crypto/ecdh.h

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,18 +13,76 @@
1313
#ifndef _CRYPTO_ECDH_
1414
#define _CRYPTO_ECDH_
1515

16+
/**
17+
* DOC: ECDH Helper Functions
18+
*
19+
* To use ECDH with the KPP cipher API, the following data structure and
20+
* functions should be used.
21+
*
22+
* The ECC curves known to the ECDH implementation are specified in this
23+
* header file.
24+
*
25+
* To use ECDH with KPP, the following functions should be used to operate on
26+
* an ECDH private key. The packet private key that can be set with
27+
* the KPP API function call of crypto_kpp_set_secret.
28+
*/
29+
1630
/* Curves IDs */
1731
#define ECC_CURVE_NIST_P192 0x0001
1832
#define ECC_CURVE_NIST_P256 0x0002
1933

34+
/**
35+
* struct ecdh - define an ECDH private key
36+
*
37+
* @curve_id: ECC curve the key is based on.
38+
* @key: Private ECDH key
39+
* @key_size: Size of the private ECDH key
40+
*/
2041
struct ecdh {
2142
unsigned short curve_id;
2243
char *key;
2344
unsigned short key_size;
2445
};
2546

47+
/**
48+
* crypto_ecdh_key_len() - Obtain the size of the private ECDH key
49+
* @params: private ECDH key
50+
*
51+
* This function returns the packet ECDH key size. A caller can use that
52+
* with the provided ECDH private key reference to obtain the required
53+
* memory size to hold a packet key.
54+
*
55+
* Return: size of the key in bytes
56+
*/
2657
int crypto_ecdh_key_len(const struct ecdh *params);
58+
59+
/**
60+
* crypto_ecdh_encode_key() - encode the private key
61+
* @buf: Buffer allocated by the caller to hold the packet ECDH
62+
* private key. The buffer should be at least crypto_ecdh_key_len
63+
* bytes in size.
64+
* @len: Length of the packet private key buffer
65+
* @p: Buffer with the caller-specified private key
66+
*
67+
* The ECDH implementations operate on a packet representation of the private
68+
* key.
69+
*
70+
* Return: -EINVAL if buffer has insufficient size, 0 on success
71+
*/
2772
int crypto_ecdh_encode_key(char *buf, unsigned int len, const struct ecdh *p);
73+
74+
/**
75+
* crypto_ecdh_decode_key() - decode a private key
76+
* @buf: Buffer holding a packet key that should be decoded
77+
* @len: Lenth of the packet private key buffer
78+
* @p: Buffer allocated by the caller that is filled with the
79+
* unpacket ECDH private key.
80+
*
81+
* The unpacking obtains the private key by pointing @p to the correct location
82+
* in @buf. Thus, both pointers refer to the same memory.
83+
*
84+
* Return: -EINVAL if buffer has insufficient size, 0 on success
85+
*/
2886
int crypto_ecdh_decode_key(const char *buf, unsigned int len, struct ecdh *p);
2987

3088
#endif

‎include/crypto/kpp.h

Lines changed: 12 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -71,7 +71,7 @@ struct crypto_kpp {
7171
*
7272
* @reqsize: Request context size required by algorithm
7373
* implementation
74-
* @base Common crypto API algorithm data structure
74+
* @base: Common crypto API algorithm data structure
7575
*/
7676
struct kpp_alg {
7777
int (*set_secret)(struct crypto_kpp *tfm, void *buffer,
@@ -89,7 +89,7 @@ struct kpp_alg {
8989
};
9090

9191
/**
92-
* DOC: Generic Key-agreement Protocol Primitevs API
92+
* DOC: Generic Key-agreement Protocol Primitives API
9393
*
9494
* The KPP API is used with the algorithm type
9595
* CRYPTO_ALG_TYPE_KPP (listed as type "kpp" in /proc/crypto)
@@ -264,6 +264,12 @@ struct kpp_secret {
264264
* Function invokes the specific kpp operation for a given alg.
265265
*
266266
* @tfm: tfm handle
267+
* @buffer: Buffer holding the packet representation of the private
268+
* key. The structure of the packet key depends on the particular
269+
* KPP implementation. Packing and unpacking helpers are provided
270+
* for ECDH and DH (see the respective header files for those
271+
* implementations).
272+
* @len: Length of the packet private key buffer.
267273
*
268274
* Return: zero on success; error code in case of error
269275
*/
@@ -279,7 +285,10 @@ static inline int crypto_kpp_set_secret(struct crypto_kpp *tfm, void *buffer,
279285
* crypto_kpp_generate_public_key() - Invoke kpp operation
280286
*
281287
* Function invokes the specific kpp operation for generating the public part
282-
* for a given kpp algorithm
288+
* for a given kpp algorithm.
289+
*
290+
* To generate a private key, the caller should use a random number generator.
291+
* The output of the requested length serves as the private key.
283292
*
284293
* @req: kpp key request
285294
*

0 commit comments

Comments
 (0)