pwcrypt
Loading...
Searching...
No Matches
Macros | Functions | Variables
pwcrypt.h File Reference

Encrypt and decrypt strings symmetrically using Argon2id key derivation + either AES-256 (GCM) or ChaCha20-Poly1305. More...

#include <stdio.h>
#include <stdint.h>
#include <stddef.h>
Include dependency graph for pwcrypt.h:

Go to the source code of this file.

Macros

#define PWCRYPT_API
 
#define PWCRYPT_VERSION   430
 
#define PWCRYPT_VERSION_STR   "4.3.0"
 
#define PWCRYPT_Z_CHUNKSIZE   (1024 * 256)
 
#define PWCRYPT_ARGON2_T_COST   4
 
#define PWCRYPT_ARGON2_M_COST   (1024 * 256)
 
#define PWCRYPT_ARGON2_PARALLELISM   2
 
#define PWCRYPT_ALGO_ID_AES256_GCM   0
 
#define PWCRYPT_ALGO_ID_CHACHA20_POLY1305   1
 
#define PWCRYPT_FILE_BUFFER_SIZE   (1024 * 256)
 
#define PWCRYPT_ERROR_INVALID_ARGS   (-1)
 
#define PWCRYPT_ERROR_OOM   1000
 
#define PWCRYPT_ERROR_PW_TOO_WEAK   2000
 
#define PWCRYPT_ERROR_ARGON2_FAILURE   3000
 
#define PWCRYPT_ERROR_ENCRYPTION_FAILURE   4000
 
#define PWCRYPT_ERROR_DECRYPTION_FAILURE   5000
 
#define PWCRYPT_ERROR_BASE64_FAILURE   6000
 
#define PWCRYPT_ERROR_COMPRESSION_FAILURE   7000
 
#define PWCRYPT_ERROR_DECOMPRESSION_FAILURE   8000
 
#define PWCRYPT_ERROR_FILE_FAILURE   9000
 
#define PWCRYPT_MIN(x, y)   (((x) < (y)) ? (x) : (y))
 
#define PWCRYPT_MAX(x, y)   (((x) > (y)) ? (x) : (y))
 
#define PWCRYPT_MAX_WIN_FILEPATH_LENGTH   (1024 * 32)
 
#define pwcrypt_fprintf   pwcrypt_fprintf_fptr
 

Functions

PWCRYPT_API unsigned char pwcrypt_is_fprintf_enabled ()
 
static int pwcrypt_printvoid (FILE *stream, const char *format,...)
 
PWCRYPT_API void pwcrypt_enable_fprintf ()
 
PWCRYPT_API void pwcrypt_disable_fprintf ()
 
PWCRYPT_API void dev_urandom (uint8_t *output_buffer, size_t output_buffer_size)
 
PWCRYPT_API void pwcrypt_get_temp_filepath (char output_buffer[256])
 
PWCRYPT_API size_t pwcrypt_get_filesize (const char *filepath)
 
PWCRYPT_API int pwcrypt_assess_password_strength (const uint8_t *password, size_t password_length)
 
PWCRYPT_API int pwcrypt_encrypt (const uint8_t *input, size_t input_length, uint32_t compress, const uint8_t *password, size_t password_length, uint32_t argon2_cost_t, uint32_t argon2_cost_m, uint32_t argon2_parallelism, uint32_t algo, uint8_t **output, size_t *output_length, uint32_t output_base64)
 
PWCRYPT_API int pwcrypt_encrypt_file (const char *input_file_path, size_t input_file_path_length, uint32_t compress, const uint8_t *password, size_t password_length, uint32_t argon2_cost_t, uint32_t argon2_cost_m, uint32_t argon2_parallelism, uint32_t algo, const char *output_file_path, size_t output_file_path_length)
 
