NodeCrypto 도움말

AES Encrypt

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

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

개요

NIST FIPS 197 표준 AES(Advanced Encryption Standard, Rijndael) 128비트 블록 암호를 사용하여 평문을 암호화한다. 연결된 Key의 바이트 길이(16, 24, 32바이트)에 따라 각각 AES-128(10라운드), AES-192(12라운드), AES-256(14라운드)으로 자동 전환된다.

9가지 표준 운용 모드(기밀성 전용 ECB, CBC, CFB, OFB, CTR, XTS, 인증 암호화 AEAD GCM, CCM, 키 래핑 KW)를 모두 지원한다. 선택한 운용 모드(Cipher Mode)에 맞춰 필요한 입력 포트(IV, Nonce, AAD)와 출력 포트(Auth Tag)가 동적으로 전환된다. 각 모드의 상세 동작은 블록 암호 운용 모드를 참고한다.

사용 시점

파라미터 설정

파라미터 (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 모드에서 암호화 전에 평문에 적용할 블록 패딩 방식이다(스트림·AEAD·XTS·KW 모드에서는 숨겨짐). 패딩 스킴을 참고한다.
오류 단일화
errorUnify		 boolean
기본값: false
변수 참조 지원 ($var: bool)		 항상 노출 활성화하면 모든 내장 암호화 오류를 지정한 단일 오류 코드·메시지로 대체한다.
단일화 오류 코드
errorUnifyCode		 text
기본값: "" (비움)
변수 참조 지원 ($var: string)		 errorUnify가 true 일 때 오류 통합 활성화 시 사용할 오류 코드이다.
단일화 오류 메시지
errorUnifyMessage		 text
기본값: "" (비움)
변수 참조 지원 ($var: string)		 errorUnify가 true 일 때 오류 통합 활성화 시 사용할 오류 메시지이다.

포트 입출력 명세

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

입력 포트

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

포트 이름포트 ID데이터 타입필수 여부노출 조건설명
Key key Bytes (16/24/32B) 필수 항상 노출 대칭 암호화 키 바이트 배열(Uint8Array). 일반 모드는 16바이트(AES-128), 24바이트(AES-192), 32바이트(AES-256)를 받으며, XTS 모드는 결합된 2개의 키인 32바이트(AES-128-XTS) 또는 64바이트(AES-256-XTS)를 받는다.
Plaintext plaintext Bytes 필수 항상 노출 암호화할 원시 평문 바이트 배열(Uint8Array)이다. XTS 모드에서는 최소 16바이트 이상이어야 하며, KW 모드에서는 8바이트의 배수(최소 16바이트 이상)인 래핑 대상 키 데이터여야 한다.
IV iv Bytes (16B) 선택 mode가 CBC 또는 CTR 또는 CFB 또는 OFB 또는 XTS 일 때 16바이트(128비트) 초기화 벡터(CBC, CFB, OFB, CTR 카운터 블록, XTS 트윅). 연결하지 않으면 16바이트 0x00으로 기본 동작한다.
Nonce nonce Bytes (12B) 선택 mode가 GCM 또는 CCM 일 때 AEAD 모드(GCM, CCM)용 12바이트(96비트) Nonce이다. 연결하지 않으면 12바이트 0x00으로 기본 동작한다(실무에서는 동일한 키로 Nonce를 절대 재사용하지 말아야 한다).
AAD aad Bytes (GCM/CCM only) 선택 mode가 GCM 또는 CCM 일 때 AEAD 모드(GCM, CCM)용 선택적 추가 인증 데이터(Additional Authenticated Data)이다. 암호화되지는 않지만 Auth Tag 무결성 계산에 포함된다.

출력 포트

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

포트 이름포트 ID데이터 타입노출 조건설명
Ciphertext ciphertext Bytes 항상 노출 생성된 암호문 바이트 배열(Uint8Array)이다(KW 모드에서는 입력보다 8바이트 긴 래핑된 키 출력).
Auth Tag tag Bytes (GCM/CCM) mode가 GCM 또는 CCM 일 때 AEAD 모드(GCM, CCM)에서 생성된 16바이트(128비트) 인증 태그(Authentication Tag)이다.

오류 케이스

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

오류 코드기본 엔진 메시지발생 조건
INVALID_KEY_LENGTH 키 길이가 올바르지 않는다 Key 길이가 유효하지 않을 때(일반 모드는 16/24/32바이트가 아닐 때, XTS 모드는 32/64바이트가 아닐 때) 발생한다.
INVALID_IV_LENGTH IV 길이가 올바르지 않는다 CBC/CFB/OFB/CTR/XTS에서 연결된 IV가 16바이트가 아닐 때 발생한다.
INVALID_NONCE_LENGTH Nonce 길이가 올바르지 않는다 GCM/CCM에서 연결된 Nonce가 12바이트가 아닐 때 발생한다.
PLAINTEXT_NOT_BLOCK_ALIGNED NoPad 모드에서는 평문 길이가 블록 크기의 배수여야 한다 ECB/CBC 모드에서 Padding = None인데 평문 길이가 16바이트의 양의 배수가 아니거나, KW 모드에서 입력이 8바이트의 배수가 아닐 때 발생한다.
DATA_TOO_SHORT 데이터 길이가 너무 짧다 XTS 또는 KW 모드에서 평문 길이가 최소 요구 길이(16바이트)보다 짧을 때 발생한다.

활용 예시

AES-256-GCM 인증 암호화(AEAD) 수행하기

32바이트 키와 12바이트 Nonce로 평문을 암호화하고 16바이트 인증 태그를 얻는다.

  1. AES Encrypt의 운용 모드를 GCM으로 설정한다.
  2. 32바이트 Key, 12바이트 Nonce, 평문 Plaintext(및 선택적 AAD)를 연결한다.
  3. Ciphertext와 16바이트 Auth Tag 출력을 Output Inspector나 AES Decrypt로 연결한다.

AES-128-CBC + PKCS#7 블록 암호화 수행하기

16바이트 키와 16바이트 IV로 가변 길이 평문을 CBC 모드로 암호화한다.

  1. 운용 모드를 CBC, 패딩을 PKCS7로 설정한다.
  2. 16바이트 Key, 16바이트 IV, 평문 Plaintext를 연결하면 16바이트 배수로 패딩·암호화된 Ciphertext가 출력된다.