Cwikius-Spring/spring-security
1
0
Fork 0
mirror of https://github.com/spring-projects/spring-security.git synced 2025-06-27 14:22:47 +00:00
Code Issues Packages Projects Releases Wiki Activity

SEC-1689: Adjust manual to remove references to separate crypto module.

Browse Source
This commit is contained in:
Luke Taylor 2011-03-08 12:58:28 +00:00
parent a50c9afbab
commit 57c3afd31a
3 changed files with 100 additions and 127 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
docs/manual/src/docbook/appendix-dependencies.xml
View File

@ -412,12 +412,4 @@
</table> </table>
</para> </para>
</section> </section>
<section>
<title><literal>spring-security-crypto</literal></title>
<para>Provides convenient cryptographic APIs which are used by projects such as OAuth.
This module currently has no external dependencies.
</para>
</section>
</appendix> </appendix>

209
docs/manual/src/docbook/crypto.xml
View File

@ -2,149 +2,136 @@
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="crypto" xmlns:xlink="http://www.w3.org/1999/xlink"> <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> <title>Spring Security Crypto Module</title>
<section id="spring-security-crypto-introduction"> <section xml:id="spring-security-crypto-introduction">
<title>Introduction</title> <title>Introduction</title>
<para> <para>
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.
</para> </para>
</section> </section>
<section id="spring-security-crypto-howtoget"> <section xml:id="spring-security-crypto-encryption">
<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> <title>Encryptors</title>
<para> <para>
The Encryptors class provides factory methods for constructing symmetric 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. Using this class, you can create ByteEncryptors to encrypt data in raw byte[] form.
You can also construct TextEncryptors to encrypt text strings. You can also construct TextEncryptors to encrypt text strings.
Encryptors are thread safe. Encryptors are thread safe.
</para> </para>
<section id="spring-security-crypto-encryption-bytes"> <section xml:id="spring-security-crypto-encryption-bytes">
<title>BytesEncryptor</title> <title>BytesEncryptor</title>
<para> <para>
Use the Encryptors.standard factory method to construct a "standard" BytesEncryptor: Use the Encryptors.standard factory method to construct a "standard" BytesEncryptor:
<programlisting language="java"><![CDATA[ <programlisting language="java"><![CDATA[
Encryptors.standard("password", "salt");]]> Encryptors.standard("password", "salt");]]>
</programlisting> </programlisting>
The "standard" encryption method is 256-bit AES using PKCS #5's PBKDF2 (Password-Based Key Derivation Function #2). The "standard" encryption method is 256-bit AES using PKCS #5's PBKDF2 (Password-Based Key Derivation Function #2).
This method requires Java 6. This method requires Java 6.
The password used to generate the SecretKey should be kept in a secure place and not be shared. 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. 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. A 16-byte random initialization vector is also applied so each encrypted message is unique.
</para> </para>
<para> <para>
The provided salt should be in hex-encoded String form, be random, and be at least 8 bytes in length. 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: Such a salt may be generated using a KeyGenerator:
<programlisting language="java"><![CDATA[ <programlisting language="java"><![CDATA[
String salt = KeyGenerators.string().generateKey(); // generates a random 8-byte salt that is then hex-encoded]]> String salt = KeyGenerators.string().generateKey(); // generates a random 8-byte salt that is then hex-encoded]]>
</programlisting> </programlisting>
</para> </para>
</section> </section>
<section id="spring-security-crypto-encryption-text"> <section xml:id="spring-security-crypto-encryption-text">
<title>TextEncryptor</title> <title>TextEncryptor</title>
<para> <para>
Use the Encryptors.text factory method to construct a standard TextEncryptor: Use the Encryptors.text factory method to construct a standard TextEncryptor:
<programlisting language="java"><![CDATA[ <programlisting language="java"><![CDATA[
Encryptors.text("password", "salt");]]> Encryptors.text("password", "salt");]]>
</programlisting> </programlisting>
A TextEncryptor uses a standard BytesEncryptor to encrypt text data. 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. Encrypted results are returned as hex-encoded strings for easy storage on the filesystem or in the database.
</para> </para>
<para> <para>
Use the Encryptors.queryableText factory method to construct a "queryable" TextEncryptor: Use the Encryptors.queryableText factory method to construct a "queryable" TextEncryptor:
<programlisting language="java"><![CDATA[ <programlisting language="java"><![CDATA[
Encryptors.queryableText("password", "salt");]]> Encryptors.queryableText("password", "salt");]]>
</programlisting> </programlisting>
The difference between a queryable TextEncryptor and a standard TextEncryptor has to do with initialization vector (iv) handling. 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. 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 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. 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. An example of queryable encrypted text would be an OAuth apiKey.
</para> </para>
</section> </section>
</section> </section>
<section id="spring-security-crypto-keygenerators"> <section xml:id="spring-security-crypto-keygenerators">
<title>Key Generators</title> <title>Key Generators</title>
<para> <para>
The KeyGenerators class provides a number of convenience factory methods for constructing different types of 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. Using this class, you can create a BytesKeyGenerator to generate byte[] keys.
You can also construct a StringKeyGenerator to generate string keys. You can also construct a StringKeyGenerator to generate string keys.
KeyGenerators are thread safe. KeyGenerators are thread safe.
</para> </para>
<section> <section>
<title>BytesKeyGenerator</title> <title>BytesKeyGenerator</title>
<para> <para>
Use the KeyGenerators.secureRandom factory methods to generate a BytesKeyGenerator backed by a SecureRandom instance: Use the KeyGenerators.secureRandom factory methods to generate a BytesKeyGenerator backed by a SecureRandom instance:
<programlisting language="java"><![CDATA[ <programlisting language="java"><![CDATA[
KeyGenerator generator = KeyGenerators.secureRandom(); KeyGenerator generator = KeyGenerators.secureRandom();
byte[] key = generator.generateKey();]]> byte[] key = generator.generateKey();]]>
</programlisting> </programlisting>
</para> </para>
<para> <para>
The default key length is 8 bytes. The default key length is 8 bytes.
There is also a KeyGenerators.secureRandom variant that provides control over the key length: There is also a KeyGenerators.secureRandom variant that provides control over the key length:
<programlisting language="java"><![CDATA[ <programlisting language="java"><![CDATA[
KeyGenerators.secureRandom(16);]]> KeyGenerators.secureRandom(16);]]>
</programlisting> </programlisting>
</para> </para>
<para> <para>
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:
<programlisting language="java"><![CDATA[ <programlisting language="java"><![CDATA[
KeyGenerators.shared(16);]]> KeyGenerators.shared(16);]]>
</programlisting> </programlisting>
</para> </para>
</section> </section>
<section> <section>
<title>StringKeyGenerator</title> <title>StringKeyGenerator</title>
<para> <para>
Use the KeyGenerators.string factory method to construct a 8-byte, SecureRandom KeyGenerator that hex-encodes each key as a String: 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[ <programlisting language="java"><![CDATA[
KeyGenerators.string();]]> KeyGenerators.string();]]>
</programlisting> </programlisting>
</para> </para>
</section> </section>
</section> </section>
<section id="spring-security-crypto-passwordencoders"> <section xml:id="spring-security-crypto-passwordencoders">
<title>Password Encoding</title> <title>Password Encoding</title>
<para> <para>
The password package of the spring-security-crypto module provides support for encoding passwords. 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: PasswordEncoder is the central service interface and has the following signature:
<programlisting language="java"><![CDATA[ <programlisting language="java"><![CDATA[
public interface PasswordEncoder { public interface PasswordEncoder {
String encode(String rawPassword); String encode(String rawPassword);
boolean matches(String rawPassword, String encodedPassword); boolean matches(String rawPassword, String encodedPassword);
}]]> }]]>
</programlisting> </programlisting>
The matches method returns true if the rawPassword, once encoded, equals the encodedPassword. The matches method returns true if the rawPassword, once encoded, equals the encodedPassword.
This method is designed to support password-based authentication schemes. This method is designed to support password-based authentication schemes.
</para> </para>
<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: 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> </para>
<programlisting language="java"><![CDATA[ <programlisting language="java"><![CDATA[
StandardPasswordEncoder encoder = new StandardPasswordEncoder("secret"); StandardPasswordEncoder encoder = new StandardPasswordEncoder("secret");
String result = encoder.encode("myPassword"); String result = encoder.encode("myPassword");
assertTrue(encoder.matches("myPassword", result));]]> assertTrue(encoder.matches("myPassword", result));]]>
</programlisting> </programlisting>
<para> <para>
The random salt ensures each hash is unique when the same password is used multiple times. 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. 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. 1024 iterations of the hashing algorithm strengthens the key and makes it more difficult to compromise using a brute force attack.
</para> </para>
</section> </section>
</chapter> </chapter>

6
docs/manual/src/docbook/introduction.xml
View File

@ -282,12 +282,6 @@
external OpenID server. <literal>org.springframework.security.openid</literal>. external OpenID server. <literal>org.springframework.security.openid</literal>.
Requires OpenID4Java.</para> Requires OpenID4Java.</para>
</section> </section>
<section xml:id="spring-security-crypto">
<title>Crypto - <literal>spring-security-crypto.jar</literal></title>
<para>Contains cryptography utility functions which are used by other
Spring projects. <literal>org.springframework.security.crypto</literal>.
</para>
</section>
</section> </section>
<section xml:id="get-source"> <section xml:id="get-source">
<title>Checking out the Source</title> <title>Checking out the Source</title>