Library `afp`

This library was written by Patrik Karlsson <patrik@cqure.net> to facilitate communication with the Apple AFP Service. It is not feature complete and still missing several functions.

The library currently supports

Authentication using the DHX UAM (CAST128)
File reading and writing
Listing sharepoints
Listing directory contents
Querying ACLs and mapping user identities (UIDs)

The library was built based on the following reference: http://developer.apple.com/mac/library/documentation/Networking/Reference/AFP_Reference/Reference/reference.html http://developer.apple.com/mac/library/documentation/Networking/Conceptual/AFP/AFPSecurity/AFPSecurity.html#//apple_ref/doc/uid/TP40000854-CH232-CHBBAGCB

Most functions have been tested against both Mac OS X 10.6.2 and Netatalk 2.0.3

The library contains the following four classes

Response

** A class used as return value by functions in the Proto class. ** The response class acts as a wrapper and holds the response data and any error information.

Proto

** This class contains all the AFP specific functions and calls. ** The functions can be accessed directly but the preferred method is through the Helper class. ** The function names closely resemble those described in the Apple documentation. ** Some functions may lack some of the options outlined in Apple's documentation.

Helper

** The helper class wraps the Proto class using functions with a more descriptive name. ** Functions are task-oriented. For example, ReadFile and usually call several functions in the Proto class. ** The purpose of this class is to give developers easy access to some of the common AFP tasks.

Util

** The Util class contains a number of static functions mainly used to convert data.

The following information will describe how to use the AFP Helper class to communicate with an AFP server.

The short version:

helper = afp.Helper:new()
status, response = helper:OpenSession( host, port )
status, response = helper:Login()
.. do some fancy AFP stuff ..
status, response = helper:Logout()
status, response = helper:CloseSession()

Here's the longer version, with some explanatory text. To start using the Helper class, the script has to create its own instance. We do this by issuing the following:

helper = afp.Helper:new()

Next a session to the AFP server must be established, this is done using the OpenSession method of the Helper class, like this:

status, response = helper:OpenSession( host, port )

The next step needed to be performed is to authenticate to the server. We need to do this even for functions that are available publicly. In order to authenticate as the public user simply authenticate using nil for both username and password. This can be achieved by calling the Login method without any parameters, like this:

status, response = helper:Login()

To authenticate to the server using the username 'admin' and password 'nimda' we do this instead:

status, response = helper:Login('admin', 'nimda')

At this stage we're authenticated and can call any of the AFP functions we're authorized to. For the purpose of this documentation, we will attempt to list the servers share points. We do this by issuing the following:

status, shares = helper:ListShares()

Once we're finished, we need to logout and close the AFP session this is done by calling the following two methods of the Helper class:

status, response = helper:Logout()
status, response = helper:CloseSession()

Consult the documentation of each function to learn more about their respective return values.

Author:

Patrik Karlsson <patrik@cqure.net>

Copyright © Same as Nmap--See https://nmap.org/book/man-legal.html

Source: https://svn.nmap.org/nmap/nselib/afp.lua

Script Arguments

afp.username: The username to use for authentication.
afp.password: The password to use for authentication.

Functions

