(68K) SSL Library | Palm OS® Programmer's API Reference

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 and Macros

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 8, "Secure Sockets Layer (SSL)," of Palm OS Programmer's Companion, vol. II, Communications. 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 87, "SSL Library Macros."

SSL Library Structures and Types ^TOP^

SslAttribute Typedef ^TOP^

Purpose

Container for an SslLib or SslContext attribute value.

Declared In

SslLib.h

Prototype

typedef UInt32 SslAttribute;

Comments

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

SslCallback Struct ^TOP^

Purpose

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

Declared In

SslLib.h

Prototype

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

typedef struct SslCallback_st SslCallback

Fields

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

Comments

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

SslCipherSuiteInfo Struct ^TOP^

Purpose

Encapsulates information about the current cipher suite.

Declared In

SslLib.h

Prototype

typedef struct SslCipherSuiteInfo_st {
   UInt8 cipherSuite[2];
   UInt16 cipher;
   UInt16 digest;
   UInt16 keyExchange;
   UInt16 authentication;
   UInt16 version;
   UInt16 cipherBitLength;
   UInt16 cipherKeyLength;
   UInt16 keyExchangeLength;
   UInt16 authenticationLength;
   UInt16 export;
} SslCipherSuiteInfo

Fields

cipherSuite: The two bye cipher suite value for the current cipher suite. See the CipherSuite attribute description in the Palm OS Programmer's Companion, vol. II, Communications 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 authenticaiton type used. One of the sslCsiAuth... constants listed under "Cipher Suite Info Constants."
version: The SSL version being used.
cipherBitLength: The number of bits of key material used for encryption key generation. For export ciphers this will be either 40 or 56 bits.
cipherKeyLength: The length of the key for the underlying cipher. For an export RC4 cipher, the cipherBitLength would be 40, but the cipherKeyLength would be 128. This is because while the SSL protocol would be using 128-bit keys to encrypt and decrypt with RC4, only 40 bits of random data would be used to generate the 128-bit key.
keyExchangeLength: The length in bits of the public key used to establish a shared secret.
authenticationLength: The length of the public key used to ensure the key exchange was not tampered with. For export ciphers, the keyExchangeLength is often shorter than the authenticationLength.
export: Set when an export cipher is being used.

Comments

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

SslContext Struct ^TOP^

Purpose

An opaque data structure that represents an SSL connection.

Declared In

SslLib.h

Prototype

typedef struct SslContext_st SslContext

Fields

None.

SslExtendedItem Struct ^TOP^

Purpose

Structure that's used to describe a single certificate-related item.

Declared In

SslLib.h

Prototype

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

Fields

type: The extended item type, one of:
field: Type-specific value.
dataType: The encoding for the item's data. For the SSL library, the value is one of the ASN.1 encoding types, as listed in SslLibAsn1.h. The encoding is relevant if you're trying to display the data bytes.
len: Number of data bytes.
offset: Location of the data itself, as an offset in bytes from the beginning of the SslExtendedItems structure that contains this SslExtendedItem.

Comments

Every SslExtendedItem has a distinct (pre-defined) "extended item type." The location of the item's data is indicated by the structure—the data isn't stored in the structure.

You never create SslExtendedItem structures yourself. The objects that relate to a particular certificate are collected into an SslExtendedItems structure and returned to you (principally) by your verify callback function.

SslExtendedItems Struct ^TOP^

Purpose

Structure that contains a set of related data items that pertain to an SSL certificate or other cryptographic entity.

Declared In

SslLib.h

Prototype

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

Fields

length: Total length of the structure, in bytes.
num: Number of elements in the eitem array.
eitem: Individual data items (these are the "related data items" mentioned above). The array contains num elements.

Comments

The SslExtendedItems structure is used as part of the SslVerify structure, and is used as the type of the PeerCert attribute.

The SslExtendedItems structure is used by the SSL library to return information to your application; you never create and populate an SslExtendedItems structure yourself.

The items in the eitem array needn't all be the same "extended item type" (as defined in SslExtendedItem). For example, the SslExtendedItems structure for a certificate typically contains an sslExItemTypeX509 item, an sslExItemTypeRSA, and an sslExItemType (for the subject name).

SslIoBuf Struct ^TOP^

Purpose

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

Declared In

SslLib.h

Prototype

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

Fields

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

Comments

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

SslLib Struct ^TOP^

Purpose

An opaque data structure that represents the SSL Library (similar to "NetLib").

Declared In

SslLib.h

Prototype

