YubiKey Personal Identity Verification (PIV) Attestation - with the TameMyCerts Policy Module for Microsoft Active Directory Certificate Services (ADCS)

Author Uwe GradeneggerPosted on Categories TameMyCerts, Windows operating system, Certificate usage, Certification AuthorityTags , , , , , ,

Since the recently released version 1.7, the TameMyCerts Policy Module for Microsoft Active Directory Certificate Services Personal Identity Verification (PIV) attestation for YubiKeys.

A YubiKey is a compact security token that can be used like a smartcard for the secure storage and use of certificates and can therefore also be used for passwordless logon to Active Directory environments.

This cool function was developed by Oscar Virot and integrated into TameMyCerts. This makes it possible to provide cryptographic proof when issuing certificates and thus ensure that a key pair is actually generated with a YubiKey and secured by it and cannot be exported.

This can be particularly helpful in complying with the NIS2 directive if companies decide to use certificates as a second factor for logging in with security-critical accounts in the Active Directory.

Do you know TameMyCerts? TameMyCerts is an add-on for the Microsoft certification authority (Active Directory Certificate Services). It extends the function of the certification authority and enables the Application of regulationsto realize the secure automation of certificate issuance. TameMyCerts is unique in the Microsoft ecosystem, has already proven itself in countless companies around the world and is available under a free license. It can downloaded via GitHub and can be used free of charge. Professional maintenance is also offered.

Establishment

Configure certificate store

During the PIV attestation a so-called attestation certificate is attached to the generated certificate request. This in turn is signed by a signature certificate on the YubiKey, which in turn is signed by a certification authority of the manufacturer Yubico.

We must therefore first instruct our policy module to trust these Yubico certificates for the purpose of PIV attestation.

TameMyCerts uses - in the same way as ADCS's Trusted Platform Module (TPM) Key Attestation - the Windows certificate store to form the certificate chain for the YubiKey PIV Attestation.

After importing the certification authority certificates, the certification authority service must be restarted so that TameMyCerts can read in the certificates.

In the "Local Machine" certificate store on the certification authority, we create two new subfolders with a PowerShell command:

  • The "YKROOT" folder will contain the certificates of the root CAs for PIV attestation.
  • The "YKCA" folder will contain the Intermediate CA certificates for PIV attestation.
Set-Location -Path Cert:\LocalMachine
New-Item -Name YKROOT
New-Item -Name YKCA

The root certification authority certificates provided by Yubico can then be imported into the newly created certificate stores - for example via the management console for the local computer certificate store (certlm.msc) or via script.

The root certification authority can be certified under this this link can be obtained from Yubico.

Import via the Microsoft Management Console (certlm.msc)

Right-click on the respective folder and select "All Tasks" - "Import...".

Select an appropriate file in the following dialog.

Then select the desired storage location.

Import via script

You can save yourself a lot of work by combining PowerShell and the command line and importing the certificates with the following commands.

For the root certification authority certificates (example):

cd YubiKey-Root-CA-Certificates\
Get-ChildItem -Path *.cer | ForEach-Object -Process { certutil -addstore YKROOT $_.FullName }

For the intermediate certification body certificates (example):

cd YubiKey-Intermediate-CA-Certificates\
Get-ChildItem -Path *.cer | ForEach-Object -Process { certutil -addstore YKCA $_.FullName }

We then restart the certification authority service to make the certificates usable for TameMyCerts.

Restart-Service -Name certsvc

Configure certificate template

As for all other certificate types, we must of course create, configure and publish a certificate template on the certification authority for our YubiKey certificates.

As this process is generic, it is not explained in detail here.

Configure policy for TameMyCerts

TameMyCerts is open source and can be used free of charge. For use in the corporate sector, however, we recommend the Conclusion of a maintenance contract. This ensures that you receive qualified support and that the module can be further developed to a high quality in the long term.

Once the trust status has been configured and a certificate template has been created, we can now create a policy for TameMyCerts as usual.

In the TameMyCerts documentation is described in more detailwhat options are available.

In its simplest form, a configuration file could look like this:

<CertificateRequestPolicy xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <YubiKeyPolicies>
    <YubiKeyPolicy />
  </YubiKeyPolicies>
</CertificateRequestPolicy>

This configuration file would only ensure that the certificate request and the corresponding key pair were generated with a YubiKey.

The following configuration file is more extensive:

