[331] | 1 | # mruby-tls-openssl
|
---|
| 2 |
|
---|
| 3 | "mruby-tls-openssl" is a TLS library for mruby using OpenSSL.
|
---|
| 4 | Though very small number of APIs are implemented currently, you can write a [HTTP2 client](https://github.com/iij/mruby-tls-openssl/blob/master/http2.rb) with it.
|
---|
| 5 |
|
---|
| 6 | ## API
|
---|
| 7 |
|
---|
| 8 | - TLS.new(host, opts={})
|
---|
| 9 | - Open a new TLS connection to `host`. `host` can be either a hostname
|
---|
| 10 | (String) or a TCP socket (TCPSocket).
|
---|
| 11 | - Supported keys in `opts`:
|
---|
| 12 | - :alpn => str
|
---|
| 13 | - send str as a protocol for ALPN
|
---|
| 14 | - :certs => str
|
---|
| 15 | - pathname of the file contains trusted root CA certificate(s)
|
---|
| 16 | - :identity => str
|
---|
| 17 | - a server's identity expected
|
---|
| 18 | - :ignore_certificate_validity => boolean
|
---|
| 19 | - ignore "Not Before" and "Not After" fields of certificates
|
---|
| 20 | - :port => Integer
|
---|
| 21 | - port number (used only when `host` is a string)
|
---|
| 22 | - :sni => false (default) | true | String
|
---|
| 23 | - use Server Name Indication (SNI)
|
---|
| 24 | - false : don't send SNI extention
|
---|
| 25 | - true : send `opts[:identity]` or `host` as a server name
|
---|
| 26 | - String : send it as a server name
|
---|
| 27 | - :version => str
|
---|
| 28 | - TLS version: one of "TLSv1.0", "TLSv1.1", "TLSv1.2", or "any"
|
---|
| 29 | - TLS#read(len=)
|
---|
| 30 | - Read `len` bytes from TLS connection.
|
---|
| 31 | - TLS#write(str)
|
---|
| 32 | - Write str to TLS connection.
|
---|
| 33 | - TLS#close
|
---|
| 34 | - Close TLS connection
|
---|
| 35 |
|
---|
| 36 | ## Example
|
---|
| 37 |
|
---|
| 38 | ```Ruby
|
---|
| 39 | # verify server's identity
|
---|
| 40 | tls = TLS.new "github.com", { :port => 443, :certs => "digicert.crt", :identity => "github.com" }
|
---|
| 41 | tls.write "GET / HTTP/1.1\r\nHost: github.com\r\nConnection: close\r\n\r\n"
|
---|
| 42 | p tls.read
|
---|
| 43 | tls.close
|
---|
| 44 | ```
|
---|
| 45 |
|
---|
| 46 | ## How to use TLS ALPN Extension
|
---|
| 47 |
|
---|
| 48 | If you want to use TLS ALPN Extension, build and install OpenSSL 1.0.2
|
---|
| 49 | (or later) into `openssldir` directory:
|
---|
| 50 |
|
---|
| 51 | ```
|
---|
| 52 | % cd mruby-tls-openssl
|
---|
| 53 | % curl https://www.openssl.org/source/openssl-1.0.2a.tar.gz | tar xzf -
|
---|
| 54 | % cd openssl-1.0.2a
|
---|
| 55 | % ./config --openssldir=`pwd`/../openssldir no-shared no-threads
|
---|
| 56 | % make
|
---|
| 57 | % make install
|
---|
| 58 | ```
|
---|
| 59 |
|
---|
| 60 | then build mruby.
|
---|
| 61 |
|
---|
| 62 |
|
---|
| 63 | ## Compile with LibreSSL
|
---|
| 64 |
|
---|
| 65 | To try [LibreSSL](http://www.libressl.org), install it to `openssldir`:
|
---|
| 66 |
|
---|
| 67 | ```
|
---|
| 68 | % cd mruby-tls-openssl
|
---|
| 69 | % curl -O http://ftp.openbsd.org/pub/OpenBSD/LibreSSL/libressl-2.1.4.tar.gz
|
---|
| 70 | % tar xzf libressl-2.1.4.tar.gz
|
---|
| 71 | % cd libressl-2.1.4
|
---|
| 72 | % ./configure --disable-shared --prefix=`pwd`/../openssldir
|
---|
| 73 | % make
|
---|
| 74 | % make install
|
---|
| 75 | ```
|
---|
| 76 |
|
---|
| 77 |
|
---|
| 78 | ## License
|
---|
| 79 |
|
---|
| 80 | Copyright (c) 2014 Internet Initiative Japan Inc.
|
---|
| 81 |
|
---|
| 82 | Permission is hereby granted, free of charge, to any person obtaining a
|
---|
| 83 | copy of this software and associated documentation files (the "Software"),
|
---|
| 84 | to deal in the Software without restriction, including without limitation
|
---|
| 85 | the rights to use, copy, modify, merge, publish, distribute, sublicense,
|
---|
| 86 | and/or sell copies of the Software, and to permit persons to whom the
|
---|
| 87 | Software is furnished to do so, subject to the following conditions:
|
---|
| 88 |
|
---|
| 89 | The above copyright notice and this permission notice shall be included in
|
---|
| 90 | all copies or substantial portions of the Software.
|
---|
| 91 |
|
---|
| 92 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
---|
| 93 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
---|
| 94 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
---|
| 95 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
---|
| 96 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
|
---|
| 97 | FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
|
---|
| 98 | DEALINGS IN THE SOFTWARE.
|
---|