Firma con strong auth
E' possibile eseguire la firma con strong auth di n hashes sia con token API che con token OWNER.
Per questa tipologia di firma sono utilizzabili solo certificati di tipo FEQ e ONESHOT.
A differenza della firma massiva, la firma con strong auth prevede una serie di chiamate poichè richiede l'apertura di una sessione di firma, l'autenticazione tramite strong auth e poi la possibilità di firmare n hashes, anche con chiamate successive.
Il numero massimo di hashes che si possono firmare in una sessione è definito in configurazione.
Le chiamate per eseguire una firma con strong auth in caso di token API e token OWNER differiscono solo nella prima chiamata.
Apertura sessione di firma
Token API
L'apertura di una sessione con token API, quindi eseguita da un dato cliente, può essere eseguita tramite il servizio:
I dati da fornire sono:
- l'alias dell'owner per cui firmare in path param
- il body seguente
{
"certificateAlias": "123",
"strongAuth": "type",
"maxSignatures": n,
"webhook": {
"url": "url"
}
}dove:
- certificateAlias è il certificato da utilizzare. Il certificato DEVE essere un certificato che appartiene all'owner indicato E al customer relativo al token. Non è obbligatorio.
- strongAuth è il tipo di strong authentication prevista. I valori possibili sono:
- SMS_OTP: strong auth tramite otp inviato per sms
- PHONE_CALL: strong auth tramite chiamata telefonica
- maxSignatures è il numero di firme che si vogliono effettuare nella sessione
- webhookUrl è l'url, opzionale, del webhook su cui si possono ricevere i cambi stato della firma. Tale webhook verrà utilizzato in base al tipo di strong auth: es. l'SMS_OTP non lo prevede, PHONE_CALL sì.
Token OWNER
L'apertura di una sessione con token ONWER, quindi eseguita da un dato titolare, può essere eseguita tramite il servizio:
I dati da fornire sono:
{
"certificateAlias": "123",
"strongAuth": "type",
"maxSignatures": n,
"webhook": {
"url": "url"
}
}dove:
- certificateAlias è il certificato da utilizzare. Il certificato DEVE essere un certificato che appartiene all'owner indicato E al customer relativo al token. Non è obbligatorio.
- strongAuth è il tipo di strong authentication prevista. I valori possibili sono:
- SMS_OTP: strong auth tramite otp inviato per sms
- PHONE_CALL: strong auth tramite chiamata telefonica
- maxSignatures è il numero di firme che si vogliono effettuare nella sessione
- webhookUrl è l'url, opzionale, del webhook su cui si possono ricevere i cambi stato della firma. Tale webhook verrà utilizzato in base al tipo di strong auth: es. l'SMS_OTP non lo prevede, PHONE_CALL sì.
In ambo i casi, in ritorno si ottiene la sessione appena aperta con le seguenti info:
{
"id": "64a19ba4ba848a71caae31d8",
"certificateAlias": "44040",
"signatureTimeout": "PT10M",
"strongAuthTimeout": "PT5M",
"strongAuth": "SMS_OTP",
"maxSignatures": 20,
"completedSignatures": 0,
"status": {
"value": "OPENED",
"step": null,
"remaining": null
},
"createdAt": "2023-07-02T15:45:40.025663395",
"lastModifiedAt": "2023-07-02T15:45:40.025663395"
}dove:
- id è l'id della sessione appena aperta. Da utilizzare nelle chiamate successive
- certificateAlias è l'alias del certificato che si userà per la firma
- strongAuth indica la tipologia di strong authentication che si userà
- maxSignatures è il numero di firme massimo che si può firmare in questa sessione
- completedSignatures indica le firme completate nella sessione. All'inizio sarò sempre zero
- createdAt e lastModifiedAt sono le date di inserimento e ultimo aggiornamento
- signatureTimeout indica il timeout della intera sessione di firma. E' un valore configurabile
- strongAuthTimeout indica il timeout della fase di strong authentication. E' un valore configurabile
- status indica lo stato della sessione. Appena creata sarò sempre in stato OPENED
A questo punto si procede in base alla tipologia di strong auth prevista dalla sessione.
Da questo momento in poi, è importante chiamare i vari metodi con un token della stessa tipologia di quella usata per l'apertura e
- con lo stesso customerId in caso di API
- con lo stesso owner in caso di OWNER.
1. SMS_OTP
Invio otp
Occorre inviare un OTP tramite il servizio
fornendo in path param l'id di sessione ritornato al punto precedente.
Validazione otp
Occorre validare l'OTP
fornendo in path param l'id di sessione ritornato al punto precedente e l'otp inviato nel body.
2. PHONE_CALL
Avvio chiamata
Occorre avviare la chiamata tramite il servizio
fornendo in path param l'id di sessione ritornato al punto precedente.
Dopo l'avvio della chiamata, i cambi di stato della sessione verranno comunicati all'integratore tramite webhook.
Quando si avvia la fase di strong authentication lo stato della sessione passerà da OPENED a STRONG_AUTH.
Il valore dello step indicherà in quale step della strong auth ci troviamo e dipenderà dal tipo di strong authentication in questione: es. nel caso di SMS_OTP sono previsti due step: SEND_SMS e VALIDATE_OTP.
remaining invece indica il numero di tentativi che si hanno a disposizione per ripetere quello step: es. nel caso di SMS_OTP si ha la possibilità di inviare n volte l'sms.
A strong auth completata, lo stato della sessione passa a READY ad indicare che la sessione è pronta per la firma.
Firma hashes
Una volta completata la strong auth, la sessione si troverà in stato READY, cioè pronta per la firma.
Solo a questo punto sarò possibile chiamare il servizio:
con i seguenti valori:
- id sessione in path param
- il body seguente
{
"certificatePin": "12345678",
"hashes": [
"myMXwslBoXkTDQ0olhq1QsiHRWWL4yj1V0IuoK+PYOg="
]
}- certificatePin è il pin del certificato da utilizzare, sempre che il certificato ne preveda uno.
- hashes è la collection di hashes in base64 da firmare. Gli hash devono essere in base64 e ottenuti con algoritmi consentiti dalla CA
Recupero sessione
In qualsiasi momento è sempre possibile recuperare una data sessione tramite il servizio: