From 01f8eb3961ab16107448e39932f850c0f2ea71df Mon Sep 17 00:00:00 2001 From: Eleftheria Stein Date: Fri, 27 Mar 2020 09:47:53 -0400 Subject: [PATCH] Update Encryptors documentation Fixes gh-8208 --- .../security/crypto/encrypt/Encryptors.java | 11 ++++++++--- .../asciidoc/_includes/servlet/crypto/index.adoc | 13 ++++++++++--- 2 files changed, 18 insertions(+), 6 deletions(-) diff --git a/crypto/src/main/java/org/springframework/security/crypto/encrypt/Encryptors.java b/crypto/src/main/java/org/springframework/security/crypto/encrypt/Encryptors.java index 7e0c5e8295..aee376b702 100644 --- a/crypto/src/main/java/org/springframework/security/crypto/encrypt/Encryptors.java +++ b/crypto/src/main/java/org/springframework/security/crypto/encrypt/Encryptors.java @@ -39,9 +39,6 @@ public class Encryptors { * not be shared * @param salt a hex-encoded, random, site-global salt value to use to generate the * key - * - * @see #standard(CharSequence, CharSequence) which uses the slightly weaker CBC mode - * (instead of GCM) */ public static BytesEncryptor stronger(CharSequence password, CharSequence salt) { return new AesBytesEncryptor(password.toString(), salt, @@ -55,11 +52,19 @@ public class Encryptors { * provided salt is expected to be hex-encoded; it should be random and at least 8 * bytes in length. Also applies a random 16 byte initialization vector to ensure each * encrypted message will be unique. Requires Java 6. + * NOTE: This mode is not + * authenticated + * and does not provide any guarantees about the authenticity of the data. + * For a more secure alternative, users should prefer + * {@link #stronger(CharSequence, CharSequence)}. * * @param password the password used to generate the encryptor's secret key; should * not be shared * @param salt a hex-encoded, random, site-global salt value to use to generate the * key + * + * @see #stronger(CharSequence, CharSequence) which uses the significatly more secure + * GCM (instead of CBC) */ public static BytesEncryptor standard(CharSequence password, CharSequence salt) { return new AesBytesEncryptor(password.toString(), salt, diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/crypto/index.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/crypto/index.adoc index 753c46c4b1..0ccfd5c605 100644 --- a/docs/manual/src/docs/asciidoc/_includes/servlet/crypto/index.adoc +++ b/docs/manual/src/docs/asciidoc/_includes/servlet/crypto/index.adoc @@ -17,14 +17,16 @@ Encryptors are thread-safe. [[spring-security-crypto-encryption-bytes]] === BytesEncryptor -Use the Encryptors.standard factory method to construct a "standard" BytesEncryptor: +Use the `Encryptors.stronger` factory method to construct a BytesEncryptor: [source,java] ---- -Encryptors.standard("password", "salt"); +Encryptors.stronger("password", "salt"); ---- -The "standard" encryption method is 256-bit AES using PKCS #5's PBKDF2 (Password-Based Key Derivation Function #2). +The "stronger" encryption method creates an encryptor using 256 bit AES encryption with +Galois Counter Mode (GCM). +It derives the secret key using PKCS #5's PBKDF2 (Password-Based Key Derivation Function #2). This method requires Java 6. The password used to generate the SecretKey should be kept in a secure place and not be shared. The salt is used to prevent dictionary attacks against the key in the event your encrypted data is compromised. @@ -38,6 +40,11 @@ Such a salt may be generated using a KeyGenerator: String salt = KeyGenerators.string().generateKey(); // generates a random 8-byte salt that is then hex-encoded ---- +Users may also use the `standard` encryption method, which is 256-bit AES in Cipher Block Chaining (CBC) Mode. +This mode is not https://en.wikipedia.org/wiki/Authenticated_encryption[authenticated] and does not provide any +guarantees about the authenticity of the data. +For a more secure alternative, users should prefer `Encryptors.stronger`. + [[spring-security-crypto-encryption-text]] === TextEncryptor Use the Encryptors.text factory method to construct a standard TextEncryptor: