S3 API Guide

A detailed guide on working with Hostman S3 Storage.

Connection Credentials

You can find S3 connection details in your Hostman control panel.

1. Go to the S3 Storage section.
2. Click on the bucket.
3. In the Settings tab, scroll down to see S3 Parameters.

We support AWS Signature V2 and AWS Signature V4.

To authenticate the requester, all requests must be signed using a signature generated with an Access Key and Secret Key.

Signature Calculation

Signature calculation consists of three steps:

1. Obtaining the signing key
2. Generating the string to sign
3. Signing the string using the key

Obtaining the Signing Key

To get the signing key, encode the following data using the HMAC-SHA256 algorithm:

DateKey = HMAC-SHA256("AWS4" + "<SecretKey>", "<YYYYMMDD>")
DateRegionKey = HMAC-SHA256(<DateKey>, "<aws-region>")
DateRegionServiceKey = HMAC-SHA256(<DateRegionKey>, "<aws-service>")
SigningKey = HMAC-SHA256(<DateRegionServiceKey>, "aws4_request")

We support request signing using the Authorization HTTP header.

Using the Authorization header is the most common method for user authentication.

General Request Format:

Authorization: AWS4-HMAC-SHA256
Credential=12345_USER/20180524/us-2/s3/aws4_request,
SignedHeaders=host;range;x-amz-date,
Signature=fe5f80f77d5fa3beca038a248ff027d0445342fe2855ddc963176630326f1024

Where:

• AWS4-HMAC-SHA256: AWS Signature Version 4 (AWS4) and the signature algorithm (HMAC-SHA256)
• Credential: Contains the access key and request information in the format: ${ACCESS_KEY}/${YYYYMMDD}/${REGION}/s3/aws4_request
• SignedHeaders: Lowercase list of header names used in the signature computation
• Signature: The signed hash, consisting of the request body hash, secret key, and request information (canonical request)

Generating the String to Sign

To generate the string to sign, create a canonical request in the following format:

<HTTPMethod>\n
<CanonicalURI>\n
<CanonicalQueryString>\n
<CanonicalHeaders>\n
<SignedHeaders>\n
<HashedPayload>

Where:

• HTTPMethod: One of the HTTP methods such as GET, PUT, HEAD, DELETE
• CanonicalURI: URI-encoded path starting after the domain with the first "/", e.g., for https://s3.hostman.com/bucket/sample.txt it would be /bucket/sample.txt
• CanonicalQueryString: Request query parameters
• CanonicalHeaders: List of headers and their values, separated by newline, in lowercase and without spaces
• SignedHeaders: List of header names (no values), sorted alphabetically, in lowercase, separated by semicolons (e.g., host;x-amz-content-sha256;x-amz-date)
• HashedPayload: SHA256 hash of the request body: Hex(SHA256Hash()). If there's no body, hash an empty string: Hex(SHA256Hash("")).

Signing the String Using the Key

The string to sign is a concatenation of the following:

"AWS4-HMAC-SHA256" + "\n" +
timeStampISO8601Format + "\n" +
<Scope> + "\n" +
Hex(SHA256Hash(<CanonicalRequest>))

Where:

• AWS4-HMAC-SHA256: Defines the encryption algorithm in use
• timeStampISO8601Format: Current UTC time in ISO 8601 format (e.g., 20130524T000000Z)
• Scope: Format: date.Format(<YYYYMMDD>) + "/" + <region> + "/" + <service> + "/aws4_request", e.g., 20130606/us-2/s3/aws4_request. This binds the signature to a specific date, region, and service. When bound to a date, the signature is valid for 15 minutes.

For more details on authentication via the Authorization header, refer to the official Amazon S3 API documentation.

Supported S3 Methods

Hostman storage is compatible with AWS S3 methods: Bucket CRUD, Bucket Location, Object CRUD, Object Copy.

Below are the main S3 methods supported by Hostman S3 storage. You can find a complete list of supported features in the official CEPH documentation.

Bucket Methods

Object Methods