Skip to content

Commit

Permalink
document code
Browse files Browse the repository at this point in the history
  • Loading branch information
Pedro Paixao authored and Pedro Paixao committed Apr 17, 2016
1 parent 06868aa commit bcb51d3
Showing 1 changed file with 169 additions and 56 deletions.
225 changes: 169 additions & 56 deletions src/crypto_aead.cc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,10 +18,35 @@
*
* A typical use case for additional data is to store protocol-specific metadata
* about the message, such as its length and encoding.
*
* Supported Algorithms:
* * AES-GCM 256: API names use `aes256gcm`
* * ChaCha20-Poly1305: API names use `chacha20poly1305`
* * ChaCha20-Poly1305-IETF: API names use `chacha20poly1305-ietf`
*
* ### Modes
*
* #### Combined
* In combined mode, the authentication tag and the encrypted
* message are stored together. Functions return a buffer that includes the
* cipher text and authentication tag.
* Encrypt/Decrypt functions return a buffer with length equal to
* `message_length + crypto_aead_*_ABYTES` bytes.
*
* #### Detached
* In detached mode, the authentication tag and the encrypted
* message in different buffers. Detached function variants are named with the
* `_detached` sufix. Encrypt functions return:
*
* { cipherText: <buffer>, mac: <buffer> }
*
* ~ cipherText (Buffer): encrypted message
* ~ mac (Buffer): authentication tag (`crypto_aead_*_ABYTES` long)
*
*/

/**
* Crypto AEAD AES 256 GCM:
* Crypto AEAD AES-GCM 256:
*
* The current implementation of this construction is hardware-accelerated and
* requires the Intel SSSE3 extensions, as well as the aesni and pclmul
Expand All @@ -30,10 +55,52 @@
* Intel Westmere processors (introduced in 2010) and newer meet the requirements.
*
* There are no plans to support non hardware-accelerated implementations of
* AES-GCM. If portability is a concern, use ChaCha20-Poly1305 instead.
* [AES-GCM](https://en.wikipedia.org/wiki/Galois/Counter_Mode).
* If portability is a concern, use ChaCha20-Poly1305 instead.
*/

/** Low Level API: */

/**
* Precompute API:
*
* Speeding up the encryption/decryption process.
* The precompute API breaks down the encrypt/decrypt functions in two stages -
* "Before" and "After". The "before" stage is called once, everytime your
* application changes encryption keys. The "after" stage is called for every
* message you need to encrypt/decrypt.
* The functions `*_beforenm` implement the "before" stage, and the `*_afternm`
* the "after" stage. They offer the same functionality as their non-precompute
* counterparts but take a "state" object generated by the `*_beforenm` instead
* of an encryption key.
*
* **Sample**:
*
* var sodium = require('sodium').api;
*
* // Generate a random key
* var key = new Buffer(crypto_aead_aes256gcm_KEYBYTES);
* sodium.randombytes_buf(key);
*
* // Generate random nonce
* var nonce = new Buffer(crypto_aead_aes256gcm_KEYBYTES);
* sodium.randombytes_buf(nonce);
*
* // Precompute and generate the state
* var state = sodium.crypto_aead_aes256gcm_beforenm(key);
*
* var message = new Buffer("this is a plain text message");
* var additionalData = new Buffer("metadata");
*
* // Encrypt Data
* var cipherText = sodium.crypto_aead_aes256gcm_encrypt_afternm(
* message, additionalData, nonce, state);
*
* // Get the plain text, i.e., original message back
* var plainText = sodium.crypto_aead_aes256gcm_decrypt_afternm(
* cipherText, additionalData, nonce, state);
*/