<CertificateRequestPolicy xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Subject>
    <SubjectRule>
      <Field>commonName</Field>
      <Mandatory>true</Mandatory>
      <Patterns>
        <Pattern>
          <Expression>^.*$</Expression>
        </Pattern>
      </Patterns>
    </SubjectRule>
  </Subject>
  <YubiKeyPolicies>
    <YubiKeyPolicy>
      <Action>Allow</Action>
      <PinPolicy>
        <string>Once</string>
        <string>Never</string>
        <string>Always</string>
        <string>MatchOnce</string>
        <string>MatchAlways</string>
      </PinPolicy>
      <TouchPolicy>
        <string>Always</string>
        <string>Never</string>
        <string>Cached</string>
      </TouchPolicy>
      <FormFactor>
        <string>UsbAKeychain</string>
        <string>UsbCKeychain</string>
        <string>UsbANano</string>
        <string>UsbCNano</string>
        <string>UsbCLightning</string>
        <string>UsbABiometricKeychain</string>
        <string>UsbCBiometricKeychain</string>
      </FormFactor>
      <MaximumFirmwareVersion>9.9.9</MaximumFirmwareVersion>
      <MinimumFirmwareVersion>5.1.3</MinimumFirmwareVersion>
      <Edition>
        <string>FIPS</string>
        <string>Normal</string>
        <string>CSPN</string>
      </Edition>
      <Slot>
        <string>9a</string>
        <string>9c</string>
        <string>9d</string>
        <string>9e</string>
      </Slot>
      <KeyAlgorithm>
        <string>RSA</string>
        <string>ECC</string>
      </KeyAlgorithm>
    </YubiKeyPolicy>
  </YubiKeyPolicies>
</CertificateRequestPolicy>

It is configured to display exactly one subject Relative Distinguished Name (RDN) of the type commonName with any value and perform YubiKey PIV attestation with the following restrictions:

  • All PIN policies are permitted.
  • All touch policies are permitted.
  • All form factors are permitted.
  • The firmware must be at least version 5.1.3.
  • All editions are permitted.
  • All slots are permitted.
  • All key algorithms are permitted.

Generate certificate request

In principle, the certificate requests must be generated with tools for Yubikeys so that the attestation information is part of them. There are various ways to do this:

An example of creating a certificate request with the yubico-piv-tool could look like this.

First, the key pair is generated. PIN and touch policies and the key algorithm are defined here. The public key is written to the "pubkey.key" file.

yubico-piv-tool --slot=9a --action=generate --pin-policy=once --touch-policy=cached --algorithm=ECCP384 --output=pubkey.key

Next, the attested certificate request is created using the previously created key pair and written to the "request.req" file.

yubico-piv-tool --slot=9a --subject="/CN=test/" --input=pubkey.key --attestation --output=request.req --action=verify-pin --action=request

Function test

For our functional test, we use the guideline described above with three different certificate requests:

  1. The first certificate request was generated in software and does not contain any attestation information.
  2. The second certificate request was generated with yubikey-piv-tool on a YubiKey with firmware 5.1.2 (this is too low for our policy).
  3. The third certificate request was generated with yubikey-piv-tool on a YubiKey with firmware 5.4.3.

This means that only the third certificate request should lead to a certificate being issued.

First attempt: no PIV attestation

We send the prepared certificate request to the certification authority:

certreq -attrib "CertificateTemplate:Yubikey_User_P384" -submit csr-no-attestation.req

As expected, this is rejected. The error code returned is "CERTSRV_E_TEMPLATE_DENIED".

A look at the event display of the certification authority reveals that the certificate request was rejected because it does not contain any usable PIV attestation data.

Second attempt: PIV attestation is available, but the firmware is too old

We send the prepared certificate request to the certification authority:

certreq -attrib "CertificateTemplate:Yubikey_User_P384" -submit 512-never-never-p384.req

As expected, this is also rejected. The error code returned is again "CERTSRV_E_TEMPLATE_DENIED".

A look at the certification authority's event display reveals that the certificate request was rejected because no Yubikey policy applies to the attestation data contained in this certificate request.

The exact functionality of the YubiKey rule set is described in the Documentation for the TameMyCerts Policy Module described.

Third attempt: PIV attestation is available and compliant with the directive

We send the prepared certificate request to the certification authority:

certreq -attrib "CertificateTemplate:Yubikey_User_P384" -submit 543-never-never-p384.req

We are now issued with a certificate.

TameMyCerts will transfer the data contained in the PIV attestation information to the issued certificate. These are

  • Firmware version of the Yubikey
  • Serial number of the Yubikey
  • PIN guideline
  • Form factor

See the Documentation from TameMyCerts for further information.

Optional: Confirm PIV attestation in the issued certificate

YubiKeys are limited to a size of 3052 bytes for issued certificates, therefore the original attestation information (the entire attestation certificate as a certificate extension) cannot be completely transferred to the issued certificate, as it could not be imported to the YubiKey.

As described above, TameMyCerts will extract the attestation information contained in the attestation certificate (as a certificate extension in the attestation certificate) and transfer it to the issued certificate.

In addition, an issuance policy can be transferred to the issued certificate using the on-board tools of the Microsoft certification authority.

The use of issuance policies requires that these are either also included in the certification authority certificate or that the "All Issuance Policies" issuance policy is included.

This is configured in the certificate template. Here you select the "Extensions" tab and edit the "Issuance Policies" section.

In the following dialog, you can create a new guideline by clicking on "Add...". This consists of a description text, optionally a URL where the corresponding written certification guideline can be found, as well as a unique, company-specific object identifier.

Issued certificates for which a successful PIV attestation has been carried out by TameMyCerts will then contain a corresponding issuing guideline in a standardized certificate extension.

Related links:

External sources

en_USEnglish
de_DEDeutsch en_USEnglish