|
|
@@ -0,0 +1,150 @@
|
|
|
+<?xml version="1.0" encoding="UTF-8"?>
|
|
|
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="crypto" xmlns:xlink="http://www.w3.org/1999/xlink">
|
|
|
+ <title>Spring Security Crypto Module</title>
|
|
|
+
|
|
|
+ <section id="spring-security-crypto-introduction">
|
|
|
+ <title>Introduction</title>
|
|
|
+ <para>
|
|
|
+ The Spring Security Crypto module provides support for symmetric encryption, key generation, and password encoding.
|
|
|
+ </para>
|
|
|
+ </section>
|
|
|
+
|
|
|
+ <section id="spring-security-crypto-howtoget">
|
|
|
+ <title>How to get</title>
|
|
|
+ <para>
|
|
|
+ Add the spring-security-crypto artifact to your classpath:
|
|
|
+ <programlisting language="xml"><![CDATA[
|
|
|
+<dependency>
|
|
|
+ <groupId>org.springframework.security</groupId>
|
|
|
+ <artifactId>spring-security-crypto</artifactId>
|
|
|
+ <version>${org.springframework.security-version}</version>
|
|
|
+</dependency>]]>
|
|
|
+ </programlisting>
|
|
|
+ </para>
|
|
|
+ </section>
|
|
|
+
|
|
|
+ <section id="spring-security-crypto-encryption">
|
|
|
+ <title>Encryptors</title>
|
|
|
+ <para>
|
|
|
+ The Encryptors class provides factory methods for constructing symmetric encryptors.
|
|
|
+ Using this class, you can create ByteEncryptors to encrypt data in raw byte[] form.
|
|
|
+ You can also construct TextEncryptors to encrypt text strings.
|
|
|
+ Encryptors are thread safe.
|
|
|
+ </para>
|
|
|
+ <section id="spring-security-crypto-encryption-bytes">
|
|
|
+ <title>BytesEncryptor</title>
|
|
|
+ <para>
|
|
|
+ Use the Encryptors.standard factory method to construct a "standard" BytesEncryptor:
|
|
|
+ <programlisting language="java"><![CDATA[
|
|
|
+Encryptors.standard("password", "salt");]]>
|
|
|
+ </programlisting>
|
|
|
+ The "standard" encryption method is 256-bit AES 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.
|
|
|
+ A 16-byte random initialization vector is also applied so each encrypted message is unique.
|
|
|
+ </para>
|
|
|
+ <para>
|
|
|
+ The provided salt should be in hex-encoded String form, be random, and be at least 8 bytes in length.
|
|
|
+ Such a salt may be generated using a KeyGenerator:
|
|
|
+ <programlisting language="java"><![CDATA[
|
|
|
+String salt = KeyGenerators.string().generateKey(); // generates a random 8-byte salt that is then hex-encoded]]>
|
|
|
+ </programlisting>
|
|
|
+ </para>
|
|
|
+ </section>
|
|
|
+ <section id="spring-security-crypto-encryption-text">
|
|
|
+ <title>TextEncryptor</title>
|
|
|
+ <para>
|
|
|
+ Use the Encryptors.text factory method to construct a standard TextEncryptor:
|
|
|
+ <programlisting language="java"><![CDATA[
|
|
|
+Encryptors.text("password", "salt");]]>
|
|
|
+ </programlisting>
|
|
|
+ A TextEncryptor uses a standard BytesEncryptor to encrypt text data.
|
|
|
+ Encrypted results are returned as hex-encoded strings for easy storage on the filesystem or in the database.
|
|
|
+ </para>
|
|
|
+ <para>
|
|
|
+ Use the Encryptors.queryableText factory method to construct a "queryable" TextEncryptor:
|
|
|
+ <programlisting language="java"><![CDATA[
|
|
|
+Encryptors.queryableText("password", "salt");]]>
|
|
|
+ </programlisting>
|
|
|
+ The difference between a queryable TextEncryptor and a standard TextEncryptor has to do with initialization vector (iv) handling.
|
|
|
+ The iv used in a queryable TextEncryptor#encrypt operation is shared, or constant, and is not randomly generated.
|
|
|
+ This means the same text encrypted multiple times will always produce the same encryption result.
|
|
|
+ This is less secure, but necessary for encrypted data that needs to be queried against.
|
|
|
+ An example of queryable encrypted text would be an OAuth apiKey.
|
|
|
+ </para>
|
|
|
+ </section>
|
|
|
+ </section>
|
|
|
+
|
|
|
+ <section id="spring-security-crypto-keygenerators">
|
|
|
+ <title>Key Generators</title>
|
|
|
+ <para>
|
|
|
+ The KeyGenerators class provides a number of convenience factory methods for constructing different types of key generators.
|
|
|
+ Using this class, you can create a BytesKeyGenerator to generate byte[] keys.
|
|
|
+ You can also construct a StringKeyGenerator to generate string keys.
|
|
|
+ KeyGenerators are thread safe.
|
|
|
+ </para>
|
|
|
+ <section>
|
|
|
+ <title>BytesKeyGenerator</title>
|
|
|
+ <para>
|
|
|
+ Use the KeyGenerators.secureRandom factory methods to generate a BytesKeyGenerator backed by a SecureRandom instance:
|
|
|
+ <programlisting language="java"><![CDATA[
|
|
|
+KeyGenerator generator = KeyGenerators.secureRandom();
|
|
|
+byte[] key = generator.generateKey();]]>
|
|
|
+ </programlisting>
|
|
|
+ </para>
|
|
|
+ <para>
|
|
|
+ The default key length is 8 bytes.
|
|
|
+ There is also a KeyGenerators.secureRandom variant that provides control over the key length:
|
|
|
+ <programlisting language="java"><![CDATA[
|
|
|
+KeyGenerators.secureRandom(16);]]>
|
|
|
+ </programlisting>
|
|
|
+ </para>
|
|
|
+ <para>
|
|
|
+ Use the KeyGenerators.shared factory method to construct a BytesKeyGenerator that always returns the same key on every invocation:
|
|
|
+ <programlisting language="java"><![CDATA[
|
|
|
+KeyGenerators.shared(16);]]>
|
|
|
+ </programlisting>
|
|
|
+ </para>
|
|
|
+ </section>
|
|
|
+ <section>
|
|
|
+ <title>StringKeyGenerator</title>
|
|
|
+ <para>
|
|
|
+ Use the KeyGenerators.string factory method to construct a 8-byte, SecureRandom KeyGenerator that hex-encodes each key as a String:
|
|
|
+ <programlisting language="java"><![CDATA[
|
|
|
+KeyGenerators.string();]]>
|
|
|
+ </programlisting>
|
|
|
+ </para>
|
|
|
+ </section>
|
|
|
+ </section>
|
|
|
+
|
|
|
+ <section id="spring-security-crypto-passwordencoders">
|
|
|
+ <title>Password Encoding</title>
|
|
|
+ <para>
|
|
|
+ The password package of the spring-security-crypto module provides support for encoding passwords.
|
|
|
+ PasswordEncoder is the central service interface and has the following signature:
|
|
|
+ <programlisting language="java"><![CDATA[
|
|
|
+public interface PasswordEncoder {
|
|
|
+ String encode(String rawPassword);
|
|
|
+ boolean matches(String rawPassword, String encodedPassword);
|
|
|
+}]]>
|
|
|
+ </programlisting>
|
|
|
+ The matches method returns true if the rawPassword, once encoded, equals the encodedPassword.
|
|
|
+ This method is designed to support password-based authentication schemes.
|
|
|
+ </para>
|
|
|
+ <para>
|
|
|
+ The StandardPasswordEncoder implementation applies 1024 iterations of the SHA-256 hashing algorithm to the rawPassword combined with a site-wide secret and 8-byte random salt:
|
|
|
+ </para>
|
|
|
+ <programlisting language="java"><![CDATA[
|
|
|
+StandardPasswordEncoder encoder = new StandardPasswordEncoder("secret");
|
|
|
+String result = encoder.encode("myPassword");
|
|
|
+assertTrue(encoder.matches("myPassword", result));]]>
|
|
|
+ </programlisting>
|
|
|
+ <para>
|
|
|
+ The random salt ensures each hash is unique when the same password is used multiple times.
|
|
|
+ The site-wide secret should be stored in a safe place separate from where passwords are stored, and is used to protect against a bruce force attack in the event the database of passwords is compromised.
|
|
|
+ 1024 iterations of the hashing algorithm strengthens the key and makes it more difficult to compromise using a brute force attack.
|
|
|
+ </para>
|
|
|
+ </section>
|
|
|
+
|
|
|
+</chapter>
|
Keith Donald