SOFTWARE

Python Guide

Install one wheel file and start with import strcrypt. No other packages are required.

0.3.1Updated 2026-09-27MIT · Linux x86_64 · Windows x64

Install

Python 3.14

Linux (bash)

curl -fLO https://www.cubiware.co.kr/api/download/strcrypt/0.3.1/strcrypt-0.3.1-cp314-cp314-manylinux_2_28_x86_64.whl
curl -fLO https://www.cubiware.co.kr/api/download/strcrypt/0.3.1/SHA256SUMS
sha256sum -c --ignore-missing SHA256SUMS
python3.14 -m venv .venv
. .venv/bin/activate
pip install strcrypt-0.3.1-cp314-cp314-manylinux_2_28_x86_64.whl

Windows (PowerShell)

curl.exe -fLO https://www.cubiware.co.kr/api/download/strcrypt/0.3.1/strcrypt-0.3.1-cp314-cp314-win_amd64.whl
curl.exe -fLO https://www.cubiware.co.kr/api/download/strcrypt/0.3.1/SHA256SUMS
Get-Content SHA256SUMS | ForEach-Object {
  $hash, $name = $_ -split '\s+', 2
  if (Test-Path $name) {
    if ((Get-FileHash $name -Algorithm SHA256).Hash -eq $hash) { "$($name): OK" } else { "$($name): FAILED" }
  }
}
py -3.14 -m venv .venv
.venv\Scripts\python.exe -m pip install strcrypt-0.3.1-cp314-cp314-win_amd64.whl

Python 3.9

Linux (bash)

curl -fLO https://www.cubiware.co.kr/api/download/strcrypt/0.3.1/strcrypt-0.3.1-cp39-cp39-manylinux_2_28_x86_64.whl
curl -fLO https://www.cubiware.co.kr/api/download/strcrypt/0.3.1/SHA256SUMS
sha256sum -c --ignore-missing SHA256SUMS
python3.9 -m venv .venv
. .venv/bin/activate
pip install strcrypt-0.3.1-cp39-cp39-manylinux_2_28_x86_64.whl

Windows (PowerShell)

curl.exe -fLO https://www.cubiware.co.kr/api/download/strcrypt/0.3.1/strcrypt-0.3.1-cp39-cp39-win_amd64.whl
curl.exe -fLO https://www.cubiware.co.kr/api/download/strcrypt/0.3.1/SHA256SUMS
Get-Content SHA256SUMS | ForEach-Object {
  $hash, $name = $_ -split '\s+', 2
  if (Test-Path $name) {
    if ((Get-FileHash $name -Algorithm SHA256).Hash -eq $hash) { "$($name): OK" } else { "$($name): FAILED" }
  }
}
py -3.9 -m venv .venv
.venv\Scripts\python.exe -m pip install strcrypt-0.3.1-cp39-cp39-win_amd64.whl

Wheels are available for each Python version from 3.9 to 3.14. The cp tag in the file name (cp39, cp310, cp311, cp312, cp313, cp314) is the Python version it installs on. For 3.10 to 3.13, replace cp314 and 3.14 in the example above with that version. On Windows, run .venv\Scripts\python.exe directly instead of activating the virtual environment, so the PowerShell execution policy does not get in the way.

Set up the key

Linux (bash)

(umask 077; openssl rand -base64 32 | head -c 32 > strcrypt.key)
export STRCRYPT_KEY_FILE="$PWD/strcrypt.key"

Windows (PowerShell)

