Socket wrapper for TLS I/O. More...

#include <XrdTlsSocket.hh>

Public Types
enum	RW_Mode { TLS_RNB_WNB , TLS_RNB_WBL , TLS_RBL_WNB , TLS_RBL_WBL }

enum	HS_Mode { TLS_HS_BLOCK = true , TLS_HS_NOBLK = false }

enum	SDType { sdForce = 1 , sdImmed = 2 , sdWait = 3 }

Public Member Functions
	XrdTlsSocket (XrdTlsContext &ctx, int sfd, RW_Mode rwm, HS_Mode hsm, bool isClient, bool serial=true)

	XrdTlsSocket ()

	~XrdTlsSocket ()
	Destructor.

XrdTls::RC	Accept (std::string *eMsg=0)

XrdTls::RC	Connect (const char thehost=0, std::string eWhy=0)

XrdTlsContext *	Context ()

XrdTlsPeerCerts *	getCerts (bool ver=true)

const char *	Init (XrdTlsContext &ctx, int sfd, RW_Mode rwm, HS_Mode hsm, bool isClient, bool serial=true, const char *tid="")

XrdTls::RC	Peek (char *buffer, size_t size, int &bytesPeek)

int	Pending (bool any=true)

XrdTls::RC	Read (char *buffer, size_t size, int &bytesRead)
	Read from the TLS connection. If necessary, a handshake will be done.

void	SetTraceID (const char *tid)

void	Shutdown (SDType=sdImmed)

XrdTls::RC	Write (const char *buffer, size_t size, int &bytesOut)

bool	NeedHandShake ()

const char *	Version ()

Private Member Functions
void	AcceptEMsg (std::string eWhy, const char reason)

int	Diagnose (const char *what, int sslrc, int tcode)

std::string	Err2Text (int sslerr)

bool	NeedHS ()

bool	Wait4OK (bool wantRead)

Private Attributes
XrdTlsSocketImpl *	pImpl

Detailed Description

Socket wrapper for TLS I/O.

Member Enumeration Documentation

◆ HS_Mode

enum XrdTlsSocket::HS_Mode

Enumerator
TLS_HS_BLOCK	Always block during handshake.
TLS_HS_NOBLK	Do not block during handshake.

◆ RW_Mode

enum XrdTlsSocket::RW_Mode

Enumerator
TLS_RNB_WNB	Non-blocking read non-blocking write.
TLS_RNB_WBL	Non-blocking read blocking write.
TLS_RBL_WNB	blocking read non-blocking write
TLS_RBL_WBL	blocking read blocking write

◆ SDType

enum XrdTlsSocket::SDType

Tear down a TLS connection

Parameters

