HKDF Key Derivation

카테고리: 키 파생 · 노드 타입 ID: kdf-hkdf

HMAC 기반 추출·확장 키 유도 (RFC 5869)

개요

RFC 5869 표준 HKDF(HMAC-based Extract-and-Expand Key Derivation Function)를 사용하여 고엔트로피 입력 키 물질(IKM)로부터 암호학적으로 강건한 하나 이상의 키 바이트열을 파생한다.

1단계 Extract($\text{PRK} = \text{HMAC-Hash}(\text{salt}, \text{IKM})$)로 엔트로피를 집중시킨 뒤, 2단계 Expand로 컨텍스트 정보(Info)를 바인딩해 최대 $255 \times \text{HashLen}$바이트의 출력 키 물질(OKM)을 생성한다.

사용 시점

ECDH Key Agreement, X25519 Key Exchange (ECDH), 또는 ML-KEM Encapsulate가 생성한 원시 공유 비밀(Shared Secret)을 실제 세션 대칭키와 IV로 변환할 때 사용한다.
하나의 마스터 시드에서 프로토콜 레이블(Info)만 달리하여 여러 개의 독립된 서브키를 파생할 때 사용한다.

파라미터 설정

파라미터 (ID)	타입 및 기본값	노출 조건	설명 및 옵션
출력 길이 (바이트) `keyLength`	`number` 기본값: `32` 변수 참조 지원 (`$var`: `int`)	항상 노출	이 노드의 출력 길이 (바이트) 설정을 지정한다.
해시 알고리즘 `hashAlgorithm`	`select` 기본값: `SHA-256`	항상 노출	이 노드의 해시 알고리즘 설정을 지정한다. `SHA-256`: SHA-256 `SHA-512`: SHA-512

포트 입출력 명세

포트 연결 규칙, 데이터 타입별 색상, 가변 포트 생성 방식은 포트 및 연결 문서를 참고한다.

입력 포트

포트 성격: 고정 입력 포트 (총 3개).

포트 이름	포트 ID	데이터 타입	필수 여부	노출 조건	설명
`Input Keying Material`	`ikm`	`Bytes`	필수	항상 노출	입력 키 물질(Input Keying Material, `Uint8Array`, 최소 1바이트 이상)이다.
`Salt`	`salt`	`Bytes`	선택	항상 노출	선택적 솔트(`Uint8Array`). 연결하지 않거나 비어 있으면 RFC 5869 규격에 따라 해시 길이만큼의 0 바이트열을 기본 솔트로 사용한다.
`Context Info`	`info`	`Bytes`	선택	항상 노출	선택적 컨텍스트 및 애플리케이션 식별 정보(`Uint8Array`). 도메인 분리(Domain Separation)를 위해 사용한다.

출력 포트

포트 성격: 고정 출력 포트 (총 1개).

포트 이름	포트 ID	데이터 타입	노출 조건	설명
`Output Key`	`okm`	`Bytes` (OKM)	항상 노출	파생된 출력 키 물질(Output Keying Material, `Uint8Array`)이다.

오류 케이스

실행 중 아래 조건이 발생하면 이 노드는 ERROR 상태가 되며, 출력 포트에 연결된 하위 노드는 실행되지 않는다.

오류 코드	기본 엔진 메시지	발생 조건
`INVALID_KDF_PARAMS`	KDF 파라미터가 올바르지 않는다	`IKM (Input Key)`이 비어 있거나 요청한 출력 길이가 `1` 미만 또는 $255 \times \text{HashLen}$을 초과할 때 발생한다.

활용 예시

X25519 공유 비밀에서 AES-256-GCM 세션 키 파생하기

ECDH 출력에 HKDF-SHA256을 적용하여 32바이트 대칭키를 얻는다.

X25519 Key Exchange (ECDH)의 Shared Secret 출력을 HKDF Key Derivation의 IKM (Input Key)에 연결한다.
출력 키 길이를 32로 설정하고 OKM (Derived Key)을 AES Encrypt에 연결한다.