Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

16    SSL Library

Security and Cryptography

Exploring Palm OS

This chapter contains reference documentation for the APIs defined in SslLib.h. The contents of this chapter are organized into the following sections:

SSL Library Structures and Types
SSL Library Constants
SSL Library Functions
Application-Defined Functions

The header file SslLib.h declares the API that this chapter describes.

For information on making use of the APIs documented in this chapter, see Chapter 2, "SSL Concepts." Much of what you do when working with the SSL library involves working with attributes; reference documentation for the macros that you use to set and get attribute values can be found in Chapter 17, "SSL Library Macros."

SSL Library Structures and Types ^TOP^

SslAttribute Typedef ^TOP^

Purpose

Container for an SslLib or SslContext attribute value.

Declared In

SslLib.h

Prototype

typedef uint32_t SslAttribute

Comments

Attribute values are listed in "SSL Library Macro Constants." Descriptions of each attribute can be found under "Attributes."

SslCallback Struct ^TOP^

Purpose

Structure used when the SSL library transfers control back to the application via a callback function.

Declared In

SslLib.h

Prototype

struct SslCallback_st {
   void *reserved;
   SslCallbackFunc callback;
   void *data;
   SslContext *ssl;
} 
typedef struct SslCallback_st SslCallback

Fields

reserved
Reserved for internal use by SslLib.
callback
A function pointer of the function to be called. See SslCallbackFunc().
data
Can be set to a value by the application, and will remain unchanged by SslLib. This value will then be available to the callback function. Use this field to communicate context information from the application to the callback. An example of its use is in a 'diagnostic' callback, in which the application could use this field to provide a handle to the logging routines to be used.
ssl
SslLib sets this field to be the SslContext if the callback is related to an SslContext. If it is not (due to being related to a SslLib), it is set to NULL.

Comments

This structure is used when the SSL library transfers control back to the application via a callback. A callback is a function that the application supplies to SslLib that will be called when specific situations occur during the SSL protocol. The callbacks are specific to the particular SslContext or SslLib they are registered with. Examples of callbacks used by the SslLib are an 'information' callback and a 'certificate validation' callback.

SslCipherSuiteInfo Struct ^TOP^

Purpose

Encapsulates information about the current cipher suite.

Declared In

SslLib.h

Prototype

typedef struct SslCipherSuiteInfo_st {
   uint8_t cipherSuite[2];
   uint16_t cipher;
   uint16_t digest;
   uint16_t keyExchange;
   uint16_t authentication;
   uint16_t version;
   uint16_t cipherBitLength;
   uint16_t cipherKeyLength;
   uint16_t keyExchangeLength;
   uint16_t authenticationLength;
   uint16_t exportCipher;
} SslCipherSuiteInfo

Fields

cipherSuite
The two bye cipher suite value for the current cipher suite. See the CipherSuite attribute for more details.
cipher
A number indicating which cipher is being used for this connection. One of the sslCsiCipher... constants listed under "Cipher Suite Info Constants."
digest
The digest value. One of the sslCsiDigest... constants listed under "Cipher Suite Info Constants."
keyExchange
The key exchange type which was used. One of the sslCsiKeyExch... constants listed under "Cipher Suite Info Constants."
authentication
The authentication type used. One of the sslCsiAuth... constants listed under "Cipher Suite Info Constants."
version
The SSL version being used.
cipherBitLength
The number of bits of key material used for encryption key generation. For export ciphers this will be either 40 or 56 bits.
cipherKeyLength
The length of the key for the underlying cipher. For an export RC4 cipher, the cipherBitLength would be 40, but the cipherKeyLength would be 128. This is because while the SSL protocol would be using 128-bit keys to encrypt and decrypt with RC4, only 40 bits of random data would be used to generate the 128-bit key.
keyExchangeLength
The length in bits of the public key used to establish a shared secret.
authenticationLength
The length of the public key used to ensure the key exchange was not tampered with. For export ciphers, the keyExchangeLength is often shorter than the authenticationLength.
exportCipher
Set when an export cipher is being used.

Comments

This structure differs from most others in that the application passes in a structure to be populated from the SslContext. Normally the SslContext returns a pointer to an internal data structure.

SslContext Struct ^TOP^

Purpose

An opaque data structure that represents an SSL connection.

Declared In

SslLib.h

Prototype

typedef struct SslContext_st SslContext

Fields

None.

SslIoBuf Struct ^TOP^

Purpose

Passed to the 'info' functions when I/O is being done.

Declared In

SslLib.h

Prototype

typedef struct SslIoBuf_st {
   SslContext *ssl;
   uint8_t *ptr;
   uint32_t outNum;
   uint32_t inNum;
   uint32_t max;
   uint32_t err;
   uint32_t flags;
} SslIoBuf

Fields

ssl
The SslContext for which this callback is being called from. It should be the same value that is held in the SslCallback structure's ssl field.
ptr
The buffer being used to store the bytes.
outNum
The number of bytes read or written; it is 0 in the 'Before' states.
inNum
The number of bytes to be read or written.
max
The maximum read that could be performed. inNum is the number of bytes that the SSL library needs right now, but max bytes could be read if they are available. Often the read operation will read more bytes than are needed, so the outNum field which returns the number of bytes read or written, can, for the read case, be larger than inNum.
err
In the 'After' argi states, err will contain the error code from the I/O operation. If there was no error, it will be 0 (errNone).
flags
The flags field is not currently used and is set to zero.

Comments

The 'Before' argi values indicate that the passed SslIoBuf indicates the I/O operation about to be performed. The 'After' argi values indicate that the SslIoBuf contains the results of the just-performed I/O operation.

SslLib Struct ^TOP^

Purpose

An opaque data structure that represents the SSL library.

Declared In

SslLib.h

Prototype

typedef struct SslLib_st SslLib

Fields

None.

SslSession Struct ^TOP^

Purpose

Holds all the security information associated with a particular SSL connection.

Declared In

SslLib.h

Prototype

typedef struct SslSession_st {
   uint32_t length;
   uint16_t version;
   unsigned char cipherSuite[2];
   unsigned char compression;
   unsigned char sessionId[33];
   unsigned char masterSecret[48];
   unsigned char time[8];
   unsigned char timeout[4];
   uint16_t certificateOffset;
   uint16_t extraData;
} SslSession

Fields

length
version
cipherSuite
The cipher suite. One of the values listed under "Cipher Suites."
compression
sessionId
The session ID. The first byte is the length.
masterSecret
Master secret.
time
Host-specific start time.
timeout
Timeout, in seconds.
certificateOffset
Optional Peer certificate; this is the offset from the front of the structure to a SslExtendedItems structure. If the offset if 0, it does not exist
extraData
Can be used to store anything, such as the host name of the peer. Application defined.

SslSocket Struct ^TOP^

Purpose

The structure used to hold the arguments to be passed to any sys/socket calls.

Declared In

SslLib.h

Prototype

typedef struct SslSocket_st {
   int32_t socket;
   uint16_t flags;
   uint16_t addrLen;
   status_t err;
   int32_t timeout;
   unsigned char addr[8];
} SslSocket

Comments

When setting this structure, the socket field will not be copied in. To set the socket to use for network connections, see the Socket attribute. The socket, flags, addrLen, err, and addr fields all correspond to the arguments passed to sendto() and recvfrom(). Read further on those functions for more details. The SslSocket passed into the SslContext will be copied into the SslContext's SslSocket structure and the SslSocket pointer returned refers to an internal SslContext data structure. When the application calls a function such as SslReceive(), the arguments passed to that function will overwrite the internal SslSocket values, so a subsequent call to SslContextGet_IoStruct() will return the newly updated fields.

SSL Library Constants ^TOP^

SSL Open Mode Flags ^TOP^

Purpose

Flags used to specify how the connection should be started when calling SslOpen().

Declared In

SslLib.h

Constants

