From afce6ebefe38a96a4c095612129751f8106bb14d Mon Sep 17 00:00:00 2001 From: Luke Walker Date: Wed, 26 Jun 2024 12:38:17 -0700 Subject: [PATCH 1/9] Remove obsolete projects with low traffic <= 1% total views --- content/projects/libykneomgr/.conf.json | 9 --------- content/projects/wordpress-u2f/.conf.json | 9 --------- content/projects/yubiadmin/.conf.json | 9 --------- content/projects/yubiauth/.conf.json | 9 --------- content/projects/yubico-windows-auth/.conf.json | 9 --------- content/projects/yubikey-neo-manager/.conf.json | 9 --------- content/projects/yubikey-salesforce-client/.conf.json | 9 --------- content/projects/yubix-vm/.conf.json | 9 --------- content/projects/yubix/.conf.json | 9 --------- 9 files changed, 81 deletions(-) delete mode 100644 content/projects/libykneomgr/.conf.json delete mode 100644 content/projects/wordpress-u2f/.conf.json delete mode 100644 content/projects/yubiadmin/.conf.json delete mode 100644 content/projects/yubiauth/.conf.json delete mode 100644 content/projects/yubico-windows-auth/.conf.json delete mode 100644 content/projects/yubikey-neo-manager/.conf.json delete mode 100644 content/projects/yubikey-salesforce-client/.conf.json delete mode 100644 content/projects/yubix-vm/.conf.json delete mode 100644 content/projects/yubix/.conf.json diff --git a/content/projects/libykneomgr/.conf.json b/content/projects/libykneomgr/.conf.json deleted file mode 100644 index d0909c82c..000000000 --- a/content/projects/libykneomgr/.conf.json +++ /dev/null @@ -1,9 +0,0 @@ -{ - "template": { - "inherit": { - "github": { - "name": "libykneomgr" - } - } - } -} diff --git a/content/projects/wordpress-u2f/.conf.json b/content/projects/wordpress-u2f/.conf.json deleted file mode 100644 index ff4c9d46c..000000000 --- a/content/projects/wordpress-u2f/.conf.json +++ /dev/null @@ -1,9 +0,0 @@ -{ - "template": { - "inherit": { - "github": { - "name": "wordpress-u2f" - } - } - } -} diff --git a/content/projects/yubiadmin/.conf.json b/content/projects/yubiadmin/.conf.json deleted file mode 100644 index eea6e3139..000000000 --- a/content/projects/yubiadmin/.conf.json +++ /dev/null @@ -1,9 +0,0 @@ -{ - "template": { - "inherit": { - "github": { - "name": "yubiadmin" - } - } - } -} diff --git a/content/projects/yubiauth/.conf.json b/content/projects/yubiauth/.conf.json deleted file mode 100644 index 53834f7d9..000000000 --- a/content/projects/yubiauth/.conf.json +++ /dev/null @@ -1,9 +0,0 @@ -{ - "template": { - "inherit": { - "github": { - "name": "yubiauth" - } - } - } -} diff --git a/content/projects/yubico-windows-auth/.conf.json b/content/projects/yubico-windows-auth/.conf.json deleted file mode 100644 index 7cdb5d3ed..000000000 --- a/content/projects/yubico-windows-auth/.conf.json +++ /dev/null @@ -1,9 +0,0 @@ -{ - "template": { - "inherit": { - "github": { - "name": "yubico-windows-auth" - } - } - } -} diff --git a/content/projects/yubikey-neo-manager/.conf.json b/content/projects/yubikey-neo-manager/.conf.json deleted file mode 100644 index eea03378e..000000000 --- a/content/projects/yubikey-neo-manager/.conf.json +++ /dev/null @@ -1,9 +0,0 @@ -{ - "template": { - "inherit": { - "github": { - "name": "yubikey-neo-manager" - } - } - } -} diff --git a/content/projects/yubikey-salesforce-client/.conf.json b/content/projects/yubikey-salesforce-client/.conf.json deleted file mode 100644 index c491b3ac4..000000000 --- a/content/projects/yubikey-salesforce-client/.conf.json +++ /dev/null @@ -1,9 +0,0 @@ -{ - "template": { - "inherit": { - "github": { - "name": "yubikey-salesforce-client" - } - } - } -} diff --git a/content/projects/yubix-vm/.conf.json b/content/projects/yubix-vm/.conf.json deleted file mode 100644 index 00ba22faf..000000000 --- a/content/projects/yubix-vm/.conf.json +++ /dev/null @@ -1,9 +0,0 @@ -{ - "template": { - "inherit": { - "github": { - "name": "yubix-vm" - } - } - } -} diff --git a/content/projects/yubix/.conf.json b/content/projects/yubix/.conf.json deleted file mode 100644 index 1e961fd0c..000000000 --- a/content/projects/yubix/.conf.json +++ /dev/null @@ -1,9 +0,0 @@ -{ - "template": { - "inherit": { - "github": { - "name": "yubix" - } - } - } -} From 7b0aed441a7e3afcb4ef0b66d02dff6bb3fa4cc4 Mon Sep 17 00:00:00 2001 From: Luke Walker Date: Wed, 26 Jun 2024 12:55:19 -0700 Subject: [PATCH 2/9] OTP plugin deprecation update --- .../Yubico_OTP_Integration_Plug-ins/index.adoc | 10 +++++----- content/projects/rlm-yubico/.conf.json | 9 --------- 2 files changed, 5 insertions(+), 14 deletions(-) delete mode 100644 content/projects/rlm-yubico/.conf.json diff --git a/content/Software_Projects/Yubico_OTP/Yubico_OTP_Integration_Plug-ins/index.adoc b/content/Software_Projects/Yubico_OTP/Yubico_OTP_Integration_Plug-ins/index.adoc index a433affca..b26cb369b 100644 --- a/content/Software_Projects/Yubico_OTP/Yubico_OTP_Integration_Plug-ins/index.adoc +++ b/content/Software_Projects/Yubico_OTP/Yubico_OTP_Integration_Plug-ins/index.adoc @@ -1,12 +1,12 @@ == Yubico OTP Integration Plug-ins These plug-ins enable you to integrate Yubico OTP support into existing systems. -Windows login:: link:/yubico-windows-auth[yubico-windows-auth] -YubiAuth:: link:/yubiauth[yubiauth] PAM module:: link:/yubico-pam[yubico-pam] -FreeRADIUS:: link:/rlm-yubico[rlm-yubico] -Shibboleth:: https://github.com/Yubico/yubico-shibboleth-idp-multifactor-login-handler[yubico-shibboleth] -JAAS:: link:/yubico-java-client[yubico-java-client] +Windows login:: link:/https://github.com/Yubico/yubico-windows-auth[yubico-windows-auth] is deprecated and no longer maintained +YubiAuth:: link:/https://github.com/Yubico/yubiauth[yubiauth] is deprecated and no longer maintained +FreeRADIUS:: link:/https://github.com/Yubico/rlm-yubico[rlm-yubico] is deprecated and no longer maintained +Shibboleth:: link:/https://github.com/Yubico/yubico-shibboleth-idp-multifactor-login-handler[yubico-shibboleth] is deprecated and no longer maintained +JAAS:: link:/https://github.com/Yubico/yubico-java-client[yubico-java-client] is deprecated and no longer maintained Third party plugins can be discovered on link:https://github.com/search?q=yubico+otp[GitHub] for example. diff --git a/content/projects/rlm-yubico/.conf.json b/content/projects/rlm-yubico/.conf.json deleted file mode 100644 index d943504ac..000000000 --- a/content/projects/rlm-yubico/.conf.json +++ /dev/null @@ -1,9 +0,0 @@ -{ - "template": { - "inherit": { - "github": { - "name": "rlm-yubico" - } - } - } -} From 63f6be50bff140fa1f3e2ca4b7e4e406382f0b47 Mon Sep 17 00:00:00 2001 From: Luke Walker Date: Wed, 26 Jun 2024 13:50:39 -0700 Subject: [PATCH 3/9] Deprecate YubiClip --- content/Developer_Program/Guides/Touch_triggered_OTP.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/Developer_Program/Guides/Touch_triggered_OTP.adoc b/content/Developer_Program/Guides/Touch_triggered_OTP.adoc index 117ee6d8c..cd83df8d1 100644 --- a/content/Developer_Program/Guides/Touch_triggered_OTP.adoc +++ b/content/Developer_Program/Guides/Touch_triggered_OTP.adoc @@ -31,12 +31,12 @@ An off-the-shelf YubiKey comes with OTP slot 1 configured with a Yubico OTP regi == How do I use the Touch-Triggered OTPs on a Mobile Device? When using the YubiKey as a Touch-Triggered One-Time Password (OTP) device on a mobile platform, the user experience is slightly different. The act of tapping and holding an NFC-enabled YubiKey to the NFC reader on a mobile device takes the place of touching the gold contact to generate an OTP. -The OTP is passed as part of the NDEF tag, which is supported on most mobile devices with NFC. Once sent, the NDEF tag can be captured by an app on the mobile platform, which can then extract the OTP and utilize it. For iOS and Android, Yubico offers a mobile SDK to support this user experience. Further, on Android, Yubico offers the YubiClip app, which will capture the OTP and save it to the device clipboard for use. +The OTP is passed as part of the NDEF tag, which is supported on most mobile devices with NFC. Once sent, the NDEF tag can be captured by an app on the mobile platform, which can then extract the OTP and utilize it. For iOS and Android, Yubico offers a mobile SDK to support this user experience. Further, Yubico offers the Yubico Authenticator Android and iOS apps, which help manage OTPs on the YubiKey. * link:https://developers.yubico.com/Software_Projects/Mobile_SDK/[YubiKit iOS SDK] * link:https://developers.yubico.com/Software_Projects/Mobile_SDK/[YubiKit Android SDK] -* link:https://play.google.com/store/apps/details?id=com.yubico.yubiclip&hl=en_US[YubiClip on Google Play] -* link:https://github.com/Yubico/yubiclip-android[YubiClip Source code] +* link:https://github.com/Yubico/yubioath-flutter[Yubico Authenticator for Android] +* link:https://github.com/Yubico/yubioath-ios[Yubico Authenticator for iOS] == How do I Load a Touch-Triggered OTP Configuration onto a YubiKey? The ability of YubiKey users to define their own OTP configurations and secrets and load them onto their device sets the YubiKey apart from its predecessors. Configurations are loaded using the same HID Keyboard channel, leveraging the flexibility of the HID keyboard specifications to use “endpoint 0” (host to keyboard) to send commands to the YubiKey. From 5b7138137327b95febcc889d936e700cfd7c1526 Mon Sep 17 00:00:00 2001 From: Luke Walker Date: Thu, 27 Jun 2024 12:20:09 -0700 Subject: [PATCH 4/9] deprecate yubicloud libraries --- content/OTP/OTP_Walk-Through.adoc | 409 ++++++------------ .../YubiCloud_Connector_Libraries/index.adoc | 13 +- content/index.partial | 28 +- 3 files changed, 149 insertions(+), 301 deletions(-) diff --git a/content/OTP/OTP_Walk-Through.adoc b/content/OTP/OTP_Walk-Through.adoc index 3e51ab686..0f890df7d 100644 --- a/content/OTP/OTP_Walk-Through.adoc +++ b/content/OTP/OTP_Walk-Through.adoc @@ -1,305 +1,150 @@ == One-Time Password (OTP) Walk-Through - -We are going to go through integrating the Yubico One-Time Password (OTP) protocol with your application or framework, step by step. - -TIP: This walk-through is designed for people who prefer *learning by doing*. If you prefer to learn concepts from the ground up, check out our link:https://developers.yubico.com/content/OTP/YubiKey-Authentication-Module-Design-Guideline-v1.0.pdf[YubiKey Authentication Module Design Guideline]. You should find this and the guide are complementary to each other. - -The walk-through is divided into several sections: - -* Overview provides the fundamentals of OTP -* Setup provides you with a starting point to follow the walk-through -* Enable your Yubikey API Authenticator -* Create your Verification Client -* Add Authentication Logic - -We recommend you check out https://demo.yubico.com/otp/verify if you are new to OTP. - === Overview -With One-Time Password (OTP), symmetric-key cryptography is used to authenticate users against a central server, also known as a Relying Party (RP). The OTP is validated by a central server for users logging into your application. - -1. At production a symmetric key is generated and loaded on the YubiKey. This can be done by Yubico if you are using the YubiCloud, or by the user directly. +We are going to go through integrating the Yubico One-Time Password (OTP) protocol with your application or framework, step by step. This updated guide focuses on using the cloud-based YubiOTP validation service (YubiCloud) at `api.yubico.com``. -2. Then the symmetric key is shared with the validation server prior to being used to generate OTPs. This must be done at programming level since the key cannot be extracted from the YubiKey. Yubico handles uploading keys to the YubiCloud prior to selling YubiKeys. +TIP: This walk-through is designed for people who prefer learning by doing. If you prefer to learn concepts from the ground up, check out our link:https://resources.yubico.com/53ZDUYE6/as/pvknxfcmgb2kv6bjw8pvp2k/YubiKey-Authentication-Module-Design-Guideline-v10.pdf[YubiKey Authentication Module Design Guideline] from 2012. The guide and this walk-through are complementary. -3. When your user makes the request to log in, the YubiKey generates an OTP to be sent to the verification server (either the YubiCloud or a services' private verification server). The response from server verifies the OTP is valid. +Try out our OTP demo at https://demo.yubico.com/otp/verify. -4. After the OTP is verified, your application uses the public identity to validate that the YubiKey belongs to the user. +=== Overview of OTP -5. Then your user is allowed to log in to your application. +With One-Time Password (OTP), symmetric-key cryptography is used to authenticate users against a central server, known as a Relying Party (RP). The OTP is validated by a central server when users log into your application. -==== Prerequisites - -A computer with browser access and a YubiKey are all you really need to get started. +* **At production:** A symmetric key is generated and loaded on the YubiKey. This can be done by Yubico for YubiCloud users or by the user directly. +* **OTP Generation:** The YubiKey generates an OTP when a user requests to log in. This OTP is sent to the verification server (YubiCloud or a link:https://developers.yubico.com/Software_Projects/Yubico_OTP/YubiCloud_Validation_Servers/[self-hosted server]). +* **OTP Validation:** The server validates the OTP and confirms that it belongs to the user. +=== Prerequisites +* A computer with browser access +* A link:https://www.yubico.com/products/[YubiKey] === Setup -Incorporating YubiKey authentication into your application or platform uses the following four components. You will be creating, configuring, and using these items throughout this walk-through. - - * Verification server - * YubiKey API authenticator - * Verification client - * Authentication logic - - -*Verification server* - -Yubico provides the YubiCloud as a free OTP validation service. We recommend you use it. Optionally, you can self-host a verification server. See link:https://developers.yubico.com/Software_Projects/Yubico_OTP/YubiCloud_Validation_Servers/[YubiCloud Validation Servers] for options on creating your own verification server. - -The YubiCloud verification server validates the OTPs generated by the YubiKey. The verification server must have the secret uploaded to it prior to verifying OTPs. Every YubiKey is registered to the YubiCloud by default. - -If the YubiCloud configuration is overwritten, use the link:https://www.yubico.com/products/services-software/download/yubikey-manager/[YubiKey Manager] to re-register the YubiKey with the YubiCloud. - - - -*Your YubiKey API authenticator* - -Obtain a YubiKey. See link:https://www.yubico.com/products/[The YubiKey] - -In the steps, you will register your YubiKey to give you access to the Yubico API. - -You will also be able to run the OTP demo server to verify your application supports multiple YubiKeys per user. - - -*Your verification client* - -This is the core task in this walk-through. You will be setting up your verification server (YubiCloud) client. Your YubiCloud client provides the pass-through logic between your users, their YubiKeys, and YubiCloud. - - -*Authentication logic* - -This is the code you need to create and include in your application or framework. There are specific requirements to ensure one YubiKey provides access to multiple applications on a framework. - -=== Enable your Yubikey API Authenticator - -Sign up for and acquire your API key. - -==== Review YubiCloud and Client Interactions - -Optionally, for testing and example purposes, use a browser to view responses and actions in plain text. All the clients are a means to take the action and support applications. - - -*Step 1* Open a browser and insert your YubiKey into the appropriate port on your computer. - -The YubiKey connects to the api.yubico.com validation server. The browser displays: - - h=string of characters - t=timestamp - status=MISSING_PARAMETER - -*Step 2* Follow Keyboard Setup Assistant. - -a) Click Continue. - -b) Tap the YubiKey. The YubiKey in this case is the keyboard. - -c) Select Keyboard Type. Then click Done. - -d) Tap the YubiKey again. - -The browser page updates and completes an OTP. The first twelve modhex characters of the `opt=` form the Private Key for the inserted YubiKey. - - - h=string of characters - t=timestamp - otp=string of characters - nonce=string of characters - sl=100 - status=OK - - -==== Register Access to the Yubico API - -*Step 1* In a browser window, go to the Yubico API registration URL, link:https://upgrade.yubico.com/getapikey/[Yubico API key signup] - -a) Enter your email address. - -b) Generate an OTP from your API YubiKey in the OTP field. - -c) Accept the Terms and Conditions. - -d) Click Get API key. - - -*Step 2* Record the Client ID and Secret Key. - -These values are used to authenticate your users on the YubiCloud. One Client ID/Secret Key pair is required for every application you create. - -*Note:* These values are never shared again. Do not loose them. - -If any there is any reason Yubico needs to shut down your client access to the YubiCloud due to malicious activities, use the YubiKey values to verify your identity. - - - -=== Create your Verification Client - -For this phase of the process, you select a library and embed the Client ID and Secret Key in your library to create your YubiCloud client. - -When your users use their YubiKeys for authentication, your client does the following: - -• Implements the OTP transport protocol -• Parses the response from validation server (YubiCloud) - -*Step 1* Choose a Yubico OTP library or create your own. - - -For each client, the hooks for integration are different due to the different syntaxes and structure for each language. - -*Select from the libraries provided by Yubico* - -The PHP, dotNet and Java clients are called by an application, and should be imported as you would a standard library. The code to use them is included in the developer.yubico.com pages for each language, in the "Usage" sections. - - - * link:https://developers.yubico.com/php-yubico/[PHP] - - * link:https://developers.yubico.com/yubico-dotnet-client/[DotNET] - - * link:https://developers.yubico.com/yubico-java-client/[Java] - -The C client and perl client need to be integrated into an application by including the libraries in the standard manner. However, you need to build the client functions - this provides much more flexibility in the process, but does require additional work. The comments in the source code for the sample client applications detail the structure and steps. - - * link:https://developers.yubico.com/yubico-c-client/[C] - - * link:https://developers.yubico.com/yubico-perl-client/[Perl] - - * link:https://developers.yubico.com/windows-apis/[Windows] - -*Optionally, build your own library.* - -See link:[Creating your own library]https://developers.yubico.com/OTP/Libraries/Creating_your_own_library.html - -*Step 2* Create your YubiCloud client using your library and set the listed actions. - -See link:https://developers.yubico.com/OTP/Libraries/Using_a_library.html[Using a Yubico OTP library] - -a) Send requests. Add to your client: - - client = Yubico(clientId, secretKey) - -Enter the `clientId` and `secretKey` you saved from registering your YubiKey for an API Key, at link:https://upgrade.yubico.com/getapikey[]. - -b) Verify submitted OTPs. Add to your client: - - otp_is_valid = client.verify(otp) - -The `otp=` value is the OTP from the YubiKey that the user inserts. - -c) Verify user login. Add to your client: - - assert otp[:12] == user.yubikey_id - -`12` indicates the first twelve modhex characters from the `otp=` field. On the YubiCloud validation server, this value is compared with the YubiKey ID that is associated with the user. - -d) Provision user YubiKeys by assigning a YubiKey ID to a User ID. - - user.yubikey_id = otp[:12] - -Add these association entries to your database. For example: - - YubiKeyID : UserID - - -=== Add Authentication Logic to your Application - -In your application, add the logic needed to process registration and authentication requests. See link:https://developers.yubico.com/OTP/OTPs_Explained.html[OTPs Explained]. - -==== User Registration - -Enable users to register with your application or platform. - - -*Step 1* Expose a connection to your UI that accepts the OTP for launching the application. For example, instruct your users to insert the YubiKey. See link:https://developers.yubico.com/OTP/[What is Yubico OTP?]. This connection sends the OTP download to the YubiCloud client for validation. - -*Step 2* Use the YubiKey Public ID and associate it with the registering user. - -*Step 3* Store the `YubiKeyID : UserID` pairs in your database. - -*Step 4* Add logic in in your application to check the `UserID` for a valid OTP response from the YubiKey validation server. - - -==== User Authentication - -Do a logic check and ensure your registered users can authenticate with your application. See link:https://developers.yubico.com/OTP/OTPs_Explained.html[OTPs Explained]. - -During authentication: - -*Step 1* Ensure your application retrieves the OTP from an inserted and tab-touched YubiKey. - -For two-factor authentication, add a field or other means to enter credentials. Indicate that the YubiKey must also be inserted and tab-touched. - -*Step 2* Pass the OTP to your YubiCloud client. - -Your YubiCloud client validates the OTP in the YubiCloud. The YubiCloud validation server returns a response. - -*Step 3* Have your YubiCloud client parse the response. - -If a `valid` response is returned, proceed with the next step in authentication. - -If YubiCloud rejects the submitted OTP, forward the YubiCloud validation server error message. This message indicates an OTP/Client error. - -*Step 4* For a valid YubiCloud response, check the YubiKey public ID against the user ID pair in your database. - -If a `valid` response is returned, authenticate the user and log them in. - -If the YubiKey ID and User ID do not match, send an error message. Create an appropriate error message. As the developer, you are responsible for creating the public-facing error messages. - - -==== Inspecting the Code - - -Verify your client is compatible with your application code base and language. - - +Incorporating YubiKey authentication into your application involves the following components: + +. **Verification server:** YubiCloud or a link:https://developers.yubico.com/Software_Projects/Yubico_OTP/YubiCloud_Validation_Servers/[self-hosted server] +. **YubiKey API authenticator:** YubiKey for generating OTPs +. **Verification client:** Your application’s logic for communicating with YubiCloud +. **Authentication logic:** Code for handling user registration and login + +=== Enable Your YubiKey API Authenticator +. Sign up for and acquire your API key: +* Go to the link:https://upgrade.yubico.com/getapikey[Yubico API key signup] page. +* Enter your email address and generate an OTP from your YubiKey. +* Accept the Terms and Conditions and click "Get API key." +* Record the Client ID and Secret Key. These values authenticate your users with the YubiCloud. + +=== Create Your Verification Client +For this phase, you'll create a client to communicate with the YubiCloud. Here's a basic example using an HTTP GET request: + +**Using a Custom YubiCloud Client** + +. **Send requests:** ++ +[source, javascript] +``` +const clientId = 'your-client-id'; +const secretKey = 'your-secret-key'; +const otp = 'generated-otp-from-yubikey'; + +const url = `https://api.yubico.com/wsapi/2.0/verify?id=${clientId}&otp=${otp}&nonce=${generateNonce()}`; +fetch(url) + .then(response => response.json()) + .then(data => { + if (data.status === 'OK') { + console.log('OTP is valid'); + } else { + console.error('OTP validation failed:', data.status); + } + }); +``` ++ +. **Generate and verify signatures:** +* Use the link:https://developers.yubico.com/OTP/Specifications/OTP_validation_protocol.html[Yubico OTP Validation Protocol Version 2.0] to construct and verify signatures. +. **Associated the YubiKey ID with the User ID** +* Modhex (modified hexadecimal) is a base-16 encoding method that YubiKeys use to ensure compatibility with different keyboard layouts. Here is an example of converting between hex and modhex in JavaScript: ++ +[source, javascript] +``` +// Convert hex to modhex +function hexToModhex(hex) { + const modhexMap = { + '0': 'c', '1': 'b', '2': 'd', '3': 'e', '4': 'f', '5': 'g', '6': 'h', '7': 'i', + '8': 'j', '9': 'k', 'a': 'l', 'b': 'n', 'c': 'r', 'd': 't', 'e': 'u', 'f': 'v' + }; + return hex.split('').map(char => modhexMap[char.toLowerCase()]).join(''); +} + +// Convert modhex to hex +function modhexToHex(modhex) { + const hexMap = { + 'c': '0', 'b': '1', 'd': '2', 'e': '3', 'f': '4', 'g': '5', 'h': '6', 'i': '7', + 'j': '8', 'k': '9', 'l': 'a', 'n': 'b', 'r': 'c', 't': 'd', 'u': 'e', 'v': 'f' + }; + return modhex.split('').map(char => hexMap[char.toLowerCase()]).join(''); +} + +// Example usage: +const hexKey = 'abcdef1234567890'; +const modhexKey = hexToModhex(hexKey); +console.log('Modhex Key:', modhexKey); + +const backToHex = modhexToHex(modhexKey); +console.log('Back to Hex:', backToHex); +``` ++ +* Extract the YubiKey ID save to the user's credential repository ++ +[source, javascript] +``` +// Example OTP from YubiKey +const otp = 'cccccccfhjfjkknvubekedkrncrkruvvkiutlfibngd'; + +// Extract the YubiID (first 12 characters) +const yubiID = otp.substring(0, 12); +console.log('YubiID (modhex):', yubiID); + +// Convert YubiID from modhex to hex if needed +const hexYubiID = modhexToHex(yubiID); +console.log('YubiID (hex):', hexYubiID); +``` + +=== Add Authentication Logic to Your Application +In your application, add the logic needed to process registration and authentication requests. + +**User Registration** + +. Expose a connection to your UI to accept the OTP for launching the application. +. Use the YubiKey Public ID to associate it with the registering user. +. Store the YubiKeyID : UserID pairs in your database. +. Add logic to check the UserID for a valid OTP response from the YubiCloud validation server. + +**User Authentication** + +. Retrieve the OTP from an inserted and tapped YubiKey. +. Pass the OTP to your YubiCloud client. +. Parse the YubiCloud response. +. Verify the YubiKey public ID against the user ID pair in your database. +. Authenticate the user if the OTP is valid. === Wrapping Up - -Congratulations! You've completed all the steps to enable your users to register and authenticate with an OTP credential. +Congratulations! You’ve completed the steps to enable your users to register and authenticate with an OTP credential. === Additional Resources +* Help, I’m Stuck!: If you get stuck, check Stack Overflow. If you don’t receive an answer, file a GitHub issue or open a link:https://support.yubico.com/hc/en-us/requests/new[support ticket with Yubico]. +* **Plug-ins for Creating your YubiKey OTP Module:** +** link:[Yubico PAM module] – For GNU/Linux, Solaris, and macOS user authentication. +** link:https://developers.yubico.com/OTP/Modhex_Converter.html[Modhex Converter] -==== Help, I'm Stuck! - -If you get stuck, you can check link:https://stackoverflow.com[Stack Overflow]. If you don't receive an answer, or remain stuck, please file an issue or open a support ticket and we'll help you out. - - -==== Plug-ins for Creating your YubiKey OTP Module - -View and download the relevant plug-in components. - -* link:https://developers.yubico.com/yubico-pam/[Yubico PAM module] – Pluggable Authentication Modules (PAM) for GNU/Linux, Solaris and macOS for user authentication. -- Requires -link:https://developers.yubico.com/yubico-c-client/[libykclient], -link:https://github.com/Yubico/yubico-pam[libpam-dev,] -cURL, -link:https://developers.yubico.com/yubico-c/[libyubiky], -link:https://developers.yubico.com/yubikey-personalization/[yubikey-personalization] - -* link:https://developers.yubico.com/yubico-java-client/[Yubico Java client] – For integrating YubiKey with your Java applications. -- Includes -link:https://github.com/Yubico/yubico-java-client/tree/master/jaas[JAAS], and -link:https://github.com/Yubico/yubico-java-client/tree/master/demo-server[demo server] - - -==== Libraries for Creating your YubiKey OTP Module - -View and download the relevant Yubico library components. - -* link:https://developers.yubico.com/php-yubico/[PHP] -- Includes -link:https://github.com/Yubico/php-yubico/blob/master/demo.php[demo.php], -link:https://github.com/Yubico/php-yubico/blob/master/example/db.sql[example/db.sql], -link:https://github.com/Yubico/php-yubico/blob/master/example/config.php[example/config.php], -link:https://github.com/Yubico/php-yubico/blob/master/example/Modhex_Calculator.php[Modhex_Calculator.php], -link:https://developers.yubico.com/OTP/Modhex_Converter.html[Modhex Converter] +=== Deprecated Libraries +The following are deprecated and archived: +* link:https://developers.yubico.com/php-yubico/[PHP] +* link:https://developers.yubico.com/yubico-dotnet-client/[DotNET] +* link:https://developers.yubico.com/yubico-java-client/[Java] * link:https://developers.yubico.com/yubico-c-client/[C] -* link:https://developers.yubico.com/yubico-java-client/[Java] -- Includes -link:https://github.com/Yubico/yubico-java-client/tree/master/jaas[JAAS], and -link:https://github.com/Yubico/yubico-java-client/tree/master/demo-server[demo server] - -* link:https://developers.yubico.com/yubico-dotnet-client/[DotNet] -- Uses `clientId` and `apiKey` from -link:https://upgrade.yubico.com/getapikey/[Yubico API key signup] - * link:https://developers.yubico.com/yubico-perl-client/[Perl] - * link:https://developers.yubico.com/windows-apis/[Windows] diff --git a/content/Software_Projects/Yubico_OTP/YubiCloud_Connector_Libraries/index.adoc b/content/Software_Projects/Yubico_OTP/YubiCloud_Connector_Libraries/index.adoc index 3e340f2a1..33a4157fe 100644 --- a/content/Software_Projects/Yubico_OTP/YubiCloud_Connector_Libraries/index.adoc +++ b/content/Software_Projects/Yubico_OTP/YubiCloud_Connector_Libraries/index.adoc @@ -5,13 +5,12 @@ Yubico has declared end-of-life for the YubiKey Validation Server (YK-VAL) and YubiKey Key Storage Module (YK-KSM). These have been moved to link://github.com/YubicoLabs/yubikey-ksm[YubicoLabs] as a reference architecture. See article, link://support.yubico.com/hc/en-us/articles/360021227000[YK-VAL, YK-KSM and YubiHSM 1 End-of-Life]. ====== -These libraries help with connecting to the YubiCloud for Yubico OTP validation from a number of different programming languages. Learn how to use a connector library link:/OTP/Libraries/Using_a_library.html[here]. +These libraries are deprecated and no longer maintained. They showed how to connect to the YubiCloud for Yubico OTP validation from a number of different programming languages. Learn how to use a connector library link:/OTP/Libraries/Using_a_library.html[here]. -PHP:: link:/php-yubico/[php-yubico] -C:: link:/yubico-c-client/[yubico-c-client] -Java:: link:/yubico-java-client/[yubico-java-client] -DotNET:: link:/yubico-dotnet-client/[yubico-dotnet-client] -Perl:: link:/yubico-perl-client/[yubico-perl-client] -Windows:: link:/windows-apis[COM API] +PHP:: link:https://github.com/Yubico/php-yubico/[php-yubico] (deprecated and no longer maintained) +C:: link:https://github.com/Yubico/yubico-c-client/[yubico-c-client] (deprecated and no longer maintained) +Java:: link:https://github.com/Yubico/yubico-java-client/[yubico-java-client] (deprecated and no longer maintained) +DotNET:: link:https://github.com/Yubico/yubico-dotnet-client/[yubico-dotnet-client] (deprecated and no longer maintained) +Perl:: link:https://github.com/Yubico/yubico-perl-client/[yubico-perl-client] (deprecated and no longer maintained) Third party implementations can be discovered on link:https://github.com/search?q=yubico+client[GitHub] for example. diff --git a/content/index.partial b/content/index.partial index 699081473..c55a1727f 100644 --- a/content/index.partial +++ b/content/index.partial @@ -204,39 +204,43 @@
- Java WebAuthn Server + Java WebAuthn Server Library - Python WebAuthn Server & CTAP + Python WebAuthn/FIDO2 Server Library - + - Yubico Desktop OATH Authenticator + C FIDO2 Library
- + - YubiKey Manager + .NET YubiKey SDK - + - Yubico Android OATH Authenticator + Yubico Mobile SDK for iOS - + - Java OTP Client + Yubico Mobile SDK for Android
- C CTAP Client + C FIDO2 Library - Python YubiHSM + Python YubiHSM Library + + + + Yubico Authenticator for Desktop and Android
From 0f3f12bd0e89e727c947bf0d61035806976cc6fe Mon Sep 17 00:00:00 2001 From: Luke Walker Date: Thu, 27 Jun 2024 12:37:58 -0700 Subject: [PATCH 5/9] Remove U2F from top menu --- content/.conf.json | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/content/.conf.json b/content/.conf.json index dd763dd4c..7928b6dbb 100644 --- a/content/.conf.json +++ b/content/.conf.json @@ -1,9 +1,9 @@ { "order": [ + "Passkeys", "WebAuthn", - "OTP", "CTAP", - "U2F", + "OTP", "OATH", "PGP", "PIV", @@ -16,7 +16,6 @@ "Mobile", "SSH", "Mobile_Dev", - "Passkeys", "Archive_Old_Dev_Docs" ], "project": "projects", From 9df745b18ad96c1e1af4be70d0c0d1ec0433af9c Mon Sep 17 00:00:00 2001 From: Luke Walker Date: Thu, 27 Jun 2024 13:30:43 -0700 Subject: [PATCH 6/9] YubicoLabs github template override --- content/.conf.json | 6 +++--- content/projects/yubikey-ksm/.conf.json | 3 ++- content/projects/yubikey-val/.conf.json | 3 ++- 3 files changed, 7 insertions(+), 5 deletions(-) diff --git a/content/.conf.json b/content/.conf.json index 7928b6dbb..cae1c6179 100644 --- a/content/.conf.json +++ b/content/.conf.json @@ -38,7 +38,7 @@ "template": { "define": { "github": { - "_defaults": { "branch": "master" }, + "_defaults": { "branch": "master", "org": "Yubico" }, "order": ["Releases", "Release_Notes", "Manuals"], "releases": { "dir": "Releases", @@ -46,7 +46,7 @@ }, "git": [ { - "url": "https://github.com/Yubico/%(name)s.git", + "url": "https://github.com/%(org)s/%(name)s.git", "branch": "%(branch)s", "files": [ ["README", "index.adoc"], @@ -83,7 +83,7 @@ "sidelinks": [ { "name": " Github", - "url": "https://github.com/Yubico/%(name)s" + "url": "https://github.com/%(org)s/%(name)s" } ] } diff --git a/content/projects/yubikey-ksm/.conf.json b/content/projects/yubikey-ksm/.conf.json index 43ee0b667..11426c9ea 100644 --- a/content/projects/yubikey-ksm/.conf.json +++ b/content/projects/yubikey-ksm/.conf.json @@ -2,7 +2,8 @@ "template": { "inherit": { "github": { - "name": "yubikey-ksm" + "name": "yubikey-ksm", + "org": "YubicoLabs" } } } diff --git a/content/projects/yubikey-val/.conf.json b/content/projects/yubikey-val/.conf.json index b17cab0a4..f42b9ce2e 100644 --- a/content/projects/yubikey-val/.conf.json +++ b/content/projects/yubikey-val/.conf.json @@ -20,7 +20,8 @@ "template": { "inherit": { "github": { - "name": "yubikey-val" + "name": "yubikey-val", + "org": "YubicoLabs" } } } From c023213e2127dda955e558e26ab27089e28551e5 Mon Sep 17 00:00:00 2001 From: Luke Walker Date: Fri, 28 Jun 2024 12:40:14 -0700 Subject: [PATCH 7/9] U2F library deprecation note --- .../FIDO_U2F/U2FVAL_Connector_Libraries/index.adoc | 13 +++++++++++++ .../FIDO_U2F/U2F_Host_Libraries/index.adoc | 12 ++++++++++++ .../FIDO_U2F/U2F_Server_Libraries/index.adoc | 13 +++++++++++++ .../FIDO_U2F/U2F_Validation_Servers/index.adoc | 13 +++++++++++++ 4 files changed, 51 insertions(+) diff --git a/content/Software_Projects/FIDO_U2F/U2FVAL_Connector_Libraries/index.adoc b/content/Software_Projects/FIDO_U2F/U2FVAL_Connector_Libraries/index.adoc index e4c67be3a..1fcdb7496 100644 --- a/content/Software_Projects/FIDO_U2F/U2FVAL_Connector_Libraries/index.adoc +++ b/content/Software_Projects/FIDO_U2F/U2FVAL_Connector_Libraries/index.adoc @@ -1,4 +1,17 @@ == U2FVAL Connector Libraries + +[Note] +====== +The U2F libraries are now deprecated and no longer maintained. We highly recommend transitioning to the FIDO2 libraries for enhanced security and compatibility. + +C:: link:/libfido2/[libfido2] +Java:: link:/java-webauthn-server/[java-webauthn-server] +Python:: link:/python-fido2/[python-fido2] + + +Learn more about link:/Passkeys[Passkeys], link:/WebAuthn[WebAuthn], and link:/CTAP[CTAP]. +====== + These libraries help with connecting to a link:/u2fval/[Yubico U2F Validation Server] from a number of different programming languages. diff --git a/content/Software_Projects/FIDO_U2F/U2F_Host_Libraries/index.adoc b/content/Software_Projects/FIDO_U2F/U2F_Host_Libraries/index.adoc index 460be16b1..fad87849f 100644 --- a/content/Software_Projects/FIDO_U2F/U2F_Host_Libraries/index.adoc +++ b/content/Software_Projects/FIDO_U2F/U2F_Host_Libraries/index.adoc @@ -1,4 +1,16 @@ == U2F Host Libraries + +[Note] +====== +The U2F libraries are now deprecated and no longer maintained. We highly recommend transitioning to the FIDO2 libraries for enhanced security and compatibility. + +Python:: link:/python-fido2/[python-fido2] +C:: link:/libfido2/[libfido2] +\.NET:: link:/https://docs.yubico.com/yesdk//[.NET YubiKey SDK] + +Learn more about link:/Passkeys[Passkeys], link:/WebAuthn[WebAuthn], and link:/CTAP[CTAP]. +====== + These libraries deal with communication on the (end-user) host side of things, such as handing data from a U2F enabled server and passing it to a U2F device connected over USB. If a U2F enabled web browser is going to be used by the end diff --git a/content/Software_Projects/FIDO_U2F/U2F_Server_Libraries/index.adoc b/content/Software_Projects/FIDO_U2F/U2F_Server_Libraries/index.adoc index d306740c9..bb9470aca 100644 --- a/content/Software_Projects/FIDO_U2F/U2F_Server_Libraries/index.adoc +++ b/content/Software_Projects/FIDO_U2F/U2F_Server_Libraries/index.adoc @@ -1,4 +1,17 @@ == U2F Server Libraries + +[Note] +====== +The U2F libraries are now deprecated and no longer maintained. We highly recommend transitioning to the FIDO2 libraries for enhanced security and compatibility. + +C:: link:/libfido2/[libfido2] +Java:: link:/java-webauthn-server/[java-webauthn-server] +Python:: link:/python-fido2/[python-fido2] + + +Learn more about link:/Passkeys[Passkeys], link:/WebAuthn[WebAuthn], and link:/CTAP[CTAP]. +====== + These libraries deal with the low level primitives of the U2F protocol and are a good starting point for anyone intending to implement their own U2F server. Learn how to use a U2F server library link:/U2F/Libraries/Using_a_library.html[here]. diff --git a/content/Software_Projects/FIDO_U2F/U2F_Validation_Servers/index.adoc b/content/Software_Projects/FIDO_U2F/U2F_Validation_Servers/index.adoc index 562eb018b..2685c95ed 100644 --- a/content/Software_Projects/FIDO_U2F/U2F_Validation_Servers/index.adoc +++ b/content/Software_Projects/FIDO_U2F/U2F_Validation_Servers/index.adoc @@ -1,4 +1,17 @@ == U2F Validation Servers + +[Note] +====== +The U2F libraries are now deprecated and no longer maintained. We highly recommend transitioning to the FIDO2 libraries for enhanced security and compatibility. + +C:: link:/libfido2/[libfido2] +Java:: link:/java-webauthn-server/[java-webauthn-server] +Python:: link:/python-fido2/[python-fido2] + + +Learn more about link:/Passkeys[Passkeys], link:/WebAuthn[WebAuthn], and link:/CTAP[CTAP]. +====== + Complete standalone U2F validation servers. * link:/u2fval/[u2fval] From 74e382c223b41d18065d614f673ff1198126556f Mon Sep 17 00:00:00 2001 From: Luke Walker Date: Fri, 28 Jun 2024 12:57:30 -0700 Subject: [PATCH 8/9] add U2F library deprecation note to guides --- content/U2F/Libraries/Using_a_library.adoc | 14 ++++++++++++++ content/U2F/Standalone_servers/index.adoc | 13 +++++++++++++ content/U2F/U2F_Walk-Through.adoc | 13 +++++++++++++ content/U2F/index.adoc | 12 ++++++++++++ 4 files changed, 52 insertions(+) diff --git a/content/U2F/Libraries/Using_a_library.adoc b/content/U2F/Libraries/Using_a_library.adoc index 4fcc4d9cf..bdaf90203 100644 --- a/content/U2F/Libraries/Using_a_library.adoc +++ b/content/U2F/Libraries/Using_a_library.adoc @@ -1,4 +1,17 @@ == Using a U2F library == + +[Note] +====== +The U2F libraries are now deprecated and no longer maintained. We highly recommend transitioning to the FIDO2 libraries for enhanced security and compatibility. + +C:: link:/libfido2/[libfido2] +Java:: link:/java-u2flib-server/[java-u2flib-server] +Python:: link:/python-fido2/[python-fido2] +\.NET:: link:/https://docs.yubico.com/yesdk//[.NET YubiKey SDK] + +Learn more about link:/Passkeys[Passkeys], link:/WebAuthn[WebAuthn], and link:/CTAP[CTAP]. +====== + Let us have a look at the U2F sequence diagram: [mscgen] @@ -132,3 +145,4 @@ For complete example code (both server and client) in various languages, have a === U2F error codes If you get an error, check out the link:Client_error_codes.html[client error codes]. + \ No newline at end of file diff --git a/content/U2F/Standalone_servers/index.adoc b/content/U2F/Standalone_servers/index.adoc index 577e7de56..7afa202b1 100644 --- a/content/U2F/Standalone_servers/index.adoc +++ b/content/U2F/Standalone_servers/index.adoc @@ -1,4 +1,17 @@ == Servers + +[Note] +====== +The U2F libraries are now deprecated and no longer maintained. We highly recommend transitioning to the FIDO2 libraries for enhanced security and compatibility. + +C:: link:/libfido2/[libfido2] +Java:: link:/java-u2flib-server/[java-u2flib-server] +Python:: link:/python-fido2/[python-fido2] +\.NET:: link:/https://docs.yubico.com/yesdk//[.NET YubiKey SDK] + +Learn more about link:/Passkeys[Passkeys], link:/WebAuthn[WebAuthn], and link:/CTAP[CTAP]. +====== + While it is quite easy to implement support for U2F by using a link:/U2F/Libraries/Using_a_library.html[server library], it is sometimes desirable to keep the U2F related logic outside of your application, making as diff --git a/content/U2F/U2F_Walk-Through.adoc b/content/U2F/U2F_Walk-Through.adoc index af798cc76..1434862f0 100644 --- a/content/U2F/U2F_Walk-Through.adoc +++ b/content/U2F/U2F_Walk-Through.adoc @@ -1,4 +1,17 @@ == U2F Walk-Through + +[Note] +====== +The U2F libraries are now deprecated and no longer maintained. We highly recommend transitioning to the FIDO2 libraries for enhanced security and compatibility. + +C:: link:/libfido2/[libfido2] +Java:: link:/java-u2flib-server/[java-u2flib-server] +Python:: link:/python-fido2/[python-fido2] +\.NET:: link:/https://docs.yubico.com/yesdk//[.NET YubiKey SDK] + +Learn more about link:/Passkeys[Passkeys], link:/WebAuthn[WebAuthn], and link:/CTAP[CTAP]. +====== + This walk-through describes how to integrate the Yubico Universal Second Factor (U2F) protocol with your application or framework. diff --git a/content/U2F/index.adoc b/content/U2F/index.adoc index 7690cf425..5a3685c34 100755 --- a/content/U2F/index.adoc +++ b/content/U2F/index.adoc @@ -48,6 +48,18 @@ For information about U2F and the implications of Apple's iOS 13.3, see: link:.. == Implementing +[Note] +====== +The U2F libraries are now deprecated and no longer maintained. We highly recommend transitioning to the FIDO2 libraries for enhanced security and compatibility. + +C:: link:/libfido2/[libfido2] +Java:: link:/java-u2flib-server/[java-u2flib-server] +Python:: link:/python-fido2/[python-fido2] +\.NET:: link:/https://docs.yubico.com/yesdk//[.NET YubiKey SDK] + +Learn more about link:/Passkeys[Passkeys], link:/WebAuthn[WebAuthn], and link:/CTAP[CTAP]. +====== + NOTE: U2F is a newer protocol and is only supported by Google Chrome/Chromium (v38+), Mozilla Firefox (v57+), and Opera (v40+) browsers. The current version of Firefox (v57) requires additional configuration for U2F to work, see the https://wiki.mozilla.org/Security/CryptoEngineering#Using_U2F_.2F_WebAuthn[Mozilla Wiki] for more details. We provide three alternatives: From 16e4db81ffb06dcf7c6bd91b3a6846b229df79eb Mon Sep 17 00:00:00 2001 From: Luke Walker Date: Fri, 28 Jun 2024 13:10:45 -0700 Subject: [PATCH 9/9] add one api.yibico.com announcement --- content/OTP/index.adoc | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/content/OTP/index.adoc b/content/OTP/index.adoc index 796840f31..bfa1e7e75 100755 --- a/content/OTP/index.adoc +++ b/content/OTP/index.adoc @@ -21,6 +21,14 @@ Apart from the general advantages of 2-factor authentication, Yubico OTP has the - *YubiKey ID embedded in OTP*. This allows for self-provisioning, as well as authenticating without a username. - *Easy to implement*. Using YubiCloud, supporting Yubico OTP is not much harder than supporting regular passwords. +== One api.yubico.com One HTTP GET +In 2020, Yubico consolidated all YubiOTP validation API servers behind a single endpoint: api.yubico.com. This modernized, cloud-based service enhances reliability and scalability. Customers now need only to make a single HTTP GET request to api.yubico.com for OTP validation. + +To optimize performance, domain names pointing to this service are geolocated, directing YubiCloud clients to the nearest endpoint. We recommend configuring your clients to use api.yubico.com if you haven't already done so. + +Please note that Yubico's legacy client libraries in PHP, C, .NET, Perl, and Java on GitHub are archived and will not be updated to support the new endpoint. These libraries previously handled multiple YubiCloud endpoints, a function now obsolete. Directly implementing the HTTP GET call in client applications removes the dependency on third-party libraries. + +For detailed guidance on generating and verifying signatures and constructing HTTP GET calls for OTP verification, refer to the link:/OTP/Specifications/OTP_validation_protocol.html[Yubico OTP Validation Protocol Version 2.0]. == Implementing We provide two alternatives: