Paseto.Core 1.1.0

Paseto.NET, a Paseto (Platform-Agnostic Security Tokens) implementation for .NET

Features

PASETO protocols

PASERK extension

Installation

Install the Paseto.Core NuGet package from the .NET CLI using:

dotnet add package Paseto.Core

or from the NuGet package manager:

Install-Package Paseto.Core

Usage

PASETO

The library exposes a Fluent API with several method overloads found in Use(), WithKey(), AddClaim(), AddFooter() and so on to provide the flexibility needed for encoding and decoding PASETO tokens and also for generating the required symmetric or asymmetric key pairs. However, you can use the Protocols and Handlers directly if you like.

Below are a couple of examples for the most common use cases:

Generating a Symmetric Key

var pasetoKey = new PasetoBuilder().Use(version, Purpose.Local)
                                   .GenerateSymmetricKey();

Generating an Asymmetric Key Pair

var pasetoKey = new PasetoBuilder().Use(version, Purpose.Public)
                                   .GenerateAsymmetricKeyPair(seed);

NOTE: A seed is not required for protocol v1.

Generating a Token

var token = new PasetoBuilder().Use(version, purpose)
                               .WithKey(key)
                               .AddClaim("data", "this is a secret message")
                               .Issuer("https://github.com/daviddesmet/paseto-dotnet")
                               .Subject(Guid.NewGuid().ToString())
                               .Audience("https://paseto.io")
                               .NotBefore(DateTime.UtcNow.AddMinutes(5))
                               .IssuedAt(DateTime.UtcNow)
                               .Expiration(DateTime.UtcNow.AddHours(1))
                               .TokenIdentifier("123456ABCD")
                               .AddFooter("arbitrary-string-that-isn't-json")
                               .Encode();

Decoding a Token

var result = new PasetoBuilder().Use(version, purpose)
                                .WithKey(key)
                                .Decode(token);

Or validate the token's payload while decoding (the header and signature is always validated):

var valParams = new PasetoTokenValidationParameters
{
    ValidateLifetime = true,
    ValidateAudience = true,
    ValidateIssuer = true,
    ValidAudience = "https://paseto.io",
    ValidIssuer = "https://github.com/daviddesmet/paseto-dotnet"
};

var result = new PasetoBuilder().Use(version, purpose)
                                .WithKey(key)
                                .Decode(token, valParams);

PASERK

The library also provides the PASERK extension for encoding and decoding a key.

A serialized key in PASERK has the format:

k[version].[type].[data]

Encoding a Key

var paserk = Paserk.Encode(pasetoKey, type);

Decoding a Key

var key = Paserk.Decode(paserk);

Roadmap

• Add support for remaining PASERK types and its operations.
• Add support for version detection when decoding.
• Add support for custom payload validation rules.
• Improve documentation.
• Remove dependency on JSON.NET.

Test Coverage

• Includes the mandatory test vectors for PASETO and PASERK.

Cryptography

• Uses Ed25519 (EdDSA over Curve25519) algorithm from CodesInChaos Chaos.NaCl cryptography library.
• Uses Blake2b cryptographic hash function from Konscious.Security.Cryptography repository.
• Uses AES-256-CTR, ECDSA over P-384 algorithms from Bouncy Castle cryptography library.
• Uses XChaCha20-Poly1305 AEAD from NaCl.Core repository.

Learn More

• PASETO (Platform-Agnostic SEcurity TOkens) is a specification and reference implementation for secure stateless tokens.
• PASERK (Platform-Agnostic SERialized Keys) is an extension to PASETO that provides key-wrapping and serialization.