Plugin de Firma

Firma documentos PDF y Word con una firma visible y un sello digital

El plugin Signer coloca una firma visible en un documento y, por defecto, lo sella con una firma digital que un lector de PDF puede verificar. Firma archivos PDF y Word (.docx). La firma visible es siempre una imagen PNG: dibujada, escrita o cargada por el firmante.

SuperficieCuándo usarlo
DocumentSigner (C#)Firma en el servidor, sin que intervenga el navegador
Drop-in widget (doconutSigner.js)Quieres una pantalla lista para cargar, firmar y descargar en tu página
HTTP endpoints on DocImage.axd (?sign=open|run|download)Construyes tu propia UI de firma contra un contrato de servidor documentado

Cada firma se coloca una sola vez, en una página. El nombre del firmante, el motivo y la ubicación pueden acompañarla.

Instalar el paquete

powershell
Install-Package Doconut.NETFramework.Signer

Para fijar el plugin a la versión que describe esta documentación:

powershell
Install-Package Doconut.NETFramework.Signer -Version 26.10.0

Mantén el paquete Signer en la misma versión que Doconut.NETFramework.

El archivo de licencia del plugin, Doconut.Viewer.Signer.lic, se coloca en la misma carpeta que Doconut.Viewer.lic; se lee junto con la licencia del visor.

Registrar el plugin

Al igual que cualquier plugin Doconut, Signer se registra con AddPlugin<TPlugin>() en DoconutHost.Initialize, llamado desde Application_Start:

csharp
Doconut.DoconutHost.Initialize(options =>
{
    options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
    options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
});

Agrega Doconut.DoconutHost.Shutdown() a Application_End para que el trabajo en segundo plano se detenga limpiamente cuando el pool de aplicaciones se recicle.

Eso es todo lo que necesita la fachada C#. El widget y sus endpoints HTTP son una opción separada, AddSignerWidget() (ver Widget integrado).

El plugin necesita una licencia que otorgue la capacidad Signer. Sin ella, DoconutHost.Initialize lanza una excepción desde Application_Start:

text
The Signer plugin is registered via AddPlugin but no active license grants Signer. Remove the AddPlugin<...>() call or install a license (or trial/demo) that includes Signer.

En System.Web eso significa que cada solicitud responde con un 500 vacío, y la razón solo aparece en el registro de eventos de Windows (fuente ASP.NET). Lanza una excepción por falta de licencia, un archivo heredado TRIAL, una licencia sin Signer, y una licencia paga usada fuera de su ventana de versión. Se aceptan licencias temporales Demo/NFR. Ver Configuración de Licencia.

Licenciamiento y marca de agua

Estado de la licenciaInicioFirma certificadaFirma visual
Licencia paga que otorga Signer, certificado configuradoIniciaSellado con tu certificado, limpio (watermarked: false)Limpio
Licencia paga que otorga Signer, sin certificadoIniciaRechazado: No signing certificate configured.Limpio
Licencia paga, certificado expirado o aún no válidoIniciaRechazado: The signing certificate expired on yyyy-MM-dd.Limpio
Licencia temporal Demo/NFR, activa o expiradaIniciaSellado con el certificado de demostración incorporado, con marca de agua (watermarked: true)Con marca de agua
Sin licencia, un archivo heredado TRIAL, una licencia sin Signer, o una licencia paga fuera de su ventana de versiónApplication_Start lanza; cada solicitud responde con un 500 vacío——

La regla es la misma para la fachada C# y el widget: la salida lleva marca de agua cuando la licencia no es una licencia de visor paga o es temporal. Bajo una licencia temporal el plugin siempre firma con su certificado de demostración incorporado, y cualquier certificado que configures no se utiliza.

El certificado de demostración produce un sello genuino, pero los lectores de PDF no lo confían. Se puede crear e probar una integración de extremo a extremo con una licencia de evaluación; para obtener una salida limpia y confiable necesitas tanto una licencia paga como tu propio certificado de firma.

Uso desde C#

DocumentSigner está registrado por DoconutHost.Initialize; resuélvelo desde DoconutHost.Services. Su constructor es interno, así que nunca lo new. Resolverlo sin AddPlugin<SignerPlugin>() lanza No IDocumentSigner is registered. Add the signing plugin: options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>().

csharp
using Doconut;
using Doconut.Core.Models.Signing;

public sealed class ContractSigning
{
    private readonly DocumentSigner _signer;

    public ContractSigning(DocumentSigner signer) => _signer = signer;

    public async Task<byte[]> SignAsync(Stream pdf, byte[] signaturePng, SigningCertificate certificate, CancellationToken ct)
    {
        var request = new SignRequest(
            new VisibleSignature(SignatureKind.Drawn, signaturePng),
            new SignaturePlacement(Page: 1, X: 0.58, Y: 0.80, W: 0.32, H: 0.12),
            SignerName: "Ada Lovelace",
            Reason: "I approve this document",
            Location: "London, UK");
        // Mode predeterminado a Certified (firma visible + sello digital); WordOutput predeterminado a Pdf.

        SignResult result = await _signer.SignAsync(pdf, ".pdf", request, certificate, ct);
        using (result.Stream)
        using (var output = new MemoryStream())
        {
            await result.Stream.CopyToAsync(output, 81920, ct);
            return output.ToArray();
        }
    }
}

SignAsync toma el flujo de origen, su extensión (".pdf" o ".docx"), la solicitud y el certificado para esta llamada. La fachada no lee SignerWidgetOptions.SigningCertificate; esa configuración es para el widget. Pase null bajo una licencia de demostración, o en modo Visual.

SignResult contiene el documento firmado como un flujo buscable, más su Extension (".pdf" o ".docx") para que puedas nombrar el archivo. Tú posees el flujo: dispón de él cuando hayas terminado.

En un controlador MVC 5

Haz que la acción sea asíncrona y await la firma. Esta estampa una firma Visual, que no necesita certificado:

csharp
[HttpPost]
public async Task<ActionResult> Sign(HttpPostedFileBase file)
{
    var signer = Doconut.DoconutHost.Services.GetRequiredService<DocumentSigner>();
    byte[] signaturePng = System.IO.File.ReadAllBytes(Server.MapPath("~/App_Data/signature.png"));

    var request = new SignRequest(
        new VisibleSignature(SignatureKind.Image, signaturePng),
        new SignaturePlacement(Page: 1, X: 0.58, Y: 0.80, W: 0.32, H: 0.12),
        Mode: SignatureMode.Visual);

    SignResult result = await signer.SignAsync(
        file.InputStream, Path.GetExtension(file.FileName), request, ct: Response.ClientDisconnectedToken);
    string contentType = result.Extension == ".pdf"
        ? "application/pdf"
        : "application/vnd.openxmlformats-officedocument.wordprocessingml.document";
    return File(result.Stream, contentType, Path.GetFileNameWithoutExtension(file.FileName) + "-signed" + result.Extension);
}

Una fuente Word se firma a PDF a menos que solicites salida Word. Nombra el resultado desde result.Extension:

csharp
var signer = Doconut.DoconutHost.Services.GetRequiredService<DocumentSigner>();
byte[] signaturePng = File.ReadAllBytes(HostingEnvironment.MapPath("~/App_Data/signature.png"));

var request = new SignRequest(
    new VisibleSignature(SignatureKind.Drawn, signaturePng),
    new SignaturePlacement(Page: 1, X: 0.58, Y: 0.80, W: 0.32, H: 0.12),
    WordOutput: WordOutput.Docx);

SignResult result = await signer.SignAsync(stream, ".docx", request, ct: ct);
string downloadName = "contract-signed" + result.Extension;   // ".docx"

SignAsync lanza una excepción en lugar de devolver cuando la llamada no puede tener éxito:

ExcepciónMensajeCuándo
InvalidOperationExceptionNo signing certificate configured.Modo certificado, una licencia de pago, y no se pasó ningún certificado
InvalidOperationExceptionThe signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd.Modo certificado con un certificado fuera de su ventana de validez
ArgumentExceptionThe sign request is invalid: the visible signature needs PNG bytes and the placement must be a normalized rectangle on a 1-based page.Bytes PNG vacíos, o una ubicación que no es válida
NotSupportedExceptionThe signer supports PDF and Word (.docx) documents; got '{extension}'.Cualquier otro tipo de origen

Modos de firma, salida de Word y certificados

Modos de firma

SignRequest.Mode elige si la firma está sellada.

ModoQué produceCertificadoVerificable
SignatureMode.Certified (predeterminado)La firma visible más un sello digitalRequerido bajo una licencia de pagoSí
SignatureMode.VisualSólo la firma visibleNunca necesarioNo: es una imagen

Use Certified cuando la firma debe ser comprobable: aprobaciones, contratos, cualquier cosa que un verificador necesite revisar para la identidad e integridad. Use Visual cuando sólo necesitas la apariencia de una firma, o no tienes certificado. Una licencia temporal marca ambas con una marca de agua.

Los sellos PDF son firmas PKCS#7 desacopladas (adbe.pkcs7.detached) con SHA-256, para claves RSA o ECDSA. Transportan los certificados del emisor encontrados en tu PFX, de modo que un lector que confíe en tu raíz pueda construir la cadena. Los sellos nativos de Word son firmas de paquetes OOXML y transportan sólo el certificado del firmante.

Documentos Word

Para una fuente .docx, SignRequest.WordOutput elige la salida. Se ignora para fuentes PDF, que siempre generan un PDF.

SalidaQué ocurreCompatibilidad del verificador
WordOutput.Pdf (predeterminado)El documento se convierte a PDF, luego se firma y sellaAmplia: un PDF firmado se verifica en cualquier lugar
WordOutput.DocxEl documento permanece en Word: la imagen de la firma se coloca en él, más una firma de paquete OOXMLLimitada: no todos los visores muestran firmas de paquetes OOXML

Mantén PDF a menos que el destinatario necesite un archivo Word editable y acepte la compatibilidad limitada del verificador.

Configuración del certificado

Para sellar con tu propia identidad, proporciona al plugin un archivo PFX (PKCS#12) que incluya la clave privada. Para el widget, establece SignerWidgetOptions.SigningCertificate; para la fachada C#, pasa el certificado a SignAsync. Proporciona ya sea los bytes o una ruta, más la contraseña. App_Data es un buen lugar para el archivo, porque IIS nunca lo sirve:

csharp
Doconut.DoconutHost.Initialize(options =>
{
    options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
    options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
    options.AddSignerWidget(widget =>
    {
        widget.SigningCertificate = new SigningCertificate
        {
            PfxBytes = File.ReadAllBytes(HostingEnvironment.MapPath("~/App_Data/signing.pfx")),
            Password = System.Configuration.ConfigurationManager.AppSettings["DoconutSigner:Password"] ?? "",
        };
    });
});
csharp
Doconut.DoconutHost.Initialize(options =>
{
    options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
    options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
    options.AddSignerWidget(widget =>
    {
        widget.SigningCertificate = new SigningCertificate
        {
            PfxPath = HostingEnvironment.MapPath("~/App_Data/signing.pfx"),
            Password = System.Configuration.ConfigurationManager.AppSettings["DoconutSigner:Password"] ?? "",
        };
    });
});

Las propiedades de SigningCertificate son solo de inicialización, lo que C# 7.3 (el predeterminado para proyectos .NET Framework) no puede establecer. Establece <LangVersion> a 9.0 o posterior en el archivo del proyecto.

El certificado se mantiene solo en memoria. Nunca se registra, se devuelve a un cliente, ni se persiste, y la contraseña nunca aparece en un mensaje de error.

Requisitos:

  • Un paquete PFX / PKCS#12 con su clave privada. Un archivo solo de clave pública (.cer, .crt) no puede firmar. Exporta la cadena del emisor con él, para que los sellos PDF la transporten.
  • La contraseña correcta.
  • Dentro de su ventana de validez. Un certificado expirado o aún no válido no detiene la aplicación, pero las firmas Certified son rechazadas hasta que se reemplace. Las firmas Visual no se ven afectadas.
  • Emitido para firma de documentos: un uso de clave con firma digital o no repudio, y un uso extendido de clave, si está presente, que permita la firma de documentos, protección de correo electrónico o autenticación de cliente. Un certificado emitido para otra cosa, como un certificado de servidor TLS, aún firma, pero los lectores PDF marcan la firma.
  • Los tokens de hardware, tarjetas inteligentes, HSM y el almacén de certificados de Windows no son compatibles. Exporta el certificado, con su clave privada y cadena, a un PFX.

Crear un PFX a partir de un certificado y su clave privada con OpenSSL:

bash
openssl pkcs12 -export -out signing.pfx -inkey private.key -in certificate.crt
# La contraseña de exportación que se le solicita es SigningCertificate.Password.

Exporta uno desde el almacén de certificados de Windows: abre certmgr.msc y busca el certificado (su ícono muestra una llave cuando la clave privada está presente). Haz clic derecho, elige All Tasks → Export…, selecciona Yes, export the private key, elige Personal Information Exchange – PKCS #12 (.PFX), y establece una contraseña.

Comprobaciones de inicio

Cuando el widget está habilitado, el certificado en SignerWidgetOptions.SigningCertificate se verifica una vez, dentro de DoconutHost.Initialize, de modo que un PFX mal configurado falla al iniciar en lugar de en la primera firma. Tres problemas lanzan un InvalidOperationException desde Application_Start, y cada solicitud responde con un 500 vacío; el mensaje está en el registro de eventos de Windows:

MensajeSolución
Doconut Signer: the certificate file was not found at '{path}'.Corrija PfxPath; asegúrese de que el archivo esté desplegado y sea legible por la cuenta del grupo de aplicaciones
Doconut Signer: the signing certificate could not be opened — the password is incorrect or the file is not a valid .pfx.Verifique la contraseña; asegúrese de que el archivo sea un .pfx real, no un .cer o .pem
Doconut Signer: the signing certificate has no private key. Re-export the .pfx INCLUDING the private key.Exporte nuevamente el PFX con la clave privada

En ASP.NET Core el host también registra una línea al iniciar nombrando el certificado, o advertiendo que está expirado o no emitido para firmar. DoconutHost no escribe esa línea, así que en .NET Framework verifique un certificado nuevo firmando un documento de prueba en modo Certificado.

La fachada C# no se verifica al iniciar. El certificado que pasa a SignAsync se lee cuando firma, por lo que una ruta o contraseña incorrecta falla esa llamada.

Widget de inserción

Habilitar los puntos finales

Los puntos finales ?sign=open|run|download del widget son servidos por DocImage.axd y están desactivados por defecto. Habilítelos junto al registro del plugin:

csharp
Doconut.DoconutHost.Initialize(options =>
{
    options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
    options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
    options.AddSignerWidget(widget =>
    {
        widget.MaxUploadMb = 25;           // el predeterminado
        widget.MaxSignatureImageKb = 512;  // el predeterminado
        // widget.SigningCertificate: ver configuración del certificado; déjalo nulo para la firma de demostración (con marca de agua)
    });
});
// System.Web lee toda la carga antes de que Doconut la vea: mantén maxRequestLength (KB) y
// maxAllowedContentLength (bytes) en Web.config por encima del MaxUploadMb del widget.

AddSignerWidget() sin argumentos habilita el widget con los valores predeterminados. No otorga firma por sí mismo: necesita AddPlugin<SignerPlugin>(), o DoconutHost.Initialize lanza:

text
AddSignerWidget() was called but the Signer plugin is not registered. Add options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>() (the widget needs it), or remove the AddSignerWidget() call.

Los puntos finales y el script son servidos por el manejador y el módulo registrado en Web.config:

xml
<system.webServer>
  <handlers>
    <add name="DocImage" verb="GET,HEAD,POST" path="DocImage.axd" type="Doconut.DocImageHandler, Doconut" />
  </handlers>
  <modules>
    <add name="DoconutResources" type="Doconut.DoconutResourceModule, Doconut" />
  </modules>
</system.webServer>

El módulo sirve el script ya sea que el widget esté habilitado o no. Sin AddSignerWidget(), el widget se carga y dibuja su zona de arrastre, y su primera solicitud responde 404: el widget entonces informa Signing is not enabled on this server.

Límites de carga

ASP.NET lee todo el cuerpo de la solicitud antes de que se ejecute DocImage.axd. Una carga superior a MaxUploadMb pero por debajo de los límites del host obtiene el JSON propio del widget 413 (File is too large.). Una carga superior a los límites del host es rechazada primero por IIS, con una página de error que el widget no puede leer. Mantenga ambos límites del host por encima del límite del widget:

xml
<system.web>
  <httpRuntime maxRequestLength="30720" />           <!-- KILOBYTES: 30 MB -->
</system.web>
<system.webServer>
  <security>
    <requestFiltering>
      <requestLimits maxAllowedContentLength="31457280" />  <!-- BYTES: 30 MB -->
    </requestFiltering>
  </security>
</system.webServer>

Una carga enviada sin un Content-Length (chunked) que supera los límites del host también recibe la página de error de IIS; no hay solución alternativa para ese caso.

Incrústalo

El script se sirve en /doconut-res/js/doconutSigner.js. Es un archivo único y autocontenido sin dependencias. Apunte basePath al manejador:

html
<div id="host"></div>
<script src="/doconut-res/js/doconutSigner.js"></script>
<script>
  const handle = Doconut.signer('#host', { basePath: '/DocImage.axd' });
</script>

Doconut.signer(selectorOrElement, options) toma un selector CSS o un elemento, lanza una excepción si el montaje no se encuentra, y devuelve un manejador. El basePath predeterminado del widget, /doconut, es el endpoint de ASP.NET Core; en este paquete debe ser '/DocImage.axd'.

El firmante sube un archivo PDF o .docx, crea una firma (Draw en un lienzo, Type un nombre con una fuente de firma, o Image desde un PNG, JPG o GIF), lo arrastra y redimensiona sobre la página, y firma y descarga el resultado. El widget siempre envía la firma como PNG; una imagen subida se convierte en el navegador a PNG que cabe en 520×160.

Opciones

OpciónTipoPredeterminadoNotas
basePathstring'/doconut'Dónde se sirven los endpoints ?sign= y las imágenes de vista previa. Establezca '/DocImage.axd' en este paquete
resPathstring'/doconut-res'Reservado; el widget incluye su propio CSS
maxUploadMbnumber25Solo verificación del lado del cliente, por lo que un archivo demasiado grande falla rápidamente. El límite del servidor es MaxUploadMb en AddSignerWidget
maxSignatureKbnumber512Límite del lado del cliente para el modo Imagen. Manténgalo igual al MaxSignatureImageKb del servidor
previewWidthnumber560Ancho en píxeles de la vista previa de la página
licenseUrlstring | nullnullConvierte el aviso de marca de agua de demostración en un enlace a esta URL
signatureModestring'certified'Tipo de firma inicial: 'certified' o 'visual'. Cualquier otro valor se convierte en 'certified'
showSignatureModeTogglebooleantrueMuestra la opción Digital signature / Visual only. Con false, el widget firma con signatureMode
wordOutputstring'pdf'Salida inicial para fuentes .docx: 'pdf' o 'docx'. Cualquier otro valor se convierte en 'pdf'
showOutputFormatTogglebooleantrueMuestra la opción PDF / Word, solo para fuentes .docx. Con false, el widget usa wordOutput
labelsobject{}Sobrescribe cualquier subconjunto de las cadenas en inglés

Ocultar un interruptor no desactiva la función; fija el valor. Dos configuraciones comunes:

javascript
// Ambos interruptores mostrados, firma digital por defecto: un firmante de autoservicio completo.
Doconut.signer('#host', { basePath: '/DocImage.axd', licenseUrl: '/pricing' });
javascript
// Solo visual, sin interruptor: un sello simple sin firma digital ofrecida.
Doconut.signer('#host', {
  basePath: '/DocImage.axd',
  signatureMode: 'visual',
  showSignatureModeToggle: false
});

Retrollamadas

RetrollamadaSe dispara cuandoCarga
onReadyUna vez, al montar (no de nuevo en reset())—
onSourceLoadedEl archivo se abre y se muestra su vista previa{ file: { token, name, pages, ext } }
onSignedLa firma tiene éxito{ downloadToken, downloadName, watermarked }
onDownloadEn cada clic de Descargar{ downloadName, downloadToken }
onErrorFalla una etapa de abrir, firmar o descargar, o un archivo en modo Imagen es demasiado grande{ message }

Una retrollamada que lanza una excepción se captura y registra; nunca interrumpe el flujo del widget.

Manejo imperativo

MétodoComportamiento
reset()Regresa a la pantalla de arrastre y limpia el flujo actual. No dispara onReady de nuevo. No hace nada después de destroy()
loadFile(file)Inicia el flujo con un File. No hace nada a menos que el widget esté en su pantalla de arrastre; llame a reset() primero si es necesario
destroy()Elimina los escuchadores, vacía el montaje y congela la instancia
javascript
const signerWidget = Doconut.signer('#host', {
  basePath: '/DocImage.axd',
  onSigned: (result) => console.log('signed', result.downloadName, result.watermarked),
  onError: (error) => console.warn(error.message)
});
document.getElementById('start-over').addEventListener('click', () => signerWidget.reset());

Etiquetas

Cada cadena tiene un valor predeterminado en inglés; labels sobrescribe cualquier subconjunto y el resto permanece en inglés. Los fragmentos que cambian en tiempo de ejecución usan {placeholders}, como uploading: 'Uploading {name}…' y pages: '{n} pages'.

ClaveValor predeterminado en inglés
dropPromptDrag & drop a PDF or Word file here
dropHintPDF or Word (.docx)
chooseFileChoose file
signatureHeadingYour signature
modeDraw / modeType / modeImageDraw / Type / Image
metaSummarySignature details (optional)
metaSignerName / metaReason / metaLocationSigner name / Reason / Location
signatureTypeSignature type
modeCertified / modeVisualDigital signature / Visual only
modeVisualNoteNo certificate — a visible mark only, not cryptographically verifiable.
outputFormatOutput format
outputPdf / outputWordPDF / Word (.docx)
signActionSign document
downloadDownload
demoNoticeDemo — signed with the Doconut demo certificate; output is watermarked.
signingNotEnabledSigning is not enabled on this server.
page / pages1 page / {n} pages

Otras claves cubren el paso de colocación, la pantalla de error, el formulario enlazado del aviso de demostración (demoNoticePrefix, demoNoticeLink, demoNoticeSuffix) y los anuncios de aria-live.

Cuando open o run responden 404 sin error JSON, el widget muestra signingNotEnabled. Un error JSON del servidor siempre prevalece, por lo que mensajes como una carga vencida permanecen visibles.

Tematización

El widget agrega la clase dsw a su elemento de montaje y lee sus colores, radio y fuentes de las propiedades personalizadas de CSS, de modo que puedes tematizarlo sin tocar sus internos:

css
#host.dsw {
  --dsw-accent: #b0522b;       /* enlaces, foco, modo activo */
  --dsw-bg: #fffaf3;
  --dsw-fg: #3b2a1a;
  --dsw-muted: #8a7a68;
  --dsw-border: #e0cbb0;
  --dsw-radius: 14px;
  --dsw-font: Georgia, "Times New Roman", serif;
  --dsw-signature-font: "Segoe Script", "Brush Script MT", cursive;   /* el modo Type */
}

Valores predeterminados: --dsw-accent: #2b6cb0, --dsw-bg: #ffffff, --dsw-fg: #1a202c, --dsw-muted: #718096, --dsw-border: #cbd5e0, --dsw-radius: 8px, una fuente de interfaz del sistema, y una fuente cursiva para la firma.

Construye tu propio frontend

El widget es un cliente para este contrato HTTP en DocImage.axd. Las rutas responden 404 hasta que se llama a AddSignerWidget(). Los errores incluyen un cuerpo JSON, { "error": "..." }, excepto donde la tabla indica "solo estado". Un valor desconocido de ?sign= responde 400.

RutaPropósitoRespuesta exitosa
POST /DocImage.axd?sign=open (multipart, un archivo)Carga un PDF o .docx y ábrelo para vista previa200 — { token, name, pages, ext }
POST /DocImage.axd?sign=run (cuerpo JSON)Firma el archivo cargado200 — { downloadToken, downloadName, watermarked }
GET /DocImage.axd?sign=download&token=<downloadToken>Transmite el archivo firmado200 — el archivo, Content-Disposition: attachment, Cache-Control: no-store

ext en la respuesta open incluye el punto inicial (".docx"). La vista previa de la página usa la ruta estándar de la imagen del visor, /DocImage.axd?token={token}&page={n}&thumb=1&width={px}; la página mostrada se convierte en placement.page.

El cuerpo run:

json
{
  "token": "GUID-from-open",
  "signature": { "kind": "Drawn", "payload": "<base64 PNG, no data: prefix>" },
  "placement": { "page": 1, "x": 0.58, "y": 0.80, "w": 0.32, "h": 0.12 },
  "meta": { "signerName": "Ada Lovelace", "reason": "I approve", "location": "London, UK" },
  "wordOutput": "pdf",
  "mode": "certified"
}
CampoNotas
tokenEl token de open
signature.kindDrawn, Typed o Image, sin distinción de mayúsculas; cualquier otro se convierte en Drawn. Solo una pista: la carga útil es siempre un PNG
signature.payloadUn PNG base64 sin formato, sin prefijo data:. Debe ser un PNG real y no mayor que MaxSignatureImageKb una vez decodificado
placement.pagebasado en 1
placement.x / y / w / hNormalizado 0..1 desde la esquina superior izquierda, con x + w ≤ 1 y y + h ≤ 1
meta.signerName / reason / locationOpcional. Cada uno se recorta, un valor en blanco se descarta, y cada uno se corta a 256 caracteres
wordOutputpdf (predeterminado) o docx; ignorado para fuentes PDF. Cualquier otro se convierte en pdf
modecertified (predeterminado) o visual. Cualquier otro se convierte en certified

downloadName sigue la salida: <source>-signed.pdf o <source>-signed.docx, y download envía el Content-Type correspondiente.

El origen cargado y el resultado firmado se conservan cada uno durante 30 minutos. Después de eso, run y download responden 404 y el archivo debe abrirse nuevamente. Todos los tokens son GUIDs.

RutaEstadoCuándoCuerpo
cualquiera404El widget no está habilitadosolo estado
cualquiera405Verbo incorrecto (open y run necesitan POST, download necesita GET)solo estado
open400No es una carga multipartExpected a multipart file upload.
open400Sin archivo, o uno vacíoNo file uploaded.
open400Cualquier cosa distinta de .pdf o .docxSigning supports PDF and Word (.docx) files only.
open413La carga supera MaxUploadMb (pero no los límites de IIS)File is too large.
run400El cuerpo no es JSON válido, o está vacíoMalformed request. / Empty request.
run400Falta el token o no es un GUIDInvalid token.
run404La carga expiró o nunca se abrióUpload expired — please re-open the file.
run400Sin firma, o sin colocaciónNo signature supplied. / No placement supplied.
run400La carga útil no es base64, está vacía, es demasiado grande, o no es un PNGSignature image is not valid base64. / Signature image is empty. / Signature image is too large. / The signature image must be a PNG.
run400La colocación está fuera de la páginaThe signature or its placement is invalid.
run400Modo certificado, una licencia paga y sin certificadoNo signing certificate configured.
run400Modo certificado con un certificado fuera de su ventana de validezThe signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd.
open, run500Procesamiento fallóUn mensaje sanitizado
download400Falta el token o no es un GUIDsolo estado
download404Token desconocido o expiradosolo estado

Un recorrido completo con fetch:

javascript
// file: el File a firmar; pngBase64: la firma como un PNG base64 sin prefijo data:,
// por ejemplo canvas.toDataURL('image/png').split(',')[1].
async function signFile(file, pngBase64) {
  const base = '/DocImage.axd';

  // 1. abrir: subir el archivo
  const form = new FormData();
  form.append('file', file, file.name);
  const opened = await (await fetch(base + '?sign=open', { method: 'POST', body: form })).json();

  // 2. ejecutar: firmarlo
  const signed = await (await fetch(base + '?sign=run', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      token: opened.token,
      signature: { kind: 'Drawn', payload: pngBase64 },
      placement: { page: 1, x: 0.58, y: 0.80, w: 0.32, h: 0.12 },
      meta: { signerName: 'Ada Lovelace', reason: 'I approve', location: 'London, UK' },
      wordOutput: 'pdf',
      mode: 'certified'
    })
  })).json();

  // 3. descargar: obtener el archivo firmado
  const blob = await (await fetch(base + '?sign=download&token=' + encodeURIComponent(signed.downloadToken))).blob();
  const link = document.createElement('a');
  link.href = URL.createObjectURL(blob);
  link.download = signed.downloadName;
  link.click();
  URL.revokeObjectURL(link.href);
}

