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