View source for Dialog: Administer OPC UA Application

This dialog allows you to administer the OPC UA application. It contains settings and operations that enable the OPC UA application to coexist and communicate properly in the operating system and in the OPC UA ecosystem.

The "Administer OPC UA Application" dialog allows:

* Viewing and managing trusted certificates. The user can change the Trusted, issuer and Rejected states of the certificates, import certificates, and delete certificates.
* Managing the own application certificate, either using self-signed approach, or from an OPC UA Global Discovery Server (GDS). The application certificate can be exported or imported. The user can also protect the private key of the certificate with a password, or unprotect it. Automatic fixes are offered for common issues with the application certificate.
* Viewing OPC UA application manifest.

The above listed aspects correspond to individual tabs on the dialog. If there is an important issue that needs your attention, the affected tab is displayed with an error or warning icon. 

You can switch between the tabs as needed. When you are done with the dialog, press {{Style=keyboard|Esc}} or click the little cross icon in the upper right corner.

= Trusted Certificates tab =

The Trusted Certificates tab shows the certificates in various certificates stores of the application, and allows you to view and change how the application you are administering trusts other OPC UA applications.

[[File:UAManageTrustedCertificatesControl.png|center|Trusted Certificates tab]]

== Certificates grid ==

The certificates are displayed in a single table (grid), with their trust status indicated textually and by an icon. In reality, the certificates are stored in several certificate stores with different purposes. The table shows a logical view, where the trust status is inferred from the placement of the certificate. Operations that change the trust status do, in fact, copy, move and remove certificates in the certificate stores.

Information in the table that may need your attention is distinguished by formatting: for example, certificate validity dates that are expired are displayed in different color.

You can sort the table in ascending or descending order by clicking (or repeated clicking) the column header you want to sort on. Column widths are sized automatically, but can also be adjusted by dragging the divider line between the columns in the header area. Hovering over an incomplete information (for example, if the column is too short) shows a tooltip with the full content of the table cell.

Select the certificate you want to work with by clicking on its row in the table, or using the arrow keys on the keyboard when the table is focused.

== Actions ==

; Trust Status&#x3A; Trusted
: Sets or resets the Trusted status of the selected certificate. Self-signed, leaf, root CA or sub-CA certificates can be trusted. A certificate that is neither Trusted nor an Issuer or Own certificate is automatically given the Rejected status; conversely, the Rejected status is removed from any certificate that is Trusted.

; Trust Status&#x3A; Issuer
: Sets or resets the Issuer status of the selected certificate. Issuer certificates are certificates used for validation of the certificate chain, but are not by itself trusted. A certificate that is neither Issuer nor Trusted or Own certificate is automatically given the Rejected status; conversely, the Rejected status is removed from any certificate that is has an Issuer status.

; Trust Status&#x3A; Rejected
: Sets or resets the Rejected status of the selected certificate. Rejected certificates do not participate in trust evaluation; they are just conveniently "marked" for further review or deletion. Setting the Rejected status automatically removed the Trusted and Issuer stattsu form the certificate; removing the Rejected status from the certificate gives the certificate the Trusted status.

Note: "'''Revoked'''" status is different from "Rejected". "Revoked" means that a Certificate Revocation List (CRL) has been issued that marks the specific certificate as revoked (e.g. because its security has been compromised). You cannot change the "Revoked" status of the certificate.

; Delete
: Permanently deletes the selected certificate from all application certificate stores. The dialog will ask you for confirmation. This action cannot be reversed. If you are not sure, you can Reject the certificate instead. The effect on the trust will be the same, but the Rejected certificate status can be changed to Trusted or Issuer again easily.

; Inspect
: Displays all properties of the selected certificate in a property grid.

; View
: Shows the selected certificate using the standard operating system (Windows) user interface.

; Import Trusted
: Imports a certificate from a file, and makes it a Trusted certificate. You can select from several file formats.

; Import Issuer
: Imports a certificate from a file, and makes it an Issuer certificate. You can select from several file formats.

; CM Operations&#x3A; Refresh Trust Lists
: Retrieves the current trust lists for the application from the Certificate Manager (CM)/Global Discovery Server (GDS), and refreshes own certificate stores accordingly. Use this command if the certificate stores of your application are not up-to-date. The CM/GDS endpoint is configured elsewhere in the application.