#define sslOpenBufferedReuse 0x0040
This is the same as SslContextSet_BufferedReuse(ssl,1);
#define sslOpenDelayHandshake 0x0080
Do not perform the handshake now
#define sslOpenModeClear 0x0001
Turn off the SSL protocol.
#define sslOpenModeSsl 0x0002
Turn on the SSL protocol.
#define sslOpenNewConnection 0x0004
Perform a new SSL handshake, clearing any previous SslSession value. This is the same as SslContextSet_SslSession(ssl,NULL).
#define sslOpenNoAutoFlush 0x0008
This is the same as SslContextSet_AutoFlush(ssl,0);
#define sslOpenUseDefaultTimeout 0x0020
Use the SslContext timeout value instead of timeout parameter.

SSL Close Mode Flags ^TOP^

Purpose

Flags that allow you to specify how to perform the SSL Protocol shutdown when calling SslClose().

Declared In

SslLib.h

Constants

#define sslCloseDontSendShutdown 0x0001
Do not send the SSL shutdown message to the server.
SslContextSet_DontSendShutdown(ssl,1);
#define sslCloseDontWaitForShutdown 0x0002
Don't wait for the server to send a shutdown message.
SslContextSet_DontWaitForShutdown(ssl,1);
#define sslCloseUseDefaultTimeout 0x0020
Use the timeout value set against the SslContext, not the timeout parameter.

Mode Attribute Values ^TOP^

Purpose

Values that control the SslContext's operating mode.

Declared In

SslLib.h

Constants

#define sslModeClear 0x0000
Causes the SSL protocol to be bypassed.
#define sslModeFlush 0x8000
Causes any data in the internal data buffers to be cleared.
#define sslModeSsl 0x0002
A subset value of sslModeSslClient
#define sslModeSslClient 0x000A

Comments

SslModeSsl is a subset value of sslModeSslClient. In a future release of SslLib, the server side of the SSL protocol may be supported in which case sslModeSslServer would be added. The application can use code like the following to determine if the SSL protocol is being used:


If (SslContextGet_Mode(ssl) & sslModeSsl) 
   /* SSL protocol enabled */ 
else 
   /* Using cleartext */ 

A comparison with sslModeSslClient could be used to determine if the client or server side of the protocol is being used for that particular SslContext.

The sslModeFlush flag is special. When used in SslContextSet_Mode(), it causes any data in the internal data buffers to be cleared. This is normally required when reusing a SslContext for a new connection. If an application is using a SslContext for cleartext, and then wants to enable SSL on the same connection, this flag should not be used.

Protocol Versions ^TOP^

Purpose

The version of the SSL protocol to use.

Declared In

SslLib.h

Constants

#define sslVersionSSLv3 0x0300
Version SSLv3 of the SSL protocol.
#define sslVersionTLSv1 0x0301
Version TLSvs, or SSLv3.1 of the SSL protocol.

Comments

SslLib sends a TLSv1 ClientHello message by default. Note that in Palm OS Cobalt version 6.0 an attempt to change this protocol version to SSLv3 via SslContextSet_ProtocolVersion() has no effect—SslLib continues to send a TLSv1 ClientHello message.

Protocol Variants ^TOP^

Purpose

The protocol variants supported by the library.

Declared In

SslLib.h

Constants

#define sslSupport_anonDHKeyExchange 0x0008
#define sslSupport_Both (sslSupport_SSLv3Protocol | sslSupport_TLSv1Protocol)
Enables both the SSLv3 and TLSv1 protocols.
#define sslSupport_DHKeyExchange 0x0002
#define sslSupport_DSASign 0x0010
#define sslSupport_Ex1024 0x0040
#define sslSupport_Ex512 0x0020
#define sslSupport_RSAKeyExchange 0x0001
#define sslSupport_RSASign 0x0004
#define sslSupport_SSLv2Header 0x0400
#define sslSupport_SSLv3 (_sslSupport_SslLib | sslSupport_SSLv3Protocol)
Enables the SSLv3 protocol.
#define sslSupport_SSLv3Protocol 0x0100
#define sslSupport_TLSv1 (_sslSupport_SslLib | sslSupport_TLSv1Protocol)
Enables the TLSv1 protocol.
#define sslSupport_TLSv1Protocol 0x0200

Comments

The protocol variants differ from the protocol version. The ProtocolHello/ProtocolVersion is what you use to talk to the peer, while the protocol variants determine what sections of the library code are turned on or off. These values are used with the ProtocolSupport attribute; set this attribute with SslContextSet_ProtocolSupport() and get it with SslContextGet_ProtocolSupport().


WARNING! Do not disable things that you don't know anything about. Also, do not turn off the Ex512/Ex1024 bits without also removing the relevant ciphers from the cipher suite list.

Use sslSupport_SSLv3, sslSupport_TLSv1, or sslSupport_Both to enable SSLv3, TLSv1, or both protocols. The default is sslSupport_Both.

Compatibility Flags ^TOP^

Purpose

Compat attribute flags that turn on compatibility with incorrect SSL protocol implementations.

Declared In

SslLib.h

Constants

#define sslCompat1RecordPerMessage 0x0004
Some servers do not like to receive SSL protocol messages separated into multiple SSL records. This option stops the write buffers being set to a size less than 1024 bytes which ensures this problem will not occur.
#define sslCompatAll 0xffff
This value enables all the bug compatibility flags.
#define sslCompatBigRecords 0x0008
Some old Microsoft servers would send data to the SSL Client in records larger than 16k bytes in size. This is not legal in the SSLv3 protocol. This flag makes SslLib tolerate these large records.
#define sslCompatNetscapeCaDnBug 0x0002
Enables support for some old versions of Netscape servers which encoded certificate requests Distinguished names wrongly. This is not currently a problem for SslLib since it does not support Client certificates.
#define sslCompatReuseCipherBug 0x0001
Enables support for servers that change cipher suites on session-reuse. They should not be doing this.

Comments

These bugs will not normally be encountered while using the SSL protocol, but if desired, it is worth enabling the compatibility in case old buggy servers are being accessed.

SSL Callback Commands ^TOP^

Purpose

General commands that all callbacks should expect to receive. There are normally related to creation and destruction of the structure that holds the callback. These commands are used in conjunction with SslCallbackFunc().

Declared In

SslLib.h

Constants

#define sslCmdFree 0x0002
Called when the callback is 'destroyed', normally due to its parent SslLib or SslContext being destroyed.
#define sslCmdGet 0x0004
Called to return a value from the callback to SslLib. The argi value for this callback is callback-specific.
#define sslCmdInfo 0x0012
An Info callback. See "The Info Callback" for more information.
#define sslCmdNew 0x0001
Called when the callback is 'copied' into an SslLib or SslContext.
#define sslCmdRead 0x0010
#define sslCmdReset 0x0003
Called when the SslContext has been reset, which occurs when a new connection is being started. It is called instead of sslCmdNew. sslCmdNew will be called only once; sslCmdReset will be called subsequently to 'reset' the state associated with the callback.
#define sslCmdSet 0x0005
Called to pass a value from SslLib to the callback. The argi value would specify the argv parameter. The argi parameter would be callback-specific.
#define sslCmdVerify 0x0013
A Verify callback. See "The Verify Callback" for more information.
#define sslCmdWrite 0x0011

Cipher Suite Info Constants ^TOP^

Purpose

Constants used with various fields of the SslCipherSuiteInfo structure.

Declared In

SslLib.h

Constants

#define sslCsiAuthNULL 0x00
#define sslCsiAuthRsa 0x01
#define sslCsiCipherNull 0x00
#define sslCsiCipherRc4 0x01
#define sslCsiDigestMd2 0x03
#define sslCsiDigestMd5 0x01
#define sslCsiDigestNull 0x00
#define sslCsiDigestSha1 0x02
#define sslCsiKeyExchNull 0x00
#define sslCsiKeyExchRsa 0x01

Cipher Suites ^TOP^

Purpose

SSL cipher suites that the SSL protocol can attempt to use.

Declared In

SslLib.h

Constants

