I have, together with a smaller part of the WG, been discussing this
for a couple of weeks. We now think it's timw for a discussion in
the whole WG, so this paper can be presented (hopefully) at the
next IETF meeting, at least be marked "as existing" or something.
I am also working on a FAQ on this subject, a summary of the arguments
we have had when composing this memo.
To be able to find the right answers to the right questions, don't
hesitate to send me any questions at all, technical or editorial.
There is also a Postscript as well as a Microsoft Word document
(1100kByte and 40kByte) which you can get by anonymous
ftp from paf-mac.nada.kth.se (130.237.222.197) in the folder "pub".
With regards
Patrik Faltstrom
NADA, KTH
Stockholm, Sweden
MacMIME - How to send Macintosh files with MIME
Sun Mar 14 22:07 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>.
2. Abstract
This memo describes how to specify a message format based on
RFC-1341 [1], to allow the transportation of Macintosh files.
The solution proposed is designed to be highly compatible
with existing mechanisms for distributing Macintosh files,
and it should be readily implementable in mail readers that
support RFC-1341.
3. Introduction
Files on the Macintosh consists of two parts, called forks:
DATA:
The actual data included in the file. This is a
series of consecutive bytes of data, often seen as
corresponding to an entire file in some other
operating systems.
RESOURCE:
Contains a collection of arbitrary attribute/value
pairs, including program segments, icon bitmaps,
and parametric values.
Besides these two, there is some additional information which
the Finder has in its "Desktop Database", and this info can
sometimes be regarded as a third part of the file.
Because of the lack of possibilities for 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 are:
AppleSingle [2] A representation of Macintosh files
as 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 widely used in the
Macintosh community. However, the BinHex
encoding should not be the primary format.
It is defined and accepted to provide
backward compatibility (see point 6 and
appendix B).
It might look strange to define three different formats, but
it isn't. All three formats has it's pros and it's cons.
The AppleDouble format should be the primary format when
sending a Macintosh document. It makes it possible for a user
that can't decode the AppleDouble header to read and use the
Data fork of the document. It also keep the Macintosh
specific information in the AppleDouble header, so a user who
can decode the AppleDouble header can get the extra in
formation, such as customised icons, which is not essential
to the document itself.
One disadvantage is though that the AppleDouble format is two
parallel streams of bytes. That means that a user who has to
create the MIME document by hand, or move and store the file
temporarily when creating the MIME message, has to handle two
files. If the receiver is known to have a Macintosh, or the
data is Macintosh specific (such as an application) it might
be more convenient to use the AppleSingle format. The
AppleSingle format is one stream of bytes only, but the
format is exactly the same as the AppleDouble header, so an
application that can decode the AppleDouble format should
also be able to decode the AppleSingle format.
But, neither AppleSingle nor AppleDouble does contain a CRC
(Cyclic Redundancy Code) which can help to detect
transmission errors. BinHex4.0 does contain such codes, both
for the Data and Resource fork. Also, the BinHex4.0 format is
one of the formats most widely used today on public file
servers when storing Macintosh files in printable ASCII
format. With that as a background, a subtype for the
BinHex4.0 format is defined. It should though only be used in
some special cases, for backward compatibility, and then only
as a replacement for the AppleSingle format, i.e. just for
sending Macintosh specific data, or to other Macintosh users.
Conclusion: The AppleDouble format should be the primary
format used, even though both AppleSingle and BinHex4.0 is
accepted. A minimal MacMIME-aware mail reader is able to
encode and decode the AppleSingle and Apple Double formats.
The BinHex4.0 format is to be recognised so the file can be
saved and later decoded with another program.
4. Syntax
This document describes some additional subtypes of the types
listed in RFC-1341.
The new subtypes added are:
application/applefile Part 5.1 and 5.2
multipart/appledouble Part 5.2
For backward compatibility with non-MIME aware mail programs
a subtype for the very wide-spread encoding of Macintosh
files, BinHex 4.0:
application/mac-binhex40 Part 7.1
5. Representation
5.1 AppleSingle
An AppleSingle, version 2 file, is sent as one consecutive
stream of bytes. The format is described in
"AppleSingle/AppleDouble Formats for Foreign Files
Developer's Note" [2]. The one and only part of the file is
sent in an application/applefile message.
The first four bytes of an AppleSingle header is, in
hexadecimal: 00, 05, 16, 00.
The AppleSingle file is binary data. Hence, it may be
necessary to perform a Content-Transfer-Encoding for
transmission. The safest encoding is Base64, since it permits
transfer over the most limited media.
An AppleSingle file includes the original Macintosh filename,
so the filename used when storing the file on a foreign
filesystem is of no importance. But, to give a hint to the
receiver what file is sent, a parameter called name can be
used. The value of this parameter must be in such character
set so it's accepted according to the rules in RFC-1341 [1].
The AppleSingle file also includes the original Macintosh
file type, but to give a hint to the receiver what type of
file is sent, a parameter called type can be used. The value
of this parameter should be human readable, and in such
character set so it's accepted according to the rules in RFC-
1341 [1].
5.2 AppleSingle example
Content-Type: application/applefile; name="New Computers
1/2 -93"; type="MSWord5.1a"
[The AppleSingle file follows (starts with, in
hexadecimal: 00051600)]
5.3 AppleDouble
An AppleDouble, version 2, file is divided in two parts, a
header and a data block. Both of these are described in
"AppleSingle/AppleDouble Formats for Foreign Files
Developer's Note" [2]. The AppleDouble file itself is sent as
a multipart/appledouble message, which is only allowed to
have two parts. The header is sent as application/applefile
and the data fork as whatever best describes it. For example
should a data part which is a GIF image be sent as image/gif.
If there is no content-type registered that is correct, the
data part should be sent as an application/octet-stream.
AppleDouble is special case of AppleSingle. The Data fork of
the Macintosh file is extracted from the AppleSingle file and
is stored separately. Therefore an implementation for
AppleSingle can also decode AppleDouble files.
The first four bytes of an AppleDouble header is, in
hexadecimal: 00, 05, 16, 07.
The AppleDouble header is binary data. Hence, it may be
necessary to perform a Content-Transfer-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 transmission.
An AppleDouble header file includes the original Macintosh
filename, so the filename used when storing the file on a
foreign filesystem is of no importance. The only thing that
might be of some importance is the naming scheme used to keep
the AppleDouble header file together with the data part. The
scheme used differs between different foreign file systems
and the rules is presented in "AppleSingle/AppleDouble
Formats for Foreign Files Developer's Note" [2]. An example
is that if the data file is named 'budget', the AppleDouble
header file should be named '%budget' on a UNIX filesystem.
To give a hint to the receiver what file is sent, a parameter
called name can be used. The value of this parameter must be
in such character set so it's accepted according to the rules
in RFC-1341 [1].
The AppleDouble header file also includes the original
Macintosh file type, but to give a hint to the receiver what
type of file is sent, a parameter called type can be used.
The value of this parameter should be human readable, and in
such character set so it's accepted according to the rules in
RFC-1341 [1]. This parameter is of great importance for the
data part of the AppleDouble file to help non-Macintosh
computers to extract the data. This scheme should be used on
the data part of the file only if there is no IANA registered
content-type for MIME that matches the Macintosh type. For
example, the Macintosh type 'GIFf' can be sent as a MIME
document with content type image/gif.
5.4 AppleDouble example
Content-Type: multipart/appledouble; boundary=mac-part
--mac-part
Content-Type: application/applefile; name="My-new-car";
type="GIF picture"
[The AppleDouble header follows (starts with, in
hexadecimal: 00051607)]
--mac-part
Content-Type: image/gif;
[The Data fork (which in this case is a GIF image)
follows]
--mac-part--
6. Problems at the transition phase
6.1 About 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 apple-binhex40.
It includes a CRC (Cyclic Redundancy Code) which can help
detecting transmission errors. To get a CRC on a message
which use the AppleSingle or AppleDouble format, you have to
use it on the message itself. That kind of functionality is
not discussed in this memo.
It is the most widely spread encoding scheme for a Macintosh
file, which make it possible for almost all Macintosh users
to decode a BinHex4.0 encoded file. The file can be saved as
a text file and decoded on a Macintosh. If a transportation
encoding is done, the receiver must be MIME-aware to get the
BinHex4.0 file. If not the receiver can receive the file and
decode it even if he is not MIME-aware.
The BinHex4.0 format should only be used as a replacement for
the AppleSingle format, i.e. it should only be used when
sending files to Macintosh users, or when sending Macintosh
specific data (a Macintosh application for example).
6.2 BinHex
The Content-Type application/mac-binhex40 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 one and only part of the file is sent in an
application/mac-binhex40 message.
A BinHex4.0 file includes the original Macintosh filename, so
the filename used when storing the file on a foreign
filesystem is of no importance. But, to give a hint to the
receiver what file is sent, a parameter called name can be
used. The value of this parameter must be in such character
set so it's accepted according to the rules in RFC-1341 [1].
6.3 BinHex example
Content-Type: application/mac-binhex40; name="car.hqx"
[The BinHex4.0 file which is NOT encoded follows]
7. 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
8. Security Considerations
Security issues are not discussed in this memo.
9. Acknowledgements
Thanks to all of the people 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 weeks 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
Peter Svanberg
10. Author's Address
Patrik Faeltstroem
Department of Numerical Analysis and Computing Science
Royal Institute of Technology
S-100 44 Stockholm
Sweden
Email: paf(_at_)nada(_dot_)kth(_dot_)se
11. Appendix A: AppleSingle and AppleDouble formats
11.1 The AppleSingle format
In the AppleSingle format, a file's contents and attributes
are stored in a single file in the foreign 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.
AppleSingle 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, modelled after the UNIX magic number feature,
specifies the file's format. Apple has defined the magic
number for the AppleSingle format as $00051600 or 0x00051600.
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, Colour 6 Macintosh colour 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 Info11 ProDOS file information, attributes
and so on
MS-DOS File Info12 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 arbitrate the use of the
rest of the range.
11.2 The AppleDouble format
The AppleDouble format uses two files to store data,
resources and attributes. The AppleDouble Data file contains
the data fork and the AppleDouble Header file contains the re
source 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 recom
mends that the resource fork entry to be placed last in the
file. The data fork is easily extended because it resides by
itself in the AppleDouble Data file.
12. Appendix B: 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 preceded, 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