RSA BSAFE SSL-C

Security protocol components for C

Search

Shutdown Functions

This section describes the functions used to tailor the shutdown mechanism in SSL. The shutdown functions are used to close SSL connections when they are no longer required, when an error in the connection has occurred, or when an SSL structure is to be reused.

SSL-C supports three shutdown modes:

  • Normal.
  • Quiet.
  • Anytime.

    Normal shutdown is the default operation. A call to SSL_shutdown() results in a close_notify alert being raised after handshake completion. Quiet shutdown behaves similarly to normal shutdown however, shutdown handshake messages are not produced. Quiet shutdown is used for non-standard implementations of SSL-C where shutdown messages are not required. Anytime shutdown allows the shutdown protocol to be performed even when the handshake is not complete. If SSL_shutdown() is called, the handshake is aborted and shutdown occurs.

    Functions

    int SSL_CTX_set_quiet_shutdown (SSL_CTX *ctx, int mode)
     Sets the quiet shutdown mode for the SSL_CTX ctx. More...

    int SSL_CTX_get_quiet_shutdown (SSL_CTX *ctx)
     Returns the current setting of the quiet shutdown flag for the SSL_CTX connection ctx. More...

    int SSL_set_quiet_shutdown (SSL *ssl, int mode)
     Sets the SSL quiet shutdown mode for the SSL ssl. More...

    int SSL_get_quiet_shutdown (SSL *ssl)
     Returns the current setting of the quiet shutdown flag for the SSL connection ssl. More...

    int SSL_CTX_set_anytime_shutdown (SSL_CTX *ctx, int mode)
     Sets the anytime shutdown flag for the SSL_CTX ctx. More...

    int SSL_CTX_get_anytime_shutdown (SSL_CTX *ctx)
     Returns the current setting for the anytime shutdown flag for the SSL_CTX connection ctx. More...

    int SSL_set_anytime_shutdown (SSL *ssl, int mode)
     Sets the anytime shutdown mode for the SSL connection ssl. More...

    int SSL_get_anytime_shutdown (SSL *ssl)
     Returns the current setting for the anytime shutdown flag for the SSL connection ssl. More...

    int SSL_set_debug (SSL *ssl)
     Sets the debug mode on the SSL object. More...

    void SSL_set_shutdown (SSL *ssl, int mode)
     Sets the shutdown status defining which parts of the shutdown handshake have been performed. More...

    int SSL_get_shutdown (SSL *ssl)
     Returns the shutdown status defining which parts of the shutdown handshake have been performed. More...

    Function Documentation

    int SSL_CTX_get_anytime_shutdown (  SSL_CTX *    ctx )  ;
     

    Returns the current setting for the anytime shutdown flag for the SSL_CTX connection ctx.

    Parameters:
    ctx [In] The SSL_CTX connection reference.
    Returns:
    The shutdown mode. One of:
  • 0 indicates normal shutdown.
  • 1 indicates anytime shutdown.
    • note.gif
    This function is not used by SSLv2.
    See also:
    SSL_set_anytime_shutdown() and SSL_CTX_get_anytime_shutdown().

    int SSL_CTX_get_quiet_shutdown (  SSL_CTX *    ctx )  ;
     

    Returns the current setting of the quiet shutdown flag for the SSL_CTX connection ctx.

    Parameters:
    ctx [In] The SSL_CTX reference from which to retrieve the default shutdown setting.
    Returns:
    The shutdown mode. One of:
  • 0 indicates normal shutdown.
  • 1 indicates quiet shutdown.
    • note.gif
    The SSL_CTX reference must be valid. The SSL_CTX holds the default value for all SSL connection references.
    This function is not used by SSLv2.

    Quiet shutdown mode allows shutdowns for SSLv3 and TLSv1 connections to ignore proper shutdown handshake messages. This deviation from the SSLv3 standard may be required when dealing with non-standard implementations.

    See also:
    SSL_set_quiet_shutdown().

    int SSL_CTX_set_anytime_shutdown (  SSL_CTX *    ctx,
    int    mode
    )  ;
     

    Sets the anytime shutdown flag for the SSL_CTX ctx. This flag activates the option which allows the shutdown protocol to be performed even when the handshake is not complete. If SSL_shutdown() is called, the handshake is aborted and shutdown occurs.

    Parameters:
    ctx [In, Out] The SSL_CTX reference against which the default shutdown mode is set.
    mode [In] The shutdown mode. One of:
  • 0 indicates normal shutdown.
  • 1 indicates anytime shutdown.
    • note.gif
    This function is not used by SSLv2.
    See also:
    SSL_CTX_get_anytime_shutdown() and SSL_set_anytime_shutdown().

    int SSL_CTX_set_quiet_shutdown (  SSL_CTX *    ctx,
    int    mode
    )  ;
     

    Sets the quiet shutdown mode for the SSL_CTX ctx.

    Parameters:
    ctx [In, Out] The SSL_CTX reference.
    mode [In] The shutdown mode. One of:
  • 0 indicates normal shutdown.
  • 1 indicates quiet shutdown.
    • note.gif
    The mode is initially set to 0 and may be subsequently set to 0 or 1. The SSL_CTX holds the default value for all SSL connection references.
    This function is not used by SSLv2.

    Quiet shutdown mode allows shutdowns for SSLv3 and TLSv1 connections to ignore proper shutdown handshake messages. This deviation from the SSLv3 standard may be required when dealing with non-standard implementations.

    See also:
    SSL_CTX_get_quiet_shutdown().

    int SSL_get_anytime_shutdown (  SSL *    ssl )  ;
     

    Returns the current setting for the anytime shutdown flag for the SSL connection ssl.

    Parameters:
    ssl [In] The SSL connection reference from which to retrieve the shutdown mode.
    Returns:
    The shutdown mode. One of:
  • 0 indicates normal shutdown.
  • 1 indicates anytime shutdown.
    • note.gif
    This function is not used by SSLv2.
    See also:
    SSL_set_anytime_shutdown() and SSL_CTX_get_anytime_shutdown().

    int SSL_get_quiet_shutdown (  SSL *    ssl )  ;
     

    Returns the current setting of the quiet shutdown flag for the SSL connection ssl.

    Parameters:
    ssl [In] The SSL connection reference from which to retrieve the shutdown mode.
    Returns:
    The shutdown mode. One of:
  • 0 on normal shutdown.
  • 1 on quiet shutdown.
    • See also:
    SSL_set_quiet_shutdown().

    int SSL_get_shutdown (  SSL *    s )  ;
     

    Returns the shutdown status defining which parts of the shutdown handshake have been performed.

    Parameters:
    s [In] The SSL structure.
    Returns:
    The shutdown mode. One of:
  • 0 indicates no shutdown sent or received.
  • 1 SSL_SENT_SHUTDOWN.
  • 2 SSL_RECEIVED_SHUTDOWN.
  • 3 Shutdown sent and received.

    • int SSL_set_anytime_shutdown (  SSL *    ssl,
    int    mode
    )  ;
     

    Sets the anytime shutdown mode for the SSL connection ssl.

    Parameters:
    ssl [In, Out] The SSL connection reference against which the shutdown mode is set.
    mode [In] The shutdown mode. One of:
  • 0 indicates normal shutdown.
  • 1 indicates anytime shutdown.
    • note.gif
    This function is not used by SSLv2.
    See also:
    SSL_get_anytime_shutdown() and SSL_CTX_set_anytime_shutdown().

    int SSL_set_debug (  SSL *    ssl )  ;
     

    Sets the debug mode on the SSL object.

    Parameters:
    ssl [In] The SSL connection reference against which to set the debug mode.
    Returns:
  • 1 indicates success.
  • 0 indicates failure.

    • int SSL_set_quiet_shutdown (  SSL *    ssl,
    int    mode
    )  ;
     

    Sets the SSL quiet shutdown mode for the SSL ssl.

    Parameters:
    ssl [In, Out] The SSL connection reference against which the shutdown mode is set.
    mode [In] The shutdown mode. One of:
  • 0 indicates normal shutdown.
  • 1 indicates quiet shutdown.
    • note.gif
    The mode is initially set to 0 and may be subsequently set to 0 or 1.
    This function is not used by SSLv2.

    Quiet shutdown mode will allow shutdowns for SSLv3 and TLSv1 connections to ignore proper shutdown handshake messages. This deviation from the SSLv3 standard may be required when dealing with non-standard implementations.

    See also:
    SSL_get_quiet_shutdown().

    void SSL_set_shutdown (  SSL *    s,
    int    mode
    )  ;
     

    Sets the shutdown status defining which parts of the shutdown handshake have been performed.

    Parameters:
    s [In, Out] The SSL structure.
    mode [In] The shutdown mode. One of:
    0 No shutdown sent or received.
    1 SSL_SENT_SHUTDOWN.
    2 SSL_RECEIVED_SHUTDOWN.
    3 Shutdown sent and received.

    Copyright (c) 1999-2004 RSA Security Inc. All rights reserved. 050-001001-2600-000-000 - 2.6