Tooark.Securities 4.0.1

Tooark.Securities

Biblioteca de segurança para aplicações .NET, fornecendo serviços de criptografia AES e autenticação JWT com suporte a múltiplos algoritmos.

📦 Conteúdo do Pacote

Serviços

Interfaces

DTOs

Options

Extensions

🔧 Instalação

dotnet add package Tooark.Securities

⚙️ Configuração

appsettings.json

Para configurar os serviços de segurança, adicione as seções Jwt e Cryptography no seu arquivo appsettings.json:

Configuração exemplo para token JWT com algoritmos simétricos (utiliza Secret para assinatura e validação):

{
  "Jwt": {
    "Algorithm": "HS256",
    "Secret": "sua-chave-secreta-com-pelo-menos-32-caracteres",
    "Issuer": "sua-aplicacao",
    "Audience": "seus-clientes",
    "ExpirationTime": 60
  }
}

Configuração exemplo para token JWT com algoritmos assimétricos (PrivateKey obrigatória para assinatura, PublicKey obrigatória para validação):

{
  "Jwt": {
    "Algorithm": "RS256",
    "PrivateKey": "sua-chave-privada-em-base64",
    "PublicKey": "sua-chave-publica-em-base64",
    "Issuer": "sua-aplicacao",
    "Audience": "seus-clientes",
    "ExpirationTime": 60
  }
}

Configuração exemplo para criptografia AES:

{
  "Cryptography": {
    "Algorithm": "GCM",
    "Secret": "sua-chave-secreta-com-32-caracteres"
  }
}

Ou com chave AES pronta em Base64 (recomendado — a chave é usada diretamente, sem derivação):

{
  "Cryptography": {
    "Algorithm": "GCM",
    "SecretBase64": "chave-de-32-bytes-em-base64"
  }
}

Propriedades de JwtOptions

Issuer/Issuers e Audience/Audiences se somam: informar qualquer um deles liga a validação do respectivo campo. Quando nenhum é informado, a validação daquele campo é desligada. O parâmetro audience de Create e Validate/ValidateAsync tem prioridade sobre a configuração.

PrivateKey e PublicKey aceitam tanto o Base64 puro quanto o PEM completo: os delimitadores -----BEGIN/END ... KEY----- e as quebras de linha são removidos ao atribuir.

Exemplo com múltiplos emissores e destinatários:

{
  "Jwt": {
    "Algorithm": "ES256",
    "PublicKey": "sua-chave-publica-em-base64",
    "Issuers": ["api-legada", "api-nova"],
    "Audiences": ["app-web", "app-mobile"],
    "ExpirationTime": 60
  }
}

Propriedades de CryptographyOptions

É obrigatório informar Secret ou SecretBase64. Quando ambos são informados, SecretBase64 tem prioridade. O SecretBase64 deve representar exatamente 32 bytes (AES-256) — valores inválidos falham no startup. Gere uma chave com Convert.ToBase64String(RandomNumberGenerator.GetBytes(32)). Com Secret, a chave é derivada via SHA256 (mantido por compatibilidade).

Program.cs

using Tooark.Securities.Injections;

var builder = WebApplication.CreateBuilder(args);

// Adiciona os serviços de segurança
builder.Services.AddTooarkSecurities(builder.Configuration);

var app = builder.Build();

Ou, para adicionar apenas o serviço de token JWT:

using Tooark.Securities.Injections;

var builder = WebApplication.CreateBuilder(args);

// Adiciona os serviços de segurança
builder.Services.AddTooarkJwtToken(builder.Configuration);

var app = builder.Build();

Ou, para adicionar apenas o serviço de criptografia:

using Tooark.Securities.Injections;

var builder = WebApplication.CreateBuilder(args);

// Adiciona os serviços de segurança
builder.Services.AddTooarkCryptography(builder.Configuration);

var app = builder.Build();

🔐 JWT - Algoritmos Suportados

Algoritmos Simétricos (HMAC)

Os mínimos seguem a RFC 7518 (chave HMAC com ao menos o tamanho da saída do hash) e são validados no startup (Options.Jwt.SecretTooShort). O tamanho é medido em bytes (UTF-8): caracteres não-ASCII ocupam mais de um byte.

Algoritmos Assimétricos (RSA)

Algoritmos Assimétricos (ECDsa)

O algoritmo padrão é ES256 quando Algorithm não é informado. Valores desconhecidos lançam exceção (Options.Jwt.AlgorithmNotSupported) — em configuração de segurança, um algoritmo inválido nunca é substituído silenciosamente por outro. Internamente, criação e validação usam o JsonWebTokenHandler (handler atual da Microsoft.IdentityModel); o UserTokenDto aceita tanto JsonWebToken quanto o legado JwtSecurityToken.

🔒 Criptografia - Algoritmos Suportados

CBCUnsafe existe apenas para ler dados antigos criptografados com IV zero: criptografar neste modo lança exceção (Options.Cryptography.AlgorithmDecryptOnly). Para novos dados, use GCM.

📝 Exemplos de Uso

JWT - Criação e Validação de Token

Configuração com HMAC (Simétrico)

