You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
228 lines
8.8 KiB
Markdown
228 lines
8.8 KiB
Markdown
# 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 [GitHub Discussions](https://github.com/smallstep/certificates/discussions).
|
|
|
|
## 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.
|