This is the proposal I have written the last couple of days with help
from a great group of people. They who have helped me are:
Dave Crocker, Steve Dorner, Erik E. Fair, David Gelhar, David Herron,
Raymond Lau, John B. Melby and Rens Troost
Please come with suggestions for changes, to me or to the list.
My email address is paf(_at_)nada(_dot_)kth(_dot_)se(_dot_)
Patrik Faltstrom
----cut here---------
MacMIME - a specification on how to
send Macintosh files with MIME
Thu Feb 25 17:52:08 1993
Patrik Faeltstroem
Department of Numerical Analysis and Computing Science
Royal Institute of Technology
paf(_at_)nada(_dot_)kth(_dot_)se
1. Status of this Memo
This draft document will be submitted to the Internet Activities
Board as a standards document. As this is a working document only,
it should neither be cited nor quoted in any formal document.
Distribution of this memo is unlimited. Please send comments to
ietf-822(_at_)dimacs(_dot_)rutgers(_dot_)edu(_dot_)
2. Abstract
This memo describes how to specify a message format defined in
RFC-1341 [1], to allow the transportation of Macintosh files. The
solution proposed is designed to be highly compatible with already
existing ways of distibuting Macintosh files, and to be easily
implemented in mail readers that support RFC-1341.
3. Introduction
The files on the Macintosh is stored in two parts, or forks:
DATA:
The actual data included in the file. It's a series of
consecutive bytes of data, often seen as corresponding
to an entire file in other operating systems.
RESOURCE:
If the file is an application, the resource fork contains
the actual code executed among some other resources
describing the applications menus, icons and dialog boxes.
Besides these two, there is some additional information which the
finder has in it's "Desktop Database", and this info can sometimes
be regarded as a third part of the file.
Because of the lack of possibilities of storing different parts of
the same file in a filesystem that only handles consecutive data in
one part, it is common to pack, or convert, the Macintosh file into
some other format before moving the file over the network.
Formats accepted is:
AppleSingle [2] - A representation of Macintosh files in one
consecutive stream of bytes, invented and
used by Apple (see appendix A).
AppleDouble [2] - A special version of AppleSingle where the Data
fork of the document is separated from the
other parts included in AppleSingle (see appendix A).
BinHex - A representation used in a very large
community. However, the BinHex encoding should
not be used. It is defined and accepted just
for backword compatibility (see point 6 and
appendix B).
4. Syntax
This document describes some additional subtypes of the types
listed in RFC-1341.
The new subtypes added are:
multipart/appledouble Part 5.1
application/appledoubleheader Part 5.1
application/applesingle Part 5.2
Because of backword compatibility with non-MIME aware mail programs
it's also described a subtype for the very wide-spread encoding of
Macintosh files, BinHex4.0.
application/binhex Part 7.1
5. Representation
5.1 AppleDouble
The Content-Type Multipart/AppleDouble describes that the mail
consists of an AppleDouble, version two, file which is devided in
two parts, a header and a Data block, which follows the description
in "AppleSingle/AppleDouble Formats for Foreign Files Developer's
Note" [2]. The header is sent as "application/AppleDoubleHeader"
and the data fork as whatever best describes it.
AppleDouble is special case of AppleSingle. The Data fork of the
Macintosh file is extracted from the AppleSingle file and is stored
separately.
The AppleDouble header is binary data. Hence, it may be necessary
to perform a Content-Tranfer-Encoding for transmission. The safest
encoding is Base64, since it permits transfer over the most limited
media. Even the Data fork of the file might need transportation
encoding for tranmission.
5.2 AppleDouble example
Content-Type: multipart/AppleDouble, boundrary=mac-part
--mac-part
Content-Type: Application/AppleDoubleHeader
[The AppleDouble header follows]
--mac-part
Content-Type: [whatever best describes the contents of the Data fork]
[The Data fork of the file follows]
--mac-part
5.3 AppleSingle
The Content-Type Application/AppleSingle describes that the body
of the mail is an AppleSingle, version two, file which follows the
description in "AppleSingle/AppleDouble Formats for Foreign Files
Developer's Note" [2]. The one and only part of the file is sent in
a "Application/AppleSingle" message.
The AppleSingle file is binary data. Hence, it may be necessary
to perform a Content-Tranfer-Encoding for transmission. The safest
encoding is Base64, since it permits transfer over the most limited
media.
5.4 AppleSingle example
Content-Type: Application/AppleSingle
[The AppleSingle file follows]
6. Example of a mailcap [3] entry
If one uses the Mailcap configuration scheme described in RFC-1343
[3], an entry in the Mailcap file on a UNIX computer might look
like:
application/applesingle; save_mac_file %s %{NAME}
If you have that type of entry, you must also have a script
named save_mac_file which looks something like:
#!/bin/sh
if [ "x$2" = "x" ]; then
DEFAULT=$HOME/Mac_File
else
DEFAULT=$HOME/$2
fi
echo -n "Save Macintosh file as [" $DEFAULT "]:"
read FILENAME
if [ "x$FILENAME" = "x" ]; then
FILENAME=$DEFAULT
fi
/bin/mv $1 $FILENAME
7. Problems at the transition phase
7.1 Anout the BinHex encoding
A very widely spread way of sending Macintosh files with electronic
mail is to encode the Macintosh file with the BinHex4.0 encoding
(see appendix B for a brief description of the BinHex4.0 format).
To help the transition phase from sending BinHex4.0 files, to this
MacMIME specification where you send either AppleSingle or
AppleDouble files encoded in some transport encoding (Base64 or
Quoted-Printable), we also define an application subtype named
BinHex.
However, it is strongly recommended NOT to use the BinHex format.
The only advantage with the BinHex encoding, is that recievers
which use non-MIME-aware mailers have a chance to get an encoded
Macintosh file, which he can move to his Macintosh and unpack the
file with some program. That will work if and only if the transport
layer, i.e. the mailer(s) used, does not alter the representation
of the 64 characters used in BinHex. The characters used is NOT the
same as those regarded as safe according to RFC-1341, so a
transport encoding with Quoted-Printable should in fact be done if
you follow this RFC. But, if you do a transport encoding, you loose
the one and only advantage with the BinHex encoding.
The goal is to replace the BinHex encoding with Base64 encoded
AppleSingle.
7.2 BinHex
The Content-Type Application/BinHex describes that the body of the
mail is a BinHex4.0 file which follows the description in appendix
B. Even though the BinHex encoding consists of characters which are not
the same as those used in Base64 (those regarded as safe according
to RFC-1341) a transportation encoding should not be done.
The BinHex encoding should be replaced in a future of Base64
encoded AppleSingle files.
The one and only part of the file is sent in a "Application/BinHex"
message.
7.3 BinHex example
Content-Type: Application/BinHex
[The BinHex4.0 file which is NOT encoded follows]
8. References
[1] Borenstein N., and N. Freed, "MIME (Multipurpose Internet Mail
Extensions): Mechanisms for Specifying and Describing the Format
of Internet Message Bodies", RFC 1341, Bellcore, Innosoft,
June 1992.
[2] AppleSingle/AppleDouble Formats for Foreign Files Developer's
Note, Apple Computer, Inc, 1990
[3] Borenstein N., "A User Agent Configuration Mechanism For
Multimedia Mail Format Information", RFC 1343, Bellcore, June 1992.
9. Security Considerations
Security issues are not discussed in this memo.
10. Acknowledgements
Thank's to all of the prople on the ietf-822 list who have come
with great input for this document.
Some of them must though be remembered by name, because they have
almost crushed my mailbox the last week with a very nice and
interesting debate.
Dave Crocker
Steve Dorner
Erik E. Fair
David Gelhar
David Herron
Raymond Lau
John B. Melby
Rens Troost
11. Author's Address
Patrik Faeltstroem
NADA, KTH
S-100 44 STOCKHOLM
SWEDEN
Email: paf(_at_)nada(_dot_)kth(_dot_)se
12. Appendix A: Specification of AppleSingle and AppleDouble formats
12.1 The AppleSingle format
In the AppleSingle format, a file's contents and attributes are
stored in a single file in the foraign file system. For example,
both forks of a Macintosh file, the Finder information, and an
associated comment are arranged in a single file with a simple
structure.
An AppleSingle file consists of a header followed by one or more
data entries. The header consists of several fixed fields and a
list of entry descriptors, each pointing to a data entry. Each
entry is optional and may or may not appear in the file.
AppleSinge file header:
Field Length
Magic number 4 bytes
Version number 4 bytes
Filler 16 bytes
Number of entries 2 bytes
Entry descriptor for each entry:
Entry ID 4 bytes
Offset 4 bytes
Length 4 bytes
Byte ordering in the file fields follows MC68000 conventions, most
significant byte first. The fields in the header file follow the
conventions described in the following sections.
Magic number
This field, modeled after the UNIX magic number feature, specifies
the file's format. Apple has defined the magic number for the
AppleSingle format as $00051600 or 0x0051600.
Version number
This field denotes the version of AppleSingle format in the event
the format evolves (more fields may be added to the header). The
version described in this note is version $00020000 or 0x00020000.
Filler
This field is all zeros ($00 or 0x00).
Number of entries
This field specifies how many different entries are included in the
file. It is an unsigned 16-bit number. If the number of entries is
any number other than 0, then that number of entry descriptors
immediately follows the number of entries field.
Entry descriptors
The entry descriptor is made up of the following three fields:
Entry ID - an unsigned 32-bit number, defines what entry is.
Entry IDs range from 1 to $FFFFFFFF. Entry ID 0 is
invalid.
Offset - an unsigned 32-bit number, shows the offset from the
beginning of the file to the beginning of the entry's
data.
Length - an unsigned 32-bit number, shows the length of the
data in bytes. The length can be 0.
Predefined entry ID's
Apple has defined a set of entry IDs and their values as follows:
Data Fork 1 Data fork
Resource Fork 2 Resource fork
Real Name 3 File's name as created on home file system
Comment 4 Standard Macintosh comment
Icon, B&W 5 Standard Macintosh black and white icon
Icon, Color 6 Macintosh color icon
File Dates Info 8 File creation date, modification date, and so on
Finder Info 9 Standard Macintosh Finder information
Macintosh File Info 10 Macintosh file information, attributes and so on
ProDOS File Info 11 ProDOS file information, attributes and so on
MS-DOS File Info 12 MS-DOS file information, attributes and so on
Short Name 13 AFP short name
AFP File Info 14 AFP file, information, attributes and so on
Directory ID 15 AFP directory ID
Apple reserves the range of entry IDs from 1 to $7FFFFFFF. The rest
of the range is available for applications to define their own
entries. Apple does not arbitrare the use of the rest of the range.
12.2 The AppleDouble format
The AppleDouble formatuses two files to store data, resources and
attributes. The AppleDouble Data file contains the data fork and
the AppleDouble Header file contains the resource fork.
The AppleDouble Data file contains the standard Macintosh data fork
with no additional header. The AppleDouble Header file has exactly
the same format as the AppleSingle file, except that it does not
contain a Data fork entry. The magic number in the AppleDouble
Header file differs from the magic number in the AppleSingle Header
file so that an application can tell whether it needs to look in
another file for the data fork. The magic number for the
AppleDouble format is $00051607 or 0x00051607.
The entries in the AppleDouble Header file can appear in any order;
however, since the resource fork is the entry that is most commonly
extended (after the data fork), Apple recommends that the resource
fork entry to be placed last in the file. The data fork is easily
extended because it resides by otself in the AppleDouble Data file.
13. Appendix B: Specification of the BinHex format
Here is a description of the Hqx7 (7 bit format as implemented in
BinHex 4.0) formats for Macintosh Application and File transfers.
The main features of the format are:
1) Error checking even using ASCII download
2) Compression of repetitive characters
3) 7 bit encoding for ASCII download
HQX Format Description (This is not intended to be a programmer's
reference).
The format is processed at three different levels:
1) 8 bit encoding of the file:
Byte: Length of FileName (1->63)
Bytes: FileName ("Length" bytes)
Byte: Version
Long: Type
Long: Creator
Word: Flags (And $F800)
Long: Length of Data Fork
Long: Length of Resource Fork
Word: CRC
Bytes: Data Fork ("Data Length" bytes)
Word: CRC
Bytes: Resource Fork ("Rsrc Length" bytes)
Word: CRC
2) Compression of repetitive characters.
($90 is the marker, encoding is made for 3->255 characters)
00 11 22 33 44 55 66 77 -> 00 11 22 33 44 55 66 77
11 22 22 22 22 22 22 33 -> 11 22 90 06 33
11 22 90 33 44 -> 11 22 90 00 33 44
3) 7 bit encoding.
The whole file is considered as a stream of bits. This stream will
be divided in blocks of 6 bits and then converted to one of 64
characters contained in a table. The characters in this table have
been chosen for maximum noise protection. The format will start
with a ":" (first character on a line) and end with a ":". There
will be a maximum of 64 characters on a line. It must be preceeded,
by this comment, starting in column 1 (it does not start in column
1 in this document):
(This file must be converted with BinHex 4.0)
Any text before this comment is to be ignored.
The characters used is:
!"#$%&'()*+,-012345689(_at_)ABCDEFGHIJKLMNPQRSTUVXYZ[`abcdefhijklmpqr