SSL Certificate Dialogs

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

Both dialog boxes have the following elements:

The single certificate box has only the above components.

The multiple certificate box also has the following:

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:

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

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);

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

  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

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);

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.

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

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

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

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.