Introducing CAPICOM

 

John Lambert
Microsoft Corporation

May 2001

[CAPICOM is a 32-bit only component that is available for use in the following operating systems: Windows Server 2008, Windows Vista, Windows XP, and Windows 2000. Instead, use the .NET Framework to implement security features. For more information, see Alternatives to Using CAPICOM.]

Summary: CAPICOM is a new security technology from Microsoft that allows Microsoft Visual Basic, Visual Basic Script, ASP, and C++ programmers to easily incorporate digital signing and encryption into their application. (5 printed pages)

Contents

Introduction What Is CAPICOM? What Can CAPICOM Do? Signing Data with CAPICOM Safe from Prying Eyes A Message for Only Alice and Bob Minding the Store Platform Availability Where to Get It Feedback and Questions

Introduction

This article introduces CAPICOM, a new security technology from Microsoft. It covers the basic features of CAPICOM. This article is recommended reading for anyone building applications involving digital certificates, digital signatures, encryption, or public key cryptography.

What Is CAPICOM?

CAPICOM is a Microsoft® ActiveX® control that provides a COM interface to Microsoft CryptoAPI. It exposes a select set of CryptoAPI functions to enable application developers to easily incorporate digital signing and encryption functionality into their applications. Because it uses COM, application developers can access this functionality in a number of programming environments such as Microsoft® Visual Basic®, Visual Basic Script, Active Server Pages, Microsoft® JScript®, C++, and others. CAPICOM is packaged as an ActiveX control, allowing Web developers to utilize it in Web based applications as well.

What Can CAPICOM Do?

CAPICOM can be used to enable the following tasks:

  • Digitally sign data with a smart card or software key
  • Verify digitally signed data
  • Graphically display certificate information
  • Inspect certificate properties such as subject name or expiration date
  • Add and remove certificates from the certificate stores
  • Encrypt and decrypt data with a password
  • Encrypt and decrypt data using public keys and certificates

Signing Data with CAPICOM

CAPICOM can sign data whether it is binary or text. CAPICOM can digitally sign data with a certificate issued from a commercial Certificate Authority (CA) such as Verisign, a certificate issued from a Microsoft® Windows® 2000 PKI, or a self-signed certificate. CAPICOM use a certificate whose private key is stored in software, on a smart card, or on a USB token device. The application developer can either pre-select the certificate needed during the signing operation or allow the user to choose, if he or she has more than one certificate. Figure 1 shows the dialog presented to the user when he or she has more than one certificate.

ms995332.intcapicom-fig01(en-us,MSDN.10).gif

Figure 1. Certificate selection dialog

CAPICOM allows the user to sign (adding the primary signature) or Cosign data (adding another signature). Cosigning is useful when two or more parties are digitally signing a contract. The signed data is returned as a PKCS#7 object. The developer can choose whether the data should be stored with the signature, as an attached signature, or separately from the signature, as a detached signature. Since the signature uses industry standard PKCS#7 it can be verified by CAPICOM or many other third party PKI applications. The application developer can add authenticated attributes to the digital signature to store information such as the time when the document was signed.

You can add digital signatures to your application in only three lines of code. The following code creates a digital signature and displays it in a text box.

Private Sub SignData_Click()
    Dim sd As New SignedData
    sd.Content = Text1.Text
    Text2.Text = sd.Sign
End Sub

A digital signature can be verified using CAPICOM. A developer can enable revocation checking during signature verification. One can either verify just the digital signature (if one is simply interested in public key verification) or verify the certificates and certificate chain involved in the digital signature. It is possible to obtain detailed error information from CAPICOM in the event of a problem during verification. Figure 2 shows a sample application that verifies a set of digital signatures on a document.

ms995332.intcapicom-fig02(en-us,MSDN.10).gif

Figure 2. A sample application that verifies a set of digital signatures

Safe from Prying Eyes

CAPICOM can be used to encrypt data with a password. Because CAPICOM is built on top of CryptoAPI, it can use the following algorithms if supported by the underlying platform:

  • RC2
  • RC4
  • DES
  • Triple DES

The following code shows how easy it is to encrypt data using CAPICOM.

Private Sub Encrypt_Click()
    Dim ed As New EncryptedData
    ed.Content = Text1.Text
    ed.SetSecret "secret"
    Text2.Text = ed.Encrypt
End Sub

A Message for Only Alice and Bob

CAPICOM can encrypt data using public key encryption by enveloping the data. Enveloped messages ensure their contents are only readable by the recipient who owns the private key corresponding to the public key used to encrypt the data. By using public key encryption, recipients do not have to share a common secret in order to communicate securely. When a message is enveloped, a session encryption key is generated and the message is encrypted with that session key. Then, the session key is encrypted separately with each of the recipients' public keys from their certificate. The enveloped message consists of the encrypted message, the certificates of the recipients, and the set of encrypted session keys, one for each recipient.

Minding the Store

Windows stores certificates in Certificate Stores. User certificates are stored in the "MY" store. Root certificates are stored in the "Root" store. Intermediate CA certificates are stored in the "CA" store. A developer can enumerate, add, or remove certificates from a certificate store or examine certificates in the Active Directory. With CAPICOM it is easy to add your root certificate to a machine in your enterprise using a simple Visual Basic Script.

Platform Availability

CAPICOM is supported on the following platforms:

  • Windows 95 with Internet Explorer 5 or above
  • Windows 98 with Internet Explorer 5 or above
  • Windows 98 SE
  • Windows Millennium Edition
  • Windows NT® 4 with Service Pack 4
  • Windows 2000

Where To Get It

CAPICOM is available today for download from the MSDN Web site. CAPICOM is delivered with the Platform SDK and is redistributable free of charge. The Platform SDK contains CAPICOM samples, API documentation, and the redistributable CAPICOM ActiveX control. The Platform SDK can be downloaded from the following URL:

https://www.microsoft.com/msdownload/platformsdk/setuplauncher.asp

Feedback and Questions

Questions about CAPICOM can be directed to the discussion list CAPICOM@discuss.microsoft.com.