1 /*
2  *     Copyright 2013 Couchbase, Inc.
3  *
4  *   Licensed under the Apache License, Version 2.0 (the "License");
5  *   you may not use this file except in compliance with the License.
6  *   You may obtain a copy of the License at
7  *
8  *       http://www.apache.org/licenses/LICENSE-2.0
9  *
10  *   Unless required by applicable law or agreed to in writing, software
11  *   distributed under the License is distributed on an "AS IS" BASIS,
12  *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  *   See the License for the specific language governing permissions and
14  *   limitations under the License.
15  */
16 
17 #ifndef INCLUDE_CBSASL_CBSASL_H_
18 #define INCLUDE_CBSASL_CBSASL_H_ 1
19 
20 #include <cbsasl/visibility.h>
21 
22 #ifdef __cplusplus
23 extern "C" {
24 #endif
25 
26     typedef enum cbsasl_error {
27         SASL_OK,
28         SASL_CONTINUE,
29         SASL_FAIL,
30         SASL_NOMEM,
31         SASL_BADPARAM,
32         SASL_NOMECH,
33         SASL_NOUSER,
34         SASL_PWERR
35     }
36     cbsasl_error_t;
37 
38     typedef struct {
39         unsigned long len;
40         unsigned char data[1];
41     } cbsasl_secret_t;
42 
43     typedef struct {
44         unsigned long id;
45         int (*proc)(void);
46         void *context;
47     } cbsasl_callback_t;
48 
49     typedef struct cbsasl_conn_st cbsasl_conn_t;
50 
51 #ifdef BUILDING_CBSASL
52     typedef cbsasl_error_t (*cbsasl_init_fn)();
53     typedef cbsasl_error_t (*cbsasl_start_fn)(cbsasl_conn_t *);
54     typedef cbsasl_error_t (*cbsasl_step_fn)(cbsasl_conn_t *, const char *,
55                                              unsigned, const char **, unsigned *);
56 
57     typedef struct cbsasl_mechs {
58         const char *name;
59         cbsasl_init_fn init;
60         cbsasl_start_fn start;
61         cbsasl_step_fn step;
62     } cbsasl_mechs_t;
63 
64     struct cbsasl_client_conn_t {
65         char *userdata;
66         int plain;
67         int (*get_username)(void *context, int id, const char **result,
68                             unsigned int *len);
69         void *get_username_ctx;
70         int (*get_password)(cbsasl_conn_t *conn, void *context, int id,
71                             cbsasl_secret_t **psecret);
72         void *get_password_ctx;
73     };
74 
75     struct cbsasl_server_conn_t {
76         char *username;
77         char *config;
78         char *sasl_data;
79         unsigned int sasl_data_len;
80         cbsasl_mechs_t mech;
81     };
82 
83     struct cbsasl_conn_st {
84         int client;
85         union {
86             struct cbsasl_client_conn_t client;
87             struct cbsasl_server_conn_t server;
88         } c;
89     };
90 #endif
91 
92     /**
93      * Lists all of the mechanisms this sasl server supports
94      *
95      * @param mechs A string containing all supported mechanism names
96      * @param mechslen The length of the mechs string
97      *
98      * @return Whether or not an error occured while getting the mechanism list
99      */
100     CBSASL_PUBLIC_API
101     cbsasl_error_t cbsasl_list_mechs(const char **mechs,
102                                      unsigned *mechslen);
103 
104     /**
105      * Initializes the sasl server
106      *
107      * This function initializes the server by loading passwords from the cbsasl
108      * password file. This function should only be called once.
109      *
110      * @return Whether or not the sasl server initialization was successful
111      */
112     CBSASL_PUBLIC_API
113     cbsasl_error_t cbsasl_server_init(void);
114 
115     /**
116      * close and release allocated resources
117      *
118      * @return SASL_OK upon success
119      */
120     CBSASL_PUBLIC_API
121     cbsasl_error_t cbsasl_server_term(void);
122 
123     /**
124      * Creates a sasl connection and begins authentication
125      *
126      * When a client receives a request for sasl authentication this function is
127      * called in order to initialize the sasl connection based on the mechanism
128      * specified.
129      *
130      * @param conn The connection context for this session
131      * @param mechanism The mechanism that will be used for authentication
132      *
133      * @return Whether or not the mecahnism initialization was successful
134      */
135     CBSASL_PUBLIC_API
136     cbsasl_error_t cbsasl_server_start(cbsasl_conn_t **conn,
137                                        const char *mech,
138                                        const char *clientin,
139                                        unsigned int clientinlen,
140                                        unsigned char **serverout,
141                                        unsigned int *serveroutlen);
142 
143     /**
144      * Does username/password authentication
145      *
146      * After the sasl connection is initialized the step function is called to
147      * check credentials.
148      *
149      * @return Whether or not the sasl step was successful
150      */
151     CBSASL_PUBLIC_API
152     cbsasl_error_t cbsasl_server_step(cbsasl_conn_t *conn,
153                                       const char *input,
154                                       unsigned inputlen,
155                                       const char **output,
156                                       unsigned *outputlen);
157 
158     /**
159      * Frees up funushed sasl connections
160      *
161      * @param conn The sasl connection to free
162      */
163     CBSASL_PUBLIC_API
164     void cbsasl_dispose(cbsasl_conn_t **pconn);
165 
166     /**
167      * Refresh the internal data (this may result in loading password
168      * databases etc)
169      *
170      * @return Whether or not the operation was successful
171      */
172     CBSASL_PUBLIC_API
173     cbsasl_error_t cbsasl_server_refresh(void);
174 
175     typedef enum {
176         CBSASL_USERNAME = 0,
177         CBSASL_CONFIG = 1
178     } cbsasl_prop_t;
179 
180     CBSASL_PUBLIC_API
181     cbsasl_error_t cbsasl_getprop(cbsasl_conn_t *conn,
182                                   cbsasl_prop_t propnum,
183                                   const void **pvalue);
184 
185     CBSASL_PUBLIC_API
186     cbsasl_error_t cbsasl_setprop(cbsasl_conn_t *conn,
187                                   cbsasl_prop_t propnum,
188                                   const void *pvalue);
189 
190     /* Client API */
191 
192 
193     /* define the different callback id's we support */
194 #define CBSASL_CB_USER 1
195 #define CBSASL_CB_AUTHNAME 2
196 #define CBSASL_CB_PASS 3
197 #define CBSASL_CB_LIST_END 4
198 
199     CBSASL_PUBLIC_API
200     cbsasl_error_t cbsasl_client_new(const char *service,
201                                      const char *serverFQDN,
202                                      const char *iplocalport,
203                                      const char *ipremoteport,
204                                      const cbsasl_callback_t *prompt_supp,
205                                      unsigned int flags,
206                                      cbsasl_conn_t **pconn);
207 
208     CBSASL_PUBLIC_API
209     cbsasl_error_t cbsasl_client_start(cbsasl_conn_t *conn,
210                                        const char *mechlist,
211                                        void **prompt_need,
212                                        const char **clientout,
213                                        unsigned int *clientoutlen,
214                                        const char **mech);
215 
216     CBSASL_PUBLIC_API
217     cbsasl_error_t cbsasl_client_step(cbsasl_conn_t *conn,
218                                       const char *serverin,
219                                       unsigned int serverinlen,
220                                       void **not_used,
221                                       const char **clientout,
222                                       unsigned int *clientoutlen);
223 
224 #ifdef __cplusplus
225 }
226 #endif
227 
228 
229 #endif  /* INCLUDE_CBSASL_CBSASL_H_ */
230