1 files changed, 82 insertions, 19 deletions

diff --git a/src/encryption.h b/src/encryption.h
index 5c6a08c..a23cbdf 100644
--- a/src/encryption.h
+++ b/src/encryption.h
@@ -13,35 +13,41 @@
 #define __VXGG_REWRITE___ENCRYPTION_H___1481879318188___
 
 #include <sodium.h>
+#include "shared.h"
 
-// Determines whether any function that calls libsodium functions also checks to make sure libsodium is actually initialized. May
-// cause unexpected issues with early exiting due to libsodium failing to initialize properly. It's recommended that you just
-// manually run `sodium_init()` in some main or init function of your own so that you can deal with a potential error yourself
+/// Determines whether any function that calls libsodium functions also checks to make sure libsodium is actually initialized. May
+/// cause unexpected issues with early exiting due to libsodium failing to initialize properly. It's recommended that you just
+/// manually run `sodium_init()` in some main or init function of your own so that you can deal with a potential error yourself
 #define ___VXGG___ALWAYS_CHECK_LIBSODIUM___ 1
 
-// Grants access to the `vxgg_setsodiumfailcb` function, which can be used to set a custom callback for what to do when libsodium
-// fails upon initialization 
+/// Grants access to the `vxgg_setsodiumfailcb` function, which can be used to set a custom callback for what to do when libsodium
+/// fails upon initialization 
 #define ___VXGG___USE_CLS_CALLBACK___ 1
 
 
 #if ___VXGG___ALWAYS_CHECK_LIBSODIUM___ > 0
-// Checks if sodium is initialized. Initializes it if not. If `___VXGG___ALWAYS_CHECK_LIBSODIUM___ > 0`, it's possible to set an error callback to avoid exiting the entire program. Otherwise calls `error()` if libsodium can't initialize
-void checksodium(void);
-
 #if ___VXGG___USE_CLS_CALLBACK___ > 0
-// Definition for the callback function that fires when a call to checksodium fails
+//! Definition for the callback function that fires when a call to checksodium fails
 typedef void (*vxgg_naclfailcb)(void*);
 
-// Sets the error callback for when libsodium fails. Runs `cb(data)` if `(sodium_init() < 0)`
+/**
+ * @brief Sets a callback and data pair to be ran if/when sodium fails to initialize
+ * 
+ * @param cb The new callback to set. Must be non-null
+ * @param data The data to be fed to the callback. May be null
+ */
 void vxgg_setsodiumfailcb(const vxgg_naclfailcb cb, void *data);
 #endif
 #endif
 
-// Chunk size for en/de-cryption. I originally wanted to use st_blksize from stat(), but given that those chunks may be of different
-// sizes between computers / filesystems / architectures / files, it's easier to just have this be a consistent macro
+/// Chunk size for en/decryption. I originally wanted to use st_blksize from stat(), but given that those chunks may be of different
+/// sizes between computers / filesystems / architectures / files, it's easier to just have this be a consistent macro
 #define CHUNKSIZE (1 << 9)
 
+const static char * test = "this is a test";
+
 // Fuck reading from a file. Even if someone ran strings on the binary and got this they wouldn't be able to regenerate the key
+//! A list of possible words for password creation
 #define PASSWORD_WORDS (\
     (const char * const []){\
         "the", "of", "to", "and", "for", "our", "their", "has", "in", "he", "a", "them", "that", "these", "by", "have", "we", \
@@ -96,27 +102,84 @@ void vxgg_setsodiumfailcb(const vxgg_naclfailcb cb, void *data);
         "reliance", "divine", "providence", "mutually", "pledge", "each", "fortunes", "sacred", "honor"\
     }\
 )
+//! Short macro for getting the `PASSWORD_WORDS` array size
 #define PASSWORD_WORDS_LEN (STATIC_ARRAY_LEN(PASSWORD_WORDS))
 
-// open() with the flags O_TMPFILE, O_WRONLY, O_CLOEXEC, and O_SYNC. Opened with mode S_IRUSR, S_IWUSR
+/**
+ * @brief open() with the flags O_TMPFILE, O_WRONLY, O_CLOEXEC, and O_SYNC. Opened with mode S_IRUSR, S_IWUSR
+ * 
+ * @param dest The filename the new descriptor should have. Must be non-null
+ * @retval (int)[-1,int] A new file descriptor. -1 on error
+ */
 int maketmp(const char * const dest);
 
-// Encrypt src to dst using libsodium's xchacha encryption suite
+/**
+ * @brief Encrypt src to dst using libsodium's xchacha encryption suite
+ * 
+ * @param src File to encrypt
+ * @param dst Destination to write encrypted file
+ * @param key Key for encryption
+ * @retval (int)[-1, 0] Returns 0 on success, sets errno and returns -1 on error 
+ */
 int encrypttofile(FILE *src, FILE *dst, const unsigned char key[crypto_secretstream_xchacha20poly1305_KEYBYTES]);
 
-// Decrypt src to dst using libsodium's xchacha encryption suite
+/**
+ * @brief Decrypt src to dst using libsodium's xchacha encryption suite
+ * 
+ * @param src File to decrypt
+ * @param dst Destination to write decrypted file
+ * @param key Key used to encrypt
+ * @retval (int)[-1, 0] Returns 0 on success, sets errno and returns -1 on error
+ */
 int decrypttofile(FILE *src, FILE *dst, const unsigned char key[crypto_secretstream_xchacha20poly1305_KEYBYTES]);
 
-// Encrypt file at `target` to `output` using Linux's named temp file system to do it in the background
+/**
+ * @brief Encrypt file at `target` to `output` using Linux's named temp file system to do it in the background
+ * 
+ * @param target 
+ * @param output 
+ * @param key 
+ * @retval (int)[,] 
+ */
 int encryptviatmp(const char * const target, const char * const output, const unsigned char key[crypto_secretstream_xchacha20poly1305_KEYBYTES]);
 
-// Decrypt the file at `encrypted` to `target`
+/**
+ * @brief Decrypt the file at `encrypted` to `target`
+ * 
+ * @param encrypted 
+ * @param target 
+ * @param key 
+ * @retval (int)[,] 
+ */
 int decryptto(const char * const encrypted, const char * const target, const unsigned char key[crypto_secretstream_xchacha20poly1305_KEYBYTES]);
 
-//
+/**
+ * @brief Link a file descriptor into the filesystem
+ * 
+ * @param target New filename the descriptor should have
+ * @param tgfd The file descriptor to link
+ * @retval (int)[-1, 0] 0 on success, -1 on error
+ */
 int linkto(const char * const target, int tgfd);
 
-//
+/**
+ * @brief Generate a password viable for use in the derivation of a key
+ * 
+ * @param str Pointer to a string. This will be filled by a malloc'ed string of words (the password). Must be non-null
+ * @param words The number of words to include in the password. A password of at least 20 words and probably not more than 40 is recommended
+ * @retval (int)[-1, words] On success, returns the number of words requested. On error, returns -1 and sets errno
+ */
 int genpassword(char **str, unsigned int words);
 
+/**
+ * @brief sodium_malloc wrapper. 
+ *
+ * Calls `error()` or `abort()` depnding on the value of `___VXGG___XALLOC_EXIT_ON_ERROR___`. Will make sure libsodium is initialized if `___VXGG___ALWAYS_CHECK_LIBSODIUM___ > 0`
+ * 
+ * @param size 
+ * @retval (void*) A pointer to some data allocated via `sodium_malloc()` 
+ */
+void* xsodium_malloc(size_t size);
+
+
 #endif
\ No newline at end of file