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