epoc32/include/wtlsnames.h
author William Roberts <williamr@symbian.org>
Wed, 31 Mar 2010 12:33:34 +0100
branchSymbian3
changeset 4 837f303aceeb
parent 2 2fe1408b6811
permissions -rw-r--r--
Current Symbian^3 public API header files (from PDK 3.0.h)
This is the epoc32/include tree with the "platform" subtrees removed, and
all but a selected few mbg and rsg files removed.
williamr@2
     1
/*
williamr@2
     2
* Copyright (c) 1997-2009 Nokia Corporation and/or its subsidiary(-ies).
williamr@2
     3
* All rights reserved.
williamr@2
     4
* This component and the accompanying materials are made available
williamr@2
     5
* under the terms of the License "Eclipse Public License v1.0"
williamr@2
     6
* which accompanies this distribution, and is available
williamr@2
     7
* at the URL "http://www.eclipse.org/legal/epl-v10.html".
williamr@2
     8
*
williamr@2
     9
* Initial Contributors:
williamr@2
    10
* Nokia Corporation - initial contribution.
williamr@2
    11
*
williamr@2
    12
* Contributors:
williamr@2
    13
*
williamr@2
    14
* Description: 
williamr@2
    15
*
williamr@2
    16
*/
williamr@2
    17
williamr@2
    18
williamr@2
    19
williamr@2
    20
#if !defined (__WTLSNAMES_H__)
williamr@2
    21
#define __WTLSNAMES_H__
williamr@2
    22
williamr@2
    23
#include <e32base.h>
williamr@2
    24
#include <e32std.h>
williamr@2
    25
#include <x500dn.h>
williamr@2
    26
williamr@2
    27
/**
williamr@2
    28
@file
williamr@2
    29
This file contains the definition for class CWTLSName.
williamr@2
    30
williamr@4
    31
@publishedAll
williamr@4
    32
@released
williamr@2
    33
williamr@2
    34
enum { null(0), text(1), binary(2), key_hash_sha(254), x509_name(255)}
williamr@2
    35
	IdentifierType;
williamr@2
    36
williamr@2
    37
We only support text and x509_name as these are the only meaningful identifiers..
williamr@2
    38
x509_name is X.500 Distinguished Name, and should use our existing X.500 DN implementation.  
williamr@2
    39
williamr@2
    40
struct {
williamr@2
    41
		IdentifierType identifier_type;
williamr@2
    42
		select (identifier_type) {
williamr@2
    43
			case null: struct {};
williamr@2
    44
			case text:
williamr@2
    45
				CharacterSet character_set;
williamr@2
    46
				opaque name<1.. 2^8-1>;
williamr@2
    47
			case binary: opaque identifier<1..2^8-1>;
williamr@2
    48
			case key_hash_sha: opaque key_hash[20];
williamr@2
    49
			case x509_name: opaque distinguished_name<1..2^8-1>;
williamr@2
    50
		} 
williamr@2
    51
		Identifier;
williamr@2
    52
williamr@2
    53
uint16 CharacterSet;
williamr@2
    54
williamr@2
    55
This maps on to one of the IANA defined character sets. There are rather a lot
williamr@2
    56
of these.  We just support the text type, with either Latin1 or UTF8 encoding.
williamr@2
    57
*/
williamr@2
    58
williamr@2
    59
/**
williamr@2
    60
 * Enumerates the types of WTLS certificate name forms/identifiers.
williamr@2
    61
 * 
williamr@2
    62
 * Only text strings and X.500 Distinguished Names are currently supported.
williamr@2
    63
 * 
williamr@2
    64
 */
williamr@2
    65
enum 
williamr@2
    66
	{
williamr@2
    67
	/* Null */
williamr@2
    68
	EWTLSNull =			0x00,
williamr@2
    69
	/* Text string (Latin-1 or Unicode). 
williamr@2
    70
	 *
williamr@2
    71
	 * A text identifier consists of a 16-bit character set identifier; 
williamr@2
    72
	 * this represents the IANA-assigned character set number. */
williamr@2
    73
	EWTLSText =			0x01,
williamr@2
    74
	/* Binary identifier.
williamr@2
    75
	 *
williamr@2
    76
	 * Certificates of this type will be rejected.*/
williamr@2
    77
	EWTLSBinary =		0x02,
williamr@2
    78
	/* Key Hash SHA-1. 
williamr@2
    79
	 *
williamr@2
    80
	 * Certificates of this type will be rejected.*/
williamr@2
    81
	EWTLSKeyHashSha =	0xfe,
williamr@2
    82
	/* X.500 Distinguished Name. */
williamr@2
    83
	EWTLSX500DN =		0xff
williamr@2
    84
	};
