libipmiconsole-dev 1.4.5-3 / usr / include / ipmiconsole.h

/*****************************************************************************\
 *  $Id: ipmiconsole.h,v 1.89 2010-08-03 00:10:59 chu11 Exp $
 *****************************************************************************
 *  Copyright (C) 2007-2012 Lawrence Livermore National Security, LLC.
 *  Copyright (C) 2006-2007 The Regents of the University of California.
 *  Produced at Lawrence Livermore National Laboratory (cf, DISCLAIMER).
 *  Written by Albert Chu <chu11@llnl.gov>
 *  UCRL-CODE-221226
 *
 *  This file is part of Ipmiconsole, a set of IPMI 2.0 SOL libraries
 *  and utilities.  For details, see http://www.llnl.gov/linux/.
 *
 *  Ipmiconsole is free software; you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by the
 *  Free Software Foundation; either version 3 of the License, or (at your
 *  option) any later version.
 *
 *  Ipmiconsole is distributed in the hope that it will be useful, but
 *  WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
 *  or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 *  for more details.
 *
 *  You should have received a copy of the GNU General Public License along
 *  with Ipmiconsole.  If not, see <http://www.gnu.org/licenses/>.
\*****************************************************************************/

#ifndef IPMICONSOLE_H
#define IPMICONSOLE_H

