260916_01_ENH: 공통 암호화 및 해시 기능 추가

This commit is contained in:
2026-09-16 12:30:30 +09:00
parent 333709fbfc
commit 1adb692661
25 changed files with 1285 additions and 3 deletions

100
README.md
View File

@@ -315,6 +315,77 @@ BypassResponse response = bypassClient.forward(
`Host`, `Content-Length`, `Transfer-Encoding`, `Connection` 같은 hop-by-hop header는
전달하지 않습니다.
### 암호화와 해시
공개 API는 `com.kri.common.feature.crypto.*`에 있습니다. 중앙 키 DB를 사용하지 않으며,
AES master key는 `kri.crypto.aes.keys` 설정 또는 각 호출의 `masterKey`로 전달합니다.
#### AES-256
기본 알고리즘은 인증 암호화인 `AES_256_GCM`입니다. `masterKey`와 salt를
`PBKDF2WithHmacSHA256`으로 처리해 256-bit AES key를 만들며, salt와 IV를 생략하면
안전한 난수로 자동 생성합니다. 기존 시스템 연동을 위해 salt와 IV를 직접 전달할 수도 있습니다.
```java
import com.kri.common.feature.crypto.aes.AesCryptoService;
import com.kri.common.feature.crypto.aes.AesDecryptRequest;
import com.kri.common.feature.crypto.aes.AesEncryptRequest;
import com.kri.common.feature.crypto.aes.AesEncryptedValue;
import com.kri.common.feature.crypto.aes.AesEncryptedValueCodec;
import com.kri.common.feature.crypto.aes.TagLayout;
AesEncryptedValue encrypted = aesCryptoService.encrypt(
AesEncryptRequest.builder(plainBytes)
.masterKey(masterKey)
.salt(salt)
.iv(iv)
.aad(aad)
.tagLayout(TagLayout.DETACHED)
.build()
);
String storedValue = AesEncryptedValueCodec.encode(encrypted);
AesEncryptedValue decoded = AesEncryptedValueCodec.decode(storedValue);
byte[] restored = aesCryptoService.decrypt(
AesDecryptRequest.builder(decoded)
.masterKey(masterKey)
.aad(aad)
.build()
);
```
- GCM tag는 ciphertext 결합형 `APPENDED` 또는 별도 필드형 `DETACHED`를 지원합니다.
- GCM tag는 생략할 수 없습니다. tag가 없는 기존 데이터는 명시적으로
`AES_256_CBC_PKCS5`를 선택해야 하며, CBC는 변조를 감지하지 못하므로 신규 데이터에 권장하지 않습니다.
- GCM IV는 12바이트, CBC IV는 16바이트이고 salt는 최소 16바이트입니다.
- 호출자가 IV를 직접 전달하면 동일한 key에서 IV가 중복되지 않도록 호출 서비스가 보장해야 합니다.
- AAD는 GCM에서만 지원하며 복호화할 때 암호화 시점과 동일한 값을 전달해야 합니다.
- 암호화 결과는 format version, algorithm, key ID, KDF iteration, salt, IV, ciphertext 및 tag 정보를 포함합니다.
#### 일반 digest와 BCrypt
```java
import com.kri.common.feature.crypto.hash.AdaptiveHashService;
import com.kri.common.feature.crypto.hash.DigestAlgorithm;
import com.kri.common.feature.crypto.hash.DigestEncoding;
import com.kri.common.feature.crypto.hash.DigestService;
String checksum = digestService.digest(
bytes,
DigestAlgorithm.SHA_256,
DigestEncoding.HEX_LOWER
);
String encodedSecret = adaptiveHashService.hash("secret-value");
boolean matched = adaptiveHashService.matches("secret-value", encodedSecret);
```
`DigestService`는 MD5, SHA-1, SHA-256, SHA-512와 HEX 소문자/대문자, Base64 출력을 지원합니다.
MD5와 SHA-1 enum 이름은 각각 `MD5_LEGACY`, `SHA_1_LEGACY`이며 기존 데이터 검증과
연동에만 사용해야 합니다. `AdaptiveHashService`는 BCrypt 기반이며 비밀번호뿐 아니라 PIN,
복구 코드, API Secret 같은 짧은 비밀값 검증에 사용할 수 있습니다. BCrypt 결과에는 salt가
포함되며 일반적인 구현의 72바이트 입력 제한을 고려해야 합니다.
### JSON
#### `JsonUtil`
@@ -497,6 +568,19 @@ kri:
jpa:
show-sql: false
format-sql: false
crypto:
aes:
active-key-id: "key-2026"
keys:
key-2026: "replace-with-a-service-master-key"
algorithm: AES_256_GCM
tag-layout: APPENDED
kdf:
iterations: 600000
salt-length: 16
hash:
bcrypt:
strength: 12
security:
enabled: true
allowed-ips:
@@ -532,6 +616,20 @@ kri:
운영 서비스에서는 JWT secret, API Key DB 접속 정보, Swagger/API Key admin 허용 IP를 반드시 서비스 환경에 맞게 override해야 합니다.
### `kri.crypto`
- `aes.active-key-id`: 직접 master key를 전달하지 않았을 때 사용할 key ID
- `aes.keys`: key ID별 master key. 복호화 호환을 위해 교체 전 key도 필요한 기간 동안 유지
- `aes.algorithm`: 기본값 `AES_256_GCM`
- `aes.tag-layout`: 기본값 `APPENDED`
- `aes.kdf.iterations`: PBKDF2 반복 횟수, 기본값 `600000`
- `aes.kdf.salt-length`: 자동 생성 salt 길이, 기본값 `16`
- `hash.bcrypt.strength`: 기본 BCrypt cost, 기본값 `12`, 허용 범위 `4..31`
`kri.crypto.enabled` 설정은 없습니다. Crypto API Bean은 항상 자동 구성되며, YML 키가 없어도
호출 시 master key를 직접 전달할 수 있습니다. 설정과 호출 양쪽에 키가 있으면 직접 전달한 키가
우선합니다. master key를 소스에 커밋하거나 로그와 예외에 출력하지 마십시오.
### `kri.auth.jwt`
관련 클래스:
@@ -753,6 +851,7 @@ Endpoint:
- `com.kri.common.autoconfigure.swagger.KriSwaggerAutoConfiguration`
- `com.kri.common.autoconfigure.redis.CommonRedisAutoConfiguration`
- `com.kri.common.autoconfigure.scheduling.CommonSchedulingAutoConfiguration`
- `com.kri.common.autoconfigure.crypto.CryptoAutoConfiguration`
---
@@ -761,6 +860,7 @@ Endpoint:
- 서비스 코드에서는 가능한 한 `feature` 패키지의 타입만 직접 사용합니다.
- `runtime` 패키지는 자동 구성으로 조립되는 내부 구현으로 보고 직접 의존을 피합니다.
- 운영 환경에서는 기본 JWT secret과 API Key DB 설정을 사용하지 않습니다.
- AES 신규 데이터는 GCM을 사용하고, MD5·SHA-1·AES-CBC는 레거시 호환 범위로 제한합니다.
- 자체 보안 정책이 필요한 서비스는 직접 `SecurityFilterChain` Bean을 등록해 기본 구성을 대체합니다.
- Swagger 접근 제한은 운영망/관리망 정책에 맞춰 `allowed-ips`를 명시합니다.
- 대용량 Excel은 일반 `Workbook` 변환보다 streaming API를 우선 검토합니다.