The aws-sign4 Reference Manual

This is the aws-sign4 Reference Manual, generated automatically by Declt version 3.0 "Montgomery Scott" on Wed Mar 25 16:54:32 2020 GMT+0.

1 Introduction

Common Lisp library for Amazon Web Services signing version 4.

Project home: https://github.com/rotatef/aws-sign4

This library implements the Signature Version 4 Signing Process, as described here: http://docs.aws.amazon.com/general/latest/gr/signature-version-4.html

Highlights:

Passes all tests in the test suite from Amazon.
Tested on ABCL, ACL, CCL, CLISP and SBCL.
Signing only, not tied to a specific http client library.

Example

See example.lisp for an example of using Drakma to make a request to SWF.

S3 supports presigned URL. This make is possible to give a web browser temporary access to download an object directly from S3. Example:

(let ((aws-sign4:*aws-credentials*
        (lambda ()
          (values "AKIAIOSFODNN7EXAMPLE" "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"))))
  (aws-sign4:aws-sign4 :region :eu-west-1
                       :service :s3
                       :host "s3-eu-west-1.amazonaws.com"
                       :path "/some-bucket/some-file"
                       :expires 300)) 
=> "https://s3-eu-west-1.amazonaws.com/some-bucket/some-file?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIOSFODNN7EXAMPLE%2F20170908%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20170908T121925Z&X-Amz-Expires=300&X-Amz-SignedHeaders=host&X-Amz-Signature=42c841837976e9c206f80554b50aa879fdb3aa4f3e6f61934ce8eba436205abf

API

Variable

AWS-SIGN4:*AWS-CREDENTIALS*

Bind this variable to a function returning two values, the access key and the secret key.

AWS-SIGN4:AWS-SIGN4 &key ...

Calculates the signature for a http request.

Parameters:

region - String designator for the AWS region. Default "us-east-1".
service - String designator for the AWS service name.
method - String designator for the http method.
host - The hostname/endpoint to for the request. Default is the value of the host header.
path - The path part of the request URI.
params - The query parameters of the URI as an assoc list.
headers - The headers as an assoc list as an assoc list.
payload - The payload, as a string or vector of octets. Strings are encoded to octets using UTF-8.
date-header - The name of the date-header, :X-AMZ-DATE or :DATE. Default :X-AMZ-DATE.
request-date - The request date as a local-time timestamp. Default (LOCAL-TIME:NOW).
expires - Provides the time period, in seconds, for which the generated presigned URL is valid.
scheme - Scheme used in presigned URL, defaults to https.

Returns seven values. Only the two first are needed, the others are useful for debugging.

If expire is nil or not supplied, the value of "Authorization" header. If expire is supplied, the presigned URL.
Value of "X-Amz-Date" or "Date" header.
Canonical request
String to sign
Credential scope
Signed headers
Signature

2 Systems

The main system appears first, followed by any subsystem dependency.

2.1 `aws-sign4`

Author

Thomas Bakketun <thomas.bakketun@copyleft.no>

License

GNU Lesser General Public Licence 3.0

Description

A library for Amazon Web Services signing version 4

Dependencies

local-time
cl-ppcre
ironclad
split-sequence
flexi-streams
secret-values

Source

aws-sign4.asd (file)

Components

package.lisp (file)
aws-sign4.lisp (file)

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.

3.1 Lisp

3.1.1 `aws-sign4.asd`

Location: aws-sign4.asd
Systems: aws-sign4 (system)

3.1.2 `aws-sign4/package.lisp`

Parent: aws-sign4 (system)
Location: package.lisp
Packages: aws-sign4

3.1.3 `aws-sign4/aws-sign4.lisp`

Dependency

package.lisp (file)

Parent

aws-sign4 (system)

Location

aws-sign4.lisp

Exported Definitions

*aws-credentials* (special variable)
aws-sign4 (function)
calculate-signature (function)
create-canonical-headers (function)
create-canonical-path (function)
create-canonical-query-string (function)
create-canonical-request (function)
get-credentials (function)

