certificates/README.md

137 lines
10 KiB
Markdown
Raw Normal View History

2018-11-01 07:46:13 +00:00
# Step Certificates
2020-07-20 21:10:36 +00:00
`step-ca` is an online certificate authority for secure, automated certificate management. It's the server counterpart to the [`step` CLI tool](https://github.com/smallstep/cli).
2020-07-09 01:42:43 +00:00
You can use it to:
2020-07-20 21:10:36 +00:00
- Issue X.509 certificates for your internal infrastructure:
- HTTPS certificates that [work in browsers](https://smallstep.com/blog/step-v0-8-6-valid-HTTPS-certificates-for-dev-pre-prod.html) ([RFC5280](https://tools.ietf.org/html/rfc5280) and [CA/Browser Forum](https://cabforum.org/baseline-requirements-documents/) compliance)
- TLS certificates for VMs, containers, APIs, mobile clients, database connections, printers, wifi networks, toaster ovens...
- Client certificates to [enable mutual TLS (mTLS)](https://smallstep.com/hello-mtls) in your infra. mTLS is an optional feature in TLS where both client and server authenticate each other. Why add the complexity of a VPN when you can safely use mTLS over the public internet?
- Issue SSH certificates:
- For people, in exchange for single sign-on ID tokens
- For hosts, in exchange for cloud instance identity documents
- Easily automate certificate management:
- It's an ACME v2 server
- It has a JSON API
- It comes with a [Go wrapper](./examples#user-content-basic-client-usage)
- ... and there's a [command-line client](https://github.com/smallstep/cli) you can use in scripts!
2020-10-27 23:20:45 +00:00
Whatever your use case, `step-ca` is easy to use and hard to misuse, thanks to [safe, sane defaults](https://smallstep.com/docs/step-ca/certificate-authority-server-production#sane-cryptographic-defaults).
---
**Don't want to run your own CA?**
To get up and running quickly, or as an alternative to running your own `step-ca` server, consider creating a [free hosted smallstep Certificate Manager authority](https://info.smallstep.com/certificate-manager-early-access-mvp/).
---
2021-10-20 22:53:04 +00:00
**Questions? Find us in [Discussions](https://github.com/smallstep/certificates/discussions) or [Join our Discord](https://u.step.sm/discord).**
2020-07-09 01:42:43 +00:00
[Website](https://smallstep.com/certificates) |
2020-10-27 23:20:45 +00:00
[Documentation](https://smallstep.com/docs) |
[Installation](https://smallstep.com/docs/step-ca/installation) |
2020-10-27 23:20:45 +00:00
[Getting Started](https://smallstep.com/docs/step-ca/getting-started) |
[Contributor's Guide](./docs/CONTRIBUTING.md)
2020-07-20 21:10:36 +00:00
[![GitHub release](https://img.shields.io/github/release/smallstep/certificates.svg)](https://github.com/smallstep/certificates/releases/latest)
[![Go Report Card](https://goreportcard.com/badge/github.com/smallstep/certificates)](https://goreportcard.com/report/github.com/smallstep/certificates)
[![Build Status](https://travis-ci.com/smallstep/certificates.svg?branch=master)](https://travis-ci.com/smallstep/certificates)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![CLA assistant](https://cla-assistant.io/readme/badge/smallstep/certificates)](https://cla-assistant.io/smallstep/certificates)
2018-11-01 07:46:13 +00:00
2019-02-16 01:47:20 +00:00
[![GitHub stars](https://img.shields.io/github/stars/smallstep/certificates.svg?style=social)](https://github.com/smallstep/certificates/stargazers)
[![Twitter followers](https://img.shields.io/twitter/follow/smallsteplabs.svg?label=Follow&style=social)](https://twitter.com/intent/follow?screen_name=smallsteplabs)
2021-12-07 18:02:44 +00:00
![star us](https://github.com/smallstep/certificates/raw/master/docs/images/star.gif)
## Features
2020-07-20 21:10:36 +00:00
### 🦾 A fast, stable, flexible private CA
Setting up a *public key infrastructure* (PKI) is out of reach for many small teams. `step-ca` makes it easier.
2020-07-20 21:10:36 +00:00
- Choose key types (RSA, ECDSA, EdDSA) and lifetimes to suit your needs
- [Short-lived certificates](https://smallstep.com/blog/passive-revocation.html) with automated enrollment, renewal, and passive revocation
2020-07-09 01:42:43 +00:00
- Capable of high availability (HA) deployment using [root federation](https://smallstep.com/blog/step-v0.8.3-federation-root-rotation.html) and/or multiple intermediaries
2020-10-27 23:20:45 +00:00
- Can operate as [an online intermediate CA for an existing root CA](https://smallstep.com/docs/tutorials/intermediate-ca-new-ca)
- [Badger, BoltDB, Postgres, and MySQL database backends](https://smallstep.com/docs/step-ca/configuration#databases)
2020-09-17 03:53:58 +00:00
### ⚙️ Many ways to automate
2020-07-20 21:10:36 +00:00
There are several ways to authorize a request with the CA and establish a chain of trust that suits your flow.
2020-07-09 01:42:43 +00:00
2020-07-20 21:10:36 +00:00
You can issue certificates in exchange for:
- [ACME challenge responses](#your-own-private-acme-server) from any ACMEv2 client
- [OAuth OIDC single sign-on tokens](https://smallstep.com/blog/easily-curl-services-secured-by-https-tls.html), eg:
- ID tokens from Okta, GSuite, Azure AD, Auth0.
- ID tokens from an OAuth OIDC service that you host, like [Keycloak](https://www.keycloak.org/) or [Dex](https://github.com/dexidp/dex)
- [Cloud instance identity documents](https://smallstep.com/blog/embarrassingly-easy-certificates-on-aws-azure-gcp/), for VMs on AWS, GCP, and Azure
2021-07-19 18:05:01 +00:00
- [Single-use, short-lived JWK tokens](https://smallstep.com/docs/step-ca/provisioners#jwk) issued by your CD tool — Puppet, Chef, Ansible, Terraform, etc.
2020-07-20 21:10:36 +00:00
- A trusted X.509 certificate (X5C provisioner)
- A SCEP challenge (SCEP provisioner)
- An SSH host certificates needing renewal (the SSHPOP provisioner)
2021-07-19 18:05:01 +00:00
- Learn more in our [provisioner documentation](https://smallstep.com/docs/step-ca/provisioners)
2019-09-17 16:52:36 +00:00
2020-07-20 21:10:36 +00:00
### 🏔 Your own private ACME server
2020-07-09 01:42:43 +00:00
2020-07-20 21:10:36 +00:00
ACME is the protocol used by Let's Encrypt to automate the issuance of HTTPS certificates. It's _super easy_ to issue certificates to any ACMEv2 ([RFC8555](https://tools.ietf.org/html/rfc8555)) client.
2020-07-09 01:42:43 +00:00
- [Use ACME in development & pre-production](https://smallstep.com/blog/private-acme-server/#local-development--pre-production)
2020-07-13 16:28:46 +00:00
- Supports the most popular [ACME challenge types](https://letsencrypt.org/docs/challenge-types/):
- For `http-01`, place a token at a well-known URL to prove that you control the web server
- For `dns-01`, add a `TXT` record to prove that you control the DNS record set
- For `tls-alpn-01`, respond to the challenge at the TLS layer ([as Caddy does](https://caddy.community/t/caddy-supports-the-acme-tls-alpn-challenge/4860)) to prove that you control the web server
2020-07-09 01:42:43 +00:00
- Works with any ACME client. We've written examples for:
- [certbot](https://smallstep.com/docs/tutorials/acme-protocol-acme-clients#certbot)
- [acme.sh](https://smallstep.com/docs/tutorials/acme-protocol-acme-clients#acmesh)
- [win-acme](https://smallstep.com/docs/tutorials/acme-protocol-acme-clients#win-acme)
- [Caddy](https://smallstep.com/docs/tutorials/acme-protocol-acme-clients#caddy-v2)
- [Traefik](https://smallstep.com/docs/tutorials/acme-protocol-acme-clients#traefik)
- [Apache](https://smallstep.com/docs/tutorials/acme-protocol-acme-clients#apache)
- [nginx](https://smallstep.com/docs/tutorials/acme-protocol-acme-clients#nginx)
2020-07-09 01:42:43 +00:00
- Get certificates programmatically using ACME, using these libraries:
- [`lego`](https://github.com/go-acme/lego) for Golang ([example usage](https://smallstep.com/docs/tutorials/acme-protocol-acme-clients#golang))
- certbot's [`acme` module](https://github.com/certbot/certbot/tree/master/acme) for Python ([example usage](https://smallstep.com/docs/tutorials/acme-protocol-acme-clients#python))
- [`acme-client`](https://github.com/publishlab/node-acme-client) for Node.js ([example usage](https://smallstep.com/docs/tutorials/acme-protocol-acme-clients#node))
2020-08-20 14:43:05 +00:00
- Our own [`step` CLI tool](https://github.com/smallstep/cli) is also an ACME client!
2020-10-27 23:20:45 +00:00
- See our [ACME tutorial](https://smallstep.com/docs/tutorials/acme-challenge) for more
2020-07-20 21:10:36 +00:00
### 👩🏽‍💻 An online SSH Certificate Authority
2019-09-16 04:27:04 +00:00
2020-07-20 21:10:36 +00:00
- Delegate SSH authentication to `step-ca` by using [SSH certificates](https://smallstep.com/blog/use-ssh-certificates/) instead of public keys and `authorized_keys` files
- For user certificates, [connect SSH to your single sign-on provider](https://smallstep.com/blog/diy-single-sign-on-for-ssh/), to improve security with short-lived certificates and MFA (or other security policies) via any OAuth OIDC provider.
- For host certificates, improve security, [eliminate TOFU warnings](https://smallstep.com/blog/use-ssh-certificates/), and set up automated host certificate renewal.
2019-09-16 04:27:04 +00:00
2020-10-27 23:20:45 +00:00
### 🤓 A general purpose PKI tool, via [`step` CLI](https://github.com/smallstep/cli) [integration](https://smallstep.com/docs/step-cli/reference/ca/)
- Generate key pairs where they're needed so private keys are never transmitted across the network
2020-10-27 23:20:45 +00:00
- [Authenticate and obtain a certificate](https://smallstep.com/docs/step-cli/reference/ca/certificate/) using any provisioner supported by `step-ca`
- Securely [distribute root certificates](https://smallstep.com/docs/step-cli/reference/ca/root/) and [bootstrap](https://smallstep.com/docs/step-cli/reference/ca/bootstrap/) PKI relying parties
- [Renew](https://smallstep.com/docs/step-cli/reference/ca/renew/) and [revoke](https://smallstep.com/docs/step-cli/reference/ca/revoke/) certificates issued by `step-ca`
- [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
2018-11-01 07:46:13 +00:00
See our installation docs [here](https://smallstep.com/docs/step-ca/installation).
## Documentation
2019-04-30 00:50:30 +00:00
Documentation can be found in a handful of different places:
2020-10-27 23:20:45 +00:00
1. On the web at https://smallstep.com/docs/step-ca.
2020-02-08 11:31:49 +00:00
2. On the command line with `step help ca xxx` where `xxx` is the subcommand
you are interested in. Ex: `step help ca provisioner list`.
2020-10-27 23:20:45 +00:00
3. In your browser, by running `step help --http=:8080 ca` from the command line
2019-04-30 00:50:30 +00:00
and visiting http://localhost:8080.
2020-10-27 23:20:45 +00:00
4. The [docs](./docs/README.md) folder is being deprecated, but it still has some documentation and tutorials.
2019-06-11 15:28:43 +00:00
2020-07-20 21:10:36 +00:00
## Feedback?
* Tell us what you like and don't like about managing your PKI - we're eager to help solve problems in this space.
* Tell us about a feature you'd like to see! [Add a feature request Issue](https://github.com/smallstep/certificates/issues/new?assignees=&labels=enhancement%2C+needs+triage&template=enhancement.md&title=), [ask on Discussions](https://github.com/smallstep/certificates/discussions), or hit us up on [Twitter](https://twitter.com/smallsteplabs).