keyreq.exe

keyreq

RSA Key Requester Tool v3.0.301.001
Prim'X Tools

Keyreq generates a RSA key in a current user CSP store, computes a certificate request for the key, submit it to a Windows 2003 Certificate Server (CA), manage the response (immediate or asynchronous), and optionally
(1) exports the resulting key and certificate to a key-file, (.pfx) and
(2) creates a certificate chain file (.p7b), and
(3) creates the associated ZoneCentral personal acces file (.zaf), and
(4) finally deletes the key and the certificate from the CSP store.

Through their CSP provider, keys can be generated by and inside smart-cards and tokens, and certificates can then be also stored in the card/token.

- The RSA key size and attributes (exchange/signature), and the CSP store can be configured.
- The CA used to deliver the certificate can be found automatically or configured. The certificate model to use can also be configured.
- The Distinguished Name for the target key owner can be configured or found automatically from a Windows account name.
- The names of the output files are deduced from the given user name. The output directory for these files can be configured.
- The password for the key-file, if any, must be configured.
- If the CA delivers certificates automatically, a single command is enough to complete the whole process. If the CA requests an approval from some enrollment agent, the first command will produce a requestId, which will have to be reused later on (when the certificate will have been delivered) with the same command, to terminate the procedure.

Keyreq can be used by a Security Administrator to pre-generate keys, certificates, and personal access lists for users. The key-files (.pfx) and the access list can then be given to users, or pre-installed on computers, or put in a network share. The certificate-files (.p7b) can also be used later to build group access files for ZoneCentral. If correctly configured, the Certificate Server may have automatically published the certificates in ActiveDirectory (in the users accounts), and the certificates are then also available through LDAP requests.
Being a command-line tool, keyreq can be scripted for any number of users, given their domain names and the passwords for their future key-files.

Platforms:

Keyreq works only on a Windows XP+ workstation, and with a Windows Certificate Authority (Windows 2003+). It does not work on 2000 workstations, but may work with a 2000 server. On the local workstation, the Windows components "CERTCLI.DLL" and "XENROLL.DLL" must be available.

IMPORTANT:

THERE IS NO USE OF PRIM'X OR ZONECENTRAL CRYPTOGRAPHY,
except for the 'personal access list' generation, extracted from ZoneCentral.
This is only a simple tool and everything else, including the private key generation and the PFX generation is accomplished with the standard Windows cryptographic APIs.
This tool is provided 'as is' without any warranty.

The key-generation process is made by the targeted/used CSP.

Command Line Parameters

keyreq

[-dn distinguishedName]
[-user userAccountName]
[-pwd accountPassword]
[-dir outputDir]
[-ca certificateAuthority]
[-id previousRequestId]
[-tpl certificateTemplate]
[-zaf]
[-nopfx]
[-pfxpwd passwordForPFX]
[-noP7]
[-csp CSPToUse]
[-ats]
[-ptc]
[-size keySize]
[-keep]

Argument Description

-dn <DN>

Distinguished name, in X500 format, of the owner of the key and certificate (subject).
Example:C=FR, DC=MyDomain, OU=MyOrg, CN=John Smith
If not supplied, keyreq will find the DN associated to the username (-user) in the ActiveDirectory domain and use it.
If supplied, keyreq will insert this value in the certificate request.
Note: even if supplied, some certificate templates on the CA may not use this value to generate the subject field of the certificate, and use instead a DN extracted from the ActiveDirectory domain.

-user <name>

Windows account name of the user owner of the key and certificate. This value MUST include the domain name, in any format (DOMAIN\User, user@domain, etc.).
This value is used to compute the names of the files to generate, if any: 'DOMAIN User.extension' .
If supplied together with a password (-pwd), the value is also used as a credential to gain access to the certificate Server.

-pwd <password>
Password associated to the username account (-user). Generally not necessary. May be given only if the current Windows user is not himself a member of the domain : the couple username/password will then be used as a credential to gain access to the certificate Server.

-dir <output dir>

