Mac Developer Library

Developer

SecurityInterface Framework Reference SFCertificatePanel Class Reference

Options
Deployment Target:

On This Page
Language:

SFCertificatePanel

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 1Certificate panel image: ../Art/cert_panel.eps

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.

Import Statement


Not Applicable

Objective-C

@import SecurityInterface;

Availability


Available in OS X v10.3 and later
  • Returns a shared certificate panel object. If the object has not already been created, this method allocates and initializes the object first.

    Declaration

    Objective-C

    + (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.

    Import Statement

    Objective-C

    @import SecurityInterface;

    Availability

    Available in OS X v10.3 and later.

    See Also

    alloc (NSObject)
    init (NSObject)

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

    Declaration

    Objective-C

    - (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 NOfalse. 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?”).

    Import Statement

    Objective-C

    @import SecurityInterface;

    Availability

    OS X v10.4

  • Displays a Help button in the sheet or panel.

    Declaration

    Objective-C

    - (void)setShowsHelp:(BOOL)showsHelp

    Parameters

    showsHelp

    Set to YEStrue 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 NOfalse, 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 NOfalse and there is no help anchor set.

    Import Statement

    Objective-C

    @import SecurityInterface;

    Availability

    OS X v10.4

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

    Declaration

    Objective-C

    - (NSString *)helpAnchor

    Import Statement

    Objective-C

    @import SecurityInterface;

    Availability

    OS X v10.4

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

    Declaration

    Objective-C

    - (BOOL)showsHelp

    Discussion

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

    Import Statement

    Objective-C

    @import SecurityInterface;

    Availability

    OS X v10.4

  • Customizes the title of the alternate button.

    Declaration

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import SecurityInterface;

    Availability

    OS X v10.4

  • Customizes the title of the default button.

    Declaration

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import SecurityInterface;

    Availability

    OS X v10.4

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

    Declaration

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import SecurityInterface;

    Availability

    OS X v10.4

    See Also

    – policies

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

    Declaration

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import SecurityInterface;

    Availability

    OS X v10.4

  • Displays one or more certificates in a modal sheet.

    Declaration

    Objective-C

    - (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 YEStrue). 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.

    Import Statement

    Objective-C

    @import SecurityInterface;

    Availability

    Available in OS X v10.3 and later.

  • Displays a certificate chain in a modal sheet.

    Declaration

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import SecurityInterface;

    Availability

    Available in OS X v10.5 and later.

  • Returns the SFCertificateView instance for the modal panel.

    Declaration

    Objective-C

    - (SFCertificateView *)certificateView

    Import Statement

    Objective-C

    @import SecurityInterface;

    Availability

    Available in OS X v10.5 and later.

  • Displays one or more specified certificates in a modal panel.

    Declaration

    Objective-C

    - (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 NOfalse.

    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 YEStrue). 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.

    Import Statement

    Objective-C

    @import SecurityInterface;

    Availability

    Available in OS X v10.3 and later.

  • Displays a certificate chain in a modal panel.

    Declaration

    Objective-C

    - (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 NOfalse.

    Return Value

    This method returns the integer constant NSOKButton when dismissed.

    Import Statement

    Objective-C

    @import SecurityInterface;

    Availability

    Available in OS X v10.5 and later.

  • Implements custom help behavior for the modal panel.

    Declaration

    Objective-C

    - (BOOL)certificatePanelShowHelp:(SFCertificatePanel *)sender

    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.

    Import Statement

    Objective-C

    @import SecurityInterface;

    Availability

    OS X v10.4

    See Also

    – setShowsHelp:
    setDelegate: (NSWindow)