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

17    SSL Library Macros

Security and Cryptography

Exploring Palm OS

This chapter provides reference documentation for the macros that your application uses to set and get SslLib and SslContext attribute values. As well, the constants representing those attributes are listed in this chapter.

This chapter is divided into the following sections:

SSL Library Macro Constants
SSL Library Macros

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

Documentation for the functions that these macros employ can be found in Chapter 16, "SSL Library." A detailed description of each attribute can be found under "Attributes."

SSL Library Macro Constants ^TOP^

Attribute Values ^TOP^

Purpose

These constants represent the attributes that you can set or get by calling SslContextGet...(), SslContextSet...(), SslLibGet...(), or SslLibSet...(). The macros documented in "SSL Library Macros" call the appropriate function and supply the proper attribute value. Accordingly, applications should use these macros instead of calling the set or get functions directly.

Complete documentation for the attributes that these values represent can be found in Chapter 2, "SSL Concepts."

Declared In

SslLibMac.h

Constants

#define sslAttrAppInt32 0x0F0A0A13
#define sslAttrAppPtr 0x0F090911
#define sslAttrAutoFlush 0x0F070712
#define sslAttrBufferedReuse 0x0F080812
#define sslAttrCertPeerCert 0x0100FF01
#define sslAttrCertPeerCertInfoType 0x0102FF01
#define sslAttrCertPeerCommonName 0x0180FF01
#define sslAttrCertSslVerify 0x0101FF04
#define sslAttrCertVerifyChain 0x0103FF01
#define sslAttrClientCertRequest 0x0F20FF12
#define sslAttrCompat 0x0F010113
#define sslAttrCspCipherSuite 0x0001FF01
#define sslAttrCspCipherSuiteInfo 0x0082FF01
#define sslAttrCspCipherSuites 0x00008101
#define sslAttrCspSslSession 0x00808001
#define sslAttrDelayReadServerFinished 0x0F232312
#define sslAttrDontSendShutdown 0x0F212112
#define sslAttrDontWaitForShutdown 0x0F222212
#define sslAttrError 0x0F111113
#define sslAttrErrorState 0x0F05FF14
#define sslAttrHelloVersion 0x0F242412
#define sslAttrHsState 0x0F12FF13
#define sslAttrInfoCallback 0x0F0E0E15
#define sslAttrInfoInterest 0x0F020213
#define sslAttrIoFlags 0x04030303
#define sslAttrIoSocket 0x04010103
#define sslAttrIoStruct 0x04008001
#define sslAttrIoTimeout 0x04020203
#define sslAttrLastAlert 0x0F131313
#define sslAttrLastApi 0x0F1FFF12
#define sslAttrLastIo 0x0F1EFF12
#define sslAttrLibAppInt32 0x0F0F0F03
#define sslAttrLibAppPtr 0x0F0E0E01
#define sslAttrLibAutoFlush 0x0F0C0C02
#define sslAttrLibBufferedReuse 0x0F0D0D02
#define sslAttrLibCompat 0x0F010103
#define sslAttrLibDelayReadServerFinished 0x0F141402
#define sslAttrLibDontSendShutdown 0x0F121202
#define sslAttrLibDontWaitForShutdown 0x0F131302
#define sslAttrLibHelloVersion 0x0F151503
#define sslAttrLibInfoCallback 0x0F080805
#define sslAttrLibInfoInterest 0x0F020203
#define sslAttrLibMode 0x0F040403
#define sslAttrLibProtocolSupport 0x0F161603
#define sslAttrLibProtocolVersion 0x0F030303
#define sslAttrLibRbufSize 0x0F101003
#define sslAttrLibReadStreaming 0x0F0B0B02
#define sslAttrLibVerifyCallback 0x0F0A0A05
#define sslAttrLibWbufSize 0x0F111103
#define sslAttrMode 0x0F048013
#define sslAttrProtocolSupport 0x0F252512
#define sslAttrProtocolVersion 0x0F030313
#define sslAttrRbufSize 0x0F1B8113
#define sslAttrReadBufPending 0x0F16FF13
#define sslAttrReadOutstanding 0x0F18FF13
#define sslAttrReadRecPending 0x0F17FF13
#define sslAttrReadStreaming 0x0F060612
#define sslAttrSessionReused 0x0F14FF12
#define sslAttrStreaming 0x0F1DFF12
#define sslAttrVerifyCallback 0x0F101015
#define sslAttrWbufSize 0x0F1C8213
#define sslAttrWriteBufPending 0x0F15FF13

SSL Library Macros ^TOP^

SslContextGet_AppInt32 Macro ^TOP^

Purpose

Obtain the value of the AppInt32 attribute, an arbitrary 32-bit value that an application can attach to an SslContext.

Declared In

SslLibMac.h

Prototype

#define SslLibGet_AppInt32 (
   lib
)

Parameters

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

Returns

Returns the 32-bit value.

Comments

SslContextDestroy() does not modify this attribute, so if the data pointed to by this attribute needs to be disposed of, the application must do this itself.

See Also

"AppInt32," SslContextSet_AppInt32(), SslLibGet_AppInt32()

SslContextGet_AppPtr Macro ^TOP^

Purpose

Obtain the value of the AppPtr attribute, an arbitrary pointer value that an application can attach to an SslContext.

Declared In

SslLibMac.h

Prototype

#define SslLibGet_AppPtr (
   lib,
    v
)

Parameters

lib
The SslContext from which the value is to be retrieved.
v
The address of a pointer variable into which the AppPtr attribute value is written.

Returns

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

Comments

SslContextDestroy() does not modify this attribute, so if the data pointed to by this attribute needs to be disposed of, the application must do this itself.

See Also

"AppPtr," SslContextSet_AppPtr(), SslLibGet_AppPtr()

SslContextGet_AutoFlush Macro ^TOP^

Purpose

Determine whether SslSend() and SslWrite() attempt to immediately send the supplied data bytes to the network.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_AutoFlush (
   ssl
)

Parameters

ssl
The SslContext from which the value is to be retrieved.

Returns

Returns 0 if data is buffered, or 1 if the data is sent immediately.

Comments

It is very important to remember to use SslFlush() when AutoFlush is disabled.

See Also

"AutoFlush," SslContextSet_AutoFlush(), SslLibGet_AutoFlush()

SslContextGet_BufferedReuse Macro ^TOP^

Purpose

Determine if the last message in an SslSession-reused handshake should be buffered instead of being sent over the network.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_BufferedReuse (
   ssl
)

Parameters

ssl
The SslContext from which the value is to be retrieved.

Returns

Returns 0 if the last message is not buffered, or a non-zero value if it is.

See Also

"BufferedReuse," SslContextSet_BufferedReuse(), SslLibGet_BufferedReuse()

SslContextGet_CertChain Macro ^TOP^

Purpose

Declared In

SslLibMac.h

Prototype

#define SslContextGet_CertChain (
   ssl,
    v
)

Parameters

ssl
The SslContext from which the value is to be retrieved.
v

Returns

SslContextGet_CipherSuite Macro ^TOP^

Purpose

Identify the cipher suite being used by the current connection.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_CipherSuite (
   ssl,
    v
)

Parameters

