Yubico Mobile iOS SDK (YubiKit)

YubiKit is an iOS library provided by Yubico to interact with YubiKeys on iOS devices.

The library is provided with a demo application which shows complete examples of how the library can be integrated and demonstrates all the features of this library in an iOS project.

Changes to this library are documented in this Changelog.

YubiKit requires a physical key to test its features. Before running the included demo application or integrating YubiKit into your own app, you need an NFC-Enabled YubiKey or a YubiKey 5Ci to test functionality.

The host application can build the library as a dependency of the application target when used inside a Xcode workspace. In addition, the library can be packed using the build.sh script, which is provided in the root folder of this project.

Read the transitioning document if you already have integrated the previous version of the SDK.

To get started, you can try the demo as part of this library or start integrating the library into your own application.

The library is provided with a demo application, YubiKitDemo. The application is implemented in Swift and it shows several examples of how to use YubiKit, including WebAuthn/FIDO2 over the accessory or NFC YubiKeys.

The YubiKit Demo application shows how the library is linked with a project so it can be used for a side-by-side comparison when adding the library to your own project.

YubiKit SDK is available as a library and can be added to any new or existing iOS Xcode project through SPM, Cocoapods, or manual setup.

[SPM Setup]

The YubiKit SDK for iOS is availble Swift Package Manger (SPM). SPM is a dependency manager built into recent versions of Xcode. Go here to learn more.

1. Open Xcode and click "File" -> "Swift Packages" -> "Add Package Dependency..."

2. Paste the following URL: https://github.com/Yubico/yubikit-ios

3. Click "Next" -> "Next" -> "Finish"

4. If your target project is written in Swift, you need to provide a bridge to the YubiKit library by adding #import <YubiKit.h> to your bridging header. If a bridging header does not exist within your project, you can add one by following this documentation.

[Cocoapods Setup]

The YubiKit SDK for iOS is available through CocoaPods. CocoaPods is a centralized dependency manager for Objective-C and Swift. Go here to learn more.

Add YubiKit to your Podfile.

use_frameworks!

pod 'YubiKit', '~> 4.5.0'

If you want to have latest changes, replace the last line with:

pod 'YubiKit', :git => 'https://github.com/Yubico/yubikit-ios.git'

Once YubiKit is added to your Podfile, run pod install and open the *.xcworkspace with Xcode.

Then import the YubiKit module and you can use its classes and methods.

import YubiKit

Continue SDK setup by skipping over Manual Setup to Enable Custom Lightning Protocol.

Enable Custom Lightning Protocol

REQUIRED if you are supporting the YubiKey 5Ci over the Lightning connector.

The YubiKey 5Ci is an Apple MFi external accessory and communicates over iAP2. You are telling your app that all communication with the 5Ci as a supported external accessory is via com.yubico.ylp.

Open info.plist and add com.yubico.ylp as a new item under Supported external accessory protocols

Enable TKSmartCard support

To support YubiKeys connected via the USB-C port on a device running iOS 16 or higher, you need to add the com.apple.security.smartcard entitlement to your application. Note that this connection only support the Smart card based applications on the YubiKey and does not support U2F, FIDO2 or OTP.

Grant accesss to NFC

To add support for NFC YubiKeys in your application, follow these steps:

• Add a NEW entitlement for reading NFC specific tags, available since iOS 13. This new entitlement is added automatically by Xcode when enabling the Near Field Communication Tag Reading capability in the target Signing & Capabilities. After enabling the capability the .entitlements file needs to contain the com.apple.developer.nfc.readersession.formats entitlement:

...
<dict>
    <key>com.apple.developer.nfc.readersession.formats</key>
    <array>
        <string>TAG</string>  // Application specific tag, including ISO 7816 Tags
    </array>
</dict>
...