Target directory for the generated files, if any. May be relative to the current directory.
If not supplied, the current directory is used.

-ca <CA>

Certificate Server and Authority who must deliver the certificate, in the form COMPUTERNAME\CANAME.
Example: 'MYDC\My Root Authority', where MYDC is a domain controler with a Certificate Services available, and My Root Authority is the name of a Certificate Authority (which may not necessarily be a root).
If not supplied, keyreq will try to find the Default CA for the current domain of the current workstation.
Warning: in this case, if there are multiple CAs available, no choice will be requested, the default one will be used to send the certificate request.

-id <requestId>

If 'automatic delivery' is enabled in the Certificate Server, this parameter is not used.
If not, the certificate delivery procedure needs threee steps : request issuance (1), separate approval by an enrollment agent (2), certificate download(3).
The first keyreq command will format and send the request, and, if the certificate is not issued immediately, will display a request Id.
You can then retry the same command, adding the parameter (-id requestId) : if the certificate was delivered meanwhile, the command completes the work. If not, you receive the same requestId and 'pending' status.

-tpl <template>

Certificate template to use for te requested certificate. Must be given with its 'native english' name.
If not supplied, the standard 'User' template is used.

-zaf

The command must generate a ZoneCentral 'personal access list' for the target user.
This file is placed in the output directory (see -dir), and is named using the username (-user) parameter : DOMAIN Username.zaf .
Warning: keyreq will work even if ZoneCentral is not installed in the current computer, BUT it will use the current ZoneCentral policies for this access list, especially regarding recovery access and SOS access. So, you must have previously defined these policies, either on the domain controler (to which you computer belongs) or locally (with the .adm policy template, see the ZoneCentral Technical Guide).

-nopfx

The command must not generate a key file (.pfx). The RSA key will then remain in the CSP store where it has been generated. If this store is a simple logical store (like Windows' default), you should absolutely also use the -keep parameter, otherwise the key will be deleted (what's the use of a certificate without the corresponding private key ?).

-pfxpwd <password>

Password to use for the generated key-file (.pfx).
Mandatory if a key-file is generated (no -nopfx).
Warning: there is no useful tool to change the password for such a key-file, so you must provide here a real, good, and strong password.
Note: there is no use of any 'password strength policy', either from ZoneCentral nor from Windows.
You must keep this password secret (of course), and supply it to the target user.
The PFX file is placed in the output directory (see -dir), and is named using the username (-user) parameter : DOMAIN Username.pfx. It contains the RSA key (both private and public part), the issued certificate with its complete certification path (hierarchy).

-noP7

By default, the command also generates a .p7b file, which is a standard file containing the issued certificate and its complete certification path (hierarchy). This file does not contain the key.
Use this switch to not generate this file.
Note: keeping such files is often useful, especially when there is no easy mean to publish certificates in the organization. When you use ActiveDirectory, a Certificate Server, and an automatic 'mapping' between certificates and accounts, all certificates are available to users through LDAP requests, and so you may not need those files.

-size <key size>

Size of the RSA key. Values are 512, 1024 (default) and 2048 bits.

-csp <CSP>

CSP <store> to use. Supply the entire and exact full name of the CSP.
The CSP generates the RSA keypair and store it.
If the parameter -keep is not used, the keypair is deleted from this store at the end of he command (after having been exported to the PFX file, if requested).
If not supplied, the default CSP "Microsoft Enhanced Cryptographic Provider v1.0" is used.
If a "smart card" CSP is used, it will generate the keypair (depending on the card, either 'on-board' or not), and keyreq will write the issued certificate in the card.

-ats

Give the 'AT_SIGNATURE' attribute to the generated RSA-key.
By default, they have the 'AT_EXCHANGE' (encryption) attribute.
Note : a key cannot have both attributes inside a CSP. To use the same key for both usages, the key must be duplicated.
This parameter has no utility if the key is exported to a key-file (.pfx).
This parameter has no relationship with the <key usage> attribute of certificates.

-ptc