ssl
The SslContext from which the value is to be retrieved.
v
Pointer to a pointer variable; upon return the pointer variable points to two bytes which identify the cipher suite being used by the current connection. If these two bytes are both set to zero, no cipher suite is being used. Otherwise, see "Cipher Suites" for the list of possible cipher suites.

Returns

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

See Also

"CipherSuite"

SslContextGet_CipherSuiteInfo Macro ^TOP^

Purpose

Obtain information relevant to the current cipher suite. This macro populates a SslCipherSuiteInfo structure that must have been allocated by the caller.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_CipherSuiteInfo (
   ssl,
    v
)

Parameters

ssl
The SslContext from which the value is to be retrieved.
v
Pointer to the SslCipherSuiteInfo structure that is to be filled in.

Returns

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

See Also

"CipherSuiteInfo", SslContextGet_CipherSuite()

SslContextGet_CipherSuites Macro ^TOP^

Purpose

Obtain the list of cipher suites that the SSL protocol is attempting to use.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_CipherSuites (
   ssl,
    v
)

Parameters

ssl
The SslContext from which the value is to be retrieved.
v
Supply the address of a pointer variable; upon return the pointer variable will point to a series of bytes, where the first two bytes indicate the number of bytes that follow, and each pair of bytes after that is one of the values listed under "Cipher Suites." See "CipherSuites" for more details on this attribute.

Returns

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

See Also

"CipherSuites", SslContextSet_CipherSuites(), SslLibGet_CipherSuites()

SslContextGet_ClientCertRequest Macro ^TOP^

Purpose

Determine whether or not the SSL server requested a client certificate.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_ClientCertRequest (
   ssl
)

Parameters

ssl
The SslContext from which the value is to be retrieved.

Returns

Returns 0 if the server did not request a client certificate, or 1 if the server did request one.

See Also

"ClientCertRequest"

SslContextGet_Compat Macro ^TOP^

Purpose

Determine which SSL protocol compatibility flags are set. These flags enable compatibility with certain incorrect SSL protocol implementations.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_Compat (
   ssl
)

Parameters

ssl
The SslContext from which the value is to be retrieved.

Returns

Returns a 32-bit integer value that is the logical OR of those compatibility flags that have been set. See "Compatibility Flags" for the defined constants that correspond to the compatibility flags.

See Also

"Compat," SslContextSet_Compat(), SslLibGet_Compat()

SslContextGet_DelayReadServerFinished Macro ^TOP^

Purpose

Declared In

SslLibMac.h

Prototype

#define SslContextGet_DelayReadServerFinished (
   ssl
)

Parameters

ssl
The SslContext from which the value is to be retrieved.

Returns

SslContextGet_DontSendShutdown Macro ^TOP^

Purpose

Determine whether or not an SslClose() will send a shutdown message to the server.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_DontSendShutdown (
   ssl
)

Parameters

ssl
The SslContext from which the value is to be retrieved.

Returns

Returns zero if SslClose() does send a shutdown message to the server, or a non-zero value if it doesn't.

See Also

"DontSendShutdown," SslContextSet_DontSendShutdown(), SslLibGet_DontSendShutdown(), SslContextGet_DontWaitForShutdown()

SslContextGet_DontWaitForShutdown Macro ^TOP^

Purpose

Determine whether or not the SslContext will wait for a shutdown message in SslClose().

Declared In

SslLibMac.h

Prototype

#define SslContextGet_DontWaitForShutdown (
   ssl
)

Parameters

ssl
The SslContext from which the value is to be retrieved.

Returns

Returns zero if the SslContext waits for a shutdown message, or a non-zero value if it doesn't.

See Also

"DontWaitForShutdown," SslLibGet_DontWaitForShutdown(), SslContextGet_DontSendShutdown(), SslContextSet_DontWaitForShutdown()

SslContextGet_Error Macro ^TOP^

Purpose

Obtain the error value produced when a fatal error occurs while using an SslContext.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_Error (
   ssl
)

Parameters

ssl
The SslContext from which the value is to be retrieved.

Returns

Returns 0 if there was no error, or one of the error codes listed under "SSL Library Errors" if an error did occur.

Comments

Once the error attribute is set, the SslLib network APIs will continue to return this error (unless the error is a non-fatal error) until either an SSL Reset is performed on the SslContext or the error is cleared.

See Also

"Error," SslContextSet_Error()

SslContextGet_HelloVersion Macro ^TOP^

Purpose

Declared In

SslLibMac.h

Prototype

#define SslContextGet_HelloVersion (
   ssl
)

Parameters

ssl
The SslContext from which the value is to be retrieved.

Returns

SslContextGet_HsState Macro ^TOP^

Purpose

Determine the state that the SSL protocol is currently in.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_HsState (
   ssl
)

Parameters

ssl
The SslContext from which the value is to be retrieved.

Returns

One of the values are defined under "SSL Protocol States" to indicate the SSL protocol handshake.

See Also

"HsState"

SslContextGet_InfoCallback Macro ^TOP^

Purpose

Obtain a pointer to the callback function called when various situations occur during the usage of an SslContext. This callback is primarily intended for debugging and feedback purposes.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_InfoCallback (
   ssl,
    v
)

Parameters

ssl
The SslContext from which the value is to be retrieved.
v
Pass the address of a pointer variable; upon return this variable will point to the callback function. The callback function is of type SslCallbackFunc().

Returns

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

Comments

See "InfoCallback" and SslCallbackFunc() (documented) for more on how this callback function is used.

See Also

"InfoCallback," SslContextSet_InfoCallback(), SslLibGet_InfoCallback()

SslContextGet_InfoInterest Macro ^TOP^

Purpose

Obtain the flags that specify the events for which the Info callback will be called.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_InfoInterest (
   ssl
)

Parameters

ssl
The SslContext from which the value is to be retrieved.

Returns

The logical OR of the sslFlgInfoxxx values listed under "InfoInterest Values."

See Also

"InfoInterest," SslContextSet_InfoInterest(), SslLibGet_InfoInterest()

SslContextGet_IoFlags Macro ^TOP^

Purpose

Obtain the flags value that is passed to sys/socket calls.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_IoFlags (
   ssl
)

Parameters

ssl
The SslContext from which the value is to be retrieved.

Returns

The 32-bit flags value that is passed to sys/socket calls.

Comments

Since we will normally be using TCP connections with SSL, this attribute is more included for completeness rather than utility. Read about this flags value in the sendto() and recvfrom() man page.


NOTE: The MSG_OOB and MSG_PEEK values are not valid and will be silently removed.

See Also

"IoFlags," SslContextSet_IoFlags()

SslContextGet_IoStruct Macro ^TOP^

Purpose

Obtain the SslContext's internal SslSocket structure.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_IoStruct (
   ssl,
    v
)

Parameters

ssl
The SslContext from which the value is to be retrieved.
v
Pass the address of a pointer variable. Upon return the variable will point to the SslContext's SslSocket structure.

Returns

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

See Also

"IoStruct," SslContextSet_IoStruct()

SslContextGet_IoTimeout Macro ^TOP^

Purpose

Obtain the SslContext's internal timeout value.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_IoTimeout (
   ssl
)

Parameters

ssl
The SslContext from which the value is to be retrieved.

Returns

The internal timeout value, in seconds.

Comments

When a call is made into the SslLib API which does not specify a timeout, this internal value is used. If the API call has a timeout value, it overrides this internal value.