• The application needs to define the list of application IDs or AIDs it can connect to, in the Info.plist file. The AID is a way of uniquely identifying an application on a ISO 7816 tag, which is usually defined by a standard. FIDO2 and U2F use the AID A0000006472F0001 on most FIDO compliant NFC keys, including the YubiKey. After adding the list of supported AIDs, the Info.plist entry should look like this:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<key>com.apple.developer.nfc.readersession.iso7816.select-identifiers</key>
<array>
    <string>A000000527471117</string> // YubiKey Management Application AID
    <string>A0000006472F0001</string> // FIDO/U2F AID
    <string>A0000005272101</string>   // OATH AID
    <string>A000000308</string>       // PIV AID
    <string>A000000527200101</string> // YubiKey application/OTP AID (for HMAC SHA1 challenge-response)
</array>
</plist>

• The Info.plist also needs to include a privacy description for NFC usage, using the NFCReaderUsageDescription key:

<key>NFCReaderUsageDescription</key>
<string>The application needs access to NFC reading to communicate with your YubiKey.</string>

Grant accesss to CAMERA

Optional: if you are planning to use the camera to read QR codes for OTP Open info.plist and add the following usage: 'Privacy - Camera Usage Description' - "This application needs access to Camera for reading QR codes."

YubiKit headers are documented and the documentation is available either by reading the header file or by using the QuickHelp from Xcode (Option + Click symbol). Use this documentation for a more detailed explanation of all the methods, properties, and parameters from the API. If you are interested in implementation details for a specific category like U2F, FIDO2, or OATH, check out the ./docs section.

YubiKit is exposing a simple and easy to use API for executing operations on the YubiKey. The API is divided into Connections and Sessions. The supported connections are YKFAccessoryConnection, YKFSmartCardConnection and YKFNFCConnection. Each session is started by calling YubiKitManager.shared.startAccessoryConnection(), YubikitManager.shared.startSmartCardConnection() or YubiKitManager.shared.startNFCConnection(). Once a YubiKey connects the SDK delivers the new connection via the YKFManagerDelegate protocol. Disconnects are also signaled through the protocol. For an easier and a more Swift-like experience you can implement something similar to this example: YKFManagerDelegate wrapper.

From a connection you can retrieve any of the sessions currently supported in the SDK. The connections are fetched by calling a method with a callback block. Once the session has been established and the corresponding application on the YubiKey has been selected the callback will return the new session. For e.g a FIDO2 session it would look like this:

connection.fido2Session { session, error in
    guard let session = session else { /* handle error and return */ }
    session.verifyPin(pin) { error in
        ...
    }
}

#import <YubiKit/YubiKit.h>

[self.connection fido2Session:^(YKFFIDO2Session * _Nullable session, NSError * _Nullable error) {
    if (error) { /* handle error and return */ }
    [session verifyPin:pin completion:^(NSError * _Nullable error) {
        ...
    }];
}];

Before initiating the accessory connection, the application should verify that the device running the app supports connecting to the YubiKey over the Lightning port. This can be done by looking at the supportsMFIAccessoryKey property on YubiKitDeviceCapabilities.

The same goes for the NFC connection and similar to the accessory connection the YubiKitDeviceCapabilities has a property supportsISO7816NFCTags that indicates wether the device supports connecting to the YubiKey over NFC.

if YubiKitDeviceCapabilities.supportsISO7816NFCTags {
    // Provide additional setup when NFC is available            
    // example
    YubiKitManager.shared.startNFCConnection()
} else {
    // Handle the missing NFC support 
}

#import <YubiKit/YubiKit.h>
...
// NFC scanning is available
if (YubiKitDeviceCapabilities.supportsISO7816NFCTags) {
    // Provide additional setup when NFC is available
} else {
    // Handle the missing NFC support
}

List of sessions is documented below with it's own specifics and samples:

• FIDO - Provides FIDO2 operations accessible via the YKFFIDO2Session.

• U2F - Provides U2F operations accessible via the YKFU2FSession.

• OATH - Allows applications, such as an authenticator app to store OATH TOTP and HOTP secrets on a YubiKey and generate one-time passwords.

