1  # `arti hsc`
 2  
 3  `arti hsc` is a command line utility for managing client keys. In the future, we
 4  plan to extend it to support managing other types of state as well.
 5  
 6  Like the other `arti` subcommands, it has an optional `--config` option for
 7  specifying the TOML configuration file. Using the correct configuration file is
 8  important, because the state and keys managed by `arti hsc` are relative to the
 9  state directory, which you might have overridden in the configuration.
10  
11  > `arti hsc` is an experimental subcommand.
12  > To use it, you will need to compile `arti` with the experimental `hsc` feature
13  
14  ## Generating a service discovery key
15  
16  Client service discovery keys (previously known as "client authorization" keys)
17  can be generated and/or retrieved using the
18  `arti hsc key get --onion-name <SVC>.onion` command.
19  By default `key get` will generate a new keypair for use with `<SVC>.onion`,
20  if one does not already exist, and output its public part in the file specified
21  with the `--output` option. If such a keypair already exists, a new one will
22  **not** be generated.
23  
24  ```console
25  $ arti -c hsc.toml hsc key get
26  >      --onion-name mnyizjj7m3hpcr7i5afph3zt7maa65johyu2ruis6z7cmnjmaj3h6tad.onion
27  >      --output -
28  descriptor:x25519:RWWKYMW5EXDUZ2ESDDC7FQJCG6ROAR34LXNSTXFSY6JMQOWNDVNQ
29  ```
30  
31  > NOTE: the public part of the generated keypair must be shared with the
32  > service, and the service must be configured to allow the client that owns it
33  > to discover its introduction points. The caller is responsible for sharing the
34  > public key with the hidden service.
35  
36  See `arti hsc key get --help` for more information.
37  
38  ## Rotating a service discovery key
39  
40  Keys can be rotated with the `arti hsc key rotate` command.
41  
42  To rotate a service discovery key:
43  ```ignore
44  $ arti -c hsc.toml hsc key rotate
45  >      --onion-name mnyizjj7m3hpcr7i5afph3zt7maa65johyu2ruis6z7cmnjmaj3h6tad.onion
46  >      --output -
47  rotate client restricted discovery key for mnyizjj7m3hpcr7i5afph3zt7maa65johyu2ruis6z7cmnjmaj3h6tad.onion? (type YES or no): YES
48  descriptor:x25519:4E4B6CILWAAM2JFSVTOTCANCCUIMSOOSXZWONSR52ETXSTCKIYIA
49  ```
50  
51  > NOTE: if the client keystore already contains a restricted discovery keypair
52  > for the service, it will be overwritten. Otherwise, a new keypair is generated.
53  
54  As key rotation is a destructive operation (the old key will be lost),
55  `arti hsc key rotate` will prompt you to confirm the operation.
56  If you wish to force removal, or to run this command non-interactively,
57  use the `-f` option, which disables the confirmation prompt.
58  
59  > NOTE: as with `arti gsc key get`, the public part of the new keypair
60  > must be shared with the service
61  
62  See `arti hsc key rotate --help` for more information.
63  
64  ## Removing a service discovery key
65  
66  Keys can be rotated with the `arti hsc key remove` command.
67  
68  To remove a service discovery key:
69  ```ignore
70  $ arti -c hsc.toml hsc key remove
71  >      --onion-name mnyizjj7m3hpcr7i5afph3zt7maa65johyu2ruis6z7cmnjmaj3h6tad.onion
72  remove client restricted discovery key for mnyizjj7m3hpcr7i5afph3zt7maa65johyu2ruis6z7cmnjmaj3h6tad.onion? (type YES or no): YES
73  descriptor:x25519:4E4B6CILWAAM2JFSVTOTCANCCUIMSOOSXZWONSR52ETXSTCKIYIA
74  ```
75  
76  As with `hsc key rotate`, you can disable the confirmation prompt and force
77  removal using the `-f` option.
78  
79  See `arti hsc key remove --help` for more information.