001    /*
002     * CDDL HEADER START
003     *
004     * The contents of this file are subject to the terms of the
005     * Common Development and Distribution License, Version 1.0 only
006     * (the "License").  You may not use this file except in compliance
007     * with the License.
008     *
009     * You can obtain a copy of the license at
010     * trunk/opends/resource/legal-notices/OpenDS.LICENSE
011     * or https://OpenDS.dev.java.net/OpenDS.LICENSE.
012     * See the License for the specific language governing permissions
013     * and limitations under the License.
014     *
015     * When distributing Covered Code, include this CDDL HEADER in each
016     * file and include the License file at
017     * trunk/opends/resource/legal-notices/OpenDS.LICENSE.  If applicable,
018     * add the following below this CDDL HEADER, with the fields enclosed
019     * by brackets "[]" replaced with your own identifying information:
020     *      Portions Copyright [yyyy] [name of copyright owner]
021     *
022     * CDDL HEADER END
023     *
024     *
025     *      Copyright 2006-2008 Sun Microsystems, Inc.
026     */
027    package org.opends.server.schema;
028    
029    
030    
031    import java.util.Arrays;
032    
033    import org.opends.server.admin.std.server.EqualityMatchingRuleCfg;
034    import org.opends.server.api.EqualityMatchingRule;
035    import org.opends.server.api.PasswordStorageScheme;
036    import org.opends.server.config.ConfigException;
037    import org.opends.server.core.DirectoryServer;
038    import org.opends.server.protocols.asn1.ASN1OctetString;
039    import org.opends.server.types.AttributeValue;
040    import org.opends.server.types.ByteString;
041    import org.opends.server.types.ConditionResult;
042    import org.opends.server.types.DirectoryException;
043    import org.opends.server.types.InitializationException;
044    
045    import static org.opends.server.loggers.debug.DebugLogger.*;
046    import org.opends.server.loggers.debug.DebugTracer;
047    import org.opends.server.types.DebugLogLevel;
048    import static org.opends.server.schema.SchemaConstants.*;
049    
050    
051    
052    /**
053     * This class implements the userPasswordMatch matching rule, which can be used
054     * to determine whether a clear-text value matches an encoded password.
055     */
056    public class UserPasswordEqualityMatchingRule
057           extends EqualityMatchingRule
058    {
059      /**
060       * The tracer object for the debug logger.
061       */
062      private static final DebugTracer TRACER = getTracer();
063    
064    
065    
066      /**
067       * Creates a new instance of this userPasswordMatch matching rule.
068       */
069      public UserPasswordEqualityMatchingRule()
070      {
071        super();
072      }
073    
074    
075    
076      /**
077       * {@inheritDoc}
078       */
079      public void initializeMatchingRule(EqualityMatchingRuleCfg configuration)
080             throws ConfigException, InitializationException
081      {
082        // No initialization is required.
083      }
084    
085    
086    
087      /**
088       * Retrieves the common name for this matching rule.
089       *
090       * @return  The common name for this matching rule, or <CODE>null</CODE> if
091       * it does not have a name.
092       */
093      public String getName()
094      {
095        return EMR_USER_PASSWORD_NAME;
096      }
097    
098    
099    
100      /**
101       * Retrieves the OID for this matching rule.
102       *
103       * @return  The OID for this matching rule.
104       */
105      public String getOID()
106      {
107        return EMR_USER_PASSWORD_OID;
108      }
109    
110    
111    
112      /**
113       * Retrieves the description for this matching rule.
114       *
115       * @return  The description for this matching rule, or <CODE>null</CODE> if
116       *          there is none.
117       */
118      public String getDescription()
119      {
120        // There is no standard description for this matching rule.
121        return EMR_USER_PASSWORD_DESCRIPTION;
122      }
123    
124    
125    
126      /**
127       * Retrieves the OID of the syntax with which this matching rule is
128       * associated.
129       *
130       * @return  The OID of the syntax with which this matching rule is associated.
131       */
132      public String getSyntaxOID()
133      {
134        return SYNTAX_USER_PASSWORD_OID;
135      }
136    
137    
138    
139      /**
140       * Retrieves the normalized form of the provided value, which is best suited
141       * for efficiently performing matching operations on that value.
142       *
143       * @param  value  The value to be normalized.
144       *
145       * @return  The normalized version of the provided value.
146       *
147       * @throws  DirectoryException  If the provided value is invalid according to
148       *                              the associated attribute syntax.
149       */
150      public ByteString normalizeValue(ByteString value)
151             throws DirectoryException
152      {
153        // We will not alter the value in any way, but we'll create a new value
154        // just in case something else is using the underlying array.
155        byte[] currentValue = value.value();
156        byte[] newValue     = new byte[currentValue.length];
157        System.arraycopy(currentValue, 0, newValue, 0, currentValue.length);
158    
159        return new ASN1OctetString(newValue);
160      }
161    
162    
163    
164      /**
165       * Indicates whether the two provided normalized values are equal to each
166       * other.
167       *
168       * @param  value1  The normalized form of the first value to compare.
169       * @param  value2  The normalized form of the second value to compare.
170       *
171       * @return  <CODE>true</CODE> if the provided values are equal, or
172       *          <CODE>false</CODE> if not.
173       */
174      public boolean areEqual(ByteString value1, ByteString value2)
175      {
176        // Since the values are already normalized, we just need to compare the
177        // associated byte arrays.
178        return Arrays.equals(value1.value(), value2.value());
179      }
180    
181    
182    
183      /**
184       * Indicates whether the provided attribute value should be considered a match
185       * for the given assertion value.  This will only be used for the purpose of
186       * extensible matching.  Other forms of matching against equality matching
187       * rules should use the <CODE>areEqual</CODE> method.
188       *
189       * @param  attributeValue  The attribute value in a form that has been
190       *                         normalized according to this matching rule.
191       * @param  assertionValue  The assertion value in a form that has been
192       *                         normalized according to this matching rule.
193       *
194       * @return  <CODE>true</CODE> if the attribute value should be considered a
195       *          match for the provided assertion value, or <CODE>false</CODE> if
196       *          not.
197       */
198      public ConditionResult valuesMatch(ByteString attributeValue,
199                                         ByteString assertionValue)
200      {
201        // We must be able to decode the attribute value using the user password
202        // syntax.
203        String[] userPWComponents;
204        try
205        {
206          userPWComponents =
207               UserPasswordSyntax.decodeUserPassword(attributeValue.stringValue());
208        }
209        catch (Exception e)
210        {
211          if (debugEnabled())
212          {
213            TRACER.debugCaught(DebugLogLevel.ERROR, e);
214          }
215    
216          return ConditionResult.FALSE;
217        }
218    
219    
220        // The first element of the array will be the scheme.  Make sure that we
221        // support the requested scheme.
222        PasswordStorageScheme storageScheme =
223             DirectoryServer.getPasswordStorageScheme(userPWComponents[0]);
224        if (storageScheme == null)
225        {
226          // It's not a scheme that we can support.
227          return ConditionResult.FALSE;
228        }
229    
230    
231        // We support the scheme, so make the determination.
232        if (storageScheme.passwordMatches(assertionValue,
233                                          new ASN1OctetString(userPWComponents[1])))
234        {
235          return ConditionResult.TRUE;
236        }
237        else
238        {
239          return ConditionResult.FALSE;
240        }
241      }
242    
243    
244    
245      /**
246       * Generates a hash code for the provided attribute value.  This version of
247       * the method will simply create a hash code from the normalized form of the
248       * attribute value.  For matching rules explicitly designed to work in cases
249       * where byte-for-byte comparisons of normalized values is not sufficient for
250       * determining equality (e.g., if the associated attribute syntax is based on
251       * hashed or encrypted values), then this method must be overridden to provide
252       * an appropriate implementation for that case.
253       *
254       * @param  attributeValue  The attribute value for which to generate the hash
255       *                         code.
256       *
257       * @return  The hash code generated for the provided attribute value.
258       */
259      public int generateHashCode(AttributeValue attributeValue)
260      {
261        // Because of the variable encoding that may be used, we have no way of
262        // comparing two user password values by hash code and therefore we'll
263        // always return the same value so that the valuesMatch method will be
264        // invoked to make the determination.
265        return 1;
266      }
267    }
268