{ "content": [ { "type": "text", "text": "# openssl-threads (man)\n\n## NAME\n\nopenssl-threads - Overview of thread safety in OpenSSL\n\n## DESCRIPTION\n\nIn this man page, we use the term thread-safe to indicate that an object or function can be\nused by multiple threads at the same time.\n\n## Sections\n\n- **NAME**\n- **DESCRIPTION**\n- **SEE ALSO**\n- **BUGS**\n- **COPYRIGHT**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "openssl-threads", "section": "", "mode": "man", "summary": "openssl-threads - Overview of thread safety in OpenSSL", "synopsis": null, "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [ { "name": "CRYPTOTHREADrunonce", "section": "3", "url": "https://www.chedong.com/phpMan.php/man/CRYPTOTHREADrunonce/3/json" } ], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "DESCRIPTION", "lines": 60, "subsections": [] }, { "name": "SEE ALSO", "lines": 2, "subsections": [] }, { "name": "BUGS", "lines": 2, "subsections": [] }, { "name": "COPYRIGHT", "lines": 9, "subsections": [] } ], "sections": { "NAME": { "content": "openssl-threads - Overview of thread safety in OpenSSL\n", "subsections": [] }, "DESCRIPTION": { "content": "In this man page, we use the term thread-safe to indicate that an object or function can be\nused by multiple threads at the same time.\n\nOpenSSL can be built with or without threads support. The most important use of this support\nis so that OpenSSL itself can use a single consistent API, as shown in \"EXAMPLES\" in\nCRYPTOTHREADrunonce(3). Multi-platform applications can also use this API.\n\nIn particular, being configured for threads support does not imply that all OpenSSL objects\nare thread-safe. To emphasize: most objects are not safe for simultaneous use. Exceptions\nto this should be documented on the specific manual pages, and some general high-level\nguidance is given here.\n\nOne major use of the OpenSSL thread API is to implement reference counting. Many objects\nwithin OpenSSL are reference-counted, so resources are not released, until the last reference\nis removed. References are often increased automatically (such as when an X509 certificate\nobject is added into an X509STORE trust store). There is often an oobbjjeeccttupref() function\nthat can be used to increase the reference count. Failure to match oobbjjeeccttupref() calls\nwith the right number of oobbjjeeccttfree() calls is a common source of memory leaks when a\nprogram exits.\n\nMany objects have set and get API's to set attributes in the object. A \"set0\" passes\nownership from the caller to the object and a \"get0\" returns a pointer but the attribute\nownership remains with the object and a reference to it is returned. A \"set1\" or \"get1\"\nfunction does not change the ownership, but instead updates the attribute's reference count\nso that the object is shared between the caller and the object; the caller must free the\nreturned attribute when finished. Functions that involve attributes that have reference\ncounts themselves, but are named with just \"set\" or \"get\" are historical; and the\ndocumentation must state how the references are handled. Get methods are often thread-safe\nas long as the ownership requirements are met and shared objects are not modified. Set\nmethods, or modifying shared objects, are generally not thread-safe as discussed below.\n\nObjects are thread-safe as long as the API's being invoked don't modify the object; in this\ncase the parameter is usually marked in the API as \"const\". Not all parameters are marked\nthis way. Note that a \"const\" declaration does not mean immutable; for example X509cmp(3)\ntakes pointers to \"const\" objects, but the implementation uses a C cast to remove that so it\ncan lock objects, generate and cache a DER encoding, and so on.\n\nAnother instance of thread-safety is when updates to an object's internal state, such as\ncached values, are done with locks. One example of this is the reference counting API's\ndescribed above.\n\nIn all cases, however, it is generally not safe for one thread to mutate an object, such as\nsetting elements of a private or public key, while another thread is using that object, such\nas verifying a signature.\n\nThe same API's can usually be used simultaneously on different objects without interference.\nFor example, two threads can calculate a signature using two different EVPPKEYCTX objects.\n\nFor implicit global state or singletons, thread-safety depends on the facility. The\nCRYPTOsecuremalloc(3) and related API's have their own lock, while CRYPTOmalloc(3) assumes\nthe underlying platform allocation will do any necessary locking. Some API's, such as\nNCONFload(3) and related, or OBJcreate(3) do no locking at all; this can be considered a\nbug.\n\nA separate, although related, issue is modifying \"factory\" objects when other objects have\nbeen created from that. For example, an SSLCTX object created by SSLCTXnew(3) is used to\ncreate per-connection SSL objects by calling SSLnew(3). In this specific case, and probably\nfor factory methods in general, it is not safe to modify the factory object after it has been\nused to create other objects.\n", "subsections": [] }, "SEE ALSO": { "content": "CRYPTOTHREADrunonce(3), local system threads documentation.\n", "subsections": [] }, "BUGS": { "content": "This page is admittedly very incomplete.\n", "subsections": [] }, "COPYRIGHT": { "content": "Copyright 2021 The OpenSSL Project Authors. All Rights Reserved.\n\nLicensed under the Apache License 2.0 (the \"License\"). You may not use this file except in\ncompliance with the License. You can obtain a copy in the file LICENSE in the source\ndistribution or at .\n\n\n\n3.0.2 2026-06-02 OPENSSL-THREADS(7SSL)", "subsections": [] } } } }