SOFTWARE

Python 사용법

wheel 파일 하나를 설치하면 import strcrypt로 불러와 쓸 수 있습니다. 다른 패키지는 필요하지 않습니다.

0.3.1갱신 2026-09-27MIT · Linux x86_64 · Windows x64

설치

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

Python 3.9~3.14 각 버전용 wheel을 제공합니다. 파일명의 cp 태그(cp39·cp310·cp311·cp312·cp313·cp314)가 설치할 Python 버전입니다. 3.10~3.13은 위 예제의 cp314와 3.14를 해당 버전으로 바꿉니다. Windows에서는 PowerShell 실행 정책에 막히지 않도록 가상환경을 활성화하지 않고 .venv\Scripts\python.exe로 실행합니다.

키 설정

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

환경 변수는 Python 프로세스를 시작하기 전에 설정합니다. 키는 처음 암복호화할 때 한 번 읽으므로 키를 바꾸면 프로세스를 다시 시작합니다. 키 규칙과 백업 안내는 개요의 빠른 시작에 있습니다.

문자열 암복호화

import strcrypt

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

encrypt는 Base64 문자열을 돌려주므로 DB 문자열 컬럼에 그대로 저장할 수 있습니다. 같은 값을 암호화해도 결과는 매번 다릅니다.

알고리즘 지정

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

복호화할 때는 암호문 헤더에서 알고리즘을 읽으므로 decrypt를 그대로 씁니다. 국내 표준 외 알고리즘(aes256gcm 등)은 환경 변수 STRCRYPT_MODE=non-approved를 설정해야 쓸 수 있습니다.

AAD 지정

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

AAD(추가 인증 데이터)는 암호화하지 않고 암호문과 함께 인증만 하는 값입니다. 암호문에 저장되지 않으므로 복호화할 때 같은 AAD를 다시 넘겨야 합니다. 고객 ID 같은 행 식별자를 AAD로 쓰면 암호문을 다른 행에 옮겨 붙였을 때 복호화가 실패해 바꿔치기를 알 수 있습니다.

배치 처리

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는 문자열 목록을, encrypt_batch_bytes_with_aad는 bytes 레코드 목록을 레코드별 AAD와 함께 처리합니다. 결과 목록은 길이와 순서가 입력과 같습니다. 레코드가 아주 많으면 chunk_size와 max_chunk_bytes로 한 번에 처리할 양을 나눕니다.

파일 암복호화

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

파일을 일정 크기씩 나눠 읽고 씁니다. 세 번째 인자로 알고리즘을 지정할 수 있고, 생략하면 현재 모드의 기본 알고리즘을 씁니다. CLI의 encrypt-file과 형식이 같아 서로의 파일을 복호화할 수 있습니다.

오류 처리

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)

키가 다르거나 AAD가 맞지 않거나 암호문이 바뀌면 ValueError가 납니다. encrypt_batch_bytes_with_aad와 decrypt_batch_bytes_with_aad는 레코드 하나라도 실패하면 결과 없이 예외를 내고, 실패한 레코드 위치를 record_index에 담습니다. 두 함수에서 키를 읽지 못하거나 모드가 허용하지 않는 알고리즘을 지정하면 RuntimeError가 납니다.

API 레퍼런스

함수	설명
`encrypt(text) / decrypt(encrypted_base64)`	문자열 ↔ Base64 암호문 문자열
`encrypt_bytes(text) / decrypt_bytes(encrypted_data)`	문자열 ↔ 암호문 bytes
`encrypt_with_algorithm(text, algorithm)`	알고리즘을 지정해 암호화. 복호화는 decrypt 또는 decrypt_with_algorithm(encrypted_base64, algorithm=None)
`encrypt_with_aad(text, aad) / decrypt_with_aad(encrypted_base64, aad)`	AAD와 함께 암복호화
`encrypt_bytes_with_aad(data, aad) / decrypt_bytes_with_aad(encrypted_data, aad)`	bytes 데이터를 AAD와 함께 암복호화
`encrypt_batch(texts) / decrypt_batch(encrypted_list)`	문자열 목록을 한 번에 처리. 목록이 크면 _parallel 함수로 병렬 처리
`encrypt_batch_bytes_with_aad(inputs, algorithm, *, aads=None, chunk_size=None, max_chunk_bytes=None)`	bytes 레코드 목록을 레코드별 AAD와 함께 암호화
`decrypt_batch_bytes_with_aad(encrypted, *, aads=None, chunk_size=None, max_chunk_bytes=None)`	위 결과를 복호화해 bytes 목록으로 반환
`encrypt_file(input_path, output_path, algorithm=None) / decrypt_file(input_path, output_path)`	파일을 일정 크기씩 나눠 읽으면서 암복호화. _parallel 함수도 있음
`search_index(value, domain)`	암호화한 열의 같은 값 검색용 인덱스(16진 64자). domain은 열을 구분하는 문자열(예: customers.ssn). SQL 함수 strcrypt_search_index와 같은 값
`supported_algorithms() / version()`	사용 가능한 알고리즘 식별자 목록, 라이브러리 버전

문제 해결

메시지	조치
is not a supported wheel on this platform	Python 3.9~3.14 각 버전용 Linux x86_64·Windows x64 wheel을 제공합니다. Python 버전과 운영체제에 맞는 wheel을 같은 Python 버전의 가상환경에 설치합니다.
STRCRYPT_KEY 환경 변수가 필요합니다	Python 프로세스를 시작하기 전에 STRCRYPT_KEY_FILE 또는 STRCRYPT_KEY를 설정합니다.
현재 모드(korean-standard)에서 허용되지 않는 알고리즘	국내 표준 외 알고리즘은 STRCRYPT_MODE=non-approved를 설정하고 프로세스를 시작합니다.