Overview
Comment: | Documentation updates |
---|---|
Downloads: | Tarball | ZIP archive | SQL archive |
Timelines: | family | ancestors | trunk | main |
Files: | files | file ages | folders |
SHA3-256: |
e03e54ee874ee241420158520ac95622 |
User & Date: | bohagan on 2024-12-19 20:56:21 |
Other Links: | branch diff | manifest | tags |
Context
2024-12-19
| ||
20:56 | Documentation updates Leaf check-in: e03e54ee87 user: bohagan tags: trunk, main | |
2024-12-17
| ||
01:24 | Corrected install pkgIndex.tcl file path check-in: 68b20030ff user: bohagan tags: trunk, main | |
Changes
Modified doc/tls.html
from [2cff05be8e]
to [037437202b].
︙ | ︙ | |||
607 608 609 610 611 612 613 | <dt><i class="arg">direction</i></dt> <dd><p>Direction is either <b class="const">Sent</b> or <b class="const">Received</b>.</p></dd> <dt><i class="arg">version</i></dt> <dd><p>Version is the protocol version.</p></dd> <dt><i class="arg">content_type</i></dt> <dd><p>Content type is the message content type.</p></dd> <dt><i class="arg">message</i></dt> | | < | | 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 | <dt><i class="arg">direction</i></dt> <dd><p>Direction is either <b class="const">Sent</b> or <b class="const">Received</b>.</p></dd> <dt><i class="arg">version</i></dt> <dd><p>Version is the protocol version.</p></dd> <dt><i class="arg">content_type</i></dt> <dd><p>Content type is the message content type.</p></dd> <dt><i class="arg">message</i></dt> <dd><p>Message is more info from the <b class="const">SSL_trace</b> API.</p></dd> </dl></dd> <dt><b class="option">session</b> <i class="arg">channelId session_id session_ticket lifetime</i></dt> <dd><p>This form of callback is invoked by the OpenSSL function <b class="function">SSL_CTX_sess_set_new_cb()</b> whenever a new session id is sent by the server during the initial connection and handshake and also during the session if the <b class="option">-post_handshake</b> option is set to true. This callback is new for TclTLS 1.8. The arguments are:</p> <dl class="doctools_definitions"> <dt><i class="arg">session_id</i></dt> <dd><p>Session Id is the current session identifier</p></dd> <dt><i class="arg">session_ticket</i></dt> <dd><p>Ticket is the session ticket info</p></dd> <dt><i class="arg">lifetime</i></dt> <dd><p>Lifetime is the ticket lifetime in seconds.</p></dd> </dl></dd> <dt><b class="option">verify</b> <i class="arg">channelId depth cert status error</i></dt> <dd><p>This callback was moved to <b class="option">-validatecommand</b> in TclTLS 1.8.</p></dd> </dl> </div> <div id="subsection4" class="doctools_subsection"><h3><a name="subsection4">Values for Password Callback</a></h3> <p>The callback for the <b class="option">-password</b> option is invoked by TclTLS whenever OpenSSL needs to obtain a password. See below for the possible arguments passed to the callback script. The user provided password is expected to be returned by the callback.</p> |
︙ | ︙ | |||
734 735 736 737 738 739 740 | <b class="option">-validatecommand</b> option is set to <b class="cmd">tls::validate_command</b>.</p> <p><em>The use of the variable <b class="variable">tls::debug</b> is not recommended. It may be removed from future releases.</em></p> </div> <div id="section6" class="doctools_section"><h2><a name="section6">Debug Examples</a></h2> <p>These examples use the default Unix platform SSL certificates. For standard installations, -cadir and -cafile should not be needed. If your certificates | | | | | 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 | <b class="option">-validatecommand</b> option is set to <b class="cmd">tls::validate_command</b>.</p> <p><em>The use of the variable <b class="variable">tls::debug</b> is not recommended. It may be removed from future releases.</em></p> </div> <div id="section6" class="doctools_section"><h2><a name="section6">Debug Examples</a></h2> <p>These examples use the default Unix platform SSL certificates. For standard installations, -cadir and -cafile should not be needed. If your certificates are in non-standard locations, specify -cadir or -cafile as needed.</p> <p>Example #1: Use HTTP package</p> <pre class="doctools_example"> package require http package require tls set url "https://www.tcl.tk/" http::register https 443 [list ::tls::socket -autoservername 1 -require 1 -command ::tls::callback -password ::tls::password -validatecommand ::tls::validate_command] # Check for error set token [http::geturl $url] if {[http::status $token] ne "ok"} { puts [format "Error %s" [http::status $token]] } # Get web page set data [http::data $token] puts [string length $data] # Cleanup ::http::cleanup $token </pre> <p>Example #2: Use raw socket</p> <pre class="doctools_example"> package require tls set url "www.tcl-lang.org" set port 443 set ch [tls::socket -autoservername 1 -servername $url -require 1 -alpn {http/1.1} -command ::tls::callback -password ::tls::password -validatecommand ::tls::validate_command $url $port] chan configure $ch -buffersize 65536 tls::handshake $ch puts $ch "GET / HTTP/1.1" flush $ch after 500 set data [read $ch] array set status [tls::status $ch] |
︙ | ︙ | |||
782 783 784 785 786 787 788 | installations, -cadir and -cafile should not be needed. If your certificates are in non-standard locations, set -cadir or use -cafile as needed.</p> <p>Example #3: Get web page</p> <pre class="doctools_example"> package require http package require tls set url "https://www.tcl.tk/" | | | | 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 | installations, -cadir and -cafile should not be needed. If your certificates are in non-standard locations, set -cadir or use -cafile as needed.</p> <p>Example #3: Get web page</p> <pre class="doctools_example"> package require http package require tls set url "https://www.tcl.tk/" http::register https 443 [list ::tls::socket -autoservername 1 -require 1] # Check for error set token [http::geturl $url] if {[http::status $token] ne "ok"} { puts [format "Error %s" [http::status $token]] } # Get web page set data [http::data $token] puts $data # Cleanup ::http::cleanup $token </pre> <p>Example #4: Download file</p> <pre class="doctools_example"> package require http package require tls set url "https://wiki.tcl-lang.org/sitemap.xml" set filename [file tail $url] http::register https 443 [list ::tls::socket -autoservername 1 -require 1] # Get file set ch [open $filename wb] set token [::http::geturl $url -blocksize 65536 -channel $ch] # Cleanup close $ch ::http::cleanup $token </pre> |
︙ | ︙ |
Modified doc/tls.man
from [ec44612f22]
to [51bf793bc5].
︙ | ︙ | |||
650 651 652 653 654 655 656 | Version is the protocol version. [def [arg content_type]] Content type is the message content type. [def [arg message]] Message is more info from the [const SSL_trace] API. | < | 650 651 652 653 654 655 656 657 658 659 660 661 662 663 | Version is the protocol version. [def [arg content_type]] Content type is the message content type. [def [arg message]] Message is more info from the [const SSL_trace] API. [list_end] [opt_def session [arg "channelId session_id session_ticket lifetime"]] This form of callback is invoked by the OpenSSL function [fun SSL_CTX_sess_set_new_cb()] whenever a new session id is sent by the server during the initial connection and handshake and also during the session |
︙ | ︙ | |||
675 676 677 678 679 680 681 | [def [arg lifetime]] Lifetime is the ticket lifetime in seconds. [list_end] [opt_def verify [arg "channelId depth cert status error"]] | | | 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 | [def [arg lifetime]] Lifetime is the ticket lifetime in seconds. [list_end] [opt_def verify [arg "channelId depth cert status error"]] This callback was moved to [option -validatecommand] in TclTLS 1.8. [list_end] [subsection "Values for Password Callback"] The callback for the [option -password] option is invoked by TclTLS whenever OpenSSL needs to obtain a password. See below for the possible arguments passed to the |
︙ | ︙ | |||
823 824 825 826 827 828 829 | [emph "The use of the variable [var tls::debug] is not recommended. It may be removed from future releases."] [section "Debug Examples"] These examples use the default Unix platform SSL certificates. For standard installations, -cadir and -cafile should not be needed. If your certificates | | | | > | 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 | [emph "The use of the variable [var tls::debug] is not recommended. It may be removed from future releases."] [section "Debug Examples"] These examples use the default Unix platform SSL certificates. For standard installations, -cadir and -cafile should not be needed. If your certificates are in non-standard locations, specify -cadir or -cafile as needed. [para] Example #1: Use HTTP package [example { package require http package require tls set url "https://www.tcl.tk/" http::register https 443 [list ::tls::socket -autoservername 1 -require 1 \ -command ::tls::callback -password ::tls::password \ -validatecommand ::tls::validate_command] # Check for error set token [http::geturl $url] if {[http::status $token] ne "ok"} { puts [format "Error %s" [http::status $token]] } |
︙ | ︙ | |||
861 862 863 864 865 866 867 | [example { package require tls set url "www.tcl-lang.org" set port 443 | | | | | 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 | [example { package require tls set url "www.tcl-lang.org" set port 443 set ch [tls::socket -autoservername 1 -servername $url -require 1 \ -alpn {http/1.1} -command ::tls::callback -password ::tls::password \ -validatecommand ::tls::validate_command $url $port] chan configure $ch -buffersize 65536 tls::handshake $ch puts $ch "GET / HTTP/1.1" flush $ch after 500 set data [read $ch] |
︙ | ︙ | |||
897 898 899 900 901 902 903 | [example { package require http package require tls set url "https://www.tcl.tk/" | | | 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 | [example { package require http package require tls set url "https://www.tcl.tk/" http::register https 443 [list ::tls::socket -autoservername 1 -require 1] # Check for error set token [http::geturl $url] if {[http::status $token] ne "ok"} { puts [format "Error %s" [http::status $token]] } |
︙ | ︙ | |||
923 924 925 926 927 928 929 | package require http package require tls set url "https://wiki.tcl-lang.org/sitemap.xml" set filename [file tail $url] | | | 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 | package require http package require tls set url "https://wiki.tcl-lang.org/sitemap.xml" set filename [file tail $url] http::register https 443 [list ::tls::socket -autoservername 1 -require 1] # Get file set ch [open $filename wb] set token [::http::geturl $url -blocksize 65536 -channel $ch] # Cleanup close $ch |
︙ | ︙ |
Modified doc/tls.n
from [4871edf916]
to [68573cb13e].
︙ | ︙ | |||
879 880 881 882 883 884 885 | Version is the protocol version\&. .TP \fIcontent_type\fR Content type is the message content type\&. .TP \fImessage\fR Message is more info from the \fBSSL_trace\fR API\&. | < | 879 880 881 882 883 884 885 886 887 888 889 890 891 892 | Version is the protocol version\&. .TP \fIcontent_type\fR Content type is the message content type\&. .TP \fImessage\fR Message is more info from the \fBSSL_trace\fR API\&. .RE .TP \fBsession\fR \fIchannelId session_id session_ticket lifetime\fR This form of callback is invoked by the OpenSSL function \fBSSL_CTX_sess_set_new_cb()\fR whenever a new session id is sent by the server during the initial connection and handshake and also during the session if the \fB-post_handshake\fR option is set to true\&. This callback is new for |
︙ | ︙ | |||
901 902 903 904 905 906 907 | Ticket is the session ticket info .TP \fIlifetime\fR Lifetime is the ticket lifetime in seconds\&. .RE .TP \fBverify\fR \fIchannelId depth cert status error\fR | | | 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 | Ticket is the session ticket info .TP \fIlifetime\fR Lifetime is the ticket lifetime in seconds\&. .RE .TP \fBverify\fR \fIchannelId depth cert status error\fR This callback was moved to \fB-validatecommand\fR in TclTLS 1\&.8\&. .PP .SS "VALUES FOR PASSWORD CALLBACK" The callback for the \fB-password\fR option is invoked by TclTLS whenever OpenSSL needs to obtain a password\&. See below for the possible arguments passed to the callback script\&. The user provided password is expected to be returned by the callback\&. .TP |
︙ | ︙ | |||
1019 1020 1021 1022 1023 1024 1025 | \fB-validatecommand\fR option is set to \fBtls::validate_command\fR\&. .PP \fIThe use of the variable \fBtls::debug\fR is not recommended\&. It may be removed from future releases\&.\fR .SH "DEBUG EXAMPLES" These examples use the default Unix platform SSL certificates\&. For standard installations, -cadir and -cafile should not be needed\&. If your certificates | | | | 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 | \fB-validatecommand\fR option is set to \fBtls::validate_command\fR\&. .PP \fIThe use of the variable \fBtls::debug\fR is not recommended\&. It may be removed from future releases\&.\fR .SH "DEBUG EXAMPLES" These examples use the default Unix platform SSL certificates\&. For standard installations, -cadir and -cafile should not be needed\&. If your certificates are in non-standard locations, specify -cadir or -cafile as needed\&. .PP Example #1: Use HTTP package .CS package require http package require tls set url "https://www\&.tcl\&.tk/" http::register https 443 [list ::tls::socket -autoservername 1 -require 1 -command ::tls::callback -password ::tls::password -validatecommand ::tls::validate_command] # Check for error set token [http::geturl $url] if {[http::status $token] ne "ok"} { puts [format "Error %s" [http::status $token]] } |
︙ | ︙ | |||
1056 1057 1058 1059 1060 1061 1062 | package require tls set url "www\&.tcl-lang\&.org" set port 443 | | | 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 | package require tls set url "www\&.tcl-lang\&.org" set port 443 set ch [tls::socket -autoservername 1 -servername $url -require 1 -alpn {http/1\&.1} -command ::tls::callback -password ::tls::password -validatecommand ::tls::validate_command $url $port] chan configure $ch -buffersize 65536 tls::handshake $ch puts $ch "GET / HTTP/1\&.1" flush $ch after 500 set data [read $ch] |
︙ | ︙ | |||
1088 1089 1090 1091 1092 1093 1094 | package require http package require tls set url "https://www\&.tcl\&.tk/" | | | 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 | package require http package require tls set url "https://www\&.tcl\&.tk/" http::register https 443 [list ::tls::socket -autoservername 1 -require 1] # Check for error set token [http::geturl $url] if {[http::status $token] ne "ok"} { puts [format "Error %s" [http::status $token]] } |
︙ | ︙ | |||
1115 1116 1117 1118 1119 1120 1121 | package require http package require tls set url "https://wiki\&.tcl-lang\&.org/sitemap\&.xml" set filename [file tail $url] | | | 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 | package require http package require tls set url "https://wiki\&.tcl-lang\&.org/sitemap\&.xml" set filename [file tail $url] http::register https 443 [list ::tls::socket -autoservername 1 -require 1] # Get file set ch [open $filename wb] set token [::http::geturl $url -blocksize 65536 -channel $ch] # Cleanup close $ch |
︙ | ︙ |