Activates the 'user protection' option for the generated key-pair.
This option requires a user-validation when the keypair is used. The user may choose among some levels of validation (OK only or a password).
This parameter has no utility if the key is exported to a key-file (.pfx), and has no utility either in the case of a Security Officer preparing keys for users.

-keep

Do not delete the RSA key from the CSP at the end of the command.
The default behaviour is to export the key to a key-file (PFX) and then delete the key in the CSP store.
Use this parameter when you want to keep the key in the CSP store, especially if the CSP is a "smart card" CSP.

Hints

For a smart card, use the following syntax : 'nopfx' is used because the target key-store is a smart-card or USB token and not a file, and then 'keep' is also used to leave keys and certificates inside this container :
keyreq -csp "csp name to use" -nopfx -keep

Only certificate templates published in the Certificate Authority can be used. The command 'certutil -template' on the server shows all the available templates, but they may not be published. Go to the Certificate Authority, select your authority, right click 'manage templates' to modify templates. Then go back to the Certificate Authority and check if this template is published. If not, do it.

Beware of the slightest differences between packages and versions of the server. A basic Windows 2003 Server, for instance, does NOT allow you to customize certificate templates, you can only use existing templates.

Certificate templates can enforce the CSP to use, or reduce the choice. Others may never use the DN supplied in the request, replacing it with information extracted from the ActiveDirectory users database. Other templates may enforce RSA key sizes. In those cases, the parameters supplied to keyreq may not give the expective results, even if the command is processed successfully. You must carefully study the certificate template you intend to use, make a trial on a few keys and certificates before going further.

For the processing of a massive amount of user accounts, il may be easier to turn on 'automatic delivery' on the Certificate Server (just during your work). To do so, go to the Certificate Authority, select your authority, display its properties, click on the 'advanced' button on the 'Strategies' tab, and turn on automatic delivery. Restart the CA. Warning: the certificate template may not accept this behaviour (it is generally the case when it allows any DN in the certificate request, because the CA cannot check the identity of the requester).

Limitations of this version

Keyreq cannot be used to renew certificates.
Keyreq cannot be used with existing RSA keys (in a PFX or in a CSP store).
If you need these features, issue a feature request to Prim'X labs.

Copyright

[keyreq] is a tool provided freely by Prim'X Technologies to help integration and deployment of Prim'X solutions.
[keyreq ] is delivered 'as is', without any warranty.
[keyreq] is supported by Prim'X Technologies. You may issue support requests, bug reports, or feature requests.

