OPC UA Connection Protocol (UACP) is an abstract protocol that establishes a full duplex channel between a Clientand Server. Concrete implementations of the UACP can be built with any middleware that supports full-duplex exchange of messages including TCP/IP and WebSockets. The term “TransportConnection” describes the specific connection used to exchange messages. For example, a socket is the TransportConnectionfor TCP/IP. TransportConnections allow responses to be returned in any order and allow responses to be returned on a different physical TransportConnectionif communication failures cause temporary interruptions.

The OPC UA Connection Protocol is designed to work with the SecureChannelimplemented by a layer higher in the stack. For this reason, the OPC UA Connection Protocol defines its interactions with the SecureChannelin addition to the wire protocol.

Figure 15illustrates the structure of a Messageplaced on the wire. This also illustrates how the Messageelements defined by the OPC UA Binary Encoding mapping (see 5.2) and the OPC UA Secure Conversation mapping (see 6.7) relate to the OPC UA Connection Protocol Messages.

image018.png

Figure 15– OPC UA Connection Protocol Message structure

Every OPC UA Connection Protocol Messagehas a header with the fields defined in Table 65.

Table 65– OPC UA Connection Protocol Message header

Name

Type

Description

MessageType

Byte [3]

A three byte ASCII code that identifies the Messagetype.

The following values are defined at this time:

HEL a Hello Message.

ACK an Acknowledge Message.

ERR an Error Message.

RHE a ReverseHello Message.

The SecureChannellayer defines additional values which the OPC UA Connection Protocollayer shall accept.

Reserved

Byte [1]

Ignored. shall be set to the ASCII codes for ‘F’ if the MessageTypeis one of the values supported by the OPC UA Connection Protocol.

MessageSize

UInt32

The length of the Message, in bytes. This value includes the 8 bytes for the Messageheader.

The layout of the OPC UA Connection Protocol Messageheader is intentionally identical to the first 8 bytes of the OPC UA Secure Conversation Messageheader defined in Table 50. This allows the OPC UA Connection Protocol layer to extract the SecureChannel Messagesfrom the incoming stream even if it does not understand their contents.

The OPC UA Connection Protocol layer shall verify the MessageTypeand make sure the MessageSizeis less than the negotiated ReceiveBufferSizebefore passing any Messageonto the SecureChannellayer.

The Hello Messagehas the additional fields shown in Table 66.

Table 66– OPC UA Connection ProtocolHello Message

Name

Data Type

Description

ProtocolVersion

UInt32

The version of the UACP protocol requested by the Client.

If Serverdoes not support the requested version or any lower version it rejects the Clientby returning Bad_ProtocolVersionUnsupported.

If the Serversupports the requested version or a lower version it shall return the version it will use in the Acknowledge Message.

The ProtocolVersionfor this version of the standard is 0.

ReceiveBufferSize

UInt32

The largest MessageChunkthat the sender can receive.

Shall be at least 1 024 bytes if the sender intends to use an ECC SecurityPolicy.

Shall be at least 8 192 bytes otherwise.

SendBufferSize

UInt32

The largest MessageChunkthat the sender will send.

Shall be at least 1 024 bytes if the sender intends to use an ECC SecurityPolicy.

Shall be at least 8 192 bytes otherwise.

MaxMessageSize

UInt32

The maximum size for any response Message.

If MessageChunkshave not been sent, the Servershall return an Error Messagewith a Bad_ResponseTooLargeerror if a response Messageexceeds this value.

If MessageChunkshave already been sent the Servershall abort the Messageas described in 6.7.3.

The Messagesize is calculated using the unencrypted Messagebody.

A value of zero indicates that the Clienthas no limit.

MaxChunkCount

UInt32

The maximum number of chunks in any response Message.

The Servershall abort the Messagewith a Bad_ResponseTooLarge Error Messageif a response Messageexceeds this value.

