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.

SuperficieUsarlo cuando
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 (?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

Instala el plugin Signer estable más reciente:

bash
dotnet add package Doconut.NET8.Signer

Para fijar el plugin a la versión que describe esta documentación, pasa la versión por separado:

bash
dotnet add package Doconut.NET8.Signer --version 26.10.0

Mantén el paquete Signer en la misma versión que Doconut.NET8. El ID del paquete es Doconut.NET8.Signer; .<version> aparece solo en el nombre de archivo .nupkg descargado.

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.

Plataformas. El plugin se ejecuta dondequiera que Doconut.NET8 se ejecute: Windows y Linux basado en glibc en x64 (no Alpine ni otras distribuciones basadas en musl). En Linux, instala la biblioteca de configuración de fuentes antes de que se abra el primer documento:

bash
apt-get update && apt-get install -y libfontconfig1

En RHEL, Fedora y distribuciones similares, el paquete es fontconfig. Sin él, la apertura de un documento falla con The system library libfontconfig1 is missing. Install it (Debian/Ubuntu: apt-get install -y libfontconfig1) and see the Linux section of the Doconut documentation.

Registrar el plugin

Como cualquier plugin Doconut, Signer se registra con AddPlugin<TPlugin>() dentro de AddDoconut():

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
});

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, AddDoconut() lanza una excepción al iniciar, antes de que la aplicación sirva una solicitud:

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.

Lanza una excepción por falta de licencia, un archivo legado TRIAL, una licencia sin Signer, y una licencia de pago usada fuera de su ventana de versión. Se aceptan licencias temporales Demo/NFR. Consulte Configuración de Licencia para saber cómo se cargan las licencias.

Licenciamiento y marca de agua

Estado de licenciaInicioFirma certificadaFirma visual
Licencia de pago que otorga Signer, certificado configuradoIniciaSellado con tu certificado, limpio (watermarked: false)Limpio
Licencia de pago que otorga Signer, sin certificadoIniciaRechazado: No signing certificate configured.Limpio
Licencia de pago, certificado expirado o aún no válidoInicia (con el widget habilitado, se registra una advertencia)Rechazado: 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 legado TRIAL, una licencia sin Signer, o una licencia de pago fuera de su ventana de versiónAddDoconut() lanza una excepción——

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 de pago o es temporal. Con 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 y 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 de pago como tu propio certificado de firma.

Uso desde C#

DocumentSigner está registrado por AddDoconut() y resuelto mediante inyección de dependencias. 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 (visible signature \u002B digital seal); 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, 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 pueda nombrar el archivo. Usted posee el flujo: dispóngalo cuando haya terminado.

Una firma Visual estampa solo la imagen y no necesita certificado:

csharp
var signer = app.Services.GetRequiredService<DocumentSigner>();
byte[] signaturePng = File.ReadAllBytes("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(stream, ".pdf", request, ct: ct);

Una fuente Word se firma a PDF a menos que solicite salida Word. Nombre el resultado de result.Extension:

csharp
var signer = app.Services.GetRequiredService<DocumentSigner>();
byte[] signaturePng = File.ReadAllBytes("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;   // \u0022.docx\u0022

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ó 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 Word y certificados

Modos de firma

SignRequest.Mode elige si la firma está sellada.

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

Utilice Certified cuando la firma debe ser comprobable: aprobaciones, contratos, cualquier cosa que un verificador necesite revisar para la identidad e integridad. Utilice Visual cuando solo necesita la apariencia de una firma, o no tiene 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 su PFX, de modo que un lector que confíe en su raíz pueda construir la cadena. Los sellos nativos de Word son firmas de paquetes OOXML y transportan solo 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é ocurreSoporte del verificador
WordOutput.Pdf (predeterminado)El documento se convierte a PDF, luego se firma y sellaAmplio: un PDF firmado se verifica en todas partes
WordOutput.DocxEl documento permanece en Word: la imagen de la firma se inserta en él, más una firma de paquete OOXMLLimitado: no todos los visores muestran firmas de paquetes OOXML

Mantenga PDF a menos que el destinatario necesite un archivo Word editable y acepte el soporte limitado del verificador.

Configuración del certificado

Para sellar con su propia identidad, proporcione al complemento un archivo PFX (PKCS#12) que incluya la clave privada. Para el widget, establezca SignerWidgetOptions.SigningCertificate; para la fachada C#, pase el certificado a SignAsync. Proporcione ya sea los bytes o una ruta, más la contraseña:

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
    options.AddSignerWidget(widget =>
    {
        widget.SigningCertificate = new SigningCertificate
        {
            PfxBytes = File.ReadAllBytes("/secure/signing.pfx"),
            Password = builder.Configuration["Signing:PfxPassword"],
        };
    });
});
csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
    options.AddSignerWidget(widget =>
    {
        widget.SigningCertificate = new SigningCertificate
        {
            PfxPath = "/secure/signing.pfx",
            Password = builder.Configuration["Signing:PfxPassword"],
        };
    });
});

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 una línea de registro o 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. Exporte la cadena del emisor con él, de modo que los sellos PDF puedan llevarla.
  • La contraseña correcta.
  • Dentro de su ventana de validez. Un certificado expirado o aún no válido no detiene la aplicación: se registra como Advertencia al iniciar, y las firmas Certificadas se rechazan hasta que se reemplace. Las firmas Visuales 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 se registra como Advertencia y los lectores PDF marcan la firma.
  • Los tokens de hardware, tarjetas inteligentes, HSM y el almacén de certificados de Windows no son compatibles. Exporte el certificado, con su clave privada y cadena, a un PFX.

