Documentation pretty much complete. Getting ready for 1.0.0 release.

Documentation/docs/AuthenticationKit.MutableUser.md

@@ -0,0 +1,36 @@
+# AuthenticationKit.MutableUser
+
+This interface aggregates [AuthenticationKit.User](AuthenticationKit.User.md), meaning all methods required by AuthenticationKit.User will also be required by AuthenticationKit.MutableUser.
+
+This interfaces should be implemented by a user class that can be modified. It is perfectly acceptable to use a single editable user class, as opposed to a mutable and immutable pair of classes.
+
+## Interface Methods
+
+<pre id="method.loginkey"><span style="font-family: 'source-code-pro', 'menlo', 'courier', monospace; color: #000000;"><span style="color: #0000FF;">Sub</span> LoginKey (<span style="color: #0000FF;">Assigns</span> Value <span style="color: #0000FF;">As</span> <span style="color: #0000FF;">Text</span>)</span></pre>
+Allows the login key to be changed for the user. If a user class does not allow editable login keys (not recommended) then simply leave this method empty.
+
+<pre id="method.setsecuritydetails"><span style="font-family: 'source-code-pro', 'menlo', 'courier', monospace; color: #000000;"><span style="color: #0000FF;">Sub</span> SetSecurityDetails (Iterations <span style="color: #0000FF;">As</span> UInteger, Algorithm <span style="color: #0000FF;">As</span> Xojo.Crypto.HashAlgorithms, ValidationHash <span style="color: #0000FF;">As</span> Xojo.Core.MemoryBlock, PasswordSalt <span style="color: #0000FF;">As</span> Xojo.Core.MemoryBlock, SecondFactorSalt <span style="color: #0000FF;">As</span> Xojo.Core.MemoryBlock)</span></pre>
+When changing the password for a user, new security details will be generated by the framework and passed to the user class via this method.
+
+`SecondFactorSalt` will be nil if two factor authentication is to be disabled. All other parameters are required and will be set.
+
+## Extension Methods
+
+These methods are supplied by the `AuthenticationKit` module automatically to all implementors of the interface.
+
+<pre id="method.setpassword"><span style="font-family: 'source-code-pro', 'menlo', 'courier', monospace; color: #000000;"><span style="color: #0000FF;">Function</span> SetPassword (<span style="color: #0000FF;">Extends</span> User <span style="color: #0000FF;">As</span> AuthenticationKit.MutableUser, Password <span style="color: #0000FF;">As</span> <span style="color: #0000FF;">Text</span>, Iterations <span style="color: #0000FF;">As</span> UInteger, Algorithm <span style="color: #0000FF;">As</span> Xojo.Crypto.HashAlgorithms) <span style="color: #0000FF;">As</span> AuthenticationKit.Token()</span></pre>
+Change the user's password with two factor authentication disabled.
+
+- `Password` is the user's password.
+- `Iterations` is the number of PBKDF2 iterations used to hash the password. The same password hashed with different iteration counts will produce different hashes. More iterations requires more cpu time, making the hash harder to break. Every server is different, so best practice is to experiment with iteration counts to produce a desired execution time.
+- `Algorithm` is the hashing algorithm to use. The algorithm will dictate the length of the hashes produced, so if possible, use SHA-512.
+
+<pre><span style="font-family: 'source-code-pro', 'menlo', 'courier', monospace; color: #000000;"><span style="color: #0000FF;">Function</span> SetPassword (<span style="color: #0000FF;">Extends</span> User <span style="color: #0000FF;">As</span> AuthenticationKit.MutableUser, Password <span style="color: #0000FF;">As</span> <span style="color: #0000FF;">Text</span>, Iterations <span style="color: #0000FF;">As</span> UInteger, Algorithm <span style="color: #0000FF;">As</span> Xojo.Crypto.HashAlgorithms, <span style="color: #0000FF;">ByRef</span> Generator <span style="color: #0000FF;">As</span> AuthenticationKit.TwoFactorProfile) <span style="color: #0000FF;">As</span> AuthenticationKit.Token()</span></pre>
+Change the user's password with two factor authentication enabled.
+
+- `Password`, `Iterations`, and `Algorithm` are the same as the other method signature.
+- `Generator` is the [AuthenticationKit.TwoFactorProfile](AuthenticationKit.TwoFactorProfile.md) to be used. If `Nil`, a new generator will be created and used.
+
+## See Also
+
+[AuthenticationKit.User](AuthenticationKit.User.md)

