Debian Codegraph @

Documentation/crypto/krb5.rst

raw
1 .. SPDX-License-Identifier: GPL-2.0
2
3 ===========================
4 Kerberos V Cryptography API
5 ===========================
6
7 .. Contents:
8
9 - Overview.
10 - Small Buffer.
11 - Encoding Type.
12 - Key Derivation.
13 - PRF+ Calculation.
14 - Kc, Ke And Ki Derivation.
15 - Crypto Functions.
16 - Preparation Functions.
17 - Encryption Mode.
18 - Checksum Mode.
19 - The krb5enc AEAD algorithm
20
21 Overview
22 ========
23
24 This API provides Kerberos 5-style cryptography for key derivation, encryption
25 and checksumming for use in network filesystems and can be used to implement
26 the low-level crypto that's needed for GSSAPI.
27
28 The following crypto types are supported::
29
30 KRB5_ENCTYPE_AES128_CTS_HMAC_SHA1_96
31 KRB5_ENCTYPE_AES256_CTS_HMAC_SHA1_96
32 KRB5_ENCTYPE_AES128_CTS_HMAC_SHA256_128
33 KRB5_ENCTYPE_AES256_CTS_HMAC_SHA384_192
34 KRB5_ENCTYPE_CAMELLIA128_CTS_CMAC
35 KRB5_ENCTYPE_CAMELLIA256_CTS_CMAC
36
37 KRB5_CKSUMTYPE_HMAC_SHA1_96_AES128
38 KRB5_CKSUMTYPE_HMAC_SHA1_96_AES256
39 KRB5_CKSUMTYPE_CMAC_CAMELLIA128
40 KRB5_CKSUMTYPE_CMAC_CAMELLIA256
41 KRB5_CKSUMTYPE_HMAC_SHA256_128_AES128
42 KRB5_CKSUMTYPE_HMAC_SHA384_192_AES256
43
44 The API can be included by::
45
46 #include <crypto/krb5.h>
47
48 Small Buffer
49 ------------
50
51 To pass small pieces of data about, such as keys, a buffer structure is
52 defined, giving a pointer to the data and the size of that data::
53
54 struct krb5_buffer {
55 unsigned int len;
56 void *data;
57 };
58
59 Encoding Type
60 =============
61
62 The encoding type is defined by the following structure::
63
64 struct krb5_enctype {
65 int etype;
66 int ctype;
67 const char *name;
68 u16 key_bytes;
69 u16 key_len;
70 u16 Kc_len;
71 u16 Ke_len;
72 u16 Ki_len;
73 u16 prf_len;
74 u16 block_len;
75 u16 conf_len;
76 u16 cksum_len;
77 ...
78 };
79
80 The fields of interest to the user of the API are as follows:
81
82 * ``etype`` and ``ctype`` indicate the protocol number for this encoding
83 type for encryption and checksumming respectively. They hold
84 ``KRB5_ENCTYPE_*`` and ``KRB5_CKSUMTYPE_*`` constants.
85
86 * ``name`` is the formal name of the encoding.
87
88 * ``key_len`` and ``key_bytes`` are the input key length and the derived key
89 length. (I think they only differ for DES, which isn't supported here).
90
91 * ``Kc_len``, ``Ke_len`` and ``Ki_len`` are the sizes of the derived Kc, Ke
92 and Ki keys. Kc is used for in checksum mode; Ke and Ki are used in
93 encryption mode.
94
95 * ``prf_len`` is the size of the result from the PRF+ function calculation.
96
97 * ``block_len``, ``conf_len`` and ``cksum_len`` are the encryption block
98 length, confounder length and checksum length respectively. All three are
99 used in encryption mode, but only the checksum length is used in checksum
100 mode.
101
102 The encoding type is looked up by number using the following function::
103
104 const struct krb5_enctype *crypto_krb5_find_enctype(u32 enctype);
105
106 Key Derivation
107 ==============
108
109 Once the application has selected an encryption type, the keys that will be
110 used to do the actual crypto can be derived from the transport key.
111
112 PRF+ Calculation
113 ----------------
114
115 To aid in key derivation, a function to calculate the Kerberos GSSAPI
116 mechanism's PRF+ is provided::
117
118 int crypto_krb5_calc_PRFplus(const struct krb5_enctype *krb5,
119 const struct krb5_buffer *K,
120 unsigned int L,
121 const struct krb5_buffer *S,
122 struct krb5_buffer *result,
123 gfp_t gfp);
124
125 This can be used to derive the transport key from a source key plus additional
126 data to limit its use.
127
128 Crypto Functions
129 ================
130
131 Once the keys have been derived, crypto can be performed on the data. The
132 caller must leave gaps in the buffer for the storage of the confounder (if
133 needed) and the checksum when preparing a message for transmission. An enum
134 and a pair of functions are provided to aid in this::
135
136 enum krb5_crypto_mode {
137 KRB5_CHECKSUM_MODE,
138 KRB5_ENCRYPT_MODE,
139 };
140
141 size_t crypto_krb5_how_much_buffer(const struct krb5_enctype *krb5,
142 enum krb5_crypto_mode mode,
143 size_t data_size, size_t *_offset);
144
145 size_t crypto_krb5_how_much_data(const struct krb5_enctype *krb5,
146 enum krb5_crypto_mode mode,
147 size_t *_buffer_size, size_t *_offset);
148
149 All these functions take the encoding type and an indication the mode of crypto
150 (checksum-only or full encryption).
151
152 The first function returns how big the buffer will need to be to house a given
153 amount of data; the second function returns how much data will fit in a buffer
154 of a particular size, and adjusts down the size of the required buffer
155 accordingly. In both cases, the offset of the data within the buffer is also
156 returned.
157
158 When a message has been received, the location and size of the data with the
159 message can be determined by calling::
160
161 int crypto_krb5_where_is_the_data(const struct krb5_enctype *krb5,
162 enum krb5_crypto_mode mode,
163 size_t *_offset, size_t *_len);
164
165 The caller provides the offset and length of the message to the function, which
166 then alters those values to indicate the region containing the data (plus any
167 padding). It is up to the caller to determine how much padding there is. The
168 function returns an error if the length is too small or if the mode is
169 unsupported. An additional function::
170
171 int crypto_krb5_check_data_len(const struct krb5_enctype *krb5,
172 enum krb5_crypto_mode mode,
173 size_t len, size_t min_content);
174
175 is provided to just do a basic check that the decrypted/verified message would
176 have a sufficient minimum payload.
177
178 Preparation Functions
179 ---------------------
180
181 Two functions are provided to allocated and prepare a crypto object for use by
182 the action functions::
183
184 struct crypto_aead *
185 crypto_krb5_prepare_encryption(const struct krb5_enctype *krb5,
186 const struct krb5_buffer *TK,
187 u32 usage, gfp_t gfp);
188 struct crypto_shash *
189 crypto_krb5_prepare_checksum(const struct krb5_enctype *krb5,
190 const struct krb5_buffer *TK,
191 u32 usage, gfp_t gfp);
192
193 Both of these functions take the encoding type, the transport key and the usage
194 value used to derive the appropriate subkey(s). They create an appropriate
195 crypto object, an AEAD template for encryption and a synchronous hash for
196 checksumming, set the key(s) on it and configure it. The caller is expected to
197 pass these handles to the action functions below.
198
199 Encryption Mode
200 ---------------
201
202 A pair of functions are provided to encrypt and decrypt a message::
203
204 ssize_t crypto_krb5_encrypt(const struct krb5_enctype *krb5,
205 struct crypto_aead *aead,
206 struct scatterlist *sg, unsigned int nr_sg,
207 size_t sg_len,
208 size_t data_offset, size_t data_len,
209 bool preconfounded);
210 int crypto_krb5_decrypt(const struct krb5_enctype *krb5,
211 struct crypto_aead *aead,
212 struct scatterlist *sg, unsigned int nr_sg,
213 size_t *_offset, size_t *_len);
214
215 In both cases, the input and output buffers are indicated by the same
216 scatterlist.
217
218 For the encryption function, the output buffer may be larger than is needed
219 (the amount of output generated is returned) and the location and size of the
220 data are indicated (which must match the encoding). If no confounder is set,
221 the function will insert one.
222
223 For the decryption function, the offset and length of the message in buffer are
224 supplied and these are shrunk to fit the data. The decryption function will
225 verify any checksums within the message and give an error if they don't match.
226
227 Checksum Mode
228 -------------
229
230 A pair of function are provided to generate the checksum on a message and to
231 verify that checksum::
232
233 ssize_t crypto_krb5_get_mic(const struct krb5_enctype *krb5,
234 struct crypto_shash *shash,
235 const struct krb5_buffer *metadata,
236 struct scatterlist *sg, unsigned int nr_sg,
237 size_t sg_len,
238 size_t data_offset, size_t data_len);
239 int crypto_krb5_verify_mic(const struct krb5_enctype *krb5,
240 struct crypto_shash *shash,
241 const struct krb5_buffer *metadata,
242 struct scatterlist *sg, unsigned int nr_sg,
243 size_t *_offset, size_t *_len);
244
245 In both cases, the input and output buffers are indicated by the same
246 scatterlist. Additional metadata can be passed in which will get added to the
247 hash before the data.
248
249 For the get_mic function, the output buffer may be larger than is needed (the
250 amount of output generated is returned) and the location and size of the data
251 are indicated (which must match the encoding).
252
253 For the verification function, the offset and length of the message in buffer
254 are supplied and these are shrunk to fit the data. An error will be returned
255 if the checksums don't match.
256
257 The krb5enc AEAD algorithm
258 ==========================
259
260 A template AEAD crypto algorithm, called "krb5enc", is provided that hashes the
261 plaintext before encrypting it (the reverse of authenc). The handle returned
262 by ``crypto_krb5_prepare_encryption()`` may be one of these, but there's no
263 requirement for the user of this API to interact with it directly.
264
265 For reference, its key format begins with a BE32 of the format number. Only
266 format 1 is provided and that continues with a BE32 of the Ke key length
267 followed by a BE32 of the Ki key length, followed by the bytes from the Ke key
268 and then the Ki key.
269
270 Using specifically ordered words means that the static test data doesn't
271 require byteswapping.