...
Eroare ASP.NET Core · Autentificare, JWT, CORS și teste

System.ArgumentOutOfRangeException: IDX10720: Unable to create KeyedHashAlgorithm for algorithm 'HS256', the key size must be greater than: '256' bits, key has '128' bits. (Parameter 'keyBytes')

Pe scurt

Cheia simetrică folosită pentru HS256 e prea scurtă: trebuie să aibă cel puțin 256 de biți, adică 32 de octeți. Folosește o cheie secretă aleatoare de minim 32 de caractere ASCII (ideal generată și păstrată în configurare sau într-un vault).

Explicat de Tudor Andrei Dumitrescu, Senior Software Developer, fondatorul Academiei ProgramatorilorActualizat la

Ce înseamnă

Algoritmul HS256 (HMAC cu SHA-256) semnează tokenul cu o cheie simetrică. Începând cu versiunile recente ale Microsoft.IdentityModel.Tokens (folosite de .NET 8), biblioteca refuză cheile mai scurte decât dimensiunea hash-ului: pentru HS256, minimum 256 de biți (32 de octeți), pentru HS384 minim 384 de biți, pentru HS512 minim 512 biți.

Mesajul îți spune exact cât are cheia ta: key has '128' bits înseamnă 16 octeți. Numărul de octeți e cel obținut din Encoding.UTF8.GetBytes(cheie): un caracter ASCII ocupă un octet, unul cu diacritice doi.

Eroarea apare fie la generarea tokenului (în endpoint-ul de login), fie la validarea primei cereri cu token, când handler-ul încearcă să verifice semnătura. Tutorialele vechi foloseau chei ca "secret" sau "cheia-mea-secreta", care mergeau cu versiunile mai vechi ale bibliotecii; după actualizare, aceleași aplicații pică.

De ce apare: cauzele frecvente

1Cheie prea scurtă

Greșit
C#
new SymmetricSecurityKey(Encoding.UTF8.GetBytes("cheie-scurta-123"))
Corect
C#
new SymmetricSecurityKey(Encoding.UTF8.GetBytes(builder.Configuration["Jwt:Cheie"]!))
// Jwt:Cheie are cel puțin 32 de caractere aleatoare

16 caractere ASCII înseamnă 128 de biți; e nevoie de minim 32 de caractere.

2Cheie generată corect

Greșit
C#
"parola123parola123"
Corect
C#
// o singură dată, în consolă:
// Convert.ToBase64String(RandomNumberGenerator.GetBytes(32))
new SymmetricSecurityKey(Convert.FromBase64String(config["Jwt:CheieBase64"]!))

O cheie de 32 de octeți aleatori, salvată ca Base64, e și suficient de lungă, și greu de ghicit.

3Algoritm mai puternic cu aceeași cheie

Greșit
C#
new SigningCredentials(cheie, SecurityAlgorithms.HmacSha512) // cheie de 32 de octeți
Corect
C#
new SigningCredentials(cheie, SecurityAlgorithms.HmacSha256)

HS512 cere 64 de octeți; dacă păstrezi cheia de 32, folosește HS256.

Repară tu

Repară eroarea, direct în pagină

Aplicația nu pornește cererile protejate: IDX10720: Unable to create KeyedHashAlgorithm for algorithm 'HS256', the key size must be greater than: '256' bits, key has '128' bits.. Înlocuiește cheia cu o-cheie-secreta-de-cel-putin-32-de-octeti, ca GET /profil să funcționeze pentru utilizatorul autentificat.

Codul care dă eroarea
C#
using System.Security.Claims;
using System.Text;
using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.IdentityModel.Tokens;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme).AddJwtBearer(o =>
    o.TokenValidationParameters = new TokenValidationParameters
    {
        ValidIssuer = "academia",
        ValidAudience = "magazin",
        IssuerSigningKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes("cheie-scurta-123")),
    });
builder.Services.AddAuthorization();
var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();

app.MapGet("/profil", (ClaimsPrincipal user) => $"Profilul lui {user.Identity!.Name}").RequireAuthorization();

app.Run();
După reparație, programul afișează
GET /profil → 200 OK
Profilul lui ana
Indiciu

HS256 cere o cheie de cel puțin 32 de octeți.

Alte forme ale mesajului

  • IDX10720: Unable to create KeyedHashAlgorithm for algorithm 'HS512', the key size must be greater than: '512' bits, key has '256' bits.
  • IDX10653: The encryption algorithm 'HS256' requires a key size of at least '128' bits.

Cum o eviți pe viitor

  • Generează cheia cu un generator criptografic (RandomNumberGenerator.GetBytes(32)) și păstreaz-o în User Secrets / vault, nu în cod.
  • Validează la pornire lungimea cheii (Options cu ValidateOnStart).
  • Folosește chei diferite pe fiecare mediu.
  • Rulează testele de integrare la fiecare modificare, ca problema să fie prinsă înainte de producție, nu raportată de utilizatori.

Întrebări frecvente

Ce înseamnă „mai mare decât 256 de biți” dacă 32 de octeți e exact 256?

În practică, biblioteca acceptă chei de cel puțin 256 de biți: 32 de octeți sunt suficienți. Formularea mesajului e puțin înșelătoare.

Pot folosi o parolă lungă ca cheie?

Merge tehnic, dar un text ușor de ghicit e o cheie slabă: cine o află poate semna tokenuri cu orice rol. Folosește octeți aleatori.

Erori înrudite

← Toate erorile ASP.NET Core

Tudor Andrei Dumitrescu
Cine a explicat eroarea

Tudor Andrei Dumitrescu

Senior Software Developer · fondatorul Academiei Programatorilor

LinkedIn
  1. 2019 Junior JavaCognizant Softvision
  2. 2021 Mid JavaCognizant Softvision
  3. 2022 Team LeaderEndava
  4. 2023 Senior Software DeveloperUniCredit
  5. Acum Senior Software DeveloperHCLTech
Certificat de absolvire Instructor / Preparator formare, Tudor Andrei Dumitrescu
Certificat de formator autorizatMinisterul Muncii și Ministerul Educației · 2022
Certificat de absolvire Instructor / Preparator formare, Tudor Andrei Dumitrescu

Certificat de formator autorizat · Ministerul Muncii și Ministerul Educației · 2022

Din 2020 construiește Academia Programatorilor, iar din 2026 și JoburiIT.ro. Fiecare eroare de aici a fost reprodusă în editorul nostru: codul greșit chiar dă mesajul din titlu, iar reparația chiar funcționează.

Învață ASP.NET Core de la zero, cu exerciții la fiecare lecție

Curs ASP.NET Core: lecții scurte, fiecare cu un exercițiu verificat automat, direct în browser. Primele 20 lecții sunt gratuite.