Encription specific configuration. More...

#include <IEncryptionConfigurationl.h>

Inheritance diagram for ZDK::IEncryptionConfiguration:

Public Member Functions
virtual ZDK::Shared::TLSConfiguration	TLSConfig ()=0
	Gets the TLS specific configuration. More...

virtual void	TLSConfig (ZDK::Shared::TLSConfiguration value)=0
	Sets the TLS specific configuration. More...

virtual ZDK::Shared::Result	AddKnownCertificate (ZDK::Shared::SecureCertData secureCert)=0
	Adds a certificate to the exception list. More...

virtual ZDK::Shared::Result	AddCertificates (ZDK::Shared::String filename)=0
	Adds TLS certificates from a PEM file. More...

virtual ZDK::Shared::Result	AddCertificatesDirect (unsigned char *data, int dataLen)=0
	Adds TLS certificates from memory. More...

virtual ZDK::Shared::Result	EnableCertServer (int discoverPort, int requestPort, const char *sharedKey, int sharedKeyLen)=0
	Starts certificate server. More...

virtual ZDK::Shared::Result	DisableCertServer ()=0
	Stops certificate server. More...

virtual ZDK::Shared::Result	DiscoverCertServer (int discoverPort, ZDK::Shared::String hostName, const char *sharedKey, int sharedKeyLen)=0
	Discovers certificate server on given port or by host name. More...

virtual ZDK::Shared::Result	SendCertRequest (ZDK::Shared::String requestBody)=0
	Sends a "request" to the discovered server. More...

virtual ZDK::Shared::Result	SendCertResponse (ZDK::ZDKHandle id, ZDK::Shared::String pResponse)=0
	Sends a response to a cert client. More...

virtual ZDK::Shared::Result	GlobalZrtpCache (ZDK::Shared::String value)=0
	Configure global ZRTP ZID Cache file. More...

virtual ZDK::SecureCertStatus	EvaluateCertificateTrust (ZDK::Shared::SecureCertData value)=0
	Evaluates the certificate trust type. More...

Public Member Functions inherited from ZDK::IZHandle
virtual ZDK::ZDKHandle	Handle () const =0

virtual	operator ZDK::ZDKHandle () const =0

virtual void	Initialize ()=0

virtual void	ReleaseReference ()=0

Detailed Description

Encription specific configuration.

Member Function Documentation

◆ AddCertificates()

virtual ZDK::Shared::Result ZDK::IEncryptionConfiguration::AddCertificates ( ZDK::Shared::String filename )

pure virtual

Adds TLS certificates from a PEM file.

Adds the certificates found in the file. The file must be in PEM format. Note that on Windows platforms the certificate authorities from the system certificate store will be automatically added.

Parameters

[in] filename File name containing PEM certificates to add

Returns

Result of the adding

0 - OK
non 0 value - failure

Result of the addition

See also: AddCertificatesDirect(), IResult

◆ AddCertificatesDirect()

virtual ZDK::Shared::Result ZDK::IEncryptionConfiguration::AddCertificatesDirect	(	unsigned char *	data,
		int	dataLen
	)

pure virtual

Adds TLS certificates from memory.

Adds the certificates at that memory location. The format must still be PEM like in AddCertificates().

Parameters

[in]	data	data to the buffer containing PEM certificates
[in]	dataLen	Size of the buffer in bytes

Returns

Result of the adding

0 - OK
non 0 value - failure

Result of the addition

See also: AddCertificates(), IResult

◆ AddKnownCertificate()

virtual ZDK::Shared::Result ZDK::IEncryptionConfiguration::AddKnownCertificate ( ZDK::Shared::SecureCertData secureCert )

pure virtual

Adds a certificate to the exception list.

Adds the given certificate to the list of exceptions.

This can be useful if the user wants to force a SIP/TLS connection with a server that presents a broken certificate.

The PEM data and its length can be taken straight from the OnContextSecureCertError() failure callback.

The next attempt to communicate with a server using the same certificate will succeed. For SIP registrations over TLS this will happen automatically. Other usages (for example calls) will have to be left for the user to retry.

The user should be warned that using exceptions makes TLS much less secure than they think it is.

Parameters

[in] secureCert The certificate in PEM format

Returns

Result of the adding

0 - OK
non 0 value - failure

Result of the addition

See also: AddCertificatesDirect(), OnContextSecureCertError(), IResult

◆ DisableCertServer()

virtual ZDK::Shared::Result ZDK::IEncryptionConfiguration::DisableCertServer ( )

pure virtual

Stops certificate server.

Returns: Result of the disable

See also: IResult

◆ DiscoverCertServer()

virtual ZDK::Shared::Result ZDK::IEncryptionConfiguration::DiscoverCertServer	(	int	discoverPort,
		ZDK::Shared::String	hostName,
		const char *	sharedKey,
		int	sharedKeyLen
	)

pure virtual

Discovers certificate server on given port or by host name.

Parameters

[in]	discoverPort	The destination port for broadcast messages
[in]	hostName	Used to run a DNS query for the "name" (also with attached local search domain)
[in]	sharedKey	The shared key to use (0 to use the old one)
[in]	sharedKeyLen	The length of the shared key in bytes (ignored if sharedKey is 0)

Returns: Result of the discovery

See also: IResult

◆ EnableCertServer()

virtual ZDK::Shared::Result ZDK::IEncryptionConfiguration::EnableCertServer	(	int	discoverPort,
		int	requestPort,
		const char *	sharedKey,
		int	sharedKeyLen
	)

pure virtual

Starts certificate server.

Parameters