By default, the SslContext's internal timeout value is 10 seconds.

See Also

"IoTimeout," SslContextSet_IoTimeout()

SslContextGet_LastAlert Macro ^TOP^

Purpose

Obtain the last alert value received from the server.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_LastAlert (
   ssl
)

Parameters

ssl
The SslContext from which the value is to be retrieved.

Returns

One of the values listed under "SSL Server Alerts."

Comments

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.

See Also

"LastAlert", SslContextSet_LastAlert()

SslContextGet_LastApi Macro ^TOP^

Purpose

Identify the last SslLib API call that was made.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_LastApi (
   ssl
)

Parameters

ssl
The SslContext from which the value is to be retrieved.

Returns

Returns one of the values listed under "LastApi Attribute Values."

See Also

"LastApi"

SslContextGet_LastIo Macro ^TOP^

Purpose

Identify the last network operation performed.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_LastIo (
   ssl
)

Parameters

ssl
The SslContext from which the value is to be retrieved.

Returns

Returns one of the values listed under "LastIO Attribute Values."

See Also

"LastIo"

SslContextGet_Mode Macro ^TOP^

Purpose

Obtain the value of the Mode attribute, which controls whether the SSL protocol is on or off.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_Mode (
   ssl
)

Parameters

ssl
The SslContext from which the value is to be retrieved.

Returns

Returns one of the values listed under "Mode Attribute Values."

See Also

"Mode," SslContextSet_Mode(), SslLibGet_Mode()

SslContextGet_PeerCert Macro ^TOP^

Purpose

Obtain the certificate supplied by the other end of the SSL connection, if one is available.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_PeerCert (
   ssl,
    v
)

Parameters

ssl
The SslContext from which the value is to be retrieved.
v
Pass the address of a pointer variable. Upon return that variable will reference an SslExtendedItems data structure internal to the SslContext that contains the peer certificate.

Returns

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

Comments

The returned pointer references an SslExtendedItems data structure which is internal to the SslContext and will be disposed of by the SslContext. If a new connection is established with the SslContext, previously returned PeerCert pointers will become invalid. If the application wishes to preserve the certificate for an extended period, it should make a local copy.

See Also

"PeerCert", "The SslExtendedItems Structure," SslContextGet_PeerCertInfoType(), SslContextGet_PeerCommonName()

SslContextGet_PeerCertInfoType Macro ^TOP^

Purpose

Declared In

SslLibMac.h

Prototype

#define SslContextGet_PeerCertInfoType (
   ssl,
    v
)

Parameters

ssl
The SslContext from which the value is to be retrieved.
v

Returns

SslContextGet_PeerCommonName Macro ^TOP^

Purpose

Obtain the server certificate's common name.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_PeerCommonName (
   ssl,
    v
)

Parameters

ssl
The SslContext from which the value is to be retrieved.
v
Supply the address of a pointer variable. Upon return the variable will point to an SslExtendedItems structure containing the common name for the server's certificate (or, if there is no common name available, the variable will be set to NULL.)

Returns

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

Example

The following code shows how to access the common name from within the SslExtendedItem structure:


SslExtendedItems *cert; 
SslExtendedItem *commonName; 
uint16_t length; 
uint8_t *bytes; 
 
SslContextGet_PeerCert(ssl, &cert); 
if (cert == NULL) goto err; 
SslContextGet_PeerCommonName(ssl,&commonName); 
length=commonName->len; 
bytes=((Int8 *)cert)+commonName->offset; 
// bytes now points to the common name, and length contains 
// the length of the common name string. 

See Also

"PeerCommonName", "The SslExtendedItems Structure"

SslContextGet_ProtocolSupport Macro ^TOP^

Purpose

Determine which variants of the SSL protocol are being used.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_ProtocolSupport (
   ssl
)

Parameters

ssl
The SslContext from which the value is to be retrieved.

Returns

One or more of the values listed under "Protocol Variants," OR'd together.

See Also

SslContextGet_ProtocolVersion(), SslContextSet_ProtocolSupport(), SslLibGet_ProtocolSupport()

SslContextGet_ProtocolVersion Macro ^TOP^

Purpose

Determine which version of the SSL protocol is being used.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_ProtocolVersion (
   ssl
)

Parameters

ssl
The SslContext from which the value is to be retrieved.

Returns

One of the values listed under "Protocol Versions."

See Also

"ProtocolVersion," SslContextSet_ProtocolVersion(), SslLibGet_ProtocolVersion()

SslContextGet_RbufSize Macro ^TOP^

Purpose

Obtain the size, in bytes, of the SslContext's read buffer.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_RbufSize (
   ssl
)

Parameters

ssl
The SslContext from which the value is to be retrieved.

Returns

The read buffer size. This is a value that ranges from 0 to 16384.

See Also

"RbufSize," SslContextSet_RbufSize(), SslLibGet_RbufSize()

SslContextGet_ReadBufPending Macro ^TOP^

Purpose

Obtains the number of data bytes that are currently buffered for reading from the SslContext.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_ReadBufPending (
   ssl
)

Parameters

ssl
The SslContext from which the value is to be retrieved.

Returns

The number of buffered read bytes.

Comments

The returned number of bytes also includes bytes used for encoding SSL records.

See Also

"ReadBufPending"

SslContextGet_ReadOutstanding Macro ^TOP^

Purpose

Obtain the number of bytes in the current record that have not been read from the network

Declared In

SslLibMac.h

Prototype

#define SslContextGet_ReadOutstanding (
   ssl
)

Parameters

ssl
The SslContext from which the value is to be retrieved.

Returns

The number of bytes outstanding in current SSL record.

See Also

"ReadOutstanding"

SslContextGet_ReadRecPending Macro ^TOP^

Purpose

Obtain the number of application data bytes that are buffered, awaiting the application to read.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_ReadRecPending (
   ssl
)

Parameters

ssl
The SslContext from which the value is to be retrieved.

Returns

The number of buffered SSL record bytes.

See Also

"ReadRecPending," SslContextGet_ReadOutstanding()

SslContextGet_ReadStreaming Macro ^TOP^

Purpose

Determine whether data can be returned to the application from the SSL connection before the full record has been downloaded.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_ReadStreaming (
   ssl
)

Parameters

ssl
The SslContext from which the value is to be retrieved.

Returns

Returns a zero value if data is only returned when the full record has been downloaded, or a non-zero value otherwise.

See Also

"ReadStreaming," SslContextSet_ReadStreaming(), SslLibGet_ReadStreaming()

SslContextGet_SessionReused Macro ^TOP^

Purpose

Determine whether the SSL handshake was able to perform a truncated handshake by re-using the SSL session values in the SslContext.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_SessionReused (
   ssl
)

Parameters

ssl
The SslContext from which the value is to be retrieved.

Returns

Returns a non-zero value if the SSL handshake was able to perform a truncated handshake by re-using the SSL session values in the SslContext, or zero if it wasn't.

See Also

"SessionReused"

SslContextGet_Socket Macro ^TOP^

Purpose

Obtain the socket that the SslContext should use to perform its network I/O operations.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_Socket (
   ssl
)

Parameters

ssl
The SslContext from which the value is to be retrieved.

Returns

The descriptor for the SslContext's socket.

See Also

