include/vlc_keystore.h

   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  * @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  */
  51 enum vlc_keystore_key {
  52     KEY_PROTOCOL,
  53     KEY_USER,
  54     KEY_SERVER,
  55     KEY_PATH,
  56     KEY_PORT,
  57     KEY_REALM,
  58     KEY_AUTHTYPE,
  59     KEY_MAX,
  60 };
  61 #define VLC_KEYSTORE_VALUES_INIT(ppsz_values) memset(ppsz_values, 0, sizeof(const char *) * KEY_MAX)
  62
  63 /**
  64  * Keystore entry returned by vlc_keystore_find()
  65  */
  66 struct vlc_keystore_entry
  67 {
  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  */
  89 VLC_API vlc_keystore *
  90 vlc_keystore_create(vlc_object_t *p_parent);
  91 #define vlc_keystore_create(x) vlc_keystore_create(VLC_OBJECT(x))
  92
  93 /**
  94  * Release a keystore object
  95  */
  96 VLC_API void
  97 vlc_keystore_release(vlc_keystore *p_keystore);
  98
  99
 100 /**
 101  * Store a secret associated with a set of key/values
 102  *
 103  * @param ppsz_values set of key/values, see vlc_keystore_key.
 104  *        ppsz_values[KEY_PROTOCOL] and  ppsz_values[KEY_SERVER] must be valid
 105  *        strings
 106  * @param p_secret binary secret or string password
 107  * @param i_secret_len length of p_secret. If it's less than 0, then p_secret
 108  * is assumed to be a '\0' terminated string
 109  * @param psz_label user friendly label
 110  *
 111  * @return VLC_SUCCESS on success, or VLC_EGENERIC on error
 112  */
 113 VLC_API int
 114 vlc_keystore_store(vlc_keystore *p_keystore,
 115                    const char *const ppsz_values[KEY_MAX],
 116                    const uint8_t* p_secret, ssize_t i_secret_len,
 117                    const char *psz_label);
 118
 119 /**
 120  * Find all entries that match a set of key/values
 121  *
 122  * @param ppsz_values set of key/values, see vlc_keystore_key, any values can
 123  * be NULL
 124  * @param pp_entries list of found entries. To be released with
 125  * vlc_keystore_release_entries()
 126  *
 127  * @return the number of entries
 128  */
 129 VLC_API unsigned int
 130 vlc_keystore_find(vlc_keystore *p_keystore,
 131                   const char *const ppsz_values[KEY_MAX],
 132                   vlc_keystore_entry **pp_entries) VLC_USED;
 133
 134 /**
 135  * Remove all entries that match a set of key/values
 136  *
 137  * @note only entries added by VLC can be removed
 138  *
 139  * @param ppsz_values set of key/values, see vlc_keystore_key, any values can
 140  * be NULL
 141  *
 142  * @return the number of entries
 143  */
 144 VLC_API unsigned int
 145 vlc_keystore_remove(vlc_keystore *p_keystore,
 146                     const char *const ppsz_values[KEY_MAX]);
 147
 148 /**
 149  * Release the list of entries returned by vlc_keystore_find()
 150  */
 151 VLC_API void
 152 vlc_keystore_release_entries(vlc_keystore_entry *p_entries, unsigned int i_count);
 153
 154 /**
 155  * @}
 156  * @defgroup credential Credential API
 157  * @{
 158  */
 159
 160 /**
 161  * @note init with vlc_credential_init()
 162  */
 163 struct vlc_credential
 164 {
 165     /** url to store or to search */
 166     const vlc_url_t *p_url;
 167     /** http realm or smb domain to search, can be overridden after a call to
 168      * vlc_credential_get() */
 169     const char *psz_realm;
 170     /** http authtype to search, can be overridden after a call to
 171      * vlc_credential_get() */
 172     const char *psz_authtype;
 173     /** valid only if vlc_credential_get() returned true */
 174     const char *psz_username;
 175     /** valid only if vlc_credential_get() returned true */
 176     const char *psz_password;
 177
 178     /* internal */
 179     enum {
 180         GET_FROM_URL,
 181         GET_FROM_OPTION,
 182         GET_FROM_MEMORY_KEYSTORE,
 183         GET_FROM_KEYSTORE,
 184         GET_FROM_DIALOG,
 185     } i_get_order;
 186
 187     vlc_keystore *p_keystore;
 188     vlc_keystore_entry *p_entries;
 189     unsigned int i_entries_count;
 190
 191     char *psz_split_domain;
 192     char *psz_var_username;
 193     char *psz_var_password;
 194
 195     char *psz_dialog_username;
 196     char *psz_dialog_password;
 197     bool b_from_keystore;
 198     bool b_store;
 199 };
 200
 201 /**
 202  * Init a credential struct
 203  *
 204  * @note to be cleaned with vlc_credential_clean()
 205  *
 206  * @param psz_url url to store or to search
 207  */
 208 VLC_API void
 209 vlc_credential_init(vlc_credential *p_credential, const vlc_url_t *p_url);
 210
 211 /**
 212  * Clean a credential struct
 213  */
 214 VLC_API void
 215 vlc_credential_clean(vlc_credential *p_credential);
 216
 217 /**
 218  * Get a username/password couple
 219  *
 220  * This will search for a credential using url, VLC options, the vlc_keystore
 221  * or by asking the user via dialog_Login(). This function can be called
 222  * indefinitely, it will first return the user/password from the url (if any),
 223  * then from VLC options (if any), then from the keystore (if any), and finally
 224  * from the dialog (if any). This function will return true as long as the user
 225  * fill the dialog texts and will return false when the user cancel it.
 226  *
 227  * @param p_parent the parent object (for var, keystore and dialog)
 228  * @param psz_option_username VLC option name for the username
 229  * @param psz_option_password VLC option name for the password
 230  * @param psz_dialog_title dialog title, if NULL, this function won't use the
 231  * keystore or the dialog
 232  * @param psz_dialog_fmt dialog text using format
 233  *
 234  * @return true if vlc_credential.psz_username and vlc_credential.psz_password
 235  * are valid, otherwise this function should not be called again.
 236  */
 237
 238 VLC_API bool
 239 vlc_credential_get(vlc_credential *p_credential, vlc_object_t *p_parent,
 240                    const char *psz_option_username,
 241                    const char *psz_option_password,
 242                    const char *psz_dialog_title,
 243                    const char *psz_dialog_fmt, ...) VLC_FORMAT(6, 7);
 244 #define vlc_credential_get(a, b, c, d, e, f, ...) \
 245     vlc_credential_get(a, VLC_OBJECT(b), c, d, e, f, ##__VA_ARGS__)
 246
 247 /**
 248  * Store the last dialog credential returned by vlc_credential_get()
 249  *
 250  * This function will store the credential in the memory keystore if it's
 251  * valid, or will store in the permanent one if it comes from the dialog and if
 252  * the user asked for it.
 253  *
 254  * @return true if the credential was stored or comes from the keystore, false
 255  * otherwise
 256  */
 257 VLC_API bool
 258 vlc_credential_store(vlc_credential *p_credential, vlc_object_t *p_parent);
 259 #define vlc_credential_store(a, b) \
 260     vlc_credential_store(a, VLC_OBJECT(b))
 261
 262 /**
 263  * @}
 264  * @defgroup keystore_implementation Implemented by keystore modules
 265  * @{
 266  */
 267
 268 #define VLC_KEYSTORE_NAME "libVLC"
 269
 270 static inline int
 271 vlc_keystore_entry_set_secret(vlc_keystore_entry *p_entry,
 272                               const uint8_t *p_secret, size_t i_secret_len)
 273 {
 274     p_entry->p_secret = (uint8_t*) malloc(i_secret_len);
 275     if (!p_entry->p_secret)
 276         return VLC_EGENERIC;
 277     memcpy(p_entry->p_secret, p_secret, i_secret_len);
 278     p_entry->i_secret_len = i_secret_len;
 279     return VLC_SUCCESS;
 280 }
 281
 282 static inline void
 283 vlc_keystore_release_entry(vlc_keystore_entry *p_entry)
 284 {
 285     for (unsigned int j = 0; j < KEY_MAX; ++j)
 286     {
 287         free(p_entry->ppsz_values[j]);
 288         p_entry->ppsz_values[j] = NULL;
 289     }
 290     free(p_entry->p_secret);
 291     p_entry->p_secret = NULL;
 292 }
 293
 294 typedef struct vlc_keystore_sys vlc_keystore_sys;
 295 struct vlc_keystore
 296 {
 297     struct vlc_common_members obj;
 298     module_t            *p_module;
 299     vlc_keystore_sys    *p_sys;
 300
 301     /** See vlc_keystore_store() */
 302     int                 (*pf_store)(vlc_keystore *p_keystore,
 303                                     const char *const ppsz_values[KEY_MAX],
 304                                     const uint8_t *p_secret,
 305                                     size_t i_secret_len, const char *psz_label);
 306     /**  See vlc_keystore_find() */
 307     unsigned int        (*pf_find)(vlc_keystore *p_keystore,
 308                                    const char *const ppsz_values[KEY_MAX],
 309                                    vlc_keystore_entry **pp_entries);
 310
 311     /** See vlc_keystore_remove() */
 312     unsigned int        (*pf_remove)(vlc_keystore *p_keystore,
 313                                      const char *const ppsz_values[KEY_MAX]);
 314 };
 315
 316 /** @} @} */
 317
 318 #endif