← Back to branch summary

~ubuntu-branches/ubuntu/trusty/ocamlnet/trusty

« back to all changes in this revision

Viewing changes to src/equeue-ssl/https_client.mli

  • Committer: Bazaar Package Importer
  • Author(s): Stéphane Glondu
  • Date: 2011-09-02 14:12:33 UTC
  • mfrom: (18.2.3 sid)
  • Revision ID: james.westby@ubuntu.com-20110902141233-zbj0ygxb92u6gy4z
Tags: 3.4-1
http://bugs.debian.org/637147
* New upstream release
  - add a new NetcgiRequire directive to ease dependency management
    (Closes: #637147)
  - remove patches that were applied upstream:
    + Added-missing-shebang-lines-in-example-shell-scripts
    + Try-also-ocamlc-for-POSIX-threads

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/equeue-ssl/https_client.mli
 
1
(* $Id: https_client.mli 1614 2011-06-09 15:08:56Z gerd $ *)
 
2
 
 
3
(** HTTPS extension to {!Http_client} *)
 
4
 
 
5
type channel_binding_id = int
 
6
(** Same as {!Http_client.channel_binding_id} *)          
 
7
 
 
8
class type transport_channel_type =
 
9
object
 
10
  method setup_e : Unix.file_descr -> channel_binding_id -> float -> exn -> 
 
11
                   string -> int -> Unixqueue.event_system ->
 
12
                   Uq_engines.multiplex_controller Uq_engines.engine
 
13
  method continue : Unix.file_descr -> channel_binding_id -> float -> exn ->
 
14
                   string -> int -> Unixqueue.event_system ->
 
15
                   Uq_engines.multiplex_controller
 
16
end
 
17
(** Same as {!Http_client.transport_channel_type} *)      
 
18
 
 
19
val https_transport_channel_type : Ssl.context -> transport_channel_type
 
20
  (** Configures a TLS tunnel for this context *)
 
21
 
 
22
(** {2 How to configure a pipeline for TLS}
 
23
 
 
24
    Just follow this recipe:
 
25
 
 
26
    1. Create the [Ssl] context:
 
27
 
 
28
    {[ Ssl.init() ]}
 
29
 
 
30
    {[ let ctx = Ssl.create_context Ssl.TLSv1 Ssl.Client_context ]}
 
31
 
 
32
    2. Create the transport channel type:
 
33
 
 
34
    {[ let tct = Https_client.https_transport_channel_type ctx ]}
 
35
 
 
36
    3. Configure the transport:
 
37
 
 
38
    {[ pipeline # configure_transport Http_client.https_cb_id tct ]}
 
39
 
 
40
    Now all URLs starting with "https://" will use this transport.
 
41
    If you need more control about the type of SSL/TLS channel, you
 
42
    can create new channel binding IDs, and configure these in addition.
 
43
    For each message needing a specific context, just set the
 
44
    channel binding ID (method [set_channel_binding] of the message).
 
45
 *)
 
46
 
 
47
(** {2 How to configure the Convenience module}
 
48
 
 
49
    Just do once:
 
50
 
 
51
    {[
 
52
    Ssl.init();
 
53
    Http_client.Convenience.configure_pipeline
 
54
      (fun p ->
 
55
         let ctx = Ssl.create_context Ssl.TLSv1 Ssl.Client_context in
 
56
         let tct = Https_client.https_transport_channel_type ctx in
 
57
         p # configure_transport Http_client.https_cb_id tct
 
58
      )
 
59
    ]}
 
60
 
 
61
    This will enable "https" for the functions in {!Http_client.Convenience},
 
62
    e.g. {[ let data = Http_client.Convenience.http_get "https://url" ]}
 
63
 
 
64
 *)
 
65
 
 
66
(** {2 How to configure {!Http_fs}}
 
67
 
 
68
    Just do once:
 
69
 
 
70
    {[
 
71
    Ssl.init()
 
72
    ]}
 
73
 
 
74
    and create the [http_fs] object with
 
75
 
 
76
    {[
 
77
    Http_fs.http_fs 
 
78
      ~config_pipeline:(
 
79
        fun p ->
 
80
          let ctx = Ssl.create_context Ssl.TLSv1 Ssl.Client_context in
 
81
          let tct = Https_client.https_transport_channel_type ctx in
 
82
          p # configure_transport Http_client.https_cb_id tct
 
83
      )
 
84
      "https://root-url"
 
85
    ]}
 
86
 
 
87
 *)
 
88
 
 
89
 
 
90
(** {2 Features and limitations} 
 
91
 
 
92
    We only implement RFC 2618, i.e. secure connections on a separate
 
93
    port (443 instead of 80). There is no support (yet) for RFC 2617,
 
94
    i.e. upgrading an existing insecure connection to a secure one.
 
95
 
 
96
    If an HTTP proxy server is configured, the TLS connection is established
 
97
    via the CONNECT method (documented in RFC 2617).
 
98
 
 
99
    Alternatively, it is also possible to connect via SOCKS version 5
 
100
    proxies.
 
101
 
 
102
    There is, so far, no support for reusing TLS sessions across connections.
 
103
    For every connection a new TLS session is created.
 
104
 *)