Figure1_

 

 

 

Figure3_

 

     OPC UA Specification

OPC 10000-4

OPC Unified Architecture

Part 4: Services

 

 

Release 1.04

2017-11-22

 

 

 

 

 

 

 


Specification Type:

Industry Standard Specification

Comments:

 

 

 

 

Document
Number

OPC 10000-4

 

 

 

Title:

OPC Unified Architecture

Part 4 :Services

Date:

2017-11-22

 

 

 

 

Version:

Release 1.04

Software:

MS-Word

 

 

Source:

OPC 10000-4 - UA Specification Part 4 - Services 1.04.docx

 

 

 

 

Author:

OPC Foundation

Status:

Release

 

 

 

 


 


 

 

CONTENTS

FIGURES. v

TABLES. vi

1       Scope. 1

2       Normative references. 1

3       Terms, definitions and conventions. 2

3.1        Terms and definitions. 2

3.2        Abbreviations and symbols. 3

3.3        Conventions for Service definitions. 3

4       Overview. 4

4.1        Service Set model 4

4.2        Request/response Service procedures. 7

5       Service Sets. 8

5.1        General 8

5.2        Service request and response header 8

5.3        Service results. 8

5.4        Discovery Service Set 9

5.4.1          Overview. 9

5.4.2          FindServers. 10

5.4.3          FindServersOnNetwork. 12

5.4.4          GetEndpoints. 13

5.4.5          RegisterServer 15

5.4.6          RegisterServer2. 17

5.5        SecureChannel Service Set 18

5.5.1          Overview. 18

5.5.2          OpenSecureChannel 20

5.5.3          CloseSecureChannel 22

5.6        Session Service Set 23

5.6.1          Overview. 23

5.6.2          CreateSession. 23

5.6.3          ActivateSession. 27

5.6.4          CloseSession. 30

5.6.5          Cancel 30

5.7        NodeManagement Service Set 31

5.7.1          Overview. 31

5.7.2          AddNodes. 31

5.7.3          AddReferences. 33

5.7.4          DeleteNodes. 35

5.7.5          DeleteReferences. 36

5.8        View Service Set 37

5.8.1          Overview. 37

5.8.2          Browse. 37

5.8.3          BrowseNext 39

5.8.4          TranslateBrowsePathsToNodeIds. 40

5.8.5          RegisterNodes. 42

5.8.6          UnregisterNodes. 43

5.9        Query Service Set 44

5.9.1          Overview. 44

5.9.2          Querying Views. 44

5.9.3          QueryFirst 44

5.9.4          QueryNext 48

5.10      Attribute Service Set 49

5.10.1        Overview. 49

5.10.2        Read. 49

5.10.3        HistoryRead. 51

5.10.4        Write. 53

5.10.5        HistoryUpdate. 55

5.11      Method Service Set 56

5.11.1        Overview. 56

5.11.2        Call 57

5.12      MonitoredItem Service Set 59

5.12.1        MonitoredItem model 59

5.12.2        CreateMonitoredItems. 64

5.12.3        ModifyMonitoredItems. 66

5.12.4        SetMonitoringMode. 68

5.12.5        SetTriggering. 69

5.12.6        DeleteMonitoredItems. 70

5.13      Subscription Service Set 71

5.13.1        Subscription model 71

5.13.2        CreateSubscription. 77

5.13.3        ModifySubscription. 79

5.13.4        SetPublishingMode. 80

5.13.5        Publish. 82

5.13.6        Republish. 83

5.13.7        TransferSubscriptions. 84

5.13.8        DeleteSubscriptions. 85

6       Service behaviours. 86

6.1        Security. 86

6.1.1          Overview. 86

6.1.2          Obtaining and Installing an Application Instance Certificate. 86

6.1.3          Determining if a Certificate is Trusted. 88

6.1.4          Creating a SecureChannel 90

6.1.5          Creating a Session. 92

6.1.6          Impersonating a User 93

6.2        Authorization Services. 93

6.2.1          Overview. 93

6.2.2          Indirect Handshake with an Identity Provider 93

6.2.3          Direct Handshake with an Identity Provider 94

6.3        Session-less Service Invocation. 95

6.3.1          Description. 95

6.3.2          Parameters. 95

6.3.3          Service results. 96

6.4        Software Certificates. 96

6.5        Auditing. 96

6.5.1          Overview. 96

6.5.2          General audit logs. 97

6.5.3          General audit Events. 97

6.5.4          Auditing for Discovery Service Set 97

6.5.5          Auditing for SecureChannel Service Set 97

6.5.6          Auditing for Session Service Set 98

6.5.7          Auditing for NodeManagement Service Set 98

6.5.8          Auditing for Attribute Service Set 98

6.5.9          Auditing for Method Service Set 99

6.5.10        Auditing for View, Query, MonitoredItem and Subscription Service Set 99

6.6        Redundancy. 99

6.6.1          Redundancy overview. 99

6.6.2          Server Redundancy. 100

6.6.3          Client Redundancy. 110

6.6.4          Network Redundancy. 110

6.6.5          Manually Forcing Failover 111

6.7        Re-establishing connections. 112

6.8        Durable Subscriptions. 113

7       Common parameter type definitions. 114

7.1        ApplicationDescription. 114

7.2        ApplicationInstanceCertificate. 115

7.3        BrowseResult 115

7.4        ContentFilter 116

7.4.1          ContentFilter structure. 116

7.4.2          ContentFilterResult 116

7.4.3          FilterOperator 117

7.4.4          FilterOperand parameters. 124

7.5        Counter 125

7.6        ContinuationPoint 126

7.7        DataValue. 126

7.7.1          General 126

7.7.2          PicoSeconds. 126

7.7.3          SourceTimestamp. 127

7.7.4          ServerTimestamp. 127

7.7.5          StatusCode assigned to a value. 127

7.8        DiagnosticInfo. 128

7.9        DiscoveryConfiguration parameters. 129

7.9.1          Overview. 129

7.9.2          MdnsDiscoveryConfiguration. 129

7.10      EndpointDescription. 129

7.11      ExpandedNodeId. 129

7.12      ExtensibleParameter 130

7.13      Index. 130

7.14      IntegerId. 130

7.15      MessageSecurityMode. 130

7.16      MonitoringParameters. 131

7.17      MonitoringFilter parameters. 131

7.17.1        Overview. 131

7.17.2        DataChangeFilter 132

7.17.3        EventFilter 133

7.17.4        AggregateFilter 134

7.18      MonitoringMode. 136

7.19      NodeAttributes parameters. 136

7.19.1        Overview. 136

7.19.2        ObjectAttributes parameter 137

7.19.3        VariableAttributes parameter 137

7.19.4        MethodAttributes parameter 138

7.19.5        ObjectTypeAttributes parameter 138

7.19.6        VariableTypeAttributes parameter 138

7.19.7        ReferenceTypeAttributes parameter 139

7.19.8        DataTypeAttributes parameter 139

7.19.9        ViewAttributes parameter 139

7.19.10     GenericAttributes parameter 140

7.20      NotificationData parameters. 140

7.20.1        Overview. 140

7.20.2        DataChangeNotification parameter 140

7.20.3        EventNotificationList parameter 141

7.20.4        StatusChangeNotification parameter 141

7.21      NotificationMessage. 141

7.22      NumericRange. 142

7.23      QueryDataSet 143

7.24      ReadValueId. 143

7.25      ReferenceDescription. 144

7.26      RelativePath. 144

7.27      RegisteredServer 145

7.28      RequestHeader 145

7.29      ResponseHeader 146

7.30      ServiceFault 147

7.31      SessionAuthenticationToken. 147

7.32      SignatureData. 148

7.33      SignedSoftwareCertificate. 148

7.34      StatusCode. 149

7.34.1        General 149

7.34.2        Common StatusCodes. 151

7.35      TimestampsToReturn. 154

7.36      UserIdentityToken parameters. 154

7.36.1        Overview. 154

7.36.2        Token Encryption and Proof of Possession. 154

7.36.3        AnonymousIdentityToken. 158

7.36.4        UserNameIdentityToken. 158

7.36.5        X509IdentityTokens. 159

7.36.6        IssuedIdentityToken. 159

7.37      UserTokenPolicy. 160

7.38      VersionTime. 160

7.39      ViewDescription. 161

Annex A (informative)  BNF definitions. 162

A.1        Overview over BNF. 162

A.2        BNF of RelativePath. 162

A.3        BNF of NumericRange. 163

Annex B (informative)  Content Filter and Query Examples. 164

B.1        Simple ContentFilter examples. 164

B.1.1          Overview. 164

B.1.2          Example 1. 164

B.1.3          Example 2. 165

B.2        Complex Examples of Query Filters. 165

B.2.1          Overview. 165

B.2.2          Used type model 166

B.2.3          Example Notes. 168

B.2.4          Example 1. 169

B.2.5          Example 2. 170

B.2.6          Example 3. 171

B.2.7          Example 4. 173

B.2.8          Example 5. 174

B.2.9          Example 6. 176

B.2.10       Example 7. 177

B.2.11       Example 8. 179

B.2.12       Example 9. 180

 

FIGURES

 

Figure 1 – Discovery Service Set........................................................... 5

Figure 2 – SecureChannel Service Set.................................................... 5

Figure 3 – Session Service Set.............................................................. 5

Figure 4 – NodeManagement Service Set................................................ 5

Figure 5 – View Service Set.................................................................. 6

Figure 6 – Attribute Service Set............................................................. 6

Figure 7 – Method Service Set............................................................... 7

Figure 8 – MonitoredItem and Subscription Service Sets............................. 7

Figure 9 – Discovery process............................................................... 10

Figure 10 – Using a Gateway Server..................................................... 15

Figure 11 – The Registration Process – Manually Launched Servers........... 16

Figure 12 – The Registration Process – Automatically Launched Servers..... 16

Figure 13 – SecureChannel and Session Services................................... 19

Figure 14 – Multiplexing Users on a Session........................................... 25

Figure 15 – MonitoredItem Model......................................................... 60

Figure 16 – Typical delay in change detection......................................... 61

Figure 17 – Queue overflow handling.................................................... 62

Figure 18 – Triggering Model............................................................... 63

Figure 19 – Obtaining and Installing an Application Instance Certificate....... 87

Figure 20 – Determining if a Application Instance Certificate is Trusted........ 90

Figure 21 – Establishing a SecureChannel............................................. 91

Figure 22 – Establishing a Session....................................................... 92

Figure 23 – Impersonating a User......................................................... 93

Figure 24 – Indirect Handshake with an Identity Provider.......................... 94

Figure 25 – Direct Handshake with an Identity Provider............................ 94

Figure 26 – Transparent Redundancy setup example.............................. 101

Figure 27 – Non-Transparent Redundancy setup................................... 102

Figure 28 – Client Start-up Steps........................................................ 105

Figure 29 – Cold Failover.................................................................. 106

Figure 30 – Warm Failover................................................................ 106

Figure 31 – Hot Failover.................................................................... 108

Figure 32 – HotAndMirrored Failover................................................... 109

Figure 33 – Server proxy for Redundancy............................................. 109

Figure 34 – Transparent Network Redundancy...................................... 110

Figure 35 – Non-Transparent Network Redundancy................................ 111

Figure 36 – Reconnect Sequence....................................................... 112

Figure 37 – Logical layers of a Server.................................................. 147

Figure 38 – Obtaining a SessionAuthenticationToken.............................. 148

Figure 39 – EncryptedSecret Layout.................................................... 156

Figure B.1 – Filter Logic Tree Example................................................ 164

Figure B.2 – Filter Logic Tree Example................................................ 165

Figure B.3 – Example Type Nodes...................................................... 167

Figure B.4 – Example Instance Nodes................................................. 168

Figure B.5 – Example 1 Filter............................................................. 169

Figure B.6 – Example 2 Filter Logic Tree.............................................. 171

Figure B.7 – Example 3 Filter Logic Tree.............................................. 172

Figure B.8 – Example 4 Filter Logic Tree.............................................. 174

Figure B.9 – Example 5 Filter Logic Tree.............................................. 175

Figure B.10 – Example 6 Filter Logic Tree............................................ 176

Figure B.11 – Example 7 Filter Logic Tree............................................ 178

Figure B.12 – Example 8 Filter Logic Tree............................................ 179

Figure B.13 – Example 9 Filter Logic Tree............................................ 181

 

TABLES

 

Table 1 – Service Definition Table.......................................................... 3

Table 2 – Parameter Types defined in Part 3............................................ 4

Table 3 – FindServers Service Parameters............................................. 12

Table 4 – FindServersOnNetwork Service Parameters.............................. 13

Table 5 – GetEndpoints Service Parameters........................................... 15

Table 6 – RegisterServer Service Parameters......................................... 17

Table 7 – RegisterServer Service Result Codes...................................... 17

Table 8 – RegisterServer2................................................................... 18

Table 9 – RegisterServer2 Service Result Codes..................................... 18

Table 10 – RegisterServer2 Operation Level Result Codes........................ 18

Table 11 – OpenSecureChannel Service Parameters................................ 21

Table 12 – OpenSecureChannel Service Result Codes............................. 22

Table 13 – CloseSecureChannel Service Parameters............................... 23

Table 14 – CloseSecureChannel Service Result Codes............................. 23

Table 15 – CreateSession Service Parameters........................................ 26

Table 16 – CreateSession Service Result Codes..................................... 27

Table 17 – ActivateSession Service Parameters...................................... 29

Table 18 – ActivateSession Service Result Codes................................... 30

Table 19 – CloseSession Service Parameters......................................... 30

Table 20 – CloseSession Service Result Codes....................................... 30

Table 21 – Cancel Service Parameters.................................................. 31

Table 22 – AddNodes Service Parameters.............................................. 32

Table 23 – AddNodes Service Result Codes........................................... 32

Table 24 – AddNodes Operation Level Result Codes................................ 33

Table 25 – AddReferences Service Parameters....................................... 34

Table 26 – AddReferences Service Result Codes.................................... 34

Table 27 – AddReferences Operation Level Result Codes......................... 34

Table 28 – DeleteNodes Service Parameters.......................................... 35

Table 29 – DeleteNodes Service Result Codes........................................ 35

Table 30 – DeleteNodes Operation Level Result Codes............................ 36

Table 31 – DeleteReferences Service Parameters................................... 36

Table 32 – DeleteReferences Service Result Codes................................. 36

Table 33 – DeleteReferences Operation Level Result Codes...................... 37

Table 34 – Browse Service Parameters................................................. 38

Table 35 – Browse Service Result Codes............................................... 39

Table 36 – Browse Operation Level Result Codes.................................... 39

Table 37 – BrowseNext Service Parameters........................................... 40

Table 38 – BrowseNext Service Result Codes......................................... 40

Table 39 – BrowseNext Operation Level Result Codes.............................. 40

Table 40 – TranslateBrowsePathsToNodeIds Service Parameters............... 41

Table 41 – TranslateBrowsePathsToNodeIds Service Result Codes............ 42

Table 42 – TranslateBrowsePathsToNodeIds Operation Level Result Codes. 42

Table 43 – RegisterNodes Service Parameters........................................ 43

Table 44 – RegisterNodes Service Result Codes..................................... 43

Table 45 – UnregisterNodes Service Parameters..................................... 43

Table 46 – UnregisterNodes Service Result Codes.................................. 44

Table 47 – QueryFirst Request Parameters............................................ 46

Table 48 – QueryFirst Response Parameters.......................................... 47

Table 49 – QueryFirst Service Result Codes........................................... 48

Table 50 – QueryFirst Operation Level Result Codes................................ 48

Table 51 – QueryNext Service Parameters............................................. 49

Table 52 – QueryNext Service Result Codes........................................... 49

Table 53 – Read Service Parameters.................................................... 50

Table 54 – Read Service Result Codes.................................................. 50

Table 55 – Read Operation Level Result Codes....................................... 51

Table 56 – HistoryRead Service Parameters........................................... 52

Table 57 – HistoryRead Service Result Codes........................................ 53

Table 58 – HistoryRead Operation Level Result Codes............................. 53

Table 59 – Write Service Parameters.................................................... 54

Table 60 – Write Service Result Codes.................................................. 55

Table 61 – Write Operation Level Result Codes....................................... 55

Table 62 – HistoryUpdate Service Parameters........................................ 56

Table 63 – HistoryUpdate Service Result Codes...................................... 56

Table 64 – HistoryUpdate Operation Level Result Codes........................... 56

Table 65 – Call Service Parameters...................................................... 58

Table 66 – Call Service Result Codes.................................................... 59

Table 67 – Call Operation Level Result Codes........................................ 59

Table 68 – Call Input Argument Result Codes......................................... 59

Table 69 – CreateMonitoredItems Service Parameters.............................. 65

Table 70 – CreateMonitoredItems Service Result Codes........................... 66

Table 71 – CreateMonitoredItems Operation Level Result Codes................ 66

Table 72 – ModifyMonitoredItems Service Parameters.............................. 67

Table 73 – ModifyMonitoredItems Service Result Codes........................... 67

Table 74 – ModifyMonitoredItems Operation Level Result Codes................ 68

Table 75 – SetMonitoringMode Service Parameters................................. 68

Table 76 – SetMonitoringMode Service Result Codes............................... 68

Table 77 – SetMonitoringMode Operation Level Result Codes.................... 68

Table 78 – SetTriggering Service Parameters......................................... 69

Table 79 – SetTriggering Service Result Codes....................................... 69

Table 80 – SetTriggering Operation Level Result Codes............................ 70

Table 81 – DeleteMonitoredItems Service Parameters.............................. 70

Table 82 – DeleteMonitoredItems Service Result Codes........................... 70

Table 83 – DeleteMonitoredItems Operation Level Result Codes................ 70

Table 84 – Subscription States............................................................. 73

Table 85 – Subscription State Table...................................................... 74

Table 86 – State variables and parameters............................................. 76

Table 87 – Functions.......................................................................... 77

Table 88 – CreateSubscription Service Parameters.................................. 78

Table 89 – CreateSubscription Service Result Codes............................... 79

Table 90 – ModifySubscription Service Parameters.................................. 80

Table 91 – ModifySubscription Service Result Codes............................... 80

Table 92 – SetPublishingMode Service Parameters.................................. 81

Table 93 – SetPublishingMode Service Result Codes............................... 81

Table 94 – SetPublishingMode Operation Level Result Codes.................... 82

Table 95 – Publish Service Parameters................................................. 83

Table 96 – Publish Service Result Codes............................................... 83

Table 97 – Publish Operation Level Result Codes.................................... 83

Table 98 – Republish Service Parameters.............................................. 84

Table 99 – Republish Service Result Codes............................................ 84

Table 100 – TransferSubscriptions Service Parameters............................ 85

Table 101 – TransferSubscriptions Service Result Codes.......................... 85

Table 102 – TransferSubscriptions Operation Level Result Codes............... 85

Table 103 – DeleteSubscriptions Service Parameters............................... 86

Table 104 – DeleteSubscriptions Service Result Codes............................ 86

Table 105 – DeleteSubscriptions Operation Level Result Codes................. 86

