<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
 -  
 -  This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
 -  project.
 -  
 -  Copyright (C) 1998-2018 OpenLink Software
 -  
 -  This project is free software; you can redistribute it and/or modify it
 -  under the terms of the GNU General Public License as published by the
 -  Free Software Foundation; only version 2 of the License, dated June 1991.
 -  
 -  This program is distributed in the hope that it will be useful, but
 -  WITHOUT ANY WARRANTY; without even the implied warranty of
 -  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 -  General Public License for more details.
 -  
 -  You should have received a copy of the GNU General Public License along
 -  with this program; if not, write to the Free Software Foundation, Inc.,
 -  51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 -  
 -  
-->
<sect1 id="mime"><title>MIME &amp; Internet Messages</title>

 <sect2 id="aboutinternetmsgs"><title>About Simple Internet (RFC 822) Messages</title>

<para>RFC 822 messages have two major parts: </para>

<itemizedlist>
  <listitem><formalpara><title>Message envelope</title>
    <para>The message envelope contains all the information needed to accomplish
    transmission and delivery of the message. This information includes the e-mail
    address of the message's creator  also known as the originator. This string
    matches the information in the Sender: header, if this header is present.
    The envelope is created by a user agent (such as MS Outlook) and is meaningful
    only to the message transfer agents (MTAs) that move the message on the path
    to its destination. </para></formalpara></listitem>
  <listitem><formalpara><title>Message contents</title>
    <para>The contents make up the object to be delivered to the recipient.
    Message contents consist of lines of ASCII text. This text is arranged in the
    classic "memo" format, in which the message contains one or more introductory
    headers and a body. </para></formalpara></listitem>
</itemizedlist>

<para>This structure can be seen in the following illustration:</para>

	<figure id="internetmailmsg" float="1">
		<title>The structure of an Internet mail</title>
		<graphic fileref="internetmailmsg.jpg" />
	</figure>

<example id="ex_simplemailmsg"><title>Simple Internet Mail Message</title>

<para>As you can see in the following sample of a message's contents,
the format described in RFC 822 produces messages readable with little
difficulty by humans. </para>

<para>The first few lines, from the first instance of "Received" to "Precedence",
are headers. These lines define the recipients, the sender, the date,
and other information involved with message transmission.</para>

<para>Following the headers is a blank line. This is marked by the consecutive
occurrence of the four characters: CR, LF, CR, LF. After this blank line
starts the body of the message. In the following example, only the final few
lines make up the message body.</para>

<programlisting><![CDATA[
Received: from techsupp@openlinksw.co.uk
Message-Id: <v1214040cad6a13935723@>
Mime-Version: 1.0
Content-Type: text/plain; charset="us-ascii"
Date: Mon, 4 Jun 1998 09:43:14 -0800
To: customer.services@openlinksw.co.uk
From: OpenLink Technical Support <techsupp@openlinksw.co.uk>
Subject: Happy Reading
Precedence: bulk

Hope you are enjoying this chapter,
Technical Support
]]></programlisting>
</example>

