Legacy Document

Inside Macintosh: Networking /

Chapter 5 - AppleTalk Data Stream Protocol (ADSP) / ADSP Reference

Routines / Establishing and Terminating an ADSP Connection

sdspOpen

The sdspOpen routine opens a secure (ASDSP) connection and causes ASDSP to perform the challenge-and-reply process that authenticates the ASDSP clients at either end of the connection. You use the PBControl function to call the sdspOpen routine. See "Routines" on page 5-43 for a description of the PBControl function.

ioCompletion	ProcPtr	A pointer to completion routine.
ioResult	OSErr	A result code.
ioCRefNum	Integer	The ADSP driver reference number.
csCode	Integer	Always sdspOpen for this function.
ccbRefNum	Integer	The CCB reference number for connection end.
localCID	Integer	The ID of this connection end.
remoteCID	Integer	The ID of remote connection end.
remoteAddress	AddrBlock	A remote internet address.
filterAddress	AddrBlock	A filter for open connection end.
sendSeq	LongInt	The initial send sequence number.
sendWindow	Integer	The initial size of remote receive queue.
recvSeq	LongInt	Not used for ASDSP.
attnSendSeq	LongInt	The attention send sequence number.
attnRecvSeq	LongInt	Not used for ASDSP.
ocMode	Byte	The connection-opening mode.
ocInterval	Byte	The interval between open requests.
ocMaximum	Byte	The maximum number of retries of the open-connection request.
secure	Boolean	A flag that determines if ASDSP authenticates the connection.
sessionKey	AuthKeyPtr	A pointer to the session encryption key.
credentialsSize	LongInt	The length of credentials.
credentials	Ptr	A pointer to credentials.
workspace	Ptr	A pointer to workspace for connection.
recipient	AuthIdentity	The identity of recipient.
issueTime	UTCTime	The time when credentials were issued.
expiry	UTCTime	The time when credentials expire.
initiator	RecordIDPtr	A pointer to record ID of initiator.
hasIntermediary	Boolean	TRUE if credentials has an intermediary.
intermediary	RecordIDPtr	A pointer to record ID of intermediary.

The use of parameters by the sdspOpen routine depends on the mode in which the routine is executed, as follows:

ocRequest		ocPassive		ocAccept
-->	ioCompletion	-->	ioCompletion	-->	ioCompletion
<--	ioResult	<--	ioResult	<--	ioResult
-->	ioCRefNum	-->	ioCRefNum	-->	ioCRefNum
-->	csCode	-->	csCode	-->	csCode
-->	ccbRefNum	-->	ccbRefNum	-->	ccbRefNum
<--	localCID	<--	localCID	<--	localCID
<--	remoteCID	<--	remoteCID	-->	remoteCID
-->	remoteAddress	<--	remoteAddress	-->	remoteAddress
-->	filterAddress	-->	filterAddress	--	filterAddress
<--	sendSeq	<--	sendSeq	-->	sendSeq
<--	sendWindow	<--	sendWindow	-->	sendWindow
--	recvSeq	--	recvSeq	--	recvSeq
<--	attnSendSeq	<--	attnSendSeq	-->	attnSendSeq
--	attnRecvSeq	--	attnRecvSeq	--	attnRecvSeq
-->	ocMode	-->	ocMode	-->	ocMode
-->	ocInterval	-->	ocInterval	-->	ocInterval
-->	ocMaximum	-->	ocMaximum	-->	ocMaximum
-->	secure	<--	secure	<--	secure
-->	sessionKey	<--	sessionKey	<--	sessionKey
-->	credentialsSize	--	credentialsSize	--	credentialsSize
-->	credentials	--	credentials	--	credentials
-->	workspace	-->	workspace	-->	workspace
--	recipient	-->	recipient	-->	recipient
--	issueTime	<--	issueTime	<--	issueTime
--	expiry	<--	expiry	<--	expiry
--	initiator	<->	initiator	<->	initiator
--	hasIntermediary	<--	hasIntermediary	<--	hasIntermediary
--	intermediary	<->	intermediary	<->	intermediary
Key: --> input <-- output <-> input and output -- not used

Field Description

csCode

The routine selector, always equal to sdspOpen for this routine.

ccbRefNum

This field is used in the same way that it is used for ADSP. See the description of this field under "dspOpen" beginning on page 5-48.

localCID

This field is used in the same way that it is used for ADSP. See the description of this field under "dspOpen" beginning on page 5-48.

remoteCID

