File: rfc3050.txt

package info (click to toggle)
doc-rfc 20181229-2
  • links: PTS, VCS
  • area: non-free
  • in suites: buster
  • size: 570,944 kB
  • sloc: xml: 285,646; sh: 107; python: 90; perl: 42; makefile: 14
file content (1963 lines) | stat: -rw-r--r-- 76,652 bytes parent folder | download | duplicates (5)
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
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963






Network Working Group                                          J. Lennox
Request for Comments: 3050                                H. Schulzrinne
Category: Informational                                      Columbia U.
                                                            J. Rosenberg
                                                             dynamicsoft
                                                            January 2001


                    Common Gateway Interface for SIP

Status of this Memo

   This memo provides information for the Internet community.  It does
   not specify an Internet standard of any kind.  Distribution of this
   memo is unlimited.

Copyright Notice

   Copyright (C) The Internet Society (2001).  All Rights Reserved.

Abstract

   In Internet telephony, there must be a means by which new services
   are created and deployed rapidly.  In the World Wide Web, the Common
   Gateway Interface (CGI) has served as popular means towards
   programming web services.  Due to the similarities between the
   Session Initiation Protocol (SIP) and the Hyper Text Transfer
   Protocol (HTTP), CGI is a good candidate for service creation in a
   SIP environment.  This document defines a SIP CGI interface for
   providing SIP services on a SIP server.

IESG Note

   The IESG notes that the mechanism specified here depends on the
   Common Gateway Interface.  Should this interface change or be
   enhanced changes in this specification may also be necessary or
   appropriate.  According to the W3C, the CGI is presently maintained
   by the NCSA Software Development Group. See

      http://www.w3c.org/cgi

   for additional information on the current state of the CGI interface.









Lennox, et al.               Informational                      [Page 1]

RFC 3050                      CGI for SIP                   January 2001


Table of Contents

   1          Introduction .......................................   3
   2          Motivations ........................................   4
   3          Differences from HTTP CGI ..........................   5
   3.1        Basic Model ........................................   6
   3.2        Persistence Model ..................................   8
   3.3        SIP CGI Triggers ...................................   9
   3.4        Naming .............................................   9
   3.5        Environment Variables ..............................   9
   3.6        Timers .............................................  10
   4          Overview of SIP CGI ................................  10
   5          SIP CGI Specification ..............................  12
   5.1        Introduction .......................................  12
   5.1.1      Relationship with HTTP CGI .........................  12
   5.1.2      Conventions of This Document .......................  12
   5.1.3      Specifications .....................................  12
   5.1.4      Terminology ........................................  13
   5.2        Notational Conventions and Generic Grammar .........  13
   5.3        Invoking the Script ................................  14
   5.4        The SIP CGI Script Command Line ....................  14
   5.5        Data Input to the SIP CGI Script ...................  14
   5.5.1      Message Metadata (Metavariables) ...................  14
   5.5.1.1    AUTH_TYPE ..........................................  16
   5.5.1.2    CONTENT_LENGTH .....................................  16
   5.5.1.3    CONTENT_TYPE .......................................  17
   5.5.1.4    GATEWAY_INTERFACE ..................................  17
   5.5.1.5    Protocol-Specific Metavariables ....................  18
   5.5.1.6    REGISTRATIONS ......................................  18
   5.5.1.7    REMOTE_ADDR ........................................  19
   5.5.1.8    REMOTE_HOST ........................................  19
   5.5.1.9    REMOTE_IDENT .......................................  19
   5.5.1.10   REMOTE_USER ........................................  20
   5.5.1.11   REQUEST_METHOD .....................................  20
   5.5.1.12   REQUEST_TOKEN ......................................  21
   5.5.1.13   REQUEST_URI ........................................  21
   5.5.1.14   RESPONSE_STATUS ....................................  21
   5.5.1.15   RESPONSE_REASON ....................................  21
   5.5.1.16   RESPONSE_TOKEN .....................................  21
   5.5.1.17   SCRIPT_COOKIE ......................................  22
   5.5.1.18   SERVER_NAME ........................................  22
   5.5.1.19   SERVER_PORT ........................................  22
   5.5.1.20   SERVER_PROTOCOL ....................................  22
   5.5.1.21   SERVER_SOFTWARE ....................................  23
   5.5.2      Message Bodies .....................................  23
   5.6        Data Output from the SIP CGI Script ................  23
   5.6.1      CGI Action Lines ...................................  25
   5.6.1.1    Status .............................................  25



Lennox, et al.               Informational                      [Page 2]

RFC 3050                      CGI for SIP                   January 2001


   5.6.1.2    Proxy Request ......................................  25
   5.6.1.3    Forward Response ...................................  26
   5.6.1.4    Script Cookie ......................................  26
   5.6.1.5    CGI Again ..........................................  27
   5.6.1.6    Default Action .....................................  27
   5.6.2      CGI Header Fields ..................................  28
   5.6.2.1    Request-Token ......................................  28
   5.6.2.2    Remove .............................................  28
   5.7        Local Expiration Handling ..........................  28
   5.8        Locally-Generated Responses ........................  29
   5.9        SIP CGI and REGISTER ...............................  29
   5.10       SIP CGI and CANCEL .................................  29
   5.11       SIP CGI and ACK ....................................  30
   5.11.1     Receiving ACK's ....................................  30
   5.11.2     Sending ACK's ......................................  30
   6          System Specifications ..............................  30
   6.1        Unix ...............................................  30
   6.2        Microsoft Windows ..................................  31
   7          Security Considerations ............................  31
   7.1        Request Initiation .................................  31
   7.2        Authenticated and Encrypted Messages ...............  31
   7.3        SIP Header Fields Containing Sensitive Information..  32
   7.4        Script Interference with the Server ................  32
   7.5        Data Length and Buffering Considerations ...........  32
   8          Acknowledgements ...................................  33
   9          Authors' Addresses .................................  33
   10         Bibliography .......................................  34
   11         Full Copyright Statement ...........................  35

1 Introduction

   In Internet telephony, there must be a means by which new services
   are created and deployed rapidly.  In traditional telephony networks,
   this was accomplished through IN service creation environments, which
   provided an interface for creating new services, often using GUI-
   based tools.

   The WWW has evolved with its own set of tools for service creation.
   Originally, web servers simply translated URLs into filenames stored
   on a local system, and returned the file content.  Over time, servers
   evolved to provide dynamic content, and forms provided a means for
   soliciting user input.  In essence, what evolved was a means for
   service creation in a web environment.  There are now many means for
   creation of dynamic web content, including server side JavaScript,
   servlets, and the common gateway interface (CGI) [1].






Lennox, et al.               Informational                      [Page 3]

RFC 3050                      CGI for SIP                   January 2001


   Multimedia communications, including Internet telephony, will also
   require a mechanism for creating services.  This mechanism is
   strongly tied to the features provided by the signaling protocols.
   The Session Initiation Protocol (SIP) [2] has been developed for
   initiation and termination of multimedia sessions.  SIP borrows
   heavily from HTTP, inheriting its client-server interaction and much
   of its syntax and semantics.  For this reason, the web service
   creation environments, and CGI in particular, seem attractive as
   starting points for developing SIP based service creation
   environments.

