v1.0 Initial commit of project

vendor/robthree/twofactorauth/docs/_config.yml

@@ -0,0 +1,3 @@
+theme: jekyll-theme-minimal
+
+logo: https://raw.githubusercontent.com/RobThree/TwoFactorAuth/master/multifactorauthforeveryone.png

vendor/robthree/twofactorauth/docs/_layouts/post.html

@@ -0,0 +1,9 @@
+---
+layout: default
+---
+
+<a href="{{ site.baseurl }}">← contents</a>
+
+<h1>{{ page.title }}</h1>
+
+{{ content }}

vendor/robthree/twofactorauth/docs/assets/css/style.scss

@@ -0,0 +1,54 @@
+---
+---
+
+@import "{{ site.theme }}";
+
+// undo some of the theme to allow code samples to be wider
+header {
+	padding-right: 0;
+}
+@media print, screen and (min-width: 961px) {
+	header {
+		border: 1px solid #e5e5e5;
+		border-radius: 5px;
+		margin-bottom: 30px;
+		margin-right: 30px;
+		padding-top: 20px;
+		position: static;
+		text-align: center;
+	}
+	section {
+		float: none;
+		width: auto;
+	}
+	footer {
+		float: none;
+		position: static;
+	}
+}
+
+// ensure code samples can be really wide
+.language-php.highlighter-rouge {
+	clear: both;
+}
+
+// add missing consistency
+header img {
+	margin-bottom: 20px;
+}
+
+// quick navigation hack needs some spacing
+section > a:first-child {
+	display: block;
+	margin-bottom:45px;
+}
+
+// 100% width is treated like clear which makes it look bad
+table {
+	width: auto;
+}
+
+// reset document block whatever so the bullets aren't disturbed by the float
+ul {
+	overflow: hidden;
+}

vendor/robthree/twofactorauth/docs/getting-started.md

