TLS

Per proteggere i dati in transito, le connessioni verso le API devono usare TLS 1.2 come versione minima.

Se il client propone cipher suite non supportate, la connessione non verrà stabilita.

Cosa succede se il mio client non è compatibile

Se il tuo client o ambiente usa cipher più vecchi o versioni TLS inferiori a 1.2, la connessione verrà rifiutata prima ancora di raggiungere le API.

L'errore tipico è un fallimento dell'handshake TLS (es. SSL handshake failed, TLSV1_ALERT_PROTOCOL_VERSION o simili a seconda del linguaggio).

Come verificare la compatibilità

Puoi testare la connessione TLS al server con uno dei seguenti metodi:

Da riga di comando (curl)

curl -v https://api.giponext.it/swagger/docs/v2 2>&1 | grep "SSL connection"

Se la connessione riesce, vedrai una riga simile a:

* SSL connection using TLSv1.3 / TLS_AES_256_GCM_SHA384

Se fallisce, vedrai un errore di handshake.

Da riga di comando (openssl)

openssl s_client -connect api.giponext.it:443 -tls1_2

Se la connessione riesce, vedrai il certificato e la cipher negoziata. Se fallisce, riceverai un errore di handshake.

Note per linguaggio/framework

Linguaggio / Runtime	Note
.NET Framework 4.8	TLS 1.2 è supportato ma potrebbe non essere abilitato di default. Aggiungi ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12; all'avvio.
.NET 6+	TLS 1.2+ è il default. Nessuna configurazione necessaria.
Java 8+	TLS 1.2 è supportato. Con Java 8, verifica che sia abilitato (potrebbe non essere il default su versioni molto vecchie). Da Java 11 è il default.
Python (requests)	Usa la versione TLS del sistema operativo. Su sistemi moderni non servono configurazioni aggiuntive. Se usi un ambiente vecchio, aggiorna OpenSSL.
Node.js 12+	TLS 1.2+ è il default. Nessuna configurazione necessaria.

Prossimi passi

• Gestione errori — come interpretare gli errori HTTP
• Rate limiting — limiti al numero di richieste