Colloquio SGSS-SIRGESA Specifiche Tecniche Versione 1.3.1 07/02/2013 RTI Funzione Nome Redazione Capo progetto RTI (Aruba) Esperto di dominio (Actalis) Capo progetto CMS (Engineering) Esperto architetture (Engineering) Umberto Ferrara, Riccardo Casiraghi Massimo Agostiniani Fabio Bennati Approvazione Capo progetto RTI Regione Toscana Funzione Nome Verifica Approvazione Nome file: CSE-ServiziAggiuntivi_SIRGESA_ST_1-3-1.odt Pag. 1 di 9
Indice AGGIORNAMENTI DELLE VERSIONI...3 1 GENERALITÀ...4 1.1 Scopo...4 1.2 Riferimenti... 4 1.3 Definizioni e abbreviazioni... 4 1.4 Allegati...4 2 PREREQUISITI/VINCOLI...5 3 SCENARIO D'USO...6 4 SPECIFICHE INTERFACCIA...6 4.1 Inizializzazione del servizio... 6 4.2 Esito dell inizializzazione del servizio... 6 5 ESEMPI...7 5.1 Form di richiesta inizializzazione servizio... 7 5.2 Preparazione richiesta inzializzazione servizio...8 5.3 Interpretazione risposta inzializzazione servizio... 9 Pag. 2 di 9
AGGIORNAMENTI DELLE VERSIONI Versione Data Motivo Modifiche 1.0 19/11/2012 Emissione -- 1.1 20/11/2012 Integrazione parametri di Aggiornati paragrafi 3.1 e 3.2, eliminato interfaccia paragrafo 3.3 1.2 30/11/2012 Revisione prerequisiti/vincoli, Aggiornato capitolo 2, aggiunto capitolo 5 aggiunti esempi 1.2 a 30/11/2012 Corretto timestamp Aggiornati paragrafi 5.1, 5.2, 5.3 1.2 b 18/12/2012 Revisione Rivisti i codici di errore comunicati a SGSS da SIRGESA 1.3 28/01/2013 Revisione Consolidamento correzioni e revisioni 1.3.1 07/02/2013 Corretti esempi di pseudocodice Aggiornati paragrafi 5.2 e 5.3 Pag. 3 di 9
1 GENERALITÀ Nell'ambito della diffusione di servizi aggiuntivi sulla CNS Regione Toscana ha implementato per le CNS di cui è ente emettitore unservizio infrastrutturale utile alla semplificazione dell'inizializzazione dei servizi. Il servizio SIstema Regionale di GEstione dei Servizi Aggiuntivi (SIRGESA) ha il compito di inizializzare il servizio aggiuntivo su richiesta del Sistema di Gestione dello Specifico Servizio (SGSS). Il servizio, una volta inizializzato potrà essere utilizzato da altri sistemi secondo le specifiche del servizio stesso. Il presente documento costituisce l output del processo di definizione delle specifiche tecniche dell interfaccia di colloquio, volto all inizializzazione di un servizio aggiuntivo sulla carta CNS regionale, tra il SIstema Regionale di GEstione dei Servizi Aggiuntivi (SIRGESA) ed il Sistema di Gestione dello Specifico Servizio (SGSS) sulle carte CNS regionali. Il documento descrive: Pre-requisiti Scenario d'uso Indicazione delle specifiche di interfaccia; 1.1 Scopo L obiettivo di questo documento è quello di descrivere l interfaccia e le modalità di interazione tra SIRGESA e SGSS. 1.2 Riferimenti http://www.digitpa.gov.it/sites/default/files/lineeguidacns%28v3.0%29.pdf 1.3 Definizioni e abbreviazioni RT Regione Toscana 1.4 Allegati N.A. Pag. 4 di 9
2 PREREQUISITI/VINCOLI Di seguito elenchiamo i pre-requisiti necessari all attivazione del colloquio tra SIRGESA e SGSS: SIRGESA ha a disposizione un proprio certificato APP2APP (p12) composto di due chiavi una pubblica ed una privata di seguito indicate con SIRGESA_PK e SIRGESA_SK. SGSS ha a disposizione un proprio certificato APP2APP (p12) composto di due chiavi una pubblica ed una privata di seguito indicate con SGSS_PK e SGSS_SK. SGSS ha definito gli eventuali elementi di sicurezza collegati alle fasi di lettura e scrittura dei dati del servizio sulla carta (certificato o PIN). SGSS è stato definito e censito all interno dell anagrafe dei servizi aggiuntivi regionali comprensivo delle relative sicurezze da attivare (certificato/pin) sulla carta e della sua chiave pubblica SGSS_PK. SGSS ha ricevuto l identificativo SIRGESA associato (nome del servizio) e la chiave pubblica di SIRGESA (SIRGESA_PK) quali elementi necessari alla gestione del colloquio tra i due sistemi SGSS deve essere in grado di recuperare il seriale dalla carta CNS regionale Affinché l'inizializzazione del servizio possa avvenire è necessario che la postazione ove è presente la CNS abbia le seguenti caratteristiche: o installazione di jre 1.6 o superiore o browser con java plugin installato o connettività di rete mentre il sistema SGSS che ne invoca SIRGESA per l'inizializzazione soddisfa i seguenti requisiti: o è una applicazione raggiungibile via rete su protocollo http dalla postazione ove è presente la CNS o gestisce richieste http ovvero http over ssl SGSS richiama la url di inizializzazione del servizio sulla carta solo se ne ha rilevato l assenza. La CNS potrebbe non essere stata attivata nelle sue funzioni di autenticazione in rete Il servizio aggiuntivo potrebbe non richiedere l'inserimento del PIN Pag. 5 di 9
3 SCENARIO D'USO Si faccia riferimento a Attivazione servizi aggiuntivi sulla TS-CNS - specifiche generali 4 SPECIFICHE INTERFACCIA 4.1 Inizializzazione del servizio Il SIRGESA espone apposita url a cui SGSS invia il client dell utente per l inizializzazione del servizio sulla carta. Le url da richiamare sono: Ambiente di pre-produzione https://<nome_server_pre-produzione>/sirgesa/inizializzaservizioaggiuntivo Ambiente di produzione https://<nome_server_produzione>/sirgesa/inizializzaservizioaggiuntivo Il sistema SIRGESA sulle indicate url: non prevede l identificazione del client attraverso il parametro verifycheck verifica che i para,etri di chiamata risultano inalterati e forniti da SGSS. Di seguito le caratteristiche di invocazione in termini di parametri passati in POST sulla chiamata: PARAMETRI nomeservizioaggiuntivo transid urlritorno serialnumber timestamp verifycheck DESCRIZIONE Nome del servizio aggiuntivo come censito su SIRGESA Identificativo di transazione nel sistema SGSS url a cui redirigere il client terminata la transazione di inizializzazione del servizio sulla carta Numero seriale della carta Tempo di generazione della richiesta espresso nel formato dd/mm/yyyy-hh:mm:ss (*) Digest secondo l algoritmo SHA-256 della concatenazione dei valori presenti nei parametri precedenti, criptato con la chiave privata di SGSS (SGSS_SK) e codificato in Base64 (**) (*) Verranno prese in considerazione ed elaborate solo le richieste pervenute al SIRGESA entro 100 secondi dal timestamp dichiarato nella chiamata. (**) Encode(Sign(Hash(nomeServizioAggiuntivo+transId+urlRitorno+serialNumber+timestamp, SHA-256), SGSS_SK),BASE64) 4.2 Esito dell inizializzazione del servizio SGSS espone apposita url a cui il sistema SIRGESA re-dirigerà il client dell utente al termine del processo di Pag. 6 di 9
inizializzazione. La suddetta url viene comunicata a SIRGESA tramite il parametro di invocazione della richiesta di inizializzazione denominato urlritorno. Di seguito riportiamo le caratteristiche di invocazione in termini di parametri passati in POST sulla chiamata: PARAMETRI nomeservizioaggiuntivo transid serialnumber Esito iverifycheck DESCRIZIONE Nome del servizio aggiuntivo come censito su SIRGESA Identificativo di transazione per SGSS e comunicata a SIRGESA nella invocazione della url di inizializzazione Numero seriale della carta Esito della operazione di inizializzazione del servizio sulla carta: 00 : servizio sulla carta inizializzato correttamente 01 : servizio sulla carta già presente 90 : ip di provenienza della chiamata non conforme 91 : sessione inesistente 92 : carta non valida / non riconosciuta 93 : operazione interrotta dall'utente (Annulla sull'applet) 94 : colloquio sirgesa non validato 95 : sessione scaduta 96 : seriale carta non conforme alla richiesta iniziale 97 : servizio inesistente 98 : richiesta non conforme 99 : errore nell inizializzazione del servizio sulla carta Digest secondo l algoritmo SHA-256 della concatenazione dei valori presenti nei parametri precedenti, criptato con la chiave privata di SIRGESA (SIRGESA_SK) e codificato in Base64 (*) (*) Encode(Sign(Hash(nomeServizioAggiuntivo+transId+serialNumber+eisto, SHA-256), SIRGESA_SK), BASE64) 5 ESEMPI 5.1 Form di richiesta inizializzazione servizio Di seguito riportiamo esempio di form per richiamare la url di inzializzazione servizio su SIRGESA. <form action="https://<nome_server>/sirgesa/inizializzaservizioaggiuntivo" method="post" id="testsirgesaform"> <input type="hidden" name="nomeservizioaggiuntivo" id="nomeservizioaggiuntivo" value="isee" /> <input type="hidden" name="transid" id="transid" value="1234567890" /> <input type="hidden" name="urlritorno" id="urlritorno" value="https://<nome_server_sgss>/sgss/urlritorno" /> <input type="hidden" name="serialnumber" id="serialnumber" value="6090004292649001" /> <input type="hidden" name="timestamp" id="timestamp" value="30/11/2012-15:30:55 /> <input type="hidden" name="verifycheck" id="verifycheck" value="8dkk1jafvy/w4x1sfbbrcaesxtasu0fif6bq3nzf9ga7ssxn9yg632jxth9odhbwbfnocnrnw8iigai/sod0jw/s9duw2vtznxv+oyzq uvthv9+o49mhdud2skseamxa2j+frxubuk3rqbttd6z7jmunkk6t4lyqib84i1gntkc=" /> <input type="submit" value="test SIRGESA" /> </form> Pag. 7 di 9
5.2 Preparazione richiesta inzializzazione servizio Di seguito riportiamo un frammento di codice in linguaggio di alto livello (Java) necessario alla preparazione della richiesta di inzializzazione: //valorizzazione dei parametri di chiamata String nomeservizioaggiuntivo = <nome del servizio aggiuntivo gestito da SGSS>; String transid = <transid interno a SGSS>; String urlritorno = <url a cui SIRGESA inoltra l'esito di inzializzazione>; String serialnumber = <seriale della carta CNS regionale>; String pathtokeystore = <path dove SGSS conserva il proprio keystore JKS>; String aliasp12 = <alias del p12 nel keystore>; String keystorepassword = <password del keystore>; SimpleDateFormat sf = new SimpleDateFormat("dd/MM/yyyy-HH:mm:ss"); String timestamp = sf.format(new Date()); // dato di cui generare il digest secondo l'algoritmo SHA-256 byte[] dato = (nomeservizioaggiuntivo + transid + urlritorno + serialnumber + timestamp).getbytes(); java.security.messagedigest md = MessageDigest.getInstance("SHA-256"); md.update(dato); byte[] digest = md.digest(); // recupero della chiave privata dal keystore JKS dove SGSS ha importato il proprio // p12 APP2APP fornito al servizio aggiuntivo KeyStore ks = KeyStore.getInstance("JKS"); InputStream in = new FileInputStream(pathToKeyStore); ks.load(in, keystorepassword.tochararray()); PrivateKey priv = (PrivateKey) ks.getkey(aliasp12, keystorepassword.tochararray()); // firma del digest con la chiave privata del p12 APP2APP Signature signer = Signature.getInstance("NONEwithRSA"); signer.initsign(priv); signer.update(digest); byte[] digestcrypted = signer.sign(); // encoding in Base64 del digest firmato per generare il valore del parametro // verifycheck da inserire nella request String verifycheck = org.apache.commons.codec.binary.base64.encodebase64string(digestcrypted); Tutte le classi java richiamate laddove non espressamente riportanti il proprio package di appartenenza fanno riferimento ai package java.io, java.text, java.security, java.security.cert. Pag. 8 di 9
5.3 Interpretazione risposta inzializzazione servizio Di seguito riportiamo un frammento di codice in linguaggio di alto livello (Java) necessario alla interpretazione della risposta di inzializzazione del servizio: //recupero dei parametri di chiamata String nomeservizioaggiuntivo = request.getparameter( nomeservizioaggiuntivo ); String transid = request.getparameter( transid ); String serialnumber = request.getparameter( serialnumber ); String esito = request.getparameter( esito ); String verifycheck = request.getparameter( verifycheck ); String pathtosirgesacertificate = <path dove SGSS conserva il certificato pubblico di SIRGESA>; //calcolo del digest prodotto dai parametri forniti nella request byte[] datoricevuto = (nomeservizioaggiuntivo + transid + serialnumber + esito).getbytes(); java.security.messagedigest md = MessageDigest.getInstance("SHA-256"); md.update(datoricevuto); byte[] digestricalcolato = md.digest(); //decoding from Base64 del parametro verifycheck byte[] verifycheckcrypted = org.apache.commons.codec.binary.base64.decodebase64(verifycheck); // recupero della chiave pubblica dal certificato FileInputStream fin = new FileInputStream(pathToSirgesaCertificate); CertificateFactory f = CertificateFactory.getInstance("X.509"); X509Certificate certificate = (X509Certificate)f.generateCertificate(fin); PublicKey publickey = certificate.getpublickey(); // verifica del parametro verifycheck rispetto al digest // rigenerato sui parametri forniti utilizzando la chiave pubblica Signature signer = Signature.getInstance("NONEwithRSA"); signer.initverify(publickey); signer.update(digestricalcolato); if(signer.verify(verifycheckcrypted)) { //SUCCESS } else { //FAIL } Tutte le classi java richiamate laddove non espressamente riportanti il proprio package di appartenenza fanno riferimento ai package java.io, java.security, java.security.cert. Pag. 9 di 9