Knowledge Base

Description

What is an “onion domain”?

.Onion is a top-level Internet domain used by anonymous websites on the Tor network accessibly only from the Tor anonymity browser. This means that standard browsers like Microsoft Edge, Google Chrome, and Mozilla Firefox will not have access to sites using the onion domain as they are unable to navigate the relay of proxy servers from which Tor is created.

Why create an Onion Site?

When you choose to create an onion site, you’re doing so more for the anonymity of site users than anything else. When the domain name is automatically generated for you, you'll receive a randomized address of 56 characters ranging from a-z and 1-9. A v3 address will always end in a 'd' due to the way v3 onion service names are encoded.

What is the difference between V2 and V3 onion address?

V3 onion service has a number security and privacy improvements over V2 which is now deprecated. The most obvious difference between V2 and V3 onion services is the different address format. V3 onion addresses have 56 characters instead of 16 (because they contain a full ed25519 public key, not just the hash of a public key).

What type of TLS certificates are supported for onion domains?

The CAB Forum, recognized as the official regulator of certificate policies, has adopted ballot SC27v3, which dictates Certification Authorities can now issue certificates for the new V3 onion address.

Why would an Onion site need a TLS certificate?

While the onion service provides some of the same protections offered by an HTTPS connection, there are additional benefits a TLS certificate can offer, some listed below:

• Websites with complex setups and that are serving HTTP and HTTPS content
• To help the user verify that the Onion address is indeed the site you are hosting (this would be a manual check done by the user looking at the cert registration information)
• Some services work with protocols, frameworks, and other infrastructure that has HTTPS connection as a requirement
• In case your web server and your tor process are in different machines

What is the process for obtaining a certificate for an onion domain?

This is a two-step process, first enroll for a certificate order, during the enrolment you will include the onion domain and supply a CSR generated from the server where you plan to install the certificate. Secondly, after the order is submitted, proving ownership over each domain is required. To prove domain ownership, a DCV (Domain Control Validation) must be completed for each supplied non-onion domain – see Supported DCV methods for all options.

How do I demonstrate control over my onion domain?

To demonstrate ownership over an onion domain, requires a special procedure which is different from the standard DCV methods. The procedure requires a special Onion CSR be signed from the Tor server. This CSR is different from those you would need to enroll for a certificate, and the process of generating the CSR uses a special algorithm (ed25519) which for this purpose is only to prove ownership of the onion domain.

1. With the Tor server installed, check that the path /var/lib/tor/hidden_service exists as this contains important files for the CSR generation process. The file hostname contains the actual onion domain that will be added to the CSR. The other two files hs_ed25519_public_key and hs_ed25519_secret_key are the public and private keys which will be used when signing the CSR.
   
   Note: It is important not to modify these files as they are mathematically bound to each other, altering the files will break the signatures integrity. If the path or files don't exist, consider restarting the Tor service or reinstalling the Tor server.
2. Once confirmed, the hidden_service directory exists and includes the three mentioned files The next step is to generate the CSR.
   
   Since the OpenSSL stand-alone tool does not currently support the new requirements. Digicert has prepared a python script that helps accomplish this step pretty easily
   (sudo pip install onionmaker).
   
   Before signing the CSR, a random value must be obtained by DigiCert i.e., nvmbbgld0dt1hhn11txgzqdhth5fvqmf.
   
   The command to execute from the terminal will look like the below:
   sudo onionmaker nvmbbgld0dt1hhn11txgzqdhth5fvqmf /var/lib/tor/hidden_service/
   If successful, the CSR should be printed within the terminal window.
   
   The signed CSR will contain the following attributes:
   > caSigningNonce – this is the random value provided to you by DigiCert
   > applicantSigningNonce – this is a random value generated by the applicant that is minimum 64bits
   
3. Respond to DigiCert with an attached copy of the CSR.
   
4. DigiCert will verify the CSR, upon successful validation. The Onion domain will be approved, and the certificate order is issued out.