"Socket," SslContextSet_Socket()

SslContextGet_SslSession Macro ^TOP^

Purpose

Get the SslContext's SslSession structure. This is either the SslSession currently being used, or the SslSession for this SslContext to use to establish its next connection.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_SslSession (
   ssl,
    v
)

Parameters

ssl
The SslContext from which the value is to be retrieved.
v
Pass the address of a pointer variable; upon return this variable will point to the SslContext's SslSession structure.

Returns

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

See Also

"SslSession," SslContextSet_SslSession()

SslContextGet_SslVerify Macro ^TOP^

Purpose

Obtain a pointer to the structure containing the verification state. This structure can be helpful when attempting to resolve any problems that SslLib may have encountered during certificate verification.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_SslVerify (
   ssl,
    v
)

Parameters

ssl
The SslContext from which the value is to be retrieved.
v
Supply the address of a pointer variable. Upon return the variable will point to an SslVerify structure containing the preserved state. See "The SslVerify Structure" for a description of this structure.

Returns

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

See Also

"SslVerify"

SslContextGet_Streaming Macro ^TOP^

Purpose

Determine if the current SslContext is doing read-streaming.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_Streaming (
   ssl
)

Parameters

ssl
The SslContext from which the value is to be retrieved.

Returns

Returns 1 if the current SslContext is doing read-streaming.

See Also

"Streaming"

SslContextGet_VerifyCallback Macro ^TOP^

Purpose

Obtain a pointer to the callback function used to assist with certificate verification.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_VerifyCallback (
   ssl,
    v
)

Parameters

ssl
The SslContext from which the value is to be retrieved.
v
Pass the address of a pointer variable; upon return this variable will point to the callback function. The callback function is of type SslCallbackFunc().

Returns

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

Comments

See "VerifyCallback" and SslCallbackFunc() (documented) for more on how this callback function is used to verify a certificate.

See Also

"VerifyCallback," SslContextSet_VerifyCallback(), SslLibGet_VerifyCallback()

SslContextGet_WbufSize Macro ^TOP^

Purpose

Obtain the size, in bytes, of the SslContext's write buffer.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_WbufSize (
   ssl
)

Parameters

ssl
The SslContext from which the value is to be retrieved.

Returns

The write buffer size. This is a value that ranges from 0 to 16384.

See Also

"WbufSize," SslContextSet_WbufSize(), SslLibGet_WbufSize()

SslContextGet_WriteBufPending Macro ^TOP^

Purpose

Obtains the number of bytes in the SslContext's write buffer waiting to be sent to the remote machine.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_WriteBufPending (
   ssl
)

Parameters

ssl
The SslContext from which the value is to be retrieved.

Returns

The number of buffered bytes waiting to be sent.

Comments

This value will normally be zero unless AutoFlush is disabled and/or non-blocking I/O is being used.

See Also

"WriteBufPending", SslContextGet_AutoFlush()

SslContextSet_AppInt32 Macro ^TOP^

Purpose

Set the value of the AppInt32 attribute, an arbitrary 32-bit value that an application can attach to an SslContext.

Declared In

SslLibMac.h

Prototype

#define SslContextSet_AppInt32 (
   ssl,
    v
)

Parameters

ssl
The SslContext on which to operate.
v
The 32-bit value.

Returns

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

Comments

SslContextDestroy() does not modify this attribute, so if the data pointed to by this attribute needs to be disposed of, the application must do this itself.

See Also

"AppInt32," SslContextGet_AppInt32(), SslLibSet_AppInt32()

SslContextSet_AppPtr Macro ^TOP^

Purpose

Set the value of the AppPtr attribute, an arbitrary pointer value that an application can attach to an SslContext.

Declared In

SslLibMac.h

Prototype

#define SslContextSet_AppPtr (
   ssl,
    v
)

Parameters

ssl
The SslContext on which to operate.
v
The AppPtr attribute value.

Returns

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

Comments

SslContextDestroy() does not modify this attribute, so if the data pointed to by this attribute needs to be disposed of, the application must do this itself.

See Also

"AppPtr," SslContextGet_AppPtr(), SslLibSet_AppPtr()

SslContextSet_AutoFlush Macro ^TOP^

Purpose

Specify whether SslSend() and SslWrite() should attempt to immediately send the supplied data bytes to the network.

Declared In

SslLibMac.h

Prototype

#define SslContextSet_AutoFlush (
   ssl,
    v
)

Parameters

ssl
The SslContext on which to operate.
v
Pass 0 to have the data buffered, or 1 to have the data sent immediately.

Returns

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

Comments

It is very important to remember to use SslFlush() when AutoFlush is disabled.

See Also

"AutoFlush," SslContextGet_AutoFlush(), SslLibSet_AutoFlush()

SslContextSet_BufferedReuse Macro ^TOP^

Purpose

Specify whether the last message in an SslSession-reused handshake should be buffered instead of being sent over the network.

Declared In

SslLibMac.h

Prototype

#define SslContextSet_BufferedReuse (
   ssl,
    v
)

Parameters

ssl
The SslContext on which to operate.
v
Supply a value of 0 if the last message should not be buffered, or a non-zero value if it should.

Returns

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

See Also

"BufferedReuse," SslContextGet_BufferedReuse(), SslLibSet_BufferedReuse()

SslContextSet_CipherSuites Macro ^TOP^

Purpose

Specify the list of cipher suites that the SSL protocol should attempt to use.

Declared In

SslLibMac.h

Prototype

#define SslContextSet_CipherSuites (
   ssl,
    v
)

Parameters

ssl
The SslContext on which to operate.
v
Pointer to an array of byte pairs. The first two bytes contain the number of bytes that follow, and each successive pair is one of the values listed under "Cipher Suites."

Returns

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

See Also

"CipherSuites", SslContextGet_CipherSuites(), SslLibSet_CipherSuites()

SslContextSet_Compat Macro ^TOP^

Purpose

Determine how compatible the SSL protocol should be with certain incorrect SSL protocol implementations.

Declared In

SslLibMac.h

Prototype

#define SslContextSet_Compat (
   ssl,
    v
)

Parameters

ssl
The SslContext on which to operate.
v
The logical OR of those compatibility flags that correspond to the SSL protocol incompatibilities that should be accommodated. See "Compatibility Flags" for the defined constants that correspond to the compatibility flags.

Returns

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

See Also

"Compat," SslContextGet_Compat(), SslLibSet_Compat()

SslContextSet_DelayReadServerFinished Macro ^TOP^

Purpose

Declared In

SslLibMac.h

Prototype

#define SslContextSet_DelayReadServerFinished (
   ssl,
    v
)

Parameters

ssl
The SslContext on which to operate.
v

Returns

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

SslContextSet_DontSendShutdown Macro ^TOP^

Purpose

Specify whether or not an SslClose() should send a shutdown message to the server.

Declared In

SslLibMac.h

Prototype

#define SslContextSet_DontSendShutdown (
   ssl,
    v
)

Parameters

ssl
The SslContext on which to operate.
v
Zero if SslClose() should send a shutdown message, or a non-zero value if it shouldn't.

Returns

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

See Also

"DontSendShutdown," SslContextGet_DontSendShutdown(), SslLibSet_DontSendShutdown(), SslContextSet_DontWaitForShutdown()

