You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

183 lines
6.3 KiB

  1. aws4
  2. ----
  3. [![Build Status](https://api.travis-ci.org/mhart/aws4.png?branch=master)](https://travis-ci.org/github/mhart/aws4)
  4. A small utility to sign vanilla Node.js http(s) request options using Amazon's
  5. [AWS Signature Version 4](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html).
  6. If you want to sign and send AWS requests in a modern browser, or an environment like [Cloudflare Workers](https://developers.cloudflare.com/workers/), then check out [aws4fetch](https://github.com/mhart/aws4fetch) – otherwise you can also bundle this library for use [in older browsers](./browser).
  7. The only AWS service that *doesn't* support v4 as of 2020-05-22 is
  8. [SimpleDB](https://docs.aws.amazon.com/AmazonSimpleDB/latest/DeveloperGuide/SDB_API.html)
  9. (it only supports [AWS Signature Version 2](https://github.com/mhart/aws2)).
  10. It also provides defaults for a number of core AWS headers and
  11. request parameters, making it very easy to query AWS services, or
  12. build out a fully-featured AWS library.
  13. Example
  14. -------
  15. ```javascript
  16. var https = require('https')
  17. var aws4 = require('aws4')
  18. // to illustrate usage, we'll create a utility function to request and pipe to stdout
  19. function request(opts) { https.request(opts, function(res) { res.pipe(process.stdout) }).end(opts.body || '') }
  20. // aws4 will sign an options object as you'd pass to http.request, with an AWS service and region
  21. var opts = { host: 'my-bucket.s3.us-west-1.amazonaws.com', path: '/my-object', service: 's3', region: 'us-west-1' }
  22. // aws4.sign() will sign and modify these options, ready to pass to http.request
  23. aws4.sign(opts, { accessKeyId: '', secretAccessKey: '' })
  24. // or it can get credentials from process.env.AWS_ACCESS_KEY_ID, etc
  25. aws4.sign(opts)
  26. // for most AWS services, aws4 can figure out the service and region if you pass a host
  27. opts = { host: 'my-bucket.s3.us-west-1.amazonaws.com', path: '/my-object' }
  28. // usually it will add/modify request headers, but you can also sign the query:
  29. opts = { host: 'my-bucket.s3.amazonaws.com', path: '/?X-Amz-Expires=12345', signQuery: true }
  30. // and for services with simple hosts, aws4 can infer the host from service and region:
  31. opts = { service: 'sqs', region: 'us-east-1', path: '/?Action=ListQueues' }
  32. // and if you're using us-east-1, it's the default:
  33. opts = { service: 'sqs', path: '/?Action=ListQueues' }
  34. aws4.sign(opts)
  35. console.log(opts)
  36. /*
  37. {
  38. host: 'sqs.us-east-1.amazonaws.com',
  39. path: '/?Action=ListQueues',
  40. headers: {
  41. Host: 'sqs.us-east-1.amazonaws.com',
  42. 'X-Amz-Date': '20121226T061030Z',
  43. Authorization: 'AWS4-HMAC-SHA256 Credential=ABCDEF/20121226/us-east-1/sqs/aws4_request, ...'
  44. }
  45. }
  46. */
  47. // we can now use this to query AWS
  48. request(opts)
  49. /*
  50. <?xml version="1.0"?>
  51. <ListQueuesResponse xmlns="https://queue.amazonaws.com/doc/2012-11-05/">
  52. ...
  53. */
  54. // aws4 can infer the HTTP method if a body is passed in
  55. // method will be POST and Content-Type: 'application/x-www-form-urlencoded; charset=utf-8'
  56. request(aws4.sign({ service: 'iam', body: 'Action=ListGroups&Version=2010-05-08' }))
  57. /*
  58. <ListGroupsResponse xmlns="https://iam.amazonaws.com/doc/2010-05-08/">
  59. ...
  60. */
  61. // you can specify any custom option or header as per usual
  62. request(aws4.sign({
  63. service: 'dynamodb',
  64. region: 'ap-southeast-2',
  65. method: 'POST',
  66. path: '/',
  67. headers: {
  68. 'Content-Type': 'application/x-amz-json-1.0',
  69. 'X-Amz-Target': 'DynamoDB_20120810.ListTables'
  70. },
  71. body: '{}'
  72. }))
  73. /*
  74. {"TableNames":[]}
  75. ...
  76. */
  77. // The raw RequestSigner can be used to generate CodeCommit Git passwords
  78. var signer = new aws4.RequestSigner({
  79. service: 'codecommit',
  80. host: 'git-codecommit.us-east-1.amazonaws.com',
  81. method: 'GIT',
  82. path: '/v1/repos/MyAwesomeRepo',
  83. })
  84. var password = signer.getDateTime() + 'Z' + signer.signature()
  85. // see example.js for examples with other services
  86. ```
  87. API
  88. ---
  89. ### aws4.sign(requestOptions, [credentials])
  90. Calculates and populates any necessary AWS headers and/or request
  91. options on `requestOptions`. Returns `requestOptions` as a convenience for chaining.
  92. `requestOptions` is an object holding the same options that the Node.js
  93. [http.request](https://nodejs.org/docs/latest/api/http.html#http_http_request_options_callback)
  94. function takes.
  95. The following properties of `requestOptions` are used in the signing or
  96. populated if they don't already exist:
  97. - `hostname` or `host` (will try to be determined from `service` and `region` if not given)
  98. - `method` (will use `'GET'` if not given or `'POST'` if there is a `body`)
  99. - `path` (will use `'/'` if not given)
  100. - `body` (will use `''` if not given)
  101. - `service` (will try to be calculated from `hostname` or `host` if not given)
  102. - `region` (will try to be calculated from `hostname` or `host` or use `'us-east-1'` if not given)
  103. - `signQuery` (to sign the query instead of adding an `Authorization` header, defaults to false)
  104. - `headers['Host']` (will use `hostname` or `host` or be calculated if not given)
  105. - `headers['Content-Type']` (will use `'application/x-www-form-urlencoded; charset=utf-8'`
  106. if not given and there is a `body`)
  107. - `headers['Date']` (used to calculate the signature date if given, otherwise `new Date` is used)
  108. Your AWS credentials (which can be found in your
  109. [AWS console](https://portal.aws.amazon.com/gp/aws/securityCredentials))
  110. can be specified in one of two ways:
  111. - As the second argument, like this:
  112. ```javascript
  113. aws4.sign(requestOptions, {
  114. secretAccessKey: "<your-secret-access-key>",
  115. accessKeyId: "<your-access-key-id>",
  116. sessionToken: "<your-session-token>"
  117. })
  118. ```
  119. - From `process.env`, such as this:
  120. ```
  121. export AWS_ACCESS_KEY_ID="<your-access-key-id>"
  122. export AWS_SECRET_ACCESS_KEY="<your-secret-access-key>"
  123. export AWS_SESSION_TOKEN="<your-session-token>"
  124. ```
  125. (will also use `AWS_ACCESS_KEY` and `AWS_SECRET_KEY` if available)
  126. The `sessionToken` property and `AWS_SESSION_TOKEN` environment variable are optional for signing
  127. with [IAM STS temporary credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_use-resources.html).
  128. Installation
  129. ------------
  130. With [npm](https://www.npmjs.com/) do:
  131. ```
  132. npm install aws4
  133. ```
  134. Can also be used [in the browser](./browser).
  135. Thanks
  136. ------
  137. Thanks to [@jed](https://github.com/jed) for his
  138. [dynamo-client](https://github.com/jed/dynamo-client) lib where I first
  139. committed and subsequently extracted this code.
  140. Also thanks to the
  141. [official Node.js AWS SDK](https://github.com/aws/aws-sdk-js) for giving
  142. me a start on implementing the v4 signature.