Class X509Certificate

  • All Implemented Interfaces:
    java.io.Serializable

    @NotMutable
    @ThreadSafety(level=COMPLETELY_THREADSAFE)
    public final class X509Certificate
    extends java.lang.Object
    implements java.io.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:
    Serialized Form
    • Constructor Detail

      • 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 Detail

      • generateSelfSignedCertificate

        @NotNull
        public static ObjectPair<X509Certificate,​java.security.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
                                                                    java.security.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
                                                                      java.security.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.
      • getSerialNumber

        @NotNull
        public java.math.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 java.lang.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 java.lang.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 java.util.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 java.util.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
                                              java.util.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 java.lang.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 java.lang.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.
      • 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.
      • 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
                                   java.lang.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 java.security.cert.Certificate toCertificate()
                                                     throws java.security.cert.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:
        java.security.cert.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 java.lang.Object
        Returns:
        A hash code for this certificate.
      • equals

        public boolean equals​(@Nullable
                              java.lang.Object o)
        Indicates whether the provided object is considered equal to this X.509 certificate.
        Overrides:
        equals in class java.lang.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 java.lang.String toString()
        Retrieves a string representation of the decoded X.509 certificate.
        Overrides:
        toString in class java.lang.Object
        Returns:
        A string representation of the decoded X.509 certificate.
      • toString

        public void toString​(@NotNull
                             java.lang.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 java.util.List<java.lang.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 java.lang.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.