OPC UA Connection Protocol (UACP) is an abstract protocol that establishes a full duplex channel between a Client and 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 TransportConnection for TCP/IP. TransportConnections allow responses to be returned in any order and allow responses to be returned on a different physical TransportConnection if communication failures cause temporary interruptions.

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

Figure 17 illustrates the structure of a Message placed on the wire. This also illustrates how the Message elements 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.

image020.png

Figure 17 – OPC UA Connection Protocol Message structure

Every OPC UA Connection Protocol Message has a header with the fields defined in Table 68.

Table 68 – OPC UA Connection Protocol Message header

Name

Type

Description

MessageType

Byte [3]

A three byte ASCII code that identifies the Message type.

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 SecureChannel layer defines additional values which the OPC UA Connection Protocol layer shall accept.

Reserved

Byte [1]

Ignored. shall be set to the ASCII codes for ‘F’ if the MessageType is 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 Message header.

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

The OPC UA Connection Protocol layer shall verify the MessageType and make sure the MessageSize is less than the negotiated ReceiveBufferSize before passing any Message onto the SecureChannel layer.

The Hello Message has the additional fields shown in Table 69.

Table 69 – OPC UA Connection Protocol Hello Message

Name

Data Type

Description

ProtocolVersion

UInt32

The version of the UACP protocol requested by the Client.

If Server does not support the requested version or any lower version it rejects the Client by returning Bad_ProtocolVersionUnsupported.

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

The ProtocolVersion for this version of the standard is 0.

ReceiveBufferSize

UInt32

The largest MessageChunk that 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 MessageChunk that 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 MessageChunks have not been sent, the Server shall return an Error Message with a Bad_ResponseTooLarge error if a response Message exceeds this value.

If MessageChunks have already been sent the Server shall abort the Message as described in 6.7.3.

The Message size is calculated using the unencrypted Message body.

A value of zero indicates that the Client has no limit.

MaxChunkCount

UInt32

The maximum number of chunks in any response Message.

The Server shall abort the Message with a Bad_ResponseTooLarge Error Message if a response Message exceeds this value.

The mechanism for aborting Messages is described fully in 6.7.3.

A value of zero indicates that the Client has no limit.

EndpointUrl

String

The URL of the Endpoint which the Client wished to connect to.

The encoded value shall be less than 4 096 bytes.

Servers shall return a Bad_TcpEndpointUrlInvalid Error Message and close the connection if the length exceeds 4 096 or if it does not recognize the resource identified by the URL.

The EndpointUrl parameter is used to allow multiple Servers to share the same endpoint on a machine. The process listening (also known as the proxy) on the endpoint would connect to the Server identified by the EndpointUrl and would forward all Messages to the Server via this socket. If one socket closes, then the proxy shall close the other socket.

If the Server does not have sufficient resources to allow the establishment of a new SecureChannel it shall immediately return a Bad_TcpNotEnoughResources Error Message and gracefully close the socket. Client should not overload Servers that return this error by immediately trying to create a new SecureChannel.

The Acknowledge Message has the additional fields shown in Table 70.

Table 70 – OPC UA Connection Protocol Acknowledge Message

Name

Type

Description

ProtocolVersion

UInt32

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

If the Client accepts the protocol version it shall ensure that it sends Messages that conform to this version.

The ProtocolVersion for this version of the standard is 0.

ReceiveBufferSize

UInt32

The largest MessageChunk that the sender can receive.

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

Shall be at least 8 192 bytes if the SendBufferSize requested 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 ReceiveBufferSize requested in the Hello Message.

Shall be at least 8 192 bytes if the ReceiveBufferSize requested 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 Message exceeds this value the Client shall report a Bad_ResponseTooLarge error to the application. If MessageChunks have already been sent the Client shall also abort the Message as described in 6.7.3.

The Message size is calculated using the unencrypted Message body.

A value of zero indicates that the Server has no limit.

MaxChunkCount

UInt32

The maximum number of chunks in any request Message.

The Client shall abort the Message with a Bad_RequestTooLarge StatusCode if a request Message exceeds this value.

The mechanism for aborting Messages is described fully in 6.7.3.

A value of zero indicates that the Server has no limit.

The Error Message has the additional fields shown in Table 71.