williamr@2
    85
williamr@2
    86
typedef TUint8 TWTLSNameType;
williamr@2
    87
williamr@2
    88
typedef TInt TWTLSCharSet;
williamr@2
    89
williamr@2
    90
// MIBenum constants from the IANA list of character sets.
williamr@2
    91
// See http://www.iana.org/assignments/character-sets for more info.
williamr@2
    92
williamr@2
    93
/** MIBenum constant for the Latin1 IANA character set */
williamr@2
    94
const TInt KWTLSLatin1CharSet = 4;
williamr@2
    95
williamr@2
    96
/** MIBenum constant for the UTF-8 IANA character set */
williamr@2
    97
const TInt KWTLSUTF8CharSet = 106;
williamr@2
    98
williamr@2
    99
class CWTLSName : public CBase
williamr@2
   100
/**
williamr@2
   101
 * Stores the type of a WTLS name and the underlying encoding of the type.
williamr@2
   102
 *
williamr@2
   103
 */
williamr@2
   104
	{
williamr@2
   105
public:
williamr@2
   106
	/**
williamr@2
   107
	 * Creates a new CWTLSName object from the specified buffer containing the binary coded representation.
williamr@2
   108
	 *
williamr@2
   109
	 * @param aBinaryData	The encoded binary representation.
williamr@2
   110
	 * @return				The new CWTLSName object.
williamr@2
   111
	 */
williamr@2
   112
	IMPORT_C static CWTLSName* NewL(const TDesC8& aBinaryData);
williamr@2
   113
williamr@2
   114
	/**
williamr@2
   115
	 * Creates a new CWTLSName object from the specified buffer containing the binary coded representation,
williamr@2
   116
	 * and puts a pointer to it onto the cleanup stack.
williamr@2
   117
	 *
williamr@2
   118
	 * @param aBinaryData	The encoded binary representation.
williamr@2
   119
	 * @return				The new CWTLSName object.
williamr@2
   120
	 */
williamr@2
   121
	IMPORT_C static CWTLSName* NewLC(const TDesC8& aBinaryData);
williamr@2
   122
	
williamr@2
   123
	/**
williamr@2
   124
	 * Creates a new CWTLSName object from the specified buffer containing the binary coded representation, 
williamr@2
   125
	 * starting at the specified offset.
williamr@2
   126
	 *
williamr@2
   127
	 * @param aBinaryData	The encoded binary representation.
williamr@2
   128
	 * @param aPos			The offset position from which to start decoding. It specifies an offset into the descriptor, 
williamr@2
   129
	 *						and is updated to the position at the end of the object.
williamr@2
   130
	 * @return				The new CWTLSName object.
williamr@2
   131
	 */
williamr@2
   132
	IMPORT_C static CWTLSName* NewL(const TDesC8& aBinaryData, TInt& aPos);
williamr@2
   133
williamr@2
   134
	/**
williamr@2
   135
	 * Creates a new CWTLSName object from the specified buffer containing the binary coded representation, 
williamr@2
   136
	 * starting at the specified offset, and puts a pointer to it onto the cleanup stack.
williamr@2
   137
	 *
williamr@2
   138
	 * @param aBinaryData	The encoded binary representation.
williamr@2
   139
	 * @param aPos			The offset position from which to start decoding. It specifies an offset into the descriptor, 
williamr@2
   140
	 *						and is updated to the position at the end of the object.
williamr@2
   141
	 * @return				The new CWTLSName object.
williamr@2
   142
	 */
williamr@2
   143
	IMPORT_C static CWTLSName* NewLC(const TDesC8& aBinaryData, TInt& aPos);
williamr@2
   144
williamr@2
   145
	/**
williamr@2
   146
	 * Creates a new CWTLSName object from an existing one.
williamr@2
   147
	 *
williamr@2
   148
	 * @param aName	An existing CWTLSName object.
williamr@2
   149
	 * @return		The new CWTLSName object.
williamr@2
   150
	 */
williamr@2
   151
	IMPORT_C static CWTLSName* NewL(const CWTLSName& aName);
williamr@2
   152
williamr@2
   153
	/**
williamr@2
   154
	 * Creates a new CWTLSName object from an existing one, 
williamr@2
   155
	 * and puts a pointer to it onto the cleanup stack.
williamr@2
   156
	 *
williamr@2
   157
	 * @param aName	An existing CWTLSName object.
williamr@2
   158
	 * @return		The new CWTLSName object.
williamr@2
   159
	 */
williamr@2
   160
	IMPORT_C static CWTLSName* NewLC(const CWTLSName& aName);	
williamr@2
   161
	
williamr@2
   162
	/**
williamr@2
   163
	 * Destructor.
williamr@2
   164
	 *
williamr@2
   165
	 * Frees all resources owned by the object, prior to its destruction.
williamr@2
   166
	 */
williamr@2
   167
	IMPORT_C ~CWTLSName(); 
williamr@2
   168
	
williamr@2
   169
	/**
williamr@2
   170
	 * Performs a simple byte compare between this WTLS name and a specified WTLS name.
williamr@2
   171
	 *
williamr@2
   172
	 * Needed for the constructing/validating of certificate chains.
williamr@2
   173
	 *
williamr@2
   174
	 * @param aName	An existing CWTLSName object.
williamr@2
   175
	 * @return		ETrue, if the WTLS names match; EFalse, otherwise.
williamr@2
   176
	 */	
williamr@2
   177
	IMPORT_C TBool ExactMatchL(const CWTLSName& aName) const;
williamr@2
   178
	
williamr@2
   179
	/** 
williamr@2
   180
	 * Gets the type of the WTLS name.
williamr@2
   181
	 *
williamr@2
   182
	 * @return	Type of WTLS name form.
williamr@2
   183
	 */	
williamr@2
   184
	IMPORT_C TWTLSNameType NameType() const;
williamr@2
   185
	
williamr@2
   186
	/** 
williamr@2
   187
	 * Gets the encoding of the underlying type of WTLS name.
williamr@2
   188
	 *
williamr@2
   189
	 * @return	Pointer descriptor representing the encoding of the WTLS name type.
williamr@2
   190
	 */	
williamr@2
   191
	IMPORT_C TPtrC8 NameData() const;
williamr@2
   192
	
williamr@2
   193
	/**
williamr@2
   194
	 * Gets the decoded value for the common or organisation name.
williamr@2
   195
	 *
williamr@2
   196
	 * Provides the functionality required by the CCertificate::IssuerL() and SubjectL() functions.
williamr@2
   197
	 *
williamr@2
   198
	 * @return A heap descriptor containing the decoded value of the common or organisation name.
williamr@2
   199
	 */
williamr@2
   200
	IMPORT_C HBufC* DisplayNameL() const;
williamr@2
   201
private:
williamr@2
   202
	CWTLSName();
williamr@2
   203
	void ConstructL(const TDesC8& aBinaryData, TInt& aPos);
williamr@2
   204
	void ConstructL(const CWTLSName& aName);
williamr@2
   205
	void AllocNameDataL(const TDesC8& aBinaryData, TInt& aPos);
williamr@2
   206
	void AllocTextDataL(const TDesC8& aBinaryData, TInt& aPos);
williamr@2
   207
	TWTLSNameType iNameType;
williamr@2
   208
	HBufC8* iNameData;
williamr@2
   209
	};
