.NET Based OPC UA Client/Server SDK
2.6.2.427
|
The ApplicationInstance depends on an XML configuration file which specifies various parameters needed by the application to run. Most of these parameters have suitable default values; however, some are required to properly configure security. In these cases, the SDK will pick suitable defaults to ensure an application can run without a configuration file, however, Application Developers must provide them before deploying any real application.
The schema for this configuration file is based on the SecuredApplication schema defined in Annex D of Part 6 of the OPC UA Specification. The order of the elements in the XML file is significant. Configuration specific to the SDK or to applications built with the SDK can be added to the Extensions element defined by the SecuredApplication schema. This can be found in the folder "configurationschema". The methods ParseExtension<T> and UpdateExtension<T> on the ApplicationInstance object can be used to read or update any individual extension. These methods require a class which supports serialization with the WCF DataContract serializer or with the standard .NET XML serializer.
The SDK defines several standard extensions for different groups of configuration parameters which, by convention, all end with the suffix ‘Settings’. These standard extensions are described below along with the mandatory elements from the SecuredApplication schema. The SDK supports the use of file paths relative to special folder names. This allows the same configuration file to be used on different machines. The syntax replaces the drive letter with a special folder name enclosed in percent signs (%). For example, the following path refers to the Documents folder for the current user:
%MyDocuments%/Logs/LogFile.txt
The complete set of special folder names is defined by the Environment.SpecialFolder enumeration.
This is the base schema for the application configuration file.
Certificates are blobs of data which can be stored on disk or in a Windows certificate store. Each certificate has a public key and a private key. The private key must be protected and is only accessible to the owner of the certificate. The public key and private key are stored in separate files for this reason.
Certificates and revocation lists have to be stored in DER format. Allowed file extensions are .der or .cer for certificates and .crl for revocation lists.
The private key is usually stored in a PKSC#12 format (*.pfx or *.p12 extension) or a PEM format (*.pem extension). If a certificate is placed a Windows certificate store, the private key is placed in a file managed by Windows.
Certificates are placed into a subfolder of the trusted certificate store, and issuer certificate store respectively, named “certs” (see the table below). Existing certificate revocation lists are placed into a subfolder named “crl”. If the crl folder exists, every CA certificate needs to have a crl file. This behavior can be deactivated by setting the DisableCertificateRevocationUnknown attribute or DisableCertificateIssuerRevocationUnknown respectively in the extension CertificateCheckSettings.
A more detailed explanation of certificate management can be found on the website of the OPC Foundation: The OPC UA Security Model for Administrators (pdf document).
Element | Description | ||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
ApplicationName | A human readable name for the application. The value has a default chosen by the application vendor but can be changed by the administrators of the application. | ||||||||||||||||||||||||||||||
ApplicationUri | A globally unique identifier for the application instance. This must be a valid URI which should include the DNS name of the machine, the name of the product and the name of the application. | ||||||||||||||||||||||||||||||
ApplicationType | The type of application. May be Server_0 or Client_1. | ||||||||||||||||||||||||||||||
Product Name | A human readable name for the product. This value is set by the application vendor. | ||||||||||||||||||||||||||||||
ApplicationCertificate | Location and identifier for the application instance certificate. The default StorePath is (StoreType is “Directory”): "%CommonApplicationData%\UnifiedAutomation\CertificateStores\PrivateKeys" | ||||||||||||||||||||||||||||||
TrustedCertificateStore | Location of the trusted certificate store. Peer and CA certificates which the application trusts are placed here. See paragraphs above for more information on file format and folder structure. The default StorePath is (StoreType is “Directory”): "%CommonApplicationData%\UnifiedAutomation\CertificateStores\Trusted" | ||||||||||||||||||||||||||||||
IssuerCertificateStore | Location of the issuer certificate store. Certificates which are needed to validate certificate chains are placed here. See paragraphs above for more information on file format and folder structure. The default StorePath is (StoreType is “Directory”): "%CommonApplicationData%\UnifiedAutomation\CertificateStores\Issuers" | ||||||||||||||||||||||||||||||
RejectedCertificatesStore | Location of the rejected certificate store. Stores certificates which have been rejected because they are untrusted. The default StorePath is (StoreType is “Directory”): "%CommonApplicationData%\UnifiedAutomation\CertificateStores\Rejected" | ||||||||||||||||||||||||||||||
BaseAddresses | The list of endpoint URLs supported by Server. Any URL with “localhost” as the domain is bound to all machine IP addresses. The “localhost” is changed to the default DNS name of the machine during initialization. A URL with “127.0.0.1” as the domain is only accessible to Clients running on the same machine. For each URI scheme the following transport profiles are assumed:
| ||||||||||||||||||||||||||||||
SecurityProfiles | A list of supported security profiles. If omitted then the Basic256 and None profiles are used as defaults. Possible values are:
| ||||||||||||||||||||||||||||||
Extensions | A list of SDK and application specific configuration settings. Any valid XML is allowed. The XML is parsed when the ApplicationInstance.ParseExtension<T> method is called by the application. |
This set of configuration options can be used to set default certificate checks which are enforced by the application as well as to override these default checks for single certificates.
See Certificate Validation for more information.
The following code shows a configuration example:
Element | Description |
---|---|
DisableDomainCheck | If set to TRUE, the domain in the endpoint URL will not be compared to the certificate domains. This parameter is only validated by the Client SDK. The Server SDK will ignore this parameter, because it doesn’t check the domain. |
DisableApplicationUriCheck | If set to TRUE, the application URI will not be compared to the application URI in the certificate. The check is required for compliant OPC UA servers but older clients may provide a wrong ApplicationUri. It is not recommended to change this setting. |
DisableCertificateTimeInvalid | If set to TRUE, expired or not yet valid certificates will be accepted. |
DisableCertificateIssuerTimeInvalid | If set to TRUE, expired or not yet valid issuer certificates will be accepted. |
DisableCertificateRevocationUnknown | If set to TRUE, certificates will be accepted even if it is not possible to check their revocation status. |
DisableCertificateIssuerRevocationUnknown | If set to TRUE, issuer certificates will be accepted even if it is not possible to check their revocation status. |
These values specify various limits used by the transport layer.
Element | Description |
---|---|
MaxBufferSize | The maximum size of any buffers allocated. If not specified, the default is 65,536. |
MaxStringLength | The maximum length of any encoded String value. If not specified, the default is 16,777,216. |
MaxByteStringLength | The maximum length of any encoded ByteString value. If not specified, the default is 16,777,216. |
MaxArrayLength | The maximum length of any encoded array value. If not specified, the default is 65,536. |
MaxMessageSize | The maximum size of any encoded message. If not specified, the default is 16,777,216. |
OperationTimeout | The default timeout, in milliseconds, for any service request. If not specified, the default is 120,000. |
ChannelLifetime | The lifetime, in milliseconds, of a secure channel. If not specified, the default is 120,000. |
InactiveChannelLifetime | The lifetime, in milliseconds, of a secure channel if there is no communication. If not specified, the default is 10,000. |
MaxChannelCount | The maximum number of sockets. If not specified, the default is 100. |
SecurityTokenLifetime | The lifetime, in milliseconds, of a security token. If not specified, the default is 3,600,000. |
These values specify various options used during installation/uninstallation.
Element | Description |
---|---|
GenerateCertificateIfNone | If TRUE a new certificate is generated if a valid one does not exist. If not specified, the default is FALSE. |
CertificateKeyLength | The length of the auto-created certificate in bits. The default is 2048. Supported values are 1024, 2048, 3072 and 4096. |
CertificateHashAlgorithm | The hash algorithm used on the auto-created certificate. The default is 'sha256'. Supported values are 'sha1' and 'sha256'. |
DeleteCertificateOnUninstall | If TRUE the application certificate is deleted during uninstall. If not specified, the default is FALSE. |
ConfigureFirewall | If TRUE the firewall is configured to open or close ports used by the endpoints specified for the application. If not specified, the default is FALSE. |
ConfigureHttpAccess | If TRUE any HTTP or HTTPS endpoints are configured to allow access by a process running with the credentials of the UsersGroup. If not specified, the default is FALSE. |
InstallAsService | If TRUE a Server is configured to run as a Windows Service. If not specified, the default is FALSE. The service will run as 'Local System'. |
ServiceName | The name of the Windows Service created during install. Must be specified if InstallAsService is set to TRUE. |
ServiceDescription | A human readable description for the Windows Service. If not specified, the default is an empty string. |
ServiceStartMode | The following values are possible: Auto, Manual, Disabled. If not specified, the default is Manual |
UsersGroup | The name of the Windows Account Group which is allowed to run the application. If not specified, the default is the ‘Users’ built-in group. |
AdministratorsGroup | The name of the Windows Account Group which is allowed to administer the application. If not specified, the default is the ‘Administrators’ built-in group. |
DisableSetFilePermissions | If FALSE access permissions are set for the executable, the configuration file and the certificate store. If not specified, the default is FALSE. |
DisableLdsCertificateExchange | If FALSE the application instance certificate is pushed to the trusted certificate store of the Local Discovery Server (LDS) and the certificate of the LDS is pulled to the own trusted store. If not specified, the default is FALSE. |
LdsTrustedCertificateStore | The location of the trusted store of the local dicovery server. This setting is only evaluated if DisableLdsCertificateExchange is FALSE. If not specified, the SDK checks if standard locations of the trusted store are available. |
LdsApplicationCertificateFile | The filename of the application instance certificate of the local discovery server. This setting is only evaluated if DisableLdsCertificateExchange is FALSE. If not specified, the SDK searches ar standard locations of the lds certificate. |
These values control the information written to the trace log files.
Element | Description |
---|---|
TraceFile | The location of the trace file. If not specified, then no trace information is written to a file. |
MaxEntriesPerLog | The maximum number of entries per log file. If not specified, then default is 0 (no limit). |
MaxLogFileBackups | The maximum number of backup for log files. If not specified, then default is 0 (no backups). |
FastTrace | If TRUE, the trace file is kept open. If FALSE, the trace file is opened and closed for each log message written. If not specified then the default is FALSE. |
MasterTraceEnabled | If FALSE, all tracing is disabled. If not specified then the default is FALSE. |
DefaultTraceLevel | The default trace level. If not specified, then the default is “Error”. |
TimestampFormat | The string format of the Timestamp within the trace entry. If not specified, then the default is “HH:mm.sss”. This setting is used to call DateTime.ToString(string format). |
ModuleSettings | A list of settings for each trace module in the process. |
ModuleName | The name of the trace module. If not specified, then the module is ignored. |
TraceEnabled | If FALSE, then tracing is disabled for the module. If not specified, then the default is TRUE. |
TraceLevel | The default trace level for the module. If not specified, then the default is “Default”. |
These are the possible trace levels that can be specified.
Level | Description |
---|---|
Default | Use the default trace level. |
None | Turn all tracing off. |
Error | Unexpected errors that require the attention of developers or administrators. |
Warning | Less critical issues that also require the attention of developers or administrators. |
System | General system messages. |
Info | Informational messages. |
InterfaceCall | The entry and exit messages for major API methods. |
Constructor | The constructors of major API objects. |
ProgramFlow | Additional entry and exit messages for minor API methods. |
Data | Verbose information when the state of objects changes during processing. |
These values control the base configuration for the Client.
Element | Description |
---|---|
ProductUri | A globally unique identifier for the product that client belongs to. If not specified then the default is an empty string. |
DiagnosticMasks | The diagnostic masks to use with each request. If not specified, then the default is 0 (no diagnostics). |
RequestTimeout | The timeout in milliseconds for each service request. If not specified, then the default is 30,000. |
MaxOperationsPerRequest | The maximum number of operations per request. The following methods support this setting:
|
SessionTimeout | The requested timeout, in milliseconds, for a session. If not specified, then the default is 600,000. |
WatchdogCycleTime | The time interval, in milliseconds, between cycles of the watchdog which checks the status of the connection with the Server. If not specified then the default is 5,000. |
WatchdogTimeout | The maximum time, in milliseconds, that the watchdog waits for a response from the Server before starting the reconnection process. If not specified then the default is 10,000. |
AutomaticReconnect | If TRUE, the watchdog will attempt to reconnect to the Server when it detects an error after it has connected. If not specified, then the default is TRUE. |
RetryInitialConnect | If TRUE, the client tries to connect automatically if the initial connect fails. It will stop when a timeout occurs. If not specified, then the default is FALSE. |
ReconnectDelay | The time in milliseconds between reconnect attempts. If not specified, then the default is 10,000. |
ReconnectTimeout | The timeout for a reconnect attempt in milliseconds. If not specified, then the default is ReconnectDelay / 2. |
ReconnectCreateSubscriptionsDelay | The timespan in milliseconds between a sucessfully recreation of a Session and the recreation of Subscriptions If not specified, then the default is 0 |
DisableIncludeChains | If FALSE, the entire chain is sent over the wire. If true, only the application instance certificate is sent over the wire. This setting allows for backward compatibility with applications that cannot handle a certificate chain or can be used in environments where issuer certificates are stored locally on the server. |
These values control the base configuration for the Server.
Element | Description |
---|---|
ProductUri | A globally unique identifier for the product that server belongs to. The default is constructued with the ApplicationUri. |
ProductName | A human readable name for the product that server belongs to. The default is the Product attribute for the EXE assembly. |
ManufacturerName | A human readable name for the manufacurer of the product. The default is the Company attribute for the EXE assembly. |
SoftwareVersion | A string representing the version of the Server software. The default is the first 2 fields from the EXE assembly FileVersion attribute. |
BuildNumber | A string representing the build of the Server software. The default is the last 2 fields from the EXE assembly FileVersion attribute. |
BuildDate | When the Server software was built. The last write time for the EXE assembly is the default. |
IsAuditActivated | If true, the Server will produce audit events. The default is FALSE. |
AvailableLocaleIds | A list of locales supported by the Server. The syntax is defined by RFC 1766. The default is "en-US". |
AvailableServerProfiles | A list of profiles supported by the Server. No profiles are specified by default. |
UserIdentity | The user identities supported by the server. The default is the anonymous user token policy. |
DiscoveryRegistration | The discovery registration settings for servers. |
Capabilities | The capabilities supported of the server. If not set, "DA" is specified as capability. |
DisableUseLeafCertificateOnlyForSignature | If true, the server uses whole the certificate data that is sent in CreateSession, for creating the server signature. If false, the leaf certificate is used. The default and recommended setting is FALSE. |
These values control the security options and network interface used by a base address.
Element | Description |
---|---|
EndpointUrl | The URL which the settings apply to. This URL must match one of the URLs in the SecuredApplication.BaseAddresses list. |
NetworkInterface | The IP address to use when binding the socket. It can be an IPv4 or IPv6 address. If omitted, then the socket is bound to all IP addresses for the machine. |
DisableNoSecurity | If true, the None message security mode is disabled for this endpoint. The default value is FALSE. |
EnableSignOnly | If true, the SignOnly message security mode is enabled for this endpoint. The default value is FALSE. |
DisableSignAndEncrypt | If true, the SignAndEncryp message security mode is disabled for this endpoint. The default value is FALSE. |
EnableXmlEncoding | If set to TRUE, the endpoint will only accept XML encoded messages. |
These values control what user identity tokens are accepted by a Server.
Element | Description |
---|---|
EnableAnonymous | Whether anonymous users are allowed. Enabled if the UserIdentitySettings are missing from the configuration. |
EnableUserName | Whether authentication with a username and password is allowed. Disabled if the UserIdentitySettings are missing from the configuration. |
EnableCertificate | Whether authentication with an X509 certificate is allowed. Disabled if the UserIdentitySettings are missing from the configuration. |
These values control how a server registers with the local discovery server.
Element | Description |
---|---|
Url | The URL of the discovery server the server must register with. The default is 'opc.tcp://localhost:4840'. |
Enabled | Whether the server should attempt to register with the discovery server. The default is TRUE. |
RegistrationInterval | The interval in seconds between registration attempts. The default and maximum is 30 and the maximum is 600. |
These values control the thread pool used by the server.
Element | Description |
---|---|
MinThreadCount | The minimum number of threads. The default and minimum value is 10. |
MaxThreadCount | Deprecated: This field is not evaluated anymore. |
MaxRequestCount | The maximum number of requests in the queue waiting for a thread. The default is 2000 and the minimum value is 100. |
These values control the behavoir of the SessionManager in the Server.
Element | Description |
---|---|
MaxRequestAge | The maximum difference in milliseconds between the timestamp of the request and the current time. The minimum and default is 60,000. |
MaxSessionCount | The maximum number of open sessions. The default is 100 and the minimum is 1. |
MinSessionTimeout | The minimum timeout in milliseconds for sessions. The default is 20,000 and the minimum is 1,000. |
MaxSessionTimeout | The maximum timeout in milliseconds for sessions. The default is 600,000 and the minimum is 60,000. |
MaxBrowseContinuationPoints | The maximum number of browse continuation points per session. The default and minimum is the MaxNodesPerBrowse. |
MaxHistoryContinuationPoints | The maximum number of history continuation points per session. The default and minimum is the MaxNodesPerHistoryDataRead. |
MaxNodesPerRead | The maximum number of read operations per request. The default and minimum is 10,000. |
MaxNodesPerWrite | The maximum number of write operations per request. The default and minimum is 10,000. |
MaxNodesPerHistoryDataRead | The maximum number of history data read operations per request. The default and minimum is 1,000. |
MaxNodesPerHistoryDataUpdate | The maximum number of history data update operations per request. The default and minimum is 1,000. |
MaxNodesPerHistoryEventRead | The maximum number of history event read operations per request. The default and minimum is 1,000. |
MaxNodesPerHistoryEventUpdate | The maximum number of history event update operations per request. The default and minimum is 1,000. |
MaxNodesPerMethodCall | The maximum number of call operations per request. The default and minimum is 10,000. |
MaxNodesPerBrowse | The maximum number of browse operations per request. The default and minimum is 1,000. |
MaxNodesPerRegisterNodes | The maximum number of register node operations per request. The default and minimum is 1,000. |
MaxNodesPerTranslateBrowsePathsToNodeIds | The maximum number of translate browse operations per request. The default and minimum is 1,000. |
MaxNodesPerNodeManagement | The maximum number of add or delete node operations per request. The default and minimum is 100. |
MaxMonitoredItemsPerCall | The maximum number of monitored item operations per request. The default and minimum is 10,000. |
MaxHistoryDataValuesPerRead | The maximum number of returned values per history read data request. The default is 10,000 and the maximum is 50,000. |
MaxHistoryEventsPerRead | The maximum number of returned values per history read event request. The default is 10,000 and the maximum is 50,000. |
MinNonceLength | The minimum nonce length. The default and minimum is 32. |
DisableNonceLengthCheck | Disables the length check of the client nonce. The default and recommended value is false. |
These values control the behavoir of the SubscriptionManager in the Server.
Element | Description |
---|---|
MinPublishingInterval | The minimum publishing interval in milliseconds. The minimum and default is PublishingIntervalResolution. |
MaxPublishingInterval | The maximum publishing interval in milliseconds. The minimum and default is the MinPublishingInterval. The default is 60,000 and the minimum is MinPublishingInterval. |
MaxKeepAliveInterval | The maximum keep alive interval in milliseconds. The default is 3,600,000 and the minimum is MinKeepAliveInterval. |
MinKeepAliveInterval | The minimum keep alive interval in milliseconds. The minimum and default is 1,000. |
MinLifetime | The minimum subscription lifetime in milliseconds. The minimum and default is the larger of 20,000 or the MinKeepAliveInterval. |
MaxLifetime | The maximum subscription lifetime in milliseconds. The default is 3,600,000 and the minimum is MinLifetime. |
PublishingIntervalResolution | The minimum publish interval in milliseconds. The default is 100. The minimum is 50. |
MaxPublishRequestCount | The maximum number of queued publish requests per session. The default is 100. The minimum is 2. |
MaxSubscriptionCount | The maximum number of subscriptions. The default and minimum is 10. |
MaxSubscriptionsPerSession | The maximum number of subscriptions. per session The default and minimum is MaxSubscriptionCount. |
MaxNotificationsPerPublish | The maximum number of notifications per publish request. .The default is 10,000. |
MaxMessageQueueSize | The maximum of saved messages per subscription. The default is 100. |
MaxDataValueQueueSize | The maximum queue size for data monitored items. The default and minimum is 1,000. |
MinEventQueueSize | The minimum queue size for event monitored items. The default and minimum is 1,000. |
MaxEventQueueSize | The maximum queue size for event monitored items. The default is the 10,000 and the minimum is MinEventQueueSize. |