diff --git a/docs/manual/src/docbook/appendix-dependencies.xml b/docs/manual/src/docbook/appendix-dependencies.xml index bfe0181a67..988aaa3c21 100644 --- a/docs/manual/src/docbook/appendix-dependencies.xml +++ b/docs/manual/src/docbook/appendix-dependencies.xml @@ -412,12 +412,4 @@ - -
- <literal>spring-security-crypto</literal> - Provides convenient cryptographic APIs which are used by projects such as OAuth. - This module currently has no external dependencies. - -
- \ No newline at end of file diff --git a/docs/manual/src/docbook/crypto.xml b/docs/manual/src/docbook/crypto.xml index febb8bd174..7fff0ba915 100644 --- a/docs/manual/src/docbook/crypto.xml +++ b/docs/manual/src/docbook/crypto.xml @@ -2,149 +2,136 @@ Spring Security Crypto Module -
+
Introduction - The Spring Security Crypto module provides support for symmetric encryption, key generation, and password encoding. + The Spring Security Crypto module provides support for symmetric encryption, key generation, and password encoding. + The code is distributed as part of the core module but has no dependencies on any other Spring Security (or Spring) code.
-
- 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. + 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: - + 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: - + 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: - + +
+
+ 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: - + 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. - -
+ + 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: - +
+ 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: - + + + 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: - + + + 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: - + +
+
+ StringKeyGenerator + + Use the KeyGenerators.string factory method to construct a 8-byte, SecureRandom KeyGenerator that hex-encodes each key as a String: + - - -
+ + +
-
- Password Encoding +
+ 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 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. - + + + 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/introduction.xml b/docs/manual/src/docbook/introduction.xml index 4488ffd199..892373a352 100644 --- a/docs/manual/src/docbook/introduction.xml +++ b/docs/manual/src/docbook/introduction.xml @@ -282,12 +282,6 @@ external OpenID server. org.springframework.security.openid. Requires OpenID4Java.
-
- Crypto - <literal>spring-security-crypto.jar</literal> - Contains cryptography utility functions which are used by other - Spring projects. org.springframework.security.crypto. - -
Checking out the Source