epoc32/include/x509certchain.h
author William Roberts <williamr@symbian.org>
Tue, 16 Mar 2010 16:12:26 +0000 (2010-03-16)
branchSymbian2
changeset 2 2fe1408b6811
parent 0 061f57f2323e
child 4 837f303aceeb
permissions -rw-r--r--
Final list of Symbian^2 public API header files
     1 /*
     2 * Copyright (c) 1998-2009 Nokia Corporation and/or its subsidiary(-ies).
     3 * All rights reserved.
     4 * This component and the accompanying materials are made available
     5 * under the terms of the License "Eclipse Public License v1.0"
     6 * which accompanies this distribution, and is available
     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".
     8 *
     9 * Initial Contributors:
    10 * Nokia Corporation - initial contribution.
    11 *
    12 * Contributors:
    13 *
    14 * Description: 
    15 * X509 certificate chain and the validation status implementations
    16 *
    17 */
    18 
    19 
    20 
    21 
    22 /**
    23  @file 
    24  @publishedAll
    25  @released
    26 */
    27  
    28 #ifndef __X509CERTCHAIN_H__
    29 #define __X509CERTCHAIN_H__
    30 
    31 #include <e32std.h>
    32 #include <x509cert.h>
    33 #include <ct.h>
    34 
    35 class TValidationStatus
    36 /** The validation status.
    37 * 
    38 * Some errors cannot be blamed on any single certificate, in which case the 
    39 * iCert value is meaningless. The same structure is used for errors and for 
    40 * warnings. 
    41 * 
    42 * @publishedAll
    43 * @released
    44 * @since v6.0 */
    45 	{
    46 public:
    47 	/** Creates a validation status object.	
    48 	* 
    49 	* @param aError	The error type that occurred when validating the certificate chain.
    50 	* @param aCert	The index number identifying the certificate that gave rise to 
    51 	* 				the error. */
    52 	IMPORT_C TValidationStatus(const TValidationError aError, const TInt aCert);
    53 	
    54 	/** The reason for the error. */
    55 	TValidationError iReason;
    56 	
    57 	/** The index number identifying the certificate that gave rise to the error. */
    58 	TInt iCert;
    59 	};
    60 
    61 class CX509CertChain : public CBase
    62 /** Abstract base class for X.509 certificate chain validation; 
    63 * derive from this to suit your profile.
    64 * 
    65 * @publishedAll
    66 * @released
    67 * @since v6.0 */
    68 	{
    69 public:
    70 	/** Gets the number of certificates in the chain.	
    71 	* 
    72 	* @return	The number of certificates in the chain. */
    73 	IMPORT_C TInt Count() const;
    74 	
    75 	/** Gets the certificate identified by the specified index.
    76 	* Note that Cert(Count()) corresponds to the root (if any)
    77 	* whilst Cert(0) corresponds to the outmost certificate in the chain.
    78 	*
    79 	* @param aIndex	The ordinal number representing the position of the certificate 
    80 	* 				within the chain.
    81 	* @return		The X.509 certificate at the specified index. */
    82 	IMPORT_C const CX509Certificate& Cert(TInt aIndex) const;
    83 	
    84 	/** Decodes the individual elements of the signed data to construct the certificates.
    85 	* 
    86 	* @param aBinaryData	The encoded binary representation.
    87 	* @return				The certificate objects. */
    88 	IMPORT_C CArrayPtrFlat<CX509Certificate>* CX509CertChain::DecodeCertsL(const TDesC8& aBinaryData);
    89 	
    90 	/** Destructor.
    91 	* 
    92 	* Frees all resources owned by the object, prior to its destruction. */
    93 	IMPORT_C ~CX509CertChain();
    94 
    95 	/** Tests whether the specified X.509 certificate chain is equal to this X.509 
    96 	* certificate chain.
    97 	* 
    98 	* @param aOther	The X.509 certificate chain to be compared.
    99 	* @return		ETrue, if the certificate chains are equal;EFalse, otherwise. */
   100 	IMPORT_C TBool IsEqualL(const CX509CertChain& aOther) const;
   101 protected:
   102 	//certificate chain
   103 	CArrayPtrFlat<CX509Certificate>* iChain;
   104 private:
   105 	static void CleanupCertArray(TAny* aArray);
   106 	};
   107 	
   108 class CCertificateValidationWarnings : public CBase
   109 	/** Encapsulates the critical extensions encountered and any warnings found
   110 	* for a particular certificate in the chain during the process of validation.
   111 	* 
   112 	* @publishedAll
   113 	* @released
   114 	* @since v9.5 */
   115 		{
   116 	public:
   117 		/** Creates an instance of CCertificateValidationWarnings.
   118 		* 
   119 		* @param aIndex	The index of aCert in the certificate chain.
   120 		* @return	A pointer to the new CCertificateWarning object. */	
   121 		IMPORT_C static CCertificateValidationWarnings* NewL(TInt aIndex);
   122 
   123 		/** Creates an instance of CCertificateValidationWarnings.
   124 		* 
   125 		* @param aIndex	The index of aCert in the certificate chain.
   126 		* @return	A pointer to the new CCertificateWarning object. */	
   127 		IMPORT_C static CCertificateValidationWarnings* NewLC(TInt aIndex);		
   128 		
   129 		/** Gets a list of critical extension OIDs found in the certificate.
   130 		* 
   131 		* @return	An array of critical extensions found. */		
   132 		IMPORT_C const RPointerArray<TDesC>& CriticalExtensionsFound() const;
   133 		
   134 		/** Gets a list of warnings generated by the certificate.
   135 		* 
   136 		* @return	An array of warnings generated. */	
   137 		IMPORT_C const RArray<TValidationStatus>& Warnings() const;
   138 		
   139 		/** Gets the index of the certificate in the chain.
   140 		* 
   141 		* @return	The certificate index number. */		
   142 		IMPORT_C TInt CertIndex() const;
   143 		
   144 		/** Externalises an object of this class to a write stream.
   145 		* 
   146 		* The presence of this function means that the standard templated operator<<() 
   147 		* can be used to externalise objects of this class.
   148 		* 
   149 		* @param aStream    Stream to which the object should be externalised. */
   150 		IMPORT_C void ExternalizeL(RWriteStream& aStream) const;
   151 		
   152 		/** Internalises an object of this class from a read stream.
   153 		* 
   154 		* The presence of this function means that the standard templated operator>>() 
   155 		* can be used to internalise objects of this class.
   156 		* 
   157 		* Note that this function has assignment semantics: it replaces the old value 
   158 		* of the object with a new value read from the read stream. 
   159 		* 
   160 		* @param aStream    Stream from which the object should be internalised. 
   161 		* @return A pointer to the new CCertificateWarning object. */
   162 		IMPORT_C static CCertificateValidationWarnings* InternalizeL(RReadStream& aStream);
   163 		
   164 		/** The destructor.
   165 		* 
   166 		* Frees all resources owned by the object. */
   167 		IMPORT_C ~CCertificateValidationWarnings();
   168 		
   169 	public:
   170 		/** Adds a warning.
   171 		* 
   172 		* @internalComponent
   173 		* @released */
   174 		IMPORT_C void AppendWarningL(TValidationStatus aWarning);
   175 		
   176 		/** Adds a critical extension OID warning.
   177 		* 
   178 		* @internalComponent
   179 		* @released */
   180 		IMPORT_C void AppendCriticalExtensionWarningL(TDesC& aCriticalExt);
   181 		
   182 	private:
   183 		CCertificateValidationWarnings(TInt aIndex);
   184 	
   185 	private:
   186 		TInt iCertIndex;
   187 		RPointerArray<TDesC> iCriticalExtsFound;
   188 		RArray<TValidationStatus> iWarnings;
   189 		};
   190 
   191 #endif