typedef struct SslLib_st SslLib

Fields

None.

SslSession Struct ^TOP^

Purpose

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

Declared In

SslLib.h

Prototype

typedef struct SslSession_st {
   UInt32 length;
   UInt16 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 certificateOffset;
   UInt16 extraData;
} SslSession

Fields

length: The total size of the structure, in bytes.
version: Version number of the SSL protocol that's being used; 0 if the session is using cleartext.
cipherSuite: Cipher suite that's being used. See the CipherSuite attribute description in Palm OS Programmer's Companion, vol. II, Communications.
compression: The name of the compression scheme that's being used.
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 hostname of peer. Application defined.

Comments

A context's SslSession is populated when you call SslOpen(). You can retrieve a context's SslSession structure and modify it directly—particularly if you want to set the fields that are reserved for application use. To retrieve the SslSession, call the SslContextGet_SslSession macro. Keep in mind that this gives you a pointer to the context's internal SslSession attribute. If you want to store the SslSession, you must copy the attribute's data.

SslSocket Struct ^TOP^

Purpose

The structure used to hold the Net Library arguments to be passed to any Net Library calls.

Declared In

SslLib.h

Prototype

typedef struct SslSocket_st {
   NetSocketRef socket;
   UInt16 flags;
   UInt16 addrLen;
   Err err;
   Int32 timeout;
   NetSocketAddrType addr;
} SslSocket

Fields

socket: Socket identifier, as created and returned by NetLibSocketOpen(). The SSL library doesn't open or connect the socket for you; all socket operations other than reading and writing data must be done through net library calls. Note that you never set the socket field directly; use the SslContextSet_Socket macro instead.
flags: Options that control a socket's I/O operations. See "I/O Flags" for a description of these options.
addrLen: The length, in bytes, of the addr field.
err: The most recent socket error.
timeout: The socket's I/O operation timeout value, in system ticks.
addr: The most recent address that the socket read from or wrote to.

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, timeout, and addr fields all correspond to the arguments passed to NetLibSend() and NetLibReceive(). Read further on those function 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.

SslVerify Struct ^TOP^

Purpose

Structure that's passed to a verify callback function to provide information about a certificate that's being verified. This happens when the verification process hits a snag, giving your app a chance to the handle the problem. The callback is also invoked when the process has successfully completed.

Declared In

SslLib.h

Prototype

typedef struct SslVerify_st {
   SslExtendedItems *certificate;
   SslExtendedItems *fieldItems;
   UInt32 field;
   SslExtendedItems *ex;
   UInt32 depth;
   UInt32 state;
} SslVerify

Fields

certificate: Points to the certificate that's being verified.
fieldItems: An array of extended items. The SslExtendedItems that's located at fieldItems[field] contains the set of items that's causing the problem.
field: An index into fieldItems.
ex: If this is an extension error, the ex field contains the data element of the X509 extension that failed.
depth: This is the level of the certificate being processed, where 0 is the server's certificate, and higher numbers are certificates along the "certificate chain" that leads to a trusted root certificate.
state: The verification state.

Comments

The list of SslExtendedItem elements that the SslExtendedItems object located at fieldItems[ field ] contains depends on the verification error:

Flavor	Contents
`sslErrVerifyBadSignature`	The server's certificate, which contains the public key entries.
`sslErrVerifyNoTrustedRoot`	`NULL`
`sslErrVerifyNotAfter`	`sslExItemTypeX509`, `asn1FldX509NotAfter`
`sslErrVerifyNotBefore`	`sslExItemTypeX509`, `asn1FldX509NotBefore`.
`sslErrVerifyConstraintViolation`	`asn1ExItemTypeX509Ex` (but see below)
`sslErrVerifyUnknownCriticalExtension`	`asn1ExItemTypeX509Ex` (but see below)
`sslErrOk`	`NULL`

The asn1ExItemTypeX509Ex item needs to be decoded in order to be used. The item contains the "object identifier" part of a certificate extension. The item in the next field (i.e. fieldItems[ field+1 ]) depends on the item's dataType field: If it's asn1Boolean, than the "+1" item contains the extension's optional Boolean "this is a critical extension" field, otherwise it contains the extension data itself. If "+1" contains the Boolean, than "+2" is the data.

The SSL library attempts to interpret only critical extensions, so the critical field should always be present. If a critical extension isn't understood, the certificate should be rejected.

SSL Library Constants ^TOP^

SSL Open Mode Flags ^TOP^

Purpose

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

Declared In

