diff --git a/README.md b/README.md index 21f4c35d..f0649175 100644 --- a/README.md +++ b/README.md @@ -22,8 +22,7 @@ Whatever your use case, `step-ca` is easy to use and hard to misuse, thanks to [ [Website](https://smallstep.com/certificates) | [Documentation](https://smallstep.com/docs) | -[Installation Guide](#installation-guide) | -[Quickstart](#quickstart) | +[Installation](https://smallstep.com/docs/step-ca/installation) | [Getting Started](https://smallstep.com/docs/step-ca/getting-started) | [Contributor's Guide](./docs/CONTRIBUTING.md) @@ -103,270 +102,9 @@ ACME is the protocol used by Let's Encrypt to automate the issuance of HTTPS cer - [Install root certificates](https://smallstep.com/docs/step-cli/reference/certificate/install/) on your machine and browsers, so your CA is trusted - [Inspect](https://smallstep.com/docs/step-cli/reference/certificate/inspect/) and [lint](https://smallstep.com/docs/step-cli/reference/certificate/lint/) certificates -## Installation Guide +## Installation -These instructions will install an OS specific version of the `step-ca` binary on -your local machine. - -Want to build from source? See [our contributor's guide](./docs/CONTRIBUTING.md) - -### Mac OS - -Install `step` and `step-ca` together, via [Homebrew](https://brew.sh/): - -``` -$ brew install step -``` - -### Linux - -> **Note:** The [`step` CLI tool](https://github.com/smallstep/cli) is the easiest way to initialize, configure, and control `step-ca`. While `step` is not technically required to run `step-ca`, it is very much recommended. - -#### Debian - -1. Install `step`. - - Download the Debian package from the - [latest `step` release](https://github.com/smallstep/cli/releases/latest): - - ``` - $ wget https://github.com/smallstep/cli/releases/download/vX.Y.Z/step-cli_X.Y.Z_amd64.deb - ``` - - Install the Debian package: - - ``` - $ sudo dpkg -i step-cli_X.Y.Z_amd64.deb - ``` - -2. Install `step-ca`. - - Download the Debian package from the [latest `step-ca` release](https://github.com/smallstep/certificates/releases/latest): - - ``` - $ wget https://github.com/smallstep/certificates/releases/download/vX.Y.Z/step-ca_X.Y.Z_amd64.deb - ``` - - Install the Debian package: - - ``` - $ sudo dpkg -i step-ca_X.Y.Z_amd64.deb - ``` - -#### Arch Linux - -We are using the [Arch User Repository](https://aur.archlinux.org) to distribute -`step` binaries for Arch Linux. - -* The `step` binary tarball can be found [here](https://aur.archlinux.org/packages/step-cli-bin/). -* The `step-ca` binary tarball can be found [here](https://aur.archlinux.org/packages/step-ca-bin/). - -You can use [pacman](https://www.archlinux.org/pacman/) to install the packages. - -#### RHEL/CentOS - -1. Install `step`. - - Download the Linux tarball from the - [latest `step` release](https://github.com/smallstep/cli/releases/latest): - - ``` - $ wget -O step-cli.tar.gz https://github.com/smallstep/cli/releases/download/vX.Y.Z/step_linux_X.Y.Z_amd64.tar.gz - ``` - - Install `step` by unzipping and copying the executable over to `/usr/bin`: - - ``` - $ tar -xf step-cli.tar.gz - $ sudo cp step_X.Y.Z/bin/step /usr/bin - ``` - -2. Install `step-ca`. - - Download the Linux package from the [latest `step-ca` release](https://github.com/smallstep/certificates/releases/latest): - - ``` - $ wget -O step-ca.tar.gz https://github.com/smallstep/certificates/releases/download/vX.Y.Z/step-ca_linux_X.Y.Z_amd64.tar.gz - ``` - - Install `step-ca` by unzipping and copying the executable over to `/usr/bin`: - - ``` - $ tar -xf step-ca.tar.gz - $ sudo cp step-ca_X.Y.Z/bin/step-ca /usr/bin - ``` - -See the [`systemctl` setup section](https://smallstep.com/docs/step-ca/certificate-authority-server-production#running-step-ca-as-a-daemon) for a -guide on configuring `step-ca` as a daemon. - -### Kubernetes - -We publish [helm charts](https://hub.helm.sh/charts/smallstep/step-certificates) for easy installation on kubernetes: - -``` -helm install step-certificates -``` - -> -> -> If you're using Kubernetes, make sure you [check out -> autocert](https://github.com/smallstep/autocert): a kubernetes add-on that builds on `step -> certificates` to automatically inject TLS/HTTPS certificates into your containers. - -### Docker - -See our [Docker getting started guide](https://smallstep.com/docs/tutorials/docker-tls-certificate-authority) - -### Test - -
$ step version
-Smallstep CLI/0.10.0 (darwin/amd64)
-Release Date: 2019-04-30 19:01 UTC
-
-$ step-ca version
-Smallstep CA/0.10.0 (darwin/amd64)
-Release Date: 2019-04-30 19:02 UTC
- -## Quickstart - -In the following guide we'll run a simple `hello` server that requires clients -to connect over an authorized and encrypted channel using HTTPS. `step-ca` -will issue certificates to our server, allowing it to authenticate and encrypt -communication. - -![Animated terminal showing step certificates in practice](https://github.com/smallstep/certificates/raw/master/docs/images/step-ca-2-legged.gif) - -Let's get started! - -### Prerequisites - -* [`step`](#installation-guide) -* [golang](https://golang.org/doc/install) - -### Let's get started! - -#### 1. Run `step ca init` to create your CA's keys & certificates and configure `step-ca`: - -
$ step ca init
-✔ What would you like to name your new PKI? (e.g. Smallstep): Example Inc.
-✔ 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 address will your new CA listen at? (e.g. :443): 127.0.0.1:8080
-✔ What would you like to name the first provisioner for your new CA? (e.g. you@smallstep.com): bob@example.com
-✔ What do you want your password to be? [leave empty and we'll generate one]: abc123
-
-Generating root certificate...
-all done!
-
-Generating intermediate certificate...
-all done!
-
-✔ Root certificate: /Users/bob/src/github.com/smallstep/step/.step/certs/root_ca.crt
-✔ Root private key: /Users/bob/src/github.com/smallstep/step/.step/secrets/root_ca_key
-✔ Root fingerprint: 702a094e239c9eec6f0dcd0a5f65e595bf7ed6614012825c5fe3d1ae1b2fd6ee
-✔ Intermediate certificate: /Users/bob/src/github.com/smallstep/step/.step/certs/intermediate_ca.crt
-✔ Intermediate private key: /Users/bob/src/github.com/smallstep/step/.step/secrets/intermediate_ca_key
-✔ Default configuration: /Users/bob/src/github.com/smallstep/step/.step/config/defaults.json
-✔ Certificate Authority configuration: /Users/bob/src/github.com/smallstep/step/.step/config/ca.json
-
-Your PKI is ready to go. To generate certificates for individual services see 'step help ca'.
- -This command will: - -- Generate [password protected](https://github.com/smallstep/certificates/blob/master/docs/GETTING_STARTED.md#passwords) private keys for your CA to sign certificates -- Generate a root and [intermediate signing certificate](https://security.stackexchange.com/questions/128779/why-is-it-more-secure-to-use-intermediate-ca-certificates) for your CA -- Create a JSON configuration file for `step-ca` (see [configuration docs](https://smallstep.com/docs/step-ca/configuration) for details) - -You can find these artifacts in `$STEPPATH` (or `~/.step` by default). - -#### 2. Start `step-ca`: - -You'll be prompted for your password from the previous step, to decrypt the CA's private signing key: - -
$ step-ca $(step path)/config/ca.json
-Please enter the password to decrypt /Users/bob/src/github.com/smallstep/step/.step/secrets/intermediate_ca_key: abc123
-2019/02/18 13:28:58 Serving HTTPS on 127.0.0.1:8080 ...
- -#### 3. Copy our `hello world` golang server. - -``` -$ cat > srv.go <$ step ca certificate localhost srv.crt srv.key -✔ Key ID: rQxROEr7Kx9TNjSQBTETtsu3GKmuW9zm02dMXZ8GUEk (bob@example.com) -✔ Please enter the password to decrypt the provisioner key: abc123 -✔ CA: https://localhost:8080/1.0/sign -✔ Certificate: srv.crt -✔ Private Key: srv.key - -$ step certificate inspect --bundle srv.crt -Certificate: - Data: - Version: 3 (0x2) - Serial Number: 140439335711218707689123407681832384336 (0x69a7a1d7f6f22f68059d2d9088307750) - Signature Algorithm: ECDSA-SHA256 - Issuer: CN=Example Inc. Intermediate CA - Validity - Not Before: Feb 18 21:32:35 2019 UTC - Not After : Feb 19 21:32:35 2019 UTC - Subject: CN=localhost -... -Certificate: - Data: - Version: 3 (0x2) - Serial Number: 207035091234452090159026162349261226844 (0x9bc18217bd560cf07db23178ed90835c) - Signature Algorithm: ECDSA-SHA256 - Issuer: CN=Example Inc. Root CA - Validity - Not Before: Feb 18 21:27:21 2019 UTC - Not After : Feb 15 21:27:21 2029 UTC - Subject: CN=Example Inc. Intermediate CA -... - -Note that `step` and `step-ca` handle details like [certificate bundling](https://smallstep.com/blog/everything-pki.html#intermediates-chains-and-bundling) for you. - -#### 5. Run the simple server. - -
$ go run srv.go &
- -#### 6. Get the root certificate from the Step CA. - -In a new Terminal window: - -
$ step ca root root.crt
-The root certificate has been saved in root.crt.
- -#### 7. Make an authenticated, encrypted curl request to your server using HTTP over TLS. - -
$ curl --cacert root.crt https://localhost:8443/hi
-Hello, world!
- -*All Done!* - -Check out the [Getting Started](./docs/GETTING_STARTED.md) guide for more examples -and best practices on running Step CA in production. +See our installation docs [here](https://smallstep.com/docs/step-ca/installation). ## Documentation