Skip to content

pagopa/io-cie-sdk

Repository files navigation


IO - The public services app

Italiano

Questo repository contiene il porting per React Native (eseguito dal team di IO) dell'SDK sviluppato da IPZS (disponibile qui)

Installazione

Per utilizzare la libreria nel tuo progetto:

npm install @pagopa/react-native-cie --save

La login con CIE può essere effettuata esclusivamente tramite tecnologia NFC (tecnologia di tipo Hardware).
Su iOS, il codice che implementa la tecnologia non è disponibile sul simulatore, rendendo impossibile la build.

Per superare il problema, è necessario rinominare la cartella ios in .ios. In questo modo, React Native non ha visibilità del codice iOS e la build va a buon fine.

Per facilitare questo passaggio e abilitare la compilazione della libreria (lanciando la build da un device reale), è stato definito il comando:

mv node_modules/@pagopa/react-native-cie/.ios node_modules/@pagopa/react-native-cie/ios
mv node_modules/@pagopa/react-native-cie/.react-native-cie.podspec node_modules/@pagopa/react-native-cie/react-native-cie.podspec
cd ios
pod install

Per effettuare l'operazione inversa, invece:

mv node_modules/@pagopa/react-native-cie/ios node_modules/@pagopa/react-native-cie/.ios
mv node_modules/@pagopa/react-native-cie/react-native-cie.podspec node_modules/@pagopa/react-native-cie/.react-native-cie.podspec
cd ios
rm -rf Pods
pod install

Compatibilità

Non tutti i device sono compatibili con la login tramite CIE. La libreria espone dei metodi per sapere se il dispositivo è compatibile oppure no

Android

Su Android, è necessario verificare la presenza dell'NFC, oltre che della versione minima dell'API (>= 23).
Recentemente, è stato scoperto che alcuni vendors disabilitano la funzionalità software extended APDU, rendendo impossibile la lettura/scrittura tramite NFC.
Purtroppo, non è possibile determinare a priori questa possibilità, ma può essere gestito l'errore ritornato dall'SDK in fase di lettura.

iOS

Su iOS, la tecnologia NFC è presente su tutti i device con iOS >= 13.

Utilizzo

Per effettuare l'autenticazione tramite CIE, sono necessari tre componenti:

  • un URI di Autenticazione;
  • il PIN della CIE;
  • la carta da leggere;

Il recupero di queste tre componenti non dipendono dall'SDK.
Per utilizzare l'SDK, è necessario importarlo

import cieManager from "@pagopa/react-native-cie";

Una volta importato, è possibile accedere a tutti i suoi metodi.

API

Di seguito sono elencate alcune delle funzionalità presenti.
E' possibile trovare qui tutte le altre.

Function Return Descrizione
hasApiLevelSupport() Promise<boolean> (Android) Verifica se l'OS supporta l'autenticazione con CIE
hasNFCFeature() Promise<boolean> Verifica se il device ha l'NFC
setPin(pin: string) Promise<void> Set del PIN della CIE
setAuthenticationUrl(url: string) Promise<void> Set dell'Url di Autenticazione
start(alertMessagesConfig?: Partial<Record<iOSAlertMessageKeys, string>>) Promise<void> Avvia l'utilizzo dell'SDK
startListeningNFC() Promise<void> (Android) Avvia la lettura dell'NFC
stopListeningNFC() Promise<void> (Android) Stoppa la lettura dell'NFC
openNFCSettings() Promise<void> (Android) Apre le impostazioni dell'OS per l'NFC
onEvent(callback: (event: Event) => void) void Callback eseguita ad ogni evento di lettura/scrittura
onError(callback: (error: Error) => void) void Callback eseguita ad ogni errore di lettura/scrittura
onSuccess(callback: (url: string) => void) void Callback eseguita in caso di success

Possibili eventi

Durante la lettura dell'NFC, i possibili errori sono i seguenti

Error code Descrizione
ON_TAG_DISCOVERED_NOT_CIE (Android) La carta letta non è una CIE
TAG_ERROR_NFC_NOT_SUPPORTED (iOS) La carta letta non è una CIE
ON_TAG_DISCOVERED E' stato riconosciuto un tag
ON_TAG_LOST Tag rimosso / allontanato
ON_CARD_PIN_LOCKED (Android) Troppi inserimenti errati del PIN. La Card CIE è bloccata
PIN Locked (iOS) Troppi inserimenti errati del PIN. La Card CIE è bloccata
ON_PIN_ERROR Pin errato. L'evento restituisce anche il numero di tentativi rimasti
PIN_INPUT_ERROR Il PIN ha un formato errato (8 cifre numeriche)
CERTIFICATE_EXPIRED La CIE è scaduta
CERTIFICATE_REVOKED La CIE è stata revocata
AUTHENTICATION_ERROR Errore di autenticazione con il server del Ministero
ON_NO_INTERNET_CONNECTION Nessuna connesione ad Internet
STOP_NFC_ERROR Errore durante lo stop della lettura NFC
START_NFC_ERROR Errore durante lo start della lettura NFC
EXTENDED_APDU_NOT_SUPPORTED Il dispositivo non supporta una caratteristica della lettura della CIE
Transmission Error (iOS) Errore durante la trasmissione NFC

