Package com.unboundid.util.ssl.cert

Class X509Certificate

java.lang.Object
com.unboundid.util.ssl.cert.X509Certificate
All Implemented Interfaces:
Serializable
@NotMutable @ThreadSafety(level=COMPLETELY_THREADSAFE) public final class X509Certificate extends Object implements Serializable
This class provides support for decoding an X.509 certificate as defined in RFC 5280. The certificate is encoded using the ASN.1 Distinguished Encoding Rules (DER), which is a subset of BER, and is supported by the code in the com.unboundid.asn1 package. The ASN.1 specification is as follows: 
   Certificate  ::=  SEQUENCE  {
        tbsCertificate       TBSCertificate,
        signatureAlgorithm   AlgorithmIdentifier,
        signatureValue       BIT STRING  }

   TBSCertificate  ::=  SEQUENCE  {
        version         [0]  EXPLICIT Version DEFAULT v1,
        serialNumber         CertificateSerialNumber,
        signature            AlgorithmIdentifier,
        issuer               Name,
        validity             Validity,
        subject              Name,
        subjectPublicKeyInfo SubjectPublicKeyInfo,
        issuerUniqueID  [1]  IMPLICIT UniqueIdentifier OPTIONAL,
                             -- If present, version MUST be v2 or v3
        subjectUniqueID [2]  IMPLICIT UniqueIdentifier OPTIONAL,
                             -- If present, version MUST be v2 or v3
        extensions      [3]  EXPLICIT Extensions OPTIONAL
                             -- If present, version MUST be v3
        }

   Version  ::=  INTEGER  {  v1(0), v2(1), v3(2)  }

   CertificateSerialNumber  ::=  INTEGER

   Validity ::= SEQUENCE {
        notBefore      Time,
        notAfter       Time }

   Time ::= CHOICE {
        utcTime        UTCTime,
        generalTime    GeneralizedTime }

   UniqueIdentifier  ::=  BIT STRING

   SubjectPublicKeyInfo  ::=  SEQUENCE  {
        algorithm            AlgorithmIdentifier,
        subjectPublicKey     BIT STRING  }

   Extensions  ::=  SEQUENCE SIZE (1..MAX) OF Extension

   Extension  ::=  SEQUENCE  {
        extnID      OBJECT IDENTIFIER,
        critical    BOOLEAN DEFAULT FALSE,
        extnValue   OCTET STRING
                    -- contains the DER encoding of an ASN.1 value
                    -- corresponding to the extension type identified
                    -- by extnID
        }

   AlgorithmIdentifier  ::=  SEQUENCE  {
        algorithm               OBJECT IDENTIFIER,
        parameters              ANY DEFINED BY algorithm OPTIONAL  }

   Name ::= CHOICE { -- only one possibility for now --
     rdnSequence  RDNSequence }

   RDNSequence ::= SEQUENCE OF RelativeDistinguishedName

   RelativeDistinguishedName ::=
     SET SIZE (1..MAX) OF AttributeTypeAndValue

   AttributeTypeAndValue ::= SEQUENCE {
     type     AttributeType,
     value    AttributeValue }

   AttributeType ::= OBJECT IDENTIFIER

   AttributeValue ::= ANY -- DEFINED BY AttributeType
