lib/crypto/gnutls_helpers.h

   1 /*
   2  * Copyright (c) 2019      Andreas Schneider <asn@samba.org>
   3  *
   4  * This program is free software: you can redistribute it and/or modify
   5  * it under the terms of the GNU General Public License as published by
   6  * the Free Software Foundation, either version 3 of the License, or
   7  * (at your option) any later version.
   8  *
   9  * This program is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  * GNU General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU General Public License
  15  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  16  */
  17
  18 #ifndef _GNUTLS_HELPERS_H
  19 #define _GNUTLS_HELPERS_H
  20
  21 #include <gnutls/gnutls.h>
  22
  23 #include "libcli/util/ntstatus.h"
  24 #include "libcli/util/werror.h"
  25 #include "lib/util/data_blob.h"
  26
  27 /* Those macros are only available in GnuTLS >= 3.6.4 */
  28 #ifndef GNUTLS_FIPS140_SET_LAX_MODE
  29 #define GNUTLS_FIPS140_SET_LAX_MODE()
  30 #endif
  31
  32 #ifndef GNUTLS_FIPS140_SET_STRICT_MODE
  33 #define GNUTLS_FIPS140_SET_STRICT_MODE()
  34 #endif
  35
  36 #ifdef DOXYGEN
  37 /**
  38  * @brief Convert a gnutls error code to a corresponding NTSTATUS.
  39  *
  40  * @param[in]  gnutls_rc      The GnuTLS return code.
  41  *
  42  * @param[in]  blocked_status The NTSTATUS return code which should be returned
  43  *                            in case the e.g. the cipher might be blocked due
  44  *                            to FIPS mode.
  45  *
  46  * @return A corresponding NTSTATUS code.
  47  */
  48 NTSTATUS gnutls_error_to_ntstatus(int gnutls_rc, NTSTATUS blocked_status);
  49 #else
  50 NTSTATUS _gnutls_error_to_ntstatus(int gnutls_rc,
  51                                    NTSTATUS blocked_status,
  52                                    const char *function,
  53                                    const char *location);
  54 #define gnutls_error_to_ntstatus(gnutls_rc, blocked_status) \
  55         _gnutls_error_to_ntstatus(gnutls_rc,                \
  56                                   blocked_status,           \
  57                                   __FUNCTION__,             \
  58                                   __location__)
  59 #endif
  60
  61 #ifdef DOXYGEN
  62 /**
  63  * @brief Convert a gnutls error code to a corresponding WERROR.
  64  *
  65  * @param[in]  gnutls_rc      The GnuTLS return code.
  66  *
  67  * @param[in]  blocked_werr   The WERROR code which should be returned if e.g
  68  *                            the cipher we want to used it not allowed to be
  69  *                            used because of FIPS mode.
  70  *
  71  * @return A corresponding WERROR code.
  72  */
  73 WERROR gnutls_error_to_werror(int gnutls_rc, WERROR blocked_werr);
  74 #else
  75 WERROR _gnutls_error_to_werror(int gnutls_rc,
  76                                WERROR blocked_werr,
  77                                const char *function,
  78                                const char *location);
  79 #define gnutls_error_to_werror(gnutls_rc, blocked_werr) \
  80         _gnutls_error_to_werror(gnutls_rc,              \
  81                                 blocked_werr,           \
  82                                 __FUNCTION__,           \
  83                                 __location__)
  84 #endif
  85
  86 enum samba_gnutls_direction { SAMBA_GNUTLS_ENCRYPT, SAMBA_GNUTLS_DECRYPT };
  87
  88 /**
  89  * @brief Encrypt or decrypt a data blob using RC4 with a key and salt.
  90  *
  91  * One of the key input should be a session key and the other a confounder
  92  * (aka salt). Which one depends on the implementation details of the
  93  * protocol.
  94  *
  95  * @param[in]  key_input1 Either a session_key or a confounder.
  96  *
  97  * @param[in]  key_input2 Either a session_key or a confounder.
  98  *
  99  * @param[in]  data       The data blob to either encrypt or decrypt. The data
 100  *                        will be encrypted or decrypted in place.
 101  *
 102  * @param[in]  encrypt    The encryption direction.
 103  *
 104  * @return A gnutls error code.
 105  */
 106 int samba_gnutls_arcfour_confounded_md5(const DATA_BLOB *key_input1,
 107                                         const DATA_BLOB *key_input2,
 108                                         DATA_BLOB *data,
 109                                         enum samba_gnutls_direction encrypt);
 110
 111 /**
 112  * @brief Encrypted a secret plaintext using AEAD_AES_256_CBC_HMAC_SHA512 and
 113  * the session key.
 114  *
 115  * This encrypts a secret plaintext using AEAD_AES_256_CBC_HMAC_SHA512 with a
 116  * key (can be the session key or PBKDF2 password). This is used in SAMR and
 117  * LSA.
 118  *
 119  * @param mem_ctx       The memory context to allocate the cipher text pointer.
 120  *
 121  * @param plaintext     The secret to encrypt
 122  *
 123  * @param cek           The content encryption key to encrypt the secret.
 124  *
 125  * @param key_salt      The salt used to calculate the encryption key.
 126  *
 127  * @param key_salt      The salt used to calculate the mac key.
 128
 129  * @param iv            The initialization vector used for the encryption.
 130  *
 131  * @param pciphertext   A pointer to store the cipher text.
 132  *
 133  * @param pauth_tag[64] An array to store the auth tag.
 134  *
 135  * @return NT_STATUS_OK on success, an nt status error code otherwise.
 136  */
 137 NTSTATUS
 138 samba_gnutls_aead_aes_256_cbc_hmac_sha512_encrypt(TALLOC_CTX *mem_ctx,
 139                                                   const DATA_BLOB *plaintext,
 140                                                   const DATA_BLOB *cek,
 141                                                   const DATA_BLOB *key_salt,
 142                                                   const DATA_BLOB *mac_salt,
 143                                                   const DATA_BLOB *iv,
 144                                                   DATA_BLOB *pciphertext,
 145                                                   uint8_t pauth_tag[64]);
 146
 147 /**
 148  * @brief Decypt cipher text using AEAD_AES_256_CBC_HMAC_SHA512 and the session
 149  * key.
 150  *
 151  * This decrypts the cipher text using AEAD_AES_256_CBC_HMAC_SHA512 with the
 152  * given content decryption key key. The plaintext will be zeroed as soon as the
 153  * data blob is freed.
 154  *
 155  * @param mem_ctx       The memory context to allocate the plaintext on.
 156  *
 157  * @param ciphertext    The cipher text to decrypt.
 158  *
 159  * @param cdk           The content decryption key.
 160  *
 161  * @param key_salt      The salt used to calculate the encryption key.
 162  *
 163  * @param key_salt      The salt used to calculate the mac key.
 164
 165  * @param iv            The initialization vector used for the encryption.
 166  *
 167  * @param auth_tag[64]  The authentication blob to be verified.
 168  *
 169  * @param pplaintext    A pointer to a DATA_BLOB to store the plaintext.
 170  *
 171  * @return NT_STATUS_OK on success, an nt status error code otherwise.
 172  */
 173 NTSTATUS
 174 samba_gnutls_aead_aes_256_cbc_hmac_sha512_decrypt(TALLOC_CTX *mem_ctx,
 175                                                   const DATA_BLOB *ciphertext,
 176                                                   const DATA_BLOB *cdk,
 177                                                   const DATA_BLOB *key_salt,
 178                                                   const DATA_BLOB *mac_salt,
 179                                                   const DATA_BLOB *iv,
 180                                                   const uint8_t auth_tag[64],
 181                                                   DATA_BLOB *pplaintext);
 182
 183 /**
 184  * @brief Check if weak crypto is allowed.
 185  *
 186  * @return true if weak crypo is allowed, false otherwise.
 187  */
 188 bool samba_gnutls_weak_crypto_allowed(void);
 189
 190 /**
 191  * @brief Derive a key using the NIST SP 800‐108 algorithm.
 192  *
 193  * The details of the algorithm can be found at
 194  * https://csrc.nist.gov/pubs/sp/800/108/r1/final.
 195  *
 196  * @param KI            The key‐derivation key used as input.
 197  *
 198  * @param KI_len        The length of the key‐derivation key.
 199  *
 200  * @param FixedData     If non‐NULL, specifies fixed data to be used in place of
 201  *                      that constructed from the Label and Context parameters.
 202  *
 203  * @param FixedData_len The length of the fixed data, if it is present.
 204  *
 205  * @param Label         A label that identifies the purpose for the derived key.
 206  *                      Ignored if FixedData is non‐NULL.
 207  *
 208  * @param Label_len     The length of the label.
 209  *
 210  * @param Context       Information related to the derived key. Ignored if
 211  *                      FixedData is non‐NULL.
 212  *
 213  * @param Context_len   The length of the context data.
 214  *
 215  * @param algorithm     The HMAC algorithm to use.
 216  *
 217  * @param KO            A buffer to receive the derived key.
 218  *
 219  * @param KO_len        The length of the key to be derived.
 220  *
 221  * @return NT_STATUS_OK on success, an NT status error code otherwise.
 222  */
 223 NTSTATUS samba_gnutls_sp800_108_derive_key(
 224         const uint8_t *KI,
 225         size_t KI_len,
 226         const uint8_t *FixedData,
 227         size_t FixedData_len,
 228         const uint8_t *Label,
 229         size_t Label_len,
 230         const uint8_t *Context,
 231         size_t Context_len,
 232         const gnutls_mac_algorithm_t algorithm,
 233         uint8_t *KO,
 234         size_t KO_len);
 235
 236 #ifndef HAVE_GNUTLS_CB_TLS_SERVER_END_POINT
 237 int legacy_gnutls_server_end_point_cb(gnutls_session_t session,
 238                                       bool is_server,
 239                                       gnutls_datum_t * cb);
 240 #endif /* HAVE_GNUTLS_CB_TLS_SERVER_END_POINT */
 241
 242 #endif /* _GNUTLS_HELPERS_H */