Przejdź do głównej zawartości
NextPDF
getnextpdf.com

Pro edycja

Podpisywanie w chmurowym KMS (AWS KMS, Azure Key Vault, GCP KMS)

W skrócie

Dział zatytułowany „W skrócie”

NextPDF Pro podpisuje plik PDF kluczem przechowywanym w chmurowej usłudze zarządzania kluczami (key-management service, KMS). Obsługiwani dostawcy to Amazon Web Services (AWS) KMS, Microsoft Azure Key Vault oraz Google Cloud Platform (GCP) Cloud KMS. Każdy dostawca implementuje jeden kontrakt podpisywania, więc aplikacja zależy od kontraktu, a nie od klasy dostawcy. Do dostawcy wysyłany jest wyłącznie skrót podpisywanych atrybutów; podczas operacji podpisywania dokument nigdy nie opuszcza hosta. Ta strona opisuje zachowanie na poziomie obserwowalnym: określa, co każdy dostawca wysyła i odbiera, jak rozstrzygane są wersje klucza oraz gdzie kończy się odpowiedzialność NextPDF za pieczę nad kluczem.

Kontrakt rozszerza kontrakt sprzętowego i chmurowego podpisującego z Core, więc strategia chmurowego KMS wpina się w tę samą ścieżkę podpisywania, z której korzysta podpisujący z Core.

Wymagania wstępne są podane we frontmatterze i powtórzone w sekcji Wymagania wstępne.

Edycja i licencjonowanie

Dział zatytułowany „Edycja i licencjonowanie”

Strategie podpisywania w chmurowym KMS są dostarczane w pakiecie nextpdf/pro i bramkowane flagą funkcji licencyjnej pro. NextPDF Core dostarcza programowy podpisujący CMS; NextPDF Enterprise dodaje sprzętową pieczę nad kluczem przez PKCS#11. Podpisywanie w chmurowym KMS to możliwość edycji Pro i jest dostępne również w Enterprise, ponieważ Enterprise zależy od Pro. Wdrożenie bez aktywnego uprawnienia Pro nie ładuje tych klas strategii; kontrakt podpisywania z Core działa dalej bez zmian. Porównaj edycje.

Co robi ta możliwość

Dział zatytułowany „Co robi ta możliwość”

Każdy podpisujący chmurowego KMS implementuje jeden kontrakt dostawcy, który rozszerza kontrakt podpisującego z Core. Kontrakt dodaje trzy rzeczy: stabilny identyfikator dostawcy na potrzeby wyszukiwania w rejestrze, metodę podpisywania uwzględniającą wersję klucza oraz samoopis algorytmów obsługiwanych przez dostawcę, dzięki czemu orchestrator może wybrać zgodnego dostawcę przed podpisaniem.

Przepływ podpisywania utrzymuje dokument na hoście:

  1. Sesja podpisywania Pro oblicza skrót dokumentu i buduje podpisywane atrybuty CMS.
  2. Sesja oblicza skrót podpisywanych atrybutów i wysyła do dostawcy wyłącznie ten skrót. Zewnętrzna usługa podpisująca, która przyjmuje dostarczony przez wywołującego skrót komunikatu (message-digest) i zwraca podpis, to ustalony wzorzec utrzymywania dokumentu wewnątrz własnej granicy, opisany w ramach referencyjnych Digital Signature Service (DSS) Unii Europejskiej.
  3. Dostawca podpisuje skrót rozstrzygniętą przez siebie wersją klucza i zwraca surowy podpis.
  4. Sesja składa strukturę CMS SignedData i osadza ją w pliku PDF.

Dostawcy są zaimplementowani na czystych wywołaniach Hypertext Transfer Protocol (HTTP) zgodnych z PSR-18 — bez zależności od zestawu narzędzi programistycznych (software development kit, SDK) żadnego dostawcy chmury. Uwierzytelnianie jest delegowane do aplikacji: dostarczasz token nośny (AWS, GCP) albo token lub poświadczenie jednostki usługowej (service principal) (Azure). Każdy dostawca normalizuje swoje wyjście pod kątem CMS: AWS i GCP zwracają podpisy Rivest–Shamir–Adleman (RSA) w postaci DER gotowej dla CMS; podpis Elliptic Curve Digital Signature Algorithm (ECDSA), który dostawca zwraca jako surową parę liczb całkowitych (Azure), jest konwertowany do postaci zakodowanej w DER, podczas gdy GCP zwraca ECDSA już zakodowany w DER. Krzywa i skrót ECDSA są parowane konwencjonalnie — P-256 z SHA-256, P-384 z SHA-384, P-521 z SHA-512 — zgodnie z zalecanym parowaniem w RFC 5480.

