mirror/openssl
2
0
Fork 0
mirror of https://github.com/openssl/openssl.git synced 2025-01-18 13:44:20 +08:00
Code Issues Packages Projects Releases Wiki Activity

Small fixes and cleanups of provider API documentation

Browse Source 
Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/14756)
This commit is contained in:
Tomas Mraz 2021-03-31 13:22:25 +02:00
parent fdb5315b2d
commit bd6e7fb7a7
13 changed files with 36 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/man7/provider-asym_cipher.pod
View File

@ -60,7 +60,7 @@ provider_query_operation() function
(see L<provider-base(7)/Provider Functions>).
All these "functions" have a corresponding function type definition
named B<OSSL_{name}_fn>, and a helper function to retrieve the
named B<OSSL_FUNC_{name}_fn>, and a helper function to retrieve the
function pointer from an B<OSSL_DISPATCH> element named
B<OSSL_FUNC_{name}>.
For example, the "function" OSSL_FUNC_asym_cipher_newctx() has these:

2
doc/man7/provider-base.pod
View File

@ -101,7 +101,7 @@ of the provider initialization function. See L<provider(7)/Provider>
for a description of the initialization function.
All these "functions" have a corresponding function type definition
named B<OSSL_{name}_fn>, and a helper function to retrieve the
named B<OSSL_FUNC_{name}_fn>, and a helper function to retrieve the
function pointer from a B<OSSL_DISPATCH> element named
B<OSSL_FUNC_{name}>.
For example, the "function" core_gettable_params() has these:

2
doc/man7/provider-cipher.pod
View File

@ -69,7 +69,7 @@ provider_query_operation() function
(see L<provider-base(7)/Provider Functions>).
All these "functions" have a corresponding function type definition
named B<OSSL_{name}_fn>, and a helper function to retrieve the
named B<OSSL_FUNC_{name}_fn>, and a helper function to retrieve the
function pointer from an B<OSSL_DISPATCH> element named
B<OSSL_FUNC_{name}>.
For example, the "function" OSSL_FUNC_cipher_newctx() has these:

2
doc/man7/provider-digest.pod
View File

@ -61,7 +61,7 @@ provider_query_operation() function
(see L<provider-base(7)/Provider Functions>).
All these "functions" have a corresponding function type definition
named B<OSSL_{name}_fn>, and a helper function to retrieve the
named B<OSSL_FUNC_{name}_fn>, and a helper function to retrieve the
function pointer from an B<OSSL_DISPATCH> element named
B<OSSL_FUNC_{name}>.
For example, the "function" OSSL_FUNC_digest_newctx() has these:

40
doc/man7/provider-encoder.pod
View File

