Class CertificateBuilder
- java.lang.Object
-
- io.netty.pkitesting.CertificateBuilder
-
public final class CertificateBuilder extends java.lang.Object
TheCertificateBuilder
produceX509Bundle
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 Description static class
CertificateBuilder.Algorithm
TheCertificateBuilder.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 Description CertificateBuilder()
Create a new certificate builder with a default configuration.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description CertificateBuilder
addCrlDistributionPoint(java.net.URI uri)
Add a URI distribution point for a certificate revocation list.CertificateBuilder
addCrlDistributionPoint(java.net.URI uri, javax.security.auth.x500.X500Principal issuer)
Add a URI distribution point for a certificate revocation list.CertificateBuilder
addExtendedKeyUsage(CertificateBuilder.ExtendedKeyUsage keyUsage)
Add the givenCertificateBuilder.ExtendedKeyUsage
to the list of extended key usages.CertificateBuilder
addExtendedKeyUsage(java.lang.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(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.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.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.CertificateBuilder
addSanDirectoryName(java.lang.String dirName)
Add a Directory Name to the Subject Alternative Names.CertificateBuilder
addSanDnsName(java.lang.String dns)
Add a DNS name to the Subject Alternate Names.CertificateBuilder
addSanIpAddress(java.lang.String ipAddress)
Add an IP address to the Subject Alternative Names.CertificateBuilder
addSanIpAddress(java.net.InetAddress ipAddress)
Add an IP address to the Subject Alternative Names.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.CertificateBuilder
addSanRegisteredId(java.lang.String oid)
Add a registeredID to the Subject Alternative Names.CertificateBuilder
addSanRfc822Name(java.lang.String name)
Add an RFC 822 name to the Subject Alternative Names.CertificateBuilder
addSanUriName(java.lang.String uri)
Add a URI name to the Subject Alternative Names.CertificateBuilder
addSanUriName(java.net.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 aX509Bundle
with a certificate signed by the given issuer bundle.X509Bundle
buildIssuedBy(X509Bundle issuerBundle, java.lang.String signAlg)
Build aX509Bundle
with a certificate signed by the given issuer bundle, using the specified signing algorithm.X509Bundle
buildSelfSigned()
Build aX509Bundle
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(java.time.Instant instant)
Set the not-after field of the certificate.CertificateBuilder
notBefore(java.time.Instant instant)
Set the not-before field of the certificate.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.CertificateBuilder
rsa2048()
Make this certificate builder use the 2048-bit RSA encryption and signing algorithm.CertificateBuilder
secureRandom(java.security.SecureRandom secureRandom)
Set theSecureRandom
instance to use when generating keys.CertificateBuilder
serial(java.math.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(java.util.OptionalInt pathLengthConstraint)
Certificate Authority certificates may impose a limit to the length of the verified certificate path they permit.CertificateBuilder
subject(java.lang.String fqdn)
Set the fully-qualified domain name (an X.500 name) as the subject of the certificate.CertificateBuilder
subject(javax.security.auth.x500.X500Principal name)
Set the subject name of the certificate to the givenX500Principal
.
-
-
-
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(java.security.SecureRandom secureRandom)
Set theSecureRandom
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, ornull
.- 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 givenX500Principal
.- 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 fromRevocationServer.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 fromRevocationServer.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 benull
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 totrue
, 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, otherwisefalse
. 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, otherwisefalse
. 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, otherwisefalse
. 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
andCertificateBuilder.KeyUsage.cRLSign
.Any certificate that has
CertificateBuilder.KeyUsage.keyCertSign
must also havesetIsCertificateAuthority(boolean)
set totrue
.- Parameters:
critical
-true
if certificate recipients are required to understand all the set bits, otherwisefalse
.keyUsages
- The key usages to set.- Returns:
- This certificate builder.
-
addExtendedKeyUsage
public CertificateBuilder addExtendedKeyUsage(java.lang.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 givenCertificateBuilder.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 java.lang.Exception
Build aX509Bundle
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 aX509Bundle
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 aX509Bundle
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.
-
-