ANSI C Based OPC UA Client/Server/PubSub SDK  1.9.1.442
Authentication

Overview

The server allows to authenticate users by username and password when a session is activated. The user’s credentials are then verified with one of the available authentication modules. Only one module can be activated at the same time.

There are five authentication modules available:

Internal Authentication Module
DEPRECATED: File based module, available on all OS that have a filesystem
InternalEx Authentication Module
File based module using salted hashes, available on all OS that have a filesystem
PAM Authentication Module
Linux only, needs PAM configuration file
SASL Authentication Module
Linux only, needs running saslauthd daemon
Win32 Authentication Module
Windows only

To activate a module, the according define has to be set to OPCUA_CONFIG_YES when compiling the SDK. After this step, the chosen module can be set after the UaServer has been initialized:

UaServer_SetUserAuthenticationTypeEx(&g_UaServer, UserAuthType_Internal_Ex, OpcUa_Null);

Additionally, the server’s endpoint has to be configured to accept UserName UserIdentityTokens. If no anonymous logon should be allowed, the Anonymous UserIdentityToken has to be disabled. Following code shows how to enable the UserName logon only:

UaServer_Configuration *pServerConfig = UaServer_GetConfiguration(&g_UaServer);
UaServer_Endpoint *pEndpoint = OpcUa_Null;
pServerConfig->uNoOfEndpoints = 1;
pServerConfig->pEndpoints = OpcUa_Alloc(sizeof(UaServer_Endpoint));
UaServer_Endpoint_Initialize(&pServerConfig->pEndpoints[0]);
pEndpoint = &pServerConfig->pEndpoints[0];
... configure endpoint ...
pEndpoint->uNoOfUserTokenPolicy = 1;
pEndpoint->pUserTokenPolicy = OpcUa_Alloc(pEndpoint->uNoOfUserTokenPolicy * sizeof(OpcUa_UserTokenPolicy));
OpcUa_UserTokenPolicy_Initialize(&pEndpoint->pUserTokenPolicy[0]);
OpcUa_String_StrnCat(&pEndpoint->pUserTokenPolicy[0].PolicyId,
OpcUa_String_FromCString("0"),
OPCUA_STRING_LENDONTCARE);
OpcUa_String_StrnCat(&pEndpoint->pUserTokenPolicy[0].SecurityPolicyUri,
OpcUa_String_FromCString(OpcUa_SecurityPolicy_Basic256Sha256),
OPCUA_STRING_LENDONTCARE);

As an alternative, the UaServer_UserAuthType can be set to UserAuthType_User. Then the third parameter of the UaServer_SetUserAuthenticationTypeEx method expects a pointer to a callback function that handles the authentication.

Modules

Internal Authentication Module

Define: #define UASERVER_SUPPORT_AUTHENTICATION_INTERNAL OPCUA_CONFIG_YES
Enum value: UserAuthType_Internal
Warning
This authentication module is deprecated, as it uses unsalted SHA1 hashes, which are insecure. It is recommended to use the InternalEx authentication module instead.

Using Username and Password

The internal authentication module reads its authentication information from a file that is defined in the uaserver_config.h file, UASERVER_AUTHFILE_PASSWD. This file contains the usernames and the SHA1 hashes of the according passwords.

The following example shows the layout of the file. The first line just denotes the contents of the single columns, it must not appear in the actual file. Also, the UserId and GroupId columns have to contain valid values, even if they are used only in connection with Authorization. The UserId and GroupId are expected to be positive integers, the username can be any string, the SHA1 hash is expected in hexadecimal representation. If the username contains spaces, it has to be enclosed in quotation marks.

<UserId> <GroupId> <UserName> <SHA1 hash of password>
0 0 root e5e9fa1ba31ecd1ae84f75caaa474f3a663f05f4
1 1 anonymous 0000000000000000000000000000000000000000
2 4 joe 21298df8a3277357ee55b01df9530b535cf08ec1
3 5 john 4f26aeafdb2367620a393c973eddbe8f8b846ebd
4 6 sue e122d28c768ab44ceafe00d71adedc80a535cdf1
5 7 "jane doe" da882eab5e403421ac24258a5f7d5f965c29c849

This is a sample configuration. It should never actually be used in a productive system. The passwords of the sample users are:

  • root: secret
  • joe: god
  • john: master
  • sue: curly
  • jane doe: pass word

The sample configuration also contains users ctt_usrT, ctt_ca1I_usrT and ctt_ca1T_usrT necessary for the OPC Foundation compliance test tool. These do not have passwords and are authenticated through user certificates.

Using X509 Certificates

The Internal authentication module can also be used to authenticate users by using X509 certificates. This feature is enabled by default when the Internal authentication module is enabled, only the endpoint has to be configured to allow X509IdentityTokens (TokenType OpcUa_UserTokenType_Certificate).

The folder containing the accepted certificates is set by the define UASERVER_USERCERTS_DIR, the folder for storing certificate revocation lists belonging to the certificates is set by the define UASERVER_USERCRL_DIR.