#define sslCs_RSA_3DES_168_SHA1 0x00, 0x0A
#define sslCs_RSA_DES_40_SHA1 0x00, 0x08
#define sslCs_RSA_DES_56_SHA1 0x00, 0x09
#define sslCs_RSA_RC4_128_MD5 0x00,0x04
#define sslCs_RSA_RC4_128_SHA1 0x00,0x05
#define sslCs_RSA_RC4_40_MD5 0x00,0x03
#define sslCs_RSA_RC4_56_SHA1 0x00,0x64

Comments

Set the cipher suites using either SslLibSet_CipherSuites() or SslContextSet_CipherSuites().

Ciphers ^TOP^

Purpose

Declared In

SslLib.h

Constants

#define sslCs_ExportCiphers "\x00\x06\x00\x64\x00\x03\x00\x08"
#define sslCs_StrongCiphers "\x00\x06\x00\x0A\x00\x05\x00\x04"
#define sslCs_WeakExportCiphers "\x00\x04\x00\x03\x00\x08"

Info Callbacks ^TOP^

Purpose

The SslCallbackFunc() callback is called when various situations occur during the usage of a SslContext. It is primarily intended for debugging and feedback purposes. If the callback returns a non-zero value, this error will be returned back out the SslLib API. The callback will be called with a command argument of sslCmdInfo. The constants listed in this section represent the possible argi values.

Declared In

SslLib.h

Constants

#define sslArgInfoAlert 0x0002
Notification of an Alert in the SSL protocol. The sslArgInfoAlert notification is called with a NULL value for the argv parameter. The application can get the LastAlert attribute from the SslContext to determine which alert was received.
#define sslArgInfoCert 0x0003
Notification of peer certificate. The sslArgInfoCert call is made after the server's certificate chain has been verified. The argv parameter is a SslExtendedItems pointer, which points to the remote server's certificate.
#define sslArgInfoHandshake 0x0001
Notification of a state change in the SSL protocol. The sslArgInfoHandshake will be called upon each handshake state change. The argv parameter will be NULL, but the HsState attribute can be interrogated to read the current state.
#define sslArgInfoReadAfter (sslCmdRead | 0x8000)
Notification after a recvfrom(), recv(), or read() sys/socket call. See the Comments section, below, for more information.
#define sslArgInfoReadBefore sslCmdRead
Notification before a recvfrom(), recv(), or read() sys/socket call. See the Comments section, below, for more information.
#define sslArgInfoWriteAfter (sslCmdWrite | 0x8000)
Notification after a sendto(), send(), or write() sys/socket call. See the Comments section, below, for more information.
#define sslArgInfoWriteBefore sslCmdWrite
Notification before a sendto(), send(), or write() sys/socket call. See the Comments section, below, for more information.

Comments

The sslArgInfo[Read | Write] [Before | After] callback is called twice for each network I/O operation. The first call is made before the call to the underlying sys/socket send or receive function. The second is made after the call has completed. If the callback returns a non-zero value, this value will be returned by original SslLib call the application made.

The argv parameter is a SslIoBuf structure. This structure's ssl field is the SslContext that the I/O operation is being performed by. ptr points to the space used, or to be used, in the operation. outNum is the number of bytes processed. It is only set in the After calls. inNum is the number of bytes to be read or written in the call. max is the maximum number of bytes that could be read. It can be larger than inNum. err is the error value, if any. This value is only set in the After calls. flags is currently not used and is set to 0.

InfoInterest Values ^TOP^

Purpose

Values used to specify the events for which of the Info Callbacks will be called. The InfoInterest value is the logical OR of these values.

Declared In

SslLib.h

Constants

#define sslFlgInfoAlert 0x0001
The sslArgInfoAlert callback.
#define sslFlgInfoCert 0x0008
The sslArgInfoCert callback.
#define sslFlgInfoHandshake 0x0002
The sslArgInfoHandshake callback.
#define sslFlgInfoIo 0x0004
The sslArgInfoReadAfter, sslArgInfoReadBefore, sslArgInfoWriteAfter, and sslArgInfoWriteBefore callbacks.

LastApi Attribute Values ^TOP^

Purpose

The last SslLib API call made. This attribute can be useful in event-driven programs.

Declared In

SslLib.h
#define sslLastApiFlush 0x04
#define sslLastApiNone 0x00
#define sslLastApiOpen 0x01
#define sslLastApiRead 0x02
Set if SslRead(), SslPeek() or SslReceive() was last called.
#define sslLastApiShutdown 0x05
#define sslLastApiWrite 0x03
Set if SslWrite() or SslSend() was last called.

LastIO Attribute Values ^TOP^

Purpose

The last network operation performed.

Declared In

SslLib.h
#define sslLastIoNone 0x00
No I/O operations have been performed since the context was last reset.
#define sslLastIoRead 0x01
A read operation.
#define sslLastIoWrite 0x02
A write operation.

Comments

Since most of the SslLib API I/O functions can cause an SSL handshake to be performed, it is often not possible to know if the reason that a SslSend() returned netErrWouldBlock is because the Send operation failed or a Receive operation failed (because a SSL Handshake was being performed). This attribute allows the application to determine which I/O operation was being called if a network error is returned. If the application is using select(), this attribute is very important. Because this attribute returns the last network operation performed, sslLastIoNone will only be returned if the SslContext has not performed any I/O operations since its last reset.

SSL Protocol States ^TOP^

Purpose

These constants indicate the state that the SSL protocol is currently in. See the SSL protocol specification for clarification on what the values mean.

Declared In

SslLib.h

Constants

#define sslHsStateCert 7
#define sslHsStateCertB 8
#define sslHsStateCertReq 13
#define sslHsStateCertReqB 14
#define sslHsStateCkEx 17
#define sslHsStateCleanup 25
#define sslHsStateClientCert 16
#define sslHsStateClientHello 2
#define sslHsStateClosed 28
#define sslHsStateDone 26
#define sslHsStateFinished 19
#define sslHsStateFlush 4
#define sslHsStateGenerateKeys 21
#define sslHsStateHelloRequest 29
#define sslHsStateNone 0
#define sslHsStateReadCcs 20
#define sslHsStateReadFinished 22
#define sslHsStateReadFinishedB 23
#define sslHsStateReadFinishedC 24
#define sslHsStateServerDone 15
#define sslHsStateServerHello 3
#define sslHsStateShutdown 27
#define sslHsStateSkEx 9
#define sslHsStateSkExAnonDh 12
#define sslHsStateSkExDh 11
#define sslHsStateSkExRsa 10
#define sslHsStateStart 1
#define sslHsStateWrite 6
#define sslHsStateWriteCcs 18
#define sslHsStateWriteClose 30
#define sslHsStateWriteFlush 5

SSL Server Alerts ^TOP^

Purpose

Alert values received from the server. These are the defined Sslv3/TLSv1 alerts as defined in the SSLv3 and TLSv1 specifications. For their meanings, refer to those specifications.

Declared In

SslLib.h

Constants

#define sslAlertAccessDenied (0x0200+49)
#define sslAlertBadCertificate (0x0100+42)
#define sslAlertBadRecordMac (0x0200+20)
#define sslAlertCertificateExpired (0x0100+45)
#define sslAlertCertificateRevoked (0x0100+44)
#define sslAlertCertificateUnknown (0x0100+46)
#define sslAlertCloseNotify (0x0100+ 0)
#define sslAlertDecodeError (0x0200+50)
#define sslAlertDecompressionFailure (0x0200+30)
#define sslAlertDecryptError (0x0200+51)
#define sslAlertDecryptionFailed (0x0200+21)
#define sslAlertExportRestricion (0x0200+60)
#define sslAlertHandshakeFailure (0x0200+40)
#define sslAlertIllegalParameter (0x0200+47)
#define sslAlertInsufficientSecurity (0x0200+71)
#define sslAlertInternalError (0x0200+80)
#define sslAlertNoCertificate (0x0100+41)
#define sslAlertNoRenegotiation (0x0100+100)
#define sslAlertProtocolVersion (0x0200+70)
#define sslAlertRecordOverflow (0x0200+22)
#define sslAlertUnexpectedMessage (0x0200+10)
#define sslAlertUnknownCa (0x0200+48)
#define sslAlertUnsupportedCertificate (0x0100+43)
#define sslAlertUserCancled (0x0100+90)

