본문 바로가기
큐비웨어

SOFTWARE

Java 사용법

JAR와 네이티브 라이브러리 파일 두 개를 두고 StrCrypt 클래스의 정적 메서드를 호출합니다.

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

설치

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

JAR는 클래스패스에, libstrcrypt_jni.so(Windows는 strcrypt_jni.dll)가 있는 디렉토리는 java.library.path에 지정합니다. Maven이나 Gradle 프로젝트에서는 JAR를 로컬 파일 의존성으로 추가합니다. Java 11 이상, Linux x86_64와 Windows 10·11 x64에서 동작합니다.

컴파일과 실행

Windows는 클래스패스 구분자가 ;이고, PowerShell에서는 -D 옵션을 따옴표로 감쌉니다.

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

키 설정

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

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

문자열 암복호화

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는 Base64 문자열을 돌려주므로 DB 문자열 컬럼에 그대로 저장할 수 있습니다. 같은 값을 암호화해도 결과는 매번 다릅니다. 아래 예제는 main 안에 이어서 쓰는 코드입니다.

알고리즘 지정

String seed = StrCrypt.encryptWithAlgorithm("alice@example.com", "seed128gcm");
System.out.println(StrCrypt.decrypt(seed));

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

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

배치 처리

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는 문자열 목록을, encryptBatchBytesWithAad는 byte[] 레코드 배열을 레코드별 AAD와 함께 처리합니다. 결과는 길이와 순서가 입력과 같습니다. 레코드가 아주 많으면 chunkSize와 maxChunkBytes를 받는 오버로드로 한 번에 처리할 양을 나눕니다.

파일 암복호화

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

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

오류 처리

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());
}

메서드는 검사 예외 StrCryptException을 던집니다. 키가 다르거나 AAD가 맞지 않거나 암호문이 바뀌면 이 예외가 납니다. encryptBatchBytesWithAad와 decryptBatchBytesWithAad는 레코드 하나라도 실패하면 결과 없이 예외를 내고, 실패한 레코드 위치를 getRecordIndex()(OptionalLong)로 알려 줍니다.

API 레퍼런스

모두 com.strcrypt.StrCrypt의 정적 메서드입니다.

메서드설명
String encrypt(String) / String decrypt(String)문자열 ↔ Base64 암호문 문자열
byte[] encryptBytes(String) / String decryptBytes(byte[])문자열 ↔ 암호문 byte[]
String encryptWithAlgorithm(String text, String algorithm)알고리즘을 지정해 암호화. 복호화는 decrypt
String encryptWithAad(String, byte[] aad) / String decryptWithAad(String, byte[] aad)AAD와 함께 암복호화
byte[] encryptBytesWithAad(byte[], byte[]) / byte[] decryptBytesWithAad(byte[], byte[])byte[] 데이터를 AAD와 함께 암복호화
List<String> encryptBatch(List<String>) / List<String> decryptBatch(List<String>)문자열 목록을 한 번에 처리. 목록이 크면 …Parallel 메서드로 병렬 처리
byte[][] encryptBatchBytesWithAad(byte[][] inputs, String algorithm, byte[][] aads)byte[] 레코드 배열을 레코드별 AAD와 함께 암호화. chunkSize와 maxChunkBytes를 받는 오버로드 있음
byte[][] decryptBatchBytesWithAad(byte[][] encrypted, byte[][] aads)위 결과를 복호화. aads는 없으면 null
void encryptFile(String in, String out, String algorithm) / void decryptFile(String in, String out)파일을 일정 크기씩 나눠 읽으면서 암복호화. algorithm이 null이면 현재 모드의 기본 알고리즘
String searchIndex(String value, String domain)암호화한 열의 같은 값 검색용 인덱스(16진 64자). domain은 열을 구분하는 문자열(예: customers.ssn). SQL 함수 strcrypt_search_index와 같은 값
List<String> supportedAlgorithms() / String version()사용 가능한 알고리즘 식별자 목록, 라이브러리 버전

문제 해결

메시지조치
네이티브 라이브러리를 로드할 수 없습니다libstrcrypt_jni.so(Windows는 strcrypt_jni.dll)가 있는 디렉토리를 -Djava.library.path로 지정합니다.
STRCRYPT_KEY 환경 변수가 필요합니다JVM을 시작하기 전에 STRCRYPT_KEY_FILE 또는 STRCRYPT_KEY를 설정합니다. 애플리케이션 서버는 서비스 환경 설정에 넣습니다.
현재 모드(korean-standard)에서 허용되지 않는 알고리즘국내 표준 외 알고리즘은 STRCRYPT_MODE=non-approved를 설정하고 JVM을 시작합니다.

이미지를 클릭하면 원본 크기 · 바깥 클릭이나 Esc로 닫기