SslContextSet_DontWaitForShutdown Macro ^TOP^

Purpose

Specify whether or not the SslContext should wait for a shutdown message in SslClose().

Declared In

SslLibMac.h

Prototype

#define SslContextSet_DontSendShutdown (
   ssl,
    v
)

Parameters

ssl
The SslContext on which to operate.
v
Zero if the SslContext waits for a shutdown message, or a non-zero value if it doesn't.

Returns

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

See Also

"DontWaitForShutdown," SslContextGet_DontWaitForShutdown(), SslContextSet_DontSendShutdown(), SslLibSet_DontWaitForShutdown()

SslContextSet_Error Macro ^TOP^

Purpose

Associate a new error value with an SslContext. This value overrides any error value produced when a fatal error occurs while using an SslContext.

Declared In

SslLibMac.h

Prototype

#define SslContextSet_Error (
   ssl,
    v
)

Parameters

ssl
The SslContext on which to operate.
v
The new error value. A value of 0 corresponds to "no error."

Returns

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

Comments

Once the error attribute is set, the SslLib network APIs will continue to return this error (unless the error is a non-fatal error) until either an SSL Reset is performed on the SslContext or the error is cleared.

See Also

"Error," SslContextGet_Error()

SslContextSet_HelloVersion Macro ^TOP^

Purpose

Declared In

SslLibMac.h

Prototype

#define SslContextSet_HelloVersion (
   ssl,
    v
)

Parameters

ssl
The SslContext on which to operate.
v

Returns

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

SslContextSet_InfoCallback Macro ^TOP^

Purpose

Specify the callback function called when various situations occur during the usage of an SslContext. This callback is primarily intended for debugging and feedback purposes.

Declared In

SslLibMac.h

Prototype

#define SslContextSet_InfoCallback (
   ssl,
    v
)

Parameters

ssl
The SslContext on which to operate.
v
A pointer to a callback function of type SslCallbackFunc().

Returns

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

Comments

See "InfoCallback" and SslCallbackFunc() (documented) for more on how this callback function is used.

See Also

"InfoCallback," SslContextGet_InfoCallback(), SslLibSet_InfoCallback()

SslContextSet_InfoInterest Macro ^TOP^

Purpose

Specify the events for which the Info callback will be called.

Declared In

SslLibMac.h

Prototype

#define SslContextSet_InfoInterest (
   ssl,
    v
)

Parameters

ssl
The SslContext on which to operate.
v
The logical OR of the sslFlgInfoxxx values listed under "InfoInterest Values."

Returns

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

See Also

"InfoInterest," SslContextGet_InfoInterest(), SslLibSet_InfoInterest()

SslContextSet_IoFlags Macro ^TOP^

Purpose

Specify the flags value that is to be passed to sys/socket calls.

Declared In

SslLibMac.h

Prototype

#define SslContextSet_IoFlags (
   ssl,
    v
)

Parameters

ssl
The SslContext on which to operate.
v
The 32-bit flags value to be passed to sys/socket calls.

Returns

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

Comments

Since we will normally be using TCP connections with SSL, this attribute is more included for completeness rather than utility. Read about this flags value in the sendto() and recvfrom() man page.


NOTE: The MSG_OOB and MSG_PEEK values are not valid and will be silently removed.

See Also

"IoFlags," SslContextGet_IoFlags()

SslContextSet_IoStruct Macro ^TOP^

Purpose

Specify the SslSocket structure to be used by an SslContext.

Declared In

SslLibMac.h

Prototype

#define SslContextSet_IoStruct (
   ssl,
    v
)

Parameters

ssl
The SslContext on which to operate.
v
Pointer to the SslSocket structure.

Returns

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

See Also

"IoStruct," SslContextSet_IoStruct()

SslContextSet_IoTimeout Macro ^TOP^

Purpose

Specify the SslContext's internal timeout value.

Declared In

SslLibMac.h

Prototype

#define SslContextSet_IoTimeout (
   ssl,
    v
)

Parameters

ssl
The SslContext on which to operate.
v
The new internal timeout value, in seconds.

Returns

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

Comments

When a call is made into the SslLib API which does not specify a timeout, this internal value is used. If the API call has a timeout value, it overrides this internal value.

By default, the SslContext's internal timeout value is 10 seconds.

See Also

"IoTimeout," SslContextGet_IoTimeout()

SslContextSet_LastAlert Macro ^TOP^

Purpose

Override the last alert value received from the server.

Declared In

SslLibMac.h

Prototype

#define SslContextSet_LastAlert (
   ssl,
    v
)

Parameters

ssl
The SslContext on which to operate.
v
The new "last alert" value. This should be one of the values listed under "SSL Server Alerts."

Returns

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

Comments

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.

See Also

"LastAlert", SslContextGet_LastAlert()

SslContextSet_Mode Macro ^TOP^

Purpose

Specify the value of the Mode attribute, which controls whether the SSL protocol is on or off.

Declared In

SslLibMac.h

Prototype

#define SslContextSet_Mode (
   ssl,
    v
)

Parameters

ssl
The SslContext on which to operate.
v
One of the values listed under "Mode Attribute Values."

Returns

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

See Also

"Mode," SslContextGet_Mode(), SslLibSet_Mode()

SslContextSet_ProtocolSupport Macro ^TOP^

Purpose

Specify the SSL protocol variants to use.

Declared In

SslLibMac.h

Prototype

#define SslContextSet_ProtocolSupport (
   ssl,
    v
)

Parameters

ssl
The SslContext on which to operate.
v
One or more of the values listed under "Protocol Variants," OR'd together.

Returns

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

Comments

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


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.

See Also

SslContextGet_ProtocolSupport(), SslContextSet_ProtocolVersion(), SslLibSet_ProtocolSupport()

SslContextSet_ProtocolVersion Macro ^TOP^

Purpose

Specify the version of the SSL protocol to use.

Declared In

SslLibMac.h

Prototype

#define SslContextSet_ProtocolVersion (
   ssl,
    v
)

Parameters

ssl
The SslContext on which to operate.
v
One of the values listed under "Protocol Versions."

Returns

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

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 has no effect—SslLib continues to send a TLSv1 ClientHello message.

See Also

"ProtocolVersion," SslContextGet_ProtocolVersion(), SslLibSet_ProtocolVersion()

SslContextSet_RbufSize Macro ^TOP^

Purpose

Specify the size, in bytes, of the SslContext's read buffer.

Declared In

SslLibMac.h

Prototype

#define SslContextSet_RbufSize (
   ssl,
    v
)

Parameters

ssl
The SslContext on which to operate.
v
The read buffer size. This is a value that ranges from 0 to 16384.

Returns

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

See Also

"RbufSize," SslContextGet_RbufSize(), SslLibSet_RbufSize()

SslContextSet_ReadStreaming Macro ^TOP^

Purpose

Specify whether data can be returned to the application from the SSL connection before the full record has been downloaded.

Declared In

SslLibMac.h

Prototype

#define SslContextSet_ReadStreaming (
   ssl,
    v
)

Parameters

ssl
The SslContext on which to operate.
v
A zero value if data is only to be returned when the full record has been downloaded, or a non-zero value otherwise.

Returns

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

See Also

"ReadStreaming," SslContextGet_ReadStreaming(), SslLibSet_ReadStreaming()