2 Motivations

   CGI has a number of strengths which make it attractive as an
   environment for creating SIP services:

        Language independence: CGI works with perl, C, VisualBasic, tcl,
             and many other languages, as long as they support access to
             environment variables.

        Exposes all headers: CGI exposes the content of all the headers
             in an HTTP request to the CGI application.  An application
             can make use of these as it sees fit, and ignore those it
             doesn't care about.  This allows all aspects of an HTTP
             request to be considered for creation of content.  In a SIP
             environment, headers have greater importance than in HTTP.
             They carry critical information about the transaction,
             including caller and callee, subject, contact addresses,
             organizations, extension names, registration parameters and
             expirations, call status, and call routes, to name a few.
             It is therefore critical for SIP services to have as much
             access to these headers as possible.  For this reason, CGI
             is very attractive.

        Creation of responses: CGI is advantageous in that it can create
             all parts of a response, including headers, status codes
             and reason phrases, in addition to message bodies.  This is
             not the case for other mechanisms, such as Java servlets,
             which are focused primarily on the body.  In a SIP
             environment, it is critical to be able to generate all
             aspects of a response (and, all aspects of new or proxied
             requests), since the body is usually not of central
             importance in SIP service creation.








Lennox, et al.               Informational                      [Page 4]

RFC 3050                      CGI for SIP                   January 2001


        Component reuse: Many of the CGI utilities allow for easy
             reading of environment variables, parsing of form data, and
             often parsing and generation of header fields.  Since SIP
             reuses the basic RFC822 [3] syntax of HTTP, many of these
             tools are applicable to SIP CGI.

        Familiar environment: Many web programmers are familiar with
             CGI.

        Ease of extensibility: Since CGI is an interface and not a
             language, it becomes easy to extend and reapply to other
             protocols, such as SIP.

   The generality, extensibility, and detailed control and access to
   information provided by CGI, coupled with the range of tools that
   exist for it, which can be immediately applied to SIP, make it a good
   mechanism for SIP service creation.

3 Differences from HTTP CGI

   While SIP and HTTP share a basic syntax and a request-response model,
   there are important differences.  Proxies play a critical role in
   services for SIP, while they are less important for HTTP.  SIP
   servers can fork requests (proxying multiple requests when a single
   request is received), an important capability absent from HTTP.  SIP
   supports additional features, such as registrations, which are absent
   from HTTP.  These differences are reflected in the differences
   between SIP CGI and HTTP CGI.  SIP CGI runs primarily on proxy,
   redirect, and registrar servers, rather than user agent servers
   (which are the equivalent of origin servers in HTTP).  SIP CGI allows
   the script to perform specific messaging functions not supported in
   HTTP CGI (such as proxying requests), and SIP CGI introduces a
   persistence model that allow a script to maintain control through
   multiple message exchanges.  HTTP CGI has no persistence for scripts.

















Lennox, et al.               Informational                      [Page 5]

RFC 3050                      CGI for SIP                   January 2001


3.1 Basic Model

   The basic model for HTTP CGI is depicted in figure 1.

                -----    ------------
     ~~~~~~~~  |req  |  |  --------  |
    |        |----------| |  http  | |
    | client | |resp |  | | server | |
    |        |----------| |        | |w
     ~~~~~~~~  |     |  |  --------  |e
                -----   |  s|  /\s   |b
               net      |  t|   |t   |
                        |e d| C |d   |s
                        |n i| G |o   |e
                        |v n| I |u   |r
                        |   |   |t   |v
                        |  \/   |    |e
                        |  -------   |r
                        | |       |  |
                        | |  CGI  |  |
                        | | prog. |  |
                        | |       |  |
                        |  -------   |
                         ------------

   Figure 1: HTTP CGI Model

   A client issues an HTTP request, which is passed either directly to
   the origin server (as shown), or is forwarded through a proxy server.
   The origin server executes a CGI script, and the CGI script returns a
   response, which is passed back to the client.  The main job of the
   script is to generate the body for the response.  Only origin servers
   execute CGI scripts, not proxy servers.


















Lennox, et al.               Informational                      [Page 6]

RFC 3050                      CGI for SIP                   January 2001


   In a SIP server, the model is different, and is depicted in Figure 2.


     ~~~~~~~~   req  -------   req   -------     req   ~~~~~~~~
    |        |------|       |-------|       |---------|        |
    | client | resp | server| resp  | server| resp    | client |
    |        |------|       |-------|       |---------|        |
     ~~~~~~~~        -------         -------           --------
                      |   | CGI
                      |   |
                     -------
                    |       |
                    |  CGI  |
                    | prog. |
                    |       |
                     -------

   Figure 2: SIP CGI Model

   The client generates a request, which is forwarded to a server.  The
   server may generate a response (such as an error or redirect
   response).  Or, if the server is a proxy server, the request is
   proxied to another server, and eventually to a user agent, and the
   response is passed back upstream, through the server, and back
   towards the client.  A SIP proxy server may additionally fork
   requests, generating multiple requests in response to a received
   request.  Generally, a proxy server will not generate the content in
   responses.  These contain session descriptions created by user
   agents.  Services, such as call forward and mobility services, are
   based on the decisions the server makes about (1) when, to where, and
   how many requests to proxy downstream, and (2) when to send a
   response back upstream.  Creation of services such as ad-hoc bridging
   (where the server acts as a media mixer in a multiparty call, without
   being asked to do so by the end users) will require the server to
   generate new requests of its own, and for it to modify and generate
   the body in responses.

   An HTTP server is mainly concerned about generation of responses.  A
   SIP server is generally concerned about performing four basic
   operations:

        Proxying of Requests: Receiving a request, adding or modifying
             any of the headers, deciding on a set of servers to forward
             the request to, and forwarding it to them.

        Returning Responses: Receiving a response, adding or modifying
             any of the headers, and passing the response towards the
             client.



Lennox, et al.               Informational                      [Page 7]

RFC 3050                      CGI for SIP                   January 2001


        Generating Requests: Creating a new request, originating at the
             server, placing headers and a body into the message, and
             sending it to a server.

        Generation of Responses: Receiving a request, generating a
             response to it, and sending it back to the client.

   When a request is received, one or more of the above operations may
   occur at once.  For example, a SIP server may generate a provisional
   response, generate a new request, and proxy the original request to
   two servers.  This implies that SIP CGI must encompass a greater set
   of functions than HTTP CGI.  These functions are a super-set of the
   simple end-server request/response model.

3.2 Persistence Model

   In HTTP CGI, a script is executed once for each request.  It
   generates the response, and then terminates.  There is no state
   maintained across requests from the same user, as a general rule
   (although this can be done -- and is -- for more complex services
   such as database accesses, which essentially encapsulate state in
   client-side cookies or dynamically-generated URLs).  A transaction is
   just a single request, and a response.

   In SIP CGI, since a request can generate many new and proxied
   requests, these themselves will generate responses.  A service will
   often require these responses to be processed, and additional
   requests or responses to be generated.  As a result, whereas an HTTP
   CGI script executes once per transaction, a SIP CGI script must
   maintain control somehow over numerous events.

   In order to enable this, and to stay with the original CGI model, we
   mandate that a SIP CGI script executes when a message arrives, and
   after generating output (in the form of additional messages),
   terminate.  State is maintained by allowing the CGI to return an
   opaque token to the server.  When the CGI script is called again for
   the same transaction, this token is passed back to the CGI script.
   When called for a new transaction, no token is passed.

   For example, consider a request which arrives at a SIP server.  The
   server calls a CGI script, which generates a provisional response and
   a proxied request.  It also returns a token to the server, and then
   terminates.  The response is returned upstream towards the client,
   and the request is proxied.  When the response to the proxied request
   arrives, the script is executed again.  The environment variables are
   set based on the content of the new response.  The script is also
   passed back the token.  Using the token as its state, the script
   decides to proxy the request to a different location.  It therefore



Lennox, et al.               Informational                      [Page 8]

RFC 3050                      CGI for SIP                   January 2001


   returns a proxied request, and another token.  The server forwards
   this new request, and when the response comes, calls the CGI script
   once more, and passes back the token.  This time, the script
   generates a final response, and passes this back to the server.  The
   server sends the response to the client, destroys the token, and the
   transaction is complete.

