Swissbit iShield FIDO2 User manual

User Manual
Swissbit iShield Key
iShield Key FIDO2 [USB-A/NFC]
iShield Key Pro [USB-A/NFC]
Date: 10 March 2023
Document Version: 1.0.0
V
e
r
s
i
o
n
:
2
.
5

Page 2 of 69
Copyright 2022 by Swissbit AG
This document as well as the information or material contained is copyrighted. Any use not explicitly permitted by
copyright law requires prior consent of Swissbit AG. This applies to any reproduction, revision, translation, storage
on microfilm as well as its import and processing in electronic systems, in particular.
The information or material contained in this document is property of Swissbit AG and any recipient of this document
shall not disclose or divulge, directly or indirectly, this document or the information or material contained herein
without the prior written consent of Swissbit AG.
All copyrights, trademarks, patents and other rights in connection herewith are expressly reserved to Swissbit AG
and no license is created hereby.
Subject to technical changes.
All brand or product names mentioned are trademarks or registered trademarks of their respective holders.

Page 3 of 69
Table of Contents
TABLE OF CONTENTS....................................................................................................3
1DOCUMENT INFORMATION ....................................................................................... 5
2OVERVIEW ISHIELD KEY .......................................................................................... 5
3SWISSBIT MANAGEMENT TOOLS ................................................................................... 7
ISHIELD KEY MANAGER COMMAND LINE TOOL ........................................................................... 7
FIDO Command.......................................................................................................................................7
HOTP Command......................................................................................................................................8
PIV Command.........................................................................................................................................8
4FIDO2 APPLICATIONS (STANDARD)................................................................................10
OVERVIEW ...........................................................................................................10
FIDO2 Registration ...............................................................................................................................10
FIDO2 Login ...........................................................................................................................................11
GETTING STARTED WITH FIDO2 APPLICATIONS........................................................................... 11
Preconditions.......................................................................................................................................11
PIN Setup of Swissbit iShield Key......................................................................................................11
Test Registration..................................................................................................................................13
Test Login..............................................................................................................................................14
Register Swissbit iShield Key on an online Microsoft account .....................................................16
Usernameless/Passwordless Sign-in on an online Microsoft account ........................................20
Sign-in with external Identity Provider ..........................................................................................20
SWISSBIT ISHIELD KEY ON VARIOUS SERVICES........................................................................... 28
Auth0.....................................................................................................................................................28
Bitbucket ..............................................................................................................................................32
Github ...................................................................................................................................................34
Amazon Web Service (AWS) ................................................................................................................37
5HOTP APPLICATIONS ............................................................................................ 39
OVERVIEW AND FUNCTIONALITY ....................................................................................... 39
Registration..........................................................................................................................................39
HOTP Computation...............................................................................................................................39
Password Generation and Authentication ......................................................................................40
Counter Resynchronization................................................................................................................41
6PIV APPLICATIONS............................................................................................... 42
OVERVIEW USE CASES.................................................................................................42
Logon.....................................................................................................................................................43
Bitlocker................................................................................................................................................44
Active Directory....................................................................................................................................44
UNDERLYING COMPONENTS........................................................................................... 45
Token Provisioning and Usage on Windows ...................................................................................45
Authentication.....................................................................................................................................45
Certificate Slots ....................................................................................................................................45
REQUIREMENTS...................................................................................................... 46
GETTING STARTED WITH PIV ON ISHIELD KEY PRO ...................................................................... 46
PIV Installation Package.....................................................................................................................46
Installation of the OpenSC Minidriver and iShield PIV Module ....................................................46
Preparation of the iShield Key Pro ...................................................................................................49
Reset the iShield Key Pro ...................................................................................................................49
USE CASE:LOCAL ACCOUNT BITLOCKER ................................................................................ 50

Page 4 of 69
Setup Process .......................................................................................................................................50
Use it to encrypt a Drive.....................................................................................................................56
USE CASE:ACTIVE DIRECTORY BITLOCKER ...............................................................................57
Setup on Server....................................................................................................................................57
Self-enroll Certificate on Client PC....................................................................................................62
Use it on Client.....................................................................................................................................64
USE CASE:ACTIVE DIRECTORY PC LOGON .............................................................................. 65
Setup on Server....................................................................................................................................65
Self-enroll Certificate on Client PC....................................................................................................65
Use it on Client.....................................................................................................................................66
TROUBLESHOOTING ...................................................................................................67
Troubleshooting “The smart card is read-only / cannot perform the requested operation”.67
Troubleshooting “An internal consistency check failed”..............................................................67
7GLOSSARY....................................................................................................... 68
8DOCUMENT HISTORY ............................................................................................ 68

