2 * Copyright (c) 1998-2009 Nokia Corporation and/or its subsidiary(-ies).
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".
9 * Initial Contributors:
10 * Nokia Corporation - initial contribution.
15 * Implementation of the class that holds the Distinguished Name of a subject
25 #if !defined (__X500DN_H__)
33 class CX500DistinguishedName : public CBase
34 /** Holds the Distinguished Name of a subject.
36 * A collection of 'attribute type and value' objects, as defined by the X.520
39 * The name used in X.509 certificates is the X.500 Distinguished Name, which
40 * describes a path through an X.500 Directory Information Tree.
42 * A Distinguished Name is a series of name-value pairs that uniquely identify
43 * an entity, i.e. the certificate subject.
49 * This is necessary when working with certificates, certificate requests, directories, etc.
54 /** Creates a new Distinguished Name object from the specified buffer containing
55 * the encoded binary representation, starting at the specified offset.
57 * @param aBinaryData The encoded binary representation.
58 * @param aPos The position from which to start decoding.
59 * @return The new Distinguished Name object. */
60 IMPORT_C static CX500DistinguishedName* NewL(const TDesC8& aBinaryData, TInt& aPos);
62 /** Creates a new Distinguished Name object from the specified buffer containing
63 * the encoded binary representation, starting at the specified offset, and puts
64 * a pointer to it onto the cleanup stack.
66 * @param aBinaryData The encoded binary representation.
67 * @param aPos The position from which to start decoding.
68 * @return The new Distinguished Name object. */
69 IMPORT_C static CX500DistinguishedName* NewLC(const TDesC8& aBinaryData, TInt& aPos);
71 /** Creates a new Distinguished Name object from the specified buffer containing
72 * the encoded binary representation.
74 * Initialises the object from its encoded binary form into an internal representation.
76 * @param aBinaryData The encoded binary representation.
77 * @return The new Distinguished Name object. */
78 IMPORT_C static CX500DistinguishedName* NewL(const TDesC8& aBinaryData);
80 /** Creates a new Distinguished Name object from the specified buffer containing
81 * the encoded binary representation, and puts a pointer to it onto the cleanup stack.
83 * Initialises the object from its encoded binary form into an internal representation.
85 * @param aBinaryData The encoded binary representation.
86 * @return The new Distinguished Name object. */
87 IMPORT_C static CX500DistinguishedName* NewLC(const TDesC8& aBinaryData);
89 /** Creates a new Distinguished Name object from the specified read stream.
91 * Construction is from a stream.
93 * @param aStream Stream from which the contents should be internalised.
94 * @return The newDistinguished Name object. */
95 IMPORT_C static CX500DistinguishedName* NewL(RReadStream& aStream);
97 /** Creates a new Distinguished Name object from the specified read stream, and
98 * puts a pointer to it onto the cleanup stack.
100 * @param aStream Stream from which the contents should be internalised.
101 * @return The new Distinguished Name object. */
102 IMPORT_C static CX500DistinguishedName* NewLC(RReadStream& aStream);
104 /** Creates a new Distinguished Name object from the specified array of 'attribute
105 * type and value' objects.
107 * The elements of the specified array are copied into this object.
109 * @param aElements The array of 'attribute type and value' objects to be copied.
110 * @return The new Distinguished Name object. */
111 IMPORT_C static CX500DistinguishedName* NewL(const CArrayPtr<CX520AttributeTypeAndValue>& aElements);
113 /** Creates a new Distinguished Name object from the specified array of 'attribute
114 * type and value' objects, and puts a pointer to it onto the cleanup stack.
116 * The elements of the specified array are copied into this object.
118 * @param aElements The array of 'attribute type and value' objects to be copied.
119 * @return The new Distinguished Name object. */
120 IMPORT_C static CX500DistinguishedName* NewLC(const CArrayPtr<CX520AttributeTypeAndValue>& aElements);
122 /** Creates a new Distinguished Name object from an existing object.
124 * This is equivalent to a copy constructor.
126 * @param aName The Distinguished Name object to be copied.
127 * @return The new Distinguished Name object. */
128 IMPORT_C static CX500DistinguishedName* NewL(const CX500DistinguishedName& aName);
130 /** Creates a new Distinguished Name object from an existing object, and puts a
131 * pointer to it onto the cleanup stack.
133 * This is equivalent to a copy constructor.
135 * @param aName The Distinguished Name object to be copied.
136 * @return The new Distinguished Name object. */
137 IMPORT_C static CX500DistinguishedName* NewLC(const CX500DistinguishedName& aName);
139 /** Externalises an object of this class to a write stream.
141 * The presence of this function means that the standard templated operator<<()
142 * can be used to externalise objects of this class.
144 * @param aStream Stream to which the object should be externalised. */
145 IMPORT_C void ExternalizeL(RWriteStream& aStream) const;
147 /** Gets the number of 'attribute type and value' objects contained by this Distinguished
150 * @return The number of 'attribute type and value' objects. */
151 IMPORT_C TInt Count() const;
153 /** Gets a reference to specific 'attribute type and value' object as identified
154 * by the specified index.
156 * @param aIndex The index number identifying the specific 'attribute type and
157 * value' object. This number is relative to zero. This value must be non-negative
158 * and less than the number of objects currently contained by this Distinguished
160 * @return The referenced 'attribute type and value' object. */
161 IMPORT_C const CX520AttributeTypeAndValue& Element(TInt aIndex) const;
165 * Frees all resources owned by the object, prior to its destruction. */
166 IMPORT_C ~CX500DistinguishedName();
168 /** Compares the specified Distinguished Name object with this Distinguished Name
171 * @param aName The Distinguished Name object to be compared.
172 * @return ETrue, if the Distinguished Name objects contain exactly the same 'attribute
173 * type and value' objects; EFalse, otherwise.
174 * @see CX520AttributeTypeAndValue::ExactMatchL()
176 * <!-- This function checks if all the fields of aName and
177 * iElements are the same but not necessarily in the same order. -->
179 IMPORT_C TBool ExactMatchL(const CX500DistinguishedName& aName) const;
182 // This function checks if the elements of iElements are a superset of
183 // the fields in aName.
184 // @param aName We want to check that the fields in aName are present in iElements.
187 // <LI>ETrue if all the fields in aName have a corresponding field in iElements.</LI>
188 // <LI>EFalse otherwise</LI>
191 * Tests whether all 'attribute type and value' objects contained in the specified
192 * Distinguished Name object are also contained within this Distinguished Name object.
194 * This function checks if the elements of iElements are a superset of the fields in aName.
196 * @param aName The Distinguished Name object to be compared.
197 * @return ETrue, if all 'attribute type and value' objects contained in the specified
198 * Distinguished Name object are also contained within this Distinguished Name
199 * object; EFalse, otherwise. */
200 IMPORT_C TBool IsWithinSubtreeL(const CX500DistinguishedName& aName) const;
203 // This function compares each of the elements in iElements with aElement. The comparison
204 // is made by the CX520AttributeTypeAndValue::ExactMatchL function.
205 // @param aElement The element which we want to compare the elements of iElements with.
208 // <LI>ETrue if one of the elements in iElements is equal to aElement.</LI>
209 // <LI>EFalse otherwise</LI>
212 * Tests whether this Distinguished Name object contains the specified 'attribute
213 * type and value' object.
215 * This function compares each of the elements in iElements with aElement. The comparison
216 * is made by the CX520AttributeTypeAndValue::ExactMatchL() function.
218 * @param aElement The 'attribute type and value' object to be checked.
219 * @return ETrue, if the specified 'attribute type and value' object is contained
220 * in this Distinguished Name object; EFalse otherwise. */
221 IMPORT_C TBool MatchElementL(const CX520AttributeTypeAndValue& aElement) const;
223 /** Gets the decoded value associated with the specified field/attribute name,
224 * from the Distinguished Name.
226 * @param aFieldName The field name.
227 * @return A heap descriptor containing the decoded value associated with the
228 * specified field name. */
229 IMPORT_C HBufC* ExtractFieldL(const TDesC& aFieldName) const;
231 /** Gets the decoded value for the common or organisation name.
233 * @return A heap descriptor containing the decoded value of the common or organisation name. */
234 IMPORT_C HBufC* DisplayNameL() const;
236 /** Encodes a DN into an ASN.1 object tree.
238 * Note that the tree has the following format:
244 * value (usually OCTET STRING)
248 * A SEQUENCE-OF object with a changed tag is used instead of
249 * a SET-OF object. This should be all right as long as it
250 * contains only one child, because otherwise child order in
251 * a SET-OF becomes important.
253 * This function does not introduce an additional dependency
254 * on ASN1 library because X500 library already depends on
255 * it -- the attribute type/value class stores and manipulated
256 * ASN.1 encodings as its values.
258 * @return ASN.1 sequence object containing the DN,
259 * pushed on the cleanup stack.
261 IMPORT_C CASN1EncSequence* EncodeASN1LC() const;
263 /** Encodes a DN into an ASN.1 object tree.
265 * See note in the description of #EncodeASN1LC for the explanation of
266 * the resulting encoding tree format.
268 * @return ASN.1 sequence object containing the DN. */
269 IMPORT_C CASN1EncSequence* EncodeASN1L() const;
272 CX500DistinguishedName();
273 void ConstructL(const CArrayPtr<CX520AttributeTypeAndValue>& aElements);
274 void ConstructL(const TDesC8& aBinaryData, TInt& aPos);
275 void ConstructL(RReadStream& aStream);
276 void InternalizeL(RReadStream& aStream);
277 CArrayPtrFlat<CX520AttributeTypeAndValue>* iElements;