Skip to content
Snippets Groups Projects
Commit 653922f7 authored by Keith Millette's avatar Keith Millette
Browse files

Add first batch of docs

parent cc2fa3dc
No related branches found
No related tags found
No related merge requests found
Expand all Hide whitespace changes
Inline Side-by-side
Showing
with 2153 additions and 0 deletions
website/docs/cmixx/_category_.json 0 → 100644
+ 8
− 0
View file @ 653922f7
{
"label": "cMixx",
"position": 4,
"link": {
"type": "generated-index",
"description": "All things related to cMixx"
}
}
website/docs/cmixx/adrp.md 0 → 100644
+ 64
− 0
View file @ 653922f7
# Anonymous Data Retrieval Protocol
The Anonymous Data Retrieval Protocol (ADRP) allows users to request
data anonymously from a server without ever revealing their identity.
With normal [end-to-end](e2e-xxm) connections in the xx Network, users always know the identity of whom
they are messaging. With ADRP, one can send a request to another user
containing a one-time-use key negotiation for an entirely new user. The
recipient can respond to the negotiation without ever knowing the
identity of the original sender. When ADRP is combined with the metadata
shredding capability of the cMixx protocol encapsulation, a powerful
anonymous data lookup is guaranteed.
This protocol is open for use with the
[xxDK](https://git.xx.network/elixxir/client) and is the basis for the
[User Discovery](userDiscovery) system’s privacy.
## Protocol Description
The requestor needs to know the xx messenger contact details
(cryptographic identity) of any user they request on the network
(including a [Diffie–Hellman
key](https://en.wikipedia.org/wiki/Diffie%E2%80%93Hellman_key_exchange)
and a network identity). xx messenger then generates a new key pair and
network identity by calculating a new, symmetric [Diffie–Hellman
key](https://en.wikipedia.org/wiki/Diffie%E2%80%93Hellman_key_exchange)
using the new key and the recipient’s key. The payload contents are then
encrypted with the new symmetric key via
[ChaCha20](https://en.wikipedia.org/wiki/Salsa20#ChaCha_variant), with
an appended HMAC.
The request is sent over cMixx in a single packet containing the new
public key (in clear-text) and encrypted message contents. Once
received, the recipient can execute a Diffie–Hellman with the clear-text
public key and decrypt the payload. The contents (and clear-text public
key) can be used to respond to the request from the new one-time-use
identity. The responses are also encrypted via
[ChaCha20](https://en.wikipedia.org/wiki/Salsa20#ChaCha_variant), with
an appended HMAC.
The recipient can then process the contents and respond via the ad-hoc
negotiated link. Finally, the sender confirms receipt by checking the
network for receptions on the new identity.
## Cryptographic Primitives Summary:
| Algorithm | Length | Description |
|---------------|----------------|-------------------------------------------------------------------------------------------------------|
| RSA | 4096 bits | Used as the signature algorithm for signing a fact or a key. |
| Blake2b | 256 bits | Algorithm used for generating single-use specific fingerprints and keys. Additionally used for HMACs. |
| Diffie Helmen | 3072 bits | Discrete log-based component of key negotiation. |
| ChaCha20 | 256 bits (key) | Messages and payloads are encrypted by ChaCha20. |
## Resources
- Single-Use
[Implementation](https://git.xx.network/elixxir/client/-/tree/release/single)
- Single-Use [Cryptographic
Library](https://git.xx.network/elixxir/crypto/-/tree/release/e2e/singleUse)
- [ID Implementation (Ephemeral and
Reception)](https://git.xx.network/xx_network/primitives/-/tree/release/id)
- [cMixx Message
Format](https://git.xx.network/elixxir/primitives/-/blob/release/format/message.go)
- [Sending cMixx
Messages](https://git.xx.network/elixxir/client/-/blob/release/network/message/sendCmix.go)
website/docs/cmixx/cmixx.md 0 → 100644
+ 13
− 0
View file @ 653922f7
---
sidebar_position: 1
---
# Overview
For cMixx, Node and Gateways pair together; every Node has a Gateway. Their relationship is a Scheduler-Worker design. In the initial design, this will be tiered with a Scheduling server orchestrating Nodes that then orchestrate their Gateways, which then pass schedules onto Clients. The Scheduling server takes its instruction from the blockchain; network participation is defined by staking and consensus. The network will rapidly remove scheduling functions from the scheduling server and move them to adjudication by xx Chain.
Currently, all components of cMixx are controlled either directly or recursively by a central Scheduling server. Each member polls the entity above them in the hierarchy for information, as shown in the figure. Bi-directional communication only exists within the same level. There are two primary components of this data that are communicated: the Network Definition File (NDF) and the RoundInfo.
The Network Definition File (NDF) contains all the connection information for the entities in the network and is provided by the Scheduling server through the hierarchy shown. The Nodes provide the hash of their current NDF to Scheduling; if they differ, then the updated NDF is provided to the Node. The Gateways poll the Nodes and Clients poll Gateways for the new NDF in the same fashion.
Nodes, Gateways, and Clients also receive scheduling instructions from the Scheduling server. These instructions are contained within RoundInfo structures, which are both prescriptive and descriptive of changes to rounds, which groups a set of Nodes to anonymize communications. A round is created when RoundInfo is issued to start a round’s precomputation. When the Nodes finish the precomputation, Scheduling issues a new RoundInfo that schedules it for realtime, which can be delayed depending on the number of queued rounds. Finally, a further RoundInfo is issued when a round completes or fails.
\ No newline at end of file
website/docs/cmixx/coverTraffic.md 0 → 100644
+ 6
− 0
View file @ 653922f7
# Cover Traffic
Cover traffic, also known as dummy traffic or decoy traffic, is used by the xx Messenger application to essentially give us two additional privacy properties known as “sender unobservability” and “receiver unobservability” (see the privacy notions paper https://arxiv.org/abs/1812.05638 ). If cover traffic is enabled, the xx Messenger client will, at random time intervals, send cover messages which are indistinguishable from ordinary messages. Any adversary watching your network traffic will not know when you are sending or receiving an ordinary message or a cover message.
Our cover traffic design is aided somewhat by our intentional recipient ID collisions (See [ID Collision and Notifications](idCollisionAndNotifications)). Cover traffic is sent to recipient IDs chosen at random from the small ID space which is intended to cause ID collisions. Therefore the cover messages will be received by random users of the xx Network.
The cover traffic yields the privacy properties summarized above and this is important for resisting attacks on the anonymity properties of the xx Network. Because your connection data leaks (true for all network connections), that can be used over time to determine who is talking to who. By activating cover traffic you are making these statistical disclosure attacks much more difficult.
website/docs/cmixx/e2e-xxm.md 0 → 100644
+ 98
− 0
View file @ 653922f7
# End-to-End Encrypted Messaging in xx Messenger
[End-to-End Encrypted
(E2EE)](https://en.wikipedia.org/wiki/End-to-end_encryption) messaging
is a way to securely and privately communicate with connections—only the
sender and receiver can read the contents of their messages. While
[cMixx](../overview/cmix) protects your metadata (the who, what,
when, and where of your communications), the E2EE between clients on the
xx Network provides the additional guarantee that no third party can
decipher data that is processed and stored. End-to-end encryption keeps
your message content private from third parties, including xx Nodes,
nodes’ internet service providers, cell phone companies, and any other
telecommunications devices or malicious actors on the internet–your data
belongs to you, and only you. We call these E2EE links authenticated
channels.
In xx Messenger, we provide E2EE messaging that is protected against
threats from quantum computers. We accomplish this by using a key
exchange algorithm that uses [post-quantum
cryptography](https://en.wikipedia.org/wiki/Post-quantum_cryptography)
combined with a known-secure regular key exchange algorithm, ensuring
that an attacker trying to break the protocol must break both to be
successful. The xx Network uses the [Supersingular Isogeny
Diffie–Helman](https://sike.org/files/SIDH-spec.pdf) (SIDH) algorithm
for post-quantum key exchange and the classic
[Diffie–Helman](https://en.wikipedia.org/wiki/Diffie%E2%80%93Hellman_key_exchange)
(DH) algorithm for regular key exchange.
To create an authenticated channel for E2EE messaging, the xx Messenger
needs the cMixx contact (public cryptographic identity key) to establish
encryption. Users can obtain these keys in one of two ways:
1. Exchanging QR codes with another user
2. Looking up another user with the User Discovery search function
After acquiring the other users’ cMixx contact, the xx Messenger sends an
authentication request message containing the SIDH and DH public keys
needed to initiate the key exchange. The recipient responds with their
own SIDH and DH public keys, and the original sender sends a final
confirmation message.
After receiving the other user’s SIDH and DH public keys, xx Messenger
computes the shared SIDH and shared DH secrets. It then combines these
secrets with a hash algorithm (BLAKE2B) to form the E2E Session Base
Key. This step finalizes the authenticated channel creation–each user
can now send E2EE messages.
To provide [forward
secrecy](https://en.wikipedia.org/wiki/Forward_secrecy) and
[post-compromise security](https://eprint.iacr.org/2016/221.pdf), the
E2E Session Base Key is periodically re-keyed in a process sometimes
known as
[ratcheting](http://cryptowiki.net/index.php?title=Ratcheted_encryption).
The sender on each side of the connection controls how often a re-key
occurs. To initiate a re-key, the client sends new SIDH and DH public
keys using the authenticated channel already in place. When the
recipient responds, the sender can generate a new E2E Session Base Key
to create a new version of the authenticated channel, which is
functionally identical to the previous authenticated channel but a
different key. These rekeys require an additional message, so they are
only sent on an as-needed basis.
Each message in the xx Messenger is encrypted with [XChaCha20 symmetric
encryption](https://cr.yp.to/chacha/chacha-20080128.pdf) with a keyed
hash [message authentication
code](https://en.wikipedia.org/wiki/Message_authentication_code)
[HMAC-SHA256](https://datatracker.ietf.org/doc/html/rfc2104). The key
used for encryption is derived from the E2E Session Base Key. In
addition, a fingerprint, which only the recipient can use, is included
in the message to allow the recipient to look up the same encryption key
for that message.
## Cryptographic Primitives Summary
| Algorithm | Length | Description |
|---------------|-----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| ChaCha20 | 256 bits | Messages and payloads are encrypted by ChaCha20. |
| BLAKE2B | 256 bits | Used as part of key generation, key expansion, identity generation, and identification codes. Used to combine Diffie–Helman and SIDH keys after key integration. |
| SHA256 | 256 bits | Message HMACs |
| Diffie–Helmen | 3072 bits | Discrete log-based component of key negotiation. |
| SIDH | 3024 bits | Quantum-resistant component of key negotiation. |
## Resources
- [Sending E2E
Messages](https://git.xx.network/elixxir/client/-/blob/release/network/message/sendE2E.go)
- [User Key
Exchange](https://git.xx.network/elixxir/client/-/tree/release/keyExchange)
- [E2E Manager and Storage
Implementation](https://git.xx.network/elixxir/client/-/tree/release/storage/e2e)
- [E2E Cryptographic
Library](https://git.xx.network/elixxir/crypto/-/tree/release/e2e)
- [Diffie Hellman Cryptographic
Library](https://git.xx.network/elixxir/crypto/-/tree/release/diffieHellman)
- [Hashing Cryptographic
Library](https://git.xx.network/elixxir/crypto/-/tree/release/hash)
- [Cloudflare's SIDH Implementation (in
Go)](https://github.com/cloudflarearchive/sidh)
website/docs/cmixx/idCollisionAndNotifications.md 0 → 100644
+ 67
− 0
View file @ 653922f7
# ID Collisions and Notifications
Typically, user IDs are unique identifiers and have the property of
being matched to one user. This allows the users to be strongly
identified, based upon an ID alone, making it easy to tell which user is
which.
When sending messages to users, the xx Network intentionally has users
share their IDs to receive messages–the sender ID details are removed
when the message is sent through the xx Network.
The goal here is to hide the identification details of which user
receives a message and prevent a special type of tagging attack possible
within the x protocol. You can read about the tagging attack in [cMixx
Tagging
Attack](https://docs.xx.network/cMix_Tagging_Attack_Analysis_and_Mitigation.pdf).
All users have a unique reception ID where they receive messages. When
you add a user as a contact, one can see their ID and use it at any time
to calculate their Ephemeral ID for a specific moment. Ephemeral IDs
rotate once per day, at a random time unique to the recipient.
Ephemeral IDs are calculated within a small bit space that is designed
to allocate at any given time roughly half as many IDs as the number of
users in the network. This ensures that users will be receiving messages
meant for other users to guarantee further privacy. However, due to
[end-to-end
encryption](e2e-xxm),
users cannot read these messages or access any data about the sender or
recipient.
At launch, and at any point where usage drops below a few hundred
thousand users, the number of users will be insufficient for this system
to function, requiring alternate protections.
## Notifications
The notifications system relies on shared ephemeral IDs to keep
notifications private. When a user registers for notifications, a server
run by the xx Network team tracks when their current ephemeral ID
receives a message and sends a notification. Then their phone processes
the notification to detect if the message is actually for the user and
will notify if it is. This bot, as well as the notifications provider
(currently available for Apple and Google operating systems), do not
know when a message is for you due to ID collisions, ensuring message
content is private.
## Cryptographic Primitives Summary
| Algorithm | Length | Description |
|--------------|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Ephemeral ID | 64 bits (max) | Weak identification of a network user. Designed such that collisions are probable. |
| User ID | 264 bits | Strong identification of a network user. Designed such that one’s user ID is unique under the [Birthday Paradox](https://en.wikipedia.org/wiki/Birthday_problem). |
| BLAKE2B | 256 bits | Used for ID generation (ephemeral and user IDs). |
## Resources
- [ID Primitives
Library](https://git.xx.network/xx_network/primitives/-/tree/release/id)
- [ID
Generation](https://git.xx.network/xx_network/crypto/-/tree/release/xx)
- [Ephemeral ID
Library](https://git.xx.network/xx_network/primitives/-/tree/release/id/ephemeral)
- [Notifications Ephemeral ID
Logic](https://git.xx.network/elixxir/notifications-bot/-/tree/release/notifications)
- [User-side Ephemeral ID
Logic](https://git.xx.network/elixxir/client/-/tree/release/storage/reception)
website/docs/cmixx/userDiscovery.md 0 → 100644
+ 103
− 0
View file @ 653922f7
# User Discovery
User Discovery (UD) is an xx Network service that helps users connect
with others by searching via username, email, or phone number. When a
user makes their xx Messenger account, they create a username and have
the option to include other identifiable information in their profile.
Other xx Messenger users can then use this information to search for
users in UD and start communicating.
User Discovery links each piece of profile data with a user’s xx
Messenger contact, which is a cryptographically generated ID and a
public key. When a user searches in UD, the search results display the
cMixx contact details needed to initiate end-to-end encrypted secure
communications. Privacy is always guaranteed; users can choose to accept
or decline communications from contacts discovered via a UD search.
User Discovery runs as a client on the xx Network. It’s server is
maintained by the xx Network team. Long term plans are to fully
decentralize this service onto the xx Network blockchain.
## User Registration
During the xx Messenger app installation process, users select a unique
username that is registered in UD. This registration is completed
securely via
[TCP/IP](https://en.wikipedia.org/wiki/Internet_protocol_suite) rather
than [cMixx](../overview/cmix).
After registering their username, xx Messenger generates cryptographic
information that will be used to identify the user uniquely. This
information includes:
- An RSA key pair defining a cryptographic identity (known as an ID)
- A discrete log Diffie–Helman public key for future key exchanges
(3072-bit, in
[RFC3526](https://datatracker.ietf.org/doc/html/rfc3526#section-4))
- An authorization signature from the network
Upon receiving their cryptographic information (i.e., by signing the
[Diffie–Hellman](https://en.wikipedia.org/wiki/Diffie%E2%80%93Hellman_key_exchange)
public key with the
[RSA](https://en.wikipedia.org/wiki/RSA_(cryptosystem)) key), users
upload their username and information to the User Discovery server to
complete registration. As a final step in the registration process, xx
Messenger ensures the username is unique and the information passes all
cryptographic checks.
### Registering Further Information
Users can choose to build out their profile by adding and registering
their email address or phone number. Users sign a registration request
with their RSA key to send the request for connection, which completes
checks before being passed to [Twilio](https://www.twilio.com), a
third-party service that will complete the verification process. Once
the user confirms their verification code, a salted hash
([Blake2b](https://en.wikipedia.org/wiki/BLAKE_(hash_function))) of
their email or phone number is stored in the database. xx Messenger
protects users’ personal information and never stores unencrypted plain
text on any servers.
## Searching for Users
xx Messenger allows users to easily find their connections by searching
for their username, email, or phone number. When a user fills in search
criteria, xx Messenger first salts and hashes the data and then sends it
over the [anonymous data retrieval
protocol](adrp), which utilizes [cMixx](../overview/cmix) and a unique, on-the-fly negotiation
format request to search for the user without ever revealing who is
searching or who is being searched. When received, the User Discovery
server searches for the salted hash in its database. If a match is
found, the relevant user’s cryptographic data is returned, allowing the
requesting user to form an
[end-to-end](e2e-xxm) relationship.
## Deletion
A user can delete a piece of their data or their entire registered
account at any time. However, this will not remove existing
relationships formed based on that data. To fully remove user data and
relationships, xx Messenger requires a signed statement that will allow
the app to completely remove data from the database.
## Cryptographic Primitives Summary
| Algorithm | Length | Description |
|----------------|-----------|-------------------------------------------------------------------------------------------------------------------|
| RSA | 4096 bits | Used as the signature algorithm for signing a fact or a key. |
| Blake2b | 256 bits | Algorithm used for hashing facts. It is a faster hashing algorithm that matches or exceeds the security of SHA-3. |
| Diffie–Hellman | 3072 bits | Discrete log-based component of key negotiation. |
## Resources
- [User-side
Code](https://git.xx.network/elixxir/client/-/tree/release/ud)
- [UD-Side Code](https://git.xx.network/elixxir/user-discovery-bot)
- [Fact
Implementation](https://git.xx.network/elixxir/primitives/-/tree/release/fact)
- [Fact Cryptographic
Library](https://git.xx.network/elixxir/crypto/-/tree/release/factID)
- [Cryptographic ID
Implementation](https://git.xx.network/xx_network/primitives/-/tree/release/id)
- [RSA
Signature](https://git.xx.network/xx_network/crypto/-/tree/release/signature/rsa)
website/docs/tutorial-basics/_category_.json → website/docs/cmixx/xxdk/_category_.json
+ 8
− 0
View file @ 653922f7
{ {
"label": "Tutorial - Basics", "label": "xxDK",
"position": 2, "position": 2,
"link": { "link": {
"type": "generated-index", "type": "generated-index",
"description": "5 minutes to learn the most important Docusaurus concepts." "description": "All things related to cMix"
} }
} }
website/docs/cmixx/xxdk/getting-started.md 0 → 100644
+ 559
− 0
View file @ 653922f7
This diff is collapsed.
website/docs/cmixx/xxdk/guides/_category_.json 0 → 100644
+ 8
− 0
View file @ 653922f7
{
"label": "Reference Guides",
"position": 5,
"link": {
"type": "generated-index",
"description": "All things related to cMix"
}
}
website/docs/cmixx/xxdk/guides/cmix-client-keystore.md 0 → 100644
+ 37
− 0
View file @ 653922f7
# cMix Client Keystore
The cMix Client Keystore is a directory-backed encrypted key-value storage which contains cryptographic keys and state data. It is implemented by wrapping the [EKV library](https://git.xx.network/elixxir/ekv).
The keystore is initially populated by a small number of critical keys that define a client’s identity. It holds all the information necessary to send messages (transmission) as well as to receive messages (reception or message pickup) on the cMix network. The keystore is extended as needed to store key and state information for various subsystems (e.g., E2E messaging).
# Handling the Client Keystore
The Client Keystore requires a directory path where it will be initialized. A client must provide a path to a directory on a filesystem as well as a password that will be used to encrypt the contents of the directory. Once initialized, several encrypted files are generated at that path and used to store a variety of things that must persist across runs of the client.
The password used to encrypt the contents of the keystore must be provided by the user or stored securely using secure storage, for example by using the [Android](https://developer.android.com/reference/android/security/KeyChain) or [iOS Keychain](https://developer.apple.com/documentation/security/keychain_services) APIs.
# Key Generation on Initialization
The cMix Client Keystore must be initialized on first run. Initializing the keystore creates a series of keys for outbound (transmission) communication with the xx network. These transmission keys are then used to register and negotiate a key with each node on the network.
The process generally takes 20~30 seconds on first run, but can take upwards of five minutes in rare cases. As a result, it is highly recommended in almost all cases to persist the initialized keystore across executions of the cMix client.
## Client Identity
At first, only the base data for sending messages (transmission) and receiving messages (reception) are stored in the keystore. These two sets of data include:
1. **Transmission Identity**
1. **RSA Transmission Keys:** The transmission keys are a pair of RSA private/public keys used to register with the xx network. The public key is signed by the client registrar, a temporary system run by the foundation to allow the registration of new clients to be disabled in the event of certain network attacks. In the future, this system will be replaced with an on-chain registrar which registers new users for a fee in xx coins.
2. **RSA Transmission ID:** This is a unique identifier used for sending messages over the network. It is generated using a salt and the RSA transmission public key.
2. **Legacy Reception Identity**
1. **RSA Reception Keys:** The [User Discovery](../technical-glossary#user-discovery-ud) system run by the xx foundation requires a signed reception identity for registration. While registration identities are generally intended to be fungible, for the xx messenger and xx foundation user discovery server, they are not and must be signed. This allows it to piggy back off of the protection mechanisms described in the *RSA Transmission Keys* section above.
2. **RSA Reception ID:** This is a unique identifier used by a cMix client to receive messages. It will typically poll this ID when looking for messages sent from other users. This ID is generated from a combination of a salt and the RSA reception public key.
## Other Critical Key Structures Stored in the Keystore
While a small set of keys are stored on initial execution, that group grows as various modules are exercised. Here are some of the more important keys which are stored in the client Keystore. This is not an exhaustive list.
- **E2E keys:** When a cMix client requests or receives requests for an authenticated connection with another client, it uses its end-to-end (E2E) identity. This is a pair of Diffie-Helman (DH) keys.
- **cMix state data**: Due to the decentralized nature of the xx network and the cMix protocol, there is no central repository for the state of message picking for an individual reception ID. Instead, it is the client’s responsibility to build a picture of the network and track its own message pickup information. This data is stored in the keystore as the client runs. The bulk of the data and its handling can be found in the [/cmix/identity](https://git.xx.network/elixxir/client/-/tree/release/cmix/identity) package.
- **Network signatures:** As described in the *Client Identity* section above, the Transmission Identity as well as the Legacy Reception Identity are signed by the Network Registrar. These signatures are stored in [/storage/user](https://git.xx.network/elixxir/client/-/tree/release/storage/user) as the `TransmissionRegistrationValidationsSignature`, and the `ReceptionRegistrationValidationsSignature`*.*
- **Node keypairs:** Clients negotiate symmetric keys with every node in the network in order to receive the mixes the nodes are a part of. These keys are stored in the keystore in [/cmix/nodes](https://git.xx.network/elixxir/client/-/tree/release/cmix/nodes).
\ No newline at end of file
website/docs/cmixx/xxdk/guides/ndf-retrieval.md 0 → 100644
+ 137
− 0
View file @ 653922f7
# NDF Retrieval
This guide covers how to fetch the [network definition file](../technical-glossary#network-definition-file-ndf), or NDF, either through the command line (CLI) or using the Client API (xxDK).
---
The xx network team maintains an encoded [NDF online](https://elixxir-bins.s3.us-west-1.amazonaws.com/ndf/mainnet.json), which has a comprehensive list of publicly available gateway addresses and their certificates. The data is base64-encoded (use `base64 -D` on the file to read). The reader may take this list or use their own methods to find gateway information depending on their trust model (see [Vetting Gateways section](https://www.notion.so/NDF-Retrieval-3899220500444ec4a71b05f954672728) below).
From this list, a [trustworthy gateway](https://www.notion.so/NDF-Retrieval-3899220500444ec4a71b05f954672728) should be determined by the reader. To avoid influencing or suggesting which gateways should be trusted, all examples in this guide use a local network. `localhost:8440` should be replaced with a trusted gateway address when fetching an NDF off of a live network.
## Using the CLI
The `getndf` CLI command enables you to download the NDF from a [network gateway](https://xxdk-dev.xx.network/technical-glossary/#gateway-also-network-gateway). This does not require a pre-established client connection, but you will need the IP address, port, and an SSL certificate for the gateway:
```bash
// Download an SSL certificate using OpenSSL 1.0.1 or newer
// (check your version if you get an error)
openssl s_client -showcerts -connect localhost:8440 < /dev/null 2>&1 | openssl x509 -outform PEM > certfile.pem
// Fetch NDF from a gateway
go run main.go getndf --gwhost localhost:8440 --cert certfile.pem | jq . >ndf.json
```
If you are trying to connect to one of the public networks, we recommend downloading an NDF directly for different environments by using the `--env` flag. This will download the NDF directly from a URL hosted by the xx network team:
```bash
// Download an NDF using the team environment URL
go run main.go getndf --env mainnet | jq . >ndf.json
```
## Using the xxDK
There are two (2) methods of retrieving an NDF via the xxDK. Neither requires a pre-established client connection.
### Downloading from a Gateway
You may download an NDF from a selected gateway using the xxDK via the `DownloadNdfFromGateway()` function. Below is an example code snippet using that xxDK call:
```go
// Gateway contact information
certPath := "path/to/gateway.crt"
address := "localhost:8440"
// Read certificate from file
cert, err := utils.ReadFile(certPath)
if err != nil {
jww.FATAL.Panicf("Failed to read file: %+v", err)
}
// Download NDF from a target gateway
resp, err := xxdk.DownloadNdfFromGateway(address, cert)
if err != nil {
jww.FATAL.Panicf("%v", err)
}
```
### Downloading from a URL
You may download an NDF using the xxDK from the URL provided by the xx network team using the `DownloadAndVerifySignedNdfWithUrl()` function call. The URL contains a signed version of the NDF which requires a certificate to verify that signature. There are several running environments, each with [its own URL and certificate](https://git.xx.network/elixxir/client/-/blob/release/cmd/deployment.go). Below is an example code snippet using that xxDK call:
```go
// Network environment parameters.
certificatePath := "path/to/certificate.crt"
ndfUrl := "<insertURL>"
// Read certificate
cert, err := ioutil.ReadFile(certificatePath)
if err != nil {
jww.FATAL.Panicf("Failed to read certificate: %v", err)
}
// Download NDF from URL
ndfJSON, err = xxdk.DownloadAndVerifySignedNdfWithUrl(ndfURL, string(cert))
if err != nil {
jww.FATAL.Panicf("Failed to download NDF: %+v", err)
}
```
## Vetting Gateways
When downloading an NDF from a gateway, it’s important to ensure that the targeted gateway can be trusted. There are many ways to do this; the team provides a few possible strategies for the reader to develop trust with a gateway. This is not intended to be a comprehensive guide for establishing trust with gateways, but a way to suggest possible avenues.
As an entry point, the team publishes a publicly available list of gateways in the published encoding of the NDF. You can download that, decode it, and select a gateway from the list. However, it is better to have some trust in the gateway as the wrong NDF can be provided by the gateway, connecting you to the wrong network. There are three (3) general methods you can use:
- **Choose a gateway run by you or an acquaintance.** If you know someone who runs a gateway, or you are running a gateway, you can use that information to connect to your gateway to get an NDF.
- **Use the longest-running gateways.** You can find the longest-running gateways by browsing the [dashboard](https://dashboard.xx.network/) and clicking on the node information, or via the [wallet](https://wallet.xx.network/#/staking) by browsing the staked validators.
- **Use team-run gateways.** If you trust the team, you can select the team gateway. The details of the team gateway are:
> **Name:** xx west
>
>
> **Node ID:** `c6wptSinakErZHrk0SlgGQXExETPYYLB2CwpLNze6FMC`
>
> **Validator wallet:** `6Wb9wqBLi8iBhpnNqqWDVPcqfRQMkqTZWq9cAsALwC7W68h4`
>
> **Gateway ID:** `c6wptSinakErZHrk0SlgGQXExETPYYLB2CwpLNze6FMB`
>
> **Address:** `161.35.228.41:22840`
>
> **Tls_certificate:**
>
> ```bash
> -----BEGIN CERTIFICATE-----
> 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
> -----END CERTIFICATE-----
> ```
>
\ No newline at end of file
website/docs/cmixx/xxdk/mobile docs/_category_.json 0 → 100644
+ 4
− 0
View file @ 653922f7
{
"label": "Mobile Docs",
"position": 4
}
website/docs/cmixx/xxdk/mobile docs/ios-sdk.md 0 → 100644
+ 230
− 0
View file @ 653922f7
---
sidebar_position: 3
---
# iOS SDK
## Installation
The Elixxir SDK requires the use of the [Swift Package Manager](https://swift.org/package-manager/)—a tool for managing the distribution of Swift code. To use the SDK, add it to dependencies in your `Package.swift` file.
```swift
dependencies: [
.package(url: "https://git.xx.network/elixxir/elixxir-dapps-sdk-swift")
]
```
## Initialization
The instructions below describe how to initialize the client and connect to the network.
1. First, you will need to create a secure area to store client data. You can do this by creating a `PasswordStorage` for saving and loading your client storage. For example purposes we will use UserDefaults, but really encourage you to not use it and use `Keychain` instead.
```swift
let demoPasswordStorage = PasswordStorage(
save: { password in
UserDefaults.standard.set(password, forKey: "SDKPassword")
},
load: {
UserDefaults.standard.value(forKey: "SDKPassword") as! Data
})
```
2. Next, create a client storage to manage client data stored on disk.
```swift
let clientStorage = ClientStorage.live(passwordStorage: demoPasswordStorage)
```
3. If a client storage already exists, load it instead of creating a new one.
```swift
let client = Client
/*
//loadClient is a blocking call, do it on the background thread
//createClient is a blocking call, do it on the background thread
*/
if clientStorage.hasStoredClient() {
client = try? clientStorage.loadClient()
} else {
client = try? clientStorage.createClient()
}
```
4. Next, create an identity. You will need to create a connection later.
```swift
/*
//Blocking call, do it on the background thread
*/
let myIdentity = try client.makeIdentity()
```
5. Start the network follower.
```swift
let networkFollower = client.networkFollower
/*
//Blocking call, do it on the background thread
//Time is in millisecond
*/
try networkFollower.start(timeoutMS: 30_000)
```
6. Finally, wait for the network to be connected.
```swift
/*
//Blocking call, do it on the background thread
//Time is in millisecond
*/
let isConnected = client.waitForNetwork(30_000)
guard isConnected else { /* try again */ }
```
## Send Rest-like message
The instructions below describe how to use the restlike API to send requests and receive messages like a rest API.
1. First, create an E2E client.
```swift
/*
//Blocking call, do it on the background thread.
*/
let clientE2E = try ClientE2ELogin.live(with: client)
```
2. Next, to initiate a connection with the remote, use an unauthenticated connection. (To get remote identity, please refer to [this](https://git.xx.network/elixxir/client/-/blob/release/restlike/README.md).)
```swift
/*
//Blocking call, do it on the background thread
// You need your remote identity.
*/
let connection = try client.connect(withAuthentication: false, recipientContact: REMOTE_IDENTITY, e2eId: clientE2E.getId())
```
3. Next, create a `RequestSender`.
```swift
let restLikeRequestSender = RestlikeRequestSender.live(authenticated: false)
```
4. Create your request that you will send.
```swift
/*
//All fields are customizable to meet your remote configuration
//Content accepts any json encoded object, this is where you include your request body
//Method number is used to refer to get, post, put, etc.
*/
let request = RestlikeMessage(
version: Int,
headers: YOUR_HEADERS,
content: YOUR_JSON_ENCODED_MODEL,
method: Int,
Uri: String,
error: String)
```
5. Send your request and wait for a response.
```swift
/*
//Blocking call, do it on the background thread
//Response is RestLikeMessage object
*/
let response = try? restLikeRequestSender.send(
client.getId(),
connection!.getId(),
request)
/*
//Jumping to the main thread to update any UI with the response
*/
DispatchQueue.main.async {
let message = response
//Use the response message here to update UI
}
```
## Send E2E message
1. First, create an E2E client.
```swift
/*
//Blocking call, do it on the background thread.
*/
let clientE2E = try ClientE2ELogin.live(with: client)
```
2. Next, to initiate a connection with the remote, use an unauthenticated connection. (To get remote identity, please refer to [this](https://git.xx.network/elixxir/client/-/blob/release/restlike/README.md).)
```swift
/*
// Blocking call, do it on the background thread
// You need your remote identity.
*/
let connection = try client.connect(
withAuthentication: false,
recipientContact: REMOTE_IDENTITY,
e2eId: clientE2E.getId())
```
2. Setup your messages listener.
```swift
/*
//Blocking call, do it on the background thread
//messageType value must be same as the value you will use to send a message
*/
connection.listen(messageType: Int) { message in
/*
//Jumping to the main thread to update any UI with the message
*/
DispatchQueue.main.async {
let msg = message
//Use the received message here to update UI
}
}
```
3. Send the message and wait to get the send report, which contains the delivery status.
```swift
/*
//Blocking call, do it on the background thread
//messageType value must be same as the value you used to setup your messages listener
*/
let sendReport = try connection?.send(
messageType: Int,
payload: YOUR_JSON_ENCODED_MODEL)
```
4. Wait for the message to be delivered and update the UI if needed.
```swift
/*
//Blocking call, do it on the background thread
//Time is in millisecond
*/
client.waitForDelivery(report: sendReport, timeoutMS: 30_000) { result in
/*
//Jumping to the main thread to update any UI
*/
DispatchQueue.main.async {
switch result {
case .delivered(let roundResults):
// You can stop loading indicator here for example
case .notDelivered:
//Show error popup here for example
}
}
}
```
website/docs/cmixx/xxdk/overview.md 0 → 100644
+ 40
− 0
View file @ 653922f7
---
sidebar_position: 1
---
# Overview
The Client API (xxDK) is the client-side software for communicating with the cMix network, a privacy-protecting layer within the larger [xx network](https://xx.network/) blockchain ecosystem. cMix builds on current data protection mechanisms by extending security beyond just content to include metadata — the what, when, where, and how of user activity.
:::info
To learn more about the cMix protocol and what it offers, a good place to start is [the cMix whitepaper](https://xx.network/xxcMixwhitepaper.pdf).
:::
The xxDK helps developers provide unparalleled privacy for their users by implementing xx network messaging features such as end-to-end encryption and metadata protection. It comes with an API library and related command-line facilities that enable developers to build full-featured xx clients for all platforms. Additionally, the base messaging protocols can be extended.
Some use cases for integrating the API into your applications include (but are not limited to) building:
- Banking applications
- Voting applications, such as [Votexx](https://votexx.org/)
- Secure messaging apps for private communication, such as [xx messenger](https://xx.network/messenger/)
The xxDK supports golang versions 1.17 or newer. You can find the most recent version on [Gitlab](https://git.xx.network/elixxir/client).
It's easy to get started with the xxDK. Explore the links below to find what you need.
### Getting Started
The [Getting Started](getting-started) guide is where to begin if you're looking to get up and running quickly.
### API Quick Reference
The [API Quick Reference](https://pkg.go.dev/gitlab.com/elixxir/client/xxdk) provides extensive detail on the different types and functions exposed by the xxDK.
### Technical Glossary
The [Technical Glossary](technical-glossary) offers meanings to unfamiliar terms and concepts specific to the cMix system.
<!-- ### FAQs
Refer to the FAQ for answers to some of our users' most common questions. -->
website/docs/cmixx/xxdk/quick-reference.md 0 → 100644
+ 665
− 0
View file @ 653922f7
This diff is collapsed.
website/docs/cmixx/xxdk/technical-glossary.md 0 → 100644
+ 97
− 0
View file @ 653922f7
---
sidebar_position: 6
---
# Technical Glossary
There are several terms and concepts in these docs that are specific to the cMix network. This page lists some of the most important and a few general computing terms.
## A
### **Authenticated Channel**
An authenticated channel is a state where both the sender and recipient have verified their identities. cMix clients can send and receive authenticated channel requests.
## C
### **Client**
A computer performing the 'client' role in a client-server network architecture.
### **cMix Client**
A cMix client is a unique user in the cMix network. It can send and receive private data. All cMix clients use the [Client API](https://git.xx.network/elixxir/client) to interact with the cMix network.
### **Client Session**
See **[Session](#session-also-client-session)**
### **Client Command-Line Interface (CLI)**
The Client CLI is a command-line tool intended for testing xx network functionality. It can send and receive messages and authenticated channel requests. For instructions on how to set it up, see [*Set Up the Client Locally*](./getting-started.md/#set-up-the-client-locally).
## G
### **Gateway (also Network Gateway)**
The public-facing component of a node. One exists for each node. Gateways store received messages and provide public access to data.
## P
### **Permissioning Server**
The permissioning server, also referred to as the scheduling server, manages the [NDF](#network-definition-file-ndf) for cMix clients and servers. It schedules cMix rounds within the network.
### **Precanned Client**
A precanned client (created with `NewPrecannedClient()`) is used for integration testing and should not be used unless you are working on the cMix gateway and servers. You cannot connect to any public networks with a precanned client.
## R
### **Rekeying**
A process of renegotiating a key with a partner. This is triggered based on how frequently the current session key is used. When that passes a threshold, a renegotiation is triggered. The user then uses an unused session with its unique key and sends that over to their partner. The partner creates a new send and receive relationship with this public key to continue communication with their partner.
### **Round**
The process by which batches of messages are processed by the mixnet. Rounds are represented by positive integers in logs.
## S
### **Server**
A computer performing the 'server' role in a client-server network architecture.
### **Session (also Client Session)**
An encrypted key-value (EKV) store containing the cryptographic keys and state of a cMix client.
## U
### **User Discovery (UD)**
User Discovery helps users make first contact with other users. Using the "single use" package within the xxDK, User Discovery implements a completely private user lookup where the system cannot determine which user is querying. The system leverages Twilio to verify emails and phone numbers if the user would like to do so.
## N
### **Network Definition File (NDF)**
A JSON file required for registering a cMix client as a user within the cMix network. It describes how to communicate with the Nodes, Gateways, and other servers on the network. For more detail, see *[Network Definition File (NDF)](https://xxnetwork.wiki/index.php/Network_Definition_File_(NDF))*.
### **Network Gateway**
See **[Gateway](#gateway-also-network-gateway)**
### **Network Health**
The state of the network as tracked by network followers. It is either healthy or unhealthy. The network is in a healthy state when the health tracker sees rounds completed successfully and vice versa.
### **Node**
A core operator of the cMix network. Executes the cMix protocol and validates the xx blockchain.
## V
### **Vanity Client**
A user whose cMix ID starts with a supplied prefix (such as their username). It is created with the `NewVanityClient()` function, which generates IDs randomly until it meets the required set of criteria. Similar to Bitcoin's vanity addresses.
\ No newline at end of file
website/docs/dapps/_category_.json 0 → 100644
+ 8
− 0
View file @ 653922f7
{
"label": "dApps",
"position": 6,
"link": {
"type": "generated-index",
"description": "3rd Party dApps"
}
}
website/docs/dapps/intro.md 0 → 100644
+ 1
− 0
View file @ 653922f7
todo
\ No newline at end of file
website/docs/dapps/phoenixx.md 0 → 100644
+ 0
− 0
View file @ 653922f7
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment