markenwerk/oath-server-suite

A collection of classes to provide second factor authentication like Yubico OTP (Yubikey), Oath (TOTP, HOTP, GoogleAuthenticator) server-side.

PHP Oath Server Suite

, _(*1)

A collection of classes to provide second factor authentication like Yubico OTP (Yubikey), Oath (TOTP, HOTP, GoogleAuthenticator) server-side., _(*2)

For more information about Oath check out https://openauthentication.org/., _(*3)

More information about TOTP (Time-based One-time Password Algorithm) can be found at Wikipedia., _(*4)

More information about HOTP (HMAC-based One-time Password Algorithm) can be found at Wikipedia., _(*5)

For more information about the Yubico OTP authentication mechanism read the „What is YubiKey OTP?“ article at https://developers.yubico.com/OTP/., _(*6)

Installation

```{json} { "require": { "chroma-x/oath-server-suite": "~4.0" } }, <sub>(*7)</sub>

## Usage

### Autoloading and namesapce

```{php}  
require_once('path/to/vendor/autoload.php');

Yubico OTP (YubiCloud)

To use Yubico OTP you need YubiCloud access. You can get free API credentials from https://upgrade.yubico.com/getapikey/., <sub>(*8)</sub>

Validating a Yubico one time password

```{php} use ChromaX\CommonException\NetworkException\Base\NetworkException;, <sub>(*9)</sub>

$otp = $_POST['otp']; $userPublicId = 'fetchedFromDatabaseOrSimilar';, <sub>(*10)</sub>

$validator = new OathServerSuite\Validation\YubicoOtp\Validator('yubiCloudClientId', 'yubiCloudSecretKey'); try { $validator->validate($otp, $userPublicId); if ($validator->isValid()) { // Validation was successful } else { // Validation failed } } catch (NetworkException $exception) { // Accessing the YubiCloud webservice failed. }, <sub>(*11)</sub>

---

### Oath – Google Authenticator style

#### Sharing the key name and secret

To allow authentication the client and server has to share a secret. Usually the server dices a secret and displays it alltogether with the key name and the authentication mechanism as a QR code.

[Google Authenticator](https://en.wikipedia.org/wiki/Google_Authenticator) and some other applications and hardware items – like the [Yubikey](https://www.yubico.com/products/yubikey-hardware/) – do not follow the standard by expecting the secrets not as hexadecimal but as [Base32](https://en.wikipedia.org/wiki/Base32) encoded data.

##### TOTP (Time-based One-time Password Algorithm)

```{php}
use ChromaX\OathServerSuite\SecretSharing\SharedSecretQrCodeProvider\SharedSecretQrCodeProvider;
use ChromaX\OathServerSuite\SecretSharing\SharedSecretUrlEncoder\TotpBase32SharedSecretUrlEncoder;
use ChromaX\QrCodeSuite\QrEncode\QrEncoder;

// Initialize Oath URL encoder for TOTP (Time-based One-time Password Algorithm)
$contentEncoder = new TotpBase32SharedSecretUrlEncoder();

// Setting the key name
$keyName = 'My Username';

// Setting the issuer name
$issuerName = 'Awesome Application';

// Setting a secret
// Attention: This is just an example value
// Use a random value of a proper length stored with your user credentials
$sharedSecret = openssl_random_pseudo_bytes(30);

// Getting the shared secret URL for usage wihtout QR code provision
$sharedSecretUrl = $contentEncoder->encode($keyName, $sharedSecret);

// Start QR code provision
// Initialize the QR code provider with Oath URL encoder for TOTP
$sharedSecretQrProvider = new SharedSecretQrCodeProvider(new TotpBase32SharedSecretUrlEncoder(), $keyName, $sharedSecret, $issuerName);

// Configure the QR code renderer for your needs
$sharedSecretQrProvider->getQrEncoder()
    ->setLevel(QrEncoder::QR_CODE_LEVEL_LOW)
    ->setTempDir('/path/to/a/writable/temp-dir');

