proton-c/include/proton/sasl.h

#ifndef PROTON_SASL_H
#define PROTON_SASL_H 1

/*
 *
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 *
 */

#include <sys/types.h>
#include <stdbool.h>
#include <proton/engine.h>

#ifdef __cplusplus
extern "C" {
#endif

/** @file
 * API for the SASL Secure Transport Layer.
 *
 * The SASL layer is responsible for establishing an authenticated
 * and/or encrypted tunnel over which AMQP frames are passed between
 * peers. The peer acting as the SASL Client must provide
 * authentication credentials. The peer acting as the SASL Server must
 * provide authentication against the received credentials.
 */

typedef struct pn_sasl_t pn_sasl_t;

/** The result of the SASL negotiation */
typedef enum {
  PN_SASL_NONE=-1,  /** negotiation not completed */
  PN_SASL_OK=0,     /** authentication succeeded */
  PN_SASL_AUTH=1,   /** failed due to bad credentials */
  PN_SASL_SYS=2,    /** failed due to a system error */
  PN_SASL_PERM=3,   /** failed due to unrecoverable error */
  PN_SASL_TEMP=4    /** failed due to transient error */
} pn_sasl_outcome_t;

/** The state of the SASL negotiation process */
typedef enum {
  PN_SASL_CONF,    /** Pending configuration by application */
  PN_SASL_IDLE,    /** Pending SASL Init */
  PN_SASL_STEP,    /** negotiation in progress */
  PN_SASL_PASS,    /** negotiation completed successfully */
  PN_SASL_FAIL     /** negotiation failed */
} pn_sasl_state_t;

/** Construct an Authentication and Security Layer object
 *
 * @return a new SASL object representing the layer.
 */
pn_sasl_t *pn_sasl(pn_transport_t *transport);

/** Access the current state of the layer.
 *
 * @param[in] sasl the layer to retrieve the state from.
 * @return The state of the sasl layer.
 */
pn_sasl_state_t pn_sasl_state(pn_sasl_t *sasl);

/** Set the acceptable SASL mechanisms for the layer.
 *
 * @param[in] sasl the layer to update
 * @param[in] mechanisms a list of acceptable SASL mechanisms,
 *                       separated by space
 */
void pn_sasl_mechanisms(pn_sasl_t *sasl, const char *mechanisms);

/** Retrieve the list of SASL mechanisms provided by the remote.
 *
 * @param[in] sasl the SASL layer.
 * @return a string containing a list of the SASL mechanisms
 *         advertised by the remote (separated by spaces)
 */
const char *pn_sasl_remote_mechanisms(pn_sasl_t *sasl);

/** Configure the SASL layer to act as a SASL client.
 *
 * The role of client is similar to a TCP client - the peer requesting
 * the connection.
 *
 * @param[in] sasl the SASL layer to configure as a client
 */
void pn_sasl_client(pn_sasl_t *sasl);

/** Configure the SASL layer to act as a server.
 *
 * The role of server is similar to a TCP server - the peer accepting
 * the connection.
 *
 * @param[in] sasl the SASL layer to configure as a server
 */
void pn_sasl_server(pn_sasl_t *sasl);

/** Configure the SASL layer to use the "PLAIN" mechanism.
 *
 * A utility function to configure a simple client SASL layer using
 * PLAIN authentication.
 *
 * @param[in] sasl the layer to configure.
 * @param[in] username credential for the PLAIN authentication
 *                     mechanism
 * @param[in] password credential for the PLAIN authentication
 *                     mechanism
 */
void pn_sasl_plain(pn_sasl_t *sasl, const char *username, const char *password);

/** Determine the size of the bytes available via pn_sasl_recv().
 *
 * Returns the size in bytes available via pn_sasl_recv().
 *
 * @param[in] sasl the SASL layer.
 * @return The number of bytes available, zero if no available data.
 */
size_t pn_sasl_pending(pn_sasl_t *sasl);

/** Read challenge/response data sent from the peer.
 *
 * Use pn_sasl_pending to determine the size of the data.
 *
 * @param[in] sasl the layer to read from.
 * @param[out] bytes written with up to size bytes of inbound data.
 * @param[in] size maximum number of bytes that bytes can accept.
 * @return The number of bytes written to bytes, or an error code if < 0.
 */
ssize_t pn_sasl_recv(pn_sasl_t *sasl, char *bytes, size_t size);

/** Send challenge or response data to the peer.
 *
 * @param[in] sasl The SASL layer.
 * @param[in] bytes The challenge/response data.
 * @param[in] size The number of data octets in bytes.
 * @return The number of octets read from bytes, or an error code if < 0
 */
ssize_t pn_sasl_send(pn_sasl_t *sasl, const char *bytes, size_t size);

/** Set the outcome of SASL negotiation
 *
 * Used by the server to set the result of the negotiation process.
 *
 * @todo
 */
void pn_sasl_done(pn_sasl_t *sasl, pn_sasl_outcome_t outcome);

/** Retrieve the outcome of SASL negotiation.
 *
 * @todo
 */
pn_sasl_outcome_t pn_sasl_outcome(pn_sasl_t *sasl);

#ifdef __cplusplus
}
#endif

#endif /* sasl.h */