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 <proton/type_compat.h> 00027 #include <proton/types.h> 00028 00029 #ifdef __cplusplus 00030 extern "C" { 00031 #endif 00032 00033 /** @file 00034 * API for the SASL Secure Transport Layer. 00035 * 00036 * The SASL layer is responsible for establishing an authenticated 00037 * and/or encrypted tunnel over which AMQP frames are passed between 00038 * peers. The peer acting as the SASL Client must provide 00039 * authentication credentials. The peer acting as the SASL Server must 00040 * provide authentication against the received credentials. 00041 * 00042 * @defgroup sasl SASL 00043 * @ingroup transport 00044 * @{ 00045 */ 00046 00047 typedef struct pn_sasl_t pn_sasl_t; 00048 00049 /** The result of the SASL negotiation */ 00050 typedef enum { 00051 PN_SASL_NONE=-1, /** negotiation not completed */ 00052 PN_SASL_OK=0, /** authentication succeeded */ 00053 PN_SASL_AUTH=1, /** failed due to bad credentials */ 00054 PN_SASL_SYS=2, /** failed due to a system error */ 00055 PN_SASL_PERM=3, /** failed due to unrecoverable error */ 00056 PN_SASL_TEMP=4 /** failed due to transient error */ 00057 } pn_sasl_outcome_t; 00058 00059 /** Construct an Authentication and Security Layer object 00060 * 00061 * This will return the SASL layer object for the supplied transport 00062 * object. If there is currently no SASL layer one will be created. 00063 * 00064 * On the client side of an AMQP connection this will have the effect 00065 * of ensuring that the AMQP SASL layer is used for that connection. 00066 * 00067 * @return an object representing the SASL layer. 00068 */ 00069 PN_EXTERN pn_sasl_t *pn_sasl(pn_transport_t *transport); 00070 00071 /** Do we support extended SASL negotiation 00072 * 00073 * Do we support extended SASL negotiation? 00074 * All implementations of Proton support ANONYMOUS and EXTERNAL on both 00075 * client and server sides and PLAIN on the client side. 00076 * 00077 * Extended SASL implememtations use an external library (Cyrus SASL) 00078 * to support other mechanisms beyond these basic ones. 00079 * 00080 * @return true if we support extended SASL negotiation, false if we only support basic negotiation. 00081 */ 00082 PN_EXTERN bool pn_sasl_extended(void); 00083 00084 /** Set the outcome of SASL negotiation 00085 * 00086 * Used by the server to set the result of the negotiation process. 00087 * 00088 * @todo 00089 */ 00090 PN_EXTERN void pn_sasl_done(pn_sasl_t *sasl, pn_sasl_outcome_t outcome); 00091 00092 /** Retrieve the outcome of SASL negotiation. 00093 * 00094 * @todo 00095 */ 00096 PN_EXTERN pn_sasl_outcome_t pn_sasl_outcome(pn_sasl_t *sasl); 00097 00098 /** Retrieve the authenticated user 00099 * 00100 * This is usually used at the the server end to find the name of the authenticated user. 00101 * On the client it will merely return whatever user was passed in to the 00102 * pn_transport_set_user_password() API. 00103 * 00104 * If pn_sasl_outcome() returns a value other than PN_SASL_OK, then there will be no user to return. 00105 * The returned value is only reliable after the PN_TRANSPORT_AUTHENTICATED event has been received. 00106 * 00107 * @param[in] sasl the sasl layer 00108 * 00109 * @return 00110 * If the SASL layer was not negotiated then 0 is returned 00111 * If the ANONYMOUS mechanism is used then the user will be "anonymous" 00112 * Otherwise a string containing the user is returned. 00113 */ 00114 PN_EXTERN const char *pn_sasl_get_user(pn_sasl_t *sasl); 00115 00116 /** Return the selected SASL mechanism 00117 * 00118 * The returned value is only reliable after the PN_TRANSPORT_AUTHENTICATED event has been received. 00119 * 00120 * @param[in] sasl the SASL layer 00121 * 00122 * @return The authentication mechanism selected by the SASL layer 00123 */ 00124 PN_EXTERN const char *pn_sasl_get_mech(pn_sasl_t *sasl); 00125 00126 /** SASL mechanisms that are to be considered for authentication 00127 * 00128 * This can be used on either the client or the server to restrict the SASL 00129 * mechanisms that may be used to the mechanisms on the list. 00130 * 00131 * @param[in] sasl the SASL layer 00132 * @param[in] mechs space separated list of mechanisms that are allowed for authentication 00133 */ 00134 PN_EXTERN void pn_sasl_allowed_mechs(pn_sasl_t *sasl, const char *mechs); 00135 00136 /** Boolean to allow use of clear text authentication mechanisms 00137 * 00138 * By default the SASL layer is configured not to allow mechanisms that disclose 00139 * the clear text of the password over an unencrypted AMQP connection. This specifically 00140 * will disallow the use of the PLAIN mechanism without using SSL encryption. 00141 * 00142 * This default is to avoid disclosing password information accidentally over an 00143 * insecure network. 00144 * 00145 * If you actually wish to use a clear text password unencrypted then you can use this 00146 * API to set allow_insecure_mechs to true. 00147 * 00148 * @param[in] sasl the SASL layer 00149 * @param[in] insecure set this to true to allow unencrypted PLAIN authentication. 00150 * 00151 */ 00152 PN_EXTERN void pn_sasl_set_allow_insecure_mechs(pn_sasl_t *sasl, bool insecure); 00153 00154 /** Return the current value for allow_insecure_mechs 00155 * 00156 * @param[in] sasl the SASL layer 00157 */ 00158 PN_EXTERN bool pn_sasl_get_allow_insecure_mechs(pn_sasl_t *sasl); 00159 00160 /** 00161 * Set the sasl configuration name 00162 * 00163 * This is used to construct the SASL configuration filename. In the current implementation 00164 * it ".conf" is added to the name and the file is looked for in the configuration directory. 00165 * 00166 * If not set it will default to "proton-server" for a sasl server and "proton-client" 00167 * for a client. 00168 * 00169 * @param[in] sasl the SASL layer 00170 * @param[in] name the configuration name 00171 */ 00172 PN_EXTERN void pn_sasl_config_name(pn_sasl_t *sasl, const char *name); 00173 00174 /** 00175 * Set the sasl configuration path 00176 * 00177 * This is used to tell SASL where to look for the configuration file. 00178 * In the current implementation it can be a colon separated list of directories. 00179 * 00180 * The environment variable PN_SASL_CONFIG_PATH can also be used to set this path, 00181 * but if both methods are used then this pn_sasl_config_path() will take precedence. 00182 * 00183 * If not set the underlying implementation default will be used. 00184 * for a client. 00185 * 00186 * @param[in] sasl the SASL layer 00187 * @param[in] path the configuration path 00188 */ 00189 PN_EXTERN void pn_sasl_config_path(pn_sasl_t *sasl, const char *path); 00190 00191 /** @} */ 00192 00193 #ifdef __cplusplus 00194 } 00195 #endif 00196 00197 #endif /* sasl.h */