If authorization is enabled, the “Subject Common Name” is used as user name for looking up the authorization information in the passwd and group file. Hence, in this configuration these files have to exist and be filled with reasonable values. Users ctt_usrT, ctt_ca1I_usrT and ctt_ca1T_usrT included in sample configuration for the OPC Foundation compliance test tool can be used as examples for this.

InternalEx Authentication Module

Define: #define UASERVER_SUPPORT_AUTHENTICATION_INTERNAL_EX OPCUA_CONFIG_YES
Enum value: UserAuthType_Internal_Ex

Using Username and Password

The InternalEx authentication module reads its authentication information from a file that is defined in the uaserver_config.h file, UASERVER_AUTHFILE_PASSWD. This file contains the usernames, hash algorithms, hash iterations, salt values and the hashes of the combination of the salt value and the corresponding password.

The following example shows the layout of the file. The first line just denotes the contents of the single columns, it must not appear in the actual file. Also, the UserId, GroupId and UserName columns have to contain valid values, even if they are used only in connection with Authorization.

  • The UserId and GroupId are expected to be positive integers.
  • The UserName must not contain quotation marks and must be enclosed in quotation marks if it contains spaces.
  • The Algorithm can be one of sha1, sha224, sha256, sha384, sha512, PBKDF2sha1, PBKDF2sha224, PBKDF2sha256, PBKDF2sha384, PBKDF2sha512.
  • Iterations is expected to be a positive integer equal to or larger than 1. For the sha* group of algorithms, this value must be 1. For the PBKDF2* group of algorithms, this is the number of iterations for the PBKDF2 algorithm.
  • Salt can be any string without quotation marks or spaces.
  • The Hash is expected in hexadecimal representation.
Note
The PBKDF2* group of algorithms is only supported for OpenSSL >= 1.1.0
<UserId> <GroupId> <UserName> <Algorithm> <Iterations> <Salt> <Hash of salt and password combined>
0 0 root sha256 1 E1C658D4E8604472846CB2A90832ED1C 9F86858245078AB26EAC5B4EFE902EF54E15C1ABBE18194A971B26263AA43085
1 1 anonymous sha256 1 00000000000000000000000000000000 0000000000000000000000000000000000000000000000000000000000000000
2 4 joe sha256 1 8F54324A2EC6456D82873D7021158447 5045A693BB665A49866235C720F4C96615A0428744C3158069B35229686947E1
3 5 john sha256 1 F3E8BA4E308741C2BCC4EA1B764B1908 466D434BB5BC1B34B65BBAC1D2C1C32ACD9431B958C5E9C698936245F781545D
4 6 sue sha256 1 5D546C33F406407196443F339E2CD780 51F6A6BB3DC40770F22D5C7B8E33BB386A64950197338D81F57EF40DF7C53A9A
5 7 "jane doe" sha256 1 1E12D2F2D5BB46FA8A063CED62BDDBA0 90115E7661E4E9E64682B0F534356F462BB28E00429DA46CB7B757A25F6549E8

This sample configuration is delivered with the UA ANSI C SDK. It should never actually be used in a productive system. The passwords of the sample users are:

  • root: secret
  • joe: god
  • john: master
  • sue: curly
  • jane doe: pass word

The sample configuration also contains users "ctt_usrT", "ctt_ca1I_usrT" and "ctt_ca1T_usrT" necessary for the OPC Foundation compliance test tool. These do not have passwords and are authenticated through user certificates.

New entries in the passwd file can be created as follows:

  1. Write new UserId and GroupId
  2. Write new UserName
    1. sha* group of algorithms:
      1. Choose one of the sha* algorithms and write it in the Algorithm column
      2. The Iterations value must be 1
      3. Generate a random salt value, e.g. by generating a GUID, and write it in the Salt column
      4. Using a SHA generator, create the hash of the combination of salt and password and write it in the Hash column (for the root entry with password secret, salt E1C658D4E8604472846CB2A90832ED1C and algorithm sha256 that would be the sha256 hash of E1C658D4E8604472846CB2A90832ED1Csecret, which is 9F86858245078AB26EAC5B4EFE902EF54E15C1ABBE18194A971B26263AA43085)
    2. PBKDF2* group of algorithms:
      1. Choose one of the PBKDF2* algorithms and write it in the Algorithm column
      2. Choose the number of iterations to use and write it in the Iterations column
      3. Generate a random salt value, e.g. by generating a GUID, and write it in the Salt column
      4. Using a PBKDF2 generator, create the hash of the given salt, password and iterations and write it in the Hash column (for the root entry with password secret, salt E1C658D4E8604472846CB2A90832ED1C, 1000 iterations and algorithm PBKDF2sha256 that would be 9C5345F67BA72A1EBC3ED94E9B21B021D4382E85F62D842C225DAD21B9FCD9FB)

Using X509 Certificates

The InternalEx authentication module can also be used to authenticate users by using X509 certificates. This feature is enabled by default when the InternalEx authentication module is enabled, only the endpoint has to be configured to allow X509IdentityTokens (TokenType OpcUa_UserTokenType_Certificate).

