forked from TrueCloudLab/certificates
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.
|
||||
|
||||
[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
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
||||
|
||||
|
||||
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**).
|
||||
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
|
||||
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
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,
|
||||
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)
|
||||
|
|
@ -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
|
||||
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
|
||||
|
|
|
|||
Loading…
Reference in a new issue