- SIAU - Specifiche di Interfaccia Applicativi Utente

Carta Regionale dei Servizi SISS Secondo Stadio - SIAU - Specifiche di Interfaccia Applicativi Utente Posto di Lavoro del Cittadino Codice documento: CRS-ISAU-SIAU#33 Versione: 06.2 PVCS: 17 Data di emissione: 02-02-2009 Stato: LISIT LI Funzione Nome Firma Redazione Area Architettura Generale Pierluigi Valenti Preverifica Area Architettura Generale Pierluigi Valenti Preapprovazione Dir. Sviluppo Nicola Contardi Verifica Governo S.I. e Centro di Competenza R.Ranza Approvazione Governo S.I. e Centro di Competenza R.Ranza LI Emissione Program Management Fabio Sirtori CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 1 di 81

CRONOLOGIA DELLE EMISSIONI Versione Revisione Interna Data Emissione 01 3 09-02-05 02 4 19-05-05 03 5 25-07-05 04 7 15-12-05 05 9 18-05-06 06 13 25-07-2007 06.1 15 15-05-2008 06.2 17 02-02-2009 CRONOLOGIA DELLE REVISIONI INTERNE Num. revisione Sintesi delle variazioni 1 Prima versione 2 Rilascio delle librerie crittografiche apposite per la PdLC Modificato il par. Scopo e campo di applicazione ; 3 Introdotta la definizione di Attestazione ; Inserito riferimenti alle specifiche Netlink e CNS. Allineato alla versione 1.3.01 dei componenti; Inserito il componente di traduzione in formato XML dei dati in formato ASN1.BER per i file 4 della Carta Cittadino; I componenti ora lavorano anche con le librerie crittografiche sviluppate da Bit4id s.r.l per il progetto CRS-SISS. Allineato alla versione 1.3.02 dei componenti; Gli ActiveX che costituiscono il pacchetto sono stati marcati come sicuri; 5 Il componente per l autenticazione SSL funziona ora anche come semplice rilevatore di inserimento/estrazione di smart card e consente l attestazione di documenti remoti. 6 Precisazione riguardo la funzione VerifyPinUI. 7 Correzioni minori in accordo alle osservazioni di LI (modificato titolo di 3 paragrafi). Introduzione nuove URL per il reperimento dei componenti ActiveX; corretti i riferimenti al 8 contesto SSL; scorporato il paragrafo relativo ai return code di errore; correzioni minori. 9 Correzioni minori. Allineato alla versione 1.4.02 dei componenti ActiveX. E ora possibile: - Determinare se il computer è un chiosco (vedi IsKiosk). 10 Dettagliati con maggior precisione i prerequisiti della connettività SSL. Snellita la sezione Configurazione e risoluzione problemi. 11 Correzioni minori. Allineato alla versione 3.0.00 dei componenti (ActiveX e Java Applet). Introdotto paragrafo 12 Sistemi Operativi e browser supportati dai componenti attivi. 13 Introdotto paragrafo Identificazione del tipo di browser. Accresciuta documentazione di alcuni metodi. 14 Aggiunti link alle specifiche Netlink e alle linee guida CNS pubblicati da CNIPA. Allineato alla versione 3.1.01 dei componenti, nelle quali la modifica del PIN forza il nuovo PIN 15 a 5 cifre per le CRS. Allineato alla versione 3.2.03 dei componenti, che comprende una nuova DLL per la lettura del 16 file EF.Dati_personali. 17 Introdotta sezione 2.1. Tutte le precedenti versioni. SOSTITUISCE/MODIFICA CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 2 di 81

CRS-SISS Stadio 2 LIMITI DI UTILIZZO DEL DOCUMENTO CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 3 di 81

INDICE DEL DOCUMENTO 1 INTRODUZIONE... 7 1.1 SCOPO E CAMPO DI APPLICAZIONE... 7 1.2 RIFERIMENTI... 7 1.3 ACRONIMI E DEFINIZIONI... 7 2 GENERALITA... 9 2.1 PREMESSA SULL UTILIZZO DEI COMPONENTI ATTIVI... 9 3 FUNZIONALITA ED ARCHITETTURA... 10 3.1 FUNZIONALITÀ... 10 3.1.1 Autenticazione SSL... 10 3.1.2 Amministrazione del PIN... 10 3.1.3 Lettura di file presenti sulla carta... 10 3.1.4 Attestazione... 11 3.1.5 Diagnostica... 11 3.1.6 Traduzione in XML dei dati presenti sulla carta... 11 3.2 ARCHITETTURA FUNZIONALE... 12 3.2.1 Identificazione delle componenti... 12 3.2.2 Reperibilità delle componenti... 12 3.2.3 Analisi e specifica dei requisiti di sicurezza... 13 3.2.4 Caricamento ed esecuzione degli ActiveX... 13 3.2.5 Caricamento ed esecuzione dell applet Java... 14 3.2.6 Sistemi Operativi e browser supportati dai componenti attivi... 14 3.2.7 Identificazione del tipo di browser... 14 4 AUTENTICAZIONE SSL... 17 4.1.1 Reperibilità delle CA emittenti i certificati CRS-SISS... 17 4.1.2 Conservazione dello stato SSL in Internet Explorer... 17 4.1.3 Conservazione dello stato SSL in Mozilla Firefox... 18 5 GESTIONE CARTA ED ATTESTAZIONE... 19 6 TRADUZIONE XML DEI DATI IN FORMATO ASN.1 BER... 20 7 DEFINIZIONE DELLE CLASSI DI INTERFACCIA... 21 7.1 Gestione degli errori... 21 7.2 RILEVAZIONE DELLA PRESENZA DI CARTE E AUTENTICAZIONE UTENTE... 21 7.2.1 INSERIMENTO IN UNA PAGINA HTML... 21 7.2.1.1 ACTIVEX... 21 7.2.1.2 JAVASCRIPT/JAVA... 21 7.2.2 INTERFACCIA... 22 7.2.3 Metodi...23 7.2.3.1 Metodo About...23 7.2.3.2 Metodo Reset...24 7.2.3.3 Metodo Start...25 7.2.4 Proprietà... 26 7.2.4.1 Proprietà CardCount...26 7.2.4.2 Proprietà CardState...27 7.2.4.3 Proprietà SISSCertificateState...28 7.2.4.4 Proprietà Version...29 7.2.5 Descrizione degli eventi... 30 7.2.5.1 Evento aftersisscertificateupdate...30 7.2.5.2 Evento beforesisscertificateupdate...31 7.2.5.3 Evento oncardstatuschange...32 7.2.5.4 Evento OnCertificatesUpdated...33 7.3 GESTIONE CARTA, ATTESTAZIONE E DIAGNOSTICA... 34 7.3.1 INSERIMENTO IN UNA PAGINA HTML... 34 7.3.1.1 ACTIVEX... 34 CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 4 di 81

7.3.1.2 JAVA... 34 7.3.2 INTERFACCIA... 35 7.3.3 Utility... 38 7.3.3.1 Descrizione delle proprietà...38 7.3.3.1.1 Proprietà IsKiosk...38 7.3.3.2 Descrizione dei metodi...39 7.3.3.2.1 Metodo Reset...39 7.3.4 Gestione del PIN...40 7.3.4.1 Descrizioni dei metodi...41 7.3.4.1.1 Metodo ChangePinUI...41 7.3.4.1.2 Metodo UnblockPinUI...42 7.3.4.1.3 Metodo VerifyPinUI...43 7.3.5 Attestazione... 44 7.3.5.1 Formato del file attestato...44 7.3.5.2 Procedura per l attestazione...45 7.3.5.3 Metodo BrowseForFileToSign...46 7.3.5.4 Proprietà CanDownload...47 7.3.5.5 Metodo CloseSigningSession...48 7.3.5.6 Proprietà DefaultFileType...49 7.3.5.7 Proprietà FileFilterIndex...50 7.3.5.8 Proprietà FileToSign...51 7.3.5.9 Proprietà FileToSignFilter...52 7.3.5.10 Proprietà IsSigningSessionPending...53 7.3.5.11 Proprietà PreviewableExtentions...54 7.3.5.12 Proprietà PreviewFileToSign...55 7.3.5.13 Metodo SetDocument...56 7.3.5.14 Proprietà Signature...57 7.3.5.15 Proprietà SignatureAsBase64...58 7.3.5.16 Metodo SignFileUI...59 7.3.5.17 Metodo SignSelectedFile...60 7.3.5.18 Metodo WriteSignatureToFile...61 7.3.6 Lettura di file presenti sulla carta... 62 7.3.6.1 Metodo GetAsnBerFileContent...63 7.3.6.2 Metodo GetAsnBerFileContentAsBase64...64 7.3.6.3 Metodo GetBinaryFileContent...65 7.3.6.4 Metodo GetBinaryFileContentAsBase64...66 7.3.7 Diagnostica... 67 7.3.7.1 Descrizione dei metodi...68 7.3.7.1.1 Metodo About...68 7.3.7.2 Metodo CheckSigning...69 7.3.7.3 Proprietà CardAtr...70 7.3.7.4 Proprietà CardReaderName...71 7.3.7.5 Proprietà CNSManufacturer...72 7.3.7.6 Metodo CNSType...73 7.3.7.7 Proprietà CryptographicProvider...74 7.3.7.8 Proprietà SISSCertificateIssuer...75 7.3.7.9 Proprietà Version...76 7.4 TRADUZIONE IN XML DEI DATI PRESENTI SULLA CARTA... 77 7.4.1 INSERIMENTO IN UNA PAGINA HTML... 77 7.4.1.1 ACTIVEX... 77 7.4.1.2 JAVA... 77 7.4.2 Descrizione dei metodi... 78 7.4.2.1 Metodo ASN1BERAsXML... 78 8 INTERFACCIA DLL... 79 8.1.1 Descrizione delle funzioni esportate... 79 8.1.1.1 Rilevazione della versione... 79 8.1.1.2 Diagnostica errori... 79 8.1.1.3 Lettura del file EF.Dati_personali... 79 9 INSTALLAZIONE... 80 9.1.1 Verifica dell installazione degli ActiveX (solo Internet Explorer)... 80 10 APPENDICE... 81 CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 5 di 81

10.1 CONFIGURAZIONE E RISOLUZIONE PROBLEMI... 81 CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 6 di 81

