NAME

vmod_awsrest - Awsrest VMOD

SYNOPSIS

import awsrest [from "path"] ;

DESCRIPTION

Append aws signature v4 to req/bereq.

•: https://github.com/xcir/libvmod-awsrest

•: https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html

•: STRING formurl(STRING)

•: STRING lf()

•: VOID v4_generic(STRING, STRING, STRING, STRING, STRING, STRING, STRING, BOOL)

VOID v4_generic(STRING, STRING, STRING, STRING, STRING, STRING, STRING, BOOL)

Prototype: VOID v4_generic(STRING service, STRING region, STRING access_key, STRING secret_key, STRING token, STRING signed_headers, STRING canonical_headers, BOOL feature)

Prototype

v4_generic(
    STRING service,               // [s3]
    STRING region,                // [ap-northeast-1]
    STRING access_key,            // [your access key]
    STRING secret_key,            // [your secret key]
    STRING session_token,         // [your session token (optional)]
    STRING signed_headers,        // [host;]                                   x-amz-content-sha256;x-amz-date is appended by default.
    STRING canonical_headers,     // [host:s3-ap-northeast-1.amazonaws.com\n]
    BOOL   feature                // [false]                                   reserved param
    )

Return value: VOID

Description: generate Authorization/x-amz-date/x-amz-content-sha256 header for AWS REST API.

Example(set to req.*)

import awsrest;

backend default {
  .host = "s3-ap-northeast-1.amazonaws.com";
}

sub vcl_recv{
  set req.http.host = "s3-ap-northeast-1.amazonaws.com";
  awsrest.v4_generic(
    service           = "s3",
    region            = "ap-northeast-1",
    access_key        = "[Your Access Key]",
    secret_key        = "[Your Secret Key]",
    signed_headers    = "host;",
    canonical_headers = "host:" + req.http.host + awsrest.lf()
  );
}

//data

//2 ReqHeader      c Authorization: AWS4-HMAC-SHA256 Credential=****************/20150704/ap-northeast-1/s3/aws4_request, SignedHeaders=host;x-amz-content-sha256;x-amz-date, Signature=****************
//2 ReqHeader      c x-amz-content-sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
//2 ReqHeader      c x-amz-date: 20150704T103402Z

Example(set to bereq.*)

import awsrest;

backend default {
  .host = "s3-ap-northeast-1.amazonaws.com";
}

sub vcl_backend_fetch{
  set bereq.http.host = "s3-ap-northeast-1.amazonaws.com";
  awsrest.v4_generic(
    service           = "s3",
    region            = "ap-northeast-1",
    access_key        = "[Your Access Key]",
    secret_key        = "[Your Secret Key]",
    signed_headers    = "host;",
    canonical_headers = "host:" + bereq.http.host + awsrest.lf()
  );
}
//data
//25 BereqHeader    b Authorization: AWS4-HMAC-SHA256 Credential=****************/20150704/ap-northeast-1/s3/aws4_request, SignedHeaders=host;x-amz-content-sha256;x-amz-date, Signature=****************
//25 BereqHeader    b x-amz-content-sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
//25 BereqHeader    b x-amz-date: 20150704T103159Z

Example(using session token)

import awsrest;

backend default {
  .host = "s3-ap-northeast-1.amazonaws.com";
}

sub vcl_backend_fetch{
  set bereq.http.host = "s3-ap-northeast-1.amazonaws.com";
  awsrest.v4_generic(
    service           = "s3",
    region            = "ap-northeast-1",
    access_key        = "[Your Access Key]",
    secret_key        = "[Your Secret Key]",
    token             = "[Your Session token]",
    signed_headers    = "host;",
    canonical_headers = "host:" + bereq.http.host + awsrest.lf()
  );
}
//data
//25 BereqHeader    b Authorization: AWS4-HMAC-SHA256 Credential=****************/20150704/ap-northeast-1/s3/aws4_request, SignedHeaders=host;x-amz-content-sha256;x-amz-date, Signature=****************
//25 BereqHeader    b x-amz-content-sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
//25 BereqHeader    b x-amz-date: 20150704T103159Z
//25 BereqHeader    b x-amz-security-token: [Your Session Token]

STRING lf()

Prototype: STRING lf()

Prototype

lf()

Return value: STRING

Description: return LF

Example

"x-amz-hoge1:hoge" + awsrest.lf() + "x-amz-hoge2:hoge" + awsrest.lf()


//data
x-amz-hoge1:hoge
x-amz-hoge2:hoge

STRING formurl(STRING)

Prototype: STRING formurl(STRING url)

Prototype

formurl(url)

Return value: STRING

Description: Add "=" if field is not have value and delimiter. Strip "?","&" from the end of a string. AWS signature v4's query-string require sorted field(std.querysort) and field with delimiter(this function)

Example

import awsrest;
import std;

sub vcl_recv{
  set req.url = awsrest.formurl(std.querysort(req.url));
}

//log
**** v1    0.5 vsl|       1001 ReqURL          c /?aa&cc&bb
**** v1    0.5 vsl|       1001 ReqURL          c /?aa=&bb=&cc=

COPYRIGHT

This document is licensed under the same license as the libvmod-awsrest project. See LICENSE for details.
Copyright (c) 2012-2017 Shohei Tanaka(@xcir)

File layout and configuration based on libvmod-example
Copyright (c) 2011 Varnish Software AS
hmac-sha1 and base64 based on libvmod-digest( https://github.com/varnish/libvmod-digest )