// Persist the QR code PNG to the filesystem
$sharedSecretQrProvider->provideQrCode('/path/to/the/qrcode.png');

HOTP (HMAC-based One-time Password Algorithm)

```{php} use ChromaX\OathServerSuite\SecretSharing\SharedSecretQrCodeProvider\SharedSecretQrCodeProvider; use ChromaX\OathServerSuite\SecretSharing\SharedSecretUrlEncoder\HotpBase32SharedSecretUrlEncoder; use ChromaX\QrCodeSuite\QrEncode\QrEncoder;, <sub>(*12)</sub>

// Initialize Oath URL encoder for HOTP (HMAC-based One-time Password Algorithm) $contentEncoder = new HotpBase32SharedSecretUrlEncoder();, <sub>(*13)</sub>

// Setting the key name $keyName = 'My Username';, <sub>(*14)</sub>

// Setting the issuer name $issuerName = 'Awesome Application';, <sub>(*15)</sub>

// Setting a secret // Attention: This is just an example value // Use a random value of a proper length stored with your user credentials $sharedSecret = openssl_random_pseudo_bytes(30);, <sub>(*16)</sub>

// Getting the shared secret URL for usage wihtout QR code provision $sharedSecretUrl = $contentEncoder->encode($keyName, $sharedSecret);, <sub>(*17)</sub>

// Start QR code provision // Initialize the QR code provider with Oath URL encoder for HOTP $sharedSecretQrProvider = new SharedSecretQrCodeProvider(new HotpBase32SharedSecretUrlEncoder(), $keyName, $sharedSecret, $issuerName);, <sub>(*18)</sub>

// Configure the QR code renderer for your needs $sharedSecretQrProvider->getQrEncoder() ->setLevel(QrEncoder::QR_CODE_LEVEL_LOW) ->setTempDir('/path/to/a/writable/temp-dir');, <sub>(*19)</sub>

// Persist the QR code PNG to the filesystem $sharedSecretQrProvider->provideQrCode('/path/to/the/qrcode.png');, <sub>(*20)</sub>

#### Validating a Oath one time password

##### TOTP (Time-based One-time Password Algorithm)

```{php}
$totp = $_POST['totp'];
$sharedSecret = 'fetchedFromDatabaseOrSimilar';

$validator = new OathServerSuite\Validation\Oath\TotpValidator();
$validator->validate($totp, $sharedSecret);
if ($validator->isValid()) {
    // Validation was successful
} else {
    // Validation failed
}

HOTP (HMAC-based One-time Password Algorithm)

```{php} $hotp = $_POST['hotp']; $sharedSecret = 'fetchedFromDatabaseOrSimilar'; $counter = (int)'fetchedFromDatabaseOrSimilar';, <sub>(*21)</sub>

$validator = new OathServerSuite\Validation\Oath\HotpValidator(); $validator->validate($hotp, $sharedSecret, $counter); if ($validator->isValid()) { // Validation was successful } else { // Validation failed }, <sub>(*22)</sub>

---

### Oath – following the standard

#### Sharing the key name and secret

##### TOTP (Time-based One-time Password Algorithm)

```{php}
use ChromaX\OathServerSuite\SecretSharing\SharedSecretQrCodeProvider\SharedSecretQrCodeProvider;
use ChromaX\OathServerSuite\SecretSharing\SharedSecretUrlEncoder\TotpSharedSecretUrlEncoder;
use ChromaX\QrCodeSuite\QrEncode\QrEncoder;

// Initialize Oath URL encoder for TOTP (Time-based One-time Password Algorithm)
$contentEncoder = new TotpSharedSecretUrlEncoder();

// Setting the key name
$keyName = 'My Username';

// Setting the issuer name
$issuerName = 'Awesome Application';

// Setting a secret
// Attention: This is just an example value
// Use a random value of a proper length stored with your user credentials
$sharedSecret = openssl_random_pseudo_bytes(30);

// Getting the shared secret URL for usage wihtout QR code provision
$sharedSecretUrl = $contentEncoder->encode($keyName, $sharedSecret);

