docs sub repo update
This commit is contained in:
max furman
parent
2b96e7a94c
commit
8ab04bd503
14 changed files with 301 additions and 347 deletions
14
README.md
14
README.md
|
|
@ -3,7 +3,7 @@
|
||||||
An online certificate authority and related tools for secure automated certificate management, so you can use TLS everywhere.
|
An online certificate authority and related tools for secure automated certificate management, so you can use TLS everywhere.
|
||||||
|
|
||||||
[Website](https://smallstep.com) |
|
[Website](https://smallstep.com) |
|
||||||
[Documentation](https://smallstep.com/docs/certificates) |
|
[Documentation](#documentation) |
|
||||||
[Installation Guide](#installation-guide) |
|
[Installation Guide](#installation-guide) |
|
||||||
[Getting Started](./docs/GETTING_STARTED.md) |
|
[Getting Started](./docs/GETTING_STARTED.md) |
|
||||||
[Contribution Guide](./docs/CONTRIBUTING.md)
|
[Contribution Guide](./docs/CONTRIBUTING.md)
|
||||||
|
|
@ -321,13 +321,17 @@ and best practices on running Step CA in production.
|
||||||
|
|
||||||
## Documentation
|
## 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
|
## The Future
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -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
|
Navigate to the Google APIs developer console and pick a suitable project from the
|
||||||
top navbar's dropdown.
|
top navbar's dropdown.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
In the masthead navigation click **Credentials** (key symbol) and then "OAuth
|
In the masthead navigation click **Credentials** (key symbol) and then "OAuth
|
||||||
consent screen" from the subnav. Fill out naming details, all mandatory fields,
|
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**
|
**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**).
|
from the available options and pick a name (e.g. **Step CLI**).
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
On successful completion, a confirmation modal with both `clientID` and
|
On successful completion, a confirmation modal with both `clientID` and
|
||||||
`clientSecret` will be presented. Please note that the `clientSecret` will
|
`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
|
will not allow direct authentication of users without their own MfA credentials
|
||||||
per account.
|
per account.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
Now using `clientID` and `clientSecret` run the following command to add
|
Now using `clientID` and `clientSecret` run the following command to add
|
||||||
G-Suite as a provisioner to `step certificates`. Please see [`step ca
|
G-Suite as a provisioner to `step certificates`. Please see [`step ca
|
||||||
|
|
|
||||||
40
docs/README.md
Normal file
40
docs/README.md
Normal file
|
|
@ -0,0 +1,40 @@
|
||||||
|
# Step Certificates Documentation
|
||||||
|
|
||||||
|
Index of Documentation and Tutorials for using and deploying the `step certificates`.
|
||||||
|
|
||||||
|
[](https://github.com/smallstep/certificates/releases)
|
||||||
|
[](https://gitter.im/smallstep/community)
|
||||||
|
[](https://microbadger.com/images/smallstep/step-ca)
|
||||||
|
[](https://goreportcard.com/report/github.com/smallstep/certificates)
|
||||||
|
[](https://travis-ci.com/smallstep/certificates)
|
||||||
|
[](https://opensource.org/licenses/Apache-2.0)
|
||||||
|
[](https://cla-assistant.io/smallstep/certificates)
|
||||||
|
|
||||||
|
[](https://github.com/smallstep/certificates/stargazers)
|
||||||
|
[](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
228
docs/defaults.md
Normal 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.
|
||||||
|
|
@ -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,11 +1,16 @@
|
||||||
# Commonly Asked Questions
|
# Frequently Asked Questions
|
||||||
|
|
||||||
These are some commonly asked questions on the topics of PKI, TLS, X509,
|
These are some commonly asked questions on the topics of PKI, TLS, X509,
|
||||||
cryptography, threshold-cryptography, etc.
|
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.
|
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
|
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.
|
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
|
TLS is a complicated protocol with lots of options, but the most common mode of
|
||||||
operation establishes a secure channel using *asymmetric cryptography* with
|
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
|
* *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
|
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
|
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
|
between names and public keys). Without proper secure PKI, an attacker can fake
|
||||||
a binding and undermine security.
|
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
|
A certificate authority (CA) stores, issues, and signs digital certificates. CAs
|
||||||
have their own key pair, with the private key carefully secured (often offline).
|
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
|
It also acts as a *central directory* and more generally as a *certificate
|
||||||
management system*, a secure location for storing and distributing key material.
|
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,
|
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
|
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
|
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.
|
web PKI design decisions aren't appropriate for internal systems.
|
||||||
|
|
||||||
#### How does identity proofing work?
|
## 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.
|
|
||||||
|
|
||||||
In general, trust will always flow back out to you, the operator of your system.
|
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
|
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
|
start with a manual identity proofing mechanism and move to a more sophisticated
|
||||||
automated method as your system grows.
|
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].
|
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)
|
||||||
|
|
@ -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
|
|
||||||
|
|
||||||
|
|
@ -201,7 +201,7 @@ through an example.
|
||||||
|
|
||||||
[Use TLS Everywhere](https://smallstep.com/blog/use-tls.html) and let us know
|
[Use TLS Everywhere](https://smallstep.com/blog/use-tls.html) and let us know
|
||||||
what you think of our tools. Get in touch over
|
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.
|
[Gitter](https://gitter.im/smallstep/community) to chat with us in real time.
|
||||||
|
|
||||||
## Further Reading
|
## Further Reading
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue