Unified -Certificate Store Tutorial

Unified -Certificate Store TutorialThe Unified Certificate Store is the single point of access for -client applications to access and manipulate certificate stores in the device. -This tutorial provides information on how you can use the Unified Certificate -Store to perform various certificate-manipulation operations. -

Procedure

Follow these steps to perform the various -certificate manipulation operations using the Unified Certificate Store:

Create an instance of -the Unified Certificate Store and initialize it.

You can create a -certificate store in read-only or writable mode. Operations like adding and -removing certificates can be performed when the certificate store is in writable -mode. Basic operations like listing certificates, retrieving certificate details, -viewing trust statuses of certificates can be performed when the certificate -store is in read-only mode.

The following steps explain the processing -of creating and initialising a Unified Certificate Store:
1. Create an instance of -the RFs class. Use the object created as a file system session.
2. Create an object of -type CUnifiedCertStore using CUnifiedCertStore::NewL() or CUnifiedCertStore::NewLC().
  
  Note:
  
  The value that you set for the Boolean variable aOpenForWrite decides -if you can open the certificate store in read-only or writable mode. Set the -value of the variable to:
  - ETrue to -open the certificate store with write access.
  - EFalse to -open the certificate store with read-only access.
3. Initialize the certificate -store and the member functions using the asynchronous function CUnifiedCertStore::Initialize().
The code snippet to create and initialize a Unified Certificate Store -is as follows:
-//Create a file system session object -RFs iFs; -iFS.connect(); -CleanupClosePushL(iFs); - - -//Create and initialize the Unified Certificate Store -CUnifiedCertStore* iCertStore = CUnifiedCertStore::NewL(iFs, ETrue); - -//iStatus is a TRequestStatus -iCertStore->Initialize(iStatus); -
Complete any of the -following tasks as per your requirement:
- Adding certificates
- Removing certificates
- Finding certificates
- Retrieving certificate as a parsed object
- Retrieving certificate details
- Managing applicability and trust settings for certificates

Adding certificates

Before -adding a certificate, it is essential to determine the certificate store to -which the certificate will be added.

The following steps explain the -process of retrieving the certificate store by specifying an appropriate index -value and then adding a certificate to the particular store:

Create an object of -a writable certificate store using MCTWritableCertStore and -retrieve the certificate store to which the certificate will be added.
Specify the details -of the certificate to be added and include it to the selected store using MCTWritableCertStore::Add().

The following code snippet explains how to add a certificate to the -certificate store:

Removing certificates

Specify -details of the certificate to be removed and then remove it from the certificate -store. The following steps provide the require details:

Create an object of -a writable certificate store using MCTWritableCertStore and -retrieve the certificate store from which the certificate will be removed.
Create a CCTCertInfo object -of the certificate to be removed. Pass this to the CUnifiedCertStore::Remove() function -to remove the particular certificate from the certificate store.

The following code snippet explains how to remove a certificate from -the certificate store:

-//Create and initialize the Unified Certificate Store -. -. -. - -//Create an object of the writable certificate store - -//Retrieve the certificate store present at the specified index -//If the certificate store index is invalid -//or the specified certificate store cannot be opened -//then the store object is NULL - -MCTWritableCertStore& ustore = iCertStore->iWritableCertStore(0); -. -. -. -//Create a CCTCertInfo object for the certificate to be removed - -//Instantiate a token - -_LIT(KTokenString,"certtoken"); - -class CSimpleToken:: public CBase,public MCTToken -{ -public: - static MCTToken* NewL(MCTTokenType* aTokenType); - -public: // From MCTToken - MCTTokenType& TokenType(); - const TDesC& Label(); - TCTTokenHandle Handle(); - -private: - MCTTokenType* iTokenType; -} - -MCTToken* CSimpleToken::NewL(MCTTokenType* aTokenType) - { - CDummyTokenClient* self = new (ELeave) CSimpleTokenType(aTokenType); - return static_cast<MCTToken*>(self); - } - - CSimpleToken::CSimpleToken(MCTTokenType* aTokenType) - : iTokenType(aTokenType), - { - } - - MCTTokenType& CSimpleToken::TokenType() - { - return *iTokenType; - } - const TDesC& CSimpleToken::Label() - { - return KTokenString(); - } - TCTTokenHandle CSimpleToken::Handle() - { - return (TCTTokenHandle(iTokenType->Type(), 0)); - } -// Create token type -TUid tokenUid = 0x103478; -CCTTokenType* tokenType = CCTTokenType(tokenUid,iFs); -CleanupReleasePushL(*tokenType); - -// Open the token -MCTToken* token = NULL; -tokenType.openToken(KTokenString, token, iStatus); -. -. -. -//The certificate label -HBufC* iCertLabel = HBufC::NewL(20); -_LIT(KTxtLabel,"CertificateLabel2"); -*iCertLabel = KTxtLabel; - -//The certificate format -TCertificateFormat icertFormat = EX968Certificate; - -//The certificate owner type -TCertificateOwnerType iCertOwnerType = EUserCertificate; - -//The certificate's subject key id and issuer key id fields -TKeyIdentifier* aSubjectKeyId = NULL; -TKeyIdentifier* aIssuerKeyId = NULL; - -//The certificate ID -const TInt KCertificateId = 0x00001234; - -//iCertInfo is a CCTCertInfo object that points to the certificate to be removed -CCTCertInfo* iCertInfo = CCTCertInfo::NewLC(*iCertLabel, icertFormat, iCertOwnerType, 999, aSubjectKeyId, aIssuerKeyId, token, KCertificateId, ETrue); - - -//Remove the certificate -ustore->Remove(iCertInfo, iStatus); -CleanupStack::PopAndDestroy(2, tokenType); -

Finding certificates

You -can specify filter criteria like certificate format, certificate owner type -and so on to find a particular set of certificates from the certificate store. -The following steps explain the process of finding certificates:

Specify a filter object -for the certificates to be returned.
Specify the filter criteria -for returning a specific category of certificates.
Use the CUnifiedCertStore::List() function -to list the filtered certificates.

The following code snippet explains how to find certificates in a -certificate store:

-//Create and initialize the Unified Certificate Store -. -. -. - -RPointerArray<CCTCertInfo> iCerts; //This variable will contain the certificates found - -//Specify filter object for the certificates -CCertAttributeFilter& iCertFilter; -iCertFilter = CCertAttributeFilter::NewL(); - - -//Specify the filter criteria -iCertFilter->SetFormat(EWTLSCertificate); -iCertFilter->SetOwnerType(ECACertificate); - - -//List the certificates based on the filter criteria -iCertStore->List(iCerts, iCertFilter, iStatus); -

Retrieving -certificate as a parsed object

You can retrieve a certificate as -a parsed object only in case of X.509 or -Wireless Transport Layer Security (WTLS) certificates. This method of retrieval -does not work for URL certificates.

Use the CUnifiedCertStore::Retrieve() function -to retrieve the certificate as a parsed object.

The following code -snippet explains how to retrieve a certificate as a parsed object:

-//Create and initialize the Unified Certificate Store -. -. -. - -//Retrieve the certificate - -//iCertInfo is a CCTCertInfo object that points to the certificate to be retrieved -//iCert contains the returned certificate - -iCertStore->Retrieve(iCertInfo, iCert, iStatus); -

Retrieving -certificate details

You can retrieve Abstract Syntax Notation One -(ASN.1) encoded certificate data from the certificate store. The certificate -data is returned as an ASN.1-encoded string.

Use the CUnifiedCertStore::Retrieve() function -to retrieve the certificate details. Unlike the function used to retrieve -a certificate as a parsed object, this function also accepts a buffer object -to hold the details of the certificate that is being retrieved.

The -following code snippet explains how to retrieve details of a specific certificate:

-//Create and initialize the Unified Certificate Store -. -. -. - -//Retrieve the certificate details - -//iCertInfo is a CCTCertInfo object that points to the certificate to be retrieved -//iCertData is an HBufC8* buffer that holds certificate data - -iCertStore->Retrieve(iCertInfo, iCertData->Des(), iStatus); -

Managing applicability -and trust settings

The trust status of a certificate indicates -if it can be considered as a trust anchor for validating any application. -This status is valid only for certificates issued by the Certificate Authority -(CA). The applicability settings of a certificate indicate the applications -for which the trust status is valid.

The Unified Certificate Store -API provides the following functions to get and set the applicability and -trust settings for certificates:

- - - -Function -Description - - - - -

Applications()

Gets a list of application UIDs for a certificate

- - -

IsApplicable()

Determines whether a certificate has a specific application UID

- - -

Trusted()

Determines whether a certificate is trusted

- - -

SetApplicability()

Sets the list of application UIDs

- - -

SetTrust()

Sets the trust flag.

- - - -

Setting applicability and trust settings

You can -change the existing applicability and trust settings of a certificate. The -details are as follows:

