Signing and Checking Code with Authenticode
This section demonstrates how to sign code by creating digital signatures and associating them with files using Microsoft Authenticode technology. Creating a fully verifiable certificate might assume the existence of a complex hierarchy of certification authorities. A root certificate and a root private key are provided for testing purposes only. Independent software vendors (ISVs) must obtain a certificate from a certification authority that is trusted by default in Windows. (For a list of trusted certification authority (CA) see Microsoft Root Certificate Program Members.)
Authenticode consists of programs for digitally signing code files as well as programs for checking that the code files were successfully signed. Currently, Authenticode allows software vendors to sign:
- .cab files
- .cat files
- .ctl files
- .dll files
- .exe files
- .ocx and
The Authenticode programs are:
- MakeCert, which creates a test X.509 certificate.
- Cert2SPC, which creates a test software publishing certificate.
- SignCode, which signs a file.
- ChkTrust, which checks the validity of the file.
- MakeCTL, which creates a certificate trust list.
- CertMgr, which manages certificates, certificate trust lists, and certificate revocation lists.
- SetReg, which sets registry keys that control the certificate verification process.
- MakeCat, which creates a combined catalog of files to avoid multiple trust dialogs in Microsoft Internet Explorer 5 and later. MakeCat is described in Using Catalog Files.
Note All user input to these programs is now case-insensitive. Additionally, separate options now exist for the key-pair name and the private-key file.
MakeCert
Use the MakeCert test program to generate a test X.509 certificate. MakeCert performs the following tasks:
- Creates a public/private key pair for digital signatures and associates it with a name that you choose.
- Associates the key pair with a publisher's name that you choose.
- Creates an X.509 certificate, signed by the test root key or one you specify, that binds your name to the public part of the key pair. The certificate is output to a file, a system certificate store, or both.
The syntax for invoking MakeCert is:
MakeCert [basic options| extended options] outputFile
MakeCert's options consist of basic options and extended options. Basic options are the most commonly used to create a certificate. Extended options provide more flexibility. The options for MakeCert are also divided into three functional groups:
- Options applicable to software publishing certificate-file, private-key, and certificate store technology.
- Options specific to software publishing certificate-file and private-key technology only.
- Options specific to certificate store technology only.
Options in groups 2 and 3 cannot be mixed, with the exception of the -ic option.
MakeCert Group 1 Options
The following group 1 options may be applied in all cases:
Options are sorted alphabetically in the left (Microsoft Internet Explorer 4.0 and later) column, and the corresponding Microsoft Internet Explorer 3.02 options are given in the middle column. Internet Explorer 3.02 options that have no direct equivalent in Internet Explorer 4.0 or later will say either "N/A" or "(See -option)" in the column for Internet Explorer 4.0 and later, and are sorted alphabetically into the order of options for Internet Explorer 4.0 and later. For example, the Internet Explorer 3.02-C option follows the -b option for Internet Explorer 4.0 and later.
| Internet Explorer 4.0 and later | Internet Explorer 3.02 UPD | Description |
|---|---|---|
| -a algorithm | -a | For Internet Explorer 3.02: Indicates the SHA1 hash algorithm should be used. MD5 is the default For Internet Explorer 4.0 and later: The hash algorithm. Must be set to either SHA1 or MD5. The default is MD5. |
| -b dateStart | -B:dateStart | The date the certificate first becomes valid. The default is when the certificate is created. The format of dateStart is mm/dd/yyyy. |
| (See -$) | -C | The certificate will be used by commercial software publishers. |
| (See -$) | -C:f | The certificate will be used by commercial software publishers who have met the minimum financial criteria. |
| -cy certificateTypes | -t:types | For Internet Explorer 3.02: The certificate type. This parameter can be E for end-entity, C for certificate authority, or both. For Internet Explorer 4.0 and later: The certificate type. Can be end, authority, or both. End stands for end-entity and authority stands for certificate authority. |
| -d displayName | -d:displayName | The display name of the subject. |
| -e dateEnd | -E:dateEnd | The date when the validity period ends. The default is the year 2039. |
| -eku OID1,OID2... | N/A | Inserts a list of one or more comma-separated enhanced key usage Object Identifiers (OIDs) into the certificate. For example, -eku 1.3.6.1.5.5.7.3.2 inserts the client authentication OID. See wincrypt.h in the Cryptography Reference documentation for definitions of allowable OIDs. |
| N/A | -g | Creates a glue certificate (Internet Explorer 3.02 only.) |
| -h numChildren | -h:numChildren | The maximum height of the tree below this certificate. |
| (See -$) | -I | The certificate will be used by individual software publishers. |
| -l policyLink | -l:policyLink | A link to software publishing certificate agency policy information—for example, a URL. |
| -m nMonths | -D:nMonths | The duration of the validity period. |
| (See -a) | -m | The MD5 hash algorithm should be used. This is the default. |
| -n name | -n:name | The name for the publisher's certificate. This name must conform to the X.500 standard. The simplest method is to use "CN=MyName" format. For example: -n "CN=Test". |
| -nscp | -N | The Netscape client authentication extension should be included. |
| -r | -r | Creates a self-signed certificate. |
| -sc subjectCertFile | -U:subjectCertFile | The certificate file name with the existing subject public key to be used. |
| -sk subjectKey | -u:subjectKey | The location of the subject's key container which holds the private key. If a key container does not exist, one is created. If neither of the -sk or -sv options are used, the JoeSoft key container is created and used by default. |
| -sky subjectKeySpec | N/A | The subject's key specification, which must be one of three possible values: 1. Signature, which stands for AT_SIGNATURE key specification. 2. Exchange, which stands for AT_KEYEXCHANGE key specification. 3. An integer, such as 3. See notes on key specifications below. |
| -sp subjectProviderName | N/A | CryptoAPI provider for subject. The default is the user's provider. See the Cryptography Reference documentation for details on CryptoAPI providers. |
| -sr subjectCertStoreLocation | N/A | The registry location of the subject's certificate store. Must be either localMachine or currentUser. currentUser is the default. currentUser means that the certificate store is under the registry key HKEY_CURRENT_USER and localMachine means HKEY_LOCAL_MACHINE. |
| -ss subjectCertStoreName | N/A | The name of the subject's certificate store where the generated certificate will be stored. |
| -sv subjectKeyFile | -k:subjectKeyFile | The location of the subject's .pvk file. If neither of the -sk or -sv options are used, the JoeSoft key container is created and used by default. |
| -sy nSubjectProviderType | N/A | CryptoAPI provider type for subject. The default is PROV_RSA_FULL. See the Cryptography Reference documentation for details on CryptoAPI provider types. |
| -# serialNumber | -#:serialNumber | The serial number of the certificate. The maximum value is 2^31. The default is a value generated by the program that is guaranteed to be unique. |
| -$ certificateAuthority | (See -I, -C, -C:f) | The type of Certificate Authority. Must be set to either commercial or individual. Commercial means the certificate will be used by commercial software publishers. Individual means the certificate will be used by individual software publishers. |
| -? | -? | Displays the basic options. |
| -! | N/A | Displays the extended options. |
If the -sky key specification option is used in Internet Explorer 4.0 and later, the specification must match the key specification indicated by the private key file or private key container. If the key specification option is not used, then the key specification indicated by the private key file or private key container will be used. If there is more than one key specification in the key container, MakeCert will first attempt to use the AT_SIGNATURE key specification. If that fails, MakeCert will then try to use AT_KEYEXCHANGE. Since most users have either an AT_SIGNATURE key or AT_KEYEXCHANGE key, this option does not need to be used in most cases.
MakeCert SPC-file and Private-key Technology Options
The following are group 2 options for software publishing certificate-file and private-key technology only:
| Internet Explorer 4.0 and later | Internet Explorer 3.02 UPD | Description |
|---|---|---|
| -ic issuerCertFile | -i: issuerCertFile | The location of the issuer's certificate. |
| -ik issuerKey | -s issuerKeyFile | The location of the issuer's key container. The default is the test root key. |
| -iky IssuerKeySpec | -K: keySpec | For Internet Explorer 3.02: The issuer's key specification. This parameter can be either S for a signature key (this is the default) or E for a key-exchange key. For Internet Explorer 4.0 and later: The issuer's key specification, which must be one of three possible values: 1. Signature, which stands for AT_SIGNATURE key specification. 2. Exchange, which stands for AT_KEYEXCHANGE key specification. 3. An integer, such as 3. See notes on key specifications below. |
| -ip IssuerProviderName | -x: providerName | CryptoAPI provider for issuer. The default is the user's provider. See the Cryptography Reference documentation for details on CryptoAPI providers. |
| -iv issuerKeyFile | -s: issuerKeyFile | The issuer's private-key file. The default is the test root. |
| -iy nIssuerProviderType | -y: nProviderType | CryptoAPI provider type for issuer. The default is PROV_RSA_FULL. See the Cryptography Reference documentation for details on CryptoAPI provider types. |
If the -iky key specification option is used in Internet Explorer 4.0 and later, the specification must match the key specification indicated by the private key file or private key container. If the key specification option is not used, the key specification indicated by the private key file or private key container will be used. If there is more than one key specification in the key container, MakeCert will first attempt to use the AT_SIGNATURE key specification. If that fails, MakeCert will then try to use AT_KEYEXCHANGE. Since most users have either an AT_SIGNATURE key or AT_KEYEXCHANGE key, this option does not need to be used in most cases.
MakeCert Certificate Store Technology Options
The following are group 3 options for certificate store technology only:
| Internet Explorer 4.0 and later | Internet Explorer 3.02 UPD | Description |
|---|---|---|
| -ic issuerCertFile | NA | The file containing the issuer's certificate. For Internet Explorer 4.0 and later, MakeCert will search in the certificate store for a certificate with an exact match. |
| -in issuerNameString | N/A | The common name of the issuer's certificate. MakeCert will search in the certificate store for a certificate whose common name includes issuerNameString. |
| -ir IssuerCertStoreLocation | N/A | The registry location of the issuer's certificate store. Must be either localMachine or currentUser. currentUser is the default. currentUser means that the certificate store is under the registry key HKEY_CURRENT_USER and localMachine means HKEY_LOCAL_MACHINE. |
| -is issuerCertStoreName | N/A | The issuer's certificate store that includes the issuer's certificate and its associated private key information. If there is more than one certificate in the store, the user must uniquely identify it with the -ic or -in option. If the certificate in the certificate store is not uniquely identified, MakeCert will fail. |
MakeCert Internet Explorer 3.02 UPD Example
The following is an example that creates a certificate using the Internet Explorer 3.02 UPD options:
MakeCert -k:c:\KeyStore\MyKey.pvk -n:CN=MySoftwareCompany Cert.cer
In this example, a certificate file called Cert.cer is created. The public part of the key pair called MyKey is bound to the publisher, MySoftwareCompany.
6.4 MakeCert Examples for Internet Explorer 4.0 and later
The following are a series of examples for creating certificates with MakeCert using the options for Internet Explorer 4.0 and later.
Make a certificate issued by the default test root. Save the certificate to a file.
MakeCert myNew.cer
Make a certificate issued by the default test root. Save it to a certificate store.
MakeCert -ss myNewStore
Make a certificate issued by the default test root. Create a .pvk file and output the certificate to both a store and a file.
MakeCert -sv myNew.pvk -ss myNewStore myNew.cer
Make a certificate issued by the default test root. Create a key container and output the certificate to both a store and a file.
MakeCert -sk myNewKey -ss myNewStore myNew.cer
Make a certificate using the default test root. Save the certificate to a store. Then make another certificate using the newly created certificate. Save the second certificate to another store.
MakeCert -sk myNewKey -ss myNewStore
MakeCert -is myNewStore -ss anotherStore
Make a certificate using the default test root. Save the certificate to my store. Then make another certificate using the newly created certificate. Because there is more than one certificate in my store, identify the first certificate using its common name.
MakeCert -sk myNewKey -n "CN=XXZZYY" -ss my
MakeCert -is my -in "XXZZYY" -ss anotherStore
Make a certificate using the default test root. Save the certificate to my store and to a file. Then make another certificate using the newly created myNew certificate. Because there is more than one certificate in my store, uniquely identify the first certificate using the certificate file name.
MakeCert -sk myNewKey -n "CN=XXZZYY" -ss my myNew.cer
MakeCert -is my -ic myNew.cer -ss anotherStore
Create a self-signed certificate named myNewRoot using the default test root. Then use SignCode with the certificate to sign a file.
MakeCert -sk myNewRootKey -r -ss myNewRoot
SignCode -s myNewRoot myControl.exe
Create a self-signed certificate named myNewRoot using the default test root. Save myNewRoot into a system certificate store ca . Then make a certificate from myNewRoot and sign some code with the certificate.
When SignCode uses a certificate in a store for signing, it will also build a certificate chain from the signing certificate to a root. All of the certificates in the certificate chain must be in any of the my, ca, spc, or root certificate stores. In this case, myNewRoot is in the ca certificate store.
MakeCert -sk myNewRootKey -r -ss ca myNewRoot.cer
MakeCert -is ca -ic myNewRoot.cer -ss myNewSign
SignCode -s myNewSign myControl.exe
Cert2SPC
After you have generated a certificate, you can create an software publishing certificate with the Cert2SPC program. This program wraps multiple X.509 certificates into a public key certificate standard (PKCS) #7 signed-data object. Note that this program is for test purposes only. A valid software publishing certificate is obtained from a certificate authority.
The syntax for Cert2SPC is:
Cert2SPC cert1.cer cert2.cer. . .certN.cer output.spc
In the previous syntax example:
- cert1. . .certN are the names of the X.509 certificates to include in the software publishing certificate.
- output is the name of the PKCS #7 object containing the X.509 certificates.
Here is an example:
Cert2SPC MyCert.cer MyCert.spc
This wraps an X.509 certificate, MyCert.cer into a PKCS #7 software publishing certificate called MyCert.spc.
SignCode
The final step is to actually sign a file using the SignCode program. This program will:
- Create a Cryptographic Digest of the file.
- Sign the digest with your private key.
- Copy the X.509 certificates from the software publishing certificate into a new PKCS #7 signed-data object. The PKCS #7 object contains the serial numbers and issuers of the certificates used to create the signature, the certificates, and the signed digest information.
- Embed the object into the file.
- Optionally, it can add a time stamp to the file. A time stamp should always be added when signing a file. However, SignCode also has the ability to add a time stamp to a previously signed file subject to some restrictions (see the examples that follow the options table).
The syntax for signing is:
SignCode [options] [fileName]
In the example, fileName is the name of the output file (Internet Explorer 4.0 and later) and options are as described below.
The options for SignCode are divided into three groups:
- Basic options applicable in all cases.
- Options specific to software publishing certificate-file and private-key technology.
- Options specific to certificate store technology.
Options in groups 2 and 3 cannot be mixed in the same operation.
SignCode Basic Options
The following basic options (group 1) may be applied in all cases:
Options are sorted alphabetically in the left (Internet Explorer 4.0 and later) column, and the corresponding Internet Explorer 3.02 options are given in the middle column. Internet Explorer 3.02 options that have no direct equivalent for Internet Explorer 4.0 and later will say either "N/A" or "(See -option)" in the column for Internet Explorer 4.0 and later, and are sorted alphabetically into the order the options for Internet Explorer 4.0 and later. For example, the Internet Explorer 3.02-individual option follows the -i option for Internet Explorer 4.0 and later.
| Internet Explorer 4.0 and later | Internet Explorer 3.02 UPD | Description |
|---|---|---|
| -a algorithm | -sha, -md5 | The hashing algorithm to use. Must be set to either SHA1 or MD5. The default is MD5. |
| (See -$) | -commercial | The code being signed was created by a commercial software publisher. The action SignCode will take depends upon both this setting and the software publishing certificate actually used. See the table following these options for possible actions. |
| -i opusInfo | -info opusInfo | A location, such as a URL, for obtaining information about your program. |
| (See -$) | -individual | The code being signed was created by an individual software publisher. The action SignCode will take depends upon both this setting and the software publishing certificate actually used. See the table following these options for possible actions. |
| -j dllName | N/A | The name of a DLL that returns an array of authenticated attributes for signing files. The user can specify more than one DLL by repeating the -j option. For example: -j dll1 -j dll2 -j dll3 |
| -jp dllParam | N/A | A parameter to be passed for the preceding DLL. For example: -j DLL1 -jp DLL1Param. Only one parameter is allowed per DLL. For a list of predefined DLLs and their parameters, see -j and -jp SignCode Options. |
| (See -a) | -md5 | Specifies that the MD5 hashing algorithm should be used. This is the default hashing algorithm. |
| -n opusName | -name opusName | The friendly name of your program. |
| N/A | -nocerts | Specifies that no X.509 certificates should be embedded in the PKCS #7 signed-data object. In this case, the relevant certificates must already be stored on the client computer. In Internet Explorer 4.0 and later, all certificates will always be included in the message. |
| N/A | -prog filename | The output file name in Internet Explorer 3.02 UPD. In Internet Explorer 4.0 and later, the file name is always placed as the last item on the command line. |
| (See -a) | -sha | Specifies that the SHA1 hashing algorithm should be used. |
| -t httpAddress | timestamper | Indicates that the file is to be time stamped. A URL specifying an address of a time stamping server must be provided (see -x for time stamping previously signed files). |
| -tr times | N/A | The maximum number of time stamping trials. The default is 1. SignCode will repeat the time stamping operation until it is successful or the limit on number of trials is reached. |
| -tw seconds | N/A | The number of seconds between each time stamping trial. The default is 0. |
| -x | -nosigning | Used when just time stamping a previously signed file. No signing is performed. Must be used in conjunction with -t. |
| -$ signingAuthority | -commercial, -individual | The type of publisher that created the code being signed. Must be either commercial or individual. The action SignCode will take depends upon both this setting and the signing certificate actually used. See the table following these options for possible actions. |
| -? | -? | Displays all of the options. |
The signature type (commercial or individual) used by SignCode depends on the signing option and certificate used. In some cases SignCode will fail the requested operation if there is a conflict. The possible signing actions are as follows:
| Certificate Type | -$ commercial | -$ individual | no option |
|---|---|---|---|
| Commercial Only | commercial | fail | commercial |
| Individual Only | fail | individual | individual |
| Both | commercial | individual | commercial |
| None | fail | individual | individual |
SignCode SPC-file and Private-key Technology Options
The following options are specific to software publishing certificate-file and private-key technology (group 2) only:
When upgrading from Internet Explorer 3.02 UPD to Internet Explorer 4.0 or later, the -pvk option should be mapped to either the -k option or to the -v option, depending on the storage location of the private key. If the private key is stored in a key container, use the -k option. If the private key is stored in a private key file, use the -v option.
| Internet Explorer 4.0 and later | Internet Explorer 3.02 UPD | Description |
|---|---|---|
| -k privateKey | -pvk privateKey | The key container that holds the private key. Cannot be used with -v. |
| -ky keySpec | N/A | Indicates the key specification, which must be one of three possible values: 1. Signature, which stands for AT_SIGNATURE key specification. 2. Exchange, which stands for AT_KEYEXCHANGE key specification. 3. An integer, such as 3. See notes on key specifications below. |
| -p providerName | -provider providerName | The CryptoAPI provider to use. The default is the user's default provider. (For more details, see the Cryptography Reference documentation.) |
| -spc credentials | -spc credentials | The file that contains the credentials. This is usually an .spc file. |
| -v privateKeyFile | -pvk privateKeyFile | The file containing the private key of the publisher (subject). This is usually a .pvk file. The -v option for Internet Explorer 4.0 or later cannot be used with -k. |
| -y providerType | -providerType providerType | The CryptoAPI provider type to use. The default is PROV_RSA_FULL. (For more details, see the Cryptography Reference documentation.) |
If the -ky key specification option is used in Internet Explorer 4.0 and later, the specification must match the key specification indicated by the private key file or private key container. If the key specification option is not used, then the key specification indicated by the private key file or private key container will be used. If there is more than one key specification in the key container, SignCode will first attempt to use the AT_SIGNATURE key specification. If that fails, SignCode will then try to use AT_KEYEXCHANGE. Because most users have either an AT_SIGNATURE key or AT_KEYEXCHANGE key, this option does not need to be used in most cases.
SignCode Certificate Technology Options
The following options are specific to certificate technology (group 3) only:
| Internet Explorer 4.0 and later | Internet Explorer 3.02 UPD | Description |
|---|---|---|
| -c certificateFile | N/A | The file containing the encoded signing certificate. SignCode will search the certificate store for a matching certificate. Either -c or -cn can be used to identify the signing certificate in the certificate store to use. |
| -cn commonNameString | N/A | The common name of the encoded signing certificate. SignCode will search in the certificate store for a certificate whose common name includes commonNameString. If the common name of more than one certificate in the certificate store includes commonNameString, SignCode will fail and issue an error. |
| -r storeLocation | N/A | The registry location of the certificate store. Must be set to either currentUser or localMachine. The default is currentUser. CurrentUser means the certificate store is under the HKEY_CURRENT_USER registry key and localMachine means it is under HKEY_LOCAL_MACHINE. |
| -s storeName | N/A | The certificate store that includes the signing certificate and associated private key. The default is my. If there is more than one certificate in the store, the desired certificate must be uniquely identified using the -c or -cn options, or SignCode will fail. |
| -sp storePolicy | N/A | The certificate store policy. Must be set to either chain or spcStore. The default is spcStore. chain means to add to the signature all of the certificates in the chain located in the following certificate stores: spc, my, ca, and root. spcStore means to add to the signature all of the certificates in the chain located in the following certificate stores: spc, my, ca, and root. Stop when the certificate is located in the spc store. This is the default. The spc store is under the HKEY_LOCAL_MACHINE registry key. The my, ca, and root stores are all under the HKEY_CURRENT_USER registry key. |
Once the file has been signed (assuming you have a valid certificate) and time stamped, the file can be distributed to your customers. Note that certificates generated with the test programs MakeCert and Cert2SPC are NOT valid for signing code that will be distributed to the public. Independent software vendors must obtain a certificate from GTE, VeriSign Inc., or another certification authority for signing code that will be distributed to the public.
SignCode Examples for Internet Explorer 3.02 UPD
Here are two examples of how to sign and time stamp a file using the Internet Explorer 3.02 UPD options. The first uses a private-key name MyKey and the second uses a private-key file My.pvk:
SignCode -prog MyControl.exe -spc Cert.spc -pvk MyKey -timeStamper http://timestamp.verisign.com/scripts/timstamp.dll
SignCode -prog MyControl.exe -spc Cert.spc -pvk My.pvk -timeStamper http://timestamp.verisign.com/scripts/timstamp.dll
Note In the URL above, timstamp.dll is correct. This is not a typographical error.
In both cases a PKCS #7 object, Cert.spc, is embedded into the digest of the file, MyControl.exe. In the first example, the digest is signed with the private key of the MyKey key pair, and a time stamp is added. In the second example, the digest is signed with the private-key file My.pvk, and a time stamp is added.
SignCode Examples for Internet Explorer 4.0 and later
Here are two examples of how to sign and time stamp a file using the options for Internet Explorer 4.0 and later. The first uses the MyKey key container and the second uses a private-key file My.pvk:
SignCode -spc Cert.spc -k MyKey -n "My control" -i http://www.my.com -$ commercial -t http://timestamp.verisign.com/scripts/timstamp.dll MyControl.exe
SignCode -spc Cert.spc -v My.pvk -n "My control" -i http://www.my.com -$ commercial -t http://timestamp.verisign.com/scripts/timstamp.dll MyControl.exe
In both cases a PKCS #7 object, Cert.spc, is embedded into the digest of the file, MyControl.exe. In the first example, the digest is signed with the private key of the MyKey key container, and a time stamp is added. In the second example, the digest is signed with the private-key file My.pvk, and a time stamp is added.
The following example shows how to sign and time stamp a file using a certificate in my store (the default certificate store). The certificate's common name is MyCert, and the program being signed has the friendly name My Control.
SignCode -cn "myCert" -n "My control" -i http://www.my.com -$ commercial -t http://timestamp.verisign.com/scripts/timstamp.dll MyControl.exe
The following example shows how to sign and time stamp a file using a certificate in theCert store. There is assumed to be only one certificate in the certificate store, so it is not necessary to identify the certificate. The certificate store is at the default registry location, HKEY_CURRENT_USER. My control is the friendly name for the program being signed.
SignCode -s "theCert" -n "My control" -i http://www.my.com -$ commercial -t http://timestamp.verisign.com/scripts/timstamp.dll MyControl.exe
Adding a Time Stamp to a Previously Signed File
A time stamp should always be added when a file is signed. However, if a file was signed without a time stamp, a time stamp can be added to that file. Here is an example of how to add a time stamp to a previously signed file:
For Internet Explorer 3.02 UPD:
SignCode -prog MyControl.exe -nosigning -timeStamper http://timestamp.verisign.com/scripts/timstamp.dll
For Internet Explorer 4.0 and later:
SignCode -t http://timestamp.verisign.com/scripts/timstamp.dll -x MyControl.exe
Notice the -x option is used in conjunction with the -t option to indicate that the file to be time stamped has already been signed. If you try to time stamp a file previously signed by Microsoft Internet Explorer 3.0 tools, the time stamp may fail with an error saying you must re-sign. If you time stamp a previously signed file using the SignCode tool for Internet Explorer 3.02 UPD or 4.0 and later, it should successfully add the time stamp. The signing and time stamping concurrent operation should always work, even if the file was previously signed by Internet Explorer 3.0 tools, because if there is an old signature it is replaced.
-j and -jp SignCode Options
The -j and -jp options are provided for more advanced users of SignCode and Internet Explorer 4.0 or later. The user can write a dynamic-link library (DLL) with predefined entry points that returns an array of authenticated or unauthenticated attributes for signing files. SignCode will take the following actions using these options:
- Load the DLL specified by the -j option.
- Pass the parameters specified by -jp option to the DLL.
- Retrieve an array of authenticated or unauthenticated attributes for signing Java files from the DLL.
- Add the attributes to the signature.
There are four predefined entry points for the DLL:
HRESULT WINAPI InitAttr(LPWSTR pInitString); // IN: the initialization string
HRESULT WINAPI GetAttr(PCRYPT_ATTRIBUTES *ppsAuthenticated, // OUT: Authenticated attributes added to signature
PCRYPT_ATTRIBUTES *ppsUnauthenticated); // OUT: Unauthenticated attributes added to signature
HRESULT WINAPI ReleaseAttr(PCRYPT_ATTRIBUTES psAuthenticated, // OUT: Authenticated attributes to be released
PCRYPT_ATTRIBUTES psUnauthenticated); // OUT: Unauthenticated attributes to be released
HRESULT WINAPI ExitAttr();
SignCode calls these entry points in the following order:
- InitAttr(initString); // (parameter specified by the -jp option)
- GetAttr();
- ExitAttr();
- InitAttr(initString); // (parameter specified by the -jp option)
- ReleaseAttr();
- ExitAttr();
ChkTrust
The ChkTrust program checks the validity of a signed file by:
- Extracting the PKCS #7 signed-data object.
- Extracting the X.509 certificates from the PKCS #7 signed-data object.
- Computing a new hash of the file and comparing it with the signed hash in the PKCS #7 object.
If the hashes agree, ChkTrust then verifies that the signer's X.509 certificate is traceable back to the root certificate and that the correct root key was used.
If all these steps are successful, it means that the file has not been tampered with, and that the vendor who signed the file was authenticated by the root authority.
Here is the syntax:
ChkTrust [options] signedFile
The options are:
| Internet Explorer 4.0 and later | Internet Explorer 3.02 UPD | Description |
|---|---|---|
| N/A | -c | Indicates that the signed file is a cabinet file. |
| N/A | -i | Indicates that the signed file is a portable executable image file. Includes .exe, .dll, and .ocx files. |
| -q | -n | Do not display user interface. |
| -? | N/A | Displays all of the options. |
In Internet Explorer 4.0 and later, ChkTrust can distinguish file types automatically, so the -c and -i switches used in the Internet Explorer 3.02 UPD version are obsolete. Here is an example for the Internet Explorer 3.02 UPD version:
ChkTrust -i MyProgram.exe
A successful response would be:
Result: 0
Here is an example for Internet Explorer 4.0 and later:
ChkTrust MyProgram.exe
Note that versions of ChkTrust that are older than the one released with Internet Explorer 3.02 UPD cannot validate files signed with this release of Authenticode.
MakeCTL
The MakeCTL utility creates a certificate trust list (CTL) and outputs the encoded CTL to a file. MakeCTL is supported in Internet Explorer 4.0 and later.
The input to MakeCTL is an array of certificate stores. MakeCTL will build a CTL which includes the SHA1 hash of all of the certificates in the certificate stores. A certificate store can be one of the following:
- A serialized store file
- A PKCS #7
- An encoded certificate file
- A system store
The syntax for invoking MakeCTL is:
MakeCTL [-u subjectUsageID] [-s [-r registryLocation]] store1 [-s [-r registryLocation]] store2 ... [-s [-r registryLocation]] storeN *output.*ctl
In the example:
- store1 store2 ... storeN are the names of the certificate stores to make the certificate trust list for.
- *output.*ctl is the name of the output file containing the certificate trust list.
The options are as follows:
| -u subjectUsageID | The CTL subject usage identifier. The default identifier is szOID_TRUSTED_CODESIGNING_CA_LIST, which specifies that the CTL consists of root certification authoritys for code signing. |
| -s | Indicates that the certificate store is a system store. |
| -r registryLocation | The registry location of the system certificate store. Meaningful only when -s is set. Must be set to either currentUser or localMachine. The default setting is currentUser. currentUser means that the certificate store is under the registry key HKEY_CURRENT_USER. localMachine means that the certificate store is under the registry key HKEY_LOCAL_MACHINE. |
| -? | Lists command syntax and options. |
An encoded CTL file must be signed before using. CTL files can be signed using the SignCode utility. Once the CTL file is signed, it can be moved to the trust system store by CertMgr. CertMgr can also move the CTL's signer certificate to the root store. If the subject usage identifier of the CTL is szOID_TRUSTED_CODESIGNING_CA_LIST (the default), all the files signed by certificates in the CTL will be trusted by ChkTrust and Authenticode.
The following example generates a CTL that includes all the certificates in a system certificate store named root:
MakeCTL -s root output.ctl
The following example generates a CTL that includes an array of certificates:
MakeCTL one.cer two.cer three.cer output.ctl
CertMgr
The CertMgr utility is a replacement for DumpCert and adds many new capabilities. CertMgr can manage certificates, certificate trust lists (CTLs), and certificate revocation lists (CRLs). The functionality of CertMgr has three parts:
- Display certificates, CTLs, and CRLs.
- Add certificates, CTLs, and CRLs from one certificate store to another.
- Delete certificates, CTLs, and CRLs from a certificate store.
Each functional part of CertMgr has its own syntax and options group. The syntax and options for different functional parts cannot be mixed.
CertMgr works with two kinds of certificate stores, StoreFile and system store. A StoreFile can be one of the following kinds of files:
- Encoded CTL/CRL/certificate file (could be base64 encoded)
- PKCS #7 file
- Signed document
- Serialized StoreFile
It is not necessary to specify the type of the StoreFile. CertMgr can determine the StoreFile type and take the appropriate actions.
A system store is located in the user's registry. The user can refer to a system store by providing just its name. It is not necessary to specify the certificate store provider type. Depending on the type of the StoreFile or system store, CertMgr will choose the corresponding store provider type.
Displaying Certificates, CTLs, and CRLs with CertMgr
The syntax for invoking CertMgr to display certificates, CTLs, and CRLs is as follows:
CertMgr [options] [-s [-r registryLocation]] StoreName
StoreName is the name of the certificate store containing the items to display. The store can be a serialized store (StoreFile) or a system store (in the registry). By default, CertMgr will display all the certificates, CTLs, or CRLs in the store, unless otherwise specified in the options.
The options are:
| -v | Verbose mode. Displays detailed information about certificates, CTLs, and CRLs. The default is to display brief information. |
| -c | Only display certificates. |
| -CTL | Only display CTLs. |
| -CRL | Only display CRLs. |
| -e encodingType | Certificate encoding type. |
| -y storeProviderType | Store provider type. |
| -f dwFlags | Store open flag. This is the dwFlags parameter passed to CertOpenStore. The default value is CERT_SYSTEM_STORE_CURRENT_USER. Meaningful only if -y is set. For more information see the Cryptography Reference documentation. |
| -s | Indicates the store is a system store. If this option is not set, the store is a StoreFile. |
| -r registryLocation | Identifies the registry location of the system certificate store. Meaningful only when -s is set. Must be set to either currentUser or localMachine. CurrentUser is the default. currentUser means that the certificate store is under the registry key HKEY_CURRENT_USER, localMachine means HKEY_LOCAL_MACHINE. |
| - ? | Displays all the options. |
Adding Certificates, CTLs, and CRLs with CertMgr
The syntax for invoking CertMgr to add certificates, CTLs, and CRLs is as follows:
CertMgr -add [options] [-s [-r registryLocation]] SourceStore [-s [-r registryLocation]] DestinationStore
SourceStore is the source certificate store that contains the existing certificates, CTLs, and CRLs. DestinationStore is the destination certificate store to which the certificates, CTLs, and CRLs will be added. The destination store will be saved as a serialized store, unless the -7 option is used, which saves the store as a PKCS #7. Note that the -7 option cannot be used when the destination store is a system store.
CertMgr can add either certificates, CTLs, or CRLs. If there is more than one item in one of these categories, the user has three options:
- Use the -all option to add all the items in the category.
- Use the -n and -sha1 options to uniquely identify the item.
- Do not specify any options, and CertMgr will prompt the user with a list of items to add. The user responds by entering the index of the item to add.
This functionality of CertMgr can be used to copy and move certificates, CTLs, and CRLs. See the examples following the options.
The options are:
| -c | Add certificates. |
| -CTL | Add CTLs. |
| -CRL | Add CRLs. |
| -all | Add all entries. |
| -7 | Save the destination store as a PKCS #7. |
| -e encodingType | Certificate encoding type. |
| -y storeProviderType | Store provider type. |
| -f dwFlags | Store open flag. This is the dwFlags parameter passed to CertOpenStore. The default value is CERT_SYSTEM_STORE_CURRENT_USER. This is meaningful only if -y is set. For more information see the Cryptography Reference documentation. |
| -n commonNameString | The common name of the certificate to add. This can be used only with certificates. |
| -s | Indicates the store is a system store. If this option is not set, the store is a StoreFile. |
| -sha1 sha1Hash | The SHA1 hash of the certificate, CTL, or CRL to add. |
| -r registryLocation | Identifies the registry location of the system certificate store. This is meaningful only when -s is set. Must be set to either currentUser or localMachine. CurrentUser is the default. currentUser means that the certificate store is under the registry key HKEY_CURRENT_USER. localMachine means HKEY_LOCAL_MACHINE. |
| - ? | Displays all the options. |
Deleting Certificates, CTLs, and CRLs with CertMgr
The syntax for invoking CertMgr to delete certificates, CTLs, and CRLs is as follows:
CertMgr -del [options] [-s [-r registryLocation]] SourceStore [-s [-r registryLocation] DestinationStore]
SourceStore is the source certificate store that contains the existing certificates, CTLs, and CRLs. DestinationStore is the destination certificate store which will contain copies of the remaining certificates, CTLs, and CRLs after the specified items have been deleted. If DestinationStore is not specified, SourceStore will also serve as the destination store (it will be modified.) The destination store will be saved as a serialized store, unless -7 option is used, which saves the store as a PKCS #7. Note that the -7 option cannot be used when the destination store is a system store.
CertMgr can delete either certificates, CTLs, or CRLs. If there is more than one item in one of these categories, the user has three options:
- Use the -all option to delete all the items in the category.
- Use the -n and -sha1 options to uniquely identify the item.
- Do not specify any options, and CertMgr will prompt the user with a list of items to delete. The user responds by entering the index of the item to delete.
The options are:
| -c | Delete certificates. |
| -CTL | Delete CTLs. |
| -CRL | Delete CRLs. |
| -all | Delete all entries. |
| -7 | Save the destination store as a PKCS #7. |
| -n commonNameString | The common name of the certificate to delete. This can be used only with certificates. |
| -sha1 sha1Hash | The SHA1 hash of the certificate, CTL, or CRL to delete. |
| -e encodingType | Certificate encoding type. |
| -y storeProviderType | Store provider type. |
| -f dwFlags | Store open flag. This is the dwFlags parameter passed to CertOpenStore. The default value is CERT_SYSTEM_STORE_CURRENT_USER. This is meaningful only if -y is set. For more information see the Cryptography Reference documentation. |
| -s | Indicates the store is a system store. If this option is not set, the store is a StoreFile. |
| -r registryLocation | Identifies the registry location of the system certificate store. This is meaningful only when -s is set. Must be set to either currentUser or localMachine. CurrentUser is the default. currentUser means that the certificate store is under the registry key HKEY_CURRENT_USER, localMachine means HKEY_LOCAL_MACHINE. |
| -? | Displays all the options. |
CertMgr Examples
View certificates, CRLs, and CTLs from a file called myFile.ext. myFile can be one of the following files: an encoded CTL, CRL, or certificate file (could be base64 encoded), a PKCS #7 file, an software publishing certificate file, a signed document, or a serialized storeFile.
CertMgr myFile.ext
View a system store called my store:
CertMgr -s my
Add all the certificates in a file called myFile.ext to a new file, called newFile.ext:
CertMgr -add -all -c myFile.ext newFile.ext
Copy all the certificates in a system store to a file called newMy.ext:
CertMgr -add -all -c -s my newMy.ext
Move a certificate with common name myCert in my system store to a file called newCert.cer:
CertMgr -add -c -n myCert -s my newCert.cer
Delete all the certificates in my system store:
CertMgr -del -all -c -s my
Delete all the CTLs in my system store and save the resulting store to a file called newStore.str:
CertMgr -del -all -ctl -s my newStore.str
The following example demonstrates how to build a CTL and move it to the root store:
// 1. Make a self-signed certificate called sign.cer.
MakeCert -sv sign.pvk -r -n "CN=THIS IS A TEST OF MAKECTL" sign.cer
// Make an SPC file using Cert2SPC.
Cert2SPC sign.cer sign.spc
// 2. Make another self-signed certificate called test.cer.
MakeCert -sv test.pvk -r -n "CN=THIS IS MY TEST CERT" test.cer
// Make an SPC file using Cert2SPC.
Cert2SPC test.cer test.spc
// 3. Make a test.ctl from test.cer.
MakeCTL test.cer test.ctl
// 4. Sign test.ctl with the sign.pvk and sign.spc made in step 1.
SignCode -v sign.pvk -spc sign.spc test.ctl
// 5. Move test.ctl to the trust system store.
CertMgr -add -ctl test.ctl -s trust
// 6. Move sign.cer to the root system store.
CertMgr -add -c sign.cer -s root
// 7. Sign something (test.exe) with test.pvk, and test.spc.
SignCode -v test.pvk -spc test.spc test.exe
// 8. Since test.cer is in the test.ctl, ChkTrust will succeed.
ChkTrust test.exe
SetReg
The SetReg utility is used to set the value of the registry keys controlling the behavior of the Authenticode certificate verification process. These keys are called the Software Publishing State Keys. When SetReg has completed the requested action, the current state of the Software Publishing State Keys is displayed.
The syntax for invoking SetReg is:
SetReg [options] [Choice #<True | False>]
The options can be one of the following values:
| Internet Explorer 4.0 and later | Internet Explorer 3.02 UPD | Description |
|---|---|---|
| -q | -q | Suppresses the display of the Software Publishing State Key values after SetReg has completed the requested action. The values are displayed by default. |
| -? | -h | Lists command syntax and options. |
Choice # must be one of the following values (valid for both Internet Explorer 3.02 and Internet Explorer 4.0 and later, except 9 and 10, which are for Internet Explorer 4.0 and later only):
| 1 | Trust the Test Root. Causes the test root to be a trusted root if set to TRUE. This is equivalent to running "regedit wvtston.reg" in Windows Internet Explorer 3.x. The default is FALSE. Any code signed with a test root will not verify unless this flag is turned TRUE. |
| 2 | Use expiration date on certificates. Causes the certificate expiration date to be checked if set to TRUE. To ignore expiration dates, set this flag to FALSE. The default is TRUE. |
| 3 | Check the revocation list. Causes the revocation check to be performed if set to TRUE. To bypass revocation check, set this flag to FALSE. The default is FALSE in Internet Explorer 3.x and TRUE in Internet Explorer 4.x. |
| 4 | Offline revocation server OK (Individual). Allows off-line approval for individual certificates if set to TRUE. The default is FALSE. |
| 5 | Offline revocation server OK (Commercial). Allows off-line approval for commercial certificates if set to TRUE. The default is FALSE. |
| 6 | Java offline revocation server OK (Individual). Allows off-line approval for individual certificates and does not display the user interface for bad certificates if set to TRUE. The default is FALSE. |
| 7 | Java offline revocation server OK (Commercial). Allows off-line approval for commercial certificates and does not display the user interface for bad certificates if set to TRUE. The default is FALSE. |
| 8 | Invalidate version 1 signed objects. Invalidates version 1 signed objects if set to TRUE. The default is FALSE. |
| 9 | Perform the revocation check on the time stamp server's certificate if set to TRUE. The default is FALSE. For Internet Explorer 4.0 and later only. |
| 10 | Only allow downloads from publishers that are contained in the Personal Trust Database if set to TRUE. The default is FALSE. For Internet Explorer 4.0 and later only. |
Here is an example:
SetReg 1 TRUE
This turns on the capability to trust the test root.