How populate PadESPreferences
This type of preference is used in method signPadesList. Their principal options are:
PAdESPreferences |
Name | Type | Mandatory | Default value | Description | Included from SWS version |
---|
hashAlgorithm | String | SHA256 | Algorithm which you want use for sign. Possibile value are: SHA1, SHA256, SHA384, SHA512 | level | Level | B | See the description of Level type | signType | int | encryptInAnyCase | boolean | false | filenameInTSD | String | Not used | outputAsTSD | boolean | Not used | withTimestamp | boolean | false | Specify if you want add or not the timestamp to file signed | outputBase64Encoded | boolean | false | Set to true if you want file signed in Base64 encode | timestampHashAlgo | String | SHA-256 | Algorithm which you want to use during the process of apply timestamp. | 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 | timestampPassword | String | Password of timestamp credentials | lockFields | List<String> | needAppearanceDisabled | boolean | false | Deprecated | page | 1 | Indicate the page number where you want apply the signature appereance | withTimestamp | boolean | false | Set to true if you want apply the timestamp after the signature | encryptionPassword | String | Specify the password PDF if present | lockFields | List<String> | signerImage | SignerImage | See the description of SignerImage | signerImageReference | String | Used for specify the template to be used. (used in old version) | withSignatureField | boolean | false | Set to true if you want apply the signature on signature field in the PDF | SignerImage
The object SignerImage is composed by the following details:
SignerImage |
Name | Type | Mandatory | Default value | Description | Included from SWS version |
---|
image | byte[] | Contains the image which you want apply on the appereance | signerName | String | Contains the text which you want type on the appereance | reason | String | Specify the reason about the signature | textPosition | String | Position of the "signerName" on appereance. Is possible to choose between: | x | int | Coordinate X of the appereance (0 is right of the page) | y | int | Coordinate Y of the appereance (0 is on bottom of the page) | width | int | Specify the width of the appereance | height | int | Specify the height of the appereance | fieldName | Specify the fieldname where apply signature. This fieldName must already exist on PDF file before apply the signature | fontName | String | Times-Roman | Specify the font of the text on appereance to be used. The possible values are: - Times-Roman
- Times-Bold
- Times-Italic
- Times-BoldItalic
- Helvetica
- Helvetica-Bold
- Helvetica-Oblique
- Helvetica-BoldOblique
- Courier
- Courier-Bold
- Courier-Oblique
- Courier-BoldOblique
- Symbol
- ZapfDingbats
| imageURL | String | URL to obtain the logo for appereance | imageVisible | boolean | false | permits to show or not the logo on appereance | fontSize | int | 10 | permits to set the fontsize | imageFilename | String | path of the logo on appereance | scaled | boolean | false | Set to true if you want resize the logo on appereance | location | place of signature | INSERT EXAMPLE WITH APPEREANCE
Level
You can see how set the correct Level signature:
Level |
Value | Description | Apply on signature | Included from SWS version |
B | in the file signed will be added the electronic signature and the signing certificate | Pades, Cades, Xades | 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 | How populate Cades Preferences
With cades signature is possible to sign every type of file, the method signCadesList require:
- Credentials associated to device signature
- bufferList, 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. | How populate Xades Preferences
With xades signature is possible to sign only XML files, the method signXadesList require;
- Credentials associated to device signature
- bufferList, list of files 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
---|
image | 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 |
byte[] |
|
| Contains the image you want to apply to the appearance. |
|
signerName | String |
|
| Contains the text you want to type to the appearance. |
|
reason | String |
|
| Indicate the reason for the signature. |
|
textVisible | boolean |
| true | Allows the text to be shown on appearance or not. |
|
textPosition | String |
|
| Position of the "signerName" on appearance. It is possible to choose between: |
|
x | int |
|
| X coordinate of the appearance (0 is on left of the page). |
|
y | int |
|
| Y coordinate of the appearance (0 is on bottom of the page). |
|
width | int |
|
| Specify the width of the appearance. |
|
height | int |
|
| Specify the height of the appearance. |
|
fieldName |
|
|
| Specify the fieldname to which the signature is to be applied. This fieldName must already exist in the PDF file before the signature is applied. |
|
fontName | String |
| Times-Roman | Specify the font to be used for the text on the appearance. The possible values are: - Times-Roman
- Times-Bold
- Times-Italic
- Times-BoldItalic
- Helvetica
- Helvetica-Bold
- Helvetica-Oblique
- Helvetica-BoldOblique
- Courier
- Courier-Bold
- Courier-Oblique
- Courier-BoldOblique
- Symbol
- ZapfDingbats
OR Specify the ttf absolute path which contain custom font (see this section below to use specific ttf) | 2.5.39 |
imageURL | String |
|
| URL to get the logo for appearance. |
|
imageVisible | boolean |
| false | Allows the logo to be displayed or not when it appears. |
|
fontSize | int |
| 10 | Allows the fontsize to set set. |
|
imageFilename | String |
|
| Path of the logo on appearance. |
|
scaled | boolean |
| false | Set true if you want to resize the logo on appearance. |
|
scaledText | boolean |
| false | Reduce the font size until fit on the appereance |
|
location | String |
|
| Place of the signature. | 2.5.53 |
fieldsNameList | List<String> |
|
| List of fields signatures you want sign | 2.5.57 |
signAllFields | boolean |
| false | Allow to sign all fields signatures available in a PDF | 2.5.57 |
NOTE: if you are using the method "signPadesMultiFieldName", the property "signAllFields" have a priority on property "fieldsNameList"
Below an example of output in Adobe if you use the option "location" and "reason":
Image Added