Ben Collins-Sussman wrote:
> Tobias, you changed the auth API in r8013, but didn't update all the
> docstrings.
Whoups. The attached patch adds the missing docstrings, and adds more
documentation. It also changes the way the auth parameters are
documented. Previously, the providers documented which parameters they
required. I've changed that so that the parameters that are passed to
the providers are documented in svn_auth.h where the credential types
are declared and documented.
It would be great if you could take a quick lock at the patch and
comment on the new auth parameter documentation before I commit it.
By the way, is the following log message too short for a change like
this? It doen't seem useful to list the functions, etc, but I'm not
sure what you usually do in cases like this.
* subversion/include/svn_client.h
* subversion/include/svn_auth.h
Moved the documentation of the auth parameters (SVN_AUTH_PARAM_*)
to where the crential types are declared. Added more documentation
and improved the doxygen comments.
/Tobias
Index: subversion/include/svn_client.h
===================================================================
--- subversion/include/svn_client.h (revision 8094)
+++ subversion/include/svn_client.h (working copy)
@@ -138,81 +138,42 @@
* @a *provider retrieves its credentials from the configuration
* mechanism. The returned credential is used to override SSL
* security on an error.
- *
- * @a *provider requires certain run-time parameters be present in
- * the auth_baton:
- *
- * - a loaded @c svn_config_t object
- * (@c SVN_AUTH_PARAM_CONFIG)
- *
- * - the name of the server-specific settings group if available
- * (@c SVN_AUTH_PARAM_SERVER_GROUP)
- *
- * - the failure bitmask reported by the ssl certificate validator
- * (@c SVN_AUTH_PARAM_SSL_SERVER_FAILURES)
- *
- * - the certificate info (svn_auth_ssl_server_cert_info_t*)
- * (@c SVN_AUTH_PARAM_SSL_SERVER_CERT_INFO)
*/
void svn_client_get_ssl_server_trust_file_provider (
svn_auth_provider_object_t **provider,
apr_pool_t *pool);
+
/** Create and return @a *provider, an authentication provider of type @c
* svn_auth_cred_ssl_client_cert_t, allocated in @a pool.
*
* @a *provider retrieves its credentials from the configuration
* mechanism. The returned credential is used to load the appropriate
* client certificate for authentication when requested by a server.
- *
- * @a *provider requires certain run-time parameters be present in
- * the auth_baton:
- *
- * - a loaded @c svn_config_t object
- * (@c SVN_AUTH_PARAM_CONFIG)
- *
- * - the name of the server-specific settings group if available
- * (@c SVN_AUTH_PARAM_SERVER_GROUP)
*/
void svn_client_get_ssl_client_cert_file_provider (
svn_auth_provider_object_t **provider,
apr_pool_t *pool);
+
/** Create and return @a *provider, an authentication provider of type @c
* svn_auth_cred_ssl_client_cert_pw_t, allocated in @a pool.
*
* @a *provider retrieves its credentials from the configuration
* mechanism. The returned credential is used when a loaded client
* certificate is protected by a passphrase.
- *
- * @a *provider requires certain run-time parameters be present in
- * the auth_baton:
- *
- * - a loaded @c svn_config_t object
- * (@c SVN_AUTH_PARAM_CONFIG)
- *
- * - the name of the server-specific settings group if available
- * (@c SVN_AUTH_PARAM_SERVER_GROUP)
*/
void svn_client_get_ssl_client_cert_pw_file_provider (
svn_auth_provider_object_t **provider,
apr_pool_t *pool);
+
/** Create and return @a *provider, an authentication provider of type @c
* svn_auth_cred_ssl_server_trust_t, allocated in @a pool.
*
* @a *provider retrieves its credentials by using the @a prompt_func
* and @a prompt_baton. The returned credential is used to override
* SSL security on an error.
- *
- * @a *provider requires certain run-time parameters be present in
- * the @c auth_baton:
- *
- * - the failure bitmask reported by the ssl certificate validator
- * (@c SVN_AUTH_PARAM_SSL_SERVER_FAILURES)
- *
- * - the certificate info (svn_auth_ssl_server_cert_info_t*)
- * (@c SVN_AUTH_PARAM_SSL_SERVER_CERT_INFO)
*/
void svn_client_get_ssl_server_trust_prompt_provider (
svn_auth_provider_object_t **provider,
@@ -220,6 +181,7 @@
void *prompt_baton,
apr_pool_t *pool);
+
/** Create and return @a *provider, an authentication provider of type @c
* svn_auth_cred_ssl_client_cert_t, allocated in @a pool.
*
@@ -227,8 +189,6 @@
* and @a prompt_baton. The returned credential is used to load the
* appropriate client certificate for authentication when requested by
* a server. The prompt will be retried @a retry_limit times.
- *
- * @a *provider requires no run-time parameters.
*/
void svn_client_get_ssl_client_cert_prompt_provider (
svn_auth_provider_object_t **provider,
@@ -237,6 +197,7 @@
int retry_limit,
apr_pool_t *pool);
+
/** Create and return @a *provider, an authentication provider of type @c
* svn_auth_cred_ssl_client_cert_pw_t, allocated in @a pool.
*
@@ -244,8 +205,6 @@
* and @a prompt_baton. The returned credential is used when a loaded
* client certificate is protected by a passphrase. The prompt will
* be retried @a retry_limit times.
- *
- * @a *provider requires no run-time parameters.
*/
void svn_client_get_ssl_client_cert_pw_prompt_provider (
svn_auth_provider_object_t **provider,
Index: subversion/include/svn_auth.h
===================================================================
--- subversion/include/svn_auth.h (revision 8094)
+++ subversion/include/svn_auth.h (working copy)
@@ -65,8 +65,9 @@
* 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 provider must
- * document run-time parameters it requires.
+ * until an authentication challenge is made.) Each credential type
+ * must document the run-time parameters that are made available to
+ * its providers.
*
* @defgroup auth_fns authentication functions
* @{
@@ -146,82 +147,158 @@
} svn_auth_provider_object_t;
-
+
/** Specific types of credentials **/
-/** A simple username/password pair. If @a may_save is TRUE, the
- * credentials are allowed to be saved to disk. */
+/** Simple username/password pair credential kind.
+ *
+ * The following auth parameters may be available to the providers:
+ *
+ * - @c SVN_AUTH_PARAM_NO_AUTH_CACHE (@c void*)
+ * - @c SVN_AUTH_PARAM_DEFAULT_USERNAME (@c char*)
+ * - @c SVN_AUTH_PARAM_DEFAULT_PASSWORD (@c char*)
+ */
#define SVN_AUTH_CRED_SIMPLE "svn.simple"
+
+/** @c SVN_AUTH_CRED_SIMPLE credentials. */
typedef struct
{
+ /** Username */
const char *username;
+ /** Password */
const char *password;
+ /** Indicates if the credentials may be saved (to disk). For example, a
+ * GUI prompt implementation with a remember password checkbox shall set
+ * @a may_save to TRUE if the checkbox is checked.
+ */
svn_boolean_t may_save;
} svn_auth_cred_simple_t;
-/** Just a username. If @a may_save is TRUE, the credentials are
- * allowed to be saved on disk. */
+
+/** Username credential kind.
+ *
+ * The following optional auth parameters are relevant to the providers:
+ *
+ * - @c SVN_AUTH_PARAM_NO_AUTH_CACHE (@c void*)
+ * - @c SVN_AUTH_PARAM_DEFAULT_USERNAME (@c char*)
+ */
#define SVN_AUTH_CRED_USERNAME "svn.username"
+
+/** @c SVN_AUTH_CRED_USERNAME credentials. */
typedef struct
{
+ /** Username */
const char *username;
+ /** Indicates if the credentials may be saved (to disk). For example, a
+ * GUI prompt implementation with a remember username checkbox shall set
+ * @a may_save to TRUE if the checkbox is checked.
+ */
svn_boolean_t may_save;
} svn_auth_cred_username_t;
-/** SSL client authentication - this provides @a cert_file and
- * optionally @a key_file (if the private key is separate) as the
- * full paths to the files, and sets @a cert_type for the type of
- * certificate file to load. If @a may_save is TRUE, the credentials
- * are allowed to be saved to disk. */
+
+/** SSL client certificate credential type.
+ *
+ * The following auth parameters are available to the providers:
+ *
+ * - @c SVN_AUTH_PARAM_CONFIG (@c svn_config_t*)
+ * - @c SVN_AUTH_PARAM_SERVER_GROUP (@c char*)
+ *
+ * The following optional auth parameters are relevant to the providers:
+ *
+ * - @c SVN_AUTH_PARAM_NO_AUTH_CACHE (@c void*)
+ */
#define SVN_AUTH_CRED_SSL_CLIENT_CERT "svn.ssl.client-cert"
+
+/** @c SVN_AUTH_CRED_SSL_CLIENT_CERT credentials. */
typedef struct
{
+ /** Full paths to the certificate file */
const char *cert_file;
+ /** Indicates if the credentials may be saved (to disk). For example, a
+ * GUI prompt implementation with a remember certificate checkbox shall
+ * set @a may_save to TRUE if the checkbox is checked.
+ */
svn_boolean_t may_save;
} svn_auth_cred_ssl_client_cert_t;
-/** SSL client passphrase.
+
+/** SSL client certificate passphrase credential type.
*
- * @a password gets set with the appropriate password for the
- * certificate. The realmstring use with this credential type
- * must be a name that makes it possible for the user to identify
- * the certificate. If @a may_save is TRUE, the credentials are
- * allowed to be saved to disk.
+ * @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:
+ *
+ * - @c SVN_AUTH_PARAM_CONFIG (@c svn_config_t*)
+ * - @c SVN_AUTH_PARAM_SERVER_GROUP (@c char*)
+ *
+ * The following optional auth parameters are relevant to the providers:
+ *
+ * - @c SVN_AUTH_PARAM_NO_AUTH_CACHE (@c void*)
*/
#define SVN_AUTH_CRED_SSL_CLIENT_CERT_PW "svn.ssl.client-passphrase"
+
+/** @c SVN_AUTH_CRED_SSL_CLIENT_CERT_PW crentials. */
typedef struct
{
+ /** Certificate password */
const char *password;
+ /** Indicates if the credentials may be saved (to disk). For example, a
+ * GUI prompt implementation with a remember password checkbox shall set
+ * @a may_save to TRUE if the checkbox is checked.
+ */
svn_boolean_t may_save;
} svn_auth_cred_ssl_client_cert_pw_t;
-/** SSL server verification.
+
+/** SSL server verification credential type.
*
- * @a accepted_failures is a bit mask of the accepted failures. If
- * @a may_save is TRUE, the credentials are allowed to be saved to
- * disk.
+ * The following auth parameters are available to the providers:
+ *
+ * - @c SVN_AUTH_PARAM_CONFIG (@c svn_config_t*)
+ * - @c SVN_AUTH_PARAM_SERVER_GROUP (@c char*)
+ * - @c SVN_AUTH_PARAM_SSL_SERVER_FAILURES (@c apr_uint32_t*)
+ * - @c SVN_AUTH_PARAM_SSL_SERVER_CERT_INFO
+ * (@c svn_auth_ssl_server_cert_info_t*)
+ *
+ * The following optional auth parameters are relevant to the providers:
+ *
+ * - @c SVN_AUTH_PARAM_NO_AUTH_CACHE (@c void*)
*/
#define SVN_AUTH_CRED_SSL_SERVER_TRUST "svn.ssl.server"
-typedef struct
-{
- svn_boolean_t may_save;
- apr_uint32_t accepted_failures;
-} svn_auth_cred_ssl_server_trust_t;
-
-/** SSL server certificate information.
+/** SSL server certificate information used by @c
+ * SVN_AUTH_CRED_SSL_SERVER_TRUST providers.
*/
typedef struct {
+ /** Primary CN */
const char *hostname;
+ /** ASCII fingerprint */
const char *fingerprint;
+ /** ASCII date from which the certificate is valid */
const char *valid_from;
+ /** ASCII date until which the certificate is valid */
const char *valid_until;
+ /** DN of the certificate issuer */
const char *issuer_dname;
-
- /* The full certificate as base-64 encoded DER */
+ /** Base-64 encoded DER certificate representation */
const char *ascii_cert;
} svn_auth_ssl_server_cert_info_t;
+/** @c SVN_AUTH_CRED_SSL_SERVER_TRUST credentials. */
+typedef struct
+{
+ /** Indicates if the credentials may be saved (to disk). For example, a
+ * GUI prompt implementation with a checkbox to accept the certificate
+ * permanently shall set @a may_save to TRUE if the checkbox is checked.
+ */
+ svn_boolean_t may_save;
+ /** Bit mask of the accepted failures */
+ apr_uint32_t accepted_failures;
+} svn_auth_cred_ssl_server_trust_t;
+
+
/** Credential-constructing prompt functions. **/
@@ -247,7 +324,13 @@
* username and password. For example, a typical usage would be to
* pass @a 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.
+ * as likely to be due to incorrect username as incorrect password.
+ *
+ * If @a 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 @a may_save is FALSE. For example, a GUI
+ * client with a remember password checkbox would grey out the checkbox if
+ * @a may_save is FALSE.
*/
typedef svn_error_t *
(*svn_auth_simple_prompt_func_t) (svn_auth_cred_simple_t **cred,
@@ -262,6 +345,12 @@
* @a baton is an implementation-specific closure.
*
* If @a realm is non-null, maybe use it in the prompt string.
+ *
+ * If @a 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 @a may_save is FALSE. For example, a GUI
+ * client with a remember username checkbox would grey out the checkbox if
+ * @a may_save is FALSE.
*/
typedef svn_error_t *
(*svn_auth_username_prompt_func_t) (svn_auth_cred_username_t **cred,
@@ -271,6 +360,26 @@
apr_pool_t *pool);
+/** @name 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.
+ * @{
+ */
+/** Certificate is not yet valid. */
+#define SVN_AUTH_SSL_NOTYETVALID 0x00000001
+/** Certificate has expired. */
+#define SVN_AUTH_SSL_EXPIRED 0x00000002
+/** Certificate's CN (hostname) does not match the remote hostname. */
+#define SVN_AUTH_SSL_CNMISMATCH 0x00000004
+/** @brief Certificate authority is unknown (i.e. not trusted) */
+#define SVN_AUTH_SSL_UNKNOWNCA 0x00000008
+/** @brief Other failure. This can happen if neon has introduced a new
+ * failure bit that we do not handle yet. */
+#define SVN_AUTH_SSL_OTHER 0x40000000
+/** @} */
+
/** Set @a *cred by prompting the user, allocating @a *cred in @a pool.
* @a baton is an implementation-specific closure.
*
@@ -280,16 +389,12 @@
* (See the #define error flag values below.) @a realm is a string
* that can be used in the prompt string.
*
- * Note that 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 without careful consideration.
+ * If @a 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 @a may_save is FALSE. For example, a GUI
+ * client with a trust permanently checkbox would grey out the checkbox if
+ * @a may_save is FALSE.
*/
-#define SVN_AUTH_SSL_NOTYETVALID 0x00000001
-#define SVN_AUTH_SSL_EXPIRED 0x00000002
-#define SVN_AUTH_SSL_CNMISMATCH 0x00000004
-#define SVN_AUTH_SSL_UNKNOWNCA 0x00000008
-#define SVN_AUTH_SSL_OTHER 0x40000000
-
typedef svn_error_t *(*svn_auth_ssl_server_trust_prompt_func_t) (
svn_auth_cred_ssl_server_trust_t **cred,
void *baton,
@@ -303,6 +408,12 @@
/** Set @a *cred by prompting the user, allocating @a *cred in @a pool.
* @a baton is an implementation-specific closure. @a realm is a string
* that can be used in the prompt string.
+ *
+ * If @a 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 @a may_save is FALSE. For example, a GUI
+ * client with a remember certificate checkbox would grey out the checkbox
+ * if @a may_save is FALSE.
*/
typedef svn_error_t *(*svn_auth_ssl_client_cert_prompt_func_t) (
svn_auth_cred_ssl_client_cert_t **cred,
@@ -315,6 +426,12 @@
/** Set @a *cred by prompting the user, allocating @a *cred in @a pool.
* @a baton is an implementation-specific closure. @a realm is a string
* identifying the certificate, and can be used in the prompt string.
+ *
+ * If @a 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 @a may_save is FALSE. For example, a GUI
+ * client with a remember password checkbox would grey out the checkbox if
+ * @a may_save is FALSE.
*/
typedef svn_error_t *(*svn_auth_ssl_client_cert_pw_prompt_func_t) (
svn_auth_cred_ssl_client_cert_pw_t **cred,
@@ -366,42 +483,47 @@
application is responsible for placing them into the auth_baton
hash. */
-/** The auth-hash prefix indicating that the parameter is global */
+/** The auth-hash prefix indicating that the parameter is global. */
#define SVN_AUTH_PARAM_PREFIX "svn:auth:"
-/** Any 'default' credentials that came in through the application
- itself, (e.g. --username and --password options). Property values
- are const char *. */
+/** @brief 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"
-/** The application doesn't want any providers to prompt users.
- Property value is irrelevant; only property's existence matters. */
+/** @brief The application doesn't want any providers to prompt
+ * users. Property value is irrelevant; only property's existence
+ * matters. */
#define SVN_AUTH_PARAM_NON_INTERACTIVE SVN_AUTH_PARAM_PREFIX "non-interactive"
-/** The application doesn't want any providers to save credentials to disk.
- Property value is irrelevant; only property's existence matters. */
+/** @brief 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_NO_AUTH_CACHE SVN_AUTH_PARAM_PREFIX "no-auth-cache"
-/** The following property is for ssl server cert providers. This
- provides the detected failures by the certificate validator */
+/** @brief The following property is for SSL server cert providers. This
+ * provides a pointer to an @c apr_uint32_t containing the failures
+ * detected by the certificate validator. */
#define SVN_AUTH_PARAM_SSL_SERVER_FAILURES SVN_AUTH_PARAM_PREFIX \
"ssl:failures"
-/** The following property is for ssl server cert providers. This
- provides the cert info (svn_auth_ssl_server_cert_info_t). */
+/** @brief The following property is for SSL server cert providers. This
+ * provides the cert info (svn_auth_ssl_server_cert_info_t). */
#define SVN_AUTH_PARAM_SSL_SERVER_CERT_INFO SVN_AUTH_PARAM_PREFIX \
"ssl:cert-info"
-/** Some providers need access to the @c svn_config_t configuration
- for individual servers in order to properly operate */
+/** Some providers need access to the @c svn_config_t configuration. */
#define SVN_AUTH_PARAM_CONFIG SVN_AUTH_PARAM_PREFIX "config"
+
+/** The current server group. */
#define SVN_AUTH_PARAM_SERVER_GROUP SVN_AUTH_PARAM_PREFIX "server-group"
-/** A configuration directory that overrides the default
- ~/.subversion. */
+/** @brief A configuration directory that overrides the default
+ * ~/.subversion. */
#define SVN_AUTH_PARAM_CONFIG_DIR SVN_AUTH_PARAM_PREFIX "config-dir"
+
/** Get an initial set of credentials.
*
* Ask @a auth_baton to set @a *credentials to a set of credentials
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Sat Dec 27 15:15:44 2003