Skip to content

Update docs in prep for 1.6.1 #133

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 15 commits into from
Oct 29, 2019
Merged

Update docs in prep for 1.6.1 #133

Show file tree
Hide file tree
Changes from 11 commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
eb3083e
Update docs in prep for 1.6.1
SalusaSecondus Oct 24, 2019
51586c9
Fix BC-FIPS artifactID
SalusaSecondus Oct 25, 2019
de5976c
Update CHANGELOG.md
SalusaSecondus Oct 25, 2019
575228e
Update CHANGELOG.md
SalusaSecondus Oct 25, 2019
ab92b57
Update README.md
SalusaSecondus Oct 25, 2019
f8d07a0
Update README.md
SalusaSecondus Oct 25, 2019
14a68d3
Update README.md
SalusaSecondus Oct 25, 2019
e2a8e08
Update CHANGELOG.md
SalusaSecondus Oct 25, 2019
d82630a
Update README.md
SalusaSecondus Oct 25, 2019
239fa59
More minor language tweaks
SalusaSecondus Oct 25, 2019
ff69afa
More minor language tweaks
SalusaSecondus Oct 25, 2019
2dc1cc4
Language tweaks
SalusaSecondus Oct 29, 2019
cf38324
Language tweaks
SalusaSecondus Oct 29, 2019
e23ac0e
Actually bump version for release
SalusaSecondus Oct 29, 2019
775bb03
Merge branch 'master' into changelog
SalusaSecondus Oct 29, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 18 additions & 4 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,24 @@
# Changelog

## 1.6.1 -- Unreleased

### Deprecation Warnings
* Deprecated `AwsCrypto.encryptString()` and `AwsCrypto.decryptString()`.
Please move to `AwsCrypto.encryptData()` and `AwsCrypto.decryptData()` with manual Base64 encoding/decoding.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Please move to `AwsCrypto.encryptData()` and `AwsCrypto.decryptData()` with manual Base64 encoding/decoding.
Replace your calls to these methods with calls to `AwsCrypto.encryptData()` and `AwsCrypto.decryptData()`. These methods use manual Base64 encoding/decoding, so they are fully compatible with other language implementations of the AWS Encryption SDK.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The new methods don't use Base64 encoding and will require the developer to apply it themselves. Do you have better wording for that?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Replace your calls to these methods with calls to AwsCrypto.encryptData() and AwsCrypto.decryptData(). Because these methods don't perform any Base64 encoding or decoding, they are fully compatible with other language implementations of the AWS Encryption SDK.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Replace your calls to these methods with calls to AwsCrypto.encryptData() and AwsCrypto.decryptData(). Unlike the deprecated methods, these methods don't perform any Base64 encoding or decoding, so they are fully compatible with other language implementations of the AWS Encryption SDK.

If you need Base64 encoding or decoding for your application, you can add it outside of the AWS Encryption SDK.

