00001 #ifndef PROTON_SASL_H 00002 #define PROTON_SASL_H 1 00003 00004 /* 00005 * 00006 * Licensed to the Apache Software Foundation (ASF) under one 00007 * or more contributor license agreements. See the NOTICE file 00008 * distributed with this work for additional information 00009 * regarding copyright ownership. The ASF licenses this file 00010 * to you under the Apache License, Version 2.0 (the 00011 * "License"); you may not use this file except in compliance 00012 * with the License. You may obtain a copy of the License at 00013 * 00014 * http://www.apache.org/licenses/LICENSE-2.0 00015 * 00016 * Unless required by applicable law or agreed to in writing, 00017 * software distributed under the License is distributed on an 00018 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 00019 * KIND, either express or implied. See the License for the 00020 * specific language governing permissions and limitations 00021 * under the License. 00022 * 00023 */ 00024 00025 #include <proton/import_export.h> 00026 #include <sys/types.h> 00027 #include <proton/type_compat.h> 00028 #include <proton/engine.h> 00029 00030 #ifdef __cplusplus 00031 extern "C" { 00032 #endif 00033 00034 /** @file 00035 * API for the SASL Secure Transport Layer. 00036 * 00037 * The SASL layer is responsible for establishing an authenticated 00038 * and/or encrypted tunnel over which AMQP frames are passed between 00039 * peers. The peer acting as the SASL Client must provide 00040 * authentication credentials. The peer acting as the SASL Server must 00041 * provide authentication against the received credentials. 00042 * 00043 * @defgroup sasl SASL 00044 * @ingroup transport 00045 * @{ 00046 */ 00047 00048 typedef struct pn_sasl_t pn_sasl_t; 00049 00050 /** The result of the SASL negotiation */ 00051 typedef enum { 00052 PN_SASL_NONE=-1, /** negotiation not completed */ 00053 PN_SASL_OK=0, /** authentication succeeded */ 00054 PN_SASL_AUTH=1, /** failed due to bad credentials */ 00055 PN_SASL_SYS=2, /** failed due to a system error */ 00056 PN_SASL_PERM=3, /** failed due to unrecoverable error */ 00057 PN_SASL_TEMP=4 /** failed due to transient error */ 00058 } pn_sasl_outcome_t; 00059 00060 /** The state of the SASL negotiation process */ 00061 typedef enum { 00062 PN_SASL_CONF, /** Pending configuration by application */ 00063 PN_SASL_IDLE, /** Pending SASL Init */ 00064 PN_SASL_STEP, /** negotiation in progress */ 00065 PN_SASL_PASS, /** negotiation completed successfully */ 00066 PN_SASL_FAIL /** negotiation failed */ 00067 } pn_sasl_state_t; 00068 00069 /** Construct an Authentication and Security Layer object 00070 * 00071 * @return a new SASL object representing the layer. 00072 */ 00073 PN_EXTERN pn_sasl_t *pn_sasl(pn_transport_t *transport); 00074 00075 /** Access the current state of the layer. 00076 * 00077 * @param[in] sasl the layer to retrieve the state from. 00078 * @return The state of the sasl layer. 00079 */ 00080 PN_EXTERN pn_sasl_state_t pn_sasl_state(pn_sasl_t *sasl); 00081 00082 /** Set the acceptable SASL mechanisms for the layer. 00083 * 00084 * @param[in] sasl the layer to update 00085 * @param[in] mechanisms a list of acceptable SASL mechanisms, 00086 * separated by space 00087 */ 00088 PN_EXTERN void pn_sasl_mechanisms(pn_sasl_t *sasl, const char *mechanisms); 00089 00090 /** Retrieve the list of SASL mechanisms provided by the remote. 00091 * 00092 * @param[in] sasl the SASL layer. 00093 * @return a string containing a list of the SASL mechanisms 00094 * advertised by the remote (separated by spaces) 00095 */ 00096 PN_EXTERN const char *pn_sasl_remote_mechanisms(pn_sasl_t *sasl); 00097 00098 /** Configure the SASL layer to act as a SASL client. 00099 * 00100 * The role of client is similar to a TCP client - the peer requesting 00101 * the connection. 00102 * 00103 * @param[in] sasl the SASL layer to configure as a client 00104 */ 00105 PN_EXTERN void pn_sasl_client(pn_sasl_t *sasl); 00106 00107 /** Configure the SASL layer to act as a server. 00108 * 00109 * The role of server is similar to a TCP server - the peer accepting 00110 * the connection. 00111 * 00112 * @param[in] sasl the SASL layer to configure as a server 00113 */ 00114 PN_EXTERN void pn_sasl_server(pn_sasl_t *sasl); 00115 00116 /** Configure the SASL layer to use the "PLAIN" mechanism. 00117 * 00118 * A utility function to configure a simple client SASL layer using 00119 * PLAIN authentication. 00120 * 00121 * @param[in] sasl the layer to configure. 00122 * @param[in] username credential for the PLAIN authentication 00123 * mechanism 00124 * @param[in] password credential for the PLAIN authentication 00125 * mechanism 00126 */ 00127 PN_EXTERN void pn_sasl_plain(pn_sasl_t *sasl, const char *username, const char *password); 00128 00129 /** Determine the size of the bytes available via pn_sasl_recv(). 00130 * 00131 * Returns the size in bytes available via pn_sasl_recv(). 00132 * 00133 * @param[in] sasl the SASL layer. 00134 * @return The number of bytes available, zero if no available data. 00135 */ 00136 PN_EXTERN size_t pn_sasl_pending(pn_sasl_t *sasl); 00137 00138 /** Read challenge/response data sent from the peer. 00139 * 00140 * Use pn_sasl_pending to determine the size of the data. 00141 * 00142 * @param[in] sasl the layer to read from. 00143 * @param[out] bytes written with up to size bytes of inbound data. 00144 * @param[in] size maximum number of bytes that bytes can accept. 00145 * @return The number of bytes written to bytes, or an error code if < 0. 00146 */ 00147 PN_EXTERN ssize_t pn_sasl_recv(pn_sasl_t *sasl, char *bytes, size_t size); 00148 00149 /** Send challenge or response data to the peer. 00150 * 00151 * @param[in] sasl The SASL layer. 00152 * @param[in] bytes The challenge/response data. 00153 * @param[in] size The number of data octets in bytes. 00154 * @return The number of octets read from bytes, or an error code if < 0 00155 */ 00156 PN_EXTERN ssize_t pn_sasl_send(pn_sasl_t *sasl, const char *bytes, size_t size); 00157 00158 /** Set the outcome of SASL negotiation 00159 * 00160 * Used by the server to set the result of the negotiation process. 00161 * 00162 * @todo 00163 */ 00164 PN_EXTERN void pn_sasl_done(pn_sasl_t *sasl, pn_sasl_outcome_t outcome); 00165 00166 /** Retrieve the outcome of SASL negotiation. 00167 * 00168 * @todo 00169 */ 00170 PN_EXTERN pn_sasl_outcome_t pn_sasl_outcome(pn_sasl_t *sasl); 00171 00172 /** @} */ 00173 00174 #ifdef __cplusplus 00175 } 00176 #endif 00177 00178 #endif /* sasl.h */