This is an automated email from the ASF dual-hosted git repository.
lprimak pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/shiro-site.git
The following commit(s) were added to refs/heads/main by this push:
new ea135cb9a docs(security): update Security Model documentation and add
rate limiting section fixes #243
ea135cb9a is described below
commit ea135cb9a372afb61811a0295acdf6accfcb003a
Author: lprimak <[email protected]>
AuthorDate: Tue Jan 13 16:10:18 2026 -0600
docs(security): update Security Model documentation and add rate limiting
section
fixes #243
---
src/site/content/jakarta-ee.adoc | 3 ++-
src/site/content/security-model.adoc | 22 +++++++---------------
src/site/templates/menu.ftl | 1 +
3 files changed, 10 insertions(+), 16 deletions(-)
diff --git a/src/site/content/jakarta-ee.adoc b/src/site/content/jakarta-ee.adoc
index 731bd736e..b785cb70f 100644
--- a/src/site/content/jakarta-ee.adoc
+++ b/src/site/content/jakarta-ee.adoc
@@ -148,7 +148,8 @@ RememberMe functionality is disabled by default. You can
enable it easily by add
authc.useRemembered = true
----
-==== Automatic delay when login failed
+[#rate_limiting]
+==== Rate limiting: Automatic delay when login failed
When user fails to log in, Shiro will automatically delay the failure response
for a number of seconds. This can be one of the strategies to prevent brute
force attacks.
NOTE: Be careful utilizing this technique, as it could be a vector for a
denial-of-service attack. Servers with virtual thread support (Project Loom)
will not be affected by the DDOS vector.
diff --git a/src/site/content/security-model.adoc
b/src/site/content/security-model.adoc
index c211a9ab2..0268029c7 100644
--- a/src/site/content/security-model.adoc
+++ b/src/site/content/security-model.adoc
@@ -1,5 +1,5 @@
= Apache Shiro Security Model
-:jbake-date: 2025-01-03 00:00:00
+:jbake-date: 2026-01-03 00:00:00
:jbake-type: page
:jbake-status: published
:jbake-tags: documentation, security
@@ -50,8 +50,10 @@ However, Shiro relies on the application to:
=== Operator Responsibilities
-* **Credential Storage**: Operators must ensure credentials are stored
securely (hashed with appropriate algorithms like bcrypt, Argon2, or PBKDF2).
-* **Brute-Force Protection**: Shiro does not include built-in rate limiting or
account lockout. Operators should implement these controls at the application
or infrastructure level.
+* **Credential Storage**: Operators must ensure credentials are stored
securely (hashed with appropriate algorithms like bcrypt or Argon2).
+* **Brute-Force Protection**: Shiro only includes built-in basic rate limiting
for
+link:jakarta-ee.html#rate_limiting[Jakarta EE only], but does not include
account lockout.
+Operators should implement these controls at the application or infrastructure
level.
* **Multi-Factor Authentication**: MFA is not built into core Shiro; operators
requiring MFA must implement custom `Realm` or `AuthenticationStrategy`
extensions.
=== Username Enumeration
@@ -101,7 +103,7 @@ By default, Shiro may reveal whether a username exists
through different error r
=== Important Notes
-* Shiro's cryptographic utilities are wrappers around standard Java
cryptography (JCA/JCE).
+* Shiro's cryptographic utilities are wrappers around standard Java
cryptography (JCA/JCE) and `BouncyCastle` libraries.
* **Algorithm Selection**: Operators must choose appropriate algorithms. Avoid
deprecated algorithms (MD5, SHA-1 for security purposes).
* **Key Management**: Shiro does not provide key management infrastructure.
Secure key storage and rotation is the operator's responsibility.
@@ -148,7 +150,7 @@ Operators should:
. Use the latest stable Shiro release.
. Configure TLS for all credential transmission.
-. Use strong password hashing (bcrypt, Argon2, or PBKDF2 with appropriate work
factors).
+. Use strong password hashing (bcrypt or Argon2 with appropriate work factors).
. Implement session fixation prevention.
. Review and restrict default configurations.
@@ -178,13 +180,3 @@ Do not disclose security vulnerabilities publicly until a
fix is available and a
* link:session-management.html[Session Management] - Session handling
documentation
* link:cryptography.html[Cryptography] - Cryptographic utilities
* link:security-reports.html[Security Reports] - Known vulnerabilities and
mitigations
-
-== Document History
-
-[cols="1,3"]
-|===
-|Date |Change
-
-|2025-01-03
-|Initial security model documentation
-|===
diff --git a/src/site/templates/menu.ftl b/src/site/templates/menu.ftl
index 9cac369fb..6efb8f6f9 100644
--- a/src/site/templates/menu.ftl
+++ b/src/site/templates/menu.ftl
@@ -66,6 +66,7 @@
<ul class="dropdown-menu" aria-labelledby="navbarDropdown-about">
<li><a class="dropdown-item" href="<#if
(content.rootpath)??>${content.rootpath}<#else></#if>about.html">About</a></li>
<li><a class="dropdown-item" href="<#if
(content.rootpath)??>${content.rootpath}<#else></#if>privacy-policy.html">Privacy
Policy</a></li>
+ <li><a class="dropdown-item" href="<#if
(content.rootpath)??>${content.rootpath}<#else></#if>security-model.html">Security
Model</a></li>
<li><a class="dropdown-item" href="<#if
(content.rootpath)??>${content.rootpath}<#else></#if>security-reports.html">Vulnerability
Reports</a></li>
</ul>
</li>