<tip><title>See Also:</title>
<para><ulink url="http://www.rfc-editor.org/rfc/rfc822.txt">RFC 822 at www.rfc-editor.org</ulink></para></tip>

  </sect2>

	<sect2 id="mimesupport">
		<title>MIME Messages - Extension to Simple Internet Messages</title>

  <para>MIME (Multipurpose Internet Mail Extensions) grew out of a need to
  encapsulate messages within messages. It includes multipart messages
  comprising a variety of file types such as images, audio, and video.
  MIME does all this while following all the standard SMTP and RFC 822 mail rules.
  MIME messages can be constructed to transport mail over any mail transport
  system that is compliant with SMTP. MIME is able to transmit objects with
  varying ranges of complexity in a way that allows any MIME-compliant user
  agent (UA) to faithfully process them  and hand them off to an appropriate
  application.  The multiple parts are arranged so that the parts requiring the
  least sophisticated UA are at the beginning of the message.  In fact, most
  MIME UAs include courtesy text when constructing messages to give users
  of non-MIME UAs an indication of the message content. This courtesy text is
  inserted ahead of any MIME parts.</para>

  <para>MIME is consistent with Internet mail protocols using headers and
  bodies.  It allows for transmission of 7-bit printable US-ASCII characters and
  maximum 1000-character lines in message bodies over all Internet mail
  transports.  It has become the most widely used extension to the simple
  e-mail standard.  It is also used as a transport mechanism in Web pages.</para>

  <para>Each content body part is made up of header fields and content.
  The headers convey specific information about the content for the message
  recipient. The content can be essentially any serialized stream of bytes, such as
  binary data or HTML.  When necessary, the content is encoded so that the
  entire body complies with RFC 822. If the content is encoded, MIME defines
  the header Content-Transfer-Encoding to specify the mechanism.  Other
  details are sometimes included, such as the Content-Disposition, which
  indicates to the recipient whether the content is to be treated simply as an
  attachment, or whether it is to be rendered inline with other content in other
  body parts.</para>

  <example id="ex_mime1"><title>A simple MIME message sample</title>
  <para>Mime message including a picture stored as a file GIF format.
  Because .gif files use 8-bit bytes, and the RFC 822 format requires messages
  to contain only US-ASCII text, the picture data must be encoded. For the
  recipient to correctly decode and display the picture, it needs information
  about which encoding mechanism was used. The following example shows part
  of a MIME header that identifies that the content is a .gif file, that it is
  encoded using the standard base64 algorithm, and that it is to be treated by
  the e-mail client as an attachment.</para>
  <programlisting><![CDATA[
Content-Type: image/gif;
     name="picture.gif"
Content-Transfer-Encoding: base64
Content-Disposition: attachment;
     filename="picture.gif"

[encoded content here]
...
]]></programlisting>
  </example>

  <para>MIME accomplishes this simplifying and rebuilding of complex files by encoding a
  file and transporting it as a message body, or a series of messages with
  component parts of the file. A MIME-compliant
  user agent (UA) on the receiving end can decode the message, presenting it
  to the reader or providing it to another application as a file. A UA that is not
  MIME-compliant will be able to process a MIME-encoded mail message, but
  may not be able to decode the message. </para>

  <para>MIME defines a message format that allows for: </para>

  <simplelist>
   <member>Textual message bodies in character sets other than US-ASCII. </member>
   <member>Non-textual message bodies. </member>
   <member>Multipart message bodies. </member>
   <member>Textual header information in character sets other than US-ASCII. </member>
  </simplelist>

<example id="ex_samplemimemesg"><title>Sample MIME Message</title>
<para>MIME uses headers and separators to tell a UA what processing is
required to re-create the message. An example with no encoded body parts is:</para>

<programlisting><![CDATA[
From: OpenLink Support <techsupp@openlinksw.co.uk>
MIME-Version: 1.0
Content-Type: multipart/mixed;
        boundary="XXXXboundary text"

This is a multipart message in MIME format.

--XXXXboundary text
Content-Type: text/plain

here is the body text

--XXXXboundary text
Content-Type: text/plain;
Content-Disposition: attachment;
        filename="test.txt"

this is the attachment text

--XXXXboundary text--
]]></programlisting>

<para>This example shows the use of a MIME message to send a text message
and an attached text file. Both are body parts of this message. </para>

<para>The "MIME-Version:" header tells the receiving UA to treat this as a MIME message. </para>

<para>The "Content-Type:" header specifies "multipart/mixed". This tells the
receiving UA that this message has parts separated by the string argument
defined in "boundary=".  A MIME-compliant UA will only display or otherwise process
content following the specified "boundary=" text strings. The actual
boundaries are constructed using the "boundary=" string, prepended by "--".
The final body part is followed by the "boundary=" string with the "--" both
prepended and appended.</para>

<para>In the preceding example, the courtesy message "This is a multipart
message in MIME format." will not be displayed or otherwise processed by the
MIME UA since it does not follow a "boundary=" string. A UA that does not support
MIME will display it, and at least this part of the message will be readable
no matter what features the reader supports. If our example had encoded
parts, they would make no sense to the human reader using a
non-MIME-compliant UA, but at least the courtesy message would give the
user a hint as to why.</para>

