fe-auth-sasl.h

Go to the documentation of this file.

/*-------------------------------------------------------------------------
 *
 * fe-auth-sasl.h
 *    Defines the SASL mechanism interface for libpq.
 *
 * Each SASL mechanism defines a frontend and a backend callback structure.
 * This is not part of the public API for applications.
 *
 * See src/include/libpq/sasl.h for the backend counterpart.
 *
 * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
 * Portions Copyright (c) 1994, Regents of the University of California
 *
 * src/interfaces/libpq/fe-auth-sasl.h
 *
 *-------------------------------------------------------------------------
 */
 
#ifndef FE_AUTH_SASL_H
#define FE_AUTH_SASL_H
 
#include "libpq-fe.h"
 
/*
 * Possible states for the SASL exchange, see the comment on exchange for an
 * explanation of these.
 */
typedef enum
{
    SASL_COMPLETE = 0,
    SASL_FAILED,
    SASL_CONTINUE,
    SASL_ASYNC,
} SASLStatus;
 
/*
 * Frontend SASL mechanism callbacks.
 *
 * To implement a frontend mechanism, declare a pg_fe_sasl_mech struct with
 * appropriate callback implementations, then hook it into conn->sasl during
 * pg_SASL_init()'s mechanism negotiation.
 */
typedef struct pg_fe_sasl_mech
{
    /*-------
     * init()
     *
     * Initializes mechanism-specific state for a connection.  This
     * callback must return a pointer to its allocated state, which will
     * be passed as-is as the first argument to the other callbacks.
     * the free() callback is called to release any state resources.
     *
     * If state allocation fails, the implementation should return NULL to
     * fail the authentication exchange.
     *
     * Input parameters:
     *
     *   conn:     The connection to the server
     *
     *   password: The user's supplied password for the current connection
     *
     *   mech:     The mechanism name in use, for implementations that may
     *             advertise more than one name (such as *-PLUS variants).
     *-------
     */
    void       *(*init) (PGconn *conn, const char *password, const char *mech);
 
    /*--------
     * exchange()
     *
     * Produces a client response to a server challenge.  As a special case
     * for client-first SASL mechanisms, exchange() is called with a NULL
     * server response once at the start of the authentication exchange to
     * generate an initial response. Returns a SASLStatus indicating the
     * state and status of the exchange.
     *
     * Input parameters:
     *
     *  state:     The opaque mechanism state returned by init()
     *
     *  final:     true if the server has sent a final exchange outcome
     *
     *  input:     The challenge data sent by the server, or NULL when
     *             generating a client-first initial response (that is, when
     *             the server expects the client to send a message to start
     *             the exchange).  This is guaranteed to be null-terminated
     *             for safety, but SASL allows embedded nulls in challenges,
     *             so mechanisms must be careful to check inputlen.
     *
     *  inputlen:  The length of the challenge data sent by the server, or -1
     *             during client-first initial response generation.
     *
     * Output parameters, to be set by the callback function:
     *
     *  output:    A malloc'd buffer containing the client's response to
     *             the server (can be empty), or NULL if the exchange should
     *             be aborted.  (The callback should return SASL_FAILED in the
     *             latter case.)
     *
     *  outputlen: The length (0 or higher) of the client response buffer,
     *             ignored if output is NULL.
     *
     * Return value:
     *
     *  SASL_CONTINUE:  The output buffer is filled with a client response.
     *                  Additional server challenge is expected
     *  SASL_ASYNC:     Some asynchronous processing external to the
     *                  connection needs to be done before a response can be
     *                  generated. The mechanism is responsible for setting up
     *                  conn->async_auth/cleanup_async_auth appropriately
     *                  before returning.
     *  SASL_COMPLETE:  The SASL exchange has completed successfully.
     *  SASL_FAILED:    The exchange has failed and the connection should be
     *                  dropped.
     *--------
     */
    SASLStatus  (*exchange) (void *state, bool final,
                             char *input, int inputlen,
                             char **output, int *outputlen);
 
    /*--------
     * channel_bound()
     *
     * Returns true if the connection has an established channel binding.  A
     * mechanism implementation must ensure that a SASL exchange has actually
     * been completed, in addition to checking that channel binding is in use.
     *
     * Mechanisms that do not implement channel binding may simply return
     * false.
     *
     * Input parameters:
     *
     *  state:    The opaque mechanism state returned by init()
     *--------
     */
    bool        (*channel_bound) (void *state);
 
    /*--------
     * free()
     *
     * Frees the state allocated by init(). This is called when the connection
     * is dropped, not when the exchange is completed.
     *
     * Input parameters:
     *
     *   state:    The opaque mechanism state returned by init()
     *--------
     */
    void        (*free) (void *state);
 
} pg_fe_sasl_mech;
 
#endif                          /* FE_AUTH_SASL_H */