diff --git a/doc/build.info b/doc/build.info index bdda13b78cba2..cf89694a65c67 100644 --- a/doc/build.info +++ b/doc/build.info @@ -1539,6 +1539,14 @@ DEPEND[html/man3/OPENSSL_strcasecmp.html]=man3/OPENSSL_strcasecmp.pod GENERATE[html/man3/OPENSSL_strcasecmp.html]=man3/OPENSSL_strcasecmp.pod DEPEND[man/man3/OPENSSL_strcasecmp.3]=man3/OPENSSL_strcasecmp.pod GENERATE[man/man3/OPENSSL_strcasecmp.3]=man3/OPENSSL_strcasecmp.pod +DEPEND[html/man3/OSSL_ALGORITHM.html]=man3/OSSL_ALGORITHM.pod +GENERATE[html/man3/OSSL_ALGORITHM.html]=man3/OSSL_ALGORITHM.pod +DEPEND[man/man3/OSSL_ALGORITHM.3]=man3/OSSL_ALGORITHM.pod +GENERATE[man/man3/OSSL_ALGORITHM.3]=man3/OSSL_ALGORITHM.pod +DEPEND[html/man3/OSSL_CALLBACK.html]=man3/OSSL_CALLBACK.pod +GENERATE[html/man3/OSSL_CALLBACK.html]=man3/OSSL_CALLBACK.pod +DEPEND[man/man3/OSSL_CALLBACK.3]=man3/OSSL_CALLBACK.pod +GENERATE[man/man3/OSSL_CALLBACK.3]=man3/OSSL_CALLBACK.pod DEPEND[html/man3/OSSL_CMP_CTX_new.html]=man3/OSSL_CMP_CTX_new.pod GENERATE[html/man3/OSSL_CMP_CTX_new.html]=man3/OSSL_CMP_CTX_new.pod DEPEND[man/man3/OSSL_CMP_CTX_new.3]=man3/OSSL_CMP_CTX_new.pod @@ -1619,6 +1627,10 @@ DEPEND[html/man3/OSSL_DECODER_from_bio.html]=man3/OSSL_DECODER_from_bio.pod GENERATE[html/man3/OSSL_DECODER_from_bio.html]=man3/OSSL_DECODER_from_bio.pod DEPEND[man/man3/OSSL_DECODER_from_bio.3]=man3/OSSL_DECODER_from_bio.pod GENERATE[man/man3/OSSL_DECODER_from_bio.3]=man3/OSSL_DECODER_from_bio.pod +DEPEND[html/man3/OSSL_DISPATCH.html]=man3/OSSL_DISPATCH.pod +GENERATE[html/man3/OSSL_DISPATCH.html]=man3/OSSL_DISPATCH.pod +DEPEND[man/man3/OSSL_DISPATCH.3]=man3/OSSL_DISPATCH.pod +GENERATE[man/man3/OSSL_DISPATCH.3]=man3/OSSL_DISPATCH.pod DEPEND[html/man3/OSSL_ENCODER.html]=man3/OSSL_ENCODER.pod GENERATE[html/man3/OSSL_ENCODER.html]=man3/OSSL_ENCODER.pod DEPEND[man/man3/OSSL_ENCODER.3]=man3/OSSL_ENCODER.pod @@ -1651,6 +1663,10 @@ DEPEND[html/man3/OSSL_HTTP_transfer.html]=man3/OSSL_HTTP_transfer.pod GENERATE[html/man3/OSSL_HTTP_transfer.html]=man3/OSSL_HTTP_transfer.pod DEPEND[man/man3/OSSL_HTTP_transfer.3]=man3/OSSL_HTTP_transfer.pod GENERATE[man/man3/OSSL_HTTP_transfer.3]=man3/OSSL_HTTP_transfer.pod +DEPEND[html/man3/OSSL_ITEM.html]=man3/OSSL_ITEM.pod +GENERATE[html/man3/OSSL_ITEM.html]=man3/OSSL_ITEM.pod +DEPEND[man/man3/OSSL_ITEM.3]=man3/OSSL_ITEM.pod +GENERATE[man/man3/OSSL_ITEM.3]=man3/OSSL_ITEM.pod DEPEND[html/man3/OSSL_LIB_CTX.html]=man3/OSSL_LIB_CTX.pod GENERATE[html/man3/OSSL_LIB_CTX.html]=man3/OSSL_LIB_CTX.pod DEPEND[man/man3/OSSL_LIB_CTX.3]=man3/OSSL_LIB_CTX.pod @@ -3120,6 +3136,8 @@ html/man3/OPENSSL_malloc.html \ html/man3/OPENSSL_s390xcap.html \ html/man3/OPENSSL_secure_malloc.html \ html/man3/OPENSSL_strcasecmp.html \ +html/man3/OSSL_ALGORITHM.html \ +html/man3/OSSL_CALLBACK.html \ html/man3/OSSL_CMP_CTX_new.html \ html/man3/OSSL_CMP_HDR_get0_transactionID.html \ html/man3/OSSL_CMP_ITAV_set0.html \ @@ -3140,6 +3158,7 @@ html/man3/OSSL_DECODER.html \ html/man3/OSSL_DECODER_CTX.html \ html/man3/OSSL_DECODER_CTX_new_for_pkey.html \ html/man3/OSSL_DECODER_from_bio.html \ +html/man3/OSSL_DISPATCH.html \ html/man3/OSSL_ENCODER.html \ html/man3/OSSL_ENCODER_CTX.html \ html/man3/OSSL_ENCODER_CTX_new_for_pkey.html \ @@ -3148,6 +3167,7 @@ html/man3/OSSL_ESS_check_signing_certs.html \ html/man3/OSSL_HTTP_REQ_CTX.html \ html/man3/OSSL_HTTP_parse_url.html \ html/man3/OSSL_HTTP_transfer.html \ +html/man3/OSSL_ITEM.html \ html/man3/OSSL_LIB_CTX.html \ html/man3/OSSL_PARAM.html \ html/man3/OSSL_PARAM_BLD.html \ @@ -3716,6 +3736,8 @@ man/man3/OPENSSL_malloc.3 \ man/man3/OPENSSL_s390xcap.3 \ man/man3/OPENSSL_secure_malloc.3 \ man/man3/OPENSSL_strcasecmp.3 \ +man/man3/OSSL_ALGORITHM.3 \ +man/man3/OSSL_CALLBACK.3 \ man/man3/OSSL_CMP_CTX_new.3 \ man/man3/OSSL_CMP_HDR_get0_transactionID.3 \ man/man3/OSSL_CMP_ITAV_set0.3 \ @@ -3736,6 +3758,7 @@ man/man3/OSSL_DECODER.3 \ man/man3/OSSL_DECODER_CTX.3 \ man/man3/OSSL_DECODER_CTX_new_for_pkey.3 \ man/man3/OSSL_DECODER_from_bio.3 \ +man/man3/OSSL_DISPATCH.3 \ man/man3/OSSL_ENCODER.3 \ man/man3/OSSL_ENCODER_CTX.3 \ man/man3/OSSL_ENCODER_CTX_new_for_pkey.3 \ @@ -3744,6 +3767,7 @@ man/man3/OSSL_ESS_check_signing_certs.3 \ man/man3/OSSL_HTTP_REQ_CTX.3 \ man/man3/OSSL_HTTP_parse_url.3 \ man/man3/OSSL_HTTP_transfer.3 \ +man/man3/OSSL_ITEM.3 \ man/man3/OSSL_LIB_CTX.3 \ man/man3/OSSL_PARAM.3 \ man/man3/OSSL_PARAM_BLD.3 \ diff --git a/doc/man3/OSSL_ALGORITHM.pod b/doc/man3/OSSL_ALGORITHM.pod new file mode 100644 index 0000000000000..cc9271b9a412c --- /dev/null +++ b/doc/man3/OSSL_ALGORITHM.pod @@ -0,0 +1,151 @@ +=pod + +=head1 NAME + +OSSL_ALGORITHM - OpenSSL Core type to define a fetchable algorithm + +=head1 SYNOPSIS + + #include + + typedef struct ossl_algorithm_st OSSL_ALGORITHM; + struct ossl_algorithm_st { + const char *algorithm_names; /* key */ + const char *property_definition; /* key */ + const OSSL_DISPATCH *implementation; + const char *algorithm_description; + }; + +=head1 DESCRIPTION + +The B type is a I that describes an +algorithm that a L provides. Arrays of this type are returned +by providers on demand from the OpenSSL libraries to describe what +algorithms the providers provide implementations of, and with what +properties. + +Arrays of this type must be terminated with a tuple where I +is NULL. + +This type of array is typically returned by the provider's operation querying +function, further described in L. + +=head2 B fields + +=over 4 + +=item I + +This string is a colon separated set of names / identities, and is used by +the appropriate fetching functionality (such as L, +L, etc) to find the desired algorithm. + +Multiple names / identities allow a specific algorithm implementation to be +fetched multiple ways. For example, the RSA algorithm has the following +known identities: + +=over 4 + +=item * + +C + +=item * + +C + +This is the name of the algorithm's OBJECT IDENTIFIER (OID), as given by the +L + +=item * + +C<1.2.840.113549.1.1.1> + +This is the OID itself for C, in canonical decimal text form. + +=back + +The resulting I string would look like this: + + "RSA:rsaEncryption:1.2.840.113549.1.1.1" + +The OpenSSL libraries use the first of the algorithm names as the main +or canonical name, on a per algorithm implementation basis. + +See the notes L below for a more in +depth discussion on I and how that may interact with +applications and libraries, including OpenSSL's. + +=item I + +This string defines a set of properties associated with a particular +algorithm implementation, and is used by the appropriate fetching +functionality (such as L, L, etc) for +a finer grained lookup of an algorithm implementation, which is useful in +case multiple implementations of the same algorithm are available. + +See L for a further description of the contents of this +string. + +=item I + +Pointer to an L array, containing pointers to the +functions of a particular algorithm implementation. + +=item I + +A string with a short human-readable description of the algorithm. + +=back + +=head1 NOTES + +=head2 On the subject of algorithm names + +Providers may find the need to register ASN.1 OIDs for algorithms using +L (via the B upcall described in +L, because some application or library -- possibly still +the OpenSSL libraries, even -- use NIDs to look up algorithms. + +In that scenario, you must make sure that the corresponding B's +I includes both the short and the long name. + +Most of the time, registering ASN.1 OIDs like this shouldn't be necessary, +and applications and libraries are encouraged to use L to +get a text representation of the OID, which may be a long or short name for +OIDs that are registered, or the OID itself in canonical decimal text form +if not (or if L is called with I = 1). + +It's recommended to make sure that the corresponding B's +I include known names as well as the OID itself in +canonical decimal text form. That should cover all scenarios. + +=begin comment RETURN VALUES doesn't make sense for a manual that only +describes a type, but document checkers still want that section, and +to have more than just the section title. + +=head1 RETURN VALUES + +txt + +=end comment + +=head1 SEE ALSO + +L, L, L, +L, L + +=head1 HISTORY + +B was added in OpenSSL 3.0 + +=head1 COPYRIGHT + +Copyright 2022 The OpenSSL Project Authors. All Rights Reserved. + +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 +L. + +=cut diff --git a/doc/man3/OSSL_CALLBACK.pod b/doc/man3/OSSL_CALLBACK.pod new file mode 100644 index 0000000000000..2aef06cfd19d2 --- /dev/null +++ b/doc/man3/OSSL_CALLBACK.pod @@ -0,0 +1,77 @@ +=pod + +=head1 NAME + +OSSL_CALLBACK, OSSL_PASSPHRASE_CALLBACK - OpenSSL Core type to define callbacks + +=head1 SYNOPSIS + + #include + typedef int (OSSL_CALLBACK)(const OSSL_PARAM params[], void *arg); + typedef int (OSSL_PASSPHRASE_CALLBACK)(char *pass, size_t pass_size, + size_t *pass_len, + const OSSL_PARAM params[], + void *arg); + +=head1 DESCRIPTION + +For certain events or activities, provider functionality may need help from +the application or the calling OpenSSL libraries themselves. For example, +user input or direct (possibly optional) user output could be implemented +this way. + +Callback functions themselves are always provided by or through the calling +OpenSSL libraries, along with a generic pointer to data I. As far as +the function receiving the pointer to the function pointer and I is +concerned, the data that I points at is opaque, and the pointer should +simply be passed back to the callback function when it's called. + +=over 4 + +=item B + +This is a generic callback function. When calling this callback function, +the caller is expected to build an B array of data it wants or +is expected to pass back, and pass that as I, as well as the opaque +data pointer it received, as I. + +=item B + +This is a specialised callback function, used specifically to prompt the +user for a passphrase. When calling this callback function, a buffer to +store the pass phrase needs to be given with I, and its size with +I. The length of the prompted pass phrase will be given back in +I<*pass_len>. + +Additional parameters can be passed with the B array I, + +=back + +=begin comment RETURN VALUES doesn't make sense for a manual that only +describes a type, but document checkers still want that section, and +to have more than just the section title. + +=head1 RETURN VALUES + +txt + +=end comment + +=head1 SEE ALSO + +L + +=head1 HISTORY + +The types described here were added in OpenSSL 3.0. + +=head1 COPYRIGHT + +Copyright 2022 The OpenSSL Project Authors. All Rights Reserved. + +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 +L. + +=cut diff --git a/doc/man3/OSSL_DISPATCH.pod b/doc/man3/OSSL_DISPATCH.pod new file mode 100644 index 0000000000000..1aca4019dcbc1 --- /dev/null +++ b/doc/man3/OSSL_DISPATCH.pod @@ -0,0 +1,81 @@ +=pod + +=head1 NAME + +OSSL_DISPATCH - OpenSSL Core type to define a dispatchable function table + +=head1 SYNOPSIS + + #include + + typedef struct ossl_dispatch_st OSSL_DISPATCH; + struct ossl_dispatch_st { + int function_id; + void (*function)(void); + }; + +=head1 DESCRIPTION + +This type is a tuple of function identity and function pointer. +Arrays of this type are passed between the OpenSSL libraries and the +providers to describe what functionality one side provides to the other. + +Arrays of this type must be terminated with a tuple having function identity +zero and function pointer NULL. + +=head2 B fields + +=over 4 + +=item I + +OpenSSL defined function identity of the implemented function. + +=item I + +Pointer to the implemented function itself. Despite the generic definition +of this field, the implemented function it points to must have a function +signature that corresponds to the I + +=back + +Available function identities and corresponding function signatures are +defined in L. +Furthermore, the chosen function identities and associated function +signature must be chosen specifically for the operation that it's intended +for, as determined by the intended L array. + +Any function identity not recognised by the recipient of this type +will be ignored. +This ensures that providers built with one OpenSSL version in mind +will work together with any other OpenSSL version that supports this +mechanism. + +=begin comment RETURN VALUES doesn't make sense for a manual that only +describes a type, but document checkers still want that section, and +to have more than just the section title. + +=head1 RETURN VALUES + +txt + +=end comment + +=head1 SEE ALSO + +L, L, L + +=head1 HISTORY + +B was added in OpenSSL 3.0. + +=head1 COPYRIGHT + +Copyright 2022 The OpenSSL Project Authors. All Rights Reserved. + +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 +L. + +=cut diff --git a/doc/man3/OSSL_ITEM.pod b/doc/man3/OSSL_ITEM.pod new file mode 100644 index 0000000000000..70d4bf361b75e --- /dev/null +++ b/doc/man3/OSSL_ITEM.pod @@ -0,0 +1,56 @@ +=pod + +=head1 NAME + +OSSL_ITEM - OpenSSL Core type for generic itemized data + +=head1 SYNOPSIS + + #include + + typedef struct ossl_item_st OSSL_ITEM; + struct ossl_item_st { + unsigned int id; + void *ptr; + }; + +=head1 DESCRIPTION + +This type is a tuple of integer and pointer. +It's a generic type used as a generic descriptor, its exact meaning +being defined by how it's used. +Arrays of this type are passed between the OpenSSL libraries and the +providers, and must be terminated with a tuple where the integer is +zero and the pointer NULL. + +This is currently mainly used for the return value of the provider's error +reason strings array, see L. + +=begin comment RETURN VALUES doesn't make sense for a manual that only +describes a type, but document checkers still want that section, and +to have more than just the section title. + +=head1 RETURN VALUES + +txt + +=end comment + +=head1 SEE ALSO + +L, L, L + +=head1 HISTORY + +B was added in OpenSSL 3.0 + +=head1 COPYRIGHT + +Copyright 2022 The OpenSSL Project Authors. All Rights Reserved. + +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 +L. + +=cut diff --git a/doc/man7/openssl-core.h.pod b/doc/man7/openssl-core.h.pod index 3d1eca3e649ab..568bf397b4a7b 100644 --- a/doc/man7/openssl-core.h.pod +++ b/doc/man7/openssl-core.h.pod @@ -20,95 +20,17 @@ The types are: =over 4 -=item B +=item L -This type is a tuple of function identity and function pointer. -Arrays of this type are passed between the OpenSSL libraries and the -providers to describe what functionality one side provides to the -other. -Arrays of this type must be terminated with a tuple having function -identity zero and function pointer NULL. +=item L -The available function identities and corresponding function -signatures are defined in L. +=item L -Any function identity not recognised by the recipient of this type -will be ignored. -This ensures that providers built with one OpenSSL version in mind -will work together with any other OpenSSL version that supports this -mechanism. +=item L -=item B +=item L -This type is a tuple of integer and pointer. -It's a generic type used as a generic descriptor, its exact meaning -being defined by how it's used. -Arrays of this type are passed between the OpenSSL libraries and the -providers, and must be terminated with a tuple where the integer is -zero and the pointer NULL. - -=item B - -This type is a tuple of an algorithm name (string), a property -definition (string) and a dispatch table (array of B). -Arrays of this type are passed on demand from the providers to the -OpenSSL libraries to describe what algorithms the providers provide -implementations of, and with what properties. -Arrays of this type must be terminated with a tuple having function -identity zero and function pointer NULL. - -The algorithm names and property definitions are defined by the -providers. - -The OpenSSL libraries use the first of the algorithm names as the main -or canonical name, on a per algorithm implementation basis. - -=item B - -This type is a structure that allows passing arbitrary object data -between two parties that have no or very little shared knowledge about -their respective internal structures for that object. -It's normally passed in arrays, where the array is terminated with an -element where all fields are zero (for non-pointers) or NULL (for -pointers). - -These arrays can be used to set parameters for some object, to request -parameters, and to describe parameters. - -B is further described in L - -=item B - -This is a function type for a generic feedback callback function: - - typedef int (OSSL_CALLBACK)(const OSSL_PARAM params[], void *arg); - -A function that takes a pointer of this type should also take a -pointer to caller data. When calling this callback, the function is -expected to build an B array of data it wants or is -expected to pass back, and pass that as I, as well as -the caller data pointer it received, as I. - -=item B - -This is a function type for a generic pass phrase callback function: - - typedef int (OSSL_PASSPHRASE_CALLBACK)(char *pass, size_t pass_size, - size_t *pass_len, - const OSSL_PARAM params[], - void *arg); - -This callback can be used to prompt the user for a passphrase. When -calling it, a buffer to store the pass phrase needs to be given with -I, and its size with I. The length of the prompted -pass phrase will be given back in I<*pass_len>. - -Additional parameters can be passed with the B array -I. - -A function that takes a pointer of this type should also take a -pointer to caller data, which should be passed as I to this -callback. +=item L =back diff --git a/util/other.syms b/util/other.syms index e984176708c7c..0b7e063547f26 100644 --- a/util/other.syms +++ b/util/other.syms @@ -55,11 +55,14 @@ EVP_SIGNATURE datatype GEN_SESSION_CB datatype NAMING_AUTHORITY datatype OPENSSL_Applink external +OSSL_ALGORITHM datatype +OSSL_CALLBACK datatype OSSL_DECODER datatype OSSL_DECODER_CTX datatype OSSL_DECODER_CONSTRUCT datatype OSSL_DECODER_CLEANUP datatype OSSL_DECODER_INSTANCE datatype +OSSL_DISPATCH datatype OSSL_ENCODER datatype OSSL_ENCODER_CTX datatype OSSL_ENCODER_CONSTRUCT datatype @@ -67,8 +70,10 @@ OSSL_ENCODER_CLEANUP datatype OSSL_ENCODER_INSTANCE datatype OSSL_HTTP_bio_cb_t datatype OSSL_HTTP_REQ_CTX datatype +OSSL_ITEM datatype OSSL_LIB_CTX datatype OSSL_PARAM datatype +OSSL_PASSPHRASE_CALLBACK datatype OSSL_PROVIDER datatype OSSL_STORE_CTX datatype OSSL_STORE_INFO datatype