Rejestr PSR-11 rozstrzyga dostawców po identyfikatorze i obsługuje leniwe fabryki. Klienci Enterprise hostujący samodzielnie rejestrują własny sterownik HSM lub KMS, implementując kontrakt dostawcy i wiążąc go w rejestrze — bez forkowania NextPDF Pro.

Semantyka wersji klucza zależna od dostawcy

Dział zatytułowany „Semantyka wersji klucza zależna od dostawcy”

Dostawcy udostępniają różne prymitywy „aktywnej wersji”, dlatego domyślne zachowanie wersji klucza jest różne:

  • AWS KMS — wersja klucza null korzysta z aliasu klucza, który AWS rozstrzyga do bieżącej wersji klucza po stronie dostawcy.
  • Azure Key Vault — wersja klucza null korzysta z adresu URL klucza bez wersji, który Azure rozstrzyga do najnowszej włączonej wersji. Jawne nadpisanie musi być 32-znakowym identyfikatorem szesnastkowym; każda inna wartość jest odrzucana, aby zapobiec wstrzyknięciu segmentu URL.
  • GCP Cloud KMS — punkt końcowy podpisu asymetrycznego działa wyłącznie na konkretnej wersji klucza kryptograficznego; nie ma „aktywnej wersji” po stronie serwera. Musisz przypiąć wersję w konfiguracji lub przekazać ją jawnie. Gdy żadna z nich nie jest ustawiona, podpisujący zgłasza błąd zarządzania kluczem, zamiast zgadywać.

Udokumentuj, którego trybu używa twoje wdrożenie, aby zachowanie było deterministyczne.

Wymagania wstępne

Dział zatytułowany „Wymagania wstępne”
  1. Zainstaluj NextPDF Core oraz pakiet Pro i miej aktywną licencję Pro.
  2. Zaprowizjonuj klucz podpisujący u wybranego dostawcy i zanotuj jego identyfikatory (alias klucza lub Amazon Resource Name dla AWS; magazyn i nazwa klucza dla Azure; projekt, lokalizacja, pęk kluczy, klucz kryptograficzny i wersja dla GCP).
  3. Dostarcz klienta HTTP zgodnego z PSR-18 oraz fabryki żądań i strumieni PSR-17.
  4. Uzyskaj poświadczenie dostawcy w swojej aplikacji: token nośny dla AWS lub GCP albo wcześniej uzyskany token lub poświadczenia jednostki usługowej dla Azure. Pozyskanie tokenu należy do aplikacji; dostarczaj sekrety z menedżera sekretów, nigdy ze źródła.

Konfiguracja

Dział zatytułowany „Konfiguracja”

Każdy dostawca ma niezmienialny obiekt konfiguracji zbudowany z twoich identyfikatorów i poświadczeń. Wspólne kwestie konfiguracyjne:

  • Identyfikator dostawcy — aws-kms, azure-keyvault lub gcp-kms, używany jako klucz wyszukiwania w rejestrze.
  • Algorytm — wybierany na wywołanie z nazwy algorytmu przekazanej przez sesję podpisywania; dostawca odrzuca algorytm, którego nie obsługuje.
  • Wersja klucza — przypięta w konfiguracji lub przekazywana na wywołanie, z opisaną wyżej semantyką zależną od dostawcy.
  • Poświadczenie — token nośny lub poświadczenia jednostki usługowej dostarczane przez aplikację z jej menedżera sekretów.

Krok po kroku

Dział zatytułowany „Krok po kroku”
  1. Zbuduj konfigurację dostawcy z twoich identyfikatorów i poświadczenia odczytanego z menedżera sekretów.
  2. Skonstruuj podpisującego dostawcy z konfiguracją, certyfikatem podpisującego w postaci DER, łańcuchem, klientem PSR-18 oraz fabrykami PSR-17.
  3. Opcjonalnie zarejestruj dostawcę w rejestrze PSR-11 pod jego identyfikatorem, aby orchestrator rozstrzygał go po nazwie.
  4. Uruchom sesję podpisywania Pro: oblicza ona skrót, buduje podpisywane atrybuty i wywołuje dostawcę wyłącznie ze skrótem.
  5. Przechwyć najbardziej szczegółowy błąd — zarządzania kluczem, nieobsługiwanego algorytmu lub nieudanego podpisu — zaloguj komunikat strukturalny bez sekretów i wyrzuć go ponownie.
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;
        }
    }
}

