Web2 Request Execution
Oyster comes with a HTTP gateway by default accessible at oyster.run.
Mapping subdomains
The gateway accepts any requests sent to <subdomain>.oyster.run and uses the subdomain to fetch the code to be executed. The subdomain is expected to be the tx hash of the code tx encoded using Base32 without any padding. This online tool can be used to encode hexadecimal transaction hash to Base32.
For example, to send requests to the code in tx hash 0x2c9eb7c03d2062516ca0a828c84b3a87d0365c47f71d326ea196f91031eefcac, you would need to send it to FSPLPQB5EBRFC3FAVAUMQSZ2Q7IDMXCH64OTE3VBS34RAMPO7SWA.oyster.run.
Perfect forwarding
The gateway aims to perfectly forward requests that it receives to the serverless function. This includes the URI path, URI query, HTTP method, HTTP headers, HTTP body, etc. This is in turn available inside the workerd runtime and can be handled by the serverless function. The same applies to the response as well.
Example request
Here is an example request being sent to the factorization function.
$ curl FSPLPQB5EBRFC3FAVAUMQSZ2Q7IDMXCH64OTE3VBS34RAMPO7SWA.oyster.run -d '{"num": 60000}' -v
* Trying <redacted>:80...
* Connected to FSPLPQB5EBRFC3FAVAUMQSZ2Q7IDMXCH64OTE3VBS34RAMPO7SWA.oyster.run (<redacted>) port 80 (#0)
> POST / HTTP/1.1
> Host: FSPLPQB5EBRFC3FAVAUMQSZ2Q7IDMXCH64OTE3VBS34RAMPO7SWA.oyster.run
> User-Agent: curl/7.81.0
> Accept: */*
> Content-Length: 14
> Content-Type: application/x-www-form-urlencoded
>
* Mark bundle as not supporting multiuse
< HTTP/1.1 200 OK
< Server: nginx/1.18.0 (Ubuntu)
< Date: Mon, 25 Dec 2023 05:29:56 GMT
< Content-Type: text/plain;charset=UTF-8
< Content-Length: 19
< Connection: keep-alive
< x-oyster-signature: 37ca998deec540de877833274f46f11b4e814341edb05dd3d41e66aac806cf714fcb1558677ab9374caa45021f87189101b5cd2cc3bdb4b9f1e65f17f6880ed31b
< x-oyster-timestamp: 1703482196
<
* Connection #0 to host FSPLPQB5EBRFC3FAVAUMQSZ2Q7IDMXCH64OTE3VBS34RAMPO7SWA.oyster.run left intact
2,2,2,2,2,3,5,5,5,5
The function successfully executes and returns the factors in the response.
Verifying the result
Here is the example request from the previous page.
$ curl FSPLPQB5EBRFC3FAVAUMQSZ2Q7IDMXCH64OTE3VBS34RAMPO7SWA.oyster.run -d '{"num": 60000}' -v
* Trying <redacted>:80...
* Connected to FSPLPQB5EBRFC3FAVAUMQSZ2Q7IDMXCH64OTE3VBS34RAMPO7SWA.oyster.run (<redacted>) port 80 (#0)
> POST / HTTP/1.1
> Host: FSPLPQB5EBRFC3FAVAUMQSZ2Q7IDMXCH64OTE3VBS34RAMPO7SWA.oyster.run
> User-Agent: curl/7.81.0
> Accept: */*
> Content-Length: 14
> Content-Type: application/x-www-form-urlencoded
>
* Mark bundle as not supporting multiuse
< HTTP/1.1 200 OK
< Server: nginx/1.18.0 (Ubuntu)
< Date: Mon, 25 Dec 2023 05:29:56 GMT
< Content-Type: text/plain;charset=UTF-8
< Content-Length: 19
< Connection: keep-alive
< x-oyster-signature: 37ca998deec540de877833274f46f11b4e814341edb05dd3d41e66aac806cf714fcb1558677ab9374caa45021f87189101b5cd2cc3bdb4b9f1e65f17f6880ed31b
< x-oyster-timestamp: 1703482196
<
* Connection #0 to host FSPLPQB5EBRFC3FAVAUMQSZ2Q7IDMXCH64OTE3VBS34RAMPO7SWA.oyster.run left intact
2,2,2,2,2,3,5,5,5,5
You might have noticed some interesting fields in the response - x-oyster-signature and x-oyster-timestamp. These fields help verify that the response is indeed coming from a serverless enclave.
General verification
The response is signed by the enclave key and a list of verified serverless enclave keys are maintained by the serverless contract. New keys can be added to the contract only after verifying an attestation from the enclave that it is a valid serverless enclave.
The message signed by the enclave is of the following format:
|oyster-serverless-hasher||timestamp|<timestamp>|request||method|<method>|pathandquery|<pathandquery>|host|<host>|body|<request_body>|response||body|<response_body>
with the elements between <> replaced with the corresponding request/response parameters.
This message is hashed using keccak256 and the digest is signed using an ECDSA keypair.
To verify, simply reconstruct the message as given above and verify the signature using the contract function below.
It is possible to verify the signature off-chain without using the contract below, but you need to ensure beforehand that the key signing the message belongs to a valid serverless enclave.
On-chain verification
The signature can be verified on-chain in the same manner. To make it easier, the serverless contract provides a helper function you can use.
TLS support
Support for TLS is in the works, so the results can be used without verification in the context of a TLS connection. TLS keys will be held purely inside the enclave, just the act of being able to establish a TLS connection is enough to verify that it is a legitimate enclave. This makes off-chain verification quite trivial and is especially important for the serverless platform to work securely with browsers and existing tools which can not implement the verification steps mentioned above.