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 029 030 031 import java.nio.ByteBuffer; 032 import java.nio.channels.SocketChannel; 033 import org.opends.server.config.ConfigEntry; 034 import org.opends.server.config.ConfigException; 035 import org.opends.server.types.DirectoryException; 036 import org.opends.server.types.InitializationException; 037 038 039 040 /** 041 * This class defines an API that may be used to encode and decode 042 * data for communication with clients over a secure channel (e.g., 043 * SSL/TLS, Kerberos confidentiality, etc.). 044 */ 045 @org.opends.server.types.PublicAPI( 046 stability=org.opends.server.types.StabilityLevel.VOLATILE, 047 mayInstantiate=true, 048 mayExtend=true, 049 mayInvoke=true) 050 public abstract class ConnectionSecurityProvider 051 { 052 /** 053 * Initializes this connection security provider using the 054 * information in the provided configuration entry. 055 * 056 * @param configEntry The entry that contains the configuration 057 * for this connection security provider. 058 * 059 * @throws ConfigException If the provided entry does not contain 060 * an acceptable configuration for this 061 * security provider. 062 * 063 * @throws InitializationException If a problem occurs during 064 * initialization that is not 065 * related to the provided 066 * configuration. 067 */ 068 public abstract void initializeConnectionSecurityProvider( 069 ConfigEntry configEntry) 070 throws ConfigException, InitializationException; 071 072 073 074 /** 075 * Performs any finalization that may be necessary for this 076 * connection security provider. 077 */ 078 public abstract void finalizeConnectionSecurityProvider(); 079 080 081 082 /** 083 * Retrieves the name used to identify this security mechanism. 084 * 085 * @return The name used to identify this security mechanism. 086 */ 087 public abstract String getSecurityMechanismName(); 088 089 090 091 /** 092 * Indicates whether client connections using this connection 093 * security provider should be considered secure. 094 * 095 * @return {@code true} if client connections using this connection 096 * security provider should be considered secure, or 097 * {@code false} if not. 098 */ 099 public abstract boolean isSecure(); 100 101 102 103 /** 104 * Creates a new instance of this connection security provider that 105 * will be used to encode and decode all communication on the 106 * provided client connection. 107 * 108 * @param clientConnection The client connection with which this 109 * security provider will be associated. 110 * @param socketChannel The socket channel that may be used to 111 * communicate with the client. 112 * 113 * @return The created connection security provider instance. 114 * 115 * @throws DirectoryException If a problem occurs while creating a 116 * new instance of this security 117 * provider for the given client 118 * connection. 119 */ 120 public abstract ConnectionSecurityProvider 121 newInstance(ClientConnection clientConnection, 122 SocketChannel socketChannel) 123 throws DirectoryException; 124 125 126 127 /** 128 * Indicates that the associated client connection is being closed 129 * and that this security provider should perform any necessary 130 * processing to deal with that. If it is indicated that the 131 * connection is still valid, then the security provider may attempt 132 * to communicate with the client to perform a graceful shutdown. 133 * 134 * @param connectionValid Indicates whether the Directory Server 135 * believes that the client connection is 136 * still valid and may be used for 137 * communication with the client. Note 138 * that this may be inaccurate, or that the 139 * state of the connection may change 140 * during the course of this method, so the 141 * security provider must be able to handle 142 * failures if they arise. 143 */ 144 public abstract void disconnect(boolean connectionValid); 145 146 147 148 /** 149 * Retrieves the size in bytes that the client should use for the 150 * byte buffer meant to hold clear-text data read from or to be 151 * written to the client. 152 * 153 * @return The size in bytes that the client should use for the 154 * byte buffer meant to hold clear-text data read from or 155 * to be written to the client. 156 */ 157 public abstract int getClearBufferSize(); 158 159 160 161 /** 162 * Retrieves the size in bytes that the client should use for the 163 * byte buffer meant to hold encoded data read from or to be written 164 * to the client. 165 * 166 * @return The size in bytes that the client should use for the 167 * byte buffer meant to hold encoded data read from or to 168 * be written to the client. 169 */ 170 public abstract int getEncodedBufferSize(); 171 172 173 174 /** 175 * Reads data from a client connection, performing any necessary 176 * negotiation in the process. Whenever any clear-text data has 177 * been obtained, then the connection security provider should make 178 * that available to the client by calling the 179 * {@code ClientConnection.processDataRead} method. 180 * 181 * @return {@code true} if all the data in the provided buffer was 182 * processed and the client connection can remain 183 * established, or {@code false} if a decoding error 184 * occurred and requests from this client should no longer 185 * be processed. Note that if this method does return 186 * {@code false}, then it must have already disconnected 187 * the client. 188 * 189 * @throws DirectoryException If a problem occurs while reading 190 * data from the client. 191 */ 192 public abstract boolean readData() 193 throws DirectoryException; 194 195 196 197 /** 198 * Writes the data contained in the provided clear-text buffer to 199 * the client, performing any necessary encoding in the process. It 200 * must be capable of dealing with input buffers that are larger 201 * than the value returned by the {@code getClearBufferSize} method. 202 * When this method returns, the provided buffer should be in its 203 * original state with regard to the position and limit. 204 * 205 * @param clearData The buffer containing the clear-text data to 206 * write to the client. 207 * 208 * @return {@code true} if all the data in the provided buffer was 209 * written to the client and the connection may remain 210 * established, or {@code false} if a problem occurred and 211 * the client connection is no longer valid. Note that if 212 * this method does return {@code false}, then it must have 213 * already disconnected the client. 214 */ 215 public abstract boolean writeData(ByteBuffer clearData); 216 } 217