The Preserve_getInfo method

Allows to get details of a document and its electronic signatures stored in the SecuSign qualified service. These details are available as a PDF, XML and HTML report.

Service description including WSDL schema, and an example request and response for SOAP 1.1 and SOAP 1.2 are located at https://localhost/secusign/default.asmx?op=Preserve_getInfo.

Localhost is the name used for the local computer; write the SDK server name/IP address instead (according to the settings in IIS).

Request in SOAP 1.1 interface

POST /secusign/default.asmx HTTP/1.1
Host: localhost
Content-Type: text/xml; charset=utf-8
Content-Length: length
SOAPAction: "http://software602.com/secusign/Preserve_getInfo"

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <Preserve_getInfo xmlns="http://software602.com/secusign/">
      <DocID>string</DocID>
      <FileData>base64Binary</FileData>
      <ExternalSignature>base64Binary</ExternalSignature>
      <Params>string</Params>
      <Properties>
        <ReportLanguage>string</ReportLanguage>
        <GetReport>boolean</GetReport>
        <GetXMLReport>boolean</GetXMLReport>
        <GetHTMLReport>boolean</GetHTMLReport>
        <GetPDFReport>boolean</GetPDFReport>
      </Properties>
    </Preserve_getInfo>
  </soap:Body>
</soap:Envelope>

Input parameters of the method

<DocID>

[mandatory element]

Input Description

string

Unique identifier of the preserved electronic signatures in a document. It was generated automatically during the preservation process in the SecuSign service. Can be found in the account’s user interface. Max. 128 characters.

<FileData>

[optional element]

Input Description

Base64Binary

Input file data encoded in base64.

<ExternalSignature>

[optional element]

Input Description

Base64Binary

External signature data encoded in base64.

<Params>

[optional element]

Input Description

String

Optional, contains other parameters. Not in use yet.

<Properties>

[optional element]

<ReportLanguage>

[optional element]

Input Description

string

Localization of textual information in the output report. Values: cz, en

Default value: cz.

<GetReport>

[optional element]

Input Description

boolean

Logical value specifying whether to generate the information directly in the response.

Default value: true.

<GetXMLReport>

[optional element]

Input Description

boolean

Logical value specifying whether to generate the information in an XML report.

Default value: false.

<GetHTMLReport>

[optional element]

Input Description

boolean

Logical value specifying whether to generate the information in an HTML report.

Default value: false.

<GetPDFReport>

[optional element]

Input Description

boolean

Logical value specifying whether to generate the information in a PDF report.

Default value: false.

