1# libaes_siv 2 3This is an [RFC5297](https://tools.ietf.org/html/rfc5297)-compliant C 4implementation of AES-SIV written by Daniel Franke on behalf of 5[Akamai Technologies](https://www.akamai.com). It is published under 6the [Apache License 7(v2.0)](https://www.apache.org/licenses/LICENSE-2.0). It uses OpenSSL 8for the underlying 9[AES](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard) and 10[CMAC](https://en.wikipedia.org/wiki/One-key_MAC) implementations and 11follows a similar interface style. 12 13An AES_SIV implementation forked from libaes_siv has been [merged into 14the OpenSSL master branch](https://github.com/openssl/openssl/pull/3540). 15However, the two implementations are not API-compatible; see section 16"OpenSSL API Comparison" below. 17 18## Overview of SIV mode 19 20Synthetic Initialization Vector (SIV) mode is a [block cipher mode of 21operation](https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation) 22for [authenticated encryption with associated 23data](https://en.wikipedia.org/wiki/Authenticated_encryption) designed 24to be maximally resistant to accidental 25[nonce](https://en.wikipedia.org/wiki/Cryptographic_nonce) reuse. If 26two messages are accidentally encrypted using the same nonce and the 27same associated data, the attacker learns nothing except whether or 28not the plaintexts of the two messages are identical to each other. 29SIV mode also permits the nonce to be intentionally omitted, resulting 30in a [deterministic encryption 31scheme](https://en.wikipedia.org/wiki/Deterministic_encryption). 32 33Here are a couple common situations where AES-SIV may be an 34appropriate choice of AEAD scheme: 35 361. You can't count on the system doing the encrypting to reliably 37 generate a unique nonce for every message. For example, the system 38 may be an embedded device with no good entropy source, or may be a 39 VM subject to be snapshotted and restored. 40 412. You want your encryption to be deterministic so that an 42 intermediating party such as a caching proxy, provided only with 43 ciphertext, can perform deduplication. 44 45The drawback to SIV mode is that it requires two passes over its 46input. This makes it potentially clumsy for use with large messages 47since the entire message must be held in memory at one time. SIV mode 48is also a bit slower than most widely-used block cipher modes (but 49can still be quite fast — see performance numbers below). 50 51Be aware that with *any* encryption scheme, including SIV, repeating 52or omitting a nonce can still be [fatal to 53security](https://xkcd.com/257) if your plaintexts have low entropy, 54e.g., if each message consists only of a single bit. 55 56Keys for SIV mode are twice the length of the keys for the underlying 57block cipher. For example, keys for AES-128-SIV are 256 bits long, 58and keys for AES-256-SIV are 512 bits long. 59 60## Build instructions 61 62Build dependencies: 63 64* Any ISO C89 compiler (GCC or Clang recommended). No C99 language 65 features are required, however `<stdint.h>` must be available and 66 must define `uint64_t`. `char` must be 8 bits and arithmetic must be 67 two's complement. 68* [CMake](https://cmake.org) >= 3.1 69* [OpenSSL](https://openssl.org) >=1.0.1 (libcrypto only). A recent 70 release from the 1.0.2 branch or later is strongly recommended since 71 1.0.1 was EOL'ed at the end of 2016. Furthermore, OpenSSL versions prior 72 to 1.0.1n and 1.0.2b have known bugs which impact `libaes_siv` and 73 will cause failures in its test suite. LibreSSL is not supported. 74* [Asciidoc](http://asciidoc.org) (only required for building man pages) 75 76Running benchmarks requires a POSIX.1-2001 compliant OS, including 77the `clock_gettime` system call. 78 79To build and install on POSIX-like platforms: 80``` 81 cmake . && 82 make && 83 make test && 84 sudo make install 85``` 86 87NOTE: Out-of-source builds are allowed, but out-of-source manpage builds 88require a2x's -D option, which may provoke an apparently bogus warning from a2x. 89 90If you want to build on an OS X machine, install the Xcode development 91environment and the command line tools, then use either the Homebrew package 92manager or the MacPorts package manager to install cmake and OpenSSL. 93 94Homebrew (https://brew.sh/): 95``` 96 brew install cmake openssl && 97 cmake -DCMAKE_PREFIX_PATH=/usr/local/opt/openssl . && 98 make && 99 make test && 100 sudo make install 101``` 102MacPorts (https://www.macports.org/): 103``` 104 sudo port install cmake openssl && 105 cmake . && 106 make && 107 make test && 108 sudo make install 109``` 110 111To create a native Windows build, you will first need to build 112OpenSSL. Install Visual Studio, CMake, ActiveState Perl, and NASM, and 113ensure that `nasm.exe` is somewhere in your `%PATH%`. From a VS developer 114command prompt, unpack the OpenSSL sources and run 115``` 116 perl Configure VC-WIN64A 117 nmake 118``` 119Then to build `libaes_siv`, run 120``` 121 cmake -G "NMake Makefiles" -DOPENSSL_ROOT_DIR=\path\to\openssl . 122 nmake 123 nmake test 124``` 125 126## Usage 127 128See the manual pages for API documentation, and the test vectors 129in `tests.c` for simple usage examples. You can also use the `demo` command 130line program to encrypt and decrypt data. 131 132## OpenSSL API Comparison 133 134In December 2018, OpenSSL merged an AES-SIV implementation derived 135from libaes_siv. As of February 2019 this implementation has not been 136released yet; it will appear some time post-1.1.1. However, despite 137the two implementations' common ancestry, they are not API-compatible. 138The OpenSSL team had to make an ugly-but-necessary compromise in order 139to shoehorn SIV mode into OpenSSL's EVP API, which is a streaming API 140that was never designed to support SIV's two-pass operation. When used for 141SIV operations, the EVP API is forced to return an error if you invoke 142`EVP_(En|De)crypt_Update` more than once for the same message. 143 144When designing libaes_siv, I rejected this behavior as an unacceptable 145breakdown of the API contract and opted to dispense with the EVP 146abstraction altogether rather than permit it to leak. libaes_siv's API 147remains stylistically similar to EVP, but is nonetheless distinct and 148avoids the above pitfall. 149 150## Performance 151 152On the author's Intel Core i7-6560U laptop, libaes_siv can process 153approximately 796 MiB of plaintext or ciphertext or 963 MiB of 154associated data per second using 256-bit keys 155(i.e., AES-128). Encrypting a zero-byte message takes approximately 156990ns. To obtain numbers for your own system, run `make bench && 157./bench`. 158 159## Software assurance 160 161libaes_siv's test suite includes all test vectors from RFC 5297 and 162achieves 100% code coverage according to 163[gcov](https://gcc.gnu.org/onlinedocs/gcc/Gcov.html). It produces 164clean output from [Valgrind](https://valgrind.org) and from Clang's 165[undefined behavior 166sanitizer](https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html), 167and is verified using [ctgrind](https://github.com/agl/ctgrind) to run 168in constant time. 169 170Nonetheless, libaes_siv should at present be considered beta-quality 171code. It has not yet been tested on platforms other than x86-64 Linux 172or benefited from any significant amount of user feedback, and 173the codebase is in need of additional review by cryptographers and 174expert C programmers. 175 176## Bugs and pull requests 177 178Use the GitHub issue tracker. For reporting sensitive security issues, 179contact the author directly. (Note: I no longer use PGP. Please 180request my Signal details if necessary). 181 182## A note on version numbers 183 184libaes_siv version numbers are of the form `<major>.<minor>.<patch>` 185and follow a semantic versioning scheme. The major version number 186will be incremented with any backward-incompatible ABI change. The 187minor version number will be incremented if new functionality is 188added without impacting ABI backward-compatibility. The patch 189version number will be incremented for releases that make no 190externally-visible changes. 191 192As a result of this scheme, on ELF platforms, the .so version will 193be the same as the release version. 194 195Version numbers indicate nothing about code quality or maturity. No 196code known or suspected to be less suitable for production use than 197previous releases will ever be tagged with a version number. 198