Table 106 – Certificate Validation Steps................................................. 89

Table 107 – SessionlessInvoke Service Parameters................................. 96

Table 108 – SessionlessInvoke Service Result Codes.............................. 96

Table 109 – ServiceLevel Ranges....................................................... 103

Table 110 – Server Failover Modes..................................................... 104

Table 111 – Redundancy Failover actions............................................. 104

Table 112 – ApplicationDescription..................................................... 115

Table 113 – ApplicationInstanceCertificate........................................... 115

Table 114 – BrowseResult................................................................. 116

Table 115 – ContentFilter Structure..................................................... 116

Table 116 – ContentFilterResult Structure............................................ 117

Table 117 – ContentFilterResult Result Codes....................................... 117

Table 118 – ContentFilterResult Operand Result Codes.......................... 117

Table 119 – Basic FilterOperator Definition........................................... 118

Table 120 – Complex FilterOperator Definition...................................... 120

Table 121 – Wildcard characters......................................................... 121

Table 122 – Conversion Rules............................................................ 122

Table 123 – Data Precedence Rules.................................................... 123

Table 124 – Logical AND Truth Table.................................................. 123

Table 125 – Logical OR Truth Table.................................................... 124

Table 126 – FilterOperand parameter TypeIds....................................... 124

Table 127 – ElementOperand............................................................. 124

Table 128 – LiteralOperand............................................................... 124

Table 129 – AttributeOperand............................................................ 125

Table 130 – SimpleAttributeOperand................................................... 125

Table 131 – DataValue..................................................................... 126

Table 132 – DiagnosticInfo................................................................ 128

Table 133 – DiscoveryConfiguration parameterTypeIds........................... 129

Table 134 – MdnsDiscoveryConfiguration............................................. 129

Table 135 – EndpointDescription........................................................ 129

Table 136 – ExpandedNodeId............................................................ 130

Table 137 – ExtensibleParameter Base Type........................................ 130

Table 138 – MessageSecurityMode Values........................................... 130

Table 139 – MonitoringParameters...................................................... 131

Table 140 – MonitoringFilter parameterTypeIds..................................... 132

Table 141 – DataChangeFilter............................................................ 132

Table 142 – EventFilter structure........................................................ 134

Table 143 – EventFilterResult structure................................................ 134

Table 144 – EventFilterResult Result Codes......................................... 134

Table 145 – AggregateFilter structure.................................................. 135

Table 146 – AggregateFilterResult structure......................................... 136

Table 147 – MonitoringMode Values.................................................... 136

Table 148 – NodeAttributes parameterTypeIds...................................... 136

Table 149 – Bit mask for specified Attributes......................................... 137

Table 150 – ObjectAttributes.............................................................. 137

Table 151 – VariableAttributes........................................................... 138

Table 152 – MethodAttributes............................................................. 138

Table 153 – ObjectTypeAttributes....................................................... 138

Table 154 – VariableTypeAttributes..................................................... 139

Table 155 – ReferenceTypeAttributes.................................................. 139

Table 156 – DataTypeAttributes.......................................................... 139

Table 157 – ViewAttributes................................................................ 140

Table 158 – GenericAttributes............................................................ 140

Table 159 – NotificationData parameterTypeIds..................................... 140

Table 160 – DataChangeNotification.................................................... 141

Table 161 – EventNotificationList........................................................ 141

Table 162 – StatusChangeNotification................................................. 141

Table 163 – NotificationMessage........................................................ 142

Table 164 – NumericRange............................................................... 142

Table 165 – QueryDataSet................................................................ 143

Table 166 – ReadValueId.................................................................. 143

Table 167 – ReferenceDescription...................................................... 144

Table 168 – RelativePath.................................................................. 144

Table 169 – RegisteredServer............................................................ 145

Table 170 – RequestHeader.............................................................. 146

Table 171 – ResponseHeader............................................................ 147

Table 172 – ServiceFault................................................................... 147

Table 173 – SignatureData................................................................ 148

Table 174 – SignedSoftwareCertificate................................................ 149

Table 175 – StatusCode Bit Assignments............................................. 150

Table 176 – DataValue InfoBits.......................................................... 151

Table 177 – Common Service Result Codes.......................................... 152

Table 178 – Common Operation Level Result Codes.............................. 153

Table 179 – TimestampsToReturn Values............................................. 154

Table 180 – UserIdentityToken parameterTypeIds.................................. 154

Table 181 – Legacy UserIdentityToken Encrypted Token Secret Format..... 155

Table 182 – EncryptedSecret Layout................................................... 157

Table 183 – EncryptedSecret DataTypes.............................................. 157

Table 184 – RsaEncryptedSecret Structure........................................... 158

Table 185 – AnonymousIdentityToken.................................................. 158

Table 186 – UserNameIdentityToken................................................... 159

Table 187 – EncryptionAlgorithm selection............................................ 159

Table 188 – X.509 v3 Identity Token.................................................... 159

Table 189 – IssuedIdentityToken........................................................ 160

Table 190 – UserTokenPolicy............................................................. 160

Table 191 – ViewDescription.............................................................. 161

Table A.1 – RelativePath................................................................... 162

Table A.2 – RelativePath Examples..................................................... 163

Table B.1 – ContentFilter Example...................................................... 165

Table B.2 – ContentFilter Example...................................................... 165

Table B.3 – Example 1 NodeTypeDescription........................................ 169

Table B.4 – Example 1 ContentFilter................................................... 169

Table B.5 – Example 1 QueryDataSets................................................ 170

Table B.6 – Example 2 NodeTypeDescription........................................ 170

Table B.7 – Example 2 ContentFilter................................................... 171

Table B.8 – Example 2 QueryDataSets................................................ 171

Table B.9 – Example 3 - NodeTypeDescription...................................... 172

Table B.10 – Example 3 ContentFilter.................................................. 173

Table B.11 – Example 3 QueryDataSets............................................... 173

Table B.12 – Example 4 NodeTypeDescription...................................... 174

Table B.13 – Example 4 ContentFilter.................................................. 174

Table B.14 – Example 4 QueryDataSets............................................... 174

Table B.15 – Example 5 NodeTypeDescription...................................... 175

Table B.16 – Example 5 ContentFilter.................................................. 175

Table B.17 – Example 5 QueryDataSets............................................... 175

Table B.18 – Example 6 NodeTypeDescription...................................... 176

Table B.19 – Example 6 ContentFilter.................................................. 176

Table B.20 – Example 6 QueryDataSets............................................... 177

Table B.21 – Example 6 QueryDataSets without Additional Information...... 177

Table B.22 – Example 7 NodeTypeDescription...................................... 178

Table B.23 – Example 7 ContentFilter.................................................. 178

Table B.24 – Example 7 QueryDataSets............................................... 178

Table B.25 – Example 8 NodeTypeDescription...................................... 179

Table B.26 – Example 8 ContentFilter.................................................. 180

Table B.27 – Example 8 QueryDataSets............................................... 180

Table B.28 – Example 9 NodeTypeDescription...................................... 180

Table B.29 – Example 9 ContentFilter.................................................. 181

Table B.30 – Example 9 QueryDataSets............................................... 181

 


OPC Foundation

____________

 

UNIFIED ARCHITECTURE –

FOREWORD

This specification is the specification for developers of OPC UA applications. The specification is a result of an analysis and design process to develop a standard interface to facilitate the development of applications by multiple vendors that shall inter-operate seamlessly together.

Copyright © 2006-2018, OPC Foundation, Inc.

AGREEMENT OF USE

COPYRIGHT RESTRICTIONS

Any unauthorized use of this specification may violate copyright laws, trademark laws, and communications regulations and statutes. This document contains information which is protected by copyright. All Rights Reserved. No part of this work covered by copyright herein may be reproduced or used in any form or by any means--graphic, electronic, or mechanical, including photocopying, recording, taping, or information storage and retrieval systems--without permission of the copyright owner.

OPC Foundation members and non-members are prohibited from copying and redistributing this specification. All copies must be obtained on an individual basis, directly from the OPC Foundation Web site
HTUhttp://www.opcfoundation.orgUTH.

PATENTS

The attention of adopters is directed to the possibility that compliance with or adoption of OPC specifications may require use of an invention covered by patent rights. OPC shall not be responsible for identifying patents for which a license may be required by any OPC specification, or for conducting legal inquiries into the legal validity or scope of those patents that are brought to its attention. OPC specifications are prospective and advisory only. Prospective users are responsible for protecting themselves against liability for infringement of patents.

WARRANTY AND LIABILITY DISCLAIMERS

WHILE THIS PUBLICATION IS BELIEVED TO BE ACCURATE, IT IS PROVIDED "AS IS" AND MAY CONTAIN ERRORS OR MISPRINTS. THE OPC FOUDATION MAKES NO WARRANTY OF ANY KIND, EXPRESSED OR IMPLIED, WITH REGARD TO THIS PUBLICATION, INCLUDING BUT NOT LIMITED TO ANY WARRANTY OF TITLE OR OWNERSHIP, IMPLIED WARRANTY OF MERCHANTABILITY OR WARRANTY OF FITNESS FOR A PARTICULAR PURPOSE OR USE. IN NO EVENT SHALL THE OPC FOUNDATION BE LIABLE FOR ERRORS CONTAINED HEREIN OR FOR DIRECT, INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, RELIANCE OR COVER DAMAGES, INCLUDING LOSS OF PROFITS, REVENUE, DATA OR USE, INCURRED BY ANY USER OR ANY THIRD PARTY IN CONNECTION WITH THE FURNISHING, PERFORMANCE, OR USE OF THIS MATERIAL, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

The entire risk as to the quality and performance of software developed using this specification is borne by you.

RESTRICTED RIGHTS LEGEND

This Specification is provided with Restricted Rights. Use, duplication or disclosure by the U.S. government is subject to restrictions as set forth in (a) this Agreement pursuant to DFARs 227.7202-3(a); (b) subparagraph (c)(1)(i) of the Rights in Technical Data and Computer Software clause at DFARs 252.227-7013; or (c) the Commercial Computer Software Restricted Rights clause at FAR 52.227-19 subdivision (c)(1) and (2), as applicable. Contractor / manufacturer are the OPC Foundation,. 16101 N. 82nd Street, Suite 3B, Scottsdale, AZ, 85260-1830

COMPLIANCE

The OPC Foundation shall at all times be the sole entity that may authorize developers, suppliers and sellers of hardware and software to use certification marks, trademarks or other special designations to indicate compliance with these materials. Products developed using this specification may claim compliance or conformance with this specification if and only if the software satisfactorily meets the certification requirements set by the OPC Foundation. Products that do not meet these requirements may claim only that the product was based on this specification and must not claim compliance or conformance with this specification.

Trademarks

Most computer and software brand names have trademarks or registered trademarks. The individual trademarks have not been listed here.

GENERAL PROVISIONS

Should any provision of this Agreement be held to be void, invalid, unenforceable or illegal by a court, the validity and enforceability of the other provisions shall not be affected thereby.

This Agreement shall be governed by and construed under the laws of the State of Minnesota, excluding its choice or law rules.

This Agreement embodies the entire understanding between the parties with respect to, and supersedes any prior understanding or agreement (oral or written) relating to, this specification.

ISSUE REPORTING

The OPC Foundation strives to maintain the highest quality standards for its published specifications, hence they undergo constant review and refinement. Readers are encouraged to report any issues and view any existing errata here: HTUhttp://www.opcfoundation.org/errataUTH

 


Revision 1.04 Highlights

The following table includes the Mantis issues resolved with this revision.

Mantis ID

Summary

Resolution

3662

3263

Requirement for a standard authorization pattern

Added description of Authorization Services in 6.2.

Extended chapters 7.36.5 IssuedIdentityToken and 7.36 UserTokenPolicy with OAuth2 and JWT related definitions.

3633

Requirement to optimize single Service invocations

Added concept of Session-less Service invocations in 6.3.

3678

Requirement to handle new attributes in AddNodes Service

Added generic structure that allows passing any number of NodeAttributes into AddNodes Service.

3135

Clarification publishing interval

Added clarification that a Client must be prepared for receiving Publish responses faster than the publishing interval.

3173

3190

Clarification Write of Variable Values with DataType LocalizedText

Added clarification that special rules for Attributes with DataType LocalizedText like DisplayName do not apply to the Value Attribute.

3272

Bad_SecurityModeInsufficient

Enhanced description of StatusCode.

3278

Call operation level results

Split operation result tables for operation level statusCode and inputArgumentResults parameters into two tables.

3319

Clarify that discovery is using SecureChannel with NONE

Added text that the SecureChannel for FindServers and GetEndpoints is created with MessageSecurityMode NONE.

3321

Avoid ‘omitted’ in services

Replaced ‘omitted’ with ‘null’ for optional service parameters.

3324

3739

SecureChannelId parameter in Open/CloseSecureChannel

Changed data type of secureChannelId to BaseDataType since the concrete type depends on protocol and is defined in Part 6.

3326

Clarification CloseSecureChannel

Added clarification that protocols defined in OPC 10000-6 may choose to omit the response.

3322

3323

3332

Specific definition which part of a certificate is used

Replaced general Certificate with public or private key in several places depending on the use case for signing and encryption.

3368

3622

Clarifications for Durable Subscriptions

Setting lifetimeInHours = 0 requests highest supported lifetime.

Added reference to Part 7 for minimum settings

3375

Fixes inconsistency with Part 5

Renamed redundancy mode HotPlusMirrored into HotAndMirrored to be consistent with enumeration in Part 5.

3421

Delay after failed user check

Added requirement to protect against user identity token attacks in ActivateSession.

3429

Certificate for SecureChannel

Removed shall for use of Application Instance Certificate use for SecureChannel. This is not possible for all protocol bindings.

3431

Clarification signature creation

Added clarification that signatures in CreateSession and ActivateSession are created with leaf certificate of a chain but the signature check must be done also with full chain if the check with just the leaf certificate fails.

3437

Status codes for RegisterServer2

Completed and restructured status code tables for RegisterServer2 service.

3464

NodeClass filter for remote nodes

NodeClass filter is ignored if NodeClass is unknown for remote nodes.

3478

Clarification StatusCode::InfoType

Removed limitation that info bits are only used with StatusCodes defined in OPC UA Part 8.

3507

Certificate Validation Steps

Added step “build certificate chain” and StatusCode Bad_CertificateChainIncomplete to Table 106 – Certificate Validation Steps.

3519

Status Bad_NotExecutable missing

Added status code Bad_NotExecutable.

3578

Missing required returned field in CreateSession::serverEndpoints

Added applicationUri to the list of required information in the serverEndpoints.

3588

Instantiation of Object and Variables with AddNodes

Added clarification that the full instance hierarchy is created for Objects and Variables based on the TypeDefinition.

3607

UserIdentityToken encryption

Clarified that the length in the UserIdentityToken encrypted token format is the length of the data to encrypt.

3626

Clarification of ResendData

Added clarification what is sent as current values in the case of ResendData is called or a subscription is transferred.

3630

Behaviour change for data change on NaN

A data change notification is only reported when the value enters or leaves the NaN state.

3782

New encrypted format for UserIdentityTokens

Added new EncryptedSecret format for UserIdentityTokens that requires encryption and signing of the user token secret.

3786

Reverse connect

Added references to reverse connect defined in Part 6 to SecureChannel Service Set and to definition of re-establishing connections.

3788

Extended filter in GetEndpoints

Added capability to extend filter capabilities in GetEndpoints by allowing query strings in the profileUris that are URLs.

3877

Nonce length in SecureChannel

Changes definition of nonce length in OpenSecureChannel to refer to new parameter SecureChannelNonceLength defined for a SecurityPolicy in Part 7.

3971

3972

HistoryRead ContinuationPoint clarifications

Changes Type of HistoryRead continuation point parameters from ByteString to ContinuationPoint.

Added clarifications in ContinuationPoint definition regarding ContinuationPoint release behaviour.

3976

Clarification certificate validation step

Added new Security Policy Check validation step that verifies if the certificate complies with the requirements defined in the SecurityPolicy.

 


OPC Unified Architecture Specification

 

Part 4: Services

 

 

 

1       Scope

This specification defines the OPC Unified Architecture (OPC UA) Services. The Services described are the collection of abstract Remote Procedure Calls (RPC) that are implemented by OPC UA Servers and called by OPC UA Clients. All interactions between OPC UA Clients and Servers occur via these Services. The defined Services are considered abstract because no particular RPC mechanism for implementation is defined in this part. OPC 10000-6 specifies one or more concrete mappings supported for implementation. For example, one mapping in OPC 10000-6 is to XML Web Services. In that case the Services described in this part appear as the Web service methods in the WSDL contract.

Not all OPC UA Servers will need to implement all of the defined Services. OPC 10000-7 defines the Profiles that dictate which Services need to be implemented in order to be compliant with a particular Profile.

2       Normative references

The following documents, in whole or in part, are normatively referenced in this document and are indispensable for its application. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments and errata) applies.

OPC 10000-1, OPC Unified Architecture - Part 1: Overview and Concepts

http://www.opcfoundation.org/UA/Part1/

OPC 10000-2, OPC Unified Architecture - Part 2: Security Model

http://www.opcfoundation.org/UA/Part2/

OPC 10000-3, OPC Unified Architecture - Part 3: Address Space Model

http://www.opcfoundation.org/UA/Part3/

OPC 10000-5, OPC Unified Architecture - Part 5: Information Model

http://www.opcfoundation.org/UA/Part5/

OPC 10000-6, OPC Unified Architecture - Part 6: Mappings

http://www.opcfoundation.org/UA/Part6/

OPC 10000-7, OPC Unified Architecture - Part 7: Profiles

http://www.opcfoundation.org/UA/Part7/

OPC 10000-8, OPC Unified Architecture - Part 8: Data Access

http://www.opcfoundation.org/UA/Part8/

OPC 10000-11, OPC Unified Architecture - Part 11: Historical Access

http://www.opcfoundation.org/UA/Part11/

OPC 10000-12, OPC Unified Architecture - Part 12: Discovery

http://www.opcfoundation.org/UA/Part12/

OPC 10000-13, OPC Unified Architecture - Part 13: Aggregates

http://www.opcfoundation.org/UA/Part13/

OPC 10000-14, OPC Unified Architecture - Part 14: PubSub

http://www.opcfoundation.org/UA/Part14/

3       Terms, definitions and conventions

3.1       Terms and definitions

For the purposes of this document, the terms and definitions given in The following documents, in whole or in part, are normatively referenced in this document and are indispensable for its application. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments and errata) applies.

OPC 10000-1, OPC 10000-2, and OPC 10000-3, as well as the following apply.

3.1.1         

Active Server

Server which is currently sourcing information

Note 1 to entry: In OPC UA redundant systems, an active Server is the Server that a Client is using as the source of data.

3.1.2         

Deadband

permitted range for value changes that will not trigger a data change Notification

Note 1 to entry: Deadband can be applied as a filter when subscribing to Variables and is used to keep noisy signals from updating the Client unnecessarily. This standard defines AbsoluteDeadband as a common filter. OPC 10000-8 defines an additional Deadband filter.

