SOFTWARE

Node.js Guide

Install the npm package file and load it with require or import. TypeScript type definitions are included.

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

Install

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

Runs on Node.js 18 or later on Linux x86_64 (glibc 2.28 or later) and Windows 10 and 11 x64. One package contains the native modules for both operating systems.

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 node 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

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 returns a Base64 string, so you can store it directly in a text column. Encrypting the same value produces a different result every time. All functions are synchronous.

Choose an algorithm

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

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

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

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

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 takes an array of strings, and encryptBatchBytesWithAad takes an array of Buffer records with per-record AAD. The result has the same length and order as the input. For very large inputs, split the work with chunkSize and maxChunkBytes.

Encrypt and decrypt files

strcrypt.encryptFile('report.csv', 'report.csv.enc');
strcrypt.decryptFile('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.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);
}

A wrong key, mismatched AAD, or altered ciphertext throws an Error. encryptBatchBytesWithAad and decryptBatchBytesWithAad throw without partial results if any record fails, and put the failing record's position in recordIndex. String arguments containing an unpaired surrogate are rejected with a RangeError whose message starts with the argument name.

API reference

Function	Description
`encrypt(text) / decrypt(encryptedBase64)`	String ↔ Base64 ciphertext string
`encryptBytes(text) / decryptBytes(encryptedData)`	String ↔ ciphertext Buffer
`encryptWithAlgorithm(text, algorithm)`	Encrypt with a chosen algorithm. Decrypt with decrypt or decryptWithAlgorithm(encryptedBase64, algorithm?)
`encryptWithAad(text, aad) / decryptWithAad(encryptedBase64, aad)`	Encrypt and decrypt with AAD (Buffer)
`encryptBytesWithAad(data, aad) / decryptBytesWithAad(encryptedData, aad)`	Encrypt and decrypt Buffer data with AAD
`encryptBatch(texts) / decryptBatch(encryptedList)`	Process an array of strings at once. Use the …Parallel functions for large arrays
`encryptBatchBytesWithAad(inputs, algorithm, aads?, chunkSize?, maxChunkBytes?)`	Encrypt an array of Buffer records with per-record AAD
`decryptBatchBytesWithAad(encrypted, aads?, chunkSize?, maxChunkBytes?)`	Decrypt the result above into an array of Buffers
`encryptFile(inputPath, outputPath, algorithm?) / decryptFile(inputPath, outputPath)`	Encrypt and decrypt files in chunks. …Parallel variants are also available
`searchIndex(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
`supportedAlgorithms() / version()`	Array 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
Cannot find module 'strcrypt-…'	The package supports Linux x86_64 (glibc) and Windows x64 only. It does not run on macOS, ARM CPUs, or musl-based images such as Alpine.
npm.ps1 cannot be loaded because running scripts is disabled	The PowerShell execution policy is blocking scripts. Run npm.cmd instead of npm.
STRCRYPT_KEY is required	Set STRCRYPT_KEY_FILE or STRCRYPT_KEY before starting the node 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.