com.zoiper.zdk.Configurations

Class EncryptionConfiguration

java.lang.Object

com.zoiper.zdk.Configurations.EncryptionConfiguration

public class EncryptionConfiguration
extends java.lang.Object

Encription specific configuration

Constructor Summary

Constructors

Constructor and Description
EncryptionConfiguration(long handle) Constructor storing the pointer/address to the underlying native object

Method Summary

Modifier and Type	Method and Description
Result	addCertificates(java.lang.String filename) Adds TLS certificates from a PEM file Adds the certificates found in the file.
Result	addCertificatesDirect(byte[] data, int dataLen) Adds TLS certificates from memory Adds the certificates at that memory location.
Result	addKnownCertificate(java.lang.String pem) Adds a certificate to the exception list Adds the given certificate to the list of exceptions.
SecureCertStatus	evaluateCertificateTrust(java.lang.String pem, java.lang.String expectedName) Evaluates the certificate trust type.
protected void	finalize() Ensures the underlying native object destruction
Result	globalZrtpCache(java.lang.String value) Configure global ZRTP ZID Cache file Sets the full file name for the global ZRTP ZID Cache file.
long	handle() Gets the pointer/address to the underlying native object
TLSConfiguration	tlsConfig() 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.
void	tlsConfig(TLSConfiguration value) 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.
SecureCertStatus	verifyUserCertificate(java.lang.String fileName, java.lang.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.

Methods inherited from class java.lang.Object

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

Constructor Detail

EncryptionConfiguration

public EncryptionConfiguration(long handle)

Constructor storing the pointer/address to the underlying native object

Parameters:

handle - Pointer/address to the underlying native object

Method Detail

handle

public long handle()

Gets the pointer/address to the underlying native object

Returns:

Pointer/address to the underlying native object

finalize

protected void finalize()

Ensures the underlying native object destruction

Overrides:

finalize in class java.lang.Object

tlsConfig

public TLSConfiguration tlsConfig()

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

public void tlsConfig(TLSConfiguration value)

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:

value - The TLS configuration

See Also:

TLSConfiguration

addKnownCertificate

public Result addKnownCertificate(java.lang.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:

pem - The certificate in PEM format

Returns:

Result of the addition

See Also:

onContextSecureCertStatus Result

addCertificates

public Result addCertificates(java.lang.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:

filename - File name containing PEM certificates to add

Returns:

Result of the addition

See Also:

Result

addCertificatesDirect

public Result addCertificatesDirect(byte[] 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:

data - data to the buffer containing PEM certificates

dataLen - Size of the buffer in bytes

Returns:

Result of the addition

See Also:

Result

globalZrtpCache

public Result globalZrtpCache(java.lang.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:

value - The ZID Cache file name, or empty to disable

Returns:

Result of the set

See Also:

Result

evaluateCertificateTrust

public SecureCertStatus evaluateCertificateTrust(java.lang.String pem,
                                                 java.lang.String expectedName)

Evaluates the certificate trust type. This function asks the OS for trust type.

Parameters:

pem - The PEM encoded certificate

expectedName - The policy will require this value to match the host name.

Returns:

The status of the evaluation

See Also:

SecureCertStatus

verifyUserCertificate

public SecureCertStatus verifyUserCertificate(java.lang.String fileName,
                                              java.lang.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:

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)

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