Replace the attestation key and certificate.
public void ReplaceAttestationKeyAndCertificate(PivPrivateKey privateKey, X509Certificate2 certificate)
The private key that will be the new attestation key.
The cert that will be the new attestation cert.
One of the inputs is
One of the inputs is not allowed (e.g. private key is 1024-bit RSA).
There is no
The YubiKey returned malformed data and authentication, either single or double, could not be performed.
The user canceled management key collection.
Mutual authentication was performed and the YubiKey was not authenticated.
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
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.
KeyCollector has an option to cancel the operation. That
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) or
before calling this method.