See Also:

  • Constructor Details

    • X509Certificate

      public X509Certificate(@NotNull byte[] encodedCertificate) throws CertException
      Decodes the contents of the provided byte array as an X.509 certificate.
      Parameters:
      encodedCertificate - The byte array containing the encoded X.509 certificate. This must not be null.
      Throws:
      CertException - If the contents of the provided byte array could not be decoded as a valid X.509 certificate.

  • Method Details

    • generateSelfSignedCertificate

      @NotNull public static ObjectPair<X509Certificate,KeyPair> generateSelfSignedCertificate(@NotNull SignatureAlgorithmIdentifier signatureAlgorithm, @NotNull PublicKeyAlgorithmIdentifier publicKeyAlgorithm, int keySizeBits, @NotNull DN subjectDN, long notBefore, long notAfter, @Nullable X509CertificateExtension... extensions) throws CertException
      Generates a self-signed X.509 certificate with the provided information.
      Parameters:
      signatureAlgorithm - The algorithm to use to generate the signature. This must not be null.
      publicKeyAlgorithm - The algorithm to use to generate the key pair. This must not be null.
      keySizeBits - The size of the key to generate, in bits.
      subjectDN - The subject DN for the certificate. This must not be null.
      notBefore - The validity start time for the certificate.
      notAfter - The validity end time for the certificate.
      extensions - The set of extensions to include in the certificate. This may be null or empty if the certificate should not include any custom extensions. Note that the generated certificate will automatically include a SubjectKeyIdentifierExtension, so that should not be provided.
      Returns:
      An ObjectPair that contains both the self-signed certificate and its corresponding key pair.
      Throws:
      CertException - If a problem is encountered while creating the certificate.

    • generateSelfSignedCertificate

      @NotNull public static X509Certificate generateSelfSignedCertificate(@NotNull SignatureAlgorithmIdentifier signatureAlgorithm, @NotNull KeyPair keyPair, @NotNull DN subjectDN, long notBefore, long notAfter, @Nullable X509CertificateExtension... extensions) throws CertException
      Generates a self-signed X.509 certificate with the provided information.
      Parameters:
      signatureAlgorithm - The algorithm to use to generate the signature. This must not be null.
      keyPair - The key pair for the certificate. This must not be null.
      subjectDN - The subject DN for the certificate. This must not be null.
      notBefore - The validity start time for the certificate.
      notAfter - The validity end time for the certificate.
      extensions - The set of extensions to include in the certificate. This may be null or empty if the certificate should not include any custom extensions. Note that the generated certificate will automatically include a SubjectKeyIdentifierExtension, so that should not be provided.
      Returns:
      An ObjectPair that contains both the self-signed certificate and its corresponding key pair.
      Throws:
      CertException - If a problem is encountered while creating the certificate.

    • generateIssuerSignedCertificate

      @NotNull public static X509Certificate generateIssuerSignedCertificate(@NotNull SignatureAlgorithmIdentifier signatureAlgorithm, @NotNull X509Certificate issuerCertificate, @NotNull PrivateKey issuerPrivateKey, @NotNull OID publicKeyAlgorithmOID, @Nullable ASN1Element publicKeyAlgorithmParameters, @NotNull ASN1BitString encodedPublicKey, @Nullable DecodedPublicKey decodedPublicKey, @NotNull DN subjectDN, long notBefore, long notAfter, @NotNull X509CertificateExtension... extensions) throws CertException
      Generates an issuer-signed X.509 certificate with the provided information.
      Parameters:
      signatureAlgorithm - The algorithm to use to generate the signature. This must not be null.
      issuerCertificate - The certificate for the issuer. This must not be null.
      issuerPrivateKey - The private key for the issuer. This must not be null.
      publicKeyAlgorithmOID - The OID for the certificate's public key algorithm. This must not be null.
      publicKeyAlgorithmParameters - The encoded public key algorithm parameters for the certificate. This may be null if there are no parameters.
      encodedPublicKey - The encoded public key for the certificate. This must not be null.
      decodedPublicKey - The decoded public key for the certificate. This may be null if it is not available.
      subjectDN - The subject DN for the certificate. This must not be null.
      notBefore - The validity start time for the certificate.
      notAfter - The validity end time for the certificate.
      extensions - The set of extensions to include in the certificate. This may be null or empty if the certificate should not include any custom extensions. Note that the generated certificate will automatically include a SubjectKeyIdentifierExtension, so that should not be provided. In addition, if the issuer certificate includes its own SubjectKeyIdentifierExtension, then its value will be used to generate an AuthorityKeyIdentifierExtension.
      Returns:
      The issuer-signed certificate.
      Throws:
      CertException - If a problem is encountered while creating the certificate.

    • getX509CertificateBytes

      @NotNull public byte[] getX509CertificateBytes()
      Retrieves the bytes that comprise the encoded representation of this X.509 certificate.
      Returns:
      The bytes that comprise the encoded representation of this X.509 certificate.

    • getVersion

      @NotNull public X509CertificateVersion getVersion()
      Retrieves the certificate version.
      Returns:
      The certificate version.

    • getSerialNumber

      @NotNull public BigInteger getSerialNumber()
      Retrieves the certificate serial number.
      Returns:
      The certificate serial number.

    • getSignatureAlgorithmOID

      @NotNull public OID getSignatureAlgorithmOID()
      Retrieves the certificate signature algorithm OID.
      Returns:
      The certificate signature algorithm OID.

    • getSignatureAlgorithmName

      @Nullable public String getSignatureAlgorithmName()
      Retrieves the certificate signature algorithm name, if available.
      Returns:
      The certificate signature algorithm name, or null if the signature algorithm OID does not correspond to any known algorithm name.

    • getSignatureAlgorithmNameOrOID

      @NotNull public String getSignatureAlgorithmNameOrOID()
      Retrieves the signature algorithm name if it is available, or the string representation of the signature algorithm OID if not.
      Returns:
      The signature algorithm name or OID.

    • getSignatureAlgorithmParameters

      @Nullable public ASN1Element getSignatureAlgorithmParameters()
      Retrieves the encoded signature algorithm parameters, if present.
      Returns:
      The encoded signature algorithm parameters, or null if there are no signature algorithm parameters.

    • getIssuerDN

      @NotNull public DN getIssuerDN()
      Retrieves the certificate issuer DN.
      Returns:
      The certificate issuer DN.

    • getNotBeforeTime

      public long getNotBeforeTime()
      Retrieves the certificate validity start time as the number of milliseconds since the epoch (January 1, 1970 UTC).
      Returns:
      The certificate validity start time as the number of milliseconds since the epoch.

    • getNotBeforeDate

      @NotNull public Date getNotBeforeDate()
      Retrieves the certificate validity start time as a Date.
      Returns:
      The certificate validity start time as a Date.

    • getNotAfterTime

      public long getNotAfterTime()
      Retrieves the certificate validity end time as the number of milliseconds since the epoch (January 1, 1970 UTC).
      Returns:
      The certificate validity end time as the number of milliseconds since the epoch.

    • getNotAfterDate

      @NotNull public Date getNotAfterDate()
      Retrieves the certificate validity end time as a Date.
      Returns:
      The certificate validity end time as a Date.

    • isWithinValidityWindow

      public boolean isWithinValidityWindow()
      Indicates whether the current time is within the certificate's validity window.
      Returns:
      true if the current time is within the certificate's validity window, or false if not.

    • isWithinValidityWindow

      public boolean isWithinValidityWindow(@NotNull Date date)
      Indicates whether the provided Date represents a time within the certificate's validity window.
      Parameters:
      date - The Date for which to make the determination. It must not be null.
      Returns:
      true if the provided Date is within the certificate's validity window, or false if not.

    • isWithinValidityWindow

      public boolean isWithinValidityWindow(long time)
      Indicates whether the specified time is within the certificate's validity window.
      Parameters:
      time - The time to for which to make the determination.
      Returns:
      true if the specified time is within the certificate's validity window, or false if not.

    • getSubjectDN

      @NotNull public DN getSubjectDN()
      Retrieves the certificate subject DN.
      Returns:
      The certificate subject DN.

    • getPublicKeyAlgorithmOID

      @NotNull public OID getPublicKeyAlgorithmOID()
      Retrieves the certificate public key algorithm OID.
      Returns:
      The certificate public key algorithm OID.

    • getPublicKeyAlgorithmName

      @Nullable public String getPublicKeyAlgorithmName()
      Retrieves the certificate public key algorithm name, if available.
      Returns:
      The certificate public key algorithm name, or null if the public key algorithm OID does not correspond to any known algorithm name.

    • getPublicKeyAlgorithmNameOrOID

      @NotNull public String getPublicKeyAlgorithmNameOrOID()
      Retrieves the public key algorithm name if it is available, or the string representation of the public key algorithm OID if not.
      Returns:
      The signature algorithm name or OID.

    • getPublicKeyAlgorithmParameters

      @Nullable public ASN1Element getPublicKeyAlgorithmParameters()
      Retrieves the encoded public key algorithm parameters, if present.
      Returns:
      The encoded public key algorithm parameters, or null if there are no public key algorithm parameters.

    • getEncodedPublicKey

      @NotNull public ASN1BitString getEncodedPublicKey()
      Retrieves the encoded public key as a bit string.
      Returns:
      The encoded public key as a bit string.

    • getDecodedPublicKey

      @Nullable public DecodedPublicKey getDecodedPublicKey()
      Retrieves a decoded representation of the public key, if available.
      Returns:
      A decoded representation of the public key, or null if the public key could not be decoded.

    • getIssuerUniqueID

      @Nullable public ASN1BitString getIssuerUniqueID()
      Retrieves the issuer unique identifier for the certificate, if any.
      Returns:
      The issuer unique identifier for the certificate, or null if there is none.

    • getSubjectUniqueID

      @Nullable public ASN1BitString getSubjectUniqueID()
      Retrieves the subject unique identifier for the certificate, if any.
      Returns:
      The subject unique identifier for the certificate, or null if there is none.

    • getExtensions

      @NotNull public List<X509CertificateExtension> getExtensions()
      Retrieves the list of certificate extensions.
      Returns:
      The list of certificate extensions.

    • getSignatureValue

      @NotNull public ASN1BitString getSignatureValue()
      Retrieves the signature value for the certificate.
      Returns:
      The signature value for the certificate.

    • verifySignature

      public void verifySignature(@Nullable X509Certificate issuerCertificate) throws CertException
      Verifies the signature for this certificate.
      Parameters:
      issuerCertificate - The issuer certificate for this certificate. It may be null if this is a self-signed certificate. It must not be null if it is not a self-signed certificate.
      Throws:
      CertException - If the certificate signature could not be verified.

    • getSHA1Fingerprint

      @NotNull public byte[] getSHA1Fingerprint() throws CertException
      Retrieves the bytes that comprise a SHA-1 fingerprint of this certificate.
      Returns:
      The bytes that comprise a SHA-1 fingerprint of this certificate.
      Throws:
      CertException - If a problem is encountered while computing the fingerprint.

    • getSHA256Fingerprint

      @NotNull public byte[] getSHA256Fingerprint() throws CertException
      Retrieves the bytes that comprise a 256-bit SHA-2 fingerprint of this certificate.
      Returns:
      The bytes that comprise a 256-bit SHA-2 fingerprint of this certificate.
      Throws:
      CertException - If a problem is encountered while computing the fingerprint.

    • isSelfSigned

      public boolean isSelfSigned()
      Indicates whether this certificate is self-signed. The following criteria will be used to make the determination:
      1. If the certificate has both subject key identifier and authority key identifier extensions, then it will be considered self-signed if and only if the subject key identifier matches the authority key identifier.
      2. If the certificate does not have both a subject key identifier and an authority key identifier, then it will be considered self-signed if and only if its subject DN matches its issuer DN.
      Returns:
      true if this certificate is self-signed, or false if it is not.

    • isIssuerFor

      public boolean isIssuerFor(@NotNull X509Certificate c)
      Indicates whether this certificate is the issuer for the provided certificate. In order for this to be true, the following conditions must be met:
      1. The subject DN of this certificate must match the issuer DN for the provided certificate.
      2. If the provided certificate has an authority key identifier extension, then this certificate must have a subject key identifier extension with a matching identifier value.
      Parameters:
      c - The certificate for which to make the determination. This must not be null.
      Returns:
      true if this certificate is considered the issuer for the provided certificate, or false if not.

    • isIssuerFor

      public boolean isIssuerFor(@NotNull X509Certificate c, @Nullable StringBuilder nonMatchReason)
      Indicates whether this certificate is the issuer for the provided certificate. In order for this to be true, the following conditions must be met:
      1. The subject DN of this certificate must match the issuer DN for the provided certificate.
      2. If the provided certificate has an authority key identifier extension, then this certificate must have a subject key identifier extension with a matching identifier value.
      Parameters:
      c - The certificate for which to make the determination. This must not be null.
      nonMatchReason - An optional buffer that may be updated with the reason that this certificate is not considered the issuer for the provided certificate. This may be null if the caller does not require a reason.
      Returns:
      true if this certificate is considered the issuer for the provided certificate, or false if not.

    • toCertificate

      @NotNull public Certificate toCertificate() throws CertificateException
      Converts this X.509 certificate object to a Java Certificate object.
      Returns:
      The Java Certificate object that corresponds to this X.509 certificate.
      Throws:
      CertificateException - If a problem is encountered while performing the conversion.

    • hashCode

      public int hashCode()
      Retrieves a hash code for this certificate.
      Overrides:
      hashCode in class Object
      Returns:
      A hash code for this certificate.

    • equals

      public boolean equals(@Nullable Object o)
      Indicates whether the provided object is considered equal to this X.509 certificate.
      Overrides:
      equals in class Object
      Parameters:
      o - The object for which to make the determination.
      Returns:
      true if the provided object is considered equal to this X.509 certificate, or false if not.

    • toString

      @NotNull public String toString()
      Retrieves a string representation of the decoded X.509 certificate.
      Overrides:
      toString in class Object
      Returns:
      A string representation of the decoded X.509 certificate.

    • toString

      public void toString(@NotNull StringBuilder buffer)
      Appends a string representation of the decoded X.509 certificate to the provided buffer.
      Parameters:
      buffer - The buffer to which the information should be appended.

    • toPEM

      @NotNull public List<String> toPEM()
      Retrieves a list of the lines that comprise a PEM representation of this X.509 certificate.
      Returns:
      A list of the lines that comprise a PEM representation of this X.509 certificate.

    • toPEMString

      @NotNull public String toPEMString()
      Retrieves a multi-line string containing a PEM representation of this X.509 certificate.
      Returns:
      A multi-line string containing a PEM representation of this X.509 certificate.