[in]	discoverPort	The listening port for broadcast messages
[in]	requestPort	The listening port for the certificate/"permission to work" requests
[in]	sharedKey	The shared key to use (0 to use the old one)
[in]	sharedKeyLen	Tthe length of the shared key in bytes (ignored if sharedKey is 0)

Returns: Result of the enable

See also: IResult

◆ EvaluateCertificateTrust()

virtual ZDK::SecureCertStatus ZDK::IEncryptionConfiguration::EvaluateCertificateTrust ( ZDK::Shared::SecureCertData value )

pure virtual

Evaluates the certificate trust type.

This function asks the OS for trust type.

Parameters

[in] value Certificate data to be evalueted

Returns: The status of the evaluation

See also: SecureCertStatus, SecureCertData

◆ GlobalZrtpCache()

virtual ZDK::Shared::Result ZDK::IEncryptionConfiguration::GlobalZrtpCache ( ZDK::Shared::String value )

pure virtual

Configure global ZRTP ZID Cache file.

Sets the full file name for the global ZRTP ZID Cache file. The file is in a file format similar to CSV. It is managed entirely by the ZDK based on RFC 6189 (ZRTP).

If the file name is an empty string or NULL pointer, the ZRTP will proceed in cacheless mode.

The file name is UTF-8 encoded and will be converted to the native Unicode encoding for the system. (Yes, this means no need for special handling on Windows!)

The cache file is used to store binary keys called "retained secrets" in the ZRTP protocol. These retained secrets are obtained from a successful ZRTP negotiation with a peer.

Each device or phone capable of ZRTP has its own ZRTP ID called "ZID". When doing the ZRTP handshake this ZID is exchanged and can later be used to associate information with a ZRTP peer.

The ZRTP negotiation includes confirmation that the person on the other end is who they claim they are. It is always recommended to confirm the person by their voice. The ZRTP cache is used to also confirm that the person is using a device that we've already interacted with.

In the very first call with a peer we will not have a cache entry. After that we expect our cache to match the peer's cache. In case this does not happen we might have a security problem. This means confirming the negotiation with the short authentication string.

Just in case, here are some details about the file format:

The first line is our own ZID, base64-encoded. The ZID is a unique ZRTP identifier consisting of 96 random bits. The ZDK will generate a new ZID for new cache files. Once generated, our ZID will not change unless a new cache file is configured or it is lost.

From the second line to the end of the file we have peer cache records, single record per line with fields separated by the pipe symbol '|'.

Each peer record consists of:

The peer's ZID, base64 encoded
Retained Secret 1, base64 encoded. The retained secret is a one-way 256-bit hash produced from a previous successful ZRTP negotiation. It will be used to confirm the peer identity for subsequent ZRTP negotiations without the need for SAS confirmation.
Retained Secret 1 expiration, ISO format, or +INF if the retained secret will never expire
Retained Secret 2, base64 encoded. After every successful ZRTP negotiation involving a Diffie-Hellman key exchange, a new retained secret is obtained. What was previously the "Retained Secret 2" is deleted. What was previously the "Retained Secret 1" becomes the new "Retained Secret 2". The brand new retained secret is stored as the new "Retained Secret 1".
Retained Secret 2 expiration, ISO format, or +INF for "never expires" or -INF for "not available yet".

Parameters

[in] value The ZID Cache file name, or empty to disable

Returns: Result of the set

See also: IResult

◆ SendCertRequest()

virtual ZDK::Shared::Result ZDK::IEncryptionConfiguration::SendCertRequest ( ZDK::Shared::String requestBody )

pure virtual

Sends a "request" to the discovered server.

To use this function DiscoverCertServer() must have been called and must have completed with 0 (Ok)

Parameters

[in] requestBody The request body that is going to be send to the server

Returns: Result of the send

See also: IResult

◆ SendCertResponse()

virtual ZDK::Shared::Result ZDK::IEncryptionConfiguration::SendCertResponse	(	ZDK::ZDKHandle	id,
		ZDK::Shared::String	pResponse
	)

pure virtual

Sends a response to a cert client.

Use from a Cert Server implementation. The text will be encrypted and sent to the client identified by id.

Parameters

[in]	id	The client id as received from the response callback
[in]	pResponse	The response to send to the client

Returns: Result of the send

See also: IResult

◆ TLSConfig() [1/2]

virtual ZDK::Shared::TLSConfiguration ZDK::IEncryptionConfiguration::TLSConfig ( )

pure virtual

Gets the TLS specific configuration.

The configuration is applied with StartContext()! Any changes after StartContext() has been invoked will not take effect until a restart happens - StopContext() followed by StartContext().

Returns: The TLS configuration

See also: TLSConfiguration

◆ TLSConfig() [2/2]

virtual void ZDK::IEncryptionConfiguration::TLSConfig ( ZDK::Shared::TLSConfiguration value )

pure virtual

Sets the TLS specific configuration.

The configuration is applied with StartContext()! Any changes after StartContext() has been invoked will not take effect until a restart happens - StopContext() followed by StartContext().

Parameters

[in] value The TLS configuration

See also: TLSConfiguration

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

Configurations/IEncryptionConfigurationl.h

Public Member Functions

Detailed Description

Member Function Documentation

◆ AddCertificates()

◆ AddCertificatesDirect()

◆ AddKnownCertificate()

◆ DisableCertServer()

◆ DiscoverCertServer()

◆ EnableCertServer()

◆ EvaluateCertificateTrust()

◆ GlobalZrtpCache()

◆ SendCertRequest()

◆ SendCertResponse()

◆ TLSConfig() [1/2]

◆ TLSConfig() [2/2]