Skip to content

Flag deprecated encryptString/decryptString APIs as deprecated. #120

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 8 commits into from
Oct 9, 2019
Merged

Flag deprecated encryptString/decryptString APIs as deprecated. #120

Changes from 2 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
656ae1e
Flag deprecated encryptString/decryptString APIs as deprecated.
lizroth Jul 30, 2019
c27754f
Improve Javadoc description of deprecation.
lizroth Jul 30, 2019
5e4b220
Clarify Javadoc for deprecation notice.
lizroth Aug 2, 2019
b60f8f1
Improve deprecation wording based on feedback.
lizroth Oct 8, 2019
7704385
Fix incorrect description.
lizroth Oct 9, 2019
b5ab0f2
Once more unto the hyphenation, dear friends.
lizroth Oct 9, 2019
2248c40
Re-remove StringExample.java.
lizroth Oct 9, 2019
22a90bf
Merge branch 'master' into update-deprecated-api-flags
lizroth Oct 9, 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
36 changes: 33 additions & 3 deletions src/main/java/com/amazonaws/encryptionsdk/AwsCrypto.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -281,7 +281,12 @@ public <K extends MasterKey<K>> CryptoResult<byte[], K> encryptData(final Master
/**
* Calls {@link #encryptData(MasterKeyProvider, byte[], Map)} on the UTF-8 encoded bytes of
* {@code plaintext} and base64 encodes the result.
* @deprecated Use the {@link #encryptData(MasterKeyProvider, byte[], Map)} and
* {@link #decryptData(MasterKeyProvider, byte[])} APIs instead. {@code encryptString} is incompatible with the
Copy link
Member

Choose a reason for hiding this comment

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

I would not say that they are incompatible without clarification. Maybe "because the the output must be base64-decoded to be compatible with other AWS Encryption SDK implementations"?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Works for me, I am but a deprecation-shaped vessel for the wordsmithing that you guys think make sense.

Copy link
Contributor

@juneb juneb Jul 31, 2019 •
edited
Loading

Choose a reason for hiding this comment

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

Because these APIs return Base64-encoded output, they are not compatible with other AWS Encryption SDK language implementations.

Copy link
Member

@mattsb42-aws mattsb42-aws Aug 1, 2019 •
edited
Loading

Choose a reason for hiding this comment

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

Because these APIs return Base64-encoded output, they are not compatible with other AWS Encryption SDK language implementations.

IMO this still conveys the wrong message.
What I would like to make sure we're communicating is that they are compatible, but only once you peal away an extra layer of encoding that this method adds.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

After some noodling, I've tried again to be clear and concise in explaining that this is deprecated, and why. When you have a second, please let me know what you think of the new wording.

* other AWS Encryption SDK language implementations. By design, this feature is not supported by the other
* language implementations.
*/
@Deprecated
public <K extends MasterKey<K>> CryptoResult<String, K> encryptString(
final MasterKeyProvider<K> provider,
final String plaintext,
Expand All @@ -295,7 +300,12 @@ public <K extends MasterKey<K>> CryptoResult<String, K> encryptString(
/**
* Calls {@link #encryptData(CryptoMaterialsManager, byte[], Map)} on the UTF-8 encoded bytes of
* {@code plaintext} and base64 encodes the result.
* @deprecated Use the {@link #encryptData(CryptoMaterialsManager, byte[], Map)} and
* {@link #decryptData(CryptoMaterialsManager, byte[])} APIs instead. {@code encryptString} is incompatible with the
* other AWS Encryption SDK language implementations. By design, this feature is not supported by the other
* language implementations.
*/
@Deprecated
public CryptoResult<String, ?> encryptString(
CryptoMaterialsManager materialsManager,
final String plaintext,
Expand All @@ -313,7 +323,12 @@ public <K extends MasterKey<K>> CryptoResult<String, K> encryptString(
/**
* Returns the equivalent to calling {@link #encryptString(MasterKeyProvider, String, Map)} with
* an empty {@code encryptionContext}.
* @deprecated Use the {@link #encryptData(MasterKeyProvider, byte[])} and
* {@link #decryptData(MasterKeyProvider, byte[])} APIs instead. {@code encryptString} is incompatible with the
* other AWS Encryption SDK language implementations. By design, this feature is not supported by the other
* language implementations.
*/
@Deprecated
public <K extends MasterKey<K>> CryptoResult<String, K> encryptString(final MasterKeyProvider<K> provider,
final String plaintext) {
return encryptString(provider, plaintext, EMPTY_MAP);
Expand All @@ -322,7 +337,12 @@ public <K extends MasterKey<K>> CryptoResult<String, K> encryptString(final Mast
/**
* Returns the equivalent to calling {@link #encryptString(CryptoMaterialsManager, String, Map)} with
* an empty {@code encryptionContext}.
* @deprecated Use the {@link #encryptData(CryptoMaterialsManager, byte[])} and
* {@link #decryptData(CryptoMaterialsManager, byte[])} APIs instead. {@code encryptString} is incompatible with the
* other AWS Encryption SDK language implementations. By design, this feature is not supported by the other
* language implementations.
*/
@Deprecated
public CryptoResult<String, ?> encryptString(
final CryptoMaterialsManager materialsManager,
final String plaintext
Expand All @@ -345,9 +365,9 @@ public <K extends MasterKey<K>> CryptoResult<byte[], K> decryptData(final Master
* Decrypts the provided ciphertext by delegating to the provided materialsManager to obtain the decrypted
* {@link DataKey}.
*
* @param materialsManager
* @param ciphertext
* @return
* @param materialsManager the {@link CryptoMaterialsManager} to use for decryption operations.
* @param ciphertext the ciphertext to attempt to decrypt.
* @return the {@link CryptoResult} with the decrypted data.
*/
public CryptoResult<byte[], ?> decryptData(
final CryptoMaterialsManager materialsManager,
Expand Down Expand Up @@ -402,7 +422,12 @@ public <K extends MasterKey<K>> CryptoResult<byte[], K> decryptData(
* UTF-8 encoded string.
*
* @see #decryptData(MasterKeyProvider, byte[])
* @deprecated Use the {@link #decryptData(MasterKeyProvider, byte[])} and
* {@link #encryptData(MasterKeyProvider, byte[], Map)} APIs instead. {@code decryptString} is incompatible with
* the other AWS Encryption SDK language implementations. By design, this feature is not supported by the other
* language implementations.
*/
@Deprecated
@SuppressWarnings("unchecked")
public <K extends MasterKey<K>> CryptoResult<String, K> decryptString(
final MasterKeyProvider<K> provider,
Expand All @@ -416,7 +441,12 @@ public <K extends MasterKey<K>> CryptoResult<String, K> decryptString(
* UTF-8 encoded string.
*
* @see #decryptData(CryptoMaterialsManager, byte[])
* @deprecated Use the {@link #decryptData(CryptoMaterialsManager, byte[])} and
* {@link #encryptData(CryptoMaterialsManager, byte[], Map)} APIs instead. {@code decryptString} is incompatible
* with the other AWS Encryption SDK language implementations. By design, this feature is not supported by the other
* language implementations.
*/
@Deprecated
public CryptoResult<String, ?> decryptString(final CryptoMaterialsManager provider,
final String ciphertext) {
Utils.assertNonNull(provider, "provider");
Expand Down