Table 71 – OPC UA Connection Protocol Error Message

Name

Type

Description

Error

UInt32

The numeric code for the error.

Possible values are listed in Table 74.

Reason

String

A more verbose description of the error.

This string shall not be more than 4 096 bytes.

A Client shall ignore strings that are longer than this.

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

The ReverseHello Message has the additional fields shown in Table 72.

Table 72 – OPC UA Connection Protocol ReverseHello Message

Name

Data Type

Description

ServerUri

String

The ApplicationUri of the Server which sent the Message.

The encoded value shall be less than 4 096 bytes.

Client shall return a Bad_TcpEndpointUrlInvalid error and close the connection if the length exceeds 4 096 or if it does not recognize the Server identified by the URI.

EndpointUrl

String

The URL of the Endpoint which the Client uses when establishing the SecureChannel.

This value shall be passed back to the Server in the Hello Message.

The encoded value shall be less than 4 096 bytes.

Clients shall 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 Server which the Client may 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 Message allows Servers behind firewalls with no open ports to connect to a Client and request that the Client establish a SecureChannel using the socket created by the Server.

For message-based protocols the ReverseHello Message allows Servers to announce their presence to a Client. In this scenario, the EndpointUrl specifies the Server’s specific address and any tokens required to access it.

Connections may be initiated by the Client or by the Server when they create a TransportConnection and establish a communication with their peer. The connection is initiated by using an EndpointUrl that specifies a network address where a peer listens for new connections. The EndpointUrl specifies a network address that is accessible to the initiator. If the listener is behind a NAT firewall, the EndpointUrl specifies an address outside the firewall. If the EndpointUrl specifies a domain name then the initiator requires access to a domain name resolution service (e.g., the DNS protocol) that maps the domain name onto a usable network address. OPC 10000-7 defines Profiles for different name resolution protocols that Clients and Servers may support.

If the Client creates the TransportConnection, the first Message sent shall be a Hello which specifies the buffer sizes that the Client supports. The Server shall respond with an Acknowledge Message which completes the buffer negotiation. The negotiated buffer size shall be reported to the SecureChannel layer. The negotiated SendBufferSize specifies the size of the MessageChunks to use for Messages sent over the connection.

If the Server creates the TransportConnection the first Message shall be a ReverseHello sent to the Client. If the Client accepts the connection, it sends a Hello message back to the Server which starts the buffer negotiation described for the Client initiated connection.

The Hello/Acknowledge Messages may 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 TransportConnection after a period of time if it does not receive a Hello or ReverseHello Message. This period of time shall be configurable and have a default value which does not exceed two minutes.

The Client sends the OpenSecureChannel request once it receives the Acknowledge back from the Server. If the Server accepts the new channel, it shall associate the TransportConnection with the SecureChannelId. The Server uses this association to determine which TransportConnection to use when it has to send a response to the Client. The Client does the same when it receives the OpenSecureChannel response.

The Server application does not do any processing while the SecureChannel is negotiated; however, the Server application shall provide the Stack with the list of trusted Certificates. The Stack shall provide notifications to the Server application whenever it receives an OpenSecureChannel request. These notifications shall include the OpenSecureChannel or Error response returned to the Client.

The sequence of Messages when establishing a Client initiated OPC UA Connection Protocol connection is shown in Figure 18.

image021.png

Figure 18 – Client initiated OPC UA Connection Protocol connection

The sequence of Messages when establishing a Server initiated OPC UA Connection Protocol connection is shown in Figure 19.

image022.png

Figure 19 – Server initiated OPC UA Connection Protocol connection

For Server-initiated connections, the Server needs to be configured and enabled by an administrator to connect to one or more Clients. For each Client, the administrator shall provide an EndpointUrl which may be use to establish a connection.wh. If the Client EndpointUrl is not known, the administrator may provide the EndpointUrl for a GDS (see OPC 10000-12) which knows about the Client. In this case, the administrator shall also provide an ApplicationUri which can be used to find the Client in the GDS.

Servers shall maintain at least one open socket without an active Session with each Client it is configured to connect to. Servers may delay re-connecting if the Client reports an error. Table 73 describes the process in full and how the Server is expected to react to different actions by the Client.

Table 73 – Client and Server Handshake during Reverse Connect

