PROCEDURA DI ACCREDITAMENTO

Transcript

1 Procedura di accreditamento Solution Partner CRS PROCEDURA DI ACCREDITAMENTO per l iscrizione all Albo dei Solution Partner CRS in quanto produttori / distributori di prodotti CRS Ready in ambito Pubblica Amministrazione Locale Allegato 7 Posto di Lavoro del Cittadino Allegato 7

2 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: 05 PVCS: 9 Data di emissione: Stato: LISIT LI Funzione Nome Firma Redazione Area Servizi Applicativi e Middleware Alberto Zanini Preverifica Area Servizi Applicativi e Middleware Pierluigi Valenti Preapprovazione UO Progettazione e Sviluppo Nicola Contardi Verifica Architettura e Supervisione Progett J.Mason Approvazione Architettura e Supervisione Progett R.Ranza LI Emissione Project Office Gianluca Cesare CRS-ISAU-SIAU#33,V.05, Pagina 2 di 89

3 CRONOLOGIA DELLE VERSIONI Num. versione Sintesi delle variazioni 1 Prima versione 2 Rilascio delle librerie crittografiche apposite per il 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 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 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 la firma 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. Tutte le precedenti versioni. SOSTITUISCE/MODIFICA CRS-SISS Stadio 2 LIMITI DI UTILIZZO DEL DOCUMENTO CRS-ISAU-SIAU#33,V.05, Pagina 3 di 89

4 INDICE DEL DOCUMENTO 1 INTRODUZIONE SCOPO E CAMPO DI APPLICAZIONE RIFERIMENTI ACRONIMI E DEFINIZIONI GENERALITA FUNZIONALITA ED ARCHITETTURA FUNZIONALITÀ Autenticazione SSL Amministrazione del PIN Lettura di file presenti sulla carta Attestazione Diagnostica Traduzione in XML dei dati presenti sulla carta ARCHITETTURA FUNZIONALE Identificazione delle componenti Aggiornamento delle componenti e reperibilità Caricamento degli ActiveX Marcatura sicura degli ActiveX Analisi e specifica dei requisiti di sicurezza AUTENTICAZIONE SSL Caricamento del certificato per l autenticazione Passaggio alla pagina protetta Autenticazione Conservazione dello stato SSL GESTIONE CARTA ED ATTESTAZIONE TRADUZIONE XML DEI DATI IN FORMATO ASN.1 BER DEFINIZIONE DELLE CLASSI DI INTERFACCIA Linguaggio di riferimento Gestione degli errori Gestione degli errori in Visual Basic/VBScript Valori delle costanti RILEVAZIONE DELLA PRESENZA DI CARTE E AUTENTICAZIONE UTENTE Descrizione dei metodi Metodo About Metodo Reset Metodo Start Descrizione delle proprietà Proprietà CardCount Proprietà CardState Proprietà SamplingDelayMsec Proprietà SISSCertificateState Proprietà Version Descrizione degli eventi Evento AfterSISSCertificateUpdate Evento BeforeSISSCertificateUpdate Evento OnCardStatusChange Evento OnCertificatesUpdated Descrizione degli errori GESTIONE CARTA, ATTESTAZIONE E DIAGNOSTICA Utility Descrizione dei metodi Metodo Reset Gestione del PIN...38 CRS-ISAU-SIAU#33,V.05, Pagina 4 di 89

5 Metodo ChangePinUI Metodo UnblockPinUI Metodo VerifyPinUI Attestazione Formato del file firmato...42 Procedura per l attestazione Metodo BrowseForFileToSign Metodo CloseSigningSession Proprietà DefaultFileType Proprietà FileFilterIndex Proprietà FileToSign Proprietà FileToSignFilter Proprietà IsFileToSignPreviewable Proprietà IsSigningSessionPending Proprietà PreviewableExtentions Proprietà PreviewFileToSign Metodo SetDocument Proprietà Signature Proprietà SignatureAsBase Metodo SignFileUI Metodo SignSelectedFile Metodo WriteSignatureToFile Lettura di file presenti sulla carta Metodo GetAsnBerFileContent Metodo GetBinaryFileContent Diagnostica Descrizione dei metodi Metodo About Metodo CheckSigning Proprietà CardAtr Proprietà CardReaderName Proprietà CNSManufacturer Metodo CNSType Proprietà CryptographicProvider Proprietà SISSCertificateIssuer Proprietà Version TRADUZIONE IN XML DEI DATI PRESENTI SULLA CARTA Descrizione dei metodi Metodo ASN1BERAsXML INSTALLAZIONE Verifica dell installazione APPENDICE INSERIMENTO DEGLI ACTIVEX IN UNA PAGINA HTML Instanziazione delle classi Gestione delle versioni Installazione manuale DISATTIVAZIONE DEGLI ACTIVEX COSTANTI UTILIZZATE DAI COMPONENTI File OcxCertUpdate.vbs File OcsKitCittadino.vbs RETURN CODE DI ERRORE CONFIGURAZIONE E RISOLUZIONE PROBLEMI Configurazione di Microsoft Internet Explorer Interazioni utente al primo accesso Installazioni con librerie crittografiche sperimentali Aggiornamento dei certificati per le fonti attendibili in Microsoft Internet Explorer Verifica dell installazione dei driver per il lettore di smart card Verifica aggiornamento dei certificati CRS-ISAU-SIAU#33,V.05, Pagina 5 di 89

6 1 INTRODUZIONE 1.1 SCOPO E CAMPO DI APPLICAZIONE Questo documento è destinato agli sviluppatori di applicazioni software basate sulla CNS e descrive la specifica e l uso dei componenti messi a disposizione dal pacchetto Posto di Lavoro del Cittadino (PdLC), distribuito dal progetto CRS-SISS. Il 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; - la firma di documenti (maggiori dettagli nei paragrafi successivi). Il Cittadino che desideri utilizzare dal proprio PC le applicazioni basate sul PdLC può reperire tutte le informazioni per la configurazione del PC stesso nella sezione dedicata alla Postazione Cittadino sul sito : Poiché la Carta Regionale dei Servizi (CRS) è stata abilitata come Carta Nazionale dei Servizi (CNS), strumento di accesso ai servizi in rete offerti da tutte le Pubbliche Amministrazioni, in questo documento useremo indifferentemente i due termini. 1.2 RIFERIMENTI CNS Carta Nazionale dei Servizi Functional Specification V.1.00; disponibile sul sito del CNIPA ( nella sezione dedicata alle specifiche tecniche della CNS. Progetto NetLink disponibile sul sito del CNIPA ( 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 ) 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 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 Posto 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 RTF Rich Text Format SISS Sistema Informativo Socio Sanitario SSL Security Socket Layer CRS-ISAU-SIAU#33,V.05, Pagina 6 di 89

7 TXT URL Windows XML TeXT file Universal Resource Locator Microsoft Windows extensible Markup Language CRS-ISAU-SIAU#33,V.05, Pagina 7 di 89

8 2 GENERALITA Il 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 Cittadino. Per l accesso da casa propria è sufficiente disporre di un PC connesso a Internet e di un lettore di smart card. L implementazione attuale è basata su tecnologia Microsoft ActiveX, che permette l utilizzo di componenti attivi all interno di pagine Web e una gestione più semplice della distribuzione del prodotto finale. Le funzioni messe a disposizione dal PdLC sono raggruppabili in tre macro-gruppi funzionali, ognuno dei quali corrisponde allo sviluppo di un componente ActiveX 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. Nel seguito del presente documento i singoli componenti del PdLC, sviluppati a partire dall identificazione dei tre macro-gruppi funzionali, verranno descritti nel loro aspetto funzionale e nelle interfacce programmatiche messe a disposizione degli sviluppatori del servizio. Le GUI del PdLC includono il logo della CRS; fanno eccezione: - la finestra di navigazione nel file-system per la selezione di un documento da firmare, perché fornita dal sistema operativo e condivisa fra tutte le applicazioni; - la finestra per l inserimento del PIN nell autenticazione utente, che riporta il logo della ditta fornitrice delle librerie crittografiche. CRS-ISAU-SIAU#33,V.05, Pagina 8 di 89

9 3 FUNZIONALITA ED ARCHITETTURA In questo illustriamo brevemente i servizi disponibili e l architettura di base del PdLC. 3.1 FUNZIONALITÀ I componenti del 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); - firmare un file presente su disco o scaricato via HTTPS (attestazione). - rilevare la configurazione del PC e della CRS, per risalire alla causa di eventuali malfunzionamenti. - tradurre in XML i dati presenti sulla carta 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. Client PdLC Internet Canale sicuro SSLv3 Server Web Utente collegato: Mario Rossi Amministrazione del PIN Il PdLC mette a disposizione dell utente le funzioni per una gestione completa del PIN della propria CRS: - verifica del PIN; - cambio del PIN; - sblocco del PIN attraverso l utilizzo del PUK 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, il 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 file Netlink). EF.Dati_personali Il sottoscritto Mario Rossi, nato a Milano il 04/04/1954 DICHIARA CRS-ISAU-SIAU#33,V.05, Pagina 9 di 89

