# SSL Certificate Dialogs

There are two dialog boxes which can show information about one or more certificates.

Both dialog boxes have the following elements:

- Four buttons whose texts can vary ( Ok/Accept, Cancel, Delete/Install, Help). Some of the buttons may be hidden, depending on what the dialog is supposed to do.
- A field for messages.
- Two smaller boxes to display the name of the subject for which the certificate is issued, and the name of the issuer.
- One larger box to present a text representation of the contents of the certificate.

The single certificate box has only the above components.

The multiple certificate box also has the following:

- A selection box with a listing of available certificates. Selecting an item in this box displays the certificate in the subject, issuer and contents boxes.
- Two optional check boxes which can be used to select that connections to servers certified by a CA is allowed, and whether or not to warn the user before accepting connection to a site certified by that CA.
- Some of the dialogs can have import and export buttons.

Different organizations of these elements can be implemented. The present desktop version (v10.x) is using a view button to open up a dialog with the common certificate information elements for dialogs that can contain multiple certificates, and have combined these fields in a single view.

## API

The SSL_Certificate_DisplayContext class is performing all information retrieval from the certificates, and provides the Certificate dialog implementation with the necessart information about which dialog elements are needed, which messages to display, and maintains the state of the dialog such as which certificate is displayed, and what actions have been selected.

SSL_Certificate_DisplayContext is defined in libssl/ui/sslcctx.h

A certificate dialog implementation must define an implementation of the class OpSSLListener, defined in "modules/windowcommander/OpWindowCommander.h", as per WindowCommander guidelines.

All dialog operations are asynchronous, and the SSL_Certificate_DisplayContext object must be updated with the result of the operation before the caller is signaled.

        SSL_Certificate_DisplayContext *ctx;

For the ctx object the following functions are available:

- ctx->IsSingleOnlyCert() : Single or multiple certificate dialog box
- ctx->GetShowCertificateOptions() : With or without allow/warn checkboxes (only for FALSE IsSingleOnlyCert)
- ctx->GetTitle() : Str::LocaleString ID for the title bar text
- ctx->GetMessage() : Str::LocaleString ID for the message text
- ctx->GetHideCancel() : Do not display the Cancel button
- ctx->GetOKButtonIsAcceptButton : Use the text "Accept" on the "OK" button instead of "OK"
- ctx->GetShowDeleteInstallButton() : Display the "Delete" button
- ctx->GetDeleteInstallButtonIsInstall: Use the text "Install" on the "Delete" button instead of "Delete".
- ctx->GetShowImportButton(): Display an import button. This is used to allow import of certificates and/or private keys.
- ctx->GetShowExportButton(): Display an export button. This is used to allow export of certificates and/or private keys.

For the multiple certificate box the following operations are required (psuedocode)

- Get list of names for the certificates

This code MUST be done during intializtion, several operations are not possible until after this list have been processed.

      OpString name;
      int i= 0;
      while(ctx->GetCertificateShortName(name, i)) // nullteminated string
      {
          AddStringToListBox((char *) name.CStr()) // GetDirect() gives pointer to the buffer
      }
      ctx->SetCurrentCertificateNumber(0);

- Update the current certificate item

Whenever the current entry in the certificate list is changed ctx->SetCurrentCertificateNumber(i) must be called, and the certificate display boxes must be updated.

- Displaying the current certificate item (both dialog types)

      OpString subject, issuer, data;
      BOOL allow_flag, warn_flag;

      ctx->GetCurrentCertificateTexts(subject, issuer, data, allow_flag, warn_flag);
      SetSubjectTextBox_text((char *) subject.CStr())
      SetIssuerTextBox_text((char *) issuer.CStr())
      SetCertDataTextBox_text((char *) data.CStr())

      if(ctx->GetShowCertificateOptions())
        UpdateAllowWarnToggles(allow_flag,warn_flag);

In addition to the above interface, certificate validation can add a number of comment strings that can either be included in the data field, or reatrieved and displayed separately. These comments describe various problems detected with the displayed certificates, beside the reason given in the dialog message.