{
  "Jwt": {
    "Algorithm": "HS256",
    "Secret": "minha-chave-secreta-super-segura-32chars",
    "Issuer": "minha-api",
    "Audience": "meus-clientes",
    "ExpirationTime": 60
  }
}

Configuração com RSA (Assimétrico)

{
  "Jwt": {
    "Algorithm": "RS256",
    "PrivateKey": "MIIEvQIBADANBgkqh...chave-privada-base64...",
    "PublicKey": "MIIBIjANBgkqhkiG9w...chave-publica-base64...",
    "Issuer": "minha-api",
    "Audience": "meus-clientes",
    "ExpirationTime": 60
  }
}

Criando um Token

public class AuthController : ControllerBase
{
    private readonly IJwtTokenService _jwtService;

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

    [HttpPost("login")]
    public IActionResult Login(LoginRequest request)
    {
        // Validar credenciais...

        // Criar dados do token
        var tokenData = new JwtTokenDto(
            id: user.Id,
            login: user.Email,
            security: user.SecurityStamp
        );

        // Gerar token
        var token = _jwtService.Create(tokenData);

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

    // Com audience customizada e claims extras
    [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: "app-mobile", extraClaims: extraClaims);

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

Validando um Token

O handler da Microsoft.IdentityModel expõe a validação apenas de forma assíncrona, então ValidateAsync é o caminho direto e Validate é o encapsulamento síncrono. Em código que já é assíncrono, prefira 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 });
}

Em código síncrono, a sobrecarga bloqueante entrega o mesmo resultado:

[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,
        // Ou usando helpers
        GuidId = result.GetGuidId,
        IntId = result.GetIntId
    });
}

Criptografia - Encrypt e Decrypt

Configuração

{
  "Cryptography": {
    "Algorithm": "GCM",
    "Secret": "minha-chave-secreta-32-caracteres"
  }
}

Usando ICryptographyService

public class DataProtectionService
{
    private readonly ICryptographyService _crypto;

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

    public string ProtectSensitiveData(string plainText)
    {
        // Retorna texto criptografado em Base64
        return _crypto.Encrypt(plainText);
    }

    public string UnprotectData(string encryptedText)
    {
        // Retorna texto original descriptografado
        return _crypto.Decrypt(encryptedText);
    }
}

Exemplo Completo

// Configurar no Program.cs (registra ICryptographyService como singleton)
builder.Services.AddTooarkCryptography(builder.Configuration);

// Usar no serviço
public class UserService
{
    private readonly ICryptographyService _crypto;

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

    public void SaveUser(User user)
    {
        // Criptografar dados sensíveis antes de salvar
        user.CreditCard = _crypto.Encrypt(user.CreditCard);
        user.SSN = _crypto.Encrypt(user.SSN);

        // Salvar no banco...
    }

    public User GetUser(int id)
    {
        var user = // Buscar do banco...

        // Descriptografar dados sensíveis
        user.CreditCard = _crypto.Decrypt(user.CreditCard);
        user.SSN = _crypto.Decrypt(user.SSN);

        return user;
    }
}

🔑 Gerando Chaves

Chave para HMAC (HS256/HS384/HS512)

# Gerar chave aleatória de 32 bytes (256 bits) para HS256
openssl rand -base64 32

# Gerar chave aleatória de 64 bytes (512 bits) para HS512
openssl rand -base64 64

Chaves RSA (RS256/PS256)

# Gerar chave privada RSA de 2048 bits
openssl genrsa -out private.pem 2048

# Extrair chave pública
openssl rsa -in private.pem -pubout -out public.pem

# Converter para formato PKCS8 (recomendado)
openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in private.pem -out private_pkcs8.pem

# Obter chave em Base64 (sem headers)
cat private_pkcs8.pem | grep -v "BEGIN\|END" | tr -d '\n'
cat public.pem | grep -v "BEGIN\|END" | tr -d '\n'

Chaves ECDsa (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

# Converter para PKCS8
openssl pkcs8 -topk8 -nocrypt -in ec_private.pem -out ec_private_pkcs8.pem

📋 Dependências

🎯 Boas Práticas

JWT

1. Use algoritmos assimétricos (RS/PS/ES) em produção - Permite validar tokens sem expor a chave de assinatura
2. Configure ExpirationTime apropriadamente - Tokens de curta duração são mais seguros
3. Use Issuer e Audience - Previne uso indevido de tokens entre aplicações
4. Armazene chaves em Secret Manager - Nunca commite chaves no código fonte

Criptografia

1. Prefira GCM sobre CBC - GCM fornece autenticação integrada
2. Nunca use CBCUnsafe para novos dados - Modo somente-descriptografia para compatibilidade com sistemas legados
3. Prefira SecretBase64 com chave aleatória de 32 bytes - A chave é usada diretamente, sem derivação
4. Gere chaves aleatórias - Use openssl rand -base64 32 ou RandomNumberGenerator.GetBytes(32)

⚠️ Códigos de Erro e Soluções

🪪 Contribuição

Contribuições são bem-vindas! Sinta-se à vontade para abrir issues e pull requests no repositório Tooark.Securities.

📄 Licença

Este projeto está licenciado sob a licença BSD 3-Clause. Veja o arquivo LICENSE para mais detalhes.