$Sir Login: Difference between revisions

From m204wiki
Jump to navigation Jump to search
 
(41 intermediate revisions by 9 users not shown)
Line 1: Line 1:
{{DISPLAYTITLE:$Sir_LOgin}}
{{DISPLAYTITLE:$Sir_Login}}
<span class="pageSubtitle"><section begin="desc" />Perform secured web or sockets login<section end="desc" /></span>
<span class="pageSubtitle">Perform secured web or sockets login</span>


==Overview==
==Overview==
<var>$Sir_Login</var> is a $function that can be used to perform user logins.  It is an unusual $function in several respects:


$Sir_Login is a function that can be used to do user logins in <var class="product">Janus Web Server</var> and <var class="product">Janus Sockets</var> applications. Besides the ability to do user logins, it is an unusual $function in several respects:
<ul>
<li>It can only be used during:
<ul>
<li><var class="product">Janus Web Server</var> or <var class="product">Janus Sockets</var> <var>[[NEWSESCMD]]</var> processing </li>


<li> <var>[[VTLAPSY parameter|VTLAPSY]]</VAR> logons from <var>IODEV</var> 7 threads </li>
</ul>
<p>
Any attempt to use <var>$Sir_Login</var> outside of these two instances will result in request cancellation. </p></li>
<li>It can only be invoked by a non-logged in user. Once a user is logged in, a <var>$Sir_Login</var> call will result in request cancellation. </li>
<li>While free to all <var class="product">Janus Web Server</var> and <var class="product">Janus Sockets</var> customers, it is implemented as a pseudo-product that requires its own authorization. This is because some sites might view the mere presence of <var>$Sir_Login</var> as a security risk, so they would not want it available on their systems.
<p>
Therefore, to make <var>$Sir_Login</var> available at a <var class="product">Janus Web Server</var> or <var class="product">Janus Sockets</var> site, the following are necessary: </p>
<ul>
<ul>
<li>It can only be run during <var class="product">Janus Web Server</var> or <var class="product">Janus Sockets</var> <var>[[NEWSESCMD]]</var> processing. Any attempt to use <var>$Sir_Login</var> outside this will result in request cancellation.
<li><var>$Sir_Login</var> must be requested by the site. </li>
<li>It can only be invoked by a non-logged in user. Once a user is logged in, a <var>$Sir_Login</var> call will result in request cancellation
<li>While free to all <var class="product">Janus Web Server</var> and <var class="product">Janus Sockets</var> customers, it is implemented as a pseudo-product that requires its own authorization. This is because some sites might view the mere presence of <var>$Sir_Login</var> as a security risk so would not want
it available on their systems.


So for <var>$Sir_Login</var> to even be made available at a <var class="product">Janus Web Server</var> or <var class="product">Janus Sockets</var> site, it must be requested by the site, and a new authorization ZAP must be applied to the Online load modules, or a new Online load module should be linked from object decks authorized for $Sir_Login.
<li>A new authorization zap must be applied to the Online load modules, or a new Online load module must be linked from object decks authorized for <var>$Sir_Login</var>. </li>
</ul>
</ul>
</ul>
<var>$Sir_Login</var> accepts six arguments and returns a 0 to indicate a successful login or a 1 to indicate login failure.


==Syntax==
==Syntax==
<p class="syntax"><span class="term">%result </span><span class="literal">= $Sir_Login(</span><span class="term">userid, accountid, passwd, newpasswd, options, outlistid</span><span class="literal">)</span>
<p class="syntax"><span class="term">%result </span><span class="literal">= $Sir_Login(</span><span class="term">userid</span>, [<span class="term">accountid</span>], [<span class="term">passwd</span>], [<span class="term">newpasswd</span>], [<span class="term">options</span>], [<span class="term">outlistid</span>]<span class="literal">)</span>
</p>
</p>


<var class="term">%result</var> is set to 0 to indicate successful login or 1 to indicate failure.
===Syntax terms===
<table>
<tr><th>%result</th>
<td>A numerical result: 0 indicates successful login; 1 indicates failure. </td>


$Sir_Login accepts six arguments and returns either a 0 to indicate a successful login or a 1 to indicate login failure.
<tr><th>userid</th>
<td>The user ID for which to attempt a login. This argument is required and must be non-null. At most sites, all <var class="product">Model 204</var> user IDs must be all uppercase, so you might need to call <var>$UPCASE</var> to translate this argument to uppercase. </td></tr>


