mirror of
https://github.com/hashicorp/vault.git
synced 2026-05-28 04:10:44 -04:00
Update AWS auth docs for SHA-1 deprecation (#15741)
Update AWS auth docs for SHA-1 deprecation We now recommend `/rsa2048` as the preferred AWS signature moving foward, as `/pkcs7` and `/signature` will stop working by default in Vault 1.12 without setting `GODEBUG=x509sha1=1` in the Vault deployment due to the move to Go 1.18. I also took this oppoturnity to try to make the docs less confusing and more consistent with all of the usages of signature, PKCS#7, DSA, and RSA terminology. Co-authored-by: Ben Ash <32777270+benashz@users.noreply.github.com> Co-authored-by: Theron Voran <tvoran@users.noreply.github.com>
This commit is contained in:
Christopher Swenson
GitHub
parent
fc20910ee7
commit
1865d577f7
3 changed files with 68 additions and 24 deletions
|
|
@ -8,6 +8,8 @@ description: This is the API documentation for the Vault AWS auth method.
|
|||
|
||||
@include 'x509-sha1-deprecation.mdx'
|
||||
|
||||
@include 'aws-sha1-deprecation.mdx'
|
||||
|
||||
This is the API documentation for the Vault AWS auth method. For
|
||||
general information about the usage and operation of the AWS method, please
|
||||
see the [Vault AWS method documentation](/docs/auth/aws).
|
||||
|
|
@ -282,10 +284,21 @@ $ curl \
|
|||
## Create Certificate Configuration
|
||||
|
||||
Registers an AWS public key to be used to verify the instance identity
|
||||
documents. While the PKCS#7 signature of the identity documents have DSA
|
||||
digest, the identity signature will have RSA digest, and hence the public
|
||||
keys for each type varies respectively. Indicate the type of the public key
|
||||
using the "type" parameter.
|
||||
documents. Indicate the type of the public key using the `type` parameter.
|
||||
Vault has the default
|
||||
[documented](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-identity-documents.html)
|
||||
set of AWS certificates built-in.
|
||||
|
||||
The `pkcs7` type is used to verify PKCS#7 signatures from the AWS
|
||||
`http://169.254.169.254/latest/dynamic/instance-identity/pkcs7` and
|
||||
`http://169.254.169.254/latest/dynamic/instance-identity/rsa2048` endpoints.
|
||||
|
||||
The `identity` type is used to verify signatures from the
|
||||
`http://169.254.169.254/latest/dynamic/instance-identity/document` and
|
||||
`http://169.254.169.254/latest/dynamic/instance-identity/signature` endpoints.
|
||||
|
||||
See the [AWS docs](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-identity-documents.html)
|
||||
for more information on the signature types and the corresponding certificates.
|
||||
|
||||
| Method | Path |
|
||||
| :----- | :---------------------------------------- |
|
||||
|
|
@ -294,13 +307,18 @@ using the "type" parameter.
|
|||
### Parameters
|
||||
|
||||
- `cert_name` `(string: <required>)` - Name of the certificate.
|
||||
- `aws_public_cert` `(string: <required>)` - Base64 encoded AWS Public key required to verify
|
||||
PKCS7 signature of the EC2 instance metadata.
|
||||
- `aws_public_cert` `(string: <required>)` - Base64-encoded AWS Public key required to verify
|
||||
PKCS#7 signature of the EC2 instance metadata.
|
||||
- `type` `(string: "pkcs7")` - Takes the value of either "pkcs7" or "identity",
|
||||
indicating the type of document which can be verified using the given
|
||||
certificate. The PKCS#7 document will have a DSA digest and the identity
|
||||
signature will have an RSA signature, and accordingly the public certificates
|
||||
to verify those also vary. Defaults to "pkcs7".
|
||||
certificate. The PKCS#7 document can be a DSA digest from the
|
||||
[/pkcs7](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/verify-pkcs7.html)
|
||||
endpoint or an RSA-2048 signature from the
|
||||
[/rsa2048](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/verify-rsa2048.html)
|
||||
endpoint.
|
||||
The identity signature is used to validate RSA signatures from the
|
||||
[/signature](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/verify-signature.html)
|
||||
endpoint. Defaults to "pkcs7".
|
||||
|
||||
### Sample Payload
|
||||
|
||||
|
|
@ -1002,19 +1020,22 @@ $ curl \
|
|||
|
||||
## Login
|
||||
|
||||
Fetch a token. This endpoint verifies the pkcs7 signature of the instance
|
||||
Fetch a token. This endpoint verifies the PKCS#7 signature of the instance
|
||||
identity document or the signature of the signed GetCallerIdentity request.
|
||||
With the ec2 auth method, or when inferring an EC2 instance, verifies that
|
||||
the instance is actually in a running state. Cross checks the constraints
|
||||
defined on the role with which the login is being performed. With the ec2
|
||||
auth method, as an alternative to pkcs7 signature, the identity document
|
||||
along with its RSA digest can be supplied to this endpoint.
|
||||
auth method, as an alternative to PKCS#7 signature, the identity document
|
||||
along with its RSA signature can be supplied to this endpoint.
|
||||
|
||||
See the [AWS docs](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-identity-documents.html)
|
||||
for more information on the signature types.
|
||||
|
||||
| Method | Path |
|
||||
| :----- | :---------------- |
|
||||
| `POST` | `/auth/aws/login` |
|
||||
|
||||
### Sample Payload
|
||||
### Parameters
|
||||
|
||||
- `role` `(string: "")` - Name of the role against which the login is being
|
||||
attempted. If `role` is not specified, then the login endpoint looks for a
|
||||
|
|
@ -1023,15 +1044,23 @@ along with its RSA digest can be supplied to this endpoint.
|
|||
username) of the IAM principal authenticated. If a matching role is not found,
|
||||
login fails.
|
||||
- `identity` `(string: <required-ec2>)` - Base64 encoded EC2 instance identity
|
||||
document. This needs to be supplied along with the `signature` parameter. If
|
||||
using `curl` for fetching the identity document, consider using the option
|
||||
document, which can usually be obtained from the
|
||||
`http://169.254.169.254/latest/dynamic/instance-identity/document` endpoint.
|
||||
When using `curl` for fetching the identity document, consider using the option
|
||||
`-w 0` while piping the output to `base64` binary.
|
||||
- `signature` `(string: <required-ec2>)` - Base64 encoded SHA256 RSA signature of
|
||||
the instance identity document. This needs to be supplied along with
|
||||
`identity` parameter when using the ec2 auth method.
|
||||
- `pkcs7` `(string: <required-ec2>)` - PKCS7 signature of the identity document with
|
||||
all `\n` characters removed. Either this needs to be set _OR_ both `identity`
|
||||
and `signature` need to be set when using the ec2 auth method.
|
||||
Either both of this and `signature` must be set _OR_ `pkcs7` must be set
|
||||
when using the ec2 auth method.
|
||||
- `signature` `(string: <required-ec2>)` - Base64-encoded SHA256 RSA signature of
|
||||
the instance identity document, which can usually be obtained from the
|
||||
`http://169.254.169.254/latest/dynamic/instance-identity/document` endpoint.
|
||||
Either both this _AND_ `identity` must be set _OR_ `pkcs7` must be set
|
||||
when using the ec2 auth method.
|
||||
- `pkcs7` `(string: <required-ec2>)` - PKCS#7 signature of the identity document
|
||||
with all `\n` characters removed. This supports signatures from the AWS
|
||||
`http://169.254.169.254/latest/dynamic/instance-identity/rsa2048`
|
||||
or `http://169.254.169.254/latest/dynamic/instance-identity/pkcs7` endpoints.
|
||||
Either this needs to be set _OR_ both `identity` and
|
||||
`signature` need to be set when using the ec2 auth method.
|
||||
- `nonce` `(string: "")` - The nonce to be used for subsequent login requests.
|
||||
If this parameter is not specified at all and if reauthentication is allowed,
|
||||
then the method will generate a random nonce, attaches it to the instance's
|
||||
|
|
@ -1053,7 +1082,7 @@ along with its RSA digest can be supplied to this endpoint.
|
|||
method.
|
||||
- `iam_request_body` `(string: <required-iam>)` - Base64-encoded body of the
|
||||
signed request. Most likely
|
||||
`QWN0aW9uPUdldENhbGxlcklkZW50aXR5JlZlcnNpb249MjAxMS0wNi0xNQ==` which is the
|
||||
`QWN0aW9uPUdldENhbGxlcklkZW50aXR5JlZlcnNpb249MjAxMS0wNi0xNQ==`, which is the
|
||||
base64 encoding of `Action=GetCallerIdentity&Version=2011-06-15`. This is
|
||||
required when using the iam auth method.
|
||||
- `iam_request_headers` `(string: <required-iam>)` - Key/value pairs of headers
|
||||
|
|
|
|||
|
|
@ -8,6 +8,8 @@ description: The aws auth method allows automated authentication of AWS entities
|
|||
|
||||
@include 'x509-sha1-deprecation.mdx'
|
||||
|
||||
@include 'aws-sha1-deprecation.mdx'
|
||||
|
||||
The `aws` auth method provides an automated mechanism to retrieve a Vault token
|
||||
for IAM principals and AWS EC2 instances. Unlike most Vault auth methods, this
|
||||
method does not require manual first-deploying, or provisioning
|
||||
|
|
@ -628,9 +630,17 @@ $ vault write auth/aws/config/client iam_server_id_header_value=vault.example.co
|
|||
|
||||
#### Perform the login operation
|
||||
|
||||
For the ec2 auth method, first fetch the PKCS#7 signature on the AWS instance:
|
||||
|
||||
```shell-session
|
||||
$ SIGNATURE=$(curl -s http://169.254.169.254/latest/dynamic/instance-identity/rsa2048 | tr -d '\n')
|
||||
```
|
||||
|
||||
then set the signature on the login endpoint:
|
||||
|
||||
```shell-session
|
||||
$ vault write auth/aws/login role=dev-role \
|
||||
pkcs7=MIAGCSqGSIb3DQEHAqCAMIACAQExCzAJBgUrDgMCGgUAMIAGCSqGSIb3DQEHAaCAJIAEggGmewogICJkZXZwYXlQcm9kdWN0Q29kZXMiIDogbnVsbCwKICAicHJpdmF0ZUlwIiA6ICIxNzIuMzEuNjMuNjAiLAogICJhdmFpbGFiaWxpdHlab25lIiA6ICJ1cy1lYXN0LTFjIiwKICAidmVyc2lvbiIgOiAiMjAxMC0wOC0zMSIsCiAgImluc3RhbmNlSWQiIDogImktZGUwZjEzNDQiLAogICJiaWxsaW5nUHJvZHVjdHMiIDogbnVsbCwKICAiaW5zdGFuY2VUeXBlIiA6ICJ0Mi5taWNybyIsCiAgImFjY291bnRJZCIgOiAiMjQxNjU2NjE1ODU5IiwKICAiaW1hZ2VJZCIgOiAiYW1pLWZjZTNjNjk2IiwKICAicGVuZGluZ1RpbWUiIDogIjIwMTYtMDQtMDVUMTY6MjY6NTVaIiwKICAiYXJjaGl0ZWN0dXJlIiA6ICJ4ODZfNjQiLAogICJrZXJuZWxJZCIgOiBudWxsLAogICJyYW1kaXNrSWQiIDogbnVsbCwKICAicmVnaW9uIiA6ICJ1cy1lYXN0LTEiCn0AAAAAAAAxggEXMIIBEwIBATBpMFwxCzAJBgNVBAYTAlVTMRkwFwYDVQQIExBXYXNoaW5ndG9uIFN0YXRlMRAwDgYDVQQHEwdTZWF0dGxlMSAwHgYDVQQKExdBbWF6b24gV2ViIFNlcnZpY2VzIExMQwIJAJa6SNnlXhpnMAkGBSsOAwIaBQCgXTAYBgkqhkiG9w0BCQMxCwYJKoZIhvcNAQcBMBwGCSqGSIb3DQEJBTEPFw0xNjA0MDUxNjI3MDBaMCMGCSqGSIb3DQEJBDEWBBRtiynzMTNfTw1TV/d8NvfgVw+XfTAJBgcqhkjOOAQDBC4wLAIUVfpVcNYoOKzN1c+h1Vsm/c5U0tQCFAK/K72idWrONIqMOVJ8Uen0wYg4AAAAAAAA nonce=5defbf9e-a8f9-3063-bdfc-54b7a42a1f95
|
||||
pkcs7=$SIGNATURE
|
||||
```
|
||||
|
||||
For the iam auth method, generating the signed request is a non-standard
|
||||
|
|
@ -703,7 +713,7 @@ curl -X POST -H "X-Vault-Token:123" "http://127.0.0.1:8200/v1/auth/aws/role/dev-
|
|||
#### Perform the login operation
|
||||
|
||||
```
|
||||
curl -X POST "http://127.0.0.1:8200/v1/auth/aws/login" -d '{"role":"dev-role","pkcs7":"'$(curl -s http://169.254.169.254/latest/dynamic/instance-identity/pkcs7 | tr -d '\n')'","nonce":"5defbf9e-a8f9-3063-bdfc-54b7a42a1f95"}'
|
||||
curl -X POST "http://127.0.0.1:8200/v1/auth/aws/login" -d '{"role":"dev-role","pkcs7":"'$(curl -s http://169.254.169.254/latest/dynamic/instance-identity/rsa2048 | tr -d '\n')'","nonce":"5defbf9e-a8f9-3063-bdfc-54b7a42a1f95"}'
|
||||
|
||||
curl -X POST "http://127.0.0.1:8200/v1/auth/aws/login" -d '{"role":"dev", "iam_http_request_method": "POST", "iam_request_url": "aHR0cHM6Ly9zdHMuYW1hem9uYXdzLmNvbS8=", "iam_request_body": "QWN0aW9uPUdldENhbGxlcklkZW50aXR5JlZlcnNpb249MjAxMS0wNi0xNQ==", "iam_request_headers": "eyJDb250ZW50LUxlbmd0aCI6IFsiNDMiXSwgIlVzZXItQWdlbnQiOiBbImF3cy1zZGstZ28vMS40LjEyIChnbzEuNy4xOyBsaW51eDsgYW1kNjQpIl0sICJYLVZhdWx0LUFXU0lBTS1TZXJ2ZXItSWQiOiBbInZhdWx0LmV4YW1wbGUuY29tIl0sICJYLUFtei1EYXRlIjogWyIyMDE2MDkzMFQwNDMxMjFaIl0sICJDb250ZW50LVR5cGUiOiBbImFwcGxpY2F0aW9uL3gtd3d3LWZvcm0tdXJsZW5jb2RlZDsgY2hhcnNldD11dGYtOCJdLCAiQXV0aG9yaXphdGlvbiI6IFsiQVdTNC1ITUFDLVNIQTI1NiBDcmVkZW50aWFsPWZvby8yMDE2MDkzMC91cy1lYXN0LTEvc3RzL2F3czRfcmVxdWVzdCwgU2lnbmVkSGVhZGVycz1jb250ZW50LWxlbmd0aDtjb250ZW50LXR5cGU7aG9zdDt4LWFtei1kYXRlO3gtdmF1bHQtc2VydmVyLCBTaWduYXR1cmU9YTY5ZmQ3NTBhMzQ0NWM0ZTU1M2UxYjNlNzlkM2RhOTBlZWY1NDA0N2YxZWI0ZWZlOGZmYmM5YzQyOGMyNjU1YiJdfQ==" }'
|
||||
```
|
||||
|
|
|
|||
5
website/content/partials/aws-sha1-deprecation.mdx
Normal file
5
website/content/partials/aws-sha1-deprecation.mdx
Normal file
|
|
@ -0,0 +1,5 @@
|
|||
~> **Note**: Starting in Vault 1.12, only the `pkcs7` login flow with the AWS
|
||||
[`/rsa2048` signature endpoint](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/verify-rsa2048.html)
|
||||
credentials will work by default due to the deprecation of SHA-1-based signatures.
|
||||
Please see [the deprecation FAQ](/docs/deprecation/faq#q-what-is-the-impact-of-removing-support-for-x-509-certificates-with-signatures-that-use-sha-1)
|
||||
for more details and a workaround.
|
||||
Loading…
Reference in a new issue