3.3 SIP CGI Triggers

   In many cases, calling the CGI script on the reception of every
   message is inefficient.  CGI scripts come at the cost of significant
   overhead since they generally require creation of a new process.
   Therefore, it is important in SIP CGI for a script to indicate, after
   it is called the first time, under what conditions it will be called
   for the remainder of the transaction.  If the script is not called,
   the server will take the "default" action, as specified in this
   document.  This allows an application designer to trade off
   flexibility for computational resources.  Making an analogy to the
   Intelligent Network (IN) - a script is able to define the triggers
   for its future execution.

   So, in summary, whereas an HTTP CGI script executes once during a
   transaction, a single SIP CGI script may execute many times during a
   transaction, and may specify at which points it would like to have
   control for the remainder of the transaction.

3.4 Naming

   In HTTP CGI, the CGI script itself is generally the resource named in
   the request URI of the HTTP request.  This is not so in SIP.  In
   general, the request URI names a user to be called.  The mapping to a
   script to be executed may depend on other SIP headers, including To
   and From fields, the SIP method, status codes, and reason phrases.
   As such, the mapping of a message to a CGI script is purely a matter
   of local policy administration at a server.  A server may have a
   single script which always executes, or it may have multiple scripts,
   and the target is selected by some parts of the header.

3.5 Environment Variables

   In HTTP CGI, environment variables are set with the values of the
   paths and other aspects of the request.  As there is no notion of a
   path in SIP, some of these environment variables do not make sense.








Lennox, et al.               Informational                      [Page 9]

RFC 3050                      CGI for SIP                   January 2001


3.6 Timers

   In SIP, certain services require that the script gets called not only
   when a message arrives, but when some timer expires.  The classic
   example of this is "call forward no answer." To be implemented with
   SIP CGI, the first time the script is executed, it must generate a
   proxied request, and also indicate a time at which to be called again
   if no response comes.  This kind of feature is not present in HTTP
   CGI, and some rudimentary support for it is needed in SIP CGI.

4 Overview of SIP CGI

   When a request arrives at a SIP server, initiating a new transaction,
   the server will set a number of environment variables, and call a CGI
   script.  The script is passed the body of the request through stdin.

   The script returns, on stdout, a set of SIP action lines, each of
   which may be modified by CGI and/or SIP headers.  This set is
   delimited through the use of two carriage returns.  The action lines
   allow the script to specify any of the four operations defined above,
   in addition to the default operation.  Generating a response is done
   by copying the the status line of the response into an action line of
   the CGI output.  For example, the following will create a 200 OK to
   the original request:

   SIP/2.0 200 OK

   The operation of proxying a request is supported by the CGI-PROXY-
   REQUEST CGI action, which takes the URL to proxy to as an argument.
   For example, to proxy a request to dante@inferno.com:

   CGI-PROXY-REQUEST sip:dante@inferno.com SIP/2.0
   Contact: sip:server1@company.com

   In this example, the server will take the original request, and
   modify any header fields normally changed during the proxy operation
   (such as decrementing Max-Forwards, and adding a Via field).  This
   message is then "merged" with the output of the CGI script - SIP
   headers specified below the action line in the CGI output will be
   added to the outbound request.  In the above example, the Contact
   header will be added.  Note that the action line looks like the
   request line of a SIP request message.  This is done in order to
   simplify parsing.

   To delete headers from the outgoing request, the merge process also
   supports the CGI header CGI-Remove.  Like SIP headers, CGI headers
   are written underneath the action line.  They are extracted by the
   SIP server, and used to provide the server with additional guidance.



Lennox, et al.               Informational                     [Page 10]

RFC 3050                      CGI for SIP                   January 2001


   CGI headers always begin with CGI to differentiate them from SIP
   headers.  In this case, the supported values for the CGI-Remove
   header are the names of headers in the original message.

   Returning of responses is more complex.  A server may receive
   multiple responses as the result of forking a request.  The script
   should be able to ask the server to return any of the responses it
   had received previously.  To support this, the server will pass an
   opaque token to the script through environment variables, unique for
   each response received.  To return a response, a CGI script needs to
   indicate which response is to be returned.  For example, to return a
   response named with the token abcdefghij, the following output is
   generated:

   CGI-FORWARD-RESPONSE abcdefghij SIP/2.0

   Finally, if the script does not output any of the above actions, the
   server does what it would normally do upon receiving the message that
   triggered the script.

   A SIP CGI script is normally only executed when the original request
   arrives.  If the script also wants to be called for subsequent
   messages in a transaction -- due to responses to proxied requests, or
   (in certain circumstances) ACK and CANCEL requests, it can perform
   the CGI-AGAIN action:

   CGI-AGAIN yes SIP/2.0

   This action applies only to the next invocation of the script; it
   means to invoke the script one more time.  Outputting "no" is
   identical to outputting "yes" on this invocation of the script and
   outputting nothing the next time the script is called.

   When the script is re-executed, it may need access to some state in
   order to continue processing.  A script can generate one piece of
   state, called a cookie, for any new request or proxied request.  It
   is passed to the server through the CGI-SET-COOKIE action.  The
   action contains a token, which is the cookie itself.  The server does
   not examine or parse the cookie.  It is simply stored.  When the
   script is re-executed, the cookie is passed back to the script
   through an environment variable.

   CGI-SET-COOKIE khsihppii8asdl SIP/2.0

   Finally, when the script causes the server to proxy a request,
   responses to these requests will arrive.  To ease matching of
   responses to requests, the script can place a request token in the
   CGI CGI-Request-Token header.  This header is removed by the server



Lennox, et al.               Informational                     [Page 11]

RFC 3050                      CGI for SIP                   January 2001


   when the request is proxied.  Any responses received to this request
   will have the token passed in an environment variable.

5 SIP CGI Specification

5.1 Introduction

5.1.1 Relationship with HTTP CGI

   This SIP CGI specification is based on work-in-progress revision 1.1
   of the HTTP CGI specification [1].  That document is a product of the
   CGI-WG mailing list, which is not an official IETF working group.
   CGI-WG's homepage is located at the URL
   http://Web.Golux.Com/coar/cgi/, and the most recent versions of the
   CGI specification are available there.  This specification
   incorporates a great deal of text from the work-in-progress version
   of that document as of February 23, 2000.  A future version of this
   specification may be changed to cite parts of that document by
   reference instead.

5.1.2 Conventions of This Document

   In this document, the key words "MUST", "MUST NOT", "REQUIRED",
   "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY",
   and "OPTIONAL" are to be interpreted as described in RFC 2119 [4] and
   indicate requirement levels for compliant SIP CGI implementations.

        Some paragraphs are indented, like this; they give
        motivations of design choices, or questions for future
        discussion in the development of SIP CGI.  They are not
        normative to the specification of the protocol.

5.1.3 Specifications

   Not all of the functions and features of SIP CGI are defined in the
   main part of this specification.  The following phrases are used to
   describe the features which are not specified:

         System-defined: The feature may differ between systems, but
               must be the same for different implementations using the
               same system.  A system will usually identify a class of
               operating systems.  Some systems are defined in section 6
               of this document.  New systems may be defined by new
               specifications without revision of this document.

         Implementation-defined: The behavior of the feature may vary
               from implementation to implementation, but a particular
               implementation should be consistent in its behavior.



Lennox, et al.               Informational                     [Page 12]

RFC 3050                      CGI for SIP                   January 2001


