Getting Started with FIDO2

Getting Started
With WebAuthn
An Overview and Example

$whoami
● Researcher at Duo Labs
● W3C Invited Expert
● Cat Enthusiast

“Good security is not about what
you can prevent, but what you
can enable”

WebAuthn is a unicorn; it decreases
user friction and increases security.

Workshop Overview
● Setting up the code (5 Minutes)
● Introduction (10 Minutes)
● Credential Requests and Responses (15 - 20 Minutes)
● Unpacking Credential Responses (10 Minutes)
● Basic Validation Steps (15 Minutes)
● Q&A (Remaining Time + Lunch)

Key Takeaways
● High level understanding of the WebAuthn speciﬁcation and terminology
● How WebAuthn registration and login requests are structured and why
● How to parse and validate Credential Responses
● What attestation is and when to handle it
● How WebAuthn and FIDO2 Authentication make a more secure web

Things Not Covered (in this talk)
● Resident Keys
● Extensions
● Account Recovery Methods
Feel free to talk to me after!

We’re using webauthn.io
( Disclosure: I made it! With the help of many people! )

Core Library
$ git clone https://github.com/duo-labs/webauthn.git

If you want to use Go
$ go get github.com/duo-labs/webauthn.io
$ cd $GOPATH/src/github.com/duo-labs/webauthn.io
$ go build -i; ./webauthn.io

If you want to use Docker
$ git clone https://github.com/duo-labs/webauthn.io.git
$ cd webauthn.io
$ docker build -t webauthn.io .
$ docker run -rm -p 9005:9005 webauthn.io

If you just want to follow along
$docker run --rm -p 9005:9005 duolabs/webauthn.io

## Docker
$git clone https://github.com/duo-labs/webauthn.io.git
$cd webauthn.io
$docker build -t webauthn.io .
$docker run -rm -p 9005:9005 webauthn.io
## Golang
$go get github.com/duo-labs/webauthn.io
$cd $GOPATH/src/github.com/duo-labs/webauthn.io
$go build -i; ./webauthn.io
## Just the web app
$ docker run --rm -p 9005:9005 duolabs/webauthn.io

If you’re busy installing the requirements still...
Just go to webauthn.io

WebAuthn is a JavaScript API. It deﬁnes two
methods, create and get, that can be
used to register and assert ownership of
credential key pairs for a given website.

Introduction: Terms
Authenticator Client Relying Party

WebAuthnCTAP2
Introduction: Terms
Authenticator Client Relying Party

Introduction: Terms
CTAP1👏 IS 👏 U2F

WebAuthnCTAP2
FIDO2 Authentication
Introduction: Terms

Registration
ex.com
“Create an account for ex.com”

Registration
ex.com
“Here is some data and a list of
parameters the credential should
have”

Registration
“Given these options, try making a Credential”

PublicKeyCredential
Registration
ex.com
JSON(PublicKeyCredential)

Registration
ex.com
“The data I sent you is signed correctly and you
followed my options!”

Login (Assertion)
ex.com
“Log me in to ex.com”

Login (Assertion)
ex.com
ID
“Assert that you own the private key for this
credential with the given ID by signing this data”

Login (Assertion)
“Given these options and ID, prove you own it”

PublicKeyCredential
Login (Assertion)
ex.com

Login (Assertion)
ex.com
“This data is properly signed and proves you
own the private key”

The Registration Request
ex.com
“Here is some data and a list of
parameters the credential should
have”

webauthn/protocol/options.go
type PublicKeyCredentialCreationOptions struct {
Challenge Challenge
RelyingParty RelyingPartyEntity
User UserEntity
Parameters []CredentialParameter
AuthenticatorSelection AuthenticatorSelection
Timeout int
CredentialExcludeList []CredentialDescriptor
Attestation string
}
The Relying Party should
hand back a response that
looks like this
Credential Creation Options

Challenge Challenge
User UserEntity
Timeout int
Attestation string
}
These 3 are required, the
rest are optional but
recommended.
Credential Creation Options

Challenge Challenge
User UserEntity
Timeout int
Attestation string
}
● Generated by RP server-side.
● Helps prevent replay attacks
● Stored until the registration is
complete
○ As session data, in a DB, etc...
Challenge Parameter

