## 7.41.2.1 Overview

The Client shall always prove possession of a UserIdentityToken when it passes it to the Server. Some tokens include a secret such as a password which the Server will accept as proof. In order to protect these secrets, the Token may be encrypted before it is passed to the Server. Other types of tokens allow the Client to create a signature with the secret associated with the Token. In these cases, the Client proves possession of a UserIdentityToken by creating a signature with the secret and passing it to the Server.

Each UserIdentityToken allowed by an Endpoint shall have a UserTokenPolicy specified in the EndpointDescription. The UserTokenPolicy specifies what SecurityPolicy to use when encrypting or signing. If this SecurityPolicy is null or empty then the Client uses the SecurityPolicy in the EndpointDescription. If the matching SecurityPolicy is set to None then no encryption or signature is required. The possible SecurityPolicies are defined in OPC 10000-7.

It is recommended that applications never set the SecurityPolicy to None for UserIdentityTokens that include a secret because these secrets could be used by an attacker to gain access to the system.

Clients shall validate the Server Certificate and ensure it is trusted before sending a UserIdentityToken encrypted with the Certificate.

The encrypted secret and Signature are embedded in a ByteString which is part of the UserIdentityToken. The format of this ByteString depends on the type of UserIdentityToken and the SecurityPolicy. Clients shall validate the Server Certificate and ensure it is trusted before sending a UserIdentityToken encrypted with the Certificate.

The legacy token secret format defined in 7.41.2.2 is not extensible and provides only encryption but the encrypted data is not signed. It is used together with the USERNAME UserIdentityToken. The password secret exchanged with this format shall not exceed 64 bytes.

The EncryptedSecret format defined in 7.41.2.3 provides an extensible secret format together with the definition how the secret is signed and encrypted. It allows for the layout to be updated as new token types are defined or new SecurityPolicies are added.

The UserIdentityToken types and the token formats supported by the Endpoint are identified by the UserTokenPolicy defined in 7.42.

To prevent the leakage of information useful to attackers, Servers shall ensure that the process of validating UserIdentityTokens completes in a fixed interval independent of whether an error occurs or not. The process of validation includes decrypting, check for padding and checking for a valid nonce. If any errors occur the return code is Bad_IdentityTokenInvalid.

Servers shall log details of any failure to validate a UserIdentityToken and shall lock out Client applications after five failures.

## 7.41.2.2 Legacy Encrypted Token Secret Format

When encrypting a UserIdentityToken, the Client appends the last ServerNonce to the secret. The data is then encrypted with the public key from the Server’s Certificate.

A Client should not add any padding after the secret. If a Client adds padding then all bytes shall be zero. A Server shall check for padding added by Clients and ensure that all padding bytes are zeros. Servers shall reject UserIdentityTokens with invalid padding. Administrators shall be able to configure Servers to accept UserIdentityTokens with invalid padding.

If no encryption is applied, the structure is not used and only the secret without any Nonce is passed to the Server.

Table 186 describes how to serialize UserIdentityTokens before applying encryption.

Table 186 – Legacy UserIdentityToken Encrypted Token Secret Format

Name Type Description
Length Byte [4]    The length of the data to be encrypted including the ServerNonce but excluding the length field.This field is a 4-byte unsigned integer encoded with the least significant bytes appearing first.
tokenData Byte [*] The token data.
serverNonce Byte [*] The last ServerNonce returned by the Server in the CreateSession or ActivateSession response.

## 7.41.2.3 EncryptedSecret Format

The EncryptedSecret uses an extensible format which has the TypeId of a DataType Node as a prefix as defined for the ExtensionObject encoding in OPC 10000-6. The general layout of the EncryptedSecret is shown in Figure 39.

Figure 39 – EncryptedSecret layout

The TypeId specifies how the EncryptedSecret is serialized and secured. For example, the RsaEncryptedSecret requires that the KeyData be encrypted with the public key associated with the EncryptingCertificate before it is serialized.

The SecurityPolicyUri is used to determine what algorithms were used to encrypt and sign the data. Valid SecurityPolicyUris are defined in OPC 10000-7.

The payload is always encrypted using the symmetric encryption algorithm specified by the SecurityPolicyUri. The KeyData is used to create the keys used needed for the symmetric encryption. The structure of the KeyData depends on the EncryptedSecret DataType.

The EncryptedSecret is secured and serialized as follows:

• Serialize the KeyData;
• If required, encrypt the KeyData and append the result to the common header;
• Update the KeyDataLength with the length of the encrypted KeyData;
• Append the Nonce and the Secret to the encrypted KeyData;
• Calculate padding required on the payload and append after the Secret;
• Calculate a Signature;
• Append the Signature.

