AWS rolesanywhere documentation change
Summary
Expanded documentation for IAM Roles Anywhere credential helper, adding advanced security features (OS certificate store integration, PKCS#11, TPM), new commands (serve, update), and detailed security considerations for credential storage and access methods.
Security assessment
The changes add extensive documentation about secure key management practices (TPM, PKCS#11, OS certificate stores) and include security warnings about credential exposure risks (e.g., localhost access in 'serve' command, file storage in 'update' command). However, there's no evidence these changes address a specific existing security vulnerability or incident.
Diff
diff --git a/rolesanywhere/latest/userguide/credential-helper.md b/rolesanywhere/latest/userguide/credential-helper.md index 97c030290..c48b31886 100644 --- a//rolesanywhere/latest/userguide/credential-helper.md +++ b//rolesanywhere/latest/userguide/credential-helper.md @@ -5 +5 @@ -SynopsisOptionsOutputExamplesCredential Helper on GitHubCredential Helper Changelog +Credential Helper on GitHubAdvanced FeaturesAvailable commandscredential-process commandserve commandupdate commandCredential Helper Changelog @@ -9 +9,3 @@ SynopsisOptionsOutputExamplesCredential Helper on GitHubCredential Helper Change -To obtain temporary security credentials from AWS Identity and Access Management Roles Anywhere, use the credential helper tool that IAM Roles Anywhere provides. This tool is compatible with the `credential_process` feature available across the language SDKs. The helper manages the process of creating a signature with the certificate and calling the endpoint to obtain session credentials; it returns the credentials to the calling process in a standard JSON format. See [Temporary security credentials in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html) for more information on session credentials. +To obtain temporary security credentials from AWS Identity and Access Management Roles Anywhere, use the credential helper tool that IAM Roles Anywhere provides. This tool is compatible with the `credential_process` feature available across the language SDKs. When used with an AWS SDK, these credentials automatically refresh before they expire, requiring no additional implementation for credential renewal. The helper manages the process of creating a signature with the certificate and calling the endpoint to obtain session credentials; it returns the credentials to the calling process in a standard JSON format. + +See [ Temporary security credentials in IAM ](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html) for more information on session credentials. @@ -40 +42,209 @@ For more information, see [Getting started](./getting-started.html). -## Synopsis +## Credential Helper on GitHub + +The source code for the credential helper is available on [GitHub](https://github.com/aws/rolesanywhere-credential-helper) so that you can adapt the helper to your needs. We encourage you to submit pull requests for changes that you would like to have included. However, AWS doesn't provide support for running modified copies of this software. + +###### Note + +You can find more modes and options and for credential helper in the [README.md](https://github.com/aws/rolesanywhere-credential-helper/blob/main/README.md). + +## Advanced Features + +The credential helper supports several advanced features for working with different types of key storage and authentication mechanisms. + +### OS Certificate Store Integration + +On Windows and macOS, the credential helper can leverage private keys and certificates stored in OS-specific secure stores: + + * **Windows:** Both CNG and Cryptography APIs are supported. By default, only the user's "MY" certificate store is searched, but you can specify a different store using the `--system-store-name` option. + + * **macOS:** Keychain Access is supported. The credential helper searches Keychains on the search list. + + + + +To use certificates from these stores, use the `--cert-selector` option instead of providing certificate and private key files. + +#### macOS Keychain Integration + +For securing keys through macOS Keychain, consider creating a dedicated Keychain that only the credential helper can access: + + 1. Create a new Keychain: + + security create-keychain -p ${CREDENTIAL_HELPER_KEYCHAIN_PASSWORD} credential-helper.keychain + + 2. Unlock the Keychain: + + security unlock-keychain -p ${CREDENTIAL_HELPER_KEYCHAIN_PASSWORD} credential-helper.keychain + + 3. Add the Keychain to the search list: + + EXISTING_KEYCHAINS=$(security list-keychains | cut -d '"' -f2) security list-keychains -s credential-helper.keychain $(echo ${EXISTING_KEYCHAINS} | awk -v ORS=" " '{print $1}') + + 4. Import your certificate and private key: + + security import /path/to/identity.pfx -T /path/to/aws_signing_helper -P ${UNWRAPPING_PASSWORD} -k credential-helper.keychain + + + + +###### Note + +Since the official credential helper binary is signed, but not notarized, so it isn't trusted by macOS by default. You may need to specify your Keychain password whenever the credential helper uses the private key, or choose to always allow the credential helper to use the Keychain item. + +#### Windows CNG Integration + +To use Windows CNG for key storage, import your certificate and private key into your user's "MY" certificate store: + + + certutil -user -p %UNWRAPPING_PASSWORD% -importPFX "MY" \path\to\identity.pfx + +You can also use PowerShell cmdlets or Windows CNG/Cryptography APIs to import certificates. + +### PKCS#11 Integration + +The credential helper supports using certificates and keys from hardware or software PKCS#11 tokens and HSMs using PKCS#11 URIs: + + * Use a certificate from a PKCS#11 token: + + --certificate 'pkcs11:manufacturer=piv_II;id=%01' + + * Use a certificate by object name: + + --certificate 'pkcs11:object=My%20RA%20key' + + * Use a certificate from a file but the key from a token: + + --certificate client-cert.pem --private-key 'pkcs11:model=SoftHSM%20v2;object=My%20RA%20key' + + + + +Most Unix-based systems use [p11-kit](https://p11-glue.github.io/p11-glue/p11-kit/manual/config.html) to provide consistent system-wide and per-user configuration of available PKCS#11 providers. For systems or containers that lack p11-kit, you can specify a specific PKCS#11 provider library using the `--pkcs11-lib` parameter. + +If your private key object has the `CKA_ALWAYS_AUTHENTICATE` attribute set and the `CKU_CONTEXT_SPECIFIC` PIN matches the `CKU_USER` PIN, you can use the `--reuse-pin` parameter to avoid being prompted for the PIN multiple times. + +###### Note + +For YubiKey devices with PIV support, when a key pair and certificate exist in slots 9a or 9c, the YubiKey automatically generates an attestation certificate for the slot. To disambiguate between your certificate and the attestation certificate, use the `CKA_LABEL` (the `object` path attribute in a URI). + +### TPM Integration + +The credential helper supports TPM wrapped keys in the `-----BEGIN TSS2 PRIVATE KEY-----` format. You can use such a file as you would any plain key file. These files are supported by both TPMv2 OpenSSL engines/providers and GnuTLS. + +###### Important + +To use these commands below you must install the [tpm2-tools](https://github.com/tpm2-software/tpm2-tools) software package. This package provides the necessary commands for working with TPM2 devices. + +This package is available on many Linux distributions through standard package managers. + +To create and use a TPM key with the credential helper: + + 1. Create a primary key in the TPM owner hierarchy: + + tpm2_createprimary -G rsa -g sha256 -p ${TPM_PRIMARY_KEY_PASSWORD} -c parent.ctx -P ${OWNER_HIERARCHY_PASSWORD} + + 2. Create a child key with the primary key as its parent: + + tpm2_create -C parent.ctx -u child.pub -r child.priv -P ${TPM_PRIMARY_KEY_PASSWORD} -p ${TPM_CHILD_KEY_PASSWORD} + + 3. Load the child key into the TPM and make it persistent: + + tpm2_load -C parent.ctx -u child.pub -r child.priv -c child.ctx -P ${TPM_PRIMARY_KEY_PASSWORD} + CHILD_HANDLE=$(tpm2_evictcontrol -c child.ctx | cut -d ' ' -f 2 | head -n 1) + + 4. Create a CSR using the TPM key: + + openssl req -provider tpm2 -provider default -propquery '?provider=tpm2' \ + -new -key handle:${CHILD_HANDLE} \ + -out client-csr.pem + + 5. After obtaining a certificate from your CA, use it with the credential helper: + + ./aws_signing_helper credential-process \ + --certificate /path/to/certificate/file \ + --private-key handle:${CHILD_HANDLE} \ + --role-arn ${ROLE_ARN} \ + --trust-anchor-arn ${TA_ARN} \ + --profile-arn ${PROFILE_ARN} + + + + +###### Important + +When using TPM handles, it's your responsibility to clear out the persistent and temporary objects from the TPM after you no longer need them. If you load a key into the TPM that isn't password-protected, anyone with access to the machine can use that key. + +Alternatively, you can use a TPM key file in the format described in the [TSS2 Private Key Format](https://www.hansenpartnership.com/draft-bottomley-tpm2-keys.html). With this approach, the wrapped private key will be loaded into the TPM as a transient object and automatically flushed after use. + +###### Note + +For RSA keys used with the credential helper, ensure they have the sign attribute set. Some tools (like the IBM OpenSSL ENGINE) create RSA keys with the decrypt attribute but not the sign attribute by default. The credential helper delegates the signing operation to the TPM rather than implementing PKCS#1 v1.5 padding manually. + +### Diagnostic Commands + +The credential helper includes diagnostic commands that can help you troubleshoot issues: + +#### read-certificate-data + +Reads and displays information about a certificate. This is useful for verifying certificate details and finding the correct certificate when multiple certificates match a selector. + + + ./aws_signing_helper read-certificate-data --certificate /path/to/certificate.pem + +Or with a certificate selector: + + + ./aws_signing_helper read-certificate-data --cert-selector Key=x509Subject,Value=CN=Subject + +If multiple certificates match a selector, information about each of them is printed. For PKCS#11, URIs for each matched certificate are also printed to help uniquely identify certificates. + +#### sign-string + +Signs a fixed test string to validate your private key and digest configuration: + + + ./aws_signing_helper sign-string --private-key /path/to/private-key.pem + +Or with a certificate selector: + + + ./aws_signing_helper sign-string --cert-selector Key=x509Subject,Value=CN=Subject + +Optional parameters include: + + * `--digest`: Must be one of SHA256 (default), SHA384, or SHA512 + + * `--format`: Must be one of text (default), json, or bin + + + + +## Available commands + +The credential helper tool provides several commands to help you work with IAM Roles Anywhere. This section describes the available commands and their usage. + + * credential-process command \- Obtains temporary security credentials from IAM Roles Anywhere using your certificate and private key. +