Windows PKI blog : certutil

How to get request statistics by template in PowerShell

alrad — Thu, 10 Sep 2009 02:03:00 GMT

I’ve been working with our support folks helping one of our customers. One of the things we wanted to learn about the environment is how many requests have been made for each certificate template that they issue. We have come up with this PowerShell script that you can run against a CA to find out.

Disclaimer

The sample scripts are not supported under any Microsoft standard support program or service. The sample scripts are provided AS IS without warranty of any kind.

Microsoft further disclaims all implied warranties including, without limitation, any implied warranties of merchantability or of fitness for a particular purpose.

The entire risk arising out of the use or performance of the sample scripts and documentation remains with you. In no event shall Microsoft, its authors, or anyone else involved in the creation, production, or delivery of the scripts be liable for any damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or other pecuniary loss) arising out of the use of or inability to use the sample scripts or documentation, even if Microsoft has been advised of the possibility of such damages.

certutil -view -out CertificateTemplate -restrict "NotBefore > 08/20/2009" csv > out.txt
$FileContents = gc out.txt
write-host "Total rows:" $FileContents.length
$GroupedCounts = $FileContents | group | sort count –Descending
$GroupedCounts | format-table Count,Name -auto

The output will look something like this:

Total rows: 10
Count Name
----- ----
4 "1.3.6.1.4.1.311...X
3 "1.3.6.1.4.1.311...Y
1 "8/20/2009 12:00 AM""Certificate Template"
1 "DomainController"
1 "EMPTY"

Let’s take a look at the script closely and also talk about what can be tweaked.

First, we run a certutil.exe to dump the template’s name or OID. The V1 templates are recorded by their name and V2/V3 templates are recorded by their OID. You can see template OIDs with the certutil.exe -template command. You can’t see it in the template snapin UI.

Note that we restrict the output by date. Some other filters that could be useful are CertificateTemplate and Request.StatusCode if you want to get counts for only template or if you’re only interested in failed requests for example. We pipe the output into a text file. We also use the -csv option so that our output is easier to consume for automation.

We then group the output by the template name/OID and sort it based on the count in the descending order. Finally we output it as a table.

Now let’s take a look at the output. Note that the last and third line from the bottom contains garbage. If you’re going to use the output of this script in some automation, you would need to get rid of those entries. They are simply an artifact of the certutil.exe output.

Defining the friendly name certificate property

MS2065 — Fri, 12 Dec 2008 15:18:23 GMT

The friendly name of a certificate can be helpful if multiple certificates with a similar subject exist in a certificate store.

One way to set the friendly name is through the certificate MMC SnapIn. Alternatively certutil.exe can be used in the following way:

Open Notepad and past the following text into the editor
[Version]
Signature = "$Windows NT$"
[Properties]
11 = "{text}My Friendly Name"
Save the file as friendlyname.inf
Determine the serialnumber of the certificate where the friendly name should be changed.
If the certificate exists in the user’s certificate store, run the following command at a command-line

certutil –repairstore –user my {SerialNumber} FriendlyName.inf

Disposition values for certutil –view –restrict (and some creative samples)

MS2065 — Fri, 03 Oct 2008 14:30:05 GMT

A while ago I explained how to determine all certificates that will expire within a given period. Now I’d like to explain how to query the CA database based on certificate or request disposition. The disposition ID’s are defined in the certsrv.h include file in the Windows SDK.

The following two tables show the disposition ID’s for the request queue and the log.

Disposition values for requests in the queue:

Disposition	Description
8	request is being processed
9	request is taken under submission
12	certificate is an archived foreign certificate
15	certificate is a CA certificate
16	parent CA certificates of the CA certificate
17	certificate is a key recovery agent certificate

Disposition values for requests in the log:

Disposition	Description
20	certificate was issued
21	certificate is revoked
30	certificate request failed
31	certificate request is denied

Show the SerialNumber of all issued and revoked certificates:

certutil -view -restrict "Disposition>=20,Disposition<=21" -out SerialNumber

Show the most recently issued certificate that is not revoked. To view the certificate copy everything between the line “-----BEGIN CERTIFICATE-----” and “-----END CERTIFICATE-----“ into a file with the file extension CER and open the file. The expression RequestID=$ instructs certutil to sort the database query from high to low and stop after the first entry is displayed.

