doc/internal/man3/openssl_ctx_get_data.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 openssl_ctx_new_index, openssl_ctx_get_data - internal OPENSSL_CTX routines
   6
   7 =head1 SYNOPSIS
   8
   9  #include <openssl/ossl_typ.h>
  10  #include "internal/cryptlib.h"
  11
  12  typedef struct openssl_ctx_method {
  13      void *(*new_func)(void);
  14      void (*free_func)(void *);
  15  } OPENSSL_CTX_METHOD;
  16
  17  int openssl_ctx_new_index(const OPENSSL_CTX_METHOD *meth);
  18  void *openssl_ctx_get_data(OPENSSL_CTX *ctx, int index);
  19
  20 =head1 DESCRIPTION
  21
  22 Internally, the OpenSSL library context C<OPENSSL_CTX> is implemented
  23 as a C<CRYPTO_EX_DATA>, which allows data from diverse parts of the
  24 library to be added and removed dynamically.
  25 Each such data item must have a corresponding CRYPTO_EX_DATA index
  26 associated with it.
  27 See the example further down to see how that's done.
  28
  29 openssl_ctx_new_index() allocates a new library context index, and
  30 associates it with the functions given through C<meth>.
  31 The functions given through that method are used to create or free
  32 items that are stored at that index whenever a library context is
  33 created or freed, meaning that the code that use a data item of that
  34 index doesn't have to worry about that, just use the data available.
  35
  36 Deallocation of an index happens automatically when the library
  37 context is freed.
  38
  39 openssl_ctx_get_data() is used to retrieve a pointer to the data in
  40 the library context C<ctx> associated with the given C<index>.
  41
  42 =head1 RETURN VALUES
  43
  44 openssl_ctx_new_index() returns -1 on error, otherwise the allocated
  45 index number.
  46
  47 openssl_ctx_get_data() returns a pointer on success, or C<NULL> on
  48 failure.
  49
  50 =head1 EXAMPLES
  51
  52 =head2 Initialization
  53
  54 For a type C<FOO> that should end up in the OpenSSL library context, a
  55 small bit of initialization is needed, i.e. to associate a constructor
  56 and a destructor to a new index.
  57
  58  /* The index will always be entirely global, and dynamically allocated */
  59  static int foo_index = -1;
  60
  61  typedef struct foo_st {
  62      int i;
  63      void *data;
  64  } FOO;
  65
  66  static void *foo_new(void)
  67  {
  68      FOO *ptr = OPENSSL_zalloc(sizeof(*foo));
  69      if (ptr != NULL)
  70          ptr->i = 42;
  71      return ptr;
  72  }
  73  static void foo_free(void *ptr)
  74  {
  75      OPENSSL_free(ptr);
  76  }
  77  static const OPENSSL_CTX_METHOD foo_method = {
  78      foo_new,
  79      foo_free
  80  };
  81
  82  static int foo_init(void)
  83  {
  84      foo_index = openssl_ctx_new_index(foo_method);
  85
  86      return foo_index != -1;
  87  }
  88
  89 =head2 Usage
  90
  91 To get and use the data stored in the library context, simply do this:
  92
  93  /*
  94   * ctx is received from a caller,
  95   * foo_index comes from the example above
  96   */
  97  FOO *data = openssl_ctx_get_data(ctx, foo_index);
  98
  99 =head1 SEE ALSO
 100
 101 L<OPENSSL_CTX(3)>
 102
 103 =head1 COPYRIGHT
 104
 105 Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
 106
 107 Licensed under the Apache License 2.0 (the "License").  You may not use
 108 this file except in compliance with the License.  You can obtain a copy
 109 in the file LICENSE in the source distribution or at
 110 L<https://www.openssl.org/source/license.html>.
 111
 112 =cut