3.1.3         

DiscoveryEndpoint

Endpoint that allows Clients access to Discovery Services without security

Note 1 to entry: A DiscoveryEndpoint allows access to Discovery Services without a Session and without message security.

3.1.4         

Endpoint

physical address available on a network that allows Clients to access one or more Services provided by a Server

Note 1 to entry: Each Server may have multiple Endpoints. The address of an Endpoint must include a HostName.

3.1.5         

Failed Server

Server that is not operational.

Note 1 to entry: In OPC UA redundant system, a failed Server is a Server that is unavailable or is not able to serve data.

3.1.6         

Failover

act of switching the source or target of information.

Note 1 to entry: In OPC UA redundant systems, a failover is the act of a Client switching away from a failed or degraded Server to another Server in the redundant set (Server failover). In some cases a Client may have no knowledge of a failover action occurring (transparent redundancy). The act of an alternate Client replacing an existing failed or degraded Client connection to a Server (Client failover).

3.1.7         

Gateway Server

Server that acts as an intermediary for one or more Servers

Note 1 to entry: Gateway Servers may be deployed to limit external access, provide protocol conversion or to provide features that the underlying Servers do not support.

3.1.8         

Hostname

unique identifier for a machine on a network

Note 1 to entry: This identifier shall be unique within a local network; however, it may also be globally unique. The identifier can be an IP address.

3.1.9         

Security Token

identifier for a cryptographic key set

Note 1 to entry: All Security Tokens belong to a security context. For OPC UA the security context is the SecureChannel.

3.1.10       

SoftwareCertificate

digital certificate for a software product that can be installed on several hosts to describe the capabilities of the software product

Note 1 to entry: Different installations of one software product could have the same software certificate. Software certificates are not relevant for security. They are used to identify a software product and its supported features. SoftwareCertificates are described in 6.4.

3.1.11       

Redundancy

the presence of duplicate components enabling the continued operation after a failure of an OPC UA component

Note 1 This may apply to Servers, Clients or networks.

3.1.12       

Redundant Server Set

two or more Servers that are redundant with each other

Note 1 A redundant server set is a group of Servers that are configured to provide Redundancy. These Servers have requirements related to the address space and provide failovers.

3.2       Abbreviations and symbols

API     Application Programming Interface

BNF    Backus-Naur Form

CA      Certificate Authority

CRL    Certificate Revocation List

CTL    Certificate Trust List

DA      Data Access

NAT    Network Address Translation

UA      Unified Architecture

URI     Uniform Resource Identifier

URL    Uniform Resource Locator

3.3       Conventions for Service definitions

OPC UA Services contain parameters that are conveyed between the Client and the Server. The OPC UA Service specifications use tables to describe Service parameters, as shown in Table 1. Parameters are organised in this table into request parameters and response parameters.

Table 1 – Service Definition Table

Name

Type

Description

Request

 

Defines the request parameters of the Service

    Simple Parameter Name

 

Description of this parameter

    Constructed Parameter Name

 

Description of the constructed parameter

       Component Parameter Name

 

Description of the component parameter

 

 

 

Response

 

Defines the response parameters of the Service

 

 

 

 

The Name, Type and Description columns contain the name, data type and description of each parameter. All parameters are mandatory, although some may be unused under certain circumstances. The Description column specifies the value to be supplied when a parameter is unused.

Two types of parameters are defined in these tables, simple and constructed. Simple parameters have a simple data type, such as Boolean or String.

Constructed parameters are composed of two or more component parameters, which can be simple or constructed. Component parameter names are indented below the constructed parameter name.

The data types used in these tables may be base types, common types to multiple Services or Service-specific types. Base data types are defined in OPC 10000-3. The base types used in Services are listed in Table 2. Data types that are common to multiple Services are defined in Clause 7. Data types that are Service-specific are defined in the parameter table of the Service.

Table 2 – Parameter Types defined in OPC 10000-3

Parameter Type

BaseDataType

Boolean

ByteString

Double

Duration

Guid

Int32

LocaleId

NodeId

QualifiedName

String

UInt16

UInt32

UInteger

UtcTime

XmlElement

 

The parameters of the Request and Indication service primitives are represented in Table 1 as Request parameters. Likewise, the parameters of the Response and Confirmation service primitives are represented in Table 1 as Response parameters. All request and response parameters are conveyed between the sender and receiver without change. Therefore, separate columns for request, indication, response and confirmation parameter values are not needed and have been intentionally omitted to improve readability.

4       Overview

4.1       Service Set model

This clause specifies the OPC UA Services. The OPC UA Service definitions are abstract descriptions and do not represent a specification for implementation. The mapping between the abstract descriptions and the Communication Stack derived from these Services are defined in OPC 10000-6. In the case of an implementation as web services, the OPC UA Services correspond to the web service and an OPC UA Service corresponds to an operation of the web service.

These Services are organised into Service Sets. Each Service Set defines a set of related Services. The organisation in Service Sets is a logical grouping used in this standard and is not used in the implementation.

The Discovery Service Set, illustrated in Figure 1, defines Services that allow a Client to discover the Endpoints implemented by a Server and to read the security configuration for each of those Endpoints.

Figure4_

Figure 1 – Discovery Service Set

The SecureChannel Service Set, illustrated in Figure 2, defines Services that allow a Client to establish a communication channel to ensure the Confidentiality and Integrity of Messages exchanged with the Server.

Figure5_ 

Figure 2 – SecureChannel Service Set

The Session Service Set, illustrated in Figure 3, defines Services that allow the Client to authenticate the user on whose behalf it is acting and to manage Sessions.

Figure6_

Figure 3 – Session Service Set

The NodeManagement Service Set, illustrated in Figure 4, defines Services that allow the Client to add, modify and delete Nodes in the AddressSpace.

Figure7_

Figure 4 – NodeManagement Service Set

The View Service Set, illustrated in Figure 5, defines Services that allow Clients to browse through the AddressSpace or subsets of the AddressSpace called Views. The Query Service Set allows Clients to get a subset of data from the AddressSpace or the View.

Figure8_

Figure 5 – View Service Set

The Attribute Service Set is illustrated in Figure 6. It defines Services that allow Clients to read and write Attributes of Nodes, including their historical values. Since the value of a Variable is modelled as an Attribute, these Services allow Clients to read and write the values of Variables.

Figure9_

Figure 6 – Attribute Service Set

The Method Service Set is illustrated in Figure 7. It defines Services that allow Clients to call methods. Methods run to completion when called. They may be called with method-specific input parameters and may return method-specific output parameters.

Figure10_

Figure 7 – Method Service Set

The MonitoredItem Service Set and the Subscription Service Set, illustrated in Figure 8, are used together to subscribe to Nodes in the OPC UA AddressSpace.

The MonitoredItem Service Set defines Services that allow Clients to create, modify, and delete MonitoredItems used to monitor Attributes for value changes and Objects for Events.

These Notifications are queued for transfer to the Client by Subscriptions.

The Subscription Service Set defines Services that allow Clients to create, modify and delete Subscriptions. Subscriptions send Notifications generated by MonitoredItems to the Client. Subscription Services also provide for Client recovery from missed Messages and communication failures.

Figure11_

Figure 8 – MonitoredItem and Subscription Service Sets

4.2       Request/response Service procedures

Request/response Service procedures describe the processing of requests received by the Server, and the subsequent return of responses. The procedures begin with the requesting Client submitting a Service request Message to the Server.

Upon receipt of the request, the Server processes the Message in two steps. In the first step, it attempts to decode and locate the Service to execute. The error handling for this step is specific to the communication technology used and is described in OPC 10000-6.

If it succeeds, then it attempts to access each operation identified in the request and perform the requested operation. For each operation in the request, it generates a separate success/failure code that it includes in a positive response Message along with any data that is to be returned.

To perform these operations, both the Client and the Server may make use of the API of a Communication Stack to construct and interpret Messages and to access the requested operation.

The implementation of each service request or response handling shall check that each service parameter lies within the specified range for that parameter.

5       Service Sets

5.1       General

This clause defines the OPC UA Service Sets and their Services. Clause 7 contains the definitions of common parameters used by these Services. Clause 6.5 describes auditing requirements for all services.

Whether or not a Server supports a Service Set, or a Service within a Service Set, is defined by its Profile. Profiles are described in OPC 10000-7.

5.2       Service request and response header

Each Service request has a RequestHeader and each Service response has a ResponseHeader.

The RequestHeader structure is defined in 7.28 and contains common request parameters such as authenticationToken, timestamp and requestHandle.

The ResponseHeader structure is defined in 7.29 and contains common response parameters such as serviceResult and diagnosticInfo.

5.3       Service results

Service results are returned at two levels in OPC UA responses, one that indicates the status of the Service call, and the other that indicates the status of each operation requested by the Service.

Service results are defined via the StatusCode (see 7.34).

The status of the Service call is represented by the serviceResult contained in the ResponseHeader (see 7.29). The mechanism for returning this parameter is specific to the communication technology used to convey the Service response and is defined in
OPC 10000-6.

The status of individual operations in a request is represented by individual StatusCodes.

The following cases define the use of these parameters.

a)   A bad code is returned in serviceResult if the Service itself failed. In this case, a ServiceFault is returned. The ServiceFault is defined in 7.30.

b)   The good code is returned in serviceResult if the Service fully or partially succeeded. In this case, other response parameters are returned. The Client shall always check the response parameters, especially all StatusCodes associated with each operation. These StatusCodes may indicate bad or uncertain results for one or more operations requested in the Service call.

All Services with arrays of operations in the request shall return a bad code in the serviceResult if the array is empty.

The Services define various specific StatusCodes and a Server shall use these specific StatusCodes as described in the Service. A Client should be able to handle these Service specific StatusCodes. In addition, a Client shall expect other common StatusCodes defined in Table 177 and Table 178. Additional details for Client handling of specific StatusCodes may be defined in OPC 10000-7.

If the Server discovers, through some out-of-band mechanism that the application or user credentials used to create a Session or SecureChannel have been compromised, then the Server should immediately terminate all sessions and channels that use those credentials. In this case, the Service result code should be either Bad_IdentityTokenRejected or Bad_CertificateUntrusted.

Message parsing can fail due to syntax errors or if data contained within the message exceeds ranges supported by the receiver. When this happens messages shall be rejected by the receiver. If the receiver is a Server then it shall return a ServiceFault with result code of Bad_DecodingError or Bad_EncodingLimitsExceeded. If the receiver is the Client then the Communication Stack should report these errors to the Client application.

Many applications will place limits on the size of messages and/or data elements contained within these messages. For example, a Server may reject requests containing string values longer than a certain length. These limits are typically set by administrators and apply to all connections between a Client and a Server.

Clients that receive Bad_EncodingLimitsExceeded faults from the Server will likely have to reformulate their requests. The administrator may need to increase the limits for the Client if it receives a response from the Server with this fault.

In some cases, parsing errors are fatal and it is not possible to return a fault. For example, the incoming message could exceed the buffer capacity of the receiver. In these cases, these errors may be treated as a communication fault which requires the SecureChannel to be re-established (see 5.5).

The Client and Server reduce the chances of a fatal error by exchanging their message size limits in the CreateSession service. This will allow either party to avoid sending a message that causes a communication fault. The Server should return a Bad_ResponseTooLarge fault if a serialized response message exceeds the message size specified by the Client. Similarly, the Client Communication Stack should report a Bad_RequestTooLarge error to the application before sending a message that exceeds the Server’s limit.

Note that the message size limits only apply to the raw message body and do not include headers or the effect of applying any security. This means that a message body that is smaller than the specified maximum could still cause a fatal error.

5.4       Discovery Service Set

5.4.1        Overview

This Service Set defines Services used to discover the Endpoints implemented by a Server and to read the security configuration for those Endpoints. The Discovery Services are implemented by individual Servers and by dedicated Discovery Servers. OPC 10000-12 describes how to use the Discovery Services with dedicated Discovery Servers.

Every Server shall have a DiscoveryEndpoint that Clients can access without establishing a Session. This Endpoint may or may not be the same Session Endpoint that Clients use to establish a SecureChannel. Clients read the security information necessary to establish a SecureChannel by calling the GetEndpoints Service on the DiscoveryEndpoint.

In addition, Servers may register themselves with a well-known Discovery Server using the RegisterServer Service. Clients can later discover any registered Servers by calling the FindServers Service on the Discovery Server.

The discovery process using FindServers is illustrated in Figure 9. The establishment of a SecureChannel (with MessageSecurityMode NONE) for FindServers and GetEndpoints is omitted from the figure for clarity.

Figure12_

Figure 9 – Discovery process

The URL for a DiscoveryEndpoint shall provide all of the information that the Client needs to connect to the DiscoveryEndpoint.

Once a Client retrieves the Endpoints, the Client can save this information and use it to connect directly to the Server again without going through the discovery process. If the Client finds that it cannot connect then the Server configuration may have changed and the Client needs to go through the discovery process again.

DiscoveryEndpoints shall not require any message security, but it may require transport layer security. In production systems, Administrators may disable discovery for security reasons and Clients shall rely on cached EndpointDescriptions. To provide support for systems with disabled Discovery Services Clients shall allow Administrators to manually update the EndpointDescriptions used to connect to a Server. Servers shall allow Administrators to disable the DiscoveryEndpoint.

A Client shall be careful when using the information returned from a DiscoveryEndpoint since it has no security. A Client does this by comparing the information returned from the DiscoveryEndpoint to the information returned in the CreateSession response. A Client shall verify that:

a)    The ApplicationUri specified in the Server Certificate is the same as the ApplicationUri provided in the EndpointDescription.

b)    The Server Certificate returned in CreateSession response is the same as the Certificate used to create the SecureChannel.

c)    The EndpointDescriptions returned from the DiscoveryEndpoint are the same as the EndpointDescriptions returned in the CreateSession response.

If the Client detects that one of the above requirements is not fulfilled, then the Client shall close the SecureChannel and report an error.

A Client shall verify the HostName specified in the Server Certificate is the same as the HostName contained in the endpointUrl provided in the EndpointDescription returned by CreateSession. If there is a difference then the Client shall report the difference and may close the SecureChannel. Servers shall add all possible HostNames like MyHost and MyHost.local into the Server Certificate. This includes IP addresses of the host or the HostName exposed by a NAT router used to connect to the Server.

5.4.2        FindServers

5.4.2.1         Description

This Service returns the Servers known to a Server or Discovery Server. The behaviour of Discovery Servers is described in detail in OPC 10000-12.

The Client may reduce the number of results returned by specifying filter criteria. A Discovery Server returns an empty list if no Servers match the criteria specified by the client. The filter criteria supported by this Service are described in 5.4.2.2.

Every Server shall provide a DiscoveryEndpoint that supports this Service. The Server shall always return a record that describes itself, however in some cases more than one record may be returned. Gateway Servers shall return a record for each Server that they provide access to plus (optionally) a record that allows the Gateway Server to be accessed as an ordinary OPC UA Server. Non-transparent redundant Servers shall provide a record for each Server in the Redundant Server Set.

Every Server shall have a globally unique identifier called the ServerUri. This identifier should be a fully qualified domain name; however, it may be a GUID or similar construct that ensures global uniqueness. The ServerUri returned by this Service shall be the same value that appears in index 0 of the ServerArray property (see OPC 10000-5). The ServerUri is returned as the applicationUri field in the ApplicationDescription (see 7.1)

Every Server shall also have a human readable identifier called the ServerName which is not necessarily globally unique. This identifier may be available in multiple locales.

A Server may have multiple HostNames. For this reason, the Client shall pass the URL it used to connect to the Endpoint to this Service. The implementation of this Service shall use this information to return responses that are accessible to the Client via the provided URL.

This Service shall not require message security but it may require transport layer security.

Some Servers may be accessed via a Gateway Server and shall have a value specified for gatewayServerUri in their ApplicationDescription (see 7.1). The discoveryUrls provided in ApplicationDescription shall belong to the Gateway Server. Some Discovery Servers may return multiple records for the same Server if that Server can be accessed via multiple paths.

This Service can be used without security and it is therefore vulnerable to Denial of Service (DOS) attacks. A Server should minimize the amount of processing required to send the response for this Service. This can be achieved by preparing the result in advance. The Server should also add a short delay before starting processing of a request during high traffic conditions.

5.4.2.2         Parameters

Table 3 defines the parameters for the Service.

Table 3 – FindServers Service Parameters

Name

Type

Description

Request

 

 

    requestHeader

RequestHeader

Common request parameters. The authenticationToken is always null. The authenticationToken shall be ignored if it is provided.

The type RequestHeader is defined in 7.28.

    endpointUrl

String

The network address that the Client used to access the DiscoveryEndpoint.

The Server uses this information for diagnostics and to determine what URLs to return in the response.

The Server should return a suitable default URL if it does not recognize the HostName in the URL.

    localeIds []

LocaleId

List of locales to use.

The Server should return the applicationName in the ApplicationDescription defined in 7.1 using one of locales specified. If the Server supports more than one of the requested locales then the Server shall use the locale that appears first in this list. If the Server does not support any of the requested locales it chooses an appropriate default locale.

The Server chooses an appropriate default locale if this list is empty.

    serverUris []

String

List of servers to return.

All known servers are returned if the list is empty.

A serverUri matches the applicationUri from the ApplicationDescription defined in 7.1.

 

 

 

Response

 

 

    responseHeader

ResponseHeader

Common response parameters.

The ResponseHeader type is defined in 7.29.

    servers []

ApplicationDescription

List of Servers that meet criteria specified in the request.

This list is empty if no servers meet the criteria.

The ApplicationDescription type is defined in 7.1.

 

5.4.2.3         Service results

Common StatusCodes are defined in Table 177.

5.4.3        FindServersOnNetwork

5.4.3.1         Description

This Service returns the Servers known to a Discovery Server. Unlike FindServers, this Service is only implemented by Discovery Servers.

The Client may reduce the number of results returned by specifying filter criteria. An empty list is returned if no Server matches the criteria specified by the Client.

This Service shall not require message security but it may require transport layer security.

Each time the Discovery Server creates or updates a record in its cache it shall assign a monotonically increasing identifier to the record. This allows Clients to request records in batches by specifying the identifier for the last record received in the last call to FindServersOnNetwork. To support this the Discovery Server shall return records in numerical order starting from the lowest record identifier. The Discovery Server shall also return the last time the counter was reset for example due to a restart of the Discovery Server. If a Client detects that this time is more recent than the last time the Client called the Service it shall call the Service again with a startingRecordId of 0.

This Service can be used without security and it is therefore vulnerable to denial of service (DOS) attacks. A Server should minimize the amount of processing required to send the response for this Service. This can be achieved by preparing the result in advance.

5.4.3.2         Parameters

Table 4 defines the parameters for the Service.

Table 4 – FindServersOnNetwork Service Parameters

Name

Type

Description

Request

 

 

requestHeader

RequestHeader

Common request parameters. The authenticationToken is always null. The authenticationToken shall be ignored if it is provided.

