otp policy

SUMMARY.adoc

@@ -30,6 +30,7 @@
  .. link:topics/login-settings/remember-me.adoc[Remember Me]
  . link:topics/authentication.adoc[Authentication]
  .. link:topics/authentication/password-policies.adoc[Password Policies]
+ .. link:topics/authentication/otp-policies.adoc[OTP Policies]
  . link:topics/admin-permissions.adoc[Master Admin Access Control]
  . link:topics/per-realm-admin-permissions.adoc[Per Realm Admin Access Control]
  . link:topics/client-registration.adoc[Client Registration]

topics/authentication/otp-policies.adoc

@@ -0,0 +1,57 @@
+
+=== OTP Policies
+
+{{book.project.name}} has a number of policies you can set up for your FreeOTP or Google Authenticator One-Time Password
+generator.  Click on the `Authentication` left menu item and got to the `OTP Policy` tab.
+
+.OTP Policy
+image:../../{{book.images}}/otp-policy.png[]
+
+Any policies you set here will be used to validate one-time passwords.  When configuring OTP, FreeOTP and Google Authenticator
+can scan in a bar code that is generated on the OTP set up page that {{book.project.name}} has.  The bar code is also
+generated from information configured on the `OTP Policy` tab.
+
+==== TOTP vs. HOTP
+
+There are two different algorithms to choose from for your OTP generators.  Time Based (TOTP) and Counter Based (HOTP) based.
+For TOTP, your token generator will hash the current time and a share secret.  The server validates the OTP by comparing
+the all hashes within a certain window of time to the submitted value.  So, TOTPs are valid only for a short window of time (usually 30 seconds).
+For HOTP a shared counter is used instead of the current time.  The server increments the counter each successful OTP login.  So, valid OTPs only
+change after a successful login.
+
+TOTP is considered a little more secure because the matchable OTP is only valid for a short window of time while the OTP for HOTP can
+be valid for an indeterminate amount of time.  HOTP is much more user friendly as the user won't have to hurry to enter in their
+OTP before the time interval is up.  With the way {{book.project.name}} has implement TOTP this distinction becomes a little more
+blurry.  HOTP requires a database update every time the server wants to increment the counter.  This can be a performance drain
+on the authentication server when there is heavy load.  So, to provide a more efficient alternative, TOTP does not remember passwords
+used.  This bypasses the need to do any DB updates, but the downside is that TOTPs can be re-used in the valid time interval.  For future
+versions of {{book.project.name}} it is planned that you will be able to configure whether TOTP checks older OTPs in the time interval.
+
+==== TOTP Configuration Options
+
+Hashing Algorithm::
+  Default is SHA1, more secure options are SHA256 and SHA512.
+Number of Digits::
+  How many characters is the OTP?  Short means more user friendly as it is less the user has to type.  More means more security.
+Look Ahead Window::
+  How many intervals ahead should the server try and match the hash?  This exists so just in case the clock of the TOTP generator
+  or authentication server get out of sync.  The default value of 1 is usually good enough.  For example, if the time interval
+  for a new token is every 30 seconds, the default value of 1 means that it will only accept valid tokens in that 30 second window.
+  Each increment of this config value will increase the valid window by 30 seconds.
+OTP Token Period::
+  Time interval in seconds a new TOTP will be generated by the token generator.  And, the time window the server is matching a hash.
+
+==== HOTP Configuration Options
+
+Hashing Algorithm::
+  Default is SHA1, more secure options are SHA256 and SHA512.
+Number of Digits::
+  How many characters is the OTP?  Short means more user friendly as it is less the user has to type.  More means more security.
+Look Ahead Window::
+  How many counters ahead should the server try and match the hash?  The default value is 1.  This exists to cover the case
+  where the user's counter gets ahead of the server's.  This can often happen as users often increment the counter
+  manually too many times by accident.  This value really should be increased to like a value of 10 or so.
+Initial Counter::
+  What is the value of the initial counter?
+
+