1.13.0 - April 2025 Release

[DennisDyallo]

Release date: April 9th, 2025

Features:

Curve25519 support has been added for PIV #210:

Keys can now be imported or generated using the Ed25519 and X25519 algorithms.
The key agreement operation can be performed with an X25519 key.
Digital signatures can now be created with a Ed25519 key.
New related unit tests have been added.
Unit tests have been added for RSA-3072 and RSA-4096 keys #197.

Support for large APDUs has been improved #208:

When sending large APDU commands to a YubiKey via the smartcard connection, the CommandChainingTransform will now throw an exception when the cumulative APDU data (sent in chunks of up to 255 bytes) exceeds the max APDU size for the given YubiKey (varies based on firmware version; see SmartCardMaxApduSizes).
Support for Ed25519 and P384 credentials has been added for FIDO #186.

Ubuntu runners have been upgraded from version 20.04 to 22.04 to support the compilation of Yubico.NativeShims #188.

Bug Fixes:

The default logger now only writes output for the "Error" log level unless another level is specified #185. Previously, the logger wrote output for all log levels, which could become overly long and difficult to evaluate.

Miscellaneous:

The License was updated to remove the information for the AesCmac.cs file from the Bouncy Castle library #196.

What's changed

• docs: Documentation edits for SCP by @DennisDyallo in docs: Documentation edits for SCP #180
• fix: The default logger only writes output for the Error log level unless other is specified by @DennisDyallo in fix: The default logger only writes output for the Error log level unless other is specified #185
• ci: Only package artifacts on manual trigger (nativeshims) by @DennisDyallo in ci: Only package artifacts on manual trigger (nativeshims) #187
• ci: Upgrade Ubuntu runners from 20.04 to 22.04 by @DennisDyallo in ci: Upgrade Ubuntu runners from 20.04 to 22.04 #188
• Fix failing NativeShims build by @DennisDyallo in Fix failing NativeShims build #189
• Adding Appcompat.md to toc.tml for visibility on the documentation site by @equijano21 in Adding Appcompat.md to toc.tml for visibility on the documentation site #190
• misc: Removed Bouncy Castle license by @DennisDyallo in misc: Removed Bouncy Castle license #196
• Feature: Supports enumerating Ed25519 and P521 credentials within FIDO by @DennisDyallo in Feature: Supports enumerating Ed25519 and P521 credentials within FIDO #186
• merged transport article content into overview by @equijano21 in merged transport article content into overview #195
• Consolidated public, private key and certificate test data into manageable class by @DennisDyallo in refactor: Consolidated public, private key and certificate test data into manageable class #197
• Using PolySharp to allow use of C#13 by @DennisDyallo in Using PolySharp to allow use of C#13 #132
• feat: Skip waiting for the first connection to the key by @TimLico in feat: Skip waiting for the first connection to the key #203
• Rework of docfx docs building-process by @DennisDyallo in ci, docs: Rework of docfx docs building-process #201
• docs: add section on build asset attestation to README by @DennisDyallo in docs: add section on build asset attestation to README #206
• Add workflow to automate deployment of docs by @ajhall in ci: Add workflow to automate deployment of docs #207
• Update fido2-auth-tokens.md by @joostd in docs: Update fido2-auth-tokens.md #212
• fix: Stop send short APDUs when exceeded max APDU size by @DennisDyallo in fix: Stop send short APDUs when exceeded max APDU size #208
• Tim/revert initial three seconds delay changes by @TimLico in fix: Revert initial three seconds delay changes #213
• feature: Added Ed25519 and X25519 keys to the PIV application by @DennisDyallo in feat: Added Ed25519 and X25519 keys to the PIV application #210
• Release notes for 1.13 by @equijano21 in Release notes for 1.13 #214

New Contributors

• @TimLico made their first contribution in feat: Skip waiting for the first connection to the key #203
• @ajhall made their first contribution in ci: Add workflow to automate deployment of docs #207
• @joostd made their first contribution in docs: Update fido2-auth-tokens.md #212

