Skip to content

Latest commit

 

History

History
129 lines (86 loc) · 7.11 KB

5-u2f.md

File metadata and controls

129 lines (86 loc) · 7.11 KB
Raw

Universal Two-Factor Authentication using U2F

FIDO (Fast IDentity Online) U2F (Universal 2nd Factor) is a standard for two-factor authentication. It is extended and superseded by FIDO2, but still widely used.

The applet requires an attestation certificate. This certificate can be a default one, or generated by you, or an official one signed by a company like Vivokey or Yubico. You don't want to generate a unique certificate for each token, because that would make the tokens uniquely identifiable, leading to privacy concerns.

The attestation certificate is used to sign certificates for transport when you register with a service. The token manufacturer (e.g. Vivokey) can also use this certificate (which they sign using their certificate authority) to validate the authenticity and model of the token and applet.

Supported features (if installed via Fidesmo):

  • Normal and extended APDU support
  • Server credentials
  • Credential types:
    • ECDSA P-256 + SHA-256 (ES2569)
  • Basic attestation using a fleet certificate
    • Signed by the VivoKey certificate authority
  • User presence (assuming the chip is implanted)
  • FIDO MDS entry

Applet Information

FIDO U2F

Compiling the Applet Yourself

Setup your environment as described in JavaCard Development Setup .

Use git to clone the sources recursively, and change into the directory. To compile, run JC_HOME=<sdks>/jc304_kit ant, replacing <sdks> with the path to your JavaCard SDKs.

Installing the Applet

You can not use the U2F applet at the same time as the FIDO2 one because they use the same AID.

Generate Attestation Certificate

You can generate your own attestation certificate. This makes your token unique, which is maybe not something you want.

In the future, Vivokey plans offer signed certificates using their own certificate authority in some way. It is unclear if or how these would be coming to the FlexSecure, as they require the more protected environment of the Apex Flex in order to not leak.

Creating certificates used to be quite the involved task requiring advanced knowledge of openssl commands, but I have written a small tool to simplify the process. Install Python3, and the cryptography, asn1, and pyscard modules (e.g. using Pip). Then, clone or download https://github.com/DangerousThings/fido-attestation-loader .

If you specify no flags, the script will use the default file names attestation.der, attestation_key.p8, ca.der, ca_key.p8, and settings.ini. If you want to, you can edit the metadata in settings.ini, also refer to the Readme file.

First, generate a certificate authority, the script will ask you for a passphrase to secure the private key.

./attestation.py ca create

Next, generate an attestation certificate and sign it using the CA. You have to create another passphrase to protect the private key of the attestation certificate.

./attestation.py cert create

Then, you can derive the applet installation parameter by running, for FIDO U2F:

./attestation.py cert show -m u2f

The attestation script has a lot more flags to control which files to use, and to provide passphrases via the arguments instead of interactively typing them. It also provides functionality to validate a certificate gainst an certificate authority. See the -h help command for more details, or refer to the Readme file of https://github.com/DangerousThings/fido-attestation-loader .

Use GlobalPlatformPro (GPP) from https://github.com/martinpaljak/GlobalPlatformPro/releases to install the applet, for Fido U2F:

gp -install U2FApplet.cap --params INSTALLPARAM

The parameter data (INSTALLPARAM) is 00, joined to the length in bytes of the public attestation certificate (16 bit integer = 2 bytes), and joined to the private key (32 bytes). See https://github.com/darconeous/u2f-javacard/blob/master/README.md for more info. You can copy it from the last line of the output of ./attestation.py cert show.

Listing the applets using gp --list should print something like this:

APP: A0000006472F0001 (SELECTABLE)
     Parent:  A000000151000000
     From:    A000000617004F97A2E95001

PKG: A000000617004F97A2E95001 (LOADED)
     Parent:  A000000151000000
     Version: 1.1
     Applet:  A000000617004F97A2E94901

Next, you have to load the public attestation certificate by sending a few chained APDUs. The DER encoded public certificate has to be chopped into 128 byte chunks, which are sent attached to a small header. The header is 80 01 HHLL KK, with HHLL being a 16 bit integer offset of that chunk, and KK being the chunk length (hex 80, usually smaller for the last chunk). Before sending the certificate, selecting the applet is required.

The FIDO2 applet requires a few more bytes to specify the AAGUID.

This task is covered by the attestation script as well, for FIDO U2F:

./attestation.py cert upload -m u2f

You might have to specify your PCSC reader index using -r, use -l to list all readers. Note that you have to run the loader as Administator on Windows, because low-level access to FIDO applets is blocked by default.

See also https://gist.github.com/darconeous/adb1b2c4b15d3d8fbc72a5097270cdaf for more info on these APDUs for U2F.

Using the Applet

Using the applet in the web requires a modern browser with support for FIDO. NFC tokens don't work on Linux (yet, see https://twitter.com/FIDOAlliance/status/1278331283874156544).

You can use the Yubikey WebAuthn test page at https://demo.yubico.com/webauthn-technical/registration to test your token.

On Android, you can use the FIDO / Webauthn Example App at https://play.google.com/store/apps/details?id=de.cotech.hw.fido.example for testing (Use the U2F tab), or use any Browser which supports the Security Manager (for details, see Android Problems and Solutions) and use the Yubico page.

Sources and Further Reading

Improve this document: https://github.com/DangerousThings/flexsecure-applets/tree/master/docs