Changeset 2970 for pjproject/trunk/pjlib/include/pj/ssl_sock.h

Timestamp:

Oct 26, 2009 3:47:52 PM (15 years ago)

Author:

nanang

Message:

Ticket #957:

• Added features in secure socket: handshake timeout timer, certificate info, renegotiation API.
• Added unit test for secure socket, along with testing purpose certificate & private key.
• Updated build configs for secure socket.

File:

• pjproject/trunk/pjlib/include/pj/ssl_sock.h (modified) (10 diffs)

pjproject/trunk/pjlib/include/pj/ssl_sock.h

@@ -61 +61 @@
 
 /**
+ * Describe structure of certificate info.
+ */
+typedef struct pj_ssl_cert_info {
+    pj_str_t    subject;            /**< Subject.               */
+    pj_str_t    issuer;             /**< Issuer.                */
+    unsigned    version;            /**< Certificate version.   */
+    pj_time_val validity_start;     /**< Validity start.        */
+    pj_time_val validity_end;       /**< Validity end.          */
+    pj_bool_t   validity_use_gmt;   /**< Flag if validity date/time 
+                                         use GMT.               */
+} pj_ssl_cert_info;
+
+
+/**
  * Create credential from files.
  *
@@ -67 +81 @@
  * @param privkey_file  The file of private key.
  * @param privkey_pass  The password of private key, if any.
+ * @param p_cert        Pointer to credential instance to be created.
  *
  * @return              PJ_SUCCESS when successful.
@@ -323 +338 @@
      */
     pj_bool_t established;
+
     /**
      * Describes secure socket protocol being used.
      */
     pj_ssl_sock_proto proto;
+
     /**
      * Describes cipher suite being used, this will only be set when connection
@@ -332 +349 @@
      */
     pj_ssl_cipher cipher;
+
     /**
      * Describes local address.
      */
     pj_sockaddr local_addr;
+
     /**
      * Describes remote address.
@@ -341 +360 @@
     pj_sockaddr remote_addr;
    
+    /**
+     * Describes active local certificate info.
+     */
+    pj_ssl_cert_info local_cert_info;
+   
+    /**
+     * Describes active remote certificate info.
+     */
+    pj_ssl_cert_info remote_cert_info;
+   
 } pj_ssl_sock_info;
 
@@ -368 +397 @@
      */
     pj_ioqueue_t *ioqueue;
+
+    /**
+     * Specify the timer heap to use. Secure socket uses the timer to provide
+     * auto cancelation on asynchronous operation when it takes longer time 
+     * than specified timeout period, e.g: security negotiation timeout.
+     */
+    pj_timer_heap_t *timer_heap;
 
     /**
@@ -431 +467 @@
 
     /**
-     * Specify buffer size for delayed send operation. This setting is only
-     * applied for some platforms that restrict more than one outstanding 
-     * send operation at a time, e.g: Symbian. So delaying/buffering send 
-     * mechanism is used to allow application to send data anytime without 
-     * worrying about current outstanding send operations.
+     * Specify buffer size for sending operation. Buffering sending data
+     * is used for allowing application to perform multiple outstanding 
+     * send operations. Whenever application specifies this setting too
+     * small, sending operation may return PJ_ENOMEM.
      *  
-     * Default value is 0, except for Symbian 8192 bytes.
+     * Default value is 8192 bytes.
      */
     pj_size_t send_buffer_size;
@@ -496 +531 @@
      * Default value is zero/not-set.
      */
-    pj_str_t servername;
+    pj_str_t server_name;
     
 } pj_ssl_sock_param;
@@ -692 +727 @@
  * @param flags         Flags to be given to pj_ioqueue_send().
  *
- *
  * @return              PJ_SUCCESS if data has been sent immediately, or
- *                      PJ_EPENDING if data cannot be sent immediately. In
- *                      this case the \a on_data_sent() callback will be
- *                      called when data is actually sent. Any other return
- *                      value indicates error condition.
+ *                      PJ_EPENDING if data cannot be sent immediately or
+ *                      PJ_ENOMEM when sending buffer could not handle all
+ *                      queued data, see \a send_buffer_size. The callback
+ *                      \a on_data_sent() will be called when data is actually
+ *                      sent. Any other return value indicates error condition.
  */
 PJ_DECL(pj_status_t) pj_ssl_sock_send(pj_ssl_sock_t *ssock,
@@ -787 +822 @@
 
 /**
+ * Starts SSL/TLS renegotiation over an already established SSL connection
+ * for this socket. This operation is performed transparently, no callback 
+ * will be called once the renegotiation completed successfully. However, 
+ * when the renegotiation fails, the connection will be closed and callback
+ * \a on_data_read() will be invoked with non-PJ_SUCCESS status code.
+ *
+ * @param ssock         The secure socket.
+ *
+ * @return              PJ_SUCCESS if renegotiation is completed immediately,
+ *                      or PJ_EPENDING if renegotiation has been started and
+ *                      waiting for completion, or the appropriate error code 
+ *                      on failure.
+ */
+PJ_DECL(pj_status_t) pj_ssl_sock_renegotiate(pj_ssl_sock_t *ssock);
+
+
+/**
  * @}
  */