Full Changelog: 1.12.1...1.13.0

---

This discussion was created from the release 1.13.0.

[DennisDyallo]

Edit, 2025-05-26: This post has been updated to correct an erroneous claim that the new key classes only supported newer YubiKeys, this is not the case. The new classes support all YubiKey firmware versions

Cryptography Key Classes in Yubico .NET SDK

The Yubico .NET SDK has introduced a new key hierarchy to enhance key management, improve type safety, and support additional key types including standard RSA, EC, and Curve25519 keys. This guide provides comprehensive information on using these new classes with the PIV application.

Overview of Changes

The SDK is transitioning from the legacy PivPrivateKey/PivPublicKey classes to the new interface-based IPrivateKey/IPublicKey approach. This change brings several benefits:

• Support for additional key types (RSA, EC, and Curve25519)
• Simplified disposal of sensitive data within new key classes
• Common interface to work with different key types throughout the SDK
• Improved type safety and consistency
• Reduced reliance on the PivAlgorithm enum
• Better integration with standard cryptographic operations

Key Type Hierarchy

All keys implement either the IPublicKey or IPrivateKey interfaces, with specific implementations:

• Public Keys

  • RSAPublicKey - For RSA keys
  • ECPublicKey - For standard elliptic curve keys
  • Curve25519PublicKey - For Ed25519 and X25519 keys

• Private Keys

  • RSAPrivateKey - For RSA keys
  • ECPrivateKey - For standard elliptic curve keys
  • Curve25519PrivateKey - For Ed25519 and X25519 keys

Available Key Types

The SDK supports the following key types, accessible via the KeyType enum:

KeyType	Description	Supported Operations
KeyType.RSA1024	1024-bit RSA key	Sign, Decrypt
KeyType.RSA2048	2048-bit RSA key	Sign, Decrypt
KeyType.RSA3072	3072-bit RSA key	Sign, Decrypt
KeyType.RSA4096	4096-bit RSA key	Sign, Decrypt
KeyType.ECP256	NIST P-256 elliptic curve	Sign, Key Agreement
KeyType.ECP384	NIST P-384 elliptic curve	Sign, Key Agreement
KeyType.Ed25519	Edwards curve (for EdDSA)	Sign
KeyType.X25519	Montgomery curve (for ECDH)	Key Agreement

Factory Methods for Key Creation

RSA Public Keys

// Create from PKCS#8 SubjectPublicKeyInfo format
byte[] encodedKey = /* your SubjectPublicKeyInfo bytes */;
IPublicKey rsaPublicKey = RSAPublicKey.CreateFromSubjectPublicKeyInfo(encodedKey);

// Create from parameters
RSAParameters parameters = /* your RSA parameters */;
RSAPublicKey rsaPublicKey = RSAPublicKey.CreateFromParameters(parameters);

RSA Private Keys

// Create from PKCS#8 PrivateKeyInfo format
byte[] encodedKey = /* your PKCS#8 PrivateKeyInfo bytes */;
RSAPrivateKey rsaPrivateKey = RSAPrivateKey.CreateFromPkcs8(encodedKey);

// Create from parameters
RSAParameters parameters = /* your RSA parameters */;
RSAPrivateKey rsaPrivateKey = RSAPrivateKey.CreateFromParameters(parameters);

EC Public Keys

// Create from PKCS#8 SubjectPublicKeyInfo format
byte[] encodedKey = /* your SubjectPublicKeyInfo bytes */;
IPublicKey ecPublicKey = ECPublicKey.CreateFromSubjectPublicKeyInfo(encodedKey);

// Create from EC parameters
ECParameters parameters = /* your EC parameters */;
ECPublicKey ecPublicKey = ECPublicKey.CreateFromParameters(parameters);

// Create from public point (0x04 || X-coordinate || Y-coordinate)
ReadOnlyMemory<byte> publicPoint = /* uncompressed EC point with 0x04 prefix */;
IPublicKey ecPublicKey = ECPublicKey.CreateFromValue(publicPoint, KeyType.ECP256);

