Legacy Documentclose button

Important: The information in this document is obsolete and should not be used for new development.

Previous Book Contents Book Index Next

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.

ioCompletionProcPtrA pointer to completion routine.
ioResultOSErrA result code.
ioCRefNumIntegerThe ADSP driver reference number.
csCodeIntegerAlways sdspOpen for this function.
ccbRefNumIntegerThe CCB reference number for
connection end.
localCIDIntegerThe ID of this connection end.
remoteCIDIntegerThe ID of remote connection end.
remoteAddressAddrBlockA remote internet address.
filterAddressAddrBlockA filter for open connection end.
sendSeqLongInt The initial send sequence number.
sendWindowIntegerThe initial size of remote receive queue.
recvSeqLongInt Not used for ASDSP.
attnSendSeqLongIntThe attention send sequence number.
attnRecvSeqLongIntNot used for ASDSP.
ocModeByteThe connection-opening mode.
ocIntervalByteThe interval between open requests.
ocMaximumByteThe maximum number of retries of the open-connection request.
secureBooleanA flag that determines if ASDSP authenticates the connection.
sessionKeyAuthKeyPtrA pointer to the session encryption key.
credentialsSizeLongIntThe length of credentials.
credentialsPtrA pointer to credentials.
workspacePtrA pointer to workspace for connection.
recipientAuthIdentityThe identity of recipient.
issueTimeUTCTimeThe time when credentials were issued.
expiryUTCTimeThe time when credentials expire.
initiatorRecordIDPtrA pointer to record ID of initiator.
hasIntermediaryBooleanTRUE if credentials has an intermediary.
intermediaryRecordIDPtrA 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:
ocRequestocPassiveocAccept
-->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:
 ModeValueMeaning
 ocRequest1ADSP attempts to open a connection with the remote socket you specify.
 ocPassive2The connection end waits to receive
a connection request.
 ocAccept3The 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:

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
noErr0No error
errOpenDenied-1273Open request denied by recipient
errFwdReset-1276A forward reset caused ASDSP to terminate the request
errOpening-1277Attempt to open connection failed
errState-1278Connection end is not open
errAborted-1279Request aborted by dspRemove or dspClose routine
errRefNum-1280Bad connection reference number
kOCEUnsupportedCredentialsVersion-1543Credentials version not supported
kOCEBadEncryptionMethod-1559During 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-1570You passed NIL for the workspace parameter
kOCEAuthenticationTrouble-1571Authentication process failed

Previous Book Contents Book Index Next

© Apple Computer, Inc.
7 JUL 1996