acl_group_to_long_string (acls): Converts a group bitmask of Search, Read and Write to table
acls_to_long_string (acls): Converts a numeric acl to string
CloseSession (self): Closes the AFP session and then the socket
create_fp_packet (self, command, data_offset, data): Creates an AFP packet
CreateDir (self, str_path): Creates a new directory on the AFP sharepoint
decode_dir_bitmap (bitmap, data, pos): Decodes a directory bitmap
decode_file_bitmap (bitmap, data, pos): Decodes a file bitmap
decode_unix_privs (privs): Decodes the UnixPrivileges.ua_permissions value
Dir (self, str_path, options, depth, parent): List the contents of a directory
DirTree (self, str_path, options): Displays a directory tree
dsi_close_session (self): Sends an DSICloseSession request to the server and handles the response
dsi_open_session (self, host, port): Sends an DSIOpenSession request to the server and handles the response
fp_close_fork (self, fork): FPCloseFork
fp_close_vol (self, volume_id): Sends an FPCloseVol request to the server and handles the response
fp_create_dir (self, vol_id, dir_id, path): FPCreateDir
fp_create_file (self, flag, vol_id, did, path): FPCreateFile
fp_enumerate_ext2 (self, volume_id, did, file_bitmap, dir_bitmap, req_count, start_index, reply_size, path): Sends an FPEnumerateExt2 request to the server and handles the response
fp_get_file_dir_parms (self, volume_id, did, file_bitmap, dir_bitmap, path): Sends an FPGetFileDirParms request to the server and handles the response
fp_get_server_info (self): Sends an GetStatus DSI request (which is basically a FPGetSrvrInfo AFP request) to the server and handles the response
fp_get_srvr_parms (self): Sends an FPGetSrvrParms AFP request to the server and handles the response
fp_get_user_info (self): Sends an FPGetUserInfo AFP request to the server and handles the response
fp_login (self, afp_version, uam, username, password, options): Sends an FPLogin request to the server and handles the response
fp_map_id (self, subfunc, id): FPMapId
fp_map_name (self, subfunc, name): FPMapName
fp_open_fork (self, flag, volume_id, did, file_bitmap, access_mode, path): Sends an FPOpenFork request to the server and handles the response
fp_open_vol (self, bitmap, volume_name): Sends an FPOpenVol request to the server and handles the response
fp_read_ext (self, fork, offset, count): FPReadExt
fp_write_ext (self, flag, fork, offset, count, fdata): FPWriteExt
getErrorCode (self): Gets the error code
getErrorMessage (self): Gets the error message
GetFileDates (self, vol_name, str_path): Returns the creation, modification and backup dates of a file
GetFileSize (self, vol_name, str_path): Gets the Unix permissions of a file
GetFileUnixPermissions (self, vol_name, str_path): Gets the Unix permissions of a file
getPacketData (self): Gets the packet data
getPacketHeader (self): Gets the packet header
getResult (self): Get the result
GetSharePermissions (self, vol_name): Determine the sharepoint permissions
GIDToName (self, gid): Maps a group id (gid) to group name
ListShares (self): List the AFP sharepoints
Login (self, username, password, options): Logs in to an AFP service
Logout (self): Logs out from the AFP service
NameToUID (self, name): Maps a username to a UID
new (self, o): Creates a new helper object
OpenSession (self, host, port): Connects to the remote server and establishes a new AFP session
parse_fp_header (self, packet): Parses the FP header (first 16-bytes of packet)
read_fp_packet (self): Reads a AFP packet of the socket
ReadFile (self, str_path): Reads a file on the AFP server
send_fp_packet (self, packet): Sends the raw packet over the socket
setErrorCode (self, code): Sets the error code
setErrorMessage (self, msg): Sets the error message
setPacket (self, packet): Sets the packet
setResult (self, result): Sets the result
SplitPath (str_path): Splits a path into two pieces, directory and file
Terminate (self): Terminates the connection, without closing the AFP session
time_to_string (timestamp): Converts AFP file timestamp to a standard text format
UIDToName (self, uid): Maps a user id (uid) to a user name
WalkDirTree (self, str_path): Walks the directory tree specified by str_path and returns the node information
WriteFile (self, str_path, fdata): Writes a file to the AFP server
ZeroPad (str, len): Pads a string with zeroes

Functions

acl_group_to_long_string (acls)

Converts a group bitmask of Search, Read and Write to table

Parameters

acls: number containing bitmasked acls

Return value:

table of ACLs

acls_to_long_string (acls)

Converts a numeric acl to string

Parameters

acls: number containing acls as received from fp_get_file_dir_parms

Return value:

table of long ACLs

CloseSession (self)

Closes the AFP session and then the socket

Parameters

self

Return values:

status boolean
string containing error message (if status is false)

create_fp_packet (self, command, data_offset, data)

Creates an AFP packet

Parameters

self
command: number should be one of the commands in the COMMAND table
data_offset: number holding the offset to the data
data: the actual data of the request

CreateDir (self, str_path)

Creates a new directory on the AFP sharepoint

Parameters

self
str_path: containing the sharepoint and the directory

Return values:

status boolean true on success, false on failure
dirId number containing the new directory id

decode_dir_bitmap (bitmap, data, pos)

Decodes a directory bitmap

Parameters

bitmap: number containing the bitmap
data: string containing the data to be decoded
pos: number containing the offset into data

Return values:

pos number containing the new offset after decoding
dir table containing the decoded values

decode_file_bitmap (bitmap, data, pos)

Decodes a file bitmap

Parameters

bitmap: number containing the bitmap
data: string containing the data to be decoded
pos: number containing the offset into data

Return values:

pos number containing the new offset after decoding
file table containing the decoded values

decode_unix_privs (privs)

Decodes the UnixPrivileges.ua_permissions value

Parameters

privs: number containing the UnixPrivileges.ua_permissions value

Return value:

string containing the ACL characters

Dir (self, str_path, options, depth, parent)

List the contents of a directory

Parameters

self
str_path: string containing the sharepoint and directory names
options: table options containing zero or more of the options max_depth and dironly
depth: number containing the current depth (used when called recursively)
parent: table containing information about the parent object (used when called recursively)

Return values:

status boolean true on success, false on failure
dir table containing a table for each directory item with the following: type, name, id, fsize, uid, gid, privs, create, modify

DirTree (self, str_path, options)

Displays a directory tree

Parameters

self
str_path: string containing the sharepoint and the directory
options: table options containing zero or more of the options max_depth and dironly

Return value:

dirtree table containing the directories

dsi_close_session (self)

Sends an DSICloseSession request to the server and handles the response

Parameters

self

dsi_open_session (self, host, port)

Sends an DSIOpenSession request to the server and handles the response

Parameters

self
host
port

Return value:

Response object

fp_close_fork (self, fork)

FPCloseFork

Parameters

self
fork: number containing the fork to close

Return value:

response object

fp_close_vol (self, volume_id)

Sends an FPCloseVol request to the server and handles the response

Parameters

self
volume_id: number containing the id of the volume to close

Return value:

response object

fp_create_dir (self, vol_id, dir_id, path)

FPCreateDir

Parameters

self
vol_id: number containing the volume id
dir_id: number containing the directory id
path: table containing the name and name encoding type of the directory to query

Return value:

response object

fp_create_file (self, flag, vol_id, did, path)

FPCreateFile

Parameters

self
flag: number where 0 indicates a soft create and 1 indicates a hard create.
vol_id: number containing the volume id
did: number containing the ancestor directory id
path: string containing the path, including the volume, path and file name

Return value:

response object

fp_enumerate_ext2 (self, volume_id, did, file_bitmap, dir_bitmap, req_count, start_index, reply_size, path)

Sends an FPEnumerateExt2 request to the server and handles the response

Parameters

self
volume_id: number containing the id of the volume to query
did: number containing the id of the directory to query
file_bitmap: number bitmask of file information to query
dir_bitmap: number bitmask of directory information to query
req_count: number
start_index: number
reply_size: number
path: table containing the name and the name encoding type of the directory to query

Return value:

response object with the following result set to a table of tables containing file_bitmap, dir_bitmap, req_count fields

fp_get_file_dir_parms (self, volume_id, did, file_bitmap, dir_bitmap, path)

Sends an FPGetFileDirParms request to the server and handles the response

Parameters

self
volume_id: number containing the id of the volume to query
did: number containing the id of the directory to query
file_bitmap: number bitmask of file information to query
dir_bitmap: number bitmask of directory information to query
path: table containing the name and the name encoding type of the directory to query

Return value:

response object with the following result file_bitmap, dir_bitmap, file_type and (dir<code> or <code>file tables) depending on whether did is a file or directory

fp_get_server_info (self)

Sends an GetStatus DSI request (which is basically a FPGetSrvrInfo AFP request) to the server and handles the response

Parameters

self

Return values:

status (true or false)
table with server information (if status is true) or error string (if status is false)

fp_get_srvr_parms (self)

Sends an FPGetSrvrParms AFP request to the server and handles the response

Parameters

self

Return value:

response object with the following result server_time, vol_count, volumes fields

fp_get_user_info (self)

Sends an FPGetUserInfo AFP request to the server and handles the response

