Improve documentation

[daviddesmet]

Improve the documentation, especially around the use of the keys.

See here for an example.

Excerpt:

...

I'm using Paseto.Core Nuget from https://github.com/daviddesmet/paseto-dotnet, and I'm trying to create v4 public PASETO token with this. My code:

public async Task<TokenResponse> GenerateAsync(Client client, TokenRequest tokenRequest, string issuer, string audience)
    {
        var privateEd25519Key = await File.ReadAllBytesAsync("private.pem");

        var pasetoToken = new PasetoBuilder()
            .Use(ProtocolVersion.V4, Purpose.Public)
            .WithKey(privateEd25519Key, Encryption.AsymmetricSecretKey)
            .Issuer(issuer)
            .Subject(tokenRequest.ClientId)
            .Audience(audience)
            .NotBefore(DateTime.UtcNow)
            .IssuedAt(DateTime.UtcNow)
            .Expiration(DateTime.UtcNow.AddSeconds(client.AccessTokenLifetime))
            .TokenIdentifier(Guid.NewGuid().ToString())
            .AddClaim("client_id", tokenRequest.ClientId)
            .AddClaim("scopes", tokenRequest.Scopes)
            .Encode();

        return new TokenResponse
        {
            AccessToken = pasetoToken,
            Lifetime = client.AccessTokenLifetime,
            Scope = tokenRequest.Scopes
        };
    }
}

Besides, due to the rather unclear documentation, I don't know if I'm really creating a token signed with a private key or encrypted.

...

Here is my solution:

public async Task<TokenResponse> GenerateAsync(Client client, TokenRequest tokenRequest, string issuer, string audience)
    {
        var ed25519pkcs8 = await File.ReadAllTextAsync("private.pem");

        var privatePemReader = new PemReader(new StringReader(ed25519pkcs8));
        var ed25519pkcs8Parameters = (Ed25519PrivateKeyParameters)privatePemReader.ReadObject();
        ISigner signer = new Ed25519Signer();
        signer.Init(true, ed25519pkcs8Parameters);

        var pasetoToken = new PasetoBuilder()
            .Use(ProtocolVersion.V4, Purpose.Public)
            .WithKey(signer.GenerateSignature(), Encryption.AsymmetricSecretKey)
            .Issuer(issuer)
            .Subject(tokenRequest.ClientId)
            .Audience(audience)
            .NotBefore(DateTime.UtcNow)
            .IssuedAt(DateTime.UtcNow)
            .Expiration(DateTime.UtcNow.AddSeconds(client.AccessTokenLifetime))
            .TokenIdentifier(Guid.NewGuid().ToString())
            .AddClaim("client_id", tokenRequest.ClientId)
            .AddClaim("scopes", tokenRequest.Scopes)
            .Encode();

        return new TokenResponse
        {
            AccessToken = pasetoToken,
            Lifetime = client.AccessTokenLifetime,
            Scope = tokenRequest.Scopes
        };
    }

It turned out that WithKey doesn't support PEM files, so you had to get the private key out of PKCS#8.