Table of Contents

Class CardCapabilityContainer

Namespace
Yubico.YubiKey.Piv.Objects
Assembly
Yubico.YubiKey.dll

Use this class to process the CCC (Card Capability Container) data.

public sealed class CardCapabilityContainer : PivDataObject
Inheritance
object
CardCapabilityContainer
Inherited Members

Remarks

The PIV standard declares,

"The Card Capability Container (CCC) is a mandatory data object whose purpose is to facilitate compatibility of Government Smart Card Interoperability Specification (GSC-IS) applications with PIV Cards."

In other words, it's a holdover from the older smart card specification. In order to remain compatible with that older spec and with older applications, it might be necessary to read and write this data object.

There are many elements that make up the CCC, but most of them are ignored by PIV and the YubiKey. Other elements are fixed. Note that the PIV standard says,

"The data model of the PIV Card Application shall be identified by data model number 0x10. ... The content of the CCC data elements, other than the data model number, are out of scope for this specification."

There is only one element that can be set in this class, namely, the Card Identifier portion of the Unique Card Identifier. This is a 14-byte value. With the YubiKey, the caller sets it, or allows the SDK to set it to random bytes.

Upon manufacture, the CCC is "empty", so the IsEmpty property is true. This object will be considered empty until the Card Identifier is set. See SetCardId(ReadOnlySpan<byte>) and SetRandomCardId().

The following list indicates the elements of the CCC that can be found on a YubiKey.

  • Unique Card Identifier
  • Application Identifier (part of the Unique Card ID
  • GSC-RID (Registered Application Provider Identifier, part of the AID)
  • Card Identifier (part of the Unique Card ID)
  • Manufacturer ID
  • Card Type
  • Container Version Number
  • Grammar Version Number
  • PKCS #15 Version Number (for the YubiKey, this is 0x00 indicating PKCS #15 is not supported
  • Data Model Number

Constructors

CardCapabilityContainer()

Build a new object. This will not get the CCC from from any YubiKey, it will only build an "empty" object.

public CardCapabilityContainer()

Remarks

To read the CCC data out of a YubiKey, call a ReadObject<T>(int) method.

Properties

ApplicationIdentifier

The "AID" (Capabilities Application Identifier), which consists of the GSC-RID || ManufacturerID || CardType.

public ReadOnlyMemory<byte> ApplicationIdentifier { get; }

Property Value

ReadOnlyMemory<byte>

CardIdentifier

The actual Card Identifier portion of the Unique Card Identifier.

public ReadOnlyMemory<byte> CardIdentifier { get; }

Property Value

ReadOnlyMemory<byte>

CardType

The card type is fixed at JavaCard.

public int CardType { get; }

Property Value

int

ContainerVersionNumber

The version number of the CCC itself, it is fixed at version 2.1.

public byte ContainerVersionNumber { get; }

Property Value

byte

DataModelNumber

The number representing the Data Model used by the smart card. For the YubiKey it is fixed at 0x10 (a PIV requirement).

public byte DataModelNumber { get; }

Property Value

byte

GrammarVersionNumber

The version number of the CCC grammar, it is fixed at version 2.1.

public byte GrammarVersionNumber { get; }

Property Value

byte

GscRid

The "Government Smart Card - Registered Application Provider Identifier".

public ReadOnlyMemory<byte> GscRid { get; }

Property Value

ReadOnlyMemory<byte>

ManufacturerId

The manufacturer ID is fixed at 0xFF

public int ManufacturerId { get; }

Property Value

int

Pkcs15Version

The version of PKCS #15 the card supports. If the card does not support PKCS #15, this number is 0x00. For the YubiKey it is fixed at 0x00.

public byte Pkcs15Version { get; }

Property Value

byte

UniqueCardIdentifier

The full Unique Card Identifier which consists of the AID || CardID.

public ReadOnlyMemory<byte> UniqueCardIdentifier { get; }

Property Value

ReadOnlyMemory<byte>

Methods

Dispose(bool)

Releases any unmanaged resources and overwrites any sensitive data.

protected override void Dispose(bool disposing)

Parameters

disposing bool

Encode()

Build the encoding of the data.

public override byte[] Encode()

Returns

byte[]

A new byte array containing the encoded data object.

Remarks

Each data object has a defined format. See the User's Manual entry on GET DATA and GET vendor data for descriptions of the formats. This method will build a new byte array containing the data set in the object. This data will generally then be stored on the YubiKey.

Note that this method returns a new byte array, not a reference to an array inside the object. If this array contains any sensitive data, make sure you overwrite it when done with it.

If the object is empty (IsEmpty is true), then this method will return the encoding of no data, which is 0x53 00.

GetDefinedDataTag()

Get the defined data tag. This is the data tag that the PIV standard or Yubico defines to specify the given data object.

public override int GetDefinedDataTag()

Returns

int

The data tag defined for the data object.

Remarks

This is also called the default data tag. This method will always return the defined tag, regardless of what the DataTag property returns. That is, even if you change the DataTag this method will still return the original, defined tag.

SetCardId(ReadOnlySpan<byte>)

Set the CardIdentifier with the given value. If the array is not exactly 14 bytes, this method will throw an exception.

public void SetCardId(ReadOnlySpan<byte> cardIdValue)

Parameters

cardIdValue ReadOnlySpan<byte>

The CardId to use.

Remarks

If there is a CardId value already in this object, this method will overwrite it.

Exceptions

ArgumentException

The data is not exactly 14 bytes.

SetRandomCardId()

Set the CardId with a random, 14-byte value.

public void SetRandomCardId()

Remarks

This method will use the random number generator built by CryptographyProviders to generate 14 random bytes as the new CardId.

If there is a CardId value already in this object, this method will overwrite it.

TryDecode(ReadOnlyMemory<byte>)

Try to decode the data given according to the format specified for the data object. If successful, return true, otherwise, return false.

public override bool TryDecode(ReadOnlyMemory<byte> encodedData)

Parameters

encodedData ReadOnlyMemory<byte>

The data to parse.

Returns

bool

A boolean, true if the method successfully decodes, false otherwise.

Remarks

This will parse the encoding and set local properties with the data. The encodedData generally was retrieved from the YubiKey.

This will replace any data in the object.

If there is no data (encodedData.Length is 0) this method will set the object to the empty state (IsEmpty will be true and the contents of any data properties will be meaningless) and return true.

If the input is not encoded as expected, this method will set the object to the empty state and return false. This includes the fixed values. That is, there are some values in some data objects that are fixed for every YubiKey, and this method will expect the contents of the encodedData to contain those fixed values.

If the input is encoded as expected, yet the data in that encoding is invalid (e.g. some element is not the correct length), this method will return false.

Exceptions

ArgumentException

The data is not properly encoded for the data object.