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/engine.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 */
59 
60 /** The state of the SASL negotiation process */
61 typedef enum {
62  PN_SASL_CONF, /** Pending configuration by application */
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 /** Configure the SASL layer to act as a SASL client.
99  *
100  * The role of client is similar to a TCP client - the peer requesting
101  * the connection.
102  *
103  * @param[in] sasl the SASL layer to configure as a client
104  */
106 
107 /** Configure the SASL layer to act as a server.
108  *
109  * The role of server is similar to a TCP server - the peer accepting
110  * the connection.
111  *
112  * @param[in] sasl the SASL layer to configure as a server
113  */
115 
116 /** Configure the SASL layer to use the "PLAIN" mechanism.
117  *
118  * A utility function to configure a simple client SASL layer using
119  * PLAIN authentication.
120  *
121  * @param[in] sasl the layer to configure.
122  * @param[in] username credential for the PLAIN authentication
123  * mechanism
124  * @param[in] password credential for the PLAIN authentication
125  * mechanism
126  */
127 PN_EXTERN void pn_sasl_plain(pn_sasl_t *sasl, const char *username, const char *password);
128 
129 /** Determine the size of the bytes available via pn_sasl_recv().
130  *
131  * Returns the size in bytes available via pn_sasl_recv().
132  *
133  * @param[in] sasl the SASL layer.
134  * @return The number of bytes available, zero if no available data.
135  */
136 PN_EXTERN size_t pn_sasl_pending(pn_sasl_t *sasl);
137 
138 /** Read challenge/response data sent from the peer.
139  *
140  * Use pn_sasl_pending to determine the size of the data.
141  *
142  * @param[in] sasl the layer to read from.
143  * @param[out] bytes written with up to size bytes of inbound data.
144  * @param[in] size maximum number of bytes that bytes can accept.
145  * @return The number of bytes written to bytes, or an error code if < 0.
146  */
147 PN_EXTERN ssize_t pn_sasl_recv(pn_sasl_t *sasl, char *bytes, size_t size);
148 
149 /** Send challenge or response data to the peer.
150  *
151  * @param[in] sasl The SASL layer.
152  * @param[in] bytes The challenge/response data.
153  * @param[in] size The number of data octets in bytes.
154  * @return The number of octets read from bytes, or an error code if < 0
155  */
156 PN_EXTERN ssize_t pn_sasl_send(pn_sasl_t *sasl, const char *bytes, size_t size);
157 
158 /** Set the outcome of SASL negotiation
159  *
160  * Used by the server to set the result of the negotiation process.
161  *
162  * @todo
163  */
165 
166 /** Retrieve the outcome of SASL negotiation.
167  *
168  * @todo
169  */
171 
172 /** @} */
173 
174 #ifdef __cplusplus
175 }
176 #endif
177 
178 #endif /* sasl.h */