autogen(docs): generate and format documentation

ory · Jan 11, 2022 · 5a4e11c · 5a4e11c
1 parent 7578aa9
commit 5a4e11c
Show file tree

Hide file tree

Showing 3 changed files with 62 additions and 22 deletions.
diff --git a/CONTRIBUTORS b/CONTRIBUTORS
@@ -148,8 +148,10 @@ Luis Pedrosa <2365589+lpedrosa@users.noreply.github.com>
 Lukasz Jagiello <jagiello.lukasz@gmail.com>
 Luke Stoward <luke_stoward@hotmail.co.uk>
 Marco Hutzsch <39520486+marcohutzsch1234@users.noreply.github.com>
+Mart Aarma <mart.aarma@nortal.com>
 Masoud Tahmasebi <mtahmasebi118@gmail.com>
 Matheus Moraes <matheusfaria.moraes@gmail.com>
+Matouš Dzivjak <matousdzivjak@gmail.com>
 Matt Bonnell <64976795+mbonnell-wish@users.noreply.github.com>
 Matt Bonnell <matt.bonnell@icloud.com>
 Matt Drollette <matt@drollette.com>

diff --git a/docs/docs/.static/api.json b/docs/docs/.static/api.json
@@ -526,7 +526,7 @@
         }
       },
       "put": {
-        "description": "Use this method if you do not want to let Hydra generate the JWKs for you, but instead save your own.\n\nA JSON Web Key (JWK) is a JavaScript Object Notation (JSON) data structure that represents a cryptographic key. A JWK Set is a JSON data structure that represents a set of JWKs. A JSON Web Key is identified by its set and key id. ORY Hydra uses this functionality to store cryptographic keys used for TLS and JSON Web Tokens (such as OpenID Connect ID tokens), and allows storing user-defined keys as well. This method is not supported when Hardware Security Module is enabled.",
+        "description": "Use this method if you do not want to let Hydra generate the JWKs for you, but instead save your own.\n\nA JSON Web Key (JWK) is a JavaScript Object Notation (JSON) data structure that represents a cryptographic key. A JWK Set is a JSON data structure that represents a set of JWKs. A JSON Web Key is identified by its set and key id. ORY Hydra uses this functionality to store cryptographic keys used for TLS and JSON Web Tokens (such as OpenID Connect ID tokens), and allows storing user-defined keys as well.",
         "consumes": ["application/json"],
         "produces": ["application/json"],
         "schemes": ["http", "https"],
@@ -577,7 +577,7 @@
         }
       },
       "post": {
-        "description": "This endpoint is capable of generating JSON Web Key Sets for you. There a different strategies available, such as symmetric cryptographic keys (HS256, HS512) and asymetric cryptographic keys (RS256, ECDSA, EdDSA). When Hardware Security Module is enabled, then only RS256, ECDSA key strategies are available. If the specified JSON Web Key Set does not exist, it will be created.\n\nA JSON Web Key (JWK) is a JavaScript Object Notation (JSON) data structure that represents a cryptographic key. A JWK Set is a JSON data structure that represents a set of JWKs. A JSON Web Key is identified by its set and key id. ORY Hydra uses this functionality to store cryptographic keys used for TLS and JSON Web Tokens (such as OpenID Connect ID tokens), and allows storing user-defined keys as well.",
+        "description": "This endpoint is capable of generating JSON Web Key Sets for you. There a different strategies available, such as symmetric cryptographic keys (HS256, HS512) and asymetric cryptographic keys (RS256, ECDSA). If the specified JSON Web Key Set does not exist, it will be created.\n\nA JSON Web Key (JWK) is a JavaScript Object Notation (JSON) data structure that represents a cryptographic key. A JWK Set is a JSON data structure that represents a set of JWKs. A JSON Web Key is identified by its set and key id. ORY Hydra uses this functionality to store cryptographic keys used for TLS and JSON Web Tokens (such as OpenID Connect ID tokens), and allows storing user-defined keys as well.",
         "consumes": ["application/json"],
         "produces": ["application/json"],
         "schemes": ["http", "https"],
@@ -716,7 +716,7 @@
         }
       },
       "put": {
-        "description": "Use this method if you do not want to let Hydra generate the JWKs for you, but instead save your own.\n\nA JSON Web Key (JWK) is a JavaScript Object Notation (JSON) data structure that represents a cryptographic key. A JWK Set is a JSON data structure that represents a set of JWKs. A JSON Web Key is identified by its set and key id. ORY Hydra uses this functionality to store cryptographic keys used for TLS and JSON Web Tokens (such as OpenID Connect ID tokens), and allows storing user-defined keys as well. This method is not supported when Hardware Security Module is enabled.",
+        "description": "Use this method if you do not want to let Hydra generate the JWKs for you, but instead save your own.\n\nA JSON Web Key (JWK) is a JavaScript Object Notation (JSON) data structure that represents a cryptographic key. A JWK Set is a JSON data structure that represents a set of JWKs. A JSON Web Key is identified by its set and key id. ORY Hydra uses this functionality to store cryptographic keys used for TLS and JSON Web Tokens (such as OpenID Connect ID tokens), and allows storing user-defined keys as well.",
         "consumes": ["application/json"],
         "produces": ["application/json"],
         "schemes": ["http", "https"],

diff --git a/docs/docs/reference/configuration.md b/docs/docs/reference/configuration.md
@@ -715,29 +715,67 @@ serve:
 dsn: ''
 
 ## hsm ##
-# Configures Hardware Security Module for hydra.openid.id-token, hydra.jwt.access-token keys
-# Either slot or token_label must be set. If token_label is set, then first slot in index with this label is used.
 #
-# Set this value using environment variables on
-# - Linux/macOS:
-#  $ export HSM_ENABLED=<value>
-#  $ export HSM_LIBRARY=<value>
-#	 $ export HSM_PIN=<value>
-#	 $ export HSM_SLOT=<value>
-#	 $ export HSM_TOKEN_LABEL=<value>
-# - Windows Command Line (CMD):
-#    > set HSM_ENABLED=<value>
-#    > set HSM_LIBRARY=<value>
-#    > set HSM_PIN=<value>
-#    > set HSM_SLOT=<value>
-#    > set HSM_TOKEN_LABEL=<value>
+# Configures Hardware Security Module.
 #
 hsm:
+  ## library ##
+  #
+  # Full path (including file extension) of the HSM vendor PKCS#11 library
+  #
+  # Set this value using environment variables on
+  # - Linux/macOS:
+  #    $ export HSM_LIBRARY=<value>
+  # - Windows Command Line (CMD):
+  #    > set HSM_LIBRARY=<value>
+  #
+  library: ''
+
+  ## pin ##
+  #
+  # PIN code for token operations
+  #
+  # Set this value using environment variables on
+  # - Linux/macOS:
+  #    $ export HSM_PIN=<value>
+  # - Windows Command Line (CMD):
+  #    > set HSM_PIN=<value>
+  #
+  pin: ''
+
+  ## slot ##
+  #
+  # Slot ID of the token to use (if label is not specified)
+  #
+  # Set this value using environment variables on
+  # - Linux/macOS:
+  #    $ export HSM_SLOT=<value>
+  # - Windows Command Line (CMD):
+  #    > set HSM_SLOT=<value>
+  #
+  slot: -100000000
+
+  ## token_label ##
+  #
+  # Label of the token to use (if slot is not specified). If both slot and label are set, token label takes preference over slot. In this case first slot, that contains this label is used.
+  #
+  # Set this value using environment variables on
+  # - Linux/macOS:
+  #    $ export HSM_TOKEN_LABEL=<value>
+  # - Windows Command Line (CMD):
+  #    > set HSM_TOKEN_LABEL=<value>
+  #
+  token_label: ''
+
+  ## enabled ##
+  #
+  # Set this value using environment variables on
+  # - Linux/macOS:
+  #    $ export HSM_ENABLED=<value>
+  # - Windows Command Line (CMD):
+  #    > set HSM_ENABLED=<value>
+  #
   enabled: false
-  library: /path/to/hsm-vendor/library.so
-  pin: partition-pin-code
-  slot: 0
-  token_label: hydra
 
 ## webfinger ##
 #