/**
* crypto_aead_aes256gcm_is_available:
*
Expand Down Expand Up @@ -100,7 +167,7 @@ NAN_METHOD(bind_crypto_aead_aes256gcm_beforenm) {

/**
* crypto_aead_aes256gcm_encrypt_afternm:
* Encrypt data
* Encrypt data in Combined Mode
*
* var c = sodium.crypto_aead_aes256gcm_encrypt_afternm(
* message,
Expand All @@ -117,24 +184,7 @@ NAN_METHOD(bind_crypto_aead_aes256gcm_beforenm) {
*
* ~ cipherText (Buffer): The encrypted message, as well as a tag authenticating
* both the confidential message `message` and non-confidential data `additionalData`
*
* **Sample**:
*
* // Generate a random key
* var key = new Buffer(crypto_aead_aes256gcm_KEYBYTES);
* sodium.randombytes_buf(key);
*
* // Generate random nonce
* var nonce = new Buffer(crypto_aead_aes256gcm_KEYBYTES);
* sodium.randombytes_buf(nonce);
*
* // Precompute and generate the state
* var state = sodium.crypto_aead_aes256gcm_beforenm(key);
*
* var message = new Buffer("this is a plain text message");
* var additionalData = new Buffer("metadata");
* var cipherText = sodium.crypto_aead_aes256gcm_encrypt_afternm(
* message, additionalData, nonce, state);
* ~ undefined: if `message` fails to encrypt
*
*/
NAN_METHOD(bind_crypto_aead_aes256gcm_encrypt_afternm) {
Expand All @@ -156,17 +206,27 @@ NAN_METHOD(bind_crypto_aead_aes256gcm_encrypt_afternm) {
return info.GetReturnValue().Set(Nan::Undefined());
}

/*
int crypto_aead_aes256gcm_decrypt_afternm(unsigned char *m,
unsigned long long *mlen_p,
unsigned char *nsec,
const unsigned char *c,
unsigned long long clen,
const unsigned char *ad,
unsigned long long adlen,
const unsigned char *npub,
const crypto_aead_aes256gcm_state *ctx_)
*/
/**
* crypto_aead_aes256gcm_decrypt_afternm:
* Decrypt data in Combined Mode
*
* var c = sodium.crypto_aead_aes256gcm_decrypt_afternm(
* cipherText,
* additionalData,
* nonce,
* ctx);
*
* ~ cipherText (Buffer): cipher text buffer, encrypted by crypto_aead_aes256gcm_encrypt_afternm()
* ~ additionalData (Buffer): non-confidential data to add to the cipher text. Can be `null`
* ~ nonce (Buffer): a nonce with `sodium.crypto_aead_aes256gcm_NPUBBYTES` in length
* ~ ctx (Buffer): state computed by `crypto_aead_aes256gcm_beforenm()`
*
* **Returns**:
*
* ~ message (Buffer): plain text message
* ~ undefined: if `cipherText` is not valid
*
*/
NAN_METHOD(bind_crypto_aead_aes256gcm_decrypt_afternm) {
Nan::EscapableHandleScope scope;

Expand All @@ -191,18 +251,58 @@ NAN_METHOD(bind_crypto_aead_aes256gcm_decrypt_afternm) {
return info.GetReturnValue().Set(Nan::Undefined());
}

/*
int crypto_aead_aes256gcm_encrypt_detached_afternm(unsigned char *c,
unsigned char *mac,
unsigned long long *maclen_p,
const unsigned char *m,
unsigned long long mlen,
const unsigned char *ad,
unsigned long long adlen,
const unsigned char *nsec,
const unsigned char *npub,
const crypto_aead_aes256gcm_state *ctx_);
*/
/**
* crypto_aead_aes256gcm_encrypt_detached_afternm:
* Encrypt data in Detached Mode
*
* var c = sodium.crypto_aead_aes256gcm_encrypt_detached_afternm(
* message,
* additionalData,
* nonce,
* ctx);
*
* ~ message (Buffer): plain text buffer
* ~ additionalData (Buffer): non-confidential data to add to the cipher text.
* Can be `null`
* ~ nonce (Buffer): a nonce with `sodium.crypto_aead_aes256gcm_NPUBBYTES` in
* length
* ~ ctx (Buffer): state computed by `crypto_aead_aes256gcm_beforenm()`
*
* **Returns**:
*
* ~ object: `cipherText` buffer with ciphered text, and `mac` with the
* authentication tag
*
* { cipherText: <buffer>, mac: <buffer> }
*
* ~ undefined: if `message` fails to encrypt
*
* **Sample**:
*
* var sodium = require('sodium').api;
*
* // Generate a random key
* var key = new Buffer(crypto_aead_aes256gcm_KEYBYTES);
* sodium.randombytes_buf(key);
*
* // Generate random nonce
* var nonce = new Buffer(crypto_aead_aes256gcm_KEYBYTES);
* sodium.randombytes_buf(nonce);
*
* // Precompute and generate the state
* var state = sodium.crypto_aead_aes256gcm_beforenm(key);
*
* var message = new Buffer("this is a plain text message");
* var additionalData = new Buffer("metadata");
*
* // Encrypt Data
* var c = sodium.crypto_aead_aes256gcm_encrypt_detached_afternm(
* message, additionalData, nonce, state);
*
* // Get the plain text, i.e., original message back
* var plainText = sodium.crypto_aead_aes256gcm_decrypt_detached_afternm(
* c.cipherText, c.mac, nonce, state);
*/
NAN_METHOD(bind_crypto_aead_aes256gcm_encrypt_detached_afternm) {
Nan::EscapableHandleScope scope;

Expand All @@ -225,17 +325,30 @@ NAN_METHOD(bind_crypto_aead_aes256gcm_encrypt_detached_afternm) {
return info.GetReturnValue().Set(Nan::Undefined());
}

/*
int crypto_aead_aes256gcm_decrypt_detached_afternm(unsigned char *m,
unsigned char *nsec,
const unsigned char *c,
unsigned long long clen,
const unsigned char *mac,
const unsigned char *ad,
unsigned long long adlen,
const unsigned char *npub,
const crypto_aead_aes256gcm_state *ctx_)
*/
/**
* crypto_aead_aes256gcm_decrypt_detached_afternm:
* Encrypt data in Detached Mode
*
* var c = sodium.crypto_aead_aes256gcm_decrypt_detached_afternm(
* cipherText,
* mac,
* nonce,
* ctx);
*
* ~ cipherText (Buffer): cipher text buffer
* ~ mac (Buffer): authentication tag. Can be null
* ~ nonce (Buffer): a nonce with `sodium.crypto_aead_aes256gcm_NPUBBYTES` in
* length
* ~ ctx (Buffer): state computed by `crypto_aead_aes256gcm_beforenm()`
*
* **Returns**:
*
* ~ message (Buffer): plain text message
* ~ undefined: if `message` fails to encrypt
*
* See: [crypto_aead_aes256gcm_encrypt_detached_afternm](crypto_aead_aes256gcm_encrypt_detached_afternm)
*
*/
NAN_METHOD(bind_crypto_aead_aes256gcm_decrypt_detached_afternm) {
Nan::EscapableHandleScope scope;

Expand Down Expand Up @@ -264,7 +377,7 @@ CRYPTO_AEAD_DETACHED_DEF(chacha20poly1305)
CRYPTO_AEAD_DEF(chacha20poly1305_ietf)
CRYPTO_AEAD_DETACHED_DEF(chacha20poly1305_ietf)

/**
/*
* Register function calls in node binding
*/
void register_crypto_aead(Handle<Object> target) {
Expand Down

0 comments on commit bcb51d3

Please sign in to comment.