ReadMsroots Method

ReadMsroots()

Returns the contents of the MSROOTS data objects.

C#
public byte[] ReadMsroots()

Returns

System.Byte[]

A new byte array containing the data stored in the MSROOTS data objects.

Exceptions

Type Condition
System.InvalidOperationException

The YubiKey encountered an error, such as an unreliable connection.

Remarks

The YubiKey PIV application can store data objects. There is a set of data elements defined by the PIV standard. See the User's Manual entry on GET DATA for information on these elements and their tags. The standard also allows for vendor-defined data objects. MSROOTS is one such vendor-defined element.

The intention of the MSROOTS data object is to store and retrieve a PKCS 7 construction containing a set of root certificates. These certificates will make it easier for the SDK to interface with the Microsoft Smart Card Base Crypto Service Provider (CSP).

Very few applications will need to use this feature. If you don't already know what the MSROOTS are, how to use them, and that they are part of your application already, then you almost certainly will never need to use this method.

This method will return whatever data is stored in the YubiKey under the tag "MSROOTS". This method will not verify that the data is a PKCS 7 construction, or that it contains root certificates, it will simply return the bytes from the data object.

While it is necessary to authenticate the management key in order to store the MSROOTS data (see WriteMsroots(ReadOnlySpan<Byte>)), it is not needed to retrieve this data. Anyone with access to a YubiKey can retrieve this data.

The method will return the data as a new byte array. It is possible there is no data on the YubiKey in the MSROOTS data objects. In that case, this method will return an empty byte array (Length of 0).

Note that YubiKey stores the data formatted as a TLV: 

  tag || length || value

for example, it might be


53 20 (contents, 32 bytes)


or


7F 61 20 (contents, 32 bytes)
The tag used varies depending on the data being stored. This method returns the contents, not the full TLV.

Note that the full amount of data might be stored in more than one data object. This method will collect all the data in all the MSROOTS data objects (in order) and concatenate.