|
@@ -0,0 +1,117 @@
|
|
|
+=pod
|
|
|
+
|
|
|
+=head1 NAME
|
|
|
+
|
|
|
+openssl_ctx_new_index, openssl_ctx_free_index,
|
|
|
+openssl_ctx_new_fn, openssl_ctx_free_fn,
|
|
|
+openssl_ctx_set_data, openssl_ctx_get_data - internal OPENSSL_CTX routines
|
|
|
+
|
|
|
+=head1 SYNOPSIS
|
|
|
+
|
|
|
+ #include <openssl/ossl_typ.h>
|
|
|
+ #include "internal/cryptlib.h"
|
|
|
+
|
|
|
+ typedef CRYPTO_EX_new openssl_ctx_new_fn;
|
|
|
+ typedef CRYPTO_EX_free openssl_ctx_free_fn;
|
|
|
+
|
|
|
+ typedef struct openssl_ctx_method {
|
|
|
+ void *(*new_func)(void);
|
|
|
+ void (*free_func)(void *);
|
|
|
+ } OPENSSL_CTX_METHOD;
|
|
|
+
|
|
|
+ int openssl_ctx_new_index(const OPENSSL_CTX_METHOD *meth);
|
|
|
+ void *openssl_ctx_get_data(OPENSSL_CTX *ctx, int index);
|
|
|
+
|
|
|
+=head1 DESCRIPTION
|
|
|
+
|
|
|
+Internally, the OpenSSL library context C<OPENSSL_CTX> is implemented
|
|
|
+as a C<CRYPTO_EX_DATA>, which allows data from diverse parts of the
|
|
|
+library to be added and removed dynamically.
|
|
|
+Each such data item must have a corresponding CRYPTO_EX_DATA index
|
|
|
+associated with it.
|
|
|
+See the example further down to see how that's done.
|
|
|
+
|
|
|
+openssl_ctx_new_index() allocates a new library context index, and
|
|
|
+associates it with the functions given through C<meth>.
|
|
|
+The functions given through that method are used to create or free
|
|
|
+items that are stored at that index whenever a library context is
|
|
|
+created or freed, meaning that the code that use a data item of that
|
|
|
+index doesn't have to worry about that, just use the data available.
|
|
|
+
|
|
|
+Deallocation of an index happens automatically when the library
|
|
|
+context is freed.
|
|
|
+
|
|
|
+openssl_ctx_get_data() is used to retrieve a pointer to the data in
|
|
|
+the library context C<ctx> associated with the given C<index>.
|
|
|
+
|
|
|
+=head1 EXAMPLES
|
|
|
+
|
|
|
+=head2 Initialization
|
|
|
+
|
|
|
+For a type C<FOO> that should end up in the OpenSSL library context, a
|
|
|
+small bit of initialization is needed, i.e. to associate a constructor
|
|
|
+and a destructor to a new index.
|
|
|
+
|
|
|
+ /* The index will always be entirely global, and dynamically allocated */
|
|
|
+ static int foo_index = -1;
|
|
|
+
|
|
|
+ typedef struct foo_st {
|
|
|
+ int i;
|
|
|
+ void *data;
|
|
|
+ } FOO;
|
|
|
+
|
|
|
+ static void *foo_new(void)
|
|
|
+ {
|
|
|
+ FOO *ptr = OPENSSL_zalloc(sizeof(*foo));
|
|
|
+ if (ptr != NULL)
|
|
|
+ ptr->i = 42;
|
|
|
+ return ptr;
|
|
|
+ }
|
|
|
+ static void foo_free(void *ptr)
|
|
|
+ {
|
|
|
+ OPENSSL_free(ptr);
|
|
|
+ }
|
|
|
+ static const OPENSSL_CTX_METHOD foo_method = {
|
|
|
+ foo_new,
|
|
|
+ foo_free
|
|
|
+ };
|
|
|
+
|
|
|
+ static int foo_init(void)
|
|
|
+ {
|
|
|
+ foo_index = openssl_ctx_new_index(foo_method);
|
|
|
+
|
|
|
+ return foo_index != -1;
|
|
|
+ }
|
|
|
+
|
|
|
+=head2 Usage
|
|
|
+
|
|
|
+To get and use the data stored in the library context, simply do this:
|
|
|
+
|
|
|
+ /*
|
|
|
+ * ctx is received from a caller,
|
|
|
+ * foo_index comes from the example above
|
|
|
+ */
|
|
|
+ FOO *data = openssl_ctx_get_data(ctx, foo_index);
|
|
|
+
|
|
|
+=head1 RETURN VALUES
|
|
|
+
|
|
|
+openssl_ctx_new_index() returns -1 on error, otherwise the allocated
|
|
|
+index number.
|
|
|
+
|
|
|
+openssl_ctx_get_data() returns a pointer on success, or C<NULL> on
|
|
|
+failure.
|
|
|
+
|
|
|
+=head1 SEE ALSO
|
|
|
+
|
|
|
+L<OPENSSL_CTX(3)>
|
|
|
+
|
|
|
+=head1 COPYRIGHT
|
|
|
+
|
|
|
+Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
|
|
|
+
|
|
|
+Licensed under the Apache License 2.0 (the "License"). You may not use
|
|
|
+this file except in compliance with the License. You can obtain a copy
|
|
|
+in the file LICENSE in the source distribution or at
|
|
|
+L<https://www.openssl.org/source/license.html>.
|
|
|
+
|
|
|
+=cut
|