diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 598dcfc..af933cc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,6 +4,13 @@ How to contribute to `common-devx` - adding skills, guides, and templates. +## Prerequisites + +Before contributing, ensure you have: + +- SSH key configured for GitHub access (see [`use-cases-ssh-authentication.md`](./human-guides/use-cases-ssh-authentication.md)) +- GPG key configured for commit signing (see [`use-cases-gpg-commit-signing.md`](./human-guides/use-cases-gpg-commit-signing.md)) + ## Development Model This repository uses **trunk-based development**: @@ -105,4 +112,4 @@ Open a [GitHub issue](https://github.com/KemingHe/common-devx/issues). --- -> Contributing Guide v2.1.0 - KemingHe/common-devx +> Contributing Guide v2.2.0 - KemingHe/common-devx diff --git a/README.md b/README.md index fed6b34..ffa3a33 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,7 @@ Available skills: commit messages, issues, PRs, meeting memos, READMEs, and more Browse [`human-guides/`](./human-guides/README.md) for: -- Git, shell, and GPG workflows (`use-cases-*.md`) +- Git, shell, SSH, and GPG workflows (`use-cases-*.md`) - Diagnostic procedures (`diagnosis-*.md`) ### For Projects diff --git a/SECURITY.md b/SECURITY.md index 260f426..a7236b8 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,6 +1,6 @@ # Security Policy -> **Last Updated**: 2026-02-05 by Keming He +> **Last Updated**: 2026-02-06 by Keming He Security considerations for using and contributing to common-devx. @@ -25,6 +25,18 @@ When using skills from this repository: 3. **Check for sensitive data** - Ensure no credentials, secrets, or PII are exposed 4. **Validate links and paths** - Confirm references point to correct locations +## Development Security + +Secure your development workflow with these practices: + +| CIA Component | Practice | Guide | +| :--- | :--- | :--- | +| **Confidentiality** | SSH key authentication | [`use-cases-ssh-authentication.md`](./human-guides/use-cases-ssh-authentication.md) | +| **Integrity** | GPG commit signing | [`use-cases-gpg-commit-signing.md`](./human-guides/use-cases-gpg-commit-signing.md) | +| **Availability** | Git version control | [`use-cases-git.md`](./human-guides/use-cases-git.md) | + +These guides apply to any Git-based workflow, not just this repository. + ## Reporting Issues ### Content Problems @@ -68,4 +80,4 @@ If you discover a security issue: --- -> Security Policy v1.0.0 - KemingHe/common-devx +> Security Policy v1.1.0 - KemingHe/common-devx diff --git a/human-guides/README.md b/human-guides/README.md index f53e154..ed9fadd 100644 --- a/human-guides/README.md +++ b/human-guides/README.md @@ -26,6 +26,7 @@ New types welcome - use descriptive prefixes that categorize the content. - [`use-cases-git.md`](./use-cases-git.md) - Git command-line workflows - [`use-cases-shell.md`](./use-cases-shell.md) - Shell operations - [`use-cases-gpg-commit-signing.md`](./use-cases-gpg-commit-signing.md) - GPG commit signing +- [`use-cases-ssh-authentication.md`](./use-cases-ssh-authentication.md) - SSH authentication (Git + servers) ### Diagnosis diff --git a/human-guides/use-cases-gpg-commit-signing.md b/human-guides/use-cases-gpg-commit-signing.md index dc070f9..80b8d52 100644 --- a/human-guides/use-cases-gpg-commit-signing.md +++ b/human-guides/use-cases-gpg-commit-signing.md @@ -152,8 +152,9 @@ Copy the entire output, including `-----BEGIN PGP PUBLIC KEY BLOCK-----` and `-- 1. Go to [**GitHub Settings**](https://github.com/settings/) > [**SSH and GPG keys**](https://github.com/settings/keys) 2. Click **New GPG key** -3. Paste your public key -4. Click **Add GPG key** +3. Title: descriptive name (e.g., "[Device Name] [YYYY]") +4. Paste your public key into the **Key** field +5. Click **Add GPG key** > [↑ Back to Table of Contents](#table-of-contents) @@ -272,4 +273,4 @@ If the issue persists and you need to commit urgently, see [Skip Signing](#skip- --- -> Use Cases - GPG Commit Signing v1.0.0 - KemingHe/common-devx +> Use Cases - GPG Commit Signing v1.0.1 - KemingHe/common-devx diff --git a/human-guides/use-cases-ssh-authentication.md b/human-guides/use-cases-ssh-authentication.md new file mode 100644 index 0000000..0bf7a37 --- /dev/null +++ b/human-guides/use-cases-ssh-authentication.md @@ -0,0 +1,288 @@ +# Use Cases - SSH Authentication + +> **Last Updated**: 2026-02-06 by Keming He + +## Platform + +> [!IMPORTANT] +> +> This guide is for **macOS / Linux** users with POSIX-compatible shell (sh, bash, zsh). +> +> For **Windows** users: See [GitHub: Connecting to GitHub with SSH](https://docs.github.com/en/authentication/connecting-to-github-with-ssh). + +Authenticate to Git hosting services and remote servers using SSH keys. + +## Table of Contents + +- [Use Cases - SSH Authentication](#use-cases---ssh-authentication) + - [Platform](#platform) + - [Table of Contents](#table-of-contents) + - [Why Use SSH Keys?](#why-use-ssh-keys) + - [Check for Existing Keys](#check-for-existing-keys) + - [Generate New Key](#generate-new-key) + - [Generate Key](#generate-key) + - [Add to ssh-agent](#add-to-ssh-agent) + - [Use Case: Git Hosting](#use-case-git-hosting) + - [Copy Public Key](#copy-public-key) + - [Add Key to GitHub](#add-key-to-github) + - [URL Rewriting](#url-rewriting) + - [Test Connection](#test-connection) + - [Use Case: Remote Servers](#use-case-remote-servers) + - [Add Key to Host](#add-key-to-host) + - [Connect](#connect) + - [File Transfer (SCP)](#file-transfer-scp) + - [Troubleshooting](#troubleshooting) + - [Permission Denied](#permission-denied) + - [Agent Issues](#agent-issues) + +## Why Use SSH Keys? + +- **Passwordless auth**: No prompts for git operations or server logins +- **More secure**: Key-based authentication is stronger than passwords +- **One setup, multiple uses**: Same key works for Git hosting, servers, and file transfer + +> [↑ Back to Table of Contents](#table-of-contents) + +--- + +## Check for Existing Keys + +```shell +ls -la ~/.ssh +``` + +Look for files like `id_ed25519` and `id_ed25519.pub` (or `id_rsa`/`id_rsa.pub`). If you have a key pair, you can skip to [Add to ssh-agent](#add-to-ssh-agent). + +> [↑ Back to Table of Contents](#table-of-contents) + +--- + +## Generate New Key + +### Generate Key + +**Ed25519** (recommended - smaller, faster, more secure): + +```shell +ssh-keygen -t ed25519 -C "your-email@example.com" +``` + +When prompted: + +1. Press **Enter** to accept the default file location (`~/.ssh/id_ed25519`) +2. Enter a passphrase (optional but recommended) + +> [!TIP] +> +> **Passphrase adds security** - if your private key is compromised, the attacker still needs the passphrase. The ssh-agent caches it so you don't type it repeatedly. + +For legacy systems that don't support Ed25519: + +```shell +ssh-keygen -t rsa -b 4096 -C "your-email@example.com" +``` + +### Add to ssh-agent + +The ssh-agent caches your key so you don't enter the passphrase repeatedly. + +```shell +# Start agent (usually auto-started on macOS) +eval "$(ssh-agent -s)" + +# Add key +ssh-add ~/.ssh/id_ed25519 + +# macOS - Use keychain for persistence across reboots +ssh-add --apple-use-keychain ~/.ssh/id_ed25519 + +# macOS - Add to `~/.ssh/config` so keys auto-load: +# Host * +# AddKeysToAgent yes +# UseKeychain yes +# IdentityFile ~/.ssh/id_ed25519 +``` + +> [↑ Back to Table of Contents](#table-of-contents) + +--- + +## Use Case: Git Hosting + +### Copy Public Key + +```shell +# Display public key (copy the output) +cat ~/.ssh/id_ed25519.pub + +# macOS: copy directly to clipboard +pbcopy < ~/.ssh/id_ed25519.pub +``` + +### Add Key to GitHub + +**GitHub**: + +1. Go to [**GitHub Settings**](https://github.com/settings/) > [**SSH and GPG keys**](https://github.com/settings/keys) +2. Click **New SSH key** +3. Title: descriptive name (e.g., "[Device Name] [YYYY]") +4. Key type: **Authentication Key** +5. Paste your public key +6. Click **Add SSH key** + +### URL Rewriting + +> [!TIP] +> +> **Use HTTPS URLs but authenticate via SSH** - clone commands from GitHub's UI work as-is, no manual URL conversion needed. + +```shell +git config --global url."git@github.com:".insteadOf "https://github.com/" +``` + +With this config: + +```shell +# This HTTPS URL from GitHub's UI... +git clone https://github.com/username/repo.git + +# ...automatically uses SSH authentication +# (Git rewrites it to git@github.com:username/repo.git) +``` + +### Test Connection + +```shell +ssh -T git@github.com +``` + +Expected output: + +```shell +Hi USERNAME! You've successfully authenticated, but GitHub does not provide shell access. +``` + +> [↑ Back to Table of Contents](#table-of-contents) + +--- + +## Use Case: Remote Servers + +The same SSH key can authenticate to Linux servers, cloud VMs, and any SSH-enabled host. + +### Add Key to Host + +**Automatic** (recommended): + +```shell +ssh-copy-id user@remote-host +``` + +This copies your public key to the remote host's `~/.ssh/authorized_keys`. + +**Manual** (if `ssh-copy-id` unavailable): + +```shell +cat ~/.ssh/id_ed25519.pub | ssh user@remote-host "mkdir -p ~/.ssh && chmod 700 ~/.ssh && cat >> ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys" +``` + +### Connect + +```shell +ssh user@remote-host +``` + +With a custom port: + +```shell +ssh -p 2222 user@remote-host +``` + +### File Transfer (SCP) + +**Upload** file to remote: + +```shell +scp local-file.txt user@remote-host:~/ +``` + +**Download** file from remote: + +```shell +scp user@remote-host:~/remote-file.txt ./ +``` + +**Upload directory** (recursive): + +```shell +scp -r local-dir/ user@remote-host:~/ +``` + +> [↑ Back to Table of Contents](#table-of-contents) + +--- + +## Troubleshooting + +### Permission Denied + +**Symptom**: + +```shell +Permission denied (publickey). +``` + +**Causes and fixes**: + +1. **Key not added to target**: + - For Git: Check key is in GitHub/GitLab SSH settings + - For servers: Check `~/.ssh/authorized_keys` on remote host + +2. **Key not in ssh-agent**: + + ```shell + ssh-add -l # List loaded keys + ssh-add ~/.ssh/id_ed25519 # Add if missing + ``` + +3. **Wrong key being used**: Create `~/.ssh/config` to specify key per host: + + ```text + Host github.com + IdentityFile ~/.ssh/id_ed25519 + + Host work-server + HostName 192.168.1.100 + User admin + IdentityFile ~/.ssh/id_work + ``` + +### Agent Issues + +**Symptom**: Key not persisting across terminal sessions. + +**Fix**: + +```shell +# Restart agent and re-add key +eval "$(ssh-agent -s)" +ssh-add ~/.ssh/id_ed25519 + +# macOS: use keychain for persistence +ssh-add --apple-use-keychain ~/.ssh/id_ed25519 +``` + +**Auto-start on shell login**: Add to `~/.bashrc` or `~/.zshrc`: + +```shell +if [ -z "$SSH_AUTH_SOCK" ]; then + eval "$(ssh-agent -s)" + ssh-add ~/.ssh/id_ed25519 +fi +``` + +> [↑ Back to Table of Contents](#table-of-contents) + +--- + +> Use Cases - SSH Authentication v1.0.0 - KemingHe/common-devx