AES Decrypt

카테고리: 대칭키 암호 · 노드 타입 ID: symmetric-aes-decrypt

NIST AES(128/192/256비트)로 암호문을 복호화한다

개요

NIST FIPS 197 AES(128/192/256비트)로 암호화된 암호문을 복호화하고, AEAD 모드(GCM, CCM)나 키 래핑 모드(KW)에서는 무결성 인증 태그를 함께 검증한다.

AEAD 및 KW 모드에서는 인증 태그 검증이 통과하기 전까지 복호화된 평문을 절대 방출하지 않으며, 태그가 1비트라도 불일치하면 즉시 AUTH_TAG_MISMATCH 오류를 발생시킨다.

사용 시점

AES Encrypt 또는 외부 표준 AES 구현체가 생성한 암호문을 복호화하고 무결성을 검증할 때 사용한다.

파라미터 설정

파라미터 (ID)	타입 및 기본값	노출 조건	설명 및 옵션
암호 운영 모드 `mode`	`select` 기본값: `ECB`	항상 노출	암호화 시 사용한 것과 동일한 운용 모드를 선택한다. 블록 암호 운용 모드를 참고한다. `ECB`: ECB (Electronic Codebook) `CBC`: CBC (Cipher Block Chaining) `GCM`: GCM (AEAD) `CCM`: CCM (AEAD) `CTR`: CTR (Counter Mode) `CFB`: CFB (Cipher Feedback) `OFB`: OFB (Output Feedback) `XTS`: XTS (Tweakable) `KW`: KW (Key Wrap)
패딩 (CBC/ECB) `padding`	`select` 기본값: `None`	항상 노출	`ECB` 및 `CBC` 모드에서 복호화 후 검증·제거할 블록 패딩 방식이다. 패딩 스킴을 참고한다. `None`: 없음 `ISO7816`: ISO/IEC 9797-1 방법 2 (ISO/IEC 7816-4) `ISO97971M3`: ISO/IEC 9797-1 방법 3 `PKCS7`: PKCS#7 (RFC 5652) `ANSIX923`: ANSI X9.23
오류 단일화 `errorUnify`	`boolean` 기본값: `false` 변수 참조 지원 (`$var`: `bool`)	항상 노출	활성화하면 패딩 오류나 태그 불일치 등을 단일 사용자 정의 오류 코드·메시지로 통합한다(패딩 오라클 방지 시뮬레이션 등에 유용).
단일화 오류 코드 `errorUnifyCode`	`text` 기본값: `""` (비움) 변수 참조 지원 (`$var`: `string`)	`errorUnify`가 `true` 일 때	오류 통합 활성화 시 사용할 오류 코드이다.
단일화 오류 메시지 `errorUnifyMessage`	`text` 기본값: `""` (비움) 변수 참조 지원 (`$var`: `string`)	`errorUnify`가 `true` 일 때	오류 통합 활성화 시 사용할 오류 메시지이다.

포트 입출력 명세

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

입력 포트

포트 성격: 고정 입력 포트 (총 6개; 조건부 노출 포트는 아래 표와 같이 파라미터 설정에 따라 전환됨).

포트 이름	포트 ID	데이터 타입	필수 여부	노출 조건	설명
`Key`	`key`	`Bytes` (16/24/32B)	필수	항상 노출	암호화에 사용된 대칭키 바이트 배열(일반 모드 16/24/32바이트, `XTS` 모드 32/64바이트)이다.
`Ciphertext`	`ciphertext`	`Bytes`	필수	항상 노출	복호화할 암호문 바이트 배열(`Uint8Array`)이다.
`IV`	`iv`	`Bytes` (16B)	선택	`mode`가 `CBC` 또는 `CTR` 또는 `CFB` 또는 `OFB` 또는 `XTS` 일 때	암호화에 사용된 16바이트 초기화 벡터(`CBC`, `CFB`, `OFB`, `CTR`, `XTS`)이다.
`Nonce`	`nonce`	`Bytes` (12B)	선택	`mode`가 `GCM` 또는 `CCM` 일 때	`GCM`/`CCM` 모드에서 암호화에 사용된 12바이트 Nonce이다.
`Auth Tag`	`tag`	`Bytes` (GCM/CCM)	선택	`mode`가 `GCM` 또는 `CCM` 일 때	`GCM`/`CCM` 모드에서 검증할 16바이트 `Auth Tag` 입력이다(필수).
`AAD`	`aad`	`Bytes` (GCM/CCM)	선택	`mode`가 `GCM` 또는 `CCM` 일 때	`GCM`/`CCM` 모드에서 암호화 시 사용한 것과 정확히 동일한 추가 인증 데이터(AAD)이다.

출력 포트

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

포트 이름	포트 ID	데이터 타입	노출 조건	설명
`Plaintext`	`plaintext`	`Bytes`	항상 노출	복호화 및 패딩 제거·인증 검증이 완료된 원본 평문 바이트 배열(`Uint8Array`)이다.

오류 케이스

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

오류 코드	기본 엔진 메시지	발생 조건
`INVALID_KEY_LENGTH`	키 길이가 올바르지 않는다	`Key` 길이가 선택한 모드(일반 16/24/32B, XTS 32/64B)와 맞지 않을 때 발생한다.
`INVALID_IV_LENGTH`	IV 길이가 올바르지 않는다	연결된 `IV`가 16바이트가 아닐 때 발생한다.
`INVALID_NONCE_LENGTH`	Nonce 길이가 올바르지 않는다	연결된 `Nonce`가 12바이트가 아닐 때 발생한다.
`INVALID_TAG_LENGTH`	인증 태그 길이가 올바르지 않는다	`GCM`/`CCM` 모드에서 연결된 `Auth Tag`가 16바이트가 아닐 때 발생한다.
`AUTH_TAG_MISMATCH`	인증 태그가 일치하지 않는다	`GCM`/`CCM` 인증 태그 검증 또는 `KW` 무결성 초기값(`A6A6A6A6A6A6A6A6`) 검증에 실패했을 때 발생한다.
`CIPHERTEXT_NOT_BLOCK_ALIGNED`	암호문 길이가 블록 크기의 배수가 아니다	`ECB`/`CBC` 모드에서 암호문 길이가 16바이트의 양의 배수가 아니거나 `KW` 모드에서 8바이트의 배수(최소 24바이트)가 아닐 때 발생한다.
`INVALID_PADDING`	패딩이 올바르지 않는다	`ECB`/`CBC` 모드에서 복호화된 블록의 패딩 바이트가 선택한 패딩 규격과 맞지 않을 때 발생한다.
`DATA_TOO_SHORT`	데이터 길이가 너무 짧다	입력 데이터가 해당 모드가 요구하는 최소 바이트 길이(예: XTS 또는 Key Wrap에서 16B)보다 짧을 때 발생한다.

활용 예시

AES-256-GCM 암호문 검증 및 복호화하기

암호문과 16바이트 Auth Tag를 검증하여 원본 평문을 복원한다.

AES Decrypt의 운용 모드를 GCM으로 설정한다.
암호화 때와 동일한 Key, Nonce, AAD와 함께 Ciphertext 및 Auth Tag를 연결하면 검증 후 Plaintext가 출력된다.