From 4fafbcca259f8f1152a9ad1075a6d2f288c9d94b Mon Sep 17 00:00:00 2001 From: LoRd_MuldeR Date: Sun, 15 Nov 2020 19:47:40 +0100 Subject: [PATCH] Updated README file. --- README.md | 95 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 95 insertions(+) diff --git a/README.md b/README.md index c1324e8..4072f5b 100644 --- a/README.md +++ b/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 [[@][:]] @@ -35,6 +37,99 @@ Command-line Usage - If `` 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 -------