Main Page   Modules   Data Structures   File List   Data Fields  

authentication functions

Overview of the svn authentication system. More...

Data Structures

struct  svn_auth_cred_simple_t
 SVN_AUTH_CRED_SIMPLE credentials. More...

struct  svn_auth_cred_ssl_client_cert_pw_t
 SVN_AUTH_CRED_SSL_CLIENT_CERT_PW credentials. More...

struct  svn_auth_cred_ssl_client_cert_t
 SVN_AUTH_CRED_SSL_CLIENT_CERT credentials. More...

struct  svn_auth_cred_ssl_server_trust_t
 SVN_AUTH_CRED_SSL_SERVER_TRUST credentials. More...

struct  svn_auth_cred_username_t
 SVN_AUTH_CRED_USERNAME credentials. More...

struct  svn_auth_provider_object_t
 A provider object, ready to be put into an array and given to svn_auth_open(). More...

struct  svn_auth_provider_t
 The main authentication "provider" vtable. More...

struct  svn_auth_ssl_server_cert_info_t
 SSL server certificate information used by SVN_AUTH_CRED_SSL_SERVER_TRUST providers. More...


SSL server certificate failure bits

Note:
These values are stored in the on disk auth cache by the SSL server certificate auth provider, so the meaning of these bits must not be changed.


#define SVN_AUTH_SSL_NOTYETVALID   0x00000001
 Certificate is not yet valid.

#define SVN_AUTH_SSL_EXPIRED   0x00000002
 Certificate has expired.

#define SVN_AUTH_SSL_CNMISMATCH   0x00000004
 Certificate's CN (hostname) does not match the remote hostname.

#define SVN_AUTH_SSL_UNKNOWNCA   0x00000008
 Certificate authority is unknown (i.e. not trusted).

#define SVN_AUTH_SSL_OTHER   0x40000000
 Other failure. This can happen if neon has introduced a new failure bit that we do not handle yet.


Default credentials defines

Any 'default' credentials that came in through the application itself, (e.g.

--username and --password options). Property values are const char *.

#define SVN_AUTH_PARAM_DEFAULT_USERNAME   SVN_AUTH_PARAM_PREFIX "username"
#define SVN_AUTH_PARAM_DEFAULT_PASSWORD   SVN_AUTH_PARAM_PREFIX "password"

Defines

#define SVN_AUTH_CRED_SIMPLE   "svn.simple"
 Simple username/password pair credential kind. More...

#define SVN_AUTH_CRED_USERNAME   "svn.username"
 Username credential kind. More...

#define SVN_AUTH_CRED_SSL_CLIENT_CERT   "svn.ssl.client-cert"
 SSL client certificate credential type. More...

#define SVN_AUTH_CRED_SSL_CLIENT_CERT_PW   "svn.ssl.client-passphrase"
 SSL client certificate passphrase credential type. More...

#define SVN_AUTH_CRED_SSL_SERVER_TRUST   "svn.ssl.server"
 SSL server verification credential type. More...

#define SVN_AUTH_PARAM_PREFIX   "svn:auth:"
 The auth-hash prefix indicating that the parameter is global.

#define SVN_AUTH_PARAM_NON_INTERACTIVE   SVN_AUTH_PARAM_PREFIX "non-interactive"
 The application doesn't want any providers to prompt users. Property value is irrelevant; only property's existence matters.

#define SVN_AUTH_PARAM_DONT_STORE_PASSWORDS
 The application doesn't want any providers to save passwords to disk. Property value is irrelevant; only property's existence matters. More...

#define SVN_AUTH_PARAM_NO_AUTH_CACHE   SVN_AUTH_PARAM_PREFIX "no-auth-cache"
 The application doesn't want any providers to save credentials to disk. Property value is irrelevant; only property's existence matters.

#define SVN_AUTH_PARAM_SSL_SERVER_FAILURES
 The following property is for SSL server cert providers. This provides a pointer to an apr_uint32_t containing the failures detected by the certificate validator. More...

#define SVN_AUTH_PARAM_SSL_SERVER_CERT_INFO
 The following property is for SSL server cert providers. This provides the cert info (svn_auth_ssl_server_cert_info_t). More...