$key = Join-Path $PWD 'strcrypt.key'
$bytes = [byte[]]::new(24)
[Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($bytes)
[IO.File]::WriteAllText($key, [Convert]::ToBase64String($bytes))
icacls $key /inheritance:r /grant:r "$($env:USERNAME):F"
$env:STRCRYPT_KEY_FILE = $key

Set the environment variable before the Python process starts. The key is read once, on the first encryption or decryption, so restart the process after changing it. Key rules and backup advice are in Quick start on the overview page.

Encrypt and decrypt strings

import strcrypt

token = strcrypt.encrypt("alice@example.com")
print(token)
print(strcrypt.decrypt(token))

encrypt returns a Base64 string, so you can store it directly in a text column. Encrypting the same value produces a different result every time.

Choose an algorithm

token = strcrypt.encrypt_with_algorithm("alice@example.com", "seed128gcm")
print(strcrypt.decrypt(token))

Decryption reads the algorithm from the ciphertext header, so plain decrypt works. Algorithms other than the Korean standards (such as aes256gcm) require the environment variable STRCRYPT_MODE=non-approved.

Use AAD

token = strcrypt.encrypt_with_aad("010-1234-5678", b"customer:42")
print(strcrypt.decrypt_with_aad(token, b"customer:42"))

AAD (additional authenticated data) is not encrypted but is authenticated together with the ciphertext. It is not stored in the ciphertext, so pass the same AAD again when decrypting. If you use a row identifier such as a customer ID as AAD, decryption fails when a ciphertext is copied to another row, which exposes the swap.

Batch processing

tokens = strcrypt.encrypt_batch(["alice@example.com", "bob@example.com"])
print(strcrypt.decrypt_batch(tokens))

rows = [b"alice@example.com", b"bob@example.com"]
aads = [b"id=1", b"id=2"]
encrypted = strcrypt.encrypt_batch_bytes_with_aad(rows, "aria256gcm", aads=aads)
print(strcrypt.decrypt_batch_bytes_with_aad(encrypted, aads=aads))

encrypt_batch takes a list of strings, and encrypt_batch_bytes_with_aad takes a list of bytes records with per-record AAD. The result has the same length and order as the input. For very large inputs, split the work with chunk_size and max_chunk_bytes.

Encrypt and decrypt files

strcrypt.encrypt_file("report.csv", "report.csv.enc")
strcrypt.decrypt_file("report.csv.enc", "report.dec.csv")

Files are read and written in chunks. The optional third argument selects the algorithm; without it, the default algorithm of the current mode is used. The format matches the CLI encrypt-file command, so each can decrypt files made by the other.

Handle errors

try:
    strcrypt.decrypt_with_aad(token, b"customer:43")
except ValueError as e:
    print(e)

try:
    strcrypt.decrypt_batch_bytes_with_aad(encrypted, aads=[b"id=1", b"id=9"])
except ValueError as e:
    print(e.record_index)

A wrong key, mismatched AAD, or altered ciphertext raises ValueError. encrypt_batch_bytes_with_aad and decrypt_batch_bytes_with_aad raise without partial results if any record fails, and put the failing record's position in record_index. The same two functions raise RuntimeError when the key cannot be loaded or the algorithm is not allowed in the current mode.

API reference

Function	Description
`encrypt(text) / decrypt(encrypted_base64)`	String ↔ Base64 ciphertext string
`encrypt_bytes(text) / decrypt_bytes(encrypted_data)`	String ↔ ciphertext bytes
`encrypt_with_algorithm(text, algorithm)`	Encrypt with a chosen algorithm. Decrypt with decrypt or decrypt_with_algorithm(encrypted_base64, algorithm=None)
`encrypt_with_aad(text, aad) / decrypt_with_aad(encrypted_base64, aad)`	Encrypt and decrypt with AAD
`encrypt_bytes_with_aad(data, aad) / decrypt_bytes_with_aad(encrypted_data, aad)`	Encrypt and decrypt bytes with AAD
`encrypt_batch(texts) / decrypt_batch(encrypted_list)`	Process a list of strings at once. Use the _parallel functions for large lists
`encrypt_batch_bytes_with_aad(inputs, algorithm, *, aads=None, chunk_size=None, max_chunk_bytes=None)`	Encrypt a list of bytes records with per-record AAD
`decrypt_batch_bytes_with_aad(encrypted, *, aads=None, chunk_size=None, max_chunk_bytes=None)`	Decrypt the result above into a list of bytes
`encrypt_file(input_path, output_path, algorithm=None) / decrypt_file(input_path, output_path)`	Encrypt and decrypt files in chunks. _parallel variants are also available
`search_index(value, domain)`	Search index for exact-match lookup on encrypted columns (64 hex characters). domain identifies the column (for example customers.ssn). Same value as the SQL function strcrypt_search_index
`supported_algorithms() / version()`	List of available algorithm identifiers, library version

Troubleshooting

Some messages from the library are shown in Korean even in an English locale.

Symptom	What to do
is not a supported wheel on this platform	Wheels are available for each Python version from 3.9 to 3.14 on Linux x86_64 and Windows x64. Match the wheel to your operating system and the Python version of your virtual environment.
STRCRYPT_KEY is required	Set STRCRYPT_KEY_FILE or STRCRYPT_KEY before starting the Python process.
현재 모드(korean-standard)에서 허용되지 않는 알고리즘 (algorithm not allowed in the current mode)	For algorithms other than the Korean standards, set STRCRYPT_MODE=non-approved before starting the process.