Other posts in the series:

• Introducing to certificate enrollment APIs — summary

Abstract

In previous posts we discussed and explored certificate enrollment APIs (CertEnroll) to perform various basic enrollment operations. In this section we will talk about advanced certificate enrollment called Enroll On Behalf Of (EOBO). This type of enrollment involves additional mechanism called registration authority (RA). This commonly is used during smart card deployments. For example, an employee prior to get a smart card is went through face-to-face interview with Enrollment Agent where he is instructed about smart card usage rules and is registered in accounting documents. After all formalities are completed, an enrollment agent creates a special certificate request where he put employee's user name (which is obtained from Active Directory) and signs it with his own special Enrollment Agent certificate. And only then the certificate request is submitted to a CA server.

Normally automatic subject construction uses requester information to build the subject. Therefore it is not possible to issue the certificate for other user account. Enroll On Behalf Of functionality allows to explicitly specify target user account name. However, EOBO requires multiple signatures in the request:

1. Original PKCS#10 request is signed by a key pair generated during request creation;
2. When PKCS#10 request is signed, it is wrapped to a PKCS#7 (in most cases) container;
3. Entire PKCS#7 container is signed by a special enrollment agent certificate;

The second signature proves that the caller (or requester) is eligible to enroll certificate one behalf of other user (in other words, impersonate another user).

Because of the powerful capability of the Enrollment Agent certificate, it is strongly recommended that your organization maintain very strong security policies for these certificates.

By using this topic, an organization can develop a custom tool for enrollment agents to perform employee registration and certificate enrollment/issuance.

Hold the ice

Today we will start with IX509CertificateRequestPkcs10 interface that will create original PKCS#10 certificate request:

$PKCS10 = New-Object -ComObject X509Enrollment.CX509CertificateRequestPkcs10

use IX509CertificateRequestPkcs10::InitializeFromTemplateName method to initialize the request object. I will show the basic scenario which do not involve smart cards.

$PKCS10.InitializeFromTemplateName(0x1,"User")

and finalize the request by using generic Encode method:

$PKCS10.Encode()

Request encoding is necessary to generate a key pair and sign the PKCS#10 request object. After calling this method, the PKCS#10 object become signed and is ready to be wrapped in PKCS#7 object:

$pkcs7 = New-Object -ComObject X509enrollment.CX509CertificateRequestPkcs7
$pkcs7.InitializeFromInnerRequest($pkcs10)

The IX509CertificateRequestPkcs7 interface has two properties: RequesterName and SignerCertificate. First property is used to specify target user name (to whom this certificate is intended). The syntax of this property is very simple. Assuming, we have 'sballmer' user account in Adatum domain, then the RequesterName property is assigned in this way:

$pkcs7.RequesterName = "ADATUM\sballmer"

The SignerCertificate property is much complex. It accepts an ISignerCertificate interface object. Therefore we must instantiate the interface object:

$signer = New-Object -ComObject X509Enrollment.CSignerCertificate

The ISignerCertificate interface has only single initialization method: ISignerCertificate::Initialize. This method accepts 4 parameters and we are interesting in the last two: Encoding and strCertificate. With Windows Vista and Windows Server 2008 we have to manually find enrollment agent certificate (with Certificate Request Agent EKU) in the personal store. The following syntax could be used to find the certificate:

$cert = Get-ChildItem Cert:\CurrentUser\My | Where-Object {$_.Extensions | Where-Object {$_.Oid.Value -eq "2.5.29.37" -and $_.EnhancedKeyUsages["1.3.6.1.4.1.311.20.2.1"]}}

If the $cert contains a single certificate object (you could specify additional filters, because the command may return multiple enrollment agent certificates) we must convert it to a base64 string and add the string as a strCertificate parameter:

$Base64 = [Convert]::ToBase64String($Cert.RawData)
$signer = New-Object -ComObject X509Enrollment.CSignerCertificate
$signer.Initialize(0,0,1,$Base64)

With Windows 7, Windows Server 2008 R2 and newer systems (Windows 8 and Windows Server 2012) you can put just thumbprint information:

$signer = New-Object -ComObject X509Enrollment.CSignerCertificate
$signer.Initialize(0,0,0xc,"3A47D2C3CF064E13FE90442DA77412CBC5FA8824")

Once the ISignerCertificate object is ready, we add it to our PKCS#7 object SignerCertificate property:

$pkcs7.SignerCertificate = $signer

ok, that is enough. Now we are ready to create enrollment object and perform actual enrollment:

$Request = New-Object -ComObject X509Enrollment.CX509Enrollment
$Request.InitializeFromRequest($pkcs7)
$Request.Enroll()

if everything is completed successfully, then you should see a new certificate in personal store:

PS C:\> dir Cert:\CurrentUser\My


    Directory: Microsoft.PowerShell.Security\Certificate::CurrentUser\My


Thumbprint                                Subject
----------                                -------
3A47D2C3CF064E13FE90442DA77412CBC5FA8824  CN=Administrator, CN=Users, DC=adatum, DC=lv
42AB649452F23E9DB506B67A295A18453CE4C5EA  CN=Steve Ballmer, CN=Users, DC=adatum, DC=lv


PS C:\>

WOW, the certificate is successfully enrolled!!!11oneone Now enrollment agent should export the certificate (only if smart card CSP is not used) and distribute it to a target user. In the case of smart card CSP, you may have to type a PIN to save the certificate to smart card and no export actions are necessary.

The End

I think this is enough for you to get the fast start with EOBO automation. In the next post I will show several advanced techniques and will discuss about several security concerns regarding the series subject.

to be continued…