contrib/subversion/subversion/include/svn_auth.h

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