Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

28    Certificate Manager

Palm OS® Programmer's API Reference

Palm OS® 68K SDK

     

The Certificate Manager manages digital certificates, handling such operations as import, export, parsing, secure storage, content authentication, and storage querying. You can use the Certificate Manager in 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.

The remainder of this chapter documents the Certificate Manager APIs. It is organized into the following sections:

Certificate Manager Structures and Types
Certificate Manager Constants
Certificate Manager Element Field Macros
Certificate Manager Functions and Macros

The header file CertificateMgr.h declares the API that this chapter describes.

Certificate Manager Structures and Types ^TOP^

CertMgrCertChainType Struct ^TOP^

Purpose

A certificate chain is used when calling CertMgrVerifyCert(). You may define a list of certificates to be used when trying to verify the certificate chain.

Declared In

CertificateMgr.h

Prototype

typedef struct {
CertMgrCertInfoType *certs;
uint32_t count;
} CertMgrCertChainType

Fields

certs
Pointer to the first certificate in the chain.
count
Number of certificates in the chain.

Compatibility

Implemented only if Palm OS Cobalt Feature Set is present.

CertMgrCertElementEnum Typedef ^TOP^

Purpose

Certificate element types, used in conjunction with CertMgrGetField().

Declared In

CertificateMgr.h

Prototype

typedef uint32_t CertMgrCertElementEnum

Constants

#define apCertMgrElementTypeRDN 34
#define apCertMgrElementTypeRSA 33
#define apCertMgrElementTypeX509Cert 32
#define apCertMgrElementTypeX509Extensions 35

Compatibility

Implemented only if Palm OS Cobalt Feature Set is present.

CertMgrCertFieldEnum Typedef ^TOP^

Purpose

Certificate element field types, used in conjunction with CertMgrGetField().

Declared In

CertificateMgr.h

Prototype

typedef uint32_t CertMgrCertFieldEnum

Comments

The values used with variables of this type depend on the certificate element. Depending on the certificate element, the element's field types are listed under one of the following:

Compatibility

Implemented only if Palm OS Cobalt Feature Set is present.

CertMgrCertInfoType Struct ^TOP^

Purpose

Abstracts a certificate object. An application uses a structure of this type to refer to a certificate in the memory address space of the Certificate Manager. You can get a reference to a certificate from a successful call to CertMgrImportCert() or CertMgrFindCert()

Declared In

CertificateMgr.h

Prototype

typedef struct {
uint32_t ref;
uint16_t format;
} CertMgrCertInfoType

Fields

ref
An opaque object.
format
The format of the certificate. See "Certificate Formats" for the defined set of certificate format values.

Compatibility

Implemented only if Palm OS Cobalt Feature Set is present.

CertMgrCertSearchEnum Typedef ^TOP^

Purpose

Specifies the search mode to CertMgrFindCert().

Declared In

CertificateMgr.h

Prototype

typedef uint32_t CertMgrCertSearchEnum

Constants

#define apCertMgrSearchCert 1000
In this mode, repeated calls to CertMgrFindCert() iterate through the certificates in the store, each time returning the certificate that resides at the location indicated by the index parameter. Each time CertMgrFindCert() is called, the index parameter is incremented. Accordingly, you can use this mode to iterate through all of the certificates in the certificate store.
#define apCertMgrSearchCertID 1001
Causes CertMgrFindCert() to look for a certificate with a certID that matches that supplied in the reference parameter. The data in reference should be a 20-byte certID.
#define apCertMgrSearchSubjectRDN apCertMgrFieldSubjectRDN
Causes CertMgrFindCert() to look for a certificate whose SubjectRDN matches the one in the reference parameter.

Compatibility

Implemented only if Palm OS Cobalt Feature Set is present.

CertMgrElementListType Struct ^TOP^

Purpose

Structure that represents a list of elements. CertMgrGetField() fills out this structure.

Declared In

CertificateMgr.h

Prototype

typedef struct {
uint32_t length;
uint32_t count;
CertMgrElementType element[1];
} CertMgrElementListType

Fields

