SFCertificateTrustPanel Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/SecurityInterface.framework
Availability
Available in OS X v10.3 and later
Companion guide
Declared in
SFCertificateTrustPanel.h

Overview

The SFCertificateTrustPanel class opens a panel or sheet that lets the user edit the trust settings in any of the certificates in a certificate chain.

The following figure shows an example of a certificate trust panel.

Figure 1  Certificate trust panel
Certificate trust panel

You can use this class to enable a user to make trust decisions when one or more certificates required for an operation are invalid or cannot be verified.

To display a certificate in a panel or sheet without editable trust settings, use the SFCertificatePanel class. To display certificates in a custom view, use the SFCertificateView class.

Tasks

Returning a Shared Certificate Trust Panel Object

Displaying a Sheet or Panel

Controlling the Appearance of a Certificate Trust Panel

Class Methods

sharedCertificateTrustPanel

Returns a shared certificate trust panel object. If the object has not already been created, this method allocates and initializes the object first.

+ (SFCertificateTrustPanel *)sharedCertificateTrustPanel
Discussion

Use this method if your application displays a single certificate trust panel or sheet at a time. If your application can display multiple certificate trust panels or sheets at once, you must allocate separate object instances (using the alloc class method inherited from NSObject) and initialize (using the init instance method, also inherited from NSObject) instead of using this class method.

Availability
  • Available in OS X v10.3 and later.
See Also
Declared In
SFCertificateTrustPanel.h

Instance Methods

beginSheetForWindow:modalDelegate:didEndSelector:contextInfo:trust:message:

Displays a modal sheet that shows the results of a certificate trust evaluation and that allows the user to edit trust settings.

- (void)beginSheetForWindow:(NSWindow *)docWindow modalDelegate:(id)delegate didEndSelector:(SEL)didEndSelector contextInfo:(void *)contextInfo trust:(SecTrustRef)trust message:(NSString *)message
Parameters
docWindow

The parent window to which the sheet is attached.

delegate

The delegate object in which the method specified in the didEndSelector parameter is implemented.

didEndSelector

A method selector for a delegate method called when the sheet has been dismissed. Implementation of this delegate method is optional.

contextInfo

A pointer to data that is passed to the delegate method. You can use this data pointer for any purpose you wish.

trust

A trust management object. Use the SecTrustCreateWithCertificates function (in Security/SecTrust.h) to create the trust management object.

message

A message string to display in the sheet.

Discussion

The delegate method has the following signature:

-(void)createPanelDidEnd:(NSWindow *)sheet
       returnCode:(int)returnCode
       contextInfo:(void *)contextInfo

The parameters for the delegate method are:

sheet

The window to which the sheet was attached.

returnCode

The result code indicating which button the user clicked: either NSFileHandlingPanelOKButton or NSFileHandlingPanelCancelButton.

contextInfo

Client-defined contextual data that is passed in the contextInfo parameter of the beginSheetForWindow:... method.

The delegate method may dismiss the keychain settings sheet itself; if it does not, the sheet is dismissed on return from the beginSheetForWindow:... method.

Availability
  • Available in OS X v10.3 and later.
Declared In
SFCertificateTrustPanel.h

informativeText

Returns the (optional) informative text currently displayed in the panel.

- (NSString *)informativeText
Availability
  • Available in OS X v10.5 and later.
Declared In
SFCertificateTrustPanel.h

runModalForTrust:message:

Displays a modal panel that shows the results of a certificate trust evaluation and that allows the user to edit trust settings.

- (NSInteger)runModalForTrust:(SecTrustRef)trust message:(NSString *)message
Parameters
trust

A trust management object. Use the SecTrustCreateWithCertificates function (in Security/SecTrust.h) to create the trust management object.

message

A message string to display in the panel.

Discussion

This method returns NSOKButton if the default button is clicked, or NSCancelButton if the alternate button is clicked.

The user can use this panel to edit trust decisions for the specified certificate or for any of the certificates in the certificate chain. The trust settings are saved when the user clicks the default button. Call SecTrustGetUserTrust to obtain the user’s trust settings.

Note that changing the user trust settings does not affect the results of a trust evaluation. Therefore, the trust evaluation shown in the panel (such as “This certificate is not yet valid”) does not change, nor does the result of a call to SecTrustGetResult. It is up to your application to determine how to handle the user’s trust decision.

Availability
  • Available in OS X v10.3 and later.
Declared In
SFCertificateTrustPanel.h

setInformativeText:

Sets the (optional) informative text displayed in the SFCertificateTrustPanel.

- (void)setInformativeText:(NSString *)informativeText
Parameters
informativeText

By default, informative text describing the current certificate’s trust status is displayed. Call this method only if your application needs to customize the displayed informative text.

Availability
  • Available in OS X v10.5 and later.
Declared In
SFCertificateTrustPanel.h