GSoap工作原理简析

1. 前言
   因为工作原因，接触GSoap已有大半年时间，春节闲来无事，简单写一下半年来对GSoap的理解。

2. 服务端

   int main() 
   {
       #ifdef WITH_OPENSSL
       //1、初始化OpenSSL(系统会自动初始化SSL，故可跳过此函数)
       //函数会调用SSL_library_init()、OpenSSL_add_all_algorithms()、SSL_load_error_strings()等，用于初始化SSL、加载加密算法及错误信息等。初始化后soap_ssl_init_done=1，表示已初始化以避免重复初始化。
       soap_ssl_init();
   
       //2、对于多线程应用，OpenSSL要求显示安装互斥锁，由此需调用 CRYPTO_thread_setup()、CRYPTO_thread_cleanup()
       //函数定义：sslclient.c
       //作用：
       //1）新建41个锁对象（crypto.h，宏CRYPTO_NUM_LOCKS定义锁数目）
       //2）设置获取当前线程ID、动态创建锁、进入/退出锁、释放锁等回调函数
       if (CRYPTO_thread_setup())  
       { 
           fprintf(stderr, "Cannot setup thread mutex\n"); 
           exit(1); 
       }   
       #endif
   
       struct soap soap, *tsoap;
       //3、初始化GSoap，包括设置测试/发送/接收日志、accept/connect/close/send/recv回调函数等。
       soap_init(&soap);
   
       //4、初始化SSL上下文环境
       //定义于stdsoap2.cpp
       //作用：初始化 struct soap结构体、设置验证结果回调函数（主要用于输出错误信息）
       if (soap_ssl_server_context(
           &soap, 
           SOAP_SSL_DEFAULT,       // flag
           "server.pem",           // 服务端密钥文件，当客户端需对服务端进行身份验证时，提供此参数
           "password",             // 服务端密钥文件的密码
           "cacert.pem",           // CA证书，包含所有可信任的客户端证书。当服务端需对客户端进行身份验证时，提供此参数    
           NULL,                   // CA证书证书所在的路径  。当希望避免在不安全系统中使用默认路径存储CA证书时，可在指定CA证书时直接指定路径或在此参数指定路径。                                                        
           "dh512.pem",            // DH（密钥交换协议/算法）文件名或字节所表示的DH密钥长(最小长度为 512, e.g."512")，若为 NULL，则使用RSA
           NULL,                   // 随机文件，若认证过程需利用包含随机数据的文件确定随机性，则填写随机文件名，否则填写 NULL
           NULL                    // 启用 SSL会话缓存的服务器标识（标识必须唯一）
       ))
       { 
           soap_print_fault(&soap, stderr); 
           exit(1); 
       } 
   
       //5、设置等待请求与发送/接受数据超时时间
       soap.accept_timeout = 60;
       soap.send_timeout = soap.recv_timeout = 30; 
   SOAP_SOCKET mbindSocket; 
   
       //6、设置服务端IP、监听端口号、请求队列最大长度
       //host=NULL，表示当前主机；backlog：请求队列最大长度，Linux系统默认为128，Windows系统下无确定值。
       SOAP_SOCKET mbindSocket = soap_bind(&soap, "127.0.0.1", 9000, 1000);
       if (!soap_valid_socket(mbindSocket))
       {
           exit(1);
       }
   
       for (;;) 
       { 
           //7、等待客户端的连接
           //定义：stdsoap2.cpp
           //原理：首先利用select模型判断判断read/write/error socket状态，然后调用accept()
           SOAP_SOCKET s = soap_accept(&soap);                     
           if (!soap_valid_socket(s)) 
           { 
               if (soap->errnum)
               {
                   continue;        // retry 
               }
               soap_destroy(soap);  // dealloc C++ data
               soap_end(soap);      // dealloc data and clean up
               continue;
           }   
   
           //8、创建新的soap运行时环境(Runtime enviroment)，深拷贝，新创建的 soap 与原先的soap runtime enviroment 是相互独立的  
           //should call soap_ssl_accept on a copy 
           struct soap *tsoap = soap_copy(&soap);                  
           if (!tsoap) 
           { 
               continue;  
           }
   
           pthread_t tid;
           pthread_create(&tid, NULL, &process_request, (void*)tsoap); 
       } 
   
       soap_destroy(&soap);     // 释放所有动态分配的对象，包括soap类实例链表clist中所有实例  
       soap_end(&soap);         // 除类实例之外，删除临时数据和反序列化数据  包括属性链表等临时数据、内存分配 (malloc) 列表、关闭SSL连接和Socket
       soap_done(&soap);        // 释放ctx，包括Reset, close communications, and remove callbacks等。必须在CRYPTO_thread_cleanup之前调用。    
       CRYPTO_thread_cleanup(); // 取消各回调函数、销毁锁对象。在多线程环境中必须使用。      
   
       return 0; 
   }
   
   void *process_request(void *soap) 
   { 
       pthread_detach(pthread_self()); // 将子线程的状态设置为detached，则线程结束后将自动释放所有资源。pthread_self()：获取线程本身的ID。非阻塞函数。
   
   #ifdef WITH_OPENSSL
   
       //soap_ssl_accept()：执行SSL/TLS握手，建立安全的SSL通道
       //serve()：处理客户端请求
       if (soap_ssl_accept(m_psoap) != SOAP_OK || serve() != SOAP_OK)
       {
       }
   
   #else
   
       if (serve() != SOAP_OK)
       {
       }
   
   #endif  
   
   soap_destroy((struct soap*)soap); // 释放所有动态分配的对象                
   soap_end((struct soap*)soap);     // 除类实例之外，删除临时数据和反序列化数据                   
   soap_free((struct soap*)soap);    // 释放 context
   
   return NULL; 
   }
   

3. soap_ssl_server_context：flags

   宏	值	描述
   SOAP_SSL_NO_AUTHENTICATION	0x00	不启用证书验证，通常用于测试
   SOAP_SSL_REQUIRE_SERVER_AUTHENTICATION	0x01	服务端需对客户端进行身份验证
   SOAP_SSL_REQUIRE_CLIENT_AUTHENTICATION	0x02	客户端需对服务端进行身份验证
   SOAP_SSL_SKIP_HOST_CHECK	0x04	不检查证书中主机的common name
   SOAP_SSL_ALLOW_EXPIRED_CERTIFICATE	0x08	不检查证书的失效日期
   SOAP_SSL_NO_DEFAULT_CA_PATH	0x10	不使用 default_verify_paths
   SOAP_SSL_RSA	0x20	使用RSA
   SOAP_SSLv3	0x40	SSL v3 only
   SOAP_TLSv1	0x80	TLS v1 only
   SOAP_SSLv3_TLSv1	0x00	SSL v3 and TLS v1 support by default (no SSL v1/v2)
   SOAP_SSL_CLIENT	0x100	client context
   SOAP_SSL_DEFAULT		SOAP_SSL_REQUIRE_SERVER_AUTHENTICATION“或操作符” SOAP_SSLv3_TLSv1