length
The length of this structure, including all of the CertMgrElementType structures needed to contain all of the list's fields.
count
The number of fields—that is, the number of CertMgrElementType structures—in the list.
element
The first element. Subsequent elements follow this one.

Compatibility

Implemented only if Palm OS Cobalt Feature Set is present.

CertMgrElementType Struct ^TOP^

Purpose

Structure that represents a single field.

Declared In

CertificateMgr.h

Prototype

typedef struct {
uint16_t type;
uint16_t field;
uint16_t dataType;
uint16_t length;
uint32_t offset;
} CertMgrElementType

Fields

type
The certificate element type. One of the CertMgrCertElementEnum values.
field
The element field identifier. One of the values listed under "X509Cert Element Fields," "RSA Element Fields," "RDN Element Fields,"or "X509Extensions Element Fields."
dataType
The field's data type. One of the values listed under "Data Types".
length
The length, in bytes, of the field data.
offset
The offset, in bytes, to the beginning of the field data.

Compatibility

Implemented only if Palm OS Cobalt Feature Set is present.

CertMgrVerifyResultType Struct ^TOP^

Purpose

If a certificate fails to verify during a call to CertMgrVerifyCert() or CertMgrAddCert(), this structure is filled in and returned to indicate the reason for the verification failure.

Declared In

CertificateMgr.h

Prototype

typedef struct {
uint32_t failureCode;
CertMgrCertInfoType cert;
uint32_t depth;
uint32_t state;
DateTimeType verifyTime;
} CertMgrVerifyResultType

Fields

failureCode
The reason for the verification failure. See "Certificate Verification Failure Codes" for the set of values that can be returned in this field.
cert
The certificate that failed to verify.
depth
How deep the failed certificate is.
state
The verification state.
verifyTime
The date and time against which the certificate was verified.

Compatibility

Implemented only if Palm OS Cobalt Feature Set is present.

Certificate Manager Constants ^TOP^

X509Cert Element Fields ^TOP^

Purpose

Fields in an X509Cert element.

Declared In

CertificateMgr.h

Constants

#define apCertMgrElementFieldEntireCert 17
#define apCertMgrElementFieldExtension 200
#define apCertMgrElementFieldExtensions 23
#define apCertMgrElementFieldInnerDER 1
#define apCertMgrElementFieldIssuerID 15
#define apCertMgrElementFieldIssuerRDN 4
#define apCertMgrElementFieldIssuerUniqueID 21
#define apCertMgrElementFieldNotAfter 7
#define apCertMgrElementFieldNotBefore 6
#define apCertMgrElementFieldPubKeyBER 8
#define apCertMgrElementFieldSerialNumber 3
#define apCertMgrElementFieldSigAlgID 91
#define apCertMgrElementFieldSignature 14
#define apCertMgrElementFieldSigOID 12
#define apCertMgrElementFieldSigParams 13
#define apCertMgrElementFieldSubjectID 16
#define apCertMgrElementFieldSubjectRDN 5
#define apCertMgrElementFieldSubjectUniqueID 22
#define apCertMgrElementFieldVersion 2
#define apCertMgrFieldExtensions apCertMgrElementFieldExtensions
#define apCertMgrFieldIssuerID apCertMgrElementFieldIssuerID
#define apCertMgrFieldIssuerRDN apCertMgrElementFieldIssuerRDN
#define apCertMgrFieldIssuerUniqueID apCertMgrElementFieldIssuerUniqueID
#define apCertMgrFieldNotAfter apCertMgrElementFieldNotAfter
#define apCertMgrFieldNotBefore apCertMgrElementFieldNotBefore
#define apCertMgrFieldPubKeyBER apCertMgrElementFieldPubKeyBER
#define apCertMgrFieldSerialNumber apCertMgrElementFieldSerialNumber
#define apCertMgrFieldSignature apCertMgrElementFieldSignature
#define apCertMgrFieldSigOID apCertMgrElementFieldSigOID
#define apCertMgrFieldSigParams apCertMgrElementFieldSigParams
#define apCertMgrFieldSubjectID apCertMgrElementFieldSubjectID
#define apCertMgrFieldSubjectRDN apCertMgrElementFieldSubjectRDN
#define apCertMgrFieldSubjectUniqueID apCertMgrElementFieldSubjectUniqueID
#define apCertMgrFieldVersion apCertMgrElementFieldVersion

