s3sdk

Class Sv4Util

lucee.Component
    extended by s3sdk.Sv4Util

Amazon Web Services Signature 4 Utility for ColdFusion Version Date: 2016-04-12 (Alpha) Copyright 2016 Leigh (cfsearching) Requirements: Adobe ColdFusion 10+ AWS Signature 4 specifications: http://docs.aws.amazon.com/general/latest/gr/signature-version-4.html Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Class Attributes:
  • synchronized : false
  •  
  • accessors : false
  •  
  • persistent : false
  •  
    Constructor Summary
    init(string accessKeyId, string secretAccessKey, [string defaultRegionName=''], [string defaultServiceName=''])
          Creates a new instance of the utility for generating signatures using the supplied settings.
    Method Summary
    private string buildAuthorizationHeader(struct requestHeaders, string signedHeaders, string credentialScope, string signature)
         Generates Authorization header string.
    private string buildCanonicalHeaders(struct requestHeaders)
         Generates a list of canonical headers.
    private string buildCanonicalQueryString(struct requestParams, [boolean isEncoded='true'])
         Generates canonical query string.
    private string buildCanonicalRequest(string requestMethod, string canonicalURI, string canonicalQueryString, string canonicalHeaders, string signedHeaders, string requestPayload)
         Generate canonical request string.
    private string buildCanonicalURI(string requestURI)
         Generates canonical URI.
    private string buildCredentialScope(string dateStamp, string regionName, string serviceName)
         Generates string indicating the scope for which the signature is valid.
    private string buildCredentialString(string dateStamp, string regionName, string serviceName)
         Generates string indicating the scope for which the signature is valid.
    private string buildSignedHeaders(struct requestHeaders, array excludeNames)
         Generates a list of signed header names.
    private string cleanHeader(string text)
         Removes extraneous white space from header names or values.
    private array cleanHeaderNames(array names)
         Scrubs header names and values:.
    private struct cleanHeaders(struct headers)
         Scrubs header names and values:.
    private struct encodeQueryParams(struct queryParams)
         URL encode query parameters and names.
    struct generateSignatureData(string requestMethod, string hostName, string requestURI, any requestBody, struct requestHeaders, struct requestParams, [boolean signedPayload='true'], [array excludeHeaders='[runtime expression]'], [string regionName], [string serviceName], [string amzDate], [string dateStamp])
         Generates Signature 4 properties for the supplied request settings.
    private binary generateSignatureKey(string dateStamp, string regionName, string serviceName, [string algorithm='HMACSHA256'])
         Generates signing key for AWS Signature V4.
    private string generateStringToSign(string amzDate, string credentialScope, string canonicalRequest)
         Generates request string to sign.
    struct getUTCStrings()
         Returns current UTC date and time in the following formats:.
    private string hash256(any text)
         Convenience method that hashes the supplied value, with SHA256.
    private binary hmacBinary(string message, binary key, [string algorithm='HMACSHA256'], [string encoding='UTF-8'])
         Convenience method which generates a (binary) HMAC code for the specified message.
    private string urlEncode([string value])
         URL encodes the supplied string per RFC 3986, which defines the following as.
     
    Methods inherited from class lucee.Component
    None

    Constructor Detail

    init

    public init(string accessKeyId, string secretAccessKey, [string defaultRegionName=''], [string defaultServiceName=''])

    Creates a new instance of the utility for generating signatures using the supplied settings

    Parameters:
    accessKeyId
    secretAccessKey
    defaultRegionName - (Optional) Sets a default region for all requests made through this instance. This setting can be overriden at the request level in generateSignatureData()
    defaultServiceName - (Optional) Sets a default service name for all requests made through this instance. This setting can be overriden at the request level in generateSignatureData()

    Method Detail

    buildAuthorizationHeader

    private string buildAuthorizationHeader(struct requestHeaders, string signedHeaders, string credentialScope, string signature)

    Generates Authorization header string. Format: algorithm + ' ' + 'Credential=' + access_key + '/' + credential_scope + ', ' + 'SignedHeaders=' + signed_headers + ', ' + 'Signature=' + signature

    Parameters:
    requestHeaders
    signedHeaders
    credentialScope
    signature

    buildCanonicalHeaders

    private string buildCanonicalHeaders(struct requestHeaders)

    Generates a list of canonical headers

    Parameters:
    requestHeaders - Structure containing headers to be included in request hash

    buildCanonicalQueryString

    private string buildCanonicalQueryString(struct requestParams, [boolean isEncoded='true'])

    Generates canonical query string

    Parameters:
    requestParams - Structure containing all parameters passed via the query string.
    isEncoded - If true, the supplied parameters are already url encoded

    buildCanonicalRequest

    private string buildCanonicalRequest(string requestMethod, string canonicalURI, string canonicalQueryString, string canonicalHeaders, string signedHeaders, string requestPayload)

    Generate canonical request string

    Parameters:
    requestMethod - - Request operation, ie PUT, GET, POST, etcetera.
    canonicalURI - - Canonical URL string. See buildCanonicalURI
    canonicalQueryString - - Canonical query string. See buildCanonicalQueryString
    canonicalHeaders - - Canonical header string. See buildCanonicalHeaders
    signedHeaders - - List of signed headers. See buildSignedHeaders
    requestPayload - - For signed requests, this is the hash of the request body. Otherwise, the raw request body

    buildCanonicalURI

    private string buildCanonicalURI(string requestURI)

    Generates canonical URI. Encoded, absolute path component of the URI, which is everything in the URI from the HTTP host to the question mark character ("?") that begins the query string parameters (if any)

    Parameters:
    requestURI

    buildCredentialScope

    private string buildCredentialScope(string dateStamp, string regionName, string serviceName)

    Generates string indicating the scope for which the signature is valid. Credential scope is represented by a slash-separated string of dimensions in the following order: dateStamp / regionName / serviceName / terminationString

    Parameters:
    dateStamp - - Current date in UTC (must be same as X-Amz-Date date). Format yyyyMMdd
    regionName - - Name of the target region, UTF-8 encoded. Example "us-east-1"
    serviceName - - Name of the target service, UTF-8 encoded. Example "s3"

    buildCredentialString

    private string buildCredentialString(string dateStamp, string regionName, string serviceName)

    Generates string indicating the scope for which the signature is valid

    Parameters:
    dateStamp - - Current date in UTC (must be same as X-Amz-Date date). Format yyyyMMdd
    regionName - - Name of the target region, UTF-8 encoded. Example "us-east-1"
    serviceName - - Name of the target service, UTF-8 encoded. Example "s3"

    buildSignedHeaders

    private string buildSignedHeaders(struct requestHeaders, array excludeNames)

    Generates a list of signed header names.

    "...By adding this list of headers, you tell AWS which headers in the request are part of the signing process and which ones AWS can ignore (for example, any additional headers added by a proxy) for purposes of validating the request."

    Parameters:
    requestHeaders - Raw headers to be included in request
    excludeNames - Names of any headers AWS should ignore for the signing process

    cleanHeader

    private string cleanHeader(string text)

    Removes extraneous white space from header names or values. See http://docs.aws.amazon.com/general/latest/gr/sigv4-create-canonical-request.html

    Parameters:
    text - Text to scrub

    cleanHeaderNames

    private array cleanHeaderNames(array names)

    Scrubs header names and values:

    Parameters:
    names

    cleanHeaders

    private struct cleanHeaders(struct headers)

    Scrubs header names and values:

    Parameters:
    headers - Header names and values to scrub

    encodeQueryParams

    private struct encodeQueryParams(struct queryParams)

    URL encode query parameters and names

    Parameters:
    queryParams

    generateSignatureData

    public struct generateSignatureData(string requestMethod, string hostName, string requestURI, any requestBody, struct requestHeaders, struct requestParams, [boolean signedPayload='true'], [array excludeHeaders='[runtime expression]'], [string regionName], [string serviceName], [string amzDate], [string dateStamp])

    Generates Signature 4 properties for the supplied request settings.

    Parameters:
    requestMethod - - Request operation, ie PUT, GET, POST, etcetera.
    hostName - - Target host name, example: bucketname.s3.amazonaws.com
    requestURI - - Absolute path of the URI. Portion of the URL after the host, to the "?" beginning the query string
    requestBody - - Body of the request. Either a string or binary value.
    requestHeaders - - Structure of http headers for used the request. Mandatory host and date headers are automatically generated.
    requestParams - - Structure containing any url parameters for the request. Mandatory parameters are automatically generated.
    signedPayload - - If true, include hash of requestPayload in signature calculations. Otherwise, literal "UNSIGNED-PAYLOAD". Default is true.
    excludeHeaders - - (Optional) List of header names AWS can exclude from the signing process. Default is an empty array, which means all headers should be "signed"
    regionName - - (Optional) Override the instance region name with this value. Example "us-east-1"
    serviceName - - (Optional) Override the instance service name with this value. Example "s3"
    amzDate - - (Optional) Override the automatic X-Amz-Date calculation with this value. Current UTC date. If supplied, @dateStamp is required. Format: yyyyMMddTHHnnssZ
    dateStamp - - (Optional) Override the automatic dateStamp calculation with this value. Current UTC date (only). If supplied, @amzDate is required. Format: yyyyMMdd

    generateSignatureKey

    private binary generateSignatureKey(string dateStamp, string regionName, string serviceName, [string algorithm='HMACSHA256'])

    Generates signing key for AWS Signature V4

    Source: http://stackoverflow.com/questions/32513197/how-to-derive-a-sign-in-key-for-aws-signature-version-4-in-coldfusion

    Parameters:
    dateStamp - Date stamp in YYYYMMDD format. Example: 20150830
    regionName - Region name that is part of the service's endpoint (alphanumeric). Example: "us-east-1"
    serviceName - Service name that is part of the service's endpoint (alphanumeric). Example: "s3"
    algorithm - HMAC algorithm. Default is "HMACSHA256"

    generateStringToSign

    private string generateStringToSign(string amzDate, string credentialScope, string canonicalRequest)

    Generates request string to sign

    Parameters:
    amzDate - - Current timestamp in UTC. Format yyyyMMddTHHnnssZ
    credentialScope - - String defining scope of request. See buildCredentialScope().
    canonicalRequest - - Canonical request string

    getUTCStrings

    public struct getUTCStrings()

    Returns current UTC date and time in the following formats: - dateStamp - Current UTC date, format: YYYYMMDD - timeStamp - Current UTC date and time, format: YYYYMMDDTHHnnssZ


    hash256

    private string hash256(any text)

    Convenience method that hashes the supplied value, with SHA256

    Parameters:
    text - value to hash

    hmacBinary

    private binary hmacBinary(string message, binary key, [string algorithm='HMACSHA256'], [string encoding='UTF-8'])

    Convenience method which generates a (binary) HMAC code for the specified message

    Parameters:
    message - Message to sign
    key - HMAC key in binary form
    algorithm - Signing algorithm. [ Default is "HMACSHA256" ]
    encoding - Character encoding of message string. [ Default is UTF-8 ]

    urlEncode

    private string urlEncode([string value])

    URL encodes the supplied string per RFC 3986, which defines the following as unreserved characters that should NOT be encoded: A-Z, a-z, 0-9, hyphen ( - ), underscore ( _ ), period ( . ), and tilde ( ~ ).

    Parameters:
    value - string to encode