The type RequestHeader is defined in 7.28.

startingRecordId

Counter

Only records with an identifier greater than this number will be returned.

Specify 0 to start with the first record in the cache.

maxRecordsToReturn

UInt32

The maximum number of records to return in the response.

0 indicates that there is no limit.

serverCapabilityFilter[]

String

List of Server capability filters. The set of allowed Server capabilities are defined in OPC 10000-12.

Only records with all of the specified Server capabilities are returned.

The comparison is case insensitive.

If this list is empty then no filtering is performed.

 

 

 

Response

 

 

responseHeader

ResponseHeader

Common response parameters.

The ResponseHeader type is defined in 7.29.

lastCounterResetTime

UtcTime

The last time the counters were reset.

servers[]

ServerOnNetwork

List of DNS service records that meet criteria specified in the request.

This list is empty if no Servers meet the criteria.

      recordId

UInt32

A unique identifier for the record.

This can be used to fetch the next batch of Servers in a subsequent call to FindServersOnNetwork.

      serverName

String

The name of the Server specified in the mDNS announcement (see OPC 10000-12).

This may be the same as the ApplicationName for the Server.

      discoveryUrl

String

The URL of the DiscoveryEndpoint.

      serverCapabilities

String[]

The set of Server capabilities supported by the Server.

The set of allowed Server capabilities are defined in OPC 10000-12.

 

5.4.3.3         Service results

Common StatusCodes are defined in Table 177.

5.4.4        GetEndpoints

5.4.4.1         Description

This Service returns the Endpoints supported by a Server and all of the configuration information required to establish a SecureChannel and a Session.

This Service shall not require message security but it may require transport layer security.

A Client may reduce the number of results returned by specifying filter criteria based on LocaleIds and Transport Profile URIs. The Server returns an empty list if no Endpoints match the criteria specified by the client. The filter criteria supported by this Service are described in 5.4.4.2.

A Server may support multiple security configurations for the same Endpoint. In this situation, the Server shall return separate EndpointDescription records for each available configuration. Clients should treat each of these configurations as distinct Endpoints even if the physical URL happens to be the same.

The security configuration for an Endpoint has four components:

Server Application Instance Certificate

Message Security Mode

Security Policy

Supported User Identity Tokens

The ApplicationInstanceCertificate is used to secure the OpenSecureChannel request (see 5.5.2). The MessageSecurityMode and the SecurityPolicy tell the Client how to secure messages sent via the SecureChannel. The UserIdentityTokens tell the Client which type of user credentials shall be passed to the Server in the ActivateSession request (see 5.6.3).

If the securityPolicyUri is NONE and none of the UserTokenPolicies requires encryption, the Client shall ignore the ApplicationInstanceCertificate.

Each EndpointDescription also specifies a URI for the Transport Profile that the Endpoint supports. The Transport Profiles specify information such as message encoding format and protocol version and are defined in OPC 10000-7.

Messages are secured by applying standard cryptography algorithms to the messages before they are sent over the network. The exact set of algorithms used depends on the SecurityPolicy for the Endpoint. OPC 10000-7 defines Profiles for common SecurityPolicies and assigns a unique URI to them. It is expected that applications have built in knowledge of the SecurityPolicies that they support, as a result, only the Profile URI for the SecurityPolicy is specified in the EndpointDescription. A Client cannot connect to an Endpoint that does not support a SecurityPolicy that it recognizes.

An EndpointDescription may specify that the message security mode is NONE. This configuration is not recommended unless the applications are communicating on a physically isolated network where the risk of intrusion is extremely small. If the message security is NONE then it is possible for Clients to deliberately or accidentally hijack Sessions created by other Clients.

A Server may have multiple HostNames. For this reason, the Client shall pass the URL it used to connect to the Endpoint to this Service. The implementation of this Service shall use this information to return responses that are accessible to the Client via the provided URL.

This Service can be used without security and it is therefore vulnerable to Denial of Service (DOS) attacks. A Server should minimize the amount of processing required to send the response for this Service. This can be achieved by preparing the result in advance. The Server should also add a short delay before starting processing of a request during high traffic conditions.

Some of the EndpointDescriptions returned in a response shall specify the Endpoint information for a Gateway Server that can be used to access another Server. In these situations, the gatewayServerUri is specified in the EndpointDescription and all security checks used to verify Certificates shall use the gatewayServerUri (see 6.1.3) instead of the serverUri.

To connect to a Server via the gateway the Client shall first establish a SecureChannel with the Gateway Server. Then the Client shall call the CreateSession service and pass the serverUri specified in the EndpointDescription to the Gateway Server. The Gateway Server shall then connect to the underlying Server on behalf of the Client. The process of connecting to a Server via a Gateway Server is illustrated in Figure 10.

Figure13_

Figure 10 – Using a Gateway Server

5.4.4.2         Parameters

Table 5 defines the parameters for the Service.

Table 5 – GetEndpoints Service Parameters

Name

Type

Description

Request

 

 

    requestHeader

RequestHeader

Common request parameters.

The authenticationToken is always null. The authenticationToken shall be ignored if it is provided.

The type RequestHeader is defined in 7.28.

    endpointUrl

String

The network address that the Client used to access the DiscoveryEndpoint.

The Server uses this information for diagnostics and to determine what URLs to return in the response.

The Server should return a suitable default URL if it does not recognize the HostName in the URL.

    localeIds []

LocaleId

List of locales to use.

Specifies the locale to use when returning human readable strings.

This parameter is described in 5.4.2.2.

    profileUris []

String

List of Transport Profile that the returned Endpoints shall support. OPC 10000-7 defines URIs for the Transport Profiles.

All Endpoints are returned if the list is empty.

If the URI is a URL, this URL may have a query string appended. The Transport Profiles that support query strings are defined in OPC 10000-7.

 

 

 

Response

 

 

    responseHeader

ResponseHeader

Common response parameters.

The ResponseHeader type is defined in 7.29.

    Endpoints []

EndpointDescription

List of Endpoints that meet criteria specified in the request.

This list is empty if no Endpoints meet the criteria.

The EndpointDescription type is defined in 7.10.

 

5.4.4.3         Service Results

Common StatusCodes are defined in Table 177.

5.4.5        RegisterServer

5.4.5.1         Description

This Service is implemented by Discovery Servers.

This Service registers a Server with a Discovery Server. This Service will be called by a Server or a separate configuration utility. Clients will not use this Service.

A Server shall establish a SecureChannel with the Discovery Server before calling this Service. The SecureChannel is described in 5.5. The Administrator of the Server shall provide the Server with an EndpointDescription for the Discovery Server as part of the configuration process. Discovery Servers shall reject registrations if the serverUri provided does not match the applicationUri in Server Certificate used to create the SecureChannel.

This Service can only be invoked via SecureChannels that support Client authentication (i.e. HTTPS cannot be used to call this Service).

A Server only provides its serverUri and the URLs of the DiscoveryEndpoints to the Discovery Server. Clients shall use the GetEndpoints Service to fetch the most up to date configuration information directly from the Server.

The Server shall provide a localized name for itself in all locales that it supports.

Servers shall be able to register themselves with a Discovery Server running on the same machine. The exact mechanisms depend on the Discovery Server implementation and are described in OPC 10000-6.

There are two types of Server applications: those which are manually launched including a start by the operating system at boot and those that are automatically launched when a Client attempts to connect. The registration process that a Server shall use depends on which category it falls into.

The registration process for manually launched Servers is illustrated in Figure 11.

Figure14_

Figure 11 – The Registration Process – Manually Launched Servers

The registration process for automatically launched Servers is illustrated in Figure 12.

Figure15_

Figure 12 – The Registration Process – Automatically Launched Servers

The registration process is designed to be platform independent, robust and able to minimize problems created by configuration errors. For that reason, Servers shall register themselves more than once.

Under normal conditions, manually launched Servers shall periodically register with the Discovery Server as long as they are able to receive connections from Clients. If a Server goes offline then it shall register itself once more and indicate that it is going offline. The period of the recurring registration should be configurable; however, the maximum is 10 minutes. If an error occurs during registration (e.g. the Discovery Server is not running) then the Server shall periodically re-attempt registration. The frequency of these attempts should start at 1 second but gradually increase until the registration frequency is the same as what it would be if no errors occurred. The recommended approach would be to double the period of each attempt until reaching the maximum.

When an automatically launched Server (or its install program) registers with the Discovery Server it shall provide a path to a semaphore file which the Discovery Server can use to determine if the Server has been uninstalled from the machine. The Discovery Server shall have read access to the file system that contains the file.

5.4.5.2         Parameters

Table 6 defines the parameters for the Service.

Table 6 – RegisterServer Service Parameters

Name

Type

Description

Request

 

 

    requestHeader

RequestHeader

Common request parameters.

The authenticationToken is always null.

The type RequestHeader is defined in 7.28.

    Server

RegisteredServer

The Server to register. The type RegisteredServer is defined in 7.27.

 

 

 

Response

 

 

    ResponseHeader

ResponseHeader

Common response parameters.

The type ResponseHeader is defined in 7.29.

 

5.4.5.3         Service Results

Table 7 defines the Service results specific to this Service. Common StatusCodes are defined in Table 177.

Table 7 – RegisterServer Service Result Codes

Symbolic Id

Description

Bad_InvalidArgument

See Table 177 for the description of this result code.

Bad_ServerUriInvalid

See Table 177 for the description of this result code.

Bad_ServerNameMissing

No ServerName was specified.

Bad_DiscoveryUrlMissing

No discovery URL was specified.

Bad_SemaphoreFileMissing

The semaphore file specified is not valid.

 

5.4.6        RegisterServer2

5.4.6.1         Description

This Service is implemented by Discovery Servers.

This Service allows a Server to register its DiscoveryUrls and capabilities with a Discovery Server. It extends the registration information from RegisterServer with information necessary for FindServersOnNetwork. This Service will be called by a Server or a separate configuration utility. Clients will not use this Service.

Servers that support RegisterServer2 shall try to register with the Discovery Server using this Service and shall fall back to RegisterServer if RegisterServer2 fails with the status Bad_ServiceUnsupported.

A Discovery Server that implements this Service needs to assign unique record ids each time this Service is called. See 5.4.3 for more details.

This Service can only be invoked via SecureChannels that support Client authentication (i.e. HTTPS cannot be used to call this Service).

5.4.6.2         Parameters

Table 8 defines the parameters for the Service.

Table 8 – RegisterServer2

Name

Type

Description

Request

 

 

    requestHeader

RequestHeader

Common request parameters.

The authenticationToken is always null.

The type RequestHeader is defined in 7.28.

    Server

RegisteredServer

The Server to register. The type RegisteredServer is defined in 7.27.

    discoveryConfiguration []

ExtensibleParameter DiscoveryConfiguration

Additional configuration settings for the Server to register.

The discoveryConfiguration is an extensible parameter type defined in 7.9.

Discovery Servers that do not understand a configuration shall return Bad_NotSupported for this configuration.

 

 

 

Response

 

 

    ResponseHeader

ResponseHeader

Common response parameters.

The type ResponseHeader is defined in 7.29.

    configurationResults []

StatusCode

List of results for the discoveryConfiguration parameters.

    diagnosticInfos []

DiagnosticInfo

List of diagnostic information for the discoveryConfiguration parameters. This list is empty if diagnostics information was not requested in the request header or if no diagnostic information was encountered in processing of the request.

 

5.4.6.3         Service results

Table 9 defines the Service results specific to this Service. Common StatusCodes are defined in Table 177.

Table 9 – RegisterServer2 Service Result Codes

Symbolic Id

Description

Bad_InvalidArgument

See Table 177 for the description of this result code.

Bad_ServerUriInvalid

See Table 177 for the description of this result code.

Bad_ServerNameMissing

No ServerName was specified.

Bad_DiscoveryUrlMissing

No discovery URL was specified.

Bad_SemaphoreFileMissing

The semaphore file specified is not valid.

Bad_ServiceUnsupported

See Table 177 for the description of this result code.

 

5.4.6.4         StatusCodes

Table 10 defines values for the operation level statusCode parameters that are specific to this Service. Common StatusCodes are defined in Table 178.

Table 10 – RegisterServer2 Operation Level Result Codes

Symbolic Id

Description

Bad_NotSupported

See Table 178 for the description of this result code.

 

5.5       SecureChannel Service Set

5.5.1        Overview

This Service Set defines Services used to open a communication channel that ensures the confidentiality and Integrity of all Messages exchanged with the Server. The base concepts for OPC UA security are defined in OPC 10000-2.

The SecureChannel Services are unlike other Services because they are not implemented directly by the OPC UA Application. Instead, they are provided by the Communication Stack on which the OPC UA Application is built. For example, an OPC UA Server may be built on a stack that allows applications to establish a SecureChannel using HTTPS. In these cases, the OPC UA Application shall verify that the Message it received was in the context of an HTTPS connection. OPC 10000-6 describes how the SecureChannel Services are implemented.

A SecureChannel is a long-running logical connection between a single Client and a single Server. This channel maintains a set of keys known only to the Client and Server, which are used to authenticate and encrypt Messages sent across the network. The SecureChannel Services allow the Client and Server to securely negotiate the keys to use.

Logical connections may be initiated by the Client or by the Server as described in OPC 10000-6. After the connection is initiated, the SecureChannel is opened and closed by the Client using the SecureChannel Services.

An EndpointDescription tells a Client how to establish a SecureChannel with a given Endpoint. A Client may obtain the EndpointDescription from a Discovery Server, via some non-UA defined directory server or from its own configuration.

The exact algorithms used to authenticate and encrypt Messages are described in the SecurityPolicy field of the EndpointDescription. A Client shall use these algorithms when it creates a SecureChannel.

It should be noted that some SecurityPolicies defined in OPC 10000-7 will turn off authentication and encryption resulting in a SecureChannel that provides no security.

When a Client and Server are communicating via a SecureChannel, they shall verify that all incoming Messages have been signed and encrypted according to the requirements specified in the EndpointDescription. An OPC UA Application shall not process any Message that does not conform to these requirements.

The relationship between the SecureChannel and the OPC UA Application depends on the implementation technology. OPC 10000-6 defines any requirements that depend on the technology used.

The correlation between the OPC UA Application Session and the SecureChannel is illustrated in Figure 13. The Communication Stack is used by the OPC UA Applications to exchange Messages. In the first step, the SecureChannel Services are used to establish a SecureChannel between the two Communication Stacks which allows the secure exchange of Messages. In the second step, the OPC UA Applications use the Session Service Set to establish an OPC UA Application Session.

Figure16_

Figure 13 – SecureChannel and Session Services

Once a Client has established a Session it may wish to access the Session from a different SecureChannel. The Client can do this by validating the new SecureChannel with the ActivateSession Service described in 5.6.3.

If a Server acts as a Client to other Servers, which is commonly referred to as Server chaining, then the Server shall be able to maintain user level security. By this we mean that the user identity should be passed to the underlying Server or it should be mapped to an appropriate user identity in the underlying server. It is unacceptable to ignore user level security. This is required to ensure that security is maintained and that a user does not obtain information that they should not have access to. Whenever possible a Server should impersonate the original Client by passing the original Client’s user identity to the underlying Server when it calls the ActivateSession Service. If impersonation is not an option then the Server shall map the original Client’s user identity onto a new user identity which the underlying Server does recognize.

5.5.2        OpenSecureChannel

5.5.2.1         Description

This Service is used to open or renew a SecureChannel that can be used to ensure Confidentiality and Integrity for Message exchange during a Session. This Service requires the Communication Stack to apply the various security algorithms to the Messages as they are sent and received. Specific implementations of this Service for different Communication Stacks are described in OPC 10000-6.

Each SecureChannel has a globally-unique identifier and is valid for a specific combination of Client and Server application instances. Each channel contains one or more SecurityTokens that identify a set of cryptography keys that are used to encrypt and authenticate Messages. SecurityTokens also have globally-unique identifiers which are attached to each Message secured with the token. This allows an authorized receiver to know how to decrypt and verify the Message.

SecurityTokens have a finite lifetime negotiated with this Service. However, differences between the system clocks on different machines and network latencies mean that valid Messages could arrive after the token has expired. To prevent valid Messages from being discarded, the applications should do the following:

a)    Clients should request a new SecurityToken after 75 % of its lifetime has elapsed. This should ensure that Clients will receive the new SecurityToken before the old one actually expires.

b)    Servers shall use the existing SecurityToken to secure outgoing Messages until the SecurityToken expires or the Server receives a Message secured with a new SecurityToken. This should ensure that Clients do not reject Messages secured with the new SecurityToken that arrive before the Client receives the new SecurityToken.

c)    Clients should accept Messages secured by an expired SecurityToken for up to 25 % of the token lifetime. This should ensure that Messages sent by the Server before the token expired are not rejected because of network delays.

Each SecureChannel exists until it is explicitly closed or until the last token has expired and the overlap period has elapsed. A Server application should limit the number of SecureChannels. To protect against misbehaving Clients and denial of service attacks, the Server shall close the oldest SecureChannel that has no Session assigned before reaching the maximum number of supported SecureChannels.

The OpenSecureChannel request and response Messages shall be signed with the sender's private key. These Messages shall always be encrypted. If the transport layer does not provide encryption, then these Messages shall be encrypted with the receiver's public key. These requirements for OpenSecureChannel only apply if the securityPolicyUri is not None.

If the protocol defined in OPC 10000-6 requires that Application Instance Certificates are used in the OpenSecureChannel Service, then Clients and Servers shall verify that the same Certificates are used in the CreateSession and ActivateSession Services. Certificates are not provided and shall not be verified if the securityPolicyUri is None.

If the securityPolicyUri is not None, a Client shall verify the HostName specified in the Server Certificate is the same as the HostName contained in the endpointUrl. If there is a difference then the Client shall report the difference and may choose to not open the SecureChannel. Servers shall add all possible HostNames like MyHost and MyHost.local into the Server Certificate. This includes IP addresses of the host or the HostName exposed by a NAT router used to connect to the Server.

Clients should be prepared to replace the HostName returned in the EndpointDescription with the HostName or the IP addresses they used to call GetEndpoints.

5.5.2.2         Parameters

Table 11 defines the parameters for the Service.

Unlike other Services, the parameters for this Service provide only an abstract definition. The concrete representation on the network depends on the mappings defined in OPC 10000-6.

Table 11 – OpenSecureChannel Service Parameters

Name

Type

Description

Request

 

 

    requestHeader

RequestHeader

Common request parameters. The authenticationToken is always null.

The type RequestHeader is defined in 7.28.

    clientCertificate

ApplicationInstance‌Certificate

A Certificate that identifies the Client.

The OpenSecureChannel request shall be signed with the private key for this Certificate.

The ApplicationInstanceCertificate type is defined in 7.2.

If the securityPolicyUri is None, the Server shall ignore the ApplicationInstanceCertificate.

    requestType

Enum

SecurityToken RequestType

The type of SecurityToken request:

An enumeration that shall be one of the following:

    ISSUE_0      creates a new SecurityToken for a new SecureChannel.

    RENEW_1           creates a new SecurityToken for an existing SecureChannel.

    secureChannelId