1 INTRODUZIONE 1.1 SCOPO E CAMPO DI APPLICAZIONE Gli sviluppatori di applicazioni software basate sulla CNS trovano in questo documento la specifica e l uso dei componenti messi a disposizione dal pacchetto Postazione di Lavoro del Cittadino (abbreviato in PdLC), distribuito dal progetto CRS-SISS. La PdLC consente: - l accesso via Internet, in modo autenticato, ai servizi esposti dalla Pubblica Amministrazione; - la gestione del PIN della CRS; - la lettura delle informazioni registrate sulla CRS; - l attestazione di documenti (maggiori dettagli nei paragrafi successivi). - il salvataggio di documenti sul PC dell utente. Il Cittadino che desideri utilizzare dal proprio PC le applicazioni basate sulla PdLC può reperire tutte le informazioni per la configurazione del PC stesso nella sezione dedicata alla Postazione Cittadino sul sito : http://www.crs.lombardia.it/. L abilitazione della Carta Regionale dei Servizi (abbreviato in CRS) come Carta Nazionale dei Servizi (abbreviato in CNS) - strumento di accesso ai servizi in rete offerti da tutte le Pubbliche Amministrazioni ci consente, in questo documento, di utilizzare indifferentemente i due termini. 1.2 RIFERIMENTI CNS Carta Nazionale dei Servizi Functional Specification V.1.00; disponibile sul sito del CNIPA (http://www.cnipa.gov.it) nella sezione dedicata alle specifiche tecniche della CNS. Progetto NetLink disponibile sul sito del CNIPA (http://www.cnipa.gov.it) nella sezione dedicata alle specifiche tecniche della CNS. 1.3 ACRONIMI E DEFINIZIONI Attestazione Operazione di firma leggera effettuata attraverso la CNS (si veda anche Par. 6.3.3) ASN.1 BER Abstract Syntax Notation One - Basic Encodig Rules CA Certification Authority Carta Smart card di tipo Carta Regionale dei Servizi CNS Carta Nazionale dei Servizi nel seguito anche Carta del Cittadino CRS Carta Regionale dei Servizi nel seguito anche Carta del Cittadino CLASSID Class Identifier COM Component Object Model CSP Crypto Service Provider nel seguito anche Librerie Crittografiche DLL Dynamic Link Library Explorer Microsoft Internet Explorer GUI Graphical User Interface HTML Hyper Text Markup Language HTTP Hyper Text Transfer Protocol IDL Interface Definition Language MB Megabyte PC/SC Personal Computer/Smart Card PdLC Postazione di Lavoro del Cittadino PDF Portable Document Format PKCS#7 Risultato di un operazione di firma; contiene il documento originale, il certificato del firmatario e altre informazioni per la verifica dell autenticità. PIN Personal Identification Number PKI Infrastruttura a chiave pubblica PUK PIN Unlocking Key CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 7 di 81

RTF SISS SSL TXT URL Windows XML Rich Text Format Sistema Informativo Socio Sanitario Security Socket Layer TeXT file Universal Resource Locator Microsoft Windows extensible Markup Language CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 8 di 81

2 GENERALITA La Postazione di Lavoro del Cittadino (PdLC) è un pacchetto software realizzato dal progetto CRS-SISS, che consente agli utenti finali, individuabili in tutti i potenziali utilizzatori dei servizi del progetto CRS-SISS di accedere, direttamente da casa propria o da postazioni dedicate dislocate sul territorio (chioschi), ad un insieme di servizi erogati dalla PA mediante l utilizzo della Carta Regionale dei Servizi (CRS). Per l accesso da casa propria è sufficiente disporre di un PC Windows connesso a Internet e di un lettore di smart card. L implementazione attuale si basa sulle tecnologie: - Microsoft ActiveX e Java per l integrazione nelle pagine Web; - Microsoft CSP e PKCS#11 per il supporto dell autenticazione SSL da parte dei browser. - DLL, attualmente limitata alla lettura del file EF.Dati_personali. Le funzioni messe a disposizione dalla PdLC sono raggruppabili in tre macro-gruppi funzionali, ognuno dei quali corrisponde allo sviluppo di un componente specifico: - rilevazione dell inserimento/estrazione di carte, con possibilità di autenticazione SSL v3 tramite la CRS; - gestione CRS, attestazione tramite CRS e diagnostica; - traduzione in XML dei dati presenti sulla carta. La descrizione dei singoli componenti della PdLC nel loro aspetto funzionale e nelle interfacce programmatiche disponibili agli sviluppatori del servizio sviluppati parte dall identificazione dei tre macro-gruppi funzionali ed è l oggetto dei prossimi capitoli. 2.1 PREMESSA SULL UTILIZZO DEI COMPONENTI ATTIVI Come risulterà evidente dalle sezioni successive, Lombardia Informatica ha sviluppato i componenti attivi in tecnologia ActiveX ed applet in modo da renderli utilizzabili nei principali browser di mercato (i.e. Internet Explorer, Mozilla Firefox), su piattaforma Windows 32 bit. Le recenti evoluzioni sul tema dell accessibilità degli strumenti informatici via web prevede controlli via via sempre più stringenti sui componenti attivi integrati in applicazioni on-line: a tal proposito, si confronti la tecnologia del site locking entro Internet Explorer 8. D altro canto, la legislazione si è espressa su queste tematiche con il D.M. 08/07/2005, Allegato A, in cui di fatto si sconsiglia l utilizzo di componenti attivi, ove possibile, per favorire l accessibilità a siti istituzionali, sia in termini di multi-browsing, sia ancor più importante - in ottica multi-piattaforma (ovvero multi-sistema Operativo). Lombardia Informatica è venuta incontro a queste esigenze sviluppando, a fianco dei componenti attivi illustrati in questo documento, due iniziative correlate : - il nodo Internet di autenticazione CNS denominato IdPC Identity Provider del Cittadino, illustrato nel documento CRS-ISAU-SIAU#76, che standardizza i paradigmi di autenticazione CNS, sposando sia i requisiti di multi-piattaforma della soluzione che quelli di multi-browser (assenza di codice attivo) ; - l applicazione CRSManager, che realizza un client di firma, gratuito, liberamente distribuibile e disponibile per piattaforma Windows, Linux e MacOS. Alle applicazioni che dovessero essere disegnate ex-novo è dunque consigliato di valutare il nuovo approccio multipiattaforma (autenticazione CNS ed utilizzo dello strumento di firma off-line) piuttosto dell utilizzo dei componenti attivi. CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 9 di 81

3 FUNZIONALITA ED ARCHITETTURA In questo capitolo illustriamo brevemente i servizi disponibili e l architettura di base della PdLC. 3.1 FUNZIONALITÀ I componenti della PdLC consentono agli sviluppatori di utilizzare la CNS per: - stabilire una connessione autenticata e cifrata secondo il protocollo SSL versione 3; - amministrare il PIN; - leggere i dati registrati sulla carta (anche protetti da PIN); - attestare un file presente su disco o scaricato via HTTP/HTTPS. - rilevare la configurazione del PC e della CRS, per risalire alla causa di eventuali malfunzionamenti. - tradurre in XML i dati presenti sulla carta. 3.1.1 Autenticazione SSL L autenticazione SSL versione 3 con client authentication consente alle parti in gioco, il server erogatore del servizio ed il client fruitore dello stesso, di effettuare un riconoscimento reciproco della rispettiva identità sfruttando un meccanismo intrinseco della tecnologia PKI (di cui la Smart Card è uno strumento) e di instaurare tra queste un canale di comunicazione protetto su di una rete aperta quale è Internet. Per questa funzionalità è necessaria e sufficiente la sola installazione delle librerie crittografiche pubblicate sul sito www.crs.lombardia.it. Client PdLC Internet Canale sicuro SSLv3 Server Web Utente collegato: Mario Rossi 3.1.2 Amministrazione del PIN La PdLC mette a disposizione dell utente le funzioni per una gestione completa del PIN della propria CRS: - verifica; - modifica; - sblocco attraverso l utilizzo del PUK. 3.1.3 Lettura di file presenti sulla carta La lettura trasparente dei file presenti sulla CNS consente alle applicazioni di recuperare informazioni registrate sulla CNS relativamente al titolare della carta stessa. Lettura trasparente significa che il contenuto dei file viene restituito come sequenza grezza di byte, cioè senza alcuna interpretazione. L estrazione dei dati è a carico del codice client. Per esempio, nel caso del file contenente i dati personali del titolare della carta, la PdLC restituisce il contenuto del relativo file, che il codice client interpreta seguendo le specifiche di formato relative. E possibile leggere sia l intera area di memoria dedicata sulla carta al file, sia i soli byte significativi nel caso di file in formato ASN.1 BER (come il certificato utente e i file Netlink). CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 10 di 81

EF.Dati_personali 30 30 30 30 36 34 30 34 31 30 33 30 30 38 31 30 31 32 32 30 30 33 30 38 31 30 31 32 32 30 30 39 30 39 44 45 30 30 30 30 36 34 30 34 31 30 33 30 30 38 31 30 31 32 Il sottoscritto Mario Rossi, nato a Milano il 04/04/1954 DICHIARA 3.1.4 Attestazione L attestazione di un documento mediante l uso delle quantità crittografiche residenti sulla carta è gestibile attraverso le seguenti micro-funzioni: - selezione del documento da attestare mediante: o impostazione diretta del percorso di un file locale; o navigazione nel file-system locale; una volta selezionato, il documento è protetto dalle modifiche fino all attestazione; o scaricamento di un documento via HTTP/HTTPS. - visualizzazione preventiva del documento (opzionale); - attestazione con sottomissione del PIN; - disponibilità dell attestazione sia come sequenza di byte, sia in formato base64 per la trasmissibilità su media di solo testo (es: e-mail). Durante l attestazione viene verificata la validità temporale del certificato rispetto a data e ora locali del PC. Il risultato dell attestazione contiene data e ora dell attestazione stessa. 3.1.5 Diagnostica Per semplificare la diagnosi di eventuali malfunzionamenti, la PdLC consente di conoscere: - la versione dei componenti installati; - il lettore di smart card usato; - le librerie crittografiche usate; - le seguenti informazioni sulla carta usata: o l ente che ha emesso il certificato SISS registrato sulla carta stessa; o la stringa di identificazione del modello di appartenenza (l ATR); o il produttore; o il tipo di carta (reale/demo e con set di chiavi nuovo o del prototipo); - se la funzione di attestazione è funzionante, senza necessità di attestare effettivamente un documento. 3.1.6 Traduzione in XML dei dati presenti sulla carta I dati registrati sulla CNS in formato ASN.1 BER possono essere tradotti in formato XML per successivi trattamenti di Identificazione Cittadino e Classi di Esenzione Fuori Linea (ICCEFL componente estraneo alla PdLC e non oggetto di trattazione in questo documento). CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 11 di 81

