Module io.netty5.buffer

Package io.netty5.buffer

Class SensitiveBufferAllocator

java.lang.Object

io.netty5.buffer.SensitiveBufferAllocator

All Implemented Interfaces:

BufferAllocator, io.netty5.util.SafeCloseable, AutoCloseable

public final class SensitiveBufferAllocator
extends Object
implements BufferAllocator

This BufferAllocator is for allocating off-heap Buffers that may contain sensitive information, which should be erased from memory (overwritten) when the buffer is closed.

The features and behaviours of this allocator are otherwise exactly the same as BufferAllocator.offHeapUnpooled().

Of particular note, the byte arrays passed to BufferAllocator.copyOf(byte[]) and BufferAllocator.constBufferSupplier(byte[]), and the buffer passed to BufferAllocator.copyOf(ByteBuffer) are not cleared by this allocator. These copies of the sensitive data must be cleared separately! Ideally these methods should not be used for sensitive data in the first place, and the sensitive data should instead be directly written to, or created in, a sensitive buffer.

This allocator is stateless, and the close() method has no effect.

Method Summary

Modifier and Type	Method	Description
Buffer	allocate(int size)	Allocate a Buffer of the given size in bytes.
void	close()	Close this allocator, freeing all of its internal resources.
Supplier<Buffer>	constBufferSupplier(byte[] bytes)	Create a supplier of "constant" Buffers from this allocator, that all have the given byte contents.
AllocationType	getAllocationType()	Get the AllocationType from this allocator.
boolean	isPooling()	Determine if this allocator is pooling and reusing its allocated memory.
static BufferAllocator	sensitiveOffHeapAllocator()	Get the sensitive off-heap buffer allocator instance.

Methods inherited from class java.lang.Object

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

Methods inherited from interface io.netty5.buffer.BufferAllocator

compose, compose, compose, copyOf, copyOf, copyOf

Method Detail

sensitiveOffHeapAllocator

public static BufferAllocator sensitiveOffHeapAllocator()

Get the sensitive off-heap buffer allocator instance.

Returns:

The allocator.

isPooling

public boolean isPooling()

Description copied from interface: BufferAllocator

Determine if this allocator is pooling and reusing its allocated memory.

Specified by:

isPooling in interface BufferAllocator

Returns:

true if this allocator is pooling and reusing its memory, false otherwise.

getAllocationType

public AllocationType getAllocationType()

Description copied from interface: BufferAllocator

Get the AllocationType from this allocator. This would typically be one of the StandardAllocationTypes.

Specified by:

getAllocationType in interface BufferAllocator

Returns:

The type of allocations performed by this allocator.

allocate

public Buffer allocate(int size)

Description copied from interface: BufferAllocator

Allocate a Buffer of the given size in bytes. This method may throw an OutOfMemoryError if there is not enough free memory available to allocate a Buffer of the requested size.

The buffer will use big endian byte order.

Note: unlike the JDK ByteBuffers, Netty Buffers are not guaranteed to be zeroed when allocated. In other words, the memory of a newly allocated buffer may contain garbage data from prior allocations, and the memory is likewise not guaranteed to be erased when the buffer is closed. If the data is sensitive and needs to be overwritten when the buffer is closed, then the buffer should be allocated with the SensitiveBufferAllocator.

Specified by:

allocate in interface BufferAllocator

Parameters:

size - The size of Buffer to allocate.

Returns:

The newly allocated Buffer.

constBufferSupplier

public Supplier<Buffer> constBufferSupplier(byte[] bytes)

Description copied from interface: BufferAllocator

Create a supplier of "constant" Buffers from this allocator, that all have the given byte contents. The buffer has the same capacity as the byte array length, and its write offset is placed at the end, and its read offset is at the beginning, such that the entire buffer contents are readable.

The buffers produced by the supplier will each have their own independent life-cycle, and closing them will make them inaccessible, just like normally allocated buffers.

The buffers produced are "constants", in the sense that they are read-only.

It can generally be expected, but is not guaranteed, that the returned supplier is more resource efficient than allocating and copying memory with other available APIs. In such optimised implementations, the underlying memory baking the buffers will be shared among all the buffers produced by the supplier.

The primary use case for this API, is when you need to repeatedly produce buffers with the same contents, and you perhaps wish to keep a static final field with these contents. The supplier-based API enforces that each usage get their own distinct buffer instance. Each of these instances cannot interfere with each other, so bugs like closing, or modifying the contents, of a shared buffer cannot occur.

Specified by:

constBufferSupplier in interface BufferAllocator

Parameters:

bytes - The byte contents of the buffers produced by the returned supplier.

Returns:

A supplier of read-only buffers with the given contents.

close

public void close()

Description copied from interface: BufferAllocator

Close this allocator, freeing all of its internal resources.

Existing (currently in-use) allocated buffers will not be impacted by calling this method. If this is a pooling or caching allocator, then existing buffers will be immediately freed when they are closed, instead of being pooled or cached.

The allocator can no longer be used to allocate more buffers after calling this method. Attempting to allocate from a closed allocator will cause IllegalStateExceptions to be thrown.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface BufferAllocator

Specified by:

close in interface io.netty5.util.SafeCloseable