adding API links

docs/developer-docs/integrations/vetkeys/technology-overview.md

@@ -1,7 +1,7 @@
 # vetKeys: technology overview
 
 ## Overview
-vetKeys on the Internet Computer allow developers to more easily perform encryption, threshold decryption, and signing when building dapps on the IC. It is powered by a protocol called **VETKD (Verifiably Encrypted Threshold Key Derivation)** that allows to derive decryption keys on demand.
+vetKeys on the Internet Computer allow developers to more easily perform encryption, threshold decryption, and signing when building dapps on the IC. It is powered by a protocol called **vetKey (Verifiably Encrypted Threshold Key Derivation)** that allows to derive decryption keys on demand.
 
 ## Key derivation on demand
 Blockchains are not known for their privacy capabilities. The goal of vetKeys is to ease the burden of using security and privacy tools on the Internet Computer. 
@@ -16,17 +16,17 @@ The availability of vetKeys allows for a series of applications including but no
 
 The main use case is to enable a blockchain to host threshold-encrypted data in a way that scales to millions of users and billions of secrets, using just a single threshold-shared secret key. BLS signatures are unique, making them immediately useful as symmetric keys.
 
-Think for example of a secure file storage dapp: a user could use the BLS signature on her identity as the root secret under which they encrypt their files before storing them in the dapp. 
+Think for example of a secure file storage dapp: a user could use the BLS signature on their identity as the root secret under which they encrypt their files before storing them in the dapp.
 The dapp enforces that only the authenticated user is allowed to recover the root key, and hence decrypt the files.
 The nodes in the blockchain assist a user in recovering their root key, but never see that key or the content of the files.
 
 ## More sophisticated access policies can also be expressed
 In a secure messaging dapp, the conversation between two users can be encrypted using the BLS signature on their pair of identities, to which only those users are given access by the dapp.
-An end-to-end encrypted decentralized social network (SocialFi) can let users encrypt posts using a key that is related to the post, e.g., the BLS signature on a unique identifier for the post.
+A secure decentralized social network could let users encrypt posts using a key that is related to the post, e.g., the BLS signature on a unique identifier for the post.
 The SocialFi dapp then ensures that only the author and the users that the post is shared with get access to that key.
 
 ## Blockchain-issued signatures and cross-chain bridges
-Because the key derivation of an IBE automatically yields a signature scheme, the resulting decryption keys can also be used as signatures issued by the blockchain.
+The key derivation of an IBE automatically yields a signature scheme, the resulting decryption keys can also be used as signatures issued by the blockchain.
 This is especially useful for blockchains that don't have a built-in certification feature enabling dapps to sign statements.
 It can also be used to efficiently bridge blockchains, e.g., to swap assets in DeFi application: a dapp on a first blockchain can verify signed statements issued by a second blockchain, without having to implement a complete light client of that second chain.
 
@@ -35,21 +35,27 @@ Because of their uniqueness, BLS signatures can also act as a verifiable random
 Trusted, verifiable randomness is important for applications such as trustless online lotteries and casinos, fair decentralized games (GameFi), and selecting random features for non-fungible tokens (NFTs). 
 
 ## "Dead man's switch"
-Journalists or whistleblowers can ensure that compromising information in their possession is automatically published if they were to become incapacitated. 
+Journalists or whistleblowers could ensure that compromising information in their possession is automatically published if they were to become incapacitated. 
 They can store the information in a dapp, encrypted under a BLS signature that the dapp automatically and publicly recovers when a certain amount of time passes after it has received an authenticated ping from its owner.
 
 ## Secret-bid auctions and MEV protection
-A VETKD-equipped blockchain can also cover use cases where many ciphertexts needs to be decrypted at the same time.
-In a secret-bid auction dapp, users can submit bids that are IBE-encrypted under an identifier of the auction, so that at the end of the auction, the dapp can decrypt all bids with a single VETKD evaluation. A similar technique can be used to prevent front-running, also known as miner-extracted value (MEV), on a decentralized exchange (DEX). Users submit their transactions IBE-encrypted under a predictable batch identifier. The DeX orders the transactions in encrypted form and, when all transactions for a particular batch have been ordered, triggers the recovery of the decryption key for that batch and executes the decrypted transactions in the fixed order. Note that all of the symmetric-encryption use cases listed above can be modified to encrypt using an IBE instead of a symmetric-key encryption, thereby eliminating the need to perform a VETKD derivation for encryption. Decryption, of course, still requires a VETKD evaluation.
+A vetKey-equipped blockchain can also cover use cases where many ciphertexts needs to be decrypted at the same time.
+In a secret-bid auction dapp, users can submit bids that are IBE-encrypted under an identifier of the auction, so that at the end of the auction, the dapp can decrypt all bids with a single vetKey evaluation. A similar technique can be used to prevent front-running, also known as miner-extracted value (MEV), on a decentralized exchange (DEX). Users submit their transactions IBE-encrypted under a predictable batch identifier. The DeX orders the transactions in encrypted form and, when all transactions for a particular batch have been ordered, triggers the recovery of the decryption key for that batch and executes the decrypted transactions in the fixed order. Note that all of the symmetric-encryption use cases listed above can be modified to encrypt using an IBE instead of a symmetric-key encryption, thereby eliminating the need to perform a vetKey derivation for encryption. Decryption, of course, still requires a vetKey evaluation.
 
 ## Time-lock encryption
