@pagopa/io-react-native-cie

Module to handle CIE (Electronic Identity Card) operations natively in React Native apps.

Caution

If you are migrating from io-cie-sdk please read the migration guide carefully

Installation

npm install @pagopa/io-react-native-cie
# or
yarn add @pagopa/io-react-native-cie

iOS

cd ios && bundle exec pod install && cd ..

Setup

Android

On Android you need to declare the following permission into your AndroidManifest.xml. More info in the official Android documentation:

  <!-- Required to access NFC hardware -->
  <uses-permission android:name="android.permission.NFC" />
  <!-- Required for authentication process -->
  <uses-permission android:name="android.permission.INTERNET" />

iOS

In Apple developer site, enable capability for NFC.
Add NFCReaderUsageDescription into your info.plist, for example:
```
<key>NFCReaderUsageDescription</key>
<string>We need to use NFC</string>
```
More info on Apple's doc

Add the required ISO7816 identifiers into your info.plist

<key>com.apple.developer.nfc.readersession.iso7816.select-identifiers</key>
<array>
  <string>A0000000308000000009816001</string>
  <string>A00000000039</string>
  <string>A0000002471001</string>
  <string>00000000000000</string>
</array>

More info on Apple's doc.

In Xcode's Signing & Capabilities tab, make sure Near Field Communication Tag Reading capability had been added. More info on Apple's doc.

Example App

A fully working example app demonstrating how to use this package is available in the example directory.

To run the example app, follow the instructions in example/README.md.

API

List of available functions

Function	Return	Description
`hasNFCFeature()`	`Promise<boolean>`	(Android) Checks if the device supports NFC feature
`isNfcEnabled()`	`Promise<boolean>`	(Android) Checks if the NFC is currently enabled
`isCieAuthenticationSupported()`	`Promise<boolean>`	(Android) Checks if the device supports CIE autentication
`openNfcSettings()`	`Promise<void>`	(Android) Opens NFC system settings page
`addListener(event: CieEvent, listener: CieEventHandlers)`	`() => void`	Adds a NFC event listener and returns a function to unsubscribe from the event
`removeListener(event: CieEvent)`	`void`	Removes all listeners for the specified event
`removeAllListeners()`	`void`	Removes all registered listeners
`setCustomIdpUrl(url?: string)`	`void`	Updates IDP url, if `undefined` will use the default IDP url
`setAlertMessage(key: AlertMessageKey, value: string)`	`void`	(iOS) Updates iOS NFC modal alert message
`setCurrentAlertMessage(value: string)`	`void`	(iOS) Updates currently displayed iOS NFC modal alert message
`startReadingAttributes(timeout: number)`	`Promise<void`	Start the CIE attributes reading process
`startReading(pin: string, authenticationUrl: string, timeout: number)`	`Promise<void`	Start the CIE reading process fro authentication
`stopReading()`	`Promise<void`	(Android) Stops all reading process

Usage

The package is split into two modules:

CieUtils: Provides functions to check the NFC status of the device.
CieManager: Provides CIE read and authentication capabilities.

Check NFC Status

Note: These methods are applicable only for Android devices, as iOS devices always have NFC available.

import { CieUtils } from '@pagopa/io-react-native-cie';

// Check if the device has NFC
await CieUtils.hasNfcFeature();
// Check if NFC is enabled
await CieUtils.isNfcEnabled();
// Convenient method to check if CIE authentication is supported
await CieUtils.isCieAuthenticationSupported();

Reading CIE Data

Reading Attributes

Read CIE attributes (card type and base64-encoded data) with optional timeout (Android only)

import { CieManager } from '@pagopa/io-react-native-cie';

CieManager.startReadingAttributes()
  .then(() => console.log('Reading started'))
  .catch((error) => console.error('Error:', error));

Authentication

Start the CIE authentication process:

CieManager.startReading('12345678', 'https//auth-url.it')
  .then(() => console.log('Authentication started'))
  .catch((error) => console.error('Error:', error));

Event System

The library uses an event-driven approach for NFC operations and read results. Events are emitted to notify your application about progress, success, or failure. Each listener method returns a cleanup function that should be called when the operation is complete or when your component unmounts.

Available events

Listener Type	Description
`onEvent`	NFC events emitted during the reading process which indicates the reading progression
`onError`	NFC error events emitted if the reading process fails
`onSuccess`	Authentication success event
`onAttributeSuccess`	Successful attribute reads

Listening for events

You can register an event listiner with CieManager.addListener and remove it with the returned unregister function or by using CieManager.removeListener

const unsubscribe = CieManager.addListener('onEvent', (event) => {
  console.log(event);
});

