SOFTWARE
CLI 사용법
strcrypt 실행 파일 하나로 문자열, 파일, 레코드 목록을 암복호화합니다. 추가로 설치할 라이브러리는 없습니다.
설치
Linux (bash)
mkdir -p ~/strcrypt && cd ~/strcrypt
curl -fLO https://www.cubiware.co.kr/api/download/strcrypt/0.3.1/strcrypt
curl -fLO https://www.cubiware.co.kr/api/download/strcrypt/0.3.1/strcrypt.hmac
curl -fLO https://www.cubiware.co.kr/api/download/strcrypt/0.3.1/SHA256SUMS
sha256sum -c --ignore-missing SHA256SUMS
chmod +x strcrypt
export PATH="$HOME/strcrypt:$PATH"
strcrypt --versionWindows (PowerShell)
New-Item -ItemType Directory -Force $HOME\strcrypt | Out-Null
cd $HOME\strcrypt
curl.exe -fLO https://www.cubiware.co.kr/api/download/strcrypt/0.3.1/strcrypt.exe
curl.exe -fLO https://www.cubiware.co.kr/api/download/strcrypt/0.3.1/strcrypt.exe.hmac
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" }
}
}
$env:Path = "$HOME\strcrypt;$env:Path"
strcrypt --version strcrypt.hmac(Windows는 strcrypt.exe.hmac)은 실행 파일과 같은 디렉토리에 둡니다. 실행 파일을 다른 곳으로 옮길 때도 함께 옮깁니다.
아래 예제는 bash 기준이며, 명령과 옵션은 Windows에서도 같습니다.
키 설정
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키 규칙과 백업 안내는 개요의 빠른 시작에 있습니다.
문자열 암복호화
strcrypt encrypt -c "alice@example.com"
CT=$(strcrypt encrypt -c "alice@example.com" | awk '$1 == "Base64:" {print $2}')
strcrypt decrypt -c "$CT"encrypt 출력 예 (암호문은 실행할 때마다 달라집니다)
알고리즘: ARIA-256-GCM
평문: alice@example.com
암호문 크기: 46바이트 (헤더 1 + nonce 12 + 암호화 데이터 17 + 태그 16)
Base64: AhKjxhJpz8uPwj8Rbq849CywCxDUNHkKfaBt8FWPdv3LqtQwG/lebCDZ7wOktw==| 옵션 | 동작 |
|---|---|
-c | 화면에만 출력하고 파일로 저장하지 않습니다. |
-q | 파일에만 저장하고 화면에는 출력하지 않습니다. |
-o <경로> | 결과 파일 경로를 지정합니다. 기본값은 ./strcrypt_enc.bin, ./strcrypt_dec.txt입니다. |
파일 암복호화
strcrypt encrypt-file -i report.csv -o report.csv.enc
strcrypt decrypt-file -i report.csv.enc -o report.dec.csv
strcrypt migrate-file -i report.csv.enc -o report.seed.enc -t seed128gcm
큰 파일도 한 번에 메모리에 올리지 않고 일정 크기씩 나눠 읽으면서 처리합니다. migrate-file은 복호화한 뒤 -t로 지정한 알고리즘으로 다시 암호화해 새 파일로 씁니다.
배치 처리
DB에서 내보낸 값 목록처럼 레코드가 많을 때 씁니다. 한 줄이 레코드 하나이며 값은 Base64로 적습니다.
값을 줄바꿈 없이 인코딩하도록 base64 -w0을 씁니다. 결과도 입력 순서대로 한 줄씩 나옵니다.
printf '%s\n' "$(printf 'alice@example.com' | base64 -w0)" "$(printf 'bob@example.com' | base64 -w0)" > rows.b64
strcrypt encrypt-batch -i rows.b64 -o rows.enc
strcrypt decrypt-batch -i rows.enc | while read -r line; do printf '%s' "$line" | base64 -d; echo; done레코드별 AAD 지정
AAD(추가 인증 데이터)는 암호화하지 않고 암호문과 함께 인증만 하는 값입니다. 행 ID를 AAD로 쓰면 다른 행의 암호문을 옮겨 붙였을 때 복호화가 실패합니다.
--format tsv에서는 데이터와 AAD를 탭으로 구분하고, 결과의 두 번째 열에 AAD가 그대로 남습니다.
printf '%s\t%s\n' "$(printf 'alice@example.com' | base64 -w0)" "$(printf 'id=1' | base64 -w0)" > rows.tsv
strcrypt encrypt-batch --format tsv -i rows.tsv -o rows_aad.enc
strcrypt decrypt-batch --format tsv -i rows_aad.enc | cut -f1 | base64 -d; echo| 옵션 | 동작 |
|---|---|
--format b64|tsv | b64는 한 줄에 Base64 값 하나, tsv는 데이터 Base64와 AAD Base64를 탭으로 구분합니다. 기본값 b64. |
-i, -o | 입력 파일과 출력 파일. 생략하면 표준 입력과 표준 출력을 씁니다. |
--chunk-size | 한 번에 처리하는 최대 레코드 수. 기본값 500. |
--max-chunk-bytes | 한 번에 처리하는 입력 바이트 합의 상한. 기본값 104857600. |
--threads | 병렬 스레드 수. 생략하면 RAYON_NUM_THREADS, 그것도 없으면 논리 CPU 수. 사용 가능한 CPU 수보다 크면 CPU 수로 줄입니다. |
오류가 나면 첫 오류에서 멈춥니다. -o 파일은 모든 레코드가 성공했을 때만 새 결과로 바뀝니다.
| 종료 코드 | 의미 |
|---|---|
0 | 성공 |
1 | 레코드 데이터 오류(Base64 형식, 필드 수, 인증 실패 등). 메시지에 줄 번호가 나옵니다. |
2 | 옵션이나 값의 사용법 오류 |
3 | 설정 오류(키를 읽지 못함, 현재 모드가 허용하지 않는 알고리즘) |
4 | 입출력이나 프로세스 오류 |
알고리즘과 모드 지정
strcrypt info
strcrypt -a seed128gcm encrypt -c "alice@example.com"
strcrypt --mode non-approved -a aes256gcm encrypt -c "alice@example.com" -a는 암호화 알고리즘을 고릅니다. 기본 모드에서는 aria256gcm, seed128gcm, lea128gcm만 쓸 수 있고,
그 밖의 알고리즘은 --mode non-approved와 함께 지정합니다. 전체 목록은 알고리즘과 동작 모드에 있습니다.
strcrypt info는 모듈 상태를 보이며, 모듈이 오류 상태(자가시험·무결성 검사 실패 등)이면 원인과 함께 종료 코드 1로 끝납니다.
명령어 레퍼런스
| 명령 | 동작 |
|---|---|
encrypt [TEXT] | 문자열을 암호화해 Base64로 출력하고 ./strcrypt_enc.bin에도 저장합니다. |
decrypt [DATA] | Base64 암호문을 복호화합니다. -f를 주면 파일(-i)에서 읽습니다. |
encrypt-file -i -o | 파일을 일정 크기씩 나눠 읽으면서 암호화합니다. |
decrypt-file -i -o | encrypt-file로 만든 파일을 복호화합니다. |
migrate-file -i -o -t | 암호화 파일을 다른 알고리즘으로 다시 암호화합니다. |
encrypt-batch | 한 줄에 레코드 하나씩 받아 입력 순서대로 암호화합니다. |
decrypt-batch | encrypt-batch 결과를 한 줄씩 복호화합니다. |
info | 지원 알고리즘과 키 상태를 보여 줍니다. |
명령마다 strcrypt <명령> --help로 전체 옵션을 볼 수 있습니다.
환경 변수
| 이름 | 용도 |
|---|---|
STRCRYPT_KEY_FILE | 키 파일 경로. 파일 권한은 0600이어야 합니다. |
STRCRYPT_KEY | 키 값(1~32바이트). STRCRYPT_KEY_FILE이 없을 때 씁니다. |
STRCRYPT_MODE | non-approved로 두면 8종 알고리즘을 모두 허용합니다. |
RAYON_NUM_THREADS | 배치 병렬 스레드 수. --threads가 우선합니다. |
문제 해결
| 메시지 | 조치 |
|---|---|
| 키 파일 권한은 0600 이어야 합니다 | chmod 600 strcrypt.key로 권한을 고칩니다. |
| STRCRYPT_KEY 환경 변수가 필요합니다 | STRCRYPT_KEY_FILE 또는 STRCRYPT_KEY를 설정한 셸에서 실행합니다. |
| 현재 모드(korean-standard)에서 허용되지 않는 알고리즘 | 국내 표준 외 알고리즘은 --mode non-approved와 함께 지정합니다. |
| IntegrityFailure | 실행 파일과 .hmac 파일(strcrypt와 strcrypt.hmac, strcrypt.exe와 strcrypt.exe.hmac)이 서로 맞지 않습니다. 두 파일을 다시 받아 SHA-256을 확인합니다. |