3.2 ARCHITETTURA FUNZIONALE Lo schema seguente illustra l architettura di base della PdLC. L identificazione e la gestione delle componenti individuate viene descritta nei paragrafi successivi. Client PdLC Pagina Web Componenti PdLC Server Web Pagina Web Componenti PdLC Librerie Crittografiche Driver lettore Smart Card 3.2.1 Identificazione delle componenti Per usufruire del servizio attraverso la PdLC, il cittadino deve munirsi di un lettore di Smart Card per PC. Il lettore va collegato al PC e vanno installati i relativi driver, di norma allegati alla periferica o scaricabili via Internet dal sito del produttore. Il Cittadino deve, inoltre, installare le librerie crittografiche di supporto alle funzioni di autenticazione SSL e firma leggera. Queste librerie sono reperibili sul sito ufficiale di progetto della CRS curato da Lombardia Informatica (http://www.crs.lombardia.it/), ovvero distribuite all interno del CRS Kit, disponibile al pubblico dal 21 ottobre 2008. A questo punto il Cittadino può richiedere la fruizione del servizio collegandosi alla pagina Web di distribuzione dello stesso e di proprietà dell ente erogatore. Tale pagina contiene un riferimento remoto ai componenti della PdLC. 3.2.2 Reperibilità delle componenti L aggiornamento delle componenti della PdLC sarà curato da Lombardia Informatica, che metterà a disposizione sul sito ufficiale di progetto della CRS/CNS (http://www.crs.lombardia.it/) gli aggiornamenti relativi alle librerie crittografiche. Per i driver del lettore l utente dovrà fare riferimento alla documentazione ed al software rilasciato dal produttore del lettore stesso (i driver del lettore distribuito da Regione Lombardia, invece, sono ovviamente compresi nel CRS Kit distribuito dal 21 ottobre 2008). I componenti da referenziare nelle pagine Web sono disponibili sia su URL HTTP che HTTPS, da far corrispondere al protocollo usato dalla pagina che le referenzia per evitare che il browser generi degli avvertimenti. Tali componenti, per l integrazione in tecnologia ActiveX e Java, sono disponibili rispettivamente alle seguenti URL: http://supportsiss.lispa.it/components/pdlc.cab 1 https://supportsiss.lispa.it/components/pdlc.cab 2 http://supportsiss.lispa.it/components/pdlc.jar http://supportsiss.lispa.it/components/pdlc.js https://supportsiss.lispa.it/components/pdlc.jar 1 Il CLASSID del componente è menzionato nel seguito del documento. 2 Vedi osservazione precedente. CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 12 di 81

https://supportsiss.lispa.it/components/pdlc.js Queste componenti sono contraddistinte da numero di versione almeno pari a: 3,0,0,0. Si noti che la web application non ha la possibilità di fissare la versione di componenti attivi con cui deve essere eseguita, in quanto i componenti attivi incorporano un automatismo che comporta l aggiornamento del client con la versione più recente dei componenti disponibile in rete. Per compatibilità con le web application già sviluppate, ed in via transitoria, sono mantenute attive anche le seguenti URL, che contengono i soli ActiveX in versione 1,x,x,x: http://supportsiss.lispa.it/components/ocskitcittadino.cab http://supportsiss.lispa.it/components/ocxcertupdate.cab http://supportsiss.lispa.it/components/ocxcrsinfo.cab https://supportsiss.lispa.it/components/ocskitcittadino.cab https://supportsiss.lispa.it/components/ocxcertupdate.cab https://supportsiss.lispa.it/components/ocxcrsinfo.cab Qualora web application referenziassero i componenti attivi alle seguenti URL: http://www.crs.lombardia.it/components/ocskitcittadino.cab http://www.crs.lombardia.it/components/ocxcertupdate.cab http://www.crs.lombardia.it/components/ocxcrsinfo.cab esse dovranno modificare i riferimenti a questi oggetti, utilizzando quelli sopra indicati, in quanto il repository unico dei componenti attivi è supportsiss.lispa.it. Si faccia riferimento alle precedenti revisioni di questo documento per evincere quali metodi/proprietà sono implementate in questi ActiveX. A partire dal 01/01/2009, Lombardia Informatica garantirà la manutenzione correttiva e le evoluzioni sulle componenti in versione 3.x.xx. Le componenti in versione 1.x.xx rimarranno comunque disponibili su web, alle URL indicate. 3.2.3 Analisi e specifica dei requisiti di sicurezza Un componente ActiveX contrassegnato come sicuro o un applet Java firmata ospitato su una pagina Web, su autorizzazione anche implicita da parte dell utente, ha accesso completo alla macchina ed è completamente accessibile al codice script incorporato nella pagina stessa. Questo fattore rappresenta un potenziale pericolo per la privacy dell utente e l integrità del suo PC. Vanno quindi predisposte opportune misure di sicurezza. Queste misure comportano sia una restrizione delle funzionalità fornibili dai componenti sia una opportuna verbosità dell interfaccia grafica, in modo da informare l utente delle attività in corso ed in modo che l utente stesso abbia la facoltà di vietare l esecuzione del codice attivo, se ritiene provenga da una pagina web considerata non attendibile. In ogni caso, qualora dovesse essere scoperta una vulnerabilità di un componente della PdLC, sarà possibile pubblicare una patch che ne impedisca l esecuzione. 3.2.4 Caricamento ed esecuzione degli ActiveX Il livello di protezione predefinito di Internet Explorer per l area Internet permette l installazione e l esecuzione degli ActiveX della PdLC, dietro autorizzazione dell utente. Qualora l utente avesse modificato in maniera restrittiva il livello di protezione, per il funzionamento degli ActiveX devono essere consentiti: - esecuzione di codice script; - download di ActiveX firmati; - esecuzione di ActiveX contrassegnati come sicuri. - interazione fra codice script e ActiveX contrassegnati come sicuri. CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 13 di 81

Per poter installare gli ActiveX referenziati dalle pagine, il profilo dell'utente che si connette deve comprendere i privilegi necessari. Una volta installati, gli ActiveX sono eseguibili anche da utenti con privilegi limitati. Il meccanismo di aggiornamento automatico integrato assicurerà la presenza dell ultima versione dietro disponibilità di connettività Internet. Gli ActiveX sono firmati con un certificato riconducibile a una CA OmniRoot, e quindi riconosciuto nativamente come attendibile da Internet Explorer. 3.2.5 Caricamento ed esecuzione dell applet Java Il livello di protezione predefinito per Internet Explorer e Firefox consente l esecuzione delle applet della PdLC, dietro autorizzazione dell utente. Qualora l utente abbia modificato in maniera restrittiva il livello di protezione, per il funzionamento delle applet devono essere consentiti: - esecuzione di codice script; - esecuzione di applet Java. Per poter eseguire le applet Java, il profilo dell'utente che vi si connette non deve comprendere privilegi particolari. Le pagine HTML non utilizzano direttamente le applet della PdLC, ma un wrapper JavaScript che, con la collaborazione dell applet stessa, converte i dati fra il codice script e la JVM e interpreta gli errori rendendone i relativi codici facilmente accessibili. 3.2.6 Sistemi Operativi e browser supportati dai componenti attivi Gli ActiveX e le applet Java sono pienamente esercibili sul Sistema Operativo Windows XP, nelle sue versioni Home e Professional, SP1 e SP2. La compatibilità con Windows Vista è, ad oggi, parziale, come dettagliato in seguito. In particolare, si ricorda che gli ActiveX sono resi disponibili su web nella versione 1,x,x,x come tre.cab separati nel dominio supportsiss.lispa.it, e nella versione 3,x,x,x come.cab unico nello stesso dominio supportsiss.lispa.it. La linea di sviluppo contraddistinta come 1,x,x,x è in fase di dismissione, dunque si caldeggia le web application ad utilizzare la release 3,x,x,x. Le applet Java esistono unicamente nella versione 3,x,x,x sul dominio supportsiss.lispa.it. Allo stato attuale dello sviluppo, ed a causa delle modifiche introdotte da Microsoft nell ambito della gestione della sicurezza del Sistema Operativo, i soli componenti che risultano compatibili con Windows Vista risultano essere gli ActiveX contrassegnati con la versione 1,5,x,x disponibili sul dominio supportsiss.lispa.it. E in previsione l introduzione della compatibilità con Windows Vista della linea di sviluppo 3,x,x,x che sino alla versione 3,0,1,0 compresa è da considerarsi non pienamente compatibile con Windows Vista. I browser supportati risultano essere: - Internet Explorer, versione 6 e superiori (per le tecnologie ActiveX ed applet); - Mozilla Firefox versione 2.0.0.0 e superiori (per la sola tecnologia applet). 3.2.7 Identificazione del tipo di browser L identificazione del tipo di browser viene effettuata dal client stesso mediante l uso di HTML e Javascript in modo tale da: - poter distinguere il tipo di user agent sulla base di informazioni più estese rispetto alla sola stringa di useragent presente nell header HTTP; - poter caricare selettivamente le risorse - quali altri script, oggetti con del codice gestito dal client. Due sono le fasi per il caricamento e l uso selettivo di ActiveX o Applet: 1. istanziazione dell oggetto corretto CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 14 di 81

2. uso delle librerie Fase 1: caricamento dell oggetto In questa fase viene istanziato l oggetto ActiveX o Applet in modo selettivo sulla base del tipo di browser. La pagina HTML che presenta la dichiarazione dell oggetto deve essere compatibile con tutte le tipologie di browser ma deve caricare solo l oggetto corretto. A questo scopo, vengono utilizzati i commenti condizionali, una particolare funzionalità del solo Internet Explorer che permette di includere degli if all interno di commenti HTML in modo tale da nascondere selettivamente alcune parti del codice HTML della pagina senza l uso di Javascript. Pagina HTML <!--[if!ie]> Firefox and others --> <applet name="applet_likitcrs" width='1' height='1' code="likitcrs.class" archive="https://supportsiss.lispa.it/components/pdlc.jar" mayscript="true" scriptable="true" id="applet_likitcrs" style="display:inline"> <!--<![endif]--> <object classid="clsid:57f9fc08-eeaf-49a8-ae3b-843a564dcc19" codebase="components/pdlc.cab#version=3,0,0,0" type="application/x-oleobject" id="likitcrs"> </object> <!--[if!ie]> Firefox and others : close outer object --> </applet> <!--<![endif]--> Questo estratto della pagina HTML ne illustra l uso: in apertura, il primo commento interpretato come condizionale esclusivamente da IE dichiara che se il client non è Internet Explorer debba essere interpretato il codice fino all endif corrispondente. In tal modo, la dichiarazione dell applet viene ignorata da IE, che leggerà solamente: <object classid="clsid:57f9fc08-eeaf-49a8-ae3b-843a564dcc19" codebase="components/pdlc.cab#version=3,0,0,0" type="application/x-oleobject" id="likitcrs"> </object> Qualsiasi altro browser, invece, gestisce i commenti come tali e non ne interpreta il significato; il browser vede l apertura di un tag <applet> e al suo interno un <object>: poiché la posizione di quest ultimo è non è corretta, viene ignorato. Il browser, quindi, vede solo: <applet name="applet_likitcrs" width='1' height='1' code="likitcrs.class" archive="https://supportsiss.lispa.it/components/pdlc.jar" mayscript="true" scriptable="true" id="applet_likitcrs" style="display:inline"> </applet> Fase 2: uso dell oggetto istanziato L interfaccia applicativa dell OCX è richiamabile direttamente dal browser mediante VBScript, mentre l applet espone le sue API tramite uno script Javascript. Per ottimizzare il comportamento, solo il browser della famiglia Mozilla (Mozilla, Firefox, ) scarica gli script eventualmente necessari tramite del codice Javascript che riconosce il tipo di browser in cui si trova. Per far ciò e per riutilizzare del codice già scritto ed ampiamente diffuso su Internet, si consiglia di utilizzare la libreria JQuery (http://jquery.com) che permette di scrivere in modo molto semplice il codice seguente: if ($.browser.msie){ if (LIKitCRS){ // do some stuff. } } else if ($.browser.mozilla){ CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 15 di 81

$.getscript("components/pdlc.js", function(){ }); kitapplet = new LISIT.LIKitCRS ("applet_likitcrs"); kitapplet.load (); // do some stuff. } else { //alert('browser non supportato'); } La libreria viene usata in due fasi: 1. identificazione del tipo di browser (if ($.browser.msie){...) 2. caricamento asincrono degli script accessori mediante la $.getscript() CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 16 di 81

4 AUTENTICAZIONE SSL Il browser esegue infatti la negoziazione del canale SSL e la sua successiva gestione con il solo supporto delle librerie crittografiche, senza alcuna necessità di intervento a livello di codifica da parte del programmatore delle pagine Web. Pertanto l installazione - e la registrazione per i browser diversi da Internet Explorer - delle librerie crittografiche sono l unico prerequisito necessario per il funzionamento dell autenticazione SSL con CNS. Le pagine Web che richiedano di seguire tale processo, possono utilizzare il componente di autenticazione che segnalerà al codice client: - l inserimento e l estrazione della CNS; - la disponibilità del sistema a stabilire la connessione SSL. Questo componente non è comunque indispensabile per l instaurazione di un canale SSL. A seconda del browser usato e della relativa configurazione, durante la negoziazione potrebbero essere richiesto l intervento dell utente oltre all inserimento del PIN. 4.1.1 Reperibilità delle CA emittenti i certificati CRS-SISS I certificati delle CA emittenti i certificati CRS-SISS presenti sulle CRS distribuite ai cittadini di Regione Lombardia, e da registrare sul server HTTPS per il supporto dell autenticazione SSL via CRS, sono disponibili sul sito di riferimento del progetto (http://www.crs.lombardia.it/). 4.1.2 Conservazione dello stato SSL in Internet Explorer In una sessione SSL con Microsoft Internet Explorer, quando un server richiede un certificato per verificare l identità di un utente, il certificato in questione viene memorizzato in una cache dedicata e qui rimane fino al riavvio del browser. Questo significa che nell ambito della stessa sessione, l autenticazione verso un sito SSL va fatta solo una volta e finché non si chiude il browser, il sito rimarrà accessibile anche dopo l estrazione della carta 3. A partire dalla versione 6 di Microsoft Internet Explorer è possibile cancellare manualmente il certificato senza chiudere la sessione: dal menu Strumenti selezionare Opzioni Internet, accedere alla pagina Contenuto e cliccare sul pulsante Cancella stato SSL; sempre sulla stessa scheda, nella pagina Avanzate, nella sezione Protezione, attivare l opzione Non salvare pagine crittografate su disco. Facendo ciò, se la carta non è nel lettore, il sito non sarà accessibile. 3 Osservazione applicabile solo se la postazione client non è dotata della Postazione di Lavoro Cittadino Regione Lombardia. Nel caso ne fosse provvista, infatti, all estrazione della carta un componente client-side provvede automaticamente a cancellare il contesto SSL di Internet Explorer. CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 17 di 81

4.1.3 Conservazione dello stato SSL in Mozilla Firefox In una sessione SSL con Mozilla Firefox, quando un server richiede un certificato per verificare l identità di un utente, il certificato in questione viene memorizzato in una cache dedicata e qui rimane fino al riavvio del browser. Questo significa che nell ambito della stessa sessione, l autenticazione verso un sito che richiede una sessione SSL va fatta solo una volta e finché non si chiude il browser, il sito rimarrà accessibile anche dopo l estrazione della carta 4. 4 Osservazione applicabile solo se la postazione client non è dotata della Postazione di Lavoro Cittadino Regione Lombardia. Nel caso ne fosse provvista, infatti, all estrazione della carta un componente client-side provvede automaticamente a chiudere Firefox. CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 18 di 81

5 GESTIONE CARTA ED ATTESTAZIONE Il componente di gestione carta ed attestazione espone metodi per la gestione del PIN, la lettura di file presenti sulla CNS e l attestazione di documenti. Come il componente per l autenticazione SSL, anche questo componente lavora sul primo lettore disponibile sul sistema. CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 19 di 81

6 TRADUZIONE XML DEI DATI IN FORMATO ASN.1 BER Il componente espone metodi per la traduzione in formato XML dei dati in formato ASN1.BER letti dai file Netlink presenti sulla CNS. CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 20 di 81

7 DEFINIZIONE DELLE CLASSI DI INTERFACCIA In questo capitolo descriviamo schematicamente l uso dei componenti che implementano i servizi della PdLC. Qui di seguito sono riportate le informazioni che si applicano alla definizione delle classi di interfaccia, disponibili in tecnologia ActiveX e Java. 7.1 Gestione degli errori Gli errori vengono segnalati con il lancio di eccezioni, intercettabili dal codice script che usa il componente. Le eccezioni sollevata dagli ActiveX e dalle classi JavaScript/Java hanno sempre le proprietà: - number: codice numerico che identifica l errore; - description: descrizione testuale dell errore. Come vedremo, per alcune funzioni è possibile demandare completamente al componente l interazione con l utente, in quanto i componenti integrano in maniera nativa delle GUI di utilizzo delle principali funzionalità esposte. In questo caso anche la visualizzazione degli errori sarà presa in carico dal componente. In tal caso, se si verifica un errore, verrà mostrata una finestra nella quale viene dettagliato il tipo di errore occorso e nessuna eccezione verrà sollevata al codice chiamante. 7.2 RILEVAZIONE DELLA PRESENZA DI CARTE E AUTENTICAZIONE UTENTE Per la rilevazione dello stato del lettore e l autenticazione SSL è disponibile la classe SCardListener. 7.2.1 Inserimento in una pagina HTML 7.2.1.1 ActiveX Per istanziare l ActiveX, inserire nell elemento HEAD del codice HTML il codice che segue. Il carattere grassetto indica la parte fissa, il carattere corsivo le parti che è possibile personalizzare. Se la pagina è accessibile su protocollo HTTPS cambiare i riferimenti http in https. <object id="pdlcssl" classid="clsid:877e14a6-0acf-4509-8cf3-e4a0f4ed46f4" codebase="http://supportsiss.lispa.it/components/pdlc.cab#version=3,0,0,0" type="application/x-oleobject"> </object> <script type="text/vbscript" src="http://supportsiss.lispa.it/components/pdlc.vbs"> </script> Il componente sarà accessibile nel codice script con l identificatore indicato dal parametro id dell elemento OBJECT (in questo caso pdlcssl). 7.2.1.2 JavaScript/Java Per istanziare l applet, inserire nell elemento HEAD del codice HTML il codice che segue. Il carattere grassetto indica la parte fissa, il carattere corsivo le parti che è possibile personalizzare. Se la pagina è accessibile su protocollo HTTPS CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 21 di 81

cambiare i riferimenti http:// in https://. Notare il codice per l attesa del caricamento dell applet prima di accedere alla stessa. <applet name="pdlcssl" id="pdlcssl" width="0" height="0" code="certupdate.class" archive="http://supportsiss.lispa.it/components/pdlc.jar" mayscript="true" scriptable="true"> </applet> <script type="text/javascript" src="http://supportsiss.lispa.it/components/pdlc.js"></script> <script type="text/javascript"> <!-- // --> </script> var scardlistener = new LISIT.SCardListener ("pdlcssl"); // Registra l evento per l attesa del caricamento dell applet. scardlistener.onloaded = function () { if (scardlistener.getloadstate () == LISIT.LOAD_STATE_OK) { // L applet è stata caricata ed è possible usarla. } else { // Il caricamento dell applet è fallito. } } try { scardlistener.load (); } catch (error) { // Il caricamento dell applet è fallito. } Il valore del parametro id e name dell elemento APPLET devono essere sempre in formato minuscolo. L accesso all applet è mediato da un oggetto della classe JavaScript LISIT.SCardListener contenuto nello script pdlc.js. 7.2.2 Interfaccia METODI About Mostra le informazioni sulla versione del componente. Reset Annullamento dell eventuali attività in corso sul componente, compresa la chiusura di eventuali GUI aperte. Start Attiva il componente. PROPRIETA CardCount Vale 1 se c è una carta nel lettore, altrimenti 0. CardState Stato della connessione alla carta. SISSCertificateState Stato di caricamento del certificato SISS. Version Versione del componente. UseSSL Abilita/disabilita il supporto per l autenticazione SSL prima dell attivazione del componente. EVENTI AfterSISSCertificateUpdate Notifica il completamento dell aggiornamento dei certificati. BeforeSISSCertificateUpdate Notifica l inizio dell aggiornamento dei certificati. OnCardStatusChange Notifica del cambiamento dello stato dei lettori. Interfaccia deprecata: EVENTI OnCertificatesUpdated Notifica del cambiamento dello stato dei certificati. CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 22 di 81

7.2.3 Metodi 7.2.3.1 Metodo About Visualizza le informazioni sulla versione del componente e l ambiente di esecuzione. object.about () Interfaccia Java/JavaScript object.about (); Argomenti object Qualsiasi istanza di un oggetto SCardListener. Note In Windows 2000 e superiori il testo contenuto nella finestra di messaggio mostrata è copiabile negli appunti con Ctrl+C e quindi incollabile come testo in qualsiasi programma. Questa possibilità è utile in caso di richieste di supporto via mail. Requisiti Tutte le versioni. Vedi anche Proprietà Version. CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 23 di 81

7.2.3.2 Metodo Reset Annulla eventuali attività in corso sul componente e chiude le eventuali GUI aperte. object.reset () object.reset (); Argomenti object Qualsiasi istanza di un oggetto SCardListener. Note L autenticazione SSL richiede l inserimento del PIN in un finestra gestita autonomamente dalle librerie crittografiche. Il codice client non riceve alcuna notifica dello stato dell operazione. E quindi possibile che l utente interrompa l operazione estraendo la carta, ma lasciando aperta la finestra di inserimento del PIN. Quando il componente informa il codice client dell estrazione della carta, il codice client può usare questo metodo per chiudere le eventuali finestre aperte. CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 24 di 81

7.2.3.3 Metodo Start Attiva la segnalazione degli eventi da parte del componente. object.start () object.start (); Argomenti object Qualsiasi istanza di un oggetto SCardListener. Note L'oggetto è inattivo e non solleverà alcun evento finché questo metodo non viene chiamato. Errori specifici Questo metodo va chiamato solo una volta per attivare la rilevazione dello stato del lettore. Non ci sono metodi per interrompere l attività del componente. Prima dell avvio, è possibile configurare il componente per la semplice rilevazione della presenza di una carta nel lettore o anche per il supporto SSL (vedi proprietà UseSSL). In questo caso sul sistema devono essere installate le librerie crittografiche rilasciate a supporto della PdLC. Valore PDLCITSSL_E_SMARTCARD_CONTEXT PDLCITSSL_E_SMARTCARD_LISTENER PDLCITSSL_E_UNSUPPORTED_WINVER Descrizione Non è possibile accedere alla libreria PC/SC. Non è stato possibile iniziare la rilevazione dello stato del lettore. La versione di Windows usata non è supportata. In JavaScript/Java queste costanti sono precedute da LISIT., come ad esempio: LISIT. PDLCITSSL_E_SMARTCARD_CONTEXT Vedi anche Proprietà UseSSL. Tutti gli eventi sollevati dal componente. CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 25 di 81

7.2.4 Proprietà 7.2.4.1 Proprietà CardCount Questa proprietà è deprecata. Restituisce 1 se c è una carta nel lettore di smart card, altrimenti 0. object.cardcount object.getcardcount (); Argomenti object Qualsiasi istanza di un oggetto SCardListener. Note Per poter rilevare la presenza di una carta, il componente va prima avviato con il metodo Start. Attraverso questa proprietà è possibile sapere se c è una carta nel lettore, ma non se la carta è inserita correttamente, è una CNS, ecc. Per questo livello di dettaglio è disponibile la proprietà CardState. Vedi anche Metodo CardState CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 26 di 81

7.2.4.2 Proprietà CardState Restituisce lo stato della connessione alla carta. object.cardstate object.getcardstate (); Argomenti object Qualsiasi istanza di un oggetto SCardListener. Note I possibili valori per questa proprietà sono: Valore Descrizione CARD_STATE_NULL Lo stato della connessione non è stato ancora determinato. Questo stato è il valore alla creazione del componente. CARD_STATE_ERROR Si è verificato un errore che ha impedito di determinare lo stato della connessione alla carta. CARD_STATE_EMPTY Il lettore è vuoto. CARD_STATE_READY La carta è inserita correttamente ed è una CNS. CARD_STATE_MUTE La carta non risponde. Verificare che sia stata inserita correttamente. CARD_STATE_BAD_CARD La carta inserita non è una CNS. Il valore predefinito è CARD_STATE_NULL. In JavaScript/Java queste costanti sono precedute da LISIT., come ad esempio: LISIT. CARD_STATE_NULL Vedi anche Proprietà CardCount. CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 27 di 81

7.2.4.3 Proprietà SISSCertificateState Restituisce lo stato di caricamento del certificato SISS. object.sisscertificatestate object.getsisscertificatestate (); Argomenti object Qualsiasi istanza di un oggetto SCardListener. Note I possibili valori per questa proprietà sono: Valore SISS_CERTIFICATE_STATE_NULL SISS_CERTIFICATE_STATE_ERROR SISS_CERTIFICATE_STATE_LOADED SISS_CERTIFICATE_STATE_LOAD_ERROR SISS_CERTIFICATE_STATE_REMOVED Descrizione Lo stato di caricamento del certificato SISS non è stato ancora determinato. Questo è il valore iniziale della proprietà. Errore durante l'aggiornamento dei certificati. Il certificato SISS è stato caricato. Il caricamento del certificato SISS è fallito. Verificare l installazione delle librerie crittografiche. Il certificato SISS è stato cancellato. SISS_CERTIFICATE_STATE_REMOVAL_ERROR La cancellazione del certificato è fallita. Il valore predefinito è SISS_CERTIFICATE_STATE_NULL. In JavaScript/Java queste costanti sono precedute da LISIT., come ad esempio: LISIT.SISS_CERTIFICATE_STATE_NULL CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 28 di 81

7.2.4.4 Proprietà Version Restituisce una stringa contenente la versione del componente. object.version object.getversion (); Argomenti object Qualsiasi istanza di un oggetto SCardListener. CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 29 di 81

7.2.5 Descrizione degli eventi 7.2.5.1 Evento aftersisscertificateupdate Segnala che, a seguito dell inserimento/estrazione di una CNS, è stato completato l aggiornamento dei certificati. Note Questo evento viene sollevato sempre dopo l evento beforesisscertificatestate, che segnala l inizio dell aggiornamento dei certificati. L esito dell aggiornamento è riportato nella proprietà SISSCertificateState. Questo evento non viene mai sollevato se il supporto per l SSL è stato disabilitato (vedi proprietà UseSSL). Vedi anche Metodo Start. Evento aftersisscertificateupdate. CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 30 di 81

7.2.5.2 Evento beforesisscertificateupdate Segnala che, a seguito dell inserimento/estrazione di una CNS, è iniziato l aggiornamento dei certificati. Note Questo evento non viene mai sollevato se il supporto per l SSL è stato disabilitato (vedi proprietà UseSSL). Si può verificare l esito dell aggiornamento nella gestione dell evento aftersisscertificateupdate. Vedi anche Metodo Start. CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 31 di 81

7.2.5.3 Evento oncardstatuschange Segnala l inserimento/estrazione di una carta nel lettore. Note Questo evento viene sollevato appena viene rilevato l'inserimento o l'estrazione di una carta. Per determinare se la carta è stata inserita o rimossa, controllare la proprietà CardState. Appena il codice client completa la gestione dell evento, se previsto (vedi proprietà UseSSL) viene eseguito l aggiornamento dei certificati. Vedi anche Proprietà CardState. CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 32 di 81

7.2.5.4 Evento OnCertificatesUpdated Questo evento è stato sostituito dall evento AfterSISSCertificateUpdate. CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 33 di 81

7.3 GESTIONE CARTA, ATTESTAZIONE E DIAGNOSTICA Per la rilevazione dello stato del lettore e l autenticazione SSL è disponibile la classe LISIT.SCardAccess. 7.3.1 Inserimento in una pagina HTML 7.3.1.1 ActiveX Per referenziare i componenti in una pagina HTML, inserire nell elemento HEAD del codice HTML il che segue. Il carattere grassetto indica la parte fissa, il carattere corsivo le parti che è possibile personalizzare. Se la pagina è accessibile su protocollo HTTPS cambiare i riferimenti http in https. <object id="pdlccard" classid="clsid:57f9fc08-eeaf-49a8-ae3b-843a564dcc19" codebase="http://supportsiss.lispa.it/components/pdlc.cab#version=3,0,0,0" type="application/x-oleobject"> </object> <script type="text/vbscript" src="http://supportsiss.lispa.it/components/pdlc.vbs"> </script> Il componente è accessibile attraverso il parametro id dell elemento OBJECT, in questo caso pdlccard. 7.3.1.2 Java Per referenziare i componenti in una pagina HTML, inserire nell elemento HEAD del codice HTML il che segue. Il carattere grassetto indica la parte fissa, il carattere corsivo le parti che è possibile personalizzare. Se la pagina è accessibile su protocollo HTTPS cambiare i riferimenti http:// in https://. Notare il codice per l attesa del caricamento dell applet prima accesso alla stessa. <applet name="pdlccard" id="pdlccard" width="0" height="0" code="likitcrs.class" archive="https://supportsiss.lispa.it/components/pdlc.jar" mayscript="true" scriptable="true"> </applet> <script type="text/javascript" src="https://supportsiss.lispa.it/components/pdlc.js"></script> <script type="text/javascript"> <!-- // --> </script> var scardaccess = new LISIT.SCardAccess ("pdlccard"); // Registra l evento per la verifica del caricamento dell applet. scardaccess.onloaded = function () { if (scardaccess.getloadstate () == LISIT.LOAD_STATE_OK) { // L applet è stata caricata ed è possible usarla. } else { // Il caricamento dell applet è fallito. } } try { scardaccess.load (); } catch (error) { // Il caricamento dell applet è fallito. } Il valore del parametro id e name dell elemento APPLET devono essere sempre in formato minuscolo. CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 34 di 81

7.3.2 INTERFACCIA About Reset Version ChangePinUI UnblockPinUI VerifyPinUI BrowseForFileToSign CloseSigningSession PreviewFileToSign SetDocument SignFileUI SignSelectedFile WriteSignatureToFile CanDownload DefaultFileType FileToSign FileFilterIndex FileToSignFilter IsSigningSessionPending PreviewableExtentions Signature UTILITY Metodi Mostra le informazioni sulla versione del componente. Interruzione dell eventuali attività in corso sul componente, compresa la chiusura di GUI aperte. Versione del componente. Modifica del PIN. Sblocco del PIN. Verifica del PIN. Proprietà GESTIONE DEL PIN Metodi ATTESTAZIONE Metodi Scelta del file da attestare mediante navigazione nel file system. Chiusura (o annullamento) della sessione di attestazione. Apre il file da attestare per la lettura con l applicazione associata al tipo di file stesso. Attestazione di un documento disponibile a un URL su protocollo HTTPS. Sessione di attestazione completamente gestita dal componente. Genera l attestazione del file correntemente selezionato. Scrive su disco in formato binario il PKCS#7 risultante dall attestazione del documento. Proprietà Indica la possibilità di download di documenti remoti. Estensione predefinita per la finestra per la selezione del file da attestare mediante navigazione nel file system. Percorso del file da attestare. Filtro da preselezionare all apertura della finestra per la selezione del file da attestare mediante navigazione nel file system. Deprecato: usare DefaultFileType. Filtro usato dalla finestra per la selezione dei file mediante navigazione nel file system. Indica se è in corso una sessione di attestazione. Lista delle estensioni di file che sono considerati documenti e quindi firmabili. PKCS#7 risultante dalla firma del documento, in formato binario. SignatureAsBase64 PKCS#7 risultante dall attestazione del documento, in formato Base 64. GetAsnBerFileContent GetBinaryFileContent LETTURA FILE Metodi Lettura dalla carta del contenuto di un file codificato in ASN.1 BER. Lettura dalla carta del contenuto dell intera area di memoria dedicata a una file. CheckSigning CardATR CNSManufacturer CNSType CardReaderName SISSCertificateIssuer Verifica la funzionalità dell attestazione. Stringa di riconoscimento della carta. Produttore della carta. Tipo di CRS usata. Lettore di smart card usato. DIAGNOSTICA Metodi Proprietà Distinguished Name (DS) dell ente che ha emesso il certificato di autenticazione presente sulla carta. CryptographicProvider Librerie crittografiche usate. ERRORI In JavaScript/Java queste costanti sono precedute da LISIT., come ad esempio LISIT. KC_E_AUTHENTICATION_FAILED. CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 35 di 81

KC_E_AUTHENTICATION_FAILED KC_E_BAD_CARD KC_E_CARD_BUSY KC_E_CARD_ERROR KC_E_CARD_NOT_FOUND KC_E_CARD_REMOVED KC_E_CARD_UNPOWERED KC_E_CARD_UNRESPONSIVE KC_E_CARD_WRITE_PROTECTED KC_E_CERTIFICATE_EXPIRED KC_E_CERTIFICATE_NOT_FOUND KC_E_CERTIFICATE_NOT_VALID_YET KC_E_COMMAND_FAILED KC_E_DEVICE_BUSY KC_E_DOCUMENT_INVALID KC_E_FAIL KC_E_FILE_NOT_FOUND KC_E_INFORMATION_SENSITIVE KC_E_INVALID_FORMAT KC_E_INVALID_STATE KC_E_IO_ERROR KC_E_IO_OPEN_ERROR KC_E_IO_READ_ERROR KC_E_IO_SEEK_ERROR KC_E_IO_WRITE_ERROR KC_E_KEY_FUNCTION_NOT_PERMITTED KC_E_KEY_UNEXTRACTABLE KC_E_NO_DLL KC_E_NOT_ALLOWED KC_E_NOT_ALLOWED KC_E_OS_ERROR KC_E_PIN_ERROR KC_E_PIN_EXPIRED KC_E_PIN_INCORRECT KC_E_PIN_INVALID KC_E_PIN_LOCKED KC_E_PIN_NOT_INITIALIZED KC_E_PUK_INCORRECT KC_E_PUK_INVALID KC_E_PUK_LOCKED KC_E_READER_ERROR KC_E_READER_NOT_FOUND KC_E_SHARING_VIOLATION KC_E_SIGNATURE_INVALID KC_E_SIGNATURE_LENGTH_INVALID KC_E_SIZE_OVERFLOW KC_E_SYSTEM_CANCELLED KC_E_TIMEOUT KC_E_UNEXPECTED_DATA Autenticazione fallita. La carta inserita non è una CNS. La carta è impegnata in un'operazione e non può rispondere alla richiesta. Errore durante l'accesso alla carta. Non è stata rilevata alcuna Carta del Cittadino collegata al sistema. La carta è stata rimossa. La carta non è alimentata. La carta non risponde. L'operazione richiesta non può essere eseguita perché la carta è protetta dalla scrittura. Certificato scaduto. Nessun certificato disponibile per eseguire l'operazione richiesta. Certificato non ancora entrato nel suo periodo di validità. La carta ha respinto la richiesta. Dispositivo impegnato (lettore o carta). Documento non valido. Fallimento senza ulteriore indicazione. File non trovato. L'informazione non può essere letta perché sensibile. Il formato dei dati analizzati non è valido. Lo stato corrente dell'oggetto non consente di eseguire l'operazione richiesta. Errore durante l'input/output. Errore durante l'apertura del flusso di input/output. Errore durante la lettura del flusso di input. Errore durante il riposizionamento nel flusso di input/output. Errore durante la scrittura nel flusso di output. La chiave non consente la funzione richiesta. La chiave non è leggibile. Errore durante il caricamento di una libreria. Operazione non consentita. Operazione non consentita. Una chiamata a una routine di sistema è fallita. Errore durante l'accesso al PIN. PIN scaduto. PIN sbagliato. Formato del PIN non valido. PIN bloccato. PIN non inizializzato. PUK sbagliato. Formato del PUK non valido. PUK bloccato. Errore durante l'accesso al lettore. Non sono stati rilevati lettori sul sistema. Errore di condivisione della risorsa. Il documento non è stato firmato con la firma indicata. La lunghezza della firma è sbagliata. Il documento da firmare supera la dimensione massima consentita. Il sistema operativo ha annullato l'operazione. Timeout scaduto. L'elaborazione è fallita a causa di dati inattesi. CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 36 di 81

KC_E_USER_CANCELLED Operazione annullata dall'utente. CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 37 di 81

7.3.3 Utility 7.3.3.1 Descrizione delle proprietà 7.3.3.1.1 Proprietà IsKiosk Restituisce True se il computer è un chiosco, altrimenti False. object.iskiosk object.iskiosk (); Argomenti object Qualsiasi istanza di un oggetto SCardAccess. Note Il valore di questa proprietà può essere forzato modificando il valore di tipo stringa IsKiosk contenuto nella chiave di registro: HKEY_LOCAL_MACHINE\SOFTWARE SOFTWARE\Lombardia Integrata\Postazione del Cittadino\IsKiosk I valori possibili sono: - auto: determina automaticamente se il computer è un chiosco (questo è il valore predefinito se la chiave è assente o contiene un valore non riconosciuto); - yes: il computer è un chiosco; - no: il computer non è un chiosco. La suddetta chiave e il suo contenuto vengono creati dall installazione del software per chioschi. CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 38 di 81

7.3.3.2 Descrizione dei metodi 7.3.3.2.1 Metodo Reset Annulla le eventuali attività in corso sul componente e chiude le eventuali GUI aperte dal componente stesso. object.reset object.reset (); Argomenti object Qualsiasi istanza di un oggetto SCardAccess. Note Il componente interagisce con l utente attraverso GUI proprietarie. E quindi possibile che l utente interrompa l operazione estraendo la carta, ma lasciando aperta una GUI. Il codice client può usare questo metodo per chiudere le eventuali finestre aperte. Versioni Tutte le versioni. CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 39 di 81

7.3.4 Gestione del PIN Il PIN della CRS/CNS è una sequenza di numeri, composta da un minimo di 5 sino ad un massimo di 8 cifre. All atto dell emissione, le CRS/CNS distribuite da Regione Lombardia sono caratterizzate da un PIN di 5 cifre. Il PUK della CRS/CNS è una sequenza di numeri di 8 cifre. Tutti i metodi ai quali viene sottomesso un PIN e/o un PUK controllano che questo formato sia rispettato prima di sottometterlo alla carta. Quindi se il formato è sbagliato, il metodo fallirà senza che sia stato incrementato il contatore di sicurezza associato al PIN (o al PUK), in quanto il PIN (o il PUK) non è stato sottomesso alla carta; se invece il formato è corretto, ma il valore non corrisponde a quello memorizzato nella carta, il contatore di sicurezza relativo sarà incrementato perché il PIN (o il PUK) è stato sottomesso alla carta. Si rammenta che il contatore di sicurezza viene azzerato al successivo inserimento del valore corretto per l oggetto associato. Tuttavia se il contatore raggiunge un limite prefissato, l oggetto associato (PIN o PUK) viene bloccato e non è più utilizzabile. Il limite per il PIN è di 3 tentativi errati, quello per il PUK di 8. Lo spazio effettivamente occupato dal PIN sulla carta è di 8 byte, superiore quindi ai 5 accettabili come minimo (1 carattere = 1 byte). I byte eventualmente eccedenti vengono valorizzati con il valore FF 16 (notazione esadecimale). Questa operazione è trasparente per l applicazione, e viene riportata per sola informazione. CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 40 di 81

7.3.4.1 Descrizioni dei metodi 7.3.4.1.1 Metodo ChangePinUI Visualizza una finestra di dialogo per la modifica del PIN. object.changepinui () object.changepinui (); Argomenti object Qualsiasi istanza di un oggetto SCardAccess. Note Il componente aprirà una propria finestra per l inserimento dei dati per la modifica del PIN: Se l operazione ha successo, verrà mostrata una finestra di conferma del successo dell operazione: altrimenti comparirà un messaggio d errore. CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 41 di 81

7.3.4.1.2 Metodo UnblockPinUI Visualizza una finestra di dialogo per lo sblocco del PIN mediante l utilizzo del PUK. object.unblockpinui () object.unblockpinui (); Parametri object Qualsiasi istanza di un oggetto SCardAccess. Note Il componente aprirà una propria finestra per l inserimento del PUK e del nuovo PIN. Il successo dell operazione viene confermato dal messaggio: CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 42 di 81

7.3.4.1.3 Metodo VerifyPinUI Visualizza una finestra di dialogo per la verifica del PIN della CRS inserita. object.verifypinui () object.verifypinui (); Parametri object Qualsiasi istanza di un oggetto SCardAccess. Descrizione Il componente aprirà una propria finestra per l inserimento del PIN da verificare. Se il PIN inserito corrisponde a quello della carta, comparirà un messaggio di conferma: altrimenti un messaggio d errore. Si noti che il metodo in oggetto è implementato per fini diasgnostici, e non restituisce al codice chiamante alcuna informazione per via programmatica sull esito dell operazione svolta. Il codice PIN, infatti, serve per abilitare l'accesso ai dati memorizzati nella carta e per consentire l'utilizzo degli oggetti di sicurezza in essa contenuti. Per questo motivo la funzione del codice PIN è tipicamente locale. E altresì importante rammentare che la Carta Nazionale dei Servizi è uno strumento di autenticazione forte in rete basato sulle quantità crittografiche in essa contenute, e pertanto è opportuno che i processi di autorizzazione all'accesso si basino su questo tipo di autenticazione che prevede la sottomissione del PIN alla carta senza darne visibilità alle applicazioni remote. CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 43 di 81

7.3.5 Attestazione L attestazione eseguita tramite una CRS/CNS è una firma leggera. Per firma leggera si intende una firma elettronica la cui valenza probatoria in sede di Giudizio è a discrezione del Giudice, perché consente l'identificazione e l'autenticazione in rete, ma non di chi fisicamente sottoscrive il documento. Di seguito vengono descritti i metodi per eseguire l attestazione. Siccome sono richieste diverse chiamate, riportiamo anche uno schema che evidenzia la successione delle operazioni, dalla configurazione alla chiusura/annullamento della sessione di attestazione. Si noti che, su indicazione di CNIPA, non è stata implementata la funzionalità di attestazione di buffer e/o di form: la connessione SSL ottiene gli stessi risultati (agendo sull intero canale trasmissivo) rendendo superfluo l uso dell attestazione per processi con un esito immediato (es. accesso autenticato a dati sensibili). Diversamente, se l obiettivo è di sottoporre istanze che saranno processate nel tempo, la soluzione preferibile è quella di far generare/completare all utente il file dell istanza, farlo attestare e, quindi, sottometterlo alla P.A. Un ipotesi su come può essere gestito, a livello applicativo, un siffatto processo di attestazione è la seguente: - L applicazione WEB che richiama le funzionalità esposte dal middleware in oggetto provvede a far scaricare sul PC del possessore della CRS un file che deve essere sottoposto ad attestazione (supponiamo sia un modulo in formato PDF pre-compilato con i dati del richiedente); - L utente, possessore della CRS, compila tale modulo con strumenti a lui a disposizione (nell ipotesi Adobe Acrobat), valorizzandolo con le informazioni significative a livello applicativo; - Il modulo compilato in tutte le sue parti viene così salvato su file system e reso disponibile per l attestazione; - L applicazione WEB invoca la funzione del middleware in oggetto, che in sequenza: a) propone un browse su file system per la selezione del file da attestare; b) dopo l avvenuta selezione da parte dell utente, mette in read only il file e chiede di inserire il PIN della CRS, eventualmente visualizzando una preview del file che si sta per attestare; c) appone l attestazione, producendo un file.p7m che contiene il risultato dell attestazione, o alternativamente restituendo al chiamante l intero PKCS#7 risultante dell attestazione. Si noti che le funzioni descritte (browse del file, preview, attestazione) sono esposte sia come API singole (la cui chiamata è dunque delegata all applicativo chiamante), sia come una singola API che, tramite un unica interfaccia grafica propria del componente, consentirà la selezione del file da attestare, la sua eventuale visualizzazione, e la sua attestazione. Alla chiusura della sessione di attestazione, viene chiusa anche l applicazione eventualmente lanciata per la visualizzazione preventiva. 7.3.5.1 Formato del file attestato Il risultato dell operazione di attestazione è un file in formato PKCS#7 MIME, identificato dall estensione P7M. Il nome di questo file corrisponderà al nome completo (cioè comprensivo di eventuale estensione) del documento attestato, a cui viene ulteriormente aggiunta l estensione.p7m (ad es.: se si attesta il file modulo.pdf il file risultante sarà modulo.pdf.p7m). Questa convenzione nella denominazione è conforme alle indicazioni del CNIPA (cfr. "Linee Guida per l'utilizzo della Firma Digitale", versione 1.1, maggio 2004, paragrafo 10.1 e successive deliberazioni). La validità del file PKCS#7 generato rispetto al formato previsto a livello normativo può essere verificata, ad esempio, con i software di verifica firma censiti da CNIPA (http://www.cnipa.it/). Poiché trattasi di una firma leggera, il certificato della CA che ha emesso il certificato del firmatario non viene incluso nel PKCS#7 risultante. Il file attestato conterrà quindi il certificato del firmatario, il documento originario, l hash firmato del documento originario (la cosiddetta firma ) e la data e l ora di apposizione della firma (i valori usati sono quelli locali del PC). CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 44 di 81

