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​(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

        public static ObjectPair<X509Certificate,​java.security.KeyPair> generateSelfSignedCertificate​(SignatureAlgorithmIdentifier signatureAlgorithm,
                                                                                                            PublicKeyAlgorithmIdentifier publicKeyAlgorithm,
                                                                                                            int keySizeBits,
                                                                                                            DN subjectDN,
                                                                                                            long notBefore,
                                                                                                            long notAfter,
                                                                                                            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

        public static X509Certificate generateSelfSignedCertificate​(SignatureAlgorithmIdentifier signatureAlgorithm,
                                                                    java.security.KeyPair keyPair,
                                                                    DN subjectDN,
                                                                    long notBefore,
                                                                    long notAfter,
                                                                    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

        public static X509Certificate generateIssuerSignedCertificate​(SignatureAlgorithmIdentifier signatureAlgorithm,
                                                                      X509Certificate issuerCertificate,
                                                                      java.security.PrivateKey issuerPrivateKey,
                                                                      OID publicKeyAlgorithmOID,
                                                                      ASN1Element publicKeyAlgorithmParameters,
                                                                      ASN1BitString encodedPublicKey,
                                                                      DecodedPublicKey decodedPublicKey,
                                                                      DN subjectDN,
                                                                      long notBefore,
                                                                      long notAfter,
                                                                      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

        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

        public java.math.BigInteger getSerialNumber()
        Retrieves the certificate serial number.
        Returns:
        The certificate serial number.
      • getSignatureAlgorithmOID

        public OID getSignatureAlgorithmOID()
        Retrieves the certificate signature algorithm OID.
        Returns:
        The certificate signature algorithm OID.
      • getSignatureAlgorithmName

        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

        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

        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

        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

        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

        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​(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

        public DN getSubjectDN()
        Retrieves the certificate subject DN.
        Returns:
        The certificate subject DN.
      • getPublicKeyAlgorithmOID

        public OID getPublicKeyAlgorithmOID()
        Retrieves the certificate public key algorithm OID.
        Returns:
        The certificate public key algorithm OID.
      • getPublicKeyAlgorithmName

        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

        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

        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

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

        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

        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

        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.
      • getSignatureValue

        public ASN1BitString getSignatureValue()
        Retrieves the signature value for the certificate.
        Returns:
        The signature value for the certificate.
      • verifySignature

        public void verifySignature​(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

        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

        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​(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​(X509Certificate c,
                                   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

        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.
      • toString

        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​(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

        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

        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.