// remove the listener with
unsubscribe()
// or
CieManager.removeListener("onEvent);

Example Usage

import { CieManager } from '@pagopa/io-react-native-cie';
import { useEffect } from 'react';

// ...

useEffect(() => {
  // Register all event listeners
  const cleanup = [
    CieManager.addListener('onEvent', (event) => {
      console.info('NFC Event', event);
    }),
    CieManager.addListener('onError', (error) => {
      console.error('NFC Error', error);
    }),
    CieManager.addListener('onSuccess', (url) => {
      console.log('Auth url:', url);
    }),
  ];

  // Cleanup all listeners on unmount
  return () => cleanup.forEach((remove) => remove());
}, []);

To remove all listeners at once:

CieManager.removeAllListeners();

NFC read events

List of events that are emitted during CIE reading process. Event names may differs based on the platform

iOS

Event	Description
ON_TAG_DISCOVERED	Tag has been discovered
ON_TAG_DISCOVERED_NOT_CIE	Discovered tag is not a CIE
CONNECTED	Connected to tag
GET_SERVICE_ID	Get CIE serviceId
SELECT_IAS	Select IAS Application
SELECT_CIE	Select CIE Application
DH_INIT_GET_G	Get DiffieHellman G parameter
DH_INIT_GET_P	Get DiffieHellman P parameter
DH_INIT_GET_Q	Get DiffieHellman Q parameter
READ_CHIP_PUBLIC_KEY	Retrive internal authentication key
SELECT_FOR_READ_FILE	Select file
READ_FILE	Read file
GET_D_H_EXTERNAL_PARAMETERS	Retrive Diffie Hellman external authenticationl parameters
SET_D_H_PUBLIC_KEY	Set Diffie Hellman internal key
GET_ICC_PUBLIC_KEY	Retrive ICC Public Key
CHIP_SET_KEY	Select key for certificate validation
CHIP_VERIFY_CERTIFICATE	Certificate validation
CHIP_SET_CAR	Select key for external authentication
CHIP_GET_CHALLENGE	Get challenge for external authentication
CHIP_ANSWER_CHALLENGE	Responds to challenge for external authentication
SELECT_KEY	Select key
VERIFY_PIN	Verify CIE Pin
SIGN	Sign data
READ_CERTIFICATE	Read CIE User Certificate
SELECT_ROOT	Select Root Application

Android

Event	Description
ON_TAG_DISCOVERED	Tag has been discovered
ON_TAG_DISCOVERED_NOT_CIE	Discovered tag is not a CIE
CONNECTED	Connected to tag
SELECT_IAS_SERVICE_ID	Selects internal authentication service for service ID
SELECT_CIE_SERVICE_ID	Selects CIE service ID
SELECT_READ_FILE_SERVICE_ID	Selects read file service ID
READ_FILE_SERVICE_ID_RESPONSE	Reads file service ID response
SELECT_IAS	Selects internal authentication service
SELECT_CIE	Selects CIE application
DH_INIT_GET_G	Gets G for Diffie-Hellman initialization
DH_INIT_GET_P	Gets P for Diffie-Hellman initialization
DH_INIT_GET_Q	Gets Q for Diffie-Hellman initialization
SELECT_FOR_READ_FILE	Selects for reading a file
READ_FILE	Reads a file
INIT_EXTERNAL_AUTHENTICATION	Initializes external authentication
SET_MSE	Sets MSE
D_H_KEY_EXCHANGE_GET_DATA	Exchanges Diffie-Hellman data
SIGN1_SELECT	Selects SIGN1 message
SIGN1_VERIFY_CERT	Verifies SIGN1 certificate
SET_CHALLENGE_RESPONSE	Sets challenge response
GET_CHALLENGE_RESPONSE	Gets challenge response
EXTERNAL_AUTHENTICATION	Performs external authentication
INTERNAL_AUTHENTICATION	Performs internal authentication
GIVE_RANDOM	Provides random data
VERIFY_PIN	Verifies PIN
READ_FILE_SM	Reads file with secure messaging
SIGN	Signs data
SIGN_WITH_CIPHER	Signs with cipher
SELECT_ROOT	Selects root

NFC error events

List of error event that may be emitted during CIE reading process

Error	Description
NOT_A_CIE	Discovered tag is not a CIE
TAG_LOST	Tag was lost during read operation
CANCELLED_BY_USER	(iOS only) Read was cancelled by user
APDU_ERROR	Protocol error or not supported
CARD_BLOCKED	Too many PIN attempts, card is blocked
WRONG_PIN	Wrong PIN
NO_INTERNET_CONNECTION	Missing internet connection
CERTIFICATE_EXPIRED	CIE expired
CERTIFICATE_REVOKED	CIE revoked
AUTHENTICATION_ERROR	unable to complete authentication
GENERIC_ERROR	Unmapped or unexpected error

Alert Messages

Note: This feature is iOS-only; Android does not support alert messages.

Customize the NFC dialog messages using CieManager.setAlertMessage(key, value):

CieManager.setAlertMessage(
  'readingInstructions',
  'Hold your iPhone near your CIE card to begin scanning.'
);

You can update the currently displayed alert message (for example, during the reading process) using CieManager.setCurrentAlertMessage(value):

CieManager.setCurrentAlertMessage('Reading in progress, 80% completed');

Available Alert Messages

Key	Description	Default Message
`readingInstructions`	Pre-scan instructions	"Tieni la tua carta d'identità elettronica sul retro dell'iPhone, nella parte in alto."
`moreTags`	Multiple tags detected	"Sono stati individuate più carte NFC. Per favore avvicina una carta alla volta."
`readingInProgress`	Reading status	"Lettura in corso, tieni ferma la carta ancora per qualche secondo..."
`readingSuccess`	Success message	"Lettura avvenuta con successo. Puoi rimuovere la carta mentre completiamo la verifica dei dati."
`invalidCard`	Invalid card error	"La carta utilizzata non sembra essere una Carta di Identità Elettronica (CIE)."
`tagLost`	Card removed error	"Hai rimosso la carta troppo presto."
`cardLocked`	Card locked error	"Carta CIE bloccata"
`wrongPin1AttemptLeft`	PIN warning (1 attempt)	"PIN errato, hai ancora 1 tentativo"
`wrongPin2AttemptLeft`	PIN warning (2 attempts)	"PIN errato, hai ancora 2 tentativi"
`genericError`	Generic error	"Qualcosa è andato storto"

Types

type CieAttributes = {
  type: string;
  base64: string;
};

Contains the CIE type (NFC manufacturer) and the attributres in base64 encoded string format. CIE type can be one of the following: NXP, GEMALTO, GEMALTO_2, ACTALIS, ST, UNKNOWN

type NfcEvent = {
  name: string;
  progress: number;
};

Event sent during the CIE reading process. Contains the name of the event and the progress associated. Event names and order may vary based on the platform.

type NfcError = {
  name: NfcErrorName;
  message?: string;
};

Error event that may be sent during the CIE reading process. Contains the name of the error and an optional message. Error names and order may vary based on the platform.

Errors

The CIE reading function may throw exceptions if the reading process cannot be initiated. These exceptions indicate issues with input validation or system compatibility. Below is a comprehensive list of possible exceptions that may be thrown during initialization:

Error Code	Platform	Description
`PIN_REGEX_NOT_VALID`	ios/Android	Invalid PIN format
`INVALID_AUTH_URL`	ios/Android	Invalid auth url format
`THREADING_ERROR`	iOS	Unexpected error
`UNKNOWN_EXCEPTION`	iOS/Android	Unexpected error

Contributing

See the contributing guide to learn how to contribute to the repository and the development workflow.

License

MIT

Made with create-react-native-library

Name		Name	Last commit message	Last commit date
Latest commit History 12 Commits
.github		.github
.yarn/releases		.yarn/releases
android		android
docs		docs
example		example
ios		ios
src		src
.DS_Store		.DS_Store
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
.node-version		.node-version
.yarnrc.yml		.yarnrc.yml
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
IoReactNativeCie.podspec		IoReactNativeCie.podspec
LICENSE		LICENSE
README.md		README.md
babel.config.js		babel.config.js
eslint.config.mjs		eslint.config.mjs
lefthook.yml		lefthook.yml
package.json		package.json
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json
turbo.json		turbo.json
yarn.lock		yarn.lock

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

@pagopa/io-react-native-cie

Table of Contents

Installation

iOS

Setup

Android

iOS

Example App

API

Usage

Check NFC Status

Reading CIE Data

Reading Attributes

Authentication

Event System

Available events

Listening for events

Example Usage

NFC read events

NFC error events

Alert Messages

Available Alert Messages

Types

Errors

Contributing

License

About

Uh oh!

Releases 5

Packages

Uh oh!

Contributors 3

Uh oh!

Languages

License

pagopa/io-react-native-cie

Folders and files

Latest commit

History

Repository files navigation

@pagopa/io-react-native-cie

Table of Contents

Installation

iOS

Setup

Android

iOS

Example App

API

Usage

Check NFC Status

Reading CIE Data

Reading Attributes

Authentication

Event System

Available events

Listening for events

Example Usage

NFC read events

NFC error events

Alert Messages

Available Alert Messages

Types

Errors

Contributing

License

About

Resources

License

Code of conduct

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 5

Packages 0

Uh oh!

Contributors 3

Uh oh!

Languages

Packages