note: Some of the information in this guide in inaccurate or incomplete. Read the comments for details.
Overview
The Apex line of implants (and their associated P71 chips) are one of the most versatile devices sold by Dangerous Things. They are one of the few chips that allows for installable applets, making them suitable for a variety of uses.
Applets enable the P71 chip to fully emulate an NFC Yubikey-style security device for authentication. This guide covers installing, setting up, and using three specific applets that enable Yubikey emulation. The applets can be installed on both an Apex chip as well as a FlexSecure or an inexpensive P71 card for testing and backup.
These three applets will enable you to:
- Generate standard TOTP authenticator codes directly on the Apex/P71
- Authenticate with the growing number of websites that support FIDO2 and U2F (Google, Facebook, Microsoft and many others)
- Secure an encrypted password vault/database using a personalized secret that never leaves the chip
Additionally, this guide utilizes a desktop PC for installing applets to both the Apex chip and a P71 test card. This is done to make it easier to get an Apex set up before implantation since desktop RFID transceivers offer better performance than most cell phones and output additional logging and debugging info.
Much of the information is this guide comes from the excellent documentation authored by @StarGate01.
Just show me the commands
If you are already familiar with the applets and use of a P71 chip and just want a minimal set of steps, check out the associated runbook.
Table of Contents
- Overview
- Platforms, Requirements, and Resources
- Installing the Applets
- Configuring the Applets
- Using the Applets
- Yubico Playground
- Tips and Tricks
Platforms, Requirements, and Resources
This guide is Windows and Android centric. Linux and Mac users should be able to complete applet installation and provisioning but may need to install additional PC/SC tools or drivers. Linux browsers do not natively support NFC security tokens, and MacOS only has limited support for them in Safari. Yubikey has an authenticator app available for Mac, but I don’t believe it supports NFC.
Hardware
- Either an Apex implant provisioned by Fidesmo (such as the Apex Flex) or a “naked” P71 implant (such as the Flex Secure)
- A PC/SC desktop reader capable of sending extended ADPU commands. I recommend the excellent ACS ACR1252U
- An Android phone
- (optional) A P71 smart card
- Feitan NXP JCOP4 P71 Smart Card - select the option “Order Sample” from the right - about $12 + $25 shipping to the United States
- If you are in the US, PM me and I may have some extras available to sell at cost
Software
- Flex Secure applets (for installing on a P71 test card or a FlexSecure implant)
- Global Platform CLI utility (for managing applets on a P71 test card or FlexSecure implant)
- Fidesmo’s CLI utility (for managing applets on an Apex chip)
- Utility for loading an HMAC secret key. Either
- yktool (Desktop, requires Java) - Releases · arekinath/yktool · GitHub, or
- Apex Manager (Android, works with both Apex and naked chips) - https://play.google.com/store/apps/details?id=com.vivokey.apexmanager&hl=en_US
- KeePassXC (desktop password manager)
- KeePass2Android (Android password manager that can open KeePassXC vaults)
- ykdroid (Android intention that lets KeePass2Android use an NFC Yubikey
- Strongbox Password Safe (iOS app for opening KeePass vaults)
Misc
- Yubico Demo Website/Playground (for testing all of the authentication modes)
- List of applet AIDs (for installing via
gporfdsm)
Installing the Applets
P71 Test Card or FlexSecure
Setup
- Download and extract the Global Platform
gptool.- I recommend adding
gp.exeto your user path so that you can run it from any directory
- I recommend adding
- Connect the NFC reader and ensure it is recognized by Windows.
- You should be able to simply place a P71 chip on it and get the “device connected” sound/notification
- Download the following applets (.cap files) from the Dangerous Things Flex Secure repository
- YkHMACApplet
- FIDO2
- vivokey-otp
Installation
Place the P71 chip on the reader and use gp.exe to install the cap files directly
# IMPORTANT! Some applets must be installed from an administrative command prompt
# list applets on card (only shows AIDs, not names)
gp.exe --list
# install applets
gp.exe --install .\YkHMACApplet.cap
gp.exe --install .\FIDO2.cap
gp.exe --install .\vivokey-otp.cap
# verify applets by comparing the before/after lists
# you can use the AID table linked in the resources section to ensure the applets are available
gp.exe --list
Once the applets are installed, you can verify their presence either by listing them with gp.exe or scanning the chip with the Apex Manager app.
Apex Flex (Fidesmo provisioned)
Setup
- Download Fidesmo’s CLI tool from the resource section. You can use either the
.exebinary (Windows) or the.jarbinary (all platforms).- I recommend placing the binary on your system path so that it can be run from anywhere
- Obtain a list of AIDs to install. Either use the table below as a reference, or obtain them yourself by making some simple, public API calls to Fidesmo’s API (best)
- Fidesmo API & Documentation: Fidesmo - Self service portal
- All Fidesmo Apps: https://api.fidesmo.com/apps?fields=all
- Note that some apps have both Cybernetic and VivoKey versions. Use the VivoKey ones, as the Cybernetic apps are meant for the P71 Ring sold by another company (although functionally I think either would work).
| Applet | Fidesmo AID |
|---|---|
| HMAC-SHA1 | 2f2e363b |
| OTP | 61fc54d5 |
| FIDO2 | cc68e88c |
Installation
# IMPORTANT! Some applets must be installed from an administrative command prompt
fdsm.exe --verbose --run 2f2e363b/install
fdsm.exe --verbose --run 61fc54d5/install
fdsm.exe --verbose --run cc68e88c/install
# list apps
fdsm.exe --card-apps
Once the applets are installed you can verify their presence either by running fdsm.exe --card-apps or scanning the chip with the Fidesmo app on a smartphone.
Configuring the Applets
The FIDO2 and OTP applets do not need any configuration before they can be used, but the HMAC/SHA1 applet must be provisioned with a secret. The instructions below are applicable both to the Apex and naked P71 chips.
HMAC-SHA1 Configuration
The HMAC-SHA1 applet works by using a private key to generate a consistent response to a challenge issued by another party. Typically the other party will generate a challenge during enrollment/registration, send the challenge to the applet, then save the response. The challenge is sometimes considered public information.
Before the HMAC-SHA1 applet can issue a response it must be configured with a secret. Once the secret key is stored in the applet, it can never again be retrieved. It is important to decide if you want to backup the secret and/or use the same secret for multiple devices. If you do not back up the secret or configure a second device, there is no way to recover or recreate the responses issued by the applet should something happen to the chip.
The secret should be entered as a 20-byte (40 character) hexadecimal string. The example below shows how to easily generate a random secret in Python or Node.
The HMAC-SHA1 applet has two slots. If you only plan on configuring a single secret, use slot 1 since most applications will select it by default.
# python
import random
import hashlib
import string
random_str = ''.join(random.choices(string.printable, k=100))
hmac_secret = hashlib.sha512(random_str.encode()).hexdigest()[:40]
print(hmac_secret)
# node
const crypto = require('crypto');
randomStr = Array(100).fill(0).map(x => Math.random().toString(36).charAt(2)).join('');
hmac_secret = crypto.createHash('sha512').update(randomStr).digest('hex').slice(0, 40)
console.log(hmac_secret
Once you have a secret generated (and possibly backed up to a secure location), there are two choices for using it to provision the applet.
yktool (desktop)
Download yktool.jar and install Java (any modern version will work).
# see help
java -jar yktool.jar --help
# provision the applet
echo '<secret>' | java -jar yktool.jar program hmac <1 or 2> -x -X
Apex Manager (Android)
- Launch the app and scan your P71 with the HMAC-SHA1 applet installed
- Tap on Key Slot 1 or 2
- Either enter a 40-character hexadecimal key or generate one randomly
- Tap Push New Key and scan your P71
HMAC-SHA1 Testing - Manual
Once you have provisioned the applet with a secret, you can use the yktool.jar utility to issue a challenge and get the response.
Challenges should be issued as a 32-byte (64 character) hexadecimal string. Make sure to select the correct slot when issuing the challenge. Place the P71 chip on the reader and run the following
# generate a 32-byte challenge and print it to the console
python -c "import random; import string; print(''.join(random.choices(string.hexdigits, k=64)).upper())"
# issue the challenge
echo '<64_character_hex_challenge>' | java -jar .\yktool.jar hmac <slot_1_or_2> -x -X
IMPORTANT: If you are backing up your HMAC-SHA1 secret by provisioning a 2nd device (such as a P71 test card), make sure you get back identical responses from both chips. If the responses differ, then you need to re-provision one or both chips with a new common secret.
Using the Applets
The three applets that were installed will collectively emulate the capabilities of a Yubikey hardware device. While the standards used are mostly platform independent, Yubikey is the largest provider of physical security tokens and has influenced how they have been set and adopted. Because of this you will sometimes see Yubikey referred to in the context of a protocol suite instead of an actual product.
HMAC-SHA1 and KeePassXC
tl;dr - KeePass vaults vaults can be secured with the HMAC-SHA1 applet, allowing to to encrypt passwords and other sensitive information. Use KeePassXC on desktop, KeePass2Android on Android, and Strongbox on iOS. On Android, you will also need to install the ykdroid intention. I have not tested on iOS.
History and Compatibility
The HMAC-SHA1 protocol is not nearly as ubiquitous as either TOTP authenticators or FIDO2. However, thanks to a code contribution by @StarGate, the applet can now work as a second authentication mechanism for KeePassXC. The KeePass line of applications function as a secure vault for passwords, payment accounts, and any other sensitive information. When combined with a device like the Apex, a cloud-saved KeePass database can serve as a kind of infinite extension of the secrets that can be secured with an implant.
KeePass vaults are stored as an encrypted database of entries, typically with a file extension of .kdbx. The original KeePass was written on the Windows-centric .NET platform (C#) and while it was later ported to other operating systems, it was difficult to update. KeePassX was a fork of KeePass rewritten in C++ for better portability. However, the project was not well maintained and has not been updated in many years. KeePassXC is the community version of KeePassX and is actively maintained with semi-frequent releases. There is limited support for compatibility in the database vault formats between the versions.
There is no direct KeePassXC mobile port, but there are free, open-source password managers on both Android and iOS that can open KeePassXC databases. A common setup is to keep the KeePass database file in the cloud, then read and write to it from multiple devices. The database format supports change detection and limited merging, making shared use mostly seamless.
Challenge-Response Formats
Both KeePass and KeePassXC support the HMAC challenge-response Yubikey protocol. However each implements it differently. KeePass uses the response to encrypt a sidecar file which is then used as a key file to unlock the database. KeePassXC instead uses a portion of the database’s random seed as the challenge, then incorporates the response (along with a password) into the master encryption key. The key is changed each time the database is saved.
Databases that are secured using a YubiKey are not cross-compatible between KeePass and KeePassXC. The method that KeePassXC uses is the more common, and is supported on most operating systems, including mobile.
USB vs NFC
Using a Yubikey via USB generally has more support than using it via NFC, especially on desktop.
KeePassXC gained support for NFC challenge-response in 2021 thanks to a PR by Stargate. KeePass2Android can use the ykdroid intention, and Strongbox for iOS can work with NFC challenge-responses starting with iOS 13.3
Security and Recovery
All of the KeePassXC combatable applications listed in this guide are open source. The KeePassXC desktop app completed a security audit in 2022. The auditor discovered “no major problems” and recommended the use of the app for use. Both a summary and the full audit are available on KeePassXC’s website.
KeePass2Android has not had any kind of formal security audit. The developer has been responsive to reported security issues. However, he appears to be a single developer maintaining the project in his free time. See this issue for an example of a reported security issue and the developer’s response.
Strongbox is developed by a wider team of people but also has not had any formal security audits. The development team has been responsive to security issues, and you can see a short response to a security question on Reddit.
KeePassXC implements limited protection against replay attacks by changing the challenge that is issued on every save. This means that an intercept of the response between the applet and a reader could only be used to open a database until the next time the file was saved and a new challenge generated. However, if the database is versioned (Windows rollback, Google, Dropbox, etc), then a replay attack would work on x number of previous instances depending on the retention and rotation policy.
If the secret used to program the HMAC-SHA1 applet was backed up, it can be used to directly open the database without needing to program the secret into another device.
KeePassXC has a standalone recovery utility available that will accept the raw secret as an input. KeePass2Android has a “Password + Challenge-Response Secret (recovery mode)” option when selecting the master key type. And Strongbox has a “Show Yubikey Secret Workaround Field” option that can be enabled.
If the secret that was used to program the HMAC-SHA1 applet is lost, there are no methods that I know of (intended or otherwise) that would allow someone to generate the correct response or gain access to the database.
Usage - KeePassXC
You must use the KBDX 4 format. When initially creating a database, select the “add additional protection” option, then pick “Challenge Response”. Place the chip on the reader then click the refresh button. If you have two secrets provisioned you will need to select the desired slot.
A similar process is used to open a database. You must place your chip on the reader and hit refresh before you can select a slot. This can be awkward if your chip is in your mouse-wielding hand. As a work-around you can press tab to focus the refresh icon, present your chip to the reader, then press space to refresh the list and enter to open the database.
Anytime the database is saved you will be prompted to “present your Yubikey”. You only have a couple of seconds to scan your chip before the request turns into an error message. If this happens you will need to manually save using the ribbon button or file menu item.
Usage - KeePass2Android
Install the ykdroid intention from the Play Store or the GitHub repository. Android intentions are a method for applications from different domains to communicate with each other. Once installed, any application can use the net.pp3345.ykdroid.intent.action.CHALLENGE_RESPONSE to send a challenge which will cause an NFC prompt to appear. The slot can be changed and should be remembered. There does not appear to be any timeout once the prompt is triggered. The intention will return the response as provided by the applet.
After starting the KeePass2Android app, select the “Password + Challenge-Response for KeePass XC” option in the “Select master key type” dropdown, enter a password and select Unlock. You will be prompted by ykroid to attach or swipe your Yubikey.
The Challenge-Response can only be used to fully unlock a database. At this time is cannot be used for quick unlock.
Usage - Strongbox (iOS)
Help Requested: I do not have an iPhone and cannot test this functionality. If anyone would like to try and and send me a short write-up I’ll update this guide.
Authenticator (TOTP)
The TOTP authenticator protocol is probably the one that is most familiar to people when they think about 2FA. The protocol is fairly simple and there are many implementations such as Google, Microsoft, and Apple Authenticator.
Software-based TOTP authenticators work by using a shared secret along with the current time to generate a 6 digit code. The authenticating party (e.g. a website) enrolls an authenticator during sign up, then uses the shared secret along with the current time to validate that a provided 6-digit code was generated by a device with the same secret.
Hardware-based TOTP authenticators such as Yubikeys work the same way except that the shared secret and code generation occur on secure hardware. The hardware generally makes the secret write-only so once it is saved to the device, it can never be directly read again.
The OTP applet takes the place of hardware, storing the secret and generating codes. Note that each provisioned secret will reduce the available space on the Apex/P71 chips. If you have many services/websites you want to enroll, you may need to be selective about which ones you store on the P71.
Both the Apex Manager and the Yubikey Authenticator smartphone apps can be used to enroll and delete secrets and request and display codes. Which one you use comes down to personal preference. There is no way to view or recover a secret once it has been enrolled. If you want to have a backup you must either enroll two authenticators with the service at the same time, or copy/backup the secret during enrollment (not recommended, as it defeats the purpose of 2FA).
Yubikey Authenticator
Operation is straightforward. You can enroll new secrets either via QR code or manually. To delete a credential first scan your chip, then tap on the credential to chose “remove”, and scan your chip again. Long pressing on a credential will copy it to the clipboard.
Apex Manager
Operations are almost identical, except that you must scan your implant first, then select Authenticator. The latest update to the app made it so that the credential codes will be generated upon the initial scan and will be immediately visible on the Authenticator page. Touch behavior is swapped from Yubikey. Use a long tap to edit or delete a credential, and a short tap to copy it to the clipboard.
Testing OTP Codes
There are several ways to test the applet before actually using it on a service. If you just want to make sure the applet is functioning, you can use FreeOTP - QR Code Generator to generate your own QR code, scan it with either app, then scan your chip and ensure a 6-digit code is generated.
If you want to test an actual login experience, use the Yubico Playground which will let you create a fake account, then sign into it using a number of options including TOTP codes. See the Playground section later in this guide for more information.
FIDO2
The FIDO2 applet has support for both regular FIDO authentication as well as U2F (Universal Two Factor). However, U2F requires OS-level support and is not implemented on some combinations of browsers and operating systems.
Similar to TOTP codes, using a FIDO-based security key involves registering the device with an authenticating party. However unlike TOTP-based authentication, the parties use public and private keys to establish trust instead of a shared secret. There are also no code to generate or enter. The full authentication flow happens during a single hardware-connected session. Where TOTP uses a shared understanding of time to prevent replay attacks, FIDO primarily uses counters.
FIDO credentials will take up storage on the P71 chip. There is currently no way to remove a credential set once it has been stored on the chip other than uninstalling and reinstalling the applet. Dangerous Things is hoping to add this functionality to the Apex Manager in the future.
Support
FIDO2 via NFC works very well on Windows with both Chrome and Firefox, and ok-ish on Android. Support for FIDO2 is more limited on MacOS and iOS and may only work with Safari (need more information).
Support on Linux using NFC is not natively supported in any of the browsers but can be hacked around by using @Stargate’s FIDO2 PC/SC Bridge which bridges an PC/SC NFC reader to a virtual USB device that Chrome and Firefox can recognize.
Usage and Testing
The process for enrolling and using a FIDO2 hardware device is simple. During registration or login your browser will ask you to present your device, and if successful you will be authenticated.
Many of the larger cloud services such as Google, iCloud, Facebook, AWS, and Microsoft support FIDO2 as a factor. The Yubico Playground is a great way to test both enrollment and usage. See the section below for more information.
Yubico Playground
Two of the three authentication applets/mechanics mentioned in this guide can be directly tested in Yubico’s Playground. However, the terminology used on their website can be confusing.
The playground allows you to create a demo account with a password, then attach as many secondary authentication methods as you want. If you have multiple methods registered with your demo account, you can hit “cancel” when prompted to present your security key to see the other options.
Below is a list of the Yubico-named method and the P71 applet/method it corresponds to.
| Yubico | Applet/Technology |
|---|---|
| Security Keys | FIDO2 |
| Internal (Built-In Authenticators) | not supported as an applet |
| Yubico One-Time Password | not supported as an applet |
| Authenticator Application | OTP (TOTP) |
| Recovery Codes | n/a |
FIDO2
FIDO2 requires multiple layers between the card reader and the the demo website. It works well on Windows + Firefox/Chome but YMMV with other combinations. There are also a lot of approvals required from both Windows and the browser before a credential can be enrolled. The process is self-explanatory once started.
When registering a FIDO2 device, there is an option that says “Enable passwordless login with this key”. Selecting this will set up the P71 as a U2F device. U2F support among browsers and operating systems is more limited compared to FIDO. If enabled, you will be required to set up a PIN that you must then enter when authenticating with the card. The entire flow is somewhat convoluted, especially when used on an implant that is not left in the field. You will have to tap your P71 three times during enrollment. Once a PIN is set it will need to be used for all FIDO2 logins, not just passwordless ones.
Authenticator Application
You can use either the Yubikey Authenticator or the Apex Manager (or both). Generated codes will be identical between each.
Recovery Codes
Try storing them in a KeePassXC database that is secured with the HMAC-SHA1 applet. Each code can only be used once.
Tips and Tricks
Just some random things I’ve found useful or information that didn’t fit well elsewhere in the guide.
Backup Strategies
- OTP Authenticator
- Enroll two devices at the same time
- While you can save the shared secret (either as a QR code or text), this is a horrible security practice
- FIDO2
- Enroll two devices at the same time if allowed by the service
- HMAC-SHA1
- Configure two devices with the same random secret, then throw it away (best)
- Save the secret somewhere secure
Best Practices
-
Archive and document the specific versions of all applications and applets you use.
- Protect yourself from breaking changes and even entire repositories disappearing.
- Download mobile applications directly from repositories if available. Google Play or Android might decide one day to remove these apps.
-
Test everything on a $15 P71 card before attempting to install and configure your Apex
- If you are in the US, shoot me a PM and I can send you a test card at cost via untracked USPS
-
Get an NFC repeater. Get lots of NFC repeaters. Put them everywhere
-
Watch the free storage amount on your P71 (using the
free-memoryapplet). You may need to limit the number of OTP and FIDO2 credentials you store.- KeePassXC can store OTP credentials. If you have a lot of credentials you can store the critical ones directly on the OTP applet (such as your primary email), but keep the others in a dedicated KeePass database. Use a different HMAC-SHA1 slot for a bit of extra security.
KeePassXC
-
Easier database unlocks if your chip is in your mouse-wielding hand
- open app and select database
- type in password
- press
tabto focus the refresh icon - present your hand to the reaper and wait for a beep
- press
spaceto refresh the list - press
enterto unlock using the default slot - remove your hand
-
Temporarily remove the Challenge-Response second factor if you are going to be creating/editing/deleting multiple entries.
- Database → Database Settings → Remove Challenge Response
