Create Params
Last updated
Last updated
This section explain you how to create the json to send to the client browser.
First of all, you need to instantiate the client
<?php
use Svgta\WebAuthn\client;
$webauthn = new client();
You must defined the Relying Party (your server). The exemple show all options :
$webauthn->rp->set(
icon: 'data:image/png;base64,iVBORw0KGgoAAA...',
name: 'My wonderful project',
id: 'myproject.tld'
);
Explanation :
icon (optional) : must be an image base64 encoded
name (required) : the name of you app
id (optional) : hostname of you project. If not set, the library take the hostname of the server
You are maybe on an url like : https://reg.myproject.tld. You can set the id with theses values :
reg.myproject.tld
myproject.tld
Using myproject.tld for the id can be useful if the authentication process is on https://auth.myproject.tld
You have to defined the user who wants to create a registration.
$webauthn->user->set(
name: '@svgta',
id: 'userUniqueId',
displayName: 'Super Vegeta',
icon : 'data:image/png;base64,iVBORw0KGgoAAA...'
);
Explanation :
name (required) : the name of the user. You may avoid to use the user email
id (optional) : the library will create an uuid for it if not set
displayName (optional) : if not set, the library use the name
icon (optional) : must be an image base64 encoded
For privacy reasons, it is not recommended using the e-mail as username.
You have to list the signg algorithms you want to use for your application.
You must give the list in your preference ordrer. Your device will then take the first one that it cans handle with. Example :
$webauthn->pubKeyCredParams->add('EDDSA');
$webauthn->pubKeyCredParams->add('ES256');
$webauthn->pubKeyCredParams->add('RS512');
$webauthn->pubKeyCredParams->add('RS256');
// OR, this is the same thing
$webauthn->pubKeyCredParams->add(-8);
$webauthn->pubKeyCredParams->add(-7);
$webauthn->pubKeyCredParams->add(-259);
$webauthn->pubKeyCredParams->add(-257);
// Another method, with all parameters
$webauthn->pubKeyCredParams->add('EDDSA', 'public-key');
$webauthn->pubKeyCredParams->add('ES256', 'public-key');
$webauthn->pubKeyCredParams->add('RS512', 'public-key');
$webauthn->pubKeyCredParams->add('RS256', 'public-key');
Then, the parameters are :
alg (required) : the algorithm you want to use (string or integer)
type (optional) : the type of key. By default public-key
To have the list of algorithms supported by the library, use pubKeyCredParams::getAlgList()
:
echo json_encode($webauthn->pubKeyCredParams::getAlgList(), JSON_PRETTY_PRINT);
As result, you will have someting like this :
{
"ES256": -7,
"ES256K": -46,
"ES384": -35,
"ES512": -36,
"EDDSA": -8,
"ED256": -260,
"ED512": -261,
"PS256": -37,
"PS384": -38,
"PS512": -39,
"RS256": -257,
"RS384": -258,
"RS512": -259,
"RS1": -65535
}
Now, you will defined how you will converse with the device. You have to set :
You don't have to defined the requireResidentKey ; the library does the job with your inputs.
Three possible options :
required
discouraged
preferred
$webauthn->userVerification->required();
// OR
$webauthn->userVerification->discouraged();
// OR
$webauthn->userVerification->preferred();
Three possible options :
required
discouraged
preferred
$webauthn->residentKey->required();
// OR
$webauthn->residentKey->discouraged();
// OR
$webauthn->residentKey->preferred();
Thee possible options :
all
cross_platform
platform
$webauthn->authenticatorAttachment->all();
// OR
$webauthn->authenticatorAttachment->cross_platform();
// OR
$webauthn->authenticatorAttachment->platform();
Four possible options :
none
indirect
direct
entreprise
$webauthn->attestation->none();
// OR
$webauthn->attestation->indirect();
// OR
$webauthn->attestation->direct();
// OR
$webauthn->attestation->enterprise();
You want to avoid some devices. For example, to not authorize a user to use the same devices he used to do a previous registration.
$webauthn->excludeCredentials->add('8EX0yiDLK8V3RZ0Cu-FQAgfs63JOl9vXLICwAyuYpCawD9km-YXsPLVm4y4Axeqn');
$webauthn->excludeCredentials->add('another key');
the method allow 3 arguments :
id (required) : the id of the key defined by the library as publicKeyCredentialId
type (optional): by default it's set to public-key
transports (optional) : it's an array. By default the array is empty
By default, the timeout is 300000. You can set another timeout like that :
webauthn->timeout('5000');
If the timeout is to big or to low, you will get in your server logs a message like that :
.... PHP message: Svgta Lib Alert: The recommended range for timeout is : 30000 milliseconds to 600000 milliseconds
The challenge is generated by the library. Nothing to do for you.
Now, you just need to get the json to send to the client. For example :
header('Content-Type: application/json; charset=utf-8');
echo $webauthn->register()->toJson();
The session store now all the informations to deal with the response of the client.
You may want the user informations without parsing this json to send to the client. You can get it by two ways, it will be seen in the next step of registration process.
code :
<?php
use Svgta\WebAuthn\client;
require dirname(__FILE__, 2) . '/vendor/autoload.php';
header('Content-Type: application/json; charset=utf-8');
$webauthn = new client();
$webauthn->rp->set(
name: 'My wonderful project',
);
$webauthn->user->set(
name: '@svgta'
);
echo $webauthn->register()->toJson();
Result :
{
"rp": {
"name": "My wonderful project",
"id": "myProject.tld"
},
"user": {
"name": "@svgta",
"id": "N2NiZjk1NzktY...",
"displayName": "@svgta"
},
"challenge": "5BWeonlacolrgA6AsFBGna2DrsrvjPlIFl9EA8ivxuG2O6kG1ozxGeZNvW9zpb820J_eLUhpstD3bWiu2yd6-g",
"pubKeyCredParams": [
{
"type": "public-key",
"alg": -7
},
{
"type": "public-key",
"alg": -257
}
],
"timeout": 300000,
"excludeCredentials": [
{
"type": "public-key",
"id": "8EX0yiDLK8V3RZ0Cu-FQAgfs63JOl9vXLICwAyuYpCawD9km-YXsPLVm4y4Axeqn"
}
],
"authenticatorSelection": {
"requireResidentKey": false,
"userVerification": "preferred",
"residentKey": "preferred"
},
"attestation": "none"
}
It's may be not what you want. It depends of the security level you need for your application.
Code :
<?php
use Svgta\WebAuthn\client;
require dirname(__FILE__, 2) . '/vendor/autoload.php';
header('Content-Type: application/json; charset=utf-8');
$webauthn = new client();
$webauthn->pubKeyCredParams->add('EDDSA');
$webauthn->pubKeyCredParams->add('RS256');
$webauthn->rp->set(
name: 'My wonderful project',
);
$webauthn->user->set(
name: '@svgta'
);
$webauthn->userVerification->required();
$webauthn->authenticatorAttachment->cross_platform();
$webauthn->residentKey->required();
$webauthn->attestation->direct();
$webauthn->excludeCredentials->add('8EX0yiDLK8V3RZ0Cu-FQAgfs63JOl9vXLICwAyuYpCawD9km-YXsPLVm4y4Axeqn');
echo $webauthn->register()->toJson();
Result :
{
"rp": {
"name": "My wonderful project",
"id": "webauthn.a6uqvj6wsxqfnfkxqsggmnkiay5ebhil67isjmjpqi7hnxguyq3jqhad.onion"
},
"user": {
"name": "@svgta",
"id": "YzQ4M2IyMDYtMGQ0YS00Yjg3LWIxN2YtMDNiOTZkYmI3Mjdl",
"displayName": "@svgta"
},
"challenge": "V4kSuyHdTcJ6VP8wEF_L-NAkwaMnhj0I6GSqsOQfLnRERmsYc1L-6djVSJvifLg0kBZvrcX-RkOGFwq3K-Uzog",
"pubKeyCredParams": [
{
"type": "public-key",
"alg": -8
},
{
"type": "public-key",
"alg": -257
}
],
"timeout": 300000,
"excludeCredentials": [
{
"type": "public-key",
"id": "8EX0yiDLK8V3RZ0Cu-FQAgfs63JOl9vXLICwAyuYpCawD9km-YXsPLVm4y4Axeqn"
}
],
"authenticatorSelection": {
"requireResidentKey": true,
"userVerification": "required",
"residentKey": "required",
"authenticatorAttachment": "cross-platform"
},
"attestation": "direct"
}