<para>There are two message body parts in our example.  Each body part
has headers of its own, in addition to the overall message headers.  Each
body-part begins with the boundary string.  If there were no headers in the
body parts, then the blank line that must follow headers in RFC 822 messages
would follow the boundary string. The first body part is a plain text message.
It is the message the sender might have typed into a UA. Its single
"Content-Type:" header identifies it as "text/plain", meaning US-ASCII
characters are used exclusively and any UA should be able to display this
body part. Text/plain is the default content type.</para>

<para>The second body part in this example contains the file attachment.
Since the file attachment is an ASCII text file, it is sent with no encoding and
its content-type is given as text/plain. The "Content-Disposition: attachment"
header has an attribute, "filename=", which specifies a suggested name for the
file. This header specifies that this body part is to be treated as a file rather
than being displayed to the user and is to be saved on local storage
under the suggested file name.</para>
</example>

<sect3 id="mimeheaders"><title>MIME Headers</title>

<para>MIME headers appear at the beginning of a MIME message as well as
within the separate body parts. Some MIME headers can be used both as
message headers and in MIME body parts. Some additional headers are defined
for use only in body parts.</para>

<para>The following headers are defined in MIME: </para>

<itemizedlist>
 <listitem><formalpara><title>MIME-Version </title>
   <para>Required header indicating that this message is to use the rules of
   MIME. "MIME-Version: 1.0" is the only currently defined MIME-Version
   header allowed. The MIME-Version header is a top-level header only and
   does not appear in body parts unless the body part is an encapsulated,
   fully formed message of content-type message/rfc822, which might
   have its own MIME-Version header.
   </para></formalpara></listitem>
 <listitem><formalpara><title>Content-Type </title>
   <para>Content-Type headers are used to specify the media type and subtype
   of data in the body of a message and to fully specify the native representation
   of such data. This header embodies much of the power of MIME. The IETF
   can add new official content types. Additionally, private content-type values
   can be defined by anyone. Such private content types have values of
   "x-something" or "X-something", where "something" can take on any value.
   </para></formalpara></listitem>
 <listitem><formalpara><title>Content-Transfer-Encoding </title>
   <para>Content-Transfer-Encoding headers can have two different meanings.
   If the value is "base64" or "quoted-printable", then the header indicates the
   encoding used for this body part. If the value is "7bit", "8bit", or "binary",
   then the header indicates that there is no encoding and that this value indicates
   only the type of content this body part contains. The default is "7bit". It should
   be noted that "8bit" and "binary" are not guaranteed to  be properly handled by all Internet (SMTP) MTAs valid in Internet mail.
   Eight bit content is not valid in Internet mail headers.
   Provision is made for private Content-Transfer-Encoding headers. These have values that
   begin with "x-" or "X-". These are for specialized cases where the users have
   the tools to decode or otherwise process a specific "x-" encoding.
   </para></formalpara></listitem>
 <listitem><formalpara><title>Content-ID </title>
   <para>Content-ID headers are world-unique values that identify body
   parts, individually or as groups. They are necessary at times to
   distinguish body parts and allow cross-referencing between body parts.
   </para></formalpara></listitem>
 <listitem><formalpara><title>Content-Description </title>
   <para>Content-Description headers are optional and are often used to
   add descriptive text to non-textual body parts.
   </para></formalpara></listitem>
 <listitem><formalpara><title>Content-Disposition </title>
   <para>Content-Disposition headers provide information about how to present
   a message or a body part. When a body part is to be treated as an attached file,
   the Content-Disposition header will include a file name attribute.
   </para></formalpara></listitem>
</itemizedlist>

<para>There are additional headers that are applied in specialized situations,
such as Content-Base and Content-Location. All of the "Content-xxx" headers
have defined sub-headers, fields, and/or attributes. Headers that begin
with "Content-" are the only headers that have defined meaning in body parts.
All other body part headers can be ignored and might actually be removed by
message transfer agents (MTAs).</para>
</sect3>

		<sect3 id="mimetree">
		<title>MIME_TREE - MIME parser</title>

