## org.apache.catalina.valves
Class CertificatesValve

    java.lang.Object
      org.apache.catalina.valves.ValveBase
          org.apache.catalina.valves.CertificatesValve

All Implemented Interfaces:
  Contained, Lifecycle, Valve

public final class CertificatesValve
extends ValveBase
implements Lifecycle

Implementation of a Valve that deals with SSL client certificates, as follows:

- If this request was not received on an SSL socket, simply pass it on unmodified.
- If this request was received on an SSL socket:
  - If this web application is using client certificate authentication, and no certificate chain is present (because the underlying socket did not default to requiring it), force an SSL handshake to acquire the client certificate chain.
  - If there is a client certificate chain present, expose it as a request attribute.
  - Expose the cipher suite and key size used on this SSL socket as request attributes.

  The above tasks have been combined into a single Valve to minimize the amount of code that has to check for the existence of JSSE classes.

  Version:
    $Revision: 1.11 $ $Date: 2004/08/26 21:43:51 $
  Author:
    Craig R. McClanahan

  Field Summary
  `protected boolean` `certificates` Are certificates required for authentication by this web application?
  `protected static org.apache.catalina.valves.CipherData[]` `ciphers` A mapping table to determine the number of effective bits in the key when using a cipher suite containing the specified cipher name.
  `protected int` `debug` The debugging detail level for this component.
  `protected static java.lang.String` `info` The descriptive information related to this implementation.
  `protected LifecycleSupport` `lifecycle` The lifecycle event support for this component.
  `protected static StringManager` `sm` The StringManager for this package.
  `protected boolean` `started` Has this component been started yet?

  Fields inherited from class org.apache.catalina.valves.ValveBase
  `container`

  Fields inherited from interface org.apache.catalina.Lifecycle
  `AFTER_START_EVENT, AFTER_STOP_EVENT, BEFORE_START_EVENT, BEFORE_STOP_EVENT, START_EVENT, STOP_EVENT`

  Constructor Summary
  `CertificatesValve()`

  Method Summary
  `void` `addLifecycleListener(LifecycleListener listener)` Add a LifecycleEvent listener to this component.
  `protected void` `expose(Request request, Request actual)` Expose the certificate chain for this request, if there is one.
  `LifecycleListener[]` `findLifecycleListeners()` Get the lifecycle listeners associated with this lifecycle.
  `int` `getDebug()` Return the debugging detail level for this component.
  `java.lang.String` `getInfo()` Return descriptive information about this Valve implementation.
  `void` `invoke(Request request, Response response, ValveContext context)` Expose the certificates chain if one was included on this request.
  `protected void` `log(java.lang.String message)` Log a message on the Logger associated with our Container (if any).
  `protected void` `log(java.lang.String message, java.lang.Throwable throwable)` Log a message on the Logger associated with our Container (if any).
  `void` `removeLifecycleListener(LifecycleListener listener)` Remove a LifecycleEvent listener from this component.
  `void` `setDebug(int debug)` Set the debugging detail level for this component.
  `void` `start()` Prepare for the beginning of active use of the public methods of this component.
  `void` `stop()` Gracefully terminate the active use of the public methods of this component.
  `protected void` `verify(Request request, Request actual)` Verify that a client certificate chain exists if our web application is doing client certificate authentication.

  Methods inherited from class org.apache.catalina.valves.ValveBase
  `getContainer, setContainer`

  Methods inherited from class java.lang.Object
  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

  Field Detail

  ### certificates

      protected boolean certificates

    Are certificates required for authentication by this web application?

  ### ciphers

      protected static final org.apache.catalina.valves.CipherData[] ciphers

    A mapping table to determine the number of effective bits in the key when using a cipher suite containing the specified cipher name. The underlying data came from the TLS Specification (RFC 2246), Appendix C.

  ### debug

      protected int debug

    The debugging detail level for this component.

  ### info

      protected static final java.lang.String info

    The descriptive information related to this implementation.

    See Also:
      Constant Field Values

  ### lifecycle

      protected LifecycleSupport lifecycle

    The lifecycle event support for this component.

  ### sm

      protected static StringManager sm

    The StringManager for this package.

  ### started

      protected boolean started

    Has this component been started yet?

  Constructor Detail

  ### CertificatesValve

      public CertificatesValve()

  Method Detail

  ### getDebug

      public int getDebug()

    Return the debugging detail level for this component.

    Overrides:
      `getDebug` in class `ValveBase`

  ### setDebug

      public void setDebug(int debug)

    Set the debugging detail level for this component.

    Overrides:
      `setDebug` in class `ValveBase`
    Parameters:
      `debug` - The new debugging detail level

  ### getInfo

      public java.lang.String getInfo()

    Return descriptive information about this Valve implementation.

    Specified by:
      `getInfo` in interface `Valve`
    Overrides:
      `getInfo` in class `ValveBase`

  ### invoke

      public void invoke(Request request,
                         Response response,
                         ValveContext context)
                  throws java.io.IOException,
                         javax.servlet.ServletException

    Expose the certificates chain if one was included on this request.

    Specified by:
      `invoke` in interface `Valve`
    Specified by:
      `invoke` in class `ValveBase`
    Parameters:
      `request` - The servlet request to be processed
      `response` - The servlet response to be created
      `context` - The valve context used to invoke the next valve in the current processing pipeline
    Throws:
      `java.io.IOException` - if an input/output error occurs
      `javax.servlet.ServletException` - if a servlet error occurs

  ### addLifecycleListener

      public void addLifecycleListener(LifecycleListener listener)

    Add a LifecycleEvent listener to this component.

    Specified by:
      `addLifecycleListener` in interface `Lifecycle`
    Parameters:
      `listener` - The listener to add

  ### findLifecycleListeners

      public LifecycleListener[] findLifecycleListeners()

    Get the lifecycle listeners associated with this lifecycle. If this Lifecycle has no listeners registered, a zero-length array is returned.

    Specified by:
      `findLifecycleListeners` in interface `Lifecycle`

  ### removeLifecycleListener

      public void removeLifecycleListener(LifecycleListener listener)

    Remove a LifecycleEvent listener from this component.

    Specified by:
      `removeLifecycleListener` in interface `Lifecycle`
    Parameters:
      `listener` - The listener to remove

  ### start

      public void start()
                 throws LifecycleException

    Prepare for the beginning of active use of the public methods of this component. This method should be called before any of the public methods of this component are utilized. It should also send a LifecycleEvent of type START_EVENT to any registered listeners.

    Specified by:
      `start` in interface `Lifecycle`
    Throws:
      `LifecycleException` - if this component detects a fatal error that prevents this component from being used

  ### stop

      public void stop()
                throws LifecycleException

    Gracefully terminate the active use of the public methods of this component. This method should be the last one called on a given instance of this component. It should also send a LifecycleEvent of type STOP_EVENT to any registered listeners.

    Specified by:
      `stop` in interface `Lifecycle`
    Throws:
      `LifecycleException` - if this component detects a fatal error that needs to be reported

  ### expose

      protected void expose(Request request,
                            Request actual)

    Expose the certificate chain for this request, if there is one.

    Parameters:
      `request` - The possibly wrapped Request being processed
      `actual` - The actual underlying Request object

  ### log

      protected void log(java.lang.String message)

    Log a message on the Logger associated with our Container (if any).

    Parameters:
      `message` - Message to be logged

  ### log

      protected void log(java.lang.String message,
                         java.lang.Throwable throwable)

    Log a message on the Logger associated with our Container (if any).

    Parameters:
      `message` - Message to be logged
      `throwable` - Associated exception

  ### verify

      protected void verify(Request request,
                            Request actual)

    Verify that a client certificate chain exists if our web application is doing client certificate authentication.

    Parameters:
      `request` - The possibly wrapped Request being processed
      `actual` - The actual underlying Request object

  Copyright ? 2000-2002 Apache Software Foundation. All Rights Reserved.