3
* ====================================================================
4
* Copyright (c) 2000-2004 CollabNet. All rights reserved.
6
* This software is licensed as described in the file COPYING, which
7
* you should have received as part of this distribution. The terms
8
* are also available at http://subversion.tigris.org/license-1.html.
9
* If newer versions of this license are posted there, you may use a
10
* newer version instead, at your option.
12
* This software consists of voluntary contributions made by many
13
* individuals. For exact contribution history, see the revision
14
* history and logs, available at http://subversion.tigris.org/.
15
* ====================================================================
19
* @brief Subversion's authentication system
25
#include <apr_pools.h>
27
#include "svn_types.h"
31
#endif /* __cplusplus */
33
/** Overview of the svn authentication system.
35
* We define an authentication "provider" as a module that is able to
36
* return a specific set of credentials. (e.g. username/password,
37
* certificate, etc.) Each provider implements a vtable that
39
* - can fetch initial credentials
40
* - can retry the fetch (or try to fetch something different)
41
* - can store the credentials for future use
43
* For any given type of credentials, there can exist any number of
44
* separate providers -- each provider has a different method of
45
* fetching. (i.e. from a disk store, by prompting the user, etc.)
47
* The application begins by creating an auth baton object, and
48
* "registers" some number of providers with the auth baton, in a
49
* specific order. (For example, it may first register a
50
* username/password provider that looks in disk store, then register
51
* a username/password provider that prompts the user.)
53
* Later on, when any svn library is challenged, it asks the auth
54
* baton for the specific credentials. If the initial credentials
55
* fail to authenticate, the caller keeps requesting new credentials.
56
* Under the hood, libsvn_auth effectively "walks" over each provider
57
* (in order of registry), one at a time, until all the providers have
58
* exhausted all their retry options.
60
* This system allows an application to flexibly define authentication
61
* behaviors (by changing registration order), and very easily write
62
* new authentication providers.
64
* An auth_baton also contains an internal hashtable of run-time
65
* parameters; any provider or library layer can set these run-time
66
* parameters at any time, so that the provider has access to the
67
* data. (For example, certain run-time data may not be available
68
* until an authentication challenge is made.) Each credential type
69
* must document the run-time parameters that are made available to
72
* @defgroup auth_fns authentication functions
77
/** The type of a Subversion authentication object */
78
typedef struct svn_auth_baton_t svn_auth_baton_t;
80
/** The type of a Subversion authentication-iteration object */
81
typedef struct svn_auth_iterstate_t svn_auth_iterstate_t;
84
/** The main authentication "provider" vtable. */
85
typedef struct svn_auth_provider_t
87
/** The kind of credentials this provider knows how to retrieve. */
88
const char *cred_kind;
90
/** Get an initial set of credentials.
92
* Set @a *credentials to a set of valid credentials within @a
93
* realmstring, or NULL if no credentials are available. Set @a
94
* *iter_baton to context that allows a subsequent call to @c
95
* next_credentials, in case the first credentials fail to
96
* authenticate. @a provider_baton is general context for the
97
* vtable, @a parameters contains any run-time data that the
98
* provider may need, and @a realmstring comes from the @c
99
* svn_auth_first_credentials call.
101
svn_error_t * (*first_credentials) (void **credentials,
103
void *provider_baton,
104
apr_hash_t *parameters,
105
const char *realmstring,
108
/** Get a different set of credentials.
110
* Set @a *credentials to another set of valid credentials, (using
111
* @a iter_baton as the context from previous call to first_credentials
112
* or next_credentials). If no more credentials are available, set
113
* @a **credentials to NULL. If the provider only has one set of
114
* credentials, this function pointer should simply be NULL. @a
115
* provider_baton is general context for the vtable, @a parameters
116
* contains any run-time data that the provider may need, and @a
117
* realmstring comes from the @c svn_auth_first_credentials call.
119
svn_error_t * (*next_credentials) (void **credentials,
121
void *provider_baton,
122
apr_hash_t *parameters,
123
const char *realmstring,
126
/** Save credentials.
128
* Store @a credentials for future use. @a provider_baton is
129
* general context for the vtable, and @a parameters contains any
130
* run-time data the provider may need. Set @a *saved to true if
131
* the save happened, or false if not. The provider is not required
132
* to save; if it refuses or is unable to save for non-fatal
133
* reasons, return false. If the provider never saves data, then
134
* this function pointer should simply be NULL. @a realmstring comes
135
* from the @c svn_auth_first_credentials call.
137
svn_error_t * (*save_credentials) (svn_boolean_t *saved,
139
void *provider_baton,
140
apr_hash_t *parameters,
141
const char *realmstring,
144
} svn_auth_provider_t;
147
/** A provider object, ready to be put into an array and given to
149
typedef struct svn_auth_provider_object_t
151
const svn_auth_provider_t *vtable;
152
void *provider_baton;
154
} svn_auth_provider_object_t;
158
/** Specific types of credentials **/
160
/** Simple username/password pair credential kind.
162
* The following auth parameters may be available to the providers:
164
* - @c SVN_AUTH_PARAM_NO_AUTH_CACHE (@c void*)
165
* - @c SVN_AUTH_PARAM_DEFAULT_USERNAME (@c char*)
166
* - @c SVN_AUTH_PARAM_DEFAULT_PASSWORD (@c char*)
168
#define SVN_AUTH_CRED_SIMPLE "svn.simple"
170
/** @c SVN_AUTH_CRED_SIMPLE credentials. */
171
typedef struct svn_auth_cred_simple_t
174
const char *username;
176
const char *password;
177
/** Indicates if the credentials may be saved (to disk). For example, a
178
* GUI prompt implementation with a remember password checkbox shall set
179
* @a may_save to TRUE if the checkbox is checked.
181
svn_boolean_t may_save;
182
} svn_auth_cred_simple_t;
185
/** Username credential kind.
187
* The following optional auth parameters are relevant to the providers:
189
* - @c SVN_AUTH_PARAM_NO_AUTH_CACHE (@c void*)
190
* - @c SVN_AUTH_PARAM_DEFAULT_USERNAME (@c char*)
192
#define SVN_AUTH_CRED_USERNAME "svn.username"
194
/** @c SVN_AUTH_CRED_USERNAME credentials. */
195
typedef struct svn_auth_cred_username_t
198
const char *username;
199
/** Indicates if the credentials may be saved (to disk). For example, a
200
* GUI prompt implementation with a remember username checkbox shall set
201
* @a may_save to TRUE if the checkbox is checked.
203
svn_boolean_t may_save;
204
} svn_auth_cred_username_t;
207
/** SSL client certificate credential type.
209
* The following auth parameters are available to the providers:
211
* - @c SVN_AUTH_PARAM_CONFIG (@c svn_config_t*)
212
* - @c SVN_AUTH_PARAM_SERVER_GROUP (@c char*)
214
* The following optional auth parameters are relevant to the providers:
216
* - @c SVN_AUTH_PARAM_NO_AUTH_CACHE (@c void*)
218
#define SVN_AUTH_CRED_SSL_CLIENT_CERT "svn.ssl.client-cert"
220
/** @c SVN_AUTH_CRED_SSL_CLIENT_CERT credentials. */
221
typedef struct svn_auth_cred_ssl_client_cert_t
223
/** Full paths to the certificate file */
224
const char *cert_file;
225
/** Indicates if the credentials may be saved (to disk). For example, a
226
* GUI prompt implementation with a remember certificate checkbox shall
227
* set @a may_save to TRUE if the checkbox is checked.
229
svn_boolean_t may_save;
230
} svn_auth_cred_ssl_client_cert_t;
233
/** SSL client certificate passphrase credential type.
235
* @note The realmstring used with this credential type must be a name that
236
* makes it possible for the user to identify the certificate.
238
* The following auth parameters are available to the providers:
240
* - @c SVN_AUTH_PARAM_CONFIG (@c svn_config_t*)
241
* - @c SVN_AUTH_PARAM_SERVER_GROUP (@c char*)
243
* The following optional auth parameters are relevant to the providers:
245
* - @c SVN_AUTH_PARAM_NO_AUTH_CACHE (@c void*)
247
#define SVN_AUTH_CRED_SSL_CLIENT_CERT_PW "svn.ssl.client-passphrase"
249
/** @c SVN_AUTH_CRED_SSL_CLIENT_CERT_PW credentials. */
250
typedef struct svn_auth_cred_ssl_client_cert_pw_t
252
/** Certificate password */
253
const char *password;
254
/** Indicates if the credentials may be saved (to disk). For example, a
255
* GUI prompt implementation with a remember password checkbox shall set
256
* @a may_save to TRUE if the checkbox is checked.
258
svn_boolean_t may_save;
259
} svn_auth_cred_ssl_client_cert_pw_t;
262
/** SSL server verification credential type.
264
* The following auth parameters are available to the providers:
266
* - @c SVN_AUTH_PARAM_CONFIG (@c svn_config_t*)
267
* - @c SVN_AUTH_PARAM_SERVER_GROUP (@c char*)
268
* - @c SVN_AUTH_PARAM_SSL_SERVER_FAILURES (@c apr_uint32_t*)
269
* - @c SVN_AUTH_PARAM_SSL_SERVER_CERT_INFO
270
* (@c svn_auth_ssl_server_cert_info_t*)
272
* The following optional auth parameters are relevant to the providers:
274
* - @c SVN_AUTH_PARAM_NO_AUTH_CACHE (@c void*)
276
#define SVN_AUTH_CRED_SSL_SERVER_TRUST "svn.ssl.server"
278
/** SSL server certificate information used by @c
279
* SVN_AUTH_CRED_SSL_SERVER_TRUST providers.
281
typedef struct svn_auth_ssl_server_cert_info_t
284
const char *hostname;
285
/** ASCII fingerprint */
286
const char *fingerprint;
287
/** ASCII date from which the certificate is valid */
288
const char *valid_from;
289
/** ASCII date until which the certificate is valid */
290
const char *valid_until;
291
/** DN of the certificate issuer */
292
const char *issuer_dname;
293
/** Base-64 encoded DER certificate representation */
294
const char *ascii_cert;
295
} svn_auth_ssl_server_cert_info_t;
297
/** @c SVN_AUTH_CRED_SSL_SERVER_TRUST credentials. */
298
typedef struct svn_auth_cred_ssl_server_trust_t
300
/** Indicates if the credentials may be saved (to disk). For example, a
301
* GUI prompt implementation with a checkbox to accept the certificate
302
* permanently shall set @a may_save to TRUE if the checkbox is checked.
304
svn_boolean_t may_save;
305
/** Bit mask of the accepted failures */
306
apr_uint32_t accepted_failures;
307
} svn_auth_cred_ssl_server_trust_t;
311
/** Credential-constructing prompt functions. **/
313
/** These exist so that different client applications can use
314
* different prompt mechanisms to supply the same credentials. For
315
* example, if authentication requires a username and password, a
316
* command-line client's prompting function might prompt first for the
317
* username and then for the password, whereas a GUI client's would
318
* present a single dialog box asking for both, and a telepathic
319
* client's would read all the information directly from the user's
320
* mind. All these prompting functions return the same type of
321
* credential, but the information used to construct the credential is
322
* gathered in an interface-specific way in each case.
325
/** Set @a *cred by prompting the user, allocating @a *cred in @a pool.
326
* @a baton is an implementation-specific closure.
328
* If @a realm is non-null, maybe use it in the prompt string.
330
* If @a username is non-null, then the user might be prompted only
331
* for a password, but @a *creds would still be filled with both
332
* username and password. For example, a typical usage would be to
333
* pass @a username on the first call, but then leave it null for
334
* subsequent calls, on the theory that if credentials failed, it's
335
* as likely to be due to incorrect username as incorrect password.
337
* If @a may_save is FALSE, the auth system does not allow the credentials
338
* to be saved (to disk). A prompt function shall not ask the user if the
339
* credentials shall be saved if @a may_save is FALSE. For example, a GUI
340
* client with a remember password checkbox would grey out the checkbox if
341
* @a may_save is FALSE.
343
typedef svn_error_t *
344
(*svn_auth_simple_prompt_func_t) (svn_auth_cred_simple_t **cred,
347
const char *username,
348
svn_boolean_t may_save,
352
/** Set @a *cred by prompting the user, allocating @a *cred in @a pool.
353
* @a baton is an implementation-specific closure.
355
* If @a realm is non-null, maybe use it in the prompt string.
357
* If @a may_save is FALSE, the auth system does not allow the credentials
358
* to be saved (to disk). A prompt function shall not ask the user if the
359
* credentials shall be saved if @a may_save is FALSE. For example, a GUI
360
* client with a remember username checkbox would grey out the checkbox if
361
* @a may_save is FALSE.
363
typedef svn_error_t *
364
(*svn_auth_username_prompt_func_t) (svn_auth_cred_username_t **cred,
367
svn_boolean_t may_save,
371
/** @name SSL server certificate failure bits
373
* @note These values are stored in the on disk auth cache by the SSL
374
* server certificate auth provider, so the meaning of these bits must
378
/** Certificate is not yet valid. */
379
#define SVN_AUTH_SSL_NOTYETVALID 0x00000001
380
/** Certificate has expired. */
381
#define SVN_AUTH_SSL_EXPIRED 0x00000002
382
/** Certificate's CN (hostname) does not match the remote hostname. */
383
#define SVN_AUTH_SSL_CNMISMATCH 0x00000004
384
/** @brief Certificate authority is unknown (i.e. not trusted) */
385
#define SVN_AUTH_SSL_UNKNOWNCA 0x00000008
386
/** @brief Other failure. This can happen if neon has introduced a new
387
* failure bit that we do not handle yet. */
388
#define SVN_AUTH_SSL_OTHER 0x40000000
391
/** Set @a *cred by prompting the user, allocating @a *cred in @a pool.
392
* @a baton is an implementation-specific closure.
394
* @a cert_info is a structure describing the server cert that was
395
* presented to the client, and @a failures is a bitmask that
396
* describes exactly why the cert could not be automatically validated,
397
* composed from the constants SVN_AUTH_SSL_* (@c SVN_AUTH_SSL_NOTYETVALID
398
* etc.). @a realm is a string that can be used in the prompt string.
400
* If @a may_save is FALSE, the auth system does not allow the credentials
401
* to be saved (to disk). A prompt function shall not ask the user if the
402
* credentials shall be saved if @a may_save is FALSE. For example, a GUI
403
* client with a trust permanently checkbox would grey out the checkbox if
404
* @a may_save is FALSE.
406
typedef svn_error_t *(*svn_auth_ssl_server_trust_prompt_func_t) (
407
svn_auth_cred_ssl_server_trust_t **cred,
410
apr_uint32_t failures,
411
const svn_auth_ssl_server_cert_info_t *cert_info,
412
svn_boolean_t may_save,
416
/** Set @a *cred by prompting the user, allocating @a *cred in @a pool.
417
* @a baton is an implementation-specific closure. @a realm is a string
418
* that can be used in the prompt string.
420
* If @a may_save is FALSE, the auth system does not allow the credentials
421
* to be saved (to disk). A prompt function shall not ask the user if the
422
* credentials shall be saved if @a may_save is FALSE. For example, a GUI
423
* client with a remember certificate checkbox would grey out the checkbox
424
* if @a may_save is FALSE.
426
typedef svn_error_t *(*svn_auth_ssl_client_cert_prompt_func_t) (
427
svn_auth_cred_ssl_client_cert_t **cred,
430
svn_boolean_t may_save,
434
/** Set @a *cred by prompting the user, allocating @a *cred in @a pool.
435
* @a baton is an implementation-specific closure. @a realm is a string
436
* identifying the certificate, and can be used in the prompt string.
438
* If @a may_save is FALSE, the auth system does not allow the credentials
439
* to be saved (to disk). A prompt function shall not ask the user if the
440
* credentials shall be saved if @a may_save is FALSE. For example, a GUI
441
* client with a remember password checkbox would grey out the checkbox if
442
* @a may_save is FALSE.
444
typedef svn_error_t *(*svn_auth_ssl_client_cert_pw_prompt_func_t) (
445
svn_auth_cred_ssl_client_cert_pw_t **cred,
448
svn_boolean_t may_save,
453
/** Initialize an authentication system.
455
* Return an authentication object in @a *auth_baton (allocated in @a
456
* pool) that represents a particular instance of the svn
457
* authentication system. @a providers is an array of @c
458
* svn_auth_provider_object_t pointers, already allocated in @a pool
459
* and intentionally ordered. These pointers will be stored within @a
460
* *auth_baton, grouped by credential type, and searched in this exact
463
void svn_auth_open(svn_auth_baton_t **auth_baton,
464
apr_array_header_t *providers,
467
/** Set an authentication run-time parameter.
469
* Store @a name / @a value pair as a run-time parameter in @a
470
* auth_baton, making the data accessible to all providers. @a name
471
* and @a value will be NOT be duplicated into the auth_baton's
472
* pool. To delete a run-time parameter, pass NULL for @a value.
474
void svn_auth_set_parameter(svn_auth_baton_t *auth_baton,
478
/** Get an authentication run-time parameter.
480
* Return a value for run-time parameter @a name from @a auth_baton.
481
* Return NULL if the parameter doesn't exist.
483
const void * svn_auth_get_parameter(svn_auth_baton_t *auth_baton,
486
/** Universal run-time parameters, made available to all providers.
488
If you are writing a new provider, then to be a "good citizen",
489
you should notice these global parameters! Note that these
490
run-time params should be treated as read-only by providers; the
491
application is responsible for placing them into the auth_baton
494
/** The auth-hash prefix indicating that the parameter is global. */
495
#define SVN_AUTH_PARAM_PREFIX "svn:auth:"
498
/** @brief Any 'default' credentials that came in through the application
499
* itself, (e.g. --username and --password options). Property values are
501
#define SVN_AUTH_PARAM_DEFAULT_USERNAME SVN_AUTH_PARAM_PREFIX "username"
502
#define SVN_AUTH_PARAM_DEFAULT_PASSWORD SVN_AUTH_PARAM_PREFIX "password"
505
/** @brief The application doesn't want any providers to prompt
506
* users. Property value is irrelevant; only property's existence
508
#define SVN_AUTH_PARAM_NON_INTERACTIVE SVN_AUTH_PARAM_PREFIX "non-interactive"
510
/** @brief The application doesn't want any providers to save passwords
511
* to disk. Property value is irrelevant; only property's existence
513
#define SVN_AUTH_PARAM_DONT_STORE_PASSWORDS SVN_AUTH_PARAM_PREFIX \
514
"dont-store-passwords"
516
/** @brief The application doesn't want any providers to save credentials
517
* to disk. Property value is irrelevant; only property's existence
519
#define SVN_AUTH_PARAM_NO_AUTH_CACHE SVN_AUTH_PARAM_PREFIX "no-auth-cache"
521
/** @brief The following property is for SSL server cert providers. This
522
* provides a pointer to an @c apr_uint32_t containing the failures
523
* detected by the certificate validator. */
524
#define SVN_AUTH_PARAM_SSL_SERVER_FAILURES SVN_AUTH_PARAM_PREFIX \
527
/** @brief The following property is for SSL server cert providers. This
528
* provides the cert info (svn_auth_ssl_server_cert_info_t). */
529
#define SVN_AUTH_PARAM_SSL_SERVER_CERT_INFO SVN_AUTH_PARAM_PREFIX \
532
/** Some providers need access to the @c svn_config_t configuration. */
533
#define SVN_AUTH_PARAM_CONFIG SVN_AUTH_PARAM_PREFIX "config"
535
/** The current server group. */
536
#define SVN_AUTH_PARAM_SERVER_GROUP SVN_AUTH_PARAM_PREFIX "server-group"
538
/** @brief A configuration directory that overrides the default
540
#define SVN_AUTH_PARAM_CONFIG_DIR SVN_AUTH_PARAM_PREFIX "config-dir"
543
/** Get an initial set of credentials.
545
* Ask @a auth_baton to set @a *credentials to a set of credentials
546
* defined by @a cred_kind and valid within @a realmstring, or NULL if
547
* no credentials are available. Otherwise, return an iteration state
548
* in @a *state, so that the caller can call @c
549
* svn_auth_next_credentials, in case the first set of credentials
550
* fails to authenticate.
552
* Use @a pool to allocate @a *state, and for temporary allocation.
553
* Note that @a *credentials will be allocated in @a auth_baton's pool.
555
svn_error_t * svn_auth_first_credentials(void **credentials,
556
svn_auth_iterstate_t **state,
557
const char *cred_kind,
558
const char *realmstring,
559
svn_auth_baton_t *auth_baton,
562
/** Get another set of credentials, assuming previous ones failed to
565
* Use @a state to fetch a different set of @a *credentials, as a
566
* follow-up to @c svn_auth_first_credentials or @c
567
* svn_auth_next_credentials. If no more credentials are available,
568
* set @a *credentials to NULL.
570
* Note that @a *credentials will be allocated in @c auth_baton's pool.
572
svn_error_t * svn_auth_next_credentials(void **credentials,
573
svn_auth_iterstate_t *state,
576
/** Save a set of credentials.
578
* Ask @a state to store the most recently returned credentials,
579
* presumably because they successfully authenticated. Use @a pool
580
* for temporary allocation. If no credentials were ever returned, do
583
svn_error_t * svn_auth_save_credentials(svn_auth_iterstate_t *state,
590
#endif /* __cplusplus */
592
#endif /* SVN_AUTH_H */
added
removed
subversion/include/svn_auth.h