4. soap_ssl_accept()
   简介：soap_accept() 之后调用，用于执行 SSL/TLS 握手，建立安全的SSL通道。

   作用：
   1）fsslauth();
   // 实际调用的是ssl_auth_init()。

   2）若未初始化OpenSSL，调用soap_ssl_init()。

   3）soap->ctx = SSL_CTX_new(SSLv23_method());
   // 建立SSL所用的method、申请SSL会话的环境（创建新的 SSL_CTX对象 作为建立 TLS/SSL 的框架）

   4）SSL_CTX_set_mode(soap->ctx,SSL_MODE_ENABLE_PARTIAL_WRITE | SSL_MODE_AUTO_RETRY);
   // 设置握手模式，允许写完或部分写完时成功返回，SSL_write(…, n) to return r with 0 < r < n。只有握手并且成功完成后，read/write才会返回

   5）RAND_load_file(soap->randfile, -1);
   // 从随机数种子文件中读取数据，-1：读取整个文件

   6）SSL_CTX_load_verify_locations(soap->ctx, soap->cafile, soap->capath);
   // 加载证书：SSL_CTX*，证书文件的名称，证书文件的路径

   7）SSL_CTX_set_client_CA_list(soap->ctx, SSL_load_client_CA_file(soap->cafile));
   // SOAP_SSL_REQUIRE_CLIENT_AUTHENTICATION：需要客户端验证时，服务器从CAfile加载可信任CA证书，并发往客户端

   8）SSL_CTX_set_default_verify_paths(soap->ctx);
   // 若!SOAP_SSL_NO_DEFAULT_CA_PATH，即使用默认验证路径，则从默认路径加载CA证书

   9）SSL_CTX_use_certificate_chain_file(soap->ctx, soap->keyfile);
   // 为SSL加载本应用证书所属的证书链

   10）SSL_CTX_set_default_passwd_cb_userdata(soap->ctx, (void*)soap->password);
   // 设置读取私钥的密码

   11）RSA *rsa = RSA_generate_key(SOAP_SSL_RSA_BITS, RSA_F4, NULL, NULL);
   SSL_CTX_set_tmp_rsa(soap->ctx, rsa);
   // 若使用RSA密钥交换算法，生成密钥对; 设置RSA密钥
   // 若采用非RSA密钥交换算法，则根据指定的算法 生成并设置密钥参数

   12）SSL_CTX_set_verify(soap->ctx, mode, soap->fsslverify);
   // 指定验证方式，mode：是否验证客户端或服务端等，fsslverify：验证结果回调函数，主要用于当验证失败时输出错误信息。

   13）SSL_CTX_set_verify_depth(soap->ctx, 9);
   // 设置允许ctx可验证的最大证书链深度

   14）struct soap *soap;
   soap->ssl = SSL_new(soap->ctx);
   // 申请一个SSL套接字

   15）BIO *bio = BIO_new_socket((int)sk, BIO_NOCLOSE);
   // 根据给定的sock返回一个socket类型的BIO SOAP_SOCKET sk —>>> 输入参数

   16）SSL_set_bio(soap->ssl, bio, bio);
   // 将SSL与bio联系起来

   17）r = SSL_accept(soap->ssl);
   // 等待一个TLS/SSL客户端启动TLS/SSL握手

   18）tcp_select();
   // 采用select模型，判断是否有新的客户端连接或可读数据到达

   19）若指定：SOAP_SSL_REQUIRE_CLIENT_AUTHENTICATION，即服务器需对客户端进行身份验证，则：
   SSL_get_verify_result(soap->ssl);
   // 对SSL中证书进行验证，并返回验证结果
   // 若验证通过，则：
   X509 *peer = SSL_get_peer_certificate(soap->ssl);
   // 从SSL套接字中提取对方的证书信息
   X509_free(peer);
   // 释放证书

   20）若soap指定了recv_timeout/send_timeout，则soap被设置为阻塞模式，否则为非阻塞模式。

5. serve()
   soap_begin_serve(struct soap*)：
   // 开始处理soap
   具体包括：
   1）soap_begin(soap);
   // 初始化soap的成员变量，并释放可能存在的内存占用

   2）soap_begin_recv(soap);
   // 准备接收数据。实际上在这里就完成了报文的接收。
   // 内部调用了函数：#define soap_get1(soap) (((soap)->bufidx>=(soap)->buflen && soap_recv(soap)) ? EOF : (unsigned char)(soap)->buf[(soap)->bufidx++])，该函数将报文全部存入缓冲区soap->buf，bufidx标明报文长度，buflen标明buf缓冲区长度。

   3）soap_envelope_begin_in(struct soap *soap);
   // 从buf中找寻envelope开始标签(begin)，in代表是从buf中解析结构 out代表把结构填充到buf。

   4）soap_recv_header(struct soap *soap);
   // 解析xml数据放置于soap->header。

   5）soap_body_begin_in(soap));
   // 与前面的两个函数功能类似。

   dispatch()：
   // 将soap->tag与各接口名逐一对比，匹配成功后，调用相应接口函数。