Authentication

Requests to the object storage can be either authenticated or unauthenticated. Unauthenticated requests can be sent by anonymous users.

K2 Cloud object storage supports the following versions of AWS authentication:

• Signature Version 2 (AWSv2);

• Signature Version 4 (AWSv4).

Authenticated requests must contain the Authorization header. The header for request authentication according to AWSv4 includes the following parameters:

Parameter	Description
AWS4-HMAC-SHA256	AWS signature type (AWS4) and signature algorithm (HMAC-SHA256)
Credential	Access key and request information in the format: <access-key>/<data>/<region>/<service>/aws4_request
SignedHeaders	List of headers used in the signature calculation in lower case and in alphabetical order, for example, host;x-amz-content-sha256;x-amz-date
Signature	A request authentication signature calculated using the access key, request body hash, and request in canonical representation.

Example of a header for authenticating a request to the S3 service:

Authorization: AWS4-HMAC-SHA256
Credential=project:user@company/20220603/<region>/s3/aws4_request,
SignedHeaders=host;x-amz-content-sha256;x-amz-date,
Signature=5d825383bc6e17bca652f2dd348eae704a30ccf900459beec3d20ddd397a0b16

Note

If you plan to make REST API calls directly from the code, you must independently calculate the call authentication signature. This is a rather cumbersome procedure, so we recommend using AWS CLI or S3cmd.

if AWS Signature Version 4 is used for authentication, the signature is calculated as follows.

Request signature

Signature calculation consists of four main steps:

1. Forming a canonical header. A canonical header includes:

   • HTTP request method used.

   • Path component from the request.

   • Request parameters in alphabetical order. If there are no parameters, then an empty string is inserted.

   • A list of headers to be signed and their values, separated by a colon. Headers are listed alphabetically in lower case without spaces. Each pair of headers and values starts on a new line (\n).

   • List of headers to be signed without values in lower case. The headers are listed in alphabetical order and separated by a semicolon.

   • SHA256 hash of the request body in hexadecimal notation. If there is no request body, then the empty string hash is calculated.

   Each component of the canonical header starts on a new line.

   For the request

   GET /?acl HTTP/1.1
   Host: bucket1.s3.k2.cloud
   X-Amz-Content-Sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
   X-Amz-Date: 20220603T153057Z
   

   the canonical representation is as follows:

   GET
   /
   acl=
   host:bucket1.s3.k2.cloud
   x-amz-content-sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
   x-amz-date:20220603T153057Z
   
   host;x-amz-content-sha256;x-amz-date
   e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
   

2. Generation of the string being signed. Such generation process uses the hexadecimal representation of the SHA256 hash of the canonical request generated in the previous step.

   # You can specify an empty string as the region and s3 as the service
   
   StringToSign = "AWS4-HMAC-SHA256" + "\n" +
     <YYYYMMDD'T'HHMMSS'Z'> + "\n" +
     <YYYYMMDD> + "/" + "<region>" + "/" + "s3/aws4_request" + "\n" +
     Hex(SHA256Hash(<CanonicalRequest>))
   

   For the canonical header from the previous step, the to-be-signed string is as follows:

   AWS4-HMAC-SHA256
   20220603T153057Z
   20220603/<region>/<service>/aws4_request
   954116b5d4a2103251ada9505859fffd57339730a4327eecd63451dd7acb1eeb
   

3. Calculation of the signing key. The key is calculated on the basis of the secret access key, which is contained in the API access settings (you can download the settings from your profile in the cloud console).

   To obtain the signing key, four message authentication codes (HMAC) are sequentially calculated using the SHA256 hash function. The respective functions are included in many programming languages. When calculating keys, you should use a binary digest rather than a hexadecimal hash (hex-digest).

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

   For example, for a secret key

   SecretAccessKey = '7w!z%C&F)J@NcRfUjXn2r5u8x/A?D(G-'
   

   the corresponding signing key will look as follows (in hexadecimal notation):

   SigningKey = fce6031213c5263262c4795957d5bb10614e66f5008bfcf3a2668a7c19380e73
   

4. Signature calculation.

   To calculate the signature, the same hashing function with a key is used as to calculate the keys themselves. The signing key (SigningKey) and the string to be signed (StringToSign) are passed as input parameters. The result should be converted to hexadecimal format.

   Signature = Hex(HMAC-SHA256(<SigningKey>,<StringToSign>))
   

   Signature example:

   5d825383bc6e17bca652f2dd348eae704a30ccf900459beec3d20ddd397a0b16
   

For more details on how to generate a signature for request authentication, see the Amazon S3 documentation.