Set applicability: Specify -a CCTCertInfo object for the certificate, an array for containing -the new applicability settings and a request status object that will contain -the result of the applicability setting operation when complete. Pass these -as parameters to the CUnifiedCertStore::SetApplicability() function -and apply the settings.
Set trust: Specify -a CCTCertInfo object for the certificate, a TBool object -to decide if the certificate is to be trusted (ETrue if trusted -and EFalse if not) and a request status object that will -contain the result of the trust setting operation when complete. Pass these -as parameters to the CUnifiedCertStore::SetTrust() function -and apply the trust settings.

The following code snippet explains how to set the applicability -and trust settings for a certificate:

-//Create and initialize the Unified Certificate Store -. -. -. - -//Parameters for applicability and trust settings - -RArray<TUid> iApplications; //The applicability settings -TBool iTrustStatus = ETrue; //The trust setting - -//Set Applicability - -//iCertInfo is a CCTCertInfo object that points to the certificate whose applicability and trust settings are to be updated - -iCertStore->SetApplicability(iCertInfo, iApplications, iStatus); - -//Set Trust - -iCertStore->SetTrust(iCertInfo, iTrustStatus, iStatus); -

Getting applicability and trust settings

You -can determine whether a certificate is trusted as well as get a list of application -UIDs for a certificate. The details are as follows:

Get applicability: Specify -a CCTCertInfo object for the certificate, an array for containing -applicability settings (Application UIDs pertaining to the certificate) and -a request status object that will contain the result of getting the applicability -settings when the operation is complete. Pass these as parameters to the CUnifiedCertStore::Applications() function.
Get trust: Specify -a CCTCertInfo object for the certificate, a TBool object -that returns the trust status of the certificate (ETrue if -trusted and EFalse if not) and a request status object that -will contain the trust settings. Pass these as parameters to the CUnifiedCertStore::Trusted() function.

The following code snippet explains how to get the applicability -and trust settings for a certificate:

-//Create and initialize the Unified Certificate Store -. -. -. -//Get Applicability - -//iCertInfo is a CCTCertInfo object that points to the certificate whose applicability and trust settings are to be updated -//iApplications is an RArray<TUid> that returns the application UIDs for the certificate - -iCertStore->Applications(iCertInfo, iApplications, iStatus); - -//Get Trust -//iTrustStatus is a TBool returns the trust status of a certificate - -iCertStore->Trusted(iCertInfo, iTrustStatus, iStatus); -

-Unified Certificate -Store Overview + + + + + +Unified +Certificate Store TutorialThe Unified Certificate Store is the single point of access for +client applications to access and manipulate certificate stores in the device. +This tutorial provides information on how you can use the Unified Certificate +Store to perform various certificate-manipulation operations. +

Procedure

Follow these steps to perform the various +certificate manipulation operations using the Unified Certificate Store:

Create an instance of +the Unified Certificate Store and initialize it.

You can create a +certificate store in read-only or writable mode. Operations like adding and +removing certificates can be performed when the certificate store is in writable +mode. Basic operations like listing certificates, retrieving certificate details, +viewing trust statuses of certificates can be performed when the certificate +store is in read-only mode.

The following steps explain the processing +of creating and initialising a Unified Certificate Store:
1. Create an instance of +the RFs class. Use the object created as a file system session.
2. Create an object of +type CUnifiedCertStore using CUnifiedCertStore::NewL() or CUnifiedCertStore::NewLC().
  
  Note:
  
  The value that you set for the Boolean variable aOpenForWrite decides +if you can open the certificate store in read-only or writable mode. Set the +value of the variable to:
  - ETrue to +open the certificate store with write access.
  - EFalse to +open the certificate store with read-only access.
3. Initialize the certificate +store and the member functions using the asynchronous function CUnifiedCertStore::Initialize().
The code snippet to create and initialize a Unified Certificate Store +is as follows:
+//Create a file system session object +RFs iFs; +iFS.connect(); +CleanupClosePushL(iFs); + + +//Create and initialize the Unified Certificate Store +CUnifiedCertStore* iCertStore = CUnifiedCertStore::NewL(iFs, ETrue); + +//iStatus is a TRequestStatus +iCertStore->Initialize(iStatus); +
Complete any of the +following tasks as per your requirement:
- Adding certificates
- Removing certificates
- Finding certificates
- Retrieving certificate as a parsed object
- Retrieving certificate details
- Managing applicability and trust settings for certificates

Adding certificates

Before +adding a certificate, it is essential to determine the certificate store to +which the certificate will be added.

The following steps explain the +process of retrieving the certificate store by specifying an appropriate index +value and then adding a certificate to the particular store:

Create an object of +a writable certificate store using MCTWritableCertStore and +retrieve the certificate store to which the certificate will be added.
Specify the details +of the certificate to be added and include it to the selected store using MCTWritableCertStore::Add().

