Class Pkix

java.lang.Object
zeroecho.pkix.Pkix
public final class Pkix extends Object
The entry point of the ZeroEcho PKIX API: certificate, CSR, CRL, and OCSP builders and parsers plus content signing and verification, all in terms of standard java.security types.

All operations are delegated to a single PkixProvider, resolved once as follows: a ServiceLoader-published provider if present, else the class named by the zeroecho.pkix.provider system property, else the built-in BouncyCastle-backed provider. This keeps the concrete cryptographic toolkit an implementation detail confined to the lib module.

  • Method Details

    • provider

      public static PkixProvider provider()
      Returns the resolved PKIX provider.
      Returns:
      the active provider

    • certificateBuilder

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

    • verifyAlternativeSignature

      public static boolean verifyAlternativeSignature(X509Certificate certificate, PublicKey issuerAlternativeKey)
      Verifies a certificate's standardized alternative signature against an explicitly trusted issuer alternative key. The subject alternative key extension does not establish issuer trust. No primary signature, validity interval or certification path is validated by this method.
      Parameters:
      certificate - nonnull certificate with all three alternative extensions
      issuerAlternativeKey - nonnull expected issuer alternative public key
      Returns:
      false for absent, malformed or invalid alternative signatures
      Throws:
      NullPointerException - if an argument is null
      UnsupportedOperationException - if the provider lacks this capability

    • parseCertificate

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

    • certificationRequestBuilder

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

    • parseCertificationRequest

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

    • crlBuilder

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

    • parseCrl

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

    • ocspResponseBuilder

      public static OcspResponseBuilder ocspResponseBuilder()
      Creates an OCSP response builder.
      Returns:
      a fresh OCSP response builder

    • parseOcspRequest

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

    • signer

      public static 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; rejection precedes provider invocation

    • verifier

      public static 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

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

    • subjectKeyIdentifier

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

    • computeCertId

      public static 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
      Returns:
      the computed cert id

    • distinguishedName

      public static 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

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

    • subjectPublicKeyAlgorithm

      public static 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

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

    • parseOcspResponse

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

    • parseDistinguishedName

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

    • parseDistinguishedNameString

      public static List<RelativeDistinguishedName> parseDistinguishedNameString(String name)
      Parses a distinguished-name string 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

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

    • subjectPublicKeyInfo

      public static byte[] subjectPublicKeyInfo(X509Certificate certificate)
      Returns the exact DER of the SubjectPublicKeyInfo embedded in a certificate.
      Parameters:
      certificate - the certificate
      Returns:
      the exact SPKI DER

    • buildSubjectPublicKeyInfo

      public static 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

      public static 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

      public static 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

      public static 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.
      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

      public static byte[] assembleOcspResponse(byte[] tbsResponseData, byte[] signatureAlgorithmDer, byte[] signature)
      Reassembles a successful OCSPResponse from its tbsResponseData, a DER-encoded signature algorithm identifier, and a raw signature.
      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

      public static 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

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

    • distinguishedNameString

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

    • parseCsr

      public static CertificationRequest parseCsr(byte[] csrPemOrDer) throws CertificationRequestException
      Parses a PKCS#10 certification request from PEM or DER encoding, verifying the proof-of-possession self-signature before returning.

      PEM input is detected by the presence of a -----BEGIN header; all other input is treated as DER. Base64-encoded DER without PEM headers is also accepted via standard Base64 decoding.

      Parameters:
      csrPemOrDer - PEM or DER bytes of the certification request; must not be null
      Returns:
      the parsed and verified certification request
      Throws:
      CertificationRequestException - if the CSR cannot be parsed or its self-signature fails verification

    • encodeCertsOnly

      public static byte[] encodeCertsOnly(List<X509Certificate> chain)
      Encodes a list of X.509 certificates as a CMS certs-only message, suitable for EST /cacerts and /simpleenroll responses.
      Parameters:
      chain - ordered certificate list; must not be null or empty
      Returns:
      DER-encoded CMS ContentInfo wrapping SignedData
      Throws:
      IllegalArgumentException - if encoding fails

    • encodeCsrAttrs

      public static byte[] encodeCsrAttrs(List<CsrAttribute> attributes)
      Encodes a list of CSR attributes as an RFC 7030 CsrAttrs DER structure, suitable for EST /csrattrs responses.
      Parameters:
      attributes - the CSR attributes to encode; must not be null
      Returns:
      DER-encoded CsrAttrs sequence
      Throws:
      IllegalArgumentException - if encoding fails

    • buildServerKeygenCsr

      public static byte[] buildServerKeygenCsr(byte[] originalCsrDer, PublicKey generatedPublicKey, PrivateKey generatedPrivateKey)
      Builds a new PKCS#10 CSR using a server-generated key pair, copying the subject DN and attributes from the original CSR, for use in EST /serverkeygen.
      Parameters:
      originalCsrDer - original PKCS#10 CSR DER (source of subject and attributes)
      generatedPublicKey - server-generated public key
      generatedPrivateKey - server-generated private key
      Returns:
      new PKCS#10 CSR DER self-signed with the generated key
      Throws:
      IllegalArgumentException - if CSR construction or signing fails
      UnsupportedRoleException - if the private key uses LMS/XMSS; rejection precedes provider invocation

    • encryptPrivateKeyForRecipient

      public static 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, for use in EST /serverkeygen responses.
      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

      public static PreCertificateResult buildPreCertificate(byte[] tbsCertificateDer, List<byte[]> issuerChainDer, ContentSigner signer)
      Builds a CT pre-certificate by adding the CT poison extension to a TBSCertificate and signing it, ready for submission to CT logs.
      Parameters:
      tbsCertificateDer - DER-encoded TBSCertificate
      issuerChainDer - DER-encoded issuer chain (issuer first, root last)
      signer - configured signer for the issuing CA key
      Returns:
      pre-certificate DER and its chain
      Throws:
      IllegalArgumentException - if pre-certificate construction or signing fails

    • embedScts

      public static 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), replacing any existing CT poison or SCT list extension.
      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

      public static 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.
      Parameters:
      jsonResponseBody - raw response body bytes from the CT log; must not be null
      Returns:
      the parsed SCT
      Throws:
      IllegalArgumentException - if the JSON is malformed or the SCT structure is invalid

    • verifySct

      public static boolean verifySct(SignedCertificateTimestamp sct, PublicKey ctLogPublicKey, byte[] preCertDer)
      Verifies an SCT's digital signature against a known CT log public key.
      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, false otherwise
      Throws:
      IllegalArgumentException - if the algorithm is unsupported or the key is invalid