Page 5 of 69
1Document Information
This document describes how to get started with your Swissbit iShield Key FIDO2 [USB-A/NFC] (hereinafter referred
to as “iShield Key FIDO2”), and iShield Key Pro [USB-A/NFC] (hereinafter referred to as “iShield Key Pro”) security
key. The iShield Key FIDO2 and iShield Key Pro offer strong authentication that is simple, secure and flexible. They
also protect users against online attacks such as phishing, social engineering and account takeover.
The iShield Key FIDO2 supports FIDO2 and U2F standards to protect online accounts. The iShield Key Pro implement
a one-chip solution with multiple applets installed to support various use cases. The iShield Key Pro supports,
additionally to FIDO2 applications, generation of HMAC-based one-time passwords (HOTP) and personal
identification and verification (PIV). You can find an overview of supported use cases and references to more
detailed descriptions later in this document in section 2. Section 3 introduces the management tools
accompanying the security key. Eventually, the uses cases are explained by applet in section 4, section 5 and
section 6. Section 4 gives in-depth guidance on how to get started with the FIDO2 functionality, section 5 explains
the HOTP generation and usage and section 6 presents how to provision and use your iShield Key Pro key as a PIV
device.
In section 4, the iShield Key FIDO2 is utilized for all FIDO2 use cases since it shares the same functionality as the
iShield Key Pro. Sections 5 and 6 are specifically applicable to the iShield Key Pro and do not pertain to the iShield
Key FIDO2.
In the following, “iShield Key” will be used in scenarios where both iShield Key FIDO2 and iShield Key Pro are
compatible.
We highly recommend registering to the Swissbit Developer Portal. We will keep you up-to-date on important
product information. Additionally, you can subscribe to receive emails for new blog posts and other product
related content.
2Overview iShield Key
The Swissbit iShield Key FIDO2 security key has the FIDO2 applet installed only, and the Swissbit iShield Key Pro

Page 6 of 69
security key has the FIDO2, HOTP and PIV applets installed. In this section, you can find the functionalities that
support your use cases.
The following table guides you to the correct section in this guide for a more detailed description of your use
case:
Use Case
Description
Applet
iShield
Key FIDO2
iShield
Key Pro
Reference
Online Authentication
User authentication for FIDO2
and U2F compatible websites
and services
FIDO2


section 4.2
2FA for Online Accounts / VPN
Two-factor authentication to
websites, services or VPN
supporting HOTP
HOTP

section 5.1
Bitlocker –Local Account
Drive encryption using Bitlocker
for Local Windows Accounts
PIV

section 6.5
Bitlocker –Active Directory
Drive encryption using Bitlocker
for Windows Active Directory
Domain Accounts
PIV

section 6.6
Windows Account Logon –
Active Directory
Logon into Windows Active
Directory Domain Account
PIV

section 6.7

Page 7 of 69
3Swissbit Management Tools
IShield Key Manager Command Line Tool
The iShield Key Manager command line tool (iKMcli.exe) supports all required operations to manage the FIDO2,
HOTP (iShield Key Pro only) and PIV (iShield Key Pro only) applets on your iShield Key and assist the use cases
presented in this guide.
You can download the command line tool from the Swissbit iShield Key landing page.
We recommend adding the iKMcli to your path. Then you can execute operations as follows:
iKMcli <command> <options>
The help of the iKMcli lists all commands and options. You can print the help by iKMcli –-help or
iKMcli <command> --help for a specific command.
You can print the info for your iShield Key, including the serial number, by the command
iKMcli info –-reader <reader>
To list all available smartcard readers and FIDO2 devices, use the following command:
iKMcli list
The detection of FIDO2 devices requires the execution of the command line tool as administrator.
There is one command for addressing the single applets installed in the iShield Key. In the following three
sections, the supported operations for FIDO2, HOTP and PIV are explained in more detail.
FIDO Command
The command fido for managing the FIDO2 applet provides an option to print information about your connected
FIDO2 device:
iKMcli fido --info
If no PIN is set yet, you can set a new PIN by
iKMcli fido --set-pin <new pin>
You can change your PIN by
iKMcli fido --change-pin <new pin> --pin <pin>
To erase all credentials and the PIN, you can reset the FIDO2 device by
iKMcli fido --reset
You will be asked to touch the FIDO2 device to reset.
All these options for the fido command use the first detected iShield Key but you can also specify a FIDO2 device.
In order to execute an operation for a specific device, pass its path with the option –-fido-path <path>. You
can use the list command to list the paths of all connected FIDO2 devices.
The fido command requires administrator rights.

