
This section demonstrates how to sign code by creating digital signatures and associating them with files using Authenticode, which is provided with the Internet Client SDK. Creating a fully verifiable certificate might assume the existence of a complex hierarchy of CAs. A root certificate and a root private key are provided for testing purposes only. Independent software vendors must obtain a certificate from GTE, VeriSign, Inc., or another CA for signing code that will be distributed to the public.
Authenticode consists of programs to digitally sign files and programs to check that the files were, indeed, successfully signed. The programs are:
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.
Use the MakeCert test program to generate a test X.509 certificate. MakeCert performs the following tasks:
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 ones to create a certificate. Extended options provide more flexibility. The options for MakeCert are also divided into three functional groups:
Options in Groups 2 and 3 cannot be mixed, with the exception of the ic option.
The following Group 1 options may be applied in all cases.
Options are sorted alphabetically in the left (IE 4.0) column, and the corresponding IE 3.02 options are given in the middle column. IE 3.02 options that have no direct IE 4.0 equivalent will say either "N/A" or "(See -option)" in the IE 4.0 column, and are sorted alphabetically into the order of IE 4.0 options. For example, the IE 3.02 -C option follows the IE 4.0 -b option.
| For IE 4.0 | For IE 3.02 UPD | Description |
| -a algorithm | -a | For IE3.02: Indicates the SHA1 hash algorithm should be used. MD5 is the default For IE4.0: 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 IE3.02: The certificate type. This parameter can be E for end-entity, C for certificate authority, or both. For IE4.0: 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 CryptoAPI 2.0 for definitions of allowable OIDs. |
| N/A | -g | Creates a glue certificate (IE 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 SPC 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. |
| -scsubjectCertFile -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 CryptoAPI 2.0 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 CryptoAPI 2.0 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 IE 4.0, 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.
The following are Group 2 options for SPC-file and private-key technology only:
| For IE 4.0 | For IE 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 IE3.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 IE4.0: 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 CryptoAPI 2.0 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 CryptoAPI 2.0 documentation for details on CryptoAPI provider types. |
If the -iky key specification option is used in IE 4.0, 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.
The following are Group 3 options for certificate store technology only:
| For IE 4.0 | For IE 3.02 UPD | Description |
| -ic issuerCertFile | NA | The file containing the issuer's certificate. For IE 4.0 only, 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. |
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.
The following are a series of examples for creating certificates with MakeCert using the Internet Explorer 4.0 options.
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 certficate 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. Since 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. Since there is more than one certificate in my store, uniquely identify the first certificate using the certificate filename.
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
After you have generated a certificate, you can create an SPC (Software Publisher Certificate) with the Cert2SPC program. This program wraps multiple X.509 certificates into a PKCS #7 signed-data object. Note that this program is for test purposes only. A valid SPC is obtained from a CA.
The syntax for Cert2SPC is:
Cert2SPC cert1.cer cert2.cer. . .certN.cer output.spc
where:
Here is an example:
Cert2SPC MyCert.cer MyCert.spc
This wraps an X.509 certificate, MyCert.cer into a PKCS #7 SPC called MyCert.spc.
The final step is to actually sign a file using the SignCode program. This program will:
The syntax for signing is:
SignCode [options] [fileName]
where fileName is the name of the output file (Internet Explorer 4.0 only) and options are as described below.
The options for SignCode are divided into three groups:
Options in groups 2 and 3 cannot be mixed in the same operation.
The following basic options (Group 1) may be applied in all cases:
Options are sorted alphabetically in the left (IE 4.0) column, and the corresponding IE 3.02 options are given in the middle column. IE 3.02 options that have no direct IE 4.0 equivalent will say either "N/A" or "(See -option)" in the IE 4.0 column, and are sorted alphabetically into the order of IE 4.0 options. For example, the IE 3.02 -individual option follows the IE 4.0 -i option.
| For IE 4.0 | For IE 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 SPC actually used. See 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 SPC actually used. See 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 pre-defined 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 given 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 IE 4.0, all certificates will always be included in the message. |
| N/A | -prog filename | The output file name in IE 3.02 UPD. In IE 4.0 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 timestamped. A URL specifying an address of a timestamping server must be provided (see -x for timestamping previously signed files). |
| -tr times | N/A | The maximum number of timestamping trials. The default is 1. SignCode will repeat the timestamping operation until it is successful or the limit on number of trials is reached. |
| -tw seconds | N/A | The number of seconds between each timestamping trial. The default is 0. |
| -x | -nosigning | Used when just timestamping 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 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 |
The following options are specific to SPC-file and private-key technology (group 2) only:
When upgrading from IE3.02 UPD to IE 4.0, 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.
| For IE 4.0 | For IE 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 CryptoAPI 2.0 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 IE 4.0 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 CryptoAPI 2.0 documentation.) |
If the -ky key specification option is used in IE 4.0, 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. Since most users have either an AT_SIGNATURE key or AT_KEYEXCHANGE key, this option does not need to be used in most cases.
The following options are specific to certificate technology (group 3) only:
| For IE 4.0 | For IE 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 timestamped, 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 CA for signing code that will be distributed to the public.
Here are two examples of how to sign and timestamp 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
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 timestamp is added. In the second example, the digest is signed with the private-key file My.pvk, and a timestamp is added.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.