SslLib.h

Constants

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

SSL Close Mode Flags ^TOP^

Purpose

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

Declared In

SslLib.h

Constants

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

Mode Attribute Values ^TOP^

Purpose

Values that control the SslContext's operating mode.

Declared In

SslLib.h

Constants

#define sslModeClear 0x0000: Causes the SSL protocol to be bypassed.
#define sslModeFlush 0x8000: Causes any data in the internal data buffers to be cleared.
#define sslModeSsl 0x0002: A subset value of sslModeSslClient
#define sslModeSslClient 0x000A: SSL is turned on, with this endpoint a client.

Comments

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

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

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

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

Protocol Versions ^TOP^

Purpose

The version of the SSL protocol to use.

Declared In

SslLib.h

Constants

#define sslVersionSSLv3 0x0300: Version SSLv3 of the SSL protocol.

Comments

SslLib implements only SSLv3 at this point in time, so modification of this value is not a good idea.

Compatibility Flags ^TOP^

Purpose

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

Declared In

SslLib.h

Constants

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

Comments

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

SSL Callback Commands ^TOP^

Purpose

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

Declared In

SslLib.h

Constants

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

Cipher Suite Info Constants ^TOP^

Purpose

Constants used with various fields of the SslCipherSuiteInfo structure.

Declared In

SslLib.h

Constants

#define sslCsiAuthNULL 0x00: (authentication field) No key exchange.
#define sslCsiAuthRsa 0x01: (authentication field) RSA.
#define sslCsiCipherNull 0x00: (cipher field) No cipher is being used for this connection.
#define sslCsiCipherRc4 0x01: (cipher field) The RSA RC4 cipher is being used for this connection.
#define sslCsiDigestMd2 0x03: (digest field) Rivest Message Digest 2.
#define sslCsiDigestMd5 0x01: (digest field) Rivest Message Digest 5.
#define sslCsiDigestNull 0x00: (digest field) No message digest.
#define sslCsiDigestSha1 0x02: (digest field) Secure Hash Algorithm-1.
#define sslCsiKeyExchNull 0x00: (keyExchange field) No key exchange is being used.
#define sslCsiKeyExchRsa 0x01: (keyExchange field) RSA key exchange.

Cipher Suites ^TOP^

Purpose

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

Declared In

SslLib.h

Constants

#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().

Info Callbacks ^TOP^

Purpose

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

Declared In

SslLib.h

Constants

#define sslArgInfoAlert 0x0002: Notification of an Alert in the SSL protocol. The sslArgInfoAlert notification is called with a NULL value for the argv parameter. The application can get the LastAlert attribute from the SslContext to determine which alert was received.
#define sslArgInfoCert 0x0003: Notification of peer certificate. The sslArgInfoCert call is made after the server's certificate chain has been verified. The argv parameter is a SslExtendedItems pointer, which points to the remote server's certificate.
#define sslArgInfoHandshake 0x0001: Notification of a state change in the SSL protocol. The sslArgInfoHandshake will be called upon each handshake state change. The argv parameter will be NULL, but the HsState attribute can be interrogated to read the current state.
#define sslArgInfoReadAfter (sslCmdRead | 0x8000): Notification after a Receive/Read Net Library call. See the Comments section, below, for more information.
#define sslArgInfoReadBefore sslCmdRead: Notification before a Receive/Read Net Library call. See the Comments section, below, for more information.
#define sslArgInfoWriteAfter (sslCmdWrite | 0x8000): Notification after a Send/Write Net Library call. See the Comments section, below, for more information.
#define sslArgInfoWriteBefore sslCmdWrite: Notification before a Send/Write Net Library 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 Net Library Send/Receive. The second is made after the call has completed. If the callback returns a non-zero value, this value will be returned by origional SslLib call the application made.

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

InfoInterest Values ^TOP^

Purpose

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

Declared In

SslLib.h

Constants

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

LastApi Attribute Values ^TOP^

Purpose

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

Declared In

SslLib.h

#define sslLastApiFlush 0x04: The previous function was SslFlush().
#define sslLastApiNone 0x00: No SSL library function call in this context since the last SSL reset.
#define sslLastApiOpen 0x01: The previous function was SslOpen().
#define sslLastApiRead 0x02: Set if SslRead(), SslPeek() or SslReceive() was last called.
#define sslLastApiShutdown 0x05: The previous function was SslClose().
#define sslLastApiWrite 0x03: Set if SslWrite() or SslSend() was last called.

