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