This service allows a Remoting client to authenticate a user to the gateway (device) and by this start a security session on behalf of her or him. More...
#include <IPasswordAuthenticationService.hpp>
Public Types | |
| using | Ptr = std::shared_ptr< IPasswordAuthenticationService > |
 Public Types inherited from Arp::System::Rsc::Services::IRscService | |
| typedef std::shared_ptr< IRscService > | Ptr |
Public Member Functions | |
| IPasswordAuthenticationService (void)=default | |
| Constructs an IPasswordAuthenticationService instance. More... | |
| virtual AuthenticationError | CreateSession (const RscString< 64 > &username, const SecureString< 128 > &password, SecurityToken &securityToken, int32 &penaltyDelayMillis)=0 |
| Starts a security context for a particular user or role known at the device. More... | |
| virtual void | CloseSession (SecurityToken securityToken)=0 |
| Terminates a security session which was started at the gateway (device) by a former call to Arp.System.Security.Services.IPasswordAuthenticationService.CreateSession. More... | |
| Public Member Functions inherited from Arp::System::Rsc::Services::IRscService | |
| IRscService (void)=default | |
| Constructs an IRscService instance. More... | |
| virtual | ~IRscService (void)=default |
| Destructs this instance and frees all resouces. More... | |
Static Public Member Functions | |
| static IRscServiceProxyFactory & | GetProxyFactory (void) |
| Static Public Member Functions inherited from Arp::System::Rsc::Services::IRscService | |
| static IRscServiceProxyFactory & | GetProxyFactory (void) |
| Returns a reference to service proxy factory to create a proxy instance of the service More... | |
Detailed Description
This service allows a Remoting client to authenticate a user to the gateway (device) and by this start a security session on behalf of her or him.
With PLCnext Technology authentication happens with usernames. But other kind of devices might not identify individual users but authenticate roles. Thus the
parameters given here in this service interface refer to role names or other kinds of identities then.
- See also
- Arp.System.Security.Services.ISecuritySessionInfoService2
This service is defined in library Arp.System.Security.Services.
Constructor & Destructor Documentation
◆ IPasswordAuthenticationService()
|
default |
Constructs an IPasswordAuthenticationService instance.
Member Function Documentation
◆ CloseSession()
|
pure virtual |
Terminates a security session which was started at the gateway (device) by a former call to Arp.System.Security.Services.IPasswordAuthenticationService.CreateSession.
- Parameters
-
securityToken Security token as formerly returned by a successful settion creation. It identifies the session which shall be closed.
◆ CreateSession()
|
pure virtual |
Starts a security context for a particular user or role known at the device.
Every successful call (see return value) to this method creates a security session for a particular user (or role) at the RSC-gateway (device). Within the same channel a client can create several sessions. Sessions are identified by the securityToken provided by this method. But please check the Ade.CommonRemoting.IRemotingAdapter whether and how it allows to change the securityToken to use within the channel. First versions of this interface requires synchronization, so switching security sessions on a per call basis did not make sense for this because it is rather expensive. The maximum number of concurrent sessions is limited by the gatway's capacitiy (respectively the device's capacity) and therefore clients shall terminate sessions which they do not need any more, Arp.System.Security.Services.IPasswordAuthenticationService.CloseSession. Sessions are automatically terminated whenever the corresponding Remoting channel is closed. Sessions cannot be used across channels.
- Parameters
-
username The name of the role or user or other identity in question.
With PLCnext Technology the name has to be a username, not a role name.
- Parameters
-
password The password which is the proof that the client is allowed to act as the user (or role) specified with username .
If the value is not an arbitrary byte sequence but a human readable text then it shall be encoded as Utf8String.
Please note that the password is sensitive data. The caller must care for keeping it secret. If the method implementation creates copies then it ensures they are erased from memory (i.e. overwritten with zeroes) before destruction and that each copy is destructed at latest when the corresponding security context is closed.
- Parameters
-
securityToken A value identifying the security session. Use it as argument for Ade.CommonRemoting.IRemotingAdapter.Authenticate.
The output value is only valid in case that the method has the return value Arp.System.Security.Services.AuthenticationError.None to indicate success. Then and only then a security session has been created which shall be closed by the client with a call to Arp.System.Security.Services.IPasswordAuthenticationService.CloseSession once it is no longer needed. All security sessions which have been opened by the client during a Remoting connection are automatically closed whenever the Remoting connection is terminated.
The value is intended to be passed to the Remoting sink of the communication channel, in example with every method call. Session context handles shall not be interpreted by the client. The client cannot derive any further meaning from the value. One exception: The value
(zero) is never returned by Arp.System.Security.Services.IPasswordAuthenticationService.CreateSession upon success. The value zero always identifies the default security session which is used when no particular security session has been established yet, in example right after the Remoting channel was established. Thus for safety reasons the out parameter securityToken is set to zero whenever this method indicates an error.
- Parameters
-
penaltyDelayMillis A timespan expressed in milliseconds for which further authentication attempts are rejected.
The value is always 0 unless the method returns Arp.System.Security.Services.AuthenticationError.InvalidCredentials or Arp.System.Security.Services.AuthenticationError.PenaltyDelayActive. Then it is a positive value. A penalty delay is imposed to slow down brute force attacks. The penalty may be valid for a particular user attempting to log in via a particular access path (TCP port, service, ...) or it may be valid for a group or even all users. The timespan is just an indication that subsequent authentication attempts may be rejected during this timespan.
Please note that the accuracy of this value is questionable due to the latency which is introduced with its transmission.
- Returns
- Upon success Arp.System.Security.Services.AuthenticationError.None is returned. Every other value indicates a failure.
The documentation for this class was generated from the following file:
- Arp/System/Security/Services/IPasswordAuthenticationService.hpp
