Updated README file.

README.md

@@ -1,26 +1,34 @@
-SlunkCrypt
-==========
+![SlunkCrypt](etc/img/SlunkCrypt-Logo.png)
 
-An experimental cryptography library and command-line tool.
+Introduction
+============
+
+SlunkCrypt is an experimental cryptography library and command-line tool.
 
 
 Legal Warning
--------------
+=============
 
 Use of SlunkCrypt may be illegal in countries where encryption is outlawed. We believe it is legal to use SlunkCrypt in many countries all around the world, but we are not lawyers, and so if in doubt you should seek legal advice before downloading it. You may find useful information at [cryptolaw.org](http://www.cryptolaw.org/), which collects information on cryptography laws in many countries, but we can't vouch for its correctness.
 
 
 Command-line Usage
-------------------
+==================
 
-This section describes the SlunkCypt command-line program:
+This section describes the SlunkCypt command-line front-end.
 
-**Synopsis:**
+Synopsis
+--------
+
+The SlunkCypt command-line program is invoked as follows:
 
     slunkcrypt --encrypt [[@][:]<passphrase>] <input.txt> <output.enc>
     slunkcrypt --decrypt [[@][:]<passphrase>] <input.enc> <output.txt>
 
-**Commands:**
+Commands
+--------
+
+One of the following commands must be chosen:
 
 - **`--encrypt` (`-e`):**  
   Encrypt the plaintext in the given input file. The ciphertext is written to the specified output file.
@@ -29,7 +37,11 @@ This section describes the SlunkCypt command-line program:
 - **`--self-test` (`-t`):**  
   Run self-test and exit application.
 
-**Options:**
+Options
+-------
+
+The following options are available:
+
 - If `<passphrase>` is prefixed with a **`@`** character, then it specifies the file to read the passphrase from.  
   *Note:* Only the first non-empty line in the specified file is used!
 - If `<passphrase>` is prefixed with a **`:`** character, then the leading character is ignored.
@@ -38,13 +50,14 @@ This section describes the SlunkCypt command-line program:
 
 
 Programming Interface (API)
----------------------------
+===========================
 
-### C99 API
+C99 API
+-------
 
-This section describes the "low-level" C99 API of the SlunkCypt library:
+This section describes the "low-level" C99 API of the SlunkCypt library.
 
-#### slunkcrypt_alloc()
+### slunkcrypt_alloc()
 
 Allocate and initialize a new SlunkCrypt encryption/decryption context.
 
@@ -61,7 +74,7 @@ Allocate and initialize a new SlunkCrypt encryption/decryption context.
     *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!
+    The password to "protect" the message. The password is given as an array of bytes (`uint8_t`), e.g. UTF-8 encoded characters; 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.
   
@@ -73,7 +86,7 @@ Allocate and initialize a new SlunkCrypt encryption/decryption context.
     
     *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()
+### slunkcrypt_reset()
   
 Re-initialize an existing SlunkCrypt encryption/decryption context.
 
@@ -100,7 +113,7 @@ Re-initialize an existing SlunkCrypt encryption/decryption context.
 ***Return value:***
   * If successful, `SLUNKCRYPT_SUCCESS` is returned; otherwise `SLUNKCRYPT_FAILURE` or `SLUNKCRYPT_ABORTED` is returned.
 
-#### slunkcrypt_free()
+### slunkcrypt_free()
 
 De-allocate an existing SlunkCrypt encryption/decryption context. This will "clear" and release any memory occupied by the context.
 
@@ -129,6 +142,62 @@ Generate a new random *nonce* (number used once), using the system's "cryptograp
 ***Return value:***
   * If successful, `SLUNKCRYPT_SUCCESS` is returned; otherwise `SLUNKCRYPT_FAILURE` or `SLUNKCRYPT_ABORTED` is returned.
 
+### slunkcrypt_encrypt()
+
+Encrypt the next message chunk, using separate input/output buffers.
+
+    int slunkcrypt_encrypt(
+        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 encrypting the message chunk. This context will be updated.
+
+ * `input`  
+    A pointer to the *input* buffer containing the next chunk of the plaintext to be encrypted. The plaintext is given as an array of bytes (`uint8_t`). This can be arbitrary binary data, e.g. UTF-8 encoded text. NULL bytes are **not** treated specially.
+    
+    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 ciphertext chunk that corresponds to the given plaintext chunk will be stored. The ciphertext 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 encrypted data. If the buffer is longer than `length` bytes, then only the first `length` bytes of the buffer will be filled with encrypted data!
+
+ * `length`  
+   The length of the plaintext 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_encrypt_inplace()
+
+Encrypt the next message chunk, using a single buffer.
+
+    int slunkcrypt_encrypt(
+        const slunkcrypt_t context,
+        uint8_t* const buffer,
+        size_t length
+    );
+
+***Parameters:***
+ * `context`  
+    The existing SlunkCrypt context to be used for encrypting the message chunk. This context will be updated.
+
+ * `buffer`  
+    A pointer to the buffer initially containing the next chunk of the plaintext to be encrypted. The plaintext is given as an array of bytes (`uint8_t`). This can be arbitrary binary data, e.g. UTF-8 encoded text. NULL bytes are **not** treated specially. The ciphertext chunk that corresponds to the given plaintext 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 encrypted 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 plaintext 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 encrypted data, in bytes.
+
+***Return value:***
+  * If successful, `SLUNKCRYPT_SUCCESS` is returned; otherwise `SLUNKCRYPT_FAILURE` or `SLUNKCRYPT_ABORTED` is returned.
+
 
 License
 -------