diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index b6819592eb..381e6d8044 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -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] diff --git a/docs/modules/ROOT/pages/servlet/integrations/concurrency.adoc b/docs/modules/ROOT/pages/features/integrations/concurrency.adoc similarity index 100% rename from docs/modules/ROOT/pages/servlet/integrations/concurrency.adoc rename to docs/modules/ROOT/pages/features/integrations/concurrency.adoc diff --git a/docs/modules/ROOT/pages/servlet/cryptography.adoc b/docs/modules/ROOT/pages/features/integrations/cryptography.adoc similarity index 100% rename from docs/modules/ROOT/pages/servlet/cryptography.adoc rename to docs/modules/ROOT/pages/features/integrations/cryptography.adoc diff --git a/docs/modules/ROOT/pages/servlet/integrations/data.adoc b/docs/modules/ROOT/pages/features/integrations/data.adoc similarity index 100% rename from docs/modules/ROOT/pages/servlet/integrations/data.adoc rename to docs/modules/ROOT/pages/features/integrations/data.adoc diff --git a/docs/modules/ROOT/pages/features/integrations/index.adoc b/docs/modules/ROOT/pages/features/integrations/index.adoc new file mode 100644 index 0000000000..96f151b5fc --- /dev/null +++ b/docs/modules/ROOT/pages/features/integrations/index.adoc @@ -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] diff --git a/docs/modules/ROOT/pages/servlet/integrations/jackson.adoc b/docs/modules/ROOT/pages/features/integrations/jackson.adoc similarity index 100% rename from docs/modules/ROOT/pages/servlet/integrations/jackson.adoc rename to docs/modules/ROOT/pages/features/integrations/jackson.adoc diff --git a/docs/modules/ROOT/pages/servlet/integrations/localization.adoc b/docs/modules/ROOT/pages/features/integrations/localization.adoc similarity index 100% rename from docs/modules/ROOT/pages/servlet/integrations/localization.adoc rename to docs/modules/ROOT/pages/features/integrations/localization.adoc diff --git a/docs/modules/ROOT/pages/servlet/crypto/index.adoc b/docs/modules/ROOT/pages/servlet/crypto/index.adoc deleted file mode 100644 index 137b3e8b69..0000000000 --- a/docs/modules/ROOT/pages/servlet/crypto/index.adoc +++ /dev/null @@ -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)) ----- -==== diff --git a/docs/modules/ROOT/pages/servlet/integrations/index.adoc b/docs/modules/ROOT/pages/servlet/integrations/index.adoc index 5bfff0a49c..0e549ff221 100644 --- a/docs/modules/ROOT/pages/servlet/integrations/index.adoc +++ b/docs/modules/ROOT/pages/servlet/integrations/index.adoc @@ -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] diff --git a/docs/modules/ROOT/pages/servlet/integrations/mvc.adoc b/docs/modules/ROOT/pages/servlet/integrations/mvc.adoc index b473543bf2..5198ffc905 100644 --- a/docs/modules/ROOT/pages/servlet/integrations/mvc.adoc +++ b/docs/modules/ROOT/pages/servlet/integrations/mvc.adoc @@ -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