Response structure

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <Preserve_getInfoResponse xmlns="http://software602.com/secusign/">
      <Preserve_getInfoResult>int</Preserve_getInfoResult>
      <Report>
        <CreationDateTime>dateTime</CreationDateTime>
        <docId>string</docId>
        <fileName>string</fileName>
        <fileSize>long</fileSize>
        <sortInfo>string</sortInfo>
        <lastUpdate>dateTime</lastUpdate>
        <expiration>dateTime</expiration>
        <docDataHash>base64Binary</docDataHash>
        <docDataHashAlg>string</docDataHashAlg>
        <currSignHashAlg>string</currSignHashAlg>
        <sigValidityCondition>ALL or AT_LEAST_ONE or LAST</sigValidityCondition>
        <sigsPreservationStatus>
          <PreservationInfo>
            <sid>string</sid>
            <sigStatus xsi:nil="true" />
            <extendedValidationEndDate>dateTime</extendedValidationEndDate>
            <signingCertSubject>string</signingCertSubject>
            <bIsDocTimeStamp>boolean</bIsDocTimeStamp>
            <procesStatus>string</procesStatus>
          </PreservationInfo>
          <PreservationInfo>
            <sid>string</sid>
            <sigStatus xsi:nil="true" />
            <extendedValidationEndDate>dateTime</extendedValidationEndDate>
            <signingCertSubject>string</signingCertSubject>
            <bIsDocTimeStamp>boolean</bIsDocTimeStamp>
            <procesStatus>string</procesStatus>
          </PreservationInfo>
        </sigsPreservationStatus>
        <preservationHistory>
          <PreservationRecord>
            <id>int</id>
            <operationTime>dateTime</operationTime>
            <operationType>REGISTER or UPDATE or UNREGISTER or UNKNOWN</operationType>
            <operationStatus>int</operationStatus>
            <operationStatusInfo>string</operationStatusInfo>
            <fileName>string</fileName>
            <fileSize>long</fileSize>
            <hashIn>string</hashIn>
            <hashOut>string</hashOut>
            <userComment>string</userComment>
          </PreservationRecord>
          <PreservationRecord>
            <id>int</id>
            <operationTime>dateTime</operationTime>
            <operationType>REGISTER or UPDATE or UNREGISTER or UNKNOWN</operationType>
            <operationStatus>int</operationStatus>
            <operationStatusInfo>string</operationStatusInfo>
            <fileName>string</fileName>
            <fileSize>long</fileSize>
            <hashIn>string</hashIn>
            <hashOut>string</hashOut>
            <userComment>string</userComment>
          </PreservationRecord>
        </preservationHistory>
        <docType>string</docType>
      </Report>
      <XMLReport>base64Binary</XMLReport>
      <HTMLReport>base64Binary</HTMLReport>
      <PDFReport>base64Binary</PDFReport>
      <StatusMessage>string</StatusMessage>
    </Preserve_getInfoResponse>
  </soap:Body>
</soap:Envelope>

Output parameters of the method

<Preserve_getInfoResult>

Return value Description

int

Result of the Preserve_getInfoResult method.

0 = OK, otherwise see Return codes of all methods and error described in StatusMessage.

<Report>

<CreationDateTime>

Return value Description

dateTime

Date and time of creating the report with information on the preserved document with electronic signatures.

<docID>

Return value Description

string

Unique identifier of the preserved document with electronic signatures. It was generated automatically during the preservation process in the SecuSign service. This identifier can be used with the Preserve_getInfo method to get details of the preserved document.

Max. 128 characters.

<fileName>

Return value Description

string

Name of the preserved document with electronic signatures.

Max. 260 characters.

<fileSize>

Return value Description

long

Size of the preserved document with electronic signatures.

<sortInfo>

Return value Description

string

Sorting details – e.g. folder name or structure of nested folders in which the document is registered with the user. Max. 100 characters.

<lastUpdate>

Return value Description

dateTime

Date and time of the last validity and validability extension for the document with electronic signatures.

<expiration>

Return value Description

dateTime

Date and time when the whole document’s validability expires. After this date it will not be possible to validate the signature certificates / seals / time stamps and provide further validability and validity of the document.

<docDataHash>

Return value Description

Base64Binary

Hash of the analyzed document encoded in Base64. The hash calculation algorithm is in the following docDataHashAlg element.

<docDataHashAlg>

Return value Description

string

The hash calculation algorithm for the analyzed document. The format is e.g.: 2.16.840.1.101.3.4.2.1.

<currSignHashAlg>

Return value Description

string

The hash calculation algorithm of the last signature.

Example: 2.16.840.1.101.3.4.2.1

<sigValidityCondition>

Return value Description

string

Selected signature validity conditions at the time it was preserved. Values:

  • ALL – all signatures are valid.

  • AT_LEAST_ONE – at least one of the signatures is valid.

  • LAST – the last signature is valid.

<sigsPreservationStatus>

<PreservationInfo>

Repeating element based on the number of signatures in the document.

<sid>
Return value Description

string

Identifier of the signature registered for the document by the SecuSign service.
<sigStatus>
<indication>
Return value Description

string

