C Documentation

No implementation of Miscreant in C is presently available, however the Rust implementation of Miscreant exposes a C API/ABI which can be used in conjunction with C/C++ projects:

https://github.com/miscreant/miscreant/tree/master/rust

This guide will take you through installing Rust, building the Rust implementation of Miscreant as a static library, and provide an overview of the C API/ABI.

Installing Rust

You will need the Rust nightly toolchain. This can be installed with:

$ curl https://sh.rustup.rs -sSf | sh -s -- --default-toolchain nightly

For more information on installing Rust, please see https://rustup.rs/

Building libmiscreant.a

Miscreant's Rust implementation can be built as a standard C static library.

After installing Rust, clone the Miscreant repo:

$ git clone git@github.com:miscreant/miscreant.git

Inside of the rust/ subdirectory of this repo, run the following command to build libmiscreant.a:

cargo build --no-default-features --features=staticlib --release

This will create target/release/libmiscreant.a which exposes a C ABI and has no runtime dependencies.

Using libmiscreant.a in a C/C++ project.

The miscreant.h C header file describes libmiscreant.a's API.

Link libmiscreant.a as you normally would any static library, e.g.

cc -o myprog myprog.c libmiscreant.a

The Miscreant Rust FFI tests include an example Makefile for a Miscreant C project.

Symmetric Encryption (AEAD) API

The Authenticated Encryption with Associated Data (AEAD) API is the recommended API for encrypting and decrypting data with Miscreant. It accepts a nonce, associated data (i.e. data you'd like to authenticate along with the encrypted message), and a message to encrypt.

When decrypting, the same nonce and associated data must be supplied as were passed at the time of encryption. If anything is amiss, e.g. if the ciphertext has been tampered with, the cipher will detect it and return a decryption error.

crypto_aead_aes128siv_encrypt(): AES-128-SIV encryption

The crypto_aead_aes128siv_encrypt() function encrypts the given data with the AES-SIV algorithm at a 128-bit security level.

Prototype

int crypto_aead_aes128siv_encrypt(
    uint8_t *ct, uint64_t *ctlen_p,
    const uint8_t *msg, uint64_t msglen,
    const uint8_t *nonce, uint64_t noncelen,
    const uint8_t *ad, uint64_t adlen,
    const uint8_t *key
);

Parameters

• ct: pointer to a buffer into which the resulting ciphertext will be written
• ctlen_p: pointer to a uint64_t value which should initially be set to the size of the buffer *ct is pointing to. Upon successful encryption, this value will be set to the size of the resulting ciphertext.
• msg: pointer to a buffer containing the plaintext message
• msglen: length of the plaintext message
• nonce: pointer to a buffer containing a nonce value
• noncelen: length of the nonce value
• ad: pointer to a buffer containing associated data
• adlen: length of the associated data
• key: pointer to a 32-byte buffer (i.e. 2 * 128-bit) containing a uniformly random AES-SIV key

Return Value

The crypto_aead_aes128siv_encrypt() method returns 0 on success and -1 on error. Error conditions include:

• Insufficient space in the ct buffer for the resulting ciphertext

crypto_aead_aes128siv_decrypt(): TODO

crypto_aead_aes256siv_encrypt(): TODO

crypto_aead_aes256siv_decrypt(): TODO

crypto_aead_aes128pmacsiv_encrypt(): TODO

crypto_aead_aes128pmacsiv_decrypt(): TODO

crypto_aead_aes256pmacsiv_encrypt(): TODO

crypto_aead_aes256pmacsiv_decrypt(): TODO