== Other controls ==

; Shared stores: Indicates whether the certificate stores (where the certificates displayed in the tab are located) are possibly shared with other applications. Note: The value displayed is based on the common locations of certificate stores. In case some the locations are configured in a special way, the status might not be correct.
:; No: The certificate stores are configured to serve this application only. 
:; Mixed: Some of the certificate stores are configured to serve this application only, while others are shared by multiple applications on the computer.
:; Yes: The application uses certificate stores that are shared by multiple applications on the computer.
: When the shared status is "Mixed" or "Yes", you need to be aware that operation that you make in this tab also affect the trust settings of other applications on the computer. In order to find the location of individual certificate stores, hover the mouse cursor over the shared status value, and a tooltip will be shown with store locations, and statistics of their usage. You can also switch to the Application Manifest to view how the certificate stores are configured.

; Refresh View: Press this button in case the contents of certificate stores might have changed by an external actor, i.e. by something that has not been invoked from this dialog - for example, if you have manually copied some certificate into the store, or removed it.

; Store errors: If there is a problem opening any of the application's certificate stores, and error icon will appear near the "Refresh View" button, and by hovering over the icon, you can obtain more information about the error(s).

= Application Certificate tab =
The Application Certificate tab allows you to view and manage the own application certificate.

The left side of the tab contains various operations that you can do to manage the certificate. The right side of the tab displays the properties of the current certificate (see "Own Certificate View" below). This way, you can always quickly check the effect of your commands on the certificate.

The certificate can be managed either using self-signed approach, or from an OPC UA Global Discovery Server (GDS). You can export or import the certificate, and you can also protect the private key of the certificate with a password, or unprotect it.

[[File:UAManageOwnCertificateControl.png|center|Application Certificate tab]]

== Create own self-signed certificate ==
This group of controls is for environments where the OPC UA certificates are managed using the self-signed approach. In such environments, there is no centralized Certificate Authority (CA), and the trust between applications (peers) needs to be established on on-by-one basis. This is usually the initial setup for experiments and simpler solutions. It becomes cumbersome to manage in larger system, and it lacks some security features - for example, there is also no standardized provision for revoking compromised certificates. 

; Validity period
: Validity period of the certificate that will be generated, in months. If you use zero, the program will select a reasonable validity period automatically. A drop-down list offers common validity periods, starting form 1 month up to 600 months (50 years).

; Minimum key size
: Minimum key size of the certificate that will be generated, in bits. If you use zero, the program will select a reasonable minimum key size automatically. A drop-down list offers common key sizes of 1024, 2048, 3072 and 4096 bits.

; Create/recreate own certificate
: Creates the own application certificate, using the parameters (validity period, minimum key size) specified in the controls above. This is a self-signed certificate. The private key password protection, if active, is maintained with the same password. 

; ...with no private key protection
: Same as "Create/recreate own certificate", but the resulting certificate is always stored without any password protection (empty password).

; ...and protect private key by new password
: Same as "Create/recreate own certificate", but you will be prompted for a new password and its confirmation, and the resulting certificate will be stored with its private key protected by the specified password.

== Obtain new certificate from OPC UA GDS ==
{{Note|Certificate operations with Global Discovery Server (GDS) may not be available, e.g. due to software licensing reasons. In such case, elements in this group may be disabled, and a corresponding explanatory message is displayed in a tooltip.}}

This group of controls is for environments where the OPC UA certificates are managed centrally, using the so-called OPC UA Certificate Manager (CM), usually integrated with an OPC UA Global Discovery Server (GDS). Among other functionality, the Certificate Manager acts as a Certificate Authority (CA) for Public Key Infrastructure (PKI).

