Updated README file.

README.md

@@ -13,6 +13,8 @@ Use of SlunkCrypt may be illegal in countries where encryption is outlawed. We b
 Command-line Usage
 ------------------
 
+This section describes the SlunkCypt command-line program:
+
 **Synopsis:**
 
     slunkcrypt --encrypt [[@][:]<passphrase>] <input.txt> <output.enc>
@@ -35,6 +37,99 @@ Command-line Usage
 - If `<passphrase>` is set to **`@-`**, then the passphrase is read from the standard input stream.
 
 
+Programming Interface (API)
+---------------------------
+
+### C99 API
+
+This section describes the "low-level" C99 API of the SlunkCypt library:
+
+#### slunkcrypt_alloc()
+
+Allocate and initialize a new SlunkCrypt encryption/decryption context.
+
+    slunkcrypt_t slunkcrypt_alloc(
+        const uint64_t nonce,
+        const uint8_t *const passwd,
+        const size_t passwd_len
+    );
+
+***Parameters:***
+  * `nonce`  
+    The *nonce* (number used once) to be used for the encryption/decryption process. The purpose of the nonce is to ensure that each message will be encrypted differently, even when the same password is used to encrypt *multiple* (possibly identical) messages. Therefore, a new *random* nonce **must** be chosen for each message to be encrypted! It is *not* necessary to keep the nonce confidential, but the same nonce **must** be used for both, encryption *and* decryption. Typically, the nonce is stored/transmitted alongside the ciphertext.
+    
+    *Note:* It is recommended to generate a random nonce via the `slunkcrypt_generate_nonce()` function for each message!
+  
+  * `passwd`  
+    The password to "protect" the message. The password is given as an array of bytes (e.g. UTF-8 encoded characters) of type `uint8_t`; a terminating NULL character is *not* required, as the length of the password is specified explicitly. The same password **may** be used to encrypt *multiple* messages. Also, the same password **must** be used for both, encryption *and* decryption; it will *only* be possible decrypt the ciphertext, if the "correct" password is known. The password must be kept confidential under all circumstances!
+    
+    *Note:* In order to thwart *brute force* attacks, it is recommended to choose a "random" password that is at least 12 characters in length and that consists of upper-case characters, lower-case characters, digits as well as other "special" characters.
+  
+  * `passwd_len`  
+    The length of password given by the `passwd` parameter, in bytes, **not** counting a terminating NULL character. The minimum/maximum length of the password are given by the `SLUNKCRYPT_PWDLEN_MIN` and `SLUNKCRYPT_PWDLEN_MAX` constants, respectively.
+
+***Return value:***
+  * If successful, a handle to the new SlunkCrypt context is return; otherwise `SLUNKCRYPT_NULL` is returned.
+    
+    *Note:* Applications **should** treat `slunkcrypt_t` as an *opaque* handle type. Also, as soon as the SlunkCrypt context is *not* needed anymore, the application **shall** call `slunkcrypt_free()` in order to "clear" and de-allocate that context.
+
+#### slunkcrypt_reset()
+  
+Re-initialize an existing SlunkCrypt encryption/decryption context.
+
+    int slunkcrypt_reset(
+        const slunkcrypt_t context,
+        const uint64_t nonce,
+        const uint8_t *const passwd,
+        const size_t passwd_len
+    );
+
+***Parameters:***
+  * `context`  
+    The existing SlunkCrypt context to be re-initialized. This must be a valid handle that was returned by a previous invocation of the `slunkcrypt_alloc()` function and that has **not** been `free`'d since then.
+
+  * `nonce`  
+    Please refer to the  `slunkcrypt_alloc()` function for details!
+
+  * `passwd`  
+    Please refer to the  `slunkcrypt_alloc()` function for details!
+
+  * `passwd_len`  
+    Please refer to the  `slunkcrypt_alloc()` function for details!
+
+***Return value:***
+  * If successful, `SLUNKCRYPT_SUCCESS` is returned; otherwise `SLUNKCRYPT_FAILURE` or `SLUNKCRYPT_ABORTED` is returned.
+
+#### slunkcrypt_free()
+
+De-allocate an existing SlunkCrypt encryption/decryption context. This will "clear" and release any memory occupied by the context.
+
+    void slunkcrypt_free(
+        const slunkcrypt_t context
+    );
+
+***Parameters:***
+ * `context`  
+    The existing SlunkCrypt context to be de-allocated. This must be a valid handle that was returned by a previous invocation of the `slunkcrypt_alloc()` function and that has **not** been `free`'d since then.
+    
+    *Note:* Once a handle has been passed to this function, that handle is *invalidated* and **must not** be used again!
+
+### slunkcrypt_generate_nonce()
+
+Generate a new random *nonce* (number used once), using the system's "cryptographically secure" entropy source.
+
+    int slunkcrypt_generate_nonce(
+      int64_t* const nonce
+    );
+
+***Parameters:***
+ * `nonce`  
+   A pointer to a variable of type `int64_t` that receives the new random nonce.
+
+***Return value:***
+  * If successful, `SLUNKCRYPT_SUCCESS` is returned; otherwise `SLUNKCRYPT_FAILURE` or `SLUNKCRYPT_ABORTED` is returned.
+
+
 License
 -------