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
SslAttribute Typedef
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
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 toNULL
.
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
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 thecipherKeyLength
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 theauthenticationLength
. -
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
Purpose
An opaque data structure that represents an SSL connection.
Declared In
SslLib.h
Prototype
typedef struct SslContext_st SslContext
Fields
SslIoBuf Struct
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'sssl
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, butmax
bytes could be read if they are available. Often the read operation will read more bytes than are needed, so theoutNum
field which returns the number of bytes read or written, can, for the read case, be larger thaninNum
. -
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
Purpose
An opaque data structure that represents the SSL library.
Declared In
SslLib.h
Prototype
typedef struct SslLib_st SslLib
Fields
SslSession Struct
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
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
SSL Open Mode Flags
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 asSslContextSet_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
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
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
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
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
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
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 theargv
parameter. Theargi
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
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
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
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
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 aNULL
value for theargv
parameter. The application can get theLastAlert
attribute from theSslContext
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. Theargv
parameter is aSslExtendedItems
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. Theargv
parameter will beNULL
, but theHsState
attribute can be interrogated to read the current state. -
#define sslArgInfoReadAfter (sslCmdRead | 0x8000)
- Notification after a
recvfrom()
,recv()
, orread()
sys/socket
call. See the Comments section, below, for more information. -
#define sslArgInfoReadBefore sslCmdRead
- Notification before a
recvfrom()
,recv()
, orread()
sys/socket
call. See the Comments section, below, for more information. -
#define sslArgInfoWriteAfter (sslCmdWrite | 0x8000)
- Notification after a
sendto()
,send()
, orwrite()
sys/socket
call. See the Comments section, below, for more information. -
#define sslArgInfoWriteBefore sslCmdWrite
- Notification before a
sendto()
,send()
, orwrite()
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
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
, andsslArgInfoWriteBefore
callbacks.
LastApi Attribute Values
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()
orSslReceive()
was last called. -
#define sslLastApiShutdown 0x05
-
#define sslLastApiWrite 0x03
- Set if
SslWrite()
orSslSend()
was last called.
LastIO Attribute Values
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
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
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 0x01
XX, while fatal Alerts have the form 0x02
XX. SslLib will fail on fatal alerts and continue on non-fatal alerts.
SSL Library Errors
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 beenNULL
. -
#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
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
SslClose Function
Purpose
Performs the shutdown part of the SSL protocol.
Declared In
SslLib.h
Prototype
status_t SslClose ( SslContext*ctx
, uint16_tmode
, uint32_ttimeout
)
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
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_tnumber
)
Parameters
-
→ ctx
- The SslContext to operate on.
-
→ number
- The number of bytes to remove from the internal buffer.
Returns
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
Purpose
Declared In
SslLib.h
Prototype
status_t SslContextCreate ( SslLib*lib
, SslContext**ctx
)
Parameters
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
Purpose
Declared In
SslLib.h
Prototype
void SslContextDestroy (
SslContext *ctx
)
Parameters
Returns
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
Purpose
Retrieve an integer attribute value from the passed SslContext structure.
Declared In
SslLib.h
Prototype
int32_t SslContextGetLong ( SslContext*lib
, SslAttributeattr
)
Parameters
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
Purpose
Retrieve a pointer to an attribute value from the passed SslContext structure.
Declared In
SslLib.h
Prototype
status_t SslContextGetPtr ( SslContext*lib
, SslAttributeattr
, 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
Purpose
Modify one of the numeric attributes of a SslContext structure.
Declared In
SslLib.h
Prototype
status_t SslContextSetLong ( SslContext*lib
, SslAttributeattr
, longvalue
)
Parameters
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
Purpose
Update one of the non-integer attributes of a SslContext.
Declared In
SslLib.h
Prototype
status_t SslContextSetPtr ( SslContext*lib
, SslAttributeattr
, 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
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
Purpose
SSL library's shared library close function.
Declared In
SslLib.h
Prototype
status_t SslLibClose ( void )
Parameters
Returns
SslLibCreate Function
Purpose
Creates the SSL library context.
Declared In
SslLib.h
Prototype
status_t SslLibCreate (
SslLib **lib
)
Parameters
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
Purpose
Destroys the context represented by lib
.
Declared In
SslLib.h
Prototype
void SslLibDestroy (
SslLib *lib
)
Parameters
Returns
See Also
SslLibGetLong Function
Purpose
Retrieve an integer attribute value from the passed SslLib structure.
Declared In
SslLib.h
Prototype
int32_t SslLibGetLong ( SslLib*lib
, SslAttributeattr
)
Parameters
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
Purpose
Retrieve an pointer attribute value from the passed SslLib structure.
Declared In
SslLib.h
Prototype
status_t SslLibGetPtr ( SslLib*lib
, SslAttributeattr
, 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
Purpose
Declared In
SslLib.h
Prototype
status_t SslLibName ( void )
Parameters
Returns
SslLibOpen Function
Purpose
SSL library's shared library open function.
Declared In
SslLib.h
Prototype
status_t SslLibOpen ( void )
Parameters
Returns
SslLibSetLong Function
Purpose
Modify one of the numeric attributes of a SslLib structure.
Declared In
SslLib.h
Prototype
status_t SslLibSetLong ( SslLib*lib
, SslAttributeattr
, int32_tvalue
)
Parameters
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
Purpose
Update one of the non-integer attributes of a SslLib.
Declared In
SslLib.h
Prototype
status_t SslLibSetPtr ( SslLib*lib
, SslAttributeattr
, 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
Purpose
SSL library's shared library sleep function.
Declared In
SslLib.h
Prototype
status_t SslLibSleep ( void )
Parameters
Returns
SslLibWake Function
Purpose
SSL library's shared library wake function.
Declared In
SslLib.h
Prototype
status_t SslLibWake ( void )
Parameters
Returns
SslOpen Function
Purpose
Initializes the passed SslContext.
Declared In
SslLib.h
Prototype
status_t SslOpen ( SslContext*ctx
, uint16_tmode
, uint32_ttimeout
)
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
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_treadSize
)
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
SslRead Function
Purpose
Declared In
SslLib.h
Prototype
int32_t SslRead ( SslContext*ctx
, void*buffer
, int32_tbufferLen
, 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
SslReceive Function
Purpose
Declared In
SslLib.h
Prototype
int16_t SslReceive ( SslContext*ctx
, void*buffer
, uint16_tbufferLen
, uint16_tflags
, void*fromAddr
, uint16_t*fromLen
, int32_ttimeout
, 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 insys/socket.h
). -
← fromAddr
- Buffer to hold address of sender (
sockaddr
). -
↔ fromLen
- On entry, size of
fromAddr
buffer. On exit, actual size of returned address infromAddr
buffer -
→ timeout
- Max timeout in system ticks. -1 means wait forever.
-
← 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
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
Purpose
Declared In
SslLib.h
Prototype
int16_t SslSend ( SslContext*ctx
, const void*buffer
, uint16_tbufferLen
, uint16_tflags
, void*toAddr
, uint16_ttoLen
, int32_ttimeout
, 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 insys/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.
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
Purpose
Declared In
SslLib.h
Prototype
int32_t SslWrite ( SslContext*ctx
, const void*buffer
, int32_tbufferLen
, 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
Application-Defined Functions
SslCallbackFunc Function
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_tcommand
, int32_targi
, 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
andargv
. -
→ 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 theargi
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:
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:
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.
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:
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.
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); }