williamr@2
   210
williamr@2
   211
class CWTLSText : public CBase
williamr@2
   212
	{
williamr@2
   213
public:
williamr@2
   214
	/**
williamr@2
   215
	 * Creates a new CWTLSText object from the specified buffer containing the binary coded representation.
williamr@2
   216
	 *
williamr@2
   217
	 * @param aBinaryData	The encoded binary representation.
williamr@2
   218
	 * @return				The new CWTLSText object.
williamr@2
   219
	 */
williamr@2
   220
	IMPORT_C static CWTLSText* NewL(const TDesC8& aBinaryData);
williamr@2
   221
williamr@2
   222
	/**
williamr@2
   223
	 * Creates a new CWTLSText object from the specified buffer containing the binary coded representation,
williamr@2
   224
	 * and puts a pointer to it onto the cleanup stack.
williamr@2
   225
	 *
williamr@2
   226
	 * @param aBinaryData	The encoded binary representation.
williamr@2
   227
	 * @return				The new CWTLSText object.
williamr@2
   228
	 */
williamr@2
   229
	IMPORT_C static CWTLSText* NewLC(const TDesC8& aBinaryData);
williamr@2
   230
williamr@2
   231
	/**
williamr@2
   232
	 * Creates a new CWTLSText object from the specified buffer containing the binary coded representation, 
williamr@2
   233
	 * starting at the specified offset.
williamr@2
   234
	 *
williamr@2
   235
	 * @param aBinaryData	The encoded binary representation.
williamr@2
   236
	 * @param aPos			The offset position from which to start decoding. It specifies an offset into the descriptor, 
williamr@2
   237
	 *						and is updated to the position at the end of the object.
williamr@2
   238
	 * @return				The new CWTLSText object.
williamr@2
   239
	 */
williamr@2
   240
	IMPORT_C static CWTLSText* NewL(const TDesC8& aBinaryData, TInt& aPos);
williamr@2
   241
williamr@2
   242
	/**
williamr@2
   243
	 * Creates a new CWTLSText object from the specified buffer containing the binary coded representation, 
williamr@2
   244
	 * starting at the specified offset, and puts a pointer to it onto the cleanup stack.
williamr@2
   245
	 *
williamr@2
   246
	 * @param aBinaryData	The encoded binary representation.
williamr@2
   247
	 * @param aPos			The offset position from which to start decoding. It specifies an offset into the descriptor, 
williamr@2
   248
	 *						and is updated to the position at the end of the object.
williamr@2
   249
	 * @return				The new CWTLSText object.
williamr@2
   250
	 */
williamr@2
   251
	IMPORT_C static CWTLSText* NewLC(const TDesC8& aBinaryData, TInt& aPos);	
williamr@2
   252
	
williamr@2
   253
	/**
williamr@2
   254
	 * Destructor.
williamr@2
   255
	 *
williamr@2
   256
	 * Frees all resources owned by the object, prior to its destruction.
williamr@2
   257
	 */
williamr@2
   258
	IMPORT_C ~CWTLSText(); 	
williamr@2
   259
	
williamr@2
   260
	/**
williamr@2
   261
	 * Performs a simple byte compare between this CWTLSText object and a specified CWTLSText object.
williamr@2
   262
	 *
williamr@2
   263
	 * There is a subtle difference between this byte-match and CWTLSName::ExactMatchL().
williamr@2
   264
	 * As opposed to the latter, this function should successfully match two names that 
williamr@2
   265
	 * are the same that were encoded using different character sets.
williamr@2
   266
	 *
williamr@2
   267
	 * @param aName	An existing CWTLSText object.
williamr@2
   268
	 * @return		ETrue, if the CWTLSText objects match; EFalse, otherwise.
williamr@2
   269
	 */	
williamr@2
   270
	IMPORT_C TBool ExactMatchL(const CWTLSText& aName) const;	
williamr@2
   271
	
williamr@2
   272
	/**
williamr@2
   273
	 * Gets the name of the CWTLSText object.
williamr@2
   274
	 *
williamr@2
   275
	 * @return A pointer to the name of the CWTLSText object. 
williamr@2
   276
	 */
williamr@2
   277
	IMPORT_C TPtrC Name() const;
williamr@2
   278
	
williamr@2
   279
	/**
williamr@2
   280
	 * Gets the character set of the CWTLSText object.
williamr@2
   281
	 *
williamr@2
   282
	 * @return The character set
williamr@2
   283
	 */
williamr@2
   284
	IMPORT_C TWTLSCharSet CharacterSet() const;
williamr@2
   285
protected:
williamr@2
   286
	/** 
williamr@2
   287
	 * @internalAll
williamr@2
   288
	 */
williamr@2
   289
	CWTLSText();
williamr@2
   290
	/** 
williamr@2
   291
	 * @internalAll
williamr@2
   292
	 */
williamr@2
   293
	void ConstructL(const TDesC8& aBinaryData, TInt& aPos);
williamr@2
   294
	HBufC* iName;
williamr@2
   295
private:
williamr@2
   296
	TInt iCharacterSet;
williamr@2
   297
	};
