diff options
Diffstat (limited to 'upstream/debian-unstable/man7/ossl-guide-libcrypto-introduction.7ssl')
| -rw-r--r-- | upstream/debian-unstable/man7/ossl-guide-libcrypto-introduction.7ssl | 443 |
1 files changed, 443 insertions, 0 deletions
diff --git a/upstream/debian-unstable/man7/ossl-guide-libcrypto-introduction.7ssl b/upstream/debian-unstable/man7/ossl-guide-libcrypto-introduction.7ssl new file mode 100644 index 00000000..e39a2102 --- /dev/null +++ b/upstream/debian-unstable/man7/ossl-guide-libcrypto-introduction.7ssl @@ -0,0 +1,443 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "OSSL-GUIDE-LIBCRYPTO-INTRODUCTION 7SSL" +.TH OSSL-GUIDE-LIBCRYPTO-INTRODUCTION 7SSL 2024-04-04 3.2.2-dev OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +ossl\-guide\-libcrypto\-introduction, crypto +\&\- OpenSSL Guide: An introduction to libcrypto +.SH INTRODUCTION +.IX Header "INTRODUCTION" +The OpenSSL cryptography library (\f(CW\*(C`libcrypto\*(C'\fR) enables access to a wide range +of cryptographic algorithms used in various Internet standards. The services +provided by this library are used by the OpenSSL implementations of TLS and +CMS, and they have also been used to implement many other third party products +and protocols. +.PP +The functionality includes symmetric encryption, public key cryptography, key +agreement, certificate handling, cryptographic hash functions, cryptographic +pseudo-random number generators, message authentication codes (MACs), key +derivation functions (KDFs), and various utilities. +.SS Algorithms +.IX Subsection "Algorithms" +Cryptographic primitives such as the SHA256 digest, or AES encryption are +referred to in OpenSSL as "algorithms". Each algorithm may have multiple +implementations available for use. For example the RSA algorithm is available as +a "default" implementation suitable for general use, and a "fips" implementation +which has been validated to FIPS 140 standards for situations where that is +important. It is also possible that a third party could add additional +implementations such as in a hardware security module (HSM). +.PP +Algorithms are implemented in providers. See +\&\fBossl\-guide\-libraries\-introduction\fR\|(7) for information about providers. +.SS Operations +.IX Subsection "Operations" +Different algorithms can be grouped together by their purpose. For example there +are algorithms for encryption, and different algorithms for digesting data. +These different groups are known as "operations" in OpenSSL. Each operation +has a different set of functions associated with it. For example to perform an +encryption operation using AES (or any other encryption algorithm) you would use +the encryption functions detailed on the \fBEVP_EncryptInit\fR\|(3) page. Or to +perform a digest operation using SHA256 then you would use the digesting +functions on the \fBEVP_DigestInit\fR\|(3) page. +.SH "ALGORITHM FETCHING" +.IX Header "ALGORITHM FETCHING" +In order to use an algorithm an implementation for it must first be "fetched". +Fetching is the process of looking through the available implementations, +applying selection criteria (via a property query string), and finally choosing +the implementation that will be used. +.PP +Two types of fetching are supported by OpenSSL \- "Explicit fetching" and +"Implicit fetching". +.SS "Explicit fetching" +.IX Subsection "Explicit fetching" +Explicit fetching involves directly calling a specific API to fetch an algorithm +implementation from a provider. This fetched object can then be passed to other +APIs. These explicit fetching functions usually have the name \f(CW\*(C`APINAME_fetch\*(C'\fR, +where \f(CW\*(C`APINAME\*(C'\fR is the name of the operation. For example \fBEVP_MD_fetch\fR\|(3) +can be used to explicitly fetch a digest algorithm implementation. The user is +responsible for freeing the object returned from the \f(CW\*(C`APINAME_fetch\*(C'\fR function +using \f(CW\*(C`APINAME_free\*(C'\fR when it is no longer needed. +.PP +These fetching functions follow a fairly common pattern, where three +arguments are passed: +.IP "The library context" 4 +.IX Item "The library context" +See \fBOSSL_LIB_CTX\fR\|(3) for a more detailed description. +This may be NULL to signify the default (global) library context, or a +context created by the user. Only providers loaded in this library context (see +\&\fBOSSL_PROVIDER_load\fR\|(3)) will be considered by the fetching function. In case +no provider has been loaded in this library context then the default provider +will be loaded as a fallback (see \fBOSSL_PROVIDER\-default\fR\|(7)). +.IP "An identifier" 4 +.IX Item "An identifier" +For all currently implemented fetching functions this is the algorithm name. +Each provider supports a list of algorithm implementations. See the provider +specific documentation for information on the algorithm implementations +available in each provider: +"OPERATIONS AND ALGORITHMS" in \fBOSSL_PROVIDER\-default\fR\|(7), +"OPERATIONS AND ALGORITHMS" in \fBOSSL_PROVIDER\-FIPS\fR\|(7), +"OPERATIONS AND ALGORITHMS" in \fBOSSL_PROVIDER\-legacy\fR\|(7) and +"OPERATIONS AND ALGORITHMS" in \fBOSSL_PROVIDER\-base\fR\|(7). +.Sp +Note, while providers may register algorithms against a list of names using a +string with a colon separated list of names, fetching algorithms using that +format is currently unsupported. +.IP "A property query string" 4 +.IX Item "A property query string" +The property query string used to guide selection of the algorithm +implementation. See +"PROPERTY QUERY STRINGS" in \fBossl\-guide\-libraries\-introduction\fR\|(7). +.PP +The algorithm implementation that is fetched can then be used with other diverse +functions that use them. For example the \fBEVP_DigestInit_ex\fR\|(3) function takes +as a parameter an \fBEVP_MD\fR object which may have been returned from an earlier +call to \fBEVP_MD_fetch\fR\|(3). +.SS "Implicit fetching" +.IX Subsection "Implicit fetching" +OpenSSL has a number of functions that return an algorithm object with no +associated implementation, such as \fBEVP_sha256\fR\|(3), \fBEVP_aes_128_cbc\fR\|(3), +\&\fBEVP_get_cipherbyname\fR\|(3) or \fBEVP_get_digestbyname\fR\|(3). These are present for +compatibility with OpenSSL before version 3.0 where explicit fetching was not +available. +.PP +When they are used with functions like \fBEVP_DigestInit_ex\fR\|(3) or +\&\fBEVP_CipherInit_ex\fR\|(3), the actual implementation to be used is +fetched implicitly using default search criteria (which uses NULL for the +library context and property query string). +.PP +In some cases implicit fetching can also occur when a NULL algorithm parameter +is supplied. In this case an algorithm implementation is implicitly fetched +using default search criteria and an algorithm name that is consistent with +the context in which it is being used. +.PP +Functions that use an \fBEVP_PKEY_CTX\fR or an \fBEVP_PKEY\fR\|(3), such as +\&\fBEVP_DigestSignInit\fR\|(3), all fetch the implementations implicitly. Usually the +algorithm to fetch is determined based on the type of key that is being used and +the function that has been called. +.SS Performance +.IX Subsection "Performance" +If you perform the same operation many times with the same algorithm then it is +recommended to use a single explicit fetch of the algorithm and then reuse the +explicitly fetched algorithm each subsequent time. This will typically be +faster than implicitly fetching the algorithm every time you use it. See an +example of Explicit fetching in "USING ALGORITHMS IN APPLICATIONS". +.PP +Prior to OpenSSL 3.0, functions such as \fBEVP_sha256()\fR which return a "const" +object were used directly to indicate the algorithm to use in various function +calls. If you pass the return value of one of these convenience functions to an +operation then you are using implicit fetching. If you are converting an +application that worked with an OpenSSL version prior to OpenSSL 3.0 then +consider changing instances of implicit fetching to explicit fetching instead. +.PP +If an explicitly fetched object is not passed to an operation, then any implicit +fetch will use an internally cached prefetched object, but it will +still be slower than passing the explicitly fetched object directly. +.PP +The following functions can be used for explicit fetching: +.IP \fBEVP_MD_fetch\fR\|(3) 4 +.IX Item "EVP_MD_fetch" +Fetch a message digest/hashing algorithm implementation. +.IP \fBEVP_CIPHER_fetch\fR\|(3) 4 +.IX Item "EVP_CIPHER_fetch" +Fetch a symmetric cipher algorithm implementation. +.IP \fBEVP_KDF_fetch\fR\|(3) 4 +.IX Item "EVP_KDF_fetch" +Fetch a Key Derivation Function (KDF) algorithm implementation. +.IP \fBEVP_MAC_fetch\fR\|(3) 4 +.IX Item "EVP_MAC_fetch" +Fetch a Message Authentication Code (MAC) algorithm implementation. +.IP \fBEVP_KEM_fetch\fR\|(3) 4 +.IX Item "EVP_KEM_fetch" +Fetch a Key Encapsulation Mechanism (KEM) algorithm implementation +.IP \fBOSSL_ENCODER_fetch\fR\|(3) 4 +.IX Item "OSSL_ENCODER_fetch" +Fetch an encoder algorithm implementation (e.g. to encode keys to a specified +format). +.IP \fBOSSL_DECODER_fetch\fR\|(3) 4 +.IX Item "OSSL_DECODER_fetch" +Fetch a decoder algorithm implementation (e.g. to decode keys from a specified +format). +.IP \fBEVP_RAND_fetch\fR\|(3) 4 +.IX Item "EVP_RAND_fetch" +Fetch a Pseudo Random Number Generator (PRNG) algorithm implementation. +.PP +See "OPERATIONS AND ALGORITHMS" in \fBOSSL_PROVIDER\-default\fR\|(7), +"OPERATIONS AND ALGORITHMS" in \fBOSSL_PROVIDER\-FIPS\fR\|(7), +"OPERATIONS AND ALGORITHMS" in \fBOSSL_PROVIDER\-legacy\fR\|(7) and +"OPERATIONS AND ALGORITHMS" in \fBOSSL_PROVIDER\-base\fR\|(7) for a list of algorithm names +that can be fetched. +.SH "FETCHING EXAMPLES" +.IX Header "FETCHING EXAMPLES" +The following section provides a series of examples of fetching algorithm +implementations. +.PP +Fetch any available implementation of SHA2\-256 in the default context. Note +that some algorithms have aliases. So "SHA256" and "SHA2\-256" are synonymous: +.PP +.Vb 3 +\& EVP_MD *md = EVP_MD_fetch(NULL, "SHA2\-256", NULL); +\& ... +\& EVP_MD_free(md); +.Ve +.PP +Fetch any available implementation of AES\-128\-CBC in the default context: +.PP +.Vb 3 +\& EVP_CIPHER *cipher = EVP_CIPHER_fetch(NULL, "AES\-128\-CBC", NULL); +\& ... +\& EVP_CIPHER_free(cipher); +.Ve +.PP +Fetch an implementation of SHA2\-256 from the default provider in the default +context: +.PP +.Vb 3 +\& EVP_MD *md = EVP_MD_fetch(NULL, "SHA2\-256", "provider=default"); +\& ... +\& EVP_MD_free(md); +.Ve +.PP +Fetch an implementation of SHA2\-256 that is not from the default provider in the +default context: +.PP +.Vb 3 +\& EVP_MD *md = EVP_MD_fetch(NULL, "SHA2\-256", "provider!=default"); +\& ... +\& EVP_MD_free(md); +.Ve +.PP +Fetch an implementation of SHA2\-256 that is preferably from the FIPS provider in +the default context: +.PP +.Vb 3 +\& EVP_MD *md = EVP_MD_fetch(NULL, "SHA2\-256", "provider=?fips"); +\& ... +\& EVP_MD_free(md); +.Ve +.PP +Fetch an implementation of SHA2\-256 from the default provider in the specified +library context: +.PP +.Vb 3 +\& EVP_MD *md = EVP_MD_fetch(libctx, "SHA2\-256", "provider=default"); +\& ... +\& EVP_MD_free(md); +.Ve +.PP +Load the legacy provider into the default context and then fetch an +implementation of WHIRLPOOL from it: +.PP +.Vb 2 +\& /* This only needs to be done once \- usually at application start up */ +\& OSSL_PROVIDER *legacy = OSSL_PROVIDER_load(NULL, "legacy"); +\& +\& EVP_MD *md = EVP_MD_fetch(NULL, "WHIRLPOOL", "provider=legacy"); +\& ... +\& EVP_MD_free(md); +.Ve +.PP +Note that in the above example the property string "provider=legacy" is optional +since, assuming no other providers have been loaded, the only implementation of +the "whirlpool" algorithm is in the "legacy" provider. Also note that the +default provider should be explicitly loaded if it is required in addition to +other providers: +.PP +.Vb 3 +\& /* This only needs to be done once \- usually at application start up */ +\& OSSL_PROVIDER *legacy = OSSL_PROVIDER_load(NULL, "legacy"); +\& OSSL_PROVIDER *default = OSSL_PROVIDER_load(NULL, "default"); +\& +\& EVP_MD *md_whirlpool = EVP_MD_fetch(NULL, "whirlpool", NULL); +\& EVP_MD *md_sha256 = EVP_MD_fetch(NULL, "SHA2\-256", NULL); +\& ... +\& EVP_MD_free(md_whirlpool); +\& EVP_MD_free(md_sha256); +.Ve +.SH "USING ALGORITHMS IN APPLICATIONS" +.IX Header "USING ALGORITHMS IN APPLICATIONS" +Cryptographic algorithms are made available to applications through use of the +"EVP" APIs. Each of the various operations such as encryption, digesting, +message authentication codes, etc., have a set of EVP function calls that can +be invoked to use them. See the \fBevp\fR\|(7) page for further details. +.PP +Most of these follow a common pattern. A "context" object is first created. For +example for a digest operation you would use an \fBEVP_MD_CTX\fR, and for an +encryption/decryption operation you would use an \fBEVP_CIPHER_CTX\fR. The +operation is then initialised ready for use via an "init" function \- optionally +passing in a set of parameters (using the \fBOSSL_PARAM\fR\|(3) type) to configure how +the operation should behave. Next data is fed into the operation in a series of +"update" calls. The operation is finalised using a "final" call which will +typically provide some kind of output. Finally the context is cleaned up and +freed. +.PP +The following shows a complete example for doing this process for digesting +data using SHA256. The process is similar for other operations such as +encryption/decryption, signatures, message authentication codes, etc. Additional +examples can be found in the OpenSSL demos (see +"DEMO APPLICATIONS" in \fBossl\-guide\-libraries\-introduction\fR\|(7)). +.PP +.Vb 4 +\& #include <stdio.h> +\& #include <openssl/evp.h> +\& #include <openssl/bio.h> +\& #include <openssl/err.h> +\& +\& int main(void) +\& { +\& EVP_MD_CTX *ctx = NULL; +\& EVP_MD *sha256 = NULL; +\& const unsigned char msg[] = { +\& 0x00, 0x01, 0x02, 0x03 +\& }; +\& unsigned int len = 0; +\& unsigned char *outdigest = NULL; +\& int ret = 1; +\& +\& /* Create a context for the digest operation */ +\& ctx = EVP_MD_CTX_new(); +\& if (ctx == NULL) +\& goto err; +\& +\& /* +\& * Fetch the SHA256 algorithm implementation for doing the digest. We\*(Aqre +\& * using the "default" library context here (first NULL parameter), and +\& * we\*(Aqre not supplying any particular search criteria for our SHA256 +\& * implementation (second NULL parameter). Any SHA256 implementation will +\& * do. +\& * In a larger application this fetch would just be done once, and could +\& * be used for multiple calls to other operations such as EVP_DigestInit_ex(). +\& */ +\& sha256 = EVP_MD_fetch(NULL, "SHA256", NULL); +\& if (sha256 == NULL) +\& goto err; +\& +\& /* Initialise the digest operation */ +\& if (!EVP_DigestInit_ex(ctx, sha256, NULL)) +\& goto err; +\& +\& /* +\& * Pass the message to be digested. This can be passed in over multiple +\& * EVP_DigestUpdate calls if necessary +\& */ +\& if (!EVP_DigestUpdate(ctx, msg, sizeof(msg))) +\& goto err; +\& +\& /* Allocate the output buffer */ +\& outdigest = OPENSSL_malloc(EVP_MD_get_size(sha256)); +\& if (outdigest == NULL) +\& goto err; +\& +\& /* Now calculate the digest itself */ +\& if (!EVP_DigestFinal_ex(ctx, outdigest, &len)) +\& goto err; +\& +\& /* Print out the digest result */ +\& BIO_dump_fp(stdout, outdigest, len); +\& +\& ret = 0; +\& +\& err: +\& /* Clean up all the resources we allocated */ +\& OPENSSL_free(outdigest); +\& EVP_MD_free(sha256); +\& EVP_MD_CTX_free(ctx); +\& if (ret != 0) +\& ERR_print_errors_fp(stderr); +\& return ret; +\& } +.Ve +.SH "ENCODING AND DECODING KEYS" +.IX Header "ENCODING AND DECODING KEYS" +Many algorithms require the use of a key. Keys can be generated dynamically +using the EVP APIs (for example see \fBEVP_PKEY_Q_keygen\fR\|(3)). However it is often +necessary to save or load keys (or their associated parameters) to or from some +external format such as PEM or DER (see \fBopenssl\-glossary\fR\|(7)). OpenSSL uses +encoders and decoders to perform this task. +.PP +Encoders and decoders are just algorithm implementations in the same way as +any other algorithm implementation in OpenSSL. They are implemented by +providers. The OpenSSL encoders and decoders are available in the default +provider. They are also duplicated in the base provider. +.PP +For information about encoders see \fBOSSL_ENCODER_CTX_new_for_pkey\fR\|(3). For +information about decoders see \fBOSSL_DECODER_CTX_new_for_pkey\fR\|(3). +.PP +As well as using encoders/decoders directly there are also some helper functions +that can be used for certain well known and commonly used formats. For example +see \fBPEM_read_PrivateKey\fR\|(3) and \fBPEM_write_PrivateKey\fR\|(3) for information +about reading and writing key data from PEM encoded files. +.SH "FURTHER READING" +.IX Header "FURTHER READING" +See \fBossl\-guide\-libssl\-introduction\fR\|(7) for an introduction to using \f(CW\*(C`libssl\*(C'\fR. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBopenssl\fR\|(1), \fBssl\fR\|(7), \fBevp\fR\|(7), \fBOSSL_LIB_CTX\fR\|(3), \fBopenssl\-threads\fR\|(7), +\&\fBproperty\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7), \fBOSSL_PROVIDER\-base\fR\|(7), +\&\fBOSSL_PROVIDER\-FIPS\fR\|(7), \fBOSSL_PROVIDER\-legacy\fR\|(7), \fBOSSL_PROVIDER\-null\fR\|(7), +\&\fBopenssl\-glossary\fR\|(7), \fBprovider\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +<https://www.openssl.org/source/license.html>. |