Action

Notes

Open Connection

Server creates a socket to a URL specified in its configuration.

Client shall close the socket after short delay if no ReverseHello Message received.

Server shall create a new socket because it cannot know if it was a network issue or due to action by the Client.

Reverse Hello

Server sends ReverseHello with its ApplicationUri.

Client may check the ApplicationUri. If it is not acceptable it shall close the socket.

Client shall send an Error Message with the code Bad_ServerTooBusy if it does not have enough resources to keep the socket open.

Client may save socket for use in the future (the sequence may pause here).

If the Server receives an Error Message it shall close the socket, log the error and reconnects after a delay specified in its configuration.

If the socket is closed without an Error Message, the Server shall create a new socket with or without a delay and sends a new ReverseHello Message.

HelloAcknowledgeOpen Secure Channel RequestOpen Secure Channel Response

Client establishes a SecureChannel and verifies that it trusts the Server.

Client may save the SecureChannel for use in the future (the sequence may pause here).

Client may use SecureChannel for Discovery or Session-less Service invocations.

Once a SecureChannel is established, the Server shall create a new socket if there is not already one without an active SecureChannel.

If the SecureChannel is closed, the Server shall create a new socket if there is not already one without an active SecureChannel.

Create Session

Client establishes a Session.

The Client closes the connection by sending a CloseSecureChannel request and closing the socket gracefully. When the Server receives this Message, it shall release all resources allocated for the channel. The body of the CloseSecureChannel request is empty. The Server does not send a CloseSecureChannel response.

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

The sequence of Messages when closing an OPC UA Connection Protocol connection is shown in Figure 20.

image023.png

Figure 20 – Closing a OPC UA Connection Protocol connection

The Server application does not do any processing when the SecureChannel is closed; however, the Stack shall provide notifications to the Server application whenever a CloseSecureChannel request is received or when the Stack cleans up an abandoned SecureChannel.

When a fatal error occurs, the Server shall send an Error Message to the Client and closes the TransportConnection gracefully. When the Client receives an Error Message it reports the error to the application and closes the TransportConnection gracefully. If a Client encounters a fatal error, it shall report the error to the application and send a CloseSecureChannel Message. The Server shall close the TransportConnection gracefully when it receives the CloseSecureChannel Message.

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

Table 74 – OPC UA Connection Protocol error codes

Name

Description

Bad_TcpServerTooBusy

The Server cannot process the request because it is too busy.

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

A Server can control the how frequently a Client reconnects by waiting to return this error.

Bad_TcpMessageTypeInvalid

The type of the Message specified in the header invalid.

Each Message starts with a 4-byte sequence of ASCII values that identifies the Message type.

The Server returns this error if the Message type is not accepted.

Some of the Message types are defined by the SecureChannel layer.

Bad_TcpSecureChannelUnknown

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

This error is reported by the SecureChannel layer.

Bad_TcpMessageTooLarge

The size of the MessageChunk specified in the header is too large.

The Server returns this error if the MessageChunk size 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 Server to determine when a timeout occurs.

Bad_TcpNotEnoughResources

There are not enough resources to process the request.

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

A Server can control the how frequently a Client reconnects 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 Server does not recognize the EndpointUrl specified.

Bad_SecurityChecksFailed

The Message was 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 SecurityToken has expired or is not recognized.

Bad_CertificateUntrusted

The sender Certificate is not trusted by the receiver.

Bad_CertificateTimeInvalid

The sender Certificate has expired or is not yet valid.

Bad_CertificateIssuerTimeInvalid

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

Bad_CertificateUseNotAllowed

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

Bad_CertificateIssuerUseNotAllowed

The issuer Certificate may not be used as a Certificate Authority.

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 Certificate has been revoked by the issuer.

Bad_IssuerCertificateRevoked

The issuer Certificate has been revoked by its issuer.

Bad_SequenceNumberInvalid

The sequence number on the message was not valid.

Bad_ServiceUnsupported

The Service Request contained in the body of the message is not supported. This error is only returned when the Request represents a security risk and it is necessary to immediately close the SecureChannel. For example, calling CreateSession on a SecureChannel that does not allow Sessions.

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

NOTE: The ‘Tcp’ prefix for some of the error codes in Table 74 was 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.