PWCRYPT_API int pwcrypt_encrypt_file_raw (FILE *input_file, FILE *output_file, uint32_t compress, const uint8_t *password, size_t password_length, uint32_t argon2_cost_t, uint32_t argon2_cost_m, uint32_t argon2_parallelism, uint32_t algo, uint32_t close_input_file, uint32_t close_output_file)
 
PWCRYPT_API int pwcrypt_decrypt (const uint8_t *encrypted_data, size_t encrypted_data_length, const uint8_t *password, size_t password_length, uint8_t **output, size_t *output_length)
 
PWCRYPT_API int pwcrypt_decrypt_file (const char *input_file_path, size_t input_file_path_length, const uint8_t *password, size_t password_length, const char *output_file_path, size_t output_file_path_length)
 
PWCRYPT_API int pwcrypt_decrypt_file_raw (FILE *input_file, FILE *output_file, const uint8_t *password, size_t password_length, uint32_t close_input_file, uint32_t close_output_file)
 
PWCRYPT_API uint32_t pwcrypt_get_version_nr ()
 
PWCRYPT_API uint32_t pwcrypt_get_argon2_version_nr ()
 
PWCRYPT_API char * pwcrypt_get_version_nr_string ()
 
PWCRYPT_API void pwcrypt_free (void *ptr)
 
PWCRYPT_API FILE * pwcrypt_fopen (const char *filename, const char *mode)
 

Variables

static const char PWCRYPT_INVALID_ARGS_ERROR_MSG [] = "pwcrypt: Invalid arguments! Please run \"pwcrypt --help\" to find out how to use this program.\n"
 
static const uint8_t EMPTY64 [64]
 

Detailed Description

Encrypt and decrypt strings symmetrically using Argon2id key derivation + either AES-256 (GCM) or ChaCha20-Poly1305.

Author
Raphael Beck

Macro Definition Documentation

◆ PWCRYPT_ALGO_ID_AES256_GCM

#define PWCRYPT_ALGO_ID_AES256_GCM   0

Algo ID for the (default) AES256-GCM encryption algorithm.

◆ PWCRYPT_ALGO_ID_CHACHA20_POLY1305

#define PWCRYPT_ALGO_ID_CHACHA20_POLY1305   1

Algo ID for the ChaCha20-Poly1305 encryption algorithm.

◆ PWCRYPT_ARGON2_M_COST

#define PWCRYPT_ARGON2_M_COST   (1024 * 256)

Default Argon2 memory cost parameter to use for key derivation if nothing else was specified.

◆ PWCRYPT_ARGON2_PARALLELISM

#define PWCRYPT_ARGON2_PARALLELISM   2

Default Argon2 degree of parallelism parameter if nothing else was specified.

◆ PWCRYPT_ARGON2_T_COST

#define PWCRYPT_ARGON2_T_COST   4

Default Argon2 time cost parameter to use for key derivation if nothing else was specified.

◆ PWCRYPT_ERROR_ARGON2_FAILURE

#define PWCRYPT_ERROR_ARGON2_FAILURE   3000

Error code for Argon2 key derivation failures.

◆ PWCRYPT_ERROR_BASE64_FAILURE

#define PWCRYPT_ERROR_BASE64_FAILURE   6000

Base-64 encoding/decoding failure.

◆ PWCRYPT_ERROR_COMPRESSION_FAILURE

#define PWCRYPT_ERROR_COMPRESSION_FAILURE   7000

This error code is returned when encryption failed due to a failure to compress the input data (ccrush lib failure).

◆ PWCRYPT_ERROR_DECOMPRESSION_FAILURE

#define PWCRYPT_ERROR_DECOMPRESSION_FAILURE   8000

Error code for when decompressing data fails (ccrush lib failure)..

◆ PWCRYPT_ERROR_DECRYPTION_FAILURE

#define PWCRYPT_ERROR_DECRYPTION_FAILURE   5000

Error code for decryption failures.

Hint: If you're having this and you're using pwcrypt as a library, try to set a breakpoint and step through the code to see what exactly is failing

