NaCl: Networking and Cryptography library

Public-key authenticated encryption: crypto_box

C++ interface

     #include "crypto_box.h"          std::string pk;     std::string sk;          pk = crypto_box_keypair(&sk);

Thecrypto_box_keypair functionrandomly generates a secret key and a corresponding public key.It puts the secret key intoskand returns the public key.It guarantees thatsk hascrypto_box_SECRETKEYBYTES bytesand thatpk hascrypto_box_PUBLICKEYBYTES bytes.

C++ NaCl also provides acrypto_box functioncallable as follows:

     #include "crypto_box.h"          std::string pk;     std::string sk;     std::string n;     std::string m;     std::string c;     c = crypto_box(m,n,pk,sk);

Thecrypto_box functionencrypts and authenticates a messagemusing the sender's secret keysk,the receiver's public keypk,and a noncen.Thecrypto_box functionreturns the resulting ciphertextc.The function raises an exceptionifsk.size() is notcrypto_box_SECRETKEYBYTESor ifpk.size() is notcrypto_box_PUBLICKEYBYTESor ifn.size() is notcrypto_box_NONCEBYTES.

C++ NaCl also provides acrypto_box_open functioncallable as follows:

     #include "crypto_box.h"          std::string pk;     std::string sk;     std::string n;     std::string c;     std::string m;     m = crypto_box_open(c,n,pk,sk);

Thecrypto_box_open functionverifies and decrypts a ciphertextcusing the receiver's secret keysk,the sender's public keypk,and a noncen.Thecrypto_box_open functionreturns the resulting plaintextm.

If the ciphertext fails verification,crypto_box_open raises an exception.The function also raises an exceptionifsk.size() is notcrypto_box_SECRETKEYBYTESor ifpk.size() is notcrypto_box_PUBLICKEYBYTESor ifn.size() is notcrypto_box_NONCEBYTES.

C interface

     #include "crypto_box.h"          unsigned char pk[crypto_box_PUBLICKEYBYTES];     unsigned char sk[crypto_box_SECRETKEYBYTES];          crypto_box_keypair(pk,sk);

Thecrypto_box_keypair functionrandomly generates a secret key and a corresponding public key.It puts the secret key intosk[0],sk[1], ...,sk[crypto_box_SECRETKEYBYTES-1]and puts the public key intopk[0],pk[1], ...,pk[crypto_box_PUBLICKEYBYTES-1].It then returns 0.

C NaCl also provides acrypto_box functioncallable as follows:

     #include "crypto_box.h"          const unsigned char pk[crypto_box_PUBLICKEYBYTES];     const unsigned char sk[crypto_box_SECRETKEYBYTES];     const unsigned char n[crypto_box_NONCEBYTES];     const unsigned char m[...]; unsigned long long mlen;     unsigned char c[...];          crypto_box(c,m,mlen,n,pk,sk);

Thecrypto_box functionencrypts and authenticates a messagem[0], ...,m[mlen-1]using the sender's secret keysk[0],sk[1], ...,sk[crypto_box_SECRETKEYBYTES-1],the receiver's public keypk[0],pk[1], ...,pk[crypto_box_PUBLICKEYBYTES-1],and a noncen[0],n[1], ...,n[crypto_box_NONCEBYTES-1].Thecrypto_box functionputs the ciphertext intoc[0],c[1], ...,c[mlen-1].It then returns 0.

WARNING:Messages in the C NaCl APIare 0-padded versions of messages in the C++ NaCl API.Specifically:The caller must ensure,before calling the C NaClcrypto_box function,that the firstcrypto_box_ZEROBYTES bytes of the messagem are all 0.Typical higher-level applicationswill work with the remaining bytes of the message;note, however, thatmlen counts all of the bytes,including the bytes required to be 0.

Similarly,ciphertexts in the C NaCl APIare 0-padded versions of messages in the C++ NaCl API.Specifically:Thecrypto_box functionensures that the firstcrypto_box_BOXZEROBYTES bytes of the ciphertextc are all 0.

