Avaya Client Services API Reference (OS X)

- Main Page
- Classes
- Files
- Related Pages

- Class List
- Class Index
- Class Hierarchy
- Class Members

Instance Methods | Properties | List of all members
CSCertificateManager Class Reference

Certificate manager class allows application developers to configure and make use of the library's client/server certificate trust validation logic. More...

`#import <CSCertificateManager.h>`

Inherits NSObject.

## Instance Methods
(NSArray *) | - appCertificatesInfo
| Returns information about the certificates stored in the private trust store. More...
(CSCertificateInfo *) | - clientIdentityCertificateInfo
| Returns information about the client identity certificate in use. More...
(NSArray *) | - certificates
| Returns a list of certificates stored in the private trust store. More...
(void) | - deleteCertStore
| Deletes an existing private trust store. More...
(BOOL) | - isCertificateStoreInUse
| Returns the private trust store status. More...
(BOOL) | - setCertificates:error:
| Creates the private trust store using supplied trusted anchors (Root and Intermediate CA certificates). More...
(void) | - validateCertificateWithSecTrustRef:completionHandler:
| Performs a trust validation of a certificate chain to determine if the secure connection with the peer can be trusted. More...
(void) | - validateCertificateWithSecTrustRef:expectedServiceDomain:expectedHostname:peerPort:completionHandler:
| Performs a trust validation of a certificate chain to determine if the secure connection with the peer can be trusted. More...
(BOOL) | - deleteClientIdentityWithError:
| Deletes persistent reference to client identity used by Client SDK. More...
(NSError *) | - setClientIdentityCertificateFromPKCS12Data:withPassword:
| DEPRECATED since 241.0.0. More...
(BOOL) | - setClientIdentity:withCertificateChain:error:
| Saves persistent reference to keychain items `SecIdentityRef` and `SecCertificateRef`. More...
(void) | - enrollWithConfiguration:enrollmentCredentialProvider:completionHandler:
| Requests client identity certificate enrollment. More...
(SecIdentityRef) | - clientIdentity
| Returns a provisioned client identity. More...
(CFArrayRef) | - clientIdentityCertificateChain
| Returns a provisioned client identity certificate (chain). More...

## Properties
id< CSCertificateManagerClientIdentityDelegate > | clientIdentityDelegate
| Delegate used to handle events related to client identity certificate's status. More...

## Detailed Description

Certificate manager class allows application developers to configure and make use of the library's client/server certificate trust validation logic.

It allows specification of a client identity certificate, configure a private trust store and certificate trust validation of all the connections, application is making on its own.

The developers can use the setCertificates:error: method to create a private trust store. It (private trust store) is an application managed certificate store that contains the Root and Intermediate CA certificates trusted (known as "trusted anchors") by an application. The private trust store is used to validate the server/client certificate chain for all the secure connections made by an application.

The private trust store has following advantages over the conventional system certificate stores provided by Operating System -

- The private trust store offers a sandbox certificate store exclusively used and managed by an application.

- The trusted anchors (certificates) in the private trust store are not shared with trusted anchors from system certificate store.

- Application administrators choose to distribute only necessary trusted CA certificates in a controlled way, not worrying for any rouge CA certificate being added to the private trust store.

- Application can create and delete the private trust store without affecting the system certificate stores and thus affecting other connection-oriented applications.

The private trust store allows application to be more secure. For example, consider a scenario where a CA inadvertently had issued certificates and revoked those later on. CA publishes the certificate status information so that application may choose to query and proceed. However, revocation status check process has its own challenges making it unsuitable, causing the rouge servers to be trusted by an applications. Such cases can be easily managed by using the private trust store. Application administrator may simply remove the corresponding CA certificate that had issued invalid certificates such that insecure connections cannot be established with the server.

This class allows an application to store a client identity certificate which can be used to pass on to the server upon server's request during TLS Mutual Authentication. A client identity certificate is trust validated by the server and untrusted certificate will be rejected by the server by issuing SSL Alert and severing the connection.

