126 lines
4.2 KiB
Markdown
126 lines
4.2 KiB
Markdown
# @aws-sdk/s3-request-presigner
|
|
|
|
[](https://www.npmjs.com/package/@aws-sdk/s3-request-presigner)
|
|
[](https://www.npmjs.com/package/@aws-sdk/s3-request-presigner)
|
|
|
|
This package provides a presigner based on signature V4 that will attempt to
|
|
generate signed url for S3.
|
|
|
|
### Get Presigned URL with Client and Command
|
|
|
|
You can generated presigned url from S3 client and command. Here's the example:
|
|
|
|
```javascript
|
|
import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
|
|
import { S3Client, GetObjectCommand } from "@aws-sdk/client-s3";
|
|
const client = new S3Client(clientParams);
|
|
const command = new GetObjectCommand(getObjectParams);
|
|
const url = await getSignedUrl(client, command, { expiresIn: 3600 });
|
|
```
|
|
|
|
You can get signed URL for other S3 operations too, like `PutObjectCommand`.
|
|
`expiresIn` config from the examples above is optional. If not set, it's default
|
|
at `900`.
|
|
|
|
If you already have a request, you can pre-sign the request following the
|
|
section bellow.
|
|
|
|
### Get Presigned URL from an Existing Request
|
|
|
|
```javascript
|
|
import { S3RequestPresigner } from "@aws-sdk/s3-request-presigner";
|
|
import { Sha256 } from "@aws-crypto/sha256-browser";
|
|
import { Hash } from "@aws-sdk/hash-node";
|
|
const signer = new S3RequestPresigner({
|
|
region: regionProvider,
|
|
credentials: credentialsProvider,
|
|
sha256: Hash.bind(null, "sha256"), // In Node.js
|
|
//sha256: Sha256 // In browsers
|
|
});
|
|
const presigned = await signer.presign(request);
|
|
```
|
|
|
|
To avoid redundant construction parameters when instantiating the s3 presigner,
|
|
you can simply spread the configuration of an existing s3 client and supply it to
|
|
the presigner's constructor.
|
|
|
|
```javascript
|
|
//s3 is instantiated from S3Client from @aws-sdk/client-s3-* packages
|
|
const signer = new S3RequestPresigner({
|
|
...s3.config,
|
|
});
|
|
```
|
|
|
|
### Get Presigned URL with headers that cannot be signed
|
|
|
|
By using the `getSignedUrl` with a `S3Client` you are able to sign your
|
|
headers, improving the security of presigned url. Importantly, if you want to
|
|
sign any `x-amz-*` headers (like the ChecksumSHA256 header in this example),
|
|
you need to provide those headers to the set of `unhoistableHeaders` in the
|
|
`getSignedUrl` params which will force those headers to be present in the
|
|
upload request.
|
|
|
|
```javascript
|
|
import { PutObjectCommand, S3Client } from "@aws-sdk/client-s3";
|
|
import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
|
|
|
|
const s3Client = new S3Client({ region: "us-east-1" });
|
|
const command = new PutObjectCommand({
|
|
Bucket: bucket,
|
|
Key: key,
|
|
ChecksumSHA256: sha,
|
|
});
|
|
|
|
const presigned = getSignedUrl(s3Client, command, {
|
|
expiresIn: expiration,
|
|
// Set of all x-amz-* headers you wish to have signed
|
|
unhoistableHeaders: new Set(["x-amz-checksum-sha256"]),
|
|
});
|
|
```
|
|
|
|
### Get Presigned URL with headers that should be signed
|
|
|
|
For headers that are not `x-amz-*` you are able to add them to the set of
|
|
`signableHeaders` to be enforced in the presigned urls request.
|
|
|
|
```javascript
|
|
import { PutObjectCommand, S3Client } from "@aws-sdk/client-s3";
|
|
import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
|
|
|
|
const s3Client = new S3Client({ region: "us-east-1" });
|
|
const command = new PutObjectCommand({
|
|
Bucket: bucket,
|
|
Key: key,
|
|
ContentType: contentType,
|
|
});
|
|
|
|
const presigned = getSignedUrl(s3Client, command, {
|
|
signableHeaders: new Set(["content-type"]),
|
|
expiresIn: expiration,
|
|
});
|
|
```
|
|
|
|
### PutObject with use of `hoistableHeaders`
|
|
|
|
`hoistableHeaders` overrides the default behavior of not hoisting
|
|
any headers that begin with `x-amz-*`.
|
|
|
|
```js
|
|
// example: Server Side Encryption headers
|
|
import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
|
|
import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
|
|
|
|
const params = {
|
|
Key: "...",
|
|
Bucket: "...",
|
|
ServerSideEncryption: "aws:kms",
|
|
SSEKMSKeyId: "arn:aws:kms:us-west-2:0000:key/abcd-1234-abcd",
|
|
};
|
|
const s3Client = new S3Client();
|
|
const command = new PutObjectCommand(params);
|
|
|
|
const preSignedUrl = await getSignedUrl(s3Client, command, {
|
|
hoistableHeaders: new Set(["x-amz-server-side-encryption", "x-amz-server-side-encryption-aws-kms-key-id"]),
|
|
});
|
|
```
|