src/TortoiseMerge/svninclude/svn_auth.h

   1 /**\r
   2  * @copyright\r
   3  * ====================================================================\r
   4  * Copyright (c) 2002-2009 CollabNet.  All rights reserved.\r
   5  *\r
   6  * This software is licensed as described in the file COPYING, which\r
   7  * you should have received as part of this distribution.  The terms\r
   8  * are also available at http://subversion.tigris.org/license-1.html.\r
   9  * If newer versions of this license are posted there, you may use a\r
  10  * newer version instead, at your option.\r
  11  *\r
  12  * This software consists of voluntary contributions made by many\r
  13  * individuals.  For exact contribution history, see the revision\r
  14  * history and logs, available at http://subversion.tigris.org/.\r
  15  * ====================================================================\r
  16  * @endcopyright\r
  17  *\r
  18  * @file svn_auth.h\r
  19  * @brief Subversion's authentication system\r
  20  */\r
  21 \r
  22 #ifndef SVN_AUTH_H\r
  23 #define SVN_AUTH_H\r
  24 \r
  25 #include <apr.h>\r
  26 #include <apr_pools.h>\r
  27 #include <apr_hash.h>\r
  28 #include <apr_tables.h>\r
  29 \r
  30 #include "svn_types.h"\r
  31 #include "svn_config.h"\r
  32 #include "svn_version.h"\r
  33 \r
  34 #ifdef __cplusplus\r
  35 extern "C" {\r
  36 #endif /* __cplusplus */\r
  37 \r
  38 /** Overview of the svn authentication system.\r
  39  *\r
  40  * We define an authentication "provider" as a module that is able to\r
  41  * return a specific set of credentials. (e.g. username/password,\r
  42  * certificate, etc.)  Each provider implements a vtable that\r
  43  *\r
  44  * - can fetch initial credentials\r
  45  * - can retry the fetch (or try to fetch something different)\r
  46  * - can store the credentials for future use\r
  47  *\r
  48  * For any given type of credentials, there can exist any number of\r
  49  * separate providers -- each provider has a different method of\r
  50  * fetching. (i.e. from a disk store, by prompting the user, etc.)\r
  51  *\r
  52  * The application begins by creating an auth baton object, and\r
  53  * "registers" some number of providers with the auth baton, in a\r
  54  * specific order.  (For example, it may first register a\r
  55  * username/password provider that looks in disk store, then register\r
  56  * a username/password provider that prompts the user.)\r
  57  *\r
  58  * Later on, when any svn library is challenged, it asks the auth\r
  59  * baton for the specific credentials.  If the initial credentials\r
  60  * fail to authenticate, the caller keeps requesting new credentials.\r
  61  * Under the hood, libsvn_auth effectively "walks" over each provider\r
  62  * (in order of registry), one at a time, until all the providers have\r
  63  * exhausted all their retry options.\r
  64  *\r
  65  * This system allows an application to flexibly define authentication\r
  66  * behaviors (by changing registration order), and very easily write\r
  67  * new authentication providers.\r
  68  *\r
  69  * An auth_baton also contains an internal hashtable of run-time\r
  70  * parameters; any provider or library layer can set these run-time\r
  71  * parameters at any time, so that the provider has access to the\r
  72  * data.  (For example, certain run-time data may not be available\r
  73  * until an authentication challenge is made.)  Each credential type\r
  74  * must document the run-time parameters that are made available to\r
  75  * its providers.\r
  76  *\r
  77  * @defgroup auth_fns Authentication functions\r
  78  * @{\r
  79  */\r
  80 \r
  81 \r
  82 /** The type of a Subversion authentication object */\r
  83 typedef struct svn_auth_baton_t svn_auth_baton_t;\r
  84 \r
  85 /** The type of a Subversion authentication-iteration object */\r
  86 typedef struct svn_auth_iterstate_t svn_auth_iterstate_t;\r
  87 \r
  88 \r
  89 /** The main authentication "provider" vtable. */\r
  90 typedef struct svn_auth_provider_t\r
  91 {\r
  92   /** The kind of credentials this provider knows how to retrieve. */\r
  93   const char *cred_kind;\r
  94 \r
  95   /** Get an initial set of credentials.\r
  96    *\r
  97    * Set @a *credentials to a set of valid credentials within @a\r
  98    * realmstring, or NULL if no credentials are available.  Set @a\r
  99    * *iter_baton to context that allows a subsequent call to @c\r
 100    * next_credentials, in case the first credentials fail to\r
 101    * authenticate.  @a provider_baton is general context for the\r
 102    * vtable, @a parameters contains any run-time data that the\r
 103    * provider may need, and @a realmstring comes from the\r
 104    * svn_auth_first_credentials() call.\r
 105    */\r
 106   svn_error_t * (*first_credentials)(void **credentials,\r
 107                                      void **iter_baton,\r
 108                                      void *provider_baton,\r
 109                                      apr_hash_t *parameters,\r
 110                                      const char *realmstring,\r
 111                                      apr_pool_t *pool);\r
 112 \r
 113   /** Get a different set of credentials.\r
 114    *\r
 115    * Set @a *credentials to another set of valid credentials (using @a\r
 116    * iter_baton as the context from previous call to first_credentials\r
 117    * or next_credentials).  If no more credentials are available, set\r
 118    * @a *credentials to NULL.  If the provider only has one set of\r
 119    * credentials, this function pointer should simply be NULL. @a\r
 120    * provider_baton is general context for the vtable, @a parameters\r
 121    * contains any run-time data that the provider may need, and @a\r
 122    * realmstring comes from the svn_auth_first_credentials() call.\r
 123    */\r
 124   svn_error_t * (*next_credentials)(void **credentials,\r
 125                                     void *iter_baton,\r
 126                                     void *provider_baton,\r
 127                                     apr_hash_t *parameters,\r
 128                                     const char *realmstring,\r
 129                                     apr_pool_t *pool);\r
 130 \r
 131   /** Save credentials.\r
 132    *\r
 133    * Store @a credentials for future use.  @a provider_baton is\r
 134    * general context for the vtable, and @a parameters contains any\r
 135    * run-time data the provider may need.  Set @a *saved to TRUE if\r
 136    * the save happened, or FALSE if not.  The provider is not required\r
 137    * to save; if it refuses or is unable to save for non-fatal\r
 138    * reasons, return FALSE.  If the provider never saves data, then\r
 139    * this function pointer should simply be NULL. @a realmstring comes\r
 140    * from the svn_auth_first_credentials() call.\r
 141    */\r
 142   svn_error_t * (*save_credentials)(svn_boolean_t *saved,\r
 143                                     void *credentials,\r
 144                                     void *provider_baton,\r
 145                                     apr_hash_t *parameters,\r
 146                                     const char *realmstring,\r
 147                                     apr_pool_t *pool);\r
 148 \r
 149 } svn_auth_provider_t;\r
 150 \r
 151 \r
 152 /** A provider object, ready to be put into an array and given to\r
 153     svn_auth_open(). */\r
 154 typedef struct svn_auth_provider_object_t\r
 155 {\r
 156   const svn_auth_provider_t *vtable;\r
 157   void *provider_baton;\r
 158 \r
 159 } svn_auth_provider_object_t;\r
 160 \r
 161 /** The type of function returning authentication provider. */\r
 162 typedef void (*svn_auth_simple_provider_func_t)\r
 163   (svn_auth_provider_object_t **provider,\r
 164    apr_pool_t *pool);\r
 165 \r
 166 \f\r
 167 /** Specific types of credentials **/\r
 168 \r
 169 /** Simple username/password pair credential kind.\r
 170  *\r
 171  * The following auth parameters are available to the providers:\r
 172  *\r
 173  * - @c SVN_AUTH_PARAM_CONFIG_CATEGORY_CONFIG (@c svn_config_t*)\r
 174  * - @c SVN_AUTH_PARAM_CONFIG_CATEGORY_SERVERS (@c svn_config_t*)\r
 175  *\r
 176  * The following auth parameters may be available to the providers:\r
 177  *\r
 178  * - @c SVN_AUTH_PARAM_NO_AUTH_CACHE (@c void*)\r
 179  * - @c SVN_AUTH_PARAM_DEFAULT_USERNAME (@c char*)\r
 180  * - @c SVN_AUTH_PARAM_DEFAULT_PASSWORD (@c char*)\r
 181  */\r
 182 #define SVN_AUTH_CRED_SIMPLE "svn.simple"\r
 183 \r
 184 /** @c SVN_AUTH_CRED_SIMPLE credentials. */\r
 185 typedef struct svn_auth_cred_simple_t\r
 186 {\r
 187   /** Username */\r
 188   const char *username;\r
 189   /** Password */\r
 190   const char *password;\r
 191   /** Indicates if the credentials may be saved (to disk). For example, a\r
 192    * GUI prompt implementation with a remember password checkbox shall set\r
 193    * @a may_save to TRUE if the checkbox is checked.\r
 194    */\r
 195   svn_boolean_t may_save;\r
 196 } svn_auth_cred_simple_t;\r
 197 \r
 198 \r
 199 /** Username credential kind.\r
 200  *\r
 201  * The following optional auth parameters are relevant to the providers:\r
 202  *\r
 203  * - @c SVN_AUTH_PARAM_NO_AUTH_CACHE (@c void*)\r
 204  * - @c SVN_AUTH_PARAM_DEFAULT_USERNAME (@c char*)\r
 205  */\r
 206 #define SVN_AUTH_CRED_USERNAME "svn.username"\r
 207 \r
 208 /** @c SVN_AUTH_CRED_USERNAME credentials. */\r
 209 typedef struct svn_auth_cred_username_t\r
 210 {\r
 211   /** Username */\r
 212   const char *username;\r
 213   /** Indicates if the credentials may be saved (to disk). For example, a\r
 214    * GUI prompt implementation with a remember username checkbox shall set\r
 215    * @a may_save to TRUE if the checkbox is checked.\r
 216    */\r
 217   svn_boolean_t may_save;\r
 218 } svn_auth_cred_username_t;\r
 219 \r
 220 \r
 221 /** SSL client certificate credential type.\r
 222  *\r
 223  * The following auth parameters are available to the providers:\r
 224  *\r
 225  * - @c SVN_AUTH_PARAM_CONFIG_CATEGORY_SERVERS (@c svn_config_t*)\r
 226  * - @c SVN_AUTH_PARAM_SERVER_GROUP (@c char*)\r
 227  *\r
 228  * The following optional auth parameters are relevant to the providers:\r
 229  *\r
 230  * - @c SVN_AUTH_PARAM_NO_AUTH_CACHE (@c void*)\r
 231  */\r
 232 #define SVN_AUTH_CRED_SSL_CLIENT_CERT "svn.ssl.client-cert"\r
 233 \r
 234 /** @c SVN_AUTH_CRED_SSL_CLIENT_CERT credentials. */\r
 235 typedef struct svn_auth_cred_ssl_client_cert_t\r
 236 {\r
 237   /** Absolute path to the certificate file */\r
 238   const char *cert_file;\r
 239   /** Indicates if the credentials may be saved (to disk). For example, a\r
 240    * GUI prompt implementation with a remember certificate checkbox shall\r
 241    * set @a may_save to TRUE if the checkbox is checked.\r
 242    */\r
 243   svn_boolean_t may_save;\r
 244 } svn_auth_cred_ssl_client_cert_t;\r
 245 \r
 246 \r
 247 /** A function returning an SSL client certificate passphrase provider. */\r
 248 typedef void (*svn_auth_ssl_client_cert_pw_provider_func_t)\r
 249   (svn_auth_provider_object_t **provider,\r
 250    apr_pool_t *pool);\r
 251 \r
 252 /** SSL client certificate passphrase credential type.\r
 253  *\r
 254  * @note The realmstring used with this credential type must be a name that\r
 255  * makes it possible for the user to identify the certificate.\r
 256  *\r
 257  * The following auth parameters are available to the providers:\r
 258  *\r
 259  * - @c SVN_AUTH_PARAM_CONFIG_CATEGORY_CONFIG (@c svn_config_t*)\r
 260  * - @c SVN_AUTH_PARAM_CONFIG_CATEGORY_SERVERS (@c svn_config_t*)\r
 261  * - @c SVN_AUTH_PARAM_SERVER_GROUP (@c char*)\r
 262  *\r
 263  * The following optional auth parameters are relevant to the providers:\r
 264  *\r
 265  * - @c SVN_AUTH_PARAM_NO_AUTH_CACHE (@c void*)\r
 266  */\r
 267 #define SVN_AUTH_CRED_SSL_CLIENT_CERT_PW "svn.ssl.client-passphrase"\r
 268 \r
 269 /** @c SVN_AUTH_CRED_SSL_CLIENT_CERT_PW credentials. */\r
 270 typedef struct svn_auth_cred_ssl_client_cert_pw_t\r
 271 {\r
 272   /** Certificate password */\r
 273   const char *password;\r
 274   /** Indicates if the credentials may be saved (to disk). For example, a\r
 275    * GUI prompt implementation with a remember password checkbox shall set\r
 276    * @a may_save to TRUE if the checkbox is checked.\r
 277    */\r
 278   svn_boolean_t may_save;\r
 279 } svn_auth_cred_ssl_client_cert_pw_t;\r
 280 \r
 281 \r
 282 /** SSL server verification credential type.\r
 283  *\r
 284  * The following auth parameters are available to the providers:\r
 285  *\r
 286  * - @c SVN_AUTH_PARAM_CONFIG_CATEGORY_SERVERS (@c svn_config_t*)\r
 287  * - @c SVN_AUTH_PARAM_SERVER_GROUP (@c char*)\r
 288  * - @c SVN_AUTH_PARAM_SSL_SERVER_FAILURES (@c apr_uint32_t*)\r
 289  * - @c SVN_AUTH_PARAM_SSL_SERVER_CERT_INFO\r
 290  *      (@c svn_auth_ssl_server_cert_info_t*)\r
 291  *\r
 292  * The following optional auth parameters are relevant to the providers:\r
 293  *\r
 294  * - @c SVN_AUTH_PARAM_NO_AUTH_CACHE (@c void*)\r
 295  */\r
 296 #define SVN_AUTH_CRED_SSL_SERVER_TRUST "svn.ssl.server"\r
 297 \r
 298 /** SSL server certificate information used by @c\r
 299  * SVN_AUTH_CRED_SSL_SERVER_TRUST providers.\r
 300  */\r
 301 typedef struct svn_auth_ssl_server_cert_info_t\r
 302 {\r
 303   /** Primary CN */\r
 304   const char *hostname;\r
 305   /** ASCII fingerprint */\r
 306   const char *fingerprint;\r
 307   /** ASCII date from which the certificate is valid */\r
 308   const char *valid_from;\r
 309   /** ASCII date until which the certificate is valid */\r
 310   const char *valid_until;\r
 311   /** DN of the certificate issuer */\r
 312   const char *issuer_dname;\r
 313   /** Base-64 encoded DER certificate representation */\r
 314   const char *ascii_cert;\r
 315 } svn_auth_ssl_server_cert_info_t;\r
 316 \r
 317 /**\r
 318  * Return a deep copy of @a info, allocated in @a pool.\r
 319  *\r
 320  * @since New in 1.3.\r
 321  */\r
 322 svn_auth_ssl_server_cert_info_t *\r
 323 svn_auth_ssl_server_cert_info_dup(const svn_auth_ssl_server_cert_info_t *info,\r
 324                                   apr_pool_t *pool);\r
 325 \r
 326 /** @c SVN_AUTH_CRED_SSL_SERVER_TRUST credentials. */\r
 327 typedef struct svn_auth_cred_ssl_server_trust_t\r
 328 {\r
 329   /** Indicates if the credentials may be saved (to disk). For example, a\r
 330    * GUI prompt implementation with a checkbox to accept the certificate\r
 331    * permanently shall set @a may_save to TRUE if the checkbox is checked.\r
 332    */\r
 333   svn_boolean_t may_save;\r
 334   /** Bit mask of the accepted failures */\r
 335   apr_uint32_t accepted_failures;\r
 336 } svn_auth_cred_ssl_server_trust_t;\r
 337 \r
 338 \r
 339 \f\r
 340 /** Credential-constructing prompt functions. **/\r
 341 \r
 342 /** These exist so that different client applications can use\r
 343  * different prompt mechanisms to supply the same credentials.  For\r
 344  * example, if authentication requires a username and password, a\r
 345  * command-line client's prompting function might prompt first for the\r
 346  * username and then for the password, whereas a GUI client's would\r
 347  * present a single dialog box asking for both, and a telepathic\r
 348  * client's would read all the information directly from the user's\r
 349  * mind.  All these prompting functions return the same type of\r
 350  * credential, but the information used to construct the credential is\r
 351  * gathered in an interface-specific way in each case.\r
 352  */\r
 353 \r
 354 /** Set @a *cred by prompting the user, allocating @a *cred in @a pool.\r
 355  * @a baton is an implementation-specific closure.\r
 356  *\r
 357  * If @a realm is non-NULL, maybe use it in the prompt string.\r
 358  *\r
 359  * If @a username is non-NULL, then the user might be prompted only\r
 360  * for a password, but @a *cred would still be filled with both\r
 361  * username and password.  For example, a typical usage would be to\r
 362  * pass @a username on the first call, but then leave it NULL for\r
 363  * subsequent calls, on the theory that if credentials failed, it's\r
 364  * as likely to be due to incorrect username as incorrect password.\r
 365  *\r
 366  * If @a may_save is FALSE, the auth system does not allow the credentials\r
 367  * to be saved (to disk). A prompt function shall not ask the user if the\r
 368  * credentials shall be saved if @a may_save is FALSE. For example, a GUI\r
 369  * client with a remember password checkbox would grey out the checkbox if\r
 370  * @a may_save is FALSE.\r
 371  */\r
 372 typedef svn_error_t *(*svn_auth_simple_prompt_func_t)\r
 373   (svn_auth_cred_simple_t **cred,\r
 374    void *baton,\r
 375    const char *realm,\r
 376    const char *username,\r
 377    svn_boolean_t may_save,\r
 378    apr_pool_t *pool);\r
 379 \r
 380 \r
 381 /** Set @a *cred by prompting the user, allocating @a *cred in @a pool.\r
 382  * @a baton is an implementation-specific closure.\r
 383  *\r
 384  * If @a realm is non-NULL, maybe use it in the prompt string.\r
 385  *\r
 386  * If @a may_save is FALSE, the auth system does not allow the credentials\r
 387  * to be saved (to disk). A prompt function shall not ask the user if the\r
 388  * credentials shall be saved if @a may_save is FALSE. For example, a GUI\r
 389  * client with a remember username checkbox would grey out the checkbox if\r
 390  * @a may_save is FALSE.\r
 391  */\r
 392 typedef svn_error_t *(*svn_auth_username_prompt_func_t)\r
 393   (svn_auth_cred_username_t **cred,\r
 394    void *baton,\r
 395    const char *realm,\r
 396    svn_boolean_t may_save,\r
 397    apr_pool_t *pool);\r
 398 \r
 399 \r
 400 /** @name SSL server certificate failure bits\r
 401  *\r
 402  * @note These values are stored in the on disk auth cache by the SSL\r
 403  * server certificate auth provider, so the meaning of these bits must\r
 404  * not be changed.\r
 405  * @{\r
 406  */\r
 407 /** Certificate is not yet valid. */\r
 408 #define SVN_AUTH_SSL_NOTYETVALID 0x00000001\r
 409 /** Certificate has expired. */\r
 410 #define SVN_AUTH_SSL_EXPIRED     0x00000002\r
 411 /** Certificate's CN (hostname) does not match the remote hostname. */\r
 412 #define SVN_AUTH_SSL_CNMISMATCH  0x00000004\r
 413 /** @brief Certificate authority is unknown (i.e. not trusted) */\r
 414 #define SVN_AUTH_SSL_UNKNOWNCA   0x00000008\r
 415 /** @brief Other failure. This can happen if neon has introduced a new\r
 416  * failure bit that we do not handle yet. */\r
 417 #define SVN_AUTH_SSL_OTHER       0x40000000\r
 418 /** @} */\r
 419 \r
 420 /** Set @a *cred by prompting the user, allocating @a *cred in @a pool.\r
 421  * @a baton is an implementation-specific closure.\r
 422  *\r
 423  * @a cert_info is a structure describing the server cert that was\r
 424  * presented to the client, and @a failures is a bitmask that\r
 425  * describes exactly why the cert could not be automatically validated,\r
 426  * composed from the constants SVN_AUTH_SSL_* (@c SVN_AUTH_SSL_NOTYETVALID\r
 427  * etc.).  @a realm is a string that can be used in the prompt string.\r
 428  *\r
 429  * If @a may_save is FALSE, the auth system does not allow the credentials\r
 430  * to be saved (to disk). A prompt function shall not ask the user if the\r
 431  * credentials shall be saved if @a may_save is FALSE. For example, a GUI\r
 432  * client with a trust permanently checkbox would grey out the checkbox if\r
 433  * @a may_save is FALSE.\r
 434  */\r
 435 typedef svn_error_t *(*svn_auth_ssl_server_trust_prompt_func_t)\r
 436   (svn_auth_cred_ssl_server_trust_t **cred,\r
 437    void *baton,\r
 438    const char *realm,\r
 439    apr_uint32_t failures,\r
 440    const svn_auth_ssl_server_cert_info_t *cert_info,\r
 441    svn_boolean_t may_save,\r
 442    apr_pool_t *pool);\r
 443 \r
 444 \r
 445 /** Set @a *cred by prompting the user, allocating @a *cred in @a pool.\r
 446  * @a baton is an implementation-specific closure.  @a realm is a string\r
 447  * that can be used in the prompt string.\r
 448  *\r
 449  * If @a may_save is FALSE, the auth system does not allow the credentials\r
 450  * to be saved (to disk). A prompt function shall not ask the user if the\r
 451  * credentials shall be saved if @a may_save is FALSE. For example, a GUI\r
 452  * client with a remember certificate checkbox would grey out the checkbox\r
 453  * if @a may_save is FALSE.\r
 454  */\r
 455 typedef svn_error_t *(*svn_auth_ssl_client_cert_prompt_func_t)\r
 456   (svn_auth_cred_ssl_client_cert_t **cred,\r
 457    void *baton,\r
 458    const char *realm,\r
 459    svn_boolean_t may_save,\r
 460    apr_pool_t *pool);\r
 461 \r
 462 \r
 463 /** Set @a *cred by prompting the user, allocating @a *cred in @a pool.\r
 464  * @a baton is an implementation-specific closure.  @a realm is a string\r
 465  * identifying the certificate, and can be used in the prompt string.\r
 466  *\r
 467  * If @a may_save is FALSE, the auth system does not allow the credentials\r
 468  * to be saved (to disk). A prompt function shall not ask the user if the\r
 469  * credentials shall be saved if @a may_save is FALSE. For example, a GUI\r
 470  * client with a remember password checkbox would grey out the checkbox if\r
 471  * @a may_save is FALSE.\r
 472  */\r
 473 typedef svn_error_t *(*svn_auth_ssl_client_cert_pw_prompt_func_t)\r
 474   (svn_auth_cred_ssl_client_cert_pw_t **cred,\r
 475    void *baton,\r
 476    const char *realm,\r
 477    svn_boolean_t may_save,\r
 478    apr_pool_t *pool);\r
 479 \r
 480 /** A type of callback function for asking whether storing a password to\r
 481  * disk in plaintext is allowed.\r
 482  *\r
 483  * In this callback, the client should ask the user whether storing\r
 484  * a password for the realm identified by @a realmstring to disk\r
 485  * in plaintext is allowed.\r
 486  *\r
 487  * The answer is returned in @a *may_save_plaintext.\r
 488  * @a baton is an implementation-specific closure.\r
 489  * All allocations should be done in @a pool.\r
 490  *\r
 491  * @since New in 1.6\r
 492  */\r
 493 typedef svn_error_t *(*svn_auth_plaintext_prompt_func_t)\r
 494   (svn_boolean_t *may_save_plaintext,\r
 495    const char *realmstring,\r
 496    void *baton,\r
 497    apr_pool_t *pool);\r
 498 \r
 499 /** A type of callback function for asking whether storing a passphrase to\r
 500  * disk in plaintext is allowed.\r
 501  *\r
 502  * In this callback, the client should ask the user whether storing\r
 503  * a passphrase for the realm identified by @a realmstring to disk\r
 504  * in plaintext is allowed.\r
 505  *\r
 506  * The answer is returned in @a *may_save_plaintext.\r
 507  * @a baton is an implementation-specific closure.\r
 508  * All allocations should be done in @a pool.\r
 509  *\r
 510  * @since New in 1.6\r
 511  */\r
 512 typedef svn_error_t *(*svn_auth_plaintext_passphrase_prompt_func_t)\r
 513   (svn_boolean_t *may_save_plaintext,\r
 514    const char *realmstring,\r
 515    void *baton,\r
 516    apr_pool_t *pool);\r
 517 \r
 518 \f\r
 519 /** Initialize an authentication system.\r
 520  *\r
 521  * Return an authentication object in @a *auth_baton (allocated in @a\r
 522  * pool) that represents a particular instance of the svn\r
 523  * authentication system.  @a providers is an array of @c\r
 524  * svn_auth_provider_object_t pointers, already allocated in @a pool\r
 525  * and intentionally ordered.  These pointers will be stored within @a\r
 526  * *auth_baton, grouped by credential type, and searched in this exact\r
 527  * order.\r
 528  */\r
 529 void\r
 530 svn_auth_open(svn_auth_baton_t **auth_baton,\r
 531               apr_array_header_t *providers,\r
 532               apr_pool_t *pool);\r
 533 \r
 534 /** Set an authentication run-time parameter.\r
 535  *\r
 536  * Store @a name / @a value pair as a run-time parameter in @a\r
 537  * auth_baton, making the data accessible to all providers.  @a name\r
 538  * and @a value will NOT be duplicated into the auth_baton's pool.\r
 539  * To delete a run-time parameter, pass NULL for @a value.\r
 540  */\r
 541 void\r
 542 svn_auth_set_parameter(svn_auth_baton_t *auth_baton,\r
 543                        const char *name,\r
 544                        const void *value);\r
 545 \r
 546 /** Get an authentication run-time parameter.\r
 547  *\r
 548  * Return a value for run-time parameter @a name from @a auth_baton.\r
 549  * Return NULL if the parameter doesn't exist.\r
 550  */\r
 551 const void *\r
 552 svn_auth_get_parameter(svn_auth_baton_t *auth_baton,\r
 553                        const char *name);\r
 554 \r
 555 /** Universal run-time parameters, made available to all providers.\r
 556 \r
 557     If you are writing a new provider, then to be a "good citizen",\r
 558     you should notice these global parameters!  Note that these\r
 559     run-time params should be treated as read-only by providers; the\r
 560     application is responsible for placing them into the auth_baton\r
 561     hash. */\r
 562 \r
 563 /** The auth-hash prefix indicating that the parameter is global. */\r
 564 #define SVN_AUTH_PARAM_PREFIX "svn:auth:"\r
 565 \r
 566 /**\r
 567  * @name Default credentials defines\r
 568  * Any 'default' credentials that came in through the application itself,\r
 569  * (e.g. --username and --password options). Property values are\r
 570  * const char *.\r
 571  * @{ */\r
 572 #define SVN_AUTH_PARAM_DEFAULT_USERNAME  SVN_AUTH_PARAM_PREFIX "username"\r
 573 #define SVN_AUTH_PARAM_DEFAULT_PASSWORD  SVN_AUTH_PARAM_PREFIX "password"\r
 574 /** @} */\r
 575 \r
 576 /** @brief The application doesn't want any providers to prompt\r
 577  * users. Property value is irrelevant; only property's existence\r
 578  * matters. */\r
 579 #define SVN_AUTH_PARAM_NON_INTERACTIVE  SVN_AUTH_PARAM_PREFIX "non-interactive"\r
 580 \r
 581 /** @brief The application doesn't want any providers to save passwords\r
 582  * to disk. Property value is irrelevant; only property's existence\r
 583  * matters. */\r
 584 #define SVN_AUTH_PARAM_DONT_STORE_PASSWORDS  SVN_AUTH_PARAM_PREFIX \\r
 585                                                  "dont-store-passwords"\r
 586 \r
 587 /** @brief Indicates whether providers may save passwords to disk in\r
 588  * plaintext. Property value can be either SVN_CONFIG_TRUE,\r
 589  * SVN_CONFIG_FALSE, or SVN_CONFIG_ASK. */\r
 590 #define SVN_AUTH_PARAM_STORE_PLAINTEXT_PASSWORDS  SVN_AUTH_PARAM_PREFIX \\r
 591                                                   "store-plaintext-passwords"\r
 592 \r
 593 /** @brief The application doesn't want any providers to save passphrase\r
 594  * to disk. Property value is irrelevant; only property's existence\r
 595  * matters. */\r
 596 #define SVN_AUTH_PARAM_DONT_STORE_SSL_CLIENT_CERT_PP \\r
 597   SVN_AUTH_PARAM_PREFIX "dont-store-ssl-client-cert-pp"\r
 598 \r
 599 /** @brief Indicates whether providers may save passphrase to disk in\r
 600  * plaintext. Property value can be either SVN_CONFIG_TRUE,\r
 601  * SVN_CONFIG_FALSE, or SVN_CONFIG_ASK. */\r
 602 #define SVN_AUTH_PARAM_STORE_SSL_CLIENT_CERT_PP_PLAINTEXT \\r
 603   SVN_AUTH_PARAM_PREFIX "store-ssl-client-cert-pp-plaintext"\r
 604 \r
 605 /** @brief The application doesn't want any providers to save credentials\r
 606  * to disk. Property value is irrelevant; only property's existence\r
 607  * matters. */\r
 608 #define SVN_AUTH_PARAM_NO_AUTH_CACHE  SVN_AUTH_PARAM_PREFIX "no-auth-cache"\r
 609 \r
 610 /** @brief The following property is for SSL server cert providers. This\r
 611  * provides a pointer to an @c apr_uint32_t containing the failures\r
 612  * detected by the certificate validator. */\r
 613 #define SVN_AUTH_PARAM_SSL_SERVER_FAILURES SVN_AUTH_PARAM_PREFIX \\r
 614   "ssl:failures"\r
 615 \r
 616 /** @brief The following property is for SSL server cert providers. This\r
 617  * provides the cert info (svn_auth_ssl_server_cert_info_t). */\r
 618 #define SVN_AUTH_PARAM_SSL_SERVER_CERT_INFO SVN_AUTH_PARAM_PREFIX \\r
 619   "ssl:cert-info"\r
 620 \r
 621 /** Some providers need access to the @c svn_config_t configuration. */\r
 622 #define SVN_AUTH_PARAM_CONFIG_CATEGORY_CONFIG SVN_AUTH_PARAM_PREFIX "config-category-config"\r
 623 #define SVN_AUTH_PARAM_CONFIG_CATEGORY_SERVERS SVN_AUTH_PARAM_PREFIX "config-category-servers"\r
 624 \r
 625 /** @deprecated Provided for backward compatibility with the 1.5 API. */\r
 626 #define SVN_AUTH_PARAM_CONFIG SVN_AUTH_PARAM_CONFIG_CATEGORY_SERVERS\r
 627 \r
 628 /** The current server group. */\r
 629 #define SVN_AUTH_PARAM_SERVER_GROUP SVN_AUTH_PARAM_PREFIX "server-group"\r
 630 \r
 631 /** @brief A configuration directory that overrides the default\r
 632  * ~/.subversion. */\r
 633 #define SVN_AUTH_PARAM_CONFIG_DIR SVN_AUTH_PARAM_PREFIX "config-dir"\r
 634 \r
 635 /** Get an initial set of credentials.\r
 636  *\r
 637  * Ask @a auth_baton to set @a *credentials to a set of credentials\r
 638  * defined by @a cred_kind and valid within @a realmstring, or NULL if\r
 639  * no credentials are available.  Otherwise, return an iteration state\r
 640  * in @a *state, so that the caller can call\r
 641  * svn_auth_next_credentials(), in case the first set of credentials\r
 642  * fails to authenticate.\r
 643  *\r
 644  * Use @a pool to allocate @a *state, and for temporary allocation.\r
 645  * Note that @a *credentials will be allocated in @a auth_baton's pool.\r
 646  */\r
 647 svn_error_t *\r
 648 svn_auth_first_credentials(void **credentials,\r
 649                            svn_auth_iterstate_t **state,\r
 650                            const char *cred_kind,\r
 651                            const char *realmstring,\r
 652                            svn_auth_baton_t *auth_baton,\r
 653                            apr_pool_t *pool);\r
 654 \r
 655 /** Get another set of credentials, assuming previous ones failed to\r
 656  * authenticate.\r
 657  *\r
 658  * Use @a state to fetch a different set of @a *credentials, as a\r
 659  * follow-up to svn_auth_first_credentials() or\r
 660  * svn_auth_next_credentials().  If no more credentials are available,\r
 661  * set @a *credentials to NULL.\r
 662  *\r
 663  * Note that @a *credentials will be allocated in @c auth_baton's pool.\r
 664  */\r
 665 svn_error_t *\r
 666 svn_auth_next_credentials(void **credentials,\r
 667                           svn_auth_iterstate_t *state,\r
 668                           apr_pool_t *pool);\r
 669 \r
 670 /** Save a set of credentials.\r
 671  *\r
 672  * Ask @a state to store the most recently returned credentials,\r
 673  * presumably because they successfully authenticated.\r
 674  * All allocations should be done in @a pool.\r
 675  *\r
 676  * If no credentials were ever returned, do nothing.\r
 677  */\r
 678 svn_error_t *\r
 679 svn_auth_save_credentials(svn_auth_iterstate_t *state,\r
 680                           apr_pool_t *pool);\r
 681 \r
 682 /** @} */\r
 683 \r
 684 /** Set @a *provider to an authentication provider of type\r
 685  * svn_auth_cred_simple_t that gets information by prompting the user\r
 686  * with @a prompt_func and @a prompt_baton.  Allocate @a *provider in\r
 687  * @a pool.\r
 688  *\r
 689  * If both @c SVN_AUTH_PARAM_DEFAULT_USERNAME and\r
 690  * @c SVN_AUTH_PARAM_DEFAULT_PASSWORD are defined as runtime\r
 691  * parameters in the @c auth_baton, then @a *provider will return the\r
 692  * default arguments when svn_auth_first_credentials() is called.  If\r
 693  * svn_auth_first_credentials() fails, then @a *provider will\r
 694  * re-prompt @a retry_limit times (via svn_auth_next_credentials()).\r
 695  * For infinite retries, set @a retry_limit to value less than 0.\r
 696  *\r
 697  * @since New in 1.4.\r
 698  */\r
 699 void\r
 700 svn_auth_get_simple_prompt_provider(svn_auth_provider_object_t **provider,\r
 701                                     svn_auth_simple_prompt_func_t prompt_func,\r
 702                                     void *prompt_baton,\r
 703                                     int retry_limit,\r
 704                                     apr_pool_t *pool);\r
 705 \r
 706 \r
 707 /** Set @a *provider to an authentication provider of type @c\r
 708  * svn_auth_cred_username_t that gets information by prompting the\r
 709  * user with @a prompt_func and @a prompt_baton.  Allocate @a *provider\r
 710  * in @a pool.\r
 711  *\r
 712  * If @c SVN_AUTH_PARAM_DEFAULT_USERNAME is defined as a runtime\r
 713  * parameter in the @c auth_baton, then @a *provider will return the\r
 714  * default argument when svn_auth_first_credentials() is called.  If\r
 715  * svn_auth_first_credentials() fails, then @a *provider will\r
 716  * re-prompt @a retry_limit times (via svn_auth_next_credentials()).\r
 717  * For infinite retries, set @a retry_limit to value less than 0.\r
 718  *\r
 719  * @since New in 1.4.\r
 720  */\r
 721 void\r
 722 svn_auth_get_username_prompt_provider\r
 723   (svn_auth_provider_object_t **provider,\r
 724    svn_auth_username_prompt_func_t prompt_func,\r
 725    void *prompt_baton,\r
 726    int retry_limit,\r
 727    apr_pool_t *pool);\r
 728 \r
 729 \r
 730 /** Set @a *provider to an authentication provider of type @c\r
 731  * svn_auth_cred_simple_t that gets/sets information from the user's\r
 732  * ~/.subversion configuration directory.\r
 733  *\r
 734  * If the provider is going to save the password unencrypted, it calls @a\r
 735  * plaintext_prompt_func, passing @a prompt_baton, before saving the\r
 736  * password.\r
 737  *\r
 738  * If @a plaintext_prompt_func is NULL it is not called and the answer is\r
 739  * assumed to be TRUE. This matches the deprecated behaviour of storing\r
 740  * unencrypted passwords by default, and is only done this way for backward\r
 741  * compatibility reasons.\r
 742  * Client developers are highly encouraged to provide this callback\r
 743  * to ensure their users are made aware of the fact that their password\r
 744  * is going to be stored unencrypted. In the future, providers may\r
 745  * default to not storing the password unencrypted if this callback is NULL.\r
 746  *\r
 747  * Clients can however set the callback to NULL and set\r
 748  * SVN_AUTH_PARAM_STORE_PLAINTEXT_PASSWORDS to SVN_CONFIG_FALSE or\r
 749  * SVN_CONFIG_TRUE to enforce a certain behaviour.\r
 750  *\r
 751  * Allocate @a *provider in @a pool.\r
 752  *\r
 753  * If a default username or password is available, @a *provider will\r
 754  * honor them as well, and return them when\r
 755  * svn_auth_first_credentials() is called.  (see @c\r
 756  * SVN_AUTH_PARAM_DEFAULT_USERNAME and @c\r
 757  * SVN_AUTH_PARAM_DEFAULT_PASSWORD).\r
 758  *\r
 759  * @since New in 1.6.\r
 760  */\r
 761 void\r
 762 svn_auth_get_simple_provider2\r
 763   (svn_auth_provider_object_t **provider,\r
 764    svn_auth_plaintext_prompt_func_t plaintext_prompt_func,\r
 765    void *prompt_baton,\r
 766    apr_pool_t *pool);\r
 767 \r
 768 /** Like svn_auth_get_simple_provider2, but without the ability to\r
 769  * call the svn_auth_plaintext_prompt_func_t callback, and the provider\r
 770  * always assumes that it is allowed to store the password in plaintext.\r
 771  *\r
 772  * @deprecated Provided for backwards compatibility with the 1.5 API.\r
 773  * @since New in 1.4.\r
 774  */\r
 775 SVN_DEPRECATED\r
 776 void\r
 777 svn_auth_get_simple_provider(svn_auth_provider_object_t **provider,\r
 778                              apr_pool_t *pool);\r
 779 \r
 780 /** Set @a *provider to an authentication provider of type @c\r
 781  * svn_auth_provider_object_t, or return @a NULL if the provider is not\r
 782  * available for the requested platform or the requested provider is unknown.\r
 783  *\r
 784  * Valid @a provider_name values are: "gnome_keyring", "keychain", "kwallet"\r
 785  * and "windows".\r
 786  *\r
 787  * Valid @a provider_type values are: "simple", "ssl_client_cert_pw" and\r
 788  * "ssl_server_trust".\r
 789  *\r
 790  * Allocate @a *provider in @a pool.\r
 791  *\r
 792  * What actually happens is we invoke the appropriate provider function to\r
 793  * supply the @a provider, like so:\r
 794  *\r
 795  *    svn_auth_get_<name>_<type>_provider(@a provider, @a pool);\r
 796  *\r
 797  * @since New in 1.6.\r
 798  */\r
 799 svn_error_t *\r
 800 svn_auth_get_platform_specific_provider\r
 801   (svn_auth_provider_object_t **provider,\r
 802    const char *provider_name,\r
 803    const char *provider_type,\r
 804    apr_pool_t *pool);\r
 805 \r
 806 /** Set @a *providers to an array of <tt>svn_auth_provider_object_t *</tt>\r
 807  * objects.\r
 808  * Only client authentication providers available for the current platform are\r
 809  * returned. Order of the platform-specific authentication providers is\r
 810  * determined by the 'password-stores' configuration option which is retrieved\r
 811  * from @a config. @a config can be NULL.\r
 812  *\r
 813  * Create and allocate @a *providers in @a pool.\r
 814  *\r
 815  * Default order of the platform-specific authentication providers:\r
 816  *   1. gnome-keyring\r
 817  *   2. kwallet\r
 818  *   3. keychain\r
 819  *   4. windows-cryptoapi\r
 820  *\r
 821  * @since New in 1.6.\r
 822  */\r
 823 svn_error_t *\r
 824 svn_auth_get_platform_specific_client_providers\r
 825   (apr_array_header_t **providers,\r
 826    svn_config_t *config,\r
 827    apr_pool_t *pool);\r
 828 \r
 829 #if (defined(WIN32) && !defined(__MINGW32__)) || defined(DOXYGEN)\r
 830 /**\r
 831  * Set @a *provider to an authentication provider of type @c\r
 832  * svn_auth_cred_simple_t that gets/sets information from the user's\r
 833  * ~/.subversion configuration directory.  Allocate @a *provider in\r
 834  * @a pool.\r
 835  *\r
 836  * This is like svn_auth_get_simple_provider(), except that, when\r
 837  * running on Window 2000 or newer (or any other Windows version that\r
 838  * includes the CryptoAPI), the provider encrypts the password before\r
 839  * storing it to disk. On earlier versions of Windows, the provider\r
 840  * does nothing.\r
 841  *\r
 842  * @since New in 1.4.\r
 843  * @note This function is only available on Windows.\r
 844  *\r
 845  * @note An administrative password reset may invalidate the account's\r
 846  * secret key. This function will detect that situation and behave as\r
 847  * if the password were not cached at all.\r
 848  */\r
 849 void\r
 850 svn_auth_get_windows_simple_provider(svn_auth_provider_object_t **provider,\r
 851                                      apr_pool_t *pool);\r
 852 \r
 853 /**\r
 854  * Set @a *provider to an authentication provider of type @c\r
 855  * svn_auth_cred_ssl_client_cert_pw_t that gets/sets information from the\r
 856  * user's ~/.subversion configuration directory.  Allocate @a *provider in\r
 857  * @a pool.\r
 858  *\r
 859  * This is like svn_auth_get_ssl_client_cert_pw_file_provider(), except that\r
 860  * when running on Window 2000 or newer, the provider encrypts the password\r
 861  * before storing it to disk. On earlier versions of Windows, the provider\r
 862  * does nothing.\r
 863  *\r
 864  * @since New in 1.6\r
 865  * @note This function is only available on Windows.\r
 866  *\r
 867  * @note An administrative password reset may invalidate the account's\r
 868  * secret key. This function will detect that situation and behave as\r
 869  * if the password were not cached at all.\r
 870  */\r
 871 void\r
 872 svn_auth_get_windows_ssl_client_cert_pw_provider\r
 873   (svn_auth_provider_object_t **provider,\r
 874    apr_pool_t *pool);\r
 875 \r
 876 /**\r
 877  * Set @a *provider to an authentication provider of type @c\r
 878  * svn_auth_cred_ssl_server_trust_t, allocated in @a pool.\r
 879  *\r
 880  * This provider automatically validates ssl server certificates with\r
 881  * the CryptoApi, like Internet Explorer and the Windows network API do.\r
 882  * This allows the rollout of root certificates via Windows Domain\r
 883  * policies, instead of Subversion specific configuration.\r
 884  *\r
 885  * @since New in 1.5.\r
 886  * @note This function is only available on Windows.\r
 887  */\r
 888 void\r
 889 svn_auth_get_windows_ssl_server_trust_provider\r
 890   (svn_auth_provider_object_t **provider,\r
 891    apr_pool_t *pool);\r
 892 \r
 893 #endif /* WIN32 && !__MINGW32__ || DOXYGEN */\r
 894 \r
 895 #if defined(DARWIN) || defined(DOXYGEN)\r
 896 /**\r
 897  * Set @a *provider to an authentication provider of type @c\r
 898  * svn_auth_cred_simple_t that gets/sets information from the user's\r
 899  * ~/.subversion configuration directory.  Allocate @a *provider in\r
 900  * @a pool.\r
 901  *\r
 902  * This is like svn_auth_get_simple_provider(), except that the\r
 903  * password is stored in the Mac OS KeyChain.\r
 904  *\r
 905  * @since New in 1.4\r
 906  * @note This function is only available on Mac OS 10.2 and higher.\r
 907  */\r
 908 void\r
 909 svn_auth_get_keychain_simple_provider(svn_auth_provider_object_t **provider,\r
 910                                       apr_pool_t *pool);\r
 911 \r
 912 /**\r
 913  * Set @a *provider to an authentication provider of type @c\r
 914  * svn_auth_cred_ssl_client_cert_pw_t that gets/sets information from the\r
 915  * user's ~/.subversion configuration directory.  Allocate @a *provider in\r
 916  * @a pool.\r
 917  *\r
 918  * This is like svn_auth_get_ssl_client_cert_pw_file_provider(), except\r
 919  * that the password is stored in the Mac OS KeyChain.\r
 920  *\r
 921  * @since New in 1.6\r
 922  * @note This function is only available on Mac OS 10.2 and higher.\r
 923  */\r
 924 void\r
 925 svn_auth_get_keychain_ssl_client_cert_pw_provider\r
 926   (svn_auth_provider_object_t **provider,\r
 927    apr_pool_t *pool);\r
 928 #endif /* DARWIN || DOXYGEN */\r
 929 \r
 930 #if (!defined(DARWIN) && !defined(WIN32)) || defined(DOXYGEN)\r
 931 /** A type of callback function for obtaining the GNOME Keyring password.\r
 932  *\r
 933  * In this callback, the client should ask the user for default keyring\r
 934  * @a keyring_name password.\r
 935  *\r
 936  * The answer is returned in @a *keyring_password.\r
 937  * @a baton is an implementation-specific closure.\r
 938  * All allocations should be done in @a pool.\r
 939  *\r
 940  * @since New in 1.6\r
 941  */\r
 942 typedef svn_error_t *(*svn_auth_gnome_keyring_unlock_prompt_func_t)\r
 943   (char **keyring_password,\r
 944    const char *keyring_name,\r
 945    void *baton,\r
 946    apr_pool_t *pool);\r
 947 \r
 948 \r
 949 /** libsvn_auth_gnome_keyring-specific run-time parameters. */\r
 950 \r
 951 /** @brief The pointer to function which prompts user for GNOME Keyring\r
 952  * password.\r
 953  * The type of this pointer should be svn_auth_gnome_keyring_unlock_prompt_func_t. */\r
 954 #define SVN_AUTH_PARAM_GNOME_KEYRING_UNLOCK_PROMPT_FUNC "gnome-keyring-unlock-prompt-func"\r
 955 \r
 956 /** @brief The baton which is passed to\r
 957  * @c *SVN_AUTH_PARAM_GNOME_KEYRING_UNLOCK_PROMPT_FUNC. */\r
 958 #define SVN_AUTH_PARAM_GNOME_KEYRING_UNLOCK_PROMPT_BATON "gnome-keyring-unlock-prompt-baton"\r
 959 \r
 960 \r
 961 /**\r
 962  * Get libsvn_auth_gnome_keyring version information.\r
 963  *\r
 964  * @since New in 1.6\r
 965  */\r
 966 const svn_version_t *\r
 967 svn_auth_gnome_keyring_version(void);\r
 968 \r
 969 \r
 970 /**\r
 971  * Set @a *provider to an authentication provider of type @c\r
 972  * svn_auth_cred_simple_t that gets/sets information from the user's\r
 973  * ~/.subversion configuration directory.\r
 974  *\r
 975  * This is like svn_client_get_simple_provider(), except that the\r
 976  * password is stored in GNOME Keyring.\r
 977  *\r
 978  * If the GNOME Keyring is locked the provider calls\r
 979  * @c *SVN_AUTH_PARAM_GNOME_KEYRING_UNLOCK_PROMPT_FUNC in order to unlock\r
 980  * the keyring.\r
 981  *\r
 982  * @c SVN_AUTH_PARAM_GNOME_KEYRING_UNLOCK_PROMPT_BATON is passed to\r
 983  * @c *SVN_AUTH_PARAM_GNOME_KEYRING_UNLOCK_PROMPT_FUNC.\r
 984  *\r
 985  * Allocate @a *provider in @a pool.\r
 986  *\r
 987  * @since New in 1.6\r
 988  * @note This function actually works only on systems with\r
 989  * libsvn_auth_gnome_keyring and GNOME Keyring installed.\r
 990  */\r
 991 void\r
 992 svn_auth_get_gnome_keyring_simple_provider\r
 993     (svn_auth_provider_object_t **provider,\r
 994      apr_pool_t *pool);\r
 995 \r
 996 \r
 997 /**\r
 998  * Set @a *provider to an authentication provider of type @c\r
 999  * svn_auth_cred_ssl_client_cert_pw_t that gets/sets information from the\r
1000  * user's ~/.subversion configuration directory.\r
1001  *\r
1002  * This is like svn_client_get_ssl_client_cert_pw_file_provider(), except\r
1003  * that the password is stored in GNOME Keyring.\r
1004  *\r
1005  * If the GNOME Keyring is locked the provider calls\r
1006  * @c *SVN_AUTH_PARAM_GNOME_KEYRING_UNLOCK_PROMPT_FUNC in order to unlock\r
1007  * the keyring.\r
1008  *\r
1009  * @c SVN_AUTH_PARAM_GNOME_KEYRING_UNLOCK_PROMPT_BATON is passed to\r
1010  * @c *SVN_AUTH_PARAM_GNOME_KEYRING_UNLOCK_PROMPT_FUNC.\r
1011  *\r
1012  * Allocate @a *provider in @a pool.\r
1013  *\r
1014  * @since New in 1.6\r
1015  * @note This function actually works only on systems with\r
1016  * libsvn_auth_gnome_keyring and GNOME Keyring installed.\r
1017  */\r
1018 void\r
1019 svn_auth_get_gnome_keyring_ssl_client_cert_pw_provider\r
1020   (svn_auth_provider_object_t **provider,\r
1021    apr_pool_t *pool);\r
1022 \r
1023 \r
1024 /**\r
1025  * Get libsvn_auth_kwallet version information.\r
1026  *\r
1027  * @since New in 1.6\r
1028  */\r
1029 const svn_version_t *\r
1030 svn_auth_kwallet_version(void);\r
1031 \r
1032 \r
1033 /**\r
1034  * Set @a *provider to an authentication provider of type @c\r
1035  * svn_auth_cred_simple_t that gets/sets information from the user's\r
1036  * ~/.subversion configuration directory.  Allocate @a *provider in\r
1037  * @a pool.\r
1038  *\r
1039  * This is like svn_client_get_simple_provider(), except that the\r
1040  * password is stored in KWallet.\r
1041  *\r
1042  * @since New in 1.6\r
1043  * @note This function actually works only on systems with libsvn_auth_kwallet\r
1044  * and KWallet installed.\r
1045  */\r
1046 void\r
1047 svn_auth_get_kwallet_simple_provider(svn_auth_provider_object_t **provider,\r
1048                                      apr_pool_t *pool);\r
1049 \r
1050 \r
1051 /**\r
1052  * Set @a *provider to an authentication provider of type @c\r
1053  * svn_auth_cred_ssl_client_cert_pw_t that gets/sets information from the\r
1054  * user's ~/.subversion configuration directory.  Allocate @a *provider in\r
1055  * @a pool.\r
1056  *\r
1057  * This is like svn_client_get_ssl_client_cert_pw_file_provider(), except\r
1058  * that the password is stored in KWallet.\r
1059  *\r
1060  * @since New in 1.6\r
1061  * @note This function actually works only on systems with libsvn_auth_kwallet\r
1062  * and KWallet installed.\r
1063  */\r
1064 void\r
1065 svn_auth_get_kwallet_ssl_client_cert_pw_provider\r
1066   (svn_auth_provider_object_t **provider,\r
1067    apr_pool_t *pool);\r
1068 #endif /* (!DARWIN && !WIN32) || DOXYGEN */\r
1069 \r
1070 \r
1071 /** Set @a *provider to an authentication provider of type @c\r
1072  * svn_auth_cred_username_t that gets/sets information from a user's\r
1073  * ~/.subversion configuration directory.  Allocate @a *provider in\r
1074  * @a pool.\r
1075  *\r
1076  * If a default username is available, @a *provider will honor it,\r
1077  * and return it when svn_auth_first_credentials() is called.  (See\r
1078  * @c SVN_AUTH_PARAM_DEFAULT_USERNAME.)\r
1079  *\r
1080  * @since New in 1.4.\r
1081  */\r
1082 void\r
1083 svn_auth_get_username_provider(svn_auth_provider_object_t **provider,\r
1084                                apr_pool_t *pool);\r
1085 \r
1086 \r
1087 /** Set @a *provider to an authentication provider of type @c\r
1088  * svn_auth_cred_ssl_server_trust_t, allocated in @a pool.\r
1089  *\r
1090  * @a *provider retrieves its credentials from the configuration\r
1091  * mechanism.  The returned credential is used to override SSL\r
1092  * security on an error.\r
1093  *\r
1094  * @since New in 1.4.\r
1095  */\r
1096 void\r
1097 svn_auth_get_ssl_server_trust_file_provider\r
1098   (svn_auth_provider_object_t **provider,\r
1099    apr_pool_t *pool);\r
1100 \r
1101 /** Set @a *provider to an authentication provider of type @c\r
1102  * svn_auth_cred_ssl_client_cert_t, allocated in @a pool.\r
1103  *\r
1104  * @a *provider retrieves its credentials from the configuration\r
1105  * mechanism.  The returned credential is used to load the appropriate\r
1106  * client certificate for authentication when requested by a server.\r
1107  *\r
1108  * @since New in 1.4.\r
1109  */\r
1110 void\r
1111 svn_auth_get_ssl_client_cert_file_provider\r
1112   (svn_auth_provider_object_t **provider,\r
1113    apr_pool_t *pool);\r
1114 \r
1115 \r
1116 /** Set @a *provider to an authentication provider of type @c\r
1117  * svn_auth_cred_ssl_client_cert_pw_t that gets/sets information from the user's\r
1118  * ~/.subversion configuration directory.\r
1119  *\r
1120  * If the provider is going to save the passphrase unencrypted,\r
1121  * it calls @a plaintext_passphrase_prompt_func, passing @a\r
1122  * prompt_baton, before saving the passphrase.\r
1123  *\r
1124  * If @a plaintext_passphrase_prompt_func is NULL it is not called\r
1125  * and the passphrase is not stored in plaintext.\r
1126  * Client developers are highly encouraged to provide this callback\r
1127  * to ensure their users are made aware of the fact that their passphrase\r
1128  * is going to be stored unencrypted.\r
1129  *\r
1130  * Clients can however set the callback to NULL and set\r
1131  * SVN_AUTH_PARAM_STORE_SSL_CLIENT_CERT_PP_PLAINTEXT to SVN_CONFIG_FALSE or\r
1132  * SVN_CONFIG_TRUE to enforce a certain behaviour.\r
1133  *\r
1134  * Allocate @a *provider in @a pool.\r
1135  *\r
1136  * @since New in 1.6.\r
1137  */\r
1138 void\r
1139 svn_auth_get_ssl_client_cert_pw_file_provider2\r
1140   (svn_auth_provider_object_t **provider,\r
1141    svn_auth_plaintext_passphrase_prompt_func_t plaintext_passphrase_prompt_func,\r
1142    void *prompt_baton,\r
1143    apr_pool_t *pool);\r
1144 \r
1145 /** Like svn_auth_get_ssl_client_cert_pw_file_provider2, but without\r
1146  * the ability to call the svn_auth_plaintext_passphrase_prompt_func_t\r
1147  * callback, and the provider always assumes that it is not allowed\r
1148  * to store the passphrase in plaintext.\r
1149  *\r
1150  * @deprecated Provided for backwards compatibility with the 1.5 API.\r
1151  * @since New in 1.4.\r
1152  */\r
1153 SVN_DEPRECATED\r
1154 void\r
1155 svn_auth_get_ssl_client_cert_pw_file_provider\r
1156   (svn_auth_provider_object_t **provider,\r
1157    apr_pool_t *pool);\r
1158 \r
1159 \r
1160 /** Set @a *provider to an authentication provider of type @c\r
1161  * svn_auth_cred_ssl_server_trust_t, allocated in @a pool.\r
1162  *\r
1163  * @a *provider retrieves its credentials by using the @a prompt_func\r
1164  * and @a prompt_baton.  The returned credential is used to override\r
1165  * SSL security on an error.\r
1166  *\r
1167  * @since New in 1.4.\r
1168  */\r
1169 void\r
1170 svn_auth_get_ssl_server_trust_prompt_provider\r
1171   (svn_auth_provider_object_t **provider,\r
1172    svn_auth_ssl_server_trust_prompt_func_t prompt_func,\r
1173    void *prompt_baton,\r
1174    apr_pool_t *pool);\r
1175 \r
1176 \r
1177 /** Set @a *provider to an authentication provider of type @c\r
1178  * svn_auth_cred_ssl_client_cert_t, allocated in @a pool.\r
1179  *\r
1180  * @a *provider retrieves its credentials by using the @a prompt_func\r
1181  * and @a prompt_baton.  The returned credential is used to load the\r
1182  * appropriate client certificate for authentication when requested by\r
1183  * a server.  The prompt will be retried @a retry_limit times. For\r
1184  * infinite retries, set @a retry_limit to value less than 0.\r
1185  *\r
1186  * @since New in 1.4.\r
1187  */\r
1188 void\r
1189 svn_auth_get_ssl_client_cert_prompt_provider\r
1190   (svn_auth_provider_object_t **provider,\r
1191    svn_auth_ssl_client_cert_prompt_func_t prompt_func,\r
1192    void *prompt_baton,\r
1193    int retry_limit,\r
1194    apr_pool_t *pool);\r
1195 \r
1196 \r
1197 /** Set @a *provider to an authentication provider of type @c\r
1198  * svn_auth_cred_ssl_client_cert_pw_t, allocated in @a pool.\r
1199  *\r
1200  * @a *provider retrieves its credentials by using the @a prompt_func\r
1201  * and @a prompt_baton.  The returned credential is used when a loaded\r
1202  * client certificate is protected by a passphrase.  The prompt will\r
1203  * be retried @a retry_limit times. For infinite retries, set\r
1204  * @a retry_limit to value less than 0.\r
1205  *\r
1206  * @since New in 1.4.\r
1207  */\r
1208 void\r
1209 svn_auth_get_ssl_client_cert_pw_prompt_provider\r
1210   (svn_auth_provider_object_t **provider,\r
1211    svn_auth_ssl_client_cert_pw_prompt_func_t prompt_func,\r
1212    void *prompt_baton,\r
1213    int retry_limit,\r
1214    apr_pool_t *pool);\r
1215 \r
1216 #ifdef __cplusplus\r
1217 }\r
1218 #endif /* __cplusplus */\r
1219 \r
1220 #endif /* SVN_AUTH_H */\r