The client applications can register a certificate status listener to get notified when client identity certificate is about to expire. This notification serves as a reminder for an user to begin requesting a renewed certificate for this application. This notification period can be configured using CSSecurityPolicyConfiguration.

Applications that have been using default certificate trust validation logic, can now delegate the trust validation request to this class. The certificate validation methods offered by this class allows the use of the private trust store or system trust store. Also, certain behavior of these methods can be preconfigured based on the application deployment scenarios via CSSecurityPolicyConfiguration.

## Method Documentation

- (NSArray *) appCertificatesInfo |  |  |

Returns information about the certificates stored in the private trust store.

This method returns an array of CSCertificateInfo objects from the private trust store only. An attempt to retrieve the certificate information while private trust store is not created is returned with `nil` array.

The CSCertificateInfo class object represents a selected set of X.509 certificate attributes that can be used for informative purpose, for example, displaying the existing trusted anchors (CA certificates) to client application's users.

Returns
  An array of CSCertificateInfo if the private trust store exists; `nil` in case the private trust store is absent.

See also
  - isCertificateStoreInUse

- (NSArray *) certificates |  |  |

Returns a list of certificates stored in the private trust store.

This method returns a certificates stored in the private trust store as an array of `SecCertificateRef`. This method can be used as an alternative to appCertificatesInfo, where client application wants to use their own certificate information parsing logic.

Returns
  An array of `SecCertificateRef` objects if private trust store exists; `nil` when private trust store is absent.

See also
  - appCertificatesInfo

- (SecIdentityRef) clientIdentity |  |  |

Returns a provisioned client identity.

Returns
  A reference to `SecIdentityRef` object containing client identity certificates and a private key. If client identity is not provisioned, it returns `nil`.

See also
  - clientIdentityCertificateChain

- (CFArrayRef) clientIdentityCertificateChain |  |  |

Returns a provisioned client identity certificate (chain).

Returns
  A reference to an array of `SecCertificateRef` containing client identity certificate chain. If the client identity is not provisioned, it returns `nil`.

See also
  - clientIdentity

- (CSCertificateInfo *) clientIdentityCertificateInfo |  |  |

Returns information about the client identity certificate in use.

This method returns a CSCertificateInfo object from the current client identity certificate.

The CSCertificateInfo class object represents a selected set of X.509 certificate attributes that can be used for informative purpose, for example, displaying the current client identity certificate to client application's users.

Returns
  A CSCertificateInfo if a client identity certificate is set; `nil` in case the client identity certificate is nil.

- (void) deleteCertStore |  |  |

Deletes an existing private trust store.

Client application can delete an existing private trust store if it wants to modify the certificates or it wants to use system certificate stores supplied by the OS.

This method deletes the private trust store only. An attempt to delete other trust stores is ignored.

See also
  - isCertificateStoreInUse

- (BOOL) deleteClientIdentityWithError: |  | (NSError **) | errorResult |

Deletes persistent reference to client identity used by Client SDK.

Client SDK will stop using client identity. Items are not removed from a keychain since it is application responsibility.

Parameters

  errorResult | `error` If the operation is successful this parameter is `nil`. If an error occurred it contains an object describing the error.

Returns
  `YES` A provisioned client identity certificate and a private key is deleted. `NO` Failure to delete the client identity certificate and a private key. The detailed error information is available `error` object.

- (void) enrollWithConfiguration: |  | (CSSCEPConfiguration *) | configuration
enrollmentCredentialProvider: |  | (id< CSEnrollmentCredentialProvider >) | enrollmentCredentialProvider
completionHandler: |  | (void(^)(CFArrayRef identityCertChain, SecIdentityRef secIdentity, NSError *result)) | completionHandler

Requests client identity certificate enrollment.

A client identity certificate identifies each client and generally issued unique to each client. This certificate is sent to the server upon request during the mutual authentication process as part of the SSL Handshake.

