1*b077aed3SPierre Pronchery=pod 2*b077aed3SPierre Pronchery 3*b077aed3SPierre Pronchery=head1 NAME 4*b077aed3SPierre Pronchery 5*b077aed3SPierre ProncheryOSSL_CALLBACK, OSSL_PASSPHRASE_CALLBACK - OpenSSL Core type to define callbacks 6*b077aed3SPierre Pronchery 7*b077aed3SPierre Pronchery=head1 SYNOPSIS 8*b077aed3SPierre Pronchery 9*b077aed3SPierre Pronchery #include <openssl/core.h> 10*b077aed3SPierre Pronchery typedef int (OSSL_CALLBACK)(const OSSL_PARAM params[], void *arg); 11*b077aed3SPierre Pronchery typedef int (OSSL_PASSPHRASE_CALLBACK)(char *pass, size_t pass_size, 12*b077aed3SPierre Pronchery size_t *pass_len, 13*b077aed3SPierre Pronchery const OSSL_PARAM params[], 14*b077aed3SPierre Pronchery void *arg); 15*b077aed3SPierre Pronchery 16*b077aed3SPierre Pronchery=head1 DESCRIPTION 17*b077aed3SPierre Pronchery 18*b077aed3SPierre ProncheryFor certain events or activities, provider functionality may need help from 19*b077aed3SPierre Proncherythe application or the calling OpenSSL libraries themselves. For example, 20*b077aed3SPierre Proncheryuser input or direct (possibly optional) user output could be implemented 21*b077aed3SPierre Proncherythis way. 22*b077aed3SPierre Pronchery 23*b077aed3SPierre ProncheryCallback functions themselves are always provided by or through the calling 24*b077aed3SPierre ProncheryOpenSSL libraries, along with a generic pointer to data I<arg>. As far as 25*b077aed3SPierre Proncherythe function receiving the pointer to the function pointer and I<arg> is 26*b077aed3SPierre Proncheryconcerned, the data that I<arg> points at is opaque, and the pointer should 27*b077aed3SPierre Proncherysimply be passed back to the callback function when it's called. 28*b077aed3SPierre Pronchery 29*b077aed3SPierre Pronchery=over 4 30*b077aed3SPierre Pronchery 31*b077aed3SPierre Pronchery=item B<OSSL_CALLBACK> 32*b077aed3SPierre Pronchery 33*b077aed3SPierre ProncheryThis is a generic callback function. When calling this callback function, 34*b077aed3SPierre Proncherythe caller is expected to build an L<OSSL_PARAM(3)> array of data it wants or 35*b077aed3SPierre Proncheryis expected to pass back, and pass that as I<params>, as well as the opaque 36*b077aed3SPierre Proncherydata pointer it received, as I<arg>. 37*b077aed3SPierre Pronchery 38*b077aed3SPierre Pronchery=item B<OSSL_PASSPHRASE_CALLBACK> 39*b077aed3SPierre Pronchery 40*b077aed3SPierre ProncheryThis is a specialised callback function, used specifically to prompt the 41*b077aed3SPierre Proncheryuser for a passphrase. When calling this callback function, a buffer to 42*b077aed3SPierre Proncherystore the pass phrase needs to be given with I<pass>, and its size with 43*b077aed3SPierre ProncheryI<pass_size>. The length of the prompted pass phrase will be given back in 44*b077aed3SPierre ProncheryI<*pass_len>. 45*b077aed3SPierre Pronchery 46*b077aed3SPierre ProncheryAdditional parameters can be passed with the L<OSSL_PARAM(3)> array I<params>, 47*b077aed3SPierre Pronchery 48*b077aed3SPierre Pronchery=back 49*b077aed3SPierre Pronchery 50*b077aed3SPierre Pronchery=begin comment RETURN VALUES doesn't make sense for a manual that only 51*b077aed3SPierre Proncherydescribes a type, but document checkers still want that section, and 52*b077aed3SPierre Proncheryto have more than just the section title. 53*b077aed3SPierre Pronchery 54*b077aed3SPierre Pronchery=head1 RETURN VALUES 55*b077aed3SPierre Pronchery 56*b077aed3SPierre Proncherytxt 57*b077aed3SPierre Pronchery 58*b077aed3SPierre Pronchery=end comment 59*b077aed3SPierre Pronchery 60*b077aed3SPierre Pronchery=head1 SEE ALSO 61*b077aed3SPierre Pronchery 62*b077aed3SPierre ProncheryL<openssl-core.h(7)> 63*b077aed3SPierre Pronchery 64*b077aed3SPierre Pronchery=head1 HISTORY 65*b077aed3SPierre Pronchery 66*b077aed3SPierre ProncheryThe types described here were added in OpenSSL 3.0. 67*b077aed3SPierre Pronchery 68*b077aed3SPierre Pronchery=head1 COPYRIGHT 69*b077aed3SPierre Pronchery 70*b077aed3SPierre ProncheryCopyright 2022 The OpenSSL Project Authors. All Rights Reserved. 71*b077aed3SPierre Pronchery 72*b077aed3SPierre ProncheryLicensed under the Apache License 2.0 (the "License"). You may not use 73*b077aed3SPierre Proncherythis file except in compliance with the License. You can obtain a copy 74*b077aed3SPierre Proncheryin the file LICENSE in the source distribution or at 75*b077aed3SPierre ProncheryL<https://www.openssl.org/source/license.html>. 76*b077aed3SPierre Pronchery 77*b077aed3SPierre Pronchery=cut 78