LSL.Signing

This library provides a simple wrapper to quickly generate a signature for an object.

Quick start

Signing objects

The following examples use the GenerateSignature method that is defined as:

byte[] GenerateSignature(object source)

Using the default options a signature can be obtained with the following:

var signature = new ObjectSignerFactory()
    .Build()
    .GenerateSignature("test-string-object");

The previous example uses a primitive type but complex objects can also be signed:

/*
    This example relies on the definition of two classes:

    [Serializable]
    public class Test {
        public int Id { get; set; }
        public Inner InnerInstance { get; set; }
    }

    [Serializable]
    public class Inner {
        public int OtherId { get; set; }
        public string Name { get; set; }
    }
*/
var signature = new ObjectSignerFactory()
    .Build()
    .GenerateSignature(new Test {
        Id = 12,
        InnerInstance = new Inner {
            OtherId = 13,
            Name = "Als"
        }
    });

Verifying objects

Once we have a signature we can then verify an object using the Verify extension method:

bool Verify(
    this IObjectSigner source, 
    object signaturee, 
    byte[] expectedSignature)

Example:

var signer = new ObjectSignerFactory()
    .Build();

var signature = signer
    .GenerateSignature("test-string-object");

// Will be true
var verifyResullt1 = signer.Verify("test-string-object", signature);

// Will be false
var verifyResullt2 = signer.Verify("different-test-string-object", signature);

Configuration

Default settings

When the ObjectSignerFactory's Build method is called without passing in a delegate to configure the signer then it uses a BinaryFormatter to serialise the object then uses an instance of HMACSHA256 to calculate a hash as the signature:

var signer = new ObjectSignerFactory().Build();

Using a custom serialiser

Passing a delegate into the Build method allows for customisation of the signer's behaviour. The configuration object exposes the WithBinarySerialiser method to customise serlisation. It is defined as:

ObjectSignerBuilder WithBinarySerialiser(
    Func<object, byte[]> serialiser)

Example:

// The following code relies on the installation of the MessagePack nuget library 
//(https://www.nuget.org/packages/MessagePack/)
var signer = new ObjectSignerFactory()
    .Build(cfg => cfg.WithBinarySerialiser(MessagePackSerializer.Serialize));

Using a custom string seriliaser

The configuration object has an extension that allows us to customise serialisation to a string instead of a byte array. The method is defined as:

ObjectSignerBuilder WithStringBasedSerialiser(
    this ObjectSignerBuilder source, 
    Func<object, string> objectToStringSerialiser)

Example:

// This code snippet depends on the NetwonSoft.JSON nuget package for serialisation to a string 
//(https://www.nuget.org/packages/Newtonsoft.Json/)
var signer = new ObjectSignerFactory()
    .Build(cfg => cfg.WithStringBasedSerialiser(JsonConvert.SerializeObject));

Customisation of object signing

As with serialisation, we can provide a custom signer via the signer configuration method WithSignatureProvider:

ObjectSignerBuilder WithSignatureProvider(
    Func<byte[], byte[]> signatureProvider)

The following example uses a HMACSHA512 instance with a secret of [1,2,3] to for signature generation.

var signer = new ObjectSignerFactory()
    .Build(cfg => cfg.WithSignatureProvider(new HMACSHA512(new[] {1,2,3}).ComputeHash));

Registering a dispose method

IObjectSigner is derived from IDisposable. As such you can register a dispose delegate for when the IObjectSigner is disposed.

var algorithm = new HMACSHA256(new[] { 1, 2, 3 });
var signer = new ObjectSignerFactory()
    .Build(cfg => cfg
        .WithSignatureProvider(algorithmn.ComputeHash)
        .OnDispose(() => algorithm.Dispose())
    );

Signer extensions

Shortcut extensions are provided to quickly configure different sized HMAC instances that a signer should use.

WARNING: All HMAC-prefixed extensions register delegates for disposing of the HashAlgorithmn and as such the IObjectSigner should be disposed when finished with.

WithHmac256SignatureProvider

Definition:

ObjectSignerBuilder WithHmac256SignatureProvider(
    this ObjectSignerBuilder source, 
    byte[] secret)

Example:

using (var signer = new ObjectSignerFactory()
    .Build(cfg => cfg.WithHmac256SignatureProvider(new[] {1,2,3}))) 
{
    // do stuff with your object signer
}

WithHmac384SignatureProvider

Definition:

ObjectSignerBuilder WithHmac384SignatureProvider(
    this ObjectSignerBuilder source, 
    byte[] secret)

Example:

using (var signer = new ObjectSignerFactory()
    .Build(cfg => cfg.WithHmac384SignatureProvider(new[] {1,2,3}))) 
{
    // do stuff with your signer
}

WithHmac512SignatureProvider

Definition:

ObjectSignerBuilder WithHmac512SignatureProvider(
    this ObjectSignerBuilder source, 
    byte[] secret)

Example:

using (var signer = new ObjectSignerFactory()
    .Build(cfg => cfg.WithHmac512SignatureProvider(new[] {1,2,3}))) 
{
    // do stuff with your signer
}

alunacjones / lsl.signing Goto Github PK

lsl.signing's Introduction

LSL.Signing

Quick start

Signing objects

Verifying objects

Configuration

Default settings

Using a custom serialiser

Using a custom string seriliaser

Customisation of object signing

Registering a dispose method

Signer extensions

WithHmac256SignatureProvider

WithHmac384SignatureProvider

WithHmac512SignatureProvider

lsl.signing's People

Contributors

Watchers

Forkers

Recommend Projects

Recommend Topics

Recommend Org