Compatibility

Implemented only if Palm OS Cobalt Feature Set is present.

RSA Element Fields ^TOP^

Purpose

Fields in an RSA element.

Declared In

CertificateMgr.h

Constants

#define apCertMgrElementFieldRSAModulus 16
#define apCertMgrElementFieldRSAPubExpo 17

Compatibility

Implemented only if Palm OS Cobalt Feature Set is present.

RDN Element Fields ^TOP^

Purpose

Fields in an RDN element.

Declared In

CertificateMgr.h

Constants

#define apCertMgrElementFieldRDNOID 4
First RDN OID.
#define apCertMgrElementFieldRDNValue 5
First RDN value.

Comments

To get the second and subsequent OIDs and values, use the apCertMgrElementFieldRDNOIDN() and apCertMgrElementFieldRDNValueN() macros, respectively.

Compatibility

Implemented only if Palm OS Cobalt Feature Set is present.

X509Extensions Element Fields ^TOP^

Purpose

Fields in an X509Extensions element.

Declared In

CertificateMgr.h

Constants

#define apCertMgrElementFieldX509ExBytes 2
First data bytes.
#define apCertMgrElementFieldX509ExCritical 1
First critical flag.
#define apCertMgrElementFieldX509ExOID 0
First extension OID.

Comments

To get the second and subsequent data bytes, critical flags, and extension OIDs, use the apCertMgrElementFieldX509ExBytesN(), apCertMgrElementFieldX509ExCriticalN(), and apCertMgrElementFieldX509ExOIDN() macros, respectively.

Compatibility

Implemented only if Palm OS Cobalt Feature Set is present.

Data Types ^TOP^

Purpose

Data type of an element field. These values appear in the CertMgrElementType data structure.

Declared In

CertificateMgr.h

Constants

#define apCertMgrElementDataTypeASN1BitString 3
#define apCertMgrElementDataTypeASN1BmpString 30
#define apCertMgrElementDataTypeASN1Boolean 1
#define apCertMgrElementDataTypeASN1EmbeddedPDV 11
#define apCertMgrElementDataTypeASN1Enumerated 10
#define apCertMgrElementDataTypeASN1Eoc 0
#define apCertMgrElementDataTypeASN1External 8
#define apCertMgrElementDataTypeASN1GenString 27
#define apCertMgrElementDataTypeASN1GenTime 24
#define apCertMgrElementDataTypeASN1GraphicString 25
#define apCertMgrElementDataTypeASN1IA5String 22
#define apCertMgrElementDataTypeASN1Integer 2
#define apCertMgrElementDataTypeASN1ISO64String 26
#define apCertMgrElementDataTypeASN1Null 5
#define apCertMgrElementDataTypeASN1NumericString 18
#define apCertMgrElementDataTypeASN1ObjDesc 7
#define apCertMgrElementDataTypeASN1OctetString 4
#define apCertMgrElementDataTypeASN1OID 6
#define apCertMgrElementDataTypeASN1PrintString 19
#define apCertMgrElementDataTypeASN1Real 9
#define apCertMgrElementDataTypeASN1Sequence 16
#define apCertMgrElementDataTypeASN1Set 17
#define apCertMgrElementDataTypeASN1T61String 20
#define apCertMgrElementDataTypeASN1UnivString 28
#define apCertMgrElementDataTypeASN1UTCTime 23
#define apCertMgrElementDataTypeASN1UTF8String 12
#define apCertMgrElementDataTypeASN1VideoTexString 21

Compatibility

Implemented only if Palm OS Cobalt Feature Set is present.

Certificate Formats ^TOP^

Purpose

Specifies the certificate format. The CertMgrCertInfoType structure's format field takes one of these values.

Declared In

CertificateMgr.h

Constants

#define apCertMgrFormatX509 1
The certificate is a DER encoded x509 certificate.
#define apCertMgrFormatXML 2
The certificate is formatted as XML.