<tr><th>accountid</th>
<td>The account ID to be used for a successful login. This argument is optional and, if not specified, the account ID is set to the same value as the user ID. Again, it may be appropriate in your environment to call <var>$UPCASE</var> to translate this argument to uppercase. </td></tr>
<tr><th>passwd</th>
<td>The password to be used for user authentication. This is an optional argument; if it is not specified or null, a trusted login is performed: the user ID is verified for validity, and if it is valid, the user is logged in without a password check. Obviously, not specifying this argument or specifying it as null should only be done when the application can be certain that the end-user is authorized to access the user ID.
<p>
No automatic case translation is performed on this argument. If <var>[[CUSTOM parameter#Using CUSTOM=(11)|CUSTOM]]</var> is <b>not</b> set to 11 (allow mixed-case passwords), you must call <var>$UpCase</var> to translate this argument to uppercase. </p>
<p>
Model&nbsp;204 version 7.6 and earlier: Passwords can be as many as 8 characters long. <br />
Model&nbsp;204 version 7.7 and later: Passwords can be as many as 127 characters long and can contain special characters and embedded blanks.  Leading and trailing blanks, however, are stripped. </p></td></tr>
<tr><th>newpasswd</th>
<td>A new password for the user ID. This is an optional argument, and if it is not specified or null, no new password is set on a successful login. If the third argument is null, this argument is ignored. If you want to ensure that the <var class="product">Model&nbsp;204</var> user password is all uppercase, call <var>$UpCase</var> to translate this argument to uppercase.
<ul>
<ul>
<li>The first argument is the userid for which to attempt a login. This argument is required and must be non-null. At least for 3270 users, all <var class="product">Model 204</var> user IDs must be all uppercase, so you may need to call <var>$UPCASE</var> to translate this argument to uppercase.
<li>Model&nbsp;204 version 7.6 and earlier: Passwords can be as many as 8 characters long. </li>
<li>The second argument is the account ID to be used for a successful login. This argument is optional and, if not specified, the account ID is set to the same value as the userid. Again, it may be appropriate in your environment to call <var>$UPCASE</var> to
translate this argument to uppercase.
<li>The third argument is the password to be used for user authentication. This is an optional argument; if it is not specified or null, a trusted login is performed: the userid is verified as a valid userid, and if it is valid, the user is logged in without a
password check. Obviously, not specifying this argument or specifying it as null should only be done when the application can be certain that the end-user is authorized to access the userid. At least for 3270 users, all <var class="product">Model 204</var> user passwords must be all uppercase, so you may need to call <var>$UpCase</var> to translate this argument to uppercase.
<li>The fourth argument is a new password for the userid. This is an optional argument, and if it is not specified or null, no new password is set on a successful login. If the third argument is null, this argument is ignored. If you want to ensure that the <var class="product">Model 204</var> user password is all uppercase, you may need to call <var>$UpCase</var> to translate this argument to uppercase.
<li>The fifth argument is a blank-delimited set of option words. These options can be


<table class="syntaxTable">
<li>Model&nbsp;204 version 7.7 and later: Passwords can be as many as 127 characters long. </li>
<tr><th><var>GUEST</var></th><td>Indicates that the user should be logged on even if the userid in the first <var>$Sir_Login</var> argument is not in CCASTAT or the external authorizer database. A GUEST login is a trusted login, since for such a login the userid is not defined anywhere that would have a password associated with it.
</ul></td></tr>


The <var>[[NEWSESGUESTOK]]</var> parameter must be specified on the Janus port definition if the GUEST option is used with $SIR_LOGIN.
<tr><th>options</th>
</td></tr>
<td>A blank-delimited set of option words. These options can be:


<tr><th><var>NOCHECK</var></th><td>Indicates that the user should be logged in without checking to see if the userid is defined in CCASTAT or the external authorizer database. A NOCHECK login is a trusted login, since for such a login the userid is not looked up anywhere so there's no password to check. NOCHECK is similar to GUEST with the exception that NOCHECK doesn't even bother to do a lookup for the user. This means a NOCHECK login is more efficient than a GUEST login, especially if an external authorizer is being used. The downside is that with a NOCHECK login, the user cannot pick up additional privileges if the userid happens to be defined in CCASTAT or the external authorizer database. Of course this downside might be considered an upside if the userids used in a particular <var>$Sir_Login</var> call are independent of userids in CCASTAT or the external authorizer database.
<table>
<tr><th><var>GUEST</var></th>
<td>Indicates that the user should be logged on even if the user ID in the first <var>$Sir_Login</var> argument is not in CCASTAT or the external authorizer database. A GUEST login is a trusted login, since for such a login the user ID is not defined anywhere that would have a password associated with it.
<p>
The <var>[[NEWSESGUESTOK]]</var> parameter must be specified on the Janus port definition if the GUEST option is used with <var>$Sir_Login</var>.</p></td></tr>


The <var>NEWSESGUESTOK</var> parameter must be specified on the Janus port definition if the <var>NOCHECK</var> option is used with $SIR_LOGIN.
<tr><th><var>NOCHECK</var></th>
</td></tr>
<td>Indicates that the user should be logged in without checking to see if the user ID is defined in CCASTAT or the external authorizer database. A NOCHECK login is a trusted login, since for such a login the user ID is not looked up anywhere so there's no password to check.
<p>
NOCHECK is similar to GUEST with the exception that NOCHECK doesn't even bother to do a lookup for the user. This means a NOCHECK login is more efficient than a GUEST login, especially if an external authorizer is being used. The downside is that with a NOCHECK login, the user cannot pick up additional privileges if the user ID happens to be defined in CCASTAT or the external authorizer database. Of course this downside might be considered an upside if the user IDs used in a particular <var>$Sir_Login</var> call are independent of user IDs in CCASTAT or the external authorizer database.</p>
<p>
The <var>NEWSESGUESTOK</var> parameter must be specified on the Janus port definition if the <var>NOCHECK</var> option is used with <var>$Sir_Login</var>.</p></td></tr>


<tr><th><var>TRUST</var></th><td>Indicates that the userid for which the login is done can do subsequent trusted logins by simply typing LOGON (with no userid) on the <var class="product">Model 204</var> command line.
<tr><th><var>TRUST</var></th>
 
<td>Indicates that the user ID for which the login is done can do subsequent trusted logins by simply typing <code>LOGON</code> (with no user ID) on the <var class="product">Model&nbsp;204</var> command line.
This feature is probably most useful in a development Online where end-users have access to the <var class="product">Model 204</var> command line and might
<p>
want to do a quick logon/logoff sequence to reset everything. Simply being able to type LOGON eliminates the need for re-entering a
This feature is probably most useful in a development Online where end users have access to the <var class="product">Model&nbsp;204</var> command line and might want to do a quick logon/logoff sequence to reset everything. Simply being able to type <code>LOGON</code> eliminates the need for re-entering a
password, so it makes quick logon/logoffs much simpler than it would be otherwise. And since the user already logged on to the thread once, there is no security hole in doing a subsequent trusted login. This parameter is only allowed for applications running on a TNSERV port, and like TNSERV ports, it is only available in Sirius Mods version 6.9 and later.</td></tr>
password, so it makes quick logon/logoffs much simpler than it would be otherwise. And since the user already logged on to the thread once, there is no security hole in doing a subsequent trusted login.</p>
<p>
This parameter is only allowed for applications running on a TNSERV port.</p></td></tr>
</table>
</table>
</td></tr>


<li>The sixth argument is the $list identifier of a $list to receive any terminal messages
<tr><th>outlistid</th>
issued during the login process. These could be error messages during a failed
<td>The sixth argument is the $list identifier of a $list to receive any terminal messages issued during the login process. These could be error messages during a failed login or information messages issued for a successful login. This is an optional parameter; if it is not specified, messages get sent to the standard output drivers, which could:
login or information messages issued for a successful login. This is an optional
parameter; if it is not specified, messages get sent to the standard output drivers,
which could:
<ul>
<ul>
<li>In a <var class="product">Janus Web Server</var> <var>$Sir_Login</var>, send the output to the browser or the audit trail, or simply swallow it.
<li>In a <var class="product">[[Janus Web Server]]</var> <var>$Sir_Login</var>, send the output to the browser or the audit trail, or simply swallow it.</li>
<li>In a <var class="product">Janus Sockets</var> <var>$Sir_Login</var>, send the output to the audit trail or to one or more open sockets.
<li>In either a <var class="product">Janus Web Server</var> or a <var class="product">Janus Sockets</var> <var>$Sir_Login</var>, capture terminal output to a $list via $LIST_CAPTURE.


If <var>$Sir_Login</var> is invoked with an output $list, the X'06' bits of the <var class="product">Model 204</var> MSGCTL user parameter are automatically cleared, then restored upon completion of <var>$Sir_Login</var> processing. This ensures that logon messages are sent to the &amp;amp;amp;amp;amp;#x201C;terminal&amp;amp;amp;amp;amp;#x201D; and so the output $list, no matter what the current MSGCTL setting is. APSY subsystems that suppress messages do so by setting one or both of the MSGCTL X'06' bits. $LIST_CAPTURE does not affect the MSGCTL setting. For more information about $lists, see the Sirius Functions Reference Manual.
<li>In a <var class="product">[[Janus Sockets]]</var> <var>$Sir_Login</var>, send the output to the audit trail or to one or more open sockets.</li>
</ul>
</ul>


Any errors in the arguments such as a null or too-long userid, a too-long password, or an invalid $list identifier cause request cancellation.
<li>In a <var class="product">Janus Web Server</var> or a <var class="product">Janus Sockets</var> <var>$Sir_Login</var>, capture terminal output to a $list via <var>[[$List_Capture]]</var>.
<p>
If <var>$Sir_Login</var> is invoked with an output [[$lists|$list]], the X'06' bits of the <var class="product">Model&nbsp;204</var> <var>[[MSGCTL parameter|MSGCTL]]</var> user parameter are automatically cleared, then restored upon completion of <var>$Sir_Login</var> processing. This ensures that logon messages are sent to the "terminal" and so the output $list, no matter what the current <var>MSGCTL</var> setting is. APSY subsystems that suppress messages do so by setting one or both of the <var>MSGCTL</var> X'06' bits. <var>$List_Capture</var> does not affect the <var>MSGCTL</var> setting. </p></li>
</ul></td></tr>
</table>


==Usage Notes and Examples==
Any errors in the arguments such as a null or too-long user ID, a too-long password, or an invalid $list identifier cause request cancellation.


<strong>Note:</strong> It cannot be overemphasized that before <var>$Sir_Login</var> is called, the password should be checked for a null value, unless the intent is to do a trusted login. Without such a check, unauthorized users can log in to an ID without that ID's password.
==Usage notes and examples==
<p class="note"><strong>Note:</strong> It cannot be overemphasized that before <var>$Sir_Login</var> is called, the password should be checked for a null value, unless the intent is to do a trusted login. Without such a check, unauthorized users can log in to an ID without that ID's password. </p>


===Trusted Login===
===Trusted Login===
Trusted logins should be limited to cases where you are certain that the correct userid can be ascertained without the use of a password. In general, this can only really be done with TCP/IP with the use of certificates, though there might be cases where network and operating system configuration allows you to be certain that a userid that is passed over a connection is valid and trustworthy without a password.
Trusted logins should be limited to cases where you are certain that the correct userid can be ascertained without the use of a password. In general, this can only really be done with TCP/IP with the use of certificates, though there might be cases where network and operating system configuration allows you to be certain that a userid that is passed over a connection is valid and trustworthy without a password.


Line 77: Line 110:


===Protected Access and External Authorizers===
===Protected Access and External Authorizers===
One simple way to use certificates for login validation is by having a local certifying authority that gives users certificates that contain their user IDs. A connection from a client that contains a certificate signed by that certifying authority can then simply do a trusted login for the user ID passed in the common name portion of the certificate, on the theory that only the user in the certificate would have access to the signed certificate.


One simple way to use certificates for login validation is by having a local certifying authority that gives users certificates that contain their userids. A connection from a client that contains a certificate signed by that certifying authority can them simply do a trusted login for the userid passed in the common name portion of the certificate, on the theory that only the user in the certificate would have access to the signed certificate.
The following is a fragment of code from a <var class="product">Janus Web Server</var> <var>NEWSESCMD</var> request that illustrates this technique:
 
The following is a fragment of code from a <var class="product">Janus Web Server</var> NEWSESCMD request that illustrates this technique:


<p class="code"> IF $WEB_CERT_INFO('CNAME', 1) EQ 'Trusted CA' THEN
<p class="code"> IF $WEB_CERT_INFO('CNAME', 1) EQ 'Trusted CA' THEN
Line 91: Line 123:
</p>
</p>


A <var class="product">Janus Sockets</var> server NEWSESCMD request that accomplishes the same thing is virtually identical (whether using a $function, as below, or using a comparable Socket object method):
A <var class="product">Janus Sockets</var> server <var>NEWSESCMD</var> request that accomplishes the same thing is virtually identical (whether using a $function, as below, or using a comparable Socket object method):


<p class="code"> IF $SOCK_CERT_INFO(1, 'CNAME', 1) EQ 'Trusted CA' THEN
<p class="code"> IF $SOCK_CERT_INFO(1, 'CNAME', 1) EQ 'Trusted CA' THEN
Line 109: Line 141:
</ul>
</ul>


More sophisticated and complex approaches to client-certificate based user validation can be implemented using the same few $functions or object methods. For example, rather than using the common name in a certificate directly as a userid, the common name could be mapped to a userid via a database lookup:
More sophisticated and complex approaches to client-certificate based user validation can be implemented using the same few $functions or object methods. For example, rather than using the common name in a certificate directly as a user ID, the common name could be mapped to a user ID by a database lookup:


<p class="code"> IF $WEB_CERT_INFO('CNAME', 1) EQ 'Trusted CA' THEN
<p class="code"> IF $WEB_CERT_INFO('CNAME', 1) EQ 'Trusted CA' THEN
Line 124: Line 156:
</p>
</p>


An even more sophisticated NEWSESCMD application could itself maintain the USERS file that contains say a common name, MD5 certificate hash and a <var class="product">Model 204</var> userid associated with the certificate. When a certificate is received, the common name and MD5 hash can be looked up in the database:
An even more sophisticated <var>NEWSESCMD</var> application could itself maintain the USERS file that contains, for example, a common name, MD5 certificate hash and a <var class="product">Model&nbsp;204</var> user ID associated with the certificate. When a certificate is received, the common name and MD5 hash can be looked up in the database:


<p class="code">  %CNAME = $WEB_CERT_INFO('CNAME')
<p class="code">  %CNAME = $WEB_CERT_INFO('CNAME')
Line 141: Line 173:
</p>
</p>


If the received certificate is not in the database, the userid and password could be obtained from HTTP headers and could be used for a logon attempt with a password. If the login fails or no userid and password were received a "401 Unauthorized" response can be sent to the client to get a userid and password:
If the received certificate is not in the database, the user ID and password could be obtained from HTTP headers and could be used for a logon attempt with a password. If the login fails or no user ID and password were received a "401 Unauthorized" response can be sent to the client to get a user ID and password:


<p class="code"> %USERID = $WEB_USER
<p class="code"> %USERID = $WEB_USER
Line 156: Line 188:
</p>
</p>


<var>[[$Web_Password]]</var>, like <var>$Sir_Login</var>, causes request cancellation if used outside of NEWSESCMD processing.
<var>[[$Web_Password]]</var>, like <var>$Sir_Login</var>, causes request cancellation if used outside of <var>NEWSESCMD</var> processing.


Finally, a successful login for a specific userid and password suggests that userid is the holder of the indicated certificate, so the certificate information can be saved in the USERS database for subsequent trusted logins:
Finally, a successful login for a specific user ID and password suggests that user ID is the holder of the indicated certificate, so the certificate information can be saved in the USERS database for subsequent trusted logins:


<p class="code">SUCCESS:
<p class="code">SUCCESS:
Line 171: Line 203:
Note that in the preceding example, it does not matter which certifying authority signed the user's certificate, as long as it was a certifying authority added to the port via the <var>[[JANUS ADDCA]]</var> command.
Note that in the preceding example, it does not matter which certifying authority signed the user's certificate, as long as it was a certifying authority added to the port via the <var>[[JANUS ADDCA]]</var> command.


A similar technique can be used with <var class="product">Janus Sockets</var>, though, of course, when a certificate is not in the database, the userid and password need to be extracted in some way other than via $WEB_USER and $WEB_PASS. The appropriate technique would largely depend on the protocol being used over TCP/IP.
A similar technique can be used with <var class="product">Janus Sockets</var>, though, of course, when a certificate is not in the database, the user ID and password need to be extracted in some way other than via <var>$Web_User</var> and <var>$Web_Pass</var>. The appropriate technique would largely depend on the protocol being used over TCP/IP.


===Telnet Example===
===Telnet Example===
 
The following illustrates how a user ID and password can be obtained from a user when using the telnet protocol over a <var class="product">Janus Sockets</var> connection:
The following illustrates how a userid and password can be obtained from a user when using the telnet protocol over a <var class="product">Janus Sockets</var> connection:


<p class="code">  REPEAT FOREVER
<p class="code">  REPEAT FOREVER
Line 200: Line 231:
</p>
</p>


Again, this kind of approach can be combined with a certificate-based approach where, if a received certificate is in the database, no userid and password prompting is done, and a trusted login is performed.
Again, this kind of approach can be combined with a certificate-based approach where, if a received certificate is in the database, no user ID and password prompting is done, and a trusted login is performed.


===Proxy Servers===
===Proxy Servers===
Another use of <var>$Sir_Login</var> might be a case where all user validation is performed by a proxy server at a well known IP address. The network and proxy server machine are securely configured in such a way that, if <var class="product">Janus Web Server</var> receives a request from a specific IP address, it can be certain of these:
Another use of <var>$Sir_Login</var> might be a case where all user validation is performed by a proxy server at a well known IP address. The network and proxy server machine are securely configured in such a way that, if <var class="product">Janus Web Server</var> receives a request from a specific IP address, it can be certain of these:


Line 211: Line 241:
</ul>
</ul>


Finally, the proxy server in question is known to place the validated userid into a nonstandard HTTP header parameter called "Userid". The following illustrates how a trusted login can be performed in such a situation:
Finally, the proxy server in question is known to place the validated user ID into a nonstandard HTTP header parameter called "Userid". The following illustrates how a trusted login can be performed in such a situation:


<p class="code"> IF $WEB_IPADDR EQ %PROXY_IPADDR THEN
<p class="code"> IF $WEB_IPADDR EQ %PROXY_IPADDR THEN
Line 223: Line 253:
</p>
</p>


In this example, the <var>$Sir_Login</var> will still fail if the userid received from the proxy server is defined neither with the external authorizer nor in CCASTAT. If, as is likely, it is undesirable to try to maintain the user lists in both the proxy server and in the external authorizer or CCASTAT, a guest login can be performed with <var>$Sir_Login</var>:
In this example, the <var>$Sir_Login</var> will still fail if the user ID received from the proxy server is defined neither with the external authorizer nor in CCASTAT. If, as is likely, it is undesirable to try to maintain the user lists in both the proxy server and in the external authorizer or CCASTAT, a guest login can be performed with <var>$Sir_Login</var>:


<p class="code"> IF $WEB_IPADDR EQ %PROXY_IPADDR THEN
<p class="code"> IF $WEB_IPADDR EQ %PROXY_IPADDR THEN
Line 235: Line 265:
</p>
</p>


In this case, the user will pick up default user privileges for the Online but will run under the userid passed by the proxy server, even when the user is not defined in CCASTAT or to the external authorizer. This can be very useful for user tracking and auditing and for web-rule-based or APSY-based user access control.
In this case, the user will pick up default user privileges for the Online but will run under the user ID passed by the proxy server, even when the user is not defined in CCASTAT or to the external authorizer. This can be very useful for user tracking and auditing and for web-rule-based or APSY-based user access control.


If there are web-based DBA or system manager applications out there that one would not expect to be accessed through the proxy server, it might be worth making sure that the proxy server did not pass the userid of a DBA or system manager who might have access to these critical applications:
If there are web-based DBA or system manager applications out there that one would not expect to be accessed through the proxy server, it might be worth making sure that the proxy server did not pass the user ID of a DBA or system manager who might have access to these critical applications:


<p class="code"> IF $WEB_IPADDR EQ %PROXY_IPADDR THEN
<p class="code"> IF $WEB_IPADDR EQ %PROXY_IPADDR THEN
Line 249: Line 279:
</p>
</p>


The combination of <var>$Sir_Login</var> and NEWSESCMD processing provides a very flexible set of facilities that allows a site to tailor <var class="product">Janus Web Server</var> and <var class="product">Janus Sockets</var> user authentication as needed. With that flexibility comes the responsibility to ensure that the chosen user authentication approach is, indeed, secure. Toward this end, it is strongly recommended that NEWSESCMD code be examined by as many eyes as is reasonable, and that Sirius Software be contacted to review NEWSESCMD code.
The combination of <var>$Sir_Login</var> and <var>NEWSESCMD</var> processing provides a very flexible set of facilities that allows a site to tailor <var class="product">Janus Web Server</var> and <var class="product">Janus Sockets</var> user authentication as needed. With that flexibility comes the responsibility to ensure that the chosen user authentication approach is, indeed, secure. Toward this end, it is strongly recommended that <var>NEWSESCMD</var> code be examined by as many eyes as is reasonable, and that Rocket Software be contacted to review <var>NEWSESCMD</var> code.


==Sample APSY==
==Sample APSY==


A sample APSY subsystem that can be used with the <var>NEWSESCMD</var> subcommand is provided by Sirius Software (it is the same sample subsystem provided for use with the <var>[[VTLAPSY parameter|VTLAPSY]]</var> parameter for IODEV7 users). The code is in the SIRIUS file, beginning with <var class="product">[[UL/SPF]]</var> Version 7.7.  Programs are VTLN.LOGIN and VTLN.ERROR, and the comments in VTLN.LOGIN explain how to customize the programs for the local environment.
A sample APSY subsystem that can be used with the <var>NEWSESCMD</var> subcommand is provided by Rocket Software (it is the same sample subsystem provided for use with the <var>[[VTLAPSY parameter|VTLAPSY]]</var> parameter for IODEV7 users). The code is in the SIRIUS file, beginning with <var class="product">[[ULSPF|UL/SPF]]</var> Version 7.7.  Programs are VTLN.LOGIN and VTLN.ERROR, and the comments in VTLN.LOGIN explain how to customize the programs for the local environment.


[[Category:Janus Web Server $functions|$Sir_Login]]
[[Category:Janus Web Server $functions|$Sir_Login]]
[[Category:$Functions|$Sir_Login]]
[[Category:$Functions|$Sir_Login]]
[[Category:Janus Web Server|$Sir_Login]]
[[Category:Janus Sockets|$Sir_Login]]

Latest revision as of 06:14, 30 May 2018

Perform secured web or sockets login

Overview

$Sir_Login is a $function that can be used to perform user logins. It is an unusual $function in several respects:

  • It can only be used during:
    • Janus Web Server or Janus Sockets NEWSESCMD processing
    • VTLAPSY logons from IODEV 7 threads

    Any attempt to use $Sir_Login outside of these two instances will result in request cancellation.

  • It can only be invoked by a non-logged in user. Once a user is logged in, a $Sir_Login call will result in request cancellation.
  • While free to all Janus Web Server and Janus Sockets customers, it is implemented as a pseudo-product that requires its own authorization. This is because some sites might view the mere presence of $Sir_Login as a security risk, so they would not want it available on their systems.

    Therefore, to make $Sir_Login available at a Janus Web Server or Janus Sockets site, the following are necessary:

    • $Sir_Login must be requested by the site.
    • A new authorization zap must be applied to the Online load modules, or a new Online load module must be linked from object decks authorized for $Sir_Login.

$Sir_Login accepts six arguments and returns a 0 to indicate a successful login or a 1 to indicate login failure.

Syntax

%result = $Sir_Login(userid, [accountid], [passwd], [newpasswd], [options], [outlistid])

Syntax terms

%result A numerical result: 0 indicates successful login; 1 indicates failure.
userid The user ID for which to attempt a login. This argument is required and must be non-null. At most sites, all Model 204 user IDs must be all uppercase, so you might need to call $UPCASE to translate this argument to uppercase.
accountid The account ID to be used for a successful login. This argument is optional and, if not specified, the account ID is set to the same value as the user ID. Again, it may be appropriate in your environment to call $UPCASE to translate this argument to uppercase.
passwd The password to be used for user authentication. This is an optional argument; if it is not specified or null, a trusted login is performed: the user ID is verified for validity, and if it is valid, the user is logged in without a password check. Obviously, not specifying this argument or specifying it as null should only be done when the application can be certain that the end-user is authorized to access the user ID.

No automatic case translation is performed on this argument. If CUSTOM is not set to 11 (allow mixed-case passwords), you must call $UpCase to translate this argument to uppercase.

Model 204 version 7.6 and earlier: Passwords can be as many as 8 characters long.
Model 204 version 7.7 and later: Passwords can be as many as 127 characters long and can contain special characters and embedded blanks. Leading and trailing blanks, however, are stripped.

newpasswd A new password for the user ID. This is an optional argument, and if it is not specified or null, no new password is set on a successful login. If the third argument is null, this argument is ignored. If you want to ensure that the Model 204 user password is all uppercase, call $UpCase to translate this argument to uppercase.
  • Model 204 version 7.6 and earlier: Passwords can be as many as 8 characters long.
  • Model 204 version 7.7 and later: Passwords can be as many as 127 characters long.
options A blank-delimited set of option words. These options can be:
GUEST Indicates that the user should be logged on even if the user ID in the first $Sir_Login argument is not in CCASTAT or the external authorizer database. A GUEST login is a trusted login, since for such a login the user ID is not defined anywhere that would have a password associated with it.

The NEWSESGUESTOK parameter must be specified on the Janus port definition if the GUEST option is used with $Sir_Login.

NOCHECK Indicates that the user should be logged in without checking to see if the user ID is defined in CCASTAT or the external authorizer database. A NOCHECK login is a trusted login, since for such a login the user ID is not looked up anywhere so there's no password to check.

NOCHECK is similar to GUEST with the exception that NOCHECK doesn't even bother to do a lookup for the user. This means a NOCHECK login is more efficient than a GUEST login, especially if an external authorizer is being used. The downside is that with a NOCHECK login, the user cannot pick up additional privileges if the user ID happens to be defined in CCASTAT or the external authorizer database. Of course this downside might be considered an upside if the user IDs used in a particular $Sir_Login call are independent of user IDs in CCASTAT or the external authorizer database.

The NEWSESGUESTOK parameter must be specified on the Janus port definition if the NOCHECK option is used with $Sir_Login.

TRUST Indicates that the user ID for which the login is done can do subsequent trusted logins by simply typing LOGON (with no user ID) on the Model 204 command line.

This feature is probably most useful in a development Online where end users have access to the Model 204 command line and might want to do a quick logon/logoff sequence to reset everything. Simply being able to type LOGON eliminates the need for re-entering a password, so it makes quick logon/logoffs much simpler than it would be otherwise. And since the user already logged on to the thread once, there is no security hole in doing a subsequent trusted login.

This parameter is only allowed for applications running on a TNSERV port.

outlistid The sixth argument is the $list identifier of a $list to receive any terminal messages issued during the login process. These could be error messages during a failed login or information messages issued for a successful login. This is an optional parameter; if it is not specified, messages get sent to the standard output drivers, which could:
  • In a Janus Web Server $Sir_Login, send the output to the browser or the audit trail, or simply swallow it.
  • In a Janus Sockets $Sir_Login, send the output to the audit trail or to one or more open sockets.
  • In a Janus Web Server or a Janus Sockets $Sir_Login, capture terminal output to a $list via $List_Capture.

    If $Sir_Login is invoked with an output $list, the X'06' bits of the Model 204 MSGCTL user parameter are automatically cleared, then restored upon completion of $Sir_Login processing. This ensures that logon messages are sent to the "terminal" and so the output $list, no matter what the current MSGCTL setting is. APSY subsystems that suppress messages do so by setting one or both of the MSGCTL X'06' bits. $List_Capture does not affect the MSGCTL setting.

Any errors in the arguments such as a null or too-long user ID, a too-long password, or an invalid $list identifier cause request cancellation.

Usage notes and examples

Note: It cannot be overemphasized that before $Sir_Login is called, the password should be checked for a null value, unless the intent is to do a trusted login. Without such a check, unauthorized users can log in to an ID without that ID's password.

Trusted Login

Trusted logins should be limited to cases where you are certain that the correct userid can be ascertained without the use of a password. In general, this can only really be done with TCP/IP with the use of certificates, though there might be cases where network and operating system configuration allows you to be certain that a userid that is passed over a connection is valid and trustworthy without a password.

Another case where trusted logins might be reasonable is when a password is retrieved from a connection, and the password is validated against a non-CCASTAT, non-external authorizer database. This database could be a Model 204 file that contains one-way encrypted passwords (saving unencrypted passwords is a very bad idea), or perhaps a database on another machine, such as an LDAP server which is queried via a Janus Sockets client request.

Protected Access and External Authorizers

One simple way to use certificates for login validation is by having a local certifying authority that gives users certificates that contain their user IDs. A connection from a client that contains a certificate signed by that certifying authority can then simply do a trusted login for the user ID passed in the common name portion of the certificate, on the theory that only the user in the certificate would have access to the signed certificate.

The following is a fragment of code from a Janus Web Server NEWSESCMD request that illustrates this technique:

IF $WEB_CERT_INFO('CNAME', 1) EQ 'Trusted CA' THEN %USERID = $WEB_CERT_INFO('CNAME') %RC = $Sir_Login(%USERID) IF NOT %RC THEN STOP END IF ...

A Janus Sockets server NEWSESCMD request that accomplishes the same thing is virtually identical (whether using a $function, as below, or using a comparable Socket object method):

IF $SOCK_CERT_INFO(1, 'CNAME', 1) EQ 'Trusted CA' THEN %USERID = $SOCK_CERT_INFO(1, 'CNAME') %RC = $Sir_Login(%USERID) IF NOT %RC THEN STOP END IF ....

Both these examples depend on the following:

  • A trusted certifying authority certificate with a common name of "Trusted CA" must be added to the appropriate port with the JANUS ADDCA command.
  • Only a single trusted CA with the indicated common name must exist. While it's unlikely that one would have trusted CA certificates for multiple certifying authorities with the same common name, this issue should still be kept in mind.

More sophisticated and complex approaches to client-certificate based user validation can be implemented using the same few $functions or object methods. For example, rather than using the common name in a certificate directly as a user ID, the common name could be mapped to a user ID by a database lookup:

IF $WEB_CERT_INFO('CNAME', 1) EQ 'Trusted CA' THEN %CNAME = $WEB_CERT_INFO('CNAME') F: IN FILE USERS FD CNAME EQ %CNAME END FIND FOR 1 RECORD IN F %RC = $Sir_Login(USERID) IF NOT %RC THEN STOP END IF . . . .

An even more sophisticated NEWSESCMD application could itself maintain the USERS file that contains, for example, a common name, MD5 certificate hash and a Model 204 user ID associated with the certificate. When a certificate is received, the common name and MD5 hash can be looked up in the database:

%CNAME = $WEB_CERT_INFO('CNAME') %MD5HASH = $WEB_CERT_INFO('MD5HASH') F: IN FILE USERS FD CNAME EQ %CNAME MD5HASH EQ %MD5HASH END FIND FOR 1 RECORD IN F %RC = $Sir_Login(USERID) IF NOT %RC THEN STOP END IF END FOR . . . .

If the received certificate is not in the database, the user ID and password could be obtained from HTTP headers and could be used for a logon attempt with a password. If the login fails or no user ID and password were received a "401 Unauthorized" response can be sent to the client to get a user ID and password:

%USERID = $WEB_USER %PASSWORD = $WEB_PASSWORD IF %USERID NE '' AND %PASSWORD NE '' THEN %RC = $Sir_Login(%USERID, %PASSWORD) IF NOT %RC THEN JUMP TO SUCCESS END IF END IF %RC = $WEB_DONE(401, 'Unauthorized') STOP . . . .

$Web_Password, like $Sir_Login, causes request cancellation if used outside of NEWSESCMD processing.

Finally, a successful login for a specific user ID and password suggests that user ID is the holder of the indicated certificate, so the certificate information can be saved in the USERS database for subsequent trusted logins:

SUCCESS: IN FILE USERS STORE RECORD CNAME = %CNAME MD5HASH = %MD5HASH USERID = %USERID END STORE STOP

Note that in the preceding example, it does not matter which certifying authority signed the user's certificate, as long as it was a certifying authority added to the port via the JANUS ADDCA command.

A similar technique can be used with Janus Sockets, though, of course, when a certificate is not in the database, the user ID and password need to be extracted in some way other than via $Web_User and $Web_Pass. The appropriate technique would largely depend on the protocol being used over TCP/IP.

Telnet Example

The following illustrates how a user ID and password can be obtained from a user when using the telnet protocol over a Janus Sockets connection:

REPEAT FOREVER %RC = $SOCK_SEND(1, 'Userid: ') %RC = $SOCK_RECVPRS(1, %DATA, 9999999) %USERID = $UPCASE(%DATA) IF %USERID NE '' THEN %RC = $SOCK_SEND(1, 'Password: ') %RC = $SOCK_RECVPRS(1, %DATA, 9999999) %PASSWORD = $UPCASE(%DATA) END IF IF %PASSWORD NE '' THEN %LIST = $LISTNEW %LOGIN = $Sir_Login(%USERID, ,%PASSWORD, , ,%LIST) FOR %I FROM 1 TO $LISTCNT(%LIST) %RC = $SOCK_SENDLN(1, $LISTINF(%LIST, %I)) END FOR IF NOT %LOGIN THEN LOOP END END IF END IF %RC = $SOCK_SENDLN(1, 'Login failed') END REPEAT

Again, this kind of approach can be combined with a certificate-based approach where, if a received certificate is in the database, no user ID and password prompting is done, and a trusted login is performed.

Proxy Servers

Another use of $Sir_Login might be a case where all user validation is performed by a proxy server at a well known IP address. The network and proxy server machine are securely configured in such a way that, if Janus Web Server receives a request from a specific IP address, it can be certain of these:

  • The request is coming from the proxy server.
  • The proxy server has performed appropriate user validation for the request.

Finally, the proxy server in question is known to place the validated user ID into a nonstandard HTTP header parameter called "Userid". The following illustrates how a trusted login can be performed in such a situation:

IF $WEB_IPADDR EQ %PROXY_IPADDR THEN %USERID = $UPCASE($WEB_HDR_PARM('USERID')) IF %USERID NE '' THEN %RC = $Sir_Login(%USERID) IF NOT %RC THEN STOP END IF . . . .

In this example, the $Sir_Login will still fail if the user ID received from the proxy server is defined neither with the external authorizer nor in CCASTAT. If, as is likely, it is undesirable to try to maintain the user lists in both the proxy server and in the external authorizer or CCASTAT, a guest login can be performed with $Sir_Login:

IF $WEB_IPADDR EQ %PROXY_IPADDR THEN %USERID = $UPCASE($WEB_HDR_PARM('USERID')) IF %USERID NE '' THEN %RC = $Sir_Login(%USERID, , , , 'GUEST') IF NOT %RC THEN STOP END IF . . . .

In this case, the user will pick up default user privileges for the Online but will run under the user ID passed by the proxy server, even when the user is not defined in CCASTAT or to the external authorizer. This can be very useful for user tracking and auditing and for web-rule-based or APSY-based user access control.

If there are web-based DBA or system manager applications out there that one would not expect to be accessed through the proxy server, it might be worth making sure that the proxy server did not pass the user ID of a DBA or system manager who might have access to these critical applications:

IF $WEB_IPADDR EQ %PROXY_IPADDR THEN %USERID = $UPCASE($WEB_HDR_PARM('USERID')) IF $WINDEX('DBA SUPERKLUGE ZEUS', %USERID) THEN AUDIT 'Received userid ' %USERID 'from proxy server' %RC = $WEB_DONE(403, 'Forbidden') STOP END IF . . . .

The combination of $Sir_Login and NEWSESCMD processing provides a very flexible set of facilities that allows a site to tailor Janus Web Server and Janus Sockets user authentication as needed. With that flexibility comes the responsibility to ensure that the chosen user authentication approach is, indeed, secure. Toward this end, it is strongly recommended that NEWSESCMD code be examined by as many eyes as is reasonable, and that Rocket Software be contacted to review NEWSESCMD code.

Sample APSY

A sample APSY subsystem that can be used with the NEWSESCMD subcommand is provided by Rocket Software (it is the same sample subsystem provided for use with the VTLAPSY parameter for IODEV7 users). The code is in the SIRIUS file, beginning with UL/SPF Version 7.7. Programs are VTLN.LOGIN and VTLN.ERROR, and the comments in VTLN.LOGIN explain how to customize the programs for the local environment.