SFCertificatePanel Class Reference

Inherits from
NSPanel : NSWindow : NSResponder : NSObject
Conforms to
NSSplitViewDelegate
NSUserInterfaceValidations (NSWindow)
NSAnimatablePropertyContainer (NSWindow)
NSUserInterfaceItemIdentification (NSWindow)
NSCoding (NSResponder)
NSObject (NSObject)
Framework
/System/Library/Frameworks/SecurityInterface.framework
Availability
Available in OS X v10.3 and later
Companion guide
Certificate, Key, and Trust Services Programming Guide
Declared in
SFCertificatePanel.h

Overview

The SFCertificatePanel class displays one or more certificates in a panel or sheet. It can optionally display all of the certificates in a certificate chain.

The following figure shows an example of a certificate panel.

Figure 1  Certificate panel
Certificate panel

This class displays certificate details, but not trust settings. To display a certificate with editable trust settings in a panel or sheet, use the SFCertificateTrustPanel class (SFCertificateTrustPanel). To display certificates in a custom view, use the SFCertificateView class (SFCertificateView).

Note that for OS X v10.4 and later, this class displays the evaluation status for each certificate. You can modify how the certificates are evaluated by calling the setPolicies: method.

Tasks

Returning a Shared Certificate Panel Object

Providing Help

Customizing the Appearance of the Sheet or Panel

Displaying a Sheet or Panel

Delegate Method for Providing Help

Class Methods

sharedCertificatePanel

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

+ (SFCertificatePanel *)sharedCertificatePanel
Discussion

