Firma

El SII valida cada documento y cada sobre con una firma XML envuelta (XMLDSig) hecha con el certificado digital de quien firma. loadCertificateFromPkcs12 y loadCertificateFromPem convierten tu certificado en un objeto Certificate de datos planos, signDocument firma con él un documento timbrado, y verifyDocumentSignature comprueba un <DTE> firmado. verifyReceivedDocuments revisa lo que envía un proveedor: la firma, el timbre y el CAF de cada documento. Debajo hay un puñado de funciones de bajo nivel que construyen y verifican la firma de cualquier elemento, y que reutilizan los sobres, los libros y el cliente del SII.

Todo lo de esta página vive en la entrada dte-sdk y corre en Node, Bun y Deno. Lee PKCS#12 y firma con node-forge, una de las cuatro dependencias de ejecución del SDK.

Uso#

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', el RUT del titular leído desde el certificado
certificate.notAfter // Date: cuándo vence
 
const caf = parseCaf(readFileSync('caf-33.xml', 'utf8'))
const stamped = stampDocument(createDocument(input), caf)
const signed = signDocument(stamped, certificate)
 
signed.xml // el <DTE> firmado, con su TED y su Signature, sin declaración XML
signed.signedAt // '2026-11-15T15:30:00', hora de Chile (TmstFirma)
signed.signature // { digestValue, signatureValue }
 
verifyDocumentSignature(signed.xml)
// { referenceId: 'DTE_T33F7', digestValid: true, signatureValid: true, valid: true }

Cargar un certificado#

Desde un archivo PKCS#12#

loadCertificateFromPkcs12(bytes, password, options?) lee un archivo .pfx o .p12. bytes es un Uint8Array (un Buffer de Node lo es).

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

Lee las dos generaciones del formato: archivos legacy (3DES y RC2) y modernos (PBES2 con AES), con bolsas de llave cifradas o planas. Encuentra el certificado hoja comparando su clave pública con la llave privada, ordena la cadena desde la hoja hasta la raíz (los endpoints TLS del SII necesitan los intermedios) y lee el RUT del titular desde el certificado.

Desde PEM#

loadCertificateFromPem({ privateKeyPem, certificatePem, chainPem? }, options?) construye el mismo objeto desde strings, por ejemplo después de convertir un .pfx con openssl pkcs12 -nodes:

Comprueba que la llave privada corresponda al certificado (CERT_INVALID cuando no) y que el certificado esté vigente ahora: que no haya pasado su notAfter (CERT_EXPIRED) ni sea anterior a su notBefore (CERT_NOT_YET_VALID). loadCertificateFromPkcs12 hace las mismas dos comprobaciones.

Opciones#

Ambos cargadores reciben LoadCertificateOptions:

El tipo Certificate#

El RUT se lee desde el certificado, en este orden: el otherName del SubjectAltName con OID 1.3.6.1.4.1.8321.1 (el que define la ley chilena de firma electrónica), luego el serialNumber del sujeto, luego la OU, y luego un token con forma de RUT en el CN. Cada candidato debe pasar rut.ts; uno inválido cae al siguiente. Ese es el RUT que usas como senderRut en la carátula de un sobre, porque el SII espera que quien envía sea el titular del certificado que firma. Mira Sobres.

Vencimiento#

import { daysUntilExpiry, isCertificateExpired } from 'dte-sdk'
 
daysUntilExpiry(certificate) // 412, días enteros; negativo una vez vencido
isCertificateExpired(certificate) // false
isCertificateExpired(certificate, { marginDays: 30 }) // true cuando vence dentro de 30 días

isCertificateExpired(certificate, { now?, marginDays? }) es true cuando now pasó notAfter menos marginDays (por defecto 0). daysUntilExpiry(certificate, { now? }) es floor((notAfter - now) / un día). Revisa el margen al arrancar, para que un certificado que vence la próxima semana se note antes de romper una corrida de emisión.

Errores#

import { isDteError } from 'dte-sdk'
 
try {
  loadCertificateFromPkcs12(bytes, process.env.PFX_PASSWORD!)
} catch (error) {
  if (isDteError(error) && error.code === 'CERT_PASSWORD_WRONG') {
    // pide la contraseña de nuevo, no reintentes en un ciclo
  }
}

Firmar un documento#

signDocument(stampedDocument, certificate, options?) renderiza el XML del documento con su TED, firma el elemento Documento (el elemento Liquidacion en una liquidación factura, 43) y devuelve un SignedDocument: el documento timbrado más:

La entrada debe ser un StampedDocument (mira Timbre); eso se comprueba al compilar, así no puedes firmar por error un documento sin TED. La firma es determinista: el mismo documento, certificado y horas dan los mismos bytes.

El documento firmado es lo que entra en un sobre (Sobres); un <DTE> firmado solo no se envía al SII.

Verificar una firma#

verifyDocumentSignature(xml) verifica la firma de un XML <DTE>, propio o recibido, y devuelve una SignatureVerification:

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

