summaryrefslogtreecommitdiffstats
path: root/doc/man7/openssl-core.h.pod
diff options
context:
space:
mode:
authorRichard Levitte <levitte@openssl.org>2019-11-18 01:29:06 +0100
committerRichard Levitte <levitte@openssl.org>2019-11-29 20:54:48 +0100
commit0d003c52d3dcf4b076bb01a6767cdd5ace2d79f6 (patch)
treec04a81334735f506d3c94a3591e224683feb78ad /doc/man7/openssl-core.h.pod
parent36fa4d8a0df9dc168047fadd0365966c7116b31d (diff)
SERIALIZER: New API for serialization of objects through providers
Serialization is needed to be able to take a provider object (such as the provider side key data) and output it in PEM form, DER form, text form (for display), and possibly other future forms (XML? JSON? JWK?) The idea is that a serializer should be able to handle objects it has intimate knowledge of, as well as object data in OSSL_PARAM form. The latter will allow libcrypto to serialize some object with a different provider than the one holding the data, if exporting of that data is allowed and there is a serializer that can handle it. We will provide serializers for the types of objects we know about, which should be useful together with any other provider that provides implementations of the same type of object. Serializers are selected by method name and a couple of additional properties: - format used to tell what format the output should be in. Possibilities could include "format=text", "format=pem", "format=der", "format=pem-pkcs1" (traditional), "format=der-pkcs1" (traditional) - type used to tell exactly what type of data should be output, for example "type=public" (the public part of a key), "type=private" (the private part of a key), "type=domainparams" (domain parameters). This also adds a passphrase callback function type, OSSL_PASSPHRASE_CALLBACK, which is a bit like OSSL_CALLBACK, but it takes a few extra arguments to place the result in. Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/10394)
Diffstat (limited to 'doc/man7/openssl-core.h.pod')
-rw-r--r--doc/man7/openssl-core.h.pod23
1 files changed, 22 insertions, 1 deletions
diff --git a/doc/man7/openssl-core.h.pod b/doc/man7/openssl-core.h.pod
index b5323e9d21..28307a97d4 100644
--- a/doc/man7/openssl-core.h.pod
+++ b/doc/man7/openssl-core.h.pod
@@ -76,7 +76,7 @@ B<OSSL_PARAM> is further described in L<OSSL_PARAM(3)>
=item B<OSSL_CALLBACK>
-This is a function type for a generic callback function:
+This is a function type for a generic feedback callback function:
typedef int (OSSL_CALLBACK)(const OSSL_PARAM params[], void *arg);
@@ -86,6 +86,27 @@ expected to build an B<OSSL_PARAM> array of data it wants or is
expected to pass back, and pass that as I<params>, as well as
the caller data pointer it received, as I<arg>.
+=item B<OSSL_PASSPHRASE_CALLBACK>
+
+This is a function type for a generic pass phrase callback function:
+
+ typedef int (OSSL_PASSPHRASE_CALLBACK)(char *pass, size_t pass_size,
+ size_t *pass_len,
+ const OSSL_PARAM params[],
+ void *arg);
+
+This callback can be used to prompt the user for a passphrase. When
+calling it, a buffer to store the pass phrase needs to be given with
+I<pass>, and its size with I<pass_size>. The length of the prompted
+pass phrase will be given back in I<*pass_len>.
+
+Additional parameters can be passed with the B<OSSL_PARAM> array
+I<params>.
+
+A function that takes a pointer of this type should also take a
+pointer to caller data, which should be passed as I<arg> to this
+callback.
+
=back
=head1 SEE ALSO