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 <sys/types.h>
27 #include <proton/type_compat.h>
28 #include <proton/types.h>
29 
30 #ifdef __cplusplus
31 extern "C" {
32 #endif
33 
34 /** @file
35  * API for the SASL Secure Transport Layer.
36  *
37  * The SASL layer is responsible for establishing an authenticated
38  * and/or encrypted tunnel over which AMQP frames are passed between
39  * peers. The peer acting as the SASL Client must provide
40  * authentication credentials. The peer acting as the SASL Server must
41  * provide authentication against the received credentials.
42  *
43  * @defgroup sasl SASL
44  * @ingroup transport
45  * @{
46  */
47 
48 typedef struct pn_sasl_t pn_sasl_t;
49 
50 /** The result of the SASL negotiation */
51 typedef enum {
52  PN_SASL_NONE=-1, /** negotiation not completed */
53  PN_SASL_OK=0, /** authentication succeeded */
54  PN_SASL_AUTH=1, /** failed due to bad credentials */
55  PN_SASL_SYS=2, /** failed due to a system error */
56  PN_SASL_PERM=3, /** failed due to unrecoverable error */
57  PN_SASL_TEMP=4, /** failed due to transient error */
58  PN_SASL_SKIPPED=5 /** the peer didn't perform the sasl exchange */
60 
61 /** The state of the SASL negotiation process */
62 typedef enum {
63  PN_SASL_CONF, /** Pending configuration by application */
64  PN_SASL_IDLE, /** Pending SASL Init */
65  PN_SASL_STEP, /** negotiation in progress */
66  PN_SASL_PASS, /** negotiation completed successfully */
67  PN_SASL_FAIL /** negotiation failed */
69 
70 /** Construct an Authentication and Security Layer object
71  *
72  * @return a new SASL object representing the layer.
73  */
75 
76 /** Access the current state of the layer.
77  *
78  * @param[in] sasl the layer to retrieve the state from.
79  * @return The state of the sasl layer.
80  */
82 
83 /** Set the acceptable SASL mechanisms for the layer.
84  *
85  * @param[in] sasl the layer to update
86  * @param[in] mechanisms a list of acceptable SASL mechanisms,
87  * separated by space
88  */
89 PN_EXTERN void pn_sasl_mechanisms(pn_sasl_t *sasl, const char *mechanisms);
90 
91 /** Retrieve the list of SASL mechanisms provided by the remote.
92  *
93  * @param[in] sasl the SASL layer.
94  * @return a string containing a list of the SASL mechanisms
95  * advertised by the remote (separated by spaces)
96  */
98 
99 /** Configure the SASL layer to act as a SASL client.
100  *
101  * The role of client is similar to a TCP client - the peer requesting
102  * the connection.
103  *
104  * @param[in] sasl the SASL layer to configure as a client
105  */
107 
108 /** Configure the SASL layer to act as a server.
109  *
110  * The role of server is similar to a TCP server - the peer accepting
111  * the connection.
112  *
113  * @param[in] sasl the SASL layer to configure as a server
114  */
116 
117 /** Configure a SASL server layer to permit the client to skip the SASL exchange.
118  *
119  * If the peer client skips the SASL exchange (i.e. goes right to the AMQP header)
120  * this server layer will succeed and result in the outcome of PN_SASL_SKIPPED.
121  * The default behavior is to fail and close the connection if the client skips
122  * SASL.
123  *
124  * @param[in] sasl the SASL layer to configure
125  * @param[in] allow true -> allow skip; false -> forbid skip
126  */
127  PN_EXTERN void pn_sasl_allow_skip(pn_sasl_t *sasl, bool allow);
128 
129 /** Configure the SASL layer to use the "PLAIN" mechanism.
130  *
131  * A utility function to configure a simple client SASL layer using
132  * PLAIN authentication.
133  *
134  * @param[in] sasl the layer to configure.
135  * @param[in] username credential for the PLAIN authentication
136  * mechanism
137  * @param[in] password credential for the PLAIN authentication
138  * mechanism
139  */
140 PN_EXTERN void pn_sasl_plain(pn_sasl_t *sasl, const char *username, const char *password);
141 
142 /** Determine the size of the bytes available via pn_sasl_recv().
143  *
144  * Returns the size in bytes available via pn_sasl_recv().
145  *
146  * @param[in] sasl the SASL layer.
147  * @return The number of bytes available, zero if no available data.
148  */
149 PN_EXTERN size_t pn_sasl_pending(pn_sasl_t *sasl);
150 
151 /** Read challenge/response data sent from the peer.
152  *
153  * Use pn_sasl_pending to determine the size of the data.
154  *
155  * @param[in] sasl the layer to read from.
156  * @param[out] bytes written with up to size bytes of inbound data.
157  * @param[in] size maximum number of bytes that bytes can accept.
158  * @return The number of bytes written to bytes, or an error code if < 0.
159  */
160 PN_EXTERN ssize_t pn_sasl_recv(pn_sasl_t *sasl, char *bytes, size_t size);
161 
162 /** Send challenge or response data to the peer.
163  *
164  * @param[in] sasl The SASL layer.
165  * @param[in] bytes The challenge/response data.
166  * @param[in] size The number of data octets in bytes.
167  * @return The number of octets read from bytes, or an error code if < 0
168  */
169 PN_EXTERN ssize_t pn_sasl_send(pn_sasl_t *sasl, const char *bytes, size_t size);
170 
171 /** Set the outcome of SASL negotiation
172  *
173  * Used by the server to set the result of the negotiation process.
174  *
175  * @todo
176  */
178 
179 /** Retrieve the outcome of SASL negotiation.
180  *
181  * @todo
182  */
184 
185 /** @} */
186 
187 #ifdef __cplusplus
188 }
189 #endif
190 
191 #endif /* sasl.h */
negotiation not completed
Definition: sasl.h:53
PN_EXTERN void pn_sasl_client(pn_sasl_t *sasl)
Configure the SASL layer to act as a SASL client.
PN_EXTERN void pn_sasl_allow_skip(pn_sasl_t *sasl, bool allow)
Configure a SASL server layer to permit the client to skip the SASL exchange.
Pending SASL Init.
Definition: sasl.h:65
#define PN_EXTERN
Definition: import_export.h:53
failed due to bad credentials
Definition: sasl.h:55
failed due to a system error
Definition: sasl.h:56
PN_EXTERN pn_sasl_t * pn_sasl(pn_transport_t *transport)
Construct an Authentication and Security Layer object.
failed due to unrecoverable error
Definition: sasl.h:57
PN_EXTERN void pn_sasl_server(pn_sasl_t *sasl)
Configure the SASL layer to act as a server.
PN_EXTERN pn_sasl_state_t pn_sasl_state(pn_sasl_t *sasl)
Access the current state of the layer.
PN_EXTERN size_t pn_sasl_pending(pn_sasl_t *sasl)
Determine the size of the bytes available via pn_sasl_recv().
Definition: sasl.h:63
failed due to transient error
Definition: sasl.h:58
Definition: sasl.h:52
struct pn_sasl_t pn_sasl_t
Definition: sasl.h:48
PN_EXTERN ssize_t pn_sasl_send(pn_sasl_t *sasl, const char *bytes, size_t size)
Send challenge or response data to the peer.
PN_EXTERN void pn_sasl_plain(pn_sasl_t *sasl, const char *username, const char *password)
Configure the SASL layer to use the &quot;PLAIN&quot; mechanism.
pn_sasl_state_t
The state of the SASL negotiation process.
Definition: sasl.h:62
PN_EXTERN const char * pn_sasl_remote_mechanisms(pn_sasl_t *sasl)
Retrieve the list of SASL mechanisms provided by the remote.
negotiation completed successfully
Definition: sasl.h:67
PN_EXTERN ssize_t pn_sasl_recv(pn_sasl_t *sasl, char *bytes, size_t size)
Read challenge/response data sent from the peer.
authentication succeeded
Definition: sasl.h:54
Pending configuration by application.
Definition: sasl.h:64
pn_sasl_outcome_t
The result of the SASL negotiation.
Definition: sasl.h:51
negotiation in progress
Definition: sasl.h:66
PN_EXTERN void pn_sasl_done(pn_sasl_t *sasl, pn_sasl_outcome_t outcome)
Set the outcome of SASL negotiation.
PN_EXTERN void pn_sasl_mechanisms(pn_sasl_t *sasl, const char *mechanisms)
Set the acceptable SASL mechanisms for the layer.
struct pn_transport_t pn_transport_t
An AMQP Transport object.
Definition: types.h:255
PN_EXTERN pn_sasl_outcome_t pn_sasl_outcome(pn_sasl_t *sasl)
Retrieve the outcome of SASL negotiation.