{ "mode": "man", "parameter": "crypto", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/crypto/7/json", "generated": "2026-06-03T06:35:53Z", "synopsis": "See the individual manual pages for details.", "sections": { "NAME": { "content": "crypto - OpenSSL cryptographic library\n", "subsections": [] }, "SYNOPSIS": { "content": "See the individual manual pages for details.\n", "subsections": [] }, "DESCRIPTION": { "content": "The OpenSSL crypto library (\"libcrypto\") implements a wide range of cryptographic algorithms\nused in various Internet standards. The services provided by this library are used by the\nOpenSSL implementations of TLS and CMS, and they have also been used to implement many other\nthird party products and protocols.\n\nThe functionality includes symmetric encryption, public key cryptography, key agreement,\ncertificate handling, cryptographic hash functions, cryptographic pseudo-random number\ngenerators, message authentication codes (MACs), key derivation functions (KDFs), and various\nutilities.\n", "subsections": [ { "name": "Algorithms", "content": "Cryptographic primitives such as the SHA256 digest, or AES encryption are referred to in\nOpenSSL as \"algorithms\". Each algorithm may have multiple implementations available for use.\nFor example the RSA algorithm is available as a \"default\" implementation suitable for general\nuse, and a \"fips\" implementation which has been validated to FIPS standards for situations\nwhere that is important. It is also possible that a third party could add additional\nimplementations such as in a hardware security module (HSM).\n" }, { "name": "Operations", "content": "Different algorithms can be grouped together by their purpose. For example there are\nalgorithms for encryption, and different algorithms for digesting data. These different\ngroups are known as \"operations\" in OpenSSL. Each operation has a different set of functions\nassociated with it. For example to perform an encryption operation using AES (or any other\nencryption algorithm) you would use the encryption functions detailed on the\nEVPEncryptInit(3) page. Or to perform a digest operation using SHA256 then you would use the\ndigesting functions on the EVPDigestInit(3) page.\n" }, { "name": "Providers", "content": "A provider in OpenSSL is a component that collects together algorithm implementations. In\norder to use an algorithm you must have at least one provider loaded that contains an\nimplementation of it. OpenSSL comes with a number of providers and they may also be obtained\nfrom third parties. If you don't load a provider explicitly (either in program code or via\nconfig) then the OpenSSL built-in \"default\" provider will be automatically loaded.\n" }, { "name": "Library contexts", "content": "A library context can be thought of as a \"scope\" within which configuration options take\neffect. When a provider is loaded, it is only loaded within the scope of a given library\ncontext. In this way it is possible for different components of a complex application to each\nuse a different library context and have different providers loaded with different\nconfiguration settings.\n\nIf an application does not explicitly create a library context then the \"default\" library\ncontext will be used.\n\nLibrary contexts are represented by the OSSLLIBCTX type. Many OpenSSL API functions take a\nlibrary context as a parameter. Applications can always pass NULL for this parameter to just\nuse the default library context.\n\nThe default library context is automatically created the first time it is needed. This will\nautomatically load any available configuration file and will initialise OpenSSL for use.\nUnlike in earlier versions of OpenSSL (prior to 1.1.0) no explicit initialisation steps need\nto be taken.\n\nSimilarly when the application exits the default library context is automatically destroyed.\nNo explicit de-initialisation steps need to be taken.\n\nSee OSSLLIBCTX(3) for more information about library contexts. See also \"ALGORITHM\nFETCHING\".\n" }, { "name": "Multi-threaded applications", "content": "As long as OpenSSL has been built with support for threads (the default case on most\nplatforms) then most OpenSSL functions are thread-safe in the sense that it is safe to call\nthe same function from multiple threads at the same time. However most OpenSSL data\nstructures are not thread-safe. For example the BIOwrite(3) and BIOread(3) functions are\nthread safe. However it would not be thread safe to call BIOwrite() from one thread while\ncalling BIOread() in another where both functions are passed the same BIO object since both\nof them may attempt to make changes to the same BIO object.\n\nThere are exceptions to these rules. A small number of functions are not thread safe at all.\nWhere this is the case this restriction should be noted in the documentation for the\nfunction. Similarly some data structures may be partially or fully thread safe. For example\nit is safe to use an OSSLLIBCTX in multiple threads.\n\nSee openssl-threads(7) for a more detailed discussion on OpenSSL threading support.\n" } ] }, "ALGORITHM FETCHING": { "content": "In order to use an algorithm an implementation for it must first be \"fetched\". Fetching is\nthe process of looking through the available implementations, applying selection criteria\n(via a property query string), and finally choosing the implementation that will be used.\n\nTwo types of fetching are supported by OpenSSL - explicit fetching and implicit fetching.\n", "subsections": [ { "name": "Property query strings", "content": "When fetching an algorithm it is possible to specify a property query string to guide the\nselection process. For example a property query string of \"provider=default\" could be used to\nforce the selection to only consider algorithm implementations in the default provider.\n\nProperty query strings can be specified explicitly as an argument to a function. It is also\npossible to specify a default property query string for the whole library context using the\nEVPsetdefaultproperties(3) function. Where both default properties and function specific\nproperties are specified then they are combined. Function specific properties will override\ndefault properties where there is a conflict.\n\nSee property(7) for more information about properties.\n" }, { "name": "Explicit fetching", "content": "Users of the OpenSSL libraries never query a provider directly for an algorithm\nimplementation. Instead, the diverse OpenSSL APIs often have explicit fetching functions that\ndo the work, and they return an appropriate algorithm object back to the user. These\nfunctions usually have the name \"APINAMEfetch\", where \"APINAME\" is the name of the\noperation. For example EVPMDfetch(3) can be used to explicitly fetch a digest algorithm\nimplementation. The user is responsible for freeing the object returned from the\n\"APINAMEfetch\" function using \"APINAMEfree\" when it is no longer needed.\n\nThese fetching functions follow a fairly common pattern, where three arguments are passed:\n\nThe library context\nSee OSSLLIBCTX(3) for a more detailed description. This may be NULL to signify the\ndefault (global) library context, or a context created by the user. Only providers loaded\nin this library context (see OSSLPROVIDERload(3)) will be considered by the fetching\nfunction. In case no provider has been loaded in this library context then the default\nprovider will be loaded as a fallback (see OSSLPROVIDER-default(7)).\n\nAn identifier\nFor all currently implemented fetching functions this is the algorithm name.\n\nA property query string\nThe property query string used to guide selection of the algorithm implementation.\n\nThe algorithm implementation that is fetched can then be used with other diverse functions\nthat use them. For example the EVPDigestInitex(3) function takes as a parameter an EVPMD\nobject which may have been returned from an earlier call to EVPMDfetch(3).\n" }, { "name": "Implicit fetch", "content": "OpenSSL has a number of functions that return an algorithm object with no associated\nimplementation, such as EVPsha256(3), EVPaes128cbc(3), EVPgetcipherbyname(3) or\nEVPgetdigestbyname(3). These are present for compatibility with OpenSSL before version 3.0\nwhere explicit fetching was not available.\n\nWhen they are used with functions like EVPDigestInitex(3) or EVPCipherInitex(3), the\nactual implementation to be used is fetched implicitly using default search criteria.\n\nIn some cases implicit fetching can also occur when a NULL algorithm parameter is supplied.\nIn this case an algorithm implementation is implicitly fetched using default search criteria\nand an algorithm name that is consistent with the context in which it is being used.\n\nFunctions that revolve around EVPPKEYCTX and EVPPKEY(3), such as EVPDigestSignInit(3) and\nfriends, all fetch the implementations implicitly. Because these functions involve both an\noperation type (such as EVPSIGNATURE(3)) and an EVPKEYMGMT(3) for the EVPPKEY(3), they try\nthe following:\n\n1. Fetch the operation type implementation from any provider given a library context and\nproperty string stored in the EVPPKEYCTX.\n\nIf the provider of the operation type implementation is different from the provider of\nthe EVPPKEY(3)'s EVPKEYMGMT(3) implementation, try to fetch a EVPKEYMGMT(3)\nimplementation in the same provider as the operation type implementation and export the\nEVPPKEY(3) to it (effectively making a temporary copy of the original key).\n\nIf anything in this step fails, the next step is used as a fallback.\n\n2. As a fallback, try to fetch the operation type implementation from the same provider as\nthe original EVPPKEY(3)'s EVPKEYMGMT(3), still using the propery string from the\nEVPPKEYCTX.\n" } ] }, "FETCHING EXAMPLES": { "content": "The following section provides a series of examples of fetching algorithm implementations.\n\nFetch any available implementation of SHA2-256 in the default context. Note that some\nalgorithms have aliases. So \"SHA256\" and \"SHA2-256\" are synonymous:\n\nEVPMD *md = EVPMDfetch(NULL, \"SHA2-256\", NULL);\n...\nEVPMDfree(md);\n\nFetch any available implementation of AES-128-CBC in the default context:\n\nEVPCIPHER *cipher = EVPCIPHERfetch(NULL, \"AES-128-CBC\", NULL);\n...\nEVPCIPHERfree(cipher);\n\nFetch an implementation of SHA2-256 from the default provider in the default context:\n\nEVPMD *md = EVPMDfetch(NULL, \"SHA2-256\", \"provider=default\");\n...\nEVPMDfree(md);\n\nFetch an implementation of SHA2-256 that is not from the default provider in the default\ncontext:\n\nEVPMD *md = EVPMDfetch(NULL, \"SHA2-256\", \"provider!=default\");\n...\nEVPMDfree(md);\n\nFetch an implementation of SHA2-256 from the default provider in the specified context:\n\nEVPMD *md = EVPMDfetch(ctx, \"SHA2-256\", \"provider=default\");\n...\nEVPMDfree(md);\n\nLoad the legacy provider into the default context and then fetch an implementation of\nWHIRLPOOL from it:\n\n/* This only needs to be done once - usually at application start up */\nOSSLPROVIDER *legacy = OSSLPROVIDERload(NULL, \"legacy\");\n\nEVPMD *md = EVPMDfetch(NULL, \"WHIRLPOOL\", \"provider=legacy\");\n...\nEVPMDfree(md);\n\nNote that in the above example the property string \"provider=legacy\" is optional since,\nassuming no other providers have been loaded, the only implementation of the \"whirlpool\"\nalgorithm is in the \"legacy\" provider. Also note that the default provider should be\nexplicitly loaded if it is required in addition to other providers:\n\n/* This only needs to be done once - usually at application start up */\nOSSLPROVIDER *legacy = OSSLPROVIDERload(NULL, \"legacy\");\nOSSLPROVIDER *default = OSSLPROVIDERload(NULL, \"default\");\n\nEVPMD *mdwhirlpool = EVPMDfetch(NULL, \"whirlpool\", NULL);\nEVPMD *mdsha256 = EVPMDfetch(NULL, \"SHA2-256\", NULL);\n...\nEVPMDfree(mdwhirlpool);\nEVPMDfree(mdsha256);\n", "subsections": [] }, "OPENSSL PROVIDERS": { "content": "OpenSSL comes with a set of providers.\n\nThe algorithms available in each of these providers may vary due to build time configuration\noptions. The openssl-list(1) command can be used to list the currently available algorithms.\n\nThe names of the algorithms shown from openssl-list(1) can be used as an algorithm identifier\nto the appropriate fetching function. Also see the provider specific manual pages linked\nbelow for further details about using the algorithms available in each of the providers.\n\nAs well as the OpenSSL providers third parties can also implement providers. For information\non writing a provider see provider(7).\n", "subsections": [ { "name": "Default provider", "content": "The default provider is built in as part of the libcrypto library and contains all of the\nmost commonly used algorithm implementations. Should it be needed (if other providers are\nloaded and offer implementations of the same algorithms), the property query string\n\"provider=default\" can be used as a search criterion for these implementations. The default\nprovider includes all of the functionality in the base provider below.\n\nIf you don't load any providers at all then the \"default\" provider will be automatically\nloaded. If you explicitly load any provider then the \"default\" provider would also need to be\nexplicitly loaded if it is required.\n\nSee OSSLPROVIDER-default(7).\n" }, { "name": "Base provider", "content": "The base provider is built in as part of the libcrypto library and contains algorithm\nimplementations for encoding and decoding for OpenSSL keys. Should it be needed (if other\nproviders are loaded and offer implementations of the same algorithms), the property query\nstring \"provider=base\" can be used as a search criterion for these implementations. Some\nencoding and decoding algorithm implementations are not FIPS algorithm implementations in\nthemselves but support algorithms from the FIPS provider and are allowed for use in \"FIPS\nmode\". The property query string \"fips=yes\" can be used to select such algorithms.\n\nSee OSSLPROVIDER-base(7).\n" }, { "name": "FIPS provider", "content": "The FIPS provider is a dynamically loadable module, and must therefore be loaded explicitly,\neither in code or through OpenSSL configuration (see config(5)). It contains algorithm\nimplementations that have been validated according to the FIPS 140-2 standard. Should it be\nneeded (if other providers are loaded and offer implementations of the same algorithms), the\nproperty query string \"provider=fips\" can be used as a search criterion for these\nimplementations. All approved algorithm implementations in the FIPS provider can also be\nselected with the property \"fips=yes\". The FIPS provider may also contain non-approved\nalgorithm implementations and these can be selected with the property \"fips=no\".\n\nSee OSSLPROVIDER-FIPS(7) and fipsmodule(7).\n" }, { "name": "Legacy provider", "content": "The legacy provider is a dynamically loadable module, and must therefore be loaded\nexplicitly, either in code or through OpenSSL configuration (see config(5)). It contains\nalgorithm implementations that are considered insecure, or are no longer in common use such\nas MD2 or RC4. Should it be needed (if other providers are loaded and offer implementations\nof the same algorithms), the property \"provider=legacy\" can be used as a search criterion for\nthese implementations.\n\nSee OSSLPROVIDER-legacy(7).\n" }, { "name": "Null provider", "content": "The null provider is built in as part of the libcrypto library. It contains no algorithms in\nit at all. When fetching algorithms the default provider will be automatically loaded if no\nother provider has been explicitly loaded. To prevent that from happening you can explicitly\nload the null provider.\n\nSee OSSLPROVIDER-null(7).\n" } ] }, "USING ALGORITHMS IN APPLICATIONS": { "content": "Cryptographic algorithms are made available to applications through use of the \"EVP\" APIs.\nEach of the various operations such as encryption, digesting, message authentication codes,\netc., have a set of EVP function calls that can be invoked to use them. See the evp(7) page\nfor further details.\n\nMost of these follow a common pattern. A \"context\" object is first created. For example for a\ndigest operation you would use an EVPMDCTX, and for an encryption/decryption operation you\nwould use an EVPCIPHERCTX. The operation is then initialised ready for use via an \"init\"\nfunction - optionally passing in a set of parameters (using the OSSLPARAM type) to configure\nhow the operation should behave. Next data is fed into the operation in a series of \"update\"\ncalls. The operation is finalised using a \"final\" call which will typically provide some kind\nof output. Finally the context is cleaned up and freed.\n\nThe following shows a complete example for doing this process for digesting data using\nSHA256. The process is similar for other operations such as encryption/decryption,\nsignatures, message authentication codes, etc.\n\n#include \n#include \n#include \n#include \n\nint main(void)\n{\nEVPMDCTX *ctx = NULL;\nEVPMD *sha256 = NULL;\nconst unsigned char msg[] = {\n0x00, 0x01, 0x02, 0x03\n};\nunsigned int len = 0;\nunsigned char *outdigest = NULL;\nint ret = 1;\n\n/* Create a context for the digest operation */\nctx = EVPMDCTXnew();\nif (ctx == NULL)\ngoto err;\n\n/*\n* Fetch the SHA256 algorithm implementation for doing the digest. We're\n* using the \"default\" library context here (first NULL parameter), and\n* we're not supplying any particular search criteria for our SHA256\n* implementation (second NULL parameter). Any SHA256 implementation will\n* do.\n*/\nsha256 = EVPMDfetch(NULL, \"SHA256\", NULL);\nif (sha256 == NULL)\ngoto err;\n\n/* Initialise the digest operation */\nif (!EVPDigestInitex(ctx, sha256, NULL))\ngoto err;\n\n/*\n* Pass the message to be digested. This can be passed in over multiple\n* EVPDigestUpdate calls if necessary\n*/\nif (!EVPDigestUpdate(ctx, msg, sizeof(msg)))\ngoto err;\n\n/* Allocate the output buffer */\noutdigest = OPENSSLmalloc(EVPMDgetsize(sha256));\nif (outdigest == NULL)\ngoto err;\n\n/* Now calculate the digest itself */\nif (!EVPDigestFinalex(ctx, outdigest, &len))\ngoto err;\n\n/* Print out the digest result */\nBIOdumpfp(stdout, outdigest, len);\n\nret = 0;\n\nerr:\n/* Clean up all the resources we allocated */\nOPENSSLfree(outdigest);\nEVPMDfree(sha256);\nEVPMDCTXfree(ctx);\nif (ret != 0)\nERRprinterrorsfp(stderr);\nreturn ret;\n}\n", "subsections": [] }, "CONFIGURATION": { "content": "By default OpenSSL will load a configuration file when it is first used. This will set up\nvarious configuration settings within the default library context. Applications that create\ntheir own library contexts may optionally configure them with a config file using the\nOSSLLIBCTXloadconfig(3) function.\n\nThe configuration file can be used to automatically load providers and set up default\nproperty query strings.\n\nFor information on the OpenSSL configuration file format see config(5).\n", "subsections": [] }, "ENCODING AND DECODING KEYS": { "content": "Many algorithms require the use of a key. Keys can be generated dynamically using the EVP\nAPIs (for example see EVPPKEYQkeygen(3)). However it is often necessary to save or load\nkeys (or their associated parameters) to or from some external format such as PEM or DER (see\nopenssl-glossary(7)). OpenSSL uses encoders and decoders to perform this task.\n\nEncoders and decoders are just algorithm implementations in the same way as any other\nalgorithm implementation in OpenSSL. They are implemented by providers. The OpenSSL encoders\nand decoders are available in the default provider. They are also duplicated in the base\nprovider.\n\nFor information about encoders see OSSLENCODERCTXnewforpkey(3). For information about\ndecoders see OSSLDECODERCTXnewforpkey(3).\n", "subsections": [] }, "LIBRARY CONVENTIONS": { "content": "Many OpenSSL functions that \"get\" or \"set\" a value follow a naming convention using the\nnumbers 0 and 1, i.e. \"get0\", \"get1\", \"set0\" and \"set1\". This can also apply to some\nfunctions that \"add\" a value to an existing set, i.e. \"add0\" and \"add1\".\n\nFor example the functions:\n\nint X509CRLadd0revoked(X509CRL *crl, X509REVOKED *rev);\nint X509add1trustobject(X509 *x, const ASN1OBJECT *obj);\n\nIn the 0 version the ownership of the object is passed to (for an add or set) or retained by\n(for a get) the parent object. For example after calling the X509CRLadd0revoked() function\nabove, ownership of the rev object is passed to the crl object. Therefore, after calling this\nfunction rev should not be freed directly. It will be freed implicitly when crl is freed.\n\nIn the 1 version the ownership of the object is not passed to or retained by the parent\nobject. Instead a copy or \"up ref\" of the object is performed. So after calling the\nX509add1trustobject() function above the application will still be responsible for freeing\nthe obj value where appropriate.\n", "subsections": [] }, "SEE ALSO": { "content": "openssl(1), ssl(7), evp(7), OSSLLIBCTX(3), openssl-threads(7), property(7),\nOSSLPROVIDER-default(7), OSSLPROVIDER-base(7), OSSLPROVIDER-FIPS(7),\nOSSLPROVIDER-legacy(7), OSSLPROVIDER-null(7), openssl-glossary(7), provider(7)\n", "subsections": [] }, "COPYRIGHT": { "content": "Copyright 2000-2022 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-04-07 CRYPTO(7SSL)", "subsections": [] } }, "summary": "crypto - OpenSSL cryptographic library", "flags": [], "examples": [], "see_also": [ { "name": "openssl", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/openssl/1/json" }, { "name": "ssl", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/ssl/7/json" }, { "name": "evp", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/evp/7/json" }, { "name": "OSSLLIBCTX", "section": "3", "url": "https://www.chedong.com/phpMan.php/man/OSSLLIBCTX/3/json" }, { "name": "openssl-threads", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/openssl-threads/7/json" }, { "name": "property", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/property/7/json" }, { "name": "OSSLPROVIDER-default", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/OSSLPROVIDER-default/7/json" }, { "name": "OSSLPROVIDER-base", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/OSSLPROVIDER-base/7/json" }, { "name": "OSSLPROVIDER-FIPS", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/OSSLPROVIDER-FIPS/7/json" }, { "name": "OSSLPROVIDER-legacy", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/OSSLPROVIDER-legacy/7/json" }, { "name": "OSSLPROVIDER-null", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/OSSLPROVIDER-null/7/json" }, { "name": "openssl-glossary", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/openssl-glossary/7/json" }, { "name": "provider", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/provider/7/json" } ] }