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