The folder containing the accepted certificates is set by the define UASERVER_USERCERTS_DIR, the folder for storing certificate revocation lists belonging to the certificates is set by the define UASERVER_USERCRL_DIR.

If authorization is enabled, the “Subject Common Name” is used as user name for looking up the authorization information in the passwd and group file. Hence, in this configuration these files have to exist and be filled with reasonable values. Users ctt_usrT, ctt_ca1I_usrT and ctt_ca1T_usrT included in sample configuration for the OPC Foundation compliance test tool can be used as examples for this.

PAM Authentication Module

Define: #define UASERVER_SUPPORT_AUTHENTICATION_PAM OPCUA_CONFIG_YES
Enum value: UserAuthType_PAM

The PAM authentication module uses the PAM library for validating the user’s credentials. The service name passed to the PAM library is “opcua”, so a “/etc/pam.d/opcua” PAM configuration file is expected to be existing. The service name can be changed in the uaserver_auth_pam.c file if necessary. The following shows the content of a sample “opcua” PAM configuration file that uses the shadow mechanism for authentication:

# Install this file to /etc/pam.d/
account required pam_unix2.so nullok
auth required pam_unix2.so nullok

If PAM is configured to use the shadow mechanism, the server has to be running in the context of a user who has read access to the /etc/shadow file.

If this module is used, the application needs to be linked against the “pam” library and the PAM development package has to be installed (usually named “pam-devel”).

More information on PAM can be found under http://www.linux-pam.org/.

Using X509 Certificates

The PAM authentication module can also be used to authenticate users by using X509 certificates. This feature is enabled by default when the PAM authentication module is enabled, only the endpoint has to be configured to allow X509IdentityTokens (TokenType OpcUa_UserTokenType_Certificate).

The folder containing the accepted certificates is set by the define UASERVER_USERCERTS_DIR, the folder for storing certificate revocation lists belonging to the certificates is set by the define UASERVER_USERCRL_DIR.

If authorization is enabled, the "Subject Common Name" is used as user name for looking up the authorization information in the passwd and group file. Hence, in this configuration these files have to exist and be filled with reasonable values. Users ctt_usrT, ctt_ca1I_usrT and ctt_ca1T_usrT included in sample configuration for the OPC Foundation compliance test tool can be used as examples for this.

SASL Authentication Module

Define: #define UASERVER_SUPPORT_AUTHENTICATION_SASL OPCUA_CONFIG_YES
Enum value: UserAuthType_SASL

The SASL authentication module uses the saslauthd daemon on the local machine for validating the user’s credentials. The saslautd daemon is expected to listen on “/var/run/sasl2/mux” for incoming connections, this value can be changed in uaserver_auth_sasl.c if necessary. The service passed to the saslauthd daemon is “imap”, this can also be changed in the same file.

If this module is used, the application needs to be linked against the “sasl2” library and the SASL development package has to be installed (usually named “sasl-devel”).

Using X509 Certificates

The SASL authentication module can also be used to authenticate users by using X509 certificates. This feature is enabled by default when the SASL authentication module is enabled, only the endpoint has to be configured to allow X509IdentityTokens (TokenType OpcUa_UserTokenType_Certificate).

The folder containing the accepted certificates is set by the define UASERVER_USERCERTS_DIR, the folder for storing certificate revocation lists belonging to the certificates is set by the define UASERVER_USERCRL_DIR.

If authorization is enabled, the "Subject Common Name" is used as user name for looking up the authorization information in the passwd and group file. Hence, in this configuration these files have to exist and be filled with reasonable values. Users ctt_usrT, ctt_ca1I_usrT and ctt_ca1T_usrT included in sample configuration for the OPC Foundation compliance test tool can be used as examples for this.

Win32 Authentication Module

Define: #define UASERVER_SUPPORT_AUTHENTICATION_WIN32 OPCUA_CONFIG_YES
Enum value: UserAuthType_Win32

The Win32 authentication module validates the user’s credentials against the windows logon provider. If the user is in a domain, the domain name can be passed together with the user name. There are two notations available that are recognized by the Win32 authentication module:

  • UPN (User Principal Name): UserName@DomainName (e.g. testuser@testdomain.com)
  • Down-Level User Logon Name: DomainName\UserName (e.g. TESTDOMAIN\testuser)

For these notations, username and domain are split at the separator automatically and are passed to the windows logon provider separately.

Using X509 Certificates

The Win32 authentication module can also be used to authenticate users by using X509 certificates. This feature is enabled by default when the Win32 authentication module is enabled, only the endpoint has to be configured to allow X509IdentityTokens (TokenType OpcUa_UserTokenType_Certificate).

The folder containing the accepted certificates is set by the define UASERVER_USERCERTS_DIR, the folder for storing certificate revocation lists belonging to the certificates is set by the define UASERVER_USERCRL_DIR.

If authorization is enabled, the “Subject Common Name” is used as user name for looking up the authorization information in the passwd and group file. Hence, in this configuration these files have to exist and be filled with reasonable values. Users ctt_usrT, ctt_ca1I_usrT and ctt_ca1T_usrT included in sample configuration for the OPC Foundation compliance test tool can be used as examples for this.