Method getCertificate
This method allow to obtain the certificate associated to signer device.
This method require same input for automatic and remote signature. Below the details:
Name | Type | Description | IN/OUT |
---|
credentials | Credentials | You must specify: - credentials.username with the device name (RHI..., AHI, SHI)
| IN |
byte[] | byte array of certificate associated to signer device | OUT | Method getAvailableSignatures
This method allow to obtain the number of signaures available
This method require same input for automatic and remote signature. Below the details:
Name | Type | Description | IN/OUT |
---|
credentials | Credentials | You must specify: - credentials.username with the device name (RHI..., AHI, SHI)
| IN |
int | number of signatures availables | OUT | NOTE: this method can't be used for signer device "pay-per-use" (device with unlimited signatures), will generate error with code: "56"
Method getSignatures
This method allow to obtain the number of signaures apposed since the device has been created
This method require same input for automatic and remote signature. Below the details:
Name | Type | Description | IN/OUT |
---|
credentials | Credentials | You must specify: - credentials.username with the device name (RHI..., AHI, SHI)
| IN |
int | number of signatures apposed | OUT | Manage error in SWS
Each method can generate an exception, for example PIN not correct, sessioneKey expired or OTP not correct.
For example if we try to execute the signPAdESListmethod with the same OTP, we get the SOAP response with error 44, as 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 the Italian language.
Below is the table description of all error messages SWS can generate 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 implemented yet | 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 |
76 | Error appositioning timestamp | Errore durante l'apposizione della marca temporale |
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 getErrors
This method return a list of errors which can be generated from SWS in in
Name | Type | Optional | Description | IN/OUT |
---|
lang | String | String county code in 2 digit, accept only EN, IT. | IN | errorCode | Integer | true | Specify the error code you want to receive in the error description. If not specified will return return all errors in a specified language. | IN |
List<ErrorDetails> | Return a list with the error(s) description. | OUT | The type "ErrorDetails" is a composed by:
- int errorCode
- String errorLanguage (language code in 2 digit for example EN)
- String errorLanguage2 (language code in 3 digit for example ENG)
- String errorText (contain the error description in a specified language)
In this method, it is possible to return the list of all errors without setting the value of errorCode.
Verify the signatures/timestamp in SWS
SWS permits to verify the signature. For SWS the signature is VALID only if the signature has been apposed with qualified certificate.
For example the the certificate which has apposed the signature is qualified if:
- Root CA enroll the certificate is in the truested list
- private key is in secure device like smartcard, token or HSM
For example if the signature has been apposed with private key on file, the verify with SWS will fail because the private isn't in a secure device (like HSM).
Method for verification of digital signatures: verifyWithPreferences
This method allow to verify different types of signatures (detached or no): Pades, Xades, Cades:
Name | Type | Mandatory | Description | IN/OUT |
---|
signedContent | byte[] | ✔️ | file to be verified | IN |
preferences | VerifyPreferences | Contain the preferences to be used during the verify process | IN | SignedDocumentReportBean | Composite class which contain the report of a signature | OUT | Below will be described the complex object "VerifiyPreferences"
VerifyPreferences |
Name | Type | Mandatory | Default value | Description | Included from SWS version |
---|
checkByteRange | boolean | detachedContent | byte[] | Contain the original file if you are verifying a detached signature | includeFea | false | If set to true permits to verify the FEA (Firma Elettronica Avanzata) signature | language | String | IT | Contain the country code two digit and specify the language of verification report. | mandatoryRevocationCheck | boolean | false | pdfEncryptionPassword | String | Contains the password of PDF files (if you are verifying PDF files with password) | recursive | boolean | false | Check if there are signatures in the file which has been signed | verifyOnDate | Date | Date of verification at specified date | namirial | boolean | falsle | Permits to use custom tsl specified on properties. Used only for test purpose. | In output will obtain the verification report described by complex object: SignedDocumentReportBean
SignedDocumentReportBean |
Name | Type | Description | Included from SWS version |
---|
overallVerified | boolean | Very IMPORTANT: outcome of verification, if true the signature is VALID | checkDate | Date | Date of execute of verification | verificationDate | Date | Date of verification. For example if the verification date is: "2021-09-03 15:30:00" specificy i want verify in that date. | plainDocument | byte[] | Original file (present only in Cades signatures) | noteReportList | NoteReportBean | List of notes to support the signature evaluation | signatureReportList | SignatureReportBean | List of specific report on a single signature | nrOfSignatures | int | Number of signature in the file are you verifiyng | signatureFormat | String | Specify the type of signature. Can be: Pades, Cades or Xades | timestampReportList | TimestampReportBean | Reports list in possible timestamps apposed to the signature | Below will be described the complex object NoteReportBean, SignatureReportBean:
NoteReportBean |
Name | Type | Description | Included from SWS version |
---|
policy | int | Note validity area (0=ALL, 1=IT, 2=EU) | about | int | Object of the note (O=other, 1=Signature, 2=holder, 3=issuer, 4=timestamp) | type | int | Type of the note (1=INFO, 2=WARNING, 3=ERROR) | synopsis | String | Brief description of the note (for example: "Key on secure device") | description | String | Detailed description of the note: "The private key associated with the test azienda certificate is stored in a secure device compliant with European Regulation 2014/910/EU" | SignatureReportBean |
Name | Type | Description | Included from SWS version |
---|
integrity | boolean | It defines the integrity of signature | signatureAlgorithmName | String | Alghoritm used to sign | serialNumber | BigInteger | Serial of the signing certificate | subjectDN | String | Subject DN of the signing certificate | subjectCN | String | Common Name (CN) in the subject DN associated to the signing certificate | issuerDN | String | Subject DN associated to the issuer of signing certificate | issuerDN | String | Common name (CN) of subject DN associated to the issuer of signing certificate | issuerCertificateStatus | enum | Issuer's certificate status. It can have the following values: VALID, REVOKE, UNKNOWN | issuerInTrustedList | boolean | It defines if the issuer of the signing certificate is a trusted entity defined by the European TSL | keySize | int | size of key associated to the signer certificate | qcComplianceStatus | enum | It defines if the signatures is in line with the Qualified Signature requirements. It can have the following values: VALID, INVALID, UNDETERMINATED, VALID_WITH_WARNINGS, INFORMATION | qcSSCDStatus | enum | If defines if the signature was created by a secure device (like smartcard, token, hsm) NOT file (p12, jks) | signatureDate | Date | Date of signature | trustedSignatureDate | boolean | Set to true if the signature include timestamp (to guarantee the date of signature) | derEncodedSignerCert | byte[] | Signer certificate in X509 format | signerCertifcateNotBefore | Date | Start date of the validity of the signing certificate | signerCertificateNotAfter | Date | End date of the validity of the signing certificate | signerCertificateStatus | enum | Status of certificate. The value can be: | id | int | number of signature | Method for verification of timestamps
The timestamp can be of two different types:
- TSR (TimeStamp Response) + original file in the same file is called TSD (TimeStamp Data)
- TSR and original file in two different files
There are two method for verify the TSD and TSR:
- verifyTimeStampData
- verifyTimeStampResponse
Method verifyTimeStampResponse and verifyTimestampData
Below the description of method "verifyTimeStampResponse":
Name | Type | Mandatory | Description | IN/OUT |
---|
tsr | byte[] | ✔️ | tsr to verify | IN |
content | byte[] | ✔️ | original file | IN |
TimestampReportBean | Report with detail of verification | OUT | And the method "verifyTimestampData":
Name | Type | Mandatory | Description | IN/OUT |
---|
tsd | byte[] | ✔️ | tsr to verify | IN |
List<TimestampReportBean> | Report with detail of verification | OUT | Below will be described the complex object TimestampReportBean:
TimestampReportBean |
Name | Type | Description | Included from SWS version |
---|
indexInteger | Return the number of timestamp verified | date | Date | When the timestamp has been apposed | signatureVerificationStatus | enum
The status of the integrity of the timestamp (indicates if the token's signature is intact), the value can be: | trustedListVerificationStatus | enum
The status of the root certificates associated, the value can be: - VALID
- INVALID
- UNDETERMINATED
| timestampCertificateStatus | enum
The status of certifcate which has apposed the timestamp, the value can be: - VALID
- INVALID
- UNDETERMINATED
| issuer | | Subject DN associated to the issuer certificate | subject | | Subject DN associated to timestamp certificate | issuerCN | | CN (Common Name) of Subject DN associated to the issuer certificate | subjectCN | | CN (Common Name) of Subject DN associated to the timestamp certificate | serialNumber | | Serial number associated to timestamp certificate | signatureAlgorithm | String
Algorithm used for apply the timestamp | hashAlgorithm | String
Algorithm used for the hash generation for document hash | comment | | Message explain the details of the error if present | timestampCertData | | Certificate associated to timestamp | content | byte[]
File oringinal which has been applied the timestamp | contentFilename | | Return the filename if present else will return "originalFile.bin" | contentMimeType | | Return the content type associated to the file if present. Else will return "application/octect-stream" | timeStampToken | | Contain the timestamp associated | boolean | Very IMPORTANT: outcome of verification, if true the signature is VALID |
|
checkDate | Date | Date of execute of verification |
|
verificationDate | Date | Date of verification. For example if the verification date is: "2021-09-03 15:30:00" specificy i want verify in that date. |
|
plainDocument | byte[] | Original file (present only in Cades signatures) |
|
noteReportList | NoteReportBean | List of notes to support the signature evaluation |
|
signatureReportList | SignatureReportBean | List of specific report on a single signature |
|
nrOfSignatures | int | Number of signature in the file are you verifiyng |
|
signatureFormat | String | Specify the type of signature. Can be: Pades, Cades or Xades |
|
timestampReportList | TimestampReportBean | Reports list in possible timestamps apposed to the signature |
|
Below will be described the complex object NoteReportBean, SignatureReportBean:
NoteReportBean |
Name | Type | Description | Included from SWS version |
---|
policy | int | Note validity area (0=ALL, 1=IT, 2=EU) |
|
about | int | Object of the note (O=other, 1=Signature, 2=holder, 3=issuer, 4=timestamp) |
|
type | int | Type of the note (1=INFO, 2=WARNING, 3=ERROR) |
|
synopsis | String | Brief description of the note (for example: "Key on secure device") |
|
description | String | Detailed description of the note: "The private key associated with the test azienda certificate is stored in a secure device compliant with European Regulation 2014/910/EU" |
|
SignatureReportBean |
Name | Type | Description | Included from SWS version |
---|
integrity | boolean | It defines the integrity of signature |
|
signatureAlgorithmName | String | Alghoritm used to sign |
|
serialNumber | BigInteger | Serial of the signing certificate |
|
subjectDN | String | Subject DN of the signing certificate |
|
subjectCN | String | Common Name (CN) in the subject DN associated to the signing certificate |
|
issuerDN | String | Subject DN associated to the issuer of signing certificate |
|
issuerDN | String | Common name (CN) of subject DN associated to the issuer of signing certificate |
|
issuerCertificateStatus | enum | Issuer's certificate status. It can have the following values: VALID, REVOKE, UNKNOWN |
|
issuerInTrustedList | boolean | It defines if the issuer of the signing certificate is a trusted entity defined by the European TSL |
|
keySize | int | size of key associated to the signer certificate |
|
qcComplianceStatus | enum | It defines if the signatures is in line with the Qualified Signature requirements. It can have the following values: VALID, INVALID, UNDETERMINATED, VALID_WITH_WARNINGS, INFORMATION |
|
qcSSCDStatus | enum | If defines if the signature was created by a secure device (like smartcard, token, hsm) NOT file (p12, jks) |
|
signatureDate | Date | Date of signature |
|
trustedSignatureDate | boolean | Set to true if the signature include timestamp (to guarantee the date of signature) |
|
derEncodedSignerCert | byte[] | Signer certificate in X509 format |
|
signerCertifcateNotBefore | Date | Start date of the validity of the signing certificate |
|
signerCertificateNotAfter | Date | End date of the validity of the signing certificate |
|
signerCertificateStatus | enum | Status of certificate. The value can be: |
|
id | int | number of signature |
|