Murphy.ByteString 4.0.3.29200

README

ByteString is a small utility library that provides a conceptually immutable byte string type with many convenient operations.

Installation

You can install ByteString via NuGet.

To build ByteString from source you will need an F# 6.0 compiler (or newer) and a .NET development environment. The .sln and .fsproj files in the source directories should be understood by .NET Core command line tools, MSBuild or IDEs such as VSCode, VisualStudio, or Rider.

Usage

ByteString is a library. Its central class is Murphy.ByteString.ByteString, which behaves a lot like System.String, only it contains bytes rather than unicode code points. Like with simple byte arrays, the contents of a byte string may be addressed by index, but they are thought to be immutable and a byte string can be used as a key for hashed or sorted collections, for example.

Here are some usage examples for the library:

#r "nuget: Murphy.ByteString, 4.0.3"
open System
open Murphy.ByteString

// Create from the UTF-8 representation of a string (any encoding is supported):
let b = ByteString.FromString("Hello world!\tHow are you?")

// Derive keys from a password:
let k, k' =
  use kdf = new Security.Cryptography.Rfc2898DeriveBytes("password", "salty stuff"B)
  kdf.GetByteString(64),
  kdf.GetByteString(64)

// Compare contents lexicographically:
printfn "k < b:  %b" <| (k < b)
printfn "k = k': %b" <| (k = k')

// Perform bitwise operations:
printfn "XOR(k, k'): %s" <| (k ^^^ k').ToHexadecimal()
printfn "Number of different bits (k, k'): %d" <| (k --- k')

// Compute cryptographic checksums:
printfn "Message digest: %s" <| b.GetHash("SHA256").ToHexadecimal()
printfn "HMAC          : %s" <| b.GetHmac("HMACSHA256", k).ToHexadecimal()

// Encrypt and authenticate data using best practices:
let box = b.BoxWith("AES/HMACSHA256", k)

// Interact with streams:
do
  use s = IO.File.Create("box.dat")
  s.Write(box)

// Or use even simpler convenience methods for files:
IO.File.ReadAllByteString("box.dat") = box
|> printfn "Still the same data? %b"

// Decrypt and authenticate data:
box.UnboxWith("AES/HMACSHA256", k)
  .ToStringUTF8()
|> printfn "Decrypted: %s"

// But not with the wrong key, of course:
match box.TryUnboxWith("AES/HMACSHA256", k') with
| Some b -> printfn "Decrypted even with the wrong key: %O" b
| None   -> printfn "Wrong key detected!"

// Format and interpret data in various ways:
Console.Write("""
b.ToEscaped():                       "{0}"B
b.ToBase64():                         {0:B}
k.ToHexadecimal().ToLower():          {1:x}
k.ToHexadecimal().ToUpper():          {1:X}
k.ToSpeak64():                        {1:S}
k.ToBigInteger(littleEndian = false): {1:D}
k.ToBigInteger(littleEndian = true):  {1:d}
""", b, k)

// Clear sensitive data
k.UnsafeClear()

// Encode and decode non-circular F# data structures in BARE format.
type Foo = {
  Bar : string
  Baz : Map<string, int * option<ByteString>>
}

let e = ByteString.FromBareMessage {
  Bar = "blah"
  Baz = Map.ofList [
    "oans", (42, None)
    "zwoa", (23, ByteString.FromArray[|1uy; 2uy; 3uy|] |> Some)
  ]
}

let d = e.ToBareMessage<Foo>()

Console.Write("""
encoded: {0:B}
decoded: {1}
""", e, d)

A variety of conversion operations, binary operators and standard interfaces are provided for byte strings. None of these modify the data represented by the instances they operate on.

However, the byte string type encapsulates a byte array and for efficiency, a few operations allow access to this raw array. These operations are marked with "unsafe" in their names and should be used with care.

Extra Modules

Ice

If you use

<PackageReference Include="Murphy.ByteString" Version="4.0.3" />
<PackageReference Include="zeroc.ice.net" Version="3.7.10" />

in your project, you may add

<Compile Include="$(ByteStringExtra)\ByteStringIce.fs" />

to get convenience methods for serialization / deserialization of Ice objects to / from byte strings.

Curve25519

If you use

<PackageReference Include="Murphy.ByteString" Version="4.0.3" />
<PackageReference Include="Rebex.Elliptic.Curve25519" Version="1.2.1" />
<PackageReference Include="Rebex.Elliptic.Ed25519" Version="1.2.1" />

in your project, you may add

<Compile Include="$(ByteStringExtra)\ByteStringCurve25519.fs" />

to get convenience methods for key agreement and asymmetric signatures using byte strings as key blobs.