VLC 4.0.0-dev
Loading...
Searching...
No Matches
vlc_keystore.h
Go to the documentation of this file.
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
26typedef struct vlc_keystore vlc_keystore;
30/* Called from src/libvlc.c */
31int
33
34/* Called from src/libvlc.c */
35void
37
38/**
39 * @defgroup keystore Keystore and credential API
40 * @ingroup os
41 * @{
42 * @file
43 * This file declares vlc keystore API
44 * @defgroup keystore_public Keystore public API
45 * @{
46 */
47
48/**
49 * List of keys that can be stored via the keystore API
50 */
60};
61#define VLC_KEYSTORE_VALUES_INIT(ppsz_values) memset(ppsz_values, 0, sizeof(const char *) * KEY_MAX)
63/**
64 * Keystore entry returned by vlc_keystore_find()
65 */
68 /** Set of key/values. Values can be NULL */
69 char * ppsz_values[KEY_MAX];
70 /** Secret password */
71 uint8_t * p_secret;
72 /** Length of the secret */
73 size_t i_secret_len;
74};
75
76/**
77 * Create a keystore object
78 *
79 * A keystore object is persistent across runtime. It is saved on local
80 * filesystem via a vlc keystore module (KWallet, SecretService, Apple Keychain
81 * Service ...).
82 *
83 * @note to be released with vlc_keystore_release()
84 *
85 * @param p_parent the parent object used to create the keystore object
86 *
87 * @return a pointer to the keystore object, or NULL in case of error
88 */
91#define vlc_keystore_create(x) vlc_keystore_create(VLC_OBJECT(x))
93/**
94 * Release a keystore object
95 */
96VLC_API void
98
99
100/**
101 * Store a secret associated with a set of key/values
102 *
103 * @param p_keystore the keystore to store the secret into
104 * @param ppsz_values set of key/values, see vlc_keystore_key.
105 * ppsz_values[KEY_PROTOCOL] and ppsz_values[KEY_SERVER] must be valid
106 * strings
107 * @param p_secret binary secret or string password
108 * @param i_secret_len length of p_secret. If it's less than 0, then p_secret
109 * is assumed to be a '\0' terminated string
110 * @param psz_label user friendly label
111 *
112 * @return VLC_SUCCESS on success, or VLC_EGENERIC on error
113 */
114VLC_API int
116 const char *const ppsz_values[KEY_MAX],
117 const uint8_t* p_secret, ssize_t i_secret_len,
118 const char *psz_label);
119
120/**
121 * Find all entries that match a set of key/values
122 *
123 * @param p_keystore the keystore instance to look into
124 * @param ppsz_values set of key/values, see vlc_keystore_key, any values can
125 * be NULL
126 * @param pp_entries list of found entries. To be released with
127 * vlc_keystore_release_entries()
128 *
129 * @return the number of entries
130 */
131VLC_API unsigned int
133 const char *const ppsz_values[KEY_MAX],
134 vlc_keystore_entry **pp_entries) VLC_USED;
135
136/**
137 * Remove all entries that match a set of key/values
138 *
139 * @note only entries added by VLC can be removed
140 *
141 * @param p_keystore the keystore instance to remove the secrets from
142 * @param ppsz_values set of key/values, see vlc_keystore_key, any values can
143 * be NULL
144 *
145 * @return the number of entries
146 */
147VLC_API unsigned int
149 const char *const ppsz_values[KEY_MAX]);
150
151/**
152 * Release the list of entries returned by vlc_keystore_find()
153 */
154VLC_API void
155vlc_keystore_release_entries(vlc_keystore_entry *p_entries, unsigned int i_count);
156
157/**
158 * @}
159 * @defgroup credential Credential API
160 * @{
161 */
162
163/**
164 * @note init with vlc_credential_init()
165 */
166struct vlc_credential
168 /** url to store or to search */
169 const vlc_url_t *p_url;
170 /** http realm or smb domain to search, can be overridden after a call to
171 * vlc_credential_get() */
172 const char *psz_realm;
173 /** http authtype to search, can be overridden after a call to
174 * vlc_credential_get() */
175 const char *psz_authtype;
176 /** valid only if vlc_credential_get() returned true */
177 const char *psz_username;
178 /** valid only if vlc_credential_get() returned true */
179 const char *psz_password;
181 /* internal */
182 enum {
192 unsigned int i_entries_count;
194 char *psz_split_domain;
203
204/**
205 * Init a credential struct
206 *
207 * @note to be cleaned with vlc_credential_clean()
208 *
209 * @param p_credential a credential instance to initialize
210 * @param p_url url to store or to search
211 */
212VLC_API void
213vlc_credential_init(vlc_credential *p_credential, const vlc_url_t *p_url);
214
215/**
216 * Clean a credential struct
217 */
218VLC_API void
220
221/**
222 * Get a username/password couple
223 *
224 * This will search for a credential using url, VLC options, the vlc_keystore
225 * or by asking the user via dialog_Login(). This function can be called
226 * indefinitely, it will first return the user/password from the url (if any),
227 * then from VLC options (if any), then from the keystore (if any), and finally
228 * from the dialog (if any). This function will return true as long as the user
229 * fill the dialog texts and will return false when the user cancel it.
230 *
231 * @param p_credential a credential instance initialized with TODO
232 * @param p_parent the parent object (for var, keystore and dialog)
233 * @param psz_option_username VLC option name for the username
234 * @param psz_option_password VLC option name for the password
235 * @param psz_dialog_title dialog title, if NULL, this function won't use the
236 * keystore or the dialog
237 * @param psz_dialog_fmt dialog text using format
238 *
239 * @return 0 if vlc_credential.psz_username and vlc_credential.psz_password
240 * are valid, or a negative errno code.
241 */
242
243VLC_API int
244vlc_credential_get(vlc_credential *p_credential, vlc_object_t *p_parent,
245 const char *psz_option_username,
246 const char *psz_option_password,
247 const char *psz_dialog_title,
248 const char *psz_dialog_fmt, ...) VLC_FORMAT(6, 7);
249#define vlc_credential_get(a, b, c, d, e, f, ...) \
250 vlc_credential_get(a, VLC_OBJECT(b), c, d, e, f, ##__VA_ARGS__)
251
252/**
253 * Store the last dialog credential returned by vlc_credential_get()
254 *
255 * This function will store the credential in the memory keystore if it's
256 * valid, or will store in the permanent one if it comes from the dialog and if
257 * the user asked for it.
258 *
259 * @return true if the credential was stored or comes from the keystore, false
260 * otherwise
261 */
262VLC_API bool
263vlc_credential_store(vlc_credential *p_credential, vlc_object_t *p_parent);
264#define vlc_credential_store(a, b) \
265 vlc_credential_store(a, VLC_OBJECT(b))
266
267/**
268 * @}
269 * @defgroup keystore_implementation Implemented by keystore modules
270 * @{
271 */
272
273#define VLC_KEYSTORE_NAME "libVLC"
275static inline int
277 const uint8_t *p_secret, size_t i_secret_len)
278{
279 p_entry->p_secret = (uint8_t*) malloc(i_secret_len);
280 if (!p_entry->p_secret)
281 return VLC_EGENERIC;
282 memcpy(p_entry->p_secret, p_secret, i_secret_len);
283 p_entry->i_secret_len = i_secret_len;
284 return VLC_SUCCESS;
285}
286
287static inline void
290 for (unsigned int j = 0; j < KEY_MAX; ++j)
291 {
292 free(p_entry->ppsz_values[j]);
293 p_entry->ppsz_values[j] = NULL;
294 }
295 free(p_entry->p_secret);
296 p_entry->p_secret = NULL;
297}
298
302 struct vlc_object_t obj;
306 /** See vlc_keystore_store() */
307 int (*pf_store)(vlc_keystore *p_keystore,
308 const char *const ppsz_values[KEY_MAX],
309 const uint8_t *p_secret,
310 size_t i_secret_len, const char *psz_label);
311 /** See vlc_keystore_find() */
312 unsigned int (*pf_find)(vlc_keystore *p_keystore,
313 const char *const ppsz_values[KEY_MAX],
314 vlc_keystore_entry **pp_entries);
315
316 /** See vlc_keystore_remove() */
317 unsigned int (*pf_remove)(vlc_keystore *p_keystore,
318 const char *const ppsz_values[KEY_MAX]);
319};
320
321/** @} */
322/** @} */
323
324#endif
#define VLC_USED
Definition fourcc_gen.c:32
#define VLC_API
Definition fourcc_gen.c:31
#define VLC_FORMAT(x, y)
String format function annotation.
Definition vlc_common.h:193
#define vlc_credential_get(a, b, c, d, e, f,...)
Definition vlc_keystore.h:250
void vlc_credential_clean(vlc_credential *p_credential)
Clean a credential struct.
Definition keystore.c:360
void vlc_credential_init(vlc_credential *p_credential, const vlc_url_t *p_url)
Init a credential struct.
Definition keystore.c:350
#define vlc_credential_store(a, b)
Definition vlc_keystore.h:265
#define VLC_EGENERIC
Unspecified error.
Definition vlc_common.h:480
#define VLC_SUCCESS
No error.
Definition vlc_common.h:478
static void vlc_keystore_release_entry(vlc_keystore_entry *p_entry)
Definition vlc_keystore.h:289
static int vlc_keystore_entry_set_secret(vlc_keystore_entry *p_entry, const uint8_t *p_secret, size_t i_secret_len)
Definition vlc_keystore.h:277
struct vlc_keystore_sys vlc_keystore_sys
Definition vlc_keystore.h:300
#define vlc_keystore_create(x)
Definition vlc_keystore.h:92
void vlc_keystore_release(vlc_keystore *p_keystore)
Release a keystore object.
Definition keystore.c:71
unsigned int vlc_keystore_find(vlc_keystore *p_keystore, const char *const ppsz_values[KEY_MAX], vlc_keystore_entry **pp_entries)
Find all entries that match a set of key/values.
Definition keystore.c:110
unsigned int vlc_keystore_remove(vlc_keystore *p_keystore, const char *const ppsz_values[KEY_MAX])
Remove all entries that match a set of key/values.
Definition keystore.c:119
vlc_keystore_key
List of keys that can be stored via the keystore API.
Definition vlc_keystore.h:52
void vlc_keystore_release_entries(vlc_keystore_entry *p_entries, unsigned int i_count)
Release the list of entries returned by vlc_keystore_find()
Definition keystore.c:127
int vlc_keystore_store(vlc_keystore *p_keystore, const char *const ppsz_values[KEY_MAX], const uint8_t *p_secret, ssize_t i_secret_len, const char *psz_label)
Store a secret associated with a set of key/values.
Definition keystore.c:80
@ KEY_PROTOCOL
Definition vlc_keystore.h:53
@ KEY_PATH
Definition vlc_keystore.h:56
@ KEY_USER
Definition vlc_keystore.h:54
@ KEY_SERVER
Definition vlc_keystore.h:55
@ KEY_REALM
Definition vlc_keystore.h:58
@ KEY_MAX
Definition vlc_keystore.h:60
@ KEY_AUTHTYPE
Definition vlc_keystore.h:59
@ KEY_PORT
Definition vlc_keystore.h:57
Definition vlc_objects.h:103
Internal module descriptor.
Definition modules.h:76
Definition vlc_keystore.h:168
const char * psz_authtype
http authtype to search, can be overridden after a call to vlc_credential_get()
Definition vlc_keystore.h:176
unsigned int i_entries_count
Definition vlc_keystore.h:193
char * psz_var_password
Definition vlc_keystore.h:197
char * psz_var_username
Definition vlc_keystore.h:196
enum vlc_credential::@236 i_get_order
bool b_store
Definition vlc_keystore.h:202
vlc_keystore_entry * p_entries
Definition vlc_keystore.h:192
char * psz_dialog_username
Definition vlc_keystore.h:199
char * psz_split_domain
Definition vlc_keystore.h:195
@ GET_FROM_KEYSTORE
Definition vlc_keystore.h:187
@ GET_FROM_MEMORY_KEYSTORE
Definition vlc_keystore.h:186
@ GET_FROM_URL
Definition vlc_keystore.h:184
@ GET_FROM_DIALOG
Definition vlc_keystore.h:188
@ GET_FROM_OPTION
Definition vlc_keystore.h:185
const char * psz_realm
http realm or smb domain to search, can be overridden after a call to vlc_credential_get()
Definition vlc_keystore.h:173
bool b_from_keystore
Definition vlc_keystore.h:201
char * psz_dialog_password
Definition vlc_keystore.h:200
const char * psz_username
valid only if vlc_credential_get() returned true
Definition vlc_keystore.h:178
vlc_keystore * p_keystore
Definition vlc_keystore.h:191
const vlc_url_t * p_url
url to store or to search
Definition vlc_keystore.h:170
const char * psz_password
valid only if vlc_credential_get() returned true
Definition vlc_keystore.h:180
Keystore entry returned by vlc_keystore_find()
Definition vlc_keystore.h:68
uint8_t * p_secret
Secret password.
Definition vlc_keystore.h:72
char * ppsz_values[KEY_MAX]
Set of key/values.
Definition vlc_keystore.h:70
size_t i_secret_len
Length of the secret.
Definition vlc_keystore.h:74
Definition vlc_keystore.h:302
unsigned int(* pf_remove)(vlc_keystore *p_keystore, const char *const ppsz_values[KEY_MAX])
See vlc_keystore_remove()
Definition vlc_keystore.h:318
int(* pf_store)(vlc_keystore *p_keystore, const char *const ppsz_values[KEY_MAX], const uint8_t *p_secret, size_t i_secret_len, const char *psz_label)
See vlc_keystore_store()
Definition vlc_keystore.h:308
struct vlc_object_t obj
Definition vlc_keystore.h:303
unsigned int(* pf_find)(vlc_keystore *p_keystore, const char *const ppsz_values[KEY_MAX], vlc_keystore_entry **pp_entries)
See vlc_keystore_find()
Definition vlc_keystore.h:313
module_t * p_module
Definition vlc_keystore.h:304
vlc_keystore_sys * p_sys
Definition vlc_keystore.h:305
VLC object common members.
Definition vlc_objects.h:53
Definition vlc_url.h:146
This file is a collection of common definitions and types.
void libvlc_InternalKeystoreClean(libvlc_int_t *p_libvlc)
Definition keystore.c:145
int libvlc_InternalKeystoreInit(libvlc_int_t *p_libvlc)
Definition keystore.c:135
char psz_label[13]
Definition vout_intf.c:90