Table of Contents

Class SecurityDomainSession

Namespace
Yubico.YubiKey.Scp
Assembly
Yubico.YubiKey.dll

Create a session for managing the Secure Channel Protocol (SCP) configuration of a YubiKey.

public sealed class SecurityDomainSession : ApplicationSession
Inheritance
object
SecurityDomainSession
Inherited Members

Remarks

See the User's Manual entry on SCP.

The Security Domain session provides secure communication and key management capabilities through both SCP03 (symmetric) and SCP11 (asymmetric) protocols. This session can be used in two ways:

  • For direct SCP management:
    • Managing SCP03 symmetric key sets (ENC, MAC, DEK)
    • Managing SCP11 asymmetric keys (EC public/private key pairs)
    • Configuring secure messaging parameters
    • Example: 
      using (var scp = new SecurityDomainSession(yubiKeyDevice, scpKeyParameters))
{
    // Manage SCP configuration
}
  • As a background security layer:
    • Secures communication (encrypted channel) with other applications (e.g., PIV, OTP, OATH, YubiHSM)
    • Provides authenticity and confidentiality (encrypted channel) for remote operations
    • Example: 
      using (var pivSession = new PivSession(yubiKeyDevice, scpKeyParameters))
{
    // Perform PIV operations with secure messaging
}

The session supports various key management operations:

  • Loading and replacing SCP03 key sets
  • Storing EC private keys (NIST P-256)
  • Storing EC public keys (NIST P-256)
  • Managing key certificates and metadata
  • Deleting keys and resetting configurations

The constructor will throw an exception if:

  • The YubiKey does not support SCP
  • The provided key parameters are incorrect

Constructors

SecurityDomainSession(IYubiKeyDevice)

Create an unauthenticated instance of SecurityDomainSession, the object that manages the security domain on the YubiKey.

public SecurityDomainSession(IYubiKeyDevice yubiKey)

Parameters

yubiKey IYubiKeyDevice

The object that represents the actual YubiKey which will perform the operations.

Remarks

Sessions created from this constructor will not be able to perform operations which require authentication

See GlobalPlatform Technology Card Specification v2.3.1 §11 APDU Command Reference for more information.

Exceptions

ArgumentNullException

The yubiKey argument is null.

SecurityDomainSession(IYubiKeyDevice, ScpKeyParameters)

Create an instance of SecurityDomainSession, the object that manages the security domain on the YubiKey.

public SecurityDomainSession(IYubiKeyDevice yubiKey, ScpKeyParameters scpKeyParameters)

Parameters

yubiKey IYubiKeyDevice

The object that represents the actual YubiKey which will perform the operations.

scpKeyParameters ScpKeyParameters

The shared secret keys that will be used to authenticate the caller and encrypt the communications.

Remarks

See the User's Manual entry on SCP.

See GlobalPlatform Technology Card Specification v2.3.1 §11 APDU Command Reference for more information on SCP.

Because this class implements IDisposable, use the using keyword. For example, 

if (YubiKeyDevice.TryGetYubiKey(serialNumber, out IYubiKeyDevice yubiKeyDevice))
{
    using (var scp = new SecurityDomainSession(yubiKeyDevice, Scp03KeyParameters.DefaultKey))
    {
        // Perform SCP operations while authenticated with SCP03
    }
}

Exceptions

ArgumentNullException

The yubiKey or scpKeys argument is null.

Methods

ClearAllowList(KeyReference)

Clears the allow list for the given KeyReference

public void ClearAllowList(KeyReference keyReference)

Parameters

keyReference KeyReference

The key reference that holds the allow list

See Also

DeleteKey(KeyReference, bool)

Delete one (or more) keys matching the specified criteria.

public void DeleteKey(KeyReference keyReference, bool deleteLast = false)

Parameters

keyReference KeyReference

A reference to the key(s) to delete.

deleteLast bool

Must be true if deleting the final key, false otherwise.

Remarks

All keys matching the given KID (Key ID) and/or KVN (Key Version Number) will be deleted, where 0 is treated as a wildcard. For SCP03 keys, they can only be deleted by KVN.

Exceptions

ArgumentException

Thrown when both KID and KVN are 0, or when attempting to delete SCP03 keys by KID.

SecureChannelException

Thrown when the delete operation fails.

GenerateEcKey(KeyReference, byte)

Generate a new EC key pair for the given key reference.

public ECPublicKey GenerateEcKey(KeyReference keyReference, byte replaceKvn)

Parameters

