| 1 | /* -*-c-*- |
| 2 | * |
| 3 | * The OCB3 authenticated encryption mode |
| 4 | * |
| 5 | * (c) 2018 Straylight/Edgeware |
| 6 | */ |
| 7 | |
| 8 | /*----- Licensing notice --------------------------------------------------* |
| 9 | * |
| 10 | * This file is part of Catacomb. |
| 11 | * |
| 12 | * Catacomb is free software: you can redistribute it and/or modify it |
| 13 | * under the terms of the GNU Library General Public License as published |
| 14 | * by the Free Software Foundation; either version 2 of the License, or |
| 15 | * (at your option) any later version. |
| 16 | * |
| 17 | * Catacomb is distributed in the hope that it will be useful, but |
| 18 | * WITHOUT ANY WARRANTY; without even the implied warranty of |
| 19 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
| 20 | * Library General Public License for more details. |
| 21 | * |
| 22 | * You should have received a copy of the GNU Library General Public |
| 23 | * License along with Catacomb. If not, write to the Free Software |
| 24 | * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, |
| 25 | * USA. |
| 26 | */ |
| 27 | |
| 28 | /*----- Notes on OCB3 -----------------------------------------------------* |
| 29 | * |
| 30 | * OCB3 was designed in 2011 by Phillip Rogaway and Ted Krovetz, building ten |
| 31 | * years of earlier work by Rogaway, Bellare, and Black, and refining Jutla's |
| 32 | * pioneering work on IACBC and IAPM. OCB3 is an efficient `authenticated |
| 33 | * encryption with associated data' (AEAD) scheme which requires only one |
| 34 | * blockcipher application per message block. |
| 35 | * |
| 36 | * The patent situation on these efficient authenticated encryption schemes |
| 37 | * is fraught. IBM hold two patents on Jutla's pioneering work on `IACBC' |
| 38 | * and `IAPM' which can apply (a third was filed at least six years too |
| 39 | * late), and Virgil Gligor and Pompiliu Donescu hold patents on their `XECB' |
| 40 | * and `XCBC' modes; these may or may not apply to OCB. Rogaway himself |
| 41 | * holds US patents on various versions of OCB, but has issued free licences |
| 42 | * for free (`open source') software, and for all non-military use. I think |
| 43 | * Catacomb's implementation of OCB falls within the scope of the former |
| 44 | * licence. |
| 45 | * |
| 46 | * OCB3 has optimized for short messages with `similar' nonces, where |
| 47 | * `similar' means `all but the low bits in the last byte are equal'; exactly |
| 48 | * how many bits depends on the block length in a rather complicated manner. |
| 49 | * This implementation supports this optimization through @pre_ocb3reinit@ |
| 50 | * (which compares the new nonce against the old one to see whether it can |
| 51 | * make use of the similarity), and, more directly, through @pre_ocb3step@, |
| 52 | * which (effectively) advances the nonce as a big-endian counter. |
| 53 | * |
| 54 | * OCB3 was originally defined only for 128-bit blockciphers, and extending |
| 55 | * it to other sizes is nontrivial, but this has been done by Ted Krovetz in |
| 56 | * I-D draft-krovetz-ocb-wideblock-00 (following initial prompting from, err, |
| 57 | * me). |
| 58 | * |
| 59 | * OCB3 is a fairly well-behaved AEAD mode. It doesn't require |
| 60 | * precommentment to the header or message lengths, but does require |
| 61 | * precommitment to the tag length. It permits header data to be processed |
| 62 | * independently of any message. It only accepts nonces the same size as the |
| 63 | * underlying blockcipher's block size, and it buffers up to a whole block's |
| 64 | * worth of data internally, which somewhat complicates streaming. |
| 65 | */ |
| 66 | |
| 67 | #ifndef CATACOMB_OCB3_H |
| 68 | #define CATACOMB_OCB3_H |
| 69 | |
| 70 | #ifdef __cplusplus |
| 71 | extern "C" { |
| 72 | #endif |
| 73 | |
| 74 | /*----- Header files ------------------------------------------------------*/ |
| 75 | |
| 76 | #include <stddef.h> |
| 77 | |
| 78 | #include <mLib/bits.h> |
| 79 | #include <mLib/buf.h> |
| 80 | |
| 81 | #ifndef CATACOMB_GAEAD_H |
| 82 | # include "gaead.h" |
| 83 | #endif |
| 84 | |
| 85 | #ifndef CATACOMB_OCB_H |
| 86 | # include "ocb.h" |
| 87 | #endif |
| 88 | |
| 89 | /*----- Macros ------------------------------------------------------------*/ |
| 90 | |
| 91 | /* --- @OCB3_DECL@ --- * |
| 92 | * |
| 93 | * Arguments: @PRE@, @pre@ = prefixes for the underlying block cipher |
| 94 | * |
| 95 | * Use: Creates declarations for OCB3 message-authentication mode. |
| 96 | */ |
| 97 | |
| 98 | #define OCB3_NSZMAX(PRE) (PRE##_BLKSZ - (PRE##_BLKSZ <= 16 ? 1 : 2)) |
| 99 | |
| 100 | #define OCB3_DECL(PRE, pre) \ |
| 101 | \ |
| 102 | typedef struct pre##_ocb3key { \ |
| 103 | pre##_ctx ctx; /* Underlying cipher context */ \ |
| 104 | uint32 lstar[PRE##_BLKSZ/4]; /* Partial-block mask */ \ |
| 105 | uint32 ldollar[PRE##_BLKSZ/4]; /* Checksum mask */ \ |
| 106 | uint32 lmask[OCB_NCALC][PRE##_BLKSZ/4]; /* Precalculated masks */ \ |
| 107 | } pre##_ocb3key; \ |
| 108 | \ |
| 109 | typedef struct pre##_ocb3aadctx { \ |
| 110 | pre##_ocb3key k; /* Processed key material */ \ |
| 111 | uint32 o[PRE##_BLKSZ/4]; /* Current offset */ \ |
| 112 | uint32 a[PRE##_BLKSZ/4]; /* Accumulator state */ \ |
| 113 | octet b[PRE##_BLKSZ]; /* Input buffer */ \ |
| 114 | unsigned long i; /* Block counter */ \ |
| 115 | unsigned off; /* Offset into buffered data */ \ |
| 116 | } pre##_ocb3aadctx; \ |
| 117 | \ |
| 118 | typedef struct pre##_ocb3ctx { \ |
| 119 | pre##_ocb3key k; /* Processed key material */ \ |
| 120 | unsigned nix, tsz; /* Nonce index and tag size */ \ |
| 121 | uint32 nbase[PRE##_BLKSZ/2]; /* Current base nonce */ \ |
| 122 | uint32 nstretch[PRE##_BLKSZ/2]; /* Stretched nonce material */ \ |
| 123 | uint32 o[PRE##_BLKSZ/4]; /* Current offset */ \ |
| 124 | uint32 a[PRE##_BLKSZ/4]; /* Accumulator state */ \ |
| 125 | octet b[PRE##_BLKSZ]; /* Input buffer */ \ |
| 126 | unsigned long i; /* Block counter */ \ |
| 127 | unsigned off; /* Offset into buffered data */ \ |
| 128 | } pre##_ocb3ctx; \ |
| 129 | \ |
| 130 | extern const octet pre##_ocb3noncesz[], pre##_ocb3tagsz[]; \ |
| 131 | \ |
| 132 | /* --- @pre_ocb3setkey@ --- * \ |
| 133 | * \ |
| 134 | * Arguments: @pre_ocb3key *key@ = pointer to key block to fill in \ |
| 135 | * @const void *k@ = pointer to key material \ |
| 136 | * @size_t ksz@ = size of key material \ |
| 137 | * \ |
| 138 | * Returns: --- \ |
| 139 | * \ |
| 140 | * Use: Initializes an OCB3 key block. \ |
| 141 | */ \ |
| 142 | \ |
| 143 | extern void pre##_ocb3setkey(pre##_ocb3key */*key*/, \ |
| 144 | const void */*k*/, size_t /*ksz*/); \ |
| 145 | \ |
| 146 | /* --- @pre_ocb3aadinit@ --- * \ |
| 147 | * \ |
| 148 | * Arguments: @pre_ocb3aadctx *aad@ = pointer to AAD context \ |
| 149 | * @const pre_ocb3key *key@ = pointer to key block \ |
| 150 | * \ |
| 151 | * Returns: --- \ |
| 152 | * \ |
| 153 | * Use: Initializes an OCB3 AAD (`additional authenticated \ |
| 154 | * data') context associated with a given key. AAD \ |
| 155 | * contexts can be copied and/or reused, saving time if \ |
| 156 | * the AAD for number of messages has a common prefix. \ |
| 157 | * \ |
| 158 | * The @key@ doesn't need to be kept around, though \ |
| 159 | * usually there'll at least be another copy in some OCB3 \ |
| 160 | * operation context because the AAD on its own isn't much \ |
| 161 | * good. \ |
| 162 | */ \ |
| 163 | \ |
| 164 | extern void pre##_ocb3aadinit(pre##_ocb3aadctx */*aad*/, \ |
| 165 | const pre##_ocb3key */*key*/); \ |
| 166 | \ |
| 167 | /* --- @pre_ocb3aadhash@ --- * \ |
| 168 | * \ |
| 169 | * Arguments: @pre_ocb3aadctx *aad@ = pointer to AAD context \ |
| 170 | * @const void *p@ = pointer to AAD material \ |
| 171 | * @size_t sz@ = length of AAD material \ |
| 172 | * \ |
| 173 | * Returns: --- \ |
| 174 | * \ |
| 175 | * Use: Feeds AAD into the context. \ |
| 176 | */ \ |
| 177 | \ |
| 178 | extern void pre##_ocb3aadhash(pre##_ocb3aadctx */*aad*/, \ |
| 179 | const void */*p*/, size_t /*sz*/); \ |
| 180 | \ |
| 181 | /* --- @pre_ocb3init@ --- * \ |
| 182 | * \ |
| 183 | * Arguments: @pre_ocb3ctx *ctx@ = pointer to OCB3 context \ |
| 184 | * @const pre_ocb3key *key@ = pointer to key block \ |
| 185 | * @const void *n@ = pointer to nonce \ |
| 186 | * @size_t nsz@ = size of nonce \ |
| 187 | * @size_t tsz@ = tag length \ |
| 188 | * \ |
| 189 | * Returns: Zero on success, @-1@ if the nonce or tag length is \ |
| 190 | * bad. \ |
| 191 | * \ |
| 192 | * Use: Initialize an OCB3 operation context with a given key. \ |
| 193 | * \ |
| 194 | * The original key needn't be kept around any more. \ |
| 195 | */ \ |
| 196 | \ |
| 197 | extern int pre##_ocb3init(pre##_ocb3ctx */*ctx*/, \ |
| 198 | const pre##_ocb3key */*k*/, \ |
| 199 | const void */*n*/, size_t /*nsz*/, \ |
| 200 | size_t /*tsz*/); \ |
| 201 | \ |
| 202 | /* --- @pre_ocb3reinit@ --- * \ |
| 203 | * \ |
| 204 | * Arguments: @pre_ocb3ctx *ctx@ = pointer to OCB3 context \ |
| 205 | * @const void *n@ = pointer to nonce \ |
| 206 | * @size_t nsz@ = size of nonce \ |
| 207 | * @size_t tsz@ = tag length \ |
| 208 | * \ |
| 209 | * Returns: Zero on success, @-1@ if the nonce or tag length is \ |
| 210 | * bad. \ |
| 211 | * \ |
| 212 | * Use: Reinitialize an OCB3 operation context, changing the \ |
| 213 | * nonce and/or tag length. \ |
| 214 | */ \ |
| 215 | \ |
| 216 | extern int pre##_ocb3reinit(pre##_ocb3ctx */*ctx*/, \ |
| 217 | const void */*n*/, size_t /*nsz*/, \ |
| 218 | size_t /*tsz*/); \ |
| 219 | \ |
| 220 | /* --- @pre_ocb3step@ --- * \ |
| 221 | * \ |
| 222 | * Arguments: @pre_ocb3ctx *ctx@ = pointer to OCB3 context \ |
| 223 | * \ |
| 224 | * Returns: --- \ |
| 225 | * \ |
| 226 | * Use: Reinitialize an OCB3 operation context, stepping to \ |
| 227 | * the `next' nonce along. \ |
| 228 | */ \ |
| 229 | \ |
| 230 | extern void pre##_ocb3step(pre##_ocb3ctx */*ctx*/); \ |
| 231 | \ |
| 232 | /* --- @pre_ocb3encrypt@ --- * \ |
| 233 | * \ |
| 234 | * Arguments: @pre_ocb3ctx *ctx@ = pointer to OCB3 operation context \ |
| 235 | * @const void *src@ = pointer to plaintext message chunk \ |
| 236 | * @size_t sz@ = size of the plaintext \ |
| 237 | * @buf *dst@ = a buffer to write the ciphertext to \ |
| 238 | * \ |
| 239 | * Returns: Zero on success; @-1@ on failure. \ |
| 240 | * \ |
| 241 | * Use: Encrypts a chunk of a plaintext message, writing a \ |
| 242 | * chunk of ciphertext to the output buffer and updating \ |
| 243 | * the operation state. \ |
| 244 | * \ |
| 245 | * Note that OCB3 delays output if its input is not a \ |
| 246 | * whole number of blocks. This means that the output \ |
| 247 | * might be smaller or larger the input by up to the block \ |
| 248 | * size. \ |
| 249 | */ \ |
| 250 | \ |
| 251 | extern int pre##_ocb3encrypt(pre##_ocb3ctx */*ctx*/, \ |
| 252 | const void */*src*/, size_t /*sz*/, \ |
| 253 | buf */*dst*/); \ |
| 254 | \ |
| 255 | /* --- @pre_ocb3decrypt@ --- * \ |
| 256 | * \ |
| 257 | * Arguments: @pre_ocb3ctx *ctx@ = pointer to OCB3 operation context \ |
| 258 | * @const void *src@ = pointer to ciphertext message chunk \ |
| 259 | * @size_t sz@ = size of the ciphertext \ |
| 260 | * @buf *dst@ = a buffer to write the plaintext to \ |
| 261 | * \ |
| 262 | * Returns: Zero on success; @-1@ on failure. \ |
| 263 | * \ |
| 264 | * Use: Decrypts a chunk of a ciphertext message, writing a \ |
| 265 | * chunk of plaintext to the output buffer and updating \ |
| 266 | * the operation state. \ |
| 267 | * \ |
| 268 | * Note that OCB3 delays output if its input is not a \ |
| 269 | * whole number of blocks. This means that the output \ |
| 270 | * might be smaller or larger the input by up to the block \ |
| 271 | * size. \ |
| 272 | */ \ |
| 273 | \ |
| 274 | extern int pre##_ocb3decrypt(pre##_ocb3ctx */*ctx*/, \ |
| 275 | const void */*src*/, size_t /*sz*/, \ |
| 276 | buf */*dst*/); \ |
| 277 | \ |
| 278 | /* --- @pre_ocb3encryptdone@ --- * \ |
| 279 | * \ |
| 280 | * Arguments: @pre_ocb3ctx *ctx@ = pointer to an OCB3 context \ |
| 281 | * @const pre_ocb3aadctx *aad@ = pointer to AAD context, \ |
| 282 | * or null \ |
| 283 | * @buf *dst@ = buffer for remaining ciphertext \ |
| 284 | * @void *tag@ = where to write the tag \ |
| 285 | * @size_t tsz@ = length of tag to store \ |
| 286 | * \ |
| 287 | * Returns: Zero on success; @-1@ on failure. \ |
| 288 | * \ |
| 289 | * Use: Completes an OCB3 encryption operation. The @aad@ \ |
| 290 | * pointer may be null if there is no additional \ |
| 291 | * authenticated data. OCB3 delays output, so this will \ |
| 292 | * cause any remaining buffered plaintext to be encrypted \ |
| 293 | * and written to @dst@. Anyway, the function will fail \ |
| 294 | * if the output buffer is broken. \ |
| 295 | */ \ |
| 296 | \ |
| 297 | extern int pre##_ocb3encryptdone(pre##_ocb3ctx */*ctx*/, \ |
| 298 | const pre##_ocb3aadctx */*aad*/, \ |
| 299 | buf */*dst*/, \ |
| 300 | void */*tag*/, size_t /*tsz*/); \ |
| 301 | \ |
| 302 | /* --- @pre_ocb3decryptdone@ --- * \ |
| 303 | * \ |
| 304 | * Arguments: @pre_ocb3ctx *ctx@ = pointer to an OCB3 context \ |
| 305 | * @const pre_ocb3aadctx *aad@ = pointer to AAD context, \ |
| 306 | * or null \ |
| 307 | * @buf *dst@ = buffer for remaining plaintext \ |
| 308 | * @const void *tag@ = tag to verify \ |
| 309 | * @size_t tsz@ = length of tag \ |
| 310 | * \ |
| 311 | * Returns: @+1@ for complete success; @0@ if tag verification \ |
| 312 | * failed; @-1@ for other kinds of errors. \ |
| 313 | * \ |
| 314 | * Use: Completes an OCB3 decryption operation. The @aad@ \ |
| 315 | * pointer may be null if there is no additional \ |
| 316 | * authenticated data. OCB3 delays output, so this will \ |
| 317 | * cause any remaining buffered ciphertext to be decrypted \ |
| 318 | * and written to @dst@. Anyway, the function will fail \ |
| 319 | * if the output buffer is broken. \ |
| 320 | */ \ |
| 321 | \ |
| 322 | extern int pre##_ocb3decryptdone(pre##_ocb3ctx */*ctx*/, \ |
| 323 | const pre##_ocb3aadctx */*aad*/, \ |
| 324 | buf */*dst*/, \ |
| 325 | const void */*tag*/, size_t /*tsz*/); \ |
| 326 | \ |
| 327 | /* --- Generic AEAD interface --- */ \ |
| 328 | \ |
| 329 | extern const gcaead pre##_ocb3; |
| 330 | |
| 331 | /*----- That's all, folks -------------------------------------------------*/ |
| 332 | |
| 333 | #ifdef __cplusplus |
| 334 | } |
| 335 | #endif |
| 336 | |
| 337 | #endif |