MariaDB 사용법

시스템 요구 사항

MariaDB

11.8 LTS (MariaDB 공식 저장소 RPM)에서 시험했습니다. 서비스 이름은 mariadb 기준입니다.

DB 설정

서버와 연결 문자셋 utf8mb4

DB 서버 OS

Linux x86_64, glibc 2.28 이상 (예: RHEL·Rocky Linux 8 이상)

빌드 도구

gcc, make, MariaDB-devel, curl, tar, sha256sum(coreutils 8.25 이상)

권한

DB 서버의 sudo 가능한 OS 계정, DB의 root(sudo mariadb)

RHEL AppStream의 MariaDB 10.x, Debian과 Ubuntu 패키지, Galera와 복제 구성, SELinux enforcing 구성은 시험하지 않았습니다. MySQL은 MySQL 사용법을 봅니다. 두 DBMS는 같은 연동 소스 묶음을 씁니다.

실행 위치

mariadbd가 UDF 라이브러리 mysql_strcrypt.so를 불러오고, UDF가 같은 plugin 디렉토리의 libstrcrypt.so를 호출합니다. 라이브러리, 키 파일, 설정은 모두 DB 서버에 둡니다. 애플리케이션 서버에는 따로 설치할 것이 없습니다. UDF는 서버 전역에 등록되므로 데이터베이스마다 설치하지 않습니다.

1. 사전 점검

mariadb --version
ldd --version | head -1
sudo mariadb -e "SELECT @@version, @@plugin_dir, @@character_set_server"
systemctl cat mariadb | grep -E '^(User|ProtectHome|ProtectSystem)='
command -v gcc make curl sha256sum tar mariadb_config

MariaDB 버전, glibc 버전, plugin 디렉토리와 서버 문자셋(utf8mb4), 서비스 실행 계정과 보호 설정, 설치된 도구가 차례로 나옵니다. 서비스에 ProtectHome=true가 있으면 서버 프로세스가 홈 디렉토리를 볼 수 없으므로 키 파일은 /etc 아래에 둡니다.

자주 발생하는 오류

2. 라이브러리 빌드와 설치

빌드 도구가 없을 때만

sudo dnf install -y gcc make MariaDB-devel

다운로드·검증·빌드·설치

mkdir -p ~/strcrypt-mariadb && cd ~/strcrypt-mariadb
curl -fLO https://www.cubiware.co.kr/api/download/strcrypt/0.3.1/libstrcrypt.so
curl -fLO https://www.cubiware.co.kr/api/download/strcrypt/0.3.1/libstrcrypt.so.hmac
curl -fLO https://www.cubiware.co.kr/api/download/strcrypt/0.3.1/strcrypt-mysql-0.3.1.tar.gz
curl -fLO https://www.cubiware.co.kr/api/download/strcrypt/0.3.1/SHA256SUMS
sha256sum -c --ignore-missing SHA256SUMS
tar xzf strcrypt-mysql-0.3.1.tar.gz && cd strcrypt-mysql-0.3.1
PLUGIN_DIR=$(sudo mariadb -N -e 'SELECT @@plugin_dir')
sudo install -m 755 ../libstrcrypt.so "$PLUGIN_DIR"
sudo install -m 644 ../libstrcrypt.so.hmac "$PLUGIN_DIR"
make STRCRYPT_LIB_DIR="$PLUGIN_DIR" STRCRYPT_INCLUDE_DIR=.
sudo install -m 755 mysql_strcrypt.so "$PLUGIN_DIR"
ldd "$PLUGIN_DIR/mysql_strcrypt.so" | grep strcrypt

UDF는 DB 서버의 헤더로 빌드해야 하므로 소스로 제공하며, MySQL과 같은 strcrypt-mysql-0.3.1.tar.gz를 씁니다. 빌드는 ~/strcrypt-mariadb 아래에서 하고, 라이브러리 3개를 모두 plugin 디렉토리에 둡니다. libstrcrypt.so를 plugin 디렉토리에 먼저 설치하고 그 경로로 빌드해야 UDF 라이브러리가 홈 디렉토리 경로를 참조하지 않습니다. 마지막 줄이 libstrcrypt.so => /usr/lib64/mysql/plugin/libstrcrypt.so를 출력하면 성공입니다. 이 단계에서는 재시작이 필요 없습니다.

자주 발생하는 오류

3. 키 파일 생성

sudo install -d -o mysql -m 700 /etc/strcrypt
head -c 24 /dev/urandom | base64 | head -c 32 | sudo -u mysql tee /etc/strcrypt/strcrypt.key > /dev/null
sudo chmod 600 /etc/strcrypt/strcrypt.key
sudo -u mysql wc -c /etc/strcrypt/strcrypt.key