#define SVN_AUTH_PARAM_CONFIG   SVN_AUTH_PARAM_PREFIX "config"
 Some providers need access to the svn_config_t configuration.

#define SVN_AUTH_PARAM_SERVER_GROUP   SVN_AUTH_PARAM_PREFIX "server-group"
 The current server group.

#define SVN_AUTH_PARAM_CONFIG_DIR   SVN_AUTH_PARAM_PREFIX "config-dir"
 A configuration directory that overrides the default ~/.subversion.


Typedefs

typedef svn_auth_baton_t svn_auth_baton_t
 The type of a Subversion authentication object.

typedef svn_auth_iterstate_t svn_auth_iterstate_t
 The type of a Subversion authentication-iteration object.

typedef svn_auth_provider_t svn_auth_provider_t
 The main authentication "provider" vtable.

typedef svn_auth_provider_object_t svn_auth_provider_object_t
 A provider object, ready to be put into an array and given to svn_auth_open().

typedef svn_auth_cred_simple_t svn_auth_cred_simple_t
 SVN_AUTH_CRED_SIMPLE credentials.

typedef svn_auth_cred_username_t svn_auth_cred_username_t
 SVN_AUTH_CRED_USERNAME credentials.

typedef svn_auth_cred_ssl_client_cert_t svn_auth_cred_ssl_client_cert_t
 SVN_AUTH_CRED_SSL_CLIENT_CERT credentials.

typedef svn_auth_cred_ssl_client_cert_pw_t svn_auth_cred_ssl_client_cert_pw_t
 SVN_AUTH_CRED_SSL_CLIENT_CERT_PW credentials.

typedef svn_auth_ssl_server_cert_info_t svn_auth_ssl_server_cert_info_t
 SSL server certificate information used by SVN_AUTH_CRED_SSL_SERVER_TRUST providers.

typedef svn_auth_cred_ssl_server_trust_t svn_auth_cred_ssl_server_trust_t
 SVN_AUTH_CRED_SSL_SERVER_TRUST credentials.

typedef svn_error_t *(* svn_auth_simple_prompt_func_t )(svn_auth_cred_simple_t **cred, void *baton, const char *realm, const char *username, svn_boolean_t may_save, apr_pool_t *pool)
 Set *cred by prompting the user, allocating *cred in pool. More...

typedef svn_error_t *(* svn_auth_username_prompt_func_t )(svn_auth_cred_username_t **cred, void *baton, const char *realm, svn_boolean_t may_save, apr_pool_t *pool)
 Set *cred by prompting the user, allocating *cred in pool. More...

typedef svn_error_t *(* svn_auth_ssl_server_trust_prompt_func_t )(svn_auth_cred_ssl_server_trust_t **cred, void *baton, const char *realm, apr_uint32_t failures, const svn_auth_ssl_server_cert_info_t *cert_info, svn_boolean_t may_save, apr_pool_t *pool)
 Set *cred by prompting the user, allocating *cred in pool. More...

typedef svn_error_t *(* svn_auth_ssl_client_cert_prompt_func_t )(svn_auth_cred_ssl_client_cert_t **cred, void *baton, const char *realm, svn_boolean_t may_save, apr_pool_t *pool)
 Set *cred by prompting the user, allocating *cred in pool. More...

typedef svn_error_t *(* svn_auth_ssl_client_cert_pw_prompt_func_t )(svn_auth_cred_ssl_client_cert_pw_t **cred, void *baton, const char *realm, svn_boolean_t may_save, apr_pool_t *pool)
 Set *cred by prompting the user, allocating *cred in pool. More...


Functions

svn_auth_ssl_server_cert_info_tsvn_auth_ssl_server_cert_info_dup (const svn_auth_ssl_server_cert_info_t *info, apr_pool_t *pool)
 Return a deep copy of info, allocated in pool. More...

void svn_auth_open (svn_auth_baton_t **auth_baton, apr_array_header_t *providers, apr_pool_t *pool)
 Initialize an authentication system. More...

void svn_auth_set_parameter (svn_auth_baton_t *auth_baton, const char *name, const void *value)
 Set an authentication run-time parameter. More...