◆ PWCRYPT_ERROR_ENCRYPTION_FAILURE

#define PWCRYPT_ERROR_ENCRYPTION_FAILURE   4000

Encryption failures return this error code.

◆ PWCRYPT_ERROR_FILE_FAILURE

#define PWCRYPT_ERROR_FILE_FAILURE   9000

Error code for failures while handling files.

◆ PWCRYPT_ERROR_INVALID_ARGS

#define PWCRYPT_ERROR_INVALID_ARGS   (-1)

Error code for invalid arguments passed to a pwcrypt function.

◆ PWCRYPT_ERROR_OOM

#define PWCRYPT_ERROR_OOM   1000

Error code "out of memory", uh oh...

◆ PWCRYPT_ERROR_PW_TOO_WEAK

#define PWCRYPT_ERROR_PW_TOO_WEAK   2000

Error code for passwords that are too weak.

◆ PWCRYPT_FILE_BUFFER_SIZE

#define PWCRYPT_FILE_BUFFER_SIZE   (1024 * 256)

The size in bytes of the file's background buffer.

◆ PWCRYPT_MAX

#define PWCRYPT_MAX ( x,
y )   (((x) > (y)) ? (x) : (y))

Picks the bigger of two numbers.

◆ PWCRYPT_MAX_WIN_FILEPATH_LENGTH

#define PWCRYPT_MAX_WIN_FILEPATH_LENGTH   (1024 * 32)

Maximum file path length on NTFS.

◆ PWCRYPT_MIN

#define PWCRYPT_MIN ( x,
y )   (((x) < (y)) ? (x) : (y))

Picks the smaller of two numbers.

◆ PWCRYPT_VERSION

#define PWCRYPT_VERSION   430

Current version of the used pwcrypt library.

◆ PWCRYPT_VERSION_STR

#define PWCRYPT_VERSION_STR   "4.3.0"

Current version of the used pwcrypt library (nicely-formatted string).

◆ PWCRYPT_Z_CHUNKSIZE

#define PWCRYPT_Z_CHUNKSIZE   (1024 * 256)

Default chunksize to use for compressing and decompressing buffers.

Function Documentation

◆ dev_urandom()

PWCRYPT_API void dev_urandom ( uint8_t * output_buffer,
size_t output_buffer_size )

(Tries to) read from /dev/urandom (or Windows equivalent, yeah...) filling the given output_buffer with output_buffer_size random bytes.

Parameters
output_bufferWhere to write the random bytes into.
output_buffer_sizeHow many random bytes to write into output_buffer

◆ pwcrypt_assess_password_strength()

PWCRYPT_API int pwcrypt_assess_password_strength ( const uint8_t * password,
size_t password_length )

Checks whether a given password is strong enough or not.

Parameters
passwordPassword string to check (does not need to be NUL-terminated; only password_length characters will be checked!).
password_lengthLength of the password string.
Returns
0 if the password is OK; a non-zero error code if the password is too weak.

◆ pwcrypt_decrypt()

PWCRYPT_API int pwcrypt_decrypt ( const uint8_t * encrypted_data,
size_t encrypted_data_length,
const uint8_t * password,
size_t password_length,
uint8_t ** output,
size_t * output_length )

Decrypts a string or a byte array that was encrypted using pwcrypt_encrypt().

Parameters
encrypted_dataThe ciphertext to decrypt.
encrypted_data_lengthLength of the encrypted_data argument (string length or byte array size).
passwordThe decryption password.
password_lengthLength of the password argument.
outputPointer to the output buffer where to write the decrypted data into. This will be allocated and NUL-terminated automatically on success; if anything fails, this will be left untouched! So you only need to pwcrypt_free() this if decryption succeeds.
output_length[OPTIONAL] Where to write the output buffer length into. Pass NULL if you don't care.
Returns
0 on success; non-zero error codes if something fails.

◆ pwcrypt_decrypt_file()

