NAME

secrypt - cryptographic library for authenticated encryption and decryption

SYNOPSIS

#include "secrypt.h"

Use these utilities for secure cryptographic operations, leveraging the Mbed TLS library (2.28.x) for implementing authenticated encryption using an Encrypt-then-MAC scheme with derived keys.

DESCRIPTION

The secrypt library offers a comprehensive suite of cryptographic functions designed to facilitate secure authenticated encryption of data buffers. It implements a robust Encrypt-then-MAC scheme to provide both confidentiality (encryption) and integrity/authenticity (message authentication code).

This implementation leverages the power of the Mbed TLS library and adheres to modern cryptographic best practices. Key security features include the use of the standard HMAC-based Key Derivation Function (HKDF, RFC 5869) to derive separate, single-use keys for encryption and authentication from a master secret. This prevents key reuse and ensures a strong separation between cryptographic operations.

For detailed, source-level documentation of each function and its parameters, see the comments in the secrypt.h header file.

Utility and Debugging Functions

print_hex(const unsigned char *data, size_t length)

Prints binary data as hexadecimal. Useful for debugging and verifying data integrity.

Returns:

This function does not return a value.
print_encrypted_data(const unsigned char *data, size_t length)

Prints encrypted data in a safe, human-readable format. Aids in verifying encryption operations.

Returns:

This function does not return a value.

Cryptographic Operations

entropy_init(mbedtls_entropy_context *entropy)

Initializes the entropy context for secure random number generation.

Returns:
- 0 on success.
- -1 on failure.

Encryption/Decryption and Hashing

crypt_and_hash_buffer(int mode, unsigned char *personalization_string, unsigned char *input_buffer, size_t *input_length, unsigned char **my_output_buffer, size_t *my_output_length, char *cipher, char *md, char *my_key)

Performs authenticated encryption or decryption on a data buffer.

Returns:
- 0 on success.
- A non-zero error code on failure.

Features

Standard-Based Key Derivation: Employs the HMAC-based Key Derivation Function (HKDF, RFC 5869) to derive strong, separate keys for encryption and authentication from a single master secret.
Key Separation: Enforces a strict separation between encryption and authentication keys, a critical best practice to prevent cryptographic interactions.
Secure IV Generation: Creates a unique and unpredictable Initialization Vector (IV) for each encryption operation using a Cryptographically Secure Pseudo-Random Number Generator (CSPRNG).
Authenticated Encryption: Provides confidentiality and integrity through a robust Encrypt-then-MAC scheme.
Timing Attack Resistance: Uses a constant-time comparison for HMAC verification during decryption to protect against timing side-channel attacks.

NOTES

Proper use of these cryptographic functions is crucial for maintaining data security. Familiarize yourself with cryptographic principles and Mbed TLS specifics to ensure the security of your data. The master key material provided should have sufficient entropy.

WARNING

Keep your Mbed TLS library and cryptographic standards updated to maintain security efficacy over time.

BUGS

Report bugs to https://github.com/nasa-jpl/ION-DTN/issues.