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

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