Sign

The SII validates every document and envelope with an enveloped XML signature (XMLDSig) made with the digital certificate of whoever signs. loadCertificateFromPkcs12 and loadCertificateFromPem turn your certificate into a plain Certificate object, signDocument signs a stamped document with it, and verifyDocumentSignature checks a signed <DTE>. verifyReceivedDocuments checks what a supplier sends: the signature, the stamp and the CAF of each document. Underneath, a handful of low-level functions build and verify the signature for any element, which the envelopes, the books and the SII client reuse.

Everything on this page lives in the dte-sdk entry point and runs on Node, Bun and Deno. It reads PKCS#12 and signs with node-forge, one of the four runtime dependencies of the SDK.

Usage#

import { readFileSync } from 'node:fs'
import {
  createDocument,
  loadCertificateFromPkcs12,
  parseCaf,
  signDocument,
  stampDocument,
  verifyDocumentSignature,
} from 'dte-sdk'
 
const certificate = loadCertificateFromPkcs12(readFileSync('firma.pfx'), process.env.PFX_PASSWORD!)
certificate.rut // '12345678-5', the holder RUT read from the certificate
certificate.notAfter // Date: when it expires
 
const caf = parseCaf(readFileSync('caf-33.xml', 'utf8'))
const stamped = stampDocument(createDocument(input), caf)
const signed = signDocument(stamped, certificate)
 
signed.xml // the signed <DTE>, with its TED and its Signature, no XML declaration
signed.signedAt // '2026-11-15T15:30:00', Chile time (TmstFirma)
signed.signature // { digestValue, signatureValue }
 
verifyDocumentSignature(signed.xml)
// { referenceId: 'DTE_T33F7', digestValid: true, signatureValid: true, valid: true }

Load a certificate#

From a PKCS#12 file#

loadCertificateFromPkcs12(bytes, password, options?) reads a .pfx or .p12 file. bytes is a Uint8Array (a Node Buffer is one).

const certificate = loadCertificateFromPkcs12(readFileSync('firma.pfx'), process.env.PFX_PASSWORD!)

It reads both generations of the format: legacy files (3DES and RC2) and modern ones (PBES2 with AES), with encrypted or plain key bags. It finds the leaf certificate by matching its public key with the private key, orders the chain from the leaf up to the root (the SII TLS endpoints need the intermediates), and reads the holder RUT from the certificate.

From PEM#

loadCertificateFromPem({ privateKeyPem, certificatePem, chainPem? }, options?) builds the same object from strings, for example after you converted a .pfx with openssl pkcs12 -nodes:

It checks that the private key matches the certificate (CERT_INVALID when it does not) and that the certificate is valid now: not past its notAfter (CERT_EXPIRED) and not before its notBefore (CERT_NOT_YET_VALID). loadCertificateFromPkcs12 makes the same two checks.

Options#

Both loaders take LoadCertificateOptions:

The Certificate type#

The RUT is read from the certificate, in this order: the SubjectAltName otherName with OID 1.3.6.1.4.1.8321.1 (the one the Chilean electronic signature law defines), then the serialNumber of the subject, then the OU, then a token with the shape of a RUT in the CN. Each candidate has to pass rut.ts; an invalid one falls through to the next. That is the RUT you use as senderRut in an envelope cover, because the SII expects the sender to be the holder of the signing certificate. See Envelopes.

Expiry#

import { daysUntilExpiry, isCertificateExpired } from 'dte-sdk'
 
daysUntilExpiry(certificate) // 412, whole days; negative once expired
isCertificateExpired(certificate) // false
isCertificateExpired(certificate, { marginDays: 30 }) // true when it expires within 30 days

isCertificateExpired(certificate, { now?, marginDays? }) is true when now is past notAfter minus marginDays (default 0). daysUntilExpiry(certificate, { now? }) is floor((notAfter - now) / one day). Check the margin at startup so a certificate that expires next week is noticed before it breaks an issuing run.

Errors#

import { isDteError } from 'dte-sdk'
 
try {
  loadCertificateFromPkcs12(bytes, process.env.PFX_PASSWORD!)
} catch (error) {
  if (isDteError(error) && error.code === 'CERT_PASSWORD_WRONG') {
    // ask for the password again, do not retry in a loop
  }
}

Sign a document#

signDocument(stampedDocument, certificate, options?) renders the document XML with its TED, signs the Documento element (the Liquidacion element for a settlement invoice, 43) and returns a SignedDocument: the stamped document plus:

The input must be a StampedDocument (see Stamp); that is checked at compile time, so you cannot sign a document without a TED by mistake. The signature is deterministic: the same document, certificate and times give the same bytes.

