Tooark.Securities 4.2.1

Tooark.Securities

Security library for .NET applications, providing AES cryptography and JWT authentication services with support for multiple algorithms.

🌍 Languages: 🇺🇸 English (this file) · 🇧🇷 Português

📦 Package Contents

Services

Interfaces

DTOs

Options

Extensions

🔧 Installation

dotnet add package Tooark.Securities

⚙️ Configuration

appsettings.json

To configure the security services, add the Jwt and Cryptography sections to your appsettings.json:

Example configuration for a JWT token with symmetric algorithms (uses Secret for signing and validation):

{
  "Jwt": {
    "Algorithm": "HS256",
    "Secret": "your-secret-key-with-at-least-32-characters",
    "Issuer": "your-application",
    "Audience": "your-clients",
    "ExpirationTime": 60
  }
}

Example configuration for a JWT token with asymmetric algorithms (PrivateKey required for signing, PublicKey required for validation):

{
  "Jwt": {
    "Algorithm": "RS256",
    "PrivateKey": "your-private-key-in-base64",
    "PublicKey": "your-public-key-in-base64",
    "Issuer": "your-application",
    "Audience": "your-clients",
    "ExpirationTime": 60
  }
}

Example configuration for AES cryptography:

{
  "Cryptography": {
    "Algorithm": "GCM",
    "Secret": "your-secret-key-with-32-characters"
  }
}

Or with a ready-made AES key in Base64 (recommended — the key is used directly, without derivation):

{
  "Cryptography": {
    "Algorithm": "GCM",
    "SecretBase64": "32-byte-key-in-base64"
  }
}

JwtOptions properties

Issuer/Issuers and Audience/Audiences add up: providing any of them turns on the validation of that field. When none is provided, the validation of that field is turned off. The audience parameter of Create and Validate/ValidateAsync takes precedence over the configuration.

PrivateKey and PublicKey accept both the raw Base64 and the full PEM: the -----BEGIN/END ... KEY----- delimiters and the line breaks are removed on assignment.

Example with multiple issuers and audiences:

{
  "Jwt": {
    "Algorithm": "ES256",
    "PublicKey": "your-public-key-in-base64",
    "Issuers": ["legacy-api", "new-api"],
    "Audiences": ["web-app", "mobile-app"],
    "ExpirationTime": 60
  }
}

CryptographyOptions properties

Secret or SecretBase64 is required. When both are provided, SecretBase64 takes precedence. SecretBase64 must represent exactly 32 bytes (AES-256) — invalid values fail at startup. Generate a key with Convert.ToBase64String(RandomNumberGenerator.GetBytes(32)). With Secret, the key is derived via SHA256 (kept for compatibility).

Program.cs

using Tooark.Securities.Injections;

var builder = WebApplication.CreateBuilder(args);

// Adds the security services
builder.Services.AddTooarkSecurities(builder.Configuration);

var app = builder.Build();

Or, to add only the JWT token service:

using Tooark.Securities.Injections;

var builder = WebApplication.CreateBuilder(args);

// Adds the security services
builder.Services.AddTooarkJwtToken(builder.Configuration);

var app = builder.Build();

Or, to add only the cryptography service:

using Tooark.Securities.Injections;

var builder = WebApplication.CreateBuilder(args);

// Adds the security services
builder.Services.AddTooarkCryptography(builder.Configuration);

var app = builder.Build();

🔐 JWT - Supported Algorithms

Symmetric Algorithms (HMAC)

The minimums follow RFC 7518 (HMAC key at least as long as the hash output) and are validated at startup (Options.Jwt.SecretTooShort). The size is measured in bytes (UTF-8): non-ASCII characters take more than one byte.

Asymmetric Algorithms (RSA)

Asymmetric Algorithms (ECDsa)

The default algorithm is ES256 when Algorithm is not provided. Unknown values throw (Options.Jwt.AlgorithmNotSupported) — in security configuration, an invalid algorithm is never silently replaced by another. Internally, creation and validation use the JsonWebTokenHandler (the current Microsoft.IdentityModel handler); UserTokenDto accepts both JsonWebToken and the legacy JwtSecurityToken.

🔒 Cryptography - Supported Algorithms

CBCUnsafe exists only to read old data encrypted with a zero IV: encrypting in this mode throws (Options.Cryptography.AlgorithmDecryptOnly). For new data, use GCM.

📝 Usage Examples

JWT - Creating and Validating a Token

Configuration with HMAC (Symmetric)

{
  "Jwt": {
    "Algorithm": "HS256",
    "Secret": "my-super-secure-secret-key-32chars",
    "Issuer": "my-api",
    "Audience": "my-clients",
    "ExpirationTime": 60
  }
}

Configuration with RSA (Asymmetric)

{
  "Jwt": {
    "Algorithm": "RS256",
    "PrivateKey": "MIIEvQIBADANBgkqh...base64-private-key...",
    "PublicKey": "MIIBIjANBgkqhkiG9w...base64-public-key...",
    "Issuer": "my-api",
    "Audience": "my-clients",
    "ExpirationTime": 60
  }
}

Creating a Token

public class AuthController : ControllerBase
{
    private readonly IJwtTokenService _jwtService;

    public AuthController(IJwtTokenService jwtService)
    {
        _jwtService = jwtService;
    }

    [HttpPost("login")]
    public IActionResult Login(LoginRequest request)
    {
        // Validate credentials...

        // Create the token data
        var tokenData = new JwtTokenDto(
            id: user.Id,
            login: user.Email,
            security: user.SecurityStamp
        );

        // Generate the token
        var token = _jwtService.Create(tokenData);

        return Ok(new { Token = token });
    }