LastIO Attribute Values ^TOP^

Purpose

The last network operation performed.

Declared In

SslLib.h

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

Comments

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

SSL Protocol States ^TOP^

Purpose

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

Declared In

SslLib.h

Constants

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

SSL Server Alerts ^TOP^

Purpose

Alert values received from the server.

Declared In

SslLib.h

Constants

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

Comments

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

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

Verification States ^TOP^

Purpose

These constants represent the possible values of the SslVerify structure's state field. They indicate which section of the certificate verification failed.

Declared In

SslLib.h

Constants

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

SSL Library Errors ^TOP^

Purpose

Error codes returned by the various SSL Library functions.

Declared In

SslLib.h

Constants

#define sslErrBadArgument (sslErrorClass+17): An invalid argument was provided to the function.
#define sslErrBadDecode (sslErrorClass+9): An error occurred while decoding values during certificate verification.
#define sslErrBadLength (sslErrorClass+13): A length argument was invalid.
#define sslErrBadOption (sslErrorClass+18): An invalid argument was provided to the function.
#define sslErrBadPeerFinished (sslErrorClass+46): The final check of the SSL handshake failed. This indicates that there was a problem establishing a shared secret value. It could be caused by the server using a certificate that does not match its private key.
#define sslErrBadSignature (sslErrorClass+47): An invalid signature was found on a ephemeral Cipher Suite message.
#define sslErrBufferTooSmall (sslErrorClass+11): A supplied buffer was not large enough for the output data.
#define sslErrCbAbort (sslErrorClass+4): This error code would be returned by an applications callback function to indicate a desire to exit. This error may not be fatal, depending on the callback that generated the error.
#define sslErrCert (sslErrorClass+39): A generic error occurred inside the SslLib certificate library.
#define sslErrCertDecodeError (sslErrorClass+51): The Servers certificate could not be decoded.
#define sslErrCsp (sslErrorClass+38): A generic error occurred inside the SslLib cryptographic library.
#define sslErrDivByZero (sslErrorClass+7): Something went wrong in the Maths 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 Net Library 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 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 Maths library. These error will normally only be generated by certificates which have invalid public keys.
#define sslErrNoRandom (sslErrorClass+16): A problem with the random number source.
#define sslErrNotFound (sslErrorClass+6): Returned on an internal SslLib search that did not find a valid entry. Consider this an internal SslLib error.
#define sslErrNotImplemented (sslErrorClass+19): An internal SslLib error.
#define sslErrNullArg (sslErrorClass+12): An passed argument was NULL that should not have been NULL.
#define sslErrOk (sslErrorClass+0): Not an error.
#define sslErrOutOfMemory (sslErrorClass+3): Returned if a dynamic memory allocation failed. This is normally considered a very bad error.
#define sslErrReadAppData (sslErrorClass+50): Application data was read by the SSL protocol when it was expecting handshake messages.
#define sslErrReallocStaticData (sslErrorClass+20): An internal SslLib error
#define sslErrRecordError (sslErrorClass+37): An invalid record was received in the SslContext.
#define sslErrUnexpectedRecord (sslErrorClass+49): A record of the wrong was received inside the SSL protocol .
#define sslErrUnsupportedCertType (sslErrorClass+52): The Servers certificate contains a public key we cannot decode.
#define sslErrUnsupportedSignatureType (sslErrorClass+53): We have been send a certificate with a signature type we do not recognize.
#define sslErrVerifyBadSignature (sslErrorClass+128)
#define sslErrVerifyCallback (sslErrorClass+134)
#define sslErrVerifyConstraintViolation (sslErrorClass+132)
#define sslErrVerifyNotAfter (sslErrorClass+130)
#define sslErrVerifyNotBefore (sslErrorClass+131)
#define sslErrVerifyNoTrustedRoot (sslErrorClass+129)
#define sslErrVerifyUnknownCriticalExtension (sslErrorClass+133)
#define sslErrWrongMessage (sslErrorClass+44): An invalid SSL message was received.

SSL Library Traps ^TOP^

Purpose

These constants are used by the trap mechanism to call the various functions in the SSL library.

Declared In

SslLib.h

Constants