Los puntos finales son same-origin: esta versión no tiene soporte CORS. Sirva su UI y el script del widget desde el mismo origen que la aplicación, o haga reverse-proxy a DocImage.axd y /doconut-res bajo el origen de su UI.

En producción

  1. Instale el plugin junto al paquete central, en la misma versión: Install-Package Doconut.NETFramework.Signer.

  2. Agregue el archivo de licencia. Coloque Doconut.Viewer.Signer.lic en la misma carpeta que Doconut.Viewer.lic.

  3. Obtenga su certificado como un PFX con su clave privada y cadena del emisor, de una autoridad certificadora o del PKI propio de su organización. Para probar primero, use una licencia de demostración (el certificado de demostración incorporado, con marca de agua) o un PFX autofirmado.

  4. Lea el certificado desde la configuración, de modo que cambiarlo nunca requiera una modificación de código:

    xml
    <appSettings>
      <add key="DoconutSigner:PfxPath" value="~/App_Data/your-certificate.pfx" />
    </appSettings>
    csharp
    var settings = System.Configuration.ConfigurationManager.AppSettings;
    
    Doconut.DoconutHost.Initialize(options =>
    {
        options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
        options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
        options.AddSignerWidget(widget => widget.SigningCertificate = new SigningCertificate
        {
            PfxPath = HostingEnvironment.MapPath(settings["DoconutSigner:PfxPath"]),
            Password = settings["DoconutSigner:Password"] ?? "",
        });
    });

    Mantenga el .pfx en App_Data, que IIS nunca sirve, y mantenga la contraseña fuera de un Web.config plano: use una sección de configuración encriptada, o un almacén de secretos que su despliegue lea.

  5. Firme un documento de prueba en modo Certificado. Un certificado que esté expirado o aún no sea válido es rechazado con The signing certificate expired on yyyy-MM-dd. (o is not valid before), y un lector de PDF muestra si confía en la firma.

