Using the CLMUtil Command-Line Tool
CLMUtil is a command-line tool in Microsoft® Identity Lifecycle Manager "2" Certificate Management Service (ILM CMS).
The following topics describe CLMUtil configuration and commands:
CLMUtil Configuration
CLMUtil Commands
Encrypting a Passphrase File with CLMUtil
CLMUtil Configuration
The CLMUtil configuration file, CLMUtil.exe.config, specifies configuration settings for CLMUtil. Table 1 shows the settings for CLMUtil.exe.config.
Table 1 Settings for CLMUtil.exe.config
| Setting | Description |
|---|---|
DatabasePath |
Connection path to the SQL Server database. You can enter this as a database connection string or as a protected registry string from the Web.config file. |
DefaultCertificateTemplateOID |
Object identifier for the default certificate template that CLMUtil should use. For example, 1.2.3.4. This setting is required when running the importpfx and importpfxbatch commands to map external certificates to profile templates. |
CertImportDebugFile |
Local directory on the CLM server for storing debugging data. This value can be an empty string, if you want to disable debugging. For example, E:\Debug.txt. |
ImportPfxSuccessDirectory |
Local directory on the CLM server for storing import successes for the importpfxbatch command only. For example, E:\Success. |
ImportPfxReportFileName |
Local file on the CLM server for storing import reports for the importpfxbatch command only. For example, E:\Success\Report.txt. |
You can edit CLMUtil.exe.config in a text editor such as Notepad. The ILM CMS installation software installs CLMUtil.exe.config at the following location: %ProgramFiles%\Microsoft Certificate Lifecycle Manager\Bin\CLMUtil.exe.config.
Important
Before you use CLMUtil, you must update the CLMUtil.exe.config to specify your database path and the default certificate template object identifier. If this object identifier is not valid, or does not correspond to an actual certificate template object identifier, certificates that you import by using the importpfx command, or commands derived from it, cause CLMUtil to display unknown certificate template names for imported certificates. Configuring other settings is optional.
CLMUtil Commands
The ILM CMS installation software installs CLMUtil at the following location: %ProgramFiles%\Microsoft Certificate Lifecycle Manager\Bin\CLMUtil.exe.
The following topics describe the CLMUtil commands:
Formatting legend for the CLMUtil command syntax
CLMUtil command parameters
encodedpapi
decodedpapi
deleterequest
dispsdaccess
dispsdadobject
genkey
importpfx
importpfxbatch
omitcertificateduringrecovery
sync
syncrequest
Formatting legend for the CLMUtil command syntax
Table 2 shows the formatting legend for the CLMUtil command syntax.
Important
Unless you add an em dash (-) before some CLMUtil commands and parameters, CLMUtil does not process your command. Throughout this document, we have marked the commands and parameters that require that you add an em dash.
Table 2 Formatting for the CLMUtil command syntax
| Format | Meaning |
|---|---|
Italic |
Information that the user must supply. |
Bold |
Elements that the user must type exactly as shown. |
Ellipsis (…) |
Parameter that can be repeated several times in a command line. |
Between brackets([]) |
Optional items. |
Between braces ({}); choices separated by pipe (|). Example: {even|odd} |
A set of choices from which the user must choose only one. |
CLMUtil command parameters
All CLMUtil commands support two parameters. Table 3 shows these parameters.
Table 3 CLMUtil command parameters
| Parameter | Description |
|---|---|
-unique |
Specifies that the ILM CMS request should not be overwritten in the CLM database, if it already exists. This is the default parameter. If you do not specify a parameter, CLMUtil uses this one. |
-overwrite |
Updates the requested information in the CLM database automatically without testing for potential problems. |
encodedpapi
Syntax |
CLMUtil {-inline | -file } {decodedpapi | -encodedpapi} [-base64 {on|off}] {FilePath | String} [Out]} |
Parameters |
|
Remarks |
Uses the computer's key to perform Data Protection API (DPAPI) encryption on a file or text string. |
Example command |
|
decodedpapi
Syntax |
CLMUtil {-inline | -file } {decodedpapi | -encodedpapi} [-base64 {on|off}] {FilePath | String} [Out] |
Parameters |
|
Remarks |
Performs Data Protection API (DPAPI) decryption. |
Example command |
|
deleterequest
Syntax |
CLMUtil [-test] [source {ca | clm | both}] -deleterequestCAComputer\CANameRequestID |
Parameters |
|
Remarks |
Deletes a request from a specified CA and deletes the associated certificate in the CLM database. |
Example command |
Note No data is deleted.
Note Data is deleted. |
dispsdaccess
Syntax |
CLMUtil {-dispdaccess | -dispsdadobject} InputString |
Parameters |
InputString Represents a security descriptor. |
Remarks |
Displays access information for a security descriptor. A security descriptor contains the security information associated with a securable object. All named Windows® objects are securable objects. Some unnamed objects, such as process and thread objects, can have security descriptors, also. For more information about security descriptors, see Security Descriptors and Access Control Lists Technical Reference (https://go.microsoft.com/fwlink/?LinkId=88418). |
Example command |
|
dispsdadobject
Syntax |
CLMUtil {-dispdaccess | -dispsdadobject} InputString |
Parameters |
InputString Represents an object in Active Directory. |
Remarks |
Displays information for an Active Directory® directory service object. |
Example command |
|
genkey
Syntax |
CLMUtil -genkey |
Parameters |
None |
Remarks |
Generates a hex-encoded symmetric key, and then displays it in the command prompt window. |
Example command |
|
importpfx
Syntax |
CLMUtil -importpfxP12Filename PassPhraseDetails CAComputer\CAName User. |
Parameters |
|
Remarks |
Automates Certutil.exe and adds the new CA entry to the CLM database. Note Certutil.exe is a command-line tool that is installed as part of Certificate Services in Windows Server® 2003. You can use Certutil.exe to dump and display certification authority (CA) configuration information, configure Certificate Services, back up and restore CA components, and verify certificates, key pairs, and certificate chains. |
Example command |
Note Rows are not overwritten.
Note Rows are overwritten.
Note Rows are overwritten. |
importpfxbatch
Syntax |
CLMUtil -importpfxbatchRootDirectory PassPhraseFileName CAComputer\CAName User |
Parameters |
|
Remarks |
Imports a batch of .p12 files into a specified root directory. CLMUtil moves files that it imports successfully to the directory specified by the ImportPfxSuccessDirectory setting in CLMUtil.exe.config. CLMUtil appends a time-stamped report file to each .pfx file processed in the batch run. CLMUtil specifies the report log location in the ImportPfxReportFileName setting in CLMUtil.exe.config. The report file shows the file name, the time that CLMUtil processed the file, whether the processing succeeded or failed, and whether CLMUtil moved the file to the directory that CLMUtil processed successful (ImportPfxSuccessDirectory). |
Example command |
Note Rows are not overwritten in the Certificates table.
Note Rows are overwritten in the Certificates table. |
omitcertificateduringrecovery
Syntax |
CLMUtil {-certidCertID| -usernameUserName-serialnumberSerialNumber} -omitcertificateduringrecovery {true|false} |
Parameters |
Important We recommend that you first run the omitcertificateduringrecovery command with the test parameter. |
Remarks |
Marks whether an archived certificate should be omitted from all CA certificate recovery operations that ILM CMS initiates. Important You must configure the database connection string in the CLMUtil.exe.config file before you run this command. |
Example command |
|
sync
Syntax |
CLMUtil [-test] [-nametype] [-submitted SubmittedDate | -completedCompletedDate | -requestidRequestIDValue] -syncCAComputer\CAName |
Parameters |
Important The sync parameter requires that the certificate subject names contain the fully-distinguished name for each user. |
Remarks |
Synchronizes the CA database and the CLM database. CLMUtil uses the distinguished name from the CA request to perform name translation. In addition, CLMUtil links the distinguished name to the new entry in CLM. |
Example command |
|
Table 4 shows the wildcard characters that you can use with the submitted, completed, and requestid parameters.
Table 4 Sync wildcard characters
| Wildcard character | Options |
|---|---|
+ |
Displays rows where the value (date or request ID) is greater than the specified value. For example, CLMUtil -submitted "+4/02/2007 12:00 AM" will only display rows for certificates that were submitted after 4/02/2007 at midnight. |
* |
Displays rows where the value (date or request ID) is less than the specified value. For example, CLMUtil -submitted "*4/02/2007 12:00 AM" will only display rows for certificates that were submitted at or before 4/02/2007 at midnight. |
syncrequest
Syntax |
CLMUtil -syncrequestCAComputer\CANameRequestIDUserIdentifier |
Parameters |
|
Remarks |
Adds an entry to the CLM database. The default command-line option (unique) will prevent any database updates, if ILM CMS finds an entry that has the same certification authority and request identifier entries. |
Example command |
Note If the request exists in the Certificates table, it will not be overwritten.
Note If the request exists in the Certificates table, it is overwritten. |
Encrypting a Passphrase File with CLMUtil
You can use the CLMUtil importpfx parameter import a passphrase file. Because this file contains passphrases, we recommend that you encrypt this file. In order to create an encrypted passphrase file, you must write an application. You can use the following code sample to write this application.
'===================================================================
' DISCLAIMER:
'-------------------------------------------------------------------
'
' This sample is provided as is and is not meant for use on a
' production environment. It is provided only for illustrative
' purposes. The end user must test and modify the sample to suit
' their target environment.
'
' Microsoft can make no representation concerning the content of
' this sample. Microsoft is providing this information only as a
' convenience to you. This is to inform you that Microsoft has not
' tested the sample and therefore cannot make any representations
' regarding the quality, safety, or suitability of any code or
' information found here.
'
'===================================================================
public static void EncryptFile(string strFile)
{
FileInfo fi = new FileInfo(strFile);
FileStream fs = new FileStream(strFile, FileMode.Open, FileAccess.Read);
byte[] data = new byte[fi.Length];
fs.Read(data, 0, (int)fi.Length);
fs.Close();
Certificate cert = new Certificate();
cert.Load("Ramji03Encryption.pfx", "1", CAPICOM_KEY_STORAGE_FLAG.CAPICOM_KEY_STORAGE_EXPORTABLE, CAPICOM_KEY_LOCATION.CAPICOM_CURRENT_USER_KEY);
ASCIIEncoding ascii = new ASCIIEncoding();
UnicodeEncoding uni = new UnicodeEncoding();
EnvelopedData enveloped = new EnvelopedDataClass();
enveloped.Content = uni.GetString(data);
//enveloped.Recipients.Add
string encryptedStr;
enveloped.Recipients.Add(cert);
encryptedStr = enveloped.Encrypt(CAPICOM_ENCODING_TYPE.CAPICOM_ENCODE_BASE64);//.CAPICOM_ENCODE_BINARY);//
byte[] outData; // = new byte[ascii.GetByteCount(encryptedStr)];
outData = Convert.FromBase64String(encryptedStr);
//outData = uni.GetBytes(encryptedStr);
FileStream fsOut = new FileStream(strFile + ".encrypted.p7", FileMode.Create, FileAccess.Write);
fsOut.Write(outData, 0, outData.Length);
fsOut.Close();
}