From 8ab04bd5037a856786db826f676f4f1d0444b188 Mon Sep 17 00:00:00 2001 From: max furman Date: Mon, 29 Apr 2019 17:50:30 -0700 Subject: [PATCH] docs sub repo update --- README.md | 14 +- docs/GETTING_STARTED.md | 6 +- docs/README.md | 40 +++ docs/defaults.md | 228 ++++++++++++++++++ docs/distribution.md | 116 --------- .../images}/connect-with-mtls-2.png | Bin docs/{ => images}/oidc1.png | Bin docs/{ => images}/oidc2.png | Bin docs/{ => images}/oidc3.png | Bin {images => docs/images}/step-ca-2-legged.gif | Bin {images => docs/images}/step-ca-3-legged.gif | Bin docs/{common-questions.md => questions.md} | 35 +-- docs/recommendations.md | 207 ---------------- docs/revocation.md | 2 +- 14 files changed, 301 insertions(+), 347 deletions(-) create mode 100644 docs/README.md create mode 100644 docs/defaults.md delete mode 100644 docs/distribution.md rename {images => docs/images}/connect-with-mtls-2.png (100%) rename docs/{ => images}/oidc1.png (100%) rename docs/{ => images}/oidc2.png (100%) rename docs/{ => images}/oidc3.png (100%) rename {images => docs/images}/step-ca-2-legged.gif (100%) rename {images => docs/images}/step-ca-3-legged.gif (100%) rename docs/{common-questions.md => questions.md} (86%) delete mode 100644 docs/recommendations.md diff --git a/README.md b/README.md index 754069d5..ec11c411 100644 --- a/README.md +++ b/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 diff --git a/docs/GETTING_STARTED.md b/docs/GETTING_STARTED.md index 44ced622..a5323832 100644 --- a/docs/GETTING_STARTED.md +++ b/docs/GETTING_STARTED.md @@ -479,7 +479,7 @@ one we'll use in this example, is G-Suite. Navigate to the Google APIs developer console and pick a suitable project from the top navbar's dropdown. -![Google Dev Console](oidc1.png) +![Google Dev Console](./images/oidc1.png) In the masthead navigation click **Credentials** (key symbol) and then "OAuth consent screen" from the subnav. Fill out naming details, all mandatory fields, @@ -492,7 +492,7 @@ Move back to **Credentials** on the subnav and choose "OAuth client ID" from the **Create credentials** dropdown. Since OIDC will be used from the `step CLI` pick **Other** from the available options and pick a name (e.g. **Step CLI**). -![Create credential](oidc2.png) +![Create credential](./images/oidc2.png) On successful completion, a confirmation modal with both `clientID` and `clientSecret` will be presented. Please note that the `clientSecret` will @@ -500,7 +500,7 @@ allow applications access to the configured OAuth consent screen. However, it will not allow direct authentication of users without their own MfA credentials per account. -![OIDC credentials](oidc3.png) +![OIDC credentials](./images/oidc3.png) Now using `clientID` and `clientSecret` run the following command to add G-Suite as a provisioner to `step certificates`. Please see [`step ca diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..06968809 --- /dev/null +++ b/docs/README.md @@ -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) diff --git a/docs/defaults.md b/docs/defaults.md new file mode 100644 index 00000000..6c775413 --- /dev/null +++ b/docs/defaults.md @@ -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. diff --git a/docs/distribution.md b/docs/distribution.md deleted file mode 100644 index 7e3907b9..00000000 --- a/docs/distribution.md +++ /dev/null @@ -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. diff --git a/images/connect-with-mtls-2.png b/docs/images/connect-with-mtls-2.png similarity index 100% rename from images/connect-with-mtls-2.png rename to docs/images/connect-with-mtls-2.png diff --git a/docs/oidc1.png b/docs/images/oidc1.png similarity index 100% rename from docs/oidc1.png rename to docs/images/oidc1.png diff --git a/docs/oidc2.png b/docs/images/oidc2.png similarity index 100% rename from docs/oidc2.png rename to docs/images/oidc2.png diff --git a/docs/oidc3.png b/docs/images/oidc3.png similarity index 100% rename from docs/oidc3.png rename to docs/images/oidc3.png diff --git a/images/step-ca-2-legged.gif b/docs/images/step-ca-2-legged.gif similarity index 100% rename from images/step-ca-2-legged.gif rename to docs/images/step-ca-2-legged.gif diff --git a/images/step-ca-3-legged.gif b/docs/images/step-ca-3-legged.gif similarity index 100% rename from images/step-ca-3-legged.gif rename to docs/images/step-ca-3-legged.gif diff --git a/docs/common-questions.md b/docs/questions.md similarity index 86% rename from docs/common-questions.md rename to docs/questions.md index 21e70ff1..723d232d 100644 --- a/docs/common-questions.md +++ b/docs/questions.md @@ -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) diff --git a/docs/recommendations.md b/docs/recommendations.md deleted file mode 100644 index c0c02d45..00000000 --- a/docs/recommendations.md +++ /dev/null @@ -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 - diff --git a/docs/revocation.md b/docs/revocation.md index 7402d3d1..c8384d46 100644 --- a/docs/revocation.md +++ b/docs/revocation.md @@ -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