proton  0
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_IDLE, /** Pending SASL Init */
64  PN_SASL_STEP, /** negotiation in progress */
65  PN_SASL_PASS, /** negotiation completed successfully */
66  PN_SASL_FAIL /** negotiation failed */
68 
69 /** Construct an Authentication and Security Layer object
70  *
71  * @return a new SASL object representing the layer.
72  */
74 
75 /** Access the current state of the layer.
76  *
77  * @param[in] sasl the layer to retrieve the state from.
78  * @return The state of the sasl layer.
79  */
81 
82 /** Set the acceptable SASL mechanisms for the layer.
83  *
84  * @param[in] sasl the layer to update
85  * @param[in] mechanisms a list of acceptable SASL mechanisms,
86  * separated by space
87  */
88 PN_EXTERN void pn_sasl_mechanisms(pn_sasl_t *sasl, const char *mechanisms);
89 
90 /** Retrieve the list of SASL mechanisms provided by the remote.
91  *
92  * @param[in] sasl the SASL layer.
93  * @return a string containing a list of the SASL mechanisms
94  * advertised by the remote (separated by spaces)
95  */
97 
98 /**
99  * @deprecated
100  * Configure the SASL layer to act as a SASL client.
101  *
102  * This is now unnecessary, and performs no function. The server/clientness
103  * of the sasl layer is determined from the role of the transport that is used to create
104  * it. The API is retained here so as not to break existing code.
105  *
106  * @param[in] sasl the SASL layer to configure as a client
107  */
109 
110 /**
111  * @deprecated
112  * Configure the SASL layer to act as a server.
113  *
114  * This is now only necessary for backwards compatibility if creating a server pn_sasl_t
115  * from a pn_transport_t which was created implicitly as a client by pn_transport().
116  *
117  * @param[in] sasl the SASL layer to configure as a server
118  */
120 
121 /** Configure a SASL server layer to permit the client to skip the SASL exchange.
122  *
123  * If the peer client skips the SASL exchange (i.e. goes right to the AMQP header)
124  * this server layer will succeed and result in the outcome of PN_SASL_SKIPPED.
125  * The default behavior is to fail and close the connection if the client skips
126  * SASL.
127  *
128  * @param[in] sasl the SASL layer to configure
129  * @param[in] allow true -> allow skip; false -> forbid skip
130  */
131 PN_EXTERN void pn_sasl_allow_skip(pn_sasl_t *sasl, bool allow);
132 
133 /** Configure the SASL layer to use the "PLAIN" mechanism.
134  *
135  * A utility function to configure a simple client SASL layer using
136  * PLAIN authentication.
137  *
138  * @param[in] sasl the layer to configure.
139  * @param[in] username credential for the PLAIN authentication
140  * mechanism
141  * @param[in] password credential for the PLAIN authentication
142  * mechanism
143  */
144 PN_EXTERN void pn_sasl_plain(pn_sasl_t *sasl, const char *username, const char *password);
145 
146 /** Determine the size of the bytes available via pn_sasl_recv().
147  *
148  * Returns the size in bytes available via pn_sasl_recv().
149  *
150  * @param[in] sasl the SASL layer.
151  * @return The number of bytes available, zero if no available data.
152  */
153 PN_EXTERN size_t pn_sasl_pending(pn_sasl_t *sasl);
154 
155 /** Read challenge/response data sent from the peer.
156  *
157  * Use pn_sasl_pending to determine the size of the data.
158  *
159  * @param[in] sasl the layer to read from.
160  * @param[out] bytes written with up to size bytes of inbound data.
161  * @param[in] size maximum number of bytes that bytes can accept.
162  * @return The number of bytes written to bytes, or an error code if < 0.
163  */
164 PN_EXTERN ssize_t pn_sasl_recv(pn_sasl_t *sasl, char *bytes, size_t size);
165 
166 /** Send challenge or response data to the peer.
167  *
168  * @param[in] sasl The SASL layer.
169  * @param[in] bytes The challenge/response data.
170  * @param[in] size The number of data octets in bytes.
171  * @return The number of octets read from bytes, or an error code if < 0
172  */
173 PN_EXTERN ssize_t pn_sasl_send(pn_sasl_t *sasl, const char *bytes, size_t size);
174 
175 /** Set the outcome of SASL negotiation
176  *
177  * Used by the server to set the result of the negotiation process.
178  *
179  * @todo
180  */
182 
183 /** Retrieve the outcome of SASL negotiation.
184  *
185  * @todo
186  */
188 
189 /** @} */
190 
191 #ifdef __cplusplus
192 }
193 #endif
194 
195 #endif /* sasl.h */
PN_EXTERN void pn_sasl_server(pn_sasl_t *sasl)
negotiation not completed
Definition: sasl.h:53
pn_sasl_outcome_t
The result of the SASL negotiation.
Definition: sasl.h:51
failed due to bad credentials
Definition: sasl.h:55
Pending SASL Init.
Definition: sasl.h:64
PN_EXTERN size_t pn_sasl_pending(pn_sasl_t *sasl)
Determine the size of the bytes available via pn_sasl_recv().
failed due to unrecoverable error
Definition: sasl.h:57
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.
failed due to a system error
Definition: sasl.h:56
#define PN_EXTERN
Definition: import_export.h:53
struct pn_sasl_t pn_sasl_t
Definition: sasl.h:48
Definition: sasl.h:52
PN_EXTERN void pn_sasl_done(pn_sasl_t *sasl, pn_sasl_outcome_t outcome)
Set the outcome of SASL negotiation.
PN_EXTERN pn_sasl_state_t pn_sasl_state(pn_sasl_t *sasl)
Access the current state of the layer.
failed due to transient error
Definition: sasl.h:58
authentication succeeded
Definition: sasl.h:54
negotiation completed successfully
Definition: sasl.h:66
Definition: sasl.h:63
PN_EXTERN void pn_sasl_mechanisms(pn_sasl_t *sasl, const char *mechanisms)
Set the acceptable SASL mechanisms for the layer.
PN_EXTERN void pn_sasl_client(pn_sasl_t *sasl)
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.
struct pn_transport_t pn_transport_t
An AMQP Transport object.
Definition: types.h:256
PN_EXTERN pn_sasl_outcome_t pn_sasl_outcome(pn_sasl_t *sasl)
Retrieve the outcome of SASL negotiation.
PN_EXTERN ssize_t pn_sasl_recv(pn_sasl_t *sasl, char *bytes, size_t size)
Read challenge/response data sent from 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 "PLAIN" mechanism.
negotiation in progress
Definition: sasl.h:65
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.
PN_EXTERN pn_sasl_t * pn_sasl(pn_transport_t *transport)
Construct an Authentication and Security Layer object.