const void * svn_auth_get_parameter (svn_auth_baton_t *auth_baton, const char *name)
 Get an authentication run-time parameter. More...

svn_error_tsvn_auth_first_credentials (void **credentials, svn_auth_iterstate_t **state, const char *cred_kind, const char *realmstring, svn_auth_baton_t *auth_baton, apr_pool_t *pool)
 Get an initial set of credentials. More...

svn_error_tsvn_auth_next_credentials (void **credentials, svn_auth_iterstate_t *state, apr_pool_t *pool)
 Get another set of credentials, assuming previous ones failed to authenticate. More...

svn_error_tsvn_auth_save_credentials (svn_auth_iterstate_t *state, apr_pool_t *pool)
 Save a set of credentials. More...


Detailed Description

Overview of the svn authentication system.

We define an authentication "provider" as a module that is able to return a specific set of credentials. (e.g. username/password, certificate, etc.) Each provider implements a vtable that

For any given type of credentials, there can exist any number of separate providers -- each provider has a different method of fetching. (i.e. from a disk store, by prompting the user, etc.)

The application begins by creating an auth baton object, and "registers" some number of providers with the auth baton, in a specific order. (For example, it may first register a username/password provider that looks in disk store, then register a username/password provider that prompts the user.)

Later on, when any svn library is challenged, it asks the auth baton for the specific credentials. If the initial credentials fail to authenticate, the caller keeps requesting new credentials. Under the hood, libsvn_auth effectively "walks" over each provider (in order of registry), one at a time, until all the providers have exhausted all their retry options.

This system allows an application to flexibly define authentication behaviors (by changing registration order), and very easily write new authentication providers.

An auth_baton also contains an internal hashtable of run-time parameters; any provider or library layer can set these run-time parameters at any time, so that the provider has access to the data. (For example, certain run-time data may not be available until an authentication challenge is made.) Each credential type must document the run-time parameters that are made available to its providers.


Define Documentation

#define SVN_AUTH_CRED_SIMPLE   "svn.simple"
 

Simple username/password pair credential kind.

The following auth parameters may be available to the providers:

  • SVN_AUTH_PARAM_NO_AUTH_CACHE (void*)
  • SVN_AUTH_PARAM_DEFAULT_USERNAME (char*)
  • SVN_AUTH_PARAM_DEFAULT_PASSWORD (char*)

Definition at line 168 of file svn_auth.h.

#define SVN_AUTH_CRED_SSL_CLIENT_CERT   "svn.ssl.client-cert"
 

SSL client certificate credential type.

The following auth parameters are available to the providers:

  • SVN_AUTH_PARAM_CONFIG (svn_config_t*)
  • SVN_AUTH_PARAM_SERVER_GROUP (char*)
The following optional auth parameters are relevant to the providers:

  • SVN_AUTH_PARAM_NO_AUTH_CACHE (void*)

Definition at line 218 of file svn_auth.h.

#define SVN_AUTH_CRED_SSL_CLIENT_CERT_PW   "svn.ssl.client-passphrase"
 

SSL client certificate passphrase credential type.

Note:
The realmstring used with this credential type must be a name that makes it possible for the user to identify the certificate.
The following auth parameters are available to the providers:

  • SVN_AUTH_PARAM_CONFIG (svn_config_t*)
  • SVN_AUTH_PARAM_SERVER_GROUP (char*)
The following optional auth parameters are relevant to the providers:

  • SVN_AUTH_PARAM_NO_AUTH_CACHE (void*)

Definition at line 247 of file svn_auth.h.

#define SVN_AUTH_CRED_SSL_SERVER_TRUST   "svn.ssl.server"
 

SSL server verification credential type.

The following auth parameters are available to the providers:

  • SVN_AUTH_PARAM_CONFIG (svn_config_t*)
  • SVN_AUTH_PARAM_SERVER_GROUP (char*)
  • SVN_AUTH_PARAM_SSL_SERVER_FAILURES (apr_uint32_t*)
  • SVN_AUTH_PARAM_SSL_SERVER_CERT_INFO (svn_auth_ssl_server_cert_info_t*)