Un elemento alterado, una referencia ausente, un ID duplicado o un elemento movido a otro lugar del árbol da digestValid: false; no lanza, así que un elemento envuelto o duplicado nunca verifica. Lanza XML_PARSE_FAILED cuando el XML está mal formado, anidado a más de 100 niveles (el límite de todo DOM que parsea el SDK) o el raíz no es DTE, y SIGNATURE_NOT_FOUND cuando no hay Signature bajo el raíz o no hay SignedInfo dentro de ella.

Solo verifica una firma de la forma que hace el SDK: una Reference con el único DigestValue, SHA-1, sin transformadas salvo enveloped-signature o C14N 1.0, y C14N 1.0 con RSA-SHA1 en SignedInfo. Una segunda Reference, otro digest u otra transformada da digestValid: false; otra canonicalización (C14N exclusiva, por ejemplo) u otro método de firma da signatureValid: false. Antes de la 0.4.0 el verificador revisaba solo la primera Reference y no leía los algoritmos. Las firmas que hace el SDK pasan igual que antes.

valid prueba que el elemento y SignedInfo están íntegros respecto del certificado que viaja en el mismo XML. No prueba que ese certificado pertenezca al firmante que esperas, ni que sea válido ante una entidad certificadora: eso es otro chequeo, y el SII hace el suyo. Verifica el timbre por separado con verifyTed (Timbre), o revisa un documento recibido completo con verifyReceivedDocuments (más abajo).

La función necesita el XML cuyo raíz es <DTE>: para un documento dentro de un sobre, usa el xml de cada documento firmado, tal como está en envelope.documents.

Verificar documentos recibidos#

verifyReceivedDocuments(xml, options?) revisa lo que te envió un proveedor, tal como llegó: un DTE, un EnvioDTE o un EnvioBOLETA. Revisa la firma del propio sobre y, por cada documento, su firma, su timbre y el CAF que trae el timbre, y devuelve cada chequeo como datos.

import { readFileSync } from 'node:fs'
import { decodeLatin1, isClaimDocumentType, verifyReceivedDocuments } from 'dte-sdk'
 
// Decodifica los bytes con la codificación que nombra la declaración XML: ISO-8859-1 en los documentos del SII.
// Producción por defecto: un documento timbrado con un CAF de certificación vuelve como inválido.
const { envelope, documents, status } = verifyReceivedDocuments(decodeLatin1(readFileSync('EnvioDTE.xml')))
 
status // 'valid' | 'invalid' | 'unchecked': el peor entre el sobre y sus documentos
envelope?.valid // la firma del propio sobre; envelope es null para un DTE solo
documents[0] // { type: 33, folio: 1234, issuerRut: '10000004-0', totalAmount: 119000, signature, ted, caf, status, xml, … }
 
// Los documentos que puedes aceptar o reclamar en el registro del SII
const toAnswer = documents.filter((doc) => doc.status === 'valid' && isClaimDocumentType(doc.type))

Cada documento se revisa de tres formas:

El status de un documento es invalid si falla un chequeo, unchecked si ninguno falla pero el IDK del CAF no tiene una llave conocida, y valid en otro caso; el status del resultado completo es el peor entre el sobre y los documentos. Un documento que falla un chequeo es un resultado, no un error. La función lanza solo con una entrada que no puede leer: XML_PARSE_FAILED para XML mal formado, un DOCTYPE, otro raíz, un sobre sin exactamente un SetDTE, un DTE o Documento con prefijo, un DTE sin su Documento, o elementos anidados a más de 100 niveles, y ENVELOPE_EMPTY para un sobre sin documentos. Antes de la 0.7.0 un archivo de unos miles de elementos anidados desbordaba la pila con un RangeError; ningún documento que escriben el SII o un emisor se acerca a 100.

Las llaves del SII y el ambiente#

SII_CAF_KEYS tiene las llaves 100 (certificación) y 300 (producción) con que el SII firma cada CAF, tomadas de los certificados del SII tal como los publican CryptoSys y LibreDTE, los mismos bytes en ambos. Solo se acepta la llave de environment, production por defecto: un CAF firmado con la otra es invalid, con la diferencia environment, y caf.environment dice cuál es, así que un documento de certificación nunca pasa por uno de producción. Pasa environment: 'certification' para revisar documentos del ambiente de certificación. siiKeys reemplaza las llaves; expande SII_CAF_KEYS en él para agregar una. cafEnvironment(keyId) dice para qué ambiente es un IDK: certification para 100, production para 300, null para otro.

verifyCafSignature(cafXml, { environment }) revisa la FRMA de un solo CAF con la misma regla y devuelve 'valid', 'invalid' o 'unchecked'. Para revisar el CAF que llevarán tus propios TED, pásale el bloque que guarda parseCaf:

import { readFileSync } from 'node:fs'
import { parseCaf, verifyCafSignature } from 'dte-sdk'
 
const caf = parseCaf(readFileSync('caf-33.xml', 'latin1')) // los archivos CAF son ISO-8859-1
verifyCafSignature(caf.xml, { environment: 'certification' }) // 'valid' para un CAF que el SII emitió en certificación

