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 <
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 */
56
}
pn_sasl_outcome_t
;
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 */
65
}
pn_sasl_state_t
;
66
67
/** Construct an Authentication and Security Layer object
68
*
69
* @return a new SASL object representing the layer.
70
*/
71
PN_EXTERN
pn_sasl_t
*
pn_sasl
(
pn_transport_t
*transport);
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
*/
78
PN_EXTERN
pn_sasl_state_t
pn_sasl_state
(
pn_sasl_t
*sasl);
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
*/
94
PN_EXTERN
const
char
*
pn_sasl_remote_mechanisms
(
pn_sasl_t
*sasl);
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
*/
103
PN_EXTERN
void
pn_sasl_client
(
pn_sasl_t
*sasl);
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
*/
112
PN_EXTERN
void
pn_sasl_server
(
pn_sasl_t
*sasl);
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
*/
162
PN_EXTERN
void
pn_sasl_done
(
pn_sasl_t
*sasl,
pn_sasl_outcome_t
outcome);
163
164
/** Retrieve the outcome of SASL negotiation.
165
*
166
* @todo
167
*/
168
PN_EXTERN
pn_sasl_outcome_t
pn_sasl_outcome
(
pn_sasl_t
*sasl);
169
170
#ifdef __cplusplus
171
}
172
#endif
173
174
#endif
/* sasl.h */
Generated on Mon Apr 8 2013 03:55:37 for proton by
1.8.3.1