Chilkat.AuthAws Class Overview

Chilkat.AuthAws holds the settings needed for AWS request authentication. It is the authentication object provided to the Chilkat Rest class when making signed AWS requests. It supports AWS Signature Version 4 by default, can optionally use the older Signature Version 2, allows credential values or secret specifiers, and can generate temporary Signature V4 pre-signed URLs for AWS services.

What the Class Is Used For

Use Chilkat.AuthAws when an application needs to provide AWS authentication information to the Chilkat Rest class for signed AWS requests. The object stores the AWS access key, secret key, region, service namespace, signature version, and optional precomputed request-body hashes. It can also generate Signature V4 pre-signed URLs that grant temporary access to a specific AWS request.

AWS Credentials Stores AccessKey and SecretKey, or secret specifiers when EnableSecrets is enabled.
Signature Version Control Uses AWS Signature Version 4 by default, with optional Signature Version 2 support for older compatibility needs.
Region and Service Signature V4 uses Region and ServiceName to construct AWS authentication.
Pre-Signed URLs Generates temporary Signature V4 URLs for AWS services such as s3 and execute-api.

Typical Workflow

  1. Create an AuthAws object.
  2. Set AccessKey and SecretKey, or enable EnableSecrets and provide secret specifiers instead of literal credential values.
  3. For Signature Version 4, set Region and ServiceName.
  4. Leave SignatureVersion at its default value of 4, unless the request specifically requires Signature Version 2.
  5. For large streaming uploads, optionally set PrecomputedSha256 for Signature V4 or PrecomputedMd5 for Signature V2.
  6. For Signature V2 requests, set CanonicalizedResourceV2.
  7. To create a temporary URL, call GenPresignedUrl with the HTTP verb, scheme, domain, path, expiration time, and AWS service name.
  8. Check LastErrorText after failures or unexpected behavior.

Core Concepts

Concept Meaning Important Members
AWS Access Key The public credential identifier used for AWS request authentication. AccessKey
AWS Secret Key The secret credential value used to compute the request signature. SecretKey
Signature Version 4 The default AWS signing method. It uses the access key, secret key, region, service name, request details, and SHA-256 request-body hash. SignatureVersion, Region, ServiceName, PrecomputedSha256
Signature Version 2 Older AWS signing method that may require a canonicalized resource string and uses MD5 for request-body hashing. SignatureVersion, CanonicalizedResourceV2, PrecomputedMd5
Precomputed Body Hash A hash supplied by the application for a non-empty request body, commonly to avoid loading an entire streamed upload into memory. PrecomputedSha256, PrecomputedMd5
Pre-Signed URL A temporary URL that includes Signature V4 query parameters allowing access for a limited time. GenPresignedUrl

Core Properties

Property Purpose Guidance
AccessKey Stores the AWS access key. Required for authenticated AWS requests and pre-signed URL generation.
SecretKey Stores the AWS secret key. Required for signing AWS requests. Can be provided as a secret specifier when EnableSecrets is true.
EnableSecrets Allows secret specifiers instead of literal values for AccessKey and SecretKey. Default is false. When true, a value beginning with !! can be used instead of the actual credential value.
SignatureVersion Selects the AWS signature version. Default is 4. Set to 2 only when the older Signature Version 2 is required.
Region AWS region used by Signature Version 4. Default is us-east-1. Examples include us-west-2, eu-west-1, and eu-central-1. Unused by Signature Version 2.
ServiceName AWS service namespace used by Signature Version 4. Examples include s3 and ses. Unused by Signature Version 2.
CanonicalizedResourceV2 Canonicalized resource string required for Signature Version 2. Must be set when using SignatureVersion = 2.
PrecomputedSha256 Optional SHA-256 hash for AWS requests with a non-empty request body. Used by Signature Version 4. Value should be the lowercase hex encoding of the 32-byte SHA-256 hash.
PrecomputedMd5 Optional MD5 hash for AWS requests with a non-empty request body. Used by Signature Version 2. Value should be the Base64 encoding of the 16-byte MD5 hash.
LastErrorText Diagnostic text for the last method or property access. Check after failures or unexpected results. Diagnostic information may be available regardless of success or failure.