7.3.5.2 Procedura per l attestazione Si assume di aver istanziato il componente per la firma leggera con il nome PdlC. INIZIO PERSONALIZZAZIONE Il documento da firmare è un PDF. PdLC.FileFilterIndex = KC_BROWSE_FILTER_INDEX_PDF oppure Il documento da firmare è un PDF. PdLC.DefaultFileType = pdf SELEZIONE DEL FILE DA FIRMARE PdLC.FileToSign = c:\mydocument.doc Impostazione diretta. oppure PdLC.BrowseForFileToSign Navigazione nel file-system. Oppure Scaricamento via HTTPS. PdLC.SetDocument https://dcss.crs.lombardia.it/document.pdf https://dcss.crs.lombardia.it/document.pdf,, pdf VISUALIZZAZIONE PREVENTIVA PdLC.PreviewFileToSign ewfiletosign GENERAZIONE DELLA FIRMA PdLC.SignSelectedFile Acquisizione della firma ElaboraFirma PdLC.Signature Formato binario. oppure Acquisizione della firma in Base 64 Formato Base 64 ElaboraFirmaInBase64 PdLC.SignatureAsBase64 SALVATAGGIO SU DISCO DELLA FIRMA PdLC.WriteSignatureToFile CHIUSURA DELLA SESSIONE DI FIRMA (ritorna nello stato INIZIO) Questa fase è accessibile da qualunque altra per annullare la sessione di firma. PdLC.CloseSigningSession CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 45 di 81

