Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -125,6 +125,7 @@ jobs:
cd host
go test -run='^$' -fuzz=FuzzDecodeHeader -fuzztime=20s ./internal/wire/
go test -run='^$' -fuzz=FuzzDecodeBody -fuzztime=20s ./internal/wire/
go test -run='^$' -fuzz=FuzzDecoder -fuzztime=20s ./internal/tui/

host-windows:
env:
Expand Down
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,7 @@ The following features are also included.
- Key usage enforcement: the core rejects any operation outside the usage assigned at generation time (ENCRYPT, DECRYPT, SIGN, VERIFY, and so on).
- Core hardening: on startup the core disables core dumps, denies `ptrace`, sets `no_new_privs` and `umask 077`, scrubs environment variables, closes unneeded `fd`s, verifies the peer UID, and checks the root key file's permissions, owner, and links. On Linux, `mlockall` prevents memory from being swapped. On Windows (experimental since 1.1.0) the core restricts its own process object with a DACL, verifies the peer's user SID and protects files with owner-only DACLs.
- Strict protocol: fixed 16-byte header, length-prefixed fields, 1 MiB body limit, and rejection of trailing bytes. `HELLO` must come first, and any framing violation terminates the session.
- Terminal UI: `kmsctl ui` offers every `kmsctl` command in a full-screen interface on Linux, macOS and Windows, built on the Go standard library only. Fingerprints are always typed by the operator, and decrypted data only goes to new private files.
- Air-gapped build: Rust dependencies are vendored in `core/vendor` and built with `--frozen`. Go builds with `GOPROXY=off` and `-mod=vendor` and has no external dependencies.

## Build and run
Expand Down
5 changes: 3 additions & 2 deletions README_KR.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,15 +39,16 @@
- 키 용도 강제: 생성 시 지정한 용도(ENCRYPT, DECRYPT, SIGN, VERIFY 등) 외의 연산은 코어 측에서 거부합니다.
- 코어 하드닝: 시작 시 코어 덤프 차단, `ptrace` 거부, `no_new_privs`, `umask 077`, 환경 변수 제거, 불필요 `fd` 정리, 피어(peer) UID 검증, 루트 키 파일 권한·소유자·링크 검증을 수행합니다. Linux에서는 `mlockall`로 메모리 스와핑(swap)을 막습니다. Windows(1.1.0부터 experimental)에서는 코어가 자기 프로세스 객체를 DACL로 제한하고, 피어의 사용자 SID를 검증하며, 파일을 소유자 전용 DACL로 보호합니다.
- 엄격한 프로토콜: 고정 16바이트 헤더와 길이 접두 필드, 1MiB 본문 상한, 후행 바이트를 거부합니다. `HELLO` 선행을 강제하며 프레이밍(framing) 위반 시 세션을 끊어냅니다.
- 터미널 UI: `kmsctl ui`는 모든 `kmsctl` 명령을 Linux, macOS, Windows에서 전체 화면 인터페이스로 제공하며 Go 표준 라이브러리만으로 만들어졌습니다. 지문은 항상 운영자가 직접 입력하고, 복호화한 데이터는 새 비공개 파일로만 저장합니다.
- 폐쇄 빌드: Rust 의존성은 `core/vendor`에 벤더링되고 `--frozen`으로 빌드합니다. Go는 `GOPROXY=off`, `-mod=vendor`로 빌드하며 외부 의존성이 없습니다.

## 빌드 및 실행

이 내용에 관해서는 [USAGE_KR.md](USAGE_KR.md)를 확인할 수 있습니다.
이 내용에 관해서는 [USAGE.md](USAGE_KR.md)를 확인할 수 있습니다.

## 보안

취약점 신고 방법과 릴리즈 검증 방법은 [SECURITY_KR.md](SECURITY_KR.md)를 확인하세요.
취약점 신고 방법과 릴리즈 검증 방법은 [SECURITY.md](SECURITY_KR.md)를 확인하세요.

## 라이선스

Expand Down
9 changes: 9 additions & 0 deletions SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -128,6 +128,15 @@ Envelope layer:
- The core rejects every operation outside the usage assigned to a key. On every use, the host checks stored metadata and public keys against the values the core recomputes from the blob.
- Node start, key generation, encryption, decryption, member changes, sent and received envelopes, inbox decisions, card renewal and witness conflicts are written to the hash-chained audit log, and each entry is signed with the core's audit key.

## Terminal UI