Comments

The alert values are received from the server and are of two types, fatal and non-fatal.

The non-fatal alerts have a value of the form 0x01XX, while fatal Alerts have the form 0x02XX. SslLib will fail on fatal alerts and continue on non-fatal alerts.

SSL Library Errors ^TOP^

Purpose

Error codes returned by the various SSL library functions.

Declared In

SslLib.h

Constants

#define sslErrBadArgument (sslErrorClass+17)
An invalid argument was provided to the function.
#define sslErrBadDecode (sslErrorClass+9)
An error occurred while decoding values during certificate verification.
#define sslErrBadLength (sslErrorClass+13)
A length argument was invalid.
#define sslErrBadOption (sslErrorClass+18)
An invalid argument was provided to the function.
#define sslErrBadPeerFinished (sslErrorClass+46)
The final check of the SSL handshake failed. This indicates that there was a problem establishing a shared secret value. It could be caused by the server using a certificate that does not match its private key.
#define sslErrBadSignature (sslErrorClass+47)
An invalid signature was found on a ephemeral Cipher Suite message.
#define sslErrBufferTooSmall (sslErrorClass+11)
A supplied buffer was not large enough for the output data.
#define sslErrCbAbort (sslErrorClass+4)
This error code would be returned by an applications callback function to indicate a desire to exit. This error may not be fatal, depending on the callback that generated the error.
#define sslErrCert (sslErrorClass+39)
A generic error occurred inside the SslLib certificate library.
#define sslErrCertDecodeError (sslErrorClass+51)
The Servers certificate could not be decoded.
#define sslErrCsp (sslErrorClass+38)
A generic error occurred inside the SslLib cryptographic library.
#define sslErrDivByZero (sslErrorClass+7)
Something went wrong in the Math library. These error will normally only be generated by certificates which have invalid public keys.
#define sslErrEof (sslErrorClass+2)
Error returned by SslLib functions when either the SSL protocol has been closed or the underlying socket has been closed. This error indicates that the current SslContext is unable to read or write any more data bytes.
#define sslErrExtraHandshakeData (sslErrorClass+43)
Extra data was found in the SSL handshake messages that should not have been there.
#define sslErrFailed (sslErrorClass+1)
A generic error.
#define sslErrFatalAlert (sslErrorClass+45)
A fatal alert was received by the SSL protocol.
#define sslErrHandshakeEncoding (sslErrorClass+40)
An error occurred during decoding of SSL handshake messages.
#define sslErrHandshakeProtocol (sslErrorClass+42)
An error occurred while processing the decoded SSL handshake messages.
#define sslErrInitNotCalled (sslErrorClass+10)
An internal SslLib error.
#define sslErrInternalError (sslErrorClass+21)
An internal SslLib error.
#define sslErrIo (sslErrorClass+5)
This error code is returned when an underlying sys/socket function call returned an error that is not fatal. A timeout, or other such non-fatal network errors will be reclassified as this error type. A function that returns this error type can be re-called once the error condition has disappeared.
#define sslErrMissingCipherSuite (sslErrorClass+80)
#define sslErrMissingProvider (sslErrorClass+41)
An internal SslLib error.
#define sslErrNoDmem (sslErrorClass+14)
An internal SslLib error.
#define sslErrNoMethodSet (sslErrorClass+15)
An internal SslLib error.
#define sslErrNoModInverse (sslErrorClass+8)
Something went wrong in the Math library. These error will normally only be generated by certificates which have invalid public keys.
#define sslErrNoRandom (sslErrorClass+16)
A problem with the random number source.
#define sslErrNotFound (sslErrorClass+6)
Returned on an internal SslLib search that did not find a valid entry. Consider this an internal SslLib error.
#define sslErrNotImplemented (sslErrorClass+19)
An internal SslLib error.
#define sslErrNullArg (sslErrorClass+12)
An passed argument was NULL that should not have been NULL.
#define sslErrOk (sslErrorClass+0)
Not an error.
#define sslErrOutOfMemory (sslErrorClass+3)
Returned if a dynamic memory allocation failed. This is normally considered a very bad error.
#define sslErrReadAppData (sslErrorClass+50)
Application data was read by the SSL protocol when it was expecting handshake messages.
#define sslErrReallocStaticData (sslErrorClass+20)
An internal SslLib error
#define sslErrRecordError (sslErrorClass+37)
An invalid record was received in the SslContext.
#define sslErrUnexpectedRecord (sslErrorClass+49)
A record of the wrong was received inside the SSL protocol.
#define sslErrUnsupportedCertType (sslErrorClass+52)
The Servers certificate contains a public key we cannot decode.
#define sslErrUnsupportedProtocol (sslErrorClass+54)
#define sslErrUnsupportedSignatureType (sslErrorClass+53)
We have been send a certificate with a signature type we do not recognize.
#define sslErrVerifyCallback (sslErrorClass+128)
#define sslErrWrongMessage (sslErrorClass+44)
An invalid SSL message was received.

Miscellaneous SSL Library Constants ^TOP^

Purpose

These constants are also defined in SslLib.h.

Declared In

SslLib.h

Constants

#define kSslDBName "SslLib"
The SSL library's database name.
#define kSslLibCreator 'ssl0'
The SSL library's creator ID.
#define kSslLibType sysFileTLibrary
The SSL library's type.

SSL Library Functions ^TOP^

SslClose Function ^TOP^

Purpose

Performs the shutdown part of the SSL protocol.

Declared In

SslLib.h

Prototype

status_t SslClose (
   SslContext *ctx,
   uint16_t mode,
   uint32_t timeout
)

Parameters

ctx
The context to query.
mode
Flags that specify how to perform the SSL Protocol shutdown. A combination of the values listed under "SSL Close Mode Flags."
timeout
Timeout, in system ticks, to use for final message exchange

Returns

Returns errNone if the operation completed successfully. Otherwise, this function returns one of the error codes listed under "SSL Library Errors."

Comments

This usually involves message exchanges. This function can be repeatedly called after a timeout until either a network error is reported or the final SSL shutdown message exchange has been completed. The mode values can be logically OR'ed together.

Example

The following code excerpt show how you might use this function:


Err err; 
SslContext *ssl; 
 
err = SslOpen(ssl,0,20*SysTicksPerSecond()); 
/* Perform SSL IO */ 
/* Shutdown the protocol but don't linger waiting for a 
 * response from the server */ 
err = SslClose(ssl,sslCloseDontWaitForshutdown,
   20*SysTicksPerSecond()); 

See Also

SslOpen(), SslContextSetLong(), SslContextSetPtr()

SslConsume Function ^TOP^

Purpose

Removes up to a specified number of bytes from the buffered read bytes in the passed SslContext.

Declared In

SslLib.h

Prototype

void SslConsume (
   SslContext *ctx,
   int32_t number
)

Parameters

ctx
The SslContext to operate on.
number
The number of bytes to remove from the internal buffer.

Returns

Nothing.

Comments

This function is normally used in conjunction with SslPeek().

Example

The following code excerpt shows how this function might be used.


Err err; 
void *data; 
Int32 *dataLen; 
 
err=SslPeek(ssl,&data,*dataLen,16*1024); 
/* Process the dataLen bytes located at data */ 
SslConsume(ssl,dataLen); 

See Also

SslPeek(), SslRead(), SslReceive()

SslContextCreate Function ^TOP^

Purpose

Creates a new SSL Context.

Declared In

SslLib.h

Prototype

status_t SslContextCreate (
   SslLib *lib,
   SslContext **ctx
)

Parameters

lib
The SSL library structure.
ctx
Where to deposit the SslContext pointer.

Returns

Returns errNone if the operation completed successfully. Otherwise, this function returns one of the error codes listed under "SSL Library Errors."

Comments

A SslContext is the data structure used to encapsulates all aspects of a SSL connection. This routine will deposit a pointer to the newly created structure at the address given by the ctx argument. Various default values will be inherited from the passed SslLib.

See Also

SslOpen(), SslContextDestroy(), SslContextSetLong(), SslContextSetPtr()

