Getting a seal / signature for a hash

The web service method SignHash allows to create a signature/seal for a hash of any document or data.

The hash calculation is run by the calling application, which is responsible for the hash calculation correctness. To create the signature/seal correctly for the hash, it is necessary to match the hashing algorithm.

The returned signature/seal for the hash must be correctly inserted in the document data (as specified by ETSI) or store with the file (in the case of an external CMS signature).

Availability of this method in the web definition depends on the version of SecuSign SDK web service.

Method name: SignHash

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=SignHash *

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/SignHash"

<?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>
    <SignHash xmlns="http://software602.com/secusign/">
      <Hash>base64Binary</Hash>
      <HashAlgOID>string</HashAlgOID>
      <CertificateID>string</CertificateID>
      <SignatureFormat>integer</SignatureFormat>
      <Params>string</Params>
    </SignHash>
  </soap:Body>
</soap:Envelope>

Input parameters of the method

<Hash>

[mandatory element]

Input Description

Base64Binary

Calculated hash of the document or data, encoded in Base64

To calculate a Base64 encoded sha256 hash, you can use e.g., openssl

  • openssl sha256 -binary test.pdf >hash.bin.

  • certutil -encode hash.bin hash. b64.

Or online applications:

<HashAlgOID>

[mandatory element]

Input Description

String

OID of the hashing algorithm used in the calculation. E.g., for the hashing algorithm SHA256, the OID would be: 2.16.840.1.101.3.4.2.1.

<CertificateID>

[optional element]

Input Description

String

Identification of the certificate to create an advanced/qualified electronic seal or an advanced/qualified electronic signature.

For in-house SecuSign SDK interface, the following formats can be used:

  • HStore: [alias]

    • Alias of the signing/sealing certificate from the HSM module of the Remote signing/sealing service.

    • If configuration key Seal_DefaultToQStore is specified in the web service configuration, the HStore prefix is not used.

  • PKCS11: [alias]

    • Alias of the signing/sealing certificate from the client’s HSM module or from the Windows system store.

  • QStore:[alias]

    • A certificate uploaded to the client’s account in Azure KeyVault is used for sealing.

  • urn:hex:[hexadecimal_encoded_sha1_hash_of_cert]

    • Signing/sealing using a certificate from the Windows system store under the current user. The application pool must be run under the specific user.

  • urn:sha:[Base64_encoded_sha1_hash_of_cert]

    • Signing/sealing using a certificate from the Windows system store under the current user. The application pool must be run under the specific user.

  • [path to PFX]

    • Signing by a specific PFX locally accessible to the web service/application in a file.

  • empty string

    • The SigningCertPath setting in SecuSign SDK web service configuration will be used.

    • If the web service configuration contains the configuration key Seal_DefaultToQStore, the default certificate from the Remote sealing service will be used.

For SecuSign web services in Azure, it is possible to use e.g., the value from CN or SERIALNUMBER – both details can be found in the SecuSign service administration > Seal after logging in to the 602 ID account user interface.

Default value: empty string.

<PrivateKeyPIN>

[optional element]

Input Description

string

The PIN selected by the applicant as the access password to the private part of the certificate.

The value is mandatory for QStore, PKCS11 and a PFX file.

If HStore alias is used, it depends on whether it is used for signing or sealing.

When signing, it is necessary to specify the PrivateKeyPIN if the PIN is set for confirmation (default). PrivateKeyPIN should be omitted if the 602KEY is set for confirmation (see the AuthMode value in ListCerts2).

When sealing, PrivateKeyPIN does not need to be included, because access to the certificate is based on the calling application’s authentication (license) certificate, unless specified otherwise.

<SignatureFormat>

[optional element]

Input Description

Int

Signature/seal type. Values:

  • 0 = CMS (CAdES detached) [default],

  • 1 = PKCS1 signature,

  • 2 = PKCS1 signature, but the Hash parameter contains DigestInfo (structure containing the document hash and OID of the hash algorithm used) directly.

<Params>

[optional element]

Input Description

String

Optional, currently not in use.

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>
    <SignHashResponse xmlns="http://software602.com/secusign/">
      <SignHashResult>int</SignHashResult>
      <Output>base64Binary</Output>
      <SigningCert>base64Binary</SigningCert>
      <StatusMessage>string</StatusMessage>
    </SignHashResponse>
  </soap:Body>
</soap:Envelope>

Output parameters of the method

<SignHashResult>

Return value Description

Int

Result of the SignHash method (getting a signature/seal for a hash). 0 = OK, otherwise see Return codes of all methods and error described in StatusMessage.

<Output>

Return value Description

Base64Binary

Signed data in CMS or PKCS1 format, encoded in Base64.

<SigningCert>

Return value Description

Base64Binary

Data of X.509 certificate used for the signature/seal, encoded in Base64. The data can be decoded to find e.g. the certificate issuer, to whom it was issued, certificate validity period, cryptographic fingerprint (hash) and other details.

<StatusMessage>

Return value Description

String

Text statement corresponding to the overall result of getting a seal/signature for a hash. The value is only filled if the result is complicated.