Firma con KMS en la nube (AWS KMS, Azure Key Vault, GCP KMS)

De un vistazo

NextPDF Pro firma un PDF con una clave custodiada en un servicio de gestión de claves en la nube (KMS). Los proveedores admitidos son Amazon Web Services (AWS) KMS, Microsoft Azure Key Vault y Google Cloud Platform (GCP) Cloud KMS. Cada proveedor implementa un mismo contrato de firma, de modo que la aplicación depende del contrato y no de una clase de proveedor. Al proveedor solo se le envía el resumen de los atributos firmados; el documento nunca sale del host para la operación de firma. Esta página es de nivel de comportamiento: indica qué envía y recibe cada proveedor, cómo se resuelven las versiones de clave y dónde deja la custodia de claves de ser responsabilidad de NextPDF.

El contrato extiende el contrato del firmante de hardware y nube del Core, de modo que una estrategia de KMS en la nube se conecta a la misma ruta de firma que utiliza el firmante del Core.

Los requisitos previos se indican en el front matter y se repiten en Requisitos previos.

Edición y licenciamiento

Las estrategias de firma con KMS en la nube se entregan en el paquete nextpdf/pro y están protegidas por el indicador de función de licencia pro. NextPDF Core incluye un firmante CMS por software; NextPDF Enterprise añade custodia de claves en hardware a través de PKCS#11. La firma con KMS en la nube es una capacidad de Pro y también es accesible en Enterprise, dado que Enterprise depende de Pro. Un despliegue sin un derecho de uso de Pro activo no carga estas clases de estrategia; el contrato de firma del Core sigue funcionando sin cambios. Comparar ediciones.

Qué hace esta capacidad

Cada firmante de KMS en la nube implementa un contrato de proveedor que extiende el contrato del firmante del Core. El contrato añade tres cosas: un identificador de proveedor estable para la búsqueda en el registro, un método de firma consciente de la versión de clave y la autodescripción de los algoritmos que admite un proveedor para que el orquestador pueda elegir un proveedor compatible antes de firmar.

El flujo de firma mantiene el documento en el host:

1. La sesión de firma de Pro calcula el resumen del documento y construye los atributos firmados CMS.
2. La sesión calcula el hash de los atributos firmados y envía al proveedor únicamente ese resumen. Un servicio de firma externo que acepta un resumen de mensaje proporcionado por el llamador y devuelve la firma es el patrón establecido para mantener el documento dentro del límite propio, tal como se describe en el marco de referencia del EU Digital Signature Service (DSS).
3. El proveedor firma el resumen con la versión de clave que resuelve y devuelve la firma en bruto.
4. La sesión ensambla el CMS SignedData y lo incrusta en el PDF.

Los proveedores se implementan mediante llamadas HTTP (Hypertext Transfer Protocol) puras de PSR-18 —sin dependencia del kit de desarrollo de software (SDK) de ningún proveedor de nube—. La autenticación se delega en la aplicación: se proporciona un token de portador (AWS, GCP) o un token o credencial de entidad de servicio (Azure). Cada proveedor normaliza su salida para CMS: AWS y GCP devuelven firmas Rivest–Shamir–Adleman (RSA) en forma DER listas para CMS; una firma del algoritmo de firma digital de curva elíptica (ECDSA) que un proveedor devuelve como un par de enteros en bruto (Azure) se convierte a la forma codificada en DER, mientras que GCP devuelve ECDSA ya codificada en DER. La curva ECDSA y el resumen se emparejan de forma convencional —P-256 con SHA-256, P-384 con SHA-384, P-521 con SHA-512— según el emparejamiento recomendado en RFC 5480.

Un registro PSR-11 resuelve los proveedores por identificador y admite fábricas perezosas. Los clientes de Enterprise con autoalojamiento registran un controlador HSM o KMS propietario implementando el contrato de proveedor y enlazándolo en el registro, sin bifurcar NextPDF Pro.

Semántica de versión de clave por proveedor

Los proveedores exponen primitivas de «versión activa» distintas, por lo que el comportamiento predeterminado de versión de clave difiere:

• AWS KMS — una versión de clave null utiliza el alias de la clave, que AWS resuelve a la versión de clave actual del lado del proveedor.
• Azure Key Vault — una versión de clave null utiliza la URL de clave sin versión, que Azure resuelve a la última versión habilitada. Una sustitución explícita debe ser un identificador hexadecimal de 32 caracteres; cualquier otro valor se rechaza para evitar la inyección de segmentos de URL.
• GCP Cloud KMS — el endpoint de firma asimétrica opera únicamente sobre una versión concreta de clave criptográfica; no existe una «versión activa» del lado del servidor. Debe fijarse una versión en la configuración o pasarse explícitamente. Si no se establece ninguna, el firmante genera un error de gestión de claves en lugar de adivinar.