SslContextDestroy Function ^TOP^

Purpose

Destroys the SSL Context.

Declared In

SslLib.h

Prototype

void SslContextDestroy (
   SslContext *ctx
)

Parameters

ctx
The SslContext to destroy.

Returns

Nothing.

Comments

This routine will free the memory associated with the passed SslContext. This function will not close the network connection or shutdown the SSL protocol. See SslClose() for information on shutting down the SSL Protocol.

See Also

SslContextCreate(), SslClose()

SslContextGetLong Function ^TOP^

Purpose

Retrieve an integer attribute value from the passed SslContext structure.

Declared In

SslLib.h

Prototype

int32_t SslContextGetLong (
   SslContext *lib,
   SslAttribute attr
)

Parameters

lib
The SslContext from which the value is to be retrieved.
attr
Attribute to retrieve.

Returns

The value of the attribute is returned. If a non-existent attribute was requested, -1 is returned. This could give incorrect values so an application should make sure to call this routine with the correct arguments.

Comments

This function is not normally used directly, but via pre-defined macros.

Example

The following example shows the use of one of the macros that make use of this function:


/* Is the SslContext configured to do ssl? */ 
if (!(SslContextGet_Mode(lib) & sslModeSsl)) 
   return(WE_ARE_NOT_USING_SSL); 

See Also

SslContextSetLong(), SslContextGetLong()

SslContextGetPtr Function ^TOP^

Purpose

Retrieve a pointer to an attribute value from the passed SslContext structure.

Declared In

SslLib.h

Prototype

status_t SslContextGetPtr (
   SslContext *lib,
   SslAttribute attr,
   void **value
)

Parameters

lib
The SslContext to retrieve the attribute from.
attr
The attribute to retrieve
value
A pointer to an attribute specific pointer

Returns

Returns errNone if the operation completed successfully. Otherwise, this function returns one of the error codes listed under "SSL Library Errors."

Comments

This function is not normally used directly, but via pre-defined macros. The type of the pointer returned is specific to the attribute being requested.

Example

The following example shows the use of one of the macros that makes use of this function:


SslSession *session; 
Err err; 
 
err = SslContextGet_SslSession(ssl,&session); 

See Also

SslContextSetPtr(), SslLibGetPtr()

SslContextSetLong Function ^TOP^

Purpose

Modify one of the numeric attributes of a SslContext structure.

Declared In

SslLib.h

Prototype

status_t SslContextSetLong (
   SslContext *lib,
   SslAttribute attr,
   long value
)

Parameters

lib
The SslContext on which to operate.
attr
The attribute to modify.
value
The new value.

Returns

Returns errNone if the operation completed successfully. Otherwise, this function returns one of the error codes listed under "SSL Library Errors."

Comments

This function is not normally used directly, rather it is used via pre-defined macros. The attr parameter specifies the SslContext attribute that will be set to the value passed in value.

Example

The following code excerpt shows how this function is used.


SslContext *ssl; 
Err err; 
 
err = SslContextCreate(lib,&ssl); 
/*modify output buffer size */ 
err = SslContextSet_WbufSize(lib,8*1024); 

See Also

SslContextSetPtr(), SslContextGetPtr(), SslContextGetLong()

SslContextSetPtr Function ^TOP^

Purpose

Update one of the non-integer attributes of a SslContext.

Declared In

SslLib.h

Prototype

status_t SslContextSetPtr (
   SslContext *lib,
   SslAttribute attr,
   void *value
)

Parameters

lib
The SslContext to modify.
attr
The attribute to update.
value
The value to update, specific to the SslAttribute.

Returns

Returns errNone if the operation completed successfully. Otherwise, this function returns one of the error codes listed under "SSL Library Errors."

Comments

The attr value defines the type of the value parameter. This function is not normally used directly, rather it is used via pre-defined macros.

Example

The following code excerpt shows how this function is used.


SslContext *ssl; 
SslCallback cb; 
Err err; 
 
err = SslContextCreate(lib,&ssl); 
 
/* Configure to have 'debugCallbackFunction' called for each 
 * SSL protocol handshake state change */ 
cb.callback = debugCallbackFunction; 
cb.data = NULL; 
err = SslContextSet_InfoInterest(lib, sslInfoHandshake); 
err = SslContextSet_InfoCallback(lib,(void *)&cb); 

See Also

SslContextGetLong(), SslContextSetLong(), SslContextGetPtr()

SslFlush Function ^TOP^

Purpose

Cause an immediate write of any data buffered in the SslContext to the network.

Declared In

SslLib.h

Prototype

status_t SslFlush (
   SslContext *ctx,
   int32_t *outstanding
)

Parameters

ctx
The SslContext to operate on.
outstanding
The number of byte still unflushed after this call.

Returns

Returns errNone if the operation completed successfully. Otherwise, this function returns one of the error codes listed under "SSL Library Errors."

Comments

An SslContext can be set into "no AutoFlush" mode. This means that the SslSend() and SslWrite() operations will not cause an immediate write to the network. If this mode is enabled, then explicit SslFlush calls need to be made to ensure that the data buffered in the SslContext is sent to the network. The main use of "no AutoFlush" is to allow multiple SslWrite()/SslSend() commands to have their output buffered in the SslContext's output buffer. This improves the SSL Protocols efficiency and is generally a good policy if lots of small write operations are being performed by the application. The number of bytes that can be written to the SslContext write buffer is a few tens of bytes less than the output buffer size. This means that if the application is writing less than this number of bytes, no network errors can occur until the SslFlush() call is made. The outstanding parameter will be updated to contain the number of buffered bytes that are still buffered in the SslContext. If this value is non-zero, the next SslWrite(), SslSend(), SslFlush() operation will attempt to write those bytes to the network.

Example

The following code excerpt shows how this function can be used:


Err err; 
 
SslContextSet_AutoFlush(ssl,0); 
SslWrite(ssl,"GET ",4); 
SslWrite(ssl,url,StrLen(url)); 
SslWrite(ssl," HTTP/1.0\r\n\r\n",13); 
 
err=SslFlush(ssl,NULL); 

See Also

SslWrite(), SslSend(), SslContextSetLong()

SslLibClose Function ^TOP^

Purpose

SSL library's shared library close function.

Declared In

SslLib.h

Prototype

status_t SslLibClose (
   void
)

Parameters

None.

Returns

SslLibCreate Function ^TOP^

Purpose

Creates the SSL library context.

Declared In

SslLib.h

Prototype

status_t SslLibCreate (
   SslLib **lib
)

Parameters

lib
Where to deposit the SslLib pointer

Returns

Returns errNone if the operation completed successfully. Otherwise, this function returns one of the error codes listed under "SSL Library Errors."

Comments

This routine will deposit the newly-created SslLib at the address given by the lib argument. This routine is generally the first call made when performing SSL functionality. Various default configuration values can be set against this structure. These values will be inherited by SslContext structures created against the SslLib.

See Also

SslLibDestroy(), SslContextCreate(), SslLibSetLong(), SslLibSetPtr()

SslLibDestroy Function ^TOP^

Purpose

Destroys the context represented by lib.

Declared In

SslLib.h

Prototype

void SslLibDestroy (
   SslLib *lib
)

Parameters

lib
SslLib structure to be destroyed.

Returns

Nothing.

See Also

SslLibCreate()

SslLibGetLong Function ^TOP^

Purpose

Retrieve an integer attribute value from the passed SslLib structure.

Declared In

SslLib.h

Prototype

int32_t SslLibGetLong (
   SslLib *lib,
   SslAttribute attr
)

Parameters

lib
The SslLib from which the value is to be retrieved.
attr
Attribute to retrieve.

Returns

The value of the attribute is returned. If a non-existent attribute was requested, -1 is returned.

Comments

This function is not normally used directly, but via pre-defined macros.

See Also

SslContextGetPtr(), SslLibSetLong(), SslContextGetLong()

SslLibGetPtr Function ^TOP^

Purpose

Retrieve an pointer attribute value from the passed SslLib structure.

Declared In