&mime_tree;

	</sect3>
	<!-- ### ~~~~ #### ~~~~ #### ~~~~ ### -->
	<sect3 id="mimemultipart">
		<title>Processing HTTP PUT of type &quot;multipart/form-data&quot;</title>
		<para>
When the Virtuoso server receives a PUT request of type &quot;multipart/form-data&quot;
from the client agent, then it passes the HTTP text to the MIME_TREE function internally
and adds any MIME subpart as an element pair (&quot;name&quot;, &quot;value&quot;)
of the &quot;params&quot; parameter of the vsp page being specified in the URI.
It also adds an additional &quot;params&quot; pair for each HTTP request MIME part
named &quot;attr-name&quot; and whose value is an array of all MIME header fields of that part.
</para>
		<example id="mime002">
			<title>Example:</title>
			<para>
Consider the following HTTP request:
</para>
			<programlisting>
PUT handler.vsp
Content-Type: &quot;multipart/form-data&quot;; boundary=&quot;--end_part&quot;

----end_part
Content-Type: image/gif
Content-Disposition: form-data; name=upload_control; filename=&quot;some image.gif&quot;

GIF...
----end_part
Content-Type: text/plain
Content-Disposition: form-data; name=textarea

The description
----end_part--
</programlisting>
			<para>
Virtuoso parses that and produces the following params content when calling handler.vsp:
</para>
			<programlisting>
( &quot;upload_control&quot;, &quot;GIF....&quot;,
  &quot;attr-upload_control&quot;, ( &quot;Content-Type&quot;, &quot;image/gif&quot;,
		&quot;Content-Disposition&quot;, &quot;form-data&quot;, &quot;name&quot;,
		&quot;upload_control&quot;, &quot;filename&quot;, &quot;some image.gif&quot;),
  &quot;textarea&quot;, &quot;The description&quot;,
  &quot;attr-textarea&quot;, (&quot;Content-Type&quot;, &quot;text/plain&quot;,
		&quot;Content-Disposition&quot;, &quot;form-data&quot;, &quot;name&quot;,
		&quot;textarea&quot;)
)
</programlisting>
		</example>
		<para>
This allows for vsp&apos;s to handle uniformly &quot;x-www-form/url-encoded&quot; and
&quot;multipart/form-data&quot; PUTS and to have full access to the MIME headers if needed.
</para>
	</sect3>
</sect2>

<sect2 id="smime"><title>S/MIME Support</title>

  <para>S/MIME is a specification for secure electronic mail. S/MIME stands for
  Secure/Multipurpose Internet Mail Extensions and was designed to add security
  to e-mail messages in MIME format. The security services offered are
  authentication (using digital signatures) and privacy (using encryption).</para>

  <para>The S/MIME specification consists of two documents:
  <ulink url="http://www.rfc-editor.org/rfc/rfc2311">S/MIME Message Specification (RFC 2311)</ulink> and
  <ulink url="http://www.rfc-editor.org/rfc/rfc2312">S/MIME Certificate Handling (RFC 2312)</ulink>.
  Both of these are Internet Drafts.  The S/MIME community has submitted these
  to the IETF.  The goal is to form a working group and produce an Internet
  standard.</para>

  <para>All certificates and private keys are read and stored as PEM encoded
  strings.  If the server is compiled without SSL support then dummy versions
  of smime_sign, smime_verify, pem_certificates_to_array and get_certificate_info
  are available so that existing SQL code would not be broken.  Currently the
  Virtuoso server supports S/MIME signing and S/MIME signature verification.
  These are done through the following 2 functions:</para>

  <para><link linkend="fn_smime_verify"><function>smime_verify()</function></link></para>

  <para><link linkend="fn_smime_sign"><function>smime_sign()</function></link></para>

  <para>A useful utility function for S/MIME support is:</para>

  <para><link linkend="fn_pem_certificates_to_array"><function>pem_certificates_to_array()</function></link></para>

</sect2>

</sect1>