NOTE: XML-formatted certificates are not currently supported in Palm OS Cobalt.

Compatibility

Implemented only if Palm OS Cobalt Feature Set is present.

Certificate Manager Error Codes ^TOP^

Purpose

Error codes returned by the various Certificate Manager functions.

Declared In

CertificateMgr.h

Constants

#define certMgrErrBackupInProgress (certErrorClass | 0x0C)
The certificate vault could not be accessed because it is in the process of being backed up.
#define certMgrErrBufTooSmall (certErrorClass | 0x07)
The export buffer is too small. The required size is written into the variable pointed to by the length parameter.
#define certMgrErrCertNotFound (certErrorClass | 0x09)
A certificate matching the specified criteria was not found.
#define certMgrErrDatabaseFail (certErrorClass | 0x0B)
A Data Manager error occurred.
#define certMgrErrFieldNotFound (certErrorClass | 0x08)
The specified field could not be found.
#define certMgrErrInvalidEncoding (certErrorClass | 0x02)
The specified format encoding is invalid.
#define certMgrErrInvalidParam (certErrorClass | 0x04)
One of the function parameters is invalid.
#define certMgrErrNotExportable (certErrorClass | 0x0A)
The certificate is not exportable. It is probably stored in compressed form.
#define certMgrErrNotImplemented (certErrorClass | 0x01)
The requested certificate format is not supported.
#define certMgrErrNotRemovable (certErrorClass | 0x0D)
The certificate is not removable.
#define certMgrErrOutOfMemory (certErrorClass | 0x03)
There was insufficient memory to complete the operation.
#define certMgrErrOutOfResources (certErrorClass | 0x06)
The Certificate Manager ran out of resources.
#define certMgrErrServiceNotStarted (certErrorClass | 0x05)
The Certificate Manager process has not started.

Compatibility

Implemented only if Palm OS Cobalt Feature Set is present.

Certificate Verification Failure Codes ^TOP^

Purpose

Indicates why a certificate failed to verify. These values are returned in the CertMgrVerifyResultType structure's failureCode field as the result of a call to CertMgrVerifyCert() or CertMgrAddCert(). These are also passed to the SSL Library's Verify callback; see "The Verify Callback".

Declared In

CertificateMgr.h

Constants

#define CertMgrVerifyFail (certErrorClass+0x80)
#define CertMgrVerifyFailBasicConstraints (CertMgrVerifyFail+8)
There was a constraint violation.
#define CertMgrVerifyFailCriticalExtension (CertMgrVerifyFail+9)
The critical extension is unknown.
#define CertMgrVerifyFailKeyUsage (CertMgrVerifyFail+7)
#define CertMgrVerifyFailNotAfter (CertMgrVerifyFail+6)
#define CertMgrVerifyFailNotBefore (CertMgrVerifyFail+5)
#define CertMgrVerifyFailSelfSigned (CertMgrVerifyFail+4)
#define CertMgrVerifyFailSignature (CertMgrVerifyFail+3)
The signature is invalid.
#define CertMgrVerifyFailUnknown (CertMgrVerifyFail+0)
#define CertMgrVerifyFailUnknownIssuer (CertMgrVerifyFail+1)
The root cannot be trusted since the issuer is not known.
#define CertMgrVerifyFailUnknownSigAlg (CertMgrVerifyFail+2)

Compatibility

Implemented only if Palm OS Cobalt Feature Set is present.

Miscellaneous Certificate Manager Constants ^TOP^

Purpose

These constants are also declared in CertificateMgr.h.

Declared In

CertificateMgr.h

Constants

#define CertMgrServiceName "pSysCertificateManager"
The name under which the Certificate Manager is registered with the Service Manager.

Compatibility

Implemented only if Palm OS Cobalt Feature Set is present.

Certificate Manager Element Field Macros ^TOP^

apCertMgrElementFieldRDNOIDN Macro ^TOP^

Purpose

Macro that evaulates to the field ID for the the second and subsequent OID fields for an RDN element.

Declared In

CertificateMgr.h

Prototype

#defineapCertMgrElementFieldRDNOIDN (
   n
)

