Managing Server Certificates by Using IISCertObj

  • Article

Applies To: Windows Server 2003, Windows Server 2003 with SP1

You can use IISCertObj to perform the following tasks:

  • Import copies of a server certificate from a .pfx file (a file containing a PFX-encrypted server certificate and a private key) from a server to multiple servers.

  • Save backup copies of server certificates on a central site.

  • Copy a server certificate from one server to multiple servers.

When using IISCertObj, you must set properties for the methods that you call. The following sections outline the necessary properties and the methods that you need to manage server certificates.

Setting IISCertObj Properties

Because a method will return an error message if the required properties for that method are not available when the method is called, you should set properties before you call methods. Table 9.4 lists the IISCertObj properties that you need to generate server certificate requests.

Table 9.4 Required IISCertObj Properties

Property Attribute Name Attribute Value Description 
ServerName

Data Type

String, write only

Contains the name of the computer on which server certificate operations are executed.

 
UserName

Data Type

String, write only

Specifies the user name that is used to log on to the remote computer. If UserName is empty, the credentials of the user that is currently logged on are used.

 
UserPassword

Data Type

String, write only

Specifies the password that is used for logging onto the remote computer.

 
InstanceName

Data Type

String, write only

Identifies the targeted metabase instance. W3svc/1 is an example.

Applying IISCertObj Methods

You can apply the following methods to the IISCertObj object: Copy, Export, GetCertInfo, Import, ImportToCertStore, IsExportable, IsInstalled, Move, and RemoveCert.

Copy

The Copy method allows you to copy a server certificate from one instance of IIS to another and from one computer to another. Use the following syntax with the Copy method:

bAllowExport, bOverwriteExisting, DestinationServerName, DestinationServerInstance, DestinationServerUserName, DestinationServerPassword

Table 9.5 lists the parameters that the Copy method uses.

Table 9.5 Copy Method Parameters

Parameter Data Type Description 
bAllowExport

Boolean

Indicates whether the imported server certificate will be exportable (true) or not exportable (false).

 
bOverwriteExisting

Boolean

Indicates whether, if an identical server certificate already exists, it is overwritten (true) or not overwritten (false).

 
DestinationServerName

String

Specifies the computer name of the server to which the server certificate will be moved.

 
DestinationServerInstance

String

Specifies the IIS metabase instance at which the server certificate will be pointed. For example, w3svc/1.

 
DestinationServerUserName

String

Specifies the user name for the destination server. If empty, the user name of the user who is currently logged on will be used.

 
DestinationServerPassword

String

Specifies the password for the destination server when the DestinationServerUserName parameter is used.

Export

The Export method exports a copy of a server certificate to a file. The target file can be on a local or remote computer. Use the following syntax with the Export method:

Export FileName Password bPrivateKey bCertChain bRemoveCert

Table 9.6 lists the parameters that the Export method uses.

Table 9.6 Export Method Parameters

Parameter Data Type Description 
FileName

String

Specifies the name of the targeted file. For example, C:\Mydir\Mycert.pfx.

 
Password

String

Specifies the password that is used to secure the file specified as FileName.

 
bPrivateKey

Boolean

Indicates whether the private key is exported (true) or not exported (false).

 
bCertChain

Boolean

Indicates whether the certificate trust chain is exported (true) or not exported (false).

 
bRemoveCert

Boolean

Indicates whether the binding of a server certificate is removed (true) or not removed (false).

GetCertInfo

The GetCertInfo method allows you to acquire information on a server certificate that is installed on the computer specified by the IISCertObj properties, ServerName and InstanceName.

The GetCertInfo method uses no parameters.

Import

The Import method imports a copy of a server certificate from a file to a local or remote computer. Use the following syntax with the Import method:

FileName Password bAllowExport bOverWriteExisting

Table 9.7 lists the parameters that the Import method uses.

Table 9.7 Import Method Parameters

Parameter Data Type Description 
FileName

String

Specifies the name of the server certificate file to import.

 
Password

String

Specifies the password that is used to secure the file specified as FileName.

 
bAllowExport

Boolean

Indicates whether the imported server certificate is exportable (true) or not exportable (false).

 
bOverwriteExisting

Boolean

Indicates whether, if an identical server certificate already exists, it is overwritten (true) or not overwritten (false).

ImportToCertStore

The ImportToCertStore method imports a copy of a server certificate from a file to the certificate store on a local or remote computer. Use the following syntax with the ImportToCertStore method:

ImportToCertStore FileName Password bAllowExport bOverwriteExisting

Table 9.8 lists the parameters that the ImportToCertStore method uses.

Table 9.8 ImportToCertStore Method Parameters

Parameter Data Type Description 
FileName

String

Specifies the name of the server certificate file to import.

 
Password

String

Specifies the password that is used to secure the file specified as FileName.

 
bAllowExport

Boolean

Indicates whether the imported server certificate is exportable (true) or not exportable (false).

 
bOverwriteExisting

Boolean

Indicates whether, if an identical server certificate already exists, it is overwritten (true) or not overwritten (false).

IsExportable

The IsExportable method allows you to determine whether a server certificate is exportable from a computer that is specified by the IIS ServerName and InstanceName properties.

The IsExportable method uses no parameters.

IsInstalled

The IsInstalled method allows you to determine whether a server certificate is installed on a computer that is specified by the IIS ServerName and InstanceName properties.

The IsInstalled method uses no parameters.

Move

The Move method allows you to move a server certificate from one instance of IIS to another, and from one computer to another. Use the following syntax with the Move method:

