AWS SigV4 Credential Signing
Configure proxy-side AWS SigV4 request signing so sandbox agents can reach AWS services through CONNECT tunnels without holding real credentials.
AWS SigV4 credential signing lets sandbox agents call AWS services (Bedrock, S3, STS, and others) through the proxy’s CONNECT tunnel. The proxy intercepts outbound requests, strips the sandbox client’s placeholder Authorization header, and re-signs the request with real AWS credentials from the provider. The sandbox never sees the real credentials.
Prerequisites
Section titled “Prerequisites”- A provider with
AWS_ACCESS_KEY_IDandAWS_SECRET_ACCESS_KEYcredentials configured. Optionally includeAWS_SESSION_TOKENfor STS temporary credentials. - An endpointless
awsprovider profile when the sandbox policy defines the service endpoints, or an endpoint-bearing service profile such asaws-s3. - A sandbox policy with
credential_signingenabled on the target endpoint. For the endpointlessawsprofile, the endpoint must also setcredential_binding.providerto the attached provider name.
Provider Setup
Section titled “Provider Setup”Import the aws profile first; a gateway serves only the profiles you
imported:
openshell profile import --url https://raw.githubusercontent.com/NVIDIA/OpenShell/main/providers/aws.yaml --globalCreate a provider with AWS credentials:
openshell provider create \ --name aws-prod \ --type aws \ --credential AWS_ACCESS_KEY_ID=AKIA... \ --credential AWS_SECRET_ACCESS_KEY=wJalr...For STS temporary credentials, include the session token:
openshell provider create \ --name aws-sts \ --type aws \ --credential AWS_ACCESS_KEY_ID=ASIA... \ --credential AWS_SECRET_ACCESS_KEY=secret... \ --credential AWS_SESSION_TOKEN=FwoGZX...To have the gateway mint and rotate STS credentials for you instead of supplying
them statically, use the aws or aws-s3 profile with the aws_sts_assume_role
refresh strategy. A single sts:AssumeRole mints all three env vars
(AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN) that the
signer reads. See Manage Providers.
Policy Configuration
Section titled “Policy Configuration”Enable SigV4 signing on a per-endpoint basis. The binding selects which provider instance supplies credentials, while the signing fields control how the proxy applies them:
| Field | Type | Required | Description |
|---|---|---|---|
credential_binding.provider |
string | For endpointless profiles | Exact name of the attached provider instance that supplies AWS credentials. |
credential_signing |
string | Yes | Signing mode: sigv4, sigv4:body, or sigv4:no_body. |
signing_service |
string | Yes | AWS service name for the SigV4 signature (e.g. bedrock, s3, sts). |
signing_region |
string | No | AWS region override. When omitted, extracted from the endpoint hostname. Required for non-standard endpoints. |
Bedrock Example
Section titled “Bedrock Example”network_policies: aws_bedrock: endpoints: - host: bedrock-runtime.us-east-1.amazonaws.com port: 443 protocol: rest credential_binding: provider: aws-prod credential_signing: sigv4 signing_service: bedrock rules: - allow: method: POST path: /model/*/invokeS3 Example
Section titled “S3 Example”network_policies: aws_s3: endpoints: - host: "*.s3.us-east-1.amazonaws.com" port: 443 protocol: rest access: full credential_binding: provider: aws-prod credential_signing: sigv4 signing_service: s3STS Example
Section titled “STS Example”network_policies: aws_sts: endpoints: - host: sts.us-east-1.amazonaws.com port: 443 protocol: rest access: full credential_binding: provider: aws-prod credential_signing: sigv4 signing_service: stsSigning Modes
Section titled “Signing Modes”The credential_signing field accepts three values:
| Value | Behavior | Use When |
|---|---|---|
sigv4 |
Auto-detect payload mode from the client SDK’s x-amz-content-sha256 header. |
Default. Works for most AWS services. |
sigv4:body |
Always buffer the request body and include its SHA-256 hash in the signature. Maximum body size: 10 MiB. | Services that require body signing (Bedrock). |
sigv4:no_body |
Sign headers only with UNSIGNED-PAYLOAD. Stream the body through without buffering. |
Large uploads (S3 PutObject), chunked transfers, or any case where body buffering is impractical. |
In sigv4 auto-detect mode, the proxy inspects the x-amz-content-sha256 header sent by the client SDK:
- Hex hash → buffer body and sign it (same as
sigv4:body). UNSIGNED-PAYLOAD→ sign headers only (same assigv4:no_body).STREAMING-UNSIGNED-PAYLOAD-TRAILER→ sign headers only, stream body through.- Absent → sign body if
Content-Lengthis present, otherwise use unsigned payload.
Region Detection
Section titled “Region Detection”The proxy extracts the AWS region from the endpoint hostname automatically. It supports standard, dualstack, FIPS, virtual-hosted, GovCloud, and China partition hostnames.
For endpoints where the region cannot be inferred from the hostname, set signing_region explicitly:
endpoints: - host: custom-vpc-endpoint.example.com port: 443 protocol: rest access: full credential_binding: provider: aws-prod credential_signing: sigv4 signing_service: s3 signing_region: us-west-2Restrictions
Section titled “Restrictions”credential_signingandrequest_body_credential_rewriteare mutually exclusive on the same endpoint. The policy validator rejects policies that set both.credential_binding.providermust name a provider attached to that sandbox. Use it only when the selected provider profile has no endpoints. Endpoint-bearing profiles already define their credential boundary.- OpenShell rejects a signed sandbox policy before activation unless the endpoint has a resolvable AWS credential source. An endpoint-bearing profile must declare
AWS_ACCESS_KEY_IDandAWS_SECRET_ACCESS_KEYand cover the signed host, port, and path. An endpointless profile must declare those keys and be selected withcredential_binding.provideron the signed endpoint. - The
sigv4:bodymode buffers at most 10 MiB. Requests with larger bodies are rejected. Usesigv4:no_bodyorsigv4(auto-detect) for large payloads. - The active provider must contain current
AWS_ACCESS_KEY_IDandAWS_SECRET_ACCESS_KEYvalues. If either becomes unavailable after policy activation, the request fails closed.
Use from a Sandbox
Section titled “Use from a Sandbox”Inside a sandbox, configure the AWS SDK with placeholder credentials. The proxy replaces them with real credentials during re-signing:
export AWS_ACCESS_KEY_ID=placeholderexport AWS_SECRET_ACCESS_KEY=placeholderexport AWS_DEFAULT_REGION=us-east-1Then use any AWS SDK or CLI normally. The proxy transparently re-signs requests before forwarding to AWS.
We are a Cloud Native Computing Foundation sandbox project.
Copyright OpenShell a Series of LF Projects, LLC
For website terms of use, trademark policy and other project policies please see lfprojects.org/policies/.