1.1 --- a/epoc32/include/x500dn.h Tue Nov 24 13:55:44 2009 +0000
1.2 +++ b/epoc32/include/x500dn.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -1,1 +1,282 @@
1.4 -x500dn.h
1.5 +/*
1.6 +* Copyright (c) 1998-2009 Nokia Corporation and/or its subsidiary(-ies).
1.7 +* All rights reserved.
1.8 +* This component and the accompanying materials are made available
1.9 +* under the terms of the License "Eclipse Public License v1.0"
1.10 +* which accompanies this distribution, and is available
1.11 +* at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.12 +*
1.13 +* Initial Contributors:
1.14 +* Nokia Corporation - initial contribution.
1.15 +*
1.16 +* Contributors:
1.17 +*
1.18 +* Description:
1.19 +* Implementation of the class that holds the Distinguished Name of a subject
1.20 +*
1.21 +*/
1.22 +
1.23 +
1.24 +
1.25 +
1.26 +/**
1.27 + @file
1.28 + @publishedAll
1.29 + @released
1.30 +*/
1.31 +#if !defined (__X500DN_H__)
1.32 +#define __X500DN_H__
1.33 +
1.34 +#include <e32base.h>
1.35 +#include <e32std.h>
1.36 +#include <s32file.h>
1.37 +#include <x520ava.h>
1.38 +
1.39 +class CX500DistinguishedName : public CBase
1.40 +/** Holds the Distinguished Name of a subject.
1.41 +*
1.42 +* A collection of 'attribute type and value' objects, as defined by the X.520
1.43 +* standard.
1.44 +*
1.45 +* The name used in X.509 certificates is the X.500 Distinguished Name, which
1.46 +* describes a path through an X.500 Directory Information Tree.
1.47 +*
1.48 +* A Distinguished Name is a series of name-value pairs that uniquely identify
1.49 +* an entity, i.e. the certificate subject.
1.50 +*
1.51 +* @publishedAll
1.52 +* @released
1.53 +*
1.54 +* <!--
1.55 +* This is necessary when working with certificates, certificate requests, directories, etc.
1.56 +* -->
1.57 +*/
1.58 + {
1.59 +public:
1.60 + /** Creates a new Distinguished Name object from the specified buffer containing
1.61 + * the encoded binary representation, starting at the specified offset.
1.62 + *
1.63 + * @param aBinaryData The encoded binary representation.
1.64 + * @param aPos The position from which to start decoding.
1.65 + * @return The new Distinguished Name object. */
1.66 + IMPORT_C static CX500DistinguishedName* NewL(const TDesC8& aBinaryData, TInt& aPos);
1.67 +
1.68 + /** Creates a new Distinguished Name object from the specified buffer containing
1.69 + * the encoded binary representation, starting at the specified offset, and puts
1.70 + * a pointer to it onto the cleanup stack.
1.71 + *
1.72 + * @param aBinaryData The encoded binary representation.
1.73 + * @param aPos The position from which to start decoding.
1.74 + * @return The new Distinguished Name object. */
1.75 + IMPORT_C static CX500DistinguishedName* NewLC(const TDesC8& aBinaryData, TInt& aPos);
1.76 +
1.77 + /** Creates a new Distinguished Name object from the specified buffer containing
1.78 + * the encoded binary representation.
1.79 + *
1.80 + * Initialises the object from its encoded binary form into an internal representation.
1.81 + *
1.82 + * @param aBinaryData The encoded binary representation.
1.83 + * @return The new Distinguished Name object. */
1.84 + IMPORT_C static CX500DistinguishedName* NewL(const TDesC8& aBinaryData);
1.85 +
1.86 + /** Creates a new Distinguished Name object from the specified buffer containing
1.87 + * the encoded binary representation, and puts a pointer to it onto the cleanup stack.
1.88 + *
1.89 + * Initialises the object from its encoded binary form into an internal representation.
1.90 + *
1.91 + * @param aBinaryData The encoded binary representation.
1.92 + * @return The new Distinguished Name object. */
1.93 + IMPORT_C static CX500DistinguishedName* NewLC(const TDesC8& aBinaryData);
1.94 +
1.95 + /** Creates a new Distinguished Name object from the specified read stream.
1.96 + *
1.97 + * Construction is from a stream.
1.98 + *
1.99 + * @param aStream Stream from which the contents should be internalised.
1.100 + * @return The newDistinguished Name object. */
1.101 + IMPORT_C static CX500DistinguishedName* NewL(RReadStream& aStream);
1.102 +
1.103 + /** Creates a new Distinguished Name object from the specified read stream, and
1.104 + * puts a pointer to it onto the cleanup stack.
1.105 + *
1.106 + * @param aStream Stream from which the contents should be internalised.
1.107 + * @return The new Distinguished Name object. */
1.108 + IMPORT_C static CX500DistinguishedName* NewLC(RReadStream& aStream);
1.109 +
1.110 + /** Creates a new Distinguished Name object from the specified array of 'attribute
1.111 + * type and value' objects.
1.112 + *
1.113 + * The elements of the specified array are copied into this object.
1.114 + *
1.115 + * @param aElements The array of 'attribute type and value' objects to be copied.
1.116 + * @return The new Distinguished Name object. */
1.117 + IMPORT_C static CX500DistinguishedName* NewL(const CArrayPtr<CX520AttributeTypeAndValue>& aElements);
1.118 +
1.119 + /** Creates a new Distinguished Name object from the specified array of 'attribute
1.120 + * type and value' objects, and puts a pointer to it onto the cleanup stack.
1.121 + *
1.122 + * The elements of the specified array are copied into this object.
1.123 + *
1.124 + * @param aElements The array of 'attribute type and value' objects to be copied.
1.125 + * @return The new Distinguished Name object. */
1.126 + IMPORT_C static CX500DistinguishedName* NewLC(const CArrayPtr<CX520AttributeTypeAndValue>& aElements);
1.127 +
1.128 + /** Creates a new Distinguished Name object from an existing object.
1.129 + *
1.130 + * This is equivalent to a copy constructor.
1.131 + *
1.132 + * @param aName The Distinguished Name object to be copied.
1.133 + * @return The new Distinguished Name object. */
1.134 + IMPORT_C static CX500DistinguishedName* NewL(const CX500DistinguishedName& aName);
1.135 +
1.136 + /** Creates a new Distinguished Name object from an existing object, and puts a
1.137 + * pointer to it onto the cleanup stack.
1.138 + *
1.139 + * This is equivalent to a copy constructor.
1.140 + *
1.141 + * @param aName The Distinguished Name object to be copied.
1.142 + * @return The new Distinguished Name object. */
1.143 + IMPORT_C static CX500DistinguishedName* NewLC(const CX500DistinguishedName& aName);
1.144 +
1.145 + /** Externalises an object of this class to a write stream.
1.146 + *
1.147 + * The presence of this function means that the standard templated operator<<()
1.148 + * can be used to externalise objects of this class.
1.149 + *
1.150 + * @param aStream Stream to which the object should be externalised. */
1.151 + IMPORT_C void ExternalizeL(RWriteStream& aStream) const;
1.152 +
1.153 + /** Gets the number of 'attribute type and value' objects contained by this Distinguished
1.154 + * Name object.
1.155 + *
1.156 + * @return The number of 'attribute type and value' objects. */
1.157 + IMPORT_C TInt Count() const;
1.158 +
1.159 + /** Gets a reference to specific 'attribute type and value' object as identified
1.160 + * by the specified index.
1.161 + *
1.162 + * @param aIndex The index number identifying the specific 'attribute type and
1.163 + * value' object. This number is relative to zero. This value must be non-negative
1.164 + * and less than the number of objects currently contained by this Distinguished
1.165 + * Name object.
1.166 + * @return The referenced 'attribute type and value' object. */
1.167 + IMPORT_C const CX520AttributeTypeAndValue& Element(TInt aIndex) const;
1.168 +
1.169 + /** Destructor.
1.170 + *
1.171 + * Frees all resources owned by the object, prior to its destruction. */
1.172 + IMPORT_C ~CX500DistinguishedName();
1.173 +
1.174 + /** Compares the specified Distinguished Name object with this Distinguished Name
1.175 + * object.
1.176 + *
1.177 + * @param aName The Distinguished Name object to be compared.
1.178 + * @return ETrue, if the Distinguished Name objects contain exactly the same 'attribute
1.179 + * type and value' objects; EFalse, otherwise.
1.180 + * @see CX520AttributeTypeAndValue::ExactMatchL()
1.181 + *
1.182 + * <!-- This function checks if all the fields of aName and
1.183 + * iElements are the same but not necessarily in the same order. -->
1.184 + */
1.185 + IMPORT_C TBool ExactMatchL(const CX500DistinguishedName& aName) const;
1.186 +
1.187 + /** <!--
1.188 + // This function checks if the elements of iElements are a superset of
1.189 + // the fields in aName.
1.190 + // @param aName We want to check that the fields in aName are present in iElements.
1.191 + // @return
1.192 + // <UL>
1.193 + // <LI>ETrue if all the fields in aName have a corresponding field in iElements.</LI>
1.194 + // <LI>EFalse otherwise</LI>
1.195 + // </UL>
1.196 + -->
1.197 + * Tests whether all 'attribute type and value' objects contained in the specified
1.198 + * Distinguished Name object are also contained within this Distinguished Name object.
1.199 + *
1.200 + * This function checks if the elements of iElements are a superset of the fields in aName.
1.201 + *
1.202 + * @param aName The Distinguished Name object to be compared.
1.203 + * @return ETrue, if all 'attribute type and value' objects contained in the specified
1.204 + * Distinguished Name object are also contained within this Distinguished Name
1.205 + * object; EFalse, otherwise. */
1.206 + IMPORT_C TBool IsWithinSubtreeL(const CX500DistinguishedName& aName) const;
1.207 +
1.208 + /** <!--
1.209 + // This function compares each of the elements in iElements with aElement. The comparison
1.210 + // is made by the CX520AttributeTypeAndValue::ExactMatchL function.
1.211 + // @param aElement The element which we want to compare the elements of iElements with.
1.212 + // @return
1.213 + // <UL>
1.214 + // <LI>ETrue if one of the elements in iElements is equal to aElement.</LI>
1.215 + // <LI>EFalse otherwise</LI>
1.216 + // </UL>
1.217 + -->
1.218 + * Tests whether this Distinguished Name object contains the specified 'attribute
1.219 + * type and value' object.
1.220 + *
1.221 + * This function compares each of the elements in iElements with aElement. The comparison
1.222 + * is made by the CX520AttributeTypeAndValue::ExactMatchL() function.
1.223 + *
1.224 + * @param aElement The 'attribute type and value' object to be checked.
1.225 + * @return ETrue, if the specified 'attribute type and value' object is contained
1.226 + * in this Distinguished Name object; EFalse otherwise. */
1.227 + IMPORT_C TBool MatchElementL(const CX520AttributeTypeAndValue& aElement) const;
1.228 +
1.229 + /** Gets the decoded value associated with the specified field/attribute name,
1.230 + * from the Distinguished Name.
1.231 + *
1.232 + * @param aFieldName The field name.
1.233 + * @return A heap descriptor containing the decoded value associated with the
1.234 + * specified field name. */
1.235 + IMPORT_C HBufC* ExtractFieldL(const TDesC& aFieldName) const;
1.236 +
1.237 + /** Gets the decoded value for the common or organisation name.
1.238 + *
1.239 + * @return A heap descriptor containing the decoded value of the common or organisation name. */
1.240 + IMPORT_C HBufC* DisplayNameL() const;
1.241 +
1.242 + /** Encodes a DN into an ASN.1 object tree.
1.243 + *
1.244 + * Note that the tree has the following format:
1.245 + * @code
1.246 + * SEQUENCE-OF
1.247 + * SET-OF
1.248 + * SEQUENCE-OF
1.249 + * OID
1.250 + * value (usually OCTET STRING)
1.251 + * ...
1.252 + * @endcode
1.253 + *
1.254 + * A SEQUENCE-OF object with a changed tag is used instead of
1.255 + * a SET-OF object. This should be all right as long as it
1.256 + * contains only one child, because otherwise child order in
1.257 + * a SET-OF becomes important.
1.258 + *
1.259 + * This function does not introduce an additional dependency
1.260 + * on ASN1 library because X500 library already depends on
1.261 + * it -- the attribute type/value class stores and manipulated
1.262 + * ASN.1 encodings as its values.
1.263 + *
1.264 + * @return ASN.1 sequence object containing the DN,
1.265 + * pushed on the cleanup stack.
1.266 + */
1.267 + IMPORT_C CASN1EncSequence* EncodeASN1LC() const;
1.268 +
1.269 + /** Encodes a DN into an ASN.1 object tree.
1.270 + *
1.271 + * See note in the description of #EncodeASN1LC for the explanation of
1.272 + * the resulting encoding tree format.
1.273 + *
1.274 + * @return ASN.1 sequence object containing the DN. */
1.275 + IMPORT_C CASN1EncSequence* EncodeASN1L() const;
1.276 +
1.277 +private:
1.278 + CX500DistinguishedName();
1.279 + void ConstructL(const CArrayPtr<CX520AttributeTypeAndValue>& aElements);
1.280 + void ConstructL(const TDesC8& aBinaryData, TInt& aPos);
1.281 + void ConstructL(RReadStream& aStream);
1.282 + void InternalizeL(RReadStream& aStream);
1.283 + CArrayPtrFlat<CX520AttributeTypeAndValue>* iElements;
1.284 + };
1.285 +
1.286 +#endif