Confianza en lectores de PDF. Un lector muestra la firma como válida cuando confía en la raíz del certificado. Con el PKI de su organización, eso se cumple en cada máquina que confía en su raíz, que suele ser cada máquina dentro de la organización. Los certificados que Adobe confía en cualquier máquina (la Adobe Approved Trust List) son, según sabemos, emitidos con la clave privada en un token de hardware o HSM, lo que este plugin no puede usar: solo firma desde un PFX. Confirme con su proveedor de certificados antes de depender de ese tipo de confianza.

Granjas web

El widget mantiene cada carga y su resultado en memoria en el servidor que sirvió open. Detrás de un balanceador de carga sin sesiones persistentes, una solicitud posterior de run, download o de vista previa puede llegar a otro servidor y no encontrar la carga. Registre el almacén de widget compartido y encriptado mediante el segundo argumento de DoconutHost.Initialize:

csharp
byte[] farmKey = Convert.FromBase64String(System.Configuration.ConfigurationManager.AppSettings["Doconut:FarmKey"]);

Doconut.DoconutHost.Initialize(
    options =>
    {
        options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
        options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
        options.AddSignerWidget();
    },
    services => services.AddDoconutDistributedWidgets(store =>
    {
        store.RootPath = @"\\fileshare\doconut";   // una carpeta que cada servidor puede leer y escribir
        store.FarmKey = farmKey;                   // al menos 32 bytes, idéntico en cada servidor
        // store.Ttl = TimeSpan.FromMinutes(30);   // cuánto tiempo se mantiene una carga (el predeterminado)
    }));
  • Un solo servidor no necesita nada: sin esta llamada se usa el almacén en memoria.
  • Las cargas y resultados están encriptados en reposo en el recurso compartido (AES-256, encrypt-then-MAC), y cada archivo está vinculado a su token, de modo que un token nunca puede leer el archivo de otro.
  • FarmKey debe tener al menos 32 bytes y ser idéntico en cada servidor. Cárguelo desde un almacén de secretos; nunca lo codifique directamente. El registro lanza un ArgumentException cuando RootPath falta o FarmKey es más corto que 32 bytes.
  • Apunte RootPath a la misma ubicación compartida que usa el visor distribuido, y proporcione a cada servidor el mismo certificado de firma.