    // With a custom audience and extra claims
    [HttpPost("login-custom")]
    public IActionResult LoginCustom(LoginRequest request)
    {
        var tokenData = new JwtTokenDto(user.Id, user.Email, user.SecurityStamp);

        var extraClaims = new[]
        {
            new Claim("role", "admin"),
            new Claim("department", "IT")
        };

        var token = _jwtService.Create(tokenData, audience: "mobile-app", extraClaims: extraClaims);

        return Ok(new { Token = token });
    }
}

Validating a Token

The Microsoft.IdentityModel handler exposes validation only asynchronously, so ValidateAsync is the direct path and Validate is the synchronous wrapper. In code that is already asynchronous, prefer ValidateAsync:

[HttpGet("validate")]
public async Task<IActionResult> ValidateTokenAsync([FromHeader] string authorization)
{
    var token = authorization.Replace("Bearer ", "");

    var result = await _jwtService.ValidateAsync(token);

    if (!string.IsNullOrEmpty(result.ErrorToken))
    {
        return Unauthorized(new { Error = result.ErrorToken });
    }

    return Ok(new { UserId = result.Id, Login = result.Login });
}

In synchronous code, the blocking overload delivers the same result:

[HttpGet("validate")]
public IActionResult ValidateToken([FromHeader] string authorization)
{
    var token = authorization.Replace("Bearer ", "");

    var result = _jwtService.Validate(token);

    if (!string.IsNullOrEmpty(result.ErrorToken))
    {
        return Unauthorized(new { Error = result.ErrorToken });
    }

    return Ok(new
    {
        UserId = result.Id,
        Login = result.Login,
        // Or using the helpers
        GuidId = result.GetGuidId,
        IntId = result.GetIntId
    });
}

Cryptography - Encrypt and Decrypt

Configuration

{
  "Cryptography": {
    "Algorithm": "GCM",
    "Secret": "my-secret-key-32-characters-long"
  }
}

Using ICryptographyService

public class DataProtectionService
{
    private readonly ICryptographyService _crypto;

    public DataProtectionService(ICryptographyService crypto)
    {
        _crypto = crypto;
    }

    public string ProtectSensitiveData(string plainText)
    {
        // Returns the encrypted text in Base64
        return _crypto.Encrypt(plainText);
    }

    public string UnprotectData(string encryptedText)
    {
        // Returns the original decrypted text
        return _crypto.Decrypt(encryptedText);
    }
}

Full Example

// Configure in Program.cs (registers ICryptographyService as a singleton)
builder.Services.AddTooarkCryptography(builder.Configuration);

// Use in the service
public class UserService
{
    private readonly ICryptographyService _crypto;

    public UserService(ICryptographyService crypto)
    {
        _crypto = crypto;
    }

    public void SaveUser(User user)
    {
        // Encrypt sensitive data before saving
        user.CreditCard = _crypto.Encrypt(user.CreditCard);
        user.SSN = _crypto.Encrypt(user.SSN);

        // Save to the database...
    }

    public User GetUser(int id)
    {
        var user = // Fetch from the database...

        // Decrypt sensitive data
        user.CreditCard = _crypto.Decrypt(user.CreditCard);
        user.SSN = _crypto.Decrypt(user.SSN);

        return user;
    }
}

🔑 Generating Keys

Key for HMAC (HS256/HS384/HS512)

# Generate a random 32-byte (256-bit) key for HS256
openssl rand -base64 32

# Generate a random 64-byte (512-bit) key for HS512
openssl rand -base64 64

RSA Keys (RS256/PS256)

# Generate a 2048-bit RSA private key
openssl genrsa -out private.pem 2048

# Extract the public key
openssl rsa -in private.pem -pubout -out public.pem

# Convert to the PKCS8 format (recommended)
openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in private.pem -out private_pkcs8.pem

# Get the key in Base64 (without headers)
cat private_pkcs8.pem | grep -v "BEGIN\|END" | tr -d '\n'
cat public.pem | grep -v "BEGIN\|END" | tr -d '\n'

ECDsa Keys (ES256/ES384/ES512)

# ES256 (P-256)
openssl ecparam -genkey -name prime256v1 -noout -out ec_private.pem
openssl ec -in ec_private.pem -pubout -out ec_public.pem

# ES384 (P-384)
openssl ecparam -genkey -name secp384r1 -noout -out ec_private.pem

# ES512 (P-521)
openssl ecparam -genkey -name secp521r1 -noout -out ec_private.pem

# Convert to PKCS8
openssl pkcs8 -topk8 -nocrypt -in ec_private.pem -out ec_private_pkcs8.pem

📋 Dependencies

🎯 Best Practices

JWT

1. Use asymmetric algorithms (RS/PS/ES) in production - Allows validating tokens without exposing the signing key
2. Configure ExpirationTime appropriately - Short-lived tokens are safer
3. Use Issuer and Audience - Prevents tokens from being misused across applications
4. Store keys in a Secret Manager - Never commit keys to source code

Cryptography

1. Prefer GCM over CBC - GCM provides built-in authentication
2. Never use CBCUnsafe for new data - Decrypt-only mode for compatibility with legacy systems
3. Prefer SecretBase64 with a random 32-byte key - The key is used directly, without derivation
4. Generate random keys - Use openssl rand -base64 32 or RandomNumberGenerator.GetBytes(32)

⚠️ Error Codes and Solutions

🪪 Contributing

Contributions are welcome! Feel free to open issues and pull requests in the Tooark.Securities repository.

📄 License

This project is licensed under the BSD 3-Clause License. See the LICENSE file for details.