The mechanism for aborting Messagesis described fully in 6.7.3.

A value of zero indicates that the Clienthas no limit.

EndpointUrl

String

The URL of the Endpointwhich the Clientwished to connect to.

The encoded value shall be less than 4 096 bytes.

Serversshall return a Bad_TcpEndpointUrlInvalid Error Messageand close the connection if the length exceeds 4 096 or if it does not recognize the resource identified by the URL.

The EndpointUrlparameter is used to allow multiple Serversto share the same endpoint on a machine. The process listening (also known as the proxy) on the endpoint would connect to the Serveridentified by the EndpointUrland would forward all Messagesto the Servervia this socket. If one socket closes, then the proxy shall close the other socket.

If the Serverdoes not have sufficient resources to allow the establishment of a new SecureChannelit shall immediately return a Bad_TcpNotEnoughResources Error Messageand gracefully close the socket. Clientshould not overload Serversthat return this error by immediately trying to create a new SecureChannel.

The Acknowledge Messagehas the additional fields shown in Table 67.

Table 67– OPC UA Connection Protocol Acknowledge Message

Name

Type

Description

ProtocolVersion

UInt32

A protocol version supported by the Serverthat is less than or equal to the protocol version requested in the Hello Message.

If the Clientaccepts the protocol version it shall ensure that it sends Messagesthat conform to this version.

The ProtocolVersionfor this version of the standard is 0.

ReceiveBufferSize

UInt32

The largest MessageChunkthat the sender can receive.

This value shall not be larger than the SendBufferSizerequested in the Hello Message.

Shall be at least 8 192 bytes if the SendBufferSizerequested in the Hello Message is >= 8 192 bytes. Shall be at least 1 024 bytes otherwise.

SendBufferSize

UInt32

The largest MessageChunk that the sender will send.

This value shall not be larger than the ReceiveBufferSizerequested in the Hello Message.

Shall be at least 8 192 bytes if the ReceiveBufferSizerequested in the Hello Message is >= 8 192 bytes. Shall be at least 1 024 bytes otherwise.

MaxMessageSize

UInt32

The maximum size for any request Message.

If a request Messageexceeds this value the Clientshall report a Bad_ResponseTooLargeerror to the application. If MessageChunkshave already been sent the Clientshall also abort the Messageas described in 6.7.3.

The Messagesize is calculated using the unencrypted Messagebody.

A value of zero indicates that the Serverhas no limit.

MaxChunkCount

UInt32

The maximum number of chunks in any request Message.

The Clientshall abort the Messagewith a Bad_RequestTooLarge StatusCodeif a request Messageexceeds this value.

The mechanism for aborting Messagesis described fully in 6.7.3.

A value of zero indicates that the Serverhas no limit.

The Error Messagehas the additional fields shown in Table 68.

Table 68– OPC UA Connection Protocol Error Message

Name

Type

Description

Error

UInt32

The numeric code for the error.

Possible values are listed in Table 70.

Reason

String

A more verbose description of the error.

This string shall not be more than 4 096 bytes.

A Clientshall ignore strings that are longer than this.

The socket is always closed gracefully by the Clientafter it receives an Error Message.

The ReverseHello Messagehas the additional fields shown in Table 69.

Table 69– OPC UA Connection Protocol ReverseHello Message

Name

Data Type

Description

ServerUri

String

The ApplicationUriof the Serverwhich sent the Message.

The encoded value shall be less than 4 096 bytes.

Clientshall return a Bad_TcpEndpointUrlInvalid error and close the connection if the length exceeds 4 096 or if it does not recognize the Serveridentified by the URI.

EndpointUrl

String

The URL of the Endpointwhich the Clientuses when establishing the SecureChannel.

This value shall be passed back to the Serverin the Hello Message.

The encoded value shall be less than 4 096 bytes.

Clientsshall return a Bad_TcpEndpointUrlInvalid error and close the connection if the length exceeds 4 096 or if it does not recognize the resource identified by the URL.