Referencia de API

La fachada y las opciones del widget están en el espacio de nombres Doconut; los tipos de solicitud y resultado están en Doconut.Core.Models.Signing. SignerPlugin está en Doconut.Plugins.Signer.

DocumentSigner

csharp
public sealed class DocumentSigner
{
    public Task<SignResult> SignAsync(
        Stream source, string sourceExtension, SignRequest request,
        SigningCertificate? cert = null, CancellationToken ct = default);
}

Resuelto a partir de DoconutHost.Services; el constructor es interno. sourceExtension es ".pdf" o ".docx". Con una licencia de pago se usa cert y la salida es limpia; con una licencia temporal se usa el certificado de demostración incorporado, cert se ignora y la salida lleva marca de agua.

SignRequest

csharp
public sealed record SignRequest(
    VisibleSignature   Signature,
    SignaturePlacement Placement,
    string?            SignerName = null,
    string?            Reason     = null,
    string?            Location   = null,
    WordOutput         WordOutput = WordOutput.Pdf,
    SignatureMode      Mode       = SignatureMode.Certified)
{
    public bool IsValid { get; }   // Signature.IsValid && Placement.IsValid
}

Una firma visible colocada una vez, más metadatos opcionales del firmante.

VisibleSignature y SignatureKind

csharp
public sealed record VisibleSignature(SignatureKind Kind, byte[] PngBytes)
{
    public bool IsValid { get; }   // PngBytes no está vacío
}

