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 #ifndef __cplusplus 00028 #include <stdbool.h> 00029 #endif 00030 #include <proton/engine.h> 00031 00032 #ifdef __cplusplus 00033 extern "C" { 00034 #endif 00035 00036 /** @file 00037 * API for the SASL Secure Transport Layer. 00038 * 00039 * The SASL layer is responsible for establishing an authenticated 00040 * and/or encrypted tunnel over which AMQP frames are passed between 00041 * peers. The peer acting as the SASL Client must provide 00042 * authentication credentials. The peer acting as the SASL Server must 00043 * provide authentication against the received credentials. 00044 */ 00045 00046 typedef struct pn_sasl_t pn_sasl_t; 00047 00048 /** The result of the SASL negotiation */ 00049 typedef enum { 00050 PN_SASL_NONE=-1, /** negotiation not completed */ 00051 PN_SASL_OK=0, /** authentication succeeded */ 00052 PN_SASL_AUTH=1, /** failed due to bad credentials */ 00053 PN_SASL_SYS=2, /** failed due to a system error */ 00054 PN_SASL_PERM=3, /** failed due to unrecoverable error */ 00055 PN_SASL_TEMP=4 /** failed due to transient error */ 00056 } pn_sasl_outcome_t; 00057 00058 /** The state of the SASL negotiation process */ 00059 typedef enum { 00060 PN_SASL_CONF, /** Pending configuration by application */ 00061 PN_SASL_IDLE, /** Pending SASL Init */ 00062 PN_SASL_STEP, /** negotiation in progress */ 00063 PN_SASL_PASS, /** negotiation completed successfully */ 00064 PN_SASL_FAIL /** negotiation failed */ 00065 } pn_sasl_state_t; 00066 00067 /** Construct an Authentication and Security Layer object 00068 * 00069 * @return a new SASL object representing the layer. 00070 */ 00071 PN_EXTERN pn_sasl_t *pn_sasl(pn_transport_t *transport); 00072 00073 /** Access the current state of the layer. 00074 * 00075 * @param[in] sasl the layer to retrieve the state from. 00076 * @return The state of the sasl layer. 00077 */ 00078 PN_EXTERN pn_sasl_state_t pn_sasl_state(pn_sasl_t *sasl); 00079 00080 /** Set the acceptable SASL mechanisms for the layer. 00081 * 00082 * @param[in] sasl the layer to update 00083 * @param[in] mechanisms a list of acceptable SASL mechanisms, 00084 * separated by space 00085 */ 00086 PN_EXTERN void pn_sasl_mechanisms(pn_sasl_t *sasl, const char *mechanisms); 00087 00088 /** Retrieve the list of SASL mechanisms provided by the remote. 00089 * 00090 * @param[in] sasl the SASL layer. 00091 * @return a string containing a list of the SASL mechanisms 00092 * advertised by the remote (separated by spaces) 00093 */ 00094 PN_EXTERN const char *pn_sasl_remote_mechanisms(pn_sasl_t *sasl); 00095 00096 /** Configure the SASL layer to act as a SASL client. 00097 * 00098 * The role of client is similar to a TCP client - the peer requesting 00099 * the connection. 00100 * 00101 * @param[in] sasl the SASL layer to configure as a client 00102 */ 00103 PN_EXTERN void pn_sasl_client(pn_sasl_t *sasl); 00104 00105 /** Configure the SASL layer to act as a server. 00106 * 00107 * The role of server is similar to a TCP server - the peer accepting 00108 * the connection. 00109 * 00110 * @param[in] sasl the SASL layer to configure as a server 00111 */ 00112 PN_EXTERN void pn_sasl_server(pn_sasl_t *sasl); 00113 00114 /** Configure the SASL layer to use the "PLAIN" mechanism. 00115 * 00116 * A utility function to configure a simple client SASL layer using 00117 * PLAIN authentication. 00118 * 00119 * @param[in] sasl the layer to configure. 00120 * @param[in] username credential for the PLAIN authentication 00121 * mechanism 00122 * @param[in] password credential for the PLAIN authentication 00123 * mechanism 00124 */ 00125 PN_EXTERN void pn_sasl_plain(pn_sasl_t *sasl, const char *username, const char *password); 00126 00127 /** Determine the size of the bytes available via pn_sasl_recv(). 00128 * 00129 * Returns the size in bytes available via pn_sasl_recv(). 00130 * 00131 * @param[in] sasl the SASL layer. 00132 * @return The number of bytes available, zero if no available data. 00133 */ 00134 PN_EXTERN size_t pn_sasl_pending(pn_sasl_t *sasl); 00135 00136 /** Read challenge/response data sent from the peer. 00137 * 00138 * Use pn_sasl_pending to determine the size of the data. 00139 * 00140 * @param[in] sasl the layer to read from. 00141 * @param[out] bytes written with up to size bytes of inbound data. 00142 * @param[in] size maximum number of bytes that bytes can accept. 00143 * @return The number of bytes written to bytes, or an error code if < 0. 00144 */ 00145 PN_EXTERN ssize_t pn_sasl_recv(pn_sasl_t *sasl, char *bytes, size_t size); 00146 00147 /** Send challenge or response data to the peer. 00148 * 00149 * @param[in] sasl The SASL layer. 00150 * @param[in] bytes The challenge/response data. 00151 * @param[in] size The number of data octets in bytes. 00152 * @return The number of octets read from bytes, or an error code if < 0 00153 */ 00154 PN_EXTERN ssize_t pn_sasl_send(pn_sasl_t *sasl, const char *bytes, size_t size); 00155 00156 /** Set the outcome of SASL negotiation 00157 * 00158 * Used by the server to set the result of the negotiation process. 00159 * 00160 * @todo 00161 */ 00162 PN_EXTERN void pn_sasl_done(pn_sasl_t *sasl, pn_sasl_outcome_t outcome); 00163 00164 /** Retrieve the outcome of SASL negotiation. 00165 * 00166 * @todo 00167 */ 00168 PN_EXTERN pn_sasl_outcome_t pn_sasl_outcome(pn_sasl_t *sasl); 00169 00170 #ifdef __cplusplus 00171 } 00172 #endif 00173 00174 #endif /* sasl.h */