Module utils

Expand description

§Cryptographic Utilities

This module provides various utility functions for cryptographic operations, including secure memory management, constant-time comparisons, and encoding/decoding functions. These utilities are designed to help implement cryptographic protocols securely and efficiently.

§Security Considerations

Many functions in this module are specifically designed to prevent side-channel attacks and other security vulnerabilities.
The memory management functions help prevent sensitive data from being leaked or swapped to disk.
Always use these utilities when handling sensitive cryptographic material.

§Key Features

Secure Memory Management: Functions for securely allocating, protecting, and clearing memory containing sensitive data.
Constant-Time Operations: Functions for comparing data in constant time to prevent timing attacks.
Encoding/Decoding: Functions for converting between binary data and hexadecimal or Base64 representations.
Arithmetic Operations: Functions for performing arithmetic on big-endian encoded numbers, useful for nonce management.

§Example

use libsodium_rs as sodium;
use sodium::utils;
use sodium::ensure_init;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    ensure_init()?;

    // Secure memory operations
    let mut sensitive_data = [0x01, 0x02, 0x03, 0x04];

    // Lock memory to prevent it from being swapped to disk
    utils::mlock(&mut sensitive_data).expect("Failed to lock memory");

    // Use the sensitive data...

    // Securely zero the memory when done
    utils::memzero(&mut sensitive_data);
    assert_eq!(sensitive_data, [0, 0, 0, 0]);

    // Unlock the memory
    utils::munlock(&mut sensitive_data).expect("Failed to unlock memory");

    // Constant-time comparison
    let tag1 = [0x01, 0x02, 0x03, 0x04];
    let tag2 = [0x01, 0x02, 0x03, 0x04];
    assert!(utils::memcmp(&tag1, &tag2));

    // Encoding/decoding
    let binary = [0xDE, 0xAD, 0xBE, 0xEF];
    let hex = utils::bin2hex(&binary);
    assert_eq!(hex, "deadbeef");

    Ok(())
}

Re-exports§

pub use vec_utils::secure_vec;
pub use vec_utils::SecureVec;

Modules§

vec_utils: Secure Vector Utilities Module

Constants§

BASE64_VARIANT_ORIGINAL: Base64 encoding variant: original (standard) Base64 encoding
BASE64_VARIANT_ORIGINAL_NO_PADDING: Base64 encoding variant: original (standard) Base64 encoding without padding
BASE64_VARIANT_URLSAFE: Base64 encoding variant: URL-safe Base64 encoding
BASE64_VARIANT_URLSAFE_NO_PADDING: Base64 encoding variant: URL-safe Base64 encoding without padding

Functions§

add_be: Add two numbers stored as big-endian bytes
allocarray: Allocate an array of elements with secure memory
base64_encoded_len: Calculate the length of a Base64 string needed to encode binary data
base642bin: Convert a Base64 string to binary data
bin2base64: Convert binary data to a Base64 string
bin2hex: Convert binary data to a hexadecimal string
compare: Compare two byte arrays in lexicographical order
free^⚠: Free memory allocated by sodium_malloc or sodium_allocarray
hex2bin: Convert a hexadecimal string to binary data
hex2bin_ignore: Convert a hexadecimal string to binary data, ignoring specified characters
hex_encoded_len: Calculate the length of a hexadecimal string needed to encode binary data
increment_be: Increment a number (usually a nonce) stored as big-endian bytes
is_zero: Check if a byte array is all zeros
malloc: Secure memory allocation
memcmp: Compare two byte slices in constant time
memzero: Zero a byte slice in a way that won’t be optimized out
mlock: Lock memory pages containing this slice, preventing them from being swapped to disk
mprotect_noaccess^⚠: Make a region of memory inaccessible
mprotect_readonly^⚠: Make a region of memory read-only
mprotect_readwrite^⚠: Make a region of memory readable and writable
munlock: Unlock previously locked memory pages
stackzero: Zero a region of the stack in a way that won’t be optimized out
sub_be: Subtract one number from another, both stored as big-endian bytes

Module utilsCopy item path