# Appendix G: Managing authorized client data \[CLIENT-AUTH-MGMT\] Hidden services and clients can configure their authorized client data either using the torrc, or using the control port. This section presents a suggested scheme for configuring client authorization. Please see appendix \[HIDSERVDIR-FORMAT\] for more information about relevant hidden service files. (NOTE: client authorization is implemented as of 0.3.5.1-alpha.) G.1. Configuring client authorization using torrc G.1.1. Hidden Service side configuration ```text A hidden service that wants to enable client authorization, needs to populate the "authorized_clients/" directory of its HiddenServiceDir directory with the ".auth" files of its authorized clients. When Tor starts up with a configured onion service, Tor checks its /authorized_clients/ directory for ".auth" files, and if any recognized and parseable such files are found, then client authorization becomes activated for that service. G.1.2. Service-side bookkeeping This section contains more details on how onion services should be keeping track of their client ".auth" files. For the "descriptor" authentication type, the ".auth" file MUST contain the x25519 public key of that client. Here is a suggested file format: :: Here is an an example: descriptor:x25519:OM7TGIVRYMY6PFX6GAC6ATRTA5U6WW6U7A4ZNHQDI6OVL52XVV2Q Tor SHOULD ignore lines it does not recognize. Tor SHOULD ignore files that don't use the ".auth" suffix. G.1.3. Client side configuration A client who wants to register client authorization data for onion services needs to add the following line to their torrc to indicate the directory which hosts ".auth_private" files containing client-side credentials for onion services: ClientOnionAuthDir The contains a file with the suffix ".auth_private" for each onion service the client is authorized with. Tor should scan the directory for ".auth_private" files to find which onion services require client authorization from this client. For the "descriptor" auth-type, a ".auth_private" file contains the private x25519 key: :descriptor:x25519: The keypair used for client authorization is created by a third party tool for which the public key needs to be transferred to the service operator in a secure out-of-band way. The third party tool SHOULD add appropriate headers to the private key file to ensure that users won't accidentally give out their private key. G.2. Configuring client authorization using the control port G.2.1. Service side A hidden service also has the option to configure authorized clients using the control port. The idea is that hidden service operators can use controller utilities that manage their access control instead of using the filesystem to register client keys. Specifically, we require a new control port command ADD_ONION_CLIENT_AUTH which is able to register x25519/ed25519 public keys tied to a specific authorized client. [XXX figure out control port command format] Hidden services who use the control port interface for client auth need to perform their own key management. G.2.2. Client side There should also be a control port interface for clients to register authorization data for hidden services without having to use the torrc. It should allow both generation of client authorization private keys, and also to import client authorization data provided by a hidden service This way, Tor Browser can present "Generate client auth keys" and "Import client auth keys" dialogs to users when they try to visit a hidden service that is protected by client authorization. Specifically, we require two new control port commands: IMPORT_ONION_CLIENT_AUTH_DATA GENERATE_ONION_CLIENT_AUTH_DATA which import and generate client authorization data respectively. [XXX how does key management work here?] [XXX what happens when people use both the control port interface and the filesystem interface?] ```