Signature validation status – indication. It may be one of the following values:

  • VALID - TOTAL_PASSED according to the ETSI [2]

  • INVALID - TOTAL_FAILED according to the ETSI [2]

  • INDETERMINATE – INDETERMINATE according to the ETSI [2] (may be temporary)

  • UNKNOWN.
<subindication>
Return value Description

string

Signature validation substatus – subindication. It may be one of the following values (according to the ETSI standard [2]):

  • VALID - The certificate was verifiably not revoked or expired at the time of signing, which means it is valid.

  • INVALID_REVOKED - The signature certificate had been revoked before the time of signing. Signature is invalid.

  • INVALID_HASH_FAILURE - The hash of signed data does not match the hash in signature. Signature is invalid.

  • INVALID_SIG_CRYPTO_FAILURE - Could not verify relation between the public key and the signature. Signature is invalid.

  • INVALID_FORMAT_FAILURE - The signed data has not been recognized; the format is invalid. Signature is invalid.

  • INDETERMINATE_NO_CERTIFICATE_CHAIN_FOUND - Signature validity cannot be decided at this moment. The certificate chain for the signature certificate could not be built up to a trusted anchor due to an unknown or unavailable CA, therefore the relevant CRL lists could not be obtained.

  • INDETERMINATE_NO_POE - Signature validity cannot be decided at this moment. Not enough information to validate the signature. This happens for example when relevant CRL lists cannot be acquired.

  • INDETERMINATE_TRY_LATER - Temporary status. The signature validity cannot be reliably determined because the required time period (so-called grace period) has not passed and therefore relevant revocation data is unavailable yet. The signature is too fresh and cannot be validated before.

  • INDETERMINATE_SIGNED_DATA_NOT_FOUND - Signature validity cannot be decided at this moment. The signed data could not be found.

  • INDETERMINATE_UNKNOWN_SIGNING_TIME - Signature validity cannot be decided at this moment. The time of signing is unknown and therefore the signature validity cannot be reliably verified. Nevertheless, it has currently not been found invalid.

  • INDETERMINATE_UNTRUST_SIGNING_TIME - Signature validity cannot be decided at this moment. There is no trusted information about signing time from time stamp. Nevertheless, it has currently not been found invalid.

  • INDETERMINATE_GENERAL_ERROR - Signature validity cannot be decided at this moment. General error, contact the service administrator.

  • INDETERMINATE_REVOKED_NO_POE - Signature validity cannot be decided at this moment. Signing certificate was revoked at the validation date/time but uncertain signing time.

  • INDETERMINATE_REVOKED_CA_NO_POE - Signature validity cannot be decided at this moment. At least one certificate chain was found but an intermediate CA certificate is revoked.

  • INDETERMINATE_OUT_OF_BOUNDS_NO_POE - Signature validity cannot be decided at this moment. The signing certificate is expired or not yet valid at the validation date/time and the Signature Validation Algorithm cannot ascertain that the signing time lies within the validity interval of the signing certificate.

  • INDETERMINATE_EXPIRED - Signature validity cannot be decided at this moment. The signature’s certificate has expired. The signature has been created after the expiration date (notAfter) of the signing certificate.

  • INDETERMINATE_NOT_YET_VALID - Signature validity cannot be decided at this moment. The signature’s certificate was not yet valid at the time of verification. The signing time lies before the issuance date (notBefore) of the signing certificate.

  • INDETERMINATE_POLICY_PROCESSING_ERROR - Signature validity cannot be decided at this moment. A given formal policy file could not be processed for any reason (e.g., not accessible, not parseable, digest mismatch, etc.)

  • INDETERMINATE_TIMESTAMP_ORDER_FAILURE - Signature validity cannot be decided at this moment. Some constraints on the order of signature timestamps and/or signed data object(s) timestamps are not respected.

  • INDETERMINATE_SIG_CONSTRAINTS_FAILURE - Signature validity cannot be decided at this moment. Signature’s constraints were not fulfilled (missing some of signed attributes, bad policy, …)

  • INDETERMINATE_CHAIN_CONSTRAINTS_FAILURE - Signature validity cannot be decided at this moment. General system error when building a path for the signing certificate.

  • INDETERMINATE_CRYPTO_CONSTRAINTS_FAILURE - At least one of the algorithms that have been used in material (e.g. the signature value, a certificate…​) involved in validating the signature, or the size of a key used with such an algorithm, is below the required cryptographic security level, and this material was produced after the time up to which this algorithm/key was considered secure (if such a time is known); and the material is not protected by a sufficiently strong time-stamp applied before the time up to which the algorithm/key was considered secure (if such a time is known).

