span-services-docs/WS-Security Requirement and Implementation Suggestion.md

# WS-Security Requirement and Implementation Suggestion

## Overview
WS-Security adalah standar untuk mengamankan _SOAP message_ dan fungsinya adalah untuk memastikan integritas (_SOAP message_ tidak pernah diubah) dan _authenticity_ (dibuat oleh pengirim yg sebenarnya).

## Requirement
- _Authentication Method / Token Profile_: X.509Certificate Token Profile
- _Header Attributes_: soapenv:mustUnderstand="1" harus ada di <wsse:Security> header.
- _Canonicalization_: dibutuhkan _Exclusive XML Canonicalization Omit/Without Comment_
- _KeyIdentifier_: apa saja dari ISSUER_SERIAL, ISSUER_SERIAL_QUOTE_FORMAT, BST_DIRECT_REFERENCE, X509_KEY_IDENTIFIER, THUMBPRINT_IDENTIFIER, SKI_KEY_IDENTIFIER (dilarang pakai KEY_VALUE) (disarankan, saat ini biasa yg dipakai BST_DIRECT_REFERENCE)
- _Signature Algorithms_: apa saja dari RSA_SHA1, RSA_SHA256, RSA_SHA512
- _Digest Algorithms_: apa saja dari SHA1, SHA256, SHA384, SHA512
- _Signature Scope_: hanya dibutuhkan di _SOAP Body_
- _Timestamp_: tidak dibutuhkan
- Enkripsi: jangan

## Sample WS-Security
Ini dibuat pakai WSS4J dengan Crypto Provider Merlin dan opsi:
- SigCanonicalization: C14N_EXCL_OMIT_COMMENTS
- KeyIdentifierType: BST_DIRECT_REFERENCE
- SignatureAlgorithm: RSA_SHA1
- DigestAlgo: SHA256

```xml
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
  <soapenv:Header>
    <wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" soapenv:mustUnderstand="1">
      <wsse:BinarySecurityToken EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary" ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3" wsu:Id="X509-33adc7a9-743b-4acd-ac3d-7947b5728d8b">MII...base64-cert...</wsse:BinarySecurityToken>
      <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#" Id="SIG-e3b862f3-c19b-43a8-bdd2-3aa53cb306eb">
        <ds:SignedInfo>
          <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#">
            <ec:InclusiveNamespaces xmlns:ec="http://www.w3.org/2001/10/xml-exc-c14n#" PrefixList="soapenv"/>
          </ds:CanonicalizationMethod>
          <ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
          <ds:Reference URI="#id-e4e057db-4f7f-4c44-aae6-ffb3607ba5fd">
            <ds:Transforms>
              <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
            </ds:Transforms>
            <ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
            <ds:DigestValue>U2VsYW1hdC4uLiBBbmRhIG1lbmVtdWthbiBzYXlh4nE=</ds:DigestValue>
          </ds:Reference>
        </ds:SignedInfo>
        <ds:SignatureValue>SGVsbG8gdGhlcmUuIEhvdydzIGxpZmU/IC0tc2tyYW1kNGogZGV2ZWxvcGVyy7+RjD9xM1naWNTuekorKgW4f5UTcLhFGPh81RqrXvbsWspjqUMLCS/7xQU1ipQLjVFfAG+S2/72S9OiILhz9ei6hIIJCodkf96PmaldSSNgKgw=</ds:SignatureValue>
        <ds:KeyInfo Id="KI-3336434d-1994-4afc-9b9b-5df2de3b8761">
          <wsse:SecurityTokenReference wsu:Id="STR-606e4c7b-1e9d-42a8-bbd1-d426c22afb45">
            <wsse:Reference URI="#X509-33adc7a9-743b-4acd-ac3d-7947b5728d8b" ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3"/>
          </wsse:SecurityTokenReference>
        </ds:KeyInfo>
      </ds:Signature>
    </wsse:Security>
  </soapenv:Header>
  <soapenv:Body xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" wsu:Id="id-e4e057db-4f7f-4c44-aae6-ffb3607ba5fd">
  Meow kucing
</soapenv:Body>
</soapenv:Envelope>
```

# Implementation Suggestion
Pakai ini (atau yg lebih baik, yg disupport):
- SigCanonicalization: C14N_EXCL_OMIT_COMMENTS
- KeyIdentifierType: BST_DIRECT_REFERENCE
- SignatureAlgorithm: RSA_SHA256
- DigestAlgo: SHA256

Lihat [sign example](./com-example-wssecurity).

## Caveats
- **Pastikan Body dan SignedInfo tidak berubah setelah proses signing**. Proses signing mengunci keaslian data dengan cara membubuhkan bukti hashing kriptografi untuk mendeteksi adanya perubahan. Jadikan proses signing hal yg sangat terakhir dari _workflow_ anda. Silahkan atur data sesuai keinginan namun jangan ubah sama sekali setelah proses signing. (beda spasi saja akan merusak signing).
- **Disarankan gunakan [implementation suggestion](#implementation-suggestion)** apabila bingung.
- **_Selftest_ terlebih dahulu jika ingin memastikan**. Sign data anda lalu verify secara mandiri.