rodauth 1.19.1 → 1.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bad06774a2bc77b951a38d149fd641d16bf1034e379458b4e5fb49bbf4dfb0f3
-  data.tar.gz: c82fc51c1c7bc5c917e4ef59816db28fb4fd3df52a90262b215215b7f1732639
+  metadata.gz: 7ecf305eda0aef347c6464decf7ef50e8e5fd4a69927bd690b68deae66de6b63
+  data.tar.gz: 6f8e6ffcd70b5ff94b4f922c04661896055b401a85930e085e8aaa91d1e12dfe
 SHA512:
-  metadata.gz: c53d4e2757e9f2d6ceb0d7724b5d6f9d7090c3e1fa88471e570b4c72ffeb63aea71e0e1dc1d93e0d16463ba982e70cd0f0e00ef8a2ecb6fbf4acdb33420da3f4
-  data.tar.gz: 50269467b08e309416984b6831a8871e023edb1287a88306e072fc375e1a75e4bdb866cc4533cab3e468d3666f1892f71bf1cfd93cefe186941957617c91e1eb
+  metadata.gz: ebc055ab52ae0da05d5145b273cc63b53e93f29dae456ff86c321e4c5d5798b92d65b43f0d91272ccb2a44b7b77fc29765e45ffc511564c814771b87fc1b62bf
+  data.tar.gz: fe083dd6517fd410eacfba69e061b3b7b82e6beae68e1413334db939c956ccb953e28d0a7a074731205e1d3ada60f12e96660b525bfc836a5a4fea45b33b881f

data/CHANGELOG

