Encription specific configuration. More...

#include <EncryptionConfiguration.h>

Inheritance diagram for ZDK_NET::EncryptionConfiguration:

Public Member Functions
	EncryptionConfiguration (ZDK::Shared::EncryptionConfiguration src)

ZDK_NET::Result ^	AddKnownCertificate (System::String^ pem)
	Adds a certificate to the exception list. More...

ZDK_NET::Result ^	AddCertificates (System::String^ filename)
	Adds TLS certificates from a PEM file. More...

ZDK_NET::Result ^	AddCertificatesDirect (unsigned char *data, int dataLen)
	Adds TLS certificates from memory. More...

ZDK_NET::Result ^	GlobalZrtpCache (System::String^ value)
	Configure global ZRTP ZID Cache file. More...

ZDK_NET::SecureCertStatus	EvaluateCertificateTrust (System::String^ pem, System::String^ expectedName)
	Evaluates the certificate trust type. More...

ZDK_NET::SecureCertStatus	VerifyUserCertificate (System::String^ fileName, System::String^ passphrase)
	Verifies usability for SSL certificate and key pair. More...

virtual long long	Handle () override

virtual void	Initialize () override

virtual void	ReleaseReference () override

Public Attributes
ZDK::IEncryptionConfiguration *	cppRef = nullptr

Properties
ZDK_NET::TLSConfiguration^	TLSConfig `[get, set]`
	Sets the TLS specific configuration. More...

Detailed Description

Encription specific configuration.

Member Function Documentation

◆ AddCertificates()

ZDK_NET::Result ^ ZDK_NET::EncryptionConfiguration::AddCertificates ( System::String^ filename )

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 addition

See also: AddCertificatesDirect(), Result

◆ AddCertificatesDirect()

ZDK_NET::Result ^ ZDK_NET::EncryptionConfiguration::AddCertificatesDirect	(	unsigned char *	data,
		int	dataLen
	)

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 addition

See also: AddCertificates(), Result

◆ AddKnownCertificate()

ZDK_NET::Result ^ ZDK_NET::EncryptionConfiguration::AddKnownCertificate ( System::String^ pem )

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 can be taken straight from the OnContextSecureCertStatus() status callback.

The next attempt to communicate with a server using the same certificate will succeed. All connection establishments (e.g. registrations and 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] pem The certificate in PEM format

Returns: Result of the addition

See also: AddCertificatesDirect(), OnContextSecureCertStatus(), Result

◆ EvaluateCertificateTrust()

ZDK_NET::SecureCertStatus ZDK_NET::EncryptionConfiguration::EvaluateCertificateTrust	(	System::String^	pem,
		System::String^	expectedName
	)

Evaluates the certificate trust type.

This function asks the OS for trust type.

Parameters

[in]	pem	The PEM encoded certificate
[in]	expectedName	The policy will require this value to match the host name.

Returns: The status of the evaluation

See also: SecureCertStatus

◆ GlobalZrtpCache()

ZDK_NET::Result ^ ZDK_NET::EncryptionConfiguration::GlobalZrtpCache ( System::String^ value )

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, SO format, or +NF 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, SO format, or +NF for "never expires" or -NF for "not available yet".

Parameters

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

Returns: Result of the set

See also: Result

◆ VerifyUserCertificate()

ZDK_NET::SecureCertStatus ZDK_NET::EncryptionConfiguration::VerifyUserCertificate	(	System::String^	fileName,
		System::String^	passphrase
	)

Verifies usability for SSL certificate and key pair.

This function can be used to check if a certificate and key pair found in a PEM or PKCS#12 file is valid before applying it to a user.

This gives much more detail than SetUserCertificate which still MUST be called to actually configure the user.

The code tries to isolate the most common errors like trying to load an encrypted private key with the incorrect password or trying to use a wrong combination of key and certificate.

Actual certificate signature validation is not done yet although we have decided to reserve an output parameter for it.

The suite for which we will test the cert is taken from the setting done by TLSConfiguration::SecureSuite()

Parameters

[in]	fileName	File name of the cert+key pair. Accepts PEM (text file with the cert and key one after the other in base64 encoding) or PKCS#12 (a binary format more common on Windows)
[in]	passphrase	Optional, the pass phrase which is used to protect the private key in the file

Returns: The status of the verification

See also: TLSConfiguration::SecureSuite()

Property Documentation

◆ TLSConfig

ZDK_NET:: TLSConfiguration^ ZDK_NET::EncryptionConfiguration::TLSConfig

getset

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/EncryptionConfiguration.h

Public Member Functions

Public Attributes

Properties

Detailed Description

Member Function Documentation

◆ AddCertificates()

◆ AddCertificatesDirect()

◆ AddKnownCertificate()

◆ EvaluateCertificateTrust()

◆ GlobalZrtpCache()

◆ VerifyUserCertificate()

Property Documentation

◆ TLSConfig