1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
|
# `arti hsc`
`arti hsc` is a command line utility for managing client keys. In the future, we
plan to extend it to support managing other types of state as well.
Like the other `arti` subcommands, it has an optional `--config` option for
specifying the TOML configuration file. Using the correct configuration file is
important, because the state and keys managed by `arti hsc` are relative to the
state directory, which you might have overridden in the configuration.
> `arti hsc` is an experimental subcommand.
> To use it, you will need to compile `arti` with the experimental `hsc` feature
## Generating a service discovery key
Client service discovery keys (previously known as "client authorization" keys)
can be generated and/or retrieved using the `arti hsc key get` command.
`key get` prompts the user for an onion address (`<SVC>.onion`). If no keypair
exists for that service, it will first be generated. It then outputs the public
part of that service's key to the file specified with the --output option.
```ignore
$ arti -c hsc.toml hsc key get --output -
Enter an onion address: mnyizjj7m3hpcr7i5afph3zt7maa65johyu2ruis6z7cmnjmaj3h6tad.onion
descriptor:x25519:RWWKYMW5EXDUZ2ESDDC7FQJCG6ROAR34LXNSTXFSY6JMQOWNDVNQ
```
If you are running this command non-interactively, you can suppress the prompt
with `--batch`:
```ignore
$ echo "mnyizjj7m3hpcr7i5afph3zt7maa65johyu2ruis6z7cmnjmaj3h6tad.onion" | arti -c hsc.toml hsc key get --output - --batch
descriptor:x25519:RWWKYMW5EXDUZ2ESDDC7FQJCG6ROAR34LXNSTXFSY6JMQOWNDVNQ
```
> Note: the public part of the generated keypair must be shared with the
> service, and the service must be configured to allow the client that owns it
> to discover its introduction points. The caller is responsible for sharing the
> public key with the hidden service.
See `arti hsc key get --help` for more information.
## Rotating a service discovery key
Keys can be rotated with the `arti hsc key rotate` command.
To rotate a service discovery key:
```ignore
$ arti -c hsc.toml hsc key rotate --output -
Enter an onion address: mnyizjj7m3hpcr7i5afph3zt7maa65johyu2ruis6z7cmnjmaj3h6tad.onion
rotate client restricted discovery key for mnyizjj7m3hpcr7i5afph3zt7maa65johyu2ruis6z7cmnjmaj3h6tad.onion? (type YES or no): YES
descriptor:x25519:4E4B6CILWAAM2JFSVTOTCANCCUIMSOOSXZWONSR52ETXSTCKIYIA
```
> Note: if the client keystore already contains a restricted discovery keypair
> for the service, it will be overwritten. Otherwise, a new keypair is generated.
As key rotation is a destructive operation (the old key will be lost),
`arti hsc key rotate` will prompt you to confirm the operation.
If you wish to force removal, or to run this command non-interactively,
use the `-f` option, which disables the confirmation prompt.
> Note: as with `arti gsc key get`, the public part of the new keypair
> must be shared with the service
See `arti hsc key rotate --help` for more information.
## Removing a service discovery key
Keys can be rotated with the `arti hsc key remove` command.
To remove a service discovery key:
```ignore
$ arti -c hsc.toml hsc key remove
Enter an onion address: mnyizjj7m3hpcr7i5afph3zt7maa65johyu2ruis6z7cmnjmaj3h6tad.onion
remove client restricted discovery key for mnyizjj7m3hpcr7i5afph3zt7maa65johyu2ruis6z7cmnjmaj3h6tad.onion? (type YES or no): YES
```
As with `hsc key rotate`, you can disable the confirmation prompt and force
removal using the `-f` option.
See `arti hsc key remove --help` for more information.
## Migrating from C Tor to Arti
Arti supports importing C Tor client restricted discovery keys
(formerly known as ["client authorization keys"])
to Arti's keystore using the experimental `arti hsc ctor-migrate` command.
> Note: this feature is only available in builds that have the experimental
> `onion-service-cli-extra` feature enabled.
This command converts restricted discovery keys to the Arti native key format
(OpenSSH key format), and copies them to Arti's keystore.
> ⚠️**WARNING** ⚠️
>
> `arti hsc ctor-migrate` will **not** remove the migrated C Tor keys from disk.
> After running this command, the discovery keys of your client
> will exist both in its original location, and in the Arti native keystore.
> **You will need to manually remove one set of keys at the end of the migration**
> (the C Tor ones, if you are confident you no longer want to use C Tor
> as an onion service client, or the Arti ones if you don't wish to switch to Arti)
To use this command, you will first need to configure Arti with a C Tor keystore
pointing to the `ClientOnionAuthDir` of the client you wish to migrate:
```toml
[[storage.keystore.ctor.clients]]
# The identifier of this keystore. (Ie, the local nickname
# used to refer to this keystore in the rest of your config.)
id = "ctor-client"
# This should be set to the `ClientOnionAuthDir` of your client.
# If Arti is configured to run as a client (i.e. if it runs in SOCKS proxy mode),
# it will read the client restricted discovery keys from this path.
#
# The key files are expected to have the `.auth_private` extension,
# and their content **must** be of the form:
# `<56-char-onion-addr-without-.onion-part>:descriptor:x25519:<x25519 private key in base32>`.
#
# Malformed files, and files that don't have the `.auth_private` extension, will be ignored.
path = "/path/to/ctor_keystore"
```
Each C Tor keystore **must** have a unique identifier.
It is an error to configure multiple keystores with the same ID.
Once you are satisfied with the configuration, you can run the migration using:
```ignore
$ arti -c hsc.toml hsc ctor-migrate --from ctor-client
```
Alternatively, you can pass the C Tor configuration as an argument using the `-o` flag:
```ignore
$ arti hsc -o storage.keystore.ctor.clients='[{id = "ctor-client", path = "/path/to/ctor_keystore"}]' ctor-migrate --from ctor-client
```
If your Arti client already has some keys for the onion services
you are migrating discovery keys for,
they will be removed as part of the migration
(by default, `ctor-migrate` prompts before removal,
but you can disable that behavior using `--batch`).
> ⚠️**WARNING** ⚠️
>
> To avoid data loss, `arti hsc ctor-migrate` should only be run when
> no other process is accessing either keystore.
> So, you must shut down your client while you do the migration.
["client authorization keys"]: https://community.torproject.org/onion-services/advanced/client-auth/
|
