subversion/include/svn_auth.h

   1 /**
   2  * @copyright
   3  * ====================================================================
   4  * Copyright (c) 2000-2004 CollabNet.  All rights reserved.
   5  *
   6  * This software is licensed as described in the file COPYING, which
   7  * you should have received as part of this distribution.  The terms
   8  * are also available at http://subversion.tigris.org/license-1.html.
   9  * If newer versions of this license are posted there, you may use a
  10  * newer version instead, at your option.
  11  *
  12  * This software consists of voluntary contributions made by many
  13  * individuals.  For exact contribution history, see the revision
  14  * history and logs, available at http://subversion.tigris.org/.
  15  * ====================================================================
  16  * @endcopyright
  17  *
  18  * @file svn_auth.h
  19  * @brief Subversion's authentication system
  20  */
  21
  22 #ifndef SVN_AUTH_H
  23 #define SVN_AUTH_H
  24
  25 #include <apr_pools.h>
  26
  27 #include "svn_types.h"
  28
  29 #ifdef __cplusplus
  30 extern "C" {
  31 #endif /* __cplusplus */
  32
  33 /** Overview of the svn authentication system.
  34  *
  35  * We define an authentication "provider" as a module that is able to
  36  * return a specific set of credentials. (e.g. username/password,
  37  * certificate, etc.)  Each provider implements a vtable that
  38  *
  39  * - can fetch initial credentials
  40  * - can retry the fetch (or try to fetch something different)
  41  * - can store the credentials for future use
  42  *
  43  * For any given type of credentials, there can exist any number of
  44  * separate providers -- each provider has a different method of
  45  * fetching. (i.e. from a disk store, by prompting the user, etc.)
  46  *
  47  * The application begins by creating an auth baton object, and
  48  * "registers" some number of providers with the auth baton, in a
  49  * specific order.  (For example, it may first register a
  50  * username/password provider that looks in disk store, then register
  51  * a username/password provider that prompts the user.)
  52  *
  53  * Later on, when any svn library is challenged, it asks the auth
  54  * baton for the specific credentials.  If the initial credentials
  55  * fail to authenticate, the caller keeps requesting new credentials.
  56  * Under the hood, libsvn_auth effectively "walks" over each provider
  57  * (in order of registry), one at a time, until all the providers have
  58  * exhausted all their retry options.
  59  *
  60  * This system allows an application to flexibly define authentication
  61  * behaviors (by changing registration order), and very easily write
  62  * new authentication providers.
  63  *
  64  * An auth_baton also contains an internal hashtable of run-time
  65  * parameters; any provider or library layer can set these run-time
  66  * parameters at any time, so that the provider has access to the
  67  * data.  (For example, certain run-time data may not be available
  68  * until an authentication challenge is made.)  Each credential type
  69  * must document the run-time parameters that are made available to
  70  * its providers.
  71  *
  72  * @defgroup auth_fns Authentication functions
  73  * @{
  74  */
  75
  76
  77 /** The type of a Subversion authentication object */
  78 typedef struct svn_auth_baton_t svn_auth_baton_t;
  79
  80 /** The type of a Subversion authentication-iteration object */
  81 typedef struct svn_auth_iterstate_t svn_auth_iterstate_t;
  82
  83
  84 /** The main authentication "provider" vtable. */
  85 typedef struct svn_auth_provider_t
  86 {
  87   /** The kind of credentials this provider knows how to retrieve. */
  88   const char *cred_kind;
  89
  90   /** Get an initial set of credentials.
  91    *
  92    * Set @a *credentials to a set of valid credentials within @a
  93    * realmstring, or NULL if no credentials are available.  Set @a
  94    * *iter_baton to context that allows a subsequent call to @c
  95    * next_credentials, in case the first credentials fail to
  96    * authenticate.  @a provider_baton is general context for the
  97    * vtable, @a parameters contains any run-time data that the
  98    * provider may need, and @a realmstring comes from the
  99    * svn_auth_first_credentials() call.
 100    */
 101   svn_error_t * (*first_credentials)(void **credentials,
 102                                      void **iter_baton,
 103                                      void *provider_baton,
 104                                      apr_hash_t *parameters,
 105                                      const char *realmstring,
 106                                      apr_pool_t *pool);
 107
 108   /** Get a different set of credentials.
 109    *
 110    * Set @a *credentials to another set of valid credentials (using @a
 111    * iter_baton as the context from previous call to first_credentials
 112    * or next_credentials).  If no more credentials are available, set
 113    * @a *credentials to NULL.  If the provider only has one set of
 114    * credentials, this function pointer should simply be NULL. @a
 115    * provider_baton is general context for the vtable, @a parameters
 116    * contains any run-time data that the provider may need, and @a
 117    * realmstring comes from the svn_auth_first_credentials() call.
 118    */
 119   svn_error_t * (*next_credentials)(void **credentials,
 120                                     void *iter_baton,
 121                                     void *provider_baton,
 122                                     apr_hash_t *parameters,
 123                                     const char *realmstring,
 124                                     apr_pool_t *pool);
 125
 126   /** Save credentials.
 127    *
 128    * Store @a credentials for future use.  @a provider_baton is
 129    * general context for the vtable, and @a parameters contains any
 130    * run-time data the provider may need.  Set @a *saved to TRUE if
 131    * the save happened, or FALSE if not.  The provider is not required
 132    * to save; if it refuses or is unable to save for non-fatal
 133    * reasons, return FALSE.  If the provider never saves data, then
 134    * this function pointer should simply be NULL. @a realmstring comes
 135    * from the svn_auth_first_credentials() call.
 136    */
 137   svn_error_t * (*save_credentials)(svn_boolean_t *saved,
 138                                     void *credentials,
 139                                     void *provider_baton,
 140                                     apr_hash_t *parameters,
 141                                     const char *realmstring,
 142                                     apr_pool_t *pool);
 143
 144 } svn_auth_provider_t;
 145
 146
 147 /** A provider object, ready to be put into an array and given to
 148     svn_auth_open(). */
 149 typedef struct svn_auth_provider_object_t
 150 {
 151   const svn_auth_provider_t *vtable;
 152   void *provider_baton;
 153
 154 } svn_auth_provider_object_t;
 155
 156
 157 \f
 158 /** Specific types of credentials **/
 159
 160 /** Simple username/password pair credential kind.
 161  *
 162  * The following auth parameters may be available to the providers:
 163  *
 164  * - @c SVN_AUTH_PARAM_NO_AUTH_CACHE (@c void*)
 165  * - @c SVN_AUTH_PARAM_DEFAULT_USERNAME (@c char*)
 166  * - @c SVN_AUTH_PARAM_DEFAULT_PASSWORD (@c char*)
 167  */
 168 #define SVN_AUTH_CRED_SIMPLE "svn.simple"
 169
 170 /** @c SVN_AUTH_CRED_SIMPLE credentials. */
 171 typedef struct svn_auth_cred_simple_t
 172 {
 173   /** Username */
 174   const char *username;
 175   /** Password */
 176   const char *password;
 177   /** Indicates if the credentials may be saved (to disk). For example, a
 178    * GUI prompt implementation with a remember password checkbox shall set
 179    * @a may_save to TRUE if the checkbox is checked.
 180    */
 181   svn_boolean_t may_save;
 182 } svn_auth_cred_simple_t;
 183
 184
 185 /** Username credential kind.
 186  *
 187  * The following optional auth parameters are relevant to the providers:
 188  *
 189  * - @c SVN_AUTH_PARAM_NO_AUTH_CACHE (@c void*)
 190  * - @c SVN_AUTH_PARAM_DEFAULT_USERNAME (@c char*)
 191  */
 192 #define SVN_AUTH_CRED_USERNAME "svn.username"
 193
 194 /** @c SVN_AUTH_CRED_USERNAME credentials. */
 195 typedef struct svn_auth_cred_username_t
 196 {
 197   /** Username */
 198   const char *username;
 199   /** Indicates if the credentials may be saved (to disk). For example, a
 200    * GUI prompt implementation with a remember username checkbox shall set
 201    * @a may_save to TRUE if the checkbox is checked.
 202    */
 203   svn_boolean_t may_save;
 204 } svn_auth_cred_username_t;
 205
 206
 207 /** SSL client certificate credential type.
 208  *
 209  * The following auth parameters are available to the providers:
 210  *
 211  * - @c SVN_AUTH_PARAM_CONFIG (@c svn_config_t*)
 212  * - @c SVN_AUTH_PARAM_SERVER_GROUP (@c char*)
 213  *
 214  * The following optional auth parameters are relevant to the providers:
 215  *
 216  * - @c SVN_AUTH_PARAM_NO_AUTH_CACHE (@c void*)
 217  */
 218 #define SVN_AUTH_CRED_SSL_CLIENT_CERT "svn.ssl.client-cert"
 219
 220 /** @c SVN_AUTH_CRED_SSL_CLIENT_CERT credentials. */
 221 typedef struct svn_auth_cred_ssl_client_cert_t
 222 {
 223   /** Full paths to the certificate file */
 224   const char *cert_file;
 225   /** Indicates if the credentials may be saved (to disk). For example, a
 226    * GUI prompt implementation with a remember certificate checkbox shall
 227    * set @a may_save to TRUE if the checkbox is checked.
 228    */
 229   svn_boolean_t may_save;
 230 } svn_auth_cred_ssl_client_cert_t;
 231
 232
 233 /** SSL client certificate passphrase credential type.
 234  *
 235  * @note The realmstring used with this credential type must be a name that
 236  * makes it possible for the user to identify the certificate.
 237  *
 238  * The following auth parameters are available to the providers:
 239  *
 240  * - @c SVN_AUTH_PARAM_CONFIG (@c svn_config_t*)
 241  * - @c SVN_AUTH_PARAM_SERVER_GROUP (@c char*)
 242  *
 243  * The following optional auth parameters are relevant to the providers:
 244  *
 245  * - @c SVN_AUTH_PARAM_NO_AUTH_CACHE (@c void*)
 246  */
 247 #define SVN_AUTH_CRED_SSL_CLIENT_CERT_PW "svn.ssl.client-passphrase"
 248
 249 /** @c SVN_AUTH_CRED_SSL_CLIENT_CERT_PW credentials. */
 250 typedef struct svn_auth_cred_ssl_client_cert_pw_t
 251 {
 252   /** Certificate password */
 253   const char *password;
 254   /** Indicates if the credentials may be saved (to disk). For example, a
 255    * GUI prompt implementation with a remember password checkbox shall set
 256    * @a may_save to TRUE if the checkbox is checked.
 257    */
 258   svn_boolean_t may_save;
 259 } svn_auth_cred_ssl_client_cert_pw_t;
 260
 261
 262 /** SSL server verification credential type.
 263  *
 264  * The following auth parameters are available to the providers:
 265  *
 266  * - @c SVN_AUTH_PARAM_CONFIG (@c svn_config_t*)
 267  * - @c SVN_AUTH_PARAM_SERVER_GROUP (@c char*)
 268  * - @c SVN_AUTH_PARAM_SSL_SERVER_FAILURES (@c apr_uint32_t*)
 269  * - @c SVN_AUTH_PARAM_SSL_SERVER_CERT_INFO
 270  *      (@c svn_auth_ssl_server_cert_info_t*)
 271  *
 272  * The following optional auth parameters are relevant to the providers:
 273  *
 274  * - @c SVN_AUTH_PARAM_NO_AUTH_CACHE (@c void*)
 275  */
 276 #define SVN_AUTH_CRED_SSL_SERVER_TRUST "svn.ssl.server"
 277
 278 /** SSL server certificate information used by @c
 279  * SVN_AUTH_CRED_SSL_SERVER_TRUST providers.
 280  */
 281 typedef struct svn_auth_ssl_server_cert_info_t
 282 {
 283   /** Primary CN */
 284   const char *hostname;
 285   /** ASCII fingerprint */
 286   const char *fingerprint;
 287   /** ASCII date from which the certificate is valid */
 288   const char *valid_from;
 289   /** ASCII date until which the certificate is valid */
 290   const char *valid_until;
 291   /** DN of the certificate issuer */
 292   const char *issuer_dname;
 293   /** Base-64 encoded DER certificate representation */
 294   const char *ascii_cert;
 295 } svn_auth_ssl_server_cert_info_t;
 296
 297 /**
 298  * Return a deep copy of @a info, allocated in @a pool.
 299  *
 300  * @since New in 1.3.
 301  */
 302 svn_auth_ssl_server_cert_info_t *
 303 svn_auth_ssl_server_cert_info_dup(const svn_auth_ssl_server_cert_info_t *info,
 304                                   apr_pool_t *pool);
 305
 306 /** @c SVN_AUTH_CRED_SSL_SERVER_TRUST credentials. */
 307 typedef struct svn_auth_cred_ssl_server_trust_t
 308 {
 309   /** Indicates if the credentials may be saved (to disk). For example, a
 310    * GUI prompt implementation with a checkbox to accept the certificate
 311    * permanently shall set @a may_save to TRUE if the checkbox is checked.
 312    */
 313   svn_boolean_t may_save;
 314   /** Bit mask of the accepted failures */
 315   apr_uint32_t accepted_failures;
 316 } svn_auth_cred_ssl_server_trust_t;
 317
 318
 319 \f
 320 /** Credential-constructing prompt functions. **/
 321
 322 /** These exist so that different client applications can use
 323  * different prompt mechanisms to supply the same credentials.  For
 324  * example, if authentication requires a username and password, a
 325  * command-line client's prompting function might prompt first for the
 326  * username and then for the password, whereas a GUI client's would
 327  * present a single dialog box asking for both, and a telepathic
 328  * client's would read all the information directly from the user's
 329  * mind.  All these prompting functions return the same type of
 330  * credential, but the information used to construct the credential is
 331  * gathered in an interface-specific way in each case.
 332  */
 333
 334 /** Set @a *cred by prompting the user, allocating @a *cred in @a pool.
 335  * @a baton is an implementation-specific closure.
 336  *
 337  * If @a realm is non-NULL, maybe use it in the prompt string.
 338  *
 339  * If @a username is non-NULL, then the user might be prompted only
 340  * for a password, but @a *cred would still be filled with both
 341  * username and password.  For example, a typical usage would be to
 342  * pass @a username on the first call, but then leave it NULL for
 343  * subsequent calls, on the theory that if credentials failed, it's
 344  * as likely to be due to incorrect username as incorrect password.
 345  *
 346  * If @a may_save is FALSE, the auth system does not allow the credentials
 347  * to be saved (to disk). A prompt function shall not ask the user if the
 348  * credentials shall be saved if @a may_save is FALSE. For example, a GUI
 349  * client with a remember password checkbox would grey out the checkbox if
 350  * @a may_save is FALSE.
 351  */
 352 typedef svn_error_t *(*svn_auth_simple_prompt_func_t)
 353   (svn_auth_cred_simple_t **cred,
 354    void *baton,
 355    const char *realm,
 356    const char *username,
 357    svn_boolean_t may_save,
 358    apr_pool_t *pool);
 359
 360
 361 /** Set @a *cred by prompting the user, allocating @a *cred in @a pool.
 362  * @a baton is an implementation-specific closure.
 363  *
 364  * If @a realm is non-NULL, maybe use it in the prompt string.
 365  *
 366  * If @a may_save is FALSE, the auth system does not allow the credentials
 367  * to be saved (to disk). A prompt function shall not ask the user if the
 368  * credentials shall be saved if @a may_save is FALSE. For example, a GUI
 369  * client with a remember username checkbox would grey out the checkbox if
 370  * @a may_save is FALSE.
 371  */
 372 typedef svn_error_t *(*svn_auth_username_prompt_func_t)
 373   (svn_auth_cred_username_t **cred,
 374    void *baton,
 375    const char *realm,
 376    svn_boolean_t may_save,
 377    apr_pool_t *pool);
 378
 379
 380 /** @name SSL server certificate failure bits
 381  *
 382  * @note These values are stored in the on disk auth cache by the SSL
 383  * server certificate auth provider, so the meaning of these bits must
 384  * not be changed.
 385  * @{
 386  */
 387 /** Certificate is not yet valid. */
 388 #define SVN_AUTH_SSL_NOTYETVALID 0x00000001
 389 /** Certificate has expired. */
 390 #define SVN_AUTH_SSL_EXPIRED     0x00000002
 391 /** Certificate's CN (hostname) does not match the remote hostname. */
 392 #define SVN_AUTH_SSL_CNMISMATCH  0x00000004
 393 /** @brief Certificate authority is unknown (i.e. not trusted) */
 394 #define SVN_AUTH_SSL_UNKNOWNCA   0x00000008
 395 /** @brief Other failure. This can happen if neon has introduced a new
 396  * failure bit that we do not handle yet. */
 397 #define SVN_AUTH_SSL_OTHER       0x40000000
 398 /** @} */
 399
 400 /** Set @a *cred by prompting the user, allocating @a *cred in @a pool.
 401  * @a baton is an implementation-specific closure.
 402  *
 403  * @a cert_info is a structure describing the server cert that was
 404  * presented to the client, and @a failures is a bitmask that
 405  * describes exactly why the cert could not be automatically validated,
 406  * composed from the constants SVN_AUTH_SSL_* (@c SVN_AUTH_SSL_NOTYETVALID
 407  * etc.).  @a realm is a string that can be used in the prompt string.
 408  *
 409  * If @a may_save is FALSE, the auth system does not allow the credentials
 410  * to be saved (to disk). A prompt function shall not ask the user if the
 411  * credentials shall be saved if @a may_save is FALSE. For example, a GUI
 412  * client with a trust permanently checkbox would grey out the checkbox if
 413  * @a may_save is FALSE.
 414  */
 415 typedef svn_error_t *(*svn_auth_ssl_server_trust_prompt_func_t)
 416   (svn_auth_cred_ssl_server_trust_t **cred,
 417    void *baton,
 418    const char *realm,
 419    apr_uint32_t failures,
 420    const svn_auth_ssl_server_cert_info_t *cert_info,
 421    svn_boolean_t may_save,
 422    apr_pool_t *pool);
 423
 424
 425 /** Set @a *cred by prompting the user, allocating @a *cred in @a pool.
 426  * @a baton is an implementation-specific closure.  @a realm is a string
 427  * that can be used in the prompt string.
 428  *
 429  * If @a may_save is FALSE, the auth system does not allow the credentials
 430  * to be saved (to disk). A prompt function shall not ask the user if the
 431  * credentials shall be saved if @a may_save is FALSE. For example, a GUI
 432  * client with a remember certificate checkbox would grey out the checkbox
 433  * if @a may_save is FALSE.
 434  */
 435 typedef svn_error_t *(*svn_auth_ssl_client_cert_prompt_func_t)
 436   (svn_auth_cred_ssl_client_cert_t **cred,
 437    void *baton,
 438    const char *realm,
 439    svn_boolean_t may_save,
 440    apr_pool_t *pool);
 441
 442
 443 /** Set @a *cred by prompting the user, allocating @a *cred in @a pool.
 444  * @a baton is an implementation-specific closure.  @a realm is a string
 445  * identifying the certificate, and can be used in the prompt string.
 446  *
 447  * If @a may_save is FALSE, the auth system does not allow the credentials
 448  * to be saved (to disk). A prompt function shall not ask the user if the
 449  * credentials shall be saved if @a may_save is FALSE. For example, a GUI
 450  * client with a remember password checkbox would grey out the checkbox if
 451  * @a may_save is FALSE.
 452  */
 453 typedef svn_error_t *(*svn_auth_ssl_client_cert_pw_prompt_func_t)
 454   (svn_auth_cred_ssl_client_cert_pw_t **cred,
 455    void *baton,
 456    const char *realm,
 457    svn_boolean_t may_save,
 458    apr_pool_t *pool);
 459
 460
 461 \f
 462 /** Initialize an authentication system.
 463  *
 464  * Return an authentication object in @a *auth_baton (allocated in @a
 465  * pool) that represents a particular instance of the svn
 466  * authentication system.  @a providers is an array of @c
 467  * svn_auth_provider_object_t pointers, already allocated in @a pool
 468  * and intentionally ordered.  These pointers will be stored within @a
 469  * *auth_baton, grouped by credential type, and searched in this exact
 470  * order.
 471  */
 472 void svn_auth_open(svn_auth_baton_t **auth_baton,
 473                    apr_array_header_t *providers,
 474                    apr_pool_t *pool);
 475
 476 /** Set an authentication run-time parameter.
 477  *
 478  * Store @a name / @a value pair as a run-time parameter in @a
 479  * auth_baton, making the data accessible to all providers.  @a name
 480  * and @a value will NOT be duplicated into the auth_baton's pool.
 481  * To delete a run-time parameter, pass NULL for @a value.
 482  */
 483 void svn_auth_set_parameter(svn_auth_baton_t *auth_baton,
 484                             const char *name,
 485                             const void *value);
 486
 487 /** Get an authentication run-time parameter.
 488  *
 489  * Return a value for run-time parameter @a name from @a auth_baton.
 490  * Return NULL if the parameter doesn't exist.
 491  */
 492 const void * svn_auth_get_parameter(svn_auth_baton_t *auth_baton,
 493                                     const char *name);
 494
 495 /** Universal run-time parameters, made available to all providers.
 496
 497     If you are writing a new provider, then to be a "good citizen",
 498     you should notice these global parameters!  Note that these
 499     run-time params should be treated as read-only by providers; the
 500     application is responsible for placing them into the auth_baton
 501     hash. */
 502
 503 /** The auth-hash prefix indicating that the parameter is global. */
 504 #define SVN_AUTH_PARAM_PREFIX "svn:auth:"
 505
 506 /**
 507  * @name Default credentials defines
 508  * Any 'default' credentials that came in through the application itself,
 509  * (e.g. --username and --password options). Property values are
 510  * const char *.
 511  * @{ */
 512 #define SVN_AUTH_PARAM_DEFAULT_USERNAME  SVN_AUTH_PARAM_PREFIX "username"
 513 #define SVN_AUTH_PARAM_DEFAULT_PASSWORD  SVN_AUTH_PARAM_PREFIX "password"
 514 /** @} */
 515
 516 /** @brief The application doesn't want any providers to prompt
 517  * users. Property value is irrelevant; only property's existence
 518  * matters. */
 519 #define SVN_AUTH_PARAM_NON_INTERACTIVE  SVN_AUTH_PARAM_PREFIX "non-interactive"
 520
 521 /** @brief The application doesn't want any providers to save passwords
 522  * to disk. Property value is irrelevant; only property's existence
 523  * matters. */
 524 #define SVN_AUTH_PARAM_DONT_STORE_PASSWORDS  SVN_AUTH_PARAM_PREFIX \
 525                                                  "dont-store-passwords"
 526
 527 /** @brief The application doesn't want any providers to save credentials
 528  * to disk. Property value is irrelevant; only property's existence
 529  * matters. */
 530 #define SVN_AUTH_PARAM_NO_AUTH_CACHE  SVN_AUTH_PARAM_PREFIX "no-auth-cache"
 531
 532 /** @brief The following property is for SSL server cert providers. This
 533  * provides a pointer to an @c apr_uint32_t containing the failures
 534  * detected by the certificate validator. */
 535 #define SVN_AUTH_PARAM_SSL_SERVER_FAILURES SVN_AUTH_PARAM_PREFIX \
 536   "ssl:failures"
 537
 538 /** @brief The following property is for SSL server cert providers. This
 539  * provides the cert info (svn_auth_ssl_server_cert_info_t). */
 540 #define SVN_AUTH_PARAM_SSL_SERVER_CERT_INFO SVN_AUTH_PARAM_PREFIX \
 541   "ssl:cert-info"
 542
 543 /** Some providers need access to the @c svn_config_t configuration. */
 544 #define SVN_AUTH_PARAM_CONFIG SVN_AUTH_PARAM_PREFIX "config"
 545
 546 /** The current server group. */
 547 #define SVN_AUTH_PARAM_SERVER_GROUP SVN_AUTH_PARAM_PREFIX "server-group"
 548
 549 /** @brief A configuration directory that overrides the default
 550  * ~/.subversion. */
 551 #define SVN_AUTH_PARAM_CONFIG_DIR SVN_AUTH_PARAM_PREFIX "config-dir"
 552
 553
 554 /** Get an initial set of credentials.
 555  *
 556  * Ask @a auth_baton to set @a *credentials to a set of credentials
 557  * defined by @a cred_kind and valid within @a realmstring, or NULL if
 558  * no credentials are available.  Otherwise, return an iteration state
 559  * in @a *state, so that the caller can call
 560  * svn_auth_next_credentials(), in case the first set of credentials
 561  * fails to authenticate.
 562  *
 563  * Use @a pool to allocate @a *state, and for temporary allocation.
 564  * Note that @a *credentials will be allocated in @a auth_baton's pool.
 565  */
 566 svn_error_t * svn_auth_first_credentials(void **credentials,
 567                                          svn_auth_iterstate_t **state,
 568                                          const char *cred_kind,
 569                                          const char *realmstring,
 570                                          svn_auth_baton_t *auth_baton,
 571                                          apr_pool_t *pool);
 572
 573 /** Get another set of credentials, assuming previous ones failed to
 574  * authenticate.
 575  *
 576  * Use @a state to fetch a different set of @a *credentials, as a
 577  * follow-up to svn_auth_first_credentials() or
 578  * svn_auth_next_credentials().  If no more credentials are available,
 579  * set @a *credentials to NULL.
 580  *
 581  * Note that @a *credentials will be allocated in @c auth_baton's pool.
 582  */
 583 svn_error_t * svn_auth_next_credentials(void **credentials,
 584                                         svn_auth_iterstate_t *state,
 585                                         apr_pool_t *pool);
 586
 587 /** Save a set of credentials.
 588  *
 589  * Ask @a state to store the most recently returned credentials,
 590  * presumably because they successfully authenticated.  Use @a pool
 591  * for temporary allocation.  If no credentials were ever returned, do
 592  * nothing.
 593  */
 594 svn_error_t * svn_auth_save_credentials(svn_auth_iterstate_t *state,
 595                                         apr_pool_t *pool);
 596
 597 /** @} */
 598
 599 /** Create and return @a *provider, an authentication provider of type
 600  * svn_auth_cred_simple_t that gets information by prompting the user
 601  * with @a prompt_func and @a prompt_baton.  Allocate @a *provider in
 602  * @a pool.
 603  *
 604  * If both @c SVN_AUTH_PARAM_DEFAULT_USERNAME and
 605  * @c SVN_AUTH_PARAM_DEFAULT_PASSWORD are defined as runtime
 606  * parameters in the @c auth_baton, then @a *provider will return the
 607  * default arguments when svn_auth_first_credentials() is called.  If
 608  * svn_auth_first_credentials() fails, then @a *provider will
 609  * re-prompt @a retry_limit times (via svn_auth_next_credentials()).
 610  *
 611  * @since New in 1.4.
 612  */
 613 void
 614 svn_auth_get_simple_prompt_provider(svn_auth_provider_object_t **provider,
 615                                     svn_auth_simple_prompt_func_t prompt_func,
 616                                     void *prompt_baton,
 617                                     int retry_limit,
 618                                     apr_pool_t *pool);
 619
 620
 621 /** Create and return @a *provider, an authentication provider of type @c
 622  * svn_auth_cred_username_t that gets information by prompting the
 623  * user with @a prompt_func and @a prompt_baton.  Allocate @a *provider
 624  * in @a pool.
 625  *
 626  * If @c SVN_AUTH_PARAM_DEFAULT_USERNAME is defined as a runtime
 627  * parameter in the @c auth_baton, then @a *provider will return the
 628  * default argument when svn_auth_first_credentials() is called.  If
 629  * svn_auth_first_credentials() fails, then @a *provider will
 630  * re-prompt @a retry_limit times (via svn_auth_next_credentials()).
 631  *
 632  * @since New in 1.4.
 633  */
 634 void svn_auth_get_username_prompt_provider
 635   (svn_auth_provider_object_t **provider,
 636    svn_auth_username_prompt_func_t prompt_func,
 637    void *prompt_baton,
 638    int retry_limit,
 639    apr_pool_t *pool);
 640
 641
 642 /** Create and return @a *provider, an authentication provider of type @c
 643  * svn_auth_cred_simple_t that gets/sets information from the user's
 644  * ~/.subversion configuration directory.  Allocate @a *provider in
 645  * @a pool.
 646  *
 647  * If a default username or password is available, @a *provider will
 648  * honor them as well, and return them when
 649  * svn_auth_first_credentials() is called.  (see @c
 650  * SVN_AUTH_PARAM_DEFAULT_USERNAME and @c
 651  * SVN_AUTH_PARAM_DEFAULT_PASSWORD).
 652  *
 653  * @since New in 1.4.
 654  */
 655 void svn_auth_get_simple_provider(svn_auth_provider_object_t **provider,
 656                                   apr_pool_t *pool);
 657
 658
 659 #if (defined(WIN32) && !defined(__MINGW32__)) || defined(DOXYGEN)
 660 /**
 661  * Create and return @a *provider, an authentication provider of type @c
 662  * svn_auth_cred_simple_t that gets/sets information from the user's
 663  * ~/.subversion configuration directory.  Allocate @a *provider in
 664  * @a pool.
 665  *
 666  * This is like svn_client_get_simple_provider(), except that, when
 667  * running on Window 2000 or newer (or any other Windows version that
 668  * includes the CryptoAPI), the provider encrypts the password before
 669  * storing it to disk. On earlier versions of Windows, the provider
 670  * does nothing.
 671  *
 672  * @since New in 1.4.
 673  * @note This function is only available on Windows.
 674  *
 675  * @note An administrative password reset may invalidate the account's
 676  * secret key. This function will detect that situation and behave as
 677  * if the password were not cached at all.
 678  */
 679 void
 680 svn_auth_get_windows_simple_provider(svn_auth_provider_object_t **provider,
 681                                      apr_pool_t *pool);
 682 #endif /* WIN32 || DOXYGEN */
 683
 684 #if defined(DARWIN) || defined(DOXYGEN)
 685
 686 /**
 687  * Create and return @a *provider, an authentication provider of type @c
 688  * svn_auth_cred_simple_t that gets/sets information from the user's
 689  * ~/.subversion configuration directory.  Allocate @a *provider in
 690  * @a pool.
 691  *
 692  * This is like svn_client_get_simple_provider(), except that the
 693  * password is stored in the Mac OS KeyChain.
 694  *
 695  * @since New in 1.4
 696  * @note This function is only available on Mac OS 10.2 and higher.
 697  */
 698 void
 699 svn_auth_get_keychain_simple_provider(svn_auth_provider_object_t **provider,
 700                                       apr_pool_t *pool);
 701
 702 #endif /* DARWIN || DOXYGEN */
 703
 704 /** Create and return @a *provider, an authentication provider of type @c
 705  * svn_auth_cred_username_t that gets/sets information from a user's
 706  * ~/.subversion configuration directory.  Allocate @a *provider in
 707  * @a pool.
 708  *
 709  * If a default username is available, @a *provider will honor it,
 710  * and return it when svn_auth_first_credentials() is called.  (See
 711  * @c SVN_AUTH_PARAM_DEFAULT_USERNAME.)
 712  *
 713  * @since New in 1.4.
 714  */
 715 void svn_auth_get_username_provider(svn_auth_provider_object_t **provider,
 716                                     apr_pool_t *pool);
 717
 718
 719 /** Create and return @a *provider, an authentication provider of type @c
 720  * svn_auth_cred_ssl_server_trust_t, allocated in @a pool.
 721  *
 722  * @a *provider retrieves its credentials from the configuration
 723  * mechanism.  The returned credential is used to override SSL
 724  * security on an error.
 725  *
 726  * @since New in 1.4.
 727  */
 728 void svn_auth_get_ssl_server_trust_file_provider
 729   (svn_auth_provider_object_t **provider,
 730    apr_pool_t *pool);
 731
 732
 733 #if (defined(WIN32) && !defined(__MINGW32__)) || defined(DOXYGEN)
 734 /**
 735  * Create and return @a *provider, an authentication provider of type @c
 736  * svn_auth_cred_ssl_server_trust_t, allocated in @a pool.
 737  *
 738  * This provider automatically validates ssl server certificates with
 739  * the CryptoApi, like Internet Explorer and the Windows network API do.
 740  * This allows the rollout of root certificates via Windows Domain
 741  * policies, instead of Subversion specific configuration.
 742  *
 743  * @since New in 1.5.
 744  * @note This function is only available on Windows.
 745  */
 746 void
 747 svn_auth_get_windows_ssl_server_trust_provider
 748   (svn_auth_provider_object_t **provider,
 749    apr_pool_t *pool);
 750 #endif /* WIN32 || DOXYGEN */
 751
 752 /** Create and return @a *provider, an authentication provider of type @c
 753  * svn_auth_cred_ssl_client_cert_t, allocated in @a pool.
 754  *
 755  * @a *provider retrieves its credentials from the configuration
 756  * mechanism.  The returned credential is used to load the appropriate
 757  * client certificate for authentication when requested by a server.
 758  *
 759  * @since New in 1.4.
 760  */
 761 void svn_auth_get_ssl_client_cert_file_provider
 762   (svn_auth_provider_object_t **provider,
 763    apr_pool_t *pool);
 764
 765
 766 /** Create and return @a *provider, an authentication provider of type @c
 767  * svn_auth_cred_ssl_client_cert_pw_t, allocated in @a pool.
 768  *
 769  * @a *provider retrieves its credentials from the configuration
 770  * mechanism.  The returned credential is used when a loaded client
 771  * certificate is protected by a passphrase.
 772  *
 773  * @since New in 1.4.
 774  */
 775 void svn_auth_get_ssl_client_cert_pw_file_provider
 776   (svn_auth_provider_object_t **provider,
 777    apr_pool_t *pool);
 778
 779
 780 /** Create and return @a *provider, an authentication provider of type @c
 781  * svn_auth_cred_ssl_server_trust_t, allocated in @a pool.
 782  *
 783  * @a *provider retrieves its credentials by using the @a prompt_func
 784  * and @a prompt_baton.  The returned credential is used to override
 785  * SSL security on an error.
 786  *
 787  * @since New in 1.4.
 788  */
 789 void svn_auth_get_ssl_server_trust_prompt_provider
 790   (svn_auth_provider_object_t **provider,
 791    svn_auth_ssl_server_trust_prompt_func_t prompt_func,
 792    void *prompt_baton,
 793    apr_pool_t *pool);
 794
 795
 796 /** Create and return @a *provider, an authentication provider of type @c
 797  * svn_auth_cred_ssl_client_cert_t, allocated in @a pool.
 798  *
 799  * @a *provider retrieves its credentials by using the @a prompt_func
 800  * and @a prompt_baton.  The returned credential is used to load the
 801  * appropriate client certificate for authentication when requested by
 802  * a server.  The prompt will be retried @a retry_limit times.
 803  *
 804  * @since New in 1.4.
 805  */
 806 void svn_auth_get_ssl_client_cert_prompt_provider
 807   (svn_auth_provider_object_t **provider,
 808    svn_auth_ssl_client_cert_prompt_func_t prompt_func,
 809    void *prompt_baton,
 810    int retry_limit,
 811    apr_pool_t *pool);
 812
 813
 814 /** Create and return @a *provider, an authentication provider of type @c
 815  * svn_auth_cred_ssl_client_cert_pw_t, allocated in @a pool.
 816  *
 817  * @a *provider retrieves its credentials by using the @a prompt_func
 818  * and @a prompt_baton.  The returned credential is used when a loaded
 819  * client certificate is protected by a passphrase.  The prompt will
 820  * be retried @a retry_limit times.
 821  *
 822  * @since New in 1.4.
 823  */
 824 void svn_auth_get_ssl_client_cert_pw_prompt_provider
 825   (svn_auth_provider_object_t **provider,
 826    svn_auth_ssl_client_cert_pw_prompt_func_t prompt_func,
 827    void *prompt_baton,
 828    int retry_limit,
 829    apr_pool_t *pool);
 830
 831 #ifdef __cplusplus
 832 }
 833 #endif /* __cplusplus */
 834
 835 #endif /* SVN_AUTH_H */