Managing Certificates Programmatically
Applies To: Windows Server 2003, Windows Server 2003 with SP1
IIS 6.0 includes the new certificate object, IISCertObj, which allows you to use scripts to process SSL certificates on your local computer or on a remote computer. You can use scripts in conjunction with IISCertObj, a COM object, to perform the following tasks:
Import copies of a certificate from a .pfx file (a file containing a PFX-encrypted certificate and a private key) from one server onto multiple servers.
Save backup copies of certificates on a central site.
Copy a certificate from one server onto multiple servers.
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 5.11 lists the IISCertObj properties that you need to generate server certificate requests.
Table 5.11 IISCertObj Properties Required for Server Certificate Requests
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:
Copy bAllowExport, bOverwriteExisting, DestinationServerName, DestinationServerInstance, DestinationServerUserName, DestinationServerPassword
Table 5.12 lists the parameters that the Copy method uses.
Table 5.12 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 5.13 lists the parameters that the Export method uses.
Table 5.13 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:
Import FileName, Password, bAllowExport, bOverwriteExisting
Table 5.14 lists the parameters that the Import method uses.
Table 5.14 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:
ImportToCertStoreFileNamePasswordbAllowExportbOverwriteExisting
Table 5.15 lists the parameters that the ImportToCertStore method uses.
Table 5.15 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 IISCertObj properties, ServerName and InstanceName.
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 5.16 lists the parameters that the Move method uses.
Table 5.16 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:
Copy bRemoveFromCertStore, bPrivateKey
Table 5.17 lists the parameters that the RemoveCert method uses.
Table 5.17 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 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 of IISCertObj, 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 of IISCertObj, 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 iisserver2,iisserver3,iisserver4 Administrator aal34290
Copying a server certificate from an existing server to a new server
Using the Copy method of IISCertObj, 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
Listing 5.4 provides a customizable text file that you can use to import a certificate from a .pfx file and assign it to the desired site.
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).
Listing 5.4 Sample Script for Importing Certificates
' certimp.vbs
'
' author: uladm 05/03/2002
'
' certimp.vbs for usage info
'
REM
REM LOCALIZATION
REM
L_SWITCH_PFX = "-c"
L_SWITCH_PFX_PASSWORD = "-p"
L_SWITCH_INSTANCE_ID = "-i"
L_SWITCH_SERVER = "-s"
L_SWITCH_USER = "-u"
L_SWITCH_PASSWORD = "-pwd"
L_DESC_PROGRAM = "certimp - imports a certificate from a pfx file and assigns it to the desired site"
L_DESC_PFX = "Specify pfx file name"
L_DESC_PFX_PASSWORD = "pfx password"
L_DESC_INSTANCE_ID = "<site> Specify server instance (site) name"
L_DESC_SERVER = "<server> Specify computer to configure"
L_DESC_USER = "User name"
L_DESC_PASSWORD = "User password"
L_DESC_EXAMPLES = "Examples:"
L_DESC_EXAMPLE1 = "certimp.vbs -c cert.pfx -p pfxpassword -i w3svc/1 -s iisserver1 -u Administrator -pwd aal34290"
L_ERR_IMPORT_ERROR = "Error importing certificate: "
L_ERR_IMPORT_SUCCESS = "Import succeeded."
REM
REM END LOCALIZATION
REM
REM
REM --- Globals ---
REM
dim g_dictParms
set g_dictParms = CreateObject ( "Scripting.Dictionary" )
REM
REM --- Set argument defaults ---
REM
g_dictParms(L_SWITCH_PFX) = ""
g_dictParms(L_SWITCH_PFX_PASSWORD) = ""
g_dictParms(L_SWITCH_INSTANCE_ID) = "w3svc/1"
g_dictParms(L_SWITCH_SERVER) = ""
g_dictParms(L_SWITCH_USER) = ""
g_dictParms(L_SWITCH_PASSWORD) = ""
REM
REM --- Begin Main Program ---
REM
if NOT ParseCommandLine ( g_dictParms, WScript.Arguments ) then
usage
WScript.Quit ( 0 )
end if
pfxfile = g_dictParms(L_SWITCH_PFX)
pfxfilepassword = g_dictParms(L_SWITCH_PFX_PASSWORD)
instance = g_dictParms(L_SWITCH_INSTANCE_ID)
server = g_dictParms(L_SWITCH_SERVER)
user = g_dictParms(L_SWITCH_USER)
userpassword = g_dictParms(L_SWITCH_PASSWORD)
REM
REM Check arguments
REM
if ( pfxfile = "" ) then
usage
WScript.Quit 0
end if
REM
REM Import certificate
REM
dim iiscertobj
set iiscertobj = WScript.CreateObject( "IIS.CertObj" )
if (user <> "") then
iiscertobj.UserName = user
if (userpassword <> "") then
iiscertobj.UserPassword = userpassword
end if
end if
if (server <> "") Then
iiscertobj.ServerName = server
end if
iiscertobj.InstanceName = instance
iiscertobj.Import pfxfile, pfxfilepassword, true, true
REM
REM Show Result
REM
if (err.number <> 0) then
WScript.echo L_ERR_IMPORT_ERROR
WScript.echo Err.Description & " (Error 0x" & Hex(Err.Number) & ")"
else
WScript.echo L_ERR_IMPORT_SUCCESS
end if
WScript.Quit 0
REM
REM
REM --- End Main Program ---
REM
REM
REM
REM ParseCommandLine ( dictParameters, cmdline )
REM Parses the command line parameters into the given dictionary
REM
REM Arguments:
REM dictParameters - A dictionary containing the global parameters
REM cmdline - Collection of command line arguments
REM
REM Returns - Success code
REM
Function ParseCommandLine ( dictParameters, cmdline )
dim fRet
dim cArgs
dim i
dim strSwitch
dim strArgument
fRet = TRUE
cArgs = cmdline.Count
i = 0
do while (i < cArgs)
REM
REM Parse the switch and its argument
REM
if i + 1 >= cArgs then
REM
REM Not enough command line arguments - Fail
REM
fRet = FALSE
exit do
end if
strSwitch = cmdline(i)
i = i + 1
strArgument = cmdline(i)
i = i + 1
REM
REM Add the switch,argument pair to the dictionary
REM
if NOT dictParameters.Exists ( strSwitch ) then
REM
REM Bad switch - Fail
REM
fRet = FALSE
exit do
end if
dictParameters(strSwitch) = strArgument
loop
ParseCommandLine = fRet
end function
REM
REM Usage ()
REM prints out the description of the command line arguments
REM
Sub Usage
WScript.Echo L_DESC_PROGRAM
WScript.Echo vbTab & L_SWITCH_PFX & " " & L_DESC_PFX
WScript.Echo vbTab & L_SWITCH_PFX_PASSWORD & " " & L_DESC_PFX_PASSWORD
WScript.Echo vbTab & L_SWITCH_INSTANCE_ID & " " & L_DESC_INSTANCE_ID
WScript.Echo vbTab & L_SWITCH_SERVER & " " & L_DESC_SERVER
WScript.Echo vbTab & L_SWITCH_USER & " " & L_DESC_USER
WScript.Echo vbTab & L_SWITCH_PASSWORD & " " & L_DESC_PASSWORD
WScript.Echo L_DESC_EXAMPLES
WScript.Echo L_DESC_EXAMPLE1
end sub