Page 8 of 69
HOTP Command
The command hotp has an option to show information about the HOTP applet on your iShield Key Pro:
iKMcli hotp --info
The info contains the version of the applet and the serial number of your iShield Key Pro.
The default PIN for authenticating an HOTP operation is 1234. You can change this factory default PIN by
iKMcli hotp --change-pin <new pin> --pin <pin>
The PIN must be between four and eight characters in length. You can optionally pass a format for the PIN with
the option --pin-format <ascii|hex>. If no PIN format is specified, ASCII format is assumed.
The command also offers the options to set the secret key and counter for the HOTP computation by the following
commands:
iKMcli hotp --set-key <key> --pin <pin>
iKMcli hotp --set-counter <counter> --pin <pin>
The secret key must be hex encoded and be of a length between 16 and 64 bytes and the counter must be a
positive integer. The factory value of the key programmed during device manufacturing is
3132333435363738393031323334353637383930 and the default 0f the initial counter value is 0. You can restore these
factory default values by
iKMcli hotp –-restore-factory-key <key> --pin <pin>
iKMcli hotp –-restore-factory-counter <counter> --pin <pin>
If you enter your PIN incorrectly 10 times, your PIN will be blocked irreversibly! You can still generate one-time
passwords but you will no longer be able to set a new secret key and counter and register your iShield Key Pro
for another application. Successful authentication of the PIN resets the retry counter.
The iShield Key Pro supports generation of one-time passwords of length 6 or 8 whereby 6 is the default length.
You can adjust the HOTP length by
iKMcli hotp --set-otp-length <length>
The hotp operations use the first detected iShield Key or you specify the smartcard reader to be used by the
option --reader <reader>. You can use the list command to print the connected smartcard readers.
PIV Command
The command piv also provides an option to print the version of the PIV applet installed on your iShield Key Pro
and your keys serial number:
iKMcli piv --info
Using the iShield Key Manager you can change the PIN, PUK and management key that are used to authenticate
PIV operations. The factory default for the PIN is 123456, the default PUK is 12345678 and the management key is
010203040506070801020304050607080102030405060708. You can change your PIN or unblock it by the PUK using
the following commands:
iKMcli piv --change-pin <new pin> --pin <pin>
iKMcli piv --unblock-pin <new pin> --puk <puk>
You can change the PUK using

Page 9 of 69
iKMcli piv --change-puk <new puk> --puk <puk>
A new management key can be set by
iKMcli piv --set-management-key <new key> --management-key <key>
You can list all certificates on the smartcard with the following command
iKMcli piv --list-certificates
In order to delete a certificate by its slot number use
iKMcli piv --delete-certificates <slot> --management-key <key>
If both PIN and PUK are blocked, you can reset your smartcard. This erases all PIV data and restores the default
settings.
iKMcli piv --reset
New values for the card holder unique identifier (CHUID) and card capability container (CCC) can be set with the
following commands:
iKMcli piv --set-chuid
iKMcli piv --set-ccc
Like the hotp operations, the piv operations use the first detected iShield Key. Alternatively, you can specify a
smartcard reader by the option --reader <reader>. You can use the list command to print the connected
smartcard readers.

