{"id":13568840,"url":"https://github.com/equalitie/ouinet","last_synced_at":"2025-04-05T03:06:03.683Z","repository":{"id":27620606,"uuid":"104485565","full_name":"equalitie/ouinet","owner":"equalitie","description":"This is a read-only mirror of: https://gitlab.com/equalitie/ouinet/","archived":false,"fork":false,"pushed_at":"2025-02-06T20:12:35.000Z","size":6510,"stargazers_count":126,"open_issues_count":13,"forks_count":13,"subscribers_count":19,"default_branch":"main","last_synced_at":"2025-03-29T02:03:51.298Z","etag":null,"topics":["bittorrent-dht","cplusplus","decentralized-web","i2p","i2p-network"],"latest_commit_sha":null,"homepage":"https://ouinet.work","language":"C++","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/equalitie.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-09-22T14:45:45.000Z","updated_at":"2025-01-29T05:07:16.000Z","dependencies_parsed_at":"2024-01-15T22:00:55.631Z","dependency_job_id":"86567b94-c767-4fbd-a470-a9629b07441f","html_url":"https://github.com/equalitie/ouinet","commit_stats":null,"previous_names":[],"tags_count":142,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/equalitie%2Fouinet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/equalitie%2Fouinet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/equalitie%2Fouinet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/equalitie%2Fouinet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/equalitie","download_url":"https://codeload.github.com/equalitie/ouinet/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247280262,"owners_count":20912967,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bittorrent-dht","cplusplus","decentralized-web","i2p","i2p-network"],"created_at":"2024-08-01T14:00:32.437Z","updated_at":"2025-04-05T03:06:03.642Z","avatar_url":"https://github.com/equalitie.png","language":"C++","funding_links":[],"categories":["C++"],"sub_categories":[],"readme":"\u003cimg src=\"https://ouinet.work/img/ouinet-logo.png\" width=250px alt=\"Ouinet\"\u003e\n\n[![pipeline status](https://gitlab.com/equalitie/ouinet/badges/main/pipeline.svg)](https://gitlab.com/equalitie/ouinet/commits/main)\n[![release](https://gitlab.com/equalitie/ouinet/-/badges/release.svg)](https://gitlab.com/equalitie/ouinet/-/releases)\n[![License: MIT](https://img.shields.io/badge/License-MIT-brightgreen.svg)](./LICENSE)\n\nOuinet is a collection of open source software libraries that create a\ndecentralized network of cooperating peers for sharing and propagating web\ncontent. A Ouinet deployment requires supporting infrastructure - run by a\ntrusted network operator - and the integration of its client libraries into\nthird-party applications for requesting and receiving desired content.\nOuinet clients collectively form a distributed cache that is global in nature,\nbut also functional on a local or national network. Peer-to-peer transports\nare used for communications.\n\nOuinet's primary integration and its initial _raison d'etre_ is to power the\n[Ceno Browser](https://censorship.no) - utilized for accessing web content\nbehind national firewalls. Supporting infrastructure on this project is\nprovided by [eQualitie](https://equalit.ie), offering injection and\nauthentication of web content into a decentralized p2p network, using the\nBitTorrent DHT for addressing and routing. Coupled with sneakernet technology\noperated by eQualitie, Ceno users can access\n[cached website replicas](https://schedule.ceno.life) from heavily limited\nor entirely isolated network environments.\n\n\n## How does it work?\n\nA typical [client][] node setup consists of a web browser or other application\nusing the special HTTP proxy provided by Ouinet. When the Ouinet proxy gets a\nrequest for content, it attempts to retrieve the resource using several\nmechanisms. For example, it could try to fetch a page from the [distributed cache][]\nby looking up the content in the BitTorrent DHT and if the content is not\navailable, it could also contact a trusted [injector][] server over a\npeer-to-peer routing system (like the [BitTorrent DHT][] or [I2P][]) and ask to\nfetch the page and store it in the distributed cache.\n\nSee our [lightning talk at the Decentralized Web Summit 2018][] for an\noverview of Ouinet's architecture or check the [documentation website][].\n\nFor a detailed technical explanation of processes and protocols you can refer\nto [Ouinet's white paper][].\n\n[lightning talk at the Decentralized Web Summit 2018]: http://archive.org/details/dweb-8_2_18_Lightning_Talks_New_Discoveries_5?start=547\n[documentation website]: https://ouinet.work/docs/how/index.html\n[Ouinet's white paper]: doc/ouinet-network-whitepaper.md\n[BitTorrent DHT]: http://bittorrent.org/beps/bep_0005.html\n[I2P]: https://geti2p.net/ \"Invisible Internet Project\"\n[client]: https://ouinet.work/docs/how/client.html\n[injector]: https://ouinet.work/docs/how/injectors.html\n[distributed cache]: https://ouinet.work/docs/how/cache.html\n\n![Ouinet request/response flow](./doc/diagrams/simple-request-flow.svg)\n\n**Warning:** Ouinet is **not an anonymity tool**, information about your\nbrowsing can be seen by other participants in the network, as well as the\nfact that your application is seeding particular content.\n\n\n## Request mechanisms\n\nThe following mechanisms to retrieve content are attempted as parallel coroutines\nshowing the results of the first responding method.\n\n- *Origin*: The client contacts the origin server directly via HTTP(S).\n- *Proxy*: The client contacts the origin server through an HTTPS proxy\n  (any available injector) and retrieves the content without\n  signing it.\n- *Injector*: The client asks the injector to fetch and sign the content\n  from the origin server, then it starts seeding the signed content to\n  the distributed cache.\n- *Distributed Cache*: The client attempts to retrieve the content from\n  the distributed cache.\n\n\n## Bridge nodes\n\nWhen a client establishes a connection to an injector and verifies that the\nconnection is genuine, it may then choose to function as an intermediary,\nallowing less fortunate clients to reach the injector through them. A client\nfunctioning as an intermediary in this way is referred to as a bridge node.\n\nIf a client chooses to function as a bridge node, it will accept connections\nusing the [uTP protocol](http://www.bittorrent.org/beps/bep_0029.html), and\nannounce its address details to the BitTorrent distributed hash table. Whenever\nthe client accepts a connection in this way, it will create a connection to an\ninjector and forward all traffic received over the incoming connection to the\nconnection with the injector, and vice versa. This lets the client function as\nan intermediary between an injector and a different client that is unable to\nconnect to the injectors directly.\n\nA detailed explanation of Bridges can be found in Ouinet's\n[docs](https://ouinet.work/docs/how/injectors.html?highlight=peer#peer-to-peer-tunnels).\n\n\n## Software artifacts included in this repo\n\n* *Client*: Command line application that serves as a proxy to the Ouinet\nnetwork.\n* *Injector*: Command line application that retrieves content from origin\nwebsites and injects the signed content to the Ouinet network so it can be\nshared peer-to-peer.\n* *Android libraries*: Java Native Interface used to expose the C++ Ouinet\nnetworking libraries to the Android applications written in Java or Kotlin.\n\n\n## Building from source\n\nThe following instructions were tested in Debian 12 with the following\npackages installed; `build-essential`, `cmake`, `git`, `libssl-dev` and\n`zlib1g-dev`, but in general to build Ouinet natively on your GNU/Linux\nsystem you just need *CMake 3.5+* and *g++* capable of C++14.\n\nOuinet uses Git submodules, thus to properly clone it, use:\n\n```shell\n$ git clone --recursive https://gitlab.com/equalitie/ouinet.git\n```\n\nAssuming that `\u003cSOURCE DIR\u003e` points to the directory where the\n`CMakeLists.txt` file is, and `\u003cBUILD DIR\u003e` is a directory of your choice\nwhere all (even temporary) build files will go, you can build Ouinet with:\n\n```shell\n$ mkdir -p \u003cBUILD DIR\u003e\n$ cd \u003cBUILD DIR\u003e\n$ cmake \u003cSOURCE DIR\u003e\n$ cmake --build \u003cBUILD DIR\u003e\n```\n\nWhen the build process finishes you will find in `\u003cBUILD DIR\u003e` the binaries\nfor `client`, `injector` and their shared libraries, e.g. `libboost_asio.so`,\n`libcpp_upnp.a`, etc.\n\nPlease refer to Ouinet docs for instructions to build artifacts using a\n[Docker](https://ouinet.work/docs/build/docker.html) or\n[Vagrant](https://ouinet.work/docs/build/vagrant.html) dev environments.\n\n\n## Running the Injector\n\nIt's recommended to create a directory named `repos/injector` where the\nconfiguration file, the ed25519 keys and the TLS certificates will be stored.\n\nThe minimum configuration to start the Injector is shown below:\n\n```conf\n# repos/injector/ouinet-injector.conf\n\nlisten-on-utp-tls = 0.0.0.0:7085\ncredentials = test_user_change_me:test_password_change_me\n```\n\nYou can find more details of the available options in this\n[config example](repos/injector/ouinet-injector.conf) or by invoking\n`injector --help`.\n\nWhen your `repo` dir and the configuration file are ready you can start\nthe injector as follows:\n\n```shell\n$ ./injector --repo /path/to/your/repo\n```\n\nDuring its first start the injector will generate the private and public keys\nneeded to [sign content](https://ouinet.work/docs/how/cache.html#signatures)\n(`ed25519-*` files) and the certificates used to establish a TLS connection\nwhen contacting the injector via the uTP protocol. Please keep an eye on these\nfiles as some of them will be needed to configure your Ouinet clients.\n\nFor a production environment you may want to deploy the Injector using\n[Docker Compose](https://ouinet.work/docs/build/docker.html#docker-deployment).\n\n**Warning:** Running an Injector turns the host into a web proxy for Clients\nwith the correct credentials, which could pose a security or privacy risk\ndepending on your context. Please keep this in mind and only assume\nreasonable risks.\n\n## Running a Client\n\nCreate a repo directory, e.g. `repos/client` and add the configuration file\nfor the new client:\n\n```conf\n# repos/client/ouinet-client.conf\n\ncache-type = bep5-http\ncache-http-public-key = abcdefghijklmnopqrstuvwxyz01234567890abcdefghijklmno\ninjector-tls-cert-file = /path/to/your/repo/client/tls-cert.pem\ninjector-credentials = test_user_change_me:test_password_change_me\n```\n\nThe value of `cache-http-public-key` can be obtained from the injector file\nnamed `ed25519-public-key` or from the injector log entry that starts with\n`[INFO] Injector swarm: sha1('ed25519:abcdefghijklmnopqrstuvwxyz01234567890abcdefghijklmno/v6/injectors`.\n\n`injector-tls-cert-file` is the path to the `tls-cert.pem` copied from the\ninjector and `injector-credentials` should be set to the same value defined\nas `credentials` in `ouinet-injector.conf`.\n\nWhen the config file is ready you can start the client as follows:\n\n```shell\n$ ./client --repo /path/to/your/repo\n```\n\nFor more details about configuration options please run `./client --help`.\n\nOnce done, you can visit `localhost:8078` in your browser and it should show\nyou the client front-end with assorted information from the client and\nconfiguration tools. The client's HTTP proxy endpoint should be available to\nthe host at `localhost:8077`.\n\nAs well as Injectors, the Ouinet Clients can be deployed in production using\n[Docker Compose](https://ouinet.work/docs/build/docker.html#deploying-a-client).\n\n\n## Testing the Client with cURL\n\nNow that the Ouinet services are running we will test a simple scenario where\na Client requests a URL from the Injector.\n\nIt's important to disable `Origin` and `Proxy` mechanisms to force Ouinet to\nfetch the content from the Injector. To do this, you can press the `disable`\nbutton in Ouinet's front-end (running by default at `localhost:8078`)\nor to set the values `disable-origin-access` and `disable-proxy-access` to\n`true` in Ouinet's config and restart the service.\n\nThe following example requests `https://ouinet.work` from Ouinet's proxy\nrunning on port `8077` and receives an HTTP response with `x-ouinet-source`\nheader set to `[\"injector\"]`. SSL verification is skipped with `--insecure`\njust to keep the example as simple as possible, but for production applications\nthe Ouinet TLS certificate should be installed and validated.\n\n```shell\n$ curl https://ouinet.work \\\n    --header 'X-Ouinet-Group: ouinet.work' \\\n    --proxy 127.0.0.1:8077 \\\n    --insecure \\\n    --silent \\\n    --output /dev/null \\\n    --write-out '%{http_code},%{header_json}' | \\\n  grep x-ouinet-source\n\n\"x-ouinet-source\":[\"injector\"]\n```\n\nIf you're interested in a script that automatically generates `X-Ouinet-Group`\nfollowing the same rules used by Ceno Browser, please check [ouinet-curl](https://gitlab.com/equalitie/ouinet-examples/-/tree/main/shell/ouinet-curl)\nin the [ouinet-examples](https://gitlab.com/equalitie/ouinet-examples/) repo.\n\n\n## Integrating Ouinet into your Android application\n\nFirst add Ouinet and Relinker as dependencies in your app's `build.gradle.kts`:\n\n```gradle\ndependencies {\n    //...\n    implementation(\"ie.equalit.ouinet:ouinet-omni:0.23.0\")\n    implementation(\"com.getkeepsafe.relinker:relinker:1.4.4\")\n}\n```\n\nIn the `MainActivity.kt` of your app, import the Ouinet classes:\n\n```kotlin\nimport ie.equalit.ouinet.Ouinet;\nimport ie.equalit.ouinet.Config\n```\n\nAdd a private member to your `MainActivity` class:\n\n```kotlin\nprivate lateinit var ouinet: Ouinet\n```\n\nInitiate the Ouinet object in its `onCreate` method using the BEP5/HTTP\ncache settings:\n\n```kotlin\nvar config = Config.ConfigBuilder(this)\n    .setCacheType(\"bep5-http\")\n    .setCacheHttpPubKey(\"abcdefghijklmnopqrstuvwxyz01234567890abcdefghijklmno\")\n    .setInjectorCredentials(\"test_user_change_me:test_password_change_me\")\n    .setInjectorTlsCert(\"-----BEGIN CERTIFICATE-----\\nMIICyTCCAbGgAwIBAgIGAWwvE3jIMA0GCSqGSIb3DQEBCwUAMBQxEjAQBgNVBAMMCWxvY2FsaG9zdDAeFw0xOTA3MjQxNjE4MjFaFw0zNDA3MjIxNjE4MjFaMBQxEjAQBgNVBAMMCWxvY2FsaG9zdDCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAOQ6tX1fh1JQJGMEpgEaqFdVpl2Jz39s+3pFJAHRQMxvQa1a4pGwlc4smrhh8Y2ZKli8zhIzFPATZ3ipdBwnLBBUnDqpZWEqsKdBGGJghM+8EitXJwtSWjR2qqZcz3Xz60MKt2S2IeL6L3/HtHM1bN93Xo3hQK/WYDQ6BEeLd6JSsns1mwwccTStu/kc3Y2EIXPh1otQ624QXb9szIdwQw7vzi0saXONdaFFbpRyoa6KKCEC7iHHfUbEhCSRpL8YMrl5z9mKqA8y+5tl3jzTHRtYE4SVG60pmd9nMQ33ue8m5ADq5Bd8Jg2qOmmg0KNFV1RHB3pljMGco6eP9zmb3jsCAwEAAaMhMB8wHQYDVR0OBBYEFMCGT2KEmo4kM08CE/rv/BbnmVfnMA0GCSqGSIb3DQEBCwUAA4IBAQBWxR7x1vADpkpVRzNxicLgd0CYitmhEWtRQp9kE33O5BjRlHQ5TTA0WBp8Nc3c5ZZ1qAnQx3tXVZ7W1QY2XjiQpsPEhFcPsAtFLP+kpDEFPi39iFv4gunR4M1zReCDTGTJ48bLtqONZ9XgJ7obW8r+TjuJyI/i11NWUwKldg0NevF1Bkddbhpt7PJHUpSSbwr3GJOKHfRw9ZaX6P86MVcJd0TaAzZPXqk+2eab43GbbD6keXRGIufMThKGyrRX+9aIaV3tx3uWAOfWVmlzf9w3gV3DlmjPSOXmUsOLk0PFwoy7O7n9zJKNrUy1N2O+j0tH5HVXOnSjpS8aNrMtpfHS\\n-----END CERTIFICATE-----\")\n    .build()\n\nouinet = Ouinet(this, config)\nouinet.start()\n```\n\nPlease refer to [this example](https://gitlab.com/equalitie/ouinet-examples/-/blob/main/android/kotlin/README.md#pass-config-values-to-ouinet-during-the-build-process) if you want to pass the config values during the build process.\n\nNow create a Proxy object pointing to Ouinet's service `127.0.0.1:8077`:\n\n```kotlin\nval ouinetService = Proxy(Proxy.Type.HTTP, InetSocketAddress(\"127.0.0.1\", 8077))\n```\n\nAnd pass the Proxy object to your HTTP client (we're using `OKHTTPClient` in\nthis example):\n\n```kotlin\nOkHttpClient.Builder().proxy(ouinetService).build()\n```\n\nFrom now on, all of the app's HTTP communication will be handled by Ouinet.\nYou can check this\n[example](https://gitlab.com/equalitie/ouinet-examples/-/blob/main/android/kotlin/README.md#validate-ouinets-tls-cert)\nfor how to deal with Ouinet's TLS certificate.\n\nPlease note that if you plan to use a directory for Ouinet's\n[static cache](https://ouinet.work/docs/build/testing.html#using-an-external-static-cache)\nin your application (by using `ConfigBuilder`'s `setCacheStaticPath()` and\n`setCacheStaticContentPath()`), then besides the permissions declared by the\nlibrary in its manifest, your app will also need the `READ_EXTERNAL_STORAGE`\npermission (Ouinet will not attempt to write to that directory).\n\nYou can find additional information to control the\n[access mechanisms](https://gitlab.com/equalitie/ouinet-examples/-/blob/main/android/kotlin/README.md#test-ouinet-access-mechanisms) as well as examples of other Android applications in\n[equalitie/ouinet-examples](https://gitlab.com/equalitie/ouinet-examples).\n\n\n## References\n\n- [Ouinet's Website](https://ouinet.work/)\n- [Documentation](https://ouinet.work/docs/)\n- [Whitepaper](doc/ouinet-network-whitepaper.md)\n- [Matrix channel](https://matrix.to/#/#ouinet:matrix.org)\n- [Integration Examples](https://gitlab.com/equalitie/ouinet-examples)\n- [Ceno Browser](https://gitlab.com/censorship-no/ceno-browser/)\n- [Ceno Docker Client](https://github.com/censorship-no/ceno-docker-client)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fequalitie%2Fouinet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fequalitie%2Fouinet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fequalitie%2Fouinet/lists"}