1 /*
2 * Diffie-Hellman secret to be used with kpp API along with helper functions
3 *
4 * Copyright (c) 2016, Intel Corporation
5 * Authors: Salvatore Benedetto <salvatore.benedetto@intel.com>
6 *
7 * This program is free software; you can redistribute it and/or modify it
8 * under the terms of the GNU General Public License as published by the Free
9 * Software Foundation; either version 2 of the License, or (at your option)
10 * any later version.
11 *
12 */
13 #ifndef _CRYPTO_DH_
14 #define _CRYPTO_DH_
15
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 * @q: Diffie-Hellman parameter Q
33 * @g: Diffie-Hellman generator G
34 * @key_size: Size of the private DH key
35 * @p_size: Size of DH parameter P
36 * @q_size: Size of DH parameter Q
37 * @g_size: Size of DH generator G
38 */
39 struct dh {
40 void *key;
41 void *p;
42 void *q;
43 void *g;
44 unsigned int key_size;
45 unsigned int p_size;
46 unsigned int q_size;
47 unsigned int g_size;
48 };
49
50 /**
51 * crypto_dh_key_len() - Obtain the size of the private DH key
52 * @params: private DH key
53 *
54 * This function returns the packet DH key size. A caller can use that
55 * with the provided DH private key reference to obtain the required
56 * memory size to hold a packet key.
57 *
58 * Return: size of the key in bytes
59 */
60 unsigned int crypto_dh_key_len(const struct dh *params);
61
62 /**
63 * crypto_dh_encode_key() - encode the private key
64 * @buf: Buffer allocated by the caller to hold the packet DH
65 * private key. The buffer should be at least crypto_dh_key_len
66 * bytes in size.
67 * @len: Length of the packet private key buffer
68 * @params: Buffer with the caller-specified private key
69 *
70 * The DH implementations operate on a packet representation of the private
71 * key.
72 *
73 * Return: -EINVAL if buffer has insufficient size, 0 on success
74 */
75 int crypto_dh_encode_key(char *buf, unsigned int len, const struct dh *params);
76
77 /**
78 * crypto_dh_decode_key() - decode a private key
79 * @buf: Buffer holding a packet key that should be decoded
80 * @len: Length of the packet private key buffer
81 * @params: Buffer allocated by the caller that is filled with the
82 * unpacked DH private key.
83 *
84 * The unpacking obtains the private key by pointing @p to the correct location
85 * in @buf. Thus, both pointers refer to the same memory.
86 *
87 * Return: -EINVAL if buffer has insufficient size, 0 on success
88 */
89 int crypto_dh_decode_key(const char *buf, unsigned int len, struct dh *params);
90
91 #endif
92
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.