1 /* rxgk/rxgk_crypto_rfc3961.c - Wrappers for RFC3961 crypto used in RXGK. */
3 * Copyright (C) 2013, 2014 by the Massachusetts Institute of Technology.
6 * Redistribution and use in source and binary forms, with or without
7 * modification, are permitted provided that the following conditions
10 * * Redistributions of source code must retain the above copyright
11 * notice, this list of conditions and the following disclaimer.
13 * * Redistributions in binary form must reproduce the above copyright
14 * notice, this list of conditions and the following disclaimer in
15 * the documentation and/or other materials provided with the
18 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
19 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
20 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
21 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
22 * COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
23 * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
24 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
25 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
27 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
28 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
29 * OF THE POSSIBILITY OF SUCH DAMAGE.
34 * Wrappers for the RFC3961 crypto routines used by RXGK, and
35 * helpers. This implementation uses the in-tree rfc3961 library, but
36 * we do not expose those types in our interface so as to be
37 * compatible with other backends in the future. It should be possible
38 * to backend to an out-of-tree krb5 library or the kernel's crypto
39 * framework using this API.
41 * Public functions in this file should return RXGK error codes, because
42 * error codes from these functions can end up on the wire. This will
43 * entail converting from any krb5 error codes that are used internally.
46 #include <afsconfig.h>
47 #include <afs/param.h>
51 # include "afs/sysincludes.h"
52 # include "afsincludes.h"
59 #include <afs/rfc3961.h>
62 #include "rxgk_private.h"
65 * This is what an rxgk_key really is, but it's a 'struct rxgk_key_s' to consumers:
66 * typedef struct rxgk_keyblock * rxgk_key;
68 struct rxgk_keyblock {
69 /* A krb5 context for this key, only to be used for initialization and
70 * destruction of the key. Do not use this for actually using the key for
71 * crypto operations; we are supposed to avoid accessing it in multiple
72 * threads at the same time. */
73 krb5_context init_ctx;
78 struct rxgk_keyblock keyblock;
81 /* Convenience macro; reduces the diff if an MIT krb5 backend is made. */
82 #define deref_keyblock_enctype(k) krb5_keyblock_get_enctype(k)
84 /* Convenience functions to convert between the opaque rxgk_key type and our
85 * internal rxgk_keyblock struct. */
86 static_inline struct rxgk_keyblock *
87 key2keyblock(rxgk_key key)
89 return &key->keyblock;
92 static_inline rxgk_key
93 keyblock2key(struct rxgk_keyblock *keyblock)
95 return (rxgk_key)keyblock;
99 * Convert krb5 error code to RXGK error code. Don't let the krb5 codes escape.
101 static_inline afs_int32
105 if (err >= ERROR_TABLE_BASE_RXGK && err < (ERROR_TABLE_BASE_RXGK + 256))
111 return RXGK_INCONSISTENCY;
116 * Convert a krb5 enctype to a krb5 checksum type.
118 * Each enctype has a mandatory (to implement) checksum type, which can be
119 * chosen when computing a checksum by passing 0 for the type parameter.
120 * However, we must separately compute the length of a checksum on a message in
121 * order to extract the checksum from a packet at RXGK_LEVEL_AUTH, and Heimdal
122 * krb5 does not expose a way to get the mandatory checksum type for a given
123 * enctype. So, we get to do it ourselves.
125 * @return -1 on failure, otherwise the checksum type.
127 static_inline afs_int32
128 etoc(afs_int32 etype)
131 case ETYPE_DES_CBC_CRC:
132 return CKSUMTYPE_RSA_MD5_DES;
133 case ETYPE_DES_CBC_MD4:
134 return CKSUMTYPE_RSA_MD4_DES;
135 case ETYPE_DES_CBC_MD5:
136 return CKSUMTYPE_RSA_MD5_DES;
137 case ETYPE_DES3_CBC_SHA1:
138 return CKSUMTYPE_HMAC_SHA1_DES3;
139 case ETYPE_ARCFOUR_MD4:
140 return CKSUMTYPE_HMAC_MD5_ENC;
141 case ETYPE_AES128_CTS_HMAC_SHA1_96:
142 return CKSUMTYPE_HMAC_SHA1_96_AES_128;
143 case ETYPE_AES256_CTS_HMAC_SHA1_96:
144 return CKSUMTYPE_HMAC_SHA1_96_AES_256;
151 * Get the number of octets of input needed for a key of the given etype,
153 * @return -1 on error, or the number of octets of input needed on success.
156 rxgk_etype_to_len(int etype)
159 krb5_error_code code;
162 code = krb5_init_context(&ctx);
165 code = krb5_enctype_keybits(ctx, etype, &bits);
166 krb5_free_context(ctx);
169 return (bits + 7) / 8;
173 * Take a raw key from some external source and produce an rxgk_key from it.
175 * The raw_key and length are not an RXGK_Data because in some cases they will
176 * come from a gss_buffer and there's no real need to do the conversion.
177 * The caller must use rxgk_release_key to deallocate memory allocated for the
180 * This routine checks whether the length of the supplied key data matches the
181 * key generation seed length for the requested enctype, in which case the RFC
182 * 3961 random_to_key operation is performed, or if it is the actual (output)
183 * key length, in which case the key data is used as-is.
185 * @param key_out the returned rxgk_key.
186 * @param raw_key a pointer to the octet stream of the key input data.
187 * @param length the length of raw_key (in octets).
188 * @param enctype the RFC 3961 enctype of the key being constructed.
189 * @return rxgk error codes.
192 rxgk_make_key(rxgk_key *key_out, void *raw_key, afs_uint32 length,
195 struct rxgk_keyblock *new_key = NULL;
198 ssize_t input_length;
200 /* Must initialize before we return. */
203 new_key = rxi_Alloc(sizeof(*new_key));
204 if (new_key == NULL) {
205 ret = RXGK_INCONSISTENCY;
208 ret = krb5_init_context(&new_key->init_ctx);
211 ret = krb5_enctype_keysize(new_key->init_ctx, enctype, &full_length);
214 input_length = rxgk_etype_to_len(enctype);
215 if (input_length < 0) {
216 ret = RXGK_INCONSISTENCY;
219 if (length == full_length) {
220 /* free with krb5_free_keyblock_contents + rxi_Free */
221 ret = krb5_keyblock_init(new_key->init_ctx, enctype, raw_key, length,
223 } else if (length == input_length) {
224 /* free with krb5_free_keyblock_contents + rxi_Free */
225 ret = krb5_random_to_key(new_key->init_ctx, enctype, raw_key, length,
232 *key_out = keyblock2key(new_key);
234 if (ret != 0 && new_key != NULL) {
235 krb5_free_context(new_key->init_ctx);
236 rxi_Free(new_key, sizeof(*new_key));
244 * The caller must use rxgk_release_key to deallocate the memory allocated
245 * for the new rxgk_key.
247 * @param[in] key_in The key to be copied.
248 * @param[out] key_out A copy of key_in.
249 * @return rxgk error codes.
252 rxgk_copy_key(rxgk_key key_in, rxgk_key *key_out)
254 struct rxgk_keyblock *keyblock;
256 keyblock = key2keyblock(key_in);
257 return rxgk_make_key(key_out, keyblock->key.keyvalue.data,
258 keyblock->key.keyvalue.length, keyblock->key.keytype);
262 * Generate a random key.
264 * The caller must use rxgk_release_key to deallocate the memory allocated
265 * for the new rxgk_key.
267 * @param[inout] enctype The RFC 3961 enctype of the key to be generated. If
268 * 0, set this to a default enctype, and use that
269 * enctype for the generated key.
270 * @param[out] key_out The random rxgk key.
271 * @return rxgk error codes.
274 rxgk_random_key(afs_int32 *enctype, rxgk_key *key_out)
284 *enctype = ETYPE_AES128_CTS_HMAC_SHA1_96;
286 len = rxgk_etype_to_len(*enctype);
288 return RXGK_INCONSISTENCY;
289 buf = rxi_Alloc(len);
291 return RXGK_INCONSISTENCY;
292 krb5_generate_random_block(buf, (size_t)len);
293 ret = rxgk_make_key(key_out, buf, len, *enctype);
299 * Release the storage underlying an rxgk key
301 * Call into the underlying library to release any storage allocated for
302 * the rxgk_key, and null out the key pointer.
305 rxgk_release_key(rxgk_key *key)
307 struct rxgk_keyblock *keyblock;
311 keyblock = key2keyblock(*key);
313 krb5_free_keyblock_contents(keyblock->init_ctx, &keyblock->key);
314 krb5_free_context(keyblock->init_ctx);
315 rxi_Free(keyblock, sizeof(*keyblock));
320 * Determine the length of a checksum (MIC) using the specified key.
322 * @param[in] key The rxgk_key being queried.
323 * @param[out] out The length of a checksum made using key.
324 * @return rxgk error codes.
327 rxgk_mic_length(rxgk_key key, size_t *out)
329 krb5_context ctx = NULL;
330 krb5_cksumtype cstype;
331 krb5_enctype enctype;
333 struct rxgk_keyblock *keyblock = key2keyblock(key);
338 ret = krb5_init_context(&ctx);
342 enctype = deref_keyblock_enctype(&keyblock->key);
343 cstype = etoc(enctype);
348 ret = krb5_checksumsize(ctx, cstype, &len);
354 krb5_free_context(ctx);
359 * Obtain the RFC 3961 Message Integrity Check of a buffer
361 * Call into the RFC 3961 encryption framework to obtain a Message Integrity
362 * Check of a buffer using the specified key and key usage. It is assumed
363 * that the rxgk_key structure includes the enctype information needed to
364 * determine which crypto routine to call.
366 * The output buffer is allocated with rx_opaque_populate() and must be freed
367 * by the caller (with rx_opaque_freeContents()).
369 * @param[in] key The key used to key the MIC.
370 * @param[in] usage The key usage value to use (from rxgk_int.h).
371 * @param[in] in The input buffer to be MICd.
372 * @param[out] out The MIC.
373 * @return rxgk error codes.
376 rxgk_mic_in_key(rxgk_key key, afs_int32 usage, RXGK_Data *in,
379 krb5_context ctx = NULL;
381 krb5_cksumtype cstype;
382 krb5_crypto crypto = NULL;
383 krb5_enctype enctype;
385 struct rxgk_keyblock *keyblock = key2keyblock(key);
388 memset(&cksum, 0, sizeof(cksum));
389 memset(out, 0, sizeof(*out));
391 ret = krb5_init_context(&ctx);
395 enctype = deref_keyblock_enctype(&keyblock->key);
396 cstype = etoc(enctype);
401 ret = krb5_checksumsize(ctx, cstype, &len);
404 ret = krb5_crypto_init(ctx, &keyblock->key, enctype, &crypto);
407 ret = krb5_create_checksum(ctx, crypto, usage, cstype, in->val,
412 if (len != cksum.checksum.length) {
413 ret = RXGK_INCONSISTENCY;
416 ret = rx_opaque_populate(out, cksum.checksum.data, len);
419 free_Checksum(&cksum);
421 krb5_crypto_destroy(ctx, crypto);
422 krb5_free_context(ctx);
427 * Verify the RFC 3961 Message Integrity Check on a message
429 * Call into the RFC 3961 encryption framework to verify a message integrity
430 * check on a message, using the specified key with the specified key usage.
431 * It is assumed that the rxgk_key structure includes the enctype information
432 * needed to determine which particular crypto routine to call.
434 * @param[in] key The key keying the checksum.
435 * @param[in] usage The key usage for the checksum.
436 * @param[in] in The buffer which was checksummed.
437 * @param[in] mic The MIC to be verified.
438 * @return rxgk error codes.
441 rxgk_check_mic_in_key(rxgk_key key, afs_int32 usage, RXGK_Data *in,
444 krb5_context ctx = NULL;
446 krb5_crypto crypto = NULL;
447 krb5_enctype enctype;
449 struct rxgk_keyblock *keyblock = key2keyblock(key);
451 memset(&cksum, 0, sizeof(cksum));
453 ret = krb5_init_context(&ctx);
457 enctype = deref_keyblock_enctype(&keyblock->key);
458 cksum.cksumtype = etoc(enctype);
459 ret = krb5_crypto_init(ctx, &keyblock->key, enctype, &crypto);
462 cksum.checksum.data = mic->val;
463 cksum.checksum.length = mic->len;
464 ret = krb5_verify_checksum(ctx, crypto, usage, in->val, in->len,
466 /* Un-alias the storage to avoid a double-free. */
467 cksum.checksum.data = NULL;
468 cksum.checksum.length = 0;
470 ret = RXGK_SEALED_INCON;
474 free_Checksum(&cksum);
476 krb5_crypto_destroy(ctx, crypto);
477 krb5_free_context(ctx);
482 * Encrypt a buffer in a key using the RFC 3961 framework
484 * Call into the RFC 3961 encryption framework to encrypt a buffer with
485 * specified key and key usage. It is assumed that the rxgk_key structure
486 * includes the enctype information needed to determine which particular
487 * crypto routine to call.
489 * The output buffer is allocated with rx_opaque_populate() and must be freed
490 * by the caller (with rx_opaque_freeContents()).
492 * @param[in] key The key used to encrypt the message.
493 * @param[in] usage The key usage for the encryption.
494 * @param[in] in The buffer being encrypted.
495 * @param[out] out The encrypted form of the message.
496 * @return rxgk error codes.
499 rxgk_encrypt_in_key(rxgk_key key, afs_int32 usage, RXGK_Data *in,
502 krb5_context ctx = NULL;
503 krb5_crypto crypto = NULL;
505 krb5_enctype enctype;
507 struct rxgk_keyblock *keyblock = key2keyblock(key);
509 memset(&kd_out, 0, sizeof(kd_out));
510 memset(out, 0, sizeof(*out));
512 ret = krb5_init_context(&ctx);
516 enctype = deref_keyblock_enctype(&keyblock->key);
517 ret = krb5_crypto_init(ctx, &keyblock->key, enctype, &crypto);
520 ret = krb5_encrypt(ctx, crypto, usage, in->val, in->len, &kd_out);
523 ret = rx_opaque_populate(out, kd_out.data, kd_out.length);
527 krb5_crypto_destroy(ctx, crypto);
528 krb5_data_free(&kd_out);
529 krb5_free_context(ctx);
534 * Decrypt a buffer using a given key in the RFC 3961 framework
536 * Call into the RFC 3961 encryption framework to decrypt a buffer with the
537 * specified key with the specified key usage. It is assumed that the
538 * rxgk_key structure includes the enctype information needed to determine
539 * which particular crypto routine to call.
541 * The output buffer is allocated with rx_opaque_populate() and must be freed
542 * by the caller (with rx_opaque_freeContents()).
544 * @param[in] key The key to use for the decryption.
545 * @param[in] usage The key usage used for the encryption.
546 * @param[in] in The encrypted message.
547 * @param[out] out The decrypted message.
548 * @return rxgk error codes.
551 rxgk_decrypt_in_key(rxgk_key key, afs_int32 usage, RXGK_Data *in,
554 krb5_context ctx = NULL;
555 krb5_crypto crypto = NULL;
557 krb5_enctype enctype;
559 struct rxgk_keyblock *keyblock = key2keyblock(key);
561 memset(out, 0, sizeof(*out));
562 memset(&kd_out, 0, sizeof(kd_out));
564 ret = krb5_init_context(&ctx);
568 enctype = deref_keyblock_enctype(&keyblock->key);
569 ret = krb5_crypto_init(ctx, &keyblock->key, enctype, &crypto);
572 ret = krb5_decrypt(ctx, crypto, usage, in->val, in->len, &kd_out);
574 ret = RXGK_SEALED_INCON;
577 ret = rx_opaque_populate(out, kd_out.data, kd_out.length);
581 krb5_crypto_destroy(ctx, crypto);
582 krb5_data_free(&kd_out);
583 krb5_free_context(ctx);
588 * Helper for derive_tk.
589 * Assumes the caller has already allocated space in 'out'.
592 PRFplus(krb5_data *out, krb5_enctype enctype, rxgk_key k0,
593 void *seed, size_t seed_len)
595 krb5_context ctx = NULL;
596 krb5_crypto crypto = NULL;
597 krb5_data prf_in, prf_out;
599 struct rxgk_keyblock *keyblock = key2keyblock(k0);
600 unsigned char *pre_key = NULL;
602 size_t desired_len = out->length;
603 afs_uint32 n_iter, iterations, dummy;
605 memset(&prf_in, 0, sizeof(prf_in));
606 memset(&prf_out, 0, sizeof(prf_out));
608 ret = krb5_init_context(&ctx);
612 ret = krb5_crypto_init(ctx, &keyblock->key, enctype, &crypto);
615 prf_in.length = sizeof(n_iter) + seed_len;
616 prf_in.data = rxi_Alloc(prf_in.length);
617 if (prf_in.data == NULL) {
618 ret = RXGK_INCONSISTENCY;
621 memcpy((unsigned char *)prf_in.data + sizeof(n_iter), seed, seed_len);
622 ret = krb5_crypto_prf_length(ctx, enctype, &block_len);
625 /* We need desired_len/block_len iterations, rounded up. */
626 iterations = (desired_len + block_len - 1) / block_len;
627 pre_key = rxi_Alloc(iterations * block_len);
628 if (pre_key == NULL) {
629 ret = RXGK_INCONSISTENCY;
633 for (n_iter = 1; n_iter <= iterations; ++n_iter) {
634 dummy = htonl(n_iter);
635 memcpy(prf_in.data, &dummy, sizeof(dummy));
636 krb5_data_free(&prf_out);
637 ret = krb5_crypto_prf(ctx, crypto, &prf_in, &prf_out);
640 memcpy(pre_key + (n_iter - 1) * block_len, prf_out.data, block_len);
642 memcpy(out->data, pre_key, desired_len);
643 out->length = desired_len;
647 krb5_crypto_destroy(ctx, crypto);
648 krb5_data_free(&prf_out);
649 krb5_free_context(ctx);
650 rxi_Free(prf_in.data, prf_in.length);
652 rxi_Free(pre_key, iterations * block_len);
661 afs_uint32 key_number;
662 } __attribute__((packed));
664 /* Our seed_data buffer that we feed into the PRF+ algorithm to generate our
665 * transport key had better be exactly 20 bytes large, to match the format of
666 * the seed data in the rxgk spec. */
667 #define RXGK_SEED_DATA_SIZE 20
670 * Compute a transport key tk given a master key k0
672 * Given a connection master key k0, derive a transport key tk from the master
673 * key and connection parameters.
675 * TK = random-to-key(PRF+(K0, L, epoch || cid || start_time || key_number))
676 * using the RFC4402 PRF+, i.e., the ordinal of the application of the
677 * pseudo-random() function is stored in a 32-bit field, not an 8-bit field
680 * @param[out] tk The derived transport key.
681 * @param[in] k0 The token master key.
682 * @param[in] epoch The rx epoch of the connection.
683 * @param[in] cid The rx connection id of the connection.
684 * @param[in] start_time The start_time of the connection.
685 * @param[in] key_number The current key number of the connection.
686 * @return rxgk error codes.
689 rxgk_derive_tk(rxgk_key *tk, rxgk_key k0, afs_uint32 epoch, afs_uint32 cid,
690 rxgkTime start_time, afs_uint32 key_number)
692 krb5_enctype enctype;
694 struct rxgk_keyblock *keyblock = key2keyblock(k0);
695 struct seed_data seed;
699 memset(&pre_key, 0, sizeof(pre_key));
700 memset(&seed, 0, sizeof(seed));
702 opr_StaticAssert(sizeof(seed) == RXGK_SEED_DATA_SIZE);
703 enctype = deref_keyblock_enctype(&keyblock->key);
704 ell = rxgk_etype_to_len(enctype);
706 return RXGK_INCONSISTENCY;
708 seed.epoch = htonl(epoch);
709 seed.cid = htonl(cid);
710 seed.time_hi = htonl((afs_int32)(start_time / ((afs_int64)1 << 32)));
711 seed.time_lo = htonl((afs_uint32)(start_time & (afs_uint64)0xffffffffu));
712 seed.key_number = htonl(key_number);
714 pre_key.data = rxi_Alloc(ell);
715 if (pre_key.data == NULL) {
716 ret = RXGK_INCONSISTENCY;
719 pre_key.length = ell;
720 ret = PRFplus(&pre_key, enctype, k0, &seed, sizeof(seed));
724 ret = rxgk_make_key(tk, pre_key.data, ell, enctype);
729 rxi_Free(pre_key.data, ell);
734 * Determine the maximum ciphertext expansion for a given enctype.
736 * @param[in] k0 The rxgk key to be used.
737 * @param[out] len_out The maximum ciphertext expansion, in octets.
738 * @return rxgk error codes.
741 rxgk_cipher_expansion(rxgk_key k0, afs_uint32 *len_out)
743 krb5_context ctx = NULL;
744 krb5_crypto crypto = NULL;
745 krb5_enctype enctype;
747 struct rxgk_keyblock *keyblock = key2keyblock(k0);
752 enctype = deref_keyblock_enctype(&keyblock->key);
753 ret = krb5_init_context(&ctx);
756 ret = krb5_crypto_init(ctx, &keyblock->key, enctype, &crypto);
759 len = krb5_crypto_overhead(ctx, crypto);
764 krb5_crypto_destroy(ctx, crypto);
765 krb5_free_context(ctx);
770 * Allocate and fill the buffer in nonce with len bytes of random data.
772 * @param[out] nonce The buffer of random data.
773 * @param[in] len The number of octets of random data to produce.
774 * @return rx error codes.
777 rxgk_nonce(RXGK_Data *nonce, afs_uint32 len)
779 if (rx_opaque_alloc(nonce, len) != 0)
780 return RXGK_INCONSISTENCY;
782 krb5_generate_random_block(nonce->val, len);