docs: add errors docs

Author: lepture

docs/changelog.rst

@@ -18,6 +18,10 @@ Changelog
 **Unreleased**
 
 - Show security warnings for ``none`` and ``RSA1_5`` algorithms.
+- Show security warnings for ``OctKey.generate_key`` and ``RSAKey.generate_key``
+  when key size is too short, per `NIST SP 800-131A`_.
+
+.. _`NIST SP 800-131A`: https://csrc.nist.gov/publications/detail/sp/800-131a/rev-2/final
 
 **Breaking changes**:
 
@@ -52,7 +56,7 @@ Changelog
 **Released on Feb 28, 2025**
 
 - Use secrets module to generate random bytes.
-- Use warnings for possible unsafe ``OctKey``` instead of raising error, via :issue:`32`.
+- Use warnings for possible unsafe ``OctKey`` instead of raising error, via :issue:`32`.
 
 1.0.3
 -----

docs/guide/errors.rst

@@ -0,0 +1,54 @@
+Errors & Warnings
+=================
+
+Here are some common errors and warnings, and how to handle them.
+
+SecurityWarning
+---------------
+
+You may encounter a ``SecurityWarning`` when using potentially
+unsafe algorithms or generating insecure keys. These warnings
+do not interrupt the execution of your application — they are
+simply printed to standard output (e.g., your terminal).
+
+If you prefer to suppress these warnings, you can use Python’s
+built-in ``warnings`` module:
+
+.. code-block:: python
+
+    import warnings
+    from joserfc.errors import SecurityWarning
+
+    warnings.simplefilter('ignore', SecurityWarning)
+
+With this configuration, ``SecurityWarning`` messages will no
+longer appear. Be cautious when suppressing these warnings, as
+they are meant to alert you to potentially insecure practices.
+
+UnsupportedAlgorithmError
+-------------------------
+
+By default, **ONLY recommended** :ref:`jwa` are allowed. With non recommended
+algorithms, you may encounter the ``UnsupportedAlgorithmError``` error.
+
+.. code-block:: python
+
+    >>> from joserfc import jws
+    >>> from joserfc.jwk import OctKey
+    >>> key = OctKey.generate_key()
+    >>> jws.serialize_compact({"alg": "HS384"}, b"payload", key)
+    Traceback (most recent call last):
+      File "<stdin>", line 1, in <module>
+      File ".../joserfc/jws.py", line 112, in serialize_compact
+        alg: JWSAlgModel = registry.get_alg(protected["alg"])
+                           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+      File ".../joserfc/_rfc7515/registry.py", line 60, in get_alg
+        raise UnsupportedAlgorithmError(f'Algorithm of "{name}" is not recommended')
+    joserfc.errors.UnsupportedAlgorithmError: unsupported_algorithm: Algorithm of "HS384" is not recommended
+
+Because "HS384" is not a recommended algorithm, it is not allowed by default. You
+SHOULD enable it manually by passing an ``algorithms`` parameter:
+
+.. code-block:: python
+
+    >>> jws.serialize_compact({"alg": "HS384"}, b"payload", key, algorithms=["HS384"])

docs/guide/jws.rst

@@ -279,14 +279,14 @@ the below error.
 
     >>> from joserfc import jws
     >>> from joserfc.jwk import OctKey
-    >>> key = OctKey.import_key("secret")
+    >>> key = OctKey.generate_key()
     >>> jws.serialize_compact({"alg": "HS384"}, b"payload", key)
     Traceback (most recent call last):
       File "<stdin>", line 1, in <module>
       File ".../joserfc/jws.py", line 112, in serialize_compact
         alg: JWSAlgModel = registry.get_alg(protected["alg"])
                            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-      File ".../joserfc/rfc7515/registry.py", line 60, in get_alg
+      File ".../joserfc/_rfc7515/registry.py", line 60, in get_alg
         raise UnsupportedAlgorithmError(f'Algorithm of "{name}" is not recommended')
     joserfc.errors.UnsupportedAlgorithmError: unsupported_algorithm: Algorithm of "HS384" is not recommended
 

docs/index.rst

@@ -78,6 +78,7 @@ Explore the following sections to discover more about ``joserfc`` and its featur
    guide/index
    guide/algorithms
    guide/registry
+   guide/errors
    migrations/index
 
 .. toctree::