The cl-ses4 Reference Manual

This is the cl-ses4 Reference Manual, version 1.3, generated automatically by Declt version 4.0 beta 2 "William Riker" on Fri Sep 15 04:22:48 2023 GMT+0.

Table of Contents


1 Introduction


2 Systems

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


2.1 cl-ses4

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

Author

Kevin Secretan <>

License

Public Domain

Version

1.3

Dependencies
  • dexador (system).
  • ironclad (system).
  • quri (system).
  • cl-ppcre (system).
  • local-time (system).
  • arrow-macros (system).
  • cl-base64 (system).
  • quickapp (system).
Source

cl-ses4.asd.

Child Components

3 Files

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


3.1 Lisp


3.1.1 cl-ses4/cl-ses4.asd

Source

cl-ses4.asd.

Parent Component

cl-ses4 (system).

ASDF Systems

cl-ses4.


3.1.2 cl-ses4/sig.lisp

Source

cl-ses4.asd.

Parent Component

cl-ses4 (system).

Packages

ses4/sig.

Public Interface
Internals

3.1.3 cl-ses4/canonicalize.lisp

Dependency

sig.lisp (file).

Source

cl-ses4.asd.

Parent Component

cl-ses4 (system).

Packages

ses4/canonicalize.

Public Interface
Internals

3.1.4 cl-ses4/ses.lisp

Dependency

canonicalize.lisp (file).

Source

cl-ses4.asd.

Parent Component

cl-ses4 (system).

Packages

ses4.

Public Interface
Internals

4 Packages

Packages are listed by definition order.


4.1 ses4/sig

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

Source

sig.lisp.

Use List
  • arrow-macros.
  • common-lisp.
Used By List
Public Interface
Internals

4.2 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.

Use List
Public Interface
Internals

4.3 ses4/canonicalize

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

Source

canonicalize.lisp.

Use List
Used By List

ses4.

Public Interface
Internals

5 Definitions

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


5.1 Public Interface


5.1.1 Special variables

Special Variable: *access-key*
Package

ses4.

Source

ses.lisp.

Special Variable: *region*
Package

ses4.

Source

ses.lisp.

Special Variable: *secret-key*
Package

ses4.

Source

ses.lisp.

Special Variable: *ses-host*
Package

ses4.

Source

ses.lisp.


5.1.2 Ordinary 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.

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.

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.

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.

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.

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.

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.

Function: create-initial-ses-headers (date-time host content-length)
Package

ses4/canonicalize.

Source

canonicalize.lisp.

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.

Function: credential-scope (date-time region service)
Package

ses4/sig.

Source

sig.lisp.

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.

Function: hash-payload (payload)

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

Package

ses4/sig.

Source

sig.lisp.

Function: hex-digest (byte-vec)
Package

ses4/sig.

Source

sig.lisp.

Function: hmac-sha256 (key data)
Package

ses4/sig.

Source

sig.lisp.

Function: main ()
Package

ses4.

Source

ses.lisp.

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.

Function: send-simple-email (&key from to subject body)

Sends a simple text email to one recipient.

Package

ses4.

Source

ses.lisp.

Function: sha256 (str)
Package

ses4/sig.

Source

sig.lisp.

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.


5.2 Internals


5.2.1 Special variables

Special Variable: *service*
Package

ses4.

Source

ses.lisp.

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

ses4/sig.

Source

sig.lisp.

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

ses4/sig.

Source

sig.lisp.

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

ses4/sig.

Source

sig.lisp.


5.2.2 Ordinary functions

Function: -main (args)
Package

ses4.

Source

ses.lisp.

Function: assoc-v (item alist)
Package

ses4.

Source

ses.lisp.

Function: handle-endpoint (endpoint)
Package

ses4.

Source

ses.lisp.

Function: handle-keys (keyfile)
Package

ses4.

Source

ses.lisp.

Function: send-email (email-params)
Package

ses4.

Source

ses.lisp.

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.

Function: spaces-merge (string)

Merges sequential spaces into a single space

Package

ses4/canonicalize.

Source

canonicalize.lisp.

Function: trim (string)

Trims leading/ending whitespace

Package

ses4/canonicalize.

Source

canonicalize.lisp.

Function: yyyymmdd (date-time)
Package

ses4/sig.

Source

sig.lisp.


5.2.3 Generic functions

Generic Reader: ses-error-msg (condition)
Generic Writer: (setf ses-error-msg) (condition)
Package

ses4.

Methods
Reader Method: ses-error-msg ((condition ses-error))
Writer Method: (setf ses-error-msg) ((condition ses-error))
Source

ses.lisp.

Target Slot

msg.


5.2.4 Conditions

Condition: ses-error
Package

ses4.

Source

ses.lisp.

Direct superclasses

error.

Direct methods
Direct slots
Slot: msg
Initargs

:msg

Readers

ses-error-msg.

Writers

(setf ses-error-msg).


Appendix A Indexes


A.1 Concepts


A.2 Functions

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

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

-
-main: Private ordinary functions

A
amazon-iso-8601-basic-time: Public ordinary functions
assoc-v: Private ordinary functions

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

D
derive-signing-key: Public ordinary functions

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

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

H
handle-endpoint: Private ordinary functions
handle-keys: Private ordinary functions
hash-payload: Public ordinary functions
hex-digest: Public ordinary functions
hmac-sha256: Public ordinary functions

M
main: Public ordinary functions
Method, (setf ses-error-msg): Private generic functions
Method, ses-error-msg: Private generic functions

S
send-email: Private ordinary functions
send-raw-email: Public ordinary functions
send-simple-email: Public ordinary functions
ses-error-msg: Private generic functions
ses-error-msg: Private generic functions
sha256: Public ordinary functions
sign: Public ordinary functions
sort-query-params: Private ordinary functions
spaces-merge: Private ordinary functions

T
trim: Private ordinary functions

Y
yyyymmdd: Private ordinary functions