fluencelabs/rust-libp2p
1
0
Fork 0
mirror of https://github.com/fluencelabs/rust-libp2p synced 2025-05-03 06:32:16 +00:00
Code Issues Projects Releases Wiki Activity

Merge pull request #68 from tomaka/secio-docs

Browse Source 
Add documentation and README for secio
This commit is contained in:
Pierre Krieger 2017-12-15 16:26:45 +01:00 committed by GitHub
commit f0bd19d848
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 110 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
libp2p-secio/Cargo.toml
View File

@ -16,4 +16,5 @@ tokio-io = "0.1.0"
untrusted = "0.6.0"
[dev-dependencies]
libp2p-tcp-transport = { path = "../libp2p-tcp-transport" }
tokio-core = "0.1.6"

57
libp2p-secio/README.md Normal file
View File

@ -0,0 +1,57 @@
The `secio` protocol is a middleware that will encrypt and decrypt communications going
through a socket (or anything that implements `AsyncRead + AsyncWrite`).
# Connection upgrade
The `SecioConfig` struct implements the `ConnectionUpgrade` trait. You can apply it over a
`Transport` by using the `with_upgrade` method. The returned object will also implement
`Transport` and will automatically apply the secio protocol over any connection that is opened
through it.
```rust
extern crate futures;
extern crate tokio_core;
extern crate tokio_io;
extern crate libp2p_swarm;
extern crate libp2p_secio;
extern crate libp2p_tcp_transport;
use futures::Future;
use libp2p_secio::{SecioConfig, SecioKeyPair};
use libp2p_swarm::{Multiaddr, Transport};
use libp2p_tcp_transport::TcpConfig;
use tokio_core::reactor::Core;
use tokio_io::io::write_all;
let mut core = Core::new().unwrap();
let transport = TcpConfig::new(core.handle())
.with_upgrade({
# let private_key = b"";
//let private_key = include_bytes!("test-private-key.pk8");
# let public_key = vec![];
//let public_key = include_bytes!("test-public-key.der").to_vec();
SecioConfig {
// See the documentation of `SecioKeyPair`.
key: SecioKeyPair::rsa_from_pkcs8(private_key, public_key).unwrap(),
}
});
let future = transport.dial(Multiaddr::new("/ip4/127.0.0.1/tcp/12345").unwrap())
.unwrap_or_else(|_| panic!("Unable to dial node"))
.and_then(|connection| {
// Sends "hello world" on the connection, will be encrypted.
write_all(connection, "hello world")
});
core.run(future).unwrap();
```
# Manual usage
> **Note**: You are encouraged to use `SecioConfig` as described above.
You can add the `secio` layer over a socket by calling `SecioMiddleware::handshake()`. This
method will perform a handshake with the host, and return a future that corresponds to the
moment when the handshake succeeds or errored. On success, the future produces a
`SecioMiddleware` that implements `Sink` and `Stream` and can be used to send packets of data.

57
libp2p-secio/src/lib.rs
View File

@ -18,19 +18,66 @@
// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
// DEALINGS IN THE SOFTWARE.
//! # Implementation of the `secio` protocol.
//!
//! The `secio` protocol is a middleware that will encrypt and decrypt communications going
//! through a socket (or anything that implements `AsyncRead + AsyncWrite`).
//!
//! # Connection upgrade
//!
//! The `SecioConfig` struct implements the `ConnectionUpgrade` trait. You can apply it over a
//! `Transport` by using the `with_upgrade` method. The returned object will also implement
//! `Transport` and will automatically apply the secio protocol over any connection that is opened
//! through it.
//!
//! ```no_run
//! extern crate futures;
//! extern crate tokio_core;
//! extern crate tokio_io;
//! extern crate libp2p_swarm;
//! extern crate libp2p_secio;
//! extern crate libp2p_tcp_transport;
//!
//! # fn main() {
//! use futures::Future;
//! use libp2p_secio::{SecioConfig, SecioKeyPair};
//! use libp2p_swarm::{Multiaddr, Transport};
//! use libp2p_tcp_transport::TcpConfig;
//! use tokio_core::reactor::Core;
//! use tokio_io::io::write_all;
//!
//! let mut core = Core::new().unwrap();
//!
//! let transport = TcpConfig::new(core.handle())
//! .with_upgrade({
//! # let private_key = b"";
//! //let private_key = include_bytes!("test-private-key.pk8");
//! # let public_key = vec![];
//! //let public_key = include_bytes!("test-public-key.der").to_vec();
//! SecioConfig {
//! // See the documentation of `SecioKeyPair`.
//! key: SecioKeyPair::rsa_from_pkcs8(private_key, public_key).unwrap(),
//! }
//! });
//!
//! let future = transport.dial(Multiaddr::new("/ip4/127.0.0.1/tcp/12345").unwrap())
//! .unwrap_or_else(|_| panic!("Unable to dial node"))
//! .and_then(|connection| {
//! // Sends "hello world" on the connection, will be encrypted.
//! write_all(connection, "hello world")
//! });
//!
//! core.run(future).unwrap();
//! # }
//! ```
//!
//! # Manual usage
//!
//! > **Note**: You are encouraged to use `SecioConfig` as described above.
//!
//! You can add the `secio` layer over a socket by calling `SecioMiddleware::handshake()`. This
//! method will perform a handshake with the host, and return a future that corresponds to the
//! moment when the handshake succeeds or errored. On success, the future produces a
//! `SecioMiddleware` that implements `Sink` and `Stream` and can be used to send packets of data.
//!
//! However for integration with the rest of `libp2p` you are encouraged to use the
//! `SecioConfig` struct instead. This struct implements the `ConnectionUpgrade` trait and
//! will automatically apply secio on any incoming or outgoing connection.
extern crate bytes;
extern crate crypto;