Legacy Document

Inside Macintosh: Networking /

Chapter 5 - AppleTalk Data Stream Protocol (ADSP) / Using ASDSP

Opening a Secure Connection

To open a secure ASDSP connection, both the initiator and the recipient must call the sdspOpen routine after calling the dspInit routine and, optionally, the dspOptions routine. First this section describes how the initiator part of an application opens a
secure connection. Then it describes how the recipient end of an application opens
a secure connection.

From the Initiator's End

An initiator can send a request to open a secure session to

• a specific socket whose client application has opened a connection end to wait passively for a connection request
• a connection listener whose function is to accept requests for secure connections and pass those requests on to a connection server

The initiator makes either an AOCE AuthTradeProxyForCredentials call or an AOCE AuthGetCredentials call to the authentication server. It passes to the authenti-
cation server its own name and the name of the recipient and gets back the session key and the credentials for the session. For an explanation of the calls that the initiator must make to the Authentication Manager, see the chapter "Authentication Manager" in Inside Macintosh: AOCE Application Programming Interfaces.

Through the sdspOpen call, the initiator passes the credentials to ASDSP to send to the recipient. ASDSP decrypts the credentials and passes the decrypted credential informa-
tion to the recipient.

To open a secure ASDSP connection, the initiator performs the following procedure:

1. Determine if the Apple Open Collaboration Environment (AOCE) software is installed by calling the Gestalt function. See the chapter "Introduction to AOCE" in Inside Macintosh: AOCE Application Programming Interfaces for a description of the selector values that you use.
2. Allocate memory for the required data structures identified in this step. The memory belongs to ASDSP until the routine completes execution, after which you can either release or reuse the memory. You must either allocate nonrelocatable memory or lock the memory until the routine completes. See the chapter "Authentication Manager" in Inside Macintosh: AOCE Application Programming Interfaces for a description of the memory that you need to allocate for calls that you make to that interface. The data structures that you need to allocate memory for are listed here:
   • An ASDSP parameter block of type SDSPParamBlock. You pass a pointer to this parameter block as the value of the paramBlock parameter to the PBControl function. (See "The ASDSP Parameter Block" on page 5-41.)
   • A workspace buffer that the sdspOpen routine uses internally whose size is equal to sdspWorkSize. The memory for this buffer must be aligned on an even boundary. You pass a pointer to this buffer as the value of the workspace parameter.
   • A buffer for the credentials retrieved from the authentication server and passed
     to ASDSP.
   • A buffer for the session key retrieved from the authentication server and passed to ASDSP. This is a data structure of type AuthKey.

3. Call the Authentication Manager's AuthGetUTCTime function to get the universal coordinated time (UTC). You base the credentials expiration time that you specify
   as input to the AuthGetCredentials function on the UTC. See the chapter "Authentication Manager" for a description of the AuthGetUTCTime function.
