Home > Language Reference > Classes

SslContext Class

  + Object
    + SslContext

Description

The SslContext class encapsulates the various properties of an SSL connection, such as certificates, encryption mode, and so on. It is always used in conjunction with a StreamSocket object. This class is instantiable and derivable. Note that SSL is only available on devices running Palm OS 5.0 and later.

To secure a socket communication with SSL using HB++, you simply have to specify an instance of this object as third parameter to the Connect method of your StreamSocket object. This will automatically start handshaking and certificate validation. If an error occurs during these steps, for example if the server provides a certificate which has expired, the SslContext class will raise a Verify event. By handling this event, your code can determine the exact reason of the failure, and optionaly instruct the library to ignore the error and to establish the connection anyway. By default (i.e. if your code does not respond to the Verify event), SSL errors cause the Connect method to fail.

A convenient way to catch events raised by an SslContext object is to derive your own class from this one, and then to use this derived class wherever an SslContext object is expected. A typical implementation for such a class will simply handle certificate validation errors, as shown below:

Private Sub SslContext_Verify(ByRef bIgnore As Boolean, ByVal eCode As HbSslVerify)
  Dim msg As String
  Dim ret As HbMsgBoxReturn

  If eCode<>hbSslVerifyOk Then
    Select Case eCode
      Case hbSslVerifyBadSignature
        msg="Bad signature"
      Case hbSslVerifyNoTrustedRoot
        msg="No trusted root"
      Case hbSslVerifyNotAfter, hbSslVerifyNotBefore
        msg="Certificate has expired"
      Case hbSslVerifyConstraintViolation
        msg="Constraint violation"
      Case hbSslVerifyUnknownExtension
        msg="Unknown critical extension"
    End Select
    ret=MsgBox("The following SSL error has occured:\n" & msg & "\nContinue ?",hbMsgBoxYesNo+hbMsgBoxError)
    If ret=hbMsgBoxYes Then bIgnore=True
  End If
End Sub

For example, you can copy this code in a new class named clsSSL, and set its Extends property to SslContext. You can then use this class in a call to the Connect method as follow:

Private Sub Button1_Click()
  Dim sock As New StreamSocket, ssl As New clsSSL

  sock.Connect "myserver.com", 443, ssl

  ' insert code that perform read/write
  ' operations here

  sock.Disconnect
End Sub

After the connection is successfully established, any subsequent read/write operation on this socket will be secured. Note that SSL encryption algorithms operate on blocks of 80 bytes each. If you write only a few bytes of data on a secured socket, they will be encapsulated into a 80-bytes block, wasting bandwidth. Therefore, it is strongly advised to provide some kind of buffering if your application is to send many small blocks of data over the network. For example, you can first write all of your small blocks into a StreamMemory object, and then write this buffer to the socket in one go.

The MiniBrowser sample illustrates how you can use this class to implement an HTTPS client.

Members

System requirements