The following code snippet explains how to add a certificate to the +certificate store:

Removing certificates

Specify +details of the certificate to be removed and then remove it from the certificate +store. The following steps provide the require details:

Create an object of +a writable certificate store using MCTWritableCertStore and +retrieve the certificate store from which the certificate will be removed.
Create a CCTCertInfo object +of the certificate to be removed. Pass this to the CUnifiedCertStore::Remove() function +to remove the particular certificate from the certificate store.

The following code snippet explains how to remove a certificate from +the certificate store:

+//Create and initialize the Unified Certificate Store +. +. +. + +//Create an object of the writable certificate store + +//Retrieve the certificate store present at the specified index +//If the certificate store index is invalid +//or the specified certificate store cannot be opened +//then the store object is NULL + +MCTWritableCertStore& ustore = iCertStore->iWritableCertStore(0); +. +. +. +//Create a CCTCertInfo object for the certificate to be removed + +//Instantiate a token + +_LIT(KTokenString,"certtoken"); + +class CSimpleToken:: public CBase,public MCTToken +{ +public: + static MCTToken* NewL(MCTTokenType* aTokenType); + +public: // From MCTToken + MCTTokenType& TokenType(); + const TDesC& Label(); + TCTTokenHandle Handle(); + +private: + MCTTokenType* iTokenType; +} + +MCTToken* CSimpleToken::NewL(MCTTokenType* aTokenType) + { + CDummyTokenClient* self = new (ELeave) CSimpleTokenType(aTokenType); + return static_cast<MCTToken*>(self); + } + + CSimpleToken::CSimpleToken(MCTTokenType* aTokenType) + : iTokenType(aTokenType), + { + } + + MCTTokenType& CSimpleToken::TokenType() + { + return *iTokenType; + } + const TDesC& CSimpleToken::Label() + { + return KTokenString(); + } + TCTTokenHandle CSimpleToken::Handle() + { + return (TCTTokenHandle(iTokenType->Type(), 0)); + } +// Create token type +TUid tokenUid = 0x103478; +CCTTokenType* tokenType = CCTTokenType(tokenUid,iFs); +CleanupReleasePushL(*tokenType); + +// Open the token +MCTToken* token = NULL; +tokenType.openToken(KTokenString, token, iStatus); +. +. +. +//The certificate label +HBufC* iCertLabel = HBufC::NewL(20); +_LIT(KTxtLabel,"CertificateLabel2"); +*iCertLabel = KTxtLabel; + +//The certificate format +TCertificateFormat icertFormat = EX968Certificate; + +//The certificate owner type +TCertificateOwnerType iCertOwnerType = EUserCertificate; + +//The certificate's subject key id and issuer key id fields +TKeyIdentifier* aSubjectKeyId = NULL; +TKeyIdentifier* aIssuerKeyId = NULL; + +//The certificate ID +const TInt KCertificateId = 0x00001234; + +//iCertInfo is a CCTCertInfo object that points to the certificate to be removed +CCTCertInfo* iCertInfo = CCTCertInfo::NewLC(*iCertLabel, icertFormat, iCertOwnerType, 999, aSubjectKeyId, aIssuerKeyId, token, KCertificateId, ETrue); + + +//Remove the certificate +ustore->Remove(iCertInfo, iStatus); +CleanupStack::PopAndDestroy(2, tokenType); +

Finding certificates

You +can specify filter criteria like certificate format, certificate owner type +and so on to find a particular set of certificates from the certificate store. +The following steps explain the process of finding certificates:

Specify a filter object +for the certificates to be returned.
Specify the filter criteria +for returning a specific category of certificates.
Use the CUnifiedCertStore::List() function +to list the filtered certificates.

The following code snippet explains how to find certificates in a +certificate store:

+//Create and initialize the Unified Certificate Store +. +. +. + +RPointerArray<CCTCertInfo> iCerts; //This variable will contain the certificates found + +//Specify filter object for the certificates +CCertAttributeFilter& iCertFilter; +iCertFilter = CCertAttributeFilter::NewL(); + + +//Specify the filter criteria +iCertFilter->SetFormat(EWTLSCertificate); +iCertFilter->SetOwnerType(ECACertificate); + + +//List the certificates based on the filter criteria +iCertStore->List(iCerts, iCertFilter, iStatus); +

Retrieving +certificate as a parsed object

You can retrieve a certificate as +a parsed object only in case of X.509 or +Wireless Transport Layer Security (WTLS) certificates. This method of retrieval +does not work for URL certificates.