#define kSslClose (sysLibTrapCustom+13)
#define kSslConsume (sysLibTrapCustom+19)
#define kSslContextCreate (sysLibTrapCustom+6)
#define kSslContextDestroy (sysLibTrapCustom+7)
#define kSslContextGetLong (sysLibTrapCustom+8)
#define kSslContextGetPtr (sysLibTrapCustom+10)
#define kSslContextSetLong (sysLibTrapCustom+9)
#define kSslContextSetPtr (sysLibTrapCustom+11)
#define kSslFlush (sysLibTrapCustom+20)
#define kSslLibClose sysLibTrapClose
#define kSslLibCreate (sysLibTrapCustom)
#define kSslLibDestroy (sysLibTrapCustom+1)
#define kSslLibGetLong (sysLibTrapCustom+3)
#define kSslLibGetPtr (sysLibTrapCustom+5)
#define kSslLibName sysLibTrapName
#define kSslLibOpen sysLibTrapOpen
#define kSslLibSetLong (sysLibTrapCustom+2)
#define kSslLibSetPtr (sysLibTrapCustom+4)
#define kSslLibSleep sysLibTrapSleep
#define kSslLibWake sysLibTrapWake
#define kSslOpen (sysLibTrapCustom+12)
#define kSslPeek (sysLibTrapCustom+18)
#define kSslRead (sysLibTrapCustom+16)
#define kSslReceive (sysLibTrapCustom+15)
#define kSslSend (sysLibTrapCustom+14)
#define kSslWrite (sysLibTrapCustom+17)

Miscellaneous SSL Library Constants ^TOP^

Purpose

These constants are also defined in SslLib.h.

Declared In

SslLib.h

Constants

#define kSslDBName "SslLib": The SSL library's name. Use this when determining if the SSL library is loaded with SysLibFind().
#define kSslLibCreator 'ssl0': The SSL library's creator ID. Use this when loading the SSL library with SysLibLoad().
#define kSslLibType sysFileTLibrary: The SSL library's type. Use this when loading the SSL library with SysLibLoad().

SSL Library Functions and Macros ^TOP^

SslClose Function ^TOP^

Purpose

Performs the shutdown part of the SSL protocol.

Declared In

SslLib.h

Prototype

Err SslClose (
   UInt16 libRef,
   SslContext *ctx,
   UInt16 mode,
   UInt32 timeout
)

Parameters

→ libRef: SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.
→ 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 ORed together.

Example

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

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

SslConsume Function ^TOP^

Purpose

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

Declared In

SslLib.h

Prototype

void SslConsume (
   UInt16 libRef,
   SslContext *ctx,
   Int32 number
)

Parameters

→ libRef: SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.
→ ctx: The SslContext to operate on.
→ number: The number of bytes to remove from the internal buffer.

Returns

Nothing.

Comments

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

Example

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

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

SslContextCreate Function ^TOP^

Purpose

Creates a new SSL Context.

Declared In

SslLib.h

Prototype

Err SslContextCreate (
   UInt16 libRef,
   SslLib *lib,
   SslContext **ctx
)

Parameters

→ libRef: SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.
→ lib: The SSL library structure.
← ctx: Where to deposit the SslContext pointer.

Returns

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

Comments

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

SslContextDestroy Function ^TOP^

Purpose

Destroys the SSL Context.

Declared In

SslLib.h

Prototype

void SslContextDestroy (
   UInt16 libRef,
   SslContext *ctx
)

Parameters

→ libRef: SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.
→ ctx: The SslContext to destroy.

Returns

Nothing.

Comments

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

SslContextGetLong Function ^TOP^

Purpose

Retrieve an integer attribute value from the passed SslContext structure.

Declared In

SslLib.h

Prototype

Int32 SslContextGetLong (
   UInt16 libRef,
   SslContext *lib,
   SslAttribute attr
)

Parameters

→ libRef: SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.
→ lib: The SslContext from which the value is to be retrieved.
→ attr: Attribute to retrieve.

Returns

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

Comments

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

Example

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

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

SslContextGetPtr Function ^TOP^

Purpose

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

Declared In

SslLib.h

Prototype

Err SslContextGetPtr (
   UInt16 libRef,
   SslContext *lib,
   SslAttribute attr,
   void **value
)

Parameters

→ libRef: SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.
→ 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(theLibRef, ssl,&session);

SslContextSetLong Function ^TOP^

Purpose

Modify one of the numeric attributes of a SslContext structure.

Declared In

SslLib.h

Prototype

Err SslContextSetLong (
   UInt16 libRef,
   SslContext *lib,
   SslAttribute attr,
   long value
)

Parameters

→ libRef: SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.
→ lib: The SslContext on which to operate.
→ attr: The attribute to modify.
→ value: The new value.

Returns

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

Comments

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

Example

The following code excerpt shows how this function is used.

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

