openssl_ctx_get_data.pod 4.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142
  1. =pod
  2. =head1 NAME
  3. openssl_ctx_get_data, openssl_ctx_run_once, openssl_ctx_onfree
  4. - internal OPENSSL_CTX routines
  5. =head1 SYNOPSIS
  6. #include <openssl/types.h>
  7. #include "internal/cryptlib.h"
  8. typedef struct openssl_ctx_method {
  9. void *(*new_func)(OPENSSL_CTX *ctx);
  10. void (*free_func)(void *);
  11. } OPENSSL_CTX_METHOD;
  12. void *openssl_ctx_get_data(OPENSSL_CTX *ctx, int index,
  13. const OPENSSL_CTX_METHOD *meth);
  14. int openssl_ctx_run_once(OPENSSL_CTX *ctx, unsigned int idx,
  15. openssl_ctx_run_once_fn run_once_fn);
  16. int openssl_ctx_onfree(OPENSSL_CTX *ctx, openssl_ctx_onfree_fn onfreefn);
  17. =head1 DESCRIPTION
  18. Internally, the OpenSSL library context B<OPENSSL_CTX> is implemented
  19. as a B<CRYPTO_EX_DATA>, which allows data from diverse parts of the
  20. library to be added and removed dynamically.
  21. Each such data item must have a corresponding CRYPTO_EX_DATA index
  22. associated with it. Unlike normal CRYPTO_EX_DATA objects we use static indexes
  23. to identify data items. These are mapped transparently to CRYPTO_EX_DATA dynamic
  24. indexes internally to the implementation.
  25. See the example further down to see how that's done.
  26. openssl_ctx_get_data() is used to retrieve a pointer to the data in
  27. the library context I<ctx> associated with the given I<index>. An
  28. OPENSSL_CTX_METHOD must be defined and given in the I<meth> parameter. The index
  29. for it should be defined in cryptlib.h. The functions through the method are
  30. used to create or free items that are stored at that index whenever a library
  31. context is created or freed, meaning that the code that use a data item of that
  32. index doesn't have to worry about that, just use the data available.
  33. Deallocation of an index happens automatically when the library
  34. context is freed.
  35. openssl_ctx_run_once is used to run some initialisation routine I<run_once_fn>
  36. exactly once per library context I<ctx> object. Each initialisation routine
  37. should be allocate a unique run once index in cryptlib.h.
  38. Any resources allocated via a run once initialisation routine can be cleaned up
  39. using openssl_ctx_onfree. This associates an "on free" routine I<onfreefn> with
  40. the library context I<ctx>. When I<ctx> is freed all associated "on free"
  41. routines are called.
  42. =head1 RETURN VALUES
  43. openssl_ctx_get_data() returns a pointer on success, or NULL on
  44. failure.
  45. =head1 EXAMPLES
  46. =head2 Initialization
  47. For a type C<FOO> that should end up in the OpenSSL library context, a
  48. small bit of initialization is needed, i.e. to associate a constructor
  49. and a destructor to an index.
  50. typedef struct foo_st {
  51. int i;
  52. void *data;
  53. } FOO;
  54. static void *foo_new(OPENSSL_CTX *ctx)
  55. {
  56. FOO *ptr = OPENSSL_zalloc(sizeof(*foo));
  57. if (ptr != NULL)
  58. ptr->i = 42;
  59. return ptr;
  60. }
  61. static void foo_free(void *ptr)
  62. {
  63. OPENSSL_free(ptr);
  64. }
  65. /*
  66. * Include a reference to this in the methods table in context.c
  67. * OPENSSL_CTX_FOO_INDEX should be added to internal/cryptlib.h
  68. */
  69. const OPENSSL_CTX_METHOD foo_method = {
  70. foo_new,
  71. foo_free
  72. };
  73. =head2 Usage
  74. To get and use the data stored in the library context, simply do this:
  75. /*
  76. * ctx is received from a caller,
  77. */
  78. FOO *data = openssl_ctx_get_data(ctx, OPENSSL_CTX_FOO_INDEX, &foo_method);
  79. =head2 Run Once
  80. void foo_cleanup(OPENSSL_CTX *ctx)
  81. {
  82. /* Free foo resources associated with ctx */
  83. }
  84. static openssl_ctx_run_once_fn do_foo_init;
  85. static int do_foo_init(OPENSSL_CTX *ctx)
  86. {
  87. /* Allocate and initialise some foo resources and associated with ctx */
  88. return openssl_ctx_onfree(ctx, &foo_cleanup)
  89. }
  90. int foo_some_function(OPENSSL_CTX *ctx)
  91. {
  92. if (!openssl_ctx_run_once(ctx,
  93. OPENSSL_CTX_FOO_RUN_ONCE_INDEX,
  94. do_foo_init))
  95. return 0;
  96. /* Do some work using foo resources in ctx */
  97. }
  98. =head1 SEE ALSO
  99. L<OPENSSL_CTX(3)>
  100. =head1 COPYRIGHT
  101. Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
  102. Licensed under the Apache License 2.0 (the "License"). You may not use
  103. this file except in compliance with the License. You can obtain a copy
  104. in the file LICENSE in the source distribution or at
  105. L<https://www.openssl.org/source/license.html>.
  106. =cut