public enum SignatureKind { Drawn, Typed, Image }

PngBytes es un PNG para cada tipo. Una firma dibujada o escrita a mano es transparente; una imagen cargada conserva la transparencia que tenía, por lo que un JPG opaco permanece opaco. Kind es solo una pista.

SignaturePlacement

csharp
public readonly record struct SignaturePlacement(int Page, double X, double Y, double W, double H)
{
    public bool IsValid { get; }   // Page >= 1; X, Y >= 0; W, H > 0; X + W <= 1; Y + H <= 1
}

Page es basado en 1; X, Y, W y H son 0..1 normalizados desde la esquina superior izquierda.

SignatureMode y WordOutput

csharp
public enum SignatureMode { Certified, Visual }   // Certified es el predeterminado
public enum WordOutput { Pdf, Docx }              // Pdf es el predeterminado; ignorado para fuentes PDF

SignResult

csharp
public sealed record SignResult(Stream Stream, string Extension);

El documento firmado como un flujo buscable, y su extensión con el punto (".pdf" o ".docx").

SigningCertificate

csharp
public sealed class SigningCertificate
{
    public byte[]? PfxBytes { get; init; }
    public string? PfxPath  { get; init; }
    public string  Password { get; init; } = "";
    public bool    HasMaterial { get; }   // PfxBytes no está vacío, o PfxPath no está en blanco
}

