docs sub repo update
@ -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)
|
@ -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.
|
@ -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.
|
|
Before Width: | Height: | Size: 572 KiB After Width: | Height: | Size: 572 KiB |
Before Width: | Height: | Size: 59 KiB After Width: | Height: | Size: 59 KiB |
Before Width: | Height: | Size: 72 KiB After Width: | Height: | Size: 72 KiB |
Before Width: | Height: | Size: 57 KiB After Width: | Height: | Size: 57 KiB |
Before Width: | Height: | Size: 6.2 MiB After Width: | Height: | Size: 6.2 MiB |
Before Width: | Height: | Size: 9.5 MiB After Width: | Height: | Size: 9.5 MiB |
@ -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
|
|
||||||
|
|