One	of the following enums: sdForce - Forced shutdown (violates TLS standard). sdImmed - Immediate shutdown (don't wait for ack); the default. sdWait - Wait for peer acknowledgement (may be slow).

Enumerator
sdForce
sdImmed
sdWait

Constructor & Destructor Documentation

◆ XrdTlsSocket() [1/2]

XrdTlsSocket::XrdTlsSocket	(	XrdTlsContext &	ctx,
		int	sfd,
		RW_Mode	rwm,
		HS_Mode	hsm,
		bool	isClient,
		bool	serial = `true`
	)

Constructor - creates specified mode TLS I/O wrapper for given socket file descriptor. Note this constructor throws an exception should any error be encountered. Use the parameterless constructor if you wish to avoid handling exceptions. When an exception is thrown, you should print all associated errors by calling GetErrs() or PrintErrs().

Parameters

ctx	- the context for the connection. Be aware that a context can be associated wity multiple connections.
sfd	- the file descriptor associated with the connection.
rwm	- One of the above enums describing how connection I/O should be handled.
hsm	- One of the above enums describing how handshakes during read/write calls should be handled.
isClient	- When true initialize for client use. Otherwise, initialize for server use.
serial	- When true, only allows one thread to use the socket at a time to prevent SSL errors (default). When false does not add this protection, assuming caller does so.

◆ XrdTlsSocket() [2/2]

XrdTlsSocket::XrdTlsSocket ( )

Constructor - reserves space for a TLS I/O wrapper. Use the Init() method to fully initialize this object.

◆ ~XrdTlsSocket()

XrdTlsSocket::~XrdTlsSocket ( )

Destructor.

Member Function Documentation

◆ Accept()

XrdTls::RC XrdTlsSocket::Accept ( std::string * eMsg = 0 )

Accept an incoming TLS connection

Parameters

eMsg	- If not nil, receives the associated error message.

Returns: The appropriate TLS return code.

◆ AcceptEMsg()

void XrdTlsSocket::AcceptEMsg	(	std::string *	eWhy,
		const char *	reason
	)

private

◆ Connect()

XrdTls::RC XrdTlsSocket::Connect	(	const char *	thehost = `0`,
		std::string *	eWhy = `0`
	)

Establish a TLS connection

Parameters

thehost	- The expected hostname. If nil the peername is not verified.
eWhy	- If not nil, receives the associated error message.

Returns: TLS_AOK if the operation was successful; otherwise the appropraite return code indicating the problem with eWhy, not nil, containing a description of the error.

◆ Context()

XrdTlsContext * XrdTlsSocket::Context ( )

Obtain context associated with this connection.

Returns: : Tls connection object

◆ Diagnose()

int XrdTlsSocket::Diagnose	(	const char *	what,
		int	sslrc,
		int	tcode
	)

private

◆ Err2Text()

std::string XrdTlsSocket::Err2Text ( int sslerr )

private

◆ getCerts()

XrdTlsPeerCerts * XrdTlsSocket::getCerts ( bool ver = true )

Get peer certificates associated with the socket.

Parameters

ver	- When true, only return verified certificates.

Returns: A pointer to the object holding the peer certificate and the associated chain. Nill is returned if there are no certificates of if verification did not occur but ver was true. The caller is responsible for deleting the returned object.

◆ Init()

const char * XrdTlsSocket::Init	(	XrdTlsContext &	ctx,
		int	sfd,
		RW_Mode	rwm,
		HS_Mode	hsm,
		bool	isClient,
		bool	serial = `true`,
		const char *	tid = `""`
	)

Initialize this object to handle the specified TLS I/O mode for the given file descriptor. Should an error occur, messages are automatically routed to the context message callback before returning.

Parameters

ctx	- the context for the connection. Be aware that a context can be associated wity multiple connections.
sfd	- the file descriptor associated with the connection.
rwm	- One of the above enums describing how connection I/O should be handled.
hsm	- One of the above enums describing how handshakes during read/write calls should be handled.
isClient	- When true initialize for client use. Otherwise, initialize for server use.
serial	- When true, only allows one thread to use the socket at a time to prevent SSL errors (default). When false does not add this protection, assuming caller does so.
tid	- Trace identifier to appear in messages. The value must have the same lifetime as this object.

Returns: =0 - object has been initialized.; !0 - an error occurred, the return value is a pointer to a message summarizing the error. This message is the same as would be thrown by the parameterized constructor.

◆ NeedHandShake()

bool XrdTlsSocket::NeedHandShake ( )

Returns: : true if the TLS/SSL session is not established yet, false otherwise

◆ NeedHS()

bool XrdTlsSocket::NeedHS ( )

private

◆ Peek()

XrdTls::RC XrdTlsSocket::Peek	(	char *	buffer,
		size_t	size,
		int &	bytesPeek
	)

Peek at the TLS connection data. If necessary, a handshake will be done.

Parameters

buffer	- Pointer to buffer to hold the data.
size	- The size of the buffer in bytes.
bytesPeek	- Number of bytes placed in the buffer, if successful.

Returns: TLS_AOK if the operation was successful; otherwise the appropraite return code indicating the problem.

◆ Pending()

int XrdTlsSocket::Pending ( bool any = true )

Check if data is pending or readable.

Parameters

any	True to return in any data is in the queue. False to return the number of processed bytes.

Returns: any = true: 1 is returned if there is data in the queue (processed or not). 0 is returned o/w. any = false: the number of processed bytes that are available. These are not necesarily data bytes. A subsequent read may still return 0.

◆ Read()

XrdTls::RC XrdTlsSocket::Read	(	char *	buffer,
		size_t	size,
		int &	bytesRead
	)

Read from the TLS connection. If necessary, a handshake will be done.

Parameters

buffer	- Pointer to buffer to hold the data.
size	- The size of the buffer in bytes.
bytesRead	- Number of bytes placed in the buffer, if successful.

Returns: TLS_AOK if the operation was successful; otherwise the appropraite return code indicating the problem.

◆ SetTraceID()

void XrdTlsSocket::SetTraceID ( const char * tid )

Set the trace identifier (used when it's updated).

Parameters

tid	- Pointer to trace identifier.

◆ Shutdown()

void XrdTlsSocket::Shutdown ( SDType = sdImmed )

◆ Version()

const char * XrdTlsSocket::Version ( )

Returns: The TLS version number being used.

◆ Wait4OK()

bool XrdTlsSocket::Wait4OK ( bool wantRead )

private

◆ Write()

XrdTls::RC XrdTlsSocket::Write	(	const char *	buffer,
		size_t	size,
		int &	bytesOut
	)

Write to the TLS connection. If necessary, a handshake will be done.

Parameters

buffer	- Pointer to buffer holding the data.
size	- The size of the data to write.
bytesOut	- Number of bytes actually written, if successful.

Returns: TLS_AOK if the operation was successful; otherwise the appropraite return code indicating the problem.

Member Data Documentation

◆ pImpl

XrdTlsSocketImpl* XrdTlsSocket::pImpl

private

The documentation for this class was generated from the following file:

XrdTlsSocket.hh

Public Types

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Member Enumeration Documentation

◆ HS_Mode

◆ RW_Mode

◆ SDType

Constructor & Destructor Documentation

◆ XrdTlsSocket() [1/2]

◆ XrdTlsSocket() [2/2]

◆ ~XrdTlsSocket()

Member Function Documentation

◆ Accept()

◆ AcceptEMsg()

◆ Connect()

◆ Context()

◆ Diagnose()

◆ Err2Text()

◆ getCerts()

◆ Init()

◆ NeedHandShake()

◆ NeedHS()

◆ Peek()

◆ Pending()

◆ Read()

◆ SetTraceID()

◆ Shutdown()

◆ Version()

◆ Wait4OK()

◆ Write()

Member Data Documentation

◆ pImpl