Fill HTTPS and CURL config file templates for AWS requests. Signature version 4. CLI utility and library. About 1350 sloc of C.
C C++ PAWN SourcePawn Shell PHP Other

README.md

awsFillAndSign

Fill a CURL config file template with AWS signature version 4. Cross-platform CLI utility and library in C.
awsFillAndSign Copyright 2016-2017 MIB SOFTWARE, INC.

PURPOSE: Sign Amazon Web Services requests with AWS Signature Version 4.

LICENSE: MIT (Free/OpenSource)

STABLITY: UNSTABLE as of 2017-01-17
Check for updates at: https://github.com/forrestcavalier/awsFillAndSign
Travis-CI status: Build Status
CodeCov status: codecov

SUPPORT: Contact the author for commercial support and consulting at http://www.mibsoftware.com/

awsFillAndSign Copyright 2016-2017 MIB SOFTWARE, INC.

 USAGE: awsFillAndSign [OPTIONS] <template-name.curl> [param1[ param2...]]

   The output is the filled template with AWS Version 4 signatures.
   Credentials come from the environment variables AWS_ACCESS_KEY_ID
   and AWS_SECRET_ACCESS_KEY (unless using the --read-key option.)
   AWS_SECURITY_TOKEN is included if it is defined.


 OPTIONS:
  --from-file      Treat the template-name as a file, not a built-in template.
                   (Use --list to see built-in templates.)

  --have-sha256    The template has a SHA256 body signature.

  -b <file-name>   Calculate SHA256 body signature from specified file.
                   (Only needed if the template does not give accurate
                   upload-file or data CURL options.)

  --read-key       Read credentials from one line on stdin in the format of:
                      <ID>,<SECRET>

  --verbose        Verbose debugging output on stderr, including generated
                   AWS Canonical Request fields.

  -D <name=value>  Put name=value into the environment.

  --encode <flag>  Control percent-encoding. 0 - (default) auto-detect;
                   1 - always percent-encode; -1 - never percent-encode.

  -                Marker for end of arguments. (Useful when parameters that
                   follow may start with '-'.)

 INFORMATION commands (output is not a filled and signed template:)
  --help           Show this message.
  --list           List the built-in templates.
  --list <name>    Show the named built-in template along with comments.

Understanding Templates

Templates are small text files which mark replaceable parameters surrounded by '@'. The purpose of awsFillAndSign is to strip comments, replace the parameters, sign the request, and write the output so that CURL can run it.

If you run awsFillAndSign --list aws-s3-put.curl you will see an example: the built-in template for AWS S3 PUT Object (for file uploads):

@//aws-s3-put.curl
@// TEMPLATE FOR:  AWS S3 PUT Object
@// REST API DOCS: http://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectPUT.html
@//
@// TEMPLATE REVISION:    2016-11-26 by MIB SOFTWARE, INC.
@// TEMPLATE LICENSE:     MIT (Free/Open Source)
@// TEMPLATE PARAMETERS:
@//   @1_bucket@     - The URI-encoded bucket name
@//   @2_filename@   - The local file name. This goes into the upload-file
@//                     CURL parameter.
@//   @3_objectname@ - The URI-encoded S3 object name.
@//
@// (Use awsFillAndSign by MIB SOFTWARE to fill the template, strip comments,
@// and add AWS Signatures before using CURL. IMPORTANT: use the -bs command
@// line flag to compute the SHA256 signature of the upload-file.)
@//
@//.default.AWS_SERVICE_NAME=s3
url="https://@1_bucket@.s3.amazonaws.com/@3_objectname@"
upload-file = "@p2_filename@"
header = "Host: @1_bucket@.s3.amazonaws.com"
header = "Authorization: AWS4-HMAC-SHA256 Credential=...,SignedHeaders=...,Signature=... (all will be replaced)"
header = "x-amz-content-sha256:will be replaced"

This template specifies three parameters. These are in the template text surrounded by '@'.

When you are authoring templates, awsFillAndSign supports the following kinds of parameters:

  • Numeric: These start with a number which is the position on the command line after the command line options, starting at 1. For convenient readability, provide a label after the value. (The label part is ignored by awsFillAndSign.)
  • Environment variable: These parameters are marked with a 'e' prefix as in '@eENV_VARIABLE_NAME@'.

If the AWS_SERVICE_NAME is not given by the template, it must be in the environment.

Some parts of the request will be URL-encoded, controlled by the --encode option. By default, this is auto-detected for each parameter. If a parameter value has a percent character (%) followed by two hexadecimal ascii digits, it is considered already encoded. The template can start with @p or @pe to never encode (which is appropriate for CURL upload-file, for example.)

When there is a request body

When there is an upload-file, as there is for AWS S3 PUT, awsFillAndSign reads the file to compute the SHA256 that is required for the request. If there is a data= field, that will be used to compute the body. You can also use -b, or supply the SHA256 in the template and give the --have-sha256 option.