10 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 firmare 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 alla firma; o scaricamento di un documento via HTTPS. - possibilità di visualizzazione preventiva del documento; - verifica temporale del certificato usato rispetto al periodo di validità; - inclusione di data e ora di firma (signing time) nel pacchetto PKCS#7 generato; - disponibilità della firma in formato base64 per la trasmissibilità su media di solo testo (es: ) Diagnostica Per semplificare la diagnosi di eventuali malfunzionamenti, il 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 firmare effettivamente un documento Traduzione in XML dei dati presenti sulla carta I dati registrati sulla CNS in formato ASN.1 BER vengono tradotti in formato XML per successivi trattamenti di Identificazione Cittadino e Classi di Esenzione Fuori Linea (ICCEFL componente estraneo al PdLC e non oggetto di trattazione in questo documento). 3.2 ARCHITETTURA FUNZIONALE Lo schema seguente illustra l architettura di base del 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 Identificazione delle componenti Per usufruire del servizio attraverso il 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. CRS-ISAU-SIAU#33,V.05, Pagina 10 di 89

11 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 ( A questo punto il Cittadino può richiedere la fruizione del servizio collegandosi alla pagina Web di distribuzione dello stesso e di proprietà dell ente erogatrice. Tale pagina contiene un riferimento remoto al componente per il PdLC sviluppato da LISIT. Il browser, in maniera nativa e del tutto trasparente all utente finale, verifica la presenza ed eventualmente la versione delle componenti ActiveX registrate sul client e, solo se necessario, procede con l installazione o all eventuale aggiornamento delle stesse Aggiornamento delle componenti e reperibilità L aggiornamento delle componenti del PdLC sarà curato da Lombardia Informatica, che metterà a disposizione sul sito ufficiale di progetto della CRS ( gli aggiornamenti relativi alle librerie crittografiche. Per i driver del lettore l utente dovrà contattare il produttore della periferica. L operazione di aggiornamento degli ActiveX, invece, avverrà in modalità trasparente per l utente sul client e ad opera di Lombardia Informatica sul server a cui gli enti erogatori del servizio faranno riferimento. Le URL in cui sono pubblicati i componenti ActiveX menzionati sono: Gli stessi ActiveX sono altresì reperibili ai seguenti indirizzi, che sono tuttavia in fase di dismissione e sono dunque da considerarsi deprecati : Agli indirizzi indicati è possibile reperire le ultime versioni stabili degli ActiveX implementati Caricamento degli ActiveX I riferimenti ai componenti vengono inseriti in una pagina Web, pubblicata su Internet, che costituisce la porta di accesso ai servizi fruibili dal cittadino e che chiameremo pagina di cortesia. Per espletare le proprie funzioni il componente ha bisogno di accedere alle risorse del sistema sul quale è eseguito (ad esempio per accedere alla carta, caricare i certificati, ecc.). Per ragioni di sicurezza, questo è possibile solo se il browser accorda al componente i relativi privilegi; la risposta dipenderà dalle impostazioni di protezione attive. La configurazione predefinita per le versioni 5 e 6 di Internet Explorer prevede: - esecuzione di ActiveX attivata; - scaricamento e installazione di ActiveX firmati: subordinata alla conferma dell utente; Explorer inoltre segnala come anonimi e pericolosi gli ActiveX firmati con un certificato non riconosciuto come attendibile; - esecuzione di ActiveX contrassegnati come sicuri: attivata. Si deduce che per consentire lo scaricamento, l installazione e l esecuzione dei componenti del PdLC con la configurazione predefinita del browser è necessario che questi siano: - firmati con un certificato riconosciuto come attendibile; - contrassegnati come sicuri. Gli ActiveX sono firmati con un certificato riconducibile a una CA OmniRoot, e quindi riconosciuto nativamente come attendibile. Per poter scaricare e/o aggiornare i componenti ActiveX, il profilo dell'utente che vi si connette deve comprendere i privilegi necessari. Ulteriori informazioni sulle modalità per l inserimento dei componenti nelle pagine Web sono disponibili in appendice. Una volta installati, i componenti sono eseguibili anche da utenti con privilegi limitati. CRS-ISAU-SIAU#33,V.05, Pagina 11 di 89

12 Al caricamento della pagina che usa i componenti, se questi non risultano già installati sul client oppure se risulta installata una versione precedente, Explorer determina che la necessità di un installazione/aggiornamento e, se compatibile con il livello di protezione attivo (è il caso delle impostazioni predefinite) procederà nell operazione, eventualmente dopo autorizzazione esplicita dell utente. I componenti sono censiti fra quelli installati in Internet Explorer con i seguenti nomi: Posto di Lavoro del Cittadino - Firma leggera; Posto di Lavoro del Cittadino - Autenticazione utente; Posto di Lavoro del Cittadino - Interprete dati Marcatura sicura degli ActiveX Gli ActiveX che costituiscono il pacchetto, a partire dalla versione , sono marcati come sicuri per funzionare con il livello di protezione predefinito di Microsoft Internet Explorer, sia in Internet che in locale. Pertanto non è più necessario configurare Internet Explorer, a meno che le impostazioni di protezione siano state personalizzate dall utente in maniera più restrittiva. Fa eccezione il componente per l autenticazione SSL che si qualifica come non sicuro in presenza della prima versione delle librerie crittografiche distribuite, fornite da Siemens; questo comportamento è intenzionale e previsto per supportare le installazioni già operative. La marcatura sicura ha determinato una restrizione delle funzionalità fornite dagli ActiveX. Pertanto non è più possibile: - specificare i tipi di file da considerare documenti e che è possibile firmare; è invece attivo un insieme fissato di tipi di file supportati, che comprende i formati di documento più diffusi: o documenti (*.TXT, *.RTF, *.DOC, *.PDF); o immagini (*.BMP, *.GIF, *.JPG, *.JPEG, *.PNG, *.TIF); - selezionare per la firma un tipo di file diverso da quelli appena indicati; - personalizzare il filtro contenuto nella finestra di navigazione nel file-system per la selezione del documento da firmare; rimane comunque possibile scegliere il tipo di file predefinito fra quelli disponibili (esattamente come prima). - modificare l intervallo predefinito di campionamento dello stato dei lettori per la rilevazione della presenza di una smart card; - selezionare per la firma un file di dimensione superiore a 6 MB; - salvare il documento firmato su disco se la dimensione di questo supera il 5% dello spazio ancora disponibile. In conseguenza della marcatura sicura inoltre: - la visualizzazione preventiva del documento prima della firma è soggetta ad autorizzazione da parte dell utente; - la lettura di ciascun file dalla CNS, anche se a lettura libera, è soggetta ad autorizzazione da parte dell utente; - l impostazione diretta del percorso di un documento da firmare è possibile se il percorso è assoluto e si riferisce a un file locale; - il testo contenuto nelle GUI è stato riscritto per informare meglio l utente sull attività in corso Analisi e specifica dei requisiti di sicurezza L esecuzione di contenuto attivo in una pagina Web rappresenta un potenziale rischio per la sicurezza e la privacy dell utente. Un componente ActiveX ospitato su una pagina Web, dopo autorizzazione anche implicita da parte dell utente, non è eseguito in una macchina virtuale, ed è completamente accessibile al codice script incorporato nella pagina Web che lo ospita. Per ragioni di sicurezza, i componenti, fin dal primo rilascio: - non consentono la cancellazione di file dal PC o dalla carta; - non memorizzano PIN e PUK della carta, ma ne richiedono l inserimento ogni volta che occorre eseguire un operazione privilegiata sulla carta; - non tracciano PIN e PUK della carta su log. Riportiamo la check-list predisposta per la valutazione della sicurezza degli ActiveX. Per ogni criterio viene descritta la soluzione che adottata dal PdLC. Nell'adozione delle contromisure abbiamo considerato utilizzo da parte di un utente finale con scarse competenze informatiche. Questi criteri sono relativi solo alle funzioni direttamente accessibili al codice client. CRS-ISAU-SIAU#33,V.05, Pagina 12 di 89

13 Invulnerabilità a parametri e dati non validi I valori dei parametri forniti sono sistematicamente controllati perché rientrino in quelli previsti. Invulnerabilità agli attacchi buffer overrun/heap overflow Tutti le proprietà e i metodi che accettano dei parametri di dimensione variabile sono potenzialmente vulnerabili a un attacco di questo tipo se i buffer usati internamente per l elaborazione sono a dimensione fissa. Pertanto tutti i buffer usati nel passaggio di valori sono dinamici. Inoltre le strutture dati usate verificano sistematicamente la validità dell accesso ai dati in memoria Nessuna assunzione sul formato dei dati forniti. La validazione del formato dei parametri viene eseguita prima di procedere con l elaborazione. Impossibilità di eseguire codice arbitrario La funzione di attestazione consente la visualizzazione dei documenti prima della firma. Alcuni formati di documenti, come ad esempio Microsoft Word, consentono di incorporare codice eseguibile all'interno dei documenti. Questa vulnerabilità non è eliminabile, perché dipende da eventuali vulnerabilità nel formato del documento e/o dell'applicazione usata per la visualizzazione. Vengono comunque prese delle misure di sicurezza: - I file selezionabili per la firma sono solo quelli previsti; - Se il file è un RTF o un TXT viene aperto con Wordpad; altrimenti l utente viene informato della possibile presenza di codice dannoso e deve autorizzare espressamente la visualizzazione. Impossibilità di creare file con un nome fornito dallo script Nessuno dei metodi disponibili prevede l esecuzione di un operazione di questo tipo. Impossibilità di creare file di dimensione arbitraria Questo requisito serve a impedire la saturazione del disco. La dimensione di una firma è limitata in conseguenza della limitazione della dimensione del documento da firmare e comunque relativamente al residuo spazio su disco. Impossibilità di leggere file con un nome fornito dallo script Il componente per l'attestazione consente di leggere il contenuto di un file, ma solo dopo che questo è stato firmato, e la firma richiede l'intervento esplicito dell'utente. Impossibilità di leggere/scrivere nel registro di configurazione, o in un file di configurazione (INI), il contenuto di una chiave specificata da script. Nessuno dei metodi disponibili prevede l esecuzione di un operazione di questo tipo. Impossibilità di eseguire una routine di sistema con parametri arbitrari La visualizzazione preventiva di un documento richiama la shell di Windows, ma solo dopo aver validato il percorso del file per assicurarsi che: o sia un documento; o non contenga caratteri di controllo; o sia un file locale. Creare o manipolare altri oggetti ActiveX decisi da script. Nessuno dei metodi disponibili prevede l esecuzione di un operazione di questo tipo. Impossibilità di accesso non autorizzato a informazioni registrate sul sistema ospite La lettura di file presenti sulla carta consente di ottenere diverse informazioni sull'utente. La legge sulla privacy impone che l'utente sia informato del prelievo di informazioni sul suo conto, in modo da poter esprimere il consenso. Il componente quindi informa l'utente che la pagina Web ha richiesto l'accesso a informazioni personali, specificandone la natura. Anche la lettura del PKCS#7 prodotto con la firma di un documento è soggetta a conferma da parte dell utente, soprattutto perché quasi sicuramente contiene dati personali. Impossibilità di danneggiare il sistema dell'utente Questa raccomandazione include anche la possibilità di errori nelle pagine Web. Le operazioni potenzialmente dannose, come la gestione del PIN, prevedono l interazione diretta con l utente con GUI proprietarie del componente. CRS-ISAU-SIAU#33,V.05, Pagina 13 di 89

14 4 AUTENTICAZIONE SSL Il componente di autenticazione lavora in background per il monitoraggio dell inserimento e dell estrazione della CRS nel primo lettore disponibile sul sistema. L instaurazione e la gestione della sessione SSL è garantita dal CSP sottostante. Il componente per l autenticazione SSL supporta anche il funzionamento come semplice rilevatore di inserimento/estrazione di smart card. In questo caso non è richiesta la presenza delle librerie crittografiche (CSP). 4.1 Caricamento del certificato per l autenticazione Attivando il componente per l autenticazione, l inserimento di una CNS causa il caricamento del certificato di autenticazione contenuto nella carta stessa. Al completamento di questa operazione il componente segnala al codice client che il certificato è stato caricato e si può procedere all autenticazione. La procedura per l eventuale verifica del caricamento del certificato è riportata in appendice. 4.2 Passaggio alla pagina protetta Appena il certificato per l autenticazione è disponibile, il codice client può iniziare una connessione SSL. Se il livello di protezione di Explorer lo prevede potrebbe essere visualizzata, una finestra che informa l utente del passaggio della connessione in modalità protetta. 4.3 Autenticazione Per poter accedere alla pagina protetta, il client deve autenticarsi al web server che espone il servizio (in questo caso la pagina) con un certificato rilasciato da una CA che sia riconosciuta dal server stesso in base a una sua lista, configurabile, di CA trusted. A fronte della richiesta di accesso viene, quindi, presentata a video la finestra di selezione del certificato client da inviare al server. Questa finestra mostra tutti e solo i certificati utente presenti sulla macchina e rilasciati da una CA riconosciuta dal server a cui si sta tentando l operazione di autenticazione. Se questa lista dovesse essere vuota, significa che nessun certificato caricato sul client consente di effettuare l autenticazione verso il server erogatore del servizio. CRS-ISAU-SIAU#33,V.05, Pagina 14 di 89

15 Poiché l autenticazione avviene attraverso meccanismi di crittografia a chiave pubblica che necessitano dell utilizzo della chiave privata risiedente sulla carta, dopo aver selezionato il relativo certificato, all utente verrà chiesto di digitare il PIN per effettuare l accesso alla carta stessa. Tale operazione corrisponde ad una vera e propria fase di autenticazione dell utente verso la carta. Figura 1 - Richiesta PIN per l'autenticazione SSL Una volta digitato il PIN e confermato mediante la pressione del tasto OK, tra il web server erogatore del servizio ed il client viene instaurato un canale di comunicazione protetto e la pagina viene caricata e mostrata dal browser Conservazione dello stato SSL 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. A partire dalla versione degli ActiveX, i browser aperti sulla Postazione del Cittadino vengono automaticamente chiusi ad avvenuta estrazione di una CNS che abbia compiuto almeno una operazione di firma (SSL v3, oppure attestazione). Si noti che nella 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. CRS-ISAU-SIAU#33,V.05, Pagina 15 di 89

16 CRS-ISAU-SIAU#33,V.05, Pagina 16 di 89

17 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.05, Pagina 17 di 89

18 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.05, Pagina 18 di 89

19 7 DEFINIZIONE DELLE CLASSI DI INTERFACCIA In questo capitolo descriviamo schematicamente l uso degli ActiveX che implementano i servizi del PdLC. Qui di seguito sono riportate le informazioni che si applicano alla definizione delle classi di interfaccia. 7.1 Linguaggio di riferimento La tecnologia Microsoft ActiveX è supportata da diversi linguaggi di scripting, ma l integrazione più diretta si ha con il linguaggio VBScript, supportato in maniera nativa da Internet Explorer. Pertanto questo è il linguaggio di scripting preso come riferimento. 7.2 Gestione degli errori Gli errori vengono segnalati con il lancio di eccezioni COM, intercettabili dal codice che usa il componente. La gestione delle eccezioni cambia a seconda del linguaggio utilizzato. Oltre alla possibilità di usare un codice d errore di sistema, i componenti definiscono dei codici d errore propri, segnalati nella documentazione che segue e i cui valori numerici sono riportati in appendice. 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 Gestione degli errori in Visual Basic/VBScript In Visual Basic/VBScript gli errori sono intercettati dal run-time e resi disponibili attraverso l oggetto predefinito Err. La proprietà Number contiene il codice dell errore; la proprietà Description contiene la descrizione, se disponibile. Il valore della proprietà Number è zero in caso di successo. 7.3 Valori delle costanti Per semplicità i valori delle costanti non sono riportati. In appendice è disponibile uno script VBScript con tutti i valori estratti da ciascuna libreria, per una comoda inclusione nelle proprie pagine. Per esempio, le costanti contenute nel file OcxCertUpdate.cab sono contenute nel file OcxCertUpdate.vbs. Per accedere a queste definizioni dai propri script è sufficiente includere nel codice HTML un elemento: <script language= VBScript src= OcxCertUpdate.vbs ></script> dove il parametro src va adattato all effettiva localizzazione dello script rispetto alla pagina chiamante (nell esempio si assume che sia nella stessa cartella). CRS-ISAU-SIAU#33,V.05, Pagina 19 di 89

20 7.4 RILEVAZIONE DELLA PRESENZA DI CARTE E AUTENTICAZIONE UTENTE Per la rilevazione dello stato del lettore e l autenticazione SSL è disponibile la classe CertUpdate. CODEBASE CLASSID F297-5CB9-4D8C-A2DB-CDFB8C69CB6D METODI About Mostra le informazioni sulla versione del componente. Reset Interruzione 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. SamplingDelayMsec Intervallo di campionamento dello stato dei lettori, in millisecondi. 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. OnCertificatesUpdated Deprecato (vedi descrizione) Notifica del cambiamento dello stato dei certificati. CRS-ISAU-SIAU#33,V.05, Pagina 20 di 89

21 7.4.1 Descrizione dei metodi Metodo About Visualizza le informazioni sulla versione del componente e l ambiente di esecuzione. object.about Parametri object Oggetto CertUpdate. 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 Metodo Version. CRS-ISAU-SIAU#33,V.05, Pagina 21 di 89

22 Metodo Reset Interruzione dell eventuali attività in corso sul componente, compresa la chiusura di eventuali GUI aperte. object.reset Parametri object Oggetto CertUpdate. 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.05, Pagina 22 di 89

23 Metodo Start Attivazione dell oggetto. object.start Parametri object Oggetto CertUpdate. Note L'oggetto è inattivo e non solleverà alcun evento finché questo metodo non viene chiamato. Questo metodo va chiamato solo una volta per attivare la rilevazione dello stato del lettore.. Una volta avviata l attività del componente, non è possibile interromperla. 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 del PdLC. Errori specifici 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. Vedi anche Proprietà UseSSL. Tutti gli eventi sollevati dal componente. CRS-ISAU-SIAU#33,V.05, Pagina 23 di 89

24 7.4.2 Descrizione delle proprietà Proprietà CardCount Proprietà di sola lettura che vale: - 1 se c è una carta nel lettore di smart card; - 0 se il lettore è vuoto. Count = object.cardcount Parametri Count object Variabile alla quale viene assegnato il valore della proprietà. Istanza di CertUpdate. 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.05, Pagina 24 di 89

25 Proprietà CardState Proprietà di sola lettura che riporta lo stato della connessione alla carta. State = object.cardstate Parametri object State Oggetto CertUpdate. Variabile che riceve il valore della proprietà CardState. 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. Vedi anche Proprietà CardCount. CRS-ISAU-SIAU#33,V.05, Pagina 25 di 89

26 Proprietà SamplingDelayMsec Proprietà di sola lettura contenente l intervallo di campionamento dello stato del lettore, in millisecondi. Interval = object.samplingdelaymsec Parametri object Oggetto CertUpdate. Interval Variabile che riceve il valore della proprietà SamplingDelayMsec. Note Il valore di questa proprietà è sempre PDLCITSSL_DEFAULT_SAMPLING_DELAY_MSEC. CRS-ISAU-SIAU#33,V.05, Pagina 26 di 89

27 Proprietà SISSCertificateState Proprietà di sola lettura che riporta lo stato di caricamento del certificato SISS. State = object.sisscertificatestate Parametri object State Oggetto CertUpdate. Variabile che riceve il valore della proprietà SISSCertificateState. 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. CRS-ISAU-SIAU#33,V.05, Pagina 27 di 89

28 Proprietà Version Proprietà di sola lettura con la versione del componente. Ver = object.version Parametri Object Ver Oggetto CertUpdate. Variabile che riceve il valore della proprietà Version. Note La versione viene restituita come stringa. CRS-ISAU-SIAU#33,V.05, Pagina 28 di 89

29 7.4.3 Descrizione degli eventi Evento AfterSISSCertificateUpdate Segnala che, a seguito dell inserimento/estrazione di una CNS, è stato completato l aggiornamento dei certificati. Sub Object_AfterSISSCertificateUpdate Gestione dell evento. End Sub 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.05, Pagina 29 di 89

30 Evento BeforeSISSCertificateUpdate Segnala che, a seguito dell inserimento/estrazione di una CNS, è iniziato l aggiornamento dei certificati. Sub Object_BeforeSISSCertificateUpdate Gestione dell evento. End Sub 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.05, Pagina 30 di 89

31 Evento OnCardStatusChange Segnala l inserimento/estrazione di una carta nel lettore. Sub Object_OnCardStatusChange Gestione dell evento. End Sub 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à CardCount, oppure 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à CardCount. Proprietà CardState. CRS-ISAU-SIAU#33,V.05, Pagina 31 di 89

32 Evento OnCertificatesUpdated Questo evento è stato sostituito dall evento AfterSISSCertificateUpdate. CRS-ISAU-SIAU#33,V.05, Pagina 32 di 89

33 7.4.4 Descrizione degli errori PDLCITSSL_E_SMARTCARD_CONTEXT Descrizione: Impossibile comunicare con il gestore delle smart card. Osservazioni: Non è stato possibile attivare la comunicazione con il gestore delle smart card e quindi non è possibile monitorare lo stato dei lettori.. PDLCITSSL_E_SMARTCARD_LISTENER Descrizione: Impossibile avviare il monitoraggio dello stato dei lettori. Osservazioni: N.A. PDLCITSSL_E_UNSUPPORTED_WINVER Descrizione: Piattaforma Microsoft Windows non supportata. La piattaforma di esecuzione (versione di Windows e Service Pack) non è supportata. Verificare la rispondenza del sistema con i requisiti del componente. Osservazioni: N.A. CRS-ISAU-SIAU#33,V.05, Pagina 33 di 89

34 7.5 GESTIONE CARTA, ATTESTAZIONE E DIAGNOSTICA Per la rilevazione dello stato del lettore e l autenticazione SSL è disponibile la classe LIKitCRS. CODEBASE CLASSID 15D151C C D794663BD6E About Reset Version ChangePinUI UnblockPinUI VerifyPinUI BrowseForFileToSign CloseSigningSession PreviewFileToSign SetDocument SignFileUI SignSelectedFile WriteSignatureToFile DefaultFileType FileToSign FileFilterIndex FileToSignFilter IsFileToSignPreviewable 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 firmare mediante navigazione nel file system. Chiusura (o annullamento) della sessione di firma. Apre il file da firmare per la lettura con l applicazione associata al tipo di file stesso. Firma un documento disponibile a un URL su protocollo HTTPS. Sessione di firma completamente gestita dal componente. Genera la firma del file correntemente selezionato. Scrive su disco in formato binario il PKCS#7 risultante dalla firma del documento. Proprietà Estensione predefinita per la finestra per la selezione del file da firmare mediante navigazione nel file system. Percorso del file da firmare. Filtro da preselezionare all apertura della finestra per la selezione del file da firmare mediante navigazione nel file system. Deprecato: usare DefaultFileType. Filtro usato dalla finestra per la selezione dei file mediante navigazione nel file system. Indica se il file selezionato è un documento ed è visualizzabile. Indica se è in corso una sessione di firma. 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 dalla firma del documento, in formato Base 64. GetAsnBerFileContent GetBinaryFileContent CheckSigning CardATR CNSManufacturer CNSType 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. DIAGNOSTICA Metodi Verifica la funzionalità dell attestazione. Proprietà Stringa di riconoscimento della carta. Produttore della carta. Tipo di CRS usata. CRS-ISAU-SIAU#33,V.05, Pagina 34 di 89

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

36 KC_E_SIZE_OVERFLOW KC_E_SYSTEM_CANCELLED KC_E_TIMEOUT KC_E_UNEXPECTED_DATA KC_E_USER_CANCELLED 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. Operazione annullata dall'utente. CRS-ISAU-SIAU#33,V.05, Pagina 36 di 89

37 7.5.1 Utility Descrizione dei metodi Metodo Reset Interruzione dell eventuali attività in corso sul componente, compresa la chiusura di eventuali GUI aperte. object.reset Parametri object Oggetto LIKitCRS. 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. CRS-ISAU-SIAU#33,V.05, Pagina 37 di 89

38 Gestione del PIN Il PIN della CRS è una stringa numerica di 5 caratteri. Il PUK della CRS è una stringa numerica di 8 caratteri. 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 accettati (1 carattere = 1 byte). I byte 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.05, Pagina 38 di 89

39 Metodo ChangePinUI Modifica del PIN. object.changepinui Parametri object Oggetto LIKitCRS. 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.05, Pagina 39 di 89

40 Metodo UnblockPinUI Sblocco del PIN attraverso il PUK object.unblockpinui Parametri object Oggetto LIKitCRS. 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.05, Pagina 40 di 89

41 Metodo VerifyPinUI Verifica del PIN. object.verifypinui Parametri object Oggetto LIKitCRS. 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.05, Pagina 41 di 89

42 7.5.2 Attestazione L attestazione eseguita tramite una CRS è 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 firma. Si noti che, su indicazione di CNIPA, non è stata implementata la funzionalità di firma 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 la firma leggera; - 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 firmare; 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 la firma leggera, producendo un file.p7m che contiene il risultato della firma, o alternativamente restituendo al chiamante l intero PKCS#7 risultante della firma. Si noti che le funzioni descritte (browse del file, preview, firma) 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 firmare, la sua eventuale visualizzazione, e la sua firma. Alla chiusura della sessione di firma, viene chiusa anche l applicazione eventualmente lanciata per la visualizzazione preventiva Formato del file firmato Il risultato dell operazione di firma è 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 firmato, a cui viene ulteriormente aggiunta l estensione.p7m (ad es.: se si firma il file modulo.pdf il file di firma 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 ( 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 firmato 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.05, Pagina 42 di 89

43 Procedura per l attestazione Si assume di aver istanziato il componente per la firma leggera con il nome PdlC. INIZIO Il documento da firmare è un PDF. PERSONALIZZAZIONE 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 pdf VISUALIZZAZIONE PREVENTIVA PdLC.PreviewFileToSign 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.05, Pagina 43 di 89

44 Metodo BrowseForFileToSign Scelta del documento da firmare mediante navigazione nel file system. object.browseforfiletosign Parametri object Oggetto LIKitCRS. Note Il componente aprirà una propria finestra di navigazione nel file-system per la scelta del file da firmare. 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.05, Pagina 44 di 89

45 Metodo CloseSigningSession Chiusura (o annullamento) dell eventuale sessione di firma in corso. object.closesigningsession Parametri object Oggetto LIKitCRS. Note La chiusura della sessione di firma comporta il rilascio di tutte le risorse impegnate per l'operazione, compreso il file bloccato per la firma, che sarà di nuovo modificabile. CRS-ISAU-SIAU#33,V.05, Pagina 45 di 89

46 Proprietà DefaultFileType Estensione predefinita per i file all interno della finestra di navigazione nel file-system: object.defaultfiletype = Extention Extention = object.defaultfiletype Parametri object Oggetto LIKitCRS. Extention Nella lettura, variabile che conterrà il valore della proprietà; nella scrittura, valore da assegnare alla proprietà. Note Il valore predefinito per questa proprietà è doc. Vedi anche Metodo BrowserForFileToSign. CRS-ISAU-SIAU#33,V.05, Pagina 46 di 89

47 Proprietà FileFilterIndex Questa proprietà è deprecata e mantenuta per compatibilità con le versioni precedenti. La proprietà alternativa è DefaultFileType. Estensione predefinita per i file all interno della finestra di navigazione nel file-system: object. FileFilterIndex = Index Index = object. FileFilterIndex Parametri object Index Oggetto LIKitCRS. Nella lettura, variabile che conterrà il valore della proprietà; nella scrittura, 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 KC_BROWSE_FILTER_INDEX_RTF KC_BROWSE_FILTER_INDEX_TXT Preseleziona i file con estensione PDF. Preseleziona i file con estensione RTF. Preseleziona i file con estensione TXT. Il valore predefinito per questa proprietà è KC_BROWSE_FILTER_INDEX_DOC. Vedi anche Proprietà DefaultFileType. Metodo BrowserForFileToSign. CRS-ISAU-SIAU#33,V.05, Pagina 47 di 89

48 Proprietà FileToSign Percorso assoluto del file da firmare. FilePath = object. FileToSign Lettura del valore. object. FileToSign = FilePath Scrittura del valore. Parametri object Oggetto LIKitCRS. FilePath Nella lettura, variabile che conterrà il valore del documento correntemente selezionato; nella scrittura, variabile che contiene il percorso completo del file da selezionare. Note Il file specificato verrà bloccato fino al completamento della sessione di firma 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.05, Pagina 48 di 89

49 Proprietà FileToSignFilter Filtro usato nella finestra per la selezione dei file mediante navigazione nel file system. Filter = object. FileToSignFilter Parametri object Oggetto LIKitCRS. Filter Variabile che conterrà il valore della proprietà. 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.05, Pagina 49 di 89

50 Proprietà IsFileToSignPreviewable Indica se il file selezionato è visualizzabile. IsDocument = object.isfiletosignpreviewable Parametri object Oggetto LIKitCRS. IsDocument Variabile che conterrà il valore della proprietà. Note Questa proprietà è accessibile solo in lettura e vale sempre True se è selezionato un file. CRS-ISAU-SIAU#33,V.05, Pagina 50 di 89

51 Proprietà IsSigningSessionPending Indica se è in corso una sessione di firma. Signing = object.issigningses IsSigningSessionPending sionpending Parametri object Oggetto LIKitCRS. Signing Variabile che conterrà il valore della proprietà. Note Questa proprietà è accessibile solo in lettura e vale True se è in corso una sessione di firma, altrimenti False. CRS-ISAU-SIAU#33,V.05, Pagina 51 di 89

52 Proprietà PreviewableExtentions Lista, separata da punto e virgola, delle estensioni di file considerati documenti. Documents = object.previewableextentions Parametri object Oggetto LIKitCRS. Documents Variabile che conterrà il valore della proprietà. Note Questa proprietà è accessibile solo in lettura. CRS-ISAU-SIAU#33,V.05, Pagina 52 di 89

53 Proprietà PreviewFileToSign Visualizzazione preventiva del file da firmare. object.previewfiletosign Parametri object Oggetto LIKitCRS. 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.05, Pagina 53 di 89

54 Metodo SetDocument Firma un documento disponibile a un URL su protocollo HTTPS. object.setdocument Url, Extention Parametri object Oggetto LIKitCRS. Url URL dalla quale scaricare il documento. Extention Estensione che identifica il tipo di file disponibile all URL indicata. Note Al momento sono consentite solo URL che iniziano per: 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 firma non è salvabile su disco (metodo WriteSignatureToFile), ma è accessibile sia in formato binario (proprietà Signature) sia base 64 (proprietà SignatureAsBase64). CRS-ISAU-SIAU#33,V.05, Pagina 54 di 89

55 Proprietà Signature Buffer contenente il PKCS#7 risultante dalla firma del documento, in formato binario. P7m = object.signature Parametri object P7m Oggetto LIKitCRS. Variabile che conterrà il valore della proprietà, come Array di Byte. Vedi anche Proprietà SignatureAsBase64. CRS-ISAU-SIAU#33,V.05, Pagina 55 di 89

56 Proprietà SignatureAsBase64 Buffer contenente il PKCS#7 risultante dalla firma del documento, in formato Base64. Base64 = object.signatureasbase64 Parametri object Base64 Oggetto LIKitCRS. Variabile che conterrà il valore della proprietà, come String. Vedi anche Proprietà Signature. CRS-ISAU-SIAU#33,V.05, Pagina 56 di 89

57 Metodo SignFileUI Apertura di una GUI che gestisce una sessione completa di firma. object.signfileui Parametri object Oggetto LIKitCRS. Note La GUI mostrata consente di eseguire tutte le operazioni associate alla firma: Se l utente firma effettivamente il file, il risultato della firma verrà scritto direttamente su disco. CRS-ISAU-SIAU#33,V.05, Pagina 57 di 89

58 Metodo SignSelectedFile Genera la firma del documento correntemente selezionato. object.signselectedfile Parametri object Oggetto LIKitCRS. Note La firma viene mantenuta in memoria fino alla chiusura della sessione di firma ed è accessibile sia in formato base 64, oppure può essere scritta su file. Per liberare la memoria occupata dalla firma occorre chiudere la sessione di firma. 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.05, Pagina 58 di 89

59 Metodo WriteSignatureToFile Scrive su disco il PKCS#7 risultante dalla firma del documento selezionato. object.writesignaturetofile Parametri object Oggetto LIKitCRS. Note Il nome del file contenente la firma 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 HTTPS. CRS-ISAU-SIAU#33,V.05, Pagina 59 di 89

60 7.5.3 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 (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.05, Pagina 60 di 89

61 Metodo GetAsnBerFileContent Lettura del contenuto significativo di un file su carta in formato ASN.1 BER. Asn1BerData = Object.GetAsnBerFileContent (FileId) Parametri Asn1BerData Variabile che riceve il contenuto del file identificato da FileId come Array di Byte.. Object Oggetto LIKitCRS. FileId Identificatore del file da leggere. Note Il metodo restituisce il contenuto del file, sotto forma di Array di Byte. 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. Si rimanda alle note del metodo GetBinaryFileContent. Vedi anche Metodo GetBinaryFileContent. CRS-ISAU-SIAU#33,V.05, Pagina 61 di 89

62 Metodo GetBinaryFileContent Lettura dalla carta dell intero contenuto dell'area di memoria dedicata a un file. Asn1BerData = Object.GetBinaryFileContent (FileId) Parametri object Oggetto LIKitCRS. FileId Identificatore del file da leggere. Note Il metodo restituisce l'intero contenuto dell'area di memoria dedicata al file, sotto forma di Array di Byte. Il contenuto significativo del file potrebbe essere più corto. Se interessa solo il contenuto significativo di un file 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 (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. CRS-ISAU-SIAU#33,V.05, Pagina 62 di 89

63 7.5.4 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, quindi sono soggetti a conferma dell utente una sola volta per sessione. CRS-ISAU-SIAU#33,V.05, Pagina 63 di 89

64 Descrizione dei metodi Metodo About Visualizza le informazioni sulla versione del componente e l ambiente di esecuzione. object.about Parametri object Oggetto LIKitCRS. 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.05, Pagina 64 di 89

65 Metodo CheckSigning Verifica il funzionamento dell attestazione. object.checksigning Parametri object Oggetto LIKitCRS. 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.05, Pagina 65 di 89

66 Proprietà CardAtr Stringa di identificazione della carta usata. Value = object.cardatr Parametri object Value Oggetto LIKitCRS. Variabile che conterrà il valore della proprietà. Note Questa proprietà è disponibile anche se la carta inserita non è una CNS.. CRS-ISAU-SIAU#33,V.05, Pagina 66 di 89

67 Proprietà CardReaderName Nome del lettore di smart card usato. Value = object.cardreadername Parametri object Value Oggetto LIKitCRS. Variabile che conterrà il valore della proprietà. Note Il nome del lettore di smart card usato dipende dal driver usato e potrebbe non corrispondere al nome riportato fisicamente sul lettore. CRS-ISAU-SIAU#33,V.05, Pagina 67 di 89

68 Proprietà CNSManufacturer Nome del produttore della CNS usata. Value = object.cnsmanufacturer Parametri object Value Oggetto LIKitCRS. Variabile che conterrà il valore della proprietà. Note Questa proprietà è disponibile solo se la carta inserita è una CNS. Se il produttore non viene riconosciuto, questa proprietà varrà Dato non disponibile. CRS-ISAU-SIAU#33,V.05, Pagina 68 di 89

69 Metodo CNSType Circuito di appartenenza della carta (reale oppure demo) e il set di chiavi Netlink usato (set del prototipo o nuovo set). Value = object.cnstype Parametri object Value Oggetto LIKitCRS. Variabile che conterrà il valore della proprietà. Note Questa proprietà è disponibile solo se la carta inserita è una CNS. Se il tipo di carta non viene riconosciuto, questa proprietà varrà Dato non disponibile. CRS-ISAU-SIAU#33,V.05, Pagina 69 di 89

70 Proprietà CryptographicProvider Nome delle librerie crittografiche usate. Value = object.cryptographicprovider Parametri object Value Oggetto LIKitCRS. Variabile che conterrà il valore della proprietà. CRS-ISAU-SIAU#33,V.05, Pagina 70 di 89

71 Proprietà SISSCertificateIssuer Distinguished Name dell ente che ha emesso il certificato SISS contenuto nella carta CRS. Value = object.sisscertificateissuer Parametri object Value Oggetto LIKitCRS. Variabile che conterrà il valore della proprietà. Note Questa proprietà è disponibile solo se la carta inserita è una CNS. CRS-ISAU-SIAU#33,V.05, Pagina 71 di 89

72 Proprietà Version Proprietà di sola lettura con la versione del componente. Ver = object.version Parametri Object Ver Oggetto LIKitCRS. Variabile che riceve il valore della proprietà Version. Note La versione viene restituita come stringa. CRS-ISAU-SIAU#33,V.05, Pagina 72 di 89

73 7.6 TRADUZIONE IN XML DEI DATI PRESENTI SULLA CARTA Le operazioni di traduzione in XML dei dati presenti sulla carta sono gestite dalla classe CRSInfo. CODEBASE CLASSID AA75-43AB F9-C5B35EC62B5D METODI ASN1BERAsXML Conversione in XML del contenuto di un file ASN.1 BER. CRS-ISAU-SIAU#33,V.05, Pagina 73 di 89

74 7.6.1 Descrizione dei metodi Metodo ASN1BERAsXML Conversione in XML dei dati codificati in ASN.1 BER.. XML = object.asn1berasxml (Asn1BerData)( Parametri XML. Object Variabile che riceve l XML corrispondente ai dati ASN.1 BER contenuti in Asn1BerData. Oggetto CrsInfo. Asn1BerData Array di Byte contenente il contenuto in ASN.1 BER del file. Note Il metodo restituisce comunque una stringa in XML valido, anche per file vuoti. CRS-ISAU-SIAU#33,V.05, Pagina 74 di 89

75 8 INSTALLAZIONE I componenti del PdLC, essendo ActiveX inseriti in una pagina Web, non prevedono il rilascio di un pacchetto di installazione dedicato, poiché vanno semplicemente messi a disposizione da un server Web come file binari e scaricati sulla postazione client direttamente dal browser sulla base delle informazioni fornite dalla stessa pagina. Il browser gestisce anche l aggiornamento. Al seguito del rilascio di una nuova versione, basterà sostituire i file messi a disposizione dal server, sarà poi il browser che, caricando le pagine, determinerà la necessità di aggiornare l installazione. Poichè il componente non deve necessariamente risiedere sullo stesso server sul quale è disponibile la pagina WEB, il Progetto richiede che siano inseriti i riferimenti alla URL a cui il componente è pubblicato sul sito di progetto, ovvero le già menzionate URL: Questo permette di localizzare il componente su un unico server al quale faranno riferimento tutte le pagine che usano il componente stesso, con ovvi vantaggi per la manutenzione evolutiva dello stesso. A livello client, si applicano i seguenti prerequisiti hardware e software: Prerequisiti Hardware Lettore smart card Compatibile: - con lo standard PC/SC, che definisce un insieme di regole per la comunicazione fra software e smart card; - con la norma ISO , che specifica le caratteristiche fisiche adottate per la CRS. Nota: la scelta dei dispositivi commerciali, anche se compatibili, può avere effetti rilevanti sui tempi di accesso alla carta introducendo ritardi (anche di parecchi secondi) nelle funzioni di accesso alla carta che si concretizzano in un elevato tempo per l apertura dei canali SSL, per l attestazione, la lettura dei file, ecc. Prerequisiti Software Sistema operativo Browser Internet Lettore smart card Librerie crittografiche Altre librerie Microsoft Windows 2000 Service Pack 4 o superiore. Microsoft Windows XP Service Pack 1 o superiore. Microsoft Internet Explorer 5 o superiore. Driver installati e funzionanti. In appendice è riportata la procedura per verificare questo punto. CSP Bit4Id versione o superiori Microsoft XML Parser (MSXML) 3.0 Service Pack 5 (SP5) o superiore Su Microsoft Windows 2000 se si usa la funzione di firma di documenti remoti potrebbe essere necessario installare il Microsoft XML Parser, versione 3.0 Service Pack 5 (o successiva). Al momento in cui scriviamo, il pacchetto di installazione (2 MB circa) di questa libreria è disponibile all URL: E comunque preferibile verificare sul sito di Microsoft la disponibilità di una versione più recente. I componenti sono destinati all inserimento in una pagina Web. Perché possano funzionare, o comunque perché sia possibile rilevare eventuali malfunzionamenti, sul browser deve essere abilitata l esecuzione di script. Ciò avviene CRS-ISAU-SIAU#33,V.05, Pagina 75 di 89

76 automaticamente lasciando impostate il livello predefinito di protezione di Internet Explorer, quindi non è richiesta alcuna personalizzazione. Tramite lo scripting, infatti, è possibile verificare se: - il browser usato è Microsoft Internet Explorer, al momento l unico browser supportato; - il componente è stato caricato correttamente. Per rilevare la disabilitazione degli script si usa l elemento NOSCRIPT: <NOSCRIPT> La pagina richiede l abilitazione dello scripting. </NOSCRIPT> Verifica dell installazione Per verificare l installazione dei componenti del PdLC: - aprire Internet Explorer; - selezionare Strumenti dal menu principale; - selezionare Opzioni Internet ; - selezionare la pagina Generale nella finestra Opzioni Internet; - cliccare su Impostazioni nella sezione File temporanei Internet; - cliccare su Visualizza oggetti... nella finestra Impostazioni; - comparirà l elenco dei componenti aggiuntivi installati: - verificare la presenza di: o Posto di Lavoro del Cittadino Autenticazione utente, versione x,y,z,w; o Posto di Lavoro del Cittadino Firma leggera, versione x,y,z,w; o Posto di Lavoro del Cittadino Interprete dati, versione x,y,z,w; tutti con il valore Installato nella voce Stato. Ulteriori informazioni sui prerequisiti client, corredate da istruzioni di installazione (ove applicabile), sono riportate e mantenute costantemente aggiornate, nella sezione dedicata al Posto di Lavoro del Cittadino, all indirizzo: CRS-ISAU-SIAU#33,V.05, Pagina 76 di 89

77 9 APPENDICE 9.1 INSERIMENTO DEGLI ACTIVEX IN UNA PAGINA HTML Instanziazione delle classi Per caricare un ActiveX in una pagina HTML si usa l elemento OBJECT. Il frammento di codice che segue istanzia l oggetto per la gestione della carta e la firma leggera e lo associa alla variabile PdLC. <OBJECT CLASSID="CLSID:15D151C C D794663BD6E" CODEBASE=" ID=PdLC TYPE="application/x-oleobject"> </OBJECT> I parametri dell elemento OBJECT da personalizzare sono evidenziati in carattere corsivo: - CLASSID: identificatore della classe da istanziare; - CODEBASE: l URL del file che contiene il componente e, opzionalmente, indicazione per la gestione delle versioni. - ID: identificatore della variabile che verrà valorizzata con un riferimento all istanza della classe. Nel codice script l accesso ai metodi e alle proprietà dell oggetto avverrà attraverso questa variabile. Siccome i componenti non sono grafici, è consigliabile annidare l elemento OBJECT all interno dell elemento HEAD Gestione delle versioni Si può specificare la versione minima del componente da usare con una determinata pagina HTML accodando la versione alla fine dell URL specificata nell attributo CODEBASE dell elemento OBJECT. Internet Explorer non verifica che il file remoto contenga effettivamente la versione dichiarata La versione indicata nell attributo CODEBASE deve corrispondere alla versione contenuta nel file remoto. Quando Internet Explorer carica una pagina che referenzia un componente da scaricare, sul client sono possibili i seguenti casi: - nessuna versione del componente è installata; - la versione richiesta è già installata; - è installata una versione precedente; - è installata una versione successiva. Specificando la versione minima del componente da usare, si può pilotare il comportamento di Internet Explorer in risposta a ognuno di questi casi. Internet Explorer può eseguire una delle seguenti azioni: - scaricare la versione più recente del componente; - non scaricare nulla: userà il componente già installato; - aggiorna la versione esistente con una versione successiva. Se l indicazione della versione minima è omessa, Internet Explorer verificherà se sul sistema è installata una versione qualsiasi e in caso negativo scaricherà e installerà il componente dall indirizzo specificato. Se è indicata una versione minima, Internet Explorer verificherà se sul sistema è installata una versione uguale o successiva e in caso negativo scaricherà e installerà il componente dall indirizzo specificato. Se per l indicazione di versione si usa il valore 1,-1,-1,-1, Internet Explorer verificherà la data di ultima modifica dei componenti installati, quindi si collegherà al sito che pubblica i componenti e richiederà informazioni sul file pubblicato, procedendo allo scaricamento e all installazione solo se risultano pubblicato un file più recente. Notare che in questo caso anche se il componente non venisse scaricato si sosterrebbe sempre il costo di uno scambio di header HTTP, perché Internet Explorer richiederà al server informazioni sul file remoto. Un caso particolare è quando per la versione si usa il valore 1,-1,-1,-1: questo valore indica a Internet Explorer di scaricare e installare la versione più recente del componente: se il componente è installato sul client, Internet Explorer scarica il componente solo se la data di ultima modifica è successiva alla data di installazione sul client. CRS-ISAU-SIAU#33,V.05, Pagina 77 di 89

78 Per un corretto utilizzo del componente e per un maggior controllo sulle versioni distribuite, tra le varie tecniche sopra individuate, il Progetto richiede che il riferimento all oggetto, all interno della pagina web, avvenga indicando il numero della versione messa a disposizione da Lombardia Informatica sul sito di riferimento ufficiale del progetto CRS Installazione manuale L installazione dei componenti è possibile solo se il profilo dell utente ha i privilegi richiesti (per esempio l utente fa parte del gruppo degli amministratori) Se nella pagina HTML si omette il parametro CODEBASE, il componente verrà istanziato solo se già installato sulla macchina. 9.2 DISATTIVAZIONE DEGLI ACTIVEX Dopo il rilascio di un componente ActiveX marcato come sicuro è possibile che venga scoperta una vulnerabilità che era sfuggita ai test. In questo caso è possibile configurare Internet Explorer affinché non istanzi più il componente difettoso in nessun caso. Siccome la disattivazione richiede l intervento sul PC, è necessario contattare gli utenti che hanno scaricato e installato il componente. Microsoft fornisce le istruzioni per la disattivazione di un ActiveX nell articolo How to stop an ActiveX control from running in Internet Explorer, disponibile su MSDN. Le operazioni descritte sono eseguibili anche da programma. C è quindi la possibilità di pubblicare una patch che le esegua automaticamente. Al momento in cui scriviamo, l articolo è disponibile a questo indirizzo: COSTANTI UTILIZZATE DAI COMPONENTI File OcxCertUpdate.vbs Le costanti qui riportate sono utili in fase di integrazione del componente per l autenticazione SSL. ' modulo Costants Const PDLCITSSL_DEFAULT_SAMPLING_DELAY_MSEC = 10 ' modulo CardStates Const CARD_STATE_NULL = 0 Const CARD_STATE_ERROR = 1 Const CARD_STATE_EMPTY = 2 Const CARD_STATE_READY = 3 Const CARD_STATE_MUTE = 4 Const CARD_STATE_BAD_CARD = 5 ' modulo SISSCertificateStates Const SISS_CERTIFICATE_STATE_NULL = 0 Const SISS_CERTIFICATE_STATE_ERROR = 1 Const SISS_CERTIFICATE_STATE_LOADED = 2 Const SISS_CERTIFICATE_STATE_LOAD_ERROR = 3 Const SISS_CERTIFICATE_STATE_REMOVED = 4 Const SISS_CERTIFICATE_STATE_REMOVAL_ERROR = 5 Const SISS_CERTIFICATE_STATE_UPDATING = 6 CRS-ISAU-SIAU#33,V.05, Pagina 78 di 89

79 9.3.2 File OcsKitCittadino.vbs Le costanti qui riportate sono utili in fase di integrazione del componente per la gestione della carta. ' modulo Costants Const KC_BROWSE_FILTER_INDEX_DOC = 0 Const KC_BROWSE_FILTER_INDEX_RTF = 3 Const KC_BROWSE_FILTER_INDEX_PDF = 4 Const KC_BROWSE_FILTER_INDEX_TXT = RETURN CODE DI ERRORE Const PDLCITSSL_E_SMARTCARD_CONTEXT = Const PDLCITSSL_E_SMARTCARD_LISTENER = Const PDLCITSSL_E_UNSUPPORTED_WINVER = Const PDLCITSSL_E_DUPLICATE_INSTANCE = Const KC_E_FAIL = Const KC_E_CARD_REMOVED = Const KC_E_CARD_ERROR = Const KC_E_CARD_NOT_FOUND = Const KC_E_CARD_WRITE_PROTECTED = Const KC_E_CARD_BUSY = Const KC_E_CARD_UNRESPONSIVE = Const KC_E_CARD_UNPOWERED = Const KC_E_DEVICE_BUSY = Const KC_E_IO_ERROR = Const KC_E_IO_OPEN_ERROR = Const KC_E_IO_SEEK_ERROR = Const KC_E_FILE_NOT_FOUND = Const KC_E_IO_READ_ERROR = Const KC_E_IO_WRITE_ERROR = Const KC_E_BUSY = Const KC_E_DOCUMENT_INVALID = Const KC_E_INFORMATION_SENSITIVE = Const KC_E_KEY_FUNCTION_NOT_PERMITTED = Const KC_E_KEY_UNEXTRACTABLE = Const KC_E_PIN_EXPIRED = Const KC_E_PIN_INCORRECT = Const KC_E_PIN_INVALID = Const KC_E_PIN_LOCKED = Const KC_E_PIN_NOT_INITIALIZED = Const KC_E_PUK_INCORRECT = Const KC_E_PUK_INVALID = Const KC_E_PUK_LOCKED = Const KC_E_NO_DLL = Const KC_E_READER_NOT_FOUND = Const KC_E_READER_ERROR = Const KC_E_SHARING_VIOLATION = Const KC_E_SIGNATURE_LENGTH_INVALID = Const KC_E_SIGNATURE_INVALID = Const KC_E_SYSTEM_CANCELLED = Const KC_E_TIMEOUT = Const KC_E_OS_ERROR = Const KC_E_PIN_ERROR = Const KC_E_AUTHENTICATION_FAILED = Const KC_E_IO_FILE_FULL = Const KC_E_CARD_DUPLICATE = CRS-ISAU-SIAU#33,V.05, Pagina 79 di 89

80 Const KC_E_DLL_ERROR = Const KC_E_CRYPTOKI_INIT_ERROR = Const KC_E_INTERNAL = Const KC_E_USER_CANCELLED = Const KC_E_INVALID_STATE = Const KC_E_NOT_ALLOWED = Const KC_E_CERTIFICATE_NOT_VALID_YET = Const KC_E_CERTIFICATE_EXPIRED = Const KC_E_CERTIFICATE_NOT_FOUND = Const KC_E_INVALID_FORMAT = Const KC_E_UNEXPECTED_DATA = Const KC_E_BAD_CARD = Const KC_E_COMMAND_FAILED = Const KC_E_CSP_VERSION_NOT_VALID = CONFIGURAZIONE E RISOLUZIONE PROBLEMI Configurazione di Microsoft Internet Explorer Come già accennato, a partire dalla versione degli ActiveX, non è più necessaria alcuna personalizzazione rispetto alle impostazioni della severity Media di Internet Explorer. Questo paragrafo indica come configurare Internet Explorer qualora non si fossero aggiornate le librerie crittografiche installando quelle definitive (Bit4Id) e risultassero installate ancora le precedenti, distribuite a fini di sperimentazione (Siemens). Per poter usare i componenti del Posto di Lavoro del Cittadino è necessario che il livello di protezione impostato in Microsoft Internet Explorer non sia superiore a una certa soglia. Se la soglia di protezione supera questa soglia, le applicazioni Web che usano il componente non funzioneranno. Il livello di protezione richiesto sulla versione 6 del browser corrisponde a un livello medio (quello predefinito), più un ulteriore permesso nel caso delle versioni dei componenti (e precedenti). ma siccome non è garantito l allineamento delle varie versioni abbiamo riportato ciascuna opzione coinvolta. Nel caso il livello di protezione attivo sia quello medio, che come abbiamo detto è il livello predefinito, in pratica occorrerà modificare l impostazione indicata al successivo punto 9 (sempre solo per la versione dei componenti e precedenti a partire dalla v degli ActiveX non è necessaria alcuna personalizzazione). Per configurare il browser, eseguire questi passi: 1. aprire Microsoft Internet Explorer; 2. cliccare su Strumenti del menu principale del browser e cliccare su Opzioni Internet...: 3. comparirà la finestra Opzioni Internet: selezionare la pagina Protezione: 1 A differenza degli altri codici di errore, che sono silenti, questa segnalazione è preceduta dalla visualizzazione di una GUI proprietaria del componente CRS-ISAU-SIAU#33,V.05, Pagina 80 di 89

81 4. selezionare l'icona Internet 5. cliccare sul pulsante Livello personalizzato... (oppure Personalizza livello ): 6. comparirà la finestra Impostazione protezione: 7. trovare la sezione Controlli e plug-in ActiveX: 8. trovare la voce Esegui controlli e plug-in ActiveX e spuntare la casella Attiva: 9. trovare la voce Inizializza e esegui script controlli ActiveX non contrassegnati come sicuri e spuntare la casella Chiedi conferma: 10. trovare la voce Scarica controlli ActiveX con firma elettronica e spuntare la casella Chiedi conferma: CRS-ISAU-SIAU#33,V.05, Pagina 81 di 89

82 11. trovare la sezione Esecuzione script: 12. trovare la voce Esecuzione script attivo e spuntare la casella Attiva: 13. cliccare sul pulsante OK: 14. comparirà la finestra di richiesta di conferma all applicazione delle modifiche; cliccare su Sì: 15. La finestra Impostazioni protezione si chiude e si ritorna alla finestra Opzioni internet; cliccare su OK: 16. la configurazione del browser è completata. CRS-ISAU-SIAU#33,V.05, Pagina 82 di 89

83 9.5.2 Interazioni utente al primo accesso Durante la prima interazione con i siti web che integrano la CRS/CNS e dunque i già menzionati ActiveX, occorrerà autorizzare l installazione delle rispondere Sì a queste richieste di conferma del browser (le finestre si riferiscono a Windows XP Service Pack 2): Su Windows 2000 è possibile che al posto delle finestre precedenti compaia una finestra con il messaggio l autenticità del contenuto non può essere verificata, come ad esempio: CRS-ISAU-SIAU#33,V.05, Pagina 83 di 89

84 Per risolvere questo problema vedere il paragrafo Aggiornamento dei certificati per le fonti attendibili in Microsoft Internet Explorer. Raccomandiamo di rifiutare l installazione dei componenti se il componente risulta essere il Posto di Lavoro del Cittadino, ma non firmato da Lombardia Integrata S.p.A. Servizi Infotelematici per il Territorio con autenticità verificata da I.T. Telecom Global CA Installazioni con librerie crittografiche sperimentali Se sul sistema sono operative le librerie crittografiche Siemens, inzialmente distribuite a fini di sperimentazione, ad ogni caricamento delle pagine che ospitano i componenti software, comparirà una richiesta di conferma all operatività degli stessi come la seguente: Raccomandiamo di accordare questo permesso, cliccando su Sì, solo se si sta navigando su un sito affidabile, come ad esempio il sito di Progetto Ricodiamo infine che è altresì obbligatorio disinstallare le librerie crittografiche in oggetto e sostituirle con quelle definitive Aggiornamento dei certificati per le fonti attendibili in Microsoft Internet Explorer La finestra visualizzata compare se Microsoft Internet Explorer non riconosce la firma dei componenti del Posto di Lavoro del Cittadino. Per tale motivo viene evidenziata dal browser una finestra con cui si chiede di autorizzare l esecuzione del componente di cui non si considera attendibile la firma. CRS-ISAU-SIAU#33,V.05, Pagina 84 di 89

85 Questo è un problema del Sistema Operativo in seguito alla quale Microsoft stessa ha rilasciato un aggiornamento che lo risolve; la causa è riconducibile al fatto che, su postazioni Windows 2000 non aggiornate, la lista dei certificati delle Autorità di certificazione fonti attendibili non è aggiornata. Per installare l aggiornamento Microsoft che risolve il problema, procedere come segue: Dal menu principale di Microsoft Internet Explorer, selezionare Strumenti e quindi Windows Update: Il browser si collega al sito di Microsoft Windows Update; nel menu sulla sinistra della pagina, cliccare su Visualizza aggiornamenti disponibili: Compaiono le opzioni disponibili per questa voce, che dipendono dal sistema operativo: cliccare sul nome del sistema operativo usato (la voce da cliccare in questo caso è Windows 2000): CRS-ISAU-SIAU#33,V.05, Pagina 85 di 89

86 Nella parte destra della pagina, compariranno gli aggiornamenti disponibili. Trovare l aggiornamento identificato come Aggiornamento per certificati di origine: Cliccare su Aggiungi. Nella parte destra della pagina, cliccare su Verifica e installa aggiornamenti Nella parte sinistra della pagina comparirà la lista di aggiornamenti selezionati, che comprenderà oltre all aggiornamento interessato anche gli aggiornamenti importanti scelti automaticamente da Microsoft Windows Update. Seguire le istruzioni riportate nella pagina per portare a completamento l aggiornamento: nel caso fossero segnalati aggiornamenti da installare separatamente, sarebbe necessario ripetere la procedura fino a installare l aggiornamento che ci interessa. Questo è l ultimo passo della procedura appena descritta Verifica dell installazione dei driver per il lettore di smart card L installazione e la funzionalità dei driver per il lettore di smart card usato è un prerequisito fondamentale per il funzionamento del Posto di Lavoro del Cittadino. Per verificare l installazione dei driver del lettore: o cliccare sul pulsante Start; o cliccare su Pannello di controllo nel menu che viene mostrato: CRS-ISAU-SIAU#33,V.05, Pagina 86 di 89

87 o cliccare sul pulsante Start; o cliccare su Impostazioni e quindi su Pannello di controllo nel menu che viene mostrato: o cliccare su Strumenti di amministrazione (l icona potrebbe essere differente da questa mostrata): o cliccare su Gestione computer: o Compare la finestra Gestione computer: nella lista a sinistra selezionare Gestione periferiche: CRS-ISAU-SIAU#33,V.05, Pagina 87 di 89

88 o Nella finestra a destra, fare doppio click sulla sezione Lettori smart card: o Se i driver sono installati correttamente, la sezione si apre e nell elenco compare la denominazione del driver usato (qui si fornisce una denominazione a puro titolo di esempio): Verifica aggiornamento dei certificati Una volta inserita una CNS nel lettore di smartcard, è possibile verificare l avvenuto aggiornamento dei certificati personali: selezionare la voce Opzioni Internet accessibile dalla voce Strumenti del menu principale di Explorer; comparirà la finestra Opzioni Internet: selezionare la pagina Contenuto: CRS-ISAU-SIAU#33,V.05, Pagina 88 di 89

89 nella sezione Certificati, cliccare sul pulsante Certificati : comparirà la lista dei certificati registrati sulla macchina, che potrebbe comprendere altri certificati usati dall utente; il certificato CRS-SISS è riconoscibile perché emesso dalla Regione Lombardia e inizia con il codice fiscale del titolare della CNS: Nota: La lista dei certificati non viene aggiornata se la finestra di cui sopra è aperta. In tal caso occorre chiudere e riaprire la finestra stessa. Poiché la rimozione dei certificati è immediata, ma la durata dell importazione è nell ordine dei secondi, l apertura di questa pagina può interferire con l aggiornamento dei certificati, conseguente all inserimento e rimozione della carta, si consiglia, quindi, di evitare l esecuzione delle due operazioni in contemporanea. Segnalibro FineDoc Non Cancellare CRS-ISAU-SIAU#33,V.05, Pagina 89 di 89