proton
0
Main Page
Related Pages
Data Structures
Files
File List
Globals
All
Data Structures
Files
Functions
Variables
Typedefs
Enumerations
Enumerator
Macros
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 <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 */
53
}
pn_sasl_outcome_t
;
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 */
62
}
pn_sasl_state_t
;
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
*/
75
pn_sasl_state_t
pn_sasl_state
(
pn_sasl_t
*sasl);
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
*/
165
pn_sasl_outcome_t
pn_sasl_outcome
(
pn_sasl_t
*sasl);
166
167
#ifdef __cplusplus
168
}
169
#endif
170
171
#endif
/* sasl.h */
Generated on Mon Feb 11 2013 20:34:32 for proton by
1.8.1.1