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. For OpenSSL < 1.1.0, any lock types should be set with
  27  * setLockTypes prior to the call to folly::ssl::init()
  28  */
  29 void init();
  30
  31 /**
  32  * Cleans up openssl. This should be invoked at most once during the lifetime
  33  * of the application. OpenSSL >= 1.1.0 users do not need to manually invoke
  34  * this method, as OpenSSL will automatically cleanup itself during the exit
  35  * of the application.
  36  */
  37 void cleanup();
  38
  39 /**
  40  * Mark openssl as initialized without actually performing any initialization.
  41  * Please use this only if you are using a library which requires that it must
  42  * make its own calls to SSL_library_init() and related functions.
  43  */
  44 void markInitialized();
  45
  46 /**
  47  * Set preferences for how to treat locks in OpenSSL.  This must be
  48  * called before folly::ssl::init(), otherwise the defaults will be used.
  49  *
  50  * OpenSSL has a lock for each module rather than for each object or
  51  * data that needs locking.  Some locks protect only refcounts, and
  52  * might be better as spinlocks rather than mutexes.  Other locks
  53  * may be totally unnecessary if the objects being protected are not
  54  * shared between threads in the application.
  55  *
  56  * For a list of OpenSSL lock types, refer to crypto/crypto.h.
  57  *
  58  * By default, all locks are initialized as mutexes.  OpenSSL's lock usage
  59  * may change from version to version and you should know what you are doing
  60  * before disabling any locks entirely.
  61  *
  62  * In newer versions of OpenSSL (>= 1.1.0), OpenSSL manages its own locks,
  63  * and this function is a no-op.
  64  *
  65  * Example: if you don't share SSL sessions between threads in your
  66  * application, you may be able to do this
  67  *
  68  * setSSLLockTypes({{
  69  *  CRYPTO_LOCK_SSL_SESSION,
  70  *  SSLContext::SSLLockType::LOCK_NONE
  71  * }})
  72  */
  73 void setLockTypes(LockTypeMapping inLockTypes);
  74
  75 /**
  76  * Set the lock types and initialize OpenSSL in an atomic fashion.  This
  77  * aborts if the library has already been initialized.
  78  */
  79 void setLockTypesAndInit(LockTypeMapping lockTypes);
  80
  81 bool isLockDisabled(int lockId);
  82
  83 void randomize();
  84
  85 } // ssl
  86 } // folly