Skip to content

Latest commit

 

History

History
235 lines (166 loc) · 9.82 KB

getting-started.mdx

File metadata and controls

235 lines (166 loc) · 9.82 KB
Raw
title html_title description
Getting Started
Getting started with open source step-ca
Learn about step-ca and where to begin

You could write several telephone books about the innards of X.509, asn.1, and the vast topics of infosec, netsec, and public key cryptography that are all part of the design of a Public Key Infrastructure (PKI). It can be a daunting process. To introduce you to the workflow, you can start by setting up a CA server and a TLS-enabled "Hello World" application.

In this guide, you will:

Requirements

You need step and step-ca installed on your system.

Initialize your certificate authority (CA)

The certificate authority (CA) is what you’ll be using to issue and sign certificates, knowing that you can trust anything using a certificate signed by the root certificate.

Run the command step ca init in a terminal to configure your CA. You'll be asked about your project, DNS setup, and other information.

The step ca init command supports several arguments that allow you to tailor your commands. Here are some of the most popular options:

  • Pass --ssh if you want to use SSH certificates (in addition to X.509)
  • Pass separate --password-file and --provisioner-password-file flags to set different signing CA and provisioner passwords.
  • Pass --helm to generate Helm YAML for use with our Helm chart
  • Pass --acme to create an ACME provisioner
  • Pass --remote-management to enable Remote Provisioner Management
Don't want to run your own CA?
To get up and running quickly, consider creating a{' '} free hosted smallstep Certificate Manager authority.

Note that one of the prompts is about the default provisioner, but for now an email address works fine as an identifier.

$ 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:8443
✔ What would you like to name the first provisioner for your new CA? (e.g. [email protected]): [email protected]
✔ What do you want your password to be? [leave empty and we will generate one]: abc123

Generating root certificate...
all done!

Generating intermediate certificate...
all done!

✔ Root certificate: /Users/bob/.step/certs/root_ca.crt
✔ Root private key: /Users/bob/.step/secrets/root_ca_key
✔ Root fingerprint: 702a094e239c9eec6f0dcd0a5f65e595bf7ed6614012825c5fe3d1ae1b2fd6ee
✔ Intermediate certificate: /Users/bob/.step/certs/intermediate_ca.crt
✔ Intermediate private key: /Users/bob/.step/secrets/intermediate_ca_key
✔ Default configuration: /Users/bob/.step/config/defaults.json
✔ Certificate Authority configuration: /Users/bob/.step/config/ca.json

Your PKI is ready to go.

Make a note of the root fingerprint! You'll need it in future steps to establish trust with your CA from other environments or hosts.

Run your certificate authority

Run your certificate authority and pass it the configuration file you just generated.

$ step-ca $(step path)/config/ca.json

Please enter the password to decrypt /Users/bob/.step/secrets/intermediate_ca_key: abc123

2019/02/18 13:28:58 Serving HTTPS on 127.0.0.1:8443 ...

Access your Certificate Authority

Access your CA

You can use step ca and step ssh command groups to interact with the CA. See Basic CA Operations for an overview of common operations.

Access your CA remotely

To access your CA remotely, install and use the step command on clients. Or you can use any ACME client to get certificates.

Because your CA root certificate is a self-signed certificate, it is not automatically trusted by clients. Any new step client must establish a trust relationship with your CA. You can establish a trust relationship by supplying your CA fingerprint to step ca bootstrap. Your CA fingerprint is a cryptographic signature identifying your root CA certificate.

To configure step to access your CA from a new machine, run:

$ step ca bootstrap --ca-url [CA URL] --fingerprint [CA fingerprint]
The root certificate has been saved in /home/alice/.step/certs/root_ca.crt.
Your configuration has been saved in /home/alice/.step/config/defaults.json.

This command downloads the root CA certificate and writes CA connection details to $HOME/.step/config/defaults.json. The step command will now trust your CA. See Basic CA Operations for an overview of common operations.

Don't know your CA fingerprint?
You can get it by running the following on your CA: $ step certificate fingerprint $(step path)/certs/root_ca.crt

You may also wish to establish system-wide trust of your CA, so your certificates will be trusted by curl and other programs. Use the step certificate install command to install your root CA certificate into your system's default trust store:

$ step certificate install $(step path)/certs/root_ca.crt
Certificate /home/alice/.step/certs/root_ca.crt has been installed.
X.509v3 Root CA Certificate (ECDSA P-256) [Serial: 2282...6360]
  Subject:     Example Inc. Root CA
  Issuer:      Example Inc. Root CA
  Valid from:  2021-05-11T21:40:19Z
          to:  2031-05-09T21:40:19Z

Example: Run A Local Web Server Using TLS

Now that the certificate authority is running, you can create an example server and use the new certificate authority to issue an X.509 certificate and connect to the server using HTTP over TLS.

For this example, you'll need to have go installed.

Get a certificate

First, you must ask the CA for a certificate (srv.crt) and private key (srv.key) for the example server on localhost:

$ step ca certificate localhost srv.crt srv.key

✔ Key ID: rQxROEr7Kx9TNjSQBTETtsu3GKmuW9zm02dMXZ8GUEk ([email protected])
✔ Please enter the password to decrypt the provisioner key: abc123
✔ CA: https://localhost:8443/1.0/sign
✔ Certificate: srv.crt
✔ Private Key: srv.key

Run a hello world example server configured for TLS connections

Now you've got your certificate. Next, you can create an example server that runs on localhost and uses TLS.

This example server listens to port 9443 and serves Hello, world! to any client that accepts the server certificate as trusted.

Here's the code for the go server:

package main
import (
    "net/http"
    "log"
)
func HiHandler(w http.ResponseWriter, req *http.Request) {
    w.Header().Set("Content-Type", "text/plain")
    w.Write([]byte("Hello, world!\n"))
}
func main() {
    http.HandleFunc("/hi", HiHandler)
    err := http.ListenAndServeTLS(":9443", "srv.crt", "srv.key", nil)
    if err != nil {
        log.Fatal(err)
    }
}

Run the server as a background process:

{`$ go run srv.go &`}

Connect to the example server

First, try making a curl request to the example server. In a new terminal, run:

$ curl https://localhost:9443/hi

If you already ran step certificate install to install your root CA into your system's default trust store, this command works and you'll see "Hello, World!".

If not, you'll see this error:

curl: (60) SSL certificate problem: unable to get local issuer certificate
More details here: https://curl.haxx.se/docs/sslcerts.html
curl failed to verify the legitimacy of the server and therefore could not
establish a secure connection to it. To learn more about this situation and
how to fix it, please visit the web page mentioned above.

In this case, curl does not yet trust your root CA.

Download the CA's root certificate and pass it into curl to establish trust.

$ step ca root root.crt

The root certificate has been saved in root.crt.

Now you can make a curl request using the root certificate you just downloaded. When you add --cacert root.crt to the curl command, it verifies that the server certificate was signed by the CA, and at that point you will see Hello, world!

$ curl --cacert root.crt https://localhost:9443/hi

Hello, world!

Congratulations! You've just generated and integrated your first certificate using step-ca.

Next Steps

  • Familiarize yourself with Basic CA Operations using step ca and step ssh command groups.
  • Check out the Configuration and Core Concepts sections to learn more about tailoring step-ca to your infrastructure needs.
  • Or, head straight to our tutorials to see more examples of using step-ca in the wild.