Generates authenticated request data to be used by a chosen http client to upload files to AWS S3 using POST.

The library receives the mandatory and optional parameters alongside with the conditions supported by AWS S3 giving back the data to be used for the upload, including policy and the signature generated using the AWS Signature Version 4 specification:

Gradle Kotlin:

implementation("io.github.dyegosutil:aws-s3-presigned-post:0.1.0-beta.3")

Maven:

<dependency>
    <groupId>io.github.dyegosutil</groupId>
    <artifactId>aws-s3-presigned-post</artifactId>
    <version>0.1.0-beta.3</version>
</dependency>

First make sure that the AWS credentials are provided using any of these possibilities and that the access key being used has the proper permission to upload in the bucket.

After that, use the PostParams builder to specify the parameters and conditions for the upload:

ZonedDateTime oneMinuteFromNow = now(systemUTC()).plus(1, MINUTES).atZone(UTC);

PostParams postParams = PostParams
    .builder(
        Region.of("eu-central-1"),      // AWS Region of the bucket
        oneMinuteFromNow,               // Expiration date 
        "myBucket",                     // Bucket name
        withKey("uploads/my_file.txt")  // Name of the S3 object key
    )
    .withContentLengthRange(7, 20)      // Adds file size upload limit
    .build();

// Generates all the necessary parameters for the pre-signed post including signature
PreSignedPost presignedPost = S3PostSigner.sign(postParams);

Use a http client in any platform to upload the file using the generated parameters from PreSignedPost.
Below is a minimalistic example using OkHttp

MultipartBody.Builder builder = new MultipartBody.Builder().setType(MultipartBody.FORM);
presignedPost.getConditions().forEach(builder::addFormDataPart);
builder.addFormDataPart(
        "file",
        "uploads/my_file.txt",
        RequestBody.create("This is a test".getBytes(), MediaType.parse("text/plain"))
);
Request request = new Request
        .Builder()
        .url(presignedPost.getUrl())
        .post(builder.build())
        .build();
try (Response response = new OkHttpClient().newCall(request).execute()) {
    if (!response.isSuccessful()) {
        throw new IOException("Upload failed. Unexpected code " + response);
    } else {
        LOGGER.info("Upload executed successfully");
    }
}

That is it. The file should be in S3 now.

Allow the uploader to use the name of the file being upload as S3 object Key:

PostParams.builder(Region.EU_CENTRAL_1, EXPIRATION_DATE, "myBucket", withAnyKey());
// Additionally, when passing the last parameter `key` to the http client, use the value `${filename}`

Allow the uploader to upload to a path starting with a defined value and to use the name of the file being upload as S3 object Key:

PostParams.builder(Region.EU_CENTRAL_1, EXPIRATION_DATE, "myBucket", "user/leo/box/");
// Additionally, when passing the last parameter `key` to the http client, use the value `user/leo/box/${filename}`

Only allow upload if the object key is test.txt(the http param, not the file name) and the file size is between 7 and 20 bytes

PostParams
        .builder(Region.EU_CENTRAL_1, EXPIRATION_DATE, "myBucket", withKey("test.txt"))
        .withContentLengthRange(7, 20)
        .build())

Allow the uploader to add any content type but enforce that the server side encryption AES256 should be specified.

PostParams
        .builder(Region.EU_CENTRAL_1, EXPIRATION_DATE, "myBucket", withKey("test.txt"))
        .withAnyContentType()
        .withServerSideEncryption(AES256)
        .build())

For more examples look into the integrationtests package inside src/test.

• Provides a guided approach with a builder to create a non-error prone PreSignedPost
• Adding the following conditions using the util methods withConditionName, withAnyConditionName and
  withConditionNameStartingWith. The ConditionName here can be any of the following:
  • Bucket
  • Region
  • Expiration Date
  • Key Name
  • Tags
  • File size
  • Success Action Status
  • Cache Control
  • File Content Type
  • Content Disposition
  • Content encoding
  • File Expire
  • Success Action Redirect
  • Acl
  • Metadata
  • Storage Class
  • Website Redirect Location
  • Checksum CRC-32
  • Checksum CRC-32C
  • Checksum SHA-1
  • Checksum SHA-256
  • Server Side Encryption Algorithm
  • AWS KMS KEY to be used to for server-side encryption
  • Server Side Encryption Context
  • Allows specifying if Amazon S3 should use an S3 Bucket Key with SSE-KMS or not
  • Allows specifying the algorithm to use to when encrypting the object.
  • Allows specifying the base64 encoded encryption key to be used for this file upload
  • Allows specifying the base64 encoded 128-bit MD5 digest of the encryption key
• PresignedFreeTextPost: an advanced option that provides flexibility for creating a Pre Signed Post on which parameters and conditions can be provided freely. Even if this library does not support a new AWS feature, using this approach will probably make it possible to use it. Note that this option requires some understanding of the AWS request creation and signing process.

• Java 8 compatible
• Remember that when using withConditionNameStartingWith, the library cannot foresee which value should be used in the client. Hence, the PreSignedPost will provide only the key but not the value for this data letting the uploader decide how to fill up this value.
• The library uses DefaultCredentialsProvider to obtain the aws credentials. Check this page to decide how to provide it
• If an ASIA aws access key is found, the library will return a new param x-amz-security-token.
• To allow the user to upload any key name, use withAnyKey() and submit in the http call for the key param the value ${filename}. Note that ${filename} variable is not compatible with withKey() condition. Only for withKeyStartingWith() and withAnyKey().
• When content-length-range is used, it is not necessary to specify this condition while using the pre signed post, even though it is in the policy. Note that this is the only exception, all other valuedConditions should be passed to aws otherwise it will return an error
• Generating S3 post data for uploading files into public access s3 buckets is not included in this library since it is pretty straight forward. That is, the only parameters necessary are the key and file.

AWS_ACCESS_KEY_ID=AKIAEXAMPLE
AWS_BUCKET=mybucket
AWS_REGION=eu-central-1
AWS_SECRET_ACCESS_KEY=mysecretaccesskey
AWS_KMS_S3_KEY=arn:aws:kms:my_region:my_account_id:key/my-key

aws-vault exec my_profile -- env | egrep '^AWS_(ACCESS_KEY_ID|SECRET_ACCESS_KEY|SESSION_TOKEN)'

aws-vault exec my_profile 
ECHO "AccessKeyId": "%AWS_ACCESS_KEY_ID%", "SecretAccessKey": "%AWS_SECRET_ACCESS_KEY%", "SessionToken": "%AWS_SESSION_TOKEN%"

<Message>The bucket does not allow ACLs</Message>

• Encapsulate complexity of validations as well as compatibility of conditions, policy and signature generation
• Preventing the generation of faulty pre signed post data
• Avoiding the library user having to dive into the AWS documentation do understand how to use the conditions.
• Provide friendly intuitive methods for specifying conditions and for generating the Pre Signed Post.

The AWS Java SDK 2 does not support the generation of Pre Signed Post, different from other AWS SDKs such as JS which does support it. What is offered for Java is the Pre Signed Put which does not support all the conditions available in the Pre Signed Post such as limiting the file size of the upload and many others.

Feel free to engage, report bugs or give feedback by creating an Issue.

• AWS S3 Post Policy
• AWS S3 Post Object
• Signing AWS API requests