init

README.md

@@ -0,0 +1,208 @@
+# Gerbera
+
+배열을 중심으로 직접 설계한 교육용 파일 암호화/복호화 CLI입니다.
+
+## 빌드와 사용
+
+macOS 또는 Linux에서는 `make` 없이 다음 스크립트로 빌드합니다.
+
+```sh
+./scripts/build.sh
+./build/gerbera encrypt 원본.txt 원본.gerbera '비밀번호'
+./build/gerbera decrypt 원본.gerbera 복원.txt '비밀번호'
+```
+
+Windows에서는 Developer Command Prompt 또는 GCC/Clang이 설정된 터미널에서
+다음 명령을 사용합니다.
+
+```bat
+scripts\build.bat
+build\gerbera.exe encrypt original.txt original.gerbera password
+build\gerbera.exe decrypt original.gerbera restored.txt password
+```
+
+스크립트 없이 직접 빌드하려면 다음 명령도 사용할 수 있습니다.
+
+```sh
+cc -Iinclude -std=c11 -O2 src/*.c -o build/gerbera
+```
+
+기존 `make`와 `make test`도 선택적으로 계속 사용할 수 있습니다.
+
+## 프로젝트 구조
+
+```text
+Gerbera/
+├── src/                 # 암호화, 복호화, 알고리즘, CLI 소스
+├── include/gerbera.h    # 공통 상수, 자료형, 함수 선언
+├── scripts/             # make가 필요 없는 빌드 스크립트
+├── tests/test.sh        # 암복호화 자동 테스트
+├── build/               # 실행 파일과 오브젝트 파일
+├── Makefile
+└── README.md
+```
+
+`make clean`을 실행하면 생성물만 담긴 `build/` 디렉터리가 정리됩니다.
+
+## 난수 생성
+
+nonce에는 `rand()`를 사용합니다.
+운영체제 난수를 사용하면 더 좋겠지만 ~~코드가 복잡해집니다.~~ ~~이건 수행평가에요~~
+
+## 배열이 쓰이는 부분
+
+- `state[256]`: 바이트 순열 기반 키 스트림 상태
+- `key[32]`: 비밀번호와 nonce에서 만든 내부 키
+- `nonce[16]`: 같은 파일/비밀번호라도 결과를 다르게 만드는 난수
+- `buffer[4096]`: 큰 파일을 일정 크기로 나누어 처리
+- `tag[16]`: 잘못된 비밀번호와 파일 손상을 검사
+
+파일 형식은 `MIZUKI🎀(10) + nonce(16) + 원본 크기(8) + 암호문 + tag(16)`입니다.
+magic의 실제 바이트 배열은 다음과 같습니다.
+
+```c
+{'M', 'I', 'Z', 'U', 'K', 'I', 0xF0, 0x9F, 0x8E, 0x80}
+```
+
+## Gerbera-1 알고리즘 설계
+
+Gerbera-1은 비밀번호로부터 만든 키 배열과 0부터 255까지의 값을 담은 상태 배열을
+계속 섞어 키 스트림을 만들고, 이를 파일 데이터와 XOR하는 방식입니다.
+
+### 기호 정의
+
+- `P[p]`: 비밀번호의 `p`번째 바이트
+- `N[n]`: 16바이트 난수 nonce의 `n`번째 바이트
+- `K[k]`: 32바이트 키 배열
+- `S[s]`: 256바이트 상태 배열
+- `ROTL8(x, q)`: 8비트 값 `x`를 왼쪽으로 `q`비트 순환 이동
+- `⊕`: 비트 단위 XOR
+
+8비트 순환 이동은 다음과 같이 계산합니다.
+
+```text
+ROTL8(x, q) = ((x << q) | (x >> (8 - q))) mod 256
+```
+
+단, `q = 0`이면 결과는 그대로 `x`입니다.
+
+### 1. 비밀번호에서 키 배열 생성
+
+먼저 고정된 32바이트 초기 배열을 `K`에 복사합니다. 암호화 키와 인증 키가
+같아지지 않도록 첫 번째 원소에 용도 구분 값 `D`를 XOR합니다.
+
+```text
+K[0] = K[0] ⊕ D
+D = 0x43  (암호화용)
+D = 0x41  (인증용)
+```
+
+그다음 `r = 0 ... 8191`의 8192라운드 동안 비밀번호의 모든 바이트를 순회합니다.
+
+```text
+a = (p + r) mod 32
+b = (a + 11) mod 32
+c = (a + 23) mod 32
+
+m = K[b] + P[p] + N[(p + r) mod 16] + r
+
+K[a] = ROTL8(K[a] ⊕ m, K[c] mod 8) + K[c]
+```
+
+각 라운드가 끝날 때 키 배열의 멀리 떨어진 두 원소를 한 번 더 섞습니다.
+
+```text
+K[r mod 32] = K[r mod 32]
+              ⊕ ROTL8(K[(r + 17) mod 32], r mod 8)
+```
+
+따라서 같은 비밀번호를 사용해도 파일마다 무작위로 생성되는 `N`이 다르면
+최종 키 배열도 달라집니다.
+
+### 2. 256바이트 상태 배열 초기화
+
+상태 배열은 먼저 `S[n] = n`으로 초기화합니다. 이후 1024회 반복하면서 키와
+nonce를 이용해 원소의 위치를 교환합니다.
+
+```text
+S[n] = n,  0 ≤ n < 256
+j = 0
+
+for n = 0 ... 1023:
+    i = n mod 256
+    j = j + S[i] + K[n mod 32] + N[n mod 16]
+    swap(S[i], S[j])
+```
+
+모든 계산이 바이트 단위이므로 `j` 역시 자동으로 `mod 256`이 적용됩니다.
+
+### 3. 키 스트림 생성과 암호화
+
+파일의 각 바이트 위치 `t`마다 상태 배열을 다시 섞고 키 스트림 바이트 `Z[t]`를
+계산합니다.
+
+```text
+i = i + 1
+j = j + S[i] + K[t mod 32]
+swap(S[i], S[j])
+
+u    = S[(S[i] + S[j]) mod 256]
+Z[t] = u ⊕ ROTL8(K[(t + u) mod 32], t mod 8)
+```
+
+평문 바이트 `M[t]`와 키 스트림을 XOR하면 암호문 `C[t]`가 됩니다.
+
+```text
+C[t] = M[t] ⊕ Z[t]
+```
+
+XOR에는 `x ⊕ y ⊕ y = x`라는 성질이 있으므로 복호화도 같은 수식입니다.
+
+```text
+M[t] = C[t] ⊕ Z[t]
+```
+
+즉, 암호화와 복호화는 같은 키 스트림 생성 함수를 사용하고 입력 데이터만
+다릅니다. 파일 전체를 메모리에 올리지 않고 `buffer[4096]` 단위로 처리하지만,
+상태 배열과 현재 위치 `t`를 유지하므로 하나의 연속된 키 스트림이 만들어집니다.
+
+### 4. 인증 태그 계산
+
+비밀번호 오류나 파일 변조를 찾기 위해 헤더와 암호문의 각 바이트 `x`를 별도의
+32바이트 인증 상태 배열 `A`에 누적합니다. 현재까지 처리한 길이를 `L`이라 하면:
+
+```text
+a = L mod 32
+b = (a + 7) mod 32
+c = (a + 19) mod 32
+
+A[a] = ROTL8(A[a] ⊕ x ⊕ A[c], A[b] mod 8) + A[b] + a
+A[c] = A[c] ⊕ ROTL8(x + A[a], a mod 8)
+L    = L + 1
+```
+
+모든 데이터를 처리한 뒤 길이 `L`을 8바이트 little-endian 배열로 만들어 같은
+방식으로 누적합니다. 그 후 256회의 최종 혼합을 수행합니다.
+
+```text
+for n = 0 ... 255:
+    v = A[(n + 1) mod 32] + A[(n + 13) mod 32] + n
+    A[n mod 32] = A[n mod 32] ⊕ ROTL8(v, n mod 8)
+```
+
+마지막 16바이트 인증 태그는 배열의 앞쪽과 뒤쪽을 XOR하여 얻습니다.
+
+```text
+TAG[n] = A[n] ⊕ A[n + 16],  0 ≤ n < 16
+```
+
+복호화할 때는 평문을 출력하기 전에 암호문으로 태그를 다시 계산합니다. 저장된
+태그와 계산한 태그가 다르면 잘못된 비밀번호 또는 손상된 파일로 판단하여 출력을
+만들지 않습니다.
+
+### 전체 처리 과정
+
+```text
+암호화: 파일 → 키 스트림 생성 → 원본 바이트 XOR → 암호문 + TAG
+복호화: 암호문 → TAG 검증 → 같은 키 스트림 XOR → 원본 파일
+```