- `kmsctl ui` calls the same node functions as the commands. It adds no storage format, protocol or network endpoint, and every action is audited as the matching command is.
- Every string drawn on the screen goes through one sanitizer that replaces C0 and C1 control characters, DEL and Unicode format characters, including bidirectional overrides, with `?`. Labels, member ids, inbox senders, audit fields, error text from other nodes and core stderr therefore cannot emit terminal escape sequences. The UI itself writes only cursor, erase, colour and mode sequences; it sets no window title and never touches the clipboard.
- `member add` requires the fingerprint to be typed or pasted from the out-of-band channel. The UI never derives it from the card.
- Decrypted data is written only to a file that is created exclusively and privately, with an owner-only DACL on Windows, and is never drawn. Buffers holding plaintext are cleared after use, which is best effort in Go.
- The node stays open for the session, so the core keeps the root key in memory until `--idle` expires or the UI exits. Core stderr is kept in a bounded in-memory log and never written to disk.
- The terminal mode is restored on exit and on SIGINT, SIGTERM and SIGHUP. With `--offline` the UI offers no action that opens a network connection.

## Platform differences

The host and the wire formats behave the same everywhere, so nodes on different platforms interoperate. What the core can enforce against the local system differs.
Expand Down
9 changes: 9 additions & 0 deletions SECURITY_KR.md
Original file line number Diff line number Diff line change
Expand Up @@ -128,6 +128,15 @@ HTTP 서비스:
- 코어는 키에 지정된 용도를 벗어나는 모든 작업을 거부합니다. 호스트는 사용할 때마다 저장된 메타데이터와 공개키를 코어가 blob에서 다시 계산한 값과 대조합니다.
- 노드 기동, 키 생성, 암호화, 복호화, 구성원 변경, 보내고 받은 봉투, inbox 처리, 카드 갱신, 증인 충돌은 해시 체인 감사 로그에 기록되며, 각 항목은 코어의 감사 키로 서명됩니다.

## 터미널 UI

- `kmsctl ui`는 명령과 같은 노드 함수를 호출합니다. 저장 형식, 프로토콜, 네트워크 엔드포인트를 새로 추가하지 않으며, 모든 동작은 해당 명령과 똑같이 감사 로그에 남습니다.
- 화면에 그리는 모든 문자열은 하나의 정화 단계를 거치며, C0·C1 제어 문자, DEL, 양방향 재정의를 포함한 Unicode 서식 문자는 `?`로 바뀝니다. 따라서 라벨, 구성원 id, 수신함 송신자, 감사 필드, 다른 노드가 보낸 오류 문구, 코어 stderr는 터미널 이스케이프 시퀀스를 내보낼 수 없습니다. UI 자체는 커서, 지우기, 색, 모드 시퀀스만 쓰며 창 제목을 바꾸지 않고 클립보드를 건드리지 않습니다.
- `member add`는 지문을 별도 채널에서 받아 직접 입력하거나 붙여 넣어야 합니다. UI는 카드에서 지문을 끌어오지 않습니다.
- 복호화한 데이터는 배타적이고 비공개로 생성한 파일(Windows는 소유자 전용 DACL)에만 쓰며 화면에 그리지 않습니다. 평문을 담은 버퍼는 사용 후 지우지만, Go에서는 최선의 노력 수준입니다.
- 노드는 세션 동안 열려 있으므로 `--idle` 시간이 지나거나 UI가 끝날 때까지 코어가 루트 키를 메모리에 둡니다. 코어 stderr는 크기가 제한된 메모리 로그에만 두고 디스크에 쓰지 않습니다.
- 터미널 모드는 종료할 때와 SIGINT, SIGTERM, SIGHUP을 받을 때 복원됩니다. `--offline`에서는 네트워크 연결을 여는 동작을 제공하지 않습니다.

## 플랫폼별 차이