The signed document is what goes into an envelope (Envelopes); a signed <DTE> on its own is not sent to the SII.

Verify a signature#

verifyDocumentSignature(xml) verifies the signature of a <DTE> XML, yours or one you received, and returns a SignatureVerification:

verifyDocumentSignature(signed.xml).valid // true
verifyDocumentSignature(signed.xml.replace('<MntTotal>119000</MntTotal>', '<MntTotal>1</MntTotal>')).valid // false

A tampered element, a missing reference, a duplicated ID or an element moved elsewhere in the tree gives digestValid: false; it does not throw, so wrapped or duplicated elements never verify. It throws XML_PARSE_FAILED when the XML is malformed, nested deeper than 100 levels (the limit of every DOM the SDK parses) or the root is not DTE, and SIGNATURE_NOT_FOUND when there is no Signature under the root or no SignedInfo in it.

Only a signature of the form the SDK makes verifies: one Reference holding the only DigestValue, SHA-1, no transform but enveloped-signature or C14N 1.0, and C14N 1.0 with RSA-SHA1 in SignedInfo. A second Reference, another digest or another transform gives digestValid: false; another canonicalization (exclusive C14N, for one) or another signature method gives signatureValid: false. Before 0.4.0 the verifier checked only the first Reference and did not read the algorithms. The signatures the SDK makes pass as before.

valid proves that the element and SignedInfo are intact with respect to the certificate that travels in the same XML. It does not prove that this certificate belongs to the signer you expect, nor that it is valid with a certification authority: that is a separate check, and the SII does its own. Verify the stamp separately with verifyTed (Stamp), or check a received document whole with verifyReceivedDocuments (below).

The function needs the XML whose root is <DTE>: for a document inside an envelope, use the xml of each signed document, as it is in envelope.documents.

Verify received documents#

verifyReceivedDocuments(xml, options?) checks what a supplier sent you, as it arrived: a DTE, an EnvioDTE or an EnvioBOLETA. It checks the envelope's own signature and, for each document, its signature, its stamp and the CAF the stamp carries, and returns every check as data.

import { readFileSync } from 'node:fs'
import { decodeLatin1, isClaimDocumentType, verifyReceivedDocuments } from 'dte-sdk'
 
// Decode the bytes with the encoding the XML declaration names: ISO-8859-1 for the SII's documents.
// Production by default: a document stamped with a certification CAF comes back invalid.
const { envelope, documents, status } = verifyReceivedDocuments(decodeLatin1(readFileSync('EnvioDTE.xml')))
 
status // 'valid' | 'invalid' | 'unchecked': the worst of the envelope and its documents
envelope?.valid // the envelope's own signature; envelope is null for a single DTE
documents[0] // { type: 33, folio: 1234, issuerRut: '10000004-0', totalAmount: 119000, signature, ted, caf, status, xml, … }
 
// The documents you can accept or claim in the SII's registry
const toAnswer = documents.filter((doc) => doc.status === 'valid' && isClaimDocumentType(doc.type))

Each document is checked three ways:

A document's status is invalid when a check fails, unchecked when none fails but the CAF's IDK has no known key, and valid otherwise; the status of the whole result is the worst of the envelope and the documents. A document that fails a check is a result, not an error. The function throws only for input it cannot read: XML_PARSE_FAILED for malformed XML, a DOCTYPE, another root, an envelope without exactly one SetDTE, a prefixed DTE or Documento, a DTE without its Documento, or elements nested deeper than 100 levels, and ENVELOPE_EMPTY for an envelope without documents. Before 0.7.0 a file of a few thousand nested elements overflowed the stack with a RangeError; no document the SII or an issuer writes comes close to 100.

The SII's keys and the environment#

SII_CAF_KEYS holds the keys 100 (certification) and 300 (production) with which the SII signs every CAF, taken from the SII's certificates as CryptoSys and LibreDTE publish them, the same bytes in both. Only the key of environment is accepted, production by default: a CAF signed with the other one is invalid, with the mismatch environment, and caf.environment says which it is, so a certification document never passes for a production one. Pass environment: 'certification' to check documents of the certification environment. siiKeys replaces the key material; spread SII_CAF_KEYS into it to add a key. cafEnvironment(keyId) says which environment an IDK is for: certification for 100, production for 300, null for another.

verifyCafSignature(cafXml, { environment }) checks the FRMA of a single CAF by the same rule and returns 'valid', 'invalid' or 'unchecked'. To check the CAF your own TEDs will carry, pass it the block parseCaf keeps:

import { readFileSync } from 'node:fs'
import { parseCaf, verifyCafSignature } from 'dte-sdk'
 
const caf = parseCaf(readFileSync('caf-33.xml', 'latin1')) // CAF files are ISO-8859-1
verifyCafSignature(caf.xml, { environment: 'certification' }) // 'valid' for a CAF the SII issued in certification

It throws CAF_INVALID when the text is not XML, holds a DOCTYPE, or has no single CAF with one DA and one FRMA. An FRMA that is there but empty is a signature that fails, not a CAF that is not one: it is invalid, whatever the CAF's IDK, as an FRMA that is not base64. Before 0.7.0 it threw CAF_INVALID, and in verifyReceivedDocuments such a CAF was no CAF, so the stamp, left without its key, failed too. Now the CAF is found and fails its SII signature, and the stamp is checked with the CAF's key like any other.

What is checked, and what is not#

• What is checked is what is reported. Each document is read from its element in the parsed input, never from a cut of the text. Its xml is that element written out: it reads back and verifies the same, but it is not the input byte for byte (a CDATA section becomes escaped text, a character reference the character, an empty element <X/>). To archive a received document, keep the bytes of the input itself, not xml.
• A document signed before it went into the envelope, with other namespaces in scope, is checked where it sits and, failing that, on its own, with the SII namespace and as written. The forms differ only in namespace declarations, never in content.
• A stamp is read only when its structure leaves no doubt: one plain TED (no prefix, no namespace declaration, no comment, CDATA or instruction) holding a DD and then an FRMT, and one CAF with one DA and one FRMA in the DD. Anything else is a failed check.
• Not checked: whose certificate signed, and whether the CAF had expired when the document was stamped.

How the signature is made#

Every XML signature in the SDK has the same shape, the one the SII validates:

• Type: enveloped XMLDSig. The Signature element goes inside the root, right after the signed element (</Documento><Signature>…</Signature></DTE>).
• Canonicalization: Canonical XML 1.0 (http://www.w3.org/TR/2001/REC-xml-c14n-20010315), without comments.
• Digest: SHA-1 of the canonical signed element (DigestValue, base64).
• Signature algorithm: RSA with SHA-1 (http://www.w3.org/2000/09/xmldsig#rsa-sha1) over the canonical SignedInfo.
• Transform: enveloped-signature.
• KeyInfo: the RSA key (Modulus, Exponent) and the certificate (X509Certificate), in base64 wrapped at 64 columns.

SHA-1 is what the SII requires; it is not a choice of the SDK. The canonicalizer is Canonical XML 1.0 restricted to what SII documents use (elements, attributes, text; no comments or processing instructions), so it is not a general XMLDSig implementation.

Low-level functions#

These are the pieces signDocument, signEnvelope and the books are built from. Use them to sign another element or to inspect a signature.

import { signEnveloped, verifyEnveloped } from 'dte-sdk'
 
const { xml, signature } = signEnveloped({
  xml: unsignedXml, // must contain …</Documento></DTE> and an ID on Documento
  elementTag: 'Documento',
  rootTag: 'DTE',
  certificate,
})
 
verifyEnveloped(xml, { elementTag: 'Documento', rootTag: 'DTE' }).valid // true

signEnveloped throws XML_PARSE_FAILED when the element, its ID attribute or the adjacent closing tags </elementTag></rootTag> are missing. signRootElement throws it when the root is not rootTag or has no closing tag. The certificate argument of both needs only privateKeyPem, publicKey and certificateBase64.

includeXsiInStoredSignedInfo controls whether the stored SignedInfo declares xmlns:xsi. The signed bytes always include it, because the canonical form inherits it from the root; the DTE stores it without (false) and envelopes and books with (true, the default). Leave it at its default unless you know the layout your verifier expects.

verifyEnveloped is what verifyDocumentSignature, verifyEnvelopeSignature, the books' verify*Signature and verifyReceivedDocuments call, each with its tags.

Crypto helpers#

Small functions over node-forge, exported for the places where you need one primitive:

The document and the XML are signed as UTF-8; the TED is signed as ISO-8859-1 (that is the 'latin1' encoding, which throws ENCODING_UNSUPPORTED_CHAR for a character above U+00FF).

Next steps#

• Envelopes: group signed documents and sign the SetDTE.
• Stamp: the step before signing.
• SII web services: the same certificate authenticates the seed and token.
• Acceptance and claims: answer the received documents you verified.
• API reference: every field of verifyReceivedDocuments and its checks.
• Security: handling the certificate and its password.