5.1.4 Terminology

   This specification uses many terms defined in the SIP/2.0
   specification [2]; however, the following terms are used here in a
   sense which may not accord with their definitions in that document,
   or with their common meaning.

         metavariable: A named parameter that carries information from
               the server to the script.  It is not necessarily a
               variable in the operating system's environment, although
               that is the most common implementation.

         script: The software which is invoked by the server via this
               interface.  It need not be a standalone program, but
               could be a dynamically-loaded or shared library, or even
               a subroutine in the server.  It may be a set of
               statements interpreted at run-time, as the term `script'
               is frequently understood, but that is not a requirement
               and within the context of this specification the term has
               the broader definition stated.

         server: The application program which invokes the script in
               order to service messages.

         message: A SIP request or response, typically either the one
               that triggered the invocation of the CGI script, or one
               that the CGI script caused to be sent.

5.2 Notational Conventions and Generic Grammar

   In this specification we use the Augmented Backus-Naur Form notation
   as described in appendix C of the SIP/2.0 specification, RFC 2543
   [2].

   The following grammatical constructs are taken from other documents;
   this table lists the appropriate sources.

        OCTET          SIP/2.0 [2] Appendix C.1
        CHAR           SIP/2.0 [2] Appendix C.1
        digit          SIP/2.0 [2] Appendix C.1
        alphanum       SIP/2.0 [2] Appendix C.1
        token          SIP/2.0 [2] Appendix C.1
        hostname       SIP/2.0 [2] Section 2
        SIP-URL        SIP/2.0 [2] Section 2
        SIP-Version    SIP/2.0 [2] Section 4.3.1
        Status-Code    SIP/2.0 [2] Section 5.1.1
        Reason-Phrase  SIP/2.0 [2] Section 5.1.1
        media-type     HTTP/1.1 [5] Section 3.7



Lennox, et al.               Informational                     [Page 13]

RFC 3050                      CGI for SIP                   January 2001


                       (via SIP/2.0 [2] Section 6.16)
        field-name     SIP/2.0 [2] Section 6.6

   Other grammatical constructs taken from outside sources are noted in
   the text.

5.3 Invoking the Script

   The script is invoked in a system-defined manner.  Unless specified
   otherwise, the file containing the script will be invoked as an
   executable program.

   Only one CGI script at a time may be outstanding for a SIP
   transaction.  If subsequently arriving responses would cause a CGI
   script to be invoked, handling of them is deferred, except for ACK,
   until CGI scripts for previous messages in the transaction terminate.
   Messages are processed in the order they are received.

5.4 The SIP CGI Script Command Line

   The server SHOULD NOT provide any command line arguments to the
   script.

        Command line arguments are used for indexed queries in HTTP
        CGI; HTTP indexed queries do not have an equivalent in SIP.

5.5 Data Input to the SIP CGI Script

   Information about a message comes from two different sources: the
   message header, and any associated content-body.  Servers MUST make
   portions of this information available to scripts.

5.5.1 Message Metadata (Metavariables)

   Each SIP CGI server implementation MUST define a mechanism to pass
   data about the message from the server to the script.  The
   metavariables containing these data are accessed by the script in a
   system-defined manner.  The representation of the characters in the
   metavariables is system-defined.

   The representation of metavariables MUST distinguish between
   undefined values (which are not present) and null values (which are
   present, but have zero length).  Null values are only allowed for
   those metavariables whose grammar permits this.







Lennox, et al.               Informational                     [Page 14]

RFC 3050                      CGI for SIP                   January 2001


        For historical reasons, HTTP CGI does not distinguish
        between null values and undefined values.  This
        specification eliminates this misfeature; null values and
        undefined values are semantically different.

   Case is not significant in the metavariable names, in that there
   cannot be two different variables whose names differ in case only.
   Here they are shown using a canonical representation of capitals plus
   underscore ("_").  The actual representation of the names is system
   defined; for a particular system the representation MAY be defined
   differently than this.

   Metavariable values MUST be considered case-sensitive except as noted
   otherwise.

   The canonical metavariables defined by this specification are:

       AUTH_TYPE
       CONTENT_LENGTH
       CONTENT_TYPE
       GATEWAY_INTERFACE
       REMOTE_ADDR
       REMOTE_HOST
       REMOTE_IDENT
       REMOTE_USER
       REGISTRATIONS
       REQUEST_METHOD
       REQUEST_TOKEN
       REQUEST_URI
       RESPONSE_STATUS
       RESPONSE_REASON
       RESPONSE_TOKEN
       SCRIPT_COOKIE
       SERVER_NAME
       SERVER_PORT
       SERVER_PROTOCOL
       SERVER_SOFTWARE

   Metavariables with names beginning with the protocol name (e.g.,
   "SIP_ACCEPT") are also canonical in their description of message
   header fields.  The number and meaning of these fields may change
   independently of this specification.  (See also section 5.5.1.5.)

   A server MAY also specify additional non-canonical metavariables.







Lennox, et al.               Informational                     [Page 15]

RFC 3050                      CGI for SIP                   January 2001


5.5.1.1 AUTH_TYPE

   If the target of the message required access authentication for
   external access, then the server MUST set the value of this variable
   from the auth-scheme token in the message's Authorization header
   field.  Otherwise it is not defined.

        AUTH_TYPE    =  "" | auth-scheme
        auth-scheme  =  "Basic" | "Digest" | "PGP" | token

   SIP access authentication schemes are described in sections 14 and 15
   of the SIP/2.0 specification [2].  The auth-scheme is not case-
   sensitive.

   Servers MUST provide this metavariable to scripts if the message
   header included an Authorization field that was authenticated.

   For the complex authentication schemes, the server SHOULD perform the
   authentication checking itself.  If the authentication failed, this
   metavariable SHOULD NOT be set.

   If several authentication credentials, with multiple schemes, are
   present in the message, this variable SHOULD be set to correspond to
   the authenticated credentials with the strongest scheme the server
   supports.  If credentials are present for several domains, the server
   SHOULD NOT perform any action on credentials from domains external to
   it.

   If both Authorization and Proxy-Authorization headers are present,
   the server SHOULD perform the authorizations based on the appropriate
   header for the context in which it is running.  For example, a server
   which is a proxy server and a registrar would use Authorization
   headers for REGISTER messages aimed at its local domains, and Proxy-
   Authorization headers for all other messages.

5.5.1.2 CONTENT_LENGTH

   This metavariable is set to the size of the message-body entity
   attached to the message, if any, in decimal number of octets.  If no
   data are attached, then this metavariable is not defined.  The syntax
   is the same as for the SIP Content-Length header field (section 6.15,
   SIP/2.0 specification [2]).

        CONTENT_LENGTH  =  "" | 1*digit

   Servers MUST provide this metavariable to scripts if the message was
   a accompanied by a content-body entity, even if the message did not
   include a Content-Length header field.



Lennox, et al.               Informational                     [Page 16]

RFC 3050                      CGI for SIP                   January 2001


5.5.1.3 CONTENT_TYPE

   If the message includes a message-body, CONTENT_TYPE is set to the
   Internet Media Type [6] of the attached entity if the type was
   provided via a Content-type field in the message header, or if the
   server can determine it in the absence of a supplied Content-type
   field.  The syntax is the same as for the SIP Content-Type header
   field.

        CONTENT_TYPE  =  "" | media-type

   The type, subtype, and parameter attribute names are not case-
   sensitive.  Parameter values MAY be case sensitive.  Media types and
   their use in SIP are described in section 6.16 of the SIP/2.0
   specification [2], and by reference in section 3.7 of the HTTP/1.1
   specification [5].

   Since in SIP the Content-Type header MUST be specified if a body is
   present, servers MUST provide this metavariable to scripts if a body
   was present in the original message, unless the "body" is actually an
   encrypted payload.

5.5.1.4 GATEWAY_INTERFACE

   This metavariable is set to the dialect of SIP CGI being used by the
   server to communicate with the script.  Syntax:

        GATEWAY_INTERFACE  =  "SIP-CGI" "/" major "." minor
        major              =  1*digit
        minor              =  1*digit

   Note that the major and minor numbers are treated as separate
   integers and hence each may be more than a single digit.  Thus SIP-
   CGI/2.4 is a lower version than SIP-CGI/2.13 which in turn is lower
   than SIP-CGI/12.3.  Leading zeros in either the major or the minor
   number MUST be ignored by scripts and SHOULD NOT be generated by
   servers.

   This document defines the 1.1 version of the SIP CGI interface
   ("SIP-CGI/1.1").

   Servers MUST provide this metavariable to scripts.

        For maximal compatibility with existing HTTP CGI libraries,
        we want to keep this as similar as possible to the syntax
        of CGI 1.1.  However, we do want it to be clear that this is
        indeed SIP CGI.  Making HTTP CGI's version identifier a
        substring of the SIP CGI identifier seemed like a



Lennox, et al.               Informational                     [Page 17]

RFC 3050                      CGI for SIP                   January 2001


        reasonable compromise. (The existing CGI libraries we
        checked do not seem to check the version.)

5.5.1.5 Protocol-Specific Metavariables

   These metavariables are specific to the protocol via which the method
   is sent.  Interpretation of these variables depends on the value of
   the SERVER_PROTOCOL metavariable (see section 5.5.1.20).

   Metavariables with names beginning with "SIP_" contain values from
   the message header, if the protocol used was SIP.  Each SIP header
   field name is converted to upper case, has all occurrences of "-"
   replaced with "_", and has "SIP_" prepended to form the metavariable
   name.  Similar transformations are applied for other protocols.  The
   header data MAY be presented as sent by the client, or MAY be
   rewritten in ways which do not change its semantics.  If multiple
   header fields with the same field-name are received then the server
   MUST rewrite them as though they had been received as a single header
   field having the same semantics before being represented in a
   metavariable.  Similarly, a header field that is received on more
   than one line MUST be merged into a single line.  The server MUST, if
   necessary, change the representation of the data (for example, the
   character set) to be appropriate for a CGI metavariable.

        Note: these metavariables' names were changed from HTTP_*
        to SIP_* since the first draft of this specification.  The
        intention had been to make it easier to use existing CGI
        libraries unmodified, but this convenience was felt to be
        outweighed by the confusion this introduced.

   Servers are not required to create metavariables for all the message
   header fields they receive.  However, because of the relatively high
   importance of headers in SIP for messages' semantic content, the
   server SHOULD provide all headers which do not contain potentially
   sensitive authorization information, such as Authorization.  Servers
   SHOULD provide protocol-specific metavariables even for information
   which is available through other SIP CGI metavariables, such as
   CONTENT_LENGTH and CONTENT_TYPE.

        This allows a SIP CGI script to determine, if necessary,
        whether the information in the other metavariables was in
        the original message, or was synthesized by the server.

5.5.1.6 REGISTRATIONS

   This metavariable contains a list the current locations the server
   has registered for the user in the Request-URI of the initial request
   of a transaction.  It is syntactically identical to the protocol



Lennox, et al.               Informational                     [Page 18]

RFC 3050                      CGI for SIP                   January 2001


   metavariable SIP_CONTACT, and thus is defined by section 5.5.1.5 of
   this document and by section 6.13 of the SIP/2.0 specification [2].
   It contains all the uris, uri parameters, display names, and contact
   parameters for the addresses registered with the server.

        The syntax of REGISTRATIONS is identical to how SIP_CONTACT
        would appear in a 302 response from a redirection server.
        This allows parsing code to be re-used.

   If a user's registrations change in the course of a transaction, the
   server SHOULD update this metavariable accordingly for subsequent
   script invocations for the transaction.

5.5.1.7 REMOTE_ADDR

   The IP address of the client that sent the message to the server.
   This is not necessarily that of the originating user agent client or
   server.

        REMOTE_ADDR  =  hostnumber
        hostnumber   =  IPv4address | IPv6address

   The definitions of IPv4address and Ipv6address are provided in
   Appendix B of RFC 2373 [7].

   For locally-generated responses (see section 5.8), this SHOULD be the
   loopback address (i.e., 127.0.0.1 for IPv4 or ::1 for IPv6).

   Servers MUST supply this value to scripts.

5.5.1.8 REMOTE_HOST

   This is the fully qualified domain name of the host sending the
   message to this server, if available, otherwise not defined.  (See
   section 5.5.1.7).  Domain names are not case sensitive.

        REMOTE_HOST  =  hostname

   Servers SHOULD provide this information to scripts.

5.5.1.9 REMOTE_IDENT

   The identity information supported about the connection by a RFC 1413
   [8] request, if available.

        REMOTE_IDENT  =  *CHAR





Lennox, et al.               Informational                     [Page 19]

RFC 3050                      CGI for SIP                   January 2001


   The server MAY choose not to support this feature, and it is
   anticipated that not many implementations will, as the information is
   not particularly useful in the presence of complex proxy paths.

5.5.1.10 REMOTE_USER

   If the message requested authentication (i.e., the AUTH_TYPE
   metavariable is set), then the value of the REMOTE_USER metavariable
   is set to the user-ID supplied for the authentication.  For Basic
   authentication this is the content of the (decoded) "userid" grammar
   element; for Digest it is content of "username-value." For PGP
   authentication, it is the URI specified in the "signed-by" parameter
   of the Authorization header, if present, otherwise the URI part of
   the From header.

   If some other authentication scheme was requested, this metavariable
   SHOULD be set to an appropriate component of the authorization
   information identifying the user or entity associated with the
   credentials.  If authentication was not requested, this metavariable
   is not defined.

        REMOTE_USER  =  *OCTET


   Servers SHOULD provide this metavariable to scripts.

5.5.1.11 REQUEST_METHOD

   If the message triggering the script was a request, the
   REQUEST_METHOD metavariable is set to the method with which the
   request was made, as described in section 4.2 of the SIP/2.0
   specification [2]; otherwise not defined.

        REQUEST_METHOD    =  sip-method
        sip-method        =  "INVITE" | "BYE" | "OPTIONS" | "CANCEL"
                             | "REGISTER" | "ACK"
                             | extension-method
        extension-method  =  token

   Note that ACK is usually not appropriate for the SIP CGI 1.1
   environment; however, see section 5.11.  The implications of REGISTER
   in the CGI context are discussed in section 5.9, and CANCEL is
   discussed in section 5.10.  A SIP CGI 1.1 server MAY choose to
   process some methods directly rather than passing them to scripts.

   Servers MUST provide this metavariable to scripts if the triggering
   message was a request.




Lennox, et al.               Informational                     [Page 20]

RFC 3050                      CGI for SIP                   January 2001


5.5.1.12 REQUEST_TOKEN

        REQUEST_TOKEN  =  token

   If the script specified a request token in a proxied request, this
   token is returned to the server in responses to that request.  Note
   that this token is chosen by the script, not by the server.  Each
   response to a proxied request contains the same value for this token.

5.5.1.13 REQUEST_URI

   This metavariable is specific to requests made with SIP.

        REQUEST_URI  =  absoluteURI  ; defined in RFC 2396 [9]

   If the message triggering the script was a request, this variable
   indicates the URI specified with the request method.  This
   metavariable is only defined if REQUEST_METHOD is defined; in that
   case, servers MUST provide it to scripts.

        This metavariable fills the roles of HTTP CGI's
        SCRIPT_NAME, PATH_INFO, and QUERY_STRING.

5.5.1.14 RESPONSE_STATUS

        RESPONSE_STATUS  =  Status-Code

   If the message triggering the script was a response, this variable
   indicates the numeric code specified in the response; otherwise it is
   not defined.  In the former case, servers MUST provide this
   metavariable to scripts.

5.5.1.15 RESPONSE_REASON

        RESPONSE_REASON  =  Reason-Phrase

   If the message triggering the script was a response, this variable
   indicates the textual string specified in the response.

5.5.1.16 RESPONSE_TOKEN

        RESPONSE_TOKEN  =  token

   If the message triggering the script was a response, the server MUST
   specify a token which subsequent invocations of the CGI script can
   use to identify this response.  This string is chosen by the server
   and is opaque to the CGI script.  See the discussion of CGI-FORWARD-
   RESPONSE in section 5.6.1 below.



Lennox, et al.               Informational                     [Page 21]

RFC 3050                      CGI for SIP                   January 2001


5.5.1.17 SCRIPT_COOKIE

        SCRIPT_COOKIE  =  token

   This is the value an earlier invocation of this script for this
   transaction passed to the server in CGI action line CGI-SET-COOKIE.
   See the description of that action in section 5.6.1.4 below.

5.5.1.18 SERVER_NAME

   The SERVER_NAME metavariable is set to the name of the server.

        SERVER_NAME  =  hostname | hostnumber

   Servers MUST provide this metavariable to scripts.

5.5.1.19 SERVER_PORT

   The SERVER_PORT metavariable is set to the port on which the message
   was received.

        SERVER_PORT  =  1*digit

   Servers MUST provide this metavariable to scripts.

5.5.1.20 SERVER_PROTOCOL

   The SERVER_PROTOCOL metavariable is set to the name and revision of
   the protocol with which the message arrived.  This will usually be
   "SIP/2.0".  This is not necessarily the same as the protocol version
   used by the server in its response to the client.

        SERVER_PROTOCOL    =  SIP-Version | extension-version
                              | extension-token
        extension-version  =  protocol "/" 1*digit "." 1*digit
        protocol           =  1*( alphanum | "+" | "-" | "." )
        extension-token    =  token

   Servers MUST provide this metavariable to scripts.












Lennox, et al.               Informational                     [Page 22]

RFC 3050                      CGI for SIP                   January 2001


5.5.1.21 SERVER_SOFTWARE

   The SERVER_SOFTWARE metavariable is set to the name and version of
   the information server software handling the message (and running the
   gateway).

        SERVER_SOFTWARE  =  1*product
        product          =  token [ "/" product-version ]
        product-version  =  token

   Servers MUST provide this metavariable to scripts.

5.5.2 Message Bodies

   As there may be a data entity attached to the message, there MUST be
   a system-defined method for the script to read these data.  Unless
   defined otherwise, this will be via the `standard input' file
   descriptor.

   If the metavariable CONTENT_LENGTH (see section 5.5.1.2) is defined,
   the server MUST supply at least that many bytes to scripts on the
   standard input stream.  Scripts are not obliged to read the data.
   Servers MAY signal an EOF condition after CONTENT_LENGTH bytes have
   been read, but are not obligated to do so.  Therefore, scripts MUST
   NOT attempt to read more than CONTENT_LENGTH bytes, even if more data
   are available.