webauthn/protocol/entities.go
type RelyingPartyEntity struct {
Name string // Organization Name most likely
Icon string // URL of a image/logo/avatar
ID string // usually the origin url (https://ex.com)
}
● Only the name is required
○ ID can be overridden
○ ex.com can create an account for
test.ex.com
○ not vice versa
● ID must have HTTPS
Relying Party Information

webauthn/protocol/entities.go
type UserEntity struct {
Name string // Readable name used by the RP
Icon string
DisplayName string // Readable name chosen by the user
ID []byte // The RP’s ID for the user.
}
● Name and ID are required
● Display Name is used for the
user’s notiﬁcation
User Information

type CredentialParameter struct {
Type string // Should be “public-key”
Algorithm string // A COSE Algorithm Identifier
}
● Only public-key is currently
defined as a type
● The algorithm field should be a
value defined in the IANA COSE
Registry
○ -7 for ES256, -257 for RS256, etc
Credential Parameters

type AuthenticatorSelection struct {
// Attachment could be “platform” or “cross-platform”
AuthenticatorAttachment string
Algorithm string // A COSE Algorithm Identifier
UserVerification string // A COSE Algorithm Identifier
}
● Nothing in this is required
● User Veriﬁcation will default to
preferred
Authenticator Selection

Challenge Challenge
User UserEntity
Timeout int
Attestation string
}
● The amount of time to allow the
authenticator/user to respond
● Unrequired
○ May actually be overridden
● Uses milliseconds
● Recommend 60 seconds
○ That’s 60000 milliseconds!
Timeout Parameter

Challenge Challenge
User UserEntity
Timeout int
Attestation string
}
● Allows us to exclude an
authenticator if it contains a
credential described in this list
● This is helpful for registering
multiple authenticators
● We’ll talk more about the
CredentialDescriptor
object later.
Credential Exclusion List

Challenge Challenge
User UserEntity
Timeout int
Attestation string
}
● Tells us if we want the
authenticator to attest the
credential
● Three conveyance types
○ Direct
○ Indirect
○ None
Attestation Conveyence

Registration Request
“Given these options, try making a Credential”

In JSON
Provided to
navigator.credentials.create()
Requested at line 105 in
webauthn.io/static/dist/js/webauthn.js
{"challenge":"InlQbas7et/4C0DVVW9/4qzoz2NuyM9c=",
"rp": {
"name": "webauthn.io",
"id": "webauthn.io"
},
"user": {
"name": "testuser",
"displayName": "testuser",
"id": "9AUAAAAAAAAAAA=="
},
"pubKeyCredParams": [
{
"type": "public-key",
"alg": -7
},
...
],
"authenticatorSelection": {
"authenticatorAttachment": "platform",
"requireResidentKey": false,
"userVerification": "preferred"
},
"timeout": 60000,
"attestation": "direct"
}
Registration Request

PublicKeyCredential
Registration Response
ex.com

In JSON
Provided from
navigator.credentials.create()
Returned at line 107 in
{
"id":"AOB4OhswadyGM0GHREg...",
"rawId":"AOB4OhswadyGM0GHREg...",
"type":"public-key",
"response":{
"attestationObject":"o2NmbXRm...",
"clientDataJSON":"eyJjaGFsbG..."
}
}

ex.com
“The data I sent you is signed correctly and you
followed my options!”

ex.com
+ ID

type PublicKeyCredentialRequestOptions struct {
Challenge Challenge
Timeout int
RelyingPartyId string
AllowedCredentials []CredentialDescriptor
UserVerification string
}
The Relying Party should
hand back a response that
looks like this
Credential Assertion Options

Challenge Challenge
Timeout int
}
● Challenge is the only
requirement!
○ Same structure as prior
Challenge Parameter

Challenge Challenge
Timeout int
}
● Same as in Creation
Request
Timeout Parameter

Challenge Challenge
Timeout int
}
● The URL of the RP
○ Can be inferred by client
Relying Party ID Attribute

Challenge Challenge
Timeout int
}
● List of Credential
Descriptions to allow for
● Should contain the
credentials registered to
the user for an RP
Allowed Credential List

type CredentialDescriptor struct {
Type string // Should be “public-key”
CredentialID []byte // Stored Credential ID
Transport []string // “usb”,“nfc”,“ble”,”internal”
}
● Type will be “public-key”
● Credential ID is the stored ID
● What transports the
authenticator should use assert
the credential.
○ Internal should be used if the
authenticator is built in to the
device.
Credential Descriptor

