Sv4Util

Class Sv4Util

lucee.Component
    models.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:

singleton

synchronized : false

accessors : false

persistent : false

Constructor Summary
init() 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, string accessKey) 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.
`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`	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, string accessKey, string secretKey, string regionName, string serviceName, [array excludeHeaders='[runtime expression]'], [string amzDate], [string dateStamp], [boolean presignDownloadURL='false']) Generates Signature 4 properties for the supplied request settings.
`private binary`	generateSignatureKey(string dateStamp, string regionName, string serviceName, string secretKey, [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`	urlEncodeForAWS([string value]) URL encodes the supplied string per RFC 3986, which defines the following as.
`string`	urlEncodePath([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()

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

Method Detail

buildAuthorizationHeader

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

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

Parameters:: requestHeaders; signedHeaders; credentialScope; signature; accessKey

Returns:: - formatted string. Example: 20150830/us-east-1/iam/aws4_request

buildCanonicalHeaders

private string buildCanonicalHeaders(struct requestHeaders)

Generates a list of canonical headers

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

Returns:: Sorted list of header pairs, delimited by new lines

buildCanonicalQueryString

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

Generates canonical query string

URI-encode each parameter name and value according to RFC 3986
Percent-encode all other characters with %XY, where X and Y are hexadecimal characters (0-9 and uppercase A-F)
Sort the encoded parameter names by character code in ascending order (ASCII order)
Build the canonical query string by starting with the first parameter name in the sorted list.
For each parameter, append the URI-encoded parameter name, followed by the character '=' (ASCII code 61), followed by the URI-encoded parameter value. Use an empty string for parameters that have no value.
Append the character '&' (ASCII code 38) after each parameter value, except for the last value in the list.

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

Returns:: canonical query string

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

public 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

Returns:: URL encoded path

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"

Returns:: - formatted string. Example: 20150830/us-east-1/iam/aws4_request

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

Returns:: Sorted list of signed header names, delimited by semi-colon ";"

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

Removes leading and trailing spaces
Converts sequential spaces to single space

Parameters:: text - Text to scrub

Returns:: parsed text

cleanHeaderNames

private array cleanHeaderNames(array names)

Scrubs header names and values:

Removes leading and trailing spaces
Converts sequential spaces to single space
Converts all names to lower case

Parameters:: names

Returns:: array of parsed header names

cleanHeaders

private struct cleanHeaders(struct headers)

Scrubs header names and values:

Removes leading and trailing spaces from names and values
Converts sequential spaces to single space in names and values
Converts all header names to lower case

Parameters:: headers - Header names and values to scrub

Returns:: structure of parsed header names and values

encodeQueryParams

private struct encodeQueryParams(struct queryParams)

URL encode query parameters and names

Parameters:: queryParams

Returns:: new structure with all parameter names and values encoded

generateSignatureData

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

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.; accessKey; secretKey; 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"; 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"; 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; presignDownloadURL

Returns:: Signature value, authorization header and all properties part of the signature calculation: ALGORITHM,AMZDATE,AUTHORIZATIONHEADER,CANONICALHEADERS,CANONICALQUERYSTRING,CANONICALREQUEST,CANONICALURI,CREDENTIALSCOPE,DATESTAMP,EXCLUDEHEADERS,HOSTNAME,REGIONNAME,REQUESTHEADERS,REQUESTMETHOD,REQUESTPARAMS,REQUESTPAYLOAD,SERVICENAME,SIGNATURE,SIGNEDHEADERS,SIGNKEYBYTES,STRINGTOSIGN

generateSignatureKey

private binary generateSignatureKey(string dateStamp, string regionName, string serviceName, string secretKey, [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"; secretKey; algorithm - HMAC algorithm. Default is "HMACSHA256"

Returns:: signing key in binary

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

Returns:: - String to be signed

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

Returns:: structure containing date and time strings

hash256

private string hash256(any text)

Convenience method that hashes the supplied value, with SHA256

Parameters:: text - value to hash

Returns:: hashed value, in lower case

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 ]

Returns:: HMAC value for the specified message as binary (currently unsupported in CF11)

urlEncodeForAWS

private string urlEncodeForAWS([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

Returns:: URI encoded string

urlEncodePath

public string urlEncodePath([string value])

Parameters:: value - string to encode

Returns:: URI encoded string