diff --git a/README.md b/README.md index b8fcc75..dd1ac30 100644 --- a/README.md +++ b/README.md @@ -16,187 +16,21 @@ PHP library for [two-factor (or multi-factor) authentication](http://en.wikipedi Optionally, you may need: +* [sockets](https://www.php.net/manual/en/book.sockets.php) if you are using `NTPTimeProvider` * [endroid/qr-code](https://github.com/endroid/qr-code) if using `EndroidQrCodeProvider` or `EndroidQrCodeWithLogoProvider`. * [bacon/bacon-qr-code](https://github.com/Bacon/BaconQrCode) if using `BaconQrCodeProvider`. ## Installation -Run the following command: +The best way of installing this library is with composer: `php composer.phar require robthree/twofactorauth` -## Quick start - -If you want to hit the ground running then have a look at the [demo](demo/demo.php). It's very simple and easy! - ## Usage -Here are some code snippets that should help you get started... - -````php -// Create a TwoFactorAuth instance -$tfa = new RobThree\Auth\TwoFactorAuth('My Company'); -```` - -The TwoFactorAuth class constructor accepts 7 arguments (all optional): - -Argument | Default value | Use -------------------|---------------|-------------------------------------------------- -`$issuer` | `null` | Will be displayed in the app as issuer name -`$digits` | `6` | The number of digits the resulting codes will be -`$period` | `30` | The number of seconds a code will be valid -`$algorithm` | `sha1` | The algorithm used (one of `sha1`, `sha256`, `sha512`, `md5`) -`$qrcodeprovider` | `null` | QR-code provider (more on this later) -`$rngprovider` | `null` | Random Number Generator provider (more on this later) -`$timeprovider` | `null` | Time provider (more on this later) - -These arguments are all '`write once`'; the class will, for it's lifetime, use these values when generating / calculating codes. The number of digits, the period and algorithm are all set to values Google's Authenticator app uses (and supports). You may specify `8` digits, a period of `45` seconds and the `sha256` algorithm but the authenticator app (be it Google's implementation, Authy or any other app) may or may not support these values. Your mileage may vary; keep it on the safe side if you don't control which app your audience uses. - -### Step 1: Set up secret shared key - -When a user wants to setup two-factor auth (or, more correctly, multi-factor auth) you need to create a secret. This will be your **shared secret**. This secret will need to be entered by the user in their app. This can be done manually, in which case you simply display the secret and have the user type it in the app: - -````php -$secret = $tfa->createSecret(); -```` - -The `createSecret()` method accepts two arguments: `$bits` (default: `80`) and `$requirecryptosecure` (default: `true`). The former is the number of bits generated for the shared secret. Make sure this argument is a multiple of 8 and, again, keep in mind that not all combinations may be supported by all apps. Google authenticator seems happy with 80 and 160, the default is set to 80 because that's what most sites (that I know of) currently use; however a value of 160 or higher is recommended (see [RFC 4226 - Algorithm Requirements](https://tools.ietf.org/html/rfc4226#section-4)). The latter is used to ensure that the secret is cryptographically secure; if you don't care very much for cryptographically secure secrets you can specify `false` and use a **non**-cryptographically secure RNG provider. - -````php -// Display shared secret -

Please enter the following code in your app: ''

-```` - -Another, more user-friendly, way to get the shared secret into the app is to generate a [QR-code](http://en.wikipedia.org/wiki/QR_code) which can be scanned by the app. To generate these QR codes you can use any one of the built-in `QRProvider` classes: - -1. `QRServerProvider` (default) -2. `ImageChartsQRCodeProvider` -3. `QRicketProvider` -4. `EndroidQrCodeProvider` (requires `endroid/qr-code` to be installed) -5. `EndroidQrCodeWithLogoProvider` (same, but supporting embedded images) -6. `BaconQrCodeProvider` (requires `bacon/bacon-qr-code` to be installed) - -...or implement your own provider. To implement your own provider all you need to do is implement the `IQRCodeProvider` interface. You can use the built-in providers mentioned before to serve as an example or read the next chapter in this file. The built-in classes all use a 3rd (e.g. external) party (Image-charts, QRServer and QRicket) for the hard work of generating QR-codes (note: each of these services might at some point not be available or impose limitations to the number of codes generated per day, hour etc.). You could, however, easily use a project like [PHP QR Code](http://phpqrcode.sourceforge.net/) (or one of the [many others](https://packagist.org/search/?q=qr)) to generate your QR-codes without depending on external sources. Later on we'll [demonstrate](#qr-code-providers) how to do this. - -The built-in providers all have some provider-specific 'tweaks' you can 'apply'. Some provide support for different colors, others may let you specify the desired image-format etc. What they all have in common is that they return a QR-code as binary blob which, in turn, will be turned into a [data URI](http://en.wikipedia.org/wiki/Data_URI_scheme) by the `TwoFactorAuth` class. This makes it easy for you to display the image without requiring extra 'roundtrips' from browser to server and vice versa. - -````php -// Display QR code to user -

Scan the following image with your app:

-

-```` - -When outputting a QR-code you can choose a `$label` for the user (which, when entering a shared secret manually, will have to be chosen by the user). This label may be an empty string or `null`. Also a `$size` may be specified (in pixels, width == height) for which we use a default value of `200`. - -### Step 2: Verify secret shared key - -When the shared secret is added to the app, the app will be ready to start generating codes which 'expire' each '`$period`' number of seconds. To make sure the secret was entered, or scanned, correctly you need to verify this by having the user enter a generated code. To check if the generated code is valid you call the `verifyCode()` method: - -````php -// Verify code -$result = $tfa->verifyCode($_SESSION['secret'], $_POST['verification']); -```` - -If you do extra validations with your `$_POST` values, just make sure the code is still submitted as string - even if that's a numeric code, casting it to integer is unreliable. Also, you may need to store `$secret` in a `$_SESSION` or other persistent storage between requests. `verifyCode()` will return either `true` (the code was valid) or `false` (the code was invalid; no points for you!). - - The `verifyCode()` accepts, aside from `$secret` and `$code`, three more arguments, with the first being `$discrepancy`. Since TOTP codes are based on time("slices") it is very important that the server (but also client) have a correct date/time. But because the two *may* differ a bit we usually allow a certain amount of leeway. Because generated codes are valid for a specific period (remember the `$period` argument in the `TwoFactorAuth`'s constructor?) we usually check the period directly before and the period directly after the current time when validating codes. So when the current time is `14:34:21`, which results in a 'current timeslice' of `14:34:00` to `14:34:30` we also calculate/verify the codes for `14:33:30` to `14:34:00` and for `14:34:30` to `14:35:00`. This gives us a 'window' of `14:33:30` to `14:35:00`. The `$discrepancy` argument specifies how many periods (or: timeslices) we check in either direction of the current time. The default `$discrepancy` of `1` results in (max.) 3 period checks: -1, current and +1 period. A `$discrepancy` of `4` would result in a larger window (or: bigger time difference between client and server) of -4, -3, -2, -1, current, +1, +2, +3 and +4 periods. - -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 unittesting etc. The default value, `null`, means: use the current time. - -The third, `$timeslice`, is an out-argument; the value returned in `$timeslice` is the value of the timeslice that matched the code (if any). This value will be 0 when the code doesn't match and non-zero when the code matches. This value can be stored with the user and can be used to prevent replay-attacks. All you need to do is, on successful login, make sure `$timeslice` is greater than the previously stored timeslice. - -### Step 3: Store `$secret` with user and we're done! - -Ok, so now the code has been verified and found to be correct. Now we can store the `$secret` with our user in our database (or elsewhere) and whenever the user begins a new session we ask for a code generated by the authentication app of their choice. All we need to do is call `verifyCode()` again with the shared secret and the entered code and we know if the user is legit or not. - -Simple as 1-2-3. - -All we need is 3 methods and a constructor: - -````php -public function __construct( - $issuer = null, - $digits = 6, - $period = 30, - $algorithm = 'sha1', - RobThree\Auth\Providers\Qr\IQRCodeProvider $qrcodeprovider = null, - RobThree\Auth\Providers\Rng\IRNGProvider $rngprovider = null -); -public function createSecret($bits = 80, $requirecryptosecure = true): string; -public function getQRCodeImageAsDataUri($label, $secret, $size = 200): string; -public function verifyCode($secret, $code, $discrepancy = 1, $time = null): bool; -```` - -### QR-code providers - -As mentioned before, this library comes with five 'built-in' QR-code providers. This chapter will touch the subject a bit but most of it should be self-explanatory. The `TwoFactorAuth`-class accepts a `$qrcodeprovider` argument which lets you specify a built-in or custom QR-code provider. All five built-in providers do a simple HTTP request to retrieve an image using cURL and implement the [`IQRCodeProvider`](lib/Providers/Qr/IQRCodeProvider.php) interface which is all you need to implement to write your own QR-code provider. - -The default provider is the [`QRServerProvider`](lib/Providers/Qr/QRServerProvider.php) which uses the [goqr.me API](http://goqr.me/api/doc/create-qr-code/) to render QR-codes. Then we have the [`ImageChartsQRCodeProvider`](lib/Providers/Qr/ImageChartsQRCodeProvider.php) which uses the [image-charts.com replacement for Google Image Charts](https://image-charts.com) to render QR-codes and the [`QRicketProvider`](lib/Providers/Qr/QRicketProvider.php) which uses the [QRickit API](http://qrickit.com/qrickit_apps/qrickit_api.php). These three providers all inherit from a common (abstract) baseclass named [`BaseHTTPQRCodeProvider`](lib/Providers/Qr/BaseHTTPQRCodeProvider.php) because all three share the same functionality: retrieve an image from a 3rd party over HTTP. Finally, we have [`EndroidQrCodeProvider`](lib/Providers/Qr/EndroidQrCodeProvider.php), [`EndroidQrCodeWithLogoProvider`](lib/Providers/Qr/EndroidQrCodeWithLogoProvider.php) and [`BaconQrCodeProvider`](lib/Providers/Qr/BaconQrCodeProvider.php) which require an optional dependency to be installed to use (see Requirements section above), but will generate the QR codes locally. All five classes have constructors that allow you to tweak some settings and most, if not all, arguments should speak for themselves. If you're not sure which values are supported, click the links in this paragraph for documentation on the API's that are utilized by these classes. - -If you don't like any of the built-in classes because you don't want to rely on external resources for example or because you're paranoid about sending the TOTP secret to these 3rd parties (which is useless to them since they miss *at least one* other factor in the [MFA process](http://en.wikipedia.org/wiki/Multi-factor_authentication)), feel tree to implement your own. The `IQRCodeProvider` interface couldn't be any simpler. All you need to do is implement 2 methods: - -````php -getMimeType(); -getQRCodeImage($qrtext, $size); -```` - -The `getMimeType()` method should return the [MIME type](http://en.wikipedia.org/wiki/Internet_media_type) of the image that is returned by our implementation of `getQRCodeImage()`. In this example it's simply `image/png`. The `getQRCodeImage()` method is passed two arguments: `$qrtext` and `$size`. The latter, `$size`, is simply the width/height in pixels of the image desired by the caller. The first, `$qrtext` is the text that should be encoded in the QR-code. An example of such a text would be: - -`otpauth://totp/LABEL:alice@google.com?secret=JBSWY3DPEHPK3PXP&issuer=ISSUER` - -All you need to do is return the QR-code as binary image data and you're done. All parts of the `$qrtext` have been escaped for you (but note: you *may* need to escape the entire `$qrtext` just once more when passing the data to another server as GET-argument). - -Let's see if we can use [PHP QR Code](http://phpqrcode.sourceforge.net/) to implement our own, custom, no-3rd-parties-allowed-here, provider. We start with downloading the [required (single) file](https://github.com/t0k4rt/phpqrcode/blob/master/phpqrcode.php) and putting it in the directory where `TwoFactorAuth.php` is located as well. Now let's implement the provider: create another file named `myprovider.php` in the `Providers\Qr` directory and paste in this content: - -````php -createSecret(); -?> -

-```` - -Voilà. Couldn't make it any simpler. - -### RNG providers - -This library also comes with three 'built-in' RNG providers ([Random Number Generator](https://en.wikipedia.org/wiki/Random_number_generation)). The RNG provider generates a number of random bytes and returns these bytes as a string. These values are then used to create the secret. By default (no RNG provider specified) TwoFactorAuth will try to determine the best available RNG provider to use. It will, by default, try to use the [`CSRNGProvider`](lib/Providers/Rng/CSRNGProvider.php) for PHP7+ or the [`MCryptRNGProvider`](lib/Providers/Rng/MCryptRNGProvider.php); if this is not available/supported for any reason it will try to use the [`OpenSSLRNGProvider`](lib/Providers/Rng/OpenSSLRNGProvider.php) and if that is also not available/supported it will try to use the final RNG provider: [`HashRNGProvider`](lib/Providers/Rng/HashRNGProvider.php). Each of these providers use their own method of generating a random sequence of bytes. The first three (`CSRNGProvider`, `OpenSSLRNGProvider` and `MCryptRNGProvider`) return a [cryptographically secure](https://en.wikipedia.org/wiki/Cryptographically_secure_pseudorandom_number_generator) sequence of random bytes whereas the `HashRNGProvider` returns a **non-cryptographically secure** sequence. - -You can easily implement your own `RNGProvider` by simply implementing the `IRNGProvider` interface. Each of the 'built-in' RNG providers have some constructor arguments that allow you to 'tweak' some of the settings to use when creating the random bytes such as which source to use (`MCryptRNGProvider`) or which hashing algorithm (`HashRNGProvider`). I encourage you to have a look at some of the ['built-in' RNG providers](lib/Providers/Rng) for details and the [`IRNGProvider` interface](lib/Providers/Rng/IRNGProvider.php). - -### Time providers - -Another set of providers in this library are the Time Providers; this library provides three 'built-in' ones. The default Time Provider used is the [`LocalMachineTimeProvider`](lib/Providers/Time/LocalMachineTimeProvider.php); this provider simply returns the output of `Time()` and is *highly recommended* as default provider. The [`HttpTimeProvider`](lib/Providers/Time/HttpTimeProvider.php) executes a `HEAD` request against a given webserver (default: google.com) and tries to extract the `Date:`-HTTP header and returns it's date. Other url's/domains can be used by specifying the url in the constructor. The final Time Provider is the [`NTPTimeProvider`](lib/Providers/Time/NTPTimeProvider.php) which does an NTP request to a specified NTP server. - -You can easily implement your own `TimeProvider` by simply implementing the `ITimeProvider` interface. +For a quick start, have a look at the [getting started](https://robthree.github.io/TwoFactorAuth/getting-started.html) page or try out the [demo](demo/demo.php). -As to *why* these Time Providers are implemented: it allows the TwoFactorAuth library to ensure the hosts time is correct (or rather: 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`. You can pass an array of `ITimeProvider`s to change this and specify the `leniency` (second argument) allowed (default: 5 seconds). The method will throw when the TwoFactorAuth's timeprovider (which can be any `ITimeProvider`, see constructor) differs more than the given amount of seconds from any of the given `ITimeProviders`. 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 (like use a GPS signal). The `ensureCorrectTime()` method is mostly to be used to make sure the server is configured correctly. +If you need more in-depth information about the configuration available then you can read through the rest of [documentation](https://robthree.github.io/TwoFactorAuth). ## Integrations diff --git a/docs/_config.yml b/docs/_config.yml new file mode 100644 index 0000000..35c8b82 --- /dev/null +++ b/docs/_config.yml @@ -0,0 +1,3 @@ +theme: jekyll-theme-minimal + +logo: https://raw.githubusercontent.com/RobThree/TwoFactorAuth/master/multifactorauthforeveryone.png diff --git a/docs/_layouts/post.html b/docs/_layouts/post.html new file mode 100644 index 0000000..7d4c7d9 --- /dev/null +++ b/docs/_layouts/post.html @@ -0,0 +1,9 @@ +--- +layout: default +--- + +← contents + +

{{ page.title }}

+ +{{ content }} diff --git a/docs/assets/css/style.scss b/docs/assets/css/style.scss new file mode 100644 index 0000000..9a8d9ff --- /dev/null +++ b/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; +} diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 0000000..e25df8b --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,58 @@ +--- +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). + +``` +php composer.phar require robthree/twofactorauth +``` + +or if you have composer installed globally + +``` +composer require robthree/twofactorauth +``` + +## 2. Create an instance + +Now you can create an instance for use with your code + +```php +use RobThree\Auth\TwoFactorAuth; + +$tfa = new TwoFactorAuth(); +``` + +**Note:** if you are not using a framework that uses composer, you should [include the composer loader yourself](https://getcomposer.org/doc/01-basic-usage.md#autoloading) + +## 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 +

Please enter the following code in your app: ''

+``` + +**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. diff --git a/docs/improved-code-verification.md b/docs/improved-code-verification.md new file mode 100644 index 0000000..ae195f4 --- /dev/null +++ b/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). diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..a1cddaa --- /dev/null +++ b/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) diff --git a/docs/optional-configuration.md b/docs/optional-configuration.md new file mode 100644 index 0000000..c2bc5cd --- /dev/null +++ b/docs/optional-configuration.md @@ -0,0 +1,56 @@ +--- +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` | `'sha1'` | The algorithm used (one of `sha1`, `sha256`, `sha512`, `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 + +This library also comes with some [Random Number Generator (RNG)](https://en.wikipedia.org/wiki/Random_number_generation) providers. The RNG provider generates a number of random bytes and returns these bytes as a string. These values are then used to create the secret. By default (no RNG provider specified) TwoFactorAuth will try to determine the best available RNG provider to use in this order. + +1. [CSRNGProvider](https://github.com/RobThree/TwoFactorAuth/blob/master/lib/Providers/Rng/CSRNGProvider.php) for PHP7+ +2. [MCryptRNGProvider](https://github.com/RobThree/TwoFactorAuth/blob/master/lib/Providers/Rng/MCryptRNGProvider.php) where mcrypt is available +3. [OpenSSLRNGProvider](https://github.com/RobThree/TwoFactorAuth/blob/master/lib/Providers/Rng/OpenSSLRNGProvider.php) where openssl is available +4. [HashRNGProvider](https://github.com/RobThree/TwoFactorAuth/blob/master/lib/Providers/Rng/HashRNGProvider.php) **non-cryptographically secure** fallback + +Each of these RNG providers have some constructor arguments that allow you to tweak some of the settings to use when creating the random bytes. + +You can also implement your own by implementing the [`IRNGProvider` interface](https://github.com/RobThree/TwoFactorAuth/blob/master/lib/Providers/Rng/IRNGProvider.php). + +### 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. diff --git a/docs/qr-codes.md b/docs/qr-codes.md new file mode 100644 index 0000000..01e8dad --- /dev/null +++ b/docs/qr-codes.md @@ -0,0 +1,61 @@ +--- +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 users app. + +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 +

Scan the following image with your app:

+ +```` + +You can also specify a size as a third argument which is 200 by default. + +**Note:** by default, the QR code returned by the instance is generated from a third party across the internet. If the third party is encountering problems or is not available from where you have hosted your code, your user will likely experience a delay in seeing the QR code, if it even loads at all. This can be overcome with offline providers configured when you create the instance. + +## Online Providers + +[QRServerProvider](qr-codes/qr-server.html) (default) + +[ImageChartsQRCodeProvider](qr-codes/image-charts.html) + +[QRicketProvider](qr-codes/qrickit.html) + +## Offline Providers + +[EndroidQrCodeProvider](qr-codes/endroid.html) and EndroidQrCodeWithLogoProvider + +[BaconQRCodeProvider](qr-codes/bacon.html) + +**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](https://github.com/RobThree/TwoFactorAuth/blob/master/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. + +## Using a specific provider + +If you do not want to use the default QR code provider, you can specify the one you want to use when you create your instance. + +```php +use RobThree\Auth\TwoFactorAuth; + +$qrCodeProvider = new YourChosenProvider(); + +$tfa = new TwoFactorAuth( + null, + 6, + 30, + 'sha1', + $qrCodeProvider +); +``` + +As you create a new instance of your provider, you can supply any extra configuration there. diff --git a/docs/qr-codes/bacon.md b/docs/qr-codes/bacon.md new file mode 100644 index 0000000..cd41404 --- /dev/null +++ b/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'` diff --git a/docs/qr-codes/endroid.md b/docs/qr-codes/endroid.md new file mode 100644 index 0000000..ccd214d --- /dev/null +++ b/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\TwoFactorAuth\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). diff --git a/docs/qr-codes/image-charts.md b/docs/qr-codes/image-charts.md new file mode 100644 index 0000000..2d669cc --- /dev/null +++ b/docs/qr-codes/image-charts.md @@ -0,0 +1,16 @@ +--- +layout: post +title: Image-Charts +--- + +## Optional Configuration + +Argument | Default value +------------------------|--------------- +`$verifyssl` | `false` +`$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. diff --git a/docs/qr-codes/qr-server.md b/docs/qr-codes/qr-server.md new file mode 100644 index 0000000..b1ac546 --- /dev/null +++ b/docs/qr-codes/qr-server.md @@ -0,0 +1,20 @@ +--- +layout: post +title: QR Server +--- + +## Optional Configuration + +Argument | Default value +------------------------|--------------- +`$verifyssl` | `false` +`$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. diff --git a/docs/qr-codes/qrickit.md b/docs/qr-codes/qrickit.md new file mode 100644 index 0000000..4c022b9 --- /dev/null +++ b/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.