1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
|
<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
-
- This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
- project.
-
- Copyright (C) 1998-2018 OpenLink Software
-
- This project is free software; you can redistribute it and/or modify it
- under the terms of the GNU General Public License as published by the
- Free Software Foundation; only version 2 of the License, dated June 1991.
-
- This program is distributed in the hope that it will be useful, but
- WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
- General Public License for more details.
-
- You should have received a copy of the GNU General Public License along
- with this program; if not, write to the Free Software Foundation, Inc.,
- 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
-
-
-->
<refentry id="fn_vsp_calculate_digest">
<refmeta>
<refentrytitle>vsp_calculate_digest</refentrytitle>
<refmiscinfo>ws</refmiscinfo>
</refmeta>
<refnamediv>
<refname>vsp_calculate_digest</refname>
<refpurpose>calculate on server-side a digest to perform a HTTP digest authentication</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis id="fsyn_vsp_calculate_digest">
<funcprototype id="fproto_vsp_calculate_digest">
<funcdef><function>vsp_calculate_digest</function></funcdef>
<paramdef>in <parameter>username</parameter> varchar</paramdef>
<paramdef>in <parameter>password</parameter> varchar</paramdef>
<paramdef>in <parameter>credentials</parameter> any</paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="desc_vsp_calculate_digest"><title>Description</title>
<para>The vsp_calculate_digest() function is used to calculate on server-side a digest to perform a
HTTP digest authentication. When the authentication type is 'digest' the function will return a md5
checksum based on credentials, user name and password. The checksum calculation will be made as required
for HTTP Digest authentication to compare against 'response' element of credentials. If the authentication
is basic a NULL will be returned.
</para>
</refsect1>
<refsect1 id="params_vsp_calculate_digest"><title>Parameters</title>
<refsect2><title>username</title>
<para>A string with name of the user account name
</para>
</refsect2>
<refsect2><title>password</title>
<para>A string with a plain text password from the users table (can be from external LDAP server etc.)
</para>
</refsect2>
<refsect2><title>credentials</title>
<para>
A vector of name/value pairs (the keyword and value are strings) of:
</para>
<table><title>Valid values</title>
<tgroup cols="2">
<thead><row><entry>Name</entry><entry>Description</entry></row></thead>
<tbody>
<row> <entry>authtype</entry> <entry>'digest' or 'basic'</entry> </row>
<row> <entry>realm</entry> <entry>from HTTP Authorization request header</entry> </row>
<row> <entry>method</entry> <entry>from HTTP request line</entry> </row>
<row> <entry>uri</entry> <entry>from HTTP Authorization request header</entry> </row>
<row> <entry>nonce</entry> <entry>from HTTP Authorization request header</entry> </row>
<row> <entry>nc</entry> <entry>from HTTP Authorization request header</entry> </row>
<row> <entry>cnonce</entry> <entry>from HTTP Authorization request header</entry> </row>
<row> <entry>qop</entry> <entry>from HTTP Authorization request header</entry> </row>
<row> <entry>response</entry> <entry>the client-side calculated digest</entry> </row>
</tbody>
</tgroup>
</table>
</refsect2>
</refsect1>
<refsect1 id="ret_vsp_calculate_digest"><title>Return Types</title><para>
A string containing md5 digest, if 'authtype' option is 'digest'. Otherwise returns null.
</para></refsect1>
<!--refsect1 id="errors_vsp_calculate_digest"><title>Errors</title>
<table><title>Errors signalled by</title>
<tgroup cols="4">
<thead><row><entry>SQLState</entry><entry>Error Code</entry><entry>Error Text</entry><entry>Description</entry></row></thead>
<tbody>
<row>
<entry><errorcode></errorcode></entry>
<entry><errorcode></errorcode></entry>
<entry><errorname></errorname></entry>
<entry></entry>
</row>
</tbody>
</tgroup>
</table>
</refsect1-->
<refsect1 id="examples_vsp_calculate_digest"><title>Examples</title>
<example id="ex_vsp_calculate_digest"><title>A VSP page performing digest authentication</title>
<para>The following page check for digest authentication and returns OK if authentication succeeds,
otherwise it asks for authentication again.
</para>
<programlisting><![CDATA[
<?vsp
declare auth any;
declare cs varchar;
auth := app_auth_vec (lines);
if (not isarray (auth))
app_get_auth ();
cs := vsp_calculate_digest ('u1', 'secret', auth);
if (cs is not null and cs = get_keyword ('response',auth))
http ('OK');
else
app_get_auth ();
?>
-- making the HTTP Digest authentication header
create procedure app_get_auth ()
{
http_request_status ('HTTP/1.1 401 Unauthorized');
http_header (sprintf ('WWW-Authenticate: Digest realm="%s", domain="%s", nonce="%s", opaque="%s", stale="%s", qop="auth", algorithm="MD5"\r\n', 'my_realm', http_path(), md5 (datestring (now ())), md5 ('some string for hash'), 'false'));
};
-- returns an array suitable for vsp_calculate_digest
create procedure app_auth_vec (in lines any)
{
declare ahdr, arr, authvec any;
ahdr := http_request_header (lines, 'Authorization');
if (isstring (ahdr) and ahdr like 'Digest%')
{
ahdr := subseq (ahdr, 6, length (ahdr));
arr := split_and_decode (ahdr, 0, '\0\0,=');
authvec := vector ('authtype', 'Digest', 'method', http_request_get ('REQUEST_METHOD'));
foreach (varchar elm in arr) do
{
declare elm1 varchar;
elm1 := trim (elm, '" ');
authvec := vector_concat (authvec, vector (elm1));
}
}
return authvec;
}
]]></programlisting>
</example>
</refsect1>
<refsect1 id="seealso_vsp_calculate_digest"><title>See Also</title>
<para>
<link linkend="fn_vhost_define">vhost_define</link>
</para>
</refsect1>
</refentry>
|