PWCRYPT_API int pwcrypt_decrypt_file ( const char * input_file_path,
size_t input_file_path_length,
const uint8_t * password,
size_t password_length,
const char * output_file_path,
size_t output_file_path_length )

Decrypts a file that was encrypted using pwcrypt_encrypt_file().

Parameters
input_file_pathFull path to the file that needs to be decrypted. Must be UTF-8 encoded. Must be NUL-terminated and its strlen() must be equal to the input_file_path_length parameter.
input_file_path_lengthLength of the input_file_path string.
passwordThe decryption password.
password_lengthLength of the password argument.
output_file_pathThis is the full output file path where to write the decrypted file into.
output_file_path_lengthLength of the output_file_path string.
Returns
0 on success; non-zero error codes if something fails.

◆ pwcrypt_decrypt_file_raw()

PWCRYPT_API int pwcrypt_decrypt_file_raw ( FILE * input_file,
FILE * output_file,
const uint8_t * password,
size_t password_length,
uint32_t close_input_file,
uint32_t close_output_file )

Decrypts a file that was encrypted using pwcrypt_encrypt_file() or pwcrypt_encrypt_file_raw().

Parameters
input_fileFile to decrypt. Must not be NULL
output_fileFile handle of the output file into which to write the decrypted result. Must not be NULL
passwordThe decryption password.
password_lengthLength of the password argument.
close_input_fileShould the input file handle be fclose'd after usage? Pass 0 for "false" and anything else for "true".
close_output_fileShould the output file handle be fclose'd after usage? Pass 0 for "false" and anything else for "true".
Returns
0 on success; non-zero error codes if something fails.

◆ pwcrypt_disable_fprintf()

PWCRYPT_API void pwcrypt_disable_fprintf ( )

Disables pwcrypts' use of fprintf().

◆ pwcrypt_enable_fprintf()

PWCRYPT_API void pwcrypt_enable_fprintf ( )

Enables pwcrypts' use of fprintf().

◆ pwcrypt_encrypt()

PWCRYPT_API int pwcrypt_encrypt ( const uint8_t * input,
size_t input_length,
uint32_t compress,
const uint8_t * password,
size_t password_length,
uint32_t argon2_cost_t,
uint32_t argon2_cost_m,
uint32_t argon2_parallelism,
uint32_t algo,
uint8_t ** output,
size_t * output_length,
uint32_t output_base64 )

Encrypts an input string of data symmetrically with a password.

The password string is fed into a customizable amount of Argon2id iterations to derive a 256-bit symmetric key, with which the input will be encrypted and written into the output buffer.

Parameters
inputThe input data to encrypt.
input_lengthLength of the input data array argument.
compressShould the input data be compressed before being encrypted? Pass 0 for no compression, or a compression level from 1 to 9 to pass to the deflate algorithm (6 is a healthy default value to use for this).
passwordThe password string (ideally a UTF8-encoded byte array, but you can obviously also encrypt using a file) with which to encrypt the input argument (this will be used to derive a 256-bit symmetric encryption key (e.g. AES-256 key) using Argon2id).
password_lengthLength of the password string argument.
argon2_cost_tThe Argon2 time cost parameter (number of iterations) to use for deriving the symmetric encryption key. Pass 0 to use the default value of PWCRYPT_ARGON2_T_COST.
argon2_cost_mThe Argon2 memory cost parameter (in KiB) to use for key derivation. Pass 0 to use the default value of PWCRYPT_ARGON2_M_COST.
argon2_parallelismDegree of parallelism to use when deriving the symmetric encryption key from the password with Argon2 (number of parallel threads). Pass 0 to use the default value of PWCRYPT_ARGON2_PARALLELISM.
algoWhich encryption algo to use (see the top of the pwcrypt.h header file for more infos).
outputPointer to the output buffer where to write the encrypted ciphertext into. This will be allocated and NUL-terminated on success; if anything fails, this will be left untouched! So you only need to pwcrypt_free() it on successful encryption.
output_length[OPTIONAL] Where to write the output buffer length into. Pass NULL if you don't care.
output_base64Should the encrypted output bytes be base64-encoded for easy textual transmission (e.g. email)? If you decide to base64-encode the encrypted data buffer, please be aware that a NUL-terminator is appended at the end to allow usage as a C-string but it will not be counted in output_length. Pass 0 for raw binary output, or anything else for a human-readable, base64-encoded output string.
Returns
0 on success; non-zero error codes if something fails.

