aeadencrypt

Classes

`VaultCipher`	High-Security Vault Cipher using AES-256-GCM with PBKDF2-HMAC-SHA512 key derivation.
`VaultUtils`	Utility methods for Vault operations, including key generation and legacy encryption.

class VaultCipher(key_name='GIS_KEY', key_path=None, auto_scrub_on_exit=True)

Bases: object

High-Security Vault Cipher using AES-256-GCM with PBKDF2-HMAC-SHA512 key derivation.

This class implements an industrial-grade “Vault” for GIS production teams. It uses a long-term master key (from ENV or file) to derive unique encryption keys for every individual blob or file, ensuring maximum security and full AAD support.

Summary of Methods

Method	Description
`encrypt_text`	Encrypts string/bytes into a Base64-encoded AES-256-GCM blob.
`decrypt_text`	Decrypts Base64 blobs back into original UTF-8 text.
`encrypt_file`	Encrypts a local file on disk with per-file salt/nonce.
`decrypt_file`	Decrypts an encrypted file back to its original state.
`scrub`	Manually zeroes out the master key from memory for safety.
`revive`	Reloads the master key from its original source.
`debug_status`	Prints the current internal state (isActive, key source, etc.).
`verify_master_key`	Verifies if the loaded master key is valid and secure.

USAGE EXAMPLE:

from ntsm.aeadencrypt import VaultCipher

# Initialize the vault instance
vault = VaultCipher(key_name='GIS_KEY')

# Encrypt sensitive string
encrypted = vault.encrypt_text("my secret", tags=b"doc_v1")

# Decrypt back
plain = vault.decrypt_text(encrypted, tags=b"doc_v1")

# Encrypt a shapefile or zip
vault.encrypt_file("orig.zip", "secure.dat", tags=b"backup_2025")

Initialize vault instance with a master key.

The key is loaded with the following priority:

Environment variable (recommended for production).
Local file on disk (convenient for development).

Parameters:

key_name (str) – Name of the environment variable. Defaults to 'GIS_KEY'.
key_path (Optional[str]) – Path to a file containing the Base64 master key.
auto_scrub_on_exit (bool) – If True, zeroes keys upon destruction. Defaults to True.

USAGE EXAMPLE:

# From Environment
vault = VaultCipher(key_name="MY_APP_KEY")

# From File
vault = VaultCipher(key_path="C:/keys/master.key")

Returns:: Initialized VaultCipher instance.

ALG_LENGTH = 32

FILE_SIZE_LIMIT = 536870912

KDF_ITERATIONS = 250000

NONCE_SIZE = 12

RSA_KEY_SIZE = 4096

SALT_SIZE = 16

TAG_SIZE = 16

debug_status()

Print the current internal state of the Vault instance.

Displays whether the vault is ACTIVE or SCRUBBED, the detected key source (ENV/FILE), and whether auto-scrub is enabled.

USAGE EXAMPLE:

vault.debug_status()

Returns:: None

decrypt_file(input_path, output_path, tags=None)

Decrypt an encrypted file back to its original state (Streaming).

Uses chunked processing to maintain constant memory usage. Validates integrity using the GCM authentication tag stored at the end of the file.

Parameters:

input_path (str) – Path to the encrypted file.
output_path (str) – Path where the decrypted result will be saved.
tags (Optional[bytes]) – Must match the tags used during encryption.

USAGE EXAMPLE:

vault.decrypt_file("config.dat", "config_restored.json", tags=b"v1")

Return type:: None
Returns:: None

decrypt_text(encryptedtext, tags=None)

Decrypt a Base64 blob back into original UTF-8 text.

Validates the authentication tag using the provided Associated Data (tags). If the data has been tampered with, it raises InvalidTag.

Parameters:

encryptedtext (str | bytes) – The Base64 blob to decrypt.
tags (Optional[bytes]) – Must match the tags used during encryption.

USAGE EXAMPLE:

# Decrypt matching the original tags
secret = vault.decrypt_text(blob, tags=b"project:77")

Return type:: str
Returns:: The original plaintext as a UTF-8 string.

encrypt_file(input_path, output_path, tags=None)

Encrypt a local file using AES-256-GCM authenticated encryption (Streaming).

Uses chunked processing (64 KiB) to maintain constant memory usage regardless of file size. The output file format is identical to previous non-streaming versions: [salt][nonce][ciphertext][tag].

Parameters:

input_path (str) – Path to the original unencrypted file.
output_path (str) – Path where the encrypted result will be saved.
tags (Optional[bytes]) – Associated Data for file authentication.

USAGE EXAMPLE:

vault.encrypt_file("config.json", "config.dat", tags=b"v1")

Return type:: None
Returns:: None

encrypt_text(plaintext, tags=None)

Encrypt text or bytes using AES-256-GCM.

Produces a standardized Base64 blob containing everything needed for decryption (salt, nonce) and the ciphertext with its authentication tag.

Parameters:

plaintext (str | bytes) – The message to encrypt.
tags (Optional[bytes]) – Associated Data (AAD) for authentication.

USAGE EXAMPLE:

vault = VaultCipher(key_name="GIS_KEY")
blob = vault.encrypt_text("GIS data", tags=b"project:77")

Returns:: b64( salt + nonce + ciphertext + tag ).
Return type:: str

revive()

