contrib/subversion/subversion/libsvn_subr/crypto.h

   1 /*
   2  * crypto.h :  cryptographic routines
   3  *
   4  * ====================================================================
   5  *    Licensed to the Apache Software Foundation (ASF) under one
   6  *    or more contributor license agreements.  See the NOTICE file
   7  *    distributed with this work for additional information
   8  *    regarding copyright ownership.  The ASF licenses this file
   9  *    to you under the Apache License, Version 2.0 (the
  10  *    "License"); you may not use this file except in compliance
  11  *    with the License.  You may obtain a copy of the License at
  12  *
  13  *      http://www.apache.org/licenses/LICENSE-2.0
  14  *
  15  *    Unless required by applicable law or agreed to in writing,
  16  *    software distributed under the License is distributed on an
  17  *    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  18  *    KIND, either express or implied.  See the License for the
  19  *    specific language governing permissions and limitations
  20  *    under the License.
  21  * ====================================================================
  22  */
  23
  24 #ifndef SVN_LIBSVN_SUBR_CRYPTO_H
  25 #define SVN_LIBSVN_SUBR_CRYPTO_H
  26
  27 /* Test for APR crypto and RNG support */
  28 #undef SVN_HAVE_CRYPTO
  29 #include <apr.h>
  30 #include <apu.h>
  31 #if APR_HAS_RANDOM
  32 #if defined(APU_HAVE_CRYPTO) && APU_HAVE_CRYPTO
  33 #define SVN_HAVE_CRYPTO
  34 #endif
  35 #endif
  36
  37 #include "svn_types.h"
  38 #include "svn_string.h"
  39
  40 #ifdef __cplusplus
  41 extern "C" {
  42 #endif /* __cplusplus */
  43
  44
  45 /* Opaque context for cryptographic operations.  */
  46 typedef struct svn_crypto__ctx_t svn_crypto__ctx_t;
  47
  48
  49 /* Return TRUE iff Subversion's cryptographic support is available. */
  50 svn_boolean_t svn_crypto__is_available(void);
  51
  52
  53 /* Set *CTX to new Subversion cryptographic context, based on an
  54    APR-managed OpenSSL cryptography context object allocated
  55    within RESULT_POOL.  */
  56 /* ### TODO: Should this be something done once with the resulting
  57    ### svn_crypto__ctx_t object stored in svn_client_ctx_t?  */
  58 svn_error_t *
  59 svn_crypto__context_create(svn_crypto__ctx_t **ctx,
  60                            apr_pool_t *result_pool);
  61
  62
  63 /* Using a PBKDF2 derivative key based on MASTER, encrypt PLAINTEXT.
  64    The salt used for PBKDF2 is returned in SALT, and the IV used for
  65    the (AES-256/CBC) encryption is returned in IV. The resulting
  66    encrypted data is returned in CIPHERTEXT.
  67
  68    Note that MASTER may be the plaintext obtained from the user or
  69    some other OS-provided cryptographic store, or it can be a derivation
  70    such as SHA1(plaintext). As long as the same octets are passed to
  71    the decryption function, everything works just fine. (the SHA1
  72    approach is suggested, to avoid keeping the plaintext master in
  73    the process' memory space)  */
  74 svn_error_t *
  75 svn_crypto__encrypt_password(const svn_string_t **ciphertext,
  76                              const svn_string_t **iv,
  77                              const svn_string_t **salt,
  78                              svn_crypto__ctx_t *ctx,
  79                              const char *plaintext,
  80                              const svn_string_t *master,
  81                              apr_pool_t *result_pool,
  82                              apr_pool_t *scratch_pool);
  83
  84
  85 /* Given the CIPHERTEXT which was encrypted using (AES-256/CBC) with
  86    initialization vector given by IV, and a key derived using PBKDF2
  87    with SALT and MASTER... return the decrypted password in PLAINTEXT.  */
  88 svn_error_t *
  89 svn_crypto__decrypt_password(const char **plaintext,
  90                              svn_crypto__ctx_t *ctx,
  91                              const svn_string_t *ciphertext,
  92                              const svn_string_t *iv,
  93                              const svn_string_t *salt,
  94                              const svn_string_t *master,
  95                              apr_pool_t *result_pool,
  96                              apr_pool_t *scratch_pool);
  97
  98 /* Generate the stuff Subversion needs to store in order to validate a
  99    user-provided MASTER password:
 100
 101    Set *CIPHERTEXT to a block of encrypted data.
 102
 103    Set *IV and *SALT to the initialization vector and salt used for
 104    encryption.
 105
 106    Set *CHECKTEXT to the check text used for validation.
 107
 108    CTX is a Subversion cryptographic context.  MASTER is the
 109    encryption secret.
 110 */
 111 svn_error_t *
 112 svn_crypto__generate_secret_checktext(const svn_string_t **ciphertext,
 113                                       const svn_string_t **iv,
 114                                       const svn_string_t **salt,
 115                                       const char **checktext,
 116                                       svn_crypto__ctx_t *ctx,
 117                                       const svn_string_t *master,
 118                                       apr_pool_t *result_pool,
 119                                       apr_pool_t *scratch_pool);
 120
 121 /* Set *IS_VALID to TRUE iff the encryption secret MASTER successfully
 122    validates using Subversion cryptographic context CTX against
 123    CIPHERTEXT, IV, SALT, and CHECKTEXT (which where probably generated
 124    via previous call to svn_crypto__generate_secret_checktext()).
 125
 126    Use SCRATCH_POOL for necessary allocations. */
 127 svn_error_t *
 128 svn_crypto__verify_secret(svn_boolean_t *is_valid,
 129                           svn_crypto__ctx_t *ctx,
 130                           const svn_string_t *master,
 131                           const svn_string_t *ciphertext,
 132                           const svn_string_t *iv,
 133                           const svn_string_t *salt,
 134                           const char *checktext,
 135                           apr_pool_t *scratch_pool);
 136
 137 #ifdef __cplusplus
 138 }
 139 #endif /* __cplusplus */
 140
 141 #endif  /* SVN_LIBSVN_SUBR_CRYPTO_H */