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.api;
028 import org.opends.messages.Message;
029
030
031
032 import java.security.cert.Certificate;
033 import java.util.List;
034
035 import org.opends.server.admin.std.server.CertificateMapperCfg;
036 import org.opends.server.config.ConfigException;
037 import org.opends.server.types.DirectoryException;
038 import org.opends.server.types.Entry;
039 import org.opends.server.types.InitializationException;
040
041
042 /**
043 * This class defines the set of methods and structures that must be
044 * implemented by a Directory Server module that implements the
045 * functionality required to uniquely map an SSL client certificate to
046 * a Directory Server user entry.
047 *
048 * @param <T> The type of configuration handled by this certificate
049 * mapper.
050 */
051 @org.opends.server.types.PublicAPI(
052 stability=org.opends.server.types.StabilityLevel.VOLATILE,
053 mayInstantiate=false,
054 mayExtend=true,
055 mayInvoke=false)
056 public abstract class CertificateMapper
057 <T extends CertificateMapperCfg>
058 {
059 /**
060 * Initializes this certificate mapper based on the information in
061 * the provided configuration entry.
062 *
063 * @param configuration The configuration that should be used to
064 * intialize this certificate mapper.
065 *
066 * @throws ConfigException If the provided entry does not contain
067 * a valid certificate mapper
068 * configuration.
069 *
070 * @throws InitializationException If a problem occurs during
071 * initialization that is not
072 * related to the server
073 * configuration.
074 */
075 public abstract void initializeCertificateMapper(T configuration)
076 throws ConfigException, InitializationException;
077
078
079
080 /**
081 * Indicates whether the provided configuration is acceptable for
082 * this certificate mapper. It should be possible to call this
083 * method on an uninitialized certificate mapper instance in order
084 * to determine whether the certificate mapper would be able to use
085 * the provided configuration.
086 * <BR><BR>
087 * Note that implementations which use a subclass of the provided
088 * configuration class will likely need to cast the configuration
089 * to the appropriate subclass type.
090 *
091 * @param configuration The certificate mapper configuration
092 * for which to make the determination.
093 * @param unacceptableReasons A list that may be used to hold the
094 * reasons that the provided
095 * configuration is not acceptable.
096 *
097 * @return {@code true} if the provided configuration is acceptable
098 * for this certificate mapper, or {@code false} if not.
099 */
100 public boolean isConfigurationAcceptable(
101 CertificateMapperCfg configuration,
102 List<Message> unacceptableReasons)
103 {
104 // This default implementation does not perform any special
105 // validation. It should be overridden by certificate mapper
106 // implementations that wish to perform more detailed validation.
107 return true;
108 }
109
110
111
112 /**
113 * Performs any finalization that may be necessary for this
114 * certificate mapper. By default, no finalization is performed.
115 */
116 public void finalizeCertificateMapper()
117 {
118 // No implementation is required by default.
119 }
120
121
122
123 /**
124 * Establishes a mapping between the information in the provided
125 * certificate chain and a single user entry in the Directory
126 * Server.
127 *
128 * @param certificateChain The certificate chain presented by the
129 * client during SSL negotiation. The
130 * peer certificate will be listed first,
131 * followed by the ordered issuer chain
132 * as appropriate.
133 *
134 * @return The entry for the user to whom the mapping was
135 * established, or {@code null} if no mapping was
136 * established and no special message is required to send
137 * back to the client.
138 *
139 * @throws DirectoryException If a problem occurred while
140 * attempting to establish the mapping.
141 * This may include internal failures,
142 * a mapping which matches multiple
143 * users, or any other case in which an
144 * error message should be returned to
145 * the client.
146 */
147 public abstract Entry mapCertificateToUser(Certificate[]
148 certificateChain)
149 throws DirectoryException;
150 }
151