BaseDataType

The identifier for the SecureChannel that the new token should belong to. This parameter shall be null when creating a new SecureChannel.

The concrete security protocol definition in OPC 10000-6 chooses the concrete DataType.

    securityMode

Enum

MessageSecurityMode

The type of security to apply to the messages.

The type MessageSecurityMode type is defined in 7.15.

A SecureChannel may have to be created even if the securityMode is NONE. The exact behaviour depends on the mapping used and is described in the OPC 10000-6.

    securityPolicyUri

String

The URI for SecurityPolicy to use when securing messages sent over the SecureChannel.

The set of known URIs and the SecurityPolicies associated with them are defined in OPC 10000-7.

    clientNonce

ByteString

A random number that shall not be used in any other request. A new clientNonce shall be generated for each time a SecureChannel is renewed.

This parameter shall have a length equal to the SecureChannelNonceLength defined for the SecurityPolicy in OPC 10000-7. The SecurityPolicy is identified by the securityPolicyUri.

    requestedLifetime

Duration

The requested lifetime, in milliseconds, for the new SecurityToken. It specifies when the Client expects to renew the SecureChannel by calling the OpenSecureChannel Service again. If a SecureChannel is not renewed, then all Messages sent using the current SecurityTokens shall be rejected by the receiver.

Several cryptanalytic attacks become easier as more material encrypted with a specific key is available. By limiting the amount of data processed using a particular key, those attacks are made more difficult. Therefore the volume of data exchanged between Client and Server must be limited by establishing a new SecurityToken after the lifetime.

The setting of the requested lifetime depends on the expected number of exchanged messages and their size in the lifetime. A higher volume of data requires shorter lifetime.

 

 

 

Response

 

 

    responseHeader

ResponseHeader

Common response parameters (see 7.29 for ResponseHeader type definition).

    securityToken

ChannelSecurityToken

Describes the new SecurityToken issued by the Server. This structure is defined in-line with the following indented items.

       channelId

BaseDataType

A unique identifier for the SecureChannel. This is the identifier that shall be supplied whenever the SecureChannel is renewed.

The concrete security protocol definition in OPC 10000-6 chooses the concrete DataType.

       tokenId

ByteString

A unique identifier for a single SecurityToken within the channel. This is the identifier that shall be passed with each Message secured with the SecurityToken.

       createdAt

UtcTime

The time when the SecurityToken was created.

       revisedLifetime

Duration

The lifetime of the SecurityToken in milliseconds. The UTC expiration time for the token may be calculated by adding the lifetime to the createdAt time.

    serverNonce

ByteString

A random number that shall not be used in any other request. A new serverNonce shall be generated for each time a SecureChannel is renewed.

This parameter shall have a length equal to the SecureChannelNonceLength defined for the SecurityPolicy in OPC 10000-7. The SecurityPolicy is identified by the securityPolicyUri.

 

5.5.2.3         Service results

Table 12 defines the Service results specific to this Service. Common StatusCodes are defined in Table 177.

Table 12 – OpenSecureChannel Service Result Codes

Symbolic Id

Description

Bad_SecurityChecksFailed

See Table 177 for the description of this result code.

Bad_CertificateTimeInvalid

See Table 177 for the description of this result code.

Bad_CertificateIssuerTimeInvalid

See Table 177 for the description of this result code.

Bad_CertificateHostNameInvalid

See Table 177 for the description of this result code.

Bad_CertificateUriInvalid

See Table 177 for the description of this result code.

Bad_CertificateUseNotAllowed

See Table 177 for the description of this result code.

Bad_CertificateIssuerUseNotAllowed

See Table 177 for the description of this result code.

Bad_CertificateUntrusted

See Table 177 for the description of this result code.

Bad_CertificateRevocationUnknown

See Table 177 for the description of this result code.

Bad_CertificateIssuerRevocationUnknown

See Table 177 for the description of this result code.

Bad_CertificateRevoked

See Table 177 for the description of this result code.

Bad_CertificateIssuerRevoked

See Table 177 for the description of this result code.

Bad_RequestTypeInvalid

The security token request type is not valid.

Bad_SecurityModeRejected

The security mode does not meet the requirements set by the Server.

Bad_SecurityPolicyRejected

The security policy does not meet the requirements set by the Server.

Bad_SecureChannelIdInvalid

See Table 177 for the description of this result code.

Bad_NonceInvalid

See Table 177 for the description of this result code.

A Server shall check the minimum length of the Client nonce and return this status if the length is below 32 bytes. A check for duplicated nonce can only be done in OpenSecureChannel calls with the request type RENEW_1.

 

5.5.3        CloseSecureChannel

5.5.3.1         Description

This Service is used to terminate a SecureChannel.

The request Messages shall be signed with the appropriate key associated with the current token for the SecureChannel.

5.5.3.2         Parameters

Table 13 defines the parameters for the Service.

Specific protocol mappings defined in OPC 10000-6 may choose to omit the response.

Table 13 – CloseSecureChannel Service Parameters

Name

Type

Description

Request

 

 

    requestHeader

RequestHeader

Common request parameters. The authenticationToken is always null.

The type RequestHeader is defined in 7.28.

    secureChannelId

BaseDataType

The identifier for the SecureChannel to close.

The concrete security protocol definition in OPC 10000-6 chooses the concrete DataType.

 

 

 

Response

 

 

    responseHeader

ResponseHeader

Common response parameters (see 7.29 for ResponseHeader definition).

 

5.5.3.3         Service results

Table 14 defines the Service results specific to this Service. Common StatusCodes are defined in Table 177.

Table 14 – CloseSecureChannel Service Result Codes

Symbolic Id

Description

Bad_SecureChannelIdInvalid

See Table 177 for the description of this result code.

 

5.6       Session Service Set

5.6.1        Overview

This Service Set defines Services for an application layer connection establishment in the context of a Session.

5.6.2        CreateSession

5.6.2.1         Description

This Service is used by an OPC UA Client to create a Session and the Server returns two values which uniquely identify the Session. The first value is the sessionId which is used to identify the Session in the audit logs and in the Server’s AddressSpace. The second is the authenticationToken which is used to associate an incoming request with a Session.

Before calling this Service, the Client shall create a SecureChannel with the OpenSecureChannel Service to ensure the Integrity of all Messages exchanged during a Session. This SecureChannel has a unique identifier which the Server shall associate with the authenticationToken. The Server may accept requests with the authenticationToken only if they are associated with the same SecureChannel that was used to create the Session. The Client may associate a new SecureChannel with the Session by calling the ActivateSession method.

The SecureChannel is always managed by the Communication Stack which means it shall provide APIs which the Server can use to find out information about the SecureChannel used for any given request. The Communication Stack shall, at a minimum, provide the SecurityPolicy and SecurityMode used by the SecureChannel. It shall also provide a SecureChannelId which uniquely identifies the SecureChannel or the Client Certificate used to establish the SecureChannel. The Server uses one of these to identify the SecureChannel used to send a request. Clause 7.31 describes how to create the authenticationToken for different types of Communication Stack.

Depending upon on the SecurityPolicy and the SecurityMode of the SecureChannel, the exchange of ApplicationInstanceCertificates and Nonces may be optional and the signatures may be empty. See OPC 10000-7 for the definition of SecurityPolicies and the handling of these parameters.

The Server returns its EndpointDescriptions in the response. Clients use this information to determine whether the list of EndpointDescriptions returned from the DiscoveryEndpoint matches the Endpoints that the Server has. If there is a difference then the Client shall close the Session and report an error. The Server returns all EndpointDescriptions for the serverUri specified by the Client in the request. The Client only verifies EndpointDescriptions with a transportProfileUri that matches the profileUri specified in the original GetEndpoints request. A Client may skip this check if the EndpointDescriptions were provided by a trusted source such as the Administrator.

The Session created with this Service shall not be used until the Client calls the ActivateSession Service and provides its SoftwareCertificates and proves possession of its Application Instance Certificate and any user identity token that it provided.

A Server application should limit the number of Sessions. To protect against misbehaving Clients and denial of service attacks, the Server shall close the oldest Session that is not activated before reaching the maximum number of supported Sessions.

The SoftwareCertificates parameter in the Server response is deprecated to reduce the message size for OPC UA Applications with limited resources. The SoftwareCertificates are provided in the Server’s AddressSpace as defined in OPC 10000-5. A SoftwareCertificate identifies the capabilities of the Server and also contains the list of OPC UA Profiles supported by the Server. OPC UA Profiles are defined in OPC 10000-7.

Additional Certificates issued by other organisations may be included to identify additional Server capabilities. Examples of these Profiles include support for specific information models and support for access to specific types of devices.

When a Session is created, the Server adds an entry for the Client in its SessionDiagnosticsArray Variable. See OPC 10000-5 for a description of this Variable.

Sessions are created to be independent of the underlying communications connection. Therefore, if a communications connection fails, the Session is not immediately affected. The exact mechanism to recover from an underlying communication connection error depends on the SecureChannel mapping as described in OPC 10000-6.

Sessions are terminated by the Server automatically if the Client fails to issue a Service request on the Session within the timeout period negotiated by the Server in the CreateSession Service response. This protects the Server against Client failures and against situations where a failed underlying connection cannot be re-established. Clients shall be prepared to submit requests in a timely manner to prevent the Session from closing automatically. Clients may explicitly terminate Sessions using the CloseSession Service.

When a Session is terminated, all outstanding requests on the Session are aborted and Bad_SessionClosed StatusCodes are returned to the Client. In addition, the Server deletes the entry for the Client from its SessionDiagnosticsArray Variable and notifies any other Clients who were subscribed to this entry.

If a Client invokes the CloseSession Service then all Subscriptions associated with the Session are also deleted if the deleteSubscriptions flag is set to TRUE. If a Server terminates a Session for any other reason, Subscriptions associated with the Session, are not deleted. Each Subscription has its own lifetime to protect against data loss in the case of a Session termination. In these cases, the Subscription can be reassigned to another Client before its lifetime expires.

Some Servers, such as aggregating Servers, also act as Clients to other Servers. These Servers typically support more than one system user, acting as their agent to the Servers that they represent. Security for these Servers is supported at two levels.

First, each OPC UA Service request contains a string parameter that is used to carry an audit record id. A Client, or any Server operating as a Client, such as an aggregating Server, can create a local audit log entry for a request that it submits. This parameter allows the Client to pass the identifier for this entry with the request. If the Server also maintains an audit log, then it can include this id in the audit log entry that it writes. When the log is examined and the entry is found, the examiner will be able to relate it directly to the audit log entry created by the Client. This capability allows for traceability across audit logs within a system. See OPC 10000-2 for additional information on auditing. A Server that maintains an audit log shall provide the information in the audit log entries via event Messages defined in this standard. The Server may choose to only provide the Audit information via event Messages. The Audit EventType is defined in OPC 10000-3.

Second, these aggregating Servers may open independent Sessions to the underlying Servers for each Client that accesses data from them. Figure 14 illustrates this concept.

Figure17_

Figure 14 – Multiplexing Users on a Session

5.6.2.2         Parameters

Table 15 defines the parameters for the Service.

Table 15 – CreateSession Service Parameters

Name

Type

Description

Request

 

 

    requestHeader

RequestHeader

Common request parameters. The authenticationToken is always null.

The type RequestHeader is defined in 7.28.

    clientDescription

Application Description

Information that describes the Client application.

The type ApplicationDescription is defined in 7.1.

    serverUri

String

This value is only specified if the EndpointDescription has a gatewayServerUri.

This value is the applicationUri from the EndpointDescription which is the applicationUri for the underlying Server. The type EndpointDescription is defined in 7.10.

    endpointUrl

String

The network address that the Client used to access the Session Endpoint.

The HostName portion of the URL should be one of the HostNames for the application that are specified in the Server’s ApplicationInstanceCertificate (see 7.2). The Server shall raise an AuditUrlMismatchEventType event if the URL does not match the Server’s HostNames. AuditUrlMismatchEventType event type is defined in OPC 10000-5.

The Server uses this information for diagnostics and to determine the set of EndpointDescriptions to return in the response.

    sessionName

String

Human readable string that identifies the Session. The Server makes this name and the sessionId visible in its AddressSpace for diagnostic purposes. The Client should provide a name that is unique for the instance of the Client.

If this parameter is not specified the Server shall assign a value.

    clientNonce

ByteString

A random number that should never be used in any other request. This number shall have a minimum length of 32 bytes. Profiles may increase the required length. The Server shall use this value to prove possession of its Application Instance Certificate in the response.

    clientCertificate

ApplicationInstance

Certificate

The Application Instance Certificate issued to the Client.

The ApplicationInstanceCertificate type is defined in 7.2.

If the securityPolicyUri is None, the Server shall ignore the ApplicationInstanceCertificate.

    Requested

    SessionTimeout

Duration

Requested maximum number of milliseconds that a Session should remain open without activity. If the Client fails to issue a Service request within this interval, then the Server shall automatically terminate the Client Session.

    maxResponse

    MessageSize

UInt32

The maximum size, in bytes, for the body of any response message.

The Server should return a Bad_ResponseTooLarge service fault if a response message exceeds this limit.

The value zero indicates that this parameter is not used.

The transport protocols defined in OPC 10000-6 may imply minimum message sizes.

More information on the use of this parameter is provided in 5.3.

Response

 

 

    responseHeader

ResponseHeader

Common response parameters (see 7.29 for ResponseHeader type).

    sessionId

NodeId

A unique NodeId assigned by the Server to the Session. This identifier is used to access the diagnostics information for the Session in the Server AddressSpace. It is also used in the audit logs and any events that report information related to the Session. The Session diagnostic information is described in OPC 10000-5. Audit logs and their related events are described in 6.5.

    authentication

    Token

Session

AuthenticationToken

A unique identifier assigned by the Server to the Session. This identifier shall be passed in the RequestHeader of each request and is used with the SecureChannelId to determine whether a Client has access to the Session. This identifier shall not be reused in a way that the Client or the Server has a chance of confusing them with a previous or existing Session.

The SessionAuthenticationToken type is described in 7.31.

    revisedSession    Timeout

Duration

Actual maximum number of milliseconds that a Session shall remain open without activity. The Server should attempt to honour the Client request for this parameter, but may negotiate this value up or down to meet its own constraints.

    serverNonce

ByteString

A random number that should never be used in any other request.

This number shall have a minimum length of 32 bytes.

The Client shall use this value to prove possession of its Application Instance Certificate in the ActivateSession request.

This value may also be used to prove possession of the userIdentityToken it specified in the ActivateSession request.

    serverCertificate

ApplicationInstance

Certificate

The Application Instance Certificate issued to the Server.

A Server shall prove possession by using the private key to sign the Nonce provided by the Client in the request. The Client shall verify that this Certificate is the same as the one it used to create the SecureChannel.

The ApplicationInstanceCertificate type is defined in 7.2.

If the securityPolicyUri is NONE and none of the UserTokenPolicies requires encryption, the Client shall ignore the ApplicationInstanceCertificate.

    serverEndpoints []

EndpointDescription

List of Endpoints that the Server supports.

The Server shall return a set of EndpointDescriptions available for the serverUri specified in the request. The EndpointDescription type is defined in 7.10. The Client shall verify this list with the list from a DiscoveryEndpoint if it used a DiscoveryEndpoint to fetch the EndpointDescriptions.

It is recommended that Servers only include the server.applicationUri, endpointUrl, securityMode, securityPolicyUri, userIdentityTokens, transportProfileUri and securityLevel with all other parameters set to null. Only the recommended parameters shall be verified by the client.

    serverSoftware

    Certificates []

SignedSoftware Certificate

This parameter is deprecated and the array shall be empty.

The SoftwareCertificates are provided in the Server AddressSpace as defined in OPC 10000-5.

    serverSignature

SignatureData

This is a signature generated with the private key associated with the serverCertificate. This parameter is calculated by appending the clientNonce to the clientCertificate and signing the resulting sequence of bytes.

If the clientCertificate contains a chain, the signature calculation shall be done only with the leaf Certificate. For backward compatibility a Client shall check the signature with the full chain if the check with the leaf Certificate fails.

The SignatureAlgorithm shall be the AsymmetricSignatureAlgorithm specified in the SecurityPolicy for the Endpoint.

The SignatureData type is defined in 7.32.

    maxRequest

    MessageSize

UInt32

The maximum size, in bytes, for the body of any request message.

The Client Communication Stack should return a Bad_RequestTooLarge error to the application if a request message exceeds this limit.

The value zero indicates that this parameter is not used.

See OPC 10000-6 for protocol specific minimum or default values.

5.3 provides more information on the use of this parameter.

 

5.6.2.3         Service results

Table 16 defines the Service results specific to this Service. Common StatusCodes are defined in Table 177.

Table 16 – CreateSession Service Result Codes

Symbolic Id

Description

Bad_SecureChannelIdInvalid

See Table 177 for the description of this result code.

Bad_NonceInvalid

See Table 177 for the description of this result code.

A Server shall check the minimum length of the Client nonce and return this status if the length is below 32 bytes. A check for a duplicated nonce is optional and requires access to the nonce used to create the secure channel.

Bad_SecurityChecksFailed

See Table 177 for the description of this result code.

Bad_CertificateTimeInvalid

See Table 177 for the description of this result code.

Bad_CertificateIssuerTimeInvalid

See Table 177 for the description of this result code.

Bad_CertificateHostNameInvalid

See Table 177 for the description of this result code.

Bad_CertificateUriInvalid

See Table 177 for the description of this result code.

Bad_CertificateUseNotAllowed

See Table 177 for the description of this result code.

Bad_CertificateIssuerUseNotAllowed

See Table 177 for the description of this result code.

Bad_CertificateUntrusted

See Table 177 for the description of this result code.

Bad_CertificateRevocationUnknown

See Table 177 for the description of this result code.

Bad_CertificateIssuerRevocationUnknown

See Table 177 for the description of this result code.

Bad_CertificateRevoked

See Table 177 for the description of this result code.

Bad_CertificateIssuerRevoked

See Table 177 for the description of this result code.

Bad_TooManySessions

The Server has reached its maximum number of Sessions.

Bad_ServerUriInvalid

See Table 177 for the description of this result code.

 

5.6.3        ActivateSession

5.6.3.1         Description

This Service is used by the Client to specify the identity of the user associated with the Session. This Service request shall be issued by the Client before it issues any Service request other than CloseSession after CreateSession. Failure to do so shall cause the Server to close the Session.

Whenever the Client calls this Service the Client shall prove that it is the same application that called the CreateSession Service. The Client does this by creating a signature with the private key associated with the clientCertificate specified in the CreateSession request. This signature is created by appending the last serverNonce provided by the Server to the serverCertificate and calculating the signature of the resulting sequence of bytes.

Once used, a serverNonce cannot be used again. For that reason, the Server returns a new serverNonce each time the ActivateSession Service is called.