@@ -1,3 +1,75 @@
+=== 1.20.0 (2019-06-07)
+
+* Support rotp 5 in the otp feature (jeremyevans)
+
+* Add jwt_refresh feature to allow shorter lived JWTs with a refresh token for creating new JWTs (allavena, jeremyevans) (#28)
+
+* Fix disallow_password_reuse feature when account_password_hash_column is not set and verify_account feature is not used (cptaffe) (#59)
+
+* Rename no_matching_email_auth_key_message to no_matching_email_auth_key_error_flash for consistency (jeremyevans)
+
+* Rename no_matching_verify_login_change_key_message to no_matching_verify_login_change_key_error_flash for consistency (jeremyevans)
+
+* Rename attempt_to_login_to_unverified_account_notice_message to attempt_to_login_to_unverified_account_error_flash for consistency (jeremyevans)
+
+* Rename attempt_to_create_unverified_account_notice_message to attempt_to_create_unverified_account_error_flash for consistency (jeremyevans)
+
+* Rename no_matching_verify_account_key_message to no_matching_verify_account_key_error_flash for consistency (jeremyevans)
+
+* Rename no_matching_unlock_account_key_message to no_matching_unlock_account_key_error_flash for consistency (jeremyevans)
+
+* Rename no_matching_reset_password_key_message to no_matching_reset_password_key_error_flash for consistency (jeremyevans)
+
+* Add otp_keys_use_hmac? and otp_setup_raw_param configuration methods to the otp feature for configuring use of HMACs with OTP authentication (jeremyevans)
+
+* Do not set a previous account password before password has been set when using disallow_password_reuse with verify_account_set_password? (jeremyevans)
+
+* Add allow_raw_single_session_key? to single_session feature to allow raw single single session tokens, for graceful transition (jeremyevans)
+
+* Add raw_remember_token_deadline to remember feature to allow raw remember tokens before given deadline, for graceful transition (jeremyevans)
+
+* Add allow_raw_email_token? configuration method to email_base feature to allow raw tokens when email_token_hmac_secret is set, for graceful transition (jeremyevans)
+
+* Add hmac_secret configuration method, used for additional security using HMACs (jeremyevans)
+
+* Use urlsafe base64 for new token keys on Ruby 1.8 (jeremyevans)
+
+* Add login_input_type configuration method for setting the input type for login inputs (jeremyevans)
+
+* Add formatted_field_error configuration method for formatting error messages (jeremyevans)
+
+* Add field_error_attributes configuration method for configuring attributes for fields with errors (jeremyevans)
+
+* Add field_attributes configuration method for configuring attributes for specific fields (jeremyevans)
+
+* Add default_field_attributes configuration method to set default attributes for all input fields (jeremyevans)
+
+* Make error handling accessible by default using aria-invalid and aria-describedby attributes (jeremyevans)
+
+* Add mark_input_fields_as_required? configuration method for whether inputs should use the required attribute (jeremyevans)
+
+* Add input_field_error_message_class configuration method for the CSS class used for error messages (jeremyevans)
+
+* Wrap all error messages in a span so they can be styled (jeremyevans)
+
+* Add input_field_error_class configuration method for customizing CSS class to use for inputs with errors (jeremyevans)
+
+* Add input_field_label_suffix configuration method for suffixing all input labels, useful for labeling fields as required (jeremyevans)
+
+* Add verify_account_resend_explanatory_text configuration method to verify_account feature for configuring text (jeremyevans)
+
+* Add unlock_account_explanatory_text and unlock_account_request_explanatory_text configuration methods to lockout feature for configuring text (jeremyevans)
+
+* Add reset_password_explanatory_text configuration method to reset_password feature for configuring text (jeremyevans)
+
+* Add otp_provisioning_uri_label and otp_secret_label configuration methods to otp feature for configuring labels displayed during OTP setup (jeremyevans)
+
+* Add add_recovery_codes_heading configuration method to recovery_codes feature for configuring heading text (jeremyevans)
+
+* Use define_method instead of instance_exec for route dispatching for better performance (jeremyevans)
+
+* Add already_an_account_with_this_login_message configuration method (1gor) (#54)
+
 === 1.19.1 (2018-11-16)
 
 * Support rotp 4 in the otp feature (jeremyevans)

data/MIT-LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2015-2018 Jeremy Evans
+Copyright (c) 2015-2019 Jeremy Evans
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to

data/README.rdoc

@@ -41,6 +41,7 @@ hashes by protecting access via database functions.
 * Session Expiration
 * Single Session (Only one active session per account)
 * JWT (JSON API support for all other features)
+* JWT Refresh (Access & Refresh Token)
 * Update Password Hash (when hash cost changes)
 * HTTP Basic Auth
 * Change Password Notify
@@ -128,17 +129,98 @@ of your application.
 
 === Tokens
 
-Account verification, password resets, remember, and lockout tokens
-all use a similar approach.  They all provide a token, in the format
-"account-id_long-random-string".  By including the id of the account
-in the token, an attacker can only attempt to bruteforce the token
-for a single account, instead of being able to bruteforce tokens for
-all accounts at once (which would be possible if the token was just a
-random string).
+Account verification, password resets, email auth, verify login change,
+remember, and lockout tokens all use a similar approach.  They all
+provide a token, in the format "account-id_long-random-string".  By
+including the id of the account in the token, an attacker can only
+attempt to bruteforce the token for a single account, instead of being
+able to bruteforce tokens for all accounts at once (which would be
+possible if the token was just a random string).
 
 Additionally, all comparisons of tokens use a timing-safe comparison
 function to reduce the risk of timing attacks.
 
+== HMAC
+
+By default, Rodauth does not use HMACs, but you are encouraged to use
+the +hmac_secret+ configuration method to set an HMAC secret.  Setting
+an HMAC secret will enable HMACs for additional security, as described
+below.
+
+=== email_base feature
+
+All features that send email use this feature.  Setting +hmac_secret+
+will make the tokens sent via email use an HMAC, while the raw token
+stored in the database will not use an HMAC.  This will make it so
+if the tokens in the database are leaked (e.g. via an SQL injection
+vulnerability), they will not be usable without also having access
+to the +hmac_secret+.  Without an HMAC, the raw token is sent in the
+email, and if the tokens in the database are leaked, they will be
+usable.
+
+To allow for an graceful transition, you can set +allow_raw_email_token?+
+to true temporarily.  This will allow the raw tokens in previous sent
+emails to still work.  This should only be set temporarily as it
+removes the security that +hmac_secret+ adds.  Most features that
+send email have tokens that expire by default in 1 day.  The
+exception is the verify_account feature, which has tokens that do
+not expire.  For the verify_account feature, if the user requested
+an email before +hmac_secret+ was set, after +allow_raw_email_token+
+is no longer set, they will need to request the verification email
+be resent, in which case they will receive an email with a token
+that uses an HMAC.
+
+=== remember feature
+
+Similar to the email_base feature, this uses HMACs for remember
+tokens, while storing the raw tokens in the database.  This makes
+it so if the raw tokens in the database are leaked, the remember
+tokens are not usable without knowledge of the +hmac_secret+.
+
+The +raw_remember_token_deadline+ configuration method can
+be set to allow a previously set raw remember token to be used
+if the deadline for the remember token is before the given time.
+This allows for graceful transition to using HMACs for remember tokens.
+By default, the deadline is 14 days after the token is created, so this
+should be set to 14 days after the time you enable the HMAC for the
+remember feature if you are using the defaults.
+
+=== otp feature
+
+Setting +hmac_secret+ will provide HMACed OTP keys to users, and
+would store the raw OTP keys in the database.  This will make so
+if the raw OTP keys in the database are leaked, they will not be
+usable for two factor authentication without knowledge of the +hmac_secret+.
+
+Unfortunately, there can be no simple graceful transition for existing users.
+When introducing +hmac_secret+ to a Rodauth installation that already uses
+the otp feature, you will have to either revoke and replace all OTP keys,
+set +otp_keys_use_hmac?+ to false and continue to use raw OTP keys, or override
++otp_keys_use_hmac?+ to return false if the user was issued an OTP key before
++hmac_secret+ was added to the configuration, and true otherwise.
++otp_keys_use_hmac?+ defaults to true if +hmac_secret+ is set, and false
+otherwise.
+
+If +otp_keys_use_hmac?+ is true, Rodauth will also ensure during OTP setup
+that the OTP key was generated by the server.  If +otp_keys_use_hmac?+ is false,
+any OTP key in a valid format will be accepted during setup.
+
+If +otp_keys_use_hmac?+ is true, the jwt and otp features are in use and you
+are setting up OTP via JSON requests, you need to first send a POST request
+to the OTP setup route.  This will return an error with the +otp_secret+ and
++otp_raw_secret+ parameters in the JSON.  These parameters should be submitted
+in the POST request to setup OTP, along with a valid OTP auth code for the
++otp_secret+.
+
+=== single_session feature
+
+Setting +hmac_secret+ will ensure the single session secret set in the
+session will be an HMACed.  This does not affect security, as the session
+itself should at the least by protected by an HMAC (if not encrypted).
+This is only done for consistency, so that the raw tokens in the database
+are distinct from the tokens provided to the users.  To allow for a
+graceful transition, +allow_raw_single_session_key?+ can be set to true.
+
 == PostgreSQL Database Setup
 
 In order to get full advantages of Rodauth's security design on PostgreSQL,
@@ -331,6 +413,14 @@ Note that these migrations require Sequel 4.35.0+.
         DateTime :email_last_sent, :null=>false, :default=>Sequel::CURRENT_TIMESTAMP
       end
 
+      # Used by the jwt refresh feature
+      create_table(:account_jwt_refresh_keys) do
+        primary_key :id, :type=>:Bignum
+        foreign_key :account_id, :accounts, :type=>:Bignum
+        String :key, :null=>false
+        DateTime :deadline, deadline_opts[1]
+      end
+
       # Used by the account verification feature
       create_table(:account_verification_keys) do
         foreign_key :id, :accounts, :primary_key=>true, :type=>:Bignum
@@ -431,6 +521,7 @@ Note that these migrations require Sequel 4.35.0+.
         run "GRANT ALL ON account_statuses TO #{user}"
         run "GRANT ALL ON accounts TO #{user}"
         run "GRANT ALL ON account_password_reset_keys TO #{user}"
+        run "GRANT ALL ON account_jwt_refresh_keys TO #{user}"
         run "GRANT ALL ON account_verification_keys TO #{user}"
         run "GRANT ALL ON account_login_change_keys TO #{user}"
         run "GRANT ALL ON account_remember_keys TO #{user}"
@@ -459,6 +550,7 @@ Note that these migrations require Sequel 4.35.0+.
                  :account_remember_keys,
                  :account_login_change_keys,
                  :account_verification_keys,
+                 :account_jwt_refresh_keys,
                  :account_password_reset_keys,
                  :accounts,
                  :account_statuses)
@@ -719,6 +811,7 @@ view the appropriate file in the doc directory.
 * {Session Expiration}[rdoc-ref:doc/session_expiration.rdoc]
 * {Single Session}[rdoc-ref:doc/single_session.rdoc]
 * {JWT}[rdoc-ref:doc/jwt.rdoc]
+* {JWT}[rdoc-ref:doc/jwt_refresh.rdoc]
 * {HTTP Basic Auth}[rdoc-ref:doc/http_basic_auth.rdoc]
 
 === Calling Rodauth in the Routing Tree

data/doc/base.rdoc

@@ -14,6 +14,13 @@ account_password_hash_column :: Set if the password hash column is in the same
                                 often used if you are replacing a legacy
                                 authentication system with Rodauth.
 db :: The Sequel::Database object used for database access.
+hmac_secret :: This sets the secret to use for all of Rodauth's HMACs.  This is
+               not set by default, in which case Rodauth does not use HMACs for
+               additional security.  However, it is highly recommended that you
+               set this.
+mark_input_fields_as_required? :: Whether input fields should be marked as
+                                  required, so browsers will not allow submission
+                                  without filling out the field (default: false).
 prefix :: The routing prefix used for Rodauth routes.  If you are calling
           in a routing subtree, this should be set to the root path of the
           subtree.  This should include a leading slash if set, but not a
@@ -41,8 +48,23 @@ cache_templates :: Whether to cache templates. True by default. It may be worth
                    switching this to false in development if you are using your
                    own templates instead of the templates provided by Rodauth.
 default_redirect :: Where to redirect after most successful actions.
+default_field_attributes :: The default attributes to use for input field tags, if
+                            field_attributes returns nil for the field.
+field_attributes(field) :: The attributes to use for the input field tags for the given
+                           field (parameter name).
+field_error_attributes(field) :: The attributes to use for the input field tags for the given
+                                 field (parameter name), if the input has an error.
 flash_error_key :: The flash key to use for error messages (default: +:error+).
 flash_notice_key :: The flash key to use for notice messages (default: +:notice+).
+formatted_field_error(field, error) :: HTML to use for error messages for the field (parameter
+                                       name), if the field has an error.  By default, uses a
+                                       span tag for the error message.
+input_field_label_suffix :: The suffix to use for all labels.  Useful for noting that
+                            the fields are required.
+input_field_error_class :: The CSS class to use for input fields with errors. Can be a
+                           space separated string for multiple CSS classes.
+input_field_error_message_class :: The CSS class to use for error messages. Can be a
+                           space separated string for multiple CSS classes.
 invalid_field_error_status :: The response status to use for invalid field
                               value errors, 422 by default.
 invalid_key_error_status :: The response status to use for invalid key codes,
@@ -54,6 +76,8 @@ invalid_password_message :: The error message to display when a given
 lockout_error_status :: The response status to use a login is attempted to an account that
                         is locked out, 403 by default.
 login_column :: The login column in the account model.
+login_input_type :: The input type to use for logins. Defaults to text but could be set to email
+                    if all logins should be valid email addresses.
 login_label :: The label to use for logins.
 login_param :: The parameter name to use for logins.
 login_required_error_status :: The response status to return when a login is required
@@ -79,6 +103,7 @@ set_deadline_values? :: Whether deadline values should be set.  True by default
                         if you want to vary the value based on a request parameter.
 template_opts :: Any template options to pass to view/render.  This can be used
                  to set a custom layout, for example.
+token_separator :: The string used to separate account id from the random key in links.
 unmatched_field_error_status :: The response status to use when two field values should
                                 match but do not, 422 by default.
 unopen_account_error_status :: The response status to use when trying to login to an

data/doc/email_auth.rdoc

@@ -29,7 +29,7 @@ email_auth_session_key :: The key in the session to hold the email auth key temp
 email_auth_skip_resend_within :: The number of seconds before sending another email auth email.
 email_auth_table :: The name of the email auth keys table.
 force_email_auth? :: Whether email auth should be forced for the account.  By default, email auth is forced if the account does not have a password.
-no_matching_email_auth_key_message :: The flash error message to show if attempting to access the email auth form with an invalid key.
+no_matching_email_auth_key_error_flash :: The flash error message to show if attempting to access the email auth form with an invalid key.
 
 == Auth Methods
 

data/doc/email_base.rdoc

@@ -5,6 +5,11 @@ that requires sending emails.
 
 == Auth Value Methods
 
+allow_raw_email_token? :: When +email_token_hmac_secret+ is used, this allows the use of the raw
+                          token.  This should only be set to true temporarily during a transition
+                          period from using raw tokens to using HMACed tokens.  After the transition
+                          period, this should not be set, as setting this to true removes the
+                          security that HMACed tokens add.
 default_post_email_redirect :: Where to redirect after sending an email. This is the default
                                redirect location for all redirects after an email is sent when the
                                account is not logged in.  Also includes cases where an email is not
@@ -13,7 +18,6 @@ email_from :: The from address to use for emails sent by Rodauth.
 email_subject_prefix :: The prefix to use for email subjects 
 require_mail? :: Set to false to not require mail, useful if using a different
                  library for sending email.
-token_separator :: The string used to separate account id from the random key in links.
 
 == Auth Methods
 

data/doc/internals.rdoc

@@ -1,6 +1,6 @@
 = Rodauth Internals
 
-Rodauth's implementation heavily uses metaprogramming in order to DRY up the codebase, which can be a little intimiting to developers who are not familiar with the codebase.  This guide explains how Rodauth is built, which should make the internals easier to understand.
+Rodauth's implementation heavily uses metaprogramming in order to DRY up the codebase, which can be a little intimidating to developers who are not familiar with the codebase.  This guide explains how Rodauth is built, which should make the internals easier to understand.
 
 == Object Model
 
@@ -16,7 +16,7 @@ Inside the block you pass to <tt>plugin :rodauth</tt>, +self+ is an instance of
 
 === Rodauth::Feature
 
-Each of the parts of rodauth that you can use is going to be a separate feature.  Rodauth::Feature is a Module subclass, and every feature you load is included in the Rodauth::Auth subclass used by the Roda application.  Rodauth::Feature has many methods designed to make building Rodauth features easier by defining methods in the Rodauth::Feature instance.
+Each of the parts of rodauth that you can use is going to be a separate feature.  Rodauth::Feature is a Module subclass, and every rodauth feature you load is an instance of this class, which is included in the Rodauth::Auth subclass used by the Roda application.  Rodauth::Feature has many methods designed to make building Rodauth features easier by defining methods in the Rodauth::Feature instance.
 
 === Rodauth::FeatureConfiguration
 

data/doc/jwt_refresh.rdoc

@@ -0,0 +1,35 @@
+= Documentation for JWT Refresh Feature
+
+The jwt_refresh feature adds support for a database-backed JWT refresh token,
+setting a short lifetime on JWT access tokens.
+
+When this feature is used, the access and refresh token are provided
+at login in the response body (the access token is still provided in the Authorization
+header), and for any subsequent POST to /jwt-refresh.
+
+Note that using the refresh token invalides the old refresh token and creates
+a new access token with an updated lifetime.  However, it does not invalidate
+older access tokens.  Older access tokens remain valid until they expire.
+
+This feature depends on the jwt feature.
+
+== Auth Value Methods
+
+jwt_access_token_key :: Name of the key in the response json holding the access token.  Default is +access_token+.
+jwt_access_token_not_before_period :: How many seconds before the current time will the jwt be considered valid (to account for inaccurate clocks). Default is 5.
+jwt_access_token_period :: Validity of an access token in seconds, default is 1800 (30 minutes).
+jwt_refresh_invalid_token_message :: Error message when the provided refresh token is non existent, invalid or expired.
+jwt_refresh_token_account_id_column :: The column name in the refresh token table storing the account id, should be a foreign key referencing the accounts table.
+jwt_refresh_token_deadline_column :: The column name in the refresh token keys table storing the deadline after which the refresh token will no longer be valid.
+jwt_refresh_token_deadline_interval :: validity of a refresh token. Default is 14 days.
+jwt_refresh_token_id_column :: The column name in the refresh token keys table storing the id of each token (the primary key of the table).
+jwt_refresh_token_key :: Name of the key in the response json holding the refresh token.  Default is +refresh_token+.
+jwt_refresh_token_key_column :: The column name in the refresh token keys table holding the refresh token key value.
+jwt_refresh_token_key_param :: Name of parameter in which the refresh token is provided when requesting a new token.  Default is +refresh_token+.
+jwt_refresh_token_table :: Name of the table holding refresh token keys.
+
+== Auth Methods
+
+after_refresh_token :: Hooks for specific processing once the refresh token has been set.
+account_from_refresh_token(token) :: Returns the account hash for the given refresh token.
+before_refresh_token :: Hooks for specific processing before the refresh token is computed.

data/doc/lockout.rdoc

@@ -19,18 +19,21 @@ account_login_failures_number_column :: The column in the account login failures
 account_login_failures_table :: The table containing number of login failures per account.
 login_lockout_error_flash :: The flash error to show if there if the account is or becomes locked out after a login attempt.
 max_invalid_logins :: The maximum number of failed logins before account lockout. As this feature is just designed for bruteforce protection, this is set to 100.
+no_matching_unlock_account_key_error_flash :: The flash error message to show if attempting to access the unlock account form with an invalid key.
 unlock_account_additional_form_tags :: HTML fragment with additional form tags to use on the unlock account form.
 unlock_account_autologin? :: Whether to autologin users after successful account unlock.
 unlock_account_button :: The text to use on the unlock account button.
 unlock_account_email_recently_sent_error_flash :: The flash error to show if not sending an unlock account email because another was sent recently.
 unlock_account_email_recently_sent_redirect :: Where to redirect after not sending an unlock account email because another was sent recently.
 unlock_account_email_subject :: The subject to use for the unlock account email.
+unlock_account_explanatory_text :: The text to display above the button to unlock an account.
 unlock_account_error_flash :: The flash error to display upon unsuccessful account unlock.
 unlock_account_key_param :: The parameter name to use for the unlock account key.
 unlock_account_notice_flash :: The flash notice to display upon successful account unlock.
 unlock_account_redirect :: Where to redirect after successful account unlock.
 unlock_account_request_additional_form_tags :: HTML fragment with additional form tags to use on the form to request an account unlock.
 unlock_account_request_button :: The text to use on the unlock account request button.
+unlock_account_request_explanatory_text :: The text to display above the button to request an account unlock.
 unlock_account_request_notice_flash :: The flash notice to display upon successful sending of the unlock account email.
 unlock_account_request_redirect :: Where to redirect after account unlock email is sent.
 unlock_account_request_route :: The route to the unlock account request action.  Defaults to +unlock-account-request+.

data/doc/login_password_requirements_base.rdoc

@@ -5,6 +5,9 @@ use a Rodauth feature that requires setting logins or passwords.
 
 == Auth Value Methods
 
+already_an_account_with_this_login_message :: The error message to display when
+                                              there already exists an account
+                                              with the same login
 login_confirm_label :: The label to use for login confirmations.
 login_confirm_param :: The parameter name to use for login confirmations.
 login_does_not_meet_requirements_message :: The error message to display when
@@ -13,7 +16,7 @@ login_does_not_meet_requirements_message :: The error message to display when
 login_maximum_length :: The maximum length for logins, 255 by default.
 login_minimum_length :: The minimum length for logins, 3 by default.
 login_too_long_message :: The error message fragment to show if the login is
-                           too long.
+                          too long.
 login_too_short_message :: The error message fragment to show if the login is
                            too short.
 logins_do_not_match_message :: The error message to display when login and

data/doc/otp.rdoc

@@ -8,56 +8,46 @@ The otp feature requires the rotp and rqrcode gems.
 
 == Auth Value Methods
 
-otp_already_setup_error_flash :: The flash error to show if going to the OTP setup
-                                 page when OTP is already setup.
-otp_already_setup_redirect :: Where to redirect if going to the OTP setup page when OTP
-                              has already been setup.
-otp_auth_additional_form_tags :: HTML fragment containing additional form tags to use on
-                                 the OTP authentication form.
+otp_already_setup_error_flash :: The flash error to show if going to the OTP setup page when OTP is already setup.
+otp_already_setup_redirect :: Where to redirect if going to the OTP setup page when OTP has already been setup.
+otp_auth_additional_form_tags :: HTML fragment containing additional form tags to use on the OTP authentication form.
 otp_auth_button :: Text to use for button on OTP authentication form.
 otp_auth_error_flash :: The flash error to show if unable to authenticate via OTP.
-otp_auth_failures_limit :: The number of allowed OTP authentication failures before locking
-                           out.
+otp_auth_failures_limit :: The number of allowed OTP authentication failures before locking out.
 otp_auth_form_footer :: A footer to display at the bottom of the OTP authentication form.
 otp_auth_label :: The label for the OTP authentication code.
 otp_auth_param :: The parameter name for the OTP authentication code.
 otp_auth_route :: The route to the OTP authentication action. Defaults to +otp-auth+.
 otp_class :: The class to use for OTP authentication (default: ROTP::TOTP)
 otp_digits :: The number of digits to use in OTP authentication codes (rotp's default is 6).
-otp_disable_additional_form_tags :: HTML fragment containing additional form tags to use on
-                                    the from to disable OTP authentication.
+otp_disable_additional_form_tags :: HTML fragment containing additional form tags to use on the from to disable OTP authentication.
 otp_disable_button :: The text to use for button on form to disable OTP authentication.
 otp_disable_error_flash :: The flash error to show if unable to disable OTP authentication.
 otp_disable_notice_flash :: The flash notice to show after disabling OTP authentication.
 otp_disable_redirect :: Where to redirect after disabling OTP authentication.
 otp_disable_route :: The route to the OTP disable action. Defaults to +otp-disable+.
-otp_drift :: The number of seconds the client and server are allowed to drift apart. The
-             default is nil, to not allow drift.
-otp_invalid_auth_code_message :: The error message to show when an invalid OTP authentication
-                                 code is used.
-otp_invalid_secret_message :: The error message to show when an invalid OTP secret is submitted
-                              during OTP setup.
+otp_drift :: The number of seconds the client and server are allowed to drift apart. The default is nil, to not allow drift.
+otp_invalid_auth_code_message :: The error message to show when an invalid OTP authentication code is used.
+otp_invalid_secret_message :: The error message to show when an invalid OTP secret is submitted during OTP setup.
 otp_interval :: The number of seconds in which to rotate TOTP auth codes (rotp's default is 300).
-otp_issuer :: The issuer to use in the OTP provisioning URL.  Defaults to the host name of the
-              request.
+otp_issuer :: The issuer to use in the OTP provisioning URL.  Defaults to the host name of the request.
 otp_keys_id_column :: The column in the otp_keys_table containing the account id.
 otp_keys_column :: The column in the otp_keys_table containing the OTP secret.
-otp_keys_failures_column :: The column in the otp_keys_table containing the
-                            number of OTP authentication failures.
-otp_keys_last_use_column :: The column in otp_keys_table containing the last authentication
-                            timestamp.
+otp_keys_failures_column :: The column in the otp_keys_table containing the number of OTP authentication failures.
+otp_keys_last_use_column :: The column in otp_keys_table containing the last authentication timestamp.
 otp_keys_table :: The table name containing the OTP secrets.
-otp_lockout_redirect :: Where to redirect if going to OTP authentication page and OTP
-                        authentication has been locked out.
-otp_lockout_error_flash :: The flash error show show when OTP authentication has been locked
-                           out due to numerous authentication failures.
+otp_keys_use_hmac? :: Whether to use HMACs for OTP keys.  Defaults to whether +hmac_secret+ has been set.  Should be set to false if adding +hmac_secret+ to Rodauth where the otp feature is already in use, as otherwise it will render existing OTP keys invalid.
+otp_lockout_redirect :: Where to redirect if going to OTP authentication page and OTP authentication has been locked out.
+otp_lockout_error_flash :: The flash error show show when OTP authentication has been locked out due to numerous authentication failures.
+otp_provisioning_uri_label :: The label used when displaying the OTP provisioning URI during OTP setup.
+otp_secret_label :: The label used when displaying the OTP secret during OTP setup.
 otp_session_key :: The session key used to store whether the user has authenticated via OTP.
-otp_setup_additional_form_tags :: HTML fragment containing additional form tags when setting up
-                                  OTP authentication.
+otp_setup_additional_form_tags :: HTML fragment containing additional form tags when setting up OTP authentication.
 otp_setup_button :: Text for the button when setting up OTP authentication.
 otp_setup_error_flash :: The flash error to show if OTP authentication setup was not successful.
 otp_setup_notice_flash :: The flash notice to show if OTP authentication setup was successful.
 otp_setup_param :: The parameter name used for the OTP secret when setting up OTP authentication.
+otp_setup_raw_param :: The parameter name used for the raw OTP secret when setting up OTP authentication, when +otp_keys_use_hmac?+ is true. 
 otp_setup_redirect :: Where to redirect after sucessful OTP authentication setup.
 otp_setup_route :: The route to the OTP setup action. Defaults to +otp-setup+.
 
@@ -80,21 +70,14 @@ otp_exists? :: Whether the current account has setup OTP.
 otp_key :: The stored OTP secret for the account.
 otp_locked_out? :: Whether the current account has been locked out of OTP authentication.
 otp_new_secret :: A new secret to use when setting up OTP.
-otp_provisioning_name :: The provisioning name to use during OTP setup, defaults to the
-                         account's email.
+otp_provisioning_name :: The provisioning name to use during OTP setup, defaults to the account's email.
 otp_provisioning_uri :: The provisioning URI displayed during OTP setup.
 otp_qr_code :: The QR code containing the otp_provisioning_uri, by default an SVG image.
 otp_record_authentication_failure :: Record an OTP authentication failure.
 otp_remove :: Removes all stored OTP data for the current account.
-otp_remove_auth_failures :: Removes OTP authentication failures for the current account,
-                            used after successful OTP authentication.
+otp_remove_auth_failures :: Removes OTP authentication failures for the current account, used after successful OTP authentication.
 otp_setup_view :: The HTML to use for the form to setup OTP authentication.
 otp_tmp_key(secret) :: Set the secret to use for the OTP key.
-otp_update_last_use :: Update the last time OTP authentication was successful for the
-                       account.  Return true if the authentication should be allowed, or
-                       false if it should not be allowed because the last authentication
-                       was too recent and indicates the possible reuse of a TOTP
-                       authentication code.
-otp_valid_code?(auth_code) :: Whether the given code is the currently valid OTP auth
-                              code for the account.
+otp_update_last_use :: Update the last time OTP authentication was successful for the account.  Return true if the authentication should be allowed, or false if it should not be allowed because the last authentication was too recent and indicates the possible reuse of a TOTP authentication code.
+otp_valid_code?(auth_code) :: Whether the given code is the currently valid OTP auth code for the account.
 otp_valid_key?(secret) :: Whether the given secret is a valid OTP secret.