Parameters

n
The OID field index. The second OID field's index would be 2.

Returns

Evaluates to the RDN element's OID field ID.

Compatibility

Implemented only if Palm OS Cobalt Feature Set is present.

apCertMgrElementFieldRDNValueN Macro ^TOP^

Purpose

Macro that evaulates to the field ID for the second and subsequent Value fields for an RDN element..

Declared In

CertificateMgr.h

Prototype

#defineapCertMgrElementFieldRDNValueN (
   n
)

Parameters

n
The Value field index. The second Value field's index would be 2.

Returns

Evaluates to the RDN element's Value field ID.

Compatibility

Implemented only if Palm OS Cobalt Feature Set is present.

apCertMgrElementFieldX509ExBytesN Macro ^TOP^

Purpose

Macro that evaulates to the field ID for the the second and subsequent Bytes fields for an X509Extended element.

Declared In

CertificateMgr.h

Prototype

#defineapCertMgrElementFieldX509ExBytesN (
   n
)

Parameters

n
The Bytes field index. The second Bytes field's index would be 2.

Returns

Evaluates to the X509Extended element's Bytes field ID.

Compatibility

Implemented only if Palm OS Cobalt Feature Set is present.

apCertMgrElementFieldX509ExCriticalN Macro ^TOP^

Purpose

Macro that evaulates to the field ID for the the second and subsequent Criticial fields for an X509Extended element.

Declared In

CertificateMgr.h

Prototype

#defineapCertMgrElementFieldX509ExCriticalN (
   n
)

Parameters

n
The Critical field index. The second Critical field's index would be 2.

Returns

Evaluates to the X509Extended element's Critical field ID.

Compatibility

Implemented only if Palm OS Cobalt Feature Set is present.

apCertMgrElementFieldX509ExOIDN Macro ^TOP^

Purpose

Macro that evaulates to the field ID for the the second and subsequent OID fields for an X509Extended element.

Declared In

CertificateMgr.h

Prototype

#defineapCertMgrElementFieldX509ExOIDN (
   n
)

Parameters

n
The OID field index. The second OID field's index would be 2.

Returns

Evaluates to the X509Extended element's OID field ID.

Compatibility

Implemented only if Palm OS Cobalt Feature Set is present.

Certificate Manager Functions and Macros ^TOP^

CertMgrAddCert Function ^TOP^

Purpose

Add a certificate to the certificate store.

Declared In

CertificateMgr.h

Prototype

status_tCertMgrAddCert (
   CertMgrCertInfoType*certInfoP,
   Booleancompress,
   CertMgrVerifyResultType*verifyResult
)

Parameters

certInfoP
Pointer to CertMgrCertInfoType structure for the certificate to be added.
compress
If true, the certificate is stored in compressed form. This saves space, but note that you cannot export certificates that are compressed.
verifyResult
Supply a pointer to a CertMgrVerifyResultType structure that will be filled in if the certificate could not be verified.

Returns

Returns errNone if the certificate was added successfully, or one of the following otherwise:

certMgrErrInvalidParam
certInfoP or verifyResult is NULL .
certMgrErrServiceNotStarted
The Certificate Manager process has not started.
certMgrErrDatabaseFail
A Data Manager error occurred.
certMgrErrBackupInProgress
The certificate vault could not be accessed because it is in the process of being backed up.

Comments

This function can be used to add an imported certificate to the certificate store. When a certificate becomes part of the store it is verified and then saved in the Certificate Manager's secure vault. Other applications may then query for it.

If the certificate cannot be added due to a failure in the verification of the certificate, this function fills in the caller-supplied CertMgrVerifyResultType structure. In many cases the caller might choose to override the verification failure and request that the certificate be stored anyway. The only errors that cannot be overridden are signature failure and unknown issuer. To override a verification error, clear the failure code in the CertMgrVerifyResultType structure and then call CertMgrAddCert() once again.

When the compress parameter is set to true, some data is thrown away from the certificate to save space. Because of this, the stored certificate is not complete and cannot be exported at a later time.

Example

The following code excerpt adds certificates that may be self-signed:


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; 
} 
} 