SslLib.h

Prototype

status_t SslLibGetPtr (
   SslLib *lib,
   SslAttribute attr,
   void **value
)

Parameters

lib
The SslLib to retrieve the attribute from.
attr
The attribute to retrieve.
value
A pointer to a attribute specific pointer

Returns

Returns errNone if the operation completed successfully. Otherwise, this function returns one of the error codes listed under "SSL Library Errors."

Comments

This function is not normally used directly, but via pre-defined macros. The type of the pointer returned is specific to the attribute being requested.

Example

The following code excerpt shows how this function is used.


SslCallback *cb; 
Err err; 
 
err = SslLibGet_InfoCallback(lib,&cb); 

See Also

SslLibSetPtr(), SslContextGetPtr()

SslLibName Function ^TOP^

Purpose

Declared In

SslLib.h

Prototype

status_t SslLibName (
   void
)

Parameters

None.

Returns

SslLibOpen Function ^TOP^

Purpose

SSL library's shared library open function.

Declared In

SslLib.h

Prototype

status_t SslLibOpen (
   void
)

Parameters

None.

Returns

SslLibSetLong Function ^TOP^

Purpose

Modify one of the numeric attributes of a SslLib structure.

Declared In

SslLib.h

Prototype

status_t SslLibSetLong (
   SslLib *lib,
   SslAttribute attr,
   int32_t value
)

Parameters

lib
The SslLib on which to operate.
attr
The attribute to modify.
value
The new value.

Returns

Returns errNone if the operation completed successfully. Otherwise, this function returns one of the error codes listed under "SSL Library Errors."

Comments

This function is not normally used directly, rather it is used via pre-defined macros. The attr parameter specifies the SslLib attribute that will be set to the value passed in value.

Example

The following code excerpt shows how this function is used.


SslLib *lib; 
Err err; 
 
err = SslLibCreate(&lib); 
err = SslLibSet_AutoFlush(lib,0); /* Turn of auto flushing */ 

See Also

SslLibCreate(), SslLibSetPtr(), SslLibGetPtr(), SslLibGetLong()

SslLibSetPtr Function ^TOP^

Purpose

Update one of the non-integer attributes of a SslLib.

Declared In

SslLib.h

Prototype

status_t SslLibSetPtr (
   SslLib *lib,
   SslAttribute attr,
   void *value
)

Parameters

lib
The SslLib to operate on.
attr
The attribute to update.
value
The value to update, specific to the SslAttribute.

Returns

Returns errNone if the operation completed successfully. Otherwise, this function returns one of the error codes listed under "SSL Library Errors."

Comments

The attr value defines the type of the value parameter. This function is not normally used directly, rather it is used via pre-defined macros.

Example

The following code excerpt shows how this function is used.


SslLib *lib; 
SslCallback cb; 
Err err; 
 
err = SslLibCreate(&lib); 
 
/* Configure to have 'debugCallbackFunction' called for each 
 * SSL protocol handshake state change */ 
cb.callback = debugCallbackFunction; 
cb.data = NULL; 
err = SslLibSet_InfoInterest(lib, sslInfoHandshake); 
err = SslLibSet_InfoCallback(lib,(void *)&cb); 

See Also

SslLibGetLong(), SslLibSetLong(), SslLibGetPtr()

SslLibSleep Function ^TOP^

Purpose

SSL library's shared library sleep function.

Declared In

SslLib.h

Prototype

status_t SslLibSleep (
   void
)

Parameters

None.

Returns

SslLibWake Function ^TOP^

Purpose

SSL library's shared library wake function.

Declared In

SslLib.h

Prototype

status_t SslLibWake (
   void
)

Parameters

None.

Returns

SslOpen Function ^TOP^

Purpose

Initializes the passed SslContext.

Declared In

SslLib.h

Prototype

status_t SslOpen (
   SslContext *ctx,
   uint16_t mode,
   uint32_t timeout
)

Parameters

ctx
The SslContext to start a SSL Handshake with.
mode
How we should 'start' this connection. A combination of the values listed under "SSL Open Mode Flags."
timeout
Optional timeout (in system ticks).

Returns

Returns errNone if the operation completed successfully. Otherwise, this function returns one of the error codes listed under "SSL Library Errors."

Comments

Depending on the mode, SslOpen() may or may not actually send the handshake messages during this function call, but may delay the handshake until the first SslSend()/SslReceive(). It may not even use the SSL protocol. The mode values can be logically OR'ed together, and their values affect the functionality of the SslOpen() call. If non-fatal network errors occur (timeouts), the function can be re-called. When the function finally returns errNone, the SSL handshake will have completed and any SslContext will be able to return a valid SslSession structure. If one re-calls SslOpen(), make sure to not have either of sslOpenModeClear or SslOpenModeSsl set or the connection will be reset.

Quite a few of the mode parameters set flags against the SslContext.

Returns

SslClose(), SslContextSetLong(), SslContextSetPtr()

SslPeek Function ^TOP^

Purpose

Obtains a pointer into the buffered data that is located in the SslContext.

Declared In

SslLib.h

Prototype

status_t SslPeek (
   SslContext *ctx,
   void **buffer_ptr,
   int32_t *availableBytes,
   int32_t readSize
)

Parameters

ctx
The SslContext to operate on.
buffer_ptr
The location to place the data pointer.
availableBytes
The location to place the number of bytes available in *buffer_ptr.
readSize
The maximum number of bytes to return.

Returns

Returns errNone if the operation completed successfully. Otherwise, this function returns one of the error codes listed under "SSL Library Errors."

Comments

This function returns a pointer to available data bytes and assigns the number available to availableBytes. This function does not copy any data bytes from the SslContext, rather it returns a pointer into the buffered data that is located in the SslContext. If there were no data bytes in the SslContext, data will be read from the network until there are data bytes available. Repeated calls to SslPeek() will return the same buffer_ptr value until a SslConsume() call is done to indicate that bytes no longer need to be buffered. readSize is the maximum number of available bytes that will be reported as being available.

This is a more advanced function but is used internally, along with SslConsume(), to build the SslRead() and SslReceive() functions. Its main use is for 'streaming' input data where the application does not need to allocate it's own data storage buffers since it can read directly from the SslContext buffers. Once a quantity of data is reported as available in *availableBytes, the total will not increase until that number of bytes has been 'consumed'.

See Also

SslConsume(), SslRead()

SslRead Function ^TOP^

Purpose

Receives data.

Declared In

SslLib.h

Prototype

int32_t SslRead (
   SslContext *ctx,
   void *buffer,
   int32_t bufferLen,
   status_t *errRet
)

Parameters

ctx
The SslContext to read from.
buffer
Buffer into which read data will be placed.
bufferLen
Size of buffer (max bytes read).
errRet
This will contain an error code if return is -1.

Returns

Returns the number of bytes successfully received, or -1 if an error occurred.

Comments

Performs the same functionality as SslReceive(). This call will use the timeout set earlier against the SslContext.

See Also

SslWrite(), SslSend()

SslReceive Function ^TOP^

Purpose

Receives data.

Declared In

SslLib.h

Prototype

int16_t SslReceive (
   SslContext *ctx,
   void *buffer,
   uint16_t bufferLen,
   uint16_t flags,
   void *fromAddr,
   uint16_t *fromLen,
   int32_t timeout,
   status_t *errRet
)

Parameters

ctx
The SslContext to use.
buffer
Buffer into which received data will be placed.
bufferLen
Size of buffer (max bytes received).
flags
One or more MSG_xxx flags (defined in sys/socket.h).
fromAddr
Buffer to hold address of sender (sockaddr).
fromLen
On entry, size of fromAddr buffer. On exit, actual size of returned address in fromAddr buffer
timeout
Max timeout in system ticks. -1 means wait forever.
errRet
This will contain an error code if return is -1.

NOTE: In Palm OS Cobalt the flags and timeout parameter values are ignored.

Returns

Returns the number of bytes successfully received, or -1 if an error occurred.

Comments

The function returns either the number of bytes successfully received or -1. If -1, there was an error. In that case, an error code will be deposited at the address given by errRet.

