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

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.

ImportantImportant
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

Table 2 shows the formatting legend for the CLMUtil command syntax.

ImportantImportant
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

  • -base64

    Enables or disables base64 encoding. Base64 encoding is enabled by default.

  • -file

    Specifies that a file that CLMUtil uses for input. This is the default parameter. If you do not specify the -inline parameter, CLMUtil requires that you provide a FilePath.

  • FilePath

    Represents the path to a file. CLMUtil uses this file as input. This is the default parameter. For example, C:\CLMFiles\File.txt.

  • -inline

    Specifies that you will provide the input in the command prompt window.

  • String

    Represents a text string you type that CLMUtil should use as the input.

  • Out

    Represents how the CLMUtil should display or store the output. If you do not specify a value for Out, CLMUtil will display the output in the command prompt window.

Remarks

Uses the computer's key to perform Data Protection API (DPAPI) encryption on a file or text string.

Example command

  • To encrypt a text string with DPAPI and have the encrypted string displayed in the command prompt window:

    CLMUtil -inline -encodedpapi "This is Some Text"

  • To encrypt text in file Test.txt and output the encrypted text to file EncryptedTest.txt:

    CLMUtil -encodedpapi C:\Files\Test.txt C:\Encrypted\EncryptedTest.txt

decodedpapi

 

Syntax

CLMUtil {-inline | -file } {decodedpapi | -encodedpapi} [-base64 {on|off}] {FilePath | String} [Out]

Parameters

  • -base64

    Enables or disables base64 decoding. Base64 decoding is enabled by default.

  • -file

    Specifies that CLMUtil will use a file will for input. This is the default parameter. If you do not specify the -inline parameter, CLMUtil requires that you provide a FilePath.

  • FilePath

    Represents the path to a file that CLMUtil should use as input. This is the default parameter. For example, C:\CLMFiles\File.txt.

  • -inline

    Specifies that you will provide the input in the command prompt window.

  • String

    Represents a text string you provide that CLMUtil should use as the input.

  • Out

    Represents how CLMUtil should display or store the output. If you do not specify a value for Out, CLMUtil displays the output in the command prompt window.

Remarks

Performs Data Protection API (DPAPI) decryption.

Example command

  • To decrypt a text string by entering the encrypted text string in the command prompt window:

    CLMUtil -inline -decodedpapi AQAAANCMnd8BFdERjHOAWE/Cl+SB
    aAAAGS0RYSpNXEGp+AXDWytlvAQA
    AAACAAAAAAADZgAAqAAAADcxzAMil
    VQ8wLJMPeVD4tsAAAAAASAAACgAAA
    AEAAAAC0h7Hr13YXYyUZ0FVzd3OCY
    AAAA8YiBvdQ62HLruxiVeYkq+S8slrxY
    ZZNTFAAAALV6tEE7yHVkT0FBTF4RGi
    Qw4N1i

  • To decrypt an encrypted string from a file, Test.txt, and output the decrypted string to a file, Decrypted.txt:

    CLMUtil -decodedpapi C:\Files\Test.txt C:\Decrypted\decrypted.txt

deleterequest

 

Syntax

CLMUtil [-test] [source {ca | clm | both}] -deleterequestCAComputer\CANameRequestID

Parameters

  • source

    Represents the sources from which CLMUtil should delete information.

    Valid values include:

    • ca

      Deletes a request from a CA.

    • clm

      Deletes a certificate from CLM.

    • both

      Deletes a request from the CA and the associated certificate from CLM. This is the default setting.

  • -test

    Specifies that CLMUtil should display the output only and not execute the delete request.

    CautionCaution
    We recommend that you run the deleterequest command with the test parameter before deleting requests.

  • CAComputer\CAName

    Represents the name of the CA. You must enter the entire CA name (computer name and CA name) and separate these values with a backslash (\). CAComputer must match the ca_server_name value in the CLM SQL database CertificateAuthority table. CAName must match the ca_name value in the CLM SQL database CertificateAuthority table. If these values do not match the values in the CLM database, CLMUtil reports an error.

  • RequestID

    Represents the request ID for a specific request.

Remarks

Deletes a request from a specified CA and deletes the associated certificate in the CLM database.

Example command

  • To test how to delete a request from a specific CA with request ID 14:

    CLMUtil -test -deleterequest testpc.contoso.com\testCA 14

noteNote
No data is deleted.

  • To delete a certificate associated with request ID 27 from CLM:

    CLMUtil -clm -deleterequest testpc.contoso.com\TestCA 27

noteNote
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 (http://go.microsoft.com/fwlink/?LinkId=88418).

Example command

  • To display information for the O:BA security descriptor:

    CLMUtil -dispsdaccess O:BA

    (O:BA designates the built-in administrator account.)

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

  • To display access information for user Syed Abbas in the Contoso domain:

    CLMUtil -dispsdadobject "LDAP://cn=SyedAbbas,cn=Users,DC=Contoso,DC=com"

genkey

 

Syntax

CLMUtil -genkey

Parameters

None

Remarks

Generates a hex-encoded symmetric key, and then displays it in the command prompt window.

Example command

  • To generate a hex encoded symmetric key:

    CLMUtil -genkey

importpfx

 

Syntax

CLMUtil -importpfx P12Filename PassPhraseDetails CAComputer\CAName User.

Parameters

  • P12Filename

    Represents the full directory path for the location of the .p12 file that CLMUtil will import. You must include the file name.

  • PassPhraseDetails

    Represents the path to the encrypted passwords, which have .p7 fine name extensions, or the explicit password for the file with a .p12 file name extension.

  • CAComputer\CAName

    Represents the name of the CA. The entire CA name must be entered (computer name and CA name). These values must be separated with a backslash (\). CAComputer must match the ca_server_name value in the CLM SQL database CertificateAuthority table. CAName must match the ca_name value in the CLM SQL database CertificateAuthority table. If these values do not match the values in the CLM database, CLMUtil reports an error.

  • User

    Represents a user. You can specify a user by using an Active Directory attribute that uniquely identifies the user, for example, the distinguished name or e-mail alias. The user who is currently logged on must have the installed certificate to decrypt the passphrase file. This decrypted data provides the file name for the .p12 file for the password mapping required by Certutil.exe.

Remarks

Automates Certutil.exe and adds the new CA entry to the CLM database.

noteNote
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

  • To import a .p12 file into the CA and SQL Certificates table while associating the file with a specified user's distinguished name:

    clmUtil -importpfx c:\p12s\test.p12 c:\p12s\passphrase.p7 testpc.contoso.com\TestCA “CN=Syed Abbas,OU=Test,DC=Testing,DC=com”

noteNote
Rows are not overwritten.

  • To import a .p12 file into the CA and SQL Certificates table while associating the file with a specified user's distinguished e-mail address:

    clmUtil–overwrite -importpfx c:\p12s\test.p12 c:\p12s\passphrase.p7 testpc.contoso.com\TestCA syed.abbas@contoso.com

noteNote
Rows are overwritten.

  • To import a .p12 file into the CA and SQL Certificates table while associating the file with a specified user's e-mail address, and to use specify the password explicitly, rather than using a .p12s passphrase file:

    clmUtil –overwrite -importpfx c:\p12s\test.p12 x1234xyz testpc.contoso.com\TestCA syed.abbas@contoso.com

noteNote
Rows are overwritten.

importpfxbatch

 

Syntax

CLMUtil -importpfxbatch RootDirectory PassPhraseFileName CAComputer\CAName User

Parameters

  • RootDirectory

    Represents the file path where the .p12 files are stored.

  • PassPhraseFileName

    Represents the name of the passphrase file. The passphrase file must be .p7 format.

  • CAComputer\CAName

    Represents the name of the CA. The entire CA name must be entered (computer name and CA name). These values must be separated with a backslash (\). CAComputer must match the ca_server_name value in the CLM SQL database CertificateAuthority table. CAName must match the ca_name value in the CLM SQL database CertificateAuthority table. If these values do not match the values in the CLM database, CLMUtil reports an error.

  • User

    Represents the user whose .pfx files you are importing. You can use either the user's e-mail address (syed@contoso.com) or the Active Directory Distinguished Name for the user (CN=Syed Abbas, OU=Test, DC=Contoso, DC=com).

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

  • To import .p12 files that are located in C:\p12s into the CertificateAuthority table and Certificates table while associating the files with a specified user's Distinguished Name:

    clmUtil -importpfxbatch c:\p12s c:\p12s\Passphrase.p7 testpc.contoso.com\TestCA “CN=Syed Abbas,OU=Test,DC=Testing,DC=com”

noteNote
Rows are not overwritten in the Certificates table.

  • To import .p12 files located in C:\p12s into the CertificateAuthority table and Certificates table while associating them with a specified user's e-mail address:

    clmUtil –overwrite -importpfxbatch c:\p12s c:\p12s\Passphrase.p7 testpc.contoso.com\TestCA syed.abbas@contoso.com

noteNote
Rows are overwritten in the Certificates table.

omitcertificateduringrecovery

 

Syntax

CLMUtil {-certidCertID| -usernameUserName-serialnumberSerialNumber} -omitcertificateduringrecovery {true|false}

Parameters

  • -certid

    Specifies that a certificates cert_id value from the Certificates table in the CLM SQL database will follow the parameter.

  • CertID

    Represents the cert_id value from the Certificates table in the CLM SQL database.

  • -username

    Specifies that a user's user name will follow the parameter.

  • UserName

    Represents a user's user name. You must enter the user name in the Domain\UserName format.

  • -serialnumber

    Specifies that a certificate serial number will follow the parameter.

  • SerialNumber

    Represents a specific certificate's serial number.

  • true

    Specifies that the certificate will be omitted. This is the default value, and CLMUtil will apply this value, if you do not explicitly specify one.

  • false

    Specifies that the certificate will be included.

  • -test

    Tests how the command will update the certificate.

ImportantImportant
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.

ImportantImportant
You must configure the database connection string in the CLMUtil.exe.config file before you run this command.

Example command

  • To mark that a certificate with request ID 1234 should be omitted from all recovery operations that ILM CMS initiates:

    CLMUtil -certid 1234 -omitcertificateduringrecovery

  • To mark that a specific user's certificate should be omitted from all recovery operations that ILM CMS initiates:

    CLMUtil -username testpc.contoso.com\Syed -serialnumber 19befedc000000000471 -omitcertificateduringrecovery true

sync

 

Syntax

CLMUtil [-test] [-nametype] [-submitted SubmittedDate | -completedCompletedDate | -requestidRequestIDValue] -syncCAComputer\CAName

Parameters

  • CAComputer\CAName

    Represents the name of the CA. The entire CA name must be entered (computer name and CA name). These values must be separated with a backslash (\). CAComputer must match the ca_server_name value in the CLM SQL database CertificateAuthority table. CAName must match the ca_name value in the CLM SQL database CertificateAuthority table. If these values do not match, the values in the CLM database, CLMUtil reports an error.

  • -name

    Specifies a user name format for CLMUtil to use when looking up certificates in the CA database. This parameter must be followed by type.

  • type

    Represents the type of user name for CLMUtil to use when looking up certificates in the CA. The default value is requestername. The following are accepted name types:

    • subject

    • requestername

    • UPN

    • A hard-coded Windows NT® 4.0 name

    • email

  • -submitted

    Specifies that CLMUtil should only show rows in the database where the date or date range matches SubmittedDate. Table 4 shows the wildcard characters that you can use with this parameter.

  • SubmittedDate

    Represents a date or date range when a certificate request was submitted. You can specify a date range by enclosing the two dates between parentheses ("").

  • -completed

    Specifies that CLMUtil should only show rows in the database where the date or date range matches CompletedDate. Table 4 shows the wildcard characters that you can use with this parameter.

  • CompletedDate

    Represents a date or date range when a certificate request was completed. You can specify a date range by enclosing the two dates between parentheses ("").

  • -requestid

    Specifies that CLMUtil should only show rows in the database where the ID or ID range matches the value(s) sp RequestIDValue. Table 4 shows the wildcard characters that you can use with this parameter.

  • RequestIDValue

    Represents a request ID or a range of request IDs for certificate requests. You can specify that a request ID should be between two request IDs.

  • -test

    We recommend that you use the sync command with the -test parameter before you use the overwrite parameter. Doing so helps identify potential CA connection and name translation issues prior to running the overwrite command.

ImportantImportant
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

  • To copy all requests from the CA to the SQL Certificates table:

    clmUtil -overwrite -sync testpc.contoso.com\TestCA

  • To copy all requests with a request ID between 10 and 20 (inclusive) from the CA to the SQL Certificates table:

    clmUtil -overwrite -requestid 10 20 -sync testpc.contoso.com\TestCA

  • To copy all requests that do not already exist in the Certificates table from the CA to the Certificates table, and to specify that only the rows with a submitted date that occurred on or before 4/13/2007 at 12:00 AM should be copied:

    clmUtil -unique -submitted "*4/13/2007 12:00 AM" -sync testpc.contoso.com\TestCA

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 -syncrequest CAComputer\CAName RequestID UserIdentifier

Parameters

  • CAComputer\CAName

    Represents the name of the CA. The entire CA name must be entered (computer name and CA name). These values must be separated with a backslash (\). CAComputer must match the ca_server_name value in the CLM SQL database CertificateAuthority table. CAName must match the ca_name value in the CLM SQL database CertificateAuthority table. If these values do not match the values in the CLM database, CLMUtil reports an error.

  • RequestID

    Represents the certificate identifier in the CA. CLMUtil obtains the CLM database connection credentials from the DatabasePath setting in CLMUtil.exe.config. CLMUtil obtains the default certificate template object identifier from the DefaultCertificateTemplateOID setting in CLMUtil.exe.config.

  • UserIdentifier

    Represents the user names in Active Directory to use to populate the cert_user_uuid field in the CLM database Certificates table. The object identifier must be an Active Directory attribute that uniquely identifies the user, for example, a distinguished name or an e-mail alias.

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

  • To copy the request with request ID of 27 from the CA to the SQL Certificates table and associate that request with user Syed Abbas by distinguished name:

    clmUtil –syncrequest testpc.contoso.com\TestCA 27 “CN=Syed Abbas,OU=Test,DC=Testing,DC=com”

noteNote
If the request exists in the Certificates table, it will not be overwritten.

  • To copy the request with request ID 99 from the CA to the SQL Certificates table and associate that request with user Syed Abbas by e-mail address:

    clmUtil -overwrite –syncrequest testpc.contoso.com\TestCA 99 syed@contoso.com

noteNote
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();
        }

Community Additions

ADD
Show: