Class CardCapabilityContainer
Use this class to process the CCC (Card Capability Container) data.
public sealed class CardCapabilityContainer : PivDataObject
- Inheritance
-
objectCardCapabilityContainer
- 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.