This value is a unique identifier for the Serverwhich the Clientmay use to look up configuration information. It should be one of the URLs returned by the GetEndpoints Service.

For connection-based protocols, such as TCP, the ReverseHello Messageallows Serversbehind firewalls with no open ports to connect to a Clientand request that the Clientestablish a SecureChannelusing the socket created by the Server.

For message-based protocols the ReverseHello Messageallows Serversto announce their presence to a Client. In this scenario, the EndpointUrlspecifies the Server’sspecific address and any tokens required to access it.

Connections may be initiated by the Clientor by the Server when they create a TransportConnectionand establish a communication with their peer.If the Clientcreates the TransportConnection, the first Messagesent shall be a Hellowhich specifies the buffer sizes that the Clientsupports. The Servershall respond with an Acknowledge Messagewhich completes the buffer negotiation. The negotiated buffer size shall be reported to the SecureChannellayer. The negotiated SendBufferSizespecifies the size of the MessageChunksto use for Messagessent over the connection.

If the Servercreates the TransportConnectionthe first Messageshall be a ReverseHellosent to the Client. If the Clientaccepts the connection, it sends a Hellomessage back to the Serverwhich starts the buffer negotiation described for the Clientinitiated connection.

The Hello/Acknowledge Messagesmay only be sent once. If they are received again the receiver shall report an error and close the TransportConnection. Applications accepting incoming connections shall close any TransportConnectionafter a period of time if it does not receive a Helloor ReverseHello Message. This period of time shall be configurable and have a default value which does not exceed two minutes.

The Clientsends the OpenSecureChannelrequest once it receives the Acknowledgeback from the Server. If the Serveraccepts the new channel, it shall associate the TransportConnectionwith the SecureChannelId. The Serveruses this association to determine which TransportConnectionto use when it has to send a response to the Client. The Clientdoes the same when it receives the OpenSecureChannelresponse.

The sequence of Messageswhen establishing a Clientinitiated OPC UA Connection Protocol connection is shown in Figure 16.

image019.png

Figure 16– Client initiated OPC UA Connection Protocol connection

The sequence of Messageswhen establishing a Serverinitiated OPC UA Connection Protocolconnection is shown in Figure 17.

image020.png

Figure 17– Server initiated OPC UA Connection Protocol connection

The Serverapplication does not do any processing while the SecureChannelis negotiated; however, the Serverapplication shall to provide the Stackwith the list of trusted Certificates. The Stackshall provide notifications to the Serverapplication whenever it receives an OpenSecureChannelrequest.These notifications shall include the OpenSecureChannelor Errorresponse returned to the Client.

The Serverneeds to be configured and enabled by an administrator to connect to one or more Clients. For each Client, the administrator shall provide an ApplicationUriand an EndpointUrlfor the Client.If the Client EndpointUrlis not known, the administrator may provide the EndpointUrlfor a GDS (see OPC 10000-12) which knows about the Client. The Servershould expect that it will take some time for a Clientto respond to a ReverseHello. Once a Clientcloses a SecureChannelor if the socket is closed without establishing a SecureChannel the Servershall create a new socket and send a new ReverseHellomessage. When a SecureChannel is established, the Server shall immediately create a new socket and sends a new ReverseHelloto ensure the Clientis able to create another SecureChannelif it is needed.Administrators may limit the number of simultaneous sockets that a Serverwill create.

The Clientcloses the connection by sending a CloseSecureChannelrequest and closing the socket gracefully. When the Serverreceives this Message,it shall release all resources allocated for the channel. The body of the CloseSecureChannelrequest is empty. The Serverdoes not send a CloseSecureChannel response.

If security verification fails for the CloseSecureChannel Message,then the Servershall report the error and close the socket.

The sequence of Messageswhen closing an OPC UA Connection Protocol connection is shown in Figure 18.

image021.png

