Package org.gnome.gio

Class TlsCertificate

java.lang.Object

io.github.jwharm.javagi.base.ProxyInstance

org.gnome.gobject.TypeInstance

org.gnome.gobject.GObject

org.gnome.gio.TlsCertificate

All Implemented Interfaces:

Proxy

Direct Known Subclasses:

TlsCertificate.TlsCertificateImpl

@Generated("io.github.jwharm.JavaGI")
public abstract class TlsCertificate
extends GObject

A certificate used for TLS authentication and encryption. This can represent either a certificate only (eg, the certificate received by a client from a server), or the combination of a certificate and a private key (which is needed when acting as a TlsServerConnection).

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	TlsCertificate.Builder<B extends TlsCertificate.Builder<B>>	Inner class implementing a builder pattern to construct a GObject with properties.
static class	TlsCertificate.TlsCertificateClass
static class	TlsCertificate.TlsCertificateImpl	The TlsCertificateImpl type represents a native instance of the abstract TlsCertificate class.

Nested classes/interfaces inherited from class org.gnome.gobject.GObject

GObject.NotifyCallback, GObject.ObjectClass

Constructor Summary

Constructors

Constructor	Description
TlsCertificate(MemorySegment address)	Create a TlsCertificate proxy instance for the provided memory address.

Method Summary

Modifier and Type	Method	Description
protected TlsCertificate	asParent()	Returns this instance as if it were its parent type.
static TlsCertificate.Builder<? extends TlsCertificate.Builder>	builder()	A TlsCertificate.Builder object constructs a TlsCertificate with the specified properties.
static TlsCertificate	fromFile(String file)	Creates a GTlsCertificate from the data in file.
static TlsCertificate	fromFiles(String certFile, String keyFile)	Creates a GTlsCertificate from the PEM-encoded data in certFile and keyFile.
static TlsCertificate	fromFileWithPassword(String file, String password)	Creates a GTlsCertificate from the data in file.
static TlsCertificate	fromPem(String data, long length)	Creates a GTlsCertificate from the PEM-encoded data in data.
static TlsCertificate	fromPkcs11Uris(String pkcs11Uri, @Nullable String privateKeyPkcs11Uri)	Creates a GTlsCertificate from a PKCS \\#11 URI.
static TlsCertificate	fromPkcs12(byte[] data, @Nullable String password)	Creates a GTlsCertificate from the data in data.
Bytes[]	getDnsNames()	Gets the value of GTlsCertificate:dns-names.
InetAddress[]	getIpAddresses()	Gets the value of GTlsCertificate:ip-addresses.
TlsCertificate	getIssuer()	Gets the GTlsCertificate representing this TlsCertificate's issuer, if known
String	getIssuerName()	Returns the issuer name from the certificate.
static MemoryLayout	getMemoryLayout()	The memory layout of the native struct.
DateTime	getNotValidAfter()	Returns the time at which the certificate became or will become invalid.
DateTime	getNotValidBefore()	Returns the time at which the certificate became or will become valid.
String	getSubjectName()	Returns the subject name from the certificate.
static Type	getType()	Get the GType of the TlsCertificate class
boolean	isSame(TlsCertificate certTwo)	Check if two GTlsCertificate objects represent the same certificate.
static List<TlsCertificate>	listNewFromFile(String file)	Creates one or more GTlsCertificates from the PEM-encoded data in file.
Set<TlsCertificateFlags>	verify(@Nullable SocketConnectable identity, @Nullable TlsCertificate trustedCa)	This verifies this TlsCertificate and returns a set of GTlsCertificateFlags indicating any problems found with it.

Methods inherited from class org.gnome.gobject.GObject

addToggleRef, addWeakPointer, bindProperty, bindProperty, bindProperty, bindPropertyFull, bindPropertyFull, bindPropertyWithClosures, bindPropertyWithClosures, compatControl, connect, connect, connect, constructed, disconnect, dispatchPropertiesChanged, dispose, dupData, dupQdata, emit, emitNotify, finalize_, forceFloating, freezeNotify, get, getData, getProperty, getProperty, getProperty, getQdata, getv, interfaceFindProperty, interfaceInstallProperty, interfaceListProperties, isFloating, newInstance, newInstance, newInstance, newInstance, newv, notify_, notify_, notifyByPspec, onNotify, ref, refSink, removeToggleRef, removeWeakPointer, replaceData, replaceQdata, runDispose, set, setData, setDataFull, setProperty, setProperty, setProperty, setQdata, setQdataFull, setv, stealData, stealQdata, takeRef, thawNotify, unref, watchClosure, weakRef, weakUnref, withProperties

Methods inherited from class org.gnome.gobject.TypeInstance

callParent, callParent, getPrivate, readGClass, writeGClass

Methods inherited from class io.github.jwharm.javagi.base.ProxyInstance

equals, handle, hashCode

Methods inherited from class java.lang.Object

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

Constructor Details

TlsCertificate

public TlsCertificate(MemorySegment address)

