| 1 | /* -*-c-*- |
| 2 | * |
| 3 | * The OCB1 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 OCB1 -----------------------------------------------------* |
| 29 | * |
| 30 | * OCB was designed in 2001 by Phillip Rogaway, with Mihir Bellare and John |
| 31 | * Black, as a blockcipher-based authenticated encryption scheme which can |
| 32 | * operate on multiple message blocks in parallel and requires only a single |
| 33 | * blockcipher application per message block. It refines Charanjit Jutla's |
| 34 | * earlier IAPM, which was the first such mode to be proven secure. This |
| 35 | * version implements the `OCB.PMAC' mode described by Rogaway in 2002, which |
| 36 | * combines the original OCB with PMAC (Rogaway and Black, 2002) into a |
| 37 | * single authenticated-encryption with associated-data (AEAD) scheme. |
| 38 | * |
| 39 | * The patent situation on these efficient authenticated encryption schemes |
| 40 | * is fraught. IBM hold two patents on Jutla's pioneering work on `IACBC' |
| 41 | * and `IAPM' which can apply (a third was filed at least six years too |
| 42 | * late), and Virgil Gligor and Pompiliu Donescu hold patents on their `XECB' |
| 43 | * and `XCBC' modes; these may or may not apply to OCB. Rogaway himself |
| 44 | * holds US patents on various versions of OCB, but has issued free licences |
| 45 | * for free (`open source') software, and for all non-military use. I think |
| 46 | * Catacomb's implementation of OCB falls within the scope of the former |
| 47 | * licence. |
| 48 | * |
| 49 | * Confusingly, Rogaway's 2004 paper `Efficient Instantiations of Tweakable |
| 50 | * Blockciphers and Refinements to Modes OCB and PMAC' named the new versions |
| 51 | * of those modes `OCB1' and `PMAC1'. The 2011 paper by Krovetz and Rogaway, |
| 52 | * `The Software Performance of Authenticated-Encryption Modes' renamed the |
| 53 | * original 2001 version of OCB as `OCB1', and the 2004 version `OCB2', and |
| 54 | * introduced a new `OCB3'. I've decided to follow and extend the 2011 |
| 55 | * naming, so `OCB1' refers to the 2001 OCB; the 2004 version would be |
| 56 | * `OCB2'. |
| 57 | * |
| 58 | * The OCB specification is clear about how OCB applies to arbitrary block |
| 59 | * sizes. |
| 60 | * |
| 61 | * OCB1 is a fairly well-behaved AEAD mode. It doesn't require |
| 62 | * precommentment to any lengths, and allows header data to be processed |
| 63 | * independently of any message. On the other hand, it only accepts nonces |
| 64 | * the same size as the underlying blockcipher's block size, and it buffers |
| 65 | * up to a whole block's worth of data internally, which somewhat complicates |
| 66 | * streaming. |
| 67 | */ |
| 68 | |
| 69 | #ifndef CATACOMB_OCB1_H |
| 70 | #define CATACOMB_OCB1_H |
| 71 | |
| 72 | #ifdef __cplusplus |
| 73 | extern "C" { |
| 74 | #endif |
| 75 | |
| 76 | /*----- Header files ------------------------------------------------------*/ |
| 77 | |
| 78 | #include <stddef.h> |
| 79 | |
| 80 | #include <mLib/bits.h> |
| 81 | #include <mLib/buf.h> |
| 82 | |
| 83 | #ifndef CATACOMB_GAEAD_H |
| 84 | # include "gaead.h" |
| 85 | #endif |
| 86 | |
| 87 | #ifndef CATACOMB_OCB_H |
| 88 | # include "ocb.h" |
| 89 | #endif |
| 90 | |
| 91 | #ifndef CATACOMB_RSVR_H |
| 92 | # include "rsvr.h" |
| 93 | #endif |
| 94 | |
| 95 | /*----- Macros ------------------------------------------------------------*/ |
| 96 | |
| 97 | /* --- @OCB1_DECL@ --- * |
| 98 | * |
| 99 | * Arguments: @PRE@, @pre@ = prefixes for the underlying block cipher |
| 100 | * |
| 101 | * Use: Creates declarations for OCB1 message-authentication mode. |
| 102 | */ |
| 103 | |
| 104 | #define OCB1_STRUCTS(PRE, pre, keyty, aadty) \ |
| 105 | \ |
| 106 | typedef struct keyty { \ |
| 107 | pre##_ctx ctx; /* Underlying cipher context */ \ |
| 108 | uint32 lxinv[PRE##_BLKSZ/4]; /* Final-block mask */ \ |
| 109 | uint32 lmask[OCB_NCALC][PRE##_BLKSZ/4]; /* Precalculated masks */ \ |
| 110 | } keyty; \ |
| 111 | \ |
| 112 | typedef struct aadty { \ |
| 113 | keyty k; /* Processed key material */ \ |
| 114 | uint32 o[PRE##_BLKSZ/4]; /* Current offset */ \ |
| 115 | uint32 a[PRE##_BLKSZ/4]; /* Accumulator state */ \ |
| 116 | octet b[PRE##_BLKSZ]; /* Input buffer */ \ |
| 117 | unsigned long i; /* Block counter */ \ |
| 118 | unsigned off; /* Offset into buffered data */ \ |
| 119 | } aadty; |
| 120 | |
| 121 | #define OCB1_DECL(PRE, pre) \ |
| 122 | \ |
| 123 | OCB1_STRUCTS(PRE, pre, pre##_ocb1key, pre##_ocb1aadctx) \ |
| 124 | \ |
| 125 | typedef struct pre##_ocb1ctx { \ |
| 126 | /* This is the same as @pre_ocb1aadctx@ above, but the two are \ |
| 127 | * logically distinct and shouldn't be muddled up. \ |
| 128 | */ \ |
| 129 | \ |
| 130 | pre##_ocb1key k; /* Processed key material */ \ |
| 131 | uint32 o[PRE##_BLKSZ/4]; /* Current offset */ \ |
| 132 | uint32 a[PRE##_BLKSZ/4]; /* Accumulator state */ \ |
| 133 | octet b[PRE##_BLKSZ]; /* Input buffer */ \ |
| 134 | unsigned long i; /* Block counter */ \ |
| 135 | unsigned off; /* Offset into buffered data */ \ |
| 136 | } pre##_ocb1ctx; \ |
| 137 | \ |
| 138 | extern const rsvr_policy pre##_ocb1policy; \ |
| 139 | \ |
| 140 | extern const octet pre##_ocb1noncesz[], pre##_ocb1tagsz[]; \ |
| 141 | \ |
| 142 | /* --- @pre_ocb1setkey@ --- * \ |
| 143 | * \ |
| 144 | * Arguments: @pre_ocb1key *key@ = pointer to key block to fill in \ |
| 145 | * @const void *k@ = pointer to key material \ |
| 146 | * @size_t ksz@ = size of key material \ |
| 147 | * \ |
| 148 | * Returns: --- \ |
| 149 | * \ |
| 150 | * Use: Initializes an OCB1 key block. \ |
| 151 | */ \ |
| 152 | \ |
| 153 | extern void pre##_ocb1setkey(pre##_ocb1key */*key*/, \ |
| 154 | const void */*k*/, size_t /*ksz*/); \ |
| 155 | \ |
| 156 | /* --- @pre_ocb1aadinit@ --- * \ |
| 157 | * \ |
| 158 | * Arguments: @pre_ocb1aadctx *aad@ = pointer to AAD context \ |
| 159 | * @const pre_ocb1key *key@ = pointer to key block \ |
| 160 | * \ |
| 161 | * Returns: --- \ |
| 162 | * \ |
| 163 | * Use: Initializes an OCB1 AAD (`additional authenticated \ |
| 164 | * data') context associated with a given key. AAD \ |
| 165 | * contexts can be copied and/or reused, saving time if \ |
| 166 | * the AAD for number of messages has a common prefix. \ |
| 167 | * \ |
| 168 | * The @key@ doesn't need to be kept around, though \ |
| 169 | * usually there'll at least be another copy in some OCB1 \ |
| 170 | * operation context because the AAD on its own isn't much \ |
| 171 | * good. \ |
| 172 | */ \ |
| 173 | \ |
| 174 | extern void pre##_ocb1aadinit(pre##_ocb1aadctx */*aad*/, \ |
| 175 | const pre##_ocb1key */*key*/); \ |
| 176 | \ |
| 177 | /* --- @pre_ocb1aadhash@ --- * \ |
| 178 | * \ |
| 179 | * Arguments: @pre_ocb1aadctx *aad@ = pointer to AAD context \ |
| 180 | * @const void *p@ = pointer to AAD material \ |
| 181 | * @size_t sz@ = length of AAD material \ |
| 182 | * \ |
| 183 | * Returns: --- \ |
| 184 | * \ |
| 185 | * Use: Feeds AAD into the context. \ |
| 186 | */ \ |
| 187 | \ |
| 188 | extern void pre##_ocb1aadhash(pre##_ocb1aadctx */*aad*/, \ |
| 189 | const void */*p*/, size_t /*sz*/); \ |
| 190 | \ |
| 191 | /* --- @pre_ocb1aadtag@ --- * \ |
| 192 | * \ |
| 193 | * Arguments: @const pre_ocb1aadctx *aad@ = pointer to context block \ |
| 194 | * @uint32 *u@ = where to write the tag \ |
| 195 | * \ |
| 196 | * Returns: --- \ |
| 197 | * \ |
| 198 | * Use: Finishes processing AAD and produces a tag which can be \ |
| 199 | * mixed with an OCB1 checksum. This function is exposed \ |
| 200 | * for internal reasons and is not expected to be \ |
| 201 | * generally useful. \ |
| 202 | */ \ |
| 203 | \ |
| 204 | extern void pre##_ocb1aadtag(const pre##_ocb1aadctx */*aad*/, \ |
| 205 | uint32 */*t*/); \ |
| 206 | \ |
| 207 | /* --- @pre_ocb1init@ --- * \ |
| 208 | * \ |
| 209 | * Arguments: @pre_ocb1ctx *ctx@ = pointer to OCB1 context \ |
| 210 | * @const pre_ocb1key *key@ = pointer to key block \ |
| 211 | * @const void *n@ = pointer to nonce \ |
| 212 | * @size_t nsz@ = size of nonce \ |
| 213 | * \ |
| 214 | * Returns: Zero on success, @-1@ if the nonce length is bad. \ |
| 215 | * \ |
| 216 | * Use: Initialize an OCB1 operation context with a given key. \ |
| 217 | * \ |
| 218 | * The original key needn't be kept around any more. \ |
| 219 | */ \ |
| 220 | \ |
| 221 | extern int pre##_ocb1init(pre##_ocb1ctx */*ctx*/, \ |
| 222 | const pre##_ocb1key */*k*/, \ |
| 223 | const void */*n*/, size_t /*nsz*/); \ |
| 224 | \ |
| 225 | /* --- @pre_ocb1reinit@ --- * \ |
| 226 | * \ |
| 227 | * Arguments: @pre_ocb1ctx *ctx@ = pointer to OCB1 context \ |
| 228 | * @const void *n@ = pointer to nonce \ |
| 229 | * @size_t nsz@ = size of nonce \ |
| 230 | * \ |
| 231 | * Returns: Zero on success, @-1@ if the nonce length is bad. \ |
| 232 | * \ |
| 233 | * Use: Reinitialize an OCB1 operation context, changing the \ |
| 234 | * nonce. \ |
| 235 | */ \ |
| 236 | \ |
| 237 | extern int pre##_ocb1reinit(pre##_ocb1ctx */*ctx*/, \ |
| 238 | const void */*n*/, size_t /*nsz*/); \ |
| 239 | \ |
| 240 | /* --- @pre_ocb1encrypt@ --- * \ |
| 241 | * \ |
| 242 | * Arguments: @pre_ocb1ctx *ctx@ = pointer to OCB1 operation context \ |
| 243 | * @const void *src@ = pointer to plaintext message chunk \ |
| 244 | * @size_t sz@ = size of the plaintext \ |
| 245 | * @buf *dst@ = a buffer to write the ciphertext to \ |
| 246 | * \ |
| 247 | * Returns: Zero on success; @-1@ on failure. \ |
| 248 | * \ |
| 249 | * Use: Encrypts a chunk of a plaintext message, writing a \ |
| 250 | * chunk of ciphertext to the output buffer and updating \ |
| 251 | * the operation state. \ |
| 252 | * \ |
| 253 | * Note that OCB1 delays output if its input is not a \ |
| 254 | * whole number of blocks. This means that the output \ |
| 255 | * might be smaller or larger the input by up to the block \ |
| 256 | * size. \ |
| 257 | */ \ |
| 258 | \ |
| 259 | extern int pre##_ocb1encrypt(pre##_ocb1ctx */*ctx*/, \ |
| 260 | const void */*src*/, size_t /*sz*/, \ |
| 261 | buf */*dst*/); \ |
| 262 | \ |
| 263 | /* --- @pre_ocb1decrypt@ --- * \ |
| 264 | * \ |
| 265 | * Arguments: @pre_ocb1ctx *ctx@ = pointer to OCB1 operation context \ |
| 266 | * @const void *src@ = pointer to ciphertext message chunk \ |
| 267 | * @size_t sz@ = size of the ciphertext \ |
| 268 | * @buf *dst@ = a buffer to write the plaintext to \ |
| 269 | * \ |
| 270 | * Returns: Zero on success; @-1@ on failure. \ |
| 271 | * \ |
| 272 | * Use: Decrypts a chunk of a ciphertext message, writing a \ |
| 273 | * chunk of plaintext to the output buffer and updating \ |
| 274 | * the operation state. \ |
| 275 | * \ |
| 276 | * Note that OCB1 delays output if its input is not a \ |
| 277 | * whole number of blocks. This means that the output \ |
| 278 | * might be smaller or larger the input by up to the block \ |
| 279 | * size. \ |
| 280 | */ \ |
| 281 | \ |
| 282 | extern int pre##_ocb1decrypt(pre##_ocb1ctx */*ctx*/, \ |
| 283 | const void */*src*/, size_t /*sz*/, \ |
| 284 | buf */*dst*/); \ |
| 285 | \ |
| 286 | /* --- @pre_ocb1encryptdone@ --- * \ |
| 287 | * \ |
| 288 | * Arguments: @pre_ocb1ctx *ctx@ = pointer to an OCB1 context \ |
| 289 | * @const pre_ocb1aadctx *aad@ = pointer to AAD context, \ |
| 290 | * or null \ |
| 291 | * @buf *dst@ = buffer for remaining ciphertext \ |
| 292 | * @void *tag@ = where to write the tag \ |
| 293 | * @size_t tsz@ = length of tag to store \ |
| 294 | * \ |
| 295 | * Returns: Zero on success; @-1@ on failure. \ |
| 296 | * \ |
| 297 | * Use: Completes an OCB1 encryption operation. The @aad@ \ |
| 298 | * pointer may be null if there is no additional \ |
| 299 | * authenticated data. OCB1 delays output, so this will \ |
| 300 | * cause any remaining buffered plaintext to be encrypted \ |
| 301 | * and written to @dst@. Anyway, the function will fail \ |
| 302 | * if the output buffer is broken. \ |
| 303 | */ \ |
| 304 | \ |
| 305 | extern int pre##_ocb1encryptdone(pre##_ocb1ctx */*ctx*/, \ |
| 306 | const pre##_ocb1aadctx */*aad*/, \ |
| 307 | buf */*dst*/, \ |
| 308 | void */*tag*/, size_t /*tsz*/); \ |
| 309 | \ |
| 310 | /* --- @pre_ocb1decryptdone@ --- * \ |
| 311 | * \ |
| 312 | * Arguments: @pre_ocb1ctx *ctx@ = pointer to an OCB1 context \ |
| 313 | * @const pre_ocb1aadctx *aad@ = pointer to AAD context, \ |
| 314 | * or null \ |
| 315 | * @buf *dst@ = buffer for remaining plaintext \ |
| 316 | * @const void *tag@ = tag to verify \ |
| 317 | * @size_t tsz@ = length of tag \ |
| 318 | * \ |
| 319 | * Returns: @+1@ for complete success; @0@ if tag verification \ |
| 320 | * failed; @-1@ for other kinds of errors. \ |
| 321 | * \ |
| 322 | * Use: Completes an OCB1 decryption operation. The @aad@ \ |
| 323 | * pointer may be null if there is no additional \ |
| 324 | * authenticated data. OCB1 delays output, so this will \ |
| 325 | * cause any remaining buffered ciphertext to be decrypted \ |
| 326 | * and written to @dst@. Anyway, the function will fail \ |
| 327 | * if the output buffer is broken. \ |
| 328 | */ \ |
| 329 | \ |
| 330 | extern int pre##_ocb1decryptdone(pre##_ocb1ctx */*ctx*/, \ |
| 331 | const pre##_ocb1aadctx */*aad*/, \ |
| 332 | buf */*dst*/, \ |
| 333 | const void */*tag*/, size_t /*tsz*/); \ |
| 334 | \ |
| 335 | /* --- Generic AEAD interface --- */ \ |
| 336 | \ |
| 337 | extern const gcaead pre##_ocb1; |
| 338 | |
| 339 | /*----- That's all, folks -------------------------------------------------*/ |
| 340 | |
| 341 | #ifdef __cplusplus |
| 342 | } |
| 343 | #endif |
| 344 | |
| 345 | #endif |