The identification number of the remote connection end. This parameter is returned by the sdspOpen routine in the ocRequest and ocPassive modes. A connection server must provide this number to the sdspOpen routine when the server executes the routine in ocAccept mode; in this case, the connection server obtains the remoteCID value from the dspCLListen routine.

remoteAddress

The internet address of the remote socket with which you wish to establish communications. This address consists of a 2-byte network number, a 1-byte node ID, and a 1-byte socket number. You must provide this parameter when you call the sdspOpen routine in
the ocRequest or ocAccept mode. When you call the sdspOpen routine in the ocAccept mode, you must use the value for the remoteAddress parameter that was returned by the dspCLListen routine. This parameter is returned by the sdspOpen routine when you call the routine in the ocPassive mode.

filterAddress

This field is used in the same way that it is used for ADSP. See the description of this field under "dspOpen" beginning on page 5-48.

sendSeq

The sequence number of the first byte that the local connection end will send to the remote connection end. ASDSP uses this number
to coordinate communications and to check for errors. ASDSP returns a value for the sendSeq parameter when you execute
the sdspOpen routine in the ocRequest or ocPassive mode. When you execute the sdspOpen routine in the ocAccept mode, you must specify the value for the sendSeq parameter that was returned by the dspCLListen routine.

sendWindow

The sequence number of the last byte that the remote connection end has buffer space to receive. ASDSP uses this number to coordinate communications and to check for errors. ASDSP returns a value for the sendWindow parameter when you execute the sdspOpen routine in the ocRequest or ocPassive mode. When you execute the sdspOpen routine in the ocAccept mode, you must specify the value for the sendWindow parameter that was returned by the dspCLListen routine.

recvSeq

This field is not used by ASDSP.

attnSendSeq

The sequence number of the next attention packet that the local connection end will transmit. ASDSP uses this number to coordinate communications and to check for errors. ASDSP returns a value for the attnSendSeq parameter when you execute the sdspOpen routine in the ocRequest or ocPassive mode. When you execute the sdspOpen routine in the ocAccept mode, you must specify the value for the attnSendSeq parameter that was returned by the dspCLListen routine.

attnRecvSeq

This field is not used by ASDSP.

ocMode

The mode in which the sdspOpen routine is to operate, as follows:

	Mode	Value	Meaning
	ocRequest	1	ADSP attempts to open a connection with the remote socket you specify.
	ocPassive	2	The connection end waits to receive a connection request.
	ocAccept	3	The connection server accepts and acknowledges receipt of a connec- tion request.

ocInterval

This field is used in the same way that it is used for ADSP. See the description of this field under "dspOpen" beginning on page 5-48.

ocMaximum

This field is used in the same way that it is used for ADSP. See the description of this field under "dspOpen" beginning on page 5-48.

secure

A flag that determines whether ASDSP authenticates the connection. On input for the initiator end, you must set this value to TRUE if you want ASDSP to authenticate the connection. You must provide a value for the secure parameter when you execute the sdspOpen routine in the ocRequest mode. ASDSP returns a value of TRUE for this parameter to the recipient for all modes if the session was authenticated.

sessionkey

A pointer to a buffer containing the session key returned by
the Authentication Manager's AuthGetCredentials or AuthTradeProxyForCredentials function. The initiator connection end must provide an input value for this parameter.
For the recipient connection end, ASDSP breaks out the session
key from the credentials block and returns a copy of the session key as the value of this parameter. See the description of the data structures that you need to allocate for ASDSP in the section "Opening a Secure Connection" beginning on page 5-30 for more information about the buffer.

credentialsSize

The size in bytes of credentials returned by the Authentica-
tion Manager's AuthTradeProxyForCredentials or AuthGetCredentials function.You must provide a value for the credentialsSize parameter when you execute the sdspOpen routine in the ocRequest mode. This parameter is not used for the recipient end of the connection when you call the sdspOpen routine in ocAccept mode or ocPassive mode.

credentials

A pointer to the credentials for this session that the Authentica-
tion Manager's AuthTradeProxyForCredentials or AuthGetCredentials function returned when you called it. Specify the size in bytes of the credential block pointed to by this parameter as the value of the credentialsSize parameter when you call the sdspOpen routine in the ocRequest mode. This parameter is not used for the recipient end of the connection when you call the sdspOpen routine in ocAccept mode or ocPassive mode. See the chapter "Authentication Manager" in Inside Macintosh: AOCE Application Programming Interfaces.

workspace