C NaCl also provides acrypto_box_open functioncallable as follows:

     #include "crypto_box.h"          const unsigned char pk[crypto_box_PUBLICKEYBYTES];     const unsigned char sk[crypto_box_SECRETKEYBYTES];     const unsigned char n[crypto_box_NONCEBYTES];     const unsigned char c[...]; unsigned long long clen;     unsigned char m[...];          crypto_box_open(m,c,clen,n,pk,sk);

Thecrypto_box_open functionverifies and decrypts a ciphertextc[0], ...,c[clen-1]using the receiver's secret keysk[0],sk[1], ...,sk[crypto_box_SECRETKEYBYTES-1],the sender's public keypk[0],pk[1], ...,pk[crypto_box_PUBLICKEYBYTES-1],and a noncen[0], ...,n[crypto_box_NONCEBYTES-1].Thecrypto_box_open functionputs the plaintext intom[0],m[1], ...,m[clen-1].It then returns 0.

If the ciphertext fails verification,crypto_box_open instead returns-1,possibly after modifyingm[0],m[1], etc.

The caller must ensure,before calling thecrypto_box_open function,that the firstcrypto_box_BOXZEROBYTES bytes of the ciphertextc areall 0.Thecrypto_box_open functionensures (in case of success)that the firstcrypto_box_ZEROBYTES bytes of the plaintextm are all 0.

C precomputation interface

Thecrypto_box_beforenm functionis callable as follows:

     #include "crypto_box.h"          unsigned char k[crypto_box_BEFORENMBYTES];     const unsigned char pk[crypto_box_PUBLICKEYBYTES];     const unsigned char sk[crypto_box_SECRETKEYBYTES];          crypto_box_beforenm(k,pk,sk);

     #include "crypto_box.h"          const unsigned char k[crypto_box_BEFORENMBYTES];     const unsigned char n[crypto_box_NONCEBYTES];     const unsigned char m[...]; unsigned long long mlen;     unsigned char c[...];          crypto_box_afternm(c,m,mlen,n,k);

     #include "crypto_box.h"          const unsigned char k[crypto_box_BEFORENMBYTES];     const unsigned char n[crypto_box_NONCEBYTES];     const unsigned char c[...]; unsigned long long clen;     unsigned char m[...];          crypto_box_open_afternm(m,c,clen,n,k);

The intermediate data computed bycrypto_box_beforenmis suitable for bothcrypto_box_afternm andcrypto_box_open_afternm,and can be reused for any number of messages.

Security model

Distinct messages between the same {sender, receiver} setare required to have distinct nonces.For example,the lexicographically smaller public key can use nonce 1 for its first message to the other key,nonce 3 for its second message, nonce 5 for its third message, etc.,while the lexicographically larger public key uses nonce 2 for its first message to the other key,nonce 4 for its second message, nonce 6 for its third message, etc.Nonces are long enough that randomly generated nonces have negligible risk of collision.

There is no harm in having the same nonce for different messagesif the {sender, receiver} sets are different.This is true even if the sets overlap.For example, a sender can use the same nonce for two different messagesif the messages are sent to two different public keys.

Thecrypto_box function is not meant to provide non-repudiation.On the contrary: thecrypto_box functionguarantees repudiability.A receiver can freely modify a boxed message,and therefore cannot convince third partiesthat this particular message came from the sender.The sender and receiver are nevertheless protected against forgeries by other parties.In the terminology ofhttps://groups.google.com/group/sci.crypt/msg/ec5c18b23b11d82c,crypto_box uses "public-key authenticators"rather than "public-key signatures."

Users who want public verifiability (or receiver-assisted public verifiability)should instead use signatures (or signcryption).Signature support is a high priority for NaCl;a signature API will be described in subsequent NaCl documentation.

SeeValidation regarding safe message lengths.

Selected primitive

Alternate primitives

Version