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 * Implementation of the class that holds the Distinguished Name of a subject

    16 *

    17 */

    18 

    19 

    20 

    21 

    22 /**

    23  @file 

    24  @publishedAll

    25  @released

    26 */

    27 #if !defined (__X500DN_H__)

    28 #define __X500DN_H__

    29 

    30 #include <e32base.h>

    31 #include <e32std.h>

    32 #include <s32file.h>

    33 #include <x520ava.h>

    34 

    35 class CX500DistinguishedName : public CBase

    36 /** Holds the Distinguished Name of a subject.

    37 *

    38 * A collection of 'attribute type and value' objects, as defined by the X.520 

    39 * standard.

    40 *

    41 * The name used in X.509 certificates is the X.500 Distinguished Name, which 

    42 * describes a path through an X.500 Directory Information Tree.

    43 *

    44 * A Distinguished Name is a series of name-value pairs that uniquely identify 

    45 * an entity, i.e. the certificate subject. 

    46 *

    47 * @publishedAll

    48 * @released

    49 *

    50 * <!-- 

    51 * This is necessary when working with certificates, certificate requests, directories, etc. 

    52 * -->

    53 */

    54 	{

    55 public:

    56 	/** Creates a new Distinguished Name object from the specified buffer containing 

    57 	* the encoded binary representation, starting at the specified offset.

    58 	* 

    59 	* @param aBinaryData	The encoded binary representation.

    60 	* @param aPos			The position from which to start decoding.

    61 	* @return				The new Distinguished Name object. */

    62 	IMPORT_C static CX500DistinguishedName* NewL(const TDesC8& aBinaryData, TInt& aPos);

    63 	

    64 	/** Creates a new Distinguished Name object from the specified buffer containing 

    65 	* the encoded binary representation, starting at the specified offset, and puts 

    66 	* a pointer to it onto the cleanup stack.

    67 	* 

    68 	* @param aBinaryData	The encoded binary representation.

    69 	* @param aPos			The position from which to start decoding.

    70 	* @return				The new Distinguished Name object. */

    71 	IMPORT_C static CX500DistinguishedName* NewLC(const TDesC8& aBinaryData, TInt& aPos);

    72 	

    73 	/** Creates a new Distinguished Name object from the specified buffer containing 

    74 	* the encoded binary representation.

    75 	* 

    76 	* Initialises the object from its encoded binary form into an internal representation.

    77 	* 

    78 	* @param aBinaryData	The encoded binary representation.

    79 	* @return				The new Distinguished Name object. */

    80 	IMPORT_C static CX500DistinguishedName* NewL(const TDesC8& aBinaryData);

    81 	

    82 	/** Creates a new Distinguished Name object from the specified buffer containing 

    83 	* the encoded binary representation, and puts a pointer to it onto the cleanup stack.

    84 	* 

    85 	* Initialises the object from its encoded binary form into an internal representation.

    86 	* 

    87 	* @param aBinaryData	The encoded binary representation.

    88 	* @return				The new Distinguished Name object. */

    89 	IMPORT_C static CX500DistinguishedName* NewLC(const TDesC8& aBinaryData);

    90 	

    91 	/** Creates a new Distinguished Name object from the specified read stream.

    92 	* 

    93 	* Construction is from a stream.

    94 	* 

    95 	* @param aStream	Stream from which the contents should be internalised.

    96 	* @return			The newDistinguished Name object. */

    97 	IMPORT_C static CX500DistinguishedName* NewL(RReadStream& aStream);

    98 	

    99 	/** Creates a new Distinguished Name object from the specified read stream, and 

   100 	* puts a pointer to it onto the cleanup stack.

   101 	* 

   102 	* @param aStream	Stream from which the contents should be internalised.

   103 	* @return			The new Distinguished Name object. */

   104 	IMPORT_C static CX500DistinguishedName* NewLC(RReadStream& aStream);	

   105 	

   106 	/** Creates a new Distinguished Name object from the specified array of 'attribute 

   107 	* type and value' objects.

   108 	* 

   109 	* The elements of the specified array are copied into this object.

   110 	* 

   111 	* @param aElements	The array of 'attribute type and value' objects to be copied.

   112 	* @return			The new Distinguished Name object. */

   113 	IMPORT_C static CX500DistinguishedName* NewL(const CArrayPtr<CX520AttributeTypeAndValue>& aElements);

   114 	

   115 	/** Creates a new Distinguished Name object from the specified array of 'attribute 

   116 	* type and value' objects, and puts a pointer to it onto the cleanup stack.

   117 	* 

   118 	* The elements of the specified array are copied into this object.

   119 	* 

   120 	* @param aElements	The array of 'attribute type and value' objects to be copied.

   121 	* @return			The new Distinguished Name object. */

   122 	IMPORT_C static CX500DistinguishedName* NewLC(const CArrayPtr<CX520AttributeTypeAndValue>& aElements);	

   123 	

   124 	/** Creates a new Distinguished Name object from an existing object.

   125 	* 

   126 	* This is equivalent to a copy constructor.

   127 	* 

   128 	* @param aName	The Distinguished Name object to be copied.

   129 	* @return		The new Distinguished Name object. */

   130 	IMPORT_C static CX500DistinguishedName* NewL(const CX500DistinguishedName& aName);

   131 	

   132 	/** Creates a new Distinguished Name object from an existing object, and puts a 

   133 	* pointer to it onto the cleanup stack.

   134 	* 

   135 	* This is equivalent to a copy constructor.

   136 	* 

   137 	* @param aName	The Distinguished Name object to be copied.

   138 	* @return		The new Distinguished Name object. */

   139 	IMPORT_C static CX500DistinguishedName* NewLC(const CX500DistinguishedName& aName);

   140 	

   141 	/** Externalises an object of this class to a write stream.

   142 	* 

   143 	* The presence of this function means that the standard templated operator<<() 

   144 	* can be used to externalise objects of this class.

   145 	* 

   146 	* @param aStream	Stream to which the object should be externalised. */

   147 	IMPORT_C void ExternalizeL(RWriteStream& aStream) const;

   148 	

   149 	/** Gets the number of 'attribute type and value' objects contained by this Distinguished 

   150 	* Name object.

   151 	* 

   152 	* @return	The number of 'attribute type and value' objects. */

   153 	IMPORT_C TInt Count() const;

   154 	

   155 	/** Gets a reference to specific 'attribute type and value' object as identified 

   156 	* by the specified index.

   157 	* 

   158 	* @param aIndex	The index number identifying the specific 'attribute type and 

   159 	* 				value' object. This number is relative to zero. This value must be non-negative 

   160 	* 				and less than the number of objects currently contained by this Distinguished 

   161 	* 				Name object.

   162 	* @return		The referenced 'attribute type and value' object. */

   163 	IMPORT_C const CX520AttributeTypeAndValue& Element(TInt aIndex) const;

   164 	

   165 	/** Destructor.

   166 	* 

   167 	* Frees all resources owned by the object, prior to its destruction. */

   168 	IMPORT_C ~CX500DistinguishedName(); 

   169 

   170 	/** Compares the specified Distinguished Name object with this Distinguished Name 

   171 	* object.

   172 	* 

   173 	* @param aName	The Distinguished Name object to be compared.

   174 	* @return		ETrue, if the Distinguished Name objects contain exactly the same 'attribute 

   175 	* 				type and value' objects; EFalse, otherwise.

   176 	* @see CX520AttributeTypeAndValue::ExactMatchL() 

   177 	*

   178 	* <!--	This function checks if all the fields of aName and 

   179 	*		iElements are the same but not necessarily in the same order. -->

   180 	*/

   181 	IMPORT_C TBool ExactMatchL(const CX500DistinguishedName& aName) const;

   182 

   183 	/** <!--

   184 	 // This function checks if the elements of iElements are a superset of

   185 	 // the fields in aName.

   186 	 // @param aName We want to check that the fields in aName are present in iElements.

   187 	 // @return 

   188 	 // <UL>

   189 	 // <LI>ETrue if all the fields in aName have a corresponding field in iElements.</LI>

   190 	 // <LI>EFalse otherwise</LI>

   191 	 // </UL>

   192 	 -->

   193 	* Tests whether all 'attribute type and value' objects contained in the specified 

   194 	* Distinguished Name object are also contained within this Distinguished Name object.

   195 	* 

   196 	* This function checks if the elements of iElements are a superset of the fields in aName.

   197 	* 

   198 	* @param aName	The Distinguished Name object to be compared.

   199 	* @return		ETrue, if all 'attribute type and value' objects contained in the specified 

   200 	* 				Distinguished Name object are also contained within this Distinguished Name 

   201 	* 				object; EFalse, otherwise. */

   202 	IMPORT_C TBool IsWithinSubtreeL(const CX500DistinguishedName& aName) const;

   203 

   204 	/** <!--

   205 	 // This function compares each of the elements in iElements with aElement. The comparison

   206 	 // is made by the CX520AttributeTypeAndValue::ExactMatchL function.

   207 	 // @param aElement The element which we want to compare the elements of iElements with.

   208 	 // @return 

   209 	 // <UL>

   210 	 // <LI>ETrue if one of the elements in iElements is equal to aElement.</LI>

   211 	 // <LI>EFalse otherwise</LI>

   212 	 // </UL>

   213 	 -->

   214 	* Tests whether this Distinguished Name object contains the specified 'attribute 

   215 	* type and value' object.

   216 	* 

   217 	* This function compares each of the elements in iElements with aElement. The comparison

   218 	* is made by the CX520AttributeTypeAndValue::ExactMatchL() function.

   219 	* 

   220 	* @param aElement	The 'attribute type and value' object to be checked.

   221 	* @return			ETrue, if the specified 'attribute type and value' object is contained 

   222 	* 					in this Distinguished Name object; EFalse otherwise. */

   223 	IMPORT_C TBool MatchElementL(const CX520AttributeTypeAndValue& aElement) const;

   224 	

   225 	/** Gets the decoded value associated with the specified field/attribute name, 

   226 	* from the Distinguished Name.

   227 	* 

   228 	* @param aFieldName	The field name.

   229 	* @return			A heap descriptor containing the decoded value associated with the 

   230 	* 					specified field name. */

   231 	IMPORT_C HBufC* ExtractFieldL(const TDesC& aFieldName) const;

   232 	

   233 	/** Gets the decoded value for the common or organisation name.

   234 	* 

   235 	* @return A heap descriptor containing the decoded value of the common or organisation name. */

   236 	IMPORT_C HBufC* DisplayNameL() const;

   237 

   238 	/** Encodes a DN into an ASN.1 object tree.

   239 	* 

   240 	* Note that the tree has the following format:

   241 	* @code

   242     *         SEQUENCE-OF

   243     *             SET-OF

   244     *                 SEQUENCE-OF

   245     *                     OID

   246     *                     value (usually OCTET STRING)

   247     *             ...

   248     * @endcode

   249 	* 

   250 	* A SEQUENCE-OF object with a changed tag is used instead of 

   251 	* a SET-OF object. This should be all right as long as it 

   252 	* contains only one child, because otherwise child order in 

   253 	* a SET-OF becomes important.

   254 	* 

   255 	* This function does not introduce an additional dependency 

   256 	* on ASN1 library because X500 library already depends on 

   257 	* it -- the attribute type/value class stores and manipulated 

   258 	* ASN.1 encodings as its values.

   259 	* 	

   260 	* @return	ASN.1 sequence object containing the DN, 

   261 	* 			pushed on the cleanup stack.

   262 	*/

   263 	IMPORT_C CASN1EncSequence* EncodeASN1LC() const;

   264 

   265 	/** Encodes a DN into an ASN.1 object tree. 

   266 	* 

   267 	* See note in the description of #EncodeASN1LC for the explanation of 

   268 	* the resulting encoding tree format.

   269 	* 	

   270 	* @return	ASN.1 sequence object containing the DN. */

   271 	IMPORT_C CASN1EncSequence* EncodeASN1L() const;

   272 

   273 private:

   274 	CX500DistinguishedName();

   275 	void ConstructL(const CArrayPtr<CX520AttributeTypeAndValue>& aElements);

   276 	void ConstructL(const TDesC8& aBinaryData, TInt& aPos);

   277 	void ConstructL(RReadStream& aStream);

   278 	void InternalizeL(RReadStream& aStream);

   279 	CArrayPtrFlat<CX520AttributeTypeAndValue>* iElements;

   280 	};

   281 

   282 #endif