@ -16,13 +16,13 @@ provider-encoder - The OSSL_ENCODER library E<lt>-E<gt> provider functions
/* Encoder parameter accessor and descriptor */
const OSSL_PARAM *OSSL_FUNC_encoder_gettable_params(void *provctx);
int encoder_get_params(OSSL_PARAM params[]);
int OSSL_FUNC_encoder_get_params(OSSL_PARAM params[]);
/* Functions to construct / destruct / manipulate the encoder context */
void *OSSL_FUNC_encoder_newctx(void *provctx);
void OSSL_FUNC_encoder_freectx(void *ctx);
int OSSL_FUNC_encoder_set_ctx_params(void *ctx, const OSSL_PARAM params[]);
const OSSL_PARAM *OSSL_FUNC_encoder_settable_ctx_params(void *provctx)
const OSSL_PARAM *OSSL_FUNC_encoder_settable_ctx_params(void *provctx);
/* Functions to check selection support */
int OSSL_FUNC_encoder_does_selection(void *provctx, int selection);
@ -36,9 +36,9 @@ provider-encoder - The OSSL_ENCODER library E<lt>-E<gt> provider functions
void *cbarg);
/* Functions to import and free a temporary object to be encoded */
void *encoder_import_object(void *ctx, int selection,
const OSSL_PARAM params[]);
void encoder_free_object(void *obj);
void *OSSL_FUNC_encoder_import_object(void *ctx, int selection,
const OSSL_PARAM params[]);
void OSSL_FUNC_encoder_free_object(void *obj);
=head1 DESCRIPTION
@ -50,7 +50,7 @@ The ENCODER operation is a generic method to encode a provider-native
object (I<obj_raw>) or an object abstraction (I<object_abstract>, see
L<provider-object(7)>) into an encoded form, and write the result to
the given OSSL_CORE_BIO. If the caller wants to get the encoded
stream to memory, it should provide a L<BIO_s_membuf(3)>.
stream to memory, it should provide a L<BIO_s_mem(3)> B<BIO>.
The encoder doesn't need to know more about the B<OSSL_CORE_BIO>
pointer than being able to pass it to the appropriate BIO upcalls (see
@ -89,10 +89,10 @@ provider_query_operation() function
(see L<provider-base(7)/Provider Functions>).
All these "functions" have a corresponding function type definition
named B<OSSL_{name}_fn>, and a helper function to retrieve the
function pointer from a B<OSSL_DISPATCH> element named
named B<OSSL_FUNC_{name}_fn>, and a helper function to retrieve the
function pointer from an B<OSSL_DISPATCH> element named
B<OSSL_FUNC_{name}>.
For example, the "function" OSSL_FUNC_encoder_encode_data() has these:
For example, the "function" OSSL_FUNC_encoder_encode() has these:
typedef int
(OSSL_FUNC_encoder_encode_fn)(void *ctx, OSSL_CORE_BIO *out,
@ -101,7 +101,7 @@ For example, the "function" OSSL_FUNC_encoder_encode_data() has these:
int selection,
OSSL_PASSPHRASE_CALLBACK *cb, void *cbarg);
static ossl_inline OSSL_FUNC_encoder_encode_fn
OSSL_FUNC_encoder_encode_data(const OSSL_DISPATCH *opf);
OSSL_FUNC_encoder_encode(const OSSL_DISPATCH *opf);
B<OSSL_DISPATCH> arrays are indexed by numbers that are provided as
macros in L<openssl-core_dispatch.h(7)>, as follows:
@ -116,7 +116,7 @@ macros in L<openssl-core_dispatch.h(7)>, as follows:
OSSL_FUNC_encoder_does_selection OSSL_FUNC_ENCODER_DOES_SELECTION
OSSL_FUNC_encoder_encode OSSL_FUNC_ENCODER_ENCODE_DATA
OSSL_FUNC_encoder_encode OSSL_FUNC_ENCODER_ENCODE
OSSL_FUNC_encoder_import_object OSSL_FUNC_ENCODER_IMPORT_OBJECT
OSSL_FUNC_encoder_free_object OSSL_FUNC_ENCODER_FREE_OBJECT
@ -127,14 +127,14 @@ The name of an implementation should match the type of object it handles.
For example, an implementation that encodes an RSA key should be named "RSA".
Likewise, an implementation that further encodes DER should be named "DER".
Properties can be use to further specify details about an implementation:
Properties can be used to further specify details about an implementation:
=over 4
=item output
This property is used to specify what type of output implementation
produces. Currently known output types are:
produces. OpenSSL providers recognize the following output types:
=over 4
@ -152,6 +152,14 @@ An implementation with that output type outputs PEM formatted data.
An implementation with that output type outputs DER formatted data.
=item msblob
An implementation with that output type outputs MSBLOB formatted data.
=item pvk
An implementation with that output type outputs PVK formatted data.
=back
=item structure
@ -224,7 +232,7 @@ OSSL_FUNC_encoder_import_object().
=head2 Encoding functions
OSSL_FUNC_encoder_encode() should take an provider-native object (in
OSSL_FUNC_encoder_encode() should take a provider-native object (in
I<obj_raw>) or an object abstraction (in I<obj_abstract>), and should output
the object in encoded form to the B<OSSL_CORE_BIO>. The I<selection> bits,
if relevant, should determine in greater detail what will be output.
@ -328,7 +336,7 @@ OSSL_FUNC_encoder_newctx() returns a pointer to a context, or NULL on
failure.
OSSL_FUNC_encoder_set_ctx_params() returns 1, unless a recognised
parameters was invalid or caused an error, for which 0 is returned.
parameter was invalid or caused an error, for which 0 is returned.
OSSL_FUNC_encoder_settable_ctx_params() returns a pointer to an array of
constant B<OSSL_PARAM> elements.
@ -336,7 +344,7 @@ constant B<OSSL_PARAM> elements.
OSSL_FUNC_encoder_does_selection() returns 1 if the encoder implementation
supports any of the I<selection> bits, otherwise 0.
OSSL_FUNC_encoder_encode() return 1 on success, or 0 on failure.
OSSL_FUNC_encoder_encode() returns 1 on success, or 0 on failure.
=head1 SEE ALSO

2
doc/man7/provider-kdf.pod
View File

@ -53,7 +53,7 @@ provider_query_operation() function
(see L<provider-base(7)/Provider Functions>).
All these "functions" have a corresponding function type definition
named B<OSSL_{name}_fn>, and a helper function to retrieve the
named B<OSSL_FUNC_{name}_fn>, and a helper function to retrieve the
function pointer from an B<OSSL_DISPATCH> element named
B<OSSL_FUNC_{name}>.
For example, the "function" OSSL_FUNC_kdf_newctx() has these:

2
doc/man7/provider-kem.pod
View File

@ -56,7 +56,7 @@ provider_query_operation() function
(see L<provider-base(7)/Provider Functions>).
All these "functions" have a corresponding function type definition
named B<OSSL_{name}_fn>, and a helper function to retrieve the
named B<OSSL_FUNC_{name}_fn>, and a helper function to retrieve the
function pointer from an B<OSSL_DISPATCH> element named
B<OSSL_FUNC_{name}>.
For example, the "function" OSSL_FUNC_kem_newctx() has these:

2
doc/man7/provider-keyexch.pod
View File

@ -54,7 +54,7 @@ provider_query_operation() function
(see L<provider-base(7)/Provider Functions>).
All these "functions" have a corresponding function type definition
named B<OSSL_{name}_fn>, and a helper function to retrieve the
named B<OSSL_FUNC_{name}_fn>, and a helper function to retrieve the
function pointer from an B<OSSL_DISPATCH> element named
B<OSSL_FUNC_{name}>.
For example, the "function" OSSL_FUNC_keyexch_newctx() has these:

2
doc/man7/provider-keymgmt.pod
View File

@ -78,7 +78,7 @@ provider_query_operation() function
(see L<provider-base(7)/Provider Functions>).
All these "functions" have a corresponding function type definition
named B<OSSL_{name}_fn>, and a helper function to retrieve the
named B<OSSL_FUNC_{name}_fn>, and a helper function to retrieve the
function pointer from a B<OSSL_DISPATCH> element named
B<OSSL_FUNC_{name}>.
For example, the "function" OSSL_FUNC_keymgmt_new() has these:

2
doc/man7/provider-mac.pod
View File

@ -54,7 +54,7 @@ provider_query_operation() function
(see L<provider-base(7)/Provider Functions>).
All these "functions" have a corresponding function type definition
named B<OSSL_{name}_fn>, and a helper function to retrieve the
named B<OSSL_FUNC_{name}_fn>, and a helper function to retrieve the
function pointer from an B<OSSL_DISPATCH> element named
B<OSSL_FUNC_{name}>.
For example, the "function" OSSL_FUNC_mac_newctx() has these:

2
doc/man7/provider-signature.pod
View File

@ -99,7 +99,7 @@ provider_query_operation() function
(see L<provider-base(7)/Provider Functions>).
All these "functions" have a corresponding function type definition
named B<OSSL_{name}_fn>, and a helper function to retrieve the
named B<OSSL_FUNC_{name}_fn>, and a helper function to retrieve the
function pointer from an B<OSSL_DISPATCH> element named
B<OSSL_FUNC_{name}>.
For example, the "function" OSSL_FUNC_signature_newctx() has these:

2
doc/man7/provider-storemgmt.pod
View File

@ -50,7 +50,7 @@ provider_query_operation() function
(see L<provider-base(7)/Provider Functions>).
All these "functions" have a corresponding function type definition named
B<OSSL_{name}_fn>, and a helper function to retrieve the function pointer
B<OSSL_FUNC_{name}_fn>, and a helper function to retrieve the function pointer
from a B<OSSL_DISPATCH> element named B<OSSL_get_{name}>.
For example, the "function" OSSL_FUNC_store_load() has these:

2
include/openssl/core_dispatch.h
View File

@ -851,7 +851,7 @@ OSSL_CORE_MAKE_FUNC(int, decoder_does_selection,
(void *provctx, int selection))
OSSL_CORE_MAKE_FUNC(int, decoder_decode,
(void *ctx, OSSL_CORE_BIO *in, int selection,
OSSL_CALLBACK *metadata_cb, void *metadata_cbarg,
OSSL_CALLBACK *data_cb, void *data_cbarg,
OSSL_PASSPHRASE_CALLBACK *pw_cb, void *pw_cbarg))
OSSL_CORE_MAKE_FUNC(int, decoder_export_object,
(void *ctx, const void *objref, size_t objref_sz,