proton  0
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
sasl.h
Go to the documentation of this file.
1 #ifndef PROTON_SASL_H
2 #define PROTON_SASL_H 1
3 
4 /*
5  *
6  * Licensed to the Apache Software Foundation (ASF) under one
7  * or more contributor license agreements. See the NOTICE file
8  * distributed with this work for additional information
9  * regarding copyright ownership. The ASF licenses this file
10  * to you under the Apache License, Version 2.0 (the
11  * "License"); you may not use this file except in compliance
12  * with the License. You may obtain a copy of the License at
13  *
14  * http://www.apache.org/licenses/LICENSE-2.0
15  *
16  * Unless required by applicable law or agreed to in writing,
17  * software distributed under the License is distributed on an
18  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
19  * KIND, either express or implied. See the License for the
20  * specific language governing permissions and limitations
21  * under the License.
22  *
23  */
24 
25 #include <proton/import_export.h>
26 #include <proton/type_compat.h>
27 #include <proton/types.h>
28 
29 #ifdef __cplusplus
30 extern "C" {
31 #endif
32 
33 /** @file
34  * API for the SASL Secure Transport Layer.
35  *
36  * The SASL layer is responsible for establishing an authenticated
37  * and/or encrypted tunnel over which AMQP frames are passed between
38  * peers. The peer acting as the SASL Client must provide
39  * authentication credentials. The peer acting as the SASL Server must
40  * provide authentication against the received credentials.
41  *
42  * @defgroup sasl SASL
43  * @ingroup transport
44  * @{
45  */
46 
47 typedef struct pn_sasl_t pn_sasl_t;
48 
49 /** The result of the SASL negotiation */
50 typedef enum {
51  PN_SASL_NONE=-1, /** negotiation not completed */
52  PN_SASL_OK=0, /** authentication succeeded */
53  PN_SASL_AUTH=1, /** failed due to bad credentials */
54  PN_SASL_SYS=2, /** failed due to a system error */
55  PN_SASL_PERM=3, /** failed due to unrecoverable error */
56  PN_SASL_TEMP=4 /** failed due to transient error */
58 
59 /** Construct an Authentication and Security Layer object
60  *
61  * This will return the SASL layer object for the supplied transport
62  * object. If there is currently no SASL layer one will be created.
63  *
64  * On the client side of an AMQP connection this will have the effect
65  * of ensuring that the AMQP SASL layer is used for that connection.
66  *
67  * @return an object representing the SASL layer.
68  */
70 
71 /** Do we support extended SASL negotiation
72  *
73  * Do we support extended SASL negotiation?
74  * All implementations of Proton support ANONYMOUS and EXTERNAL on both
75  * client and server sides and PLAIN on the client side.
76  *
77  * Extended SASL implememtations use an external library (Cyrus SASL)
78  * to support other mechanisms beyond these basic ones.
79  *
80  * @return true if we support extended SASL negotiation, false if we only support basic negotiation.
81  */
82 PN_EXTERN bool pn_sasl_extended(void);
83 
84 /** Set the outcome of SASL negotiation
85  *
86  * Used by the server to set the result of the negotiation process.
87  *
88  * @todo
89  */
91 
92 /** Retrieve the outcome of SASL negotiation.
93  *
94  * @todo
95  */
97 
98 /** Retrieve the authenticated user
99  *
100  * This is usually used at the the server end to find the name of the authenticated user.
101  * On the client it will merely return whatever user was passed in to the
102  * pn_transport_set_user_password() API.
103  *
104  * If pn_sasl_outcome() returns a value other than PN_SASL_OK, then there will be no user to return.
105  * The returned value is only reliable after the PN_TRANSPORT_AUTHENTICATED event has been received.
106  *
107  * @param[in] sasl the sasl layer
108  *
109  * @return
110  * If the SASL layer was not negotiated then 0 is returned
111  * If the ANONYMOUS mechanism is used then the user will be "anonymous"
112  * Otherwise a string containing the user is returned.
113  */
114 PN_EXTERN const char *pn_sasl_get_user(pn_sasl_t *sasl);
115 
116 /** Return the selected SASL mechanism
117  *
118  * The returned value is only reliable after the PN_TRANSPORT_AUTHENTICATED event has been received.
119  *
120  * @param[in] sasl the SASL layer
121  *
122  * @return The authentication mechanism selected by the SASL layer
123  */
124 PN_EXTERN const char *pn_sasl_get_mech(pn_sasl_t *sasl);
125 
126 /** SASL mechanisms that are to be considered for authentication
127  *
128  * This can be used on either the client or the server to restrict the SASL
129  * mechanisms that may be used to the mechanisms on the list.
130  *
131  * @param[in] sasl the SASL layer
132  * @param[in] mechs space separated list of mechanisms that are allowed for authentication
133  */
134 PN_EXTERN void pn_sasl_allowed_mechs(pn_sasl_t *sasl, const char *mechs);
135 
136 /** Boolean to allow use of clear text authentication mechanisms
137  *
138  * By default the SASL layer is configured not to allow mechanisms that disclose
139  * the clear text of the password over an unencrypted AMQP connection. This specifically
140  * will disallow the use of the PLAIN mechanism without using SSL encryption.
141  *
142  * This default is to avoid disclosing password information accidentally over an
143  * insecure network.
144  *
145  * If you actually wish to use a clear text password unencrypted then you can use this
146  * API to set allow_insecure_mechs to true.
147  *
148  * @param[in] sasl the SASL layer
149  * @param[in] insecure set this to true to allow unencrypted PLAIN authentication.
150  *
151  */
152 PN_EXTERN void pn_sasl_set_allow_insecure_mechs(pn_sasl_t *sasl, bool insecure);
153 
154 /** Return the current value for allow_insecure_mechs
155  *
156  * @param[in] sasl the SASL layer
157  */
159 
160 /**
161  * Set the sasl configuration name
162  *
163  * This is used to construct the SASL configuration filename. In the current implementation
164  * it ".conf" is added to the name and the file is looked for in the configuration directory.
165  *
166  * If not set it will default to "proton-server" for a sasl server and "proton-client"
167  * for a client.
168  *
169  * @param[in] sasl the SASL layer
170  * @param[in] name the configuration name
171  */
172 PN_EXTERN void pn_sasl_config_name(pn_sasl_t *sasl, const char *name);
173 
174 /**
175  * Set the sasl configuration path
176  *
177  * This is used to tell SASL where to look for the configuration file.
178  * In the current implementation it can be a colon separated list of directories.
179  *
180  * The environment variable PN_SASL_CONFIG_PATH can also be used to set this path,
181  * but if both methods are used then this pn_sasl_config_path() will take precedence.
182  *
183  * If not set the underlying implementation default will be used.
184  * for a client.
185  *
186  * @param[in] sasl the SASL layer
187  * @param[in] path the configuration path
188  */
189 PN_EXTERN void pn_sasl_config_path(pn_sasl_t *sasl, const char *path);
190 
191 /** @} */
192 
193 #ifdef __cplusplus
194 }
195 #endif
196 
197 #endif /* sasl.h */
pn_sasl_outcome_t
The result of the SASL negotiation.
Definition: sasl.h:50
PN_EXTERN void pn_sasl_config_path(pn_sasl_t *sasl, const char *path)
Set the sasl configuration path.
PN_EXTERN bool pn_sasl_extended(void)
Do we support extended SASL negotiation.
PN_EXTERN pn_sasl_outcome_t pn_sasl_outcome(pn_sasl_t *sasl)
Retrieve the outcome of SASL negotiation.
failed due to a system error
Definition: sasl.h:55
PN_EXTERN void pn_sasl_allowed_mechs(pn_sasl_t *sasl, const char *mechs)
SASL mechanisms that are to be considered for authentication.
PN_EXTERN void pn_sasl_config_name(pn_sasl_t *sasl, const char *name)
Set the sasl configuration name.
#define PN_EXTERN
Definition: import_export.h:53
PN_EXTERN pn_sasl_t * pn_sasl(pn_transport_t *transport)
Construct an Authentication and Security Layer object.
struct pn_transport_t pn_transport_t
An AMQP Transport object.
Definition: types.h:255
PN_EXTERN const char * pn_sasl_get_mech(pn_sasl_t *sasl)
Return the selected SASL mechanism.
PN_EXTERN const char * pn_sasl_get_user(pn_sasl_t *sasl)
Retrieve the authenticated user.
PN_EXTERN void pn_sasl_set_allow_insecure_mechs(pn_sasl_t *sasl, bool insecure)
Boolean to allow use of clear text authentication mechanisms.
authentication succeeded
Definition: sasl.h:53
Definition: sasl.h:51
PN_EXTERN void pn_sasl_done(pn_sasl_t *sasl, pn_sasl_outcome_t outcome)
Set the outcome of SASL negotiation.
negotiation not completed
Definition: sasl.h:52
PN_EXTERN bool pn_sasl_get_allow_insecure_mechs(pn_sasl_t *sasl)
Return the current value for allow_insecure_mechs.
failed due to unrecoverable error
Definition: sasl.h:56
failed due to bad credentials
Definition: sasl.h:54
struct pn_sasl_t pn_sasl_t
Definition: sasl.h:47