diff --git a/docs/manual/src/docbook/crypto.xml b/docs/manual/src/docbook/crypto.xml new file mode 100644 index 0000000000..febb8bd174 --- /dev/null +++ b/docs/manual/src/docbook/crypto.xml @@ -0,0 +1,150 @@ + + + Spring Security Crypto Module + +
+ Introduction + + The Spring Security Crypto module provides support for symmetric encryption, key generation, and password encoding. + +
+ +
+ How to get + + Add the spring-security-crypto artifact to your classpath: + + org.springframework.security + spring-security-crypto + ${org.springframework.security-version} +]]> + + +
+ +
+ Encryptors + + 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. + +
+ BytesEncryptor + + Use the Encryptors.standard factory method to construct a "standard" BytesEncryptor: + + + 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. + + + 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: + + + +
+
+ TextEncryptor + + Use the Encryptors.text factory method to construct a standard TextEncryptor: + + + 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. + + + Use the Encryptors.queryableText factory method to construct a "queryable" TextEncryptor: + + + 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. + +
+
+ +
+ Key Generators + + 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. + +
+ BytesKeyGenerator + + Use the KeyGenerators.secureRandom factory methods to generate a BytesKeyGenerator backed by a SecureRandom instance: + + + + + The default key length is 8 bytes. + There is also a KeyGenerators.secureRandom variant that provides control over the key length: + + + + + Use the KeyGenerators.shared factory method to construct a BytesKeyGenerator that always returns the same key on every invocation: + + + +
+
+ StringKeyGenerator + + Use the KeyGenerators.string factory method to construct a 8-byte, SecureRandom KeyGenerator that hex-encodes each key as a String: + + + +
+
+ +
+ Password Encoding + + 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: + + + The matches method returns true if the rawPassword, once encoded, equals the encodedPassword. + This method is designed to support password-based authentication schemes. + + + 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: + + + + + 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. + +
+ + \ No newline at end of file diff --git a/docs/manual/src/docbook/springsecurity.xml b/docs/manual/src/docbook/springsecurity.xml index d6ef831d70..03346f3a5b 100644 --- a/docs/manual/src/docbook/springsecurity.xml +++ b/docs/manual/src/docbook/springsecurity.xml @@ -167,6 +167,7 @@ +