Qpid Proton C API  0.24.0
sasl-plugin.h
1 #ifndef PROTON_SASL_PLUGIN_H
2 #define PROTON_SASL_PLUGIN_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 <proton/type_compat.h>
27 #include <proton/types.h>
28 
29 #ifdef __cplusplus
30 extern "C" {
31 #endif
32 
35 /*
36  Internal SASL authenticator interface: These are the entry points to a SASL implementations
37 
38  Free up all data structures allocated by the SASL implementation
39  void free(pn_transport_t *transport);
40 
41  Return space separated list of supported mechanisms (client and server)
42  If the returned string is dynamically allocated by the SASL implemetation
43  it must stay valid until the free entry point is called.
44  const char *list_mechs(pn_transport_t *transport);
45 
46  Initialise for either client or server (can't call both for a
47  given transport/connection):
48  bool init_server(pn_transport_t *transport);
49  bool init_client(pn_transport_t *transport);
50 
51  Writing:
52  void prepare_write(pn_transport_t *transport);
53 
54  Reading:
55  Server side (process server SASL messages):
56  void process_init(pn_transport_t *transport, const char *mechanism, const pn_bytes_t *recv);
57  void process_response(pn_transport_t *transport, const pn_bytes_t *recv);
58 
59  Client side (process client SASL messages)
60  bool process_mechanisms(pn_transport_t *transport, const char *mechs);
61  void process_challenge(pn_transport_t *transport, const pn_bytes_t *recv);
62  void process_outcome(pn_transport_t *transport);
63 
64  Security layer interface (active after SASL succeeds)
65  bool can_encrypt(pn_transport_t *transport);
66  ssize_t max_encrypt_size(pn_transport_t *transport);
67  ssize_t encode(pn_transport_t *transport, pn_bytes_t in, pn_bytes_t *out);
68  ssize_t decode(pn_transport_t *transport, pn_bytes_t in, pn_bytes_t *out);
69 */
70 
71 typedef struct pnx_sasl_implementation
72 {
73  void (*free)(pn_transport_t *transport);
74 
75  const char* (*list_mechs)(pn_transport_t *transport);
76 
77  bool (*init_server)(pn_transport_t *transport);
78  bool (*init_client)(pn_transport_t *transport);
79 
80  void (*prepare_write)(pn_transport_t *transport);
81 
82  void (*process_init)(pn_transport_t *transport, const char *mechanism, const pn_bytes_t *recv);
83  void (*process_response)(pn_transport_t *transport, const pn_bytes_t *recv);
84 
85  bool (*process_mechanisms)(pn_transport_t *transport, const char *mechs);
86  void (*process_challenge)(pn_transport_t *transport, const pn_bytes_t *recv);
87  void (*process_outcome)(pn_transport_t *transport);
88 
89  bool (*can_encrypt)(pn_transport_t *transport);
90  ssize_t (*max_encrypt_size)(pn_transport_t *transport);
91  ssize_t (*encode)(pn_transport_t *transport, pn_bytes_t in, pn_bytes_t *out);
92  ssize_t (*decode)(pn_transport_t *transport, pn_bytes_t in, pn_bytes_t *out);
93 
94 } pnx_sasl_implementation;
95 
96 /* Shared SASL API used by the actual SASL authenticators */
97 enum pnx_sasl_state {
98  SASL_NONE,
99  SASL_POSTED_INIT,
100  SASL_POSTED_MECHANISMS,
101  SASL_POSTED_RESPONSE,
102  SASL_POSTED_CHALLENGE,
103  SASL_RECVED_OUTCOME_SUCCEED,
104  SASL_RECVED_OUTCOME_FAIL,
105  SASL_POSTED_OUTCOME,
106  SASL_ERROR
107 };
108 
109 /* APIs used by sasl implementations */
110 PN_EXTERN void pnx_sasl_logf(pn_transport_t *transport, const char *format, ...);
111 PN_EXTERN void pnx_sasl_error(pn_transport_t *transport, const char* err, const char* condition_name);
112 
113 PN_EXTERN void *pnx_sasl_get_context(pn_transport_t *transport);
114 PN_EXTERN void pnx_sasl_set_context(pn_transport_t *transport, void *context);
115 
116 PN_EXTERN bool pnx_sasl_is_client(pn_transport_t *transport);
117 PN_EXTERN bool pnx_sasl_is_included_mech(pn_transport_t *transport, pn_bytes_t s);
118 PN_EXTERN bool pnx_sasl_is_transport_encrypted(pn_transport_t *transport);
119 PN_EXTERN bool pnx_sasl_get_allow_insecure_mechs(pn_transport_t *transport);
120 PN_EXTERN bool pnx_sasl_get_auth_required(pn_transport_t *transport);
121 PN_EXTERN const char *pnx_sasl_get_external_username(pn_transport_t *transport);
122 PN_EXTERN int pnx_sasl_get_external_ssf(pn_transport_t *transport);
123 
124 PN_EXTERN const char *pnx_sasl_get_username(pn_transport_t *transport);
125 PN_EXTERN const char *pnx_sasl_get_password(pn_transport_t *transport);
126 PN_EXTERN void pnx_sasl_clear_password(pn_transport_t *transport);
127 PN_EXTERN const char *pnx_sasl_get_remote_fqdn(pn_transport_t *transport);
128 PN_EXTERN const char *pnx_sasl_get_selected_mechanism(pn_transport_t *transport);
129 
130 PN_EXTERN void pnx_sasl_set_bytes_out(pn_transport_t *transport, pn_bytes_t bytes);
131 PN_EXTERN void pnx_sasl_set_desired_state(pn_transport_t *transport, enum pnx_sasl_state desired_state);
132 PN_EXTERN void pnx_sasl_set_selected_mechanism(pn_transport_t *transport, const char *mechanism);
133 PN_EXTERN void pnx_sasl_set_local_hostname(pn_transport_t * transport, const char * fqdn);
134 PN_EXTERN void pnx_sasl_succeed_authentication(pn_transport_t *transport, const char *username);
135 PN_EXTERN void pnx_sasl_fail_authentication(pn_transport_t *transport);
136 
137 PN_EXTERN void pnx_sasl_set_implementation(pn_transport_t *transport, const pnx_sasl_implementation *impl, void *context);
138 PN_EXTERN void pnx_sasl_set_default_implementation(const pnx_sasl_implementation *impl);
139 
142 #ifdef __cplusplus
143 }
144 #endif
145 
146 #endif /* sasl-plugin.h */
AMQP and API data types.
struct pn_transport_t pn_transport_t
A network channel supporting an AMQP connection.
Definition: types.h:431
A const byte buffer.
Definition: types.h:212