Lanza CAF_INVALID cuando el texto no es XML, trae un DOCTYPE o no tiene un solo CAF con un DA y una FRMA. Una FRMA que está pero vacía es una firma que falla, no un CAF que no lo es: es invalid, sea cual sea el IDK del CAF, como una FRMA que no es base64. Antes de la 0.7.0 lanzaba CAF_INVALID, y en verifyReceivedDocuments un CAF así no era CAF, así que el timbre, sin su llave, también fallaba. Ahora el CAF se encuentra y falla su firma del SII, y el timbre se chequea con la llave del CAF como cualquier otro.

Qué se revisa y qué no#

• Lo que se revisa es lo que se informa. Cada documento se lee desde su elemento en la entrada parseada, nunca de un trozo del texto. Su xml es ese elemento escrito: se lee y verifica igual, pero no es la entrada byte a byte (una sección CDATA pasa a texto escapado, una referencia de carácter al carácter, un elemento vacío a <X/>). Para archivar un documento recibido, guarda los bytes de la propia entrada, no xml.
• Un documento firmado antes de entrar al sobre, con otros namespaces en alcance, se revisa donde está y, si eso falla, solo, con el namespace del SII y tal como viene. Las formas difieren solo en las declaraciones de namespace, nunca en el contenido.
• Un timbre se lee solo cuando su estructura no deja dudas: un TED simple (sin prefijo, sin declaración de namespace, sin comentarios, CDATA ni instrucciones) con un DD y luego una FRMT, y un CAF con un DA y una FRMA en el DD. Cualquier otra cosa es un chequeo fallido.
• No se revisa: de quién es el certificado que firmó, ni si el CAF estaba vencido cuando se timbró el documento.

Cómo se hace la firma#

Toda firma XML del SDK tiene la misma forma, la que valida el SII:

• Tipo: XMLDSig envuelta. El elemento Signature va dentro del raíz, justo después del elemento firmado (</Documento><Signature>…</Signature></DTE>).
• Canonicalización: Canonical XML 1.0 (http://www.w3.org/TR/2001/REC-xml-c14n-20010315), sin comentarios.
• Digest: SHA-1 del elemento firmado canónico (DigestValue, base64).
• Algoritmo de firma: RSA con SHA-1 (http://www.w3.org/2000/09/xmldsig#rsa-sha1) sobre el SignedInfo canónico.
• Transformación: enveloped-signature.
• KeyInfo: la clave RSA (Modulus, Exponent) y el certificado (X509Certificate), en base64 cortado a 64 columnas.

SHA-1 es lo que exige el SII; no es una elección del SDK. El canonicalizador es Canonical XML 1.0 acotado a lo que usan los documentos del SII (elementos, atributos, texto; sin comentarios ni instrucciones de procesamiento), así que no es una implementación general de XMLDSig.

Funciones de bajo nivel#

Son las piezas con que se construyen signDocument, signEnvelope y los libros. Úsalas para firmar otro elemento o para inspeccionar una firma.

import { signEnveloped, verifyEnveloped } from 'dte-sdk'
 
const { xml, signature } = signEnveloped({
  xml: unsignedXml, // debe contener …</Documento></DTE> y un ID en Documento
  elementTag: 'Documento',
  rootTag: 'DTE',
  certificate,
})
 
verifyEnveloped(xml, { elementTag: 'Documento', rootTag: 'DTE' }).valid // true

signEnveloped lanza XML_PARSE_FAILED cuando faltan el elemento, su atributo ID o las etiquetas de cierre adyacentes </elementTag></rootTag>. signRootElement lo lanza cuando el raíz no es rootTag o no tiene etiqueta de cierre. El argumento certificate de ambas solo necesita privateKeyPem, publicKey y certificateBase64.

includeXsiInStoredSignedInfo controla si el SignedInfo guardado declara xmlns:xsi. Los bytes firmados siempre lo incluyen, porque la forma canónica lo hereda del raíz; el DTE lo guarda sin él (false) y los sobres y libros con él (true, el valor por defecto). Déjalo en su valor por defecto salvo que conozcas el formato que espera tu verificador.

verifyEnveloped es lo que llaman verifyDocumentSignature, verifyEnvelopeSignature, los verify*Signature de los libros y verifyReceivedDocuments, cada una con sus etiquetas.

Helpers criptográficos#

Funciones pequeñas sobre node-forge, exportadas para los lugares donde necesitas una sola primitiva:

El documento y el XML se firman como UTF-8; el TED se firma como ISO-8859-1 (es la codificación 'latin1', que lanza ENCODING_UNSUPPORTED_CHAR para un carácter sobre U+00FF).

Siguientes pasos#

• Sobres: agrupa documentos firmados y firma el SetDTE.
• Timbre: el paso previo a firmar.
• Servicios web del SII: el mismo certificado autentica la semilla y el token.
• Aceptación y reclamos: responde los documentos recibidos que verificaste.
• Referencia de la API: cada campo de verifyReceivedDocuments y sus chequeos.
• Seguridad: cómo manejar el certificado y su contraseña.