Crate hmac_serialiser

HMAC Signer

hmac-serialiser is a Rust library for generating and verifying HMAC signatures for secure data transmission.

Regarding the cryptographic implementations, you can choose which implementations to use from via the features flag in the Cargo.toml file:

• rust_crypto (default)
  • the underlying SHA1, SHA2, HMAC, and HKDF implementations are by RustCrypto.
• ring
  • The underlying SHA1, SHA2, HMAC, and HKDF implementations are from the ring crate.

Additionally, the data serialisation and de-serialisation uses the serde crate and the signed data is then encoded or decoded using the base64 crate.

License

This library is licensed under the MIT license.

Features

• Supports various encoding schemes for signatures.
• Flexible HMAC signer logic for custom data types.
• Provides a convenient interface for signing and verifying data.

Example

use hmac_serialiser::{Encoder, HmacSigner, KeyInfo, Payload, Algorithm};
use serde::{Serialize, Deserialize};

#[derive(Serialize, Deserialize, Debug)]
struct UserData {
    // Add your data fields here
    username: String,
    email: String,
}

impl Payload for UserData {
    fn get_exp(&self) -> Option<chrono::DateTime<chrono::Utc>> {
        // Add logic to retrieve expiration time if needed
        None
    }
}

fn main() {
    // Define your secret key, salt, and optional info
    let key_info = KeyInfo {
        key: b"your_secret_key".to_vec(),
        salt: b"your_salt".to_vec(),
        info: vec![], // empty info
    };

    // Initialize the HMAC signer
    let signer = HmacSigner::new(key_info, Algorithm::SHA256, Encoder::UrlSafeNoPadding);

    // Serialize your data
    let user_data = UserData {
        username: "user123".to_string(),
        email: "user123@example.com".to_string(),
    };

    // Sign the data (safe to use by clients)
    let token = signer.sign(&user_data);
    println!("Token: {}", token);
     
    // Verify the token given by the client
    let verified_data: UserData = signer.unsign(&token)
        .expect("Failed to verify token");
    println!("Verified data: {:?}", verified_data);
}

Supported Encoders

• Standard: Standard base64 encoding.
• UrlSafe: URL-safe base64 encoding.
• StandardNoPadding: Standard base64 encoding without padding.
• UrlSafeNoPadding: URL-safe base64 encoding without padding. (Default)

Supported HMAC Algorithms

• SHA1
• SHA256 (Default)
• SHA384
• SHA512

Note: Although SHA1 is cryptographically broken, HMAC-SHA1 is not used for integrity checks like file hash checks. Therefore, it is still considered secure to use HMAC-SHA1 to verify the authenticity of a given payload. However, it is still recommended to choose a stronger hash function like SHA256 or even SHA512.

Traits

• Payload: A trait for data structures that can be signed and verified.

Errors

Errors are represented by the Error enum, which includes:

• InvalidInput: Invalid input payload.
• InvalidSignature: Invalid signature provided.
• InvalidPayload: Invalid payload structure when de-serialising valid payload
• InvalidToken: Invalid token provided.
• HkdfExpandError: Error during key expansion.
• HkdfFillError: Error during key filling.
• TokenExpired: Token has expired.

Contributing

Contributions are welcome! Feel free to open issues and pull requests on GitHub.

Re-exports

pub use algorithm::Algorithm;

pub use errors::Error;

Modules

algorithm

errors

hkdf

Structs

HmacSigner

A struct that holds the HMAC signer logic.

KeyInfo

A struct that holds the key information required for key expansion.

Enums

Encoder

An enum for defining the encoding scheme for the payload and the signature.

Constants

DELIM

Traits

Payload

A trait for custom payload types that can be signed and verified.