26S23b

QK·2026년 9월 22일

MinIO AIStor와 MinKMS(MinIO KMS) 환경에서 사용자별·Prefix별로 서로 다른 암호화 키를 적용하여 격리하는 것은 가능합니다.

MinIO의 SSE-KMS(Server-Side Encryption with KMS) 모델에서는 버킷 수준의 단일 기본 키뿐만 아니라, 각 사용자가 업로드할 때 자신이 접근 권한을 가진 특정 KMS 마스터 키(Key ID)를 지정하거나, MinIO IAM Policy의 조건문(kms:KeyId)을 통해 특정 Prefix에는 특정 KMS 키만 사용하도록 강제할 수 있습니다.

MinIO 공식 문서 기준의 아키텍처 원리와 일반 사용자를 위한 전용 키 발급 및 암호화 적용 절차입니다.

Prefix별 키 분리 구조의 핵심 원리

MinKMS(KMS) 계층:

MinKMS 내에 Prefix/사용자 단위의 마스터 키(key-team-a, key-team-b 등)를 생성합니다.
MinKMS 정책(App/Role)을 통해 MinIO 테넌트가 해당 키들을 암·복호화(GenerateKey, Decrypt)할 수 있도록 권한을 부여합니다.

MinIO IAM 계층:

버킷 내 특정 Prefix(team-a/*)에 접근하는 사용자(user-a)에게 해당 Prefix에 대한 s3:PutObject, s3:GetObject 권한을 줍니다.
중요: IAM 정책 조건문(Condition)을 걸어, user-a가 업로드할 때는 반드시 전용 키(key-team-a) 헤더를 사용해야만 업로드가 허용되도록 강제(kms:KeyId)합니다. 다른 키를 쓰거나 키를 지정하지 않으면 업로드가 거부(Deny)됩니다.

단계별 적용 절차 (Admin $\rightarrow$ User)

1단계: MinKMS에서 전용 암호화 키 생성 (Admin)

MinKMS CLI(kes 또는 minkms)를 통해 해당 사용자가 사용할 마스터 키를 생성합니다.

# 사용자/Prefix 전용 키 생성 (예: team-a 전용 키)
kes key create key-team-a -k https://minkms-endpoint:7373

2단계: MinIO IAM 정책 생성 (특정 Prefix 및 특정 Key 강제) (Admin)

사용자가 bucket-data/team-a/* 경로에 객체를 올릴 때 반드시 key-team-a를 헤더로 명시하도록 강제하는 정책 JSON을 작성합니다.

policy-team-a.json:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowPrefixAccess",
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:PutObject"
      ],
      "Resource": [
        "arn:aws:s3:::bucket-data/team-a/*"
      ]
    },
    {
      "Sid": "EnforceSpecificKMSKeyOnUpload",
      "Effect": "Deny",
      "Action": "s3:PutObject",
      "Resource": "arn:aws:s3:::bucket-data/team-a/*",
      "Condition": {
        "StringNotEquals": {
          "s3:x-amz-server-side-encryption-aws-kms-key-id": "key-team-a"
        }
      }
    },
    {
      "Sid": "DenyNonKMSEncryption",
      "Effect": "Deny",
      "Action": "s3:PutObject",
      "Resource": "arn:aws:s3:::bucket-data/team-a/*",
      "Condition": {
        "StringNotEquals": {
          "s3:x-amz-server-side-encryption": "aws:kms"
        }
      }
    }
  ]
}

정책을 MinIO에 등록하고 사용자에게 바인딩합니다:

# 정책 등록
mc admin policy create myminio team-a-kms-policy policy-team-a.json

# 사용자에게 정책 연결 (mc idp 통합 계정 또는 로컬 사용자)
mc admin policy attach myminio team-a-kms-policy --user user-team-a

3단계: 일반 사용자의 암호화 객체 업로드 및 조회 (User)

일반 사용자(user-team-a)는 자신의 자격 증명(AccessKey/SecretKey)으로 로그인한 뒤, 업로드 시 SSE-KMS 방식과 자신에게 할당된 키 ID를 지정해야 합니다.

CLI(`mc`) 사용 시

# 전용 키를 명시하여 업로드
mc cp target_file.bin myminio/bucket-data/team-a/target_file.bin \
  --enc-kms "key-team-a"

(만약 --enc-kms 옵션을 빼먹거나 다른 키 key-team-b를 지정하면 MinIO가 정책에 의해 Access Denied로 차단합니다.)

Python (`boto3`) SDK 사용 시

import boto3

s3 = boto3.client(
    "s3",
    endpoint_url="https://minio-aistor.example.com",
    aws_access_key_id="USER_ACCESS_KEY",
    aws_secret_access_key="USER_SECRET_KEY",
)

with open("sample.parquet", "rb") as f:
    s3.put_object(
        Bucket="bucket-data",
        Key="team-a/sample.parquet",
        Body=f,
        ServerSideEncryption="aws:kms",
        SSEKMSKeyId="key-team-a",  # 발급받은 전용 키 명시 필수
    )

파일 조회(Download) 시

MinIO는 객체 메타데이터에 어떤 KMS 키로 암호화되었는지 기록해 둡니다.
사용자가 GetObject를 호출하면 MinIO가 자동으로 MinKMS에 해당 키 복호화를 요청하므로, 다운로드 시에는 사용자가 별도의 키 ID 옵션을 줄 필요 없이 일반 다운로드와 동일하게 조회됩니다.
만약 MinKMS 정책상 해당 키가 비활성화되거나 사용자 권한이 회수되면 GetObject 시점에 복호화 실패로 다운로드가 차단됩니다.

MinIO 공식 문서(KMS 레퍼런스 체계) 기준으로 KES를 배제하고 MinKMS(엔터프라이즈 네이티브 KMS)를 사용할 때 바뀌는 핵심 포인트는 1) 관리 도구 및 키 프로비저닝 워크플로우, 2) 인증 및 정책 관리 모델, 3) MinIO 설정 방식입니다.

클라이언트/일반 사용자 관점(S3 API 호출 및 MinIO IAM 정책)에서는 동일하지만, 관리자 관점의 키 발급과 KMS 연동 절차가 완전히 바뀝니다.

1. 주요 변경점 요약

구분	KES (Key Encryption Service)	MinKMS (MinIO Enterprise KMS)
관리 도구 (CLI)	`kes` 독립 바이너리 CLI 사용	`minkms` 전용 CLI 또는 MinIO Enterprise Console UI
인증 모델	mTLS 인증서(Client/Server Cert) 기반	App ID + API Key / Secret Token 또는 OIDC/Role 기반
키 저장소(Backend)	Vault, AWS KMS 등의 어댑터 역할 필요	자체 내장 암호화 스토리지 및 완전 관리형 키 저장소
MinIO 연동 환경변수	`MINIO_KMS_KES_ENDPOINT` 등	`MINIO_KMS_SERVER` (MinKMS 전용 엔드포인트 및 토큰)
접근 제어 (RBAC)	YAML 설정 파일 내 정책(Policies) 명시	MinKMS 자체 RBAC 정책(Policy) 및 API Key 바인딩

2. MinKMS 기준 변경된 단계별 절차 (Admin)

1단계: MinKMS CLI 로그인 및 전용 마스터 키 생성

kes key create 대신, minkms CLI를 통해 마스터 키를 생성합니다.

# 1. MinKMS 엔드포인트 로그인 (관리자 인증)
minkms auth login --endpoint https://minkms.example.com:7373 --token <ADMIN_ENCRYPTION_TOKEN>

# 2. 사용자/Prefix 전용 마스터 키 생성 (예: team-a 전용 키)
minkms key create key-team-a

(Enterprise Console 웹 UI가 구성되어 있다면 KMS -> Keys 메뉴에서 클릭 몇 번으로 즉시 생성할 수도 있습니다.)

2단계: MinIO 테넌트에 키 사용 권한 부여 (MinKMS 정책)

KES에서는 설정 파일에 mTLS 클라이언트 지문을 등록했지만, MinKMS에서는 MinIO 테넌트 서비스 계정(App ID)에 해당 키에 대한 암/복호화 권한(generate-key, decrypt)을 부여하는 정책을 생성하고 바인딩합니다.

# MinKMS 정책 정의 (MinIO가 key-team-a를 사용하여 암호화/복호화할 수 있도록 허용)
minkms policy create allow-team-a-key \
  --action key:generate \
  --action key:decrypt \
  --resource key-team-a

# MinIO 테넌트의 App ID/Client ID에 정책 부여
minkms policy bind allow-team-a-key --app-id minio-aistor-tenant-01

3단계: MinIO AIStor 테넌트 환경변수 설정

MinIO 컨테이너/파드에 주입하는 KMS 환경변수 체계가 MinKMS 전용으로 적용됩니다.

# MinIO와 MinKMS 연동 환경변수
MINIO_KMS_SERVER=https://minkms.example.com:7373
MINIO_KMS_APP_ID=minio-aistor-tenant-01
MINIO_KMS_APP_SECRET=<MINKMS_GENERATED_SECRET_KEY>
MINIO_KMS_API_KEY=<OPTIONAL_API_KEY>

3. 변경되지 않는 부분 (일반 사용자 및 S3 계층)

MinKMS로 전환되더라도 일반 사용자가 사용하는 S3 API 규격과 MinIO IAM 정책은 100% 동일합니다.

MinIO IAM Policy:

앞서 작성한 s3:x-amz-server-side-encryption-aws-kms-key-id: key-team-a 조건문은 그대로 유지됩니다. MinIO는 내부적으로 이 Key ID를 받아 MinKMS API로 중계하기 때문입니다.

클라이언트 CLI (mc):

mc cp file.parquet myminio/bucket-data/team-a/file.parquet --enc-kms "key-team-a"

SDK (boto3 등):

ServerSideEncryption='aws:kms', SSEKMSKeyId='key-team-a' 파라미터는 완전히 동일하게 작동합니다.

즉, 인프라/관리자 단에서 kes 바이너리와 인증서 노가다가 빠지고, minkms 전용 CLI/UI 및 정책 바인딩으로 일원화되어 운영 복잡도가 훨씬 낮아지는 것이 MinKMS 도입 시 달라지는 핵심입니다.

===

네, MinIO AIStor와 MinIO KMS (minkms) 연동 환경에서는 버킷 내부의 Prefix 또는 개별 사용자별로 서로 다른 암호화 키(Master Key)를 생성하고 지정하여 구분 암호화하는 것이 가능합니다.

1. Prefix 및 사용자별 암호화 키 분리 원리

MinIO KMS 측: 하나의 Enclave 내부에 사용자나 Prefix 전용 마스터 키(예: userA-key, userB-key, dept1-prefix-key)를 개별적으로 여러 개 생성해 둘 수 있습니다. 필요한 경우 KMS의 PBAC(정책 기반 접근 제어) 정책을 사용해 특정 키 이름 패턴(userA-key*)에 대한 암호화/복호화 권한만 허용하도록 제한할 수도 있습니다.
MinIO AIStor (S3) 측: 클라이언트(사용자)가 데이터 업로드 시 S3 헤더(X-Amz-Server-Side-Encryption-Aws-Kms-Key-Id)에 사용할 전용 키 이름을 지정하거나, 특정 Prefix 경로에 기본 암호화 키를 다르게 바인딩해 두면, AIStor가 MinIO KMS에 해당 키에 대한 데이터 암호화 키(DEK) 발급을 요청하여 각기 다른 키로 암호화 처리합니다.

2. 일반 사용자를 위한 전용 키 발급 및 암호화 적용 절차 (MinIO Docs 기준)

1단계: MinIO KMS에서 사용자/Prefix 전용 마스터 키 생성 (KMS 관리자)

SysAdmin 또는 해당 Enclave 관리자가 minkms add-key 명령어를 실행하여 전용 암호화 키를 생성합니다.

minkms add-key <USER_KEY_NAME> --enclave <ENCLAVE_NAME> --api-key k1:<ADMIN_API_KEY>

실제 명령어 예시:

minkms add-key userA-key --enclave aistor-primary --api-key k1:ADMIN_KEY_VALUE

2단계: (선택 사항) KMS 정책 작성 및 접근 권한 할당 (KMS 관리자)

특정 사용자나 서비스 계정이 지정된 키에 대해서만 접근(KEY:ENCRYPT, KEY:DECRYPT, KEY:GENERATE)할 수 있도록 Glob 스펙 기반 정책을 작성하여 할당할 수 있습니다.

{
  "allow": {
    "KEY:ENCRYPT": ["userA-key*"],
    "KEY:DECRYPT": ["userA-key*"],
    "KEY:GENERATE": ["userA-key*"],
    "KEY:STATUS": ["userA-key*"]
  }
}

정책 등록 및 할당:

minkms add-policy userA-policy --file userA-policy.json --enclave aistor-primary
minkms set-policy userA-policy --identity h1:<USER_IDENTITY_VALUE> --enclave aistor-primary

3단계: AIStor 버킷/Prefix 단위 키 지정 및 암호화 적용 (사용자/S3 관리자)

전용 키가 생성되면 두 가지 방식 중 하나로 암호화를 적용할 수 있습니다.

방식 A. 특정 Prefix/버킷에 기본 암호화 키 설정 (`mc encrypt set`)

특정 버킷 하위의 Prefix 경로에 대해 업로드되는 모든 객체가 자동으로 해당 전용 키로 암호화되도록 기본 암호화 키를 설정합니다.

# userA의 Prefix 경로에 userA-key를 기본 암호화 키로 지정
mc encrypt set sse-kms userA-key myminio/my-bucket/userA-prefix/

방식 B. 객체 업로드 시 요청 헤더로 전용 키 직접 지정

클라이언트 애플리케이션 또는 S3 사용자가 파일 업로드(PUT) 시 S3 SSE-KMS 헤더로 할당받은 전용 키 이름을 지정합니다.

MinIO Client (mc) 사용 시:

mc cp --encrypt-key "sse-kms=userA-key" mydata.csv myminio/my-bucket/userA-prefix/

S3 API / SDK (REST, Boto3 등) 사용 시:
업로드 요청 헤더에 아래 항목을 포함합니다:
```
X-Amz-Server-Side-Encryption: aws:kms
X-Amz-Server-Side-Encryption-Aws-Kms-Key-Id: userA-key
```

💡 참고: S3 일반 클라이언트는 MinIO KMS에 직접 접근하지 않고 AIStor 서버를 거쳐 동작하므로, 클라이언트는 자신이 사용할 KMS 키 이름(userA-key)만 전달받아 업로드 헤더나 Prefix 암호화 설정에 사용하시면 됩니다.

암호화 적용 후 mc head 명령 등을 통해 특정 객체의 SSE-KMS 암호화 적용 상태 및 사용된 키 정보 확인 예시가 필요하신가요?

engineer

이전 포스트

26S23a

다음 포스트

26S23b

Prefix별 키 분리 구조의 핵심 원리

단계별 적용 절차 (Admin $\rightarrow$ User)

1단계: MinKMS에서 전용 암호화 키 생성 (Admin)

2단계: MinIO IAM 정책 생성 (특정 Prefix 및 특정 Key 강제) (Admin)

3단계: 일반 사용자의 암호화 객체 업로드 및 조회 (User)

CLI(`mc`) 사용 시

Python (`boto3`) SDK 사용 시

파일 조회(Download) 시

1. 주요 변경점 요약

2. MinKMS 기준 변경된 단계별 절차 (Admin)

1단계: MinKMS CLI 로그인 및 전용 마스터 키 생성

2단계: MinIO 테넌트에 키 사용 권한 부여 (MinKMS 정책)

3단계: MinIO AIStor 테넌트 환경변수 설정

3. 변경되지 않는 부분 (일반 사용자 및 S3 계층)

1. Prefix 및 사용자별 암호화 키 분리 원리

2. 일반 사용자를 위한 전용 키 발급 및 암호화 적용 절차 (MinIO Docs 기준)

1단계: MinIO KMS에서 사용자/Prefix 전용 마스터 키 생성 (KMS 관리자)

2단계: (선택 사항) KMS 정책 작성 및 접근 권한 할당 (KMS 관리자)

3단계: AIStor 버킷/Prefix 단위 키 지정 및 암호화 적용 (사용자/S3 관리자)

방식 A. 특정 Prefix/버킷에 기본 암호화 키 설정 (`mc encrypt set`)

방식 B. 객체 업로드 시 요청 헤더로 전용 키 직접 지정

26S23a

26S24a

0개의 댓글

26S23b

Prefix별 키 분리 구조의 핵심 원리

단계별 적용 절차 (Admin →\rightarrow→ User)

1단계: MinKMS에서 전용 암호화 키 생성 (Admin)

2단계: MinIO IAM 정책 생성 (특정 Prefix 및 특정 Key 강제) (Admin)

3단계: 일반 사용자의 암호화 객체 업로드 및 조회 (User)

CLI(mc) 사용 시

Python (boto3) SDK 사용 시

파일 조회(Download) 시

1. 주요 변경점 요약

2. MinKMS 기준 변경된 단계별 절차 (Admin)

1단계: MinKMS CLI 로그인 및 전용 마스터 키 생성

2단계: MinIO 테넌트에 키 사용 권한 부여 (MinKMS 정책)

3단계: MinIO AIStor 테넌트 환경변수 설정

3. 변경되지 않는 부분 (일반 사용자 및 S3 계층)

1. Prefix 및 사용자별 암호화 키 분리 원리

2. 일반 사용자를 위한 전용 키 발급 및 암호화 적용 절차 (MinIO Docs 기준)

1단계: MinIO KMS에서 사용자/Prefix 전용 마스터 키 생성 (KMS 관리자)

2단계: (선택 사항) KMS 정책 작성 및 접근 권한 할당 (KMS 관리자)

3단계: AIStor 버킷/Prefix 단위 키 지정 및 암호화 적용 (사용자/S3 관리자)

방식 A. 특정 Prefix/버킷에 기본 암호화 키 설정 (mc encrypt set)

방식 B. 객체 업로드 시 요청 헤더로 전용 키 직접 지정

26S23a

26S24a

0개의 댓글

단계별 적용 절차 (Admin $\rightarrow$ User)

CLI(`mc`) 사용 시

Python (`boto3`) SDK 사용 시

방식 A. 특정 Prefix/버킷에 기본 암호화 키 설정 (`mc encrypt set`)