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