SslContextSetPtr Function ^TOP^

Purpose

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

Declared In

SslLib.h

Prototype

Err SslContextSetPtr (
   UInt16 libRef,
   SslContext *lib,
   SslAttribute attr,
   void *value
)

Parameters

→ libRef: SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.
→ 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(theLibRef, lib,&ssl); 
 
/* Configure to have 'debugCallbackFunction' called for each 
 * SSL protocol handshake state change */ 
cb.callback = debugCallbackFunction; 
cb.data = NULL; 
err = SslContextSet_InfoInterest(theLibRef, lib,
   sslInfoHandshake); 
err = SslContextSet_InfoCallback(theLibRef, lib,(void *)&cb);

SslFlush Function ^TOP^

Purpose

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

Declared In

SslLib.h

Prototype

Err SslFlush (
   UInt16 libRef,
   SslContext *ctx,
   Int32 *outstanding
)

Parameters

→ libRef: SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.
→ 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

A SslContext can be set into 'noAutoFlush' 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 noAutoFlush is to allow multiple SslWrite/SslSend commands to have their output buffered in the SslContexts 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 operaton 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(theLibRef, ssl,0); 
SslWrite(theLibRef, ssl,"GET ",4, &err); 
SslWrite(theLibRef, ssl,url,StrLen(url), &err); 
SslWrite(theLibRef, ssl," HTTP/1.0\r\n\r\n",13, &err); 
 
err=SslFlush(theLibRef, ssl,NULL);

SslLibClose Function ^TOP^

Purpose

SSL Library's shared library close function.

Declared In

SslLib.h

Prototype

Err SslLibClose (
   UInt16 libRef
)

Parameters

→ libRef: SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

Returns

Returns errNone if the SSL library was successfully closed.

SslLibCreate Function ^TOP^

Purpose

Creates the SSL library context.

Declared In

SslLib.h

Prototype

Err SslLibCreate (
   UInt16 libRef,
   SslLib **lib
)

Parameters

→ libRef: SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.
← lib: Where to deposit the SslLib pointer

Returns

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

Comments

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

SslLibDestroy Function ^TOP^

Purpose

Destroys the context represented by lib.

Declared In

SslLib.h

Prototype

void SslLibDestroy (
   UInt16 libRef,
   SslLib *lib
)

Parameters

→ libRef: SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.
→ lib: SslLib structure to be destroyed.

Returns

Nothing.

SslLibGetLong Function ^TOP^

Purpose

Retrieve an integer attribute value from the passed SslLib structure.

Declared In

SslLib.h

Prototype

Int32 SslLibGetLong (
   UInt16 libRef,
   SslLib *lib,
   SslAttribute attr
)

Parameters

→ libRef: SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.
→ lib: The SslLib from which the value is to be retrieved.
→ attr: Attribute to retrieve.

Returns

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

Comments

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

SslLibGetPtr Function ^TOP^

Purpose

Retrieve an pointer attribute value from the passed SslLib structure.

Declared In

SslLib.h

Prototype

Err SslLibGetPtr (
   UInt16 libRef,
   SslLib *lib,
   SslAttribute attr,
   void **value
)

Parameters

→ libRef: SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.
→ 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(theLibRef, lib,&cb);

SslLibName Function ^TOP^

Purpose

Declared In

SslLib.h

Prototype

Err SslLibName (
   UInt16 libRef
)

Parameters

→ libRef: SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

Returns

SslLibOpen Function ^TOP^

Purpose

SSL Library's shared library open function.

Declared In

SslLib.h

Prototype

Err SslLibOpen (
   UInt16 libRef
)

Parameters

→ libRef: SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

Returns

Returns errNone if the SSL library was successfully opened.

SslLibSetLong Function ^TOP^

Purpose

Modify one of the numeric attributes of a SslLib structure.

Declared In

SslLib.h

Prototype

Err SslLibSetLong (
   UInt16 libRef,
   SslLib *lib,
   SslAttribute attr,
   Int32 value
)

Parameters

→ libRef: SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.
→ lib: The SslLib on which to operate.
→ attr: The attribute to modify.
→ value: The new value.

Returns

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

Comments

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

Example

The following code excerpt shows how this function is used.

SslLib *lib; 
Err err; 
 
err = SslLibCreate(theLibRef, &lib); 
err = SslLibSet_AutoFlush(theLibRef, lib,0); /* Turn off */

SslLibSetPtr Function ^TOP^

Purpose

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

Declared In

SslLib.h

