Authenticode

Authenticode consists of programs to digitally sign files and programs to check that the files were, indeed, successfully signed. Before you begin, first check that the underlying CryptoAPI is running. To do this, type:

c:>api *

This should generate SUCCESS messages until its stopped.

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.

We will now discuss these programs in more detail.

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 is the location of the publisher's key pair name. If a key pair does not exist, one is created.
• -k:subjectKeyFile is the location of the publisher's .pvk file.
• -n:name 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 is the display name of the publisher in the SPC UI.
• -s:issuerKeyFile is the location of the issuer's key. The default is the root key.
• -i:issuerCertFile is the location of the issuer's certificate.
• -b:logoFile is the file name of the SPC agency logo (for example, a .bmp file).
• -l:policyLink 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 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 means the certificate will be used by individual software publishers.
• -C means the certificate will be used by commercial software publishers.
• -C:f means the certificate will be used by commercial software publishers who have met the minimum financial criteria.
• -S:session is the session name for an enrollment session.
• -P:purpose is the purpose for which the certificate is being generated. This parameter can either be CodeSigning (this is the default) or ClientAuth.
• -x:providerName is the CryptoAPI provider to use. (See the CryptoAPI documentation for more details.)
• -y:nProviderType is the CryptoAPI provider type to use. (See the CryptoAPI documentation for more details.)
• -K:keyspec 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 is the date when the certificate first becomes valid. The default is when the certificate is created.
• -D:nMonths is the duration of the validity period.
• -E:dateEnd is the date when the validity period ends. The default is the year 2039.
• -h:numChildren is the maximum height of the tree below this certificate.
• -t:types is the certificate type. This parameter can be E for end-entity, C for certificate authority, or both.
• -g creates a glue certificate.
• -r creates a self-signed certificate.
• -m means to use the MD5 hash algorithm. This is the default.
• -a means to use the SHA1 hash algorithm.
• -? displays 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

[-name opusName [-info opusInfo]]] [-gui] [-nocerts]

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.
• -name opusName is a name for your program.
• -info opusInfo is a location, such as an URL, for obtaining information about your program.
• -gui invokes the wizard
• -nocerts means you don't 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 is the CryptoAPI provider to use. (See the CryptoAPI documentation for more details.)
• -providerType providerType is the CryptoAPI provider type to use. (See the CryptoAPI documentation for more details.)
• -commerical means the code being signed was created by a commercial software publisher.
• -individual means the code being signed was created by an individual software publisher.
• -sha means you want to use the SHA hashing algorithm.
• -md5 means you want to use the MD5 hashing algorithm. This is the default hashing algorithm.
• -? displays 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:

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

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

Here is an example:

ChkTrust MyProgram.exe

A successful response is:

Result: 0