Compatibility

Implemented only if Palm OS Cobalt Feature Set is present.

See Also

CertMgrImportCert(), CertMgrRemoveCert(), CertMgrVerifyCert()

CertMgrExportCert Function ^TOP^

Purpose

Exports a certificate from the certificate store to a caller-supplied buffer.

Declared In

CertificateMgr.h

Prototype

status_tCertMgrExportCert (
   CertMgrCertInfoType*certInfoP,
   uint8_t*certData,
   uint32_t*certDataLen
)

Parameters

certInfoP
Reference to the certificate to be exported.
certData
Pointer to a caller-allocated buffer into which the exported certificate data will be written, or NULL to determine how large this buffer should be (the needed size, in bytes, is returned via certDataLen).
certDataLen
When calling this function, *certDataLen should be set to the size of the certData buffer, or 0 to determine how large the certData buffer should be. Upon return *certDataLen is set to the size of the exported certificate data.

Returns

Returns errNone if the operation completed successfully, or one of the following otherwise:

certMgrErrBufTooSmall
The export buffer is too small. The required size is written into *certDataLen.
certMgrErrNotExportable
The certificate is not exportable. It is probably stored in compressed form.
certMgrErrDatabaseFail
A Data Manager error occurred.
certMgrErrBackupInProgress
The certificate vault could not be accessed because it is in the process of being backed up.

Comments

This function attempts to fill the supplied buffer with the same data that was imported into the Certificate Manager.


NOTE: In Palm OS Cobalt only DER encoded X509 format certificates are supported. Because of this, all exported certificate data will be in this format.

If the certificate was compressed when it was added to the store, it cannot be exported.

If the export buffer is not large enough, an error is returned along with the expected size.

Compatibility

Implemented only if Palm OS Cobalt Feature Set is present.

See Also

CertMgrImportCert()

CertMgrFindCert Function ^TOP^

Purpose

Search the certificate store for a certificate matching the specified criteria.

Declared In

CertificateMgr.h

Prototype

status_tCertMgrFindCert (
   uint32_t*index,
   CertMgrCertSearchEnumsearchFlag,
   uint8_t*reference,
   uint32_treferenceLen,
   CertMgrCertInfoType*certInfoP
)

Parameters

index
Set to 0 to start new search. As a certificate matching the specified criteria is found, *index is set to the index of the certificate within the certificate store.
searchFlag
Value that specifies how the search is to be performed. Supply one of the values listed under CertMgrCertSearchEnum.
reference
The data being searched for. If searchFlag is apCertMgrSearchCertID, this should be the 20-byte certID being searched for. If searchFlag is apCertMgrSearchSubjectRDN search, this should be the SubjectRDN being searched for.
referenceLen
The size, in bytes, of the data pointed to by reference.
certInfoP
Pointer to a CertMgrCertInfoType structure that is filled in as appropriate to identify the certificate that was found.

Returns

Returns errNone if the operation completed successfully, or one of the following otherwise:

certMgrErrInvalidParam
One of the function parameters is invalid.
certMgrErrServiceNotStarted
The Certificate Manager process has not started.
certMgrErrCertNotFound
A certificate matching the specified criteria was not found.
certMgrErrBackupInProgress
The certificate vault could not be accessed because it is in the process of being backed up.

Example

To find a certificate with the certificate ID in certificateID, do the following:


err = CertMgrFindCert(0, apCertMgrSearchCertID, 
certificateID, 20,
&certInfo); 

Compatibility

Implemented only if Palm OS Cobalt Feature Set is present.

See Also

CertMgrReleaseCertInfo()

CertMgrGetField Function ^TOP^

Purpose

Get the value of a certificate field.

Declared In

CertificateMgr.h

Prototype

status_tCertMgrGetField (
   CertMgrCertInfoType*certInfoP,
   CertMgrCertElementEnumelementType,
   CertMgrCertFieldEnumfieldType,
   CertMgrElementListType*result,
   uint32_t*resultLengthP
)

Parameters