Cree 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.

Exporte uno desde el almacén de certificados de Windows: abra certmgr.msc y encuentre el certificado (su ícono muestra una llave cuando la clave privada está presente). Haga clic derecho, elija Todas las tareas → Exportar…, seleccione Sí, exportar la clave privada, elija Intercambio de información personal – PKCS #12 (.PFX), y establezca una contraseña.

Comprobaciones al iniciar

Cuando el widget está habilitado, el certificado en SignerWidgetOptions.SigningCertificate se verifica una vez, dentro de AddDoconut(), de modo que un PFX mal configurado falla al iniciar en lugar de en la primera firma. Tres problemas generan un InvalidOperationException:

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 de la aplicación
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

De lo contrario, el host escribe una línea en el registro al iniciar. Información cuando el certificado está listo:

text
Doconut Signer: using certificate '{subject}' (valid until yyyy-MM-dd). Signatures are digitally sealed.

Una Advertencia cuando está expirado, aún no es válido, o no está emitido para firma de documentos:

text
Doconut Signer: the signing certificate '{subject}' expired on yyyy-MM-dd. Certified signatures will be refused until it is replaced.
Doconut Signer: the signing certificate '{subject}' is not valid before yyyy-MM-dd. Certified signatures will be refused until then.
Doconut Signer: the signing certificate '{subject}' is not issued for document signing (its key usage excludes it). PDF readers will flag these signatures.

Y Información cuando no hay certificado configurado:

text
Doconut Signer: no signing certificate configured — output uses the built-in demo certificate and is watermarked. Set SignerWidgetOptions.SigningCertificate to sign with your own certificate.

Esa última línea es la misma bajo cualquier licencia. Con una licencia paga el certificado de demostración nunca se usa: sin certificado, solo funcionan las firmas Visuales.

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 incrustable

Habilitar los endpoints

Los endpoints ?sign=open|run|download del widget están desactivados por defecto. Habilítelos junto al registro del plugin:

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
    options.AddSignerWidget(widget =>
    {
        widget.MaxUploadMb = 25;           // por defecto
        widget.MaxSignatureImageKb = 512;  // por defecto
        // widget.SigningCertificate: ver configuración del certificado; dejarlo null para la firma de demostración (con marca de agua)
    });
});

AddSignerWidget() sin argumentos habilita el widget con los valores predeterminados. No otorga la firma por sí mismo: necesita AddPlugin<SignerPlugin>(), o AddDoconut() 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.

Sin AddSignerWidget(), cada solicitud ?sign= responde 404. El script sigue sirviéndose, por lo que el widget se carga y dibuja su zona de arrastre, luego informa Signing is not enabled on this server. en su primera solicitud.

Incrustarlo

UseDoconutResources() sirve el script en {ResourcesPath}/js/doconutSigner.js (por defecto /doconut-res/js/doconutSigner.js). Es un único archivo autónomo sin dependencias:

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