English

This repository contains the React Native library for CIE integration, written by IO

Installation

To use the library in your project

npm install @pagopa/react-native-cie --save

The login with CIE works only with NFC (hardware tecnology).
On iOS, the code that implements this tecnology isn't available on simulator, so it's not possible to build the project.

To solve this issue, you can rename the ios folder into .ios. After that, ReactNative has no more visibility on the iOS part and the build goes well.

If you want, you can use these commands to enable o disable the compiling phase.

Enable

mv node_modules/@pagopa/react-native-cie/.ios node_modules/@pagopa/react-native-cie/ios
mv node_modules/@pagopa/react-native-cie/.react-native-cie.podspec node_modules/@pagopa/react-native-cie/react-native-cie.podspec
cd ios
pod install

Disable

mv node_modules/@pagopa/react-native-cie/ios node_modules/@pagopa/react-native-cie/.ios
mv node_modules/@pagopa/react-native-cie/react-native-cie.podspec node_modules/@pagopa/react-native-cie/.react-native-cie.podspec
cd ios
rm -rf Pods
pod install

Compatibility

Note that not all the devices can allow the CIE login. This library provides you the methods to check that.

Android

On Android, is mandatory to check if the device has the NFC feature and the minimum version for the API (>= 23).
Recently, it was discovered a new issue. Some vendors are disabling a feature called software extended APDU. This feature disable the writing/reading through the NFC.
Unfortunately, it's not possible to determinate this possibility at beginning, but it's possible to handle the error returned by the SDK while reading the CIE.

iOS

On iOS, the NFC feature is available on all the device with iOS >=13.

Usage

To provide the CIE authentication, 3 components are required:

  • Authentication URI;
  • CIE pin;
  • the physical CIE to read;

It's up to you to get this components.
To use the library, just import it!

import cieManager from "@pagopa/react-native-cie";

Now you have access to all the methods.

API

A summary of some functionalities are written below, but you can find more here.

Function Return Desciption
hasApiLevelSupport() Promise<boolean> (Android) Check if OS has the minimum Api version
hasNFCFeature() Promise<boolean> Check if the device has the NFC
setPin(pin: string) Promise<void> Set the pin of the CIE
setAuthenticationUrl(url: string) Promise<void> Set the Authentication Url
setCutomIdpUrl(url: string?) <void> Set a Custom IdP Url
enableLog(isEnabled: boolean) <void> Enable the sdk logs
start(alertMessagesConfig?: Partial<Record<iOSAlertMessageKeys, string>>) Promise<void> Start the SDK
startListeningNFC() Promise<void> (Android) Start the reading from the NFC
stopListeningNFC() Promise<void> (Android) Stop the reading from the NFC
openNFCSettings() Promise<void> (Android) Open the OS Settings for the NFC
onEvent(callback: (event: Event) => void) void Callback after any events of reading/writing
onError(callback: (error: Error) => void) void Callback after any errors of reading/writing
onSuccess(callback: (url: string) => void) void Success Callback

Handle errors

You can handle the errors that happens while reading the NFC.

Error code Description
ON_TAG_DISCOVERED_NOT_CIE (Android) The card is not a CIE
TAG_ERROR_NFC_NOT_SUPPORTED (iOS) The card is not a CIE
ON_TAG_DISCOVERED A tag is discovered.
ON_TAG_LOST A tag is lost
ON_CARD_PIN_LOCKED (Android) The CIE is locked because of too many insert of wrong PIN
PIN Locked (iOS) The CIE is locked because of too many insert of wrong PIN
ON_PIN_ERROR Wrong PIN. The error returns also the remaining attempts number
PIN_INPUT_ERROR Wrong format for the PIN. It must be 8 numeric characters
CERTIFICATE_EXPIRED Expired CIE
CERTIFICATE_REVOKED Revoked CIE
AUTHENTICATION_ERROR Authentication error during the communication with Government server
ON_NO_INTERNET_CONNECTION No Internet connection
STOP_NFC_ERROR Error while stopping the NFC reading
START_NFC_ERROR Error while starting the NFC reading
EXTENDED_APDU_NOT_SUPPORTED The device cannot read the CIE
Transmission Error (iOS) Generic Error