Updated README file.
This commit is contained in:
parent
06f57ca483
commit
469981bef2
GPG Key ID:
2B5913365F57E03F
249
README.md
249
README.md
@ -176,7 +176,7 @@ Here is a simple example on how to use the SlunkCrypt [**`Encryptor`**](#encrypt
|
||||
input.read(reinterpret_cast<char*>(buffer), BUFF_SIZE);
|
||||
if ((!input.bad()) && (input.gcount() > 0))
|
||||
{
|
||||
if (!slunk_encrypt.encrypt_inplace(buffer, (size_t)input.gcount()))
|
||||
if (!slunk_encrypt.inplace(buffer, (size_t)input.gcount()))
|
||||
{
|
||||
/* Implement error handling here */
|
||||
}
|
||||
@ -204,7 +204,7 @@ Here is a simple example on how to use the SlunkCrypt [**`Decryptor`**](#decrypt
|
||||
input.read(reinterpret_cast<char*>(buffer), BUFF_SIZE);
|
||||
if ((!input.bad()) && (input.gcount() > 0))
|
||||
{
|
||||
if (!slunk_decrypt.decrypt_inplace(buffer, (size_t)input.gcount()))
|
||||
if (!slunk_decrypt.inplace(buffer, (size_t)input.gcount()))
|
||||
{
|
||||
/* Implement error handling here */
|
||||
}
|
||||
@ -241,11 +241,11 @@ Create and initialize a new **``Encryptor``** instance. Also generated a new, ra
|
||||
|
||||
* Throws `std::runtime_error`, if the nonce could not be generated, or if the SlunkCrypt context could not be allocated.
|
||||
|
||||
#### Encryptor::encrypt() [1]
|
||||
#### Encryptor::process() [1]
|
||||
|
||||
Encrypt the next message chunk, using separate input/output buffers.
|
||||
|
||||
bool encrypt(
|
||||
bool process(
|
||||
const uint8_t *const input,
|
||||
uint8_t *const output,
|
||||
size_t length
|
||||
@ -270,11 +270,11 @@ Encrypt the next message chunk, using separate input/output buffers.
|
||||
|
||||
* If successful, `true` is returned; otherwise `false` is returned.
|
||||
|
||||
#### Encryptor::encrypt() [2]
|
||||
#### Encryptor::process() [2]
|
||||
|
||||
Encrypt the next message chunk, using separate input/output containers (`std::vector`).
|
||||
|
||||
bool encrypt(
|
||||
bool process(
|
||||
const std::vector<uint8_t> &input,
|
||||
std::vector<uint8_t> &output
|
||||
);
|
||||
@ -293,11 +293,11 @@ Encrypt the next message chunk, using separate input/output containers (`std::ve
|
||||
|
||||
* If successful, `true` is returned; otherwise `false` is returned. The function fails, if the *output* `std::vector` is too small.
|
||||
|
||||
#### Encryptor::encrypt_inplace() [1]
|
||||
#### Encryptor::inplace() [1]
|
||||
|
||||
Encrypt the next message chunk, using a single buffer.
|
||||
|
||||
bool encrypt_inplace(
|
||||
bool inplace(
|
||||
uint8_t *const buffer,
|
||||
size_t length
|
||||
);
|
||||
@ -316,11 +316,11 @@ Encrypt the next message chunk, using a single buffer.
|
||||
|
||||
* If successful, `true` is returned; otherwise `false` is returned.
|
||||
|
||||
#### Encryptor::encrypt_inplace() [2]
|
||||
#### Encryptor::inplace() [2]
|
||||
|
||||
Encrypt the next message chunk, using a single container (`std::vector`).
|
||||
|
||||
bool encrypt_inplace(
|
||||
bool inplace(
|
||||
std::vector<uint8_t> &buffer
|
||||
);
|
||||
|
||||
@ -374,11 +374,11 @@ Create and initialize a new **``Decryptor``** instance.
|
||||
|
||||
* Throws `std::runtime_error`, if the SlunkCrypt context could not be allocated.
|
||||
|
||||
#### Decryptor::decrypt() [1]
|
||||
#### Decryptor::process() [1]
|
||||
|
||||
Decrypt the next message chunk, using separate input/output buffers.
|
||||
|
||||
bool decrypt(
|
||||
bool process(
|
||||
const uint8_t *const input,
|
||||
uint8_t *const output,
|
||||
size_t length
|
||||
@ -403,11 +403,11 @@ Decrypt the next message chunk, using separate input/output buffers.
|
||||
|
||||
* If successful, `true` is returned; otherwise `false` is returned.
|
||||
|
||||
#### Decryptor::decrypt() [2]
|
||||
#### Decryptor::process() [2]
|
||||
|
||||
Decrypt the next message chunk, using separate input/output containers (`std::vector`).
|
||||
|
||||
bool decrypt(
|
||||
bool process(
|
||||
const std::vector<uint8_t> &input,
|
||||
std::vector<uint8_t> &output
|
||||
);
|
||||
@ -426,11 +426,11 @@ Decrypt the next message chunk, using separate input/output containers (`std::ve
|
||||
|
||||
* If successful, `true` is returned; otherwise `false` is returned. The function fails, if the *output* `std::vector` is too small.
|
||||
|
||||
#### Decryptor::decrypt_inplace() [1]
|
||||
#### Decryptor::inplace() [1]
|
||||
|
||||
Decrypt the next message chunk, using a single buffer.
|
||||
|
||||
bool decrypt_inplace(
|
||||
bool inplace(
|
||||
uint8_t *const buffer,
|
||||
size_t length
|
||||
);
|
||||
@ -449,11 +449,11 @@ Decrypt the next message chunk, using a single buffer.
|
||||
|
||||
* If successful, `true` is returned; otherwise `false` is returned.
|
||||
|
||||
#### Decryptor::decrypt_inplace() [2]
|
||||
#### Decryptor::inplace() [2]
|
||||
|
||||
Decrypt the next message chunk, using a single container (`std::vector`).
|
||||
|
||||
bool decrypt_inplace(
|
||||
bool inplace(
|
||||
std::vector<uint8_t> &buffer
|
||||
);
|
||||
|
||||
@ -471,14 +471,19 @@ C99 API
|
||||
|
||||
This section describes the "low-level" C99 API of the SlunkCypt library.
|
||||
|
||||
### slunkcrypt_alloc()
|
||||
### Functions
|
||||
|
||||
The SlunkCypt library defines the following functions:
|
||||
|
||||
#### 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
|
||||
const size_t passwd_len,
|
||||
const int mode
|
||||
);
|
||||
|
||||
***Parameters:***
|
||||
@ -486,7 +491,7 @@ Allocate and initialize a new SlunkCrypt encryption/decryption context.
|
||||
* `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!
|
||||
*Note:* It is recommended to generate a random nonce via the [`slunkcrypt_generate_nonce()`](#slunkcrypt_generate_nonce) function for each message!
|
||||
|
||||
* `passwd`
|
||||
The password to "protect" the message. The password is given as a byte array (`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!
|
||||
@ -496,13 +501,16 @@ Allocate and initialize a new SlunkCrypt encryption/decryption context.
|
||||
* `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.
|
||||
|
||||
* `mode`
|
||||
The mode of operation. Use `SLUNKCRYPT_ENCRYPT` in order to set up this context for *encryption*, or use `SLUNKCRYPT_DECRYPT` in order to set up this context for *decryption*.
|
||||
|
||||
***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.
|
||||
*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()`](#slunkcrypt_free) in order to "erase" and de-allocate that context. If a SlunkCrypt context is *not* de-allocated properly, it will result in a memory leak!
|
||||
|
||||
### slunkcrypt_reset()
|
||||
#### slunkcrypt_reset()
|
||||
|
||||
Re-initialize an existing SlunkCrypt encryption/decryption context.
|
||||
|
||||
@ -510,28 +518,23 @@ Re-initialize an existing SlunkCrypt encryption/decryption context.
|
||||
const slunkcrypt_t context,
|
||||
const uint64_t nonce,
|
||||
const uint8_t *const passwd,
|
||||
const size_t passwd_len
|
||||
const size_t passwd_len,
|
||||
const int mode
|
||||
);
|
||||
|
||||
***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.
|
||||
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()`](#slunkcrypt_alloc) function.
|
||||
|
||||
* `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!
|
||||
* *other parameters*:
|
||||
Please refer to the [`slunkcrypt_alloc()`](#slunkcrypt_alloc) function for details!
|
||||
|
||||
***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.
|
||||
|
||||
@ -542,11 +545,11 @@ De-allocate an existing SlunkCrypt encryption/decryption context. This will "cle
|
||||
***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.
|
||||
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()`](#slunkcrypt_alloc) function.
|
||||
|
||||
*Note:* Once a handle has been passed to this function, that handle is *invalidated* and **must not** be used again!
|
||||
|
||||
### slunkcrypt_generate_nonce()
|
||||
#### slunkcrypt_generate_nonce()
|
||||
|
||||
Generate a new random *nonce* (number used once), using the system's "cryptographically secure" entropy source.
|
||||
|
||||
@ -563,11 +566,11 @@ Generate a new random *nonce* (number used once), using the system's "cryptograp
|
||||
|
||||
* If successful, `SLUNKCRYPT_SUCCESS` is returned; otherwise `SLUNKCRYPT_FAILURE` or `SLUNKCRYPT_ABORTED` is returned.
|
||||
|
||||
### slunkcrypt_encrypt()
|
||||
#### slunkcrypt_process()
|
||||
|
||||
Encrypt the next message chunk, using separate input/output buffers.
|
||||
Encrypt or decrypt the next message chunk, using separate input/output buffers.
|
||||
|
||||
int slunkcrypt_encrypt(
|
||||
int slunkcrypt_process(
|
||||
const slunkcrypt_t context,
|
||||
const uint8_t *const input,
|
||||
uint8_t *const output,
|
||||
@ -577,30 +580,32 @@ Encrypt the next message chunk, using separate input/output buffers.
|
||||
***Parameters:***
|
||||
|
||||
* `context`
|
||||
The existing SlunkCrypt context to be used for encrypting the message chunk. This context will be updated.
|
||||
The existing SlunkCrypt context to be used for processing the message chunk. This context will be updated.
|
||||
|
||||
*Note:* This function operates either in "encryption" mode or in "decryption" mode, depending on how the given SlunkCrypt context has been [initialized](#slunkcrypt_alloc) or [re-initialized](#slunkcrypt_reset).
|
||||
|
||||
* `input`
|
||||
A pointer to the *input* buffer containing the next chunk of the plaintext to be encrypted. The plaintext is given as a byte array (`uint8_t`). This can be arbitrary binary data, e.g. UTF-8 encoded text. NULL bytes are **not** treated specially.
|
||||
A pointer to the *input* buffer containing the next chunk of the plaintext to be encrypted (*encryption* mode), or the next chunk of the ciphertext to be decrypted (*decryption* mode). The input data is given as a byte array (`uint8_t`). This can be arbitrary binary data, e.g. UTF-8 encoded text. NULL bytes are **not** treated specially by this function.
|
||||
|
||||
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!
|
||||
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; 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 a byte array (`uint8_t`); it has the same length as the plaintext data.
|
||||
A pointer to the *output* buffer where the ciphertext that corresponds to the given plaintext chunk (*encryption* mode), or the plaintext that corresponds to the given ciphertext chunk (*decryption* mode) will be stored. The output data is stored as a byte array (`uint8_t`) and it always has the same length as the input 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!
|
||||
The *output* buffer **must** provide sufficient space for storing *at least* `length` bytes. If the buffer is longer than `length` bytes, then only the first `length` bytes will be filled!
|
||||
|
||||
* `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.
|
||||
The length of the given plaintext chunk (*encryption* mode), or the length of the given ciphertext chunk (*decryption* mode) in the `input` buffer, in bytes. At the same time, this parameter determines the minimum required size of the `output` buffer, in bytes. If this parameter is set to *zero*, the function does nothing; this is *not* considered an error.
|
||||
|
||||
***Return value:***
|
||||
|
||||
* If successful, `SLUNKCRYPT_SUCCESS` is returned; otherwise `SLUNKCRYPT_FAILURE` or `SLUNKCRYPT_ABORTED` is returned.
|
||||
|
||||
### slunkcrypt_encrypt_inplace()
|
||||
#### slunkcrypt_inplace()
|
||||
|
||||
Encrypt the next message chunk, using a single buffer.
|
||||
Encrypt or decrypt the next message chunk, using a *single* input/output buffer.
|
||||
|
||||
int slunkcrypt_encrypt_inplace(
|
||||
int slunkcrypt_inplace(
|
||||
const slunkcrypt_t context,
|
||||
uint8_t *const buffer,
|
||||
size_t length
|
||||
@ -609,81 +614,23 @@ Encrypt the next message chunk, using a single buffer.
|
||||
***Parameters:***
|
||||
|
||||
* `context`
|
||||
The existing SlunkCrypt context to be used for encrypting the message chunk. This context will be updated.
|
||||
The existing SlunkCrypt context to be used for processing the message chunk. This context will be updated.
|
||||
|
||||
*Note:* This function operates either in "encryption" mode or in "decryption" mode, depending on how the given SlunkCrypt context has been [initialized](#slunkcrypt_alloc) or [re-initialized](#slunkcrypt_reset).
|
||||
|
||||
* `buffer`
|
||||
A pointer to the buffer initially containing the next chunk of the plaintext to be encrypted. The plaintext is given as a byte array (`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.
|
||||
A pointer to the buffer containing the next chunk of the plaintext to be encrypted (*encryption* mode), or the next chunk of the ciphertext to be decrypted (*decryption* mode). The input data is given as a byte array (`uint8_t`). This can be arbitrary binary data, e.g. UTF-8 encoded text. NULL bytes are **not** treated specially by this function. The ciphertext that corresponds to the given plaintext chunk (*encryption* mode), or the plaintext that corresponds to the given ciphertext chunk (*decryption* mode) will be stored to the ***same*** buffer.
|
||||
|
||||
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.
|
||||
The given buffer **must** initially contain *at least* `length` bytes of input data. The first `length` bytes in the buffer will be processed and will be *overwritten* with the corresponding output data. If the buffer is longer than `length` bytes, then only the first `length` bytes in the buffer will be processed; the remainder is ignored!
|
||||
|
||||
* `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.
|
||||
The length of the plaintext chunk (*encryption* mode), or the length of the ciphertext chunk (*decryption* mode) initially contained in the input/output buffer, in bytes.
|
||||
|
||||
***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 a byte array (`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 a byte array (`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 a byte array (`uint8_t`). The plaintext that corresponds to the given ciphertext 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()
|
||||
#### slunkcrypt_random_bytes()
|
||||
|
||||
Generate a sequence of random bytes, using the system's "cryptographically secure" entropy source.
|
||||
|
||||
@ -697,19 +644,19 @@ Generate a sequence of random bytes, using the system's "cryptographically secur
|
||||
* `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!
|
||||
The *output* buffer **must** provide sufficient space for storing *at least* `length` bytes of random data. *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.
|
||||
The number of random bytes to be generated. At the same time, this parameter determines the minimum required size of the `output` buffer, 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 random bytes that have been generated and that have been stored to the `output` buffer buffer 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.
|
||||
The number of generated random bytes can be *at most* `length`. Less than `length` random bytes will be generated, if and only if the the system's "cryptographically secure" entropy source could *not* provide the requested number of bytes at this time – in that case, you can try again later. The number of generated bytes can be as low as **0**.
|
||||
|
||||
|
||||
### slunkcrypt_bzero()
|
||||
#### slunkcrypt_bzero()
|
||||
|
||||
Erase the contents of a byte array, by overwriting it with *zero* bytes. Compiler optimizations will **not** remove the erase operation.
|
||||
|
||||
@ -723,35 +670,81 @@ Erase the contents of a byte array, by overwriting it with *zero* bytes. Compile
|
||||
* `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; the remainder of the buffer will *not* be modified!
|
||||
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.
|
||||
|
||||
### Global variables
|
||||
|
||||
The SlunkCypt library defines the following global variables:
|
||||
|
||||
#### Version information
|
||||
|
||||
These variables can be used to determine the version of the SlunkCrypt library at runtime, using the [semantic versioning](https://semver.org/spec/v2.0.0.html) scheme:
|
||||
|
||||
* `const uint16_t SLUNKCRYPT_VERSION_MAJOR` – The current *major* version.
|
||||
* `const uint16_t SLUNKCRYPT_VERSION_MINOR` – The current *minor* version.
|
||||
* `const uint16_t SLUNKCRYPT_VERSION_PATCH` – The current *patch* version.
|
||||
* `const char *SLUNKCRYPT_BUILD` – The build date and time, as a C string, in the *"mmm dd yyyy hh:mm:ss"* format.
|
||||
|
||||
#### Abort request
|
||||
|
||||
If this flag is set to a non-zero value by the application, any ongoing SlunkCypt library invocation will be aborted as quickly as possible:
|
||||
|
||||
* `volatile int g_slunkcrypt_abort_flag` – The global abort flag.
|
||||
|
||||
*Note:* Applications may set this flag in their signal handler, e.g. when a `SIGINT` is received, in order to "gracefully" shut down the SlunkCypt library. All long-running library functions will return `SLUNKCRYPT_ABORTED`, if the invocation was interrupted. The application still is responsible for [free](#slunkcrypt_free)'ing any SlunkCypt contexts that it allocated successfully!
|
||||
|
||||
### Constants
|
||||
|
||||
The SlunkCypt library defines the following constants:
|
||||
|
||||
#### Mode of operation
|
||||
|
||||
The SlunkCypt library supports the following modes of operation:
|
||||
|
||||
* `SLUNKCRYPT_ENCRYPT` – Run library in *encryption* mode, i.e. consume plaintext and produce ciphertext.
|
||||
* `SLUNKCRYPT_DECRYPT` – Run library in *decryption* mode, i.e. consume ciphertext and produce plaintext.
|
||||
|
||||
#### Limits
|
||||
|
||||
The following limits are defined for the SlunkCypt library:
|
||||
|
||||
* `SLUNKCRYPT_PWDLEN_MIN` – The *minimum* required length of a password, currently **8** bytes.
|
||||
* `SLUNKCRYPT_PWDLEN_MAX` – The *maximum* allowed length of a password, currently **256** bytes.
|
||||
|
||||
#### Error codes
|
||||
|
||||
SlunkCypt library functions that return an error code may return one of the following constants:
|
||||
|
||||
* `SLUNKCRYPT_SUCCESS` – The operation completed successfully.
|
||||
* `SLUNKCRYPT_FAILURE` – The operation has failed.
|
||||
* `SLUNKCRYPT_ABORTED` – The operation was aborted before completion, as requested by the application.
|
||||
|
||||
Thread safety
|
||||
-------------
|
||||
|
||||
The following functions are fully "thread-safe" and thus may safely be called by *any* thread at *any* time ***without*** the need for synchronization:
|
||||
|
||||
* `slunkcrypt_alloc()`
|
||||
* `slunkcrypt_generate_nonce()`
|
||||
* `slunkcrypt_random_bytes()`
|
||||
* `slunkcrypt_bzero()`
|
||||
* `Encryptor::Encryptor()`
|
||||
* `Decryptor::Decryptor()`
|
||||
|
||||
The following functions are "reentrant" and thus may safely be called by *any* thread at *any* time ***without*** the need for synchronization – provided that each instance of `slunkcrypt_t`, `Encryptor` or `Decryptor` is "owned" by a *single* thread **and** each instance will *exclusively* be access by its respective "owner" thread:
|
||||
The following functions are "reentrant" and thus may safely be called by *any* thread at *any* time ***without*** the need for synchronization – provided that each instance of `slunkcrypt_t`, `Encryptor` or `Decryptor` is "owned" by a *single* thread **and** that each instance will *exclusively* be access by its respective "owner" thread:
|
||||
|
||||
* `slunkcrypt_reset()`
|
||||
* `slunkcrypt_free()`
|
||||
* `slunkcrypt_encrypt()`
|
||||
* `slunkcrypt_encrypt_inplace()`
|
||||
* `slunkcrypt_decrypt()`
|
||||
* `slunkcrypt_decrypt_inplace()`
|
||||
* `Encryptor::encrypt()`
|
||||
* `Encryptor::encrypt_inplace()`
|
||||
* `slunkcrypt_process()`
|
||||
* `slunkcrypt_inplace()`
|
||||
* `Encryptor::process()`
|
||||
* `Encryptor::inplace()`
|
||||
* `Encryptor::get_nonce()`
|
||||
* `Decryptor::decrypt()`
|
||||
* `Decryptor::decrypt_inplace()`
|
||||
* `Decryptor::process()`
|
||||
* `Decryptor::inplace()`
|
||||
|
||||
***Note:*** If the same `slunkcrypt_t`, `Encryptor` or `Decryptor` instance needs to be shared across *multiple* threads (i.e. the same instance is accessed by *concurrent* threads), then the application **must** *serialize* any invocation of the above functions on that shared instance, by using a suitable synchronization mechanism! This can be achieved by using a [*mutex*](https://linux.die.net/man/3/pthread_mutex_lock).
|
||||
|
||||
|
||||
2
etc/style/gh-pandoc.min.css
vendored
2
etc/style/gh-pandoc.min.css
vendored
File diff suppressed because one or more lines are too long
@ -5,7 +5,7 @@ if "%PANDODC_PATH%"=="" (
|
||||
)
|
||||
|
||||
echo on
|
||||
"%PANDODC_PATH%\pandoc.exe" -o "%~dp0\README.html" --self-contained --toc --toc-depth=2 --css etc\style\gh-pandoc.min.css "%~dp0\README.md"
|
||||
"%PANDODC_PATH%\pandoc.exe" -o "%~dp0\README.html" --self-contained --toc --toc-depth=3 --css etc\style\gh-pandoc.min.css "%~dp0\README.md"
|
||||
@echo off
|
||||
|
||||
echo.
|
||||
|
||||
@ -2,4 +2,4 @@
|
||||
set -e
|
||||
cd -- "$(dirname -- "${BASH_SOURCE[0]}")"
|
||||
|
||||
pandoc -o README.html --self-contained --toc --toc-depth=2 --css etc/style/gh-pandoc.min.css README.md
|
||||
pandoc -o README.html --self-contained --toc --toc-depth=3 --css etc/style/gh-pandoc.min.css README.md
|
||||
|
||||
Loading…
Reference in New Issue
Block a user