Errata exists for this version of the document.
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 omitted 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.
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.
The legacy token secret format defined in 7.36.2.2 is not extensible and provides only encryption but the encrypted data is not signed. It is used together with the USERNAME_1 UserIdentityToken. The password secret exchanged with this format shall not exceed 64 bytes.
The EncryptedSecret format defined in 7.36.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.37.
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.
If no encryption is applied, the structure is not used and only the secret without any Nonce is passed to the Server.
Table 181 describes how to serialize UserIdentityTokens before applying encryption.
Table 181 – 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. |
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, RsaEncryptedSecrets require that the policy header be encrypted with the public key associated with the EncryptingCertificate before it is serialized. Other TypeIds may or may not require the policy header to be encrypted.
The SecurityPolicyUri is used to determine what algorithms were used to encrypt and sign the data.
The payload is always encrypted using the symmetric encryption algorithm specified by the SecurityPolicyUri. The EncryptingKey and InitializationVector are used to initialize this algorithm. The mechanisms used to initialize the symmetric encryption algorithm depend on the TypeId. The lengths of the fields are specified by the SecurityPolicyUri.
The Signature using the symmetric signature algorithm specified by the SecurityPolicyUri. The SymmetricKey and InitializationVector are used to initialize this algorithm. The mechanisms used to initialize the symmetric signature algorithm depend on the TypeId. The length of the SymmetricKey is specified by the SecurityPolicyUri.
The EncryptedSecret is secured and serialized as follows:
- Serialize the common header;
- Serialize the policy header;
- Encrypt the policy header and append the result to the common header;
- Update the PolicyHeaderLength with the length of the encrypted header;
- Append the Nonce and the Secret to the encrypted policy header;
- Calculate padding required on the payload and append after the Secret;
- Encrypt the payload;
- Calculate a Signature on {common header | encrypted policy header | encrypted payload};
- Append the Signature.
Individual fields are serialized using the UA Binary encoding (see OPC 10000-6) for the DataType specified in Table 182. 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. Two separate padding operations are needed because two different encryption algorithms may be used. 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:
- Deserialize the common header;
- Decrypt the policy header using the private key associated with the EncryptingCertificate;
- Verify the padding in the policy header;
- Verify the Signature with the SigningKey;
- Decrypt the payload;
- Verify the padding on the payload;
- Extract the Secret;
If the TypeId does not require the policy header to be encrypted then the padding on the policy header is omitted and the PolicyHeaderLength specifies the length of the unencrypted data.
The fields in the EncryptedSecret are described in Table 182. The first three fields TypeId, EncodingMask and Length belong to the ExtensionObject encoding defined in OPC 10000-6.
Table 182 – 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 SecurityPolicy used to apply security. |
EncryptingCertificate |
ByteString |
The SHA1 thumbprint of the DER form of the encrypting Certificate. |
SigningTime |
DateTime |
When the Signature was created. |
PolicyHeaderLength |
UInt16 |
The length of the policy header that follows If the policy header is encrypted this is the length of the encrypted data; Otherwise, it is the length of the unencrypted data; |
SigningKey |
ByteString |
The key data used to create the Signature. The TypeId specifies how this data is used. |
EncryptingKey |
ByteString |
The key data used to encrypt the payload. The TypeId specifies how this data is used. |
InitializationVector |
ByteString |
The data used to initialize the algorithm used to encrypt the payload. The TypeId specifies how this data is used. |
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 source of the Nonce is defined by the context in which this EncryptedSecret is used. The length of the Nonce shall equal the SecureChannelNonceLength specified by the SecurityPolicy. |
Secret |
ByteString |
The tokenData that depends on the IssuedIdentityToken. If the tokenData is a String is it encoded using UTF-8 first. |
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 signature calculated using the symmetric signing algorithm specified by the SecurityPolicyUri. The length of the signature is specified by the SecurityPolicyUri. |
The currently available EncryptedSecret DataTypes are defined in Table 183.
Table 183 – EncryptedSecret DataTypes
Type Name |
When to Use |
RsaEncryptedSecret |
Used when the SecurityPolicy requires the use of RSA based asymmetric encryption. It is described in 7.36.2.4. |
The RsaEncryptedSecret uses RSA based asymmetric encryption to encrypt the policy header.
Additional semantics for the fields in the EncryptedSecret layout for the RsaEncryptedSecret Structure are described in Table 184.
Table 184 – RsaEncryptedSecret Structure
Name |
Type |
Description |
TypeId |
NodeId |
The NodeId of the RsaEncryptedSecret DataType Node. |
EncodingMask |
Byte |
See Table 182. |
Length |
UInt32 |
See Table 182. |
SecurityPolicyUri |
String |
See Table 182. |
EncryptingCertificate |
ByteString |
See Table 182. |
SigningTime |
DateTime |
See Table 182. |
PolicyHeaderLength |
UInt16 |
See Table 182. |
SigningKey |
ByteString |
The key used to compute the Signature. See Table 182 for additional details. |
EncryptingKey |
ByteString |
The key used to encrypt payload. See Table 182 for additional details. |
InitializationVector |
ByteString |
The initialization vector used with the EncryptingKey. See Table 182 for additional details. |
Nonce |
ByteString |
See Table 182. |
Secret |
ByteString |
See Table 182. |
PayloadPadding |
Byte[*] |
See Table 182. |
PayloadPaddingSize |
UInt16 |
See Table 182. |
Signature |
Byte[*] |
See Table 182. |