Internal Definitions

create-signed-headers (function)
ensure-octets (function)
hash (function)
hex-encode (function)
hmac (function)
merge-duplicate-headers (function)
string-to-sign (function)
trimall (function)
url-encode (function)

4 Packages

Packages are listed by definition order.

4.1 `aws-sign4`

Source

package.lisp (file)

Use List

common-lisp

Exported Definitions

*aws-credentials* (special variable)
aws-sign4 (function)
calculate-signature (function)
create-canonical-headers (function)
create-canonical-path (function)
create-canonical-query-string (function)
create-canonical-request (function)
get-credentials (function)

Internal Definitions

create-signed-headers (function)
ensure-octets (function)
hash (function)
hex-encode (function)
hmac (function)
merge-duplicate-headers (function)
string-to-sign (function)
trimall (function)
url-encode (function)

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

5.1 Exported definitions

5.1.1 Special variables

Special Variable: *aws-credentials*

Package: aws-sign4
Source: aws-sign4.lisp (file)

5.1.2 Functions

Function: aws-sign4 &key REGION SERVICE METHOD HOST PATH PARAMS HEADERS PAYLOAD DATE-HEADER REQUEST-DATE EXPIRES SCHEME

Package: aws-sign4
Source: aws-sign4.lisp (file)

Function: calculate-signature K-SECRET STRING-TO-SIGN DATE REGION SERVICE

Package: aws-sign4
Source: aws-sign4.lisp (file)

Function: create-canonical-headers HEADERS

Package: aws-sign4
Source: aws-sign4.lisp (file)

Function: create-canonical-path PATH

Package: aws-sign4
Source: aws-sign4.lisp (file)

Function: create-canonical-query-string PARAMS

Package: aws-sign4
Source: aws-sign4.lisp (file)

Function: create-canonical-request METHOD CANONICAL-PATH CANONICAL-QUERY-STRING CANONICAL-HEADERS SIGNED-HEADERS PAYLOAD

Package: aws-sign4
Source: aws-sign4.lisp (file)

Function: get-credentials ()

Package: aws-sign4
Source: aws-sign4.lisp (file)

5.2 Internal definitions

5.2.1 Functions

Function: create-signed-headers CANONICAL-HEADERS

Package: aws-sign4
Source: aws-sign4.lisp (file)

Function: ensure-octets DATA

Package: aws-sign4
Source: aws-sign4.lisp (file)

Function: hash DATA

Package: aws-sign4
Source: aws-sign4.lisp (file)

Function: hex-encode BYTES

Package: aws-sign4
Source: aws-sign4.lisp (file)

Function: hmac KEY DATA

Package: aws-sign4
Source: aws-sign4.lisp (file)

Function: merge-duplicate-headers HEADERS

Package: aws-sign4
Source: aws-sign4.lisp (file)

Function: string-to-sign REQUEST-DATE CREDENTIAL-SCOPE CANONICAL-REQUEST

Package: aws-sign4
Source: aws-sign4.lisp (file)

Function: trimall STRING

Package: aws-sign4
Source: aws-sign4.lisp (file)

Function: url-encode STRING &key ESCAPE%

URL-encodes a string using the external format UTF-8. If keyword parameter ESCAPE% is NIL, the % is not escaped.

Package: aws-sign4
Source: aws-sign4.lisp (file)

Appendix A Indexes

A.1 Concepts

Jump to:	A F L

	Index Entry	Section

A
	`aws-sign4.asd`:	The aws-sign4․asd file
	`aws-sign4/aws-sign4.lisp`:	The aws-sign4/aws-sign4․lisp file
	`aws-sign4/package.lisp`:	The aws-sign4/package․lisp file

F
	File, Lisp, `aws-sign4.asd`:	The aws-sign4․asd file
	File, Lisp, `aws-sign4/aws-sign4.lisp`:	The aws-sign4/aws-sign4․lisp file
	File, Lisp, `aws-sign4/package.lisp`:	The aws-sign4/package․lisp file

