src/interfaces/libpq/fe-auth-sasl.h

   1 /*-------------------------------------------------------------------------
   2  *
   3  * fe-auth-sasl.h
   4  *        Defines the SASL mechanism interface for libpq.
   5  *
   6  * Each SASL mechanism defines a frontend and a backend callback structure.
   7  * This is not part of the public API for applications.
   8  *
   9  * See src/include/libpq/sasl.h for the backend counterpart.
  10  *
  11  * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
  12  * Portions Copyright (c) 1994, Regents of the University of California
  13  *
  14  * src/interfaces/libpq/fe-auth-sasl.h
  15  *
  16  *-------------------------------------------------------------------------
  17  */
  18
  19 #ifndef FE_AUTH_SASL_H
  20 #define FE_AUTH_SASL_H
  21
  22 #include "libpq-fe.h"
  23
  24 /*
  25  * Possible states for the SASL exchange, see the comment on exchange for an
  26  * explanation of these.
  27  */
  28 typedef enum
  29 {
  30         SASL_COMPLETE = 0,
  31         SASL_FAILED,
  32         SASL_CONTINUE,
  33 } SASLStatus;
  34
  35 /*
  36  * Frontend SASL mechanism callbacks.
  37  *
  38  * To implement a frontend mechanism, declare a pg_fe_sasl_mech struct with
  39  * appropriate callback implementations, then hook it into conn->sasl during
  40  * pg_SASL_init()'s mechanism negotiation.
  41  */
  42 typedef struct pg_fe_sasl_mech
  43 {
  44         /*-------
  45          * init()
  46          *
  47          * Initializes mechanism-specific state for a connection.  This
  48          * callback must return a pointer to its allocated state, which will
  49          * be passed as-is as the first argument to the other callbacks.
  50          * the free() callback is called to release any state resources.
  51          *
  52          * If state allocation fails, the implementation should return NULL to
  53          * fail the authentication exchange.
  54          *
  55          * Input parameters:
  56          *
  57          *   conn:     The connection to the server
  58          *
  59          *   password: The user's supplied password for the current connection
  60          *
  61          *   mech:     The mechanism name in use, for implementations that may
  62          *                         advertise more than one name (such as *-PLUS variants).
  63          *-------
  64          */
  65         void       *(*init) (PGconn *conn, const char *password, const char *mech);
  66
  67         /*--------
  68          * exchange()
  69          *
  70          * Produces a client response to a server challenge.  As a special case
  71          * for client-first SASL mechanisms, exchange() is called with a NULL
  72          * server response once at the start of the authentication exchange to
  73          * generate an initial response. Returns a SASLStatus indicating the
  74          * state and status of the exchange.
  75          *
  76          * Input parameters:
  77          *
  78          *      state:     The opaque mechanism state returned by init()
  79          *
  80          *      input:     The challenge data sent by the server, or NULL when
  81          *                         generating a client-first initial response (that is, when
  82          *                         the server expects the client to send a message to start
  83          *                         the exchange).  This is guaranteed to be null-terminated
  84          *                         for safety, but SASL allows embedded nulls in challenges,
  85          *                         so mechanisms must be careful to check inputlen.
  86          *
  87          *      inputlen:  The length of the challenge data sent by the server, or -1
  88          *             during client-first initial response generation.
  89          *
  90          * Output parameters, to be set by the callback function:
  91          *
  92          *      output:    A malloc'd buffer containing the client's response to
  93          *                         the server (can be empty), or NULL if the exchange should
  94          *                         be aborted.  (The callback should return SASL_FAILED in the
  95          *                         latter case.)
  96          *
  97          *      outputlen: The length (0 or higher) of the client response buffer,
  98          *                         ignored if output is NULL.
  99          *
 100          * Return value:
 101          *
 102          *      SASL_CONTINUE:  The output buffer is filled with a client response.
 103          *                                      Additional server challenge is expected
 104          *      SASL_COMPLETE:  The SASL exchange has completed successfully.
 105          *      SASL_FAILED:    The exchange has failed and the connection should be
 106          *                                      dropped.
 107          *--------
 108          */
 109         SASLStatus      (*exchange) (void *state, char *input, int inputlen,
 110                                                          char **output, int *outputlen);
 111
 112         /*--------
 113          * channel_bound()
 114          *
 115          * Returns true if the connection has an established channel binding.  A
 116          * mechanism implementation must ensure that a SASL exchange has actually
 117          * been completed, in addition to checking that channel binding is in use.
 118          *
 119          * Mechanisms that do not implement channel binding may simply return
 120          * false.
 121          *
 122          * Input parameters:
 123          *
 124          *      state:    The opaque mechanism state returned by init()
 125          *--------
 126          */
 127         bool            (*channel_bound) (void *state);
 128
 129         /*--------
 130          * free()
 131          *
 132          * Frees the state allocated by init(). This is called when the connection
 133          * is dropped, not when the exchange is completed.
 134          *
 135          * Input parameters:
 136          *
 137          *   state:    The opaque mechanism state returned by init()
 138          *--------
 139          */
 140         void            (*free) (void *state);
 141
 142 } pg_fe_sasl_mech;
 143
 144 #endif                                                  /* FE_AUTH_SASL_H */