Create a TlsCertificate proxy instance for the provided memory address.

Parameters:

address - the memory address of the native object

Method Details

getType

public static Type getType()

Get the GType of the TlsCertificate class

Returns:

the GType

getMemoryLayout

public static MemoryLayout getMemoryLayout()

The memory layout of the native struct.

Returns:

the memory layout

asParent

protected TlsCertificate asParent()

Returns this instance as if it were its parent type. This is mostly synonymous to the Java super keyword, but will set the native typeclass function pointers to the parent type. When overriding a native virtual method in Java, "chaining up" with super.methodName() doesn't work, because it invokes the overridden function pointer again. To chain up, call asParent().methodName(). This will call the native function pointer of this virtual method in the typeclass of the parent type.

Overrides:

asParent in class GObject

fromFile

public static TlsCertificate fromFile(String file)
                               throws GErrorException

Creates a GTlsCertificate from the data in file.

As of 2.72, if the filename ends in .p12 or .pfx the data is loaded by g_tls_certificate_new_from_pkcs12() otherwise it is loaded by g_tls_certificate_new_from_pem(). See those functions for exact details.

If file cannot be read or parsed, the function will return null and set error.

Parameters:

file - file containing a certificate to import

Returns:

the new certificate, or null on error

Throws:

GErrorException - see GError

fromFileWithPassword

public static TlsCertificate fromFileWithPassword(String file,
 String password)
                                           throws GErrorException

Creates a GTlsCertificate from the data in file.

If file cannot be read or parsed, the function will return null and set error.

Any unknown file types will error with IOErrorEnum.NOT_SUPPORTED. Currently only .p12 and .pfx files are supported. See g_tls_certificate_new_from_pkcs12() for more details.

Parameters:

file - file containing a certificate to import

password - password for PKCS 12 files

Returns:

the new certificate, or null on error

Throws:

GErrorException - see GError

fromFiles

public static TlsCertificate fromFiles(String certFile,
 String keyFile)
                                throws GErrorException

Creates a GTlsCertificate from the PEM-encoded data in certFile and keyFile. The returned certificate will be the first certificate found in certFile. As of GLib 2.44, if certFile contains more certificates it will try to load a certificate chain. All certificates will be verified in the order found (top-level certificate should be the last one in the file) and the GTlsCertificate:issuer property of each certificate will be set accordingly if the verification succeeds. If any certificate in the chain cannot be verified, the first certificate in the file will still be returned.

If either file cannot be read or parsed, the function will return null and set error. Otherwise, this behaves like g_tls_certificate_new_from_pem().

Parameters:

certFile - file containing one or more PEM-encoded certificates to import

keyFile - file containing a PEM-encoded private key to import

Returns:

the new certificate, or null on error

Throws:

GErrorException - see GError

fromPem

public static TlsCertificate fromPem(String data,
 long length)
                              throws GErrorException

Creates a GTlsCertificate from the PEM-encoded data in data. If data includes both a certificate and a private key, then the returned certificate will include the private key data as well. (See the GTlsCertificate:private-key-pem property for information about supported formats.)

The returned certificate will be the first certificate found in data. As of GLib 2.44, if data contains more certificates it will try to load a certificate chain. All certificates will be verified in the order found (top-level certificate should be the last one in the file) and the GTlsCertificate:issuer property of each certificate will be set accordingly if the verification succeeds. If any certificate in the chain cannot be verified, the first certificate in the file will still be returned.

Parameters:

data - PEM-encoded certificate data

length - the length of data, or -1 if it's 0-terminated.

Returns:

the new certificate, or null if data is invalid

Throws:

GErrorException - see GError

fromPkcs11Uris

public static TlsCertificate fromPkcs11Uris(String pkcs11Uri,
 @Nullable
 @Nullable String privateKeyPkcs11Uri)
                                     throws GErrorException

Creates a GTlsCertificate from a PKCS \\#11 URI.

An example pkcs11Uri would be pkcs11:model=Model;manufacturer=Manufacture;serial=1;token=My%20Client%20Certificate;id=%01

Where the token’s layout is:

 Object 0:
   URL: pkcs11:model=Model;manufacturer=Manufacture;serial=1;token=My%20Client%20Certificate;id=%01;object=private%20key;type=private
   Type: Private key (RSA-2048)
   ID: 01

 Object 1:
   URL: pkcs11:model=Model;manufacturer=Manufacture;serial=1;token=My%20Client%20Certificate;id=%01;object=Certificate%20for%20Authentication;type=cert
   Type: X.509 Certificate (RSA-2048)
   ID: 01
 

In this case the certificate and private key would both be detected and used as expected. pkcsUri may also just reference an X.509 certificate object and then optionally privateKeyPkcs11Uri allows using a private key exposed under a different URI.

Note that the private key is not accessed until usage and may fail or require a PIN later.

Parameters:

pkcs11Uri - A PKCS \\11 URI

privateKeyPkcs11Uri - A PKCS \\11 URI

Returns:

the new certificate, or null on error

Throws:

GErrorException - see GError