Signature Version 4 vs Signature Version 2

Area Signature Version 4 Signature Version 2
Selected by SignatureVersion = 4 SignatureVersion = 2
Default? Yes. This is the default value. No. Must be explicitly selected.
Region used? Yes. Uses Region. No. Region is unused.
Service namespace used? Yes. Uses ServiceName. No. ServiceName is unused.
Request-body hash Uses SHA-256. Optional precomputed value is supplied through PrecomputedSha256. Uses MD5. Optional precomputed value is supplied through PrecomputedMd5.
Extra required resource setting None listed in this class. Requires CanonicalizedResourceV2.
Pre-signed URL method GenPresignedUrl generates Signature V4 pre-signed URLs. GenPresignedUrl is for Signature V4, not V2.
Recommended default: Leave SignatureVersion set to 4 unless a specific older AWS workflow requires Signature Version 2.

Credential Handling and EnableSecrets

EnableSecrets allows the application to provide a secret specifier instead of the literal access key or secret key.

Setting Credential Value Style Behavior
EnableSecrets = false Literal credential values. AccessKey and SecretKey are interpreted as the actual AWS credential values.
EnableSecrets = true Secret specifiers beginning with !!. Values such as !!part1|part2|.. can be provided instead of literal credential values.
Default behavior: EnableSecrets defaults to false. Enable it only when the application is using Chilkat secret specifiers for credential lookup.

Precomputed Request-Body Hashes

For AWS requests with a non-empty request body, the signature may require a hash of the body. Supplying a precomputed hash is especially useful for streamed uploads where loading the entire body into memory would be undesirable.

Property Signature Version Required Encoding Common Use
PrecomputedSha256 Signature Version 4 Lowercase hex encoding of the 32-byte SHA-256 hash. S3 upload from a stream or other request-body signing where the body should not be read entirely into memory.
PrecomputedMd5 Signature Version 2 Base64 encoding of the 16-byte MD5 hash. Older Signature Version 2 request-body signing, especially streamed upload scenarios.
Memory behavior: If the appropriate precomputed hash is not provided, Chilkat may need to stream the entire file into memory so it can calculate the request-body hash for authentication.

Generating Pre-Signed URLs

GenPresignedUrl generates a temporary URL using AWS Signature Version 4. The URL includes query parameters such as the algorithm, credential scope, timestamp, expiration, signed headers, and signature.

Argument Meaning Examples / Notes
httpVerb HTTP method for the request. Examples: GET, PUT, POST, DELETE.
useHttps Controls whether the generated URL starts with HTTPS or HTTP. true emits https://; false emits http://.
domain Hostname used in the generated URL. The domain must match the AWS endpoint being accessed.
path Request path to be signed. The path becomes part of the URL and signature calculation.
numSecondsValid Number of seconds the URL remains valid. Used for the expiration query parameter.
awsService AWS service name for the pre-signed URL. Examples include s3 and execute-api.
Required properties: Before calling GenPresignedUrl, set valid values for SecretKey, AccessKey, and Region.
POST note: The documentation notes that pre-signed URLs for POST operations are generally not feasible for AWS services except S3.

Method Summary

Method Purpose Key Requirements
GenPresignedUrl Generates a temporary Signature V4 pre-signed URL for an AWS service. Requires AccessKey, SecretKey, and Region. The method also uses the supplied HTTP verb, scheme, domain, path, expiration, and service name.

Configuration Checklist

