1 /*****************************************************************************
2 * vlc_keystore.h:
3 *****************************************************************************
4 * Copyright (C) 2015-2016 VLC authors and VideoLAN
5 *
6 * This program is free software; you can redistribute it and/or modify it
7 * under the terms of the GNU Lesser General Public License as published by
8 * the Free Software Foundation; either version 2.1 of the License, or
9 * (at your option) any later version.
10 *
11 * This program is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 * GNU Lesser General Public License for more details.
15 *
16 * You should have received a copy of the GNU Lesser General Public License
17 * along with this program; if not, write to the Free Software Foundation,
18 * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
19 *****************************************************************************/
20
21 #ifndef VLC_KEYSTORE_H
22 # define VLC_KEYSTORE_H
23
24 #include <vlc_common.h>
25
26 typedef struct vlc_keystore vlc_keystore;
27 typedef struct vlc_keystore_entry vlc_keystore_entry;
28 typedef struct vlc_credential vlc_credential;
29
30 /* Called from src/libvlc.c */
31 int
32 libvlc_InternalKeystoreInit(libvlc_int_t *p_libvlc);
33
34 /* Called from src/libvlc.c */
35 void
36 libvlc_InternalKeystoreClean(libvlc_int_t *p_libvlc);
37
38 /**
39 * @defgroup keystore Keystore and credential API
40 * @{
41 * @file
42 * This file declares vlc keystore API
43 * @defgroup keystore_public Keystore public API
44 * @{
45 */
46
47 /**
48 * List of keys that can be stored via the keystore API
49 */
50 enum vlc_keystore_key {
51 KEY_PROTOCOL,
52 KEY_USER,
53 KEY_SERVER,
54 KEY_PATH,
55 KEY_PORT,
56 KEY_REALM,
57 KEY_AUTHTYPE,
58 KEY_MAX,
59 };
60 #define VLC_KEYSTORE_VALUES_INIT(ppsz_values) memset(ppsz_values, 0, sizeof(const char *) * KEY_MAX)
61
62 /**
63 * Keystore entry returned by vlc_keystore_find()
64 */
65 struct vlc_keystore_entry
66 {
67 /** Set of key/values. Values can be NULL */
68 char * ppsz_values[KEY_MAX];
69 /** Secret password */
70 uint8_t * p_secret;
71 /** Length of the secret */
72 size_t i_secret_len;
73 };
74
75 /**
76 * Create a keystore object
77 *
78 * A keystore object is persistent across runtime. It is saved on local
79 * filesystem via a vlc keystore module (KWallet, SecretService, Apple Keychain
80 * Service ...).
81 *
82 * @note to be released with vlc_keystore_release()
83 *
84 * @param p_parent the parent object used to create the keystore object
85 *
86 * @return a pointer to the keystore object, or NULL in case of error
87 */
88 VLC_API vlc_keystore *
89 vlc_keystore_create(vlc_object_t *p_parent);
90 #define vlc_keystore_create(x) vlc_keystore_create(VLC_OBJECT(x))
91
92 /**
93 * Release a keystore object
94 */
95 VLC_API void
96 vlc_keystore_release(vlc_keystore *p_keystore);
97
98
99 /**
100 * Store a secret associated with a set of key/values
101 *
102 * @param ppsz_values set of key/values, see vlc_keystore_key.
103 * ppsz_values[KEY_PROTOCOL] and ppsz_values[KEY_SERVER] must be valid
104 * strings
105 * @param p_secret binary secret or string password
106 * @param i_secret_len length of p_secret. If it's less than 0, then p_secret
107 * is assumed to be a '\0' terminated string
108 * @param psz_label user friendly label
109 *
110 * @return VLC_SUCCESS on success, or VLC_EGENERIC on error
111 */
112 VLC_API int
113 vlc_keystore_store(vlc_keystore *p_keystore,
114 const char *const ppsz_values[KEY_MAX],
115 const uint8_t* p_secret, ssize_t i_secret_len,
116 const char *psz_label);
117
118 /**
119 * Find all entries that match a set of key/values
120 *
121 * @param ppsz_values set of key/values, see vlc_keystore_key, any values can
122 * be NULL
123 * @param pp_entries list of found entries. To be released with
124 * vlc_keystore_release_entries()
125 *
126 * @return the number of entries
127 */
128 VLC_API unsigned int
129 vlc_keystore_find(vlc_keystore *p_keystore,
130 const char *const ppsz_values[KEY_MAX],
131 vlc_keystore_entry **pp_entries) VLC_USED;
132
133 /**
134 * Remove all entries that match a set of key/values
135 *
136 * @note only entries added by VLC can be removed
137 *
138 * @param ppsz_values set of key/values, see vlc_keystore_key, any values can
139 * be NULL
140 *
141 * @return the number of entries
142 */
143 VLC_API unsigned int
144 vlc_keystore_remove(vlc_keystore *p_keystore,
145 const char *const ppsz_values[KEY_MAX]);
146
147 /**
148 * Release the list of entries returned by vlc_keystore_find()
149 */
150 VLC_API void
151 vlc_keystore_release_entries(vlc_keystore_entry *p_entries, unsigned int i_count);
152
153 /**
154 * @}
155 * @defgroup credential Credential API
156 * @{
157 */
158
159 /**
160 * @note init with vlc_credential_init()
161 */
162 struct vlc_credential
163 {
164 /** url to store or to search */
165 const vlc_url_t *p_url;
166 /** http realm or smb domain to search, can be overridden after a call to
167 * vlc_credential_get() */
168 const char *psz_realm;
169 /** http authtype to search, can be overridden after a call to
170 * vlc_credential_get() */
171 const char *psz_authtype;
172 /** valid only if vlc_credential_get() returned true */
173 const char *psz_username;
174 /** valid only if vlc_credential_get() returned true */
175 const char *psz_password;
176
177 /* internal */
178 enum {
179 GET_FROM_URL,
180 GET_FROM_OPTION,
181 GET_FROM_MEMORY_KEYSTORE,
182 GET_FROM_KEYSTORE,
183 GET_FROM_DIALOG,
184 } i_get_order;
185
186 vlc_keystore *p_keystore;
187 vlc_keystore_entry *p_entries;
188 unsigned int i_entries_count;
189
190 char *psz_split_domain;
191 char *psz_var_username;
192 char *psz_var_password;
193
194 char *psz_dialog_username;
195 char *psz_dialog_password;
196 bool b_from_keystore;
197 bool b_store;
198 };
199
200 /**
201 * Init a credential struct
202 *
203 * @note to be cleaned with vlc_credential_clean()
204 *
205 * @param psz_url url to store or to search
206 */
207 VLC_API void
208 vlc_credential_init(vlc_credential *p_credential, const vlc_url_t *p_url);
209
210 /**
211 * Clean a credential struct
212 */
213 VLC_API void
214 vlc_credential_clean(vlc_credential *p_credential);
215
216 /**
217 * Get a username/password couple
218 *
219 * This will search for a credential using url, VLC options, the vlc_keystore
220 * or by asking the user via dialog_Login(). This function can be called
221 * indefinitely, it will first return the user/password from the url (if any),
222 * then from VLC options (if any), then from the keystore (if any), and finally
223 * from the dialog (if any). This function will return true as long as the user
224 * fill the dialog texts and will return false when the user cancel it.
225 *
226 * @param p_parent the parent object (for var, keystore and dialog)
227 * @param psz_option_username VLC option name for the username
228 * @param psz_option_password VLC option name for the password
229 * @param psz_dialog_title dialog title, if NULL, this function won't use the
230 * keystore or the dialog
231 * @param psz_dialog_fmt dialog text using format
232 *
233 * @return true if vlc_credential.psz_username and vlc_credential.psz_password
234 * are valid, otherwise this function should not be called again.
235 */
236
237 VLC_API bool
238 vlc_credential_get(vlc_credential *p_credential, vlc_object_t *p_parent,
239 const char *psz_option_username,
240 const char *psz_option_password,
241 const char *psz_dialog_title,
242 const char *psz_dialog_fmt, ...) VLC_FORMAT(6, 7);
243 #define vlc_credential_get(a, b, c, d, e, f, ...) \
244 vlc_credential_get(a, VLC_OBJECT(b), c, d, e, f, ##__VA_ARGS__)
245
246 /**
247 * Store the last dialog credential returned by vlc_credential_get()
248 *
249 * This function will store the credential in the memory keystore if it's
250 * valid, or will store in the permanent one if it comes from the dialog and if
251 * the user asked for it.
252 *
253 * @return true if the credential was stored or comes from the keystore, false
254 * otherwise
255 */
256 VLC_API bool
257 vlc_credential_store(vlc_credential *p_credential, vlc_object_t *p_parent);
258 #define vlc_credential_store(a, b) \
259 vlc_credential_store(a, VLC_OBJECT(b))
260
261 /**
262 * @}
263 * @defgroup keystore_implementation Implemented by keystore modules
264 * @{
265 */
266
267 #define VLC_KEYSTORE_NAME "libVLC"
268
269 static inline int
vlc_keystore_entry_set_secret(vlc_keystore_entry * p_entry,const uint8_t * p_secret,size_t i_secret_len)270 vlc_keystore_entry_set_secret(vlc_keystore_entry *p_entry,
271 const uint8_t *p_secret, size_t i_secret_len)
272 {
273 p_entry->p_secret = (uint8_t*) malloc(i_secret_len);
274 if (!p_entry->p_secret)
275 return VLC_EGENERIC;
276 memcpy(p_entry->p_secret, p_secret, i_secret_len);
277 p_entry->i_secret_len = i_secret_len;
278 return VLC_SUCCESS;
279 }
280
281 static inline void
vlc_keystore_release_entry(vlc_keystore_entry * p_entry)282 vlc_keystore_release_entry(vlc_keystore_entry *p_entry)
283 {
284 for (unsigned int j = 0; j < KEY_MAX; ++j)
285 {
286 free(p_entry->ppsz_values[j]);
287 p_entry->ppsz_values[j] = NULL;
288 }
289 free(p_entry->p_secret);
290 p_entry->p_secret = NULL;
291 }
292
293 typedef struct vlc_keystore_sys vlc_keystore_sys;
294 struct vlc_keystore
295 {
296 VLC_COMMON_MEMBERS
297 module_t *p_module;
298 vlc_keystore_sys *p_sys;
299
300 /** See vlc_keystore_store() */
301 int (*pf_store)(vlc_keystore *p_keystore,
302 const char *const ppsz_values[KEY_MAX],
303 const uint8_t *p_secret,
304 size_t i_secret_len, const char *psz_label);
305 /** See vlc_keystore_find() */
306 unsigned int (*pf_find)(vlc_keystore *p_keystore,
307 const char *const ppsz_values[KEY_MAX],
308 vlc_keystore_entry **pp_entries);
309
310 /** See vlc_keystore_remove() */
311 unsigned int (*pf_remove)(vlc_keystore *p_keystore,
312 const char *const ppsz_values[KEY_MAX]);
313 };
314
315 /** @} @} */
316
317 #endif
318