fromPkcs12

public static TlsCertificate fromPkcs12(byte[] data,
 @Nullable
 @Nullable String password)
                                 throws GErrorException

Creates a GTlsCertificate from the data in data. It must contain a certificate and matching private key.

If extra certificates are included they will be verified as a chain and the GTlsCertificate:issuer property will be set. All other data will be ignored.

You can pass as single password for all of the data which will be used both for the PKCS 12 container as well as encrypted private keys. If decryption fails it will error with TlsError.BAD_CERTIFICATE_PASSWORD.

This constructor requires support in the current GTlsBackend. If support is missing it will error with IOErrorEnum.NOT_SUPPORTED.

Other parsing failures will error with TlsError.BAD_CERTIFICATE.

Parameters:

data - DER-encoded PKCS 12 format certificate data

password - optional password for encrypted certificate data

Returns:

the new certificate, or null if data is invalid

Throws:

GErrorException - see GError

listNewFromFile

public static List<TlsCertificate> listNewFromFile(String file)
                                            throws GErrorException

Creates one or more GTlsCertificates from the PEM-encoded data in file. If file cannot be read or parsed, the function will return null and set error. If file does not contain any PEM-encoded certificates, this will return an empty list and not set error.

Parameters:

file - file containing PEM-encoded certificates to import

Returns:

a GList containing GTlsCertificate objects. You must free the list and its contents when you are done with it.

Throws:

GErrorException - see GError

getDnsNames

public Bytes[] getDnsNames()

Gets the value of GTlsCertificate:dns-names.

Returns:

A GPtrArray of GBytes elements, or null if it's not available.

getIpAddresses

public InetAddress[] getIpAddresses()

Gets the value of GTlsCertificate:ip-addresses.

Returns:

A GPtrArray of GInetAddress elements, or null if it's not available.

getIssuer

public TlsCertificate getIssuer()

Gets the GTlsCertificate representing this TlsCertificate's issuer, if known

Returns:

The certificate of this TlsCertificate's issuer, or null if this TlsCertificate is self-signed or signed with an unknown certificate.

getIssuerName

public String getIssuerName()

Returns the issuer name from the certificate.

Returns:

The issuer name, or null if it's not available.

getNotValidAfter

public DateTime getNotValidAfter()

Returns the time at which the certificate became or will become invalid.

Returns:

The not-valid-after date, or null if it's not available.

getNotValidBefore

public DateTime getNotValidBefore()

Returns the time at which the certificate became or will become valid.

Returns:

The not-valid-before date, or null if it's not available.

getSubjectName

public String getSubjectName()

Returns the subject name from the certificate.

Returns:

The subject name, or null if it's not available.

isSame

public boolean isSame(TlsCertificate certTwo)

Check if two GTlsCertificate objects represent the same certificate. The raw DER byte data of the two certificates are checked for equality. This has the effect that two certificates may compare equal even if their GTlsCertificate:issuer, GTlsCertificate:private-key, or GTlsCertificate:private-key-pem properties differ.

Parameters:

certTwo - second certificate to compare

Returns:

whether the same or not

verify

public Set<TlsCertificateFlags> verify(@Nullable
 @Nullable SocketConnectable identity,
 @Nullable
 @Nullable TlsCertificate trustedCa)

This verifies this TlsCertificate and returns a set of GTlsCertificateFlags indicating any problems found with it. This can be used to verify a certificate outside the context of making a connection, or to check a certificate against a CA that is not part of the system CA database.

If this TlsCertificate is valid, TlsCertificateFlags.NO_FLAGS is returned.

If identity is not null, this TlsCertificate's name(s) will be compared against it, and TlsCertificateFlags.BAD_IDENTITY will be set in the return value if it does not match. If identity is null, that bit will never be set in the return value.

If trustedCa is not null, then this TlsCertificate (or one of the certificates in its chain) must be signed by it, or else TlsCertificateFlags.UNKNOWN_CA will be set in the return value. If trustedCa is null, that bit will never be set in the return value.

GLib guarantees that if certificate verification fails, at least one error will be set in the return value, but it does not guarantee that all possible errors will be set. Accordingly, you may not safely decide to ignore any particular type of error. For example, it would be incorrect to mask TlsCertificateFlags.EXPIRED if you want to allow expired certificates, because this could potentially be the only error flag set even if other problems exist with the certificate.

Because TLS session context is not used, GTlsCertificate may not perform as many checks on the certificates as GTlsConnection would. For example, certificate constraints may not be honored, and revocation checks may not be performed. The best way to verify TLS certificates used by a TLS connection is to let GTlsConnection handle the verification.

Parameters:

identity - the expected peer identity

trustedCa - the certificate of a trusted authority

Returns:

the appropriate GTlsCertificateFlags

builder

public static TlsCertificate.Builder<? extends TlsCertificate.Builder> builder()

A TlsCertificate.Builder object constructs a TlsCertificate with the specified properties. Use the various set...() methods to set properties, and finish construction with TlsCertificate.Builder.build().