SslContextSet_Socket Macro ^TOP^

Purpose

Specify the socket that the SslContext should use to perform its network I/O operations.

Declared In

SslLibMac.h

Prototype

#define SslContextSet_Socket (
   ssl,
    v
)

Parameters

ssl
The SslContext on which to operate.
v
The descriptor referencing the socket.

Returns

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

See Also

"Socket," SslContextGet_Socket()

SslContextSet_SslSession Macro ^TOP^

Purpose

Specify the SslContext's SslSession structure. This is the SslSession for this SslContext to use to establish its next connection.

Declared In

SslLibMac.h

Prototype

#define SslContextSet_SslSession (
   ssl,
    v
)

Parameters

ssl
The SslContext on which to operate.
v
A pointer to the SslSession structure.

Returns

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

See Also

"SslSession," SslContextGet_SslSession()

SslContextSet_VerifyCallback Macro ^TOP^

Purpose

Specify the callback function to assist with certificate verification.

Declared In

SslLibMac.h

Prototype

#define SslContextSet_VerifyCallback (
   ssl,
    v
)

Parameters

ssl
The SslContext on which to operate.
v
A pointer to a callback function of type SslCallbackFunc().

Returns

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

Comments

See "VerifyCallback" and SslCallbackFunc() (documented) for more on how this callback function is used to verify a certificate.

See Also

"VerifyCallback," SslContextGet_VerifyCallback(), SslLibSet_VerifyCallback()

SslContextSet_WbufSize Macro ^TOP^

Purpose

Specify the size, in bytes, of the SslContext's write buffer.

Declared In

SslLibMac.h

Prototype

#define SslContextSet_WbufSize (
   ssl,
    v
)

Parameters

ssl
The SslContext on which to operate.
v
The write buffer size. This is a value that ranges from 0 to 16384.

Returns

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

See Also

"WbufSize," SslContextGet_WbufSize(), SslLibSet_WbufSize()

SslLibGet_AppInt32 Macro ^TOP^

Purpose

Obtain the value of the AppInt32 attribute, an arbitrary 32-bit value that an application can attach to an SslLib.

Declared In

SslLibMac.h

Prototype

#define SslLibGet_AppInt32 (
   lib
)

Parameters

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

Returns

Returns the 32-bit value.

Comments

SslLibDestroy() does not modify this attribute, so if the data pointed to by this attribute needs to be disposed of, the application must do this itself.

See Also

"AppInt32," SslLibSet_AppInt32(), SslContextGet_AppInt32()

SslLibGet_AppPtr Macro ^TOP^

Purpose

Obtain the value of the AppPtr attribute, an arbitrary pointer value that an application can attach to an SslLib.

Declared In

SslLibMac.h

Prototype

#define SslLibGet_AppPtr (
   lib,
    v
)

Parameters

lib
The SslLib from which the value is to be retrieved.
v
The address of a pointer variable into which the AppPtr attribute value is written.

Returns

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

Comments

SslLibDestroy() does not modify this attribute, so if the data pointed to by this attribute needs to be disposed of, the application must do this itself.

See Also

"AppPtr," SslLibSet_AppPtr(), SslContextGet_AppPtr()

SslLibGet_AutoFlush Macro ^TOP^

Purpose

Determine whether SslSend() and SslWrite() attempt to immediately send the supplied data bytes to the network.

Declared In

SslLibMac.h

Prototype

#define SslLibGet_AutoFlush (
   lib
)

Parameters

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

Returns

Returns 0 if data is buffered, or 1 if the data is sent immediately.

Comments

It is very important to remember to use SslFlush() when AutoFlush is disabled.

See Also

"AutoFlush," SslLibSet_AutoFlush(), SslContextGet_AutoFlush()

SslLibGet_BufferedReuse Macro ^TOP^

Purpose

Determine if the last message in an SslSession-reused handshake should be buffered instead of being sent over the network.

Declared In

SslLibMac.h

Prototype

#define SslLibGet_BufferedReuse (
   lib
)

Parameters

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

Returns

Returns 0 if the last message is not buffered, or a non-zero value if it is.

See Also

"BufferedReuse," SslLibSet_BufferedReuse(), SslContextGet_BufferedReuse()

SslLibGet_CipherSuites Macro ^TOP^

Purpose

Obtain the list of cipher suites that the SSL protocol is attempting to use. This list is inherited from the SslLib when an SslContext is created.

Declared In

SslLibMac.h

Prototype

#define SslLibGet_CipherSuites (
   lib,
    v
)

Parameters

lib
The SslLib from which the value is to be retrieved.
v
Supply the address of a pointer variable; upon return the pointer variable will point to a series of bytes, where the first two bytes indicate the number of bytes that follow, and each pair of bytes after that is one of the values listed under "Cipher Suites." See "CipherSuites" for more details on this attribute.

Returns

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

See Also

"CipherSuites", SslLibSet_CipherSuites(), SslContextGet_CipherSuites()

SslLibGet_Compat Macro ^TOP^

Purpose

Determine which SSL protocol compatibility flags are set. These flags enable compatibility with certain incorrect SSL protocol implementations.

Declared In

SslLibMac.h

Prototype

#define SslLibGet_Compat (
   lib
)

Parameters

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

Returns

Returns a 32-bit integer value that is the logical OR of those compatibility flags that have been set. See "Compatibility Flags" for the defined constants that correspond to the compatibility flags.

See Also

"Compat," SslLibSet_Compat(), SslContextGet_Compat()

SslLibGet_DelayReadServerFinished Macro ^TOP^

Purpose

Declared In

SslLibMac.h

Prototype

#define SslLibGet_DelayReadServerFinished (
   lib
)

Parameters

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

Returns

SslLibGet_DontSendShutdown Macro ^TOP^

Purpose

Determine whether or not an SslClose() will send a shutdown message to the server.

Declared In

SslLibMac.h

Prototype

#define SslLibGet_DontSendShutdown (
   lib
)

Parameters

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

Returns

Returns zero if SslClose() does send a shutdown message to the server, or a non-zero value if it doesn't.

See Also

"DontSendShutdown," SslLibSet_DontSendShutdown(), SslContextGet_DontSendShutdown(), SslLibGet_DontWaitForShutdown()

SslLibGet_DontWaitForShutdown Macro ^TOP^

Purpose

Determine whether or not the SslLib will wait for a shutdown message in SslClose().

Declared In

SslLibMac.h

Prototype

#define SslLibGet_DontWaitForShutdown (
   lib
)

Parameters

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

Returns

Returns zero if the SslLib waits for a shutdown message, or a non-zero value if it doesn't.

See Also

"DontWaitForShutdown," SslContextGet_DontWaitForShutdown(), SslLibGet_DontSendShutdown(), SslLibSet_DontWaitForShutdown()

SslLibGet_HelloVersion Macro ^TOP^

Purpose

Declared In

SslLibMac.h

Prototype

#define SslLibGet_HelloVersion (
   lib
)

Parameters

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

Returns

SslLibGet_InfoCallback Macro ^TOP^

Purpose

Obtain a pointer to the callback function called when various situations occur during the usage of an SslLib. This callback is primarily intended for debugging and feedback purposes.

Declared In

SslLibMac.h

Prototype

#define SslLibGet_InfoCallback (
   lib,
    v
)

