Windows Server 2008 R2 CAPolicy.inf Syntax

[Ned Pyle]

First published on TechNet on Oct 15, 2009
Greetings! This is Jonathan again. I was reviewing Chris’ excellent blog post series on designing and implementing a PKI when I realized that it would be helpful to better document the CAPolicy.inf file. The information in this post relies heavily on the information published in the Windows Server 2003 Help File, but this information is updated to include information pertinent to Windows Server 2008 R2.

Another helpful document that discusses many of these settings is available on Technet .

Background

First, what is a CAPolicy.inf file? The CAPolicy.inf contains various settings that are used when installing the Active Directory Certification Service (ADCS) or when renewing the CA certificate. The CAPolicy.inf file is not required to install ADCS with the default settings, but in many cases the default settings are insufficient. The CAPolicy.inf can be used to configure CAs in these more complicated deployments.

Once you have created your CAPolicy.inf file, you must copy it into the %systemroot% folder (e.g., C:Windows) of your server before you install ADCS or renew the CA certificate.

I’m not going to discuss what settings you need for your particular configuration, nor will I offer guidance on how you should set up your PKI to meet whatever your needs may be. Please follow Chris’ series for that sort of information. I’m simply going to document the available settings in the CAPolicy.inf which, if you follow Chris’ guidance, you’ll find will come in handy.

Let’s get started, shall we?

As I mentioned earlier, the CAPolicy.inf file uses the .INF file structure to specify sections, settings, and values for those settings. It will be impossible here to define a default template suitable for all purposes, so I’m just going to describe all the options and allow you to decide which settings meet your needs. Not all the settings below are required in the file, but those that are required will be called out.

The following key words are used to describe the .INF file structure.

• A section is an area in the .INF file that covers a logical group of keys. A section always appears in brackets in the .INF file.
• A key is the parameter that is to the left of the equal sign.
• A value is the parameter that is to the right of the equal sign.

Version

The first two lines of the CAPolicy.inf file are:

[Version]
Signature=”$Windows NT$”

• [Version] is the section .
• Signature is the key .
• “$Windows NT$” is the value .

Version is the only required section, and must be at the beginning of your CAPolicy.inf file.

PolicyStatementExtension

Next is the PolicyStatementExtension section. This section lists the name of the policies for this CA. Multiple policies are separated by commas. The names LegalPolicy and ManagementPolicy are used here as examples, but the names can be whatever the CA administrator chooses when creating the CAPolicy.inf file.

NOTE : Administrator defined section names must observe the following syntax rules:

• A section name cannot have leading or trailing spaces, a linefeed character, a return character, or any invisible control character, and it should not contain tabs.
• A section name cannot contain either of the bracket ( [] ) characters, a single percent ( % ) character, a semicolon ( ; ), or any internal double quotation ( “ ) characters.
• A section name cannot have a backslash ( ) as its last character.

The names have meaning in the context of a specific deployment, or in relation to custom applications that actually check for the presence of these policies.

[PolicyStatementExtension]
Policies= LegalPolicy,ManagementPolicy

For each policy defined in the PolicyStatementExtension section there must be a section that defines the settings for that particular policy. For the example above, the CAPolicy.inf must contain a [LegalPolicy] section and a [ManagementPolicy] section.

For each policy, you need to provide a user-defined object identifier ( OID ) and either the text you want displayed as the policy statement or a URL pointer to the policy statement. The URL can be in the form of an HTTP, FTP, or LDAP URL. Continuing on with the example started above, if you are going to have text in the policy statement, then the next three lines of the CAPolicy.inf will be:

[LegalPolicy]
OID= 1.1.1.1.1.1.1
Notice= ”Legal policy statement text”

If you are going to use a URL to host the CA policy statement, then next three lines would instead be:

[ManagementPolicy]
OID= 1.1.1.1.1.1.2
URL= http://pki.wingtiptoys.com/policies/managementpolicy.asp

Please note that the OID above is arbitrary and is used as an example. In a true deployment, you would obtain an OID from your own OID gatekeeper.

In addition:

• Multiple URL keys are supported
• Multiple Notice keys are supported
• Notice and URL keys in the same policy section are supported.
• URLs with spaces or text with spaces must be surrounded by quotes. This is true for the URL key, regardless of the section in which it appears.
• The Notice text has a maximum length of 511 characters on Windows Server 2003 [R2], and a maximum length of 4095 characters on Window Server 2008 [R2].