L
	Lisp File, `aws-sign4.asd`:	The aws-sign4․asd file
	Lisp File, `aws-sign4/aws-sign4.lisp`:	The aws-sign4/aws-sign4․lisp file
	Lisp File, `aws-sign4/package.lisp`:	The aws-sign4/package․lisp file

Jump to:	A F L

A.2 Functions

Jump to:	A C E F G H M S T U

	Index Entry	Section

A
	`aws-sign4`:	Exported functions

C
	`calculate-signature`:	Exported functions
	`create-canonical-headers`:	Exported functions
	`create-canonical-path`:	Exported functions
	`create-canonical-query-string`:	Exported functions
	`create-canonical-request`:	Exported functions
	`create-signed-headers`:	Internal functions

E
	`ensure-octets`:	Internal functions

F
	`Function, aws-sign4`:	Exported functions
	`Function, calculate-signature`:	Exported functions
	`Function, create-canonical-headers`:	Exported functions
	`Function, create-canonical-path`:	Exported functions
	`Function, create-canonical-query-string`:	Exported functions
	`Function, create-canonical-request`:	Exported functions
	`Function, create-signed-headers`:	Internal functions
	`Function, ensure-octets`:	Internal functions
	`Function, get-credentials`:	Exported functions
	`Function, hash`:	Internal functions
	`Function, hex-encode`:	Internal functions
	`Function, hmac`:	Internal functions
	`Function, merge-duplicate-headers`:	Internal functions
	`Function, string-to-sign`:	Internal functions
	`Function, trimall`:	Internal functions
	`Function, url-encode`:	Internal functions

G
	`get-credentials`:	Exported functions

H
	`hash`:	Internal functions
	`hex-encode`:	Internal functions
	`hmac`:	Internal functions

M
	`merge-duplicate-headers`:	Internal functions

S
	`string-to-sign`:	Internal functions

T
	`trimall`:	Internal functions

U
	`url-encode`:	Internal functions

Jump to:	A C E F G H M S T U

A.3 Variables

Jump to:	* S

	Index Entry	Section

*
	`aws-credentials`:	Exported special variables

S
	`Special Variable, aws-credentials`:	Exported special variables

Jump to:	* S

A.4 Data types

Jump to:	A P S

	Index Entry	Section

A
	`aws-sign4`:	The aws-sign4 system
	`aws-sign4`:	The aws-sign4 package

P
	`Package, aws-sign4`:	The aws-sign4 package

S
	`System, aws-sign4`:	The aws-sign4 system

Jump to:	A P S

• Introduction		What aws-sign4 is all about
• Systems		The systems documentation
• Files		The files documentation
• Packages		The packages documentation
• Definitions		The symbols documentation
• Indexes		Concepts, functions, variables and data types

• Concept index
• Function index
• Variable index
• Data type index

• The aws-sign4.asd file
• The aws-sign4/package.lisp file
• The aws-sign4/aws-sign4.lisp file

The aws-sign4 Reference Manual

Table of Contents

The aws-sign4 Reference Manual

1 Introduction

Common Lisp library for Amazon Web Services signing version 4.

Highlights:

Example

API

2 Systems

2.1 aws-sign4

3 Files

3.1 Lisp

3.1.1 aws-sign4.asd

3.1.2 aws-sign4/package.lisp

3.1.3 aws-sign4/aws-sign4.lisp

4 Packages

4.1 aws-sign4

5 Definitions

5.1 Exported definitions

5.1.1 Special variables

5.1.2 Functions

5.2 Internal definitions

5.2.1 Functions

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types

2.1 `aws-sign4`

3.1.1 `aws-sign4.asd`

3.1.2 `aws-sign4/package.lisp`

3.1.3 `aws-sign4/aws-sign4.lisp`

4.1 `aws-sign4`