Parameters

  configuration | SCEP Configuration that will be used for client identity certificate enrollment.
  enrollmentCredentialProvider | A reference to an enrollment credentials provider that challenges the client for enrollment credentials (certificate common name and enrollment password).
  completionHandler | A block to be called when operation is completed. `identityCertChain` A reference to an array of `SecCertificateRef` containing client identity certificate chain. `secIdentity` A reference to `SecIdentityRef` containing the client identity mainly private key. `result` Is an object describing enrollment result

- (BOOL) isCertificateStoreInUse |  |  |

Returns the private trust store status.

This method can be used to determine if a client application has successfully creates its own trust store. It can also be used to check if the private trust store already exists.

Returns
  `YES` The private trust store exists. `NO` The private trust store is absent.

See also
  CSCertificateManager::setCertificates

- (BOOL) setCertificates: |  | (NSArray *) | certificates
error: |  | (NSError **) | error

Creates the private trust store using supplied trusted anchors (Root and Intermediate CA certificates).

This method creates the private trust store if one does not exists. Unlike system certificate stores, the client application can configure only one trust store.The Root and Intermediate CA certificates can be added while creating the trust store and cannot be modified subsequently; any such modification attempts result into an error. In order to modify existing private trust store, a call to CSCertificateManager::deleteCertStore is required followed by CSCertificateManager::setCertificates:error:.

Before calling this method, client applications must ensure the CSSecurityPolicyConfiguration::privateTrustStoreEnabled property is enabled.

Parameters

  certificates | CA certificates trusted by the client application.
  error | If operation is successful `error` is nil. If an error occurred it contains an object describing the error.

Returns
  `YES` If operation is successful and private trust store has been created. `NO` If operation is failed; detailed error information is available via `error` object.

- (BOOL) setClientIdentity: |  | (SecIdentityRef) | secIdentity
withCertificateChain: |  | (NSArray *) | identityCertChain
error: |  | (NSError **) | errorResult

Saves persistent reference to keychain items `SecIdentityRef` and `SecCertificateRef`.

When Client SDK starts it will restore client identity from a keychain.

It is application responsibility to maintain client identity items lifetime in the keychain. Note that application can use custom keychain to protect its data.

A client identity certificate identifies each client and generally issued unique to each client. This certificate is sent to the server upon request during the mutual authentication process as part of the SSL Handshake.

Client application using custom client certificate enrollment process can use this method to provision retrieved client identity.

Parameters

  secIdentity | A reference to `SecIdentityRef` containing the client identity.
  identityCertChain | A reference to an array of `SecCertificateRef` containing client identity certificate chain.
  errorResult | `error` If the operation is successful this parameter is `nil`. If an error occurred it contains an object describing the error.

Returns
  `YES` If the client identity has been provisioned successfully. `NO` If method is failed to provision client identity. The error describing the failure is available via `error` object.

- (NSError *) setClientIdentityCertificateFromPKCS12Data: |  | (NSData *) | PKCS12Data
withPassword: |  | (NSString *) | password

DEPRECATED since 241.0.0.

- (void) validateCertificateWithSecTrustRef: |  | (SecTrustRef) | secTrustRef
completionHandler: |  | (void(^)(NSError *error)) | completionHandler

Performs a trust validation of a certificate chain to determine if the secure connection with the peer can be trusted.

While establishing secure connection, the certificate chain is received as part of SSL Handshake that can be validated using this method. The validation result determines if the connection is secure and peer can be trusted. This method performs trust validation asynchronously and upon completion a block is called to post the result.

As per RFC 5280, the trust validation involves a certificate chain building which leads upto a trusted anchors. For client application, if the private trust store has been configured, it will be solely used to build a certificate chain. In a case when the private trust store is unavailable, the system certificate stores will be used. This method does not fallback between the certificate stores (private trust store vs system certificate stores) or shares them while looking for the trusted anchors.

The client application that wants perform hostname validation using service type can use `expectedServiceDomain` parameter leaving `expectedHostname` empty and vice versa. These two fields are mutually exclusive.

Parameters

  secTrustRef | A reference to the trust object to evaluate.
  completionHandler | A block to be called when the operation is completed. `error` If the operation is successful this parameter is `nil`. If an error occurred it contains an object describing the error.

See also
  CSCertificateManager::validateCertificateWithSecTrustRef(SecTrustRef) expectedServiceDomain:(NSString*) expectedHostname:(NSString*) peerPort:(int) completionHandler:(void (^)(NSError *error))

- (void) validateCertificateWithSecTrustRef: |  | (SecTrustRef) | secTrustRef
expectedServiceDomain: |  | (NSString *) | expectedServiceDomain
expectedHostname: |  | (NSString *) | expectedHostname
peerPort: |  | (int) | peerPort
completionHandler: |  | (void(^)(NSError *error)) | completionHandler

Performs a trust validation of a certificate chain to determine if the secure connection with the peer can be trusted.

While establishing secure connection, the certificate chain is received as part of SSL Handshake that can be validated using this method. The validation result determines if the connection is secure and peer can be trusted. This method performs trust validation asynchronously and upon completion a block is called to post the result.

As per RFC 5280, the trust validation involves a certificate chain building which leads upto a trusted anchors. For client application, if the private trust store has been configured, it will be solely used to build a certificate chain. In a case when the private trust store is unavailable, the system certificate stores will be used. This method does not fall back between the certificate stores (private trust store vs system certificate stores) or shares them while looking for the trusted anchors.

As part of the trust validation, this method performs an extended hostname validation (known as "server identity validation") by matching different identifiers as explained below. The configured hostname is internally supplied by each "Service" or "Provider" calling this method. The client application can configure a policy to ignore the hostname validation errors. Such policy can be set via CSSecurityPolicyConfiguration::continueOnTLSServerIdentityFailure property. By default, this method currently ignores all hostname validation errors.

The hostname is matched as per the following order of identifiers:

1. The match is performed against identifiers like DNS name and IP address from certificate's subject alternative name (SAN) attribute.
2. If subject alternative name attribute is unavailable, the match is performed against certificate's common name (CN) attribute.

For SIP service domains, a full match is performed against URI and DNS parameters value from certificate's subject alternative name attribute.

For Wildcard certificates, a partial matching for DNS hostname is supported except for SIP service domains (RFC 5922).

Following rules apply for partial matching:

- The match is performed at a single level sub-domain. `*`.example.com matches with `foo.example.com` `*`.*.example.com does not match with `foo.bar.example.com`
- Internet TLDs (Top Level Domains) do not match. `*`.com does not match with `example.com` `*`.co.in does not match with `example.co.in`
- Partial domain name match is not supported. `f*`.example.com does not match with `foo.example.com`
- Partial matching for SIP service domain is not supported.

This method verifies certificate's revocation status, however, this feature is not supported on iOS. The revocation status of an entire certificate chain is verified using OCSP or CRL. The revocation check using OCSP is preferred over CRL. The client application can configure the security policy to be used while processing the revocation errors. The security policy can be configured by setting CSSecurityPolicyConfiguration::revocationCheckPolicy.

Parameters

  secTrustRef | A reference to the trust object to evaluate.
  expectedServiceDomain | The domain the server is expected to be authoritative for.
  expectedHostname | The hostname that was used to connect to the server that provided the certificates.
  peerPort | The port number that was used to connect to the server that provided the certificates.
  completionHandler | A block to be called when operation is completed. `error` If the operation is successful this parameter is `nil`. If an error occurred it contains an object describing the error.

See also
  CSSecurityPolicyConfiguration::continueOnTLSServerIdentityFailure
  CSSecurityPolicyConfiguration::revocationCheckPolicy
  - validateCertificateWithSecTrustRef:completionHandler:

## Property Documentation

- (id<CSCertificateManagerClientIdentityDelegate>) clientIdentityDelegate
| read write nonatomic weak

Delegate used to handle events related to client identity certificate's status.

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

- CSCertificateManager.h