-Time-lock encryption enables a sender to encrypt a message to the future, ensuring that it will get decrypted at a given time, but no earlier than that time. Existing solutions rely on centralized trusted parties, witness encryption (see next paragraph), or gradual release through puzzle solving. Time-lock encryption can be achieved via IBE by letting a centralized authority release IBE decryption keys corresponding to the current time at regular intervals, and letting the sender IBE-encrypt its message using the desired decryption time as identity.The authority's functionality can be run in a dapp on a VETKD-equipped blockchain, eliminating the need for a trusted central party.
+Time-lock encryption enables a sender to encrypt a message to the future, ensuring that it will get decrypted at a given time, but no earlier than that time. Existing solutions rely on centralized trusted parties, witness encryption (see next paragraph), or gradual release through puzzle solving. Time-lock encryption can be achieved via IBE by letting a centralized authority release IBE decryption keys corresponding to the current time at regular intervals, and letting the sender IBE-encrypt its message using the desired decryption time as identity.The authority's functionality can be run in a dapp on a vetKey-equipped blockchain, eliminating the need for a trusted central party.
 
 ## Witness encryption
-A witness encryption scheme for a language (L) with witness relationship (R) lets a sender encrypt a message to an instance (x) in L that can only be decrypted using a witness (w) such that R(x,w). The only current implementations are based on indistinguishability obfuscation, of which few instantiations are known based on well-founded assumptions. Witness encryption is almost trivial to implement on a VETKD-enabled blockchain: anyone can IBE-encrypt their message using the instance x as identity, while a witness-verifying dapp lets anyone who provides a valid witness w for x (or a valid zero-knowledge proof of knowledge of w, if it should remain private) to obtain the decryption key for x. The primitive may sound rather theoretical at first, but it actually covers quite practical use cases as it enables one to encrypt to any verifiable future event, e.g., the price of a stock going above or below a certain level, information escrow, or break-the-glass policies.
+A witness encryption scheme for a language (L) with witness relationship (R) lets a sender encrypt a message to an instance (x) in L that can only be decrypted using a witness (w) such that R(x,w). The only current implementations are based on indistinguishability obfuscation, of which few instantiations are known based on well-founded assumptions. Witness encryption is almost trivial to implement on a vetKey-enabled blockchain: anyone can IBE-encrypt their message using the instance x as identity, while a witness-verifying dapp lets anyone who provides a valid witness w for x (or a valid zero-knowledge proof of knowledge of w, if it should remain private) to obtain the decryption key for x. The primitive may sound rather theoretical at first, but it actually covers quite practical use cases as it enables one to encrypt to any verifiable future event, e.g., the price of a stock going above or below a certain level, information escrow, or break-the-glass policies.
 
 ## One-time programs
-Another cryptographic primitive with few instantiations is one-time programs that can be executed only once on a single input, and that don't leak anything about the program other than the result of the computation. Their only currently known instances rely on trusted hardware or on witness encryption on a blockchain. Given that witness encryption is easy to build on a VETKD-enabled blockchain, it should not come as a surprise that one-time programs are as well. The creator of the program garbles the circuit and IBE-encrypts the input wire keys, using the wire index and the value as the identity. A dapp assists users in recovering the IBE decryption corresponding to their input, making sure that only a single value for each wire is ever recovered.
+Another cryptographic primitive with few instantiations is one-time programs that can be executed only once on a single input, and that don't leak anything about the program other than the result of the computation. Their only currently known instances rely on trusted hardware or on witness encryption on a blockchain. Given that witness encryption is easy to build on a vetKey-enabled blockchain, it should not come as a surprise that one-time programs are as well. The creator of the program garbles the circuit and IBE-encrypts the input wire keys, using the wire index and the value as the identity. A dapp assists users in recovering the IBE decryption corresponding to their input, making sure that only a single value for each wire is ever recovered.
+
+## Proposed system API
+In ongoing development of the vetKeys feature, there is an API descriptions in this [draft MR to extend the Interface Spec](https://github.com/dfinity/interface-spec/pull/158), which contains API descriptions for the two new methods:
+* `vetkd_public_key' ([preview](https://deploy-preview-158--ic-interface-spec.netlify.app/docs/#ic-vetkd_public_key))
+* `vetkd_encrypted_key' ([preview](https://deploy-preview-158--ic-interface-spec.netlify.app/docs/#ic-vetkd_encrypted_key))
+The exact API is then in the [Interface Overview](https://deploy-preview-158--ic-interface-spec.netlify.app/docs/#ic-candid) (in the section “Threshold key derivation”)
 
 ## References
 - [Forum post](https://forum.dfinity.org/t/threshold-key-derivation-privacy-on-the-ic/16560).