Client and backend. This class is shared: the same code is compiled into your app and into your server, so everything on this page works in both.

public final class CertificateRequest

Object
CertificateRequest

A PKCS#10 certificate signing request (RFC 2986): what a device sends a certificate authority to get the client certificate it then presents over mutual TLS.

The key pair never leaves the device. The request carries the public key and the names the certificate is for, signed with the private key to prove the device holds it:

KeyPair keys = KeyGenerator.ec(256);
byte[] csr = new CertificateRequest(keys.getPublicKey().getEncoded(), "EC")
        .commonName("thermostat-42")
        .organization("Example Devices")
        .dnsName("thermostat-42.local")
        .sign(data -> Signature.sign(Signature.SHA256_WITH_ECDSA, keys.getPrivateKey(), data));
String pem = CertificateRequest.toPem(csr);

The class only encodes. The signature comes from whatever holds the key: a hardware key store signs with its own call, and a headless device on the backend with com.codename1.backend.Crypto:

byte[] key = Crypto.generateEcKey(Crypto.P256);
byte[] csr = new CertificateRequest(Der.publicKeyOf(key), "EC")
        .commonName(deviceId)
        .sign(data -> Crypto.sign(Crypto.ES256, key, data));

Requests are signed with SHA-256: ECDSA for an EC key, PKCS#1 v1.5 for an RSA key.

Nested types

interface CertificateRequest.Signer Signs the encoded request body with the private key matching the request’s public key, using getSignatureAlgorithm().

Constructors

public CertificateRequest(byte[] subjectPublicKeyInfo, String keyAlgorithm) Starts a request for a public key.

Methods

`public` `String getSignatureAlgorithm()`	The signature algorithm the `Signer` has to use: `SHA256withECDSA` or `SHA256withRSA`.
`public` `CertificateRequest commonName(String name)`	Adds the subject’s common name (CN), typically the device identity.
`public` `CertificateRequest organization(String name)`	Adds the subject’s organization (O).
`public` `CertificateRequest organizationalUnit(String name)`	Adds the subject’s organizational unit (OU).
`public` `CertificateRequest country(String code)`	Adds the subject’s country (C).
`public` `CertificateRequest dnsName(String name)`	Asks for a DNS name in the certificate’s subject alternative names, which is what a TLS client checks when the device is the server.
`public` `CertificateRequest ipAddress(String address)`	Asks for an IPv4 address in the subject alternative names.
`public byte[] getInfo()`	The DER CertificationRequestInfo: the part of the request that is signed.
`public byte[] encode(byte[] signature)`	Encodes the request with a signature made elsewhere over `getInfo()`.
`public byte[] sign(CertificateRequest.Signer signer) throws IOException`	Signs and encodes the request.
`public static` `String toPem(byte[] der)`	Wraps a DER request in the PEM form most certificate authorities take.

Inherited methods

From Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait, clone, finalize

Constructor details

CertificateRequest

public CertificateRequest(byte[] subjectPublicKeyInfo, String keyAlgorithm)

Starts a request for a public key.

Parameters

subjectPublicKeyInfo byte[]: the X.509 DER public key, as PublicKey.getEncoded() returns it
keyAlgorithm String: EC or RSA

Method details

getSignatureAlgorithm

public String getSignatureAlgorithm()

The signature algorithm the Signer has to use: SHA256withECDSA or SHA256withRSA.

Returns

the JCA name of the algorithm

commonName

public CertificateRequest commonName(String name)

Adds the subject’s common name (CN), typically the device identity.

Parameters

name String: the name

Returns

this request

organization

public CertificateRequest organization(String name)

Adds the subject’s organization (O).

Parameters

name String: the organization

Returns

this request

organizationalUnit

public CertificateRequest organizationalUnit(String name)

Adds the subject’s organizational unit (OU).

Parameters

name String: the unit

Returns

this request

country

public CertificateRequest country(String code)

Adds the subject’s country (C).

Parameters

code String: the two-letter ISO 3166 code

Returns

this request

dnsName

public CertificateRequest dnsName(String name)

Asks for a DNS name in the certificate’s subject alternative names, which is what a TLS client checks when the device is the server.

Parameters

name String: the host name, ASCII

Returns

this request

ipAddress

public CertificateRequest ipAddress(String address)

Asks for an IPv4 address in the subject alternative names.

Parameters

address String: dotted decimal, such as 192.168.1.20

Returns

this request

getInfo

public byte[] getInfo()

The DER CertificationRequestInfo: the part of the request that is signed.

Returns

the encoded bytes

encode

public byte[] encode(byte[] signature)

Encodes the request with a signature made elsewhere over getInfo().

Parameters

signature byte[]: the signature bytes

Returns

the DER request

sign

public byte[] sign(CertificateRequest.Signer signer)
throws IOException

Signs and encodes the request.

Parameters

signer CertificateRequest.Signer: signs with the private key

Returns

the DER request

Throws

IOException: when the signer fails

toPem

public static String toPem(byte[] der)

Wraps a DER request in the PEM form most certificate authorities take.

Parameters

der byte[]: the encoded request

Returns

-----BEGIN CERTIFICATE REQUEST----- and the base64 body