@@ -0,0 +1,63 @@
+---
+layout: post
+title: Getting Started
+---
+
+## 1. Installation
+
+The best way of making use of this project is by installing it with [composer](https://getcomposer.org/doc/01-basic-usage.md).
+
+```
+composer require robthree/twofactorauth
+```
+
+## 2. Create an instance
+
+`TwoFactorAuth` constructor requires an object able to provide a QR Code image. It is the only mandatory argument. This lets you select your preferred QR Code generator/library.
+
+See [QR code providers documentation](qr-codes.md) for more information about the different possibilites.
+
+Example code:
+
+```php
+use RobThree\Auth\TwoFactorAuth;
+use RobThree\Auth\Providers\Qr\BaconQrCodeProvider; // if using Bacon
+use RobThree\Auth\Providers\Qr\EndroidQrCodeProvider; // if using Endroid
+
+// using Bacon
+$tfa = new TwoFactorAuth(new BaconQrCodeProvider());
+// using Endroid
+$tfa = new TwoFactorAuth(new EndroidQrCodeProvider());
+// using a custom object implementing IQRCodeProvider interface
+$tfa = new TwoFactorAuth(new MyQrCodeProvider());
+// using named argument and a variable
+$tfa = new TwoFactorAuth(qrcodeprovider: $qrGenerator);
+```
+
+## 3. Shared secrets
+
+When your user is setting up two-factor, or multi-factor, authentication in your project, you can create a secret from the instance.
+
+```php
+$secret = $tfa->createSecret();
+```
+
+Once you have a secret, it can be communicated to the user however you wish.
+
+```php
+<p>Please enter the following code in your app: '<?php echo $secret; ?>'</p>
+```
+
+**Note:** until you have verified the user is able to use the secret properly, you should store the secret as part of the current session and not save the secret against your user record.
+
+## 4. Verifying
+
+Having provided the user with the secret, the best practice is to verify their authenticator app can create the appropriate code.
+
+```php
+$result = $tfa->verifyCode($secret, $_POST['verification']);
+```
+
+If `$result` is `true` then your user has been able to successfully record the `$secret` in their authenticator app and it has generated an appropriate code.
+
+You can now save the `$secret` to your user record and use the same `verifyCode` method each time they log in.

vendor/robthree/twofactorauth/docs/improved-code-verification.md

@@ -0,0 +1,32 @@
+---
+layout: post
+title: Improved Code Verification
+---
+
+When verifying codes that a user has entered, there are other optional arguments which can improve verification of the code.
+
+```php
+$result = $tfa->verifyCode($secret, $_POST['verification'], $discrepancy, $time, &$timeslice);
+```
+
+## Discrepancy (default 1)
+
+As the codes that are generated and accepted are consistent within a certain time window (i.e. a timeslice, 30 seconds long by default), it is very important that the server (and the users authenticator app) have the correct time (and date).
+
+The value of `$discrepancy` is the number of timeslices checked in **both** directions of the current one. So when the current time is `14:34:21`, the 'current timeslice' is `14:34:00` to `14:34:30`. If the default is left unchanged, we also verify the code against the timeslice of `14:33:30` to `14:34:00` and for `14:34:30` to `14:35:00`.
+
+This should be sufficient for most cases however you can increase it if you wish. It would be unwise for this to be too high as it could allow a code to be valid for long enough that it could be used fraudulently.
+
+## Time (default null)
+
+The second, `$time`, allows you to check a code for a specific point in time. This argument has no real practical use but can be handy for unit testing. The default value, `null`, means: use the current time.
+
+## Timeslice
+
+`$timeslice` returns a value by reference. The value returned is the timeslice that matched the code (if any) or `0`.
+
+You can store a timeslice alongside the secret and verify that any new timeslice is greater than the existing one.
+
+i.e. if `verifyCode` returns true _and_ the returned timeslice is greater than the last used timeslice for this user/secret then this is the first time the code has been used and you should now store the higher timeslice to verify that the user.
+
+This is an effective defense against a [replay attack](https://en.wikipedia.org/wiki/Replay_attack).

vendor/robthree/twofactorauth/docs/index.md

@@ -0,0 +1,18 @@
+---
+title: Contents
+---
+
+## [The Basics - Getting Started](getting-started.html)
+
+## Advanced Usage
+
+[QR Codes](qr-codes.html)
+- [QRServerProvider](qr-codes/qr-server.html)
+- [ImageChartsQRCodeProvider](qr-codes/image-charts.html)
+- [QRicketProvider](qr-codes/qrickit.html)
+- [EndroidQrCodeProvider](qr-codes/endroid.html) (and EndroidQrCodeWithLogoProvider)
+- [BaconQRCodeProvider](qr-codes/bacon.html)
+
+[Improved Code Verification](improved-code-verification.html)
+
+[Other Optional Configuration](optional-configuration.html)

vendor/robthree/twofactorauth/docs/optional-configuration.md

@@ -0,0 +1,47 @@
+---
+layout: post
+title: Optional Configuration
+---
+
+## Instance Configuration
+
+The instance (`new TwoFactorAuth()`) can only be configured by the constructor with the following optional arguments
+
+Argument          | Default value     | Use
+------------------|-------------------|-----
+`$issuer`         | `null`            | Will be displayed in the users app as the default issuer name when using QR code to import the secret
+`$digits`         | `6`               | The number of digits the resulting codes will be
+`$period`         | `30`              | The number of seconds a code will be valid
+`$algorithm`      | `Algorithm::Sha1` | The algorithm used (one of `Algorithm::Sha1`, `Algorithm::Sha256`, `Algorithm::Sha512`, `Algorithm::Md5`)
+`$qrcodeprovider` | `null`            | QR-code provider
+`$rngprovider`    | `null`            | Random Number Generator provider
+`$timeprovider`   | `null`            | Time provider
+
+**Note:** the default values for `$digits`, `$period`, and `$algorithm` provide the widest variety of support amongst common authenticator apps such as Google Authenticator. If you choose to use different values for these arguments you will likely have to instruct your users to use a specific app which supports your chosen configuration.
+
+### RNG providers
+
+Should you feel the need to use a CSPRNG different than `random_bytes()`, you can use the `rngprovider` argument of the constructor to provide an object implementing the [`IRNGProvider`](https://github.com/RobThree/TwoFactorAuth/blob/master/lib/Providers/Rng/IRNGProvider.php) interface.
+
+### Time providers
+
+These allow the TwoFactorAuth library to ensure the servers time is correct (or at least within a margin).
+
+You can use the `ensureCorrectTime()` method to ensure the hosts time is correct. By default this method will compare the hosts time (returned by calling `time()` on the `LocalMachineTimeProvider`) to the default `NTPTimeProvider` and `HttpTimeProvider`.
+
+**Note:** the `NTPTimeProvider` requires your PHP to have the ability to create sockets. If you do not have that ability and wish to use this function, you should pass an array with only an instance of `HttpTimeProvider`.
+
+Alternatively, you can pass an array of classes that implement the [`ITimeProvider` interface](https://github.com/RobThree/TwoFactorAuth/blob/master/lib/Providers/Time/ITimeProvider.php) to change this and specify the second argument, leniency in seconds (default: 5). An exception will be thrown if the time difference is greater than the leniency.
+
+Ordinarily, you should not need to monitor that the time on the server is correct in this way however if you choose to, we advise to call this method sparingly when relying on 3rd parties (which both the `HttpTimeProvider` and `NTPTimeProvider` do) or, if you need to ensure time is correct on a (very) regular basis to implement an `ITimeProvider` that is more efficient than the built-in ones (making use of a GPS signal for example).
+
+## Secret Configuration
+
+Secrets can be optionally configured with the following optional arguments
+
+Argument               | Default value | Use
+-----------------------|---------------|-----
+`$bits`                | `80`          | The number of bits (related to the length of the secret)
+`$requirecryptosecure` | `true`        | Whether you want to require a cryptographically secure source of random numbers
+
+**Note:** as above, these values provide the widest variety of support amongst common authenticator apps however you may choose to increase the value of `$bits` (160 or higher is recommended, see [RFC 4226 - Algorithm Requirements](https://tools.ietf.org/html/rfc4226#section-4)) as long as it is set to a multiple of 8.

vendor/robthree/twofactorauth/docs/qr-codes.md

@@ -0,0 +1,58 @@
+---
+layout: post
+title: QR Codes
+---
+
+An alternative way of communicating the secret to the user is through the use of [QR Codes](http://en.wikipedia.org/wiki/QR_code) which most if not all authenticator mobile apps can scan.
+
+This can avoid accidental typing errors and also pre-set some text values within the two factor authentication mobile application.
+
+You can display the QR Code as a base64 encoded image using the instance as follows, supplying the users name or other public identifier as the first argument
+
+````php
+<p>Scan the following image with your app:</p>
+<img src="<?php echo $tfa->getQRCodeImageAsDataUri('Bob Ross', $secret); ?>">
+````
+
+You can also specify a size as a third argument which is 200 by default.
+
+## Offline Providers
+
+[EndroidQrCodeProvider](qr-codes/endroid.md) and EndroidQrCodeWithLogoProvider
+
+[BaconQRCodeProvider](qr-codes/bacon.md)
+
+**Note:** offline providers may have additional PHP requirements in order to function, you should study what is required before trying to make use of them.
+
+## Custom Provider
+
+If you wish to make your own QR Code provider to reference another service or library, it must implement the [IQRCodeProvider interface](../lib/Providers/Qr/IQRCodeProvider.php).
+
+It is recommended to use similar constructor arguments as the included providers to avoid big shifts when trying different providers.
+
+Example:
+
+```php
+use RobThree\Auth\TwoFactorAuth;
+// using a custom object implementing IQRCodeProvider
+$tfa = new TwoFactorAuth(new MyQrCodeProvider());
+// using named argument and a variable
+$tfa = new TwoFactorAuth(qrcodeprovider: $qrGenerator);
+```
+
+## Online Providers
+
+**Warning:** Using an external service for generating QR codes encoding authentication secrets is **not** recommended! You should instead make use of the included offline providers listed above.
+
+* Gogr.me: [QRServerProvider](qr-codes/qr-server.md)
+* Image Charts: [ImageChartsQRCodeProvider](qr-codes/image-charts.md)
+* Qrickit: [QRicketProvider](qr-codes/qrickit.md)
+* Google Charts: [GoogleChartsQrCodeProvider](qr-codes/google-charts.md)
+
+Example:
+
+```php
+use RobThree\Auth\TwoFactorAuth;
+use RobThree\Auth\Providers\Qr\GoogleChartsQrCodeProvider;
+$tfa = new TwoFactorAuth(new GoogleChartsQrCodeProvider());
+```

vendor/robthree/twofactorauth/docs/qr-codes/bacon.md

@@ -0,0 +1,23 @@
+---
+layout: post
+title: bacon/bacon-qr-code
+---
+
+## Installation
+
+In order to use this provider, you will need to install the library at version 2 (or later) and its dependencies
+
+```
+composer require bacon/bacon-qr-code ^2.0
+```
+
+You will also need the PHP imagick extension **if** you aren't using the SVG format.
+
+## Optional Configuration
+
+Argument            | Default value
+--------------------|---------------
+`$borderWidth`      | `4`
+`$backgroundColour` | `'#ffffff'`
+`$foregroundColour` | `'#000000'`
+`$format`           | `'png'`

vendor/robthree/twofactorauth/docs/qr-codes/endroid.md

@@ -0,0 +1,37 @@
+---
+layout: post
+title: endroid/qr-code
+---
+
+## Installation
+
+In order to use this provider, you will need to install the library at version 3 and its dependencies
+
+```
+composer require endroid/qr-code ^3.0
+```
+
+You will also need the PHP gd extension installing.
+
+## Optional Configuration
+
+Argument                | Default value
+------------------------|---------------
+`$bgcolor`              | `'ffffff'`
+`$color`                | `'000000'`
+`$margin`               | `0`
+`$errorcorrectionlevel` | `'H'`
+
+## Logo
+
+If you make use of `EndroidQrCodeWithLogoProvider` then you have access to the `setLogo` function on the provider so you may add a logo to the centre of your QR code.
+
+```php
+use RobThree\Auth\Providers\Qr\EndroidQrCodeWithLogoProvider;
+
+$qrCodeProvider = new EndroidQrCodeWithLogoProvider();
+
+$qrCodeProvider->setLogo('/path/to/your/image');
+```
+
+You can see how to also set the size of the logo in the [source code](https://github.com/RobThree/TwoFactorAuth/blob/master/lib/Providers/Qr/EndroidQrCodeWithLogoProvider.php).

vendor/robthree/twofactorauth/docs/qr-codes/google-charts.md

@@ -0,0 +1,15 @@
+---
+layout: post
+title: QR GoogleCharts
+---
+
+See: https://developers.google.com/chart/infographics/docs/qr_codes
+
+## Optional Configuration
+
+Argument                | Default value
+------------------------|---------------
+`$verifyssl`            | `false`
+`$errorcorrectionlevel` | `'L'`
+`$margin`               | `4`
+`$encoding`             | `'UTF-8'`

vendor/robthree/twofactorauth/docs/qr-codes/image-charts.md

@@ -0,0 +1,16 @@
+---
+layout: post
+title: Image-Charts
+---
+
+## Optional Configuration
+
+Argument                | Default value
+------------------------|---------------
+`$verifyssl`            | `true`
+`$errorcorrectionlevel` | `'L'`
+`$margin`               | `4`
+
+`$verifyssl` is used internally to help guarantee the security of the connection. It is possible that where you are running the code from will have problems verifying an SSL connection so if you know this is not the case, you can supply `true`.
+
+The other parameters are passed to [Image-Charts](https://documentation.image-charts.com/qr-codes/) so you can refer to them for more detail on how the values are used.

vendor/robthree/twofactorauth/docs/qr-codes/qr-server.md

@@ -0,0 +1,20 @@
+---
+layout: post
+title: QR Server
+---
+
+## Optional Configuration
+
+Argument                | Default value
+------------------------|---------------
+`$verifyssl`            | `true`
+`$errorcorrectionlevel` | `'L'`
+`$margin`               | `4`
+`$qzone`                | `1`
+`$bgcolor`              | `'ffffff'`
+`$color`                | `'000000'`
+`$format`               | `'png'`
+
+`$verifyssl` is used internally to help guarantee the security of the connection. It is possible that where you are running the code from will have problems verifying an SSL connection so if you know this is not the case, you can supply `true`.
+
+The other parameters are passed to [goqr.me](http://goqr.me/api/doc/create-qr-code/) so you can refer to them for more detail on how the values are used.

vendor/robthree/twofactorauth/docs/qr-codes/qrickit.md

@@ -0,0 +1,15 @@
+---
+layout: post
+title: QRickit
+---
+
+## Optional Configuration
+
+Argument                | Default value
+------------------------|---------------
+`$errorcorrectionlevel` | `'L'`
+`$bgcolor`              | `'ffffff'`
+`$color`                | `'000000'`
+`$format`               | `'png'`
+
+The parameters are passed to [QRickit](http://qrickit.com/qrickit_apps/qrickit_api.php) so you can refer to them for more detail on how the values are used.