Url-Encoding Amazon S3 Resource Keys For Pre-Signed Urls In ColdFusion

<cfscript>

	filename = "file";

	// Build up the file name, one ASCII character at a time.
	for ( i = 32 ; i <= 126 ; i++ ) {

		// The colon (:) is illegal on the Mac in folder and file names.
		if ( i == asc( ":" ) ) {

			continue;

		}

		// The forward-slash messes up the file name on the Mac. This ends up being
		// reported as a ":". It's a bit confusing to me. If you do want to use "/" in
		// an S3 file name, you have to escape it so that S3 doesn't treat it as a
		// pseudo-directory separator.
		if ( i == asc( "/" ) ) {

			continue;

		}

		filename &= chr( i );

	}

	// NOTE: We're writing to this to the output (instead of writing a file object),
	// since ColdFusion (Java) was having an issue writing some of the characters in
	// the resultant file path. I'm not sure which ones.
	writeOutput( filename & ".jpg" );

</cfscript>

<cfscript>

	/**
	* I get the expiration in seconds based on the given expires-at date. This takes
	* care of the UTC conversion and expects to receive a date in local time.
	*
	* @output false
	*/
	public numeric function getExpirationInSeconds( required date expiresAt ) {

		var localEpoch = dateConvert( "utc2local", "1970/01/01" );

		return( dateDiff( "s", localEpoch, expiresAt ) );

	}


	/**
	* I get the file name of the test file we [previously] uploaded to Amazon S3 in an
	* attempt to explore the URL encoding needed to reference an object key. This
	* generates a file name with the every non-control chracter in the first 127 ASCII
	* character (less some characters that are illegal on the Mac OSX).
	*
	* @output false
	*/
	public string function getTestFileName() {

		var filename = "file";

		// Build up the file name, one ASCII character at a time.
		for ( var i = 32 ; i <= 126 ; i++ ) {

			// The colon (:) is illegal on the Mac in folder and file names.
			if ( i == asc( ":" ) ) {

				continue;

			}

			// The forward-slash messes up the file name on the Mac. This ends up being
			// reported as a ":". It's a bit confusing to me. If you do want to use "/"
			// in an S3 file name, you probably have to escape it so that S3 doesn't
			// treat it as a pseudo-directory separator -- not 100% sure on that.
			if ( i == asc( "/" ) ) {

				continue;

			}

			filename &= chr( i );

		}

		return( filename & ".jpg" );

	}


	/**
	* I generate the signature for the given resource which will be available until
	* the given expiration date (in seconds).
	*
	* @output false
	*/
	public string function generateSignature(
		required string resource,
		required numeric expirationInSeconds
		) {

		var stringToSignParts = [
			"GET",
			"",
			"",
			expirationInSeconds,
			resource
		];

		var stringToSign = arrayToList( stringToSignParts, chr( 10 ) );

		var signature = hmac( stringToSign, aws.secretKey, "HmacSHA1", "utf-8" );

		// By default, ColdFusion returns the Hmac in Hex; we need to convert it to
		// base64 for usag in the pre-signed URL.
		return(
			binaryEncode( binaryDecode( signature, "hex" ), "base64" )
		);

	}


	/**
	* I encode the given S3 object key for use in a url. Amazon S3 keys have some non-
	* standard behavior for encoding - see this Amazon forum thread for more information:
	* https://forums.aws.amazon.com/thread.jspa?threadID=55746
	*
	* @output false
	*/
	public string function urlEncodeS3Key( required string key ) {

		key = urlEncodedFormat( key, "utf-8" );

		// At this point, we have a key that has been encoded too aggressively by
		// ColdFusion. Now, we have to go through and un-escape the characters that
		// AWS does not expect to be encoded.

		// The following are "unreserved" characters in the RFC 3986 spec for Uniform
		// Resource Identifiers (URIs) - http://tools.ietf.org/html/rfc3986#section-2.3
		key = replace( key, "%2E", ".", "all" );
		key = replace( key, "%2D", "-", "all" );
		key = replace( key, "%5F", "_", "all" );
		key = replace( key, "%7E", "~", "all" );

		// Technically, the "/" characters can be encoded and will work. However, if the
		// bucket name is included in this key, then it will break (since it will bleed
		// into the S3 domain: "s3.amazonaws.com%2fbucket"). As such, I like to unescape
		// the slashes to make the function more flexible. Plus, I think we can all agree
		// that regular slashes make the URLs look nicer.
		key = replace( key, "%2F", "/", "all" );

		// This one isn't necessary; but, I think it makes for a more attactive URL.
		// --
		// NOTE: That said, it looks like Amazon S3 may always interpret a "+" as a
		// space, which may not be the way other servers work. As such, we are leaving
		// the "+"" literal as the encoded hex value, %2B.
		key = replace( key, "%20", "+", "all" );

		return( key );

	}


	// ------------------------------------------------------ //
	// ------------------------------------------------------ //


	// Include my AWS credentials (so they are not in the code). Creates the structure:
	// * aws.bucket
	// * aws.accessID
	// * aws.secretKey
	include "./credentials.cfm";

	// Define the key to our character-test file. The filename in this key uses all the
	// ASCII characters between 32 and 126 (less the slash and the colon). It looks like:
	// --
	// file !"#$%&'()*+,-.0123456789;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz{|}~.jpg
	// --
	key = urlEncodeS3Key( "testing-characters/" & getTestFileName() );

	// Define the full resource of our key in our bucket.
	resource = ( "/" & aws.bucket & "/" & key );

	expirationInSeconds = getExpirationInSeconds( dateAdd( "n", 3, now() ) );

	signature = generateSignature( resource, expirationInSeconds );

	urlEncodedSignature = urlEncodedFormat( signature );

</cfscript>

<cfoutput>

	<!--- Render the pre-signed URL directly in the browser. --->
	<img
		src="https://s3.amazonaws.com#resource#?AWSAccessKeyId=#aws.accessID#&Expires=#expirationInSeconds#&Signature=#urlEncodedSignature#"
		width="325"
		style="display: inline-block ; margin-right: 15px ;"
		/>

	<!--- Try to use the pre-signed URL to download the image from Amazon S3. --->
	<cfhttp
		result="get"
		method="get"
		url="https://s3.amazonaws.com#resource#?AWSAccessKeyId=#aws.accessID#&Expires=#expirationInSeconds#&Signature=#urlEncodedSignature#"
		getasbinary="yes"
		file="#expandPath( './from-s3.jpg' )#"
		/>

	<img src="./from-s3.jpg" width="325" />

</cfoutput>