Authenticode

Authenticode consists of programs to digitally sign files and programs to check that the files were, indeed, successfully signed.

The programs are:

• MakeCert, which creates a test X.509 certificate.
• Cert2SPC, which creates a test SPC.
• SignCode, which uses the SPC to sign a file.
• PeSigMgr, which checks to see that the file was signed.
• ChkTrust, which checks the validity of the file.

These programs are discussed in more detail below.

Note that before using the test X.509 certificate, you will want to add some keys to your registry. Type

regedit wvtston.reg

(located in the directory that you installed the signing tools) before attempting to use the test certificate.

MakeCert

Use the MakeCert program to generate a test X.509 certificate. The program does the following:

1. It creates a public/private key pair for digital signatures and associates it with a name that you choose.
2. It associates the key pair with a publisher's name that you choose.
3. It creates an X.509 certificate, signed by the root key or one you specifiy, that binds your name to the public part of the key pair. If you do not specify a root key, MakeCert generates one for you.

The syntax for invoking MakeCert is:

MAKECERT [options] outputfile

where the options are:

• -u:subjectKey which is the location of the publisher's key pair name. If a key pair does not exist, one is created.
• -k:subjectKeyFile which is the location of the publisher's .pvk file.
• -n:name which is the name for the publisher's certificate. This name must conform to the X.500 standard. The easiest way to do this is to use the form "CN=MyName."
• -d:displayname which is the display name of the publisher in the SPC UI.
• -s:issuerKeyFile which is the location of the issuer's key. The default is the root key.
• -i:issuerCertFile which is the location of the issuer's certificate.
• -b:logoFile which is the file name of the SPC agency logo (for example, a .bmp file).
• -l:policyLink which is a link to SPC agency policy information (for example, a URL).
• -U:subjectCertFile is the certificate file name with the existing subject public key to be used.
• -#:serialNumber which is 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.
• -I which means the certificate will be used by individual software publishers.
• -C which means the certificate will be used by commercial software publishers.
• -C:f which means the certificate will be used by commercial software publishers who have met the minimum financial criteria.
• -S:session which is the session name for an enrollment session.
• -P:purpose which is the purpose for which the certificate is being generated. This parameter can either be CodeSigning (this is the default) or ClientAuth.
• -x:providerName which is the CryptoAPI provider to use. (See the CryptoAPI documentation for more details.)
• -y:nProviderType which is the CryptoAPI provider type to use. (See the CryptoAPI documentation for more details.)
• -K:keyspec which is the key specification. This parameter can either be S for a signature key (this is the default) or E for a key-exchange key.
• -B:dateStart which is the date when the certificate first becomes valid. The default is when the certificate is created.
• -D:nMonths which is the duration of the validity period.
• -E:dateEnd which is the date when the validity period ends. The default is the year 2039.
• -h:numChildren which is the maximum height of the tree below this certificate.
• -t:types which is the certificate type. This parameter can be E for end-entity, C for certificate authority, or both.
• -g which creates a glue certificate.
• -r which creates a self-signed certificate.
• -m which means to use the MD5 hash algorithm. This is the default.
• -a which means to use the SHA1 hash algorithm.
• -? which displays all the options.

Here is an example:

>MakeCert -u:MyKey -n:CN=MySoftwareCompany Cert.cer

This generates a certificate file called Cert.cer. The public part of the key pair called KeyName is bound to the publisher, MySoftwareCompany.

This utility program should not be used once the software publisher obtains a valid X.509 software publisher certificate from the appropriate CA.

Cert2SPC

After you have generated a certificate, you must create an SPC with the Cert2SPC program. This program wraps the X.509 certificate and the root certificate into a PKCS#7 signed-data object. PKCS#7 objects are commonly used to carry certificates because it is possible to put several of them into a single object. Again, 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:

• cert1. . .certN are the names of the X.509 certificates.
• output is the name of the SPC. This is a PKCS#7object containing the X.509 certificate and the root certificate.

Here is an example:

>Cert2Spc root.cer cert.cer cert.spc

This combines Cert.cer and Root.cer to make an SPC called Cert.spc.

SignCode

The final step is to use the SPC to actually sign a file. This is done with the SignCode program. This program will:

1. Create a cryptographic digest of the file.
2. Sign the digest with your private key.
3. Extract the X.509 certificates from the SPC.
4. Create a new PKCS#7 signed-data object that contains the serial numbers of the certificates and the signed digest information.
5. Embed the object into the file.

If you have a valid SPC, then you can use this program to actually sign your code. The SignCode program has a wizard to help you do this. To sign code using the wizard, simply type "SignCode" without any options. If you want to sign your code manually, the syntax is:

SignCode [-prog filename -spc credentials -pvk privateKeyFile ] [options]

where:

• -prog filename is the name of the file to sign.
• -spc credentials is the file that contains the credentials. This is usually an .spc file.
• -pvk privateKeyFile is the file containing the private key of the publisher. This is usually a .pvk file.

and where the options are:

• -name opusName which is a name for your program.
• -info opusInfo which is a location, such as an URL, for obtaining information about your program.
• -gui which invokes the wizard.
• -nocerts which means you do not want any X.509 certificates embedded in the PKCS#7 signed-data object. In this case, the relevant certificates must already be stored on the client computer.
• -provider providerName which is the CryptoAPI provider to use. (See the CryptoAPI documentation for more details.)
• -providerType providerType which is the CryptoAPI provider type to use. (See the CryptoAPI documentation for more details.)
• -commerical which means the code being signed was created by a commercial software publisher.
• -individual which means the code being signed was created by an individual software publisher.
• -sha which means you want to use the SHA hashing algorithm.
• -md5 which means you want to use the MD5 hashing algorithm. This is the default hashing algorithm.
• -? Which displays all the options.

Here is an example of how to sign a file:

>SignCode -prog MyProgram.exe -spc Cert.spc -pvk MyKey

This embeds a PKCS#7 object, Cert.spc, into the digest of file, MyProgram. The digest is signed with the private key of the MyKey key pair.

Once this is done (assuming you have a valid certificate), the file can be distributed to your customers.

PeSigMgr

The PeSigMgr program checks to see if SignCode was successful. This means the file should have a PKCS#7 object embedded in it. Here is the syntax:

PESIGMGR [options] signedfile

where the optionsare:

• -l which lists the certificates in an image.
• -a:<-filename -> which adds a certificate file to an image.
• -r:<-index -> which removes certificate <-index -> from an image.
• -s:<-filename -> which is used with -r to save the removed certificate.
• -t:<-CertType -> which is used with -a to specify the type of certificate, where CertType may be X509 or PKCS7. (The default is PKCS7.)
• -? which displays all the options.

and where signedfile is the name of the signed file you want to check.

Here is an example:

>PeSigMgr -l MyProgram.exe

A sample response is:

>Certificate 0 Revision 256 Type PKCS#7

This means a certificate was embedded in the file.

ChkTrust

The ChkTrust program checks the validity of the file by:

1. Extracting the PKCS#7 signed-data object.
2. Extracting the X.509 certificates from the PKCS#7 signed-data object.
3. 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 points back to the root certificate and that the correct root key was used.

If all these steps are successful, the file has not been tampered with, and the vendor was authorized to publish the file by the root authority.

Here is the syntax:

CHKTRUST [type] signedfile

where type is one of the following:

• -c which is a cabinet file.
• -i which is a PE image file.
• -j which is a Java class file.

Here is an example:

ChkTrust MyProgram.exe

A successful response is:

Result: 0