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