Parameters

lib
The SslLib from which the value is to be retrieved.
v
Pass the address of a pointer variable; upon return this variable will point to the callback function. The callback function is of type SslCallbackFunc().

Returns

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

Comments

See "InfoCallback" and SslCallbackFunc() (documented) for more on how this callback function is used.

See Also

"InfoCallback," SslLibSet_InfoCallback(), SslContextGet_InfoCallback()

SslLibGet_InfoInterest Macro ^TOP^

Purpose

Obtain the flags that specify the events for which the Info callback will be called.

Declared In

SslLibMac.h

Prototype

#define SslLibGet_InfoInterest (
   lib
)

Parameters

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

Returns

The logical OR of the sslFlgInfoxxx values listed under "InfoInterest Values."

See Also

"InfoInterest," SslLibSet_InfoInterest(), SslContextGet_InfoInterest()

SslLibGet_Mode Macro ^TOP^

Purpose

Obtain the value of the Mode attribute, which controls whether the SSL protocol is on or off.

Declared In

SslLibMac.h

Prototype

#define SslLibGet_Mode (
   lib
)

Parameters

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

Returns

Returns one of the values listed under "Mode Attribute Values."

See Also

"Mode," SslLibSet_Mode(), SslContextGet_Mode()

SslLibGet_ProtocolSupport Macro ^TOP^

Purpose

Determine which variants of the SSL protocol the library supports.

Declared In

SslLibMac.h

Prototype

#define SslLibGet_ProtocolSupport (
   lib
)

Parameters

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

Returns

One or more of the values listed under "Protocol Variants," OR'd together.

See Also

SslContextGet_ProtocolSupport(), SslLibGet_ProtocolVersion(), SslLibSet_ProtocolSupport()

SslLibGet_ProtocolVersion Macro ^TOP^

Purpose

Determine which version of the SSL protocol is being used.

Declared In

SslLibMac.h

Prototype

#define SslLibGet_ProtocolVersion (
   lib
)

Parameters

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

Returns

One of the values listed under "Protocol Versions."

See Also

"ProtocolVersion," SslLibSet_ProtocolVersion(), SslContextGet_ProtocolVersion()

SslLibGet_RbufSize Macro ^TOP^

Purpose

Obtain the size, in bytes, of the read buffer. Read and write buffers are associated with an SslContext; SslContexts created against this SslLib will inherit the SslLib's buffer values.

Declared In

SslLibMac.h

Prototype

#define SslLibGet_RbufSize (
   lib
)

Parameters

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

Returns

The read buffer size. This is a value that ranges from 0 to 16384.

See Also

"RbufSize," SslLibSet_RbufSize(), SslContextGet_RbufSize()

SslLibGet_ReadStreaming Macro ^TOP^

Purpose

Determine whether data can be returned to the application from the SSL connection before the full record has been downloaded.

Declared In

SslLibMac.h

Prototype

#define SslLibGet_ReadStreaming (
   lib
)

Parameters

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

Returns

Returns a zero value if data is only returned when the full record has been downloaded, or a non-zero value otherwise.

See Also

"ReadStreaming," SslContextGet_ReadStreaming(), SslLibSet_ReadStreaming()

SslLibGet_VerifyCallback Macro ^TOP^

Purpose

Obtain a pointer to the callback function used to assist with certificate verification.

Declared In

SslLibMac.h

Prototype

#define SslLibGet_VerifyCallback (
   lib,
    v
)

Parameters

lib
The SslLib from which the value is to be retrieved.
v
Pass the address of a pointer variable; upon return this variable will point to the callback function. The callback function is of type SslCallbackFunc().

Returns

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

Comments

See "VerifyCallback" and SslCallbackFunc() (documented) for more on how this callback function is used to verify a certificate.

See Also

"VerifyCallback," SslLibSet_VerifyCallback(), SslContextGet_VerifyCallback()

SslLibGet_WbufSize Macro ^TOP^

Purpose

Obtain the size, in bytes, of the write buffer. Read and write buffers are associated with an SslContext; SslContexts created against this SslLib will inherit the SslLib's buffer values.

Declared In

SslLibMac.h

Prototype

#define SslLibGet_WbufSize (
   lib
)

Parameters

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

Returns

The write buffer size. This is a value that ranges from 0 to 16384.

See Also

"WbufSize," SslLibSet_WbufSize(), SslContextGet_WbufSize()

SslLibSet_AppInt32 Macro ^TOP^

Purpose

Set the value of the AppInt32 attribute, an arbitrary 32-bit value that an application can attach to an SslLib.

Declared In

SslLibMac.h

Prototype

#define SslLibSet_AppInt32 (
   lib,
    v
)

Parameters

lib
The SslLib on which to operate.
v
The 32-bit value.

Returns

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

Comments

SslLibDestroy() does not modify this attribute, so if the data pointed to by this attribute needs to be disposed of, the application must do this itself.

See Also

"AppInt32," SslLibGet_AppInt32(), SslContextSet_AppInt32()

SslLibSet_AppPtr Macro ^TOP^

Purpose

Set the value of the AppPtr attribute, an arbitrary pointer value that an application can attach to an SslLib.

Declared In

SslLibMac.h

Prototype

#define SslLibSet_AppPtr (
   lib,
    v
)

Parameters

lib
The SslLib on which to operate.
v
The AppPtr attribute value.

Returns

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

Comments

SslLibDestroy() does not modify this attribute, so if the data pointed to by this attribute needs to be disposed of, the application must do this itself.

See Also

"AppPtr," SslLibGet_AppPtr(), SslContextSet_AppPtr()

SslLibSet_AutoFlush Macro ^TOP^

Purpose

Specify whether SslSend() and SslWrite() should attempt to immediately send the supplied data bytes to the network.

Declared In

SslLibMac.h

Prototype

#define SslLibSet_AutoFlush (
   lib,
    v
)

Parameters

lib
The SslLib on which to operate.
v
Pass 0 to have the data buffered, or 1 to have the data sent immediately.

Returns

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

Comments

It is very important to remember to use SslFlush() when AutoFlush is disabled.

See Also

"AutoFlush," SslContextGet_AutoFlush(), SslLibSet_AutoFlush()

SslLibSet_BufferedReuse Macro ^TOP^

Purpose

Specify whether the last message in an SslSession-reused handshake should be buffered instead of being sent over the network.

Declared In

SslLibMac.h

Prototype

#define SslLibSet_BufferedReuse (
   lib,
    v
)

Parameters

lib
The SslLib on which to operate.
v
Supply a value of 0 if the last message should not be buffered, or a non-zero value if it should.

Returns

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

See Also

"BufferedReuse," SslLibGet_BufferedReuse(), SslContextSet_BufferedReuse()

SslLibSet_CipherSuites Macro ^TOP^

Purpose

Specify the list of cipher suites that the SSL protocol should attempt to use. When an SslContext is created, it inherits this list of cipher suites.

Declared In

SslLibMac.h

Prototype

#define SslLibSet_CipherSuites (
   lib,
    v
)

Parameters

lib
The SslLib on which to operate.
v
Pointer to an array of byte pairs. The first two bytes contain the number of bytes that follow, and each successive pair is one of the values listed under "Cipher Suites."

Returns

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

See Also