Establezca PfxBytes o PfxPath, más Password. Los setters son solo de inicialización: el proyecto necesita C# 9.0 o posterior.

SignerWidgetOptions

csharp
public sealed class SignerWidgetOptions
{
    public int MaxUploadMb { get; set; } = 25;
    public int MaxSignatureImageKb { get; set; } = 512;
    public SigningCertificate? SigningCertificate { get; set; }
}

Establezca a través de DoconutOptions.AddSignerWidget(Action<SignerWidgetOptions>? configure = null), que devuelve el DoconutOptions para que las llamadas puedan encadenarse. Un SigningCertificate nulo significa el certificado de demostración bajo una licencia temporal, y firmas Visual solo bajo una de pago.

Solución de problemas

SíntomaCausaSolución
Cada solicitud devuelve un 500 vacío después de agregar el plugin; el registro de eventos muestra The Signer plugin is registered via AddPlugin but no active license grants Signer.Sin licencia, un archivo TRIAL, una licencia sin Signer, o una licencia de pago fuera de su ventana de versiónInstale una licencia que conceda Signer, o elimine AddPlugin<SignerPlugin>()
El registro de eventos muestra AddSignerWidget() was called but the Signer plugin is not registered.El widget está habilitado sin su pluginAgregue options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>()
El registro de eventos muestra Doconut Signer: the certificate file was not found at '{path}'.PfxPath apunta a un archivo que faltaCorrija la ruta; despliegue el archivo donde la cuenta del pool de la aplicación pueda leerlo
El registro de eventos muestra Doconut Signer: the signing certificate could not be opened — the password is incorrect or the file is not a valid .pfx.Contraseña incorrecta, o no es un archivo PKCS#12Verifique la contraseña; use un .pfx real
El registro de eventos muestra Doconut Signer: the signing certificate has no private key. Re-export the .pfx INCLUDING the private key.El PFX se exportó sin su clave privadaExportelo nuevamente con la clave privada
new SigningCertificate { … } no compilaEl proyecto usa C# 7.3, que no puede establecer propiedades solo de inicializaciónEstablezca <LangVersion> a 9.0 o posterior
Resolver DocumentSigner lanza No IDocumentSigner is registered.SignerPlugin no está registradoAgregue AddPlugin<SignerPlugin>() en DoconutHost.Initialize
La salida lleva marca de aguaLa licencia es temporal (Demo/NFR)Utilice una licencia de pago que conceda Signer
run responde 400 No signing certificate configured.Una licencia de pago, modo Certificado, y sin certificadoConfigure SigningCertificate, o firme en modo Visual
run responde 400 The signing certificate expired on yyyy-MM-dd.El certificado está desactualizadoReemplácelo; las firmas Visual siguen funcionando mientras tanto
El widget se carga pero dice Signing is not enabled on this server.AddSignerWidget() no fue llamado, o basePath no está '/DocImage.axd'Llame a AddSignerWidget(); establezca basePath: '/DocImage.axd'
Una carga grande muestra una página de error de IIS en lugar del mensaje del widgetmaxRequestLength / maxAllowedContentLength están por debajo de MaxUploadMbAumente ambos límites de host por encima de MaxUploadMb
run responde 400 The signature image must be a PNG., Signature image is not valid base64. o Signature image is too large.Una UI personalizada envió una URL data:, un JPG, o más de MaxSignatureImageKbEnvíe un PNG base64 sin formato dentro del límite
open responde 413 File is too large.La carga supera MaxUploadMbAumente MaxUploadMb en AddSignerWidget; el maxUploadMb del widget es solo una verificación del lado del cliente
run o download responde 404 Upload expired — please re-open the file.Han pasado los 30 minutos, o otro servidor en el conjunto no tiene la cargaAbra el archivo nuevamente; en un conjunto, registre AddDoconutDistributedWidgets
Un .docx firmado no muestra firma en algunos visoresLa salida de Word lleva una firma de paquete OOXML, que muchos visores no muestranFirme a PDF, que es el predeterminado
Los lectores de PDF indican que la identidad del firmante es desconocidaEl lector no confía en la raíz del certificado (el certificado de demostración nunca es confiable)Utilice un certificado de una raíz que sus lectores confíen
El widget falla cuando la UI está en otro origenLos endpoints no tienen soporte CORSSirva la UI desde el mismo origen, o haga reverse-proxy de DocImage.axd y /doconut-res
El tema no se aplicaEl selector apunta a un elemento dentro del montajeApunte al propio montaje: #host.dsw o #host

Notas del framework

En comparación con los paquetes ASP.NET Core, este paquete difiere solo en el alojamiento; la API, el contrato del endpoint, el script del widget y las reglas de licencia son los mismos.

  • Registro está en Application_Start, a través de DoconutHost.Initialize, en lugar de builder.Services.AddDoconut. Servicios como AddDoconutDistributedWidgets van en su segundo argumento.
  • Puntos finales son servidos por DocImage.axd y el script por DoconutResourceModule, ambos registrados en Web.config, en lugar de UseDoconut() y UseDoconutResources(). El widget necesita basePath: '/DocImage.axd'.
  • Fallas de inicio aparecen como un 500 vacío en cada solicitud, con la razón en el registro de eventos de Windows.
  • Cargas son leídas completamente por ASP.NET antes de que Doconut las vea, por lo que los límites de IIS deben estar por encima de MaxUploadMb.
  • Sin línea de registro de inicio sobre el certificado: los tres errores de certificado siguen lanzándose, pero la línea que nombra el certificado no se escribe.
  • C# 9.0 o posterior es necesario para establecer las propiedades de solo inicialización de SigningCertificate.
  • Solo Windows, como el resto del paquete .NET Framework.

¿Fue útil esta página?