The cl-ses4 Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The cl-ses4 Reference Manual

This is the cl-ses4 Reference Manual, version 1.1, generated automatically by Declt version 3.0 "Montgomery Scott" on Mon Apr 19 15:19:25 2021 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

CL-SES4

This is a library for using Amazon Web Services (AWS) Simple Email Service (SES) to send emails using the newer Signature Version 4 signing process.

Usage

Stand-alone program

The included build.sh script will produce a binary with SBCL.

$ ./build.sh
$ ./ses-send-email -h
Usage: ses-send-email -k FILE [OPTIONS]
  -h  --help             Display this help menu
  -k  --keys=FILE        The AWS credentials file to use. Should be in the form
(("aws-access-key" . "")
 ("aws-secret-key" . ""))

  -e  --endpoint=URL     The Amazon SES endpoint to use. If an endpoint is not specified, the default of "https://email.us-east-1.amazonaws.com/" is used.
  -f  --from=FROM_EMAIL  The email of the sender.
  -t  --to=TO_EMAIL      The email of the receiver.
  -s  --subject=SUBJECT  The subject of the email.
  -m  --message=MESSAGE  The email body.
  -r  --raw              Send a raw email. Data will be read from STDIN.

Examples:
ses-send-mail -k aws-credentials -r < /my-email.txt
cat my-email.txt | ses-send-mail -k aws-credentials -r
ses-send-mail -k aws-credentials -f noreply@example.com -t user@example.com -s Subject -m 'Hello User'

The binary also works as the target for PHP's mail(), i.e. configure your php.ini file to include the line:

sendmail_path = /path/to/ses-send-email -k /path/to/aws-credentials -r

Library

After loading the system cl-ses4, the main package is ses4. Bind ses4:*ses-host* and ses4:*ses-region* if you need to be different from the default (SES verifies your emails region-by-region), also set ses4:*access-key* and ses4:*secret-key* to your respective credentials.

You can then call (ses4:send-simple-email ...) or (ses4:send-raw-email ...) depending on your needs.

Limitations

This was made primarily to solve my own use case, as such I have made no special effort to support things like multiple recipients, CC/BCC, more expressive email addresses, special support for HTML emails beyond setting the header yourself in a raw email, using any of the other not-email-sending API endpoints that SES exposes, more specific errors and error handling than what's present, or validating anything works in other Common Lisp implementations. (The tests did pass in CCL.)

If you have a specific feature request not yet supported, or run into a bug, feel free to file an Issue or submit a Pull Request.

Copyright License

This library is free software released into the public domain. See UNLICENSE for more details.

Motivation

Amazon deprecated the old version 3 signing process, which will at some point (likely March 2021) break the 10+ year old Perl script I've been using. There is another Common Lisp project related to sending emails with SES, cl-ses, however it too uses the old version 3 signing process and I felt like it would be easier to start from scratch. Perhaps in the future we can merge into a single project, or a new project can supersede both.


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

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


Previous: , Up: Systems   [Contents][Index]

2.1 cl-ses4

Author

Kevin Secretan <github@thejach.com>

License

Public Domain

Description

AWS SES email sender using Signature Version 4 of Amazon’s API

Version

1.1

Dependencies
Source

cl-ses4.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Files

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


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 cl-ses4.asd

Location

/home/quickref/quicklisp/dists/quicklisp/software/cl-ses4-20210411-git/cl-ses4.asd

Systems

