---Overview---

MorphOS shared OpenSSL library with 64-bit time_t

NOTES

        This library is not related to AmiSSL, nor is it ABI compatible
        with it.

HISTORY

        4.0    OpenSSL 4.0.0, included with MorphOS 3.20

DESCRIPTION

        openssl4.library provides the OpenSSL library functionality as a
        system-wide, shared library. Using the library reduces the size of
        the application binary and reduces the run-time memory footprint.
        Addidionally, the shared library can be easily upgraded to
        incorporate security and functionality fixes.

        The library differs from typical shared library in that it doesn't
        provide a traditional LVO function entries. Instead the library
        functions are called via function stubs provided at linking time.
        libcrypto_shared.a and libssl_shared.a contain these stub functions
        and constructor / destructor to open and close the shared library as
        needed. In normal applications there is no need to manually open
        the library or adjust the code in any way.

        This library is only intended for libnix, that is for code compiled
        with -noixemul.

   SUB-PROCESSES / THREADING

        Sub-processes of the same application should not open the library
        separately. The main process must keep the library open for as long
        as the sub-processes are using the library base. All types of
        threads (CreateNewProc(), GCC threads, libpthread, OBThread erc) are
        supported.

        Opening the library again in a sub-process would lead to undesired
        behaviour: the subproces would then get a new application context
        and would not share configuration with the parent process.

FILEHANDLES

        Passing standard I/O file streams (FILE *) works as expected. You can
        use BIO_set_fp(), BIO_get_fp() and BIO_new_fp() or any other function
        that accepts FILE *, just like with any other platform. BIO_s_fd is
        also fully functional.

        If dos.library BPTR file handles need to be used, this can be done
        via BIO_meth_new function. For details refer to:
        https://www.openssl.org/docs/manmaster/man3/BIO_meth_new.html

FUTURE

        The library API/ABI will remain stable. If new functions are added,
        or their ABI changes, new functions will be added to the library and
        the library version is bumped. If existing functions are removed they
        will be changed to either implement a compatible functionality, or
        if infeasible, return an error.

        If at some point in the future upstream openssl library introduces
        sweeping API/ABI changes, a new library with a different name will
        be provided.

        In case a library with a new name is introduced, the old versions
        of the library will still be provided as well. This ensures that
        existing applications will continue to function.

SOCKETS

        The library opens bsdsocket.library internally and uses it when
        needed. The application may of course open bsdsocket.library itself
        too, if needed, and pass sockets descriptors to library functions as
        needed.

SPECIAL USE CASES

        1. Using openssl4.library without a startup code

        Using openssl4.library without the standard startup code is possible.
        Declare 'struct Library *OpenSSL4Base;' and open and close the
        library as needed. Note that each library open gives you a unique
        library base. This base refers to single application context, so you
        likely only should open the library once at startup and close it
        before application termination.

        2. Using openssl4.library in a shared library/device/class

        Using openssl4.library in such case is possible, but requires care.
        Here are some considerations:
         - You *MUST NOT* open the library from your LIB_Init and close it
           at LIB_expunge. This will not work correctly.
         - Opening / closing the library in your LIB_Open / LIB_Close will
           likely not work well. It's highly recommended to use a worker
           process instead.
         - You must CloseLibrary the library base you get from OpenLibrary.
           Opening the library multiple times gives a new base each time
           so your code must be careful to maintain the returned library
           base in re-entrant manner. The safest bet is to use a worker
           process that opens the library once and closes it when
           terminating. This worker can launch new child processes that use
           the same library base.
         - If your code must be fully re-entrant and cannot use a single
           global OpenSSL4Base, you can link the code against -lssl_sharedext
           -lcrypto_sharedext *and* provide a _fetch_OpenSSL4Base function
           that returns the relevant library base. This code be implemented
           for example as:

           struct Library *_fetch_OpenSSL4Base(void)
           {
               ABOX_DEFTASKSYSBASE;

               /* Just an example; do whatever is needed to get the base */
               struct Library *OpenSSL4Base = FindTask(NULL)->tc_UserData;

               return OpenSSL4Base;
           }

         - Depending on your implementation it might not be sensible to
           load the global configuration. If you do not wish to load it,
           use: OPENSSL_init_crypto(OPENSSL_INIT_NO_LOAD_CONFIG, NULL) and
           OPENSSL_init_ssl(OPENSSL_INIT_NO_LOAD_CONFIG, NULL).

USING

        Compile your code normally, using the SDK provided openssl headers.
        For linking specify: -lssl_shared -lcrypto_shared