keyReference KeyReference

The KID-KVN pair of the key that should be generated.

replaceKvn byte

The key version number of the key set that should be replaced, or 0 to generate a new key pair.

Returns

ECPublicKey

The parameters of the generated key, including the curve and the public point.

Remarks

GlobalPlatform has no command to generate key pairs on the card itself. This is a Yubico extension that tries to mimic the format of the GPC PUT KEY command.

Exceptions

SecureChannelException

Thrown when there was an SCP error, described in the exception message.

GetCardRecognitionData()

Retrieves the card recognition data from the YubiKey device.

public ReadOnlyMemory<byte> GetCardRecognitionData()

Returns

ReadOnlyMemory<byte>

The card recognition data as a byte array.

Remarks

The card recognition data is a TLV (Tag-Length-Value) encoded structure that contains information about the card. See GlobalPlatform Technology Card Specification v2.3.1 §H.2 Structure of Card Recognition Data for more information.

GetCertificates(KeyReference)

Retrieves the certificates associated with the given keyReference.

public IReadOnlyList<X509Certificate2> GetCertificates(KeyReference keyReference)

Parameters

keyReference KeyReference

The key reference for which the certificates should be retrieved.

Returns

IReadOnlyList<X509Certificate2>

A list of X.509 certificates associated with the key reference. The leaf certificate is the last certificate in the list

Exceptions

SecureChannelException

Thrown when there was an SCP error, described in the exception message.

GetData(int, ReadOnlyMemory<byte>?)

Gets data from the YubiKey associated with the given tag.

public ReadOnlyMemory<byte> GetData(int tag, ReadOnlyMemory<byte>? data = null)

Parameters

tag int

The tag of the data to retrieve.

data ReadOnlyMemory<byte>?

Optional data to send with the command.

Returns

ReadOnlyMemory<byte>

The encoded tlv data retrieved from the YubiKey.

Remarks

Sessions created from this constructor will not be able to perform operations which require authentication

See GlobalPlatform Technology Card Specification v2.3.1 §11 APDU Command Reference for more information.

Exceptions

SecureChannelException

Thrown when there was an SCP error, described in the exception message.

GetKeyInformation()

Retrieves the key information stored in the YubiKey and returns it in a dictionary format.

public IReadOnlyDictionary<KeyReference, Dictionary<byte, byte>> GetKeyInformation()

Returns

IReadOnlyDictionary<KeyReference, Dictionary<byte, byte>>

A read only dictionary containing the KeyReference as the key and a dictionary of key components as the value.

Exceptions

SecureChannelException

Thrown when there was an SCP error, described in the exception message.

GetSupportedCaIdentifiers(bool, bool)

Gets the supported CA identifiers for KLOC and/or KLCC.

public IReadOnlyDictionary<KeyReference, ReadOnlyMemory<byte>> GetSupportedCaIdentifiers(bool kloc, bool klcc)

Parameters

kloc bool

Whether to retrieve Key Loading OCE Certificate (KLOC) identifiers.

klcc bool

Whether to retrieve Key Loading Card Certificate (KLCC) identifiers.

Returns

IReadOnlyDictionary<KeyReference, ReadOnlyMemory<byte>>

A dictionary of KeyReference and byte arrays representing the CA identifiers.

Exceptions

ArgumentException

Thrown when both kloc and klcc are false.

SecureChannelException

Thrown when there was an SCP error, described in the exception message.

PutKey(KeyReference, ECPrivateKey, int)

Puts an EC private key onto the YubiKey using the Security Domain.

public void PutKey(KeyReference keyReference, ECPrivateKey privateKeyParameters, int replaceKvn = 0)

Parameters

keyReference KeyReference

The key reference identifying where to store the key.

privateKeyParameters ECPrivateKey

The EC private key parameters to store.

replaceKvn int

The key version number to replace, or 0 for a new key (Default value is 0).

Exceptions

ArgumentException

Thrown when the private key is not of type NIST P-256.

InvalidOperationException

Thrown when no secure session is established.

SecureChannelException

Thrown when the new key set's checksum failed to verify, or some other SCP related error described in the exception message.

PutKey(KeyReference, ECPublicKey, int)

Puts an EC public key onto the YubiKey using the Security Domain.

public void PutKey(KeyReference keyReference, ECPublicKey publicKey, int replaceKvn = 0)

Parameters

keyReference KeyReference

The key reference identifying where to store the key.

publicKey ECPublicKey

The EC public key parameters to store.

replaceKvn int