5.6 Data Output from the SIP CGI Script

   There MUST be a system-defined method for the script to send data
   back to the server or client.  Unless defined otherwise, this will be
   via the `standard output' file descriptor.

   Servers MAY implement a timeout period within which data must be
   received from scripts, a maximum number of requests or responses that
   a particular CGI script can initiate, a maximum total number of
   requests or responses that can be sent by scripts over the lifetime
   of a transaction, or any other resource limitations it desires.  If a
   script exceeds one of these limitations, the server MAY terminate the
   script process and SHOULD abort the transaction with either a `504
   Gateway Timed Out' or a `500 Internal Server Error' response.










Lennox, et al.               Informational                     [Page 23]

RFC 3050                      CGI for SIP                   January 2001


   A SIP CGI script's output consists of any number of messages, each
   corresponding to actions which the script is requesting that the
   server perform.  Messages consist of an action line, whose syntax is
   specific to the type of action, followed by CGI header fields and SIP
   header fields.  Action lines determine the nature of the action
   performed, and are described in section 5.6.1.  CGI header fields
   pass additional instructions or information to the server, and are
   described in section 5.6.2.

   A message MUST contain exactly one action line, MAY also contain any
   number of CGI header fields and SIP header fields, and MAY contain a
   SIP body.

   All header fields (both SIP and CGI) occurring in an output message
   MUST be specified one per line; SIP CGI 1.1 makes no provision for
   continuation lines.

   The generic syntax of CGI header fields is specified in section
   5.6.2.

   A server MAY choose to honor only some of the requests or responses;
   in particular, it SHOULD NOT accept any responses following a Status
   message which sends a definitive non-success response.

   The messages sent by a script are delimited as follows:

        1.   A message begins with an action line.

        2.   If the message does not contain a Content-Type header
             field, or if it contains the header field "Content-Length:
             0", then it is terminated by a blank line.

        3.   If the message contains both Content-Type and Content-
             Length header fields, the message has a body consisting of
             the Content-Length octets following the blank line below
             the set.  The next message begins after the body (and
             optionally some number of blank lines).  If the script
             closes its output prematurely, the server SHOULD report a
             500-class server error.

        4.   If the message contains Content-Type but not Content-
             Length, the message's body similarly begins with the blank
             line following the set; this body extends until the script
             closes its output.  In this case, this is necessarily the
             last message the script can send.  The server SHOULD insert
             a Content-Length header containing the amount of data read
             before the script closed its output.




