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
proton-c
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 Mon Jun 2 2014 22:59:05 for proton by
1.8.1.2