The key version number to replace, or 0 for a new key (Default value is 0).

Exceptions

ArgumentException

Thrown when the public key is not of type SECP256R1.

InvalidOperationException

Thrown when no secure session is established.

SecureChannelException

Thrown when the new key set's checksum failed to verify, or some other SCP related error described in the exception message.

PutKey(KeyReference, StaticKeys, int)

Puts an SCP03 key set onto the YubiKey using the Security Domain.

public void PutKey(KeyReference keyReference, StaticKeys staticKeys, int replaceKvn = 0)

Parameters

keyReference KeyReference

The key reference identifying where to store the key.

staticKeys StaticKeys

The new SCP03 key set to store.

replaceKvn int

The key version number to replace, or 0 for a new key (Default value is 0).

Exceptions

ArgumentException

Thrown when the KID is not 0x01 for SCP03 key sets.

SecureChannelException

Thrown when the new key set's checksum failed to verify, or some other SCP related error described in the exception message.

Reset()

Perform a factory reset of the Security Domain. This will remove all keys and associated data, as well as restore the default SCP03 static keys, and generate a new (attestable) SCP11b key.

public void Reset()

StoreAllowlist(KeyReference, IReadOnlyCollection<string>)

Stores an allowlist of certificate serial numbers for a specified key reference using the GlobalPlatform STORE DATA command.

public void StoreAllowlist(KeyReference keyReference, IReadOnlyCollection<string> serials)

Parameters

keyReference KeyReference

A reference to the key for which the allowlist will be stored.

serials IReadOnlyCollection<string>

The list of certificate serial numbers (in hexadecimal string format) to be stored in the allowlist for the given KeyReference.

Remarks

This method requires off-card entity verification. If an allowlist is not stored, any certificate signed by the CA can be used.

See GlobalPlatform Technology Card Specification v2.3.1 §11 APDU Command Reference for more information.

Exceptions

ArgumentException

Thrown when a serial number cannot be encoded properly.

SecureChannelException

Thrown when there was an SCP error, described in the exception message.

StoreCaIssuer(KeyReference, ReadOnlyMemory<byte>)

Store the SKI (Subject Key Identifier) for the CA of a given key. Requires off-card entity verification.

public void StoreCaIssuer(KeyReference keyReference, ReadOnlyMemory<byte> ski)

Parameters

keyReference KeyReference

A reference to the key for which to store the CA issuer.

ski ReadOnlyMemory<byte>

The Subject Key Identifier to store.

StoreCertificates(KeyReference, IReadOnlyList<X509Certificate2>)

Store a list of certificates associated with the given key reference using the GlobalPlatform STORE DATA command.

public void StoreCertificates(KeyReference keyReference, IReadOnlyList<X509Certificate2> certificates)

Parameters

keyReference KeyReference

The key reference associated with the certificates.

certificates IReadOnlyList<X509Certificate2>

The certificates to store.

Remarks

The certificates will be stored in the order they are provided in the list.

See GlobalPlatform Technology Card Specification v2.3.1 §11 APDU Command Reference for more information.

Exceptions

ArgumentException

Thrown when certificatedata

SecureChannelException

Thrown when there was an SCP error, described in the exception message.

StoreData(ReadOnlyMemory<byte>)

Stores data in the Security Domain or targeted Application on the YubiKey using the GlobalPlatform STORE DATA command.

public void StoreData(ReadOnlyMemory<byte> data)

Parameters

data ReadOnlyMemory<byte>

The data to be stored, which must be formatted as BER-TLV structures according to ISO 8825.

Remarks

The STORE DATA command is used to transfer data to either the Security Domain itself or to an Application being personalized. The data must be formatted as BER-TLV structures according to ISO 8825.

This implementation: - Uses a single block transfer (P1.b8=1 indicating last block) - Requires BER-TLV formatted data (P1.b5-b4=10) - Does not provide encryption information (P1.b7-b6=00)

See GlobalPlatform Technology Card Specification v2.3.1 §11 APDU Command Reference for more information.

The SecurityDomainSession makes use of this method to store data in the Security Domain. Such as the StoreCaIssuer(KeyReference, ReadOnlyMemory<byte>), StoreCertificates(KeyReference, IReadOnlyList<X509Certificate2>), StoreAllowlist(KeyReference, IReadOnlyCollection<string>), and other data.

Exceptions

InvalidOperationException

Thrown when no secure connection is available or the security context is invalid.

SecureChannelException

Thrown when there was an SCP error, described in the exception message.