allSignatureFieldNamesWithPreferences
This method allow to retrieve all signature field present inside a file. Using preferences the user is able to retrieve more details about the signature applied to a given signature field.
Below you can find a description of IN/OUT fields.
Name | Type | Mandatory | Description | IN/OUT |
---|
buffer | byte[] | ✔️ | The file to search for signature fields | IN |
preferences | SignatureFieldPreferences | ❌ | Preferences to be applied to the search operation | IN |
| List<SignatureFieldName> |
| List of all signature field names | OUT |
SignatureFieldPreferences
Here you can find a description of the complex object SignatureFieldPreferences
SignatureFieldPreferences |
Name | Type | Description | Included from SWS version |
---|
withDetails | boolean | Show details about the signature field signed, for example the appearence ( height, widht, x, y), signer name, sign date, the reason, location and the page DEFAULT=false | 2.5.56 |
withCertificate | boolean | Retrieve the signer certificate in base64 encoding and certificate subjectDN DEFAULT=false | 2.5.56 |
encryptionPassword | String | The encryption password used to protect the PDF given in input if present | 2.5.56 |
SignatureFieldName
Here you can find a description of the complex object SignatureFieldName
SignatureFieldName |
Name | Type | Description | Included from SWS version |
---|
identifier | String | Signature field name identifier | 2.5.56 |
signed | boolean | TRUE: the signature field is already signed FALSE: the signature field is not signed | 2.5.56 |
signatureDetails | SignatureDetails | Complex object containing details about the signature applied to a given field if signed | 2.5.56 |
SignatureDetails
Here you can find a description of the complex object SignatureDetails
SignatureDetails |
Name | Type | Description | Included from SWS version |
---|
name | String | Signer name applied to a given signature field | 2.5.56 |
signDate | Timestamp | Unix timestamp representing the date of when the signature has been applied | 2.5.56 |
location | String | The location of where the signature has been applied | 2.5.56 |
reason | String | Reason applied to a given signature | 2.5.56 |
page | Integer | Page where the signature field is present ( -1 if the page is not found ) | 2.5.56 |
appearance | PdfRectangle | Complex object containing info about the signature field box | 2.5.56 |
certificate | String | Base64-encoding of the signer certificate | 2.5.56 |
subjectDN | String | SubjectDN of the signer certificate | 2.5.56 |
PdfRectangle
Here you can find a description of the complex object PdfRectangle
PdfRectangle |
Name | Type | Description | Included from SWS version |
---|
witdth | Float | Width of the signature field | 2.5.56 |
height | Float | Heigth of the signature field | 2.5.56 |
x | Float | Lower left X-Axis position of the signature field | 2.5.56 |
y | Float | Lower left Y-Axis position of the signature field | 2.5.56 |
Example response
Here you can find an example response:
Code Block |
---|
|
[
{
"identifier": "SignatureField-1",
"signed": false
},
{
"identifier": "SignatureField-2",
"signatureDetails": {
"name": "My Name and Surname",
"signDate": 1687869549000,
"location": "Milan",
"reason": "Signed for general purpose",
"page": -1,
"appearance": {
"width": 40.50,
"height": 10.20,
"x": 1.0,
"y": 2.3
},
"certificate": "<base64-encoded certificate>",
"subjectDN": "CN=My Name and Surname, SERIALNUMBER=1234567890, GIVENNAME=MyName, SURNAME=My Surname, C=IT"
},
"signed": true
}
] |
T | Like B-Level, but adds a time-stamp, respectively a time-mark that proves that the signature existed at a certain date and time | Pades, Cades, Xades | LT | Like T-Level, but adds VRI (Verification Related Information) data to the DSS (Long Term) | Pades, Cades, Xades | LTA | Like LT-level, but adds a document time stamp and VRI data for the TSA (Time Stamping Authority). An LTA may help to validate the signature beyond any event that may limit its validity (Long Term with Arichive Time-Stamps) | Pades, Cades, Xades | LTV | (Long Term Validation) contain the OCSP/CRL response after the sign. It is used for validation after the signing certificate has been expired | Pades | Cades Preferences
With cades signature is possible to sign every type of file, the method signCades require:
- Credentials associated to device signature
- buffer, list of files which you want sign
- CAdESPreferences, the preferences about CAdES signature
In the following table you can see how set correctly the CAdESPreferences
CAdESPreferences |
Name | Type | Mandatory | Default value | Description | Included from SWS version |
---|
filenameInTSD | outputAsTSD | outputBase64Encoded | boolean | false | Encoded the file just signed in base64 | timestampHashAlgo | String | SHA-256 | Algorithm which you want to use during the process of apply timestamp. | timestampPassword | timestampUrl | String | URL of timestamp provider with standard RFC3161. Namirial URL: PROD: https://timestamp.namirialtsp.com / http://timestamp.namirialtsp.com TEST: https://timestamp.test.namirialtsp.com / http://timestamp.test.namirialtsp.com | timestampUsername | String | Username of timestamp credentials | hashAlgorithm | String | yes | SHA256 | Algorithm which you want use for sign. Possibile value are: SHA1, SHA256, SHA384, SHA512 | level | Level | B | See the description of Level type | withTimestamp | boolean | false | Set to true if you want apply the timestamp after the signature | counterSignature | counterSignatureIndex | detached | boolean | false | Set to true if you want signature and files in two different files. The output will be the signature. | Xades Preferences
With xades signature is possible to sign only XML files, the method signXades require;
- Credentials associated to device signature
- buffer, file which you want sign
- XAdESPreferences, the preferences about XAdES signature
In the following table you can see how set correctly the XAdESPreferences
XAdESPreferences |
Name | Type | Mandatory | Default value | Description | Included from SWS version |
---|
filenameInTSD | outputAsTSD | outputBase64Encoded | boolean | false | Encoded the file just signed in base64 | timestampHashAlgo | String | SHA-256 | Algorithm which you want to use during the process of apply timestamp. | timestampPassword | timestampUrl | String | URL of timestamp provider with standard RFC3161. Namirial URL: PROD: https://timestamp.namirialtsp.com / http://timestamp.namirialtsp.com TEST: https://timestamp.test.namirialtsp.com / http://timestamp.test.namirialtsp.com | timestampUsername | String | Username of timestamp credentials | hashAlgorithm | String | yes | SHA256 | Algorithm which you want use for sign. Possibile value are: SHA1, SHA256, SHA384, SHA512 | level | Level | B | See the description of Level type | withTimestamp | boolean | false | Set to true if you want apply the timestamp after the signature | detached | boolean | false | Set to true if you want signature and files in two different files. The output will be the signature. | detachedReferenceURI | String | signElement | String | signatureId | String | withoutSignatureExclusion | boolean | false | Permits to sign the file with/without previous signature | XPathQuery | String | Permetis to sign a specified path of XML | Manage error in SWS
Every method can generate exception, for example caused by PIN not correct, sessioneKey expired or OTP not correct.
For example if we can try to execute the method signPAdESList using the same OTP used we obtain SOAP response with error 44, like in this response:
Code Block |
---|
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<soap:Fault>
<faultcode>soap:Server</faultcode>
<faultstring>Codice OTP errato, riprovare con il prossimo codice</faultstring>
<detail>
<ns2:WSException xmlns:ns2="http://service.ws.nam/">
<error>44</error>
<message>Codice OTP errato, riprovare con il prossimo codice</message>
</ns2:WSException>
</detail>
</soap:Fault>
</soap:Body>
</soap:Envelope> |
By default the error message is in Italian language.
Below the table description with all error messages can generate SWS during your execution method:
Error details |
---|
Error number | Description |
English | Italian |
0 | No errors found | Nessun errore riscontrato |
1 | Generic error | Errore Generico |
2 | Virtual device not found | Dispositivo virtuale inesistente |
3 | Virtual device locked | Dispositivo virtuale bloccato |
4 | Wrong credentials | Credenziali errate |
5 | Wrong emergency code | Codice di emergenza errato |
6 | Virtual device status changes denied | Modifiche allo stato del dispositivo virtuale negate |
7 | Signature error | Errore nella firma |
8 | Error creating slot | Errore nella creazione dello slot |
9 | Error deleting slot | Errore nella eliminazione dello slot |
10 | PIN change error | Errore nel cambio PIN |
11 | Key generation error | Errore nella generazione chiave |
12 | Error in key management configuration | Errore nella configurazione del sistema di gestione delle chiavi |
13 | Wrong company code | Codice azienda errato |
14 | No available slots | Nessuno slot disponibile |
15 | Virtual device already exists | Dispositivo virtuale gia' esistente |
16 | Operation performed using a wrong certificate | Operazione eseguita usando il certificato errato |
17 | Wrong virtual device code | Codice dispositivo virtuale errato |
18 | Slot already used | Slot gia' utilizzato |
22 | Incompatible file format for the signature type required | Richiesta una firma di file di formato non compatibile con il tipo di firma richiesto |
23 | Unsupported hash algorithm | Algoritmo di hash non supportato |
24 | Error decrypting CMS data | Errore nella decifratura del CMS EnvelopedData |
25 | Error importing key and certificates | Errore nell'importazione di chiave e certificati |
26 | The public key in the certificate does not match the private key | Chiave pubblica nel certificato non corrisponde a quella privata |
27 | Web method denied for the credentials or ssl certificate used | Eseguita una chiamata a web method mediante credenziali o certificato ssl non abilitato per questa funzione |
28 | CA doesn't exist | La CA inserita non esiste |
29 | The user didn't enter all required fields for the profile | L'utente non ha inserito tutti i campi richiesti per il profilo |
30 | EJBCA error | Errore di EJBCA |
31 | Authorization denied | Autorizzazione negata |
32 | Error due to waiting for data approval | Errore dovuto all'attesa per l'approvazione dei dati |
33 | Error approving the entered data | Errore nell'approvazione dei dati inseriti |
34 | Illegal query | Errore per query illegale |
35 | Certificate already revoked | Certificato gia' revocato in precedenza |
36 | I / O error, caused by writing / reading / converting a file / byte array / string | Errore di I/O, causato dalla scrittura/lettura/conversione di un file/array di byte/stringa |
37 | Payment verification failed | Verifica di pagamento non andata a buon fine |
38 | No available signatures | Eseguite tutte le firme a disposizione |
42 | A denied feature is invoked in the current mode | E' stata richiamata una funzionalita' non permessa nella modalita' corrente |
43 | A denied feature is invoked in the implementation used | E' stata richiamata una funzionalita' non permessa nell'implementazione usata |
44 | Wrong OTP code, try again with the next code | Codice OTP errato, riprovare con il prossimo codice |
45 | The key isn't associated to a certificate | La chiave non ha associato un certificato |
46 | Unknown certificate format | E' stato passato un certificato di formato sconosciuto |
47 | It isn't possible to open the slot | Non e' stato possibile aprire lo slot |
49 | Key login error | Errore di login sulla chiave |
50 | Error generating the CSR | Errore nella generazione del CSR |
51 | The maximum number of attempts to access the virtual device is reached | Raggiunto il numero massimo di tentativi di accesso al dispositivo virtuale |
52 | Error decrypting | Errore nella decifra |
53 | The certificate has expired | Il certificato associato alla chiave e' scaduto |
54 | There are no tokens for automatic signature with Cosign HSM | Non sono disponibili token per la firma automatica con hsm Cosign |
55 | Error updating certificate in db | Errore durante l'aggiornamento del certificato nel db |
56 | Wrong method use | Errato utilizzo del metodo |
57 | Method not yet implemented | Metodo non ancora implementato |
58 | Error assigning the OTP | Errore durante l'assegnazione dell'OTP |
59 | Error assigning the static token | Errore durante l'assegnazione del token statico |
60 | Error deleting the account | Errore durante la cancellazione dell'account |
61 | Error activating the account | Errore durante l'attivazione dell'account |
62 | Error loading the account | Errore durante il caricamento dell'account |
63 | Error unlocking the account | Errore durante lo sblocco dell'account |
64 | Unavailable hsm licenses | Licenze per hsm esaurite |
65 | PIN too short | PIN troppo corto |
66 | Session key incorrect | Session key errata |
67 | Session key not specified | Session key non specificata |
68 | Session key undefined | Session key non definita |
69 | Session key expired | Session key scaduta |
70 | Session key not usable | Session key non utilizzabile |
71 | Error generating session key | Errore durante la generazione della session key |
72 | Error incrementing the session counter | Errore durante l'incremento del session counter |
73 | Error sending OTP code | Errore durante l'invio del codice OTP |
74 | Error deleting session key | Errore durante la cancellazione della session key |
77 | Error closing session | Errore durante la chiusura della sessione |
78 | The number of documents to be signed differs from the number of signature preferences | Il numero di documenti da firmare differisce dal numero di preferenze di firma |
79 | Error detecting Security World | Errore durante il rilevamento del Security World |
80 | Error detecting the Module | Errore durante il rilevamento del Modulo |
81 | Error reading the SoftCard | Errore durante la lettura della SoftCard |
82 | Error writing the SoftCard | Errore durante la scrittura della SoftCard |
83 | Error deleting the SoftCard | Errore durante la cancellazione della SoftCard |
84 | Error loading SoftCard | Errore durante il caricamento della SoftCard |
85 | SoftCard not loaded | SoftCard non caricata |
86 | SoftCard already exists in the system | SoftCard gia' esistente a sistema |
87 | SoftCard does not exist | SoftCard inesistente |
88 | Error reading the key | Errore durante la lettura della chiave |
89 | Error writing the key | Errore durante la scrittura della chiave |
90 | Error deleting the key | Errore durante la cancellazione della chiave |
91 | Error decrypting the RSA data | Errore durante la decifratura RSA |
92 | Error decrypting the CMS envelope | Errore durante la decifratura CMS |
93 | Error creating the SoftCard | Errore durante la creazione della SoftCard |
94 | The size of the hash does not coincide with the expected one by the algorithm | La dimensione dell'hash non coincide con quella prevista dall'algoritmo |
95 | Error loading Cosign Tokens | Errore durante il caricamento dei Token Cosign |
96 | The system takes too much time, HSM overload. Try again | Il sistema impiega troppo tempo, HSM sovraccarico. Riprovare |
97 | Timeout passed | Timeout superato |
98 | No signature device associated to the user | Nessun dispositivo di firma remota risulta associato all'utente in questione |
1001 | The OTP device does not exist | Dispositivo OTP non esistente a sistema |
1007 | The OTP device was not activated | Il dispositivo OTP non risulta essere stato attivato |
1009 | Unavailable attempts for the OTP device | Superato il numero massimo di tentativi per il dispositivo OTP |
1016 | The OTP device was not associated to the holder | Il dispositivo OTP non risulta essere stato associato al titolare |
Method signPadesList
This parameters required (IN) and the output (OUT) of this method can be specified with this table:
signPadesList |
Name | Type | Description | IN/OUT |
---|
credentials | Credentials | See the section Credentials for see how populate this object | IN |
bufferList | List<byte[]> | List of byte array which you want sign | IN |
PAdESPreferences | PAdESPreferences | Specify the details of PadesSignature. See the section PadesPreferences for populate di object | IN |
List<byte> | List of byte array containg the file just signed | OUT | Method signCadesList
This parameters required (IN) and the output (OUT) of this method can be specified with this table:
signPadesList |
Name | Type | Description | IN/OUT |
---|
credentials | Credentials | See the section Credentials for see how populate this object | IN |
bufferList | List<byte[]> | List of byte array which you want sign | IN |
CAdESPreferences | CAdESPreferences | Specify the details of PadesSignature. See the section CadesPreferences for populate this object | IN |
List<byte> | List of byte array containg the file just signed | OUT | Method signXadesList
This parameters required (IN) and the output (OUT) of this method can be specified with this table:
signXadesList |
Name | Type | Description | IN/OUT |
---|
credentials | Credentials | See the section Credentials for see how populate this object | IN |
bufferList | List<byte[]> | List of byte array which you want sign | IN |
XAdESPreferences | XAdESPreferences | Specify the details of XadesSignature. See the section XadesPreferences for populate this object | IN |
List<byte> | List of byte array containg the file just signed | OUT | ADVANCED USE
VERIFY TIMESTAMP
While for verify only timestamp, you can use this methods:
timestampTSDVerify → It permits to validate TSD files (file and timestamp in the same file)
timestampTSRVerify → It permits to validate TSR files (file and timestamp in two different files)