|
Avaya Client Services API Reference (iOS)
|
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 a provisioned client identity certificate and a private key. More... | |
| (NSError *) | - setClientIdentityCertificateFromPKCS12Data:withPassword: |
| DEPRECATED since 241.0.0. More... | |
| (BOOL) | - setClientIdentity:withCertificateChain:error: |
| Securely stores a client identity certificate and a private key to use during mutual authentication. 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... | |
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.
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.
| - (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.
nil in case the private trust store is absent.| - (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.
SecCertificateRef objects if private trust store exists; nil when private trust store is absent.| - (SecIdentityRef) clientIdentity |
Returns a provisioned client identity.
SecIdentityRef object containing client identity certificates and a private key. If client identity is not provisioned, it returns nil.| - (CFArrayRef) clientIdentityCertificateChain |
Returns a provisioned client identity certificate (chain).
SecCertificateRef containing client identity certificate chain. If the client identity is not provisioned, it returns nil.| - (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.
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.
| - (BOOL) deleteClientIdentityWithError: | (NSError **) | errorResult |
Deletes a provisioned client identity certificate and a private key.
Items are deleted from application keychain.
Client application can modify the client certificate by deleting an existing certificate and setting newer one.
| errorResult | error If the operation is successful this parameter is nil. If an error occurred it contains an object describing the error. |
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.
| 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.
YES The private trust store exists. NO The private trust store is absent.| - (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.
| 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. |
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 | |
Securely stores a client identity certificate and a private key to use during mutual authentication.
Items are recored in application keychain.
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.
| secIdentity | A reference to SecIdentityRef containing the client identity mainly private key. |
| 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. |
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.
| 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. |
| - (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:
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:
*.example.com matches with foo.example.com *.*.example.com does not match with foo.bar.example.com *.com does not match with example.com *.co.in does not match with example.co.in f*.example.com does not match with foo.example.com 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.
| 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. |
|
readwritenonatomicweak |
Delegate used to handle events related to client identity certificate's status.