When the ActivateSession Service is called for the first time then the Server shall reject the request if the SecureChannel is not same as the one associated with the CreateSession request. Subsequent calls to ActivateSession may be associated with different SecureChannels. If this is the case then the Server shall verify that the Certificate the Client used to create the new SecureChannel is the same as the Certificate used to create the original SecureChannel. In addition, the Server shall verify that the Client supplied a UserIdentityToken that is identical to the token currently associated with the Session. Once the Server accepts the new SecureChannel it shall reject requests sent via the old SecureChannel.

The ActivateSession Service is used to associate a user identity with a Session. When a Client provides a user identity then it shall provide proof that it is authorized to use that user identity. The exact mechanism used to provide this proof depends on the type of the UserIdentityToken. If the token is a UserNameIdentityToken then the proof is the password that is included in the token. If the token is an X509IdentityToken then the proof is a signature generated with private key associated with the Certificate. The data to sign is created by appending the last serverNonce to the serverCertificate specified in the CreateSession response. If a token includes a secret then it should be encrypted using the public key from the serverCertificate.

Servers shall take proper measures to protect against attacks on user identity tokens. Such an attack is assumed if repeated connection attempts with invalid user identity tokens happen. One option is to lock out an OPC UA Client for a period of time if the user identity token validation fails several times. The OPC UA Client is either detected by IP address for unsecured connections or by the ApplicationInstanceUri for secured connections. Another option is delaying the Service response when the validation of a user identity fails. This delay time could be increased with repeated failures. Sporadic failures shall not delay connections with valid tokens.

Clients can change the identity of a user associated with a Session by calling the ActivateSession Service. The Server validates the signatures provided with the request and then validates the new user identity. If no errors occur the Server replaces the user identity for the Session. Changing the user identity for a Session may cause discontinuities in active Subscriptions because the Server may have to tear down connections to an underlying system and re-establish them using the new credentials.

When a Client supplies a list of locale ids in the request, each locale id is required to contain the language component. It may optionally contain the <country/region> component. When the Server returns a LocalizedText in the context of the Session, it also may return both the language and the country/region or just the language as its default locale id.

When a Server returns a string to the Client, it first determines if there are available translations for it. If there are, then the Server returns the string whose locale id exactly matches the locale id with the highest priority in the Client-supplied list.

If there are no exact matches, then the Server ignores the <country/region> component of the locale id, and returns the string whose <language> component matches the <language> component of the locale id with the highest priority in the Client supplied list.

If there still are no matches, then the Server returns the string that it has along with the locale id.

A Gateway Server is expected to impersonate the user provided by the Client when it connects to the underlying Server. This means it shall re-calculate the signatures on the UserIdentityToken using the nonce provided by the underlying Server. The Gateway Server will have to use its own user credentials if the UserIdentityToken provided by the Client does not support impersonation.

5.6.3.2         Parameters

Table 17 defines the parameters for the Service.

Table 17 – ActivateSession Service Parameters

Name

Type

Description

Request

 

 

    requestHeader

RequestHeader

Common request parameters. The type RequestHeader is defined in 7.28.

    clientSignature

SignatureData

This is a signature generated with the private key associated with the clientCertificate. This parameter is calculated by appending the serverNonce to the serverCertificate and signing the resulting sequence of bytes.

If the serverCertificate contains a chain, the signature calculation shall be done only with the leaf Certificate. For backward compatibility a Server shall check the signature with the full chain if the check with the leaf Certificate fails.

The SignatureAlgorithm shall be the AsymmetricSignatureAlgorithm specified in the SecurityPolicy for the Endpoint.

The SignatureData type is defined in 7.32.

    clientSoftwareCertificates []

SignedSoftware‌Certificate

Reserved for future use.

The SignedSoftwareCertificate type is defined in 7.33.

    localeIds []

LocaleId

List of locale ids in priority order for localized strings. The first LocaleId in the list has the highest priority. If the Server returns a localized string to the Client, the Server shall return the translation with the highest priority that it can. If it does not have a translation for any of the locales identified in this list, then it shall return the string value that it has and include the locale id with the string. See OPC 10000-3 for more detail on locale ids. If the Client fails to specify at least one locale id, the Server shall use any that it has.

This parameter only needs to be specified during the first call to ActivateSession during a single application Session. If it is not specified the Server shall keep using the current localeIds for the Session.

    userIdentityToken

Extensible Parameter

UserIdentityToken

The credentials of the user associated with the Client application. The Server uses these credentials to determine whether the Client should be allowed to activate a Session and what resources the Client has access to during this Session.

The UserIdentityToken is an extensible parameter type defined in 7.36.

The EndpointDescription specifies what UserIdentityTokens the Server shall accept.

Null or empty user token shall always be interpreted as anonymous.

    userTokenSignature

SignatureData

If the Client specified a user identity token that supports digital signatures, then it shall create a signature and pass it as this parameter. Otherwise the parameter is null.

The SignatureAlgorithm depends on the identity token type.

The SignatureData type is defined in 7.32.

 

 

 

Response

 

 

    responseHeader

ResponseHeader

Common response parameters (see 7.29 for ResponseHeader definition).

    serverNonce

ByteString

A random number that should never be used in any other request.

This number shall have a minimum length of 32 bytes.

The Client shall use this value to prove possession of its Application Instance Certificate in the next call to ActivateSession request.

    results []

StatusCode

List of validation results for the SoftwareCertificates (see 7.34 for StatusCode definition).

    diagnosticInfos []

DiagnosticInfo

List of diagnostic information associated with SoftwareCertificate validation errors (see 7.8 for DiagnosticInfo definition). This list is empty if diagnostics information was not requested in the request header or if no diagnostic information was encountered in processing of the request.

 

5.6.3.3         Service results

Table 18 defines the Service results specific to this Service. Common StatusCodes are defined in Table 177.

Table 18 – ActivateSession Service Result Codes

Symbolic Id

Description

Bad_IdentityTokenInvalid

See Table 177 for the description of this result code.

Bad_IdentityTokenRejected

See Table 177 for the description of this result code.

Bad_UserAccessDenied

See Table 177 for the description of this result code.

Bad_ApplicationSignatureInvalid

The signature provided by the Client application is missing or invalid.

Bad_UserSignatureInvalid

The user token signature is missing or invalid.

Bad_NoValidCertificates

The Client did not provide at least one Software Certificate that is valid and meets the profile requirements for the Server.

Bad_IdentityChangeNotSupported

The Server does not support changing the user identity assigned to the session.

 

5.6.4        CloseSession

5.6.4.1         Description

This Service is used to terminate a Session. The Server takes the following actions when it receives a CloseSession request:

a)    It stops accepting requests for the Session. All subsequent requests received for the Session are discarded.

b)    It returns negative responses with the StatusCode Bad_SessionClosed to all requests that are currently outstanding to provide for the timely return of the CloseSession response. Clients are urged to wait for all outstanding requests to complete before submitting the CloseSession request.

c)    It removes the entry for the Client in its SessionDiagnosticsArray Variable.

When the CloseSession Service is called before the Session is successfully activated, the Server shall reject the request if the SecureChannel is not the same as the one associated with the CreateSession request.

5.6.4.2         Parameters

Table 19 defines the parameters for the Service.

Table 19 – CloseSession Service Parameters

Name

Type

Description

Request

 

 

    requestHeader

RequestHeader

Common request parameters (see 7.28 for RequestHeader definition).

    deleteSubscriptions

Boolean

If the value is TRUE, the Server deletes all Subscriptions associated with the Session. If the value is FALSE, the Server keeps the Subscriptions associated with the Session until they timeout based on their own lifetime.

 

 

 

Response

 

 

    responseHeader

ResponseHeader

Common response parameters (see 7.29 for ResponseHeader definition).

 

5.6.4.3         Service results

Table 20 defines the Service results specific to this Service. Common StatusCodes are defined in Table 177.

Table 20 – CloseSession Service Result Codes

Symbolic Id

Description

Bad_SessionIdInvalid

See Table 177 for the description of this result code.

 

5.6.5        Cancel

5.6.5.1         Description

This Service is used to cancel outstanding Service requests. Successfully cancelled service requests shall respond with Bad_RequestCancelledByClient.

5.6.5.2         Parameters

Table 21 defines the parameters for the Service.

Table 21 – Cancel Service Parameters

Name

Type

Description

Request

 

 

    requestHeader

RequestHeader

Common request parameters (see 7.28 for RequestHeader definition).

    requestHandle

IntegerId

The requestHandle assigned to one or more requests that should be cancelled. All outstanding requests with the matching requestHandle shall be cancelled.

 

 

 

Response

 

 

    responseHeader

ResponseHeader

Common response parameters (see 7.29 for ResponseHeader definition).

    cancelCount

UInt32

Number of cancelled requests.

 

5.6.5.3         Service results

Common StatusCodes are defined in Table 177.

5.7       NodeManagement Service Set

5.7.1        Overview

This Service Set defines Services to add and delete AddressSpace Nodes and References between them. All added Nodes continue to exist in the AddressSpace even if the Client that created them disconnects from the Server.

5.7.2        AddNodes

5.7.2.1         Description

This Service is used to add one or more Nodes into the AddressSpace hierarchy. Using this Service, each Node is added as the TargetNode of a HierarchicalReference to ensure that the AddressSpace is fully connected and that the Node is added as a child within the AddressSpace hierarchy (see OPC 10000-3).

When a Server creates an instance of a TypeDefinitionNode it shall create the same hierarchy of Nodes beneath the new Object or Variable depending on the ModellingRule of each InstanceDeclaration. All Nodes with a ModellingRule of Mandatory shall be created or an existing Node shall be referenced that conforms to the InstanceDeclaration. The creation of Nodes with other ModellingRules is Server specific.

5.7.2.2         Parameters

Table 22 defines the parameters for the Service.

Table 22 – AddNodes Service Parameters

Name

Type

Description

Request

 

 

    requestHeader

RequestHeader

Common request parameters (see 7.28 for RequestHeader definition).

    nodesToAdd []

AddNodesItem

List of Nodes to add. All Nodes are added as a Reference to an existing Node using a hierarchical ReferenceType. This structure is defined in-line with the following indented items.

       parentNodeId

Expanded NodeId

ExpandedNodeId of the parent Node for the Reference. The ExpandedNodeId type is defined in 7.11.

       referenceTypeId

NodeId

NodeId of the hierarchical ReferenceType to use for the Reference from the parent Node to the new Node.

       requestedNewNodeId

Expanded NodeId

Client requested expanded NodeId of the Node to add. The serverIndex in the expanded NodeId shall be 0.

If the Server cannot use this NodeId, it rejects this Node and returns the appropriate error code.

If the Client does not want to request a NodeId, then it sets the value of this parameter to the null expanded NodeId.

If the Node to add is a ReferenceType Node, its NodeId should be a numeric id. See OPC 10000-3 for a description of ReferenceType NodeIds.

       browseName

QualifiedName

The browse name of the Node to add.

       nodeClass

NodeClass

NodeClass of the Node to add.

       nodeAttributes

Extensible Parameter

NodeAttributes

The Attributes that are specific to the NodeClass. The NodeAttributes parameter type is an extensible parameter type specified in 7.19.

A Client is allowed to omit values for some or all Attributes. If an Attribute value is null, the Server shall use the default values from the TypeDefinitionNode. If a TypeDefinitionNode was not provided the Server shall choose a suitable default value.

The Server may still add an optional Attribute to the Node with an appropriate default value even if the Client does not specify a value.

       typeDefinition

Expanded NodeId

NodeId of the TypeDefinitionNode for the Node to add. This parameter shall be null for all NodeClasses other than Object and Variable in which case it shall be provided.

 

 

 

Response

 

 

    responseHeader

Response Header

Common response parameters (see 7.29 for ResponseHeader definition).

    results []

AddNodesResult

List of results for the Nodes to add. The size and order of the list matches the size and order of the nodesToAdd request parameter. This structure is defined in-line with the following indented items.

       statusCode

StatusCode

StatusCode for the Node to add (see 7.34 for StatusCode definition).

       addedNodeId

NodeId

Server assigned NodeId of the added Node. Null NodeId if the operation failed.

    diagnosticInfos []

DiagnosticInfo

List of diagnostic information for the Nodes to add (see 7.8 for DiagnosticInfo definition). The size and order of the list matches the size and order of the nodesToAdd request parameter. This list is empty if diagnostics information was not requested in the request header or if no diagnostic information was encountered in processing of the request.

 

5.7.2.3         Service results

Table 23 defines the Service results specific to this Service. Common StatusCodes are defined in Table 177.

Table 23 – AddNodes Service Result Codes

Symbolic Id

Description

Bad_NothingToDo

See Table 177 for the description of this result code.

Bad_TooManyOperations

See Table 177 for the description of this result code.

 

5.7.2.4         StatusCodes

Table 24 defines values for the operation level statusCode parameter that are specific to this Service. Common StatusCodes are defined in Table 178.

Table 24 – AddNodes Operation Level Result Codes

Symbolic Id

Description

Bad_ParentNodeIdInvalid

The parent node id does not to refer to a valid node.

Bad_ReferenceTypeIdInvalid

See Table 178 for the description of this result code.

Bad_ReferenceNotAllowed

The reference could not be created because it violates constraints imposed by the data model.

Bad_NodeIdRejected

The requested node id was rejected either because it was invalid or because the Server does not allow node ids to be specified by the client.

Bad_NodeIdExists

The requested node id is already used by another node.

Bad_NodeClassInvalid

See Table 178 for the description of this result code.

Bad_BrowseNameInvalid

See Table 178 for the description of this result code.

Bad_BrowseNameDuplicated

The browse name is not unique among nodes that share the same relationship with the parent.

Bad_NodeAttributesInvalid

The node Attributes are not valid for the node class.

Bad_TypeDefinitionInvalid

See Table 178 for the description of this result code.

Bad_UserAccessDenied

See Table 177 for the description of this result code.

 

5.7.3        AddReferences

5.7.3.1         Description

This Service is used to add one or more References to one or more Nodes. The NodeClass is an input parameter that is used to validate that the Reference to be added matches the NodeClass of the TargetNode. This parameter is not validated if the Reference refers to a TargetNode in a remote Server.

In certain cases, adding new References to the AddressSpace shall require that the Server add new Server ids to the Server’s ServerArray Variable. For this reason, remote Servers are identified by their URI and not by their ServerArray index. This allows the Server to add the remote Server URIs to its ServerArray.

5.7.3.2         Parameters

Table 25 defines the parameters for the Service.

Table 25 – AddReferences Service Parameters

Name

Type

Description

Request

 

 

    requestHeader

Request Header

Common request parameters (see 7.28 for RequestHeader definition).

    referencesToAdd []

AddReferences Item

List of Reference instances to add to the SourceNode. The targetNodeClass of each Reference in the list shall match the NodeClass of the TargetNode. This structure is defined in-line with the following indented items.

       sourceNodeId

NodeId

NodeId of the Node to which the Reference is to be added. The source Node shall always exist in the Server to add the Reference. The isForward parameter can be set to FALSE if the target Node is on the local Server and the source Node on the remote Server.

       referenceTypeId

NodeId

NodeId of the ReferenceType that defines the Reference.

       isForward

Boolean

If the value is TRUE, the Server creates a forward Reference. If the value is FALSE, the Server creates an inverse Reference.

       targetServerUri

String

URI of the remote Server. If this parameter is not null, it overrides the serverIndex in the targetNodeId.

       targetNodeId

Expanded NodeId

Expanded NodeId of the TargetNode. The ExpandedNodeId type is defined in 7.11.

       targetNodeClass

NodeClass

NodeClass of the TargetNode. The Client shall specify this since the TargetNode might not be accessible directly by the Server.

 

 

 

Response

 

 

    responseHeader

Response Header

Common response parameters (see 7.29 for ResponseHeader definition).

    results []

StatusCode

List of StatusCodes for the References to add (see 7.34 for StatusCode definition). The size and order of the list matches the size and order of the referencesToAdd request parameter.

    diagnosticInfos []

Diagnostic Info

List of diagnostic information for the References to add (see 7.8 for DiagnosticInfo definition). The size and order of the list matches the size and order of the referencesToAdd request parameter. This list is empty if diagnostics information was not requested in the request header or if no diagnostic information was encountered in processing of the request.

 

5.7.3.3         Service results

Table 26 defines the Service results specific to this Service. Common StatusCodes are defined in Table 177.

Table 26 – AddReferences Service Result Codes

Symbolic Id

Description

Bad_NothingToDo

See Table 177 for the description of this result code.

Bad_TooManyOperations

See Table 177 for the description of this result code.

 

5.7.3.4         StatusCodes

Table 27 defines values for the results parameter that are specific to this Service. Common StatusCodes are defined in Table 178.

Table 27 – AddReferences Operation Level Result Codes

Symbolic Id

Description

Bad_SourceNodeIdInvalid

See Table 178 for the description of this result code.

Bad_ReferenceTypeIdInvalid

See Table 178 for the description of this result code.

Bad_ServerUriInvalid

See Table 177 for the description of this result code.

Bad_TargetNodeIdInvalid

See Table 178 for the description of this result code.

Bad_NodeClassInvalid

See Table 178 for the description of this result code.

Bad_ReferenceNotAllowed

The reference could not be created because it violates constraints imposed by the data model on this Server.

Bad_ReferenceLocalOnly

The reference type is not valid for a reference to a remote Server.

Bad_UserAccessDenied

See Table 177 for the description of this result code.

Bad_DuplicateReferenceNotAllowed

The reference type between the nodes is already defined.

Bad_InvalidSelfReference

The Server does not allow this type of self reference on this node.

 

5.7.4        DeleteNodes

5.7.4.1         Description

This Service is used to delete one or more Nodes from the AddressSpace.

When any of the Nodes deleted by an invocation of this Service is the TargetNode of a Reference, then those References are left unresolved based on the deleteTargetReferences parameter.

When any of the Nodes deleted by an invocation of this Service is being monitored, then a Notification containing the status code Bad_NodeIdUnknown is sent to the monitoring Client indicating that the Node has been deleted.

5.7.4.2         Parameters

Table 28 defines the parameters for the Service.

Table 28 – DeleteNodes Service Parameters

Name

Type

Description

Request

 

 

    requestHeader

Request Header

Common request parameters (see 7.28 for RequestHeader definition).

    nodesToDelete []

DeleteNodes Item

List of Nodes to delete. This structure is defined in-line with the following indented items.

       nodeId

NodeId

NodeId of the Node to delete.

       deleteTargetReferences

Boolean

A Boolean parameter with the following values:

    TRUE          delete References in TargetNodes that Reference the Node to delete.

    FALSE        delete only the References for which the Node to delete is the source.

The Server cannot guarantee that it is able to delete all References from TargetNodes if this parameter is TRUE.

 

 

 

Response

 

 

    responseHeader

Response Header

Common response parameters (see 7.29 for ResponseHeader definition).

    results []

StatusCode

List of StatusCodes for the Nodes to delete (see 7.34 for StatusCode definition). The size and order of the list matches the size and order of the list of the nodesToDelete request parameter.

    diagnosticInfos []

Diagnostic Info