See Also

SslSend(), read()

SslSend Function ^TOP^

Purpose

Sends data over the network.

Declared In

SslLib.h

Prototype

int16_t SslSend (
   SslContext *ctx,
   const void *buffer,
   uint16_t bufferLen,
   uint16_t flags,
   void *toAddr,
   uint16_t toLen,
   int32_t timeout,
   status_t *errRet
)

Parameters

ctx
The SslContext to use.
buffer
Buffer containing data to send.
bufferLen
Length, in bytes, of data to send.
flags
One or more MSG_xxx flags (defined in sys/socket.h).
toAddr
Address to send to. See the sendto() manpage.
toLen
Size of toAddr buffer
timeout
Max timeout in system ticks. -1 means wait forever.
errRet
This will contain an error code if return is -1.

NOTE: In Palm OS Cobalt the flags and timeout parameter values are ignored.

Returns

Returns the number of bytes successfully sent, or -1 if an error occurred.

Comments

This function mirrors the sendto() function and has similar arguments and semantics.

The function returns either the number of bytes successfully sent or -1. If -1, there was an error. In that case, an error code will be deposited at the address given by errRet. The other parameters are the same as for sendto() and are used when the data bytes are written to the network.

See Also

SslReceive(), sendto()

SslWrite Function ^TOP^

Purpose

Sends data over the network.

Declared In

SslLib.h

Prototype

int32_t SslWrite (
   SslContext *ctx,
   const void *buffer,
   int32_t bufferLen,
   status_t *errRet
)

Parameters

ctx
The SslContext to write to.
buffer
Buffer containing data to write.
bufferLen
Length, in bytes, of data to write.
errRet
This will contain an error code if return is -1.

Returns

Returns the number of bytes successfully sent, or -1 if an error occurred.

Comments

Performs the same functionality as SslSend(). This call will use the timeout set earlier against the SslContext.

See Also

SslRead(), SslSend()

Application-Defined Functions ^TOP^

SslCallbackFunc Function ^TOP^

Purpose

A function that the application supplies to SslLib that will be called when specific situations occur during the SSL protocol. The callbacks are specific to the particular SslContext or SslLib they are registered with.

Declared In

SslLib.h

Prototype

int32_t (
   *SslCallbackFunc
) (
   SslCallback *cb,
   int32_t command,
   int32_t argi,
   void *argv
)

Parameters

cb
The SslCallback structure itself.
command
A command which specifies the reason for the callback. A single callback structure can be used to handle several different types of SslLib callbacks. In this case, the function must have conditional logic to distinguish between the different commands. The command is used to interpret the remaining two parameters, argi and argv.
argi
A command-specific 32-bit integer, normally used to specify more information about the reason for the callback.
argv
Pointer to a value that is normally determined by the command and/or the argi arguments.

Returns

Returns errNone if the callback command was process without error, or a command-specific error code value otherwise.

Comments

An application will supply an SslCallback structure to the SslLib library. When SslLib needs to then invoke the callback, the callback function is called with four arguments.

When an SslCallback is passed into SslLib, a copy is taken of the structure. This means that the structure passed in can be thought of as a template. It is important to remember that the data field will be copied, so if the object this element points to must be destroyed, additional logic will be required. When a SslContext is created, the SslCallback structures supplied to the SslLib are copied into the SslContext. This could cause problems if not handled correctly if the data pointed to by the data field is dynamic memory.

There are several general 'commands' that all callbacks should expect to receive; these commands are listed under "SSL Callback Commands." There are normally related to creation and destruction of the structure that holds the callback. If the callback does need to perform any action due to these conditions, return 0.

Example

If a callback returns a non-zero value, the SSL library will treat this as an error and return this value back out to the application. This can be used to implement abort functionality. While in the callback, any SslLib functions can be called to retrieve further information. If an sslCmdInfoAlert command is being processed, SslContextGet_LastAlert() can be called to retrieve the alert message that was received as shown here:


alert=SslContextGet_LastAlert(cb->ssl); 

The alert values that can be returned are listed under "SSL Server Alerts."

There are two defined callbacks currently used by SslLib: "Info" and "Verify."

The Info Callback

For the Info callback, the command parameter is set to sslCmdInfo. The argi, and argv values passed are as follows:

argi

argv type

sslArgInfoHandshake

NULL

sslArgInfoAlert

NULL

sslArgInfoReadBefore

SslIoBuf

sslArgInfoReadAfter

SslIoBuf

sslArgInfoWriteBefore

SslIoBuf

sslArgInfoWriteAfter

SslIoBuf

sslArgCert

SslExtendedItems - the certificate sent by the server.

See "Info Callbacks" for more information on these argi values.

This wealth of information makes it possible for the application to receive notification of state changes in the SSL protocol, receive any SSL protocol alert messages, and track the I/O operation that the SSL protocol is performing. This callback is primarily intended to aid in debugging applications or to provide visual feedback to the progress of the SSL protocol.

The Verify Callback

For the Verify callback, the command parameter is set to sslCmdVerify. The argi, and argv values passed are as follows:

argi

argv type

CertMgrVerifyFailSignature

SslVerify

CertMgrVerifyFailUnknownIssuer

SslVerify

CertMgrVerifyFailNotAfter

SslVerify

CertMgrVerifyFailNotBefore

SslVerify

CertMgrVerifyFailBasicConstraints

SslVerify

CertMgrVerifyFailCriticalExtension

SslVerify

errNone

SslVerify

During the SSL handshake the server side sends a certificate to the client. This certificate contains the server's public key. SslLib attempts to verify that the certificate is valid. During this certificate verification process, if there are any errors, the Verify callback is called.

The application can, through this callback, override any of the error conditions reported during verification. If there is no Verify callback associated with an SslContext, any errors will immediately be returned to the application.

The Verify callback will be called as each certificate in the certificate chain is verified with any error values encountered passed in argi until the certificate is verified. If the certificate verifies ok, the 0 value is passed. This process is repeated for each certificate. This means that even if the certificate chain verifies without an error, the callback will be called once for each certificate (with a 0 argi value). If an Info callback is also registered, it would be called once after the certificate chain has been verified with the server's certificate. If there is no verification callback, and an error occurs, the application can 'clear' the error and re-call the relevant SslLib function. The verification will proceed from where it was up to.

The SslVerify Structure

The SslVerify structure is defined as follows:


typedef struct SslVerify_st {
   SslExtendedItems *certificate;
   SslExtendedItems *fieldItems;   /* Problem field base */
   UInt32 field;                   /* Problem field */
   SslExtendedItems *ex;           /* Extension */
   UInt32 depth;                   /* Certificate depth */
   UInt32 state;                   /* Verification state */
} SslVerify; 


NOTE: The SslVerify structure is not declared in the Palm OS header files. In order to use it you'll have to declare it yourself.

certificate is a pointer to a structure containing the certificate currently being processed. fieldItems is a pointer to a structure that contains the data element that is currently causing a problem. field is the index into fieldItems of the erroneous data element. The ex field, if there is an error in extension processing, contains the data element that makes up the X509 extension that just failed. depth is the level of the certificate being processed, where 0 is the server's certificate, and higher numbers are certificates being used to chain to a trusted root certificate.

The following #defines represent the possible values of the state field. They indicate which section of the certificate verification failed.


#define sslVerifyFindParent 1
#define sslVerifySignature 2
#define sslVerifyNotBefore 3
#define sslVerifyNotAfterFindParent 4
#define sslVerifyExtensions 5
#define sslVerifyDone 6 


NOTE: The above #defines are not declared in the Palm OS header files. In order to use them you'll have to declare them yourself.

fieldItems will not always be the same pointer as certificate. This is especially true during extension errors. If we have an error in an extension, and the extension has been "decomposed," the "decomposed" elements will be in the ex field. The object identifier that identifies the extension "decomposed" in ex would be verify->fieldItems.item[verify->field].

The following table lists the elements identified by the fieldItems and field values.

sslErrCertBadSignature

The server's certificate, which contains the public key entries.

SslErrCertNoTrustedRoot