7.3.5.3 Metodo BrowseForFileToSign Scelta del documento da attestare mediante navigazione nel file system. object.browseforfiletosign () object.browseforfiletosign (); Parametri object Qualsiasi istanza di un oggetto SCardAccess. Note Il componente aprirà una propria finestra di navigazione nel file-system per la scelta del file da attestare. Il tipo di finestra che comparirà dipende dal sistema operativo usato. Se l utente seleziona un file, il percorso completo del file sarà contenuto nella proprietà FileToSign. Non è consentita la selezione di file con estensioni diverse da quelle previste (vedi proprietà PreviewableExtensions). Vedi anche Proprietà FileToSign. Proprietà FileFilterIndex. Proprietà PreviewableExtentions. Metodo SetDocument. CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 46 di 81

7.3.5.4 Proprietà CanDownload Restituisce True se sul sistema è presente il componente per il download di documenti remoti, altrimenti False. object.candownload () object.candownload (); Parametri object Qualsiasi istanza di un oggetto SCardAccess. Vedi anche Metodo SetDocument. CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 47 di 81

7.3.5.5 Metodo CloseSigningSession Chiude l eventuale sessione di attestazione in corso. object.closesigningsession () object.closesigningsession (); Parametri object Qualsiasi istanza di un oggetto SCardAccess. Note La chiusura della sessione di attestazione comporta il rilascio di tutte le risorse impegnate per l'operazione, compreso il file bloccato per l attestazione, che sarà di nuovo modificabile. CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 48 di 81

