Tanda tangan digital mencatat siapa yang menandatangani dokumen. Timestamp tepercaya mencatat kapan, dan waktu tersebut berasal dari otoritas timestamp independen (TSA) bukan dari jam pada komputer penandatangan. Tutorial ini menunjukkan cara menandatangani dokumen Word dengan tanda tangan XAdES‑T yang memiliki timestamp menggunakan Python, kemudian mengonfirmasi bahwa timestamp tersebut ada dalam file.

Poin Utama

  • Setel keduanya SignOptions.xml_dsig_level = XmlDsigLevel.X_AD_ES_T dan SignOptions.timestamp_settings. Jika hanya satu yang diatur, akan menghasilkan tanda tangan tanpa cap waktu, dan tidak ada error yang memberi tahu Anda hal itu.
  • Aspose.Words meminta cap waktu selama DigitalSignatureUtil.sign, sehingga panggilan tersebut memerlukan akses jaringan ke TSA.
  • DOCX dan DOC dapat diberi cap waktu. File ODT tidak dapat.
  • DigitalSignature.is_valid memeriksa tanda tangan, bukan cap waktu. Konfirmasikan cap waktu secara terpisah.

Apa yang Ditambahkan Timestamp Terpercaya pada Tanda Tangan

Setiap tanda tangan yang dibuat oleh Aspose.Words membawa waktu penandatanganan, yang diatur oleh SignOptions.sign_time. Nilai tersebut berasal dari mesin penandatangan, sehingga siapa pun yang menentang dokumen dapat menentang waktu tersebut juga.

Signature XAdES‑T menambahkan bukti independen. Setelah dokumen ditandatangani, Aspose.Words mengirimkan hash nilai tanda tangan ke TSA. TSA mengembalikan token RFC 3161, yang ditandatangani dengan sertifikatnya sendiri, yang mengikat hash ke waktu tertentu. Token tersebut disimpan di dalam tanda tangan. Seorang verifier kemudian dapat menunjukkan bahwa tanda tangan tersebut ada pada saat itu, yang paling penting ketika sertifikat penandatangan kemudian kedaluwarsa atau dicabut.

Prasyarat

Sebelum Anda menjalankan contoh, pastikan Anda memiliki:

