folly/ssl/Init.h

   1 /*
   2  * Copyright 2004-present Facebook, Inc.
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *   http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16 #pragma once
  17
  18 #include <map>
  19
  20 #include <folly/ssl/OpenSSLLockTypes.h>
  21
  22 namespace folly {
  23 namespace ssl {
  24 /**
  25  * Initializes openssl. This should be invoked once, during the start of an
  26  * application. Subsequent calls to this function are no-ops.
  27  *
  28  * For OpenSSL < 1.1.0, any lock types should be set with setLockTypes prior to
  29  * the call to folly::ssl::init()
  30  */
  31 void init();
  32
  33 /**
  34  * Cleans up openssl. This should be invoked at most once during the lifetime
  35  * of the application. OpenSSL >= 1.1.0 users do not need to manually invoke
  36  * this method, as OpenSSL will automatically cleanup itself during the exit
  37  * of the application.
  38  */
  39 void cleanup();
  40
  41 /**
  42  * Mark openssl as initialized without actually performing any initialization.
  43  * Please use this only if you are using a library which requires that it must
  44  * make its own calls to SSL_library_init() and related functions.
  45  */
  46 void markInitialized();
  47
  48 /**
  49  * Set preferences for how to treat locks in OpenSSL.  This must be
  50  * called before folly::ssl::init(), otherwise the defaults will be used.
  51  *
  52  * OpenSSL has a lock for each module rather than for each object or
  53  * data that needs locking.  Some locks protect only refcounts, and
  54  * might be better as spinlocks rather than mutexes.  Other locks
  55  * may be totally unnecessary if the objects being protected are not
  56  * shared between threads in the application.
  57  *
  58  * For a list of OpenSSL lock types, refer to crypto/crypto.h.
  59  *
  60  * By default, all locks are initialized as mutexes.  OpenSSL's lock usage
  61  * may change from version to version and you should know what you are doing
  62  * before disabling any locks entirely.
  63  *
  64  * In newer versions of OpenSSL (>= 1.1.0), OpenSSL manages its own locks,
  65  * and this function is a no-op.
  66  *
  67  * Example: if you don't share SSL sessions between threads in your
  68  * application, you may be able to do this
  69  *
  70  * setSSLLockTypes({{
  71  *  CRYPTO_LOCK_SSL_SESSION,
  72  *  SSLContext::SSLLockType::LOCK_NONE
  73  * }})
  74  */
  75 void setLockTypes(LockTypeMapping inLockTypes);
  76
  77 /**
  78  * Set the lock types and initialize OpenSSL in an atomic fashion.  This
  79  * aborts if the library has already been initialized.
  80  */
  81 void setLockTypesAndInit(LockTypeMapping lockTypes);
  82
  83 bool isLockDisabled(int lockId);
  84
  85 void randomize();
  86
  87 } // namespace ssl
  88 } // namespace folly