The Clientshall always prove possession of a UserIdentityToken when it passes it to the Server. Some tokens include a secret such as a password which the Serverwill accept as proof. In order to protect these secrets, the Tokenmay be encrypted before it is passed to the Server. Other types of tokens allow the Clientto create a signature with the secret associated with the Token. In these cases, the Clientproves possession of a UserIdentityToken by creating a signature with the secret and passing it to the Server.
Each UserIdentityTokenallowed by an Endpointshall have a UserTokenPolicyspecified in the EndpointDescription. The UserTokenPolicyspecifies what SecurityPolicyto use when encrypting or signing. If this SecurityPolicyis null or empty then the Clientuses the SecurityPolicyin the EndpointDescription. If the matching SecurityPolicyis set to Nonethen no encryption or signature is required. The possible SecurityPoliciesare defined in OPC 10000-7.
It is recommended that applications never set the SecurityPolicyto Nonefor UserIdentityTokensthat include a secret because these secrets could be used by an attacker to gain access to the system.
Clientsshall validate the Server Certificateand ensure it is trusted before sending a UserIdentityTokenencrypted with the Certificate.
The encrypted secret and Signatureare embedded in a ByteStringwhich is part of the UserIdentityToken. The format of this ByteStringdepends on the type of UserIdentityTokenand the SecurityPolicy. Clientsshall validate the Server Certificateand ensure it is trusted before sending a UserIdentityTokenencrypted with the Certificate.
The legacy token secret format defined in 7.41.2.2is 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 EncryptedSecretformat defined in 7.41.2.3provides 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 SecurityPoliciesare added.
The UserIdentityTokentypes and the token formats supported by the Endpointare identified by the UserTokenPolicydefined in 7.42.
To prevent the leakage of information useful to attackers, Serversshall ensure that the process of validating UserIdentityTokenscompletes 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.
Serversshall log details of any failure to validate a UserIdentityToken and shall lock out Clientapplications after five failures.
When encrypting a UserIdentityToken, the Clientappends the last ServerNonceto the secret. The data is then encrypted with the public key from the Server’s Certificate.
A Clientshould not add any padding after the secret. If a Clientadds padding then all bytes shall be zero. A Servershall check for padding added by Clientsand ensure that all padding bytes are zeros. Serversshall reject UserIdentityTokens with invalid padding. Administrators shall be able to configure Serversto accept UserIdentityTokens with invalid padding.
If no encryption is applied, the structure is not used and only the secret without any Nonceis passed to the Server.
Table 186describes how to serialize UserIdentityTokensbefore 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 ServerNoncebut excluding the lengthfield. 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 ServerNoncereturned by the Serverin the CreateSessionor ActivateSessionresponse. |
The EncryptedSecretuses an extensible format which has the TypeIdof a DataType Nodeas a prefix as defined for the ExtensionObjectencoding in OPC 10000-6. The general layout of the EncryptedSecretis shown in Figure 39.
Figure 39– EncryptedSecret layout
The TypeIdspecifies how the EncryptedSecretis serialized and secured. For example, the RsaEncryptedSecretrequires that the KeyDatabe encrypted with the public key associated with the EncryptingCertificatebefore it is serialized.
The SecurityPolicyUriis 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 KeyDatais used to create the keys used needed for the symmetric encryption. The structure of the KeyDatadepends on the EncryptedSecret DataType.
The EncryptedSecretis secured and serialized as follows:
- Serialize the common header;
- 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;
- Encrypt the payload;
- Calculate a Signature;
- Append the Signature.
Individual fields are serialized using the UA Binary encoding (see OPC 10000-6) for the DataTypespecified in Table 187. The Paddingis 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 Paddingare set to the the least significant byte of the PaddingSize.
The EncryptedSecret is deserilized and validated as follows:
- Deserialize the common header;
- Verify the Signature if the KeyData is not encrypted;
- Decrypt the KeyData and verify the Signature if the KeyData is encrypted;
- Decrypt the payload;
- Verify the padding on the payload;
- Extract the Secret;
The fields in the EncryptedSecretare described in Table 187. The first three fields TypeId, EncodingMaskand Lengthbelong to the ExtensionObjectencoding defined in OPC 10000-6.
Table 187– EncryptedSecret layout
Name |
Type |
Description |
TypeId |
NodeId |
|
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 SecurityPolicyused to apply security. |
Certificate |
ByteString |
The signing and/or encrypting Certificate. |
SigningTime |
DateTime |
When the Signaturewas created. |
KeyDataLength |
UInt16 |
The length, in bytes, of the KeyDatathat follows If the KeyDatais 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 DataTypedescribes how the key data is structured for different SecurityPolicies. |
Nonce |
ByteString |
This is the last serverNoncereturned in the CreateSessionor ActivateSession Responsewhen a UserIdentityTokenis passed with the ActivateSession Request. If used outside of an ActivateSession call, the Nonceis created by the sender and is a function of the SecureChannelNonceLength. |
Secret |
ByteString |
The secret to protect. The passwordwhen used with UserNameIdentityTokens. The tokenDatawhen used with IssuedIdentityTokens. |
PayloadPadding |
Byte[*] |
Additional padding added to ensure the size of the encrypted payload is an integer multiple of the input block size for the symmetric encryption algorithm specified by the SecurityPolicyUri. The value of each byte is the least significant byte of the PayloadPaddingSize. |
PayloadPaddingSize |
UInt16 |
The size of the padding added to the payload. |
Signature |
Byte[*] |
The Signaturecalculated after all encryption is applied. Each EncryptedSecret DataTypedescribes how the Signatureis calculated for different SecurityPolicies. |
The PayloadPaddingSize adjusted with the following formula:
If (Secret.Length + PayloadPaddingSize < InputBlockSize) Then
PayloadPaddingSize = PayloadPaddingSize + InputBlockSize
Where the InputBlockSize is specified by the SymmetricEncryptionAlgorithm.
The currently available EncryptedSecret DataTypesare defined in Table 188.
Table 188– EncryptedSecret DataTypes
Type Name |
When to Use |
RsaEncryptedSecret |
Used when the SecurityPolicyrequires the use of RSA cryptography. It is described in 7.41.2.4. |
EccEncryptedSecret |
Used when the SecurityPolicyrequires the use of ECC cryptography.It is described in . |
The RsaEncryptedSecretuses RSA based Asymmetric Cryptography.
Additional semantics for the fields in the EncryptedSecretlayout for the RsaEncryptedSecret Structureare described in Table 189.
Table 189– RsaEncryptedSecret structure
Name |
Type |
Description |
TypeId |
NodeId |
The NodeIdof the RsaEncryptedSecret DataType Node. |
EncodingMask |
Byte |
See Table 187. |
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 KeyDatais encrypted with the PublicKeyassociated 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 ServerNoncereturned in the CreateSessionor ActivateSession Responsewhen proving a UserIdentityTokenpassed in the ActivateSession Request. In other contexts, this is a Noncecreated by the sender with a length equal to the SecureChannelNonceLength. |
Secret |
ByteString |
See Table 187. |
PayloadPadding |
Byte[*] |
See Table 187. |
PayloadPaddingSize |
UInt16 |
See Table 187. |
Signature |
Byte[*] |
The Signaturecalculated with the SigningKey. The Signaturecalculated is calculated after encrypting the KeyDataand the payload. |
The EccEncryptedSecretuses ECC based Asymmetric Cryptography.
Additional semantics for the fields in the EncryptedSecretlayout for the EccEncryptedSecretStructure are described in Table 190.
The EccEncryptedSecretuses ECC EphemeralKeysto create the symmetric key used to encrypt the Secret. The handshake required to create and use the EphemeralKeysis described in OPC 10000-6.
Table 190– EccEncryptedSecret Layout
Name |
Type |
Description |
TypeId |
NodeId |
The NodeIdof the EccEncryptedSecret DataType Node. |
EncodingMask |
Byte |
See Table 187 |
Length |
UInt32 |
See Table 187 |
SecurityPolicyUri |
String |
See Table 187 |
Certificate |
ByteString |
The signing Certificateencoded in DER form. The value shall include the entire chain. This value may be null or empty if the SigningCertificateis known to the receiver. This is true if the structure is used to provide a UserIdentityTokento a Serverover a SecureChanneland the SigningCertificateis the Client ApplicationInstance Certificate. |
SigningTime |
DateTime |
See Table 187 |
KeyDataLength |
UInt16 |
The length of the KeyDatawithout encryption. |
KeyData |
|
The KeyDatais not encrypted. |
SenderPublicKey |
ByteString |
The Public Keyfor the EphemeralKeycreated by the sender. |
ReceiverPublicKey |
ByteString |
The Public Keyfor the EphemeralKeycreated by the receiver. |
Nonce |
ByteString |
A Nonce. This is the last ServerNoncereturned in the CreateSessionor ActivateSession Responsewhen proving a UserIdentityTokenpassed in the ActivateSession Request. In other contexts, this is a Noncecreated by the sender with a length equal to the ½ of the SecureChannelNonceLength. |
Secret |
ByteString |
See Table 187 |
PayloadPadding |
Byte [*] |
See Table 187 |
PayloadPaddingSize |
UInt16 |
See Table 187 |
Signature |
Byte [*] |
The Signaturecalculated with the PrivateKeyof the signing Certificate. The Signaturecalculated is calculated after encrypting the payload. |