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
CertMgrCertChainType Struct
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
Compatibility
Implemented only if Palm OS Cobalt Feature Set is present.
CertMgrCertElementEnum Typedef
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
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
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
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 theindex
parameter. Each timeCertMgrFindCert()
is called, theindex
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 thereference
parameter. The data inreference
should be a 20-byte certID. -
#define apCertMgrSearchSubjectRDN apCertMgrFieldSubjectRDN
- Causes
CertMgrFindCert()
to look for a certificate whose SubjectRDN matches the one in thereference
parameter.
Compatibility
Implemented only if Palm OS Cobalt Feature Set is present.
CertMgrElementListType Struct
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
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
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
X509Cert Element Fields
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
Purpose
Declared In
CertificateMgr.h
Constants
Compatibility
Implemented only if Palm OS Cobalt Feature Set is present.
RDN Element Fields
Purpose
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
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
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
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.
Compatibility
Implemented only if Palm OS Cobalt Feature Set is present.
Certificate Manager Error Codes
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
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
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
apCertMgrElementFieldRDNOIDN Macro
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
#define apCertMgrElementFieldRDNOIDN (
n
)
Parameters
Returns
Evaluates to the RDN element's OID field ID.
Compatibility
Implemented only if Palm OS Cobalt Feature Set is present.
apCertMgrElementFieldRDNValueN Macro
Purpose
Macro that evaulates to the field ID for the second and subsequent Value fields for an RDN element..
Declared In
CertificateMgr.h
Prototype
#define apCertMgrElementFieldRDNValueN (
n
)
Parameters
Returns
Evaluates to the RDN element's Value field ID.
Compatibility
Implemented only if Palm OS Cobalt Feature Set is present.
apCertMgrElementFieldX509ExBytesN Macro
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
#define apCertMgrElementFieldX509ExBytesN (
n
)
Parameters
Returns
Evaluates to the X509Extended element's Bytes field ID.
Compatibility
Implemented only if Palm OS Cobalt Feature Set is present.
apCertMgrElementFieldX509ExCriticalN Macro
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
#define apCertMgrElementFieldX509ExCriticalN (
n
)
Parameters
Returns
Evaluates to the X509Extended element's Critical field ID.
Compatibility
Implemented only if Palm OS Cobalt Feature Set is present.
apCertMgrElementFieldX509ExOIDN Macro
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
#define apCertMgrElementFieldX509ExOIDN (
n
)
Parameters
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
CertMgrAddCert Function
Purpose
Add a certificate to the certificate store.
Declared In
CertificateMgr.h
Prototype
status_t CertMgrAddCert ( 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
orverifyResult
isNULL
. -
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
Purpose
Exports a certificate from the certificate store to a caller-supplied buffer.
Declared In
CertificateMgr.h
Prototype
status_t CertMgrExportCert ( 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 viacertDataLen
). -
↔ certDataLen
- When calling this function,
*
certDataLen
should be set to the size of thecertData
buffer, or 0 to determine how large thecertData
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
CertMgrFindCert Function
Purpose
Search the certificate store for a certificate matching the specified criteria.
Declared In
CertificateMgr.h
Prototype
status_t CertMgrFindCert ( 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. IfsearchFlag
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
CertMgrGetField Function
Purpose
Get the value of a certificate field.
Declared In
CertificateMgr.h
Prototype
status_t CertMgrGetField ( 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 theelementType
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 toCertMgrElementListType
. -
← resultLengthP
- When calling this function,
*
resultLengthP
should be set to the size of theresult
buffer, or 0 to determine how large theresult
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
isNULL
or it is not a valid certificate reference, orresultLengthP
isNULL
. -
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 CertMgrOrganicationNameOIDLen 5 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
Purpose
Imports a certificate from a buffer into the certificate store.
Declared In
CertificateMgr.h
Prototype
status_t CertMgrImportCert ( 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.
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
CertMgrReleaseCertInfo Function
Purpose
Release resources that allocated by the Certificate Manager during a successful call to CertMgrFindCert()
or CertMgrImportCert()
.
Declared In
CertificateMgr.h
Prototype
status_t CertMgrReleaseCertInfo (
CertMgrCertInfoType *certInfoP
)
Parameters
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
Purpose
Remove a certificate from the certificate store.
Declared In
CertificateMgr.h
Prototype
status_t CertMgrRemoveCert (
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
CertMgrVerifyCert Function
Purpose
Authenticate the validity of a certificate.
Declared In
CertificateMgr.h
Prototype
status_t CertMgrVerifyCert ( 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
orverifyResult
isNULL
. -
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
CertMgrVerifyFailure Macro
Purpose
Determine if a given error code is a Certificate Manager verification error.
Declared In
CertificateMgr.h
Prototype
#define CertMgrVerifyFailure (
err
)
Parameters
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.