Add Provisioner documentation
max furman
6 years ago
parent
9735d1db22
commit
0f846cf8dd
@ -0,0 +1,108 @@
|
||||
# Commonly 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
|
||||
more features to the Step toolkit over time.
|
||||
|
||||
#### What's 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.
|
||||
Normal TCP connections communicate in plain text, allowing attackers to
|
||||
eavesdrop and spoof messages. If used properly, TLS provides *confidentiality*
|
||||
and *integrity* for TCP traffic, ensuring that messages can only be seen by their
|
||||
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:
|
||||
* *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
|
||||
distributed, even to adversaries, without compromising security.
|
||||
* *Digital certificates* are data structures that map a public key to the
|
||||
well-known name of the owner of the corresponding private key (e.g., a DNS host name).
|
||||
They *bind* a name to the public key so you can address recipients by name instead of
|
||||
using public keys directly (which are big random numbers).
|
||||
|
||||
Briefly, there are two functions that can be achieved using asymmetric cryptography:
|
||||
* Messages can be *encrypted* using the public key to ensure that only the
|
||||
private key holder can *decrypt* them, and
|
||||
* Messages can be *signed* using the private key so that anyone with the *public
|
||||
key* knows the message came from the private key holder.
|
||||
With digital certificates, you can replace "private key holder" with "named entity,"
|
||||
which makes things a whole lot more useful. It lets you use names, instead of
|
||||
public keys, to address messages.
|
||||
|
||||
PKI stands for *public key infrastructure*. Abstractly, it's a set of policies
|
||||
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?
|
||||
|
||||
A certificate authority (CA) stores, issues, and signs digital certificates. CAs
|
||||
have their own key pair, with the private key carefully secured (often offline).
|
||||
The CA binds its name to its public key by signing a digital certificate using
|
||||
its own private key (called *self signing*). The CA's self-signed certificate,
|
||||
or *root certificate*, is distributed to all principals in the system (e.g., all
|
||||
of the clients and servers in your infrastructure).
|
||||
|
||||
So, the CA is tasked with securely binding names to public keys. Here's how that process works.
|
||||
1. When a named principal wants a certificate, it generates its own key pair.
|
||||
Nobody else ever needs to know the private key, not even the CA.
|
||||
2. The principal creates a certificate signing request (CSR), containing its
|
||||
name and public key (and some other stuff), and submits it to the CA. The CSR is
|
||||
self-signed, like the root certificate, so the CA knows that the requestor has
|
||||
the corresponding private key.
|
||||
3. The CA performs some form of *identity proofing*, certifying that the request
|
||||
is coming from the principal named in the CSR.
|
||||
4. Once satisfied, the CA issues a certificate by using its own private key to
|
||||
sign a certificate binding the name and public key from the CSR.
|
||||
|
||||
Certificates signed by the CA are used to securely introduce principals that
|
||||
don't already know one anothers' public keys. Assuming both principals agree on
|
||||
a trusted CA, they can exchange digital certificates and authenticate the
|
||||
signatures to gain some assurance that they are communicating with the named entity.
|
||||
|
||||
Technically, smallstep's certificate authority is more than just a certificate
|
||||
authority. It combines several PKI roles into one simple, flexible package. It
|
||||
acts as a *registration authority*, accepting requests for digital certificates
|
||||
and verifying the identity of the requesting entities before establishing bindings.
|
||||
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?
|
||||
|
||||
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
|
||||
communication for your own internal infrastructure? There are several reasons:
|
||||
* It's expensive to provision certificates from a public CA for all of your services
|
||||
* Public CAs can't handle client certificates (mutual TLS)
|
||||
* It's much harder (and more expensive) to revoke or roll certificates from public CAs
|
||||
* It relies on a third party that can subvert your security
|
||||
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.
|
||||
|
||||
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
|
||||
token-based manual mechanism here]. As your system grows, this process can become
|
||||
onerous. Automated identity proofing requires careful coordination between
|
||||
different parts of your system. Smallstep provides additional tooling, and vetted
|
||||
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?
|
||||
|
||||
Absolutely. [Details here].
|
||||
@ -0,0 +1,193 @@
|
||||
## 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.
|
||||
|
||||
### 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 is more performance 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
|
||||
|
||||
Loading…
Reference in New Issue