Signing and Checking Code with Authenticode

Signing and Checking Code with Authenticode


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.

MakeCert

Use the MakeCert test program to generate a test X.509 certificate. MakeCert performs the following tasks:

  1. Creates a public/private key pair for digital signatures and associates it with a name that you choose.
  2. Associates the key pair with a publisher's name that you choose.
  3. 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 ones to create a certificate. Extended options provide more flexibility. The options for MakeCert are also divided into three functional groups:

  1. Options applicable to SPC-file, private-key, and certificate store technology.
  2. Options specific to SPC-file and private-key technology only.
  3. 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 (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.

MakeCert SPC-file and Private-key Technology Options

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.

MakeCert Certificate Store Technology Options

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.

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 Internet Explorer 4.0 Examples

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

Cert2SPC

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.

SignCode

The final step is to actually sign a file using the SignCode program. This program will:

  1. Create a cryptographic digest of the file.
  2. Sign the digest with your private key.
  3. Copy the X.509 certificates from the SPC 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.
  4. Embed the object into the file.
  5. Optionally, it can add a timestamp to the file. A timestamp should always be added when signing a file. However, SignCode also has the ability to add a timestamp 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]

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:

  1. Basic options applicable in all cases
  2. Options specific to SPC-file and private-key technology
  3. 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 (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

SignCode SPC-file and Private-key Technology Options

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.

SignCode Certificate Technology Options

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.

SignCode Examples for Internet Explorer 3.02 UPD

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.