certutil -view -restrict "RequestId=$,Disposition=20" -out RawCertificate

Show all certificate requests that failed for the certificate template with the common name "EnrollmentAgent" after September 24th 2008:

certutil -view -restrict "Disposition=30,notbefore=>9/24/2008,certificate template=EnrollmentAgent" -out RawCertificate

Show the SerialNumber and the Request Status Code for all certificate requests that have been submitted by CONTOSO\user1:

certutil -view -restrict "RequesterName=CONTOSO\user1" -out SerialNumber,StatusCode

Show all CRL attributes for the CRL that was published before the current CRL:

certutil -restrict "CRLRowID=$-1" –view CRL

Note: If you don’t know how to restrict the query by a certain attribute dump all certificate or request attributes by not specifying the –out parameter. Then take the output as a sample to build the query with the attributes that you are looking for.

Marking private keys as non-exportable with certutil -importpfx

MS2065 — Sun, 29 Jul 2007 23:00:00 GMT

When importing a PFX-file with the certificate import wizard, you can choose if the private key should be exportable or not. Your choice is stored in the key storage property identifier that is key-storage specific. In other words, there is no information in the certificate about the exportability of the related private key. It is possible that if you import the same PFX-file into different computers that the private key is maked as exportable on one computer and is not marked as exportable on another.

To perform a PFX-file import at a command-line you may be familiar with the certutil -importPFX command. Since Windows Server 2003 SP1, certutil understands extra arguments to improve the PFX import.

Here is the abstract syntax:

certutil -importPFX {PFXfile} [NoExport|NoCert|AT_SIGNATURE|AT_KEYEXCHANGE]

To make the private key non-exportable, use the following command:

certutil -importPFX [PFXfile] NoExport

To just install the private key but not the certificate, use the NoCert argument. It can be combined with the NoExport argument.

certutil -importPFX [PFXfile] NoCert

There are two more arguments forcing AT_SIGNATURE or AT_KEYEXCHANGE. Both cannot be used in combination and may require a conversion to a RSA key.

certutil -importPFX [PFXfile] AT_SIGNATURE

certutil -importPFX [PFXfile] AT_KEYEXCHANGE

To combine multiple modifiers with one command, all modifiers must appear comma seperated as a single common line parameter. For example:

certutil -importPFX [PFXfile] "NoExport,AT_KEYEXCHANGE"

A simple way to set the certutil -config option

MS2065 — Sat, 12 May 2007 21:07:00 GMT

When you are performing an operation on a remote CA, certutil requires the config string as input parameter. The common way to find out the config string is to run a certutil -dump command, list all available CAs in the Active Directory forest and copy/past the config parameter from the dump into the new command-line.

There is a much simpler way to set the config string in certutil. Just use a dash as config string and certutil will show a selection dialog with all CAs that are registered in your Active Directory forest.

For example to verify the responsiveness of a remote CA, run the following command and select the target CA from the list of available CAs.

certutil –config - -ping

Manually publishing a CA certificate or CRL into a LDAP store

MS2065 — Fri, 13 Apr 2007 12:27:00 GMT

The CA is automatically publishing its own certificates and related CRLs into Active Directory if a LDAP reference is configured in the CA property “Extensions”.

If you are using a different LDAP server (such as Microsoft ADAM) to make the CA certificate and CRL available, certificates and CRLs must be published manually. The easiest way to do that is with certutil.

Perform the following command to publish the CRL manually into a LDAP-store.

certutil –addstore "LDAP://[server]/[DN]?certificateRevocationList?base?objectclass=cRLDistributionPoint" [CRL-File]

Replace [server] with the name of the LDAP server where you have write permissions.
Replace [DN] with the path that you have used in the CA configuration.
Replace [CRL-File] with the file name of the CRL that you want to publish.

Here is the command to publish a CA certificate manually:

certutil –addstore "LDAP://[server]/[DN]?cACertificate?base?objectClass=certificationAuthority" [cert-file]

To manually publish a CA certificate or CRL into Active Directory you should still use certutil –dspublish instead of certutil –addstore.

How to find out the max size of certificate attributes

