Skip to content

Latest commit

 

History

History
112 lines (81 loc) · 2.87 KB

openssl_ctx_get_data.pod

File metadata and controls

112 lines (81 loc) · 2.87 KB
Raw

NAME

openssl_ctx_new_index, openssl_ctx_get_data - internal OPENSSL_CTX routines

SYNOPSIS

#include <openssl/ossl_typ.h>
#include "internal/cryptlib.h"

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);

DESCRIPTION

Internally, the OpenSSL library context OPENSSL_CTX is implemented as a 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 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 ctx associated with the given index.

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 NULL on failure.

EXAMPLES

Initialization

For a type 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;
}

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);

SEE ALSO

OPENSSL_CTX(3)

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 https://www.openssl.org/source/license.html.