ReplaceAttestationKeyAndCertificate Method

ReplaceAttestationKeyAndCertificate(PivPrivateKey, X509Certificate2)

Replace the attestation key and certificate.

C#

public void ReplaceAttestationKeyAndCertificate(PivPrivateKey privateKey, X509Certificate2 certificate)

Parameters

Type	Name	Description
PivPrivateKey	privateKey	The private key that will be the new attestation key.
System.Security.Cryptography.X509Certificates.X509Certificate2	certificate	The cert that will be the new attestation cert.

Exceptions

Type	Condition
System.ArgumentNullException	One of the inputs is null.
System.ArgumentException	One of the inputs is not allowed (e.g. private key is 1024-bit RSA).
System.InvalidOperationException	There is no KeyCollector loaded, the key provided was not a valid Triple-DES key, or the YubiKey had some other error, such as unreliable connection.
MalformedYubiKeyResponseException	The YubiKey returned malformed data and authentication, either single or double, could not be performed.
System.OperationCanceledException	The user canceled management key collection.
System.Security.SecurityException	Mutual authentication was performed and the YubiKey was not authenticated.

Remarks

See the User's Manual entry on PIV attestation for more information on attestation statements and replacing them.

Note that attestation is a feature available on YubiKeys version 4.3 and later.

The YubiKey is manufactured with an attestation key and cert. This is the key that is used to sign the attestation statement, and the cert that verifies the attestation key.

This key was generated by Yubico, and the cert chains to a Yubico root. They are shared by many YubiKeys. If you want to replace them with your own, call this method.

Note that if you replace the Yubico key and cert, there is no way to recover them, they will be gone for good. So use this method with caution.

Note also that this is an operation that very few users will want to do. There are some companies who want to make sure the cert that is the attestation statement chains to one of their roots, instead of a Yubico root. For those companies, this feature is available. However, this is not common. If you are wondering if you want to replace the attestation key and cert, you almost certainly do not. If this is not already a requirement in your application, it almost certainly is not something you will be doing.

There are limitations placed on the key and cert. The key must be either RSA-2048, ECC-P256, or ECC-P384. The cert must be X.509, it must be version 2 or 3, the full DER encoding of the SubjectName must be fewer than 1029 bytes, and the total length of the certificate must be fewer than 3052 bytes. This method will verify that these restrictions are met.

YubiKeys before version 5 allowed 1024-bit RSA keys as the attestation key. However, this method, regardless of the YubiKey version, will not accept 1024-bit RSA keys.

This method will NOT, however, verify that the public key represented in the cert is indeed the partner to the private key specified. If you want to make sure they match, see the User's Manual entry on PIV attestation for a discussion on verifying compatibility.

Due to space and compute limitations, the YubiKey itself does not verify the inputs before loading them. That means it is possible to load bad key/cert combinations. For example, it is possible to load a cert that contains a subject key that is not the partner to the private key. In that case, the YubiKey will create attestation statements that do not verify or do not chain to a root. In other cases, the YubiKey might simply return an error when requested to build an attestation statement. Hence, you must be certain the key and cert you load are correct, and you should thoroughly test the attestation statements before deployment.

The method will not verify the cert itself, nor will it verify the validity dates inside the cert.

In order to perform this operation, the management key must be authenticated during this session. If it has not been authenticated, this method will call AuthenticateManagementKey(Boolean). That is, your application does not need to authenticate the management key separately (i.e., call TryAuthenticateManagementKey or AuthenticateManagementKey), this method will determine if the management key has been authenticated or not, and if not, it will make the call to perform mutual authentication.

The authentication method will collect the management key using the KeyCollector delegate. If no such delegate has been set, it will throw an exception.

The KeyCollector has an option to cancel the operation. That is, the AuthenticateManagementKey method will call the KeyCollector requesting the management key, and it is possible that during the collection operations, the user cancels. The KeyCollector will return to the authentication method noting the cancellation. In that case, it will throw an exception. If you want the authentication to return false on user cancellation, you must call TryAuthenticateManagementKey(Boolean) directly before calling this method.