Documenta qué modo utiliza tu despliegue para que el comportamiento sea determinista.

Requisitos previos

1. Instala NextPDF Core y el paquete de Pro, y dispón de una licencia de Pro activa.
2. Aprovisiona una clave de firma en el proveedor elegido y anota sus identificadores (alias de clave o Amazon Resource Name para AWS; nombre de bóveda y de clave para Azure; proyecto, ubicación, anillo de claves, clave criptográfica y versión para GCP).
3. Proporciona un cliente HTTP de PSR-18 y fábricas de petición y de flujo de PSR-17.
4. Obtén la credencial del proveedor en tu aplicación: un token de portador para AWS o GCP, o un token previamente obtenido o credenciales de entidad de servicio para Azure. La adquisición del token es responsabilidad de tu aplicación; suministra los secretos desde tu gestor de secretos, nunca desde el código fuente.

Configuración

Cada proveedor tiene un objeto de configuración inmutable construido a partir de tus identificadores y credenciales. Aspectos comunes de la configuración:

• Identificador de proveedor — aws-kms, azure-keyvault o gcp-kms, usado como clave de búsqueda en el registro.
• Algoritmo — seleccionado por llamada a partir del nombre de algoritmo que pasa tu sesión de firma; el proveedor rechaza un algoritmo que no admite.
• Versión de clave — fijada en la configuración o pasada por llamada, con la semántica por proveedor descrita arriba.
• Credencial — un token de portador o credenciales de entidad de servicio que tu aplicación suministra desde su gestor de secretos.

Paso a paso

1. Construye la configuración del proveedor a partir de tus identificadores y una credencial leída desde tu gestor de secretos.
2. Construye el firmante del proveedor con la configuración, el certificado del firmante en forma DER, la cadena, el cliente de PSR-18 y las fábricas de PSR-17.
3. Opcionalmente, registra el proveedor en el registro PSR-11 bajo su identificador para que el orquestador lo resuelva por nombre.
4. Ejecuta la sesión de firma de Pro: calcula el resumen, construye los atributos firmados y llama al proveedor solo con el resumen.
5. Captura el fallo más específico —de gestión de claves, de algoritmo no admitido o de firma fallida—, registra un mensaje estructural sin secretos y vuelve a lanzar la excepción.

examples/pro/kms-provider-registry.php

<?php

declare(strict_types=1);

require_once __DIR__ . '/../../vendor/autoload.php';

use NextPDF\Pro\Security\Signing\Kms\KeyManagementProviderRegistry;
use NextPDF\Pro\Security\Signing\Kms\KmsSignerInterface;

/**
 * Register cloud-KMS providers behind one registry resolved by identifier.
 *
 * Each provider is supplied as a lazy factory so a provider is only
 * constructed when first resolved. The caller depends on the registry and
 * the provider contract, not on a concrete provider class.
 *
 * @param array<non-empty-string, callable(): KmsSignerInterface> $factories
 *        Provider factories keyed by provider identifier.
 *
 * @return KeyManagementProviderRegistry The populated registry.
 */
function buildKmsRegistry(array $factories): KeyManagementProviderRegistry
{
    $registry = new KeyManagementProviderRegistry();

    foreach ($factories as $providerId => $factory) {
        $registry->registerFactory($providerId, $factory);
    }

    return $registry;
}

examples/pro/kms-sign-guarded.php

<?php

declare(strict_types=1);

require_once __DIR__ . '/../../vendor/autoload.php';

use NextPDF\Pro\Security\Signing\Kms\KmsSignerInterface;
use NextPDF\Pro\Security\Exception\KeyManagementException;
use NextPDF\Pro\Security\Exception\SignatureFailedException;
use NextPDF\Pro\Security\Exception\UnsupportedAlgorithmException;
use Psr\Log\LoggerInterface;