32바이트 키를 mysql 계정만 읽을 수 있는 파일로 만듭니다. 마지막 줄이 32 /etc/strcrypt/strcrypt.key를 출력해야 합니다. 두 번째 줄은 기존 키 파일을 덮어쓰므로 키가 이미 있으면 다시 실행하지 않습니다. 키는 SQL 인자나 테이블로 전달하지 않습니다. 키를 잃으면 암호문을 복구할 수 없으니 키를 따로 백업해 두세요.

자주 발생하는 오류

키 파일 문제는 5단계 이후 함수를 호출할 때 ERROR 1123 (HY000): Can't initialize function 'strcrypt_encrypt'; 환경 변수 오류: 뒤에 붙어 나옵니다. 서버가 사유를 80바이트에서 자르므로 문구 끝이 잘려 보입니다. 키 파일을 고친 뒤에는 mariadb를 다시 시작해야 반영됩니다.

4. 서버에 키 경로 전달

sudo mkdir -p /etc/systemd/system/mariadb.service.d
printf '[Service]\nEnvironment=STRCRYPT_KEY_FILE=/etc/strcrypt/strcrypt.key\n' | sudo tee /etc/systemd/system/mariadb.service.d/strcrypt.conf
sudo systemctl daemon-reload
sudo systemctl restart mariadb
systemctl show mariadb -p Environment

systemd 설정 조각 파일로 mariadb 서비스에 환경 변수 STRCRYPT_KEY_FILE을 넘깁니다. 마지막 줄이 Environment=STRCRYPT_KEY_FILE=/etc/strcrypt/strcrypt.key를 출력하면 반영된 것입니다. 재시작하는 동안 DB 접속이 잠시 끊깁니다. 셸에서 export한 값은 서버에 전달되지 않습니다. 국내 표준 외 알고리즘을 쓰려면 Environment=STRCRYPT_MODE=non-approved 줄을 추가합니다.

자주 발생하는 오류

5. UDF 등록

cd ~/strcrypt-mariadb/strcrypt-mysql-0.3.1
sudo mariadb < install.sql

install.sql이 함수 6개를 등록하고 마지막에 암복호화 시험을 실행합니다. 출력에 [OK]와 === 설치 완료 ===가 나오면 성공입니다. 등록은 서버를 다시 시작해도 유지되고, 스크립트는 다시 실행할 수 있습니다. 스크립트는 기존 함수를 먼저 지우므로 라이브러리 파일이 없는 상태에서 실행하면 함수가 모두 사라집니다.

자주 발생하는 오류

6. 실행 권한 정리

MariaDB에는 UDF 실행 권한이 없어 복호화 함수를 호출할 사용자를 제한할 수 없습니다. DB에 접속할 수 있는 계정이면 권한이 USAGE뿐이어도 암호문 문자열을 복호화합니다. 대신 익명 계정을 지우고, 암호문 컬럼과 키 파일에 접근할 수 있는 계정을 제한합니다.

익명 계정 삭제, FILE 권한 회수, secure_file_priv 지정

sudo mariadb -e "SELECT user, host FROM mysql.user WHERE user = '' OR (File_priv = 'Y' AND user NOT IN ('root', 'mysql'))"
sudo mariadb -N -e "SELECT CONCAT('DROP USER ', QUOTE(user), '@', QUOTE(host), ';') FROM mysql.user WHERE user = ''" | sudo mariadb
sudo mariadb -N -e "SELECT CONCAT('REVOKE FILE ON *.* FROM ', QUOTE(user), '@', QUOTE(host), ';') FROM mysql.user WHERE File_priv = 'Y' AND user NOT IN ('root', 'mysql')" | sudo mariadb
sudo install -d -o mysql -g mysql -m 750 /var/lib/mysql-files
printf '[mariadb]\nsecure_file_priv=/var/lib/mysql-files\n' | sudo tee /etc/my.cnf.d/strcrypt-hardening.cnf
sudo systemctl restart mariadb
sudo mariadb -N -e "SELECT @@secure_file_priv"

첫 줄은 지울 익명 계정과 FILE 권한 계정을 보여 줍니다. 마지막 줄이 /var/lib/mysql-files/를 출력하면 적용된 것입니다. 마지막 재시작으로 DB 접속이 잠시 끊기고, 이후 이 디렉토리 밖의 LOAD DATA INFILE과 INTO OUTFILE이 거부됩니다. 기존 애플리케이션이 이 기능을 쓰는지 먼저 확인합니다. 이 블록은 다시 실행할 수 있습니다.

암호문 컬럼을 뺀 컬럼 권한 예

GRANT SELECT (id, name) ON appdb.customers TO 'reporter'@'localhost';

자주 발생하는 오류

7. 설치 확인

문자셋과 기본 암복호화