cl-ses4 (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 cl-ses4/sig.lisp

Parent

cl-ses4 (system)

Location

sig.lisp

Packages

ses4/sig

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.3 cl-ses4/canonicalize.lisp

Dependency

sig.lisp (file)

Parent

cl-ses4 (system)

Location

canonicalize.lisp

Packages

ses4/canonicalize

Exported Definitions
Internal Definitions

Previous: , Up: Lisp files   [Contents][Index]

3.1.4 cl-ses4/ses.lisp

Dependency

canonicalize.lisp (file)

Parent

cl-ses4 (system)

Location

ses.lisp

Packages

ses4

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Next: , Previous: , Up: Packages   [Contents][Index]

4.1 ses4/sig

Functions related to hashing and cryptographically SIGning data used for the AWS request

Source

sig.lisp (file)

Use List
Used By List
Exported Definitions
Internal Definitions

Next: , Previous: , Up: Packages   [Contents][Index]

4.2 ses4/canonicalize

Functions related to canonicalizing data used
for the AWS request into the expected formats

Source

canonicalize.lisp (file)

Use List
Used By List

ses4

Exported Definitions
Internal Definitions

Previous: , Up: Packages   [Contents][Index]

4.3 ses4

Primary package for cl-ses4, exports two functions for sending mail and a main function to run as a standalone program.

Source

ses.lisp (file)

Use List
Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

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


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Special variables

Special Variable: *access-key*
Package

ses4

Source

ses.lisp (file)

Special Variable: *region*
Package

ses4

Source

ses.lisp (file)

Special Variable: *secret-key*
Package

ses4

Source

ses.lisp (file)

Special Variable: *ses-host*
Package

ses4

Source

ses.lisp (file)


Previous: , Up: Exported definitions   [Contents][Index]

5.1.2 Functions

Function: amazon-iso-8601-basic-time DATE-TIME

Returns date-time in the format YYYYMMDDTHHMMSSZ, which is required by Amazon.

Package

ses4/sig

Source

sig.lisp (file)

Function: canonicalize-headers HEADERS

Given an alist of headers, canonicalize them as per https://docs.aws.amazon.com/general/latest/gr/sigv4-create-canonical-request.html The result will be a string with all header names lowercased and sorted, with each followed by a colon, a trimmed value, then a newline. The trimming process removes excess whitespace before/after the value and replaces sequential spaces with a single space.

Package

ses4/canonicalize

Source

canonicalize.lisp (file)

Function: canonicalize-query-string QS

Canonicalizes query string to AWS rules as per https://docs.aws.amazon.com/general/latest/gr/sigv4-create-canonical-request.html Expects the query string either as a string in the form ’Param1=Val1&Param2=Val2’, with any equal signs in either names or values already encoded to %3D, or an alist of query params in the form ((Param1 . Val1) (Param2 . Val2)) with not-yet-encoded equal signs. Returns the query string as a string in the form ’Param1=Val1&Param2=Val2’

Package

ses4/canonicalize

Source

canonicalize.lisp (file)

Function: canonicalize-signed-headers HEADERS

Return list of headers in alist of HEADERS used as the signed headers value in https://docs.aws.amazon.com/general/latest/gr/sigv4-create-canonical-request.html Each header name is lowercased, sorted, and joined with a semicolon separator. Values are not included.

Package

ses4/canonicalize

Source

canonicalize.lisp (file)

Function: canonicalize-uri URI

Canonicalizes URI as per https://docs.aws.amazon.com/general/latest/gr/sigv4-create-canonical-request.html Specifically, each path segment is uri-encoded twice, and redundant or relative path components are removed.

Package

ses4/canonicalize

Source

canonicalize.lisp (file)

Function: create-authorization-header ACCESS-KEY DATE REGION SERVICE HEADERS SIGNATURE

Creates the header value part of the Authorization header defined by https://docs.aws.amazon.com/general/latest/gr/sigv4-add-signature-to-request.html

Package

ses4/canonicalize

Source

canonicalize.lisp (file)

Function: create-canonical-request HTTP-REQUEST-METHOD URI QUERY-STRING HEADERS REQUEST-PAYLOAD

Following https://docs.aws.amazon.com/general/latest/gr/sigv4-create-canonical-request.html constructs a canonical request given each not-yet-canonicalized parameter.
Note headers should be an alist.
Query string can be either an alist (recommended) or a string

Package

ses4/canonicalize

Source

canonicalize.lisp (file)

Function: create-initial-ses-headers DATE-TIME HOST CONTENT-LENGTH
Package

ses4/canonicalize

Source

canonicalize.lisp (file)

Function: create-string-to-sign DATE-TIME REGION SERVICE CANONICAL-REQUEST

Given a local-time:timestamp, a region, a service, and a cononical request (created by #’create-canonical-request) returns a string to sign according to https://docs.aws.amazon.com/general/latest/gr/sigv4-create-string-to-sign.html with AWS4-HMAC-SHA256 as the default algorithm.

Package

ses4/sig

Source

sig.lisp (file)

Function: credential-scope DATE-TIME REGION SERVICE
Package

ses4/sig

Source

sig.lisp (file)

Function: derive-signing-key SECRET-KEY DATE REGION SERVICE

Given an AWS Secret Access Key, a local-time:timestamp, region, and service,
computes the signing key as per https://docs.aws.amazon.com/general/latest/gr/sigv4-calculate-signature.html

Package

ses4/sig

Source

sig.lisp (file)

Function: hash-payload PAYLOAD

Creates HashedPayload = Lowercase(HexEncode(Hash(payload))) using SHA256

Package

ses4/sig

Source

sig.lisp (file)

Function: hex-digest BYTE-VEC
Package

ses4/sig

Source

sig.lisp (file)

Function: hmac-sha256 KEY DATA &aux MAC
Package

ses4/sig

Source

sig.lisp (file)

Function: main ()
Package

ses4

Source

ses.lisp (file)

Function: send-raw-email RAW

Sends a raw email, suitable as input from something expecting a sendmail-like interface, formatted like MIME-Version: 1.0
Content-type: text/html; charset=utf-8
From: user@example.com
To: to@example.com
Subject: Thing

<html>
...
</html>

Package

ses4

Source

ses.lisp (file)

Function: send-simple-email &key FROM TO SUBJECT BODY

Sends a simple text email to one recipient.

Package

ses4

Source

ses.lisp (file)

Function: sha256 STR
Package

ses4/sig

Source

sig.lisp (file)

Function: sign DERIVED-KEY STRING-TO-SIGN

Computes signature for the derived key and string-to-sign calculated by above functions

Package

ses4/sig

Source

sig.lisp (file)


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Special variables

Special Variable: *service*
Package

ses4

Source

ses.lisp (file)

Special Variable: +amazon-iso-8601-basic-time-format+
Package

ses4/sig

Source

sig.lisp (file)

Special Variable: +credential-scope-date-format+
Package

ses4/sig

Source

sig.lisp (file)

Special Variable: +iso-8601-time-format+
Package

ses4/sig

Source

sig.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Functions

Function: -main ARGS
Package

ses4

Source

ses.lisp (file)

Function: assoc-v ITEM ALIST
Package

ses4

Source

ses.lisp (file)

Function: handle-endpoint ENDPOINT
Package

ses4

Source

ses.lisp (file)

Function: handle-keys KEYFILE
Package

ses4

Source

ses.lisp (file)

Function: send-email EMAIL-PARAMS
Package

ses4

Source

ses.lisp (file)

Function: sort-query-params PARAMS

Given an alist of query params, sorts them by param name in ascending order. Params with duplicate names are then sorted by value.

Package

ses4/canonicalize

Source

canonicalize.lisp (file)

Function: spaces-merge STRING

Merges sequential spaces into a single space

Package

ses4/canonicalize

Source

canonicalize.lisp (file)

Function: trim STRING

Trims leading/ending whitespace

Package

ses4/canonicalize

Source

canonicalize.lisp (file)

Function: yyyymmdd DATE-TIME
Package

ses4/sig

Source

sig.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.3 Generic functions

Generic Function: ses-error-msg CONDITION
Generic Function: (setf ses-error-msg) NEW-VALUE CONDITION
Package

ses4

Methods
Method: ses-error-msg (CONDITION ses-error)
Method: (setf ses-error-msg) NEW-VALUE (CONDITION ses-error)
Source

ses.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.4 Conditions

Condition: ses-error ()
Package

ses4

Source

ses.lisp (file)

Direct superclasses

error (condition)

Direct methods
Direct slots
Slot: msg
Initargs

:msg

Readers

ses-error-msg (generic function)

Writers

(setf ses-error-msg) (generic function)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   C   F   L  
Index Entry  Section

C
cl-ses4.asd: The cl-ses4․asd file
cl-ses4/canonicalize.lisp: The cl-ses4/canonicalize․lisp file
cl-ses4/ses.lisp: The cl-ses4/ses․lisp file
cl-ses4/sig.lisp: The cl-ses4/sig․lisp file

F
File, Lisp, cl-ses4.asd: The cl-ses4․asd file
File, Lisp, cl-ses4/canonicalize.lisp: The cl-ses4/canonicalize․lisp file
File, Lisp, cl-ses4/ses.lisp: The cl-ses4/ses․lisp file
File, Lisp, cl-ses4/sig.lisp: The cl-ses4/sig․lisp file

L
Lisp File, cl-ses4.asd: The cl-ses4․asd file
Lisp File, cl-ses4/canonicalize.lisp: The cl-ses4/canonicalize․lisp file
Lisp File, cl-ses4/ses.lisp: The cl-ses4/ses․lisp file
Lisp File, cl-ses4/sig.lisp: The cl-ses4/sig․lisp file

Jump to:   C   F   L  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   (   -  
A   C   D   F   G   H   M   S   T   Y  
Index Entry  Section

(
(setf ses-error-msg): Internal generic functions
(setf ses-error-msg): Internal generic functions

-
-main: Internal functions

A
amazon-iso-8601-basic-time: Exported functions
assoc-v: Internal functions

C
canonicalize-headers: Exported functions
canonicalize-query-string: Exported functions
canonicalize-signed-headers: Exported functions
canonicalize-uri: Exported functions
create-authorization-header: Exported functions
create-canonical-request: Exported functions
create-initial-ses-headers: Exported functions
create-string-to-sign: Exported functions
credential-scope: Exported functions

D
derive-signing-key: Exported functions

F
Function, -main: Internal functions
Function, amazon-iso-8601-basic-time: Exported functions
Function, assoc-v: Internal functions
Function, canonicalize-headers: Exported functions
Function, canonicalize-query-string: Exported functions
Function, canonicalize-signed-headers: Exported functions
Function, canonicalize-uri: Exported functions
Function, create-authorization-header: Exported functions
Function, create-canonical-request: Exported functions
Function, create-initial-ses-headers: Exported functions
Function, create-string-to-sign: Exported functions
Function, credential-scope: Exported functions
Function, derive-signing-key: Exported functions
Function, handle-endpoint: Internal functions
Function, handle-keys: Internal functions
Function, hash-payload: Exported functions
Function, hex-digest: Exported functions
Function, hmac-sha256: Exported functions
Function, main: Exported functions
Function, send-email: Internal functions
Function, send-raw-email: Exported functions
Function, send-simple-email: Exported functions
Function, sha256: Exported functions
Function, sign: Exported functions
Function, sort-query-params: Internal functions
Function, spaces-merge: Internal functions
Function, trim: Internal functions
Function, yyyymmdd: Internal functions

G
Generic Function, (setf ses-error-msg): Internal generic functions
Generic Function, ses-error-msg: Internal generic functions

H
handle-endpoint: Internal functions
handle-keys: Internal functions
hash-payload: Exported functions
hex-digest: Exported functions
hmac-sha256: Exported functions

M
main: Exported functions
Method, (setf ses-error-msg): Internal generic functions
Method, ses-error-msg: Internal generic functions

S
send-email: Internal functions
send-raw-email: Exported functions
send-simple-email: Exported functions
ses-error-msg: Internal generic functions
ses-error-msg: Internal generic functions
sha256: Exported functions
sign: Exported functions
sort-query-params: Internal functions
spaces-merge: Internal functions

T
trim: Internal functions

Y
yyyymmdd: Internal functions

Jump to:   (   -  
A   C   D   F   G   H   M   S   T   Y  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   *   +  
M   S  
Index Entry  Section

*
*access-key*: Exported special variables
*region*: Exported special variables
*secret-key*: Exported special variables
*service*: Internal special variables
*ses-host*: Exported special variables

+
+amazon-iso-8601-basic-time-format+: Internal special variables
+credential-scope-date-format+: Internal special variables
+iso-8601-time-format+: Internal special variables

M
msg: Internal conditions

S
Slot, msg: Internal conditions
Special Variable, *access-key*: Exported special variables
Special Variable, *region*: Exported special variables
Special Variable, *secret-key*: Exported special variables
Special Variable, *service*: Internal special variables
Special Variable, *ses-host*: Exported special variables
Special Variable, +amazon-iso-8601-basic-time-format+: Internal special variables
Special Variable, +credential-scope-date-format+: Internal special variables
Special Variable, +iso-8601-time-format+: Internal special variables

Jump to:   *   +  
M   S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   C   P   S  
Index Entry  Section

C
cl-ses4: The cl-ses4 system
Condition, ses-error: Internal conditions

P
Package, ses4: The ses4 package
Package, ses4/canonicalize: The ses4/canonicalize package
Package, ses4/sig: The ses4/sig package

S
ses-error: Internal conditions
ses4: The ses4 package
ses4/canonicalize: The ses4/canonicalize package
ses4/sig: The ses4/sig package
System, cl-ses4: The cl-ses4 system

Jump to:   C   P   S