Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 12 additions & 36 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,22 +1,23 @@
# Auth over HTTP

> ⚠️ **Warning**: This is ONLY a proof of concept. It is NOT ready for production use. DO NOT USE THIS IN PRODUCTION.
> [!WARNING]
> This is ONLY a proof of concept. It is NOT ready for production use. DO NOT USE THIS IN PRODUCTION.

This repo contains a proof of concept for HTTP Authentication for canisters. It showcases how to use [HTTP Message Signatures](https://www.rfc-editor.org/rfc/rfc9421.html) to authenticate requests to a canister.
This repo contains a proof of concept for HTTP Authentication for IC canisters. It showcases how to use the [Binary Representation of HTTP Messages](https://www.ietf.org/rfc/rfc9292.html) to send authenticated HTTP requests to a canister.

## Advantages

Using HTTP Message Signatures instead of the custom authentication mechanism has the following advantages:
Using HTTP Authentication instead of the custom authentication mechanism has the following advantages:

- Uses an IETF standard for authentication that does not require [setting custom fields in the request body](https://internetcomputer.org/docs/references/ic-interface-spec#authentication)
- Uses an IETF standard for encoding HTTP messages that does not require [setting custom fields in the request body](https://internetcomputer.org/docs/references/ic-interface-spec#authentication)
- Removes the need of [CBOR](https://internetcomputer.org/docs/references/ic-interface-spec#api-cbor) for encoding messages sent to and received from canisters. As a consequence:
- Canisters can expose their API using their preferred standard (e.g. OpenAPI, gRPC, etc.)
- Existing and widely adopted API standards (REST, GraphQL, etc.) can be used to interact with canisters, enabling popular tools and libraries to be used
- Developing client and server side code is easy, as the requests and responses are standard HTTP requests and responses

## Try It Out

The todo app example is available on mainnet at https://a5eh2-zqaaa-aaaac-qad2a-cai.icp0.io/
The todo app example is available on mainnet at https://a7hps-myaaa-aaaau-acuna-cai.icp3.io/, behind an [HTTP Gateway](https://github.com/ilbertt/http-gateway) that follows the new protocol.

### Components

Expand All @@ -26,9 +27,10 @@ Examples:

Packages:

- [ic-http-auth](./packages/ic-http-auth/): The canister side library for verifying HTTP Message Signatures
- [http-auth-js](./packages/http-auth-js/): The client side library for sending signed HTTP requests to a canister
- [ic-http](./packages/ic-http/): The canister side library for encoding and decoding HTTP messages
- [`@icp-sdk/http`](./packages/http-auth-js/): The client side library for sending signed HTTP requests to a canister
- [insomnia-plugin-ic-http-auth](./packages/insomnia-plugin-ic-http-auth/): An [Insomnia](https://insomnia.rest/) plugin for sending signed HTTP requests to a canister
- [local-replica](./packages/local-replica/): A binary that runs PocketIC and an HTTP Gateway locally

### Prerequisites

Expand All @@ -43,50 +45,24 @@ After cloning the repository, install the dependencies:

```shell
pnpm i
dfx deps pull
```

Then, start the local network:

```shell
dfx start --background --clean
cargo run -p local-replica
```

Then, deploy the canisters:

```shell
dfx deps deploy
dfx deploy
```

In the output, you will see a URL similar to `http://<canister-id>.localhost:4943`. Open this URL in your browser to see the todo app running locally.

## Benchmarks

At the current state, the proof of concept verifies signatures of requests sent to the canister inside the canisters directly. Verifying canister signatures is

We use [Canbench](https://github.com/dfinity/canbench) to benchmark the performance of some functions of the [ic-http-auth](./packages/ic-http-auth/) package.

To run the benchmarks, first install the `canbench` CLI:

```shell
cargo install canbench
```

Then, run the benchmarks:

```shell
cd packages/ic-http-auth
canbench
```

The latest results can be found in the [canbench_results.yml](./packages/ic-http-auth/canbench_results.yml) file.

> Note: if you want to update the benchmarks results, you can run the benchmarks with the `--persist` flag:
>
> ```shell
> canbench --persist
> ```
> [!NOTE]
> Currently, the HTTP Gateway running locally does not support the old HTTP Protocol, so the Internet Identity frontend will not work locally. You can either disable authentication locally or use the app deployed on mainnet.

## Contributing

Expand Down