ssh-encoding: add derive feature

Adds an optional feature that re-exports `ssh-derive` macros and exposes
a documentation module with examples. The examples also serve as tests.

Also adds tests for the derive feature in the form of declaring various
structs and enums and asserting that encoding/decoding works as expected.

Author: tsurdevson

Cargo.lock

@@ -4,7 +4,7 @@
 //! Custom derive support for the [`ssh-encoding`] crate.
 //!
 //! Note that this crate shouldn't be used directly, but instead accessed
-//! by using the `derive` feature of the `der` crate, which re-exports this crate's
+//! by using the `derive` feature of the [`ssh-encoding`] crate, which re-exports this crate's
 //! macros from the toplevel.
 //!
 //! [`ssh-encoding`]: ../ssh-encoding

ssh-derive/src/lib.rs

@@ -20,6 +20,7 @@ base64ct = { version = "1.7", optional = true }
 bytes = { version = "1", optional = true, default-features = false }
 digest = { version = "=0.11.0-pre.9", optional = true, default-features = false }
 pem-rfc7468 = { version = "1.0.0-rc.2", optional = true }
+ssh-derive = { version = "0.0.1-alpha", optional = true, path = "../ssh-derive" }
 
 [dev-dependencies]
 hex-literal = "0.4.1"
@@ -30,6 +31,7 @@ alloc = ["base64ct?/alloc", "pem-rfc7468?/alloc"]
 base64 = ["dep:base64ct"]
 bytes = ["alloc", "dep:bytes"]
 pem = ["base64", "dep:pem-rfc7468"]
+derive = ["ssh-derive"]
 
 [package.metadata.docs.rs]
 all-features = true

ssh-encoding/Cargo.toml

@@ -0,0 +1,64 @@
+//! # Deriving [`Encode`] and [`Decode`]
+//!
+//! The traits [`Encode`] and [`Decode`] can be derived for any struct or enum where all its fields
+//! implement [`Encode`] and [`Decode`].
+//!
+//! [`Encode`]: [crate::Encode]
+//! [`Decode`]: [crate::Decode]
+//! ## Example
+//!
+//! Here is an example of how you could define a handful of the SSH message types.
+//! ```
+//! use ssh_encoding::{Decode, Encode};
+//!
+//! #[derive(Debug, PartialEq, Encode, Decode)]
+//! #[repr(u8)]
+//! enum Message {
+//!     Disconnect {
+//!         reason_code: u32,
+//!         description: String,
+//!         language_tag: String,
+//!     } = 1,
+//!     EcdhInit {
+//!         client_public_key: Vec<u8>,
+//!     } = 30,
+//!     EcdhReply {
+//!         host_key: HostKey,
+//!         server_public_key: Vec<u8>,
+//!         #[ssh(length_prefixed)]
+//!         host_signature: HostSignature,
+//!     } = 31,
+//! }
+//!
+//! #[derive(Debug, PartialEq, Encode, Decode)]
+//! #[ssh(length_prefixed)]
+//! struct HostKey {
+//!     key_type: String,
+//!     ecdsa_curve_identifier: String,
+//!     ecdsa_public_key: Vec<u8>,
+//! }
+//!
+//! #[derive(Debug, PartialEq, Encode, Decode)]
+//! struct HostSignature {
+//!     signature_type: String,
+//!     signature: Vec<u8>,
+//! }
+//!
+//! let message = Message::EcdhReply {
+//!     host_key: HostKey {
+//!         key_type: "ecdsa-sha2-nistp256".into(),
+//!         ecdsa_curve_identifier: "nistp256".into(),
+//!         ecdsa_public_key: vec![0x01, 0x02, 0x03],
+//!     },
+//!     server_public_key: vec![0x04, 0x05, 0x06],
+//!     host_signature: HostSignature {
+//!         signature_type: "ecdsa-sha2-nistp256".into(),
+//!         signature: vec![0x07, 0x08, 0x09],
+//!     },
+//! };
+//!
+//! let encoded = message.encode_vec().unwrap();
+//! assert_eq!(&encoded[..13], &[31, 0, 0, 0, 42, 0, 0, 0, 19, 101, 99, 100, 115]);
+//! let decoded = Message::decode(&mut &encoded[..]).unwrap();
+//! assert_eq!(message, decoded);
+//! ```

ssh-encoding/src/derive.rs

@@ -62,3 +62,8 @@ pub use digest;
 
 #[cfg(feature = "pem")]
 pub use crate::pem::{DecodePem, EncodePem};
+
+#[cfg(feature = "derive")]
+pub use ssh_derive::{Decode, Encode};
+#[cfg(feature = "derive")]
+pub mod derive;