The following optional auth parameters are relevant to the providers:

  • SVN_AUTH_PARAM_NO_AUTH_CACHE (void*)

Definition at line 276 of file svn_auth.h.

#define SVN_AUTH_CRED_USERNAME   "svn.username"
 

Username credential kind.

The following optional auth parameters are relevant to the providers:

  • SVN_AUTH_PARAM_NO_AUTH_CACHE (void*)
  • SVN_AUTH_PARAM_DEFAULT_USERNAME (char*)

Definition at line 192 of file svn_auth.h.

#define SVN_AUTH_PARAM_DONT_STORE_PASSWORDS
 

Value:

SVN_AUTH_PARAM_PREFIX \
                                                 "dont-store-passwords"
The application doesn't want any providers to save passwords to disk. Property value is irrelevant; only property's existence matters.

Definition at line 523 of file svn_auth.h.

#define SVN_AUTH_PARAM_SSL_SERVER_CERT_INFO
 

Value:

SVN_AUTH_PARAM_PREFIX \
  "ssl:cert-info"
The following property is for SSL server cert providers. This provides the cert info (svn_auth_ssl_server_cert_info_t).

Definition at line 539 of file svn_auth.h.

#define SVN_AUTH_PARAM_SSL_SERVER_FAILURES
 

Value:

SVN_AUTH_PARAM_PREFIX \
  "ssl:failures"
The following property is for SSL server cert providers. This provides a pointer to an apr_uint32_t containing the failures detected by the certificate validator.

Definition at line 534 of file svn_auth.h.


Typedef Documentation

typedef svn_error_t*(* svn_auth_simple_prompt_func_t)(svn_auth_cred_simple_t **cred, void *baton, const char *realm, const char *username, svn_boolean_t may_save, apr_pool_t *pool)
 

Set *cred by prompting the user, allocating *cred in pool.

baton is an implementation-specific closure.

If realm is non-null, maybe use it in the prompt string.

If username is non-null, then the user might be prompted only for a password, but *creds would still be filled with both username and password. For example, a typical usage would be to pass username on the first call, but then leave it null for subsequent calls, on the theory that if credentials failed, it's as likely to be due to incorrect username as incorrect password.

If may_save is FALSE, the auth system does not allow the credentials to be saved (to disk). A prompt function shall not ask the user if the credentials shall be saved if may_save is FALSE. For example, a GUI client with a remember password checkbox would grey out the checkbox if may_save is FALSE.

Definition at line 352 of file svn_auth.h.

typedef svn_error_t*(* svn_auth_ssl_client_cert_prompt_func_t)( svn_auth_cred_ssl_client_cert_t **cred, void *baton, const char *realm, svn_boolean_t may_save, apr_pool_t *pool)
 

Set *cred by prompting the user, allocating *cred in pool.

baton is an implementation-specific closure. realm is a string that can be used in the prompt string.

If may_save is FALSE, the auth system does not allow the credentials to be saved (to disk). A prompt function shall not ask the user if the credentials shall be saved if may_save is FALSE. For example, a GUI client with a remember certificate checkbox would grey out the checkbox if may_save is FALSE.

Definition at line 434 of file svn_auth.h.

typedef svn_error_t*(* svn_auth_ssl_client_cert_pw_prompt_func_t)( svn_auth_cred_ssl_client_cert_pw_t **cred, void *baton, const char *realm, svn_boolean_t may_save, apr_pool_t *pool)
 

Set *cred by prompting the user, allocating *cred in pool.

baton is an implementation-specific closure. realm is a string identifying the certificate, and can be used in the prompt string.

If may_save is FALSE, the auth system does not allow the credentials to be saved (to disk). A prompt function shall not ask the user if the credentials shall be saved if may_save is FALSE. For example, a GUI client with a remember password checkbox would grey out the checkbox if may_save is FALSE.

Definition at line 452 of file svn_auth.h.

typedef svn_error_t*(* svn_auth_ssl_server_trust_prompt_func_t)( svn_auth_cred_ssl_server_trust_t **cred, void *baton, const char *realm, apr_uint32_t failures, const svn_auth_ssl_server_cert_info_t *cert_info, svn_boolean_t may_save, apr_pool_t *pool)
 