EC Private Keys

// Create from PKCS#8 PrivateKeyInfo format
byte[] encodedKey = /* your PKCS#8 PrivateKeyInfo bytes */;
ECPrivateKey ecPrivateKey = ECPrivateKey.CreateFromPkcs8(encodedKey);

// Create from EC parameters
ECParameters parameters = /* your EC parameters with D value */;
ECPrivateKey ecPrivateKey = ECPrivateKey.CreateFromParameters(parameters);

// Create from private scalar value
ReadOnlyMemory<byte> privateValue = /* your private scalar value */;
ECPrivateKey ecPrivateKey = ECPrivateKey.CreateFromValue(privateValue, KeyType.ECP256);

Curve25519 Public Keys

// Create from PKCS#8 SubjectPublicKeyInfo format
byte[] encodedKey = /* your SubjectPublicKeyInfo bytes */;
Curve25519PublicKey curve25519PublicKey = Curve25519PublicKey.CreateFromSubjectPublicKeyInfo(encodedKey);

// Create from public point bytes
ReadOnlyMemory<byte> publicPoint = /* your public point bytes */;
Curve25519PublicKey curve25519PublicKey = Curve25519PublicKey.CreateFromValue(publicPoint, KeyType.Ed25519);
// Or for X25519
Curve25519PublicKey x25519PublicKey = Curve25519PublicKey.CreateFromValue(publicPoint, KeyType.X25519);

Curve25519 Private Keys

// Create from PKCS#8 PrivateKeyInfo format
byte[] encodedKey = /* your PKCS#8 PrivateKeyInfo bytes */;
Curve25519PrivateKey curve25519PrivateKey = Curve25519PrivateKey.CreateFromPkcs8(encodedKey);

// Create from private scalar value
ReadOnlyMemory<byte> privateKey = /* your private key bytes */;
Curve25519PrivateKey ed25519PrivateKey = Curve25519PrivateKey.CreateFromValue(privateKey, KeyType.Ed25519);
// Or for X25519
Curve25519PrivateKey x25519PrivateKey = Curve25519PrivateKey.CreateFromValue(privateKey, KeyType.X25519);

Using with PIV Session

Generating Key Pairs

The GenerateKeyPair method now accepts a KeyType parameter:

using Yubico.YubiKey;
using Yubico.YubiKey.Piv;
using Yubico.YubiKey.Cryptography;

using var pivSession = new PivSession(yubiKey)
// Setup key collector
pivSession.KeyCollector = yourKeyCollector;

// Authenticate with management key
pivSession.AuthenticateManagementKey();

// Generate an Ed25519 key pair
IPublicKey publicKey = pivSession.GenerateKeyPair(
    PivSlot.Authentication,
    KeyType.Ed25519,
    PivPinPolicy.Once,
    PivTouchPolicy.Never);

// Check the returned key type
if (publicKey is Curve25519PublicKey ed25519PublicKey)
{
    // Access the public point
    ReadOnlyMemory<byte> publicPoint = ed25519PublicKey.PublicPoint;
    
    // Export the key in SubjectPublicKeyInfo format
    byte[] exportedKey = ed25519PublicKey.ExportSubjectPublicKeyInfo();
}

Importing Private Keys

Import private keys with the ImportPrivateKey method:

// Create a private key to import
byte[] pkcs8EncodedKey = /* Load PKCS#8 private key */;
IPrivateKey privateKey = Curve25519PrivateKey.CreateFromPkcs8(pkcs8EncodedKey);

// Import into the YubiKey
using var pivSession = new PivSession(yubiKey)

pivSession.KeyCollector = yourKeyCollector;
pivSession.AuthenticateManagementKey();

pivSession.ImportPrivateKey(
    PivSlot.KeyManagement,
    privateKey,
    PivPinPolicy.Once,
    PivTouchPolicy.Never);

Key Agreement with X25519

Perform key agreement operations with X25519 keys:

// Generate or import an X25519 key
using var pivSession = new PivSession(yubiKey)

