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