#ifdef __cplusplus
extern "C" {
#endif

#include <stdint.h>
#include <freeipmi/freeipmi.h>

/*
 * Libipmiconsole version
 *
 * MAJOR - Incremented when interfaces are changed or removed.
 *         Interfaces may be binary incompatible.  When incremented, MINOR
 *         and PATCH are zeroed.
 *
 * MINOR - Incremented when interfaces are added.  Interfaces are
 *         binary compatible with older minor versions.  When incremented,
 *         PATCH is zeroed.
 *
 * PATCH - Incremented when interfaces are not changed.  Typically
 *         incremented due to bug fixes or minor features.  Interfaces are
 *         forward and backward compatible to other PATCH versions.
 */

#define LIBIPMICONSOLE_VERSION_MAJOR 1
#define LIBIPMICONSOLE_VERSION_MINOR 2
#define LIBIPMICONSOLE_VERSION_PATCH 3

/*
 * IPMI Console Error Codes
 */
#define IPMICONSOLE_ERR_SUCCESS                               0
#define IPMICONSOLE_ERR_CTX_NULL                              1
#define IPMICONSOLE_ERR_CTX_INVALID                           2
#define IPMICONSOLE_ERR_ALREADY_SETUP                         3
#define IPMICONSOLE_ERR_NOT_SETUP                             4
#define IPMICONSOLE_ERR_CTX_NOT_SUBMITTED                     5
#define IPMICONSOLE_ERR_CTX_IS_SUBMITTED                      6
#define IPMICONSOLE_ERR_PARAMETERS                            7
#define IPMICONSOLE_ERR_HOSTNAME_INVALID                      8
#define IPMICONSOLE_ERR_IPMI_2_0_UNAVAILABLE                  9
#define IPMICONSOLE_ERR_CIPHER_SUITE_ID_UNAVAILABLE          10
#define IPMICONSOLE_ERR_USERNAME_INVALID                     11
#define IPMICONSOLE_ERR_PASSWORD_INVALID                     12
#define IPMICONSOLE_ERR_K_G_INVALID                          13
#define IPMICONSOLE_ERR_PRIVILEGE_LEVEL_INSUFFICIENT         14
#define IPMICONSOLE_ERR_PRIVILEGE_LEVEL_CANNOT_BE_OBTAINED   15
#define IPMICONSOLE_ERR_SOL_UNAVAILABLE                      16
#define IPMICONSOLE_ERR_SOL_INUSE                            17
#define IPMICONSOLE_ERR_SOL_STOLEN                           18
#define IPMICONSOLE_ERR_SOL_REQUIRES_ENCRYPTION              19
#define IPMICONSOLE_ERR_SOL_REQUIRES_NO_ENCRYPTION           20
#define IPMICONSOLE_ERR_BMC_BUSY                             21
#define IPMICONSOLE_ERR_BMC_ERROR                            22
#define IPMICONSOLE_ERR_BMC_IMPLEMENTATION                   23
#define IPMICONSOLE_ERR_CONNECTION_TIMEOUT                   24
#define IPMICONSOLE_ERR_SESSION_TIMEOUT                      25
#define IPMICONSOLE_ERR_EXCESS_RETRANSMISSIONS_SENT          26
#define IPMICONSOLE_ERR_EXCESS_ERRORS_RECEIVED               27
#define IPMICONSOLE_ERR_OUT_OF_MEMORY                        28
#define IPMICONSOLE_ERR_TOO_MANY_OPEN_FILES                  29
#define IPMICONSOLE_ERR_SYSTEM_ERROR                         30
#define IPMICONSOLE_ERR_INTERNAL_ERROR                       31
#define IPMICONSOLE_ERR_ERRNUMRANGE                          32

/*
 * Debug Flags
 *
 * Utilized with ipmiconsole_engine_init() or with struct
 * ipmiconsole_engine_config below for debugging.
 *
 * When used with ipmiconsole_engine_init(), enables debugging in
 * libipmiconsole global activities, such as the libipmiconsole engine
 * threads.
 *
 * When used with struct ipmiconsole_engine_config and a context,
 * enables debugging specific to an IPMI connection with a specific
 * host.
 *
 * STDOUT       - Output debugging to stdout
 * STDERR       - Output debugging to stderr
 * SYSLOG       - Output debugging to the Syslog
 * FILE         - Output debugging to files in current working directory
 * IPMI_PACKETS - Dump IPMI Packets too
 * DEFAULT      - Informs library to use default, may it be standard
 *                or configured via libipmiconsole.conf.
 */
#define IPMICONSOLE_DEBUG_STDOUT           0x00000001
#define IPMICONSOLE_DEBUG_STDERR           0x00000002
#define IPMICONSOLE_DEBUG_SYSLOG           0x00000004
#define IPMICONSOLE_DEBUG_FILE             0x00000008
#define IPMICONSOLE_DEBUG_IPMI_PACKETS     0x00000010
#define IPMICONSOLE_DEBUG_DEFAULT          0xFFFFFFFF

/*
 * IPMI Privilege Constants
 *
 * Utilized with struct ipmiconsole_ipmi_config below to specify a
 * privilege level to authenticate with.
 */
#define IPMICONSOLE_PRIVILEGE_USER                0
#define IPMICONSOLE_PRIVILEGE_OPERATOR            1
#define IPMICONSOLE_PRIVILEGE_ADMIN               2

/*
 * Workaround Flags
 *
 * Utilized with struct ipmiconsole_ipmi_config below to specify
 * workarounds for specific motherboard manufacturers.
 *
 * AUTHENTICATION_CAPABILITIES
 *
 * This workaround flag will skip early checks for username
 * capabilities, authentication capabilities, and K_g support and
 * allow IPMI authentication to succeed.  It works around multiple
 * issues in which the remote system does not properly report username
 * capabilities, authentication capabilities, or K_g status.
 *
 * INTEL_2_0_SESSION
 *
 * This workaround flag will work around several Intel IPMI 2.0
 * authentication issues.  The issues covered include padding of
 * usernames, automatic acceptance of a RAKP 4 response integrity
 * check when using the integrity algorithm MD5-128, and password
 * truncation if the authentication algorithm is HMAC-MD5-128.
 *
 * SUPERMICRO_2_0_SESSION
 *
 * This workaround option will work around several Supermicro IPMI 2.0
 * authentication issues on motherboards w/ Peppercon IPMI firmware.
 * The issues covered include handling invalid length authentication
 * codes.
 *
 * SUN_2_0_SESSION
 *
 * This workaround flag will work work around several Sun IPMI 2.0
 * authentication issues.  The issues covered include invalid lengthed
 * hash keys, improperly hashed keys, and invalid cipher suite
 * records.  This workaround automatically includes the
 * OPEN_SESSION_PRIVILEGE workaround.  
 *
 * OPEN_SESSION_PRIVILEGE
 * 
 * This workaround flag will slightly alter FreeIPMI's IPMI 2.0
 * connection protocol to workaround an invalid hashing algorithm used
 * by the remote system.  The privilege level sent during the Open
 * Session stage of an IPMI 2.0 connection is used for hashing keys
 * instead of the privilege level sent during the RAKP1 connection
 * stage.  This workaround is automatically triggered with the
 * SUN_2_0_SESSION workaround.
 *
 * NON_EMPTY_INTEGRITY_CHECK_VALUE
 *
 * This workaround option will work around an invalid integrity check
 * value during an IPMI 2.0 session establishment when using Cipher
 * Suite ID 0.  The integrity check value should be 0 length, however
 * the remote motherboard responds with a non-empty field.
 *
 * NO_CHECKSUM_CHECK
 *
 * This workaround option will work around motheboards that calculate
 * checksums incorrectly in IPMI command responses, but the packet is
 * otherwise valid.  Users are cautioned on the use of this option, as
 * it removes some validation of packet integrity.  However, it is
 * unlikely to be an issue in most situations.
 *
 * SERIAL_ALERTS_DEFERRED
 *
 * This workaround option will set serial alerts to be deferred
 * instead of have them be failures.  This works around motherboards
 * that perform IPMI over serial along with IPMI serial over LAN.
 *
 * INCREMENT_SOL_PACKET_SEQUENCE
 *
 * This workaround option will increment the SOL payload packet
 * sequence number under dire circumstances.  Normally SOL should
 * never do this, however some motherboards have shown to get "stuck"
 * due to an internal bug on the motherboard.  This workaround can
 * help in getting the BMC un-stuck.
 *
 * IGNORE_SOL_PAYLOAD_SIZE
 *
 * This workaround flag will not check for valid SOL payload sizes and
 * assume a proper set.  It works around remote systems that report
 * invalid IPMI 2.0 SOL payload sizes.
 *
 * IGNORE_SOL_PORT
 *
 * This workaround flag will ignore alternate SOL ports specified
 * during the protocol.  It works around remote systems that report
 * invalid alternate SOL ports.
 *
 * SKIP_SOL_ACTIVATION_STATUS
 *
 * This workaround flag will not check the current activation status
 * of SOL during the protocol setup.  It works around remote systems
 * that do not properly support this command.
 *
 * SKIP_CHANNEL_PAYLOAD_SUPPORT
 *
 * This workaround flag will skip the portion of the protocol that
 * checks if SOL is supported on the current channel.  It works around
 * remote systems that do not properly support this command.
 *
 * DEFAULT
 *
 * Informs library to use default, may it be the standard default or
 * a default configured via libipmiconsole.conf.
 *
 * Note: The non-logical bitmask order below is set for future
 * expansion and matching w/ libfreeipmi.
 */
#define IPMICONSOLE_WORKAROUND_AUTHENTICATION_CAPABILITIES     0x00000001
#define IPMICONSOLE_WORKAROUND_INTEL_2_0_SESSION               0x00000002
#define IPMICONSOLE_WORKAROUND_SUPERMICRO_2_0_SESSION          0x00000004
#define IPMICONSOLE_WORKAROUND_SUN_2_0_SESSION                 0x00000008
#define IPMICONSOLE_WORKAROUND_OPEN_SESSION_PRIVILEGE          0x00000010
#define IPMICONSOLE_WORKAROUND_NON_EMPTY_INTEGRITY_CHECK_VALUE 0x00000020
#define IPMICONSOLE_WORKAROUND_NO_CHECKSUM_CHECK               0x00000040
#define IPMICONSOLE_WORKAROUND_SERIAL_ALERTS_DEFERRED          0x00000080
#define IPMICONSOLE_WORKAROUND_INCREMENT_SOL_PACKET_SEQUENCE   0x00000100
#define IPMICONSOLE_WORKAROUND_IGNORE_SOL_PAYLOAD_SIZE         0x01000000
#define IPMICONSOLE_WORKAROUND_IGNORE_SOL_PORT                 0x02000000
#define IPMICONSOLE_WORKAROUND_SKIP_SOL_ACTIVATION_STATUS      0x04000000
#define IPMICONSOLE_WORKAROUND_SKIP_CHANNEL_PAYLOAD_SUPPORT    0x08000000
#define IPMICONSOLE_WORKAROUND_DEFAULT                         0xFFFFFFFF

/*
 * Engine Flags
 *
 * Utilized with struct ipmiconsole_engine_config below to alter
 * libipmiconsole engine behavior. 
 *
 * CLOSE_FD
 *
 * By default, the ipmiconsole engine will not close the file
 * descriptor (returned by ipmiconsole_ctx_fd()) when an error occurs
 * within the ipmiconsole engine (such as a session timeout).  A user
 * will subsequently see an EOF on a read() or an EPIPE on a write()
 * to know an error occurred.
 *
 * This flag will inform the engine to close the file descriptor on
 * error.  This will change the behavior of how the user should
 * program with the file descriptor.  For example, calls to read() and
 * write() would likely return with EBADF errors instead of EOF or
 * EPIPE errors respectively.  Calls to select() may return with EBADF
 * errors and calls to poll() could result in POLLNVAL returned
 * events.
 *
 * OUTPUT_ON_SOL_ESTABLISHED
 *
 * When submitting a context to the engine non-blocking, another way
 * to determine if the SOL session has been established is if data has
 * output from the remote console and is available for you to read.
 * Under most circumstances, this isn't a controllable situation.
 *
 * This flag will inform the engine to output a single NUL character
 * ('\0') to the console once a SOL session has been established.  If
 * the CLOSE_FD flag isn't used above, this would allow the user to
 * expect an EOF vs. 1 byte of data on a read() to determine if the
 * SOL session has failed or succeeded.  The user may choose to output
 * the NUL anyways (it should do no harm) or simply throw out the
 * first byte ever read from remote console.
 *
 * LOCK_MEMORY
 *
 * Inform libipmiconsole to lock memory to prevent sensitive
 * information (such as usernames and passwords) to be non-swappable.
 *
 * SERIAL_KEEPALIVE
 *
 * On some motherboards, it's been observed that IPMI connections
 * between the IPMI client and remote BMC/server can stay alive while
 * the remote server's internal connection between the BMC and serial
 * chip can be lost.  This has been observed under several situations, 
 * such as when the remote system is rebooted or a IPMI SOL session is
 * stolen.   
 *
 * The affect is that this loss of the serial connection will not be
 * noticed by the IPMI client until serial data is transfered from the
 * client to the BMC and a timeout (or similar error) eventually occurs.
 * The IPMI client must then reconnect to restablish the session.
 *
 * This is a severe problem for IPMI clients that predominantly log
 * serial data or display serial output without user interactivity.
 * From the IPMI client perspective, there is simply no output from
 * the serial port and no error has actually occurred.
 * 
 * This option will inform the libipmiconsole engine to send serial
 * keepalive packets in addition to the IPMI keepalive packets that
 * normally keep a connection alive.  The serial keepalive packets are
 * standard SOL payload packets, but contain a single NUL character in
 * them.  The single NUL character is to ensure that the underlying
 * serial receiver is alive and functioning.  Retransmission and
 * timeouts are handled identically to normal IPMI packets in the code
 * (e.g. as if somebody typed a character).  The serial keepalive
 * packets are dispatched if a SOL packet response has not been
 * received within the length of time of a session timeout.
 *
 * This option is highly recommended for IPMI clients that do not have
 * high user interactivity, as this may discover broken connections
 * far more quickly.  However, caution should be maintained, as the
 * NUL character byte may affect the remote system depending on what
 * input it may or may not be expecting.
 * 
 * SERIAL_KEEPALIVE_EMPTY
 *
 * This option is identical to SERIAL_KEEPALIVE, except that the
 * serial keepalive packets are empty and without character data.  On
 * some motherboards, this may be sufficient to deal with the "serial
 * keepalive" issue and character data need not be sent with each
 * packet.  On some systems though, a SOL packet without character
 * data may not be ACKed, and therefore the keepalive fails.
 *
 * DEFAULT
 *
 * Informs library to use default, may it be the standard default or
 * a default configured via libipmiconsole.conf.
 */
#define IPMICONSOLE_ENGINE_CLOSE_FD                  0x00000001
#define IPMICONSOLE_ENGINE_OUTPUT_ON_SOL_ESTABLISHED 0x00000002
#define IPMICONSOLE_ENGINE_LOCK_MEMORY               0x00000004
#define IPMICONSOLE_ENGINE_SERIAL_KEEPALIVE          0x00000008
#define IPMICONSOLE_ENGINE_SERIAL_KEEPALIVE_EMPTY    0x00000010
#define IPMICONSOLE_ENGINE_DEFAULT                   0xFFFFFFFF

/*
 * Behavior Flags
 *
 * Utilized with struct ipmiconsole_protocol_config below to atler
 * SOL connection behavior.
 *
 * ERROR_ON_SOL_INUSE
 *
 * Under most circumstances, if SOL is detected as being in use,
 * libipmiconsole will attempt to deactivate the earlier SOL session
 * and activate the SOL session under the current one.  This default
 * behavior exists for several reasons, most notably that earlier SOL
 * sessions may have not been able to be deactivated properly.  This
 * security flag changes the default behavior to return an error if
 * SOL is already detected as being in use.  If it is detected as in
 * use, the errnum returned from ipmiconsole_ctx_errnum() would be
 * IPMICONSOLE_ERR_SOL_INUSE.
 *
 * DEACTIVATE_ONLY
 *
 * Only attempt to deactivate the SOL session.  If an SOL session is
 * not active, do nothing.
 *
 * DEACTIVATE_ALL_INSTANCES
 *
 * When a SOL session is deactivated via the DEACTIVATE_ONLY flag,
 * only the currently configured SOL payload instance will be
 * deactivated, not any other instance.  This flag will inform
 * libipmiconsole to deactivate all presently activated instances.
 * This may be useful in a few circumstances where a user might want
 * to deactivate all current sessions.
 * 
 * DEFAULT
 *
 * Informs library to use default, may it be the standard default or
 * a default configured via libipmiconsole.conf.
 */
#define IPMICONSOLE_BEHAVIOR_ERROR_ON_SOL_INUSE       0x00000001
#define IPMICONSOLE_BEHAVIOR_DEACTIVATE_ONLY          0x00000002
#define IPMICONSOLE_BEHAVIOR_DEACTIVATE_ALL_INSTANCES 0x00000004
#define IPMICONSOLE_BEHAVIOR_DEFAULT                  0xFFFFFFFF

/*
 * Context Status
 *
 * Returned by ipmiconsole_ctx_status() below.
 *
 * ERROR
 *
 * An error has occurred retrieving the status.
 *
 * NOT_SUBMITTED
 *
 * The context has not been submitted to the engine.
 *
 * SUBMITTED
 *
 * The context has been submitted to the engine.  SOL has not been
 * established and an error has not yet occurred.
 *
 * SOL_ERROR
 *
 * The context has received an error during SOL establishment.
 *
 * SOL_ESTABLISHED
 *
 * The context has established a SOL session.
 *
 */
enum ipmiconsole_ctx_status
{
  IPMICONSOLE_CTX_STATUS_ERROR = -1,
  IPMICONSOLE_CTX_STATUS_NOT_SUBMITTED = 0,
  IPMICONSOLE_CTX_STATUS_SUBMITTED = 1,
  IPMICONSOLE_CTX_STATUS_SOL_ERROR = 2,
  IPMICONSOLE_CTX_STATUS_SOL_ESTABLISHED = 3,
};
typedef enum ipmiconsole_ctx_status ipmiconsole_ctx_status_t;

/*
 * ipmiconsole_ipmi_config
 *
 * IPMI configuration for a connection to a remote IPMI machine.
 * Defaults can be modified using the libipmiconsole.conf file.
 *
 * username
 *
 *   BMC username. Pass NULL ptr for default username.  Standard
 *   default is the null (e.g. empty) username.  Maximum length of 16
 *   bytes.
 *
 * password
 *
 *   BMC password. Pass NULL ptr for default password.  Standard
 *   default is the null (e.g. empty) password.  Maximum length of 20
 *   bytes.
 *
 * k_g
 *
 *   BMC Key for 2-key authentication.  Pass NULL ptr to use the
 *   default.  Standard default is the null (e.g. empty) k_g,
 *   which will use the password as the BMC key.  The k_g key need not
 *   be an ascii string.
 *
 * k_g_len
 *
 *   Length of k_g.  Necessary b/c k_g may contain null values in its
 *   key.  Maximum length of 20 bytes.
 *
 * privilege_level
 *
 *   privilege level to authenticate with.
 *
 *   Supported privilege levels:
 *
 *   IPMICONSOLE_PRIVILEGE_USER
 *   IPMICONSOLE_PRIVILEGE_OPERATOR
 *   IPMICONSOLE_PRIVILEGE_ADMIN
 *
 *   Pass < 0 for default.  Standard default is
 *   IPMICONSOLE_PRIVILEGE_ADMIN.
 *
 * cipher_suite_id
 *
 *   Cipher suite identifier to determine authentication, integrity,
 *   and confidentiality algorithms to use.
 *
 *   Supported Cipher Suite IDs
 *   (Key: A - Authentication Algorithm
 *         I - Integrity Algorithm
 *         C - Confidentiality Algorithm)
 *
 *   0 - A = None; I = None; C = None
 *   1 - A = HMAC-SHA1; I = None; C = None
 *   2 - A = HMAC-SHA1; I = HMAC-SHA1-96; C = None
 *   3 - A = HMAC-SHA1; I = HMAC-SHA1-96; C = AES-CBC-128
 *   6 - A = HMAC-MD5; I = None; C = None
 *   7 - A = HMAC-MD5; I = HMAC-MD5-128; C = None
 *   8 - A = HMAC-MD5; I = HMAC-MD5-128; C = AES-CBC-128
 *   11 - A = HMAC-MD5; I = MD5-128; C = None
 *   12 - A = HMAC-MD5; I = MD5-128; C = AES-CBC-128
 *   15 - A = HMAC-SHA256; I = None; C = None
 *   16 - A = HMAC-SHA256; I = HMAC-SHA256-128; C = None
 *   17 - A = HMAC-SHA256; I = HMAC-SHA256-128; C = AES-CBC-128
 *
 *   Pass < 0 for default.  Standard default is 3.
 *
 * workaround_flags
 *
 *   Bitwise OR of flags indicating IPMI implementation changes.  Some
 *   BMCs which are non-compliant and may require a workaround flag
 *   for correct operation. Pass IPMICONSOLE_WORKAROUND_DEFAULT for
 *   default.  Standard default is 0, no modifications to the IPMI
 *   protocol.
 */
struct ipmiconsole_ipmi_config
{
  char *username;
  char *password;
  unsigned char *k_g;
  unsigned int k_g_len;
  int privilege_level;
  int cipher_suite_id;
  unsigned int workaround_flags;
};

/*
 * ipmiconsole_protocol_config
 *
 * Configuration information for the IPMI protocol management.
 * Defaults can be modified using the libipmiconsole.conf file.
 *
 * session_timeout_len
 *
 *   Specifies the session timeout length in milliseconds.  Pass <= 0
 *   for default.  Standard default is 60000 (60 seconds).
 *
 * retransmission_timeout_len
 *
 *   Specifies the packet retransmission timeout length in
 *   milliseconds.  Pass <= 0 for default.  Standard default is
 *   500 (0.5 seconds).
 *
 * retransmission_backoff_count
 *
 *   Specifies the packet retransmission count until retransmission
 *   timeout lengths will be backed off.  Pass <= 0 for default.
 *   Standard default is 2.
 *
 * keepalive_timeout_len
 *
 *   Specifies the session timeout length in milliseconds until a
 *   keepalive packet is sent.  Pass <= 0 for default.  Standard
 *   default is 20000 (20 seconds).
 *
 * retransmission_keepalive_timeout_len
 *
 *   Specifies the keepalive packet retransmission timeout length in
 *   milliseconds.  Pass <= 0 for default.  Standard default is
 *   5000 (5 seconds).
 *
 * acceptable_packet_errors_count
 *
 *   Specifies the maximum number of consecutive packet errors that
 *   can be received from a remote BMC before an error is returned and
 *   the session ended.  Pass <= 0 for default.  Standard
 *   default is 16.
 *
 *   Note: This has been added to the behavior of the IPMI engine due
 *   to issues where remote BMCs can become "un-synced" with sequence
 *   numbers due to a network kernel boot.  It is possible a stream of
 *   packets can be sent to the remote client with session sequence
 *   numbers that are excessively outside of the acceptable window
 *   range.
 *
 * maximum_retransmission_count
 *
 *   Specifies the maximum number of retransmissions that can be sent
 *   for any IPMI packet before an error is returned and the session
 *   ended.  Pass <= 0 for default.  Standard default is 16.
 *
 *   Note: This has been added to the behavior of the IPMI engine due
 *   to issues where remote BMCs can become "un-synced" with sequence
 *   numbers due to a network kernel boot.  It is possible for some
 *   packets (in particular 'ping' packets to keep an IPMI session
 *   alive) to be accepted by the remote BMC, but not SOL packets.
 *
 */
struct ipmiconsole_protocol_config
{
  int session_timeout_len;
  int retransmission_timeout_len;
  int retransmission_backoff_count;
  int keepalive_timeout_len;
  int retransmission_keepalive_timeout_len;
  int acceptable_packet_errors_count;
  int maximum_retransmission_count;
};

/*
 * ipmiconsole_engine_config
 *
 * Configuration information for how the engine should interact with
 * the user or API.  Defaults can be modified using the
 * libipmiconsole.conf file.
 *
 * engine_flags
 *
 *   Bitwise OR of flags indicating how the ipmiconsole engine should
 *   behave for a particular context.  Pass IPMICONSOLE_ENGINE_DEFAULT
 *   for default.  Standard default is 0.
 *
 * behavior_flags
 *
 *   Bitwise OR of flags indicating any protocol behavior that should
 *   be changed from the default.  Pass IPMICONSOLE_BEHAVIOR_DEFAULT
 *   for default.  Standard default is 0.
 *
 * debug_flags
 *
 *   Bitwise OR of flags indicating how debug output should (or should
 *   not) be output. Pass IPMICONSOLE_DEBUG_DEFAULT for default.
 *   Standard default is 0.
 *
 */
struct ipmiconsole_engine_config
{
  unsigned int engine_flags;
  unsigned int behavior_flags;
  unsigned int debug_flags;
};

/*
 * Context Config Option
 *
 * Used for setting or getting advanced configuration options.  See
 * ipmiconsole_ctx_set_config_option() and
 * ipmiconsole_ctx_get_config_option().
 *
 * SOL_PAYLOAD_INSTANCE
 *
 * The SOL payload instance number to be used.  Defaults to 1 and has
 * range of 1 to 15.  Most systems only support a single instance,
 * however a few allow users to access multiple.  They could be used
 * to allow multiple users to see the same serial session, or allow
 * users to access different serial sessions behind a device.  It is
 * not commonly available or necessary when communicating via SOL to a
 * single server.  The SOL payload instance number is specified and
 * retrieved via a pointer to an unsigned int.
 *
 */
enum ipmiconsole_ctx_config_option
{
  IPMICONSOLE_CTX_CONFIG_OPTION_SOL_PAYLOAD_INSTANCE = 0,
};
typedef enum ipmiconsole_ctx_config_option ipmiconsole_ctx_config_option_t;

#define IPMICONSOLE_THREAD_COUNT_MAX       32

typedef struct ipmiconsole_ctx *ipmiconsole_ctx_t;

/*
 * Ipmiconsole_callback
 *
 * Function prototype for a callback function.
 * ipmiconsole_engine_submit() below.
 */
typedef void (*Ipmiconsole_callback)(void *);

/*
 * ipmiconsole_engine_init
 *
 * Initialize the ipmiconsole engine.  Engine threads will be created
 * which will manage SOL sessions for the user.  This function must be
 * called before ipmi console contexts can be submitted into the
 * engine.  This call will also parse and load alternate defaults from
 * the libipmiconsole.conf defaults file.
 *
 * Parameters:
 *
 * thread_count
 *
 *   Number of threads the engine will support.  Pass 0 for default of 4.
 *
 * debug_flags
 *
 *   Bitwise OR of flags indicating how debug output should (or should
 *   not) be output. Pass 0 for default of no debugging.
 *
 * Returns 0 on success, -1 on error.  On error errno will be set to
 * indicate error.  Possible errnos are ENOMEM if memory cannot be
 * allocated.
 */
int ipmiconsole_engine_init (unsigned int thread_count,
                             unsigned int debug_flags);

/*
 * ipmiconsole_engine_submit
 *
 * Submit a context to the ipmiconsole engine non-blocking.  This
 * function can return prior to a SOL session being established.  A
 * return value of 0 indicates the context was submitted properly.  A
 * return value of -1 indicates an error occurred during the
 * submission.  On an error, ipmiconsole_ctx_errnum() can be used to
 * determine the type of error that occured.
 *
 * After a context has been submitted, the user may determine if a SOL
 * session has been established several ways:
 *
 * A) Poll on the context status, retrieved via
 * ipmiconsole_ctx_status().  On an error, ipmiconsole_ctx_errnum()
 * can be used to determine the specific IPMI related error that
 * occurred.
 *
 * B) Poll on the context file descriptor, retrieved via
 * ipmiconsole_ctx_fd().  A SOL establishment error will result in an
 * EOF being returned on the file descriptor.  A proper SOL
 * establishment can be determined via a readable character on the
 * file descriptor.  The use of the OUTPUT_ON_SOL_ESTABLISHED Engine
 * flag above can aid in this.  The CLOSE_FD Engine flag can be set to
 * slightly alter this behavior, please see above. On an error,
 * ipmiconsole_ctx_errnum() can be used to determine the specific IPMI
 * related error that occurred.
 *
 * C) Specify a callback function.  The callback function specified as
 * a parameter below will be called directly after a SOL session has
 * been established or a session establishment error has occurred
 * (e.g. SOL not supported, authentication error, etc.).  Within those
 * callback functions, ipmiconsole_ctx_status() can be used to
 * determine which has occurred.  This callback will be called by the
 * engine thread, therefore users may need to protect their
 * application's shared data.
 *
 * Due to the non-blocking semantics of this function, it is possible
 * that multiple errors could occur simultaneously and the errnum
 * retrieved via ipmiconsole_ctx_errnum() may not be the one that
 * caused the SOL session to fail.  However, this will not occur given
 * proper usage of the API.  For example, if the user called
 * ipmiconsole_engine_submit() twice with the same context, an SOL
 * error in the engine background could race with the setting of the
 * errnum IPMICONSOLE_ERR_CTX_IS_SUBMITTED in the second call.
 *
 * Parameters:
 *
 * callback
 *
 *   If specified, a callback function will be called from the engine
 *   when a SOL session has been established or a SOL establishment
 *   error has occurred.  Will only be called under a non-blocking
 *   engine submission via ipmiconsole_engine_submit().  Will be
 *   called once and only once during an individual engine submission.
 *   For example, if a SOL session is established then a later session
 *   timeout occurs, the later session timeout will not generate a
 *   function call to the callback.  Pass NULL for no callback.
 *
 *   The callback function can be called simultaneously from different
 *   engine threads.  It is the user's responsibility to protect
 *   against any race conditions in their callback function.
 *
 * callback_arg
 *
 *   Specify an arbitrary argument to be passed to the callback
 *   routine.  If the callback will be required to process the context
 *   status, the context should be included in this argument.
 *
 * Returns 0 on success, -1 on error.  ipmiconsole_ctx_errnum() can be
 * called to determine the cause of the error.
 */
int ipmiconsole_engine_submit (ipmiconsole_ctx_t c,
                               Ipmiconsole_callback callback,
                               void *callback_arg);

/*
 * ipmiconsole_engine_submit_block
 *
 * Submit a context to the ipmiconsole engine and block until a SOL
 * session is established or an error/timeout occurs.  A return value
 * of 0 indicates the SOL session was established and a -1 indicates
 * an error occurred.  On an error, ipmiconsole_ctx_errnum() can be
 * used to determine the type of error that occured.
 *
 * Returns 0 on success, -1 on error.  ipmiconsole_ctx_errnum() can be
 * called to determine the cause of the error.
 */
int ipmiconsole_engine_submit_block (ipmiconsole_ctx_t c);

/*
 * ipmiconsole_engine_teardown
 *
 * Teardown the ipmiconsole engine.  This function will destroy
 * all threads and contexts managed by the engine.
 *
 * Parameters:
 *
 * cleanup_sol_sessions
 *
 *   If set to non zero, SOL sessions will be torn down cleanly.
 *   ipmiconsole_engine_teardown() will block until all active ipmi
 *   sessions have been closed cleanly or timed out.
 */
void ipmiconsole_engine_teardown (int cleanup_sol_sessions);

/*
 * ipmiconsole_ctx_create
 *
 * Create an ipmiconsole context.  The context can then be submitted
 * into the ipmiconsole engine (via ipmiconsole_engine_submit() or
 * ipmiconsole_engine_submit_block()) to establish a SOL session.  The
 * context cannot be submitted to the ipmiconsole engine more than
 * once.  After it has been submitted to the ipmiconsole engine, it
 * cannot be reused.
 *
 * Parameters:
 *
 * hostname
 *
 *   Host or IP address you wish to connect to.
 *
 * ipmi_config
 *
 *   IPMI configuration.  See ipmiconsole_ipmi_config definition
 *   above.
 *
 * protocol_config
 *
 *   IPMI protocol configuration.  See ipmiconsole_protocol_config
 *   definition above.
 *
 * engine_config
 *
 *   Ipmiconsole engine configuration.  See ipmiconsole_engine_config
 *   definition above.
 *
 * Returns ctx on success, NULL on error.  On error errno will be set to
 * indicate error.  Possible errnos are EINVAL on invalid input,
 * ENOMEM if memory cannot be allocated, EMFILE if process file
 * descriptors limits have been reached, and EAGAIN if
 * ipmiconsole_engine_init() has not yet been called.
 */
ipmiconsole_ctx_t ipmiconsole_ctx_create (const char *hostname,
                                          struct ipmiconsole_ipmi_config *ipmi_config,
                                          struct ipmiconsole_protocol_config *protocol_config,
                                          struct ipmiconsole_engine_config *engine_config);

/*
 * ipmiconsole_ctx_set_config
 *
 * Set the value of an advanced configuration value.  This
 * configuration value must be set prior to a context being submitted
 * to the ipmiconsole engine (via ipmiconsole_engine_submit() or
 * ipmiconsole_engine_submit_block()).  After it has been submitted to
 * the ipmiconsole engine, it cannot be changed.
 *
 * See enum ipmiconsole_ctx_config_option above for config options and
 * pointer types expected by this function.
 *
 * Returns 0 on success, -1 on error.  ipmiconsole_ctx_errnum() can be
 * called to determine the cause of the error.
 */
int ipmiconsole_ctx_set_config (ipmiconsole_ctx_t c,
				ipmiconsole_ctx_config_option_t config_option,
                                void *config_option_value);
/*
 * ipmiconsole_ctx_get_config
 *
 * Get the value of an advanced configuration value.
 *
 * See enum ipmiconsole_ctx_config_option above for config options and
 * pointer types expected by this function.
 *
 * Returns 0 on success, -1 on error.  ipmiconsole_ctx_errnum() can be
 * called to determine the cause of the error.
 */
int ipmiconsole_ctx_get_config (ipmiconsole_ctx_t c,
				ipmiconsole_ctx_config_option_t config_option,
                                void *config_option_value);

/*
 * ipmiconsole_ctx_errnum
 *
 * Returns the errnum of the most recently recorded error for the
 * context that has not yet been read by the user.
 */
int ipmiconsole_ctx_errnum (ipmiconsole_ctx_t c);

/*
 * ipmiconsole_ctx_strerror
 *
 * Returns a pointer to statically allocated string describing the
 * error code in errnum.
 */
char *ipmiconsole_ctx_strerror (int errnum);

/*
 * ipmiconsole_ctx_errormsg
 *
 * Returns a pointer to statically allocated string describing the
 * most recent error for the context.
 */
char *ipmiconsole_ctx_errormsg (ipmiconsole_ctx_t c);

/*
 * ipmiconsole_ctx_status
 *
 * Returns the current context status.  Primarily used to determine if
 * a context submission (submitted non-blocking via
 * ipmiconsole_engine_submit()) has been established or not.  Returns
 * IPMICONSOLE_CTX_STATUS_ERROR (-1) on error.
 */
ipmiconsole_ctx_status_t ipmiconsole_ctx_status (ipmiconsole_ctx_t c);

/*
 * ipmiconsole_ctx_fd
 *
 * Returns a file descriptor for console reading and writing after it
 * has been submitted to the engine.  Returns -1 on error.
 * ipmiconsole_ctx_errnum() can be called to determine the cause of
 * the error.
 *
 * If the user closes the file descriptor while the serial over lan
 * session is established, the session will be torn down in the
 * engine.
 *
 * If an error occurs on the engine side (for example a session
 * timeout) the other end of the file descriptor pair (from which this
 * fd is a part of) will be closed.  The error can be determined via
 * ipmiconsole_ctx_errnum().  The user of this file descriptor will
 * typically see this affect via an EOF on a read() or an EPIPE on a
 * write().  For alternate file descriptor behavior, see ENGINE flags
 * above.
 */
int ipmiconsole_ctx_fd (ipmiconsole_ctx_t c);

/*
 * ipmiconsole_ctx_generate_break
 *
 * Generate a break on an active serial over LAN session.
 *
 * Returns 0 on success, -1 on error.  ipmiconsole_ctx_errnum() can be
 * called to determine the cause of the error.
 */
int ipmiconsole_ctx_generate_break (ipmiconsole_ctx_t c);

/*
 * ipmiconsole_ctx_destroy
 *
 * Destroy a context.  Will close file descriptor retrieved from
 * ipmiconsole_ctx_fd().
 */
void ipmiconsole_ctx_destroy (ipmiconsole_ctx_t c);

/*
 * ipmiconsole_username_is_valid
 *
 * Convenience function to determine if a username is valid. Note that
 * a NULL pointer, which would result in libipmiconsole using a
 * default value, is considered an invalid input here.
 *
 * Returns 1 if username is valid, 0 if it is not.
 */
int ipmiconsole_username_is_valid (const char *username);

/*
 * ipmiconsole_password_is_valid
 *
 * Convenience function to determine if a password is valid.  Note
 * that a NULL pointer, which would result in libipmiconsole using a
 * default value, is considered an invalid input here.
 *
 * Returns 1 if password is valid, 0 if it is not.
 */
int ipmiconsole_password_is_valid (const char *password);

/*
 * ipmiconsole_k_g_is_valid
 *
 * Convenience function to determine if a k_g is valid.  Note that a
 * NULL pointer, which would result in libipmiconsole using a default
 * value, is considered an invalid input here.
 *
 * Returns 1 if k_g is valid, 0 if it is not.
 */
int ipmiconsole_k_g_is_valid (const unsigned char *k_g, unsigned int k_g_len);

/*
 * ipmiconsole_privilege_level_is_valid
 *
 * Convenience function to determine if a privilege level is valid.
 * Note that a negative value, which would result in libipmiconsole
 * using a default value, is considered an invalid input here.
 *
 * Returns 1 if privilege level is valid, 0 if it is not.
 */
int ipmiconsole_privilege_level_is_valid (int privilege_level);

/*
 * ipmiconsole_cipher_suite_id_is_valid
 *
 * Convenience function to determine if a cipher suite id is valid.
 * Note that a negative value, which would result in libipmiconsole
 * using a default value, is considered an invalid input here.
 *
 * Returns 1 if cipher suite id is valid, 0 if it is not.
 */
int ipmiconsole_cipher_suite_id_is_valid (int cipher_suite_id);

/*
 * ipmiconsole_workaround_flags_is_valid
 *
 * Convenience function to determine if workaround flags are valid.
 * Note that a bitmask value of IPMICONSOLE_WORKAROUND_DEFAULT, which
 * would result in libipmiconsole using a default value, is considered
 * an invalid input here.
 *
 * Returns 1 if workaround flags are valid, 0 if they are not.
 */
int ipmiconsole_workaround_flags_is_valid (unsigned int workaround_flags);

#ifdef __cplusplus
}
#endif

#endif /* IPMICONSOLE_H */