An example of multiple notices and URLs in a policy section would be:

[LegalPolicy]
OID= 1.1.1.1.1.1.1
URL= http://pki.wingtiptoys.com/policies/legalpolicy.asp
URL= ftp://ftp.wingtiptoys.com/pki/policies/legalpolicy.asp
Notice= ”Legal policy statement text”

CRLDistributionPoint

You can specify CRL Distribution Points (CDPs) for a root CA certificate in the CAPolicy.inf. This section does not configure the CDP for the CA itself. After the CA has been installed you can configure the CDP URLs that the CA will include in each certificate that it issues. The URLs specified in this section of the CAPolicy.inf file are included in the root CA certificate itself.

[CRLDistributionPoint]
URL= http://pki.wingtiptoys.com/cdp/WingtipToysRootCA.crl

Some additional information about this section:

• Multiple URLs are supported.
• HTTP, FTP, and LDAP URLs are supported. HTTPS URLs are not supported.
• This section is only used if you are setting up a root CA or renewing the root CA certificate. Subordinate CA CDP extensions are determined by the CA which issues the subordinate CA’s certificate.
• URLs with spaces must be surrounded by quotes.
• If no URLs are specified – that is, if the [CRLDistributionPoint] section exists in the file but is empty – the CRL Distribution Point extension will be omitted from the root CA certificate. This is usually preferable when setting up a root CA. Windows does not perform revocation checking on a root CA certificate so the CDP extension is superfluous in a root CA certificate.

Authority Information Access

You can specify the authority information access points in the CAPolicy.inf for the root CA certificate.

[AuthorityInformationAccess]
URL= http://pki.wingtiptoys.com/Public/myCA.crt

Some additional notes on the authority information access section:

• Multiple URLs are supported.
• HTTP, FTP, LDAP and FILE URLs are supported. HTTPS URLs are not supported.
• This section is only used if you are setting up a root CA, or renewing the root CA certificate. Subordinate CA AIA extensions are determined by the CA which issued the subordinate CA’s certificate.
• URLs with spaces must be surrounded by quotes.
• If no URLs are specified – that is, if the [AuthorityInformationAccess] section exists in the file but is empty – the CRL Distribution Point extension will be omitted from the root CA certificate. Again, this would be the preferred setting in the case of a root CA certificate as there is no authority higher than a root CA that would need to be referenced by a link to its certificate.

Enhanced Key Usage

Another section of the CAPolicy.inf file is [EnhancedKeyUsageExtension] , which is used to specify the Enhanced Key Usage extension OIDs placed in the CA certificate.

• Multiple OIDs are supported.
• This section can be used during CA setup or CA certificate renewal.
• This section can be used for both the root CA and for subordinate CAs.
• This extension can be marked as Critical .

An example of this section is:

[EnhancedKeyUsageExtension]
OID= 1.2.3.4.5
OID= 1.2.3.4.6
Critical= No

If this section is omitted from the CAPolicy.inf file, the Enhanced Key Usage extension will be omitted from the root CA certificate. If this extension does not exist in a root CA certificate then that root CA certificate can be trusted for all purposes.

By populating this section with specific OIDs, you are limiting the purposes for which the root CA certificate can be trusted. For example, consider the following section:

[EnhancedKeyUsageExtension]
OID= 1.3.6.1.5.5.7.3.4        ; Secure Email
OID= 1.3.6.1.4.1.311.20.2.2    ; Smart Card Logon
Critical= No

During the setup of the CA, the root CA certificate will be created with the two OIDs above in the Enhanced Key Usage extension. This root certificate, because of the OIDs specified, can only be trusted for Secure Email (signing and encrypting) and Smart Card Logon. Any certificate issued for some other purpose, such as Client or Server Authentication, would be considered invalid. This restriction would apply not only to this root CA, but also to any CA subordinate to this root.

Basic Constraints

You can use the CAPolicy.inf file to define the PathLength constraint in the Basic Constraints extension of the root CA certificate. Setting the PathLength basic constraint allows you to limit the path length of the CA hierarchy by specifying how many tiers of subordinate CAs can exist beneath the root. A PathLength of 1 means there can be at most one tier of CAs beneath the root. These subordinate CAs will have a PathLength basic constraint of 0, which means that they cannot issue any subordinate CA certificates.

This extension can be marked as Critical .

[BasicConstraintsExtension]
PathLength= 1
Critical= Yes

It is not recommended to use this section in the CAPolicy.inf file for a subordinate CA. To add a PathLength constraint to a subordinate CA certificate if the parent CA has no PathLength constraint in its own certificate, you can set the CAPathLength registry value on the parent CA. For example, to issue a subordinate CA certificate with a PathLength constraint of 1, use the following command to configure the parent CA.

Certutil –setreg PolicyCAPathLength 2

Setting this value causes the CA to behave as though its own certificate had a PathLength constraint of whatever number you specify. Any subordinate CA certificate issued by the parent CA will have a PathLength constraint set appropriately in its Basic Constraints extension.

You must restart Active Directory Certificate Services for this change to take effect.

Cross Certificate Distribution Points

The cross certificate distribution points (CCDP) extension identifies where cross certificates related to the CA certificate can be obtained and how often that location is updated. The CCDP extension is useful if the CA has been cross-certified with another PKI hierarchy. Windows XP and later operating systems would use this extension for the discovery of cross-certificates that might be used during the path discovery and chain building process.

The SyncDeltaTime key indicates how often, in seconds, the locations referred to by the URL key(s) are updated. While this entire section is optional, if it exists, and if the SyncDeltaTime key is present, then at least one URL key must also be present.

This extension can be marked as Critical .

[CrossCertificateDistributionPointsExtension]
SyncDeltaTime= 600    ; in seconds
URL= http://pki.wingtiptoys.com/ccdp/PartnersCA.crt
Critical= No

Request Attributes

The [RequestAttributes] section, when implemented on a subordinate CA, allows you to specify a custom subordinate certification authority template. There is already the default Subordinate Certificate Authority template that is published in Active Directory the first time an Enterprise CA is installed in the forest. This default template, however, is a v1 template (Windows 2000-style) and cannot be edited. The CertificateTemplate key allows you specify a different template for your subordinate CA certificate request, one that you created by duplicating the default template.

[RequestAttributes]
CertificateTemplate= WingtipToysSubCA

Server Settings

Another optional section of the CAPolicy.inf is [certsrv_server] , which is used to specify renewal key length, the renewal validity period, and the certificate revocation list (CRL) validity period for a CA that is being renewed or installed. None of the keys in this section are required. Many of these settings have default values that are sufficient for most needs and can simply be omitted from the CAPolicy.inf file. Alternatively, many of these settings can be changed after the CA has been installed.

An example would be:

[certsrv_server]
RenewalKeyLength= 2048
RenewalValidityPeriod= Years
RenewalValidityPeriodUnits= 5
CRLPeriod= Days
CRLPeriodUnits= 2
CRLDeltaPeriod= Hours
CRLDeltaPeriodUnits= 4
ClockSkewMinutes= 20
LoadDefaultTemplates= True
AlternateSignatureAlgorithm= 0
ForceUTF8= 0
EnableKeyCounting= 0

RenewalKeyLength sets the key size for renewal only. This is only used when a new key pair is generated during CA certificate renewal. The key size for the initial CA certificate is set when the CA is installed.

When renewing a CA certificate with a new key pair, the key length can be either increased or decreased. We in Support see this most often when a customer has set a root CA key size of 4096 bytes or higher, and then discover that they have Java apps or network devices that can only support key sizes of 2048 bytes. In that situation, we can use this setting in the CAPolicy.inf file to reduce the key size of the CA. Of course, that means that we have to reissue all the certificates issued by that CA. The higher up in the hierarchy the CA resides, the more inconvenient this procedure is.

RenewalValidityPeriod and RenewalValidityPeriodUnits establish the lifetime of the new root CA certificate when renewing the old root CA certificate. It only applies to a root CA. The certificate lifetime of a subordinate CA is determined by its superior. RenewalValidityPeriod can have the following values: Hours, Days, Weeks, Months, and Years.

CRLPeriod and CRLPeriodUnits establish the validity period for the base CRL, while CRLDeltaPeriod and CRLDeltaPeriodUnits establish the validity period of the delta CRL. CRLPeriod and CRLDeltaPeriod can have the following values: Hours, Days, Weeks, Months, and Years. Each of these settings can be configured after the CA has been installed:

