Získání pečeti / podpisu k hash

Metoda webové služby SignHash umožňuje vytvořit podpis/pečeť k hash libovolného dokumentu nebo datům.

Výpočet hash provádí volající aplikace, která je zodpovědná za správnost výpočtu hashe. Pro správné vytvoření podpisu/pečeti k danému hash je nutné, aby odpovídal také hashovací algoritmus.

Vrácený podpis/pečeť k hash je třeba odpovídajícím způsobem vložit do dat dokumentu (dle specifikací ETSI) nebo uchovat u daného souboru (v případě externího CMS podpisu).

Dostupnost metody ve webové definici je závislá na verzi webové služby SecuSign SDK (viz Konfigurace).

Název metody: SignHash

Popis služby včetně WSDL schématu a příklad požadavku a odpovědi pro SOAP 1.1 a SOAP 1.2 je umístěn na https://localhost/secusign/default.asmx?op=SignHash.

Localhost je název používaný pro lokální počítač; namísto něj zvolte jméno/IP adresu SDK serveru (dle nastavení v IIS).

Požadavek v rozhraní SOAP 1.1

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>

Vstupní parametry metody

<Hash>

[povinný element]

Vstup Popis

Base64Binary

Vypočtený Hash dokumentu nebo dat kódovaný v Base64.

Pro výpočet kódovaného Base64 sha256 hash lze využít např. openssl:

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

  • certutil -encode hash.bin hash.b64

nebo třeba externí online aplikace:

<HashAlgOID>

[povinný element]

Vstup Popis

String

OID hashovacího algoritmu použitého pro výpočet. Například pro hashovací algoritmus SHA256 to je OID: 2.16.840.1.101.3.4.2.1.

<CertificateID>

[nepovinný element]

Vstup Popis

String

Identifikace certifikátu pro vytvoření zaručené/kvalifikované elektronické pečeti nebo zaručeného/kvalifikovaného elektronického podpisu.

V případě in-house rozhraní SecuSign SDK je možné použít formáty:

  • PKCS11:[alias]

    • alias certifikátu pro podepsání/pečetění z HSM modulu klienta nebo ze systémového úložiště Windows.

  • QStore:[alias]

    • Pečetí se certifikátem nahraným na účtu klienta v Azure KeyVault.

  • urn:hex:[hexadecimalne_kodovany_sha1_hash_certu]

    • podepsání/pečetění certifikátem ze systémového úložiště Windows pod Current User. Nutné spouštět aplikační pool pod konkrétním uživatelem.

  • urn:sha:[Base64_kodovany_sha1_hash_certu]

    • podepsání/pečetění certifikátem ze systémového úložiště Windows pod Current User. Nutné spouštět aplikační pool pod konkrétním uživatelem.

  • [cesta k PFX]

    • podepsání konkrétním PFX, který je lokálně přístupný pro webovou službu/aplikaci v souboru.

  • prázdný řetězec

    • použije se nastavení SigningCertPath v konfiguraci webové služby SecuSign SDK.

    • pokud je v konfiguraci webové služby nastaven konfigurační klíč Seal_DefaultToQStore, pak se použije výchozí certifikát ze služby Vzdáleného pečetění

V případě webových služeb SecuSign v Azure je možné použít např. hodnotu z CN nebo SERIALNUMBER – obě informace je možné zjistit v administraci služby SecuSign > Seal po přihlášení do uživatelského rozhraní 602 ID účtu.

Výchozí hodnota: prázdný řetězec.

<PrivateKeyPIN>

[nepovinný element]

Vstup Popis

string

PIN, který byl zvolen žadatelem jako přístupové heslo k privátní části certifikátu:

  • Hodnota je povinná v případě QStore, PKCS11 a souboru PFX.

  • Pro podepisování s nastaveným potvrzením pomocí PIN je nutné PrivateKeyPIN uvést.

  • Pro podepisování s nastaveným potvrzením pomocí 602KEY se PrivateKeyPIN neuvádí.

  • Pro pečetění není nutné PrivateKeyPIN uvádět, protože přístup k certifikátu je definován na základě autentizačního (licenčního) certifikátu volající aplikace, pokud není zvoleno jinak.

<SignatureFormat>

[nepovinný element]

Vstup Popis

Int

Typ podpisu/pečeti. Hodnoty:

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

  • 1 = PKCS1 signature,

  • 2 = PKCS1 signature, ale parametr Hash obsahuje přímo DigestInfo (struktura obsahující hash dokumentu a OID použitého hash algoritmu).

<Params>

[nepovinný element]

Vstup Popis

String

Nepovinné, aktuálně se nevyužívá.

Struktura odpovědi na požadavek

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>

Výstupní parametry metody

<SignHashResult>

Návratová hodnota Popis

Int

Výsledek metody SignHash (získání podpis/pečeti k hash). 0 = v pořádku, jinak Návratové kódy všech metod a chyba popsaná ve StatusMessage.

<Output>

Návratová hodnota Popis

Base64Binary

Podepsaná data ve formátu CMS nebo PKCS1 kódovaná v Base64.

<SigningCert>

Návratová hodnota Popis

Base64Binary

Data X.509 certifikátu použitého pro podpis/pečeť kódovaná v Base64. Ze získaných dat lze po dekódování zjistit např. vystavitel certifikátu, pro koho byl certifikát vystaven, platnost certifikátu od-do, kryptografický otisk (hash) a další informace.

<StatusMessage>

Návratová hodnota Popis

String

Textová zpráva odpovídající celkovému výsledku získání pečeti/podpisu k hash. Hodnota je naplněna pouze v případě problematického výsledku.