Lennox, et al.               Informational                     [Page 24]

RFC 3050                      CGI for SIP                   January 2001


        5.   If a message contains a non-zero Content-Length but does
             not contain a Content-Type, it is an error.  The server
             SHOULD report a 500-class server error.

        The output of a SIP CGI script is intended to be
        syntactically identical to that of a UDP packet in which
        multiple requests or responses are sent, so that the same
        message parser may be used.

5.6.1 CGI Action Lines

5.6.1.1 Status

        Status  =  SIP-Version 3*digit SP reason-phrase NL

   This action line causes the server to generate a SIP response and
   relay it upstream towards the client.  The server MUST copy the To,
   From, Call-ID, and CSeq headers from the original request into the
   response if these headers are not specified in the script output.
   The server SHOULD copy any other headers from the request which would
   normally be copied in the response if these are not specified in the
   script output.

   For compatibility with HTTP CGI, a server MAY interpret a message
   containing a Content-Type header field and no action line as though
   it contained "SIP/2.0 200 OK".  This usage is deprecated.

5.6.1.2 Proxy Request

        Proxy-Request  =  "CGI-PROXY-REQUEST" SIP-URL SIP-Version

   This action line causes the server to forward a request to the
   specified SIP URI.  It may be sent either by a script triggered by a
   request, in which case the triggering request is forwarded; or by a
   script triggered by a response on a server which is running
   statefully, in which case the initial request of the transaction is
   sent.

   Any SIP header field MAY be specified below the action line.
   Specified SIP headers replace all those in the original message in
   their entirety; if a script wants to preserve header elements from
   the original message as well as adding new ones, it can concatenate
   them by the usual rules of header concatenation, and place the result
   in the script output.  New header fields are added to the message
   after any Via headers but before any other headers.






Lennox, et al.               Informational                     [Page 25]