Use this method if your application displays a single certificate panel or sheet at a time. If your application can display multiple certificate panels or sheets at once, you must allocate separate object instances (using the alloc class method inherited from NSObject) and initialize them (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
SFCertificatePanel.h

Instance Methods

beginSheetForWindow:modalDelegate:didEndSelector:contextInfo:certificates:showGroup:

Displays one or more certificates in a modal sheet.

- (void)beginSheetForWindow:(NSWindow *)docWindow modalDelegate:(id)delegate didEndSelector:(SEL)didEndSelector contextInfo:(void *)contextInfo certificates:(NSArray *)certificates showGroup:(BOOL)showGroup
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 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.

certificates

The certificates to display. Pass an NSArray containing one or more objects of type SecCertificateRef in this parameter. The first certificate in the array must be the leaf certificate. The other certificates (if any) can be included in any order.

showGroup

Specifies whether additional certificates (other than the leaf certificate) are displayed.

Discussion

The behavior of this method is somewhat different in OS X v10.4 and later versus OS X v10.3. In OS X v10.3, the sheet displays whatever certificates you pass in the certificates parameter (provided the showGroup parameter is set to YES). Starting with OS X v10.4, the sheet displays the leaf certificate (that is, the first certificate in the array you pass) plus any other certificates in the certificate chain that the Security Server can find. If you include all of the certificates in the chain in the certificates parameter, you can ensure that the same certificates are displayed whatever the version of the operating system, and may decrease the time required to find and display the certificates in OS X v10.4 and later.

The delegate method has the following signature:

-(void)certificateSheetDidEnd:(NSWindow *)sheet
       returnCode:(NSInteger)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 beginSheetForDirectory:... method.

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

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

beginSheetForWindow:modalDelegate:didEndSelector:contextInfo:trust:showGroup:

Displays a certificate chain in a modal sheet.

- (void)beginSheetForWindow:(NSWindow *)docWindow modalDelegate:(id)delegate didEndSelector:(SEL)didEndSelector contextInfo:(void *)contextInfo trust:(SecTrustRef)trust showGroup:(BOOL)showGroup
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 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 SecTrustRef object for the certificates to be displayed.

showGroup

Specifies whether additional certificates (other than the leaf certificate) are displayed.

Discussion

The sheet displays the leaf certificate plus any other certificates in the certificate chain that the Security Server can find.

The delegate method has the following signature:

-(void)certificateSheetDidEnd:(NSWindow *)sheet
       returnCode:(NSInteger)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 beginSheetForDirectory:... method.

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

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

certificateView

Returns the SFCertificateView instance for the modal panel.

- (SFCertificateView *)certificateView
Availability
  • Available in OS X v10.5 and later.
Declared In
SFCertificatePanel.h

helpAnchor

Returns the current help anchor string for the sheet or panel.

- (NSString *)helpAnchor
Availability
  • OS X v10.4
See Also
Declared In
SFCertificatePanel.h

policies

Returns an array of policies used to evaluate the status of the displayed certificates.

- (NSArray *)policies
Discussion

This method returns an autoreleased NSArray containing one or more objects of type SecPolicyRef , as set by a previous setPolicies: call, or the Apple X.509 Basic Policy if setPolicies: has not been called. See “AppleX509TP Trust Policies” in Certificate, Key, and Trust Services Reference for a list of policies and object identifiers provided by the AppleX509TP module.

Availability
  • OS X v10.4
See Also
Declared In
SFCertificatePanel.h

runModalForCertificates:showGroup:

Displays one or more specified certificates in a modal panel.

- (NSInteger)runModalForCertificates:(NSArray *)certificates showGroup:(BOOL)showGroup
Parameters
certificates

The certificates to display. Pass an NSArray containing one or more objects of type SecCertificateRef in this parameter. The first certificate in the array must be the leaf certificate. The other certificates (if any) can be included in any order.

showGroup

Specifies whether additional certificates (other than the leaf certificate) are displayed. To show only a single certificate, specify only one SecCertificateRef in the array and set showGroup to NO.

Return Value

This method returns the integer constant NSOKButton when dismissed.

Discussion

The behavior of this method is somewhat different in OS X v10.4 and later versus OS X v10.3. In OS X v10.3, the panel displays whatever certificates you pass in the certificates parameter (provided the showGroup parameter is set to YES). Starting with OS X v10.4, the panel displays the leaf certificate (that is, the first certificate in the array you pass) plus any other certificates in the certificate chain that the Security Server can find. If you include all of the certificates in the chain in the certificates parameter, you can ensure that the same certificates are displayed whatever the version of the operating system, and may decrease the time required to find and display the certificates in OS X v10.4 and later.

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

runModalForTrust:showGroup:

Displays a certificate chain in a modal panel.

- (NSInteger)runModalForTrust:(SecTrustRef)trust showGroup:(BOOL)showGroup
Parameters
trust

A SecTrustRef object associated with the certificate chain to display.

showGroup

Specifies whether additional certificates (other than the leaf certificate) are displayed. To show only a single certificate, specify only one SecCertificateRef in the array and set showGroup to NO.

Return Value

This method returns the integer constant NSOKButton when dismissed.

Availability
  • Available in OS X v10.5 and later.
See Also
Declared In
SFCertificatePanel.h

setAlternateButtonTitle:

Customizes the title of the alternate button.

- (void)setAlternateButtonTitle:(NSString *)title
Parameters
title

The new title for the alternate button. If this method is not called, or if title is set to nil, the button is not shown.

Discussion

The alternate button is typically labelled “Cancel”. The alternate button dismisses the sheet or panel and returns a value of NSCancelButton.

Availability
  • OS X v10.4
See Also
Declared In
SFCertificatePanel.h

setDefaultButtonTitle:

Customizes the title of the default button.

- (void)setDefaultButtonTitle:(NSString *)title
Parameters
title

The new title for the default button. The default title for this button is “OK”.

Discussion

The default button dismisses the sheet or panel and returns a value of NSOKButton.

Availability
  • OS X v10.4
See Also
Declared In
SFCertificatePanel.h

setHelpAnchor:

Sets the help anchor string for the sheet or modal panel.

- (void)setHelpAnchor:(NSString *)anchor
Parameters
anchor

The new help anchor string.

Discussion

You may call this function to set a help anchor string if you display a help button in the sheet or modal panel and do not implement the delegate method certificatePanelShowHelp:, or if the delegate method returns NO. If you display a help button, do not set a help anchor string, and do not implement a delegate, the certificate panel displays a default help page (“Why isn’t a certificate being accepted?”).

Availability
  • OS X v10.4
See Also
Declared In
SFCertificatePanel.h

setPolicies:

Specifies one or more policies that apply to the displayed certificates.

- (void)setPolicies:(id)policies
Parameters
policies

The policies to use when evaluating the certificates’ status. You can pass either a SecPolicyRef object or an NSArray (containing one or more SecPolicyRef instances) in this parameter. If policies is set to nil, the Apple X.509 Basic Policy is used.

Discussion

Applications typically display a certificate panel in the context of a specific use, such as SSL or S/MIME. You should set only the policy references that apply to your intended use. See “AppleX509TP Trust Policies” for a list of policies and object identifiers provided by the AppleX509TP module.

Availability
  • OS X v10.4
See Also
Declared In
SFCertificatePanel.h

setShowsHelp:

Displays a Help button in the sheet or panel.

- (void)setShowsHelp:(BOOL)showsHelp
Parameters
showsHelp

Set to YES to display the help button. The help button is hidden by default.

Discussion

When a user clicks the help button, the certificate panel first checks the delegate for a certificatePanelShowHelp: method. If the delegate does not implement such a method, or the delegate method returns NO, then the NSHelpManager method openHelpAnchor:inBook: is called with a nil book and the anchor specified by the setHelpAnchor: method. An exception is raised if the delegate returns NO and there is no help anchor set.

Availability
  • OS X v10.4
See Also
Declared In
SFCertificatePanel.h

showsHelp

Indicates whether the help button is currently set to be displayed.

- (BOOL)showsHelp
Discussion

This method returns YES if the help button is currently set to be displayed.

Availability
  • OS X v10.4
See Also
Declared In
SFCertificatePanel.h

Delegate Methods

certificatePanelShowHelp:

Implements custom help behavior for the modal panel.

- (BOOL)certificatePanelShowHelp:(SFCertificatePanel *)sender
Parameters
sender

The certificate panel for which to implement custom help.

Discussion

You can use this delegate method to implement custom help if you call the setShowsHelp: method to display a help button in the sheet or panel. If you are not implementing custom help, do not implement this method.

Availability
  • OS X v10.4
See Also
Declared In
SFCertificatePanel.h


© 2012 Apple Inc. All Rights Reserved. (Last updated: 2012-06-11)

Did this document help you? Yes It's good, but... Not helpful...