doc/man7/openssl-core.h.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 openssl/core.h - OpenSSL Core types
   6
   7 =head1 SYNOPSIS
   8
   9  #include <openssl/core.h>
  10
  11 =head1 DESCRIPTION
  12
  13 The F<< <openssl/core.h> >> header defines a number of public types that
  14 are used to communicate between the OpenSSL libraries and
  15 implementation providers.
  16 These types are designed to minimise the need for intimate knowledge
  17 of internal structures between the OpenSSL libraries and the providers.
  18
  19 The types are:
  20
  21 =over 4
  22
  23 =item B<OSSL_DISPATCH>
  24
  25 This type is a tuple of function identity and function pointer.
  26 Arrays of this type are passed between the OpenSSL libraries and the
  27 providers to describe what functionality one side provides to the
  28 other.
  29 Arrays of this type must be terminated with a tuple having function
  30 identity zero and function pointer NULL.
  31
  32 The available function identities and corresponding function
  33 signatures are defined in L<openssl-core_dispatch.h(7)>.
  34
  35 Any function identity not recognised by the recipient of this type
  36 will be ignored.
  37 This ensures that providers built with one OpenSSL version in mind
  38 will work together with any other OpenSSL version that supports this
  39 mechanism.
  40
  41 =item B<OSSL_ITEM>
  42
  43 This type is a tuple of integer and pointer.
  44 It's a generic type used as a generic descriptor, its exact meaning
  45 being defined by how it's used.
  46 Arrays of this type are passed between the OpenSSL libraries and the
  47 providers, and must be terminated with a tuple where the integer is
  48 zero and the pointer NULL.
  49
  50 =item B<OSSL_ALGORITHM>
  51
  52 This type is a tuple of an algorithm name (string), a property
  53 definition (string) and a dispatch table (array of B<OSSL_DISPATCH>).
  54 Arrays of this type are passed on demand from the providers to the
  55 OpenSSL libraries to describe what algorithms the providers provide
  56 implementations of, and with what properties.
  57 Arrays of this type must be terminated with a tuple having function
  58 identity zero and function pointer NULL.
  59
  60 The algorithm names and property definitions are defined by the
  61 providers.
  62
  63 =item B<OSSL_PARAM>
  64
  65 This type is a structure that allows passing arbitrary object data
  66 between two parties that have no or very little shared knowledge about
  67 their respective internal structures for that object.
  68 It's normally passed in arrays, where the array is terminated with an
  69 element where all fields are zero (for non-pointers) or NULL (for
  70 pointers).
  71
  72 These arrays can be used to set parameters for some object, to request
  73 parameters, and to describe parameters.
  74
  75 B<OSSL_PARAM> is further described in L<OSSL_PARAM(3)>
  76
  77 =item B<OSSL_CALLBACK>
  78
  79 This is a function type for a generic feedback callback function:
  80
  81     typedef int (OSSL_CALLBACK)(const OSSL_PARAM params[], void *arg);
  82
  83 A function that takes a pointer of this type should also take a
  84 pointer to caller data.  When calling this callback, the function is
  85 expected to build an B<OSSL_PARAM> array of data it wants or is
  86 expected to pass back, and pass that as I<params>, as well as
  87 the caller data pointer it received, as I<arg>.
  88
  89 =item B<OSSL_PASSPHRASE_CALLBACK>
  90
  91 This is a function type for a generic pass phrase callback function:
  92
  93     typedef int (OSSL_PASSPHRASE_CALLBACK)(char *pass, size_t pass_size,
  94                                            size_t *pass_len,
  95                                            const OSSL_PARAM params[],
  96                                            void *arg);
  97
  98 This callback can be used to prompt the user for a passphrase.  When
  99 calling it, a buffer to store the pass phrase needs to be given with
 100 I<pass>, and its size with I<pass_size>.  The length of the prompted
 101 pass phrase will be given back in I<*pass_len>.
 102
 103 Additional parameters can be passed with the B<OSSL_PARAM> array
 104 I<params>.
 105
 106 A function that takes a pointer of this type should also take a
 107 pointer to caller data, which should be passed as I<arg> to this
 108 callback.
 109
 110 =back
 111
 112 =head1 SEE ALSO
 113
 114 L<openssl-core_dispatch.h(7)>
 115
 116 =head1 HISTORY
 117
 118 The types described here were added in OpenSSL 3.0.
 119
 120 =head1 COPYRIGHT
 121
 122 Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved.
 123
 124 Licensed under the Apache License 2.0 (the "License").  You may not use
 125 this file except in compliance with the License.  You can obtain a copy
 126 in the file LICENSE in the source distribution or at
 127 L<https://www.openssl.org/source/license.html>.
 128
 129 =cut