chrissewell/hetty
1
0
Fork 0
mirror of https://github.com/dstotijn/hetty.git synced 2025-07-01 18:47:29 -04:00
Code Issues Packages Projects Releases Wiki Activity

Documenting CA certificates setup for hetty (#21)

Browse Source 
* Documenting CA certificates setup for hetty

- Provides more accessible instructions on CA certificates
- New sections provided for "Certificate Setup and Installation"
- Configuring certificates for hetty using defaults and direct CLI
  arguments
- Trusting CA certificates on Windows, macOS, and Ubuntu
- Mention for additional Linux distros not covered by Ubuntu

Ref: #12

* Updated README to show instructions for generating CA cert/key with both Hetty and OpenSSL

* Update README.md

Co-authored-by: David Stotijn <dstotijn@gmail.com>

* Apply suggestions from code review

Co-authored-by: David Stotijn <dstotijn@gmail.com>

* Removed suggestion on possible HSTS error from README as it could be irrelevant or misleading

Co-authored-by: David Stotijn <dstotijn@gmail.com>
This commit is contained in:
Tom
2020-10-08 13:04:57 -04:00
committed by GitHub
parent fa41e9c46c
commit 13240109b6
1 changed files with 79 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

81
README.md
View File

@ -86,8 +86,85 @@ Usage of ./hetty:
CA private key filepath. Creates a new CA private key if file doesn't exist (default "~/.hetty/hetty_key.pem") CA private key filepath. Creates a new CA private key if file doesn't exist (default "~/.hetty/hetty_key.pem")
``` ```
⚠️ _Todo: Write instructions for installing CA certificate in local CA store, and_ ## Certificate Setup and Installation
_configuring Hetty to be used as a proxy server._
In order for Hetty to proxy requests going to HTTPS endpoints, a root CA certificate for
Hetty will need to be set up. Furthermore, the CA certificate may need to be
installed to the host for them to be trusted by your browser. The following steps
will cover how you can generate your certificate, provide them to hetty, and how
you can install them in your local CA store.
⚠️ _This process was done on a Linux machine but should_
_provide guidance on Windows and macOS as well._
### Generating CA certificates
You can generate a CA keypair two different ways. The first is bundled directly
with Hetty, and simplifies the process immensely. The alternative is using OpenSSL
to generate them, which provides more control over expiration time and cryptography
used, but requires you install the OpenSSL tooling. The first is suggested for any
beginners trying to get started.
#### Generating CA certificates with hetty
Hetty will generate the default key and certificate on its own if none are supplied
or found in `~/.hetty/` when first running the CLI. To generate a default key and
certificate with hetty, simply run the command with no arguments
```sh
hetty
```
You should now have a key and certificate located at `~/.hetty/hetty_key.pem` and
`~/.hetty/hetty_cert.pem` respectively.
#### Generating CA certificates with OpenSSL
You can start off by generating a new key and CA certificate which will both expire
after a month.
```sh
mkdir ~/.hetty
openssl req -newkey rsa:2048 -new -nodes -x509 -days 31 -keyout ~/.hetty/hetty_key.pem -out ~/.hetty/hetty_cert.pem
```
The default location which `hetty` will check for the key and CA certificate is under
`~/.hetty/`, at `hetty_key.pem` and `hetty_cert.pem` respectively. You can move them
here and `hetty` will detect them automatically. Otherwise, you can specify the
location of these as arguments to `hetty`.
```
hetty -key key.pem -cert cert.pem
```
### Trusting the CA certificate
In order for your browser to allow traffic to the local Hetty proxy, you may need
to install these certificates to your local CA store.
On Ubuntu, you can update your local CA store with the certificate by running the
following commands:
```sh
sudo cp ~/.hetty/hetty_cert.pem /usr/local/share/ca-certificates/hetty.crt
sudo update-ca-certificates
```
On Windows, you would add your certificate by using the Certificate Manager. You
can launch that by running the command:
```batch
certmgr.msc
```
On macOS, you can add your certificate by using the Keychain Access program. This
can be found under `Application/Utilities/Keychain Access.app`. After opening this,
drag the certificate into the app. Next, open the certificate in the app, enter the
_Trust_ section, and under _When using this certificate_ select _Always Trust_.
_Note: Various Linux distributions may require other steps or commands for updating_
_their certificate authority. See the documentation relevant to your distribution for_
_more information on how to update the system to trust your self-signed certificate._
## Vision and roadmap ## Vision and roadmap