final readonly class KmsSigningService
{
    public function __construct(
        private KmsSignerInterface $provider,
        private LoggerInterface $logger,
    ) {}

    /**
     * Sign a signed-attributes digest with a pinned key version.
     *
     * Only the digest is sent to the provider; the document stays on the
     * host. Each failure mode is caught as its most specific type so the
     * caller can distinguish a key-version problem from a transport failure.
     *
     * @param string      $digest     The signed-attributes digest to sign.
     * @param string      $algorithm  The OpenSSL-style algorithm name.
     * @param string|null $keyVersion The pinned key version, or null for the
     *                                 provider default (per-provider semantics).
     *
     * @throws KeyManagementException        When the key version is unknown or required and absent.
     * @throws UnsupportedAlgorithmException When the provider does not support the algorithm.
     * @throws SignatureFailedException      When the provider sign operation fails.
     *
     * @return string The raw signature bytes (DER for RSA and ECDSA per CMS rules).
     */
    public function sign(string $digest, string $algorithm, ?string $keyVersion): string
    {
        try {
            return $this->provider->signWithVersion($digest, $algorithm, $keyVersion);
        } catch (KeyManagementException | UnsupportedAlgorithmException | SignatureFailedException $e) {
            $this->logger->error('KMS signing failed', [
                'provider' => $this->provider->providerId(),
                'reason'   => $e->getMessage(),
            ]);

            throw $e;
        }
    }
}

Verificación

1. Confirma que el proveedor se autodescribe con el algoritmo que pretendes usar antes de firmar, de modo que un algoritmo no admitido se detecte en la selección y no en la llamada al proveedor.
2. Confirma que solo se transmite el resumen: los bytes del documento no deben aparecer en el cuerpo de la petición al proveedor. La petición lleva un resumen codificado en base64, no el archivo.
3. Para ECDSA, confirma que la firma incrustada está codificada en DER; el firmante convierte por ti una firma de par de enteros en bruto.
4. Abre el PDF firmado en un validador configurado con tus anclas de confianza y confirma que la firma se notifica como criptográficamente intacta. Una firma producida no es una firma verificada; la decisión de confianza corresponde al verificador.
5. Confirma que ningún token, credencial ni material de clave aparece en los registros de tu aplicación.

Seguridad y cumplimiento

• La clave permanece en el proveedor. Una estrategia de KMS en la nube es un punto de integración, no un almacén de claves. NextPDF Pro no custodia la clave privada para una estrategia de KMS.
• Solo el resumen cruza el límite. La sesión envía al proveedor el resumen de los atributos firmados, no el documento, según el patrón de entrada por resumen de mensaje descrito en el marco de referencia del EU DSS.
• El rango de bytes lo calcula el motor. Nunca se acepta del llamador.
• Cierre seguro ante fallos. Un fallo de proveedor, de red, de versión de clave o de algoritmo no admitido genera una excepción tipada. La sesión no produce silenciosamente un documento sin firmar y nunca sustituye por un algoritmo más débil.
• Las credenciales son secretos. Los tokens y las credenciales de entidad de servicio provienen de tu gestor de secretos y se excluyen de los registros.

Esta página concierne a la firma criptográfica. Toda fuente normativa está parafraseada; no se reproduce ningún texto normativo. ### Límite de custodia de claves

La protección de la clave depende del manejo de la clave, del KMS configurado y del despliegue. NextPDF Pro proporciona la integración con KMS, no el almacén de claves. NextPDF Pro es compatible con FIPS únicamente cuando se configura contra un KMS o HSM validado con FIPS; no es en sí mismo un módulo criptográfico validado con FIPS y no realiza ninguna afirmación de certificación FIPS.

Tratamiento de fallos

• Versión de clave desconocida o deshabilitada. El proveedor asigna una respuesta de no encontrado o de versión deshabilitada a una excepción de gestión de claves que nombra al proveedor y a la clave.
• GCP sin una versión fijada. El firmante de GCP genera un error de gestión de claves cuando ni la configuración ni la llamada suministran una versión, porque el endpoint de firma asimétrica opera únicamente sobre una versión concreta.
• Algoritmo no admitido. Solicitar un algoritmo que el proveedor no admite genera una excepción de algoritmo no admitido antes de cualquier llamada de red.
• Fallo de transporte. Un error del cliente de PSR-18 se asigna a una excepción de firma fallida; la sesión no produce un resultado parcial.
• Credencial ausente. Un firmante sin token y sin credenciales de entidad de servicio genera un error tipado en lugar de llamar al proveedor sin autenticar.

Consulta también

• Seguridad — NextPDF Pro — enmascaramiento, detección de PII y toda la superficie de firma de Pro.
• Firma con HSM — NextPDF Enterprise — custodia de claves en hardware PKCS#11.
• Firma — NextPDF Enterprise — el productor a largo plazo PAdES B-LT y B-LTA.
• Seguridad / Firma (Core) — el firmante CMS del Core y el contrato de estrategia de firma.
• KMS · CMS · ECDSA · HSM — términos del glosario.