contrib/subversion/subversion/include/private/svn_auth_private.h

   1 /**
   2  * @copyright
   3  * ====================================================================
   4  *    Licensed to the Apache Software Foundation (ASF) under one
   5  *    or more contributor license agreements.  See the NOTICE file
   6  *    distributed with this work for additional information
   7  *    regarding copyright ownership.  The ASF licenses this file
   8  *    to you under the Apache License, Version 2.0 (the
   9  *    "License"); you may not use this file except in compliance
  10  *    with the License.  You may obtain a copy of the License at
  11  *
  12  *      http://www.apache.org/licenses/LICENSE-2.0
  13  *
  14  *    Unless required by applicable law or agreed to in writing,
  15  *    software distributed under the License is distributed on an
  16  *    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  17  *    KIND, either express or implied.  See the License for the
  18  *    specific language governing permissions and limitations
  19  *    under the License.
  20  * ====================================================================
  21  * @endcopyright
  22  *
  23  * @file svn_auth_private.h
  24  * @brief Subversion's authentication system - Internal routines
  25  */
  26
  27 #ifndef SVN_AUTH_PRIVATE_H
  28 #define SVN_AUTH_PRIVATE_H
  29
  30 #include <apr_pools.h>
  31 #include <apr_hash.h>
  32
  33 #include "svn_types.h"
  34 #include "svn_error.h"
  35
  36 #ifdef __cplusplus
  37 extern "C" {
  38 #endif /* __cplusplus */
  39
  40 /** SSL server authority verification credential type.
  41  *
  42  * The followin auth parameters are available to the providers:
  43  *
  44  * - @c SVN_AUTH_PARAM_SSL_SERVER_FAILURES (@c apr_uint32_t*)
  45  * - @c SVN_AUTH_PARAM_SSL_SERVER_CERT_INFO
  46  *      (@c svn_auth_ssl_server_cert_info_t*)
  47  *
  48  * The following optional auth parameters are relevant to the providers:
  49  *
  50  * - @c SVN_AUTH_PARAM_NO_AUTH_CACHE (@c void*)
  51  *
  52  * @since New in 1.9.
  53  */
  54 #define SVN_AUTH_CRED_SSL_SERVER_AUTHORITY "svn.ssl.server.authority"
  55
  56
  57
  58 /* If you add a password type for a provider which stores
  59  * passwords on disk in encrypted form, remember to update
  60  * svn_auth__simple_save_creds_helper. Otherwise it will be
  61  * assumed that your provider stores passwords in plaintext. */
  62 #define SVN_AUTH__SIMPLE_PASSWORD_TYPE             "simple"
  63 #define SVN_AUTH__WINCRYPT_PASSWORD_TYPE           "wincrypt"
  64 #define SVN_AUTH__KEYCHAIN_PASSWORD_TYPE           "keychain"
  65 #define SVN_AUTH__KWALLET_PASSWORD_TYPE            "kwallet"
  66 #define SVN_AUTH__GNOME_KEYRING_PASSWORD_TYPE      "gnome-keyring"
  67 #define SVN_AUTH__GPG_AGENT_PASSWORD_TYPE          "gpg-agent"
  68
  69 /* A function that stores in *PASSWORD (potentially after decrypting it)
  70    the user's password.  It might be obtained directly from CREDS, or
  71    from an external store, using REALMSTRING and USERNAME as keys.
  72    (The behavior is undefined if REALMSTRING or USERNAME are NULL.)
  73    If NON_INTERACTIVE is set, the user must not be involved in the
  74    retrieval process.  Set *DONE to TRUE if a password was stored
  75    in *PASSWORD, to FALSE otherwise. POOL is used for any necessary
  76    allocation. */
  77 typedef svn_error_t * (*svn_auth__password_get_t)
  78   (svn_boolean_t *done,
  79    const char **password,
  80    apr_hash_t *creds,
  81    const char *realmstring,
  82    const char *username,
  83    apr_hash_t *parameters,
  84    svn_boolean_t non_interactive,
  85    apr_pool_t *pool);
  86
  87 /* A function that stores PASSWORD (or some encrypted version thereof)
  88    either directly in CREDS, or externally using REALMSTRING and USERNAME
  89    as keys into the external store.  If NON_INTERACTIVE is set, the user
  90    must not be involved in the storage process. Set *DONE to TRUE if the
  91    password was store, to FALSE otherwise. POOL is used for any necessary
  92    allocation. */
  93 typedef svn_error_t * (*svn_auth__password_set_t)
  94   (svn_boolean_t *done,
  95    apr_hash_t *creds,
  96    const char *realmstring,
  97    const char *username,
  98    const char *password,
  99    apr_hash_t *parameters,
 100    svn_boolean_t non_interactive,
 101    apr_pool_t *pool);
 102
 103 /* Use PARAMETERS and REALMSTRING to set *CREDENTIALS to a set of
 104    pre-cached authentication credentials pulled from the simple
 105    credential cache store identified by PASSTYPE.  PASSWORD_GET is
 106    used to obtain the password value.  Allocate *CREDENTIALS from
 107    POOL.
 108
 109    NOTE:  This function is a common implementation of code used by
 110    several of the simple credential providers (the default disk cache
 111    mechanism, Windows CryptoAPI, GNOME Keyring, etc.), typically in
 112    their "first_creds" implementation.  */
 113 svn_error_t *
 114 svn_auth__simple_creds_cache_get(void **credentials,
 115                                  void **iter_baton,
 116                                  void *provider_baton,
 117                                  apr_hash_t *parameters,
 118                                  const char *realmstring,
 119                                  svn_auth__password_get_t password_get,
 120                                  const char *passtype,
 121                                  apr_pool_t *pool);
 122
 123 /* Use PARAMETERS and REALMSTRING to save CREDENTIALS in the simple
 124    credential cache store identified by PASSTYPE.  PASSWORD_SET is
 125    used to do the actual storage.  Use POOL for necessary allocations.
 126    Set *SAVED according to whether or not the credentials were
 127    successfully stored.
 128
 129    NOTE:  This function is a common implementation of code used by
 130    several of the simple credential providers (the default disk cache
 131    mechanism, Windows CryptoAPI, GNOME Keyring, etc.) typically in
 132    their "save_creds" implementation.  */
 133 svn_error_t *
 134 svn_auth__simple_creds_cache_set(svn_boolean_t *saved,
 135                                  void *credentials,
 136                                  void *provider_baton,
 137                                  apr_hash_t *parameters,
 138                                  const char *realmstring,
 139                                  svn_auth__password_set_t password_set,
 140                                  const char *passtype,
 141                                  apr_pool_t *pool);
 142
 143 /* Implementation of svn_auth__password_get_t that retrieves
 144    the plaintext password from CREDS when USERNAME matches the stored
 145    credentials. */
 146 svn_error_t *
 147 svn_auth__simple_password_get(svn_boolean_t *done,
 148                               const char **password,
 149                               apr_hash_t *creds,
 150                               const char *realmstring,
 151                               const char *username,
 152                               apr_hash_t *parameters,
 153                               svn_boolean_t non_interactive,
 154                               apr_pool_t *pool);
 155
 156 /* Implementation of svn_auth__password_set_t that stores
 157    the plaintext password in CREDS. */
 158 svn_error_t *
 159 svn_auth__simple_password_set(svn_boolean_t *done,
 160                               apr_hash_t *creds,
 161                               const char *realmstring,
 162                               const char *username,
 163                               const char *password,
 164                               apr_hash_t *parameters,
 165                               svn_boolean_t non_interactive,
 166                               apr_pool_t *pool);
 167
 168
 169 /* Use PARAMETERS and REALMSTRING to set *CREDENTIALS to a set of
 170    pre-cached authentication credentials pulled from the SSL client
 171    certificate passphrase credential cache store identified by
 172    PASSTYPE.  PASSPHRASE_GET is used to obtain the passphrase value.
 173    Allocate *CREDENTIALS from POOL.
 174
 175    NOTE:  This function is a common implementation of code used by
 176    several of the ssl client passphrase credential providers (the
 177    default disk cache mechanism, Windows CryptoAPI, GNOME Keyring,
 178    etc.), typically in their "first_creds" implementation.  */
 179 svn_error_t *
 180 svn_auth__ssl_client_cert_pw_cache_get(void **credentials,
 181                                        void **iter_baton,
 182                                        void *provider_baton,
 183                                        apr_hash_t *parameters,
 184                                        const char *realmstring,
 185                                        svn_auth__password_get_t passphrase_get,
 186                                        const char *passtype,
 187                                        apr_pool_t *pool);
 188
 189 /* Use PARAMETERS and REALMSTRING to save CREDENTIALS in the SSL
 190    client certificate passphrase credential cache store identified by
 191    PASSTYPE.  PASSPHRASE_SET is used to do the actual storage.  Use
 192    POOL for necessary allocations.  Set *SAVED according to whether or
 193    not the credentials were successfully stored.
 194
 195    NOTE:  This function is a common implementation of code used by
 196    several of the simple credential providers (the default disk cache
 197    mechanism, Windows CryptoAPI, GNOME Keyring, etc.) typically in
 198    their "save_creds" implementation.  */
 199 svn_error_t *
 200 svn_auth__ssl_client_cert_pw_cache_set(svn_boolean_t *saved,
 201                                        void *credentials,
 202                                        void *provider_baton,
 203                                        apr_hash_t *parameters,
 204                                        const char *realmstring,
 205                                        svn_auth__password_set_t passphrase_set,
 206                                        const char *passtype,
 207                                        apr_pool_t *pool);
 208
 209 /* This implements the svn_auth__password_get_t interface.
 210    Set **PASSPHRASE to the plaintext passphrase retrieved from CREDS;
 211    ignore other parameters. */
 212 svn_error_t *
 213 svn_auth__ssl_client_cert_pw_get(svn_boolean_t *done,
 214                                  const char **passphrase,
 215                                  apr_hash_t *creds,
 216                                  const char *realmstring,
 217                                  const char *username,
 218                                  apr_hash_t *parameters,
 219                                  svn_boolean_t non_interactive,
 220                                  apr_pool_t *pool);
 221
 222 /* This implements the svn_auth__password_set_t interface.
 223    Store PASSPHRASE in CREDS; ignore other parameters. */
 224 svn_error_t *
 225 svn_auth__ssl_client_cert_pw_set(svn_boolean_t *done,
 226                                  apr_hash_t *creds,
 227                                  const char *realmstring,
 228                                  const char *username,
 229                                  const char *passphrase,
 230                                  apr_hash_t *parameters,
 231                                  svn_boolean_t non_interactive,
 232                                  apr_pool_t *pool);
 233
 234 #if (defined(WIN32) && !defined(__MINGW32__)) || defined(DOXYGEN)
 235 /**
 236  * Set @a *provider to an authentication provider that implements
 237  * ssl authority verification via the Windows CryptoApi.
 238  *
 239  * This provider automatically validates authority certificates with
 240  * the CryptoApi, like Internet Explorer and the Windows network API do.
 241  * This allows the rollout of root certificates via Windows Domain
 242  * policies, instead of Subversion specific configuration.
 243  *
 244  * @note This function is only available on Windows.
 245  */
 246 void
 247 svn_auth__get_windows_ssl_server_authority_provider(
 248                             svn_auth_provider_object_t **provider,
 249                             apr_pool_t *pool);
 250 #endif
 251
 252
 253 #ifdef __cplusplus
 254 }
 255 #endif /* __cplusplus */
 256
 257 #endif /* SVN_AUTH_PRIVATE_H */