Class CertificateBuilder

java.lang.Object
io.netty.pkitesting.CertificateBuilder
public final class CertificateBuilder extends 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 Details

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

    • 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(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(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(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(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(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(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(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(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(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(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(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(String uri) throws URISyntaxException
      Add a URI name to the Subject Alternative Names.
      Parameters:
      uri - The URI to add to the SANs.
      Returns:
      This certificate builder.
      Throws:
      URISyntaxException

    • addSanUriName

      public CertificateBuilder addSanUriName(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(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(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(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(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(URI uri, 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(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 invalid input: '&' signature sizes.
      Returns:
      This certificate builder.
      See Also:

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

    • publicKey

      public CertificateBuilder publicKey(PublicKey publicKey)
      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:
      publicKey - The public key to wrap in a certificate.
      Returns:
      This certificate builder.

    • keyPair

      public CertificateBuilder keyPair(KeyPair keyPair)
      Instruct the certificate builder to not generate its own key pair, but to instead create a certificate that uses the given key pair.

      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), or when creating cross-signed certificates.

      Cross-signing is when two certificates have the same subject and public key, but are signed by different keys. In effect, it's the same logical certificate, but manifest as two different "concrete" certificate objects, i.e. two different X509Bundle objects. Cross-signing can be done to both leaf certificates and to issuers, and can create complicated certificate graphs. The technique is used for introducing new roots and issuers to a PKI system, in a backwards compatible way where certificates can be trusted by peers that aren't familiar with the new roots or issuers.

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

      Parameters:
      keyPair - The key pair to use when creating a certificate.
      Returns:
      This certificate builder.

    • addExtensionOctetString

      public CertificateBuilder addExtensionOctetString(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(String identifierOID, boolean critical, 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(String identifierOID, boolean critical, 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.

    • setKeyUsage

      public CertificateBuilder setKeyUsage(boolean critical, CertificateBuilder.KeyUsage... keyUsages)
      The key usage specify the intended usages for which the certificate has been issued. Some are overlapping, some are deprecated, and some are implied by usage.

      For Certificate Authority usage, the important ones are CertificateBuilder.KeyUsage.keyCertSign and CertificateBuilder.KeyUsage.cRLSign.

      Any certificate that has CertificateBuilder.KeyUsage.keyCertSign must also have setIsCertificateAuthority(boolean) set to true.

      Parameters:
      critical - true if certificate recipients are required to understand all the set bits, otherwise false.
      keyUsages - The key usages to set.
      Returns:
      This certificate builder.

    • addExtendedKeyUsage

      public CertificateBuilder addExtendedKeyUsage(String oid)
      Add the given OID to the list of extended key usages.
      Parameters:
      oid - The OID to add.
      Returns:
      This certificate builder.
      See Also:

    • addExtendedKeyUsage

      public CertificateBuilder addExtendedKeyUsage(CertificateBuilder.ExtendedKeyUsage keyUsage)
      Add the given CertificateBuilder.ExtendedKeyUsage to the list of extended key usages.
      Parameters:
      keyUsage - The extended key usage to add.
      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 Exception
      Build a X509Bundle with a self-signed certificate.
      Returns:
      The newly created bundle.
      Throws:
      Exception - If something went wrong in the process.

    • buildIssuedBy

      public X509Bundle buildIssuedBy(X509Bundle issuerBundle) throws 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:
      Exception - If something went wrong in the process.

    • buildIssuedBy

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