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  * Set the read timeout for this connection.
  79  *
  80  * Arguments:
  81  *
  82  * ns_context   - Network security context
  83  * timeout      - Read timeout, in seconds.
  84  */
  85
  86 void netsec_set_timeout(netsec_context *ns_context, int timeout);
  87
  88 /*
  89  * Read a "line" from the network.  This reads one CR/LF terminated line.
  90  * Returns a pointer to a NUL-terminated string.  This memory is valid
  91  * until the next call to any read function.  Will return an error if
  92  * the line does not terminate with a CR/LF.
  93  *
  94  * Arguments:
  95  *
  96  * ns_context   - Network security context
  97  * length       - Returned length of string
  98  * errstr       - Error string
  99  *
 100  * Returns pointer to string, or NULL on error.
 101  */
 102
 103 char *netsec_readline(netsec_context *ns_context, size_t *lenght,
 104                       char **errstr);
 105
 106 /*
 107  * Read bytes from the network.
 108  *
 109  * Arguments:
 110  *
 111  * ns_context   - Network security context
 112  * buffer       - Read buffer
 113  * size         - Buffer size
 114  * errstr       - Error size
 115  *
 116  * Returns number of bytes read, or -1 on error.
 117  */
 118
 119 ssize_t netsec_read(netsec_context *ns_context, void *buffer, size_t size,
 120                     char **errstr);
 121
 122 /*
 123  * Write data to the network; if encryption is being performed, we will
 124  * do it.  Data may be buffered; use netsec_flush() to flush any outstanding
 125  * data to the network.
 126  *
 127  * Arguments:
 128  *
 129  * ns_context   - Network security context
 130  * buffer       - Output buffer to write to network
 131  * size         - Size of data to write to network
 132  * errstr       - Error string
 133  *
 134  * Returns OK on success, NOTOK otherwise.
 135  */
 136
 137 int netsec_write(netsec_context *ns_context, const void *buffer, size_t size,
 138                  char **errstr);
 139
 140 /*
 141  * Write bytes using printf formatting
 142  *
 143  * Arguments:
 144  *
 145  * ns_context   - Network security context
 146  * errstr       - Error string
 147  * format       - Format string
 148  * ...          - Arguments for format string
 149  *
 150  * Returns OK on success, NOTOK on error.
 151  */
 152
 153 int netsec_printf(netsec_context *ns_context, char **errstr,
 154                   const char *format, ...);
 155
 156 /*
 157  * Write bytes using a va_list argument.
 158  *
 159  * Arguments:
 160  *
 161  * ns_context   - Network security context
 162  * errstr       - Error string
 163  * format       - Format string
 164  * ap           - stdarg list.
 165  *
 166  * Returns OK on success, NOTOK on error.
 167  */
 168
 169 int netsec_vprintf(netsec_context *ns_context, char **errstr,
 170                    const char *format, va_list ap);
 171
 172 /*
 173  * Flush any buffered bytes to the network.
 174  *
 175  * Arguments:
 176  *
 177  * ns_context   - Network security context
 178  * errstr       - Error string
 179  *
 180  * Returns OK on success, NOTOK on error.
 181  */
 182
 183 int netsec_flush(netsec_context *ns_context, char **errstr);
 184
 185 /*
 186  * Enumerated types for the type of message we are sending/receiving.
 187  */
 188
 189 enum sasl_message_type {
 190         NETSEC_SASL_START,      /* Start of SASL authentication */
 191         NETSEC_SASL_READ,       /* Reading a message */
 192         NETSEC_SASL_WRITE,      /* Writing a message */
 193         NETSEC_SASL_FINISH,     /* Complete SASL exchange */
 194         NETSEC_SASL_CANCEL      /* Cancel a SASL exchange */
 195 };
 196
 197 /*
 198  * The SASL callback; this is designed to parse a protocol-specific
 199  * message and return the SASL protocol message back.
 200  *
 201  * The meaning of the arguments to the callback depend on the mtype
 202  * arguments.  See below for more detail.
 203  *
 204  * Arguments:
 205  *
 206  * mtype        - The type of message we are processing (read/write/cancel).
 207  * indata       - A pointer to any input data.
 208  * indatasize   - The size of the input data in bytes
 209  * outdata      - Output data (freed by caller)
 210  * outdatasize  - Size of output data
 211  * errstr       - An error string to be returned (freed by caller).
 212  *
 213  * Parameter interpretation based on mtype value:
 214  *
 215  * NETSEC_SASL_START    - Create a protocol message that starts SASL
 216  *                        authentication.  If an initial response is
 217  *                        supported, indata and indatasize will contain it.
 218  *                        Otherwise they will be set to NULL and 0.
 219  *                        The complete protocol message should be
 220  *                        stored in outdata/outdatasize, to be free()d
 221  *                        by the caller.  Alternatively, the plugin
 222  *                        can choose to send the data on their own.
 223  * NETSEC_SASL_READ     - Parse and decode a protocol message and extract
 224  *                        out the SASL payload data.  indata will be set
 225  *                        to NULL; the callback must read in the necessary
 226  *                        data using the appropriate netsec function.
 227  *                        outdata/outdatasize should contain the decoded
 228  *                        SASL message (again, must be free()d by the caller).
 229  * NETSEC_SASL_WRITE    - Generate a protocol message to send over the
 230  *                        network.  indata/indatasize will contain the
 231  *                        SASL payload data.  outdata/outdatasize should
 232  *                        contain the complete protocol message.  Alternatively
 233  *                        the plugin can write the data to the network
 234  *                        directly.
 235  * NETSEC_SASL_FINISH   - Process the final SASL message exchange; at
 236  *                        this point SASL exchange should have completed
 237  *                        and we should get a message back from the server
 238  *                        telling us whether or not authentication is
 239  *                        successful.  All buffer parameters are NULL.
 240  * NETSEC_SASL_CANCEL   - Generate a protocol message that cancels the
 241  *                        SASL protocol exchange; outdata/outdatasize
 242  *                        should contain this message.
 243  *
 244  * The callback should return OK on success, NOTOK on failure.  Depending
 245  * at the point of the authentication exchange, the callback may be asked
 246  * to generate a cancel message.
 247  *
 248  * Some higher-level notes in terms of protocol management:
 249  *
 250  * Any data returned in outdata should consist of allocated data that
 251  * the sasl routines is expected to free.
 252  */
 253
 254 typedef int (*netsec_sasl_callback)(enum sasl_message_type mtype,
 255                                     unsigned const char *indata,
 256                                     unsigned int indatasize,
 257                                     unsigned char **outdata,
 258                                     unsigned int *outdatasize, char **errstr);
 259
 260 /*
 261  * Sets the SASL parameters for this connection.  If this function is
 262  * not called or is called with NULL for arguments, SASL authentication
 263  * will not be attempted for this connection.
 264  *
 265  * The caller must provide a callback to parse the protocol and return
 266  * the SASL protocol messages (see above for callback details).
 267  *
 268  * Arguments:
 269  *
 270  * ns_context   - Network security context
 271  * hostname     - Fully qualified hostname of remote host.
 272  * service      - Service name (set to NULL to disable SASL).
 273  * mechanism    - The mechanism desired by the user.  If NULL, the SASL
 274  *                library will attempt to negotiate the best mechanism.
 275  * callback     - SASL protocol callbacks
 276  * errstr       - Error string.
 277  *
 278  * Returns NOTOK if SASL is not supported.
 279  */
 280
 281 int netsec_set_sasl_params(netsec_context *ns_context, const char *hostname,
 282                            const char *service, const char *mechanism,
 283                            netsec_sasl_callback callback, char **errstr);
 284
 285 /*
 286  * Start SASL negotiation.  The Netsec library will use the callbacks
 287  * supplied in netsec_set_sasl_params() to format and parse the protocol
 288  * messages.
 289  *
 290  * Arguments:
 291  *
 292  * ns_context   - Network security context
 293  * mechlist     - Space-separated list of supported SASL mechanisms
 294  * errstr       - An error string to be returned upon error.
 295  *
 296  * Returns OK on success, NOTOK on failure.
 297  */
 298
 299 int netsec_negotiate_sasl(netsec_context *ns_context, const char *mechlist,
 300                           char **errstr);
 301
 302 /*
 303  * Returns the chosen SASL mechanism by the SASL library or netsec.
 304  *
 305  * Arguments:
 306  *
 307  * ns_context   - Network security context
 308  *
 309  * Returns a string containing the chosen mech, or NULL if SASL is not
 310  * supported or in use.
 311  */
 312
 313 char *netsec_get_sasl_mechanism(netsec_context *ns_context);
 314
 315 /*
 316  * Set the OAuth service name used to retrieve the OAuth parameters from
 317  * user's profile.  Just calling this function is not enough to guarantee
 318  * that XOAUTH2 authentication will be performed; the appropriate mechanism
 319  * name must be passed into netsec_set_sasl_params().
 320  *
 321  * Arguments:
 322  *
 323  * ns_context   - Network security context
 324  * service      - OAuth2 service names.
 325  *
 326  * Returns NOTOK if OAuth2 is not supported.
 327  */
 328
 329 int netsec_set_oauth_service(netsec_context *ns_context, const char *service);
 330
 331 /*
 332  * Controls whether or not TLS will be negotiated for this connection.
 333  *
 334  * Note: callers still have to call netsec_tls_negotiate() to start
 335  * TLS negotiation at the appropriate point in the protocol.
 336  *
 337  * Arguments
 338  *
 339  * tls          - If nonzero, enable TLS. Otherwise disable TLS
 340  *                negotiation.
 341  *
 342  * Returns NOTOK if TLS is not supported or was unable to initialize.
 343  */
 344
 345 int netsec_set_tls(netsec_context *context, int tls, char **errstr);
 346
 347 /*
 348  * Start TLS negotiation on this protocol.  This connection should have
 349  * netsec_set_tls() called on it.
 350  *
 351  * Arguments:
 352  *
 353  * ns_context   - Network security context
 354  * errstr       - Error string upon failure.
 355  *
 356  * Returns OK on success, NOTOK on failure.
 357  */
 358
 359 int netsec_negotiate_tls(netsec_context *ns_context, char **errstr);
 360
 361 /*
 362  * Allocate and format an error string; should be used by plugins
 363  * to report errors.
 364  *
 365  * Arguments:
 366  *
 367  * errstr       - Error string to be returned
 368  * format       - printf(3) format string
 369  * ...          - Arguments to printf(3)
 370  *
 371  */
 372
 373 void netsec_err(char **errstr, const char *format, ...);