diplodocus.org Git - nmh/blob - h/netsec.h

   1 /*
   2  * Network security library routines for nmh.
   3  *
   4  * These are a common set of routines to handle network security for
   5  * things like SASL and OpenSSL.
   6  */
   7
   8 struct _netsec_context;
   9 typedef struct _netsec_context netsec_context;
  10
  11 /*
  12  * Create a network security context.  Returns the allocated network
  13  * security context.  Cannot fail.
  14  */
  15
  16 netsec_context *netsec_init(void);
  17
  18 /*
  19  * Shuts down the security context for a connection and frees all
  20  * associated resources.
  21  *
  22  * Arguments:
  23  *
  24  * ns_context   - Network security context
  25  * closeflag    - If set to 1, close the socket descriptor as well.
  26  */
  27
  28 void netsec_shutdown(netsec_context *ns_context, int closeflag);
  29
  30 /*
  31  * Sets the file descriptor for this connection.  This will be used by
  32  * the underlying communication.
  33  *
  34  * Arguments:
  35  *
  36  * ns_context   - Network security context
  37  * fd           - File descriptor of network connection.
  38  */
  39
  40 void netsec_set_fd(netsec_context *ns_context, int fd);
  41
  42 /*
  43  * Set the userid used to authenticate to this connection.
  44  *
  45  * Arguments:
  46  *
  47  * ns_context   - Network security context
  48  * userid       - Userid to be used for authentication.  Cannot be NULL.
  49  */
  50
  51 void netsec_set_userid(netsec_context *ns_context, const char *userid);
  52
  53 /*
  54  * Returns "snoop" status on current connection.
  55  *
  56  * Arguments:
  57  *
  58  * ns_context   - Network security context
  59  *
  60  * Returns "1" if snoop is enabled, 0 if it is not.
  61  */
  62
  63 int netsec_get_snoop(netsec_context *ns_context);
  64
  65 /*
  66  * Sets "snoop" status; if snoop is set to a nonzero value, network traffic
  67  * will be logged on standard error.
  68  *
  69  * Arguments:
  70  *
  71  * ns_context   - Network security context
  72  * snoop        - Integer value; set to nonzero to enable traffic logging
  73  */
  74
  75 void netsec_set_snoop(netsec_context *ns_context, int snoop);
  76
  77 /*
  78  * A callback designed to handle the snoop output; it can be used by
  79  * a protocol to massage the data in a more user-friendly way.
  80  *
  81  * Arguments:
  82  *
  83  * ns_context   - Network security context
  84  * string       - String to output
  85  * len          - Length of string
  86  */
  87
  88 typedef void (*netsec_snoop_callback)(netsec_context *ns_context,
  89                                      const char *string, size_t len);
  90
  91 /*
  92  * Set the read timeout for this connection.
  93  *
  94  * Arguments:
  95  *
  96  * ns_context   - Network security context
  97  * timeout      - Read timeout, in seconds.
  98  */
  99
 100 void netsec_set_timeout(netsec_context *ns_context, int timeout);
 101
 102 /*
 103  * Read a "line" from the network.  This reads one CR/LF terminated line.
 104  * Returns a pointer to a NUL-terminated string.  This memory is valid
 105  * until the next call to any read function.  Will return an error if
 106  * the line does not terminate with a CR/LF.
 107  *
 108  * Arguments:
 109  *
 110  * ns_context   - Network security context
 111  * length       - Returned length of string
 112  * errstr       - Error string
 113  *
 114  * Returns pointer to string, or NULL on error.
 115  */
 116
 117 char *netsec_readline(netsec_context *ns_context, size_t *lenght,
 118                       char **errstr);
 119
 120 /*
 121  * Read bytes from the network.
 122  *
 123  * Arguments:
 124  *
 125  * ns_context   - Network security context
 126  * buffer       - Read buffer
 127  * size         - Buffer size
 128  * errstr       - Error size
 129  *
 130  * Returns number of bytes read, or -1 on error.
 131  */
 132
 133 ssize_t netsec_read(netsec_context *ns_context, void *buffer, size_t size,
 134                     char **errstr);
 135
 136 /*
 137  * Write data to the network; if encryption is being performed, we will
 138  * do it.  Data may be buffered; use netsec_flush() to flush any outstanding
 139  * data to the network.
 140  *
 141  * Arguments:
 142  *
 143  * ns_context   - Network security context
 144  * buffer       - Output buffer to write to network
 145  * size         - Size of data to write to network
 146  * errstr       - Error string
 147  *
 148  * Returns OK on success, NOTOK otherwise.
 149  */
 150
 151 int netsec_write(netsec_context *ns_context, const void *buffer, size_t size,
 152                  char **errstr);
 153
 154 /*
 155  * Write bytes using printf formatting
 156  *
 157  * Arguments:
 158  *
 159  * ns_context   - Network security context
 160  * errstr       - Error string
 161  * format       - Format string
 162  * ...          - Arguments for format string
 163  *
 164  * Returns OK on success, NOTOK on error.
 165  */
 166
 167 int netsec_printf(netsec_context *ns_context, char **errstr,
 168                   const char *format, ...);
 169
 170 /*
 171  * Write bytes using a va_list argument.
 172  *
 173  * Arguments:
 174  *
 175  * ns_context   - Network security context
 176  * errstr       - Error string
 177  * format       - Format string
 178  * ap           - stdarg list.
 179  *
 180  * Returns OK on success, NOTOK on error.
 181  */
 182
 183 int netsec_vprintf(netsec_context *ns_context, char **errstr,
 184                    const char *format, va_list ap);
 185
 186 /*
 187  * Flush any buffered bytes to the network.
 188  *
 189  * Arguments:
 190  *
 191  * ns_context   - Network security context
 192  * errstr       - Error string
 193  *
 194  * Returns OK on success, NOTOK on error.
 195  */
 196
 197 int netsec_flush(netsec_context *ns_context, char **errstr);
 198
 199 /*
 200  * Enumerated types for the type of message we are sending/receiving.
 201  */
 202
 203 enum sasl_message_type {
 204         NETSEC_SASL_START,      /* Start of SASL authentication */
 205         NETSEC_SASL_READ,       /* Reading a message */
 206         NETSEC_SASL_WRITE,      /* Writing a message */
 207         NETSEC_SASL_FINISH,     /* Complete SASL exchange */
 208         NETSEC_SASL_CANCEL      /* Cancel a SASL exchange */
 209 };
 210
 211 /*
 212  * The SASL callback; this is designed to parse a protocol-specific
 213  * message and return the SASL protocol message back.
 214  *
 215  * The meaning of the arguments to the callback depend on the mtype
 216  * arguments.  See below for more detail.
 217  *
 218  * Arguments:
 219  *
 220  * mtype        - The type of message we are processing (read/write/cancel).
 221  * indata       - A pointer to any input data.
 222  * indatasize   - The size of the input data in bytes
 223  * outdata      - Output data (freed by caller)
 224  * outdatasize  - Size of output data
 225  * errstr       - An error string to be returned (freed by caller).
 226  *
 227  * As a general note, plugins should perform their own I/O.  Buffers returned
 228  * by NETSEC_SASL_READ should be allocated by the plugins and will be freed
 229  * by the netsec package.  Error messages returned should be created by
 230  * netsec_err().
 231  *
 232  * Parameter interpretation based on mtype value:
 233  *
 234  * NETSEC_SASL_START    - Create a protocol message that starts SASL
 235  *                        authentication.  If an initial response is
 236  *                        supported, indata and indatasize will contain it.
 237  *                        Otherwise they will be set to NULL and 0.
 238  * NETSEC_SASL_READ     - Parse and decode a protocol message and extract
 239  *                        out the SASL payload data.  indata will be set
 240  *                        to NULL; the callback must read in the necessary
 241  *                        data using the appropriate netsec function.
 242  *                        outdata/outdatasize should contain the decoded
 243  *                        SASL message (again, must be free()d by the caller).
 244  * NETSEC_SASL_WRITE    - Generate a protocol message to send over the
 245  *                        network.  indata/indatasize will contain the
 246  *                        SASL payload data.
 247  * NETSEC_SASL_FINISH   - Process the final SASL message exchange; at
 248  *                        this point SASL exchange should have completed
 249  *                        and we should get a message back from the server
 250  *                        telling us whether or not authentication is
 251  *                        successful.  All buffer parameters are NULL.
 252  * NETSEC_SASL_CANCEL   - Generate a protocol message that cancels the
 253  *                        SASL protocol exchange; outdata/outdatasize
 254  *                        should contain this message.
 255  *
 256  * The callback should return OK on success, NOTOK on failure.  Depending
 257  * at the point of the authentication exchange, the callback may be asked
 258  * to generate a cancel message.
 259  */
 260
 261 typedef int (*netsec_sasl_callback)(enum sasl_message_type mtype,
 262                                     unsigned const char *indata,
 263                                     unsigned int indatasize,
 264                                     unsigned char **outdata,
 265                                     unsigned int *outdatasize, char **errstr);
 266
 267 /*
 268  * Sets the SASL parameters for this connection.  If this function is
 269  * not called or is called with NULL for arguments, SASL authentication
 270  * will not be attempted for this connection.
 271  *
 272  * The caller must provide a callback to parse the protocol and return
 273  * the SASL protocol messages (see above for callback details).
 274  *
 275  * Arguments:
 276  *
 277  * ns_context   - Network security context
 278  * hostname     - Fully qualified hostname of remote host.
 279  * service      - Service name (set to NULL to disable SASL).
 280  * mechanism    - The mechanism desired by the user.  If NULL, the SASL
 281  *                library will attempt to negotiate the best mechanism.
 282  * callback     - SASL protocol callbacks
 283  * errstr       - Error string.
 284  *
 285  * Returns NOTOK if SASL is not supported.
 286  */
 287
 288 int netsec_set_sasl_params(netsec_context *ns_context, const char *hostname,
 289                            const char *service, const char *mechanism,
 290                            netsec_sasl_callback callback, char **errstr);
 291
 292 /*
 293  * Start SASL negotiation.  The Netsec library will use the callbacks
 294  * supplied in netsec_set_sasl_params() to format and parse the protocol
 295  * messages.
 296  *
 297  * Arguments:
 298  *
 299  * ns_context   - Network security context
 300  * mechlist     - Space-separated list of supported SASL mechanisms
 301  * errstr       - An error string to be returned upon error.
 302  *
 303  * Returns OK on success, NOTOK on failure.
 304  */
 305
 306 int netsec_negotiate_sasl(netsec_context *ns_context, const char *mechlist,
 307                           char **errstr);
 308
 309 /*
 310  * Returns the chosen SASL mechanism by the SASL library or netsec.
 311  *
 312  * Arguments:
 313  *
 314  * ns_context   - Network security context
 315  *
 316  * Returns a string containing the chosen mech, or NULL if SASL is not
 317  * supported or in use.
 318  */
 319
 320 char *netsec_get_sasl_mechanism(netsec_context *ns_context);
 321
 322 /*
 323  * Set the OAuth service name used to retrieve the OAuth parameters from
 324  * user's profile.  Just calling this function is not enough to guarantee
 325  * that XOAUTH2 authentication will be performed; the appropriate mechanism
 326  * name must be passed into netsec_set_sasl_params().
 327  *
 328  * Arguments:
 329  *
 330  * ns_context   - Network security context
 331  * service      - OAuth2 service names.
 332  *
 333  * Returns NOTOK if OAuth2 is not supported.
 334  */
 335
 336 int netsec_set_oauth_service(netsec_context *ns_context, const char *service);
 337
 338 /*
 339  * Controls whether or not TLS will be negotiated for this connection.
 340  *
 341  * Note: callers still have to call netsec_tls_negotiate() to start
 342  * TLS negotiation at the appropriate point in the protocol.
 343  *
 344  * Arguments
 345  *
 346  * tls          - If nonzero, enable TLS. Otherwise disable TLS
 347  *                negotiation.
 348  *
 349  * Returns NOTOK if TLS is not supported or was unable to initialize.
 350  */
 351
 352 int netsec_set_tls(netsec_context *context, int tls, char **errstr);
 353
 354 /*
 355  * Start TLS negotiation on this protocol.  This connection should have
 356  * netsec_set_tls() called on it.
 357  *
 358  * Arguments:
 359  *
 360  * ns_context   - Network security context
 361  * errstr       - Error string upon failure.
 362  *
 363  * Returns OK on success, NOTOK on failure.
 364  */
 365
 366 int netsec_negotiate_tls(netsec_context *ns_context, char **errstr);
 367
 368 /*
 369  * Allocate and format an error string; should be used by plugins
 370  * to report errors.
 371  *
 372  * Arguments:
 373  *
 374  * errstr       - Error string to be returned
 375  * format       - printf(3) format string
 376  * ...          - Arguments to printf(3)
 377  *
 378  */
 379
 380 void netsec_err(char **errstr, const char *format, ...);