From 1865d577f788ea53a9ff2795377f254ec97c1d3e Mon Sep 17 00:00:00 2001 From: Christopher Swenson Date: Tue, 7 Jun 2022 12:45:46 -0700 Subject: [PATCH] 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 --- website/content/api-docs/auth/aws.mdx | 73 +++++++++++++------ website/content/docs/auth/aws.mdx | 14 +++- .../content/partials/aws-sha1-deprecation.mdx | 5 ++ 3 files changed, 68 insertions(+), 24 deletions(-) create mode 100644 website/content/partials/aws-sha1-deprecation.mdx diff --git a/website/content/api-docs/auth/aws.mdx b/website/content/api-docs/auth/aws.mdx index fc275b5b7e..ba80410651 100644 --- a/website/content/api-docs/auth/aws.mdx +++ b/website/content/api-docs/auth/aws.mdx @@ -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: )` - Name of the certificate. -- `aws_public_cert` `(string: )` - Base64 encoded AWS Public key required to verify - PKCS7 signature of the EC2 instance metadata. +- `aws_public_cert` `(string: )` - 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: )` - 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: )` - 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: )` - 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: )` - 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: )` - 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: )` - 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: )` - Key/value pairs of headers diff --git a/website/content/docs/auth/aws.mdx b/website/content/docs/auth/aws.mdx index 8b1faca020..c08da513ce 100644 --- a/website/content/docs/auth/aws.mdx +++ b/website/content/docs/auth/aws.mdx @@ -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==" }' ``` diff --git a/website/content/partials/aws-sha1-deprecation.mdx b/website/content/partials/aws-sha1-deprecation.mdx new file mode 100644 index 0000000000..28b762cbad --- /dev/null +++ b/website/content/partials/aws-sha1-deprecation.mdx @@ -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.