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 * Property values are const char *.
574 /** Default username provided by the application itself (e.g. --username) */
575 #define SVN_AUTH_PARAM_DEFAULT_USERNAME SVN_AUTH_PARAM_PREFIX "username"
576 /** Default password provided by the application itself (e.g. --password) */
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 /** This provides a pointer to a @c svn_config_t containting the config
633 #define SVN_AUTH_PARAM_CONFIG_CATEGORY_CONFIG SVN_AUTH_PARAM_PREFIX \
634 "config-category-config"
636 /** This provides a pointer to a @c svn_config_t containting the servers
638 #define SVN_AUTH_PARAM_CONFIG_CATEGORY_SERVERS SVN_AUTH_PARAM_PREFIX \
639 "config-category-servers"
641 /** @deprecated Provided for backward compatibility with the 1.5 API. */
642 #define SVN_AUTH_PARAM_CONFIG SVN_AUTH_PARAM_CONFIG_CATEGORY_SERVERS
644 /** The current server group. */
645 #define SVN_AUTH_PARAM_SERVER_GROUP SVN_AUTH_PARAM_PREFIX "server-group"
647 /** @brief A configuration directory that overrides the default
649 #define SVN_AUTH_PARAM_CONFIG_DIR SVN_AUTH_PARAM_PREFIX "config-dir"
651 /** Get an initial set of credentials.
653 * Ask @a auth_baton to set @a *credentials to a set of credentials
654 * defined by @a cred_kind and valid within @a realmstring, or NULL if
655 * no credentials are available. Otherwise, return an iteration state
656 * in @a *state, so that the caller can call
657 * svn_auth_next_credentials(), in case the first set of credentials
658 * fails to authenticate.
660 * Use @a pool to allocate @a *state, and for temporary allocation.
661 * Note that @a *credentials will be allocated in @a auth_baton's pool.
664 svn_auth_first_credentials(void **credentials,
665 svn_auth_iterstate_t **state,
666 const char *cred_kind,
667 const char *realmstring,
668 svn_auth_baton_t *auth_baton,
671 /** Get another set of credentials, assuming previous ones failed to
674 * Use @a state to fetch a different set of @a *credentials, as a
675 * follow-up to svn_auth_first_credentials() or
676 * svn_auth_next_credentials(). If no more credentials are available,
677 * set @a *credentials to NULL.
679 * Note that @a *credentials will be allocated in @c auth_baton's pool.
682 svn_auth_next_credentials(void **credentials,
683 svn_auth_iterstate_t *state,
686 /** Save a set of credentials.
688 * Ask @a state to store the most recently returned credentials,
689 * presumably because they successfully authenticated.
690 * All allocations should be done in @a pool.
692 * If no credentials were ever returned, do nothing.
695 svn_auth_save_credentials(svn_auth_iterstate_t *state,
698 /** Forget a set (or all) memory-cached credentials.
700 * Remove references (if any) in @a auth_baton to credentials cached
701 * therein. If @a cred_kind and @a realmstring are non-NULL, forget
702 * only the credentials associated with those credential types and
703 * realm. Otherwise @a cred_kind and @a realmstring must both be
704 * NULL, and this function will forget all credentials cached within
707 * @note This function does not affect persisted authentication
708 * credential storage at all. It is merely a way to cause Subversion
709 * to forget about credentials already fetched from a provider,
710 * forcing them to be fetched again later should they be required.
715 svn_auth_forget_credentials(svn_auth_baton_t *auth_baton,
716 const char *cred_kind,
717 const char *realmstring,
722 /** Set @a *provider to an authentication provider of type
723 * svn_auth_cred_simple_t that gets information by prompting the user
724 * with @a prompt_func and @a prompt_baton. Allocate @a *provider in
727 * If both @c SVN_AUTH_PARAM_DEFAULT_USERNAME and
728 * @c SVN_AUTH_PARAM_DEFAULT_PASSWORD are defined as runtime
729 * parameters in the @c auth_baton, then @a *provider will return the
730 * default arguments when svn_auth_first_credentials() is called. If
731 * svn_auth_first_credentials() fails, then @a *provider will
732 * re-prompt @a retry_limit times (via svn_auth_next_credentials()).
733 * For infinite retries, set @a retry_limit to value less than 0.
738 svn_auth_get_simple_prompt_provider(svn_auth_provider_object_t **provider,
739 svn_auth_simple_prompt_func_t prompt_func,
745 /** Set @a *provider to an authentication provider of type @c
746 * svn_auth_cred_username_t that gets information by prompting the
747 * user with @a prompt_func and @a prompt_baton. Allocate @a *provider
750 * If @c SVN_AUTH_PARAM_DEFAULT_USERNAME is defined as a runtime
751 * parameter in the @c auth_baton, then @a *provider will return the
752 * default argument when svn_auth_first_credentials() is called. If
753 * svn_auth_first_credentials() fails, then @a *provider will
754 * re-prompt @a retry_limit times (via svn_auth_next_credentials()).
755 * For infinite retries, set @a retry_limit to value less than 0.
760 svn_auth_get_username_prompt_provider(
761 svn_auth_provider_object_t **provider,
762 svn_auth_username_prompt_func_t prompt_func,
768 /** Set @a *provider to an authentication provider of type @c
769 * svn_auth_cred_simple_t that gets/sets information from the user's
770 * ~/.subversion configuration directory.
772 * If the provider is going to save the password unencrypted, it calls @a
773 * plaintext_prompt_func, passing @a prompt_baton, before saving the
776 * If @a plaintext_prompt_func is NULL it is not called and the answer is
777 * assumed to be TRUE. This matches the deprecated behaviour of storing
778 * unencrypted passwords by default, and is only done this way for backward
779 * compatibility reasons.
780 * Client developers are highly encouraged to provide this callback
781 * to ensure their users are made aware of the fact that their password
782 * is going to be stored unencrypted. In the future, providers may
783 * default to not storing the password unencrypted if this callback is NULL.
785 * Clients can however set the callback to NULL and set
786 * SVN_AUTH_PARAM_STORE_PLAINTEXT_PASSWORDS to SVN_CONFIG_FALSE or
787 * SVN_CONFIG_TRUE to enforce a certain behaviour.
789 * Allocate @a *provider in @a pool.
791 * If a default username or password is available, @a *provider will
792 * honor them as well, and return them when
793 * svn_auth_first_credentials() is called. (see @c
794 * SVN_AUTH_PARAM_DEFAULT_USERNAME and @c
795 * SVN_AUTH_PARAM_DEFAULT_PASSWORD).
800 svn_auth_get_simple_provider2(
801 svn_auth_provider_object_t **provider,
802 svn_auth_plaintext_prompt_func_t plaintext_prompt_func,
806 /** Like svn_auth_get_simple_provider2, but without the ability to
807 * call the svn_auth_plaintext_prompt_func_t callback, and the provider
808 * always assumes that it is allowed to store the password in plaintext.
810 * @deprecated Provided for backwards compatibility with the 1.5 API.
815 svn_auth_get_simple_provider(svn_auth_provider_object_t **provider,
818 /** Set @a *provider to an authentication provider of type @c
819 * svn_auth_provider_object_t, or return @c NULL if the provider is not
820 * available for the requested platform or the requested provider is unknown.
822 * Valid @a provider_name values are: "gnome_keyring", "keychain", "kwallet",
823 * "gpg_agent", and "windows".
825 * Valid @a provider_type values are: "simple", "ssl_client_cert_pw" and
826 * "ssl_server_trust".
828 * Allocate @a *provider in @a pool.
830 * What actually happens is we invoke the appropriate provider function to
831 * supply the @a provider, like so:
833 * svn_auth_get_<name>_<type>_provider(@a provider, @a pool);
838 svn_auth_get_platform_specific_provider(
839 svn_auth_provider_object_t **provider,
840 const char *provider_name,
841 const char *provider_type,
844 /** Set @a *providers to an array of <tt>svn_auth_provider_object_t *</tt>
846 * Only client authentication providers available for the current platform are
847 * returned. Order of the platform-specific authentication providers is
848 * determined by the 'password-stores' configuration option which is retrieved
849 * from @a config. @a config can be NULL.
851 * Create and allocate @a *providers in @a pool.
853 * Default order of the platform-specific authentication providers:
858 * 5. windows-cryptoapi
863 svn_auth_get_platform_specific_client_providers(
864 apr_array_header_t **providers,
865 svn_config_t *config,
868 #if (defined(WIN32) && !defined(__MINGW32__)) || defined(DOXYGEN)
870 * Set @a *provider to an authentication provider of type @c
871 * svn_auth_cred_simple_t that gets/sets information from the user's
872 * ~/.subversion configuration directory. Allocate @a *provider in
875 * This is like svn_auth_get_simple_provider(), except that, when
876 * running on Window 2000 or newer (or any other Windows version that
877 * includes the CryptoAPI), the provider encrypts the password before
878 * storing it to disk. On earlier versions of Windows, the provider
882 * @note This function is only available on Windows.
884 * @note An administrative password reset may invalidate the account's
885 * secret key. This function will detect that situation and behave as
886 * if the password were not cached at all.
889 svn_auth_get_windows_simple_provider(svn_auth_provider_object_t **provider,
893 * Set @a *provider to an authentication provider of type @c
894 * svn_auth_cred_ssl_client_cert_pw_t that gets/sets information from the
895 * user's ~/.subversion configuration directory. Allocate @a *provider in
898 * This is like svn_auth_get_ssl_client_cert_pw_file_provider(), except that
899 * when running on Window 2000 or newer, the provider encrypts the password
900 * before storing it to disk. On earlier versions of Windows, the provider
904 * @note This function is only available on Windows.
906 * @note An administrative password reset may invalidate the account's
907 * secret key. This function will detect that situation and behave as
908 * if the password were not cached at all.
911 svn_auth_get_windows_ssl_client_cert_pw_provider(
912 svn_auth_provider_object_t **provider,
916 * Set @a *provider to an authentication provider of type @c
917 * svn_auth_cred_ssl_server_trust_t, allocated in @a pool.
919 * This provider automatically validates ssl server certificates with
920 * the CryptoApi, like Internet Explorer and the Windows network API do.
921 * This allows the rollout of root certificates via Windows Domain
922 * policies, instead of Subversion specific configuration.
925 * @note This function is only available on Windows.
928 svn_auth_get_windows_ssl_server_trust_provider(
929 svn_auth_provider_object_t **provider,
932 #endif /* WIN32 && !__MINGW32__ || DOXYGEN */
934 #if defined(DARWIN) || defined(DOXYGEN)
936 * Set @a *provider to an authentication provider of type @c
937 * svn_auth_cred_simple_t that gets/sets information from the user's
938 * ~/.subversion configuration directory. Allocate @a *provider in
941 * This is like svn_auth_get_simple_provider(), except that the
942 * password is stored in the Mac OS KeyChain.
945 * @note This function is only available on Mac OS 10.2 and higher.
948 svn_auth_get_keychain_simple_provider(svn_auth_provider_object_t **provider,
952 * Set @a *provider to an authentication provider of type @c
953 * svn_auth_cred_ssl_client_cert_pw_t that gets/sets information from the
954 * user's ~/.subversion configuration directory. Allocate @a *provider in
957 * This is like svn_auth_get_ssl_client_cert_pw_file_provider(), except
958 * that the password is stored in the Mac OS KeyChain.
961 * @note This function is only available on Mac OS 10.2 and higher.
964 svn_auth_get_keychain_ssl_client_cert_pw_provider(
965 svn_auth_provider_object_t **provider,
967 #endif /* DARWIN || DOXYGEN */
969 #if (!defined(DARWIN) && !defined(WIN32)) || defined(DOXYGEN)
970 /** A type of callback function for obtaining the GNOME Keyring password.
972 * In this callback, the client should ask the user for default keyring
973 * @a keyring_name password.
975 * The answer is returned in @a *keyring_password.
976 * @a baton is an implementation-specific closure.
977 * All allocations should be done in @a pool.
981 typedef svn_error_t *(*svn_auth_gnome_keyring_unlock_prompt_func_t)(
982 char **keyring_password,
983 const char *keyring_name,
988 /** libsvn_auth_gnome_keyring-specific run-time parameters. */
990 /** @brief The pointer to function which prompts user for GNOME Keyring
992 * The type of this pointer should be svn_auth_gnome_keyring_unlock_prompt_func_t. */
993 #define SVN_AUTH_PARAM_GNOME_KEYRING_UNLOCK_PROMPT_FUNC "gnome-keyring-unlock-prompt-func"
995 /** @brief The baton which is passed to
996 * @c *SVN_AUTH_PARAM_GNOME_KEYRING_UNLOCK_PROMPT_FUNC. */
997 #define SVN_AUTH_PARAM_GNOME_KEYRING_UNLOCK_PROMPT_BATON "gnome-keyring-unlock-prompt-baton"
1001 * Get libsvn_auth_gnome_keyring version information.
1005 const svn_version_t *
1006 svn_auth_gnome_keyring_version(void);
1010 * Set @a *provider to an authentication provider of type @c
1011 * svn_auth_cred_simple_t that gets/sets information from the user's
1012 * ~/.subversion configuration directory.
1014 * This is like svn_client_get_simple_provider(), except that the
1015 * password is stored in GNOME Keyring.
1017 * If the GNOME Keyring is locked the provider calls
1018 * @c *SVN_AUTH_PARAM_GNOME_KEYRING_UNLOCK_PROMPT_FUNC in order to unlock
1021 * @c SVN_AUTH_PARAM_GNOME_KEYRING_UNLOCK_PROMPT_BATON is passed to
1022 * @c *SVN_AUTH_PARAM_GNOME_KEYRING_UNLOCK_PROMPT_FUNC.
1024 * Allocate @a *provider in @a pool.
1027 * @note This function actually works only on systems with
1028 * libsvn_auth_gnome_keyring and GNOME Keyring installed.
1031 svn_auth_get_gnome_keyring_simple_provider(
1032 svn_auth_provider_object_t **provider,
1037 * Set @a *provider to an authentication provider of type @c
1038 * svn_auth_cred_ssl_client_cert_pw_t that gets/sets information from the
1039 * user's ~/.subversion configuration directory.
1041 * This is like svn_client_get_ssl_client_cert_pw_file_provider(), except
1042 * that the password is stored in GNOME Keyring.
1044 * If the GNOME Keyring is locked the provider calls
1045 * @c *SVN_AUTH_PARAM_GNOME_KEYRING_UNLOCK_PROMPT_FUNC in order to unlock
1048 * @c SVN_AUTH_PARAM_GNOME_KEYRING_UNLOCK_PROMPT_BATON is passed to
1049 * @c *SVN_AUTH_PARAM_GNOME_KEYRING_UNLOCK_PROMPT_FUNC.
1051 * Allocate @a *provider in @a pool.
1054 * @note This function actually works only on systems with
1055 * libsvn_auth_gnome_keyring and GNOME Keyring installed.
1058 svn_auth_get_gnome_keyring_ssl_client_cert_pw_provider(
1059 svn_auth_provider_object_t **provider,
1064 * Get libsvn_auth_kwallet version information.
1068 const svn_version_t *
1069 svn_auth_kwallet_version(void);
1073 * Set @a *provider to an authentication provider of type @c
1074 * svn_auth_cred_simple_t that gets/sets information from the user's
1075 * ~/.subversion configuration directory. Allocate @a *provider in
1078 * This is like svn_client_get_simple_provider(), except that the
1079 * password is stored in KWallet.
1082 * @note This function actually works only on systems with libsvn_auth_kwallet
1083 * and KWallet installed.
1086 svn_auth_get_kwallet_simple_provider(svn_auth_provider_object_t **provider,
1091 * Set @a *provider to an authentication provider of type @c
1092 * svn_auth_cred_ssl_client_cert_pw_t that gets/sets information from the
1093 * user's ~/.subversion configuration directory. Allocate @a *provider in
1096 * This is like svn_client_get_ssl_client_cert_pw_file_provider(), except
1097 * that the password is stored in KWallet.
1100 * @note This function actually works only on systems with libsvn_auth_kwallet
1101 * and KWallet installed.
1104 svn_auth_get_kwallet_ssl_client_cert_pw_provider(
1105 svn_auth_provider_object_t **provider,
1107 #endif /* (!DARWIN && !WIN32) || DOXYGEN */
1109 #if !defined(WIN32) || defined(DOXYGEN)
1111 * Set @a *provider to an authentication provider of type @c
1112 * svn_auth_cred_simple_t that gets/sets information from the user's
1113 * ~/.subversion configuration directory.
1115 * This is like svn_client_get_simple_provider(), except that the
1116 * password is obtained from gpg_agent, which will keep it in
1119 * Allocate @a *provider in @a pool.
1122 * @note This function actually works only on systems with
1123 * GNU Privacy Guard installed.
1126 svn_auth_get_gpg_agent_simple_provider
1127 (svn_auth_provider_object_t **provider,
1129 #endif /* !defined(WIN32) || defined(DOXYGEN) */
1132 /** Set @a *provider to an authentication provider of type @c
1133 * svn_auth_cred_username_t that gets/sets information from a user's
1134 * ~/.subversion configuration directory. Allocate @a *provider in
1137 * If a default username is available, @a *provider will honor it,
1138 * and return it when svn_auth_first_credentials() is called. (See
1139 * @c SVN_AUTH_PARAM_DEFAULT_USERNAME.)
1141 * @since New in 1.4.
1144 svn_auth_get_username_provider(svn_auth_provider_object_t **provider,
1148 /** Set @a *provider to an authentication provider of type @c
1149 * svn_auth_cred_ssl_server_trust_t, allocated in @a pool.
1151 * @a *provider retrieves its credentials from the configuration
1152 * mechanism. The returned credential is used to override SSL
1153 * security on an error.
1155 * @since New in 1.4.
1158 svn_auth_get_ssl_server_trust_file_provider(
1159 svn_auth_provider_object_t **provider,
1162 /** Set @a *provider to an authentication provider of type @c
1163 * svn_auth_cred_ssl_client_cert_t, allocated in @a pool.
1165 * @a *provider retrieves its credentials from the configuration
1166 * mechanism. The returned credential is used to load the appropriate
1167 * client certificate for authentication when requested by a server.
1169 * @since New in 1.4.
1172 svn_auth_get_ssl_client_cert_file_provider(
1173 svn_auth_provider_object_t **provider,
1177 /** Set @a *provider to an authentication provider of type @c
1178 * svn_auth_cred_ssl_client_cert_pw_t that gets/sets information from the user's
1179 * ~/.subversion configuration directory.
1181 * If the provider is going to save the passphrase unencrypted,
1182 * it calls @a plaintext_passphrase_prompt_func, passing @a
1183 * prompt_baton, before saving the passphrase.
1185 * If @a plaintext_passphrase_prompt_func is NULL it is not called
1186 * and the passphrase is not stored in plaintext.
1187 * Client developers are highly encouraged to provide this callback
1188 * to ensure their users are made aware of the fact that their passphrase
1189 * is going to be stored unencrypted.
1191 * Clients can however set the callback to NULL and set
1192 * SVN_AUTH_PARAM_STORE_SSL_CLIENT_CERT_PP_PLAINTEXT to SVN_CONFIG_FALSE or
1193 * SVN_CONFIG_TRUE to enforce a certain behaviour.
1195 * Allocate @a *provider in @a pool.
1197 * @since New in 1.6.
1200 svn_auth_get_ssl_client_cert_pw_file_provider2(
1201 svn_auth_provider_object_t **provider,
1202 svn_auth_plaintext_passphrase_prompt_func_t plaintext_passphrase_prompt_func,
1206 /** Like svn_auth_get_ssl_client_cert_pw_file_provider2, but without
1207 * the ability to call the svn_auth_plaintext_passphrase_prompt_func_t
1208 * callback, and the provider always assumes that it is not allowed
1209 * to store the passphrase in plaintext.
1211 * @deprecated Provided for backwards compatibility with the 1.5 API.
1212 * @since New in 1.4.
1216 svn_auth_get_ssl_client_cert_pw_file_provider(
1217 svn_auth_provider_object_t **provider,
1221 /** Set @a *provider to an authentication provider of type @c
1222 * svn_auth_cred_ssl_server_trust_t, allocated in @a pool.
1224 * @a *provider retrieves its credentials by using the @a prompt_func
1225 * and @a prompt_baton. The returned credential is used to override
1226 * SSL security on an error.
1228 * @since New in 1.4.
1231 svn_auth_get_ssl_server_trust_prompt_provider(
1232 svn_auth_provider_object_t **provider,
1233 svn_auth_ssl_server_trust_prompt_func_t prompt_func,
1238 /** Set @a *provider to an authentication provider of type @c
1239 * svn_auth_cred_ssl_client_cert_t, allocated in @a pool.
1241 * @a *provider retrieves its credentials by using the @a prompt_func
1242 * and @a prompt_baton. The returned credential is used to load the
1243 * appropriate client certificate for authentication when requested by
1244 * a server. The prompt will be retried @a retry_limit times. For
1245 * infinite retries, set @a retry_limit to value less than 0.
1247 * @since New in 1.4.
1250 svn_auth_get_ssl_client_cert_prompt_provider(
1251 svn_auth_provider_object_t **provider,
1252 svn_auth_ssl_client_cert_prompt_func_t prompt_func,
1258 /** Set @a *provider to an authentication provider of type @c
1259 * svn_auth_cred_ssl_client_cert_pw_t, allocated in @a pool.
1261 * @a *provider retrieves its credentials by using the @a prompt_func
1262 * and @a prompt_baton. The returned credential is used when a loaded
1263 * client certificate is protected by a passphrase. The prompt will
1264 * be retried @a retry_limit times. For infinite retries, set
1265 * @a retry_limit to value less than 0.
1267 * @since New in 1.4.
1270 svn_auth_get_ssl_client_cert_pw_prompt_provider(
1271 svn_auth_provider_object_t **provider,
1272 svn_auth_ssl_client_cert_pw_prompt_func_t prompt_func,
1280 #endif /* __cplusplus */
1282 #endif /* SVN_AUTH_H */