[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)
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.
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.
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:
- 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.
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:
Feedback and Questions
Questions about CAPICOM can be directed to the discussion list CAPICOM@discuss.microsoft.com.