proton
0
Main Page
Related Pages
Modules
Data Structures
Files
File List
Globals
All
Data Structures
Files
Functions
Variables
Typedefs
Enumerations
Enumerator
Macros
Groups
Pages
include
proton
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 */
58
}
pn_sasl_outcome_t
;
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 */
67
}
pn_sasl_state_t
;
68
69
/** Construct an Authentication and Security Layer object
70
*
71
* @return a new SASL object representing the layer.
72
*/
73
PN_EXTERN
pn_sasl_t
*
pn_sasl
(
pn_transport_t
*transport);
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
*/
80
PN_EXTERN
pn_sasl_state_t
pn_sasl_state
(
pn_sasl_t
*sasl);
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
*/
96
PN_EXTERN
const
char
*
pn_sasl_remote_mechanisms
(
pn_sasl_t
*sasl);
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
*/
105
PN_EXTERN
void
pn_sasl_client
(
pn_sasl_t
*sasl);
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
*/
114
PN_EXTERN
void
pn_sasl_server
(
pn_sasl_t
*sasl);
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
*/
164
PN_EXTERN
void
pn_sasl_done
(
pn_sasl_t
*sasl,
pn_sasl_outcome_t
outcome);
165
166
/** Retrieve the outcome of SASL negotiation.
167
*
168
* @todo
169
*/
170
PN_EXTERN
pn_sasl_outcome_t
pn_sasl_outcome
(
pn_sasl_t
*sasl);
171
172
/** @} */
173
174
#ifdef __cplusplus
175
}
176
#endif
177
178
#endif
/* sasl.h */
Generated on Thu Jul 10 2014 02:10:59 for proton by
1.8.3.1