MS2065 — Mon, 26 Feb 2007 10:52:00 GMT

The other day I was asked how many subject alternate names will fit into a single certificate. I asked myself what the best way would be to find out. After a short time of thinking I decided to look at the schema defintion of the CA database. The schema will tell for sure how many characters fit into a certain attribute because the database has to store every attribute for a certificate or a request.

So the answer is pretty simple here: There is no limit how many items fit into an attribute but there is a limit regarding the total size.

To determine the max size of a certificate attribut, just run the following command on the CA computer:

certutil -schema

The output shows information about the max. sizes. Once you have this information, just count the number of characters for an attribute in your certificate request an you know if it fits.

Carsten

How to manually set the archive flag for certifictes

MS2065 — Thu, 22 Feb 2007 19:19:00 GMT

If you have to select a certain certificate for authentication for example, you may wonder why several certificates are presented by the UI. Internet Explorer may offer several client authentication certificates while securely connecting to a web site or Outlook presents a number of certificates that can be used for eMail encryption.

One reason for such behavior could be that unnecessarily multiple certificates are available in your certificate store. Multiple certificates for the same purpose can exist if old certificates are not properly archived when new certificates are enrolled. Autoenrollment takes care of the archival process but when certificates are manually enrolled, old certificates are not flagged as archived.

Instead of deleting certificates (what you should never do with encryption certificates) you can just archive them. Unfortunately, the Certificates MMC snap-in provides no way to set the archive flag for a certificate. Therefore, install and use CAPICOM to set the flag for a given certificate with a script. The following script can be used as a sample to archive certificates. CAPICOM is fully documented on http://msdn.microsoft.com/.

Option Explicit

Const CAPICOM_CERTIFICATE_FIND_SHA1_HASH = 0

Const CAPICOM_CURRENT_USER_STORE = 2

Const CAPICOM_STORE_OPEN_READ_WRITE = 1

Const CAPICOM_STORE_OPEN_INCLUDE_ARCHIVED = 256

Dim oArgs

Dim oStore, oCertificates

Set oArgs = Wscript.Arguments

if oArgs.Count <> 1 then

wscript.echo "Must specify the certificate thumbprint as argument"

wscript.quit 1

end if

Set oStore = CreateObject("CAPICOM.Store")

oStore.Open CAPICOM_CURRENT_USER_STORE, "My", CAPICOM_STORE_OPEN_READ_WRITE or CAPICOM_STORE_OPEN_INCLUDE_ARCHIVED

Set oCertificates = oStore.Certificates.Find(CAPICOM_CERTIFICATE_FIND_SHA1_HASH, oArgs(0))

if oCertificates.Count = 1 then

oCertificates(1).Archived = false

end if

oStore.CLose

Set oCertificates = Nothing

Set oStore = Nothing

The script requires the thumbprint of the certificate to be archived as command-line parameter, for example

cscript archivecert.vbs “be 46 c0 95 ea 4f b7”

To un-archive existing certificates, just change the line oCertificates(1).Archive=false to oCertificates(1).Archive=true.

Instead using CAPICOM you might also consider the CertificateProvider class in Powershell to manipulate certificate stores.

Also from version 6 on (included in Windows Vista or a more recent Windows version), certutil.exe can be used to archive and un-archive certificates. To archive a certificate, use Notepad to create a text file Archive.inf that has the following content:

[Properties]
19 = Empty

To remove the archive bit from a certificate, use Notepad to create an INF file that has the following content:

[Properties]
19 =

Then run the following command at a command line for each cert to be archived:

certutil –repairstore –user my [CertificateThumbprint] Archive.inf

In the above command, you can also use a comma-separated list of CertificateThumbprints, if you prefer. If you copy/paste the thumbprint and it includes space characters, the thumbprint must be included in double quotes.

Once a certificate is flagged as archived, it does not appear in the certificates MMC snap-in unless the Archived certificates option is set. Also the certificate selection dialogs in Internet Explorer and Outlook do not show archived certificates.

To show archived certificates with the certificates MMC snap-in do the following:

1. Open the certificates MMC snap-in

2. Select the Certificates – Current User container in the left pane

3. From the menu chose View and then Options

4. Mark the option Archived certificates and click OK.