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
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
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
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 \
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 \
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 \
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 \
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 \
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 \
--- /dev/null
+=pod
+
+=head1 NAME
+
+OSSL_ALGORITHM - OpenSSL Core type to define a fetchable algorithm
+
+=head1 SYNOPSIS
+
+ #include <openssl/core.h>
+
+ 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<OSSL_ALGORITHM> type is a I<public structure> that describes an
+algorithm that a L<provider(7)> 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<algorithm_names>
+is NULL.
+
+This type of array is typically returned by the provider's operation querying
+function, further described in L<provider-base(7)/Provider Functions>.
+
+=head2 B<OSSL_ALGORITHM> fields
+
+=over 4
+
+=item I<algorithm_names>
+
+This string is a colon separated set of names / identities, and is used by
+the appropriate fetching functionality (such as L<EVP_CIPHER_fetch(3)>,
+L<EVP_MD_fetch(3)>, 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<RSA>
+
+=item *
+
+C<rsaEncryption>
+
+This is the name of the algorithm's OBJECT IDENTIFIER (OID), as given by the
+L<PKCS#1 RFC's ASN.1 module|https://www.rfc-editor.org/rfc/rfc8017#appendix-C>
+
+=item *
+
+C<1.2.840.113549.1.1.1>
+
+This is the OID itself for C<rsaEncryption>, in canonical decimal text form.
+
+=back
+
+The resulting I<algorithm_names> 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</On the subject of algorithm names> below for a more in
+depth discussion on I<algorithm_names> and how that may interact with
+applications and libraries, including OpenSSL's.
+
+=item I<property_definition>
+
+This string defines a set of properties associated with a particular
+algorithm implementation, and is used by the appropriate fetching
+functionality (such as L<EVP_CIPHER_fetch(3)>, L<EVP_MD_fetch(3)>, 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<property(7)> for a further description of the contents of this
+string.
+
+=item I<implementation>
+
+Pointer to an L<OSSL_DISPATCH(3)> array, containing pointers to the
+functions of a particular algorithm implementation.
+
+=item I<algorithm_description>
+
+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<OBJ_create(3)> (via the B<core_obj_create> upcall described in
+L<provider-base(7)>, 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<OSSL_ALGORITHM>'s
+I<algorithm_names> 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<OBJ_obj2txt(3)> 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<OBJ_obj2txt(3)> is called with I<no_name> = 1).
+
+It's recommended to make sure that the corresponding B<OSSL_ALGORITHM>'s
+I<algorithm_names> 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<crypto(7)>, L<provider-base(7)>, L<openssl-core.h(7)>,
+L<openssl-core_dispatch.h(7)>, L<OSSL_DISPATCH(3)>
+
+=head1 HISTORY
+
+B<OSSL_ALGORITHM> 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<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+OSSL_CALLBACK, OSSL_PASSPHRASE_CALLBACK - OpenSSL Core type to define callbacks
+
+=head1 SYNOPSIS
+
+ #include <openssl/core.h>
+ 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<arg>. As far as
+the function receiving the pointer to the function pointer and I<arg> is
+concerned, the data that I<arg> points at is opaque, and the pointer should
+simply be passed back to the callback function when it's called.
+
+=over 4
+
+=item B<OSSL_CALLBACK>
+
+This is a generic callback function. When calling this callback function,
+the caller is expected to build an B<OSSL_PARAM> array of data it wants or
+is expected to pass back, and pass that as I<params>, as well as the opaque
+data pointer it received, as I<arg>.
+
+=item B<OSSL_PASSPHRASE_CALLBACK>
+
+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<pass>, and its size with
+I<pass_size>. The length of the prompted pass phrase will be given back in
+I<*pass_len>.
+
+Additional parameters can be passed with the B<OSSL_PARAM> array I<params>,
+
+=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<openssl-core.h(7)>
+
+=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<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+OSSL_DISPATCH - OpenSSL Core type to define a dispatchable function table
+
+=head1 SYNOPSIS
+
+ #include <openssl/core.h>
+
+ 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<OSSL_DISPATCH> fields
+
+=over 4
+
+=item I<function_id>
+
+OpenSSL defined function identity of the implemented function.
+
+=item I<function>
+
+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<function_id>
+
+=back
+
+Available function identities and corresponding function signatures are
+defined in L<openssl-core_dispatch.h(7)>.
+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<OSSL_ALGORITHM(3)> 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<crypto(7)>, L<openssl-core_dispatch.h(7)>, L<OSSL_ALGORITHM(3)>
+
+=head1 HISTORY
+
+B<OSSL_DISPATCH> 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<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+OSSL_ITEM - OpenSSL Core type for generic itemized data
+
+=head1 SYNOPSIS
+
+ #include <openssl/core.h>
+
+ 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<provider-base(7)/Provider Functions>.
+
+=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<crypto(7)>, L<provider-base(7)>, L<openssl-core.h(7)>
+
+=head1 HISTORY
+
+B<OSSL_ITEM> 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<https://www.openssl.org/source/license.html>.
+
+=cut
=over 4
-=item B<OSSL_DISPATCH>
+=item L<OSSL_DISPATCH(3)>
-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<OSSL_ITEM(3)>
-The available function identities and corresponding function
-signatures are defined in L<openssl-core_dispatch.h(7)>.
+=item L<OSSL_ALGORITHM(3)>
-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<OSSL_PARAM(3)>
-=item B<OSSL_ITEM>
+=item L<OSSL_CALLBACK(3)>
-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<OSSL_ALGORITHM>
-
-This type is a tuple of an algorithm name (string), a property
-definition (string) and a dispatch table (array of B<OSSL_DISPATCH>).
-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<OSSL_PARAM>
-
-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<OSSL_PARAM> is further described in L<OSSL_PARAM(3)>
-
-=item B<OSSL_CALLBACK>
-
-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<OSSL_PARAM> array of data it wants or is
-expected to pass back, and pass that as I<params>, as well as
-the caller data pointer it received, as I<arg>.
-
-=item B<OSSL_PASSPHRASE_CALLBACK>
-
-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<pass>, and its size with I<pass_size>. The length of the prompted
-pass phrase will be given back in I<*pass_len>.
-
-Additional parameters can be passed with the B<OSSL_PARAM> array
-I<params>.
-
-A function that takes a pointer of this type should also take a
-pointer to caller data, which should be passed as I<arg> to this
-callback.
+=item L<OSSL_PASSPHRASE_CALLBACK(3)>
=back
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
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
projects / thirdparty / openssl.git / commitdiff
