zdk.objc
Instance Methods | Properties | List of all members
<ZDKEncryptionConfiguration> Protocol Reference

Encription specific configuration. More...

#import <ZDKEncryptionConfiguration.h>

Inheritance diagram for <ZDKEncryptionConfiguration>:
<ZDKZHandle>

Instance Methods

(id< ZDKResult >) - addKnownCertificate:
 Adds a certificate to the exception list. More...
 
(id< ZDKResult >) - addCertificates:
 Adds TLS certificates from a PEM file. More...
 
(id< ZDKResult >) - addCertificatesDirect:dataLen:
 Adds TLS certificates from memory. More...
 
(id< ZDKResult >) - globalZrtpCache:
 Configure global ZRTP ZID Cache file. More...
 
(ZDKSecureCertStatus) - evaluateCertificateTrust:expectedName:
 Evaluates the certificate trust type. More...
 
(ZDKSecureCertStatus) - verifyUserCertificate:passphrase:
 Verifies usability for SSL certificate and key pair. More...
 
(NSString *) - handlesDescription
 
- Instance Methods inherited from <ZDKZHandle>
(long int) - handle
 
(void) - initialize
 
(void) - releaseReference
 
(NSString *) - handlesDescription
 

Properties

id< ZDKTLSConfiguration > _Nullable tlsConfig
 Sets the TLS specific configuration. More...
 

Detailed Description

Encription specific configuration.

Method Documentation

◆ addCertificates:

- (id< ZDKResult >) addCertificates: (NSString *)  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]filenameFile name containing PEM certificates to add
Returns
Result of the addition
See also
addCertificatesDirect(), ZDKResult

◆ addCertificatesDirect:dataLen:

- (id< ZDKResult >) addCertificatesDirect: (unsigned char *)  data
dataLen: (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]datadata to the buffer containing PEM certificates
[in]dataLenSize of the buffer in bytes
Returns
Result of the addition
See also
addCertificates(), ZDKResult

◆ addKnownCertificate:

- (id< ZDKResult >) addKnownCertificate: (NSString *)  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]pemThe certificate in PEM format
Returns
Result of the addition
See also
addCertificatesDirect(), onContextSecureCertStatus(), ZDKResult

◆ evaluateCertificateTrust:expectedName:

- (ZDKSecureCertStatus) evaluateCertificateTrust: (NSString *)  pem
expectedName: (NSString *)  expectedName 

Evaluates the certificate trust type.

This function asks the OS for trust type.

Parameters
[in]pemThe PEM encoded certificate
[in]expectedNameThe policy will require this value to match the host name.
Returns
The status of the evaluation
See also
SecureCertStatus

◆ globalZrtpCache:

- (id< ZDKResult >) globalZrtpCache: (NSString *)  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, ZDKSO format, or +ZDKNF 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, ZDKSO format, or +ZDKNF for "never expires" or -ZDKNF for "not available yet".
Parameters
[in]valueThe ZID Cache file name, or empty to disable
Returns
Result of the set
See also
ZDKResult

◆ handlesDescription

- (NSString *) handlesDescription

Reimplemented from <ZDKZHandle>.

◆ verifyUserCertificate:passphrase:

- (ZDKSecureCertStatus) verifyUserCertificate: (NSString *)  fileName
passphrase: (NSString *)  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 zdktlsConfiguration::SecureSuite()

Parameters
[in]fileNameFile 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]passphraseOptional, the pass phrase which is used to protect the private key in the file
Returns
The status of the verification
See also
zdktlsConfiguration::SecureSuite()

Property Documentation

◆ tlsConfig

- (id<ZDKTLSConfiguration> _Nullable) tlsConfig
readwritenonatomicassign

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]valueThe TLS configuration
See also
ZDKTLSConfiguration

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