diff --git a/README.md b/README.md index a147286..3719799 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ ## Terminology - `peer`: the person or device you are sending a secret to - `share code`: the `ENDE-PUB-1:...` string used for peer onboarding -- `send` / `receive`: task-oriented names for `encrypt` / `decrypt` +- `encrypt` / `decrypt`: the primary commands for sending and receiving secrets - `recipient` / `sender`: lower-level trust model terms still used in advanced commands ## Install/build @@ -110,34 +110,46 @@ The tutorial guides you through: 5. **Decrypt** — automatically decrypts the result from step 4 ## Quickstart -1. Generate local key material: +1. Generate your local key and print a share code: ```bash -./ende key keygen --name alice --export-public --export-dir . -./ende key keygen --name bob --export-public --export-dir . +./ende key keygen --name alice ``` -2. Alice shares the `share:` code from keygen output to Bob. +This prints: +- your recipient public key +- your signing public key +- your `share:` code (`ENDE-PUB-1:...`) -You can re-print a share code later: +2. Re-print your share code any time: ```bash ./ende key share --name alice ``` -3. Bob adds Alice as a peer in one command: +3. Set your default signer once: ```bash -./ende add-peer +./ende key use --name alice +``` + +4. Register a peer from a share code: +```bash +./ende register # share code (ENDE-PUB-1:...): ENDE-PUB-1:... # peer name override (optional, Enter to use the shared name): ``` -4. Run a local safety check before first real use: +You can also register non-interactively: +```bash +./ende register --alias bob --share 'ENDE-PUB-1:...' +``` + +5. Run a local safety check before first real use: ```bash ./ende doctor ``` `ende doctor` checks: - keyring file presence and permissions - default signer configuration -- private key file paths and `0600` permissions +- private key file paths and file permission safety - peer / trusted-signing-key registration consistency To remove a registered alias later: @@ -145,38 +157,44 @@ To remove a registered alias later: ./ende unregister alice ``` -5. Send a secret securely (default: text to stdout): +6. Encrypt a secret for a registered peer. + +Default behavior: +- output format: armored text +- output target: stdout + +Example: ```bash -echo 'TOKEN=abc123' | ./ende send -t bob +echo 'TOKEN=abc123' | ./ende encrypt -t bob ``` -5-0. Encrypt from file input: +Encrypt from a file: ```bash -./ende send -t bob -f secrets.env -o secret.txt +./ende encrypt -t bob -f secrets.env -o secret.txt ``` -5-1. Save text output to file (optional): +Save armored text to a file: ```bash -echo 'TOKEN=abc123' | ./ende send -t bob --text -o secret.txt +echo 'TOKEN=abc123' | ./ende encrypt -t bob -o secret.txt ``` -5-2. Raw binary output (optional): +Write raw binary instead: ```bash -echo 'TOKEN=abc123' | ./ende send -t bob --binary -o secret.ende +echo 'TOKEN=abc123' | ./ende encrypt -t bob --binary -o secret.ende ``` -5-3. Prompt for a secret interactively without echoing it to the terminal: +Prompt for a secret interactively without echoing it: ```bash -./ende send -t bob --prompt -o secret.txt +./ende encrypt -t bob --prompt -o secret.txt ``` Interactive prompt notes: - TTY input is masked so the secret is not echoed while typing. - Empty prompt input is rejected. - Non-interactive stdin/file workflows continue to work as before. -5-4. Review peer and output details before sending: +Review peer and output details before encrypting: ```bash -echo 'TOKEN=abc123' | ./ende send -t bob --confirm -o secret.txt +echo 'TOKEN=abc123' | ./ende encrypt -t bob --confirm -o secret.txt ``` `--confirm` shows: - peer alias and short fingerprint @@ -186,33 +204,50 @@ echo 'TOKEN=abc123' | ./ende send -t bob --confirm -o secret.txt For automation, you can keep the summary behavior in scripts and skip the prompt explicitly: ```bash -echo 'TOKEN=abc123' | ./ende send -t bob --confirm --yes -o secret.txt +echo 'TOKEN=abc123' | ./ende encrypt -t bob --confirm --yes -o secret.txt ``` -6. Receive and decrypt: +7. Verify and decrypt: ```bash ./ende verify -i secret.ende -./ende receive -i secret.ende -o decrypted.txt +./ende decrypt -i secret.ende -o decrypted.txt ``` Text envelope input is also supported: ```bash ./ende verify -i secret.txt -./ende receive -i secret.txt -o decrypted.txt -./ende receive -i secret.txt --text-out +./ende decrypt -i secret.txt -o decrypted.txt +./ende decrypt -i secret.txt --text-out ``` Safer plaintext output options: ```bash # Refuse to overwrite an existing plaintext file -./ende receive -i secret.ende -o decrypted.txt --no-clobber +./ende decrypt -i secret.ende -o decrypted.txt --no-clobber # Write plaintext to a temporary 0600 file and print the path -./ende receive -i secret.ende --out-temp +./ende decrypt -i secret.ende --out-temp ``` `--out-temp` is useful when you want Ende to choose a short-lived secure file path for you. +## Peer Inspection + +Show a registered recipient: +```bash +./ende recipient show bob +``` + +Show the trusted signing key for the same alias: +```bash +./ende sender show bob +``` + +List everything currently registered: +```bash +./ende key list +``` + ## Health Checks Use `ende doctor` to validate local trust and configuration before troubleshooting a failed encrypt/decrypt flow: @@ -230,6 +265,8 @@ The command prints `ok`, `warn`, and `fail` results and exits non-zero when a ha - `ende k` = `ende key` - `ende rcpt` = `ende recipient` - `ende snd` = `ende sender` +- `ende reg` = `ende register` +- `ende unreg` = `ende unregister` - `ende key kg` = `ende key keygen` - `ende key ls` = `ende key list` @@ -256,6 +293,10 @@ This performs GitHub SSH key lookup for identity pinning (TOFU) and stores a pin See the generated options table and raw `--help` output: - [CLI_HELP.md](CLI_HELP.md) +| Skill | Description | +|-------|-------------| +| [ende-secret-share](.kiro/skills/ende-secret-share/) | ende CLI로 팀원을 peer 등록하고 시크릿을 암호화하여 클립보드로 안전하게 전달한다. | + ## Open Source - License: [LICENSE](LICENSE) - Contributing guide: [CONTRIBUTING.md](CONTRIBUTING.md) diff --git a/USAGE_EN.md b/USAGE_EN.md index 9dd9309..6d2148e 100644 --- a/USAGE_EN.md +++ b/USAGE_EN.md @@ -50,7 +50,7 @@ Invoke-WebRequest -Uri "https://github.com/DevopsArtFactory/ende/releases/downlo --- ## 2. Initial Setup (One-time per user) -Each developer generates their local keys. +Each developer generates their own local key once. ```bash ./ende key keygen --name @@ -58,11 +58,25 @@ Each developer generates their local keys. Example: ```bash -./ende key keygen --name alice --export-public --export-dir . -./ende key keygen --name bob --export-public --export-dir . +./ende key keygen --name alice ``` -`keygen` output includes a `share:` token. Copy that token to the other user. +`keygen` prints: +- your recipient public key +- your signing public key +- your `share:` code (`ENDE-PUB-1:...`) + +You can print the share code again later: + +```bash +./ende key share --name alice +``` + +Set your default signer once: + +```bash +./ende key use --name alice +``` Generated assets: - `~/.config/ende/keyring.yaml` @@ -73,28 +87,33 @@ Generated assets: ## 3. Sender (Alice) Workflow -### 3-1) Register recipient (Bob) public key -Bob exports his recipient public key; Alice stores it as an alias. +### 3-1) Register Bob from a share code +Bob sends his `share:` code to Alice. On Alice's side: ```bash -./ende key keygen --name alice -# copy `share: ENDE-PUB-1:...` +./ende register +# share code (ENDE-PUB-1:...): ENDE-PUB-1:... +# peer name override (optional, Enter to use the shared name): ``` -On Bob's side (share-first interactive onboarding): +Non-interactive form: ```bash -./ende register -# share token (ENDE-PUB-1:...): ENDE-PUB-1:... -# alias override (optional, Enter to use token id): +./ende register --alias bob --share 'ENDE-PUB-1:...' +``` + +### 3-2) Run a local safety check +```bash +./ende doctor ``` -### 3-2) Encrypt + sign secret +### 3-3) Encrypt + sign secret ```bash -echo 'TOKEN=abc123' | ./ende encrypt -t bob -o secret.ende +echo 'TOKEN=abc123' | ./ende encrypt -t bob ``` Important: +- Default output is armored text to stdout. - `--sign-as` is required unless a default signer is set via `ende key use`. - `--to` can be repeated for multi-recipient delivery. @@ -103,12 +122,29 @@ Multi-recipient example: echo 'TOKEN=abc123' | ./ende encrypt -t bob -t diana -o secret.ende ``` -### 3-3) Send ciphertext file -Only send `secret.ende`. +Encrypt from a file: +```bash +./ende encrypt -t bob -f secrets.env -o secret.txt +``` + +Write raw binary instead of text: +```bash +echo 'TOKEN=abc123' | ./ende encrypt -t bob --binary -o secret.ende +``` + +Prompt for a secret interactively: +```bash +./ende encrypt -t bob --prompt -o secret.txt +``` + +Review peer and output details before encrypting: +```bash +echo 'TOKEN=abc123' | ./ende encrypt -t bob --confirm -o secret.txt +``` -For text-only channels (messenger/email), use: +For automation: ```bash -echo 'TOKEN=abc123' | ./ende encrypt -t bob --text -o secret.txt +echo 'TOKEN=abc123' | ./ende encrypt -t bob --confirm --yes -o secret.txt ``` --- @@ -140,6 +176,13 @@ Explicit stdout example: ./ende decrypt -i secret.ende -o - ``` +Other plaintext output options: +```bash +./ende decrypt -i secret.ende -o decrypted.txt --no-clobber +./ende decrypt -i secret.ende --out-temp +./ende decrypt -i secret.txt --text-out +``` + --- ## 5. GitHub Username Mode (Optional) @@ -167,6 +210,7 @@ Behavior: - `ende rcpt` = `ende recipient` - `ende snd` = `ende sender` - `ende reg` = `ende register` +- `ende unreg` = `ende unregister` - `ende key kg` = `ende key keygen` - `ende key ls` = `ende key list` @@ -196,7 +240,7 @@ Options: - `--file `: file containing age recipient key (required) ### `ende key list` -List local keys and recipient aliases. +List local keys, recipients, and trusted senders. ### `ende key use` Set default signer key ID for `encrypt`. @@ -205,6 +249,13 @@ Options: - `--name `: key ID - positional arg `` is also supported (`ende key use alice`) +### `ende key share` +Print a share code for an existing local key. + +Options: +- `--name `: key ID +- positional arg `` is also supported (`ende key share alice`) + --- ## 6-2) recipient @@ -242,6 +293,8 @@ Options: - `--text`: output ASCII-armored envelope (default `true`) - `--binary`: output raw binary envelope - `--prompt`: prompt secret input interactively +- `--confirm`: show a summary and ask before encrypting +- `--yes`: skip the confirmation prompt when `--confirm` is used ### `ende decrypt` Verify + decrypt envelope. @@ -251,6 +304,8 @@ Options: - `-o, --out `: plaintext output (`--out -` must be explicit) - `--verify-required `: enforce signature verification (default `true`) - `--text-out`: print decrypted plaintext to stdout +- `--no-clobber`: refuse to overwrite an existing plaintext file +- `--out-temp`: write plaintext to a temporary `0600` file and print the path ### `ende verify` Verify signature without decrypting. @@ -295,6 +350,9 @@ Options: - `--signing-public `: sender signing public key for manual one-step registration - `--force`: overwrite existing recipient/sender entries +### `ende unregister ` +Remove a registered alias and its matching trusted sender entry. + --- ## 7. Security Design Considerations diff --git a/USAGE_KO.md b/USAGE_KO.md index 31b5b3f..d32722a 100644 --- a/USAGE_KO.md +++ b/USAGE_KO.md @@ -50,7 +50,7 @@ Invoke-WebRequest -Uri "https://github.com/DevopsArtFactory/ende/releases/downlo --- ## 2. 초기 준비 (각자 1회) -각 개발자는 로컬에 자신의 키를 생성합니다. +각 개발자는 로컬에 자신의 키를 한 번 생성합니다. ```bash ./ende key keygen --name <내-ID> @@ -58,11 +58,25 @@ Invoke-WebRequest -Uri "https://github.com/DevopsArtFactory/ende/releases/downlo 예: ```bash -./ende key keygen --name alice --export-public --export-dir . -./ende key keygen --name bob --export-public --export-dir . +./ende key keygen --name alice ``` -`keygen` 출력의 `share:` 토큰을 상대에게 전달하면 됩니다. +`keygen` 출력에는 아래가 포함됩니다. +- recipient 공개키 +- signing 공개키 +- `share:` 코드 (`ENDE-PUB-1:...`) + +share 코드는 나중에 다시 출력할 수 있습니다. + +```bash +./ende key share --name alice +``` + +기본 송신자도 한 번 설정해두면 편합니다. + +```bash +./ende key use --name alice +``` 생성되는 항목: - `~/.config/ende/keyring.yaml` @@ -73,28 +87,33 @@ Invoke-WebRequest -Uri "https://github.com/DevopsArtFactory/ende/releases/downlo ## 3. 보내는 사람(Alice) 기준 -### 3-1) 받는 사람(Bob)의 recipient 공개키 등록 -Bob이 자신의 recipient 공개키를 전달하면 Alice가 alias로 등록합니다. +### 3-1) Bob의 share 코드로 등록 +Bob이 자신의 `share:` 코드를 Alice에게 전달합니다. Alice 측: ```bash -./ende key keygen --name alice -# 출력된 share: ENDE-PUB-1:... 복사 +./ende register +# share code (ENDE-PUB-1:...): ENDE-PUB-1:... +# peer name override (optional, Enter to use the shared name): ``` -Bob 측(share 우선 대화형 등록): +비대화형 방식: ```bash -./ende register -# share token (ENDE-PUB-1:...): ENDE-PUB-1:... -# alias override (optional, Enter to use token id): +./ende register --alias bob --share 'ENDE-PUB-1:...' +``` + +### 3-2) 로컬 상태 점검 +```bash +./ende doctor ``` -### 3-2) 비밀값 암호화 + 서명 +### 3-3) 비밀값 암호화 + 서명 ```bash -echo 'TOKEN=abc123' | ./ende encrypt -t bob -o secret.ende +echo 'TOKEN=abc123' | ./ende encrypt -t bob ``` 중요: +- 기본 출력은 armored text + stdout입니다. - `--sign-as`는 `ende key use`로 기본 송신자를 설정하지 않은 경우 필수입니다. - `--to`는 여러 번 사용 가능(다중 수신자). @@ -103,12 +122,29 @@ echo 'TOKEN=abc123' | ./ende encrypt -t bob -o secret.ende echo 'TOKEN=abc123' | ./ende encrypt -t bob -t diana -o secret.ende ``` -### 3-3) 암호문 전달 -생성된 `secret.ende` 파일만 전달합니다. +파일에서 암호화: +```bash +./ende encrypt -t bob -f secrets.env -o secret.txt +``` + +raw 바이너리로 출력: +```bash +echo 'TOKEN=abc123' | ./ende encrypt -t bob --binary -o secret.ende +``` + +비밀값을 대화형으로 입력: +```bash +./ende encrypt -t bob --prompt -o secret.txt +``` + +암호화 전에 peer/출력 정보를 확인: +```bash +echo 'TOKEN=abc123' | ./ende encrypt -t bob --confirm -o secret.txt +``` -메신저/이메일 같은 텍스트 채널로 보낼 때: +자동화에서는: ```bash -echo 'TOKEN=abc123' | ./ende encrypt -t bob --text -o secret.txt +echo 'TOKEN=abc123' | ./ende encrypt -t bob --confirm --yes -o secret.txt ``` --- @@ -140,6 +176,13 @@ echo 'TOKEN=abc123' | ./ende encrypt -t bob --text -o secret.txt ./ende decrypt -i secret.ende -o - ``` +그 외 출력 옵션: +```bash +./ende decrypt -i secret.ende -o decrypted.txt --no-clobber +./ende decrypt -i secret.ende --out-temp +./ende decrypt -i secret.txt --text-out +``` + --- ## 5. GitHub username 기반(선택) @@ -167,6 +210,7 @@ echo 'TOKEN=abc123' | ./ende encrypt -t bob --text -o secret.txt - `ende rcpt` = `ende recipient` - `ende snd` = `ende sender` - `ende reg` = `ende register` +- `ende unreg` = `ende unregister` - `ende key kg` = `ende key keygen` - `ende key ls` = `ende key list` @@ -196,7 +240,7 @@ recipient 공개키를 alias로 import - `--file `: age recipient 키 파일 경로 (필수) ### `ende key list` -로컬 키/recipient 목록 출력 +로컬 키/recipient/trusted sender 목록 출력 ### `ende key use` `encrypt` 기본 송신자 키 ID 설정 @@ -205,6 +249,13 @@ recipient 공개키를 alias로 import - `--name `: 키 ID - positional 인자 ``도 지원 (`ende key use alice`) +### `ende key share` +기존 로컬 키의 share 코드 출력 + +옵션: +- `--name `: 키 ID +- positional 인자 ``도 지원 (`ende key share alice`) + --- ## 6-2) recipient @@ -242,6 +293,8 @@ recipient 키 교체 - `--text`: ASCII armor 출력 (기본 `true`) - `--binary`: raw 바이너리 envelope 출력 - `--prompt`: 대화형으로 암호화할 값 입력 +- `--confirm`: 암호화 전 요약 확인 +- `--yes`: `--confirm` 사용 시 확인 프롬프트 생략 ### `ende decrypt` 검증 + 복호화 @@ -251,6 +304,8 @@ recipient 키 교체 - `-o, --out `: 평문 출력 경로 (`--out -`는 명시적으로만 허용) - `--verify-required `: 서명 검증 강제 여부 (기본 `true`) - `--text-out`: 복호화 평문을 stdout으로 출력 +- `--no-clobber`: 기존 평문 파일 덮어쓰기 거부 +- `--out-temp`: 임시 `0600` 파일에 평문 저장 후 경로 출력 ### `ende verify` 복호화 없이 서명 검증 @@ -295,6 +350,9 @@ recipient + trusted sender를 한 번에 등록 - `--signing-public `: 수동 원스텝 등록용 서명 공개키 - `--force`: 기존 recipient/sender 엔트리 덮어쓰기 +### `ende unregister ` +등록된 alias와 대응 trusted sender를 함께 제거 + --- ## 7. 설계 시 고려한 보안 사항