@ECHO OFF REM Command file for Sphinx documentation if "%SPHINXBUILD%" == "" ( set SPHINXBUILD=sphinx-build ) set BUILDDIR=_build set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% . set I18NSPHINXOPTS=%SPHINXOPTS% . if NOT "%PAPER%" == "" ( set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS% ) if "%1" == "" goto help if "%1" == "help" ( :help echo.Please use `make ^` where ^ is one of echo. html to make standalone HTML files echo. dirhtml to make HTML files named index.html in directories echo. singlehtml to make a single large HTML file echo. pickle to make pickle files echo. json to make JSON files echo. htmlhelp to make HTML files and a HTML help project echo. qthelp to make HTML files and a qthelp project echo. devhelp to make HTML files and a Devhelp project echo. epub to make an epub echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter echo. text to make text files echo. man to make manual pages echo. texinfo to make Texinfo files echo. gettext to make PO message catalogs echo. changes to make an overview over all changed/added/deprecated items echo. linkcheck to check all external links for integrity echo. doctest to run all doctests embedded in the documentation if enabled goto end ) if "%1" == "clean" ( for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i del /q /s %BUILDDIR%\* goto end ) if "%1" == "html" ( %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html if errorlevel 1 exit /b 1 echo. echo.Build finished. The HTML pages are in %BUILDDIR%/html. goto end ) if "%1" == "dirhtml" ( %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml if errorlevel 1 exit /b 1 echo. echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. goto end ) if "%1" == "singlehtml" ( %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml if errorlevel 1 exit /b 1 echo. echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. goto end ) if "%1" == "pickle" ( %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle if errorlevel 1 exit /b 1 echo. echo.Build finished; now you can process the pickle files. goto end ) if "%1" == "json" ( %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json if errorlevel 1 exit /b 1 echo. echo.Build finished; now you can process the JSON files. goto end ) if "%1" == "htmlhelp" ( %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp if errorlevel 1 exit /b 1 echo. echo.Build finished; now you can run HTML Help Workshop with the ^ .hhp project file in %BUILDDIR%/htmlhelp. goto end ) if "%1" == "qthelp" ( %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp if errorlevel 1 exit /b 1 echo. echo.Build finished; now you can run "qcollectiongenerator" with the ^ .qhcp project file in %BUILDDIR%/qthelp, like this: echo.^> qcollectiongenerator %BUILDDIR%\qthelp\Cryptography.qhcp echo.To view the help file: echo.^> assistant -collectionFile %BUILDDIR%\qthelp\Cryptography.ghc goto end ) if "%1" == "devhelp" ( %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp if errorlevel 1 exit /b 1 echo. echo.Build finished. goto end ) if "%1" == "epub" ( %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub if errorlevel 1 exit /b 1 echo. echo.Build finished. The epub file is in %BUILDDIR%/epub. goto end ) if "%1" == "latex" ( %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex if errorlevel 1 exit /b 1 echo. echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. goto end ) if "%1" == "text" ( %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text if errorlevel 1 exit /b 1 echo. echo.Build finished. The text files are in %BUILDDIR%/text. goto end ) if "%1" == "man" ( %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man if errorlevel 1 exit /b 1 echo. echo.Build finished. The manual pages are in %BUILDDIR%/man. goto end ) if "%1" == "texinfo" ( %SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo if errorlevel 1 exit /b 1 echo. echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo. goto end ) if "%1" == "gettext" ( %SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale if errorlevel 1 exit /b 1 echo. echo.Build finished. The message catalogs are in %BUILDDIR%/locale. goto end ) if "%1" == "changes" ( %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes if errorlevel 1 exit /b 1 echo. echo.The overview file is in %BUILDDIR%/changes. goto end ) if "%1" == "linkcheck" ( %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck if errorlevel 1 exit /b 1 echo. echo.Link check complete; look for any errors in the above output ^ or in %BUILDDIR%/linkcheck/output.txt. goto end ) if "%1" == "doctest" ( %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest if errorlevel 1 exit /b 1 echo. echo.Testing of doctests in the sources finished, look at the ^ results in %BUILDDIR%/doctest/output.txt. goto end ) :end href='#n54'>54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 
C bindings
==========

C bindings are bindings to C libraries, using cffi_ whenever possible.

.. _cffi: https://cffi.readthedocs.io

Bindings live in :py:mod:`cryptography.hazmat.bindings`.

When modifying the bindings you will need to recompile the C extensions to
test the changes. This can be accomplished with ``pip install -e .`` in the
project root. If you do not do this a ``RuntimeError`` will be raised.

Style guide
-----------

Don't name parameters:

.. code-block:: c

    /* Good */
    long f(long);
    /* Bad */
    long f(long x);

...unless they're inside a struct:

.. code-block:: c

    struct my_struct {
        char *name;
        int number;
        ...;
    };

Include ``void`` if the function takes no arguments:

.. code-block:: c

    /* Good */
    long f(void);
    /* Bad */
    long f();

Wrap lines at 80 characters like so:

.. code-block:: c

    /* Pretend this went to 80 characters */
    long f(long, long,
           int *)

Include a space after commas between parameters:

.. code-block:: c

    /* Good */
    long f(int, char *)
    /* Bad */
    long f(int,char *)