호스트와 와이어 형식은 어디서나 같게 동작하므로 서로 다른 플랫폼의 노드끼리 상호 운용됩니다. 코어가 로컬 시스템에 대해 강제할 수 있는 것은 다릅니다.
Expand Down
72 changes: 71 additions & 1 deletion USAGE.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,23 @@ $ kmsctl version
kmsctl 1.1.0 (go go1.27.4, go_fips=true)
```

### Go toolchain

The `Makefile` exports `GOTOOLCHAIN=local` and `GOPROXY=off`, so `make` only uses the `go` on your `PATH` and never downloads anything. When that `go` is older than the version in `host/go.mod`, the build stops with `go: go.mod requires go >= 1.27.4 (running go 1.27.2; GOTOOLCHAIN=local)`. This happens when `go.mod` was raised, for example for a security fix, before your installed Go was updated.

- The preferred fix is to update Go to the version in `host/go.mod` (`brew upgrade go`, the official installer or your package manager).
- If you cannot update right away, download the toolchain once and pass it on the `make` command line. A variable on the `make` command line overrides the `Makefile`; the same variable set in the environment does not.

```bash
$ GOTOOLCHAIN=go1.27.4 go version # once: fetched from the module proxy and checked against the Go checksum database
$ make build GOTOOLCHAIN=go1.27.4
$ make test GOTOOLCHAIN=go1.27.4
```

- The first line needs network access because `make` cannot download with `GOPROXY=off`. After that the toolchain is in the module cache and builds work offline. On an air-gapped host, install a verified Go release of the required version instead.
- Running `go` directly in `host/` without `make` uses the default `GOTOOLCHAIN=auto`, so Go downloads and switches to the required version by itself. Set `GOTOOLCHAIN=local` to forbid that, as CI does.
- `kmsctl version` shows which Go built the binary.

## Installation

Release tarballs are provided for Linux amd64 and arm64 and require glibc 2.38 or later, such as Ubuntu 24.04 or Debian 13. `kmsd` and `kmsctl` are static binaries, and `kms-core` links glibc dynamically. Windows x86_64 and ARM64 are provided as zip archives (`pairier-1.1.0-windows-amd64.zip`, `pairier-1.1.0-windows-arm64.zip`) built in CI; their core is non-FIPS. No macOS binaries are provided, so build from source for development (see [Build](#build)).
Expand Down Expand Up @@ -258,14 +275,60 @@ Global options may appear before or after the command. `kmsctl --dir X key list`
| `encrypt --id KEYID [--in FILE] [--out FILE] [--aad STR]` | Encrypts. Reads stdin when no input is given. |
| `decrypt --id KEYID [--in FILE] [--out FILE] [--aad STR]` | Decrypts. |
| `audit verify [--anchor SEQ:HASH]... [--anchor-file FILE] [--peer MEMBER --url URL]` | Verifies the audit log chain and every checkpoint signature, and prints the head. Also checks that every given head (`--anchor`, `--anchor-file`, `--peer`) is still in the log. |
| `ui [--offline] [--idle DUR] [--lang LANG]` | Opens the terminal UI described below. |
| `version` | Prints the version and the Go FIPS status. |

If the file given with `--out` already exists, the command fails instead of overwriting it, and new files are created with `0600` permissions. Exit codes are as follows.
If the file given with `--out` already exists, the command fails instead of overwriting it, and new files are created with `0600` permissions, on Windows with a DACL that allows only you and SYSTEM. Exit codes are as follows.

- Success `0`
- Execution failure `1`
- Argument error `2`

## Terminal UI

`kmsctl ui` opens a full-screen terminal interface for everything the commands above do. It calls the same node code, so every action is written to the audit log exactly as the matching command would write it.

```
alice$ kmsctl --dir ~/.pairier ui
```

```powershell
PS> .\kmsctl.exe --dir "$env:LOCALAPPDATA\pairier\bob" ui
```

Without `--dir` or `$KMS_DIR` it asks for the node directory (default `~/.pairier`, on Windows `%LOCALAPPDATA%\pairier`), and when the directory does not exist it offers to initialize a node there.

| Option | Default | Description |
|---------------|---------|---------------------------------------------------------------------------------------------------------------------------------------------------------|
| `--offline` | off | Hides every action that contacts another node (push, health, peer audit). Use it on air-gapped hosts. |
| `--idle DUR` | `10m` | Closes the node and stops the core after this long without input. `0` keeps it open. |
| `--lang LANG` | `auto` | UI language, `en` or `ko`. `auto` picks Korean when `LC_ALL`, `LC_MESSAGES` or `LANG` starts with `ko`, or when the Windows display language is Korean. |

The global options (`--dir`, `--core`, `--timeout`, `--allow-unlocked-memory`) apply as usual.

| Tab | Keys | Commands |
|-----------|-----------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------|
| 1 Node | `c` export card, `R` renew card | `card`, `card renew` |
| 2 Keys | `Enter` info, `n` new, `s` send to a file, `p` push, `r` receive a file, `e` encrypt a file, `d` decrypt a file | `key list`, `key info`, `key gen`, `key send`, `key push`, `key receive`, `encrypt`, `decrypt` |
| 3 Members | `a` add, `w` export witnessed heads, `h` health | `member list`, `member add`, `member witness`, `peer health` |
| 4 Inbox | `Enter` accept, `x` reject, `i` import an envelope file | `inbox list`, `inbox accept`, `inbox reject`, `key receive` |
| 5 Audit | `v` verify with anchors, an anchor file or a peer | `audit verify` |
| 6 Log | | Session messages and core stderr, kept in memory only |

On every tab `Tab`, `Shift+Tab` or `1`-`6` switch tabs, the arrow keys or `j`/`k` move, `/` filters the list, `Esc` clears the filter or cancels a running action, `Ctrl+R` refreshes, `?` shows help, and `q` or `Ctrl+C` quits. In a form `Tab` and the arrow keys move between fields, `Space` toggles, `Left`/`Right` choose, and `Enter` moves to the next field and submits on the last one.

The UI behaves differently from a shell session in a few places.

- Adding a member asks you to type or paste the fingerprint you received over the other channel. The UI never fills it in from the card file.
- Sending, pushing, accepting and rejecting ask for confirmation and show the member fingerprint. Renewing the card asks you to type the member id.
- Encryption and decryption work on files only, up to 1 MiB. Decrypted data is written to a new file that only you can read (`0600`, on Windows an owner-only DACL) and is never drawn on the screen. Existing files are never overwritten.
- Labels, member ids, error messages from other nodes and core output are drawn with control and bidirectional formatting characters replaced by `?`, so none of them can inject terminal escape sequences. The UI sets no window title and does not use the clipboard.
- The node is opened once per session and the lists refresh every 15 seconds, so envelopes that `kmsd` receives appear without a restart. `kmsd` can keep running on the same directory.
- When `--idle` expires the node is closed, the core process exits and the screen is cleared. `Enter` opens the node again.
- In Korean the screens, forms and dialogs are translated. Messages from the node, the core and other nodes stay in English so that they match the troubleshooting table. Shortcuts also work while the Korean input method is on: the Dubeolsik jamo are read as the Latin keys in the same position, so `ㅂ` acts as `q`.

It needs an interactive terminal on both standard input and output, at least 64 columns by 18 rows. On Linux and macOS any terminal that understands xterm sequences works, but not `TERM=dumb`. On Windows use Windows Terminal, or PowerShell or cmd in the console of Windows 10 1809 or later. The mintty window of Git Bash is not a console, so start the UI from Windows Terminal or through `winpty`. On Windows the UI is experimental like the rest of the Windows support.

## Key usage

| Usage | Meaning |
Expand Down Expand Up @@ -349,6 +412,8 @@ PS> $env:KMS_DIR = "$env:LOCALAPPDATA\pairier\bob"
PS> .\kmsd.exe --listen 0.0.0.0:7443
```