certInfoP
Reference to the certificate from which the field is to be retrieved.
elementType
The certificate element type. This should be one of the values listed under CertMgrCertElementEnum.
fieldType
The type of field to be retrieved. See CertMgrCertFieldEnum. Note that the set of values that can be supplied to this parameter varies depending on the value of the elementType parameter.
result
Pointer to a buffer into which the field data is written, or NULL to obtain the size of the needed buffer. The size of the field data (actual or needed) is written into *resultLengthP. Note that the contents of the buffer upon return are structured according to CertMgrElementListType.
resultLengthP
When calling this function, *resultLengthP should be set to the size of the result buffer, or 0 to determine how large the result buffer should be. Upon return *resultLengthP is set to the size of the field data.

Returns

Returns errNone if the operation completed successfully, or one of the following otherwise:

certMgrErrInvalidParam
certInfoP is NULL or it is not a valid certificate reference, or resultLengthP is NULL.
certMgrErrBufTooSmall
The export buffer is too small. The required size is written into *resultLengthP.
certMgrErrFieldNotFound
The specified field could not be found.

Example

The following code excerpt shows you you might use this function.


#define CertMgrOrganicationNameOIDLen5 
static uint8_t 
CertMgrOrganizationNameOID[CertMgrOrganicationNameOIDLen] = 
{0x06, 0x03, 0x55, 0x04, 0x0a}; 
 
/* Getting the issuer RDN from the cert */ 
CertMgrImplGetField(certInfoP, apCertMgrElementTypeRDN,  0,
field, &fieldlen); 
 
/* This gets the whole issuer RDN, you must then go through 
each field and find the one that you want, an OID field leads 
a data field */ 
 
/* The following code finds the code for the issuer name and 
sets a label to it */ 
/* Fields in list */ 
for (index = 0; index < field->count; index++) { 
 
if (field->element[index].dataType ==
apCertMgrElementDataTypeASN1OID) { 
if (field->element[index].length ==
CertMgrOrganicationNameOIDLen) { 
if (MemCmp(CertMgrOrganizationNameOID, 
((uint8_t *)field)+field->element[index].offset,
CertMgrOrganizationNameOIDLen) == 0) { 
 
uint16_t buflen = field->element[index +
1].length; 
uint8_t *buffer = ((uint8_t *)field) + 
field->element[index + 1].offset; 
uint16_t count  = 0; 
 
Char label[40]; 
uint16_t pre = 0; 
 
MemSet(label, 40, 0); 
 
if (buflen < 40) { 
pre = (40 - buflen) / 2; 
 
MemSet(label, pre, ' '); 
} 
 
MemMove(label+pre,buffer,buflen>39 ? 39:buflen); 
 
FrmCopyLabel(frmP, selfsignedaddCertnameLabel,
label); 
break; 
} 
} 
} 
} 

Compatibility

Implemented only if Palm OS Cobalt Feature Set is present.

CertMgrImportCert Function ^TOP^

Purpose

Imports a certificate from a buffer into the certificate store.

Declared In

CertificateMgr.h

Prototype

status_tCertMgrImportCert (
   uint8_t*certData,
   uint32_tcertDataLen,
   CertMgrCertInfoType*certInfoP
)

Parameters

certData
Pointer to a buffer containing the certificate data being imported.
certDataLen
The size, in bytes, of the data in certData.
certInfoP
When calling this function, you can optionally specify the format of the certificate data by setting the format field of this structure. Upon return, this structure's fields are filled in appropriately to identify the certificate that was imported.

NOTE: In Palm OS Cobalt only DER encoded X509 format certificates are supported.

Returns

Returns errNone if the operation completed successfully, or one of the following otherwise:

certMgrErrInvalidEncoding
The specified format encoding is invalid.
certMgrErrOutOfMemory
There was insufficient memory to complete the operation.
certMgrErrInvalidParam
One of the function parameters is invalid.
certMgrErrServiceNotStarted
The Certificate Manager process has not started.
certMgrErrBackupInProgress
The certificate vault could not be accessed because it is in the process of being backed up.
certMgrErrNotImplemented
The requested certificate format is not supported.

Example

A likely scenario would be an application that imports a certificate that was stored in the its PRC. The following code excerpt shows how to do this:


