Create features/integrations
This commit is contained in:
Rob Winch
parent
ab63ebbbee
commit
ca2bc958df
|
|
@ -10,6 +10,12 @@
|
|||
*** xref:features/exploits/csrf.adoc[CSRF]
|
||||
*** xref:features/exploits/headers.adoc[HTTP Headers]
|
||||
*** xref:features/exploits/http.adoc[HTTP Requests]
|
||||
** xref:features/integrations/index.adoc[Integrations]
|
||||
*** xref:features/integrations/cryptography.adoc[Cryptography]
|
||||
*** xref:features/integrations/data.adoc[Spring Data]
|
||||
*** xref:features/integrations/concurrency.adoc[Java's Concurrency APIs]
|
||||
*** xref:features/integrations/jackson.adoc[Jackson]
|
||||
*** xref:features/integrations/localization.adoc[Localization]
|
||||
* xref:modules.adoc[Project Modules]
|
||||
* xref:samples.adoc[Samples]
|
||||
* xref:servlet/index.adoc[Servlet Applications]
|
||||
|
|
@ -60,10 +66,6 @@
|
|||
*** xref:servlet/exploits/firewall.adoc[]
|
||||
** xref:servlet/integrations/index.adoc[Integrations]
|
||||
*** xref:servlet/integrations/servlet-api.adoc[Servlet APIs]
|
||||
*** xref:servlet/integrations/data.adoc[Spring Data]
|
||||
*** xref:servlet/integrations/concurrency.adoc[Java's Concurrency APIs]
|
||||
*** xref:servlet/integrations/jackson.adoc[Jackson]
|
||||
*** xref:servlet/integrations/localization.adoc[Localization]
|
||||
*** xref:servlet/integrations/mvc.adoc[Spring MVC]
|
||||
*** xref:servlet/integrations/websocket.adoc[WebSocket]
|
||||
*** xref:servlet/integrations/cors.adoc[Spring's CORS Support]
|
||||
|
|
@ -75,7 +77,6 @@
|
|||
** xref:servlet/test/index.adoc[Testing]
|
||||
*** xref:servlet/test/method.adoc[Method Security]
|
||||
*** xref:servlet/test/mockmvc.adoc[MockMvc Support]
|
||||
** xref:servlet/cryptography.adoc[Cryptography]
|
||||
** xref:servlet/appendix/index.adoc[Appendix]
|
||||
*** xref:servlet/appendix/database-schema.adoc[Database Schemas]
|
||||
*** xref:servlet/appendix/namespace.adoc[XML Namespace]
|
||||
|
|
|
|||
|
|
@ -0,0 +1,13 @@
|
|||
[[integrations]]
|
||||
= Integrations
|
||||
|
||||
Spring Security provides integrations with numerous frameworks and APIs.
|
||||
In this section, we discuss generic integrations that are not specific to Servlet or Reactive environments.
|
||||
To see specific integrations, refer to the xref:servlet/integrations/index.adoc[Servlet] and xref:servlet/integrations/index.adoc[Reactive] Integrations sections.
|
||||
// FIXME add link to reactive integrations
|
||||
|
||||
* xref:features/integrations/cryptography.adoc[Cryptography]
|
||||
* xref:features/integrations/data.adoc[Spring Data]
|
||||
* xref:features/integrations/concurrency.adoc[Java's Concurrency APIs]
|
||||
* xref:features/integrations/jackson.adoc[Jackson]
|
||||
* xref:features/integrations/localization.adoc[Localization]
|
||||
|
|
@ -1,264 +0,0 @@
|
|||
[[crypto]]
|
||||
= Spring Security Crypto Module
|
||||
|
||||
|
||||
[[spring-security-crypto-introduction]]
|
||||
== Introduction
|
||||
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.
|
||||
|
||||
|
||||
[[spring-security-crypto-encryption]]
|
||||
== 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.
|
||||
|
||||
[[spring-security-crypto-encryption-bytes]]
|
||||
=== BytesEncryptor
|
||||
Use the `Encryptors.stronger` factory method to construct a BytesEncryptor:
|
||||
|
||||
.BytesEncryptor
|
||||
====
|
||||
.Java
|
||||
[source,java,role="primary"]
|
||||
----
|
||||
Encryptors.stronger("password", "salt");
|
||||
----
|
||||
|
||||
.Kotlin
|
||||
[source,kotlin,role="secondary"]
|
||||
----
|
||||
Encryptors.stronger("password", "salt")
|
||||
----
|
||||
====
|
||||
|
||||
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.
|
||||
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:
|
||||
|
||||
.Generating a key
|
||||
====
|
||||
.Java
|
||||
[source,java,role="primary"]
|
||||
----
|
||||
String salt = KeyGenerators.string().generateKey(); // generates a random 8-byte salt that is then hex-encoded
|
||||
----
|
||||
|
||||
.Kotlin
|
||||
[source,kotlin,role="secondary"]
|
||||
----
|
||||
val 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:
|
||||
|
||||
.TextEncryptor
|
||||
====
|
||||
.Java
|
||||
[source,java,role="primary"]
|
||||
----
|
||||
Encryptors.text("password", "salt");
|
||||
----
|
||||
|
||||
.Kotlin
|
||||
[source,kotlin,role="secondary"]
|
||||
----
|
||||
Encryptors.text("password", "salt")
|
||||
----
|
||||
====
|
||||
|
||||
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:
|
||||
|
||||
.Queryable TextEncryptor
|
||||
====
|
||||
.Java
|
||||
[source,java,role="primary"]
|
||||
----
|
||||
Encryptors.queryableText("password", "salt");
|
||||
----
|
||||
|
||||
.Kotlin
|
||||
[source,kotlin,role="secondary"]
|
||||
----
|
||||
Encryptors.queryableText("password", "salt")
|
||||
----
|
||||
====
|
||||
|
||||
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.
|
||||
|
||||
[[spring-security-crypto-keygenerators]]
|
||||
== 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
|
||||
====
|
||||
.Java
|
||||
[source,java,role="primary"]
|
||||
----
|
||||
BytesKeyGenerator generator = KeyGenerators.secureRandom();
|
||||
byte[] key = generator.generateKey();
|
||||
----
|
||||
|
||||
.Kotlin
|
||||
[source,kotlin,role="secondary"]
|
||||
----
|
||||
val generator = KeyGenerators.secureRandom()
|
||||
val key = generator.generateKey()
|
||||
----
|
||||
====
|
||||
|
||||
The default key length is 8 bytes.
|
||||
There is also a KeyGenerators.secureRandom variant that provides control over the key length:
|
||||
|
||||
.KeyGenerators.secureRandom
|
||||
====
|
||||
.Java
|
||||
[source,java,role="primary"]
|
||||
----
|
||||
KeyGenerators.secureRandom(16);
|
||||
----
|
||||
|
||||
.Kotlin
|
||||
[source,kotlin,role="secondary"]
|
||||
----
|
||||
KeyGenerators.secureRandom(16)
|
||||
----
|
||||
====
|
||||
|
||||
Use the KeyGenerators.shared factory method to construct a BytesKeyGenerator that always returns the same key on every invocation:
|
||||
|
||||
.KeyGenerators.shared
|
||||
====
|
||||
.Java
|
||||
[source,java,role="primary"]
|
||||
----
|
||||
KeyGenerators.shared(16);
|
||||
----
|
||||
|
||||
.Kotlin
|
||||
[source,kotlin,role="secondary"]
|
||||
----
|
||||
KeyGenerators.shared(16)
|
||||
----
|
||||
====
|
||||
|
||||
=== StringKeyGenerator
|
||||
Use the KeyGenerators.string factory method to construct a 8-byte, SecureRandom KeyGenerator that hex-encodes each key as a String:
|
||||
|
||||
.StringKeyGenerator
|
||||
====
|
||||
.Java
|
||||
[source,java,role="primary"]
|
||||
----
|
||||
KeyGenerators.string();
|
||||
----
|
||||
|
||||
.Kotlin
|
||||
[source,kotlin,role="secondary"]
|
||||
----
|
||||
KeyGenerators.string()
|
||||
----
|
||||
====
|
||||
|
||||
[[spring-security-crypto-passwordencoders]]
|
||||
== 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:
|
||||
|
||||
[source,java]
|
||||
----
|
||||
public interface PasswordEncoder {
|
||||
|
||||
String encode(String rawPassword);
|
||||
|
||||
boolean matches(String rawPassword, String encodedPassword);
|
||||
}
|
||||
----
|
||||
|
||||
The matches method returns true if the rawPassword, once encoded, equals the encodedPassword.
|
||||
This method is designed to support password-based authentication schemes.
|
||||
|
||||
The `BCryptPasswordEncoder` implementation uses the widely supported "bcrypt" algorithm to hash the passwords.
|
||||
Bcrypt uses a random 16 byte salt value and is a deliberately slow algorithm, in order to hinder password crackers.
|
||||
The amount of work it does can be tuned using the "strength" parameter which takes values from 4 to 31.
|
||||
The higher the value, the more work has to be done to calculate the hash.
|
||||
The default value is 10.
|
||||
You can change this value in your deployed system without affecting existing passwords, as the value is also stored in the encoded hash.
|
||||
|
||||
.BCryptPasswordEncoder
|
||||
====
|
||||
.Java
|
||||
[source,java,role="primary"]
|
||||
----
|
||||
|
||||
// Create an encoder with strength 16
|
||||
BCryptPasswordEncoder encoder = new BCryptPasswordEncoder(16);
|
||||
String result = encoder.encode("myPassword");
|
||||
assertTrue(encoder.matches("myPassword", result));
|
||||
----
|
||||
|
||||
.Kotlin
|
||||
[source,kotlin,role="secondary"]
|
||||
----
|
||||
|
||||
// Create an encoder with strength 16
|
||||
val encoder = BCryptPasswordEncoder(16)
|
||||
val result: String = encoder.encode("myPassword")
|
||||
assertTrue(encoder.matches("myPassword", result))
|
||||
----
|
||||
====
|
||||
|
||||
The `Pbkdf2PasswordEncoder` implementation uses PBKDF2 algorithm to hash the passwords.
|
||||
In order to defeat password cracking PBKDF2 is a deliberately slow algorithm and should be tuned to take about .5 seconds to verify a password on your system.
|
||||
|
||||
|
||||
.Pbkdf2PasswordEncoder
|
||||
====
|
||||
.Java
|
||||
[source,java,role="primary"]
|
||||
----
|
||||
// Create an encoder with all the defaults
|
||||
Pbkdf2PasswordEncoder encoder = new Pbkdf2PasswordEncoder();
|
||||
String result = encoder.encode("myPassword");
|
||||
assertTrue(encoder.matches("myPassword", result));
|
||||
----
|
||||
|
||||
.Kotlin
|
||||
[source,kotlin,role="secondary"]
|
||||
----
|
||||
// Create an encoder with all the defaults
|
||||
val encoder = Pbkdf2PasswordEncoder()
|
||||
val result: String = encoder.encode("myPassword")
|
||||
assertTrue(encoder.matches("myPassword", result))
|
||||
----
|
||||
====
|
||||
|
|
@ -4,10 +4,6 @@ Spring Security integrates with numerous frameworks and APIs.
|
|||
In this section, we discuss Spring Security integration with:
|
||||
|
||||
* xref:servlet/integrations/servlet-api.adoc[Servlet APIs]
|
||||
* xref:servlet/integrations/data.adoc[Spring Data]
|
||||
* xref:servlet/integrations/concurrency.adoc[Java's Concurrency APIs]
|
||||
* xref:servlet/integrations/jackson.adoc[Jackson]
|
||||
* xref:servlet/integrations/localization.adoc[Localization]
|
||||
* xref:servlet/integrations/mvc.adoc[Spring MVC]
|
||||
* xref:servlet/integrations/websocket.adoc[WebSocket]
|
||||
* xref:servlet/integrations/cors.adoc[Spring's CORS Support]
|
||||
|
|
|
|||
|
|
@ -492,7 +492,7 @@ The `SecurityContext` that is used to process the `Callable` is the `SecurityCon
|
|||
|
||||
There is no automatic integration with a `DeferredResult` that is returned by controllers.
|
||||
This is because `DeferredResult` is processed by the users and thus there is no way of automatically integrating with it.
|
||||
However, you can still use xref:servlet/integrations/concurrency.adoc#concurrency[Concurrency Support] to provide transparent integration with Spring Security.
|
||||
However, you can still use xref:features/integrations/concurrency.adoc#concurrency[Concurrency Support] to provide transparent integration with Spring Security.
|
||||
|
||||
[[mvc-csrf]]
|
||||
== Spring MVC and CSRF Integration
|
||||
|
|
|
|||
Loading…
Reference in New Issue