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 */