Parameters

self

Return value:

response object with the following result user_bitmap and uid fields

fp_login (self, afp_version, uam, username, password, options)

Sends an FPLogin request to the server and handles the response

This function currently only supports the 3.1 through 3.3 protocol versions It currently supports the following authentication methods: o No User Authent o DHCAST128

The DHCAST128 UAM should work against most servers even though it's superceded by the DHX2 UAM.

Parameters

self
afp_version: string (AFP3.3|AFP3.2|AFP3.1)
uam: string containing authentication information
username
password
options

Return value:

Response object

fp_map_id (self, subfunc, id)

FPMapId

Parameters

self
subfunc: number containing the subfunction to call
id: number containing th id to translate

Return value:

response object with the id in the result field

fp_map_name (self, subfunc, name)

FPMapName

Parameters

self
subfunc: number containing the subfunction to call
name: string containing name to map

Return value:

response object with the mapped name in the result field

fp_open_fork (self, flag, volume_id, did, file_bitmap, access_mode, path)

Sends an FPOpenFork request to the server and handles the response

Parameters

self
flag: number
volume_id: number containing the id of the volume to query
did: number containing the id of the directory to query
file_bitmap: number bitmask of file information to query
access_mode: number containing bitmask of options from ACCESS_MODE
path: string containing the name of the directory to query

Return value:

response object with the following result contents file_bitmap and fork_id

fp_open_vol (self, bitmap, volume_name)

Sends an FPOpenVol request to the server and handles the response

Parameters

self
bitmap: number bitmask of volume information to request
volume_name: string containing the volume name to query

Return value:

response object with the following result bitmap and volume_id fields

fp_read_ext (self, fork, offset, count)

FPReadExt

Parameters

self
fork: number containing the open fork
offset: number containing the offset from where writing should start. Negative value indicates offset from the end of the fork
count: number containing the number of bytes to be written

Return value:

response object

fp_write_ext (self, flag, fork, offset, count, fdata)

FPWriteExt

Parameters

self
flag: number indicates whether Offset is relative to the beginning or end of the fork.
fork: number containing the open fork
offset: number containing the offset from where writing should start. Negative value indicates offset from the end of the fork
count: number containing the number of bytes to be written
fdata: string containing the data to be written

Return value:

response object

getErrorCode (self)

Gets the error code

Parameters

self

Return value:

code number containing the error code

getErrorMessage (self)

Gets the error message

Parameters

self

Return value:

msg string containing the error

GetFileDates (self, vol_name, str_path)

Returns the creation, modification and backup dates of a file

Parameters

self
vol_name: string containing the name of the volume
str_path: string containing the name of the file

Return values:

status true on success, false on failure
dates table containing the following fields: create - Creation date of the file modify - Modification date of the file backup - Date of last backup
err string (on failure) containing the error message

GetFileSize (self, vol_name, str_path)

Gets the Unix permissions of a file

Parameters

self
vol_name: string containing the name of the volume
str_path: string containing the name of the file

Return values:

status true on success, false on failure
size containing the size of the file in bytes
err string (on failure) containing the error message

GetFileUnixPermissions (self, vol_name, str_path)

Gets the Unix permissions of a file

Parameters

self
vol_name: string containing the name of the volume
str_path: string containing the name of the file

Return values:

status true on success, false on failure
acls table (on success) containing the following fields uid - a numeric user identifier gid - a numeric group identifier privs - a string value representing the permissions eg: drwx------
err string (on failure) containing the error message

getPacketData (self)

Gets the packet data

Parameters

self

getPacketHeader (self)

Gets the packet header

Parameters

self

getResult (self)

Get the result

Parameters

self

Return value:

result

GetSharePermissions (self, vol_name)

Determine the sharepoint permissions

Parameters

self
vol_name: string containing the name of the volume

Return values:

status boolean true on success, false on failure
acls table containing the volume acls as returned by acls_to_long_string

GIDToName (self, gid)

Maps a group id (gid) to group name

Parameters

self
gid: number containing the gid to lookup

Return values:

status boolean true on success, false on failure
groupname string on success error string on failure

ListShares (self)

List the AFP sharepoints

