proton  0
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros 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 <sys/types.h>
26 #include <stdbool.h>
27 #include <proton/engine.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 
43 typedef struct pn_sasl_t pn_sasl_t;
44 
45 /** The result of the SASL negotiation */
46 typedef enum {
47  PN_SASL_NONE=-1, /** negotiation not completed */
48  PN_SASL_OK=0, /** authentication succeeded */
49  PN_SASL_AUTH=1, /** failed due to bad credentials */
50  PN_SASL_SYS=2, /** failed due to a system error */
51  PN_SASL_PERM=3, /** failed due to unrecoverable error */
52  PN_SASL_TEMP=4 /** failed due to transient error */
54 
55 /** The state of the SASL negotiation process */
56 typedef enum {
57  PN_SASL_CONF, /** Pending configuration by application */
58  PN_SASL_IDLE, /** Pending SASL Init */
59  PN_SASL_STEP, /** negotiation in progress */
60  PN_SASL_PASS, /** negotiation completed successfully */
61  PN_SASL_FAIL /** negotiation failed */
63 
64 /** Construct an Authentication and Security Layer object
65  *
66  * @return a new SASL object representing the layer.
67  */
68 pn_sasl_t *pn_sasl(pn_transport_t *transport);
69 
70 /** Access the current state of the layer.
71  *
72  * @param[in] sasl the layer to retrieve the state from.
73  * @return The state of the sasl layer.
74  */
76 
77 /** Set the acceptable SASL mechanisms for the layer.
78  *
79  * @param[in] sasl the layer to update
80  * @param[in] mechanisms a list of acceptable SASL mechanisms,
81  * separated by space
82  */
83 void pn_sasl_mechanisms(pn_sasl_t *sasl, const char *mechanisms);
84 
85 /** Retrieve the list of SASL mechanisms provided by the remote.
86  *
87  * @param[in] sasl the SASL layer.
88  * @return a string containing a list of the SASL mechanisms
89  * advertised by the remote (separated by spaces)
90  */
91 const char *pn_sasl_remote_mechanisms(pn_sasl_t *sasl);
92 
93 /** Configure the SASL layer to act as a SASL client.
94  *
95  * The role of client is similar to a TCP client - the peer requesting
96  * the connection.
97  *
98  * @param[in] sasl the SASL layer to configure as a client
99  */
100 void pn_sasl_client(pn_sasl_t *sasl);
101 
102 /** Configure the SASL layer to act as a server.
103  *
104  * The role of server is similar to a TCP server - the peer accepting
105  * the connection.
106  *
107  * @param[in] sasl the SASL layer to configure as a server
108  */
109 void pn_sasl_server(pn_sasl_t *sasl);
110 
111 /** Configure the SASL layer to use the "PLAIN" mechanism.
112  *
113  * A utility function to configure a simple client SASL layer using
114  * PLAIN authentication.
115  *
116  * @param[in] sasl the layer to configure.
117  * @param[in] username credential for the PLAIN authentication
118  * mechanism
119  * @param[in] password credential for the PLAIN authentication
120  * mechanism
121  */
122 void pn_sasl_plain(pn_sasl_t *sasl, const char *username, const char *password);
123 
124 /** Determine the size of the bytes available via pn_sasl_recv().
125  *
126  * Returns the size in bytes available via pn_sasl_recv().
127  *
128  * @param[in] sasl the SASL layer.
129  * @return The number of bytes available, zero if no available data.
130  */
131 size_t pn_sasl_pending(pn_sasl_t *sasl);
132 
133 /** Read challenge/response data sent from the peer.
134  *
135  * Use pn_sasl_pending to determine the size of the data.
136  *
137  * @param[in] sasl the layer to read from.
138  * @param[out] bytes written with up to size bytes of inbound data.
139  * @param[in] size maximum number of bytes that bytes can accept.
140  * @return The number of bytes written to bytes, or an error code if < 0.
141  */
142 ssize_t pn_sasl_recv(pn_sasl_t *sasl, char *bytes, size_t size);
143 
144 /** Send challenge or response data to the peer.
145  *
146  * @param[in] sasl The SASL layer.
147  * @param[in] bytes The challenge/response data.
148  * @param[in] size The number of data octets in bytes.
149  * @return The number of octets read from bytes, or an error code if < 0
150  */
151 ssize_t pn_sasl_send(pn_sasl_t *sasl, const char *bytes, size_t size);
152 
153 /** Set the outcome of SASL negotiation
154  *
155  * Used by the server to set the result of the negotiation process.
156  *
157  * @todo
158  */
159 void pn_sasl_done(pn_sasl_t *sasl, pn_sasl_outcome_t outcome);
160 
161 /** Retrieve the outcome of SASL negotiation.
162  *
163  * @todo
164  */
166 
167 #ifdef __cplusplus
168 }
169 #endif
170 
171 #endif /* sasl.h */