/* Get certificate from PRC */ 
err = SignGetCertificateByIndex(dbP, certIndex, &certBlock,
&certDataLength, certData); 
 
/* Load certificate onto cert mgr */ 
err = CertMgrImportCert(certData, certDataLength, &certInfo); 

Compatibility

Implemented only if Palm OS Cobalt Feature Set is present.

See Also

CertMgrExportCert()

CertMgrReleaseCertInfo Function ^TOP^

Purpose

Release resources that allocated by the Certificate Manager during a successful call to CertMgrFindCert() or CertMgrImportCert().

Declared In

CertificateMgr.h

Prototype

status_tCertMgrReleaseCertInfo (
   CertMgrCertInfoType*certInfoP
)

Parameters

certInfoP
Reference to the certificate for which resources are to be released..

Returns

Returns errNone if the operation completed successfully, or certMgrErrInvalidParam if certInfoP is invalid.

Comments

Failure to call this function after a successful call to CertMgrFindCert() or CertMgrImportCert() will result in a memory leak.

Compatibility

Implemented only if Palm OS Cobalt Feature Set is present.

CertMgrRemoveCert Function ^TOP^

Purpose

Remove a certificate from the certificate store.

Declared In

CertificateMgr.h

Prototype

status_tCertMgrRemoveCert (
   CertMgrCertInfoType*certInfoP
)

Parameters

certInfoP
Pointer to CertMgrCertInfoType structure for the certificate to be added.

Returns

Returns errNone if the operation completed successfully, or one of the following otherwise:

certMgrErrInvalidParam
certInfoP is invalid.
certMgrErrBackupInProgress
The certificate vault could not be accessed because it is in the process of being backed up.
certMgrErrNotRemovable
The certificate is not removable.

Comments

This function does not invalidate any other certificates already in the store. However, it may cause further verifications of new certificates to fail (for instance, if a root certificate is removed).

Compatibility

Implemented only if Palm OS Cobalt Feature Set is present.

See Also

CertMgrAddCert()

CertMgrVerifyCert Function ^TOP^

Purpose

Authenticate the validity of a certificate.

Declared In

CertificateMgr.h

Prototype

status_tCertMgrVerifyCert (
   CertMgrCertInfoType*certInfoP,
   CertMgrCertChainType*certChainP,
   CertMgrVerifyResultType*verifyResult
)

Parameters

certInfoP
Pointer to CertMgrCertInfoType structure for the certificate to be validated.
certChainP
A chain of certificates that make up the authentication tree for this certificate.
verifyResult
Supply a pointer to a CertMgrVerifyResultType structure that will be filled in if the certificate could not be verified.

Returns

Returns errNone if the operation completed successfully, or one of the following otherwise:

certMgrErrInvalidParam
certInfoP or verifyResult is NULL.
certMgrErrOutOfMemory
There was insufficient memory to complete the operation.
certMgrErrOutOfResources
The Certificate Manager ran out of resources.
certMgrErrServiceNotStarted
The Certificate Manager process has not started.

This function authenticates the validity of the certificate. Many different error conditions may occur, and they are returned through the verifyResult parameter.

Specify a certificate chain when the chain of certificates that authenticate the specified certificate is not contained in the Certificate Manager's certificate store. (For instance, when all or some of the certificatess in the chain have just been imported but not yet added.) When necessary, the Certificate Manager will also authenticate a certificate in the chain. The chain need not be in any order, and the certificates in the chain need not all be part of the chain.

Compatibility

Implemented only if Palm OS Cobalt Feature Set is present.

See Also

CertMgrAddCert()

CertMgrVerifyFailure Macro ^TOP^

Purpose

Determine if a given error code is a Certificate Manager verification error.

Declared In

CertificateMgr.h

Prototype

#defineCertMgrVerifyFailure (
   err
)

Parameters

err
The error code being checked.

Returns

Evaluates to true if the supplied error code is within the range of verification failure errors, false otherwise. See "Certificate Verification Failure Codes" for those error codes that are classified as verification errors.

Compatibility

Implemented only if Palm OS Cobalt Feature Set is present.