docs sub repo update

This commit is contained in:
max furman 2019-04-29 17:50:30 -07:00
parent 2b96e7a94c
commit 8ab04bd503
14 changed files with 301 additions and 347 deletions

View file

@ -3,7 +3,7 @@
An online certificate authority and related tools for secure automated certificate management, so you can use TLS everywhere.
[Website](https://smallstep.com) |
[Documentation](https://smallstep.com/docs/certificates) |
[Documentation](#documentation) |
[Installation Guide](#installation-guide) |
[Getting Started](./docs/GETTING_STARTED.md) |
[Contribution Guide](./docs/CONTRIBUTING.md)
@ -321,13 +321,17 @@ and best practices on running Step CA in production.
## Documentation
Documentation can be found in three places:
Documentation can be found in a handful of different places:
1. On the command line with `step ca help xxx` where `xxx` is the subcommand you are interested in. Ex: `step help ca provisioners list`
1. The [docs](./docs) sub-repo has an index of documentation and tutorials.
2. On the web at https://smallstep.com/docs/certificates
2. On the command line with `step ca help xxx` where `xxx` is the subcommand
you are interested in. Ex: `step help ca provisioners list`.
3. On your browser by running `step ca help --http :8080` and visiting http://localhost:8080
3. On the web at https://smallstep.com/docs/certificates.
4. On your browser by running `step ca help --http :8080` from the command line
and visiting http://localhost:8080.
## The Future

View file

@ -479,7 +479,7 @@ one we'll use in this example, is G-Suite.
Navigate to the Google APIs developer console and pick a suitable project from the
top navbar's dropdown.
![Google Dev Console](oidc1.png)
![Google Dev Console](./images/oidc1.png)
In the masthead navigation click **Credentials** (key symbol) and then "OAuth
consent screen" from the subnav. Fill out naming details, all mandatory fields,
@ -492,7 +492,7 @@ Move back to **Credentials** on the subnav and choose "OAuth client ID" from the
**Create credentials** dropdown. Since OIDC will be used from the `step CLI` pick **Other**
from the available options and pick a name (e.g. **Step CLI**).
![Create credential](oidc2.png)
![Create credential](./images/oidc2.png)
On successful completion, a confirmation modal with both `clientID` and
`clientSecret` will be presented. Please note that the `clientSecret` will
@ -500,7 +500,7 @@ allow applications access to the configured OAuth consent screen. However, it
will not allow direct authentication of users without their own MfA credentials
per account.
![OIDC credentials](oidc3.png)
![OIDC credentials](./images/oidc3.png)
Now using `clientID` and `clientSecret` run the following command to add
G-Suite as a provisioner to `step certificates`. Please see [`step ca

40
docs/README.md Normal file
View file

@ -0,0 +1,40 @@
# Step Certificates Documentation
Index of Documentation and Tutorials for using and deploying the `step certificates`.
[![GitHub release](https://img.shields.io/github/release/smallstep/certificates.svg)](https://github.com/smallstep/certificates/releases)
[![Join the chat at https://gitter.im/smallstep/community](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/smallstep/community)
[![CA Image](https://images.microbadger.com/badges/image/smallstep/step-ca.svg)](https://microbadger.com/images/smallstep/step-ca)
[![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)
[![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)
## Index
* **General Info**
* [Website](https://smallstep.com)
* [Installation Guide](../README.md#installation-guide)
* [Getting Started](./GETTING_STARTED.md): in depth guide on getting started
with `step certificates`, including all configuration options.
* [Contribution Guide](./CONTRIBUTING.md)
* [Sane Defaults](./defaults.md): default algorithms and attributes used
in cryptographic primitives and why they were selected.
* [Frequently Asked Questions](./questions.md)
* Check out our [Blog](https://smallstep.com/blog/). We post quality
educational content as well as periodic updates on new releases.
* **API**: Guides to using the API via the `step` CLI.
* [Revoking Certificates](./revocation.md)
* [Persistence Layer](./database.md): description and guide to using `step certificates`'
persistence layer for storing certificate management metadata.
* **Tutorials**: Guides for deploying and getting started with `step` in various environments.
* [Docker](./docker.md)
* [Kubernetes](../autocert/README.md)
## Further Reading
* [Use TLS Everywhere](https://smallstep.com/blog/use-tls.html)
* [Everything you should know about certificates and PKI but are too afraid to ask](https://smallstep.com/blog/everything-pki.html)

228
docs/defaults.md Normal file
View file

@ -0,0 +1,228 @@
# Default Algorithms and Attributes for Tokens, Keys, Certificates, etc.
The `step` ecosystem aims to be a "easy to use and hard to misuse" suite of PKI
tools. This means we need to select sane defaults for the myriad
configuration options that exist when using cryptographic primitives and higher
order abstractions (e.g. JWTs).
Below we document significant configuration options that we have selected as
defaults. These selections will change and evolve over time; security and
cryptography are constantly changing in response to real world pressures. We
intend for this document be an accurate representation of current best practices
in the industry, and to have these practices codified as defaults in the `step
certificates` code base. If you have questions, suggestions, or comments about
any of these decisions please let us know by opening an issue on this repo,
reaching out through [Twitter](twitter.com/smallsteplabs), or through our
[Gitter](https://gitter.im/smallstep/community) to chat with us in real time.
## Tokens
We use JWTs (JSON Web Tokens) to prove authenticity and identity within the
Step ecosystem. JWTs have received negative attention because they are easy to
misuse and misconfigure. We agree! But lots of things are easy to misuse. We also
believe that when configured well JWTs are a great way to sign and encode data.
Our JWT's are, by default, short-lived (5 minute lifespan) and one time use
during the lifetime of the Step CA. We use a 1 minute clock drift leeway
because that was the recommended default in the reputable JWT package that we
chose. If using Step JWTs or your own JWTs in your code be sure to verify and
validate every single standard attribute of the JWT. JWTs, like all
cryptographic tools, are useless without proper attention to configuration and
guidelines.
## Keys
RSA keys don't scale very well. To get 128 bits of security, you need 3,072-bit
RSA keys, which are noticeably slower. ECDSA keys provide an alternative
that offers better security and better performance. At 256 bits, ECDSA keys
provide 128 bits of security. A small number of older clients don't support
ECDSA, but most modern clients do.
**Default Key Type**: ECDSA
**Default Curve Bits**: P-256
We've chosen the AES encryption algorithm (aka Rijndael) for writing private
keys to disk because it was the official choice of the Advanced
Encryption Standard contest. The three supported key sizes are 128, 192, and
256. Each of these is considered to be unbreakable for the forseeable future,
therefore we chose 128 bits as our default because the performance is
better (as compared to the greater key sizes) and because we agree, with
the designers of the algorithm, that 128 bits are quite sufficient for
most security needs.
**Default PEMCipher**: AES128
## X.509 Certificate Defaults
### Root Certificate
* Validity (10 year window)
* **Not Before**: Now
* **Not After**: Now + 10 years
A 10 year window seems advisable until software and tools can be written
for rotating the root certificate.
* **Basic Constraints**
* **CA**: TRUE
The root certificate is a Certificate Authority, it will be used to sign
other Certificates.
* **pathlen**: 1
The path length constraint expresses the number of possible intermediate
CA certificates in a path built from an end-entity certificate up to the
CA certificate. An absent path length constraint means that there is no
limitation to the number of intermediate certificates from end-entity to
the CA certificate. The smallstep PKI has only one intermediate CA
certificate between end-entity certificates and the root CA certificcate.
* **Key Usage** describes how the certificate can be used.
* **Certificate Sign**
Indicates that our root public key will be used to verify a signature on
certificates.
* **CRL Sign**
Indicates that our root public key will be used to verify a signature on
revocation information, such as CRL.
### Intermediate Certificate
* Validity (10 year window)
* **Not Before**: Now
* **Not After**: Now + 10 years
A 10 year window seems advisable until software and tools can be written
for rotating the root certificate.
* **Basic Constraints**
* **CA**: TRUE
The intermediate certificate is a Certificate Authority, used to sign
end-entity (service, process, job, etc.) certificates.
* **pathlen**: 0
The path length constraint expresses the number of possible intermediate
CA certificates in a path built from an end-entity certificate up to the
CA certificate. An absent path length constraint means that there is no
limitation to the number of intermediate certificates from end-entity to
the CA certificate. There are no additional intermediary certificates in
the path between the smallstep intermediate CA and end-entity certificates.
* **Key Usage**
* **Certificate Signing**
Indicates that our the intermediate private key can be used to sign
certificate requests.
* **CRL Sign**
Indicates that this public key can be used to verify a signature on
revocation information, such as CRL.
### Leaf Certificate - End Entity Certificate (certificates returned by the CA)
* Validity (24 hour window)
* **Not Before**: Now
* **Not After**: Now + 24 hours
The default is a 24hr window. This value is somewhat arbitrary, however,
our goal is to have seamless end-entity certificate rotation (we are
getting close). Rotating certificates frequently is good security hygiene
because it gives bad actors very little time to form an attack and limits
the usefulness of any single private key in the system. We will continue
to work towards decreasing this window because we believe it significantly
reduces probability and effectiveness of any attack.
* **Key Usage**
* **Key Encipherment**
Indicates that a certificate will be used with a protocol that encrypts keys.
* **Digital Signature**
Indicates that this public key may be used as a digital signature to
support security services that enable entity authentication and data
origin authentication with integrity.
* **Extended Key Usage**
* **TLS Web Server Authentication**
Certificate can be used as the server side certificate in the TLS protocol.
* **TLS Web Client Authentication**
Certificate can be used as the client side certificate in the TLS protocol.
## Default TLS Configuration Options
* **Min TLS Version**: TLS 1.2
* **Max TLS Version**: TLS 1.2
The PCI Security Standards Council required all payment processors
and merchants to move to TLS 1.2 and above by June 30, 2018. By setting
TLS 1.2 as the default for all tls protocol negotiation we encourage our
users to adopt the same security conventions.
* **Default Cipher Suites**:
```
[
"TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305",
"TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256",
]
```
The default 'ciphersuites' are a list of two cipher combinations. For
communication between services running step there is no need for cipher suite
negotiation. The server can specify a single cipher suite which the client is
already known to support.
Reasons for selecting `TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305`:
* ECDHE key exchange algorithm has perfect forward secrecy
* ECDSA has smaller keys and better performance (than RSA)
* CHACHA20 with POLY1305 is the cipher mode used by google.
* CHACHA20's performance is better than GCM and CBC.
The http2 spec requires the `TLS_ECDHE_(RSA|ECDSA)_WITH_AES_128_GCM_SHA256`
ciphersuite be accepted by the server, therefore it makes our list of
default ciphersuites until we build the functionality to modify our defaults
based on http version.
* **Approved Cipher Suites**:
```
[
"TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA",
"TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256",
"TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256",
"TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA",
"TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384",
"TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305",
"TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA",
"TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256",
"TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256",
"TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA",
"TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384",
"TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305",
]
```
Above is a list of step approved cipher suites. Not all communication
can be mediated with step TLS functionality. For those connections the list of
server supported cipher suites must have more options - in case older clients
do not support our favored cipher suite.
Reasons for selecting these cipher suites can be found in the following
[ssllabs article](https://github.com/ssllabs/research/wiki/SSL-and-TLS-Deployment-Best-Practices#23-use-secure-cipher-suites).
* **Renegotation**: Never
TLS renegotiation significantly complicates the state machine and has been
the source of numerous, subtle security issues. Therefore, by default we
disable it.

View file

@ -1,116 +0,0 @@
# Distribution
This section describes how to build and deploy publicly available releases of
the Step CA.
## Creating A New Release
New releases are (almost) entirely built and deployed by Travis-CI. Creating a new
release is as simple as pushing a new github tag.
**Definitions**:
* **Standard Release**: ready for public use. no `-rc*` suffix on the version.
e.g. `v1.0.2`
* **Release Candidate**: not ready for public use, still testing. must have a
`-rc*` suffix. e.g. `v1.0.2-rc` or `v1.0.2-rc.4`
1. **Update the version of step/cli**
```
$ dep ensure -update github.com/smallstep/cli
```
2. **Commit all changes.**
Make sure that the local checkout is up to date with the remote origin and
that all local changes have been pushed.
```
$ git pull --rebase origin master
$ git push
```
3. **Tag it!**
1. **Find the most recent tag.**
```
$ git fetch --tags
$ git tag
```
The new tag needs to be the logical successor of the most recent existing tag.
See [versioning](#versioning) section for more information on version numbers.
2. **Select the type and value of the next tag.**
Is the new release a *release candidate* or a *standard release*?
1. Release Candidate
If the most recent tag is a standard release, say `v1.0.2`, then the version
of the next release candidate should be `v1.0.3-rc.1`. If the most recent tag
is a release candidate, say `v1.0.2-rc.3`, then the version of the next
release candidate should be `v1.0.2-rc.4`.
2. Standard Release
If the most recent tag is a standard release, say `v1.0.2`, then the version
of the next standard release should be `v1.0.3`. If the most recent tag
is a release candidate, say `v1.0.2-rc.3`, then the version of the next
standard release should be `v1.0.3`.
3. **Create a local tag.**
```
$ git tag v1.0.3 # standard release
...or
$ git tag v1.0.3-rc.1 # release candidate
```
4. **Push the new tag to the remote origin.**
```
$ git push origin tag v1.0.3 # standard release
...or
$ git push origin tag v1.0.3-rc.1 # release candidate
```
4. Check the build status at
[Travis-CI](https://travis-ci.com/smallstep/certificates/builds/).
Travis will begin by verifying that there are no compilation or linting errors
and then run the unit tests. Assuming all the checks have passed, Travis will
build Darwin and Linux artifacts (for easily installing `step`) and upload them
as part of the [Github Release](https://github.com/smallstep/certificates/releases).
Travis will build and upload the following artifacts:
* **step-certificates_1.0.3_amd64.deb**: debian package for installation on linux.
* **step-certificates_1.0.3_linux_amd64.tar.gz**: tarball containing a statically compiled linux binary.
* **step-certificates_1.0.3_darwin_amd64.tar.gz**: tarball containing a statically compiled darwin binary.
* **step-certificates.tar.gz**: tarball containing a git archive of the full repo.
6. **Update the AUR Arch Linux package**
**NOTE**: if you plan to release `cli` next then you can skip this step.
```
$ cd archlinux
# Get up to date...
$ git pull origin master
$ make
$ ./update --ca v1.0.3
```
*All Done!*
## Versioning
We use [SemVer](http://semver.org/) for versioning. See the
[tags on this repository](https://github.com/smallstep/certificates) for all
available versions.

View file

Before

Width:  |  Height:  |  Size: 572 KiB

After

Width:  |  Height:  |  Size: 572 KiB

View file

Before

Width:  |  Height:  |  Size: 59 KiB

After

Width:  |  Height:  |  Size: 59 KiB

View file

Before

Width:  |  Height:  |  Size: 72 KiB

After

Width:  |  Height:  |  Size: 72 KiB

View file

Before

Width:  |  Height:  |  Size: 57 KiB

After

Width:  |  Height:  |  Size: 57 KiB

View file

Before

Width:  |  Height:  |  Size: 6.2 MiB

After

Width:  |  Height:  |  Size: 6.2 MiB

View file

Before

Width:  |  Height:  |  Size: 9.5 MiB

After

Width:  |  Height:  |  Size: 9.5 MiB

View file

@ -1,11 +1,16 @@
# Commonly Asked Questions
# Frequently Asked Questions
These are some commonly asked questions on the topics of PKI, TLS, X509,
cryptography, threshold-cryptography, etc.
We hope to reduce the amount of hand-waving in these responses as we add
Hopefully we will reduce the amount of hand-waving in these responses as we add
more features to the Step toolkit over time.
#### What's TLS & PKI?
> We encourage you to read
> [our blog post on everything relating to PKI](https://smallstep.com/blog/everything-pki.html)
> as we believe it to be a solid resource that answers many of of the questions
> listed below.
## What are TLS & PKI?
TLS stands for *transport layer security*. It used to be called *secure sockets
layer* (or SSL), but technically SSL refers to an older version of the protocol.
@ -16,7 +21,9 @@ intended recipient, and cannot be modified in transit.
TLS is a complicated protocol with lots of options, but the most common mode of
operation establishes a secure channel using *asymmetric cryptography* with
*digital certificates* (or just certificates for short). First, some quick definitions:
*digital certificates* (or just certificates for short).
First, some quick definitions:
* *Asymmetric cryptography* (a.k.a., public key cryptography) is an underappreciated
gift from mathematics to computer science. It uses a *key pair*: a private key
known only to the recipient of the message, and a public key that can be broadly
@ -40,7 +47,7 @@ and procedures for managing digital certificates (i.e., managing the bindings
between names and public keys). Without proper secure PKI, an attacker can fake
a binding and undermine security.
#### What's a certificate authority?
## What's a certificate authority?
A certificate authority (CA) stores, issues, and signs digital certificates. CAs
have their own key pair, with the private key carefully secured (often offline).
@ -73,7 +80,7 @@ and verifying the identity of the requesting entities before establishing bindin
It also acts as a *central directory* and more generally as a *certificate
management system*, a secure location for storing and distributing key material.
#### Why not just use Verisign, Entrust, Let's Encrypt, etc?
## Why not just use Verisign, Entrust, Let's Encrypt, etc?
The web's *open public key infrastructure* (web PKI), while far from perfect,
is an important foundation for securing the web. So why not use it for securing
@ -86,14 +93,7 @@ communication for your own internal infrastructure? There are several reasons:
More broadly, the answer is that web PKI was designed for the web. A lot of the
web PKI design decisions aren't appropriate for internal systems.
#### How does identity proofing work?
Good question. However you want it to. Details here. Give some options: simple
meat-space token-based method should probably be default. But we should also
support the use of a CI/CD pipeline or orchestrator as a *registration authority*
so you can automate certificate provisioning.
Also talk about ACME, if we decide to support it.
## How does identity proofing work?
In general, trust will always flow back out to you, the operator of your system.
With that in mind, the simplest form of identity proofing is manual: [describe
@ -104,6 +104,11 @@ designs, to help with this. If you integrate with our other tools its easy to
start with a manual identity proofing mechanism and move to a more sophisticated
automated method as your system grows.
#### I already have PKI in place. Can I use this with my own root certificate?
## I already have PKI in place. Can I use this with my own root certificate?
Absolutely. [Details here].
## Furher Reading
* [Use TLS Everywhere](https://smallstep.com/blog/use-tls.html)
* [Everything you should know about certificates and PKI but are too afraid to ask](https://smallstep.com/blog/everything-pki.html)

View file

@ -1,207 +0,0 @@
## Sane Recommendations
TLS, PKI, X509, HTTPS, etc. all require configuration. All of
these technologies allow the user to "shoot themselves in the foot" by
misconfiguring them and reducing their benefits significantly. Therefore,
offering an easy to use solution that works out of the box means choosing and
enforcing sane default configurations for all these technologies.
Below we document some of the significant default configuration that we recommend.
This document is a moving target: security and cryptography are constanly
changing and evolving - vulnerabilities are found, new algorithms are created,
etc. We inted for this document be an accurate representation of current
best practices in the industry, and to have these practices codified as defaults
in the `certificates` code base. If you have questions, suggestions, or comments
about any of these decisions please let us know.
### Tokens
We use JWTs (JSON Web Tokens to prove authenticity and identity within the Step
ecosystem. JWTs have received negative attention because they are easy to
misuse, misconfigure.
We agree! But lots of things are easy to misuse. We also believe
that when configured well JWTs are a great way to sign and encode data. Our JWT's
are, by default, short-lived (5 minute lifespan) and can only be used once during
the lifetime of the Step CA. We use a 1 minute clock drift leeway because that
was the recommended default in the reputable JWT package that we chose. If using
Step JWTs or your own JWTs in your code be sure to verify and validate every
single standard attributed of the JWT. JWTs, like all cryptographic tools,
are useless without proper attention to configuration and guidelines.
### Keys
```
// RSA keys don't scale very well. To get 128 bits of security, you need 3,072-bit
// RSA keys, which are noticeably slower. ECDSA keys provide an alternative
// that offers better security and better performance. At 256 bits, ECDSA keys
// provide 128 bits of security. A small number of older clients don't support
// ECDSA, but most modern clients do.
Default Key Type: ECDSA
Default Curve Bits: P-256
// Encryption algorithm for writing private keys to disk. We've chosen AES
// (aka Rijndael) because it was the official choice of the Advanced Encryption
// Standard contest. The three supported key sizes are 128, 192, and 256. Each
// of these is considered to be unbreakable for the forseeable future, therefore
// we chose 128 bits as our default because the performance is better
// (as compared to the greater key sizes) and because we agree, with the
// designers of the algorithm, that 128 bits are quite sufficient for most
// security needs.
Default PEMCipher: AES128
```
### X.509 Certificate Defaults
* **root certificate**
```
* Validity (10 year window)
* Not Before: Now
// A 10 year window seems advisable until software and tools can be written
// for rotating the root certificate.
* Not After: Now + 10 years
* Basic Constraints
// The root certificate is a Certificate Authority, it will be used to sign
// other Certificates.
* CA: TRUE
// The path length constraint expresses the number of possible intermediate
// CA certificates in a path built from an end-entity certificate up to the
// CA certificate. An absent path length constraint means that there is no
// limitation to the number of intermediate certificates from end-entity to
// the CA certificate. The smallstep PKI has only one intermediate CA
//certificate between end-entity certificates and the root CA certificcate.
* pathlen: 1
* Key Usage // Describes how the keys can be used.
// Indicates that a certificate will be used with a protocol that encrypts keys.
* Key Encipherment
// Indicates that our root public key will be used to verify a signature on
// certificates.
* Certificate Signing
// Indicates that our root public key will be used to verify a signature on
// revocation
// information, such as CRL.
* CRL Sign
// Indicates that our root public key may be used as a digital signature to
// support security services that enable entity authentication and data
// origin authentication with integrity.
* Digital Signature
```
* **intermediate certificate**
```
* Validity (10 year window)
* Not Before: Now
// A 10 year window seems advisable until software and tools can be written
// for rotating the intermediates certificates without considerable agony
// on the part of the user.
* Not After: Now + 10 years
* Basic Constraints
// The intermediate certificate is a Certificate Authority, used to sign
// end-entity (service, process, job, etc.) certificates.
* CA: TRUE
// The path length constraint expresses the number of possible intermediate
// CA certificates in a path built from an end-entity certificate up to the
// CA certificate. An absent path length constraint means that there is no
// limitation to the number of intermediate certificates from end-entity to
// the CA certificate. There are no additional intermediary certificates in
// the path between the smallstep intermediate CA and end-entity certificates.
* pathlen: 0
* Key Usage
// Indicates that a certificate will be used with a protocol that encrypts keys.
* Key Encipherment
// Indicates that our root public key will be used to verify a signature on
// certificates.
* Certificate Signing
// Indicates that this public key can be used to verify a signature on
// revocation information, such as CRL.
* CRL Sign
// Indicates that this public key may be used as a digital signature to
// support security services that enable entity authentication and data
// origin authentication with integrity.
* Digital Signature
* Extended Key Usage
// Certificate can be used as the server side certificate in the TLS protocol.
* TLS Web Server Authentication
// Certificate can be used as the client side certificate in the TLS protocol.
* TLS Web Client Authentication
```
* **Leaf Certificate - End Entity Certificate** (certificates returned by the CA)
```
* Validity (24 hour window)
* Not Before: Now
// The default is a 24hr window. This value is somewhat arbitrary, however,
// our goal is to have seamless end-entity certificate rotation (we are
// getting close). Rotating certificates frequently is good security hygiene
// because it gives bad actors very little time to form an attack and limits
// the usefulness of any single private key in the system. We will continue
// to work towards decreasing this window because we believe it significantly
// reduces probability and effectiveness of any attack.
* Not After: Now + 24 hours
* Key Usage
// Indicates that a certificate will be used with a protocol that encrypts keys.
* Key Encipherment
// Indicates that this public key may be used as a digital signature to
// support security services that enable entity authentication and data
// origin authentication with integrity.
* Digital Signature
* Extended Key Usage
// Certificate can be used as the server side certificate in the TLS protocol.
* TLS Web Server Authentication
// Certificate can be used as the client side certificate in the TLS protocol.
* TLS Web Client Authentication
```
### Default TLS Configuration Options
```
// The PCI Security Standards Council is requiring all payment processors
// and merchants to move to TLS 1.2 and above by June 30, 2018. By setting
// TLS 1.2 as the default for all tls protocol negotiation we encourage our
// users to adopt the same security conventions.
* MinVersion: TLS 1.2
* MaxVersion: TLS 1.2
// https://github.com/ssllabs/research/wiki/SSL-and-TLS-Deployment-Best-Practices#23-use-secure-cipher-suites
// The default 'ciphersuites' is a single cipher combination. For communication
// between services running step there is no need for cipher suite negotiation.
// The server can specify a single cipher suite which the client is already
// known to support. Reasons for selecting "TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305":
// - ECDHE key exchange algorithm has perfect forward secrecy
// - ECDSA has smaller keys and better performance (than RSA)
// - CHACHA20 with POLY1305 is the cipher mode used by google.
// - CHACHA20's performance is better than GCM and CBC.
// NOTE: The http2 spec requires the "TLS_ECDHE_(RSA|ECDSA)_WITH_AES_128_GCM_SHA256"
// ciphersuite be accepted by the server, therefore it makes our list of
// default ciphersuites until we build the functionality to modify our defaults
// based on http version.
* DefaultCipherSuites: [
"TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305",
"TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256",
]
// The following is a list of step approved cipher suites. Not all communication
// can be mediated with step TLS functionality. For those connections the list of
// server supported cipher suites must have more options - in case older clients
// do not support our favored cipher suite. Reasons for selecting these cipher
// suites can be found in the ssllabs article cited above.
* ApprovedCipherSuites: [
"TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA",
"TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256",
"TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256",
"TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA",
"TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384",
"TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305",
"TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA",
"TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256",
"TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256",
"TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA",
"TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384",
"TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305",
]
// TLS renegotiation significantly complicates the state machine and has been
// the source of numerous, subtle security issues. Therefore, by default we
// disable it.
* Renegotation: Never

View file

@ -201,7 +201,7 @@ through an example.
[Use TLS Everywhere](https://smallstep.com/blog/use-tls.html) and let us know
what you think of our tools. Get in touch over
[twitter](twitter.com/smallsteplabs) or through our
[Twitter](twitter.com/smallsteplabs) or through our
[Gitter](https://gitter.im/smallstep/community) to chat with us in real time.
## Further Reading