# State and key management CLI > This document uses deprecated terminology: "client authorization" is > now known as "restricted discovery". Arti will need the following new subcommands: * `arti-keys`, porcelain key management commands, for general key management * `arti-keys-raw`, plumbing key management commands * `arti-hss`, for managing the state (including keys) of hidden services * `arti-hsc`, for managing the state (including keys) of hidden service clients Initially, `arti-hss` and `arti-hsc` will be only used for listing, manipulating, and verifying the contents of Arti key stores (they are frontends to Arti's [`KeyMgr`]). In the future, they will be extended to support manipulating other types of persistent state too (for example, `arti hss` will also be used for manipulating the on-disk IPT records of the service). NOTE: The subcommands documented here do not exist yet. Rather than being the documentation for a finished product, this document is * a design document describing what needs to be implemented (which implicitly highlights what `KeyMgr` features we are missing) * a starting point for the CLI docs (although it might require some amendments, depending on how much the implementation deviates from what is described here) This document illustrates what the rendered man pages for the future state management CLIs might look like. The actual documentation/man pages will be be generated by rendering the [ROFF] obtained from the documentation of Arti's `clap::Command` (which will include the new `hsc` and `hss` subcommands). NOTE: This document talks about "keys and certificates", but the `KeyMgr` does not currently support certificates (but it will in the future. See [arti#955]) NOTE: `arti-keys`, `arti-keys-raw`, `arti-hsc` and `arti-hss` will be implemented as arti subcommands (`arti keys`, `arti hsc`, `arti hss`). TODO HSS: Design commands for converting C Tor HS service state to an Arti keystore and associated state (calling it something like `arti-hss migrate` or `arti-hss ctor-migrate`) ## `arti-keys` ``` NAME arti-keys - Command-line key management tools for Arti DESCRIPTION A CLI for accessing, manipulating and validating the contents of Arti key stores. As with arti, keystores are configured through Arti's TOML config (specified using the --config flag). The key management functionality is exposed as a collection of subcommands, each subcommand supporting a different set of options. This command provides high-level subcommands ("porcelain"), suitable for most use cases. Its subcommands implement high-level operations, manipulating either individual keys or key bundles, as applicable. They also provide guardrails preventing users from corrupting the key stores, and are suitable for routine key management tasks. Moreover, they don't require familiarity with the implementation details of Arti's key stores. TODO: explain what an ArtiPath is (ArtiPaths are mentioned throughout the manual) OPTIONS -c, --config Specify which config file(s) to read. Defaults to [File("$HOME/.config/arti/arti.toml"), Dir("$HOME/.config/arti/arti.d/")] --disable-fs-permission-checks Don't check permissions on the files we use. --keystore-dir Use the keystore from the specified directory, which should be an Arti format keystore. This is a convenience alias for -o storage.keystore.path= -h, --help Print help information -l, --log-level Override the log level (usually one of 'trace', 'debug', 'info', 'warn', 'error'). -o Override config file parameters, using TOML-like syntax. -V, --version Print version information SUBCOMMANDS help Print this message or the help of the given subcommand(s) list List keys and certificates from the configured key stores describe Print information about a specific key verify Perform validity and consistency checks ``` ### `arti-keys-list` ``` NAME arti-keys-list - List keys and certificates from the configured key stores SYNOPSIS arti keys list [OPTIONS] DESCRIPTION List the keys and certificates from the specified key stores. If no key stores are specified, this command lists the keys and certificates from all stores. In the pretty-printed output: * expired keys and certificates are annotated with (exp). * unrecognized keys and certificates (i.e. keys that have an unknown purpose) are annotated with (unk) * the keys and certificates that are not associated with one of the configured identities (i.e. keys with an unrecognized client/service nickname) are also annotated with (unk) OPTIONS --keystore all List the keys and certificates from all key stores. This is the default behavior if the --keystore flag is omitted --keystore default List the keys and certificates from the default keystore. --keystore [...] Specifies the IDs of the keystores to list keys and certificates from. The IDs must be associated with keystores from the Arti TOML config. It is an error to specify a key store ID not associated with any of the configured key stores. --output [pretty|json] The output format. Defaults to 'pretty', a pretty-printed, human-friendly format. --verbose Print more information about each listed key. This includes a description of the key, the ID of the key store it is located in, and whether the key is unrecognized or expired. This flag is disregarded if --output=json, because the JSON output always contains the full description of the key TODO: in the future we might want an option for only listing certs or only listing a type of key TODO: maybe this needs an option for listing keys that match a given ArtiPath pattern? EXAMPLES To pretty-print all the keys and certificates from keystores foo and bar: arti keys --config arti.toml list \ --keystore foo,bar \ --output pretty Sample output: ===== foo ===== client/alice/abc.onion/KS_hsc_desc_enc.x25519_private client/alice/xyz.onion/KS_hsc_desc_enc.x25519_private client/alice/xyz.onion/KS_hsc_desc_not_a_valid_name.x25519_private (unk) hs/carol/KS_hs_id.expanded_ed25519_private hs/carol/KS_hs_blind_id+19666_1440_43200.ed25519_expanded_private (exp) hs/carol/KS_hs_blind_id+19667_1440_43200.ed25519_expanded_private hs/carol/KS_hs_desc_sign+19666_1440_43200.ed25519_expanded_private (exp) hs/carol/KS_hs_desc_sign+19667_1440_43200.ed25519_expanded_private hs/dan/KS_hs_id.expanded_ed25519_private hs/eve/KS_hs_blind_id+19666_1440_43200.ed25519_expanded_private (unk) hs/eve/KS_hs_desc_sign+19667_1440_43200.ed25519_expanded_private (unk) ===== bar ===== client/bob/def.onion/KS_hsc_desc_enc.x25519_private To include more information about each key, use --verbose: arti keys --config arti.toml list \ --keystore foo,bar \ --output pretty \ --verbose Sample output: ===== client/alice/abc.onion/KS_hsc_desc_enc.x25519_private ===== purpose: Client authorization key, used for onion descriptor decryption client: alice keystore ID: foo expired: no ===== client/alice/xyz.onion/KS_hsc_desc_not_a_valid_name.x25519_private ===== purpose: unknown client: alice keystore ID: foo ===== hs/eve/KS_hs_desc_sign+19666_1440_43200.ed25519_expanded_private ===== purpose: descriptor signing key service: unknown keystore ID: foo expired: unknown ===== hs/eve/KS_hs_desc_sign+19667_1440_43200.ed25519_expanded_private ===== purpose: descriptor signing key service: unknown keystore ID: foo expired: unknown ... With --output=json, the command prints the same information in JSON format. TODO: Add JSON output sample ``` #### Implementation Required `KeyMgr` APIs: * `KeyMgr::list_matching` * `KeyMgr::describe` TODO: we might want to add a `KeyMgr::list_all` for listing all the keys from a given store (today this can be achieved by calling `list_matching` with a `"*"` `KeyPathPattern`). This command will be implemented by an API that uses `KeyMgr::list_matching` and `KeyMgr::describe` under the hood. Note: `KeyMgr::list_matching` lists the keys from all keystores. It will need to be modified to accept a `KeystoreSelector` argument to support only listing the keys from a given keystore (otherwise we can't implement the `--keystore` option). We'll also need some way of detecting which keys are expired: given a valid `KeyPath`, the API will: * parse it back into its corresponding `KeySpecifier` * check if the `TimePeriod` stored in the `KeySpecifier` is "relevant". If it is not, it will declare the key expired. Checking if the `TimePeriod` is relevant or not can be done by checking if it's one of the `NetDir::hs_all_time_periods()` returned by a recent `NetDir`. Alternatively, the API could try to "guess" which time periods are relevant based on the current wallclock time ### `arti-keys-verify` ``` NAME arti-keys-verify - perform consistency, validity, and integrity checks on the specified stores SYNOPSIS arti keys verify [OPTIONS] DESCRIPTION The key validity checks fail if there are any * keys and certificates not associated with any current identity * unrecognized keys * expired keys * ... (TODO) If --fix is not specified, this command lists the keys and certificates that failed the validity checks from each key store, along with the reason for the failure. Note: * expired keys and certificates are annotated with (exp). * unrecognized keys and certificates (i.e. keys that have an unknown purpose) are annotated with (unk) * the keys and certificates that are not associated with one of the configured identities (i.e. keys with an unrecognized client/service nickname) are also annotated with (unk) OPTIONS --keystore default Perform checks on the default keystore. This is the default behavior if the --keystore flag is omitted --keystore [...] Specifies the IDs of the keystores to check. The IDs must be associated with keystores from the Arti TOML config. It is an error to specify a key store ID not associated with any of the configured key stores. --fix Attempt to fix the problems detected. Any expired or unrecognized keys and certificates are removed. Prompts before every removal --output [pretty|json] The output format. Defaults to 'pretty', a pretty-printed, human-friendly format --verbose Print more information about each reported problem. This flag is disregarded if --output=json, because the JSON output always contains the full error report EXAMPLES Perform validity checks on keystores foo and bar: arti keys verify --config arti.toml \ --keystore foo,bar \ --output pretty Sample output: verifying 2 keystores bar ... OK foo ... FAILED failures: ====== foo ====== client/alice/xyz.onion/KS_hsc_desc_not_a_valid_name.x25519_private (unk) hs/carol/KS_hs_blind_id+19666_1440_43200.ed25519_expanded_private (exp) hs/carol/KS_hs_desc_sign+19666_1440_43200.ed25519_expanded_private (exp) Perform validity checks on keystores foo and bar, removing any invalid keys: arti keys verify --config arti.toml \ --keystore foo,bar \ --fix Sample output: verifying 2 keystores bar ... OK foo ... FAILED failures: ====== foo ====== client/alice/xyz.onion/KS_hsc_desc_not_a_valid_name.x25519_private (unk) Remove? [y/N]: y hs/carol/KS_hs_blind_id+19666_1440_43200.ed25519_expanded_private (exp) Remove? [y/N]: y hs/carol/KS_hs_desc_sign+19666_1440_43200.ed25519_expanded_private (exp) Remove? [y/N]: N ``` #### Implementation Required `KeyMgr` APIs: * `KeyMgr::list_matching` * `KeyMgr::describe` * `KeyMgr::remove` This command is exactly like `arti-keys-list`, except it also removes the invalid keys if prompted to do so. ### `arti-keys-describe` ``` NAME arti-keys-describe - print information about a specific key SYNOPSIS arti keys describe [OPTIONS] DESCRIPTION Given the ArtiPath of a key, print a description of what the key is used for. OPTIONS --output [pretty|json] The output format. Defaults to 'pretty', a pretty-printed, human-friendly format --verbose Print more information about the key. This includes a description of the key, the ID of the key store it is located in, and whether the key is unrecognized or expired. This flag is disregarded if --output=json, because the JSON output always contains the full description of the key TODO: maybe this needs an option for describing keys that match a given ArtiPath pattern? EXAMPLES Describe the ArtiPath of a hidden service identity key: arti keys describe hs/carol/KS_hs_id.expanded_ed25519_private Sample output: ===== hs/carol/KS_hs_id.expanded_ed25519_private ===== purpose: The long-term identity keypair of the service. type: ed25519 keypair service: carol expired: no Describe a malformed client ArtiPath: arti keys describe \ client/alice/xyz.onion/KS_hsc_desc_not_a_valid_name.x25519_private Sample output: ===== client/alice/xyz.onion/KS_hsc_desc_not_a_valid_name.x25519_private ===== purpose: unknown type: x25519 keypair expired: unknown Describe a malformed ArtiPath: arti keys describe abc.xyz Sample output: ===== abc.xyz ===== purpose: unknown type: unknown expired: unknown ``` #### Implementation Required `KeyMgr` APIs: * `KeyMgr::describe` This will be implemented by an API based on `KeyMgr::describe`. As mentioned under `arti-keys-list`, the API will also need to be able to detect if the specified key is expired or not (this is not something `KeyMgr` can do. See [`Reactor`] for an example of how key expiration is detected and handled today. The key expiration logic will need to be factored out of [`Reactor`], because we'll need it for the CLI APIs too). ## `arti-keys-raw` ``` NAME arti-keys-raw - Command-line key management plumbing tools for Arti DESCRIPTION A CLI for accessing and manipulating the contents of Arti key stores. As with arti, keystores are configured through Arti's TOML config (specified using the --config flag). The key management functionality is exposed as a collection of "plumbing" subcommands, each subcommand supporting a different set of options. The arti-keys-raw commands operate at a lower level than the arti-keys(1) commands. They operate on individual keys, specified as `ArtiPath`s. As such, their misuse can lead to key store corruption. You most likely do **not** need to use these: all common/routine use cases *should* be covered by the higher level arti-keys(1) subcommands. If you find yourself needing these commands for routine key management tasks, it means we are missing a porcelain wrapper for your workflow. TODO: explain what an ArtiPath is (ArtiPaths are mentioned throughout the manual) OPTIONS -c, --config Specify which config file(s) to read. Defaults to [File("$HOME/.config/arti/arti.toml"), Dir("$HOME/.config/arti/arti.d/")] --disable-fs-permission-checks Don't check permissions on the files we use. --keystore-dir Use the keystore from the specified directory, which should be an Arti format keystore. This is a convenience alias for -o storage.keystore.path= -h, --help Print help information -l, --log-level Override the log level (usually one of 'trace', 'debug', 'info', 'warn', 'error'). -o Override config file parameters, using TOML-like syntax. -V, --version Print version information SUBCOMMANDS list Plumbing subcommand for listing the files from key stores remove-by-path Plumbing subcommand for removing files from key stores ``` ### `arti-keys-raw-list` (plumbing) ``` NAME arti-keys-raw-list - List all available keys, without interpreting their meaning SYNOPSIS arti keys-raw list [OPTIONS] DESCRIPTION List the keys and certificates from the specified key stores. If no key stores are specified, this command lists the keys and certificates from all stores. OPTIONS --keystore all List the keys and certificates from all key stores. This is the default behavior if the --keystore flag is omitted --keystore default List the keys and certificates from the default keystore. --keystore [...] Specifies the IDs of the keystores to list keys and certificates from. The IDs must be associated with keystores from the Arti TOML config. It is an error to specify a key store ID not associated with any of the configured key stores. EXAMPLES List the keys in keystores foo and bar: arti keys-raw list --config arti.toml \ --keystore foo,bar Sample output: ===== foo ===== abc/not-a-key.txt client/alice/abc.onion/ks_hsc_desc_enc.x25519_private client/alice/xyz.onion/KS_hsc_desc_enc.x25519_private client/alice/xyz.onion/KS_hsc_desc_not_a_valid_name.x25519_private hs/carol/KS_hs_id.expanded_ed25519_private hs/carol/KS_hs_blind_id+19666_1440_43200.ed25519_expanded_private hs/carol/KS_hs_blind_id+19667_1440_43200.ed25519_expanded_private hs/carol/KS_hs_desc_sign+19666_1440_43200.ed25519_expanded_private hs/carol/KS_hs_desc_sign+19667_1440_43200.ed25519_expanded_private hs/dan/KS_hs_id.expanded_ed25519_private hs/eve/KS_hs_blind_id+19666_1440_43200.ed25519_expanded_private hs/eve/KS_hs_desc_sign+19667_1440_43200.ed25519_expanded_private ===== bar ===== client/bob/def.onion/KS_hsc_desc_enc.x25519_private ``` #### Implementation Required `KeyMgr` APIs: * `KeyMgr::list_matching` ### `arti-keys-raw-remove-by-path` (plumbing) ``` NAME arti-keys-raw-remove-by-path - Remove a key, given its ArtiPath SYNOPSIS arti keys-raw remove-by-path [OPTIONS] DESCRIPTION Remove the specified file from the key store. The specified RAW_PATH is in the format of an ArtiPath, and so it is relative to the key store root. TODO: warn about misuse OPTIONS --keystore default Remove the key from the default keystore. This is the default behavior if the --keystore flag is omitted --keystore Specifies the ID of the keystore to remove the key from. The ID must match one of the key store IDs configured in the specified config. It is an error to specify an unrecognized key store ID. --remove-all Remove **all** the keys and certificates of this key from all keystores. This is a dangerous option and should be used with care. Prompts before removal. Cannot be used with --keystore EXAMPLES Remove a file from keystore foo: arti keys-raw --config arti.toml remove-by-path \ --keystore foo \ client/alice/abc.onion/ks_hsc_desc_enc.x25519_private Remove a file that is probably not a key from keystore foo: arti keys-raw --config arti.toml remove-by-path \ --keystore foo \ foo/some-file.txt ``` #### Implementation Required `KeyMgr` APIs: * `KeyMgr::remove` ## `arti-hsc` ``` NAME arti-hsc - Command-line tool for managing the state of Arti hidden service clients SYNOPSIS arti hsc [OPTIONS] [SUBCOMMAND-OPTIONS] DESCRIPTION A CLI for accessing, manipulating and validating the contents of Arti key stores and other persistent state. As with arti, keystores are configured through Arti's TOML config (specified using the --config flag). The state management functionality is exposed as a collection of subcommands, each subcommand supporting a different set of options. TODO: explain what an ArtiPath is (ArtiPaths are mentioned throughout the manual) OPTIONS -c, --config Specify which config file(s) to read. Defaults to [File("$HOME/.config/arti/arti.toml"), Dir("$HOME/.config/arti/arti.d/")] --disable-fs-permission-checks Don't check permissions on the files we use. --keystore-dir Use the keystore from the specified directory, which should be an Arti format keystore. This is a convenience alias for -o storage.keystore.path= -h, --help Print help information -l, --log-level Override the log level (usually one of 'trace', 'debug', 'info', 'warn', 'error'). -o Override config file parameters, using TOML-like syntax. -V, --version Print version information SUBCOMMANDS help Print this message or the help of the given subcommand(s) generate-key Generate a key in one of the configured key stores remove-key Remove a key from one of the configured key stores ``` ### `arti-hsc-generate-key` ``` NAME arti-hsc-generate-key-auth - Generate a hidden service client authorization key SYNOPSIS arti hsc generate-key auth [OPTIONS] DESCRIPTION NOTE: while generate-key currently has only one subcommand ("auth"), in the future we might need to extend it with additional subcommands (if we extend the protocol to support other forms of client auth, for example) Generate a hidden service client authorization key, placing the keypair in the specified key store. This generates an x25519 descriptor encryption keypair and prints the corresponding public key to stdout in the format specified via the --pub-format option. This command should be run by clients who want to connect to a hidden service that requires client authorization. To connect to a hidden service that has client authorization enabled, clients need to share the public part of the key with the hidden service through a secure channel. The hidden service can then authorize the client to connect by encrypting its descriptor with the client's public key. The client uses the generated x25519 keypair to compute the keys for decrypting the superencrypted layer of the descriptor. OPTIONS --keystore default Generate the key in the default keystore. This is the default behavior if the --keystore flag is omitted --keystore Specifies the ID of the keystore to generate the key into. The ID must match one of the key store IDs configured in the specified config. It is an error to specify an unrecognized key store ID. --nickname The nickname of the client for which to generate the key --hsid The hidden service for which to generate the key --pub-format [arti|ctor] The format to print the public part of the key in TODO: decide what the arti format looks like --force Whether to overwrite the key if it already exists EXAMPLES Generate a client authorization key for service xyz.onion in keystore foo: arti hsc --config arti.toml generate-key auth --keystore foo \ --nickname alice \ --hsid xyz.onion \ --pub-format ctor Stdout: descriptor:x25519:dz4q5xqlb4ldnbs72iarrml4ephk3du4i7o2cgiva5lwr6wkquja TODO: update this section and document the arti --pub-format after we reach a conclusion in #1028 ``` #### Implementation Required `KeyMgr` APIs: * `KeyMgr::generate` ### `arti-hsc-remove-key` ``` NAME arti-hsc-remove-key - remove a client authorization key from the specified key store SYNOPSIS arti hsc remove-key auth [OPTIONS] DESCRIPTION NOTE: like generate-key, remove-key currently has only one subcommand ("auth"). Remove a hidden service client authorization key from the specified key store. After removing the key, the client will no longer be able to connect to the service specified via --hsid, if the service has enabled client authorization. OPTIONS --nickname The nickname of the client for which to remove the key --hsid The hidden service the key is associated with EXAMPLES Remove the client authorization key for service xyz.onion from keystore foo: arti hsc --config arti.toml remove-key auth --keystore foo \ --type desc-enc \ --nickname alice \ --hsid xyz.onion ``` #### Implementation Required `KeyMgr` APIs: * `KeyMgr::remove` ## `arti-hss` ``` NAME arti-hss - Command-line tool for managing the state of Arti hidden services SYNOPSIS arti hss [OPTIONS] [SUBCOMMAND-OPTIONS] DESCRIPTION A state management tool for Arti hidden services. The managed state includes: * the IPT state of the service stored on disk * the keys associated with the service OPTIONS -c, --config Specify which config file(s) to read. Defaults to [File("$HOME/.config/arti/arti.toml"), Dir("$HOME/.config/arti/arti.d/")] --disable-fs-permission-checks Don't check permissions on the files we use. --keystore-dir Use the keystore from the specified directory, which should be an Arti format keystore. This is a convenience alias for -o storage.keystore.path= -h, --help Print help information -l, --log-level Override the log level (usually one of 'trace', 'debug', 'info', 'warn', 'error'). -o Override config file parameters, using TOML-like syntax. -V, --version Print version information SUBCOMMANDS help Print this message or the help of the given subcommand(s) new-service Initialize a new hidden service generate-online-keys Generate all the keys necessary to run a hidden service destroy Remove all the keys and state of a hidden service print-onion Print the .onion address of a service auth-clients Manage the authorized clients of this hidden service destroy-and-recreate Generate a new identity keypair for a hidden service ``` ### `arti-hss-new-service` ``` NAME arti-hss-new-service - initialize a new hidden service SYNOPSIS arti hss new-service [OPTIONS] DESCRIPTION Initializes a new hidden service by generating a new identity keypair and placing it in the specified key store. Users wanting to create a new service that will run in offline mode should run this command on a secure offline host to create its identity keys, and then run arti-hss-generate-online-keys(1) to generate the keys needed to run the service. Before running this command, ensure the hidden service you are initializing is configured in the Arti config (specified via --config). If Arti is already running using a config that contains an entry for the hidden service, its identity key has likely already been automatically generated by Arti. If that is the case, this command will report that an identity key already exists for the service, and exit with an error. TODO: make Arti support watching for keystore changes. Decide what happens if a new service is configured while Arti is running OPTIONS --keystore default Place the identity key in the default keystore. This is the default behavior if the --keystore flag is omitted --keystore Specifies the ID of the keystore to generate the identity key into. The ID must match one of the key store IDs configured in the specified config. It is an error to specify an unrecognized key store ID. --nickname The nickname of the service EXAMPLES Initialize a new hidden service with nickname "shallot" in the default key store: arti hss --config arti.toml new-service \ --nickname shallot Sample output: Generated a new hidden service using nickname "shallot": wrxdvcaqpuzakbfww5sxs6r2uybczwijzfn2ezy2osaj7iox7kl7nhad.onion If any of the configured keystores contain any entries for service "shallot", a new identity key pair will **not** be generated: Cannot generate a new service with nickname "shallot": keystores foo and bar contain keys associated with a pre-existing hidden service with the same nickname Hint: use a different nickname. Alternatively, if you want to erase the service with nickname "shallot", run: arti hss --config arti.toml destroy \ --nickname shallot before retrying the operation If the public part of the identity key is available, this command also prints the corresponding .onion address before exiting: Cannot generate new hidden service with nickname "shallot": an identity key already exists wrxdvcaqpuzakbfww5sxs6r2uybczwijzfn2ezy2osaj7iox7kl7nhad.onion ``` #### Implementation Required `KeyMgr` APIs: * `KeyMgr::generate` ### `arti-hss-generate-online-keys` ``` NAME arti-hss-generate-online-keys - generate the keys needed to run a hidden service in offline mode SYNOPSIS arti hss generate-online-keys [OPTIONS] DESCRIPTION Generates all the keys required for a hidden service to operate without needing access to its identity key, up to a given time period. You do **not** need to run this command unless you want to run a hidden service in offline mode (where the identity key of the service is kept offline). If the identity keys are "online" (i.e. available on the host running the hidden service), you do not need to run this command, as Arti will automatically generate all the necessary keys and certificates. This command should be run on a secure offline system where the secret identity key of the service is available. It generates keys inside an "online" keystore, specified via --online-keystore-dir. Because the "online" keystore is a directory on disk, it can be copied from the offline system to the (online) hidden service host using the file-copying utilities available on your system. On the online system, the storage.keystore.path from the TOML config of the hidden service should point to the path the "online" keystore was copied to. The service will be able to operate without its secret identity key until the time specified via --up-to. After that, additional keys will need to be generated. This command assumes the hidden service has already been initialized, either manually, using arti-hss-new-service(1), or implicitly, by starting arti as a hidden service, and that the identity keypair is available in one of the configured key stores. Generates the following keys and certificates for each time period starting from the current time period up until the time specified via --up-to: * blinded identity keypair * descriptor signing key * descriptor signing certificate (obtained by signing the descriptor signing key with the blinded identity key) OPTIONS --online-keystore-dir The root of the online keystore, where the keys will be generated. The keystore directory will be created if it does not already exist. --nickname The nickname of the service for which to generate the keys --up-to {|} A timestamp or duration representing the validity interval of the generated keys. The service will be able to run using the generated keys until the specified , or for the specified . after which new keys will need to be generated. Timestamps represent an absolute date/time given in RFC3339 format. Durations are relative to the current time (i.e. the time when this command was run), and represent a number of hours, minutes, or days (for example "--up-to 48h", --up-to 48 hours", "--up-to 10 days"). EXAMPLES Initialize a new "online" keystore at $HOME/foo with the keys needed in order for hidden service "shallot" to run in offline mode until 2023-02-09T12:00:00Z (the identity key of the service must be in one of the keystores configured in arti.toml): arti hss --config arti.toml generate-online-keys \ --online-keystore-dir $HOME/foo \ --nickname shallot \ --up-to 2023-02-09T12:00:00Z Keystore foo can be exported to the online system by copying the $HOME/foo directory. On the online system, in the TOML config of the hidden service, storage.keystore.path should point to the parent directory of foo (TODO: make the keystore ID part of the config). ``` #### Implementation Required `KeyMgr` APIs: * `KeyMgr::generate` ### `arti-hss-destroy` ``` NAME arti-hss-destroy - remove the persistent state and all the keys of a hidden service SYNOPSIS arti hss destroy [OPTIONS] DESCRIPTION Remove the persistent state and all the keys of a hidden service. This removes * the IPT state of the service stored on disk * any the keys associated with the service, from all key stores OPTIONS --nickname The nickname of the service to erase EXAMPLES Erase all the keys and state hidden service with nickname "shallot": arti hss --config arti.toml destroy \ --nickname shallot ``` #### Implementation Required `KeyMgr` APIs: * `KeyMgr::remove` ### `arti-hss-print-onion` ``` NAME arti-hss-print-onion - print the .onion address of a service SYNOPSIS arti hss print-onion [OPTIONS] DESCRIPTION Print the .onion address of a service. OPTIONS --nickname The nickname of the service to display EXAMPLES Print the .onion address of the service with nickname allium from the default keystore: arti hss --nickname allium print-onion-address Sample output: wrxdvcaqpuzakbfww5sxs6r2uybczwijzfn2ezy2osaj7iox7kl7nhad.onion ``` #### Implementation Required `KeyMgr` APIs: * `KeyMgr::get` ### `arti-hss-auth-clients` ``` NAME arti-hss-auth-clients - Manage the authorized clients of this hidden service SYNOPSIS arti hss auth-clients [SUBCOMMAND] DESCRIPTION A command for managing the authorized clients of an Arti hidden service. TODO: document how these commands are supposed to work after we reach a conclusion in #1028 SUBCOMMANDS help Print this message or the help of the given subcommand(s) import Import the public keys of a client disable Un-authorize a previously authorized client enable Authorize a new client ``` ### `arti-hss-destroy-and-recreate` ``` NAME arti-hss-destroy-and-recreate - Generate a new identity keypair for a hidden service SYNOPSIS arti hss destroy-and-recreate [OPTIONS] DESCRIPTION A command for generating a new set of keys for an existing hidden service. This command deletes all the keys, including identity key, of the specified service and generates a fresh identity keypair. This command preserves the nickname of the service and its configuration (including the authorized clients). TODO: Expand on the description, add an example OPTIONS --nickname The nickname of the service to destroy and recreate ``` #### Implementation Required `KeyMgr` APIs: * `KeyMgr::remove` * `KeyMgr::generate` [`KeyMgr`]: https://docs.rs/tor-keymgr/0.4.0/tor_keymgr/struct.KeyMgr.html [ROFF]: https://crates.io/crates/clap_mangen [arti#955]: https://gitlab.torproject.org/tpo/core/arti/-/issues/955