const_stringClass

Template class for storing and managing an encrypted constant string. More...

Public Functions

Type	Name
constexpr	const_string (const char32_t(&str)[N]) noexcept
const const_array< char32_t, N > *	raw_data () const noexcept
size_t	get_hash () const
void	initialize () const

Private Properties

Type	Name
const_array< char32_t, N >	data_

Detailed Description

The const_string class template provides functionality to store a string of type char32_t in an encrypted form using a specified key and a unique identifier N . The encryption is applied either at compile time or runtime, depending on how the string is constructed.

The class allows the string to be securely stored and later decrypted when needed. It also supports conversion to various string formats, such as std::string , std::wstring , and std::u32string , which makes it versatile in handling different types of text data in a secure way.

Template Parameters:

Key : The encryption key used for encoding and decoding the string.
Hash : A compile-time constant representing the hash of the string, used for integrity checks or identification.
N : The size of the string (number of characters in the string).

Example Usage:

#include <antispy/libantispy.h>

int main() {
   constexpr auto encrypted_str = libantispy::const_string<1234, 5678, 14>(U"SensitiveData");
   std::string decrypted_str = encrypted_str;  // Automatically decrypts and converts to std::string
}

Template Parameters

Key: The encryption key.
Hash: The hash of the string.
N: The length of the string.

Public Functions

constexpr const_string (const char32_t(&str)[N]) noexcept

Constructs a const_string object from a UTF-32 source string with compile-time encryption.

Definition

constexpr libantispy::const_string< Key, Hash, N >::const_string

Detailed Description

The const_string constructor is designed to securely store a string of UTF-32 characters by encrypting the entire string at compile time using a specified encryption key. The encrypted string is stored in a const_array<char32_t, N> , which ensures the data remains immutable and secure once the object is created.

Detailed Description:

Encryption Process : The constructor uses a compile-time encryption technique to transform the input string str into an encrypted form. This transformation is carried out by the detail::string::encode function, which takes each character in the string and applies an encryption algorithm that incorporates the specified Key and the character's index position within the string. The result is a securely encrypted string stored as a const_array<char32_t, N> , an immutable array optimized for storing constant data.
Compile-Time Security : The encryption is performed entirely at compile time, ensuring that the original plaintext string is never exposed in the compiled binary. This mechanism is particularly important in security-sensitive applications where string literals might contain confidential information, such as cryptographic keys, passwords, or other sensitive data.
Performance Considerations : By encrypting the string at compile time, the constructor eliminates the need for runtime encryption, which not only improves performance but also enhances security by reducing the attack surface. The encrypted string is ready to use as soon as the program starts, with no additional processing required.
Memory Layout Randomization : The layout of the const_string object is randomized using ANTISPY_RANDOM_LAYOUT_START and ANTISPY_RANDOM_LAYOUT_END directives. These macros help protect against memory-based attacks by making it harder to predict the memory layout of the object, further securing the stored data.

Template Parameters

Key: The encryption key used to encrypt each character in the string. This key is a compile-time constant and ensures that the same key is consistently applied across the entire string.
Hash: A compile-time constant that represents a hash of the string, used for identification or integrity checks. This value is calculated based on the original string before encryption.
N: The size of the string, representing the number of characters in the string, including the null-terminator if present. The size is a template parameter and is determined at compile time.

Parameters

str: The source string to be encrypted, passed as a reference to a constant array of UTF-32 characters with a length of N . This string should be a null-terminated array, and it represents the plaintext data that needs to be securely stored within the const_string object.

Example Usage:

#include <antispy/libantispy.h>

int main() {
   constexpr auto my_encrypted_string = libantispy::const_string<0xABC123, 0xDEADBEEF, 5>(U"test");
}

In this example, the string "test" is encrypted at compile time using the key 0xABC123 and stored within a const_string object. The Hash parameter is set to 0xDEADBEEF , and the string length N is 5, accounting for the null terminator.

Notes:

The Key parameter must be carefully chosen to ensure secure encryption. A poorly chosen key might weaken the encryption, making it easier for attackers to decipher the string.
The encrypted data is immutable, which means it cannot be modified after the const_string object is created. This immutability is crucial for maintaining the integrity and security of the stored data.

const const_array< char32_t, N > * raw_data () const noexcept

