3 * ====================================================================
4 * Licensed to the Apache Software Foundation (ASF) under one
5 * or more contributor license agreements. See the NOTICE file
6 * distributed with this work for additional information
7 * regarding copyright ownership. The ASF licenses this file
8 * to you under the Apache License, Version 2.0 (the
9 * "License"); you may not use this file except in compliance
10 * with the License. You may obtain a copy of the License at
12 * http://www.apache.org/licenses/LICENSE-2.0
14 * Unless required by applicable law or agreed to in writing,
15 * software distributed under the License is distributed on an
16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17 * KIND, either express or implied. See the License for the
18 * specific language governing permissions and limitations
20 * ====================================================================
24 * @brief Subversion's authentication system
31 #include <apr_pools.h>
33 #include <apr_tables.h>
35 #include "svn_types.h"
36 #include "svn_config.h"
40 #endif /* __cplusplus */
42 /** Overview of the svn authentication system.
44 * We define an authentication "provider" as a module that is able to
45 * return a specific set of credentials. (e.g. username/password,
46 * certificate, etc.) Each provider implements a vtable that
48 * - can fetch initial credentials
49 * - can retry the fetch (or try to fetch something different)
50 * - can store the credentials for future use
52 * For any given type of credentials, there can exist any number of
53 * separate providers -- each provider has a different method of
54 * fetching. (i.e. from a disk store, by prompting the user, etc.)
56 * The application begins by creating an auth baton object, and
57 * "registers" some number of providers with the auth baton, in a
58 * specific order. (For example, it may first register a
59 * username/password provider that looks in disk store, then register
60 * a username/password provider that prompts the user.)
62 * Later on, when any svn library is challenged, it asks the auth
63 * baton for the specific credentials. If the initial credentials
64 * fail to authenticate, the caller keeps requesting new credentials.
65 * Under the hood, libsvn_auth effectively "walks" over each provider
66 * (in order of registry), one at a time, until all the providers have
67 * exhausted all their retry options.
69 * This system allows an application to flexibly define authentication
70 * behaviors (by changing registration order), and very easily write
71 * new authentication providers.
73 * An auth_baton also contains an internal hashtable of run-time
74 * parameters; any provider or library layer can set these run-time
75 * parameters at any time, so that the provider has access to the
76 * data. (For example, certain run-time data may not be available
77 * until an authentication challenge is made.) Each credential type
78 * must document the run-time parameters that are made available to
81 * @defgroup auth_fns Authentication functions
86 /** The type of a Subversion authentication object */
87 typedef struct svn_auth_baton_t svn_auth_baton_t
;
89 /** The type of a Subversion authentication-iteration object */
90 typedef struct svn_auth_iterstate_t svn_auth_iterstate_t
;
93 /** The main authentication "provider" vtable. */
94 typedef struct svn_auth_provider_t
96 /** The kind of credentials this provider knows how to retrieve. */
97 const char *cred_kind
;
99 /** Get an initial set of credentials.
101 * Set @a *credentials to a set of valid credentials within @a
102 * realmstring, or NULL if no credentials are available. Set @a
103 * *iter_baton to context that allows a subsequent call to @c
104 * next_credentials, in case the first credentials fail to
105 * authenticate. @a provider_baton is general context for the
106 * vtable, @a parameters contains any run-time data that the
107 * provider may need, and @a realmstring comes from the
108 * svn_auth_first_credentials() call.
110 svn_error_t
* (*first_credentials
)(void **credentials
,
112 void *provider_baton
,
113 apr_hash_t
*parameters
,
114 const char *realmstring
,
117 /** Get a different set of credentials.
119 * Set @a *credentials to another set of valid credentials (using @a
120 * iter_baton as the context from previous call to first_credentials
121 * or next_credentials). If no more credentials are available, set
122 * @a *credentials to NULL. If the provider only has one set of
123 * credentials, this function pointer should simply be NULL. @a
124 * provider_baton is general context for the vtable, @a parameters
125 * contains any run-time data that the provider may need, and @a
126 * realmstring comes from the svn_auth_first_credentials() call.
128 svn_error_t
* (*next_credentials
)(void **credentials
,
130 void *provider_baton
,
131 apr_hash_t
*parameters
,
132 const char *realmstring
,
135 /** Save credentials.
137 * Store @a credentials for future use. @a provider_baton is
138 * general context for the vtable, and @a parameters contains any
139 * run-time data the provider may need. Set @a *saved to TRUE if
140 * the save happened, or FALSE if not. The provider is not required
141 * to save; if it refuses or is unable to save for non-fatal
142 * reasons, return FALSE. If the provider never saves data, then
143 * this function pointer should simply be NULL. @a realmstring comes
144 * from the svn_auth_first_credentials() call.
146 svn_error_t
* (*save_credentials
)(svn_boolean_t
*saved
,
148 void *provider_baton
,
149 apr_hash_t
*parameters
,
150 const char *realmstring
,
153 } svn_auth_provider_t
;
156 /** A provider object, ready to be put into an array and given to
158 typedef struct svn_auth_provider_object_t
160 const svn_auth_provider_t
*vtable
;
161 void *provider_baton
;
163 } svn_auth_provider_object_t
;
165 /** The type of function returning authentication provider. */
166 typedef void (*svn_auth_simple_provider_func_t
)(
167 svn_auth_provider_object_t
**provider
,
171 /** Specific types of credentials **/
173 /** Simple username/password pair credential kind.
175 * The following auth parameters are available to the providers:
177 * - @c SVN_AUTH_PARAM_CONFIG_CATEGORY_CONFIG (@c svn_config_t*)
178 * - @c SVN_AUTH_PARAM_CONFIG_CATEGORY_SERVERS (@c svn_config_t*)
180 * The following auth parameters may be available to the providers:
182 * - @c SVN_AUTH_PARAM_NO_AUTH_CACHE (@c void*)
183 * - @c SVN_AUTH_PARAM_DEFAULT_USERNAME (@c char*)
184 * - @c SVN_AUTH_PARAM_DEFAULT_PASSWORD (@c char*)
186 #define SVN_AUTH_CRED_SIMPLE "svn.simple"
188 /** @c SVN_AUTH_CRED_SIMPLE credentials. */
189 typedef struct svn_auth_cred_simple_t
192 const char *username
;
194 const char *password
;
195 /** Indicates if the credentials may be saved (to disk). For example, a
196 * GUI prompt implementation with a remember password checkbox shall set
197 * @a may_save to TRUE if the checkbox is checked.
199 svn_boolean_t may_save
;
200 } svn_auth_cred_simple_t
;
203 /** Username credential kind.
205 * The following optional auth parameters are relevant to the providers:
207 * - @c SVN_AUTH_PARAM_NO_AUTH_CACHE (@c void*)
208 * - @c SVN_AUTH_PARAM_DEFAULT_USERNAME (@c char*)
210 #define SVN_AUTH_CRED_USERNAME "svn.username"
212 /** @c SVN_AUTH_CRED_USERNAME credentials. */
213 typedef struct svn_auth_cred_username_t
216 const char *username
;
217 /** Indicates if the credentials may be saved (to disk). For example, a
218 * GUI prompt implementation with a remember username checkbox shall set
219 * @a may_save to TRUE if the checkbox is checked.
221 svn_boolean_t may_save
;
222 } svn_auth_cred_username_t
;
225 /** SSL client certificate credential type.
227 * The following auth parameters are available to the providers:
229 * - @c SVN_AUTH_PARAM_CONFIG_CATEGORY_SERVERS (@c svn_config_t*)
230 * - @c SVN_AUTH_PARAM_SERVER_GROUP (@c char*)
232 * The following optional auth parameters are relevant to the providers:
234 * - @c SVN_AUTH_PARAM_NO_AUTH_CACHE (@c void*)
236 #define SVN_AUTH_CRED_SSL_CLIENT_CERT "svn.ssl.client-cert"
238 /** @c SVN_AUTH_CRED_SSL_CLIENT_CERT credentials. */
239 typedef struct svn_auth_cred_ssl_client_cert_t
241 /** Absolute path to the certificate file */
242 const char *cert_file
;
243 /** Indicates if the credentials may be saved (to disk). For example, a
244 * GUI prompt implementation with a remember certificate checkbox shall
245 * set @a may_save to TRUE if the checkbox is checked.
247 svn_boolean_t may_save
;
248 } svn_auth_cred_ssl_client_cert_t
;
251 /** A function returning an SSL client certificate passphrase provider. */
252 typedef void (*svn_auth_ssl_client_cert_pw_provider_func_t
)(
253 svn_auth_provider_object_t
**provider
,
256 /** SSL client certificate passphrase credential type.
258 * @note The realmstring used with this credential type must be a name that
259 * makes it possible for the user to identify the certificate.
261 * The following auth parameters are available to the providers:
263 * - @c SVN_AUTH_PARAM_CONFIG_CATEGORY_CONFIG (@c svn_config_t*)
264 * - @c SVN_AUTH_PARAM_CONFIG_CATEGORY_SERVERS (@c svn_config_t*)
265 * - @c SVN_AUTH_PARAM_SERVER_GROUP (@c char*)
267 * The following optional auth parameters are relevant to the providers:
269 * - @c SVN_AUTH_PARAM_NO_AUTH_CACHE (@c void*)
271 #define SVN_AUTH_CRED_SSL_CLIENT_CERT_PW "svn.ssl.client-passphrase"
273 /** @c SVN_AUTH_CRED_SSL_CLIENT_CERT_PW credentials. */
274 typedef struct svn_auth_cred_ssl_client_cert_pw_t
276 /** Certificate password */
277 const char *password
;
278 /** Indicates if the credentials may be saved (to disk). For example, a
279 * GUI prompt implementation with a remember password checkbox shall set
280 * @a may_save to TRUE if the checkbox is checked.
282 svn_boolean_t may_save
;
283 } svn_auth_cred_ssl_client_cert_pw_t
;
286 /** SSL server verification credential type.
288 * The following auth parameters are available to the providers:
290 * - @c SVN_AUTH_PARAM_CONFIG_CATEGORY_SERVERS (@c svn_config_t*)
291 * - @c SVN_AUTH_PARAM_SERVER_GROUP (@c char*)
292 * - @c SVN_AUTH_PARAM_SSL_SERVER_FAILURES (@c apr_uint32_t*)
293 * - @c SVN_AUTH_PARAM_SSL_SERVER_CERT_INFO
294 * (@c svn_auth_ssl_server_cert_info_t*)
296 * The following optional auth parameters are relevant to the providers:
298 * - @c SVN_AUTH_PARAM_NO_AUTH_CACHE (@c void*)
300 #define SVN_AUTH_CRED_SSL_SERVER_TRUST "svn.ssl.server"
302 /** SSL server certificate information used by @c
303 * SVN_AUTH_CRED_SSL_SERVER_TRUST providers.
305 typedef struct svn_auth_ssl_server_cert_info_t
308 const char *hostname
;
309 /** ASCII fingerprint */
310 const char *fingerprint
;
311 /** ASCII date from which the certificate is valid */
312 const char *valid_from
;
313 /** ASCII date until which the certificate is valid */
314 const char *valid_until
;
315 /** DN of the certificate issuer */
316 const char *issuer_dname
;
317 /** Base-64 encoded DER certificate representation */
318 const char *ascii_cert
;
319 } svn_auth_ssl_server_cert_info_t
;
322 * Return a deep copy of @a info, allocated in @a pool.
326 svn_auth_ssl_server_cert_info_t
*
327 svn_auth_ssl_server_cert_info_dup(const svn_auth_ssl_server_cert_info_t
*info
,
330 /** @c SVN_AUTH_CRED_SSL_SERVER_TRUST credentials. */
331 typedef struct svn_auth_cred_ssl_server_trust_t
333 /** Indicates if the credentials may be saved (to disk). For example, a
334 * GUI prompt implementation with a checkbox to accept the certificate
335 * permanently shall set @a may_save to TRUE if the checkbox is checked.
337 svn_boolean_t may_save
;
338 /** Bit mask of the accepted failures */
339 apr_uint32_t accepted_failures
;
340 } svn_auth_cred_ssl_server_trust_t
;
344 /** Credential-constructing prompt functions. **/
346 /** These exist so that different client applications can use
347 * different prompt mechanisms to supply the same credentials. For
348 * example, if authentication requires a username and password, a
349 * command-line client's prompting function might prompt first for the
350 * username and then for the password, whereas a GUI client's would
351 * present a single dialog box asking for both, and a telepathic
352 * client's would read all the information directly from the user's
353 * mind. All these prompting functions return the same type of
354 * credential, but the information used to construct the credential is
355 * gathered in an interface-specific way in each case.
358 /** Set @a *cred by prompting the user, allocating @a *cred in @a pool.
359 * @a baton is an implementation-specific closure.
361 * If @a realm is non-NULL, maybe use it in the prompt string.
363 * If @a username is non-NULL, then the user might be prompted only
364 * for a password, but @a *cred would still be filled with both
365 * username and password. For example, a typical usage would be to
366 * pass @a username on the first call, but then leave it NULL for
367 * subsequent calls, on the theory that if credentials failed, it's
368 * as likely to be due to incorrect username as incorrect password.
370 * If @a may_save is FALSE, the auth system does not allow the credentials
371 * to be saved (to disk). A prompt function shall not ask the user if the
372 * credentials shall be saved if @a may_save is FALSE. For example, a GUI
373 * client with a remember password checkbox would grey out the checkbox if
374 * @a may_save is FALSE.
376 typedef svn_error_t
*(*svn_auth_simple_prompt_func_t
)(
377 svn_auth_cred_simple_t
**cred
,
380 const char *username
,
381 svn_boolean_t may_save
,
385 /** Set @a *cred by prompting the user, allocating @a *cred in @a pool.
386 * @a baton is an implementation-specific closure.
388 * If @a realm is non-NULL, maybe use it in the prompt string.
390 * If @a may_save is FALSE, the auth system does not allow the credentials
391 * to be saved (to disk). A prompt function shall not ask the user if the
392 * credentials shall be saved if @a may_save is FALSE. For example, a GUI
393 * client with a remember username checkbox would grey out the checkbox if
394 * @a may_save is FALSE.
396 typedef svn_error_t
*(*svn_auth_username_prompt_func_t
)(
397 svn_auth_cred_username_t
**cred
,
400 svn_boolean_t may_save
,
404 /** @name SSL server certificate failure bits
406 * @note These values are stored in the on disk auth cache by the SSL
407 * server certificate auth provider, so the meaning of these bits must
411 /** Certificate is not yet valid. */
412 #define SVN_AUTH_SSL_NOTYETVALID 0x00000001
413 /** Certificate has expired. */
414 #define SVN_AUTH_SSL_EXPIRED 0x00000002
415 /** Certificate's CN (hostname) does not match the remote hostname. */
416 #define SVN_AUTH_SSL_CNMISMATCH 0x00000004
417 /** @brief Certificate authority is unknown (i.e. not trusted) */
418 #define SVN_AUTH_SSL_UNKNOWNCA 0x00000008
419 /** @brief Other failure. This can happen if an unknown failure occurs
420 * that we do not handle yet. */
421 #define SVN_AUTH_SSL_OTHER 0x40000000
424 /** Set @a *cred by prompting the user, allocating @a *cred in @a pool.
425 * @a baton is an implementation-specific closure.
427 * @a cert_info is a structure describing the server cert that was
428 * presented to the client, and @a failures is a bitmask that
429 * describes exactly why the cert could not be automatically validated,
430 * composed from the constants SVN_AUTH_SSL_* (@c SVN_AUTH_SSL_NOTYETVALID
431 * etc.). @a realm is a string that can be used in the prompt string.
433 * If @a may_save is FALSE, the auth system does not allow the credentials
434 * to be saved (to disk). A prompt function shall not ask the user if the
435 * credentials shall be saved if @a may_save is FALSE. For example, a GUI
436 * client with a trust permanently checkbox would grey out the checkbox if
437 * @a may_save is FALSE.
439 typedef svn_error_t
*(*svn_auth_ssl_server_trust_prompt_func_t
)(
440 svn_auth_cred_ssl_server_trust_t
**cred
,
443 apr_uint32_t failures
,
444 const svn_auth_ssl_server_cert_info_t
*cert_info
,
445 svn_boolean_t may_save
,
449 /** Set @a *cred by prompting the user, allocating @a *cred in @a pool.
450 * @a baton is an implementation-specific closure. @a realm is a string
451 * that can be used in the prompt string.
453 * If @a may_save is FALSE, the auth system does not allow the credentials
454 * to be saved (to disk). A prompt function shall not ask the user if the
455 * credentials shall be saved if @a may_save is FALSE. For example, a GUI
456 * client with a remember certificate checkbox would grey out the checkbox
457 * if @a may_save is FALSE.
459 typedef svn_error_t
*(*svn_auth_ssl_client_cert_prompt_func_t
)(
460 svn_auth_cred_ssl_client_cert_t
**cred
,
463 svn_boolean_t may_save
,
467 /** Set @a *cred by prompting the user, allocating @a *cred in @a pool.
468 * @a baton is an implementation-specific closure. @a realm is a string
469 * identifying the certificate, and can be used in the prompt string.
471 * If @a may_save is FALSE, the auth system does not allow the credentials
472 * to be saved (to disk). A prompt function shall not ask the user if the
473 * credentials shall be saved if @a may_save is FALSE. For example, a GUI
474 * client with a remember password checkbox would grey out the checkbox if
475 * @a may_save is FALSE.
477 typedef svn_error_t
*(*svn_auth_ssl_client_cert_pw_prompt_func_t
)(
478 svn_auth_cred_ssl_client_cert_pw_t
**cred
,
481 svn_boolean_t may_save
,
484 /** A type of callback function for asking whether storing a password to
485 * disk in plaintext is allowed.
487 * In this callback, the client should ask the user whether storing
488 * a password for the realm identified by @a realmstring to disk
489 * in plaintext is allowed.
491 * The answer is returned in @a *may_save_plaintext.
492 * @a baton is an implementation-specific closure.
493 * All allocations should be done in @a pool.
497 typedef svn_error_t
*(*svn_auth_plaintext_prompt_func_t
)(
498 svn_boolean_t
*may_save_plaintext
,
499 const char *realmstring
,
503 /** A type of callback function for asking whether storing a passphrase to
504 * disk in plaintext is allowed.
506 * In this callback, the client should ask the user whether storing
507 * a passphrase for the realm identified by @a realmstring to disk
508 * in plaintext is allowed.
510 * The answer is returned in @a *may_save_plaintext.
511 * @a baton is an implementation-specific closure.
512 * All allocations should be done in @a pool.
516 typedef svn_error_t
*(*svn_auth_plaintext_passphrase_prompt_func_t
)(
517 svn_boolean_t
*may_save_plaintext
,
518 const char *realmstring
,
523 /** Initialize an authentication system.
525 * Return an authentication object in @a *auth_baton (allocated in @a
526 * pool) that represents a particular instance of the svn
527 * authentication system. @a providers is an array of @c
528 * svn_auth_provider_object_t pointers, already allocated in @a pool
529 * and intentionally ordered. These pointers will be stored within @a
530 * *auth_baton, grouped by credential type, and searched in this exact
534 svn_auth_open(svn_auth_baton_t
**auth_baton
,
535 const apr_array_header_t
*providers
,
538 /** Set an authentication run-time parameter.
540 * Store @a name / @a value pair as a run-time parameter in @a
541 * auth_baton, making the data accessible to all providers. @a name
542 * and @a value will NOT be duplicated into the auth_baton's pool.
543 * To delete a run-time parameter, pass NULL for @a value.
546 svn_auth_set_parameter(svn_auth_baton_t
*auth_baton
,
550 /** Get an authentication run-time parameter.
552 * Return a value for run-time parameter @a name from @a auth_baton.
553 * Return NULL if the parameter doesn't exist.
556 svn_auth_get_parameter(svn_auth_baton_t
*auth_baton
,
559 /** Universal run-time parameters, made available to all providers.
561 If you are writing a new provider, then to be a "good citizen",
562 you should notice these global parameters! Note that these
563 run-time params should be treated as read-only by providers; the
564 application is responsible for placing them into the auth_baton
567 /** The auth-hash prefix indicating that the parameter is global. */
568 #define SVN_AUTH_PARAM_PREFIX "svn:auth:"
571 * @name Default credentials defines
572 * Any 'default' credentials that came in through the application itself,
573 * (e.g. --username and --password options). Property values are
576 #define SVN_AUTH_PARAM_DEFAULT_USERNAME SVN_AUTH_PARAM_PREFIX "username"
577 #define SVN_AUTH_PARAM_DEFAULT_PASSWORD SVN_AUTH_PARAM_PREFIX "password"
580 /** @brief The application doesn't want any providers to prompt
581 * users. Property value is irrelevant; only property's existence
583 #define SVN_AUTH_PARAM_NON_INTERACTIVE SVN_AUTH_PARAM_PREFIX "non-interactive"
585 /** @brief The application doesn't want any providers to save passwords
586 * to disk. Property value is irrelevant; only property's existence
588 #define SVN_AUTH_PARAM_DONT_STORE_PASSWORDS SVN_AUTH_PARAM_PREFIX \
589 "dont-store-passwords"
591 /** @brief Indicates whether providers may save passwords to disk in
592 * plaintext. Property value can be either SVN_CONFIG_TRUE,
593 * SVN_CONFIG_FALSE, or SVN_CONFIG_ASK.
596 #define SVN_AUTH_PARAM_STORE_PLAINTEXT_PASSWORDS SVN_AUTH_PARAM_PREFIX \
597 "store-plaintext-passwords"
599 /** @brief The application doesn't want any providers to save passphrase
600 * to disk. Property value is irrelevant; only property's existence
604 #define SVN_AUTH_PARAM_DONT_STORE_SSL_CLIENT_CERT_PP \
605 SVN_AUTH_PARAM_PREFIX "dont-store-ssl-client-cert-pp"
607 /** @brief Indicates whether providers may save passphrase to disk in
608 * plaintext. Property value can be either SVN_CONFIG_TRUE,
609 * SVN_CONFIG_FALSE, or SVN_CONFIG_ASK.
612 #define SVN_AUTH_PARAM_STORE_SSL_CLIENT_CERT_PP_PLAINTEXT \
613 SVN_AUTH_PARAM_PREFIX "store-ssl-client-cert-pp-plaintext"
615 /** @brief The application doesn't want any providers to save credentials
616 * to disk. Property value is irrelevant; only property's existence
618 #define SVN_AUTH_PARAM_NO_AUTH_CACHE SVN_AUTH_PARAM_PREFIX "no-auth-cache"
620 /** @brief The following property is for SSL server cert providers. This
621 * provides a pointer to an @c apr_uint32_t containing the failures
622 * detected by the certificate validator. */
623 #define SVN_AUTH_PARAM_SSL_SERVER_FAILURES SVN_AUTH_PARAM_PREFIX \
626 /** @brief The following property is for SSL server cert providers. This
627 * provides the cert info (svn_auth_ssl_server_cert_info_t). */
628 #define SVN_AUTH_PARAM_SSL_SERVER_CERT_INFO SVN_AUTH_PARAM_PREFIX \
631 /** Some providers need access to the @c svn_config_t configuration. */
632 #define SVN_AUTH_PARAM_CONFIG_CATEGORY_CONFIG SVN_AUTH_PARAM_PREFIX "config-category-config"
633 #define SVN_AUTH_PARAM_CONFIG_CATEGORY_SERVERS SVN_AUTH_PARAM_PREFIX "config-category-servers"
635 /** @deprecated Provided for backward compatibility with the 1.5 API. */
636 #define SVN_AUTH_PARAM_CONFIG SVN_AUTH_PARAM_CONFIG_CATEGORY_SERVERS
638 /** The current server group. */
639 #define SVN_AUTH_PARAM_SERVER_GROUP SVN_AUTH_PARAM_PREFIX "server-group"
641 /** @brief A configuration directory that overrides the default
643 #define SVN_AUTH_PARAM_CONFIG_DIR SVN_AUTH_PARAM_PREFIX "config-dir"
645 /** Get an initial set of credentials.
647 * Ask @a auth_baton to set @a *credentials to a set of credentials
648 * defined by @a cred_kind and valid within @a realmstring, or NULL if
649 * no credentials are available. Otherwise, return an iteration state
650 * in @a *state, so that the caller can call
651 * svn_auth_next_credentials(), in case the first set of credentials
652 * fails to authenticate.
654 * Use @a pool to allocate @a *state, and for temporary allocation.
655 * Note that @a *credentials will be allocated in @a auth_baton's pool.
658 svn_auth_first_credentials(void **credentials
,
659 svn_auth_iterstate_t
**state
,
660 const char *cred_kind
,
661 const char *realmstring
,
662 svn_auth_baton_t
*auth_baton
,
665 /** Get another set of credentials, assuming previous ones failed to
668 * Use @a state to fetch a different set of @a *credentials, as a
669 * follow-up to svn_auth_first_credentials() or
670 * svn_auth_next_credentials(). If no more credentials are available,
671 * set @a *credentials to NULL.
673 * Note that @a *credentials will be allocated in @c auth_baton's pool.
676 svn_auth_next_credentials(void **credentials
,
677 svn_auth_iterstate_t
*state
,
680 /** Save a set of credentials.
682 * Ask @a state to store the most recently returned credentials,
683 * presumably because they successfully authenticated.
684 * All allocations should be done in @a pool.
686 * If no credentials were ever returned, do nothing.
689 svn_auth_save_credentials(svn_auth_iterstate_t
*state
,
692 /** Forget a set (or all) memory-cached credentials.
694 * Remove references (if any) in @a auth_baton to credentials cached
695 * therein. If @a cred_kind and @a realmstring are non-NULL, forget
696 * only the credentials associated with those credential types and
697 * realm. Otherwise @a cred_kind and @a realmstring must both be
698 * NULL, and this function will forget all credentials cached within
701 * @note This function does not affect persisted authentication
702 * credential storage at all. It is merely a way to cause Subversion
703 * to forget about credentials already fetched from a provider,
704 * forcing them to be fetched again later should they be required.
709 svn_auth_forget_credentials(svn_auth_baton_t
*auth_baton
,
710 const char *cred_kind
,
711 const char *realmstring
,
716 /** Set @a *provider to an authentication provider of type
717 * svn_auth_cred_simple_t that gets information by prompting the user
718 * with @a prompt_func and @a prompt_baton. Allocate @a *provider in
721 * If both @c SVN_AUTH_PARAM_DEFAULT_USERNAME and
722 * @c SVN_AUTH_PARAM_DEFAULT_PASSWORD are defined as runtime
723 * parameters in the @c auth_baton, then @a *provider will return the
724 * default arguments when svn_auth_first_credentials() is called. If
725 * svn_auth_first_credentials() fails, then @a *provider will
726 * re-prompt @a retry_limit times (via svn_auth_next_credentials()).
727 * For infinite retries, set @a retry_limit to value less than 0.
732 svn_auth_get_simple_prompt_provider(svn_auth_provider_object_t
**provider
,
733 svn_auth_simple_prompt_func_t prompt_func
,
739 /** Set @a *provider to an authentication provider of type @c
740 * svn_auth_cred_username_t that gets information by prompting the
741 * user with @a prompt_func and @a prompt_baton. Allocate @a *provider
744 * If @c SVN_AUTH_PARAM_DEFAULT_USERNAME is defined as a runtime
745 * parameter in the @c auth_baton, then @a *provider will return the
746 * default argument when svn_auth_first_credentials() is called. If
747 * svn_auth_first_credentials() fails, then @a *provider will
748 * re-prompt @a retry_limit times (via svn_auth_next_credentials()).
749 * For infinite retries, set @a retry_limit to value less than 0.
754 svn_auth_get_username_prompt_provider(
755 svn_auth_provider_object_t
**provider
,
756 svn_auth_username_prompt_func_t prompt_func
,
762 /** Set @a *provider to an authentication provider of type @c
763 * svn_auth_cred_simple_t that gets/sets information from the user's
764 * ~/.subversion configuration directory.
766 * If the provider is going to save the password unencrypted, it calls @a
767 * plaintext_prompt_func, passing @a prompt_baton, before saving the
770 * If @a plaintext_prompt_func is NULL it is not called and the answer is
771 * assumed to be TRUE. This matches the deprecated behaviour of storing
772 * unencrypted passwords by default, and is only done this way for backward
773 * compatibility reasons.
774 * Client developers are highly encouraged to provide this callback
775 * to ensure their users are made aware of the fact that their password
776 * is going to be stored unencrypted. In the future, providers may
777 * default to not storing the password unencrypted if this callback is NULL.
779 * Clients can however set the callback to NULL and set
780 * SVN_AUTH_PARAM_STORE_PLAINTEXT_PASSWORDS to SVN_CONFIG_FALSE or
781 * SVN_CONFIG_TRUE to enforce a certain behaviour.
783 * Allocate @a *provider in @a pool.
785 * If a default username or password is available, @a *provider will
786 * honor them as well, and return them when
787 * svn_auth_first_credentials() is called. (see @c
788 * SVN_AUTH_PARAM_DEFAULT_USERNAME and @c
789 * SVN_AUTH_PARAM_DEFAULT_PASSWORD).
794 svn_auth_get_simple_provider2(
795 svn_auth_provider_object_t
**provider
,
796 svn_auth_plaintext_prompt_func_t plaintext_prompt_func
,
800 /** Like svn_auth_get_simple_provider2, but without the ability to
801 * call the svn_auth_plaintext_prompt_func_t callback, and the provider
802 * always assumes that it is allowed to store the password in plaintext.
804 * @deprecated Provided for backwards compatibility with the 1.5 API.
809 svn_auth_get_simple_provider(svn_auth_provider_object_t
**provider
,
812 /** Set @a *provider to an authentication provider of type @c
813 * svn_auth_provider_object_t, or return @c NULL if the provider is not
814 * available for the requested platform or the requested provider is unknown.
816 * Valid @a provider_name values are: "gnome_keyring", "keychain", "kwallet",
817 * "gpg_agent", and "windows".
819 * Valid @a provider_type values are: "simple", "ssl_client_cert_pw" and
820 * "ssl_server_trust".
822 * Allocate @a *provider in @a pool.
824 * What actually happens is we invoke the appropriate provider function to
825 * supply the @a provider, like so:
827 * svn_auth_get_<name>_<type>_provider(@a provider, @a pool);
832 svn_auth_get_platform_specific_provider(
833 svn_auth_provider_object_t
**provider
,
834 const char *provider_name
,
835 const char *provider_type
,
838 /** Set @a *providers to an array of <tt>svn_auth_provider_object_t *</tt>
840 * Only client authentication providers available for the current platform are
841 * returned. Order of the platform-specific authentication providers is
842 * determined by the 'password-stores' configuration option which is retrieved
843 * from @a config. @a config can be NULL.
845 * Create and allocate @a *providers in @a pool.
847 * Default order of the platform-specific authentication providers:
852 * 5. windows-cryptoapi
857 svn_auth_get_platform_specific_client_providers(
858 apr_array_header_t
**providers
,
859 svn_config_t
*config
,
862 #if (defined(WIN32) && !defined(__MINGW32__)) || defined(DOXYGEN)
864 * Set @a *provider to an authentication provider of type @c
865 * svn_auth_cred_simple_t that gets/sets information from the user's
866 * ~/.subversion configuration directory. Allocate @a *provider in
869 * This is like svn_auth_get_simple_provider(), except that, when
870 * running on Window 2000 or newer (or any other Windows version that
871 * includes the CryptoAPI), the provider encrypts the password before
872 * storing it to disk. On earlier versions of Windows, the provider
876 * @note This function is only available on Windows.
878 * @note An administrative password reset may invalidate the account's
879 * secret key. This function will detect that situation and behave as
880 * if the password were not cached at all.
883 svn_auth_get_windows_simple_provider(svn_auth_provider_object_t
**provider
,
887 * Set @a *provider to an authentication provider of type @c
888 * svn_auth_cred_ssl_client_cert_pw_t that gets/sets information from the
889 * user's ~/.subversion configuration directory. Allocate @a *provider in
892 * This is like svn_auth_get_ssl_client_cert_pw_file_provider(), except that
893 * when running on Window 2000 or newer, the provider encrypts the password
894 * before storing it to disk. On earlier versions of Windows, the provider
898 * @note This function is only available on Windows.
900 * @note An administrative password reset may invalidate the account's
901 * secret key. This function will detect that situation and behave as
902 * if the password were not cached at all.
905 svn_auth_get_windows_ssl_client_cert_pw_provider(
906 svn_auth_provider_object_t
**provider
,
910 * Set @a *provider to an authentication provider of type @c
911 * svn_auth_cred_ssl_server_trust_t, allocated in @a pool.
913 * This provider automatically validates ssl server certificates with
914 * the CryptoApi, like Internet Explorer and the Windows network API do.
915 * This allows the rollout of root certificates via Windows Domain
916 * policies, instead of Subversion specific configuration.
919 * @note This function is only available on Windows.
922 svn_auth_get_windows_ssl_server_trust_provider(
923 svn_auth_provider_object_t
**provider
,
926 #endif /* WIN32 && !__MINGW32__ || DOXYGEN */
928 #if defined(DARWIN) || defined(DOXYGEN)
930 * Set @a *provider to an authentication provider of type @c
931 * svn_auth_cred_simple_t that gets/sets information from the user's
932 * ~/.subversion configuration directory. Allocate @a *provider in
935 * This is like svn_auth_get_simple_provider(), except that the
936 * password is stored in the Mac OS KeyChain.
939 * @note This function is only available on Mac OS 10.2 and higher.
942 svn_auth_get_keychain_simple_provider(svn_auth_provider_object_t
**provider
,
946 * Set @a *provider to an authentication provider of type @c
947 * svn_auth_cred_ssl_client_cert_pw_t that gets/sets information from the
948 * user's ~/.subversion configuration directory. Allocate @a *provider in
951 * This is like svn_auth_get_ssl_client_cert_pw_file_provider(), except
952 * that the password is stored in the Mac OS KeyChain.
955 * @note This function is only available on Mac OS 10.2 and higher.
958 svn_auth_get_keychain_ssl_client_cert_pw_provider(
959 svn_auth_provider_object_t
**provider
,
961 #endif /* DARWIN || DOXYGEN */
963 #if (!defined(DARWIN) && !defined(WIN32)) || defined(DOXYGEN)
964 /** A type of callback function for obtaining the GNOME Keyring password.
966 * In this callback, the client should ask the user for default keyring
967 * @a keyring_name password.
969 * The answer is returned in @a *keyring_password.
970 * @a baton is an implementation-specific closure.
971 * All allocations should be done in @a pool.
975 typedef svn_error_t
*(*svn_auth_gnome_keyring_unlock_prompt_func_t
)(
976 char **keyring_password
,
977 const char *keyring_name
,
982 /** libsvn_auth_gnome_keyring-specific run-time parameters. */
984 /** @brief The pointer to function which prompts user for GNOME Keyring
986 * The type of this pointer should be svn_auth_gnome_keyring_unlock_prompt_func_t. */
987 #define SVN_AUTH_PARAM_GNOME_KEYRING_UNLOCK_PROMPT_FUNC "gnome-keyring-unlock-prompt-func"
989 /** @brief The baton which is passed to
990 * @c *SVN_AUTH_PARAM_GNOME_KEYRING_UNLOCK_PROMPT_FUNC. */
991 #define SVN_AUTH_PARAM_GNOME_KEYRING_UNLOCK_PROMPT_BATON "gnome-keyring-unlock-prompt-baton"
995 * Get libsvn_auth_gnome_keyring version information.
999 const svn_version_t
*
1000 svn_auth_gnome_keyring_version(void);
1004 * Set @a *provider to an authentication provider of type @c
1005 * svn_auth_cred_simple_t that gets/sets information from the user's
1006 * ~/.subversion configuration directory.
1008 * This is like svn_client_get_simple_provider(), except that the
1009 * password is stored in GNOME Keyring.
1011 * If the GNOME Keyring is locked the provider calls
1012 * @c *SVN_AUTH_PARAM_GNOME_KEYRING_UNLOCK_PROMPT_FUNC in order to unlock
1015 * @c SVN_AUTH_PARAM_GNOME_KEYRING_UNLOCK_PROMPT_BATON is passed to
1016 * @c *SVN_AUTH_PARAM_GNOME_KEYRING_UNLOCK_PROMPT_FUNC.
1018 * Allocate @a *provider in @a pool.
1021 * @note This function actually works only on systems with
1022 * libsvn_auth_gnome_keyring and GNOME Keyring installed.
1025 svn_auth_get_gnome_keyring_simple_provider(
1026 svn_auth_provider_object_t
**provider
,
1031 * Set @a *provider to an authentication provider of type @c
1032 * svn_auth_cred_ssl_client_cert_pw_t that gets/sets information from the
1033 * user's ~/.subversion configuration directory.
1035 * This is like svn_client_get_ssl_client_cert_pw_file_provider(), except
1036 * that the password is stored in GNOME Keyring.
1038 * If the GNOME Keyring is locked the provider calls
1039 * @c *SVN_AUTH_PARAM_GNOME_KEYRING_UNLOCK_PROMPT_FUNC in order to unlock
1042 * @c SVN_AUTH_PARAM_GNOME_KEYRING_UNLOCK_PROMPT_BATON is passed to
1043 * @c *SVN_AUTH_PARAM_GNOME_KEYRING_UNLOCK_PROMPT_FUNC.
1045 * Allocate @a *provider in @a pool.
1048 * @note This function actually works only on systems with
1049 * libsvn_auth_gnome_keyring and GNOME Keyring installed.
1052 svn_auth_get_gnome_keyring_ssl_client_cert_pw_provider(
1053 svn_auth_provider_object_t
**provider
,
1058 * Get libsvn_auth_kwallet version information.
1062 const svn_version_t
*
1063 svn_auth_kwallet_version(void);
1067 * Set @a *provider to an authentication provider of type @c
1068 * svn_auth_cred_simple_t that gets/sets information from the user's
1069 * ~/.subversion configuration directory. Allocate @a *provider in
1072 * This is like svn_client_get_simple_provider(), except that the
1073 * password is stored in KWallet.
1076 * @note This function actually works only on systems with libsvn_auth_kwallet
1077 * and KWallet installed.
1080 svn_auth_get_kwallet_simple_provider(svn_auth_provider_object_t
**provider
,
1085 * Set @a *provider to an authentication provider of type @c
1086 * svn_auth_cred_ssl_client_cert_pw_t that gets/sets information from the
1087 * user's ~/.subversion configuration directory. Allocate @a *provider in
1090 * This is like svn_client_get_ssl_client_cert_pw_file_provider(), except
1091 * that the password is stored in KWallet.
1094 * @note This function actually works only on systems with libsvn_auth_kwallet
1095 * and KWallet installed.
1098 svn_auth_get_kwallet_ssl_client_cert_pw_provider(
1099 svn_auth_provider_object_t
**provider
,
1101 #endif /* (!DARWIN && !WIN32) || DOXYGEN */
1103 #if !defined(WIN32) || defined(DOXYGEN)
1105 * Set @a *provider to an authentication provider of type @c
1106 * svn_auth_cred_simple_t that gets/sets information from the user's
1107 * ~/.subversion configuration directory.
1109 * This is like svn_client_get_simple_provider(), except that the
1110 * password is obtained from gpg_agent, which will keep it in
1113 * Allocate @a *provider in @a pool.
1116 * @note This function actually works only on systems with
1117 * GNU Privacy Guard installed.
1120 svn_auth_get_gpg_agent_simple_provider
1121 (svn_auth_provider_object_t
**provider
,
1123 #endif /* !defined(WIN32) || defined(DOXYGEN) */
1126 /** Set @a *provider to an authentication provider of type @c
1127 * svn_auth_cred_username_t that gets/sets information from a user's
1128 * ~/.subversion configuration directory. Allocate @a *provider in
1131 * If a default username is available, @a *provider will honor it,
1132 * and return it when svn_auth_first_credentials() is called. (See
1133 * @c SVN_AUTH_PARAM_DEFAULT_USERNAME.)
1135 * @since New in 1.4.
1138 svn_auth_get_username_provider(svn_auth_provider_object_t
**provider
,
1142 /** Set @a *provider to an authentication provider of type @c
1143 * svn_auth_cred_ssl_server_trust_t, allocated in @a pool.
1145 * @a *provider retrieves its credentials from the configuration
1146 * mechanism. The returned credential is used to override SSL
1147 * security on an error.
1149 * @since New in 1.4.
1152 svn_auth_get_ssl_server_trust_file_provider(
1153 svn_auth_provider_object_t
**provider
,
1156 /** Set @a *provider to an authentication provider of type @c
1157 * svn_auth_cred_ssl_client_cert_t, allocated in @a pool.
1159 * @a *provider retrieves its credentials from the configuration
1160 * mechanism. The returned credential is used to load the appropriate
1161 * client certificate for authentication when requested by a server.
1163 * @since New in 1.4.
1166 svn_auth_get_ssl_client_cert_file_provider(
1167 svn_auth_provider_object_t
**provider
,
1171 /** Set @a *provider to an authentication provider of type @c
1172 * svn_auth_cred_ssl_client_cert_pw_t that gets/sets information from the user's
1173 * ~/.subversion configuration directory.
1175 * If the provider is going to save the passphrase unencrypted,
1176 * it calls @a plaintext_passphrase_prompt_func, passing @a
1177 * prompt_baton, before saving the passphrase.
1179 * If @a plaintext_passphrase_prompt_func is NULL it is not called
1180 * and the passphrase is not stored in plaintext.
1181 * Client developers are highly encouraged to provide this callback
1182 * to ensure their users are made aware of the fact that their passphrase
1183 * is going to be stored unencrypted.
1185 * Clients can however set the callback to NULL and set
1186 * SVN_AUTH_PARAM_STORE_SSL_CLIENT_CERT_PP_PLAINTEXT to SVN_CONFIG_FALSE or
1187 * SVN_CONFIG_TRUE to enforce a certain behaviour.
1189 * Allocate @a *provider in @a pool.
1191 * @since New in 1.6.
1194 svn_auth_get_ssl_client_cert_pw_file_provider2(
1195 svn_auth_provider_object_t
**provider
,
1196 svn_auth_plaintext_passphrase_prompt_func_t plaintext_passphrase_prompt_func
,
1200 /** Like svn_auth_get_ssl_client_cert_pw_file_provider2, but without
1201 * the ability to call the svn_auth_plaintext_passphrase_prompt_func_t
1202 * callback, and the provider always assumes that it is not allowed
1203 * to store the passphrase in plaintext.
1205 * @deprecated Provided for backwards compatibility with the 1.5 API.
1206 * @since New in 1.4.
1210 svn_auth_get_ssl_client_cert_pw_file_provider(
1211 svn_auth_provider_object_t
**provider
,
1215 /** Set @a *provider to an authentication provider of type @c
1216 * svn_auth_cred_ssl_server_trust_t, allocated in @a pool.
1218 * @a *provider retrieves its credentials by using the @a prompt_func
1219 * and @a prompt_baton. The returned credential is used to override
1220 * SSL security on an error.
1222 * @since New in 1.4.
1225 svn_auth_get_ssl_server_trust_prompt_provider(
1226 svn_auth_provider_object_t
**provider
,
1227 svn_auth_ssl_server_trust_prompt_func_t prompt_func
,
1232 /** Set @a *provider to an authentication provider of type @c
1233 * svn_auth_cred_ssl_client_cert_t, allocated in @a pool.
1235 * @a *provider retrieves its credentials by using the @a prompt_func
1236 * and @a prompt_baton. The returned credential is used to load the
1237 * appropriate client certificate for authentication when requested by
1238 * a server. The prompt will be retried @a retry_limit times. For
1239 * infinite retries, set @a retry_limit to value less than 0.
1241 * @since New in 1.4.
1244 svn_auth_get_ssl_client_cert_prompt_provider(
1245 svn_auth_provider_object_t
**provider
,
1246 svn_auth_ssl_client_cert_prompt_func_t prompt_func
,
1252 /** Set @a *provider to an authentication provider of type @c
1253 * svn_auth_cred_ssl_client_cert_pw_t, allocated in @a pool.
1255 * @a *provider retrieves its credentials by using the @a prompt_func
1256 * and @a prompt_baton. The returned credential is used when a loaded
1257 * client certificate is protected by a passphrase. The prompt will
1258 * be retried @a retry_limit times. For infinite retries, set
1259 * @a retry_limit to value less than 0.
1261 * @since New in 1.4.
1264 svn_auth_get_ssl_client_cert_pw_prompt_provider(
1265 svn_auth_provider_object_t
**provider
,
1266 svn_auth_ssl_client_cert_pw_prompt_func_t prompt_func
,
1274 #endif /* __cplusplus */
1276 #endif /* SVN_AUTH_H */