List of diagnostic information for the Nodes to delete (see 7.8 for DiagnosticInfo definition). The size and order of the list matches the size and order of the nodesToDelete request parameter. This list is empty if diagnostics information was not requested in the request header or if no diagnostic information was encountered in processing of the request.

 

5.7.4.3         Service results

Table 29 defines the Service results specific to this Service. Common StatusCodes are defined in Table 177.

Table 29 – DeleteNodes Service Result Codes

Symbolic Id

Description

Bad_NothingToDo

See Table 177 for the description of this result code.

Bad_TooManyOperations

See Table 177 for the description of this result code.

 

5.7.4.4         StatusCodes

Table 30 defines values for the results parameter that are specific to this Service. Common StatusCodes are defined in Table 178.

Table 30 – DeleteNodes Operation Level Result Codes

Symbolic Id

Description

Bad_NodeIdInvalid

See Table 178 for the description of this result code.

Bad_NodeIdUnknown

See Table 178 for the description of this result code.

Bad_UserAccessDenied

See Table 177 for the description of this result code.

Bad_NoDeleteRights

See Table 178 for the description of this result code.

Uncertain_ReferenceNotDeleted

The Server was not able to delete all target references.

 

5.7.5        DeleteReferences

5.7.5.1         Description

This Service is used to delete one or more References of a Node.

When any of the References deleted by an invocation of this Service are contained in a View, then the ViewVersion Property is updated if this Property is supported.

Table 31 defines the parameters for the Service.

Table 31 – DeleteReferences Service Parameters

Name

Type

Description

Request

 

 

    requestHeader

RequestHeader

Common request parameters (see 7.28 for RequestHeader definition).

    referencesToDelete []

DeleteReferences Item

List of References to delete. This structure is defined in-line with the following indented items.

       sourceNodeId

NodeId

NodeId of the Node that contains the Reference to delete.

       referenceTypeId

NodeId

NodeId of the ReferenceType that defines the Reference to delete.

       isForward

Boolean

If the value is TRUE, the Server deletes a forward Reference. If the value is FALSE, the Server deletes an inverse Reference.

       targetNodeId

ExpandedNodeId

NodeId of the TargetNode of the Reference.

If the Server index indicates that the TargetNode is a remote Node, then the nodeId shall contain the absolute namespace URI. If the TargetNode is a local Node the nodeId shall contain the namespace index.

       deleteBidirectional

Boolean

A Boolean parameter with the following values:

    TRUE          delete the specified Reference and the opposite Reference from the TargetNode. If the TargetNode is located in a remote Server, the Server is permitted to delete the specified Reference only.

    FALSE        delete only the specified Reference.

 

 

 

Response

 

 

    responseHeader

ResponseHeader

Common response parameters (see 7.29 for ResponseHeader definition).

    results []

StatusCode

List of StatusCodes for the References to delete (see 7.34 for StatusCode definition). The size and order of the list matches the size and order of the referencesToDelete request parameter.

    diagnosticInfos []

DiagnosticInfo

List of diagnostic information for the References to delete (see 7.8 for DiagnosticInfo definition). The size and order of the list matches the size and order of the referencesToDelete request parameter. This list is empty if diagnostics information was not requested in the request header or if no diagnostic information was encountered in processing of the request.

 

5.7.5.2         Service results

Table 32 defines the Service results specific to this Service. Common StatusCodes are defined in Table 177.

Table 32 – DeleteReferences Service Result Codes

Symbolic Id

Description

Bad_NothingToDo

See Table 177 for the description of this result code.

Bad_TooManyOperations

See Table 177 for the description of this result code.

 

5.7.5.3         StatusCodes

Table 33 defines values for the results parameter that are specific to this Service. Common StatusCodes are defined in Table 178.

Table 33 – DeleteReferences Operation Level Result Codes

Symbolic Id

Description

Bad_SourceNodeIdInvalid

See Table 178 for the description of this result code.

Bad_ReferenceTypeIdInvalid

See Table 178 for the description of this result code.

Bad_ServerIndexInvalid

The Server index is not valid.

Bad_TargetNodeIdInvalid

See Table 178 for the description of this result code.

Bad_UserAccessDenied

See Table 177 for the description of this result code.

Bad_NoDeleteRights

See Table 178 for the description of this result code.

 

5.8       View Service Set

5.8.1        Overview

Clients use the browse Services of the View Service Set to navigate through the AddressSpace or through a View which is a subset of the AddressSpace.

A View is a subset of the AddressSpace created by the Server. Future versions of this standard may also define services to create Client-defined Views. See OPC 10000-5 for a description of the organisation of views in the AddressSpace.

5.8.2        Browse

5.8.2.1         Description

This Service is used to discover the References of a specified Node. The browse can be further limited by the use of a View. This Browse Service also supports a primitive filtering capability.

In some cases it may take longer than the Client timeout hint to process all nodes to browse. In this case the Server may return zero results with a continuation point for the affected nodes before the timeout expires.

5.8.2.2         Parameters

Table 34 defines the parameters for the Service.

Table 34 – Browse Service Parameters

Name

Type

Description

Request

 

 

    requestHeader

RequestHeader

Common request parameters (see 7.28 for RequestHeader definition).

    View

ViewDescription

Description of the View to browse (see 7.39 for ViewDescription definition). An empty ViewDescription value indicates the entire AddressSpace. Use of the empty ViewDescription value causes all References of the nodesToBrowse to be returned. Use of any other View causes only the References of the nodesToBrowse that are defined for that View to be returned.

    requestedMax

    ReferencesPerNode

Counter

Indicates the maximum number of references to return for each starting Node specified in the request. The value 0 indicates that the Client is imposing no limitation (see 7.5 for Counter definition).

    nodesToBrowse []

BrowseDescription

A list of nodes to Browse. This structure is defined in-line with the following indented items.

       nodeId

NodeId

NodeId of the Node to be browsed. If a view is provided, it shall include this Node.

       browseDirection

Enum

BrowseDirection

An enumeration that specifies the direction of References to follow. It has the following values:

    FORWARD_0      select only forward References.

    INVERSE_1         select only inverse References.

    BOTH_2              select forward and inverse References.

    INVALID_3           no value specified.

The returned References do indicate the direction the Server followed in the isForward parameter of the ReferenceDescription.

Symmetric References are always considered to be in forward direction therefore the isForward flag is always set to TRUE and symmetric References are not returned if browseDirection is set to INVERSE_1.

       referenceTypeId

NodeId

Specifies the NodeId of the ReferenceType to follow. Only instances of this ReferenceType or its subtypes are returned.

If not specified then all References are returned and includeSubtypes is ignored.

       includeSubtypes

Boolean

Indicates whether subtypes of the ReferenceType should be included in the browse. If TRUE, then instances of referenceTypeId and all of its subtypes are returned.

       nodeClassMask

UInt32

Specifies the NodeClasses of the TargetNodes. Only TargetNodes with the selected NodeClasses are returned. The NodeClasses are assigned the following bits:

Bit

NodeClass

0

Object

1

Variable

2

Method

3

ObjectType

4

VariableType

5

ReferenceType

6

DataType

7

View

If set to zero, then all NodeClasses are returned.

If the NodeClass is unknown for a remote Node, the nodeClassMask is ignored.

       resultMask

UInt32

Specifies the fields in the ReferenceDescription structure that should be returned. The fields are assigned the following bits:

Bit

Result

0

ReferenceType

1

IsForward

2

NodeClass

3

BrowseName

4

DisplayName

5

TypeDefinition

The ReferenceDescription type is defined in 7.25.

 

 

 

Response

 

 

    responseHeader

Response Header

Common response parameters (see 7.29 for ResponseHeader definition).

    results []

BrowseResult

A list of BrowseResults. The size and order of the list matches the size and order of the nodesToBrowse specified in the request.

The BrowseResult type is defined in 7.3.

    diagnosticInfos []

Diagnostic Info

List of diagnostic information for the results (see 7.8 for DiagnosticInfo definition). The size and order of the list matches the size and order of the results response parameter. This list is empty if diagnostics information was not requested in the request header or if no diagnostic information was encountered in processing of the request.

 

5.8.2.3         Service results

Table 35 defines the Service results specific to this Service. Common StatusCodes are defined in Table 177.

Table 35 – Browse Service Result Codes

Symbolic Id

Description

Bad_ViewIdUnknown

See Table 177 for the description of this result code.

Bad_ViewTimestampInvalid

See Table 177 for the description of this result code.

Bad_ViewParameterMismatchInvalid

See Table 177 for the description of this result code.

Bad_ViewVersionInvalid

See Table 177 for the description of this result code.

Bad_NothingToDo

See Table 177 for the description of this result code.

Bad_TooManyOperations

See Table 177 for the description of this result code.

 

5.8.2.4         StatusCodes

Table 36 defines values for the results parameter that are specific to this Service. Common StatusCodes are defined in Table 178.

Table 36 – Browse Operation Level Result Codes

Symbolic Id

Description

Bad_NodeIdInvalid

See Table 178 for the description of this result code.

Bad_NodeIdUnknown

See Table 178 for the description of this result code.

Bad_ReferenceTypeIdInvalid

See Table 178 for the description of this result code.

Bad_BrowseDirectionInvalid

See Table 178 for the description of this result code.

Bad_NodeNotInView

See Table 178 for the description of this result code.

Bad_NoContinuationPoints

See Table 178 for the description of this result code.

Uncertain_NotAllNodesAvailable

Browse results may be incomplete because of the unavailability of a subsystem.

 

5.8.3        BrowseNext

5.8.3.1         Description

This Service is used to request the next set of Browse or BrowseNext response information that is too large to be sent in a single response. “Too large” in this context means that the Server is not able to return a larger response or that the number of results to return exceeds the maximum number of results to return that was specified by the Client in the original Browse request. The BrowseNext shall be submitted on the same Session that was used to submit the Browse or BrowseNext that is being continued.

5.8.3.2         Parameters

Table 37 defines the parameters for the Service.

Table 37 – BrowseNext Service Parameters

Name

Type

Description

Request

 

 

    requestHeader

Request Header

Common request parameters (see 7.28 for RequestHeader definition).

    releaseContinuationPoints

Boolean

A Boolean parameter with the following values:

    TRUE          passed continuationPoints shall be reset to free resources in the Server. The continuation points are released and the results and diagnosticInfos arrays are empty.

    FALSE        passed continuationPoints shall be used to get the next set of browse information.

A Client shall always use the continuation point returned by a Browse or BrowseNext response to free the resources for the continuation point in the Server. If the Client does not want to get the next set of browse information, BrowseNext shall be called with this parameter set to TRUE.

    continuationPoints []

Continuation Point

A list of Server-defined opaque values that represent continuation points. The value for a continuation point was returned to the Client in a previous Browse or BrowseNext response. These values are used to identify the previously processed Browse or BrowseNext request that is being continued and the point in the result set from which the browse response is to continue.

Clients may mix continuation points from different Browse or BrowseNext responses.

The ContinuationPoint type is described in 7.6.

 

 

 

Response

 

 

    responseHeader

Response Header

Common response parameters (see 7.29 for ResponseHeader definition).

    results []

BrowseResult

A list of references that met the criteria specified in the original Browse request.

The size and order of this list matches the size and order of the continuationPoints request parameter.

The BrowseResult type is defined in 7.3.

    diagnosticInfos []

Diagnostic Info

List of diagnostic information for the results (see 7.8 for DiagnosticInfo definition). The size and order of the list matches the size and order of the results response parameter. This list is empty if diagnostics information was not requested in the request header or if no diagnostic information was encountered in processing of the request.

 

5.8.3.3         Service results

Table 38 defines the Service results specific to this Service. Common StatusCodes are defined in Table 177.

Table 38 – BrowseNext Service Result Codes

Symbolic Id

Description

Bad_NothingToDo

See Table 177 for the description of this result code.

Bad_TooManyOperations

See Table 177 for the description of this result code.

 

5.8.3.4         StatusCodes

Table 39 defines values for the results parameter that are specific to this Service. Common StatusCodes are defined in Table 178.

Table 39 – BrowseNext Operation Level Result Codes

Symbolic Id

Description

Bad_NodeIdInvalid

See Table 178 for the description of this result code.

Bad_NodeIdUnknown

See Table 178 for the description of this result code.

Bad_ReferenceTypeIdInvalid

See Table 178 for the description of this result code.

Bad_BrowseDirectionInvalid

See Table 178 for the description of this result code.

Bad_NodeNotInView

See Table 178 for the description of this result code.

Bad_ContinuationPointInvalid

See Table 178 for the description of this result code.

 

5.8.4        TranslateBrowsePathsToNodeIds

5.8.4.1         Description

This Service is used to request that the Server translates one or more browse paths to NodeIds. Each browse path is constructed of a starting Node and a RelativePath. The specified starting Node identifies the Node from which the RelativePath is based. The RelativePath contains a sequence of ReferenceTypes and BrowseNames.

One purpose of this Service is to allow programming against type definitions. Since BrowseNames shall be unique in the context of type definitions, a Client may create a browse path that is valid for a type definition and use this path on instances of the type. For example, an ObjectType “Boiler” may have a “HeatSensor” Variable as InstanceDeclaration. A graphical element programmed against the “Boiler” may need to display the Value of the “HeatSensor”. If the graphical element would be called on “Boiler1”, an instance of “Boiler”, it would need to call this Service specifying the NodeId of “Boiler1” as starting Node and the BrowseName of the “HeatSensor” as browse path. The Service would return the NodeId of the “HeatSensor” of “Boiler1” and the graphical element could subscribe to its Value Attribute.

If a Node has multiple targets with the same BrowseName, the Server shall return a list of NodeIds. However, since one of the main purposes of this Service is to support programming against type definitions, the NodeId of the Node based on the type definition of the starting Node is returned as the first NodeId in the list.

5.8.4.2         Parameters

Table 40 defines the parameters for the Service.

Table 40 – TranslateBrowsePathsToNodeIds Service Parameters

Name

Type

Description

Request

 

 

    requestHeader

RequestHeader

Common request parameters (see 7.28 for RequestHeader definition).

    browsePaths []

BrowsePath

List of browse paths for which NodeIds are being requested. This structure is defined in-line with the following indented items.

       startingNode

NodeId

NodeId of the starting Node for the browse path.

       relativePath

RelativePath

The path to follow from the startingNode.

The last element in the relativePath shall always have a targetName specified. This further restricts the definition of the RelativePath type. The Server shall return Bad_BrowseNameInvalid if the targetName is missing.

The RelativePath structure is defined in 7.26.

 

 

 

Response

 

 

    responseHeader

ResponseHeader

Common response parameters (see 7.29 for ResponseHeader definition).

    results []

BrowsePathResult

List of results for the list of browse paths. The size and order of the list matches the size and order of the browsePaths request parameter. This structure is defined in-line with the following indented items.

       statusCode

StatusCode

StatusCode for the browse path (see 7.34 for StatusCode definition).

       targets []

BrowsePathTarget

 

List of targets for the relativePath from the startingNode. This structure is defined in-line with the following indented items.

A Server may encounter a Reference to a Node in another Server which it cannot follow while it is processing the RelativePath. If this happens the Server returns the NodeId of the external Node and sets the remainingPathIndex parameter to indicate which RelativePath elements still need to be processed. To complete the operation the Client shall connect to the other Server and call this service again using the target as the startingNode and the unprocessed elements as the relativePath.

           targetId

ExpandedNodeId

The identifier for a target of the RelativePath.

           remainingPathIndex

Index

The index of the first unprocessed element in the RelativePath.

This value shall be equal to the maximum value of Index data type if all elements were processed (see 7.13 for Index definition).

    diagnosticInfos []

DiagnosticInfo

List of diagnostic information for the list of browse paths (see 7.8 for DiagnosticInfo definition). The size and order of the list matches the size and order of the browsePaths request parameter. This list is empty if diagnostics information was not requested in the request header or if no diagnostic information was encountered in processing of the request.

 

5.8.4.3         Service results

Table 41 defines the Service results specific to this Service. Common StatusCodes are defined in 7.34.

Table 41 – TranslateBrowsePathsToNodeIds Service Result Codes

Symbolic Id

Description

Bad_NothingToDo

See Table 177 for the description of this result code.

Bad_TooManyOperations

See Table 177 for the description of this result code.

 

5.8.4.4         StatusCodes

Table 42 defines values for the operation level statusCode parameters that are specific to this Service. Common StatusCodes are defined in Table 178.

Table 42 – TranslateBrowsePathsToNodeIds Operation Level Result Codes

Symbolic Id

Description

Bad_NodeIdInvalid

See Table 178 for the description of this result code.

Bad_NodeIdUnknown

See Table 178 for the description of this result code.

Bad_NothingToDo

See Table 177 for the description of this result code.

This code indicates that the relativePath contained an empty list.

Bad_BrowseNameInvalid

See Table 178 for the description of this result code.

This code indicates that a TargetName was missing in a RelativePath.

Uncertain_ReferenceOutOfServer

The path element has targets which are in another server.

Bad_TooManyMatches

The requested operation has too many matches to return.

Users should use queries for large result sets. Servers should allow at least 10 matches before returning this error code.

Bad_QueryTooComplex

The requested operation requires too many resources in the server.

Bad_NoMatch

The requested relativePath cannot be resolved to a target to return.

 

5.8.5        RegisterNodes

5.8.5.1         Description

A Server often has no direct access to the information that it manages. Variables or services might be in underlying systems where additional effort is required to establish a connection to these systems. The RegisterNodes Service can be used by Clients to register the Nodes that they know they will access repeatedly (e.g. Write, Call). It allows Servers to set up anything needed so that the access operations will be more efficient. Clients can expect performance improvements when using registered NodeIds, but the optimization measures are vendor-specific. For Variable Nodes Servers shall concentrate their optimization efforts on the Value Attribute.

Registered NodeIds are only guaranteed to be valid within the current Session. Clients shall unregister unneeded Ids immediately to free up resources.

RegisterNodes does not validate the NodeIds from the request. Servers will simply copy unknown NodeIds in the response. Structural NodeId errors (size violations, invalid id types) will cause the complete Service to fail.

For the purpose of Auditing, Servers shall not use the registered NodeIds but only the canonical NodeIds which is the value of the NodeId Attribute.

5.8.5.2         Parameters

Table 43 defines the parameters for the Service.

Table 43 – RegisterNodes Service Parameters

Name

Type

Description

Request

 

 

    requestHeader

Request Header

Common request parameters (see 7.28 for RequestHeader definition).

    nodesToRegister []

NodeId

List of NodeIds to register that the Client has retrieved through browsing, querying or in some other manner.

 

 

 

Response

 

 

    responseHeader

Response Header

Common response parameters (see 7.29 for ResponseHeader definition).

    registeredNodeIds []

NodeId

A list of NodeIds which the Client shall use for subsequent access operations. The size and order of this list matches the size and order of the nodesToRegister request parameter.

The Server may return the NodeId from the request or a new (an alias) NodeId. It is recommended that the Server return a numeric NodeIds for aliasing.

In case no optimization is supported for a Node, the Server shall return the NodeId from the request.

 

5.8.5.3         Service results