Retrieves a pointer to the raw encrypted data stored within the const_string object.

Definition

const const_array< char32_t, N > * libantispy::const_string< Key, Hash, N >::raw_data

Detailed Description

This function returns a pointer to the internal const_array that holds the encrypted UTF-32 string data. The data is stored in a const_array<char32_t, N> structure, which maintains the integrity of the encrypted string while ensuring that the original content remains secure and unaltered.

Detailed Description:

Purpose :
- The raw_data() function is designed to provide access to the internal storage of the const_string object, specifically the encrypted data. This function is particularly useful in scenarios where low-level access to the encrypted content is required, such as for debugging, testing, or further cryptographic processing.
Return Type :
- The function returns a const pointer to a const_array<char32_t, N> object, ensuring that the data cannot be modified through this pointer. The use of const guarantees that the raw data is accessed in a read-only manner, preserving the integrity of the encrypted string.
Encryption Context :
- The data returned by this function is still encrypted, as the const_string class is designed to protect sensitive string content. Any operations on this raw data should take into account that it is not in plain text.
Security Considerations :
- The function provides direct access to the encrypted data, which should be handled with care to avoid unintended exposure or misuse. Since the data is encrypted, it is not directly human-readable, and further decryption steps would be necessary to interpret its contents.
Performance :
- The function is marked as noexcept , indicating that it is guaranteed not to throw exceptions. This makes it suitable for performance-critical applications where exception safety is required.

Example Usage:

#include <antispy/libantispy.h>

int main() {
   constexpr auto my_encrypted_u32string = libantispy::const_string<0xABC123, 0xDEADBEEF, 5>(U"test");
   const auto* raw_data_ptr = my_encrypted_u32string.raw_data();
}

In this example, the raw_data() function is used to retrieve a pointer to the raw encrypted data within the my_encrypted_u32string object. This pointer can be used for further analysis or processing of the encrypted data.

Returns

A const pointer to a const_array<char32_t, N> object containing the encrypted string data.

The data returned by this function is encrypted and read-only. To obtain the original plaintext string, decryption must be performed using the appropriate methods provided by the const_string class.

size_t get_hash () const

Retrieves the precomputed hash value associated with the const_string object.

Definition

size_t libantispy::const_string< Key, Hash, N >::get_hash

Detailed Description

This function returns the hash value that was calculated at compile-time and associated with the const_string instance. The hash serves as a unique identifier for the string's content, allowing for efficient comparisons, integrity checks, and other operations where a quick validation of the string's data is necessary.

Detailed Description:

Purpose :
- The get_hash() function is designed to provide a way to retrieve the precomputed hash value of the const_string . This hash is a compile-time constant, ensuring that it is always consistent and can be used to verify the identity or integrity of the string without needing to access or decrypt the actual string data.
Hash Value :
- The Hash value represents a unique fingerprint of the string's content, generated using a hashing algorithm (such as FNV-1a) at compile-time. It is a key component in ensuring that the const_string maintains a high level of security and efficiency in operations like comparisons.
Return Type :
- The function returns a size_t value, which is the type used for the hash. This type ensures that the hash value is large enough to accommodate the range of possible hash values, providing good collision resistance.
Performance :
- The function is marked as ANTISPY_NOINLINE , indicating that it is not inlined by the compiler. This may be done to avoid potential issues with instruction cache usage or to improve binary size in certain contexts. Despite this, retrieving the hash value is a constant-time operation with minimal overhead.
Security Considerations :
- Since the hash is a precomputed value, it does not expose any sensitive information directly. However, it serves as a reliable method for quickly checking if two const_string objects contain the same content without needing to decrypt or compare the full strings.

Example Usage:

#include <antispy/libantispy.h>

int main() {
   constexpr auto my_encrypted_string = libantispy::const_string<0xABC123, 0xDEADBEEF, 5>(U"test");
   size_t hash_value = my_encrypted_string.get_hash();
}

In this example, the get_hash() function is used to retrieve the hash value associated with the my_encrypted_string object. This hash value can then be used in comparisons or as a quick check to validate the content of the string.

Returns

The precomputed size_t hash value associated with the const_string object.

The hash value is precomputed and constant, meaning it does not change during the lifetime of the const_string object. This ensures consistent behavior across different instances of the same string.

void initialize () const

