(Classic) Amazon S3 Module

There is now a KRL Module for uploading text to Amazon S3. The module's RID is a41x174 and can be loaded like all other modules (User Defined Modules).

For example, this would load the module with the alias AWSS3:

use module a41x174 alias AWSS3
	with AWSKeys = keys:aws() 

When loading the module, be sure to define your AWS keys in the meta block. There are two required keys, and should be defined like so:

key aws {
	"AWSAccessKey": "YOURACCESSKEYHERE",
	"AWSSecretKey": "YOURSECRETKEYHERE"
}

The Amazon S3 Module provides three functions and two actions.

getValue function

getValue takes one parameter. This parameter type is a string that is encoded as a Data URI.

getValue returns the base64 encoded value of the data URI. In other words, it strips out the "data:<mimetype>;base64," and returns the actual data.

rule getValue is active {
	select when pageview ".*" setting ()
	pre {
		image = <<
			data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAA
			UAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIB
			KE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==
		>>;
		base64EncodedData = AWSS3:getValue(image);
		// Evaluates to iVBORw0KGgoAAAA...
	}
	noop();
}

 

getType function

getType takes one parameter. This parameter type is a string encoded as a Data URI.

getType performs the exact opposite operation of getValue. Instead of returning the base64 encoded data, getType returns the mimetype of the data URI encoded data.

rule getType is active {
	select when pageview ".*" setting ()
	pre {
		image = <<
			data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAA
			UAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIB
			KE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==
		>>;
		mimetype = AWSS3:getType(image);
		// Evaluates to image/png
	}
	noop();
}

makeAwsUrl(bucket, object_name)

This is a convenience function that calculates the AWS URL from a given bucket and object name. This is useful for determining where AWS stored the item and allows programmers to not hardcode URL strings in their code that might change. 

upload action

The upload action is currently the only action available in the Amazon S3 Module. It takes three parameters, the bucket, the object_name and the object_value.

The bucket is a string. This string should contain the name of the Amazon S3 bucket to upload your file to.

The object_name is a string. This string is the name to upload your file as.

The object_value is the value of the file to upload.

As well as having these three parameters, you can also configure the upload action with the following options:

  • object_type
    • This option is the mimetype of the file you are uploading.
  • acl
    • This option is the same as the Amazon ACL. It defaults to "public-read"
rule upload is active {
	select when pageview ".*" setting ()
	pre {
		text = "This is a test upload";
	}
	{
		AWSS3:upload("kynetx_example", "kynetx_example_upload.txt", text);
	}
}

Using the base64 functions, we can also upload images. Do it, like so:

	rule upload is active {
		select when pageview ".*" setting ()
		pre {
			image = <<
				data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAA
				UAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIB
				KE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==
			>>;
		}
		{
			AWSS3:upload("kynetx_example", "testuploaddata.png", this2that:base642string(AWSS3:getValue(image)))
				with object_type = AWSS3:getType(image);
		}
	}

del action

The delete action takes two parameters, the bucket and the object_name.

The bucket is a string. This string should contain the name of the Amazon S3 bucket to delete the file from.

The object_name is a string. This string is the name the file to delete.

As well as having these three parameters, you can also configure the upload action with the following options:

  • object_type
    • This option is the mimetype of the file you are delete.
  • acl
    • This option is the same as the Amazon ACL. It defaults to "public-read"

Since these values are used to calculate the ACL authorization string, they must be correct. 

rule upload is active {
	select when pageview ".*" setting ()
	{
		AWSS3:del("kynetx_example", "kynetx_example_upload.txt");
	}
}

Security Considerations

There are a few things you should do to make this more secure. You should take every precaution to ensure that keys are not exposed by their use in KRL. This can be difficult since KRL rulesets are read from URLs by the engine. You should also limit what each AWS key can do to just the tasks that it needs to perform to do its work. Here are some suggestions:

  1. Create a separate user in AWS for each project.
  2. Create a access key and secret for that user
  3. Create a policy for that user that only allows access to the specific AWS resources (e.g. buckets) needed by the project. See the AWS Policy Generator for more information. 
  4. Put the developer key and secret in a protected key module and provide them just to the rulesets that need them. Do not put them in the same ruleset as the code using them as shown in the examples on this page unless those rulesets will be protected. An example can be see in the Maintenance Service for Fuse

Example Ruleset

ruleset a41x175 {
	meta {
		name "TestAmazonS3Module"
 
		description <<
			TestAmazonS3Module
		>>
 
		author "Jessie A. Morris"
 
		// Uncomment this line to require Marketplace purchase to use this app.
		// authz require user
		logging on
		
		key aws {
		   "AWSAccessKey": "YOURACCESSKEYHERE",
		   "AWSSecretKey": "YOURSECRETKEYHERE"
		}

		use module a41x174 alias AWSS3
			with AWSKeys = keys:aws()
	}
 
	dispatch {
		// Some example dispatch domains
		// domain "example.com"
		// domain "other.example.com"
	}
 
	global {
		image = <<
			data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAA
			UAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIB
			KE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==
		>>;
	}
 
	rule getValue is active {
		select when pageview ".*" setting ()
		pre {
			base64EncodedData = AWSS3:getValue(image);
		}
		noop();
	}
 
	rule getType is active {
		select when pageview ".*" setting ()
		pre {
			mimetype = AWSS3:getType(image);
		}
		noop();
	}
 
	rule upload is active {
		select when pageview ".*" setting ()
		pre {
			text = "This is a test upload";
		}
		{
			AWSS3:upload("jessiemorristest", "testuploaddata.png", 
				this2that:base642string(AWSS3:getValue(image))
			)
				with object_type = AWSS3:getType(image);


		}
	}
}

Tests

The AWSS3 module is tested by the this code.  

Copyright Picolabs | Licensed under Creative Commons.