Weryfikacja

Dział zatytułowany „Weryfikacja”
  1. Potwierdź, że dostawca samoopisuje algorytm, którego zamierzasz użyć, przed podpisaniem, aby nieobsługiwany algorytm został wychwycony na etapie wyboru, a nie przy wywołaniu dostawcy.
  2. Potwierdź, że przesyłany jest wyłącznie skrót: bajty dokumentu nie mogą pojawić się w ciele żądania do dostawcy. Żądanie niesie skrót zakodowany w base64, a nie plik.
  3. Dla ECDSA potwierdź, że osadzony podpis jest zakodowany w DER — podpisujący konwertuje za ciebie podpis będący surową parą liczb całkowitych.
  4. Otwórz podpisany plik PDF w walidatorze skonfigurowanym z twoimi kotwicami zaufania i potwierdź, że podpis jest raportowany jako kryptograficznie nienaruszony. Wytworzony podpis to nie zweryfikowany podpis; decyzja o zaufaniu należy do weryfikatora.
  5. Potwierdź, że w logach aplikacji nie pojawia się żaden token, poświadczenie ani materiał klucza.

Bezpieczeństwo i zgodność

Dział zatytułowany „Bezpieczeństwo i zgodność”
  • Klucz pozostaje u dostawcy. Strategia chmurowego KMS to punkt integracji, a nie magazyn kluczy. NextPDF Pro nie przechowuje klucza prywatnego dla strategii KMS.
  • Granicę przekracza wyłącznie skrót. Sesja wysyła do dostawcy skrót podpisywanych atrybutów, a nie dokument — to wzorzec wejścia skrótu komunikatu opisany w ramach referencyjnych EU DSS.
  • Zakres bajtów oblicza silnik. Nigdy nie jest on przyjmowany od wywołującego.
  • Bezpieczna awaria (fail-closed). Awaria dostawcy, sieci, wersji klucza lub nieobsługiwanego algorytmu zgłasza wyjątek typowany. Sesja nie wytwarza po cichu niepodpisanego dokumentu i nigdy nie zastępuje algorytmu słabszym.
  • Poświadczenia to sekrety. Tokeny i poświadczenia jednostki usługowej pochodzą z twojego menedżera sekretów i są wykluczone z logów.

Ta strona dotyczy podpisywania kryptograficznego. Każde źródło normatywne jest parafrazowane; żaden tekst normatywny nie jest odtwarzany. ### Granica pieczy nad kluczem

Ochrona klucza zależy od obsługi klucza, skonfigurowanego KMS oraz wdrożenia. NextPDF Pro zapewnia integrację z KMS, a nie magazyn kluczy. NextPDF Pro jest zgodny z FIPS tylko wtedy, gdy jest skonfigurowany względem KMS lub HSM walidowanego zgodnie z FIPS; sam w sobie nie jest modułem kryptograficznym walidowanym zgodnie z FIPS i nie formułuje żadnego twierdzenia o certyfikacji FIPS.

Obsługa awarii

Dział zatytułowany „Obsługa awarii”
  • Nieznana lub wyłączona wersja klucza. Dostawca mapuje odpowiedź „nie znaleziono” lub „wersja wyłączona” na wyjątek zarządzania kluczem, który nazywa dostawcę i klucz.
  • GCP bez przypiętej wersji. Podpisujący GCP zgłasza błąd zarządzania kluczem, gdy ani konfiguracja, ani wywołanie nie dostarczają wersji, ponieważ punkt końcowy podpisu asymetrycznego działa wyłącznie na konkretnej wersji.
  • Nieobsługiwany algorytm. Zażądanie algorytmu, którego dostawca nie obsługuje, zgłasza wyjątek nieobsługiwanego algorytmu przed jakimkolwiek wywołaniem sieciowym.
  • Awaria transportu. Błąd klienta PSR-18 jest mapowany na wyjątek nieudanego podpisu; sesja nie wytwarza częściowego wyniku.
  • Brak poświadczenia. Podpisujący bez tokenu i bez poświadczeń jednostki usługowej zgłasza błąd typowany, zamiast wywoływać dostawcę bez uwierzytelnienia.

Zobacz też

Dział zatytułowany „Zobacz też”