Use the CUnifiedCertStore::Retrieve() function +to retrieve the certificate as a parsed object.

The following code +snippet explains how to retrieve a certificate as a parsed object:

+//Create and initialize the Unified Certificate Store +. +. +. + +//Retrieve the certificate + +//iCertInfo is a CCTCertInfo object that points to the certificate to be retrieved +//iCert contains the returned certificate + +iCertStore->Retrieve(iCertInfo, iCert, iStatus); +

Retrieving +certificate details

You can retrieve Abstract Syntax Notation One +(ASN.1) encoded certificate data from the certificate store. The certificate +data is returned as an ASN.1-encoded string.

Use the CUnifiedCertStore::Retrieve() function +to retrieve the certificate details. Unlike the function used to retrieve +a certificate as a parsed object, this function also accepts a buffer object +to hold the details of the certificate that is being retrieved.

The +following code snippet explains how to retrieve details of a specific certificate:

+//Create and initialize the Unified Certificate Store +. +. +. + +//Retrieve the certificate details + +//iCertInfo is a CCTCertInfo object that points to the certificate to be retrieved +//iCertData is an HBufC8* buffer that holds certificate data + +iCertStore->Retrieve(iCertInfo, iCertData->Des(), iStatus); +

Managing applicability +and trust settings

The trust status of a certificate indicates +if it can be considered as a trust anchor for validating any application. +This status is valid only for certificates issued by the Certificate Authority +(CA). The applicability settings of a certificate indicate the applications +for which the trust status is valid.

The Unified Certificate Store +API provides the following functions to get and set the applicability and +trust settings for certificates:

+ + + +Function +Description + + + + +

Applications()

Gets a list of application UIDs for a certificate

+ + +

IsApplicable()

Determines whether a certificate has a specific application UID

+ + +

Trusted()

Determines whether a certificate is trusted

+ + +

SetApplicability()

Sets the list of application UIDs

+ + +

SetTrust()

Sets the trust flag.

+ + + +

Setting applicability and trust settings

You can +change the existing applicability and trust settings of a certificate. The +details are as follows:

Set applicability: Specify +a CCTCertInfo object for the certificate, an array for containing +the new applicability settings and a request status object that will contain +the result of the applicability setting operation when complete. Pass these +as parameters to the CUnifiedCertStore::SetApplicability() function +and apply the settings.
Set trust: Specify +a CCTCertInfo object for the certificate, a TBool object +to decide if the certificate is to be trusted (ETrue if trusted +and EFalse if not) and a request status object that will +contain the result of the trust setting operation when complete. Pass these +as parameters to the CUnifiedCertStore::SetTrust() function +and apply the trust settings.

The following code snippet explains how to set the applicability +and trust settings for a certificate:

+//Create and initialize the Unified Certificate Store +. +. +. + +//Parameters for applicability and trust settings + +RArray<TUid> iApplications; //The applicability settings +TBool iTrustStatus = ETrue; //The trust setting + +//Set Applicability + +//iCertInfo is a CCTCertInfo object that points to the certificate whose applicability and trust settings are to be updated + +iCertStore->SetApplicability(iCertInfo, iApplications, iStatus); + +//Set Trust + +iCertStore->SetTrust(iCertInfo, iTrustStatus, iStatus); +

Getting applicability and trust settings

You +can determine whether a certificate is trusted as well as get a list of application +UIDs for a certificate. The details are as follows:

Get applicability: Specify +a CCTCertInfo object for the certificate, an array for containing +applicability settings (Application UIDs pertaining to the certificate) and +a request status object that will contain the result of getting the applicability +settings when the operation is complete. Pass these as parameters to the CUnifiedCertStore::Applications() function.
Get trust: Specify +a CCTCertInfo object for the certificate, a TBool object +that returns the trust status of the certificate (ETrue if +trusted and EFalse if not) and a request status object that +will contain the trust settings. Pass these as parameters to the CUnifiedCertStore::Trusted() function.

The following code snippet explains how to get the applicability +and trust settings for a certificate:

+//Create and initialize the Unified Certificate Store +. +. +. +//Get Applicability + +//iCertInfo is a CCTCertInfo object that points to the certificate whose applicability and trust settings are to be updated +//iApplications is an RArray<TUid> that returns the application UIDs for the certificate + +iCertStore->Applications(iCertInfo, iApplications, iStatus); + +//Get Trust +//iTrustStatus is a TBool returns the trust status of a certificate + +iCertStore->Trusted(iCertInfo, iTrustStatus, iStatus); +

+Unified Certificate +Store Overview

\ No newline at end of file