4. Obtain your (the initiator's) identity and the recipient's record ID. (You can use the local identity or get a specific identity for the initiator.) You need to pass these values to the authentication server to get the session key and credential block from the server. See the chapter "Authentication Manager" for a discussion of identities and complete instruction on how to get these values.
5. Call the Authentication Manager's AuthGetCredentials function or AuthTradeProxyForCredentials function to get the credentials and the session key. You use these values as input to the sdspOpen routine. See the chapter "Authentication Manager" for information on the AuthGetCredentials and AuthTradeProxyForCredentials functions.

   You pass the AuthGetCredentials function or AuthTradeProxyForCredentials function the following values returned from the functions that you called in the previous steps:

   • The initiator's identity.
   • A pointer to a buffer containing the record ID for the recipient.
   • The desired expiration time of the credentials. You use the expiry parameter to specify for how long you want the credentials to be valid. Credentials are valid for at most eight hours after they are returned to the initiator by the server. You base the expiration time on the UTC time returned by the AuthGetUTCTime function.
   • The expected length of the credentials. A buffer three times the size of a packed record ID is usually sufficient for credentials. The AOCE constant kPackedRecordIDMaxBytes specifies the size of a single packed record ID.

6. Call the sdspOpen routine to open a secure connection. To call the sdspOpen routine, you call the Device Manager's PBControl function and specify sdspOpen as the value of the csCode parameter. The parameter block for the sdspOpen routine includes fields also used for the standard dspOpen routine. In addition to these parameters, you specify parameters used in the authentication process to establish
   the secure connection.

   The initiator application calls the sdspOpen routine with a value of ocRequest for the ocMode parameter to direct ASDSP to open a connection with a specific socket on the AppleTalk internet. When you execute the sdspOpen routine in the ocRequest mode, ASDSP sends an open-connection request to the address you specify.

   If the socket to which you send the open-connection request is a connection listener, the connection server that operates that connection listener can select any socket on the internet to be the connection end that responds to the open-connection request. To restrict the socket from which you will accept a response to your open-connection request, specify a value for the filterAddress parameter to the sdspOpen routine.

   To use the ocRequest mode, you must know the complete internet address of the remote socket, and the ASDSP client at that address must either be a connection listener or have executed the sdspOpen routine in the ocPassive mode. You can use the NBP routines to obtain a list of the names of objects on the internet and to determine the internet address of a socket when you know its name. See the chapter "Name-Binding Protocol (NBP)" in this book for information on the NBP routines.

   In addition to the standard ADSP parameters required for a dspOpen call, the initiator supplies the following input values to the sdspOpen call:

   	Parameter	Value
   	secure	To open a secure authenticated connection, pass a value of TRUE. To open a normal, unauthenticated connection, pass a value of FALSE.
   	sessionKey	A pointer to the encryption key returned from the AuthGetCredentials or AuthTradeProxyForCredentials function.
   	credentialsSize	The value that the AuthGetCredentials function or the AuthTradeProxyForCredentials function returned that specifies the length of the credentials.
   	credentials	A pointer to the credentials that the AuthGetCredentials function or the AuthTradeProxyForCredentials function returned.
   	workspace	A pointer to the workspace buffer that you allocated, which is for ASDSP's internal use.

From the Recipient End

To open a secure ASDSP connection, the recipient performs the following procedure:

1. Allocate memory for the following data structures. The memory belongs to ASDSP until the routine completes execution, after which you can either release or reuse the memory. You must either allocate nonrelocatable memory or lock the memory until the routine completes.
   • An ASDSP secure parameter block of type SDSPParamBlock. You pass a pointer to this parameter block as the value of the paramBlock parameter to the PBControl function. (See "The ASDSP Parameter Block" beginning on page 5-41.)
   • A workspace buffer that the sdspOpen routine uses internally whose size is equal to sdspWorkSize. The memory for this buffer must be aligned on an even boundary. You must pass a pointer to the buffer as the value of the workspace parameter.
   • A data structure of type AuthKey for the session key retrieved from the authentica-
     tion server and passed to ASDSP. ASDSP breaks out from the credentials block the session key encrypted in the recipient's private key and returns the session key to the recipient in the sessionKey buffer.
   • A buffer for the record ID of the initiator that ASDSP returns to the recipient in response to the recipient's sdspOpen routine. You pass a pointer to this buffer as the value of the initiator parameter. ASDSP breaks out the initiator's record ID from the credential block that the initiator passes to ASDSP and returns it to the recipient. See the chapter "Authentication Manager" in Inside Macintosh: AOCE Application Programming Interfaces for a description of how to create a maximum-
     size record ID structure that is large enough to hold any record ID.
   • A buffer for the record ID of the intermediary that ASDSP returns to the recipient if an intermediary is found in the credentials. You pass a pointer to this buffer as the value of the intermediary parameter. An intermediary is a proxy that has used the AuthTradeProxyForCredentials function to obtain the credentials used in the authentication process. See the chapter "Authentication Manager" in Inside Macintosh: AOCE Application Programming Interfaces for a discussion of the use of an intermediary and the AuthTradeProxyForCredentials function and for a description of how to create a maximum-size record ID structure that is large enough to hold any record ID.

2. Call the sdspOpen routine to open a secure connection. To call the sdspOpen routine, you call the Device Manager's PBControl function and specify sdspOpen as the value of the csCode parameter. The parameter block for the sdspOpen routine includes fields also used for the standard dspOpen routine. In addition to these parameters, you specify parameters used in the authentication process to establish
   the secure connection.

   A recipient end of a connection can be either a connection listener that listens for connection requests and passes them on to a connection server or a socket that waits passively to receive a connection request.

   If the recipient is a connection listener, it calls the sdspOpen routine with a
   value of ocAccept for the ocMode parameter. The connection server accepts
   and acknowledges receipt of a connection request. When you call the sdspOpen routine, you must provide the values returned by the dspCLListen routine
   for the remoteCID, remoteAddress, sendSeq, sendWindow, and attnSendSeq parameters. You can poll the state field in the CCB to determine when the connection is open. Alternatively, you can check the result code for the sdspOpen routine when the routine completes execution. If the routine returns the noErr
   result code, then the connection is open.

   If the recipient is a connection end associated with a passive socket that calls the sdspOpen routine with a value of ocPassive for the ocMode parameter, use the ocPassive mode when you expect to receive an open-connection request from a remote socket. You can specify a value for the filterAddress parameter to restrict the network number, node ID, or socket number from which you will accept an open-connection request.

   You can poll the state field in the CCB to determine when the connection end is waiting to receive an open-connection request, when the connection end is waiting to receive an acknowledgment of an open-connection request, and when the connection is open. See the section "The ADSP Connection Control Block Record" beginning on page 5-35 for a description of the CCB fields. Alternatively, you can check the result code for the dspOpen routine when the routine completes execution. If the routine returns the noErr result code, then the connection is open.

   In addition to the standard ADSP parameters required for a dspOpen call, the recipient supplies the following input values to the sdspOpen call:

   	Parameter	Value
   	sessionKey	A pointer to a data structure of type AuthKey, which you allocated. ASDSP copies the session key into this buffer if an authenticated connection was successfully opened.
   	workspace	A pointer to the workspace buffer that you allocated, which is for ASDSP's internal use.
   	recipient	The identity of the recipient.
   	initiator	A pointer to a maximum-size record ID. ASDSP copies the initiator's record ID into this structure if an authenticated connection was successfully opened.
   	intermediary	A pointer to a maximum-size record ID. ASDSP copies the intermediary's record ID into this structure if an authenticated connection was successfully opened and an intermediary was used to obtain the credentials used to authenticate the call.

   If a secure connection was successfully opened, ASDSP returns the following values:

   	Parameter	Value
   	issueTime	The time when the credentials were issued. ASDSP copies this value from the credentials.
   	expiry	The time when the credentials expire. ASDSP copies this value from the credentials.
   	sessionKey	The encryption key for the session. ASDSP copies this value from the credentials.
   	initiator	A pointer to a maximum-size record ID structure. If an authenticated connection was successfully opened, this structure holds the initiator's record ID.
   	hasIntermediary	A flag that is set to TRUE if an intermediary was used to obtain the credentials.
   	intermediary	A pointer to a maximum-size record ID. If an authentication connection was successfully opened and an intermediary was used to obtain the credentials, this structure holds the intermediary's record ID.

Sending Encrypted Data Across a Secure Connection

After a secure connection is established, both ends can send encrypted data over the session. ASDSP client applications use the dspWrite routine to send data, encrypted
or not, over a secure connection. You can turn the encryption feature on or off on a message-by-message basis by setting one flag to direct ASDSP to encrypt the data and setting another flag to terminate the message.

To set these flags, you use the bits of the end-of-message (eom) field; this field is part of the ioParams variant record of the DSP parameter block that you pass to the dspWrite routine. For secure connections, the eom field comprises these two single-bit flags instead of a zero-nonzero byte. You can use the dspEncryptMask and dspEOMMask masks to set these flags, or you can use the dspEncryptBit or dspEOMBit constant.

Note

Apart from the dspWrite routine's eom parameter, the interface to ADSP remains unchanged in regard to encryption.

The encryption process is transparent to the client application that receives the data; ASDSP determines if the received information is encrypted, and, if so, it decrypts the byte stream before copying the data to the read buffer specified by the dspRead routine.

To write data that ASDSP encrypts and then transmits or to terminate data encryption, you call the dspWrite routine using the Device Manager's PBControl function.

• Set the encrypt bit of the eom field (bit 1) of the DSP parameter block. To set the encrypt bit, you use the dspEncryptMask mask or the dspEncryptBit constant. Note that ASDSP checks this flag on the first write of the connection or the first write following a write for which the end-of-message flag (bit 0 of the eom field) is set.
• Set the end-of-message bit (bit 0) of the eom field to terminate the encrypted message. To set the end-of-message bit, you use the dspEOMMask mask or the dspEOMBit constant.

If you want to encrypt all messages, you can simply set the encrypt bit on all
dspWrite calls.