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 middleware 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 12illustrates 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.

image015.png

Figure 12– OPC UA Connection Protocol Message structure

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

Table 50– 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 Protocolprotocol.

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 41. 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 51.

Table 51– OPC UA Connection ProtocolHello Message

Name

Data Type

Description

ProtocolVersion

UInt32

The latest version of the UACP protocol supported by the Client.

The Servermay reject the Clientby returning Bad_ProtocolVersionUnsupported.

If the Serveraccepts the connection is responsible for ensuring that it returns Messagesthat conform to this version of the protocol.

The Servershall always accept versions greater than what it supports.

ReceiveBufferSize

UInt32

The largest MessageChunkthat the sender can receive.

SendBufferSize

UInt32

The largest MessageChunkthat the sender will send.

MaxMessageSize

UInt32

The maximum size for 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.

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 52.

Table 52– OPC UA Connection Protocol Acknowledge Message

Name

Type

Description

ProtocolVersion

UInt32

The latest version of the UACP protocol supported by the Server.

If the Clientaccepts the connection is responsible for ensuring that it sends Messagesthat conform to this version of the protocol.

The Clientshall always accept versions greater than what it supports.

ReceiveBufferSize

UInt32

The largest MessageChunkthat the sender can receive.

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

SendBufferSize

UInt32

The largest MessageChunk that the sender will send.

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

MaxMessageSize

UInt32

The maximum size for 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.

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 53.

Table 53– OPC UA Connection Protocol Error Message

Name

Type

Description

Error

UInt32

The numeric code for the error.

This shall be one of the values listed in Table 55.

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 54.

Table 54– 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’sprotocol specific 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 are shown in Figure 13.

image016.png

Figure 13– Client initiated OPC UA Connection Protocol connection

The sequence of Messageswhen establishing a Serverinitiated OPC UA Connection Protocolconnection are shown in Figure 14.

image017.png

Figure 14– 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 thenthe Servershall create a new socket and send a new ReverseHellomessage. 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 15.

image018.png

Figure 15– 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 55.

Table 55– 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 Messagespecified in the header is too large.

The Serverreturns this error if the Messagesize 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_CertificateUnknown

The receiver Certificatethumbprint is not recognized by the receiver.

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

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