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.
| Superficie | Cuá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
Install-Package Doconut.NETFramework.SignerPara fijar el plugin a la versión que describe esta documentación:
Install-Package Doconut.NETFramework.Signer -Version 26.10.0Manté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:
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:
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 licencia | Inicio | Firma certificada | Firma visual |
|---|---|---|---|
Licencia paga que otorga Signer, certificado configurado | Inicia | Sellado con tu certificado, limpio (watermarked: false) | Limpio |
Licencia paga que otorga Signer, sin certificado | Inicia | Rechazado: No signing certificate configured. | Limpio |
| Licencia paga, certificado expirado o aún no válido | Inicia | Rechazado: The signing certificate expired on yyyy-MM-dd. | Limpio |
| Licencia temporal Demo/NFR, activa o expirada | Inicia | Sellado 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ón | Application_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>().
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:
[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:
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ón | Mensaje | Cuándo |
|---|---|---|
InvalidOperationException | No signing certificate configured. | Modo certificado, una licencia de pago, y no se pasó ningún certificado |
InvalidOperationException | The 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 |
ArgumentException | The 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 |
NotSupportedException | The 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.
| Modo | Qué produce | Certificado | Verificable |
|---|---|---|---|
SignatureMode.Certified (predeterminado) | La firma visible más un sello digital | Requerido bajo una licencia de pago | Sí |
SignatureMode.Visual | Sólo la firma visible | Nunca necesario | No: 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.
| Salida | Qué ocurre | Compatibilidad del verificador |
|---|---|---|
WordOutput.Pdf (predeterminado) | El documento se convierte a PDF, luego se firma y sella | Amplia: un PDF firmado se verifica en cualquier lugar |
WordOutput.Docx | El documento permanece en Word: la imagen de la firma se coloca en él, más una firma de paquete OOXML | Limitada: 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:
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"] ?? "",
};
});
});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:
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:
| Mensaje | Solució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:
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:
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:
<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:
<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:
<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ón | Tipo | Predeterminado | Notas |
|---|---|---|---|
basePath | string | '/doconut' | Dónde se sirven los endpoints ?sign= y las imágenes de vista previa. Establezca '/DocImage.axd' en este paquete |
resPath | string | '/doconut-res' | Reservado; el widget incluye su propio CSS |
maxUploadMb | number | 25 | Solo 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 |
maxSignatureKb | number | 512 | Límite del lado del cliente para el modo Imagen. Manténgalo igual al MaxSignatureImageKb del servidor |
previewWidth | number | 560 | Ancho en píxeles de la vista previa de la página |
licenseUrl | string | null | null | Convierte el aviso de marca de agua de demostración en un enlace a esta URL |
signatureMode | string | 'certified' | Tipo de firma inicial: 'certified' o 'visual'. Cualquier otro valor se convierte en 'certified' |
showSignatureModeToggle | boolean | true | Muestra la opción Digital signature / Visual only. Con false, el widget firma con signatureMode |
wordOutput | string | 'pdf' | Salida inicial para fuentes .docx: 'pdf' o 'docx'. Cualquier otro valor se convierte en 'pdf' |
showOutputFormatToggle | boolean | true | Muestra la opción PDF / Word, solo para fuentes .docx. Con false, el widget usa wordOutput |
labels | object | {} | Sobrescribe cualquier subconjunto de las cadenas en inglés |
Ocultar un interruptor no desactiva la función; fija el valor. Dos configuraciones comunes:
// Ambos interruptores mostrados, firma digital por defecto: un firmante de autoservicio completo.
Doconut.signer('#host', { basePath: '/DocImage.axd', licenseUrl: '/pricing' });// Solo visual, sin interruptor: un sello simple sin firma digital ofrecida.
Doconut.signer('#host', {
basePath: '/DocImage.axd',
signatureMode: 'visual',
showSignatureModeToggle: false
});Retrollamadas
| Retrollamada | Se dispara cuando | Carga |
|---|---|---|
onReady | Una vez, al montar (no de nuevo en reset()) | — |
onSourceLoaded | El archivo se abre y se muestra su vista previa | { file: { token, name, pages, ext } } |
onSigned | La firma tiene éxito | { downloadToken, downloadName, watermarked } |
onDownload | En cada clic de Descargar | { downloadName, downloadToken } |
onError | Falla 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étodo | Comportamiento |
|---|---|
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 |
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'.
| Clave | Valor predeterminado en inglés |
|---|---|
dropPrompt | Drag & drop a PDF or Word file here |
dropHint | PDF or Word (.docx) |
chooseFile | Choose file |
signatureHeading | Your signature |
modeDraw / modeType / modeImage | Draw / Type / Image |
metaSummary | Signature details (optional) |
metaSignerName / metaReason / metaLocation | Signer name / Reason / Location |
signatureType | Signature type |
modeCertified / modeVisual | Digital signature / Visual only |
modeVisualNote | No certificate — a visible mark only, not cryptographically verifiable. |
outputFormat | Output format |
outputPdf / outputWord | PDF / Word (.docx) |
signAction | Sign document |
download | Download |
demoNotice | Demo — signed with the Doconut demo certificate; output is watermarked. |
signingNotEnabled | Signing is not enabled on this server. |
page / pages | 1 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:
#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.
| Ruta | Propósito | Respuesta exitosa |
|---|---|---|
POST /DocImage.axd?sign=open (multipart, un archivo) | Carga un PDF o .docx y ábrelo para vista previa | 200 — { token, name, pages, ext } |
POST /DocImage.axd?sign=run (cuerpo JSON) | Firma el archivo cargado | 200 — { downloadToken, downloadName, watermarked } |
GET /DocImage.axd?sign=download&token=<downloadToken> | Transmite el archivo firmado | 200 — 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:
{
"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"
}| Campo | Notas |
|---|---|
token | El token de open |
signature.kind | Drawn, 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.payload | Un PNG base64 sin formato, sin prefijo data:. Debe ser un PNG real y no mayor que MaxSignatureImageKb una vez decodificado |
placement.page | basado en 1 |
placement.x / y / w / h | Normalizado 0..1 desde la esquina superior izquierda, con x + w ≤ 1 y y + h ≤ 1 |
meta.signerName / reason / location | Opcional. Cada uno se recorta, un valor en blanco se descarta, y cada uno se corta a 256 caracteres |
wordOutput | pdf (predeterminado) o docx; ignorado para fuentes PDF. Cualquier otro se convierte en pdf |
mode | certified (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.
| Ruta | Estado | Cuándo | Cuerpo |
|---|---|---|---|
| cualquiera | 404 | El widget no está habilitado | solo estado |
| cualquiera | 405 | Verbo incorrecto (open y run necesitan POST, download necesita GET) | solo estado |
open | 400 | No es una carga multipart | Expected a multipart file upload. |
open | 400 | Sin archivo, o uno vacío | No file uploaded. |
open | 400 | Cualquier cosa distinta de .pdf o .docx | Signing supports PDF and Word (.docx) files only. |
open | 413 | La carga supera MaxUploadMb (pero no los límites de IIS) | File is too large. |
run | 400 | El cuerpo no es JSON válido, o está vacío | Malformed request. / Empty request. |
run | 400 | Falta el token o no es un GUID | Invalid token. |
run | 404 | La carga expiró o nunca se abrió | Upload expired — please re-open the file. |
run | 400 | Sin firma, o sin colocación | No signature supplied. / No placement supplied. |
run | 400 | La carga útil no es base64, está vacía, es demasiado grande, o no es un PNG | Signature image is not valid base64. / Signature image is empty. / Signature image is too large. / The signature image must be a PNG. |
run | 400 | La colocación está fuera de la página | The signature or its placement is invalid. |
run | 400 | Modo certificado, una licencia paga y sin certificado | No signing certificate configured. |
run | 400 | Modo certificado con un certificado fuera de su ventana de validez | The signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd. |
open, run | 500 | Procesamiento falló | Un mensaje sanitizado |
download | 400 | Falta el token o no es un GUID | solo estado |
download | 404 | Token desconocido o expirado | solo estado |
Un recorrido completo con fetch:
// 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
-
Instale el plugin junto al paquete central, en la misma versión:
Install-Package Doconut.NETFramework.Signer. -
Agregue el archivo de licencia. Coloque
Doconut.Viewer.Signer.licen la misma carpeta queDoconut.Viewer.lic. -
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.
-
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>csharpvar 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
.pfxenApp_Data, que IIS nunca sirve, y mantenga la contraseña fuera de unWeb.configplano: use una sección de configuración encriptada, o un almacén de secretos que su despliegue lea. -
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.(ois 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:
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.
FarmKeydebe 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 unArgumentExceptioncuandoRootPathfalta oFarmKeyes más corto que 32 bytes.- Apunte
RootPatha 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
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
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
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
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
public enum SignatureMode { Certified, Visual } // Certified es el predeterminado
public enum WordOutput { Pdf, Docx } // Pdf es el predeterminado; ignorado para fuentes PDFSignResult
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
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
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íntoma | Causa | Solució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ón | Instale 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 plugin | Agregue 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 falta | Corrija 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#12 | Verifique 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 privada | Exportelo nuevamente con la clave privada |
new SigningCertificate { … } no compila | El proyecto usa C# 7.3, que no puede establecer propiedades solo de inicialización | Establezca <LangVersion> a 9.0 o posterior |
Resolver DocumentSigner lanza No IDocumentSigner is registered. | SignerPlugin no está registrado | Agregue AddPlugin<SignerPlugin>() en DoconutHost.Initialize |
| La salida lleva marca de agua | La 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 certificado | Configure SigningCertificate, o firme en modo Visual |
run responde 400 The signing certificate expired on yyyy-MM-dd. | El certificado está desactualizado | Reemplá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 widget | maxRequestLength / maxAllowedContentLength están por debajo de MaxUploadMb | Aumente 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 MaxSignatureImageKb | Envíe un PNG base64 sin formato dentro del límite |
open responde 413 File is too large. | La carga supera MaxUploadMb | Aumente 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 carga | Abra el archivo nuevamente; en un conjunto, registre AddDoconutDistributedWidgets |
Un .docx firmado no muestra firma en algunos visores | La salida de Word lleva una firma de paquete OOXML, que muchos visores no muestran | Firme a PDF, que es el predeterminado |
| Los lectores de PDF indican que la identidad del firmante es desconocida | El 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 origen | Los endpoints no tienen soporte CORS | Sirva la UI desde el mismo origen, o haga reverse-proxy de DocImage.axd y /doconut-res |
| El tema no se aplica | El selector apunta a un elemento dentro del montaje | Apunte 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 deDoconutHost.Initialize, en lugar debuilder.Services.AddDoconut. Servicios comoAddDoconutDistributedWidgetsvan en su segundo argumento. - Puntos finales son servidos por
DocImage.axdy el script porDoconutResourceModule, ambos registrados enWeb.config, en lugar deUseDoconut()yUseDoconutResources(). El widget necesitabasePath: '/DocImage.axd'. - Fallas de inicio aparecen como un
500vací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?