CertificateBuilder (Netty/PKITesting 4.2.0.RC1 API)

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);

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`CertificateBuilder.Algorithm` The `CertificateBuilder.Algorithm` enum encapsulates both the key type, key generation parameters, and the signature algorithm to use.
`static class`	`CertificateBuilder.ExtendedKeyUsage` The extended key usage field specify what the certificate and key is allowed to be used for.
`static class`	`CertificateBuilder.KeyUsage` The key usage field specify what the certificate and key is allowed to be used for.

Constructor Summary

Constructors
Constructor and Description

CertificateBuilder()
Create a new certificate builder with a default configuration.

Constructors
Constructor and Description
`CertificateBuilder()` Create a new certificate builder with a default configuration.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`CertificateBuilder`	`addCrlDistributionPoint(URI uri)` Add a URI distribution point for a certificate revocation list.
`CertificateBuilder`	`addCrlDistributionPoint(URI uri, X500Principal issuer)` Add a URI distribution point for a certificate revocation list.
`CertificateBuilder`	`addExtendedKeyUsage(CertificateBuilder.ExtendedKeyUsage keyUsage)` Add the given `CertificateBuilder.ExtendedKeyUsage` to the list of extended key usages.
`CertificateBuilder`	`addExtendedKeyUsage(String oid)` Add the given OID to the list of extended key usages.
`CertificateBuilder`	`addExtendedKeyUsageClientAuth()` Add client-authentication to the list of extended key usages.
`CertificateBuilder`	`addExtendedKeyUsageCodeSigning()` Add code signing to the list of extended key usages.
`CertificateBuilder`	`addExtendedKeyUsageEmailProtection()` Add email protection to the list of extended key usages.
`CertificateBuilder`	`addExtendedKeyUsageKerberosClientAuth()` Add Kerberos client authentication to the list of extended key usages.
`CertificateBuilder`	`addExtendedKeyUsageMicrosoftSmartcardLogin()` Add Microsoft smartcard login to the list of extended key usages.
`CertificateBuilder`	`addExtendedKeyUsageOcspSigning()` Add OCSP signing to the list of extended key usages.
`CertificateBuilder`	`addExtendedKeyUsageServerAuth()` Add server-authentication to the list of extended key usages.
`CertificateBuilder`	`addExtendedKeyUsageTimeStamping()` Add time-stamping to the list of extended key usages.
`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.
`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.
`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.
`CertificateBuilder`	`addSanDirectoryName(String dirName)` Add a Directory Name to the Subject Alternative Names.
`CertificateBuilder`	`addSanDnsName(String dns)` Add a DNS name to the Subject Alternate Names.
`CertificateBuilder`	`addSanIpAddress(InetAddress ipAddress)` Add an IP address to the Subject Alternative Names.
`CertificateBuilder`	`addSanIpAddress(String ipAddress)` Add an IP address to the Subject Alternative Names.
`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.
`CertificateBuilder`	`addSanRegisteredId(String oid)` Add a registeredID to the Subject Alternative Names.
`CertificateBuilder`	`addSanRfc822Name(String name)` Add an RFC 822 name to the Subject Alternative Names.
`CertificateBuilder`	`addSanUriName(String uri)` Add a URI name to the Subject Alternative Names.
`CertificateBuilder`	`addSanUriName(URI uri)` Add a URI name to the Subject Alternative Names.
`CertificateBuilder`	`algorithm(CertificateBuilder.Algorithm algorithm)` Set the key algorithm to use.
`X509Bundle`	`buildIssuedBy(X509Bundle issuerBundle)` Build a `X509Bundle` with a certificate signed by the given issuer bundle.
`X509Bundle`	`buildIssuedBy(X509Bundle issuerBundle, String signAlg)` Build a `X509Bundle` with a certificate signed by the given issuer bundle, using the specified signing algorithm.
`X509Bundle`	`buildSelfSigned()` Build a `X509Bundle` with a self-signed certificate.
`CertificateBuilder`	`copy()` Produce a copy of the current state in this certificate builder.
`CertificateBuilder`	`ecp256()` Make this certificate builder use the NIST EC-P 256 elliptic curve key algorithm.
`CertificateBuilder`	`notAfter(Instant instant)` Set the not-after field of the certificate.
`CertificateBuilder`	`notBefore(Instant instant)` Set the not-before field of the certificate.
`CertificateBuilder`	`publicKey(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.
`CertificateBuilder`	`rsa2048()` Make this certificate builder use the 2048-bit RSA encryption and signing algorithm.
`CertificateBuilder`	`secureRandom(SecureRandom secureRandom)` Set the `SecureRandom` instance to use when generating keys.
`CertificateBuilder`	`serial(BigInteger serial)` Set the specific serial number to use in the certificate.
`CertificateBuilder`	`setIsCertificateAuthority(boolean isCA)` Set the certificate authority field.
`CertificateBuilder`	`setKeyUsage(boolean critical, CertificateBuilder.KeyUsage... keyUsages)` The key usage specify the intended usages for which the certificate has been issued.
`CertificateBuilder`	`setPathLengthConstraint(OptionalInt pathLengthConstraint)` Certificate Authority certificates may impose a limit to the length of the verified certificate path they permit.
`CertificateBuilder`	`subject(String fqdn)` Set the fully-qualified domain name (an X.500 name) as the subject of the certificate.
`CertificateBuilder`	`subject(X500Principal name)` Set the subject name of the certificate to the given `X500Principal`.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- 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.
  - 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 & 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(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(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:
    
    CertificateBuilder.ExtendedKeyUsage, addExtendedKeyUsage(ExtendedKeyUsage)
  - 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.

Class CertificateBuilder

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

CertificateBuilder

Method Detail

copy

secureRandom

notBefore

notAfter

serial

subject

subject

addSanOtherName

addSanRfc822Name

addSanDnsName

addSanDirectoryName

addSanUriName

addSanUriName

addSanIpAddress

addSanIpAddress

addSanRegisteredId

addCrlDistributionPoint

addCrlDistributionPoint

setIsCertificateAuthority

setPathLengthConstraint

algorithm

ecp256

rsa2048

publicKey

addExtensionOctetString

addExtensionUtf8String

addExtensionAsciiString

setKeyUsage

addExtendedKeyUsage

addExtendedKeyUsage

addExtendedKeyUsageServerAuth

addExtendedKeyUsageClientAuth

addExtendedKeyUsageCodeSigning

addExtendedKeyUsageEmailProtection

addExtendedKeyUsageTimeStamping

addExtendedKeyUsageOcspSigning

addExtendedKeyUsageKerberosClientAuth

addExtendedKeyUsageMicrosoftSmartcardLogin

buildSelfSigned

buildIssuedBy

buildIssuedBy