Package io.netty.pkitesting

Class CertificateBuilder

  • public final class CertificateBuilder
extends java.lang.Object
    The CertificateBuilder produce X509Bundle instances, where the keys use the specified algorithm, and the certificate have the specified data.

    The builder can make self-signed bundles, or can make bundles that are signed by other bundles to build a verified certificate path.

    The builder can also make certificate that are invalid in various ways, for testing purpose. The most typical application is to make a certificate that has already expired or is not yet valid.

    See RFC 5280 for the details of X.509 certificate contents.

    Here is an example where a leaf certificate is created and signed by a self-signed issuer certificate: 

    
 Instant now = Instant.now();
 CertificateBuilder template = new CertificateBuilder()
             .notBefore(now.minus(1, DAYS))
             .notAfter(now.plus(1, DAYS));
 X509Bundle issuer = template.copy()
             .subject("CN=testca, OU=dept, O=your-org")
             .setKeyUsage(true, KeyUsage.digitalSignature, KeyUsage.keyCertSign)
             .setIsCertificateAuthority(true)
             .buildSelfSigned();
 X509Bundle leaf = template.copy()
             .subject("CN=leaf, OU=dept, O=your-org")
             .setKeyUsage(true, KeyUsage.digitalSignature)
             .addExtendedKeyUsage(ExtendedKeyUsage.PKIX_KP_SERVER_AUTH)
             .addSanDnsName("san-1.leaf.dept.your-org.com")
             .buildIssuedBy(issuer);

    • Constructor Detail

      • CertificateBuilder

        public CertificateBuilder()
        Create a new certificate builder with a default configuration. Unless specified otherwise, the builder will produce bundles that use the NIST EC-P 256 key algorithm, and the certificates will be valid as of yesterday and expire tomorrow.

    • Method Detail

      • copy

        public CertificateBuilder copy()
        Produce a copy of the current state in this certificate builder.
        Returns:
        A copy of this certificate builder.

      • provider

        public CertificateBuilder provider​(java.security.Provider provider)
        Set the Provider instance to use when generating keys.
        Parameters:
        provider - The provider instance to use.
        Returns:
        This certificate builder.

      • secureRandom

        public CertificateBuilder secureRandom​(java.security.SecureRandom secureRandom)
        Set the SecureRandom instance to use when generating keys.
        Parameters:
        secureRandom - The secure random instance to use.
        Returns:
        This certificate builder.

      • notBefore

        public CertificateBuilder notBefore​(java.time.Instant instant)
        Set the not-before field of the certificate. The certificate will not be valid before this time.
        Parameters:
        instant - The not-before time.
        Returns:
        This certificate builder.

      • notAfter

        public CertificateBuilder notAfter​(java.time.Instant instant)
        Set the not-after field of the certificate. The certificate will not be valid after this time.
        Parameters:
        instant - The not-after time.
        Returns:
        This certificate builder.

      • serial

        public CertificateBuilder serial​(java.math.BigInteger serial)
        Set the specific serial number to use in the certificate. One will be generated randomly, if none is specified.
        Parameters:
        serial - The serial number to use, or null.
        Returns:
        This certificate builder.

      • subject

        public CertificateBuilder subject​(java.lang.String fqdn)
        Set the fully-qualified domain name (an X.500 name) as the subject of the certificate.
        Parameters:
        fqdn - The subject name to use.
        Returns:
        This certificate builder.

      • subject

        public CertificateBuilder subject​(javax.security.auth.x500.X500Principal name)
        Set the subject name of the certificate to the given X500Principal.
        Parameters:
        name - The subject name to use.
        Returns:
        This certificate builder.

      • addSanOtherName

        public CertificateBuilder addSanOtherName​(java.lang.String typeOid,
                                          byte[] encodedValue)
        Add an Other Name to the Subject Alternative Names, of the given OID type, and with the given encoded value. The type and value will be wrapped in a SEQUENCE.
        Parameters:
        typeOid - The OID type of the Other Name value.
        encodedValue - The encoded Other Name value.
        Returns:
        This certificate builder.

      • addSanRfc822Name

        public CertificateBuilder addSanRfc822Name​(java.lang.String name)
        Add an RFC 822 name to the Subject Alternative Names. The RFC 822 standard is the obsolete specification for email, so these SANs are email addresses.
        Parameters:
        name - The email address to add to the SANs.
        Returns:
        This certificate builder.

      • addSanDnsName

        public CertificateBuilder addSanDnsName​(java.lang.String dns)
        Add a DNS name to the Subject Alternate Names.
        Parameters:
        dns - The DNS name to add.
        Returns:
        This certificate builder.

      • addSanDirectoryName

        public CertificateBuilder addSanDirectoryName​(java.lang.String dirName)
        Add a Directory Name to the Subject Alternative Names. These are LDAP directory paths.
        Parameters:
        dirName - The directory name to add to the SANs.
        Returns:
        This certificate builder.

      • addSanUriName

        public CertificateBuilder addSanUriName​(java.lang.String uri)
                                 throws java.net.URISyntaxException
        Add a URI name to the Subject Alternative Names.
        Parameters:
        uri - The URI to add to the SANs.
        Returns:
        This certificate builder.
        Throws:
        java.net.URISyntaxException

      • addSanUriName

        public CertificateBuilder addSanUriName​(java.net.URI uri)
        Add a URI name to the Subject Alternative Names.
        Parameters:
        uri - The URI to add to the SANs.
        Returns:
        This certificate builder.

      • addSanIpAddress

        public CertificateBuilder addSanIpAddress​(java.lang.String ipAddress)
        Add an IP address to the Subject Alternative Names. IPv4 and IPv6 addresses are both supported and converted to their correct encoding.
        Parameters:
        ipAddress - The IP address to add to the SANs.
        Returns:
        This certificate builder.

      • addSanIpAddress

        public CertificateBuilder addSanIpAddress​(java.net.InetAddress ipAddress)
        Add an IP address to the Subject Alternative Names. IPv4 and IPv6 addresses are both supported and converted to their correct encoding.
        Parameters:
        ipAddress - The IP address to add to the SANs.
        Returns:
        This certificate builder.

      • addSanRegisteredId

        public CertificateBuilder addSanRegisteredId​(java.lang.String oid)
        Add a registeredID to the Subject Alternative Names. A registeredID is an OBJECT IDENTIFIER, or OID, in ASN.1 speak.
        Parameters:
        oid - The OID to add to the SANs.
        Returns:
        This certificate builder.

      • addCrlDistributionPoint

        public CertificateBuilder addCrlDistributionPoint​(java.net.URI uri)
        Add a URI distribution point for a certificate revocation list.

        If you are testing certificate revocation using the RevocationServer, you would obtain this URI from RevocationServer.getCrlUri(X509Bundle) with your intended issuer certificate bundle.

        Parameters:
        uri - The URI for the CRL file.
        Returns:
        This certificate builder.

      • addCrlDistributionPoint

        public CertificateBuilder addCrlDistributionPoint​(java.net.URI uri,
                                                  javax.security.auth.x500.X500Principal issuer)
        Add a URI distribution point for a certificate revocation list.

        If you are testing certificate revocation using the RevocationServer, you would obtain this URI from RevocationServer.getCrlUri(X509Bundle) with your intended issuer certificate bundle.

        Parameters:
        uri - The URI for the CRL file.
        issuer - The issuer that signs the CRL file. This MUST be null if the CRL issuer is also the issuer of the certificate being built. Otherwise, if this certificate and the CRL will be signed by different issuers, then this MUST be the subject name of the CRL signing certificate.
        Returns:
        This certificate builder.

      • setIsCertificateAuthority

        public CertificateBuilder setIsCertificateAuthority​(boolean isCA)
        Set the certificate authority field. If this is set to true, then this builder can build self-signed certificates, and those certifiactes can be used to sign other certificates.
        Parameters:
        isCA - true if this builder should make CA certificates.
        Returns:
        This certificate builder.

      • setPathLengthConstraint

        public CertificateBuilder setPathLengthConstraint​(java.util.OptionalInt pathLengthConstraint)
        Certificate Authority certificates may impose a limit to the length of the verified certificate path they permit.
        Parameters:
        pathLengthConstraint - The maximum verified path length, if any.
        Returns:
        This certificate builder.

      • algorithm

        public CertificateBuilder algorithm​(CertificateBuilder.Algorithm algorithm)
        Set the key algorithm to use. This also determines how certificates are signed.
        Parameters:
        algorithm - The algorithm to use when generating the private key.
        Returns:
        This certificate builder.

      • ecp256

        public CertificateBuilder ecp256()
        Make this certificate builder use the NIST EC-P 256 elliptic curve key algorithm. This algorithm provides a good balance between security, compatibility, performance, and key & signature sizes.
        Returns:
        This certificate builder.
        See Also:
        ecp256()

      • rsa2048

        public CertificateBuilder rsa2048()
        Make this certificate builder use the 2048-bit RSA encryption and signing algorithm. This algorithm provides maximum compatibility, but keys are large and slow to generate.
        Returns:
        This certificate builder.
        See Also:
        rsa2048()

      • publicKey

        public CertificateBuilder publicKey​(java.security.PublicKey key)
        Instruct the certificate builder to not generate its own key pair, but to instead create a certificate that uses the given public key.

        This method is useful if you want to use an existing key-pair, e.g. to emulate a certificate authority responding to a Certificate Signing Request (CSR).

        If the given public key is null (the default) then a new key-pair will be generated instead.

        Parameters:
        key - The public key to wrap in a certificate.
        Returns:
        This certificate builder.

      • addExtensionOctetString

        public CertificateBuilder addExtensionOctetString​(java.lang.String identifierOID,
                                                  boolean critical,
                                                  byte[] contents)
        Add a custom extension to the certificate, with the given OID, criticality flag, and DER-encoded contents.
        Parameters:
        identifierOID - The OID identifying the extension.
        critical - true if the extension is critical, otherwise false. Certificate systems MUST reject certificates with critical extensions they don't recognize.
        contents - The DER-encoded extension contents.
        Returns:
        This certificate builder.

      • addExtensionUtf8String

        public CertificateBuilder addExtensionUtf8String​(java.lang.String identifierOID,
                                                 boolean critical,
                                                 java.lang.String value)
        Add a custom DER-encoded ASN.1 UTF-8 string extension to the certificate, with the given OID, criticality, and string value. The string will be converted to its proper binary encoding by this method.
        Parameters:
        identifierOID - The OID identifying the extension.
        critical - true if the extension is critical, otherwise false. Certificate systems MUST reject certificates with critical extensions they don't recognize.
        value - The string value.
        Returns:
        This certificate builder.

      • addExtensionAsciiString

        public CertificateBuilder addExtensionAsciiString​(java.lang.String identifierOID,
                                                  boolean critical,
                                                  java.lang.String value)
        Add a custom DER-encoded ASN.1 IA5String (an ASCII string) extension to the certificate, with the given OID, criticality, and string value. The string will be converted to its proper binary encoding by this method.
        Parameters:
        identifierOID - The OID identifying the extension.
        critical - true if the extension is critical, otherwise false. Certificate systems MUST reject certificates with critical extensions they don't recognize.
        value - The string value.
        Returns:
        This certificate builder.

      • addExtendedKeyUsageServerAuth

        public CertificateBuilder addExtendedKeyUsageServerAuth()
        Add server-authentication to the list of extended key usages.
        Returns:
        This certificate builder.

      • addExtendedKeyUsageClientAuth

        public CertificateBuilder addExtendedKeyUsageClientAuth()
        Add client-authentication to the list of extended key usages.
        Returns:
        This certificate builder.

      • addExtendedKeyUsageCodeSigning

        public CertificateBuilder addExtendedKeyUsageCodeSigning()
        Add code signing to the list of extended key usages.
        Returns:
        This certificate builder.

      • addExtendedKeyUsageEmailProtection

        public CertificateBuilder addExtendedKeyUsageEmailProtection()
        Add email protection to the list of extended key usages.
        Returns:
        This certificate builder.

      • addExtendedKeyUsageTimeStamping

        public CertificateBuilder addExtendedKeyUsageTimeStamping()
        Add time-stamping to the list of extended key usages.
        Returns:
        This certificate builder.

      • addExtendedKeyUsageOcspSigning

        public CertificateBuilder addExtendedKeyUsageOcspSigning()
        Add OCSP signing to the list of extended key usages.
        Returns:
        This certificate builder.

      • addExtendedKeyUsageKerberosClientAuth

        public CertificateBuilder addExtendedKeyUsageKerberosClientAuth()
        Add Kerberos client authentication to the list of extended key usages.
        Returns:
        This certificate builder.

      • addExtendedKeyUsageMicrosoftSmartcardLogin

        public CertificateBuilder addExtendedKeyUsageMicrosoftSmartcardLogin()
        Add Microsoft smartcard login to the list of extended key usages.
        Returns:
        This certificate builder.

      • buildSelfSigned

        public X509Bundle buildSelfSigned()
                           throws java.lang.Exception
        Build a X509Bundle with a self-signed certificate.
        Returns:
        The newly created bundle.
        Throws:
        java.lang.Exception - If something went wrong in the process.

      • buildIssuedBy

        public X509Bundle buildIssuedBy​(X509Bundle issuerBundle)
                         throws java.lang.Exception
        Build a X509Bundle with a certificate signed by the given issuer bundle. The signing algorithm used will be derived from the issuers public key.
        Returns:
        The newly created bundle.
        Throws:
        java.lang.Exception - If something went wrong in the process.

      • buildIssuedBy

        public X509Bundle buildIssuedBy​(X509Bundle issuerBundle,
                                java.lang.String signAlg)
                         throws java.lang.Exception
        Build a X509Bundle with a certificate signed by the given issuer bundle, using the specified signing algorithm.
        Returns:
        The newly created bundle.
        Throws:
        java.lang.Exception - If something went wrong in the process.