williamr@2
   298
williamr@2
   299
//this class implements the 'structured' variant of the text type defined in the WTLS spec, section 10.5.2:
williamr@2
   300
//<servicename>; <organization>; <country>[; <commonname>[; <extension>[; <extension>[ …. ]]]]
williamr@2
   301
_LIT(KWTLSCountryName,"C");
williamr@2
   302
_LIT(KWTLSOrganizationName,"O");
williamr@2
   303
_LIT(KWTLSServiceName,"OU");
williamr@2
   304
_LIT(KWTLSTitle,"T");
williamr@2
   305
_LIT(KWTLSCommonName,"CN");
williamr@2
   306
williamr@2
   307
class TWTLSStructuredTextField 
williamr@2
   308
	{
williamr@2
   309
public:
williamr@2
   310
	/** 
williamr@2
   311
     * @internalAll
williamr@2
   312
     */
williamr@2
   313
	TWTLSStructuredTextField(const TDesC& aType, const TDesC& aValue);
williamr@2
   314
williamr@2
   315
	/**
williamr@2
   316
	 *
williamr@2
   317
	 * @return	
williamr@2
   318
	 */
williamr@2
   319
	IMPORT_C TPtrC Type() const;
williamr@2
   320
williamr@2
   321
	/**
williamr@2
   322
	 *
williamr@2
   323
	 * @return
williamr@2
   324
	 */
williamr@2
   325
	IMPORT_C TPtrC Value() const;
williamr@2
   326
williamr@2
   327
private:
williamr@2
   328
	const TPtrC iType;
williamr@2
   329
	const TPtrC iValue; 
williamr@2
   330
	};
williamr@2
   331
williamr@2
   332
class CWTLSStructuredText : public CWTLSText
williamr@2
   333
	{
williamr@2
   334
public:
williamr@2
   335
	/**
williamr@2
   336
	 * Creates a new CWTLSStructuredText object from the specified buffer containing the binary coded representation.
williamr@2
   337
	 *
williamr@2
   338
	 * @param aBinaryData	The encoded binary representation.
williamr@2
   339
	 * @return				The new CWTLSStructuredText object.
williamr@2
   340
	 */
williamr@2
   341
	IMPORT_C static CWTLSStructuredText* NewL(const TDesC8& aBinaryData);
williamr@2
   342
williamr@2
   343
	/**
williamr@2
   344
	 * Creates a new CWTLSStructuredText object from the specified buffer containing the binary coded representation,
williamr@2
   345
	 * and puts a pointer to it onto the cleanup stack.
williamr@2
   346
	 *
williamr@2
   347
	 * @param aBinaryData	The encoded binary representation.
williamr@2
   348
	 * @return				The new CWTLSStructuredText object.
williamr@2
   349
	 */
williamr@2
   350
	IMPORT_C static CWTLSStructuredText* NewLC(const TDesC8& aBinaryData);
williamr@2
   351
williamr@2
   352
	/**
williamr@2
   353
	 * Creates a new CWTLSStructuredText object from the specified buffer containing the binary coded representation, 
williamr@2
   354
	 * starting at the specified offset.
williamr@2
   355
	 *
williamr@2
   356
	 * @param aBinaryData	The encoded binary representation.
williamr@2
   357
	 * @param aPos			The offset position from which to start decoding. It specifies an offset into the descriptor, 
williamr@2
   358
	 *						and is updated to the position at the end of the object.
williamr@2
   359
	 * @return				The new CWTLSStructuredText object.
williamr@2
   360
	 */
williamr@2
   361
	IMPORT_C static CWTLSStructuredText* NewL(const TDesC8& aBinaryData, TInt& aPos);
williamr@2
   362
williamr@2
   363
	/**
williamr@2
   364
	 * Creates a new CWTLSStructuredText object from the specified buffer containing the binary coded representation, 
williamr@2
   365
	 * starting at the specified offset, and puts a pointer to it onto the cleanup stack.
williamr@2
   366
	 *
williamr@2
   367
	 * @param aBinaryData	The encoded binary representation.
williamr@2
   368
	 * @param aPos			The offset position from which to start decoding. It specifies an offset into the descriptor, 
williamr@2
   369
	 *						and is updated to the position at the end of the object.
williamr@2
   370
	 * @return				The new CWTLSStructuredText object.
williamr@2
   371
	 */
williamr@2
   372
	IMPORT_C static CWTLSStructuredText* NewLC(const TDesC8& aBinaryData, TInt& aPos);
williamr@2
   373
	
williamr@2
   374
	/**
williamr@2
   375
	 * Destructor.
williamr@2
   376
	 *
williamr@2
   377
	 * Frees all resources owned by the object, prior to its destruction.
williamr@2
   378
	 */
williamr@2
   379
	IMPORT_C ~CWTLSStructuredText(); 
williamr@2
   380
	
williamr@2
   381
	/**
williamr@2
   382
	 * 
williamr@2
   383
	 *
williamr@2
   384
	 * @return
williamr@2
   385
	 */
williamr@2
   386
	IMPORT_C HBufC* DisplayNameL() const;
williamr@2
   387
williamr@2
   388
	//accessors for defined fields
williamr@2
   389
	
williamr@2
   390
	/**
williamr@2
   391
	 *
williamr@2
   392
	 *
williamr@2
   393
	 * @return
williamr@2
   394
	 */
williamr@2
   395
	IMPORT_C TPtrC ServiceName() const;
williamr@2
   396
	
williamr@2
   397
	/**
williamr@2
   398
	 *
williamr@2
   399
	 *
williamr@2
   400
	 * @return
williamr@2
   401
	 */
williamr@2
   402
	IMPORT_C TPtrC Organization() const;
williamr@2
   403
	
williamr@2
   404
	/**
williamr@2
   405
	 *
williamr@2
   406
	 *
williamr@2
   407
	 * @return
williamr@2
   408
	 */
williamr@2
   409
	IMPORT_C TPtrC Country() const;
williamr@2
   410
	
williamr@2
   411
	/**
williamr@2
   412
	 *
williamr@2
   413
	 *
williamr@2
   414
	 * @return
williamr@2
   415
	 */
williamr@2
   416
	IMPORT_C TInt Count() const;
williamr@2
   417
williamr@2
   418
	
williamr@2
   419
	/**
williamr@2
   420
	 *
williamr@2
   421
	 *
williamr@2
   422
	 * Note 
williamr@2
   423
	 *
williamr@2
   424
	 * @param aType
williamr@2
   425
	 * @return	A pointer to a TWTLSStructuredTextField object; NULL if field not found. 
williamr@2
   426
	 *			The returned object remains the property of the structured text object
williamr@2
   427
	 *			(so don't delete it).
williamr@2
   428
	 */
williamr@2
   429
	IMPORT_C const TWTLSStructuredTextField* FieldByName(const TDesC& aType) const;
williamr@2
   430
	
williamr@2
   431
	/**
williamr@2
   432
	 *
williamr@2
   433
	 *
williamr@2
   434
	 * @return
williamr@2
   435
	 */
williamr@2
   436
	IMPORT_C const TWTLSStructuredTextField& FieldByIndex(TInt aIndex) const;
williamr@2
   437
private:
williamr@2
   438
	CWTLSStructuredText();
williamr@2
   439
	void ConstructL(const TDesC8& aBinaryData, TInt& aPos);
williamr@2
   440
	void AddFieldValueL(const TDesC& aFieldName, TInt& aPos);
williamr@2
   441
	void AddFieldL(TInt& aPos);
williamr@2
   442
	TPtrC GetFieldL(TDesC& aString, TInt& aPos);
williamr@2
   443
	TBool GetSubFieldL(TDesC& aString, TInt& aPos);
williamr@2
   444
	CArrayFixFlat<TWTLSStructuredTextField>* iFields; 
williamr@2
   445
	};
williamr@2
   446
williamr@2
   447
#endif
williamr@4
   448
williamr@4
   449