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