alexvanin/certificates
1
0
Fork 0
forked from TrueCloudLab/certificates
Code Pull requests Activity

docs: docker bit of grammar adjustment.

Browse source
This commit is contained in:
max furman 2019-04-08 15:02:19 -07:00
parent 82aa425d15
commit 730433fca0
1 changed files with 62 additions and 83 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

145
docs/docker.md
View file

@ -6,82 +6,80 @@ For short, we will use **step-ca** to refer to [step certificates](https://githu
## Requirements ## Requirements
To be able to follow this guide you need to install [step 1. To follow this guide you will need to [install step
cli](https://github.com/smallstep/cli). Follow the installation instructions to cli](https://github.com/smallstep/cli#installation-guide).
install it in your environment.
## Getting the image 2. Get the docker image.
The first thing that we need to run step-ca is pull the image from docker. Get Get the latest version of **step-ca** from the [step-ca docker
the latest version from the [step-ca docker hub](https://hub.docker.com/r/smallstep/step-ca):
hub](https://hub.docker.com/r/smallstep/step-ca) and run:
```sh ```sh
docker pull smallstep/step-ca $ docker pull smallstep/step-ca
``` ```
## Volumes 3. Create the required volumens.
To be able to run step-ca we need to create a volume in docker where we will We need to create a volume in docker where we will store our PKI as well as
store our PKI as well as the step-ca configuration file. the step-ca configuration file.
To create a volume just run: ```sh
$ docker volume create step
```
```sh 4. Intialize the PKI.
docker volume create step
```
## Initializing the PKI The simple way to do this is to run an interactive terminal:
The simpler way to do this is to run an interactive terminal and initialize it: ```sh
$ docker run -it -v step:/home/step smallstep/step-ca sh
``` ~ $ step ca init
$ docker run -it -v step:/home/step smallstep/step-ca sh ✔ What would you like to name your new PKI? (e.g. Smallstep): Smallstep
~ $ step ca init ✔ What DNS names or IP addresses would you like to add to your new CA? (e.g. ca.smallstep.com[,1.1.1.1,etc.]): localhost
✔ What would you like to name your new PKI? (e.g. Smallstep): Smallstep ✔ What address will your new CA listen at? (e.g. :443): :9000
✔ What DNS names or IP addresses would you like to add to your new CA? (e.g. ca.smallstep.com[,1.1.1.1,etc.]): localhost ✔ What would you like to name the first provisioner for your new CA? (e.g. you@smallstep.com): admin
✔ What address will your new CA listen at? (e.g. :443): :9000 ✔ What do you want your password to be? [leave empty and we'll generate one]: <your password here>
✔ What would you like to name the first provisioner for your new CA? (e.g. you@smallstep.com): admin
✔ What do you want your password to be? [leave empty and we'll generate one]: <your password here>
Generating root certificate... Generating root certificate...
all done! all done!
Generating intermediate certificate... Generating intermediate certificate...
all done! all done!
✔ Root certificate: /home/step/certs/root_ca.crt ✔ Root certificate: /home/step/certs/root_ca.crt
✔ Root private key: /home/step/secrets/root_ca_key ✔ Root private key: /home/step/secrets/root_ca_key
✔ Root fingerprint: f9e45ae9ec5d42d702ce39fd9f3125372ce54d0b29a5ff3016b31d9b887a61a4 ✔ Root fingerprint: f9e45ae9ec5d42d702ce39fd9f3125372ce54d0b29a5ff3016b31d9b887a61a4
✔ Intermediate certificate: /home/step/certs/intermediate_ca.crt ✔ Intermediate certificate: /home/step/certs/intermediate_ca.crt
✔ Intermediate private key: /home/step/secrets/intermediate_ca_key ✔ Intermediate private key: /home/step/secrets/intermediate_ca_key
✔ Default configuration: /home/step/config/defaults.json ✔ Default configuration: /home/step/config/defaults.json
✔ Certificate Authority configuration: /home/step/config/ca.json ✔ Certificate Authority configuration: /home/step/config/ca.json
Your PKI is ready to go. To generate certificates for individual services see 'step help ca'. Your PKI is ready to go. To generate certificates for individual services see 'step help ca'.
``` ```
Our image is expecting the password to be placed in /home/step/secrets/password 5. Place the PKI root password in a known location.
you can simple go in to the terminal again and write that file:
```sh Our image is expecting the password to be placed in `/home/step/secrets/password`
$ docker run -it -v step:/home/step smallstep/step-ca sh you can simple go in to the terminal again and write that file:
~ $ echo <your password here> > /home/step/secrets/password
```
At this time everything is ready to run step-ca. ```sh
$ docker run -it -v step:/home/step smallstep/step-ca sh
~ $ echo <your password here> > /home/step/secrets/password
```
At this time everything is ready to run step-ca!
## Running step certificates ## Running step certificates
Now that we have the volume and we have initialized the PKI we can run step-ca Now that we have configured our environment we are ready to run step-ca.
and expose locally the server address with:
Expose the server address locally and run the step-ca with:
```sh ```sh
docker run -d -p 127.0.0.1:9000:9000 -v step:/home/step smallstep/step-ca $ docker run -d -p 127.0.0.1:9000:9000 -v step:/home/step smallstep/step-ca
``` ```
You can verify with curl that the service is running: Let's verify that the service is running with curl:
```sh ```sh
$ curl https://localhost:9000/health $ curl https://localhost:9000/health
curl: (60) SSL certificate problem: unable to get local issuer certificate curl: (60) SSL certificate problem: unable to get local issuer certificate
@ -105,32 +103,12 @@ accepted certificate authority.
## Dev environment bootstrap ## Dev environment bootstrap
To initialize the development environment we need to go back to [Initializing To initialize the development environment we need to grab the Root fingerprint
the PKI](#initializing-the-pki) and grab the Root fingerprint. In our case from the [Initializing the PKI](#initializing-the-pki) step earlier. In the
case of this example:
`f9e45ae9ec5d42d702ce39fd9f3125372ce54d0b29a5ff3016b31d9b887a61a4`. With the `f9e45ae9ec5d42d702ce39fd9f3125372ce54d0b29a5ff3016b31d9b887a61a4`. With the
fingerprint we can bootstrap our dev environment. fingerprint we can bootstrap our dev environment.
```sh
$ step ca bootstrap --ca-url https://localhost:9000 --fingerprint f9e45ae9ec5d42d702ce39fd9f3125372ce54d0b29a5ff3016b31d9b887a61a4
The root certificate has been saved in ~/.step/certs/root_ca.crt.
Your configuration has been saved in ~/.step/config/defaults.json.
```
From this moment forward [step cli](https://github.com/smallstep/cli) is
configured properly to use step certificates.
But curl and the rest of your environment won't accept the root certificate, we
can install the root certificate and everything would be ready.
```sh
$ step certificate install ~/.step/certs/root_ca.crt
Password:
Certificate ~/.step/certs/root_ca.crt has been installed.
```
We can skip this last step if we go back to the bootstrap and run it with the
`--install` flag:
```sh ```sh
$ step ca bootstrap --ca-url https://localhost:9000 --fingerprint f9e45ae9ec5d42d702ce39fd9f3125372ce54d0b29a5ff3016b31d9b887a61a4 --install $ step ca bootstrap --ca-url https://localhost:9000 --fingerprint f9e45ae9ec5d42d702ce39fd9f3125372ce54d0b29a5ff3016b31d9b887a61a4 --install
The root certificate has been saved in ~/.step/certs/root_ca.crt. The root certificate has been saved in ~/.step/certs/root_ca.crt.
@ -138,25 +116,24 @@ Your configuration has been saved in ~/.step/config/defaults.json.
Installing the root certificate in the system truststore... done. Installing the root certificate in the system truststore... done.
``` ```
Now curl will not complain: Now [step cli](https://github.com/smallstep/cli) is configured to use step-ca
and our new root certificate is trusted by our local environment.
```sh ```sh
$ curl https://localhost:9000/health $ curl https://localhost:9000/health
{"status":"ok"} {"status":"ok"}
``` ```
And you will be able to run web services using TLS (and mTLS): And we are able to run web services configured with TLS (and mTLS):
```sh ```sh
$ $ step ca certificate localhost localhost.crt localhost.key ~ $ step ca certificate localhost localhost.crt localhost.key
✔ Key ID: aTPGWP0qbuQdflR5VxtNouDIOXyNMH1H9KAZKP-UcHo (admin) ✔ Key ID: aTPGWP0qbuQdflR5VxtNouDIOXyNMH1H9KAZKP-UcHo (admin)
✔ Please enter the password to decrypt the provisioner key: ✔ Please enter the password to decrypt the provisioner key:
✔ CA: https://localhost:9000/1.0/sign ✔ CA: https://localhost:9000/1.0/sign
✔ Certificate: localhost.crt ✔ Certificate: localhost.crt
✔ Private Key: localhost.key ✔ Private Key: localhost.key
$ step ca root root_ca.crt ~ $ step ca root root_ca.crt
The root certificate has been saved in root_ca.crt. The root certificate has been saved in root_ca.crt.
$ python <<EOF ~ $ python <<EOF
import BaseHTTPServer, ssl import BaseHTTPServer, ssl
class H(BaseHTTPServer.BaseHTTPRequestHandler): class H(BaseHTTPServer.BaseHTTPRequestHandler):
def do_GET(self): def do_GET(self):
@ -168,9 +145,11 @@ httpd.serve_forever()
EOF EOF
``` ```
And in another terminal or in your browser: Test from another terminal:
```sh ```sh
$ curl https://localhost:8443 $ curl https://localhost:8443
👋 Hello! Welcome to TLS 🔒✅ 👋 Hello! Welcome to TLS 🔒✅
``` ```
Or visit `https://localhost:8443` from your browser.