mirror of
https://github.com/ben-grande/qusal.git
synced 2025-07-24 07:00:49 -04:00
doc: lint markdown files
Only way to have a unified markdown syntax is to enforce the wanted syntax by linting the files. Don't rely on the many markdown syntaxes, be consistent.
This commit is contained in:
Ben Grande
parent
88d9ba525c
commit
383c840f2f
68 changed files with 1297 additions and 815 deletions
|
|
@ -4,21 +4,21 @@ SSH Agent through Qrexec in Qubes OS.
|
|||
|
||||
## Table of Contents
|
||||
|
||||
* [Description](#description)
|
||||
* [Security](#security)
|
||||
* [Installation](#installation)
|
||||
* [Access Control](#access-control)
|
||||
* [Usage](#usage)
|
||||
* [Server](#server)
|
||||
* [Generate keys](#generate-keys)
|
||||
* [Limit key usage](#limit-key-usage)
|
||||
* [Reload agent](#reload-agent)
|
||||
* [Debug Agent side](#debug-agent-side)
|
||||
* [Client](#client)
|
||||
* [Enable and Start the service](#enable-and-start-the-service)
|
||||
* [Single agent per client](#single-agent-per-client)
|
||||
* [Multiple agents per client](#multiple-agents-per-client)
|
||||
* [Credits](#credits)
|
||||
* [Description](#description)
|
||||
* [Security](#security)
|
||||
* [Installation](#installation)
|
||||
* [Access Control](#access-control)
|
||||
* [Usage](#usage)
|
||||
* [Server](#server)
|
||||
* [Generate keys](#generate-keys)
|
||||
* [Limit key usage](#limit-key-usage)
|
||||
* [Reload agent](#reload-agent)
|
||||
* [Debug Agent side](#debug-agent-side)
|
||||
* [Client](#client)
|
||||
* [Enable and Start the service](#enable-and-start-the-service)
|
||||
* [Single agent per client](#single-agent-per-client)
|
||||
* [Multiple agents per client](#multiple-agents-per-client)
|
||||
* [Credits](#credits)
|
||||
|
||||
## Description
|
||||
|
||||
|
|
@ -46,29 +46,34 @@ to.
|
|||
|
||||
A rogue client has full control of the allowed agent, therefore it can:
|
||||
|
||||
1. Use the keys for as long as the client runs;
|
||||
2. Lock the agent with `ssh-add -X`; and
|
||||
3. Delete keys from memory by issuing `ssh-add -D`
|
||||
1. Use the keys for as long as the client runs;
|
||||
2. Lock the agent with `ssh-add -X`; and
|
||||
3. Delete keys from memory by issuing `ssh-add -D`
|
||||
|
||||
## Installation
|
||||
|
||||
- Top:
|
||||
* Top:
|
||||
|
||||
```sh
|
||||
sudo qubesctl top.enable sys-ssh-agent
|
||||
sudo qubesctl --targets=tpl-sys-ssh-agent,sys-ssh-agent state.apply
|
||||
sudo qubesctl top.disable sys-ssh-agent
|
||||
```
|
||||
|
||||
- State:
|
||||
* State:
|
||||
|
||||
<!-- pkg:begin:post-install -->
|
||||
|
||||
```sh
|
||||
sudo qubesctl state.apply sys-ssh-agent.create
|
||||
sudo qubesctl --skip-dom0 --targets=tpl-sys-ssh-agent state.apply sys-ssh-agent.install
|
||||
sudo qubesctl --skip-dom0 --targets=sys-ssh-agent state.apply sys-ssh-agent.configure
|
||||
```
|
||||
|
||||
<!-- pkg:end:post-install -->
|
||||
|
||||
Installation on the client template:
|
||||
|
||||
```sh
|
||||
sudo qubesctl --skip-dom0 --targets=TEMPLATE state.apply sys-ssh-agent.install-client
|
||||
```
|
||||
|
|
@ -82,6 +87,7 @@ As the default policy does not configure any allow rule, you are responsible
|
|||
for doing so.
|
||||
|
||||
Allow access to the specified agent based on the qube tag:
|
||||
|
||||
```qrexecpolicy
|
||||
qusal.SshAgent +work @tag:work @default allow target=sys-ssh-agent
|
||||
qusal.SshAgent +work @anyvm @anyvm deny
|
||||
|
|
@ -90,18 +96,22 @@ qusal.SshAgent +personal @anyvm @anyvm deny
|
|||
```
|
||||
|
||||
Ask access from `untrusted` qubes to the untrusted agent:
|
||||
|
||||
```qrexecpolicy
|
||||
qusal.SshAgent +untrusted untrusted @default ask target=sys-ssh-agent default_target=sys-ssh-agent
|
||||
qusal.SshAgent +untrusted @anyvm @anyvm deny
|
||||
```
|
||||
|
||||
Ask access from `trusted` to use the agent `trusted` on the alternative qube agent named `sys-ssh-agent-trusted`:
|
||||
Ask access from `trusted` to use the agent `trusted` on the alternative qube
|
||||
agent named `sys-ssh-agent-trusted`:
|
||||
|
||||
```qrexecpolicy
|
||||
qusal.SshAgent +trusted trusted @default ask target=sys-ssh-agent-trusted default_target=sys-ssh-agent-trusted
|
||||
qusal.SshAgent +trusted @anyvm @anyvm deny
|
||||
```
|
||||
|
||||
Always recommended to end with an explicit deny rule:
|
||||
|
||||
```qrexecpolicy
|
||||
qusal.SshAgent * @anyvm @anyvm deny
|
||||
```
|
||||
|
|
@ -119,12 +129,14 @@ directory should have the same name as the agent itself. Example:
|
|||
|
||||
Import preexisting keys to the agent directory or generate keys for a specific
|
||||
agent:
|
||||
|
||||
```sh
|
||||
mkdir -m 0700 -p ~/.ssh/identities.d/<AGENT>
|
||||
ssh-keygen -t ed25519 -f ~/.ssh/identities.d/<AGENT>/id_example
|
||||
```
|
||||
|
||||
You would do the following for the `work` agent:
|
||||
|
||||
```sh
|
||||
mkdir -m 0700 -p ~/.ssh/identities.d/work
|
||||
ssh-keygen -t ed25519 -f ~/.ssh/identities.d/work/id_example
|
||||
|
|
@ -139,6 +151,7 @@ You can set custom options by writing them to a file on the same path of the
|
|||
private key, but ending with the suffix `.ssh-add-option`. If the key is named
|
||||
`id_ed25519`, the option file should be named `id_ed25519.ssh-add-option`.
|
||||
The `.ssh-add-option` file has the following format:
|
||||
|
||||
```sh
|
||||
# id_ed25519.ssh-add-option
|
||||
-q -t 600
|
||||
|
|
@ -149,6 +162,7 @@ The `.ssh-add-option` file has the following format:
|
|||
Or you can manually add the key to the agent which are not located under the
|
||||
`~/.ssh/identities.d` directory so they aren't automatically added (substitute
|
||||
AGENT, SECS, and LIFE for their appropriate values):
|
||||
|
||||
```sh
|
||||
SSH_AUTH_SOCK="/run/user/1000/qusal-ssh-agent/<AGENT>.sock" ssh-add -t <SECS> -f <FILE>
|
||||
```
|
||||
|
|
@ -158,6 +172,7 @@ SSH_AUTH_SOCK="/run/user/1000/qusal-ssh-agent/<AGENT>.sock" ssh-add -t <SECS> -f
|
|||
The keys are added to the agent on the first call to that specific agent.
|
||||
If you have added keys to the correct agent directory but haven't rebooted
|
||||
yet, you will have to add the keys by executing:
|
||||
|
||||
```sh
|
||||
qvm-ssh-agent reload <AGENT>
|
||||
qvm-ssh-agent reload work
|
||||
|
|
@ -166,6 +181,7 @@ qvm-ssh-agent reload work
|
|||
#### Debug Agent side
|
||||
|
||||
You can list agents and their keys with:
|
||||
|
||||
```sh
|
||||
qvm-ssh-agent ls <AGENT>
|
||||
```
|
||||
|
|
@ -176,16 +192,19 @@ qvm-ssh-agent ls <AGENT>
|
|||
|
||||
Enable and start the connection to the SSH Agent via Qrexec for specified
|
||||
`<AGENT>`:
|
||||
|
||||
```sh
|
||||
sudo systemctl --no-block restart qusal-ssh-agent-forwarder@<AGENT>.service
|
||||
sudo systemctl --no-block restart qusal-ssh-agent-forwarder@personal.service
|
||||
```
|
||||
|
||||
You can start the service on boot if you place the above line
|
||||
`/rw/config/rc.local` of the client.
|
||||
|
||||
The ssh-agent socket will be at `/tmp/qusal-ssh-agent-forwarder/<AGENT>.sock`.
|
||||
|
||||
You can test the connection is working with:
|
||||
|
||||
```sh
|
||||
SSH_AUTH_SOCK="/tmp/qusal-ssh-agent-forwarder/personal.sock" ssh-add -l
|
||||
```
|
||||
|
|
@ -195,6 +214,7 @@ SSH_AUTH_SOCK="/tmp/qusal-ssh-agent-forwarder/personal.sock" ssh-add -l
|
|||
You might want to set the `SSH_AUTH_SOCK` and `SSH_AGENT_PID` environment
|
||||
variables to point to the `work` agent so every connection will use the same
|
||||
agent:
|
||||
|
||||
```sh
|
||||
echo 'export SSH_AUTH_SOCK=/tmp/qusal-ssh-agent-forwarder/work.sock;
|
||||
SSH_AGENT_PID="$(pgrep -f "/tmp/qusal-ssh-agent-forwarder/work.sock")";
|
||||
|
|
@ -209,11 +229,14 @@ different agent is not an alternative. Instead, use SSH client native method,
|
|||
the `IdentityAgent` option.
|
||||
|
||||
You can control the SSH agent via SSH command-line option:
|
||||
|
||||
```sh
|
||||
ssh -o IdentityAgent=/tmp/qusal-ssh-agent-forwarder/personal.sock personal-site.com
|
||||
ssh -o IdentityAgent=/tmp/qusal-ssh-agent-forwarder/work.sock work-site.com
|
||||
```
|
||||
|
||||
You can control the SSH agent via SSH configuration:
|
||||
|
||||
```sshconfig
|
||||
Host personal
|
||||
IdentityAgent /tmp/qusal-ssh-agent-forwarder/personal.sock
|
||||
|
|
@ -225,4 +248,4 @@ Host work
|
|||
|
||||
## Credits
|
||||
|
||||
- [Unman](https://github.com/unman/qusal-ssh-agent)
|
||||
* [Unman](https://github.com/unman/qusal-ssh-agent)
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue