{ "content": [ { "type": "text", "text": "# FIPS_MODULE (info)\n\n## NAME\n\nfipsmodule - OpenSSL fips module guide\n\n## SYNOPSIS\n\nSee the individual manual pages for details.\n\n## DESCRIPTION\n\nThis guide details different ways that OpenSSL can be used in\nconjunction with the FIPS module. Which is the correct approach to use\nwill depend on your own specific circumstances and what you are\nattempting to achieve.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **SEE ALSO**\n- **COPYRIGHT**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "FIPS_MODULE", "section": "", "mode": "info", "summary": "fipsmodule - OpenSSL fips module guide", "synopsis": "See the individual manual pages for details.", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [ { "name": "migrationguide", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/migrationguide/7/json" }, { "name": "crypto", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/crypto/7/json" }, { "name": "fipsconfig", "section": "5", "url": "https://www.chedong.com/phpMan.php/man/fipsconfig/5/json" } ], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 2, "subsections": [] }, { "name": "DESCRIPTION", "lines": 435, "subsections": [] }, { "name": "SEE ALSO", "lines": 2, "subsections": [] }, { "name": "COPYRIGHT", "lines": 8, "subsections": [] } ], "sections": { "NAME": { "content": "fipsmodule - OpenSSL fips module guide\n", "subsections": [] }, "SYNOPSIS": { "content": "See the individual manual pages for details.\n", "subsections": [] }, "DESCRIPTION": { "content": "This guide details different ways that OpenSSL can be used in\nconjunction with the FIPS module. Which is the correct approach to use\nwill depend on your own specific circumstances and what you are\nattempting to achieve.\n\nNote that the old functions FIPSmode() and FIPSmodeset() are no\nlonger present so you must remove them from your application if you use\nthem.\n\nApplications written to use the OpenSSL 3.0 FIPS module should not use\nany legacy APIs or features that avoid the FIPS module. Specifically\nthis includes:\n\no Low level cryptographic APIs (use the high level APIs, such as EVP,\ninstead)\n\no Engines\n\no Any functions that create or modify custom \"METHODS\" (for example\nEVPMDmethnew(), EVPCIPHERmethnew(), EVPPKEYmethnew(),\nRSAmethnew(), ECKEYMETHODnew(), etc.)\n\nAll of the above APIs are deprecated in OpenSSL 3.0 - so a simple rule\nis to avoid using all deprecated functions. See migrationguide(7) for\na list of deprecated functions.\n\nMaking all applications use the FIPS module by default\nOne simple approach is to cause all applications that are using OpenSSL\nto only use the FIPS module for cryptographic algorithms by default.\n\nThis approach can be done purely via configuration. As long as\napplications are built and linked against OpenSSL 3.0 and do not\noverride the loading of the default config file or its settings then\nthey can automatically start using the FIPS module without the need for\nany further code changes.\n\nTo do this the default OpenSSL config file will have to be modified.\nThe location of this config file will depend on the platform, and any\noptions that were given during the build process. You can check the\nlocation of the config file by running this command:\n\n$ openssl version -d\nOPENSSLDIR: \"/usr/local/ssl\"\n\nCaution: Many Operating Systems install OpenSSL by default. It is a\ncommon error to not have the correct version of OpenSSL in your $PATH.\nCheck that you are running an OpenSSL 3.0 version like this:\n\n$ openssl version -v\nOpenSSL 3.0.0-dev xx XXX xxxx (Library: OpenSSL 3.0.0-dev xx XXX xxxx)\n\nThe OPENSSLDIR value above gives the directory name for where the\ndefault config file is stored. So in this case the default config file\nwill be called /usr/local/ssl/openssl.cnf.\n\nEdit the config file to add the following lines near the beginning:\n\nconfigdiagnostics = 1\nopensslconf = opensslinit\n\n.include /usr/local/ssl/fipsmodule.cnf\n\n[opensslinit]\nproviders = providersect\n\n[providersect]\nfips = fipssect\nbase = basesect\n\n[basesect]\nactivate = 1\n\nObviously the include file location above should match the path and\nname of the FIPS module config file that you installed earlier. See\n.\n\nFor FIPS usage, it is recommened that the configdiagnostics option is\nenabled to prevent accidental use of non-FIPS validated algorithms via\nbroken or mistaken configuration. See config(5).\n\nAny applications that use OpenSSL 3.0 and are started after these\nchanges are made will start using only the FIPS module unless those\napplications take explicit steps to avoid this default behaviour. Note\nthat this configuration also activates the \"base\" provider. The base\nprovider does not include any cryptographic algorithms (and therefore\ndoes not impact the validation status of any cryptographic operations),\nbut does include other supporting algorithms that may be required. It\nis designed to be used in conjunction with the FIPS module.\n\nThis approach has the primary advantage that it is simple, and no code\nchanges are required in applications in order to benefit from the FIPS\nmodule. There are some disadvantages to this approach:\n\no You may not want all applications to use the FIPS module.\n\nIt may be the case that some applications should and some should\nnot use the FIPS module.\n\no If applications take explicit steps to not load the default config\nfile or set different settings.\n\nThis method will not work for these cases.\n\no The algorithms available in the FIPS module are a subset of the\nalgorithms that are available in the default OpenSSL Provider.\n\nIf any applications attempt to use any algorithms that are not\npresent, then they will fail.\n\no Usage of certain deprecated APIs avoids the use of the FIPS module.\n\nIf any applications use those APIs then the FIPS module will not be\nused.\n\nSelectively making applications use the FIPS module by default\nA variation on the above approach is to do the same thing on an\nindividual application basis. The default OpenSSL config file depends\non the compiled in value for OPENSSLDIR as described in the section\nabove. However it is also possible to override the config file to be\nused via the OPENSSLCONF environment variable. For example the\nfollowing, on Unix, will cause the application to be executed with a\nnon-standard config file location:\n\n$ OPENSSLCONF=/my/nondefault/openssl.cnf myapplication\n\nUsing this mechanism you can control which config file is loaded (and\nhence whether the FIPS module is loaded) on an application by\napplication basis.\n\nThis removes the disadvantage listed above that you may not want all\napplications to use the FIPS module. All the other advantages and\ndisadvantages still apply.\n\nProgrammatically loading the FIPS module (default library context)\nApplications may choose to load the FIPS provider explicitly rather\nthan relying on config to do this. The config file is still necessary\nin order to hold the FIPS module config data (such as its self test\nstatus and integrity data). But in this case we do not automatically\nactivate the FIPS provider via that config file.\n\nTo do things this way configure as per \"Making all applications use the\nFIPS module by default\" above, but edit the fipsmodule.cnf file to\nremove or comment out the line which says \"activate = 1\" (note that\nsetting this value to 0 is not sufficient). This means all the\nrequired config information will be available to load the FIPS module,\nbut it is not automatically loaded when the application starts. The\nFIPS provider can then be loaded programmatically like this:\n\n#include \n\nint main(void)\n{\nOSSLPROVIDER *fips;\nOSSLPROVIDER *base;\n\nfips = OSSLPROVIDERload(NULL, \"fips\");\nif (fips == NULL) {\nprintf(\"Failed to load FIPS provider\\n\");\nexit(EXITFAILURE);\n}\nbase = OSSLPROVIDERload(NULL, \"base\");\nif (base == NULL) {\nOSSLPROVIDERunload(fips);\nprintf(\"Failed to load base provider\\n\");\nexit(EXITFAILURE);\n}\n\n/* Rest of application */\n\nOSSLPROVIDERunload(base);\nOSSLPROVIDERunload(fips);\nexit(EXITSUCCESS);\n}\n\nNote that this should be one of the first things that you do in your\napplication. If any OpenSSL functions get called that require the use\nof cryptographic functions before this occurs then, if no provider has\nyet been loaded, then the default provider will be automatically\nloaded. If you then later explicitly load the FIPS provider then you\nwill have both the FIPS and the default provider loaded at the same\ntime. It is undefined which implementation of an algorithm will be used\nif multiple implementations are available and you have not explicitly\nspecified via a property query (see below) which one should be used.\n\nAlso note that in this example we have additionally loaded the \"base\"\nprovider. This loads a sub-set of algorithms that are also available\nin the default provider - specifically non cryptographic ones which may\nbe used in conjunction with the FIPS provider. For example this\ncontains algorithms for encoding and decoding keys. If you decide not\nto load the default provider then you will usually want to load the\nbase provider instead.\n\nIn this example we are using the \"default\" library context. OpenSSL\nfunctions operate within the scope of a library context. If no library\ncontext is explicitly specified then the default library context is\nused. For further details about library contexts see the\nOSSLLIBCTX(3) man page.\n\nLoading the FIPS module at the same time as other providers\nIt is possible to have the FIPS provider and other providers (such as\nthe default provider) all loaded at the same time into the same library\ncontext. You can use a property query string during algorithm fetches\nto specify which implementation you would like to use.\n\nFor example to fetch an implementation of SHA256 which conforms to FIPS\nstandards you can specify the property query \"fips=yes\" like this:\n\nEVPMD *sha256;\n\nsha256 = EVPMDfetch(NULL, \"SHA2-256\", \"fips=yes\");\n\nIf no property query is specified, or more than one implementation\nmatches the property query then it is undefined which implementation of\na particular algorithm will be returned.\n\nThis example shows an explicit request for an implementation of SHA256\nfrom the default provider:\n\nEVPMD *sha256;\n\nsha256 = EVPMDfetch(NULL, \"SHA2-256\", \"provider=default\");\n\nIt is also possible to set a default property query string. The\nfollowing example sets the default property query of \"fips=yes\" for all\nfetches within the default library context:\n\nEVPsetdefaultproperties(NULL, \"fips=yes\");\n\nIf a fetch function has both an explicit property query specified, and\na default property query is defined then the two queries are merged\ntogether and both apply. The local property query overrides the default\nproperties if the same property name is specified in both.\n\nThere are two important built-in properties that you should be aware\nof:\n\nThe \"provider\" property enables you to specify which provider you want\nan implementation to be fetched from, e.g. \"provider=default\" or\n\"provider=fips\". All algorithms implemented in a provider have this\nproperty set on them.\n\nThere is also the \"fips\" property. All FIPS algorithms match against\nthe property query \"fips=yes\". There are also some non-cryptographic\nalgorithms available in the default and base providers that also have\nthe \"fips=yes\" property defined for them. These are the encoder and\ndecoder algorithms that can (for example) be used to write out a key\ngenerated in the FIPS provider to a file. The encoder and decoder\nalgorithms are not in the FIPS module itself but are allowed to be used\nin conjunction with the FIPS algorithms.\n\nIt is possible to specify default properties within a config file. For\nexample the following config file automatically loads the default and\nfips providers and sets the default property value to be \"fips=yes\".\nNote that this config file does not load the \"base\" provider. All\nsupporting algorithms that are in \"base\" are also in \"default\", so it\nis unnecessary in this case:\n\nconfigdiagnostics = 1\nopensslconf = opensslinit\n\n.include /usr/local/ssl/fipsmodule.cnf\n\n[opensslinit]\nproviders = providersect\nalgsection = algorithmsect\n\n[providersect]\nfips = fipssect\ndefault = defaultsect\n\n[defaultsect]\nactivate = 1\n\n[algorithmsect]\ndefaultproperties = fips=yes\n\nProgrammatically loading the FIPS module (nondefault library context)\nIn addition to using properties to separate usage of the FIPS module\nfrom other usages this can also be achieved using library contexts. In\nthis example we create two library contexts. In one we assume the\nexistence of a config file called openssl-fips.cnf that automatically\nloads and configures the FIPS and base providers. The other library\ncontext will just use the default provider.\n\nOSSLLIBCTX *fipslibctx, *nonfipslibctx;\nOSSLPROVIDER *defctxnull = NULL;\nEVPMD *fipssha256 = NULL, *nonfipssha256 = NULL;\nint ret = 1;\n\n/*\n* Create two nondefault library contexts. One for fips usage and\n* one for non-fips usage\n*/\nfipslibctx = OSSLLIBCTXnew();\nnonfipslibctx = OSSLLIBCTXnew();\nif (fipslibctx == NULL || nonfipslibctx == NULL)\ngoto err;\n\n/* Prevent anything from using the default library context */\ndefctxnull = OSSLPROVIDERload(NULL, \"null\");\n\n/*\n* Load config file for the FIPS library context. We assume that\n* this config file will automatically activate the FIPS and base\n* providers so we don't need to explicitly load them here.\n*/\nif (!OSSLLIBCTXloadconfig(fipslibctx, \"openssl-fips.cnf\"))\ngoto err;\n\n/*\n* We don't need to do anything special to load the default\n* provider into nonfipslibctx. This happens automatically if no\n* other providers are loaded.\n* Because we don't call OSSLLIBCTXloadconfig() explicitly for\n* nonfipslibctx it will just use the default config file.\n*/\n\n/* As an example get some digests */\n\n/* Get a FIPS validated digest */\nfipssha256 = EVPMDfetch(fipslibctx, \"SHA2-256\", NULL);\nif (fipssha256 == NULL)\ngoto err;\n\n/* Get a non-FIPS validated digest */\nnonfipssha256 = EVPMDfetch(nonfipslibctx, \"SHA2-256\", NULL);\nif (nonfipssha256 == NULL)\ngoto err;\n\n/* Use the digests */\n\nprintf(\"Success\\n\");\nret = 0;\n\nerr:\nEVPMDfree(fipssha256);\nEVPMDfree(nonfipssha256);\nOSSLLIBCTXfree(fipslibctx);\nOSSLLIBCTXfree(nonfipslibctx);\nOSSLPROVIDERunload(defctxnull);\n\nreturn ret;\n\nNote that we have made use of the special \"null\" provider here which we\nload into the default library context. We could have chosen to use the\ndefault library context for FIPS usage, and just create one additional\nlibrary context for other usages - or vice versa. However if code has\nnot been converted to use library contexts then the default library\ncontext will be automatically used. This could be the case for your\nown existing applications as well as certain parts of OpenSSL itself.\nNot all parts of OpenSSL are library context aware. If this happens\nthen you could \"accidentally\" use the wrong library context for a\nparticular operation. To be sure this doesn't happen you can load the\n\"null\" provider into the default library context. Because a provider\nhas been explicitly loaded, the default provider will not automatically\nload. This means code using the default context by accident will fail\nbecause no algorithms will be available.\n\nSee \"Library Context\" in migrationguide(7) for additional information\nabout the Library Context.\n\nUsing Encoders and Decoders with the FIPS module\nEncoders and decoders are used to read and write keys or parameters\nfrom or to some external format (for example a PEM file). If your\napplication generates keys or parameters that then need to be written\ninto PEM or DER format then it is likely that you will need to use an\nencoder to do this. Similarly you need a decoder to read previously\nsaved keys and parameters. In most cases this will be invisible to you\nif you are using APIs that existed in OpenSSL 1.1.1 or earlier such as\ni2dPrivateKey(3). However the appropriate encoder/decoder will need to\nbe available in the library context associated with the key or\nparameter object. The built-in OpenSSL encoders and decoders are\nimplemented in both the default and base providers and are not in the\nFIPS module boundary. However since they are not cryptographic\nalgorithms themselves it is still possible to use them in conjunction\nwith the FIPS module, and therefore these encoders/decoders have the\n\"fips=yes\" property against them. You should ensure that either the\ndefault or base provider is loaded into the library context in this\ncase.\n\nUsing the FIPS module in SSL/TLS\nWriting an application that uses libssl in conjunction with the FIPS\nmodule is much the same as writing a normal libssl application. If you\nare using global properties and the default library context to specify\nusage of FIPS validated algorithms then this will happen automatically\nfor all cryptographic algorithms in libssl. If you are using a\nnondefault library context to load the FIPS provider then you can\nsupply this to libssl using the function SSLCTXnewex(3). This works\nas a drop in replacement for the function SSLCTXnew(3) except it\nprovides you with the capability to specify the library context to be\nused. You can also use the same function to specify libssl specific\nproperties to use.\n\nIn this first example we create two SSLCTX objects using two different\nlibrary contexts.\n\n/*\n* We assume that a nondefault library context with the FIPS\n* provider loaded has been created called fipslibctx.\n*/\nSSLCTX *fipssslctx = SSLCTXnewex(fipslibctx, NULL, TLSmethod());\n/*\n* We assume that a nondefault library context with the default\n* provider loaded has been created called nonfipslibctx.\n*/\nSSLCTX *nonfipssslctx = SSLCTXnewex(nonfipslibctx, NULL,\nTLSmethod());\n\nIn this second example we create two SSLCTX objects using different\nproperties to specify FIPS usage:\n\n/*\n* The \"fips=yes\" property includes all FIPS approved algorithms\n* as well as encoders from the default provider that are allowed\n* to be used. The NULL below indicates that we are using the\n* default library context.\n*/\nSSLCTX *fipssslctx = SSLCTXnewex(NULL, \"fips=yes\", TLSmethod());\n/*\n* The \"provider!=fips\" property allows algorithms from any\n* provider except the FIPS provider\n*/\nSSLCTX *nonfipssslctx = SSLCTXnewex(NULL, \"provider!=fips\",\nTLSmethod());\n\nConfirming that an algorithm is being provided by the FIPS module\nA chain of links needs to be followed to go from an algorithm instance\nto the provider that implements it. The process is similar for all\nalgorithms. Here the example of a digest is used.\n\nTo go from an EVPMDCTX to an EVPMD, use EVPMDCTXmd(3) . To go\nfrom the EVPMD to its OSSLPROVIDER, use EVPMDget0provider(3). To\nextract the name from the OSSLPROVIDER, use\nOSSLPROVIDERget0name(3).\n", "subsections": [] }, "SEE ALSO": { "content": "migrationguide(7), crypto(7), fipsconfig(5)\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\nthis file except in compliance with the License. You can obtain a copy\nin the file LICENSE in the source distribution or at\n.\n\n3.0.2 2026-06-02 FIPSMODULE(7SSL)", "subsections": [] } } } }