Initializes the const_string object by invoking the initialize method on the stored encrypted data.

Definition

void libantispy::const_string< Key, Hash, N >::initialize

Detailed Description

The initialize() function is designed to trigger any necessary initialization routines for the encrypted data stored within the const_string object. This is particularly useful in contexts where additional setup or preparation of the encrypted string's internal state is required before it can be used or accessed.

Detailed Description:

Purpose :
- The primary purpose of this function is to call the initialize() method on the data_ member, which represents the encrypted array of characters stored in the const_string object. This method may perform various internal tasks such as setting up memory, ensuring correct alignment, or preparing the data for decryption.
Behavior :
- When invoked, the initialize() function will directly call data_.initialize() , which in turn executes any initialization logic defined within the const_array class (or equivalent). The function is marked as const , indicating that it does not modify the visible state of the const_string object from the perspective of the caller.
Optimization Considerations :
- The function is marked with the ANTISPY_OPTNONE attribute, suggesting that the compiler should avoid applying certain optimizations to this function. This might be necessary to ensure that the initialization process is executed as intended, without being skipped or altered by aggressive optimizations that could interfere with the correct setup of the encrypted data.
Use Case :
- The initialize() function is typically used in scenarios where the encrypted data requires explicit initialization before any operations can be performed on it. This could be important in low-level security routines, where precise control over the data's state and memory layout is crucial.
Const-Correctness :
- Despite being a const function, initialize() might modify the internal state of the data_ member (if data_ itself is mutable or if initialize() modifies internal aspects that don't affect the external behavior). This ensures that the function can be safely called on a const instance of const_string without violating const-correctness.

Example Usage:

#include <antispy/libantispy.h>

int main() {
   constexpr auto my_encrypted_string = libantispy::const_string<0xABC123, 0xDEADBEEF, 5>(U"test");
   my_encrypted_string.initialize();
}

In this example, the initialize() function is called on an instance of const_string , ensuring that the internal encrypted data is fully initialized and ready for use.

This function is part of the internal mechanisms of the const_string class and is primarily intended for use in scenarios where low-level initialization control is required.

Private Properties

const_array< char32_t, N > data_

Stores the encrypted string data in a constant array.

Definition

const_array<char32_t, N> libantispy::const_string< Key, Hash, N >::data_

Detailed Description

The data_ member variable holds the encrypted version of the string within the const_string object. It is a constant array ( const_array ) of char32_t elements, with the size determined by the template parameter N .

Detailed Description:

Type :
- const_array<char32_t, N> : This is a custom type that likely represents an array of char32_t elements. It is designed to store data securely, with N representing the number of characters in the string.
Purpose :
- The data_ member is used to securely store the encrypted version of the string provided to the const_string object.
- The encryption is performed during the construction of the const_string object, using the encryption key ( Key ) and other parameters.
Initialization :
- The data_ array is initialized at the time of the const_string object's construction.
- The initialization is done through a call to detail::string::encode , which encrypts the original string and stores the result in data_ .
Access :
- The data_ array is not intended to be accessed directly by external code. Instead, it is used internally within the const_string class.
- Access to the encrypted data is provided through various member functions, such as raw_data() , which returns a pointer to data_ .
- The decryption of data_ is handled internally when the const_string is converted back to a regular string type, such as std::string , std::wstring , or std::u32string .
Memory and Security Considerations :
- The data_ array is designed to store the encrypted data in a way that enhances security, preventing unauthorized access or tampering.
- As a const_array , the data_ array is immutable, meaning its content cannot be modified after initialization. This immutability is important for maintaining the integrity and security of the encrypted string.
Role in Encryption :
- data_ plays a crucial role in the const_string class by storing the encrypted version of the string.
- The encryption process ensures that even if the memory where data_ resides is inspected, the original string cannot be easily extracted without the correct decryption key.

Example Usage in Context:

#include <antispy/libantispy.h>

int main() {
   constexpr auto my_const_string = libantispy::const_string<0xABC123, 0xDEADBEEF, 5>(U"Hello");
   auto raw_encrypted_data = my_const_string.raw_data();
}

In this example, my_const_string holds the encrypted version of "Hello", stored in data_ . The raw_data() function provides access to this encrypted data, though typically for internal use.

This member is part of the internal implementation of the const_string class and is crucial for maintaining the security of stored string data.