Page 10 of 69
4FIDO2 Applications (Standard)
Overview
The Swissbit iShield Key FIDO2 and iShield Key Pro are FIDO-certified plug-and-play security products that support
FIDO2 and U2F standards to protect online accounts. They provide strongest and most trusted hardware
authentication and allow users to securely access websites, applications, online services and company networks
such as Google, Microsoft, Salesforce, Amazon Web Services, etc. You can visit FIDO Alliance
(https://fidoalliance.org/fido2/) for more information. Swissbit provides a test website (https://fido.ishield.cloud/)
to allow users to test with Swissbit iShield Key.
This section explains FIDO2 registration and login and all FIDO2 functionalities are compatible for both iShield Key
FIDO2 and iShield Key Pro. Section 4.2 gets you started with your iShield Key and section 4.3 shows how to register
the key with various online services.
FIDO2 Registration
When registering for an online service, the server requests a public key that it can assign with the user’s account
for this one service for online authentication. The user will then be able to authenticate if they are in possession
of the corresponding private key. Using the iShield Key for FIDO2 registration, the user needs to authenticate with
the user PIN and touch the security key. The public private key is generated on the iShield Key hardware
authenticator and assigned with the user account. Lastly, the public key is sent to the server.

Page 11 of 69
FIDO2 Login
After successful FIDO2 registration, the online service has the public key for the user account and the
corresponding private key is stored securely on the iShield Key. The online service challenges the user to sign
with the private key. If the online server can verify the signature using the public key, the authentication is
successful and user is granted access to their account.
Getting started with FIDO2 Applications
Preconditions
The Swissbit iShield Key supports platforms and applications that are conform to FIDO/U2F/WebAuthn standards.
Following Platforms are supported:
OS:
oWindows 10,
oMacOS,
oLinux,
oChrome OS,
oAndroid
Browsers:
oFirefox,
oMS Edge,
oChrome,
oApple Safari
PIN Setup of Swissbit iShield Key
Note: The Swissbit iShield Key is ready to use. If PIN is not required, jump to section 4.2.3
To manage the security PIN of the Swissbit iShield Key, a built-in functionality for security key management of
Windows 10 might be used.
Get your Swissbit iShield Key and windows computer ready.
To launch the security key management, please click “Start --- Settings --- Accounts”, then choose the option
“Security key” and click the button “Manage”

Page 12 of 69
A pop-up window will prompt you to insert your security key into the USB port. Please insert the Swissbit iShield
Key.
In case the Swissbit iShield Key is recognized, then you can either choose to create or change the PIN for the
Swissbit iShield Key, which depends on whether there was a PIN stored previously. Meanwhile, the PIN of the
Swissbit iShield Key can be reset if it was lost or forgotten. Please note that the PIN and credentials will be
removed after resetting.

Page 13 of 69
You could set up a new PIN if there is no PIN stored in it. To change the security PIN, the current PIN is required.
If you reset the Swissbit iShield Key, please note that the credentials are lost after reset.
Test Registration
Please visit the test website https://fido.ishield.cloud, which supports WebAuthn, to test your Swissbit iShield
Key.

Page 14 of 69
The website looks like this:
To register the Swissbit iShield Key, enter any name for credential ID, and click “Register”
The security PIN is now required if a security PIN was setup as stated in section 4.2.2.
Note: If the security PIN is lost or not needed for your use case, move to section 4.2.2 to reset Swissbit iShield Key.
Please note that you have to register your key again after resetting.
After security PIN is accepted, you have to touch the end of the Swissbit iShield Key, to make sure that a human
is now operating it and not a machine. You will be prompted to touch your security key.
Now registration is completed. The Swissbit iShield Key is ready to be logged in.
Test Login
Please enter the Test ID that you registered before, and then click “Login”
Security PIN may be asked depending on whether the security PIN was set as stated in section 4.2.2. When
requested, touch the end of the Swissbit iShield Key to make sure a human is operating it.

Page 15 of 69
Finally, you will see the success message as shown below and the credential information about the Swissbit
iShield Key you used. It means that the Swissbit iShield Key is working properly.

Page 16 of 69
Register Swissbit iShield Key on an online Microsoft account
You can easily sign into your Microsoft account with the Swissbit iShield Key without giving your e-mail address
and password. In this section, we will guide you how to register the Swissbit iShield Key on an “online” Microsoft
account. To log into an offline Microsoft account e.g. a local Windows PC account is not covered in this section.
Note: Please get your Microsoft account ready.
Visit https://login.live.com/ to login.
After login, you will be directed to the main page. Click “Security” from the top blue bar and choose “Advanced
security options”.
On this page, you can manage your activated sign-in and verification options. Click “Add a new way to sign in
or verify” to add the Swissbit iShield Key as a security key.

Page 17 of 69
In the following page choose “Use a security key”.
Connect your Swissbit iShield Key and click “Next”. As the Swissbit iShield Key is an USB security key with NFC,
you could choose, either to plug it into your USB port, or to keep it close to your NFC reader.

Page 18 of 69
Follow the pop-up to setup your Swissbit iShield Key. Please note that Microsoft requires the user to create a PIN
for the Swissbit iShield Key.
After you finish your setup, you will see the success page as shown below.

Page 19 of 69
Meanwhile, you will receive an e-mail from Microsoft.
Back on the verification options page, your Swissbit iShield Key should already be listed and you can manage it
anytime (in the screenshot it is named “iShield FIDO2”).

Page 20 of 69
Usernameless/Passwordless Sign-in on an online Microsoft account
As the Swissbit iShield Key is already registered on Microsoft, you can now sign in without an e-mail address and
password.
Visit https://login.live.com/ to login, and click “Sign in with a security key”. If you don’t see this option, click
“Sign-in Options” at the bottom and choose “Sign in with a security key”.
Now plug in your Swissbit iShield Key, or keep it close to your NFC reader.
When your Swissbit iShield Key is detected, enter your PIN.
Now you are successfully logged into the Microsoft account.
Sign-in with external Identity Provider
If you want to setup Single Sign-On with the Swissbit iShield Key, but your target service does not support
FIDO/WebAuthn natively, then you can use an external Identity Provider like Keycloak. In the following section,
we will demonstrate how to setup Single Sign-On with Keycloak and your Swissbit iShield Key.
This demo consists of two parts. A Dracoon App (“Dracoon”) which is a third party cloud service provider and
Keycloak which is an open-source Identity and Access Management service.