// Setup and authenticate
pivSession.KeyCollector = yourKeyCollector;
pivSession.VerifyPin();  // Required for cryptographic operations

// Get other party's public key
byte[] otherPartyPublicKeyBytes = /* Other party's X25519 public key */;

// Create a key agreement object (details depend on your implementation)
// This is a simplified example
Memory<byte> sharedSecret = new byte[32];
pivSession.KeyAgree(
    PivSlot.KeyManagement,  // Slot containing your private key
    otherPartyPublicKeyBytes, 
    sharedSecret);

// Use the shared secret for key derivation or encryption

Exporting Keys

Export keys in standard formats:

// Export public key in SubjectPublicKeyInfo format
byte[] spki = ecPublicKey.ExportSubjectPublicKeyInfo();

// Export private key in PKCS#8 PrivateKeyInfo format
byte[] pkcs8 = ecPrivateKey.ExportPkcs8PrivateKey();

Handling Key Data Securely

All private key classes implement secure cleanup methods:

// Using disposable pattern to ensure sensitive data is cleared
using (ECPrivateKey privateKey = ECPrivateKey.CreateFromPkcs8(encodedKey))
{
    // Use the private key
}

// The private key data is securely cleared from memory after disposal

// Using try-finally and clearing explicityly
try
{
    ECPrivateKey privateKey = ECPrivateKey.CreateFromPkcs8(encodedKey);
    // Use the private key
}
finally
{
    // Ensure sensitive data is cleared
    privateKey.Clear();
}

Migration Guide

The old PIV key types will still function, but are deprecated. The new classes are designed to be more usable and they support the new key types. Most users will find the new keys and their factory methods easy to use.
The old classes will be removed in a future version of the SDK.
When updating your code from the old API to the new one:

1. Replace PivAlgorithm values with the corresponding KeyType:

   • PivAlgorithm.Rsa2048 → KeyType.RSA2048
   • PivAlgorithm.EccP256 → KeyType.ECP256

2. Update key type handling:

   • PivPublicKey → IPublicKey (base interface)
   • PivPrivateKey → IPrivateKey (base interface)
   • Use type checking (e.g., is ECPublicKey) to access specific properties

3. Use the new factory methods for key creation:

   • RSAPublicKey.CreateFromSubjectPublicKeyInfo()
   • ECPrivateKey.CreateFromValue()
   • Curve25519PublicKey.CreateFromValue()

These new key classes provide a more robust, type-safe approach to cryptographic operations with YubiKeys, while supporting modern key types like Ed25519 and X25519.

[virot]

Important: The new key classes require YubiKey version 5.7 or greater.

and

The old classes will be removed in a future version of the SDK.

Does this mean products building on Yubico.NET.SDK will have to decide if to maintain combability for pre 5.7.0 or no new things in the future?

I have tested for instance "The GenerateKeyPair method now accepts a KeyType parameter" with a 5.2.7 YubiKey and it works.
Is new as in X25519 limited to newer keys?

[DennisDyallo]

Hi!
No ETA is set for removing obsolete classes as of yet, but rest assured it will be in a major version. Your products are safe.

PivPrivateKeys and PivPublicKeys will exist until that point. After that, the idea is that devs will have to use the implementations of IPublicKey and IPrivateKey to work with PivSession (and other YubiKey application sessions).

I hope this makes sense to you.

[virot]

I am more curious, about the line that says IPublicKey requires YubiKey 5.7 or greater. That would imply that when the major version comes all older are obsolete. And would require more from all depending products for keeping multiple code branches. I am all for switching, but of it means loosing all older firmware YubiKeys, its isn't an easy choice.

[DennisDyallo]

Hi @virot and thanks for keeping the discussion and question alive. That line should not have made the post and has been removed. The new classes are for all YubiKey versions. I have updated the OP to reflect this mistake.
Curious, do you know which array of versions your company has currently deployed?

[virot]

Hi, I know my current companies are running 5.4.3 and later at least.. I have a few 5.2 myself.
This is mostly due to my Powershell7 module. I will start to transition to the new model.