SOFTWARE

Java Guide

Place two files, the JAR and its native library, and call the static methods of the StrCrypt class.

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

Install

Linux (bash)

mkdir -p lib
curl -fL -o lib/strcrypt-0.3.1.jar https://www.cubiware.co.kr/api/download/strcrypt/0.3.1/strcrypt-0.3.1.jar
curl -fL -o lib/libstrcrypt_jni.so https://www.cubiware.co.kr/api/download/strcrypt/0.3.1/libstrcrypt_jni.so
curl -fLO https://www.cubiware.co.kr/api/download/strcrypt/0.3.1/SHA256SUMS
(cd lib && sha256sum -c --ignore-missing ../SHA256SUMS)

Windows (PowerShell)

New-Item -ItemType Directory -Force lib | Out-Null
curl.exe -fL -o lib\strcrypt-0.3.1.jar https://www.cubiware.co.kr/api/download/strcrypt/0.3.1/strcrypt-0.3.1.jar
curl.exe -fL -o lib\strcrypt_jni.dll https://www.cubiware.co.kr/api/download/strcrypt/0.3.1/strcrypt_jni.dll
curl.exe -fL -o lib\SHA256SUMS https://www.cubiware.co.kr/api/download/strcrypt/0.3.1/SHA256SUMS
cd lib
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" }
  }
}
cd ..

Put the JAR on the classpath and the directory containing libstrcrypt_jni.so (strcrypt_jni.dll on Windows) on java.library.path. In Maven or Gradle projects, add the JAR as a local file dependency. Requires Java 11 or later on Linux x86_64 or Windows 10 and 11 x64.

Compile and run

On Windows the classpath separator is ;, and in PowerShell the -D option must be quoted.

Linux (bash)

javac -cp lib/strcrypt-0.3.1.jar App.java
java -cp lib/strcrypt-0.3.1.jar:. -Djava.library.path=lib App

Windows (PowerShell)

javac -cp lib\strcrypt-0.3.1.jar App.java
java -cp "lib\strcrypt-0.3.1.jar;." "-Djava.library.path=lib" App

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 JVM starts. The key is read once, on the first encryption or decryption, so restart the JVM after changing it. Key rules and backup advice are in Quick start on the overview page.

Encrypt and decrypt strings

import com.strcrypt.StrCrypt;
import com.strcrypt.StrCryptException;
import java.nio.charset.StandardCharsets;
import java.util.List;

public class App {
    public static void main(String[] args) throws StrCryptException {
        String token = StrCrypt.encrypt("alice@example.com");
        System.out.println(token);
        System.out.println(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. The examples below continue inside main.

Choose an algorithm

String seed = StrCrypt.encryptWithAlgorithm("alice@example.com", "seed128gcm");
System.out.println(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

byte[] aad = "customer:42".getBytes(StandardCharsets.UTF_8);
String phone = StrCrypt.encryptWithAad("010-1234-5678", aad);
System.out.println(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

List<String> tokens = StrCrypt.encryptBatch(List.of("alice@example.com", "bob@example.com"));
System.out.println(StrCrypt.decryptBatch(tokens));

byte[][] rows = { "alice@example.com".getBytes(StandardCharsets.UTF_8), "bob@example.com".getBytes(StandardCharsets.UTF_8) };
byte[][] aads = { "id=1".getBytes(StandardCharsets.UTF_8), "id=2".getBytes(StandardCharsets.UTF_8) };
byte[][] encrypted = StrCrypt.encryptBatchBytesWithAad(rows, "aria256gcm", aads);
byte[][] decrypted = StrCrypt.decryptBatchBytesWithAad(encrypted, aads);

encryptBatch takes a list of strings, and encryptBatchBytesWithAad takes an array of byte[] records with per-record AAD. The result has the same length and order as the input. For very large inputs, use the overloads that take chunkSize and maxChunkBytes.

Encrypt and decrypt files

StrCrypt.encryptFile("report.csv", "report.csv.enc", null);
StrCrypt.decryptFile("report.csv.enc", "report.dec.csv");

Files are read and written in chunks. When the third argument is null, 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, "customer:43".getBytes(StandardCharsets.UTF_8));
} catch (StrCryptException e) {
    System.out.println(e.getMessage());
}

try {
    StrCrypt.decryptBatchBytesWithAad(encrypted, new byte[][] { aads[0], "id=9".getBytes(StandardCharsets.UTF_8) });
} catch (StrCryptException e) {
    System.out.println(e.getRecordIndex());
}

Methods throw the checked exception StrCryptException, including for a wrong key, mismatched AAD, or altered ciphertext. encryptBatchBytesWithAad and decryptBatchBytesWithAad throw without partial results if any record fails, and report the failing record's position through getRecordIndex() (OptionalLong).

API reference

All are static methods of com.strcrypt.StrCrypt.

Method	Description
`String encrypt(String) / String decrypt(String)`	String ↔ Base64 ciphertext string
`byte[] encryptBytes(String) / String decryptBytes(byte[])`	String ↔ ciphertext byte[]
`String encryptWithAlgorithm(String text, String algorithm)`	Encrypt with a chosen algorithm. Decrypt with decrypt
`String encryptWithAad(String, byte[] aad) / String decryptWithAad(String, byte[] aad)`	Encrypt and decrypt with AAD
`byte[] encryptBytesWithAad(byte[], byte[]) / byte[] decryptBytesWithAad(byte[], byte[])`	Encrypt and decrypt byte[] data with AAD
`List<String> encryptBatch(List<String>) / List<String> decryptBatch(List<String>)`	Process a list of strings at once. Use the …Parallel methods for large lists
`byte[][] encryptBatchBytesWithAad(byte[][] inputs, String algorithm, byte[][] aads)`	Encrypt an array of byte[] records with per-record AAD. Overloads accept chunkSize and maxChunkBytes
`byte[][] decryptBatchBytesWithAad(byte[][] encrypted, byte[][] aads)`	Decrypt the result above. Pass null for aads when there is none
`void encryptFile(String in, String out, String algorithm) / void decryptFile(String in, String out)`	Encrypt and decrypt files in chunks. A null algorithm uses the default of the current mode
`String searchIndex(String value, String 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
`List<String> supportedAlgorithms() / String 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
ExceptionInInitializerError when StrCrypt is first used, caused by a native library load failure	Point -Djava.library.path to the directory that contains libstrcrypt_jni.so (strcrypt_jni.dll on Windows).
STRCRYPT_KEY is required	Set STRCRYPT_KEY_FILE or STRCRYPT_KEY before the JVM starts. For application servers, add it to the service environment.
현재 모드(korean-standard)에서 허용되지 않는 알고리즘 (algorithm not allowed in the current mode)	For algorithms other than the Korean standards, set STRCRYPT_MODE=non-approved before the JVM starts.