openssl-core.h.pod 4.2 KB

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