1251881Speter/**
2251881Speter * @copyright
3251881Speter * ====================================================================
4251881Speter *    Licensed to the Apache Software Foundation (ASF) under one
5251881Speter *    or more contributor license agreements.  See the NOTICE file
6251881Speter *    distributed with this work for additional information
7251881Speter *    regarding copyright ownership.  The ASF licenses this file
8251881Speter *    to you under the Apache License, Version 2.0 (the
9251881Speter *    "License"); you may not use this file except in compliance
10251881Speter *    with the License.  You may obtain a copy of the License at
11251881Speter *
12251881Speter *      http://www.apache.org/licenses/LICENSE-2.0
13251881Speter *
14251881Speter *    Unless required by applicable law or agreed to in writing,
15251881Speter *    software distributed under the License is distributed on an
16251881Speter *    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17251881Speter *    KIND, either express or implied.  See the License for the
18251881Speter *    specific language governing permissions and limitations
19251881Speter *    under the License.
20251881Speter * ====================================================================
21251881Speter * @endcopyright
22251881Speter *
23251881Speter * @file svn_auth.h
24251881Speter * @brief Subversion's authentication system
25251881Speter */
26251881Speter
27251881Speter#ifndef SVN_AUTH_H
28251881Speter#define SVN_AUTH_H
29251881Speter
30251881Speter#include <apr.h>
31251881Speter#include <apr_pools.h>
32251881Speter#include <apr_hash.h>
33251881Speter#include <apr_tables.h>
34251881Speter
35251881Speter#include "svn_types.h"
36251881Speter#include "svn_config.h"
37251881Speter
38251881Speter#ifdef __cplusplus
39251881Speterextern "C" {
40251881Speter#endif /* __cplusplus */
41251881Speter
42251881Speter/** Overview of the svn authentication system.
43251881Speter *
44251881Speter * We define an authentication "provider" as a module that is able to
45251881Speter * return a specific set of credentials. (e.g. username/password,
46251881Speter * certificate, etc.)  Each provider implements a vtable that
47251881Speter *
48251881Speter * - can fetch initial credentials
49251881Speter * - can retry the fetch (or try to fetch something different)
50251881Speter * - can store the credentials for future use
51251881Speter *
52251881Speter * For any given type of credentials, there can exist any number of
53251881Speter * separate providers -- each provider has a different method of
54251881Speter * fetching. (i.e. from a disk store, by prompting the user, etc.)
55251881Speter *
56251881Speter * The application begins by creating an auth baton object, and
57251881Speter * "registers" some number of providers with the auth baton, in a
58251881Speter * specific order.  (For example, it may first register a
59251881Speter * username/password provider that looks in disk store, then register
60251881Speter * a username/password provider that prompts the user.)
61251881Speter *
62251881Speter * Later on, when any svn library is challenged, it asks the auth
63251881Speter * baton for the specific credentials.  If the initial credentials
64251881Speter * fail to authenticate, the caller keeps requesting new credentials.
65251881Speter * Under the hood, libsvn_auth effectively "walks" over each provider
66251881Speter * (in order of registry), one at a time, until all the providers have
67251881Speter * exhausted all their retry options.
68251881Speter *
69251881Speter * This system allows an application to flexibly define authentication
70251881Speter * behaviors (by changing registration order), and very easily write
71251881Speter * new authentication providers.
72251881Speter *
73251881Speter * An auth_baton also contains an internal hashtable of run-time
74251881Speter * parameters; any provider or library layer can set these run-time
75251881Speter * parameters at any time, so that the provider has access to the
76251881Speter * data.  (For example, certain run-time data may not be available
77251881Speter * until an authentication challenge is made.)  Each credential type
78251881Speter * must document the run-time parameters that are made available to
79251881Speter * its providers.
80251881Speter *
81251881Speter * @defgroup auth_fns Authentication functions
82251881Speter * @{
83251881Speter */
84251881Speter
85251881Speter
86251881Speter/** The type of a Subversion authentication object */
87251881Spetertypedef struct svn_auth_baton_t svn_auth_baton_t;
88251881Speter
89251881Speter/** The type of a Subversion authentication-iteration object */
90251881Spetertypedef struct svn_auth_iterstate_t svn_auth_iterstate_t;
91251881Speter
92251881Speter
93251881Speter/** The main authentication "provider" vtable. */
94251881Spetertypedef struct svn_auth_provider_t
95251881Speter{
96251881Speter  /** The kind of credentials this provider knows how to retrieve. */
97251881Speter  const char *cred_kind;
98251881Speter
99251881Speter  /** Get an initial set of credentials.
100251881Speter   *
101251881Speter   * Set @a *credentials to a set of valid credentials within @a
102251881Speter   * realmstring, or NULL if no credentials are available.  Set @a
103251881Speter   * *iter_baton to context that allows a subsequent call to @c
104251881Speter   * next_credentials, in case the first credentials fail to
105251881Speter   * authenticate.  @a provider_baton is general context for the
106251881Speter   * vtable, @a parameters contains any run-time data that the
107251881Speter   * provider may need, and @a realmstring comes from the
108251881Speter   * svn_auth_first_credentials() call.
109251881Speter   */
110251881Speter  svn_error_t * (*first_credentials)(void **credentials,
111251881Speter                                     void **iter_baton,
112251881Speter                                     void *provider_baton,
113251881Speter                                     apr_hash_t *parameters,
114251881Speter                                     const char *realmstring,
115251881Speter                                     apr_pool_t *pool);
116251881Speter
117251881Speter  /** Get a different set of credentials.
118251881Speter   *
119251881Speter   * Set @a *credentials to another set of valid credentials (using @a
120251881Speter   * iter_baton as the context from previous call to first_credentials
121251881Speter   * or next_credentials).  If no more credentials are available, set
122251881Speter   * @a *credentials to NULL.  If the provider only has one set of
123251881Speter   * credentials, this function pointer should simply be NULL. @a
124251881Speter   * provider_baton is general context for the vtable, @a parameters
125251881Speter   * contains any run-time data that the provider may need, and @a
126251881Speter   * realmstring comes from the svn_auth_first_credentials() call.
127251881Speter   */
128251881Speter  svn_error_t * (*next_credentials)(void **credentials,
129251881Speter                                    void *iter_baton,
130251881Speter                                    void *provider_baton,
131251881Speter                                    apr_hash_t *parameters,
132251881Speter                                    const char *realmstring,
133251881Speter                                    apr_pool_t *pool);
134251881Speter
135251881Speter  /** Save credentials.
136251881Speter   *
137251881Speter   * Store @a credentials for future use.  @a provider_baton is
138251881Speter   * general context for the vtable, and @a parameters contains any
139251881Speter   * run-time data the provider may need.  Set @a *saved to TRUE if
140251881Speter   * the save happened, or FALSE if not.  The provider is not required
141251881Speter   * to save; if it refuses or is unable to save for non-fatal
142251881Speter   * reasons, return FALSE.  If the provider never saves data, then
143251881Speter   * this function pointer should simply be NULL. @a realmstring comes
144251881Speter   * from the svn_auth_first_credentials() call.
145251881Speter   */
146251881Speter  svn_error_t * (*save_credentials)(svn_boolean_t *saved,
147251881Speter                                    void *credentials,
148251881Speter                                    void *provider_baton,
149251881Speter                                    apr_hash_t *parameters,
150251881Speter                                    const char *realmstring,
151251881Speter                                    apr_pool_t *pool);
152251881Speter
153251881Speter} svn_auth_provider_t;
154251881Speter
155251881Speter
156251881Speter/** A provider object, ready to be put into an array and given to
157251881Speter    svn_auth_open(). */
158251881Spetertypedef struct svn_auth_provider_object_t
159251881Speter{
160251881Speter  const svn_auth_provider_t *vtable;
161251881Speter  void *provider_baton;
162251881Speter
163251881Speter} svn_auth_provider_object_t;
164251881Speter
165251881Speter/** The type of function returning authentication provider. */
166251881Spetertypedef void (*svn_auth_simple_provider_func_t)(
167251881Speter  svn_auth_provider_object_t **provider,
168251881Speter  apr_pool_t *pool);
169251881Speter
170251881Speter
171251881Speter/** Specific types of credentials **/
172251881Speter
173251881Speter/** Simple username/password pair credential kind.
174251881Speter *
175251881Speter * The following auth parameters are available to the providers:
176251881Speter *
177251881Speter * - @c SVN_AUTH_PARAM_CONFIG_CATEGORY_CONFIG (@c svn_config_t*)
178251881Speter * - @c SVN_AUTH_PARAM_CONFIG_CATEGORY_SERVERS (@c svn_config_t*)
179251881Speter *
180251881Speter * The following auth parameters may be available to the providers:
181251881Speter *
182251881Speter * - @c SVN_AUTH_PARAM_NO_AUTH_CACHE (@c void*)
183251881Speter * - @c SVN_AUTH_PARAM_DEFAULT_USERNAME (@c char*)
184251881Speter * - @c SVN_AUTH_PARAM_DEFAULT_PASSWORD (@c char*)
185251881Speter */
186251881Speter#define SVN_AUTH_CRED_SIMPLE "svn.simple"
187251881Speter
188251881Speter/** @c SVN_AUTH_CRED_SIMPLE credentials. */
189251881Spetertypedef struct svn_auth_cred_simple_t
190251881Speter{
191251881Speter  /** Username */
192251881Speter  const char *username;
193251881Speter  /** Password */
194251881Speter  const char *password;
195251881Speter  /** Indicates if the credentials may be saved (to disk). For example, a
196251881Speter   * GUI prompt implementation with a remember password checkbox shall set
197251881Speter   * @a may_save to TRUE if the checkbox is checked.
198251881Speter   */
199251881Speter  svn_boolean_t may_save;
200251881Speter} svn_auth_cred_simple_t;
201251881Speter
202251881Speter
203251881Speter/** Username credential kind.
204251881Speter *
205251881Speter * The following optional auth parameters are relevant to the providers:
206251881Speter *
207251881Speter * - @c SVN_AUTH_PARAM_NO_AUTH_CACHE (@c void*)
208251881Speter * - @c SVN_AUTH_PARAM_DEFAULT_USERNAME (@c char*)
209251881Speter */
210251881Speter#define SVN_AUTH_CRED_USERNAME "svn.username"
211251881Speter
212251881Speter/** @c SVN_AUTH_CRED_USERNAME credentials. */
213251881Spetertypedef struct svn_auth_cred_username_t
214251881Speter{
215251881Speter  /** Username */
216251881Speter  const char *username;
217251881Speter  /** Indicates if the credentials may be saved (to disk). For example, a
218251881Speter   * GUI prompt implementation with a remember username checkbox shall set
219251881Speter   * @a may_save to TRUE if the checkbox is checked.
220251881Speter   */
221251881Speter  svn_boolean_t may_save;
222251881Speter} svn_auth_cred_username_t;
223251881Speter
224251881Speter
225251881Speter/** SSL client certificate credential type.
226251881Speter *
227251881Speter * The following auth parameters are available to the providers:
228251881Speter *
229251881Speter * - @c SVN_AUTH_PARAM_CONFIG_CATEGORY_SERVERS (@c svn_config_t*)
230251881Speter * - @c SVN_AUTH_PARAM_SERVER_GROUP (@c char*)
231251881Speter *
232251881Speter * The following optional auth parameters are relevant to the providers:
233251881Speter *
234251881Speter * - @c SVN_AUTH_PARAM_NO_AUTH_CACHE (@c void*)
235251881Speter */
236251881Speter#define SVN_AUTH_CRED_SSL_CLIENT_CERT "svn.ssl.client-cert"
237251881Speter
238251881Speter/** @c SVN_AUTH_CRED_SSL_CLIENT_CERT credentials. */
239251881Spetertypedef struct svn_auth_cred_ssl_client_cert_t
240251881Speter{
241251881Speter  /** Absolute path to the certificate file */
242251881Speter  const char *cert_file;
243251881Speter  /** Indicates if the credentials may be saved (to disk). For example, a
244251881Speter   * GUI prompt implementation with a remember certificate checkbox shall
245251881Speter   * set @a may_save to TRUE if the checkbox is checked.
246251881Speter   */
247251881Speter  svn_boolean_t may_save;
248251881Speter} svn_auth_cred_ssl_client_cert_t;
249251881Speter
250251881Speter
251251881Speter/** A function returning an SSL client certificate passphrase provider. */
252251881Spetertypedef void (*svn_auth_ssl_client_cert_pw_provider_func_t)(
253251881Speter  svn_auth_provider_object_t **provider,
254251881Speter  apr_pool_t *pool);
255251881Speter
256251881Speter/** SSL client certificate passphrase credential type.
257251881Speter *
258251881Speter * @note The realmstring used with this credential type must be a name that
259251881Speter * makes it possible for the user to identify the certificate.
260251881Speter *
261251881Speter * The following auth parameters are available to the providers:
262251881Speter *
263251881Speter * - @c SVN_AUTH_PARAM_CONFIG_CATEGORY_CONFIG (@c svn_config_t*)
264251881Speter * - @c SVN_AUTH_PARAM_CONFIG_CATEGORY_SERVERS (@c svn_config_t*)
265251881Speter * - @c SVN_AUTH_PARAM_SERVER_GROUP (@c char*)
266251881Speter *
267251881Speter * The following optional auth parameters are relevant to the providers:
268251881Speter *
269251881Speter * - @c SVN_AUTH_PARAM_NO_AUTH_CACHE (@c void*)
270251881Speter */
271251881Speter#define SVN_AUTH_CRED_SSL_CLIENT_CERT_PW "svn.ssl.client-passphrase"
272251881Speter
273251881Speter/** @c SVN_AUTH_CRED_SSL_CLIENT_CERT_PW credentials. */
274251881Spetertypedef struct svn_auth_cred_ssl_client_cert_pw_t
275251881Speter{
276251881Speter  /** Certificate password */
277251881Speter  const char *password;
278251881Speter  /** Indicates if the credentials may be saved (to disk). For example, a
279251881Speter   * GUI prompt implementation with a remember password checkbox shall set
280251881Speter   * @a may_save to TRUE if the checkbox is checked.
281251881Speter   */
282251881Speter  svn_boolean_t may_save;
283251881Speter} svn_auth_cred_ssl_client_cert_pw_t;
284251881Speter
285251881Speter
286251881Speter/** SSL server verification credential type.
287251881Speter *
288251881Speter * The following auth parameters are available to the providers:
289251881Speter *
290251881Speter * - @c SVN_AUTH_PARAM_CONFIG_CATEGORY_SERVERS (@c svn_config_t*)
291251881Speter * - @c SVN_AUTH_PARAM_SERVER_GROUP (@c char*)
292251881Speter * - @c SVN_AUTH_PARAM_SSL_SERVER_FAILURES (@c apr_uint32_t*)
293251881Speter * - @c SVN_AUTH_PARAM_SSL_SERVER_CERT_INFO
294251881Speter *      (@c svn_auth_ssl_server_cert_info_t*)
295251881Speter *
296251881Speter * The following optional auth parameters are relevant to the providers:
297251881Speter *
298251881Speter * - @c SVN_AUTH_PARAM_NO_AUTH_CACHE (@c void*)
299251881Speter */
300251881Speter#define SVN_AUTH_CRED_SSL_SERVER_TRUST "svn.ssl.server"
301251881Speter
302251881Speter/** SSL server certificate information used by @c
303251881Speter * SVN_AUTH_CRED_SSL_SERVER_TRUST providers.
304251881Speter */
305251881Spetertypedef struct svn_auth_ssl_server_cert_info_t
306251881Speter{
307251881Speter  /** Primary CN */
308251881Speter  const char *hostname;
309251881Speter  /** ASCII fingerprint */
310251881Speter  const char *fingerprint;
311251881Speter  /** ASCII date from which the certificate is valid */
312251881Speter  const char *valid_from;
313251881Speter  /** ASCII date until which the certificate is valid */
314251881Speter  const char *valid_until;
315251881Speter  /** DN of the certificate issuer */
316251881Speter  const char *issuer_dname;
317251881Speter  /** Base-64 encoded DER certificate representation */
318251881Speter  const char *ascii_cert;
319251881Speter} svn_auth_ssl_server_cert_info_t;
320251881Speter
321251881Speter/**
322251881Speter * Return a deep copy of @a info, allocated in @a pool.
323251881Speter *
324251881Speter * @since New in 1.3.
325251881Speter */
326251881Spetersvn_auth_ssl_server_cert_info_t *
327251881Spetersvn_auth_ssl_server_cert_info_dup(const svn_auth_ssl_server_cert_info_t *info,
328251881Speter                                  apr_pool_t *pool);
329251881Speter
330251881Speter/** @c SVN_AUTH_CRED_SSL_SERVER_TRUST credentials. */
331251881Spetertypedef struct svn_auth_cred_ssl_server_trust_t
332251881Speter{
333251881Speter  /** Indicates if the credentials may be saved (to disk). For example, a
334251881Speter   * GUI prompt implementation with a checkbox to accept the certificate
335251881Speter   * permanently shall set @a may_save to TRUE if the checkbox is checked.
336251881Speter   */
337251881Speter  svn_boolean_t may_save;
338251881Speter  /** Bit mask of the accepted failures */
339251881Speter  apr_uint32_t accepted_failures;
340251881Speter} svn_auth_cred_ssl_server_trust_t;
341251881Speter
342251881Speter
343251881Speter
344251881Speter/** Credential-constructing prompt functions. **/
345251881Speter
346251881Speter/** These exist so that different client applications can use
347251881Speter * different prompt mechanisms to supply the same credentials.  For
348251881Speter * example, if authentication requires a username and password, a
349251881Speter * command-line client's prompting function might prompt first for the
350251881Speter * username and then for the password, whereas a GUI client's would
351251881Speter * present a single dialog box asking for both, and a telepathic
352251881Speter * client's would read all the information directly from the user's
353251881Speter * mind.  All these prompting functions return the same type of
354251881Speter * credential, but the information used to construct the credential is
355251881Speter * gathered in an interface-specific way in each case.
356251881Speter */
357251881Speter
358251881Speter/** Set @a *cred by prompting the user, allocating @a *cred in @a pool.
359251881Speter * @a baton is an implementation-specific closure.
360251881Speter *
361251881Speter * If @a realm is non-NULL, maybe use it in the prompt string.
362251881Speter *
363251881Speter * If @a username is non-NULL, then the user might be prompted only
364251881Speter * for a password, but @a *cred would still be filled with both
365251881Speter * username and password.  For example, a typical usage would be to
366251881Speter * pass @a username on the first call, but then leave it NULL for
367251881Speter * subsequent calls, on the theory that if credentials failed, it's
368251881Speter * as likely to be due to incorrect username as incorrect password.
369251881Speter *
370251881Speter * If @a may_save is FALSE, the auth system does not allow the credentials
371251881Speter * to be saved (to disk). A prompt function shall not ask the user if the
372251881Speter * credentials shall be saved if @a may_save is FALSE. For example, a GUI
373251881Speter * client with a remember password checkbox would grey out the checkbox if
374251881Speter * @a may_save is FALSE.
375251881Speter */
376251881Spetertypedef svn_error_t *(*svn_auth_simple_prompt_func_t)(
377251881Speter  svn_auth_cred_simple_t **cred,
378251881Speter  void *baton,
379251881Speter  const char *realm,
380251881Speter  const char *username,
381251881Speter  svn_boolean_t may_save,
382251881Speter  apr_pool_t *pool);
383251881Speter
384251881Speter
385251881Speter/** Set @a *cred by prompting the user, allocating @a *cred in @a pool.
386251881Speter * @a baton is an implementation-specific closure.
387251881Speter *
388251881Speter * If @a realm is non-NULL, maybe use it in the prompt string.
389251881Speter *
390251881Speter * If @a may_save is FALSE, the auth system does not allow the credentials
391251881Speter * to be saved (to disk). A prompt function shall not ask the user if the
392251881Speter * credentials shall be saved if @a may_save is FALSE. For example, a GUI
393251881Speter * client with a remember username checkbox would grey out the checkbox if
394251881Speter * @a may_save is FALSE.
395251881Speter */
396251881Spetertypedef svn_error_t *(*svn_auth_username_prompt_func_t)(
397251881Speter  svn_auth_cred_username_t **cred,
398251881Speter  void *baton,
399251881Speter  const char *realm,
400251881Speter  svn_boolean_t may_save,
401251881Speter  apr_pool_t *pool);
402251881Speter
403251881Speter
404251881Speter/** @name SSL server certificate failure bits
405251881Speter *
406251881Speter * @note These values are stored in the on disk auth cache by the SSL
407251881Speter * server certificate auth provider, so the meaning of these bits must
408251881Speter * not be changed.
409251881Speter * @{
410251881Speter */
411251881Speter/** Certificate is not yet valid. */
412251881Speter#define SVN_AUTH_SSL_NOTYETVALID 0x00000001
413251881Speter/** Certificate has expired. */
414251881Speter#define SVN_AUTH_SSL_EXPIRED     0x00000002
415251881Speter/** Certificate's CN (hostname) does not match the remote hostname. */
416251881Speter#define SVN_AUTH_SSL_CNMISMATCH  0x00000004
417251881Speter/** @brief Certificate authority is unknown (i.e. not trusted) */
418251881Speter#define SVN_AUTH_SSL_UNKNOWNCA   0x00000008
419251881Speter/** @brief Other failure. This can happen if an unknown failure occurs
420251881Speter * that we do not handle yet. */
421251881Speter#define SVN_AUTH_SSL_OTHER       0x40000000
422251881Speter/** @} */
423251881Speter
424251881Speter/** Set @a *cred by prompting the user, allocating @a *cred in @a pool.
425251881Speter * @a baton is an implementation-specific closure.
426251881Speter *
427251881Speter * @a cert_info is a structure describing the server cert that was
428251881Speter * presented to the client, and @a failures is a bitmask that
429251881Speter * describes exactly why the cert could not be automatically validated,
430251881Speter * composed from the constants SVN_AUTH_SSL_* (@c SVN_AUTH_SSL_NOTYETVALID
431251881Speter * etc.).  @a realm is a string that can be used in the prompt string.
432251881Speter *
433251881Speter * If @a may_save is FALSE, the auth system does not allow the credentials
434251881Speter * to be saved (to disk). A prompt function shall not ask the user if the
435251881Speter * credentials shall be saved if @a may_save is FALSE. For example, a GUI
436251881Speter * client with a trust permanently checkbox would grey out the checkbox if
437251881Speter * @a may_save is FALSE.
438251881Speter */
439251881Spetertypedef svn_error_t *(*svn_auth_ssl_server_trust_prompt_func_t)(
440251881Speter  svn_auth_cred_ssl_server_trust_t **cred,
441251881Speter  void *baton,
442251881Speter  const char *realm,
443251881Speter  apr_uint32_t failures,
444251881Speter  const svn_auth_ssl_server_cert_info_t *cert_info,
445251881Speter  svn_boolean_t may_save,
446251881Speter  apr_pool_t *pool);
447251881Speter
448251881Speter
449251881Speter/** Set @a *cred by prompting the user, allocating @a *cred in @a pool.
450251881Speter * @a baton is an implementation-specific closure.  @a realm is a string
451251881Speter * that can be used in the prompt string.
452251881Speter *
453251881Speter * If @a may_save is FALSE, the auth system does not allow the credentials
454251881Speter * to be saved (to disk). A prompt function shall not ask the user if the
455251881Speter * credentials shall be saved if @a may_save is FALSE. For example, a GUI
456251881Speter * client with a remember certificate checkbox would grey out the checkbox
457251881Speter * if @a may_save is FALSE.
458251881Speter */
459251881Spetertypedef svn_error_t *(*svn_auth_ssl_client_cert_prompt_func_t)(
460251881Speter  svn_auth_cred_ssl_client_cert_t **cred,
461251881Speter  void *baton,
462251881Speter  const char *realm,
463251881Speter  svn_boolean_t may_save,
464251881Speter  apr_pool_t *pool);
465251881Speter
466251881Speter
467251881Speter/** Set @a *cred by prompting the user, allocating @a *cred in @a pool.
468251881Speter * @a baton is an implementation-specific closure.  @a realm is a string
469251881Speter * identifying the certificate, and can be used in the prompt string.
470251881Speter *
471251881Speter * If @a may_save is FALSE, the auth system does not allow the credentials
472251881Speter * to be saved (to disk). A prompt function shall not ask the user if the
473251881Speter * credentials shall be saved if @a may_save is FALSE. For example, a GUI
474251881Speter * client with a remember password checkbox would grey out the checkbox if
475251881Speter * @a may_save is FALSE.
476251881Speter */
477251881Spetertypedef svn_error_t *(*svn_auth_ssl_client_cert_pw_prompt_func_t)(
478251881Speter  svn_auth_cred_ssl_client_cert_pw_t **cred,
479251881Speter  void *baton,
480251881Speter  const char *realm,
481251881Speter  svn_boolean_t may_save,
482251881Speter  apr_pool_t *pool);
483251881Speter
484251881Speter/** A type of callback function for asking whether storing a password to
485251881Speter * disk in plaintext is allowed.
486251881Speter *
487251881Speter * In this callback, the client should ask the user whether storing
488251881Speter * a password for the realm identified by @a realmstring to disk
489251881Speter * in plaintext is allowed.
490251881Speter *
491251881Speter * The answer is returned in @a *may_save_plaintext.
492251881Speter * @a baton is an implementation-specific closure.
493251881Speter * All allocations should be done in @a pool.
494251881Speter *
495251881Speter * @since New in 1.6
496251881Speter */
497251881Spetertypedef svn_error_t *(*svn_auth_plaintext_prompt_func_t)(
498251881Speter  svn_boolean_t *may_save_plaintext,
499251881Speter  const char *realmstring,
500251881Speter  void *baton,
501251881Speter  apr_pool_t *pool);
502251881Speter
503251881Speter/** A type of callback function for asking whether storing a passphrase to
504251881Speter * disk in plaintext is allowed.
505251881Speter *
506251881Speter * In this callback, the client should ask the user whether storing
507251881Speter * a passphrase for the realm identified by @a realmstring to disk
508251881Speter * in plaintext is allowed.
509251881Speter *
510251881Speter * The answer is returned in @a *may_save_plaintext.
511251881Speter * @a baton is an implementation-specific closure.
512251881Speter * All allocations should be done in @a pool.
513251881Speter *
514251881Speter * @since New in 1.6
515251881Speter */
516251881Spetertypedef svn_error_t *(*svn_auth_plaintext_passphrase_prompt_func_t)(
517251881Speter  svn_boolean_t *may_save_plaintext,
518251881Speter  const char *realmstring,
519251881Speter  void *baton,
520251881Speter  apr_pool_t *pool);
521251881Speter
522251881Speter
523251881Speter/** Initialize an authentication system.
524251881Speter *
525251881Speter * Return an authentication object in @a *auth_baton (allocated in @a
526251881Speter * pool) that represents a particular instance of the svn
527251881Speter * authentication system.  @a providers is an array of @c
528251881Speter * svn_auth_provider_object_t pointers, already allocated in @a pool
529251881Speter * and intentionally ordered.  These pointers will be stored within @a
530251881Speter * *auth_baton, grouped by credential type, and searched in this exact
531251881Speter * order.
532251881Speter */
533251881Spetervoid
534251881Spetersvn_auth_open(svn_auth_baton_t **auth_baton,
535251881Speter              const apr_array_header_t *providers,
536251881Speter              apr_pool_t *pool);
537251881Speter
538251881Speter/** Set an authentication run-time parameter.
539251881Speter *
540251881Speter * Store @a name / @a value pair as a run-time parameter in @a
541251881Speter * auth_baton, making the data accessible to all providers.  @a name
542251881Speter * and @a value will NOT be duplicated into the auth_baton's pool.
543251881Speter * To delete a run-time parameter, pass NULL for @a value.
544251881Speter */
545251881Spetervoid
546251881Spetersvn_auth_set_parameter(svn_auth_baton_t *auth_baton,
547251881Speter                       const char *name,
548251881Speter                       const void *value);
549251881Speter
550251881Speter/** Get an authentication run-time parameter.
551251881Speter *
552251881Speter * Return a value for run-time parameter @a name from @a auth_baton.
553251881Speter * Return NULL if the parameter doesn't exist.
554251881Speter */
555251881Speterconst void *
556251881Spetersvn_auth_get_parameter(svn_auth_baton_t *auth_baton,
557251881Speter                       const char *name);
558251881Speter
559251881Speter/** Universal run-time parameters, made available to all providers.
560251881Speter
561251881Speter    If you are writing a new provider, then to be a "good citizen",
562251881Speter    you should notice these global parameters!  Note that these
563251881Speter    run-time params should be treated as read-only by providers; the
564251881Speter    application is responsible for placing them into the auth_baton
565251881Speter    hash. */
566251881Speter
567251881Speter/** The auth-hash prefix indicating that the parameter is global. */
568251881Speter#define SVN_AUTH_PARAM_PREFIX "svn:auth:"
569251881Speter
570251881Speter/**
571251881Speter * @name Default credentials defines
572251881Speter * Property values are const char *.
573251881Speter * @{ */
574251881Speter/** Default username provided by the application itself (e.g. --username) */
575251881Speter#define SVN_AUTH_PARAM_DEFAULT_USERNAME  SVN_AUTH_PARAM_PREFIX "username"
576251881Speter/** Default password provided by the application itself (e.g. --password) */
577251881Speter#define SVN_AUTH_PARAM_DEFAULT_PASSWORD  SVN_AUTH_PARAM_PREFIX "password"
578251881Speter/** @} */
579251881Speter
580251881Speter/** @brief The application doesn't want any providers to prompt
581251881Speter * users. Property value is irrelevant; only property's existence
582251881Speter * matters. */
583251881Speter#define SVN_AUTH_PARAM_NON_INTERACTIVE  SVN_AUTH_PARAM_PREFIX "non-interactive"
584251881Speter
585251881Speter/** @brief The application doesn't want any providers to save passwords
586251881Speter * to disk. Property value is irrelevant; only property's existence
587251881Speter * matters. */
588251881Speter#define SVN_AUTH_PARAM_DONT_STORE_PASSWORDS  SVN_AUTH_PARAM_PREFIX \
589251881Speter                                                 "dont-store-passwords"
590251881Speter
591251881Speter/** @brief Indicates whether providers may save passwords to disk in
592251881Speter * plaintext. Property value can be either SVN_CONFIG_TRUE,
593251881Speter * SVN_CONFIG_FALSE, or SVN_CONFIG_ASK.
594251881Speter * @since New in 1.6.
595251881Speter */
596251881Speter#define SVN_AUTH_PARAM_STORE_PLAINTEXT_PASSWORDS  SVN_AUTH_PARAM_PREFIX \
597251881Speter                                                  "store-plaintext-passwords"
598251881Speter
599251881Speter/** @brief The application doesn't want any providers to save passphrase
600251881Speter * to disk. Property value is irrelevant; only property's existence
601251881Speter * matters.
602251881Speter * @since New in 1.6.
603251881Speter */
604251881Speter#define SVN_AUTH_PARAM_DONT_STORE_SSL_CLIENT_CERT_PP \
605251881Speter  SVN_AUTH_PARAM_PREFIX "dont-store-ssl-client-cert-pp"
606251881Speter
607251881Speter/** @brief Indicates whether providers may save passphrase to disk in
608251881Speter * plaintext. Property value can be either SVN_CONFIG_TRUE,
609251881Speter * SVN_CONFIG_FALSE, or SVN_CONFIG_ASK.
610251881Speter * @since New in 1.6.
611251881Speter */
612251881Speter#define SVN_AUTH_PARAM_STORE_SSL_CLIENT_CERT_PP_PLAINTEXT \
613251881Speter  SVN_AUTH_PARAM_PREFIX "store-ssl-client-cert-pp-plaintext"
614251881Speter
615251881Speter/** @brief The application doesn't want any providers to save credentials
616251881Speter * to disk. Property value is irrelevant; only property's existence
617251881Speter * matters. */
618251881Speter#define SVN_AUTH_PARAM_NO_AUTH_CACHE  SVN_AUTH_PARAM_PREFIX "no-auth-cache"
619251881Speter
620251881Speter/** @brief The following property is for SSL server cert providers. This
621251881Speter * provides a pointer to an @c apr_uint32_t containing the failures
622251881Speter * detected by the certificate validator. */
623251881Speter#define SVN_AUTH_PARAM_SSL_SERVER_FAILURES SVN_AUTH_PARAM_PREFIX \
624251881Speter  "ssl:failures"
625251881Speter
626251881Speter/** @brief The following property is for SSL server cert providers. This
627251881Speter * provides the cert info (svn_auth_ssl_server_cert_info_t). */
628251881Speter#define SVN_AUTH_PARAM_SSL_SERVER_CERT_INFO SVN_AUTH_PARAM_PREFIX \
629251881Speter  "ssl:cert-info"
630251881Speter
631251881Speter/** This provides a pointer to a @c svn_config_t containting the config
632251881Speter * category. */
633251881Speter#define SVN_AUTH_PARAM_CONFIG_CATEGORY_CONFIG SVN_AUTH_PARAM_PREFIX \
634251881Speter  "config-category-config"
635251881Speter
636251881Speter/** This provides a pointer to a @c svn_config_t containting the servers
637251881Speter * category. */
638251881Speter#define SVN_AUTH_PARAM_CONFIG_CATEGORY_SERVERS SVN_AUTH_PARAM_PREFIX \
639251881Speter  "config-category-servers"
640251881Speter
641251881Speter/** @deprecated Provided for backward compatibility with the 1.5 API. */
642251881Speter#define SVN_AUTH_PARAM_CONFIG SVN_AUTH_PARAM_CONFIG_CATEGORY_SERVERS
643251881Speter
644251881Speter/** The current server group. */
645251881Speter#define SVN_AUTH_PARAM_SERVER_GROUP SVN_AUTH_PARAM_PREFIX "server-group"
646251881Speter
647251881Speter/** @brief A configuration directory that overrides the default
648251881Speter * ~/.subversion. */
649251881Speter#define SVN_AUTH_PARAM_CONFIG_DIR SVN_AUTH_PARAM_PREFIX "config-dir"
650251881Speter
651251881Speter/** Get an initial set of credentials.
652251881Speter *
653251881Speter * Ask @a auth_baton to set @a *credentials to a set of credentials
654251881Speter * defined by @a cred_kind and valid within @a realmstring, or NULL if
655251881Speter * no credentials are available.  Otherwise, return an iteration state
656251881Speter * in @a *state, so that the caller can call
657251881Speter * svn_auth_next_credentials(), in case the first set of credentials
658251881Speter * fails to authenticate.
659251881Speter *
660251881Speter * Use @a pool to allocate @a *state, and for temporary allocation.
661251881Speter * Note that @a *credentials will be allocated in @a auth_baton's pool.
662251881Speter */
663251881Spetersvn_error_t *
664251881Spetersvn_auth_first_credentials(void **credentials,
665251881Speter                           svn_auth_iterstate_t **state,
666251881Speter                           const char *cred_kind,
667251881Speter                           const char *realmstring,
668251881Speter                           svn_auth_baton_t *auth_baton,
669251881Speter                           apr_pool_t *pool);
670251881Speter
671251881Speter/** Get another set of credentials, assuming previous ones failed to
672251881Speter * authenticate.
673251881Speter *
674251881Speter * Use @a state to fetch a different set of @a *credentials, as a
675251881Speter * follow-up to svn_auth_first_credentials() or
676251881Speter * svn_auth_next_credentials().  If no more credentials are available,
677251881Speter * set @a *credentials to NULL.
678251881Speter *
679251881Speter * Note that @a *credentials will be allocated in @c auth_baton's pool.
680251881Speter */
681251881Spetersvn_error_t *
682251881Spetersvn_auth_next_credentials(void **credentials,
683251881Speter                          svn_auth_iterstate_t *state,
684251881Speter                          apr_pool_t *pool);
685251881Speter
686251881Speter/** Save a set of credentials.
687251881Speter *
688251881Speter * Ask @a state to store the most recently returned credentials,
689251881Speter * presumably because they successfully authenticated.
690251881Speter * All allocations should be done in @a pool.
691251881Speter *
692251881Speter * If no credentials were ever returned, do nothing.
693251881Speter */
694251881Spetersvn_error_t *
695251881Spetersvn_auth_save_credentials(svn_auth_iterstate_t *state,
696251881Speter                          apr_pool_t *pool);
697251881Speter
698251881Speter/** Forget a set (or all) memory-cached credentials.
699251881Speter *
700251881Speter * Remove references (if any) in @a auth_baton to credentials cached
701251881Speter * therein.  If @a cred_kind and @a realmstring are non-NULL, forget
702251881Speter * only the credentials associated with those credential types and
703251881Speter * realm.  Otherwise @a cred_kind and @a realmstring must both be
704251881Speter * NULL, and this function will forget all credentials cached within
705251881Speter * @a auth_baton.
706251881Speter *
707251881Speter * @note This function does not affect persisted authentication
708251881Speter * credential storage at all.  It is merely a way to cause Subversion
709251881Speter * to forget about credentials already fetched from a provider,
710251881Speter * forcing them to be fetched again later should they be required.
711251881Speter *
712251881Speter * @since New in 1.8.
713251881Speter */
714251881Spetersvn_error_t *
715251881Spetersvn_auth_forget_credentials(svn_auth_baton_t *auth_baton,
716251881Speter                            const char *cred_kind,
717251881Speter                            const char *realmstring,
718251881Speter                            apr_pool_t *pool);
719251881Speter
720251881Speter/** @} */
721251881Speter
722251881Speter/** Set @a *provider to an authentication provider of type
723251881Speter * svn_auth_cred_simple_t that gets information by prompting the user
724251881Speter * with @a prompt_func and @a prompt_baton.  Allocate @a *provider in
725251881Speter * @a pool.
726251881Speter *
727251881Speter * If both @c SVN_AUTH_PARAM_DEFAULT_USERNAME and
728251881Speter * @c SVN_AUTH_PARAM_DEFAULT_PASSWORD are defined as runtime
729251881Speter * parameters in the @c auth_baton, then @a *provider will return the
730251881Speter * default arguments when svn_auth_first_credentials() is called.  If
731251881Speter * svn_auth_first_credentials() fails, then @a *provider will
732251881Speter * re-prompt @a retry_limit times (via svn_auth_next_credentials()).
733251881Speter * For infinite retries, set @a retry_limit to value less than 0.
734251881Speter *
735251881Speter * @since New in 1.4.
736251881Speter */
737251881Spetervoid
738251881Spetersvn_auth_get_simple_prompt_provider(svn_auth_provider_object_t **provider,
739251881Speter                                    svn_auth_simple_prompt_func_t prompt_func,
740251881Speter                                    void *prompt_baton,
741251881Speter                                    int retry_limit,
742251881Speter                                    apr_pool_t *pool);
743251881Speter
744251881Speter
745251881Speter/** Set @a *provider to an authentication provider of type @c
746251881Speter * svn_auth_cred_username_t that gets information by prompting the
747251881Speter * user with @a prompt_func and @a prompt_baton.  Allocate @a *provider
748251881Speter * in @a pool.
749251881Speter *
750251881Speter * If @c SVN_AUTH_PARAM_DEFAULT_USERNAME is defined as a runtime
751251881Speter * parameter in the @c auth_baton, then @a *provider will return the
752251881Speter * default argument when svn_auth_first_credentials() is called.  If
753251881Speter * svn_auth_first_credentials() fails, then @a *provider will
754251881Speter * re-prompt @a retry_limit times (via svn_auth_next_credentials()).
755251881Speter * For infinite retries, set @a retry_limit to value less than 0.
756251881Speter *
757251881Speter * @since New in 1.4.
758251881Speter */
759251881Spetervoid
760251881Spetersvn_auth_get_username_prompt_provider(
761251881Speter  svn_auth_provider_object_t **provider,
762251881Speter  svn_auth_username_prompt_func_t prompt_func,
763251881Speter  void *prompt_baton,
764251881Speter  int retry_limit,
765251881Speter  apr_pool_t *pool);
766251881Speter
767251881Speter
768251881Speter/** Set @a *provider to an authentication provider of type @c
769251881Speter * svn_auth_cred_simple_t that gets/sets information from the user's
770251881Speter * ~/.subversion configuration directory.
771251881Speter *
772251881Speter * If the provider is going to save the password unencrypted, it calls @a
773251881Speter * plaintext_prompt_func, passing @a prompt_baton, before saving the
774251881Speter * password.
775251881Speter *
776251881Speter * If @a plaintext_prompt_func is NULL it is not called and the answer is
777251881Speter * assumed to be TRUE. This matches the deprecated behaviour of storing
778251881Speter * unencrypted passwords by default, and is only done this way for backward
779251881Speter * compatibility reasons.
780251881Speter * Client developers are highly encouraged to provide this callback
781251881Speter * to ensure their users are made aware of the fact that their password
782251881Speter * is going to be stored unencrypted. In the future, providers may
783251881Speter * default to not storing the password unencrypted if this callback is NULL.
784251881Speter *
785251881Speter * Clients can however set the callback to NULL and set
786251881Speter * SVN_AUTH_PARAM_STORE_PLAINTEXT_PASSWORDS to SVN_CONFIG_FALSE or
787251881Speter * SVN_CONFIG_TRUE to enforce a certain behaviour.
788251881Speter *
789251881Speter * Allocate @a *provider in @a pool.
790251881Speter *
791251881Speter * If a default username or password is available, @a *provider will
792251881Speter * honor them as well, and return them when
793251881Speter * svn_auth_first_credentials() is called.  (see @c
794251881Speter * SVN_AUTH_PARAM_DEFAULT_USERNAME and @c
795251881Speter * SVN_AUTH_PARAM_DEFAULT_PASSWORD).
796251881Speter *
797251881Speter * @since New in 1.6.
798251881Speter */
799251881Spetervoid
800251881Spetersvn_auth_get_simple_provider2(
801251881Speter  svn_auth_provider_object_t **provider,
802251881Speter  svn_auth_plaintext_prompt_func_t plaintext_prompt_func,
803251881Speter  void *prompt_baton,
804251881Speter  apr_pool_t *pool);
805251881Speter
806251881Speter/** Like svn_auth_get_simple_provider2, but without the ability to
807251881Speter * call the svn_auth_plaintext_prompt_func_t callback, and the provider
808251881Speter * always assumes that it is allowed to store the password in plaintext.
809251881Speter *
810251881Speter * @deprecated Provided for backwards compatibility with the 1.5 API.
811251881Speter * @since New in 1.4.
812251881Speter */
813251881SpeterSVN_DEPRECATED
814251881Spetervoid
815251881Spetersvn_auth_get_simple_provider(svn_auth_provider_object_t **provider,
816251881Speter                             apr_pool_t *pool);
817251881Speter
818251881Speter/** Set @a *provider to an authentication provider of type @c
819251881Speter * svn_auth_provider_object_t, or return @c NULL if the provider is not
820251881Speter * available for the requested platform or the requested provider is unknown.
821251881Speter *
822251881Speter * Valid @a provider_name values are: "gnome_keyring", "keychain", "kwallet",
823251881Speter * "gpg_agent", and "windows".
824251881Speter *
825251881Speter * Valid @a provider_type values are: "simple", "ssl_client_cert_pw" and
826251881Speter * "ssl_server_trust".
827251881Speter *
828251881Speter * Allocate @a *provider in @a pool.
829251881Speter *
830251881Speter * What actually happens is we invoke the appropriate provider function to
831251881Speter * supply the @a provider, like so:
832251881Speter *
833251881Speter *    svn_auth_get_<name>_<type>_provider(@a provider, @a pool);
834251881Speter *
835251881Speter * @since New in 1.6.
836251881Speter */
837251881Spetersvn_error_t *
838251881Spetersvn_auth_get_platform_specific_provider(
839251881Speter  svn_auth_provider_object_t **provider,
840251881Speter  const char *provider_name,
841251881Speter  const char *provider_type,
842251881Speter  apr_pool_t *pool);
843251881Speter
844251881Speter/** Set @a *providers to an array of <tt>svn_auth_provider_object_t *</tt>
845251881Speter * objects.
846251881Speter * Only client authentication providers available for the current platform are
847251881Speter * returned. Order of the platform-specific authentication providers is
848251881Speter * determined by the 'password-stores' configuration option which is retrieved
849251881Speter * from @a config. @a config can be NULL.
850251881Speter *
851251881Speter * Create and allocate @a *providers in @a pool.
852251881Speter *
853251881Speter * Default order of the platform-specific authentication providers:
854251881Speter *   1. gnome-keyring
855251881Speter *   2. kwallet
856251881Speter *   3. keychain
857251881Speter *   4. gpg-agent
858251881Speter *   5. windows-cryptoapi
859251881Speter *
860251881Speter * @since New in 1.6.
861251881Speter */
862251881Spetersvn_error_t *
863251881Spetersvn_auth_get_platform_specific_client_providers(
864251881Speter  apr_array_header_t **providers,
865251881Speter  svn_config_t *config,
866251881Speter  apr_pool_t *pool);
867251881Speter
868251881Speter#if (defined(WIN32) && !defined(__MINGW32__)) || defined(DOXYGEN)
869251881Speter/**
870251881Speter * Set @a *provider to an authentication provider of type @c
871251881Speter * svn_auth_cred_simple_t that gets/sets information from the user's
872251881Speter * ~/.subversion configuration directory.  Allocate @a *provider in
873251881Speter * @a pool.
874251881Speter *
875251881Speter * This is like svn_auth_get_simple_provider(), except that, when
876251881Speter * running on Window 2000 or newer (or any other Windows version that
877251881Speter * includes the CryptoAPI), the provider encrypts the password before
878251881Speter * storing it to disk. On earlier versions of Windows, the provider
879251881Speter * does nothing.
880251881Speter *
881251881Speter * @since New in 1.4.
882251881Speter * @note This function is only available on Windows.
883251881Speter *
884251881Speter * @note An administrative password reset may invalidate the account's
885251881Speter * secret key. This function will detect that situation and behave as
886251881Speter * if the password were not cached at all.
887299742Sdim * @deprecated Provided for backwards compatibility with the 1.8 API.  Use
888299742Sdim * svn_auth_get_platform_specific_provider with provider_name of "windows"
889299742Sdim * and provider_type of "simple".
890251881Speter */
891299742SdimSVN_DEPRECATED
892251881Spetervoid
893251881Spetersvn_auth_get_windows_simple_provider(svn_auth_provider_object_t **provider,
894251881Speter                                     apr_pool_t *pool);
895251881Speter
896251881Speter/**
897251881Speter * Set @a *provider to an authentication provider of type @c
898251881Speter * svn_auth_cred_ssl_client_cert_pw_t that gets/sets information from the
899251881Speter * user's ~/.subversion configuration directory.  Allocate @a *provider in
900251881Speter * @a pool.
901251881Speter *
902251881Speter * This is like svn_auth_get_ssl_client_cert_pw_file_provider(), except that
903251881Speter * when running on Window 2000 or newer, the provider encrypts the password
904251881Speter * before storing it to disk. On earlier versions of Windows, the provider
905251881Speter * does nothing.
906251881Speter *
907251881Speter * @since New in 1.6
908251881Speter * @note This function is only available on Windows.
909251881Speter *
910251881Speter * @note An administrative password reset may invalidate the account's
911251881Speter * secret key. This function will detect that situation and behave as
912251881Speter * if the password were not cached at all.
913299742Sdim * @deprecated Provided for backwards compatibility with the 1.8 API.
914299742Sdim * Use svn_auth_get_platform_specific_provider with provider_name
915299742Sdim * of "windows" and provider_type of "ssl_client_cert_pw".
916251881Speter */
917299742SdimSVN_DEPRECATED
918251881Spetervoid
919251881Spetersvn_auth_get_windows_ssl_client_cert_pw_provider(
920251881Speter  svn_auth_provider_object_t **provider,
921251881Speter  apr_pool_t *pool);
922251881Speter
923251881Speter/**
924251881Speter * Set @a *provider to an authentication provider of type @c
925251881Speter * svn_auth_cred_ssl_server_trust_t, allocated in @a pool.
926251881Speter *
927251881Speter * This provider automatically validates ssl server certificates with
928251881Speter * the CryptoApi, like Internet Explorer and the Windows network API do.
929251881Speter * This allows the rollout of root certificates via Windows Domain
930251881Speter * policies, instead of Subversion specific configuration.
931251881Speter *
932251881Speter * @since New in 1.5.
933251881Speter * @note This function is only available on Windows.
934299742Sdim * @deprecated Provided for backwards compatibility with the 1.8 API.
935299742Sdim * Use svn_auth_get_platform_specific_provider with provider_name
936299742Sdim * of "windows" and provider_type of "ssl_server_trust".
937251881Speter */
938299742SdimSVN_DEPRECATED
939251881Spetervoid
940251881Spetersvn_auth_get_windows_ssl_server_trust_provider(
941251881Speter  svn_auth_provider_object_t **provider,
942251881Speter  apr_pool_t *pool);
943251881Speter
944251881Speter#endif /* WIN32 && !__MINGW32__ || DOXYGEN */
945251881Speter
946251881Speter#if defined(DARWIN) || defined(DOXYGEN)
947251881Speter/**
948251881Speter * Set @a *provider to an authentication provider of type @c
949251881Speter * svn_auth_cred_simple_t that gets/sets information from the user's
950251881Speter * ~/.subversion configuration directory.  Allocate @a *provider in
951251881Speter * @a pool.
952251881Speter *
953251881Speter * This is like svn_auth_get_simple_provider(), except that the
954251881Speter * password is stored in the Mac OS KeyChain.
955251881Speter *
956251881Speter * @since New in 1.4
957251881Speter * @note This function is only available on Mac OS 10.2 and higher.
958299742Sdim * @deprecated Provided for backwards compatibility with the 1.8 API.
959299742Sdim * Use svn_auth_get_platform_specific_provider with provider_name
960299742Sdim * of "keychain" and provider_type of "simple".
961251881Speter */
962299742SdimSVN_DEPRECATED
963251881Spetervoid
964251881Spetersvn_auth_get_keychain_simple_provider(svn_auth_provider_object_t **provider,
965251881Speter                                      apr_pool_t *pool);
966251881Speter
967251881Speter/**
968251881Speter * Set @a *provider to an authentication provider of type @c
969251881Speter * svn_auth_cred_ssl_client_cert_pw_t that gets/sets information from the
970251881Speter * user's ~/.subversion configuration directory.  Allocate @a *provider in
971251881Speter * @a pool.
972251881Speter *
973251881Speter * This is like svn_auth_get_ssl_client_cert_pw_file_provider(), except
974251881Speter * that the password is stored in the Mac OS KeyChain.
975251881Speter *
976251881Speter * @since New in 1.6
977251881Speter * @note This function is only available on Mac OS 10.2 and higher.
978299742Sdim * @deprecated Provided for backwards compatibility with the 1.8 API.
979299742Sdim * Use svn_auth_get_platform_specific_provider with provider_name
980299742Sdim * of "keychain" and provider_type of "ssl_client_cert_pw".
981251881Speter */
982299742SdimSVN_DEPRECATED
983251881Spetervoid
984251881Spetersvn_auth_get_keychain_ssl_client_cert_pw_provider(
985251881Speter  svn_auth_provider_object_t **provider,
986251881Speter  apr_pool_t *pool);
987251881Speter#endif /* DARWIN || DOXYGEN */
988251881Speter
989262253Speter/* Note that the gnome keyring unlock prompt related items below must be
990262253Speter * declared for all platforms in order to allow SWIG interfaces to be
991262253Speter * used regardless of the platform. */
992262253Speter
993251881Speter/** A type of callback function for obtaining the GNOME Keyring password.
994251881Speter *
995251881Speter * In this callback, the client should ask the user for default keyring
996251881Speter * @a keyring_name password.
997251881Speter *
998251881Speter * The answer is returned in @a *keyring_password.
999251881Speter * @a baton is an implementation-specific closure.
1000251881Speter * All allocations should be done in @a pool.
1001251881Speter *
1002251881Speter * @since New in 1.6
1003251881Speter */
1004251881Spetertypedef svn_error_t *(*svn_auth_gnome_keyring_unlock_prompt_func_t)(
1005251881Speter  char **keyring_password,
1006251881Speter  const char *keyring_name,
1007251881Speter  void *baton,
1008251881Speter  apr_pool_t *pool);
1009251881Speter
1010251881Speter
1011251881Speter/** libsvn_auth_gnome_keyring-specific run-time parameters. */
1012251881Speter
1013251881Speter/** @brief The pointer to function which prompts user for GNOME Keyring
1014251881Speter * password.
1015251881Speter * The type of this pointer should be svn_auth_gnome_keyring_unlock_prompt_func_t. */
1016251881Speter#define SVN_AUTH_PARAM_GNOME_KEYRING_UNLOCK_PROMPT_FUNC "gnome-keyring-unlock-prompt-func"
1017251881Speter
1018251881Speter/** @brief The baton which is passed to
1019251881Speter * @c *SVN_AUTH_PARAM_GNOME_KEYRING_UNLOCK_PROMPT_FUNC. */
1020251881Speter#define SVN_AUTH_PARAM_GNOME_KEYRING_UNLOCK_PROMPT_BATON "gnome-keyring-unlock-prompt-baton"
1021251881Speter
1022262253Speter#if (!defined(DARWIN) && !defined(WIN32)) || defined(DOXYGEN)
1023251881Speter/**
1024251881Speter * Get libsvn_auth_gnome_keyring version information.
1025251881Speter *
1026251881Speter * @since New in 1.6
1027251881Speter */
1028251881Speterconst svn_version_t *
1029251881Spetersvn_auth_gnome_keyring_version(void);
1030251881Speter
1031251881Speter
1032251881Speter/**
1033251881Speter * Set @a *provider to an authentication provider of type @c
1034251881Speter * svn_auth_cred_simple_t that gets/sets information from the user's
1035251881Speter * ~/.subversion configuration directory.
1036251881Speter *
1037251881Speter * This is like svn_client_get_simple_provider(), except that the
1038251881Speter * password is stored in GNOME Keyring.
1039251881Speter *
1040251881Speter * If the GNOME Keyring is locked the provider calls
1041251881Speter * @c *SVN_AUTH_PARAM_GNOME_KEYRING_UNLOCK_PROMPT_FUNC in order to unlock
1042251881Speter * the keyring.
1043251881Speter *
1044251881Speter * @c SVN_AUTH_PARAM_GNOME_KEYRING_UNLOCK_PROMPT_BATON is passed to
1045251881Speter * @c *SVN_AUTH_PARAM_GNOME_KEYRING_UNLOCK_PROMPT_FUNC.
1046251881Speter *
1047251881Speter * Allocate @a *provider in @a pool.
1048251881Speter *
1049251881Speter * @since New in 1.6
1050251881Speter * @note This function actually works only on systems with
1051251881Speter * libsvn_auth_gnome_keyring and GNOME Keyring installed.
1052299742Sdim * @deprecated Provided for backwards compatibility with the 1.8 API.
1053299742Sdim * Use svn_auth_get_platform_specific_provider with provider_name
1054299742Sdim * of "gnome_keyring" and provider_type of "simple".
1055251881Speter */
1056299742SdimSVN_DEPRECATED
1057251881Spetervoid
1058251881Spetersvn_auth_get_gnome_keyring_simple_provider(
1059251881Speter  svn_auth_provider_object_t **provider,
1060251881Speter  apr_pool_t *pool);
1061251881Speter
1062251881Speter
1063251881Speter/**
1064251881Speter * Set @a *provider to an authentication provider of type @c
1065251881Speter * svn_auth_cred_ssl_client_cert_pw_t that gets/sets information from the
1066251881Speter * user's ~/.subversion configuration directory.
1067251881Speter *
1068251881Speter * This is like svn_client_get_ssl_client_cert_pw_file_provider(), except
1069251881Speter * that the password is stored in GNOME Keyring.
1070251881Speter *
1071251881Speter * If the GNOME Keyring is locked the provider calls
1072251881Speter * @c *SVN_AUTH_PARAM_GNOME_KEYRING_UNLOCK_PROMPT_FUNC in order to unlock
1073251881Speter * the keyring.
1074251881Speter *
1075251881Speter * @c SVN_AUTH_PARAM_GNOME_KEYRING_UNLOCK_PROMPT_BATON is passed to
1076251881Speter * @c *SVN_AUTH_PARAM_GNOME_KEYRING_UNLOCK_PROMPT_FUNC.
1077251881Speter *
1078251881Speter * Allocate @a *provider in @a pool.
1079251881Speter *
1080251881Speter * @since New in 1.6
1081251881Speter * @note This function actually works only on systems with
1082251881Speter * libsvn_auth_gnome_keyring and GNOME Keyring installed.
1083299742Sdim * @deprecated Provided for backwards compatibility with the 1.8 API.
1084299742Sdim * Use svn_auth_get_platform_specific_provider with provider_name
1085299742Sdim * of "gnome_keyring" and provider_type of "ssl_client_cert_pw".
1086251881Speter */
1087299742SdimSVN_DEPRECATED
1088251881Spetervoid
1089251881Spetersvn_auth_get_gnome_keyring_ssl_client_cert_pw_provider(
1090251881Speter  svn_auth_provider_object_t **provider,
1091251881Speter  apr_pool_t *pool);
1092251881Speter
1093251881Speter
1094251881Speter/**
1095251881Speter * Get libsvn_auth_kwallet version information.
1096251881Speter *
1097251881Speter * @since New in 1.6
1098251881Speter */
1099251881Speterconst svn_version_t *
1100251881Spetersvn_auth_kwallet_version(void);
1101251881Speter
1102251881Speter
1103251881Speter/**
1104251881Speter * Set @a *provider to an authentication provider of type @c
1105251881Speter * svn_auth_cred_simple_t that gets/sets information from the user's
1106251881Speter * ~/.subversion configuration directory.  Allocate @a *provider in
1107251881Speter * @a pool.
1108251881Speter *
1109251881Speter * This is like svn_client_get_simple_provider(), except that the
1110251881Speter * password is stored in KWallet.
1111251881Speter *
1112251881Speter * @since New in 1.6
1113251881Speter * @note This function actually works only on systems with libsvn_auth_kwallet
1114251881Speter * and KWallet installed.
1115299742Sdim * @deprecated Provided for backwards compatibility with the 1.8 API.
1116299742Sdim * Use svn_auth_get_platform_specific_provider with provider_name
1117299742Sdim * of "kwallet" and provider_type of "simple".
1118251881Speter */
1119299742SdimSVN_DEPRECATED
1120251881Spetervoid
1121251881Spetersvn_auth_get_kwallet_simple_provider(svn_auth_provider_object_t **provider,
1122251881Speter                                     apr_pool_t *pool);
1123251881Speter
1124251881Speter
1125251881Speter/**
1126251881Speter * Set @a *provider to an authentication provider of type @c
1127251881Speter * svn_auth_cred_ssl_client_cert_pw_t that gets/sets information from the
1128251881Speter * user's ~/.subversion configuration directory.  Allocate @a *provider in
1129251881Speter * @a pool.
1130251881Speter *
1131251881Speter * This is like svn_client_get_ssl_client_cert_pw_file_provider(), except
1132251881Speter * that the password is stored in KWallet.
1133251881Speter *
1134251881Speter * @since New in 1.6
1135251881Speter * @note This function actually works only on systems with libsvn_auth_kwallet
1136251881Speter * and KWallet installed.
1137299742Sdim * @deprecated Provided for backwards compatibility with the 1.8 API.
1138299742Sdim * Use svn_auth_get_platform_specific_provider with provider_name
1139299742Sdim * of "kwallet" and provider_type of "ssl_client_cert_pw".
1140251881Speter */
1141299742SdimSVN_DEPRECATED
1142251881Spetervoid
1143251881Spetersvn_auth_get_kwallet_ssl_client_cert_pw_provider(
1144251881Speter  svn_auth_provider_object_t **provider,
1145251881Speter  apr_pool_t *pool);
1146251881Speter#endif /* (!DARWIN && !WIN32) || DOXYGEN */
1147251881Speter
1148251881Speter#if !defined(WIN32) || defined(DOXYGEN)
1149251881Speter/**
1150251881Speter * Set @a *provider to an authentication provider of type @c
1151251881Speter * svn_auth_cred_simple_t that gets/sets information from the user's
1152251881Speter * ~/.subversion configuration directory.
1153251881Speter *
1154251881Speter * This is like svn_client_get_simple_provider(), except that the
1155251881Speter * password is obtained from gpg_agent, which will keep it in
1156251881Speter * a memory cache.
1157251881Speter *
1158251881Speter * Allocate @a *provider in @a pool.
1159251881Speter *
1160251881Speter * @since New in 1.8
1161251881Speter * @note This function actually works only on systems with
1162251881Speter * GNU Privacy Guard installed.
1163299742Sdim * @deprecated Provided for backwards compatibility with the 1.8 API.
1164299742Sdim * Use svn_auth_get_platform_specific_provider with provider_name
1165299742Sdim * of "gpg_agent" and provider_type of "simple".
1166251881Speter */
1167299742SdimSVN_DEPRECATED
1168251881Spetervoid
1169251881Spetersvn_auth_get_gpg_agent_simple_provider
1170251881Speter    (svn_auth_provider_object_t **provider,
1171251881Speter     apr_pool_t *pool);
1172251881Speter#endif /* !defined(WIN32) || defined(DOXYGEN) */
1173251881Speter
1174251881Speter
1175251881Speter/** Set @a *provider to an authentication provider of type @c
1176251881Speter * svn_auth_cred_username_t that gets/sets information from a user's
1177251881Speter * ~/.subversion configuration directory.  Allocate @a *provider in
1178251881Speter * @a pool.
1179251881Speter *
1180251881Speter * If a default username is available, @a *provider will honor it,
1181251881Speter * and return it when svn_auth_first_credentials() is called.  (See
1182251881Speter * @c SVN_AUTH_PARAM_DEFAULT_USERNAME.)
1183251881Speter *
1184251881Speter * @since New in 1.4.
1185251881Speter */
1186251881Spetervoid
1187251881Spetersvn_auth_get_username_provider(svn_auth_provider_object_t **provider,
1188251881Speter                               apr_pool_t *pool);
1189251881Speter
1190251881Speter
1191251881Speter/** Set @a *provider to an authentication provider of type @c
1192251881Speter * svn_auth_cred_ssl_server_trust_t, allocated in @a pool.
1193251881Speter *
1194251881Speter * @a *provider retrieves its credentials from the configuration
1195251881Speter * mechanism.  The returned credential is used to override SSL
1196251881Speter * security on an error.
1197251881Speter *
1198251881Speter * @since New in 1.4.
1199251881Speter */
1200251881Spetervoid
1201251881Spetersvn_auth_get_ssl_server_trust_file_provider(
1202251881Speter  svn_auth_provider_object_t **provider,
1203251881Speter  apr_pool_t *pool);
1204251881Speter
1205251881Speter/** Set @a *provider to an authentication provider of type @c
1206251881Speter * svn_auth_cred_ssl_client_cert_t, allocated in @a pool.
1207251881Speter *
1208251881Speter * @a *provider retrieves its credentials from the configuration
1209251881Speter * mechanism.  The returned credential is used to load the appropriate
1210251881Speter * client certificate for authentication when requested by a server.
1211251881Speter *
1212251881Speter * @since New in 1.4.
1213251881Speter */
1214251881Spetervoid
1215251881Spetersvn_auth_get_ssl_client_cert_file_provider(
1216251881Speter  svn_auth_provider_object_t **provider,
1217251881Speter  apr_pool_t *pool);
1218251881Speter
1219251881Speter
1220251881Speter/** Set @a *provider to an authentication provider of type @c
1221251881Speter * svn_auth_cred_ssl_client_cert_pw_t that gets/sets information from the user's
1222251881Speter * ~/.subversion configuration directory.
1223251881Speter *
1224251881Speter * If the provider is going to save the passphrase unencrypted,
1225251881Speter * it calls @a plaintext_passphrase_prompt_func, passing @a
1226251881Speter * prompt_baton, before saving the passphrase.
1227251881Speter *
1228251881Speter * If @a plaintext_passphrase_prompt_func is NULL it is not called
1229251881Speter * and the passphrase is not stored in plaintext.
1230251881Speter * Client developers are highly encouraged to provide this callback
1231251881Speter * to ensure their users are made aware of the fact that their passphrase
1232251881Speter * is going to be stored unencrypted.
1233251881Speter *
1234251881Speter * Clients can however set the callback to NULL and set
1235251881Speter * SVN_AUTH_PARAM_STORE_SSL_CLIENT_CERT_PP_PLAINTEXT to SVN_CONFIG_FALSE or
1236251881Speter * SVN_CONFIG_TRUE to enforce a certain behaviour.
1237251881Speter *
1238251881Speter * Allocate @a *provider in @a pool.
1239251881Speter *
1240251881Speter * @since New in 1.6.
1241251881Speter */
1242251881Spetervoid
1243251881Spetersvn_auth_get_ssl_client_cert_pw_file_provider2(
1244251881Speter  svn_auth_provider_object_t **provider,
1245251881Speter  svn_auth_plaintext_passphrase_prompt_func_t plaintext_passphrase_prompt_func,
1246251881Speter  void *prompt_baton,
1247251881Speter  apr_pool_t *pool);
1248251881Speter
1249251881Speter/** Like svn_auth_get_ssl_client_cert_pw_file_provider2, but without
1250251881Speter * the ability to call the svn_auth_plaintext_passphrase_prompt_func_t
1251251881Speter * callback, and the provider always assumes that it is not allowed
1252251881Speter * to store the passphrase in plaintext.
1253251881Speter *
1254251881Speter * @deprecated Provided for backwards compatibility with the 1.5 API.
1255251881Speter * @since New in 1.4.
1256251881Speter */
1257251881SpeterSVN_DEPRECATED
1258251881Spetervoid
1259251881Spetersvn_auth_get_ssl_client_cert_pw_file_provider(
1260251881Speter  svn_auth_provider_object_t **provider,
1261251881Speter  apr_pool_t *pool);
1262251881Speter
1263251881Speter
1264251881Speter/** Set @a *provider to an authentication provider of type @c
1265251881Speter * svn_auth_cred_ssl_server_trust_t, allocated in @a pool.
1266251881Speter *
1267251881Speter * @a *provider retrieves its credentials by using the @a prompt_func
1268251881Speter * and @a prompt_baton.  The returned credential is used to override
1269251881Speter * SSL security on an error.
1270251881Speter *
1271251881Speter * @since New in 1.4.
1272251881Speter */
1273251881Spetervoid
1274251881Spetersvn_auth_get_ssl_server_trust_prompt_provider(
1275251881Speter  svn_auth_provider_object_t **provider,
1276251881Speter  svn_auth_ssl_server_trust_prompt_func_t prompt_func,
1277251881Speter  void *prompt_baton,
1278251881Speter  apr_pool_t *pool);
1279251881Speter
1280251881Speter
1281251881Speter/** Set @a *provider to an authentication provider of type @c
1282251881Speter * svn_auth_cred_ssl_client_cert_t, allocated in @a pool.
1283251881Speter *
1284251881Speter * @a *provider retrieves its credentials by using the @a prompt_func
1285251881Speter * and @a prompt_baton.  The returned credential is used to load the
1286251881Speter * appropriate client certificate for authentication when requested by
1287251881Speter * a server.  The prompt will be retried @a retry_limit times. For
1288251881Speter * infinite retries, set @a retry_limit to value less than 0.
1289251881Speter *
1290251881Speter * @since New in 1.4.
1291251881Speter */
1292251881Spetervoid
1293251881Spetersvn_auth_get_ssl_client_cert_prompt_provider(
1294251881Speter  svn_auth_provider_object_t **provider,
1295251881Speter  svn_auth_ssl_client_cert_prompt_func_t prompt_func,
1296251881Speter  void *prompt_baton,
1297251881Speter  int retry_limit,
1298251881Speter  apr_pool_t *pool);
1299251881Speter
1300251881Speter
1301251881Speter/** Set @a *provider to an authentication provider of type @c
1302251881Speter * svn_auth_cred_ssl_client_cert_pw_t, allocated in @a pool.
1303251881Speter *
1304251881Speter * @a *provider retrieves its credentials by using the @a prompt_func
1305251881Speter * and @a prompt_baton.  The returned credential is used when a loaded
1306251881Speter * client certificate is protected by a passphrase.  The prompt will
1307251881Speter * be retried @a retry_limit times. For infinite retries, set
1308251881Speter * @a retry_limit to value less than 0.
1309251881Speter *
1310251881Speter * @since New in 1.4.
1311251881Speter */
1312251881Spetervoid
1313251881Spetersvn_auth_get_ssl_client_cert_pw_prompt_provider(
1314251881Speter  svn_auth_provider_object_t **provider,
1315251881Speter  svn_auth_ssl_client_cert_pw_prompt_func_t prompt_func,
1316251881Speter  void *prompt_baton,
1317251881Speter  int retry_limit,
1318251881Speter  apr_pool_t *pool);
1319251881Speter
1320251881Speter
1321251881Speter#ifdef __cplusplus
1322251881Speter}
1323251881Speter#endif /* __cplusplus */
1324251881Speter
1325251881Speter#endif /* SVN_AUTH_H */
1326