</sigStatus>

<extendedValidationEndDate>
Return value Description

dateTime

Date and time until when the signature validability were extended.
<signingCertSubject>
Return value Description

string

Treated signature certificate identification.
<bISDocTimeStamp>
Return value Description

boolean

Specifies whether the signature is a standalone time stamp.
<procesStatus>
Return value Description

string

Signature treatment status at the time of preservation. Values:

  • None – The signature was not treated

  • Full – The signature was fully treated.

  • Partial – The signature was treated partially (does not contain all validation data).

  • Unknown – Unknown status.

</PreservationInfo>

</sigsPreservationStatus>

<preservationHistory>

<PreservationRecord>
<id>
Return value Description

int

Identification of the operation performed.
<operationTime>
Return value Description

dateTime

Operation date and time.
<operationType>
Return value Description

PreserveOperation

Type of operation performed. Values:

  • REGISTER – preservation of a document with electronic signatures

  • UPDATE – validity and validability extension for a document’s electronic signatures

  • UNREGISTER – removal of a document from preservation in the SecuSign service

  • UNKNOWN – unknown operation type.
<operationStatus>
Return value Description

int

Operation status. 0 = OK.
<operationStatusInfo>
Return value Description

string

Text statement corresponding to the operation status.
<fileName>
Return value Description

string

Name of file whose signature was preserved. Max. 260 characters.
<fileSize>
Return value Description

long

Size of file whose signature was preserved.
<hashIn>
Return value Description

string

Hash of the input document file.
<hashOut>
Return value Description

string

Hash of the output document file.
<userComment>
Return value Description

string

User comment or description of the document.

</PreservationRecord>

</preservationHistory>

<docType>

Return value Description

UNKNOWN

Unknown document type.

CMSPKCS7

Document signed with an internal CMS/PKCS7 signature, e.g. Data messages from the Data Mailbox Information System.

CMSPKCS7Ext

Document signed with an external CMS/PKCS7 signature, e.g. Data messages from the Data Mailbox Information System.

PDF

PDF document.

XML

XML data.

XML602FORM

FO/ZFO forms for Software602 Form Filler.

XMLISDOC

Signed XML ISDOC data.

ASiC_S_CAdES

ASiC-Simple with CAdES signature.

ASiC_S_XAdES

ASiC-Simple with XAdES signature.

ASiC_S_Tst

ASiC-Simple with Timestamp.

ASiC_E_CAdES_Tst

ASiC-Extended with CAdES signature or Timestamp.

ASiC_E_XAdES

ASiC-Extended with XAdES signature.

MS_WORD

Signed MS Word document.

MS_EXCEL

Signed MS Excel document.

MS_PWR_PNT

Signed MS PowerPoint document.

ODF

Signed OpenDocumentFormat (OpenOffice).

</Report>

<XMLReport>

Return value Description

Base64Binary

XML report data with information on the preserved document, encoded in Base64.

<HTMLReport>

Return value Description

Base64Binary

HTML report data with information on the preserved document, encoded in Base64.

<PDFReport>

Return value Description

Base64Binary

PDF report data with information on the preserved document, encoded in Base64.

<StatusMessage>

Return value Description

String

Text statement corresponding to the overall result of getting information for a document with electronic signatures in the SecuSign service. The value is only filled if the result is complicated.