From 5a753ba908fe69628ef397ef745d1475a2c15060 Mon Sep 17 00:00:00 2001 From: Jan de Muijnck-Hughes Date: Sun, 8 Dec 2013 15:58:03 +0000 Subject: [PATCH] Added api documentation. The outward facing api has been documented where possible. If the documentation has not been added a `@todo` annotations has been added. Doxygen will constuct a list of TODO's automatically. --- Doxyfile | 4 +- src/libsodium/include/sodium/crypto_auth.h | 60 +++++ src/libsodium/include/sodium/crypto_box.h | 234 +++++++++++++++++- .../include/sodium/crypto_generichash.h | 45 ++++ src/libsodium/include/sodium/crypto_hash.h | 36 ++- src/libsodium/include/sodium/crypto_int32.h | 12 + src/libsodium/include/sodium/crypto_int64.h | 3 + .../include/sodium/crypto_onetimeauth.h | 60 +++++ .../include/sodium/crypto_secretbox.h | 75 ++++++ .../include/sodium/crypto_shorthash.h | 21 ++ src/libsodium/include/sodium/crypto_sign.h | 89 ++++++- src/libsodium/include/sodium/crypto_stream.h | 76 +++++- src/libsodium/include/sodium/crypto_uint16.h | 4 + src/libsodium/include/sodium/crypto_uint32.h | 4 + src/libsodium/include/sodium/crypto_uint64.h | 4 + src/libsodium/include/sodium/crypto_uint8.h | 4 + .../include/sodium/crypto_verify_16.h | 41 ++- .../include/sodium/crypto_verify_32.h | 36 ++- src/libsodium/include/sodium/randombytes.h | 39 +++ src/libsodium/include/sodium/utils.h | 27 ++ src/libsodium/include/sodium/version.h.in | 9 + 21 files changed, 860 insertions(+), 23 deletions(-) diff --git a/Doxyfile b/Doxyfile index c785e70f..e1cdeccb 100644 --- a/Doxyfile +++ b/Doxyfile @@ -455,7 +455,7 @@ HIDE_UNDOC_MEMBERS = YES # no effect if EXTRACT_ALL is enabled. # The default value is: NO. -HIDE_UNDOC_CLASSES = NO +HIDE_UNDOC_CLASSES = YES # If the HIDE_FRIEND_COMPOUNDS tag is set to YES, doxygen will hide all friend # (class|struct|union) declarations. If set to NO these declarations will be @@ -735,7 +735,7 @@ WARN_LOGFILE = INPUT = README.markdown \ test \ - src/libsodium/include + src # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses diff --git a/src/libsodium/include/sodium/crypto_auth.h b/src/libsodium/include/sodium/crypto_auth.h index b28533d0..181ab810 100644 --- a/src/libsodium/include/sodium/crypto_auth.h +++ b/src/libsodium/include/sodium/crypto_auth.h @@ -6,29 +6,89 @@ #include "crypto_auth_hmacsha512256.h" #include "export.h" +/** + * \defgroup auth Authentication + * + * Methods for authentication. + * + * @{ + */ + + #ifdef __cplusplus extern "C" { #endif #define crypto_auth_BYTES crypto_auth_hmacsha512256_BYTES + /// Lenght of the authenticator SODIUM_EXPORT size_t crypto_auth_bytes(void); #define crypto_auth_KEYBYTES crypto_auth_hmacsha512256_KEYBYTES + /// Length of the key used for authentication. SODIUM_EXPORT size_t crypto_auth_keybytes(void); #define crypto_auth_PRIMITIVE "hmacsha512256" + /// The underlying primitive used. SODIUM_EXPORT const char *crypto_auth_primitive(void); +/** + * Constructs a one time authentication token for the given message msg using a given secret key. + * + * @param[out] tok the generated authentication token. + * @param[in] msg the message to be authenticated. + * @param[in] mlen the length of msg. + * @param[in] key the key used to compute the token. + * + * @return 0 if operation successful. + * + * @pre tok must have minimum length crypto_auth_BYTES + * @pre key must be of length crypto_auth_KEY_BYTES + * @post the first crypto_auth_BYTES of auth will contain the result. + * + * Example innvocation: + * + *~~~~~{.c} + * const unsigned char k[crypto_auth_KEYBYTES]; + * const unsigned char m[...]; unsigned long long mlen; + * unsigned char a[crypto_auth_BYTES]; + * + * crypto_auth(a,m,mlen,k); + *~~~~~ + */ SODIUM_EXPORT int crypto_auth(unsigned char *out, const unsigned char *in, unsigned long long inlen, const unsigned char *k); +/** + * Verifies that the given authentication token is correct for the + * given message and key. + * + * @param[out] tok the generated token. + * @param[in] msg the message to be authenticated. + * @param[in] mlen the length of msg. + * @param[in] key the key used to compute the authentication. + * + * @return 0 if tok is the correct token for msg under the + * given key. Otherwise -1. + * + * @pre tok must have minimum length crypto_auth_BYTES + * @pre key must be of length crypto_auth_KEY_BYTES + * + *~~~~~{.c} + * const unsigned char k[crypto_auth_KEYBYTES]; + * const unsigned char m[...]; unsigned long long mlen; + * const unsigned char a[crypto_auth_BYTES]; + * + * crypto_auth_verify(a,m,mlen,k); + *~~~~~ + */ SODIUM_EXPORT int crypto_auth_verify(const unsigned char *h, const unsigned char *in, unsigned long long inlen, const unsigned char *k); + /// @} #ifdef __cplusplus } #endif diff --git a/src/libsodium/include/sodium/crypto_box.h b/src/libsodium/include/sodium/crypto_box.h index a2ff0a1e..cfa6a524 100644 --- a/src/libsodium/include/sodium/crypto_box.h +++ b/src/libsodium/include/sodium/crypto_box.h @@ -1,12 +1,35 @@ #ifndef crypto_box_H #define crypto_box_H -/* +/** \defgroup apke Authenticated Public-Key Encryption + * + * Definitions and functions to perform Authenticated Encryption. + * + * Authentication encryption provides guarantees towards the: + * + * - confidentiality + * - integrity + * - authenticity + * + * of data. + * + * Alongside the standard interface there also exists a + * pre-computation interface. In the event that applications are + * required to send several messages to the same receiver, speed can + * be gained by splitting the operation into two steps: before and + * after. Similarly applications that receive several messages from + * the same sender can gain speed through the use of the: before, and + * open_after functions. + * + * + * \warning * THREAD SAFETY: crypto_box_keypair() is thread-safe, * provided that you called sodium_init() once before using any * other libsodium function. * Other functions are always thread-safe. - */ + * + * @{ +*/ #include @@ -17,65 +40,250 @@ extern "C" { #endif + #define crypto_box_PUBLICKEYBYTES crypto_box_curve25519xsalsa20poly1305_PUBLICKEYBYTES +/// Size of Public Key. SODIUM_EXPORT size_t crypto_box_publickeybytes(void); #define crypto_box_SECRETKEYBYTES crypto_box_curve25519xsalsa20poly1305_SECRETKEYBYTES +/// Size of Secret Key SODIUM_EXPORT size_t crypto_box_secretkeybytes(void); #define crypto_box_BEFORENMBYTES crypto_box_curve25519xsalsa20poly1305_BEFORENMBYTES +/// Size of the pre-computed ciphertext SODIUM_EXPORT size_t crypto_box_beforenmbytes(void); #define crypto_box_NONCEBYTES crypto_box_curve25519xsalsa20poly1305_NONCEBYTES +/// Size of the Nonce SODIUM_EXPORT size_t crypto_box_noncebytes(void); #define crypto_box_ZEROBYTES crypto_box_curve25519xsalsa20poly1305_ZEROBYTES +/// No. of leading 0 bytes in the message. SODIUM_EXPORT size_t crypto_box_zerobytes(void); #define crypto_box_BOXZEROBYTES crypto_box_curve25519xsalsa20poly1305_BOXZEROBYTES +/// No. of leading 0 bytes in the cipher-text. SODIUM_EXPORT size_t crypto_box_boxzerobytes(void); #define crypto_box_MACBYTES crypto_box_curve25519xsalsa20poly1305_MACBYTES +/// SODIUM_EXPORT size_t crypto_box_macbytes(void); #define crypto_box_PRIMITIVE "curve25519xsalsa20poly1305" +/// The underlying cryptographic primitive. SODIUM_EXPORT const char *crypto_box_primitive(void); +/** + * Randomly generates a secret key and a corresponding public key. + * + * @param[out] pk the buffer for the public key + * @param[out] sk the buffer for the private key with length crypto_box_SECRETKEYTBYTES + * + * @return 0 if generation successful. + * + * @pre the buffer for pk must be at least crypto_box_PUBLICKEYBYTES in length + * @pre the buffer for sk must be at least crypto_box_SECRETKEYTBYTES in length + * @post first crypto_box_PUBLICKEYTBYTES of pk will be the key data. + * @post first crypto_box_SECRETKEYTBYTES of sk will be the key data. + * + * Example innvocation: + * + *~~~~~{.c} + * + * unsigned char pk[crypto_box_PUBLICKEYBYTES]; + * unsigned char sk[crypto_box_SECRETKEYBYTES]; + * + * crypto_box_keypair(pk,sk); + *~~~~~ + * + */ SODIUM_EXPORT int crypto_box_keypair(unsigned char *pk, unsigned char *sk); +/** + * Partially performs the computation required for both encryption and + * decryption of data. + * + * @param[out] k the result of the computation. + * @param[in] pk the receivers public key, used for encryption. + * @param[in] sk the senders private key, used for signing. + * + * The intermediate data computed by crypto_box_beforenm is suitable + * for both crypto_box_afternm and crypto_box_open_afternm, and can be + * reused for any number of messages. + * + * Example innvocation: + * + *~~~~~{.c} + * 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); + *~~~~~ + */ SODIUM_EXPORT -int crypto_box_beforenm(unsigned char *k, const unsigned char *pk, +int crypto_box_beforenm(unsigned char *k, + const unsigned char *pk, const unsigned char *sk); +/** + * Encrypts a given a message m, using partial computed data. + * + * @param[out] ctxt the buffer for the cipher-text. + * @param[in] msg the message to be encrypted. + * @param[in] mlen the length of msg. + * @param[in] nonce a randomly generated nonce. + * @param[in] k the partial computed data. + * + * @return 0 if operation is successful. + * + * @pre first crypto_box_ZEROBYTES of msg be all 0. + * @pre the nonce must have size crypto_box_NONCEBYTES. + * @post first crypto_box_BOXZERBYTES of ctxt be all 0. + * @post first mlen bytes of ctxt will contain the ciphertext. + * + * Example innvocation: + * + *~~~~~{.c} + * 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); + *~~~~~ + */ SODIUM_EXPORT -int crypto_box_afternm(unsigned char *c, const unsigned char *m, - unsigned long long mlen, const unsigned char *n, +int crypto_box_afternm(unsigned char *c, + const unsigned char *m, + unsigned long long mlen, + const unsigned char *n, const unsigned char *k); +/** + * Decrypts a ciphertext ctxt given the receivers private key, and + * senders public key. + * + * @param[out] msg the buffer to place resulting plaintext. + * @param[in] ctxt the ciphertext to be decrypted. + * @param[in] clen the length of the ciphertext. + * @param[in] nonce a randomly generated nonce. + * @param[in] k the partial computed data. + * + * @return 0 if successful and -1 if verification fails. + * + * @pre first crypto_box_BOXZEROBYTES of ctxt be all 0. + * @pre the nonce must have size crypto_box_NONCEBYTES. + * @post first clen bytes of msg will contain the plaintext. + * @post first crypto_box_ZEROBYTES of msg will be all 0. + * + * Example innvocation: + * + *~~~~~{.c} + * + * 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); + *~~~~~ + */ SODIUM_EXPORT -int crypto_box_open_afternm(unsigned char *m, const unsigned char *c, - unsigned long long clen, const unsigned char *n, +int crypto_box_open_afternm(unsigned char *m, + const unsigned char *c, + unsigned long long clen, + const unsigned char *n, const unsigned char *k); +/** + * Encrypts a message given the senders secret key, and receivers + * public key. + * + * @param[out] ctxt the buffer for the cipher-text. + * @param[in] msg the message to be encrypted. + * @param[in] mlen the length of msg. + * @param[in] nonce a randomly generated nonce. + * @param[in] pk the receivers public key, used for encryption. + * @param[in] sk the senders private key, used for signing. + * + * @return 0 if operation is successful. + * + * @pre first crypto_box_ZEROBYTES of msg be all 0. + * @pre the nonce must have size crypto_box_NONCEBYTES. + * @post first crypto_box_BOXZERBYTES of ctxt be all 0. + * @post first mlen bytes of ctxt will contain the ciphertext. + * + * Example innvocation: + * + *~~~~~{.c} + * 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); + *~~~~~ + */ SODIUM_EXPORT -int crypto_box(unsigned char *c, const unsigned char *m, - unsigned long long mlen, const unsigned char *n, - const unsigned char *pk, const unsigned char *sk); +int crypto_box(unsigned char *c, + const unsigned char *m, + unsigned long long mlen, + const unsigned char *n, + const unsigned char *pk, + const unsigned char *sk); +/** + * Decrypts a ciphertext ctxt given the receivers private key, and + * senders public key. + * + * @param[out] msg the buffer to place resulting plaintext. + * @param[in] ctxt the ciphertext to be decrypted. + * @param[in] clen the length of the ciphertext. + * @param[in] nonce a randomly generated. + * @param[in] pk the senders public key, used for verification. + * @param[in] sk the receivers private key, used for decryption. + * + * @return 0 if successful and -1 if verification fails. + * + * @pre first crypto_box_BOXZEROBYTES of ctxt be all 0. + * @pre the nonce must have size crypto_box_NONCEBYTES. + * @post first clen bytes of msg will contain the plaintext. + * @post first crypto_box_ZEROBYTES of msg will be all 0. + * + * Example innvocation: + * + *~~~~~{.c} + * 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); + *~~~~~ + */ SODIUM_EXPORT -int crypto_box_open(unsigned char *m, const unsigned char *c, - unsigned long long clen, const unsigned char *n, - const unsigned char *pk, const unsigned char *sk); +int crypto_box_open(unsigned char *m, + const unsigned char *c, + unsigned long long clen, + const unsigned char *n, + const unsigned char *pk, + const unsigned char *sk); + + /** @} */ #ifdef __cplusplus } #endif diff --git a/src/libsodium/include/sodium/crypto_generichash.h b/src/libsodium/include/sodium/crypto_generichash.h index 52a16a8c..e934fe35 100644 --- a/src/libsodium/include/sodium/crypto_generichash.h +++ b/src/libsodium/include/sodium/crypto_generichash.h @@ -6,63 +6,108 @@ #include "crypto_generichash_blake2b.h" #include "export.h" +/** + * \addgroup hash + * + * @TODO document + * + * @{ + */ + #ifdef __cplusplus extern "C" { #endif #define crypto_generichash_BYTES crypto_generichash_blake2b_BYTES + /** + * @todo document + */ SODIUM_EXPORT size_t crypto_generichash_bytes(void); #define crypto_generichash_BYTES_MIN crypto_generichash_blake2b_BYTES_MIN + /** + * @todo document + */ SODIUM_EXPORT size_t crypto_generichash_bytes_min(void); #define crypto_generichash_BYTES_MAX crypto_generichash_blake2b_BYTES_MAX + /** + * @todo document + */ SODIUM_EXPORT size_t crypto_generichash_bytes_max(void); #define crypto_generichash_KEYBYTES crypto_generichash_blake2b_KEYBYTES + /** + * @todo document + */ SODIUM_EXPORT size_t crypto_generichash_keybytes(void); #define crypto_generichash_KEYBYTES_MIN crypto_generichash_blake2b_KEYBYTES_MIN + /** + * @todo document + */ SODIUM_EXPORT size_t crypto_generichash_keybytes_min(void); #define crypto_generichash_KEYBYTES_MAX crypto_generichash_blake2b_KEYBYTES_MAX + /** + * @todo document + */ SODIUM_EXPORT size_t crypto_generichash_keybytes_max(void); #define crypto_generichash_BLOCKBYTES crypto_generichash_blake2b_BLOCKBYTES + /** + * @todo document + */ SODIUM_EXPORT size_t crypto_generichash_blockbytes(void); #define crypto_generichash_PRIMITIVE "blake2b" + /** + * @todo document + */ SODIUM_EXPORT const char *crypto_generichash_primitive(void); typedef crypto_generichash_blake2b_state crypto_generichash_state; + /** + * @todo document + */ SODIUM_EXPORT int crypto_generichash(unsigned char *out, size_t outlen, const unsigned char *in, unsigned long long inlen, const unsigned char *key, size_t keylen); + /** + * @todo document + */ SODIUM_EXPORT int crypto_generichash_init(crypto_generichash_state *state, const unsigned char *key, const size_t keylen, const size_t outlen); + /** + * @todo document + */ SODIUM_EXPORT int crypto_generichash_update(crypto_generichash_state *state, const unsigned char *in, unsigned long long inlen); + /** + * @todo document + */ SODIUM_EXPORT int crypto_generichash_final(crypto_generichash_state *state, unsigned char *out, const size_t outlen); + /// @} #ifdef __cplusplus } #endif diff --git a/src/libsodium/include/sodium/crypto_hash.h b/src/libsodium/include/sodium/crypto_hash.h index 738180f4..8e458f21 100644 --- a/src/libsodium/include/sodium/crypto_hash.h +++ b/src/libsodium/include/sodium/crypto_hash.h @@ -4,18 +4,48 @@ #include "crypto_hash_sha512.h" #include "export.h" -#define crypto_hash_BYTES crypto_hash_sha512_BYTES -#define crypto_hash_BLOCKBYTES crypto_hash_sha512_BLOCKBYTES -#define crypto_hash_PRIMITIVE "sha512" +/** + * \defgroup hash Methods for Hashing + * + * Utility function to allow for hash computation. + * + * @{ + */ + +#define crypto_hash_BYTES crypto_hash_sha512_BYTES ///< @todo +#define crypto_hash_BLOCKBYTES crypto_hash_sha512_BLOCKBYTES ///< @todo +#define crypto_hash_PRIMITIVE "sha512" ///< @todo #ifdef __cplusplus extern "C" { #endif +/** + * Compute a crypto_hash_BYTES hash of the given message. + * + * @param[out] hbuf a buffer to store the resulting hash. + * @param[in] msg the message to be hashed. + * @param[in] mlen the length of the message to be hashed. + * + * @return 0 if successful operation. + * + * @pre hbuf must have length minimum crypto_hash_BYTES. + * @post first crypto_hash_BYTES. of hbuf will contain the hash. + * + * Example Innvocation: + * + *~~~~~{.c} + * const unsigned char m[...]; unsigned long long mlen; + * unsigned char h[crypto_hash_BYTES]; + * + * crypto_hash(h,m,mlen); + *~~~~~ + */ SODIUM_EXPORT int crypto_hash(unsigned char *out, const unsigned char *in, unsigned long long inlen); + /// @} #ifdef __cplusplus } #endif diff --git a/src/libsodium/include/sodium/crypto_int32.h b/src/libsodium/include/sodium/crypto_int32.h index a22019d8..09be85ec 100644 --- a/src/libsodium/include/sodium/crypto_int32.h +++ b/src/libsodium/include/sodium/crypto_int32.h @@ -3,6 +3,18 @@ #include +/** \defgroup ints Integer Definitions + * + * @todo Document + * + * @{ + */ + +/** + * @todo + */ typedef int32_t crypto_int32; + +/// @} #endif diff --git a/src/libsodium/include/sodium/crypto_int64.h b/src/libsodium/include/sodium/crypto_int64.h index f68a2836..c9dec3e7 100644 --- a/src/libsodium/include/sodium/crypto_int64.h +++ b/src/libsodium/include/sodium/crypto_int64.h @@ -3,6 +3,9 @@ #include +/** \ingroup ints + * @todo + */ typedef int64_t crypto_int64; #endif diff --git a/src/libsodium/include/sodium/crypto_onetimeauth.h b/src/libsodium/include/sodium/crypto_onetimeauth.h index f43d8319..ebb478b2 100644 --- a/src/libsodium/include/sodium/crypto_onetimeauth.h +++ b/src/libsodium/include/sodium/crypto_onetimeauth.h @@ -6,30 +6,90 @@ #include "crypto_onetimeauth_poly1305.h" #include "export.h" + +/** + * \defgroup onetimeauth One-Time Authentication + * + * Methods for one-time authentication. + * + * @{ + */ + #ifdef __cplusplus extern "C" { #endif #define crypto_onetimeauth_BYTES crypto_onetimeauth_poly1305_BYTES + /// Size of the authentication token. SODIUM_EXPORT size_t crypto_onetimeauth_bytes(void); #define crypto_onetimeauth_KEYBYTES crypto_onetimeauth_poly1305_KEYBYTES + /// Size of the secret key used. SODIUM_EXPORT size_t crypto_onetimeauth_keybytes(void); #define crypto_onetimeauth_PRIMITIVE "poly1305" + /// Return the underyling primitive. SODIUM_EXPORT const char *crypto_onetimeauth_primitive(void); +/** + * Constructs a one time authentication token for the given message msg using a given secret key. + * + * @param[out] tok the generated token. + * @param[in] msg the message to be authenticated. + * @param[in] mlen the length of msg. + * @param[in] key the key used to compute the authentication. + * + * @return 0 if operation successful. + * + * @pre token must have minimum length crypto_onetimeauth_BYTES + * @pre key must be of length crypto_onetimeauth_KEY_BYTES + * @post the first crypto_onetimeauth_BYTES of the token will contain the result. + * + * Example innvocation: + * + *~~~~~{.c} + * const unsigned char k[crypto_onetimeauth_KEYBYTES]; + * const unsigned char m[...]; unsigned long long mlen; + * unsigned char a[crypto_onetimeauth_BYTES]; + + * crypto_onetimeauth(a,m,mlen,k); + *~~~~~ + */ SODIUM_EXPORT int crypto_onetimeauth(unsigned char *out, const unsigned char *in, unsigned long long inlen, const unsigned char *k); +/** + * Verifies that the given authentication token is correct for the + * given message and key. + * + * @param[out] tok the generated token. + * @param[in] msg the message to be authenticated. + * @param[in] mlen the length of msg. + * @param[in] key the key used to compute the authentication. + * + * @return 0 if tok is the correct token for msg under the + * given key. Otherwise -1. + * + * @pre tok must have minimum length crypto_onetimeauth_BYTES + * @pre key must be of length crypto_onetimeauth_KEY_BYTES + * + *~~~~~{.c} + * const unsigned char k[crypto_onetimeauth_KEYBYTES]; + * const unsigned char m[...]; unsigned long long mlen; + * const unsigned char a[crypto_onetimeauth_BYTES]; + * + * crypto_onetimeauth_verify(a,m,mlen,k); + *~~~~~ + */ SODIUM_EXPORT int crypto_onetimeauth_verify(const unsigned char *h, const unsigned char *in, unsigned long long inlen, const unsigned char *k); + /// @} #ifdef __cplusplus } #endif diff --git a/src/libsodium/include/sodium/crypto_secretbox.h b/src/libsodium/include/sodium/crypto_secretbox.h index 3d064e5d..002524b4 100644 --- a/src/libsodium/include/sodium/crypto_secretbox.h +++ b/src/libsodium/include/sodium/crypto_secretbox.h @@ -6,44 +6,119 @@ #include "crypto_secretbox_xsalsa20poly1305.h" #include "export.h" +/** + * \defgroup asymenc Authenticated Symmetric Encryption + * + * Definitions and functions for authenticated symmetric encryption. + * + * @{ + */ + #ifdef __cplusplus extern "C" { #endif #define crypto_secretbox_KEYBYTES crypto_secretbox_xsalsa20poly1305_KEYBYTES +/// Size of symmetric key. SODIUM_EXPORT size_t crypto_secretbox_keybytes(void); #define crypto_secretbox_NONCEBYTES crypto_secretbox_xsalsa20poly1305_NONCEBYTES +/// Size of the nonce. SODIUM_EXPORT size_t crypto_secretbox_noncebytes(void); #define crypto_secretbox_ZEROBYTES crypto_secretbox_xsalsa20poly1305_ZEROBYTES +/// No. of leading 0 bytes in the message. SODIUM_EXPORT size_t crypto_secretbox_zerobytes(void); #define crypto_secretbox_BOXZEROBYTES crypto_secretbox_xsalsa20poly1305_BOXZEROBYTES +/// No. of leading 0 bytes in the cipher-text. SODIUM_EXPORT size_t crypto_secretbox_boxzerobytes(void); #define crypto_secretbox_MACBYTES crypto_secretbox_xsalsa20poly1305_MACBYTES +/// SODIUM_EXPORT size_t crypto_secretbox_macbytes(void); #define crypto_secretbox_PRIMITIVE "xsalsa20poly1305" +/// SODIUM_EXPORT const char *crypto_secretbox_primitive(void); +/** + * + * Encrypts and authenticates a message using the given secret key, and nonce.. + * + * @param[out] ctxt the buffer for the cipher-text. + * @param[in] msg the message to be encrypted. + * @param[in] mlen the length of msg. + * @param[in] nonce a nonce with length crypto_box_NONCEBYTES. + * @param[in] key the shared secret key. + * + * @return 0 if operation is successful. + * + * @pre first crypto_secretbox_ZEROBYTES of msg be all 0.. + * @post first crypto_secretbox_BOXZERBYTES of ctxt be all 0. + * @post first mlen bytes of ctxt will contain the ciphertext. + * + * + *~~~~~{.c} + * const unsigned char k[crypto_secretbox_KEYBYTES]; + * const unsigned char n[crypto_secretbox_NONCEBYTES]; + * const unsigned char m[...]; unsigned long long mlen; + * unsigned char c[...]; unsigned long long clen; + * + * crypto_secretbox(c,m,mlen,n,k); + *~~~~~ + */ SODIUM_EXPORT int crypto_secretbox(unsigned char *c, const unsigned char *m, unsigned long long mlen, const unsigned char *n, const unsigned char *k); +/** + * + * Decrypts a ciphertext ctxt given the receivers private key, and + * senders public key. + * + * @param[out] msg the buffer to place resulting plaintext. + * @param[in] ctxt the ciphertext to be decrypted. + * @param[in] clen the length of the ciphertext. + * @param[in] nonce a randomly generated nonce. + * @param[in] key the shared secret key. + * + * @return 0 if successful and -1 if verification fails. + * + * @pre first crypto_secretbox_BOXZEROBYTES of ctxt be all 0. + * @pre the nonce must be of length crypto_secretbox_NONCEBYTES + * @post first clen bytes of msg will contain the plaintext. + * @post first crypto_secretbox_ZEROBYTES of msg will be all 0. + * + * @warning if verification fails msg may contain data from the + * computation. + + * Example innvocation: + * + *~~~~~{.c} + * const unsigned char k[crypto_secretbox_KEYBYTES]; + * const unsigned char n[crypto_secretbox_NONCEBYTES]; + * const unsigned char c[...]; unsigned long long clen; + * unsigned char m[...]; + * + * crypto_secretbox_open(m,c,clen,n,k); + *~~~~~ + */ SODIUM_EXPORT int crypto_secretbox_open(unsigned char *m, const unsigned char *c, unsigned long long clen, const unsigned char *n, const unsigned char *k); + +/** < @} */ + #ifdef __cplusplus } #endif diff --git a/src/libsodium/include/sodium/crypto_shorthash.h b/src/libsodium/include/sodium/crypto_shorthash.h index 5173727a..c6d87b38 100644 --- a/src/libsodium/include/sodium/crypto_shorthash.h +++ b/src/libsodium/include/sodium/crypto_shorthash.h @@ -6,26 +6,47 @@ #include "crypto_shorthash_siphash24.h" #include "export.h" +/** + * \addgroup hash + * + * @todo document + * + * @{ + */ + #ifdef __cplusplus extern "C" { #endif #define crypto_shorthash_BYTES crypto_shorthash_siphash24_BYTES + /** + * @todo document + */ SODIUM_EXPORT size_t crypto_shorthash_bytes(void); #define crypto_shorthash_KEYBYTES crypto_shorthash_siphash24_KEYBYTES + /** + * @todo document + */ SODIUM_EXPORT size_t crypto_shorthash_keybytes(void); #define crypto_shorthash_PRIMITIVE "siphash24" + /** + * @todo document + */ SODIUM_EXPORT const char *crypto_shorthash_primitive(void); SODIUM_EXPORT + /** + * @todo document + */ int crypto_shorthash(unsigned char *out, const unsigned char *in, unsigned long long inlen, const unsigned char *k); + ///@} #ifdef __cplusplus } #endif diff --git a/src/libsodium/include/sodium/crypto_sign.h b/src/libsodium/include/sodium/crypto_sign.h index 9efb2ebc..2127fcfb 100644 --- a/src/libsodium/include/sodium/crypto_sign.h +++ b/src/libsodium/include/sodium/crypto_sign.h @@ -1,11 +1,17 @@ #ifndef crypto_sign_H #define crypto_sign_H -/* +/** \defgroup dsig Digital Signatures + * + * Definitions and functions to perform digital signatures. + * + * \warning * THREAD SAFETY: crypto_sign_keypair() is thread-safe, * provided that you called sodium_init() once before using any * other libsodium function. * Other functions, including crypto_sign_seed_keypair() are always thread-safe. + * + * @{ */ #include @@ -18,42 +24,123 @@ extern "C" { #endif #define crypto_sign_BYTES crypto_sign_ed25519_BYTES +/// length of resulting signature. SODIUM_EXPORT size_t crypto_sign_bytes(void); #define crypto_sign_SEEDBYTES crypto_sign_ed25519_SEEDBYTES +/// @todo Document crypto_sign_SEEDBYTES SODIUM_EXPORT size_t crypto_sign_seedbytes(void); #define crypto_sign_PUBLICKEYBYTES crypto_sign_ed25519_PUBLICKEYBYTES +/// length of verification key. + SODIUM_EXPORT size_t crypto_sign_publickeybytes(void); #define crypto_sign_SECRETKEYBYTES crypto_sign_ed25519_SECRETKEYBYTES +/// length of signing key. SODIUM_EXPORT size_t crypto_sign_secretkeybytes(void); #define crypto_sign_PRIMITIVE "ed25519" +/// The underlying primitive SODIUM_EXPORT const char *crypto_sign_primitive(void); + /** + * + */ SODIUM_EXPORT int crypto_sign_seed_keypair(unsigned char *pk, unsigned char *sk, const unsigned char *seed); +/** + * Generates a signing/verification key pair. + * + * @param[out] vk the verification key. + * @param[out] sk the signing key. + * + * @return 0 if operation successful. + * + * @pre the buffer for vk must be at least crypto_sign_PUBLICKEYBYTES in length + * @pre the buffer for sk must be at least crypto_sign_SECRETKEYTBYTES in length + * @post first crypto_sign_PUBLICKEYTBYTES of vk will be the key data. + * @post first crypto_sign_SECRETKEYTBYTES of sk will be the key data. + * + * + *~~~~~{.c} + * unsigned char vk[crypto_sign_PUBLICKEYBYTES]; + * unsigned char sk[crypto_sign_SECRETKEYBYTES]; + * + * crypto_sign_keypair(vk,sk); + *~~~~~ + */ + SODIUM_EXPORT int crypto_sign_keypair(unsigned char *pk, unsigned char *sk); +/** + * Signs a given message using the signer's signing key. + * + * @param[out] sig the resulting signature. + * @param[out] slen the length of the signature. + * @param[in] msg the message to be signed. + * @param[in] mlen the length of the message. + * @param[in] sk the signing key. + * + * @return 0 if operation successful + * + * @pre sig must be of length mlen+crypto_sign_BYTES + * + *~~~~~{.c} + * const unsigned char sk[crypto_sign_SECRETKEYBYTES]; + * const unsigned char m[...]; + * unsigned long long mlen; + * unsigned char sm[...]; + * unsigned long long smlen; + * + * crypto_sign(sm,&smlen,m,mlen,sk); + *~~~~~ + */ SODIUM_EXPORT int crypto_sign(unsigned char *sm, unsigned long long *smlen, const unsigned char *m, unsigned long long mlen, const unsigned char *sk); +/** + * Verifies the signed message sig using the signer's verification key. + * + * @param[out] msg the resulting message. + * @param[out] mlen the length of msg. + * @param[in] sig the signed message. + * @param[in] smlen length of the signed message. + * @param[in] vk the verification key. + * + * @return 0 if successful, -1 if verification fails. + * + * @pre length of msg must be at least smlen + * + * @warning if verification fails msg may contain data from the + * computation. + * + * Example innvocation: + * + *~~~~~{.c} + * const unsigned char pk[crypto_sign_PUBLICKEYBYTES]; + * const unsigned char sm[...]; unsigned long long smlen; + * unsigned char m[...]; unsigned long long mlen; + * + * crypto_sign_open(m,&mlen,sm,smlen,pk); + *~~~~~ + */ SODIUM_EXPORT int crypto_sign_open(unsigned char *m, unsigned long long *mlen, const unsigned char *sm, unsigned long long smlen, const unsigned char *pk); + /** @} */ #ifdef __cplusplus } #endif diff --git a/src/libsodium/include/sodium/crypto_stream.h b/src/libsodium/include/sodium/crypto_stream.h index e16aef35..466299af 100644 --- a/src/libsodium/include/sodium/crypto_stream.h +++ b/src/libsodium/include/sodium/crypto_stream.h @@ -1,12 +1,26 @@ #ifndef crypto_stream_H #define crypto_stream_H -/* +/** \defgroup symenc Symmetric Encryption + * + * Definitions and functions for symmetric encryption. + * + * Alongside the standard interface there also exists a + * pre-computation interface. In the event that applications are + * required to send several messages to the same receiver, speed can + * be gained by splitting the operation into two steps: before and + * after. Similarly applications that receive several messages from + * the same sender can gain speed through the use of the: before, and + * open_after functions. + * + * \warning * WARNING: This is just a stream cipher. It is NOT authenticated encryption. * While it provides some protection against eavesdropping, it does NOT * provide any security against active attacks. * Unless you know what you're doing, what you are looking for is probably * the crypto_box functions. + * + * @{ */ #include @@ -19,26 +33,86 @@ extern "C" { #endif #define crypto_stream_KEYBYTES crypto_stream_xsalsa20_KEYBYTES + /// Size of Keys used SODIUM_EXPORT size_t crypto_stream_keybytes(void); #define crypto_stream_NONCEBYTES crypto_stream_xsalsa20_NONCEBYTES + /// Size of nonces SODIUM_EXPORT size_t crypto_stream_noncebytes(void); #define crypto_stream_PRIMITIVE "xsalsa20" + /// The underlying primitive. SODIUM_EXPORT const char *crypto_stream_primitive(void); +/** + * Generates a stream using the given secret key and nonce. + * + * @param[out] stream the generated stream. + * @param[out] slen the length of the generated stream. + * @param[in] nonce the nonce used to generate the stream. + * @param[in] key the key used to generate the stream. + * + * @return 0 if operation successful + * + * @pre nonce must have minimum length crypto_stream_NONCEBYTES + * @pre key must have minimum length crypto_stream_KEYBYTES + * @post stream will have length slen + * + * Example invocation: + * + *~~~~~{.c} + * const unsigned char k[crypto_stream_KEYBYTES]; + * const unsigned char n[crypto_stream_NONCEBYTES]; + * unsigned char c[...]; unsigned long long clen; + * + * crypto_stream(c,clen,n,k); + *~~~~~ + */ SODIUM_EXPORT int crypto_stream(unsigned char *c, unsigned long long clen, const unsigned char *n, const unsigned char *k); +/** + * Encrypts the given message using the given secret key and nonce. + * + * The crypto_stream_xor function guarantees that the ciphertext is + * the plaintext (xor) the output of crypto_stream. Consequently + * crypto_stream_xor can also be used to decrypt. + * + * @param[out] ctxt buffer for the resulting ciphertext. + * @param[in] msg the message to be encrypted. + * @param[in] mlen the length of the message. + * @param[in] nonce the nonce used during encryption. + * @param[in] key secret key used during encryption. + * + * @return 0 if operation successful. + * + * @pre ctxt must have length minimum mlen. + * @pre nonce must have length minimum crypto_stream_NONCEBYTES. + * @pre key must have length minimum crpyto_stream_KEYBYTES + * @post first mlen bytes of ctxt will contain the ciphertext. + * + * Example invocation: + * + *~~~~~{.c} + * const unsigned char k[crypto_stream_KEYBYTES]; + * const unsigned char n[crypto_stream_NONCEBYTES]; + * unsigned char m[...]; + * unsigned long long mlen; + * unsigned char c[...]; + * + * crypto_stream_xor(c,m,mlen,n,k); + *~~~~~ + */ SODIUM_EXPORT int crypto_stream_xor(unsigned char *c, const unsigned char *m, unsigned long long mlen, const unsigned char *n, const unsigned char *k); + /** @} */ #ifdef __cplusplus } #endif diff --git a/src/libsodium/include/sodium/crypto_uint16.h b/src/libsodium/include/sodium/crypto_uint16.h index 6be4e347..a05b91a3 100644 --- a/src/libsodium/include/sodium/crypto_uint16.h +++ b/src/libsodium/include/sodium/crypto_uint16.h @@ -3,6 +3,10 @@ #include +/** \ingroup ints + * + * @todo + */ typedef uint16_t crypto_uint16; #endif diff --git a/src/libsodium/include/sodium/crypto_uint32.h b/src/libsodium/include/sodium/crypto_uint32.h index ba66cecc..890a89fc 100644 --- a/src/libsodium/include/sodium/crypto_uint32.h +++ b/src/libsodium/include/sodium/crypto_uint32.h @@ -3,6 +3,10 @@ #include +/** \ingroup ints + * + * @todo + */ typedef uint32_t crypto_uint32; #endif diff --git a/src/libsodium/include/sodium/crypto_uint64.h b/src/libsodium/include/sodium/crypto_uint64.h index 98b3f6d3..af836d94 100644 --- a/src/libsodium/include/sodium/crypto_uint64.h +++ b/src/libsodium/include/sodium/crypto_uint64.h @@ -3,6 +3,10 @@ #include +/** \ingroup ints + * + * @todo + */ typedef uint64_t crypto_uint64; #endif diff --git a/src/libsodium/include/sodium/crypto_uint8.h b/src/libsodium/include/sodium/crypto_uint8.h index 789613ba..fe360f18 100644 --- a/src/libsodium/include/sodium/crypto_uint8.h +++ b/src/libsodium/include/sodium/crypto_uint8.h @@ -3,6 +3,10 @@ #include +/** \ingroup ints + * + * @todo + */ typedef uint8_t crypto_uint8; #endif diff --git a/src/libsodium/include/sodium/crypto_verify_16.h b/src/libsodium/include/sodium/crypto_verify_16.h index 972a02f3..dcac6412 100644 --- a/src/libsodium/include/sodium/crypto_verify_16.h +++ b/src/libsodium/include/sodium/crypto_verify_16.h @@ -4,20 +4,57 @@ #include #include "export.h" -#define crypto_verify_16_BYTES 16U +/** + * \defgroup strcmp String Comparison + * + * Methods to compare 16 and 32 byte strings. + * + * @{ + */ + +#define crypto_verify_16_BYTES 16U ///< @TODO #ifdef __cplusplus extern "C" { #endif + /// @todo SODIUM_EXPORT size_t crypto_verify_16_bytes(void); +/** + * Compares the first crypto_verify_16_BYTES of the given strings. + * + * @param[in] string1 a string + * @param[in] string2 another string + * + * @return 0 if string1 and string2 are equal, otherwise -1. + * + * @pre string1 must be minimum of crypto_verify_16_BYTES long. + * @pre string2 must be minimum of crypto_verify_16_BYTES long. + * + * @note The time taken by the function is independent of the contents + * of string1 and string2. In contrast, the standard C comparison + * function memcmp(string1,string2,16) takes time that is dependent on + * the longest matching prefix of string1 and string2. This often + * allows for easy timing attacks. + * + * Example invocation: + * + *~~~~~{.c} + * const unsigned char x[16]; + * const unsigned char y[16]; + * + * crypto_verify_16(x,y); + *~~~~~ + */ SODIUM_EXPORT int crypto_verify_16(const unsigned char *x, const unsigned char *y); -#define crypto_verify_16_ref crypto_verify_16 +#define crypto_verify_16_ref crypto_verify_16 ///< @TODO + + /// @} #ifdef __cplusplus } #endif diff --git a/src/libsodium/include/sodium/crypto_verify_32.h b/src/libsodium/include/sodium/crypto_verify_32.h index f3ada230..1e7a63cd 100644 --- a/src/libsodium/include/sodium/crypto_verify_32.h +++ b/src/libsodium/include/sodium/crypto_verify_32.h @@ -4,20 +4,54 @@ #include #include "export.h" +/** \addtogroup strcmp + * + * @{ + */ + #define crypto_verify_32_BYTES 32U #ifdef __cplusplus extern "C" { #endif + /// @TODO SODIUM_EXPORT size_t crypto_verify_32_bytes(void); +/** + * Compares the first crypto_verify_32_BYTES of the given strings. + * + * @param[in] string1 a string + * @param[in] string2 another string + * + * @return 0 if string1 and string2 are equal, otherwise -1. + * + * @pre string1 must be minimum of crypto_verify_32_BYTES long. + * @pre string2 must be minimum of crypto_verify_32_BYTES long. + * + * @note The time taken by the function is independent of the contents + * of string1 and string2. In contrast, the standard C comparison + * function memcmp(string1,string2,32) takes time that is dependent on + * the longest matching prefix of string1 and string2. This often + * allows for easy timing attacks. + * + * Example invocation: + * + *~~~~~{.c} + * const unsigned char x[32]; + * const unsigned char y[32]; + * + * crypto_verify_32(x,y); + *~~~~~ + */ SODIUM_EXPORT int crypto_verify_32(const unsigned char *x, const unsigned char *y); -#define crypto_verify_32_ref crypto_verify_32 +#define crypto_verify_32_ref crypto_verify_32 ///< @TODO + + /// @} #ifdef __cplusplus } #endif diff --git a/src/libsodium/include/sodium/randombytes.h b/src/libsodium/include/sodium/randombytes.h index db5077e6..bc5b9181 100644 --- a/src/libsodium/include/sodium/randombytes.h +++ b/src/libsodium/include/sodium/randombytes.h @@ -9,10 +9,19 @@ #include "export.h" +/** + * \defgroup randbytes Random byte generation + * + * @{ + */ + #ifdef __cplusplus extern "C" { #endif + /** + * @todo + */ typedef struct randombytes_implementation { const char *(*implementation_name)(void); uint32_t (*random)(void); @@ -22,30 +31,60 @@ typedef struct randombytes_implementation { int (*close)(void); } randombytes_implementation; +/** + * @todo + */ SODIUM_EXPORT int randombytes_set_implementation(randombytes_implementation *impl); +/** + * Fill the specified buffer with size random bytes. + */ SODIUM_EXPORT void randombytes(unsigned char * const buf, const unsigned long long buf_len); +/** + * Return the implementation name. + */ SODIUM_EXPORT const char *randombytes_implementation_name(void); +/** + * Return a random 32-bit unsigned value. + */ SODIUM_EXPORT uint32_t randombytes_random(void); +/** + * Generate a new key for the pseudorandom number generator. The file + * descriptor for the entropy source is kept open, so that the + * generator can be reseeded even in a chroot() jail. + * + */ SODIUM_EXPORT void randombytes_stir(void); +/** + * Return a value between 0 and upper_bound using a uniform + * distribution. + */ SODIUM_EXPORT uint32_t randombytes_uniform(const uint32_t upper_bound); +/** + * Fill the specified buffer with size random bytes. + */ SODIUM_EXPORT void randombytes_buf(void * const buf, const size_t size); +/** + * Close the file descriptor or the handle for the cryptographic + * service provider. + */ SODIUM_EXPORT int randombytes_close(void); + /// @} #ifdef __cplusplus } #endif diff --git a/src/libsodium/include/sodium/utils.h b/src/libsodium/include/sodium/utils.h index 14b6a747..5ae3d77e 100644 --- a/src/libsodium/include/sodium/utils.h +++ b/src/libsodium/include/sodium/utils.h @@ -6,6 +6,12 @@ #include "export.h" +/** \defgroup util Util Functions + * + * + * @{ + */ + #ifdef __cplusplus extern "C" { #endif @@ -16,19 +22,40 @@ extern "C" { # define _SODIUM_C99(X) X #endif + /** @todo + * + */ unsigned char *_sodium_alignedcalloc(unsigned char ** const unaligned_p, const size_t len); +/** + * Securely wipe a region in memory. + * + * @param[in] pnt the region on memory + * @param[in] size the size of the region to be wiped. + * + * @warning If a region has been allocated on the heap, you still have + * to make sure that it can't get swapped to disk, possibly using + * mlock(2). + * + */ SODIUM_EXPORT void sodium_memzero(void * const pnt, const size_t len); + /** @todo + * + */ SODIUM_EXPORT int sodium_memcmp(const void * const b1_, const void * const b2_, size_t size); + /** @todo + * + */ SODIUM_EXPORT char *sodium_bin2hex(char * const hex, const size_t hexlen, const unsigned char *bin, const size_t binlen); + /// @} #ifdef __cplusplus } #endif diff --git a/src/libsodium/include/sodium/version.h.in b/src/libsodium/include/sodium/version.h.in index ddc8cfd1..6d92ba2d 100644 --- a/src/libsodium/include/sodium/version.h.in +++ b/src/libsodium/include/sodium/version.h.in @@ -4,6 +4,10 @@ #include "export.h" +/** \addtogroup util + * @{ + */ + #define SODIUM_VERSION_STRING "@VERSION@" #define SODIUM_LIBRARY_VERSION_MAJOR @SODIUM_LIBRARY_VERSION_MAJOR@ @@ -13,15 +17,20 @@ extern "C" { #endif + /// Return the version string SODIUM_EXPORT const char *sodium_version_string(void); + /// Return the library's Minor version number. SODIUM_EXPORT int sodium_library_version_major(void); + + /// Return the library's Minor version number. SODIUM_EXPORT int sodium_library_version_minor(void); + /// @} #ifdef __cplusplus } #endif