// Start QR code provision
// Initialize the QR code provider with Oath URL encoder for TOTP
$sharedSecretQrProvider = new SharedSecretQrCodeProvider(new TotpSharedSecretUrlEncoder(), $keyName, $sharedSecret, $issuerName);

// Configure the QR code renderer for your needs
$sharedSecretQrProvider->getQrEncoder()
    ->setLevel(QrEncoder::QR_CODE_LEVEL_LOW)
    ->setTempDir('/path/to/a/writable/temp-dir');

// Persist the QR code PNG to the filesystem
$sharedSecretQrProvider->provideQrCode('/path/to/the/qrcode.png');

HOTP (HMAC-based One-time Password Algorithm)

```{php} use ChromaX\OathServerSuite\SecretSharing\SharedSecretQrCodeProvider\SharedSecretQrCodeProvider; use ChromaX\OathServerSuite\SecretSharing\SharedSecretUrlEncoder\HotpSharedSecretUrlEncoder; use ChromaX\QrCodeSuite\QrEncode\QrEncoder;, <sub>(*23)</sub>

// Initialize Oath URL encoder for HOTP (HMAC-based One-time Password Algorithm) $contentEncoder = new HotpSharedSecretUrlEncoder();, <sub>(*24)</sub>

// Setting the key name $keyName = 'My Username';, <sub>(*25)</sub>

// Setting the issuer name $issuerName = 'Awesome Application';, <sub>(*26)</sub>

// Setting a secret // Attention: This is just an example value // Use a random value of a proper length stored with your user credentials $sharedSecret = openssl_random_pseudo_bytes(30);, <sub>(*27)</sub>

// Getting the shared secret URL for usage wihtout QR code provision $sharedSecretUrl = $contentEncoder->encode($keyName, $sharedSecret);, <sub>(*28)</sub>

// Start QR code provision // Initialize the QR code provider with Oath URL encoder for HOTP $sharedSecretQrProvider = new SharedSecretQrCodeProvider(new HotpSharedSecretUrlEncoder(), $keyName, $sharedSecret, $issuerName);, <sub>(*29)</sub>

// Configure the QR code renderer for your needs $sharedSecretQrProvider->getQrEncoder() ->setLevel(QrEncoder::QR_CODE_LEVEL_LOW) ->setTempDir('/path/to/a/writable/temp-dir');, <sub>(*30)</sub>

// Persist the QR code PNG to the filesystem $sharedSecretQrProvider->provideQrCode('/path/to/the/qrcode.png');, <sub>(*31)</sub>

#### Validating a Oath one time password

##### TOTP (Time-based One-time Password Algorithm)

```{php}
$totp = $_POST['totp'];
$sharedSecret = 'fetchedFromDatabaseOrSimilar';

$validator = new OathServerSuite\Validation\Oath\TotpValidator();
$validator->validate($totp, $sharedSecret);
if ($validator->isValid()) {
    // Validation was successful
} else {
    // Validation failed
}

HOTP (HMAC-based One-time Password Algorithm)

```{php} $hotp = $_POST['hotp']; $sharedSecret = 'fetchedFromDatabaseOrSimilar'; $counter = (int)'fetchedFromDatabaseOrSimilar';, <sub>(*32)</sub>

$validator = new OathServerSuite\Validation\Oath\HotpValidator(); $validator->validate($hotp, $sharedSecret, $counter); if ($validator->isValid()) { // Validation was successful } else { // Validation failed } ```, <sub>(*33)</sub>

Exception handling

PHP Oath Server Suite provides different exceptions – some provided by the PHP Common Exceptions project – for proper handling.
You can find more information about PHP Common Exceptions at Github., <sub>(*34)</sub>

Contribution

Contributing to our projects is always very appreciated.
But: please follow the contribution guidelines written down in the CONTRIBUTING.md document., <sub>(*35)</sub>

License

PHP Oath Server Suite is under the MIT license., <sub>(*36)</sub>