Scenario Set These Members Notes
Standard Signature V4 request AccessKey, SecretKey, Region, ServiceName SignatureVersion defaults to 4.
Signature V4 streamed upload Standard Signature V4 members + PrecomputedSha256 The precomputed SHA-256 value should be lowercase hex.
Signature V2 request SignatureVersion = 2, AccessKey, SecretKey, CanonicalizedResourceV2 Region and ServiceName are unused for Signature V2.
Signature V2 request with body hash Signature V2 members + PrecomputedMd5 The precomputed MD5 value should be Base64 encoded.
Credential lookup through secret specifiers EnableSecrets = true, AccessKey, SecretKey Credential properties can contain values such as !!part1|part2|.. instead of literal secrets.
Pre-signed URL AccessKey, SecretKey, Region, then call GenPresignedUrl The service is supplied as the method’s awsService argument.

Diagnostics and Troubleshooting

Problem Area Member What to Check
Authentication fails AccessKey, SecretKey, LastErrorText Confirm credentials are correct and check LastErrorText for diagnostic details.
Signature V4 request is rejected Region, ServiceName, SignatureVersion Confirm SignatureVersion = 4, the region is correct, and the service namespace matches the AWS service.
Signature V2 request is rejected CanonicalizedResourceV2, SignatureVersion Confirm SignatureVersion = 2 and that CanonicalizedResourceV2 is set correctly.
Streaming upload uses too much memory PrecomputedSha256, PrecomputedMd5 Supply the appropriate precomputed hash so Chilkat does not need to read the entire stream into memory to compute it.
Pre-signed URL generation fails GenPresignedUrl, AccessKey, SecretKey, Region Confirm the required properties are set before calling the method and verify the supplied domain, path, HTTP verb, expiration, and service name.
Secret specifier is not resolved EnableSecrets Confirm EnableSecrets is true and the credential value uses the expected !!part1|part2|.. format.

Common Pitfalls

Pitfall Better Approach
Forgetting to set Region for Signature V4. Set Region explicitly for the AWS region being accessed, even though the default is us-east-1.
Leaving ServiceName unset for Signature V4. Set it to the AWS service namespace, such as s3 or ses.
Using Signature V2 without CanonicalizedResourceV2. Set CanonicalizedResourceV2 whenever SignatureVersion is set to 2.
Providing a SHA-256 hash in the wrong format. PrecomputedSha256 must be lowercase hex for the 32-byte SHA-256 hash.
Providing an MD5 hash in the wrong format. PrecomputedMd5 must be Base64 for the 16-byte MD5 hash.
Expecting pre-signed POST URLs to work broadly across AWS services. The documentation notes that pre-signed POST URLs are generally not feasible for AWS services except S3.
Using secret specifiers without enabling secret support. Set EnableSecrets = true before assigning secret specifier strings to credential properties.

Best Practices

Recommendation Reason
Use Signature Version 4 for normal AWS authentication. It is the default and uses region, service namespace, and SHA-256 request hashing.
Set Region and ServiceName explicitly. This avoids relying on defaults and helps ensure the signature matches the intended AWS endpoint and service.
Use EnableSecrets when credentials should not be stored as literal strings. It allows credential properties to contain secret specifiers instead of the actual access key and secret key values.
Provide precomputed hashes for streamed request bodies. This can avoid reading the entire upload into memory just to compute the request-body hash for authentication.
Use CanonicalizedResourceV2 only for Signature V2 workflows. The property is required for V2 and unused for V4.
Use GenPresignedUrl for temporary Signature V4 access. It creates URLs containing the required Signature V4 query parameters and expiration.
Check LastErrorText after failures. It provides the most useful diagnostic detail for credential, signature, precomputed hash, and pre-signed URL problems.

Summary

Chilkat.AuthAws is a compact AWS authentication configuration class. It stores AWS access and secret keys, supports secret specifiers, selects Signature Version 4 or Version 2, supplies region and service namespace information for Signature V4, supports precomputed request-body hashes, and can generate temporary Signature V4 pre-signed URLs.

The most important practical guidance is to use Signature Version 4 by default, explicitly set the region and service name, provide precomputed hashes for streamed request bodies, and use EnableSecrets when credentials should be resolved from a secret store rather than assigned directly.