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.extensions;
028    import org.opends.messages.MessageBuilder;
029    
030    
031    import org.opends.server.types.DirectoryException;
032    import org.opends.server.types.Operation;
033    
034    
035    
036    /**
037     * This interface defines a set of methods that must be implemented by a class
038     * (expected to be a client connection) that can dynamically enable and disable
039     * the TLS connection security provider.  This will be used by the StartTLS
040     * extended operation handler to perform the core function of enabling TLS on an
041     * established connection.
042     */
043    public interface TLSCapableConnection
044    {
045      /**
046       * Indicates whether TLS protection is actually available for the underlying
047       * client connection.  If there is any reason that TLS protection cannot be
048       * enabled on this client connection, then it should be appended to the
049       * provided buffer.
050       *
051       * @param  unavailableReason  The buffer used to hold the reason that TLS is
052       *                            not available on the underlying client
053       *                            connection.
054       *
055       * @return  <CODE>true</CODE> if TLS is available on the underlying client
056       *          connection, or <CODE>false</CODE> if it is not.
057       */
058      public boolean tlsProtectionAvailable(MessageBuilder unavailableReason);
059    
060    
061    
062      /**
063       * Installs the TLS connection security provider on this client connection.
064       * If an error occurs in the process, then the underlying client connection
065       * must be terminated and an exception must be thrown to indicate the
066       * underlying cause.
067       *
068       * @throws  DirectoryException  If the TLS connection security provider could
069       *                              not be enabled and the underlying connection
070       *                              has been closed.
071       */
072      public void enableTLSConnectionSecurityProvider()
073             throws DirectoryException;
074    
075    
076    
077      /**
078       * Disables the TLS connection security provider on this client connection.
079       * This must also eliminate any authentication that had been performed on the
080       * client connection so that it is in an anonymous state.  If a problem occurs
081       * while attempting to revert the connection to a non-TLS-protected state,
082       * then an exception must be thrown and the client connection must be
083       * terminated.
084       *
085       * @throws  DirectoryException  If TLS protection cannot be reverted and the
086       *                              underlying client connection has been closed.
087       */
088      public void disableTLSConnectionSecurityProvider()
089             throws DirectoryException;
090    
091    
092    
093      /**
094       * Sends a response to the client in the clear rather than through the
095       * encrypted channel.  This should only be used when processing the StartTLS
096       * extended operation to send the response in the clear after the SSL
097       * negotiation has already been initiated.
098       *
099       * @param  operation  The operation for which to send the response in the
100       *                    clear.
101       *
102       * @throws  DirectoryException  If a problem occurs while sending the response
103       *                              in the clear.
104       */
105      public void sendClearResponse(Operation operation)
106             throws DirectoryException;
107    }
108