yuanshanhshan / ockam Goto Github PK

Rust and Elixir libraries for end-to-end encrypted, mutually authenticated, secure communication.

Data, within modern distributed applications, are rarely exchanged over a single point-to-point transport connection. Application messages routinely flow over complex, multi-hop, multi-protocol routes — across data centers, through queues and caches, via gateways and brokers — before reaching their end destination.

Transport layer security protocols are unable to protect application messages because their protection is constrained by the length and duration of the underlying transport connection.

Ockam is a suite of programming libraries and infrastructure that makes it simple for our applications to guarantee end-to-end integrity, authenticity, and confidentiality of data.

We no longer have to implicitly depend on the defenses of every machine or application within the same, usually porous, network boundary. Our application's messages don't have to be vulnerable at every point, along their journey, where a transport connection terminates.

Instead, our application can have a strikingly smaller vulnerability surface and easily make granular authorization decisions about all incoming information and commands.

• End-to-end encrypted, mutually authenticated secure channels.
• Key establishment, rotation, and revocation - for fleets, at scale.
• Identity profiles isolated by privacy contexts.
• Attribute-based Access Control - credentials with selective disclosure.
• Add-ons for a variety of operating environments, transport protocols, and cryptographic hardware.
• Libraries for multiple languages - Rust, Elixir (more on the roadmap).

Let's write a simple example to create an encrypted secure channel between Alice and Bob. When a message is sent through this channel it will be encrypted when it enters the channel and decrypted just before it exits the channel.

For the purpose of our first example, we'll create a local channel within one program. In later examples, you'll see that it's just as easy to create end-to-end protected channels over multi-hop, multi-protocol transport routes:

1. Install Rust

   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
   

2. Setup a new cargo project to get started.

   cargo new --lib hello_ockam && cd hello_ockam && mkdir examples &&
     echo 'ockam = "*"' >> Cargo.toml && cargo build
   

   If the above instructions don't work on your machine, please post a question, we would love to help.

3. Create a file at examples/hello.rs and copy the below code snippet to it.

   // examples/hello.rs
   
   use ockam::{route, Context, Entity, Result, SecureChannels, TrustEveryonePolicy, Vault};
   
   #[ockam::node]
   async fn main(mut ctx: Context) -> Result<()> {
       // Create a Vault to safely store secret keys for Alice and Bob.
       let vault = Vault::create(&ctx)?;
   
       // Create an Entity to represent Bob.
       let mut bob = Entity::create(&ctx, &vault)?;
   
       // Create a secure channel listener for Bob that will wait for requests to
       // initiate an Authenticated Key Exchange.
       bob.create_secure_channel_listener("bob", TrustEveryonePolicy)?;
   
       // Create an entity to represent Alice.
       let mut alice = Entity::create(&ctx, &vault)?;
   
       // As Alice, connect to Bob's secure channel listener and perform an
       // Authenticated Key Exchange to establish an encrypted secure channel with Bob.
       let channel = alice.create_secure_channel("bob", TrustEveryonePolicy)?;
   
       // Send a message, ** THROUGH ** the secure channel,
       // to the "app" worker on the other side.
       //
       // This message will automatically get encrypted when it enters the channel
       // and decrypted just before it exits the channel.
       ctx.send(route![channel, "app"], "Hello Ockam!".to_string()).await?;
   
       // Wait to receive a message for the "app" worker and print it.
       let message = ctx.receive::<String>().await?;
       println!("App Received: {}", message); // should print "Hello Ockam!"
   
       // Stop all workers, stop the node, cleanup and return.
       ctx.stop().await
   }

4. Run the example

   cargo run --example hello
   

Congratulations on running your first Ockam program 🥳.

A lot happened when you ran this small example. It created a secure vault, spawned workers to represent entities, established a mutually authenticated channel and then routed a message through that channel. This involved running cryptographic protocols for generating keys, authenticating as an entity, performing an authenticated key exchange and exchanging messages with authenticated encryption.

To learn more about how we make these powerful cryptographic protocols simple to use, please have a look at our step-by-step guide where we introduce the building blocks in Ockam.

Here's a high-level view of the core ideas in Ockam.

To learn more please see our step-by-step guide.

• End-to-End Encryption with Rust: In this hands-on guide, we create two small Rust programs called Alice and Bob. Alice and Bob send each other messages, over the network, via a cloud service. They mutually authenticate each other and have a cryptographic guarantee that the integrity, authenticity, and confidentiality of their messages is protected end-to-end. 👉

• Step-by-Step Deep Dive: In this step-by-step guide we write many small rust programs to understand the various building blocks that make up Ockam. We dive into Node, Workers, Routing, Transport, Secure Channels and more. 👉

• End-to-End Encryption through Kafka: In this guide, we show two programs called Alice and Bob. Alice and Bob send each other messages, over the network, via a cloud service, through Kafka. They mutually authenticate each other and have a cryptographic guarantee that the integrity, authenticity, and confidentiality of their messages is protected end-to-end. The Kafka instance, the intermediary cloud service and attackers on the network are not be able to see or change the contents of en-route messages. The application data in Kafka is encrypted. 👉

The code in this repository is licensed under the terms of the Apache License 2.0.