Move bAllowExport bOverwriteExisting DestinationServerName DestinationServerInstance DestinationServerUserName DestinationServerPassword

Table 9.9 lists the parameters that the Move method uses.

Table 9.9 Move Method Parameters

Parameter Data Type Description 
bAllowExport

Boolean

Indicates whether the imported server certificate is exportable (true) or not exportable (false).

 
bOverWriteExisting

Boolean

Indicates whether, if an identical server certificate already exists, it is overwritten (true) or not overwritten (false).

 
DestinationServerName

String

Specifies the computer name of the server to which the server certificate will be moved.

 
DestinationServerInstance

String

Specifies the IIS metabase instance at which the server certificate will be pointed. For example, w3svc/1.

 
DestinationServerUserName

String

Specifies the user name for the destination server. If no user name is entered, the user name of the user that is currently logged on will be used.

 
DestinationServerPassword

String

Specifies the password for the destination server when the DestinationServerUserName parameter is used.

RemoveCert

The RemoveCert method allows you to delete a server certificate from a certificate store. Use the following syntax with the RemoveCert method:

RemoveCert bRemoveFromCertStore bPrivateKey

Table 9.10 lists the parameters that the RemoveCert method uses.

Table 9.10 RemoveCert Method Parameters

Parameter Data Type Description 
bRemoveFromCertStore

Boolean

Indicates whether the server certificate is removed (true) or not removed (false).

 
bPrivateKey

Boolean

Indicates whether the private key of the server certificate is removed (true) or not removed (false).

Sample Server Certificate Management Scripts

In IIS, if you use Windows Script Host or ASP, you can execute scripts that communicate with IISCertObj programmatically to import, archive, or export server certificates.

Importing server certificates to multiple servers

Large sites often need to use one server certificate for secure user logon to multiple servers. It would be time-consuming to use the Microsoft Management Console (MMC) to add copies of the server certificate to each server. By using the Import method, you can install copies of the same server certificate on all of the targeted servers.

To import a server certificate from a certificate store on one server to other servers, first save the following script in your text editor as CertImport.vbs.

Important

You must be a member of the Administrators group on the local computer to run scripts and executables. As a security best practice, log on to your computer by using an account that is not in the Administrators group, and then use the runas command to run your script or executable as an administrator. At a command prompt, type runas /profile /User:MyMachine</STRONG>Administrator cmd to open a command window with administrator rights and then type cscript.exe ScriptName (include the script's full path and any parameters).

Option Explicit
Dim iiscertobj, pfxfile, pfxfilepassword, InstanceName, WebFarmServers, IISServer
Set iiscertobj = WScript.CreateObject("IIS.CertObj")
pfxfile = WScript.Arguments(0)
pfxfilepassword = WScript.Arguments(1)
InstanceName = WScript.Arguments(2)
WebFarmServers = split(WScript.Arguments(3), ",")
iiscertobj.UserName = WScript.Arguments(4)
iiscertobj.UserPassword = WScript.Arguments(5)
For Each IISServer in WebFarmServers
  iiscertobj.ServerName = IISServer
  iiscertobj.InstanceName = InstanceName
  iiscertobj.Import pfxfile, pfxfilepassword, true, true
Next

After you save the script as CertImport.vbs, run this command:

Certimport.vbs cert.pfx pfxPassword w3svc/1 iisserver1,iisserver2,iisserver3 Administrator aal34290

Saving backup copies of server certificates in a central archive

Using the Export method, you can archive a backup of each server certificate on your server farm to a central site.

To export copies of server certificates to the central site, first save the following script in your text editor as Save_all_certs.vbs.

Option Explicit
Dim iiscertobj, targetServer, targetServers, pfxbasename, pfxpassword, InstanceName 
Set iiscertobj = WScript.CreateObject("IIS.CertObj")
pfxbasename = WScript.Arguments(0) 
pfxpassword = WScript.Arguments(1) 
InstanceName = WScript.Arguments(2) 
targetServers = split(WScript.Arguments(3), ",")
iiscertobj.UserName = WScript.Arguments(4) 
iiscertobj.UserPassword = WScript.Arguments(5)
iiscertobj.InstanceName = InstanceName
For Each targetServer in targetServers 
  iiscertobj.ServerName = targetServer 
  iiscertobj.Export pfxbasename + targetServer + ".pfx", pfxpassword, true, false, false 
Next

After you save the script as Save_all_certs.vbs, run this command:

Save_all_certs.vbs C:\certbackup\ pfxpassword w3svc/1 iisserver1,iisserver2,iisserver3 Administrator aal34290

Copying a server certificate from an existing server to a new server

Using the Copy method, you can copy a server certificate to a new server after you add the server to a server farm.

To copy a server certificate from an existing server to a new server, first save the following script in your text editor as Certcopy.vbs.

Option Explicit
Dim iiscertobj, targetServer, targetServers, targetInstance
Set iiscertobj = WScript.CreateObject("IIS.CertObj")
iiscertobj.ServerName = WScript.Arguments(0)
iiscertobj.Instancename = WScript.Arguments(1)
targetServers = split(WScript.Arguments(2), ",")
targetInstance = WScript.Arguments(3)
iiscertobj.UserName = WScript.Arguments(4)
iiscertobj.UserPassword = WScript.Arguments(5) 
For Each targetServer in targetServers
  iiscertobj.Copy true, true, targetServer, targetInstance
Next

After you save this script as Certcopy.vbs, run this command:

Certcopy.vbs iisServer1 w3svc/1 iisServer2 w3svc/1 Administrator asdf-0324