Appendix 3: Certreq.exe Syntax
Applies To: Windows Server 2003 with SP1
Certreq.exe is a command-line tool that is included in Windows 2000 Server, Windows XP, and Windows Server 2003 as well as in the Windows Server 2003 Administration Tools Pack. The version available with Windows XP and Windows Server 2003 is different from the version that is included in Windows 2000 Server. When using certreq.exe, you must distinguish between these versions.
Important
This document was written for Windows XP and Windows Server 2003. Some, but not all of the settings discussed in this article will apply to newer operating system. See Certreq as the reference for newer operating system versions.
Tip
Several readers have asked for an actual example and mentioned that certreq is more difficult than using a graphical user interface. Microsoft KB article 931351 provides an example of how to perform a certificate request using a web interface as well as using Certreq.
You can perform the following tasks with certreq.exe.
Create new certificate requests. This includes the generation of key material that corresponds to the certificate request.
Apply policies to a certificate request. This applies to CA certificates where various constraints are required. Since you cannot include certificate policies in the certificate request that is created by a CA, you have to apply the policy to the CA certificate request explicitly.
Submit certificate requests to a certification authority. This feature also works with remote certification authorities, so that you can submit a request via the network to a remote CA.
Retrieve certificates from a CA. Based on the certificate request ID, you can retrieve any certificate from a CA and save it to a file.
Accept (and install) certificates or responses. This command is intended to accept a certificate or a response that contains a certificate. Once you have created a certificate request with certreq.exe, it remains in a pending state on your computer until you install the certificate that corresponds to the request.
Sign certificate requests. In the case where the certificate template administrator has set the number of certificate enrollment agent signatures to a value greater than zero, you can sign certificate requests with this option.
The Windows 2000 version of certreq.exe can only submit certificate requests and retrieve issued certificates. All other options require the certreq.exe version that comes with Windows XP or Windows Server 2003. For more information about the command-line syntax, run certreq,exe with the following parameters to display all available syntax and parameter information.
Certreq.exe -v -?
Creating Certificate Requests
The –new parameter with certreq.exe is used to construct new certificate requests. Certreq.exe uses an INF file as an input option that defines the certificate request parameters. When the certificate request is constructed based on the INF file, key material is also generated. A certificate request process can be divided into the following elements.
Read the INF file.
Create the private and public key based on the information in the INF file, and store the private key in the local key store of the user or computer profile as appropriate.
Create the certificate request based on the information in the INF file and store the request in a Base64-encoded file or, optionally, in binary form if the –binary option is selected.
Certreq.exe INF File Structure
Since the INF file allows for a rich set of parameters and options to be specified, it is difficult to define a default template that administrators should use for all purposes. Therefore, this section describes all the options to enable you to create an INF file tailored to your specific needs.
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.
For example, a minimal INF file would look similar to the following:
[NewRequest]
; At least one value must be set in this section
Subject = "CN=W2K3-BO-DC.contoso2.com"
Note
You can remark lines by putting a semi-colon (;) in front of the line.
The following are some of the possible sections that may be added to the INF file.
[Version]
This section is optional and is not required in an INF file. If present, it must contain the Signature key.
Signature
The signature key must be equal to the fixed string "$Windows NT$".
[NewRequest]
This section is mandatory for an INF file that acts as a template for a new certificate request. If this section is missing, the following error message will be displayed.
"INF file line not found 0xe0000102 (INF: -536870654)"
This section requires at least one key with a value. If this section is empty and has no keys, the following error message will be displayed.
"Incorrect function. 0x1 (WIN32: 1)"
EncipherOnly
Syntax |
EncipherOnly={Boolean} |
Values |
TRUE or FALSE |
Default value |
FALSE |
Sample |
|
Supported with CA type |
Windows 2000 Windows Server 2003 |
Can be manipulated in a pending request |
Yes (through the key usage extension) |
This parameter has an impact on the functional capabilities of the public-private key pair. If the value is set to TRUE, the key can exclusively be used for "encipherment" (encryption). If it is set to FALSE, the key can be used for "encipherment" and other purposes. This parameter refers only to the key type in CryptoAPI and has an indirect relationship only to the key usage extension that may be included in an issued X.509 certificate. The default value of the certificate enrollment control is set to FALSE. This setting only affects AT_KEYEXCHANGE key types and then correspondingly limits the key usage to key Encipherment, data Encipherment, or both. The digital signature and non-repudiation key usage(s) will be disallowed.
Exportable
Syntax |
Exportable = {Boolean} |
Values |
TRUE or FALSE |
Default value |
FALSE |
Sample |
|
Supported with CA type |
Windows 2000 Windows Server 2003 |
Can be manipulated in a pending request |
No |
This parameter is ignored when the "UseExistingKeySet" key is set to TRUE because you can set the exportable flag only when a new key is created. You cannot change this flag for an existing key. If this attribute is set to TRUE, the private key can be exported with the certificate. To ensure a high level of security, private keys should not be exportable; however, in some cases, it might be required to make the private key exportable if several computers or users must share the same private key. For example, a Web server that runs SSL and is published with Internet Security and Acceleration (ISA) to the Internet requires a certificate with an exportable key because the certificate and key must be installed on the Web server and the ISA server as well. Also, if it is required that the keys be managed and backed up, they must be exportable to provide for this functionality.
This setting correlates with the template configuration if a Windows Server 2003 enterprise CA is used. A certificate template administrator can explicitly define if private keys should be exportable.
Note
The template setting for exportable has no affect on the exportability properties of a key generated through certreq.exe -new.
KeyContainer
Syntax |
KeyContainer = {Key_containerName} |
Values |
Random string value (GUID) |
Default value |
None |
Sample |
|
Supported with CA type |
Windows 2000 Windows Server 2003 |
Can be manipulated in a pending request |
No |
It is not recommended to set this parameter for new requests where new key material is generated. The key container is automatically generated and maintained by the system.
For requests where the existing key material should be used, this value can be set to the key-container name of the existing key.
Use the certutil –key command to display the list of available key containers for the computer context.
Use the certutil –key –user command for the current user’s context.
If you need to find the key container for a specific certificate, use the certutil –store my command for machine certificates.
To find the key container for a specific certificate in the current user’s certificate store, use the certutil –store –user my command.
If the "UseExistingKeySet" key is set to TRUE, the key container must be set explicitly in the INF file or in the renewal certificate.
KeyLength
Syntax |
KeyLength = {integer} |
Values |
Any valid key length that is supported by the cryptographic service provider |
Default value |
1024 [depends on the certificate service provider (CSP)] |
Sample |
|
Supported with CA type |
Windows 2000 Windows Server 2003 |
Can be manipulated in a pending request |
No |
The key length defines the length of the public and private key. The key length has an impact on the security level of the certificate. Greater key length usually provides a higher security level; however, some applications may have limitations regarding the key length.
KeySpec
Syntax |
KeySpec = {integer} |
Values |
AT_KEYEXCHANGE: 1 AT_SIGNATURE: 2 |
Default value |
2 |
Sample |
|
Supported with CA type |
Windows 2000 Windows Server 2003 |
Can be manipulated in a pending request |
No |
Warning
The KeySpec determines if the key can be used for signatures, for Key Exchange (encryption), or for both. If the KeySpec is set to a value of 2, the EncipherOnly key is ignored. Starting with Windows Vista and Windows Server 2003 R2, specifying EncipherOnly= in the INF will cause an error.
KeyUsage
Syntax |
KeyUsage = {hexadecimal_value} |
Values |
CERT_DIGITAL_SIGNATURE_KEY_USAGE 0x80 CERT_NON_REPUDIATION_KEY_USAGE 0x40 CERT_KEY_ENCIPHERMENT_KEY_USAGE 0x20 CERT_DATA_ENCIPHERMENT_KEY_USAGE 0x10 CERT_KEY_AGREEMENT_KEY_USAGE 0x08 CERT_KEY_CERT_SIGN_KEY_USAGE 0x04 CERT_OFFLINE_CRL_SIGN_KEY_USAGE 0x02 CERT_CRL_SIGN_KEY_USAGE 0x02 CERT_ENCIPHER_ONLY_KEY_USAGE 0x01 |
Default value |
0xC0 for AT_SIGNATURE (default) For AT_KEYEXCHANGE, EncipherOnly = TRUE: 0x30 For AT_KEYEXCHANGE, EncipherOnly = FALSE: 0xf0 |
Sample |
|
Supported with CA type |
Windows 2000 Windows Server 2003 |
Can be manipulated in a pending request |
Yes |
The key usage defines what the certificate key should be used for. The value is a bit field that is composed of the key usage flags as they are defined in the Windows Platform Software Development Kit (SDK). (See the include file wincrypt.h.) Caution should be used in defining the correct key usage for the certificate request based on the intended application usage.
Note
The key usage extension has an indirect dependency with the enhanced key usage extension. For example, if you specify "Encrypting File System" as the enhanced key usage, you should also specify "Key Encipherment" as the key usage.
To combine multiple key usages, summarize the values of the individual key usages by performing hexadecimal arithmetic. The default key usage is set to Digital Signature (0x80) and Non-Repudiation (0x40). The hexadecimal sum of 0x80 and 0x40 is in 0xC0.
The key usage parameter is primarily useful if certificate requests are submitted to stand-alone CAs. Only enterprise CAs have certificate key usages predefined through certificate templates. The key usage extension is set to critical by default.
MachineKeySet
Syntax |
MachineKeySet = {Boolean} |
Values |
TRUE or FALSE |
Default value |
FALSE |
Sample |
|
Supported with CA type |
Windows 2000 Windows Server 2003 |
Can be manipulated in a pending request |
No |
This key is important when you need to create certificates that are owned by the computer and not a user. The key material that is generated is maintained in the security context of the security principal (user or computer account) that has created the request. When an administrator creates a certificate request on behalf of a computer, the key material must be created in the computer’s security context and not the administrator’s security context. Otherwise, the computer could not access its private key because it would be in the administrator’s security context.
You must set this key to TRUE if you are creating requests for domain controllers, a Web server, or any other service that runs in the computer’s security context.
PrivateKeyArchive
Syntax |
PrivateKeyArchive = {Boolean} |
Values |
TRUE or FALSE |
Default value |
FALSE |
Sample |
|
Supported with CA type |
Windows Server 2003 |
Can be manipulated in a pending request |
No |
The PrivateKeyArchive setting works only if the corresponding RequestType is set to "CMC" because only the Certificate Management Messages over CMS (CMC) request format allows for securely transferring the requester’s private key to the CA for key archival. Only the Windows Server 2003 enterprise CA supports private key archival. The Windows Server 2003 enterprise CA must be online and accessible to retrieve the CA encryption certificate directly during this process.
ProviderName
Syntax |
ProviderName = {CSP_stringname} |
Values |
The descriptive name of the certificate service provider |
Default value |
Microsoft Strong Cryptographic Provider |
Sample |
|
Supported with CA type |
Windows 2000 Windows Server 2003 |
Can be manipulated in a pending request |
No |
The provider name is the display name of the CSP. If you do not know the provider name of the CSP you are using, run certutil –csplist from a command line. The command will display the names of all CSPs that are available on the local system.
ProviderType
Syntax |
ProviderType = {integer} |
Values |
The number that describes the provider type |
Default value |
12 |
Sample |
|
Supported with CA type |
Windows 2000 Windows Server 2003 |
Can be manipulated in a pending request |
No |
The provider type is used to select specific providers based on specific algorithm capability such as "RSA Full". If you do not know the provider type of the CSP you are using, run certutil –csplist from a command-line prompt. The command will display the provider type of all CSPs that are available on the local system.
RenewalCert
Syntax |
RenewalCert={CertificateHash} |
Values |
The certificate hash of any certificate that is available at the computer where the certificate request is created |
Default value |
n/a |
Sample |
|
Supported with CA type |
Windows 2000 Windows Server 2003 |
Can be manipulated in a pending request |
No |
If you need to renew a certificate that exists on the system where the certificate request is generated, you must specify its certificate hash as the value for this key. If you do not know the certificate hash, use the Certificates MMC Snap-In and look at the certificate that should be renewed. Open the certificate properties and see the "Thumbprint" attribute of the certificate. Certificate renewal requires either a PKCS#7 or a CMC request format.
Note
You can only renew certificates that are time valid. Expired certificates cannot be renewed and must be replaced with a new certificate.
Requestername
Syntax |
Requestername=samAccountName in Active Directory |
Values |
|
Default value |
n/a |
Sample |
|
Supported with CA type |
Windows 2000 (with a PKCS#7 request type only) Windows Server 2003 |
Can be manipulated in a pending request |
No |
The requester name can be specified for certificate requests if the RequestType is set to PKCS7 or CMC. If the RequestType is set to PKCS10, this key will be ignored. The Requestername can only be set as part of the request. You cannot manipulate the Requestername in a pending request.
RequestType
Syntax |
RequestType={string value} |
Values |
CMC PKCS10 PKCS10- PKCS7 |
Default value |
PKCS10 |
Sample |
|
Supported with CA type |
Windows 2000 (except CMC request type) Windows Server 2003 |
Can be manipulated in a pending request |
No |
The RequestType determines the standard that is used to generate and send the certificate request.
Silent
Syntax |
Silent={Boolean} |
Values |
TRUE or FALSE |
Default value |
FALSE |
Sample |
|
Supported with CA type |
Windows 2000 Windows Server 2003 |
Can be manipulated in a pending request |
No |
By default, this option allows the CSP access to the interactive user desktop and request information such as a smart card PIN from the user. If this key is set to TRUE, the CSP must not interact with the desktop and will be blocked from displaying any user interface to the user.
SMIME
Syntax |
SMIME = {Boolean} |
Values |
TRUE | FALSE |
Default value |
False (when KeySpec = AT_SIGNATURE) |
Sample |
|
Supported with CA type |
Windows 2000 (if the policy module is configured in the registry to ignore the extension in the request) Windows Server 2003 |
Can be manipulated in a pending request |
Yes |
If this parameter is set to TRUE, an extension with the object identifier value 1.2.840.113549.1.9.15 is added to the request. The extension contains up to four object identifiers, depending on the CSP capability, which refer to symmetric encryption algorithms that may be used by Secure Multipurpose Internet Mail Extensions (S/MIME) applications such as Outlook.
When an S/MIME encrypted e-mail is sent, the sender’s computer does not know exactly what encryption algorithms are supported by the receiver. Thus, the weakest encryption algorithm was chosen by default to ensure a high level of interoperability. Today, the majority of computers support encryption algorithms that can handle stronger keys than 40-bit. To give the sender of an S/MIME message a hint as to which encryption algorithms might be supported by the receiver, identifiers of supported symmetric algorithms are inserted in the certificate. Alternatively, Outlook can be configured through the registry to always use the default encryption algorithm. For more information, see the Knowledge Base article at https://support.microsoft.com/?id=307472
This functionality is supported with Outlook XP SP2 or a later version.
If the CA administrator has added the object identifier for S/MIME capabilities to the CA configuration parameter "DisableExtensionList", the CA will ignore the S/MIME capabilities in the request. For more information about how to add entries to the "DisabledExtensionList", see the Windows Server 2003 PKI Operations Guide at https://www.microsoft.com/technet/prodtechnol/windowsserver2003/technologies/security/ws03pkog.mspx
Subject
Syntax |
Subject={String} |
Values |
Relative Distinguished Name string values |
Default value |
n/a |
Sample |
|
Supported with CA type |
Windows 2000 Windows Server 2003 |
Can be manipulated in a pending request |
Yes |
Several applications rely on the subject information in a certificate. Thus, it is recommended that a value for this key be specified. If the subject is not set here, it is recommended that a subject name be included as part of the subject alternative name certificate extension.
UseExistingKeySet
Syntax |
UseExistingKeySet={Boolean} |
Values |
TRUE or FALSE |
Default value |
FALSE |
Sample |
|
Supported with CA type |
Windows 2000 Windows Server 2003 |
Can be manipulated in a pending request |
No |
This parameter is used to specify that an existing key pair should be used in building a certificate request. If this key is set to TRUE, you must also specify a value for the RenewalCert key or the KeyContainer name. You must not set the Exportable key because you cannot change the properties of an existing key. In this case, no key material is generated when the certificate request is built.
UserProtected
Syntax |
UserProtected={Boolean} |
Values |
TRUE or FALSE |
Default value |
FALSE |
Sample |
|
Supported with CA type |
Windows 2000 Windows Server 2003 |
Can be manipulated in a pending request |
No |
If this key is set to TRUE, a CryptoAPI password window is displayed when the key is generated during the certificate request build process. You can optionally protect the key with a password in the window or choose to display only a window when the key is used within an application. Once the key is protected with a password, you must enter this password every time the key is accessed. For more information about strong private key protection, see https://www.microsoft.com/technet/prodtechnol/windowsserver2003/technologies/security/autoenro.mspx
[EnhancedKeyUsageExtension]
The enhanced key usage extension determines for what purposes a certificate can be used. To see a list of object identifiers that are supported by your CA, run the following command at a command-line prompt.
certutil –oid [OID string value]
Note
You can add custom object identifiers to the CA configuration. Thus, the default list of object identifiers that is supplied with a Windows Server 2003 CA can be extended according to your requirements.
For a list of object identifiers that are supported with the Microsoft PKI, see the Knowledge Base article "Object IDs Associated with Microsoft Cryptography" at https://support.microsoft.com/?id=287547.
Object Identifier
Syntax |
OID={OID_String} |
Values |
Any valid object identifier |
Default value |
n/a |
Sample |
|
Supported with CA type |
Windows 2000 Windows Server 2003 |
Can be manipulated in a pending request |
Yes |
The object identifier is specified as a value that will be added to the enhanced key usage of the certificate. To specify multiple object identifiers, add a new line for every object identifier required. For example:
OID = 1.3.6.1.5.5.7.3.1
OID = 1.3.6.1.5.5.7.3.2
[Extensions]
Instead of specifying extensions in this section, you can set extensions at the time you submit the certificate request to a Windows Server 2003 CA or a Windows 2000 CA if the request is initially made pending.
{OID}
Syntax |
{OID} = {Base64Text} |
Values |
any valid object identifier that appears in the certificate |
Default value |
n/a |
Sample |
|
Supported with CA type |
Windows 2000 Windows Server 2003 |
Can be manipulated in a pending request |
Yes |
Certificate extensions can be added to a request through this parameter. The value must be a Base64-encoded string. To split the string into several lines, use the _continue_ key word.
Critical
Syntax |
Critical = {coma-separated OIDList} |
Values |
Any valid object identifier that appears in the certificate [Extensions] section |
Default value |
n/a |
Sample value |
|
Can be manipulated in a pending request |
Yes |
This parameter carries the list of object identifiers of certificate extensions where the extension is set to critical. A certificate extension can also be set to critical with the certutil –setextension command during the time a certificate request is pending. For more information, see the section "certutil -setextension".
[RequestAttributes]
All keys from this section can be specified as part of the certreq -submit -attrib command. For example, instead of specifying the CertificateTemplate in the INF instruction file, you could use the following command at a command-line prompt.
certreq -submit -attrib "CertificateTemplate:Domaincontroller" dcname.req
CertificateTemplate
Syntax |
CertificateTemplate = {Templatename} |
Values |
Any valid certificate template name |
Default value |
n/a |
Sample value |
Critical = "DomainController" |
Can be manipulated in a pending request |
Yes |
The value of this key instructs the CA as to which certificate template should be used in processing the certificate request. The name must be specified as the common name of the certificate template or the object identifier of the template, not the template display name. A list of valid certificate template common names can be determined with the following command.
certutil -template
SAN
Syntax |
SAN = ["{tag}={value}&{tag}={value}]..." To see an example of how to compose a request for a SAN see the "How to use the Certreq.exe utility to create and submit a certificate request that includes a SAN" section in Microsoft KB article 931351. |
Values |
A list of valid subjectalternatename2 extension tags. email, upn, dns, guid, url, ipaddress, oid Alternatively, any valid object identifier can be specified. |
Default value |
n/a |
Sample value |
See below; should always include double quotation marks around value(s) |
Can be manipulated in a pending request |
Yes |
The subject alternative name can be specified in various ways. A service principal name (SPN) is specified as a user principal name (UPN) value. The value is a string type by default but can have a prefix of a tag in section brackets "{}" that determines the data type of the value explicitly as exemplified in the following table.
| SAN string | |
|---|---|
|
An ASN.1 string is inserted in the subject alternative name with one or several encoded extensions. The octet is a wrapper around a Base64 string encoded in binary format. |
|
An ASN.1 string is inserted in the subject alternative name with one or several encoded extensions. The value is a string encoded with a UTF8 wrapper. |
|
An ASN.1 string is inserted in the subject alternative name with one or several encoded extensions. |
|
The user’s e-mail address is inserted in the subject alternative name. |
|
The DNS name is set to the computer’s FQDN. |
|
The distinguished name is set to the domain controller's distinguished name. |
|
The URL is set to an http URL. |
|
The IP is inserted in the subject alternative name. |
|
A given object identifier is inserted in the subject alternative name. |
|
The UPN name represents the user. |
|
A GUID is inserted in the subject alternative name. |
Multiple tags and values must be combined with an ampersand (&). For example, to set the UPN and the GUID, you would have to set the subject alternative name as follows at a command-line prompt.
-attrib "SAN:upn=John.Smith@contoso.com&guid=f7c3ac41-b8ce-4fb4-aa58-3d1dc0e36b39"
If you insert the subject alternative name in the INF file, the syntax would look like this.
SAN="upn=John.Smith@contoso.com&guid=f7c3ac41-b8ce-4fb4-aa58-3d1dc0e36b39"
-policy
For a detailed description and examples of this option, see the "Planning and Implementing Cross-Certification and Qualified Subordination Using Windows Server 2003" white paper at https://www.microsoft.com/technet/prodtechnol/windowsserver2003/technologies/security/ws03qswp.mspx.
-submit
This is the default option for certreq.exe. If no option is specified explicitly at the command-line prompt, certreq.exe attempts to submit a certificate request to a CA. You must specify a certificate request file when using the –submit option. If this parameter is omitted, a common File Open window is displayed where you can select the appropriate certificate request file. For more information about the available command-line parameters for this option, see Certreq –submit fails with error 0x80094800 or type certreq -submit -? from a command line.
Certificate attributes from the RequestAttributes section in the INF instruction file can be alternatively specified as a command-line parameter for Windows 2000 Server and Windows Server 2003. For a list of valid subject alternative tags that may be used with the –submit parameter, see SAN. It is important to separate attribute types with "\n". Use an ampersand (&) to separate each specific subject alternative name attribute value.
The following are samples of certreq.exe commands.
certreq -attrib "SAN:email=John.Smith@contoso.com" -submit myreq.req
certreq -submit -attrib "CertificateTemplate:Domaincontroller\nSAN:DNS=w2k3bodc.contoso.com" dcname.req dcname.cer dcname.p7b
certreq -submit -attrib "SAN:UPN=admin@contoso.com&email=sample@bar.com&guid=f7c3ac41-b8ce-4fb4-aa58-3d1dc0e36b39"
-retrieve
This option allows you to retrieve an issued certificate from the CA. Certificate owners or submitters can retrieve their certificate(s) from a Windows 2000 or 2003 CA. The certificate manager can retrieve all certificates from a Windows Server 2003 CA. This is not a security issue because certificates that are made available through the CA database contain only public information and only the original requestor may retrieve an issued certificate.
-accept
The final and most important step of the certificate enrollment process is to accept a certificate or response after it has been issued and retrieved from the CA. Certificates that are auto-enrolled or requested through the MMC Snap-In are accepted using the automation built into these applications. However, manual certificate requests, such as those submitted using certreq.exe, must be accepted and installed manually. The -accept parameter of certreq.exe links the previously generated private key with the issued certificate and removes the pending certificate request from the system where the certificate is requested. Accepting a CMC full response is required when archiving a private key on the CA.
-sign
Once the template administrator has configured the template to require one or more signatures on a certificate request, you must add these signatures to the request in order for the CA to process it correctly. The default Certificate Services Web enrollment pages can add only one signature to a certificate request, specifically when an Enrollment Agent certificate is used to request a smart card certificate on behalf of another user. If more than one signature is required, you must add these signatures with certreq.exe –sign from the command line to the raw certificate request, one at a time.