Parameters

self

Return value:

volumes table containing the sharepoints

Login (self, username, password, options)

Logs in to an AFP service

Parameters

self
username: (optional) string containing the username
password: (optional) string containing the user password
options: table containing additional options uam

Logout (self)

Logs out from the AFP service

Parameters

self

NameToUID (self, name)

Maps a username to a UID

Parameters

self
name: string containing the username to map to an UID

Return values:

status boolean true on success, false on failure
UID number on success error string on failure

new (self, o)

Creates a new helper object

Parameters

self
o

OpenSession (self, host, port)

Connects to the remote server and establishes a new AFP session

Parameters

self
host: table as received by the action function of the script
port: table as received by the action function of the script

Return values:

status boolean
string containing error message (if status is false)

parse_fp_header (self, packet)

Parses the FP header (first 16-bytes of packet)

Parameters

self
packet: string containing the raw packet

Return value:

table with header data containing flags, command, request_id, error_code, length and reserved fields

read_fp_packet (self)

Reads a AFP packet of the socket

Parameters

self

Return value:

Response object

ReadFile (self, str_path)

Reads a file on the AFP server

Parameters

self
str_path: string containing the AFP sharepoint, path and filename eg. HR/Documents/File.doc

Return values:

status boolean true on success, false on failure
content string containing the file contents

send_fp_packet (self, packet)

Sends the raw packet over the socket

Parameters

self
packet: containing the raw data

Return value:

Response object

setErrorCode (self, code)

Sets the error code

Parameters

self
code: number containing the error code

setErrorMessage (self, msg)

Sets the error message

Parameters

self
msg: string containing the error message

setPacket (self, packet)

Sets the packet

Parameters

self
packet

setResult (self, result)

Sets the result

Parameters

self
result: result to set

SplitPath (str_path)

Splits a path into two pieces, directory and file

Parameters

str_path: string containing the path to split

Return value:

dir table containing dir and file

Terminate (self)

Terminates the connection, without closing the AFP session

Parameters

self

Return values:

status (always true)
string (always "")

time_to_string (timestamp)

Converts AFP file timestamp to a standard text format

Parameters

timestamp: value returned by FPEnumerateExt2 or FPGetFileDirParms

Return value:

string representing the timestamp

UIDToName (self, uid)

Maps a user id (uid) to a user name

Parameters

self
uid: number containing the uid to resolve

Return values:

status boolean true on success, false on failure
username string on success error string on failure

WalkDirTree (self, str_path)

Walks the directory tree specified by str_path and returns the node information

Parameters

self
str_path: string containing the directory

Return values:

status boolean true on success, otherwise false
item table containing node information DirectoryId and DirectoryName

WriteFile (self, str_path, fdata)

Writes a file to the AFP server

Parameters

self
str_path: string containing the AFP sharepoint, path and filename eg. HR/Documents/File.doc
fdata: string containing the data to write to the file

Return values:

status boolean true on success, false on failure
error string containing error message if status is false

ZeroPad (str, len)

Pads a string with zeroes

Parameters

str: string containing the string to be padded
len: number containing the length of the new string

Return value:

str string containing the new string

Library afp

Script Arguments

Functions

Functions

Parameters

Return value:

Parameters

Return value:

Parameters

Return values:

Parameters

Parameters

Return values:

Parameters

Return values:

Parameters

Return values:

Parameters

Return value:

Parameters

Return values:

Parameters

Return value:

Parameters

Parameters

Return value:

Parameters

Return value:

Parameters

Return value:

Parameters

Return value:

Parameters

Return value:

Parameters

Return value:

Parameters

Return value:

Parameters

Return values:

Parameters

Return value:

Parameters

Return value:

Parameters

Return value:

Parameters

Return value:

Parameters

Return value:

Parameters

Return value:

Parameters

Return value:

Parameters

Return value:

Parameters

Return value:

Parameters

Return value:

Parameters

Return value:

Parameters

Return values:

Parameters

Return values:

Parameters

Return values:

Parameters

Parameters

Parameters

Return value:

Parameters

Return values:

Parameters

Return values:

Parameters

Return value:

Parameters

Parameters

Library `afp`