• OTP - Provides implementation classes to obtain YubiKey OTP via accessory (5Ci) or NFC.

• PIV - Provides PIV operations accessible via the YKFPIVSession.

• Challenge-response - Provides a method to use HMAC-SHA1 challenge-response.

• Management - Provides ability to enable or disable available application on YubiKey

• SmartCardInterface - Provides low level access to the Yubikey with which you can send custom APDUs to the key

YubiKit allows customizing some of its behavior by using YubiKitConfiguration and YubiKitExternalLocalization.

let localizedAlertMessage = NSLocalizedString("NFC_SCAN_MESSAGE", comment: "Scan your YubiKey.")
YubiKitExternalLocalization.nfcScanAlertMessage = localizedAlertMessage

#import <YubiKit/YubiKit.h>
...
NSString *localizedAlertMessage = NSLocalizedString(@"NFC_SCAN_MESSAGE", @"Scan your YubiKey.");
YubiKitExternalLocalization.nfcScanAlertMessage = localizedNfcScanAlertMessage;

Yubikit doesn't store any data locally on the device. This includes NSUserDefaults, application sandbox folders and Keychain. All the data required to perform an operation is stored in memory for the duration of the operation and then discarded.

Yubikit doesn't communicate with any services, like web services or other type of network communication. YubiKit is a library for sending, receiving and processing the data from a YubiKey.

YubiKit is a library which should be used only to interact with a device manufactured by Yubico. While some parts of it may work with other devices, the library was developed and tested to work with YubiKeys. When attaching a MFI accessory, YubiKit will always check if the manufacturer of the device is Yubico before connecting to it.

Yes, YubiKit is compiled to accommodate any modern iOS project. The supplied library is compiled with Position Independent code and Bitcode. The release version of the library is optimized (Fastest, smallest).

No, YubiKit is not logging in release mode. The logs from YubiKit will show only in debug builds to help the developer to see what YubiKit does. The same stands for assertions. YubiKit will assert in debug mode to warn the developer when invalid parameters are passed to the library or when something unexpected happened with the key. In release, the library will handle invalid states in different ways (e.g. returning nil if the object was not properly initialized, returning errors, etc.).

YubiKit should work on any modern version of iOS (10+) with a few exceptions*. It's recommended to always ask the users to upgrade to the latest version of iOS to protect them from known, old iOS issues. Supporting the last 2 version of iOS (n and n-1) is usually a good practice to keep the old versions of iOS out. According to Apple statistics, ~90-95% of all iOS devices run the latest 2 versions of iOS because upgrading the OS is free and Apple usually provides a device with upgrades for 5 years.

* Some versions of iOS had bugs affecting all external accessories. iOS 11.2 was one of them where the applications could not communicate with accessories due to some bugs in the XPC communication. The bug was fixed by Apple in iOS 11.2.6. For these reasons it's recommended to take in consideration rare but possible iOS bugs when designing the application.

Starting from Xcode 9, the IDE provides the ability to debug the application wirelessly. In this way the physical connector is not used for connecting the device to the computer, for debugging the application. This WWDC session explains the wireless debugging functionality in Xcode.

The USB-C type iOS devices, such as the iPad Pro 3rd generation, have limited support when using the YubiKey 5Ci or another type of YubiKey with USB-C connector. The OS is not officially supporting external accessories on these devices. However these devices support external USB keyboards, so the OTP functionality of the key will work and the key can be used to generate Yubico OTPs and HOTPs.

1. Xcode Help - Add a capability to a target
2. Xcode Help - Build settings reference
3. Technical Q&A QA1490 - Building Objective-C static libraries with categories
4. Apple Developer - Swift and Objective-C in the Same Project
5. Yubico - Developers website
6. Yubico - Online Demo for OTP and U2F
7. Yubico - OTP documentation
8. Yubico - What is U2F?
9. Yubico - YKOATH Protocol Specifications
10. FIDO Alliance - CTAP2 specifications
11. W3.org - Web Authentication: An API for accessing Public Key Credentials