Prototype

Err SslLibSetPtr (
   UInt16 libRef,
   SslLib *lib,
   SslAttribute attr,
   void *value
)

Parameters

→ libRef: SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.
→ 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(theLibRef, &lib); 
 
/* Configure to have 'debugCallbackFunction' called for each 
 * SSL protocol handshake state change */ 
cb.callback = debugCallbackFunction; 
cb.data = NULL; 
err = SslLibSet_InfoInterest(theLibRef, lib,
   sslInfoHandshake); 
err = SslLibSet_InfoCallback(theLibRef, lib,(void *)&cb);

SslLibSleep Function ^TOP^

Purpose

SSL Library's shared library sleep function.

Declared In

SslLib.h

Prototype

Err SslLibSleep (
   UInt16 libRef
)

Parameters

→ libRef: SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

Returns

SslLibWake Function ^TOP^

Purpose

SSL Library's shared library wake function.

Declared In

SslLib.h

Prototype

Err SslLibWake (
   UInt16 libRef
)

Parameters

→ libRef: SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

Returns

SslOpen Function ^TOP^

Purpose

Initializes the passed SslContext.

Declared In

SslLib.h

Prototype

Err SslOpen (
   UInt16 libRef,
   SslContext *ctx,
   UInt16 mode,
   UInt32 timeout
)

Parameters

→ libRef: SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.
↔ 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) to use for in Net Library.

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 ORed together, and their values affect the functionality of the SslOpen() call. If non-fatal network errors occur (timeouts), the function can be re-called. When the function finally returns errNone, the SSL handshake will have completed and any SslContext will be able to return a valid SslSession structure. If one re-calls SslOpen(), make sure to not have either of sslOpenModeClear or SslOpenModeSsl set or the connection will be reset.

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

Returns

SslClose(), SslContextSetLong(), SslContextSetPtr()

SslPeek Function ^TOP^

Purpose

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

Declared In

SslLib.h

Prototype

Err SslPeek (
   UInt16 libRef,
   SslContext *ctx,
   void **buffer_ptr,
   Int32 *availableBytes,
   Int32 readSize
)

Parameters

→ libRef: SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.
→ 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 bufferes since it can read directly from the SslContext buffers. Once a quantity of data is reported as availale in *availableBytes, the total will not increase until that number of bytes has been 'consumed'.

SslRead Function ^TOP^

Purpose

Receives data.

Declared In

SslLib.h

Prototype

Int32 SslRead (
   UInt16 libRef,
   SslContext *ctx,
   void *buffer,
   Int32 bufferLen,
   Err *errRet
)

Parameters

→ libRef: SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.
→ 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.

SslReceive Function ^TOP^

Purpose

Receives data.

Declared In

SslLib.h

Prototype

Int16 SslReceive (
   UInt16 libRef,
   SslContext *ctx,
   void *buffer,
   UInt16 bufferLen,
   UInt16 flags,
   void *fromAddr,
   UInt16 fromLen,
   Int32 timeout,
   Err *errRet
)

Parameters

→ libRef: SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.
→ 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 netIOFlag... flags. See the Net Library documentation.
← fromAddr: Buffer to hold address of sender (NetSocketAddrType).
↔ fromLen: Size of fromAddr 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.

SslSend Function ^TOP^

Purpose

Sends data over the network.

Declared In

SslLib.h

Prototype

Int16 SslSend (
   UInt16 libRef,
   SslContext *ctx,
   const void *buffer,
   UInt16 bufferLen,
   UInt16 flags,
   void *toAddr,
   UInt16 toLen,
   Int32 timeout,
   Err *errRet
)

Parameters

→ libRef: SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.
→ ctx: The SslContext to use.
→ buffer: Buffer containing data to send.
→ bufferLen: Length, in bytes, of data to send.
→ flags: One or more netIOFlag... flags. See the Net Library documentation.
→ toAddr: Address to send to. See the NetLibSend() documentation.
→ 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 NetLibSend() 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 NetLibSend() and are used when the data bytes are written to the network.

SslWrite Function ^TOP^

Purpose

Sends data over the network.

Declared In

SslLib.h

Prototype

Int32 SslWrite (
   UInt16 libRef,
   SslContext *ctx,
   const void *buffer,
   Int32 bufferLen,
   Err *errRet
)

Parameters

→ libRef: SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.
← 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.

Application-Defined Functions ^TOP^

SslCallbackFunc Function ^TOP^

Purpose

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

Declared In

SslLib.h

Prototype

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

