crypto.h (8960B)
1 // Copyright 2014 The BoringSSL Authors 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // https://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 #ifndef OPENSSL_HEADER_CRYPTO_H 16 #define OPENSSL_HEADER_CRYPTO_H 17 18 #include <openssl/base.h> // IWYU pragma: export 19 #include <openssl/sha.h> 20 21 // Upstream OpenSSL defines |OPENSSL_malloc|, etc., in crypto.h rather than 22 // mem.h. 23 #include <openssl/mem.h> 24 25 // Upstream OpenSSL defines |CRYPTO_LOCK|, etc., in crypto.h rather than 26 // thread.h. 27 #include <openssl/thread.h> 28 29 30 #if defined(__cplusplus) 31 extern "C" { 32 #endif 33 34 35 // crypto.h contains functions for library-wide initialization and properties. 36 37 38 // CRYPTO_is_confidential_build returns one if the linked version of BoringSSL 39 // has been built with the BORINGSSL_CONFIDENTIAL define and zero otherwise. 40 // 41 // This is used by some consumers to identify whether they are using an 42 // internal version of BoringSSL. 43 OPENSSL_EXPORT int CRYPTO_is_confidential_build(void); 44 45 // CRYPTO_has_asm returns one unless BoringSSL was built with OPENSSL_NO_ASM, 46 // in which case it returns zero. 47 OPENSSL_EXPORT int CRYPTO_has_asm(void); 48 49 // BORINGSSL_self_test triggers most of the FIPS KAT-based self tests. It 50 // returns one on success and zero on error. It currently skips the SLH-DSA 51 // tests, which take a really long time to run. 52 OPENSSL_EXPORT int BORINGSSL_self_test(void); 53 54 // BORINGSSL_self_test_all triggers all of the FIPS KAT-based self tests. This 55 // is the 'self-test' entry point required by FIPS 140. It returns one on 56 // success and zero on error. This test will take a very long time to run. You 57 // probably do not want to run this in a resource or time constrained test. 58 OPENSSL_EXPORT int BORINGSSL_self_test_all(void); 59 60 // BORINGSSL_integrity_test triggers the module's integrity test where the code 61 // and data of the module is matched against a hash injected at build time. It 62 // returns one on success or zero if there's a mismatch. This function only 63 // exists if the module was built in FIPS mode without ASAN. 64 OPENSSL_EXPORT int BORINGSSL_integrity_test(void); 65 66 // CRYPTO_pre_sandbox_init initializes the crypto library, pre-acquiring some 67 // unusual resources to aid running in sandboxed environments. It is safe to 68 // call this function multiple times and concurrently from multiple threads. 69 // 70 // For more details on using BoringSSL in a sandboxed environment, see 71 // SANDBOXING.md in the source tree. 72 OPENSSL_EXPORT void CRYPTO_pre_sandbox_init(void); 73 74 #if defined(OPENSSL_ARM) && defined(OPENSSL_LINUX) && \ 75 !defined(OPENSSL_STATIC_ARMCAP) 76 // CRYPTO_needs_hwcap2_workaround returns one if the ARMv8 AArch32 AT_HWCAP2 77 // workaround was needed. See https://crbug.com/boringssl/46. 78 OPENSSL_EXPORT int CRYPTO_needs_hwcap2_workaround(void); 79 #endif // OPENSSL_ARM && OPENSSL_LINUX && !OPENSSL_STATIC_ARMCAP 80 81 #if defined(FUZZING_BUILD_MODE_UNSAFE_FOR_PRODUCTION) 82 // CRYPTO_set_fuzzer_mode, in non-production fuzzer builds, configures a "fuzzer 83 // mode" in the library, which disables various signature checks and disables 84 // encryption in parts of TLS. 85 // 86 // By default, fuzzer builds make the PRNG deterministic (and thus unsafe for 87 // production), but continue to run cryptographic operations as usual. This 88 // allows a fuzzer build of BoringSSL to be used dependency of fuzzer builds of 89 // other libraries, without changing in semantics. This function enables further 90 // incompatible changes intended for fuzzing BoringSSL itself. 91 OPENSSL_EXPORT void CRYPTO_set_fuzzer_mode(int enabled); 92 #endif 93 94 95 // FIPS monitoring 96 97 // FIPS_mode returns zero unless BoringSSL is built with BORINGSSL_FIPS, in 98 // which case it returns one. 99 OPENSSL_EXPORT int FIPS_mode(void); 100 101 // fips_counter_t denotes specific APIs/algorithms. A counter is maintained for 102 // each in FIPS mode so that tests can be written to assert that the expected, 103 // FIPS functions are being called by a certain peice of code. 104 enum fips_counter_t { 105 fips_counter_evp_aes_128_gcm = 0, 106 fips_counter_evp_aes_256_gcm = 1, 107 fips_counter_evp_aes_128_ctr = 2, 108 fips_counter_evp_aes_256_ctr = 3, 109 110 fips_counter_max = 3, 111 }; 112 113 // FIPS_read_counter returns a counter of the number of times the specific 114 // function denoted by |counter| has been used. This always returns zero unless 115 // BoringSSL was built with BORINGSSL_FIPS_COUNTERS defined. 116 OPENSSL_EXPORT size_t FIPS_read_counter(enum fips_counter_t counter); 117 118 119 // Deprecated functions. 120 121 // OPENSSL_VERSION_TEXT contains a string the identifies the version of 122 // “OpenSSL”. node.js requires a version number in this text. 123 #define OPENSSL_VERSION_TEXT "OpenSSL 1.1.1 (compatible; BoringSSL)" 124 125 #define OPENSSL_VERSION 0 126 #define OPENSSL_CFLAGS 1 127 #define OPENSSL_BUILT_ON 2 128 #define OPENSSL_PLATFORM 3 129 #define OPENSSL_DIR 4 130 131 // OpenSSL_version is a compatibility function that returns the string 132 // "BoringSSL" if |which| is |OPENSSL_VERSION| and placeholder strings 133 // otherwise. 134 OPENSSL_EXPORT const char *OpenSSL_version(int which); 135 136 #define SSLEAY_VERSION OPENSSL_VERSION 137 #define SSLEAY_CFLAGS OPENSSL_CFLAGS 138 #define SSLEAY_BUILT_ON OPENSSL_BUILT_ON 139 #define SSLEAY_PLATFORM OPENSSL_PLATFORM 140 #define SSLEAY_DIR OPENSSL_DIR 141 142 // SSLeay_version calls |OpenSSL_version|. 143 OPENSSL_EXPORT const char *SSLeay_version(int which); 144 145 // SSLeay is a compatibility function that returns OPENSSL_VERSION_NUMBER from 146 // base.h. 147 OPENSSL_EXPORT unsigned long SSLeay(void); 148 149 // OpenSSL_version_num is a compatibility function that returns 150 // OPENSSL_VERSION_NUMBER from base.h. 151 OPENSSL_EXPORT unsigned long OpenSSL_version_num(void); 152 153 // CRYPTO_malloc_init returns one. 154 OPENSSL_EXPORT int CRYPTO_malloc_init(void); 155 156 // OPENSSL_malloc_init returns one. 157 OPENSSL_EXPORT int OPENSSL_malloc_init(void); 158 159 // ENGINE_load_builtin_engines does nothing. 160 OPENSSL_EXPORT void ENGINE_load_builtin_engines(void); 161 162 // ENGINE_register_all_complete returns one. 163 OPENSSL_EXPORT int ENGINE_register_all_complete(void); 164 165 // OPENSSL_load_builtin_modules does nothing. 166 OPENSSL_EXPORT void OPENSSL_load_builtin_modules(void); 167 168 // OPENSSL_INIT_* are options in OpenSSL to configure the library. In BoringSSL, 169 // they do nothing. 170 #define OPENSSL_INIT_NO_LOAD_CRYPTO_STRINGS 0 171 #define OPENSSL_INIT_LOAD_CRYPTO_STRINGS 0 172 #define OPENSSL_INIT_ADD_ALL_CIPHERS 0 173 #define OPENSSL_INIT_ADD_ALL_DIGESTS 0 174 #define OPENSSL_INIT_NO_ADD_ALL_CIPHERS 0 175 #define OPENSSL_INIT_NO_ADD_ALL_DIGESTS 0 176 #define OPENSSL_INIT_LOAD_CONFIG 0 177 #define OPENSSL_INIT_NO_LOAD_CONFIG 0 178 #define OPENSSL_INIT_NO_ATEXIT 0 179 #define OPENSSL_INIT_ATFORK 0 180 #define OPENSSL_INIT_ENGINE_RDRAND 0 181 #define OPENSSL_INIT_ENGINE_DYNAMIC 0 182 #define OPENSSL_INIT_ENGINE_OPENSSL 0 183 #define OPENSSL_INIT_ENGINE_CRYPTODEV 0 184 #define OPENSSL_INIT_ENGINE_CAPI 0 185 #define OPENSSL_INIT_ENGINE_PADLOCK 0 186 #define OPENSSL_INIT_ENGINE_AFALG 0 187 #define OPENSSL_INIT_ENGINE_ALL_BUILTIN 0 188 189 // OPENSSL_init_crypto returns one. 190 OPENSSL_EXPORT int OPENSSL_init_crypto(uint64_t opts, 191 const OPENSSL_INIT_SETTINGS *settings); 192 193 // OPENSSL_cleanup does nothing. 194 OPENSSL_EXPORT void OPENSSL_cleanup(void); 195 196 // FIPS_mode_set returns one if |on| matches whether BoringSSL was built with 197 // |BORINGSSL_FIPS| and zero otherwise. 198 OPENSSL_EXPORT int FIPS_mode_set(int on); 199 200 // FIPS_module_name returns the name of the FIPS module. 201 OPENSSL_EXPORT const char *FIPS_module_name(void); 202 203 // FIPS_module_hash returns the 32-byte hash of the FIPS module. 204 OPENSSL_EXPORT const uint8_t *FIPS_module_hash(void); 205 206 // FIPS_version returns the version of the FIPS module, or zero if the build 207 // isn't exactly at a verified version. The version, expressed in base 10, will 208 // be a date in the form yyyymmddXX where XX is often "00", but can be 209 // incremented if multiple versions are defined on a single day. 210 // 211 // (This format exceeds a |uint32_t| in the year 4294.) 212 OPENSSL_EXPORT uint32_t FIPS_version(void); 213 214 // FIPS_query_algorithm_status returns one if |algorithm| is FIPS validated in 215 // the current BoringSSL and zero otherwise. 216 OPENSSL_EXPORT int FIPS_query_algorithm_status(const char *algorithm); 217 218 #if defined(OPENSSL_ARM) && defined(OPENSSL_LINUX) && \ 219 !defined(OPENSSL_STATIC_ARMCAP) 220 // CRYPTO_has_broken_NEON returns zero. 221 OPENSSL_EXPORT int CRYPTO_has_broken_NEON(void); 222 #endif 223 224 // CRYPTO_library_init does nothing. Historically, it was needed in some build 225 // configurations to initialization the library. This is no longer necessary. 226 OPENSSL_EXPORT void CRYPTO_library_init(void); 227 228 229 #if defined(__cplusplus) 230 } // extern C 231 #endif 232 233 #endif // OPENSSL_HEADER_CRYPTO_H