`kmsctl.exe ui` needs Windows Terminal or the console of Windows 10 1809 or later.

## Running kms-core standalone

Normally `kmsctl` and `kmsd` launch the core themselves. To run the core separately under its own user, use socket path mode as follows.
Expand Down Expand Up @@ -450,3 +515,8 @@ The directory that holds the socket must be owned by the core user or root. A di
| `store: insecure directory: ... is not owned by the current user` | On Windows the file or directory was created by another account, or by a tool running elevated, so its owner is Administrators. Take ownership with `icacls PATH /setowner "%USERNAME%" /T` or recreate it with `kmsctl init`. The core reports the root key the same way as `object is not owned by the current user`. |
| `store: insecure directory: ... is on a network drive` | Move the node directory to a local volume. |
| `transport: --socket: unsupported` | The standalone socket mode is not available on Windows. Let `kmsctl` or `kmsd` start the core. |
| `ui: term: standard input and output must be an interactive terminal` | Input or output is redirected, or the shell has no console, such as Git Bash in mintty. Run it directly in a terminal; on Windows use Windows Terminal, PowerShell or cmd, or `winpty kmsctl ui`. |
| `ui: term: the console does not support virtual terminal sequences` | The Windows console is older than Windows 10 1809. Use Windows Terminal or a newer Windows. |
| `terminal too small` | The window is smaller than 64 columns by 18 rows. Enlarge it; the UI redraws on its own. |
| `go: go.mod requires go >= 1.27.4 (running go 1.27.2; GOTOOLCHAIN=local)` | The installed Go is older than `host/go.mod`. Update Go, or see [Go toolchain](#go-toolchain). |
| `go: download go1.27.4 for ...: toolchain not available` | The toolchain is not in the module cache, and `make` cannot download it with `GOPROXY=off`. Run `GOTOOLCHAIN=go1.27.4 go version` once with network access. |
Loading
Loading