Commit d64b6299 authored by Richard Levitte's avatar Richard Levitte
Browse files

Add an OpenSSL library context 



The context builds on CRYPTO_EX_DATA, allowing it to be dynamically
extended with new data from the different parts of libcrypto.

Reviewed-by: default avatarMatt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/8225)
parent e17f5b6a

crypto/build.info

+1 −1
Original line number Diff line number Diff line
@@ -12,7 +12,7 @@ SOURCE[../libcrypto]=\ 
        cryptlib.c mem.c mem_dbg.c cversion.c ex_data.c cpt_err.c \

        ebcdic.c uid.c o_time.c o_str.c o_dir.c o_fopen.c ctype.c \

        threads_pthread.c threads_win.c threads_none.c getenv.c \

        o_init.c o_fips.c mem_sec.c init.c sparse_array.c \

        o_init.c o_fips.c mem_sec.c init.c context.c sparse_array.c \

        {- $target{cpuid_asm_src} -} {- $target{uplink_aux_src} -}



DEPEND[cversion.o]=buildinf.h

crypto/context.c

0 → 100644
+110 −0
Original line number Diff line number Diff line 
/*

 * 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

 * https://www.openssl.org/source/license.html

 */



#include "internal/cryptlib.h"

#include "internal/thread_once.h"



struct openssl_ctx_st {

    CRYPTO_RWLOCK *lock;

    CRYPTO_EX_DATA data;

};



static OPENSSL_CTX default_context;



static int context_init(OPENSSL_CTX *ctx)

{

    return (ctx->lock = CRYPTO_THREAD_lock_new()) != NULL

        && CRYPTO_new_ex_data(CRYPTO_EX_INDEX_OPENSSL_CTX, NULL,

                              &ctx->data);

}



static int context_deinit(OPENSSL_CTX *ctx)

{

    CRYPTO_free_ex_data(CRYPTO_EX_INDEX_OPENSSL_CTX, NULL, &ctx->data);

    CRYPTO_THREAD_lock_free(ctx->lock);

    return 1;

}



static CRYPTO_ONCE default_context_init = CRYPTO_ONCE_STATIC_INIT;

static void do_default_context_deinit(void)

{

    context_deinit(&default_context);

}

DEFINE_RUN_ONCE_STATIC(do_default_context_init)

{

    return OPENSSL_init_crypto(0, NULL)

        && context_init(&default_context)

        && OPENSSL_atexit(do_default_context_deinit);

}



OPENSSL_CTX *OPENSSL_CTX_new(void)

{

    OPENSSL_CTX *ctx = OPENSSL_zalloc(sizeof(*ctx));



    if (ctx != NULL && !context_init(ctx)) {

        OPENSSL_CTX_free(ctx);

        ctx = NULL;

    }

    return ctx;

}



void OPENSSL_CTX_free(OPENSSL_CTX *ctx)

{

    if (ctx != NULL)

        context_deinit(ctx);

    OPENSSL_free(ctx);

}



static void openssl_ctx_generic_new(void *parent_ign, void *ptr_ign,

                                    CRYPTO_EX_DATA *ad, int index,

                                    long argl_ign, void *argp)

{

    const OPENSSL_CTX_METHOD *meth = argp;

    void *ptr = meth->new_func();



    if (ptr != NULL)

        CRYPTO_set_ex_data(ad, index, ptr);

}

static void openssl_ctx_generic_free(void *parent_ign, void *ptr,

                                     CRYPTO_EX_DATA *ad, int index,

                                     long argl_ign, void *argp)

{

    const OPENSSL_CTX_METHOD *meth = argp;



    meth->free_func(ptr);

}

int openssl_ctx_new_index(const OPENSSL_CTX_METHOD *meth)

{

    return CRYPTO_get_ex_new_index(CRYPTO_EX_INDEX_OPENSSL_CTX, 0, (void *)meth,

                                   openssl_ctx_generic_new, NULL,

                                   openssl_ctx_generic_free);

}



void *openssl_ctx_get_data(OPENSSL_CTX *ctx, int index)

{

    void *data = NULL;



    if (ctx == NULL) {

        if (!RUN_ONCE(&default_context_init, do_default_context_init))

            return 0;

        ctx = &default_context;

    }



    CRYPTO_THREAD_read_lock(ctx->lock);



    /* The alloc call ensures there's a value there */

    if (CRYPTO_alloc_ex_data(CRYPTO_EX_INDEX_OPENSSL_CTX, NULL,

                             &ctx->data, index))

        data = CRYPTO_get_ex_data(&ctx->data, index);



    CRYPTO_THREAD_unlock(ctx->lock);



    return data;

}

doc/internal/man3/openssl_ctx_get_data.pod

0 → 100644
+117 −0
Original line number Diff line number Diff line 
=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

doc/man3/OPENSSL_CTX.pod

0 → 100644
+48 −0
Original line number Diff line number Diff line 
=pod



=head1 NAME



OPENSSL_CTX, OPENSSL_CTX_new, OPENSSL_CTX_free - OpenSSL library context



=head1 SYNOPSIS



 #include <openssl/crypto.h>



 typedef struct openssl_ctx_st OPENSSL_CTX;



 OPENSSL_CTX *OPENSSL_CTX_new(void);

 void OPENSSL_CTX_free(OPENSSL_CTX *ctx);



=head1 DESCRIPTION



C<OPENSSL_CTX> is an internal OpenSSL library context type.

Applications may allocate their own, but may also use C<NULL> to use

the internal default context with functions that take a C<OPENSSL_CTX>

argument.



OPENSSL_CTX_new() creates a new OpenSSL library context.



OPENSSL_CTX_free() frees the given C<ctx>.



=head1 RETURN VALUES



OPENSSL_CTX_new() return a library context pointer on success, or

C<NULL> on error.



OPENSSL_CTX_free() doesn't return any value.



=head1 HISTORY



OPENSSL_CTX, OPENSSL_CTX_new() and OPENSSL_CTX_free()

were added in OpenSSL 3.0.0.



=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

include/internal/cryptlib.h

+9 −0
Original line number Diff line number Diff line
@@ -95,4 +95,13 @@ uint32_t OPENSSL_rdtsc(void); 
size_t OPENSSL_instrument_bus(unsigned int *, size_t);

size_t OPENSSL_instrument_bus2(unsigned int *, size_t, size_t);



typedef struct openssl_ctx_method {

    void *(*new_func)(void);

    void (*free_func)(void *);

} OPENSSL_CTX_METHOD;

/* For each type of data to store in the context, an index must be created */

int openssl_ctx_new_index(const OPENSSL_CTX_METHOD *);

/* Functions to retrieve pointers to data by index */

void *openssl_ctx_get_data(OPENSSL_CTX *, int /* index */);



#endif