THUAI6/CAPI/cpp/grpc/include/openssl/core.h

/*
 * Copyright 2019-2021 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
 */

#ifndef OPENSSL_CORE_H
#define OPENSSL_CORE_H
#pragma once

#include <stddef.h>
#include <openssl/types.h>

#ifdef __cplusplus
extern "C"
{
#endif

    /*-
     * Base types
     * ----------
     *
     * These are the types that the OpenSSL core and providers have in common
     * to communicate data between them.
     */

    /* Opaque handles to be used with core upcall functions from providers */
    typedef struct ossl_core_handle_st OSSL_CORE_HANDLE;
    typedef struct openssl_core_ctx_st OPENSSL_CORE_CTX;
    typedef struct ossl_core_bio_st OSSL_CORE_BIO;

    /*
     * Dispatch table element.  function_id numbers and the functions are defined
     * in core_dispatch.h, see macros with 'OSSL_CORE_MAKE_FUNC' in their names.
     *
     * An array of these is always terminated by function_id == 0
     */
    struct ossl_dispatch_st
    {
        int function_id;
        void (*function)(void);
    };

    /*
     * Other items, essentially an int<->pointer map element.
     *
     * We make this type distinct from OSSL_DISPATCH to ensure that dispatch
     * tables remain tables with function pointers only.
     *
     * This is used whenever we need to pass things like a table of error reason
     * codes <-> reason string maps, ...
     *
     * Usage determines which field works as key if any, rather than field order.
     *
     * An array of these is always terminated by id == 0 && ptr == NULL
     */
    struct ossl_item_st
    {
        unsigned int id;
        void* ptr;
    };

    /*
     * Type to tie together algorithm names, property definition string and
     * the algorithm implementation in the form of a dispatch table.
     *
     * An array of these is always terminated by algorithm_names == NULL
     */
    struct ossl_algorithm_st
    {
        const char* algorithm_names;     /* key */
        const char* property_definition; /* key */
        const OSSL_DISPATCH* implementation;
        const char* algorithm_description;
    };

    /*
     * Type to pass object data in a uniform way, without exposing the object
     * structure.
     *
     * An array of these is always terminated by key == NULL
     */
    struct ossl_param_st
    {
        const char* key;        /* the name of the parameter */
        unsigned int data_type; /* declare what kind of content is in buffer */
        void* data;             /* value being passed in or out */
        size_t data_size;       /* data size */
        size_t return_size;     /* returned content size */
    };

/* Currently supported OSSL_PARAM data types */
/*
 * OSSL_PARAM_INTEGER and OSSL_PARAM_UNSIGNED_INTEGER
 * are arbitrary length and therefore require an arbitrarily sized buffer,
 * since they may be used to pass numbers larger than what is natively
 * available.
 *
 * The number must be buffered in native form, i.e. MSB first on B_ENDIAN
 * systems and LSB first on L_ENDIAN systems.  This means that arbitrary
 * native integers can be stored in the buffer, just make sure that the
 * buffer size is correct and the buffer itself is properly aligned (for
 * example by having the buffer field point at a C integer).
 */
#define OSSL_PARAM_INTEGER 1
#define OSSL_PARAM_UNSIGNED_INTEGER 2
/*-
 * OSSL_PARAM_REAL
 * is a C binary floating point values in native form and alignment.
 */
#define OSSL_PARAM_REAL 3
/*-
 * OSSL_PARAM_UTF8_STRING
 * is a printable string.  It is expected to be printed as it is.
 */
#define OSSL_PARAM_UTF8_STRING 4
/*-
 * OSSL_PARAM_OCTET_STRING
 * is a string of bytes with no further specification.  It is expected to be
 * printed as a hexdump.
 */
#define OSSL_PARAM_OCTET_STRING 5
/*-
 * OSSL_PARAM_UTF8_PTR
 * is a pointer to a printable string.  It is expected to be printed as it is.
 *
 * The difference between this and OSSL_PARAM_UTF8_STRING is that only pointers
 * are manipulated for this type.
 *
 * This is more relevant for parameter requests, where the responding
 * function doesn't need to copy the data to the provided buffer, but
 * sets the provided buffer to point at the actual data instead.
 *
 * WARNING!  Using these is FRAGILE, as it assumes that the actual
 * data and its location are constant.
 *
 * EXTRA WARNING!  If you are not completely sure you most likely want
 * to use the OSSL_PARAM_UTF8_STRING type.
 */
#define OSSL_PARAM_UTF8_PTR 6
/*-
 * OSSL_PARAM_OCTET_PTR
 * is a pointer to a string of bytes with no further specification.  It is
 * expected to be printed as a hexdump.
 *
 * The difference between this and OSSL_PARAM_OCTET_STRING is that only pointers
 * are manipulated for this type.
 *
 * This is more relevant for parameter requests, where the responding
 * function doesn't need to copy the data to the provided buffer, but
 * sets the provided buffer to point at the actual data instead.
 *
 * WARNING!  Using these is FRAGILE, as it assumes that the actual
 * data and its location are constant.
 *
 * EXTRA WARNING!  If you are not completely sure you most likely want
 * to use the OSSL_PARAM_OCTET_STRING type.
 */
#define OSSL_PARAM_OCTET_PTR 7

    /*
     * Typedef for the thread stop handling callback. Used both internally and by
     * providers.
     *
     * Providers may register for notifications about threads stopping by
     * registering a callback to hear about such events. Providers register the
     * callback using the OSSL_FUNC_CORE_THREAD_START function in the |in| dispatch
     * table passed to OSSL_provider_init(). The arg passed back to a provider will
     * be the provider side context object.
     */
    typedef void (*OSSL_thread_stop_handler_fn)(void* arg);

    /*-
     * Provider entry point
     * --------------------
     *
     * This function is expected to be present in any dynamically loadable
     * provider module.  By definition, if this function doesn't exist in a
     * module, that module is not an OpenSSL provider module.
     */
    /*-
     * |handle|     pointer to opaque type OSSL_CORE_HANDLE.  This can be used
     *              together with some functions passed via |in| to query data.
     * |in|         is the array of functions that the Core passes to the provider.
     * |out|        will be the array of base functions that the provider passes
     *              back to the Core.
     * |provctx|    a provider side context object, optionally created if the
     *              provider needs it.  This value is passed to other provider
     *              functions, notably other context constructors.
     */
    typedef int(OSSL_provider_init_fn)(const OSSL_CORE_HANDLE* handle, const OSSL_DISPATCH* in, const OSSL_DISPATCH** out, void** provctx);
#ifdef __VMS
#pragma names save
#pragma names uppercase, truncated
#endif
    OPENSSL_EXPORT OSSL_provider_init_fn OSSL_provider_init;
#ifdef __VMS
#pragma names restore
#endif

    /*
     * Generic callback function signature.
     *
     * The expectation is that any provider function that wants to offer
     * a callback / hook can do so by taking an argument with this type,
     * as well as a pointer to caller-specific data.  When calling the
     * callback, the provider function can populate an OSSL_PARAM array
     * with data of its choice and pass that in the callback call, along
     * with the caller data argument.
     *
     * libcrypto may use the OSSL_PARAM array to create arguments for an
     * application callback it knows about.
     */
    typedef int(OSSL_CALLBACK)(const OSSL_PARAM params[], void* arg);
    typedef int(OSSL_INOUT_CALLBACK)(const OSSL_PARAM in_params[], OSSL_PARAM out_params[], void* arg);
    /*
     * Passphrase callback function signature
     *
     * This is similar to the generic callback function above, but adds a
     * result parameter.
     */
    typedef int(OSSL_PASSPHRASE_CALLBACK)(char* pass, size_t pass_size, size_t* pass_len, const OSSL_PARAM params[], void* arg);

#ifdef __cplusplus
}
#endif

#endif