Figure 18– Closing a OPC UA Connection Protocol connection

The Serverapplication does not do any processing when the SecureChannelis closed; however, the Stackshall provide notifications to the Serverapplication whenever a CloseSecureChannelrequest is received or when the Stackcleans up an abandoned SecureChannel.

When a fatal error occurs, the Servershall send an Error Messageto the Client and closes the TransportConnectiongracefully. When the Clientreceives an Error Messageit reports the error to the application and closes the TransportConnectiongracefully. If a Clientencounters a fatal error, it shall report the error to the application and send a CloseSecureChannel Message. The Server shall close the TransportConnectiongracefully when it receives the CloseSecureChannel Message.

The possible OPC UA Connection Protocol errors are defined in Table 70.

Table 70– OPC UA Connection Protocolerror codes

Name

Description

Bad_TcpServerTooBusy

The Servercannot process the request because it is too busy.

It is up to the Serverto determine when it needs to return this Message.

A Servercan control the how frequently a Clientreconnects by waiting to return this error.

Bad_TcpMessageTypeInvalid

The type of the Messagespecified in the header invalid.

Each Messagestarts with a 4-byte sequence of ASCII values that identifies the Messagetype.

The Serverreturns this error if the Messagetype is not accepted.

Some of the Messagetypes are defined by the SecureChannellayer.

Bad_TcpSecureChannelUnknown

The SecureChannelId and/or TokenId are not currently in use.

This error is reported by the SecureChannellayer.

Bad_TcpMessageTooLarge

The size of the MessageChunkspecified in the header is too large.

The Serverreturns this error if the MessageChunksize exceeds its maximum buffer size or the receive buffer size negotiated during the Hello/Acknowledge exchange.

Bad_Timeout

A timeout occurred while accessing a resource.

It is up to the Serverto determine when a timeout occurs.

Bad_TcpNotEnoughResources

There are not enough resources to process the request.

The Serverreturns this error when it runs out of memory or encounters similar resource problems.

A Servercan control the how frequently a Clientreconnects by waiting to return this error.

Bad_TcpInternalError

An internal error occurred.

This should only be returned if an unexpected configuration or programming error occurs.

Bad_TcpEndpointUrlInvalid

The Serverdoes not recognize the EndpointUrl specified.

Bad_SecurityChecksFailed

The Messagewas rejected because it could not be verified.

Bad_RequestInterrupted

The request could not be sent because of a network interruption.

Bad_RequestTimeout

Timeout occurred while processing the request.

Bad_SecureChannelClosed

The secure channel has been closed.

Bad_SecureChannelTokenUnknown

The SecurityTokenhas expired or is not recognized.

Bad_CertificateUntrusted

The sender Certificateis not trusted by the receiver.

Bad_CertificateTimeInvalid

The sender Certificatehas expired or is not yet valid.

Bad_CertificateIssuerTimeInvalid

The issuer for the sender Certificatehas expired or is not yet valid.

Bad_CertificateUseNotAllowed

The sender’s Certificatemay not be used for establishing a secure channel.

Bad_CertificateIssuerUseNotAllowed

The issuer Certificatemay not be used as a CertificateAuthority.

Bad_CertificateRevocationUnknown

Could not verify the revocation status of the sender’s Certificate.

Bad_CertificateIssuerRevocationUnknown

Could not verify the revocation status of the issuer Certificate.

Bad_CertificateRevoked

The sender Certificatehas been revoked by the issuer.

Bad_IssuerCertificateRevoked

The issuer Certificatehas been revoked by its issuer.

Bad_SequenceNumberInvalid

The sequence number on the message was not valid.

The numeric values for these error codes are defined in A.2.

NOTE: The ‘Tcp’ prefix for some of the error codes in Table 70was chosen when TCP/IP was the only implementation of the OPC UA Connection Protocol. These codes are used with any implementation of the OPC UA Connection Protocol.