SELECT @@character_set_client, @@character_set_connection, @@character_set_server;
SELECT CONVERT(strcrypt_decrypt(strcrypt_encrypt_algo('test', 'aria256gcm')) USING utf8mb4) AS result;

왕복 시험 (1,000행, 시험 테이블은 끝에서 삭제)

CREATE TABLE strcrypt_selftest (id INT PRIMARY KEY, val VARCHAR(100) CHARACTER SET utf8mb4 NOT NULL);
INSERT INTO strcrypt_selftest SELECT seq, CONCAT('row-', seq, '-홍길동') FROM seq_1_to_1000;

SELECT COUNT(*) AS CHECKED,
       SUM(NOT (CAST(strcrypt_decrypt(strcrypt_encrypt_algo(val, 'aria256gcm')) AS BINARY) <=> CAST(val AS BINARY))) AS MISMATCHES
FROM strcrypt_selftest;

DROP TABLE strcrypt_selftest;

애플리케이션 사용자로 애플리케이션 DB에 접속해 실행합니다(예: mariadb -u app_user -p appdb). 첫 조회는 utf8mb4 세 개, 두 번째는 test, 왕복 시험은 CHECKED 1000 | MISMATCHES 0이 나와야 합니다. 왕복 시험에는 CREATE, DROP, INSERT, SELECT 권한이 필요합니다.

자주 발생하는 오류

SQL 함수

SELECT, INSERT, UPDATE 어디서나 일반 함수처럼 씁니다. 입력이 NULL이면 결과도 NULL입니다. 결과 문자셋이 binary라 문자열로 쓰려면 CONVERT(... USING utf8mb4)로 감싸고, 값을 비교할 때는 CAST(... AS BINARY)로 바이트를 비교합니다(7단계 예). 암호화할 때는 strcrypt_encrypt_algo로 알고리즘을 지정합니다. 알고리즘을 뺀 strcrypt_encrypt의 암호문은 헤더가 없어, 서버의 동작 모드를 바꾸면 복호화되지 않습니다.

한 행의 암복호화가 실패하면 문장 전체가 멈추지 않고 그 행만 NULL이 됩니다. 변조된 암호문, 다른 키, Base64가 아닌 값, UTF-8이 아닌 입력, NUL 바이트가 든 입력이 여기에 해당하며 NULL 입력과 구분되지 않습니다.

암호문은 같은 값이어도 매번 달라서 인덱스로 찾을 수 없습니다. 같은 값 검색이 필요하면 strcrypt_search_index(값, '테이블.열') 결과를 검색용 컬럼에 저장하고 인덱스를 겁니다. 조회할 때도 같은 함수로 검색어의 인덱스를 만들어 비교합니다. 키 없는 SHA-256 해시는 쓰지 않습니다. 주민번호처럼 추측할 수 있는 값은 후보를 모두 해시해 보면 원래 값이 나옵니다. 검색용 컬럼은 같은 값을 가진 행이 어느 것인지 드러내므로 필요한 컬럼에만 두고, UDF는 함수별 실행 권한이 없어 접속할 수 있는 모든 계정이 이 함수로 후보 값의 인덱스를 만들어 맞춰 볼 수 있다는 점을 감안합니다.

대량 처리

MariaDB에는 여러 행을 한 번에 받는 UDF가 없습니다. UDF는 행마다 한 번씩 호출되는 구조라 SQL 안에서 호출 횟수를 줄일 수 없기 때문입니다. 여러 행은 DB 밖에서 기본 키 순서로 청크를 조회해 CLI로 한 번에 암복호화하고, 기본 키 조건으로 반영합니다. CLI로 만든 암호문은 UDF로, UDF로 만든 암호문은 CLI로 복호화할 수 있습니다. 이 방법은 서버의 local_infile 설정과 임시 테이블 권한이 필요 없고, SELECT·UPDATE 권한만 씁니다.

CLI 준비

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

작업 디렉토리 (키 사본과 접속 정보)

mkdir -p ~/strcrypt-batch && cd ~/strcrypt-batch
sudo install -o "$USER" -m 600 /etc/strcrypt/strcrypt.key strcrypt.key
(umask 077; printf '[client]\nuser=%s\npassword=%s\n' 'app_user' 'APP_PASSWORD' > app.cnf)
export STRCRYPT_KEY_FILE="$PWD/strcrypt.key"
export PATH="$HOME/strcrypt:$PATH"
DB="mariadb --defaults-extra-file=$PWD/app.cnf appdb"

CLI는 DB와 같은 키를 써야 합니다. 서버 키 파일은 mysql 계정만 읽으므로 현재 계정이 읽을 사본을 만들고, 애플리케이션 사용자의 접속 정보를 권한 600 파일에 둡니다. APP_PASSWORD를 실제 비밀번호로 바꿉니다. 작업이 끝나면 키 사본과 app.cnf를 지웁니다.

