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.