Set *cred by prompting the user, allocating *cred in pool.

baton is an implementation-specific closure.

cert_info is a structure describing the server cert that was presented to the client, and failures is a bitmask that describes exactly why the cert could not be automatically validated, composed from the constants SVN_AUTH_SSL_* (SVN_AUTH_SSL_NOTYETVALID etc.). realm is a string that can be used in the prompt string.

If may_save is FALSE, the auth system does not allow the credentials to be saved (to disk). A prompt function shall not ask the user if the credentials shall be saved if may_save is FALSE. For example, a GUI client with a trust permanently checkbox would grey out the checkbox if may_save is FALSE.

Definition at line 414 of file svn_auth.h.

typedef svn_error_t*(* svn_auth_username_prompt_func_t)(svn_auth_cred_username_t **cred, void *baton, const char *realm, svn_boolean_t may_save, apr_pool_t *pool)
 

Set *cred by prompting the user, allocating *cred in pool.

baton is an implementation-specific closure.

If realm is non-null, maybe use it in the prompt string.

If may_save is FALSE, the auth system does not allow the credentials to be saved (to disk). A prompt function shall not ask the user if the credentials shall be saved if may_save is FALSE. For example, a GUI client with a remember username checkbox would grey out the checkbox if may_save is FALSE.

Definition at line 372 of file svn_auth.h.


Function Documentation

svn_error_t* svn_auth_first_credentials void **    credentials,
svn_auth_iterstate_t **    state,
const char *    cred_kind,
const char *    realmstring,
svn_auth_baton_t   auth_baton,
apr_pool_t *    pool
 

Get an initial set of credentials.

Ask auth_baton to set *credentials to a set of credentials defined by cred_kind and valid within realmstring, or NULL if no credentials are available. Otherwise, return an iteration state in *state, so that the caller can call svn_auth_next_credentials(), in case the first set of credentials fails to authenticate.

Use pool to allocate *state, and for temporary allocation. Note that *credentials will be allocated in auth_baton's pool.

const void* svn_auth_get_parameter svn_auth_baton_t   auth_baton,
const char *    name
 

Get an authentication run-time parameter.

Return a value for run-time parameter name from auth_baton. Return NULL if the parameter doesn't exist.

svn_error_t* svn_auth_next_credentials void **    credentials,
svn_auth_iterstate_t   state,
apr_pool_t *    pool
 

Get another set of credentials, assuming previous ones failed to authenticate.

Use state to fetch a different set of *credentials, as a follow-up to svn_auth_first_credentials() or svn_auth_next_credentials(). If no more credentials are available, set *credentials to NULL.

Note that *credentials will be allocated in auth_baton's pool.

void svn_auth_open svn_auth_baton_t **    auth_baton,
apr_array_header_t *    providers,
apr_pool_t *    pool
 

Initialize an authentication system.

Return an authentication object in *auth_baton (allocated in pool) that represents a particular instance of the svn authentication system. providers is an array of svn_auth_provider_object_t pointers, already allocated in pool and intentionally ordered. These pointers will be stored within *auth_baton, grouped by credential type, and searched in this exact order.

svn_error_t* svn_auth_save_credentials svn_auth_iterstate_t   state,
apr_pool_t *    pool
 

Save a set of credentials.

Ask state to store the most recently returned credentials, presumably because they successfully authenticated. Use pool for temporary allocation. If no credentials were ever returned, do nothing.

void svn_auth_set_parameter svn_auth_baton_t   auth_baton,
const char *    name,
const void *    value
 

Set an authentication run-time parameter.

Store name / value pair as a run-time parameter in auth_baton, making the data accessible to all providers. name and value will be NOT be duplicated into the auth_baton's pool. To delete a run-time parameter, pass NULL for value.

svn_auth_ssl_server_cert_info_t* svn_auth_ssl_server_cert_info_dup const svn_auth_ssl_server_cert_info_t   info,
apr_pool_t *    pool
 

Return a deep copy of info, allocated in pool.

Since:
New in 1.3.


Generated on Wed Jun 7 11:02:15 2006 for Subversion by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002