Doconut.signer(selectorOrElement, options) acepta un selector CSS o un elemento, lanza una excepción si no se encuentra el montaje, y devuelve un manejador.

El firmante sube un archivo PDF o .docx, crea una firma (Dibujar en un lienzo, Escribir un nombre con una fuente de firma, o Imagen desde un PNG, JPG o GIF), la 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 se ajusta a 520×160.

Opciones

OpciónTipoPredeterminadoNotas
basePathstring'/doconut'Dónde se sirven los endpoints ?sign= y las imágenes de vista previa
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 Firma digital / Solo visual. 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: '/doconut', licenseUrl: '/pricing' });
javascript
// Solo visual, sin interruptor: un sello simple sin firma digital ofrecida.
Doconut.signer('#host', {
  basePath: '/doconut',
  signatureMode: 'visual',
  showSignatureModeToggle: false
});

Retrollamadas

RetrollamadaSe dispara cuandoCarga útil
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 }
onDownloadAl hacer clic en Descargar cada vez{ downloadName, downloadToken }
onErrorUn paso de abrir, firmar o descargar falla, o un archivo en modo Imagen es demasiado grande{ message }

Una retrollamada que lanza una excepción es capturada y registrada; nunca interrumpe el flujo del widget.

Manejo imperativo

MétodoComportamiento
reset()Regresa a la pantalla de caída y borra 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 caída; llama a reset() primero si es necesario
destroy()Elimina los listeners, vacía el montaje y congela la instancia
javascript
const signerWidget = Doconut.signer('#host', {
  basePath: '/doconut',
  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 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 UI del sistema y una fuente cursiva para firmas.

Construye tu propio frontend

El widget es un cliente para este contrato HTTP. Las tres rutas se encuentran bajo la ruta donde UseDoconut() está montado (normalmente /doconut), y responden 404 hasta que se llama a AddSignerWidget(). Los errores llevan un cuerpo JSON, { "error": "..." }, excepto donde la tabla indica "solo estado". Un valor desconocido de ?sign= responde 400.

RutaPropósitoRespuesta exitosa
POST ?sign=open (multipart, one file)Cargar un PDF o .docx y abrirlo para vista previa200 — { token, name, pages, ext }
POST ?sign=run (JSON body)Firmar el archivo cargado200 — { downloadToken, downloadName, watermarked }
GET ?sign=download&token=<downloadToken>Transmitir 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 imagen del visor, {basePath}?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 valor se convierte en Drawn. Solo una pista: la carga siempre es un PNG
signature.payloadUn PNG base64 puro, sin prefijo data:. Debe ser un PNG real y no mayor que MaxSignatureImageKb una vez decodificado
placement.pageBasado en 1
placement.x / y / w / h0..1 normalizado 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 (por defecto) o docx; ignorado para fuentes PDF. Cualquier otro valor se convierte en pdf
modecertified (por defecto) o visual. Cualquier otro valor 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 de nuevo. 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.
open400No hay archivo, o está vacíoNo file uploaded.
open400Cualquier cosa distinta de .pdf o .docxSigning supports PDF and Word (.docx) files only.
open413La carga supera MaxUploadMbFile 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 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 puro, sin prefijo data:
// por ejemplo canvas.toDataURL('image/png').split(',')[1].
async function signFile(file, pngBase64) {
  const base = '/doconut';

  // 1. open: 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. run: 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. download: 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. Sirve tu UI y el script del widget desde el mismo origen que Doconut, o haz reverse‑proxy de ambos caminos /doconut (la ruta del middleware y la ruta de los recursos) bajo el origen de tu UI.

En producción

  1. Instala el plugin junto al paquete central, en la misma versión: dotnet add package Doconut.NET8.Signer.

  2. Añade el archivo de licencia. Coloca Doconut.Viewer.Signer.lic en la misma carpeta que Doconut.Viewer.lic.

  3. Obtén tu certificado como un PFX con su clave privada y cadena de emisores, de una autoridad certificadora o de la PKI propia de tu organización. Para probar primero, usa una licencia de demostración (el certificado de demo incorporado, con marca de agua) o un PFX autofirmado.

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

    json
    "DoconutSigner": { "PfxPath": "certs/your-certificate.pfx" }
    csharp
    var signerSettings = builder.Configuration.GetSection("DoconutSigner");
    
    builder.Services.AddDoconut(options =>
    {
        options.LicensePath = "Doconut.Viewer.lic";
        options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
        options.AddSignerWidget(widget => widget.SigningCertificate = new SigningCertificate
        {
            PfxPath = Path.Combine(builder.Environment.ContentRootPath, signerSettings["PfxPath"]),
            Password = signerSettings["Password"] ?? "",
        });
    });

    Mantén el .pfx fuera de wwwroot, y mantén la contraseña fuera de appsettings.json: secretos de usuario en desarrollo (dotnet user-secrets set "DoconutSigner:Password" "<password>"), una variable de entorno (DoconutSigner__Password) o una bóveda en producción.

  5. Revisa el registro de inicio. Debería mostrar using certificate '{subject}' (valid until …). Signatures are digitally sealed.. Una advertencia, en cambio, significa que el certificado está expirado, aún no es válido, o no está emitido para la firma de documentos.

Confía en los lectores PDF. Un lector muestra la firma como válida cuando confía en la raíz del certificado. Con la PKI de tu organización, eso se cumple en cada máquina que confía en tu 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 cual este plugin no puede usar: solo firma desde un PFX. Confirma con tu 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 nodo 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 nodo y no encontrar la carga. Registra el almacén de widget compartido y cifrado una sola vez, después de AddDoconut():

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

builder.Services.AddDoconutDistributedWidgets(store =>
{
    store.RootPath = @"\\fileshare\doconut";   // una carpeta que cada nodo puede leer y escribir
    store.FarmKey = farmKey;                   // al menos 32 bytes, idéntico en cada nodo
    // store.Ttl = TimeSpan.FromMinutes(30);   // cuánto tiempo se mantiene una carga (el predeterminado)
});
  • Un solo servidor no necesita nada: sin esta llamada se utiliza el almacén en memoria.
  • Las cargas y resultados están cifrados 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 nodo. Cárgalo desde un almacén de secretos; nunca lo codifiques directamente. El registro lanza un ArgumentException cuando RootPath falta o FarmKey es más corto que 32 bytes.
  • Apunta RootPath a la misma ubicación compartida que usa el visor distribuido, y proporciona a cada nodo 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 mediante inyección de dependencias; el constructor es interno. sourceExtension es ".pdf" o ".docx". Con una licencia paga cert se utiliza 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 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.

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 Visuales solo bajo una licencia paga.

Solución de problemas

SíntomaCausaSolución
AddDoconut() lanza 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 paga fuera de su ventana de versiónInstale una licencia que conceda Signer, o elimine AddPlugin<SignerPlugin>()
AddDoconut() lanza AddSignerWidget() was called but the Signer plugin is not registered.El widget está habilitado sin su complementoAgregue options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>()
AddDoconut() lanza 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 de la aplicación pueda leerlo
AddDoconut() lanza 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
AddDoconut() lanza Doconut Signer: the signing certificate has no private key. Re-export the .pfx INCLUDING the private key.El PFX se exportó sin su clave privadaExpórtelo nuevamente con la clave privada
Resolviendo DocumentSigner lanza No IDocumentSigner is registered.SignerPlugin no está registradoAgregue AddPlugin<SignerPlugin>() dentro de AddDoconut()
La salida lleva marca de aguaLa licencia es temporal (Demo/NFR)Use una licencia paga que conceda Signer
run responde 400 No signing certificate configured.Una licencia paga, 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á desactualizadoReemplacelo; las firmas Visuales siguen funcionando mientras tanto
El registro indica que la salida "usa el certificado de demostración incorporado", pero una licencia paga rechaza firmas CertificadasEsa línea se escribe siempre que no se configura un certificado, sea cual sea la licenciaConfigure SigningCertificate
El widget se carga pero dice Signing is not enabled on this server.AddSignerWidget() no fue llamado, o basePath no coincide donde UseDoconut() está montadoLlame a AddSignerWidget(); corrija basePath
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 puro dentro del límite
open responde 413 File is too large.La carga supera MaxUploadMbEleve 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.El intervalo de 30 minutos expiró, o un nodo de la granja web no tiene la cargaAbra el archivo de nuevo; en una granja, 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, 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)Use 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 las rutas Doconut
El tema no se aplicaEl selector apunta a un elemento dentro del montajeApunte al propio montaje: #host.dsw o #host

¿Fue útil esta página?