"CipherSuites", SslLibGet_CipherSuites(), SslContextSet_CipherSuites()

SslLibSet_Compat Macro ^TOP^

Purpose

Determine how compatible the SSL protocol should be with certain incorrect SSL protocol implementations.

Declared In

SslLibMac.h

Prototype

#define SslLibSet_Compat (
   lib,
    v
)

Parameters

lib
The SslLib on which to operate.
v
The logical OR of those compatibility flags that correspond to the SSL protocol incompatibilities that should be accommodated. See "Compatibility Flags" for the defined constants that correspond to the compatibility flags.

Returns

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

See Also

"Compat," SslLibGet_Compat(), SslContextSet_Compat()

SslLibSet_DelayReadServerFinished Macro ^TOP^

Purpose

Declared In

SslLibMac.h

Prototype

#define SslLibSet_DelayReadServerFinished (
   lib,
    v
)

Parameters

lib
The SslLib on which to operate.
v

Returns

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

SslLibSet_DontSendShutdown Macro ^TOP^

Purpose

Specify whether or not an SslClose() should send a shutdown message to the server.

Declared In

SslLibMac.h

Prototype

#define SslLibSet_DontSendShutdown (
   lib,
    v
)

Parameters

lib
The SslLib on which to operate.
v
Zero if SslClose() should send a shutdown message, or a non-zero value if it shouldn't.

Returns

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

See Also

"DontSendShutdown," SslLibGet_DontSendShutdown(), SslContextSet_DontSendShutdown(), SslLibSet_DontWaitForShutdown()

SslLibSet_DontWaitForShutdown Macro ^TOP^

Purpose

Specify whether or not the SSlLib should wait for a shutdown message in SslClose().

Declared In

SslLibMac.h

Prototype

#define SslLibSet_DontWaitForShutdown (
   lib,
    v
)

Parameters

lib
The SslLib on which to operate.
v
Zero if the SslLib waits for a shutdown message, or a non-zero value if it doesn't.

Returns

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

See Also

"DontWaitForShutdown," SslLibGet_DontWaitForShutdown(), SslLibSet_DontSendShutdown(), SslContextSet_DontWaitForShutdown()

SslLibSet_HelloVersion Macro ^TOP^

Purpose

Declared In

SslLibMac.h

Prototype

#define SslLibSet_HelloVersion (
   lib,
    v
)

Parameters

lib
The SslLib on which to operate.
v

Returns

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

SslLibSet_InfoCallback Macro ^TOP^

Purpose

Specify the callback function called when various situations occur during the usage of an SslLib. This callback is primarily intended for debugging and feedback purposes.

Declared In

SslLibMac.h

Prototype

#define SslLibSet_InfoCallback (
   lib,
    v
)

Parameters

lib
The SslLib on which to operate.
v
A pointer to a callback function of type SslCallbackFunc().

Returns

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

Comments

See "InfoCallback" and SslCallbackFunc() (documented) for more on how this callback function is used.

See Also

"InfoCallback," SslLibGet_InfoCallback(), SslContextSet_InfoCallback()

SslLibSet_InfoInterest Macro ^TOP^

Purpose

Specify the events for which the Info callback will be called.

Declared In

SslLibMac.h

Prototype

#define SslLibSet_InfoInterest (
   lib,
    v
)

Parameters

lib
The SslLib on which to operate.
v
The logical OR of the sslFlgInfoxxx values listed under "InfoInterest Values."

Returns

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

See Also

"InfoInterest," SslLibGet_InfoInterest(), SslContextSet_InfoInterest()

SslLibSet_Mode Macro ^TOP^

Purpose

Specify the value of the Mode attribute, which controls whether the SSL protocol is on or off.

Declared In

SslLibMac.h

Prototype

#define SslLibSet_Mode (
   lib,
    v
)

Parameters

lib
The SslLib on which to operate.
v
One of the values listed under "Mode Attribute Values."

Returns

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

See Also

"Mode," SslLibGet_Mode(), SslContextSet_Mode()

SslLibSet_ProtocolSupport Macro ^TOP^

Purpose

Sets the protocol variants supported by the library.

Declared In

SslLibMac.h

Prototype

#define SslLibSet_ProtocolSupport (
   lib,
    v
)

Parameters

lib
The SslLib on which to operate.
v
One or more of the values listed under "Protocol Variants," OR'd together.

Returns

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

Comments

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


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.

See Also

SslContextSet_ProtocolSupport(), SslLibGet_ProtocolSupport(), SslLibSet_ProtocolVersion()

SslLibSet_ProtocolVersion Macro ^TOP^

Purpose

Specify the version of the SSL protocol to use.

Declared In

SslLibMac.h

Prototype

#define SslLibSet_ProtocolVersion (
   lib,
    v
)

Parameters

lib
The SslLib on which to operate.
v
One of the values listed under "Protocol Versions."

Returns

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

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 has no effect—SslLib continues to send a TLSv1 ClientHello message.

See Also

"ProtocolVersion," SslLibGet_ProtocolVersion(), SslContextSet_ProtocolVersion()

SslLibSet_RbufSize Macro ^TOP^

Purpose

Specify the size, in bytes, of the read buffer. Read and write buffers are associated with an SslContext; SslContexts created against this SslLib will inherit the SslLib's buffer values.

Declared In

SslLibMac.h

Prototype

#define SslLibSet_RbufSize (
   lib,
    v
)

Parameters

lib
The SslLib on which to operate.
v
The read buffer size. This is a value that ranges from 0 to 16384.

Returns

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

See Also

"RbufSize," SslLibGet_RbufSize(), SslContextSet_RbufSize()

SslLibSet_ReadStreaming Macro ^TOP^

Purpose

Specify whether data can be returned to the application from the SSL connection before the full record has been downloaded.

Declared In

SslLibMac.h

Prototype

#define SslLibSet_ReadStreaming (
   lib,
    v
)

Parameters

lib
The SslLib on which to operate.
v
A zero value if data is only to be returned when the full record has been downloaded, or a non-zero value otherwise.

Returns

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

See Also

"ReadStreaming," SslContextSet_ReadStreaming(), SslLibGet_ReadStreaming()

SslLibSet_VerifyCallback Macro ^TOP^

Purpose

Specify the callback function to assist with certificate verification.

Declared In

SslLibMac.h

Prototype

#define SslLibSet_VerifyCallback (
   lib,
    v
)

Parameters

lib
The SslLib on which to operate.
v
A pointer to a callback function of type SslCallbackFunc().

Returns

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

Comments

See "VerifyCallback" and SslCallbackFunc() (documented) for more on how this callback function is used to verify a certificate.

See Also

"VerifyCallback," SslLibGet_VerifyCallback(), SslContextSet_VerifyCallback()

SslLibSet_WbufSize Macro ^TOP^

Purpose

Specify the size, in bytes, of the write buffer. Read and write buffers are associated with an SslContext; SslContexts created against this SslLib will inherit the SslLib's buffer values.

Declared In

SslLibMac.h

Prototype

#define SslLibSet_WbufSize (
   lib,
    v
)

Parameters

lib
The SslLib on which to operate.
v
The write buffer size. This is a value that ranges from 0 to 16384.

Returns

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

See Also

"WbufSize," SslLibGet_WbufSize(), SslContextSet_WbufSize()