From 9ce7494cda368d85701058cea950912b5eeea237 Mon Sep 17 00:00:00 2001 From: technorama Date: Tue, 3 Apr 2007 18:29:30 +0000 Subject: [PATCH] * ext/openssl/ossl_ssl.c: Add documentation. git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@12142 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- ChangeLog | 10 ++-- ext/openssl/ossl_ssl.c | 106 ++++++++++++++++++++++++++++++++++++++++- 2 files changed, 111 insertions(+), 5 deletions(-) diff --git a/ChangeLog b/ChangeLog index 2ca3afa293..febfc58c00 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,7 @@ +Tue Apr 4 04:17:18 2007 Technorama Ltd. + + * ext/openssl/ossl_ssl.c: Add documentation. + Tue Apr 3 16:22:24 2007 Nobuyoshi Nakada * ext/openssl/extconf.rb: check for functions added in 1.9. @@ -5,7 +9,7 @@ Tue Apr 3 16:22:24 2007 Nobuyoshi Nakada * ext/openssl/ruby_missing.h: check per features instead by checking version code. [ruby-core:10845] -Tue Apr 3 16:02:44 2007 Technorama +Tue Apr 3 16:02:44 2007 Technorama Ltd. * ext/openssl/ossl_bn.c: More documentation. @@ -22,7 +26,7 @@ Tue Apr 3 09:36:55 2007 NAKAMURA Usaku * ext/openssl/ruby_missing.h: need to include version.h to check RUBY_VERSION_CODE. -Mon Apr 3 07:10:12 2007 Technorama +Mon Apr 3 07:10:12 2007 Technorama Ltd. * ext/openssl/ossl_{ssl.[ch],ssl_session.c}, ext/openssl/lib/openssl/lib/openssl/ssl.rb: @@ -30,7 +34,7 @@ Mon Apr 3 07:10:12 2007 Technorama config, and statistics methods. -Mon Apr 3 04:00:23 2007 Technorama +Mon Apr 3 04:00:23 2007 Technorama Ltd. * ext/openssl/{ossl.[ch],ossl_pkey.c} Add documentation. diff --git a/ext/openssl/ossl_ssl.c b/ext/openssl/ossl_ssl.c index e1df249dbc..76423b773b 100644 --- a/ext/openssl/ossl_ssl.c +++ b/ext/openssl/ossl_ssl.c @@ -141,6 +141,14 @@ ossl_sslctx_s_alloc(VALUE klass) return Data_Wrap_Struct(klass, 0, ossl_sslctx_free, ctx); } +/* + * call-seq: + * SSLContext.new => ctx + * SSLContext.new(:TLSv1) => ctx + * SSLContext.new("SSLv23_client") => ctx + * + * You can get a list of valid methods with OpenSSL::SSL::SSLContext::METHODS + */ static VALUE ossl_sslctx_initialize(int argc, VALUE *argv, VALUE self) { @@ -573,6 +581,10 @@ ossl_ssl_cipher_to_ary(SSL_CIPHER *cipher) return ary; } +/* + * call-seq: + * ctx.ciphers => [[name, version, bits, alg_bits], ...] + */ static VALUE ossl_sslctx_get_ciphers(VALUE self) { @@ -601,6 +613,12 @@ ossl_sslctx_get_ciphers(VALUE self) return ary; } +/* + * call-seq: + * ctx.ciphers = "cipher1:cipher2:..." + * ctx.ciphers = [name, ...] + * ctx.ciphers = [[name, version, bits, alg_bits], ...] + */ static VALUE ossl_sslctx_set_ciphers(VALUE self, VALUE v) { @@ -822,6 +840,20 @@ ossl_ssl_s_alloc(VALUE klass) return Data_Wrap_Struct(klass, 0, ossl_ssl_free, NULL); } +/* + * call-seq: + * SSLSocket.new(io) => aSSLSocket + * SSLSocket.new(io, ctx) => aSSLSocket + * + * === Parameters + * * +io+ is a real ruby IO object. Not an IO like object that responds to read/write. + * * +ctx+ is an OpenSSLSSL::SSLContext. + * + * The OpenSSL::Buffering module provides additional IO methods. + * + * This method will freeze the SSLContext if one is provided; + * however, session management is still allowed in the frozen SSLContext. + */ static VALUE ossl_ssl_initialize(int argc, VALUE *argv, VALUE self) { @@ -919,6 +951,10 @@ ossl_start_ssl(VALUE self, int (*func)(), const char *funcname) return self; } +/* + * call-seq: + * ssl.connect => self + */ static VALUE ossl_ssl_connect(VALUE self) { @@ -926,6 +962,10 @@ ossl_ssl_connect(VALUE self) return ossl_start_ssl(self, SSL_connect, "SSL_connect"); } +/* + * call-seq: + * ssl.accept => self + */ static VALUE ossl_ssl_accept(VALUE self) { @@ -933,6 +973,15 @@ ossl_ssl_accept(VALUE self) return ossl_start_ssl(self, SSL_accept, "SSL_accept"); } +/* + * call-seq: + * ssl.sysread(length) => string + * ssl.sysread(length, buffer) => buffer + * + * === Parameters + * * +length+ is a positive integer. + * * +buffer+ is a string used to store the result. + */ static VALUE ossl_ssl_read(int argc, VALUE *argv, VALUE self) { @@ -990,6 +1039,10 @@ ossl_ssl_read(int argc, VALUE *argv, VALUE self) return str; } +/* + * call-seq: + * ssl.syswrite(string) => integer + */ static VALUE ossl_ssl_write(VALUE self, VALUE str) { @@ -1030,6 +1083,10 @@ ossl_ssl_write(VALUE self, VALUE str) return INT2NUM(nwrite); } +/* + * call-seq: + * ssl.sysclose => nil + */ static VALUE ossl_ssl_close(VALUE self) { @@ -1043,6 +1100,10 @@ ossl_ssl_close(VALUE self) return Qnil; } +/* + * call-seq: + * ssl.cert => cert or nil + */ static VALUE ossl_ssl_get_cert(VALUE self) { @@ -1067,6 +1128,10 @@ ossl_ssl_get_cert(VALUE self) return ossl_x509_new(cert); } +/* + * call-seq: + * ssl.peer_cert => cert or nil + */ static VALUE ossl_ssl_get_peer_cert(VALUE self) { @@ -1092,6 +1157,10 @@ ossl_ssl_get_peer_cert(VALUE self) return obj; } +/* + * call-seq: + * ssl.peer_cert_chain => [cert, ...] or nil + */ static VALUE ossl_ssl_get_peer_cert_chain(VALUE self) { @@ -1118,6 +1187,10 @@ ossl_ssl_get_peer_cert_chain(VALUE self) return ary; } +/* + * call-seq: + * ssl.cipher => [name, version, bits, alg_bits] + */ static VALUE ossl_ssl_get_cipher(VALUE self) { @@ -1134,6 +1207,10 @@ ossl_ssl_get_cipher(VALUE self) return ossl_ssl_cipher_to_ary(cipher); } +/* + * call-seq: + * ssl.state => string + */ static VALUE ossl_ssl_get_state(VALUE self) { @@ -1153,6 +1230,10 @@ ossl_ssl_get_state(VALUE self) return ret; } +/* + * call-seq: + * ssl.pending => integer + */ static VALUE ossl_ssl_pending(VALUE self) { @@ -1223,6 +1304,7 @@ void Init_ossl_ssl() { int i; + VALUE ary; #if 0 /* let rdoc know about mOSSL */ mOSSL = rb_define_module("OpenSSL"); @@ -1241,7 +1323,14 @@ Init_ossl_ssl() mSSL = rb_define_module_under(mOSSL, "SSL"); eSSLError = rb_define_class_under(mSSL, "SSLError", eOSSLError); - /* class SSLContext */ + /* class SSLContext + * + * The following attributes are available but don't show up in rdoc. + * All attributes must be set before calling SSLSocket.new(io, ctx). + * * cert, key, client_ca, ca_file, ca_path, timeout, verify_mode, verify_depth + * * client_cert_cb, tmp_dh_callback, session_id_context, + * * session_add_cb, session_new_cb, session_remove_cb + */ cSSLContext = rb_define_class_under(mSSL, "SSLContext", rb_cObject); rb_define_alloc_func(cSSLContext, ossl_sslctx_s_alloc); for(i = 0; i < numberof(ossl_sslctx_attrs); i++) @@ -1268,7 +1357,20 @@ Init_ossl_ssl() rb_define_method(cSSLContext, "session_cache_stats", ossl_sslctx_get_session_cache_stats, 0); rb_define_method(cSSLContext, "flush_sessions", ossl_sslctx_flush_sessions, -1); - /* class SSLSocket */ + ary = rb_ary_new2(numberof(ossl_ssl_method_tab)); + for (i = 0; i < numberof(ossl_ssl_method_tab); i++) { + rb_ary_push(ary, ID2SYM(rb_intern(ossl_ssl_method_tab[i].name))); + } + rb_obj_freeze(ary); + /* holds a list of available SSL/TLS methods */ + rb_define_const(cSSLContext, "METHODS", ary); + + /* class SSLSocket + * + * The following attributes are available but don't show up in rdoc. + * * io, context, sync_close + * + */ cSSLSocket = rb_define_class_under(mSSL, "SSLSocket", rb_cObject); rb_define_alloc_func(cSSLSocket, ossl_ssl_s_alloc); for(i = 0; i < numberof(ossl_ssl_attr_readers); i++)