A pointer to a buffer that you allocate as workspace for the sdspOpen routine's internal use. The memory for the buffer that you allocate must be aligned on an even boundary and must be equal in size to the sdspWorkSize constant, which is 2048 bytes.

recipient

When the value of the ocMode parameter is ocAccept, you specify the identity of the connection server as the value of the recipient parameter. When the value of the ocMode parameter
is ocPassive, you specify the identity of the socket that is the recipient of the request call as the value of the recipient parameter. This field is not used when the ocMode parameter
value is ocRequest.

issueTime

The time when the authentication credentials were issued. Together with the expiry parameter value, the issueTime parameter specifies the period of time for which the credentials are valid. ASDSP extracts the value for the issueTime parameter from the decrypted credentials. ASDSP returns this value when the mode is ocPassive or ocAccept. The issueTime field is not used when the ocMode parameter value is ocRequest.

expiry

The time when the authentication credentials expire. Together with the issueTime parameter value, the expiry parameter specifies the duration for which the credentials are valid. ASDSP extracts the value for the expiry parameter from the decrypted credentials. This field is not used when the ocMode parameter value is ocRequest.

initiator

A pointer to the record ID of the initiator that ASDSP returns when the value of the ocMode parameter is ocAccept or ocPassive. ASDSP extracts this value from the encrypted credentials. This field is not used when the ocMode parameter value is ocRequest.

hasIntermediary

A flag that ASDSP sets if the credentials have an intermediary.
When this flag is set, a proxy was used; an intermediary used
the AuthTradeProxyForCredentials function to obtain the credentials used in the authentication process. The sdspOpen routine returns this value when the ocMode parameter value is ocPassive or ocAccept.

intermediary

A pointer to a buffer that is used to store the record ID of the inter-
mediary, if ASDSP finds an intermediary in the credentials. The sdspOpen routine returns this value when the ocMode parameter value is ocPassive or ocAccept.

DESCRIPTION

The sdspOpen routine opens a secure connection end if the identities of both the initiator and the recipient connection ends can be proven in the authentication process. You set the ocMode field of the parameter block to specify the opening mode that the sdspOpen routine is to use. The sdspOpen routine puts a connection end into one of the three following opening modes:

• In the ocRequest mode, ASDSP attempts to open a connection with the socket at the internet address you specify as the remoteAddress parameter.
• In the ocPassive mode, the connection end waits to receive an open-connection request from a remote connection end. You can use the filterAddress parameter
  to restrict the addresses from which you will accept a connection request.
• In the ocAccept mode, connection servers complete open-connection dialogs. When a connection server is informed by its connection listener that the connection listener has received an open-connection request, the connection server calls the dspInit routine to establish a connection end and then calls the sdspOpen routine in ocAccept mode to complete the connection. Connection listeners and connection servers are described in "Creating and Using a Connection Listener" beginning on page 5-22 and in "Establishing and Terminating an ADSP Connection" beginning on page 5-44. See "Connection Listeners" on page 5-7 for a brief introduction to connection listeners.

  Except for the authentication process, these three modes are used by ASDSP and ADSP in the same way and their behavior is the same. See the description of how these modes are used in "dspOpen" beginning on page 5-48.

  If ASDSP cannot successfully complete the authentication process, ASDSP tears down the connection and the sdspOpen calls made by both the initiator and the recipient return a result code reporting the reason why the authentication process failed. For the conditions that can cause the authentication process to fail, see the list of result codes that follows.

ASSEMBLY-LANGUAGE INFORMATION

To execute the sdspOpen routine from assembly language, call the _Control trap macro with a value of sdspOpen in the csCode field of the parameter block.

RESULT CODES

noErr	0	No error
errOpenDenied	-1273	Open request denied by recipient
errFwdReset	-1276	A forward reset caused ASDSP to terminate the request
errOpening	-1277	Attempt to open connection failed
errState	-1278	Connection end is not open
errAborted	-1279	Request aborted by dspRemove or dspClose routine
errRefNum	-1280	Bad connection reference number
kOCEUnsupportedCredentialsVersion	-1543	Credentials version not supported
kOCEBadEncryptionMethod	-1559	During the authentication process, the ASDSP implementations could not agree on an encryption method to be used (ASDSP can support multiple stream encryption methods. In Release 1, only RC4 and "no encryption" are supported.)
kOCENoASDSPWorkSpace	-1570	You passed NIL for the workspace parameter
kOCEAuthenticationTrouble	-1571	Authentication process failed