doc/internal/man3/ossl_lib_ctx_get_data.pod

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