Digitally signing your code
This authorization process is implemented using Microsoft’s Authenticode technology to determine the status of an application’s code signature. Obtaining an Authenticode compatible certificate from an authority is described later in this chapter. Any certificate authority should work; however, we have had good results using Verisign, Equifax, and Thawte.
A digital certificate is a set of data, which uniquely identifies you, an entity, and is issued by a certification authority (CA) only after that authority has verified your identity. It contains information including your (the owner’s) public key, your name, an expiration date, the name of the Certification Authority that issued the certificate, and a serial number.
The data set includes your public cryptographic key. When you sign your code, Authenticode reads the public key that is retrieved from the certificate information contained in your signed code. This public key is used to verify your identity. (More information on the public key is provided later in this appendix.)
A digital certificate can come in various formats. Of these, the X.509 certificate format is an emerging standard that has been widely used for many years.
An application signed using Authenticode provides security to the QuickBooks user in two ways:
- Authenticity: the user can be confident that the code has indeed originated from you, the software publisher.
- Integrity: the code contained in your application has not been tampered with after it was published.
Notice that Authenticode does not guarantee to end users that it is safe to run the code signed and contained in your application. Neither does Authenticode provide copy protection for your software.
A Certificate Authority is an entity that is entrusted to issue certificates asserting that the recipient individual, machine or organization requesting the certificate fulfills the conditions of an established policy. The CA could be an external commercial CA, or it could be a CA run by your company.
Simply put, it is the Certificate Authority that issues digital certificates. A certificate authority such as VeriSign or Thawte can provide digital certificates.
The following are well-known Certificate Authorities that issue digital certificates compatible with Authenticode:
Once you develop and test your code, you can run it through a one-way hash function that produces a fixed-length “digest.” The digest is then encrypted with your private key; and combined into a signature block with the name of the hash algorithm and the certificate.
As mentioned previously, the certificate holds information such as your name, the public key, and the name of the certificate authority’s certificate. This signature block is then inserted back into the portable-executable file format under a reserved section, and the code is then distributed.
When your application attempts to access QuickBooks, the authorization process that uses Authenticode is invoked. In this process, the signature is extracted, the certificate authority that authenticated the certificate is determined and your public key distributed by that certificate authority is read. Using this public key, the digest is decrypted. The specified digest is run on the code again, creating a new digest. If the code has not been modified since it was signed, the new digest should match the old one. If the two digests don’t match, it implies that either the code was modified, or the public and private keys aren’t a matched pair. In either case, the code becomes suspect and the QuickBooks user is warned about this fact.
The Internet Client Software Developer’s Kit (Microsoft’s Authenticode toolkit) provides the necessary utilities to make it easy to follow the code-signing process.
You need to apply for a Software Publisher’s Certificate from an appropriate Certificate Authority. As mentioned earlier, make sure that you are asking for a Software Publisher’s Certificate that is compatible with Microsoft Authenticode technology. The actual application process may differ depending on which Certificate Authority you use.
Along with your application, you need to submit the details such as your company registration and organizational information to the Certificate Authority. This is required by the Certificate Authority to verify your identity.
When the Certificate Authority verifies the information that you submitted, it will inform you of this fact and provide you with guidelines to download the certificate. It may take about 3 to 5 days for the Certificate Authority to complete this step.
At this stage, you will have obtained the Certificate as a Software Publishing Certificate (.spc) file.
To perform code signing, you will be using the following:
- The private key stored as a .pvk file, generated during the certificate application process.
- The Software Publishing Certificate (.spc) file received from the Certificate Authority.
You may sign your code at a stage just preceding your code distribution process. Code signing is a quick process, not lasting more than a few minutes. You need to only sign your code once each time you rebuild or distribute your application.
The following is a checklist of the items you will need to sign your application:
- A Software Publisher’s Certificate compatible with Microsoft Authenticode.
- Internet Explorer (IE) version 4.0 or above.
- The Internet Client Software Developer’s Kit downloaded from Microsoft’s web site and installed on your system.
You may find the following web site links useful for additional reference:
Certificate Authorities:
Information on Authenticode
No. You cannot digitally sign ActiveX or Java applications. QuickBooks looks for the executable process that is connecting to it via COM and will not be able to find the signature. For example, if you use a Java-to-COM bridge such as JACOB, you are going through a .dll so when QuickBooks traces back it’s going to find the java virtual machine and not your signature.
This section describes the process of using a digital certificate to sign application code. It describes the process using QuickBooks, a sample application to be signed, and Microsoft’s Internet Client Software Developer’s Kit.
Suppose we have an application called Sally’s Report Writer, represented by TestApp.exe, This application sends a qbXML request to QuickBooks, which contains a request for querying vendor information for reporting. Suppose the application’s UI looks like this:
When “Send request to QuickBooks” is selected, QuickBooks goes through the authorization process. QuickBooks then displays the following information about the application:
- The Application calls itself “Test Application”.
- This application does not have a certificate.
- QuickBooks cannot verify the developer’s identity.
This information is displayed in a dialog box to the QuickBooks user, as shown below:
Now, lets see what happens after we digitally sign this application and observe how QuickBooks displays information about the certification to the user.
You use Internet Client Software Developer’s Kit to sign the application.
Notice that the following programs are installed as part of the Internet Client Software Developer’s Kit (working with IE-5.X):
- MakeCert, which creates a test X.509 certificate.
- Cert2SPC, which creates a test SPC.
- 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.
The installation process places these programs in \inetsdkbin by default. The only one of these application that you absolutely need to use is SignCode.
However, if you want to familiarize yourself with the signing process, you can create a test digital certificate and use this to sign your code. You may perform this test even before you apply for a digital certificate from a Certificate Authority of your choice, or while waiting for your request to be processed.
To create a test certificate, use the MakeCert, and Cert2SPC components of the Internet Client Software Developer’s Kit. For additional information on creating a test certificate, refer to the Microsoft documentation.
Let us incorporate digital code signing in our application “Sally’s report Writer”, represented by TestApp.exe. We accomplish this by using the program SignCode. Follow these steps:
Where to Obtain the Internet Client Software Developer’s Kit
Run SignCode. This brings up the Digital Signature wizard.
In the wizard, click Next.
In the file selection dialog, browse for TestApp.exe, select it, and click Next.
In the next dialog, select Custom and then click Next.
Specify the location of the certificate file (.spc), then browse to the private key file (.pvk) when prompted.
Provide the private key password when prompted.
Select the “SHA1” Hash algorithm when prompted.
Select “All certificates in the certificate path including root” and “No additional certificates” when prompted.
Select “Select from Store” to display the list of certificates. You should see the certificate received from the Certificate Authority in the list.
Select the desired certificate and click OK.
Click Next to display details for this certificate.
Click View Certificate to view the details for the certificate.
Click Next. This is where you must specify an appropriate description of your application for display to the QuickBooks user. This value must match exactly the application name you supply in the AppName parameter of the OpenConnection2 call! For our purpose, let us specify the description as “Report Writer for QuickBooks Vendor Information”, and the web URL as “http://www.SallysReports.com”.
Click Next.
Leaving the timestamp box unchecked, click Next.
Click Finish. SignCode displays the message: “The Digital Signing wizard was completed successfully.”
At this stage you have a digitally signed application TestApp.exe. If you run this with QuickBooks, you can observe the change in the User Interface for the authorization process in QuickBooks.
The certification information is displayed to the QuickBooks user. QuickBooks displays the Application Name “Report Writer for QuickBooks Vendor Information” and the Developer’s Name “Sally’s Report Writer”. The fact that the Certificate Authority “Test Certificate Authority” has verified your identity is also displayed.