Individual fields are serialized using the UA Binary encoding (see OPC 10000-6) for the DataType specified in Table 187. The Padding is used to ensure there is enough data to fill an integer multiple of encryption blocks. The size of the encryption block depends on the encryption algorithm. The total length of the Padding, not including the PaddingSize, is encoded as a UInt16. The individual bytes of the Padding are set to the the least significant byte of the PaddingSize.

The EncryptedSecret is deserilized and validated as follows:

• Verify the Signature if the KeyData is not encrypted;
• Decrypt the KeyData and verify the Signature if the KeyData is encrypted;
• Extract the Secret;

The fields in the EncryptedSecret are described in Table 187. The first three fields TypeId, EncodingMask and Length belong to the ExtensionObject encoding defined in OPC 10000-6.

Table 187 – EncryptedSecret layout

Name Type Description
TypeId NodeId The NodeId of the DataType Node.
EncodingMask Byte This value is always 1.
Length Int32 The length of the data that follows including the Signature.
SecurityPolicyUri String The URI for the SecurityPolicy used to apply security.
Certificate ByteString The signing and/or encrypting Certificate.
SigningTime DateTime When the Signature was created.
KeyDataLength UInt16    The length, in bytes, of the KeyData that follows   If the KeyData is encrypted this is the length of the encrypted data;Otherwise, it is the length of the unencrypted data.
KeyData Byte [*] The key data used to create the keys needed for decrypting and verifying the payload. Each EncryptedSecret DataType describes how the key data is structured for different SecurityPolicies.
Nonce ByteString    This is the last serverNonce returned in the CreateSession or ActivateSession Response when a UserIdentityToken is passed with the ActivateSession Request. If used outside of an ActivateSession call, the Nonce is created by the sender and is a function of the SecureChannelNonceLength.
Secret ByteString    The secret to protect.   The password when used with UserNameIdentityTokens.   The tokenData when used with IssuedIdentityTokens.If the Secret is a String is it encoded using UTF-8 first.
Signature Byte[*]    The Signature calculated after all encryption is applied.Each EncryptedSecret DataType describes how the Signature is calculated for different SecurityPolicies.

If (Secret.Length + PayloadPaddingSize < InputBlockSize) Then


Where the InputBlockSize is specified by the SymmetricEncryptionAlgorithm.

The currently available EncryptedSecret DataTypes are defined in Table 188.

Table 188 – EncryptedSecret DataTypes

Type Name When to Use
RsaEncryptedSecret Used when the SecurityPolicy requires the use of RSA cryptography. It is described in 7.41.2.4.
EccEncryptedSecret Used when the SecurityPolicy requires the use of ECC cryptography. It is described in .

## 7.41.2.4 RsaEncryptedSecret DataType

The RsaEncryptedSecret uses RSA based Asymmetric Cryptography.

Additional semantics for the fields in the EncryptedSecret layout for the RsaEncryptedSecret Structure are described in Table 189.

Table 189 – RsaEncryptedSecret structure

Name Type Description
TypeId NodeId The NodeId of the RsaEncryptedSecret DataType Node.
Length UInt32 See Table 187.
SecurityPolicyUri String See Table 187.
Certificate ByteString The SHA1 hash of the DER form of the Certificate used to encrypt the KeyData.
SigningTime DateTime See Table 187.
KeyDataLength UInt16 The length, in bytes, of the encrypted KeyData.
KeyData   The KeyData is encrypted with the PublicKey associated with the Certificate.
SigningKey ByteString    The key used to compute the Signature.
EncryptingKey ByteString    The key used to encrypt payload.
InitializationVector ByteString    The initialization vector used with the EncryptingKey.
Nonce ByteString A Nonce. This is the last ServerNonce returned in the CreateSession or ActivateSession Response when proving a UserIdentityToken passed in the ActivateSession Request. In other contexts, this is a Nonce created by the sender with a length equal to the SecureChannelNonceLength.
Secret ByteString See Table 187.
Signature Byte[*]    The Signature calculated with the SigningKey.The Signature calculated is calculated after encrypting the KeyData and the payload.

## 7.41.2.5 EccEncryptedSecret DataType

The EccEncryptedSecret uses ECC based Asymmetric Cryptography.

Additional semantics for the fields in the EncryptedSecret layout for the EccEncryptedSecret Structure are described in Table 190.

The EccEncryptedSecret uses ECC EphemeralKeys to create the symmetric key used to encrypt the Secret. The handshake required to create and use the EphemeralKeys is described in OPC 10000-6.

Table 190 – EccEncryptedSecret Layout

Name Type Description
TypeId NodeId The NodeId of the EccEncryptedSecret DataType Node.