Certutil -setreg CACRLPeriod Weeks
Certutil -setreg CACRLPeriodUnits 1
Certutil -setreg CACRLDeltaPeriod Days
Certutil -setreg CACRLDeltaPeriodUnits 1

Restart Active Directory Certificate Services for any changes to take effect.

ClockSkewMinutes allows you to accommodate possible clock synchronization issues. The CA will set the effective time of the published base CRL and delta CRL to the current time less the ClockSkewMinutes . For example, if the clock skew is set to 5 minutes, and the current time is 4:00pm, then the effective time of a newly published CRL would be 3:55pm.

This value can also be set after the CA has been installed.

Certutil -setreg CAClockSkewMinutes 10

Restart Active Directory Certificate Services for any changes to take effect.

The default value for ClockSkewMinutes is 10 minutes; if this interval is sufficient then this key can be omitted from the CAPolicy.inf file.

LoadDefaultTemplates only applies during the install of an Enterprise CA. This setting, either True or False (or 1 or 0), dictates whether or not the CA is configured with any of the default templates.

In a default installation of the CA, a subset of the default certificate templates is added to the Certificate Templates folder in the Certification Authority snap-in. This means that as soon as the ADCS service starts after the role has been installed a user or computer with sufficient permissions can immediately enroll for a certificate. This behavior is not always desirable.

To illustrate the point, the Domain Controller and Domain Controller Authentication templates are among the default templates added to the CA as it is installed. The default permissions on these two templates allow all domain controllers in the forest to enroll for certificates based those two templates. Finally, the default behavior of a domain controller is to immediately enroll for a Domain Controller or Domain Controller Authentication template as soon as an Enterprise CA is detected in the forest (Windows 2000 DCs will attempt to enroll for a Domain Controller certificate; Windows Server 2003 and higher will attempt to enroll for a Domain Controller Authentication certificate).

You may not want to issue any certificates immediately after a CA has been installed, so you can use the LoadDefaultTemplates setting to prevent the default templates from being added to the Enterprise CA. If there are no templates configured on the CA then it can issue no certificates.

On Windows Server 2003 and Windows Server 2003 R2, the LoadDefaultTemplates setting only applies to a root Enterprise CA. It is ignored on a subordinate Enterprise CA.

On Windows Server 2008 and Windows Server 2008 R2, the LoadDefaultTemplates setting applies to both root and subordinate Enterprise CAs.

AlternateSignatureAlgorithm configures the CA to support the PKCS#1 V2.1 signature format for both the CA certificate and certificate requests. When set to 1 on a root CA the CA certificate will include the PKCS#1 V2.1 signature format. When set on a subordinate CA, the subordinate CA will create a certificate request that includes the PKCS#1 V2.1 signature format.

ForceUTF8 changes the default encoding of relative distinguished names (RDNs) in Subject and Issuer distinguished names to UTF-8. Only those RDNs that support UTF-8, such as those that are defined as Directory String types by an RFC, are affected. For example, the RDN for Domain Component (DC) supports encoding as either IA5 or UTF-8, while the Country RDN (C) only supports encoding as a Printable String. The ForceUTF8 directive will therefore affect a DC RDN but will not affect a C RDN.

Finally, EnableKeyCounting configures the CA to increment a counter every time the CA’s signing key is used. Do not enable this setting unless you have a Hardware Security Module (HSM) and associated cryptographic service provider (CSP) that supports key counting. Neither the Microsoft Strong CSP nor the Microsoft Software Key Storage Provider (KSP) support key counting.

For more caveats to be aware of when using key counting, please review the following KB article:

951721 The certification authority startup event in the Security log always reports a usage cou...

Conclusion

There we go. We’ve finally finished the list of all the settings you can configure via the CAPolicy.inf file.

I had at first considered putting all the sections I talked about above into one file so you could see how a “finished” CAPolicy.inf file would look. Then I realized that would be a monumentally bad idea seeing as, with the exception of the [Version] section, everything covered above is totally optional – perhaps with some settings even being contradictory. I’d hate to be responsible for a bad sample CAPolicy.inf file bouncing around the Internet.

The settings that you will want to configure in your CAPolicy.inf file will completely depend on your needs, and will vary between root CAs and subordinate CAs. I certainly hope that you find this information useful.

- Jonathan ‘Small bills only’ Stephens