SM4 Encrypt

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

중국 국가표준 SM4 128비트 블록 암호 (GB/T 32907 / GM/T 0002)

개요

중국 국가표준(GB/T 32907-2016, GM/T 0002-2012) 및 ISO/IEC 18033-3으로 제정된 32라운드 불균형 파이스텔 128비트 블록 암호 SM4로 평문을 암호화한다.

항상 16바이트(128비트) 키와 16바이트(128비트) 블록을 사용하며, ECB, CBC, CFB, OFB, CTR, GCM, CCM 모드를 지원한다.

TLS 1.3(RFC 8998 TLS_SM4_GCM_SM3), 중국 상용 암호(ShangMi) 호환 시스템, 또는 GB/T 32907 테스트 벡터를 구현·검증할 때 사용한다.

파라미터 (ID)	타입 및 기본값	노출 조건	설명 및 옵션
암호 운영 모드 `mode`	`select` 기본값: `ECB`	항상 노출	128비트 블록 운용 모드(`ECB`, `CBC`, `CFB`, `OFB`, `CTR`, `GCM`, `CCM`)이다. 자세한 내용은 블록 암호 운용 모드를 참고한다. `ECB`: ECB (Electronic Codebook) `CBC`: CBC (Cipher Block Chaining) `GCM`: GCM (AEAD) `CTR`: CTR (Counter Mode)
패딩 `padding`	`select` 기본값: `None`	항상 노출	`ECB`/`CBC` 모드에서 적용할 16바이트 블록 패딩 방식이다. 자세한 내용은 패딩 스킴을 참고한다. `None`: 없음 `Zero`: ISO/IEC 9797-1 방법 1 (제로 패딩) `ISO7816`: ISO/IEC 9797-1 방법 2 (ISO/IEC 7816-4) `ISO97971M3`: ISO/IEC 9797-1 방법 3 `PKCS7`: PKCS#7 (RFC 5652) `NIST80038B`: NIST SP 800-38B `ANSIX923`: ANSI X9.23
오류 단일화 `errorUnify`	`boolean` 기본값: `false` 변수 참조 지원 (`$var`: `bool`)	항상 노출	활성화하면 내장 오류를 지정한 단일 오류 코드·메시지로 대체한다.
단일화 오류 코드 `errorUnifyCode`	`text` 기본값: `""` (비움) 변수 참조 지원 (`$var`: `string`)	`errorUnify`가 `true` 일 때	오류 통합 활성화 시 사용할 오류 코드이다.
단일화 오류 메시지 `errorUnifyMessage`	`text` 기본값: `""` (비움) 변수 참조 지원 (`$var`: `string`)	`errorUnify`가 `true` 일 때	오류 통합 활성화 시 사용할 오류 메시지이다.

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

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

포트 이름	포트 ID	데이터 타입	필수 여부	노출 조건	설명
`Key`	`key`	`Bytes` (16B)	필수	항상 노출	16바이트(128비트) SM4 비밀 키이다.
`Plaintext`	`plaintext`	`Bytes`	필수	항상 노출	암호화할 평문 바이트 배열(`Uint8Array`)이다.
`IV`	`iv`	`Bytes` (16B)	선택	`mode`가 `CBC` 또는 `CTR` 일 때	16바이트 초기화 벡터(`CBC`, `CFB`, `OFB`, `CTR`)이다.
`Nonce`	`nonce`	`Bytes` (12B)	선택	`mode`가 `GCM` 일 때	12바이트 AEAD Nonce(`GCM`, `CCM`)이다.
`AAD`	`aad`	`Bytes` (GCM only)	선택	`mode`가 `GCM` 일 때	`GCM`/`CCM` 모드용 선택적 추가 인증 데이터(AAD)이다.

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

포트 이름	포트 ID	데이터 타입	노출 조건	설명
`Ciphertext`	`ciphertext`	`Bytes`	항상 노출	암호화된 바이트 배열(`Uint8Array`)이다.
`Auth Tag`	`tag`	`Bytes` (GCM)	`mode`가 `GCM` 일 때	`GCM`/`CCM` 모드에서 생성된 16바이트 인증 태그이다.

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

오류 코드	기본 엔진 메시지	발생 조건
`INVALID_KEY_LENGTH`	키 길이가 올바르지 않는다	`Key`가 정확히 16바이트가 아닐 때 발생한다.
`INVALID_IV_LENGTH`	IV 길이가 올바르지 않는다	연결된 `IV`가 16바이트가 아니거나 `Nonce`가 12바이트가 아닐 때 발생한다.
`PLAINTEXT_NOT_BLOCK_ALIGNED`	NoPad 모드에서는 평문 길이가 블록 크기의 배수여야 한다	`ECB`/`CBC` 모드에서 `Padding = None`인데 평문 길이가 16바이트의 양의 배수가 아닐 때 발생한다.
`INVALID_NONCE_LENGTH`	Nonce 길이가 올바르지 않는다	연결된 AEAD 또는 스트림 암호 `Nonce`가 12바이트(96비트)가 아닐 때 발생한다.

16바이트 키와 12바이트 Nonce로 SM4-GCM 암호문과 태그를 생성한다.

SM4 Encrypt의 운용 모드를 GCM으로 설정하고 16바이트 Key, 12바이트 Nonce, Plaintext를 연결한다.