Updated README file.

README.md

@@ -193,7 +193,7 @@ Encrypt the next message chunk, using separate input/output buffers.
 
 Encrypt the next message chunk, using a single buffer.
 
-    int slunkcrypt_encrypt(
+    int slunkcrypt_encrypt_inplace(
         const slunkcrypt_t context,
         uint8_t* const buffer,
         size_t length
@@ -214,6 +214,104 @@ Encrypt the next message chunk, using a single buffer.
 ***Return value:***
   * If successful, `SLUNKCRYPT_SUCCESS` is returned; otherwise `SLUNKCRYPT_FAILURE` or `SLUNKCRYPT_ABORTED` is returned.
 
+### slunkcrypt_decrypt()
+
+Decrypt the next ciphertext chunk, using separate input/output buffers.
+
+    int slunkcrypt_decrypt(
+        const slunkcrypt_t context,
+        const uint8_t *const input,
+        uint8_t* const output,
+        size_t length
+    );
+
+***Parameters:***
+ * `context`  
+    The existing SlunkCrypt context to be used for decrypting the ciphertext chunk. This context will be updated.
+
+ * `input`  
+    A pointer to the *input* buffer containing the next chunk of the ciphertext to be decrypted. The ciphertext is given as an array of bytes (`uint8_t`).
+    
+    The *input* buffer must contain *at least* `length` bytes of data. If the buffer is longer than `length` bytes, then only the first `length` bytes will be processed and the remainder is ignored!
+
+ * `output`  
+    A pointer to the *output* buffer where the plaintext chunk that corresponds to the given ciphertext chunk will be stored. The plaintext is stored as an array of bytes (`uint8_t`); it has the same length as the plaintext data.
+    
+    The *output* buffer must provide sufficient space for storing *at least* `length` bytes of decrypted data. If the buffer is longer than `length` bytes, then only the first `length` bytes of the buffer will be filled with decrypted data!
+
+ * `length`  
+   The length of the ciphertext chunk contained in the *input* buffer given by the `input` parameter, in bytes. At the same time, this determines the minimum required size of the *output* buffer given by the `output` parameters, in bytes.
+
+***Return value:***
+  * If successful, `SLUNKCRYPT_SUCCESS` is returned; otherwise `SLUNKCRYPT_FAILURE` or `SLUNKCRYPT_ABORTED` is returned.
+
+### slunkcrypt_decrypt_inplace()
+
+Decrypt the next ciphertext chunk, using a single buffer.
+
+    int slunkcrypt_decrypt_inplace(
+        const slunkcrypt_t context,
+        uint8_t* const buffer,
+        size_t length
+    );
+
+***Parameters:***
+ * `context`  
+    The existing SlunkCrypt context to be used for decrypting the ciphertext chunk. This context will be updated.
+
+ * `buffer`  
+    A pointer to the buffer initially containing the next chunk of the ciphertext to be decrypted. The ciphertext is given as an array of bytes (`uint8_t`). The plaintext chunk that corresponds to the given ciphertext chunk will be stored to the *same* buffer, thus replacing the plaintext data.
+    
+    The buffer must initially contain *at least* `length` bytes of input data; the first `length` bytes of the buffer will be overwritten with the decrypted data. If the buffer is longer than `length` bytes, then only the first `length` bytes will be processed and overwritten.
+
+ * `length`  
+   The length of the ciphertext chunk initially contained in the input/output buffer given by the `buffer` parameter, in bytes. At the same time, this determines the portion of the input/output buffer that will be overwritten with decrypted data, in bytes.
+
+***Return value:***
+  * If successful, `SLUNKCRYPT_SUCCESS` is returned; otherwise `SLUNKCRYPT_FAILURE` or `SLUNKCRYPT_ABORTED` is returned.
+
+### slunkcrypt_random_bytes()
+
+Generate a sequence of random bytes, using the system's "cryptographically secure" entropy source.
+
+    size_t slunkcrypt_random_bytes(
+      uint8_t* const buffer,
+      const size_t length
+    );
+
+***Parameters:***
+ * `buffer`  
+   A pointer to the *output* buffer where the random bytes will be stored.
+
+   The *output* buffer must provide sufficient space for storing *at least* `length` bytes of random data. If the buffer is longer than `length` bytes, then *at most* the first `length` bytes of the buffer will be filled with random data!
+
+ * `length`  
+   The number of random bytes to be generated. At the same time, this determines the minimum required size of the *output* buffer given by the `output` parameters, in bytes.
+
+***Return value:***
+  * If successful, the number of random bytes that have been generated and stored to the *output* buffer is returned; otherwise `0` is returned.
+    
+    The number of generated bytes can be *at most* `length`. Less than `length` bytes *may* be generated, if the entropy source could **not** provide the requested number of bytes at this time. In that case, you can try again.
+
+
+### slunkcrypt_bzero()
+
+Erase the contents of a byte array, by overwriting it with *zero* bytes, guaranteeing that compiler optimizations will **not** remove the erase operation.
+
+    void slunkcrypt_bzero(
+      void* const buffer,
+      const size_t length
+    );
+
+***Parameters:***
+ * `buffer`  
+   A pointer to the buffer whose content is to be erased.
+
+   The buffer must be *at least* `length` bytes in size. If the buffer is longer than `length` bytes, then *only* the first `length` bytes of the buffer will be erased!
+
+ * `length`  
+   The size of the buffer to be erased, in bytes.
+
 
 License
 =======