7.3.5.6 Proprietà DefaultFileType Imposta o restituisce l estensione predefinita per i file all interno della finestra di navigazione nel file-system: object.defaultfiletype object.getdefaultfiletype (); object.setdefaultfiletype (newvalue); Parametri object Qualsiasi istanza di un oggetto SCardAccess. newvalue Valore da assegnare alla proprietà. Note Il valore predefinito per questa proprietà è doc. Vedi anche Metodo BrowserForFileToSign. CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 49 di 81

7.3.5.7 Proprietà FileFilterIndex Questa proprietà è deprecata e mantenuta per compatibilità con le versioni precedenti. La proprietà alternativa è DefaultFileType. Restituisce il codice dell estensione predefinita per i file all interno della finestra di navigazione nel file-system: object.filefilterindex object.getfilefilterindex (); object.setfilefilterindex (newvalue); Parametri object Qualsiasi istanza di un oggetto SCardAccess. newvalue Valore da assegnare alla proprietà. Note I possibili valori per questa proprietà sono: Valore Descrizione KC_BROWSE_FILTER_INDEX_DOC Preseleziona i file con estensione DOC. KC_BROWSE_FILTER_INDEX_PDF Preseleziona i file con estensione PDF. KC_BROWSE_FILTER_INDEX_RTF Preseleziona i file con estensione RTF. KC_BROWSE_FILTER_INDEX_TXT Preseleziona i file con estensione TXT. Il valore predefinito per questa proprietà è KC_BROWSE_FILTER_INDEX_DOC. In JavaScript/Java queste costanti sono precedute da LISIT., come ad esempio: LISIT.KC_BROWSE_FILTER_INDEX_DOC Vedi anche Proprietà DefaultFileType. Metodo BrowserForFileToSign. CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 50 di 81

