ChaCha20-Poly1305 Encrypt

카테고리: 대칭키 암호 · 노드 타입 ID: symmetric-chacha20-poly1305-encrypt

RFC 8439 부가 데이터 인증 암호화 (AEAD)

개요

IETF RFC 8439 표준 ChaCha20-Poly1305 인증 암호화(AEAD) 구조로 임의 길이의 평문을 암호화하고 16바이트 인증 태그를 계산한다.

Daniel J. Bernstein의 20라운드 ChaCha20 ARX 스트림 암호(32바이트 키, 12바이트 IETF Nonce, 블록 카운터 1부터 평문 암호화)와 블록 카운터 0에서 파생한 일회용 키로 동작하는 Poly1305 MAC을 결합한다. 32비트 덧셈·XOR·비트 회전만 사용하므로 전용 AES 하드웨어 가속이 없는 환경에서도 빠른 속도와 상수 시간(Constant-time) 부채널 내성을 제공한다.

사용 시점

TLS 1.3, WireGuard, SSH, QUIC, 모바일·임베디드 메시징 등 소프트웨어 상수 시간 AEAD가 선호되는 최신 프로토콜에서 메시지를 암호화할 때 사용한다.
RFC 8439 §2.8.2 AEAD 테스트 벡터를 검증할 때 사용한다.

파라미터 설정

파라미터 (ID)	타입 및 기본값	노출 조건	설명 및 옵션
오류 단일화 `errorUnify`	`boolean` 기본값: `false` 변수 참조 지원 (`$var`: `bool`)	항상 노출	활성화하면 내장 오류를 지정한 단일 오류 코드·메시지로 대체한다.
단일화 오류 코드 `errorUnifyCode`	`text` 기본값: `""` (비움) 변수 참조 지원 (`$var`: `string`)	`errorUnify`가 `true` 일 때	오류 통합 활성화 시 사용할 오류 코드이다.
단일화 오류 메시지 `errorUnifyMessage`	`text` 기본값: `""` (비움) 변수 참조 지원 (`$var`: `string`)	`errorUnify`가 `true` 일 때	오류 통합 활성화 시 사용할 오류 메시지이다.

포트 입출력 명세

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

입력 포트

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

포트 이름	포트 ID	데이터 타입	필수 여부	노출 조건	설명
`Key`	`key`	`Bytes` (32B)	필수	항상 노출	32바이트(256비트) ChaCha20-Poly1305 비밀 키이다.
`Plaintext`	`plaintext`	`Bytes`	필수	항상 노출	암호화할 임의 길이의 평문 바이트 배열(`Uint8Array`, 블록 패딩 불필요)이다.
`Nonce`	`nonce`	`Bytes` (12B)	선택	항상 노출	12바이트(96비트) IETF Nonce이다. 연결하지 않으면 12바이트 `0x00`으로 기본 동작한다(실무에서는 동일한 키로 Nonce를 절대 재사용해서는 안 된다).
`AAD`	`aad`	`Bytes`	선택	항상 노출	암호화되지 않고 Poly1305 MAC으로 함께 인증할 선택적 추가 인증 데이터(AAD, `Uint8Array`)이다.

출력 포트

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

포트 이름	포트 ID	데이터 타입	노출 조건	설명
`Ciphertext`	`ciphertext`	`Bytes`	항상 노출	암호화된 바이트 배열(`Plaintext`와 바이트 길이가 정확히 동일)이다.
`Auth Tag`	`tag`	`Bytes` (16B)	항상 노출	16바이트(128비트) Poly1305 인증 태그이다.

오류 케이스

실행 중 아래 조건이 발생하면 이 노드는 ERROR 상태가 되며, 출력 포트에 연결된 하위 노드는 실행되지 않는다. 오류 통합(errorUnify)을 활성화하면 아래의 모든 오류 코드가 사용자가 지정한 단일 오류 코드와 메시지로 대체된다.

오류 코드	기본 엔진 메시지	발생 조건
`INVALID_KEY_LENGTH`	키 길이가 올바르지 않는다	`Key`가 정확히 32바이트가 아닐 때 발생한다.
`INVALID_NONCE_LENGTH`	Nonce 길이가 올바르지 않는다	연결된 `Nonce`가 정확히 12바이트가 아닐 때 발생한다.

활용 예시

ChaCha20-Poly1305로 인증 암호화 수행하기

32바이트 키와 12바이트 Nonce로 메시지를 암호화하고 16바이트 태그를 얻는다.

32바이트 Key, 12바이트 Nonce, 평문 Plaintext(및 선택적 AAD)를 ChaCha20-Poly1305 Encrypt에 연결하면 Ciphertext와 16바이트 Auth Tag가 출력된다.