By default these comments are included in the data element, but this may be disabled by using

      ctx->SetDisplayCertCommentsInView(FALSE);

ctx->GetDisplayCertCommentsInView() will return the current status of this flag.

To retrieve the list of comments the dialog manager should use

      OpstringC *comment;
      int i;

      comment = ctx->AccessCertificateComment(i);

comment is NULL if there is no comment for value i. The index is always in the range 0..n-1, and the function will return NULL for any index >= n

- Updating the context checkbox toggles

When ctx->GetShowCertificateOptions() is TRUE, changes in the allow/warn checkboxes should be immediately signalled to the context with

      ctx->UpdateCurrentCertificate(allow_flag, warn_flag);

- Performing action

When one of the buttons (OK, Cancel, Delete) is clicked the dialog must signal these actions using the PerformAction function :

      ssl_cert_button_action  button;
      ssl_cert_display_action action;

      action = ctx->PerformAction(button);

button is one of

SSL_CERT_BUTTON_OK
  The OK/Accept button was clicked.
SSL_CERT_BUTTON_CANCEL
  The Cancel button was clicked
SSL_CERT_BUTTON_INSTALL_DELETE
  The Delete/Install button was clicked

||

The return value action can be one of

SSL_CERT_DO_NOTHING
  Do nothing :-)
SSL_CERT_CLOSE_WINDOW
  Close the dialog box, and return to caller.
SSL_CERT_DELETE_CURRENT_ITEM
  Delete the current item in the certificate name list and update current position to move to the next certificate in the list if possible.

- Import/Export of certificates and/or private keys

The certificate context can import and export cerificates to and from a file. The dialog manager must provide the filename.

    	OpString filename;
    	OpString extension;

    	SSL_dialog_config dialogconfig(window, mh, message, id); // All values application specific
    	SSL_Certificate_Installer_Base *installer_handler = NULL;

    	BOOL success = ctx->ImportCertificate(filename, dialogconfig, installer_handler);
    	// After completed
    	OP_DELETE(installer_handler);

    	SSL_Certificate_Installer_Base *export_handler = NULL;
    	OP_STATUS export_success = ctx->ExportCertificate(filename, extension, dialogconfig, installer_handler);
    	// After completed
    	OP_DELETE(installer_handler);

Opera presently support the following filetypes defined in the language strings Str::SI_IMPORT_USER_CERTIFICATE_TYPES (for client certificate import, only if ctx->GetTitle() == Str::SI_SITE_CERT_DLG_TITLE) and Str::SI_IMEXPORT_OTHER_CERTIFICATE_TYPES

- X509
- PKCS 7 (just signed message or full message)
- PEM files (of the above formats)

For client certificates PKCS 12 (certificate and private key) is also supported.

For the export call the extension MUST be one of the following

- p12 (PKCS 12)
- p7s (PKCS 7 signed)
- p7 (PKCS 7 full)
- pem (PEM file of X509)
- usr (X509 binary, client only)
- crt (X509 binary, authority only)

For any other extension X509 binary is assumed.

### Advanced: Direct access to certificate items

Some platforms are not able to use the ctx->GetCurrentCertificateTexts output due to screen size limitations.

In these cases the platform MAY use

      URL info;
      BOOL warn, deny;
      OpString text_field;
      Str::LocaleString description;
      SSL_Certinfo_mode info_type

      info = ctx->AccessCurrentCertificateInfo(warn, deny, text_field, description, info_type);

text_field is currently not used, but will in some future versions contain information about the location of the certificate's private key, such as in relation to smartcards.

description is a language string enum used as a caption for the certifiacte display in XML mode

info_type defines which field(s) to retrieve (e.g the whole certificate, just subject name, etc), and what format to use, XML or plain text.

If there is no certificate information available info is an empty URL.

The document in the returned URL is either an XML or a text document. The XML format for the full certificate is a machine readable document, that can also be rendered directly in a viewer.