Argument	Description
-dn <DN>	Distinguished name, in X500 format, of the owner of the key and certificate (subject). Example:C=FR, DC=MyDomain, OU=MyOrg, CN=John Smith If not supplied, keyreq will find the DN associated to the username (-user) in the ActiveDirectory domain and use it. If supplied, keyreq will insert this value in the certificate request. Note: even if supplied, some certificate templates on the CA may not use this value to generate the subject field of the certificate, and use instead a DN extracted from the ActiveDirectory domain.
-user <name>	Windows account name of the user owner of the key and certificate. This value MUST include the domain name, in any format (DOMAIN\User, user@domain, etc.). This value is used to compute the names of the files to generate, if any: 'DOMAIN User.extension' . If supplied together with a password (-pwd), the value is also used as a credential to gain access to the certificate Server.
-pwd <password>	Password associated to the username account (-user). Generally not necessary. May be given only if the current Windows user is not himself a member of the domain : the couple username/password will then be used as a credential to gain access to the certificate Server.
-dir <output dir>	Target directory for the generated files, if any. May be relative to the current directory. If not supplied, the current directory is used.
-ca <CA>	Certificate Server and Authority who must deliver the certificate, in the form COMPUTERNAME\CANAME. Example: 'MYDC\My Root Authority', where MYDC is a domain controler with a Certificate Services available, and My Root Authority is the name of a Certificate Authority (which may not necessarily be a root). If not supplied, keyreq will try to find the Default CA for the current domain of the current workstation. Warning: in this case, if there are multiple CAs available, no choice will be requested, the default one will be used to send the certificate request.
-id <requestId>	If 'automatic delivery' is enabled in the Certificate Server, this parameter is not used. If not, the certificate delivery procedure needs threee steps : request issuance (1), separate approval by an enrollment agent (2), certificate download(3). The first keyreq command will format and send the request, and, if the certificate is not issued immediately, will display a request Id. You can then retry the same command, adding the parameter (-id requestId) : if the certificate was delivered meanwhile, the command completes the work. If not, you receive the same requestId and 'pending' status.
-tpl <template>	Certificate template to use for te requested certificate. Must be given with its 'native english' name. If not supplied, the standard 'User' template is used.
-zaf	The command must generate a ZoneCentral 'personal access list' for the target user. This file is placed in the output directory (see -dir), and is named using the username (-user) parameter : DOMAIN Username.zaf . Warning: keyreq will work even if ZoneCentral is not installed in the current computer, BUT it will use the current ZoneCentral policies for this access list, especially regarding recovery access and SOS access. So, you must have previously defined these policies, either on the domain controler (to which you computer belongs) or locally (with the .adm policy template, see the ZoneCentral Technical Guide).
-nopfx	The command must not generate a key file (.pfx). The RSA key will then remain in the CSP store where it has been generated. If this store is a simple logical store (like Windows' default), you should absolutely also use the -keep parameter, otherwise the key will be deleted (what's the use of a certificate without the corresponding private key ?).
-pfxpwd <password>	Password to use for the generated key-file (.pfx). Mandatory if a key-file is generated (no -nopfx). Warning: there is no useful tool to change the password for such a key-file, so you must provide here a real, good, and strong password. Note: there is no use of any 'password strength policy', either from ZoneCentral nor from Windows. You must keep this password secret (of course), and supply it to the target user. The PFX file is placed in the output directory (see -dir), and is named using the username (-user) parameter : DOMAIN Username.pfx. It contains the RSA key (both private and public part), the issued certificate with its complete certification path (hierarchy).
-noP7	By default, the command also generates a .p7b file, which is a standard file containing the issued certificate and its complete certification path (hierarchy). This file does not contain the key. Use this switch to not generate this file. Note: keeping such files is often useful, especially when there is no easy mean to publish certificates in the organization. When you use ActiveDirectory, a Certificate Server, and an automatic 'mapping' between certificates and accounts, all certificates are available to users through LDAP requests, and so you may not need those files.
-size <key size>	Size of the RSA key. Values are 512, 1024 (default) and 2048 bits.
-csp <CSP>	CSP <store> to use. Supply the entire and exact full name of the CSP. The CSP generates the RSA keypair and store it. If the parameter -keep is not used, the keypair is deleted from this store at the end of he command (after having been exported to the PFX file, if requested). If not supplied, the default CSP "Microsoft Enhanced Cryptographic Provider v1.0" is used. If a "smart card" CSP is used, it will generate the keypair (depending on the card, either 'on-board' or not), and keyreq will write the issued certificate in the card.
-ats	Give the 'AT_SIGNATURE' attribute to the generated RSA-key. By default, they have the 'AT_EXCHANGE' (encryption) attribute. Note : a key cannot have both attributes inside a CSP. To use the same key for both usages, the key must be duplicated. This parameter has no utility if the key is exported to a key-file (.pfx). This parameter has no relationship with the <key usage> attribute of certificates.
-ptc	Activates the 'user protection' option for the generated key-pair. This option requires a user-validation when the keypair is used. The user may choose among some levels of validation (OK only or a password). This parameter has no utility if the key is exported to a key-file (.pfx), and has no utility either in the case of a Security Officer preparing keys for users.
-keep	Do not delete the RSA key from the CSP at the end of the command. The default behaviour is to export the key to a key-file (PFX) and then delete the key in the CSP store. Use this parameter when you want to keep the key in the CSP store, especially if the CSP is a "smart card" CSP.