NULL

SslErrCertNotAfter

sslExItemTypeX509, asn1FldX509NotAfter

SslErrCertNotBefore

sslExItemTypeX509, asn1FldX509NotBefore

sslErrCertConstraintViolation

asn1ExItemTypeX509Ex start location

sslErrCertUnknownCriticalExtension

asn1ExItemTypeX509Ex start location

SslErrOk

NULL

See the following section, "Extensions and Critical Extensions," for background on the cases of the returned field being the "asn1ExItemTypeX509Ex start location."

Extensions and Critical Extensions

A certificate can have zero or more extensions. These extensions specify extra information to be used during evaluation of a certificate. Each extension consists of an "Object identifier," an optional Boolean "critical extension" flag, and the data bytes. The fieldItems->item[field] values in this case points to the SslExtendedItem that contains the "Object identifier" for that extension. field+1 will reference either the optional Boolean field that flags the extension as critical or the data bytes.


SslVerify *verify; 
SslExtendedItem *oid,*critical,*data; 
 
oid= &(verify->fieldItems[verify->field]); 
if (verify->fieldItems[verify->field+1].data_type == 
asn1Boolean) 
   { 
   critical=(verify->fieldItems[verify->field+1]); 
   data=(verify->fieldItems[verify->field+2]); 
   } 
else 
   { 
   critical=NULL; 
   data= &(verify->fieldItems[verify->field+1]); 
   } 
/* The data bytes for the 'data' is located at 
 * ((Uint8 *)verify->fieldItems)+data->offset; 

SslLib attempts to interpret only critical extensions, so the critical field should always be present. If a critical extension is not understood, the certificate should be rejected. These callback values allow the application to accept a certificate with critical extensions that the application SslLib does not understand.

SslLib recognizes three extensions at this point in time, taken from the X.509 standard:

2.5.29.15

KeyUsage

2.5.29.37

ExtKeyUsage

2.5.29.19

BasicConstraints

If any of these constraints are flagged as critical, an error will not occur (assuming they are valid).


IMPORTANT: In Palm OS Cobalt version 6.1 and earlier, the SSL library does not process the BasicConstraints or KeyUsage extensions. If the SSL library finds a critical extension of any type, CertMgrVerifyFailCriticalExtension is returned to the application. For more information, see "Critical Extensions."

BasicConstraints is the only extension currently verified. It specifies if a certificate can be used for signing other certificates. If the certificate is being used incorrectly, an sslErrCertConstraintViolation error will be generated. For this error, the ex field of the SslVerify structure will potentially contain


asn1ExItemTypeX509ExData, asn1FldX509ExBasicConstraintsCa 
asn1ExItemTypeX509ExData, asn1FldX509ExBasicConstraintsPathLenConstraint 

Note that if these optional fields are not in the certificate, they will not be present in the SslExtendedItems. The PathLenConstraint will also not contain any data bytes; rather,. the numeric value this field contains will be encoded in the len field of the SslExtendedItem. If this was not the case, the application would have to learn all about decoding ASN.1 integers. The depth field relates to this certificate.

If this error occurs, the application should not override the error, due to its serious nature.

The SslExtendedItems Structure

The SslExtendedItems structure is defined as follows:


typedef struct SslExtendedItems_st {
   UInt32 length;
   UInt32 num;
   SslExtendedItem eitem[1];
} SslExtendedItems; 


NOTE: The SslExtendedItems structure is not declared in the Palm OS header files. In order to use it you'll have to declare it yourself.

The SslExtendedItems structure is used to hold a set of SslExtendedItem structures. The eitem field, while defined as a size of one, is actually large enough to hold num entries. The length field is the total size of the structure. The structure can be copied by allocating length bytes and then copying length bytes from the SslExtendedItems pointer into the new location. An SslExtendedItems structure is used to hold sets of related data elements. A set of such values may contain a RSA public key, a certificate, and a certificate extension all in the same SslExtendedItems structure.

The SslExtendedItem Structure

Each SslExtendedItem belongs to a type that is predefined for each of these objects.

Currently defined values are:

sslExItemTypeX509

X.509 Certificate.

SslExItemTypeRSA

RSA public key.

sslExItemTypeRDN

An X.509 Relative Distinguished Name (RDN). This is a complex way of saying a certificate name. Each certificate contains two names, the Subject of the certificate and the Issuer of the certificate. Both are encoded as RDNs which contain multiple fields.

sslExItemTypeX509Ex

X.509 certificates can contain what are called Extensions. A certificate can contain multiple extensions. This type is used to specify extensions.

SslExItemTypeE509ExData

Used to group 'decomposed' X.509 extensions.

The SslExtendedItem structure is defined as follows:


typedef struct SslExtendedItem_st {
   UInt16 type;
   UInt16 field;
   UInt16 dataType;
   UInt16 len;
   UInt32 offset;
} SslExtendedItem; 


NOTE: The SslExtendedItem structure is not declared in the Palm OS header files. In order to use it you'll have to declare it yourself.

An SslExtendedItem structure is a single data element. The type field values (as specified in the preceding table) are used to group related items. A single SslExtendedItems structure can contain multiple SslExtendedItem structures with different type values. In this way a single structure can contain elements referring to both a certificate and an RSA public key.

The field field contains a type-specific value that is used to identify the SslExtendedItem. The values for this field are defined specifically for each type.

The dataType field specifies the encoding type of the data. For the cases being used by SslLib, the value is the ASN.1 encoding type. These values are defined in the SslLibAsn1.h header file. They are relevant primarily if the application is attempting to display the data bytes.

The len field is the length of the data in the SslExtendedItem

The offset field is the offset from the start of the parent SslExtendedItems to the data field.

To access all the data bytes in an SslExtendedItems structure:


SslExtendedItems *ei; 
UInt16 i,j; 
UInt8 *p; 
 
for (i=0; i<ei->num; i++) { 
   p=((Uint8 *)ei)+ei->eitem[i].offset; 
 
   for (j=0; j<ei->eitem[i].len; j++) 
      doSomething(p[j]); 
} 

An SslExtendedItems structure will often contain multiple types. When SslLib returns an SslExtendedItems structure for a certificate, it will usually contain the types sslExItemTypeX509, sslExItemTypeRSA, and sslExItemTypeRDN (for the subject name).

Example

Following is an example of usage from the SslLib, for the 'information' callback:


Int32 info_callback(SslCallback *cb,Int32 command, 
   Int32 argi,void *argv); 
 
SslCallback infoCB; 
 
infoCB.callback=info_callback; 
SslContextSet_InfoCallback(ssl,&infoCB); 
SslContextSet_InfoInteresrt(ssl, 
   sslFlgInfoAlert| 
   sslFlgInfoHandshake| 
   sslFlgInfoIo); 
 
/* We have now configured the SslContext so that 
 * info_callback will be called when 'interesting' events 
 * occur. */ 
 
Int32 info_callback(SslCallback *cb,Int32 command, 
   Int32 argi, void *argv) 
   { 
   UInt32 alert; 
 
   switch (command){ 
   case sslCmdInfo: 
      /* We have received an 'info' call */ 
      switch (argi){ 
      case sslArgInfoHandshake: 
         /* The SslContext is in the handshake stage 
            of connection establishment. */ 
         break; 
      case sslArgInfoAlert: 
         /* An Alert message was received by the SslContext*/ 
         alert=SslContextGet_LastAlert(cb->ssl); 
         break; 
      case sslArgInfoReadBefore: 
      case sslArgInfoReadAfter: 
      case sslArgInfoWriteBefore: 
      case sslArgInfoWriteAfter: 
         /* The SslContext is doing network operations */ 
         break; 
      } 
      break; 
   case sslCmdNew:   /* Called when we are 'copied in' */ 
   case sslCmdFree:   /* Called when we are 'finished' */ 
   case sslCmdReset:   /* Called instead of 'sslCmdNew' to
      reset the settings */ 
   case sslCmdSet:   /* Set a value */ 
   case sslCmdGet:   /* Get a value */ 
      break; 
   } 
   return(0); 
}