◆ pwcrypt_encrypt_file()

PWCRYPT_API int pwcrypt_encrypt_file ( const char * input_file_path,
size_t input_file_path_length,
uint32_t compress,
const uint8_t * password,
size_t password_length,
uint32_t argon2_cost_t,
uint32_t argon2_cost_m,
uint32_t argon2_parallelism,
uint32_t algo,
const char * output_file_path,
size_t output_file_path_length )

Encrypts a file symmetrically with a password.

The password string is fed into a customizable amount of Argon2id iterations to derive a 256-bit symmetric key, with which the input will be encrypted and written into the output buffer.

Parameters
input_file_pathFull path to the file that needs to be encrypted. Must be UTF-8 encoded. Must be NUL-terminated and its strlen() must be equal to the input_file_path_length parameter.
input_file_path_lengthLength of the input_file_path string.
compressShould the input data be compressed before being encrypted? Pass 0 for no compression, or a compression level from 1 to 9 to pass to the deflate algorithm (6 is a healthy default value to use for this).
passwordThe password string (ideally a UTF8-encoded byte array, but you can obviously also encrypt using a file) with which to encrypt the input argument (this will be used to derive a 256-bit symmetric encryption key (e.g. AES-256 key) using Argon2id).
password_lengthLength of the password string argument.
argon2_cost_tThe Argon2 time cost parameter (number of iterations) to use for deriving the symmetric encryption key. Pass 0 to use the default value of PWCRYPT_ARGON2_T_COST.
argon2_cost_mThe Argon2 memory cost parameter (in KiB) to use for key derivation. Pass 0 to use the default value of PWCRYPT_ARGON2_M_COST.
argon2_parallelismDegree of parallelism to use when deriving the symmetric encryption key from the password with Argon2 (number of parallel threads). Pass 0 to use the default value of PWCRYPT_ARGON2_PARALLELISM.
algoWhich encryption algo to use (see the top of the pwcrypt.h header file for more infos).
output_file_pathThis is the full output file path where to write the encrypted file into.
output_file_path_lengthLength of the output_file_path string.
Returns
0 on success; non-zero error codes if something fails.

◆ pwcrypt_encrypt_file_raw()

PWCRYPT_API int pwcrypt_encrypt_file_raw ( FILE * input_file,
FILE * output_file,
uint32_t compress,
const uint8_t * password,
size_t password_length,
uint32_t argon2_cost_t,
uint32_t argon2_cost_m,
uint32_t argon2_parallelism,
uint32_t algo,
uint32_t close_input_file,
uint32_t close_output_file )

Encrypts a file symmetrically with a password.

The password string is fed into a customizable amount of Argon2id iterations to derive a 256-bit symmetric key, with which the input will be encrypted and written into the output buffer.

