.github | ||
api | ||
authority | ||
ca | ||
cmd/step-ca | ||
debian | ||
docker | ||
docs | ||
examples | ||
logging | ||
monitoring | ||
server | ||
.gitignore | ||
.travis.yml | ||
CHANGELOG.md | ||
config.json | ||
Gopkg.lock | ||
Gopkg.toml | ||
LICENSE | ||
Makefile | ||
README.md |
SHHHH, THIS PROJECT HASN'T OFFICIALLY LAUNCHED YET AND THIS REPO IS SUPER SECRET!!!
Step Certificates
An online certificate authority and related tools for secure automated certificate management, so you can use TLS everywhere.
For more information and docs see the Step website and the blog post announcing Step Certificate Authority.
Why?
Managing your own public key infrastructure (PKI) can be tedious and error prone. Good security hygiene is hard. Setting up simple PKI is out of reach for many small teams, and following best practices like proper certificate revocation and rolling is challenging even for experts.
This project is part of smallstep's broader security architecture, which makes it much easier to implement good security practices early, and incrementally improve them as your system matures.
Table of Contents
- Installing
- Documentation
- Terminology
- Getting Started
- Commonly Asked Questions
- Recommended Defaults
- How To Create A New Release
- Versioning
- LICENSE
- CHANGELOG
Installing
These instructions will install an OS specific version of the step
binary on
your local machine.
Mac OS
Install step
via Homebrew:
brew install smallstep/smallstep/step
Linux
Download the latest Debian package from releases:
wget https://github.com/smallstep/certificates/releases/download/X.Y.Z/step_X.Y.Z_amd64.deb
Install the Debian package:
sudo dpkg -i step-ca_X.Y.Z_amd64.deb
Documentation
Documentation can be found in three places:
-
On the command line with
step ca help xxx
wherexxx
is the subcommand you are interested in. Ex:step help ca provisioners list
-
On the web at https://smallstep.com/docs/step-ca
-
In your browser with
step ca help --http :8080
and visiting http://localhost:8080
Terminology
PKI - Public Key Infrastructure
A set of roles, policies, and procedures needed to create, manage, distribute, use, store, and revoke digital certificates and manage public-key encryption. The purpose of a PKI is to facilitate the secure electronic transfer of information for a range of network activities.
Provisioners
Provisioners are people or code that are registered with the CA and authorized to issue "provisioning tokens". Provisioning tokens are single use tokens that can be used to authenticate with the CA and get a certificate.
Getting Started
Demonstrates setting up your own PKI and certificate authority using step ca
and getting certificates using the step
command line tool and SDK.
Prerequisites
Initializing PKI and configuring the Certificate Authority
To initialize a PKI and configure the Step Certificate Authority run:
step ca init
You'll be asked for a name for your PKI. This name will appear in your CA certificates. It doesn't really matter what you choose. The name of your organization or your project will suffice.
If you run:
tree .
You should see:
...
├── config
│ └── ca.json
└── secrets
├── intermediate_ca.crt
├── intermediate_ca_key
├── root_ca.crt
├── root_ca_key
The files created include:
root_ca.crt
androot_ca_key
: the root certificate and private key for your PKIintermediate_ca.crt
andintermediate_ca_key
: the intermediate certificate and private key that will be used to sign leaf certificatesca.json
: the configuration file necessary for running the Step CA.
All of the files endinging in _key
are password protected using the password
you chose during PKI initialization.
What's Inside ca.json
?
ca.json
is responsible for configuring communication, authorization, and
default new certificate values for the Step CA. Below is a short list of
definitions and descriptions of available configuration attributes.
-
root
: location of the root certificate on the filesystem. The root certificate is used to mutually authenticate all api clients of the CA. -
crt
: location of the intermediate certificate on the filesystem. The intermediate certificate is returned alongside each new certificate, allowing the client to complete the certificate chain. -
key
: location of the intermediate private key on the filesystem. The intermediate key signs all new certificates generated by the CA. -
password
: optionally store the password for decrypting the intermediate private key (this should be the same password you chose during PKI initialization). If the value is not stored in configuration then you will be prompted for it when starting the CA. -
address
: e.g.127.0.0.1:8080
- address and port on which the CA will bind and respond to requests. -
dnsNames
: comma separated list of DNS Name(s) for the CA. -
logger
: the default logging format for the CA istext
. The other options isjson
. -
tls
: settings for negotiating communication with the CA; includes acceptable ciphersuites, min/max TLS version, etc. -
authority
: controls the request authorization and signature processes.-
template
: default ASN1DN values for new certificates. -
claims
: default validation for requested attributes in the certificate request. Can be overriden by similar claims objects defined by individual provisioners.-
minTLSCertDuration
: do not allow certificates with a duration less than this value. -
maxTLSCertDuration
: do not allow certificates with a duration greater than this value. -
defaultTLSCertDuration
: if no certificate validity period is specified, use this value. -
disableIssuedAtCheck
: disable a check verifying that provisioning tokens must be issued after the CA has booted. This is one prevention against token reuse. The default value isfalse
. Do not change this unless you know what you are doing.
-
-
provisioners
: list of provisioners. Each provisioner has aname
, associated public/private keys, and an optionalclaims
attribute that will override any values set in the globalclaims
directly underneathauthority
.
-
step ca init
will generate one provisioner. New provisioners can be added by
running step ca provisioner add
.
Running the CA
To start the CA run:
step-ca $STEPPATH/config/ca.step
Set your defaults
This is optional, but we recommend you populate a defaults.json
file with a
few variables that will make your command line experience much more pleasant.
$ cat > $STEPPATH/config/defaults.json
{
"ca-url": "https://<dns-name>:<port>",
"ca-config": "/home/user/.step/config/ca.json"
"root": "/home/user/.step/secrets/root_ca.crt"
}
-
ca-curl: Use the DNS name and port that you used when initializing the CA.
-
root: Path to the root certificate on the file system.
You can always override these values with command-line flags.
Hot Reload
It is important that the CA be able to handle configuration changes with no downtime.
Our CA has a built in reload
function allowing it to:
- Finish processing existing connections while blocking new ones.
- Parse the configuration file and re-initialize the API.
- Begin accepting blocked and new connections.
reload
is triggered by sending a SIGHUP to the PID (see man kill
for your OS) of the Step CA process. A few important details to note when using reload
:
- The location of the modified configuration must be in the same location as it
was in the original invocation of
step-ca
. So, if the original command was
$ step-ca ./.step/config/ca.json
then, upon reload
, the Step CA will read it's new configuration from the same
configuration file.
-
Step CA requires the password to decrypt the intermediate certificate, again, upon
reload
. You can auotmate this in one of two ways:- Use the
--password-file
flag in the original invocation. - Use the top level
password
attribute in theca.json
configuration file.
- Use the
Let's issue a certificate!
There are two steps to issuing a certificate at the command line:
- Generate a provisioning token using your provisioning credentials.
- Generate a CSR and exchange it, along with the provisioning token, for a certificate.
If you would like to generate a certificate from the command line, the Step CLI provides a single command that will prompt you to select and decrypt an authorized provisioner and then request a new certificate.
$ step ca certificate "foo.example.com" foo.crt foo.key
If you would like to generate certificates on demand from an automated configuration management solution (no user input) you would split the above flow into two commands.
$ TOKEN=$(step ca token foo.example.com \
--kid 4vn46fbZT68Uxfs9LBwHkTvrjEvxQqx-W8nnE-qDjts \
--ca-url https://ca.example.com \
--root /path/to/root_ca.crt --password-file /path/to/provisioner/password)
$ step ca certificate "foo.example.com" foo.crt foo.key --token "$TOKEN" \
--ca-url https://ca.example.com --root /path/to/root_ca.crt
You can take a closer look at the contents of the certificate using step certificate inspect
:
$ step certificate inspect foo.crt
List|Add|Remove Provisioners
The Step CA configuration is initialized with one provisioner; one entity that is authorized by the CA to generate provisioning tokens for new certificates. We encourage you to have many provisioners - ideally one for each entity in your infrastructure.
Why should I be using multiple provisioners?
- Each certificate generated by the Step CA contains the ID of the provisioner
that issued the provisioning token authorizing the creation of the cert. This
ID is stored in the X.509 ExtraExtensions of the certificate under
OID: 1.3.6.1.4.1.37476.9000.64.1
and can be inspected by runningstep certificate inspect foo.crt
. These IDs can and should be used to debug and gather information about the origin of a certificate. If every member of your ops team and the configuration management tools all use the same provisioner to authorize new certificates you lose valuable visibility into the workings of your PKI. - Each provisioner should require a unique password to decrypt it's private key -- we can generate unique passwords for you but we can't force you to use them. If you only have one provisioner then every entity in the infrastructure will need access to that one password. Jim from your dev ops team should not be using the same provisioner/password combo to authorize certificates for debugging as Chef is for your CICD - no matter how trustworthy Jim says he is.
Let's begin by listing the existing provisioners:
$ bin/step ca provisioner list
Now let's add a provisioner for Jim.
$ bin/step ca provisioner add jim@smallstep.com --create
NOTE: This change will not affect the Step CA until a reload
is forced by
sending a SIGHUP signal to the process.
List the provisioners again and you will see that nothing has changed.
$ bin/step ca provisioner list
Now let's reload
the CA. You will need to re-enter your intermediate
password unless it's in your ca.json
or your are using --password-file
.
$ ps aux | grep step-ca # to get the PID
$ kill -1 <pid>
Once the CA is running again, list the provisioners, again.
$ bin/step ca provisioner list
Boom! Magic.
Now suppose Jim forgets his password ('come on Jim!'), and he'd like to remove
his old provisioner. Get the kid
(Key ID) of Jim's provisioner by listing
the provisioners and finding the appropriate one. Then run:
$ bin/step ca provisioner remove jim@smallstep.com --kid <kid>
Then reload
the CA and verify that Jim's provisioner is no longer returned
in the provisioner list.
We can also remove all of Jim's provisioners, supposing Jim forgot all the passwords ('really Jim?'), by running the following:
$ bin/step ca provisioner remove jim@smallstep.com --all
The same entity may have multiple provisioners for authorizing different types of certs. Each of these provisioners must have unique keys.
Versioning
We use SemVer for versioning. For the versions available, see the tags on this repository.
License
This project is licensed under the MIT License - see the LICENSE file for details