svn_auth.h

Go to the documentation of this file.
00001 /**
00002  * @copyright
00003  * ====================================================================
00004  * Copyright (c) 2000-2004 CollabNet.  All rights reserved.
00005  *
00006  * This software is licensed as described in the file COPYING, which
00007  * you should have received as part of this distribution.  The terms
00008  * are also available at http://subversion.tigris.org/license-1.html.
00009  * If newer versions of this license are posted there, you may use a
00010  * newer version instead, at your option.
00011  *
00012  * This software consists of voluntary contributions made by many
00013  * individuals.  For exact contribution history, see the revision
00014  * history and logs, available at http://subversion.tigris.org/.
00015  * ====================================================================
00016  * @endcopyright
00017  *
00018  * @file svn_auth.h
00019  * @brief Subversion's authentication system
00020  */
00021 
00022 #ifndef SVN_AUTH_H
00023 #define SVN_AUTH_H
00024 
00025 #include <apr_pools.h>
00026 
00027 #include "svn_types.h"
00028 
00029 #ifdef __cplusplus
00030 extern "C" {
00031 #endif /* __cplusplus */
00032 
00033 /** Overview of the svn authentication system.
00034  *
00035  * We define an authentication "provider" as a module that is able to
00036  * return a specific set of credentials. (e.g. username/password,
00037  * certificate, etc.)  Each provider implements a vtable that
00038  *
00039  * - can fetch initial credentials
00040  * - can retry the fetch (or try to fetch something different)
00041  * - can store the credentials for future use
00042  *
00043  * For any given type of credentials, there can exist any number of
00044  * separate providers -- each provider has a different method of
00045  * fetching. (i.e. from a disk store, by prompting the user, etc.)
00046  *
00047  * The application begins by creating an auth baton object, and
00048  * "registers" some number of providers with the auth baton, in a
00049  * specific order.  (For example, it may first register a
00050  * username/password provider that looks in disk store, then register
00051  * a username/password provider that prompts the user.)
00052  *
00053  * Later on, when any svn library is challenged, it asks the auth
00054  * baton for the specific credentials.  If the initial credentials
00055  * fail to authenticate, the caller keeps requesting new credentials.
00056  * Under the hood, libsvn_auth effectively "walks" over each provider
00057  * (in order of registry), one at a time, until all the providers have
00058  * exhausted all their retry options.
00059  *
00060  * This system allows an application to flexibly define authentication
00061  * behaviors (by changing registration order), and very easily write
00062  * new authentication providers.
00063  *
00064  * An auth_baton also contains an internal hashtable of run-time
00065  * parameters; any provider or library layer can set these run-time
00066  * parameters at any time, so that the provider has access to the
00067  * data.  (For example, certain run-time data may not be available
00068  * until an authentication challenge is made.)  Each credential type
00069  * must document the run-time parameters that are made available to
00070  * its providers.
00071  *
00072  * @defgroup auth_fns Authentication functions
00073  * @{
00074  */
00075 
00076 
00077 /** The type of a Subversion authentication object */
00078 typedef struct svn_auth_baton_t svn_auth_baton_t;
00079 
00080 /** The type of a Subversion authentication-iteration object */
00081 typedef struct svn_auth_iterstate_t svn_auth_iterstate_t;
00082 
00083 
00084 /** The main authentication "provider" vtable. */
00085 typedef struct svn_auth_provider_t
00086 {
00087   /** The kind of credentials this provider knows how to retrieve. */
00088   const char *cred_kind;
00089 
00090   /** Get an initial set of credentials.
00091    *
00092    * Set @a *credentials to a set of valid credentials within @a
00093    * realmstring, or NULL if no credentials are available.  Set @a
00094    * *iter_baton to context that allows a subsequent call to @c
00095    * next_credentials, in case the first credentials fail to
00096    * authenticate.  @a provider_baton is general context for the
00097    * vtable, @a parameters contains any run-time data that the
00098    * provider may need, and @a realmstring comes from the
00099    * svn_auth_first_credentials() call.
00100    */
00101   svn_error_t * (*first_credentials)(void **credentials,
00102                                      void **iter_baton,
00103                                      void *provider_baton,
00104                                      apr_hash_t *parameters,
00105                                      const char *realmstring,
00106                                      apr_pool_t *pool);
00107 
00108   /** Get a different set of credentials.
00109    *
00110    * Set @a *credentials to another set of valid credentials (using @a
00111    * iter_baton as the context from previous call to first_credentials
00112    * or next_credentials).  If no more credentials are available, set
00113    * @a *credentials to NULL.  If the provider only has one set of
00114    * credentials, this function pointer should simply be NULL. @a
00115    * provider_baton is general context for the vtable, @a parameters
00116    * contains any run-time data that the provider may need, and @a
00117    * realmstring comes from the svn_auth_first_credentials() call.
00118    */
00119   svn_error_t * (*next_credentials)(void **credentials,
00120                                     void *iter_baton,
00121                                     void *provider_baton,
00122                                     apr_hash_t *parameters,
00123                                     const char *realmstring,
00124                                     apr_pool_t *pool);
00125 
00126   /** Save credentials.
00127    *
00128    * Store @a credentials for future use.  @a provider_baton is
00129    * general context for the vtable, and @a parameters contains any
00130    * run-time data the provider may need.  Set @a *saved to TRUE if
00131    * the save happened, or FALSE if not.  The provider is not required
00132    * to save; if it refuses or is unable to save for non-fatal
00133    * reasons, return FALSE.  If the provider never saves data, then
00134    * this function pointer should simply be NULL. @a realmstring comes
00135    * from the svn_auth_first_credentials() call.
00136    */
00137   svn_error_t * (*save_credentials)(svn_boolean_t *saved,
00138                                     void *credentials,
00139                                     void *provider_baton,
00140                                     apr_hash_t *parameters,
00141                                     const char *realmstring,
00142                                     apr_pool_t *pool);
00143 
00144 } svn_auth_provider_t;
00145 
00146 
00147 /** A provider object, ready to be put into an array and given to
00148     svn_auth_open(). */
00149 typedef struct svn_auth_provider_object_t
00150 {
00151   const svn_auth_provider_t *vtable;
00152   void *provider_baton;
00153 
00154 } svn_auth_provider_object_t;
00155 
00156 
00157 
00158 /** Specific types of credentials **/
00159 
00160 /** Simple username/password pair credential kind.
00161  *
00162  * The following auth parameters may be available to the providers:
00163  *
00164  * - @c SVN_AUTH_PARAM_NO_AUTH_CACHE (@c void*)
00165  * - @c SVN_AUTH_PARAM_DEFAULT_USERNAME (@c char*)
00166  * - @c SVN_AUTH_PARAM_DEFAULT_PASSWORD (@c char*)
00167  */
00168 #define SVN_AUTH_CRED_SIMPLE "svn.simple"
00169 
00170 /** @c SVN_AUTH_CRED_SIMPLE credentials. */
00171 typedef struct svn_auth_cred_simple_t
00172 {
00173   /** Username */
00174   const char *username;
00175   /** Password */
00176   const char *password;
00177   /** Indicates if the credentials may be saved (to disk). For example, a
00178    * GUI prompt implementation with a remember password checkbox shall set
00179    * @a may_save to TRUE if the checkbox is checked.
00180    */
00181   svn_boolean_t may_save;
00182 } svn_auth_cred_simple_t;
00183 
00184 
00185 /** Username credential kind.
00186  *
00187  * The following optional auth parameters are relevant to the providers:
00188  *
00189  * - @c SVN_AUTH_PARAM_NO_AUTH_CACHE (@c void*)
00190  * - @c SVN_AUTH_PARAM_DEFAULT_USERNAME (@c char*)
00191  */
00192 #define SVN_AUTH_CRED_USERNAME "svn.username"
00193 
00194 /** @c SVN_AUTH_CRED_USERNAME credentials. */
00195 typedef struct svn_auth_cred_username_t
00196 {
00197   /** Username */
00198   const char *username;
00199   /** Indicates if the credentials may be saved (to disk). For example, a
00200    * GUI prompt implementation with a remember username checkbox shall set
00201    * @a may_save to TRUE if the checkbox is checked.
00202    */
00203   svn_boolean_t may_save;
00204 } svn_auth_cred_username_t;
00205 
00206 
00207 /** SSL client certificate credential type.
00208  *
00209  * The following auth parameters are available to the providers:
00210  *
00211  * - @c SVN_AUTH_PARAM_CONFIG (@c svn_config_t*)
00212  * - @c SVN_AUTH_PARAM_SERVER_GROUP (@c char*)
00213  *
00214  * The following optional auth parameters are relevant to the providers:
00215  *
00216  * - @c SVN_AUTH_PARAM_NO_AUTH_CACHE (@c void*)
00217  */
00218 #define SVN_AUTH_CRED_SSL_CLIENT_CERT "svn.ssl.client-cert"
00219 
00220 /** @c SVN_AUTH_CRED_SSL_CLIENT_CERT credentials. */
00221 typedef struct svn_auth_cred_ssl_client_cert_t
00222 {
00223   /** Full paths to the certificate file */
00224   const char *cert_file;
00225   /** Indicates if the credentials may be saved (to disk). For example, a
00226    * GUI prompt implementation with a remember certificate checkbox shall
00227    * set @a may_save to TRUE if the checkbox is checked.
00228    */
00229   svn_boolean_t may_save;
00230 } svn_auth_cred_ssl_client_cert_t;
00231 
00232 
00233 /** SSL client certificate passphrase credential type.
00234  *
00235  * @note The realmstring used with this credential type must be a name that
00236  * makes it possible for the user to identify the certificate.
00237  *
00238  * The following auth parameters are available to the providers:
00239  *
00240  * - @c SVN_AUTH_PARAM_CONFIG (@c svn_config_t*)
00241  * - @c SVN_AUTH_PARAM_SERVER_GROUP (@c char*)
00242  *
00243  * The following optional auth parameters are relevant to the providers:
00244  *
00245  * - @c SVN_AUTH_PARAM_NO_AUTH_CACHE (@c void*)
00246  */
00247 #define SVN_AUTH_CRED_SSL_CLIENT_CERT_PW "svn.ssl.client-passphrase"
00248 
00249 /** @c SVN_AUTH_CRED_SSL_CLIENT_CERT_PW credentials. */
00250 typedef struct svn_auth_cred_ssl_client_cert_pw_t
00251 {
00252   /** Certificate password */
00253   const char *password;
00254   /** Indicates if the credentials may be saved (to disk). For example, a
00255    * GUI prompt implementation with a remember password checkbox shall set
00256    * @a may_save to TRUE if the checkbox is checked.
00257    */
00258   svn_boolean_t may_save;
00259 } svn_auth_cred_ssl_client_cert_pw_t;
00260 
00261 
00262 /** SSL server verification credential type.
00263  *
00264  * The following auth parameters are available to the providers:
00265  *
00266  * - @c SVN_AUTH_PARAM_CONFIG (@c svn_config_t*)
00267  * - @c SVN_AUTH_PARAM_SERVER_GROUP (@c char*)
00268  * - @c SVN_AUTH_PARAM_SSL_SERVER_FAILURES (@c apr_uint32_t*)
00269  * - @c SVN_AUTH_PARAM_SSL_SERVER_CERT_INFO
00270  *      (@c svn_auth_ssl_server_cert_info_t*)
00271  *
00272  * The following optional auth parameters are relevant to the providers:
00273  *
00274  * - @c SVN_AUTH_PARAM_NO_AUTH_CACHE (@c void*)
00275  */
00276 #define SVN_AUTH_CRED_SSL_SERVER_TRUST "svn.ssl.server"
00277 
00278 /** SSL server certificate information used by @c
00279  * SVN_AUTH_CRED_SSL_SERVER_TRUST providers.
00280  */
00281 typedef struct svn_auth_ssl_server_cert_info_t
00282 {
00283   /** Primary CN */
00284   const char *hostname;
00285   /** ASCII fingerprint */
00286   const char *fingerprint;
00287   /** ASCII date from which the certificate is valid */
00288   const char *valid_from;
00289   /** ASCII date until which the certificate is valid */
00290   const char *valid_until;
00291   /** DN of the certificate issuer */
00292   const char *issuer_dname;
00293   /** Base-64 encoded DER certificate representation */
00294   const char *ascii_cert;
00295 } svn_auth_ssl_server_cert_info_t;
00296 
00297 /**
00298  * Return a deep copy of @a info, allocated in @a pool.
00299  *
00300  * @since New in 1.3.
00301  */
00302 svn_auth_ssl_server_cert_info_t *
00303 svn_auth_ssl_server_cert_info_dup(const svn_auth_ssl_server_cert_info_t *info,
00304                                   apr_pool_t *pool);
00305 
00306 /** @c SVN_AUTH_CRED_SSL_SERVER_TRUST credentials. */
00307 typedef struct svn_auth_cred_ssl_server_trust_t
00308 {
00309   /** Indicates if the credentials may be saved (to disk). For example, a
00310    * GUI prompt implementation with a checkbox to accept the certificate
00311    * permanently shall set @a may_save to TRUE if the checkbox is checked.
00312    */
00313   svn_boolean_t may_save;
00314   /** Bit mask of the accepted failures */
00315   apr_uint32_t accepted_failures;
00316 } svn_auth_cred_ssl_server_trust_t;
00317 
00318 
00319 
00320 /** Credential-constructing prompt functions. **/
00321 
00322 /** These exist so that different client applications can use
00323  * different prompt mechanisms to supply the same credentials.  For
00324  * example, if authentication requires a username and password, a
00325  * command-line client's prompting function might prompt first for the
00326  * username and then for the password, whereas a GUI client's would
00327  * present a single dialog box asking for both, and a telepathic
00328  * client's would read all the information directly from the user's
00329  * mind.  All these prompting functions return the same type of
00330  * credential, but the information used to construct the credential is
00331  * gathered in an interface-specific way in each case.
00332  */
00333 
00334 /** Set @a *cred by prompting the user, allocating @a *cred in @a pool.
00335  * @a baton is an implementation-specific closure.
00336  *
00337  * If @a realm is non-NULL, maybe use it in the prompt string.
00338  *
00339  * If @a username is non-NULL, then the user might be prompted only
00340  * for a password, but @a *cred would still be filled with both
00341  * username and password.  For example, a typical usage would be to
00342  * pass @a username on the first call, but then leave it NULL for
00343  * subsequent calls, on the theory that if credentials failed, it's
00344  * as likely to be due to incorrect username as incorrect password.
00345  *
00346  * If @a may_save is FALSE, the auth system does not allow the credentials
00347  * to be saved (to disk). A prompt function shall not ask the user if the
00348  * credentials shall be saved if @a may_save is FALSE. For example, a GUI
00349  * client with a remember password checkbox would grey out the checkbox if
00350  * @a may_save is FALSE.
00351  */
00352 typedef svn_error_t *(*svn_auth_simple_prompt_func_t)
00353   (svn_auth_cred_simple_t **cred,
00354    void *baton,
00355    const char *realm,
00356    const char *username,
00357    svn_boolean_t may_save,
00358    apr_pool_t *pool);
00359 
00360 
00361 /** Set @a *cred by prompting the user, allocating @a *cred in @a pool.
00362  * @a baton is an implementation-specific closure.
00363  *
00364  * If @a realm is non-NULL, maybe use it in the prompt string.
00365  *
00366  * If @a may_save is FALSE, the auth system does not allow the credentials
00367  * to be saved (to disk). A prompt function shall not ask the user if the
00368  * credentials shall be saved if @a may_save is FALSE. For example, a GUI
00369  * client with a remember username checkbox would grey out the checkbox if
00370  * @a may_save is FALSE.
00371  */
00372 typedef svn_error_t *(*svn_auth_username_prompt_func_t)
00373   (svn_auth_cred_username_t **cred,
00374    void *baton,
00375    const char *realm,
00376    svn_boolean_t may_save,
00377    apr_pool_t *pool);
00378 
00379 
00380 /** @name SSL server certificate failure bits
00381  *
00382  * @note These values are stored in the on disk auth cache by the SSL
00383  * server certificate auth provider, so the meaning of these bits must
00384  * not be changed.
00385  * @{
00386  */
00387 /** Certificate is not yet valid. */
00388 #define SVN_AUTH_SSL_NOTYETVALID 0x00000001
00389 /** Certificate has expired. */
00390 #define SVN_AUTH_SSL_EXPIRED     0x00000002
00391 /** Certificate's CN (hostname) does not match the remote hostname. */
00392 #define SVN_AUTH_SSL_CNMISMATCH  0x00000004
00393 /** @brief Certificate authority is unknown (i.e. not trusted) */
00394 #define SVN_AUTH_SSL_UNKNOWNCA   0x00000008
00395 /** @brief Other failure. This can happen if neon has introduced a new
00396  * failure bit that we do not handle yet. */
00397 #define SVN_AUTH_SSL_OTHER       0x40000000
00398 /** @} */
00399 
00400 /** Set @a *cred by prompting the user, allocating @a *cred in @a pool.
00401  * @a baton is an implementation-specific closure.
00402  *
00403  * @a cert_info is a structure describing the server cert that was
00404  * presented to the client, and @a failures is a bitmask that
00405  * describes exactly why the cert could not be automatically validated,
00406  * composed from the constants SVN_AUTH_SSL_* (@c SVN_AUTH_SSL_NOTYETVALID
00407  * etc.).  @a realm is a string that can be used in the prompt string.
00408  *
00409  * If @a may_save is FALSE, the auth system does not allow the credentials
00410  * to be saved (to disk). A prompt function shall not ask the user if the
00411  * credentials shall be saved if @a may_save is FALSE. For example, a GUI
00412  * client with a trust permanently checkbox would grey out the checkbox if
00413  * @a may_save is FALSE.
00414  */
00415 typedef svn_error_t *(*svn_auth_ssl_server_trust_prompt_func_t)
00416   (svn_auth_cred_ssl_server_trust_t **cred,
00417    void *baton,
00418    const char *realm,
00419    apr_uint32_t failures,
00420    const svn_auth_ssl_server_cert_info_t *cert_info,
00421    svn_boolean_t may_save,
00422    apr_pool_t *pool);
00423 
00424 
00425 /** Set @a *cred by prompting the user, allocating @a *cred in @a pool.
00426  * @a baton is an implementation-specific closure.  @a realm is a string
00427  * that can be used in the prompt string.
00428  *
00429  * If @a may_save is FALSE, the auth system does not allow the credentials
00430  * to be saved (to disk). A prompt function shall not ask the user if the
00431  * credentials shall be saved if @a may_save is FALSE. For example, a GUI
00432  * client with a remember certificate checkbox would grey out the checkbox
00433  * if @a may_save is FALSE.
00434  */
00435 typedef svn_error_t *(*svn_auth_ssl_client_cert_prompt_func_t)
00436   (svn_auth_cred_ssl_client_cert_t **cred,
00437    void *baton,
00438    const char *realm,
00439    svn_boolean_t may_save,
00440    apr_pool_t *pool);
00441 
00442 
00443 /** Set @a *cred by prompting the user, allocating @a *cred in @a pool.
00444  * @a baton is an implementation-specific closure.  @a realm is a string
00445  * identifying the certificate, and can be used in the prompt string.
00446  *
00447  * If @a may_save is FALSE, the auth system does not allow the credentials
00448  * to be saved (to disk). A prompt function shall not ask the user if the
00449  * credentials shall be saved if @a may_save is FALSE. For example, a GUI
00450  * client with a remember password checkbox would grey out the checkbox if
00451  * @a may_save is FALSE.
00452  */
00453 typedef svn_error_t *(*svn_auth_ssl_client_cert_pw_prompt_func_t)
00454   (svn_auth_cred_ssl_client_cert_pw_t **cred,
00455    void *baton,
00456    const char *realm,
00457    svn_boolean_t may_save,
00458    apr_pool_t *pool);
00459 
00460 
00461 
00462 /** Initialize an authentication system.
00463  *
00464  * Return an authentication object in @a *auth_baton (allocated in @a
00465  * pool) that represents a particular instance of the svn
00466  * authentication system.  @a providers is an array of @c
00467  * svn_auth_provider_object_t pointers, already allocated in @a pool
00468  * and intentionally ordered.  These pointers will be stored within @a
00469  * *auth_baton, grouped by credential type, and searched in this exact
00470  * order.
00471  */
00472 void svn_auth_open(svn_auth_baton_t **auth_baton,
00473                    apr_array_header_t *providers,
00474                    apr_pool_t *pool);
00475 
00476 /** Set an authentication run-time parameter.
00477  *
00478  * Store @a name / @a value pair as a run-time parameter in @a
00479  * auth_baton, making the data accessible to all providers.  @a name
00480  * and @a value will NOT be duplicated into the auth_baton's pool.
00481  * To delete a run-time parameter, pass NULL for @a value.
00482  */
00483 void svn_auth_set_parameter(svn_auth_baton_t *auth_baton,
00484                             const char *name,
00485                             const void *value);
00486 
00487 /** Get an authentication run-time parameter.
00488  *
00489  * Return a value for run-time parameter @a name from @a auth_baton.
00490  * Return NULL if the parameter doesn't exist.
00491  */
00492 const void * svn_auth_get_parameter(svn_auth_baton_t *auth_baton,
00493                                     const char *name);
00494 
00495 /** Universal run-time parameters, made available to all providers.
00496 
00497     If you are writing a new provider, then to be a "good citizen",
00498     you should notice these global parameters!  Note that these
00499     run-time params should be treated as read-only by providers; the
00500     application is responsible for placing them into the auth_baton
00501     hash. */
00502 
00503 /** The auth-hash prefix indicating that the parameter is global. */
00504 #define SVN_AUTH_PARAM_PREFIX "svn:auth:"
00505 
00506 /**
00507  * @name Default credentials defines
00508  * Any 'default' credentials that came in through the application itself,
00509  * (e.g. --username and --password options). Property values are
00510  * const char *.
00511  * @{ */
00512 #define SVN_AUTH_PARAM_DEFAULT_USERNAME  SVN_AUTH_PARAM_PREFIX "username"
00513 #define SVN_AUTH_PARAM_DEFAULT_PASSWORD  SVN_AUTH_PARAM_PREFIX "password"
00514 /** @} */
00515 
00516 /** @brief The application doesn't want any providers to prompt
00517  * users. Property value is irrelevant; only property's existence
00518  * matters. */
00519 #define SVN_AUTH_PARAM_NON_INTERACTIVE  SVN_AUTH_PARAM_PREFIX "non-interactive"
00520 
00521 /** @brief The application doesn't want any providers to save passwords
00522  * to disk. Property value is irrelevant; only property's existence
00523  * matters. */
00524 #define SVN_AUTH_PARAM_DONT_STORE_PASSWORDS  SVN_AUTH_PARAM_PREFIX \
00525                                                  "dont-store-passwords"
00526 
00527 /** @brief The application doesn't want any providers to save credentials
00528  * to disk. Property value is irrelevant; only property's existence
00529  * matters. */
00530 #define SVN_AUTH_PARAM_NO_AUTH_CACHE  SVN_AUTH_PARAM_PREFIX "no-auth-cache"
00531 
00532 /** @brief The following property is for SSL server cert providers. This
00533  * provides a pointer to an @c apr_uint32_t containing the failures
00534  * detected by the certificate validator. */
00535 #define SVN_AUTH_PARAM_SSL_SERVER_FAILURES SVN_AUTH_PARAM_PREFIX \
00536   "ssl:failures"
00537 
00538 /** @brief The following property is for SSL server cert providers. This
00539  * provides the cert info (svn_auth_ssl_server_cert_info_t). */
00540 #define SVN_AUTH_PARAM_SSL_SERVER_CERT_INFO SVN_AUTH_PARAM_PREFIX \
00541   "ssl:cert-info"
00542 
00543 /** Some providers need access to the @c svn_config_t configuration. */
00544 #define SVN_AUTH_PARAM_CONFIG SVN_AUTH_PARAM_PREFIX "config"
00545 
00546 /** The current server group. */
00547 #define SVN_AUTH_PARAM_SERVER_GROUP SVN_AUTH_PARAM_PREFIX "server-group"
00548 
00549 /** @brief A configuration directory that overrides the default
00550  * ~/.subversion. */
00551 #define SVN_AUTH_PARAM_CONFIG_DIR SVN_AUTH_PARAM_PREFIX "config-dir"
00552 
00553 
00554 /** Get an initial set of credentials.
00555  *
00556  * Ask @a auth_baton to set @a *credentials to a set of credentials
00557  * defined by @a cred_kind and valid within @a realmstring, or NULL if
00558  * no credentials are available.  Otherwise, return an iteration state
00559  * in @a *state, so that the caller can call
00560  * svn_auth_next_credentials(), in case the first set of credentials
00561  * fails to authenticate.
00562  *
00563  * Use @a pool to allocate @a *state, and for temporary allocation.
00564  * Note that @a *credentials will be allocated in @a auth_baton's pool.
00565  */
00566 svn_error_t * svn_auth_first_credentials(void **credentials,
00567                                          svn_auth_iterstate_t **state,
00568                                          const char *cred_kind,
00569                                          const char *realmstring,
00570                                          svn_auth_baton_t *auth_baton,
00571                                          apr_pool_t *pool);
00572 
00573 /** Get another set of credentials, assuming previous ones failed to
00574  * authenticate.
00575  *
00576  * Use @a state to fetch a different set of @a *credentials, as a
00577  * follow-up to svn_auth_first_credentials() or
00578  * svn_auth_next_credentials().  If no more credentials are available,
00579  * set @a *credentials to NULL.
00580  *
00581  * Note that @a *credentials will be allocated in @c auth_baton's pool.
00582  */
00583 svn_error_t * svn_auth_next_credentials(void **credentials,
00584                                         svn_auth_iterstate_t *state,
00585                                         apr_pool_t *pool);
00586 
00587 /** Save a set of credentials.
00588  *
00589  * Ask @a state to store the most recently returned credentials,
00590  * presumably because they successfully authenticated.  Use @a pool
00591  * for temporary allocation.  If no credentials were ever returned, do
00592  * nothing.
00593  */
00594 svn_error_t * svn_auth_save_credentials(svn_auth_iterstate_t *state,
00595                                         apr_pool_t *pool);
00596 
00597 /** @} */
00598 
00599 /** Create and return @a *provider, an authentication provider of type
00600  * svn_auth_cred_simple_t that gets information by prompting the user
00601  * with @a prompt_func and @a prompt_baton.  Allocate @a *provider in
00602  * @a pool.
00603  *
00604  * If both @c SVN_AUTH_PARAM_DEFAULT_USERNAME and
00605  * @c SVN_AUTH_PARAM_DEFAULT_PASSWORD are defined as runtime
00606  * parameters in the @c auth_baton, then @a *provider will return the
00607  * default arguments when svn_auth_first_credentials() is called.  If
00608  * svn_auth_first_credentials() fails, then @a *provider will
00609  * re-prompt @a retry_limit times (via svn_auth_next_credentials()).
00610  *
00611  * @since New in 1.4.
00612  */
00613 void
00614 svn_auth_get_simple_prompt_provider(svn_auth_provider_object_t **provider,
00615                                     svn_auth_simple_prompt_func_t prompt_func,
00616                                     void *prompt_baton,
00617                                     int retry_limit,
00618                                     apr_pool_t *pool);
00619 
00620 
00621 /** Create and return @a *provider, an authentication provider of type @c
00622  * svn_auth_cred_username_t that gets information by prompting the
00623  * user with @a prompt_func and @a prompt_baton.  Allocate @a *provider
00624  * in @a pool.
00625  *
00626  * If @c SVN_AUTH_PARAM_DEFAULT_USERNAME is defined as a runtime
00627  * parameter in the @c auth_baton, then @a *provider will return the
00628  * default argument when svn_auth_first_credentials() is called.  If
00629  * svn_auth_first_credentials() fails, then @a *provider will
00630  * re-prompt @a retry_limit times (via svn_auth_next_credentials()).
00631  *
00632  * @since New in 1.4.
00633  */
00634 void svn_auth_get_username_prompt_provider
00635   (svn_auth_provider_object_t **provider,
00636    svn_auth_username_prompt_func_t prompt_func,
00637    void *prompt_baton,
00638    int retry_limit,
00639    apr_pool_t *pool);
00640 
00641 
00642 /** Create and return @a *provider, an authentication provider of type @c
00643  * svn_auth_cred_simple_t that gets/sets information from the user's
00644  * ~/.subversion configuration directory.  Allocate @a *provider in
00645  * @a pool.
00646  *
00647  * If a default username or password is available, @a *provider will
00648  * honor them as well, and return them when
00649  * svn_auth_first_credentials() is called.  (see @c
00650  * SVN_AUTH_PARAM_DEFAULT_USERNAME and @c
00651  * SVN_AUTH_PARAM_DEFAULT_PASSWORD).
00652  *
00653  * @since New in 1.4.
00654  */
00655 void svn_auth_get_simple_provider(svn_auth_provider_object_t **provider,
00656                                   apr_pool_t *pool);
00657 
00658 
00659 #if (defined(WIN32) && !defined(__MINGW32__)) || defined(DOXYGEN)
00660 /**
00661  * Create and return @a *provider, an authentication provider of type @c
00662  * svn_auth_cred_simple_t that gets/sets information from the user's
00663  * ~/.subversion configuration directory.  Allocate @a *provider in
00664  * @a pool.
00665  *
00666  * This is like svn_client_get_simple_provider(), except that, when
00667  * running on Window 2000 or newer (or any other Windows version that
00668  * includes the CryptoAPI), the provider encrypts the password before
00669  * storing it to disk. On earlier versions of Windows, the provider
00670  * does nothing.
00671  *
00672  * @since New in 1.4.
00673  * @note This function is only available on Windows.
00674  *
00675  * @note An administrative password reset may invalidate the account's
00676  * secret key. This function will detect that situation and behave as
00677  * if the password were not cached at all.
00678  */
00679 void
00680 svn_auth_get_windows_simple_provider(svn_auth_provider_object_t **provider,
00681                                      apr_pool_t *pool);
00682 #endif /* WIN32 || DOXYGEN */
00683 
00684 #if defined(DARWIN) || defined(DOXYGEN)
00685 
00686 /**
00687  * Create and return @a *provider, an authentication provider of type @c
00688  * svn_auth_cred_simple_t that gets/sets information from the user's
00689  * ~/.subversion configuration directory.  Allocate @a *provider in
00690  * @a pool.
00691  *
00692  * This is like svn_client_get_simple_provider(), except that the
00693  * password is stored in the Mac OS KeyChain.
00694  *
00695  * @since New in 1.4
00696  * @note This function is only available on Mac OS 10.2 and higher.
00697  */
00698 void
00699 svn_auth_get_keychain_simple_provider(svn_auth_provider_object_t **provider,
00700                                       apr_pool_t *pool);
00701 
00702 #endif /* DARWIN || DOXYGEN */
00703 
00704 /** Create and return @a *provider, an authentication provider of type @c
00705  * svn_auth_cred_username_t that gets/sets information from a user's
00706  * ~/.subversion configuration directory.  Allocate @a *provider in
00707  * @a pool.
00708  *
00709  * If a default username is available, @a *provider will honor it,
00710  * and return it when svn_auth_first_credentials() is called.  (See
00711  * @c SVN_AUTH_PARAM_DEFAULT_USERNAME.)
00712  *
00713  * @since New in 1.4.
00714  */
00715 void svn_auth_get_username_provider(svn_auth_provider_object_t **provider,
00716                                     apr_pool_t *pool);
00717 
00718 
00719 /** Create and return @a *provider, an authentication provider of type @c
00720  * svn_auth_cred_ssl_server_trust_t, allocated in @a pool.
00721  *
00722  * @a *provider retrieves its credentials from the configuration
00723  * mechanism.  The returned credential is used to override SSL
00724  * security on an error.
00725  *
00726  * @since New in 1.4.
00727  */
00728 void svn_auth_get_ssl_server_trust_file_provider
00729   (svn_auth_provider_object_t **provider,
00730    apr_pool_t *pool);
00731 
00732 
00733 #if (defined(WIN32) && !defined(__MINGW32__)) || defined(DOXYGEN)
00734 /**
00735  * Create and return @a *provider, an authentication provider of type @c
00736  * svn_auth_cred_ssl_server_trust_t, allocated in @a pool.
00737  *
00738  * This provider automatically validates ssl server certificates with
00739  * the CryptoApi, like Internet Explorer and the Windows network API do.
00740  * This allows the rollout of root certificates via Windows Domain
00741  * policies, instead of Subversion specific configuration.
00742  *
00743  * @since New in 1.5.
00744  * @note This function is only available on Windows.
00745  */
00746 void
00747 svn_auth_get_windows_ssl_server_trust_provider
00748   (svn_auth_provider_object_t **provider,
00749    apr_pool_t *pool);
00750 #endif /* WIN32 || DOXYGEN */
00751 
00752 /** Create and return @a *provider, an authentication provider of type @c
00753  * svn_auth_cred_ssl_client_cert_t, allocated in @a pool.
00754  *
00755  * @a *provider retrieves its credentials from the configuration
00756  * mechanism.  The returned credential is used to load the appropriate
00757  * client certificate for authentication when requested by a server.
00758  *
00759  * @since New in 1.4.
00760  */
00761 void svn_auth_get_ssl_client_cert_file_provider
00762   (svn_auth_provider_object_t **provider,
00763    apr_pool_t *pool);
00764 
00765 
00766 /** Create and return @a *provider, an authentication provider of type @c
00767  * svn_auth_cred_ssl_client_cert_pw_t, allocated in @a pool.
00768  *
00769  * @a *provider retrieves its credentials from the configuration
00770  * mechanism.  The returned credential is used when a loaded client
00771  * certificate is protected by a passphrase.
00772  *
00773  * @since New in 1.4.
00774  */
00775 void svn_auth_get_ssl_client_cert_pw_file_provider
00776   (svn_auth_provider_object_t **provider,
00777    apr_pool_t *pool);
00778 
00779 
00780 /** Create and return @a *provider, an authentication provider of type @c
00781  * svn_auth_cred_ssl_server_trust_t, allocated in @a pool.
00782  *
00783  * @a *provider retrieves its credentials by using the @a prompt_func
00784  * and @a prompt_baton.  The returned credential is used to override
00785  * SSL security on an error.
00786  *
00787  * @since New in 1.4.
00788  */
00789 void svn_auth_get_ssl_server_trust_prompt_provider
00790   (svn_auth_provider_object_t **provider,
00791    svn_auth_ssl_server_trust_prompt_func_t prompt_func,
00792    void *prompt_baton,
00793    apr_pool_t *pool);
00794 
00795 
00796 /** Create and return @a *provider, an authentication provider of type @c
00797  * svn_auth_cred_ssl_client_cert_t, allocated in @a pool.
00798  *
00799  * @a *provider retrieves its credentials by using the @a prompt_func
00800  * and @a prompt_baton.  The returned credential is used to load the
00801  * appropriate client certificate for authentication when requested by
00802  * a server.  The prompt will be retried @a retry_limit times.
00803  *
00804  * @since New in 1.4.
00805  */
00806 void svn_auth_get_ssl_client_cert_prompt_provider
00807   (svn_auth_provider_object_t **provider,
00808    svn_auth_ssl_client_cert_prompt_func_t prompt_func,
00809    void *prompt_baton,
00810    int retry_limit,
00811    apr_pool_t *pool);
00812 
00813 
00814 /** Create and return @a *provider, an authentication provider of type @c
00815  * svn_auth_cred_ssl_client_cert_pw_t, allocated in @a pool.
00816  *
00817  * @a *provider retrieves its credentials by using the @a prompt_func
00818  * and @a prompt_baton.  The returned credential is used when a loaded
00819  * client certificate is protected by a passphrase.  The prompt will
00820  * be retried @a retry_limit times.
00821  *
00822  * @since New in 1.4.
00823  */
00824 void svn_auth_get_ssl_client_cert_pw_prompt_provider
00825   (svn_auth_provider_object_t **provider,
00826    svn_auth_ssl_client_cert_pw_prompt_func_t prompt_func,
00827    void *prompt_baton,
00828    int retry_limit,
00829    apr_pool_t *pool);
00830 
00831 #ifdef __cplusplus
00832 }
00833 #endif /* __cplusplus */
00834 
00835 #endif /* SVN_AUTH_H */

Generated on Sun Dec 21 19:08:26 2008 for Subversion by  doxygen 1.3.9.1