diff --git a/examples/ssh/ssh_config b/examples/ssh/ssh_config
index f22475d..a743b4d 100644
--- a/examples/ssh/ssh_config
+++ b/examples/ssh/ssh_config
@@ -12,6 +12,9 @@
## - host sections only apply to the matched names
## - canonicalization forces a configuration reload to check the now canonical
## host name against the configuration
+##
+## Sources:
+## - https://man.openbsd.org/ssh_config
################################################################################
# Canonicalize host names as first thing
diff --git a/examples/ssh/sshd_config b/examples/ssh/sshd_config
index 173923d..9261771 100644
--- a/examples/ssh/sshd_config
+++ b/examples/ssh/sshd_config
@@ -1,14 +1,16 @@
-# $OpenBSD: sshd_config,v 1.103 2018/04/09 20:41:22 tj Exp $
-
-# This is the sshd server system-wide configuration file. See
-# sshd_config(5) for more information.
-
-# This sshd was compiled with PATH=/usr/bin:/bin:/usr/sbin:/sbin
-
-# The strategy used for options in the default sshd_config shipped with
-# OpenSSH is to specify options with their default value where
-# possible, but leave them commented. Uncommented options override the
-# default value.
+################################################################################
+## /etc/ssh/sshd_config
+##
+## SSHD server system-wide configuration file.
+##
+## This sshd was compiled with PATH='/usr/bin:/bin:/usr/sbin:/sbin'.
+## The strategy used for options in the default sshd_config shipped with OpenSSH
+## is to specify options with their default value where possible, but leave them
+## commented. Uncommented options override the default value.
+##
+## Sources:
+## - https://man.openbsd.org/sshd_config
+################################################################################
#Port 22
#AddressFamily any
diff --git a/knowledge base/gnupg.md b/knowledge base/gnupg.md
index e535776..bbd7181 100644
--- a/knowledge base/gnupg.md
+++ b/knowledge base/gnupg.md
@@ -11,10 +11,10 @@
1. [Unattended key generation](#unattended-key-generation)
1. [Change a key's password](#change-a-keys-password)
1. [Put comments in a message or file](#put-comments-in-a-message-or-file)
-1. [Use a GPG key for SSH authentication](#use-a-gpg-key-for-ssh-authentication)
- 1. [Create an authentication-capable key or subkey](#create-an-authentication-capable-key-or-subkey)
- 1. [Enable SSH to use the GPG subkey](#enable-ssh-to-use-the-gpg-subkey)
- 1. [Share the GPG-SSH key](#share-the-gpg-ssh-key)
+1. [Use GPG keys for SSH authentication](#use-gpg-keys-for-ssh-authentication)
+ 1. [Create authentication-capable keys or subkeys](#create-authentication-capable-keys-or-subkeys)
+ 1. [Enable SSH to use GPG (sub)keys](#enable-ssh-to-use-gpg-subkeys)
+ 1. [Share GPG-SSH keys](#share-gpg-ssh-keys)
1. [Troubleshooting](#troubleshooting)
1. [`gpg failed to sign the data; fatal: failed to write commit object`](#gpg-failed-to-sign-the-data-fatal-failed-to-write-commit-object)
1. [`sign_and_send_pubkey: signing failed for … from agent: agent refused operation`](#sign_and_send_pubkey-signing-failed-for--from-agent-agent-refused-operation)
@@ -163,7 +163,8 @@ gpg --output 'file.out' --decrypt 'file.in.gpg'
find . -type f -name "*.gpg" -exec gpg --decrypt-files {} +
```
-The second command will create the decrypted version of all files in the same directory. Each file will have the same name of the encrypted version, minus the `.gpg` extension.
+The second command will create the decrypted version of all files in the same directory. Each file will have the same
+name of the encrypted version, minus the `.gpg` extension.
## Key export
@@ -179,7 +180,8 @@ gpg --output 'file.out.gpg' --encrypt --recipient 'recipient' 'file.in'
gpg --armor --symmetric --output 'file.out.gpg' 'file.in'
```
-Export all encrypted private keys (which will also include corresponding public keys) to a text file and create an encrypted version of that file:
+Export all encrypted private keys (which will also include corresponding public keys) to a text file and create an
+encrypted version of that file:
```sh
# Export.
@@ -199,7 +201,8 @@ gpg --export-ownertrust > 'otrust.txt'
## Key import
-As the new user execute `gpg --import` commands against the secured files, or the decrypted content of those files, and then check for the new keys with `gpg -k` and `gpg -K`, e.g.:
+As the new user execute `gpg --import` commands against the secured files, or the decrypted content of those files, and
+then check for the new keys with `gpg -k` and `gpg -K`, e.g.:
```sh
gpg --output 'myprivatekeys.asc' --decrypt 'mysecretatedprivatekeys.sec.asc' && \
@@ -267,18 +270,20 @@ hQIMAwbYc…
```
OpenPGP defines all text to be in UTF-8, so a comment may be any UTF-8 string.
-The whole point of armoring, however, is to provide seven-bit-clean data, so if a comment has characters that are outside the US-ASCII range of UTF they may very well not survive transport.
+The whole point of armoring, however, is to provide seven-bit-clean data, so if a comment has characters that are
+outside the US-ASCII range of UTF they may very well not survive transport.
-## Use a GPG key for SSH authentication
+## Use GPG keys for SSH authentication
> See also [How to enable SSH access using a GPG key for authentication].
This exercise will use a GPG subkey with only the authentication capability enabled to complete SSH connections.
You can create multiple subkeys as you would do for SSH key pairs.
-### Create an authentication-capable key or subkey
+### Create authentication-capable keys or subkeys
-To create subkeys, you should already have a GPG key. If you don't, read one of the many fine tutorials available on this topic.
+To create subkeys, you should already have a GPG key. If you don't, read one of the many fine tutorials available on
+this topic.
Create the subkey by editing your existing key **in expert mode** to get access to the appropriate options:
```sh
@@ -345,17 +350,20 @@ gpg> quit
Save changes? (y/N) y
```
-### Enable SSH to use the GPG subkey
+### Enable SSH to use GPG (sub)keys
-When using SSH, `ssh-agent` is used to manage SSH keys. When using a GPG key, `gpg-agent` is used to manage GPG keys.
+When using SSH, `ssh-agent` is used to manage SSH keys. When using a GPG key, `gpg-agent` is used to manage GPG
+keys.
To get `gpg-agent` to handle requests from SSH, you need to enable its SSH support:
```sh
echo "enable-ssh-support" >> ~/.gnupg/gpg-agent.conf
```
-You can avoid using `ssh-add` to load the keys by preemptively specifying which GPG keys to use in the `~/.gnupg/sshcontrol` file.
-Entries in this file need to be keygrips (internal identifiers that `gpg-agent` uses to refer to the keys). A keygrip refers to both the public and private key.
+You can avoid using `ssh-add` to load the keys by preemptively specifying which GPG keys to use in the
+`~/.gnupg/sshcontrol` file.
+Entries in this file need to be keygrips (internal identifiers that `gpg-agent` uses to refer to the keys). A keygrip
+refers to both the public and private key.
Find the keygrips you need, then add them to the `~/.gnupg/sshcontrol` file:
```sh
@@ -407,9 +415,10 @@ $ ssh-add -L
ssh-rsa AAAAB3NzaC…7SD8UQ== (none)
```
-### Share the GPG-SSH key
+### Share GPG-SSH keys
-Run `ssh-add -L` to list your public keys and copy them over manually to the remote host, or use `ssh-copy-id` as you would normally do.
+Run `ssh-add -L` to list one's public keys, then copy them over manually to the remote host.
+Alternatively, use `ssh-copy-id` as one would normally do.
## Troubleshooting
@@ -429,7 +438,8 @@ Run `ssh-add -L` to list your public keys and copy them over manually to the rem
**Cause:**
-The environment variable `GPG_TTY` was not set and Pinentry could not reach the terminal session to prompt for the key's passphrase.
+The environment variable `GPG_TTY` was not set and Pinentry could not reach the terminal session to prompt for the key's
+passphrase.
**Solution:**
diff --git a/knowledge base/ssh.md b/knowledge base/ssh.md
index c7f3eec..c9e70c1 100644
--- a/knowledge base/ssh.md
+++ b/knowledge base/ssh.md
@@ -19,7 +19,7 @@
1. [Troubleshooting](#troubleshooting)
1. [No matching host key type found](#no-matching-host-key-type-found)
1. [Further readings](#further-readings)
-1. [Sources](#sources)
+ 1. [Sources](#sources)
## TL;DR
@@ -178,7 +178,8 @@ When connecting to a host, the SSH client will use settings:
1. from the user's `~/.ssh/config` file,
1. from the `/etc/ssh/ssh_config` file
-Settings are loaded in a first-come-first-served way. They should hence appear from the most specific to the most generic, both by file and by position in those files:
+Settings are loaded in a **first-come-first-served** way. They should hence appear from the most specific to the most
+generic, both by file and by position in those files:
```ssh-config
Host targaryen
@@ -286,7 +287,8 @@ Notable options:
- `auto_cache` enables caching based on modification times;
- `reconnect` reconnects to the server;
-- `defer_permissions` works around the issue where certain shares may mount properly, but cause _permissions denied_ errors when accessed (caused by how Mac OS X's Finder translates and interprets permissions;
+- `defer_permissions` works around the issue where certain shares may mount properly, but cause _permissions denied_
+ errors when accessed (caused by how Mac OS X's Finder translates and interprets permissions;
- `noappledouble` prevents Mac OS X to write `.DS_Store` files on the remote file system;
- `volname` defines the name to use for the volume.
@@ -314,7 +316,8 @@ Error message example:
> `Unable to negotiate with XXX port 22: no matching host key type found. Their offer: ssh-rsa.`
-Cause: the server only supports the kind of RSA with SHA-1, which is considered weak and deprecated in newer SSH versions.
+Cause: the server only supports the kind of RSA with SHA-1, which is considered weak and deprecated in newer SSH
+versions.
Workaround: explicitly set your client to use the specified key type adding
@@ -342,10 +345,9 @@ Solution: update the SSH server.
- [`SSHD_CONFIG(5)`][sshd_config man page] man page
- [`sshd_config`][sshd_config example] example
- [ssh-agent]
+- [Use GPG keys for SSH authentication]
-## Sources
-
-All the references in the [further readings] section, plus the following:
+### Sources
- [Use SSHFS to mount a remote directory as a volume on OSX]
- [Using the SSH config file]
@@ -361,18 +363,19 @@ All the references in the [further readings] section, plus the following:
References
-->
-
-[ssh_config man page]: https://man.openbsd.org/ssh_config
-[ssh-agent]: https://www.ssh.com/academy/ssh/agent
-[sshd_config man page]: https://man.openbsd.org/sshd_config
-
-[further readings]: #further-readings
+
+[use gpg keys for ssh authentication]: gnupg.md#use-gpg-keys-for-ssh-authentication
[ssh_config example]: ../examples/ssh/ssh_config
[sshd_config example]: ../examples/ssh/sshd_config
+
+[ssh_config man page]: https://man.openbsd.org/ssh_config
+[ssh-agent]: https://www.ssh.com/academy/ssh/agent
+[sshd_config man page]: https://man.openbsd.org/sshd_config
+
[get started with openssh for windows]: https://learn.microsoft.com/en-us/windows-server/administration/openssh/openssh_install_firstuse?tabs=gui
[how to enable ssh access using a gpg key for authentication]: https://opensource.com/article/19/4/gpg-subkeys-ssh