awsauth

README

go-aws-auth

Go-AWS-Auth is a comprehensive, lightweight library for signing requests to Amazon Web Services.

It's easy to use: simply build your HTTP request and call awsauth.Sign(req) before sending your request over the wire.

Full GoDoc Documentation

Supported signing mechanisms

• Signed Signature Version 2
• Signed Signature Version 3
• Signed Signature Version 4
• Custom S3 Authentication Scheme
• Security Token Service
• S3 Query String Authentication
• IAM Role

For more info about AWS authentication, see the comprehensive docs at AWS.

Install

Go get it:

$ go get github.com/smartystreets/go-aws-auth

Then import it:

import "github.com/smartystreets/awsauth"

Using your AWS Credentials

The library looks for credentials in this order:

1. Hard-code: You can manually wire the credentials into awsauth.Keys for testing or spike code:

   awsauth.Keys = &awsauth.Credentials{
   	AccessKeyID: "Access Key ID", 
   	SecretAccessKey: "Secret Access Key",
   	SecurityToken: "Security Token",	// STS (optional)
   }
   

2. Environment variables: Set the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables with your credentials. The library will automatically detect and use them. Optionally, you may also set the AWS_SECURITY_TOKEN environment variable if you are using temporary credentials from STS.

3. IAM Role: If running on EC2 and the credentials are neither hard-coded nor in the environment, go-aws-auth will detect the first IAM role assigned to the current EC2 instance and use those credentials.

Be especially careful with option 1 if the code is committed to source control.

Signing requests

Once your credentials are set up, just make the request, have it signed, and perform the request as usual.

url := "https://iam.amazonaws.com/?Action=ListRoles&Version=2010-05-08"
client := &http.Client{}

req, err := http.NewRequest("GET", url, nil)

awsauth.Sign(req)	// Automatically chooses the best signing mechanism for the service

resp, err := client.Do(req)

Contributing

This library is nearing feature-complete and should work well for most common AWS interactions. Please feel free to contribute by forking, opening issues, submitting pull requests, etc. Thanks to all contributors! Can't wait until we hit 1.0!

Documentation

Overview

Package awsauth implements AWS request signing using Signed Signature Version 2, Signed Signature Version 4, and the S3 Custom HTTP Authentication Scheme.

Index

• func Sign(req *http.Request) *http.Request
• func Sign2(req *http.Request) *http.Request
• func Sign3(req *http.Request) *http.Request
• func Sign4(req *http.Request) *http.Request
• func SignS3(req *http.Request) *http.Request
• func SignS3Url(req *http.Request, expire time.Time) *http.Request
• type Credentials

Functions

func Sign

func Sign(req *http.Request) *http.Request

Sign signs a request bound for AWS. It automatically chooses the best authentication scheme based on the service the request is going to.

func Sign2

func Sign2(req *http.Request) *http.Request

Sign2 signs a request with Signed Signature Version 2. If the service you're accessing supports Version 4, use that instead.

func Sign3

func Sign3(req *http.Request) *http.Request

Sign3 signs a request with Signed Signature Version 3. If the service you're accessing supports Version 4, use that instead.

func Sign4

func Sign4(req *http.Request) *http.Request

Sign4 signs a request with Signed Signature Version 4.

func SignS3

func SignS3(req *http.Request) *http.Request

SignS3 signs a request bound for Amazon S3 using their custom HTTP authentication scheme.

func SignS3Url

func SignS3Url(req *http.Request, expire time.Time) *http.Request

SignS3Url signs a GET request for a resource on Amazon S3 by appending query string parameters containing credentials and signature. You must specify an expiration date for these signed requests. After that date, a request signed with this method will be rejected by S3.

Types

type Credentials

type Credentials struct {
	AccessKeyID     string
	SecretAccessKey string
	SecurityToken   string `json:"Token"`
	Expiration      time.Time
}

var Keys *Credentials

Keys stores the authentication credentials to be used when signing requests. You can set them manually or leave it to awsauth to use environment variables.