Table 44 defines the Service results specific to this Service. Common StatusCodes are defined in Table 177.

Table 44 – RegisterNodes Service Result Codes

Symbolic Id

Description

Bad_NothingToDo

See Table 177 for the description of this result code.

Bad_TooManyOperations

See Table 177 for the description of this result code.

Bad_NodeIdInvalid

See Table 178 for the description of this result code.

Servers shall completely reject the RegisterNodes request if any of the NodeIds in the nodesToRegister parameter are structurally invalid.

 

5.8.6        UnregisterNodes

5.8.6.1         Description

This Service is used to unregister NodeIds that have been obtained via the RegisterNodes service.

UnregisterNodes does not validate the NodeIds from the request. Servers shall simply unregister NodeIds that are known as registered NodeIds. Any NodeIds that are in the list, but are not registered NodeIds are simply ignored.

5.8.6.2         Parameters

Table 50 defines the parameters for the Service.

Table 45 – UnregisterNodes Service Parameters

Name

Type

Description

Request

 

 

    requestHeader

Request Header

Common request parameters (see 7.28 for RequestHeader definition).

    nodesToUnregister []

NodeId

A list of NodeIds that have been obtained via the RegisterNodes service.

 

 

 

Response

 

 

    responseHeader

Response Header

Common response parameters (see 7.29 for ResponseHeader definition).

 

5.8.6.3         Service results

Table 51 defines the Service results specific to this Service. Common StatusCodes are defined in Table 177.

Table 46 – UnregisterNodes Service Result Codes

Symbolic Id

Description

Bad_NothingToDo

See Table 177 for the description of this result code.

Bad_TooManyOperations

See Table 177 for the description of this result code.

 

5.9       Query Service Set

5.9.1        Overview

This Service Set is used to issue a Query to a Server. OPC UA Query is generic in that it provides an underlying storage mechanism independent Query capability that can be used to access a wide variety of OPC UA data stores and information management systems. OPC UA Query permits a Client to access data maintained by a Server without any knowledge of the logical schema used for internal storage of the data. Knowledge of the AddressSpace is sufficient.

An OPC UA Application is expected to use the OPC UA Query Services as part of an initialization process or an occasional information synchronization step. For example, OPC UA Query would be used for bulk data access of a persistent store to initialise an analysis application with the current state of a system configuration. A Query may also be used to initialise or populate data for a report.

A Query defines what instances of one or more TypeDefinitionNodes in the AddressSpace should supply a set of Attributes. Results returned by a Server are in the form of an array of QueryDataSets. The selected Attribute values in each QueryDataSet come from the definition of the selected TypeDefinitionNodes or related TypeDefinitionNodes and appear in results in the same order as the Attributes that were passed into the Query. Query also supports Node filtering on the basis of Attribute values, as well as relationships between TypeDefinitionNodes.

See Annex B for example queries.

5.9.2        Querying Views

A View is a subset of the AddressSpace available in the Server. See OPC 10000-5 for a description of the organisation of Views in the AddressSpace.

For any existing View, a Query may be used to return a subset of data from the View. When an application issues a Query against a View, only data defined by the View is returned. Data not included in the View but included in the original AddressSpace is not returned.

The Query Services supports access to current and historical data. The Service supports a Client querying a past version of the AddressSpace. Clients may specify a ViewVersion or a Timestamp in a Query to access past versions of the AddressSpace. OPC UA Query is complementary to Historical Access in that the former is used to Query an AddressSpace that existed at a time and the latter is used to Query for the value of Attributes over time. In this way, a Query can be used to retrieve a portion of a past AddressSpace so that Attribute value history may be accessed using Historical Access even if the Node is no longer in the current AddressSpace.

Servers that support Query are expected to be able to access the AddressSpace that is associated with the local Server and any Views that are available on the local Server. If a View or the AddressSpace also references a remote Server, query may be able to access the AddressSpace of the remote Server, but it is not required. If a Server does access a remote Server the access shall be accomplished using the user identity of the Client as described in 5.5.1.

5.9.3        QueryFirst

5.9.3.1         Description

This Service is used to issue a Query request to the Server. The complexity of the Query can range from very simple to highly sophisticated. The Query can simply request data from instances of a TypeDefinitionNode or TypeDefinitionNode subject to restrictions specified by the filter. On the other hand, the Query can request data from instances of related Node types by specifying a RelativePath from an originating TypeDefinitionNode. In the filter, a separate set of paths can be constructed for limiting the instances that supply data. A filtering path can include multiple RelatedTo operators to define a multi-hop path between source instances and target instances. For example, one could filter on students that attend a particular school, but return information about students and their families. In this case, the student school relationship is traversed for filtering, but the student family relationship is traversed to select data. For a complete description of ContentFilter see 7.4, also see Clause B.1 for simple examples and Clause B.2 for more complex examples of content filter and queries.

The Client provides an array of NodeTypeDescription which specify the NodeId of a TypeDefinitionNode and selects what Attributes are to be returned in the response. A Client can also provide a set of RelativePaths through the type system starting from an originating TypeDefinitionNode. Using these paths, the Client selects a set of Attributes from Nodes that are related to instances of the originating TypeDefinitionNode. Additionally, the Client can request the Server return instances of subtypes of TypeDefinitionNodes. If a selected Attribute does not exist in a TypeDefinitionNode but does exist in a subtype, it is assumed to have a null value in the TypeDefinitionNode in question. Therefore, this does not constitute an error condition and a null value is returned for the Attribute.

The Client can use the filter parameter to limit the result set by restricting Attributes and Properties to certain values. Another way the Client can use a filter to limit the result set is by specifying how instances should be related, using RelatedTo operators. In this case, if an instance at the top of the RelatedTo path cannot be followed to the bottom of the path via specified hops, no QueryDataSets are returned for the starting instance or any of the intermediate instances.

When querying for related instances in the RelativePath, the Client can optionally ask for References. A Reference is requested via a RelativePath that only includes a ReferenceType. If all References are desired than the root ReferenceType is listed. These References are returned as part of the QueryDataSets.

Query Services allow a special handling of the targetName field in the RelativePath. In several Query use cases a type NodeId is necessary in the path instead of a QualifiedName. Therefore the Client is allowed to specify a NodeId in the QualifiedName. This is done by setting the namespaceIndex of the targetName to zero and the name part of the targetName to the XML representation of the NodeId. The XML representation is defined in OPC 10000-6. When matching instances are returned as the target node, the target node shall be an instance of the specified type or subtype of the specified type.

Table 47 defines the request parameters and Table 48 the response parameters for the QueryFirst Service.

Table 47 – QueryFirst Request Parameters

Name

Type

Description

Request

 

 

    requestHeader

RequestHeader

Common request parameters (see 7.28 for RequestHeader definition).

    View

ViewDescription

Specifies a View and temporal context to a Server (see 7.39 for ViewDescription definition).

    nodeTypes []

NodeTypeDescription

This is the Node type description. This structure is defined in-line with the following indented items.

       typeDefinitionNode

ExpandedNodeId

NodeId of the originating TypeDefinitionNode of the instances for which data is to be returned.

       includeSubTypes

Boolean

A flag that indicates whether the Server should include instances of subtypes of the TypeDefinitionNode in the list of instances of the Node type.

       dataToReturn []

QueryDataDescription

Specifies an Attribute or Reference from the originating typeDefinitionNode along a given relativePath for which to return data. This structure is defined in-line with the following indented items.

           relativePath

RelativePath

Browse path relative to the originating Node that identifies the Node which contains the data that is being requested, where the originating Node is an instance Node of the type defined by the type definition Node. The instance Nodes are further limited by the filter provided as part of this call. For a definition of relativePath see 7.26.

This relative path could end on a Reference, in which case the ReferenceDescription of the Reference would be returned as its value.

The targetName field of the relativePath may contain a type NodeId. This is done by setting the namespaceIndex of the targetName to zero and the name part of the targetName to the XML representation of the NodeId. The XML representation is defined in OPC 10000-6.

When matching instances are returned as the target node, the target node shall be an instance of the specified type or subtype of the specified type.

           attributeId

IntegerId

Id of the Attribute. This shall be a valid Attribute Id. The IntegerId is defined in 7.14. The IntegerId for Attributes are defined in OPC 10000-6. If the RelativePath ended in a Reference then this parameter is 0 and ignored by the server.

           indexRange

NumericRange

This parameter is used to identify a single element of a structure or an array, or a single range of indexes for arrays. If a range of elements are specified, the values are returned as a composite. The first element is identified by index 0 (zero). The NumericRange type is defined in 7.22.

This parameter is null if the specified Attribute is not an array or a structure. However, if the specified Attribute is an array or a structure, and this parameter is null, then all elements are to be included in the range.

    Filter

ContentFilter

Resulting Nodes shall be limited to the Nodes matching the criteria defined by the filter. ContentFilter is discussed in 7.4. If an empty filter is provided then the entire AddressSpace shall be examined and all Nodes that contain a matching requested Attribute or Reference are returned.

    maxDataSetsToReturn

Counter

The number of QueryDataSets that the Client wants the Server to return in the response and on each subsequent continuation call response. The Server is allowed to further limit the response, but shall not exceed this limit.

A value of 0 indicates that the Client is imposing no limitation.

    maxReferencesToReturn

Counter

The number of References that the Client wants the Server to return in the response for each QueryDataSet and on each subsequent continuation call response. The Server is allowed to further limit the response, but shall not exceed this limit.

A value of 0 indicates that the Client is imposing no limitation.

For example a result where 4 Nodes are being returned, but each has 100 References, if this limit were set to 50 then only the first 50 References for each Node would be returned on the initial call and a continuation point would be set indicating additional data.

 

Table 48 – QueryFirst Response Parameters

Name

Type

Description

Response

 

 

    responseHeader

ResponseHeader

Common response parameters (see 7.29 for ResponseHeader definition).

    queryDataSets []

QueryDataSet

The array of QueryDataSets. This array is empty if no Nodes or References met the nodeTypes criteria. In this case the continuationPoint parameter shall be empty.

The QueryDataSet type is defined in 7.23.

    continuationPoint

ContinuationPoint

Server-defined opaque value that identifies the continuation point.

The continuation point is used only when the Query results are too large to be returned in a single response. “Too large” in this context means that the Server is not able to return a larger response or that the number of QueryDataSets to return exceeds the maximum number of QueryDataSets to return that was specified by the Client in the request.

The continuation point is used in the QueryNext Service. When not used, the value of this parameter is null. If a continuation point is returned, the Client shall call QueryNext to get the next set of QueryDataSets or to free the resources for the continuation point in the Server.

A continuation point shall remain active until the Client passes the continuation point to QueryNext or the session is closed. If the maximum continuation points have been reached the oldest continuation point shall be reset.

The ContinuationPoint type is described in 7.6.

    parsingResults[]

ParsingResult

List of parsing results for QueryFirst. The size and order of the list matches the size and order of the NodeTypes request parameter. This structure is defined in-line with the following indented items.

This list is populated with any status codes that are related to the processing of the node types that are part of the query. The array can be empty if no errors where encountered. If any node type encountered an error all node types shall have an associated status code.

       statusCode

StatusCode

Parsing result for the requested NodeTypeDescription.

       dataStatusCodes []

StatusCode

List of results for dataToReturn. The size and order of the list matches the size and order of the dataToReturn request parameter. The array can be empty if no errors where encountered.

       dataDiagnosticInfos []

DiagnosticInfo

List of diagnostic information dataToReturn (see 7.8 for DiagnosticInfo definition). The size and order of the list matches the size and order of the dataToReturn request parameter. This list is empty if diagnostics information was not requested in the request header or if no diagnostic information was encountered in processing of the query request.

    diagnosticInfos []

DiagnosticInfo

List of diagnostic information for the requested NodeTypeDescription. This list is empty if diagnostics information was not requested in the request header or if no diagnostic information was encountered in processing of the query request.

    filterResult

ContentFilter

Result

A structure that contains any errors associated with the filter.

This structure shall be empty if no errors occurred.

The ContentFilterResult type is defined in 7.4.2.

 

5.9.3.2         Service results

If the Query is invalid or cannot be processed, then QueryDataSets are not returned and only a Service result, filterResult, parsingResults and optional DiagnosticInfo is returned. Table 49 defines the Service results specific to this Service. Common StatusCodes are defined in Table 177.

Table 49 – QueryFirst Service Result Codes

Symbolic Id

Description

Bad_NothingToDo

See Table 177 for the description of this result code.

Bad_TooManyOperations

See Table 177 for the description of this result code.

Bad_ContentFilterInvalid

See Table 178 for the description of this result code.

Bad_ViewIdUnknown

See Table 177 for the description of this result code.

Bad_ViewTimestampInvalid

See Table 177 for the description of this result code.

Bad_ViewParameterMismatchInvalid

See Table 177 for the description of this result code.

Bad_ViewVersionInvalid

See Table 177 for the description of this result code.

Bad_InvalidFilter

The provided filter is invalid, see the filterResult for specific errors

Bad_NodelistError

The NodeTypes provided contain an error, see the parsingResults for specific errors

Bad_InvalidView

The provided ViewDescription is not a valid ViewDescription.

Good_ResultsMayBeIncomplete

The Server should have followed a reference to a node in a remote Server but did not. The result set may be incomplete.

 

5.9.3.3         StatusCodes

Table 50 defines values for the parsingResults statusCode parameter that are specific to this Service. Common StatusCodes are defined in Table 178.

Table 50 – QueryFirst Operation Level Result Codes

Symbolic Id

Description

Bad_NodeIdInvalid

See Table 178 for the description of this result code.

Bad_NodeIdUnknown

See Table 178 for the description of this result code.

Bad_NotTypeDefinition

The provided NodeId was not a type definition NodeId.

Bad_AttributeIdInvalid

See Table 178 for the description of this result code.

Bad_IndexRangeInvalid

See Table 178 for the description of this result code.

 

5.9.4        QueryNext

5.9.4.1         Descriptions

This Service is used to request the next set of QueryFirst or QueryNext response information that is too large to be sent in a single response. “Too large” in this context means that the Server is not able to return a larger response or that the number of QueryDataSets to return exceeds the maximum number of QueryDataSets to return that was specified by the Client in the original request. The QueryNext shall be submitted on the same session that was used to submit the QueryFirst or QueryNext that is being continued.

5.9.4.2         Parameters

Table 51 defines the parameters for the Service.

Table 51 – QueryNext Service Parameters

Name

Type

Description

Request

 

 

    requestHeader

Request Header

Common request parameters (see 7.28 for RequestHeader definition).

    releaseContinuationPoint

Boolean

A Boolean parameter with the following values:

    TRUE          passed continuationPoint shall be reset to free resources for the continuation point in the Server.

    FALSE        passed continuationPoint shall be used to get the next set of QueryDataSets.

A Client shall always use the continuation point returned by a QueryFirst or QueryNext response to free the resources for the continuation point in the Server. If the Client does not want to get the next set of Query information, QueryNext shall be called with this parameter set to TRUE.

If the parameter is set to TRUE all array parameters in the response shall contain empty arrays.

    continuationPoint

ContinuationPoint

Server defined opaque value that represents the continuation point. The value of the continuation point was returned to the Client in a previous QueryFirst or QueryNext response. This value is used to identify the previously processed QueryFirst or QueryNext request that is being continued, and the point in the result set from which the browse response is to continue.

The ContinuationPoint type is described in 7.6.

 

 

 

Response

 

 

    responseHeader

Response Header

Common response parameters (see 7.29 for ResponseHeader definition).

    queryDataSets []

QueryDataSet

The array of QueryDataSets.

The QueryDataSet type is defined in 7.23.

    revisedContinuationPoint

ContinuationPoint

Server-defined opaque value that represents the continuation point. It is used only if the information to be returned is too large to be contained in a single response. When not used or when releaseContinuationPoint is set, the value of this parameter is null.

The ContinuationPoint type is described in 7.6.

 

5.9.4.3         Service results

Table 52 defines the Service results specific to this Service. Common StatusCodes are defined in Table 177.

Table 52 – QueryNext Service Result Codes

Symbolic Id

Description

Bad_ContinuationPointInvalid

See Table 178 for the description of this result code.

 

5.10     Attribute Service Set

5.10.1      Overview

This Service Set provides Services to access Attributes that are part of Nodes.

5.10.2      Read

5.10.2.1      Description

This Service is used to read one or more Attributes of one or more Nodes. For constructed Attribute values whose elements are indexed, such as an array, this Service allows Clients to read the entire set of indexed values as a composite, to read individual elements or to read ranges of elements of the composite.

The maxAge parameter is used to direct the Server to access the value from the underlying data source, such as a device, if its copy of the data is older than that which the maxAge specifies. If the Server cannot meet the requested maximum age, it returns its “best effort” value rather than rejecting the request.

5.10.2.2      Parameters

Table 53 defines the parameters for the Service.

Table 53 – Read Service Parameters

Name

Type

Description

Request

 

 

    requestHeader

RequestHeader

Common request parameters (see 7.28 for RequestHeader definition).

    maxAge

Duration

Maximum age of the value to be read in milliseconds. The age of the value is based on the difference between the ServerTimestamp and the time when the Server starts processing the request. For example if the Client specifies a maxAge of 500 milliseconds and it takes 100 milliseconds until the Server starts processing the request, the age of the returned value could be 600 milliseconds prior to the time it was requested.

If the Server has one or more values of an Attribute that are within the maximum age, it can return any one of the values or it can read a new value from the data source. The number of values of an Attribute that a Server has depends on the number of MonitoredItems that are defined for the Attribute. In any case, the Client can make no assumption about which copy of the data will be returned.

If the Server does not have a value that is within the maximum age, it shall attempt to read a new value from the data source.

If the Server cannot meet the requested maxAge, it returns its “best effort” value rather than rejecting the request. This may occur when the time it takes the Server to process and return the new data value after it has been accessed is greater than the specified maximum age.

If maxAge is set to 0, the Server shall attempt to read a new value from the data source.

If maxAge is set to the max Int32 value or greater, the Server shall attempt to get a cached value.

Negative values are invalid for maxAge.

    timestampsTo

    Return

Enum

TimestampsTo Return

An enumeration that specifies the Timestamps to be returned for each requested Variable Value Attribute. The TimestampsToReturn enumeration is defined in 7.35.

    nodesToRead []

ReadValueId

List of Nodes and their Attributes to read. For each entry in this list, a StatusCode is returned, and if it indicates success, the Attribute Value is also returned. The ReadValueId parameter type is defined in 7.24.

 

 

 

Response

 

 

    responseHeader

ResponseHeader

Common response parameters (see 7.29 for ResponseHeader definition).

    results []

DataValue

List of Attribute values (see 7.7 for DataValue definition). The size and order of this list matches the size and order of the nodesToRead request parameter. There is one entry in this list for each Node contained in the nodesToRead parameter.

    diagnosticInfos []

DiagnosticInfo

List of diagnostic information (see 7.8 for DiagnosticInfo definition). The size and order of this list matches the size and order of the nodesToRead request parameter. There is one entry in this list for each Node contained in the nodesToRead parame