Interface PkixProvider

All Known Implementing Classes:
BcPkixProvider
public interface PkixProvider
The service-provider contract that backs the ZeroEcho PKIX API.

A provider supplies the concrete builders, parsers, and signing operators. The default provider is implemented with BouncyCastle and is confined to the lib module; a JDK-only or in-house provider can replace it in future without any change to the public zeroecho.pkix API. Providers are resolved by Pkix.

  • Method Details

    • verifyAlternativeSignature

      default boolean verifyAlternativeSignature(X509Certificate certificate, PublicKey issuerAlternativeKey)
      Verifies only the standardized alternative signature using an explicit issuer alternative key. Missing or malformed alternative extensions fail closed. This operation performs no path, time or primary-signature checks.
      Parameters:
      certificate - nonnull certificate with all three alternative extensions
      issuerAlternativeKey - nonnull trusted issuer alternative public key
      Returns:
      whether the alternative signature is valid
      Throws:
      UnsupportedOperationException - if unsupported by this provider

    • id

      String id()
      Returns the stable provider identifier (for diagnostics and selection).
      Returns:
      the provider id

    • certificateBuilder

      CertificateBuilder certificateBuilder()
      Creates a new certificate builder.
      Returns:
      a fresh certificate builder

    • parseCertificate

      X509Certificate parseCertificate(byte[] der)
      Parses a DER-encoded X.509 certificate.
      Parameters:
      der - the certificate DER
      Returns:
      the parsed certificate

    • certificationRequestBuilder

      CertificationRequestBuilder certificationRequestBuilder()
      Creates a new certification-request builder.
      Returns:
      a fresh CSR builder

    • parseCertificationRequest

      CertificationRequest parseCertificationRequest(byte[] der)
      Parses a DER-encoded PKCS#10 certification request.
      Parameters:
      der - the request DER
      Returns:
      the parsed request

    • crlBuilder

      CrlBuilder crlBuilder()
      Creates a new CRL builder.
      Returns:
      a fresh CRL builder

    • parseCrl

      X509CRL parseCrl(byte[] der)
      Parses a DER-encoded X.509 CRL.
      Parameters:
      der - the CRL DER
      Returns:
      the parsed CRL

    • ocspResponseBuilder

      OcspResponseBuilder ocspResponseBuilder()
      Creates a new OCSP response builder.
      Returns:
      a fresh OCSP response builder

    • parseOcspRequest

      OcspRequest parseOcspRequest(byte[] der)
      Parses a DER-encoded OCSP request.
      Parameters:
      der - the request DER
      Returns:
      the parsed request

    • signer

      ContentSigner signer(PrivateKey privateKey, AlgorithmIdentifier algorithm)
      Creates a content signer over a local private key.
      Parameters:
      privateKey - the signing private key
      algorithm - the signature algorithm identifier
      Returns:
      a content signer
      Throws:
      UnsupportedRoleException - if LMS/XMSS signing is requested; implementations must reject before key use

    • verifier

      ContentVerifier verifier(PublicKey publicKey, AlgorithmIdentifier algorithm)
      Creates a content verifier over a public key.
      Parameters:
      publicKey - the verifying public key
      algorithm - the signature algorithm identifier
      Returns:
      a content verifier

    • verifier

      ContentVerifier verifier(byte[] subjectPublicKeyInfoDer, AlgorithmIdentifier algorithm)
      Creates a content verifier over a DER-encoded SubjectPublicKeyInfo and a signature algorithm identifier, honouring any algorithm parameters (such as RSASSA-PSS parameters) carried by the identifier.
      Parameters:
      subjectPublicKeyInfoDer - the SPKI DER of the verifying key
      algorithm - the signature algorithm identifier
      Returns:
      a content verifier

    • subjectKeyIdentifier

      byte[] subjectKeyIdentifier(PublicKey publicKey)
      Computes the standard subject key identifier (SHA-1 of the SPKI) for a key.
      Parameters:
      publicKey - the public key
      Returns:
      the subject key identifier bytes

    • computeCertId

      CertId computeCertId(X509Certificate issuer, BigInteger serialNumber, String digestAlgorithmOid)
      Computes an OCSP CertId for a certificate under a given issuer.
      Parameters:
      issuer - the issuer certificate
      serialNumber - the subject certificate serial number
      digestAlgorithmOid - the digest algorithm OID for the hashes
      Returns:
      the computed cert id

    • distinguishedName

      X500Principal distinguishedName(List<RelativeDistinguishedName> relativeNames)
      Builds a byte-exact distinguished name from typed relative distinguished names.
      Parameters:
      relativeNames - the ordered relative distinguished names
      Returns:
      the distinguished name

    • parseAlgorithmIdentifier

      AlgorithmIdentifier parseAlgorithmIdentifier(byte[] der)
      Parses a DER-encoded X.509 AlgorithmIdentifier.
      Parameters:
      der - the algorithm-identifier DER
      Returns:
      the parsed algorithm identifier

    • subjectPublicKeyAlgorithm

      AlgorithmIdentifier subjectPublicKeyAlgorithm(byte[] subjectPublicKeyInfoDer)
      Extracts the algorithm identifier from a DER-encoded SubjectPublicKeyInfo.
      Parameters:
      subjectPublicKeyInfoDer - the SPKI DER
      Returns:
      the subject public key algorithm identifier

    • publicKeyFromSubjectPublicKeyInfo

      PublicKey publicKeyFromSubjectPublicKeyInfo(byte[] subjectPublicKeyInfoDer)
      Recovers a public key from a DER-encoded SubjectPublicKeyInfo.
      Parameters:
      subjectPublicKeyInfoDer - the SPKI DER
      Returns:
      the public key

    • parseOcspResponse

      OcspResponse parseOcspResponse(byte[] der)
      Parses a DER-encoded OCSP response.
      Parameters:
      der - the response DER
      Returns:
      the parsed response

    • parseDistinguishedName

      List<RelativeDistinguishedName> parseDistinguishedName(byte[] nameDer)
      Parses a DER-encoded X.500 Name into its ordered, single-valued relative distinguished names, preserving the ASN.1 string type of each value.
      Parameters:
      nameDer - the DER encoding of an X.500 Name
      Returns:
      the ordered relative distinguished names

    • parseDistinguishedNameString

      List<RelativeDistinguishedName> parseDistinguishedNameString(String name)
      Parses a distinguished-name string (as produced by distinguishedNameString(java.util.List)) into its ordered, single-valued relative distinguished names, preserving the written order.
      Parameters:
      name - the distinguished-name string
      Returns:
      the ordered relative distinguished names

    • subjectPublicKeyBytes

      byte[] subjectPublicKeyBytes(byte[] subjectPublicKeyInfoDer)
      Returns the raw contents of the public-key BIT STRING of a DER-encoded SubjectPublicKeyInfo (the bytes after the unused-bits octet).
      Parameters:
      subjectPublicKeyInfoDer - the SPKI DER
      Returns:
      the public-key bit-string content bytes

    • subjectPublicKeyInfo

      byte[] subjectPublicKeyInfo(X509Certificate certificate)
      Returns the exact DER of the SubjectPublicKeyInfo embedded in a certificate, byte-for-byte as encoded in the certificate.
      Parameters:
      certificate - the certificate
      Returns:
      the exact SPKI DER

    • buildSubjectPublicKeyInfo

      byte[] buildSubjectPublicKeyInfo(AlgorithmIdentifier algorithm, byte[] publicKeyBits)
      Builds the DER of a SubjectPublicKeyInfo from an algorithm identifier and the raw public-key BIT STRING contents.
      Parameters:
      algorithm - the subject public-key algorithm identifier
      publicKeyBits - the raw public-key bit-string content bytes
      Returns:
      the SPKI DER

    • parseExtensions

      List<CertificateExtension> parseExtensions(byte[] der)
      Parses a DER-encoded X.509 Extensions sequence into typed extensions.
      Parameters:
      der - the DER of an Extensions sequence
      Returns:
      the parsed extensions in order

    • parseGeneralNames

      List<GeneralName> parseGeneralNames(byte[] der)
      Parses a DER-encoded GeneralNames sequence into typed general names.
      Parameters:
      der - the DER of a GeneralNames sequence
      Returns:
      the parsed general names in order

    • assembleCertificateOrCrl

      byte[] assembleCertificateOrCrl(byte[] tbs, byte[] signature, boolean crl)
      Reassembles a signed certificate or CRL from its tbs bytes and a raw signature, repeating the algorithm identifier embedded in the tbs as the outer signatureAlgorithm, and validates that the result parses.
      Parameters:
      tbs - the tbsCertificate or tbsCertList DER
      signature - the raw signature bytes
      crl - true for a CRL, false for a certificate
      Returns:
      the DER of the assembled signed object

    • assembleOcspResponse

      byte[] assembleOcspResponse(byte[] tbsResponseData, byte[] signatureAlgorithmDer, byte[] signature)
      Reassembles a successful OCSPResponse wrapping a BasicOCSPResponse from its tbsResponseData, a DER-encoded signature algorithm identifier, and a raw signature, and validates that the result parses as successful.
      Parameters:
      tbsResponseData - the tbsResponseData DER
      signatureAlgorithmDer - the DER of the signature AlgorithmIdentifier
      signature - the raw signature bytes
      Returns:
      the DER of the assembled OCSP response

    • assembleOcspResponse

      byte[] assembleOcspResponse(byte[] tbsResponseData, byte[] signatureAlgorithmDer, byte[] signature, List<X509Certificate> chain)
      Reassembles a successful OCSP response from unsigned ResponseData, an encoded signature algorithm, a raw signature and an ordered certificate chain. Certificates are embedded in the supplied order without sorting or trust validation. An empty chain omits the optional certs field, matching the three-argument overload. No signer is invoked and the raw signature is not cryptographically verified by assembly.

      Inputs remain caller-owned and are not retained. The returned DER array is independent. Time and auxiliary memory are linear in response-data, algorithm, signature and total embedded-certificate bytes. No aggregate live-response size limit is introduced.

      Parameters:
      tbsResponseData - nonnull DER-encoded unsigned ResponseData
      signatureAlgorithmDer - nonnull DER-encoded signature AlgorithmIdentifier
      signature - nonnull raw signature bytes
      chain - nonnull certificate list in exact embedding order, with no null elements
      Returns:
      freshly encoded successful OCSP response DER
      Throws:
      NullPointerException - if an argument or a chain element is null
      IllegalArgumentException - if DER parsing or certificate encoding fails

    • encodeAlgorithmIdentifier

      byte[] encodeAlgorithmIdentifier(AlgorithmIdentifier algorithm)
      Returns the DER encoding of an X.509 AlgorithmIdentifier.
      Parameters:
      algorithm - the algorithm identifier
      Returns:
      the DER encoding

    • distinguishedNameString

      String distinguishedNameString(List<RelativeDistinguishedName> relativeNames)
      Renders a distinguished name, built from typed relative distinguished names, as its canonical string form (attribute short names, most-significant first).
      Parameters:
      relativeNames - the ordered relative distinguished names
      Returns:
      the string form of the distinguished name

    • encodeCertsOnly

      byte[] encodeCertsOnly(List<X509Certificate> chain)
      Encodes a list of X.509 certificates as a CMS certs-only message (SignedData with no signers, only the certificate bag).

      The returned bytes are the DER-encoded ContentInfo wrapping the SignedData. The encoding is suitable for use as the body of an EST /cacerts or /simpleenroll response.

      Parameters:
      chain - ordered certificate list; must not be null or empty
      Returns:
      DER-encoded CMS certs-only ContentInfo
      Throws:
      IllegalArgumentException - if encoding fails

    • encodeCsrAttrs

      byte[] encodeCsrAttrs(List<CsrAttribute> attributes)
      Encodes a list of CSR attributes as an RFC 7030 CsrAttrs structure (DER-encoded ASN.1 sequence of OIDs and optional attribute values).
      Parameters:
      attributes - the CSR attributes to encode; must not be null
      Returns:
      DER-encoded CsrAttrs sequence
      Throws:
      IllegalArgumentException - if encoding fails

    • buildServerKeygenCsr

      byte[] buildServerKeygenCsr(byte[] originalCsrDer, PublicKey generatedPublicKey, PrivateKey generatedPrivateKey)
      Builds a new DER-encoded PKCS#10 CSR using the supplied generated key pair, copying the subject DN and all attributes from the original CSR.

      The self-signature over the rebuilt CSR uses SHA-256withECDSA for EC keys and SHA-256withRSA for RSA keys, determined from the generated private key type.

      Parameters:
      originalCsrDer - DER-encoded original PKCS#10 CSR (source of subject and attributes)
      generatedPublicKey - server-generated public key to embed
      generatedPrivateKey - server-generated private key used to self-sign
      Returns:
      DER-encoded PKCS#10 CSR signed with the generated key
      Throws:
      IllegalArgumentException - if CSR construction or signing fails
      UnsupportedRoleException - if the private key uses LMS/XMSS; implementations must reject before parsing the CSR or using the key

    • encryptPrivateKeyForRecipient

      byte[] encryptPrivateKeyForRecipient(byte[] pkcs8PrivateKeyDer, X509Certificate recipientCertificate)
      Encrypts a PKCS#8 private key for a single recipient using CMS EnvelopedData with AES-256-GCM content encryption.

      The recipient is identified by the public key in the supplied certificate. The key is wrapped using RSA-OAEP (for RSA keys) or ECDH-KDF (for EC keys) depending on the recipient certificate's public key algorithm.

      Parameters:
      pkcs8PrivateKeyDer - DER-encoded PKCS#8 private key to encrypt
      recipientCertificate - the recipient's certificate (public key used for wrap)
      Returns:
      DER-encoded CMS ContentInfo wrapping the EnvelopedData
      Throws:
      IllegalArgumentException - if encryption fails

    • buildPreCertificate

      PreCertificateResult buildPreCertificate(byte[] tbsCertificateDer, List<byte[]> issuerChainDer, ContentSigner signer)
      Builds a CT pre-certificate from an existing TBSCertificate by adding the CT poison extension (OID 1.3.6.1.4.1.11129.2.4.3) and signing with the supplied signer.

      The pre-certificate is submitted to CT logs; logs return SCTs that are later embedded in the final certificate via embedScts(byte[], List).

      Parameters:
      tbsCertificateDer - DER-encoded TBSCertificate without the poison extension
      issuerChainDer - DER-encoded issuer chain (issuer first, root last)
      signer - configured signer for the issuing CA key
      Returns:
      pre-certificate DER and its chain, ready for CT log submission
      Throws:
      IllegalArgumentException - if pre-certificate construction or signing fails

    • embedScts

      byte[] embedScts(byte[] tbsCertificateDer, List<SignedCertificateTimestamp> scts)
      Embeds a list of SCTs into a TBSCertificate as the SCT list extension (OID 1.3.6.1.4.1.11129.2.4.2), producing a modified TBSCertificate DER ready for final signing.

      If the TBSCertificate already carries a poison extension (OID 1.3.6.1.4.1.11129.2.4.3), it is replaced by the SCT list extension. Any pre-existing SCT list extension is also replaced.

      Parameters:
      tbsCertificateDer - DER-encoded TBSCertificate
      scts - verified SCTs to embed; must contain at least one entry
      Returns:
      modified DER-encoded TBSCertificate with the SCT list extension
      Throws:
      IllegalArgumentException - if embedding fails

    • parseSct

      SignedCertificateTimestamp parseSct(byte[] jsonResponseBody)
      Parses a Signed Certificate Timestamp from the JSON response body returned by a CT log's add-pre-chain or add-chain endpoint.

      Expected JSON fields: sct_version, id (base64 log ID), timestamp (epoch milliseconds), extensions (base64, may be empty), signature (base64-encoded TLS DigitallySigned structure).

      Parameters:
      jsonResponseBody - raw response body bytes; must not be null
      Returns:
      the parsed SCT
      Throws:
      IllegalArgumentException - if the JSON is malformed or the SCT structure is invalid

    • verifySct

      boolean verifySct(SignedCertificateTimestamp sct, PublicKey ctLogPublicKey, byte[] preCertDer)
      Verifies an SCT's digital signature against a known CT log public key.

      The signed data covers the SCT fields (version, log ID, timestamp, extensions) concatenated with a SHA-256 hash of the pre-certificate DER, as a simplified verification approach. Returns false if the signature is invalid; throws only on algorithmic or key errors.

      Parameters:
      sct - the SCT to verify; must not be null
      ctLogPublicKey - EC or RSA public key of the CT log; must not be null
      preCertDer - DER-encoded pre-certificate that was submitted; must not be null
      Returns:
      true if the signature is valid
      Throws:
      IllegalArgumentException - if the algorithm is unsupported or the key is invalid