Devices running Palm OS Cobalt include a Certificate Manager, developed by RSA Security. The Certificate Manager handles X.509 standard certificates. The Certificate Manager exposes a standard API for applications and system modules that need certificate services.
NOTE: The Certificate Manager is only present on Palm Powered devices running Palm OS Cobalt. Be sure to check for the Palm OS Cobalt Feature Set before attempting to call any of the Certificate Manager functions.
Certificate Manager
The Certificate Manager provides a secure server for the storing and parsing of DER-encoded X.509 digital certificates. It exposes functions that allow you to import, export, parse, and verify those certificates.
You can use the Certificate Manager in either of two different ways: as a certificate verifier and parser, and as a certificate store. In the verifier/parser mode, the Certificate Manager takes data as input and parses it as a digital certificate. The user can then verify the certificate and access its internal fields. In certificate store mode, the Certificate Manager can securely store a tree of digital certificates (with multiple roots) and make the fields of those certificates available to users.
The Certificate Manager is a system server with a client-side library. To securely store certificates, the Certificate Manager makes use of the Data Manager's vault facilities. This allows the Certificate Manager to guarantee the integrity of any certificate added to its certificate store.
Note that very few applications use the Certificate Manager directly. The Certificate Manager only exposes a fairly low-level set of APIs.
Certificate Store Operations
The Certificate Manager can securely store a tree of digital certificates (with multiple roots). Figure 13.1 shows the basic certificate hierarchy.
Figure 13.1 Certificate Hierarchy
At boot time the certificate store is seeded with the list of root certificates that were stored in ROM by the device manufacturer. These ROM certificates are used to authenticate RAM certificates.
To get a certificate from the store, call CertMgrFindCert(). This function can be used in one of two modes: to find a particular certificate by ID or by subject RDN, or to iterate through all of the certificates in the certificate store. You control this function's operation through the use of the searchFlag parameter.
To add and remove certificates from the store, you use CertMgrAddCert() and CertMgrRemoveCert(), respectively. Note that you can only add a certificate if its authentication chain already resides in the certificate store, or if the certificate is self-signed. Also note that removing a certificate that is part of an authentication chain may prevent new certificates from being authenticated.
The code excerpt shown in Listing 13.1 shows how you can use CertMgrAddCert() to add a self-signed certificate to the certificate store.
Listing 13.1 Adding a self-signed certificate
while (true) {
err = CertMgrAddCert(&certInfo, false, &verifyResult);
if (err) {
CertMgrReleaseCertInfo(&certInfo);
goto exit;
}
if (verifyResult.failureCode == 0) {
break;
} else {
if (verifyResult.failureCode ==
CertMgrVerifyFailSelfSigned) {
verifyResult.failureCode = 0;
continue;
}
/* Another type of failure */
break;
}
}
Certificate Verification and Parsing
Use CertMgrImportCert() to import a DER-encoded x509 certificate and get back a CertMgrCertInfoType structure. This structure represents a certificate object. You then verify this certificate's contents by calling CertMgrVerifyCert(). Once you have a verified certificate, use CertMgrGetField() to get fields out of the certificate. Most commonly, applications will want to get the key from the certificate.
Once you are done with a certificate, be sure to call CertMgrReleaseCertInfo() to release these resources that were allocated by the Certificate Manager during the call to CertMgrFindCert() or CertMgrImportCert().
Certificate Backup and Restore
All certificates in the certificate store are backed up and restored.