e1f9273a9ce25afd94ab2cfb421ceab4f589d208
[folly.git] / 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 } // namespace ssl
86 } // namespace folly