RFC 3050                      CGI for SIP                   January 2001


   Any headers from the original request which are not generated by the
   CGI script are copied into the proxied request, after modifications
   normally performed by a proxy server.  In particular, the server MUST
   append a Via field and decrement Max-Forwards.  A server MAY perform
   additional modifications as it sees fit, such as adding a Record-
   Route header.  A server SHOULD NOT append these headers if they are
   specified in the script output.

   A script MAY specify that a SIP header is to be deleted from the
   message by using the CGI-Remove CGI header; see section 5.6.2.

   If the message does not specify a body, the body from the initial
   request is used.  A message with "Content-Length: 0" is specifying an
   empty body; this causes the body to be deleted from the message.

   If the original request was authenticated by any means other than
   `basic,' the script SHOULD NOT add, change, or remove any end-to-end
   headers, as this would break the authentication.

5.6.1.3 Forward Response

        Forward-Response  =  "CGI-FORWARD-RESPONSE" Response-Name
                              SIP-Version
        Response-Name     =  response-token | "this"

   This action line causes the server to forward a response on to its
   appropriate final destination.  The same rules apply for accompanying
   SIP headers and message bodies as for CGI-PROXY-REQUEST.

   The specified response name may either be a response token the server
   previously submitted in a RESPONSE_TOKEN metavariable, or the string
   "this." The string "this" may only be sent if the message which
   triggered this CGI script was a response; it indicates that this
   triggering response should be forwarded.

5.6.1.4 Script Cookie

        Script-Cookie  =  "CGI-SET-COOKIE" token SIP-Version

   This action line causes the server to store a script cookie, passed
   as a token in the action line.  Subsequent script invocations for
   messages within the same transaction carry the token in a meta-
   header.  The script can alter the value of the cookie by subsequent
   script cookie actions.  This alteration will take affect for all
   subsequent script invocations.






Lennox, et al.               Informational                     [Page 26]

RFC 3050                      CGI for SIP                   January 2001


5.6.1.5 CGI Again

        CGI-Again  =  "CGI-AGAIN" ("yes" | "no") SIP-Version

   This action line determines whether the script will be invoked for
   subsequent requests and responses for this transaction.  If the
   parameter "yes" is given to this action, the script will be executed
   again when the next message arrives.  If the parameter is "no," or
   this action is not specified, the script will not be executed again,
   and the server will perform its default action for all subsequent
   messages.

5.6.1.6 Default Action

   If none of the actions CGI-PROXY-REQUEST, CGI-FORWARD-RESPONSE, or a
   new response are performed -- that is to say, the script outputs only
   CGI-AGAIN, CGI-SET-COOKIE, or nothing -- the script performs its
   default action.  The default action to take depends on the event
   which triggered the script:

         Request received: When the request is first received, the
               default action of the server is to check whether the
               domain of the server matches the domain of the Request-
               URI.  If it does not, the request is proxied to the
               request in the Request-URI.  Otherwise, the server checks
               its registration database against the request, and either
               proxies or redirects the request based on the action
               specified by the user agent in the registration.

         Proxied response received: If a response is received to a
               proxied request, the server forwards the response towards
               the caller if the response was a 200 or 600 class
               response, and sends a CANCEL on all pending branches.  If
               the response was 100 class, the state machinery for that
               branch is updated, and the response is proxied upstream
               towards the caller unless the it was a 100 response, not
               some other 1xx.  For 300, 400, and 500 class responses,
               an ACK is sent, and the response is forwarded upstream
               towards the caller if all other branches have terminated,
               and the response is the best received so far.  If not all
               branches have terminated, the server does nothing.  If
               all branches have terminated, but this response is not
               the best, the best is forwarded upstream.  This is the
               basic algorithm outlined in the SIP specification.







Lennox, et al.               Informational                     [Page 27]

RFC 3050                      CGI for SIP                   January 2001


5.6.2 CGI Header Fields

   CGI header fields syntactically resemble SIP header fields, but their
   names all begin with the string "CGI-".  The SIP server MUST strip
   all CGI header fields from any message before sending it, including
   those it does not recognize.

   CGI header fields have the generic syntax specified in section 6.6 of
   the SIP/2.0 specification [2].  The field-name is not case sensitive;
   the field value MUST conform to the grammar of that specific field in
   the specification where it is defined.

5.6.2.1 Request-Token

        Request-Token  =  "CGI-Request-Token" ":" token

   To assist in matching responses to proxied requests, the script can
   place a CGI-Request-Token CGI header in a CGI-PROXY-REQUEST or new
   request.  This header contains a token, opaque to the server.  When a
   response to this request arrives, the token is passed back to the
   script as a meta-header.

        This allows scripts to "fork" a proxy request, and
        correlate which response corresponds to which branch of the
        request.

5.6.2.2 Remove

        Remove  =  "CGI-Remove" ":" 1#field-name

   The CGI-Remove header allows the script to remove SIP headers from
   the outgoing request or response.  The value of this header is a
   comma-separated list of SIP headers which should be removed before
   sending out the message.

   A script MAY specify headers which are not in the request; the server
   SHOULD silently ignore these.  A script SHOULD NOT both specify a SIP
   header in its output and also list that header in a CGI-Remove
   header; the result of doing this is undefined.

5.7 Local Expiration Handling

   If a CGI script specifies an Expires header field along with CGI-
   PROXY-REQUEST, the SIP server SHOULD track the expiration timeout
   locally as well as sending the message to the remote server.  When
   the timeout expires, the server SHOULD generate a "408 Request





Lennox, et al.               Informational                     [Page 28]

RFC 3050                      CGI for SIP                   January 2001


   Timeout" response.  The timeout response SHOULD be handled as
   specified in section 5.8.  At the time the request is timed out, the
   server SHOULD also transmit CANCEL messages for the request.

        This allows a SIP CGI script in a proxy server to implement
        services like "Call Forward No Answer" to trigger after a
        user-determined time, even if the remote user-agent server
        is not responding or does not properly handle the Expires
        header field.

5.8 Locally-Generated Responses

   In a proxy environment, locally-generated responses such as "408
   Request Timeout" SHOULD be sent to the CGI script in the same manner
   as received messages are.  However, messages which merely report a
   problem with a message, such as "400 Bad Request", SHOULD NOT be.

        This is the other half of the requirements for the
        implementation of the "Call Forward No Answer" service,
        along with the local handling of the Expires header.

5.9 SIP CGI and REGISTER

   The specific semantics of a SIP CGI script which is triggered by a
   REGISTER request are somewhat different than that of those triggered
   by call-related requests; however, allowing user control of
   registration may in some cases be useful.  The two specific actions
   for REGISTER that need to be discussed are the response "200" and the
   default action.  In the former case, the server SHOULD assume that
   the CGI script is handling the registration internally, and SHOULD
   NOT add the registration to its internal registration database; in
   the latter case, the server SHOULD add the registration to its own
   database.  The server also SHOULD NOT add the registration if a 3xx,
   4xx, 5xx, or 6xx status was returned, or if the registration request
   was proxied to another location.

5.10 SIP CGI and CANCEL

   SIP CGI servers SHOULD execute scripts when a CANCEL message is
   received.  The script SHOULD clean up any state it has for the
   transaction as quickly as possible.










Lennox, et al.               Informational                     [Page 29]

RFC 3050                      CGI for SIP                   January 2001


   When a CANCEL is received at a server for an existing transaction,
   the server SHOULD send a 200 OK response to the cancel and cancel all
   currently outstanding branches.  The transmission of the script on a
   CANCEL message is purely advisory, and the script SHOULD NOT perform
   any actions in response to it.

5.11 SIP CGI and ACK

5.11.1 Receiving ACK's

   Under normal circumstances, if the server receives an ACK, the script
   is not re-executed.  If the ACK is destined for the proxy
   (acknowledging a 300, 400, 500, or 600 response), the ACK causes
   response retransmissions to cease.  If the ACK is for a 200 response
   forwarded from a downstream server, the ACK is proxied downstream.

   However, if the script generated its own 200 response to an INVITE
   request, the script SHOULD be re-executed with the ACK message.  This
   is necessary in cases where the script is causing the proxy to act as
   a UAS.  ACK messages can contain bodies, and would therefore be
   useful to the script.

5.11.2 Sending ACK's

   When the server receives a non-200 final response to an INVITE
   request, it SHOULD generate an ACK on its own, and not depend on the
   script to do so.  There is no way in SIP CGI 1.1 to override this
   behavior.  However, since the server will not generate an ACK for 200
   responses to INVITE, a script causing the server to act as a UAC MUST
   generate ACK's for them.

6 System Specifications

6.1 Unix

   The implementation of SIP CGI on a Unix operating system platform
   SHOULD use environment variables as the mechanism of providing
   request metadata to CGI scripts.

   For Unix compatible operating systems, the following are defined:

        Environment variables: These are accessed by the C library
             routine getenv.








Lennox, et al.               Informational                     [Page 30]

RFC 3050                      CGI for SIP                   January 2001


        The current working directory: The current working directory for
             the script SHOULD be set to the directory containing the
             script.

        Character set: The US-ASCII character set is used for the
             definition of environment variable names and header field
             names; the newline (NL) sequence is LF; servers SHOULD also
             accept CR LF as a newline.

6.2 Microsoft Windows

   The implementation of SIP CGI on 32-bit Microsoft Windows system
   platforms (Windows 95, 98, NT, and 2000) SHOULD use environment
   variables as the mechanism of providing request metadata to CGI
   scripts.

   For Microsoft Windows, the following are defined:

        Environment variables: These are accessed by the C library
             routine getenv.

        The current working directory: The current working directory for
             the script SHOULD be set to the directory containing the
             script.

        Character set: The US-ASCII character set is used for the
             definition of environment variable names and header field
             names; the newline (NL) sequence is CR LF; servers SHOULD
             also accept LF as a newline.

7 Security Considerations

7.1 Request Initiation

   CGI scripts are able to initiate arbitrary SIP transactions, or to
   produce spoofed responses of any sort.  This protocol does not
   attempt to restrict the actions CGI scripts can take.  Server
   administrators MUST consider CGI scripts to be as security-sensitive
   as their SIP server itself, and perform equivalent levels of security
   review before installing them.

7.2 Authenticated and Encrypted Messages

   CGI scripts must be careful not to interfere with authentication.  In
   particular, adding or removing header fields that are below the
   Authorization header will cause the message to fail authentication at
   the user agent.




Lennox, et al.               Informational                     [Page 31]

RFC 3050                      CGI for SIP                   January 2001


   When a SIP request is encrypted, the headers which are in the clear
   are passed to the server according to this specification.  The
   encrypted portion of the request is passed to the script as a body.
   Any SIP headers output by the script will be added to the message.
   However, scripts should be aware that these may be discarded if they
   also exist within the encrypted portion.

7.3 SIP Header Fields Containing Sensitive Information

   Some SIP header fields may carry sensitive information which the
   server SHOULD NOT pass on to the script unless explicitly configured
   to do so.  For example, if the server protects the script using the
   Basic authentication scheme, then the client will send an
   Authorization header field containing a username and password.  If
   the server, rather than the script, validates this information then
   the password SHOULD NOT be passed on to the script via the
   HTTP_AUTHORIZATION metavariable.

7.4 Script Interference with the Server

   The most common implementation of CGI invokes the script as a child
   process using the same user and group as the server process.  It
   SHOULD therefore be ensured that the script cannot interfere with the
   server process, its configuration, or documents.

   If the script is executed by calling a function linked in to the
   server software (either at compile-time or run-time) then precautions
   SHOULD be taken to protect the core memory of the server, or to
   ensure that untrusted code cannot be executed.

7.5 Data Length and Buffering Considerations

   This specification places no limits on the length of entity bodies
   presented to the script.  Scripts SHOULD NOT assume that statically
   allocated buffers of any size are sufficient to contain the entire
   submission at one time.  Use of a fixed length buffer without careful
   overflow checking may result in an attacker exploiting `stack-
   smashing' or `stack-overflow' vulnerabilities of the operating
   system.  Scripts may spool large submissions to disk or other
   buffering media, but a rapid succession of large submissions may
   result in denial of service conditions.  If the CONTENT_LENGTH of an
   entity-body is larger than resource considerations allow, scripts
   SHOULD respond with `413 Request Entity Too Large.'








Lennox, et al.               Informational                     [Page 32]

RFC 3050                      CGI for SIP                   January 2001


8 Acknowledgements

   This work draws extremely heavily upon the HTTP CGI specification
   [1]; approximately half the text of the specification section is
   taken from that document.

9 Authors' Addresses

   Jonathan Lennox
   Dept. of Computer Science
   Columbia University
   1214 Amsterdam Avenue, MC 0401
   New York, NY 10027
   USA

   EMail: lennox@cs.columbia.edu


   Jonathan Rosenberg
   dynamicsoft
   72 Eagle Rock Ave.
   First Floor
   East Hanover, NJ 07936

   EMail: jdrosen@dynamicsoft.com


   Henning Schulzrinne
   Dept. of Computer Science
   Columbia University
   1214 Amsterdam Avenue, MC 0401
   New York, NY 10027
   USA

   EMail: schulzrinne@cs.columbia.edu
















Lennox, et al.               Informational                     [Page 33]

RFC 3050                      CGI for SIP                   January 2001


10 Bibliography

   [1]  http://hoohoo.ncsa.uiuc.edu/cgi/interface.html

   [2]  Handley, M, Schulzrinne, H., Schooler, E. and J. Rosenberg,
        "SIP:  Session Initiation Protocol", RFC 2543, March 1999.

   [3]  Crocker, D., "Standard for the Format of ARPA Internet Text
        Messages", STD 10, RFC 822, August 1982.

   [4]  Bradner, S., "Key words for use in RFCs to indicate requirement
        levels", BCP 14, RFC 2119, March 1997.

   [5]  Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L.,
        Leach, P. and T. Berners-Lee, "Hypertext Transfer Protocol --
        HTTP/1.1", RFC 2616, June 1999.

   [6]  Freed, N. and N. Borenstein, "Multipurpose Internet Mail
        Extensions (MIME) Part Two: Media Types", RFC 2046, November
        1996.

   [7]  Hinden, R. and S. Deering, "IP Version 6 Addressing
        Architecture", RFC 2373, July 1998.

   [8]  St. Johns, M., "Identification Protocol", RFC 1413, January
        1993.

   [9]  Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform Resource
        Identifiers (URI): Generic Syntax", RFC 2396, August 1998.






















Lennox, et al.               Informational                     [Page 34]

RFC 3050                      CGI for SIP                   January 2001


11 Full Copyright Statement

   Copyright (C) The Internet Society (2001).  All Rights Reserved.

   This document and translations of it may be copied and furnished to
   others, and derivative works that comment on or otherwise explain it
   or assist in its implementation may be prepared, copied, published
   and distributed, in whole or in part, without restriction of any
   kind, provided that the above copyright notice and this paragraph are
   included on all such copies and derivative works.  However, this
   document itself may not be modified in any way, such as by removing
   the copyright notice or references to the Internet Society or other
   Internet organizations, except as needed for the purpose of
   developing Internet standards in which case the procedures for
   copyrights defined in the Internet Standards process must be
   followed, or as required to translate it into languages other than
   English.

   The limited permissions granted above are perpetual and will not be
   revoked by the Internet Society or its successors or assigns.

   This document and the information contained herein is provided on an
   "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
   TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
   BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
   HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
   MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Acknowledgement

   Funding for the RFC Editor function is currently provided by the
   Internet Society.



















Lennox, et al.               Informational                     [Page 35]