RSA BSAFE Micro Edition Suite

Streamlined security for mobile and embedded devices
Search  Print

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...

    void SSL_set_shutdown (SSL *ssl, int mode)
     Sets the shutdown mode value in the SSL structure by directly accessing the ssl structure. More...

    int SSL_get_shutdown (SSL *ssl)
     Returns the shutdown mode value from the SSL structure by directly accessing the SSL structure. 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 *    ssl )  ;
     

    Returns the shutdown mode value from the SSL structure by directly accessing the SSL structure. The shutdown status defines the parts of the shutdown handshake that have been performed.

    Parameters:
    ssl [In] The SSL structure.
    Returns:
    The shutdown mode. One of:
    ModeDescription
    0 No shutdown sent or received
    1
    		SSL_SENT_SHUTDOWN
    2
    		SSL_RECEIVED_SHUTDOWN
    3
    		Shutdown sent and received
    See also:
    SSL_set_shutdown().

    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_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 *    ssl,
    int    mode
    )  ;
     

    Sets the shutdown mode value in the SSL structure by directly accessing the ssl structure. The shutdown status defines the parts of the shutdown handshake that have been performed.

    Parameters:
    ssl [In,Out] The SSL connection reference against which the shutdown mode is set.
    mode The shutdown mode. One of: >
    ModeDescription
    0No shutdown sent or received.
    1Close notify message has been sent.
    2Close notify message has been received.
    3Shutdown sent and received.
    note.gif
    ssl is not NULL.
    This function pre-empts the normal shutdown by manually setting the shutdown status.

    This function is not used by SSLv2.

    See also:
    SSL_get_shutdown().

    Copyright (c) 1999-2005 RSA Security Inc. All rights reserved. 072-001001-2100-001-000 - 2.1