diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index 1e392a1..0000000 --- a/docs/Makefile +++ /dev/null @@ -1,34 +0,0 @@ -# Copyright 2024 Ant Group Co., Ltd. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -# Minimal makefile for Sphinx documentation -# - -# You can set these variables from the command line, and also -# from the environment for the first two. -SPHINXOPTS ?= -SPHINXBUILD ?= sphinx-build -SOURCEDIR = . -BUILDDIR = _build - -# Put it first so that "make" without argument is like "make help". -help: - @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -.PHONY: help Makefile - -# Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css deleted file mode 100644 index be5205c..0000000 --- a/docs/_static/css/custom.css +++ /dev/null @@ -1,26 +0,0 @@ -/** - * Copyright 2024 Ant Group Co., Ltd - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -html[data-theme="light"] { - --pst-color-primary: rgb(22 119 255); - --pst-color-secondary: rgb(22 255 201); -} - -html[data-theme="dark"] { - --pst-color-primary: rgb(22 119 255); - --pst-color-secondary: rgb(22 255 201); - --pst-color-background: rgb(56, 56, 56); -} diff --git a/docs/_static/favicon.ico b/docs/_static/favicon.ico deleted file mode 100644 index 58c2592..0000000 Binary files a/docs/_static/favicon.ico and /dev/null differ diff --git a/docs/_static/logo-dark.png b/docs/_static/logo-dark.png deleted file mode 100644 index e77d487..0000000 Binary files a/docs/_static/logo-dark.png and /dev/null differ diff --git a/docs/_static/logo.png b/docs/_static/logo.png deleted file mode 100644 index 2117fe6..0000000 Binary files a/docs/_static/logo.png and /dev/null differ diff --git a/docs/conf.py b/docs/conf.py deleted file mode 100644 index 2754bdc..0000000 --- a/docs/conf.py +++ /dev/null @@ -1,118 +0,0 @@ -# Copyright 2024 Ant Group Co., Ltd. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -# Configuration file for the Sphinx documentation builder. -# -# This file only contains a selection of the most common options. For a full -# list see the documentation: -# https://www.sphinx-doc.org/en/master/usage/configuration.html - -# -- Path setup -------------------------------------------------------------- - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -# -import os -import sys - -# -- Project information ----------------------------------------------------- - -project = 'YACL' -copyright = '2022-2024 Ant Group Co., Ltd' -author = 'YACL authors' - -# The full version, including alpha/beta/rc tags -# release = '0.0.6' - -# -- Multi-language config --------------------------------------------------- - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -# -# This is also used if you do content translation via gettext catalogs. -# Usually you set "language" from the command line for these cases. -language = 'zh_CN' - -locale_dirs = ['locale/'] -gettext_compact = False # optional. -gettext_uuid = False # optional. -# gettext_location = False - -# -- General configuration --------------------------------------------------- - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. -extensions = [ - 'sphinx.ext.autodoc', - 'sphinx.ext.viewcode', - 'sphinx.ext.intersphinx', - 'sphinx.ext.mathjax', - 'sphinx.ext.napoleon', - "sphinx_inline_tabs", - "sphinx_togglebutton", - "myst_parser", -] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This pattern also affects html_static_path and html_extra_path. -exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] - -# -- Options for HTML output ------------------------------------------------- - -html_favicon = '_static/favicon.ico' - -html_css_files = [ - 'css/custom.css', -] - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# -html_theme = "pydata_sphinx_theme" - -html_context = {"default_mode": "light"} - -html_sidebars = {"index": [], "**": ["search-field", "sidebar-nav-bs"]} - -html_theme_options = { - "logo": { - "text": "YACL", - }, - "pygments_light_style": "tango", - "pygments_dark_style": "native", - "icon_links": [ - { - "name": "GitHub", - "url": "https://github.com/secretflow/yacl", - "icon": "fa-brands fa-github", - "type": "fontawesome", - }, - ], - # https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/layout.html - # the default "navbar-logo" section is redundant and has bugs, so remove it. - # "navbar_start": [], - "secondary_sidebar_items": ["page-toc"], - # "language_switch_button": True, -} - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] diff --git a/docs/imgs/ecdh_psi_1.png b/docs/imgs/ecdh_psi_1.png deleted file mode 100644 index 4e399c8..0000000 Binary files a/docs/imgs/ecdh_psi_1.png and /dev/null differ diff --git a/docs/imgs/ecdh_psi_2.png b/docs/imgs/ecdh_psi_2.png deleted file mode 100644 index 3e40610..0000000 Binary files a/docs/imgs/ecdh_psi_2.png and /dev/null differ diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index a1d99dc..0000000 --- a/docs/index.rst +++ /dev/null @@ -1,29 +0,0 @@ -YACL Documentation -=============================== - -YACL (Yet Another Common Cryptography Library) is a sub-project of `SecretFlow `_, it is a C++ library that provides cryptography, network and io modules for other SecretFlow repositories. Yacl is designed to be a **low-level** library that could be either integrated into a big **secure system**, or used in a standalone way for a **quick POC** (see: `Develop `_), or even help with your **security/cryptography research** (see: `Research `_). - -- **About Cryptography Modules:** The crypto modules in Yacl implement many state-of-art secure computation protocols, including primitives like OT, VOLE, TPRE, and tools like PRG, RO. Check the full list of Yacl's `supported algorithms list `_. -- **About Network ("link") Modules:** The network ("link") module in Yacl uses `BRPC `_ to handle network. And we also provide a "mocked" in-memory link. -- **About IO Modules:** Yacl also provides many io modules for kv storage, file io, `bristol circuits `_, and so on. - -The following parts describes the top-level folders of Yacl repository. - -- `yacl/base/ `_: some basic types and utils in yacl. -- `yacl/crypto/ `_: crypto algorithm without link. -- `yacl/kernel/ `_: crypto kernel that includes link with (WIP) multi-thread support, i.e. OT, DPF. -- `yacl/io/ `_: a simple streaming-based io library. -- `yacl/link/ `_: a simple rpc-based MPI framework, providing the `SPMD `_ parallel programming capability. - -.. toctree:: - :maxdepth: 2 - :caption: Contents - :numbered: 1 - :titlesonly: - - src/getting_started - src/develop/index - src/research/index - src/security - src/algorithms - src/changelog diff --git a/docs/requirements.txt b/docs/requirements.txt deleted file mode 100644 index 284bc1e..0000000 --- a/docs/requirements.txt +++ /dev/null @@ -1,14 +0,0 @@ -sphinx -sphinx-intl -sphinx-copybutton -sphinx-togglebutton -sphinx-inline-tabs -sphinxcontrib-htmlhelp -sphinxcontrib-applehelp - -# HACK see: https://github.com/CrossNox/m2r2/issues/68#issuecomment-2145795360 -docutils>=0.18.1,<0.21 -myst-parser==4.0.0 - -# theme -pydata-sphinx-theme diff --git a/docs/src/algorithms.rst b/docs/src/algorithms.rst deleted file mode 100644 index 0e45632..0000000 --- a/docs/src/algorithms.rst +++ /dev/null @@ -1,2 +0,0 @@ -.. include:: ../../ALGORITHMS.md - :parser: myst_parser.sphinx_ diff --git a/docs/src/changelog.rst b/docs/src/changelog.rst deleted file mode 100644 index 9f448a2..0000000 --- a/docs/src/changelog.rst +++ /dev/null @@ -1,2 +0,0 @@ -.. include:: ../../CHANGELOG.md - :parser: myst_parser.sphinx_ diff --git a/docs/src/develop/example_psi.rst b/docs/src/develop/example_psi.rst deleted file mode 100644 index b225271..0000000 --- a/docs/src/develop/example_psi.rst +++ /dev/null @@ -1,96 +0,0 @@ -Example: Build a PSI Protocol -============================= - -This is an example of how to use Yacl's ECC api and link to build up a `PSI (Private Set Intersection) `_ protocol. The code of this example is avaliable at `link `_. - -.. warning:: - This example is merely designed for demonstration only, please do not use this example in production. - -Step 1: Understand ECDH-PSI -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Before we start, the ECDH-PSI protocols are formally designed as the following, where lambda indicates the computational security parameter, and H() indicates a cryptographically secure (collision-free) hash function. - -.. image:: ../../imgs/ecdh_psi_1.png - :width: 300 - :alt: Alternative text - -.. image:: ../../imgs/ecdh_psi_2.png - :width: 300 - :alt: Alternative text - -Step 2: Implement Protocol -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -We provide the implementation in the following codes. Note that it's almost always a good idea to separate the definitions and implementations into ``*.h`` and ``*.cc`` files. - -.. literalinclude:: ../../../examples/psi/cpp/ecdh_psi.h - :language: cpp - -.. literalinclude:: ../../../examples/psi/cpp/ecdh_psi.cc - :language: cpp - -Besides the two files, you also need to write a `BUILD.bazel` file to tell `bazel` how to compile your files together. - -.. code:: - - load("//bazel:yacl.bzl", "yacl_cc_binary", "yacl_cc_library", "yacl_cc_test") - - package(default_visibility = ["//visibility:public"]) - - yacl_cc_library( - name = "ecdh_psi", - srcs = [ - "ecdh_psi.cc", - ], - hdrs = [ - "ecdh_psi.h", - ], - deps = [ - "//yacl/crypto/ecc", - "//yacl/link", - ], - ) - - yacl_cc_test( - name = "ecdh_psi_test", - srcs = ["ecdh_psi_test.cc"], - deps = [":ecdh_psi"], - ) - -Step 2: Write and Run Tests -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Also, we recommend all users to write unit tests for implementations. In oder to run the following tests, you can ``bazel test //examples/psi/ecdh_psi_test``. - -.. literalinclude:: ../../../examples/psi/cpp/ecdh_psi_test.cc - :language: cpp - -Step 3: Generate Executables and Run with CSV files -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Also, alternatively you can build an executable for two users to actually run the PSI protocols with their private data. We show an example ``main.cc`` file in the below. - -.. literalinclude:: ../../../examples/psi/cpp/ecdh_psi_main.cc - :language: cpp - -In order to compile, run ``bazel build //examples/psi/ecdh_psi_main -c opt``. The ``-c opt`` flag tells the bazel build system to build a release (or, optimized) version of the executable. - -To run the exeutable, open two terminals in the same machine. - -.. note:: - - Please make sure your machine's 10086 and 10087 ports are avaliable. - -In the first terminal, at yacl's project root, run - -.. code:: bash - - ./bazel-bin/examples/psi/ecdh_psi_main --rank=0 - - -Then in the second terminal, at yacl's project root, run - -.. code:: bash - - ./bazel-bin/examples/psi/ecdh_psi_main --rank=1 diff --git a/docs/src/develop/example_psi_java.rst b/docs/src/develop/example_psi_java.rst deleted file mode 100644 index c076d8e..0000000 --- a/docs/src/develop/example_psi_java.rst +++ /dev/null @@ -1,22 +0,0 @@ -Example: Bind PSI to Java -========================= - -This is an example of how to use Yacl's ECC api and link to build up a `PSI (Private Set Intersection) `_ protocol, and provide a java language binding using JNI. The code of this example is avaliable on `Github `_. - -.. warning:: - This example is merely designed for demonstration only, please do not use this example in production. - -Step 1: Implement -^^^^^^^^^^^^^^^^^ - -.. literalinclude:: ../../../examples/psi/java/ecdh_psi_jni.cc - :language: cpp - -.. literalinclude:: ../../../examples/psi/java/EcdhPsi.java - :language: java - -Step 2: Build and Test -^^^^^^^^^^^^^^^^^^^^^^ - -.. literalinclude:: ../../../examples/psi/java/EcdhPsiTest.java - :language: java diff --git a/docs/src/develop/example_psi_python.rst b/docs/src/develop/example_psi_python.rst deleted file mode 100644 index 38da0df..0000000 --- a/docs/src/develop/example_psi_python.rst +++ /dev/null @@ -1,25 +0,0 @@ -Example: Bind PSI to Python -=========================== - -This is an example of how to use Yacl's ECC api and link to build up a `PSI (Private Set Intersection) `_ protocol, and provide a python language binding using `pybind11 `_. The code of this example is avaliable on `Github `_. - -.. warning:: - This example is merely designed for demonstration only, please do not use this example in production. - -Step 1: Implement -^^^^^^^^^^^^^^^^^ - -.. literalinclude:: ../../../examples/psi/python/ecdh_psi_pybind.h - :language: cpp - -.. literalinclude:: ../../../examples/psi/python/ecdh_psi_pybind.cc - :language: cpp - -.. literalinclude:: ../../../examples/psi/python/ecdh_psi.py - :language: python - -Step 2: Build and Test -^^^^^^^^^^^^^^^^^^^^^^ - -.. literalinclude:: ../../../examples/psi/python/ecdh_psi_test.py - :language: python diff --git a/docs/src/develop/index.rst b/docs/src/develop/index.rst deleted file mode 100644 index 89341ce..0000000 --- a/docs/src/develop/index.rst +++ /dev/null @@ -1,62 +0,0 @@ -Develop -======= - -**For Traditioanl PKI:** Since there are so many existing time-proof, efficient, and standardized implementation of PKI algorithms, Yacl **does not re-implement** those algorithms. Instead, Yacl only provides a light-weighted and "easy-to-use" wrapper for the most popular industrial libraries (e.g. `OpenSSL `_, `TongSuo `_, `LibSodium `_, etc.) - -**For ECC (Elliptic-Curve Cryptography):** Yacl integrates many curve implementation from OpenSSL, you may use the code in the following to use any curve as you like. For more information about all supported curve names, see: `yacl/crypto/ecc/curve_meta.cc `_ - -.. code-block:: cpp - - #include "yacl/crypto/ecc/ecc_spi.h" - - auto ec = yacl::crypto::EcGroupFactory::Instance().Create( - /*** curve name */ "FourQ"); - - auto order = ec->GetOrder(); - auto g = ec->GetGenerator(); - auto p = ec->GetField(); - - // You can also: - // ec->Add(/* first point */, /* second point */); - // ec->Mul(/* first point */, /* second scalar */); - // ... for more see: yacl/crypto/ecc/ecc_spi.h - -**For Randomness** Yacl has also provide some easy-to-use randomness generation functions. Random functions usually start with **Secure** or **Fast**, secure random implementation uses the standardized ctr-drbg, and fast uses hash-drbg. It is always recommended to use **Secure**-Random functions. - -.. code-block:: cpp - - #include "yacl/crypto/rand/rand.h" - - auto rand_u64 = yacl::crypto::SecureRandU64(); - auto rand_u128 = yacl::crypto::SecureRandU128(); - - std::vector rand_bytes = yacl::crypto::SecureRandBytes(10); - - // ... for more see: yacl/crypto/rand/rand.h - -**For Secure Computation Protocols:** Yacl provides many secure computation primitives, such as OT, VOLE and so on. It is recommended to use the `yacl/kernel/...` api for general usage. For more advanced users, please use `yacl/algorithms/...`. - -.. code-block:: cpp - - #include "yacl/kernel/ot_kernel.h" - - // ... setup link as lctx ..., at sender side - OtSendStore ot_send(num_ot, OtStoreType::Compact); // placeholder - OtKernel kernel_send(OtKernel::Role::Sender, OtKernel::ExtAlgorithm::Ferret); - kernel_send.init(lctx); // base ot - kernel_send.eval_cot_random_choice(lctx, /* number of ot */, &ot_send); - - // ... setup link as lctx ..., at receiver side - OtRecvStore ot_recv(num_ot, OtStoreType::Compact); // placeholder - OtKernel kernel_recv(OtKernel::Role::Receiver, OtKernel::ExtAlgorithm::Ferret); - kernel_recv.init(lctx); // base ot - kernel_recv.eval_cot_random_choice(lctx, /* number of ot */, &ot_recv); - -**ECDH-PSI Example:** We also provide a step-to-step demo to demonstrate how to build an ECDH-PSI protocol from the tools that Yacl provides, and then bind the protocol implementation to JAVA and Python. See the following link for more detail. - -.. toctree:: - :maxdepth: 1 - - example_psi - example_psi_java - example_psi_python diff --git a/docs/src/getting_started.rst b/docs/src/getting_started.rst deleted file mode 100644 index be138a8..0000000 --- a/docs/src/getting_started.rst +++ /dev/null @@ -1,2 +0,0 @@ -.. include:: ../../GETTING_STARTED.md - :parser: myst_parser.sphinx_ diff --git a/docs/src/research/index.rst b/docs/src/research/index.rst deleted file mode 100644 index 100023d..0000000 --- a/docs/src/research/index.rst +++ /dev/null @@ -1,51 +0,0 @@ -Research -======== - -Yacl is also designed for cryptography researchers. We notice that junior (or early-career) cryptography researchers have been constantly finding it difficult to demonstrate their new ideas, or run emperical benchmarks. - -Desite the **ECC, Random, and Secure Computation** introduced in `Develop Section <../develop/index.html>`_. Yacl has provided the following tools for cryptographic researchers. - -.. note:: - - Yacl has dedicated to long-term support for cryptography research, please do not hesitation to contact us for security issues, bugs, pull requests, or requiring new features . - -**yacl/math:** Yacl provides ``MPInt`` type for big number operations. - -.. code-block:: cpp - - #include "yacl/math/mpint/mp_int.h" - - auto kOne = 1_mp; // same as MPInt(1); - auto kTwo = 2_mp; // same as MPInt(2); - auto kZero = 0_mp; // same as MPInt(0); - - MPInt::Add( ... ); - MPInt::AddMod( ... ); - MPInt::Mul( ... ); - MPInt::MulMod( ... ); - - MPInt::RandPrimeOver( ... ); - MPInt::RandomLtN( ... ) - - // ... for more see: yacl/math/mpint/mp_int.h - -**yacl/crypto/tools:** Yacl also provides some theoretical tools such as Random Oralce, Random Permutation, etc. - -.. code-block:: cpp - - #include "yacl/crypto/tools/ro.h" - #include "yacl/crypto/tools/rp.h" - #include "yacl/crypto/tools/prg.h" - - const auto& RO = RandomOracle::GetDefault(); - auto out = RO.Gen(SecureRandBytes(param)); - - const auto& RP = RP::GetDefault(); - auto out = RP.Gen(SecureRandU128()); - - Prg prg(SecureRandSeed()); - auto out = prg(); - - // ... for more see: yacl/crypto/tools - -**yacl/crypto/experimental:** Yacl puts experimental cryptography algorithms here. diff --git a/docs/src/security.rst b/docs/src/security.rst deleted file mode 100644 index 18aeb18..0000000 --- a/docs/src/security.rst +++ /dev/null @@ -1,2 +0,0 @@ -.. include:: ../../SECURITY.md - :parser: myst_parser.sphinx_ diff --git a/renovate.json b/renovate.json index add6bd2..1c5f8fa 100644 --- a/renovate.json +++ b/renovate.json @@ -9,8 +9,5 @@ ], "ignoreDeps": [ "bazel" - ], - "reviewers": [ - "team:yacl-dev" ] }