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 The OpenSSL libraries use the first of the algorithm names as the main
  64 or canonical name, on a per algorithm implementation basis.
  65
  66 =item B<OSSL_PARAM>
  67
  68 This type is a structure that allows passing arbitrary object data
  69 between two parties that have no or very little shared knowledge about
  70 their respective internal structures for that object.
  71 It's normally passed in arrays, where the array is terminated with an
  72 element where all fields are zero (for non-pointers) or NULL (for
  73 pointers).
  74
  75 These arrays can be used to set parameters for some object, to request
  76 parameters, and to describe parameters.
  77
  78 B<OSSL_PARAM> is further described in L<OSSL_PARAM(3)>
  79
  80 =item B<OSSL_CALLBACK>
  81
  82 This is a function type for a generic feedback callback function:
  83
  84     typedef int (OSSL_CALLBACK)(const OSSL_PARAM params[], void *arg);
  85
  86 A function that takes a pointer of this type should also take a
  87 pointer to caller data.  When calling this callback, the function is
  88 expected to build an B<OSSL_PARAM> array of data it wants or is
  89 expected to pass back, and pass that as I<params>, as well as
  90 the caller data pointer it received, as I<arg>.
  91
  92 =item B<OSSL_PASSPHRASE_CALLBACK>
  93
  94 This is a function type for a generic pass phrase callback function:
  95
  96     typedef int (OSSL_PASSPHRASE_CALLBACK)(char *pass, size_t pass_size,
  97                                            size_t *pass_len,
  98                                            const OSSL_PARAM params[],
  99                                            void *arg);
 100
 101 This callback can be used to prompt the user for a passphrase.  When
 102 calling it, a buffer to store the pass phrase needs to be given with
 103 I<pass>, and its size with I<pass_size>.  The length of the prompted
 104 pass phrase will be given back in I<*pass_len>.
 105
 106 Additional parameters can be passed with the B<OSSL_PARAM> array
 107 I<params>.
 108
 109 A function that takes a pointer of this type should also take a
 110 pointer to caller data, which should be passed as I<arg> to this
 111 callback.
 112
 113 =back
 114
 115 =head1 SEE ALSO
 116
 117 L<openssl-core_dispatch.h(7)>
 118
 119 =head1 HISTORY
 120
 121 The types described here were added in OpenSSL 3.0.
 122
 123 =head1 COPYRIGHT
 124
 125 Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved.
 126
 127 Licensed under the Apache License 2.0 (the "License").  You may not use
 128 this file except in compliance with the License.  You can obtain a copy
 129 in the file LICENSE in the source distribution or at
 130 L<https://www.openssl.org/source/license.html>.
 131
 132 =cut