[PR #120](https://github.com/aws/aws-encryption-sdk-java/pull/120)

### Patches
* Correctly validate version [PR #116](https://github.com/aws/aws-encryption-sdk-java/pull/116)
* `ParsedCiphertext` now handles truncated input properly [PR #119](https://github.com/aws/aws-encryption-sdk-java/pull/119)

### Maintenance
* Add support for standard test vectors via `testVectorZip` system property.
* No longer require use of BouncyCastle with RSA `JceMasterKey`s
* No longer use BouncyCastle for Elliptic Curve key generation and point compression/decompression
* Add support for standard test vectors via `testVectorZip` system property. [PR #127](https://github.com/aws/aws-encryption-sdk-java/pull/127)
* Remove all explicit cryptographic dependencies on BouncyCastle. The AWS Encryption SDK for Java still uses Bouncy Castle for other tasks. PRs
[#128](https://github.com/aws/aws-encryption-sdk-java/pull/128),
[#129](https://github.com/aws/aws-encryption-sdk-java/pull/129),
[#130](https://github.com/aws/aws-encryption-sdk-java/pull/130),
[#131](https://github.com/aws/aws-encryption-sdk-java/pull/131),
and [#132](https://github.com/aws/aws-encryption-sdk-java/pull/132).

## 1.6.0 -- 2019-05-31

Expand All @@ -17,7 +31,7 @@
## 1.5.0 -- 2019-05-30

### Minor Changes
* Add dependency on Apache Commons Codec 1.12.
* Added dependency on Apache Commons Codec 1.12.
* Use org.apache.commons.codec.binary.Base64 instead of java.util.Base64 so
that the SDK can be used on systems that do not have java.util.Base64 but
support Java 8 language features.
Expand Down
50 changes: 20 additions & 30 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,26 +9,31 @@ For more details about the design and architecture of the SDK, see the [official
### Required Prerequisites
To use this SDK you must have:

* **A Java 8 development environment**
* **A Java 8 or newer development environment**

If you do not have one, go to [Java SE Downloads](https://www.oracle.com/technetwork/java/javase/downloads/index.html) on the Oracle website, then download and install the Java SE Development Kit (JDK). Java 8 or higher is required.
If you do not have one, we recommend [Amazon Corretto](https://aws.amazon.com/corretto/).

**Note:** If you use the Oracle JDK, you must also download and install the [Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files](http://www.oracle.com/technetwork/java/javase/downloads/jce8-download-2133166.html).

* **Bouncy Castle**
* **Bouncy Castle** or **Bouncy Castle FIPS**

Bouncy Castle provides a cryptography API for Java. If you do not have Bouncy Castle, go to https://bouncycastle.org/latest_releases.html, then download the provider file that corresponds to your JDK. Or, you can pick it up from Maven:
The AWS Encryption SDK for Java uses Bouncy Castle for serializing and deserializing cryptographic objects.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The AWS Encryption SDK for Java uses Bouncy Castle for serializing and deserializing cryptographic objects.
The AWS Encryption SDK for Java uses Bouncy Castle to serialize and deserialize cryptographic objects.

It does not explicitly use Bouncy Castle (or any other [JCA Provider](https://docs.oracle.com/javase/8/docs/api/java/security/Provider.html)) for the underlying cryptography.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"explicitly use?" Do we use anything implicitly? Or: It does not require Bouncy Castle (or ...).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We do not specify the provider and thus receive the highest priority implementation from the JCA. We could explicitly request a provider (or explicitly use provider specific classes), in which case only that explicit provider could/would be used.

We don't know (or care) which provider we are using any more. It might be Bouncy Castle (if our callers have configured that to be the default), it might by the SUN provider (from Java), it might be ACCP.

Instead, it uses the platform default, which may be configured or overridden as documented in the
[Java Cryptography Architecture (JCA) Reference Guide](https://docs.oracle.com/javase/9/security/java-cryptography-architecture-jca-reference-guide.htm#JSSEC-GUID-2BCFDD85-D533-4E6C-8CE9-29990DEB0190).

```xml
<dependency>
<groupId>org.bouncycastle</groupId>
<artifactId>bcprov-ext-jdk15on</artifactId>
<version>1.61</version>
</dependency>
```
If you do not have Bouncy Castle, go to https://bouncycastle.org/latest_releases.html, then download the provider file that corresponds to your JDK.
Or, you can pick it up from Maven (groupId: `org.bouncycastle`, artifactId: `bcprov-ext-jdk15on`).

Beginning in version 1.6.1,
the AWS Encryption SDK also works with Bouncy Castle FIPS (groupId: `org.bouncycastle`, artifactId: `bc-fips`)
as an alternative to non-FIPS Bouncy Castle.
For help installing and configuring Bouncy Castle FIPS, see [BC FIPS documentation](https://www.bouncycastle.org/documentation.html),
including User Guides and Security Policy for proper installation and configuration.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
including User Guides and Security Policy for proper installation and configuration.
For help installing and configuring Bouncy Castle FIPS, see Bouncy Castle's [BC FIPS Documentation](https://www.bouncycastle.org/documentation.html),
including the User Guides and Security Policy.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I moved the end of the sentence to the beginning, so we can remove the end ("for proper installation and configuration"). Otherwise, it's redundant. If you want the "proper" in there, put it in the opening clause.


### Optional Prerequisites

#### AWS Integration
You don't need an Amazon Web Services (AWS) account to use this SDK, but some of the [example code][examples] requires an AWS account, a customer master key (CMK) in AWS KMS, and the AWS SDK for Java.

* **To create an AWS account**, go to [Sign In or Create an AWS Account](https://portal.aws.amazon.com/gp/aws/developer/registration/index.html) and then choose **I am a new user.** Follow the instructions to create an AWS account.
Expand All @@ -37,6 +42,10 @@ You don't need an Amazon Web Services (AWS) account to use this SDK, but some of

* **To download and install the AWS SDK for Java**, go to [Installing the AWS SDK for Java](https://docs.aws.amazon.com/AWSSdkDocsJava/latest/DeveloperGuide/java-dg-install-sdk.html) in the AWS SDK for Java documentation and then follow the instructions on that page.

#### Amazon Corretto Crypto Provider
Many users find that the Amazon Corretto Crypto Provider (ACCP) significantly improves the performance of the AWS Encryption SDK.
For help with installation and using ACCP, see the [ACCP GitHub Respository](https://github.com/corretto/amazon-corretto-crypto-provider) .
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
For help with installation and using ACCP, see the [ACCP GitHub Respository](https://github.com/corretto/amazon-corretto-crypto-provider) .
For help installing and using ACCP, see the [ACCP GitHub Respository](https://github.com/corretto/amazon-corretto-crypto-provider) .


### Download

You can get the latest release from Maven:
Expand All @@ -49,25 +58,6 @@ You can get the latest release from Maven:
</dependency>
```

Don't forget to enable the download of snapshot jars from Maven:

```xml
<profiles>
<profile>
<id>allow-snapshots</id>
<activation><activeByDefault>true</activeByDefault></activation>
<repositories>
<repository>
<id>snapshots-repo</id>
<url>https://oss.sonatype.org/content/repositories/snapshots</url>
<releases><enabled>false</enabled></releases>
<snapshots><enabled>true</enabled></snapshots>
</repository>
</repositories>
</profile>
</profiles>
```

### Get Started

The following code sample demonstrates how to get started:
Expand Down