Parameters
input_fileFile that needs to be encrypted. Must not be NULL
output_fileFile handle of the output file into which the encryption result should be written into. Must not be NULL
compressShould the input data be compressed before being encrypted? Pass 0 for no compression, or a compression level from 1 to 9 to pass to the deflate algorithm (6 is a healthy default value to use for this).
passwordThe password string (ideally a UTF8-encoded byte array, but you can obviously also encrypt using a file) with which to encrypt the input argument (this will be used to derive a 256-bit symmetric encryption key (e.g. AES-256 key) using Argon2id).
password_lengthLength of the password string argument.
argon2_cost_tThe Argon2 time cost parameter (number of iterations) to use for deriving the symmetric encryption key. Pass 0 to use the default value of PWCRYPT_ARGON2_T_COST.
argon2_cost_mThe Argon2 memory cost parameter (in KiB) to use for key derivation. Pass 0 to use the default value of PWCRYPT_ARGON2_M_COST.
argon2_parallelismDegree of parallelism to use when deriving the symmetric encryption key from the password with Argon2 (number of parallel threads). Pass 0 to use the default value of PWCRYPT_ARGON2_PARALLELISM.
algoWhich encryption algo to use (see the top of the pwcrypt.h header file for more infos).
close_input_fileShould the input file handle be fclose'd after usage? Pass 0 for "false" and anything else for "true".
close_output_fileShould the output file handle be fclose'd after usage? Pass 0 for "false" and anything else for "true".
Returns
0 on success; non-zero error codes if something fails.

◆ pwcrypt_fopen()

PWCRYPT_API FILE * pwcrypt_fopen ( const char * filename,
const char * mode )

Wrapper around fopen()

Parameters
filenameFile path.
modeFile open mode ("r", "w", "rb", etc...)
Returns
FILE* or null

◆ pwcrypt_free()

PWCRYPT_API void pwcrypt_free ( void * ptr)

Wrapper around free() (mainly useful for C# interop).

Parameters
ptrThe memory to free (typically the output of one of the two main pwcrypt functions).

◆ pwcrypt_get_argon2_version_nr()

PWCRYPT_API uint32_t pwcrypt_get_argon2_version_nr ( )

Gets the current Argon2 version number used by pwcrypt (numeric).

Returns
Argon2 version number (32-bit unsigned integer).

◆ pwcrypt_get_filesize()

PWCRYPT_API size_t pwcrypt_get_filesize ( const char * filepath)

Retrieve the size of a file.

Parameters
filepathThe file path.
Returns
The file size (in bytes) if retrieval succeeded; 0 if getting the file size failed for some reason.

◆ pwcrypt_get_temp_filepath()

PWCRYPT_API void pwcrypt_get_temp_filepath ( char output_buffer[256])

Gets a completely random, temporary file name (usually located within /var/tmp).

Parameters
output_bufferWhere to write the temporary file path into (must be a writeable char buffer of at least 256B).

◆ pwcrypt_get_version_nr()

PWCRYPT_API uint32_t pwcrypt_get_version_nr ( )

Gets the current pwcrypt version number (numeric).

Returns
Pwcrypt version number (32-bit unsigned integer).

◆ pwcrypt_get_version_nr_string()

PWCRYPT_API char * pwcrypt_get_version_nr_string ( )

Gets the current pwcrypt version number as a nicely-formatted, human-readable string.

Returns
Pwcrypt version number (MAJOR.MINOR.PATCH)

◆ pwcrypt_is_fprintf_enabled()

PWCRYPT_API unsigned char pwcrypt_is_fprintf_enabled ( )

Checks whether pwcrypt fprintf is enabled (whether errors are fprintfed into stderr).

Returns
Whether errors are fprintfed into stderr or not.

◆ pwcrypt_printvoid()

static int pwcrypt_printvoid ( FILE * stream,
const char * format,
... )
inlinestatic

Like fprintf() except it doesn't do anything. Like printing into /dev/null :D lots of fun!

Parameters
stream[IGNORED]
format[IGNORED]
...[IGNORED]
Returns
0

Variable Documentation

◆ EMPTY64

const uint8_t EMPTY64[64]
static
Initial value:
= {
0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00,
}

An array of 64 bytes of value 0x00.

◆ PWCRYPT_INVALID_ARGS_ERROR_MSG

const char PWCRYPT_INVALID_ARGS_ERROR_MSG[] = "pwcrypt: Invalid arguments! Please run \"pwcrypt --help\" to find out how to use this program.\n"
static

Error message for invalid CLI arguments.