Challenge Challenge
Timeout int
}
● Should the user be verified by
the authenticator?
○ Required
○ Preferred
○ Discouraged
● User Verification == “Human”
Verification
● Defaults to preferred
● If set to required, client will
exclude ineligible authenticators
User Verification Requirements

In JSON
Provided to
navigator.credentials.get()
Requested at line 105 in
{
"publicKey": {
"challenge": "DTea9k7tF9waXg0LTbOVOEvm0unHoo=",
"timeout": 60000,
"rpId": "webauthn.io",
"allowCredentials": [
{
"id": "KWUeR0DoUAkpS5S3nHydoK..."
},
-- More Allowed Credentials --
{
"id": "i7yvlHv0YMF3BK81VeqIdW..."
}
]
}
Assertion Request

PublicKeyCredential
Assertion Response
ex.com

In JSON
Provided from
navigator.credentials.get()
Returned at line 107 in
{
"response":{
"authenticatorData":"o2NmbXRm...",
"clientDataJSON":"eyJjaGFsbG...",
"signature":"oASLKdlOMEIBaqs...",
"userHandle":"9AUAAAA...",
}
}
Assertion Response

Functions where we handle this data
● RequestNewCredential in webauthn.io/server/credential.go:17
○ Calls BeginRegistration in webauthn/webauthn/registration.go:19
● MakeNewCredential in webauthn.io/server/credential.go:66
○ Calls FinishRegistration in webauthn/webauthn/registration.go:105
● GetAssertion in webauthn.io/server/assertion.go:21
○ Calls BeginLogin in webauthn/webauthn/registration.go:25
● MakeAssertion in webauthn.io/server/assertion.go:57
○ Calls FinishLogin in webauthn/webauthn/registration.go:85

To Rebuild Your Code
## For Golang
## End the Go application (Ctrl-C)
$go run main.go
## For Docker
$docker down $DOCKER_ID // get ID with $docker ps
$docker build .
$docker run -p 9005:9005 --rm webauthn.io

{
"response":{
"attestationObject":"o2NmbXRm...",
"clientDataJSON":"eyJjaGFsbG..."
}
}
● Highlighted values contain all we
need
● URL Base 64 Encoded
● Parsed in webauthn/
○ webauthn/registration.go
○ protocol/credential.go
○ protocol/attestation.go

type CollectedClientData struct {
Type CeremonyType
Challenge string
Origin string
TokenBinding TokenBinding
}
Client Data
● Contains the type of event (ceremony)
○ webauthn.create
○ Webauthn.get
● The initial challenge
● The origin URL
○ According to the authenticator
● Token binding helps us bind the
session
● But how do we trust it?

Attestation
protocol/attestation.go:56

Attestation and Attestation Objects
● Attestation Objects are packed in CBOR
○ Concise Binary Object Representation
● The Attestation Signature (most of the time) gives us proof that
the authenticator actually created the credential
● Up to the developer to check trust roots (with services like
FIDO’s Metadata Service)
● Read the spec or look in webauthn for instructions

Should I Handle or Request Attestation?
● Are you…
○ A bank?
○ A government agency?
○ Often attacked by nation states?
○ Excited to use the FIDO Metadata Service?
● If not, you probably don’t need to do attestation.

{
"response":{
"authenticatorData":"o2NmbXRm...",
"clientDataJSON":"eyJjaGFsbG...",
"signature":"oASLKdlOMEIBaqs...",
"userHandle":"9AUAAAA...",
}
}
Assertion Response
● Client Data remains the same format
● Authenticator data instead of
Attestation data
● Signature != Attestation Signature
● Parsed in webauthn/
○ protocol/assertion.go:49

Validation in 3 parts
1. Validate the data from the RP
○ Request Type, Request Origin, Challenge, etc
2. Validate the data from the Authenticator
○ Signature, Attestation data, AAGUID
3. Validate the credential
○ Public Key Format, Signature

Validation
● Check out the veriﬁcation methods in webauthn/
○ protocol/credential.go
○ protocol/attestation.go
○ protocol/assertion.go

Thank you!
Twitter: @codekaiju
nsteele@duo.com

Getting Started with FIDO2

Recommended

Recommended

More Related Content

What's hot

What's hot (20)

Similar to Getting Started with FIDO2

Similar to Getting Started with FIDO2 (20)

More from FIDO Alliance

More from FIDO Alliance (20)

Recently uploaded

Recently uploaded (20)

Getting Started with FIDO2