7.3.5.8 Proprietà FileToSign Imposta o restituisce il percorso assoluto del file da attestare. object.filetosign object.getfiletosign (); object.setfiletosign (newvalue); Parametri object Qualsiasi istanza di un oggetto SCardAccess. newvalue Valore da assegnare alla proprietà. Note Il file specificato verrà bloccato fino al completamento della sessione di attestazione o all'annullamento della stessa. Pertanto alle altre applicazioni sarà possibile aprire il file solo per leggerlo. Tale precauzione si rende necessaria per securizzare i dati che si stanno per attestare. Non è consentita la selezione di file oltre i 6 MB. Questa proprietà può essere valorizzata anche attraverso il metodo BrowseForFileToSign. Questa proprietà non viene valorizzata se il documento viene scaricato via HTTPS. Vedi anche Metodo BrowseForFileToSign. CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 51 di 81

7.3.5.9 Proprietà FileToSignFilter Restituisce una stringa contenente il filtro usato nella finestra per la selezione dei file mediante navigazione nel file system. object.filetosignfilter object.getfiletosignfilter (); Parametri object Qualsiasi istanza di un oggetto SCardAccess. Note Questa proprietà è accessibile solo in lettura. Il valore predefinito per questa proprietà genera il filtro: Vedi anche Proprietà FileFilterIndex CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 52 di 81

7.3.5.10 Proprietà IsSigningSessionPending Restituisce True se è in corso una sessione di attestazione, altrimenti False. object.issigningsessionpending object.issigningsessionpending (); Parametri object Qualsiasi istanza di un oggetto SCardAccess. CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 53 di 81

7.3.5.11 Proprietà PreviewableExtentions Restituisce una stringa contenente le estensioni di file considerati documenti, separate da punto e virgola. object.previewableextentions object.getpreviewableextentions (); Parametri object Qualsiasi istanza di un oggetto SCardAccess. CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 54 di 81

7.3.5.12 Proprietà PreviewFileToSign Visualizza il file da attestare aprendolo con l applicazione associata. object.previewfiletosign () object.previewfiletosign (); Parametri object Qualsiasi istanza di un oggetto SCardAccess. Note I file RTF e TXT vengono aperti con l applicazione predefinita di Windows Wordpad, gli altri file con l applicazione associata. La visualizzazione è soggetta a conferma da parte dell utente. CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 55 di 81

