SOFTWARE

Node.js 사용법

npm 패키지 파일을 설치하면 require나 import로 불러와 쓸 수 있습니다. TypeScript 타입 정의가 함께 들어 있습니다.

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

설치

Linux (bash)

curl -fLO https://www.cubiware.co.kr/api/download/strcrypt/0.3.1/strcrypt-0.3.1.tgz
curl -fLO https://www.cubiware.co.kr/api/download/strcrypt/0.3.1/SHA256SUMS
sha256sum -c --ignore-missing SHA256SUMS
npm install ./strcrypt-0.3.1.tgz

Windows (PowerShell)

curl.exe -fLO https://www.cubiware.co.kr/api/download/strcrypt/0.3.1/strcrypt-0.3.1.tgz
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" }
  }
}
npm install .\strcrypt-0.3.1.tgz

Node.js 18 이상, Linux x86_64(glibc 2.28 이상)와 Windows 10·11 x64에서 동작합니다. 패키지 하나에 두 운영체제용 네이티브 모듈이 모두 들어 있습니다.

키 설정

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

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

문자열 암복호화

const strcrypt = require('strcrypt');

const token = strcrypt.encrypt('alice@example.com');
console.log(token);
console.log(strcrypt.decrypt(token));

ESM

import { encrypt, decrypt } from 'strcrypt';

console.log(decrypt(encrypt('alice@example.com')));

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

알고리즘 지정

const seed = strcrypt.encryptWithAlgorithm('alice@example.com', 'seed128gcm');
console.log(strcrypt.decrypt(seed));

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

AAD 지정

const aad = Buffer.from('customer:42');
const phone = strcrypt.encryptWithAad('010-1234-5678', aad);
console.log(strcrypt.decryptWithAad(phone, aad));

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

배치 처리

const tokens = strcrypt.encryptBatch(['alice@example.com', 'bob@example.com']);
console.log(strcrypt.decryptBatch(tokens));

const rows = [Buffer.from('alice@example.com'), Buffer.from('bob@example.com')];
const aads = [Buffer.from('id=1'), Buffer.from('id=2')];
const encrypted = strcrypt.encryptBatchBytesWithAad(rows, 'aria256gcm', aads);
console.log(strcrypt.decryptBatchBytesWithAad(encrypted, aads).map(String));

encryptBatch는 문자열 배열을, encryptBatchBytesWithAad는 Buffer 레코드 배열을 레코드별 AAD와 함께 처리합니다. 결과 배열은 길이와 순서가 입력과 같습니다. 레코드가 아주 많으면 chunkSize와 maxChunkBytes로 한 번에 처리할 양을 나눕니다.

파일 암복호화

strcrypt.encryptFile('report.csv', 'report.csv.enc');
strcrypt.decryptFile('report.csv.enc', 'report.dec.csv');

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

오류 처리

try {
  strcrypt.decryptWithAad(phone, Buffer.from('customer:43'));
} catch (e) {
  console.log(e.message);
}

try {
  strcrypt.decryptBatchBytesWithAad(encrypted, [Buffer.from('id=1'), Buffer.from('id=9')]);
} catch (e) {
  console.log(e.recordIndex);
}

키가 다르거나 AAD가 맞지 않거나 암호문이 바뀌면 Error가 발생합니다. encryptBatchBytesWithAad와 decryptBatchBytesWithAad는 레코드 하나라도 실패하면 결과 없이 예외를 내고, 실패한 레코드 위치를 recordIndex에 담습니다. 문자열 인자에 짝이 없는 서로게이트 문자가 있으면 인자 이름으로 시작하는 RangeError로 거부합니다.

API 레퍼런스

함수	설명
`encrypt(text) / decrypt(encryptedBase64)`	문자열 ↔ Base64 암호문 문자열
`encryptBytes(text) / decryptBytes(encryptedData)`	문자열 ↔ 암호문 Buffer
`encryptWithAlgorithm(text, algorithm)`	알고리즘을 지정해 암호화. 복호화는 decrypt 또는 decryptWithAlgorithm(encryptedBase64, algorithm?)
`encryptWithAad(text, aad) / decryptWithAad(encryptedBase64, aad)`	AAD(Buffer)와 함께 암복호화
`encryptBytesWithAad(data, aad) / decryptBytesWithAad(encryptedData, aad)`	Buffer 데이터를 AAD와 함께 암복호화
`encryptBatch(texts) / decryptBatch(encryptedList)`	문자열 배열을 한 번에 처리. 배열이 크면 …Parallel 함수로 병렬 처리
`encryptBatchBytesWithAad(inputs, algorithm, aads?, chunkSize?, maxChunkBytes?)`	Buffer 레코드 배열을 레코드별 AAD와 함께 암호화
`decryptBatchBytesWithAad(encrypted, aads?, chunkSize?, maxChunkBytes?)`	위 결과를 복호화해 Buffer 배열로 반환
`encryptFile(inputPath, outputPath, algorithm?) / decryptFile(inputPath, outputPath)`	파일을 일정 크기씩 나눠 읽으면서 암복호화. …Parallel 함수도 있음
`searchIndex(value, domain)`	암호화한 열의 같은 값 검색용 인덱스(16진 64자). domain은 열을 구분하는 문자열(예: customers.ssn). SQL 함수 strcrypt_search_index와 같은 값
`supportedAlgorithms() / version()`	사용 가능한 알고리즘 식별자 배열, 라이브러리 버전

문제 해결

메시지	조치
Cannot find module 'strcrypt-…'	Linux x86_64(glibc)와 Windows x64만 지원합니다. macOS, ARM CPU, musl 기반 이미지(Alpine 등)에서는 쓸 수 없습니다.
npm.ps1 파일을 로드할 수 없습니다	PowerShell 실행 정책이 스크립트 실행을 막은 경우입니다. npm 대신 npm.cmd로 실행합니다.
STRCRYPT_KEY 환경 변수가 필요합니다	node 프로세스를 시작하기 전에 STRCRYPT_KEY_FILE 또는 STRCRYPT_KEY를 설정합니다.
현재 모드(korean-standard)에서 허용되지 않는 알고리즘	국내 표준 외 알고리즘은 STRCRYPT_MODE=non-approved를 설정하고 프로세스를 시작합니다.