diff options
Diffstat (limited to 'doc')
21 files changed, 1069 insertions, 1086 deletions
diff --git a/doc/man1/openssl-list.pod.in b/doc/man1/openssl-list.pod.in index df970a0959..26680849a2 100644 --- a/doc/man1/openssl-list.pod.in +++ b/doc/man1/openssl-list.pod.in @@ -19,8 +19,8 @@ B<openssl list> [B<-random-generators>] [B<-cipher-commands>] [B<-cipher-algorithms>] -[B<-serializers>] -[B<-deserializers>] +[B<-encoders>] +[B<-decoders>] [B<-public-key-algorithms>] {- output_off() if $disabled{"deprecated-3.0"}; "" -}[B<-public-key-methods>] @@ -84,18 +84,18 @@ Display a list of random number generators. See L</Display of algorithm names> for a description of how names are displayed. -=item B<-serializers> +=item B<-encoders> -Display a list of serializers. +Display a list of encoders. See L</Display of algorithm names> for a description of how names are displayed. In verbose mode, the algorithms provided by a provider will get additional information on what parameters each implementation supports. -=item B<-deserializers> +=item B<-decoders> -Display a list of deserializers. +Display a list of decoders. See L</Display of algorithm names> for a description of how names are displayed. diff --git a/doc/man3/OSSL_DECODER.pod b/doc/man3/OSSL_DECODER.pod new file mode 100644 index 0000000000..96d0a51ca5 --- /dev/null +++ b/doc/man3/OSSL_DECODER.pod @@ -0,0 +1,142 @@ +=pod + +=head1 NAME + +OSSL_DECODER, +OSSL_DECODER_fetch, +OSSL_DECODER_up_ref, +OSSL_DECODER_free, +OSSL_DECODER_provider, +OSSL_DECODER_properties, +OSSL_DECODER_is_a, +OSSL_DECODER_number, +OSSL_DECODER_do_all_provided, +OSSL_DECODER_names_do_all, +OSSL_DECODER_gettable_params, +OSSL_DECODER_get_params +- Decoder method routines + +=head1 SYNOPSIS + + #include <openssl/decoder.h> + + typedef struct ossl_decoder_st OSSL_DECODER; + + OSSL_DECODER *OSSL_DECODER_fetch(OPENSSL_CTX *ctx, const char *name, + const char *properties); + int OSSL_DECODER_up_ref(OSSL_DECODER *decoder); + void OSSL_DECODER_free(OSSL_DECODER *decoder); + const OSSL_PROVIDER *OSSL_DECODER_provider(const OSSL_DECODER *decoder); + const char *OSSL_DECODER_properties(const OSSL_DECODER *decoder); + int OSSL_DECODER_is_a(const OSSL_DECODER *decoder, const char *name); + int OSSL_DECODER_number(const OSSL_DECODER *decoder); + void OSSL_DECODER_do_all_provided(OPENSSL_CTX *libctx, + void (*fn)(OSSL_DECODER *decoder, void *arg), + void *arg); + void OSSL_DECODER_names_do_all(const OSSL_DECODER *decoder, + void (*fn)(const char *name, void *data), + void *data); + const OSSL_PARAM *OSSL_DECODER_gettable_params(OSSL_DECODER *decoder); + int OSSL_DECODER_get_params(OSSL_DECODER_CTX *ctx, const OSSL_PARAM params[]); + +=head1 DESCRIPTION + +B<OSSL_DECODER> is a method for decoders, which know how to +decode encoded data into an object of some type that the rest +of OpenSSL knows how to handle. + +OSSL_DECODER_fetch() looks for an algorithm within the provider that +has been loaded into the B<OPENSSL_CTX> given by I<ctx>, having the +name given by I<name> and the properties given by I<properties>. +The I<name> determines what type of object the fetched decoder +method is expected to be able to decode, and the properties are +used to determine the expected output type. +For known properties and the values they may have, please have a look +in L<provider-encoder(7)/Names and properties>. + +OSSL_DECODER_up_ref() increments the reference count for the given +I<decoder>. + +OSSL_DECODER_free() decrements the reference count for the given +I<decoder>, and when the count reaches zero, frees it. + +OSSL_DECODER_provider() returns the provider of the given +I<decoder>. + +OSSL_DECODER_properties() returns the property definition associated +with the given I<decoder>. + +OSSL_DECODER_is_a() checks if I<decoder> is an implementation +of an algorithm that's identifiable with I<name>. + +OSSL_DECODER_number() returns the internal dynamic number assigned +to the given I<decoder>. + +OSSL_DECODER_names_do_all() traverses all names for the given +I<decoder>, and calls I<fn> with each name and I<data>. + +OSSL_DECODER_do_all_provided() traverses all encoder +implementations by all activated providers in the library context +I<libctx>, and for each of the implementations, calls I<fn> with the +implementation method and I<data> as arguments. + +OSSL_DECODER_gettable_params() returns an L<OSSL_PARAM(3)> +array of parameter descriptors. + +OSSL_DECODER_get_params() attempts to get parameters specified +with an L<OSSL_PARAM(3)> array I<params>. Parameters that the +implementation doesn't recognise should be ignored. + +=head1 RETURN VALUES + +OSSL_DECODER_fetch() returns a pointer to an OSSL_DECODER object, +or NULL on error. + +OSSL_DECODER_up_ref() returns 1 on success, or 0 on error. + +OSSL_DECODER_free() doesn't return any value. + +OSSL_DECODER_provider() returns a pointer to a provider object, or +NULL on error. + +OSSL_DECODER_properties() returns a pointer to a property +definition string, or NULL on error. + +OSSL_DECODER_is_a() returns 1 if I<decoder> was identifiable, +otherwise 0. + +OSSL_DECODER_number() returns an integer. + +=head1 NOTES + +OSSL_DECODER_fetch() may be called implicitly by other fetching +functions, using the same library context and properties. +Any other API that uses keys will typically do this. + +=begin comment TODO(3.0) Add examples! + +=head1 EXAMPLES + +Text, because pod2xxx doesn't like empty sections + +=end comment + +=head1 SEE ALSO + +L<provider(7)>, L<OSSL_DECODER_CTX(3)>, L<OSSL_DECODER_from_bio(3)>, +L<OSSL_DECODER_CTX_new_by_EVP_PKEY(3)>, L<OPENSSL_CTX(3)> + +=head1 HISTORY + +The functions described here were added in OpenSSL 3.0. + +=head1 COPYRIGHT + +Copyright 2020 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 diff --git a/doc/man3/OSSL_DECODER_CTX.pod b/doc/man3/OSSL_DECODER_CTX.pod new file mode 100644 index 0000000000..7dbd7550df --- /dev/null +++ b/doc/man3/OSSL_DECODER_CTX.pod @@ -0,0 +1,74 @@ +=pod + +=head1 NAME + +OSSL_DECODER_CTX, +OSSL_DECODER_CTX_new, +OSSL_DECODER_settable_ctx_params, +OSSL_DECODER_CTX_set_params, +OSSL_DECODER_CTX_free +- Encoder context routines + +=head1 SYNOPSIS + + #include <openssl/decoder.h> + + typedef struct ossl_decoder_ctx_st OSSL_DECODER_CTX; + + OSSL_DECODER_CTX *OSSL_DECODER_CTX_new(OPENSSL_CTX *libctx); + const OSSL_PARAM *OSSL_DECODER_settable_ctx_params(OSSL_DECODER *decoder); + int OSSL_DECODER_CTX_set_params(OSSL_DECODER_CTX *ctx, + const OSSL_PARAM params[]); + void OSSL_DECODER_CTX_free(OSSL_DECODER_CTX *ctx); + +=head1 DESCRIPTION + +B<OSSL_DECODER_CTX> is a context with which B<OSSL_DECODER> +operations are performed. The context typically holds values, both +internal and supplied by the application, which are useful for the +implementations supplied by providers. + +OSSL_DECODER_CTX_new() creates a new empty B<OSSL_DECODER_CTX>. + +OSSL_DECODER_settable_ctx_params() returns an L<OSSL_PARAM(3)> +array of parameter descriptors. + +OSSL_DECODER_CTX_set_params() attempts to set parameters specified +with an L<OSSL_PARAM(3)> array I<params>. These parameters are passed +to all decoders that have been added to the I<ctx> so far. +Parameters that an implementation doesn't recognise should be ignored +by it. + +OSSL_DECODER_CTX_free() frees the given context I<ctx>. + +=head1 RETURN VALUES + +OSSL_DECODER_CTX_new() returns a pointer to a +B<OSSL_DECODER_CTX>, or NULL if the context structure couldn't be +allocated. + +OSSL_DECODER_settable_ctx_params() returns an L<OSSL_PARAM(3)> +array, or NULL if none is available. + +OSSL_DECODER_CTX_set_params() returns 1 if all recognised +parameters were valid, or 0 if one of them was invalid or caused some +other failure in the implementation. + +=head1 SEE ALSO + +L<provider(7)>, L<OSSL_DECODER(3)>, L<OSSL_DECODER_from_bio(3)> + +=head1 HISTORY + +The functions described here were added in OpenSSL 3.0. + +=head1 COPYRIGHT + +Copyright 2020 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 diff --git a/doc/man3/OSSL_DECODER_CTX_new_by_EVP_PKEY.pod b/doc/man3/OSSL_DECODER_CTX_new_by_EVP_PKEY.pod new file mode 100644 index 0000000000..4486e6b001 --- /dev/null +++ b/doc/man3/OSSL_DECODER_CTX_new_by_EVP_PKEY.pod @@ -0,0 +1,109 @@ +=pod + +=head1 NAME + +OSSL_DECODER_CTX_new_by_EVP_PKEY, +OSSL_DECODER_CTX_set_passphrase, +OSSL_DECODER_CTX_set_pem_password_cb, +OSSL_DECODER_CTX_set_passphrase_ui +- Decoder routines to decode EVP_PKEYs + +=head1 SYNOPSIS + + #include <openssl/decoder.h> + + OSSL_DECODER_CTX * + OSSL_DECODER_CTX_new_by_EVP_PKEY(const EVP_PKEY *pkey, const char *input_type, + OPENSSL_CTX *libctx, const char *propquery); + + int OSSL_DECODER_CTX_set_passphrase(OSSL_DECODER_CTX *ctx, + const unsigned char *kstr, + size_t klen); + int OSSL_DECODER_CTX_set_pem_password_cb(OSSL_DECODER_CTX *ctx, + pem_password_cb *cb, + void *cbarg); + int OSSL_DECODER_CTX_set_passphrase_ui(OSSL_DECODER_CTX *ctx, + const UI_METHOD *ui_method, + void *ui_data); + +=head1 DESCRIPTION + +OSSL_DECODER_CTX_new_by_EVP_PKEY() is a utility function that +creates a B<OSSL_DECODER_CTX>, finds all applicable decoder +implementations and sets them up, so all the caller has to do next is +call functions like OSSL_DECODE_from_bio(). + +Internally OSSL_DECODER_CTX_new_by_EVP_PKEY() searches for all +available L<EVP_KEYMGMT(3)> implementations, and then builds a list of all +potential decoder implementations that may be able to process the +encoded input into data suitable for B<EVP_PKEY>s. All these +implementations are implicitly fetched using I<libctx> and I<propquery>. + +The search of decoder implementations can be limited with +I<input_type>, which specifies a starting input type. This is further +explained in L<OSSL_DECODER_CTX_set_input_type(3)>. + +If no suitable decoder was found, OSSL_DECODER_CTX_new_by_EVP_PKEY() +still creates a B<OSSL_DECODER_CTX>, but with no associated +decoder (L<OSSL_DECODER_CTX_num_decoders(3)> returns +zero). This helps the caller distinguish between an error when +creating the B<OSSL_DECODER_CTX>, and the lack the decoder +support and act accordingly. + +OSSL_DECODER_CTX_set_passphrase() gives the implementation a +pass phrase to use when decrypting the encoded private key. +Alternatively, a pass phrase callback may be specified with the +following functions. + +OSSL_DECODER_CTX_set_pem_password_cb() and +OSSL_DECODER_CTX_set_passphrase_ui() set up a callback method that +the implementation can use to prompt for a pass phrase, giving the caller +the choice of prefered pass phrase callback form. These are called +indirectly, through an internal B<OSSL_PASSPHRASE_CALLBACK> function. + +The internal B<OSSL_PASSPHRASE_CALLBACK> function caches the pass phrase, to +be re-used in all decodings that are performed in the same +decoding run +(for example, within one L<OSSL_DECODER_from_bio(3)> call). + +=for comment the name OSSL_DECODER_CTX_set_pem_password_cb() leaves +open the future possibility of having a function where the caller can set a +B<OSSL_PASSPHRASE_CALLBACK> method as another option. + +=head1 RETURN VALUES + +OSSL_DECODER_CTX_new_by_EVP_PKEY() returns a pointer to a +B<OSSL_DECODER_CTX>, or NULL if it couldn't be created. + +OSSL_DECODER_CTX_set_passphrase(), +OSSL_DECODER_CTX_set_pem_password_cb() and +OSSL_DECODER_CTX_set_passphrase_ui() +all return 1 on success, or 0 on failure. + +=head1 NOTES + +Parts of the function names are made to match already existing OpenSSL +names. + +B<EVP_PKEY> in OSSL_DECODER_CTX_new_by_EVP_PKEY() matches the type +name, thus making for the naming pattern +B<OSSL_DECODER_CTX_new_by_I<TYPE>>() when new types are handled. + +=head1 SEE ALSO + +L<provider(7)>, L<OSSL_DECODER(3)>, L<OSSL_DECODER_CTX(3)> + +=head1 HISTORY + +The functions described here were added in OpenSSL 3.0. + +=head1 COPYRIGHT + +Copyright 2020 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 diff --git a/doc/man3/OSSL_DECODER_from_bio.pod b/doc/man3/OSSL_DECODER_from_bio.pod new file mode 100644 index 0000000000..1beb74d5ff --- /dev/null +++ b/doc/man3/OSSL_DECODER_from_bio.pod @@ -0,0 +1,276 @@ +=pod + +=head1 NAME + +OSSL_DECODER_from_bio, +OSSL_DECODER_from_fp, +OSSL_DECODER_CTX_set_input_type, +OSSL_DECODER_CTX_add_decoder, +OSSL_DECODER_CTX_add_extra, +OSSL_DECODER_CTX_num_decoders, +OSSL_DECODER_INSTANCE, +OSSL_DECODER_CONSTRUCT, +OSSL_DECODER_CLEANUP, +OSSL_DECODER_CTX_set_construct, +OSSL_DECODER_CTX_set_construct_data, +OSSL_DECODER_CTX_set_cleanup, +OSSL_DECODER_CTX_get_construct, +OSSL_DECODER_CTX_get_construct_data, +OSSL_DECODER_CTX_get_cleanup, +OSSL_DECODER_export, +OSSL_DECODER_INSTANCE_decoder, +OSSL_DECODER_INSTANCE_decoder_ctx +- Routines to perform a decoding + +=head1 SYNOPSIS + + #include <openssl/decoder.h> + + int OSSL_DECODER_from_bio(OSSL_DECODER_CTX *ctx, BIO *in); + int OSSL_DECODER_from_fp(OSSL_DECODER_CTX *ctx, FILE *fp); + + int OSSL_DECODER_CTX_set_input_type(OSSL_DECODER_CTX *ctx, + const char *input_type); + int OSSL_DECODER_CTX_add_decoder(OSSL_DECODER_CTX *ctx, OSSL_DECODER *decoder); + int OSSL_DECODER_CTX_add_extra(OSSL_DECODER_CTX *ctx); + int OSSL_DECODER_CTX_num_decoders(OSSL_DECODER_CTX *ctx); + + typedef struct ossl_decoder_instance_st OSSL_DECODER_INSTANCE; + OSSL_DECODER * + OSSL_DECODER_INSTANCE_decoder(OSSL_DECODER_INSTANCE *decoder_inst); + void *OSSL_DECODER_INSTANCE_decoder_ctx(OSSL_DECODER_INSTANCE *decoder_inst); + + typedef int (OSSL_DECODER_CONSTRUCT)(OSSL_DECODER_INSTANCE *decoder_inst, + const OSSL_PARAM *params, + void *construct_data); + typedef void (OSSL_DECODER_CLEANUP)(void *construct_data); + + int OSSL_DECODER_CTX_set_construct(OSSL_DECODER_CTX *ctx, + OSSL_DECODER_CONSTRUCT *construct); + int OSSL_DECODER_CTX_set_construct_data(OSSL_DECODER_CTX *ctx, + void *construct_data); + int OSSL_DECODER_CTX_set_cleanup(OSSL_DECODER_CTX *ctx, + OSSL_DECODER_CLEANUP *cleanup); + OSSL_DECODER_CONSTRUCT *OSSL_DECODER_CTX_get_construct(OSSL_DECODER_CTX *ctx); + void *OSSL_DECODER_CTX_get_construct_data(OSSL_DECODER_CTX *ctx); + OSSL_DECODER_CLEANUP *OSSL_DECODER_CTX_get_cleanup(OSSL_DECODER_CTX *ctx); + + int OSSL_DECODER_export(OSSL_DECODER_INSTANCE *decoder_inst, + void *reference, size_t reference_sz, + OSSL_CALLBACK *export_cb, void *export_cbarg); + +Feature availability macros: + +=over 4 + +=item OSSL_DECODER_from_fp() is only available when B<OPENSSL_NO_STDIO> +is undefined. + +=back + +=head1 DESCRIPTION + +The B<OSSL_DECODER_CTX> holds data about multiple decoders, as +needed to figure out what the input data is and to attempt to unpack it into +one of several possible related results. This also includes chaining +decoders, so the output from one can become the input for another. +This allows having generic format decoders such as PEM to DER, as well +as more specialized decoders like DER to RSA. + +The chains may be limited by specifying an input type, which is considered a +starting point. +This is both considered by OSSL_DECODER_CTX_add_extra(), which will +stop adding on more decoder implementations when it has already added +those that take the specified input type, and OSSL_DECODER_from_bio(), +which will only start the decoding process with the decoder +implementations that take that input type. For example, if the input type +is set to C<DER>, a PEM to DER decoder will be ignored. + +The input type can also be NULL, which means that the caller doesn't know +what type of input they have. In this case, OSSL_DECODER_from_bio() +will simply try with one decoder implementation after the other, and +thereby discover what kind of input the caller gave it. + +For every decoding done, even an intermediary one, a constructor +provided by the caller is called to attempt to construct an appropriate type +/ structure that the caller knows how to handle from the current +decoding result. +The constructor is set with OSSL_DECODER_CTX_set_construct(). + +B<OSSL_DECODER_INSTANCE> is an opaque structure that contains +data about the decoder that was just used, and that may be +useful for the constructor. There are some functions to extract data +from this type, described further down. + +=head2 Functions + +OSSL_DECODER_from_bio() runs the decoding process for the +context I<ctx>, with the input coming from the B<BIO> I<in>. Should +it make a difference, it's recommended to have the BIO set in binary +mode rather than text mode. + +OSSL_DECODER_from_fp() does the same thing as OSSL_DECODER_from_bio(), +except that the input is coming from the B<FILE> I<fp>. + +OSSL_DECODER_CTX_add_decoder() populates the B<OSSL_DECODER_CTX> +I<ctx> with a decoder, to be used to attempt to decode some +encoded input. + +OSSL_DECODER_CTX_add_extra() finds decoders that generate +input for already added decoders, and adds them as well. This is +used to build decoder chains. + +OSSL_DECODER_CTX_set_input_type() sets the starting input type. This +limits the decoder chains to be considered, as explained in the general +description above. + +OSSL_DECODER_CTX_num_decoders() gets the number of +decoders currently added to the context I<ctx>. + +OSSL_DECODER_CTX_set_construct() sets the constructor I<construct>. + +OSSL_DECODER_CTX_set_construct_data() sets the constructor data that is +passed to the constructor every time it's called. + +OSSL_DECODER_CTX_set_cleanup() sets the constructor data I<cleanup> +function. This is called by L<OSSL_DECODER_CTX_free(3)>. + +OSSL_DECODER_CTX_get_construct(), +OSSL_DECODER_CTX_get_construct_data() and +OSSL_DECODER_CTX_get_cleanup() +return the values that have been set by +OSSL_DECODER_CTX_set_construct(), +OSSL_DECODER_CTX_set_construct_data() and +OSSL_DECODER_CTX_set_cleanup() respectively. + +OSSL_DECODER_export() is a fallback function for constructors that +cannot use the data they get directly for diverse reasons. It takes the same +decode instance I<decoder_inst> that the constructor got and an object +I<reference>, unpacks the object which it refers to, and exports it by creating +an L<OSSL_PARAM(3)> array that it then passes to I<export_cb>, along with +I<export_arg>. + +OSSL_DECODER_INSTANCE_decoder() can be used to get the +decoder method from a decoder instance I<decoder_inst>. + +OSSL_DECODER_INSTANCE_decoder-ctx() can be used to get the +decoder method's provider context from a decoder instance +I<decoder_inst>. + +=head2 Constructor + +A B<OSSL_DECODER_CONSTRUCT> gets the following arguments: + +=over 4 + +=item I<decoder_inst> + +The B<OSSL_DECODER_INSTANCE> for the decoder from which +the constructor gets its data. + +=item I<params> + +The data produced by the decoder, further described below. + +=item I<construct_data> + +The pointer that was set with OSSL_DECODE_CTX_set_construct_data(). + +=back + +The constructor is expected to return 1 when the data it receives can +be constructed, otherwise 0. + +The globally known parameters that the constructor can get in I<params> +are: + +=over 4 + +=item "data-type" (B<OSSL_DECODER_PARAM_DATA_TYPE>) <UTF8 string> + +This is a detected content type that some decoders may provide. +For example, PEM input sometimes has a type specified in its header, +and some decoders may add that information as this parameter. +This is an optional parameter, but may be useful for extra checks in +the constructor. + +=item "data" (B<OSSL_DECODER_PARAM_DATA>) <octet string> + +The decoded data itself, as an octet string. This is produced by +decoders when it's possible to pass an object in this form. Most +often, this is simply meant to be passed to the next decoder in a +chain, but could be considered final data as well, at the discretion +of the constructor. + +=item "reference" (B<OSSL_DECODER_PARAM_DATA>) <octet string> + +The decoded data itself, as a reference to an object. The +reference itself is an octet string, and can be passed to other +operations and functions within the same provider as the one that +provides I<decoder>. + +=back + +At least one of "data" or "reference" must be present, and it's +possible that both can be. A constructor should choose to use the +"reference" parameter if possible, otherwise it should use the "data" +parameter. + +If it's not possible to use the "reference" parameter, but that's +still what a constructor wants to do, it is possible to use +OSSL_DECODER_export() as a fallback. + +=head1 RETURN VALUES + +OSSL_DECODER_from_bio() and OSSL_DECODER_from_fp() return 1 on +success, or 0 on failure. + +OSSL_DECODER_CTX_add_decoder(), +OSSL_DECODER_CTX_add_extra(), +OSSL_DECODER_CTX_set_construct(), +OSSL_DECODER_CTX_set_construct_data() and +OSSL_DECODER_CTX_set_cleanup() return 1 on success, or 0 on +failure. + +OSSL_DECODER_CTX_get_construct(), +OSSL_DECODER_CTX_get_construct_data() and +OSSL_DECODER_CTX_get_cleanup() return the current pointers to the +cosntructor, the constructor data and the cleanup functions, respectively. + +OSSL_DECODER_CTX_num_decoders() returns the current +number of decoders. It returns 0 if I<ctx> is NULL. + +OSSL_DECODER_export() returns 1 on success, or 0 on failure. + +OSSL_DECODER_INSTANCE_decoder() returns an +B<OSSL_DECODER> pointer on success, or NULL on failure. + +OSSL_DECODER_INSTANCE_decoder_ctx() returns a provider +context pointer on success, or NULL on failure.> + +=begin comment TODO(3.0) Add examples! + +=head1 EXAMPLES + +Text, because pod2xxx doesn't like empty sections + +=end comment + +=head1 SEE ALSO + +L<provider(7)>, L<OSSL_DECODER_CTX(3)> + +=head1 HISTORY + +The functions described here were added in OpenSSL 3.0. + +=head1 COPYRIGHT + +Copyright 2020 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 diff --git a/doc/man3/OSSL_DESERIALIZER.pod b/doc/man3/OSSL_DESERIALIZER.pod deleted file mode 100644 index 5562a8122b..0000000000 --- a/doc/man3/OSSL_DESERIALIZER.pod +++ /dev/null @@ -1,146 +0,0 @@ -=pod - -=head1 NAME - -OSSL_DESERIALIZER, -OSSL_DESERIALIZER_fetch, -OSSL_DESERIALIZER_up_ref, -OSSL_DESERIALIZER_free, -OSSL_DESERIALIZER_provider, -OSSL_DESERIALIZER_properties, -OSSL_DESERIALIZER_is_a, -OSSL_DESERIALIZER_number, -OSSL_DESERIALIZER_do_all_provided, -OSSL_DESERIALIZER_names_do_all, -OSSL_DESERIALIZER_gettable_params, -OSSL_DESERIALIZER_get_params -- Deserializer method routines - -=head1 SYNOPSIS - - #include <openssl/deserializer.h> - - typedef struct ossl_deserializer_st OSSL_DESERIALIZER; - - OSSL_DESERIALIZER *OSSL_DESERIALIZER_fetch(OPENSSL_CTX *ctx, const char *name, - const char *properties); - int OSSL_DESERIALIZER_up_ref(OSSL_DESERIALIZER *deserializer); - void OSSL_DESERIALIZER_free(OSSL_DESERIALIZER *deserializer); - const OSSL_PROVIDER *OSSL_DESERIALIZER_provider(const OSSL_DESERIALIZER - *deserializer); - const char *OSSL_DESERIALIZER_properties(const OSSL_DESERIALIZER *deser); - int OSSL_DESERIALIZER_is_a(const OSSL_DESERIALIZER *deserializer, - const char *name); - int OSSL_DESERIALIZER_number(const OSSL_DESERIALIZER *deserializer); - void OSSL_DESERIALIZER_do_all_provided(OPENSSL_CTX *libctx, - void (*fn)(OSSL_DESERIALIZER *deserializer, - void *arg), - void *arg); - void OSSL_DESERIALIZER_names_do_all(const OSSL_DESERIALIZER *deserializer, - void (*fn)(const char *name, void *data), - void *data); - const OSSL_PARAM *OSSL_DESERIALIZER_gettable_params(OSSL_DESERIALIZER *deser); - int OSSL_DESERIALIZER_get_params(OSSL_DESERIALIZER_CTX *ctx, - const OSSL_PARAM params[]); - -=head1 DESCRIPTION - -B<OSSL_DESERIALIZER> is a method for deserializers, which know how to -deserialize serialized data into an object of some type that the rest -of OpenSSL knows how to handle. - -OSSL_DESERIALIZER_fetch() looks for an algorithm within the provider that -has been loaded into the B<OPENSSL_CTX> given by I<ctx>, having the -name given by I<name> and the properties given by I<properties>. -The I<name> determines what type of object the fetched deserializer -method is expected to be able to deserialize, and the properties are -used to determine the expected output type. -For known properties and the values they may have, please have a look -in L<provider-serializer(7)/Names and properties>. - -OSSL_DESERIALIZER_up_ref() increments the reference count for the given -I<deserializer>. - -OSSL_DESERIALIZER_free() decrements the reference count for the given -I<deserializer>, and when the count reaches zero, frees it. - -OSSL_DESERIALIZER_provider() returns the provider of the given -I<deserializer>. - -OSSL_DESERIALIZER_properties() returns the property definition associated -with the given I<deserializer>. - -OSSL_DESERIALIZER_is_a() checks if I<deserializer> is an implementation -of an algorithm that's identifiable with I<name>. - -OSSL_DESERIALIZER_number() returns the internal dynamic number assigned -to the given I<deserializer>. - -OSSL_DESERIALIZER_names_do_all() traverses all names for the given -I<deserializer>, and calls I<fn> with each name and I<data>. - -OSSL_DESERIALIZER_do_all_provided() traverses all serializer -implementations by all activated providers in the library context -I<libctx>, and for each of the implementations, calls I<fn> with the -implementation method and I<data> as arguments. - -OSSL_DESERIALIZER_gettable_params() returns an L<OSSL_PARAM(3)> -array of parameter descriptors. - -OSSL_DESERIALIZER_get_params() attempts to get parameters specified -with an L<OSSL_PARAM(3)> array I<params>. Parameters that the -implementation doesn't recognise should be ignored. - -=head1 RETURN VALUES - -OSSL_DESERIALIZER_fetch() returns a pointer to an OSSL_DESERIALIZER object, -or NULL on error. - -OSSL_DESERIALIZER_up_ref() returns 1 on success, or 0 on error. - -OSSL_DESERIALIZER_free() doesn't return any value. - -OSSL_DESERIALIZER_provider() returns a pointer to a provider object, or -NULL on error. - -OSSL_DESERIALIZER_properties() returns a pointer to a property -definition string, or NULL on error. - -OSSL_DESERIALIZER_is_a() returns 1 if I<deserializer> was identifiable, -otherwise 0. - -OSSL_DESERIALIZER_number() returns an integer. - -=head1 NOTES - -OSSL_DESERIALIZER_fetch() may be called implicitly by other fetching -functions, using the same library context and properties. -Any other API that uses keys will typically do this. - -=begin comment TODO(3.0) Add examples! - -=head1 EXAMPLES - -Text, because pod2xxx doesn't like empty sections - -=end comment - -=head1 SEE ALSO - -L<provider(7)>, L<OSSL_DESERIALIZER_CTX(3)>, L<OSSL_DESERIALIZER_from_bio(3)>, -L<OSSL_DESERIALIZER_CTX_new_by_EVP_PKEY(3)>, L<OPENSSL_CTX(3)> - -=head1 HISTORY - -The functions described here were added in OpenSSL 3.0. - -=head1 COPYRIGHT - -Copyright 2020 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 diff --git a/doc/man3/OSSL_DESERIALIZER_CTX.pod b/doc/man3/OSSL_DESERIALIZER_CTX.pod deleted file mode 100644 index 413584f8dc..0000000000 --- a/doc/man3/OSSL_DESERIALIZER_CTX.pod +++ /dev/null @@ -1,74 +0,0 @@ -=pod - -=head1 NAME - -OSSL_DESERIALIZER_CTX, -OSSL_DESERIALIZER_CTX_new, -OSSL_DESERIALIZER_settable_ctx_params, -OSSL_DESERIALIZER_CTX_set_params, -OSSL_DESERIALIZER_CTX_free -- Serializer context routines - -=head1 SYNOPSIS - - #include <openssl/deserializer.h> - - typedef struct ossl_deserializer_ctx_st OSSL_DESERIALIZER_CTX; - - OSSL_DESERIALIZER_CTX *OSSL_DESERIALIZER_CTX_new(OPENSSL_CTX *libctx); - const OSSL_PARAM *OSSL_DESERIALIZER_settable_ctx_params(OSSL_DESERIALIZER *deser); - int OSSL_DESERIALIZER_CTX_set_params(OSSL_DESERIALIZER_CTX *ctx, - const OSSL_PARAM params[]); - void OSSL_DESERIALIZER_CTX_free(OSSL_DESERIALIZER_CTX *ctx); - -=head1 DESCRIPTION - -B<OSSL_DESERIALIZER_CTX> is a context with which B<OSSL_DESERIALIZER> -operations are performed. The context typically holds values, both -internal and supplied by the application, which are useful for the -implementations supplied by providers. - -OSSL_DESERIALIZER_CTX_new() creates a new empty B<OSSL_DESERIALIZER_CTX>. - -OSSL_DESERIALIZER_settable_ctx_params() returns an L<OSSL_PARAM(3)> -array of parameter descriptors. - -OSSL_DESERIALIZER_CTX_set_params() attempts to set parameters specified -with an L<OSSL_PARAM(3)> array I<params>. These parameters are passed -to all deserializers that have been added to the I<ctx> so far. -Parameters that an implementation doesn't recognise should be ignored -by it. - -OSSL_DESERIALIZER_CTX_free() frees the given context I<ctx>. - -=head1 RETURN VALUES - -OSSL_DESERIALIZER_CTX_new() returns a pointer to a -B<OSSL_DESERIALIZER_CTX>, or NULL if the context structure couldn't be -allocated. - -OSSL_DESERIALIZER_settable_ctx_params() returns an L<OSSL_PARAM(3)> -array, or NULL if none is available. - -OSSL_DESERIALIZER_CTX_set_params() returns 1 if all recognised -parameters were valid, or 0 if one of them was invalid or caused some -other failure in the implementation. - -=head1 SEE ALSO - -L<provider(7)>, L<OSSL_DESERIALIZER(3)>, L<OSSL_DESERIALIZER_from_bio(3)> - -=head1 HISTORY - -The functions described here were added in OpenSSL 3.0. - -=head1 COPYRIGHT - -Copyright 2020 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 diff --git a/doc/man3/OSSL_DESERIALIZER_CTX_new_by_EVP_PKEY.pod b/doc/man3/OSSL_DESERIALIZER_CTX_new_by_EVP_PKEY.pod deleted file mode 100644 index c8466657c9..0000000000 --- a/doc/man3/OSSL_DESERIALIZER_CTX_new_by_EVP_PKEY.pod +++ /dev/null @@ -1,111 +0,0 @@ -=pod - -=head1 NAME - -OSSL_DESERIALIZER_CTX_new_by_EVP_PKEY, -OSSL_DESERIALIZER_CTX_set_passphrase, -OSSL_DESERIALIZER_CTX_set_pem_password_cb, -OSSL_DESERIALIZER_CTX_set_passphrase_ui -- Deserializer routines to deserialize EVP_PKEYs - -=head1 SYNOPSIS - - #include <openssl/deserializer.h> - - OSSL_DESERIALIZER_CTX * - OSSL_DESERIALIZER_CTX_new_by_EVP_PKEY(const EVP_PKEY *pkey, - const char *input_type, - OPENSSL_CTX *libctx, - const char *propquery); - - int OSSL_DESERIALIZER_CTX_set_passphrase(OSSL_DESERIALIZER_CTX *ctx, - const unsigned char *kstr, - size_t klen); - int OSSL_DESERIALIZER_CTX_set_pem_password_cb(OSSL_DESERIALIZER_CTX *ctx, - pem_password_cb *cb, - void *cbarg); - int OSSL_DESERIALIZER_CTX_set_passphrase_ui(OSSL_DESERIALIZER_CTX *ctx, - const UI_METHOD *ui_method, - void *ui_data); - -=head1 DESCRIPTION - -OSSL_DESERIALIZER_CTX_new_by_EVP_PKEY() is a utility function that -creates a B<OSSL_DESERIALIZER_CTX>, finds all applicable deserializer -implementations and sets them up, so all the caller has to do next is -call functions like OSSL_DESERIALIZE_from_bio(). - -Internally OSSL_DESERIALIZER_CTX_new_by_EVP_PKEY() searches for all -available L<EVP_KEYMGMT(3)> implementations, and then builds a list of all -potential deserializer implementations that may be able to process the -serialized input into data suitable for B<EVP_PKEY>s. All these -implementations are implicitly fetched using I<libctx> and I<propquery>. - -The search of deserializer implementations can be limited with -I<input_type>, which specifies a starting input type. This is further -explained in L<OSSL_DESERIALIZER_CTX_set_input_type(3)>. - -If no suitable deserializer was found, OSSL_DESERIALIZER_CTX_new_by_EVP_PKEY() -still creates a B<OSSL_DESERIALIZER_CTX>, but with no associated -deserializer (L<OSSL_DESERIALIZER_CTX_num_deserializers(3)> returns -zero). This helps the caller distinguish between an error when -creating the B<OSSL_DESERIALIZER_CTX>, and the lack the deserializer -support and act accordingly. - -OSSL_DESERIALIZER_CTX_set_passphrase() gives the implementation a -pass phrase to use when decrypting the serialized private key. -Alternatively, a pass phrase callback may be specified with the -following functions. - -OSSL_DESERIALIZER_CTX_set_pem_password_cb() and -OSSL_DESERIALIZER_CTX_set_passphrase_ui() set up a callback method that -the implementation can use to prompt for a pass phrase, giving the caller -the choice of prefered pass phrase callback form. These are called -indirectly, through an internal B<OSSL_PASSPHRASE_CALLBACK> function. - -The internal B<OSSL_PASSPHRASE_CALLBACK> function caches the pass phrase, to -be re-used in all deserializations that are performed in the same -deserialization run -(for example, within one L<OSSL_DESERIALIZER_from_bio(3)> call). - -=for comment the name OSSL_DESERIALIZER_CTX_set_pem_password_cb() leaves -open the future possibility of having a function where the caller can set a -B<OSSL_PASSPHRASE_CALLBACK> method as another option. - -=head1 RETURN VALUES - -OSSL_DESERIALIZER_CTX_new_by_EVP_PKEY() returns a pointer to a -B<OSSL_DESERIALIZER_CTX>, or NULL if it couldn't be created. - -OSSL_DESERIALIZER_CTX_set_passphrase(), -OSSL_DESERIALIZER_CTX_set_pem_password_cb() and -OSSL_DESERIALIZER_CTX_set_passphrase_ui() -all return 1 on success, or 0 on failure. - -=head1 NOTES - -Parts of the function names are made to match already existing OpenSSL -names. - -B<EVP_PKEY> in OSSL_DESERIALIZER_CTX_new_by_EVP_PKEY() matches the type -name, thus making for the naming pattern -B<OSSL_DESERIALIZER_CTX_new_by_I<TYPE>>() when new types are handled. - -=head1 SEE ALSO - -L<provider(7)>, L<OSSL_DESERIALIZER(3)>, L<OSSL_DESERIALIZER_CTX(3)> - -=head1 HISTORY - -The functions described here were added in OpenSSL 3.0. - -=head1 COPYRIGHT - -Copyright 2020 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 diff --git a/doc/man3/OSSL_DESERIALIZER_from_bio.pod b/doc/man3/OSSL_DESERIALIZER_from_bio.pod deleted file mode 100644 index 1aa54899a5..0000000000 --- a/doc/man3/OSSL_DESERIALIZER_from_bio.pod +++ /dev/null @@ -1,280 +0,0 @@ -=pod - -=head1 NAME - -OSSL_DESERIALIZER_from_bio, -OSSL_DESERIALIZER_from_fp, -OSSL_DESERIALIZER_CTX_set_input_type, -OSSL_DESERIALIZER_CTX_add_deserializer, -OSSL_DESERIALIZER_CTX_add_extra, -OSSL_DESERIALIZER_CTX_num_deserializers, -OSSL_DESERIALIZER_INSTANCE, -OSSL_DESERIALIZER_CONSTRUCT, -OSSL_DESERIALIZER_CLEANUP, -OSSL_DESERIALIZER_CTX_set_construct, -OSSL_DESERIALIZER_CTX_set_construct_data, -OSSL_DESERIALIZER_CTX_set_cleanup, -OSSL_DESERIALIZER_CTX_get_construct, -OSSL_DESERIALIZER_CTX_get_construct_data, -OSSL_DESERIALIZER_CTX_get_cleanup, -OSSL_DESERIALIZER_export, -OSSL_DESERIALIZER_INSTANCE_deserializer, -OSSL_DESERIALIZER_INSTANCE_deserializer_ctx -- Routines to perform a deserialization - -=head1 SYNOPSIS - - #include <openssl/deserializer.h> - - int OSSL_DESERIALIZER_from_bio(OSSL_DESERIALIZER_CTX *ctx, BIO *in); - int OSSL_DESERIALIZER_from_fp(OSSL_DESERIALIZER_CTX *ctx, FILE *fp); - - int OSSL_DESERIALIZER_CTX_set_input_type(OSSL_DESERIALIZER_CTX *ctx, - const char *input_type); - int OSSL_DESERIALIZER_CTX_add_deserializer(OSSL_DESERIALIZER_CTX *ctx, - OSSL_DESERIALIZER *deser); - int OSSL_DESERIALIZER_CTX_add_extra(OSSL_DESERIALIZER_CTX *ctx); - int OSSL_DESERIALIZER_CTX_num_deserializers(OSSL_DESERIALIZER_CTX *ctx); - - typedef struct ossl_deserializer_instance_st OSSL_DESERIALIZER_INSTANCE; - OSSL_DESERIALIZER *OSSL_DESERIALIZER_INSTANCE_deserializer - (OSSL_DESERIALIZER_INSTANCE *deser_inst); - void *OSSL_DESERIALIZER_INSTANCE_deserializer_ctx - (OSSL_DESERIALIZER_INSTANCE *deser_inst); - - typedef int (OSSL_DESERIALIZER_CONSTRUCT) - (OSSL_DESERIALIZER_INSTANCE *deser_inst, - const OSSL_PARAM *params, void *construct_data); - typedef void (OSSL_DESERIALIZER_CLEANUP)(void *construct_data); - - int OSSL_DESERIALIZER_CTX_set_construct - (OSSL_DESERIALIZER_CTX *ctx, OSSL_DESERIALIZER_CONSTRUCT *construct); - int OSSL_DESERIALIZER_CTX_set_construct_data - (OSSL_DESERIALIZER_CTX *ctx, void *construct_data); - int OSSL_DESERIALIZER_CTX_set_cleanup(OSSL_DESERIALIZER_CTX *ctx, - OSSL_DESERIALIZER_CLEANUP *cleanup); - OSSL_DESERIALIZER_CONSTRUCT * - OSSL_DESERIALIZER_CTX_get_construct(OSSL_DESERIALIZER_CTX *ctx); - void *OSSL_DESERIALIZER_CTX_get_construct_data(OSSL_DESERIALIZER_CTX *ctx); - OSSL_DESERIALIZER_CLEANUP * - OSSL_DESERIALIZER_CTX_get_cleanup(OSSL_DESERIALIZER_CTX *ctx); - - int OSSL_DESERIALIZER_export(OSSL_DESERIALIZER_INSTANCE *deser_inst, - void *reference, size_t reference_sz, - OSSL_CALLBACK *export_cb, void *export_cbarg); - -Feature availability macros: - -=over 4 - -=item OSSL_DESERIALIZER_from_fp() is only available when B<OPENSSL_NO_STDIO> -is undefined. - -=back - -=head1 DESCRIPTION - -The B<OSSL_DESERIALIZER_CTX> holds data about multiple deserializers, as -needed to figure out what the input data is and to attempt to unpack it into -one of several possible related results. This also includes chaining -deserializers, so the output from one can become the input for another. -This allows having generic format deserializers such as PEM to DER, as well -as more specialized deserializers like DER to RSA. - -The chains may be limited by specifying an input type, which is considered a -starting point. -This is both considered by OSSL_DESERIALIZER_CTX_add_extra(), which will -stop adding on more deserializer implementations when it has already added -those that take the specified input type, and OSSL_DESERIALIZER_from_bio(), -which will only start the deserializing process with the deserializer -implementations that take that input type. For example, if the input type -is set to C<DER>, a PEM to DER deserializer will be ignored. - -The input type can also be NULL, which means that the caller doesn't know -what type of input they have. In this case, OSSL_DESERIALIZER_from_bio() -will simply try with one deserializer implementation after the other, and -thereby discover what kind of input the caller gave it. - -For every deserialization done, even an intermediary one, a constructor -provided by the caller is called to attempt to construct an appropriate type -/ structure that the caller knows how to handle from the current -deserialization result. -The constructor is set with OSSL_DESERIALIZER_CTX_set_construct(). - -B<OSSL_DESERIALIZER_INSTANCE> is an opaque structure that contains -data about the deserializer that was just used, and that may be -useful for the constructor. There are some functions to extract data -from this type, described further down. - -=head2 Functions - -OSSL_DESERIALIZER_from_bio() runs the deserialization process for the -context I<ctx>, with the input coming from the B<BIO> I<in>. Should -it make a difference, it's recommended to have the BIO set in binary -mode rather than text mode. - -OSSL_DESERIALIZER_from_fp() does the same thing as OSSL_DESERIALIZER_from_bio(), -except that the input is coming from the B<FILE> I<fp>. - -OSSL_DESERIALIZER_CTX_add_deserializer() populates the B<OSSL_DESERIALIZER_CTX> -I<ctx> with a deserializer, to be used to attempt to deserialize some -serialized input. - -OSSL_DESERIALIZER_CTX_add_extra() finds deserializers that generate -input for already added deserializers, and adds them as well. This is -used to build deserializer chains. - -OSSL_DESERIALIZER_CTX_set_input_type() sets the starting input type. This -limits the deserializer chains to be considered, as explained in the general -description above. - -OSSL_DESERIALIZER_CTX_num_deserializers() gets the number of -deserializers currently added to the context I<ctx>. - -OSSL_DESERIALIZER_CTX_set_construct() sets the constructor I<construct>. - -OSSL_DESERIALIZER_CTX_set_construct_data() sets the constructor data that is -passed to the constructor every time it's called. - -OSSL_DESERIALIZER_CTX_set_cleanup() sets the constructor data I<cleanup> -function. This is called by L<OSSL_DESERIALIZER_CTX_free(3)>. - -OSSL_DESERIALIZER_CTX_get_construct(), -OSSL_DESERIALIZER_CTX_get_construct_data() and -OSSL_DESERIALIZER_CTX_get_cleanup() -return the values that have been set by -OSSL_DESERIALIZER_CTX_set_construct(), -OSSL_DESERIALIZER_CTX_set_construct_data() and -OSSL_DESERIALIZER_CTX_set_cleanup() respectively. - -OSSL_DESERIALIZER_export() is a fallback function for constructors that -cannot use the data they get directly for diverse reasons. It takes the same -deserialize instance I<deser_inst> that the constructor got and an object -I<reference>, unpacks the object which it refers to, and exports it by creating -an L<OSSL_PARAM(3)> array that it then passes to I<export_cb>, along with -I<export_arg>. - -OSSL_DESERIALIZER_INSTANCE_deserializer() can be used to get the -deserializer method from a deserializer instance I<deser_inst>. - -OSSL_DESERIALIZER_INSTANCE_deserializer-ctx() can be used to get the -deserializer method's provider context from a deserializer instance -I<deser_inst>. - -=head2 Constructor - -A B<OSSL_DESERIALIZER_CONSTRUCT> gets the following arguments: - -=over 4 - -=item I<deser_inst> - -The B<OSSL_DESERIALIZER_INSTANCE> for the deserializer from which -the constructor gets its data. - -=item I<params> - -The data produced by the deserializer, further described below. - -=item I<construct_data> - -The pointer that was set with OSSL_DESERIALIZE_CTX_set_construct_data(). - -=back - -The constructor is expected to return 1 when the data it receives can -be constructed, otherwise 0. - -The globally known parameters that the constructor can get in I<params> -are: - -=over 4 - -=item "data-type" (B<OSSL_DESERIALIZER_PARAM_DATA_TYPE>) <UTF8 string> - -This is a detected content type that some deserializers may provide. -For example, PEM input sometimes has a type specified in its header, -and some deserializers may add that information as this parameter. -This is an optional parameter, but may be useful for extra checks in -the constructor. - -=item "data" (B<OSSL_DESERIALIZER_PARAM_DATA>) <octet string> - -The deserialized data itself, as an octet string. This is produced by -deserializers when it's possible to pass an object in this form. Most -often, this is simply meant to be passed to the next deserializer in a -chain, but could be considered final data as well, at the discretion -of the constructor. - -=item "reference" (B<OSSL_DESERIALIZER_PARAM_DATA>) <octet string> - -The deserialized data itself, as a reference to an object. The -reference itself is an octet string, and can be passed to other -operations and functions within the same provider as the one that -provides I<deser>. - -=back - -At least one of "data" or "reference" must be present, and it's -possible that both can be. A constructor should choose to use the -"reference" parameter if possible, otherwise it should use the "data" -parameter. - -If it's not possible to use the "reference" parameter, but that's -still what a constructor wants to do, it is possible to use -OSSL_DESERIALIZER_export() as a fallback. - -=head1 RETURN VALUES - -OSSL_DESERIALIZER_from_bio() and OSSL_DESERIALIZER_from_fp() return 1 on -success, or 0 on failure. - -OSSL_DESERIALIZER_CTX_add_deserializer(), -OSSL_DESERIALIZER_CTX_add_extra(), -OSSL_DESERIALIZER_CTX_set_construct(), -OSSL_DESERIALIZER_CTX_set_construct_data() and -OSSL_DESERIALIZER_CTX_set_cleanup() return 1 on success, or 0 on -failure. - -OSSL_DESERIALIZER_CTX_get_construct(), -OSSL_DESERIALIZER_CTX_get_construct_data() and -OSSL_DESERIALIZER_CTX_get_cleanup() return the current pointers to the -cosntructor, the constructor data and the cleanup functions, respectively. - -OSSL_DESERIALIZER_CTX_num_deserializers() returns the current -number of deserializers. It returns 0 if I<ctx> is NULL. - -OSSL_DESERIALIZER_export() returns 1 on success, or 0 on failure. - -OSSL_DESERIALIZER_INSTANCE_deserializer() returns an -B<OSSL_DESERIALIZER> pointer on success, or NULL on failure. - -OSSL_DESERIALIZER_INSTANCE_deserializer_ctx() returns a provider -context pointer on success, or NULL on failure.> - -=begin comment TODO(3.0) Add examples! - -=head1 EXAMPLES - -Text, because pod2xxx doesn't like empty sections - -=end comment - -=head1 SEE ALSO - -L<provider(7)>, L<OSSL_DESERIALIZER_CTX(3)> - -=head1 HISTORY - -The functions described here were added in OpenSSL 3.0. - -=head1 COPYRIGHT - -Copyright 2020 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 diff --git a/doc/man3/OSSL_ENCODER.pod b/doc/man3/OSSL_ENCODER.pod new file mode 100644 index 0000000000..d8998310bd --- /dev/null +++ b/doc/man3/OSSL_ENCODER.pod @@ -0,0 +1,126 @@ +=pod + +=head1 NAME + +OSSL_ENCODER, +OSSL_ENCODER_fetch, +OSSL_ENCODER_up_ref, +OSSL_ENCODER_free, +OSSL_ENCODER_provider, +OSSL_ENCODER_properties, +OSSL_ENCODER_is_a, +OSSL_ENCODER_number, +OSSL_ENCODER_do_all_provided, +OSSL_ENCODER_names_do_all +- Encoder method routines + +=head1 SYNOPSIS + + #include <openssl/encoder.h> + + typedef struct ossl_encoder_st OSSL_ENCODER; + + OSSL_ENCODER *OSSL_ENCODER_fetch(OPENSSL_CTX *ctx, const char *name, + const char *properties); + int OSSL_ENCODER_up_ref(OSSL_ENCODER *encoder); + void OSSL_ENCODER_free(OSSL_ENCODER *encoder); + const OSSL_PROVIDER *OSSL_ENCODER_provider(const OSSL_ENCODER *encoder); + const char *OSSL_ENCODER_properties(const OSSL_ENCODER *encoder); + int OSSL_ENCODER_is_a(const OSSL_ENCODER *encoder, const char *name); + int OSSL_ENCODER_number(const OSSL_ENCODER *encoder); + void OSSL_ENCODER_do_all_provided(OPENSSL_CTX *libctx, + void (*fn)(OSSL_ENCODER *encoder, void *arg), + void *arg); + void OSSL_ENCODER_names_do_all(const OSSL_ENCODER *encoder, + void (*fn)(const char *name, void *data), + void *data); + +=head1 DESCRIPTION + +=for comment Future development should also talk about decoding + +B<OSSL_ENCODER> is a method for encoders, which know how to +encode an object of some kind to a encoded form, such as PEM, +DER, or even human readable text. + +OSSL_ENCODER_fetch() looks for an algorithm within the provider that +has been loaded into the B<OPENSSL_CTX> given by I<ctx>, having the +name given by I<name> and the properties given by I<properties>. +The I<name> determines what type of object the fetched encoder +method is expected to be able to encode, and the properties are +used to determine the expected output type. +For known properties and the values they may have, please have a look +in L<provider-encoder(7)/Names and properties>. + +OSSL_ENCODER_up_ref() increments the reference count for the given +I<encoder>. + +OSSL_ENCODER_free() decrements the reference count for the given +I<encoder>, and when the count reaches zero, frees it. + +OSSL_ENCODER_provider() returns the provider of the given +I<encoder>. + +OSSL_ENCODER_provider() returns the property definition associated +with the given I<encoder>. + +OSSL_ENCODER_is_a() checks if I<encoder> is an implementation of an +algorithm that's identifiable with I<name>. + +OSSL_ENCODER_number() returns the internal dynamic number assigned to +the given I<encoder>. + +OSSL_ENCODER_names_do_all() traverses all names for the given +I<encoder>, and calls I<fn> with each name and I<data>. + +OSSL_ENCODER_do_all_provided() traverses all encoder +implementations by all activated providers in the library context +I<libctx>, and for each of the implementations, calls I<fn> with the +implementation method and I<data> as arguments. + +=head1 NOTES + +OSSL_ENCODER_fetch() may be called implicitly by other fetching +functions, using the same library context and properties. +Any other API that uses keys will typically do this. + +=head1 RETURN VALUES + +OSSL_ENCODER_fetch() returns a pointer to the key management +implementation represented by an OSSL_ENCODER object, or NULL on +error. + +OSSL_ENCODER_up_ref() returns 1 on success, or 0 on error. + +OSSL_ENCODER_free() doesn't return any value. + +OSSL_ENCODER_provider() returns a pointer to a provider object, or +NULL on error. + +OSSL_ENCODER_properties() returns a pointer to a property +definition string, or NULL on error. + +OSSL_ENCODER_is_a() returns 1 of I<encoder> was identifiable, +otherwise 0. + +OSSL_ENCODER_number() returns an integer. + +=head1 SEE ALSO + +L<provider(7)>, L<OSSL_ENCODER_CTX(3)>, L<OSSL_ENCODER_to_bio(3)>, +L<OSSL_ENCODER_CTX_new_by_EVP_PKEY(3)>, L<OPENSSL_CTX(3)> + +=head1 HISTORY + +The functions described here were added in OpenSSL 3.0. + +=head1 COPYRIGHT + +Copyright 2019 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 diff --git a/doc/man3/OSSL_ENCODER_CTX.pod b/doc/man3/OSSL_ENCODER_CTX.pod new file mode 100644 index 0000000000..bf339c6a4f --- /dev/null +++ b/doc/man3/OSSL_ENCODER_CTX.pod @@ -0,0 +1,93 @@ +=pod + +=head1 NAME + +OSSL_ENCODER_CTX, +OSSL_ENCODER_CTX_new, +OSSL_ENCODER_CTX_get_encoder, +OSSL_ENCODER_settable_ctx_params, +OSSL_ENCODER_CTX_set_params, +OSSL_ENCODER_CTX_free +- Encoder context routines + +=head1 SYNOPSIS + + #include <openssl/encoder.h> + + typedef struct ossl_encoder_ctx_st OSSL_ENCODER_CTX; + + OSSL_ENCODER_CTX *OSSL_ENCODER_CTX_new(OSSL_ENCODER *encoder); + const OSSL_ENCODER *OSSL_ENCODER_CTX_get_encoder(OSSL_ENCODER_CTX *ctx); + const OSSL_PARAM *OSSL_ENCODER_settable_ctx_params(OSSL_ENCODER *encoder); + int OSSL_ENCODER_CTX_set_params(OSSL_ENCODER_CTX *ctx, + const OSSL_PARAM params[]); + void OSSL_ENCODER_CTX_free(OSSL_ENCODER_CTX *ctx); + +=head1 DESCRIPTION + +B<OSSL_ENCODER_CTX> is a context with which B<OSSL_ENCODER> +operations are performed. The context typically holds values, both +internal and supplied by the application, which are useful for the +implementations supplied by providers. + +OSSL_ENCODER_CTX_new() creates a B<OSSL_ENCODER_CTX> associated +with the encoder I<encoder>. NULL is a valid I<encoder>, the context will +be created anyway, it's just not very useful. This is intentional, to +distinguish between errors in allocating the context or assigning it +values on one hand, and the lack of encoder support on the other. + +=begin comment + +The above distinction makes it possible for other routines to sense if +they need to report an error or fall back on other methods to +encode. + +=end comment + +OSSL_ENCODER_CTX_get_encoder() gets the encoder method +currently associated with the context I<ctx>. + +OSSL_ENCODER_settable_ctx_params() returns an L<OSSL_PARAM(3)> +array of parameter descriptors. + +OSSL_ENCODER_CTX_set_params() attempts to set parameters specified +with an L<OSSL_PARAM(3)> array I<params>. Parameters that the +implementation doesn't recognise should be ignored. + +OSSL_ENCODER_CTX_free() frees the given context I<ctx>. + +=head1 RETURN VALUES + +OSSL_ENCODER_CTX_new() returns a pointer to a +B<OSSL_ENCODER_CTX>, or NULL if the context structure couldn't be +allocated. + +OSSL_ENCODER_CTX_get_encoder() returns a pointer to the +encoder method associated with I<ctx>. NULL is a valid return +value and signifies that there is no associated encoder method. + +OSSL_ENCODER_settable_ctx_params() returns an L<OSSL_PARAM(3)> +array, or NULL if none is available. + +OSSL_ENCODER_CTX_set_params() returns 1 if all recognised +parameters were valid, or 0 if one of them was invalid or caused some +other failure in the implementation. + +=head1 SEE ALSO + +L<provider(7)>, L<OSSL_ENCODER(3)> + +=head1 HISTORY + +The functions described here were added in OpenSSL 3.0. + +=head1 COPYRIGHT + +Copyright 2019 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 diff --git a/doc/man3/OSSL_ENCODER_CTX_new_by_EVP_PKEY.pod b/doc/man3/OSSL_ENCODER_CTX_new_by_EVP_PKEY.pod new file mode 100644 index 0000000000..2aa103fd14 --- /dev/null +++ b/doc/man3/OSSL_ENCODER_CTX_new_by_EVP_PKEY.pod @@ -0,0 +1,144 @@ +=pod + +=head1 NAME + +OSSL_ENCODER_CTX_new_by_EVP_PKEY, +OSSL_ENCODER_CTX_set_cipher, +OSSL_ENCODER_CTX_set_passphrase, +OSSL_ENCODER_CTX_set_passphrase_cb, +OSSL_ENCODER_CTX_set_passphrase_ui, +OSSL_ENCODER_PUBKEY_TO_PEM_PQ, +OSSL_ENCODER_PrivateKey_TO_PEM_PQ, +OSSL_ENCODER_Parameters_TO_PEM_PQ, +OSSL_ENCODER_PUBKEY_TO_DER_PQ, +OSSL_ENCODER_PrivateKey_TO_DER_PQ, +OSSL_ENCODER_Parameters_TO_DER_PQ, +OSSL_ENCODER_PUBKEY_TO_TEXT_PQ, +OSSL_ENCODER_PrivateKey_TO_TEXT_PQ, +OSSL_ENCODER_Parameters_TO_TEXT_PQ +- Encoder routines to encode EVP_PKEYs + +=head1 SYNOPSIS + + #include <openssl/encoder.h> + + OSSL_ENCODER_CTX *OSSL_ENCODER_CTX_new_by_EVP_PKEY(const EVP_PKEY *pkey, + const char *propquery); + + int OSSL_ENCODER_CTX_set_cipher(OSSL_ENCODER_CTX *ctx, + const char *cipher_name, + const char *propquery); + int OSSL_ENCODER_CTX_set_passphrase(OSSL_ENCODER_CTX *ctx, + const unsigned char *kstr, + size_t klen); + int OSSL_ENCODER_CTX_set_passphrase_cb(OSSL_ENCODER_CTX *ctx, + pem_password_cb *cb, void *cbarg); + int OSSL_ENCODER_CTX_set_passphrase_ui(OSSL_ENCODER_CTX *ctx, + const UI_METHOD *ui_method, + void *ui_data); + + #define OSSL_ENCODER_PUBKEY_TO_PEM_PQ "format=pem,type=public" + #define OSSL_ENCODER_PrivateKey_TO_PEM_PQ "format=pem,type=private" + #define OSSL_ENCODER_Parameters_TO_PEM_PQ "format=pem,type=parameters" + + #define OSSL_ENCODER_PUBKEY_TO_DER_PQ "format=der,type=public" + #define OSSL_ENCODER_PrivateKey_TO_DER_PQ "format=der,type=private" + #define OSSL_ENCODER_Parameters_TO_DER_PQ "format=der,type=parameters" + + #define OSSL_ENCODER_PUBKEY_TO_TEXT_PQ "format=text,type=public" + #define OSSL_ENCODER_PrivateKey_TO_TEXT_PQ "format=text,type=private" + #define OSSL_ENCODER_Parameters_TO_TEXT_PQ "format=text,type=parameters" + +=head1 DESCRIPTION + +OSSL_ENCODER_CTX_new_by_EVP_PKEY() creates a B<OSSL_ENCODER_CTX> +with a suitable attached output routine for B<EVP_PKEY>s. It will +search for a encoder implementation that matches the algorithm of +the B<EVP_PKEY> and the property query given with I<propquery>. It +will prefer to find a encoder from the same provider as the key +data of the B<EVP_PKEY> itself, but failing that, it will choose the +first encoder that supplies a generic encoding function. + +If no suitable encoder was found, OSSL_ENCODER_CTX_new_by_EVP_PKEY() +still creates a B<OSSL_ENCODER_CTX>, but with no associated +encoder (L<OSSL_ENCODER_CTX_get_encoder(3)> returns NULL). +This helps the caller distinguish between an error when creating +the B<OSSL_ENCODER_CTX>, and the lack the encoder support and +act accordingly. + +OSSL_ENCODER_CTX_set_cipher() tells the implementation what cipher +should be used to encrypt encoded keys. The cipher is given by +name I<cipher_name>. The interpretation of that I<cipher_name> is +implementation dependent. The implementation may implement the digest +directly itself or by other implementations, or it may choose to fetch +it. If the implementation supports fetching the cipher, then it may +use I<propquery> as properties to be queried for when fetching. +I<cipher_name> may also be NULL, which will result in unencrypted +encoding. + +OSSL_ENCODER_CTX_set_passphrase() gives the implementation a +pass phrase to use when encrypting the encoded private key. +Alternatively, a pass phrase callback may be specified with the +following functions. + +OSSL_ENCODER_CTX_set_passphrase_cb() and +OSSL_ENCODER_CTX_set_passphrase_ui() sets up a callback method that +the implementation can use to prompt for a pass phrase. + +=for comment Note that the callback method is called indirectly, +through an internal B<OSSL_PASSPHRASE_CALLBACK> function. + +The macros B<OSSL_ENCODER_PUBKEY_TO_PEM_PQ>, +B<OSSL_ENCODER_PrivateKey_TO_PEM_PQ>, +B<OSSL_ENCODER_Parameters_TO_PEM_PQ>, +B<OSSL_ENCODER_PUBKEY_TO_DER_PQ>, +B<OSSL_ENCODER_PrivateKey_TO_DER_PQ>, +B<OSSL_ENCODER_Parameters_TO_DER_PQ>, +B<OSSL_ENCODER_PUBKEY_TO_TEXT_PQ>, +B<OSSL_ENCODER_PrivateKey_TO_TEXT_PQ>, +B<OSSL_ENCODER_Parameters_TO_TEXT_PQ> are convenience macros with +property queries to encode the B<EVP_PKEY> as a public key, private +key or parameters to B<PEM>, to B<DER>, or to text. + +=head1 RETURN VALUES + +OSSL_ENCODER_CTX_new_by_EVP_PKEY() returns a pointer to a +B<OSSL_ENCODER_CTX>, or NULL if it couldn't be created. + +OSSL_ENCODER_CTX_set_cipher(), +OSSL_ENCODER_CTX_set_passphrase(), +OSSL_ENCODER_CTX_set_passphrase_cb(), and +OSSL_ENCODER_CTX_set_passphrase_ui() all return 1 on success, or 0 +on failure. + +=head1 NOTES + +Parts of the function and macro names are made to match already +existing OpenSSL names. + +B<EVP_PKEY> in OSSL_ENCODER_CTX_new_by_EVP_PKEY() matches the type +name, thus making for the naming pattern +B<OSSL_ENCODER_CTX_new_by_I<TYPE>>() when new types are handled. + +B<PUBKEY>, B<PrivateKey> and B<Parameters> in the macro names match +the B<I<TYPE>> part of B<PEM_write_bio_I<TYPE>> functions as well +as B<i2d_I<TYPE>_bio> functions. + +=head1 SEE ALSO + +L<provider(7)>, L<OSSL_ENCODER(3)>, L<OSSL_ENCODER_CTX(3)> + +=head1 HISTORY + +The functions described here were added in OpenSSL 3.0. + +=head1 COPYRIGHT + +Copyright 2019-2020 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 diff --git a/doc/man3/OSSL_SERIALIZER_to_bio.pod b/doc/man3/OSSL_ENCODER_to_bio.pod index 3ed68a17ed..ee9998b2eb 100644 --- a/doc/man3/OSSL_SERIALIZER_to_bio.pod +++ b/doc/man3/OSSL_ENCODER_to_bio.pod @@ -2,46 +2,46 @@ =head1 NAME -OSSL_SERIALIZER_to_bio, -OSSL_SERIALIZER_to_fp -- Serializer file output routines +OSSL_ENCODER_to_bio, +OSSL_ENCODER_to_fp +- Encoder file output routines =head1 SYNOPSIS - #include <openssl/serializer.h> + #include <openssl/encoder.h> - int OSSL_SERIALIZER_to_bio(OSSL_SERIALIZER_CTX *ctx, BIO *out); - int OSSL_SERIALIZER_to_fp(OSSL_SERIALIZER_CTX *ctx, FILE *fp); + int OSSL_ENCODER_to_bio(OSSL_ENCODER_CTX *ctx, BIO *out); + int OSSL_ENCODER_to_fp(OSSL_ENCODER_CTX *ctx, FILE *fp); Feature availability macros: =over 4 -=item OSSL_SERIALIZER_to_fp() is only available when B<OPENSSL_NO_STDIO> +=item OSSL_ENCODER_to_fp() is only available when B<OPENSSL_NO_STDIO> is undefined. =back =head1 DESCRIPTION -OSSL_SERIALIZER_to_bio() runs the serialization process for the +OSSL_ENCODER_to_bio() runs the encoding process for the context I<ctx>, with the output going to the B<BIO> I<out>. The application is required to set up the B<BIO> properly, for example to have it in text or binary mode if that's appropriate. -=for comment Know your serializer! +=for comment Know your encoder! -OSSL_SERIALIZER_to_fp() does the same thing as OSSL_SERIALIZER_to_bio(), +OSSL_ENCODER_to_fp() does the same thing as OSSL_ENCODER_to_bio(), except that the output is going to the B<FILE> I<fp>. =head1 RETURN VALUES -OSSL_SERIALIZER_to_bio() and OSSL_SERIALIZER_to_fp() return 1 on +OSSL_ENCODER_to_bio() and OSSL_ENCODER_to_fp() return 1 on success, or 0 on failure. =head1 SEE ALSO -L<provider(7)>, L<OSSL_SERIALIZER_CTX(3)> +L<provider(7)>, L<OSSL_ENCODER_CTX(3)> =head1 HISTORY diff --git a/doc/man3/OSSL_SERIALIZER.pod b/doc/man3/OSSL_SERIALIZER.pod deleted file mode 100644 index 05b889bf60..0000000000 --- a/doc/man3/OSSL_SERIALIZER.pod +++ /dev/null @@ -1,129 +0,0 @@ -=pod - -=head1 NAME - -OSSL_SERIALIZER, -OSSL_SERIALIZER_fetch, -OSSL_SERIALIZER_up_ref, -OSSL_SERIALIZER_free, -OSSL_SERIALIZER_provider, -OSSL_SERIALIZER_properties, -OSSL_SERIALIZER_is_a, -OSSL_SERIALIZER_number, -OSSL_SERIALIZER_do_all_provided, -OSSL_SERIALIZER_names_do_all -- Serializer method routines - -=head1 SYNOPSIS - - #include <openssl/serializer.h> - - typedef struct ossl_serializer_st OSSL_SERIALIZER; - - OSSL_SERIALIZER *OSSL_SERIALIZER_fetch(OPENSSL_CTX *ctx, const char *name, - const char *properties); - int OSSL_SERIALIZER_up_ref(OSSL_SERIALIZER *serializer); - void OSSL_SERIALIZER_free(OSSL_SERIALIZER *serializer); - const OSSL_PROVIDER *OSSL_SERIALIZER_provider(const OSSL_SERIALIZER - *serializer); - const char *OSSL_SERIALIZER_properties(const OSSL_SERIALIZER *ser); - int OSSL_SERIALIZER_is_a(const OSSL_SERIALIZER *serializer, - const char *name); - int OSSL_SERIALIZER_number(const OSSL_SERIALIZER *serializer); - void OSSL_SERIALIZER_do_all_provided(OPENSSL_CTX *libctx, - void (*fn)(OSSL_SERIALIZER *serializer, - void *arg), - void *arg); - void OSSL_SERIALIZER_names_do_all(const OSSL_SERIALIZER *serializer, - void (*fn)(const char *name, void *data), - void *data); - -=head1 DESCRIPTION - -=for comment Future development should also talk about deserialization - -B<OSSL_SERIALIZER> is a method for serializers, which know how to -serialize an object of some kind to a serialized form, such as PEM, -DER, or even human readable text. - -OSSL_SERIALIZER_fetch() looks for an algorithm within the provider that -has been loaded into the B<OPENSSL_CTX> given by I<ctx>, having the -name given by I<name> and the properties given by I<properties>. -The I<name> determines what type of object the fetched serializer -method is expected to be able to serialize, and the properties are -used to determine the expected output type. -For known properties and the values they may have, please have a look -in L<provider-serializer(7)/Names and properties>. - -OSSL_SERIALIZER_up_ref() increments the reference count for the given -I<serializer>. - -OSSL_SERIALIZER_free() decrements the reference count for the given -I<serializer>, and when the count reaches zero, frees it. - -OSSL_SERIALIZER_provider() returns the provider of the given -I<serializer>. - -OSSL_SERIALIZER_provider() returns the property definition associated -with the given I<serializer>. - -OSSL_SERIALIZER_is_a() checks if I<serializer> is an implementation of an -algorithm that's identifiable with I<name>. - -OSSL_SERIALIZER_number() returns the internal dynamic number assigned to -the given I<serializer>. - -OSSL_SERIALIZER_names_do_all() traverses all names for the given -I<serializer>, and calls I<fn> with each name and I<data>. - -OSSL_SERIALIZER_do_all_provided() traverses all serializer -implementations by all activated providers in the library context -I<libctx>, and for each of the implementations, calls I<fn> with the -implementation method and I<data> as arguments. - -=head1 NOTES - -OSSL_SERIALIZER_fetch() may be called implicitly by other fetching -functions, using the same library context and properties. -Any other API that uses keys will typically do this. - -=head1 RETURN VALUES - -OSSL_SERIALIZER_fetch() returns a pointer to the key management -implementation represented by an OSSL_SERIALIZER object, or NULL on -error. - -OSSL_SERIALIZER_up_ref() returns 1 on success, or 0 on error. - -OSSL_SERIALIZER_free() doesn't return any value. - -OSSL_SERIALIZER_provider() returns a pointer to a provider object, or -NULL on error. - -OSSL_SERIALIZER_properties() returns a pointer to a property -definition string, or NULL on error. - -OSSL_SERIALIZER_is_a() returns 1 of I<serializer> was identifiable, -otherwise 0. - -OSSL_SERIALIZER_number() returns an integer. - -=head1 SEE ALSO - -L<provider(7)>, L<OSSL_SERIALIZER_CTX(3)>, L<OSSL_SERIALIZER_to_bio(3)>, -L<OSSL_SERIALIZER_CTX_new_by_EVP_PKEY(3)>, L<OPENSSL_CTX(3)> - -=head1 HISTORY - -The functions described here were added in OpenSSL 3.0. - -=head1 COPYRIGHT - -Copyright 2019 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 diff --git a/doc/man3/OSSL_SERIALIZER_CTX.pod b/doc/man3/OSSL_SERIALIZER_CTX.pod deleted file mode 100644 index d446b842d0..0000000000 --- a/doc/man3/OSSL_SERIALIZER_CTX.pod +++ /dev/null @@ -1,94 +0,0 @@ -=pod - -=head1 NAME - -OSSL_SERIALIZER_CTX, -OSSL_SERIALIZER_CTX_new, -OSSL_SERIALIZER_CTX_get_serializer, -OSSL_SERIALIZER_settable_ctx_params, -OSSL_SERIALIZER_CTX_set_params, -OSSL_SERIALIZER_CTX_free -- Serializer context routines - -=head1 SYNOPSIS - - #include <openssl/serializer.h> - - typedef struct ossl_serializer_ctx_st OSSL_SERIALIZER_CTX; - - OSSL_SERIALIZER_CTX *OSSL_SERIALIZER_CTX_new(OSSL_SERIALIZER *ser); - const OSSL_SERIALIZER * - OSSL_SERIALIZER_CTX_get_serializer(OSSL_SERIALIZER_CTX *ctx); - const OSSL_PARAM *OSSL_SERIALIZER_settable_ctx_params(OSSL_SERIALIZER *ser); - int OSSL_SERIALIZER_CTX_set_params(OSSL_SERIALIZER_CTX *ctx, - const OSSL_PARAM params[]); - void OSSL_SERIALIZER_CTX_free(OSSL_SERIALIZER_CTX *ctx); - -=head1 DESCRIPTION - -B<OSSL_SERIALIZER_CTX> is a context with which B<OSSL_SERIALIZER> -operations are performed. The context typically holds values, both -internal and supplied by the application, which are useful for the -implementations supplied by providers. - -OSSL_SERIALIZER_CTX_new() creates a B<OSSL_SERIALIZER_CTX> associated -with the serializer I<ser>. NULL is a valid I<ser>, the context will -be created anyway, it's just not very useful. This is intentional, to -distinguish between errors in allocating the context or assigning it -values on one hand, and the lack of serializer support on the other. - -=begin comment - -The above distinction makes it possible for other routines to sense if -they need to report an error or fall back on other methods to -serialize. - -=end comment - -OSSL_SERIALIZER_CTX_get_serializer() gets the serializer method -currently associated with the context I<ctx>. - -OSSL_SERIALIZER_settable_ctx_params() returns an L<OSSL_PARAM(3)> -array of parameter descriptors. - -OSSL_SERIALIZER_CTX_set_params() attempts to set parameters specified -with an L<OSSL_PARAM(3)> array I<params>. Parameters that the -implementation doesn't recognise should be ignored. - -OSSL_SERIALIZER_CTX_free() frees the given context I<ctx>. - -=head1 RETURN VALUES - -OSSL_SERIALIZER_CTX_new() returns a pointer to a -B<OSSL_SERIALIZER_CTX>, or NULL if the context structure couldn't be -allocated. - -OSSL_SERIALIZER_CTX_get_serializer() returns a pointer to the -serializer method associated with I<ctx>. NULL is a valid return -value and signifies that there is no associated serializer method. - -OSSL_SERIALIZER_settable_ctx_params() returns an L<OSSL_PARAM(3)> -array, or NULL if none is available. - -OSSL_SERIALIZER_CTX_set_params() returns 1 if all recognised -parameters were valid, or 0 if one of them was invalid or caused some -other failure in the implementation. - -=head1 SEE ALSO - -L<provider(7)>, L<OSSL_SERIALIZER(3)> - -=head1 HISTORY - -The functions described here were added in OpenSSL 3.0. - -=head1 COPYRIGHT - -Copyright 2019 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 diff --git a/doc/man3/OSSL_SERIALIZER_CTX_new_by_EVP_PKEY.pod b/doc/man3/OSSL_SERIALIZER_CTX_new_by_EVP_PKEY.pod deleted file mode 100644 index 5797ab1caa..0000000000 --- a/doc/man3/OSSL_SERIALIZER_CTX_new_by_EVP_PKEY.pod +++ /dev/null @@ -1,144 +0,0 @@ -=pod - -=head1 NAME - -OSSL_SERIALIZER_CTX_new_by_EVP_PKEY, -OSSL_SERIALIZER_CTX_set_cipher, -OSSL_SERIALIZER_CTX_set_passphrase, -OSSL_SERIALIZER_CTX_set_passphrase_cb, -OSSL_SERIALIZER_CTX_set_passphrase_ui, -OSSL_SERIALIZER_PUBKEY_TO_PEM_PQ, -OSSL_SERIALIZER_PrivateKey_TO_PEM_PQ, -OSSL_SERIALIZER_Parameters_TO_PEM_PQ, -OSSL_SERIALIZER_PUBKEY_TO_DER_PQ, -OSSL_SERIALIZER_PrivateKey_TO_DER_PQ, -OSSL_SERIALIZER_Parameters_TO_DER_PQ, -OSSL_SERIALIZER_PUBKEY_TO_TEXT_PQ, -OSSL_SERIALIZER_PrivateKey_TO_TEXT_PQ, -OSSL_SERIALIZER_Parameters_TO_TEXT_PQ -- Serializer routines to serialize EVP_PKEYs - -=head1 SYNOPSIS - - #include <openssl/serializer.h> - - OSSL_SERIALIZER_CTX *OSSL_SERIALIZER_CTX_new_by_EVP_PKEY(const EVP_PKEY *pkey, - const char *propquery); - - int OSSL_SERIALIZER_CTX_set_cipher(OSSL_SERIALIZER_CTX *ctx, - const char *cipher_name, - const char *propquery); - int OSSL_SERIALIZER_CTX_set_passphrase(OSSL_SERIALIZER_CTX *ctx, - const unsigned char *kstr, - size_t klen); - int OSSL_SERIALIZER_CTX_set_passphrase_cb(OSSL_SERIALIZER_CTX *ctx, - pem_password_cb *cb, void *cbarg); - int OSSL_SERIALIZER_CTX_set_passphrase_ui(OSSL_SERIALIZER_CTX *ctx, - const UI_METHOD *ui_method, - void *ui_data); - - #define OSSL_SERIALIZER_PUBKEY_TO_PEM_PQ "format=pem,type=public" - #define OSSL_SERIALIZER_PrivateKey_TO_PEM_PQ "format=pem,type=private" - #define OSSL_SERIALIZER_Parameters_TO_PEM_PQ "format=pem,type=parameters" - - #define OSSL_SERIALIZER_PUBKEY_TO_DER_PQ "format=der,type=public" - #define OSSL_SERIALIZER_PrivateKey_TO_DER_PQ "format=der,type=private" - #define OSSL_SERIALIZER_Parameters_TO_DER_PQ "format=der,type=parameters" - - #define OSSL_SERIALIZER_PUBKEY_TO_TEXT_PQ "format=text,type=public" - #define OSSL_SERIALIZER_PrivateKey_TO_TEXT_PQ "format=text,type=private" - #define OSSL_SERIALIZER_Parameters_TO_TEXT_PQ "format=text,type=parameters" - -=head1 DESCRIPTION - -OSSL_SERIALIZER_CTX_new_by_EVP_PKEY() creates a B<OSSL_SERIALIZER_CTX> -with a suitable attached output routine for B<EVP_PKEY>s. It will -search for a serializer implementation that matches the algorithm of -the B<EVP_PKEY> and the property query given with I<propquery>. It -will prefer to find a serializer from the same provider as the key -data of the B<EVP_PKEY> itself, but failing that, it will choose the -first serializer that supplies a generic serializing function. - -If no suitable serializer was found, OSSL_SERIALIZER_CTX_new_by_EVP_PKEY() -still creates a B<OSSL_SERIALIZER_CTX>, but with no associated -serializer (L<OSSL_SERIALIZER_CTX_get_serializer(3)> returns NULL). -This helps the caller distinguish between an error when creating -the B<OSSL_SERIALIZER_CTX>, and the lack the serializer support and -act accordingly. - -OSSL_SERIALIZER_CTX_set_cipher() tells the implementation what cipher -should be used to encrypt serialized keys. The cipher is given by -name I<cipher_name>. The interpretation of that I<cipher_name> is -implementation dependent. The implementation may implement the digest -directly itself or by other implementations, or it may choose to fetch -it. If the implementation supports fetching the cipher, then it may -use I<propquery> as properties to be queried for when fetching. -I<cipher_name> may also be NULL, which will result in unencrypted -serialization. - -OSSL_SERIALIZER_CTX_set_passphrase() gives the implementation a -pass phrase to use when encrypting the serialized private key. -Alternatively, a pass phrase callback may be specified with the -following functions. - -OSSL_SERIALIZER_CTX_set_passphrase_cb() and -OSSL_SERIALIZER_CTX_set_passphrase_ui() sets up a callback method that -the implementation can use to prompt for a pass phrase. - -=for comment Note that the callback method is called indirectly, -through an internal B<OSSL_PASSPHRASE_CALLBACK> function. - -The macros B<OSSL_SERIALIZER_PUBKEY_TO_PEM_PQ>, -B<OSSL_SERIALIZER_PrivateKey_TO_PEM_PQ>, -B<OSSL_SERIALIZER_Parameters_TO_PEM_PQ>, -B<OSSL_SERIALIZER_PUBKEY_TO_DER_PQ>, -B<OSSL_SERIALIZER_PrivateKey_TO_DER_PQ>, -B<OSSL_SERIALIZER_Parameters_TO_DER_PQ>, -B<OSSL_SERIALIZER_PUBKEY_TO_TEXT_PQ>, -B<OSSL_SERIALIZER_PrivateKey_TO_TEXT_PQ>, -B<OSSL_SERIALIZER_Parameters_TO_TEXT_PQ> are convenience macros with -property queries to serialize the B<EVP_PKEY> as a public key, private -key or parameters to B<PEM>, to B<DER>, or to text. - -=head1 RETURN VALUES - -OSSL_SERIALIZER_CTX_new_by_EVP_PKEY() returns a pointer to a -B<OSSL_SERIALIZER_CTX>, or NULL if it couldn't be created. - -OSSL_SERIALIZER_CTX_set_cipher(), -OSSL_SERIALIZER_CTX_set_passphrase(), -OSSL_SERIALIZER_CTX_set_passphrase_cb(), and -OSSL_SERIALIZER_CTX_set_passphrase_ui() all return 1 on success, or 0 -on failure. - -=head1 NOTES - -Parts of the function and macro names are made to match already -existing OpenSSL names. - -B<EVP_PKEY> in OSSL_SERIALIZER_CTX_new_by_EVP_PKEY() matches the type -name, thus making for the naming pattern -B<OSSL_SERIALIZER_CTX_new_by_I<TYPE>>() when new types are handled. - -B<PUBKEY>, B<PrivateKey> and B<Parameters> in the macro names match -the B<I<TYPE>> part of B<PEM_write_bio_I<TYPE>> functions as well -as B<i2d_I<TYPE>_bio> functions. - -=head1 SEE ALSO - -L<provider(7)>, L<OSSL_SERIALIZER(3)>, L<OSSL_SERIALIZER_CTX(3)> - -=head1 HISTORY - -The functions described here were added in OpenSSL 3.0. - -=head1 COPYRIGHT - -Copyright 2019-2020 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 diff --git a/doc/man7/OSSL_PROVIDER-FIPS.pod b/doc/man7/OSSL_PROVIDER-FIPS.pod index dd4d21f7cc..fc9c191855 100644 --- a/doc/man7/OSSL_PROVIDER-FIPS.pod +++ b/doc/man7/OSSL_PROVIDER-FIPS.pod @@ -35,7 +35,7 @@ make sure to get implementations of this provider and none other. The "fips=yes" property can be use to make sure only FIPS approved implementations are used for crypto operations. This may also include other non-crypto support operations that are not in the fips provider, -such as asymmetric key serializers, +such as asymmetric key encoders, see L<OSSL_PROVIDER-default(7)/Asymmetric Key Management>. =head1 OPERATIONS AND ALGORITHMS diff --git a/doc/man7/OSSL_PROVIDER-base.pod b/doc/man7/OSSL_PROVIDER-base.pod index 5896c5a91e..06b608be60 100644 --- a/doc/man7/OSSL_PROVIDER-base.pod +++ b/doc/man7/OSSL_PROVIDER-base.pod @@ -6,7 +6,7 @@ OSSL_PROVIDER-base - OpenSSL base provider =head1 DESCRIPTION -The OpenSSL base provider supplies the serialization for OpenSSL's +The OpenSSL base provider supplies the encoding for OpenSSL's asymmetric cryptography. =head2 Properties @@ -36,7 +36,7 @@ implementations of this provider and none other. =back These may be used in a property query string with fetching functions to select -which data are to be serialized. Either the private key material, the public +which data are to be encoded. Either the private key material, the public key material or the domain parameters can be selected. =over 4 @@ -50,32 +50,32 @@ key material or the domain parameters can be selected. =back These may be used in a property query string with fetching functions to select -the serialization output format. Either the DER, PEM and plaintext are +the encoding output format. Either the DER, PEM and plaintext are currently permitted. =head1 OPERATIONS AND ALGORITHMS The OpenSSL base provider supports these operations and algorithms: -=head2 Asymmetric Key Serializer +=head2 Asymmetric Key Encoder -In addition to "provider=base", some of these serializers define the +In addition to "provider=base", some of these encoders define the property "fips=yes", to allow them to be used together with the FIPS provider. =over 4 -=item RSA, see L<OSSL_SERIALIZER-RSA(7)> +=item RSA, see L<OSSL_ENCODER-RSA(7)> -=item DH, see L<OSSL_SERIALIZER-DH(7)> +=item DH, see L<OSSL_ENCODER-DH(7)> -=item DSA, see L<OSSL_SERIALIZER-DSA(7)> +=item DSA, see L<OSSL_ENCODER-DSA(7)> -=item EC, see L<OSSL_SERIALIZER-EC(7)> +=item EC, see L<OSSL_ENCODER-EC(7)> -=item X25519, see L<OSSL_SERIALIZER-X25519(7)> +=item X25519, see L<OSSL_ENCODER-X25519(7)> -=item X448, see L<OSSL_SERIALIZER-X448(7)> +=item X448, see L<OSSL_ENCODER-X448(7)> =back diff --git a/doc/man7/OSSL_PROVIDER-default.pod b/doc/man7/OSSL_PROVIDER-default.pod index f82f8d8551..0b477b56c1 100644 --- a/doc/man7/OSSL_PROVIDER-default.pod +++ b/doc/man7/OSSL_PROVIDER-default.pod @@ -192,25 +192,25 @@ The OpenSSL default provider supports these operations and algorithms: =back -=head2 Asymmetric Key Serializer +=head2 Asymmetric Key Encoder -The default provider also includes all of the serialization algorithms +The default provider also includes all of the encoding algorithms present in the base provider. Some of these have the property "fips=yes", to allow them to be used together with the FIPS provider. =over 4 -=item RSA, see L<OSSL_SERIALIZER-RSA(7)> +=item RSA, see L<OSSL_ENCODER-RSA(7)> -=item DH, see L<OSSL_SERIALIZER-DH(7)> +=item DH, see L<OSSL_ENCODER-DH(7)> -=item DSA, see L<OSSL_SERIALIZER-DSA(7)> +=item DSA, see L<OSSL_ENCODER-DSA(7)> -=item EC, see L<OSSL_SERIALIZER-EC(7)> +=item EC, see L<OSSL_ENCODER-EC(7)> -=item X25519, see L<OSSL_SERIALIZER-X25519(7)> +=item X25519, see L<OSSL_ENCODER-X25519(7)> -=item X448, see L<OSSL_SERIALIZER-X448(7)> +=item X448, see L<OSSL_ENCODER-X448(7)> =back diff --git a/doc/man7/provider-serializer.pod b/doc/man7/provider-encoder.pod index 0c1662837f..99787e7040 100644 --- a/doc/man7/provider-serializer.pod +++ b/doc/man7/provider-encoder.pod @@ -2,16 +2,10 @@ =head1 NAME -provider-serializer - The SERIALIZER library E<lt>-E<gt> provider functions +provider-encoder - The ENCODER library E<lt>-E<gt> provider functions =head1 SYNOPSIS -=begin comment - -Future development will also include deserializing functions. - -=end comment - #include <openssl/core_dispatch.h> /* @@ -20,39 +14,42 @@ Future development will also include deserializing functions. * pointers in OSSL_DISPATCH arrays. */ - /* Functions to construct / destruct / manipulate the serializer context */ - void *OSSL_FUNC_serializer_newctx(void *provctx); - void OSSL_FUNC_serializer_freectx(void *ctx); - int OSSL_FUNC_serializer_set_ctx_params(void *ctx, const OSSL_PARAM params[]); - const OSSL_PARAM *OSSL_FUNC_serializer_settable_ctx_params(void *provctx) + /* 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) - /* Functions to serialize object data */ - int OSSL_FUNC_serializer_serialize_data(void *ctx, const OSSL_PARAM *data, + /* Functions to encode object data */ + int OSSL_FUNC_encoder_encode_data(void *ctx, const OSSL_PARAM *data, OSSL_CORE_BIO *out, OSSL_PASSPHRASE_CALLBACK *cb, void *cbarg); - int OSSL_FUNC_serializer_serialize_object(void *ctx, void *obj, OSSL_CORE_BIO *out, + int OSSL_FUNC_encoder_encode_object(void *ctx, void *obj, OSSL_CORE_BIO *out, OSSL_PASSPHRASE_CALLBACK *cb, void *cbarg); =head1 DESCRIPTION -The SERIALIZER is a generic method to serialize any set of object data +I<We use the wide term "encode" in this manual. This includes but is +not limited to serialization.> + +The ENCODER is a generic method to encode any set of object data in L<OSSL_PARAM(3)> array form, or any provider side object into -serialized form, and write it to the given OSSL_CORE_BIO. If the caller wants -to get the serialized stream to memory, it should provide a +encoded form, and write it 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)>. -The serializer doesn't need to know more about the B<OSSL_CORE_BIO> pointer than +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 L<provider-base(7)/Core functions>). -The serialization using the L<OSSL_PARAM(3)> array form allows a -serializer to be used for data that's been exported from another +The encoding using the L<OSSL_PARAM(3)> array form allows a +encoder to be used for data that's been exported from another provider, and thereby allow them to exist independently of each other. -The serialization using a provider side object can only be safely used +The encoding using a provider side object can only be safely used with provider data coming from the same provider, for example keys with the L<KEYMGMT|provider-keymgmt(7)> provider. @@ -66,34 +63,34 @@ 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 B<OSSL_FUNC_{name}>. -For example, the "function" OSSL_FUNC_serializer_serialize_data() has these: +For example, the "function" OSSL_FUNC_encoder_encode_data() has these: typedef int - (OSSL_FUNC_serializer_serialize_data_fn)(void *provctx, + (OSSL_FUNC_encoder_encode_data_fn)(void *provctx, const OSSL_PARAM params[], OSSL_CORE_BIO *out); - static ossl_inline OSSL_FUNC_serializer_serialize_data_fn - OSSL_FUNC_serializer_serialize_data(const OSSL_DISPATCH *opf); + static ossl_inline OSSL_FUNC_encoder_encode_data_fn + OSSL_FUNC_encoder_encode_data(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: - OSSL_FUNC_serializer_newctx OSSL_FUNC_SERIALIZER_NEWCTX - OSSL_FUNC_serializer_freectx OSSL_FUNC_SERIALIZER_FREECTX - OSSL_FUNC_serializer_set_ctx_params OSSL_FUNC_SERIALIZER_SET_CTX_PARAMS - OSSL_FUNC_serializer_settable_ctx_params OSSL_FUNC_SERIALIZER_SETTABLE_CTX_PARAMS + OSSL_FUNC_encoder_newctx OSSL_FUNC_ENCODER_NEWCTX + OSSL_FUNC_encoder_freectx OSSL_FUNC_ENCODER_FREECTX + OSSL_FUNC_encoder_set_ctx_params OSSL_FUNC_ENCODER_SET_CTX_PARAMS + OSSL_FUNC_encoder_settable_ctx_params OSSL_FUNC_ENCODER_SETTABLE_CTX_PARAMS - OSSL_FUNC_serializer_serialize_data OSSL_FUNC_SERIALIZER_SERIALIZE_DATA - OSSL_FUNC_serializer_serialize_object OSSL_FUNC_SERIALIZER_SERIALIZE_OBJECT + OSSL_FUNC_encoder_encode_data OSSL_FUNC_ENCODER_ENCODE_DATA + OSSL_FUNC_encoder_encode_object OSSL_FUNC_ENCODER_ENCODE_OBJECT =head2 Names and properties The name of an implementation should match the type of object it -handles. For example, an implementation that serializes an RSA key +handles. For example, an implementation that encodes an RSA key should be named accordingly. -To be able to specify exactly what serialization format and what type -of data a serializer implementation is expected to handle, two +To be able to specify exactly what encoding format and what type +of data a encoder implementation is expected to handle, two additional properties may be given: =over 4 @@ -156,77 +153,77 @@ know anything about. =head2 Context functions -OSSL_FUNC_serializer_newctx() returns a context to be used with the rest of +OSSL_FUNC_encoder_newctx() returns a context to be used with the rest of the functions. -OSSL_FUNC_serializer_freectx() frees the given I<ctx>, if it was created by -OSSL_FUNC_serializer_newctx(). +OSSL_FUNC_encoder_freectx() frees the given I<ctx>, if it was created by +OSSL_FUNC_encoder_newctx(). -OSSL_FUNC_serializer_set_ctx_params() sets context data according to +OSSL_FUNC_encoder_set_ctx_params() sets context data according to parameters from I<params> that it recognises. Unrecognised parameters should be ignored. -OSSL_FUNC_serializer_settable_ctx_params() returns a constant B<OSSL_PARAM> -array describing the parameters that OSSL_FUNC_serializer_set_ctx_params() +OSSL_FUNC_encoder_settable_ctx_params() returns a constant B<OSSL_PARAM> +array describing the parameters that OSSL_FUNC_encoder_set_ctx_params() can handle. See L<OSSL_PARAM(3)> for further details on the parameters structure used -by OSSL_FUNC_serializer_set_ctx_params() and OSSL_FUNC_serializer_settable_ctx_params(). +by OSSL_FUNC_encoder_set_ctx_params() and OSSL_FUNC_encoder_settable_ctx_params(). -=head2 Serializing functions +=head2 Encoding functions -=for comment There will be a "Deserializing functions" title as well +=for comment There will be a "Decoding functions" title as well -OSSL_FUNC_serializer_serialize_data() should take an array of B<OSSL_PARAM>, +OSSL_FUNC_encoder_encode_data() should take an array of B<OSSL_PARAM>, I<data>, and if it contains the data necessary for the object type that the implementation handles, it should output the object in -serialized form to the B<OSSL_CORE_BIO>. +encoded form to the B<OSSL_CORE_BIO>. -OSSL_FUNC_serializer_serialize_object() should take a pointer to an object -that it knows intimately, and output that object in serialized form to +OSSL_FUNC_encoder_encode_object() should take a pointer to an object +that it knows intimately, and output that object in encoded form to the B<OSSL_CORE_BIO>. The caller I<must> ensure that this function is called with a pointer that the provider of this function is familiar with. It is not suitable to use with object pointers coming from other providers. -Both serialization functions also take an B<OSSL_PASSPHRASE_CALLBACK> +Both encoding functions also take an B<OSSL_PASSPHRASE_CALLBACK> function pointer along with a pointer to application data I<cbarg>, which should be used when a pass phrase prompt is needed. -=head2 Serializer parameters +=head2 Encoder parameters -Parameters currently recognised by built-in serializers are as +Parameters currently recognised by built-in encoders are as follows: =over 4 -=item "cipher" (B<OSSL_SERIALIZER_PARAM_CIPHER>) <UTF8 string> +=item "cipher" (B<OSSL_ENCODER_PARAM_CIPHER>) <UTF8 string> The name of the encryption cipher to be used when generating encrypted -serialization. This is used when serializing private keys, as well as +encoding. This is used when encoding private keys, as well as other objects that need protection. -If this name is invalid for the serialization implementation, the -implementation should refuse to perform the serialization, i.e. -OSSL_FUNC_serializer_serialize_data() and OSSL_FUNC_serializer_serialize_object() +If this name is invalid for the encoding implementation, the +implementation should refuse to perform the encoding, i.e. +OSSL_FUNC_encoder_encode_data() and OSSL_FUNC_encoder_encode_object() should return an error. -=item "properties" (B<OSSL_SERIALIZER_PARAM_PROPERTIES>) <UTF8 string> +=item "properties" (B<OSSL_ENCODER_PARAM_PROPERTIES>) <UTF8 string> The properties to be queried when trying to fetch the algorithm given with the "cipher" parameter. This must be given together with the "cipher" parameter to be considered valid. -The serialization implementation isn't obligated to use this value. +The encoding implementation isn't obligated to use this value. However, it is recommended that implementations that do not handle property strings return an error on receiving this parameter unless its value NULL or the empty string. -=item "passphrase" (B<OSSL_SERIALIZER_PARAM_PASS>) <octet string> +=item "passphrase" (B<OSSL_ENCODER_PARAM_PASS>) <octet string> A pass phrase provided by the application. When this is given, the -built-in serializers will not attempt to use the passphrase callback. +built-in encoders will not attempt to use the passphrase callback. =back @@ -244,16 +241,16 @@ of object it's being prompted for. =head1 RETURN VALUES -OSSL_FUNC_serializer_newctx() returns a pointer to a context, or NULL on +OSSL_FUNC_encoder_newctx() returns a pointer to a context, or NULL on failure. -OSSL_FUNC_serializer_set_ctx_params() returns 1, unless a recognised +OSSL_FUNC_encoder_set_ctx_params() returns 1, unless a recognised parameters was invalid or caused an error, for which 0 is returned. -OSSL_FUNC_serializer_settable_ctx_params() returns a pointer to an array of +OSSL_FUNC_encoder_settable_ctx_params() returns a pointer to an array of constant B<OSSL_PARAM> elements. -OSSL_FUNC_serializer_serialize_data() and OSSL_FUNC_serializer_serialize_object() +OSSL_FUNC_encoder_encode_data() and OSSL_FUNC_encoder_encode_object() return 1 on success, or 0 on failure. =head1 SEE ALSO @@ -262,7 +259,7 @@ L<provider(7)> =head1 HISTORY -The SERIALIZER interface was introduced in OpenSSL 3.0. +The ENCODER interface was introduced in OpenSSL 3.0. =head1 COPYRIGHT diff --git a/doc/man7/provider.pod b/doc/man7/provider.pod index 62ff8695f1..2f7f019650 100644 --- a/doc/man7/provider.pod +++ b/doc/man7/provider.pod @@ -154,13 +154,13 @@ The number for this operation is B<OSSL_OP_ASYM_CIPHER>. The functions the provider can offer are described in L<provider-asym_cipher(7)> -=item Serialization +=item Encoding In the OpenSSL libraries, the corresponding method object is -B<OSSL_SERIALIZER>. -The number for this operation is B<OSSL_OP_SERIALIZER>. +B<OSSL_ENCODER>. +The number for this operation is B<OSSL_OP_ENCODER>. The functions the provider can offer are described in -L<provider-serializer(7)> +L<provider-encoder(7)> =back @@ -277,7 +277,7 @@ The base provider is built in as part of the F<libcrypto> library. Should it be needed (if other providers are loaded and offer implementations of the same algorithms), the property "provider=base" can be used as a search criterion for these implementations. Some -non-cryptographic algorithms (such as serializers for loading keys and +non-cryptographic algorithms (such as encoders for loading keys and parameters from files) are not FIPS algorithm implementations in themselves but support algorithms from the FIPS provider and are allowed for use in "FIPS mode". The property "fips=yes" can be used to select such algorithms. |