기존 컬럼 일괄 암호화

set -euo pipefail
last=0
while :; do
  rows=$($DB -N -B -e "SELECT id, REPLACE(TO_BASE64(ssn), '\n', '') FROM customers
                       WHERE id > $last AND ssn IS NOT NULL AND ssn_enc IS NULL ORDER BY id LIMIT 1000")
  [ -z "$rows" ] && break
  enc=$(printf '%s\n' "$rows" | cut -f2 | strcrypt encrypt-batch -a aria256gcm)
  paste <(printf '%s\n' "$rows" | cut -f1) <(printf '%s\n' "$enc") | awk -F'\t' '
    BEGIN { print "UPDATE customers SET ssn_enc = CASE id" }
    { print "WHEN " $1 " THEN \047" $2 "\047"; ids = ids (NR > 1 ? "," : "") $1 }
    END { print "END WHERE id IN (" ids ");" }' | $DB
  last=$(printf '%s\n' "$rows" | tail -n 1 | cut -f1)
  echo "encrypted up to id $last"
done

작업 디렉토리 설정과 같은 셸에서 실행합니다. 대화형 셸에서는 set -e 때문에 오류가 날 때 셸이 닫히므로, 두 블록을 한 파일로 저장해 bash로 실행하는 편이 안전합니다. 1,000행씩 평문을 Base64로 조회해 encrypt-batch로 암호화하고, 청크마다 UPDATE 한 문장으로 반영합니다. 청크마다 encrypted up to id ...를 출력합니다. ssn_enc IS NULL 조건이 있어 중간에 멈추면 같은 명령으로 이어서 처리합니다. 한 문장은 max_allowed_packet보다 작아야 하므로 값이 크면 청크 크기를 줄입니다.

• TO_BASE64는 76자마다 줄바꿈을 넣습니다. REPLACE로 지우지 않으면 CLI가 invalid Base64로 멈춥니다.
• NULL은 조회 결과에서 문자열 NULL이 되고, 이 문자열도 Base64로 읽혀 CLI가 오류 없이 엉뚱한 값을 암호화하므로 ssn IS NOT NULL 조건을 뺄 수 없습니다.

결과 대조 (app_user로 실행)

SELECT COUNT(*) AS CHECKED,
       SUM(NOT (CAST(strcrypt_decrypt(ssn_enc) AS BINARY) <=> CAST(ssn AS BINARY))) AS MISMATCHES
FROM customers WHERE ssn IS NOT NULL;

MISMATCHES가 0이면 CLI가 만든 암호문이 모두 UDF로 복호화된 것입니다.

UDF가 만든 암호문을 CLI로 복호화

$DB -N -B -e "SELECT strcrypt_encrypt_algo(ssn, 'aria256gcm') FROM customers WHERE id IN (1, 7) ORDER BY id" |
  strcrypt decrypt-batch | while read -r line; do printf '%s' "$line" | base64 -d; echo; done

decrypt-batch는 평문을 Base64로 내보내므로 base64 -d로 되돌려 한 줄씩 출력합니다.

제한 사항

• UDF 호출을 사용자별로 제한할 수 없습니다. 접속 계정과 암호문 컬럼의 읽기 권한으로 보호합니다.
• 평문은 UTF-8이어야 하고 NUL 바이트가 없어야 합니다. utf8mb4가 아닌 컬럼 값은 CONVERT(값 USING utf8mb4)로 넘깁니다.
• 클라이언트로 받는 결과는 max_allowed_packet보다 작아야 합니다. 서버 안에서 테이블에 저장하는 값은 이 한도를 넘어도 만들어집니다.
• 키 파일이나 서버 환경 변수를 바꾸면 mariadb를 다시 시작한 뒤부터 반영됩니다.
• 같은 값도 암호화할 때마다 암호문이 달라지므로 암호문 컬럼으로는 검색하거나 인덱스를 만들 수 없습니다. 검색이 필요하면 해시 컬럼을 따로 둡니다.
• 평문은 DB 서버의 mariadbd 프로세스 메모리를 거칩니다.

API 레퍼런스

암호화와 복호화 결과의 문자셋은 binary입니다. 키 오류, 라이브러리 오류, 상수로 준 허용되지 않는 알고리즘은 문장 전체를 ERROR 1123으로 멈추고, 그 밖의 행 단위 실패는 그 행만 NULL로 돌려줍니다.

시험 환경

1~7단계, 대량 처리 예시(2,495행 왕복, 한글 값과 긴 값 포함), USAGE 권한 계정과 익명 계정의 호출 가능 여부, 컬럼 권한 차단, secure_file_priv 적용 후 키 파일 읽기 거부를 확인했습니다(2026-09-17).