xref: /3.0.2-MP2/memcached/include/cbsasl/cbsasl.h (revision ca4ab0ea)
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
23extern "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