pip install --upgrade "aspose-words>=26.9"
  • Sertifikat penandatangan dalam format PKCS#12 (.pfx atau .p12) dan kata sandinya.
  • URL otoritas timestamp. Contoh menggunakan FreeTSA (https://freetsa.org/tsr), sebuah TSA publik gratis yang nyaman untuk pengujian. Untuk dokumen produksi, gunakan TSA yang direkomendasikan oleh organisasi atau penyedia sertifikat Anda, karena orang yang memeriksa dokumen Anda harus mempercayai sertifikat TSA tersebut.
  • Kredensial TSA, hanya jika TSA Anda memerlukan otentikasi.

Tanpa lisensi, Aspose.Words berjalan dalam mode evaluasi dengan batasan. Sebuah lisensi sementara menghapusnya saat Anda menguji.

Tandatangani Dokumen Word dengan Timestamp Tepercaya

Script berikut menandatangani file DOCX dengan tanda tangan XAdES‑T dan menyematkan timestamp dari TSA.

import datetime
import aspose.words as aw

# Replace these values with your own files and credentials.
INPUT_DOC = "contract.docx"
OUTPUT_DOC = "contract-signed.docx"
CERT_FILE = "signing-cert.pfx"
CERT_PASSWORD = "your-pfx-password"

TSA_URL = "https://freetsa.org/tsr"
TSA_USER = ""       # Fill in only if your TSA requires authentication.
TSA_PASSWORD = ""

# Load the signing certificate from a PKCS#12 file.
cert_holder = aw.digitalsignatures.CertificateHolder.create(
    file_name=CERT_FILE, password=CERT_PASSWORD)

# Request an XAdES-T signature and point it at a timestamp authority.
sign_options = aw.digitalsignatures.SignOptions()
sign_options.xml_dsig_level = aw.digitalsignatures.XmlDsigLevel.X_AD_ES_T
sign_options.timestamp_settings = aw.digitalsignatures.DigitalSignatureTimestampSettings(
    server_url=TSA_URL,
    user_name=TSA_USER,
    password=TSA_PASSWORD,
    timeout=datetime.timedelta(seconds=60),  # Default is 100 seconds.
)

# Sign the document. Aspose.Words contacts the TSA during this call.
aw.digitalsignatures.DigitalSignatureUtil.sign(
    src_file_name=INPUT_DOC,
    dst_file_name=OUTPUT_DOC,
    cert_holder=cert_holder,
    sign_options=sign_options,
)
print(f"Signed with a trusted timestamp: {OUTPUT_DOC}")

Cara Kerja Kode

  • CertificateHolder.create membaca kunci pribadi dan rantai sertifikat dari file .pfx. Kata sandi yang salah akan gagal di sini, sebelum proses penandatanganan dimulai.
  • XmlDsigLevel.X_AD_ES_T memberi tahu Aspose.Words untuk membuat tanda tangan XAdES-T, yang merupakan XAdES-EPES ditambah cap waktu tanda tangan.
  • DigitalSignatureTimestampSettings menyimpan URL TSA, nama pengguna dan kata sandi opsional, serta batas waktu opsional. String kosong diperbolehkan untuk TSA yang menerima permintaan anonim. Jika TSA merespons dengan tantangan otentikasi HTTP, Aspose.Words mengirimkan kredensial yang Anda berikan.
  • DigitalSignatureUtil.sign menulis salinan yang ditandatangani ke OUTPUT_DOC dan membiarkan file input tidak berubah. Menandatangani dokumen yang belum ditandatangani: jika input sudah memiliki tanda tangan, output akan berisi tanda tangan yang ada serta yang baru.

Periksa Apakah Timestamp Telah Disematkan

Objek DigitalSignature yang dikembalikan oleh Aspose.Words tidak menampilkan timestamp, dan is_valid tidak memeriksanya. Dalam pengujian, sebuah dokumen yang token timestamp‑nya sengaja rusak masih melaporkan is_valid sebagai True. Untuk mengonfirmasi timestamp, lihat di dalam XML tanda tangan yang disimpan dalam paket DOCX:

import base64
import re
import zipfile
import aspose.words as aw

SIGNED_DOC = "contract-signed.docx"

# 1. Check the signature itself.
for sig in aw.digitalsignatures.DigitalSignatureUtil.load_signatures(SIGNED_DOC):
    print(f"Signer: {sig.subject_name} | valid: {sig.is_valid}")

# 2. Check that a timestamp token was embedded, and save it for inspection.
with zipfile.ZipFile(SIGNED_DOC) as package:
    for part in package.namelist():
        if part.startswith("_xmlsignatures/sig") and part.endswith(".xml"):
            xml = package.read(part).decode("utf-8")
            match = re.search(r"<(?:\w+:)?EncapsulatedTimeStamp[^>]*>([^<]+)<", xml)
            if match:
                with open("timestamp-token.der", "wb") as f:
                    f.write(base64.b64decode(match.group(1)))
                print(f"{part}: timestamp embedded (saved to timestamp-token.der)")
            else:
                print(f"{part}: no timestamp found")

Untuk DOCX yang ditandatangani, Anda harus melihat output yang serupa dengan ini:

Signer: CN=Your Name | valid: True
_xmlsignatures/sig1.xml: timestamp embedded (saved to timestamp-token.der)

Untuk membaca waktu yang disertifikasi TSA, berikan token yang disimpan ke OpenSSL:

openssl ts -reply -token_in -in timestamp-token.der -token_out -text

Baris Time stamp menunjukkan waktu bersertifikat dalam GMT, dan baris TSA mengidentifikasi otoritas yang mengeluarkannya.

Pemeriksaan ini membaca format paket DOCX. File DOC menyimpan tanda tangannya dalam kontainer biner, sehingga skrip berbasis ZIP tidak berlaku untuknya.

Memecahkan Masalah Kesalahan Penandatanganan dan Stempel Waktu

GejalaPenyebab yang MungkinApa yang Harus Dilakukan
Penandatanganan berhasil, tetapi tidak ada stempel waktu yang disematkanHanya satu dari xml_dsig_level = X_AD_ES_T dan timestamp_settings yang diaturAtur keduanya sebelum memanggil sign. Dengan XML_D_SIG atau X_AD_ES_EPES, pengaturan stempel waktu diabaikan.
RuntimeError menyebutkan (401) UnauthorizedTSA memerlukan kredensial, atau kredensialnya salahBerikan nama pengguna dan kata sandi yang dikeluarkan oleh penyedia TSA Anda.
RuntimeError menyebutkan koneksi ditolak atau kesalahan proxyURL TSA salah, atau firewall atau proxy memblokir permintaanPeriksa URL dan pastikan mesin yang menjalankan skrip Anda dapat menjangkau TSA.
RuntimeError menyebutkan The operation has timed outTSA tidak menjawab dalam batas waktuCoba lagi, atau berikan timeout yang lebih lama ke DigitalSignatureTimestampSettings.
File output kosong tetap ada setelah terjadi kesalahansign membuat file tujuan sebelum permintaan TSA gagalHapus file tujuan sebelum mencoba lagi, atau tulis ke jalur sementara dan ubah namanya setelah panggilan berhasil.
RuntimeError mengatakan penandaan waktu tidak didukung oleh format file iniInputnya adalah file ODTBerikan stempel waktu pada file DOCX atau DOC, atau konversi ke PDF dan gunakan jalur penandatanganan PDF yang dijelaskan di bawah.
No usable version of libssl was found, atau crash tentang paket ICU yang hilang, pada LinuxRuntime .NET yang dibundel dalam paket Python memerlukan OpenSSL 1.1 dan versi ICU yang didukungInstal OpenSSL 1.1, atau instal ICU yang didukung. Jika aplikasi Anda tidak memerlukan format khusus budaya, atur DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=1 untuk kesalahan ICU.

Alternatif: Menandai Waktu Tanda Tangan dalam Output PDF

Jika penerima Anda memerlukan PDF daripada file Word yang ditandatangani, Anda tidak memerlukan DigitalSignatureUtil. Tanda tangani dan beri cap waktu PDF saat menyimpannya dengan mengatur PdfSaveOptions.digital_signature_details.timestamp_settings ke objek PdfDigitalSignatureTimestampSettings. Jalur ini telah tersedia jauh lebih lama daripada 26.9. Referensi PdfDigitalSignatureTimestampSettings mencakup contoh lengkap.

Langkah Selanjutnya

Untuk menambahkan baris tanda tangan, menandatangani dengan gambar baris tanda tangan, atau menghapus tanda tangan yang ada, lihat Bekerja dengan Tanda Tangan Digital dalam dokumentasi Aspose.Words for Python.

FAQ

  1. Apa yang ditambahkan timestamp tepercaya pada tanda tangan digital?
    Otoritas timestamp (TSA) mengesahkan waktu tanda tangan dibuat. Waktu tersebut berasal dari pihak ketiga independen, bukan dari jam komputer penandatangan, dan memungkinkan verifikator menunjukkan bahwa tanda tangan ada sebelum sertifikat penandatangan kedaluwarsa atau dicabut.

  2. Versi Aspose.Words mana yang mendukung timestamping di DigitalSignatureUtil?
    Versi 26.9 dari Aspose.Words for Python via .NET menambahkan SignOptions.timestamp_settings, XmlDsigLevel.X_AD_ES_T, dan kelas DigitalSignatureTimestampSettings. Versi sebelumnya hanya dapat menambahkan timestamp pada tanda tangan dalam output PDF.

  3. Apakah saya perlu mengatur xml_dsig_level dan timestamp_settings?
    Ya. Jika hanya salah satu yang diatur, Aspose.Words tetap menandatangani dokumen tetapi tidak meminta atau menyematkan timestamp, dan tidak menghasilkan error.

  4. Format file apa yang dapat ditambahkan timestamp?
    File DOCX dan DOC yang ditandatangani dengan X_AD_ES_T menerima timestamp. Menandatangani file ODT dengan timestamp menghasilkan error yang menyatakan format tersebut tidak mendukung timestamping.

  5. Apakah is_valid mengonfirmasi bahwa timestamp valid?
    Tidak. DigitalSignature.is_valid memeriksa tanda tangan itu sendiri. Untuk mengonfirmasi timestamp, periksa bahwa XML tanda tangan berisi token timestamp dan inspeksi token tersebut dengan alat seperti OpenSSL.

  6. Apa yang terjadi jika TSA tidak dapat dijangkau?
    DigitalSignatureUtil.sign menghasilkan RuntimeError yang menjelaskan masalah jaringan, otentikasi, atau timeout. Jalur tujuan mungkin tertinggal sebagai file kosong, jadi hapus file tersebut sebelum mencoba lagi.

Dapatkan Lisensi Gratis dan Dukungan