Use C-style ``/* */`` comments instead of C++-style ``//``:

.. code-block:: c

    // Bad
    /* Good */

Values set by ``#define`` should be assigned the appropriate type. If you see
this:

.. code-block:: c

    #define SOME_INTEGER_LITERAL 0x0;
    #define SOME_UNSIGNED_INTEGER_LITERAL 0x0001U;
    #define SOME_STRING_LITERAL "hello";

...it should be added to the bindings like so:

.. code-block:: c

    static const int SOME_INTEGER_LITERAL;
    static const unsigned int SOME_UNSIGNED_INTEGER_LITERAL;
    static const char *const SOME_STRING_LITERAL;

Adding constant, types, functions...
------------------------------------

You can create bindings for any name that exists in some version of
the library you're binding against. However, the project also has to
keep supporting older versions of the library. In order to achieve this,
binding modules have a ``CUSTOMIZATIONS`` constant, and there is a
``CONDITIONAL_NAMES`` constants in
``src/cryptography/hazmat/bindings/openssl/_conditional.py``.

Let's say you want to enable quantum transmogrification. The upstream
library implements this as the following API::

    static const int QM_TRANSMOGRIFICATION_ALIGNMENT_LEFT;
    static const int QM_TRANSMOGRIFICATION_ALIGNMENT_RIGHT;
    typedef ... QM_TRANSMOGRIFICATION_CTX;
    int QM_transmogrify(QM_TRANSMOGRIFICATION_CTX *, int);

To start, create a new constant that defines if the *actual* library
has the feature you want, and add it to ``TYPES``::

    static const long Cryptography_HAS_QUANTUM_TRANSMOGRIFICATION;

This should start with ``Cryptography_``, since we're adding it in
this library. This prevents namespace collisions.

Then, define the actual features (constants, types, functions...) you
want to expose. If it's a constant, just add it to ``TYPES``::

    static const int QM_TRANSMOGRIFICATION_ALIGNMENT_LEFT;
    static const int QM_TRANSMOGRIFICATION_ALIGNMENT_RIGHT;

If it's a struct, add it to ``TYPES`` as well. The following is an
opaque struct::

    typedef ... QM_TRANSMOGRIFICATION_CTX;

... but you can also make some or all items in the struct accessible::

    typedef struct {
        /* Fundamental constant k for your particular universe */
        BIGNUM *k;
        ...;
    } QM_TRANSMOGRIFICATION_CTX;

For functions just add the signature to ``FUNCTIONS``::

    int QM_transmogrify(QM_TRANSMOGRIFICATION_CTX *, int);

Then, we define the ``CUSTOMIZATIONS`` entry. To do that, we have to
come up with a C preprocessor expression that decides whether or not a
feature exists in the library. For example::

    #ifdef QM_transmogrify

Then, we set the flag that signifies the feature exists::

    static const long Cryptography_HAS_QUANTUM_TRANSMOGRIFICATION = 1;

Otherwise, we set that flag to 0::

    #else
    static const long Cryptography_HAS_QUANTUM_TRANSMOGRIFICATION = 0;

Then, in that ``#else`` block, we define the names that aren't
available as dummy values. For an integer constant, use 0::

    static const int QM_TRANSMOGRIFICATION_ALIGNMENT_LEFT = 0;
    static const int QM_TRANSMOGRIFICATION_ALIGNMENT_RIGHT = 0;

For a function, it's a bit trickier. You have to define a function
pointer of the appropriate type to be NULL::

    int (*QM_transmogrify)(QM_TRANSMOGRIFICATION_CTX *, int) = NULL;

(To do that, copy the signature, put a ``*`` in front of the function
name and wrap it in parentheses, and then put ``= NULL`` at the end).

Note how types don't need to be conditionally defined, as long as all
the necessarily type definitions are in place.

Finally, add an entry to ``CONDITIONAL_NAMES`` with all of the things
you want to conditionally export::

    def cryptography_has_quantum_transmogrification():
        return [
            "QM_TRANSMOGRIFICATION_ALIGNMENT_LEFT",
            "QM_TRANSMOGRIFICATION_ALIGNMENT_RIGHT",
            "QM_transmogrify",
        ]


    CONDITIONAL_NAMES = {
        ...
        "Cryptography_HAS_QUANTUM_TRANSMOGRIFICATION": (
            cryptography_has_quantum_transmogrification
        ),
    }


Caveats
~~~~~~~

Sometimes, a set of loosely related features are added in the same
version, and it's impractical to create ``#ifdef`` statements for each
one. In that case, it may make sense to either check for a particular
version. For example, to check for OpenSSL 1.1.0 or newer::

    #if OPENSSL_VERSION_NUMBER >= 0x10100000L

Sometimes, the version of a library on a particular platform will have
features that you thought it wouldn't, based on its version.
Occasionally, packagers appear to ship arbitrary VCS checkouts. As a
result, sometimes you may have to add separate ``#ifdef`` statements
for particular features. This kind of issue is typically only caught
by running the tests on a wide variety of systems, which is the job of
our continuous integration infrastructure.
generated by cgit v1.2.3 (git 2.25.1) at 2025-05-24 04:19:52 +0000