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.
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.