7.3.5.13 Metodo SetDocument Scaricamento e attestazione di un documento disponibile a un URL su protocollo HTTP/HTTPS. object.setdocument (Url, Extention) Metodo non disponibile per l interfaccia JavaScript/Java. Parametri object Qualsiasi istanza di un oggetto SCardAccess. Url URL dalla quale scaricare il documento. Extention Estensione che identifica il tipo di file disponibile all URL indicata. Note Il codice client non ha accesso sotto forma di file ai dati scaricati (la proprietà FileToSign non viene valorizzata), quindi questo metodo si presta particolarmente bene per l integrazione nei chioschi. Il PKCS#7 risultante dall operazione di attestazione non è salvabile su disco (metodo WriteSignatureToFile), ma è accessibile sia in formato binario (proprietà Signature) sia base 64 (proprietà SignatureAsBase64). Su Microsoft Windows 2000, questa funzione è disponibile solo se sul PC è il Microsoft XML Parser, versione 3.0 Service Pack 5 (o successivo). Al momento in cui scriviamo, il pacchetto di installazione (2 MB circa) di questa libreria è disponibile all URL: http://download.microsoft.com/download/a/5/e/a5e03798-2454-4d4b-89a3-4a47579891d8/msxml3.msi E comunque preferibile verificare sul sito di Microsoft la disponibilità di una versione più recente. Per verificare in maniera programmatica la disponibilità di questo metodo, vedere la proprietà CanDownload. Sulla sola piattaforma Windows Vista, il download è possibile solamente in una zona di file system resa accessibile dal Sistema Operativo. Tale restrizione viene comunicata all utente con la GUI che segue: CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 56 di 81

7.3.5.14 Proprietà Signature Restituisce un Array di Byte contenente il PKCS#7 risultante dall attestazione del documento. object. Signature object.getsignature (); Parametri object Qualsiasi istanza di un oggetto SCardAccess. Vedi anche Proprietà SignatureAsBase64. CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 57 di 81

7.3.5.15 Proprietà SignatureAsBase64 Restituisce una stringa contenente la codifica in Base64 del PKCS#7 risultante dall attestazione del documento. object. SignatureAsBase64 object.getsignatureasbase64 (); Parametri object Qualsiasi istanza di un oggetto SCardAccess. Vedi anche Proprietà Signature. CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 58 di 81

7.3.5.16 Metodo SignFileUI Apertura di una GUI che gestisce una sessione completa di attestazione. object. SignFileUI () object. signfileui (); Parametri object Qualsiasi istanza di un oggetto SCardAccess. Note La GUI mostrata consente di eseguire tutte le operazioni associate all attestazione: Se l utente attesta effettivamente il file, il risultato dell attestazione verrà scritto direttamente su disco. Sulla sola piattaforma Windows Vista, il risultato dell attestazione viene posizionato nell unico folder messo a disposizione dal Sistema Operativo per l accesso al disco. L utente viene informato di questa restrizione con la seguente GUI: CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 59 di 81

7.3.5.17 Metodo SignSelectedFile Attesta il documento correntemente selezionato. object. SignSelectedFile () object. signselectedfile (); Parametri object Qualsiasi istanza di un oggetto SCardAccess. Note L attestazione viene mantenuta in memoria fino alla chiusura della sessione di attestazione ed è accessibile sia in formato base 64, oppure può essere scritta su file. Per liberare la memoria occupata dall attestazione occorre chiudere la sessione. Il componente aprirà una propria finestra informativa, che richiede l inserimento del PIN. Vedi anche Metodo BrowseForFileToSign. Proprietà FileToSign. Proprietà Signature. Proprietà SignatureAsBase64. Metodo WriteSignatureToFile. CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 60 di 81

7.3.5.18 Metodo WriteSignatureToFile Scrive su disco il PKCS#7 risultante dall attestazione. object. WriteSignatureToFile () object. writesignaturetofile (); Parametri object Qualsiasi istanza di un oggetto SCardAccess. Note Il nome del file contenente l attestazione sarà lo stesso del file originale, con l aggiunta dell estensione.p7m, che identifica i file in formato PKCS#7 MIME. Il file verrà creato nella stessa cartella del file di riferimento, e se esiste già un file con lo stesso nome, verrà richiesta di conferma alla sovrascrittura. Non è consentita la scrittura su disco del PKCS#7 risultante dalla firma di un documento scaricato via HTTP/HTTPS. Sulla sola piattaforma Windows Vista, il risultato dell attestazione viene posizionato nell unico folder messo a disposizione dal Sistema Operativo per l accesso al disco. L utente viene informato di questa restrizione con la seguente GUI: CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 61 di 81

7.3.6 Lettura di file presenti sulla carta Il componente espone metodi per la lettura di file dalla carta. Questi metodi accettano il percorso del file da leggere e restituiscono una sequenza di byte con il contenuto del file stesso. L indicazione del file da leggere può avvenire in diversi modi: - in codifica esadecimale secondo lo standard ISO/IEC 7816-4 (es. 3F002F02), oppure - con i nomi simbolici definiti dalle specifiche Netlink (es. EF.NKAF), oppure - con i nomi simbolici definiti dalle specifiche CNS (es. EF.Dati_personali). L utente viene informato della natura dei dati richiesti e ne autorizza o rifiuta l accesso. Se il file è ad accesso libero, la GUI si presenterà come questa: Se il file è protetto da PIN la GUI sarà invece simile a questa (notare la casella per l inserimento del PIN): CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 62 di 81

7.3.6.1 Metodo GetAsnBerFileContent Restituisce un Array di Byte con il contenuto significativo di un file su carta che si sa a priori essere in formato ASN.1 BER. object.getasnberfilecontent (FileId) Object.getAsnBerFileContent (FileId); Parametri Object FileId Qualsiasi istanza di un oggetto SCardAccess. Identificatore del file da leggere. Note Il formato del file non è verificato, ma viene controllata solo la lunghezza dell elemento radice. Gli eventuali byte eccedenti non verranno restituiti. Questo significa che il metodo restituisce comunque dei dati se la lunghezza dell elemento radice è espressa correttamente secondo la codifica ASN.1 BER. Per quanto riguarda i file specificati dal progetto Netlink, il formato degli stessi è dettagliato nel documento: http://www.cnipa.gov.it/site/_files/netlink_dati_pdc_v2.0.pdf Si rimanda alle note del metodo GetBinaryFileContent. Vedi anche Metodo GetAsnBerFileContentAsBase64 Metodo GetBinaryFileContent Metodo GetBinaryFileContentAsBase64 CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 63 di 81

7.3.6.2 Metodo GetAsnBerFileContentAsBase64 Restituisce una stringa contenente la codifica in Base64 del contenuto significativo di un file su carta che si sa a priori essere in formato ASN.1 BER. object.getasnberfilecontentasbase64 (FileId) Object.getAsnBerFileContentAsBase64 (FileId); Parametri Object FileId Qualsiasi istanza di un oggetto SCardAccess. Identificatore del file da leggere. Note Si rimanda alle note del metodo GetAsnBerFileContent. Vedi anche Metodo GetAsnBerFileContent Metodo GetBinaryFileContent Metodo GetBinaryFileContentAsBase64 CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 64 di 81

7.3.6.3 Metodo GetBinaryFileContent Restituisce un Array di Byte con l intero contenuto dell'area di memoria dedicata a un file. object.getbinaryfilecontent (FileId) object.getbinaryfilecontent (FileId); Parametri object Qualsiasi istanza di un oggetto SCardAccess. FileId Identificatore del file da leggere. Note Il contenuto significativo del file potrebbe essere più corto del valore restituito. L interpretazione dei dati è a carico del chiamante. Il formato dei file binari specificati dal progetto CNS, in particolare del file EF.DatiPersonali, è pubblicato da CNIPA nel documento: http://www.cnipa.gov.it/site/_files/lineeguidacns(v3.0).rtf Se interessa solo il contenuto significativo di un file che si sa a priori codificato in ASN.1 BER, è possibile usare il metodo GetAsnBerFileContent. Il percorso del file espresso indifferentemente come: - nome simbolico definito dalle specifiche CNS (es. "EF.Dati_personali"); - nome simbolico definiti dalle specifiche Netlink (es. "EF.NKAF"); - percorso assoluto in codifica esadecimale secondo lo standard ISO/IEC 7816-4 (es. "3F002F02 : notare l'assenza di separatori, spazio o altro, fra la rappresentazione testuali dei byte). Se viene usato un nome simbolico, i caratteri. (punto), (spazio) e _ (sottolineatura) sono ignorati. Per esempio gli identificatori: o EF.DATIPERSONALI ; o EF.DatiPersonali ; o ef.dati personali identificano lo stesso file. Vedi anche Metodo GetAsnBerFileContent Metodo GetAsnBerFileContentAsBase64 Metodo GetBinaryFileContentAsBase64 CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 65 di 81

7.3.6.4 Metodo GetBinaryFileContentAsBase64 Restituisce una stringa contenente la codifica in Base64 dell intero contenuto dell'area di memoria dedicata a un file. object.getbinaryfilecontentasbase64 (FileId) object.getbinaryfilecontentasbase64 (FileId); Parametri object Qualsiasi istanza di un oggetto SCardAccess. FileId Identificatore del file da leggere. Note Si rimanda alle note del metodo GetBinaryFileContent. Vedi anche Metodo GetAsnBerFileContent Metodo GetAsnBerFileContentAsBase64 Metodo GetBinaryFileContent CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 66 di 81

7.3.7 Diagnostica In questo gruppo vengono descritti i metodi diagnostici per la risoluzione di eventuali problemi di configurazione. Questi metodi ricavano informazioni sulla carta e sull ambiente di esecuzione, ma non informazioni personali, e sono soggetti a conferma dell utente una sola volta per sessione. CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 67 di 81

7.3.7.1 Descrizione dei metodi 7.3.7.1.1 Metodo About Visualizza le informazioni sulla versione del componente e l ambiente di esecuzione. object. About () object.about (); Parametri object Qualsiasi istanza di un oggetto SCardAccess. Note In Windows 2000 e superiori il testo contenuto nella finestra di messaggio mostrata è copiabile negli appunti con Ctrl+C e quindi incollabile come testo. Vedi anche Proprietà Version. CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 68 di 81

7.3.7.2 Metodo CheckSigning Verifica il corretto funzionamento dell attestazione. object.checksigning () object.checksigning (); Parametri object Qualsiasi istanza di un oggetto SCardAccess. Note Per eseguire la verifica, il componente richiederà il PIN della carta con una GUI simile a quella usata per l attestazione vera e propria: CRS-ISAU-SIAU#33,V.06.2,02-02-2009 Pagina 69 di 81