How to use OSCP
===============

Note: The actual code snippets are indented.

Include ocsp.h in your header file.

	#include <ocsp.h>

Link your project with ocsp.lib: add the following string to your project's .mmp
file:

	LIBRARY ocsp.lib

Add the following to your class declaration, which should be derived from
CActive:

	COcspClient* iOcspClient;

You will need to know revocation server URI. It is possible to get it from
installer preferences. Most Software Install components accept the URI as a
construction parameter. This is because they are started by the UI which stores
preferences in its resource file. If you want to retrieve it yourself, you can
use the following code (taken from InstallEngineImpl.cpp):

	//	Open instapp's ini file
	static CDictionaryStore* OpenIniFileLC(RFs& aFs)
		{
		CApaAppFinder* appFinder=CApaScanningAppFinder::NewL(aFs);
		CleanupStack::PushL(appFinder);
		TUid instAppUid={KUidInstallAppValue};
		TFileName libName=appFinder->FindAppL(KInstallAppName,instAppUid);
		CleanupStack::PopAndDestroy(appFinder); 
		TParse parser;
		User::LeaveIfError(parser.SetNoWild(KIniFileExtension,&KInstAppDriveC(),
			&libName));
		aFs.MkDirAll(parser.FullName()); // ignore the error
		CDictionaryFileStore* dict = CDictionaryFileStore::OpenLC(aFs,
			parser.FullName(),instAppUid);
		return dict;
		}

	// get preferences from ini file
	{
	RFs fs;
	User::LeaveIfError(fs.Connect());
	CleanupClosePushL(fs);
	CDictionaryStore* iniFile=OpenIniFileLC(fs); // see above
	User::LeaveIfNull(iniFile);
	RDictionaryReadStream readStream;
	readStream.OpenLC(*iniFile,KUidInstallPrefs);
	TInstallPrefs prefs; // this is what you need
	TRAPD(ret,readStream >> prefs);   // will return KErrEof first time
	CleanupStack::PopAndDestroy(2); //readStream, iniFile
	CleanupStack::Pop(); // fs 
	fs.Close();
	}

If at any time you want to cancel OCSP check, call

	iOcspClient->CancelCheck();

When ready to perform the check (the certificate chain is built), use the
following code as a template (from JavaInstallerSecurityManager.cpp):

	COCSPParameters* params = COCSPParameters::NewLC();
	params->SetURIL(*iOCSPServerURI, ETrue);
	params->AddCertificatesL(*iCertChain);
	
	// Set up authorisation scheme - we've a special UID registered with the
	// certStore for the appropriate certificates
	COCSPDirectAuthorisationScheme* scheme = 
		COCSPDirectAuthorisationScheme::NewLC(
		TUid::Uid(KCertStoreUIDForSWInstallOCSPSigning));
	params->AddAuthorisationSchemeL(scheme);
	CleanupStack::Pop(scheme);
   		
	// Won't set validation time - this uses the response producedAt time
	// instead. This avoids us relying on an accurate time in the device.
	// Caching of old responses avoided by use of the nonce.

	iOcspClient = COcspClient::NewL(params);
	CleanupStack::Pop(params);
	iOcspClient->Check(iStatus);

When the request completes and your class's RunL() is called, use the following
function template to process the result:

	TBool accept = ETrue;
	switch (iStatus.Int())
		{
		case OCSP::KErrNoCertificates:
			// No certs in OCSP request - no proper cert chain formed.
			// Covered by check digital sig logic already, so we let it pass.
			break;
		case KErrNone:
		    {
			// Check the outcome of every transaction made
			for (TInt index = 0; 
				accept && index < iOcspClient->TransactionCount(); 
				++index)
				{
				const TOCSPOutcome& outcome = iOcspClient->Outcome(index);

				// We have the OCSP response.  Interpret it, asking the user
				// what questions we need to.  Return determines whether we
				// continue the install
				switch (outcome.iStatus)
					{
					case OCSP::ETransportError:
					case OCSP::EClientInternalError:
					case OCSP::EMalformedRequest:
					case OCSP::EServerInternalError:
					case OCSP::ETryLater:
					case OCSP::ESignatureRequired:
					case OCSP::EClientUnauthorised:
					case OCSP::EUnknownResponseType:
						// Error: unable to obtain certificate status
						break;
					case OCSP::ENoServerSpecified:
					case OCSP::EInvalidURI:
						// Error: invalid revocation server URI
						break;
					case OCSP::EResponseSignatureValidationFailure:
						// Error: response signature validation failed
						break;
					case OCSP::EThisUpdateTooLate:
					case OCSP::EThisUpdateTooEarly:
					case OCSP::ENextUpdateTooEarly:
					case OCSP::ENonceMismatch:
					case OCSP::EMalformedResponse:
					case OCSP::EUnknownCriticalExtension:
					case OCSP::EMissingCertificates:
						// Error: invalid server response
						break;
					case OCSP::EMissingNonce:
						// Error: missing nonce
						break;
					case OCSP::ECertificateNotValidAtValidationTime:
						// Error: invalid certificate status information
						break;
					case OCSP::EValid:
						switch(outcome.iResult)
							{
							case OCSP::EGood:
								accept = ETrue;
								break;
							case OCSP::EUnknown:
								// ask user
								break;
							case OCSP::ERevoked:
								// ask user
								break;
							default:
								ASSERT(EFalse);
							}
						break;
					default:
						ASSERT(EFalse);
						break;
					}
				}	
			break;
			}
		default:
			// Error: cannot obtain certificate status, ask user
			break;
		}

	delete iOcspClient;
	iOcspClient = NULL;

OCSP check can take a long time. Therefore it is a good thing to display a
status dialog for the user telling her that OCSP check is in progress and
allowing her to cancel it. Both SIS and Java installers delegate this function
to their respective UI handlers.