Parameters

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

Returns

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

Comments

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

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

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

Example

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

alert=SslContextGet_LastAlert(theLibRef, cb->ssl);

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

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

The Info Callback

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

argi	argv type
`sslArgInfoHandshake`	`NULL`
`sslArgInfoAlert`	`NULL`
`sslArgInfoReadBefore`	`SslIoBuf`
`sslArgInfoReadAfter`	`SslIoBuf`
`sslArgInfoWriteBefore`	`SslIoBuf`
`sslArgInfoWriteAfter`	`SslIoBuf`
`sslArgCert`	`SslExtendedItems -` the certificate sent by the server.

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

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

The Verify Callback

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

argi	argv type
`sslErrVerifyBadSignature`	`SslVerify`
`sslErrVerifyNoTrustedRoot`	`SslVerify`
`sslErrVerifyNotAfter`	`SslVerify`
`sslErrVerifyNotBefore`	`SslVerify`
`sslErrVerifyConstraintViolation`	`SslVerify`
`sslErrVerifyUnknownCriticalExtension`	`SslVerify`
`0`	`SslVerify`

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

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

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

The SslVerify Structure

The SslVerify structure is defined as follows:

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

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

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 for a given verification error.

Verification Error	`fieldItems[field]` contains...
`sslErrCertBadSignature`	The server's certificate, which contains the public key entries.
`SslErrCertNoTrustedRoot`	`NULL`
`SslErrCertNotAfter`	`sslExItemTypeX509`, `asn1FldX509NotAfter`
`SslErrCertNotBefore`	`sslExItemTypeX509`, `asn1FldX509NotBefore`
`sslErrCertConstraintViolation`	`asn1ExItemTypeX509Ex` start location
`sslErrCertUnknownCriticalExtension`	`asn1ExItemTypeX509Ex` start location
`SslErrOk`	`NULL`

For the cases of the returned field being the "asn1ExItemTypeX509Ex start location", an explanation is as follows:

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

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

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

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

2.5.29.15	`KeyUsage`
2.5.29.37	`ExtKeyUsage`
2.5.29.19	`BasicConstraints`

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

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;

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 strucuture.

The SslExtendedItem Structure

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

Currently defined values are:

`sslExItemTypeX509`	X.509 Certificate.
`SslExItemTypeRSA`	RSA public key.
`sslExItemTypeRDN`	An X.509 Relative Distinguished Name (RDN). This is a complex way of saying a certificate name. Each certificate contains two names, the Subject of the certificate and the Issuer of the certificate. Both are encoded as RDNs which contain multiple fields.
`sslExItemTypeX509Ex`	X.509 certificates can contain what are called Extensions. A certificate can contain multiple extensions. This type is used to specify extensions.
`SslExItemTypeE509ExData`	Used to group 'decomposed' X.509 extensions.

The SslExtendedItem structure is defined as follows:

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

An SslExtendedItem strucure 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(theLibRef, ssl,&infoCB); 
SslContextSet_InfoInterest(theLibRef, 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(theLibRef, 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); 
}

86 SSL Library

SSL Library Structures and Types ^TOP^

SslAttribute Typedef ^TOP^

Purpose

Declared In

Prototype

Comments

SslCallback Struct ^TOP^

Purpose

Declared In

Prototype

Fields

Comments

SslCipherSuiteInfo Struct ^TOP^

Purpose

Declared In

Prototype

Fields

Comments

SslContext Struct ^TOP^

Purpose

Declared In

Prototype

Fields

SslExtendedItem Struct ^TOP^

Purpose

Declared In

Prototype

Fields

Comments

SslExtendedItems Struct ^TOP^

Purpose

Declared In

Prototype

Fields

Comments

SslIoBuf Struct ^TOP^

Purpose

Declared In

Prototype

Fields

Comments

SslLib Struct ^TOP^

Purpose

Declared In

Prototype

Fields

SslSession Struct ^TOP^

Purpose

Declared In

Prototype

Fields

Comments

SslSocket Struct ^TOP^

Purpose

Declared In

Prototype

Fields

Comments

SslVerify Struct ^TOP^

Purpose

Declared In

Prototype

Fields

Comments

SSL Library Constants ^TOP^

SSL Open Mode Flags ^TOP^

Purpose

Declared In

Constants

SSL Close Mode Flags ^TOP^

Purpose

Declared In

Constants

Mode Attribute Values ^TOP^

Purpose

Declared In

Constants

Comments

Protocol Versions ^TOP^