Reload the encryption key from the original source (file or env).

Restores the ACTIVE status of a scrubbed vault by re-fetching the master key from its original source (disk or environment).

USAGE EXAMPLE:

vault.revive()

Returns:: None

scrub()

Manually zero-out the master key in memory.

Ensures that sensitive key material is removed from memory immediately rather than waiting for garbage collection. Useful in notebook environments.

USAGE EXAMPLE:

vault.scrub()
# After this, the instance can no longer encrypt/decrypt until revived.

Returns:: None

verify_master_key()

Verify if the loaded master key is valid and has sufficient length.

Checks if the internal master key is correctly set, has minimum 256-bit entropy, and hasn’t been scrubbed.

USAGE EXAMPLE:

if vault.verify_master_key():
    print("Key is secure and ready.")

Return type:: bool
Returns:: True if the key is valid, raises an exception otherwise.

class VaultUtils

Bases: object

Utility methods for Vault operations, including key generation and legacy encryption.

This class provides a collection of static methods for generating cryptographic keys, standardizing legacy encryption/decryption, and generating secure passwords.

Summary of Methods

Method	Description
`generate_key`	Generates a high-entropy 512-bit master key and saves it to a file.
`generate_pair_key`	Generates an RSA key pair and saves them as PEM-encoded files.
`encrypt_text`	Encrypts text using legacy AES-128-CBC with Zero IV and MD5 KDF.
`decrypt_text`	Decrypts text using legacy AES-128-CBC with Zero IV and MD5 KDF.
`gen_password`	Generates a random secure password with customizable length.

USAGE EXAMPLE:

from ntsm.aeadencrypt import VaultUtils

# Generate a new master key
key_path = VaultUtils.generate_key("./keys")

# Encrypt text with a legacy key
secret = "my_password"
encrypted = VaultUtils.encrypt_text("secret data", secret)

static decrypt_text(encrypted_text, secret_key)

Decrypt a Base64-encoded ciphertext using AES-128-CBC with a user-provided secret key and zero IV.

Standard legacy decryption method. Must use the same secret key used for encryption. Reverses PKCS7 padding and MD5 key derivation logic.

Parameters:

encrypted_text (str) – The Base64-encoded ciphertext to decrypt.
secret_key (str) – The key used for decryption.

Caution

SECURITY WARNING: This method uses MD5 for key derivation and a Zero IV. It is intended for legacy compatibility only and is NOT as secure as VaultCipher. Users are strongly advised to migrate to VaultCipher for modern applications. This method is scheduled to be deprecated in version 0.2.0 of the package.

USAGE EXAMPLE:

from ntsm.aeadencrypt import VaultUtils

# Decrypt text
plain = VaultUtils.decrypt_text("B64DATA...", "my_secret_key")

Return type:: str
Returns:: The decrypted plaintext string.

static encrypt_text(text_to_encrypt, secret_key)

Encrypt text using AES-128-CBC with a user-provided secret key and zero IV.

Standard legacy encryption method. If the secret key is not 16 characters long, it is hashed using MD5 to produce a 16-byte key. Uses PKCS7 padding.

Parameters:

text_to_encrypt (str) – The plaintext message to encrypt.
secret_key (str) – The key used for encryption.

Caution

SECURITY WARNING: This method uses MD5 for key derivation and a Zero IV. It is intended for legacy compatibility only and is NOT as secure as VaultCipher. Users are strongly advised to migrate to VaultCipher for modern applications. This method is scheduled to be deprecated in version 0.2.0 of the package.

USAGE EXAMPLE:

from ntsm.aeadencrypt import VaultUtils

# Encrypt text
cipher = VaultUtils.encrypt_text("Hello World", "my_secret_key")

Return type:: str
Returns:: The Base64-encoded encrypted text.

static gen_password(min_len, max_len)

Generate a custom random secure password.

Creates a random password using the characters from the password-generator library, excluding common confusing special characters.

Parameters:

min_len (int) – Minimum length of the password.
max_len (int) – Maximum length of the password.

USAGE EXAMPLE:

from ntsm.aeadencrypt import VaultUtils

# Generate a 20-25 character password
pwd = VaultUtils.gen_password(20, 25)

Return type:: str
Returns:: The generated random password.

static generate_key(output_dir)

Generate high-entropy 512-bit master key (recommended).

Creates a 64-byte random key, encodes it in Base64, and saves it to a timestamped file within the specified directory.

Parameters:: output_dir (str) – The directory where the key file will be saved.

USAGE EXAMPLE:

from ntsm.aeadencrypt import VaultUtils

# Generate key in 'secrets' folder
path = VaultUtils.generate_key("./secrets")
# result: "./secrets/82c75c65_2024-05-20.key"

Return type:: str
Returns:: The absolute path to the generated key file.

static generate_pair_key(output_dir)

Generate an RSA key pair and save as *.key files with unique ID names.

Creates a 4096-bit RSA key pair. Both private and public keys are saved in PEM format to the specified directory with unique identifiers.

Parameters:: output_dir (str) – The directory where the key pair files will be saved.

USAGE EXAMPLE:

from ntsm.aeadencrypt import VaultUtils

# Generate RSA pair
priv, pub = VaultUtils.generate_pair_key("./keys")

Return type:: tuple[str, str]
Returns:: A tuple containing (private_key_path, public_key_path).