epoc32/include/wtlscert.h
author William Roberts <williamr@symbian.org>
Tue, 16 Mar 2010 16:12:26 +0000
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) 1997-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 *
    16 */
    17 
    18 
    19 
    20 
    21 /**
    22  @file 
    23  @internalAll 
    24 */
    25 
    26 #ifndef __WTLSCERT_H__
    27 #define __WTLSCERT_H__
    28 
    29 #include <e32base.h>
    30 #include <e32std.h>
    31 #include <s32std.h>
    32 #include <signed.h>
    33 #include <unifiedcertstore.h>
    34 #include <wtlsnames.h>
    35 
    36 
    37 class CRSAPublicKey;
    38 class CDSAPublicKey;
    39 class CDSASignature;
    40 class CDSAParameters;
    41 
    42 const TInt KWTLSCertMaxDataElements = 6;
    43 
    44 /**
    45  * @publishedAll
    46  * @released
    47  */
    48 class CWTLSRSASignatureResult : public CRSASignatureResult
    49 	{
    50 public:
    51 	IMPORT_C static CWTLSRSASignatureResult* NewL(const CAlgorithmIdentifier& aDigestAlgorithm, const TDesC8& aDigest);
    52 	IMPORT_C static CWTLSRSASignatureResult* NewLC(const CAlgorithmIdentifier& aDigestAlgorithm, const TDesC8& aDigest);
    53 	IMPORT_C virtual TBool VerifyL(const TDesC8& aResult);
    54 private:
    55 	void ConstructL(const CAlgorithmIdentifier& aDigestAlgorithm, const TDesC8& aDigest);
    56 	};
    57 
    58 /**
    59  * @publishedAll
    60  * @released
    61  */
    62 class TWTLSKeyFactory : public TKeyFactory
    63 	{
    64 public:
    65 	virtual CRSAPublicKey* RSAPublicKeyL(const TDesC8& aEncoding) const;
    66 	virtual CRSASignatureResult* RSASignatureResultL(const CAlgorithmIdentifier& aDigestAlgorithm, TDesC8& aDigest) const;
    67 	virtual CDSAPublicKey* DSAPublicKeyL(const CDSAParameters& aParams, const TDesC8& aEncoding) const;
    68 	virtual CDSASignature* DSASignatureL(const TDesC8& aEncoding) const;
    69 	virtual CDSAParameters* DSAParametersL(const TDesC8& aEncoding) const;
    70 	virtual CDSAPublicKey* DSAPublicKeyL(const TDesC8& aParamsEncoding, const TDesC8& aEncoding) const;
    71 	};
    72 
    73 /**
    74  * @publishedAll
    75  * @released
    76  */
    77 class CWTLSValidityPeriod : public CValidityPeriod
    78 	{
    79 public:
    80 	IMPORT_C static CWTLSValidityPeriod* NewL(const TDesC8& aBinaryData);
    81 	IMPORT_C static CWTLSValidityPeriod* NewLC(const TDesC8& aBinaryData);
    82 	IMPORT_C static CWTLSValidityPeriod* NewL(const TDesC8& aBinaryData, TInt& aPos);
    83 	IMPORT_C static CWTLSValidityPeriod* NewLC(const TDesC8& aBinaryData, TInt& aPos);
    84 private:
    85 	CWTLSValidityPeriod();
    86 	void ConstructL(const TDesC8& aBinaryData, TInt& aPos);
    87 	};
    88 
    89 /**
    90  * @publishedAll
    91  * @released
    92  */
    93 class CWTLSAlgorithmIdentifier : public CAlgorithmIdentifier
    94 	{
    95 public:
    96 	IMPORT_C static CWTLSAlgorithmIdentifier* NewL(const TDesC8& aBinaryData);
    97 	IMPORT_C static CWTLSAlgorithmIdentifier* NewLC(const TDesC8& aBinaryData);
    98 	IMPORT_C static CWTLSAlgorithmIdentifier* NewL(const TDesC8& aBinaryData, TInt& aPos);
    99 	IMPORT_C static CWTLSAlgorithmIdentifier* NewLC(const TDesC8& aBinaryData, TInt& aPos);
   100 private:
   101 	CWTLSAlgorithmIdentifier();
   102 	void ConstructL(const TDesC8& aBinaryData, TInt& aPos);
   103 	};
   104 
   105 /**
   106  * @publishedAll
   107  * @released
   108  */
   109 class CWTLSSigningAlgorithmIdentifier : public CSigningAlgorithmIdentifier
   110 	{
   111 public:
   112 	IMPORT_C static CWTLSSigningAlgorithmIdentifier* NewL(const TDesC8& aBinaryData);
   113 	IMPORT_C static CWTLSSigningAlgorithmIdentifier* NewLC(const TDesC8& aBinaryData);
   114 	IMPORT_C static CWTLSSigningAlgorithmIdentifier* NewL(const TDesC8& aBinaryData, TInt& aPos);
   115 	IMPORT_C static CWTLSSigningAlgorithmIdentifier* NewLC(const TDesC8& aBinaryData, TInt& aPos);
   116 private:
   117 	CWTLSSigningAlgorithmIdentifier();
   118 	void ConstructL(const TDesC8& aBinaryData, TInt& aPos);
   119 	};
   120 
   121 /**
   122  * @publishedAll
   123  * @released
   124  */
   125 class CWTLSSubjectPublicKeyInfo : public CSubjectPublicKeyInfo
   126 	{
   127 public:
   128 	IMPORT_C static CWTLSSubjectPublicKeyInfo* NewL(const TDesC8& aBinaryData);
   129 	IMPORT_C static CWTLSSubjectPublicKeyInfo* NewLC(const TDesC8& aBinaryData);
   130 	IMPORT_C static CWTLSSubjectPublicKeyInfo* NewL(const TDesC8& aBinaryData, TInt& aPos);
   131 	IMPORT_C static CWTLSSubjectPublicKeyInfo* NewLC(const TDesC8& aBinaryData, TInt& aPos);
   132 private:
   133 	CWTLSSubjectPublicKeyInfo();
   134 	void ConstructL(const TDesC8& aBinaryData, TInt& aPos);
   135 	};
   136 
   137 _LIT(KWTLSTCAType, " T");
   138 _LIT(KWTLSTCAValue, "ca");
   139 
   140 /**
   141  * @publishedAll
   142  * @released
   143  */
   144 class CWTLSCertificate : public CCertificate
   145 	{
   146 public:
   147 	enum	//enum values for encoded data element positions in tbsCert data structure
   148 		{	//these values are to be used as params to DataElementEncoding() function
   149 		EVersionNumber = 0,
   150 		EAlgorithmId = 1,
   151 		EIssuerName = 2,
   152 		EValidityPeriod = 3,
   153 		ESubjectName = 4,
   154 		ESubjectPublicKeyInfo = 5,
   155 		};
   156 		
   157 	/**
   158 	 * Creates a new CWTLSCertificate object from the specified buffer containing the binary coded representation.
   159 	 *
   160 	 * @param aBinaryData	The encoded binary representation.
   161 	 * @return				The new CWTLSCertificate object.
   162 	 */	
   163 	IMPORT_C static CWTLSCertificate* NewL(const TDesC8& aBinaryData);
   164 
   165 	/**
   166 	 * Creates a new CWTLSCertificate object from the specified buffer containing the binary coded representation,
   167 	 * and puts a pointer to it onto the cleanup stack.
   168 	 *
   169 	 * @param aBinaryData	The encoded binary representation.
   170 	 * @return				The new CWTLSCertificate object.
   171 	 */	
   172 	IMPORT_C static CWTLSCertificate* NewLC(const TDesC8& aBinaryData);
   173 
   174 	/**
   175 	 * Creates a new CWTLSCertificate object from the specified buffer containing the binary coded representation.
   176 	 *
   177 	 * @param aBinaryData	The encoded binary representation.
   178 	 * @param aPos			An offset into the descriptor, and is updated to the position at the end of the object.
   179 	 * @return				The new CWTLSCertificate object.
   180 	 */	
   181 	IMPORT_C static CWTLSCertificate* NewL(const TDesC8& aBinaryData, TInt& aPos);
   182 
   183 	/**
   184 	 * Creates a new CWTLSCertificate object from the specified buffer containing the binary coded representation,
   185 	 * and puts a pointer to it onto the cleanup stack.
   186 	 *
   187 	 * @param aBinaryData	The encoded binary representation.
   188 	 * @param aPos			An offset into the descriptor, and is updated to the position at the end of the object.
   189 	 * @return				The new CWTLSCertificate object.
   190 	 */	
   191 	IMPORT_C static CWTLSCertificate* NewLC(const TDesC8& aBinaryData, TInt& aPos);
   192 
   193 	/**
   194 	 * Creates a new CWTLSCertificate object from a stream.
   195 	 *
   196 	 * The stream must have been written using the corresponding ExternalizeL() function.
   197 	 *
   198 	 * @param aStream	The stream to be used as input.
   199 	 * @return			The new CWTLSCertificate object.
   200 	 */	
   201 	IMPORT_C static CWTLSCertificate* NewL(RReadStream& aStream);
   202 
   203 	/**
   204 	 * Creates a new CWTLSCertificate object from a stream,
   205 	 * and puts a pointer to it onto the cleanup stack.
   206 	 *
   207 	 * The stream must have been written using the corresponding ExternalizeL() function.
   208 	 *
   209 	 * @param aStream	The stream to be used as input.
   210 	 * @return			The new CWTLSCertificate object.
   211 	 */	
   212 	IMPORT_C static CWTLSCertificate* NewLC(RReadStream& aStream);
   213 
   214 	/**
   215 	 * Creates a new CWTLSCertificate object from an existing one in the certificate store.
   216 	 *
   217 	 * @param aCert	The certificate to be copied.
   218 	 * @return		The new CWTLSCertificate object.
   219 	 */	
   220 	IMPORT_C static CWTLSCertificate* NewL(const CWTLSCertificate& aCert);
   221 
   222 	/**
   223 	 * Creates a new CWTLSCertificate object from an existing one in the certificate store,
   224 	 * and puts a pointer to it onto the cleanup stack.
   225 	 *
   226 	 * @param aCert	The certificate to be copied.
   227 	 * @return		The new CWTLSCertificate object.
   228 	 */	
   229 	IMPORT_C static CWTLSCertificate* NewLC(const CWTLSCertificate& aCert);
   230 
   231 	/**
   232 	 * Destructor.
   233 	 *
   234 	 * Frees all resources owned by the object, prior to its destruction.
   235 	 */
   236 	IMPORT_C ~CWTLSCertificate();
   237 	
   238 	/**
   239 	* Tests whether this WTLS certificate is the same as the specified WTLS certificate.
   240 	*
   241 	* This is not a simple as it sounds. For X.509 certificates equality means that the issuer name 
   242 	* and serial number fields are the same. This guarantees equality since a CA must ensure that every 
   243 	* certificate it issues has a unique serial number. But WTLS certificates do not include serial numbers, 
   244 	* so there seems to be no definition of equality. This function uses a byte-for-byte comparison of the 
   245 	* signatures on the certificates: this should not result in any false positives, but may give false 
   246 	* negatives if CAs do naughty things like recertifying the same key (which they have been known to do).
   247 	*
   248 	* @param aCert	A WTLS certificate
   249 	* @return		ETrue, if the parameter is the same certificate; EFalse, otherwise.
   250 	*/
   251 	IMPORT_C TBool IsEqualL(const CWTLSCertificate& aCert) const;
   252 	
   253 	//extra accessors
   254 	
   255 	/**
   256 	 * Gets the version number of the WTLS certificate.
   257 	 *
   258 	 * @return	The version number of the certificate. Always returns 1.
   259 	 */
   260 	IMPORT_C TInt Version() const;
   261 	
   262 	/**
   263 	 * Gets the name of the WTLS certificate's issuing authority.
   264 	 *
   265 	 * @return	A WTLS name:
   266 	 *			@li	If the name is an X.500 DN, then if the name contains a Common name, that will be returned. 
   267 	 * 				Otherwise, if the name contains an Organization name, that will be returned. Otherwise an empty 
   268 	 * 				string will be returned. 
   269 	 *			@li	If the name is of type text, then if the name is not a 'structured' name the entire string will 
   270 	 *				be returned, otherwise the same procedure will be followed as for X.509 certificates.
   271 	 * 			@li	If the name is null an empty string will be returned. 
   272 	 */
   273 	 // Unsupported -- If the name is a key hash or binary value the entire contents will be returned.
   274 	IMPORT_C const CWTLSName& IssuerName() const;
   275 	
   276 	/**
   277 	* Gets the name of the owner of the public key the WTLS certificate contains.
   278 	*
   279 	* @return A WTLS name.
   280 	*/
   281 	IMPORT_C const CWTLSName& SubjectName() const;
   282 	IMPORT_C virtual TBool IsSelfSignedL() const;
   283 	IMPORT_C virtual HBufC* SubjectL() const;
   284 	IMPORT_C virtual HBufC* IssuerL() const;
   285 	
   286 	/**
   287 	* Initialises the certificate from a stream. 
   288 	*
   289 	* This should not be called by client code; instead the static factory function above should be used. 
   290 	* If a client is using the certstore component for storage then it should use CCertStore::AddL() for 
   291 	* externalizing and CWTLSCert::NewL(CCertStore& aStore, const CCertStoreEntry& aEntry); for restoring.
   292 	*
   293 	* @param aStream 
   294 	*/
   295 	IMPORT_C void InternalizeL(RReadStream& aStream);
   296 	
   297 	/**
   298 	* Gets the certificate's signed data.
   299 	*
   300 	* @return	A non-modifiable pointer descriptor representing the certificate's signed data.
   301 	*/
   302 	IMPORT_C const TPtrC8 SignedDataL() const;
   303 	
   304 	/**
   305 	* Gets the encoding for a data element at the specified index.
   306 	*
   307 	* @param aIndex	The position of the encoded data element.
   308 	*/
   309 	IMPORT_C virtual const TPtrC8* DataElementEncoding(const TUint aIndex) const;
   310 	
   311 	/**
   312 	* Tests whether a non-selfsigned certificate can be used to sign others.
   313 	* 
   314 	* Currently this only supports structured text variety of WTLS certificates.  
   315 	* Other certificate types will return EFalse.
   316 	*
   317 	* @return	ETrue, if the certificate is capable of signing other certificates; otherwise, EFalse. 
   318 	*/
   319 	IMPORT_C TBool IsTCAL() const;
   320 private:
   321 	CWTLSCertificate();
   322 	void ConstructL(const TDesC8& aBinaryData, TInt& aPos);
   323 	void ConstructL(const CWTLSCertificate& aCertificate);
   324 	void ConstructCertL(const TDesC8& aBinaryData, TInt& aPos);
   325 	void InitEncodedDataElementsL();
   326 	//private data
   327 	TInt iVersion;
   328 	CWTLSName* iIssuerName;
   329 	CWTLSName* iSubjectName;
   330 	TFixedArray<TPtrC8*, KWTLSCertMaxDataElements>* iDataElements;
   331 	};
   332 
   333 #endif