Documentation/docs/AuthenticationKit.Token.md

@@ -0,0 +1,19 @@
+# AuthenticationKit.Token
+
+This class represents a hash and salt pair that may belong to a user's password, or may be false data.
+
+## Constructors
+
+<pre><span style="font-family: 'source-code-pro', 'menlo', 'courier', monospace; color: #000000;">ByteCount <span style="color: #0000FF;">As</span> UInteger</span></pre>
+Create a false token.
+
+<pre><span style="font-family: 'source-code-pro', 'menlo', 'courier', monospace; color: #000000;">Hash <span style="color: #0000FF;">As</span> Xojo.Core.MemoryBlock, Salt <span style="color: #0000FF;">As</span> Xojo.Core.MemoryBlock</span></pre>
+Create a token with the provided unencoded hash and salt.
+
+## Properties
+
+<pre id="property.hash"><span style="font-family: 'source-code-pro', 'menlo', 'courier', monospace; color: #000000;">Hash <span style="color: #0000FF;">As</span> Xojo.Core.MemoryBlock</span></pre>
+The unencoded hash bytes.
+
+<pre id="property.salt"><span style="font-family: 'source-code-pro', 'menlo', 'courier', monospace; color: #000000;">Salt <span style="color: #0000FF;">As</span> Xojo.Core.MemoryBlock</span></pre>
+The unencoded salt bytes.

Documentation/docs/AuthenticationKit.TwoFactorProfile.md