; GDS endpoint (with Certificate Manager)
: The URL of the Global Discovery Server. The URL can be entered manually, or you can browse for it (using the {{Style=button|...}} button. Additional operations related to the endpoint input are available through the drop-down button {{Style=button|&#x25be;}}. Commonly, you may need to specify the {{Style=menu|User Identity}}, and/or change the {{Style=menu|Endpoint Selection Policy}}.

; Certificate type
: Select the type of certificate that should be issued by the GDS. There are typically several options, and the choice may depend on who will "consume" the certificate, i.e. who will be the parties (application) that need to trust this application's certificate. The certificate type is optional, and when left empty, the most appropriate type will be chosen automatically. The list of available certificate types comes from the GDS. If it cannot be obtained for some reason, a "fallback" list of well-known certificate types is offered instead.

; Obtain/reobtain new certificate
: Obtains a new application own certificate from the certificate manager, and stores it as current certificate for subsequent usage. The private key password protection, if active, is maintained with the same password. The operation involves multiple steps and displays progress messages accordingly.

; ...with no private key password protection
: Same as "Obtain/reobtain new certificate", but the resulting certificate is always stored without any password protection (empty password).

; ...and protect private key by new password
: Same as "Obtain/reobtain new certificate", but you will be prompted for a new password and its confirmation, and the resulting certificate will be stored with its private key protected by the specified password.

; Refresh trust lists
: Retrieves the current trust lists for the application from the Certificate Manager (CM)/Global Discovery Server (GDS), and refreshes own certificate stores accordingly. Use this command if the certificate stores of your application are not up-to-date. Note that trust lists are refreshed automatically after when you obtain/reobtain a certificate from the GDS.

== Import/export application certificate ==
Controls in this group allow you to exchange the application own certificate with other applications or systems using files.

; Import certificate from file
: Imports the current application certificate, together with its private key, from a specified file. The file must currently be in the PFX format. Use this command if you have generated the application certificate using some external tool, such as the OPC UA Certificate Generator utility. If the private key of the certificate in the file is protected by a password, and the password is different from what is currently configured in the application, you will be asked to enter the password, before the import can proceed.

; Export certificate to file
: Exports the current application certificate, without the private key, into a specified file. You can choose between the several file formats: CER files (*.cer), DER files (*.der) - the default, PFX files (*.pfx), and PKCS #12 files (*.p12). The dialog will offer a file name based on the current certificate subject name, but you can change it to anything you like. Use this command if you have another application that needs to trust this application, and the other application is capable of importing the certificate and will then trust it.

; Export certificate with private key to file
: Exports the current application certificate, <u>together with its private key</u>, into a specified file. You can choose between the PFX file format (*.pfx) - the default, or PKCS #12 (*.p12). You can optionally protect the private key of the exported certificate with a password that you enter. This command is used rarely, possibly to back-up the existing application or transfer it to a new hardware.

{{Warning|Do not use the "Export certificate with private key to file" command to obtain file for establishing trust with other applications. The private key of the certificate is not needed for this purpose, and shall not be exposed in this way. Doing so would have serious negative security implications.}}

== Remove own certificate ==
Pressing the {{Style=button|Remove own certificate}} button will remove the current own certificate, together with its private key, from the certificate store. This action cannot be reversed.

== Private key protection ==
{{Note|Not all applications allow changing the certificate private key password. In such applications, corresponding elements in this group are not visible.}}

Certificates have public and private keys. The private key of the certificate is the secret part of it. It needs to be secured in such a way that only authorized entities - such as the application itself - have access to it. This is done by various ways, e.g. by storing the certificate's private key in a secure certificate store, which uses operating system mechanism to guard access only to selected users. An additional protection can be made using the private key password. In this case, the certificate's private key is unusable without also having the correct password.

When working with controls in this group, you need to keep in mind that for the application to work, the private key password configured in the application must match the actual password by which the private key of the current certificate is protected. By making a mistake in administering the application, these passwords can become out of sync, rendering the secure communications of the application impossible. The dialog detects such situation and warns about it, though.

; Protect by new password
: This operation asks you for a new password and its confirmation, and then protects the private key of the certificate with it.

; Unprotect (empty password)
: This operation removes the password protection from the private key.

; Private key password configured
: Indicates whether or not the application is configured to use password to access the private key of the certificate, and/or to create/recreate or obtain/reobtain new certificates. The indication does *not* reflect the status of the private key password protection of the certificate as such.

; Set
: Set the password that the application will use to access the certificate private key. This does *not* affect status of the private key password protection of the certificate as such.

; Reset
: Reset (remove) the password that the application uses to access the private key. This does *not* affect status of the private key password protection of the certificate as such.

== Own Certificate View ==
The Own Certificate View forms the right side of the Application Certificate tab. For most part, it is a read-only view of the current application certificate, in a property grid.

When there is no own certificate available, either because it is simply missing, or due to some error accessing the certificate store, the property grid is replaced by an information box which provides more information related to the status or error.

By default, the properties in the property grid are displayed grouped into logical categories. Using the button icons above the grid, you can switch between this categorized view, and an alphabetically sorted view.

The "Refresh View" button can be used when the certificate might have been changed by an external actor, i.e. by something that has not been invoked from this dialog - for example, if you have manually copied the certificate into the store, or removed it.

Pressing the {{Style=button|View}} button shows the current own certificate using the standard operating system (Windows) user interface.

A colored caption bar above the property grid shows the current status of the own certificate. The program makes an analysis of various aspects related to the own certificate, and shows hints, warning and errors from the analysis. In order to obtain lengthier explanation of the status, hover the mouse cursor over the colored status caption bar. In some cases, there is also a {{Style=button|More}} button displayed next to the status caption. Press this button to show the details of the actual error.

The program has a built-in capability to provide solutions for common issues related to the own certificate. When such solution is available, a {{Style=button|Fix}} button appears next to the colored status caption bar. Press this button and the fix will be made automatically, or you will be walked through the possible steps of the solution.

= Application Manifest tab =

The OPC UA application manifest contains the application registration information together with data related to PKI administration, such as paths to the certificate stores used.

The information contained in the OPC UA application manifest can roughly be divided into three areas:
* Information that identifies or otherwise integrates the application in the OPC UA ecosystem, such as application URI, application type, application name, and product URI.
* Information needed to create the application instance certificate, such as the certificate subject name or its parts. Note that the certificate also contains some of the information described above, such  as the application URI.
* Information that allows the OPC UA application to execute and be administered in the operating system environment, such as location of the certificate stores it uses.

This logical separation is reflected in how the information is laid out on the Application Manifest tab:

[[File:UAManageApplicationManifestControl.png|center|Application Manifest tab]]

You cannot change the information in the Application Manifest tab; it comes from the OPC UA application itself. Use this tab mainly to verify that 
the information displayed is correct, and/or to share it with other parties. For example, the application URI is needed in some scenarios to connect to the application.

The information displayed reflects the final (effective) values, those that the application actually uses. Behind the scenes, the application manifest might be composed from several (partial) sources, and some elements (such as the certificate store paths) then go through a final resolution step.

If any issues were found, the bottom part of this tab shows warnings and error messages related to the application manifest.

= Common procedures =
== Trusting a Rejected certificate ==
Probably by far the most common usage for this dialog is to establish a trust of your application with a previously untrusted peer application, using self-signed certificates for application authentication. If the two applications attempt to connect in a secure way for the first time, and the trust is not configured, the other party certificate is rejected, and is placed into the Rejected certificate store (which as shows as "Rejected" trust status in the "Trusted Certificates" tab).

In order to establish trust to an application with a self-signed certificate that has been rejected:

# Open the "Administer OPC UA Application " dialog.
# Switch to the {{Style=label|Trusted Certificates}} tab.
# Locate the rejected certificate of the other application in the table. It will have "'''Rejected'''" in its Trust Status, and the name of the application and other identifying information will match the other application.
# Verify that the thumbprint of the certificate is identical to the known thumbprint of the certificate of the other application. This is an important step for security; if you skip it, you might end up trusting and connecting with an unintended, possibly rogue application. The other application will typically have some way to display the thumbprint of its certificate to the user. To verify the thumbprint, either:
## Select the {{Style=menu|Inspect}} action, find the {{Style=label|Identification: Thumbprint}} row in the property grid, and verify the thumbprint. Then press the {{Style=button|OK}} button.
## Select the {{Style=menu|View}} action, switch to the {{Style=label|Details}} tab, find the {{Style=label|Thumbprint}} row in the field list, and verify the thumbprint. Then press the {{Style=button|OK}} button.
# If the thumbprint in the previous step was correct, select the {{Style=menu|Trust Status: Trusted}} action. This will change the trust status of the selected certificate from '''Rejected''' to '''Trusted'''.