@@ -0,0 +1,40 @@
+# AuthenticationKit.TwoFactorProfile
+
+This is the class responsible for creating and validating [time-based one-time passwords](https://en.wikipedia.org/wiki/Time-based_One-time_Password_Algorithm) (TOTPs).
+
+Be aware that the most popular authenticator, Google Authenticator, does not respect most changes to the default properties. Google Authenticator will still read a provisioning uri with non-default values, but will not generate matching codes. For this reason, it is recommended that all properties be left at their default values.
+
+## Constructors
+
+<pre><span style="font-family: 'source-code-pro', 'menlo', 'courier', monospace; color: #000000;">Secret <span style="color: #0000FF;">As</span> Xojo.Core.MemoryBlock</span></pre>
+The unencoded secret shared between the server and the user.
+
+## Methods
+
+<pre id="method.generatecode"><span style="font-family: 'source-code-pro', 'menlo', 'courier', monospace; color: #000000;"><span style="color: #0000FF;">Function</span> GenerateCode () <span style="color: #0000FF;">As</span> UInteger</span></pre>
+Generate a password for the current time.
+
+<pre><span style="font-family: 'source-code-pro', 'menlo', 'courier', monospace; color: #000000;"><span style="color: #0000FF;">Function</span> GenerateCode (AtTime <span style="color: #0000FF;">As</span> Xojo.Core.Date) <span style="color: #0000FF;">As</span> UInteger</span></pre>
+Generate a password for the time provided by `AtTime`.
+
+<pre id="method.provisioninguri"><span style="font-family: 'source-code-pro', 'menlo', 'courier', monospace; color: #000000;"><span style="color: #0000FF;">Function</span> ProvisioningURI (Label <span style="color: #0000FF;">As</span> <span style="color: #0000FF;">Text</span>, Issuer <span style="color: #0000FF;">As</span> <span style="color: #0000FF;">Text</span> = <span style="color: #6600FE;">&quot;&quot;</span>) <span style="color: #0000FF;">As</span> <span style="color: #0000FF;">Text</span></span></pre>
+Create a [provisioning uri](https://github.com/google/google-authenticator/wiki/Key-Uri-Format) that can be consumed by an authenticator. This is commonly encoded into a QR code that can be read by a device's camera.
+
+`Label` is usually the account name to be associated with the profile. `Issuer` is the website or company issuing the profile. Although the `Issuer` is not required, it is strongly recommended.
+
+<pre id="method.secret"><span style="font-family: 'source-code-pro', 'menlo', 'courier', monospace; color: #000000;"><span style="color: #0000FF;">Function</span> Secret () <span style="color: #0000FF;">As</span> Xojo.Core.MemoryBlock</span></pre>
+The unencoded secret key used to generate unique codes.
+
+<pre id="method.verifycode"><span style="font-family: 'source-code-pro', 'menlo', 'courier', monospace; color: #000000;"><span style="color: #0000FF;">Function</span> VerifyCode (Code <span style="color: #0000FF;">As</span> UInteger) <span style="color: #0000FF;">As</span> <span style="color: #0000FF;">Boolean</span></span></pre>
+Verify that `Code` is valid for the current time. Also checks both the previous code and next code to help alleviate clock synchronization and other user timing issues.
+
+## Properties
+
+<pre id="property.digest"><span style="font-family: 'source-code-pro', 'menlo', 'courier', monospace; color: #000000;">Digest <span style="color: #0000FF;">As</span> Xojo.Crypto.HashAlgorithms</span></pre>
+The hash algorithm that should be used. Valid values are SHA-1, SHA-256, and SHA-512. Other values will trigger a Xojo.Core.InvalidArgumentException. Default is SHA-1. *Google Authenticator ignores this value and uses SHA-1 instead.*
+
+<pre id="property.digits"><span style="font-family: 'source-code-pro', 'menlo', 'courier', monospace; color: #000000;">Digits <span style="color: #0000FF;">As</span> UInteger</span></pre>
+The number of digits of the generated passwords. Valid values are 6 and 8. Other values will trigger a Xojo.Core.InvalidArgumentException. Default is 6. *Google Authenticator ignores this value and uses 6 instead.*
+
+<pre id="property.period"><span style="font-family: 'source-code-pro', 'menlo', 'courier', monospace; color: #000000;">Period <span style="color: #0000FF;">As</span> Xojo.Core.DateInterval</span></pre>
+The number of seconds each password should be valid for. Default is 30. *Google Authenticator ignores this value and uses 30 instead.*

Documentation/docs/AuthenticationKit.User.md

@@ -0,0 +1,33 @@
+# AuthenticationKit.User
+
+A class which is used to describe user login details must implement the AuthenticationKit.User interface. This interface only provides access to details, but does not allow editing of details. An editable user class should implement [AuthenticationKit.MutableUser](AuthenticationKit.MutableUser.md) instead.
+
+## Interface Methods
+
+<pre id="method.algorithm"><span style="font-family: 'source-code-pro', 'menlo', 'courier', monospace; color: #000000;"><span style="color: #0000FF;">Function</span> Algorithm () <span style="color: #0000FF;">As</span> Xojo.Crypto.HashAlgorithms</span></pre>
+Return the hash algorithm used. Only SHA-1, SHA-256, and SHA-512 algorithms are acceptable values.
+
+<pre id="method.iterations"><span style="font-family: 'source-code-pro', 'menlo', 'courier', monospace; color: #000000;"><span style="color: #0000FF;">Function</span> Iterations () <span style="color: #0000FF;">As</span> UInteger</span></pre>
+Return the number of PBKDF2 repeats used to generate hashes.
+
+<pre id="method.loginkey"><span style="font-family: 'source-code-pro', 'menlo', 'courier', monospace; color: #000000;"><span style="color: #0000FF;">Function</span> LoginKey () <span style="color: #0000FF;">As</span> <span style="color: #0000FF;">Text</span></span></pre>
+Return the user's login key. It is recommended that the login key not the user's email address or visible to other users at all. An ideal user class will have a login key which is private, and a user name which is public. However, this is by no means a requirement. The returned value should be what the user uses to sign in with.
+
+<pre id="method.passwordsalt"><span style="font-family: 'source-code-pro', 'menlo', 'courier', monospace; color: #000000;"><span style="color: #0000FF;">Function</span> PasswordSalt () <span style="color: #0000FF;">As</span> Xojo.Core.MemoryBlock</span></pre>
+Return a `Xojo.Core.MemoryBlock` of the bytes used as the password's salt.
+
+<pre id="method.secondfactorsalt"><span style="font-family: 'source-code-pro', 'menlo', 'courier', monospace; color: #000000;"><span style="color: #0000FF;">Function</span> SecondFactorSalt () <span style="color: #0000FF;">As</span> Xojo.Core.MemoryBlock</span></pre>
+Return a `Xojo.Core.MemoryBlock` of the bytes used as the two factor authentication token's salt.
+
+<pre id="method.twofactorenabled"><span style="font-family: 'source-code-pro', 'menlo', 'courier', monospace; color: #000000;"><span style="color: #0000FF;">Function</span> TwoFactorEnabled () <span style="color: #0000FF;">As</span> <span style="color: #0000FF;">Boolean</span></span></pre>
+Return `True` if two factor authentication is enabled.
+
+<pre id="method.userid"><span style="font-family: 'source-code-pro', 'menlo', 'courier', monospace; color: #000000;"><span style="color: #0000FF;">Function</span> UserID () <span style="color: #0000FF;">As</span> <span style="color: #0000FF;">Auto</span></span></pre>
+Return a unique identifier for the user. This may be a uuid, an integer id, the user's username.... whatever immutable value is used to uniquely identify a user.
+
+<pre id="method.validationhash"><span style="font-family: 'source-code-pro', 'menlo', 'courier', monospace; color: #000000;"><span style="color: #0000FF;">Function</span> ValidationHash () <span style="color: #0000FF;">As</span> Xojo.Core.MemoryBlock</span></pre>
+Return the validation hash provided to the AuthenticationKit.MutableUser.SetSecurityDetails method.
+
+## See Also
+
+[AuthenticationKit.MutableUser](AuthenticationKit.MutableUser.md)

Documentation/docs/AuthenticationKit.Validator.md

@@ -26,9 +26,9 @@ An alias of the `Save` method which accepts only an array of `Tokens`.
 <pre><span style="font-family: 'source-code-pro', 'menlo', 'courier', monospace; color: #000000;"><span style="color: #0000FF;">Function</span> Save (<span style="color: #0000FF;">Extends</span> Validator <span style="color: #0000FF;">As</span> AuthenticationKit.Validator, User <span style="color: #0000FF;">As</span> AuthenticationKit.User, Tokens() <span style="color: #0000FF;">As</span> AuthenticationKit.Token) <span style="color: #0000FF;">As</span> <span style="color: #0000FF;">Boolean</span></span></pre>
 An alias of the `Save` method which accepts a single `User` and an array of `Tokens`.
 
-<pre id="validatepassword"><span style="font-family: 'source-code-pro', 'menlo', 'courier', monospace; color: #000000;"><span style="color: #0000FF;">Function</span> ValidatePassword (<span style="color: #0000FF;">Extends</span> Validator <span style="color: #0000FF;">As</span> AuthenticationKit.Validator, User <span style="color: #0000FF;">As</span> AuthenticationKit.User, Password <span style="color: #0000FF;">As</span> <span style="color: #0000FF;">Text</span>, <span style="color: #0000FF;">ByRef</span> Generator <span style="color: #0000FF;">As</span> AuthenticationKit.SecondFactorGenerator) <span style="color: #0000FF;">As</span> <span style="color: #0000FF;">Boolean</span></span></pre>
-Test `Password` against `User`. Returns `True` if the password matches. `Generator` is a `ByRef` reference to a [AuthenticationKit.SecondFactorGenerator](AuthenticationKit.SecondFactorGenerator.md) that will be set to valid instance if the user has two factor authentication enabled, or set to nil if not enabled.
+<pre id="validatepassword"><span style="font-family: 'source-code-pro', 'menlo', 'courier', monospace; color: #000000;"><span style="color: #0000FF;">Function</span> ValidatePassword (<span style="color: #0000FF;">Extends</span> Validator <span style="color: #0000FF;">As</span> AuthenticationKit.Validator, User <span style="color: #0000FF;">As</span> AuthenticationKit.User, Password <span style="color: #0000FF;">As</span> <span style="color: #0000FF;">Text</span>, <span style="color: #0000FF;">ByRef</span> Generator <span style="color: #0000FF;">As</span> AuthenticationKit.TwoFactorProfile) <span style="color: #0000FF;">As</span> <span style="color: #0000FF;">Boolean</span></span></pre>
+Test `Password` against `User`. Returns `True` if the password matches. `Generator` is a `ByRef` reference to a [AuthenticationKit.TwoFactorProfile](AuthenticationKit.TwoFactorProfile.md) that will be set to valid instance if the user has two factor authentication enabled, or set to nil if not enabled.
 
 ## See Also
 
-[AuthenticationKit.Token](AuthenticationKit.Token.md), [AuthenticationKit.SecondFactorGenerator](AuthenticationKit.SecondFactorGenerator.md)
+[AuthenticationKit.Token](AuthenticationKit.Token.md), [AuthenticationKit.TwoFactorProfile](AuthenticationKit.TwoFactorProfile.md)