Repository: swiftmailer/swiftmailer
Branch: master
Commit: 47a449111b9c
Files: 364
Total size: 3.7 MB

Directory structure:
gitextract_gp3ij5u3/

├── .gitattributes
├── .github/
│   ├── ISSUE_TEMPLATE.md
│   ├── PULL_REQUEST_TEMPLATE.md
│   └── workflows/
│       └── tests.yml
├── .gitignore
├── .php_cs.dist
├── CHANGES
├── LICENSE
├── README.md
├── composer.json
├── doc/
│   ├── headers.rst
│   ├── index.rst
│   ├── introduction.rst
│   ├── japanese.rst
│   ├── messages.rst
│   ├── notes/
│   │   ├── CHARSETS
│   │   ├── rfc/
│   │   │   ├── rfc0821.txt
│   │   │   ├── rfc0822.txt
│   │   │   ├── rfc1341.txt
│   │   │   ├── rfc1521.txt
│   │   │   ├── rfc1854.txt
│   │   │   ├── rfc2015.txt
│   │   │   ├── rfc2045.txt
│   │   │   ├── rfc2046.txt
│   │   │   ├── rfc2047.txt
│   │   │   ├── rfc2048.txt
│   │   │   ├── rfc2049.txt
│   │   │   ├── rfc2183.txt
│   │   │   ├── rfc2222.txt
│   │   │   ├── rfc2231.txt
│   │   │   ├── rfc2234.txt
│   │   │   ├── rfc2440.txt
│   │   │   ├── rfc2487.txt
│   │   │   ├── rfc2554.txt
│   │   │   ├── rfc2821.txt
│   │   │   ├── rfc2822.txt
│   │   │   ├── rfc3156.txt
│   │   │   ├── rfc3676.txt
│   │   │   ├── rfc4505.txt
│   │   │   ├── rfc4616.txt
│   │   │   ├── rfc4870.txt
│   │   │   ├── rfc4871.txt
│   │   │   ├── rfc4880.txt
│   │   │   ├── rfc4954.txt
│   │   │   ├── rfc5751.txt
│   │   │   └── whats_where.txt
│   │   ├── rfc5672.txt
│   │   ├── rfc6376.txt
│   │   └── smtp.txt
│   ├── plugins.rst
│   └── sending.rst
├── lib/
│   ├── classes/
│   │   ├── Swift/
│   │   │   ├── AddressEncoder/
│   │   │   │   ├── IdnAddressEncoder.php
│   │   │   │   └── Utf8AddressEncoder.php
│   │   │   ├── AddressEncoder.php
│   │   │   ├── AddressEncoderException.php
│   │   │   ├── Attachment.php
│   │   │   ├── ByteStream/
│   │   │   │   ├── AbstractFilterableInputStream.php
│   │   │   │   ├── ArrayByteStream.php
│   │   │   │   ├── FileByteStream.php
│   │   │   │   └── TemporaryFileByteStream.php
│   │   │   ├── CharacterReader/
│   │   │   │   ├── GenericFixedWidthReader.php
│   │   │   │   ├── UsAsciiReader.php
│   │   │   │   └── Utf8Reader.php
│   │   │   ├── CharacterReader.php
│   │   │   ├── CharacterReaderFactory/
│   │   │   │   └── SimpleCharacterReaderFactory.php
│   │   │   ├── CharacterReaderFactory.php
│   │   │   ├── CharacterStream/
│   │   │   │   ├── ArrayCharacterStream.php
│   │   │   │   └── NgCharacterStream.php
│   │   │   ├── CharacterStream.php
│   │   │   ├── ConfigurableSpool.php
│   │   │   ├── DependencyContainer.php
│   │   │   ├── DependencyException.php
│   │   │   ├── EmbeddedFile.php
│   │   │   ├── Encoder/
│   │   │   │   ├── Base64Encoder.php
│   │   │   │   ├── QpEncoder.php
│   │   │   │   └── Rfc2231Encoder.php
│   │   │   ├── Encoder.php
│   │   │   ├── Events/
│   │   │   │   ├── CommandEvent.php
│   │   │   │   ├── CommandListener.php
│   │   │   │   ├── Event.php
│   │   │   │   ├── EventDispatcher.php
│   │   │   │   ├── EventListener.php
│   │   │   │   ├── EventObject.php
│   │   │   │   ├── ResponseEvent.php
│   │   │   │   ├── ResponseListener.php
│   │   │   │   ├── SendEvent.php
│   │   │   │   ├── SendListener.php
│   │   │   │   ├── SimpleEventDispatcher.php
│   │   │   │   ├── TransportChangeEvent.php
│   │   │   │   ├── TransportChangeListener.php
│   │   │   │   ├── TransportExceptionEvent.php
│   │   │   │   └── TransportExceptionListener.php
│   │   │   ├── FailoverTransport.php
│   │   │   ├── FileSpool.php
│   │   │   ├── FileStream.php
│   │   │   ├── Filterable.php
│   │   │   ├── IdGenerator.php
│   │   │   ├── Image.php
│   │   │   ├── InputByteStream.php
│   │   │   ├── IoException.php
│   │   │   ├── KeyCache/
│   │   │   │   ├── ArrayKeyCache.php
│   │   │   │   ├── DiskKeyCache.php
│   │   │   │   ├── KeyCacheInputStream.php
│   │   │   │   ├── NullKeyCache.php
│   │   │   │   └── SimpleKeyCacheInputStream.php
│   │   │   ├── KeyCache.php
│   │   │   ├── LoadBalancedTransport.php
│   │   │   ├── Mailer/
│   │   │   │   ├── ArrayRecipientIterator.php
│   │   │   │   └── RecipientIterator.php
│   │   │   ├── Mailer.php
│   │   │   ├── MemorySpool.php
│   │   │   ├── Message.php
│   │   │   ├── Mime/
│   │   │   │   ├── Attachment.php
│   │   │   │   ├── CharsetObserver.php
│   │   │   │   ├── ContentEncoder/
│   │   │   │   │   ├── Base64ContentEncoder.php
│   │   │   │   │   ├── NativeQpContentEncoder.php
│   │   │   │   │   ├── NullContentEncoder.php
│   │   │   │   │   ├── PlainContentEncoder.php
│   │   │   │   │   ├── QpContentEncoder.php
│   │   │   │   │   ├── QpContentEncoderProxy.php
│   │   │   │   │   └── RawContentEncoder.php
│   │   │   │   ├── ContentEncoder.php
│   │   │   │   ├── EmbeddedFile.php
│   │   │   │   ├── EncodingObserver.php
│   │   │   │   ├── Header.php
│   │   │   │   ├── HeaderEncoder/
│   │   │   │   │   ├── Base64HeaderEncoder.php
│   │   │   │   │   └── QpHeaderEncoder.php
│   │   │   │   ├── HeaderEncoder.php
│   │   │   │   ├── Headers/
│   │   │   │   │   ├── AbstractHeader.php
│   │   │   │   │   ├── DateHeader.php
│   │   │   │   │   ├── IdentificationHeader.php
│   │   │   │   │   ├── MailboxHeader.php
│   │   │   │   │   ├── OpenDKIMHeader.php
│   │   │   │   │   ├── ParameterizedHeader.php
│   │   │   │   │   ├── PathHeader.php
│   │   │   │   │   └── UnstructuredHeader.php
│   │   │   │   ├── IdGenerator.php
│   │   │   │   ├── MimePart.php
│   │   │   │   ├── SimpleHeaderFactory.php
│   │   │   │   ├── SimpleHeaderSet.php
│   │   │   │   ├── SimpleMessage.php
│   │   │   │   └── SimpleMimeEntity.php
│   │   │   ├── MimePart.php
│   │   │   ├── NullTransport.php
│   │   │   ├── OutputByteStream.php
│   │   │   ├── Plugins/
│   │   │   │   ├── AntiFloodPlugin.php
│   │   │   │   ├── BandwidthMonitorPlugin.php
│   │   │   │   ├── Decorator/
│   │   │   │   │   └── Replacements.php
│   │   │   │   ├── DecoratorPlugin.php
│   │   │   │   ├── ImpersonatePlugin.php
│   │   │   │   ├── Logger.php
│   │   │   │   ├── LoggerPlugin.php
│   │   │   │   ├── Loggers/
│   │   │   │   │   ├── ArrayLogger.php
│   │   │   │   │   └── EchoLogger.php
│   │   │   │   ├── MessageLogger.php
│   │   │   │   ├── Pop/
│   │   │   │   │   ├── Pop3Connection.php
│   │   │   │   │   └── Pop3Exception.php
│   │   │   │   ├── PopBeforeSmtpPlugin.php
│   │   │   │   ├── RedirectingPlugin.php
│   │   │   │   ├── Reporter.php
│   │   │   │   ├── ReporterPlugin.php
│   │   │   │   ├── Reporters/
│   │   │   │   │   ├── HitReporter.php
│   │   │   │   │   └── HtmlReporter.php
│   │   │   │   ├── Sleeper.php
│   │   │   │   ├── ThrottlerPlugin.php
│   │   │   │   └── Timer.php
│   │   │   ├── Preferences.php
│   │   │   ├── ReplacementFilterFactory.php
│   │   │   ├── RfcComplianceException.php
│   │   │   ├── SendmailTransport.php
│   │   │   ├── Signer.php
│   │   │   ├── Signers/
│   │   │   │   ├── BodySigner.php
│   │   │   │   ├── DKIMSigner.php
│   │   │   │   ├── DomainKeySigner.php
│   │   │   │   ├── HeaderSigner.php
│   │   │   │   ├── OpenDKIMSigner.php
│   │   │   │   └── SMimeSigner.php
│   │   │   ├── SmtpTransport.php
│   │   │   ├── Spool.php
│   │   │   ├── SpoolTransport.php
│   │   │   ├── StreamFilter.php
│   │   │   ├── StreamFilters/
│   │   │   │   ├── ByteArrayReplacementFilter.php
│   │   │   │   ├── StringReplacementFilter.php
│   │   │   │   └── StringReplacementFilterFactory.php
│   │   │   ├── SwiftException.php
│   │   │   ├── Transport/
│   │   │   │   ├── AbstractSmtpTransport.php
│   │   │   │   ├── Esmtp/
│   │   │   │   │   ├── Auth/
│   │   │   │   │   │   ├── CramMd5Authenticator.php
│   │   │   │   │   │   ├── LoginAuthenticator.php
│   │   │   │   │   │   ├── NTLMAuthenticator.php
│   │   │   │   │   │   ├── PlainAuthenticator.php
│   │   │   │   │   │   └── XOAuth2Authenticator.php
│   │   │   │   │   ├── AuthHandler.php
│   │   │   │   │   ├── Authenticator.php
│   │   │   │   │   ├── EightBitMimeHandler.php
│   │   │   │   │   └── SmtpUtf8Handler.php
│   │   │   │   ├── EsmtpHandler.php
│   │   │   │   ├── EsmtpTransport.php
│   │   │   │   ├── FailoverTransport.php
│   │   │   │   ├── IoBuffer.php
│   │   │   │   ├── LoadBalancedTransport.php
│   │   │   │   ├── NullTransport.php
│   │   │   │   ├── SendmailTransport.php
│   │   │   │   ├── SmtpAgent.php
│   │   │   │   ├── SpoolTransport.php
│   │   │   │   └── StreamBuffer.php
│   │   │   ├── Transport.php
│   │   │   └── TransportException.php
│   │   └── Swift.php
│   ├── dependency_maps/
│   │   ├── cache_deps.php
│   │   ├── message_deps.php
│   │   ├── mime_deps.php
│   │   └── transport_deps.php
│   ├── mime_types.php
│   ├── preferences.php
│   ├── swift_required.php
│   └── swiftmailer_generate_mimes_config.php
├── phpunit.xml.dist
└── tests/
    ├── IdenticalBinaryConstraint.php
    ├── StreamCollector.php
    ├── SwiftMailerSmokeTestCase.php
    ├── SwiftMailerTestCase.php
    ├── _samples/
    │   ├── charsets/
    │   │   ├── iso-2022-jp/
    │   │   │   └── one.txt
    │   │   ├── iso-8859-1/
    │   │   │   └── one.txt
    │   │   └── utf-8/
    │   │       ├── one.txt
    │   │       ├── three.txt
    │   │       └── two.txt
    │   ├── dkim/
    │   │   ├── dkim.test.priv
    │   │   └── dkim.test.pub
    │   ├── files/
    │   │   └── data.txt
    │   └── smime/
    │       ├── CA.srl
    │       ├── ca.crt
    │       ├── ca.key
    │       ├── create-cert.sh
    │       ├── encrypt.crt
    │       ├── encrypt.key
    │       ├── encrypt2.crt
    │       ├── encrypt2.key
    │       ├── intermediate.crt
    │       ├── intermediate.key
    │       ├── sign.crt
    │       ├── sign.key
    │       ├── sign2.crt
    │       └── sign2.key
    ├── acceptance/
    │   └── Swift/
    │       ├── AttachmentAcceptanceTest.php
    │       ├── ByteStream/
    │       │   └── FileByteStreamAcceptanceTest.php
    │       ├── CharacterReaderFactory/
    │       │   └── SimpleCharacterReaderFactoryAcceptanceTest.php
    │       ├── DependencyContainerAcceptanceTest.php
    │       ├── EmbeddedFileAcceptanceTest.php
    │       ├── Encoder/
    │       │   ├── Base64EncoderAcceptanceTest.php
    │       │   ├── QpEncoderAcceptanceTest.php
    │       │   └── Rfc2231EncoderAcceptanceTest.php
    │       ├── KeyCache/
    │       │   ├── ArrayKeyCacheAcceptanceTest.php
    │       │   └── DiskKeyCacheAcceptanceTest.php
    │       ├── MessageAcceptanceTest.php
    │       ├── Mime/
    │       │   ├── AttachmentAcceptanceTest.php
    │       │   ├── ContentEncoder/
    │       │   │   ├── Base64ContentEncoderAcceptanceTest.php
    │       │   │   ├── NativeQpContentEncoderAcceptanceTest.php
    │       │   │   ├── PlainContentEncoderAcceptanceTest.php
    │       │   │   └── QpContentEncoderAcceptanceTest.php
    │       │   ├── EmbeddedFileAcceptanceTest.php
    │       │   ├── HeaderEncoder/
    │       │   │   └── Base64HeaderEncoderAcceptanceTest.php
    │       │   ├── MimePartAcceptanceTest.php
    │       │   └── SimpleMessageAcceptanceTest.php
    │       ├── MimePartAcceptanceTest.php
    │       └── Transport/
    │           └── StreamBuffer/
    │               ├── AbstractStreamBufferAcceptanceTest.php
    │               ├── BasicSocketAcceptanceTest.php
    │               ├── ProcessAcceptanceTest.php
    │               ├── SocketTimeoutTest.php
    │               ├── SslSocketAcceptanceTest.php
    │               └── TlsSocketAcceptanceTest.php
    ├── acceptance.conf.php.default
    ├── bootstrap.php
    ├── bug/
    │   └── Swift/
    │       ├── Bug111Test.php
    │       ├── Bug118Test.php
    │       ├── Bug206Test.php
    │       ├── Bug274Test.php
    │       ├── Bug34Test.php
    │       ├── Bug35Test.php
    │       ├── Bug38Test.php
    │       ├── Bug518Test.php
    │       ├── Bug51Test.php
    │       ├── Bug534Test.php
    │       ├── Bug650Test.php
    │       ├── Bug71Test.php
    │       ├── Bug76Test.php
    │       └── BugFileByteStreamConsecutiveReadCallsTest.php
    ├── fixtures/
    │   └── MimeEntityFixture.php
    ├── smoke/
    │   └── Swift/
    │       └── Smoke/
    │           ├── AttachmentSmokeTest.php
    │           ├── BasicSmokeTest.php
    │           ├── HtmlWithAttachmentSmokeTest.php
    │           └── InternationalSmokeTest.php
    ├── smoke.conf.php.default
    └── unit/
        └── Swift/
            ├── ByteStream/
            │   └── ArrayByteStreamTest.php
            ├── CharacterReader/
            │   ├── GenericFixedWidthReaderTest.php
            │   ├── UsAsciiReaderTest.php
            │   └── Utf8ReaderTest.php
            ├── CharacterStream/
            │   └── ArrayCharacterStreamTest.php
            ├── DependencyContainerTest.php
            ├── Encoder/
            │   ├── Base64EncoderTest.php
            │   ├── QpEncoderTest.php
            │   └── Rfc2231EncoderTest.php
            ├── Events/
            │   ├── CommandEventTest.php
            │   ├── EventObjectTest.php
            │   ├── ResponseEventTest.php
            │   ├── SendEventTest.php
            │   ├── SimpleEventDispatcherTest.php
            │   ├── TransportChangeEventTest.php
            │   └── TransportExceptionEventTest.php
            ├── KeyCache/
            │   ├── ArrayKeyCacheTest.php
            │   └── SimpleKeyCacheInputStreamTest.php
            ├── Mailer/
            │   └── ArrayRecipientIteratorTest.php
            ├── MailerTest.php
            ├── MessageTest.php
            ├── Mime/
            │   ├── AbstractMimeEntityTest.php
            │   ├── AttachmentTest.php
            │   ├── ContentEncoder/
            │   │   ├── Base64ContentEncoderTest.php
            │   │   ├── PlainContentEncoderTest.php
            │   │   └── QpContentEncoderTest.php
            │   ├── EmbeddedFileTest.php
            │   ├── HeaderEncoder/
            │   │   ├── Base64HeaderEncoderTest.php
            │   │   └── QpHeaderEncoderTest.php
            │   ├── Headers/
            │   │   ├── DateHeaderTest.php
            │   │   ├── IdentificationHeaderTest.php
            │   │   ├── MailboxHeaderTest.php
            │   │   ├── ParameterizedHeaderTest.php
            │   │   ├── PathHeaderTest.php
            │   │   └── UnstructuredHeaderTest.php
            │   ├── IdGeneratorTest.php
            │   ├── MimePartTest.php
            │   ├── SimpleHeaderFactoryTest.php
            │   ├── SimpleHeaderSetTest.php
            │   ├── SimpleMessageTest.php
            │   └── SimpleMimeEntityTest.php
            ├── Plugins/
            │   ├── AntiFloodPluginTest.php
            │   ├── BandwidthMonitorPluginTest.php
            │   ├── DecoratorPluginTest.php
            │   ├── LoggerPluginTest.php
            │   ├── Loggers/
            │   │   ├── ArrayLoggerTest.php
            │   │   └── EchoLoggerTest.php
            │   ├── PopBeforeSmtpPluginTest.php
            │   ├── RedirectingPluginTest.php
            │   ├── ReporterPluginTest.php
            │   ├── Reporters/
            │   │   ├── HitReporterTest.php
            │   │   └── HtmlReporterTest.php
            │   └── ThrottlerPluginTest.php
            ├── Signers/
            │   ├── DKIMSignerTest.php
            │   ├── OpenDKIMSignerTest.php
            │   └── SMimeSignerTest.php
            ├── StreamFilters/
            │   ├── ByteArrayReplacementFilterTest.php
            │   ├── StringReplacementFilterFactoryTest.php
            │   └── StringReplacementFilterTest.php
            └── Transport/
                ├── AbstractSmtpEventSupportTest.php
                ├── AbstractSmtpTest.php
                ├── Esmtp/
                │   ├── Auth/
                │   │   ├── CramMd5AuthenticatorTest.php
                │   │   ├── LoginAuthenticatorTest.php
                │   │   ├── NTLMAuthenticatorTest.php
                │   │   └── PlainAuthenticatorTest.php
                │   └── AuthHandlerTest.php
                ├── EsmtpTransport/
                │   └── ExtensionSupportTest.php
                ├── EsmtpTransportTest.php
                ├── FailoverTransportTest.php
                ├── LoadBalancedTransportTest.php
                ├── SendmailTransportTest.php
                └── StreamBufferTest.php

================================================
FILE CONTENTS
================================================

================================================
FILE: .gitattributes
================================================
*.crt -crlf
*.key -crlf
*.srl -crlf
*.pub -crlf
*.priv -crlf
*.txt -crlf

# ignore directories in the git-generated distributed .zip archive
/doc/notes export-ignore
/tests export-ignore
/phpunit.xml.dist export-ignore


================================================
FILE: .github/ISSUE_TEMPLATE.md
================================================
<!-- Please fill in this template according to your issue. -->

| Q                   | A
| ------------------- | -----
| Bug report?         | yes/no
| Feature request?    | yes/no
| RFC?                | yes/no
| How used?           | Standalone/Symfony/3party
| Swiftmailer version | x.y.z
| PHP version         | x.y.z

### Observed behaviour
<!-- What does the code do? -->

### Expected behaviour
<!-- What should the code do? -->

### Example
<!-- Example to reproduce the issue. -->


================================================
FILE: .github/PULL_REQUEST_TEMPLATE.md
================================================
<!-- Please fill in this template according to the PR you're about to submit. -->

| Q             | A
| ------------- | ---
| Bug fix?      | yes/no
| New feature?  | yes/no
| Doc update?   | yes/no
| BC breaks?    | yes/no
| Deprecations? | yes/no
| Fixed tickets | #... <!-- #-prefixed issue number(s), if any -->
| License       | MIT


<!-- Replace this comment by the description of your issue. -->


================================================
FILE: .github/workflows/tests.yml
================================================
name: tests

on:
  push:
  pull_request:

jobs:
  linux_tests:
    runs-on: ubuntu-20.04

    services:
      mailcatcher:
        image: dockage/mailcatcher:0.7.1
        ports:
          - 4456:1025

    strategy:
      fail-fast: true
      matrix:
        php: ['7.0', '7.1', '7.2', '7.3', '7.4', '8.0', '8.1']

    name: PHP ${{ matrix.php }}

    steps:
      - name: Checkout code
        uses: actions/checkout@v2

      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: ${{ matrix.php }}
          extensions: dom, curl, libxml, mbstring, zip, intl
          tools: composer:v2
          coverage: none

      - name: Prepare test config files
        run: |
          cp tests/acceptance.conf.php.default tests/acceptance.conf.php
          cp tests/smoke.conf.php.default tests/smoke.conf.php

      - name: Require Symfony PHPUnit Bridge 5.4 for PHP 8.1
        if: ${{ matrix.php >= 8.1 }}
        run: composer require symfony/phpunit-bridge:^5.4 --dev --prefer-dist --no-interaction --no-progress

      - name: Install dependencies
        uses: nick-invision/retry@v1
        with:
          timeout_minutes: 5
          max_attempts: 5
          command: composer update --prefer-stable --prefer-dist --no-interaction --no-progress

      - name: Execute tests
        run: vendor/bin/simple-phpunit --verbose
        env:
          SYMFONY_PHPUNIT_REMOVE_RETURN_TYPEHINT: 1


================================================
FILE: .gitignore
================================================
/.php_cs.cache
/.phpunit
/.phpunit.result.cache
/build/*
/composer.lock
/phpunit.xml
/tests/acceptance.conf.php
/tests/smoke.conf.php
/vendor/


================================================
FILE: .php_cs.dist
================================================
<?php

return PhpCsFixer\Config::create()
    ->setRules([
        '@Symfony' => true,
        '@Symfony:risky' => true,
        '@PHPUnit75Migration:risky' => true,
        'php_unit_dedicate_assert' => ['target' => '5.6'],
        'array_syntax' => ['syntax' => 'short'],
        'php_unit_fqcn_annotation' => true,
        'no_unreachable_default_argument_value' => false,
        'braces' => ['allow_single_line_closure' => true],
        'heredoc_to_nowdoc' => false,
        'ordered_imports' => true,
        'phpdoc_types_order' => ['null_adjustment' => 'always_last', 'sort_algorithm' => 'none'],
        'native_function_invocation' => ['include' => ['@compiler_optimized'], 'scope' => 'all'],
        'fopen_flags' => false,
    ])
    ->setRiskyAllowed(true)
    ->setFinder(PhpCsFixer\Finder::create()->in(__DIR__))
;


================================================
FILE: CHANGES
================================================
Changelog
=========

**Swiftmailer will stop being maintained at the end of November 2021.**

Please, move to Symfony Mailer at your earliest convenience.
Symfony Mailer is the next evolution of Swiftmailer.
It provides the same features with support for modern PHP code and support for third-party providers.
See https://symfony.com/doc/current/mailer.html for more information.

6.3.0 (2021-10-18)
------------------

 * Fix support for PHP 8.1

6.2.7 (2021-03-09)
------------------

 * Allow egulias/email-validator 3.1+

6.2.6 (2021-03-05)
------------------

 * Fix Bcc support

6.2.5 (2021-01-12)
------------------

 * Don't trust properties at destruct time
 * Remove invalid PHPDocs param in EventDispatcher interface
 * Bump license year
 * Removes PHP version from README

6.2.4 (2020-12-08)
------------------

 * Prevent flushing of the bubble queue when event handler raises another event
 * Add support for PHP 8
 * Code cleanups

6.2.3 (2019-11-12)
------------------

 * no changes

6.2.2 (2019-11-12)
------------------

 * fixed compat with PHP 7.4
 * fixed error message when connecting to a stream raises an error before connect()

6.2.1 (2019-04-21)
------------------

 * reverted "deprecated Swift_CharacterStream_ArrayCharacterStream and Swift_CharacterStream_NgCharacterStream in favor of Swift_CharacterStream_CharacterStream"

6.2.0 (2019-03-10)
------------------

 * added support for symfony/polyfill-intl-dn
 * deprecated Swift_CharacterStream_ArrayCharacterStream and Swift_CharacterStream_NgCharacterStream in favor of Swift_CharacterStream_CharacterStream

6.1.3 (2018-09-11)
------------------

 * added auto-start to the SMTP transport when sending a message
 * tweaked error message when the response from an SMTP server is empty
 * fixed missing property in Swift_Mime_IdGenerator
 * exposed original body content type with Swift_Mime_SimpleMimeEntity::getBodyContentType()
 * fixed typo in variable name in Swift_AddressEncoder_IdnAddressEncoder
 * fixed return type in MessageLogger
 * fixed missing property addressEncoder in SimpleHeaderFactory class

6.1.2 (2018-07-13)
------------------

 * handled recipient errors when pipelining

6.1.1 (2018-07-04)
------------------

 * removed hard dependency on an IDN encoder

6.1.0 (2018-07-02)
------------------

 * added address encoder exceptions during send
 * added support for bubbling up authenticator error messages
 * added support for non-ASCII email addresses
 * introduced new dependencies: transport.smtphandlers and transport.authhandlers
 * deprecated Swift_Signers_OpenDKIMSigner; use Swift_Signers_DKIMSigner instead
 * added support for SMTP pipelining
 * added Swift_Transport_Esmtp_EightBitMimeHandler
 * fixed startTLS only allowed tls1.0, now allowed: tls1.0, tls1.1, tls1.2

6.0.2 (2017-09-30)
------------------

 * fixed DecoratorPlugin
 * removed usage of getmypid()

6.0.1 (2017-05-20)
------------------

 * fixed BC break that can be avoided easily

6.0.0 (2017-05-19)
------------------

 * added Swift_Transport::ping()
 * removed Swift_Mime_HeaderFactory, Swift_Mime_HeaderSet, Swift_Mime_Message, Swift_Mime_MimeEntity,
   and Swift_Mime_ParameterizedHeader interfaces
 * removed Swift_MailTransport and Swift_Transport_MailTransport
 * removed Swift_Encoding
 * removed the Swift_Transport_MailInvoker interface and Swift_Transport_SimpleMailInvoker class
 * removed the Swift_SignedMessage class
 * removed newInstance() methods everywhere
 * methods operating on Date header now use DateTimeImmutable object instead of Unix timestamp;
   Swift_Mime_Headers_DateHeader::getTimestamp()/setTimestamp() renamed to getDateTime()/setDateTime()
 * bumped minimum version to PHP 7.0
 * removed Swift_Validate and replaced by egulias/email-validator

5.4.9 (2018-01-23)
------------------

 * no changes, last version of the 5.x series

5.4.8 (2017-05-01)
------------------

 * fixed encoding inheritance in addPart()
 * fixed sorting MIME children when their types are equal

5.4.7 (2017-04-20)
------------------

 * fixed NTLMAuthenticator clobbering bcmath scale

5.4.6 (2017-02-13)
------------------

 * removed exceptions thrown in destructors as they lead to fatal errors
 * switched to use sha256 by default in DKIM as per the RFC
 * fixed an 'Undefined variable: pipes' PHP notice
 * fixed long To headers when using the mail transport
 * fixed NTLMAuthenticator when no domain is passed with the username
 * prevented fatal error during unserialization of a message
 * fixed a PHP warning when sending a message that has a length of a multiple of 8192

5.4.5 (2016-12-29)
------------------

 * SECURITY FIX:  fixed CVE-2016-10074 by disallowing potentially unsafe shell characters

   Prior to 5.4.5, the mail transport (Swift_Transport_MailTransport) was vulnerable to passing
   arbitrary shell arguments if the "From", "ReturnPath" or "Sender" header came
   from a non-trusted source, potentially allowing Remote Code Execution
 * deprecated the mail transport

5.4.4 (2016-11-23)
------------------

 * reverted escaping command-line args to mail (PHP mail() function already does it)

5.4.3 (2016-07-08)
------------------

 * fixed SimpleHeaderSet::has()/get() when the 0 index is removed
 * removed the need to have mcrypt installed
 * fixed broken MIME header encoding with quotes/colons and non-ascii chars
 * allowed mail transport send for messages without To header
 * fixed PHP 7 support

5.4.2 (2016-05-01)
------------------

 * fixed support for IPv6 sockets
 * added auto-retry when sending messages from the memory spool
 * fixed consecutive read calls in Swift_ByteStream_FileByteStream
 * added support for iso-8859-15 encoding
 * fixed PHP mail extra params on missing reversePath
 * added methods to set custom stream context options
 * fixed charset changes in QpContentEncoderProxy
 * added return-path header to the ignoredHeaders list of DKIMSigner
 * fixed crlf for subject using mail
 * fixed add soft line break only when necessary
 * fixed escaping command-line args to mail

5.4.1 (2015-06-06)
------------------

 * made Swiftmailer exceptions confirm to PHP base exception constructor signature
 * fixed MAIL FROM & RCPT TO headers to be RFC compliant

5.4.0 (2015-03-14)
------------------

 * added the possibility to add extra certs to PKCS#7 signature
 * fix base64 encoding with streams
 * added a new RESULT_SPOOLED status for SpoolTransport
 * fixed getBody() on attachments when called more than once
 * removed dots from generated filenames in filespool

5.3.1 (2014-12-05)
------------------

 * fixed cloning of messages with attachments

5.3.0 (2014-10-04)
------------------

 * fixed cloning when using signers
 * reverted removal of Swift_Encoding
 * drop support for PHP 5.2.x

5.2.2 (2014-09-20)
------------------

 * fixed Japanese support
 * fixed the memory spool when the message changes when in the pool
 * added support for cloning messages
 * fixed PHP warning in the redirect plugin
 * changed the way to and cc-ed email are sent to only use one transaction

5.2.1 (2014-06-13)
------------------

 * SECURITY FIX: fixed CLI escaping when using sendmail as a transport

   Prior to 5.2.1, the sendmail transport (Swift_Transport_SendmailTransport)
   was vulnerable to an arbitrary shell execution if the "From" header came
   from a non-trusted source and no "Return-Path" is configured.

 * fixed parameter in DKIMSigner
 * fixed compatibility with PHP < 5.4

5.2.0 (2014-05-08)
------------------

 * fixed Swift_ByteStream_FileByteStream::read() to match to the specification
 * fixed from-charset and to-charset arguments in mbstring_convert_encoding() usages
 * fixed infinite loop in StreamBuffer
 * fixed NullTransport to return the number of ignored emails instead of 0
 * Use phpunit and mockery for unit testing (realityking)

5.1.0 (2014-03-18)
------------------

 * fixed data writing to stream when sending large messages
 * added support for libopendkim (https://github.com/xdecock/php-opendkim)
 * merged SignedMessage and Message
 * added Gmail XOAuth2 authentication
 * updated the list of known mime types
 * added NTLM authentication

5.0.3 (2013-12-03)
------------------

 * fixed double-dot bug
 * fixed DKIM signer

5.0.2 (2013-08-30)
------------------

 * handled correct exception type while reading IoBuffer output

5.0.1 (2013-06-17)
------------------

 * changed the spool to only start the transport when a mail has to be sent
 * fixed compatibility with PHP 5.2
 * fixed LICENSE file

5.0.0 (2013-04-30)
------------------

 * changed the license from LGPL to MIT

4.3.1 (2013-04-11)
------------------

 * removed usage of the native QP encoder when the charset is not UTF-8
 * fixed usage of uniqid to avoid collisions
 * made a performance improvement when tokenizing large headers
 * fixed usage of the PHP native QP encoder on PHP 5.4.7+

4.3.0 (2013-01-08)
------------------

 * made the temporary directory configurable via the TMPDIR env variable
 * added S/MIME signer and encryption support

4.2.2 (2012-10-25)
------------------

 * added the possibility to throttle messages per second in ThrottlerPlugin (mostly for Amazon SES)
 * switched mime.qpcontentencoder to automatically use the PHP native encoder on PHP 5.4.7+
 * allowed specifying a whitelist with regular expressions in RedirectingPlugin

4.2.1 (2012-07-13)
------------------

 * changed the coding standards to PSR-1/2
 * fixed issue with autoloading
 * added NativeQpContentEncoder to enhance performance (for PHP 5.3+)

4.2.0 (2012-06-29)
------------------

 * added documentation about how to use the Japanese support introduced in 4.1.8
 * added a way to override the default configuration in a lazy way
 * changed the PEAR init script to lazy-load the initialization
 * fixed a bug when calling Swift_Preferences before anything else (regression introduced in 4.1.8)

4.1.8 (2012-06-17)
------------------

 * added Japanese iso-2022-jp support
 * changed the init script to lazy-load the initialization
 * fixed docblocks (@id) which caused some problems with libraries parsing the dobclocks
 * fixed Swift_Mime_Headers_IdentificationHeader::setId() when passed an array of ids
 * fixed encoding of email addresses in headers
 * added replacements setter to the Decorator plugin

4.1.7 (2012-04-26)
------------------

 * fixed QpEncoder safeMapShareId property

4.1.6 (2012-03-23)
------------------

 * reduced the size of serialized Messages

4.1.5 (2012-01-04)
------------------

 * enforced Swift_Spool::queueMessage() to return a Boolean
 * made an optimization to the memory spool: start the transport only when required
 * prevented stream_socket_client() from generating an error and throw a Swift_TransportException instead
 * fixed a PHP warning when calling to mail() when safe_mode is off
 * many doc tweaks

4.1.4 (2011-12-16)
------------------

 * added a memory spool (Swift_MemorySpool)
 * fixed too many opened files when sending emails with attachments

4.1.3 (2011-10-27)
------------------

 * added STARTTLS support
 * added missing @return tags on fluent methods
 * added a MessageLogger plugin that logs all sent messages
 * added composer.json

4.1.2 (2011-09-13)
------------------

 * fixed wrong detection of magic_quotes_runtime
 * fixed fatal errors when no To or Subject header has been set
 * fixed charset on parameter header continuations
 * added documentation about how to install Swiftmailer from the PEAR channel
 * fixed various typos and markup problem in the documentation
 * fixed warning when cache directory does not exist
 * fixed "slashes are escaped" bug
 * changed require_once() to require() in autoload

4.1.1 (2011-07-04)
------------------

 * added missing file in PEAR package

4.1.0 (2011-06-30)
------------------

 * documentation has been converted to ReST

4.1.0 RC1 (2011-06-17)
----------------------

New features:

 * changed the Decorator Plugin to allow replacements in all headers
 * added Swift_Mime_Grammar and Swift_Validate to validate an email address
 * modified the autoloader to lazy-initialize Swiftmailer
 * removed Swift_Mailer::batchSend()
 * added NullTransport
 * added new plugins: RedirectingPlugin and ImpersonatePlugin
 * added a way to send messages asynchronously (Spool)


================================================
FILE: LICENSE
================================================
Copyright (c) 2013-2021 Fabien Potencier

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is furnished
to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.


================================================
FILE: README.md
================================================
Swift Mailer
------------

**Swiftmailer will stop being maintained at the end of November 2021.**

Please, move to [Symfony Mailer](https://symfony.com/doc/current/mailer.html) at your earliest convenience.
[Symfony Mailer](https://symfony.com/doc/current/mailer.html) is the next evolution of Swiftmailer.
It provides the same features with support for modern PHP code and support for third-party providers.

Swift Mailer is a component based mailing solution for PHP.
It is released under the MIT license.

Swift Mailer is highly object-oriented by design and lends itself
to use in complex web application with a great deal of flexibility.

For full details on usage, read the [documentation](https://swiftmailer.symfony.com/docs/introduction.html).

Sponsors
--------

<div>
    <a href="https://blackfire.io/docs/introduction?utm_source=swiftmailer&utm_medium=github_readme&utm_campaign=logo">
        <img src="https://static.blackfire.io/assets/intemporals/logo/png/blackfire-io_secondary_horizontal_transparent.png?1" width="255px" alt="Blackfire.io">
    </a>
</div>


================================================
FILE: composer.json
================================================
{
    "name": "swiftmailer/swiftmailer",
    "type": "library",
    "description": "Swiftmailer, free feature-rich PHP mailer",
    "keywords": ["mail","mailer","email"],
    "homepage": "https://swiftmailer.symfony.com",
    "license": "MIT",
    "authors": [
        {
            "name": "Chris Corbyn"
        },
        {
            "name": "Fabien Potencier",
            "email": "fabien@symfony.com"
        }
    ],
    "require": {
        "php": ">=7.0.0",
        "egulias/email-validator": "^2.0|^3.1",
        "symfony/polyfill-iconv": "^1.0",
        "symfony/polyfill-mbstring": "^1.0",
        "symfony/polyfill-intl-idn": "^1.10"
    },
    "require-dev": {
        "mockery/mockery": "^1.0",
        "symfony/phpunit-bridge": "^4.4|^5.4"
    },
    "suggest": {
        "ext-intl": "Needed to support internationalized email addresses"
    },
    "autoload": {
        "files": ["lib/swift_required.php"]
    },
    "autoload-dev": {
        "psr-0": { "Swift_": "tests/unit" }
    },
    "extra": {
        "branch-alias": {
            "dev-master": "6.2-dev"
        }
    },
    "minimum-stability": "dev",
    "prefer-stable": true
}


================================================
FILE: doc/headers.rst
================================================
Message Headers
===============

Sometimes you'll want to add your own headers to a message or modify/remove
headers that are already present. You work with the message's HeaderSet to do
this.

Header Basics
-------------

All MIME entities in Swift Mailer -- including the message itself -- store
their headers in a single object called a HeaderSet. This HeaderSet is
retrieved with the ``getHeaders()`` method.

As mentioned in the previous chapter, everything that forms a part of a message
in Swift Mailer is a MIME entity that is represented by an instance of
``Swift_Mime_SimpleMimeEntity``. This includes -- most notably -- the message
object itself, attachments, MIME parts and embedded images. Each of these MIME
entities consists of a body and a set of headers that describe the body.

For all of the "standard" headers in these MIME entities, such as the
``Content-Type``, there are named methods for working with them, such as
``setContentType()`` and ``getContentType()``. This is because headers are a
moderately complex area of the library. Each header has a slightly different
required structure that it must meet in order to comply with the standards that
govern email (and that are checked by spam blockers etc).

You fetch the HeaderSet from a MIME entity like so::

    $message = new Swift_Message();

    // Fetch the HeaderSet from a Message object
    $headers = $message->getHeaders();

    $attachment = Swift_Attachment::fromPath('document.pdf');

    // Fetch the HeaderSet from an attachment object
    $headers = $attachment->getHeaders();

The job of the HeaderSet is to contain and manage instances of Header objects.
Depending upon the MIME entity the HeaderSet came from, the contents of the
HeaderSet will be different, since an attachment for example has a different
set of headers to those in a message.

You can find out what the HeaderSet contains with a quick loop, dumping out the
names of the headers::

    foreach ($headers->getAll() as $header) {
      printf("%s<br />\n", $header->getFieldName());
    }

    /*
    Content-Transfer-Encoding
    Content-Type
    MIME-Version
    Date
    Message-ID
    From
    Subject
    To
    */

You can also dump out the rendered HeaderSet by calling its ``toString()``
method::

    echo $headers->toString();

    /*
    Message-ID: <1234869991.499a9ee7f1d5e@swift.generated>
    Date: Tue, 17 Feb 2009 22:26:31 +1100
    Subject: Awesome subject!
    From: sender@example.org
    To: recipient@example.org
    MIME-Version: 1.0
    Content-Type: text/plain; charset=utf-8
    Content-Transfer-Encoding: quoted-printable
    */

Where the complexity comes in is when you want to modify an existing header.
This complexity comes from the fact that each header can be of a slightly
different type (such as a Date header, or a header that contains email
addresses, or a header that has key-value parameters on it!). Each header in
the HeaderSet is an instance of ``Swift_Mime_Header``. They all have common
functionality, but knowing exactly what type of header you're working with will
allow you a little more control.

You can determine the type of header by comparing the return value of its
``getFieldType()`` method with the constants ``TYPE_TEXT``,
``TYPE_PARAMETERIZED``, ``TYPE_DATE``, ``TYPE_MAILBOX``, ``TYPE_ID`` and
``TYPE_PATH`` which are defined in ``Swift_Mime_Header``::

    foreach ($headers->getAll() as $header) {
      switch ($header->getFieldType()) {
        case Swift_Mime_Header::TYPE_TEXT: $type = 'text';
          break;
        case Swift_Mime_Header::TYPE_PARAMETERIZED: $type = 'parameterized';
          break;
        case Swift_Mime_Header::TYPE_MAILBOX: $type = 'mailbox';
          break;
        case Swift_Mime_Header::TYPE_DATE: $type = 'date';
          break;
        case Swift_Mime_Header::TYPE_ID: $type = 'ID';
          break;
        case Swift_Mime_Header::TYPE_PATH: $type = 'path';
          break;
      }
      printf("%s: is a %s header<br />\n", $header->getFieldName(), $type);
    }

    /*
    Content-Transfer-Encoding: is a text header
    Content-Type: is a parameterized header
    MIME-Version: is a text header
    Date: is a date header
    Message-ID: is a ID header
    From: is a mailbox header
    Subject: is a text header
    To: is a mailbox header
    */

Headers can be removed from the set, modified within the set, or added to the
set.

The following sections show you how to work with the HeaderSet and explain the
details of each implementation of ``Swift_Mime_Header`` that may exist within
the HeaderSet.

Header Types
------------

Because all headers are modeled on different data (dates, addresses, text!)
there are different types of Header in Swift Mailer. Swift Mailer attempts to
categorize all possible MIME headers into more general groups, defined by a
small number of classes.

Text Headers
~~~~~~~~~~~~

Text headers are the simplest type of Header. They contain textual information
with no special information included within it -- for example the Subject
header in a message.

There's nothing particularly interesting about a text header, though it is
probably the one you'd opt to use if you need to add a custom header to a
message. It represents text just like you'd think it does. If the text contains
characters that are not permitted in a message header (such as new lines, or
non-ascii characters) then the header takes care of encoding the text so that
it can be used.

No header -- including text headers -- in Swift Mailer is vulnerable to
header-injection attacks. Swift Mailer breaks any attempt at header injection
by encoding the dangerous data into a non-dangerous form.

It's easy to add a new text header to a HeaderSet. You do this by calling the
HeaderSet's ``addTextHeader()`` method::

    $message = new Swift_Message();
    $headers = $message->getHeaders();
    $headers->addTextHeader('Your-Header-Name', 'the header value');

Changing the value of an existing text header is done by calling it's
``setValue()`` method::

    $subject = $message->getHeaders()->get('Subject');
    $subject->setValue('new subject');

When output via ``toString()``, a text header produces something like the
following::

    $subject = $message->getHeaders()->get('Subject');
    $subject->setValue('amazing subject line');
    echo $subject->toString();

    /*

    Subject: amazing subject line

    */

If the header contains any characters that are outside of the US-ASCII range
however, they will be encoded. This is nothing to be concerned about since mail
clients will decode them back::

    $subject = $message->getHeaders()->get('Subject');
    $subject->setValue('contains – dash');
    echo $subject->toString();

    /*

    Subject: contains =?utf-8?Q?=E2=80=93?= dash

    */

Parameterized Headers
~~~~~~~~~~~~~~~~~~~~~

Parameterized headers are text headers that contain key-value parameters
following the textual content. The Content-Type header of a message is a
parameterized header since it contains charset information after the content
type.

The parameterized header type is a special type of text header. It extends the
text header by allowing additional information to follow it. All of the methods
from text headers are available in addition to the methods described here.

Adding a parameterized header to a HeaderSet is done by using the
``addParameterizedHeader()`` method which takes a text value like
``addTextHeader()`` but it also accepts an associative array of key-value
parameters::

    $message = new Swift_Message();
    $headers = $message->getHeaders();
    $headers->addParameterizedHeader(
      'Header-Name', 'header value',
      ['foo' => 'bar']
      );

To change the text value of the header, call it's ``setValue()`` method just as
you do with text headers.

To change the parameters in the header, call the header's ``setParameters()``
method or the ``setParameter()`` method (note the pluralization)::

    $type = $message->getHeaders()->get('Content-Type');

    // setParameters() takes an associative array
    $type->setParameters([
      'name' => 'file.txt',
      'charset' => 'iso-8859-1'
    ]);

    // setParameter() takes two args for $key and $value
    $type->setParameter('charset', 'iso-8859-1');

When output via ``toString()``, a parameterized header produces something like
the following::

    $type = $message->getHeaders()->get('Content-Type');
    $type->setValue('text/html');
    $type->setParameter('charset', 'utf-8');

    echo $type->toString();

    /*

    Content-Type: text/html; charset=utf-8

    */

If the header contains any characters that are outside of the US-ASCII range
however, they will be encoded, just like they are for text headers. This is
nothing to be concerned about since mail clients will decode them back.
Likewise, if the parameters contain any non-ascii characters they will be
encoded so that they can be transmitted safely::

    $attachment = new Swift_Attachment();
    $disp = $attachment->getHeaders()->get('Content-Disposition');
    $disp->setValue('attachment');
    $disp->setParameter('filename', 'report–may.pdf');
    echo $disp->toString();

    /*

    Content-Disposition: attachment; filename*=utf-8''report%E2%80%93may.pdf

    */

Date Headers
~~~~~~~~~~~~

Date headers contains an RFC 2822 formatted date (i.e. what PHP's ``date('r')``
returns). They are used anywhere a date or time is needed to be presented as a
message header.

The data on which a date header is modeled as a DateTimeImmutable object. The
object is used to create a correctly structured RFC 2822 formatted date with
timezone such as ``Tue, 17 Feb 2009 22:26:31 +1100``.

The obvious place this header type is used is in the ``Date:`` header of the
message itself.

It's easy to add a new date header to a HeaderSet. You do this by calling the
HeaderSet's ``addDateHeader()`` method::

    $message = new Swift_Message();
    $headers = $message->getHeaders();
    $headers->addDateHeader('Your-Header', new DateTimeImmutable('3 days ago'));

Changing the value of an existing date header is done by calling it's
``setDateTime()`` method::

    $date = $message->getHeaders()->get('Date');
    $date->setDateTime(new DateTimeImmutable());

When output via ``toString()``, a date header produces something like the
following::

    $date = $message->getHeaders()->get('Date');
    echo $date->toString();

    /*

    Date: Wed, 18 Feb 2009 13:35:02 +1100

    */

Mailbox (e-mail address) Headers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Mailbox headers contain one or more email addresses, possibly with personalized
names attached to them. The data on which they are modeled is represented by an
associative array of email addresses and names.

Mailbox headers are probably the most complex header type to understand in
Swift Mailer because they accept their input as an array which can take various
forms, as described in the previous chapter.

All of the headers that contain e-mail addresses in a message -- with the
exception of ``Return-Path:`` which has a stricter syntax -- use this header
type. That is, ``To:``, ``From:`` etc.

You add a new mailbox header to a HeaderSet by calling the HeaderSet's
``addMailboxHeader()`` method::

    $message = new Swift_Message();
    $headers = $message->getHeaders();
    $headers->addMailboxHeader('Your-Header-Name', [
          'person1@example.org' => 'Person Name One',
          'person2@example.org',
          'person3@example.org',
          'person4@example.org' => 'Another named person'
    ]);

Changing the value of an existing mailbox header is done by calling it's
``setNameAddresses()`` method::

    $to = $message->getHeaders()->get('To');
    $to->setNameAddresses([
      'joe@example.org' => 'Joe Bloggs',
      'john@example.org' => 'John Doe',
      'no-name@example.org'
    ]);

If you don't wish to concern yourself with the complicated accepted input
formats accepted by ``setNameAddresses()`` as described in the previous chapter
and you only want to set one or more addresses (not names) then you can just
use the ``setAddresses()`` method instead::

    $to = $message->getHeaders()->get('To');
    $to->setAddresses([
      'joe@example.org',
      'john@example.org',
      'no-name@example.org'
    ]);

.. note::

    Both methods will accept the above input format in practice.

If all you want to do is set a single address in the header, you can use a
string as the input parameter to ``setAddresses()`` and/or
``setNameAddresses()``::

    $to = $message->getHeaders()->get('To');
    $to->setAddresses('joe-bloggs@example.org');

When output via ``toString()``, a mailbox header produces something like the
following::

    $to = $message->getHeaders()->get('To');
    $to->setNameAddresses([
      'person1@example.org' => 'Name of Person',
      'person2@example.org',
      'person3@example.org' => 'Another Person'
    ]);

    echo $to->toString();

    /*

    To: Name of Person <person1@example.org>, person2@example.org, Another Person
     <person3@example.org>

    */

Internationalized domains are automatically converted to IDN encoding::

    $to = $message->getHeaders()->get('To');
    $to->setAddresses('joe@ëxämple.org');

    echo $to->toString();

    /*

    To: joe@xn--xmple-gra1c.org

    */

ID Headers
~~~~~~~~~~

ID headers contain identifiers for the entity (or the message). The most
notable ID header is the Message-ID header on the message itself.

An ID that exists inside an ID header looks more-or-less less like an email
address. For example, ``<1234955437.499becad62ec2@example.org>``. The part to
the left of the @ sign is usually unique, based on the current time and some
random factor. The part on the right is usually a domain name.

Any ID passed to the header's ``setId()`` method absolutely MUST conform to
this structure, otherwise you'll get an Exception thrown at you by Swift Mailer
(a ``Swift_RfcComplianceException``). This is to ensure that the generated
email complies with relevant RFC documents and therefore is less likely to be
blocked as spam.

It's easy to add a new ID header to a HeaderSet. You do this by calling the
HeaderSet's ``addIdHeader()`` method::

    $message = new Swift_Message();
    $headers = $message->getHeaders();
    $headers->addIdHeader('Your-Header-Name', '123456.unqiue@example.org');

Changing the value of an existing ID header is done by calling its ``setId()``
method::

    $msgId = $message->getHeaders()->get('Message-ID');
    $msgId->setId(time() . '.' . uniqid('thing') . '@example.org');

When output via ``toString()``, an ID header produces something like the
following::

    $msgId = $message->getHeaders()->get('Message-ID');
    echo $msgId->toString();

    /*

    Message-ID: <1234955437.499becad62ec2@example.org>

    */

Path Headers
~~~~~~~~~~~~

Path headers are like very-restricted mailbox headers. They contain a single
email address with no associated name. The Return-Path header of a message is a
path header.

You add a new path header to a HeaderSet by calling the HeaderSet's
``addPathHeader()`` method::

    $message = new Swift_Message();
    $headers = $message->getHeaders();
    $headers->addPathHeader('Your-Header-Name', 'person@example.org');

Changing the value of an existing path header is done by calling its
``setAddress()`` method::

    $return = $message->getHeaders()->get('Return-Path');
    $return->setAddress('my-address@example.org');

When output via ``toString()``, a path header produces something like the
following::

    $return = $message->getHeaders()->get('Return-Path');
    $return->setAddress('person@example.org');
    echo $return->toString();

    /*

    Return-Path: <person@example.org>

    */

Header Operations
-----------------

Working with the headers in a message involves knowing how to use the methods
on the HeaderSet and on the individual Headers within the HeaderSet.

Adding new Headers
~~~~~~~~~~~~~~~~~~

New headers can be added to the HeaderSet by using one of the provided
``add..Header()`` methods.

The added header will appear in the message when it is sent::

    // Adding a custom header to a message
    $message = new Swift_Message();
    $headers = $message->getHeaders();
    $headers->addTextHeader('X-Mine', 'something here');

    // Adding a custom header to an attachment
    $attachment = Swift_Attachment::fromPath('/path/to/doc.pdf');
    $attachment->getHeaders()->addDateHeader('X-Created-Time', time());

Retrieving Headers
~~~~~~~~~~~~~~~~~~

Headers are retrieved through the HeaderSet's ``get()`` and ``getAll()``
methods::

    $headers = $message->getHeaders();

    // Get the To: header
    $toHeader = $headers->get('To');

    // Get all headers named "X-Foo"
    $fooHeaders = $headers->getAll('X-Foo');

    // Get the second header named "X-Foo"
    $foo = $headers->get('X-Foo', 1);

    // Get all headers that are present
    $all = $headers->getAll();

When using ``get()`` a single header is returned that matches the name (case
insensitive) that is passed to it. When using ``getAll()`` with a header name,
an array of headers with that name are returned. Calling ``getAll()`` with no
arguments returns an array of all headers present in the entity.

.. note::

    It's valid for some headers to appear more than once in a message (e.g.
    the Received header). For this reason ``getAll()`` exists to fetch all
    headers with a specified name. In addition, ``get()`` accepts an optional
    numerical index, starting from zero to specify which header you want more
    specifically.

.. note::

    If you want to modify the contents of the header and you don't know for
    sure what type of header it is then you may need to check the type by
    calling its ``getFieldType()`` method.

Check if a Header Exists
~~~~~~~~~~~~~~~~~~~~~~~~

You can check if a named header is present in a HeaderSet by calling its
``has()`` method::

    $headers = $message->getHeaders();

    // Check if the To: header exists
    if ($headers->has('To')) {
      echo 'To: exists';
    }

    // Check if an X-Foo header exists twice (i.e. check for the 2nd one)
    if ($headers->has('X-Foo', 1)) {
      echo 'Second X-Foo header exists';
    }

If the header exists, ``true`` will be returned or ``false`` if not.

.. note::

    It's valid for some headers to appear more than once in a message (e.g.
    the Received header). For this reason ``has()`` accepts an optional
    numerical index, starting from zero to specify which header you want to
    check more specifically.

Removing Headers
~~~~~~~~~~~~~~~~

Removing a Header from the HeaderSet is done by calling the HeaderSet's
``remove()`` or ``removeAll()`` methods::

    $headers = $message->getHeaders();

    // Remove the Subject: header
    $headers->remove('Subject');

    // Remove all X-Foo headers
    $headers->removeAll('X-Foo');

    // Remove only the second X-Foo header
    $headers->remove('X-Foo', 1);

When calling ``remove()`` a single header will be removed. When calling
``removeAll()`` all headers with the given name will be removed. If no headers
exist with the given name, no errors will occur.

.. note::

    It's valid for some headers to appear more than once in a message (e.g.
    the Received header). For this reason ``remove()`` accepts an optional
    numerical index, starting from zero to specify which header you want to
    check more specifically. For the same reason, ``removeAll()`` exists to
    remove all headers that have the given name.

Modifying a Header's Content
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To change a Header's content you should know what type of header it is and then
call it's appropriate setter method. All headers also have a
``setFieldBodyModel()`` method that accepts a mixed parameter and delegates to
the correct setter::

The header will be updated inside the HeaderSet and the changes will be seen
when the message is sent::

    $headers = $message->getHeaders();

    // Change the Subject: header
    $subj = $headers->get('Subject');
    $subj->setValue('new subject here');

    // Change the To: header
    $to = $headers->get('To');
    $to->setNameAddresses([
      'person@example.org' => 'Person',
      'thing@example.org'
    ]);

    // Using the setFieldBodyModel() just delegates to the correct method
    // So here to calls setNameAddresses()
    $to->setFieldBodyModel([
      'person@example.org' => 'Person',
      'thing@example.org'
    ]);


================================================
FILE: doc/index.rst
================================================
Swiftmailer
===========

.. toctree::
    :maxdepth: 2

    introduction
    messages
    headers
    sending
    plugins
    japanese


================================================
FILE: doc/introduction.rst
================================================
Swift Mailer: A feature-rich PHP Mailer
=======================================

Swift Mailer is a component based library for sending e-mails from PHP applications.

**Swift Mailer will stop being maintained at the end of November 2021.**

Please, move to `Symfony Mailer <https://symfony.com/doc/current/mailer.html>`_ at your earliest convenience.
`Symfony Mailer <https://symfony.com/doc/current/mailer.html>`_ is the next evolution of Swift Mailer.
It provides the same features with support for modern PHP code and support for third-party providers.

System Requirements
-------------------

Swift Mailer supports PHP 7.0 to PHP 8.1 included (``proc_*`` functions must be
available).

Swift Mailer does not work when used with function overloading as implemented
by ``mbstring`` when ``mbstring.func_overload`` is set to ``2``.

Installation
------------

The recommended way to install Swiftmailer is via Composer:

.. code-block:: bash

    $ composer require "swiftmailer/swiftmailer:^6.0"

Basic Usage
-----------

Here is the simplest way to send emails with Swift Mailer::

    require_once '/path/to/vendor/autoload.php';

    // Create the Transport
    $transport = (new Swift_SmtpTransport('smtp.example.org', 25))
      ->setUsername('your username')
      ->setPassword('your password')
    ;

    // Create the Mailer using your created Transport
    $mailer = new Swift_Mailer($transport);

    // Create a message
    $message = (new Swift_Message('Wonderful Subject'))
      ->setFrom(['john@doe.com' => 'John Doe'])
      ->setTo(['receiver@domain.org', 'other@domain.org' => 'A name'])
      ->setBody('Here is the message itself')
      ;

    // Send the message
    $result = $mailer->send($message);

You can also use Sendmail as a transport::

    // Sendmail
    $transport = new Swift_SendmailTransport('/usr/sbin/sendmail -bs');

Getting Help
------------

For general support, use `Stack Overflow <https://stackoverflow.com>`_.

For bug reports and feature requests, create a new ticket in `GitHub
<https://github.com/swiftmailer/swiftmailer/issues>`_.


================================================
FILE: doc/japanese.rst
================================================
Using Swift Mailer for Japanese Emails
======================================

To send emails in Japanese, you need to tweak the default configuration.

Call the ``Swift::init()`` method with the following code as early as possible
in your code::

    Swift::init(function () {
        Swift_DependencyContainer::getInstance()
            ->register('mime.qpheaderencoder')
            ->asAliasOf('mime.base64headerencoder');

        Swift_Preferences::getInstance()->setCharset('iso-2022-jp');
    });

    /* rest of code goes here */

That's all!


================================================
FILE: doc/messages.rst
================================================
Creating Messages
=================

Creating messages in Swift Mailer is done by making use of the various MIME
entities provided with the library. Complex messages can be quickly created
with very little effort.

Quick Reference
---------------

You can think of creating a Message as being similar to the steps you perform
when you click the Compose button in your mail client. You give it a subject,
specify some recipients, add any attachments and write your message::

    // Create the message
    $message = (new Swift_Message())

      // Give the message a subject
      ->setSubject('Your subject')

      // Set the From address with an associative array
      ->setFrom(['john@doe.com' => 'John Doe'])

      // Set the To addresses with an associative array (setTo/setCc/setBcc)
      ->setTo(['receiver@domain.org', 'other@domain.org' => 'A name'])

      // Give it a body
      ->setBody('Here is the message itself')

      // And optionally an alternative body
      ->addPart('<q>Here is the message itself</q>', 'text/html')

      // Optionally add any attachments
      ->attach(Swift_Attachment::fromPath('my-document.pdf'))
      ;

Message Basics
--------------

A message is a container for anything you want to send to somebody else. There
are several basic aspects of a message that you should know.

An e-mail message is made up of several relatively simple entities that are
combined in different ways to achieve different results. All of these entities
have the same fundamental outline but serve a different purpose. The Message
itself can be defined as a MIME entity, an Attachment is a MIME entity, all
MIME parts are MIME entities -- and so on!

The basic units of each MIME entity -- be it the Message itself, or an
Attachment -- are its Headers and its body:

.. code-block:: text

    Header-Name: A header value
    Other-Header: Another value

    The body content itself

The Headers of a MIME entity, and its body must conform to some strict
standards defined by various RFC documents. Swift Mailer ensures that these
specifications are followed by using various types of object, including
Encoders and different Header types to generate the entity.

The Structure of a Message
~~~~~~~~~~~~~~~~~~~~~~~~~~

Of all of the MIME entities, a message -- ``Swift_Message`` is the largest and
most complex. It has many properties that can be updated and it can contain
other MIME entities -- attachments for example -- nested inside it.

A Message has a lot of different Headers which are there to present information
about the message to the recipients' mail client. Most of these headers will be
familiar to the majority of users, but we'll list the basic ones. Although it's
possible to work directly with the Headers of a Message (or other MIME entity),
the standard Headers have accessor methods provided to abstract away the
complex details for you. For example, although the Date on a message is written
with a strict format, you only need to pass a DateTimeInterface instance to
``setDate()``.

+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------+
| Header                        | Description                                                                                                                        | Accessors                                   |
+===============================+====================================================================================================================================+=============================================+
| ``Message-ID``                | Identifies this message with a unique ID, usually containing the domain name and time generated                                    | ``getId()`` / ``setId()``                   |
+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------+
| ``Return-Path``               | Specifies where bounces should go (Swift Mailer reads this for other uses)                                                         | ``getReturnPath()`` / ``setReturnPath()``   |
+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------+
| ``From``                      | Specifies the address of the person who the message is from. This can be multiple addresses if multiple people wrote the message.  | ``getFrom()`` / ``setFrom()``               |
+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------+
| ``Sender``                    | Specifies the address of the person who physically sent the message (higher precedence than ``From:``)                             | ``getSender()`` / ``setSender()``           |
+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------+
| ``To``                        | Specifies the addresses of the intended recipients                                                                                 | ``getTo()`` / ``setTo()``                   |
+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------+
| ``Cc``                        | Specifies the addresses of recipients who will be copied in on the message                                                         | ``getCc()`` / ``setCc()``                   |
+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------+
| ``Bcc``                       | Specifies the addresses of recipients who the message will be blind-copied to. Other recipients will not be aware of these copies. | ``getBcc()`` / ``setBcc()``                 |
+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------+
| ``Reply-To``                  | Specifies the address where replies are sent to                                                                                    | ``getReplyTo()`` / ``setReplyTo()``         |
+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------+
| ``Subject``                   | Specifies the subject line that is displayed in the recipients' mail client                                                        | ``getSubject()`` / ``setSubject()``         |
+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------+
| ``Date``                      | Specifies the date at which the message was sent                                                                                   | ``getDate()`` / ``setDate()``               |
+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------+
| ``Content-Type``              | Specifies the format of the message (usually ``text/plain`` or ``text/html``)                                                      | ``getContentType()`` / ``setContentType()`` |
+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------+
| ``Content-Transfer-Encoding`` | Specifies the encoding scheme in the message                                                                                       | ``getEncoder()`` / ``setEncoder()``         |
+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------+

Working with a Message Object
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Although there are a lot of available methods on a message object, you only
need to make use of a small subset of them. Usually you'll use
``setSubject()``, ``setTo()`` and ``setFrom()`` before setting the body of your
message with ``setBody()``::

    $message = new Swift_Message();
    $message->setSubject('My subject');

All MIME entities (including a message) have a ``toString()`` method that you
can call if you want to take a look at what is going to be sent. For example,
if you ``echo $message->toString();`` you would see something like this:

.. code-block:: text

    Message-ID: <1230173678.4952f5eeb1432@swift.generated>
    Date: Thu, 25 Dec 2008 13:54:38 +1100
    Subject: Example subject
    From: Chris Corbyn <chris@w3style.co.uk>
    To: Receiver Name <recipient@example.org>
    MIME-Version: 1.0
    Content-Type: text/plain; charset=utf-8
    Content-Transfer-Encoding: quoted-printable

    Here is the message

We'll take a closer look at the methods you use to create your message in the
following sections.

Adding Content to Your Message
------------------------------

Rich content can be added to messages in Swift Mailer with relative ease by
calling methods such as ``setSubject()``, ``setBody()``, ``addPart()`` and
``attach()``.

Setting the Subject Line
~~~~~~~~~~~~~~~~~~~~~~~~

The subject line, displayed in the recipients' mail client can be set with the
``setSubject()`` method, or as a parameter to ``new Swift_Message()``::

    // Pass it as a parameter when you create the message
    $message = new Swift_Message('My amazing subject');

    // Or set it after like this
    $message->setSubject('My amazing subject');

Setting the Body Content
~~~~~~~~~~~~~~~~~~~~~~~~

The body of the message -- seen when the user opens the message -- is specified
by calling the ``setBody()`` method. If an alternative body is to be included,
``addPart()`` can be used.

The body of a message is the main part that is read by the user. Often people
want to send a message in HTML format (``text/html``), other times people want
to send in plain text (``text/plain``), or sometimes people want to send both
versions and allow the recipient to choose how they view the message.

As a rule of thumb, if you're going to send a HTML email, always include a
plain-text equivalent of the same content so that users who prefer to read
plain text can do so.

If the recipient's mail client offers preferences for displaying text vs. HTML
then the mail client will present that part to the user where available. In
other cases the mail client will display the "best" part it can - usually HTML
if you've included HTML::

    // Pass it as a parameter when you create the message
    $message = new Swift_Message('Subject here', 'My amazing body');

    // Or set it after like this
    $message->setBody('My <em>amazing</em> body', 'text/html');

    // Add alternative parts with addPart()
    $message->addPart('My amazing body in plain text', 'text/plain');

Attaching Files
---------------

Attachments are downloadable parts of a message and can be added by calling the
``attach()`` method on the message. You can add attachments that exist on disk,
or you can create attachments on-the-fly.

Although we refer to files sent over e-mails as "attachments" -- because
they're attached to the message -- lots of other parts of the message are
actually "attached" even if we don't refer to these parts as attachments.

File attachments are created by the ``Swift_Attachment`` class and then
attached to the message via the ``attach()`` method on it. For all of the
"every day" MIME types such as all image formats, word documents, PDFs and
spreadsheets you don't need to explicitly set the content-type of the
attachment, though it would do no harm to do so. For less common formats you
should set the content-type -- which we'll cover in a moment.

Attaching Existing Files
~~~~~~~~~~~~~~~~~~~~~~~~

Files that already exist, either on disk or at a URL can be attached to a
message with just one line of code, using ``Swift_Attachment::fromPath()``.

You can attach files that exist locally, or if your PHP installation has
``allow_url_fopen`` turned on you can attach files from other
websites.

The attachment will be presented to the recipient as a downloadable file with
the same filename as the one you attached::

    // Create the attachment
    // * Note that you can technically leave the content-type parameter out
    $attachment = Swift_Attachment::fromPath('/path/to/image.jpg', 'image/jpeg');

    // Attach it to the message
    $message->attach($attachment);

    // The two statements above could be written in one line instead
    $message->attach(Swift_Attachment::fromPath('/path/to/image.jpg'));

    // You can attach files from a URL if allow_url_fopen is on in php.ini
    $message->attach(Swift_Attachment::fromPath('http://site.tld/logo.png'));

Setting the Filename
~~~~~~~~~~~~~~~~~~~~

Usually you don't need to explicitly set the filename of an attachment because
the name of the attached file will be used by default, but if you want to set
the filename you use the ``setFilename()`` method of the Attachment.

The attachment will be attached in the normal way, but meta-data sent inside
the email will rename the file to something else::

    // Create the attachment and call its setFilename() method
    $attachment = Swift_Attachment::fromPath('/path/to/image.jpg')
      ->setFilename('cool.jpg');

    // Because there's a fluid interface, you can do this in one statement
    $message->attach(
      Swift_Attachment::fromPath('/path/to/image.jpg')->setFilename('cool.jpg')
    );

Attaching Dynamic Content
~~~~~~~~~~~~~~~~~~~~~~~~~

Files that are generated at runtime, such as PDF documents or images created
via GD can be attached directly to a message without writing them out to disk.
Use ``Swift_Attachment`` directly.

The attachment will be presented to the recipient as a downloadable file
with the filename and content-type you specify::

    // Create your file contents in the normal way, but don't write them to disk
    $data = create_my_pdf_data();

    // Create the attachment with your data
    $attachment = new Swift_Attachment($data, 'my-file.pdf', 'application/pdf');

    // Attach it to the message
    $message->attach($attachment);


    // You can alternatively use method chaining to build the attachment
    $attachment = (new Swift_Attachment())
      ->setFilename('my-file.pdf')
      ->setContentType('application/pdf')
      ->setBody($data)
      ;

.. note::

    If you would usually write the file to disk anyway you should just attach
    it with ``Swift_Attachment::fromPath()`` since this will use less memory.

Changing the Disposition
~~~~~~~~~~~~~~~~~~~~~~~~

Attachments just appear as files that can be saved to the Desktop if desired.
You can make attachment appear inline where possible by using the
``setDisposition()`` method of an attachment.

The attachment will be displayed within the email viewing window if the mail
client knows how to display it::

    // Create the attachment and call its setDisposition() method
    $attachment = Swift_Attachment::fromPath('/path/to/image.jpg')
      ->setDisposition('inline');


    // Because there's a fluid interface, you can do this in one statement
    $message->attach(
      Swift_Attachment::fromPath('/path/to/image.jpg')->setDisposition('inline')
    );

.. note::

    If you try to create an inline attachment for a non-displayable file type
    such as a ZIP file, the mail client should just present the attachment as
    normal.

Embedding Inline Media Files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Often, people want to include an image or other content inline with a HTML
message. It's easy to do this with HTML linking to remote resources, but this
approach is usually blocked by mail clients. Swift Mailer allows you to embed
your media directly into the message.

Mail clients usually block downloads from remote resources because this
technique was often abused as a mean of tracking who opened an email. If
you're sending a HTML email and you want to include an image in the message
another approach you can take is to embed the image directly.

Swift Mailer makes embedding files into messages extremely streamlined. You
embed a file by calling the ``embed()`` method of the message,
which returns a value you can use in a ``src`` or
``href`` attribute in your HTML.

Just like with attachments, it's possible to embed dynamically generated
content without having an existing file available.

The embedded files are sent in the email as a special type of attachment that
has a unique ID used to reference them within your HTML attributes. On mail
clients that do not support embedded files they may appear as attachments.

Although this is commonly done for images, in theory it will work for any
displayable (or playable) media type. Support for other media types (such as
video) is dependent on the mail client however.

Embedding Existing Files
........................

Files that already exist, either on disk or at a URL can be embedded in a
message with just one line of code, using ``Swift_EmbeddedFile::fromPath()``.

You can embed files that exist locally, or if your PHP installation has
``allow_url_fopen`` turned on you can embed files from other websites.

The file will be displayed with the message inline with the HTML wherever its ID
is used as a ``src`` attribute::

    // Create the message
    $message = new Swift_Message('My subject');

    // Set the body
    $message->setBody(
    '<html>' .
    ' <body>' .
    '  Here is an image <img src="' . // Embed the file
         $message->embed(Swift_Image::fromPath('image.png')) .
       '" alt="Image" />' .
    '  Rest of message' .
    ' </body>' .
    '</html>',
      'text/html' // Mark the content-type as HTML
    );

    // You can embed files from a URL if allow_url_fopen is on in php.ini
    $message->setBody(
    '<html>' .
    ' <body>' .
    '  Here is an image <img src="' .
         $message->embed(Swift_Image::fromPath('http://site.tld/logo.png')) .
       '" alt="Image" />' .
    '  Rest of message' .
    ' </body>' .
    '</html>',
      'text/html'
    );

.. note::

    ``Swift_Image`` and ``Swift_EmbeddedFile`` are just aliases of one another.
    ``Swift_Image`` exists for semantic purposes.

.. note::

    You can embed files in two stages if you prefer. Just capture the return
    value of ``embed()`` in a variable and use that as the ``src`` attribute::

        // If placing the embed() code inline becomes cumbersome
        // it's easy to do this in two steps
        $cid = $message->embed(Swift_Image::fromPath('image.png'));

        $message->setBody(
        '<html>' .
        ' <body>' .
        '  Here is an image <img src="' . $cid . '" alt="Image" />' .
        '  Rest of message' .
        ' </body>' .
        '</html>',
          'text/html' // Mark the content-type as HTML
        );

Embedding Dynamic Content
.........................

Images that are generated at runtime, such as images created via GD can be
embedded directly to a message without writing them out to disk. Use the
standard ``new Swift_Image()`` method.

The file will be displayed with the message inline with the HTML wherever its ID
is used as a ``src`` attribute::

    // Create your file contents in the normal way, but don't write them to disk
    $img_data = create_my_image_data();

    // Create the message
    $message = new Swift_Message('My subject');

    // Set the body
    $message->setBody(
    '<html>' .
    ' <body>' .
    '  Here is an image <img src="' . // Embed the file
         $message->embed(new Swift_Image($img_data, 'image.jpg', 'image/jpeg')) .
       '" alt="Image" />' .
    '  Rest of message' .
    ' </body>' .
    '</html>',
      'text/html' // Mark the content-type as HTML
    );

.. note::

    ``Swift_Image`` and ``Swift_EmbeddedFile`` are just aliases of one another.
    ``Swift_Image`` exists for semantic purposes.

.. note::

    You can embed files in two stages if you prefer. Just capture the return
    value of ``embed()`` in a variable and use that as the ``src`` attribute::

        // If placing the embed() code inline becomes cumbersome
        // it's easy to do this in two steps
        $cid = $message->embed(new Swift_Image($img_data, 'image.jpg', 'image/jpeg'));

        $message->setBody(
        '<html>' .
        ' <body>' .
        '  Here is an image <img src="' . $cid . '" alt="Image" />' .
        '  Rest of message' .
        ' </body>' .
        '</html>',
          'text/html' // Mark the content-type as HTML
        );

Adding Recipients to Your Message
---------------------------------

Recipients are specified within the message itself via ``setTo()``, ``setCc()``
and ``setBcc()``. Swift Mailer reads these recipients from the message when it
gets sent so that it knows where to send the message to.

Message recipients are one of three types:

* ``To:`` recipients -- the primary recipients (required)

* ``Cc:`` recipients -- receive a copy of the message (optional)

* ``Bcc:`` recipients -- hidden from other recipients (optional)

Each type can contain one, or several addresses. It's possible to list only the
addresses of the recipients, or you can personalize the address by providing
the real name of the recipient.

Make sure to add only valid email addresses as recipients. If you try to add an
invalid email address with ``setTo()``, ``setCc()`` or ``setBcc()``, Swift
Mailer will throw a ``Swift_RfcComplianceException``.

If you add recipients automatically based on a data source that may contain
invalid email addresses, you can prevent possible exceptions by validating the
addresses using::

    use Egulias\EmailValidator\EmailValidator;
    use Egulias\EmailValidator\Validation\RFCValidation;

    $validator = new EmailValidator();
    $validator->isValid("example@example.com", new RFCValidation()); //true

and only adding addresses that validate. Another way would be to wrap your ``setTo()``, ``setCc()`` and
``setBcc()`` calls in a try-catch block and handle the
``Swift_RfcComplianceException`` in the catch block.

.. sidebar:: Syntax for Addresses

    If you only wish to refer to a single email address (for example your
    ``From:`` address) then you can just use a string::

          $message->setFrom('some@address.tld');

    If you want to include a name then you must use an associative array::

         $message->setFrom(['some@address.tld' => 'The Name']);

    If you want to include multiple addresses then you must use an array::

         $message->setTo(['some@address.tld', 'other@address.tld']);

    You can mix personalized (addresses with a name) and non-personalized
    addresses in the same list by mixing the use of associative and
    non-associative array syntax::

         $message->setTo([
           'recipient-with-name@example.org' => 'Recipient Name One',
           'no-name@example.org', // Note that this is not a key-value pair
           'named-recipient@example.org' => 'Recipient Name Two'
         ]);

Setting ``To:`` Recipients
~~~~~~~~~~~~~~~~~~~~~~~~~~

``To:`` recipients are required in a message and are set with the ``setTo()``
or ``addTo()`` methods of the message.

To set ``To:`` recipients, create the message object using either ``new
Swift_Message( ... )``, then call the ``setTo()`` method with a complete array
of addresses, or use the ``addTo()`` method to iteratively add recipients.

The ``setTo()`` method accepts input in various formats as described earlier in
this chapter. The ``addTo()`` method takes either one or two parameters. The
first being the email address and the second optional parameter being the name
of the recipient.

``To:`` recipients are visible in the message headers and will be seen by the
other recipients::

    // Using setTo() to set all recipients in one go
    $message->setTo([
      'person1@example.org',
      'person2@otherdomain.org' => 'Person 2 Name',
      'person3@example.org',
      'person4@example.org',
      'person5@example.org' => 'Person 5 Name'
    ]);

.. note::

    Multiple calls to ``setTo()`` will not add new recipients -- each
    call overrides the previous calls. If you want to iteratively add
    recipients, use the ``addTo()`` method::

        // Using addTo() to add recipients iteratively
        $message->addTo('person1@example.org');
        $message->addTo('person2@example.org', 'Person 2 Name');

Setting ``Cc:`` Recipients
~~~~~~~~~~~~~~~~~~~~~~~~~~

``Cc:`` recipients are set with the ``setCc()`` or ``addCc()`` methods of the
message.

To set ``Cc:`` recipients, create the message object using either ``new
Swift_Message( ... )``, then call the ``setCc()`` method with a complete array
of addresses, or use the ``addCc()`` method to iteratively add recipients.

The ``setCc()`` method accepts input in various formats as described earlier in
this chapter. The ``addCc()`` method takes either one or two parameters. The
first being the email address and the second optional parameter being the name
of the recipient.

``Cc:`` recipients are visible in the message headers and will be seen by the
other recipients::

    // Using setTo() to set all recipients in one go
    $message->setTo([
      'person1@example.org',
      'person2@otherdomain.org' => 'Person 2 Name',
      'person3@example.org',
      'person4@example.org',
      'person5@example.org' => 'Person 5 Name'
    ]);

.. note::

    Multiple calls to ``setCc()`` will not add new recipients -- each call
    overrides the previous calls. If you want to iteratively add Cc:
    recipients, use the ``addCc()`` method::

        // Using addCc() to add recipients iteratively
        $message->addCc('person1@example.org');
        $message->addCc('person2@example.org', 'Person 2 Name');

Setting ``Bcc:`` Recipients
~~~~~~~~~~~~~~~~~~~~~~~~~~~

``Bcc:`` recipients receive a copy of the message without anybody else knowing
it, and are set with the ``setBcc()`` or ``addBcc()`` methods of the message.

To set ``Bcc:`` recipients, create the message object using either ``new
Swift_Message( ... )``, then call the ``setBcc()`` method with a complete array
of addresses, or use the ``addBcc()`` method to iteratively add recipients.

The ``setBcc()`` method accepts input in various formats as described earlier
in this chapter. The ``addBcc()`` method takes either one or two parameters.
The first being the email address and the second optional parameter being the
name of the recipient.

Only the individual ``Bcc:`` recipient will see their address in the message
headers. Other recipients (including other ``Bcc:`` recipients) will not see
the address::

    // Using setBcc() to set all recipients in one go
    $message->setBcc([
      'person1@example.org',
      'person2@otherdomain.org' => 'Person 2 Name',
      'person3@example.org',
      'person4@example.org',
      'person5@example.org' => 'Person 5 Name'
    ]);

.. note::

    Multiple calls to ``setBcc()`` will not add new recipients -- each call
    overrides the previous calls. If you want to iteratively add Bcc:
    recipients, use the ``addBcc()`` method::

        // Using addBcc() to add recipients iteratively
        $message->addBcc('person1@example.org');
        $message->addBcc('person2@example.org', 'Person 2 Name');

.. sidebar:: Internationalized Email Addresses

    Traditionally only ASCII characters have been allowed in email addresses.
    With the introduction of internationalized domain names (IDNs), non-ASCII
    characters may appear in the domain name. By default, Swiftmailer encodes
    such domain names in Punycode (e.g. xn--xample-ova.invalid). This is
    compatible with all mail servers.

    RFC 6531 introduced an SMTP extension, SMTPUTF8, that allows non-ASCII
    characters in email addresses on both sides of the @ sign. To send to such
    addresses, your outbound SMTP server must support the SMTPUTF8 extension.
    You should use the ``Swift_AddressEncoder_Utf8AddressEncoder`` address
    encoder and enable the ``Swift_Transport_Esmtp_SmtpUtf8Handler`` SMTP
    extension handler::

        $smtpUtf8 = new Swift_Transport_Esmtp_SmtpUtf8Handler();
        $transport->setExtensionHandlers([$smtpUtf8]);
        $utf8Encoder = new Swift_AddressEncoder_Utf8AddressEncoder();
        $transport->setAddressEncoder($utf8Encoder);

Specifying Sender Details
-------------------------

An email must include information about who sent it. Usually this is managed by
the ``From:`` address, however there are other options.

The sender information is contained in three possible places:

* ``From:`` -- the address(es) of who wrote the message (required)

* ``Sender:`` -- the address of the single person who sent the message
  (optional)

* ``Return-Path:`` -- the address where bounces should go to (optional)

You must always include a ``From:`` address by using ``setFrom()`` on the
message. Swift Mailer will use this as the default ``Return-Path:`` unless
otherwise specified.

The ``Sender:`` address exists because the person who actually sent the email
may not be the person who wrote the email. It has a higher precedence than the
``From:`` address and will be used as the ``Return-Path:`` unless otherwise
specified.

Setting the ``From:`` Address
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A ``From:`` address is required and is set with the ``setFrom()`` method of the
message. ``From:`` addresses specify who actually wrote the email, and usually
who sent it.

What most people probably don't realize is that you can have more than one
``From:`` address if more than one person wrote the email -- for example if an
email was put together by a committee.

The ``From:`` address(es) are visible in the message headers and will be seen
by the recipients.

.. note::

    If you set multiple ``From:`` addresses then you absolutely must set a
    ``Sender:`` address to indicate who physically sent the message.

::

    // Set a single From: address
    $message->setFrom('your@address.tld');

    // Set a From: address including a name
    $message->setFrom(['your@address.tld' => 'Your Name']);

    // Set multiple From: addresses if multiple people wrote the email
    $message->setFrom([
      'person1@example.org' => 'Sender One',
      'person2@example.org' => 'Sender Two'
    ]);

Setting the ``Sender:`` Address
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A ``Sender:`` address specifies who sent the message and is set with the
``setSender()`` method of the message.

The ``Sender:`` address is visible in the message headers and will be seen by
the recipients.

This address will be used as the ``Return-Path:`` unless otherwise specified.

.. note::

    If you set multiple ``From:`` addresses then you absolutely must set a
    ``Sender:`` address to indicate who physically sent the message.

You must not set more than one sender address on a message because it's not
possible for more than one person to send a single message::

    $message->setSender('your@address.tld');

Setting the ``Return-Path:`` (Bounce) Address
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The ``Return-Path:`` address specifies where bounce notifications should be
sent and is set with the ``setReturnPath()`` method of the message.

You can only have one ``Return-Path:`` and it must not include a personal name.

Bounce notifications will be sent to this address::

    $message->setReturnPath('bounces@address.tld');

Signed/Encrypted Message
------------------------

To increase the integrity/security of a message it is possible to sign and/or
encrypt an message using one or multiple signers.

S/MIME
~~~~~~

S/MIME can sign and/or encrypt a message using the OpenSSL extension.

When signing a message, the signer creates a signature of the entire content of
the message (including attachments).

The certificate and private key must be PEM encoded, and can be either created
using for example OpenSSL or obtained at an official Certificate Authority (CA).

**The recipient must have the CA certificate in the list of trusted issuers in
order to verify the signature.**

**Make sure the certificate supports emailProtection.**

When using OpenSSL this can done by the including the *-addtrust
emailProtection* parameter when creating the certificate::

    $message = new Swift_Message();

    $smimeSigner = new Swift_Signers_SMimeSigner();
    $smimeSigner->setSignCertificate('/path/to/certificate.pem', '/path/to/private-key.pem');
    $message->attachSigner($smimeSigner);

When the private key is secured using a passphrase use the following instead::

    $message = new Swift_Message();

    $smimeSigner = new Swift_Signers_SMimeSigner();
    $smimeSigner->setSignCertificate('/path/to/certificate.pem', ['/path/to/private-key.pem', 'passphrase']);
    $message->attachSigner($smimeSigner);

By default the signature is added as attachment, making the message still
readable for mailing agents not supporting signed messages.

Storing the message as binary is also possible but not recommended::

    $smimeSigner->setSignCertificate('/path/to/certificate.pem', '/path/to/private-key.pem', PKCS7_BINARY);

When encrypting the message (also known as enveloping), the entire message
(including attachments) is encrypted using a certificate, and the recipient can
then decrypt the message using corresponding private key.

Encrypting ensures nobody can read the contents of the message without the
private key.

Normally the recipient provides a certificate for encrypting and keeping the
decryption key private.

Using both signing and encrypting is also possible::

    $message = new Swift_Message();

    $smimeSigner = new Swift_Signers_SMimeSigner();
    $smimeSigner->setSignCertificate('/path/to/sign-certificate.pem', '/path/to/private-key.pem');
    $smimeSigner->setEncryptCertificate('/path/to/encrypt-certificate.pem');
    $message->attachSigner($smimeSigner);

The used encryption cipher can be set as the second parameter of
setEncryptCertificate()

See https://secure.php.net/manual/openssl.ciphers for a list of supported ciphers.

By default the message is first signed and then encrypted, this can be changed
by adding::

    $smimeSigner->setSignThenEncrypt(false);

**Changing this is not recommended as most mail agents don't support this
none-standard way.**

Only when having trouble with sign then encrypt method, this should be changed.

Requesting a Read Receipt
-------------------------

It is possible to request a read-receipt to be sent to an address when the
email is opened. To request a read receipt set the address with
``setReadReceiptTo()``::

    $message->setReadReceiptTo('your@address.tld');

When the email is opened, if the mail client supports it a notification will be
sent to this address.

.. note::

    Read receipts won't work for the majority of recipients since many mail
    clients auto-disable them. Those clients that will send a read receipt
    will make the user aware that one has been requested.

Setting the Character Set
-------------------------

The character set of the message (and its MIME parts) is set with the
``setCharset()`` method. You can also change the global default of UTF-8 by
working with the ``Swift_Preferences`` class.

Swift Mailer will default to the UTF-8 character set unless otherwise
overridden. UTF-8 will work in most instances since it includes all of the
standard US keyboard characters in addition to most international characters.

It is absolutely vital however that you know what character set your message
(or it's MIME parts) are written in otherwise your message may be received
completely garbled.

There are two places in Swift Mailer where you can change the character set:

* In the ``Swift_Preferences`` class

* On each individual message and/or MIME part

To set the character set of your Message:

* Change the global UTF-8 setting by calling
  ``Swift_Preferences::setCharset()``; or

* Call the ``setCharset()`` method on the message or the MIME part::

    // Approach 1: Change the global setting (suggested)
    Swift_Preferences::getInstance()->setCharset('iso-8859-2');

    // Approach 2: Call the setCharset() method of the message
    $message = (new Swift_Message())
      ->setCharset('iso-8859-2');

    // Approach 3: Specify the charset when setting the body
    $message->setBody('My body', 'text/html', 'iso-8859-2');

    // Approach 4: Specify the charset for each part added
    $message->addPart('My part', 'text/plain', 'iso-8859-2');

Setting the Encoding
--------------------

The body of each MIME part needs to be encoded. Binary attachments are encoded
in base64 using the ``Swift_Mime_ContentEncoder_Base64ContentEncoder``. Text
parts are traditionally encoded in quoted-printable using
``Swift_Mime_ContentEncoder_QpContentEncoder`` or
``Swift_Mime_ContentEncoder_NativeQpContentEncoder``.

The encoder of the message or MIME part is set with the ``setEncoder()`` method.

Quoted-printable is the safe choice, because it converts 8-bit text as 7-bit.
Most modern SMTP servers support 8-bit text. This is advertised via the 8BITMIME
SMTP extension. If your outbound SMTP server supports this SMTP extension, and
it supports downgrading the message (e.g converting to quoted-printable on the
fly) when delivering to a downstream server that does not support the extension,
you may wish to use ``Swift_Mime_ContentEncoder_PlainContentEncoder`` in
``8bit`` mode instead. This has the advantage that the source data is slightly
more readable and compact, especially for non-Western languages.

        $eightBitMime = new Swift_Transport_Esmtp_EightBitMimeHandler();
        $transport->setExtensionHandlers([$eightBitMime]);
        $plainEncoder = new Swift_Mime_ContentEncoder_PlainContentEncoder('8bit');
        $message->setEncoder($plainEncoder);

Setting the Line Length
-----------------------

The length of lines in a message can be changed by using the
``setMaxLineLength()`` method on the message::

    $message->setMaxLineLength(1000);

Swift Mailer defaults to using 78 characters per line in a message. This is
done for historical reasons and so that the message can be easily viewed in
plain-text terminals

Lines that are longer than the line length specified will be wrapped between
words.

.. note::

    You should never set a maximum length longer than 1000 characters
    according to RFC 2822. Doing so could have unspecified side-effects such
    as truncating parts of your message when it is transported between SMTP
    servers.

Setting the Message Priority
----------------------------

You can change the priority of the message with ``setPriority()``. Setting the
priority will not change the way your email is sent -- it is purely an
indicative setting for the recipient::

    // Indicate "High" priority
    $message->setPriority(2);

The priority of a message is an indication to the recipient what significance
it has. Swift Mailer allows you to set the priority by calling the
``setPriority`` method. This method takes an integer value between 1 and 5:

* ``Swift_Mime_SimpleMessage::PRIORITY_HIGHEST``: 1
* ``Swift_Mime_SimpleMessage::PRIORITY_HIGH``: 2
* ``Swift_Mime_SimpleMessage::PRIORITY_NORMAL``: 3
* ``Swift_Mime_SimpleMessage::PRIORITY_LOW``: 4
* ``Swift_Mime_SimpleMessage::PRIORITY_LOWEST``: 5

::

    // Or use the constant to be more explicit
    $message->setPriority(Swift_Mime_SimpleMessage::PRIORITY_HIGH);


================================================
FILE: doc/notes/CHARSETS
================================================
Following is a list of character sets along with their widths:
--------------------------------------------------------------

1 Octet 8bit:
-------------
Windows 125* (CP125*)
CP*
ANSI
ISO-8859-* (IEC-8859-*)
Macintosh (Mac OS Roman)
KOI8-U (potentially KOI*8-*)
KOI8-R
MIK
Cork (T1)
ISCII
VISCII


1 Octet 7bit:
-------------
US-ASCII
K0I7

2 octets 16 bit:
----------------
UCS-2
UTF-16* (UTF-16BE etc)

4-octets 32 bit:
----------------
UCS-4
UTF-32

Variable-width:
----------------------------
Big5 - http://en.wikipedia.org/wiki/Big5 (1-2 bytes: 00-7f=1, 81-fe=2)
HKSCS - http://en.wikipedia.org/wiki/HKSCS (a big5 variant, but some variants use 10646)
ISO-10646 (IEC-10646) - http://en.wikipedia.org/wiki/ISO_10646 (unicode)
UTF-8 (1-5 bytes)
ISO-2022 (IEC-2022) - http://en.wikipedia.org/wiki/ISO_2022
Shift-JIS - http://en.wikipedia.org/wiki/Shift-JIS

A good resource:
----------------
http://en.wikipedia.org/wiki/Character_encoding#Simple_character_sets



================================================
FILE: doc/notes/rfc/rfc0821.txt
================================================

                                                                        

   RFC 821
                                    
                                    
                                    
                                    
                                    
                     SIMPLE MAIL TRANSFER PROTOCOL
                                    
                                    
                                    
                           Jonathan B. Postel





























                              August 1982
                                    
                                    
                                    
                     Information Sciences Institute
                   University of Southern California
                           4676 Admiralty Way
                   Marina del Rey, California  90291

                             (213) 822-1511



                                                                        
RFC 821                                                      August 1982
                                           Simple Mail Transfer Protocol



                           TABLE OF CONTENTS

   1.  INTRODUCTION .................................................. 1

   2.  THE SMTP MODEL ................................................ 2

   3.  THE SMTP PROCEDURE ............................................ 4

      3.1.  Mail ..................................................... 4
      3.2.  Forwarding ............................................... 7
      3.3.  Verifying and Expanding .................................. 8
      3.4.  Sending and Mailing ..................................... 11
      3.5.  Opening and Closing ..................................... 13
      3.6.  Relaying ................................................ 14
      3.7.  Domains ................................................. 17
      3.8.  Changing Roles .......................................... 18

   4.  THE SMTP SPECIFICATIONS ...................................... 19

      4.1.  SMTP Commands ........................................... 19
      4.1.1.  Command Semantics ..................................... 19
      4.1.2.  Command Syntax ........................................ 27
      4.2.  SMTP Replies ............................................ 34
      4.2.1.  Reply Codes by Function Group ......................... 35
      4.2.2.  Reply Codes in Numeric Order .......................... 36
      4.3.  Sequencing of Commands and Replies ...................... 37
      4.4.  State Diagrams .......................................... 39
      4.5.  Details ................................................. 41
      4.5.1.  Minimum Implementation ................................ 41
      4.5.2.  Transparency .......................................... 41
      4.5.3.  Sizes ................................................. 42

   APPENDIX A:  TCP ................................................. 44
   APPENDIX B:  NCP ................................................. 45
   APPENDIX C:  NITS ................................................ 46
   APPENDIX D:  X.25 ................................................ 47
   APPENDIX E:  Theory of Reply Codes ............................... 48
   APPENDIX F:  Scenarios ........................................... 51

   GLOSSARY ......................................................... 64

   REFERENCES ....................................................... 67




Network Working Group                                          J. Postel
Request for Comments: DRAFT                                          ISI
Replaces: RFC 788, 780, 772                                  August 1982

                     SIMPLE MAIL TRANSFER PROTOCOL


1.  INTRODUCTION

   The objective of Simple Mail Transfer Protocol (SMTP) is to transfer
   mail reliably and efficiently.

   SMTP is independent of the particular transmission subsystem and
   requires only a reliable ordered data stream channel.  Appendices A,
   B, C, and D describe the use of SMTP with various transport services.
   A Glossary provides the definitions of terms as used in this
   document.

   An important feature of SMTP is its capability to relay mail across
   transport service environments.  A transport service provides an
   interprocess communication environment (IPCE).  An IPCE may cover one
   network, several networks, or a subset of a network.  It is important
   to realize that transport systems (or IPCEs) are not one-to-one with
   networks.  A process can communicate directly with another process
   through any mutually known IPCE.  Mail is an application or use of
   interprocess communication.  Mail can be communicated between
   processes in different IPCEs by relaying through a process connected
   to two (or more) IPCEs.  More specifically, mail can be relayed
   between hosts on different transport systems by a host on both
   transport systems.
























Postel                                                          [Page 1]


                                                                        
August 1982                                                      RFC 821
Simple Mail Transfer Protocol                                           



2.  THE SMTP MODEL

   The SMTP design is based on the following model of communication:  as
   the result of a user mail request, the sender-SMTP establishes a
   two-way transmission channel to a receiver-SMTP.  The receiver-SMTP
   may be either the ultimate destination or an intermediate.  SMTP
   commands are generated by the sender-SMTP and sent to the
   receiver-SMTP.  SMTP replies are sent from the receiver-SMTP to the
   sender-SMTP in response to the commands.

   Once the transmission channel is established, the SMTP-sender sends a
   MAIL command indicating the sender of the mail.  If the SMTP-receiver
   can accept mail it responds with an OK reply.  The SMTP-sender then
   sends a RCPT command identifying a recipient of the mail.  If the
   SMTP-receiver can accept mail for that recipient it responds with an
   OK reply; if not, it responds with a reply rejecting that recipient
   (but not the whole mail transaction).  The SMTP-sender and
   SMTP-receiver may negotiate several recipients.  When the recipients
   have been negotiated the SMTP-sender sends the mail data, terminating
   with a special sequence.  If the SMTP-receiver successfully processes
   the mail data it responds with an OK reply.  The dialog is purposely
   lock-step, one-at-a-time.

     -------------------------------------------------------------

   
               +----------+                +----------+
   +------+    |          |                |          |
   | User |<-->|          |      SMTP      |          |
   +------+    |  Sender- |Commands/Replies| Receiver-|
   +------+    |   SMTP   |<-------------->|    SMTP  |    +------+
   | File |<-->|          |    and Mail    |          |<-->| File |
   |System|    |          |                |          |    |System|
   +------+    +----------+                +----------+    +------+
   

                Sender-SMTP                Receiver-SMTP

                           Model for SMTP Use

                                Figure 1

     -------------------------------------------------------------

   The SMTP provides mechanisms for the transmission of mail; directly
   from the sending user's host to the receiving user's host when the



[Page 2]                                                          Postel


                                                                        
RFC 821                                                      August 1982
                                           Simple Mail Transfer Protocol



   two host are connected to the same transport service, or via one or
   more relay SMTP-servers when the source and destination hosts are not
   connected to the same transport service.

   To be able to provide the relay capability the SMTP-server must be
   supplied with the name of the ultimate destination host as well as
   the destination mailbox name.

   The argument to the MAIL command is a reverse-path, which specifies
   who the mail is from.  The argument to the RCPT command is a
   forward-path, which specifies who the mail is to.  The forward-path
   is a source route, while the reverse-path is a return route (which
   may be used to return a message to the sender when an error occurs
   with a relayed message).

   When the same message is sent to multiple recipients the SMTP
   encourages the transmission of only one copy of the data for all the
   recipients at the same destination host.

   The mail commands and replies have a rigid syntax.  Replies also have
   a numeric code.  In the following, examples appear which use actual
   commands and replies.  The complete lists of commands and replies
   appears in Section 4 on specifications.

   Commands and replies are not case sensitive.  That is, a command or
   reply word may be upper case, lower case, or any mixture of upper and
   lower case.  Note that this is not true of mailbox user names.  For
   some hosts the user name is case sensitive, and SMTP implementations
   must take case to preserve the case of user names as they appear in
   mailbox arguments.  Host names are not case sensitive.

   Commands and replies are composed of characters from the ASCII
   character set [1].  When the transport service provides an 8-bit byte
   (octet) transmission channel, each 7-bit character is transmitted
   right justified in an octet with the high order bit cleared to zero.

   When specifying the general form of a command or reply, an argument
   (or special symbol) will be denoted by a meta-linguistic variable (or
   constant), for example, "<string>" or "<reverse-path>".  Here the
   angle brackets indicate these are meta-linguistic variables.
   However, some arguments use the angle brackets literally.  For
   example, an actual reverse-path is enclosed in angle brackets, i.e.,
   "<John.Smith@USC-ISI.ARPA>" is an instance of <reverse-path> (the
   angle brackets are actually transmitted in the command or reply).





Postel                                                          [Page 3]


                                                                        
August 1982                                                      RFC 821
Simple Mail Transfer Protocol                                           



3.  THE SMTP PROCEDURES

   This section presents the procedures used in SMTP in several parts.
   First comes the basic mail procedure defined as a mail transaction.
   Following this are descriptions of forwarding mail, verifying mailbox
   names and expanding mailing lists, sending to terminals instead of or
   in combination with mailboxes, and the opening and closing exchanges.
   At the end of this section are comments on relaying, a note on mail
   domains, and a discussion of changing roles.  Throughout this section
   are examples of partial command and reply sequences, several complete
   scenarios are presented in Appendix F.

   3.1.  MAIL

      There are three steps to SMTP mail transactions.  The transaction
      is started with a MAIL command which gives the sender
      identification.  A series of one or more RCPT commands follows
      giving the receiver information.  Then a DATA command gives the
      mail data.  And finally, the end of mail data indicator confirms
      the transaction.

         The first step in the procedure is the MAIL command.  The
         <reverse-path> contains the source mailbox.

            MAIL <SP> FROM:<reverse-path> <CRLF>

         This command tells the SMTP-receiver that a new mail
         transaction is starting and to reset all its state tables and
         buffers, including any recipients or mail data.  It gives the
         reverse-path which can be used to report errors.  If accepted,
         the receiver-SMTP returns a 250 OK reply.

         The <reverse-path> can contain more than just a mailbox.  The
         <reverse-path> is a reverse source routing list of hosts and
         source mailbox.  The first host in the <reverse-path> should be
         the host sending this command.

         The second step in the procedure is the RCPT command.

            RCPT <SP> TO:<forward-path> <CRLF>

         This command gives a forward-path identifying one recipient.
         If accepted, the receiver-SMTP returns a 250 OK reply, and
         stores the forward-path.  If the recipient is unknown the
         receiver-SMTP returns a 550 Failure reply.  This second step of
         the procedure can be repeated any number of times.



[Page 4]                                                          Postel


                                                                        
RFC 821                                                      August 1982
                                           Simple Mail Transfer Protocol



         The <forward-path> can contain more than just a mailbox.  The
         <forward-path> is a source routing list of hosts and the
         destination mailbox.  The first host in the <forward-path>
         should be the host receiving this command.

         The third step in the procedure is the DATA command.

            DATA <CRLF>

         If accepted, the receiver-SMTP returns a 354 Intermediate reply
         and considers all succeeding lines to be the message text.
         When the end of text is received and stored the SMTP-receiver
         sends a 250 OK reply.

         Since the mail data is sent on the transmission channel the end
         of the mail data must be indicated so that the command and
         reply dialog can be resumed.  SMTP indicates the end of the
         mail data by sending a line containing only a period.  A
         transparency procedure is used to prevent this from interfering
         with the user's text (see Section 4.5.2).

            Please note that the mail data includes the memo header
            items such as Date, Subject, To, Cc, From [2].

         The end of mail data indicator also confirms the mail
         transaction and tells the receiver-SMTP to now process the
         stored recipients and mail data.  If accepted, the
         receiver-SMTP returns a 250 OK reply.  The DATA command should
         fail only if the mail transaction was incomplete (for example,
         no recipients), or if resources are not available.

      The above procedure is an example of a mail transaction.  These
      commands must be used only in the order discussed above.
      Example 1 (below) illustrates the use of these commands in a mail
      transaction.














Postel                                                          [Page 5]


                                                                        
August 1982                                                      RFC 821
Simple Mail Transfer Protocol                                           



      -------------------------------------------------------------

                     Example of the SMTP Procedure

         This SMTP example shows mail sent by Smith at host Alpha.ARPA,
         to Jones, Green, and Brown at host Beta.ARPA.  Here we assume
         that host Alpha contacts host Beta directly.

            S: MAIL FROM:<Smith@Alpha.ARPA>
            R: 250 OK

            S: RCPT TO:<Jones@Beta.ARPA>
            R: 250 OK

            S: RCPT TO:<Green@Beta.ARPA>
            R: 550 No such user here

            S: RCPT TO:<Brown@Beta.ARPA>
            R: 250 OK

            S: DATA
            R: 354 Start mail input; end with <CRLF>.<CRLF>
            S: Blah blah blah...
            S: ...etc. etc. etc.
            S: <CRLF>.<CRLF>
            R: 250 OK

         The mail has now been accepted for Jones and Brown.  Green did
         not have a mailbox at host Beta.

                               Example 1

      -------------------------------------------------------------
















[Page 6]                                                          Postel


                                                                        
RFC 821                                                      August 1982
                                           Simple Mail Transfer Protocol



   3.2.  FORWARDING

      There are some cases where the destination information in the
      <forward-path> is incorrect, but the receiver-SMTP knows the
      correct destination.  In such cases, one of the following replies
      should be used to allow the sender to contact the correct
      destination.

         251 User not local; will forward to <forward-path>

            This reply indicates that the receiver-SMTP knows the user's
            mailbox is on another host and indicates the correct
            forward-path to use in the future.  Note that either the
            host or user or both may be different.  The receiver takes
            responsibility for delivering the message.

         551 User not local; please try <forward-path>

            This reply indicates that the receiver-SMTP knows the user's
            mailbox is on another host and indicates the correct
            forward-path to use.  Note that either the host or user or
            both may be different.  The receiver refuses to accept mail
            for this user, and the sender must either redirect the mail
            according to the information provided or return an error
            response to the originating user.

      Example 2 illustrates the use of these responses.

      -------------------------------------------------------------

                         Example of Forwarding

      Either

      S: RCPT TO:<Postel@USC-ISI.ARPA>
      R: 251 User not local; will forward to <Postel@USC-ISIF.ARPA>

      Or

      S: RCPT TO:<Paul@USC-ISIB.ARPA>
      R: 551 User not local; please try <Mockapetris@USC-ISIF.ARPA>

                               Example 2

      -------------------------------------------------------------




Postel                                                          [Page 7]


                                                                        
August 1982                                                      RFC 821
Simple Mail Transfer Protocol                                           



   3.3.  VERIFYING AND EXPANDING

      SMTP provides as additional features, commands to verify a user
      name or expand a mailing list.  This is done with the VRFY and
      EXPN commands, which have character string arguments.  For the
      VRFY command, the string is a user name, and the response may
      include the full name of the user and must include the mailbox of
      the user.  For the EXPN command, the string identifies a mailing
      list, and the multiline response may include the full name of the
      users and must give the mailboxes on the mailing list.

      "User name" is a fuzzy term and used purposely.  If a host
      implements the VRFY or EXPN commands then at least local mailboxes
      must be recognized as "user names".  If a host chooses to
      recognize other strings as "user names" that is allowed.

      In some hosts the distinction between a mailing list and an alias
      for a single mailbox is a bit fuzzy, since a common data structure
      may hold both types of entries, and it is possible to have mailing
      lists of one mailbox.  If a request is made to verify a mailing
      list a positive response can be given if on receipt of a message
      so addressed it will be delivered to everyone on the list,
      otherwise an error should be reported (e.g., "550 That is a
      mailing list, not a user").  If a request is made to expand a user
      name a positive response can be formed by returning a list
      containing one name, or an error can be reported (e.g., "550 That
      is a user name, not a mailing list").

      In the case of a multiline reply (normal for EXPN) exactly one
      mailbox is to be specified on each line of the reply.  In the case
      of an ambiguous request, for example, "VRFY Smith", where there
      are two Smith's the response must be "553 User ambiguous".

      The case of verifying a user name is straightforward as shown in
      example 3.














[Page 8]                                                          Postel


                                                                        
RFC 821                                                      August 1982
                                           Simple Mail Transfer Protocol



      -------------------------------------------------------------

                    Example of Verifying a User Name

         Either

            S: VRFY Smith
            R: 250 Fred Smith <Smith@USC-ISIF.ARPA>

         Or

            S: VRFY Smith
            R: 251 User not local; will forward to <Smith@USC-ISIQ.ARPA>

         Or

            S: VRFY Jones
            R: 550 String does not match anything.

         Or

            S: VRFY Jones
            R: 551 User not local; please try <Jones@USC-ISIQ.ARPA>

         Or

            S: VRFY Gourzenkyinplatz
            R: 553 User ambiguous.

                               Example 3

      -------------------------------------------------------------

















Postel                                                          [Page 9]


                                                                        
August 1982                                                      RFC 821
Simple Mail Transfer Protocol                                           



      The case of expanding a mailbox list requires a multiline reply as
      shown in example 4.

      -------------------------------------------------------------

                  Example of Expanding a Mailing List

         Either

            S: EXPN Example-People
            R: 250-Jon Postel <Postel@USC-ISIF.ARPA>
            R: 250-Fred Fonebone <Fonebone@USC-ISIQ.ARPA>
            R: 250-Sam Q. Smith <SQSmith@USC-ISIQ.ARPA>
            R: 250-Quincy Smith <@USC-ISIF.ARPA:Q-Smith@ISI-VAXA.ARPA>
            R: 250-<joe@foo-unix.ARPA>
            R: 250 <xyz@bar-unix.ARPA>

         Or

            S: EXPN Executive-Washroom-List
            R: 550 Access Denied to You.

                               Example 4

      -------------------------------------------------------------

      The character string arguments of the VRFY and EXPN commands
      cannot be further restricted due to the variety of implementations
      of the user name and mailbox list concepts.  On some systems it
      may be appropriate for the argument of the EXPN command to be a
      file name for a file containing a mailing list, but again there is
      a variety of file naming conventions in the Internet.

      The VRFY and EXPN commands are not included in the minimum
      implementation (Section 4.5.1), and are not required to work
      across relays when they are implemented.













[Page 10]                                                         Postel


                                                                        
RFC 821                                                      August 1982
                                           Simple Mail Transfer Protocol



   3.4.  SENDING AND MAILING

      The main purpose of SMTP is to deliver messages to user's
      mailboxes.  A very similar service provided by some hosts is to
      deliver messages to user's terminals (provided the user is active
      on the host).  The delivery to the user's mailbox is called
      "mailing", the delivery to the user's terminal is called
      "sending".  Because in many hosts the implementation of sending is
      nearly identical to the implementation of mailing these two
      functions are combined in SMTP.  However the sending commands are
      not included in the required minimum implementation
      (Section 4.5.1).  Users should have the ability to control the
      writing of messages on their terminals.  Most hosts permit the
      users to accept or refuse such messages.

      The following three command are defined to support the sending
      options.  These are used in the mail transaction instead of the
      MAIL command and inform the receiver-SMTP of the special semantics
      of this transaction:

         SEND <SP> FROM:<reverse-path> <CRLF>

            The SEND command requires that the mail data be delivered to
            the user's terminal.  If the user is not active (or not
            accepting terminal messages) on the host a 450 reply may
            returned to a RCPT command.  The mail transaction is
            successful if the message is delivered the terminal.

         SOML <SP> FROM:<reverse-path> <CRLF>

            The Send Or MaiL command requires that the mail data be
            delivered to the user's terminal if the user is active (and
            accepting terminal messages) on the host.  If the user is
            not active (or not accepting terminal messages) then the
            mail data is entered into the user's mailbox.  The mail
            transaction is successful if the message is delivered either
            to the terminal or the mailbox.

         SAML <SP> FROM:<reverse-path> <CRLF>

            The Send And MaiL command requires that the mail data be
            delivered to the user's terminal if the user is active (and
            accepting terminal messages) on the host.  In any case the
            mail data is entered into the user's mailbox.  The mail
            transaction is successful if the message is delivered the
            mailbox.



Postel                                                         [Page 11]


                                                                        
August 1982                                                      RFC 821
Simple Mail Transfer Protocol                                           



      The same reply codes that are used for the MAIL commands are used
      for these commands.















































[Page 12]                                                         Postel


                                                                        
RFC 821                                                      August 1982
                                           Simple Mail Transfer Protocol



   3.5.  OPENING AND CLOSING

      At the time the transmission channel is opened there is an
      exchange to ensure that the hosts are communicating with the hosts
      they think they are.

      The following two commands are used in transmission channel
      opening and closing:

         HELO <SP> <domain> <CRLF>

         QUIT <CRLF>

      In the HELO command the host sending the command identifies
      itself; the command may be interpreted as saying "Hello, I am
      <domain>".

      -------------------------------------------------------------

                     Example of Connection Opening

         R: 220 BBN-UNIX.ARPA Simple Mail Transfer Service Ready
         S: HELO USC-ISIF.ARPA
         R: 250 BBN-UNIX.ARPA

                               Example 5

      -------------------------------------------------------------

      -------------------------------------------------------------

                     Example of Connection Closing

         S: QUIT
         R: 221 BBN-UNIX.ARPA Service closing transmission channel

                               Example 6

      -------------------------------------------------------------










Postel                                                         [Page 13]


                                                                        
August 1982                                                      RFC 821
Simple Mail Transfer Protocol                                           



   3.6.  RELAYING

      The forward-path may be a source route of the form
      "@ONE,@TWO:JOE@THREE", where ONE, TWO, and THREE are hosts.  This
      form is used to emphasize the distinction between an address and a
      route.  The mailbox is an absolute address, and the route is
      information about how to get there.  The two concepts should not
      be confused.

      Conceptually the elements of the forward-path are moved to the
      reverse-path as the message is relayed from one server-SMTP to
      another.  The reverse-path is a reverse source route, (i.e., a
      source route from the current location of the message to the
      originator of the message).  When a server-SMTP deletes its
      identifier from the forward-path and inserts it into the
      reverse-path, it must use the name it is known by in the
      environment it is sending into, not the environment the mail came
      from, in case the server-SMTP is known by different names in
      different environments.

      If when the message arrives at an SMTP the first element of the
      forward-path is not the identifier of that SMTP the element is not
      deleted from the forward-path and is used to determine the next
      SMTP to send the message to.  In any case, the SMTP adds its own
      identifier to the reverse-path.

      Using source routing the receiver-SMTP receives mail to be relayed
      to another server-SMTP  The receiver-SMTP may accept or reject the
      task of relaying the mail in the same way it accepts or rejects
      mail for a local user.  The receiver-SMTP transforms the command
      arguments by moving its own identifier from the forward-path to
      the beginning of the reverse-path.  The receiver-SMTP then becomes
      a sender-SMTP, establishes a transmission channel to the next SMTP
      in the forward-path, and sends it the mail.

      The first host in the reverse-path should be the host sending the
      SMTP commands, and the first host in the forward-path should be
      the host receiving the SMTP commands.

      Notice that the forward-path and reverse-path appear in the SMTP
      commands and replies, but not necessarily in the message.  That
      is, there is no need for these paths and especially this syntax to
      appear in the "To:" , "From:", "CC:", etc. fields of the message
      header.

      If a server-SMTP has accepted the task of relaying the mail and



[Page 14]                                                         Postel


                                                                        
RFC 821                                                      August 1982
                                           Simple Mail Transfer Protocol



      later finds that the forward-path is incorrect or that the mail
      cannot be delivered for whatever reason, then it must construct an
      "undeliverable mail" notification message and send it to the
      originator of the undeliverable mail (as indicated by the
      reverse-path).

      This notification message must be from the server-SMTP at this
      host.  Of course, server-SMTPs should not send notification
      messages about problems with notification messages.  One way to
      prevent loops in error reporting is to specify a null reverse-path
      in the MAIL command of a notification message.  When such a
      message is relayed it is permissible to leave the reverse-path
      null.  A MAIL command with a null reverse-path appears as follows:

         MAIL FROM:<>

      An undeliverable mail notification message is shown in example 7.
      This notification is in response to a message originated by JOE at
      HOSTW and sent via HOSTX to HOSTY with instructions to relay it on
      to HOSTZ.  What we see in the example is the transaction between
      HOSTY and HOSTX, which is the first step in the return of the
      notification message.



























Postel                                                         [Page 15]


                                                                        
August 1982                                                      RFC 821
Simple Mail Transfer Protocol                                           



      -------------------------------------------------------------

            Example Undeliverable Mail Notification Message

         S: MAIL FROM:<>
         R: 250 ok
         S: RCPT TO:<@HOSTX.ARPA:JOE@HOSTW.ARPA>
         R: 250 ok
         S: DATA
         R: 354 send the mail data, end with .
         S: Date: 23 Oct 81 11:22:33
         S: From: SMTP@HOSTY.ARPA
         S: To: JOE@HOSTW.ARPA
         S: Subject: Mail System Problem
         S:
         S:   Sorry JOE, your message to SAM@HOSTZ.ARPA lost.
         S:   HOSTZ.ARPA said this:
         S:    "550 No Such User"
         S: .
         R: 250 ok

                               Example 7

      -------------------------------------------------------------

























[Page 16]                                                         Postel


                                                                        
RFC 821                                                      August 1982
                                           Simple Mail Transfer Protocol



   3.7.  DOMAINS

      Domains are a recently introduced concept in the ARPA Internet
      mail system.  The use of domains changes the address space from a
      flat global space of simple character string host names to a
      hierarchically structured rooted tree of global addresses.  The
      host name is replaced by a domain and host designator which is a
      sequence of domain element strings separated by periods with the
      understanding that the domain elements are ordered from the most
      specific to the most general.

      For example, "USC-ISIF.ARPA", "Fred.Cambridge.UK", and
      "PC7.LCS.MIT.ARPA" might be host-and-domain identifiers.

      Whenever domain names are used in SMTP only the official names are
      used, the use of nicknames or aliases is not allowed.

































Postel                                                         [Page 17]


                                                                        
August 1982                                                      RFC 821
Simple Mail Transfer Protocol                                           



   3.8.  CHANGING ROLES

      The TURN command may be used to reverse the roles of the two
      programs communicating over the transmission channel.

      If program-A is currently the sender-SMTP and it sends the TURN
      command and receives an ok reply (250) then program-A becomes the
      receiver-SMTP.

      If program-B is currently the receiver-SMTP and it receives the
      TURN command and sends an ok reply (250) then program-B becomes
      the sender-SMTP.

      To refuse to change roles the receiver sends the 502 reply.

      Please note that this command is optional.  It would not normally
      be used in situations where the transmission channel is TCP.
      However, when the cost of establishing the transmission channel is
      high, this command may be quite useful.  For example, this command
      may be useful in supporting be mail exchange using the public
      switched telephone system as a transmission channel, especially if
      some hosts poll other hosts for mail exchanges.



























[Page 18]                                                         Postel


                                                                        
RFC 821                                                      August 1982
                                           Simple Mail Transfer Protocol



4.  THE SMTP SPECIFICATIONS

   4.1.  SMTP COMMANDS

      4.1.1.  COMMAND SEMANTICS

         The SMTP commands define the mail transfer or the mail system
         function requested by the user.  SMTP commands are character
         strings terminated by <CRLF>.  The command codes themselves are
         alphabetic characters terminated by <SP> if parameters follow
         and <CRLF> otherwise.  The syntax of mailboxes must conform to
         receiver site conventions.  The SMTP commands are discussed
         below.  The SMTP replies are discussed in the Section 4.2.

         A mail transaction involves several data objects which are
         communicated as arguments to different commands.  The
         reverse-path is the argument of the MAIL command, the
         forward-path is the argument of the RCPT command, and the mail
         data is the argument of the DATA command.  These arguments or
         data objects must be transmitted and held pending the
         confirmation communicated by the end of mail data indication
         which finalizes the transaction.  The model for this is that
         distinct buffers are provided to hold the types of data
         objects, that is, there is a reverse-path buffer, a
         forward-path buffer, and a mail data buffer.  Specific commands
         cause information to be appended to a specific buffer, or cause
         one or more buffers to be cleared.

         HELLO (HELO)

            This command is used to identify the sender-SMTP to the
            receiver-SMTP.  The argument field contains the host name of
            the sender-SMTP.

            The receiver-SMTP identifies itself to the sender-SMTP in
            the connection greeting reply, and in the response to this
            command.

            This command and an OK reply to it confirm that both the
            sender-SMTP and the receiver-SMTP are in the initial state,
            that is, there is no transaction in progress and all state
            tables and buffers are cleared.







Postel                                                         [Page 19]


                                                                        
August 1982                                                      RFC 821
Simple Mail Transfer Protocol                                           



         MAIL (MAIL)

            This command is used to initiate a mail transaction in which
            the mail data is delivered to one or more mailboxes.  The
            argument field contains a reverse-path.

            The reverse-path consists of an optional list of hosts and
            the sender mailbox.  When the list of hosts is present, it
            is a "reverse" source route and indicates that the mail was
            relayed through each host on the list (the first host in the
            list was the most recent relay).  This list is used as a
            source route to return non-delivery notices to the sender.
            As each relay host adds itself to the beginning of the list,
            it must use its name as known in the IPCE to which it is
            relaying the mail rather than the IPCE from which the mail
            came (if they are different).  In some types of error
            reporting messages (for example, undeliverable mail
            notifications) the reverse-path may be null (see Example 7).

            This command clears the reverse-path buffer, the
            forward-path buffer, and the mail data buffer; and inserts
            the reverse-path information from this command into the
            reverse-path buffer.

         RECIPIENT (RCPT)

            This command is used to identify an individual recipient of
            the mail data; multiple recipients are specified by multiple
            use of this command.

            The forward-path consists of an optional list of hosts and a
            required destination mailbox.  When the list of hosts is
            present, it is a source route and indicates that the mail
            must be relayed to the next host on the list.  If the
            receiver-SMTP does not implement the relay function it may
            user the same reply it would for an unknown local user
            (550).

            When mail is relayed, the relay host must remove itself from
            the beginning forward-path and put itself at the beginning
            of the reverse-path.  When mail reaches its ultimate
            destination (the forward-path contains only a destination
            mailbox), the receiver-SMTP inserts it into the destination
            mailbox in accordance with its host mail conventions.





[Page 20]                                                         Postel


                                                                        
RFC 821                                                      August 1982
                                           Simple Mail Transfer Protocol



               For example, mail received at relay host A with arguments

                  FROM:<USERX@HOSTY.ARPA>
                  TO:<@HOSTA.ARPA,@HOSTB.ARPA:USERC@HOSTD.ARPA>

               will be relayed on to host B with arguments

                  FROM:<@HOSTA.ARPA:USERX@HOSTY.ARPA>
                  TO:<@HOSTB.ARPA:USERC@HOSTD.ARPA>.

            This command causes its forward-path argument to be appended
            to the forward-path buffer.

         DATA (DATA)

            The receiver treats the lines following the command as mail
            data from the sender.  This command causes the mail data
            from this command to be appended to the mail data buffer.
            The mail data may contain any of the 128 ASCII character
            codes.

            The mail data is terminated by a line containing only a
            period, that is the character sequence "<CRLF>.<CRLF>" (see
            Section 4.5.2 on Transparency).  This is the end of mail
            data indication.

            The end of mail data indication requires that the receiver
            must now process the stored mail transaction information.
            This processing consumes the information in the reverse-path
            buffer, the forward-path buffer, and the mail data buffer,
            and on the completion of this command these buffers are
            cleared.  If the processing is successful the receiver must
            send an OK reply.  If the processing fails completely the
            receiver must send a failure reply.

            When the receiver-SMTP accepts a message either for relaying
            or for final delivery it inserts at the beginning of the
            mail data a time stamp line.  The time stamp line indicates
            the identity of the host that sent the message, and the
            identity of the host that received the message (and is
            inserting this time stamp), and the date and time the
            message was received.  Relayed messages will have multiple
            time stamp lines.

            When the receiver-SMTP makes the "final delivery" of a
            message it inserts at the beginning of the mail data a



Postel                                                         [Page 21]


                                                                        
August 1982                                                      RFC 821
Simple Mail Transfer Protocol                                           



            return path line.  The return path line preserves the
            information in the <reverse-path> from the MAIL command.
            Here, final delivery means the message leaves the SMTP
            world.  Normally, this would mean it has been delivered to
            the destination user, but in some cases it may be further
            processed and transmitted by another mail system.

               It is possible for the mailbox in the return path be
               different from the actual sender's mailbox, for example,
               if error responses are to be delivered a special error
               handling mailbox rather than the message senders.

            The preceding two paragraphs imply that the final mail data
            will begin with a  return path line, followed by one or more
            time stamp lines.  These lines will be followed by the mail
            data header and body [2].  See Example 8.

            Special mention is needed of the response and further action
            required when the processing following the end of mail data
            indication is partially successful.  This could arise if
            after accepting several recipients and the mail data, the
            receiver-SMTP finds that the mail data can be successfully
            delivered to some of the recipients, but it cannot be to
            others (for example, due to mailbox space allocation
            problems).  In such a situation, the response to the DATA
            command must be an OK reply.  But, the receiver-SMTP must
            compose and send an "undeliverable mail" notification
            message to the originator of the message.  Either a single
            notification which lists all of the recipients that failed
            to get the message, or separate notification messages must
            be sent for each failed recipient (see Example 7).  All
            undeliverable mail notification messages are sent using the
            MAIL command (even if they result from processing a SEND,
            SOML, or SAML command).















[Page 22]                                                         Postel


                                                                        
RFC 821                                                      August 1982
                                           Simple Mail Transfer Protocol



     -------------------------------------------------------------

            Example of Return Path and Received Time Stamps

      Return-Path: <@GHI.ARPA,@DEF.ARPA,@ABC.ARPA:JOE@ABC.ARPA>   
      Received: from GHI.ARPA by JKL.ARPA ; 27 Oct 81 15:27:39 PST
      Received: from DEF.ARPA by GHI.ARPA ; 27 Oct 81 15:15:13 PST
      Received: from ABC.ARPA by DEF.ARPA ; 27 Oct 81 15:01:59 PST
      Date: 27 Oct 81 15:01:01 PST                                
      From: JOE@ABC.ARPA                                          
      Subject: Improved Mailing System Installed                  
      To: SAM@JKL.ARPA                                            
                                    
      This is to inform you that ...                              

                               Example 8

     -------------------------------------------------------------

         SEND (SEND)

            This command is used to initiate a mail transaction in which
            the mail data is delivered to one or more terminals.  The
            argument field contains a reverse-path.  This command is
            successful if the message is delivered to a terminal.

            The reverse-path consists of an optional list of hosts and
            the sender mailbox.  When the list of hosts is present, it
            is a "reverse" source route and indicates that the mail was
            relayed through each host on the list (the first host in the
            list was the most recent relay).  This list is used as a
            source route to return non-delivery notices to the sender.
            As each relay host adds itself to the beginning of the list,
            it must use its name as known in the IPCE to which it is
            relaying the mail rather than the IPCE from which the mail
            came (if they are different).

            This command clears the reverse-path buffer, the
            forward-path buffer, and the mail data buffer; and inserts
            the reverse-path information from this command into the
            reverse-path buffer.

         SEND OR MAIL (SOML)

            This command is used to initiate a mail transaction in which
            the mail data is delivered to one or more terminals or



Postel                                                         [Page 23]


                                                                        
August 1982                                                      RFC 821
Simple Mail Transfer Protocol                                           



            mailboxes. For each recipient the mail data is delivered to
            the recipient's terminal if the recipient is active on the
            host (and accepting terminal messages), otherwise to the
            recipient's mailbox.  The argument field contains a
            reverse-path.  This command is successful if the message is
            delivered to a terminal or the mailbox.

            The reverse-path consists of an optional list of hosts and
            the sender mailbox.  When the list of hosts is present, it
            is a "reverse" source route and indicates that the mail was
            relayed through each host on the list (the first host in the
            list was the most recent relay).  This list is used as a
            source route to return non-delivery notices to the sender.
            As each relay host adds itself to the beginning of the list,
            it must use its name as known in the IPCE to which it is
            relaying the mail rather than the IPCE from which the mail
            came (if they are different).

            This command clears the reverse-path buffer, the
            forward-path buffer, and the mail data buffer; and inserts
            the reverse-path information from this command into the
            reverse-path buffer.

         SEND AND MAIL (SAML)

            This command is used to initiate a mail transaction in which
            the mail data is delivered to one or more terminals and
            mailboxes. For each recipient the mail data is delivered to
            the recipient's terminal if the recipient is active on the
            host (and accepting terminal messages), and for all
            recipients to the recipient's mailbox.  The argument field
            contains a reverse-path.  This command is successful if the
            message is delivered to the mailbox.

            The reverse-path consists of an optional list of hosts and
            the sender mailbox.  When the list of hosts is present, it
            is a "reverse" source route and indicates that the mail was
            relayed through each host on the list (the first host in the
            list was the most recent relay).  This list is used as a
            source route to return non-delivery notices to the sender.
            As each relay host adds itself to the beginning of the list,
            it must use its name as known in the IPCE to which it is
            relaying the mail rather than the IPCE from which the mail
            came (if they are different).

            This command clears the reverse-path buffer, the



[Page 24]                                                         Postel


                                                                        
RFC 821                                                      August 1982
                                           Simple Mail Transfer Protocol



            forward-path buffer, and the mail data buffer; and inserts
            the reverse-path information from this command into the
            reverse-path buffer.

         RESET (RSET)

            This command specifies that the current mail transaction is
            to be aborted.  Any stored sender, recipients, and mail data
            must be discarded, and all buffers and state tables cleared.
            The receiver must send an OK reply.

         VERIFY (VRFY)

            This command asks the receiver to confirm that the argument
            identifies a user.  If it is a user name, the full name of
            the user (if known) and the fully specified mailbox are
            returned.

            This command has no effect on any of the reverse-path
            buffer, the forward-path buffer, or the mail data buffer.

         EXPAND (EXPN)

            This command asks the receiver to confirm that the argument
            identifies a mailing list, and if so, to return the
            membership of that list.  The full name of the users (if
            known) and the fully specified mailboxes are returned in a
            multiline reply.

            This command has no effect on any of the reverse-path
            buffer, the forward-path buffer, or the mail data buffer.

         HELP (HELP)

            This command causes the receiver to send helpful information
            to the sender of the HELP command.  The command may take an
            argument (e.g., any command name) and return more specific
            information as a response.

            This command has no effect on any of the reverse-path
            buffer, the forward-path buffer, or the mail data buffer.








Postel                                                         [Page 25]


                                                                        
August 1982                                                      RFC 821
Simple Mail Transfer Protocol                                           



         NOOP (NOOP)

            This command does not affect any parameters or previously
            entered commands.  It specifies no action other than that
            the receiver send an OK reply.

            This command has no effect on any of the reverse-path
            buffer, the forward-path buffer, or the mail data buffer.

         QUIT (QUIT)

            This command specifies that the receiver must send an OK
            reply, and then close the transmission channel.

            The receiver should not close the transmission channel until
            it receives and replies to a QUIT command (even if there was
            an error).  The sender should not close the transmission
            channel until it send a QUIT command and receives the reply
            (even if there was an error response to a previous command).
            If the connection is closed prematurely the receiver should
            act as if a RSET command had been received (canceling any
            pending transaction, but not undoing any previously
            completed transaction), the sender should act as if the
            command or transaction in progress had received a temporary
            error (4xx).

         TURN (TURN)

            This command specifies that the receiver must either (1)
            send an OK reply and then take on the role of the
            sender-SMTP, or (2) send a refusal reply and retain the role
            of the receiver-SMTP.

            If program-A is currently the sender-SMTP and it sends the
            TURN command and receives an OK reply (250) then program-A
            becomes the receiver-SMTP.  Program-A is then in the initial
            state as if the transmission channel just opened, and it
            then sends the 220 service ready greeting.

            If program-B is currently the receiver-SMTP and it receives
            the TURN command and sends an OK reply (250) then program-B
            becomes the sender-SMTP.  Program-B is then in the initial
            state as if the transmission channel just opened, and it
            then expects to receive the 220 service ready greeting.

            To refuse to change roles the receiver sends the 502 reply.



[Page 26]                                                         Postel


                                                                        
RFC 821                                                      August 1982
                                           Simple Mail Transfer Protocol



         There are restrictions on the order in which these command may
         be used.

            The first command in a session must be the HELO command.
            The HELO command may be used later in a session as well.  If
            the HELO command argument is not acceptable a 501 failure
            reply must be returned and the receiver-SMTP must stay in
            the same state.

            The NOOP, HELP, EXPN, and VRFY commands can be used at any
            time during a session.

            The MAIL, SEND, SOML, or SAML commands begin a mail
            transaction.  Once started a mail transaction consists of
            one of the transaction beginning commands, one or more RCPT
            commands, and a DATA command, in that order.  A mail
            transaction may be aborted by the RSET command.  There may
            be zero or more transactions in a session.

            If the transaction beginning command argument is not
            acceptable a 501 failure reply must be returned and the
            receiver-SMTP must stay in the same state.  If the commands
            in a transaction are out of order a 503 failure reply must
            be returned and the receiver-SMTP must stay in the same
            state.

            The last command in a session must be the QUIT command.  The
            QUIT command can not be used at any other time in a session.

      4.1.2.  COMMAND SYNTAX

         The commands consist of a command code followed by an argument
         field.  Command codes are four alphabetic characters.  Upper
         and lower case alphabetic characters are to be treated
         identically.  Thus, any of the following may represent the mail
         command:

            MAIL    Mail    mail    MaIl    mAIl

         This also applies to any symbols representing parameter values,
         such as "TO" or "to" for the forward-path.  Command codes and
         the argument fields are separated by one or more spaces.
         However, within the reverse-path and forward-path arguments
         case is important.  In particular, in some hosts the user
         "smith" is different from the user "Smith".




Postel                                                         [Page 27]


                                                                        
August 1982                                                      RFC 821
Simple Mail Transfer Protocol                                           



         The argument field consists of a variable length character
         string ending with the character sequence <CRLF>.  The receiver
         is to take no action until this sequence is received.

         Square brackets denote an optional argument field.  If the
         option is not taken, the appropriate default is implied.











































[Page 28]                                                         Postel


                                                                        
RFC 821                                                      August 1982
                                           Simple Mail Transfer Protocol



         The following are the SMTP commands:

            HELO <SP> <domain> <CRLF>

            MAIL <SP> FROM:<reverse-path> <CRLF>

            RCPT <SP> TO:<forward-path> <CRLF>

            DATA <CRLF>

            RSET <CRLF>

            SEND <SP> FROM:<reverse-path> <CRLF>

            SOML <SP> FROM:<reverse-path> <CRLF>

            SAML <SP> FROM:<reverse-path> <CRLF>

            VRFY <SP> <string> <CRLF>

            EXPN <SP> <string> <CRLF>

            HELP [<SP> <string>] <CRLF>

            NOOP <CRLF>

            QUIT <CRLF>

            TURN <CRLF>




















Postel                                                         [Page 29]


                                                                        
August 1982                                                      RFC 821
Simple Mail Transfer Protocol                                           



         The syntax of the above argument fields (using BNF notation
         where applicable) is given below.  The "..." notation indicates
         that a field may be repeated one or more times.

            <reverse-path> ::= <path>

            <forward-path> ::= <path>

            <path> ::= "<" [ <a-d-l> ":" ] <mailbox> ">"

            <a-d-l> ::= <at-domain> | <at-domain> "," <a-d-l>

            <at-domain> ::= "@" <domain>

            <domain> ::=  <element> | <element> "." <domain>

            <element> ::= <name> | "#" <number> | "[" <dotnum> "]"

            <mailbox> ::= <local-part> "@" <domain>

            <local-part> ::= <dot-string> | <quoted-string>

            <name> ::= <a> <ldh-str> <let-dig>

            <ldh-str> ::= <let-dig-hyp> | <let-dig-hyp> <ldh-str>

            <let-dig> ::= <a> | <d>

            <let-dig-hyp> ::= <a> | <d> | "-"

            <dot-string> ::= <string> | <string> "." <dot-string>

            <string> ::= <char> | <char> <string>

            <quoted-string> ::=  """ <qtext> """

            <qtext> ::=  "\" <x> | "\" <x> <qtext> | <q> | <q> <qtext>

            <char> ::= <c> | "\" <x>

            <dotnum> ::= <snum> "." <snum> "." <snum> "." <snum>

            <number> ::= <d> | <d> <number>

            <CRLF> ::= <CR> <LF>




[Page 30]                                                         Postel


                                                                        
RFC 821                                                      August 1982
                                           Simple Mail Transfer Protocol



            <CR> ::= the carriage return character (ASCII code 13)

            <LF> ::= the line feed character (ASCII code 10)

            <SP> ::= the space character (ASCII code 32)

            <snum> ::= one, two, or three digits representing a decimal
                      integer value in the range 0 through 255

            <a> ::= any one of the 52 alphabetic characters A through Z
                      in upper case and a through z in lower case

            <c> ::= any one of the 128 ASCII characters, but not any
                      <special> or <SP>

            <d> ::= any one of the ten digits 0 through 9

            <q> ::= any one of the 128 ASCII characters except <CR>,
                      <LF>, quote ("), or backslash (\)

            <x> ::= any one of the 128 ASCII characters (no exceptions)

            <special> ::= "<" | ">" | "(" | ")" | "[" | "]" | "\" | "."
                      | "," | ";" | ":" | "@"  """ | the control
                      characters (ASCII codes 0 through 31 inclusive and
                      127)

         Note that the backslash, "\", is a quote character, which is
         used to indicate that the next character is to be used
         literally (instead of its normal interpretation).  For example,
         "Joe\,Smith" could be used to indicate a single nine character
         user field with comma being the fourth character of the field.

         Hosts are generally known by names which are translated to
         addresses in each host.  Note that the name elements of domains
         are the official names -- no use of nicknames or aliases is
         allowed.

         Sometimes a host is not known to the translation function and
         communication is blocked.  To bypass this barrier two numeric
         forms are also allowed for host "names".  One form is a decimal
         integer prefixed by a pound sign, "#", which indicates the
         number is the address of the host.  Another form is four small
         decimal integers separated by dots and enclosed by brackets,
         e.g., "[123.255.37.2]", which indicates a 32-bit ARPA Internet
         Address in four 8-bit fields.



Postel                                                         [Page 31]


                                                                        
August 1982                                                      RFC 821
Simple Mail Transfer Protocol                                           



         The time stamp line and the return path line are formally
         defined as follows:

         <return-path-line> ::= "Return-Path:" <SP><reverse-path><CRLF>

         <time-stamp-line> ::= "Received:" <SP> <stamp> <CRLF>

            <stamp> ::= <from-domain> <by-domain> <opt-info> ";"
                      <daytime>

            <from-domain> ::= "FROM" <SP> <domain> <SP>

            <by-domain> ::= "BY" <SP> <domain> <SP>

            <opt-info> ::= [<via>] [<with>] [<id>] [<for>]

            <via> ::= "VIA" <SP> <link> <SP>

            <with> ::= "WITH" <SP> <protocol> <SP>

            <id> ::= "ID" <SP> <string> <SP>

            <for> ::= "FOR" <SP> <path> <SP>

            <link> ::= The standard names for links are registered with
                      the Network Information Center.

            <protocol> ::= The standard names for protocols are
                      registered with the Network Information Center.

            <daytime> ::= <SP> <date> <SP> <time>

            <date> ::= <dd> <SP> <mon> <SP> <yy>

            <time> ::= <hh> ":" <mm> ":" <ss> <SP> <zone>

            <dd> ::= the one or two decimal integer day of the month in
                      the range 1 to 31.

            <mon> ::= "JAN" | "FEB" | "MAR" | "APR" | "MAY" | "JUN" |
                      "JUL" | "AUG" | "SEP" | "OCT" | "NOV" | "DEC"

            <yy> ::= the two decimal integer year of the century in the
                      range 00 to 99.





[Page 32]                                                         Postel


                                                                        
RFC 821                                                      August 1982
                                           Simple Mail Transfer Protocol



            <hh> ::= the two decimal integer hour of the day in the
                      range 00 to 24.

            <mm> ::= the two decimal integer minute of the hour in the
                      range 00 to 59.

            <ss> ::= the two decimal integer second of the minute in the
                      range 00 to 59.

            <zone> ::= "UT" for Universal Time (the default) or other
                      time zone designator (as in [2]).

            

     -------------------------------------------------------------

                          Return Path Example

         Return-Path: <@CHARLIE.ARPA,@BAKER.ARPA:JOE@ABLE.ARPA>

                               Example 9

     -------------------------------------------------------------

     -------------------------------------------------------------

                        Time Stamp Line Example

      Received: FROM ABC.ARPA BY XYZ.ARPA ; 22 OCT 81 09:23:59 PDT

         Received: from ABC.ARPA by XYZ.ARPA via TELENET with X25
                   id M12345 for Smith@PDQ.ARPA ; 22 OCT 81 09:23:59 PDT

                               Example 10

      -------------------------------------------------------------













Postel                                                         [Page 33]


                                                                        
August 1982                                                      RFC 821
Simple Mail Transfer Protocol                                           



   4.2.  SMTP REPLIES

      Replies to SMTP commands are devised to ensure the synchronization
      of requests and actions in the process of mail transfer, and to
      guarantee that the sender-SMTP always knows the state of the
      receiver-SMTP.  Every command must generate exactly one reply.

         The details of the command-reply sequence are made explicit in
         Section 5.3 on Sequencing and Section 5.4 State Diagrams.

      An SMTP reply consists of a three digit number (transmitted as
      three alphanumeric characters) followed by some text.  The number
      is intended for use by automata to determine what state to enter
      next; the text is meant for the human user.  It is intended that
      the three digits contain enough encoded information that the
      sender-SMTP need not examine the text and may either discard it or
      pass it on to the user, as appropriate.  In particular, the text
      may be receiver-dependent and context dependent, so there are
      likely to be varying texts for each reply code.  A discussion of
      the theory of reply codes is given in Appendix E.  Formally, a
      reply is defined to be the sequence:  a three-digit code, <SP>,
      one line of text, and <CRLF>, or a multiline reply (as defined in
      Appendix E).  Only the EXPN and HELP commands are expected to
      result in multiline replies in normal circumstances, however
      multiline replies are allowed for any command.
























[Page 34]                                                         Postel


                                                                        
RFC 821                                                      August 1982
                                           Simple Mail Transfer Protocol



      4.2.1.  REPLY CODES BY FUNCTION GROUPS

         500 Syntax error, command unrecognized
            [This may include errors such as command line too long]
         501 Syntax error in parameters or arguments
         502 Command not implemented
         503 Bad sequence of commands
         504 Command parameter not implemented
          
         211 System status, or system help reply
         214 Help message
            [Information on how to use the receiver or the meaning of a
            particular non-standard command; this reply is useful only
            to the human user]
          
         220 <domain> Service ready
         221 <domain> Service closing transmission channel
         421 <domain> Service not available,
             closing transmission channel
            [This may be a reply to any command if the service knows it
            must shut down]
          
         250 Requested mail action okay, completed
         251 User not local; will forward to <forward-path>
         450 Requested mail action not taken: mailbox unavailable
            [E.g., mailbox busy]
         550 Requested action not taken: mailbox unavailable
            [E.g., mailbox not found, no access]
         451 Requested action aborted: error in processing
         551 User not local; please try <forward-path>
         452 Requested action not taken: insufficient system storage
         552 Requested mail action aborted: exceeded storage allocation
         553 Requested action not taken: mailbox name not allowed
            [E.g., mailbox syntax incorrect]
         354 Start mail input; end with <CRLF>.<CRLF>
         554 Transaction failed
         












Postel                                                         [Page 35]


                                                                        
August 1982                                                      RFC 821
Simple Mail Transfer Protocol                                           



      4.2.2.  NUMERIC ORDER LIST OF REPLY CODES

         211 System status, or system help reply
         214 Help message
            [Information on how to use the receiver or the meaning of a
            particular non-standard command; this reply is useful only
            to the human user]
         220 <domain> Service ready
         221 <domain> Service closing transmission channel
         250 Requested mail action okay, completed
         251 User not local; will forward to <forward-path>
          
         354 Start mail input; end with <CRLF>.<CRLF>
          
         421 <domain> Service not available,
             closing transmission channel
            [This may be a reply to any command if the service knows it
            must shut down]
         450 Requested mail action not taken: mailbox unavailable
            [E.g., mailbox busy]
         451 Requested action aborted: local error in processing
         452 Requested action not taken: insufficient system storage
          
         500 Syntax error, command unrecognized
            [This may include errors such as command line too long]
         501 Syntax error in parameters or arguments
         502 Command not implemented
         503 Bad sequence of commands
         504 Command parameter not implemented
         550 Requested action not taken: mailbox unavailable
            [E.g., mailbox not found, no access]
         551 User not local; please try <forward-path>
         552 Requested mail action aborted: exceeded storage allocation
         553 Requested action not taken: mailbox name not allowed
            [E.g., mailbox syntax incorrect]
         554 Transaction failed
         












[Page 36]                                                         Postel


                                                                        
RFC 821                                                      August 1982
                                           Simple Mail Transfer Protocol



   4.3.  SEQUENCING OF COMMANDS AND REPLIES

      The communication between the sender and receiver is intended to
      be an alternating dialogue, controlled by the sender.  As such,
      the sender issues a command and the receiver responds with a
      reply.  The sender must wait for this response before sending
      further commands.

      One important reply is the connection greeting.  Normally, a
      receiver will send a 220 "Service ready" reply when the connection
      is completed.  The sender should wait for this greeting message
      before sending any commands.

         Note: all the greeting type replies have the official name of
         the server host as the first word following the reply code.

            For example,

               220 <SP> USC-ISIF.ARPA <SP> Service ready <CRLF>

      The table below lists alternative success and failure replies for
      each command.  These must be strictly adhered to; a receiver may
      substitute text in the replies, but the meaning and action implied
      by the code numbers and by the specific command reply sequence
      cannot be altered.

      COMMAND-REPLY SEQUENCES

         Each command is listed with its possible replies.  The prefixes
         used before the possible replies are "P" for preliminary (not
         used in SMTP), "I" for intermediate, "S" for success, "F" for
         failure, and "E" for error.  The 421 reply (service not
         available, closing transmission channel) may be given to any
         command if the SMTP-receiver knows it must shut down.  This
         listing forms the basis for the State Diagrams in Section 4.4.

            CONNECTION ESTABLISHMENT
               S: 220
               F: 421
            HELO
               S: 250
               E: 500, 501, 504, 421
            MAIL
               S: 250
               F: 552, 451, 452
               E: 500, 501, 421



Postel                                                         [Page 37]


                                                                        
August 1982                                                      RFC 821
Simple Mail Transfer Protocol                                           



            RCPT
               S: 250, 251
               F: 550, 551, 552, 553, 450, 451, 452
               E: 500, 501, 503, 421
            DATA
               I: 354 -> data -> S: 250
                                 F: 552, 554, 451, 452
               F: 451, 554
               E: 500, 501, 503, 421
            RSET
               S: 250
               E: 500, 501, 504, 421
            SEND
               S: 250
               F: 552, 451, 452
               E: 500, 501, 502, 421
            SOML
               S: 250
               F: 552, 451, 452
               E: 500, 501, 502, 421
            SAML
               S: 250
               F: 552, 451, 452
               E: 500, 501, 502, 421
            VRFY
               S: 250, 251
               F: 550, 551, 553
               E: 500, 501, 502, 504, 421
            EXPN
               S: 250
               F: 550
               E: 500, 501, 502, 504, 421
            HELP
               S: 211, 214
               E: 500, 501, 502, 504, 421
            NOOP
               S: 250
               E: 500, 421
            QUIT
               S: 221
               E: 500
            TURN
               S: 250
               F: 502
               E: 500, 503




[Page 38]                                                         Postel


                                                                        
RFC 821                                                      August 1982
                                           Simple Mail Transfer Protocol



   4.4.  STATE DIAGRAMS

      Following are state diagrams for a simple-minded SMTP
      implementation.  Only the first digit of the reply codes is used.
      There is one state diagram for each group of SMTP commands.  The
      command groupings were determined by constructing a model for each
      command and then collecting together the commands with
      structurally identical models.

      For each command there are three possible outcomes:  "success"
      (S), "failure" (F), and "error" (E). In the state diagrams below
      we use the symbol B for "begin", and the symbol W for "wait for
      reply".

      First, the diagram that represents most of the SMTP commands:

         
                                  1,3    +---+
                             ----------->| E |
                            |            +---+
                            |
         +---+    cmd    +---+    2      +---+
         | B |---------->| W |---------->| S |
         +---+           +---+           +---+
                            |
                            |     4,5    +---+
                             ----------->| F |
                                         +---+
         

         This diagram models the commands:

            HELO, MAIL, RCPT, RSET, SEND, SOML, SAML, VRFY, EXPN, HELP,
            NOOP, QUIT, TURN.















Postel                                                         [Page 39]


                                                                        
August 1982                                                      RFC 821
Simple Mail Transfer Protocol                                           



      A more complex diagram models the DATA command:

         
         +---+   DATA    +---+ 1,2                 +---+
         | B |---------->| W |-------------------->| E |
         +---+           +---+        ------------>+---+
                         3| |4,5     |
                          | |        |
            --------------   -----   |
           |                      |  |             +---+
           |               ----------     -------->| S |
           |              |       |      |         +---+
           |              |  ------------
           |              | |     |
           V           1,3| |2    |
         +---+   data    +---+     --------------->+---+
         |   |---------->| W |                     | F |
         +---+           +---+-------------------->+---+
                              4,5


         Note that the "data" here is a series of lines sent from the
         sender to the receiver with no response expected until the last
         line is sent.

























[Page 40]                                                         Postel


                                                                        
RFC 821                                                      August 1982
                                           Simple Mail Transfer Protocol



   4.5.  DETAILS

      4.5.1.  MINIMUM IMPLEMENTATION

         In order to make SMTP workable, the following minimum
         implementation is required for all receivers:

            COMMANDS -- HELO
                        MAIL
                        RCPT
                        DATA
                        RSET
                        NOOP
                        QUIT

      4.5.2.  TRANSPARENCY

         Without some provision for data transparency the character
         sequence "<CRLF>.<CRLF>" ends the mail text and cannot be sent
         by the user.  In general, users are not aware of such
         "forbidden" sequences.  To allow all user composed text to be
         transmitted transparently the following procedures are used.

            1. Before sending a line of mail text the sender-SMTP checks
            the first character of the line.  If it is a period, one
            additional period is inserted at the beginning of the line.

            2. When a line of mail text is received by the receiver-SMTP
            it checks the line.  If the line is composed of a single
            period it is the end of mail.  If the first character is a
            period and there are other characters on the line, the first
            character is deleted.

         The mail data may contain any of the 128 ASCII characters.  All
         characters are to be delivered to the recipient's mailbox
         including format effectors and other control characters.  If
         the transmission channel provides an 8-bit byte (octets) data
         stream, the 7-bit ASCII codes are transmitted right justified
         in the octets with the high order bits cleared to zero.

            In some systems it may be necessary to transform the data as
            it is received and stored.  This may be necessary for hosts
            that use a different character set than ASCII as their local
            character set, or that store data in records rather than





Postel                                                         [Page 41]


                                                                        
August 1982                                                      RFC 821
Simple Mail Transfer Protocol                                           



            strings.  If such transforms are necessary, they must be
            reversible -- especially if such transforms are applied to
            mail being relayed.

      4.5.3.  SIZES

         There are several objects that have required minimum maximum
         sizes.  That is, every implementation must be able to receive
         objects of at least these sizes, but must not send objects
         larger than these sizes.

                                    
          ****************************************************
          *                                                  *
          *  TO THE MAXIMUM EXTENT POSSIBLE, IMPLEMENTATION  *
          *  TECHNIQUES WHICH IMPOSE NO LIMITS ON THE LENGTH *
          *  OF THESE OBJECTS SHOULD BE USED.                *
          *                                                  *
          ****************************************************

            user

               The maximum total length of a user name is 64 characters.

            domain

               The maximum total length of a domain name or number is 64
               characters.

            path

               The maximum total length of a reverse-path or
               forward-path is 256 characters (including the punctuation
               and element separators).

            command line

               The maximum total length of a command line including the
               command word and the <CRLF> is 512 characters.

            reply line

               The maximum total length of a reply line including the
               reply code and the <CRLF> is 512 characters.





[Page 42]                                                         Postel


                                                                        
RFC 821                                                      August 1982
                                           Simple Mail Transfer Protocol



            text line

               The maximum total length of a text line including the
               <CRLF> is 1000 characters (but not counting the leading
               dot duplicated for transparency).

            recipients buffer

               The maximum total number of recipients that must be
               buffered is 100 recipients.

                                    
          ****************************************************
          *                                                  *
          *  TO THE MAXIMUM EXTENT POSSIBLE, IMPLEMENTATION  *
          *  TECHNIQUES WHICH IMPOSE NO LIMITS ON THE LENGTH *
          *  OF THESE OBJECTS SHOULD BE USED.                *
          *                                                  *
          ****************************************************

         Errors due to exceeding these limits may be reported by using
         the reply codes, for example:

            500 Line too long.

            501 Path too long

            552 Too many recipients.

            552 Too much mail data.



















Postel                                                         [Page 43]


                                                                        
August 1982                                                      RFC 821
Simple Mail Transfer Protocol                                           



APPENDIX A

   TCP Transport service

      The Transmission Control Protocol [3] is used in the ARPA
      Internet, and in any network following the US DoD standards for
      internetwork protocols.

      Connection Establishment

         The SMTP transmission channel is a TCP connection established
         between the sender process port U and the receiver process port
         L.  This single full duplex connection is used as the
         transmission channel.  This protocol is assigned the service
         port 25 (31 octal), that is L=25.

      Data Transfer

         The TCP connection supports the transmission of 8-bit bytes.
         The SMTP data is 7-bit ASCII characters.  Each character is
         transmitted as an 8-bit byte with the high-order bit cleared to
         zero.



























[Page 44]                                                         Postel


                                                                        
RFC 821                                                      August 1982
                                           Simple Mail Transfer Protocol



APPENDIX B

   NCP Transport service

      The ARPANET Host-to-Host Protocol [4] (implemented by the Network
      Control Program) may be used in the ARPANET.

      Connection Establishment

         The SMTP transmission channel is established via NCP between
         the sender process socket U and receiver process socket L.  The
         Initial Connection Protocol [5] is followed resulting in a pair
         of simplex connections.  This pair of connections is used as
         the transmission channel.  This protocol is assigned the
         contact socket 25 (31 octal), that is L=25.

      Data Transfer

         The NCP data connections are established in 8-bit byte mode.
         The SMTP data is 7-bit ASCII characters.  Each character is
         transmitted as an 8-bit byte with the high-order bit cleared to
         zero.



























Postel                                                         [Page 45]


                                                                        
August 1982                                                      RFC 821
Simple Mail Transfer Protocol                                           



APPENDIX C

   NITS

      The Network Independent Transport Service [6] may be used.

      Connection Establishment

         The SMTP transmission channel is established via NITS between
         the sender process and receiver process.  The sender process
         executes the CONNECT primitive, and the waiting receiver
         process executes the ACCEPT primitive.

      Data Transfer

         The NITS connection supports the transmission of 8-bit bytes.
         The SMTP data is 7-bit ASCII characters.  Each character is
         transmitted as an 8-bit byte with the high-order bit cleared to
         zero.






























[Page 46]                                                         Postel


                                                                        
RFC 821                                                      August 1982
                                           Simple Mail Transfer Protocol



APPENDIX D

   X.25 Transport service

      It may be possible to use the X.25 service [7] as provided by the
      Public Data Networks directly, however, it is suggested that a
      reliable end-to-end protocol such as TCP be used on top of X.25
      connections.









































Postel                                                         [Page 47]


                                                                        
August 1982                                                      RFC 821
Simple Mail Transfer Protocol                                           



APPENDIX E

   Theory of Reply Codes

      The three digits of the reply each have a special significance.
      The first digit denotes whether the response is good, bad or
      incomplete.  An unsophisticated sender-SMTP will be able to
      determine its next action (proceed as planned, redo, retrench,
      etc.) by simply examining this first digit.  A sender-SMTP that
      wants to know approximately what kind of error occurred (e.g.,
      mail system error, command syntax error) may examine the second
      digit, reserving the third digit for the finest gradation of
      information.

         There are five values for the first digit of the reply code:

            1yz   Positive Preliminary reply

               The command has been accepted, but the requested action
               is being held in abeyance, pending confirmation of the
               information in this reply.  The sender-SMTP should send
               another command specifying whether to continue or abort
               the action.

                  [Note: SMTP does not have any commands that allow this
                  type of reply, and so does not have the continue or
                  abort commands.]

            2yz   Positive Completion reply

               The requested action has been successfully completed.  A
               new request may be initiated.

            3yz   Positive Intermediate reply

               The command has been accepted, but the requested action
               is being held in abeyance, pending receipt of further
               information.  The sender-SMTP should send another command
               specifying this information.  This reply is used in
               command sequence groups.

            4yz   Transient Negative Completion reply

               The command was not accepted and the requested action did
               not occur.  However, the error condition is temporary and
               the action may be requested again.  The sender should



[Page 48]                                                         Postel


                                                                        
RFC 821                                                      August 1982
                                           Simple Mail Transfer Protocol



               return to the beginning of the command sequence (if any).
               It is difficult to assign a meaning to "transient" when
               two different sites (receiver- and sender- SMTPs) must
               agree on the interpretation.  Each reply in this category
               might have a different time value, but the sender-SMTP is
               encouraged to try again.  A rule of thumb to determine if
               a reply fits into the 4yz or the 5yz category (see below)
               is that replies are 4yz if they can be repeated without
               any change in command form or in properties of the sender
               or receiver.  (E.g., the command is repeated identically
               and the receiver does not put up a new implementation.)

            5yz   Permanent Negative Completion reply

               The command was not accepted and the requested action did
               not occur.  The sender-SMTP is discouraged from repeating
               the exact request (in the same sequence).  Even some
               "permanent" error conditions can be corrected, so the
               human user may want to direct the sender-SMTP to
               reinitiate the command sequence by direct action at some
               point in the future (e.g., after the spelling has been
               changed, or the user has altered the account status).

         The second digit encodes responses in specific categories:

            x0z   Syntax -- These replies refer to syntax errors,
                  syntactically correct commands that don't fit any
                  functional category, and unimplemented or superfluous
                  commands.

            x1z   Information --  These are replies to requests for
                  information, such as status or help.

            x2z   Connections -- These are replies referring to the
                  transmission channel.

            x3z   Unspecified as yet.

            x4z   Unspecified as yet.

            x5z   Mail system -- These replies indicate the status of
                  the receiver mail system vis-a-vis the requested
                  transfer or other mail system action.

         The third digit gives a finer gradation of meaning in each
         category specified by the second digit.  The list of replies



Postel                                                         [Page 49]


                                                                        
August 1982                                                      RFC 821
Simple Mail Transfer Protocol                                           



         illustrates this.  Each reply text is recommended rather than
         mandatory, and may even change according to the command with
         which it is associated.  On the other hand, the reply codes
         must strictly follow the specifications in this section.
         Receiver implementations should not invent new codes for
         slightly different situations from the ones described here, but
         rather adapt codes already defined.

         For example, a command such as NOOP whose successful execution
         does not offer the sender-SMTP any new information will return
         a 250 reply.  The response is 502 when the command requests an
         unimplemented non-site-specific action.  A refinement of that
         is the 504 reply for a command that is implemented, but that
         requests an unimplemented parameter.

      The reply text may be longer than a single line; in these cases
      the complete text must be marked so the sender-SMTP knows when it
      can stop reading the reply.  This requires a special format to
      indicate a multiple line reply.

         The format for multiline replies requires that every line,
         except the last, begin with the reply code, followed
         immediately by a hyphen, "-" (also known as minus), followed by
         text.  The last line will begin with the reply code, followed
         immediately by <SP>, optionally some text, and <CRLF>.

            For example:
                                123-First line
                                123-Second line
                                123-234 text beginning with numbers
                                123 The last line

         In many cases the sender-SMTP then simply needs to search for
         the reply code followed by <SP> at the beginning of a line, and
         ignore all preceding lines.  In a few cases, there is important
         data for the sender in the reply "text".  The sender will know
         these cases from the current context.












[Page 50]                                                         Postel


                                                                        
RFC 821                                                      August 1982
                                           Simple Mail Transfer Protocol



APPENDIX F

   Scenarios

      This section presents complete scenarios of several types of SMTP
      sessions.

   A Typical SMTP Transaction Scenario

      This SMTP example shows mail sent by Smith at host USC-ISIF, to
      Jones, Green, and Brown at host BBN-UNIX.  Here we assume that
      host USC-ISIF contacts host BBN-UNIX directly.  The mail is
      accepted for Jones and Brown.  Green does not have a mailbox at
      host BBN-UNIX.

      -------------------------------------------------------------

         R: 220 BBN-UNIX.ARPA Simple Mail Transfer Service Ready
         S: HELO USC-ISIF.ARPA
         R: 250 BBN-UNIX.ARPA

         S: MAIL FROM:<Smith@USC-ISIF.ARPA>
         R: 250 OK

         S: RCPT TO:<Jones@BBN-UNIX.ARPA>
         R: 250 OK

         S: RCPT TO:<Green@BBN-UNIX.ARPA>
         R: 550 No such user here

         S: RCPT TO:<Brown@BBN-UNIX.ARPA>
         R: 250 OK

         S: DATA
         R: 354 Start mail input; end with <CRLF>.<CRLF>
         S: Blah blah blah...
         S: ...etc. etc. etc.
         S: .
         R: 250 OK

         S: QUIT
         R: 221 BBN-UNIX.ARPA Service closing transmission channel

                               Scenario 1

      -------------------------------------------------------------



Postel                                                         [Page 51]


                                                                        
August 1982                                                      RFC 821
Simple Mail Transfer Protocol                                           



   Aborted SMTP Transaction Scenario

      -------------------------------------------------------------

         R: 220 MIT-Multics.ARPA Simple Mail Transfer Service Ready
         S: HELO ISI-VAXA.ARPA
         R: 250 MIT-Multics.ARPA

         S: MAIL FROM:<Smith@ISI-VAXA.ARPA>
         R: 250 OK

         S: RCPT TO:<Jones@MIT-Multics.ARPA>
         R: 250 OK

         S: RCPT TO:<Green@MIT-Multics.ARPA>
         R: 550 No such user here

         S: RSET
         R: 250 OK

         S: QUIT
         R: 221 MIT-Multics.ARPA Service closing transmission channel

                               Scenario 2

      -------------------------------------------------------------























[Page 52]                                                         Postel


                                                                        
RFC 821                                                      August 1982
                                           Simple Mail Transfer Protocol



   Relayed Mail Scenario

      -------------------------------------------------------------

         Step 1  --  Source Host to Relay Host

            R: 220 USC-ISIE.ARPA Simple Mail Transfer Service Ready
            S: HELO MIT-AI.ARPA
            R: 250 USC-ISIE.ARPA

            S: MAIL FROM:<JQP@MIT-AI.ARPA>
            R: 250 OK

            S: RCPT TO:<@USC-ISIE.ARPA:Jones@BBN-VAX.ARPA>
            R: 250 OK

            S: DATA
            R: 354 Start mail input; end with <CRLF>.<CRLF>
            S: Date: 2 Nov 81 22:33:44
            S: From: John Q. Public <JQP@MIT-AI.ARPA>
            S: Subject:  The Next Meeting of the Board
            S: To: Jones@BBN-Vax.ARPA
            S:
            S: Bill:
            S: The next meeting of the board of directors will be
            S: on Tuesday.
            S:                                              John.
            S: .
            R: 250 OK

            S: QUIT
            R: 221 USC-ISIE.ARPA Service closing transmission channel

















Postel                                                         [Page 53]


                                                                        
August 1982                                                      RFC 821
Simple Mail Transfer Protocol                                           



         Step 2  --  Relay Host to Destination Host

            R: 220 BBN-VAX.ARPA Simple Mail Transfer Service Ready
            S: HELO USC-ISIE.ARPA
            R: 250 BBN-VAX.ARPA

            S: MAIL FROM:<@USC-ISIE.ARPA:JQP@MIT-AI.ARPA>
            R: 250 OK

            S: RCPT TO:<Jones@BBN-VAX.ARPA>
            R: 250 OK

            S: DATA
            R: 354 Start mail input; end with <CRLF>.<CRLF>
            S: Received: from MIT-AI.ARPA by USC-ISIE.ARPA ;
               2 Nov 81 22:40:10 UT
            S: Date: 2 Nov 81 22:33:44
            S: From: John Q. Public <JQP@MIT-AI.ARPA>
            S: Subject:  The Next Meeting of the Board
            S: To: Jones@BBN-Vax.ARPA
            S:
            S: Bill:
            S: The next meeting of the board of directors will be
            S: on Tuesday.
            S:                                              John.
            S: .
            R: 250 OK

            S: QUIT
            R: 221 USC-ISIE.ARPA Service closing transmission channel

                               Scenario 3

      -------------------------------------------------------------















[Page 54]                                                         Postel


                                                                        
RFC 821                                                      August 1982
                                           Simple Mail Transfer Protocol



   Verifying and Sending Scenario

      -------------------------------------------------------------

         R: 220 SU-SCORE.ARPA Simple Mail Transfer Service Ready
         S: HELO MIT-MC.ARPA
         R: 250 SU-SCORE.ARPA

         S: VRFY Crispin
         R: 250 Mark Crispin <Admin.MRC@SU-SCORE.ARPA>

         S: SEND FROM:<EAK@MIT-MC.ARPA>
         R: 250 OK

         S: RCPT TO:<Admin.MRC@SU-SCORE.ARPA>
         R: 250 OK

         S: DATA
         R: 354 Start mail input; end with <CRLF>.<CRLF>
         S: Blah blah blah...
         S: ...etc. etc. etc.
         S: .
         R: 250 OK

         S: QUIT
         R: 221 SU-SCORE.ARPA Service closing transmission channel

                               Scenario 4

      -------------------------------------------------------------



















Postel                                                         [Page 55]


                                                                        
August 1982                                                      RFC 821
Simple Mail Transfer Protocol                                           



   Sending and Mailing Scenarios

      First the user's name is verified, then  an attempt is made to
      send to the user's terminal.  When that fails, the messages is
      mailed to the user's mailbox.

      -------------------------------------------------------------

         R: 220 SU-SCORE.ARPA Simple Mail Transfer Service Ready
         S: HELO MIT-MC.ARPA
         R: 250 SU-SCORE.ARPA

         S: VRFY Crispin
         R: 250 Mark Crispin <Admin.MRC@SU-SCORE.ARPA>

         S: SEND FROM:<EAK@MIT-MC.ARPA>
         R: 250 OK

         S: RCPT TO:<Admin.MRC@SU-SCORE.ARPA>
         R: 450 User not active now

         S: RSET
         R: 250 OK

         S: MAIL FROM:<EAK@MIT-MC.ARPA>
         R: 250 OK

         S: RCPT TO:<Admin.MRC@SU-SCORE.ARPA>
         R: 250 OK

         S: DATA
         R: 354 Start mail input; end with <CRLF>.<CRLF>
         S: Blah blah blah...
         S: ...etc. etc. etc.
         S: .
         R: 250 OK

         S: QUIT
         R: 221 SU-SCORE.ARPA Service closing transmission channel

                               Scenario 5

      -------------------------------------------------------------






[Page 56]                                                         Postel


                                                                        
RFC 821                                                      August 1982
                                           Simple Mail Transfer Protocol



      Doing the preceding scenario more efficiently.

      -------------------------------------------------------------

         R: 220 SU-SCORE.ARPA Simple Mail Transfer Service Ready
         S: HELO MIT-MC.ARPA
         R: 250 SU-SCORE.ARPA

         S: VRFY Crispin
         R: 250 Mark Crispin <Admin.MRC@SU-SCORE.ARPA>

         S: SOML FROM:<EAK@MIT-MC.ARPA>
         R: 250 OK

         S: RCPT TO:<Admin.MRC@SU-SCORE.ARPA>
         R: 250 User not active now, so will do mail.

         S: DATA
         R: 354 Start mail input; end with <CRLF>.<CRLF>
         S: Blah blah blah...
         S: ...etc. etc. etc.
         S: .
         R: 250 OK

         S: QUIT
         R: 221 SU-SCORE.ARPA Service closing transmission channel

                               Scenario 6

      -------------------------------------------------------------



















Postel                                                         [Page 57]


                                                                        
August 1982                                                      RFC 821
Simple Mail Transfer Protocol                                           



   Mailing List Scenario

      First each of two mailing lists are expanded in separate sessions
      with different hosts.  Then the message is sent to everyone that
      appeared on either list (but no duplicates) via a relay host.

      -------------------------------------------------------------

         Step 1  --  Expanding the First List

            R: 220 MIT-AI.ARPA Simple Mail Transfer Service Ready
            S: HELO SU-SCORE.ARPA
            R: 250 MIT-AI.ARPA

            S: EXPN Example-People
            R: 250-<ABC@MIT-MC.ARPA>
            R: 250-Fred Fonebone <Fonebone@USC-ISIQ.ARPA>
            R: 250-Xenon Y. Zither <XYZ@MIT-AI.ARPA>
            R: 250-Quincy Smith <@USC-ISIF.ARPA:Q-Smith@ISI-VAXA.ARPA>
            R: 250-<joe@foo-unix.ARPA>
            R: 250 <xyz@bar-unix.ARPA>

            S: QUIT
            R: 221 MIT-AI.ARPA Service closing transmission channel

























[Page 58]                                                         Postel


                                                                        
RFC 821                                                      August 1982
                                           Simple Mail Transfer Protocol



         Step 2  --  Expanding the Second List

            R: 220 MIT-MC.ARPA Simple Mail Transfer Service Ready
            S: HELO SU-SCORE.ARPA
            R: 250 MIT-MC.ARPA

            S: EXPN Interested-Parties
            R: 250-Al Calico <ABC@MIT-MC.ARPA>
            R: 250-<XYZ@MIT-AI.ARPA>
            R: 250-Quincy Smith <@USC-ISIF.ARPA:Q-Smith@ISI-VAXA.ARPA>
            R: 250-<fred@BBN-UNIX.ARPA>
            R: 250 <xyz@bar-unix.ARPA>

            S: QUIT
            R: 221 MIT-MC.ARPA Service closing transmission channel


































Postel                                                         [Page 59]


                                                                        
August 1982                                                      RFC 821
Simple Mail Transfer Protocol                                           



         Step 3  --  Mailing to All via a Relay Host

            R: 220 USC-ISIE.ARPA Simple Mail Transfer Service Ready
            S: HELO SU-SCORE.ARPA
            R: 250 USC-ISIE.ARPA

            S: MAIL FROM:<Account.Person@SU-SCORE.ARPA>
            R: 250 OK
            S: RCPT TO:<@USC-ISIE.ARPA:ABC@MIT-MC.ARPA>
            R: 250 OK
            S: RCPT TO:<@USC-ISIE.ARPA:Fonebone@USC-ISIQA.ARPA>
            R: 250 OK
            S: RCPT TO:<@USC-ISIE.ARPA:XYZ@MIT-AI.ARPA>
            R: 250 OK
            S: RCPT
                TO:<@USC-ISIE.ARPA,@USC-ISIF.ARPA:Q-Smith@ISI-VAXA.ARPA>
            R: 250 OK
            S: RCPT TO:<@USC-ISIE.ARPA:joe@FOO-UNIX.ARPA>
            R: 250 OK
            S: RCPT TO:<@USC-ISIE.ARPA:xyz@BAR-UNIX.ARPA>
            R: 250 OK
            S: RCPT TO:<@USC-ISIE.ARPA:fred@BBN-UNIX.ARPA>
            R: 250 OK

            S: DATA
            R: 354 Start mail input; end with <CRLF>.<CRLF>
            S: Blah blah blah...
            S: ...etc. etc. etc.
            S: .
            R: 250 OK

            S: QUIT
            R: 221 USC-ISIE.ARPA Service closing transmission channel

                               Scenario 7

      -------------------------------------------------------------












[Page 60]                                                         Postel


                                                                        
RFC 821                                                      August 1982
                                           Simple Mail Transfer Protocol



   Forwarding Scenarios

      -------------------------------------------------------------

         R: 220 USC-ISIF.ARPA Simple Mail Transfer Service Ready
         S: HELO LBL-UNIX.ARPA
         R: 250 USC-ISIF.ARPA

         S: MAIL FROM:<mo@LBL-UNIX.ARPA>
         R: 250 OK

         S: RCPT TO:<fred@USC-ISIF.ARPA>
         R: 251 User not local; will forward to <Jones@USC-ISI.ARPA>

         S: DATA
         R: 354 Start mail input; end with <CRLF>.<CRLF>
         S: Blah blah blah...
         S: ...etc. etc. etc.
         S: .
         R: 250 OK

         S: QUIT
         R: 221 USC-ISIF.ARPA Service closing transmission channel

                               Scenario 8

      -------------------------------------------------------------






















Postel                                                         [Page 61]


                                                                        
August 1982                                                      RFC 821
Simple Mail Transfer Protocol                                           



      -------------------------------------------------------------

         Step 1  --  Trying the Mailbox at the First Host

            R: 220 USC-ISIF.ARPA Simple Mail Transfer Service Ready
            S: HELO LBL-UNIX.ARPA
            R: 250 USC-ISIF.ARPA

            S: MAIL FROM:<mo@LBL-UNIX.ARPA>
            R: 250 OK

            S: RCPT TO:<fred@USC-ISIF.ARPA>
            R: 251 User not local; will forward to <Jones@USC-ISI.ARPA>

            S: RSET
            R: 250 OK

            S: QUIT
            R: 221 USC-ISIF.ARPA Service closing transmission channel

         Step 2  --  Delivering the Mail at the Second Host

            R: 220 USC-ISI.ARPA Simple Mail Transfer Service Ready
            S: HELO LBL-UNIX.ARPA
            R: 250 USC-ISI.ARPA

            S: MAIL FROM:<mo@LBL-UNIX.ARPA>
            R: 250 OK

            S: RCPT TO:<Jones@USC-ISI.ARPA>
            R: OK

            S: DATA
            R: 354 Start mail input; end with <CRLF>.<CRLF>
            S: Blah blah blah...
            S: ...etc. etc. etc.
            S: .
            R: 250 OK

            S: QUIT
            R: 221 USC-ISI.ARPA Service closing transmission channel

                               Scenario 9

      -------------------------------------------------------------




[Page 62]                                                         Postel


                                                                        
RFC 821                                                      August 1982
                                           Simple Mail Transfer Protocol



   Too Many Recipients Scenario

      -------------------------------------------------------------

         R: 220 BERKELEY.ARPA Simple Mail Transfer Service Ready
         S: HELO USC-ISIF.ARPA
         R: 250 BERKELEY.ARPA

         S: MAIL FROM:<Postel@USC-ISIF.ARPA>
         R: 250 OK

         S: RCPT TO:<fabry@BERKELEY.ARPA>
         R: 250 OK

         S: RCPT TO:<eric@BERKELEY.ARPA>
         R: 552 Recipient storage full, try again in another transaction

         S: DATA
         R: 354 Start mail input; end with <CRLF>.<CRLF>
         S: Blah blah blah...
         S: ...etc. etc. etc.
         S: .
         R: 250 OK

         S: MAIL FROM:<Postel@USC-ISIF.ARPA>
         R: 250 OK

         S: RCPT TO:<eric@BERKELEY.ARPA>
         R: 250 OK

         S: DATA
         R: 354 Start mail input; end with <CRLF>.<CRLF>
         S: Blah blah blah...
         S: ...etc. etc. etc.
         S: .
         R: 250 OK

         S: QUIT
         R: 221 BERKELEY.ARPA Service closing transmission channel

                              Scenario 10

      -------------------------------------------------------------

      Note that a real implementation must handle many recipients as
      specified in Section 4.5.3.



Postel                                                         [Page 63]


                                                                        
August 1982                                                      RFC 821
Simple Mail Transfer Protocol                                           



GLOSSARY

   ASCII

      American Standard Code for Information Interchange [1].

   command

      A request for a mail service action sent by the sender-SMTP to the
      receiver-SMTP.

   domain

      The hierarchially structured global character string address of a
      host computer in the mail system.

   end of mail data indication

      A special sequence of characters that indicates the end of the
      mail data.  In particular, the five characters carriage return,
      line feed, period, carriage return, line feed, in that order.

   host

      A computer in the internetwork environment on which mailboxes or
      SMTP processes reside.

   line

      A a sequence of ASCII characters ending with a <CRLF>.

   mail data

      A sequence of ASCII characters of arbitrary length, which conforms
      to the standard set in the Standard for the Format of ARPA
      Internet Text Messages (RFC 822 [2]).

   mailbox

      A character string (address) which identifies a user to whom mail
      is to be sent.  Mailbox normally consists of the host and user
      specifications.  The standard mailbox naming convention is defined
      to be "user@domain".  Additionally, the "container" in which mail
      is stored.





[Page 64]                                                         Postel


                                                                        
RFC 821                                                      August 1982
                                           Simple Mail Transfer Protocol



   receiver-SMTP process

      A process which transfers mail in cooperation with a sender-SMTP
      process.  It waits for a connection to be established via the
      transport service.  It receives SMTP commands from the
      sender-SMTP, sends replies, and performs the specified operations.

   reply

      A reply is an acknowledgment (positive or negative) sent from
      receiver to sender via the transmission channel in response to a
      command.  The general form of a reply is a completion code
      (including error codes) followed by a text string.  The codes are
      for use by programs and the text is usually intended for human
      users.

   sender-SMTP process

      A process which transfers mail in cooperation with a receiver-SMTP
      process.  A local language may be used in the user interface
      command/reply dialogue.  The sender-SMTP initiates the transport
      service connection.  It initiates SMTP commands, receives replies,
      and governs the transfer of mail.

   session

      The set of exchanges that occur while the transmission channel is
      open.

   transaction

      The set of exchanges required for one message to be transmitted
      for one or more recipients.

   transmission channel

      A full-duplex communication path between a sender-SMTP and a
      receiver-SMTP for the exchange of commands, replies, and mail
      text.

   transport service

      Any reliable stream-oriented data communication services.  For
      example, NCP, TCP, NITS.





Postel                                                         [Page 65]


                                                                        
August 1982                                                      RFC 821
Simple Mail Transfer Protocol                                           



   user

      A human being (or a process on behalf of a human being) wishing to
      obtain mail transfer service.  In addition, a recipient of
      computer mail.

   word

      A sequence of printing characters.

   <CRLF>

      The characters carriage return and line feed (in that order).

   <SP>

      The space character.
































[Page 66]                                                         Postel


                                                                        
RFC 821                                                      August 1982
                                           Simple Mail Transfer Protocol



REFERENCES

   [1]  ASCII

      ASCII, "USA Code for Information Interchange", United States of
      America Standards Institute, X3.4, 1968.  Also in:  Feinler, E.
      and J. Postel, eds., "ARPANET Protocol Handbook", NIC 7104, for
      the Defense Communications Agency by SRI International, Menlo
      Park, California, Revised January 1978.

   [2]  RFC 822

      Crocker, D., "Standard for the Format of ARPA Internet Text
      Messages," RFC 822, Department of Electrical Engineering,
      University of Delaware, August 1982.

   [3]  TCP

      Postel, J., ed., "Transmission Control Protocol - DARPA Internet
      Program Protocol Specification", RFC 793, USC/Information Sciences
      Institute, NTIS AD Number A111091, September 1981.  Also in:
      Feinler, E. and J. Postel, eds., "Internet Protocol Transition
      Workbook", SRI International, Menlo Park, California, March 1982.

   [4]  NCP

      McKenzie,A., "Host/Host Protocol for the ARPA Network", NIC 8246,
      January 1972.  Also in:  Feinler, E. and J. Postel, eds., "ARPANET
      Protocol Handbook", NIC 7104, for the Defense Communications
      Agency by SRI International, Menlo Park, California, Revised
      January 1978.

   [5]  Initial Connection Protocol

      Postel, J., "Official Initial Connection Protocol", NIC 7101,
      11 June 1971.  Also in:  Feinler, E. and J. Postel, eds., "ARPANET
      Protocol Handbook", NIC 7104, for the Defense Communications
      Agency by SRI International, Menlo Park, California, Revised
      January 1978.

   [6]  NITS

      PSS/SG3, "A Network Independent Transport Service", Study Group 3,
      The Post Office PSS Users Group, February 1980.  Available from
      the DCPU, National Physical Laboratory, Teddington, UK.




Postel                                                         [Page 67]


                                                                        
August 1982                                                      RFC 821
Simple Mail Transfer Protocol                                           



   [7]  X.25

      CCITT, "Recommendation X.25 - Interface Between Data Terminal
      Equipment (DTE) and Data Circuit-terminating Equipment (DCE) for
      Terminals Operating in the Packet Mode on Public Data Networks,"
      CCITT Orange Book, Vol. VIII.2, International Telephone and
      Telegraph Consultative Committee, Geneva, 1976.

         








































[Page 68]                                                         Postel



================================================
FILE: doc/notes/rfc/rfc0822.txt
================================================

 




     RFC #  822

     Obsoletes:  RFC #733  (NIC #41952)












                        STANDARD FOR THE FORMAT OF

                        ARPA INTERNET TEXT MESSAGES






                              August 13, 1982






                                Revised by

                             David H. Crocker


                      Dept. of Electrical Engineering
                 University of Delaware, Newark, DE  19711
                      Network:  DCrocker @ UDel-Relay














 
     Standard for ARPA Internet Text Messages


                             TABLE OF CONTENTS


     PREFACE ....................................................   ii

     1.  INTRODUCTION ...........................................    1

         1.1.  Scope ............................................    1
         1.2.  Communication Framework ..........................    2

     2.  NOTATIONAL CONVENTIONS .................................    3

     3.  LEXICAL ANALYSIS OF MESSAGES ...........................    5

         3.1.  General Description ..............................    5
         3.2.  Header Field Definitions .........................    9
         3.3.  Lexical Tokens ...................................   10
         3.4.  Clarifications ...................................   11

     4.  MESSAGE SPECIFICATION ..................................   17

         4.1.  Syntax ...........................................   17
         4.2.  Forwarding .......................................   19
         4.3.  Trace Fields .....................................   20
         4.4.  Originator Fields ................................   21
         4.5.  Receiver Fields ..................................   23
         4.6.  Reference Fields .................................   23
         4.7.  Other Fields .....................................   24

     5.  DATE AND TIME SPECIFICATION ............................   26

         5.1.  Syntax ...........................................   26
         5.2.  Semantics ........................................   26

     6.  ADDRESS SPECIFICATION ..................................   27

         6.1.  Syntax ...........................................   27
         6.2.  Semantics ........................................   27
         6.3.  Reserved Address .................................   33

     7.  BIBLIOGRAPHY ...........................................   34


                             APPENDIX

     A.  EXAMPLES ...............................................   36
     B.  SIMPLE FIELD PARSING ...................................   40
     C.  DIFFERENCES FROM RFC #733 ..............................   41
     D.  ALPHABETICAL LISTING OF SYNTAX RULES ...................   44


     August 13, 1982               - i -                      RFC #822



 
     Standard for ARPA Internet Text Messages


                                  PREFACE


          By 1977, the Arpanet employed several informal standards for
     the  text  messages (mail) sent among its host computers.  It was
     felt necessary to codify these practices and  provide  for  those
     features  that  seemed  imminent.   The result of that effort was
     Request for Comments (RFC) #733, "Standard for the Format of ARPA
     Network Text Message", by Crocker, Vittal, Pogran, and Henderson.
     The specification attempted to avoid major  changes  in  existing
     software, while permitting several new features.

          This document revises the specifications  in  RFC  #733,  in
     order  to  serve  the  needs  of the larger and more complex ARPA
     Internet.  Some of RFC #733's features failed  to  gain  adequate
     acceptance.   In  order to simplify the standard and the software
     that follows it, these features have been removed.   A  different
     addressing  scheme  is  used, to handle the case of inter-network
     mail; and the concept of re-transmission has been introduced.

          This specification is intended for use in the ARPA Internet.
     However, an attempt has been made to free it of any dependence on
     that environment, so that it can be applied to other network text
     message systems.

          The specification of RFC #733 took place over the course  of
     one  year, using the ARPANET mail environment, itself, to provide
     an on-going forum for discussing the capabilities to be included.
     More  than  twenty individuals, from across the country, partici-
     pated in  the  original  discussion.   The  development  of  this
     revised specification has, similarly, utilized network mail-based
     group discussion.  Both specification efforts  greatly  benefited
     from the comments and ideas of the participants.

          The syntax of the standard,  in  RFC  #733,  was  originally
     specified  in  the  Backus-Naur Form (BNF) meta-language.  Ken L.
     Harrenstien, of SRI International, was responsible for  re-coding
     the  BNF  into  an  augmented  BNF  that makes the representation
     smaller and easier to understand.












     August 13, 1982              - ii -                      RFC #822


 
     Standard for ARPA Internet Text Messages


     1.  INTRODUCTION

     1.1.  SCOPE

          This standard specifies a syntax for text messages that  are
     sent  among  computer  users, within the framework of "electronic
     mail".  The standard supersedes  the  one  specified  in  ARPANET
     Request  for Comments #733, "Standard for the Format of ARPA Net-
     work Text Messages".

          In this context, messages are viewed as having  an  envelope
     and  contents.   The  envelope  contains  whatever information is
     needed to accomplish transmission  and  delivery.   The  contents
     compose  the object to be delivered to the recipient.  This stan-
     dard applies only to the format and some of the semantics of mes-
     sage  contents.   It contains no specification of the information
     in the envelope.

          However, some message systems may use information  from  the
     contents  to create the envelope.  It is intended that this stan-
     dard facilitate the acquisition of such information by programs.

          Some message systems may  store  messages  in  formats  that
     differ  from the one specified in this standard.  This specifica-
     tion is intended strictly as a definition of what message content
     format is to be passed BETWEEN hosts.

     Note:  This standard is NOT intended to dictate the internal for-
            mats  used  by sites, the specific message system features
            that they are expected to support, or any of  the  charac-
            teristics  of  user interface programs that create or read
            messages.

          A distinction should be made between what the  specification
     REQUIRES  and  what  it ALLOWS.  Messages can be made complex and
     rich with formally-structured components of information or can be
     kept small and simple, with a minimum of such information.  Also,
     the standard simplifies the interpretation  of  differing  visual
     formats  in  messages;  only  the  visual  aspect of a message is
     affected and not the interpretation  of  information  within  it.
     Implementors may choose to retain such visual distinctions.

          The formal definition is divided into four levels.  The bot-
     tom level describes the meta-notation used in this document.  The
     second level describes basic lexical analyzers that  feed  tokens
     to  higher-level  parsers.   Next is an overall specification for
     messages; it permits distinguishing individual fields.   Finally,
     there is definition of the contents of several structured fields.



     August 13, 1982               - 1 -                      RFC #822


 
     Standard for ARPA Internet Text Messages


     1.2.  COMMUNICATION FRAMEWORK

          Messages consist of lines of text.   No  special  provisions
     are  made for encoding drawings, facsimile, speech, or structured
     text.  No significant consideration has been given  to  questions
     of  data  compression  or to transmission and storage efficiency,
     and the standard tends to be free with the number  of  bits  con-
     sumed.   For  example,  field  names  are specified as free text,
     rather than special terse codes.

          A general "memo" framework is used.  That is, a message con-
     sists of some information in a rigid format, followed by the main
     part of the message, with a format that is not specified in  this
     document.   The  syntax of several fields of the rigidly-formated
     ("headers") section is defined in  this  specification;  some  of
     these fields must be included in all messages.

          The syntax  that  distinguishes  between  header  fields  is
     specified  separately  from  the  internal  syntax for particular
     fields.  This separation is intended to allow simple  parsers  to
     operate on the general structure of messages, without concern for
     the detailed structure of individual header fields.   Appendix  B
     is provided to facilitate construction of these parsers.

          In addition to the fields specified in this document, it  is
     expected  that  other fields will gain common use.  As necessary,
     the specifications for these "extension-fields" will be published
     through  the same mechanism used to publish this document.  Users
     may also  wish  to  extend  the  set  of  fields  that  they  use
     privately.  Such "user-defined fields" are permitted.

          The framework severely constrains document tone and  appear-
     ance and is primarily useful for most intra-organization communi-
     cations and  well-structured   inter-organization  communication.
     It  also  can  be used for some types of inter-process communica-
     tion, such as simple file transfer and remote job entry.  A  more
     robust  framework might allow for multi-font, multi-color, multi-
     dimension encoding of information.  A  less  robust  one,  as  is
     present  in  most  single-machine  message  systems,  would  more
     severely constrain the ability to add fields and the decision  to
     include specific fields.  In contrast with paper-based communica-
     tion, it is interesting to note that the RECEIVER  of  a  message
     can   exercise  an  extraordinary  amount  of  control  over  the
     message's appearance.  The amount of actual control available  to
     message  receivers  is  contingent upon the capabilities of their
     individual message systems.





     August 13, 1982               - 2 -                      RFC #822


 
     Standard for ARPA Internet Text Messages


     2.  NOTATIONAL CONVENTIONS

          This specification uses an augmented Backus-Naur Form  (BNF)
     notation.  The differences from standard BNF involve naming rules
     and indicating repetition and "local" alternatives.

     2.1.  RULE NAMING

          Angle brackets ("<", ">") are not  used,  in  general.   The
     name  of  a rule is simply the name itself, rather than "<name>".
     Quotation-marks enclose literal text (which may be  upper  and/or
     lower  case).   Certain  basic  rules  are  in uppercase, such as
     SPACE, TAB, CRLF, DIGIT, ALPHA, etc.  Angle brackets are used  in
     rule  definitions,  and  in  the rest of this  document, whenever
     their presence will facilitate discerning the use of rule names.

     2.2.  RULE1 / RULE2:  ALTERNATIVES

          Elements separated by slash ("/") are alternatives.   There-
     fore "foo / bar" will accept foo or bar.

     2.3.  (RULE1 RULE2):  LOCAL ALTERNATIVES

          Elements enclosed in parentheses are  treated  as  a  single
     element.   Thus,  "(elem  (foo  /  bar)  elem)"  allows the token
     sequences "elem foo elem" and "elem bar elem".

     2.4.  *RULE:  REPETITION

          The character "*" preceding an element indicates repetition.
     The full form is:

                              <l>*<m>element

     indicating at least <l> and at most <m> occurrences  of  element.
     Default values are 0 and infinity so that "*(element)" allows any
     number, including zero; "1*element" requires at  least  one;  and
     "1*2element" allows one or two.

     2.5.  [RULE]:  OPTIONAL

          Square brackets enclose optional elements; "[foo  bar]"   is
     equivalent to "*1(foo bar)".

     2.6.  NRULE:  SPECIFIC REPETITION

          "<n>(element)" is equivalent to "<n>*<n>(element)"; that is,
     exactly  <n>  occurrences  of (element). Thus 2DIGIT is a 2-digit
     number, and 3ALPHA is a string of three alphabetic characters.


     August 13, 1982               - 3 -                      RFC #822


 
     Standard for ARPA Internet Text Messages


     2.7.  #RULE:  LISTS

          A construct "#" is defined, similar to "*", as follows:

                              <l>#<m>element

     indicating at least <l> and at most <m> elements, each  separated
     by  one  or more commas (","). This makes the usual form of lists
     very easy; a rule such as '(element *("," element))' can be shown
     as  "1#element".   Wherever this construct is used, null elements
     are allowed, but do not  contribute  to  the  count  of  elements
     present.   That  is,  "(element),,(element)"  is  permitted,  but
     counts as only two elements.  Therefore, where at least one  ele-
     ment  is required, at least one non-null element must be present.
     Default values are 0 and infinity so that "#(element)" allows any
     number,  including  zero;  "1#element" requires at least one; and
     "1#2element" allows one or two.

     2.8.  ; COMMENTS

          A semi-colon, set off some distance to  the  right  of  rule
     text,  starts  a comment that continues to the end of line.  This
     is a simple way of including useful notes in  parallel  with  the
     specifications.



























     August 13, 1982               - 4 -                      RFC #822


 
     Standard for ARPA Internet Text Messages


     3.  LEXICAL ANALYSIS OF MESSAGES

     3.1.  GENERAL DESCRIPTION

          A message consists of header fields and, optionally, a body.
     The  body  is simply a sequence of lines containing ASCII charac-
     ters.  It is separated from the headers by a null line  (i.e.,  a
     line with nothing preceding the CRLF).

     3.1.1.  LONG HEADER FIELDS

        Each header field can be viewed as a single, logical  line  of
        ASCII  characters,  comprising  a field-name and a field-body.
        For convenience, the field-body  portion  of  this  conceptual
        entity  can be split into a multiple-line representation; this
        is called "folding".  The general rule is that wherever  there
        may  be  linear-white-space  (NOT  simply  LWSP-chars), a CRLF
        immediately followed by AT LEAST one LWSP-char may instead  be
        inserted.  Thus, the single line

            To:  "Joe & J. Harvey" <ddd @Org>, JJV @ BBN

        can be represented as:

            To:  "Joe & J. Harvey" <ddd @ Org>,
                    JJV@BBN

        and

            To:  "Joe & J. Harvey"
                            <ddd@ Org>, JJV
             @BBN

        and

            To:  "Joe &
             J. Harvey" <ddd @ Org>, JJV @ BBN

             The process of moving  from  this  folded   multiple-line
        representation  of a header field to its single line represen-
        tation is called "unfolding".  Unfolding  is  accomplished  by
        regarding   CRLF   immediately  followed  by  a  LWSP-char  as
        equivalent to the LWSP-char.

        Note:  While the standard  permits  folding  wherever  linear-
               white-space is permitted, it is recommended that struc-
               tured fields, such as those containing addresses, limit
               folding  to higher-level syntactic breaks.  For address
               fields, it  is  recommended  that  such  folding  occur


     August 13, 1982               - 5 -                      RFC #822


 
     Standard for ARPA Internet Text Messages


               between addresses, after the separating comma.

     3.1.2.  STRUCTURE OF HEADER FIELDS

        Once a field has been unfolded, it may be viewed as being com-
        posed of a field-name followed by a colon (":"), followed by a
        field-body, and  terminated  by  a  carriage-return/line-feed.
        The  field-name must be composed of printable ASCII characters
        (i.e., characters that  have  values  between  33.  and  126.,
        decimal, except colon).  The field-body may be composed of any
        ASCII characters, except CR or LF.  (While CR and/or LF may be
        present  in the actual text, they are removed by the action of
        unfolding the field.)

        Certain field-bodies of headers may be  interpreted  according
        to  an  internal  syntax  that some systems may wish to parse.
        These  fields  are  called  "structured   fields".    Examples
        include  fields containing dates and addresses.  Other fields,
        such as "Subject"  and  "Comments",  are  regarded  simply  as
        strings of text.

        Note:  Any field which has a field-body  that  is  defined  as
               other  than  simply <text> is to be treated as a struc-
               tured field.

               Field-names, unstructured field bodies  and  structured
               field bodies each are scanned by their own, independent
               "lexical" analyzers.

     3.1.3.  UNSTRUCTURED FIELD BODIES

        For some fields, such as "Subject" and "Comments",  no  struc-
        turing  is assumed, and they are treated simply as <text>s, as
        in the message body.  Rules of folding apply to these  fields,
        so  that  such  field  bodies  which occupy several lines must
        therefore have the second and successive lines indented by  at
        least one LWSP-char.

     3.1.4.  STRUCTURED FIELD BODIES

        To aid in the creation and reading of structured  fields,  the
        free  insertion   of linear-white-space (which permits folding
        by inclusion of CRLFs)  is  allowed  between  lexical  tokens.
        Rather  than  obscuring  the  syntax  specifications for these
        structured fields with explicit syntax for this  linear-white-
        space, the existence of another "lexical" analyzer is assumed.
        This analyzer does not apply  for  unstructured  field  bodies
        that  are  simply  strings  of  text, as described above.  The
        analyzer provides  an  interpretation  of  the  unfolded  text


     August 13, 1982               - 6 -                      RFC #822


 
     Standard for ARPA Internet Text Messages


        composing  the body of the field as a sequence of lexical sym-
        bols.

        These symbols are:

                     -  individual special characters
                     -  quoted-strings
                     -  domain-literals
                     -  comments
                     -  atoms

        The first four of these symbols  are  self-delimiting.   Atoms
        are not; they are delimited by the self-delimiting symbols and
        by  linear-white-space.   For  the  purposes  of  regenerating
        sequences  of  atoms  and quoted-strings, exactly one SPACE is
        assumed to exist, and should be used, between them.  (Also, in
        the "Clarifications" section on "White Space", below, note the
        rules about treatment of multiple contiguous LWSP-chars.)

        So, for example, the folded body of an address field

            ":sysmail"@  Some-Group. Some-Org,
            Muhammed.(I am  the greatest) Ali @(the)Vegas.WBA




























     August 13, 1982               - 7 -                      RFC #822


 
     Standard for ARPA Internet Text Messages


        is analyzed into the following lexical symbols and types:

                    :sysmail              quoted string
                    @                     special
                    Some-Group            atom
                    .                     special
                    Some-Org              atom
                    ,                     special
                    Muhammed              atom
                    .                     special
                    (I am  the greatest)  comment
                    Ali                   atom
                    @                     atom
                    (the)                 comment
                    Vegas                 atom
                    .                     special
                    WBA                   atom

        The canonical representations for the data in these  addresses
        are the following strings:

                        ":sysmail"@Some-Group.Some-Org

        and

                            Muhammed.Ali@Vegas.WBA

        Note:  For purposes of display, and when passing  such  struc-
               tured information to other systems, such as mail proto-
               col  services,  there  must  be  NO  linear-white-space
               between  <word>s  that are separated by period (".") or
               at-sign ("@") and exactly one SPACE between  all  other
               <word>s.  Also, headers should be in a folded form.


















     August 13, 1982               - 8 -                      RFC #822


 
     Standard for ARPA Internet Text Messages


     3.2.  HEADER FIELD DEFINITIONS

          These rules show a field meta-syntax, without regard for the
     particular  type  or internal syntax.  Their purpose is to permit
     detection of fields; also, they present to  higher-level  parsers
     an image of each field as fitting on one line.

     field       =  field-name ":" [ field-body ] CRLF

     field-name  =  1*<any CHAR, excluding CTLs, SPACE, and ":">

     field-body  =  field-body-contents
                    [CRLF LWSP-char field-body]

     field-body-contents =
                   <the ASCII characters making up the field-body, as
                    defined in the following sections, and consisting
                    of combinations of atom, quoted-string, and
                    specials tokens, or else consisting of texts>
































     August 13, 1982               - 9 -                      RFC #822


 
     Standard for ARPA Internet Text Messages


     3.3.  LEXICAL TOKENS

          The following rules are used to define an underlying lexical
     analyzer,  which  feeds  tokens to higher level parsers.  See the
     ANSI references, in the Bibliography.

                                                 ; (  Octal, Decimal.)
     CHAR        =  <any ASCII character>        ; (  0-177,  0.-127.)
     ALPHA       =  <any ASCII alphabetic character>
                                                 ; (101-132, 65.- 90.)
                                                 ; (141-172, 97.-122.)
     DIGIT       =  <any ASCII decimal digit>    ; ( 60- 71, 48.- 57.)
     CTL         =  <any ASCII control           ; (  0- 37,  0.- 31.)
                     character and DEL>          ; (    177,     127.)
     CR          =  <ASCII CR, carriage return>  ; (     15,      13.)
     LF          =  <ASCII LF, linefeed>         ; (     12,      10.)
     SPACE       =  <ASCII SP, space>            ; (     40,      32.)
     HTAB        =  <ASCII HT, horizontal-tab>   ; (     11,       9.)
     <">         =  <ASCII quote mark>           ; (     42,      34.)
     CRLF        =  CR LF

     LWSP-char   =  SPACE / HTAB                 ; semantics = SPACE

     linear-white-space =  1*([CRLF] LWSP-char)  ; semantics = SPACE
                                                 ; CRLF => folding

     specials    =  "(" / ")" / "<" / ">" / "@"  ; Must be in quoted-
                 /  "," / ";" / ":" / "\" / <">  ;  string, to use
                 /  "." / "[" / "]"              ;  within a word.

     delimiters  =  specials / linear-white-space / comment

     text        =  <any CHAR, including bare    ; => atoms, specials,
                     CR & bare LF, but NOT       ;  comments and
                     including CRLF>             ;  quoted-strings are
                                                 ;  NOT recognized.

     atom        =  1*<any CHAR except specials, SPACE and CTLs>

     quoted-string = <"> *(qtext/quoted-pair) <">; Regular qtext or
                                                 ;   quoted chars.

     qtext       =  <any CHAR excepting <">,     ; => may be folded
                     "\" & CR, and including
                     linear-white-space>

     domain-literal =  "[" *(dtext / quoted-pair) "]"




     August 13, 1982              - 10 -                      RFC #822


 
     Standard for ARPA Internet Text Messages


     dtext       =  <any CHAR excluding "[",     ; => may be folded
                     "]", "\" & CR, & including
                     linear-white-space>

     comment     =  "(" *(ctext / quoted-pair / comment) ")"

     ctext       =  <any CHAR excluding "(",     ; => may be folded
                     ")", "\" & CR, & including
                     linear-white-space>

     quoted-pair =  "\" CHAR                     ; may quote any char

     phrase      =  1*word                       ; Sequence of words

     word        =  atom / quoted-string


     3.4.  CLARIFICATIONS

     3.4.1.  QUOTING

        Some characters are reserved for special interpretation,  such
        as  delimiting lexical tokens.  To permit use of these charac-
        ters as uninterpreted data, a quoting mechanism  is  provided.
        To quote a character, precede it with a backslash ("\").

        This mechanism is not fully general.  Characters may be quoted
        only  within  a subset of the lexical constructs.  In particu-
        lar, quoting is limited to use within:

                             -  quoted-string
                             -  domain-literal
                             -  comment

        Within these constructs, quoting is REQUIRED for  CR  and  "\"
        and for the character(s) that delimit the token (e.g., "(" and
        ")" for a comment).  However, quoting  is  PERMITTED  for  any
        character.

        Note:  In particular, quoting is NOT permitted  within  atoms.
               For  example  when  the local-part of an addr-spec must
               contain a special character, a quoted  string  must  be
               used.  Therefore, a specification such as:

                            Full\ Name@Domain

               is not legal and must be specified as:

                            "Full Name"@Domain


     August 13, 1982              - 11 -                      RFC #822


 
     Standard for ARPA Internet Text Messages


     3.4.2.  WHITE SPACE

        Note:  In structured field bodies, multiple linear space ASCII
               characters  (namely  HTABs  and  SPACEs) are treated as
               single spaces and may freely surround any  symbol.   In
               all header fields, the only place in which at least one
               LWSP-char is REQUIRED is at the beginning of  continua-
               tion lines in a folded field.

        When passing text to processes  that  do  not  interpret  text
        according to this standard (e.g., mail protocol servers), then
        NO linear-white-space characters should occur between a period
        (".") or at-sign ("@") and a <word>.  Exactly ONE SPACE should
        be used in place of arbitrary linear-white-space  and  comment
        sequences.

        Note:  Within systems conforming to this standard, wherever  a
               member of the list of delimiters is allowed, LWSP-chars
               may also occur before and/or after it.

        Writers of  mail-sending  (i.e.,  header-generating)  programs
        should realize that there is no network-wide definition of the
        effect of ASCII HT (horizontal-tab) characters on the  appear-
        ance  of  text  at another network host; therefore, the use of
        tabs in message headers, though permitted, is discouraged.

     3.4.3.  COMMENTS

        A comment is a set of ASCII characters, which is  enclosed  in
        matching  parentheses  and which is not within a quoted-string
        The comment construct permits message originators to add  text
        which  will  be  useful  for  human readers, but which will be
        ignored by the formal semantics.  Comments should be  retained
        while  the  message  is subject to interpretation according to
        this standard.  However, comments  must  NOT  be  included  in
        other  cases,  such  as  during  protocol  exchanges with mail
        servers.

        Comments nest, so that if an unquoted left parenthesis  occurs
        in  a  comment  string,  there  must  also be a matching right
        parenthesis.  When a comment acts as the delimiter  between  a
        sequence of two lexical symbols, such as two atoms, it is lex-
        ically equivalent with a single SPACE,  for  the  purposes  of
        regenerating  the  sequence, such as when passing the sequence
        onto a mail protocol server.  Comments are  detected  as  such
        only within field-bodies of structured fields.

        If a comment is to be "folded" onto multiple lines,  then  the
        syntax  for  folding  must  be  adhered to.  (See the "Lexical


     August 13, 1982              - 12 -                      RFC #822


 
     Standard for ARPA Internet Text Messages


        Analysis of Messages" section on "Folding Long Header  Fields"
        above,  and  the  section on "Case Independence" below.)  Note
        that  the  official  semantics  therefore  do  not  "see"  any
        unquoted CRLFs that are in comments, although particular pars-
        ing programs may wish to note their presence.  For these  pro-
        grams,  it would be reasonable to interpret a "CRLF LWSP-char"
        as being a CRLF that is part of the comment; i.e., the CRLF is
        kept  and  the  LWSP-char is discarded.  Quoted CRLFs (i.e., a
        backslash followed by a CR followed by a  LF)  still  must  be
        followed by at least one LWSP-char.

     3.4.4.  DELIMITING AND QUOTING CHARACTERS

        The quote character (backslash) and  characters  that  delimit
        syntactic  units  are not, generally, to be taken as data that
        are part of the delimited or quoted unit(s).   In  particular,
        the   quotation-marks   that   define   a  quoted-string,  the
        parentheses that define  a  comment  and  the  backslash  that
        quotes  a  following  character  are  NOT  part of the quoted-
        string, comment or quoted character.  A quotation-mark that is
        to  be  part  of  a quoted-string, a parenthesis that is to be
        part of a comment and a backslash that is to be part of either
        must  each be preceded by the quote-character backslash ("\").
        Note that the syntax allows any character to be quoted  within
        a  quoted-string  or  comment; however only certain characters
        MUST be quoted to be included as data.  These  characters  are
        the  ones that are not part of the alternate text group (i.e.,
        ctext or qtext).

        The one exception to this rule  is  that  a  single  SPACE  is
        assumed  to  exist  between  contiguous words in a phrase, and
        this interpretation is independent of  the  actual  number  of
        LWSP-chars  that  the  creator  places  between the words.  To
        include more than one SPACE, the creator must make  the  LWSP-
        chars be part of a quoted-string.

        Quotation marks that delimit a quoted string  and  backslashes
        that  quote  the  following character should NOT accompany the
        quoted-string when the string is passed to processes  that  do
        not interpret data according to this specification (e.g., mail
        protocol servers).

     3.4.5.  QUOTED-STRINGS

        Where permitted (i.e., in words in structured fields)  quoted-
        strings  are  treated  as a single symbol.  That is, a quoted-
        string is equivalent to an atom, syntactically.  If a  quoted-
        string  is to be "folded" onto multiple lines, then the syntax
        for folding must be adhered to.  (See the "Lexical Analysis of


     August 13, 1982              - 13 -                      RFC #822


 
     Standard for ARPA Internet Text Messages


        Messages"  section  on "Folding Long Header Fields" above, and
        the section on "Case  Independence"  below.)   Therefore,  the
        official  semantics  do  not  "see" any bare CRLFs that are in
        quoted-strings; however particular parsing programs  may  wish
        to  note  their presence.  For such programs, it would be rea-
        sonable to interpret a "CRLF LWSP-char" as being a CRLF  which
        is  part  of the quoted-string; i.e., the CRLF is kept and the
        LWSP-char is discarded.  Quoted CRLFs (i.e., a backslash  fol-
        lowed  by  a CR followed by a LF) are also subject to rules of
        folding, but the presence of the quoting character (backslash)
        explicitly  indicates  that  the  CRLF  is  data to the quoted
        string.  Stripping off the first following LWSP-char  is  also
        appropriate when parsing quoted CRLFs.

     3.4.6.  BRACKETING CHARACTERS

        There is one type of bracket which must occur in matched pairs
        and may have pairs nested within each other:

            o   Parentheses ("(" and ")") are used  to  indicate  com-
                ments.

        There are three types of brackets which must occur in  matched
        pairs, and which may NOT be nested:

            o   Colon/semi-colon (":" and ";") are   used  in  address
                specifications  to  indicate that the included list of
                addresses are to be treated as a group.

            o   Angle brackets ("<" and ">")  are  generally  used  to
                indicate  the  presence of a one machine-usable refer-
                ence (e.g., delimiting mailboxes), possibly  including
                source-routing to the machine.

            o   Square brackets ("[" and "]") are used to indicate the
                presence  of  a  domain-literal, which the appropriate
                name-domain  is  to  use  directly,  bypassing  normal
                name-resolution mechanisms.

     3.4.7.  CASE INDEPENDENCE

        Except as noted, alphabetic strings may be represented in  any
        combination of upper and lower case.  The only syntactic units








     August 13, 1982              - 14 -                      RFC #822


 
     Standard for ARPA Internet Text Messages


        which requires preservation of case information are:

                    -  text
                    -  qtext
                    -  dtext
                    -  ctext
                    -  quoted-pair
                    -  local-part, except "Postmaster"

        When matching any other syntactic unit, case is to be ignored.
        For  example, the field-names "From", "FROM", "from", and even
        "FroM" are semantically equal and should all be treated ident-
        ically.

        When generating these units, any mix of upper and  lower  case
        alphabetic  characters  may  be  used.  The case shown in this
        specification is suggested for message-creating processes.

        Note:  The reserved local-part address unit, "Postmaster",  is
               an  exception.   When  the  value "Postmaster" is being
               interpreted, it must be  accepted  in  any  mixture  of
               case, including "POSTMASTER", and "postmaster".

     3.4.8.  FOLDING LONG HEADER FIELDS

        Each header field may be represented on exactly one line  con-
        sisting  of the name of the field and its body, and terminated
        by a CRLF; this is what the parser sees.  For readability, the
        field-body  portion of long header fields may be "folded" onto
        multiple lines of the actual field.  "Long" is commonly inter-
        preted  to  mean greater than 65 or 72 characters.  The former
        length serves as a limit, when the message is to be viewed  on
        most  simple terminals which use simple display software; how-
        ever, the limit is not imposed by this standard.

        Note:  Some display software often can selectively fold lines,
               to  suit  the display terminal.  In such cases, sender-
               provided  folding  can  interfere  with   the   display
               software.

     3.4.9.  BACKSPACE CHARACTERS

        ASCII BS characters (Backspace, decimal 8) may be included  in
        texts and quoted-strings to effect overstriking.  However, any
        use of backspaces which effects an overstrike to the  left  of
        the beginning of the text or quoted-string is prohibited.





     August 13, 1982              - 15 -                      RFC #822


 
     Standard for ARPA Internet Text Messages


     3.4.10.  NETWORK-SPECIFIC TRANSFORMATIONS

        During transmission through heterogeneous networks, it may  be
        necessary  to  force data to conform to a network's local con-
        ventions.  For example, it may be required that a CR  be  fol-
        lowed  either by LF, making a CRLF, or by <null>, if the CR is
        to stand alone).  Such transformations are reversed, when  the
        message exits that network.

        When  crossing  network  boundaries,  the  message  should  be
        treated  as  passing  through  two modules.  It will enter the
        first module containing whatever network-specific  transforma-
        tions  that  were  necessary  to  permit migration through the
        "current" network.  It then passes through the modules:

            o   Transformation Reversal

                The "current" network's idiosyncracies are removed and
                the  message  is returned to the canonical form speci-
                fied in this standard.

            o   Transformation

                The "next" network's local idiosyncracies are  imposed
                on the message.

                                ------------------
                    From   ==>  | Remove Net-A   |
                    Net-A       | idiosyncracies |
                                ------------------
                                       ||
                                       \/
                                  Conformance
                                  with standard
                                       ||
                                       \/
                                ------------------
                                | Impose Net-B   |  ==>  To
                                | idiosyncracies |       Net-B
                                ------------------











     August 13, 1982              - 16 -                      RFC #822


 
     Standard for ARPA Internet Text Messages


     4.  MESSAGE SPECIFICATION

     4.1.  SYNTAX

     Note:  Due to an artifact of the notational conventions, the syn-
            tax  indicates that, when present, some fields, must be in
            a particular order.  Header fields  are  NOT  required  to
            occur  in  any  particular  order, except that the message
            body must occur AFTER  the  headers.   It  is  recommended
            that,  if  present,  headers be sent in the order "Return-
            Path", "Received", "Date",  "From",  "Subject",  "Sender",
            "To", "cc", etc.

            This specification permits multiple  occurrences  of  most
            fields.   Except  as  noted,  their  interpretation is not
            specified here, and their use is discouraged.

          The following syntax for the bodies of various fields should
     be  thought  of  as  describing  each field body as a single long
     string (or line).  The "Lexical Analysis of Message"  section  on
     "Long  Header Fields", above, indicates how such long strings can
     be represented on more than one line in  the  actual  transmitted
     message.

     message     =  fields *( CRLF *text )       ; Everything after
                                                 ;  first null line
                                                 ;  is message body

     fields      =    dates                      ; Creation time,
                      source                     ;  author id & one
                    1*destination                ;  address required
                     *optional-field             ;  others optional

     source      = [  trace ]                    ; net traversals
                      originator                 ; original mail
                   [  resent ]                   ; forwarded

     trace       =    return                     ; path to sender
                    1*received                   ; receipt tags

     return      =  "Return-path" ":" route-addr ; return address

     received    =  "Received"    ":"            ; one per relay
                       ["from" domain]           ; sending host
                       ["by"   domain]           ; receiving host
                       ["via"  atom]             ; physical path
                      *("with" atom)             ; link/mail protocol
                       ["id"   msg-id]           ; receiver msg id
                       ["for"  addr-spec]        ; initial form


     August 13, 1982              - 17 -                      RFC #822


 
     Standard for ARPA Internet Text Messages


                        ";"    date-time         ; time received

     originator  =   authentic                   ; authenticated addr
                   [ "Reply-To"   ":" 1#address] )

     authentic   =   "From"       ":"   mailbox  ; Single author
                 / ( "Sender"     ":"   mailbox  ; Actual submittor
                     "From"       ":" 1#mailbox) ; Multiple authors
                                                 ;  or not sender

     resent      =   resent-authentic
                   [ "Resent-Reply-To"  ":" 1#address] )

     resent-authentic =
                 =   "Resent-From"      ":"   mailbox
                 / ( "Resent-Sender"    ":"   mailbox
                     "Resent-From"      ":" 1#mailbox  )

     dates       =   orig-date                   ; Original
                   [ resent-date ]               ; Forwarded

     orig-date   =  "Date"        ":"   date-time

     resent-date =  "Resent-Date" ":"   date-time

     destination =  "To"          ":" 1#address  ; Primary
                 /  "Resent-To"   ":" 1#address
                 /  "cc"          ":" 1#address  ; Secondary
                 /  "Resent-cc"   ":" 1#address
                 /  "bcc"         ":"  #address  ; Blind carbon
                 /  "Resent-bcc"  ":"  #address

     optional-field =
                 /  "Message-ID"        ":"   msg-id
                 /  "Resent-Message-ID" ":"   msg-id
                 /  "In-Reply-To"       ":"  *(phrase / msg-id)
                 /  "References"        ":"  *(phrase / msg-id)
                 /  "Keywords"          ":"  #phrase
                 /  "Subject"           ":"  *text
                 /  "Comments"          ":"  *text
                 /  "Encrypted"         ":" 1#2word
                 /  extension-field              ; To be defined
                 /  user-defined-field           ; May be pre-empted

     msg-id      =  "<" addr-spec ">"            ; Unique message id






     August 13, 1982              - 18 -                      RFC #822


 
     Standard for ARPA Internet Text Messages


     extension-field =
                   <Any field which is defined in a document
                    published as a formal extension to this
                    specification; none will have names beginning
                    with the string "X-">

     user-defined-field =
                   <Any field which has not been defined
                    in this specification or published as an
                    extension to this specification; names for
                    such fields must be unique and may be
                    pre-empted by published extensions>

     4.2.  FORWARDING

          Some systems permit mail recipients to  forward  a  message,
     retaining  the original headers, by adding some new fields.  This
     standard supports such a service, through the "Resent-" prefix to
     field names.

          Whenever the string "Resent-" begins a field name, the field
     has  the  same  semantics as a field whose name does not have the
     prefix.  However, the message is assumed to have  been  forwarded
     by  an original recipient who attached the "Resent-" field.  This
     new field is treated as being more recent  than  the  equivalent,
     original  field.   For  example, the "Resent-From", indicates the
     person that forwarded the message, whereas the "From" field indi-
     cates the original author.

          Use of such precedence  information  depends  upon  partici-
     pants'  communication needs.  For example, this standard does not
     dictate when a "Resent-From:" address should receive replies,  in
     lieu of sending them to the "From:" address.

     Note:  In general, the "Resent-" fields should be treated as con-
            taining  a  set  of information that is independent of the
            set of original fields.  Information for  one  set  should
            not  automatically be taken from the other.  The interpre-
            tation of multiple "Resent-" fields, of the same type,  is
            undefined.

          In the remainder of this specification, occurrence of  legal
     "Resent-"  fields  are treated identically with the occurrence of








     August 13, 1982              - 19 -                      RFC #822


 
     Standard for ARPA Internet Text Messages


     fields whose names do not contain this prefix.

     4.3.  TRACE FIELDS

          Trace information is used to provide an audit trail of  mes-
     sage  handling.   In  addition,  it indicates a route back to the
     sender of the message.

          The list of known "via" and  "with"  values  are  registered
     with  the  Network  Information  Center, SRI International, Menlo
     Park, California.

     4.3.1.  RETURN-PATH

        This field  is  added  by  the  final  transport  system  that
        delivers  the message to its recipient.  The field is intended
        to contain definitive information about the address and  route
        back to the message's originator.

        Note:  The "Reply-To" field is added  by  the  originator  and
               serves  to  direct  replies,  whereas the "Return-Path"
               field is used to identify a path back to  the  origina-
               tor.

        While the syntax  indicates  that  a  route  specification  is
        optional,  every attempt should be made to provide that infor-
        mation in this field.

     4.3.2.  RECEIVED

        A copy of this field is added by each transport  service  that
        relays the message.  The information in the field can be quite
        useful for tracing transport problems.

        The names of the sending  and  receiving  hosts  and  time-of-
        receipt may be specified.  The "via" parameter may be used, to
        indicate what physical mechanism the message  was  sent  over,
        such  as  Arpanet or Phonenet, and the "with" parameter may be
        used to indicate the mail-,  or  connection-,  level  protocol
        that  was  used, such as the SMTP mail protocol, or X.25 tran-
        sport protocol.

        Note:  Several "with" parameters may  be  included,  to  fully
               specify the set of protocols that were used.

        Some transport services queue mail; the internal message iden-
        tifier that is assigned to the message may be noted, using the
        "id" parameter.  When the  sending  host  uses  a  destination
        address specification that the receiving host reinterprets, by


     August 13, 1982              - 20 -                      RFC #822


 
     Standard for ARPA Internet Text Messages


        expansion or transformation, the receiving host  may  wish  to
        record  the original specification, using the "for" parameter.
        For example, when a copy of mail is sent to the  member  of  a
        distribution  list,  this  parameter may be used to record the
        original address that was used to specify the list.

     4.4.  ORIGINATOR FIELDS

          The standard allows only a subset of the combinations possi-
     ble  with the From, Sender, Reply-To, Resent-From, Resent-Sender,
     and Resent-Reply-To fields.  The limitation is intentional.

     4.4.1.  FROM / RESENT-FROM

        This field contains the identity of the person(s)  who  wished
        this  message to be sent.  The message-creation process should
        default this field  to  be  a  single,  authenticated  machine
        address,  indicating  the  AGENT  (person,  system or process)
        entering the message.  If this is not done, the "Sender" field
        MUST  be  present.  If the "From" field IS defaulted this way,
        the "Sender" field is  optional  and  is  redundant  with  the
        "From"  field.   In  all  cases, addresses in the "From" field
        must be machine-usable (addr-specs) and may not contain  named
        lists (groups).

     4.4.2.  SENDER / RESENT-SENDER

        This field contains the authenticated identity  of  the  AGENT
        (person,  system  or  process)  that sends the message.  It is
        intended for use when the sender is not the author of the mes-
        sage,  or  to  indicate  who among a group of authors actually
        sent the message.  If the contents of the "Sender" field would
        be  completely  redundant  with  the  "From"  field,  then the
        "Sender" field need not be present and its use is  discouraged
        (though  still legal).  In particular, the "Sender" field MUST
        be present if it is NOT the same as the "From" Field.

        The Sender mailbox  specification  includes  a  word  sequence
        which  must correspond to a specific agent (i.e., a human user
        or a computer program) rather than a standard  address.   This
        indicates  the  expectation  that  the field will identify the
        single AGENT (person,  system,  or  process)  responsible  for
        sending  the mail and not simply include the name of a mailbox
        from which the mail was sent.  For example in the  case  of  a
        shared login name, the name, by itself, would not be adequate.
        The local-part address unit, which refers to  this  agent,  is
        expected to be a computer system term, and not (for example) a
        generalized person reference which can  be  used  outside  the
        network text message context.


     August 13, 1982              - 21 -                      RFC #822


 
     Standard for ARPA Internet Text Messages


        Since the critical function served by the  "Sender"  field  is
        identification  of  the agent responsible for sending mail and
        since computer programs cannot be held accountable  for  their
        behavior, it is strongly recommended that when a computer pro-
        gram generates a message, the HUMAN  who  is  responsible  for
        that program be referenced as part of the "Sender" field mail-
        box specification.

     4.4.3.  REPLY-TO / RESENT-REPLY-TO

        This field provides a general  mechanism  for  indicating  any
        mailbox(es)  to which responses are to be sent.  Three typical
        uses for this feature can  be  distinguished.   In  the  first
        case,  the  author(s) may not have regular machine-based mail-
        boxes and therefore wish(es) to indicate an alternate  machine
        address.   In  the  second case, an author may wish additional
        persons to be made aware of, or responsible for,  replies.   A
        somewhat  different  use  may be of some help to "text message
        teleconferencing" groups equipped with automatic  distribution
        services:   include the address of that service in the "Reply-
        To" field of all messages  submitted  to  the  teleconference;
        then  participants  can  "reply"  to conference submissions to
        guarantee the correct distribution of any submission of  their
        own.

        Note:  The "Return-Path" field is added by the mail  transport
               service,  at the time of final deliver.  It is intended
               to identify a path back to the orginator  of  the  mes-
               sage.   The  "Reply-To"  field  is added by the message
               originator and is intended to direct replies.

     4.4.4.  AUTOMATIC USE OF FROM / SENDER / REPLY-TO

        For systems which automatically  generate  address  lists  for
        replies to messages, the following recommendations are made:

            o   The "Sender" field mailbox should be sent  notices  of
                any  problems in transport or delivery of the original
                messages.  If there is no  "Sender"  field,  then  the
                "From" field mailbox should be used.

            o   The  "Sender"  field  mailbox  should  NEVER  be  used
                automatically, in a recipient's reply message.

            o   If the "Reply-To" field exists, then the reply  should
                go to the addresses indicated in that field and not to
                the address(es) indicated in the "From" field.




     August 13, 1982              - 22 -                      RFC #822


 
     Standard for ARPA Internet Text Messages


            o   If there is a "From" field, but no  "Reply-To"  field,
                the  reply should be sent to the address(es) indicated
                in the "From" field.

        Sometimes, a recipient may actually wish to  communicate  with
        the  person  that  initiated  the  message  transfer.  In such
        cases, it is reasonable to use the "Sender" address.

        This recommendation is intended  only  for  automated  use  of
        originator-fields  and is not intended to suggest that replies
        may not also be sent to other recipients of messages.   It  is
        up  to  the  respective  mail-handling programs to decide what
        additional facilities will be provided.

        Examples are provided in Appendix A.

     4.5.  RECEIVER FIELDS

     4.5.1.  TO / RESENT-TO

        This field contains the identity of the primary recipients  of
        the message.

     4.5.2.  CC / RESENT-CC

        This field contains the identity of  the  secondary  (informa-
        tional) recipients of the message.

     4.5.3.  BCC / RESENT-BCC

        This field contains the identity of additional  recipients  of
        the  message.   The contents of this field are not included in
        copies of the message sent to the primary and secondary  reci-
        pients.   Some  systems  may choose to include the text of the
        "Bcc" field only in the author(s)'s  copy,  while  others  may
        also include it in the text sent to all those indicated in the
        "Bcc" list.

     4.6.  REFERENCE FIELDS

     4.6.1.  MESSAGE-ID / RESENT-MESSAGE-ID

             This field contains a unique identifier  (the  local-part
        address  unit)  which  refers to THIS version of THIS message.
        The uniqueness of the message identifier is guaranteed by  the
        host  which  generates  it.  This identifier is intended to be
        machine readable and not necessarily meaningful to humans.   A
        message  identifier pertains to exactly one instantiation of a
        particular message; subsequent revisions to the message should


     August 13, 1982              - 23 -                      RFC #822


 
     Standard for ARPA Internet Text Messages


        each receive new message identifiers.

     4.6.2.  IN-REPLY-TO

             The contents of this field identify  previous  correspon-
        dence  which this message answers.  Note that if message iden-
        tifiers are used in this  field,  they  must  use  the  msg-id
        specification format.

     4.6.3.  REFERENCES

             The contents of this field identify other  correspondence
        which  this message references.  Note that if message identif-
        iers are used, they must use the msg-id specification format.

     4.6.4.  KEYWORDS

             This field contains keywords  or  phrases,  separated  by
        commas.

     4.7.  OTHER FIELDS

     4.7.1.  SUBJECT

             This is intended to provide a summary,  or  indicate  the
        nature, of the message.

     4.7.2.  COMMENTS

             Permits adding text comments  onto  the  message  without
        disturbing the contents of the message's body.

     4.7.3.  ENCRYPTED

             Sometimes,  data  encryption  is  used  to  increase  the
        privacy  of  message  contents.   If the body of a message has
        been encrypted, to keep its contents private, the  "Encrypted"
        field  can be used to note the fact and to indicate the nature
        of the encryption.  The first <word> parameter  indicates  the
        software  used  to  encrypt the body, and the second, optional
        <word> is intended to  aid  the  recipient  in  selecting  the
        proper  decryption  key.   This  code word may be viewed as an
        index to a table of keys held by the recipient.

        Note:  Unfortunately, headers must contain envelope,  as  well
               as  contents,  information.  Consequently, it is neces-
               sary that they remain unencrypted, so that  mail  tran-
               sport   services   may   access   them.   Since  names,
               addresses, and "Subject"  field  contents  may  contain


     August 13, 1982              - 24 -                      RFC #822


 
     Standard for ARPA Internet Text Messages


               sensitive  information,  this  requirement limits total
               message privacy.

             Names of encryption software are registered with the Net-
        work  Information Center, SRI International, Menlo Park, Cali-
        fornia.

     4.7.4.  EXTENSION-FIELD

             A limited number of common fields have  been  defined  in
        this  document.   As  network mail requirements dictate, addi-
        tional fields may be standardized.   To  provide  user-defined
        fields  with  a  measure  of  safety,  in name selection, such
        extension-fields will never have names  that  begin  with  the
        string "X-".

             Names of Extension-fields are registered with the Network
        Information Center, SRI International, Menlo Park, California.

     4.7.5.  USER-DEFINED-FIELD

             Individual users of network mail are free to  define  and
        use  additional  header  fields.   Such fields must have names
        which are not already used in the current specification or  in
        any definitions of extension-fields, and the overall syntax of
        these user-defined-fields must conform to this specification's
        rules   for   delimiting  and  folding  fields.   Due  to  the
        extension-field  publishing  process,  the  name  of  a  user-
        defined-field may be pre-empted

        Note:  The prefatory string "X-" will never  be  used  in  the
               names  of Extension-fields.  This provides user-defined
               fields with a protected set of names.


















     August 13, 1982              - 25 -                      RFC #822


 
     Standard for ARPA Internet Text Messages


     5.  DATE AND TIME SPECIFICATION

     5.1.  SYNTAX

     date-time   =  [ day "," ] date time        ; dd mm yy
                                                 ;  hh:mm:ss zzz

     day         =  "Mon"  / "Tue" /  "Wed"  / "Thu"
                 /  "Fri"  / "Sat" /  "Sun"

     date        =  1*2DIGIT month 2DIGIT        ; day month year
                                                 ;  e.g. 20 Jun 82

     month       =  "Jan"  /  "Feb" /  "Mar"  /  "Apr"
                 /  "May"  /  "Jun" /  "Jul"  /  "Aug"
                 /  "Sep"  /  "Oct" /  "Nov"  /  "Dec"

     time        =  hour zone                    ; ANSI and Military

     hour        =  2DIGIT ":" 2DIGIT [":" 2DIGIT]
                                                 ; 00:00:00 - 23:59:59

     zone        =  "UT"  / "GMT"                ; Universal Time
                                                 ; North American : UT
                 /  "EST" / "EDT"                ;  Eastern:  - 5/ - 4
                 /  "CST" / "CDT"                ;  Central:  - 6/ - 5
                 /  "MST" / "MDT"                ;  Mountain: - 7/ - 6
                 /  "PST" / "PDT"                ;  Pacific:  - 8/ - 7
                 /  1ALPHA                       ; Military: Z = UT;
                                                 ;  A:-1; (J not used)
                                                 ;  M:-12; N:+1; Y:+12
                 / ( ("+" / "-") 4DIGIT )        ; Local differential
                                                 ;  hours+min. (HHMM)

     5.2.  SEMANTICS

          If included, day-of-week must be the day implied by the date
     specification.

          Time zone may be indicated in several ways.  "UT" is Univer-
     sal  Time  (formerly called "Greenwich Mean Time"); "GMT" is per-
     mitted as a reference to Universal Time.  The  military  standard
     uses  a  single  character for each zone.  "Z" is Universal Time.
     "A" indicates one hour earlier, and "M" indicates 12  hours  ear-
     lier;  "N"  is  one  hour  later, and "Y" is 12 hours later.  The
     letter "J" is not used.  The other remaining two forms are  taken
     from ANSI standard X3.51-1975.  One allows explicit indication of
     the amount of offset from UT; the other uses  common  3-character
     strings for indicating time zones in North America.


     August 13, 1982              - 26 -                      RFC #822


 
     Standard for ARPA Internet Text Messages


     6.  ADDRESS SPECIFICATION

     6.1.  SYNTAX

     address     =  mailbox                      ; one addressee
                 /  group                        ; named list

     group       =  phrase ":" [#mailbox] ";"

     mailbox     =  addr-spec                    ; simple address
                 /  phrase route-addr            ; name & addr-spec

     route-addr  =  "<" [route] addr-spec ">"

     route       =  1#("@" domain) ":"           ; path-relative

     addr-spec   =  local-part "@" domain        ; global address

     local-part  =  word *("." word)             ; uninterpreted
                                                 ; case-preserved

     domain      =  sub-domain *("." sub-domain)

     sub-domain  =  domain-ref / domain-literal

     domain-ref  =  atom                         ; symbolic reference

     6.2.  SEMANTICS

          A mailbox receives mail.  It is a  conceptual  entity  which
     does  not necessarily pertain to file storage.  For example, some
     sites may choose to print mail on their line printer and  deliver
     the output to the addressee's desk.

          A mailbox specification comprises a person, system  or  pro-
     cess name reference, a domain-dependent string, and a name-domain
     reference.  The name reference is optional and is usually used to
     indicate  the  human name of a recipient.  The name-domain refer-
     ence specifies a sequence of sub-domains.   The  domain-dependent
     string is uninterpreted, except by the final sub-domain; the rest
     of the mail service merely transmits it as a literal string.

     6.2.1.  DOMAINS

        A name-domain is a set of registered (mail)  names.   A  name-
        domain  specification  resolves  to  a subordinate name-domain
        specification  or  to  a  terminal  domain-dependent   string.
        Hence,  domain  specification  is  extensible,  permitting any
        number of registration levels.


     August 13, 1982              - 27 -                      RFC #822


 
     Standard for ARPA Internet Text Messages


        Name-domains model a global, logical, hierarchical  addressing
        scheme.   The  model is logical, in that an address specifica-
        tion is related to name registration and  is  not  necessarily
        tied  to  transmission  path.   The  model's  hierarchy  is  a
        directed graph, called an in-tree, such that there is a single
        path  from  the root of the tree to any node in the hierarchy.
        If more than one path actually exists, they are considered  to
        be different addresses.

        The root node is common to all addresses; consequently, it  is
        not  referenced.   Its  children  constitute "top-level" name-
        domains.  Usually, a service has access to its own full domain
        specification and to the names of all top-level name-domains.

        The "top" of the domain addressing hierarchy -- a child of the
        root  --  is  indicated  by  the right-most field, in a domain
        specification.  Its child is specified to the left, its  child
        to the left, and so on.

        Some groups provide formal registration services;  these  con-
        stitute   name-domains   that  are  independent  logically  of
        specific machines.  In addition, networks and machines  impli-
        citly  compose name-domains, since their membership usually is
        registered in name tables.

        In the case of formal registration, an organization implements
        a  (distributed)  data base which provides an address-to-route
        mapping service for addresses of the form:

                         person@registry.organization

        Note that "organization" is a logical  entity,  separate  from
        any particular communication network.

        A mechanism for accessing "organization" is universally avail-
        able.   That mechanism, in turn, seeks an instantiation of the
        registry; its location is not indicated in the address specif-
        ication.   It  is assumed that the system which operates under
        the name "organization" knows how to find a subordinate regis-
        try.  The registry will then use the "person" string to deter-
        mine where to send the mail specification.

        The latter,  network-oriented  case  permits  simple,  direct,
        attachment-related address specification, such as:

                              user@host.network

        Once the network is accessed, it is expected  that  a  message
        will  go  directly  to the host and that the host will resolve


     August 13, 1982              - 28 -                      RFC #822


 
     Standard for ARPA Internet Text Messages


        the user name, placing the message in the user's mailbox.

     6.2.2.  ABBREVIATED DOMAIN SPECIFICATION

        Since any number of  levels  is  possible  within  the  domain
        hierarchy,  specification  of  a  fully  qualified address can
        become inconvenient.  This standard permits abbreviated domain
        specification, in a special case:

            For the address of  the  sender,  call  the  left-most
            sub-domain  Level  N.   In a header address, if all of
            the sub-domains above (i.e., to the right of) Level  N
            are  the same as those of the sender, then they do not
            have to appear in the specification.   Otherwise,  the
            address must be fully qualified.

            This feature is subject  to  approval  by  local  sub-
            domains.   Individual  sub-domains  may  require their
            member systems, which originate mail, to provide  full
            domain  specification only.  When permitted, abbrevia-
            tions may be present  only  while  the  message  stays
            within the sub-domain of the sender.

            Use of this mechanism requires the sender's sub-domain
            to reserve the names of all top-level domains, so that
            full specifications can be distinguished from abbrevi-
            ated specifications.

        For example, if a sender's address is:

                 sender@registry-A.registry-1.organization-X

        and one recipient's address is:

                recipient@registry-B.registry-1.organization-X

        and another's is:

                recipient@registry-C.registry-2.organization-X

        then ".registry-1.organization-X" need not be specified in the
        the  message,  but  "registry-C.registry-2"  DOES  have  to be
        specified.  That is, the first two addresses may  be  abbrevi-
        ated, but the third address must be fully specified.

        When a message crosses a domain boundary, all  addresses  must
        be  specified  in  the  full format, ending with the top-level
        name-domain in the right-most field.  It is the responsibility
        of  mail  forwarding services to ensure that addresses conform


     August 13, 1982              - 29 -                      RFC #822


 
     Standard for ARPA Internet Text Messages


        with this requirement.  In the case of abbreviated  addresses,
        the  relaying  service must make the necessary expansions.  It
        should be noted that it often is difficult for such a  service
        to locate all occurrences of address abbreviations.  For exam-
        ple, it will not be possible to find such abbreviations within
        the  body  of  the  message.   The "Return-Path" field can aid
        recipients in recovering from these errors.

        Note:  When passing any portion of an addr-spec onto a process
               which  does  not interpret data according to this stan-
               dard (e.g., mail protocol servers).  There must  be  NO
               LWSP-chars  preceding  or  following the at-sign or any
               delimiting period ("."), such as  shown  in  the  above
               examples,   and   only  ONE  SPACE  between  contiguous
               <word>s.

     6.2.3.  DOMAIN TERMS

        A domain-ref must be THE official name of a registry, network,
        or  host.   It  is  a  symbolic  reference, within a name sub-
        domain.  At times, it is necessary to bypass standard  mechan-
        isms  for  resolving  such  references,  using  more primitive
        information, such as a network host address  rather  than  its
        associated host name.

        To permit such references, this standard provides the  domain-
        literal  construct.   Its contents must conform with the needs
        of the sub-domain in which it is interpreted.

        Domain-literals which refer to domains within the ARPA  Inter-
        net  specify  32-bit  Internet addresses, in four 8-bit fields
        noted in decimal, as described in Request for  Comments  #820,
        "Assigned Numbers."  For example:

                                 [10.0.3.19]

        Note:  THE USE OF DOMAIN-LITERALS IS STRONGLY DISCOURAGED.  It
               is  permitted  only  as  a means of bypassing temporary
               system limitations, such as name tables which  are  not
               complete.

        The names of "top-level" domains, and  the  names  of  domains
        under  in  the  ARPA Internet, are registered with the Network
        Information Center, SRI International, Menlo Park, California.

     6.2.4.  DOMAIN-DEPENDENT LOCAL STRING

        The local-part of an  addr-spec  in  a  mailbox  specification
        (i.e.,  the  host's  name for the mailbox) is understood to be


     August 13, 1982              - 30 -                      RFC #822


 
     Standard for ARPA Internet Text Messages


        whatever the receiving mail protocol server allows.  For exam-
        ple,  some systems do not understand mailbox references of the
        form "P. D. Q. Bach", but others do.

        This specification treats periods (".") as lexical separators.
        Hence,  their  presence  in  local-parts which are not quoted-
        strings, is detected.   However,  such  occurrences  carry  NO
        semantics.  That is, if a local-part has periods within it, an
        address parser will divide the local-part into several tokens,
        but  the  sequence  of  tokens will be treated as one uninter-
        preted unit.  The sequence  will  be  re-assembled,  when  the
        address is passed outside of the system such as to a mail pro-
        tocol service.

        For example, the address:

                           First.Last@Registry.Org

        is legal and does not require the local-part to be  surrounded
        with  quotation-marks.   (However,  "First  Last" DOES require
        quoting.)  The local-part of the address, when passed  outside
        of  the  mail  system,  within  the  Registry.Org  domain,  is
        "First.Last", again without quotation marks.

     6.2.5.  BALANCING LOCAL-PART AND DOMAIN

        In some cases, the boundary between local-part and domain  can
        be  flexible.  The local-part may be a simple string, which is
        used for the final determination of the  recipient's  mailbox.
        All  other  levels  of  reference  are, therefore, part of the
        domain.

        For some systems, in the case of abbreviated reference to  the
        local  and  subordinate  sub-domains,  it  may  be possible to
        specify only one reference within the domain  part  and  place
        the  other,  subordinate  name-domain  references  within  the
        local-part.  This would appear as:

                        mailbox.sub1.sub2@this-domain

        Such a specification would be acceptable  to  address  parsers
        which  conform  to  RFC  #733,  but  do not support this newer
        Internet standard.  While contrary to the intent of this stan-
        dard, the form is legal.

        Also, some sub-domains have a specification syntax which  does
        not conform to this standard.  For example:

                      sub-net.mailbox@sub-domain.domain


     August 13, 1982              - 31 -                      RFC #822


 
     Standard for ARPA Internet Text Messages


        uses a different parsing  sequence  for  local-part  than  for
        domain.

        Note:  As a rule,  the  domain  specification  should  contain
               fields  which  are  encoded  according to the syntax of
               this standard and which contain  generally-standardized
               information.   The local-part specification should con-
               tain only that portion of the  address  which  deviates
               from the form or intention of the domain field.

     6.2.6.  MULTIPLE MAILBOXES

        An individual may have several mailboxes and wish  to  receive
        mail  at  whatever  mailbox  is  convenient  for the sender to
        access.  This standard does not provide a means of  specifying
        "any member of" a list of mailboxes.

        A set of individuals may wish to receive mail as a single unit
        (i.e.,  a  distribution  list).  The <group> construct permits
        specification of such a list.  Recipient mailboxes are  speci-
        fied  within  the  bracketed  part (":" - ";").  A copy of the
        transmitted message is to be  sent  to  each  mailbox  listed.
        This  standard  does  not  permit  recursive  specification of
        groups within groups.

        While a list must be named, it is not required that  the  con-
        tents  of  the  list be included.  In this case, the <address>
        serves only as an indication of group distribution  and  would
        appear in the form:

                                    name:;

        Some mail  services  may  provide  a  group-list  distribution
        facility,  accepting  a single mailbox reference, expanding it
        to the full distribution list, and relaying the  mail  to  the
        list's  members.   This standard provides no additional syntax
        for indicating such a  service.   Using  the  <group>  address
        alternative,  while listing one mailbox in it, can mean either
        that the mailbox reference will be expanded to a list or  that
        there is a group with one member.

     6.2.7.  EXPLICIT PATH SPECIFICATION

        At times, a  message  originator  may  wish  to  indicate  the
        transmission  path  that  a  message  should  follow.  This is
        called source routing.  The normal addressing scheme, used  in
        an  addr-spec,  is  carefully separated from such information;
        the <route> portion of a route-addr is provided for such occa-
        sions.  It specifies the sequence of hosts and/or transmission


     August 13, 1982              - 32 -                      RFC #822


 
     Standard for ARPA Internet Text Messages


        services that are  to  be  traversed.   Both  domain-refs  and
        domain-literals may be used.

        Note:  The use of source routing is discouraged.   Unless  the
               sender has special need of path restriction, the choice
               of transmission route should be left to the mail  tran-
               sport service.

     6.3.  RESERVED ADDRESS

          It often is necessary to send mail to a site, without  know-
     ing  any  of its valid addresses.  For example, there may be mail
     system dysfunctions, or a user may wish to find  out  a  person's
     correct address, at that site.

          This standard specifies a single, reserved  mailbox  address
     (local-part)  which  is  to  be valid at each site.  Mail sent to
     that address is to be routed to  a  person  responsible  for  the
     site's mail system or to a person with responsibility for general
     site operation.  The name of the reserved local-part address is:

                                Postmaster

     so that "Postmaster@domain" is required to be valid.

     Note:  This reserved local-part must be  matched  without  sensi-
            tivity to alphabetic case, so that "POSTMASTER", "postmas-
            ter", and even "poStmASteR" is to be accepted.























     August 13, 1982              - 33 -                      RFC #822


 
     Standard for ARPA Internet Text Messages


     7.  BIBLIOGRAPHY


     ANSI.  "USA Standard Code  for  Information  Interchange,"  X3.4.
        American  National Standards Institute: New York (1968).  Also
        in:  Feinler, E.  and J. Postel, eds., "ARPANET Protocol Hand-
        book", NIC 7104.

     ANSI.  "Representations of Universal Time, Local  Time  Differen-
        tials,  and United States Time Zone References for Information
        Interchange," X3.51-1975.  American National Standards  Insti-
        tute:  New York (1975).

     Bemer, R.W., "Time and the Computer."  In:  Interface  Age  (Feb.
        1979).

     Bennett, C.J.  "JNT Mail Protocol".  Joint Network Team,  Ruther-
        ford and Appleton Laboratory:  Didcot, England.

     Bhushan, A.K., Pogran, K.T., Tomlinson,  R.S.,  and  White,  J.E.
        "Standardizing  Network  Mail  Headers,"   ARPANET Request for
        Comments No. 561, Network Information Center  No.  18516;  SRI
        International:  Menlo Park (September 1973).

     Birrell, A.D., Levin, R.,  Needham,  R.M.,  and  Schroeder,  M.D.
        "Grapevine:  An Exercise in Distributed Computing," Communica-
        tions of the ACM 25, 4 (April 1982), 260-274.

     Crocker,  D.H.,  Vittal,  J.J.,  Pogran,  K.T.,  Henderson,  D.A.
        "Standard  for  the  Format  of  ARPA  Network  Text Message,"
        ARPANET Request for  Comments  No.  733,  Network  Information
        Center  No.  41952.   SRI International:  Menlo Park (November
        1977).

     Feinler, E.J. and Postel, J.B.  ARPANET Protocol  Handbook,  Net-
        work  Information  Center  No.  7104   (NTIS AD A003890).  SRI
        International:  Menlo Park (April 1976).

     Harary, F.   "Graph  Theory".   Addison-Wesley:   Reading,  Mass.
        (1969).

     Levin, R. and Schroeder, M.  "Transport  of  Electronic  Messages
        through  a  Network,"   TeleInformatics  79, pp. 29-33.  North
        Holland (1979).  Also  as  Xerox  Palo  Alto  Research  Center
        Technical Report CSL-79-4.

     Myer, T.H. and Henderson, D.A.  "Message Transmission  Protocol,"
        ARPANET  Request  for  Comments,  No. 680, Network Information
        Center No. 32116.  SRI International:  Menlo Park (1975).


     August 13, 1982              - 34 -                      RFC #822


 
     Standard for ARPA Internet Text Messages


     NBS.  "Specification of Message Format for Computer Based Message
        Systems, Recommended Federal Information Processing Standard."
        National  Bureau   of   Standards:    Gaithersburg,   Maryland
        (October 1981).

     NIC.  Internet Protocol Transition Workbook.  Network Information
        Center,   SRI-International,  Menlo  Park,  California  (March
        1982).

     Oppen, D.C. and Dalal, Y.K.  "The Clearinghouse:  A Decentralized
        Agent  for  Locating  Named  Objects in a Distributed Environ-
        ment," OPD-T8103.  Xerox Office Products Division:  Palo Alto,
        CA. (October 1981).

     Postel, J.B.  "Assigned Numbers,"  ARPANET Request for  Comments,
        No. 820.  SRI International:  Menlo Park (August 1982).

     Postel, J.B.  "Simple Mail Transfer  Protocol,"  ARPANET  Request
        for Comments, No. 821.  SRI International:  Menlo Park (August
        1982).

     Shoch, J.F.  "Internetwork naming, addressing  and  routing,"  in
        Proc. 17th IEEE Computer Society International Conference, pp.
        72-79, Sept. 1978, IEEE Cat. No. 78 CH 1388-8C.

     Su, Z. and Postel, J.  "The Domain Naming Convention for Internet
        User  Applications,"  ARPANET  Request  for Comments, No. 819.
        SRI International:  Menlo Park (August 1982).























     August 13, 1982              - 35 -                      RFC #822


 
     Standard for ARPA Internet Text Messages


                                 APPENDIX


     A.  EXAMPLES

     A.1.  ADDRESSES

     A.1.1.  Alfred Neuman <Neuman@BBN-TENEXA>

     A.1.2.  Neuman@BBN-TENEXA

             These two "Alfred Neuman" examples have identical  seman-
        tics, as far as the operation of the local host's mail sending
        (distribution) program (also sometimes  called  its  "mailer")
        and  the remote host's mail protocol server are concerned.  In
        the first example, the  "Alfred  Neuman"  is  ignored  by  the
        mailer,  as "Neuman@BBN-TENEXA" completely specifies the reci-
        pient.  The second example contains  no  superfluous  informa-
        tion,  and,  again,  "Neuman@BBN-TENEXA" is the intended reci-
        pient.

        Note:  When the message crosses name-domain  boundaries,  then
               these specifications must be changed, so as to indicate
               the remainder of the hierarchy, starting with  the  top
               level.

     A.1.3.  "George, Ted" <Shared@Group.Arpanet>

             This form might be used to indicate that a single mailbox
        is  shared  by several users.  The quoted string is ignored by
        the originating host's mailer, because  "Shared@Group.Arpanet"
        completely specifies the destination mailbox.

     A.1.4.  Wilt . (the  Stilt) Chamberlain@NBA.US

             The "(the  Stilt)" is a comment, which is NOT included in
        the  destination  mailbox  address  handed  to the originating
        system's mailer.  The local-part of the address is the  string
        "Wilt.Chamberlain", with NO space between the first and second
        words.

     A.1.5.  Address Lists

     Gourmets:  Pompous Person <WhoZiWhatZit@Cordon-Bleu>,
                Childs@WGBH.Boston, Galloping Gourmet@
                ANT.Down-Under (Australian National Television),
                Cheapie@Discount-Liquors;,
       Cruisers:  Port@Portugal, Jones@SEA;,
         Another@Somewhere.SomeOrg


     August 13, 1982              - 36 -                      RFC #822


 
     Standard for ARPA Internet Text Messages


        This group list example points out the use of comments and the
        mixing of addresses and groups.

     A.2.  ORIGINATOR ITEMS

     A.2.1.  Author-sent

             George Jones logs into his host  as  "Jones".   He  sends
        mail himself.

            From:  Jones@Group.Org

        or

            From:  George Jones <Jones@Group.Org>

     A.2.2.  Secretary-sent

             George Jones logs in as Jones on his  host.   His  secre-
        tary,  who logs in as Secy sends mail for him.  Replies to the
        mail should go to George.

            From:    George Jones <Jones@Group>
            Sender:  Secy@Other-Group

     A.2.3.  Secretary-sent, for user of shared directory

             George Jones' secretary sends mail  for  George.  Replies
        should go to George.

            From:     George Jones<Shared@Group.Org>
            Sender:   Secy@Other-Group

        Note that there need not be a space between  "Jones"  and  the
        "<",  but  adding a space enhances readability (as is the case
        in other examples.

     A.2.4.  Committee activity, with one author

             George is a member of a committee.  He wishes to have any
        replies to his message go to all committee members.

            From:     George Jones <Jones@Host.Net>
            Sender:   Jones@Host
            Reply-To: The Committee: Jones@Host.Net,
                                     Smith@Other.Org,
                                     Doe@Somewhere-Else;

        Note  that  if  George  had  not  included  himself   in   the


     August 13, 1982              - 37 -                      RFC #822


 
     Standard for ARPA Internet Text Messages


        enumeration  of  The  Committee,  he  would not have gotten an
        implicit reply; the presence of the  "Reply-to"  field  SUPER-
        SEDES the sending of a reply to the person named in the "From"
        field.

     A.2.5.  Secretary acting as full agent of author

             George Jones asks his secretary  (Secy@Host)  to  send  a
        message for him in his capacity as Group.  He wants his secre-
        tary to handle all replies.

            From:     George Jones <Group@Host>
            Sender:   Secy@Host
            Reply-To: Secy@Host

     A.2.6.  Agent for user without online mailbox

             A friend  of  George's,  Sarah,  is  visiting.   George's
        secretary  sends  some  mail to a friend of Sarah in computer-
        land.  Replies should go to George, whose mailbox is Jones  at
        Registry.

            From:     Sarah Friendly <Secy@Registry>
            Sender:   Secy-Name <Secy@Registry>
            Reply-To: Jones@Registry.

     A.2.7.  Agent for member of a committee

             George's secretary sends out a message which was authored
        jointly by all the members of a committee.  Note that the name
        of the committee cannot be specified, since <group> names  are
        not permitted in the From field.

            From:   Jones@Host,
                    Smith@Other-Host,
                    Doe@Somewhere-Else
            Sender: Secy@SHost














     August 13, 1982              - 38 -                      RFC #822


 
     Standard for ARPA Internet Text Messages


     A.3.  COMPLETE HEADERS

     A.3.1.  Minimum required

     Date:     26 Aug 76 1429 EDT        Date:     26 Aug 76 1429 EDT
     From:     Jones@Registry.Org   or   From:     Jones@Registry.Org
     Bcc:                                To:       Smith@Registry.Org

        Note that the "Bcc" field may be empty, while the  "To"  field
        is required to have at least one address.

     A.3.2.  Using some of the additional fields

     Date:     26 Aug 76 1430 EDT
     From:     George Jones<Group@Host>
     Sender:   Secy@SHOST
     To:       "Al Neuman"@Mad-Host,
               Sam.Irving@Other-Host
     Message-ID:  <some.string@SHOST>

     A.3.3.  About as complex as you're going to get

     Date     :  27 Aug 76 0932 PDT
     From     :  Ken Davis <KDavis@This-Host.This-net>
     Subject  :  Re: The Syntax in the RFC
     Sender   :  KSecy@Other-Host
     Reply-To :  Sam.Irving@Reg.Organization
     To       :  George Jones <Group@Some-Reg.An-Org>,
                 Al.Neuman@MAD.Publisher
     cc       :  Important folk:
                   Tom Softwood <Balsa@Tree.Root>,
                   "Sam Irving"@Other-Host;,
                 Standard Distribution:
                   /main/davis/people/standard@Other-Host,
                   "<Jones>standard.dist.3"@Tops-20-Host>;
     Comment  :  Sam is away on business. He asked me to handle
                 his mail for him.  He'll be able to provide  a
                 more  accurate  explanation  when  he  returns
                 next week.
     In-Reply-To: <some.string@DBM.Group>, George's message
     X-Special-action:  This is a sample of user-defined field-
                 names.  There could also be a field-name
                 "Special-action", but its name might later be
                 preempted
     Message-ID: <4231.629.XYzi-What@Other-Host>






     August 13, 1982              - 39 -                      RFC #822


 
     Standard for ARPA Internet Text Messages


     B.  SIMPLE FIELD PARSING

          Some mail-reading software systems may wish to perform  only
     minimal  processing,  ignoring  the internal syntax of structured
     field-bodies and treating them the  same  as  unstructured-field-
     bodies.  Such software will need only to distinguish:

         o   Header fields from the message body,

         o   Beginnings of fields from lines which continue fields,

         o   Field-names from field-contents.

          The abbreviated set of syntactic rules  which  follows  will
     suffice  for  this  purpose.  It describes a limited view of mes-
     sages and is a subset of the syntactic rules provided in the main
     part of this specification.  One small exception is that the con-
     tents of field-bodies consist only of text:

     B.1.  SYNTAX


     message         =   *field *(CRLF *text)

     field           =    field-name ":" [field-body] CRLF

     field-name      =  1*<any CHAR, excluding CTLs, SPACE, and ":">

     field-body      =   *text [CRLF LWSP-char field-body]


     B.2.  SEMANTICS

          Headers occur before the message body and are terminated  by
     a null line (i.e., two contiguous CRLFs).

          A line which continues a header field begins with a SPACE or
     HTAB  character,  while  a  line  beginning a field starts with a
     printable character which is not a colon.

          A field-name consists of one or  more  printable  characters
     (excluding  colon,  space, and control-characters).  A field-name
     MUST be contained on one line.  Upper and lower case are not dis-
     tinguished when comparing field-names.







     August 13, 1982              - 40 -                      RFC #822


 
     Standard for ARPA Internet Text Messages


     C.  DIFFERENCES FROM RFC #733

          The following summarizes the differences between this  stan-
     dard  and the one specified in Arpanet Request for Comments #733,
     "Standard for the Format of ARPA  Network  Text  Messages".   The
     differences  are  listed  in the order of their occurrence in the
     current specification.

     C.1.  FIELD DEFINITIONS

     C.1.1.  FIELD NAMES

        These now must be a sequence of  printable  characters.   They
        may not contain any LWSP-chars.

     C.2.  LEXICAL TOKENS

     C.2.1.  SPECIALS

        The characters period ("."), left-square  bracket  ("["),  and
        right-square  bracket ("]") have been added.  For presentation
        purposes, and when passing a specification to  a  system  that
        does  not conform to this standard, periods are to be contigu-
        ous with their surrounding lexical tokens.   No  linear-white-
        space  is  permitted  between them.  The presence of one LWSP-
        char between other tokens is still directed.

     C.2.2.  ATOM

        Atoms may not contain SPACE.

     C.2.3.  SPECIAL TEXT

        ctext and qtext have had backslash ("\") added to the list  of
        prohibited characters.

     C.2.4.  DOMAINS

        The lexical tokens  <domain-literal>  and  <dtext>  have  been
        added.

     C.3.  MESSAGE SPECIFICATION

     C.3.1.  TRACE

        The "Return-path:" and "Received:" fields have been specified.





     August 13, 1982              - 41 -                      RFC #822


 
     Standard for ARPA Internet Text Messages


     C.3.2.  FROM

        The "From" field must contain machine-usable addresses  (addr-
        spec).   Multiple  addresses may be specified, but named-lists
        (groups) may not.

     C.3.3.  RESENT

        The meta-construct of prefacing field names  with  the  string
        "Resent-"  has been added, to indicate that a message has been
        forwarded by an intermediate recipient.

     C.3.4.  DESTINATION

        A message must contain at least one destination address field.
        "To" and "CC" are required to contain at least one address.

     C.3.5.  IN-REPLY-TO

        The field-body is no longer a comma-separated list, although a
        sequence is still permitted.

     C.3.6.  REFERENCE

        The field-body is no longer a comma-separated list, although a
        sequence is still permitted.

     C.3.7.  ENCRYPTED

        A field has been specified that permits  senders  to  indicate
        that the body of a message has been encrypted.

     C.3.8.  EXTENSION-FIELD

        Extension fields are prohibited from beginning with the  char-
        acters "X-".

     C.4.  DATE AND TIME SPECIFICATION

     C.4.1.  SIMPLIFICATION

        Fewer optional forms are permitted  and  the  list  of  three-
        letter time zones has been shortened.

     C.5.  ADDRESS SPECIFICATION






     August 13, 1982              - 42 -                      RFC #822


 
     Standard for ARPA Internet Text Messages


     C.5.1.  ADDRESS

        The use of quoted-string, and the ":"-atom-":" construct, have
        been  removed.   An  address  now  is  either a single mailbox
        reference or is a named list of addresses.  The  latter  indi-
        cates a group distribution.

     C.5.2.  GROUPS

        Group lists are now required to to have a name.   Group  lists
        may not be nested.

     C.5.3.  MAILBOX

        A mailbox specification  may  indicate  a  person's  name,  as
        before.   Such  a  named  list  no longer may specify multiple
        mailboxes and may not be nested.

     C.5.4.  ROUTE ADDRESSING

        Addresses now are taken to be absolute, global specifications,
        independent  of transmission paths.  The <route> construct has
        been provided, to permit explicit specification  of  transmis-
        sion  path.   RFC  #733's  use  of multiple at-signs ("@") was
        intended as a general syntax  for  indicating  routing  and/or
        hierarchical addressing.  The current standard separates these
        specifications and only one at-sign is permitted.

     C.5.5.  AT-SIGN

        The string " at " no longer is used as an  address  delimiter.
        Only at-sign ("@") serves the function.

     C.5.6.  DOMAINS

        Hierarchical, logical name-domains have been added.

     C.6.  RESERVED ADDRESS

     The local-part "Postmaster" has been reserved, so that users  can
     be guaranteed at least one valid address at a site.










     August 13, 1982              - 43 -                      RFC #822


 
     Standard for ARPA Internet Text Messages


     D.  ALPHABETICAL LISTING OF SYNTAX RULES

     address     =  mailbox                      ; one addressee
                 /  group                        ; named list
     addr-spec   =  local-part "@" domain        ; global address
     ALPHA       =  <any ASCII alphabetic character>
                                                 ; (101-132, 65.- 90.)
                                                 ; (141-172, 97.-122.)
     atom        =  1*<any CHAR except specials, SPACE and CTLs>
     authentic   =   "From"       ":"   mailbox  ; Single author
                 / ( "Sender"     ":"   mailbox  ; Actual submittor
                     "From"       ":" 1#mailbox) ; Multiple authors
                                                 ;  or not sender
     CHAR        =  <any ASCII character>        ; (  0-177,  0.-127.)
     comment     =  "(" *(ctext / quoted-pair / comment) ")"
     CR          =  <ASCII CR, carriage return>  ; (     15,      13.)
     CRLF        =  CR LF
     ctext       =  <any CHAR excluding "(",     ; => may be folded
                     ")", "\" & CR, & including
                     linear-white-space>
     CTL         =  <any ASCII control           ; (  0- 37,  0.- 31.)
                     character and DEL>          ; (    177,     127.)
     date        =  1*2DIGIT month 2DIGIT        ; day month year
                                                 ;  e.g. 20 Jun 82
     dates       =   orig-date                   ; Original
                   [ resent-date ]               ; Forwarded
     date-time   =  [ day "," ] date time        ; dd mm yy
                                                 ;  hh:mm:ss zzz
     day         =  "Mon"  / "Tue" /  "Wed"  / "Thu"
                 /  "Fri"  / "Sat" /  "Sun"
     delimiters  =  specials / linear-white-space / comment
     destination =  "To"          ":" 1#address  ; Primary
                 /  "Resent-To"   ":" 1#address
                 /  "cc"          ":" 1#address  ; Secondary
                 /  "Resent-cc"   ":" 1#address
                 /  "bcc"         ":"  #address  ; Blind carbon
                 /  "Resent-bcc"  ":"  #address
     DIGIT       =  <any ASCII decimal digit>    ; ( 60- 71, 48.- 57.)
     domain      =  sub-domain *("." sub-domain)
     domain-literal =  "[" *(dtext / quoted-pair) "]"
     domain-ref  =  atom                         ; symbolic reference
     dtext       =  <any CHAR excluding "[",     ; => may be folded
                     "]", "\" & CR, & including
                     linear-white-space>
     extension-field =
                   <Any field which is defined in a document
                    published as a formal extension to this
                    specification; none will have names beginning
                    with the string "X-">


     August 13, 1982              - 44 -                      RFC #822


 
     Standard for ARPA Internet Text Messages


     field       =  field-name ":" [ field-body ] CRLF
     fields      =    dates                      ; Creation time,
                      source                     ;  author id & one
                    1*destination                ;  address required
                     *optional-field             ;  others optional
     field-body  =  field-body-contents
                    [CRLF LWSP-char field-body]
     field-body-contents =
                   <the ASCII characters making up the field-body, as
                    defined in the following sections, and consisting
                    of combinations of atom, quoted-string, and
                    specials tokens, or else consisting of texts>
     field-name  =  1*<any CHAR, excluding CTLs, SPACE, and ":">
     group       =  phrase ":" [#mailbox] ";"
     hour        =  2DIGIT ":" 2DIGIT [":" 2DIGIT]
                                                 ; 00:00:00 - 23:59:59
     HTAB        =  <ASCII HT, horizontal-tab>   ; (     11,       9.)
     LF          =  <ASCII LF, linefeed>         ; (     12,      10.)
     linear-white-space =  1*([CRLF] LWSP-char)  ; semantics = SPACE
                                                 ; CRLF => folding
     local-part  =  word *("." word)             ; uninterpreted
                                                 ; case-preserved
     LWSP-char   =  SPACE / HTAB                 ; semantics = SPACE
     mailbox     =  addr-spec                    ; simple address
                 /  phrase route-addr            ; name & addr-spec
     message     =  fields *( CRLF *text )       ; Everything after
                                                 ;  first null line
                                                 ;  is message body
     month       =  "Jan"  /  "Feb" /  "Mar"  /  "Apr"
                 /  "May"  /  "Jun" /  "Jul"  /  "Aug"
                 /  "Sep"  /  "Oct" /  "Nov"  /  "Dec"
     msg-id      =  "<" addr-spec ">"            ; Unique message id
     optional-field =
                 /  "Message-ID"        ":"   msg-id
                 /  "Resent-Message-ID" ":"   msg-id
                 /  "In-Reply-To"       ":"  *(phrase / msg-id)
                 /  "References"        ":"  *(phrase / msg-id)
                 /  "Keywords"          ":"  #phrase
                 /  "Subject"           ":"  *text
                 /  "Comments"          ":"  *text
                 /  "Encrypted"         ":" 1#2word
                 /  extension-field              ; To be defined
                 /  user-defined-field           ; May be pre-empted
     orig-date   =  "Date"        ":"   date-time
     originator  =   authentic                   ; authenticated addr
                   [ "Reply-To"   ":" 1#address] )
     phrase      =  1*word                       ; Sequence of words




     August 13, 1982              - 45 -                      RFC #822


 
     Standard for ARPA Internet Text Messages


     qtext       =  <any CHAR excepting <">,     ; => may be folded
                     "\" & CR, and including
                     linear-white-space>
     quoted-pair =  "\" CHAR                     ; may quote any char
     quoted-string = <"> *(qtext/quoted-pair) <">; Regular qtext or
                                                 ;   quoted chars.
     received    =  "Received"    ":"            ; one per relay
                       ["from" domain]           ; sending host
                       ["by"   domain]           ; receiving host
                       ["via"  atom]             ; physical path
                      *("with" atom)             ; link/mail protocol
                       ["id"   msg-id]           ; receiver msg id
                       ["for"  addr-spec]        ; initial form
                        ";"    date-time         ; time received

     resent      =   resent-authentic
                   [ "Resent-Reply-To"  ":" 1#address] )
     resent-authentic =
                 =   "Resent-From"      ":"   mailbox
                 / ( "Resent-Sender"    ":"   mailbox
                     "Resent-From"      ":" 1#mailbox  )
     resent-date =  "Resent-Date" ":"   date-time
     return      =  "Return-path" ":" route-addr ; return address
     route       =  1#("@" domain) ":"           ; path-relative
     route-addr  =  "<" [route] addr-spec ">"
     source      = [  trace ]                    ; net traversals
                      originator                 ; original mail
                   [  resent ]                   ; forwarded
     SPACE       =  <ASCII SP, space>            ; (     40,      32.)
     specials    =  "(" / ")" / "<" / ">" / "@"  ; Must be in quoted-
                 /  "," / ";" / ":" / "\" / <">  ;  string, to use
                 /  "." / "[" / "]"              ;  within a word.
     sub-domain  =  domain-ref / domain-literal
     text        =  <any CHAR, including bare    ; => atoms, specials,
                     CR & bare LF, but NOT       ;  comments and
                     including CRLF>             ;  quoted-strings are
                                                 ;  NOT recognized.
     time        =  hour zone                    ; ANSI and Military
     trace       =    return                     ; path to sender
                    1*received                   ; receipt tags
     user-defined-field =
                   <Any field which has not been defined
                    in this specification or published as an
                    extension to this specification; names for
                    such fields must be unique and may be
                    pre-empted by published extensions>
     word        =  atom / quoted-string




     August 13, 1982              - 46 -                      RFC #822


 
     Standard for ARPA Internet Text Messages


     zone        =  "UT"  / "GMT"                ; Universal Time
                                                 ; North American : UT
                 /  "EST" / "EDT"                ;  Eastern:  - 5/ - 4
                 /  "CST" / "CDT"                ;  Central:  - 6/ - 5
                 /  "MST" / "MDT"                ;  Mountain: - 7/ - 6
                 /  "PST" / "PDT"                ;  Pacific:  - 8/ - 7
                 /  1ALPHA                       ; Military: Z = UT;
     <">         =  <ASCII quote mark>           ; (     42,      34.)











































     August 13, 1982              - 47 -                      RFC #822



================================================
FILE: doc/notes/rfc/rfc1341.txt
================================================






            Network Working Group               N. Borenstein, Bellcore
            Request for Comments: 1341               N. Freed, Innosoft
                                                              June 1992



                   MIME  (Multipurpose Internet Mail Extensions):


                      Mechanisms for Specifying and Describing
                       the Format of Internet Message Bodies


          Status of this Memo

            This RFC specifies an IAB standards track protocol  for  the
            Internet  community, and requests discussion and suggestions
            for improvements.  Please refer to the  current  edition  of
            the    "IAB    Official    Protocol   Standards"   for   the
            standardization  state  and   status   of   this   protocol.
            Distribution of this memo is unlimited.

          Abstract

            RFC 822 defines  a  message  representation  protocol  which
            specifies  considerable  detail  about  message headers, but
            which leaves the message content, or message body,  as  flat
            ASCII  text.   This document redefines the format of message
            bodies to allow multi-part textual and  non-textual  message
            bodies  to  be  represented  and  exchanged  without loss of
            information.   This is based on earlier work  documented  in
            RFC  934  and  RFC  1049, but extends and revises that work.
            Because RFC 822 said so little about  message  bodies,  this
            document  is  largely  orthogonal to (rather than a revision
            of) RFC 822.

            In  particular,  this  document  is  designed   to   provide
            facilities  to include multiple objects in a single message,
            to represent body text in  character  sets  other  than  US-
            ASCII,  to  represent formatted multi-font text messages, to
            represent non-textual material  such  as  images  and  audio
            fragments,  and  generally  to  facilitate  later extensions
            defining new types of Internet mail for use  by  cooperating
            mail agents.

            This document does NOT extend Internet mail header fields to
            permit  anything  other  than  US-ASCII  text  data.   It is
            recognized that such extensions are necessary, and they  are
            the subject of a companion document [RFC -1342].

            A table of contents appears at the end of this document.






            Borenstein & Freed                                  [Page i]







            1    Introduction

            Since its publication in 1982, RFC 822 [RFC-822] has defined
            the   standard  format  of  textual  mail  messages  on  the
            Internet.  Its success has been such that the RFC 822 format
            has  been  adopted,  wholly  or  partially,  well beyond the
            confines of the Internet and  the  Internet  SMTP  transport
            defined  by RFC 821 [RFC-821].  As the format has seen wider
            use,  a  number  of  limitations  have  proven  increasingly
            restrictive for the user community.

            RFC 822 was intended to specify a format for text  messages.
            As such, non-text messages, such as multimedia messages that
            might include audio or images,  are  simply  not  mentioned.
            Even in the case of text, however, RFC 822 is inadequate for
            the needs of mail users whose languages require the  use  of
            character  sets  richer  than US ASCII [US-ASCII]. Since RFC
            822 does not specify mechanisms for mail  containing  audio,
            video,  Asian  language  text, or even text in most European
            languages, additional specifications are needed

            One of the notable limitations of  RFC  821/822  based  mail
            systems  is  the  fact  that  they  limit  the  contents  of
            electronic  mail  messages  to  relatively  short  lines  of
            seven-bit  ASCII.   This  forces  users  to convert any non-
            textual data that they may wish to send into seven-bit bytes
            representable  as printable ASCII characters before invoking
            a local mail UA (User Agent,  a  program  with  which  human
            users  send  and  receive  mail). Examples of such encodings
            currently used in the  Internet  include  pure  hexadecimal,
            uuencode,  the  3-in-4 base 64 scheme specified in RFC 1113,
            the Andrew Toolkit Representation [ATK], and many others.

            The limitations of RFC 822 mail become even more apparent as
            gateways  are  designed  to  allow  for the exchange of mail
            messages between RFC 822 hosts and X.400 hosts. X.400 [X400]
            specifies  mechanisms  for the inclusion of non-textual body
            parts  within  electronic  mail   messages.    The   current
            standards  for  the  mapping  of  X.400  messages to RFC 822
            messages specify that either X.400  non-textual  body  parts
            should  be converted to (not encoded in) an ASCII format, or
            that they should be discarded, notifying the  RFC  822  user
            that  discarding has occurred.  This is clearly undesirable,
            as information that a user may  wish  to  receive  is  lost.
            Even  though  a  user's  UA  may  not have the capability of
            dealing with the non-textual body part, the user might  have
            some  mechanism  external  to the UA that can extract useful
            information from the body part.  Moreover, it does not allow
            for  the  fact  that the message may eventually be gatewayed
            back into an X.400 message handling system (i.e., the  X.400
            message  is  "tunneled"  through  Internet  mail), where the
            non-textual  information  would  definitely  become   useful
            again.




            Borenstein & Freed                                  [Page 1]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


            This document describes several mechanisms that  combine  to
            solve most of these problems without introducing any serious
            incompatibilities with the existing world of RFC  822  mail.
            In particular, it describes:

            1.  A MIME-Version header field, which uses a version number
                 to  declare  a  message  to  be  conformant  with  this
                 specification and  allows  mail  processing  agents  to
                 distinguish  between  such messages and those generated
                 by older or non-conformant software, which is  presumed
                 to lack such a field.

            2.  A Content-Type header field, generalized from  RFC  1049
                 [RFC-1049],  which  can be used to specify the type and
                 subtype of data in the body of a message and  to  fully
                 specify  the  native  representation (encoding) of such
                 data.

                 2.a.  A "text" Content-Type value, which can be used to
                      represent  textual  information  in  a  number  of
                      character  sets  and  formatted  text  description
                      languages in a standardized manner.

                 2.b.  A "multipart" Content-Type value,  which  can  be
                      used  to  combine  several body parts, possibly of
                      differing types of data, into a single message.

                 2.c.  An "application" Content-Type value, which can be
                      used  to transmit application data or binary data,
                      and hence,  among  other  uses,  to  implement  an
                      electronic mail file transfer service.

                 2.d.  A "message" Content-Type value, for encapsulating
                      a mail message.

                 2.e  An "image"  Content-Type value,  for  transmitting
                      still image (picture) data.

                 2.f.  An "audio"  Content-Type value, for  transmitting
                      audio or voice data.

                 2.g.  A "video"  Content-Type value,  for  transmitting
                      video or moving image data, possibly with audio as
                      part of the composite video data format.

            3.  A Content-Transfer-Encoding header field, which  can  be
                 used  to specify an auxiliary encoding that was applied
                 to the data in order to allow it to pass  through  mail
                 transport  mechanisms  which may have data or character
                 set limitations.

            4.  Two optional header fields that can be used  to  further
                 describe the data in a message body, the Content-ID and
                 Content-Description header fields.



            Borenstein & Freed                                  [Page 2]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


            MIME has been carefully designed as an extensible mechanism,
            and  it  is  expected  that  the set of content-type/subtype
            pairs   and   their   associated   parameters   will    grow
            significantly with time.  Several other MIME fields, notably
            including character set names, are likely to have new values
            defined  over time.  In order to ensure that the set of such
            values is  developed  in  an  orderly,  well-specified,  and
            public  manner,  MIME  defines  a registration process which
            uses the Internet Assigned Numbers  Authority  (IANA)  as  a
            central  registry  for  such  values.   Appendix  F provides
            details about how IANA registration is accomplished.

            Finally, to specify and promote interoperability, Appendix A
            of  this  document  provides a basic applicability statement
            for a subset of the above mechanisms that defines a  minimal
            level of "conformance" with this document.

            HISTORICAL NOTE:  Several of  the  mechanisms  described  in
            this  document  may seem somewhat strange or even baroque at
            first reading.  It is important to note  that  compatibility
            with  existing  standards  AND  robustness  across  existing
            practice were two of the highest priorities of  the  working
            group   that   developed   this  document.   In  particular,
            compatibility was always favored over elegance.

            2    Notations, Conventions, and Generic BNF Grammar

            This document is being published in  two  versions,  one  as
            plain  ASCII  text  and  one  as  PostScript.  The latter is
            recommended, though the textual contents are  identical.  An
            Andrew-format  copy  of this document is also available from
            the first author (Borenstein).

            Although the mechanisms specified in this document  are  all
            described  in prose, most are also described formally in the
            modified BNF notation of RFC 822.  Implementors will need to
            be  familiar  with this notation in order to understand this
            specification, and are referred to RFC 822  for  a  complete
            explanation of the modified BNF notation.

            Some of the modified BNF in this document makes reference to
            syntactic  entities  that  are defined in RFC 822 and not in
            this document.  A complete formal grammar, then, is obtained
            by combining the collected grammar appendix of this document
            with that of RFC 822.

            The term CRLF, in this document, refers to the  sequence  of
            the  two  ASCII  characters CR (13) and LF (10) which, taken
            together, in this order, denote a  line  break  in  RFC  822
            mail.

            The term "character  set",  wherever  it  is  used  in  this
            document,  refers  to a coded character set, in the sense of
            ISO character set standardization  work,  and  must  not  be



            Borenstein & Freed                                  [Page 3]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


            misinterpreted as meaning "a set of characters."

            The term "message", when not further qualified, means either
            the (complete or "top-level") message being transferred on a
            network, or  a  message  encapsulated  in  a  body  of  type
            "message".

            The term "body part", in this document,  means  one  of  the
            parts  of  the body of a multipart entity. A body part has a
            header and a body, so it makes sense to speak about the body
            of a body part.

            The term "entity", in this document, means either a  message
            or  a  body  part.  All kinds of entities share the property
            that they have a header and a body.

            The term "body", when not further qualified, means the  body
            of  an  entity, that is the body of either a message or of a
            body part.

            Note : the previous four definitions are  clearly  circular.
            This  is  unavoidable,  since the overal structure of a MIME
            message is indeed recursive.

            In this document, all numeric and octet values are given  in
            decimal notation.

            It must be noted that  Content-Type  values,  subtypes,  and
            parameter  names  as  defined  in  this  document  are case-
            insensitive.  However, parameter values  are  case-sensitive
            unless otherwise specified for the specific parameter.

            FORMATTING NOTE:  This document has been carefully formatted
            for   ease  of  reading.  The  PostScript  version  of  this
            document, in particular, places notes like this  one,  which
            may  be  skipped  by  the  reader, in a smaller, italicized,
            font, and indents it as well.  In the text version, only the
            indentation  is  preserved,  so  if you are reading the text
            version of this you  might  consider  using  the  PostScript
            version  instead.  However,  all such notes will be indented
            and preceded by "NOTE:" or some similar  introduction,  even
            in the text version.

            The primary purpose  of  these  non-essential  notes  is  to
            convey  information about the rationale of this document, or
            to  place  this  document  in  the  proper   historical   or
            evolutionary  context.   Such  information may be skipped by
            those who are  focused  entirely  on  building  a  compliant
            implementation,  but  may  be  of  use  to those who wish to
            understand why this document is written as it is.

            For ease of  recognition,  all  BNF  definitions  have  been
            placed  in  a  fixed-width font in the PostScript version of
            this document.



            Borenstein & Freed                                  [Page 4]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


            3    The MIME-Version Header Field

            Since RFC 822 was published in 1982, there has  really  been
            only  one  format  standard for Internet messages, and there
            has  been  little  perceived  need  to  declare  the  format
            standard  in  use.  This document is an independent document
            that complements RFC 822. Although the  extensions  in  this
            document have been defined in such a way as to be compatible
            with RFC 822, there are  still  circumstances  in  which  it
            might  be  desirable  for  a  mail-processing  agent to know
            whether a message was composed  with  the  new  standard  in
            mind.

            Therefore, this document defines a new header field,  "MIME-
            Version",  which is to be used to declare the version of the
            Internet message body format standard in use.

            Messages composed in  accordance  with  this  document  MUST
            include  such  a  header  field, with the following verbatim
            text:

            MIME-Version: 1.0

            The presence of this header field is an assertion  that  the
            message has been composed in compliance with this document.

            Since it is possible that a future document might extend the
            message format standard again, a formal BNF is given for the
            content of the MIME-Version field:

            MIME-Version := text

            Thus, future  format  specifiers,  which  might  replace  or
            extend  "1.0", are (minimally) constrained by the definition
            of "text", which appears in RFC 822.

            Note that the MIME-Version header field is required  at  the
            top  level  of  a  message. It is not required for each body
            part of a multipart entity.  It is required for the embedded
            headers  of  a  body  of  type  "message" if and only if the
            embedded message is itself claimed to be MIME-compliant.
















            Borenstein & Freed                                  [Page 5]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


            4    The Content-Type Header Field

            The purpose of the Content-Type field  is  to  describe  the
            data  contained  in the body fully enough that the receiving
            user agent can pick an appropriate  agent  or  mechanism  to
            present  the  data  to the user, or  otherwise deal with the
            data in an appropriate manner.

            HISTORICAL NOTE:  The Content-Type header  field  was  first
            defined  in RFC 1049.  RFC 1049 Content-types used a simpler
            and less powerful syntax, but one that is largely compatible
            with the mechanism given here.

            The Content-Type  header field is used to specify the nature
            of  the  data  in  the body of an entity, by giving type and
            subtype identifiers, and by providing auxiliary  information
            that may be required for certain types.   After the type and
            subtype names, the remainder of the header field is simply a
            set of parameters, specified in an attribute/value notation.
            The set of meaningful parameters differs for  the  different
            types.   The  ordering  of  parameters  is  not significant.
            Among the defined parameters is  a  "charset"  parameter  by
            which  the  character  set used in the body may be declared.
            Comments are allowed in accordance with RFC  822  rules  for
            structured header fields.

            In general, the top-level Content-Type is  used  to  declare
            the  general  type  of  data,  while the subtype specifies a
            specific format for that type of data.  Thus, a Content-Type
            of  "image/xyz" is enough to tell a user agent that the data
            is an image, even if the user agent has no knowledge of  the
            specific  image format "xyz".  Such information can be used,
            for example, to decide whether or not to show a user the raw
            data from an unrecognized subtype -- such an action might be
            reasonable for unrecognized subtypes of text,  but  not  for
            unrecognized  subtypes  of image or audio.  For this reason,
            registered subtypes of audio, image, text, and video, should
            not  contain  embedded  information  that  is  really  of  a
            different type.  Such compound types should  be  represented
            using the "multipart" or "application" types.

            Parameters are modifiers of the content-subtype, and do  not
            fundamentally  affect  the  requirements of the host system.
            Although  most  parameters  make  sense  only  with  certain
            content-types,  others  are  "global" in the sense that they
            might apply to any  subtype.  For  example,  the  "boundary"
            parameter makes sense only for the "multipart" content-type,
            but the "charset" parameter might make  sense  with  several
            content-types.

            An initial set of seven Content-Types  is  defined  by  this
            document.   This  set  of  top-level names is intended to be
            substantially complete.  It is expected  that  additions  to
            the   larger   set  of  supported  types  can  generally  be



            Borenstein & Freed                                  [Page 6]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


            accomplished by  the  creation  of  new  subtypes  of  these
            initial  types.   In the future, more top-level types may be
            defined only by an extension to this standard.   If  another
            primary  type is to be used for any reason, it must be given
            a name starting  with  "X-"  to  indicate  its  non-standard
            status  and  to  avoid  a  potential  conflict with a future
            official name.

            In the Extended BNF notation  of  RFC  822,  a  Content-Type
            header field value is defined as follows:

            Content-Type := type "/" subtype *[";" parameter]

            type :=          "application"     / "audio"
                      / "image"           / "message"
                      / "multipart"  / "text"
                      / "video"           / x-token

            x-token := <The two characters "X-" followed, with no
                       intervening white space, by any token>

            subtype := token

            parameter := attribute "=" value

            attribute := token

            value := token / quoted-string

            token := 1*<any CHAR except SPACE, CTLs, or tspecials>

            tspecials :=  "(" / ")" / "<" / ">" / "@"  ; Must be in
                       /  "," / ";" / ":" / "\" / <">  ; quoted-string,
                       /  "/" / "[" / "]" / "?" / "."  ; to use within
                       /  "="                        ; parameter values

            Note that the definition of "tspecials" is the same  as  the
            RFC  822  definition  of "specials" with the addition of the
            three characters "/", "?", and "=".

            Note also that a subtype specification is MANDATORY.   There
            are no default subtypes.

            The  type,  subtype,  and  parameter  names  are  not   case
            sensitive.   For  example,  TEXT,  Text,  and  TeXt  are all
            equivalent.  Parameter values are normally  case  sensitive,
            but   certain   parameters   are  interpreted  to  be  case-
            insensitive, depending on the intended use.   (For  example,
            multipart  boundaries  are  case-sensitive, but the "access-
            type" for message/External-body is not case-sensitive.)

            Beyond this syntax, the only constraint on the definition of
            subtype  names  is  the  desire  that  their  uses  must not
            conflict.  That is, it would  be  undesirable  to  have  two



            Borenstein & Freed                                  [Page 7]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


            different       communities       using       "Content-Type:
            application/foobar"  to  mean  two  different  things.   The
            process  of  defining  new  content-subtypes,  then,  is not
            intended to be a mechanism for  imposing  restrictions,  but
            simply  a  mechanism  for publicizing the usages. There are,
            therefore,  two  acceptable  mechanisms  for  defining   new
            Content-Type subtypes:

                 1.  Private values (starting  with  "X-")  may  be
                      defined  bilaterally  between two cooperating
                      agents  without   outside   registration   or
                      standardization.

                 2.   New  standard  values  must  be   documented,
                      registered  with,  and  approved  by IANA, as
                      described in Appendix F.  Where intended  for
                      public  use,  the  formats they refer to must
                      also be defined by a published specification,
                      and possibly offered for standardization.

            The seven  standard  initial  predefined  Content-Types  are
            detailed in the bulk of this document.  They are:

                 text --  textual  information.   The  primary  subtype,
                      "plain",  indicates plain (unformatted) text.   No
                      special software  is  required  to  get  the  full
                      meaning  of  the  text, aside from support for the
                      indicated character set.  Subtypes are to be  used
                      for  enriched  text  in  forms  where  application
                      software may enhance the appearance of  the  text,
                      but such software must not be required in order to
                      get the general  idea  of  the  content.  Possible
                      subtypes  thus include any readable word processor
                      format.   A  very  simple  and  portable  subtype,
                      richtext, is defined in this document.
                 multipart --  data  consisting  of  multiple  parts  of
                      independent  data  types.   Four  initial subtypes
                      are  defined,  including   the   primary   "mixed"
                      subtype,  "alternative"  for representing the same
                      data in multiple  formats,  "parallel"  for  parts
                      intended to be viewed simultaneously, and "digest"
                      for multipart entities in which each  part  is  of
                      type "message".
                 message  --  an  encapsulated  message.   A   body   of
                      Content-Type "message" is itself a fully formatted
                      RFC 822 conformant message which may  contain  its
                      own  different  Content-Type  header  field.   The
                      primary  subtype  is  "rfc822".    The   "partial"
                      subtype is defined for partial messages, to permit
                      the fragmented transmission  of  bodies  that  are
                      thought  to be too large to be passed through mail
                      transport    facilities.      Another     subtype,
                      "External-body",  is  defined for specifying large
                      bodies by reference to an external data source.



            Borenstein & Freed                                  [Page 8]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


                 image --  image data.  Image requires a display  device
                      (such  as a graphical display, a printer, or a FAX
                      machine)  to  view   the   information.    Initial
                      subtypes  are  defined  for  two widely-used image
                      formats, jpeg and gif.
                 audio --  audio data,  with  initial  subtype  "basic".
                      Audio  requires  an audio output device (such as a
                      speaker or a telephone) to "display" the contents.
                 video --  video data.  Video requires the capability to
                      display   moving   images,   typically   including
                      specialized hardware and  software.   The  initial
                      subtype is "mpeg".
                 application --  some  other  kind  of  data,  typically
                      either uninterpreted binary data or information to
                      be processed by  a  mail-based  application.   The
                      primary  subtype, "octet-stream", is to be used in
                      the case of uninterpreted binary  data,  in  which
                      case  the  simplest recommended action is to offer
                      to write the information into a file for the user.
                      Two  additional  subtypes, "ODA" and "PostScript",
                      are defined for transporting  ODA  and  PostScript
                      documents  in  bodies.   Other  expected  uses for
                      "application"  include  spreadsheets,   data   for
                      mail-based  scheduling  systems, and languages for
                      "active" (computational) email.  (Note that active
                      email   entails   several  securityconsiderations,
                      which  are   discussed   later   in   this   memo,
                      particularly      in      the      context      of
                      application/PostScript.)

            Default RFC 822 messages are typed by this protocol as plain
            text  in the US-ASCII character set, which can be explicitly
            specified as "Content-type:  text/plain;  charset=us-ascii".
            If  no  Content-Type  is specified, either by error or by an
            older user agent, this default is assumed.   In the presence
            of  a  MIME-Version header field, a receiving User Agent can
            also assume  that  plain  US-ASCII  text  was  the  sender's
            intent.   In  the  absence  of a MIME-Version specification,
            plain US-ASCII text must still be assumed, but the  sender's
            intent might have been otherwise.

            RATIONALE:  In the absence of any Content-Type header  field
            or MIME-Version header field, it is impossible to be certain
            that a message is actually text in  the  US-ASCII  character
            set,  since  it  might  well  be  a  message that, using the
            conventions that predate this  document,  includes  text  in
            another  character  set or non-textual data in a manner that
            cannot  be  automatically  recognized  (e.g.,  a   uuencoded
            compressed  UNIX  tar  file).  Although  there  is  no fully
            acceptable alternative to treating such untyped messages  as
            "text/plain;  charset=us-ascii",  implementors should remain
            aware that if a message lacks both the MIME-Version and  the
            Content-Type  header  fields,  it  may  in  practice contain
            almost anything.



            Borenstein & Freed                                  [Page 9]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


            It should be noted that  the  list  of  Content-Type  values
            given  here  may  be  augmented  in time, via the mechanisms
            described above, and that the set of subtypes is expected to
            grow substantially.

            When a mail reader encounters mail with an unknown  Content-
            type  value,  it  should generally treat it as equivalent to
            "application/octet-stream",  as  described  later  in   this
            document.

            5    The Content-Transfer-Encoding Header Field

            Many Content-Types which could usefully be  transported  via
            email  are  represented, in their "natural" format, as 8-bit
            character or binary data.  Such data cannot  be  transmitted
            over   some  transport  protocols.   For  example,  RFC  821
            restricts mail messages to 7-bit  US-ASCII  data  with  1000
            character lines.

            It is necessary, therefore, to define a  standard  mechanism
            for  re-encoding  such  data into a 7-bit short-line format.
            This  document  specifies  that  such  encodings   will   be
            indicated by a new "Content-Transfer-Encoding" header field.
            The Content-Transfer-Encoding field is used to indicate  the
            type  of  transformation  that  has  been  used  in order to
            represent the body in an acceptable manner for transport.

            Unlike Content-Types, a proliferation  of  Content-Transfer-
            Encoding  values  is  undesirable and unnecessary.  However,
            establishing   only   a   single   Content-Transfer-Encoding
            mechanism  does  not  seem  possible.    There is a tradeoff
            between the desire for a compact and efficient  encoding  of
            largely-binary  data  and the desire for a readable encoding
            of data that is mostly, but not entirely, 7-bit  data.   For
            this reason, at least two encoding mechanisms are necessary:
            a "readable" encoding and a "dense" encoding.

            The Content-Transfer-Encoding field is designed  to  specify
            an invertible mapping between the "native" representation of
            a type of data and a  representation  that  can  be  readily
            exchanged  using  7  bit  mail  transport protocols, such as
            those defined by RFC 821 (SMTP). This  field  has  not  been
            defined  by  any  previous  standard. The field's value is a
            single token specifying the type of encoding, as  enumerated
            below.  Formally:

            Content-Transfer-Encoding := "BASE64" / "QUOTED-PRINTABLE" /
                                         "8BIT"   / "7BIT" /
                                         "BINARY" / x-token

            These values are not case sensitive.  That  is,  Base64  and
            BASE64  and  bAsE64 are all equivalent.  An encoding type of
            7BIT requires that the body is already in a seven-bit  mail-
            ready representation.  This is the default value -- that is,



            Borenstein & Freed                                 [Page 10]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


            "Content-Transfer-Encoding:  7BIT"   is   assumed   if   the
            Content-Transfer-Encoding header field is not present.

            The values "8bit", "7bit", and "binary" all  imply  that  NO
            encoding  has  been performed. However, they are potentially
            useful as indications of the kind of data contained  in  the
            object,  and  therefore  of  the kind of encoding that might
            need to be performed for transmission in a  given  transport
            system.   "7bit"  means  that the data is all represented as
            short lines of US-ASCII data.  "8bit" means that  the  lines
            are  short,  but  there  may be non-ASCII characters (octets
            with the high-order bit set).  "Binary" means that not  only
            may non-ASCII characters be present, but also that the lines
            are not necessarily short enough for SMTP transport.

            The difference between  "8bit"  (or  any  other  conceivable
            bit-width  token)  and  the  "binary" token is that "binary"
            does not require adherence to any limits on line  length  or
            to  the  SMTP  CRLF semantics, while the bit-width tokens do
            require such adherence.  If the body contains  data  in  any
            bit-width   other  than  7-bit,  the  appropriate  bit-width
            Content-Transfer-Encoding token must be used  (e.g.,  "8bit"
            for unencoded 8 bit wide data).  If the body contains binary
            data, the "binary" Content-Transfer-Encoding token  must  be
            used.

            NOTE:  The distinction between the Content-Transfer-Encoding
            values  of  "binary,"  "8bit," etc. may seem unimportant, in
            that all of them really mean "none" -- that  is,  there  has
            been  no encoding of the data for transport.  However, clear
            labeling will be  of  enormous  value  to  gateways  between
            future mail transport systems with differing capabilities in
            transporting data that do not meet the restrictions  of  RFC
            821 transport.

            As of  the  publication  of  this  document,  there  are  no
            standardized  Internet transports for which it is legitimate
            to include unencoded 8-bit or binary data  in  mail  bodies.
            Thus  there  are  no  circumstances  in  which the "8bit" or
            "binary" Content-Transfer-Encoding is actually legal on  the
            Internet.   However,  in the event that 8-bit or binary mail
            transport becomes a reality in Internet mail, or  when  this
            document  is  used  in  conjunction  with any other 8-bit or
            binary-capable transport mechanism, 8-bit or  binary  bodies
            should be labeled as such using this mechanism.

            NOTE:  The five values  defined  for  the  Content-Transfer-
            Encoding  field  imply  nothing about the Content-Type other
            than the algorithm by which it was encoded or the  transport
            system requirements if unencoded.

            Implementors  may,  if  necessary,   define   new   Content-
            Transfer-Encoding  values, but must use an x-token, which is
            a name prefixed by "X-" to indicate its non-standard status,



            Borenstein & Freed                                 [Page 11]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


            e.g.,    "Content-Transfer-Encoding:     x-my-new-encoding".
            However, unlike Content-Types and subtypes, the creation  of
            new   Content-Transfer-Encoding  values  is  explicitly  and
            strongly  discouraged,  as  it  seems   likely   to   hinder
            interoperability  with  little potential benefit.  Their use
            is allowed only  as  the  result  of  an  agreement  between
            cooperating user agents.

            If a Content-Transfer-Encoding header field appears as  part
            of  a  message header, it applies to the entire body of that
            message.   If  a  Content-Transfer-Encoding   header   field
            appears as part of a body part's headers, it applies only to
            the body of that  body  part.   If  an  entity  is  of  type
            "multipart"  or  "message", the Content-Transfer-Encoding is
            not permitted to have any  value  other  than  a  bit  width
            (e.g., "7bit", "8bit", etc.) or "binary".

            It should be noted that email is character-oriented, so that
            the  mechanisms  described  here are mechanisms for encoding
            arbitrary byte streams, not bit streams.  If a bit stream is
            to  be encoded via one of these mechanisms, it must first be
            converted to an 8-bit byte stream using the network standard
            bit  order  ("big-endian"),  in  which the earlier bits in a
            stream become the higher-order bits in a byte.  A bit stream
            not  ending at an 8-bit boundary must be padded with zeroes.
            This document provides a mechanism for noting  the  addition
            of such padding in the case of the application Content-Type,
            which has a "padding" parameter.

            The encoding mechanisms defined here explicitly  encode  all
            data  in  ASCII.   Thus,  for example, suppose an entity has
            header fields such as:

                 Content-Type: text/plain; charset=ISO-8859-1
                 Content-transfer-encoding: base64

            This should be interpreted to mean that the body is a base64
            ASCII  encoding  of  data that was originally in ISO-8859-1,
            and will be in that character set again after decoding.

            The following sections will define the two standard encoding
            mechanisms.    The   definition   of  new  content-transfer-
            encodings is explicitly discouraged and  should  only  occur
            when  absolutely  necessary.   All content-transfer-encoding
            namespace except that  beginning  with  "X-"  is  explicitly
            reserved  to  the  IANA  for future use.  Private agreements
            about   content-transfer-encodings   are   also   explicitly
            discouraged.

            Certain Content-Transfer-Encoding values may only be used on
            certain  Content-Types.   In  particular,  it  is  expressly
            forbidden to use any encodings other than "7bit", "8bit", or
            "binary"  with  any  Content-Type  that recursively includes
            other Content-Type  fields,   notably  the  "multipart"  and



            Borenstein & Freed                                 [Page 12]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


            "message" Content-Types.  All encodings that are desired for
            bodies of type multipart or message  must  be  done  at  the
            innermost  level,  by encoding the actual body that needs to
            be encoded.

            NOTE  ON  ENCODING  RESTRICTIONS:   Though  the  prohibition
            against  using  content-transfer-encodings  on  data of type
            multipart or message may  seem  overly  restrictive,  it  is
            necessary  to  prevent  nested  encodings, in which data are
            passed through an encoding  algorithm  multiple  times,  and
            must  be  decoded  multiple  times  in  order to be properly
            viewed.  Nested encodings  add  considerable  complexity  to
            user  agents:   aside  from  the obvious efficiency problems
            with such multiple encodings, they  can  obscure  the  basic
            structure  of a message.  In particular, they can imply that
            several decoding operations are necessary simply to find out
            what  types  of  objects a message contains.  Banning nested
            encodings may complicate the job of certain  mail  gateways,
            but  this  seems less of a problem than the effect of nested
            encodings on user agents.

            NOTE ON THE RELATIONSHIP BETWEEN CONTENT-TYPE  AND  CONTENT-
            TRANSFER-ENCODING:   It  may seem that the Content-Transfer-
            Encoding could be inferred from the characteristics  of  the
            Content-Type  that  is to be encoded, or, at the very least,
            that certain Content-Transfer-Encodings  could  be  mandated
            for  use  with  specific  Content-Types.  There  are several
            reasons why this is not the case. First, given  the  varying
            types  of  transports  used  for mail, some encodings may be
            appropriate for some Content-Type/transport combinations and
            not  for  others.  (For  example, in an  8-bit transport, no
            encoding would be required for  text  in  certain  character
            sets,  while  such  encodings are clearly required for 7-bit
            SMTP.)  Second, certain Content-Types may require  different
            types  of  transfer  encoding under different circumstances.
            For example, many PostScript bodies might  consist  entirely
            of  short lines of 7-bit data and hence require little or no
            encoding. Other PostScript bodies  (especially  those  using
            Level  2 PostScript's binary encoding mechanism) may only be
            reasonably represented using a  binary  transport  encoding.
            Finally,  since Content-Type is intended to be an open-ended
            specification  mechanism,   strict   specification   of   an
            association  between Content-Types and encodings effectively
            couples the specification of an application protocol with  a
            specific  lower-level transport. This is not desirable since
            the developers of a Content-Type should not have to be aware
            of all the transports in use and what their limitations are.

            NOTE ON TRANSLATING  ENCODINGS:   The  quoted-printable  and
            base64  encodings  are  designed  so that conversion between
            them is possible. The only  issue  that  arises  in  such  a
            conversion  is  the handling of line breaks. When converting
            from  quoted-printable  to  base64  a  line  break  must  be
            converted  into  a CRLF sequence. Similarly, a CRLF sequence



            Borenstein & Freed                                 [Page 13]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


            in base64 data should be  converted  to  a  quoted-printable
            line break, but ONLY when converting text data.

            NOTE  ON  CANONICAL  ENCODING  MODEL:     There   was   some
            confusion,  in  earlier  drafts  of this memo, regarding the
            model for when email data was to be converted  to  canonical
            form  and  encoded, and in particular how this process would
            affect the treatment of CRLFs, given that the representation
            of  newlines  varies greatly from system to system. For this
            reason, a canonical  model  for  encoding  is  presented  as
            Appendix H.

            5.1  Quoted-Printable Content-Transfer-Encoding

            The Quoted-Printable encoding is intended to represent  data
            that largely consists of octets that correspond to printable
            characters in the ASCII character set.  It encodes the  data
            in  such  a way that the resulting octets are unlikely to be
            modified by mail transport.  If the data being  encoded  are
            mostly  ASCII  text,  the  encoded  form of the data remains
            largely recognizable by humans.  A body  which  is  entirely
            ASCII  may also be encoded in Quoted-Printable to ensure the
            integrity of the data should  the  message  pass  through  a
            character-translating, and/or line-wrapping gateway.

            In this encoding, octets are to be represented as determined
            by the following rules:

                 Rule #1:  (General  8-bit  representation)  Any  octet,
                 except  those  indicating a line break according to the
                 newline convention of the canonical form  of  the  data
                 being encoded, may be represented by an "=" followed by
                 a two digit hexadecimal representation of  the  octet's
                 value. The digits of the hexadecimal alphabet, for this
                 purpose, are "0123456789ABCDEF". Uppercase letters must
                 be
                 used when sending hexadecimal  data,  though  a  robust
                 implementation   may   choose  to  recognize  lowercase
                 letters on receipt. Thus, for  example,  the  value  12
                 (ASCII  form feed) can be represented by "=0C", and the
                 value 61 (ASCII  EQUAL  SIGN)  can  be  represented  by
                 "=3D".   Except  when  the  following  rules  allow  an
                 alternative encoding, this rule is mandatory.

                 Rule #2: (Literal representation) Octets  with  decimal
                 values  of 33 through 60 inclusive, and 62 through 126,
                 inclusive, MAY be represented as the  ASCII  characters
                 which  correspond  to  those  octets (EXCLAMATION POINT
                 through LESS THAN,  and  GREATER  THAN  through  TILDE,
                 respectively).

                 Rule #3: (White Space): Octets with values of 9 and  32
                 MAY   be  represented  as  ASCII  TAB  (HT)  and  SPACE
                 characters,  respectively,   but   MUST   NOT   be   so



            Borenstein & Freed                                 [Page 14]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


                 represented at the end of an encoded line. Any TAB (HT)
                 or SPACE characters on an encoded  line  MUST  thus  be
                 followed  on  that  line  by a printable character.  In
                 particular, an "=" at  the  end  of  an  encoded  line,
                 indicating  a  soft line break (see rule #5) may follow
                 one or more TAB (HT) or SPACE characters.   It  follows
                 that  an  octet with value 9 or 32 appearing at the end
                 of an encoded line must  be  represented  according  to
                 Rule  #1.  This  rule  is  necessary  because some MTAs
                 (Message Transport  Agents,  programs  which  transport
                 messages from one user to another, or perform a part of
                 such transfers) are known to pad  lines  of  text  with
                 SPACEs,  and  others  are known to remove "white space"
                 characters from the end  of  a  line.  Therefore,  when
                 decoding  a  Quoted-Printable  body, any trailing white
                 space on a line must be deleted, as it will necessarily
                 have been added by intermediate transport agents.

                 Rule #4 (Line Breaks): A line  break  in  a  text  body
                 part,   independent   of  what  its  representation  is
                 following the  canonical  representation  of  the  data
                 being  encoded, must be represented by a (RFC 822) line
                 break,  which  is  a  CRLF  sequence,  in  the  Quoted-
                 Printable  encoding.  If isolated CRs and LFs, or LF CR
                 and CR LF sequences are allowed  to  appear  in  binary
                 data  according  to  the  canonical  form, they must be
                 represented   using  the  "=0D",  "=0A",  "=0A=0D"  and
                 "=0D=0A" notations respectively.

                 Note that many implementation may elect to  encode  the
                 local representation of various content types directly.
                 In particular, this may apply to plain text material on
                 systems  that  use  newline conventions other than CRLF
                 delimiters. Such an implementation is permissible,  but
                 the  generation  of  line breaks must be generalized to
                 account for the case where alternate representations of
                 newline sequences are used.

                 Rule  #5  (Soft  Line  Breaks):  The   Quoted-Printable
                 encoding REQUIRES that encoded lines be no more than 76
                 characters long. If longer lines are to be encoded with
                 the  Quoted-Printable encoding, 'soft' line breaks must
                 be used. An equal sign  as  the  last  character  on  a
                 encoded  line indicates such a non-significant ('soft')
                 line break in the encoded text. Thus if the "raw"  form
                 of the line is a single unencoded line that says:

                      Now's the time for all folk to come to the aid of
                      their country.

                 This  can  be  represented,  in  the   Quoted-Printable
                 encoding, as





            Borenstein & Freed                                 [Page 15]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


                      Now's the time =
                      for all folk to come=
                       to the aid of their country.

                 This provides a mechanism with  which  long  lines  are
                 encoded  in  such  a  way as to be restored by the user
                 agent.  The 76  character  limit  does  not  count  the
                 trailing   CRLF,   but  counts  all  other  characters,
                 including any equal signs.

            Since the hyphen character ("-") is represented as itself in
            the  Quoted-Printable  encoding,  care  must  be taken, when
            encapsulating a quoted-printable encoded body in a multipart
            entity,  to  ensure that the encapsulation boundary does not
            appear anywhere in the encoded body.  (A good strategy is to
            choose a boundary that includes a character sequence such as
            "=_" which can never appear in a quoted-printable body.  See
            the   definition   of   multipart  messages  later  in  this
            document.)

            NOTE:  The quoted-printable encoding represents something of
            a   compromise   between   readability  and  reliability  in
            transport.   Bodies  encoded   with   the   quoted-printable
            encoding will work reliably over most mail gateways, but may
            not work  perfectly  over  a  few  gateways,  notably  those
            involving  translation  into  EBCDIC.  (In theory, an EBCDIC
            gateway could decode a quoted-printable body  and  re-encode
            it  using  base64,  but  such gateways do not yet exist.)  A
            higher  level  of  confidence  is  offered  by  the   base64
            Content-Transfer-Encoding.  A way to get reasonably reliable
            transport through EBCDIC gateways is to also quote the ASCII
            characters

                 !"#$@[\]^`{|}~

            according to rule #1.  See Appendix B for more information.

            Because quoted-printable data is  generally  assumed  to  be
            line-oriented,  it is to be expected that the breaks between
            the lines  of  quoted  printable  data  may  be  altered  in
            transport,  in  the  same  manner  that  plain text mail has
            always been altered in Internet mail  when  passing  between
            systems   with   differing  newline  conventions.   If  such
            alterations are likely to constitute  a  corruption  of  the
            data,  it  is  probably  more  sensible  to  use  the base64
            encoding rather than the quoted-printable encoding.











            Borenstein & Freed                                 [Page 16]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


            5.2  Base64 Content-Transfer-Encoding

            The  Base64   Content-Transfer-Encoding   is   designed   to
            represent  arbitrary  sequences  of octets in a form that is
            not humanly readable.  The encoding and decoding  algorithms
            are simple, but the encoded data are consistently only about
            33 percent larger than the unencoded data.  This encoding is
            based on the one used in Privacy Enhanced Mail applications,
            as defined in RFC 1113.   The  base64  encoding  is  adapted
            from  RFC  1113, with one change:  base64 eliminates the "*"
            mechanism for embedded clear text.

            A 65-character subset of US-ASCII is used, enabling  6  bits
            to  be  represented per printable character. (The extra 65th
            character, "=", is used  to  signify  a  special  processing
            function.)

            NOTE:  This subset has the important  property  that  it  is
            represented   identically   in  all  versions  of  ISO  646,
            including US ASCII, and all characters  in  the  subset  are
            also  represented  identically  in  all  versions of EBCDIC.
            Other popular encodings, such as the encoding  used  by  the
            UUENCODE  utility  and the base85 encoding specified as part
            of Level 2 PostScript, do not share  these  properties,  and
            thus  do  not  fulfill the portability requirements a binary
            transport encoding for mail must meet.

            The encoding process represents 24-bit groups of input  bits
            as  output  strings of 4 encoded characters. Proceeding from
            left  to  right,  a  24-bit  input  group   is   formed   by
            concatenating  3  8-bit input groups. These 24 bits are then
            treated as 4 concatenated 6-bit groups,  each  of  which  is
            translated  into a single digit in the base64 alphabet. When
            encoding a bit stream  via  the  base64  encoding,  the  bit
            stream  must  be  presumed  to  be  ordered  with  the most-
            significant-bit first.  That is, the first bit in the stream
            will be the high-order bit in the first byte, and the eighth
            bit will be the low-order bit in the first byte, and so on.

            Each 6-bit group is used as an index into  an  array  of  64
            printable  characters. The character referenced by the index
            is placed in the output string. These characters, identified
            in  Table  1,  below,  are  selected so as to be universally
            representable,  and  the  set   excludes   characters   with
            particular  significance to SMTP (e.g., ".", "CR", "LF") and
            to the encapsulation boundaries  defined  in  this  document
            (e.g., "-").










            Borenstein & Freed                                 [Page 17]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


                            Table 1: The Base64 Alphabet

               Value Encoding  Value  Encoding   Value  Encoding   Value
            Encoding
                   0 A            17 R            34 i            51 z
                   1 B            18 S            35 j            52 0
                   2 C            19 T            36 k            53 1
                   3 D            20 U            37 l            54 2
                   4 E            21 V            38 m            55 3
                   5 F            22 W            39 n            56 4
                   6 G            23 X            40 o            57 5
                   7 H            24 Y            41 p            58 6
                   8 I            25 Z            42 q            59 7
                   9 J            26 a            43 r            60 8
                  10 K            27 b            44 s            61 9
                  11 L            28 c            45 t            62 +
                  12 M            29 d            46 u            63 /
                  13 N            30 e            47 v
                  14 O            31 f            48 w         (pad) =
                  15 P            32 g            49 x
                  16 Q            33 h            50 y

            The output stream (encoded bytes)  must  be  represented  in
            lines  of  no more than 76 characters each.  All line breaks
            or other characters not found in Table 1 must be ignored  by
            decoding  software.   In  base64 data, characters other than
            those in  Table  1,  line  breaks,  and  other  white  space
            probably  indicate  a  transmission  error,  about  which  a
            warning  message  or  even  a  message  rejection  might  be
            appropriate under some circumstances.

            Special processing is performed if fewer than  24  bits  are
            available  at  the  end  of  the data being encoded.  A full
            encoding quantum is always completed at the end of  a  body.
            When  fewer  than  24  input  bits are available in an input
            group, zero bits  are  added  (on  the  right)  to  form  an
            integral number of 6-bit groups.  Output character positions
            which are not required to represent actual  input  data  are
            set  to  the  character  "=".   Since all base64 input is an
            integral number of octets,  only  the  following  cases  can
            arise:  (1)  the  final  quantum  of  encoding  input  is an
            integral multiple of  24  bits;  here,  the  final  unit  of
            encoded  output will be an integral multiple of 4 characters
            with no "=" padding, (2) the final quantum of encoding input
            is  exactly  8  bits; here, the final unit of encoded output
            will  be  two  characters  followed  by  two   "="   padding
            characters,  or  (3)  the final quantum of encoding input is
            exactly 16 bits; here, the final unit of encoded output will
            be three characters followed by one "=" padding character.

            Care must be taken to use the proper octets for line  breaks
            if base64 encoding is applied directly to text material that
            has not been converted to  canonical  form.  In  particular,
            text  line  breaks  should  be converted into CRLF sequences



            Borenstein & Freed                                 [Page 18]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


            prior to base64 encoding. The important  thing  to  note  is
            that this may be done directly by the encoder rather than in
            a prior canonicalization step in some implementations.

            NOTE: There is no  need  to  worry  about  quoting  apparent
            encapsulation  boundaries  within  base64-encoded  parts  of
            multipart entities because no hyphen characters are used  in
            the base64 encoding.

            6    Additional Optional Content- Header Fields

            6.1  Optional Content-ID Header Field

            In constructing a high-level user agent, it may be desirable
            to   allow   one   body   to   make  reference  to  another.
            Accordingly, bodies may be labeled  using  the  "Content-ID"
            header  field,  which  is  syntactically  identical  to  the
            "Message-ID" header field:

            Content-ID := msg-id

            Like  the  Message-ID  values,  Content-ID  values  must  be
            generated to be as unique as possible.

            6.2  Optional Content-Description Header Field

            The ability to associate some descriptive information with a
            given body is often desirable. For example, it may be useful
            to mark an "image" body as "a picture of the  Space  Shuttle
            Endeavor."    Such  text  may  be  placed  in  the  Content-
            Description header field.

            Content-Description := *text

            The description is presumed to  be  given  in  the  US-ASCII
            character  set,  although  the  mechanism specified in [RFC-
            1342]  may  be  used  for  non-US-ASCII  Content-Description
            values.



















            Borenstein & Freed                                 [Page 19]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


            7    The Predefined Content-Type Values

            This document defines seven initial Content-Type values  and
            an  extension  mechanism  for private or experimental types.
            Further standard types must  be  defined  by  new  published
            specifications.   It is expected that most innovation in new
            types of mail will take place as subtypes of the seven types
            defined  here.   The  most  essential characteristics of the
            seven content-types are summarized in Appendix G.

            7.1  The Text Content-Type

            The text Content-Type is intended for sending material which
            is  principally textual in form.  It is the default Content-
            Type.  A "charset" parameter may be  used  to  indicate  the
            character set of the body text.  The primary subtype of text
            is "plain".  This indicates plain (unformatted)  text.   The
            default  Content-Type  for  Internet  mail  is  "text/plain;
            charset=us-ascii".

            Beyond plain text, there are many formats  for  representing
            what might be known as "extended text" -- text with embedded
            formatting and  presentation  information.   An  interesting
            characteristic of many such representations is that they are
            to some extent  readable  even  without  the  software  that
            interprets  them.   It is useful, then, to distinguish them,
            at the highest level, from such unreadable data  as  images,
            audio,  or  text  represented in an unreadable form.  In the
            absence  of  appropriate  interpretation  software,  it   is
            reasonable to show subtypes of text to the user, while it is
            not reasonable to do so with most nontextual data.

            Such formatted textual  data  should  be  represented  using
            subtypes  of text.  Plausible subtypes of text are typically
            given by the common name of the representation format, e.g.,
            "text/richtext".

            7.1.1     The charset parameter

            A critical parameter that may be specified in  the  Content-
            Type  field  for  text  data  is the character set.  This is
            specified with a "charset" parameter, as in:

                 Content-type: text/plain; charset=us-ascii

            Unlike some  other  parameter  values,  the  values  of  the
            charset  parameter  are  NOT  case  sensitive.   The default
            character set, which must be assumed in  the  absence  of  a
            charset parameter, is US-ASCII.

            An initial list of predefined character  set  names  can  be
            found at the end of this section.  Additional character sets
            may be registered with IANA  as  described  in  Appendix  F,
            although the standardization of their use requires the usual



            Borenstein & Freed                                 [Page 20]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


            IAB  review  and  approval.  Note  that  if  the   specified
            character  set  includes  8-bit  data,  a  Content-Transfer-
            Encoding header field and a corresponding  encoding  on  the
            data  are  required  in  order to transmit the body via some
            mail transfer protocols, such as SMTP.

            The default character set, US-ASCII, has been the subject of
            some  confusion  and  ambiguity  in the past.  Not only were
            there some ambiguities in the definition,  there  have  been
            wide  variations  in  practice.   In order to eliminate such
            ambiguity and variations  in  the  future,  it  is  strongly
            recommended  that  new  user  agents  explicitly  specify  a
            character set via the Content-Type header field.  "US-ASCII"
            does not indicate an arbitrary seven-bit character code, but
            specifies that the body uses character coding that uses  the
            exact  correspondence  of  codes  to characters specified in
            ASCII.  National use variations of ISO 646 [ISO-646] are NOT
            ASCII   and   their  use  in  Internet  mail  is  explicitly
            discouraged. The omission of the ISO 646  character  set  is
            deliberate  in  this regard.  The character set name of "US-
            ASCII" explicitly refers  to ANSI X3.4-1986 [US-ASCII] only.
            The  character  set name "ASCII" is reserved and must not be
            used for any purpose.

            NOTE: RFC 821 explicitly specifies "ASCII",  and  references
            an earlier version of the American Standard.  Insofar as one
            of the purposes of specifying a Content-Type  and  character
            set is to permit the receiver to unambiguously determine how
            the sender intended the coded  message  to  be  interpreted,
            assuming  anything  other than "strict ASCII" as the default
            would risk unintentional and  incompatible  changes  to  the
            semantics  of  messages  now being transmitted.    This also
            implies that messages containing characters coded  according
            to  national  variations on ISO 646, or using code-switching
            procedures (e.g., those of ISO 2022), as well  as  8-bit  or
            multiple   octet character encodings MUST use an appropriate
            character set  specification  to  be  consistent  with  this
            specification.

            The complete US-ASCII character set is listed in [US-ASCII].
            Note  that  the control characters including DEL (0-31, 127)
            have no defined meaning  apart  from  the  combination  CRLF
            (ASCII  values 13 and 10) indicating a new line.  Two of the
            characters have de facto meanings in wide use: FF (12) often
            means  "start  subsequent  text  on  the  beginning of a new
            page"; and TAB or HT (9) often  (though  not  always)  means
            "move  the  cursor  to  the  next available column after the
            current position where the column number is a multiple of  8
            (counting  the  first column as column 0)." Apart from this,
            any use of the control characters or DEL in a body  must  be
            part   of   a  private  agreement  between  the  sender  and
            recipient.  Such  private  agreements  are  discouraged  and
            should  be  replaced  by  the  other  capabilities  of  this
            document.



            Borenstein & Freed                                 [Page 21]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


            NOTE:   Beyond  US-ASCII,  an  enormous   proliferation   of
            character  sets  is  possible. It is the opinion of the IETF
            working group that a large number of character sets is NOT a
            good  thing.   We would prefer to specify a single character
            set that can be used universally for representing all of the
            world's   languages   in  electronic  mail.   Unfortunately,
            existing practice in several communities seems to  point  to
            the  continued  use  of  multiple character sets in the near
            future.  For this reason, we define names for a small number
            of  character  sets  for  which  a  strong  constituent base
            exists.    It is our hope  that  ISO  10646  or  some  other
            effort  will  eventually define a single world character set
            which can then be specified for use in Internet mail, but in
            the  advance of that definition we cannot specify the use of
            ISO  10646,  Unicode,  or  any  other  character  set  whose
            definition is, as of this writing, incomplete.

            The defined charset values are:

                 US-ASCII -- as defined in [US-ASCII].

                 ISO-8859-X -- where "X"  is  to  be  replaced,  as
                      necessary,  for  the  parts of ISO-8859 [ISO-
                      8859].  Note that the ISO 646 character  sets
                      have  deliberately  been  omitted in favor of
                      their  8859  replacements,  which   are   the
                      designated  character sets for Internet mail.
                      As of the publication of this  document,  the
                      legitimate  values  for  "X" are the digits 1
                      through 9.

            Note that the character set used,  if  anything  other  than
            US-ASCII,   must  always  be  explicitly  specified  in  the
            Content-Type field.

            No other character set name may be  used  in  Internet  mail
            without  the  publication  of a formal specification and its
            registration with IANA as described in  Appendix  F,  or  by
            private agreement, in which case the character set name must
            begin with "X-".

            Implementors are discouraged  from  defining  new  character
            sets for mail use unless absolutely necessary.

            The "charset" parameter has been defined primarily  for  the
            purpose  of  textual  data, and is described in this section
            for that reason.   However,  it  is  conceivable  that  non-
            textual  data might also wish to specify a charset value for
            some purpose, in which  case  the  same  syntax  and  values
            should be used.

            In general, mail-sending  software  should  always  use  the
            "lowest  common  denominator"  character  set possible.  For
            example, if a body contains  only  US-ASCII  characters,  it



            Borenstein & Freed                                 [Page 22]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


            should be marked as being in the US-ASCII character set, not
            ISO-8859-1, which, like all the ISO-8859 family of character
            sets,  is  a  superset  of  US-ASCII.   More generally, if a
            widely-used character set is a subset of  another  character
            set,  and a body contains only characters in the widely-used
            subset, it should be labeled as being in that  subset.  This
            will increase the chances that the recipient will be able to
            view the mail correctly.

            7.1.2     The Text/plain subtype

            The primary subtype of text   is  "plain".   This  indicates
            plain  (unformatted)  text.  The  default  Content-Type  for
            Internet  mail,  "text/plain;  charset=us-ascii",  describes
            existing  Internet practice, that is, it is the type of body
            defined by RFC 822.

            7.1.3     The Text/richtext subtype

            In order to promote the  wider  interoperability  of  simple
            formatted  text,  this  document defines an extremely simple
            subtype of "text", the "richtext" subtype.  This subtype was
            designed to meet the following criteria:

                 1.  The syntax must be extremely simple to  parse,
                 so  that  even  teletype-oriented mail systems can
                 easily strip away the formatting  information  and
                 leave only the readable text.

                 2.  The syntax must be extensible to allow for new
                 formatting commands that are deemed essential.

                 3.  The capabilities must be extremely limited, to
                 ensure  that  it  can  represent  no  more than is
                 likely to be representable by the  user's  primary
                 word  processor.   While  this  limits what can be
                 sent, it increases the  likelihood  that  what  is
                 sent can be properly displayed.

                 4.  The syntax must be compatible  with  SGML,  so
                 that,  with  an  appropriate  DTD  (Document  Type
                 Definition, the standard mechanism for defining  a
                 document  type  using SGML), a general SGML parser
                 could be made to parse richtext.  However, despite
                 this  compatibility,  the  syntax  should  be  far
                 simpler than full SGML, so that no SGML  knowledge
                 is required in order to implement it.

            The syntax of "richtext" is very simple.  It is assumed,  at
            the  top-level,  to be in the US-ASCII character set, unless
            of course a different charset parameter was specified in the
            Content-type  field.   All  characters represent themselves,
            with the exception of the "<" character (ASCII 60), which is
            used   to  mark  the  beginning  of  a  formatting  command.



            Borenstein & Freed                                 [Page 23]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


            Formatting  instructions  consist  of  formatting   commands
            surrounded  by angle brackets ("<>", ASCII 60 and 62).  Each
            formatting command may be no  more  than  40  characters  in
            length,  all in US-ASCII, restricted to the alphanumeric and
            hyphen ("-") characters. Formatting commands may be preceded
            by  a  forward slash or solidus ("/", ASCII 47), making them
            negations, and such negations must always exist  to  balance
            the  initial opening commands, except as noted below.  Thus,
            if the formatting command "<bold>" appears  at  some  point,
            there  must  later  be a "</bold>" to balance it.  There are
            only three exceptions to this "balancing" rule:  First,  the
            command "<lt>" is used to represent a literal "<" character.
            Second, the command "<nl>" is used to represent  a  required
            line  break.   (Otherwise,  CRLFs in the data are treated as
            equivalent to  a  single  SPACE  character.)   Finally,  the
            command  "<np>"  is  used to represent a page break.  (NOTE:
            The 40 character  limit  on  formatting  commands  does  not
            include  the  "<",  ">",  or  "/"  characters  that might be
            attached to such commands.)

            Initially defined formatting commands, not all of which will
            be implemented by all richtext implementations, include:

                 Bold -- causes the subsequent text  to  be  in  a  bold
                      font.
                 Italic -- causes the subsequent text to be in an italic
                      font.
                 Fixed -- causes the subsequent text to be  in  a  fixed
                      width font.
                 Smaller -- causes  the  subsequent  text  to  be  in  a
                      smaller font.
                 Bigger -- causes the subsequent text to be in a  bigger
                      font.
                 Underline  --  causes  the  subsequent   text   to   be
                      underlined.
                 Center -- causes the subsequent text to be centered.
                 FlushLeft -- causes the  subsequent  text  to  be  left
                      justified.
                 FlushRight -- causes the subsequent text  to  be  right
                      justified.
                 Indent -- causes the subsequent text to be indented  at
                      the left margin.
                 IndentRight  --  causes  the  subsequent  text  to   be
                      indented at the right margin.
                 Outdent -- causes the subsequent text to  be  outdented
                      at the left margin.
                 OutdentRight  --  causes  the  subsequent  text  to  be
                      outdented at the right margin.
                 SamePage -- causes the subsequent text to  be  grouped,
                      if possible, on one page.
                 Subscript  --  causes  the  subsequent   text   to   be
                      interpreted as a subscript.





            Borenstein & Freed                                 [Page 24]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


                 Superscript  --  causes  the  subsequent  text  to   be
                      interpreted as a superscript.
                 Heading -- causes the subsequent text to be interpreted
                      as a page heading.
                 Footing -- causes the subsequent text to be interpreted
                      as a page footing.
                 ISO-8859-X  (for any value of X  that  is  legal  as  a
                      "charset" parameter) -- causes the subsequent text
                      to be  interpreted  as  text  in  the  appropriate
                      character set.
                 US-ASCII  --  causes  the   subsequent   text   to   be
                      interpreted as text in the US-ASCII character set.
                 Excerpt -- causes the subsequent text to be interpreted
                      as   a   textual   excerpt  from  another  source.
                      Typically this will be displayed using indentation
                      and  an  alternate font, but such decisions are up
                      to the viewer.
                 Paragraph  --  causes  the  subsequent   text   to   be
                      interpreted    as   a   single   paragraph,   with
                      appropriate  paragraph  breaks  (typically   blank
                      space) before and after.
                 Signature  --  causes  the  subsequent   text   to   be
                      interpreted  as  a  "signature".  Some systems may
                      wish to display signatures in a  smaller  font  or
                      otherwise set them apart from the main text of the
                      message.
                 Comment -- causes the subsequent text to be interpreted
                      as a comment, and hence not shown to the reader.
                 No-op -- has no effect on the subsequent text.
                 lt -- <lt> is replaced by a literal "<" character.   No
                      balancing </lt> is allowed.
                 nl -- <nl> causes a line break.  No balancing </nl>  is
                      allowed.
                 np -- <np> causes a page break.  No balancing </np>  is
                      allowed.

            Each positive formatting command affects all subsequent text
            until  the matching negative formatting command.  Such pairs
            of formatting commands must be properly balanced and nested.
            Thus, a proper way to describe text in bold italics is:

                      <bold><italic>the-text</italic></bold>

                 or, alternately,

                      <italic><bold>the-text</bold></italic>

                 but,  in  particular,  the  following  is  illegal
                 richtext:

                      <bold><italic>the-text</bold></italic>

            NOTE:   The  nesting  requirement  for  formatting  commands
            imposes  a  slightly  higher  burden  upon  the composers of



            Borenstein & Freed                                 [Page 25]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


            richtext  bodies,  but   potentially   simplifies   richtext
            displayers  by  allowing  them  to be stack-based.  The main
            goal of richtext is to be simple enough to  make  multifont,
            formatted  email  widely  readable,  so  that those with the
            capability of  sending  it  will  be  able  to  do  so  with
            confidence.   Thus  slightly  increased  complexity  in  the
            composing software was  deemed  a  reasonable  tradeoff  for
            simplified  reading  software.  Nonetheless, implementors of
            richtext  readers  are  encouraged  to  follow  the  general
            Internet  guidelines  of being conservative in what you send
            and liberal in what you accept.  Those implementations  that
            can  do so are encouraged to deal reasonably with improperly
            nested richtext.

            Implementations  must  regard  any  unrecognized  formatting
            command  as  equivalent to "No-op", thus facilitating future
            extensions to "richtext".  Private extensions may be defined
            using  formatting  commands that begin with "X-", by analogy
            to Internet mail header field names.

            It is worth noting that no special behavior is required  for
            the TAB (HT) character. It is recommended, however, that, at
            least  when  fixed-width  fonts  are  in  use,  the   common
            semantics  of  the  TAB  (HT)  character should be observed,
            namely that it moves to the next column position that  is  a
            multiple  of  8.   (In  other words, if a TAB (HT) occurs in
            column n, where the leftmost column is column 0,  then  that
            TAB   (HT)   should   be  replaced  by  8-(n  mod  8)  SPACE
            characters.)

            Richtext also differentiates between "hard" and "soft"  line
            breaks.   A line break (CRLF) in the richtext data stream is
            interpreted as a "soft" line break,  one  that  is  included
            only for purposes of mail transport, and is to be treated as
            white space by richtext interpreters.  To include  a  "hard"
            line  break (one that must be displayed as such), the "<nl>"
            or "<paragraph> formatting constructs  should  be  used.  In
            general, a soft line break should be treated as white space,
            but when soft line breaks immediately follow  a  <nl>  or  a
            </paragraph>  tag they should be ignored rather than treated
            as white space.

            Putting all this  together,  the  following  "text/richtext"
            body fragment:

                      <bold>Now</bold> is the time for
                      <italic>all</italic> good men
                       <smaller>(and <lt>women>)</smaller> to
                      <ignoreme></ignoreme> come

                      to the aid of their
                      <nl>





            Borenstein & Freed                                 [Page 26]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


                      beloved <nl><nl>country. <comment> Stupid
                      quote! </comment> -- the end

            represents the following  formatted  text  (which  will,  no
            doubt,  look  cryptic  in  the  text-only  version  of  this
            document):

                 Now is the time for all good men (and <women>)  to
                 come to the aid of their
                 beloved

                 country. -- the end

            Richtext conformance:  A minimal richtext implementation  is
            one  that  simply  converts "<lt>" to "<", converts CRLFs to
            SPACE, converts <nl> to a newline according to local newline
            convention,  removes  everything between a <comment> command
            and the next balancing </comment> command, and  removes  all
            other  formatting  commands  (all  text  enclosed  in  angle
            brackets).

            NOTE ON THE RELATIONSHIP OF RICHTEXT TO SGML:   Richtext  is
            decidedly  not  SGML,  and  must  not  be  used to transport
            arbitrary SGML  documents.   Those  who  wish  to  use  SGML
            document  types as a mail transport format must define a new
            text or application subtype, e.g.,  "text/sgml-dtd-whatever"
            or   "application/sgml-dtd-whatever",   depending   on   the
            perceived readability  of  the  DTD  in  use.   Richtext  is
            designed  to  be  compatible  with SGML, and specifically so
            that it will be possible to define a richtext DTD if one  is
            needed.   However,  this  does not imply that arbitrary SGML
            can be called richtext, nor that richtext implementors  have
            any  need  to  understand  SGML;  the  description  in  this
            document is a complete definition of richtext, which is  far
            simpler than complete SGML.

            NOTE ON THE INTENDED USE OF RICHTEXT:  It is recognized that
            implementors  of  future  mail  systems  will want rich text
            functionality  far  beyond  that   currently   defined   for
            richtext.   The  intent  of  richtext is to provide a common
            format for expressing that functionality in a form in  which
            much  of  it, at least, will be understood by interoperating
            software.  Thus,  in  particular,  software  with  a  richer
            notion  of  formatted  text  than  richtext  can  still  use
            richtext as its basic representation, but can extend it with
            new  formatting  commands and by hiding information specific
            to that software  system  in  richtext  comments.   As  such
            systems  evolve,  it  is  expected  that  the  definition of
            richtext  will  be  further  refined  by  future   published
            specifications,  but  richtext  as  defined  here provides a
            platform on which evolutionary refinements can be based.

            IMPLEMENTATION NOTE:  In  some  environments,  it  might  be
            impossible  to combine certain richtext formatting commands,



            Borenstein & Freed                                 [Page 27]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


            whereas in  others  they  might  be  combined  easily.   For
            example,  the  combination  of  <bold>  and  <italic>  might
            produce bold italics on systems that support such fonts, but
            there  exist  systems that can make text bold or italicized,
            but not both.  In  such  cases,  the  most  recently  issued
            recognized formatting command should be preferred.

            One of the major goals in the design of richtext was to make
            it  so  simple  that  even  text-only mailers will implement
            richtext-to-plain-text  translators,  thus  increasing   the
            likelihood  that  multifont  text  will become "safe" to use
            very widely.  To demonstrate this simplicity,  an  extremely
            simple  35-line  C program that converts richtext input into
            plain text output is included in Appendix D.











































            Borenstein & Freed                                 [Page 28]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


            7.2  The Multipart Content-Type

            In the case of multiple part messages, in which one or  more
            different  sets  of  data  are  combined in a single body, a
            "multipart" Content-Type field must appear in  the  entity's
            header. The body must then contain one or more "body parts,"
            each preceded by an encapsulation boundary, and the last one
            followed  by  a  closing boundary.  Each part starts with an
            encapsulation  boundary,  and  then  contains  a  body  part
            consisting  of   header area, a blank line, and a body area.
            Thus a body part is similar to an RFC 822 message in syntax,
            but different in meaning.

            A body part is NOT to be interpreted as  actually  being  an
            RFC  822  message.   To  begin  with,  NO  header fields are
            actually required in body parts.  A body  part  that  starts
            with  a blank line, therefore, is allowed and is a body part
            for which all default values are to be assumed.  In  such  a
            case,  the  absence  of  a Content-Type header field implies
            that the encapsulation is plain  US-ASCII  text.   The  only
            header  fields  that have defined meaning for body parts are
            those the names of which begin with "Content-".   All  other
            header  fields  are  generally  to be ignored in body parts.
            Although  they  should  generally  be   retained   in   mail
            processing,  they may be discarded by gateways if necessary.
            Such other fields are permitted to appear in body parts  but
            should  not  be  depended on. "X-" fields may be created for
            experimental or private purposes, with the recognition  that
            the information they contain may be lost at some gateways.

            The distinction between an RFC 822 message and a  body  part
            is  subtle,  but  important.  A gateway between Internet and
            X.400 mail, for example, must be able to tell the difference
            between  a  body part that contains an image and a body part
            that contains an encapsulated message, the body of which  is
            an  image.   In order to represent the latter, the body part
            must have "Content-Type: message", and its body  (after  the
            blank  line)  must be the encapsulated message, with its own
            "Content-Type: image" header  field.   The  use  of  similar
            syntax facilitates the conversion of messages to body parts,
            and vice versa, but the distinction between the two must  be
            understood  by implementors.  (For the special case in which
            all parts actually are messages, a "digest" subtype is  also
            defined.)

            As stated previously, each  body  part  is  preceded  by  an
            encapsulation boundary.  The encapsulation boundary MUST NOT
            appear inside any of the encapsulated parts.   Thus,  it  is
            crucial  that  the  composing  agent  be  able to choose and
            specify the unique boundary that will separate the parts.

            All present and future subtypes of the "multipart" type must
            use  an  identical  syntax.  Subtypes  may  differ  in their
            semantics, and may impose additional restrictions on syntax,



            Borenstein & Freed                                 [Page 29]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


            but  must  conform  to the required syntax for the multipart
            type.  This requirement ensures  that  all  conformant  user
            agents  will  at least be able to recognize and separate the
            parts of any  multipart  entity,  even  of  an  unrecognized
            subtype.

            As stated in the definition of the Content-Transfer-Encoding
            field, no encoding other than "7bit", "8bit", or "binary" is
            permitted for entities of type "multipart".   The  multipart
            delimiters  and  header fields are always 7-bit ASCII in any
            case, and data within the body parts can  be  encoded  on  a
            part-by-part  basis,  with  Content-Transfer-Encoding fields
            for each appropriate body part.

            Mail gateways, relays, and other mail  handling  agents  are
            commonly  known  to alter the top-level header of an RFC 822
            message.   In particular, they frequently  add,  remove,  or
            reorder  header  fields.   Such  alterations  are explicitly
            forbidden for the body part headers embedded in  the  bodies
            of messages of type "multipart."

            7.2.1     Multipart:  The common syntax

            All subtypes of "multipart" share a common  syntax,  defined
            in  this  section.   A simple example of a multipart message
            also appears in this section.  An example of a more  complex
            multipart message is given in Appendix C.

            The Content-Type field for multipart  entities requires  one
            parameter,   "boundary",   which  is  used  to  specify  the
            encapsulation  boundary.   The  encapsulation  boundary   is
            defined   as  a  line  consisting  entirely  of  two  hyphen
            characters ("-", decimal code 45) followed by  the  boundary
            parameter value from the Content-Type header field.

            NOTE:  The hyphens are  for  rough  compatibility  with  the
            earlier  RFC  934  method  of message encapsulation, and for
            ease   of   searching   for   the   boundaries    in    some
            implementations.  However, it should be noted that multipart
            messages  are  NOT  completely  compatible  with   RFC   934
            encapsulations;  in  particular,  they  do  not obey RFC 934
            quoting conventions  for  embedded  lines  that  begin  with
            hyphens.   This  mechanism  was  chosen  over  the  RFC  934
            mechanism because the latter causes lines to grow with  each
            level  of  quoting.  The combination of this growth with the
            fact that SMTP implementations  sometimes  wrap  long  lines
            made  the  RFC 934 mechanism unsuitable for use in the event
            that deeply-nested multipart structuring is ever desired.

            Thus, a typical multipart Content-Type  header  field  might
            look like this:

                 Content-Type: multipart/mixed;




            Borenstein & Freed                                 [Page 30]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


                      boundary=gc0p4Jq0M2Yt08jU534c0p

            This indicates that the entity consists  of  several  parts,
            each itself with a structure that is syntactically identical
            to an RFC 822 message, except that the header area might  be
            completely  empty,  and  that the parts are each preceded by
            the line

                 --gc0p4Jq0M2Yt08jU534c0p

            Note that the  encapsulation  boundary  must  occur  at  the
            beginning  of  a line, i.e., following a CRLF, and that that
            initial CRLF is considered to be part of  the  encapsulation
            boundary  rather  than  part  of  the preceding part.    The
            boundary must be followed immediately either by another CRLF
            and the header fields for the next part, or by two CRLFs, in
            which case there are no header fields for the next part (and
            it is therefore assumed to be of Content-Type text/plain).

            NOTE:   The  CRLF  preceding  the  encapsulation   line   is
            considered  part  of  the boundary so that it is possible to
            have a part that does not end with  a  CRLF  (line   break).
            Body  parts that must be considered to end with line breaks,
            therefore, should have two CRLFs preceding the encapsulation
            line, the first of which is part of the preceding body part,
            and the  second  of  which  is  part  of  the  encapsulation
            boundary.

            The requirement that the encapsulation boundary begins  with
            a  CRLF  implies  that  the  body of a multipart entity must
            itself begin with a CRLF before the first encapsulation line
            --  that  is, if the "preamble" area is not used, the entity
            headers must be followed by TWO CRLFs.  This is  indeed  how
            such  entities  should be composed.  A tolerant mail reading
            program, however, may interpret a  body  of  type  multipart
            that  begins  with  an encapsulation line NOT initiated by a
            CRLF  as  also  being  an  encapsulation  boundary,  but   a
            compliant  mail  sending  program  must  not  generate  such
            entities.

            Encapsulation  boundaries  must  not   appear   within   the
            encapsulations,  and  must  be no longer than 70 characters,
            not counting the two leading hyphens.

            The encapsulation boundary following the last body part is a
            distinguished  delimiter that indicates that no further body
            parts will follow.  Such a delimiter  is  identical  to  the
            previous  delimiters,  with the addition of two more hyphens
            at the end of the line:

                 --gc0p4Jq0M2Yt08jU534c0p--

            There appears to be room for additional information prior to
            the  first  encapsulation  boundary  and following the final



            Borenstein & Freed                                 [Page 31]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


            boundary.  These areas should generally be left  blank,  and
            implementations  should  ignore anything that appears before
            the first boundary or after the last one.

            NOTE:  These "preamble" and "epilogue" areas  are  not  used
            because  of the lack of proper typing of these parts and the
            lack  of  clear  semantics  for  handling  these  areas   at
            gateways, particularly X.400 gateways.

            NOTE:  Because encapsulation boundaries must not  appear  in
            the  body  parts  being  encapsulated,  a  user  agent  must
            exercise care to choose a unique boundary.  The boundary  in
            the example above could have been the result of an algorithm
            designed to produce boundaries with a very  low  probability
            of  already  existing in the data to be encapsulated without
            having to prescan  the  data.   Alternate  algorithms  might
            result in more 'readable' boundaries for a recipient with an
            old user agent, but would  require  more  attention  to  the
            possibility   that   the   boundary   might  appear  in  the
            encapsulated  part.   The  simplest  boundary  possible   is
            something like "---", with a closing boundary of "-----".

            As a very simple example, the  following  multipart  message
            has  two  parts,  both  of  them  plain  text,  one  of them
            explicitly typed and one of them implicitly typed:

                 From: Nathaniel Borenstein <nsb@bellcore.com>
                 To:  Ned Freed <ned@innosoft.com>
                 Subject: Sample message
                 MIME-Version: 1.0
                 Content-type: multipart/mixed; boundary="simple
                 boundary"

                 This is the preamble.  It is to be ignored, though it
                 is a handy place for mail composers to include an
                 explanatory note to non-MIME compliant readers.
                 --simple boundary

                 This is implicitly typed plain ASCII text.
                 It does NOT end with a linebreak.
                 --simple boundary
                 Content-type: text/plain; charset=us-ascii

                 This is explicitly typed plain ASCII text.
                 It DOES end with a linebreak.

                 --simple boundary--
                 This is the epilogue.  It is also to be ignored.

            The use of a Content-Type of multipart in a body part within
            another  multipart  entity  is explicitly allowed.   In such
            cases, for obvious reasons, care must  be  taken  to  ensure
            that  each  nested  multipart  entity  must  use a different
            boundary delimiter. See Appendix C for an example of  nested



            Borenstein & Freed                                 [Page 32]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


            multipart entities.

            The use of the multipart Content-Type  with  only  a  single
            body  part  may  be  useful  in  certain  contexts,  and  is
            explicitly permitted.

            The only mandatory parameter for the multipart  Content-Type
            is  the  boundary  parameter,  which  consists  of  1  to 70
            characters from a set of characters known to be very  robust
            through  email  gateways,  and  NOT ending with white space.
            (If a boundary appears to end with white  space,  the  white
            space  must be presumed to have been added by a gateway, and
            should  be  deleted.)   It  is  formally  specified  by  the
            following BNF:

            boundary := 0*69<bchars> bcharsnospace

            bchars := bcharsnospace / " "

            bcharsnospace :=    DIGIT / ALPHA / "'" / "(" / ")" / "+"  /
            "_"
                           / "," / "-" / "." / "/" / ":" / "=" / "?"

            Overall, the body of a multipart entity may be specified  as
            follows:

            multipart-body := preamble 1*encapsulation
                           close-delimiter epilogue

            encapsulation := delimiter CRLF body-part

            delimiter := CRLF "--" boundary   ; taken from  Content-Type
            field.
                                           ;   when   content-type    is
            multipart
                                         ; There must be no space
                                         ; between "--" and boundary.

            close-delimiter := delimiter "--" ; Again, no  space  before
            "--"

            preamble :=  *text                  ;  to  be  ignored  upon
            receipt.

            epilogue :=  *text                  ;  to  be  ignored  upon
            receipt.

            body-part = <"message" as defined in RFC 822,
                     with all header fields optional, and with the
                     specified delimiter not occurring anywhere in
                     the message body, either on a line by itself
                     or as a substring anywhere.  Note that the





            Borenstein & Freed                                 [Page 33]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


                     semantics of a part differ from the semantics
                     of a message, as described in the text.>

            NOTE:  Conspicuously missing from the multipart  type  is  a
            notion  of  structured,  related body parts.  In general, it
            seems premature to try to  standardize  interpart  structure
            yet.  It is recommended that those wishing to provide a more
            structured or integrated multipart messaging facility should
            define   a   subtype  of  multipart  that  is  syntactically
            identical, but  that  always  expects  the  inclusion  of  a
            distinguished part that can be used to specify the structure
            and integration of the other parts,  probably  referring  to
            them  by  their Content-ID field.  If this approach is used,
            other implementations will not recognize  the  new  subtype,
            but  will  treat it as the primary subtype (multipart/mixed)
            and will thus be able to show the user the  parts  that  are
            recognized.

            7.2.2     The Multipart/mixed (primary) subtype

            The primary subtype for multipart, "mixed", is intended  for
            use  when  the body parts are independent and intended to be
            displayed  serially.   Any  multipart   subtypes   that   an
            implementation does not recognize should be treated as being
            of subtype "mixed".

            7.2.3     The Multipart/alternative subtype

            The multipart/alternative type is syntactically identical to
            multipart/mixed,   but  the  semantics  are  different.   In
            particular, each of the parts is an "alternative" version of
            the same information.  User agents should recognize that the
            content of the various parts are interchangeable.  The  user
            agent  should  either  choose  the  "best" type based on the
            user's environment and preferences, or offer  the  user  the
            available  alternatives.  In general, choosing the best type
            means displaying only the LAST part that can  be  displayed.
            This  may be used, for example, to send mail in a fancy text
            format in such  a  way  that  it  can  easily  be  displayed
            anywhere:

            From:  Nathaniel Borenstein <nsb@bellcore.com>
            To: Ned Freed <ned@innosoft.com>
            Subject: Formatted text mail
            MIME-Version: 1.0
            Content-Type: multipart/alternative; boundary=boundary42


            --boundary42
            Content-Type: text/plain; charset=us-ascii

            ...plain text version of message goes here....





            Borenstein & Freed                                 [Page 34]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


            --boundary42
            Content-Type: text/richtext

            .... richtext version of same message goes here ...
            --boundary42
            Content-Type: text/x-whatever

            .... fanciest formatted version of same  message  goes  here
            ...
            --boundary42--

            In this example, users  whose  mail  system  understood  the
            "text/x-whatever"  format  would see only the fancy version,
            while other users would see only the richtext or plain  text
            version, depending on the capabilities of their system.

            In general, user agents that  compose  multipart/alternative
            entities  should place the body parts in increasing order of
            preference, that is, with the  preferred  format  last.  For
            fancy  text,  the sending user agent should put the plainest
            format first and the richest format  last.   Receiving  user
            agents  should  pick  and  display  the last format they are
            capable of  displaying.   In  the  case  where  one  of  the
            alternatives  is  itself  of  type  "multipart" and contains
            unrecognized sub-parts, the user agent may choose either  to
            show that alternative, an earlier alternative, or both.

            NOTE:  From an implementor's perspective, it might seem more
            sensible  to  reverse  this  ordering, and have the plainest
            alternative last.  However, placing the plainest alternative
            first    is    the    friendliest   possible   option   when
            mutlipart/alternative entities are viewed using a  non-MIME-
            compliant mail reader.  While this approach does impose some
            burden on  compliant  mail  readers,  interoperability  with
            older  mail  readers was deemed to be more important in this
            case.

            It may be the case  that  some  user  agents,  if  they  can
            recognize more than one of the formats, will prefer to offer
            the user the choice of which format  to  view.   This  makes
            sense, for example, if mail includes both a nicely-formatted
            image version and an easily-edited text  version.   What  is
            most  critical,  however, is that the user not automatically
            be shown multiple versions of the  same  data.   Either  the
            user  should  be shown the last recognized version or should
            explicitly be given the choice.











            Borenstein & Freed                                 [Page 35]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


            7.2.4     The Multipart/digest subtype

            This document defines a "digest" subtype  of  the  multipart
            Content-Type.   This  type  is  syntactically  identical  to
            multipart/mixed,  but  the  semantics  are  different.    In
            particular,  in a digest, the default Content-Type value for
            a   body   part   is   changed    from    "text/plain"    to
            "message/rfc822".   This  is  done  to allow a more readable
            digest format that is largely  compatible  (except  for  the
            quoting convention) with RFC 934.

            A digest in this format might,  then,  look  something  like
            this:

            From: Moderator-Address
            MIME-Version: 1.0
            Subject:  Internet Digest, volume 42
            Content-Type: multipart/digest;
                 boundary="---- next message ----"


            ------ next message ----

            From: someone-else
            Subject: my opinion

            ...body goes here ...

            ------ next message ----

            From: someone-else-again
            Subject: my different opinion

            ... another body goes here...

            ------ next message ------

            7.2.5     The Multipart/parallel subtype

            This document defines a "parallel" subtype of the  multipart
            Content-Type.   This  type  is  syntactically  identical  to
            multipart/mixed,  but  the  semantics  are  different.    In
            particular,  in  a  parallel  entity,  all  of the parts are
            intended to be presented in parallel, i.e.,  simultaneously,
            on  hardware  and  software  that  are  capable of doing so.
            Composing agents should be aware that many mail readers will
            lack this capability and will show the parts serially in any
            event.









            Borenstein & Freed                                 [Page 36]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


            7.3  The Message Content-Type

            It is frequently desirable, in sending mail, to  encapsulate
            another  mail  message. For this common operation, a special
            Content-Type, "message", is defined.  The  primary  subtype,
            message/rfc822,  has  no required parameters in the Content-
            Type field.  Additional subtypes, "partial"  and  "External-
            body",  do  have  required  parameters.   These subtypes are
            explained below.

            NOTE:  It has been suggested that subtypes of message  might
            be  defined  for  forwarded  or rejected messages.  However,
            forwarded and rejected messages can be handled as  multipart
            messages  in  which  the  first part contains any control or
            descriptive  information,  and  a  second  part,   of   type
            message/rfc822,   is  the  forwarded  or  rejected  message.
            Composing rejection and forwarding messages in  this  manner
            will  preserve  the type information on the original message
            and allow it to be correctly presented to the recipient, and
            hence is strongly encouraged.

            As stated in the definition of the Content-Transfer-Encoding
            field, no encoding other than "7bit", "8bit", or "binary" is
            permitted for messages  or  parts  of  type  "message".  The
            message  header  fields are always US-ASCII in any case, and
            data within the body can still be encoded, in which case the
            Content-Transfer-Encoding  header  field in the encapsulated
            message will reflect this.  Non-ASCII text in the headers of
            an   encapsulated   message   can  be  specified  using  the
            mechanisms described in [RFC-1342].

            Mail gateways, relays, and other mail  handling  agents  are
            commonly  known  to alter the top-level header of an RFC 822
            message.   In particular, they frequently  add,  remove,  or
            reorder  header  fields.   Such  alterations  are explicitly
            forbidden for  the  encapsulated  headers  embedded  in  the
            bodies of messages of type "message."

            7.3.1     The Message/rfc822 (primary) subtype

            A Content-Type of "message/rfc822" indicates that  the  body
            contains  an encapsulated message, with the syntax of an RFC
            822 message.

            7.3.2     The Message/Partial subtype

            A subtype of message, "partial",  is  defined  in  order  to
            allow  large  objects  to  be  delivered as several separate
            pieces  of  mail  and  automatically  reassembled   by   the
            receiving  user  agent.   (The  concept  is  similar  to  IP
            fragmentation/reassembly in the basic  Internet  Protocols.)
            This  mechanism  can  be  used  when  intermediate transport
            agents limit the size of individual  messages  that  can  be
            sent.   Content-Type  "message/partial"  thus indicates that



            Borenstein & Freed                                 [Page 37]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


            the body contains a fragment of a larger message.

            Three parameters must be specified in the Content-Type field
            of  type  message/partial:  The  first,  "id",  is  a unique
            identifier,  as  close  to  a  world-unique  identifier   as
            possible,  to  be  used  to  match  the parts together.  (In
            general, the identifier  is  essentially  a  message-id;  if
            placed  in  double  quotes,  it  can  be  any message-id, in
            accordance with the BNF for  "parameter"  given  earlier  in
            this  specification.)   The second, "number", an integer, is
            the part number, which indicates where this part  fits  into
            the  sequence  of  fragments.   The  third, "total", another
            integer, is the total number of parts. This  third  subfield
            is  required  on  the  final  part,  and  is optional on the
            earlier parts. Note also that these parameters may be  given
            in any order.

            Thus, part 2 of a 3-part message  may  have  either  of  the
            following header fields:

                 Content-Type: Message/Partial;
                      number=2; total=3;
                      id="oc=jpbe0M2Yt4s@thumper.bellcore.com";

                 Content-Type: Message/Partial;
                      id="oc=jpbe0M2Yt4s@thumper.bellcore.com";
                      number=2

            But part 3 MUST specify the total number of parts:

                 Content-Type: Message/Partial;
                      number=3; total=3;
                      id="oc=jpbe0M2Yt4s@thumper.bellcore.com";

            Note that part numbering begins with 1, not 0.

            When the parts of a message broken up in this manner are put
            together,  the  result is a complete RFC 822 format message,
            which may have its own Content-Type header field,  and  thus
            may contain any other data type.

            Message fragmentation and reassembly:  The  semantics  of  a
            reassembled  partial  message  must  be those of the "inner"
            message, rather than  of  a  message  containing  the  inner
            message.   This  makes  it  possible, for example, to send a
            large audio message as several partial messages,  and  still
            have  it  appear  to the recipient as a simple audio message
            rather than as an encapsulated message containing  an  audio
            message.   That  is,  the  encapsulation  of  the message is
            considered to be "transparent".

            When  generating   and   reassembling   the   parts   of   a
            message/partial  message,  the  headers  of the encapsulated
            message must be merged with the  headers  of  the  enclosing



            Borenstein & Freed                                 [Page 38]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


            entities.  In  this  process  the  following  rules  must be
            observed:

                 (1) All of the headers from the initial  enclosing
                 entity  (part  one),  except those that start with
                 "Content-" and "Message-ID", must  be  copied,  in
                 order, to the new message.

                 (2) Only those headers  in  the  enclosed  message
                 which  start with "Content-" and "Message-ID" must
                 be appended, in order, to the headers of  the  new
                 message.   Any  headers  in  the  enclosed message
                 which do not start  with  "Content-"  (except  for
                 "Message-ID") will be ignored.

                 (3) All of the headers from  the  second  and  any
                 subsequent messages will be ignored.

            For example, if an audio message is broken into  two  parts,
            the first part might look something like this:

                 X-Weird-Header-1: Foo
                 From: Bill@host.com
                 To: joe@otherhost.com
                 Subject: Audio mail
                 Message-ID: id1@host.com
                 MIME-Version: 1.0
                 Content-type: message/partial;
                      id="ABC@host.com";
                      number=1; total=2

                 X-Weird-Header-1: Bar
                 X-Weird-Header-2: Hello
                 Message-ID: anotherid@foo.com
                 Content-type: audio/basic
                 Content-transfer-encoding: base64

                 ... first half of encoded audio data goes here...

            and the second half might look something like this:

                 From: Bill@host.com
                 To: joe@otherhost.com
                 Subject: Audio mail
                 MIME-Version: 1.0
                 Message-ID: id2@host.com
                 Content-type: message/partial;
                      id="ABC@host.com"; number=2; total=2

                 ... second half of encoded audio data goes here...

            Then,  when  the  fragmented  message  is  reassembled,  the
            resulting  message  to  be displayed to the user should look
            something like this:



            Borenstein & Freed                                 [Page 39]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


                 X-Weird-Header-1: Foo
                 From: Bill@host.com
                 To: joe@otherhost.com
                 Subject: Audio mail
                 Message-ID: anotherid@foo.com
                 MIME-Version: 1.0
                 Content-type: audio/basic
                 Content-transfer-encoding: base64

                 ... first half of encoded audio data goes here...
                 ... second half of encoded audio data goes here...

            It should be  noted  that,  because  some  message  transfer
            agents  may choose to automatically fragment large messages,
            and because such  agents  may  use  different  fragmentation
            thresholds,  it  is  possible  that  the pieces of a partial
            message, upon reassembly, may prove themselves to comprise a
            partial message.  This is explicitly permitted.

            It should also be noted that the inclusion of a "References"
            field  in the headers of the second and subsequent pieces of
            a fragmented message that references the Message-Id  on  the
            previous  piece  may  be  of  benefit  to  mail readers that
            understand and track references. However, the generation  of
            such "References" fields is entirely optional.

            7.3.3     The Message/External-Body subtype

            The external-body subtype indicates  that  the  actual  body
            data are not included, but merely referenced.  In this case,
            the  parameters  describe  a  mechanism  for  accessing  the
            external data.

            When  a   message   body   or   body   part   is   of   type
            "message/external-body",   it  consists  of  a  header,  two
            consecutive  CRLFs,  and  the   message   header   for   the
            encapsulated  message.  If another pair of consecutive CRLFs
            appears, this of course ends  the  message  header  for  the
            encapsulated   message.   However,  since  the  encapsulated
            message's body is itself external, it does NOT appear in the
            area  that  follows.   For  example,  consider the following
            message:

                 Content-type: message/external-body; access-
                 type=local-file;
                      name=/u/nsb/Me.gif

                 Content-type:  image/gif

                 THIS IS NOT REALLY THE BODY!

            The area at the end, which  might  be  called  the  "phantom
            body", is ignored for most external-body messages.  However,
            it may be used to contain auxilliary  information  for  some



            Borenstein & Freed                                 [Page 40]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


            such  messages,  as  indeed  it  is  when the access-type is
            "mail-server".   Of  the  access-types   defined   by   this
            document, the phantom body is used only when the access-type
            is "mail-server".  In all other cases, the phantom  body  is
            ignored.

            The only always-mandatory  parameter  for  message/external-
            body  is  "access-type";  all of the other parameters may be
            mandatory or optional depending on the value of access-type.

                 ACCESS-TYPE -- One or more case-insensitive words,
                 comma-separated,   indicating   supported   access
                 mechanisms by  which  the  file  or  data  may  be
                 obtained.  Values include, but are not limited to,
                 "FTP", "ANON-FTP",  "TFTP",  "AFS",  "LOCAL-FILE",
                 and   "MAIL-SERVER".  Future  values,  except  for
                 experimental values beginning with "X-",  must  be
                 registered with IANA, as described in Appendix F .

            In addition, the following two parameters are  optional  for
            ALL access-types:

                 EXPIRATION -- The date (in the RFC 822 "date-time"
                 syntax, as extended by RFC 1123 to permit 4 digits
                 in the date field) after which  the  existence  of
                 the external data is not guaranteed.

                 SIZE -- The size (in octets)  of  the  data.   The
                 intent  of this parameter is to help the recipient
                 decide whether or  not  to  expend  the  necessary
                 resources to retrieve the external data.

                 PERMISSION -- A field that  indicates  whether  or
                 not it is expected that clients might also attempt
                 to  overwrite  the  data.   By  default,   or   if
                 permission  is "read", the assumption is that they
                 are not, and that if the data is  retrieved  once,
                 it  is never needed again. If PERMISSION is "read-
                 write", this assumption is invalid, and any  local
                 copy  must  be  considered  no  more than a cache.
                 "Read"  and  "Read-write"  are  the  only  defined
                 values of permission.

            The precise semantics of the access-types defined  here  are
            described in the sections that follow.

            7.3.3.1  The "ftp" and "tftp" access-types

            An access-type of FTP or TFTP  indicates  that  the  message
            body is accessible as a file using the FTP [RFC-959] or TFTP
            [RFC-783] protocols, respectively.  For these  access-types,
            the following additional parameters are mandatory:





            Borenstein & Freed                                 [Page 41]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


                 NAME -- The name of the  file  that  contains  the
                 actual body data.

                 SITE -- A machine  from  which  the  file  may  be
                 obtained, using the given protocol

            Before the data is retrieved,  using  these  protocols,  the
            user  will  generally need to be asked to provide a login id
            and a password for the machine named by the site parameter.

            In addition, the  following  optional  parameters  may  also
            appear when the access-type is FTP or ANON-FTP:

                 DIRECTORY -- A directory from which the data named
                 by NAME should be retrieved.

                 MODE  --  A  transfer  mode  for  retrieving   the
                 information, e.g. "image".

            7.3.3.2  The "anon-ftp" access-type

            The "anon-ftp" access-type is identical to the "ftp"  access
            type,  except  that  the user need not be asked to provide a
            name and password for the specified site.  Instead, the  ftp
            protocol  will be used with login "anonymous" and a password
            that corresponds to the user's email address.

            7.3.3.3  The "local-file" and "afs" access-types

            An access-type of "local-file"  indicates  that  the  actual
            body  is  accessible  as  a  file  on the local machine.  An
            access-type of "afs" indicates that the file  is  accessible
            via  the  global  AFS  file  system.   In both cases, only a
            single parameter is required:

                 NAME -- The name of the  file  that  contains  the
                 actual body data.

            The following optional parameter may be used to describe the
            locality  of  reference  for  the data, that is, the site or
            sites at which the file is expected to be visible:

                 SITE -- A domain specifier for a machine or set of
                 machines that are known to have access to the data
                 file.  Asterisks may be used for wildcard matching
                 to   a   part   of   a   domain   name,   such  as
                 "*.bellcore.com", to indicate a set of machines on
                 which the data should be directly visible, while a
                 single asterisk may be used  to  indicate  a  file
                 that  is  expected  to  be  universally available,
                 e.g., via a global file system.

            7.3.3.4  The "mail-server" access-type




            Borenstein & Freed                                 [Page 42]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


            The "mail-server" access-type indicates that the actual body
            is  available  from  a mail server.  The mandatory parameter
            for this access-type is:

                 SERVER -- The email address  of  the  mail  server
                 from which the actual body data can be obtained.

            Because mail servers accept a variety  of  syntax,  some  of
            which  is  multiline,  the full command to be sent to a mail
            server is not included as a parameter  on  the  content-type
            line.   Instead,  it  may  be provided as the "phantom body"
            when  the  content-type  is  message/external-body  and  the
            access-type is mail-server.

            Note that  MIME  does  not  define  a  mail  server  syntax.
            Rather,  it  allows  the  inclusion of arbitrary mail server
            commands  in  the  phantom  body.   Implementations   should
            include the phantom body in the body of the message it sends
            to the mail server address to retrieve the relevant data.






































            Borenstein & Freed                                 [Page 43]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


            7.3.3.5  Examples and Further Explanations

            With  the  emerging  possibility  of  very  wide-area   file
            systems,  it becomes very hard to know in advance the set of
            machines where a  file  will  and  will  not  be  accessible
            directly  from the file system.  Therefore it may make sense
            to provide both a file name, to be tried directly,  and  the
            name of one or more sites from which the file is known to be
            accessible.  An implementation can try  to  retrieve  remote
            files  using FTP or any other protocol, using anonymous file
            retrieval or prompting the user for the necessary  name  and
            password.   If  an  external body is accessible via multiple
            mechanisms, the sender may include multiple  parts  of  type
            message/external-body    within    an    entity    of   type
            multipart/alternative.

            However, the external-body mechanism is not intended  to  be
            limited  to  file  retrieval,  as  shown  by the mail-server
            access-type.  Beyond this, one  can  imagine,  for  example,
            using a video server for external references to video clips.

            If an entity is of type  "message/external-body",  then  the
            body  of  the  entity  will contain the header fields of the
            encapsulated message.  The body itself is to be found in the
            external  location.   This  means  that  if  the body of the
            "message/external-body"  message  contains  two  consecutive
            CRLFs,  everything  after  those  pairs  is  NOT part of the
            message itself.  For  most  message/external-body  messages,
            this trailing area must simply be ignored.  However, it is a
            convenient place for additional data that cannot be included
            in  the  content-type  header field.   In particular, if the
            "access-type" value is "mail-server", then the trailing area
            must  contain  commands to be sent to the mail server at the
            address given by NAME@SITE, where  NAME  and  SITE  are  the
            values of the NAME and SITE parameters, respectively.

            The embedded message header fields which appear in the  body
            of the message/external-body data can be used to declare the
            Content-type  of  the  external  body.   Thus   a   complete
            message/external-body  message,  referring  to a document in
            PostScript format, might look like this:

                 From: Whomever
                 Subject: whatever
                 MIME-Version: 1.0
                 Message-ID: id1@host.com
                 Content-Type: multipart/alternative; boundary=42


                 --42
                 Content-Type: message/external-body;
                      name="BodyFormats.ps";





            Borenstein & Freed                                 [Page 44]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


                      site="thumper.bellcore.com";
                      access-type=ANON-FTP;
                      directory="pub";
                      mode="image";
                      expiration="Fri, 14 Jun 1991 19:13:14 -0400 (EDT)"

                 Content-type: application/postscript

                 --42
                 Content-Type: message/external-body;
                      name="/u/nsb/writing/rfcs/RFC-XXXX.ps";
                      site="thumper.bellcore.com";
                      access-type=AFS
                      expiration="Fri, 14 Jun 1991 19:13:14 -0400 (EDT)"

                 Content-type: application/postscript

                 --42
                 Content-Type: message/external-body;
                      access-type=mail-server
                      server="listserv@bogus.bitnet";
                      expiration="Fri, 14 Jun 1991 19:13:14 -0400 (EDT)"

                 Content-type: application/postscript

                 get rfc-xxxx doc

                 --42--

            Like the  message/partial  type,  the  message/external-body
            type  is  intended to be transparent, that is, to convey the
            data type in the external  body  rather  than  to  convey  a
            message  with  a body of that type.  Thus the headers on the
            outer and inner parts must be merged using the same rules as
            for  message/partial.   In  particular,  this means that the
            Content-type header is overridden, but the From and  Subject
            headers are preserved.

            Note that since the external bodies are not  transported  as
            mail,  they  need  not  conform to the 7-bit and line length
            requirements, but might in fact be  binary  files.   Thus  a
            Content-Transfer-Encoding is not generally necessary, though
            it is permitted.

            Note that the body of a message of  type  "message/external-
            body"  is  governed  by  the  basic  syntax  for  an RFC 822
            message.   In  particular,   anything   before   the   first
            consecutive  pair  of  CRLFs  is  header  information, while
            anything after it is body information, which is ignored  for
            most access-types.







            Borenstein & Freed                                 [Page 45]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


            7.4  The Application Content-Type

            The "application" Content-Type is to be used for data  which
            do  not fit in any of the other categories, and particularly
            for data to be processed by mail-based uses  of  application
            programs.  This is information which must be processed by an
            application before it is  viewable  or  usable  to  a  user.
            Expected  uses  for  Content-Type  application include mail-
            based  file  transfer,  spreadsheets,  data  for  mail-based
            scheduling    systems,    and    languages    for   "active"
            (computational) email.  (The latter, in particular, can pose
            security    problems   which   should   be   understood   by
            implementors, and are considered in detail in the discussion
            of the application/PostScript content-type.)

            For example, a meeting scheduler  might  define  a  standard
            representation for information about proposed meeting dates.
            An intelligent user agent  would  use  this  information  to
            conduct  a dialog with the user, and might then send further
            mail based on that dialog. More generally, there  have  been
            several  "active"  messaging  languages  developed  in which
            programs in a suitably specialized language are sent through
            the   mail   and   automatically   run  in  the  recipient's
            environment.

            Such  applications  may  be  defined  as  subtypes  of   the
            "application"  Content-Type.   This  document  defines three
            subtypes: octet-stream, ODA, and PostScript.

            In general, the subtype of application  will  often  be  the
            name  of  the  application  for which the data are intended.
            This does not mean, however, that  any  application  program
            name  may  be used freely as a subtype of application.  Such
            usages  must  be  registered  with  IANA,  as  described  in
            Appendix F.

            7.4.1     The Application/Octet-Stream (primary) subtype

            The primary subtype of application, "octet-stream",  may  be
            used  to indicate that a body contains binary data.  The set
            of possible parameters includes, but is not limited to:

                 NAME -- a suggested name for the  binary  data  if
                 stored as a file.

                 TYPE -- the general type  or  category  of  binary
                 data.   This  is  intended  as information for the
                 human recipient  rather  than  for  any  automatic
                 processing.

                 CONVERSIONS -- the set  of  operations  that  have
                 been  performed  on  the data before putting it in
                 the mail (and before any Content-Transfer-Encoding
                 that   might   have  been  applied).  If  multiple



            Borenstein & Freed                                 [Page 46]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


                 conversions have occurred, they must be  separated
                 by  commas  and  specified  in the order they were
                 applied -- that is, the leftmost conversion   must
                 have  occurred  first,  and conversions are undone
                 from right  to  left.   Note  that  NO  conversion
                 values   are   defined   by  this  document.   Any
                 conversion values that that do not begin with "X-"
                 must  be preceded by a published specification and
                 by  registration  with  IANA,  as   described   in
                 Appendix F.

                 PADDING -- the number of bits of padding that were
                 appended  to  the  bitstream comprising the actual
                 contents to  produce  the  enclosed  byte-oriented
                 data.  This is useful for enclosing a bitstream in
                 a body when the total number  of  bits  is  not  a
                 multiple of the byte size.

            The values  for  these  attributes  are  left  undefined  at
            present,  but  may  require specification in the future.  An
            example of a common (though UNIX-specific) usage might be:

                 Content-Type:  application/octet-stream;
                      name=foo.tar.Z; type=tar;
                      conversions="x-encrypt,x-compress"

            However, it should be noted that the use of such conversions
            is  explicitly  discouraged due to a lack of portability and
            standardization.   The  use  of  uuencode  is   particularly
            discouraged,   in  favor  of  the  Content-Transfer-Encoding
            mechanism, which is both more standardized and more portable
            across mail boundaries.

            The recommended action for an implementation  that  receives
            application/octet-stream  mail is to simply offer to put the
            data in a file, with any  Content-Transfer-Encoding  undone,
            or perhaps to use it as input to a user-specified process.

            To reduce the danger of transmitting rogue programs  through
            the  mail,  it  is strongly recommended that implementations
            NOT implement a path-search mechanism whereby  an  arbitrary
            program  named  in  the  Content-Type  parameter  (e.g.,  an
            "interpreter=" parameter) is found and  executed  using  the
            mail body as input.

            7.4.2     The Application/PostScript subtype

            A  Content-Type  of  "application/postscript"  indicates   a
            PostScript    program.    The   language   is   defined   in
            [POSTSCRIPT].  It is recommended  that  Postscript  as  sent
            through  email  should  use  Postscript document structuring
            conventions if at all possible, and correctly.





            Borenstein & Freed                                 [Page 47]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


            The execution  of  general-purpose  PostScript  interpreters
            entails   serious   security  risks,  and  implementors  are
            discouraged from simply sending PostScript email  bodies  to
            "off-the-shelf"  interpreters.   While it is usually safe to
            send PostScript to a printer, where the potential  for  harm
            is  greatly constrained, implementors should consider all of
            the  following  before  they  add  interactive  display   of
            PostScript bodies to their mail readers.

            The remainder of this section outlines some, though probably
            not  all,  of  the possible problems with sending PostScript
            through the mail.

            Dangerous operations in the PostScript language include, but
            may  not be limited to, the PostScript operators deletefile,
            renamefile,  filenameforall,  and  file.    File   is   only
            dangerous  when  applied  to  something  other than standard
            input or output. Implementations may also define  additional
            nonstandard  file operators; these may also pose a threat to
            security.     Filenameforall,  the  wildcard   file   search
            operator,  may  appear at first glance to be harmless. Note,
            however, that this operator  has  the  potential  to  reveal
            information  about  what  files the recipient has access to,
            and this  information  may  itself  be  sensitive.   Message
            senders  should  avoid the use of potentially dangerous file
            operators, since these operators  are  quite  likely  to  be
            unavailable  in secure PostScript implementations.  Message-
            receiving and -displaying software should either  completely
            disable  all  potentially  dangerous  file operators or take
            special care not to delegate any special authority to  their
            operation. These operators should be viewed as being done by
            an outside agency when  interpreting  PostScript  documents.
            Such  disabling  and/or  checking  should be done completely
            outside of the reach of the PostScript language itself; care
            should  be  taken  to  insure  that  no  method  exists  for
            reenabling full-function versions of these operators.

            The PostScript language provides facilities for exiting  the
            normal  interpreter,  or  server, loop. Changes made in this
            "outer"  environment   are   customarily   retained   across
            documents, and may in some cases be retained semipermanently
            in nonvolatile memory. The operators associated with exiting
            the  interpreter  loop  have the potential to interfere with
            subsequent document processing. As such, their  unrestrained
            use  constitutes  a  threat  of  service denial.  PostScript
            operators that exit the interpreter loop  include,  but  may
            not  be  limited  to, the exitserver and startjob operators.
            Message-sending software should not generate PostScript that
            depends  on  exiting  the  interpreter  loop to operate. The
            ability to exit  will  probably  be  unavailable  in  secure
            PostScript     implementations.     Message-receiving    and
            -displaying  software  should,  if  possible,  disable   the
            ability   to   make   retained  changes  to  the  PostScript
            environment. Eliminate the startjob and exitserver commands.



            Borenstein & Freed                                 [Page 48]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


            If  these  commands  cannot  be eliminated, at least set the
            password associated with them to a hard-to-guess value.

            PostScript provides operators for  setting  system-wide  and
            device-specific  parameters. These parameter settings may be
            retained across jobs and may potentially pose  a  threat  to
            the  correct  operation  of the interpreter.  The PostScript
            operators that set system and device parameters include, but
            may  not be limited to, the setsystemparams and setdevparams
            operators.  Message-sending  software  should  not  generate
            PostScript  that  depends on the setting of system or device
            parameters to operate correctly. The ability  to  set  these
            parameters will probably be unavailable in secure PostScript
            implementations. Message-receiving and -displaying  software
            should,  if  possible,  disable the ability to change system
            and  device  parameters.  If  these  operators   cannot   be
            disabled,  at least set the password associated with them to
            a hard-to-guess value.

            Some   PostScript   implementations   provide    nonstandard
            facilities  for  the direct loading and execution of machine
            code.  Such  facilities  are  quite    obviously   open   to
            substantial  abuse.    Message-sending  software  should not
            make use of such features. Besides being  totally  hardware-
            specific,  they  are also likely to be unavailable in secure
            implementations  of  PostScript.     Message-receiving   and
            -displaying  software  should not allow such operators to be
            used if they exist.

            PostScript is an extensible language, and many, if not most,
            implementations   of  it  provide  a  number  of  their  own
            extensions. This document does not deal with such extensions
            explicitly   since   they   constitute  an  unknown  factor.
            Message-sending software should not make use of  nonstandard
            extensions;   they  are  likely  to  be  missing  from  some
            implementations. Message-receiving and -displaying  software
            should  make  sure that any nonstandard PostScript operators
            are secure and don't present any kind of threat.

            It is  possible  to  write  PostScript  that  consumes  huge
            amounts  of various system resources. It is also possible to
            write PostScript programs that loop infinitely.  Both  types
            of  programs  have  the potential to cause damage if sent to
            unsuspecting recipients.   Message-sending  software  should
            avoid  the  construction and dissemination of such programs,
            which  is  antisocial.   Message-receiving  and  -displaying
            software  should  provide  appropriate  mechanisms  to abort
            processing of a document after a reasonable amount  of  time
            has  elapsed. In addition, PostScript interpreters should be
            limited to the consumption of only a  reasonable  amount  of
            any given system resource.

            Finally, bugs may  exist  in  some  PostScript  interpreters
            which  could  possibly  be  exploited  to  gain unauthorized



            Borenstein & Freed                                 [Page 49]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


            access to a  recipient's  system.  Apart  from  noting  this
            possibility,  there is no specific action to take to prevent
            this, apart from the timely correction of such bugs  if  any
            are found.

            7.4.3     The Application/ODA subtype

            The "ODA" subtype of application is used to indicate that  a
            body  contains  information  encoded according to the Office
            Document  Architecture  [ODA]   standards,  using  the  ODIF
            representation  format.   For  application/oda, the Content-
            Type line should also specify an attribute/value  pair  that
            indicates  the document application profile (DAP), using the
            key word "profile".  Thus an appropriate header field  might
            look like this:

            Content-Type:  application/oda; profile=Q112

            Consult the ODA standard [ODA] for further information.






































            Borenstein & Freed                                 [Page 50]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


            7.5  The Image Content-Type

            A Content-Type of "image" indicates that the bodycontains an
            image.   The subtype names the specific image format.  These
            names are case insensitive.  Two initial subtypes are "jpeg"
            for the JPEG format, JFIF encoding, and "gif" for GIF format
            [GIF].

            The list of image subtypes given here is  neither  exclusive
            nor  exhaustive,  and  is expected to grow as more types are
            registered with IANA, as described in Appendix F.

            7.6  The Audio Content-Type

            A Content-Type of "audio" indicates that the  body  contains
            audio  data.   Although  there  is not yet a consensus on an
            "ideal" audio format for use  with  computers,  there  is  a
            pressing   need   for   a   format   capable   of  providing
            interoperable behavior.

            The initial subtype of "basic" is  specified  to  meet  this
            requirement by providing an absolutely minimal lowest common
            denominator  audio  format.   It  is  expected  that  richer
            formats for higher quality and/or lower bandwidth audio will
            be defined by a later document.

            The content of the "audio/basic" subtype  is  audio  encoded
            using  8-bit ISDN u-law [PCM]. When this subtype is present,
            a sample rate of 8000 Hz and a single channel is assumed.

            7.7  The Video Content-Type

            A Content-Type of "video" indicates that the body contains a
            time-varying-picture   image,   possibly   with   color  and
            coordinated sound.   The  term  "video"  is  used  extremely
            generically,  rather  than  with reference to any particular
            technology or format, and is not meant to preclude  subtypes
            such  as animated drawings encoded compactly.    The subtype
            "mpeg" refers to video coded according to the MPEG  standard
            [MPEG].

            Note  that  although  in  general  this  document   strongly
            discourages  the  mixing of multiple media in a single body,
            it is recognized that many so-called "video" formats include
            a   representation  for  synchronized  audio,  and  this  is
            explicitly permitted for subtypes of "video".

            7.8  Experimental Content-Type Values

            A Content-Type value beginning with the characters "X-" is a
            private  value,  to  be  used  by consenting mail systems by
            mutual agreement.  Any format without a rigorous and  public
            definition  must  be named with an "X-" prefix, and publicly
            specified  values  shall  never  begin  with  "X-".   (Older



            Borenstein & Freed                                 [Page 51]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


            versions  of  the  widely-used Andrew system use the "X-BE2"
            name, so new systems  should  probably  choose  a  different
            name.)

            In general, the use of  "X-"  top-level  types  is  strongly
            discouraged.   Implementors  should  invent  subtypes of the
            existing types whenever  possible.   The  invention  of  new
            types   is  intended  to  be  restricted  primarily  to  the
            development of new media types for email,  such  as  digital
            odors  or  holography,  and  not  for  new  data  formats in
            general. In many cases, a subtype  of  application  will  be
            more appropriate than a new top-level type.













































            Borenstein & Freed                                 [Page 52]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


            Summary

            Using the MIME-Version, Content-Type, and  Content-Transfer-
            Encoding  header  fields,  it  is  possible to include, in a
            standardized way, arbitrary types of data objects  with  RFC
            822  conformant  mail  messages.  No restrictions imposed by
            either RFC 821 or RFC 822 are violated, and  care  has  been
            taken  to  avoid  problems caused by additional restrictions
            imposed  by  the  characteristics  of  some  Internet   mail
            transport  mechanisms  (see Appendix B). The "multipart" and
            "message"  Content-Types  allow  mixing   and   hierarchical
            structuring  of  objects  of  different  types  in  a single
            message.  Further  Content-Types  provide   a   standardized
            mechanism  for  tagging  messages  or  body  parts as audio,
            image, or several other  kinds  of  data.   A  distinguished
            parameter syntax allows further specification of data format
            details,  particularly  the   specification   of   alternate
            character  sets.  Additional  optional header fields provide
            mechanisms for certain extensions deemed desirable  by  many
            implementors.  Finally, a number of useful Content-Types are
            defined for general use by consenting user  agents,  notably
            text/richtext, message/partial, and message/external-body.



































            Borenstein & Freed                                 [Page 53]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


            Acknowledgements

            This document is the result of the collective  effort  of  a
            large  number  of  people,  at several IETF meetings, on the
            IETF-SMTP  and  IETF-822  mailing  lists,   and   elsewhere.
            Although   any  enumeration  seems  doomed  to  suffer  from
            egregious  omissions,  the  following  are  among  the  many
            contributors to this effort:

            Harald Tveit Alvestrand       Timo Lehtinen
            Randall Atkinson              John R. MacMillan
            Philippe Brandon              Rick McGowan
            Kevin Carosso                 Leo Mclaughlin
            Uhhyung Choi                  Goli Montaser-Kohsari
            Cristian Constantinof         Keith Moore
            Mark Crispin                  Tom Moore
            Dave Crocker                  Erik Naggum
            Terry Crowley                 Mark Needleman
            Walt Daniels                  John Noerenberg
            Frank Dawson                  Mats Ohrman
            Hitoshi Doi                   Julian Onions
            Kevin Donnelly                Michael Patton
            Keith Edwards                 David J. Pepper
            Chris Eich                    Blake C. Ramsdell
            Johnny Eriksson               Luc Rooijakkers
            Craig Everhart                Marshall T. Rose
            Patrik Faeltstroem              Jonathan Rosenberg
            Erik E. Fair                  Jan Rynning
            Roger Fajman                  Harri Salminen
            Alain Fontaine                Michael Sanderson
            James M. Galvin               Masahiro Sekiguchi
            Philip Gladstone              Mark Sherman
            Thomas Gordon                 Keld Simonsen
            Phill Gross                   Bob Smart
            James Hamilton                Peter Speck
            Steve Hardcastle-Kille        Henry Spencer
            David Herron                  Einar Stefferud
            Bruce Howard                  Michael Stein
            Bill Janssen                  Klaus Steinberger
            Olle Jaernefors                Peter Svanberg
            Risto Kankkunen               James Thompson
            Phil Karn                     Steve Uhler
            Alan Katz                     Stuart Vance
            Tim Kehres                    Erik van der Poel
            Neil Katin                    Guido van Rossum
            Kyuho Kim                     Peter Vanderbilt
            Anders Klemets                Greg Vaudreuil
            John Klensin                  Ed Vielmetti
            Valdis Kletniek               Ryan Waldron
            Jim Knowles                   Wally Wedel
            Stev Knowles                  Sven-Ove Westberg
            Bob Kummerfeld                Brian Wideen





            Borenstein & Freed                                 [Page 54]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


            Pekka Kytolaakso              John Wobus
            Stellan Lagerstr.m            Glenn Wright
            Vincent Lau                   Rayan Zachariassen
            Donald Lindsay                David Zimmerman
            The authors apologize for  any  omissions  from  this  list,
            which are certainly unintentional.



















































            Borenstein & Freed                                 [Page 55]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


            Appendix A -- Minimal MIME-Conformance

            The mechanisms described in this  document  are  open-ended.
            It  is definitely not expected that all implementations will
            support all of the Content-Types described,  nor  that  they
            will  all  share  the  same extensions.  In order to promote
            interoperability,  however,  it  is  useful  to  define  the
            concept  of  "MIME-conformance" to define a certain level of
            implementation  that  allows  the  useful  interworking   of
            messages  with  content that differs from US ASCII text.  In
            this  section,  we  specify  the   requirements   for   such
            conformance.

            A mail user agent that is MIME-conformant MUST:

                 1.  Always generate a "MIME-Version:  1.0"  header
                 field.

                 2.  Recognize the Content-Transfer-Encoding header
                 field,  and  decode all received data encoded with
                 either    the    quoted-printable    or     base64
                 implementations.    Encode  any  data sent that is
                 not in seven-bit mail-ready  representation  using
                 one  of  these  transformations  and  include  the
                 appropriate    Content-Transfer-Encoding    header
                 field,  unless  the underlying transport mechanism
                 supports non-seven-bit data, as SMTP does not.

                 3.   Recognize  and  interpret  the   Content-Type
                 header  field,  and  avoid  showing users raw data
                 with a Content-Type field  other  than  text.   Be
                 able  to  send  at least text/plain messages, with
                 the character set specified as a parameter  if  it
                 is not US-ASCII.

                 4.  Explicitly handle the  following  Content-Type
                 values, to at least the following extents:

                 Text:
                      -- Recognize  and  display  "text"  mail
                           with the character set "US-ASCII."
                      -- Recognize  other  character  sets  at
                           least  to  the extent of being able
                           to  inform  the  user  about   what
                           character set the message uses.
                      -- Recognize the "ISO-8859-*"  character
                           sets to the extent of being able to
                           display those characters  that  are
                           common  to ISO-8859-* and US-ASCII,
                           namely all  characters  represented
                           by octet values 0-127.
                      -- For unrecognized  subtypes,  show  or
                           offer  to  show  the user the "raw"
                           version of the data.  An ability at



            Borenstein & Freed                                 [Page 56]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


                           least to convert "text/richtext" to
                           plain text, as shown in Appendix D,
                           is encouraged, but not required for
                           conformance.
                 Message:
                      --Recognize and  display  at  least  the
                           primary (822) encapsulation.
                 Multipart:
                      --   Recognize   the   primary   (mixed)
                           subtype.    Display   all  relevant
                           information on  the  message  level
                           and  the body part header level and
                           then display or  offer  to  display
                           each     of    the    body    parts
                           individually.
                      -- Recognize the "alternative"  subtype,
                           and    avoid   showing   the   user
                           redundant         parts          of
                           multipart/alternative mail.
                      -- Treat any unrecognized subtypes as if
                           they were "mixed".
                 Application:
                      -- Offer the ability to remove either of
                           the  two types of Content-Transfer-
                           Encoding defined in  this  document
                           and  put  the resulting information
                           in a user file.

                 5.  Upon encountering  any  unrecognized  Content-
                 Type, an implementation must treat it as if it had
                 a Content-Type of "application/octet-stream"  with
                 no  parameter  sub-arguments.  How  such  data are
                 handled is up to  an  implementation,  but  likely
                 options   for   handling  such  unrecognized  data
                 include offering the user to write it into a  file
                 (decoded   from  its  mail  transport  format)  or
                 offering the user to name a program to  which  the
                 decoded   data   should   be   passed   as  input.
                 Unrecognized predefined types, which  in  a  MIME-
                 conformant   mailer  might  still  include  audio,
                 image, or video, should also be  treated  in  this
                 way.

            A user agent that meets the above conditions is said  to  be
            MIME-conformant.   The  meaning of this phrase is that it is
            assumed  to  be  "safe"  to  send  virtually  any  kind   of
            properly-marked  data to users of such mail systems, because
            such systems will at least be able  to  treat  the  data  as
            undifferentiated  binary, and will not simply splash it onto
            the screen of unsuspecting users.   There is  another  sense
            in  which  it is always "safe" to send data in a format that
            is MIME-conformant, which is that such data will  not  break
            or  be  broken by any known systems that are conformant with
            RFC 821 and RFC 822.  User agents that  are  MIME-conformant



            Borenstein & Freed                                 [Page 57]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


            have  the  additional  guarantee  that  the user will not be
            shown data that were never intended to be viewed as text.























































            Borenstein & Freed                                 [Page 58]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


            Appendix B -- General Guidelines For Sending Email Data

            Internet email is not a perfect, homogeneous  system.   Mail
            may  become  corrupted  at several stages in its travel to a
            final destination. Specifically, email sent  throughout  the
            Internet  may  travel  across  many networking technologies.
            Many networking and mail technologies  do  not  support  the
            full   functionality   possible   in   the   SMTP  transport
            environment. Mail traversing these systems is likely  to  be
            modified in such a way that it can be transported.

            There exist many widely-deployed non-conformant MTAs in  the
            Internet.  These  MTAs,  speaking  the  SMTP protocol, alter
            messages on the fly to take advantage of the  internal  data
            structure  of the hosts they are implemented on, or are just
            plain broken.

            The following guidelines may be useful to anyone devising  a
            data  format  (Content-Type)  that  will  survive the widest
            range of  networking  technologies  and  known  broken  MTAs
            unscathed.    Note  that  anything  encoded  in  the  base64
            encoding will satisfy these rules, but that some  well-known
            mechanisms,  notably  the  UNIX uuencode facility, will not.
            Note also that  anything  encoded  in  the  Quoted-Printable
            encoding will survive most gateways intact, but possibly not
            some gateways to systems that use the EBCDIC character set.

                 (1) Under some circumstances the encoding used for
                 data  may change as part of normal gateway or user
                 agent operation. In  particular,  conversion  from
                 base64  to  quoted-printable and vice versa may be
                 necessary. This may result  in  the  confusion  of
                 CRLF  sequences  with  line  breaks  in  text body
                 parts.  As  such,  the  persistence  of  CRLF   as
                 something  other  than  a line break should not be
                 relied on.

                 (2) Many systems may elect to represent and  store
                 text  data  using local newline conventions. Local
                 newline conventions may not match the RFC822  CRLF
                 convention -- systems are known that use plain CR,
                 plain LF, CRLF, or counted records.  The result is
                 that isolated CR and LF characters  are  not  well
                 tolerated  in    general;  they  may  be  lost  or
                 converted to delimiters on some systems, and hence
                 should not be relied on.

                 (3) TAB (HT) characters may be  misinterpreted  or
                 may be automatically converted to variable numbers
                 of  spaces.    This   is   unavoidable   in   some
                 environments, notably those not based on the ASCII
                 character  set.  Such   conversion   is   STRONGLY
                 DISCOURAGED,  but  it  may occur, and mail formats
                 should not rely on the  persistence  of  TAB  (HT)



            Borenstein & Freed                                 [Page 59]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


                 characters.

                 (4) Lines longer than 76 characters may be wrapped
                 or  truncated  in some environments. Line wrapping
                 and line truncation are STRONGLY DISCOURAGED,  but
                 unavoidable  in  some  cases.  Applications  which
                 require long lines  should  somehow  differentiate
                 between  soft and hard line breaks.  (A simple way
                 to  do  this  is  to  use   the   quoted-printable
                 encoding.)

                 (5)  Trailing "white space" characters (SPACE, TAB
                 (HT)) on a line may be discarded by some transport
                 agents, while other transport agents may pad lines
                 with  these characters so that all lines in a mail
                 file are of equal  length.    The  persistence  of
                 trailing  white  space,  therefore,  should not be
                 relied on.

                 (6)  Many mail domains use variations on the ASCII
                 character  set,  or  use  character  sets  such as
                 EBCDIC which contain most but not all of  the  US-
                 ASCII  characters.   The  correct  translation  of
                 characters not in the "invariant"  set  cannot  be
                 depended  on across character converting gateways.
                 For example, this  situation  is  a  problem  when
                 sending  uuencoded  information  across BITNET, an
                 EBCDIC system.  Similar problems can occur without
                 crossing  a gateway, since many Internet hosts use
                 character sets other than ASCII  internally.   The
                 definition  of  Printable  Strings  in  X.400 adds
                 further restrictions in certain special cases.  In
                 particular,  the only characters that are known to
                 be consistent  across  all  gateways  are  the  73
                 characters  that correspond to the upper and lower
                 case letters A-Z and a-z, the 10 digits  0-9,  and
                 the following eleven special characters:

                                "'"  (ASCII code 39)
                                "("  (ASCII code 40)
                                ")"  (ASCII code 41)
                                "+"  (ASCII code 43)
                                ","  (ASCII code 44)
                                "-"  (ASCII code 45)
                                "."  (ASCII code 46)
                                "/"  (ASCII code 47)
                                ":"  (ASCII code 58)
                                "="  (ASCII code 61)
                                "?"  (ASCII code 63)

                 A maximally portable mail representation, such  as
                 the   base64  encoding,  will  confine  itself  to
                 relatively short lines of text in which  the  only
                 meaningful  characters  are taken from this set of



            Borenstein & Freed                                 [Page 60]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


                 73 characters.

            Please note that the above list is NOT a list of recommended
            practices  for  MTAs.  RFC  821  MTAs  are  prohibited  from
            altering the character  of  white  space  or  wrapping  long
            lines.   These  BAD and illegal practices are known to occur
            on established networks, and implementions should be  robust
            in dealing with the bad effects they can cause.

















































            Borenstein & Freed                                 [Page 61]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


            Appendix C -- A Complex Multipart Example

            What follows is the outline of a complex multipart  message.
            This  message  has five parts to be displayed serially:  two
            introductory  plain  text  parts,  an   embedded   multipart
            message,  a  richtext  part, and a closing encapsulated text
            message  in  a  non-ASCII  character  set.    The   embedded
            multipart message has two parts to be displayed in parallel,
            a picture and an audio fragment.

                 MIME-Version: 1.0
                 From: Nathaniel Borenstein <nsb@bellcore.com>
                 Subject: A multipart example
                 Content-Type: multipart/mixed;
                      boundary=unique-boundary-1

                 This is the preamble area of a multipart message.
                 Mail readers that understand multipart format
                 should ignore this preamble.
                 If you are reading this text, you might want to
                 consider changing to a mail reader that understands
                 how to properly display multipart messages.
                 --unique-boundary-1

                 ...Some text appears here...
                 [Note that the preceding blank line means
                 no header fields were given and this is text,
                 with charset US ASCII.  It could have been
                 done with explicit typing as in the next part.]

                 --unique-boundary-1
                 Content-type: text/plain; charset=US-ASCII

                 This could have been part of the previous part,
                 but illustrates explicit versus implicit
                 typing of body parts.

                 --unique-boundary-1
                 Content-Type: multipart/parallel;
                      boundary=unique-boundary-2


                 --unique-boundary-2
                 Content-Type: audio/basic
                 Content-Transfer-Encoding: base64

                 ... base64-encoded 8000 Hz single-channel
                     u-law-format audio data goes here....

                 --unique-boundary-2
                 Content-Type: image/gif
                 Content-Transfer-Encoding: Base64





            Borenstein & Freed                                 [Page 62]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


                 ... base64-encoded image data goes here....

                 --unique-boundary-2--

                 --unique-boundary-1
                 Content-type: text/richtext

                 This is <bold><italic>richtext.</italic></bold>
                 <nl><nl>Isn't it
                 <bigger><bigger>cool?</bigger></bigger>

                 --unique-boundary-1
                 Content-Type: message/rfc822

                 From: (name in US-ASCII)
                 Subject: (subject in US-ASCII)
                 Content-Type: Text/plain; charset=ISO-8859-1
                 Content-Transfer-Encoding: Quoted-printable

                 ... Additional text in ISO-8859-1 goes here ...

                 --unique-boundary-1--



































            Borenstein & Freed                                 [Page 63]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


            Appendix D -- A Simple Richtext-to-Text Translator in C

            One of the major goals in the design of the richtext subtype
            of the text Content-Type is to make formatted text so simple
            that even  text-only  mailers  will  implement  richtext-to-
            plain-text  translators, thus increasing the likelihood that
            multifont text will become "safe" to use  very  widely.   To
            demonstrate  this  simplicity,  what follows is an extremely
            simple 44-line C program that converts richtext  input  into
            plain text output:

                 #include <stdio.h>
                 #include <ctype.h>
                 main() {
                     int c, i;
                     char token[50];

                     while((c = getc(stdin)) != EOF) {
                         if (c == '<') {
                             for (i=0; (i<49 && (c = getc(stdin)) != '>'
                                       && c != EOF); ++i) {
                                 token[i] = isupper(c) ? tolower(c) : c;
                             }
                             if (c == EOF) break;
                             if (c != '>') while ((c = getc(stdin)) !=
                 '>'
                                       && c != EOF) {;}
                             if (c == EOF) break;
                             token[i] = '\0';
                             if (!strcmp(token, "lt")) {
                                 putc('<', stdout);
                             } else if (!strcmp(token, "nl")) {
                                 putc('\n', stdout);
                             } else if (!strcmp(token, "/paragraph")) {
                                 fputs("\n\n", stdout);
                             } else if (!strcmp(token, "comment")) {
                                 int commct=1;
                                 while (commct > 0) {
                                     while ((c = getc(stdin)) != '<'
                                      && c != EOF) ;
                                     if (c == EOF) break;
                                     for (i=0; (c = getc(stdin)) != '>'
                                        && c != EOF; ++i) {
                                         token[i] = isupper(c) ?
                                          tolower(c) : c;
                                     }
                                     if (c== EOF) break;
                                     token[i] = NULL;
                                     if (!strcmp(token, "/comment")) --
                 commct;
                                     if (!strcmp(token, "comment"))
                 ++commct;





            Borenstein & Freed                                 [Page 64]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


                                 }
                             } /* Ignore all other tokens */
                         } else if (c != '\n') putc(c, stdout);
                     }
                     putc('\n', stdout); /* for good measure */
                 }
            It should be noted that one can do considerably better  than
            this  in  displaying  richtext  data on a dumb terminal.  In
            particular, one can replace font information such as  "bold"
            with textual emphasis (like *this* or   _T_H_I_S_).  One can
            also  properly  handle  the  richtext  formatting   commands
            regarding  indentation, justification, and others.  However,
            the above program is all  that  is  necessary  in  order  to
            present richtext on a dumb terminal.











































            Borenstein & Freed                                 [Page 65]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


            Appendix E -- Collected Grammar

            This appendix contains the complete BNF grammar for all  the
            syntax specified by this document.

            By itself, however, this grammar is incomplete.   It  refers
            to  several  entities  that  are defined by RFC 822.  Rather
            than   reproduce   those   definitions   here,   and    risk
            unintentional  differences  between  the  two, this document
            simply refers the  reader  to  RFC  822  for  the  remaining
            definitions.  Wherever a term is undefined, it refers to the
            RFC 822 definition.

            attribute := token

            body-part = <"message" as defined in RFC 822,
                     with all header fields optional, and with the
                     specified delimiter not occurring anywhere in
                     the message body, either on a line by itself
                     or as a substring anywhere.>

            boundary := 0*69<bchars> bcharsnospace

            bchars := bcharsnospace / " "

            bcharsnospace :=    DIGIT / ALPHA / "'" / "(" / ")" / "+"  /
            "_"
                           / "," / "-" / "." / "/" / ":" / "=" / "?"

            close-delimiter := delimiter "--"

            Content-Description := *text

            Content-ID := msg-id

            Content-Transfer-Encoding  :=      "BASE64"     /   "QUOTED-
            PRINTABLE" /
                                            "8BIT"  / "7BIT" /
                                            "BINARY"     / x-token

            Content-Type := type "/" subtype *[";" parameter]

            delimiter := CRLF "--" boundary   ; taken from  Content-Type
            field.
                                           ;   when   content-type    is
            multipart
                                         ; There should be no space
                                         ; between "--" and boundary.

            encapsulation := delimiter CRLF body-part

            epilogue :=  *text                  ;  to  be  ignored  upon
            receipt.




            Borenstein & Freed                                 [Page 66]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


            MIME-Version := 1*text

            multipart-body := preamble  1*encapsulation  close-delimiter
            epilogue

            parameter := attribute "=" value

            preamble :=  *text                  ;  to  be  ignored  upon
            receipt.

            subtype := token

            token := 1*<any CHAR except SPACE, CTLs, or tspecials>

            tspecials :=  "(" / ")" / "<" / ">" / "@"  ; Must be in
                       /  "," / ";" / ":" / "\" / <">  ; quoted-string,
                       /  "/" / "[" / "]" / "?" / "."  ; to use within
                       /  "="                        ; parameter values


            type :=            "application"     /  "audio"     ;  case-
            insensitive
                      / "image"           / "message"
                      / "multipart"  / "text"
                      / "video"           / x-token

            value := token / quoted-string

            x-token := <The two characters "X-" followed, with no
                       intervening white space, by any token>



























            Borenstein & Freed                                 [Page 67]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


            Appendix F -- IANA Registration Procedures

            MIME  has  been  carefully  designed  to   have   extensible
            mechanisms,  and  it  is  expected  that the set of content-
            type/subtype pairs and their associated parameters will grow
            significantly with time.  Several other MIME fields, notably
            character  set  names,  access-type   parameters   for   the
            message/external-body  type,  conversions parameters for the
            application  type,  and  possibly   even   Content-Transfer-
            Encoding  values, are likely to have new values defined over
            time.  In order to ensure that the set  of  such  values  is
            developed  in an orderly, well-specified, and public manner,
            MIME defines a registration process which uses the  Internet
            Assigned  Numbers Authority (IANA) as a central registry for
            such values.

            In general, parameters in the content-type header field  are
            used  to convey supplemental information for various content
            types, and their use is defined when  the  content-type  and
            subtype  are  defined.  New parameters should not be defined
            as a way to introduce new functionality.

            In  order  to  simplify  and  standardize  the  registration
            process,  this appendix gives templates for the registration
            of new values with IANA.  Each of these is given in the form
            of  an  email  message  template,  to  be  filled  in by the
            registering party.

            F.1  Registration of New Content-type/subtype Values

            Note that MIME is  generally  expected  to  be  extended  by
            subtypes.   If  a  new fundamental top-level type is needed,
            its  specification  should  be  published  as  an   RFC   or
            submitted  in  a  form   suitable  to  become an RFC, and be
            subject to the Internet standards process.

                 To:  IANA@isi.edu
                 Subject:  Registration of new MIME content-type/subtype

                 MIME type name:

                 (If the above is not an existing top-level MIME type,
                 please explain why an existing type cannot be used.)

                 MIME subtype name:

                 Required parameters:

                 Optional parameters:

                 Encoding considerations:

                 Security considerations:




            Borenstein & Freed                                 [Page 68]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


                 Published specification:

                 (The published specification must be an Internet RFC or
                 RFC-to-be if a new top-level type is being defined, and
                 must be a publicly available specification in any
                 case.)

                 Person & email address to contact for further
                 information:
            F.2  Registration of New Character Set Values

                 To:  IANA@isi.edu
                 Subject:  Registration of new MIME character set value

                 MIME character set name:

                 Published specification:

                 (The published specification must be an Internet RFC or
                 RFC-to-be or an international standard.)

                 Person & email address to contact for further
                 information:

            F.3  Registration of New Access-type Values for
            Message/external-body

                 To:  IANA@isi.edu
                 Subject:  Registration of new MIME Access-type for
                      Message/external-body content-type

                 MIME access-type name:

                 Required parameters:

                 Optional parameters:

                 Published specification:

                 (The published specification must be an Internet RFC or
                 RFC-to-be.)

                 Person & email address to contact for further
                 information:


            F.4  Registration of New Conversions Values for Application

                 To:  IANA@isi.edu
                 Subject:  Registration of new MIME Conversions value
                 for Application content-type

                 MIME Conversions name:




            Borenstein & Freed                                 [Page 69]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


                 Published specification:

                 (The published specification must be an Internet RFC or
                 RFC-to-be.)

                 Person & email address to contact for further
                 information:


















































            Borenstein & Freed                                 [Page 70]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


            Appendix G -- Summary of the Seven Content-types

            Content-type: text

            Subtypes defined by this document:  plain, richtext

            Important Parameters: charset

            Encoding notes: quoted-printable generally preferred  if  an
                 encoding  is  needed and the character set is mostly an
                 ASCII superset.

            Security considerations:  Rich text formats such as TeX  and
                 Troff  often contain mechanisms for executing arbitrary
                 commands or file system operations, and should  not  be
                 used  automatically unless these security problems have
                 been addressed.  Even plain text  may  contain  control
                 characters that can be used to exploit the capabilities
                 of   "intelligent"   terminals   and   cause   security
                 violations.   User  interfaces  designed to run on such
                 terminals should be aware of and try  to  prevent  such
                 problems.
            ________________________________________________________________

            Content-type: multipart

            Subtypes defined by  this  document:    mixed,  alternative,
                 digest, parallel.

            Important Parameters: boundary

            Encoding notes: No content-transfer-encoding is permitted.

            ________________________________________________________________

            Content-type: message

            Subtypes  defined  by  this  document:    rfc822,   partial,
                 external-body

            Important Parameters: id, number, total

            Encoding notes: No content-transfer-encoding is permitted.

            ________________________________________________________________

            Content-type: application

            Subtypes  defined   by   this   document:      octet-stream,
                 postscript, oda

            Important Parameters: profile





            Borenstein & Freed                                 [Page 71]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


            Encoding notes: base64 generally preferred for  octet-stream
                 or other unreadable subtypes.

            Security considerations:  This  type  is  intended  for  the
            transmission  of data to be interpreted by locally-installed
            programs.  If used,  for  example,  to  transmit  executable
            binary  programs  or programs in general-purpose interpreted
            languages, such as LISP programs or  shell  scripts,  severe
            security  problems  could  result.   In  general, authors of
            mail-reading  agents  are  cautioned  against  giving  their
            systems  the  power  to  execute mail-based application data
            without carefully  considering  the  security  implications.
            While  it  is  certainly possible to define safe application
            formats and even safe interpreters for unsafe formats,  each
            interpreter  should  be  evaluated  separately  for possible
            security problems.
            ________________________________________________________________

            Content-type: image

            Subtypes defined by this document:  jpeg, gif

            Important Parameters: none

            Encoding notes: base64 generally preferred

            ________________________________________________________________

            Content-type: audio

            Subtypes defined by this document:  basic

            Important Parameters: none

            Encoding notes: base64 generally preferred

            ________________________________________________________________

            Content-type: video

            Subtypes defined by this document:  mpeg

            Important Parameters: none

            Encoding notes: base64 generally preferred












            Borenstein & Freed                                 [Page 72]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


            Appendix H -- Canonical Encoding Model



            There was some confusion, in earlier drafts  of  this  memo,
            regarding  the model for when email data was to be converted
            to canonical form and encoded, and in  particular  how  this
            process  would affect the treatment of CRLFs, given that the
            representation of newlines varies  greatly  from  system  to
            system.   For this reason, a canonical model for encoding is
            presented below.

            The process of composing a MIME message part can be modelled
            as  being  done in a number of steps.  Note that these steps
            are roughly similar to those steps used in RFC1113:

            Step 1.  Creation of local form.

            The body part to be transmitted is created in  the  system's
            native format.   The native character set is used, and where
            appropriate local end of line conventions are used as  well.
            The may be a UNIX-style text file, or a Sun raster image, or
            a VMS indexed file, or  audio  data  in  a  system-dependent
            format   stored  only  in  memory,  or  anything  else  that
            corresponds to the local model  for  the  representation  of
            some form of information.

            Step 2.  Conversion to canonical form.

            The entire body part,  including  "out-of-band"  information
            such   as   record   lengths  and  possibly  file  attribute
            information, is converted to  a  universal  canonical  form.
            The  specific  content  type of the body part as well as its
            associated attributes dictate the nature  of  the  canonical
            form  that is used.  Conversion to the proper canonical form
            may involve  character  set  conversion,  transformation  of
            audio   data,   compression,  or  various  other  operations
            specific to the various content types.

            For example, in the case of text/plain data, the  text  must
            be  converted to a supported character set and lines must be
            delimited with CRLF delimiters in  accordance  with  RFC822.
            Note  that the restriction on line lengths implied by RFC822
            is eliminated  if  the  next  step  employs  either  quoted-
            printable or base64 encoding.

            Step 3.  Apply transfer encoding.

            A Content-Transfer-Encoding appropriate for this  body  part
            is  applied.   Note  that  there  is  no  fixed relationship
            between the content  type  and  the  transfer  encoding.  In
            particular,  it  may  be  appropriate  to base the choice of
            base64 or quoted-printable  on  character  frequency  counts
            which are specific to a given instance of body part.



            Borenstein & Freed                                 [Page 73]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


            Step 4.  Insertion into message.

            The encoded object is inserted  into  a  MIME  message  with
            appropriate body part headers and boundary markers.

            It is vital to note that these steps are only a model;  they
            are  specifically  NOT  a blueprint for how an actual system
            would be built.  In particular, the model fails  to  account
            for two common designs:

                 1.  In many cases the conversion  to  a  canonical
                 form  prior  to encoding will be subsumed into the
                 encoder itself, which  understands  local  formats
                 directly.    For   example,   the   local  newline
                 convention for text  bodyparts  might  be  carried
                 through to the encoder itself along with knowledge
                 of what that format is.

                 2.  The output of the encoders may  have  to  pass
                 through  one  or  more  additional  steps prior to
                 being transmitted as  a  message.   As  such,  the
                 output  of  the  encoder may not be compliant with
                 the formats specified by RFC822.   In  particular,
                 once   again   it   may  be  appropriate  for  the
                 converter's output to  be  expressed  using  local
                 newline conventions rather than using the standard
                 RFC822 CRLF delimiters.

            Other implementation variations  are  conceivable  as  well.
            The  only  important  aspect  of this discussion is that the
            resulting messages are consistent with those produced by the
            model described here.

























            Borenstein & Freed                                 [Page 74]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


            References

            [US-ASCII] Coded Character Set--7-Bit American Standard Code
            for Information Interchange, ANSI X3.4-1986.

            [ATK]  Borenstein,  Nathaniel  S.,  Multimedia  Applications
            Development with the Andrew Toolkit, Prentice-Hall, 1990.

            [GIF] Graphics Interchange Format (Version 89a), Compuserve,
            Inc., Columbus, Ohio, 1990.

            [ISO-2022] International Standard--Information  Processing--
            ISO  7-bit  and  8-bit  coded character sets--Code extension
            techniques, ISO 2022:1986.

            [ISO-8859] Information Processing -- 8-bit Single-Byte Coded
            Graphic  Character Sets -- Part 1: Latin Alphabet No. 1, ISO
            8859-1:1987.  Part 2: Latin  alphabet  No.  2,  ISO  8859-2,
            1987.  Part 3: Latin alphabet No. 3, ISO 8859-3, 1988.  Part
            4:  Latin  alphabet  No.  4,  ISO  8859-4,  1988.   Part  5:
            Latin/Cyrillic   alphabet,  ISO  8859-5,  1988.     Part  6:
            Latin/Arabic  alphabet,  ISO  8859-6,   1987.      Part   7:
            Latin/Greek   alphabet,   ISO   8859-7,   1987.     Part  8:
            Latin/Hebrew alphabet, ISO 8859-8, 1988.     Part  9:  Latin
            alphabet No. 5, ISO 8859-9, 1990.

            [ISO-646] International  Standard--Information  Processing--
            ISO  7-bit coded  character set for information interchange,
            ISO 646:1983.

            [MPEG]  Video  Coding  Draft  Standard  ISO  11172  CD,  ISO
            IEC/TJC1/SC2/WG11 (Motion Picture Experts Group), May, 1991.

            [ODA] ISO 8613;  Information  Processing:  Text  and  Office
            System;  Office  Document Architecture (ODA) and Interchange
            Format (ODIF), Part 1-8, 1989.

            [PCM] CCITT, Fascicle III.4 - Recommendation G.711,  Geneva,
            1972, "Pulse Code Modulation (PCM) of Voice Frequencies".

            [POSTSCRIPT]  Adobe  Systems,  Inc.,   PostScript   Language
            Reference Manual,  Addison-Wesley, 1985.

            [X400]  Schicker, Pietro, "Message Handling Systems, X.400",
            Message  Handling  Systems  and Distributed Applications, E.
            Stefferud, O-j. Jacobsen,  and  P.  Schicker,  eds.,  North-
            Holland, 1989, pp. 3-41.

            [RFC-783]  Sollins, K.R.  TFTP Protocol (revision 2).  June,
            1981, MIT, RFC-783.

            [RFC-821]  Postel,  J.B.   Simple  Mail  Transfer  Protocol.
            August, 1982, USC/Information Sciences Institute, RFC-821.




            Borenstein & Freed                                 [Page 75]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


            [RFC-822]   Crocker, D.  Standard for  the  format  of  ARPA
            Internet  text  messages. August, 1982, UDEL, RFC-822.

            [RFC-934]   Rose, M.T.; Stefferud, E.A.   Proposed  standard
            for    message     encapsulation.  January,   1985, Delaware
            and NMA, RFC-934.

            [RFC-959]   Postel,  J.B.;  Reynolds,  J.K.   File  Transfer
            Protocol.      October,   1985,   USC/Information   Sciences
            Institute, RFC-959.

            [RFC-1049]   Sirbu,  M.A.   Content-Type  header  field  for
            Internet messages.  March, 1988, CMU,  RFC-1049.

            [RFC-1113]   Linn,  J.   Privacy  enhancement  for  Internet
            electronic    mail:  Part    I  -  message  encipherment and
            authentication procedures.   August,  1989, IAB Privacy Task
            Force, RFC-1113.

            [RFC-1154]  Robinson, D.; Ullmann, R.  Encoding header field
            for   Internet   messages.  April,   1990,   Prime Computer,
            Inc., RFC-1154.

            [RFC-1342] Moore, Keith, Representation of Non-Ascii Text in
            Internet   Message   Headers.   June,  1992,  University  of
            Tennessee, RFC-1342.

            Security Considerations

            Security issues  are  discussed  in  Section  7.4.2  and  in
            Appendix  G.   Implementors should pay special attention  to
            the security implications of any mail content-types that can
            cause the remote execution of any actions in the recipient's
            environment.   In  such  cases,  the   discussion   of   the
            applicaton/postscript   content-type  in  Section  7.4.2 may
            serve as a model for considering  other  content-types  with
            remote execution capabilities.




















            Borenstein & Freed                                 [Page 76]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992


            Authors' Addresses

            For more information, the authors of this  document  may  be
            contacted via Internet mail:

                                Nathaniel S. Borenstein
                                 MRE 2D-296, Bellcore
                                     445 South St.
                               Morristown, NJ 07962-1910

                                Phone: +1 201 829 4270
                                 Fax:  +1 201 829 7019
                                Email: nsb@bellcore.com


                                       Ned Freed
                             Innosoft International, Inc.
                                 250 West First Street
                                       Suite 240
                                  Claremont, CA 91711

                                Phone:  +1 714 624 7907
                                 Fax: +1 714 621 5319
                                Email: ned@innosoft.com

































            Borenstein & Freed                                 [Page 77]




            RFC 1341MIME: Multipurpose Internet Mail ExtensionsJune 1992





            THIS PAGE INTENTIONALLY LEFT BLANK.

            Please discard this page and place the  following  table  of
            contents after the title page.


















































            Borenstein & Freed                                  [Page i]








                               Table of Contents


            1     Introduction.......................................  1
            2     Notations, Conventions, and Generic BNF Grammar....  3
            3     The MIME-Version Header Field......................  5
            4     The Content-Type Header Field......................  6
            5     The Content-Transfer-Encoding Header Field......... 10
            5.1   Quoted-Printable Content-Transfer-Encoding......... 14
            5.2   Base64 Content-Transfer-Encoding................... 17
            6     Additional Optional Content- Header Fields......... 19
            6.1   Optional Content-ID Header Field................... 19
            6.2   Optional Content-Description Header Field.......... 19
            7     The Predefined Content-Type Values................. 20
            7.1   The Text Content-Type.............................. 20
            7.1.1 The charset parameter.............................. 20
            7.1.2 The Text/plain subtype............................. 23
            7.1.3 The Text/richtext subtype.......................... 23
            7.2   The Multipart Content-Type......................... 29
            7.2.1 Multipart:  The common syntax...................... 30
            7.2.2 The Multipart/mixed (primary) subtype.............. 34
            7.2.3 The Multipart/alternative subtype.................. 34
            7.2.4 The Multipart/digest subtype....................... 36
            7.2.5 The Multipart/parallel subtype..................... 36
            7.3   The Message Content-Type........................... 37
            7.3.1 The Message/rfc822 (primary) subtype............... 37
            7.3.2 The Message/Partial subtype........................ 37
            7.3.3 The Message/External-Body subtype.................. 40
            7.4   The Application Content-Type....................... 46
            7.4.1 The Application/Octet-Stream (primary) subtype..... 46
            7.4.2 The Application/PostScript subtype................. 47
            7.4.3 The Application/ODA subtype........................ 50
            7.5   The Image Content-Type............................. 51
            7.6   The Audio Content-Type............................. 51
            7.7   The Video Content-Type............................. 51
            7.8   Experimental Content-Type Values................... 51
                  Summary............................................ 53
                  Acknowledgements................................... 54
                  Appendix A -- Minimal MIME-Conformance............. 56
                  Appendix B -- General Guidelines For Sending Email Data59
                  Appendix C -- A Complex Multipart Example.......... 62
                  Appendix D -- A Simple Richtext-to-Text Translator in C64
                  Appendix E -- Collected Grammar.................... 66
                  Appendix F -- IANA Registration Procedures......... 68
                  F.1  Registration of New Content-type/subtype Values..68
                  F.2  Registration of New Character Set Values...... 69
                  F.3  Registration of New Access-type Values for Message/external-body69
                  F.4  Registration of New Conversions Values for Application69
                  Appendix G -- Summary of the Seven Content-types... 71
                  Appendix H -- Canonical Encoding Model............. 73
                  References......................................... 75
                  Security Considerations............................ 76
                  Authors' Addresses................................. 77



            Borenstein & Freed                                 [Page ii]
































































            Borenstein & Freed                                [Page iii]



================================================
FILE: doc/notes/rfc/rfc1521.txt
================================================






Network Working Group                                      N. Borenstein
Request for Comments: 1521                                      Bellcore
Obsoletes: 1341                                                 N. Freed
Category: Standards Track                                       Innosoft
                                                          September 1993


         MIME (Multipurpose Internet Mail Extensions) Part One:
                Mechanisms for Specifying and Describing
                 the Format of Internet Message Bodies

Status of this Memo

   This RFC specifies an Internet standards track protocol for the
   Internet community, and requests discussion and suggestions for
   improvements.  Please refer to the current edition of the "Internet
   Official Protocol Standards" for the standardization state and status
   of this protocol.  Distribution of this memo is unlimited.

Abstract

   STD 11, RFC 822 defines a message representation protocol which
   specifies considerable detail about message headers, but which leaves
   the message content, or message body, as flat ASCII text.  This
   document redefines the format of message bodies to allow multi-part
   textual and non-textual message bodies to be represented and
   exchanged without loss of information.  This is based on earlier work
   documented in RFC 934 and STD 11, RFC 1049, but extends and revises
   that work.  Because RFC 822 said so little about message bodies, this
   document is largely orthogonal to (rather than a revision of) RFC
   822.

   In particular, this document is designed to provide facilities to
   include multiple objects in a single message, to represent body text
   in character sets other than US-ASCII, to represent formatted multi-
   font text messages, to represent non-textual material such as images
   and audio fragments, and generally to facilitate later extensions
   defining new types of Internet mail for use by cooperating mail
   agents.

   This document does NOT extend Internet mail header fields to permit
   anything other than US-ASCII text data.  Such extensions are the
   subject of a companion document [RFC-1522].

   This document is a revision of RFC 1341.  Significant differences
   from RFC 1341 are summarized in Appendix H.





Borenstein & Freed                                              [Page 1]

RFC 1521                          MIME                    September 1993


Table of Contents

   1.     Introduction.......................................  3
   2.     Notations, Conventions, and Generic BNF Grammar....  6
   3.     The MIME-Version Header Field......................  7
   4.     The Content-Type Header Field......................  9
   5.     The Content-Transfer-Encoding Header Field......... 13
   5.1.   Quoted-Printable Content-Transfer-Encoding......... 18
   5.2.   Base64 Content-Transfer-Encoding................... 21
   6.     Additional Content-Header Fields................... 23
   6.1.   Optional Content-ID Header Field................... 23
   6.2.   Optional Content-Description Header Field.......... 24
   7.     The Predefined Content-Type Values................. 24
   7.1.   The Text Content-Type.............................. 24
   7.1.1. The charset parameter.............................. 25
   7.1.2. The Text/plain subtype............................. 28
   7.2.   The Multipart Content-Type......................... 28
   7.2.1. Multipart:  The common syntax...................... 29
   7.2.2. The Multipart/mixed (primary) subtype.............. 34
   7.2.3. The Multipart/alternative subtype.................. 34
   7.2.4. The Multipart/digest subtype....................... 36
   7.2.5. The Multipart/parallel subtype..................... 37
   7.2.6. Other Multipart subtypes........................... 37
   7.3.   The Message Content-Type........................... 38
   7.3.1. The Message/rfc822 (primary) subtype............... 38
   7.3.2. The Message/Partial subtype........................ 39
   7.3.3. The Message/External-Body subtype.................. 42
   7.3.3.1.  The "ftp" and "tftp" access-types............... 44
   7.3.3.2.  The "anon-ftp" access-type...................... 45
   7.3.3.3.  The "local-file" and "afs" access-types......... 45
   7.3.3.4.  The "mail-server" access-type................... 45
   7.3.3.5.  Examples and Further Explanations............... 46
   7.4.   The Application Content-Type....................... 49
   7.4.1. The Application/Octet-Stream (primary) subtype..... 50
   7.4.2. The Application/PostScript subtype................. 50
   7.4.3. Other Application subtypes......................... 53
   7.5.   The Image Content-Type............................. 53
   7.6.   The Audio Content-Type............................. 54
   7.7.   The Video Content-Type............................. 54
   7.8.   Experimental Content-Type Values................... 54
   8.     Summary............................................ 56
   9.     Security Considerations............................ 56
   10.    Authors' Addresses................................. 57
   11.    Acknowledgements................................... 58
   Appendix A -- Minimal MIME-Conformance.................... 60
   Appendix B -- General Guidelines For Sending Email Data... 63
   Appendix C -- A Complex Multipart Example................. 66
   Appendix D -- Collected Grammar........................... 68



Borenstein & Freed                                              [Page 2]

RFC 1521                          MIME                    September 1993


   Appendix E -- IANA Registration Procedures................ 72
   E.1  Registration of New Content-type/subtype Values...... 72
   E.2  Registration of New Access-type Values
        for Message/external-body............................ 73
   Appendix F -- Summary of the Seven Content-types.......... 74
   Appendix G -- Canonical Encoding Model.................... 76
   Appendix H -- Changes from RFC 1341....................... 78
   References................................................ 80

1.    Introduction

   Since its publication in 1982, STD 11, RFC 822 [RFC-822] has defined
   the standard format of textual mail messages on the Internet.  Its
   success has been such that the RFC 822 format has been adopted,
   wholly or partially, well beyond the confines of the Internet and the
   Internet SMTP transport defined by STD 10, RFC 821 [RFC-821].  As the
   format has seen wider use, a number of limitations have proven
   increasingly restrictive for the user community.

   RFC 822 was intended to specify a format for text messages.  As such,
   non-text messages, such as multimedia messages that might include
   audio or images, are simply not mentioned.  Even in the case of text,
   however, RFC 822 is inadequate for the needs of mail users whose
   languages require the use of character sets richer than US ASCII
   [US-ASCII]. Since RFC 822 does not specify mechanisms for mail
   containing audio, video, Asian language text, or even text in most
   European languages, additional specifications are needed.

   One of the notable limitations of RFC 821/822 based mail systems is
   the fact that they limit the contents of electronic mail messages to
   relatively short lines of seven-bit ASCII.  This forces users to
   convert any non-textual data that they may wish to send into seven-
   bit bytes representable as printable ASCII characters before invoking
   a local mail UA (User Agent, a program with which human users send
   and receive mail). Examples of such encodings currently used in the
   Internet include pure hexadecimal, uuencode, the 3-in-4 base 64
   scheme specified in RFC 1421, the Andrew Toolkit Representation
   [ATK], and many others.

   The limitations of RFC 822 mail become even more apparent as gateways
   are designed to allow for the exchange of mail messages between RFC
   822 hosts and X.400 hosts. X.400 [X400] specifies mechanisms for the
   inclusion of non-textual body parts within electronic mail messages.
   The current standards for the mapping of X.400 messages to RFC 822
   messages specify either that X.400 non-textual body parts must be
   converted to (not encoded in) an ASCII format, or that they must be
   discarded, notifying the RFC 822 user that discarding has occurred.
   This is clearly undesirable, as information that a user may wish to



Borenstein & Freed                                              [Page 3]

RFC 1521                          MIME                    September 1993


   receive is lost.  Even though a user's UA may not have the capability
   of dealing with the non-textual body part, the user might have some
   mechanism external to the UA that can extract useful information from
   the body part.  Moreover, it does not allow for the fact that the
   message may eventually be gatewayed back into an X.400 message
   handling system (i.e., the X.400 message is "tunneled" through
   Internet mail), where the non-textual information would definitely
   become useful again.

   This document describes several mechanisms that combine to solve most
   of these problems without introducing any serious incompatibilities
   with the existing world of RFC 822 mail.  In particular, it
   describes:

   1. A MIME-Version header field, which uses a version number to
       declare a message to be conformant with this specification and
       allows mail processing agents to distinguish between such
       messages and those generated by older or non-conformant software,
       which is presumed to lack such a field.

   2. A Content-Type header field, generalized from RFC 1049 [RFC-1049],
       which can be used to specify the type and subtype of data in the
       body of a message and to fully specify the native representation
       (encoding) of such data.

       2.a. A "text" Content-Type value, which can be used to represent
            textual information in a number of character sets and
            formatted text description languages in a standardized
            manner.

       2.b. A "multipart" Content-Type value, which can be used to
            combine several body parts, possibly of differing types of
            data, into a single message.

       2.c. An "application" Content-Type value, which can be used to
            transmit application data or binary data, and hence, among
            other uses, to implement an electronic mail file transfer
            service.

       2.d. A "message" Content-Type value, for encapsulating another
            mail message.

       2.e An "image" Content-Type value, for transmitting still image
            (picture) data.

       2.f. An "audio" Content-Type value, for transmitting audio or
            voice data.




Borenstein & Freed                                              [Page 4]

RFC 1521                          MIME                    September 1993


       2.g. A "video" Content-Type value, for transmitting video or
            moving image data, possibly with audio as part of the
            composite video data format.

   3. A Content-Transfer-Encoding header field, which can be used to
       specify an auxiliary encoding that was applied to the data in
       order to allow it to pass through mail transport mechanisms which
       may have data or character set limitations.

   4. Two additional header fields that can be used to further describe
       the data in a message body, the Content-ID and Content-
       Description header fields.

   MIME has been carefully designed as an extensible mechanism, and it
   is expected that the set of content-type/subtype pairs and their
   associated parameters will grow significantly with time.  Several
   other MIME fields, notably including character set names, are likely
   to have new values defined over time.  In order to ensure that the
   set of such values is developed in an orderly, well-specified, and
   public manner, MIME defines a registration process which uses the
   Internet Assigned Numbers Authority (IANA) as a central registry for
   such values.  Appendix E provides details about how IANA registration
   is accomplished.

   Finally, to specify and promote interoperability, Appendix A of this
   document provides a basic applicability statement for a subset of the
   above mechanisms that defines a minimal level of "conformance" with
   this document.

      HISTORICAL NOTE: Several of the mechanisms described in this
      document may seem somewhat strange or even baroque at first
      reading.  It is important to note that compatibility with existing
      standards AND robustness across existing practice were two of the
      highest priorities of the working group that developed this
      document.  In particular, compatibility was always favored over
      elegance.

   MIME was first defined and published as RFCs 1341 and 1342 [RFC-1341]
   [RFC-1342].  This document is a relatively minor updating of RFC
   1341, and is intended to supersede it.  The differences between this
   document and RFC 1341 are summarized in Appendix H.  Please refer to
   the current edition of the "IAB Official Protocol Standards" for the
   standardization state and status of this protocol.  Several other RFC
   documents will be of interest to the MIME implementor, in particular
   [RFC 1343], [RFC-1344], and [RFC-1345].






Borenstein & Freed                                              [Page 5]

RFC 1521                          MIME                    September 1993


2.    Notations, Conventions, and Generic BNF Grammar

   This document is being published in two versions, one as plain ASCII
   text and one as PostScript (PostScript is a trademark of Adobe
   Systems Incorporated.).  While the text version is the official
   specification, some will find the PostScript version easier to read.
   The textual contents are identical.  An Andrew-format copy of this
   document is also available from the first author (Borenstein).

   Although the mechanisms specified in this document are all described
   in prose, most are also described formally in the modified BNF
   notation of RFC 822.  Implementors will need to be familiar with this
   notation in order to understand this specification, and are referred
   to RFC 822 for a complete explanation of the modified BNF notation.

   Some of the modified BNF in this document makes reference to
   syntactic entities that are defined in RFC 822 and not in this
   document.  A complete formal grammar, then, is obtained by combining
   the collected grammar appendix of this document with that of RFC 822
   plus the modifications to RFC 822 defined in RFC 1123, which
   specifically changes the syntax for `return', `date' and `mailbox'.

   The term CRLF, in this document, refers to the sequence of the two
   ASCII characters CR (13) and LF (10) which, taken together, in this
   order, denote a line break in RFC 822 mail.

   The term "character set" is used in this document to refer to a
   method used with one or more tables to convert encoded text to a
   series of octets.  This definition is intended to allow various kinds
   of text encodings, from simple single-table mappings such as ASCII to
   complex table switching methods such as those that use ISO 2022's
   techniques.  However, a MIME character set name must fully specify
   the mapping to be performed.

   The term "message", when not further qualified, means either the
   (complete or "top-level") message being transferred on a network, or
   a message encapsulated in a body of type "message".

   The term "body part", in this document, means one of the parts of the
   body of a multipart entity. A body part has a header and a body, so
   it makes sense to speak about the body of a body part.

   The term "entity", in this document, means either a message or a body
   part.  All kinds of entities share the property that they have a
   header and a body.

   The term "body", when not further qualified, means the body of an
   entity, that is the body of either a message or of a body part.



Borenstein & Freed                                              [Page 6]

RFC 1521                          MIME                    September 1993


      NOTE: The previous four definitions are clearly circular.  This is
      unavoidable, since the overall structure of a MIME message is
      indeed recursive.

   In this document, all numeric and octet values are given in decimal
   notation.

   It must be noted that Content-Type values, subtypes, and parameter
   names as defined in this document are case-insensitive.  However,
   parameter values are case-sensitive unless otherwise specified for
   the specific parameter.

      FORMATTING NOTE: This document has been carefully formatted for
      ease of reading.  The PostScript version of this document, in
      particular, places notes like this one, which may be skipped by
      the reader, in a smaller, italicized, font, and indents it as
      well.  In the text version, only the indentation is preserved, so
      if you are reading the text version of this you might consider
      using the PostScript version instead. However, all such notes will
      be indented and preceded by "NOTE:" or some similar introduction,
      even in the text version.

      The primary purpose of these non-essential notes is to convey
      information about the rationale of this document, or to place this
      document in the proper historical or evolutionary context.  Such
      information may be skipped by those who are focused entirely on
      building a conformant implementation, but may be of use to those
      who wish to understand why this document is written as it is.

      For ease of recognition, all BNF definitions have been placed in a
      fixed-width font in the PostScript version of this document.

3.    The MIME-Version Header Field

   Since RFC 822 was published in 1982, there has really been only one
   format standard for Internet messages, and there has been little
   perceived need to declare the format standard in use.  This document
   is an independent document that complements RFC 822. Although the
   extensions in this document have been defined in such a way as to be
   compatible with RFC 822, there are still circumstances in which it
   might be desirable for a mail-processing agent to know whether a
   message was composed with the new standard in mind.

   Therefore, this document defines a new header field, "MIME-Version",
   which is to be used to declare the version of the Internet message
   body format standard in use.

   Messages composed in accordance with this document MUST include such



Borenstein & Freed                                              [Page 7]

RFC 1521                          MIME                    September 1993


   a header field, with the following verbatim text:

   MIME-Version: 1.0

   The presence of this header field is an assertion that the message
   has been composed in compliance with this document.

   Since it is possible that a future document might extend the message
   format standard again, a formal BNF is given for the content of the
   MIME-Version field:

   version := "MIME-Version" ":" 1*DIGIT "." 1*DIGIT

   Thus, future format specifiers, which might replace or extend "1.0",
   are constrained to be two integer fields, separated by a period.  If
   a message is received with a MIME-version value other than "1.0", it
   cannot be assumed to conform with this specification.

   Note that the MIME-Version header field is required at the top level
   of a message. It is not required for each body part of a multipart
   entity.  It is required for the embedded headers of a body of type
   "message" if and only if the embedded message is itself claimed to be
   MIME-conformant.

   It is not possible to fully specify how a mail reader that conforms
   with MIME as defined in this document should treat a message that
   might arrive in the future with some value of MIME-Version other than
   "1.0".  However, conformant software is encouraged to check the
   version number and at least warn the user if an unrecognized MIME-
   version is encountered.

   It is also worth noting that version control for specific content-
   types is not accomplished using the MIME-Version mechanism.  In
   particular, some formats (such as application/postscript) have
   version numbering conventions that are internal to the document
   format.  Where such conventions exist, MIME does nothing to supersede
   them.  Where no such conventions exist, a MIME type might use a
   "version" parameter in the content-type field if necessary.

   NOTE TO IMPLEMENTORS: All header fields defined in this document,
   including MIME-Version, Content-type, etc., are subject to the
   general syntactic rules for header fields specified in RFC 822.  In
   particular, all can include comments, which means that the following
   two MIME-Version fields are equivalent:

                    MIME-Version: 1.0
                    MIME-Version: 1.0 (Generated by GBD-killer 3.7)




Borenstein & Freed                                              [Page 8]

RFC 1521                          MIME                    September 1993


4.    The Content-Type Header Field

   The purpose of the Content-Type field is to describe the data
   contained in the body fully enough that the receiving user agent can
   pick an appropriate agent or mechanism to present the data to the
   user, or otherwise deal with the data in an appropriate manner.

   HISTORICAL NOTE: The Content-Type header field was first defined in
   RFC 1049.  RFC 1049 Content-types used a simpler and less powerful
   syntax, but one that is largely compatible with the mechanism given
   here.

   The Content-Type header field is used to specify the nature of the
   data in the body of an entity, by giving type and subtype
   identifiers, and by providing auxiliary information that may be
   required for certain types.  After the type and subtype names, the
   remainder of the header field is simply a set of parameters,
   specified in an attribute/value notation.  The set of meaningful
   parameters differs for the different types.  In particular, there are
   NO globally-meaningful parameters that apply to all content-types.
   Global mechanisms are best addressed, in the MIME model, by the
   definition of additional Content-* header fields.  The ordering of
   parameters is not significant.  Among the defined parameters is a
   "charset" parameter by which the character set used in the body may
   be declared. Comments are allowed in accordance with RFC 822 rules
   for structured header fields.

   In general, the top-level Content-Type is used to declare the general
   type of data, while the subtype specifies a specific format for that
   type of data.  Thus, a Content-Type of "image/xyz" is enough to tell
   a user agent that the data is an image, even if the user agent has no
   knowledge of the specific image format "xyz".  Such information can
   be used, for example, to decide whether or not to show a user the raw
   data from an unrecognized subtype -- such an action might be
   reasonable for unrecognized subtypes of text, but not for
   unrecognized subtypes of image or audio.  For this reason, registered
   subtypes of audio, image, text, and video, should not contain
   embedded information that is really of a different type.  Such
   compound types should be represented using the "multipart" or
   "application" types.

   Parameters are modifiers of the content-subtype, and do not
   fundamentally affect the requirements of the host system.  Although
   most parameters make sense only with certain content-types, others
   are "global" in the sense that they might apply to any subtype.  For
   example, the "boundary" parameter makes sense only for the
   "multipart" content-type, but the "charset" parameter might make
   sense with several content-types.



Borenstein & Freed                                              [Page 9]

RFC 1521                          MIME                    September 1993


   An initial set of seven Content-Types is defined by this document.
   This set of top-level names is intended to be substantially complete.
   It is expected that additions to the larger set of supported types
   can generally be accomplished by the creation of new subtypes of
   these initial types.  In the future, more top-level types may be
   defined only by an extension to this standard.  If another primary
   type is to be used for any reason, it must be given a name starting
   with "X-" to indicate its non-standard status and to avoid a
   potential conflict with a future official name.

   In the Augmented BNF notation of RFC 822, a Content-Type header field
   value is defined as follows:

     content  :=   "Content-Type"  ":"  type  "/"  subtype  *(";"
     parameter)
               ; case-insensitive matching of type and subtype

     type :=          "application"     / "audio"
               / "image"           / "message"
               / "multipart"  / "text"
               / "video"           / extension-token
               ; All values case-insensitive

     extension-token :=  x-token / iana-token

     iana-token := <a publicly-defined extension token,
               registered with IANA, as specified in
               appendix E>

     x-token := <The two characters "X-" or "x-" followed, with
                 no intervening white space, by any token>

     subtype := token ; case-insensitive

     parameter := attribute "=" value

     attribute := token   ; case-insensitive

     value := token / quoted-string

     token  :=  1*<any (ASCII) CHAR except SPACE, CTLs,
                   or tspecials>

     tspecials :=  "(" / ")" / "<" / ">" / "@"
                /  "," / ";" / ":" / "\" / <">
                /  "/" / "[" / "]" / "?" / "="
               ; Must be in quoted-string,
               ; to use within parameter values



Borenstein & Freed                                             [Page 10]

RFC 1521                          MIME                    September 1993


   Note that the definition of "tspecials" is the same as the RFC 822
   definition of "specials" with the addition of the three characters
   "/", "?", and "=", and the removal of ".".

   Note also that a subtype specification is MANDATORY.  There are no
   default subtypes.

   The type, subtype, and parameter names are not case sensitive.  For
   example, TEXT, Text, and TeXt are all equivalent.  Parameter values
   are normally case sensitive, but certain parameters are interpreted
   to be case-insensitive, depending on the intended use.  (For example,
   multipart boundaries are case-sensitive, but the "access-type" for
   message/External-body is not case-sensitive.)

   Beyond this syntax, the only constraint on the definition of subtype
   names is the desire that their uses must not conflict.  That is, it
   would be undesirable to have two different communities using
   "Content-Type: application/foobar" to mean two different things.  The
   process of defining new content-subtypes, then, is not intended to be
   a mechanism for imposing restrictions, but simply a mechanism for
   publicizing the usages. There are, therefore, two acceptable
   mechanisms for defining new Content-Type subtypes:

            1.  Private values (starting with "X-") may be
                defined bilaterally between two cooperating
                agents without outside registration or
                standardization.

            2.  New standard values must be documented,
                registered with, and approved by IANA, as
                described in Appendix E.  Where intended for
                public use, the formats they refer to must
                also be defined by a published specification,
                and possibly offered for standardization.

   The seven standard initial predefined Content-Types are detailed in
   the bulk of this document.  They are:

    text -- textual information.  The primary subtype,
         "plain", indicates plain (unformatted) text.  No
         special software is required to get the full
         meaning of the text, aside from support for the
         indicated character set.  Subtypes are to be used
         for enriched text in forms where application
         software may enhance the appearance of the text,
         but such software must not be required in order to
         get the general idea of the content.  Possible
         subtypes thus include any readable word processor



Borenstein & Freed                                             [Page 11]

RFC 1521                          MIME                    September 1993


         format.  A very simple and portable subtype,
         richtext, was defined in RFC 1341, with a future
         revision expected.

    multipart -- data consisting of multiple parts of
         independent data types.  Four initial subtypes
         are defined, including the primary "mixed"
         subtype, "alternative" for representing the same
         data in multiple formats, "parallel" for parts
         intended to be viewed simultaneously, and "digest"
         for multipart entities in which each part is of
         type "message".

    message -- an encapsulated message.  A body of
         Content-Type "message" is itself all or part of a
         fully formatted RFC 822 conformant message which
         may contain its own different Content-Type header
         field.  The primary subtype is "rfc822".  The
         "partial" subtype is defined for partial messages,
         to permit the fragmented transmission of bodies
         that are thought to be too large to be passed
         through mail transport facilities.  Another
         subtype, "External-body", is defined for
         specifying large bodies by reference to an
         external data source.

    image -- image data.  Image requires a display device
         (such as a graphical display, a printer, or a FAX
         machine) to view the information.  Initial
         subtypes are defined for two widely-used image
         formats, jpeg and gif.

    audio -- audio data, with initial subtype "basic".
         Audio requires an audio output device (such as a
         speaker or a telephone) to "display" the contents.

    video -- video data.  Video requires the capability to
         display moving images, typically including
         specialized hardware and software.  The initial
         subtype is "mpeg".

    application -- some other kind of data, typically
         either uninterpreted binary data or information to
         be processed by a mail-based application.  The
         primary subtype, "octet-stream", is to be used in
         the case of uninterpreted binary data, in which
         case the simplest recommended action is to offer
         to write the information into a file for the user.



Borenstein & Freed                                             [Page 12]

RFC 1521                          MIME                    September 1993


         An additional subtype, "PostScript", is defined
         for transporting PostScript documents in bodies.
         Other expected uses for "application" include
         spreadsheets, data for mail-based scheduling
         systems, and languages for "active"
         (computational) email.  (Note that active email
         and other application data may entail several
         security considerations, which are discussed later
         in this memo, particularly in the context of
         application/PostScript.)

   Default RFC 822 messages are typed by this protocol as plain text in
   the US-ASCII character set, which can be explicitly specified as
   "Content-type: text/plain; charset=us-ascii".  If no Content-Type is
   specified, this default is assumed.  In the presence of a MIME-
   Version header field, a receiving User Agent can also assume that
   plain US-ASCII text was the sender's intent.  In the absence of a
   MIME-Version specification, plain US-ASCII text must still be
   assumed, but the sender's intent might have been otherwise.

      RATIONALE: In the absence of any Content-Type header field or
      MIME-Version header field, it is impossible to be certain that a
      message is actually text in the US-ASCII character set, since it
      might well be a message that, using the conventions that predate
      this document, includes text in another character set or non-
      textual data in a manner that cannot be automatically recognized
      (e.g., a uuencoded compressed UNIX tar file).  Although there is
      no fully acceptable alternative to treating such untyped messages
      as "text/plain; charset=us-ascii", implementors should remain
      aware that if a message lacks both the MIME-Version and the
      Content-Type header fields, it may in practice contain almost
      anything.

   It should be noted that the list of Content-Type values given here
   may be augmented in time, via the mechanisms described above, and
   that the set of subtypes is expected to grow substantially.

   When a mail reader encounters mail with an unknown Content-type
   value, it should generally treat it as equivalent to
   "application/octet-stream", as described later in this document.

5.    The Content-Transfer-Encoding Header Field

   Many Content-Types which could usefully be transported via email are
   represented, in their "natural" format, as 8-bit character or binary
   data.  Such data cannot be transmitted over some transport protocols.
   For example, RFC 821 restricts mail messages to 7-bit US-ASCII data
   with lines no longer than 1000 characters.



Borenstein & Freed                                             [Page 13]

RFC 1521                          MIME                    September 1993


   It is necessary, therefore, to define a standard mechanism for re-
   encoding such data into a 7-bit short-line format.  This document
   specifies that such encodings will be indicated by a new "Content-
   Transfer-Encoding" header field.  The Content-Transfer-Encoding field
   is used to indicate the type of transformation that has been used in
   order to represent the body in an acceptable manner for transport.

   Unlike Content-Types, a proliferation of Content-Transfer-Encoding
   values is undesirable and unnecessary.  However, establishing only a
   single Content-Transfer-Encoding mechanism does not seem possible.
   There is a tradeoff between the desire for a compact and efficient
   encoding of largely-binary data and the desire for a readable
   encoding of data that is mostly, but not entirely, 7-bit data.  For
   this reason, at least two encoding mechanisms are necessary: a
   "readable" encoding and a "dense" encoding.

   The Content-Transfer-Encoding field is designed to specify an
   invertible mapping between the "native" representation of a type of
   data and a representation that can be readily exchanged using 7 bit
   mail transport protocols, such as those defined by RFC 821 (SMTP).
   This field has not been defined by any previous standard. The field's
   value is a single token specifying the type of encoding, as
   enumerated below.  Formally:

   encoding := "Content-Transfer-Encoding" ":" mechanism

   mechanism :=     "7bit"  ;  case-insensitive
                  / "quoted-printable"
                  / "base64"
                  / "8bit"
                  / "binary"
                  / x-token

   These values are not case sensitive.  That is, Base64 and BASE64 and
   bAsE64 are all equivalent.  An encoding type of 7BIT requires that
   the body is already in a seven-bit mail-ready representation.  This
   is the default value -- that is, "Content-Transfer-Encoding: 7BIT" is
   assumed if the Content-Transfer-Encoding header field is not present.

   The values "8bit", "7bit", and "binary" all mean that NO encoding has
   been performed. However, they are potentially useful as indications
   of the kind of data contained in the object, and therefore of the
   kind of encoding that might need to be performed for transmission in
   a given transport system.  In particular:

       "7bit" means that the data is all represented as short
            lines of US-ASCII data.




Borenstein & Freed                                             [Page 14]

RFC 1521                          MIME                    September 1993


       "8bit" means that the lines are short, but there may be
            non-ASCII characters (octets with the high-order
            bit set).

       "Binary" means that not only may non-ASCII characters
            be present, but also that the lines are not
            necessarily short enough for SMTP transport.

   The difference between "8bit" (or any other conceivable bit-width
   token) and the "binary" token is that "binary" does not require
   adherence to any limits on line length or to the SMTP CRLF semantics,
   while the bit-width tokens do require such adherence.  If the body
   contains data in any bit-width other than 7-bit, the appropriate
   bit-width Content-Transfer-Encoding token must be used (e.g., "8bit"
   for unencoded 8 bit wide data).  If the body contains binary data,
   the "binary" Content-Transfer-Encoding token must be used.

      NOTE: The distinction between the Content-Transfer-Encoding values
      of "binary", "8bit", etc.  may seem unimportant, in that all of
      them really mean "none" -- that is, there has been no encoding of
      the data for transport.  However, clear labeling will be of
      enormous value to gateways between future mail transport systems
      with differing capabilities in transporting data that do not meet
      the restrictions of RFC 821 transport.

      Mail transport for unencoded 8-bit data is defined in RFC-1426
      [RFC-1426].  As of the publication of this document, there are no
      standardized Internet mail transports for which it is legitimate
      to include unencoded binary data in mail bodies.  Thus there are
      no circumstances in which the "binary" Content-Transfer-Encoding
      is actually legal on the Internet.  However, in the event that
      binary mail transport becomes a reality in Internet mail, or when
      this document is used in conjunction with any other binary-capable
      transport mechanism, binary bodies should be labeled as such using
      this mechanism.

      NOTE: The five values defined for the Content-Transfer-Encoding
      field imply nothing about the Content-Type other than the
      algorithm by which it was encoded or the transport system
      requirements if unencoded.

   Implementors may, if necessary, define new Content-Transfer-Encoding
   values, but must use an x-token, which is a name prefixed by "X-" to
   indicate its non-standard status, e.g., "Content-Transfer-Encoding:
   x-my-new-encoding".  However, unlike Content-Types and subtypes, the
   creation of new Content-Transfer-Encoding values is explicitly and
   strongly discouraged, as it seems likely to hinder interoperability
   with little potential benefit.  Their use is allowed only as the



Borenstein & Freed                                             [Page 15]

RFC 1521                          MIME                    September 1993


   result of an agreement between cooperating user agents.

   If a Content-Transfer-Encoding header field appears as part of a
   message header, it applies to the entire body of that message.  If a
   Content-Transfer-Encoding header field appears as part of a body
   part's headers, it applies only to the body of that body part.  If an
   entity is of type "multipart" or "message", the Content-Transfer-
   Encoding is not permitted to have any value other than a bit width
   (e.g., "7bit", "8bit", etc.) or "binary".

   It should be noted that email is character-oriented, so that the
   mechanisms described here are mechanisms for encoding arbitrary octet
   streams, not bit streams.  If a bit stream is to be encoded via one
   of these mechanisms, it must first be converted to an 8-bit byte
   stream using the network standard bit order ("big-endian"), in which
   the earlier bits in a stream become the higher-order bits in a byte.
   A bit stream not ending at an 8-bit boundary must be padded with
   zeroes.  This document provides a mechanism for noting the addition
   of such padding in the case of the application Content-Type, which
   has a "padding" parameter.

   The encoding mechanisms defined here explicitly encode all data in
   ASCII.  Thus, for example, suppose an entity has header fields such
   as:

        Content-Type: text/plain; charset=ISO-8859-1
        Content-transfer-encoding: base64

   This must be interpreted to mean that the body is a base64 ASCII
   encoding of data that was originally in ISO-8859-1, and will be in
   that character set again after decoding.

   The following sections will define the two standard encoding
   mechanisms.  The definition of new content-transfer-encodings is
   explicitly discouraged and should only occur when absolutely
   necessary.  All content-transfer-encoding namespace except that
   beginning with "X-" is explicitly reserved to the IANA for future
   use.  Private agreements about content-transfer-encodings are also
   explicitly discouraged.

   Certain Content-Transfer-Encoding values may only be used on certain
   Content-Types.  In particular, it is expressly forbidden to use any
   encodings other than "7bit", "8bit", or "binary" with any Content-
   Type that recursively includes other Content-Type fields, notably the
   "multipart" and "message" Content-Types.  All encodings that are
   desired for bodies of type multipart or message must be done at the
   innermost level, by encoding the actual body that needs to be
   encoded.



Borenstein & Freed                                             [Page 16]

RFC 1521                          MIME                    September 1993


      NOTE ON ENCODING RESTRICTIONS: Though the prohibition against
      using content-transfer-encodings on data of type multipart or
      message may seem overly restrictive, it is necessary to prevent
      nested encodings, in which data are passed through an encoding
      algorithm multiple times, and must be decoded multiple times in
      order to be properly viewed.  Nested encodings add considerable
      complexity to user agents: aside from the obvious efficiency
      problems with such multiple encodings, they can obscure the basic
      structure of a message.  In particular, they can imply that
      several decoding operations are necessary simply to find out what
      types of objects a message contains.  Banning nested encodings may
      complicate the job of certain mail gateways, but this seems less
      of a problem than the effect of nested encodings on user agents.

      NOTE ON THE RELATIONSHIP BETWEEN CONTENT-TYPE AND CONTENT-
      TRANSFER-ENCODING: It may seem that the Content-Transfer-Encoding
      could be inferred from the characteristics of the Content-Type
      that is to be encoded, or, at the very least, that certain
      Content-Transfer-Encodings could be mandated for use with specific
      Content-Types. There are several reasons why this is not the case.
      First, given the varying types of transports used for mail, some
      encodings may be appropriate for some Content-Type/transport
      combinations and not for others.  (For example, in an 8-bit
      transport, no encoding would be required for text in certain
      character sets, while such encodings are clearly required for 7-
      bit SMTP.)  Second, certain Content-Types may require different
      types of transfer encoding under different circumstances. For
      example, many PostScript bodies might consist entirely of short
      lines of 7-bit data and hence require little or no encoding.
      Other PostScript bodies (especially those using Level 2
      PostScript's binary encoding mechanism) may only be reasonably
      represented using a binary transport encoding. Finally, since
      Content-Type is intended to be an open-ended specification
      mechanism, strict specification of an association between
      Content-Types and encodings effectively couples the specification
      of an application protocol with a specific lower-level transport.
      This is not desirable since the developers of a Content-Type
      should not have to be aware of all the transports in use and what
      their limitations are.

      NOTE ON TRANSLATING ENCODINGS: The quoted-printable and base64
      encodings are designed so that conversion between them is
      possible.  The only issue that arises in such a conversion is the
      handling of line breaks.  When converting from quoted-printable to
      base64 a line break must be converted into a CRLF sequence.
      Similarly, a CRLF sequence in base64 data must be converted to a
      quoted-printable line break, but ONLY when converting text data.




Borenstein & Freed                                             [Page 17]

RFC 1521                          MIME                    September 1993


      NOTE ON CANONICAL ENCODING MODEL: There was some confusion, in
      earlier drafts of this memo, regarding the model for when email
      data was to be converted to canonical form and encoded, and in
      particular how this process would affect the treatment of CRLFs,
      given that the representation of newlines varies greatly from
      system to system, and the relationship between content-transfer-
      encodings and character sets.  For this reason, a canonical model
      for encoding is presented as Appendix G.

5.1.  Quoted-Printable Content-Transfer-Encoding

   The Quoted-Printable encoding is intended to represent data that
   largely consists of octets that correspond to printable characters in
   the ASCII character set.  It encodes the data in such a way that the
   resulting octets are unlikely to be modified by mail transport.  If
   the data being encoded are mostly ASCII text, the encoded form of the
   data remains largely recognizable by humans.  A body which is
   entirely ASCII may also be encoded in Quoted-Printable to ensure the
   integrity of the data should the message pass through a character-
   translating, and/or line-wrapping gateway.

   In this encoding, octets are to be represented as determined by the
   following rules:

      Rule #1: (General 8-bit representation) Any octet, except those
      indicating a line break according to the newline convention of the
      canonical (standard) form of the data being encoded, may be
      represented by an "=" followed by a two digit hexadecimal
      representation of the octet's value.  The digits of the
      hexadecimal alphabet, for this purpose, are "0123456789ABCDEF".
      Uppercase letters must be used when sending hexadecimal data,
      though a robust implementation may choose to recognize lowercase
      letters on receipt.  Thus, for example, the value 12 (ASCII form
      feed) can be represented by "=0C", and the value 61 (ASCII EQUAL
      SIGN) can be represented by "=3D".  Except when the following
      rules allow an alternative encoding, this rule is mandatory.

      Rule #2: (Literal representation) Octets with decimal values of 33
      through 60 inclusive, and 62 through 126, inclusive, MAY be
      represented as the ASCII characters which correspond to those
      octets (EXCLAMATION POINT through LESS THAN, and GREATER THAN
      through TILDE, respectively).

      Rule #3: (White Space): Octets with values of 9 and 32 MAY be
      represented as ASCII TAB (HT) and SPACE characters, respectively,
      but MUST NOT be so represented at the end of an encoded line. Any
      TAB (HT) or SPACE characters on an encoded line MUST thus be
      followed on that line by a printable character.  In particular, an



Borenstein & Freed                                             [Page 18]

RFC 1521                          MIME                    September 1993


      "=" at the end of an encoded line, indicating a soft line break
      (see rule #5) may follow one or more TAB (HT) or SPACE characters.
      It follows that an octet with value 9 or 32 appearing at the end
      of an encoded line must be represented according to Rule #1.  This
      rule is necessary because some MTAs (Message Transport Agents,
      programs which transport messages from one user to another, or
      perform a part of such transfers) are known to pad lines of text
      with SPACEs, and others are known to remove "white space"
      characters from the end of a line.  Therefore, when decoding a
      Quoted-Printable body, any trailing white space on a line must be
      deleted, as it will necessarily have been added by intermediate
      transport agents.

      Rule #4 (Line Breaks): A line break in a text body, independent of
      what its representation is following the canonical representation
      of the data being encoded, must be represented by a (RFC 822) line
      break, which is a CRLF sequence, in the Quoted-Printable encoding.
      Since the canonical representation of types other than text do not
      generally include the representation of line breaks, no hard line
      breaks (i.e.  line breaks that are intended to be meaningful and
      to be displayed to the user) should occur in the quoted-printable
      encoding of such types.  Of course, occurrences of "=0D", "=0A",
      "0A=0D" and "=0D=0A" will eventually be encountered.  In general,
      however, base64 is preferred over quoted-printable for binary
      data.

      Note that many implementations may elect to encode the local
      representation of various content types directly, as described in
      Appendix G.  In particular, this may apply to plain text material
      on systems that use newline conventions other than CRLF
      delimiters. Such an implementation is permissible, but the
      generation of line breaks must be generalized to account for the
      case where alternate representations of newline sequences are
      used.

      Rule #5 (Soft Line Breaks): The Quoted-Printable encoding REQUIRES
      that encoded lines be no more than 76 characters long. If longer
      lines are to be encoded with the Quoted-Printable encoding, 'soft'
      line breaks must be used. An equal sign as the last character on a
      encoded line indicates such a non-significant ('soft') line break
      in the encoded text. Thus if the "raw" form of the line is a
      single unencoded line that says:

          Now's the time for all folk to come to the aid of
          their country.

      This can be represented, in the Quoted-Printable encoding, as




Borenstein & Freed                                             [Page 19]

RFC 1521                          MIME                    September 1993


          Now's the time =
          for all folk to come=
           to the aid of their country.

      This provides a mechanism with which long lines are encoded in
      such a way as to be restored by the user agent.  The 76 character
      limit does not count the trailing CRLF, but counts all other
      characters, including any equal signs.

   Since the hyphen character ("-") is represented as itself in the
   Quoted-Printable encoding, care must be taken, when encapsulating a
   quoted-printable encoded body in a multipart entity, to ensure that
   the encapsulation boundary does not appear anywhere in the encoded
   body.  (A good strategy is to choose a boundary that includes a
   character sequence such as "=_" which can never appear in a quoted-
   printable body.  See the definition of multipart messages later in
   this document.)

      NOTE: The quoted-printable encoding represents something of a
      compromise between readability and reliability in transport.
      Bodies encoded with the quoted-printable encoding will work
      reliably over most mail gateways, but may not work perfectly over
      a few gateways, notably those involving translation into EBCDIC.
      (In theory, an EBCDIC gateway could decode a quoted-printable body
      and re-encode it using base64, but such gateways do not yet
      exist.)  A higher level of confidence is offered by the base64
      Content-Transfer-Encoding.  A way to get reasonably reliable
      transport through EBCDIC gateways is to also quote the ASCII
      characters

             !"#$@[\]^`{|}~

      according to rule #1.  See Appendix B for more information.

   Because quoted-printable data is generally assumed to be line-
   oriented, it is to be expected that the representation of the breaks
   between the lines of quoted printable data may be altered in
   transport, in the same manner that plain text mail has always been
   altered in Internet mail when passing between systems with differing
   newline conventions.  If such alterations are likely to constitute a
   corruption of the data, it is probably more sensible to use the
   base64 encoding rather than the quoted-printable encoding.

   WARNING TO IMPLEMENTORS: If binary data are encoded in quoted-
   printable, care must be taken to encode CR and LF characters as "=0D"
   and "=0A", respectively.  In particular, a CRLF sequence in binary
   data should be encoded as "=0D=0A".  Otherwise, if CRLF were
   represented as a hard line break, it might be incorrectly decoded on



Borenstein & Freed                                             [Page 20]

RFC 1521                          MIME                    September 1993


   platforms with different line break conventions.

   For formalists, the syntax of quoted-printable data is described by
   the following grammar:

   quoted-printable := ([*(ptext / SPACE / TAB) ptext] ["="] CRLF)
        ; Maximum line length of 76 characters excluding CRLF

   ptext := octet /<any ASCII character except "=", SPACE, or TAB>
        ; characters not listed as "mail-safe" in Appendix B
        ; are also not recommended.

   octet := "=" 2(DIGIT / "A" / "B" / "C" / "D" / "E" / "F")
        ; octet must be used for characters > 127, =, SPACE, or TAB,
        ; and is recommended for any characters not listed in
        ; Appendix B as "mail-safe".

5.2.  Base64 Content-Transfer-Encoding

   The Base64 Content-Transfer-Encoding is designed to represent
   arbitrary sequences of octets in a form that need not be humanly
   readable.  The encoding and decoding algorithms are simple, but the
   encoded data are consistently only about 33 percent larger than the
   unencoded data.  This encoding is virtually identical to the one used
   in Privacy Enhanced Mail (PEM) applications, as defined in RFC 1421.
   The base64 encoding is adapted from RFC 1421, with one change: base64
   eliminates the "*" mechanism for embedded clear text.

   A 65-character subset of US-ASCII is used, enabling 6 bits to be
   represented per printable character. (The extra 65th character, "=",
   is used to signify a special processing function.)

      NOTE: This subset has the important property that it is
      represented identically in all versions of ISO 646, including US
      ASCII, and all characters in the subset are also represented
      identically in all versions of EBCDIC.  Other popular encodings,
      such as the encoding used by the uuencode utility and the base85
      encoding specified as part of Level 2 PostScript, do not share
      these properties, and thus do not fulfill the portability
      requirements a binary transport encoding for mail must meet.

   The encoding process represents 24-bit groups of input bits as output
   strings of 4 encoded characters. Proceeding from left to right, a
   24-bit input group is formed by concatenating 3 8-bit input groups.
   These 24 bits are then treated as 4 concatenated 6-bit groups, each
   of which is translated into a single digit in the base64 alphabet.
   When encoding a bit stream via the base64 encoding, the bit stream
   must be presumed to be ordered with the most-significant-bit first.



Borenstein & Freed                                             [Page 21]

RFC 1521                          MIME                    September 1993


   That is, the first bit in the stream will be the high-order bit in
   the first byte, and the eighth bit will be the low-order bit in the
   first byte, and so on.

   Each 6-bit group is used as an index into an array of 64 printable
   characters. The character referenced by the index is placed in the
   output string. These characters, identified in Table 1, below, are
   selected so as to be universally representable, and the set excludes
   characters with particular significance to SMTP (e.g., ".", CR, LF)
   and to the encapsulation boundaries defined in this document (e.g.,
   "-").

                            Table 1: The Base64 Alphabet

      Value Encoding  Value Encoding  Value Encoding  Value Encoding
           0 A            17 R            34 i            51 z
           1 B            18 S            35 j            52 0
           2 C            19 T            36 k            53 1
           3 D            20 U            37 l            54 2
           4 E            21 V            38 m            55 3
           5 F            22 W            39 n            56 4
           6 G            23 X            40 o            57 5
           7 H            24 Y            41 p            58 6
           8 I            25 Z            42 q            59 7
           9 J            26 a            43 r            60 8
          10 K            27 b            44 s            61 9
          11 L            28 c            45 t            62 +
          12 M            29 d            46 u            63 /
          13 N            30 e            47 v
          14 O            31 f            48 w         (pad) =
          15 P            32 g            49 x
          16 Q            33 h            50 y

   The output stream (encoded bytes) must be represented in lines of no
   more than 76 characters each.  All line breaks or other characters
   not found in Table 1 must be ignored by decoding software.  In base64
   data, characters other than those in Table 1, line breaks, and other
   white space probably indicate a transmission error, about which a
   warning message or even a message rejection might be appropriate
   under some circumstances.

   Special processing is performed if fewer than 24 bits are available
   at the end of the data being encoded.  A full encoding quantum is
   always completed at the end of a body.  When fewer than 24 input bits
   are available in an input group, zero bits are added (on the right)
   to form an integral number of 6-bit groups.  Padding at the end of
   the data is performed using the '=' character.  Since all base64
   input is an integral number of octets, only the following cases can



Borenstein & Freed                                             [Page 22]

RFC 1521                          MIME                    September 1993


   arise: (1) the final quantum of encoding input is an integral
   multiple of 24 bits; here, the final unit of encoded output will be
   an integral multiple of 4 characters with no "=" padding, (2) the
   final quantum of encoding input is exactly 8 bits; here, the final
   unit of encoded output will be two characters followed by two "="
   padding characters, or (3) the final quantum of encoding input is
   exactly 16 bits; here, the final unit of encoded output will be three
   characters followed by one "=" padding character.

   Because it is used only for padding at the end of the data, the
   occurrence of any '=' characters may be taken as evidence that the
   end of the data has been reached (without truncation in transit).  No
   such assurance is possible, however, when the number of octets
   transmitted was a multiple of three.

   Any characters outside of the base64 alphabet are to be ignored in
   base64-encoded data.  The same applies to any illegal sequence of
   characters in the base64 encoding, such as "====="

   Care must be taken to use the proper octets for line breaks if base64
   encoding is applied directly to text material that has not been
   converted to canonical form.  In particular, text line breaks must be
   converted into CRLF sequences prior to base64 encoding. The important
   thing to note is that this may be done directly by the encoder rather
   than in a prior canonicalization step in some implementations.

      NOTE: There is no need to worry about quoting apparent
      encapsulation boundaries within base64-encoded parts of multipart
      entities because no hyphen characters are used in the base64
      encoding.

6.    Additional Content-Header Fields

6.1.  Optional Content-ID Header Field

   In constructing a high-level user agent, it may be desirable to allow
   one body to make reference to another.  Accordingly, bodies may be
   labeled using the "Content-ID" header field, which is syntactically
   identical to the "Message-ID" header field:

   id :=  "Content-ID" ":" msg-id
   Like the Message-ID values, Content-ID values must be generated to be
   world-unique.

   The Content-ID value may be used for uniquely identifying MIME
   entities in several contexts, particularly for cacheing data
   referenced by the message/external-body mechanism.  Although the
   Content-ID header is generally optional, its use is mandatory in



Borenstein & Freed                                             [Page 23]

RFC 1521                          MIME                    September 1993


   implementations which generate data of the optional MIME Content-type
   "message/external-body".  That is, each message/external-body entity
   must have a Content-ID field to permit cacheing of such data.

   It is also worth noting that the Content-ID value has special
   semantics in the case of the multipart/alternative content-type.
   This is explained in the section of this document dealing with
   multipart/alternative.

6.2.  Optional Content-Description Header Field

   The ability to associate some descriptive information with a given
   body is often desirable. For example, it may be useful to mark an
   "image" body as "a picture of the Space Shuttle Endeavor."  Such text
   may be placed in the Content-Description header field.

   description := "Content-Description" ":" *text

   The description is presumed to be given in the US-ASCII character
   set, although the mechanism specified in [RFC-1522] may be used for
   non-US-ASCII Content-Description values.

7.    The Predefined Content-Type Values

   This document defines seven initial Content-Type values and an
   extension mechanism for private or experimental types.  Further
   standard types must be defined by new published specifications.  It
   is expected that most innovation in new types of mail will take place
   as subtypes of the seven types defined here.  The most essential
   characteristics of the seven content-types are summarized in Appendix
   F.

7.1  The Text Content-Type

   The text Content-Type is intended for sending material which is
   principally textual in form.  It is the default Content-Type.  A
   "charset" parameter may be used to indicate the character set of the
   body text for some text subtypes, notably including the primary
   subtype, "text/plain", which indicates plain (unformatted) text.  The
   default Content-Type for Internet mail is "text/plain; charset=us-
   ascii".

   Beyond plain text, there are many formats for representing what might
   be known as "extended text" -- text with embedded formatting and
   presentation information.  An interesting characteristic of many such
   representations is that they are to some extent readable even without
   the software that interprets them.  It is useful, then, to
   distinguish them, at the highest level, from such unreadable data as



Borenstein & Freed                                             [Page 24]

RFC 1521                          MIME                    September 1993


   images, audio, or text represented in an unreadable form.  In the
   absence of appropriate interpretation software, it is reasonable to
   show subtypes of text to the user, while it is not reasonable to do
   so with most nontextual data.

   Such formatted textual data should be represented using subtypes of
   text.  Plausible subtypes of text are typically given by the common
   name of the representation format, e.g., "text/richtext" [RFC-1341].

7.1.1.     The charset parameter

   A critical parameter that may be specified in the Content-Type field
   for text/plain data is the character set.  This is specified with a
   "charset" parameter, as in:

        Content-type: text/plain; charset=us-ascii

   Unlike some other parameter values, the values of the charset
   parameter are NOT case sensitive.  The default character set, which
   must be assumed in the absence of a charset parameter, is US-ASCII.

   The specification for any future subtypes of "text" must specify
   whether or not they will also utilize a "charset" parameter, and may
   possibly restrict its values as well.  When used with a particular
   body, the semantics of the "charset" parameter should be identical to
   those specified here for "text/plain", i.e., the body consists
   entirely of characters in the given charset.  In particular, definers
   of future text subtypes should pay close attention the the
   implications of multibyte character sets for their subtype
   definitions.

   This RFC specifies the definition of the charset parameter for the
   purposes of MIME to be a unique mapping of a byte stream to glyphs, a
   mapping which does not require external profiling information.

   An initial list of predefined character set names can be found at the
   end of this section.  Additional character sets may be registered
   with IANA, although the standardization of their use requires the
   usual IESG [RFC-1340] review and approval.  Note that if the
   specified character set includes 8-bit data, a Content-Transfer-
   Encoding header field and a corresponding encoding on the data are
   required in order to transmit the body via some mail transfer
   protocols, such as SMTP.

   The default character set, US-ASCII, has been the subject of some
   confusion and ambiguity in the past.  Not only were there some
   ambiguities in the definition, there have been wide variations in
   practice.  In order to eliminate such ambiguity and variations in the



Borenstein & Freed                                             [Page 25]

RFC 1521                          MIME                    September 1993


   future, it is strongly recommended that new user agents explicitly
   specify a character set via the Content-Type header field.  "US-
   ASCII" does not indicate an arbitrary seven-bit character code, but
   specifies that the body uses character coding that uses the exact
   correspondence of codes to characters specified in ASCII.  National
   use variations of ISO 646 [ISO-646] are NOT ASCII and their use in
   Internet mail is explicitly discouraged. The omission of the ISO 646
   character set is deliberate in this regard.  The character set name
   of "US-ASCII" explicitly refers to ANSI X3.4-1986 [US-ASCII] only.
   The character set name "ASCII" is reserved and must not be used for
   any purpose.

      NOTE: RFC 821 explicitly specifies "ASCII", and references an
      earlier version of the American Standard.  Insofar as one of the
      purposes of specifying a Content-Type and character set is to
      permit the receiver to unambiguously determine how the sender
      intended the coded message to be interpreted, assuming anything
      other than "strict ASCII" as the default would risk unintentional
      and incompatible changes to the semantics of messages now being
      transmitted.  This also implies that messages containing
      characters coded according to national variations on ISO 646, or
      using code-switching procedures (e.g., those of ISO 2022), as well
      as 8-bit or multiple octet character encodings MUST use an
      appropriate character set specification to be consistent with this
      specification.

   The complete US-ASCII character set is listed in [US-ASCII].  Note
   that the control characters including DEL (0-31, 127) have no defined
   meaning apart from the combination CRLF (ASCII values 13 and 10)
   indicating a new line.  Two of the characters have de facto meanings
   in wide use: FF (12) often means "start subsequent text on the
   beginning of a new page"; and TAB or HT (9) often (though not always)
   means "move the cursor to the next available column after the current
   position where the column number is a multiple of 8 (counting the
   first column as column 0)." Apart from this, any use of the control
   characters or DEL in a body must be part of a private agreement
   between the sender and recipient.  Such private agreements are
   discouraged and should be replaced by the other capabilities of this
   document.

      NOTE: Beyond US-ASCII, an enormous proliferation of character sets
      is possible. It is the opinion of the IETF working group that a
      large number of character sets is NOT a good thing.  We would
      prefer to specify a single character set that can be used
      universally for representing all of the world's languages in
      electronic mail.  Unfortunately, existing practice in several
      communities seems to point to the continued use of multiple
      character sets in the near future.  For this reason, we define



Borenstein & Freed                                             [Page 26]

RFC 1521                          MIME                    September 1993


      names for a small number of character sets for which a strong
      constituent base exists.

   The defined charset values are:

   US-ASCII -- as defined in [US-ASCII].

        ISO-8859-X -- where "X" is to be replaced, as necessary, for the
             parts of ISO-8859 [ISO-8859].  Note that the ISO 646
             character sets have deliberately been omitted in favor of
             their 8859 replacements, which are the designated character
             sets for Internet mail.  As of the publication of this
             document, the legitimate values for "X" are the digits 1
             through 9.

   The character sets specified above are the ones that were relatively
   uncontroversial during the drafting of MIME.  This document does not
   endorse the use of any particular character set other than US-ASCII,
   and recognizes that the future evolution of world character sets
   remains unclear.  It is expected that in the future, additional
   character sets will be registered for use in MIME.

   Note that the character set used, if anything other than US-ASCII,
   must always be explicitly specified in the Content-Type field.

   No other character set name may be used in Internet mail without the
   publication of a formal specification and its registration with IANA,
   or by private agreement, in which case the character set name must
   begin with "X-".

   Implementors are discouraged from defining new character sets for
   mail use unless absolutely necessary.

   The "charset" parameter has been defined primarily for the purpose of
   textual data, and is described in this section for that reason.
   However, it is conceivable that non-textual data might also wish to
   specify a charset value for some purpose, in which case the same
   syntax and values should be used.

   In general, mail-sending software must always use the "lowest common
   denominator" character set possible.  For example, if a body contains
   only US-ASCII characters, it must be marked as being in the US-ASCII
   character set, not ISO-8859-1, which, like all the ISO-8859 family of
   character sets, is a superset of US-ASCII.  More generally, if a
   widely-used character set is a subset of another character set, and a
   body contains only characters in the widely-used subset, it must be
   labeled as being in that subset.  This will increase the chances that
   the recipient will be able to view the mail correctly.



Borenstein & Freed                                             [Page 27]

RFC 1521                          MIME                    September 1993


7.1.2.     The Text/plain subtype

   The primary subtype of text is "plain".  This indicates plain
   (unformatted) text.  The default Content-Type for Internet mail,
   "text/plain; charset=us-ascii", describes existing Internet practice.
   That is, it is the type of body defined by RFC 822.

   No other text subtype is defined by this document.

   The formal grammar for the content-type header field for text is as
   follows:

   text-type := "text" "/" text-subtype [";" "charset" "=" charset]

   text-subtype := "plain" / extension-token

   charset := "us-ascii"/ "iso-8859-1"/ "iso-8859-2"/ "iso-8859-3"
          / "iso-8859-4"/ "iso-8859-5"/ "iso-8859-6"/ "iso-8859-7"
          / "iso-8859-8" / "iso-8859-9" / extension-token
                    ; case insensitive

7.2.  The Multipart Content-Type

   In the case of multiple part entities, in which one or more different
   sets of data are combined in a single body, a "multipart" Content-
   Type field must appear in the entity's header. The body must then
   contain one or more "body parts," each preceded by an encapsulation
   boundary, and the last one followed by a closing boundary.  Each part
   starts with an encapsulation boundary, and then contains a body part
   consisting of header area, a blank line, and a body area.  Thus a
   body part is similar to an RFC 822 message in syntax, but different
   in meaning.

   A body part is NOT to be interpreted as actually being an RFC 822
   message.  To begin with, NO header fields are actually required in
   body parts.  A body part that starts with a blank line, therefore, is
   allowed and is a body part for which all default values are to be
   assumed.  In such a case, the absence of a Content-Type header field
   implies that the corresponding body is plain US-ASCII text.  The only
   header fields that have defined meaning for body parts are those the
   names of which begin with "Content-".  All other header fields are
   generally to be ignored in body parts.  Although they should
   generally be retained in mail processing, they may be discarded by
   gateways if necessary.  Such other fields are permitted to appear in
   body parts but must not be depended on.  "X-" fields may be created
   for experimental or private purposes, with the recognition that the
   information they contain may be lost at some gateways.




Borenstein & Freed                                             [Page 28]

RFC 1521                          MIME                    September 1993


      NOTE: The distinction between an RFC 822 message and a body part
      is subtle, but important. A gateway between Internet and X.400
      mail, for example, must be able to tell the difference between a
      body part that contains an image and a body part that contains an
      encapsulated message, the body of which is an image.  In order to
      represent the latter, the body part must have "Content-Type:
      message", and its body (after the blank line) must be the
      encapsulated message, with its own "Content-Type: image" header
      field.  The use of similar syntax facilitates the conversion of
      messages to body parts, and vice versa, but the distinction
      between the two must be understood by implementors.  (For the
      special case in which all parts actually are messages, a "digest"
      subtype is also defined.)

   As stated previously, each body part is preceded by an encapsulation
   boundary.  The encapsulation boundary MUST NOT appear inside any of
   the encapsulated parts.  Thus, it is crucial that the composing agent
   be able to choose and specify the unique boundary that will separate
   the parts.

   All present and future subtypes of the "multipart" type must use an
   identical syntax.  Subtypes may differ in their semantics, and may
   impose additional restrictions on syntax, but must conform to the
   required syntax for the multipart type.  This requirement ensures
   that all conformant user agents will at least be able to recognize
   and separate the parts of any multipart entity, even of an
   unrecognized subtype.

   As stated in the definition of the Content-Transfer-Encoding field,
   no encoding other than "7bit", "8bit", or "binary" is permitted for
   entities of type "multipart".  The multipart delimiters and header
   fields are always represented as 7-bit ASCII in any case (though the
   header fields may encode non-ASCII header text as per [RFC-1522]),
   and data within the body parts can be encoded on a part-by-part
   basis, with Content-Transfer-Encoding fields for each appropriate
   body part.

   Mail gateways, relays, and other mail handling agents are commonly
   known to alter the top-level header of an RFC 822 message.  In
   particular, they frequently add, remove, or reorder header fields.
   Such alterations are explicitly forbidden for the body part headers
   embedded in the bodies of messages of type "multipart."

7.2.1.     Multipart:  The common syntax

   All subtypes of "multipart" share a common syntax, defined in this
   section.  A simple example of a multipart message also appears in
   this section.  An example of a more complex multipart message is



Borenstein & Freed                                             [Page 29]

RFC 1521                          MIME                    September 1993


   given in Appendix C.

   The Content-Type field for multipart entities requires one parameter,
   "boundary", which is used to specify the encapsulation boundary.  The
   encapsulation boundary is defined as a line consisting entirely of
   two hyphen characters ("-", decimal code 45) followed by the boundary
   parameter value from the Content-Type header field.

      NOTE: The hyphens are for rough compatibility with the earlier RFC
      934 method of message encapsulation, and for ease of searching for
      the boundaries in some implementations. However, it should be
      noted that multipart messages are NOT completely compatible with
      RFC 934 encapsulations; in particular, they do not obey RFC 934
      quoting conventions for embedded lines that begin with hyphens.
      This mechanism was chosen over the RFC 934 mechanism because the
      latter causes lines to grow with each level of quoting.  The
      combination of this growth with the fact that SMTP implementations
      sometimes wrap long lines made the RFC 934 mechanism unsuitable
      for use in the event that deeply-nested multipart structuring is
      ever desired.

   WARNING TO IMPLEMENTORS: The grammar for parameters on the Content-
   type field is such that it is often necessary to enclose the
   boundaries in quotes on the Content-type line.  This is not always
   necessary, but never hurts.  Implementors should be sure to study the
   grammar carefully in order to avoid producing illegal Content-type
   fields. Thus, a typical multipart Content-Type header field might
   look like this:

                 Content-Type: multipart/mixed;
                      boundary=gc0p4Jq0M2Yt08jU534c0p

   But the following is illegal:

                 Content-Type: multipart/mixed;
                      boundary=gc0p4Jq0M:2Yt08jU534c0p

   (because of the colon) and must instead be represented as

                 Content-Type: multipart/mixed;
                      boundary="gc0p4Jq0M:2Yt08jU534c0p"

   This indicates that the entity consists of several parts, each itself
   with a structure that is syntactically identical to an RFC 822
   message, except that the header area might be completely empty, and
   that the parts are each preceded by the line

                 --gc0p4Jq0M:2Yt08jU534c0p



Borenstein & Freed                                             [Page 30]

RFC 1521                          MIME                    September 1993


   Note that the encapsulation boundary must occur at the beginning of a
   line, i.e., following a CRLF, and that the initial CRLF is considered
   to be attached to the encapsulation boundary rather than part of the
   preceding part.  The boundary must be followed immediately either by
   another CRLF and the header fields for the next part, or by two
   CRLFs, in which case there are no header fields for the next part
   (and it is therefore assumed to be of Content-Type text/plain).

      NOTE: The CRLF preceding the encapsulation line is conceptually
      attached to the boundary so that it is possible to have a part
      that does not end with a CRLF (line break). Body parts that must
      be considered to end with line breaks, therefore, must have two
      CRLFs preceding the encapsulation line, the first of which is part
      of the preceding body part, and the second of which is part of the
      encapsulation boundary.

   Encapsulation boundaries must not appear within the encapsulations,
   and must be no longer than 70 characters, not counting the two
   leading hyphens.

   The encapsulation boundary following the last body part is a
   distinguished delimiter that indicates that no further body parts
   will follow.  Such a delimiter is identical to the previous
   delimiters, with the addition of two more hyphens at the end of the
   line:

                 --gc0p4Jq0M2Yt08jU534c0p--

   There appears to be room for additional information prior to the
   first encapsulation boundary and following the final boundary.  These
   areas should generally be left blank, and implementations must ignore
   anything that appears before the first boundary or after the last
   one.

      NOTE: These "preamble" and "epilogue" areas are generally not used
      because of the lack of proper typing of these parts and the lack
      of clear semantics for handling these areas at gateways,
      particularly X.400 gateways.  However, rather than leaving the
      preamble area blank, many MIME implementations have found this to
      be a convenient place to insert an explanatory note for recipients
      who read the message with pre-MIME software, since such notes will
      be ignored by MIME-compliant software.

      NOTE: Because encapsulation boundaries must not appear in the body
      parts being encapsulated, a user agent must exercise care to
      choose a unique boundary.  The boundary in the example above could
      have been the result of an algorithm designed to produce
      boundaries with a very low probability of already existing in the



Borenstein & Freed                                             [Page 31]

RFC 1521                          MIME                    September 1993


      data to be encapsulated without having to prescan the data.
      Alternate algorithms might result in more 'readable' boundaries
      for a recipient with an old user agent, but would require more
      attention to the possibility that the boundary might appear in the
      encapsulated part.  The simplest boundary possible is something
      like "---", with a closing boundary of "-----".

   As a very simple example, the following multipart message has two
   parts, both of them plain text, one of them explicitly typed and one
   of them implicitly typed:

      From: Nathaniel Borenstein <nsb@bellcore.com>
      To:  Ned Freed <ned@innosoft.com>
      Subject: Sample message
      MIME-Version: 1.0
      Content-type: multipart/mixed; boundary="simple
      boundary"

      This is the preamble.  It is to be ignored, though it
      is a handy place for mail composers to include an
      explanatory note to non-MIME conformant readers.
      --simple boundary

      This is implicitly typed plain ASCII text.
      It does NOT end with a linebreak.
      --simple boundary
      Content-type: text/plain; charset=us-ascii

      This is explicitly typed plain ASCII text.
      It DOES end with a linebreak.

      --simple boundary--
      This is the epilogue.  It is also to be ignored.

   The use of a Content-Type of multipart in a body part within another
   multipart entity is explicitly allowed.  In such cases, for obvious
   reasons, care must be taken to ensure that each nested multipart
   entity must use a different boundary delimiter. See Appendix C for an
   example of nested multipart entities.

   The use of the multipart Content-Type with only a single body part
   may be useful in certain contexts, and is explicitly permitted.

   The only mandatory parameter for the multipart Content-Type is the
   boundary parameter, which consists of 1 to 70 characters from a set
   of characters known to be very robust through email gateways, and NOT
   ending with white space.  (If a boundary appears to end with white
   space, the white space must be presumed to have been added by a



Borenstein & Freed                                             [Page 32]

RFC 1521                          MIME                    September 1993


   gateway, and must be deleted.)  It is formally specified by the
   following BNF:

   boundary := 0*69<bchars> bcharsnospace

   bchars := bcharsnospace / " "

   bcharsnospace :=    DIGIT / ALPHA / "'" / "(" / ")" / "+" /"_"
                 / "," / "-" / "." / "/" / ":" / "=" / "?"

   Overall, the body of a multipart entity may be specified  as
   follows:

   multipart-body := preamble 1*encapsulation
                  close-delimiter epilogue

   encapsulation := delimiter body-part CRLF

   delimiter := "--" boundary CRLF ; taken from Content-Type field.
                                   ; There must be no space
                                   ; between "--" and boundary.

   close-delimiter := "--" boundary "--" CRLF ; Again, no space
   by "--",

   preamble := discard-text   ;  to  be  ignored upon receipt.

   epilogue := discard-text   ;  to  be  ignored upon receipt.

   discard-text := *(*text CRLF)

   body-part := <"message" as defined in RFC 822,
             with all header fields optional, and with the
             specified delimiter not occurring anywhere in
             the message body, either on a line by itself
             or as a substring anywhere.  Note that the
             semantics of a part differ from the semantics
             of a message, as described in the text.>

      NOTE: In certain transport enclaves, RFC 822 restrictions such as
      the one that limits bodies to printable ASCII characters may not
      be in force.  (That is, the transport domains may resemble
      standard Internet mail transport as specified in RFC821 and
      assumed by RFC822, but without certain restrictions.)  The
      relaxation of these restrictions should be construed as locally
      extending the definition of bodies, for example to include octets
      outside of the ASCII range, as long as these extensions are
      supported by the transport and adequately documented in the



Borenstein & Freed                                             [Page 33]

RFC 1521                          MIME                    September 1993


      Content-Transfer-Encoding header field. However, in no event are
      headers (either message headers or body-part headers) allowed to
      contain anything other than ASCII characters.

      NOTE: Conspicuously missing from the multipart type is a notion of
      structured, related body parts.  In general, it seems premature to
      try to standardize interpart structure yet.  It is recommended
      that those wishing to provide a more structured or integrated
      multipart messaging facility should define a subtype of multipart
      that is syntactically identical, but that always expects the
      inclusion of a distinguished part that can be used to specify the
      structure and integration of the other parts, probably referring
      to them by their Content-ID field.  If this approach is used,
      other implementations will not recognize the new subtype, but will
      treat it as the primary subtype (multipart/mixed) and will thus be
      able to show the user the parts that are recognized.

7.2.2.     The Multipart/mixed (primary) subtype

   The primary subtype for multipart, "mixed", is intended for use when
   the body parts are independent and need to be bundled in a particular
   order.  Any multipart subtypes that an implementation does not
   recognize must be treated as being of subtype "mixed".

7.2.3.     The Multipart/alternative subtype

   The multipart/alternative type is syntactically identical to
   multipart/mixed, but the semantics are different.  In particular,
   each of the parts is an "alternative" version of the same
   information.

   Systems should recognize that the content of the various parts are
   interchangeable.  Systems should choose the "best" type based on the
   local environment and preferences, in some cases even through user
   interaction.  As with multipart/mixed, the order of body parts is
   significant.  In this case, the alternatives appear in an order of
   increasing faithfulness to the original content. In general, the best
   choice is the LAST part of a type supported by the recipient system's
   local environment.

   Multipart/alternative may be used, for example, to send mail in a
   fancy text format in such a way that it can easily be displayed
   anywhere:








Borenstein & Freed                                             [Page 34]

RFC 1521                          MIME                    September 1993


   From:  Nathaniel Borenstein <nsb@bellcore.com>
   To: Ned Freed <ned@innosoft.com>
   Subject: Formatted text mail
   MIME-Version: 1.0
   Content-Type: multipart/alternative; boundary=boundary42

   --boundary42

   Content-Type: text/plain; charset=us-ascii

      ...plain text version of message goes here....
   --boundary42
   Content-Type: text/richtext

      .... RFC 1341 richtext version of same message goes here ...
   --boundary42
   Content-Type: text/x-whatever

      .... fanciest formatted version of same  message  goes  here
      ...
   --boundary42--

   In this example, users whose mail system understood the "text/x-
   whatever" format would see only the fancy version, while other users
   would see only the richtext or plain text version, depending on the
   capabilities of their system.

   In general, user agents that compose multipart/alternative entities
   must place the body parts in increasing order of preference, that is,
   with the preferred format last.  For fancy text, the sending user
   agent should put the plainest format first and the richest format
   last.  Receiving user agents should pick and display the last format
   they are capable of displaying.  In the case where one of the
   alternatives is itself of type "multipart" and contains unrecognized
   sub-parts, the user agent may choose either to show that alternative,
   an earlier alternative, or both.

      NOTE: From an implementor's perspective, it might seem more
      sensible to reverse this ordering, and have the plainest
      alternative last.  However, placing the plainest alternative first
      is the friendliest possible option when multipart/alternative
      entities are viewed using a non-MIME-conformant mail reader.
      While this approach does impose some burden on conformant mail
      readers, interoperability with older mail readers was deemed to be
      more important in this case.

   It may be the case that some user agents, if they can recognize more
   than one of the formats, will prefer to offer the user the choice of



Borenstein & Freed                                             [Page 35]

RFC 1521                          MIME                    September 1993


   which format to view.  This makes sense, for example, if mail
   includes both a nicely-formatted image version and an easily-edited
   text version.  What is most critical, however, is that the user not
   automatically be shown multiple versions of the same data.  Either
   the user should be shown the last recognized version or should be
   given the choice.

   NOTE ON THE SEMANTICS OF CONTENT-ID IN MULTIPART/ALTERNATIVE: Each
   part of a multipart/alternative entity represents the same data, but
   the mappings between the two are not necessarily without information
   loss.  For example, information is lost when translating ODA to
   PostScript or plain text.  It is recommended that each part should
   have a different Content-ID value in the case where the information
   content of the two parts is not identical.  However, where the
   information content is identical -- for example, where several parts
   of type "application/external- body" specify alternate ways to access
   the identical data -- the same Content-ID field value should be used,
   to optimize any cacheing mechanisms that might be present on the
   recipient's end.  However, it is recommended that the Content-ID
   values used by the parts should not be the same Content-ID value that
   describes the multipart/alternative as a whole, if there is any such
   Content-ID field.  That is, one Content-ID value will refer to the
   multipart/alternative entity, while one or more other Content-ID
   values will refer to the parts inside it.

7.2.4.     The Multipart/digest subtype

   This document defines a "digest" subtype of the multipart Content-
   Type.  This type is syntactically identical to multipart/mixed, but
   the semantics are different.  In particular, in a digest, the default
   Content-Type value for a body part is changed from "text/plain" to
   "message/rfc822".  This is done to allow a more readable digest
   format that is largely compatible (except for the quoting convention)
   with RFC 934.

















Borenstein & Freed                                             [Page 36]

RFC 1521                          MIME                    September 1993


   A digest in this format might, then, look something like this:

   From: Moderator-Address
   To: Recipient-List
   MIME-Version: 1.0
   Subject:  Internet Digest, volume 42
   Content-Type: multipart/digest;
        boundary="---- next message ----"

   ------ next message ----

   From: someone-else
   Subject: my opinion

      ...body goes here ...

   ------ next message ----

   From: someone-else-again
   Subject: my different opinion

      ... another body goes here...

   ------ next message ------

7.2.5.     The Multipart/parallel subtype

   This document defines a "parallel" subtype of the multipart Content-
   Type.  This type is syntactically identical to multipart/mixed, but
   the semantics are different.  In particular, in a parallel entity,
   the order of body parts is not significant.

   A common presentation of this type is to display all of the parts
   simultaneously on hardware and software that are capable of doing so.
   However, composing agents should be aware that many mail readers will
   lack this capability and will show the parts serially in any event.

7.2.6.     Other Multipart subtypes

   Other multipart subtypes are expected in the future.  MIME
   implementations must in general treat unrecognized subtypes of
   multipart as being equivalent to "multipart/mixed".

   The formal grammar for content-type header fields for multipart data
   is given by:

   multipart-type := "multipart" "/" multipart-subtype
                  ";" "boundary" "=" boundary



Borenstein & Freed                                             [Page 37]

RFC 1521                          MIME                    September 1993


   multipart-subtype := "mixed" / "parallel" / "digest"
                  / "alternative" / extension-token

7.3.  The Message Content-Type

   It is frequently desirable, in sending mail, to encapsulate another
   mail message. For this common operation, a special Content-Type,
   "message", is defined.  The primary subtype, message/rfc822, has no
   required parameters in the Content-Type field.  Additional subtypes,
   "partial" and "External-body", do have required parameters.  These
   subtypes are explained below.

      NOTE: It has been suggested that subtypes of message might be
      defined for forwarded or rejected messages.  However, forwarded
      and rejected messages can be handled as multipart messages in
      which the first part contains any control or descriptive
      information, and a second part, of type message/rfc822, is the
      forwarded or rejected message.  Composing rejection and forwarding
      messages in this manner will preserve the type information on the
      original message and allow it to be correctly presented to the
      recipient, and hence is strongly encouraged.

   As stated in the definition of the Content-Transfer-Encoding field,
   no encoding other than "7bit", "8bit", or "binary" is permitted for
   messages or parts of type "message".  Even stronger restrictions
   apply to the subtypes "message/partial" and "message/external-body",
   as specified below.  The message header fields are always US-ASCII in
   any case, and data within the body can still be encoded, in which
   case the Content-Transfer-Encoding header field in the encapsulated
   message will reflect this.  Non-ASCII text in the headers of an
   encapsulated message can be specified using the mechanisms described
   in [RFC-1522].

   Mail gateways, relays, and other mail handling agents are commonly
   known to alter the top-level header of an RFC 822 message.  In
   particular, they frequently add, remove, or reorder header fields.
   Such alterations are explicitly forbidden for the encapsulated
   headers embedded in the bodies of messages of type "message."

7.3.1.     The Message/rfc822 (primary) subtype

   A Content-Type of "message/rfc822" indicates that the body contains
   an encapsulated message, with the syntax of an RFC 822 message.
   However, unlike top-level RFC 822 messages, it is not required that
   each message/rfc822 body must include a "From", "Subject", and at
   least one destination header.

   It should be noted that, despite the use of the numbers "822", a



Borenstein & Freed                                             [Page 38]

RFC 1521                          MIME                    September 1993


   message/rfc822 entity can include enhanced information as defined in
   this document.  In other words, a message/rfc822 message may be a
   MIME message.

7.3.2.     The Message/Partial subtype

   A subtype of message, "partial", is defined in order to allow large
   objects to be delivered as several separate pieces of mail and
   automatically reassembled by the receiving user agent.  (The concept
   is similar to IP fragmentation/reassembly in the basic Internet
   Protocols.)  This mechanism can be used when intermediate transport
   agents limit the size of individual messages that can be sent.
   Content-Type "message/partial" thus indicates that the body contains
   a fragment of a larger message.

   Three parameters must be specified in the Content-Type field of type
   message/partial: The first, "id", is a unique identifier, as close to
   a world-unique identifier as possible, to be used to match the parts
   together.  (In general, the identifier is essentially a message-id;
   if placed in double quotes, it can be any message-id, in accordance
   with the BNF for "parameter" given earlier in this specification.)
   The second, "number", an integer, is the part number, which indicates
   where this part fits into the sequence of fragments.  The third,
   "total", another integer, is the total number of parts. This third
   subfield is required on the final part, and is optional (though
   encouraged) on the earlier parts.  Note also that these parameters
   may be given in any order.

   Thus, part 2 of a 3-part message may have either of the following
   header fields:

                Content-Type: Message/Partial;
                     number=2; total=3;
                     id="oc=jpbe0M2Yt4s@thumper.bellcore.com"

                Content-Type: Message/Partial;
                     id="oc=jpbe0M2Yt4s@thumper.bellcore.com";
                     number=2

   But part 3 MUST specify the total number of parts:

                Content-Type: Message/Partial;
                     number=3; total=3;
                     id="oc=jpbe0M2Yt4s@thumper.bellcore.com"

   Note that part numbering begins with 1, not 0.

   When the parts of a message broken up in this manner are put



Borenstein & Freed                                             [Page 39]

RFC 1521                          MIME                    September 1993


   together, the result is a complete MIME entity, which may have its
   own Content-Type header field, and thus may contain any other data
   type.

   Message fragmentation and reassembly: The semantics of a reassembled
   partial message must be those of the "inner" message, rather than of
   a message containing the inner message.  This makes it possible, for
   example, to send a large audio message as several partial messages,
   and still have it appear to the recipient as a simple audio message
   rather than as an encapsulated message containing an audio message.
   That is, the encapsulation of the message is considered to be
   "transparent".

   When generating and reassembling the parts of a message/partial
   message, the headers of the encapsulated message must be merged with
   the headers of the enclosing entities.  In this process the following
   rules must be observed:

      (1) All of the header fields from the initial enclosing entity
      (part one), except those that start with "Content-" and the
      specific header fields "Message-ID", "Encrypted", and "MIME-
      Version", must be copied, in order, to the new message.

      (2) Only those header fields in the enclosed message which start
      with "Content-" and "Message-ID", "Encrypted", and "MIME-Version"
      must be appended, in order, to the header fields of the new
      message.  Any header fields in the enclosed message which do not
      start with "Content-" (except for "Message-ID", "Encrypted", and
      "MIME-Version") will be ignored.

      (3) All of the header fields from the second and any subsequent
      messages will be ignored.

   For example, if an audio message is broken into two parts, the first
   part might look something like this:

      X-Weird-Header-1: Foo
      From: Bill@host.com
      To: joe@otherhost.com
      Subject: Audio mail
      Message-ID: <id1@host.com>
      MIME-Version: 1.0
      Content-type: message/partial;
           id="ABC@host.com";
           number=1; total=2

      X-Weird-Header-1: Bar
      X-Weird-Header-2: Hello



Borenstein & Freed                                             [Page 40]

RFC 1521                          MIME                    September 1993


      Message-ID: <anotherid@foo.com>
      MIME-Version: 1.0
      Content-type: audio/basic
      Content-transfer-encoding: base64

         ... first half of encoded audio data goes here...

   and the second half might look something like this:

      From: Bill@host.com
      To: joe@otherhost.com
      Subject: Audio mail
      MIME-Version: 1.0
      Message-ID: <id2@host.com>
      Content-type: message/partial;
           id="ABC@host.com"; number=2; total=2

         ... second half of encoded audio data goes here...

   Then, when the fragmented message is reassembled, the resulting
   message to be displayed to the user should look something like this:

      X-Weird-Header-1: Foo
      From: Bill@host.com
      To: joe@otherhost.com
      Subject: Audio mail
      Message-ID: <anotherid@foo.com>
      MIME-Version: 1.0
      Content-type: audio/basic
      Content-transfer-encoding: base64

         ... first half of encoded audio data goes here...
         ... second half of encoded audio data goes here...

   Note on encoding of MIME entities encapsulated inside message/partial
   entities: Because data of type "message" may never be encoded in
   base64 or quoted-printable, a problem might arise if message/partial
   entities are constructed in an environment that supports binary or
   8-bit transport.  The problem is that the binary data would be split
   into multiple message/partial objects, each of them requiring binary
   transport.  If such objects were encountered at a gateway into a 7-
   bit transport environment, there would be no way to properly encode
   them for the 7-bit world, aside from waiting for all of the parts,
   reassembling the message, and then encoding the reassembled data in
   base64 or quoted-printable.  Since it is possible that different
   parts might go through different gateways, even this is not an
   acceptable solution.  For this reason, it is specified that MIME
   entities of type message/partial must always have a content-



Borenstein & Freed                                             [Page 41]

RFC 1521                          MIME                    September 1993


   transfer-encoding of 7-bit (the default).  In particular, even in
   environments that support binary or 8-bit transport, the use of a
   content-transfer-encoding of "8bit" or "binary" is explicitly
   prohibited for entities of type message/partial.

   It should be noted that, because some message transfer agents may
   choose to automatically fragment large messages, and because such
   agents may use different fragmentation thresholds, it is possible
   that the pieces of a partial message, upon reassembly, may prove
   themselves to comprise a partial message.  This is explicitly
   permitted.

   It should also be noted that the inclusion of a "References" field in
   the headers of the second and subsequent pieces of a fragmented
   message that references the Message-Id on the previous piece may be
   of benefit to mail readers that understand and track references.
   However, the generation of such "References" fields is entirely
   optional.

   Finally, it should be noted that the "Encrypted" header field has
   been made obsolete by Privacy Enhanced Messaging (PEM), but the rules
   above are believed to describe the correct way to treat it if it is
   encountered in the context of conversion to and from message/partial
   fragments.

7.3.3.     The Message/External-Body subtype

   The external-body subtype indicates that the actual body data are not
   included, but merely referenced.  In this case, the parameters
   describe a mechanism for accessing the external data.

   When an entity is of type "message/external-body", it consists of a
   header, two consecutive CRLFs, and the message header for the
   encapsulated message.  If another pair of consecutive CRLFs appears,
   this of course ends the message header for the encapsulated message.
   However, since the encapsulated message's body is itself external, it
   does NOT appear in the area that follows.  For example, consider the
   following message:

      Content-type: message/external-body; access-
      type=local-file;

           name="/u/nsb/Me.gif"

      Content-type:  image/gif
      Content-ID: <id42@guppylake.bellcore.com>
      Content-Transfer-Encoding: binary




Borenstein & Freed                                             [Page 42]

RFC 1521                          MIME                    September 1993


      THIS IS NOT REALLY THE BODY!

   The area at the end, which might be called the "phantom body", is
   ignored for most external-body messages.  However, it may be used to
   contain auxiliary information for some such messages, as indeed it is
   when the access-type is "mail-server".  Of the access-types defined
   by this document, the phantom body is used only when the access-type
   is "mail-server".  In all other cases, the phantom body is ignored.

   The only always-mandatory parameter for message/external-body is
   "access-type"; all of the other parameters may be mandatory or
   optional depending on the value of access-type.

      ACCESS-TYPE -- A case-insensitive word, indicating the supported
      access mechanism by which the file or data may be obtained.
      Values include, but are not limited to, "FTP", "ANON-FTP", "TFTP",
      "AFS", "LOCAL-FILE", and "MAIL-SERVER".  Future values, except for
      experimental values beginning with "X-" must be registered with
      IANA, as described in Appendix E .

   In addition, the following three parameters are optional for ALL
   access-types:

      EXPIRATION -- The date (in the RFC 822 "date-time" syntax, as
      extended by RFC 1123 to permit 4 digits in the year field) after
      which the existence of the external data is not guaranteed.

      SIZE -- The size (in octets) of the data.  The intent of this
      parameter is to help the recipient decide whether or not to expend
      the necessary resources to retrieve the external data.  Note that
      this describes the size of the data in its canonical form, that
      is, before any Content- Transfer-Encoding has been applied or
      after the data have been decoded.

      PERMISSION -- A case-insensitive field that indicates whether or
      not it is expected that clients might also attempt to overwrite
      the data.  By default, or if permission is "read", the assumption
      is that they are not, and that if the data is retrieved once, it
      is never needed again.  If PERMISSION is "read-write", this
      assumption is invalid, and any local copy must be considered no
      more than a cache.  "Read" and "Read-write" are the only defined
      values of permission.

   The precise semantics of the access-types defined here are described
   in the sections that follow.

   The encapsulated headers in ALL message/external-body entities MUST
   include a Content-ID header field to give a unique identifier by



Borenstein & Freed                                             [Page 43]

RFC 1521                          MIME                    September 1993


   which to reference the data.  This identifier may be used for
   cacheing mechanisms, and for recognizing the receipt of the data when
   the access-type is "mail-server".

   Note that, as specified here, the tokens that describe external-body
   data, such as file names and mail server commands, are required to be
   in the US-ASCII character set.  If this proves problematic in
   practice, a new mechanism may be required as a future extension to
   MIME, either as newly defined access-types for message/external-body
   or by some other mechanism.

   As with message/partial, it is specified that MIME entities of type
   message/external-body must always have a content-transfer-encoding of
   7-bit (the default).  In particular, even in environments that
   support binary or 8-bit transport, the use of a content-transfer-
   encoding of "8bit" or "binary" is explicitly prohibited for entities
   of type message/external-body.

7.3.3.1.  The "ftp" and "tftp" access-types

   An access-type of FTP or TFTP indicates that the message body is
   accessible as a file using the FTP [RFC-959] or TFTP [RFC-783]
   protocols, respectively.  For these access-types, the following
   additional parameters are mandatory:

      NAME -- The name of the file that contains the actual body data.

      SITE -- A machine from which the file may be obtained, using the
      given protocol. This must be a fully qualified domain name, not a
      nickname.

   Before any data are retrieved, using FTP, the user will generally
   need to be asked to provide a login id and a password for the machine
   named by the site parameter.  For security reasons, such an id and
   password are not specified as content-type parameters, but must be
   obtained from the user.

   In addition, the following parameters are optional:

      DIRECTORY -- A directory from which the data named by NAME should
      be retrieved.

      MODE -- A case-insensitive string indicating the mode to be used
      when retrieving the information.  The legal values for access-type
      "TFTP" are "NETASCII", "OCTET", and "MAIL", as specified by the
      TFTP protocol [RFC-783].  The legal values for access-type "FTP"
      are "ASCII", "EBCDIC", "IMAGE", and "LOCALn" where "n" is a
      decimal integer, typically 8.  These correspond to the



Borenstein & Freed                                             [Page 44]

RFC 1521                          MIME                    September 1993


      representation types "A" "E" "I" and "L n" as specified by the FTP
      protocol [RFC-959].  Note that "BINARY" and "TENEX" are not valid
      values for MODE, but that "OCTET" or "IMAGE" or "LOCAL8" should be
      used instead.  IF MODE is not specified, the default value is
      "NETASCII" for TFTP and "ASCII" otherwise.

7.3.3.2.  The "anon-ftp" access-type

   The "anon-ftp" access-type is identical to the "ftp" access type,
   except that the user need not be asked to provide a name and password
   for the specified site.  Instead, the ftp protocol will be used with
   login "anonymous" and a password that corresponds to the user's email
   address.

7.3.3.3.  The "local-file" and "afs" access-types

   An access-type of "local-file" indicates that the actual body is
   accessible as a file on the local machine.  An access-type of "afs"
   indicates that the file is accessible via the global AFS file system.
   In both cases, only a single parameter is required:

      NAME -- The name of the file that contains the actual body data.

   The following optional parameter may be used to describe the locality
   of reference for the data, that is, the site or sites at which the
   file is expected to be visible:

      SITE -- A domain specifier for a machine or set of machines that
      are known to have access to the data file.  Asterisks may be used
      for wildcard matching to a part of a domain name, such as
      "*.bellcore.com", to indicate a set of machines on which the data
      should be directly visible, while a single asterisk may be used to
      indicate a file that is expected to be universally available,
      e.g., via a global file system.

7.3.3.4.  The "mail-server" access-type

   The "mail-server" access-type indicates that the actual body is
   available from a mail server.  The mandatory parameter for this
   access-type is:

      SERVER -- The email address of the mail server from which the
      actual body data can be obtained.

   Because mail servers accept a variety of syntaxes, some of which is
   multiline, the full command to be sent to a mail server is not
   included as a parameter on the content-type line.  Instead, it is
   provided as the "phantom body" when the content-type is



Borenstein & Freed                                             [Page 45]

RFC 1521                          MIME                    September 1993


   message/external-body and the access- type is mail-server.

   An optional parameter for this access-type is:

      SUBJECT -- The subject that is to be used in the mail that is sent
      to obtain the data. Note that keying mail servers on Subject lines
      is NOT recommended, but such mail servers are known to exist.

   Note that MIME does not define a mail server syntax.  Rather, it
   allows the inclusion of arbitrary mail server commands in the phantom
   body.  Implementations must include the phantom body in the body of
   the message it sends to the mail server address to retrieve the
   relevant data.

   It is worth noting that, unlike other access-types, mail-server
   access is asynchronous and will happen at an unpredictable time in
   the future.  For this reason, it is important that there be a
   mechanism by which the returned data can be matched up with the
   original message/external-body entity.  MIME mailservers must use the
   same Content-ID field on the returned message that was used in the
   original message/external-body entity, to facilitate such matching.

7.3.3.5.  Examples and Further Explanations

   With the emerging possibility of very wide-area file systems, it
   becomes very hard to know in advance the set of machines where a file
   will and will not be accessible directly from the file system.
   Therefore it may make sense to provide both a file name, to be tried
   directly, and the name of one or more sites from which the file is
   known to be accessible.  An implementation can try to retrieve remote
   files using FTP or any other protocol, using anonymous file retrieval
   or prompting the user for the necessary name and password.  If an
   external body is accessible via multiple mechanisms, the sender may
   include multiple parts of type message/external-body within an entity
   of type multipart/alternative.

   However, the external-body mechanism is not intended to be limited to
   file retrieval, as shown by the mail-server access-type.  Beyond
   this, one can imagine, for example, using a video server for external
   references to video clips.

   If an entity is of type "message/external-body", then the body of the
   entity will contain the header fields of the encapsulated message.
   The body itself is to be found in the external location.  This means
   that if the body of the "message/external-body" message contains two
   consecutive CRLFs, everything after those pairs is NOT part of the
   message itself.  For most message/external-body messages, this
   trailing area must simply be ignored.  However, it is a convenient



Borenstein & Freed                                             [Page 46]

RFC 1521                          MIME                    September 1993


   place for additional data that cannot be included in the content-type
   header field.  In particular, if the "access-type" value is "mail-
   server", then the trailing area must contain commands to be sent to
   the mail server at the address given by the value of the SERVER
   parameter.

   The embedded message header fields which appear in the body of the
   message/external-body data must be used to declare the Content-type
   of the external body if it is anything other than plain ASCII text,
   since the external body does not have a header section to declare its
   type.  Similarly, any Content-transfer-encoding other than "7bit"
   must also be declared here.  Thus a complete message/external-body
   message, referring to a document in PostScript format, might look
   like this:

      From: Whomever
      To: Someone
      Subject: whatever
      MIME-Version: 1.0
      Message-ID: <id1@host.com>
      Content-Type: multipart/alternative; boundary=42
      Content-ID: <id001@guppylake.bellcore.com>

      --42
      Content-Type: message/external-body;
           name="BodyFormats.ps";
           site="thumper.bellcore.com";
           access-type=ANON-FTP;
           directory="pub";
           mode="image";
           expiration="Fri, 14 Jun 1991 19:13:14 -0400 (EDT)"

      Content-type: application/postscript
      Content-ID: <id42@guppylake.bellcore.com>

      --42
      Content-Type: message/external-body;
           name="/u/nsb/writing/rfcs/RFC-MIME.ps";
           site="thumper.bellcore.com";
           access-type=AFS
           expiration="Fri, 14 Jun 1991 19:13:14 -0400 (EDT)"

      Content-type: application/postscript
      Content-ID: <id42@guppylake.bellcore.com>

      --42
      Content-Type: message/external-body;
           access-type=mail-server



Borenstein & Freed                                             [Page 47]

RFC 1521                          MIME                    September 1993


           server="listserv@bogus.bitnet";
           expiration="Fri, 14 Jun 1991 19:13:14 -0400 (EDT)"

      Content-type: application/postscript
      Content-ID: <id42@guppylake.bellcore.com>

      get RFC-MIME.DOC

      --42--

   Note that in the above examples, the default Content-transfer-
   encoding of "7bit" is assumed for the external postscript data.

   Like the message/partial type, the message/external-body type is
   intended to be transparent, that is, to convey the data type in the
   external body rather than to convey a message with a body of that
   type.  Thus the headers on the outer and inner parts must be merged
   using the same rules as for message/partial.  In particular, this
   means that the Content-type header is overridden, but the From and
   Subject headers are preserved.

   Note that since the external bodies are not transported as mail, they
   need not conform to the 7-bit and line length requirements, but might
   in fact be binary files.  Thus a Content-Transfer-Encoding is not
   generally necessary, though it is permitted.

   Note that the body of a message of type "message/external-body" is
   governed by the basic syntax for an RFC 822 message.  In particular,
   anything before the first consecutive pair of CRLFs is header
   information, while anything after it is body information, which is
   ignored for most access-types.

   The formal grammar for content-type header fields for data of type
   message is given by:

   message-type := "message" "/" message-subtype

   message-subtype := "rfc822"
                   / "partial" 2#3partial-param
                   / "external-body" 1*external-param
                   / extension-token

   partial-param :=     (";" "id" "=" value)
              /  (";" "number" "=" 1*DIGIT)
              /  (";" "total" "=" 1*DIGIT)
         ; id & number required; total  required  for  last part

   external-param :=   (";" "access-type" "=" atype)



Borenstein & Freed                                             [Page 48]

RFC 1521                          MIME                    September 1993


              / (";" "expiration" "=" date-time)
                   ; Note that date-time is quoted
              / (";" "size" "=" 1*DIGIT)
              / (";"  "permission"  "="  ("read"  /  "read-write"))
                   ; Permission is case-insensitive
              / (";" "name" "="  value)
              / (";" "site" "=" value)
              / (";" "dir" "=" value)
              / (";" "mode" "=" value)
              / (";" "server" "=" value)
              / (";" "subject" "=" value)
          ; access-type required;others required based on access-type

   atype := "ftp" / "anon-ftp" / "tftp" / "local-file"
                  / "afs" / "mail-server" / extension-token
                  ; Case-insensitive

7.4.  The Application Content-Type

   The "application" Content-Type is to be used for data which do not
   fit in any of the other categories, and particularly for data to be
   processed by mail-based uses of application programs.  This is
   information which must be processed by an application before it is
   viewable or usable to a user.  Expected uses for Content-Type
   application include mail-based file transfer, spreadsheets, data for
   mail-based scheduling systems, and languages for "active"
   (computational) email.  (The latter, in particular, can pose security
   problems which must be understood by implementors, and are considered
   in detail in the discussion of the application/PostScript content-
   type.)

   For example, a meeting scheduler might define a standard
   representation for information about proposed meeting dates.  An
   intelligent user agent would use this information to conduct a dialog
   with the user, and might then send further mail based on that dialog.
   More generally, there have been several "active" messaging languages
   developed in which programs in a suitably specialized language are
   sent through the mail and automatically run in the recipient's
   environment.

   Such applications may be defined as subtypes of the "application"
   Content-Type.  This document defines two subtypes: octet-stream, and
   PostScript.

   In general, the subtype of application will often be the name of the
   application for which the data are intended.  This does not mean,
   however, that any application program name may be used freely as a
   subtype of application.  Such usages (other than subtypes beginning



Borenstein & Freed                                             [Page 49]

RFC 1521                          MIME                    September 1993


   with "x-") must be registered with IANA, as described in Appendix E.

7.4.1.     The Application/Octet-Stream (primary) subtype

   The primary subtype of application, "octet-stream", may be used to
   indicate that a body contains binary data.  The set of possible
   parameters includes, but is not limited to:

      TYPE -- the general type or category of binary data.  This is
      intended as information for the human recipient rather than for
      any automatic processing.

      PADDING -- the number of bits of padding that were appended to the
      bit-stream comprising the actual contents to produce the enclosed
      byte-oriented data.  This is useful for enclosing a bit-stream in
      a body when the total number of bits is not a multiple of the byte
      size.

   An additional parameter, "conversions", was defined in [RFC-1341] but
   has been removed.

   RFC 1341 also defined the use of a "NAME" parameter which gave a
   suggested file name to be used if the data were to be written to a
   file.  This has been deprecated in anticipation of a separate
   Content-Disposition header field, to be defined in a subsequent RFC.

   The recommended action for an implementation that receives
   application/octet-stream mail is to simply offer to put the data in a
   file, with any Content-Transfer-Encoding undone, or perhaps to use it
   as input to a user-specified process.

   To reduce the danger of transmitting rogue programs through the mail,
   it is strongly recommended that implementations NOT implement a
   path-search mechanism whereby an arbitrary program named in the
   Content-Type parameter (e.g., an "interpreter=" parameter) is found
   and executed using the mail body as input.

7.4.2.     The Application/PostScript subtype

   A Content-Type of "application/postscript" indicates a PostScript
   program.  Currently two variants of the PostScript language are
   allowed; the original level 1 variant is described in [POSTSCRIPT]
   and the more recent level 2 variant is described in [POSTSCRIPT2].

   PostScript is a registered trademark of Adobe Systems, Inc.  Use of
   the MIME content-type "application/postscript" implies recognition of
   that trademark and all the rights it entails.




Borenstein & Freed                                             [Page 50]

RFC 1521                          MIME                    September 1993


   The PostScript language definition provides facilities for internal
   labeling of the specific language features a given program uses. This
   labeling, called the PostScript document structuring conventions, is
   very general and provides substantially more information than just
   the language level.

   The use of document structuring conventions, while not required, is
   strongly recommended as an aid to interoperability.  Documents which
   lack proper structuring conventions cannot be tested to see whether
   or not they will work in a given environment.  As such, some systems
   may assume the worst and refuse to process unstructured documents.

   The execution of general-purpose PostScript interpreters entails
   serious security risks, and implementors are discouraged from simply
   sending PostScript email bodies to "off-the-shelf" interpreters.
   While it is usually safe to send PostScript to a printer, where the
   potential for harm is greatly constrained, implementors should
   consider all of the following before they add interactive display of
   PostScript bodies to their mail readers.

   The remainder of this section outlines some, though probably not all,
   of the possible problems with sending PostScript through the mail.

   Dangerous operations in the PostScript language include, but may not
   be limited to, the PostScript operators deletefile, renamefile,
   filenameforall, and file.  File is only dangerous when applied to
   something other than standard input or output. Implementations may
   also define additional nonstandard file operators; these may also
   pose a threat to security.  Filenameforall, the wildcard file search
   operator, may appear at first glance to be harmless. Note, however,
   that this operator has the potential to reveal information about what
   files the recipient has access to, and this information may itself be
   sensitive.  Message senders should avoid the use of potentially
   dangerous file operators, since these operators are quite likely to
   be unavailable in secure PostScript implementations.  Message-
   receiving and -displaying software should either completely disable
   all potentially dangerous file operators or take special care not to
   delegate any special authority to their operation. These operators
   should be viewed as being done by an outside agency when interpreting
   PostScript documents.  Such disabling and/or checking should be done
   completely outside of the reach of the PostScript language itself;
   care should be taken to insure that no method exists for re-enabling
   full-function versions of these operators.

   The PostScript language provides facilities for exiting the normal
   interpreter, or server, loop. Changes made in this "outer"
   environment are customarily retained across documents, and may in
   some cases be retained semipermanently in nonvolatile memory. The



Borenstein & Freed                                             [Page 51]

RFC 1521                          MIME                    September 1993


   operators associated with exiting the interpreter loop have the
   potential to interfere with subsequent document processing. As such,
   their unrestrained use constitutes a threat of service denial.
   PostScript operators that exit the interpreter loop include, but may
   not be limited to, the exitserver and startjob operators.  Message-
   sending software should not generate PostScript that depends on
   exiting the interpreter loop to operate. The ability to exit will
   probably be unavailable in secure PostScript implementations.
   Message-receiving and -displaying software should, if possible,
   disable the ability to make retained changes to the PostScript
   environment, and eliminate the startjob and exitserver commands.  If
   these commands cannot be eliminated, the password associated with
   them should at least be set to a hard-to-guess value.

   PostScript provides operators for setting system-wide and device-
   specific parameters. These parameter settings may be retained across
   jobs and may potentially pose a threat to the correct operation of
   the interpreter.  The PostScript operators that set system and device
   parameters include, but may not be limited to, the setsystemparams
   and setdevparams operators.  Message-sending software should not
   generate PostScript that depends on the setting of system or device
   parameters to operate correctly. The ability to set these parameters
   will probably be unavailable in secure PostScript implementations.
   Message-receiving and -displaying software should, if possible,
   disable the ability to change system and device parameters.  If these
   operators cannot be disabled, the password associated with them
   should at least be set to a hard-to-guess value.

   Some PostScript implementations provide nonstandard facilities for
   the direct loading and execution of machine code.  Such facilities
   are quite obviously open to substantial abuse.  Message-sending
   software should not make use of such features. Besides being totally
   hardware- specific, they are also likely to be unavailable in secure
   implementations of PostScript.  Message-receiving and -displaying
   software should not allow such operators to be used if they exist.

   PostScript is an extensible language, and many, if not most,
   implementations of it provide a number of their own extensions. This
   document does not deal with such extensions explicitly since they
   constitute an unknown factor.  Message-sending software should not
   make use of nonstandard extensions; they are likely to be missing
   from some implementations. Message-receiving and -displaying software
   should make sure that any nonstandard PostScript operators are secure
   and don't present any kind of threat.

   It is possible to write PostScript that consumes huge amounts of
   various system resources. It is also possible to write PostScript
   programs that loop infinitely.  Both types of programs have the



Borenstein & Freed                                             [Page 52]

RFC 1521                          MIME                    September 1993


   potential to cause damage if sent to unsuspecting recipients.
   Message-sending software should avoid the construction and
   dissemination of such programs, which is antisocial.  Message-
   receiving and -displaying software should provide appropriate
   mechanisms to abort processing of a document after a reasonable
   amount of time has elapsed. In addition, PostScript interpreters
   should be limited to the consumption of only a reasonable amount of
   any given system resource.

   Finally, bugs may exist in some PostScript interpreters which could
   possibly be exploited to gain unauthorized access to a recipient's
   system.  Apart from noting this possibility, there is no specific
   action to take to prevent this, apart from the timely correction of
   such bugs if any are found.

7.4.3.     Other Application subtypes

   It is expected that many other subtypes of application will be
   defined in the future.  MIME implementations must generally treat any
   unrecognized subtypes as being equivalent to application/octet-
   stream.

   The formal grammar for content-type header fields for application
   data is given by:

   application-type :=  "application" "/" application-subtype

   application-subtype := ("octet-stream" *stream-param)
                       / "postscript" / extension-token

   stream-param :=  (";" "type" "=" value)
                       / (";" "padding" "=" padding)

   padding := "0" / "1" /  "2" /  "3" / "4" / "5" / "6" / "7"

7.5.  The Image Content-Type

   A Content-Type of "image" indicates that the body contains an image.
   The subtype names the specific image format.  These names are case
   insensitive.  Two initial subtypes are "jpeg" for the JPEG format,
   JFIF encoding, and "gif" for GIF format [GIF].

   The list of image subtypes given here is neither exclusive nor
   exhaustive, and is expected to grow as more types are registered with
   IANA, as described in Appendix E.

   The formal grammar for the content-type header field for data of type
   image is given by:



Borenstein & Freed                                             [Page 53]

RFC 1521                          MIME                    September 1993


   image-type := "image" "/" ("gif" / "jpeg" / extension-token)

7.6.  The Audio Content-Type

   A Content-Type of "audio" indicates that the body contains audio
   data.  Although there is not yet a consensus on an "ideal" audio
   format for use with computers, there is a pressing need for a format
   capable of providing interoperable behavior.

   The initial subtype of "basic" is specified to meet this requirement
   by providing an absolutely minimal lowest common denominator audio
   format.  It is expected that richer formats for higher quality and/or
   lower bandwidth audio will be defined by a later document.

   The content of the "audio/basic" subtype is audio encoded using 8-bit
   ISDN mu-law [PCM].  When this subtype is present, a sample rate of
   8000 Hz and a single channel is assumed.

   The formal grammar for the content-type header field for data of type
   audio is given by:

   audio-type := "audio" "/" ("basic" / extension-token)

7.7.  The Video Content-Type

   A Content-Type of "video" indicates that the body contains a time-
   varying-picture image, possibly with color and coordinated sound.
   The term "video" is used extremely generically, rather than with
   reference to any particular technology or format, and is not meant to
   preclude subtypes such as animated drawings encoded compactly.  The
   subtype "mpeg" refers to video coded according to the MPEG standard
   [MPEG].

   Note that although in general this document strongly discourages the
   mixing of multiple media in a single body, it is recognized that many
   so-called "video" formats include a representation for synchronized
   audio, and this is explicitly permitted for subtypes of "video".

   The formal grammar for the content-type header field for data of type
   video is given by:

   video-type := "video" "/" ("mpeg" / extension-token)

7.8.  Experimental Content-Type Values

   A Content-Type value beginning with the characters "X-" is a private
   value, to be used by consenting mail systems by mutual agreement.
   Any format without a rigorous and public definition must be named



Borenstein & Freed                                             [Page 54]

RFC 1521                          MIME                    September 1993


   with an "X-" prefix, and publicly specified values shall never begin
   with "X-".  (Older versions of the widely-used Andrew system use the
   "X-BE2" name, so new systems should probably choose a different
   name.)

   In general, the use of "X-" top-level types is strongly discouraged.
   Implementors should invent subtypes of the existing types whenever
   possible.  The invention of new types is intended to be restricted
   primarily to the development of new media types for email, such as
   digital odors or holography, and not for new data formats in general.
   In many cases, a subtype of application will be more appropriate than
   a new top-level type.







































Borenstein & Freed                                             [Page 55]

RFC 1521                          MIME                    September 1993


8. Summary

   Using the MIME-Version, Content-Type, and Content-Transfer-Encoding
   header fields, it is possible to include, in a standardized way,
   arbitrary types of data objects with RFC 822 conformant mail
   messages.  No restrictions imposed by either RFC 821 or RFC 822 are
   violated, and care has been taken to avoid problems caused by
   additional restrictions imposed by the characteristics of some
   Internet mail transport mechanisms (see Appendix B). The "multipart"
   and "message" Content-Types allow mixing and hierarchical structuring
   of objects of different types in a single message.  Further Content-
   Types provide a standardized mechanism for tagging messages or body
   parts as audio, image, or several other kinds of data.  A
   distinguished parameter syntax allows further specification of data
   format details, particularly the specification of alternate character
   sets.  Additional optional header fields provide mechanisms for
   certain extensions deemed desirable by many implementors.  Finally, a
   number of useful Content-Types are defined for general use by
   consenting user agents, notably message/partial, and
   message/external-body.

9. Security Considerations

   Security issues are discussed in Section 7.4.2 and in Appendix F.
   Implementors should pay special attention to the security
   implications of any mail content-types that can cause the remote
   execution of any actions in the recipient's environment.  In such
   cases, the discussion of the application/postscript content-type in
   Section 7.4.2 may serve as a model for considering other content-
   types with remote execution capabilities.





















Borenstein & Freed                                             [Page 56]

RFC 1521                          MIME                    September 1993


10. Authors' Addresses

   For more information, the authors of this document may be contacted
   via Internet mail:

   Nathaniel S. Borenstein
   MRE 2D-296, Bellcore
   445 South St.
   Morristown, NJ 07962-1910

   Phone: +1 201 829 4270
   Fax:  +1 201 829 7019
   Email: nsb@bellcore.com


   Ned Freed
   Innosoft International, Inc.
   250 West First Street
   Suite 240
   Claremont, CA 91711

   Phone:  +1 909 624 7907
   Fax: +1 909 621 5319
   Email: ned@innosoft.com

   MIME is a result of the work of the Internet Engineering Task Force
   Working Group on Email Extensions. The chairman of that group, Greg
   Vaudreuil, may be reached at:

   Gregory M. Vaudreuil
   Tigon Corporation
   17060 Dallas Parkway
   Dallas Texas, 75248

   Phone:    +1 214-733-2722
   EMail: gvaudre@cnri.reston.va.us















Borenstein & Freed                                             [Page 57]

RFC 1521                          MIME                    September 1993


11. Acknowledgements

   This document is the result of the collective effort of a large
   number of people, at several IETF meetings, on the IETF-SMTP and
   IETF-822 mailing lists, and elsewhere.  Although any enumeration
   seems doomed to suffer from egregious omissions, the following are
   among the many contributors to this effort:

            Harald Tveit Alvestrand       Timo Lehtinen
            Randall Atkinson              John R. MacMillan
            Philippe Brandon              Rick McGowan
            Kevin Carosso                 Leo Mclaughlin
            Uhhyung Choi                  Goli Montaser-Kohsari
            Cristian Constantinof         Keith Moore
            Mark Crispin                  Tom Moore
            Dave Crocker                  Erik Naggum
            Terry Crowley                 Mark Needleman
            Walt Daniels                  John Noerenberg
            Frank Dawson                  Mats Ohrman
            Hitoshi Doi                   Julian Onions
            Kevin Donnelly                Michael Patton
            Keith Edwards                 David J. Pepper
            Chris Eich                    Blake C. Ramsdell
            Johnny Eriksson               Luc Rooijakkers
            Craig Everhart                Marshall T. Rose
            Patrik Faeltstroem            Jonathan Rosenberg
            Erik E. Fair                  Jan Rynning
            Roger Fajman                  Harri Salminen
            Alain Fontaine                Michael Sanderson
            James M. Galvin               Masahiro Sekiguchi
            Philip Gladstone              Mark Sherman
            Thomas Gordon                 Keld Simonsen
            Phill Gross                   Bob Smart
            James Hamilton                Peter Speck
            Steve Hardcastle-Kille        Henry Spencer
            David Herron                  Einar Stefferud
            Bruce Howard                  Michael Stein
            Bill Janssen                  Klaus Steinberger
            Olle Jaernefors               Peter Svanberg
            Risto Kankkunen               James Thompson
            Phil Karn                     Steve Uhler
            Alan Katz                     Stuart Vance
            Tim Kehres                    Erik van der Poel
            Neil Katin                    Guido van Rossum
            Kyuho Kim                     Peter Vanderbilt
            Anders Klemets                Greg Vaudreuil
            John Klensin                  Ed Vielmetti
            Valdis Kletniek               Ryan Waldron



Borenstein & Freed                                             [Page 58]

RFC 1521                          MIME                    September 1993


            Jim Knowles                   Wally Wedel
            Stev Knowles                  Sven-Ove Westberg
            Bob Kummerfeld                Brian Wideen
            Pekka Kytolaakso              John Wobus
            Stellan Lagerstrom            Glenn Wright
            Vincent Lau                   Rayan Zachariassen
            Donald Lindsay                David Zimmerman
            Marc Andreessen               Bob Braden
            Brian Capouch                 Peter Clitherow
            Dave Collier-Brown            John Coonrod
            Stephen Crocker               Jim Davis
            Axel Deininger                Dana S Emery
            Martin Forssen                Stephen Gildea
            Terry Gray                    Mark Horton
            Warner Losh                   Carlyn Lowery
            Laurence Lundblade            Charles Lynn
            Larry Masinter                Michael J. McInerny
            Jon Postel                    Christer Romson
            Yutaka Sato                   Markku Savela
            Richard Alan Schafer          Larry W. Virden
            Rhys Weatherly                Jay Weber
            Dave Wecker

The authors apologize for any omissions from this list, which are
certainly unintentional.


























Borenstein & Freed                                             [Page 59]

RFC 1521                          MIME                    September 1993


Appendix A -- Minimal MIME-Conformance

   The mechanisms described in this document are open-ended.  It is
   definitely not expected that all implementations will support all of
   the Content-Types described, nor that they will all share the same
   extensions.  In order to promote interoperability, however, it is
   useful to define the concept of "MIME-conformance" to define a
   certain level of implementation that allows the useful interworking
   of messages with content that differs from US ASCII text.  In this
   section, we specify the requirements for such conformance.

   A mail user agent that is MIME-conformant MUST:

      1.  Always generate a "MIME-Version: 1.0" header field.

      2.  Recognize the Content-Transfer-Encoding header field, and
      decode all received data encoded with either the quoted-printable
      or base64 implementations.  Encode any data sent that is not in
      seven-bit mail-ready representation using one of these
      transformations and include the appropriate Content-Transfer-
      Encoding header field, unless the underlying transport mechanism
      supports non-seven-bit data, as SMTP does not.

      3.  Recognize and interpret the Content-Type header field, and
      avoid showing users raw data with a Content-Type field other than
      text.  Be able to send at least text/plain messages, with the
      character set specified as a parameter if it is not US-ASCII.

      4.  Explicitly handle the following Content-Type values, to at
      least the following extents:

      Text:

            -- Recognize and display "text" mail
                 with the character set "US-ASCII."

            -- Recognize other character sets at
                 least to the extent of being able
                 to inform the user about what
                 character set the message uses.

            -- Recognize the "ISO-8859-*" character
                 sets to the extent of being able to
                 display those characters that are
                 common to ISO-8859-* and US-ASCII,
                 namely all characters represented
                 by octet values 0-127.




Borenstein & Freed                                             [Page 60]

RFC 1521                          MIME                    September 1993


            -- For unrecognized subtypes, show or
                 offer to show the user the "raw"
                 version of the data after
                 conversion of the content from
                 canonical form to local form.

       Message:

            -- Recognize and display at least the
                 primary (822) encapsulation.

       Multipart:

            -- Recognize the primary (mixed)
                 subtype.  Display all relevant
                 information on the message level
                 and the body part header level and
                 then display or offer to display
                 each of the body parts individually.

            -- Recognize the "alternative" subtype,
                 and avoid showing the user
                 redundant parts of
                 multipart/alternative mail.

            -- Treat any unrecognized subtypes as if
                 they were "mixed".

       Application:

            -- Offer the ability to remove either of
                 the two types of Content-Transfer-
                 Encoding defined in this document
                 and put the resulting information
                 in a user file.

      5.  Upon encountering any unrecognized Content- Type, an
      implementation must treat it as if it had a Content-Type of
      "application/octet-stream" with no parameter sub-arguments.  How
      such data are handled is up to an implementation, but likely
      options for handling such unrecognized data include offering the
      user to write it into a file (decoded from its mail transport
      format) or offering the user to name a program to which the
      decoded data should be passed as input.  Unrecognized predefined
      types, which in a MIME-conformant mailer might still include
      audio, image, or video, should also be treated in this way.

   A user agent that meets the above conditions is said to be MIME-



Borenstein & Freed                                             [Page 61]

RFC 1521                          MIME                    September 1993


   conformant.  The meaning of this phrase is that it is assumed to be
   "safe" to send virtually any kind of properly-marked data to users of
   such mail systems, because such systems will at least be able to
   treat the data as undifferentiated binary, and will not simply splash
   it onto the screen of unsuspecting users.  There is another sense in
   which it is always "safe" to send data in a format that is MIME-
   conformant, which is that such data will not break or be broken by
   any known systems that are conformant with RFC 821 and RFC 822.  User
   agents that are MIME-conformant have the additional guarantee that
   the user will not be shown data that were never intended to be viewed
   as text.








































Borenstein & Freed                                             [Page 62]

RFC 1521                          MIME                    September 1993


Appendix B -- General Guidelines For Sending Email Data

   Internet email is not a perfect, homogeneous system.  Mail may become
   corrupted at several stages in its travel to a final destination.
   Specifically, email sent throughout the Internet may travel across
   many networking technologies.  Many networking and mail technologies
   do not support the full functionality possible in the SMTP transport
   environment. Mail traversing these systems is likely to be modified
   in such a way that it can be transported.

   There exist many widely-deployed non-conformant MTAs in the Internet.
   These MTAs, speaking the SMTP protocol, alter messages on the fly to
   take advantage of the internal data structure of the hosts they are
   implemented on, or are just plain broken.

   The following guidelines may be useful to anyone devising a data
   format (Content-Type) that will survive the widest range of
   networking technologies and known broken MTAs unscathed.  Note that
   anything encoded in the base64 encoding will satisfy these rules, but
   that some well-known mechanisms, notably the UNIX uuencode facility,
   will not.  Note also that anything encoded in the Quoted-Printable
   encoding will survive most gateways intact, but possibly not some
   gateways to systems that use the EBCDIC character set.

      (1) Under some circumstances the encoding used for data may change
      as part of normal gateway or user agent operation. In particular,
      conversion from base64 to quoted-printable and vice versa may be
      necessary. This may result in the confusion of CRLF sequences with
      line breaks in text bodies. As such, the persistence of CRLF as
      something other than a line break must not be relied on.

      (2) Many systems may elect to represent and store text data using
      local newline conventions. Local newline conventions may not match
      the RFC822 CRLF convention -- systems are known that use plain CR,
      plain LF, CRLF, or counted records.  The result is that isolated
      CR and LF characters are not well tolerated in general; they may
      be lost or converted to delimiters on some systems, and hence must
      not be relied on.

      (3) TAB (HT) characters may be misinterpreted or may be
      automatically converted to variable numbers of spaces.  This is
      unavoidable in some environments, notably those not based on the
      ASCII character set. Such conversion is STRONGLY DISCOURAGED, but
      it may occur, and mail formats must not rely on the persistence of
      TAB (HT) characters.

      (4) Lines longer than 76 characters may be wrapped or truncated in
      some environments. Line wrapping and line truncation are STRONGLY



Borenstein & Freed                                             [Page 63]

RFC 1521                          MIME                    September 1993


      DISCOURAGED, but unavoidable in some cases. Applications which
      require long lines must somehow differentiate between soft and
      hard line breaks.  (A simple way to do this is to use the quoted-
      printable encoding.)

      (5) Trailing "white space" characters (SPACE, TAB (HT)) on a line
      may be discarded by some transport agents, while other transport
      agents may pad lines with these characters so that all lines in a
      mail file are of equal length.  The persistence of trailing white
      space, therefore, must not be relied on.

      (6) Many mail domains use variations on the ASCII character set,
      or use character sets such as EBCDIC which contain most but not
      all of the US-ASCII characters.  The correct translation of
      characters not in the "invariant" set cannot be depended on across
      character converting gateways.  For example, this situation is a
      problem when sending uuencoded information across BITNET, an
      EBCDIC system.  Similar problems can occur without crossing a
      gateway, since many Internet hosts use character sets other than
      ASCII internally.  The definition of Printable Strings in X.400
      adds further restrictions in certain special cases.  In
      particular, the only characters that are known to be consistent
      across all gateways are the 73 characters that correspond to the
      upper and lower case letters A-Z and a-z, the 10 digits 0-9, and
      the following eleven special characters:

                        "'"  (ASCII code 39)
                        "("  (ASCII code 40)
                        ")"  (ASCII code 41)
                        "+"  (ASCII code 43)
                        ","  (ASCII code 44)
                        "-"  (ASCII code 45)
                        "."  (ASCII code 46)
                        "/"  (ASCII code 47)
                        ":"  (ASCII code 58)
                        "="  (ASCII code 61)
                        "?"  (ASCII code 63)

      A maximally portable mail representation, such as the base64
      encoding, will confine itself to relatively short lines of text in
      which the only meaningful characters are taken from this set of 73
      characters.

      (7) Some mail transport agents will corrupt data that includes
      certain literal strings.  In particular, a period (".") alone on a
      line is known to be corrupted by some (incorrect) SMTP
      implementations, and a line that starts with the five characters
      "From " (the fifth character is a SPACE) are commonly corrupted as



Borenstein & Freed                                             [Page 64]

RFC 1521                          MIME                    September 1993


      well.  A careful composition agent can prevent these corruptions
      by encoding the data (e.g., in the quoted-printable encoding,
      "=46rom " in place of "From " at the start of a line, and "=2E" in
      place of "." alone on a line.

   Please note that the above list is NOT a list of recommended
   practices for MTAs.  RFC 821 MTAs are prohibited from altering the
   character of white space or wrapping long lines.  These BAD and
   illegal practices are known to occur on established networks, and
   implementations should be robust in dealing with the bad effects they
   can cause.








































Borenstein & Freed                                             [Page 65]

RFC 1521                          MIME                    September 1993


Appendix C -- A Complex Multipart Example

   What follows is the outline of a complex multipart message.  This
   message has five parts to be displayed serially: two introductory
   plain text parts, an embedded multipart message, a richtext part, and
   a closing encapsulated text message in a non-ASCII character set.
   The embedded multipart message has two parts to be displayed in
   parallel, a picture and an audio fragment.

      MIME-Version: 1.0
      From: Nathaniel Borenstein <nsb@bellcore.com>
      To: Ned Freed <ned@innosoft.com>
      Subject: A multipart example
      Content-Type: multipart/mixed;
           boundary=unique-boundary-1

      This is the preamble area of a multipart message.
      Mail readers that understand multipart format
      should ignore this preamble.
      If you are reading this text, you might want to
      consider changing to a mail reader that understands
      how to properly display multipart messages.
      --unique-boundary-1

         ...Some text appears here...
      [Note that the preceding blank line means
      no header fields were given and this is text,
      with charset US ASCII.  It could have been
      done with explicit typing as in the next part.]

      --unique-boundary-1
      Content-type: text/plain; charset=US-ASCII

      This could have been part of the previous part,
      but illustrates explicit versus implicit
      typing of body parts.

      --unique-boundary-1
      Content-Type: multipart/parallel;
           boundary=unique-boundary-2


      --unique-boundary-2
      Content-Type: audio/basic
      Content-Transfer-Encoding: base64

         ... base64-encoded 8000 Hz single-channel
             mu-law-format audio data goes here....



Borenstein & Freed                                             [Page 66]

RFC 1521                          MIME                    September 1993


      --unique-boundary-2
      Content-Type: image/gif
      Content-Transfer-Encoding: base64

         ... base64-encoded image data goes here....

      --unique-boundary-2--

      --unique-boundary-1
      Content-type: text/richtext

      This is <bold><italic>richtext.</italic></bold>
      <smaller>as defined in RFC 1341</smaller>
      <nl><nl>Isn't it
      <bigger><bigger>cool?</bigger></bigger>

      --unique-boundary-1
      Content-Type: message/rfc822

      From: (mailbox in US-ASCII)
      To: (address in US-ASCII)
      Subject: (subject in US-ASCII)
      Content-Type: Text/plain; charset=ISO-8859-1
      Content-Transfer-Encoding: Quoted-printable

         ... Additional text in ISO-8859-1 goes here ...

      --unique-boundary-1--























Borenstein & Freed                                             [Page 67]

RFC 1521                          MIME                    September 1993


Appendix D -- Collected Grammar

   This appendix contains the complete BNF grammar for all the syntax
   specified by this document.

   By itself, however, this grammar is incomplete.  It refers to several
   entities that are defined by RFC 822.  Rather than reproduce those
   definitions here, and risk unintentional differences between the two,
   this document simply refers the reader to RFC 822 for the remaining
   definitions.  Wherever a term is undefined, it refers to the RFC 822
   definition.

   application-subtype := ("octet-stream" *stream-param)
                       / "postscript" / extension-token

   application-type :=  "application" "/" application-subtype

   attribute := token    ; case-insensitive

   atype := "ftp" / "anon-ftp" / "tftp" / "local-file"
                  / "afs" / "mail-server" / extension-token
                  ; Case-insensitive

   audio-type := "audio" "/" ("basic" / extension-token)

   body-part := <"message" as defined in RFC 822,
            with all header fields optional, and with the
            specified delimiter not occurring anywhere in
            the message body, either on a line by itself
            or as a substring anywhere.>

      NOTE: In certain transport enclaves, RFC 822 restrictions such as
      the one that limits bodies to printable ASCII characters may not
      be in force.  (That is, the transport domains may resemble
      standard Internet mail transport as specified in RFC821 and
      assumed by RFC822, but without certain restrictions.)  The
      relaxation of these restrictions should be construed as locally
      extending the definition of bodies, for example to include octets
      outside of the ASCII range, as long as these extensions are
      supported by the transport and adequately documented in the
      Content-Transfer-Encoding header field. However, in no event are
      headers (either message headers or body-part headers) allowed to
      contain anything other than ASCII characters.








Borenstein & Freed                                             [Page 68]

RFC 1521                          MIME                    September 1993


   boundary := 0*69<bchars> bcharsnospace

   bchars := bcharsnospace / " "

   bcharsnospace :=    DIGIT / ALPHA / "'" / "(" / ")" / "+"  / "_"
                  / "," / "-" / "." / "/" / ":" / "=" / "?"

   charset := "us-ascii" / "iso-8859-1" / "iso-8859-2"/ "iso-8859-3"
        / "iso-8859-4" / "iso-8859-5" /  "iso-8859-6" / "iso-8859-7"
        / "iso-8859-8" / "iso-8859-9" / extension-token
        ; case insensitive

   close-delimiter := "--" boundary "--" CRLF;Again,no space by "--",

   content  := "Content-Type"  ":" type "/" subtype  *(";" parameter)
             ; case-insensitive matching of type and subtype

   delimiter := "--" boundary CRLF  ;taken from Content-Type field.
                                ; There must be no space
                                ; between "--" and boundary.

   description := "Content-Description" ":" *text

   discard-text := *(*text CRLF)

   encapsulation := delimiter body-part CRLF

   encoding := "Content-Transfer-Encoding" ":" mechanism

   epilogue := discard-text        ;  to  be  ignored upon receipt.

   extension-token :=  x-token / iana-token

   external-param :=   (";" "access-type" "=" atype)
                  / (";" "expiration" "=" date-time)

                       ; Note that date-time is quoted
                  / (";" "size" "=" 1*DIGIT)
                  / (";"  "permission"  "="  ("read" / "read-write"))
                       ; Permission is case-insensitive
                  / (";" "name" "="  value)
                  / (";" "site" "=" value)
                  / (";" "dir" "=" value)
                  / (";" "mode" "=" value)
                  / (";" "server" "=" value)
                  / (";" "subject" "=" value)
           ;access-type required; others required based on access-type




Borenstein & Freed                                             [Page 69]

RFC 1521                          MIME                    September 1993


   iana-token := <a publicly-defined extension token,
             registered with IANA, as specified in
             appendix E>

   id :=  "Content-ID" ":" msg-id

   image-type := "image" "/" ("gif" / "jpeg" / extension-token)

   mechanism :=     "7bit"    ;  case-insensitive
                  / "quoted-printable"
                  / "base64"
                  / "8bit"
                  / "binary"
                  / x-token

   message-subtype := "rfc822"
                  / "partial" 2#3partial-param
                  / "external-body" 1*external-param
                  / extension-token

   message-type := "message" "/" message-subtype

   multipart-body :=preamble 1*encapsulation close-delimiter epilogue

   multipart-subtype := "mixed" / "parallel" / "digest"
                  / "alternative" / extension-token

   multipart-type := "multipart" "/" multipart-subtype
                  ";" "boundary" "=" boundary

   octet := "=" 2(DIGIT / "A" / "B" / "C" / "D" / "E" / "F")
        ; octet must be used for characters > 127, =, SPACE, or
   TAB,
        ; and is recommended for any characters not listed in
        ; Appendix B as "mail-safe".

   padding := "0" / "1" /  "2" /  "3" / "4" / "5" / "6" / "7"

   parameter := attribute "=" value

   partial-param :=     (";" "id" "=" value)
                  /  (";" "number" "=" 1*DIGIT)
                  /  (";" "total" "=" 1*DIGIT)
             ; id & number required;total required for last part

   preamble := discard-text       ;  to  be  ignored upon receipt.

   ptext := octet / <any ASCII character except "=", SPACE,  or TAB>



Borenstein & Freed                                             [Page 70]

RFC 1521                          MIME                    September 1993


        ; characters not listed as "mail-safe" in Appendix B
        ; are also not recommended.

   quoted-printable := ([*(ptext / SPACE /  TAB)  ptext]  ["="] CRLF)
        ; Maximum line length of 76 characters excluding CRLF

   stream-param :=  (";" "type" "=" value)
                / (";" "padding" "=" padding)

   subtype := token  ; case-insensitive

   text-subtype := "plain" / extension-token

   text-type := "text" "/" text-subtype [";" "charset" "=" charset]

   token  :=  1*<any  (ASCII) CHAR except SPACE, CTLs, or tspecials>

   tspecials :=  "(" / ")" / "<" / ">" / "@"
              /  "," / ";" / ":" / "\" / <">
              /  "/" / "[" / "]" / "?" / "="
             ; Must be in quoted-string,
             ; to use within parameter values


   type :=     "application"     /  "audio"   ; case-insensitive
             / "image"           / "message"
             / "multipart"  / "text"
             / "video"           / extension-token
             ; All values case-insensitive

   value := token / quoted-string

   version := "MIME-Version" ":" 1*DIGIT "." 1*DIGIT

   video-type := "video" "/" ("mpeg" / extension-token)

   x-token := <The two characters "X-" or "x-" followed, with no
              intervening white space, by any token>













Borenstein & Freed                                             [Page 71]

RFC 1521                          MIME                    September 1993


Appendix E -- IANA Registration Procedures

   MIME has been carefully designed to have extensible mechanisms, and
   it is expected that the set of content-type/subtype pairs and their
   associated parameters will grow significantly with time.  Several
   other MIME fields, notably character set names, access-type
   parameters for the message/external-body type, and possibly even
   Content-Transfer-Encoding values, are likely to have new values
   defined over time.  In order to ensure that the set of such values is
   developed in an orderly, well-specified, and public manner, MIME
   defines a registration process which uses the Internet Assigned
   Numbers Authority (IANA) as a central registry for such values.

   In general, parameters in the content-type header field are used to
   convey supplemental information for various content types, and their
   use is defined when the content-type and subtype are defined.  New
   parameters should not be defined as a way to introduce new
   functionality.

   In order to simplify and standardize the registration process, this
   appendix gives templates for the registration of new values with
   IANA.  Each of these is given in the form of an email message
   template, to be filled in by the registering party.

   E.1  Registration of New Content-type/subtype Values

   Note that MIME is generally expected to be extended by subtypes.  If
   a new fundamental top-level type is needed, its specification must be
   published as an RFC or submitted in a form suitable to become an RFC,
   and be subject to the Internet standards process.

      To:  IANA@isi.edu
      Subject:  Registration of new MIME
           content-type/subtype

      MIME type name:

      (If the above is not an existing top-level MIME type,
      please explain why an existing type cannot be used.)

      MIME subtype name:

      Required parameters:

      Optional parameters:

      Encoding considerations:




Borenstein & Freed                                             [Page 72]

RFC 1521                          MIME                    September 1993


      Security considerations:

      Published specification:

      (The published specification must be an Internet RFC or
      RFC-to-be if a new top-level type is being defined, and
      must be a publicly available specification in any
      case.)

      Person & email address to contact for further information:

   E.2  Registration of New Access-type Values
           for Message/external-body

      To:  IANA@isi.edu
      Subject:  Registration of new MIME Access-type for
           Message/external-body content-type

      MIME access-type name:

      Required parameters:

      Optional parameters:

      Published specification:

      (The published specification must be an Internet RFC or
      RFC-to-be.)

      Person & email address to contact for further information:





















Borenstein & Freed                                             [Page 73]

RFC 1521                          MIME                    September 1993


Appendix F -- Summary of the Seven Content-types

   Content-type: text

   Subtypes defined by this document:  plain

   Important Parameters: charset

   Encoding notes: quoted-printable generally preferred if an encoding
      is needed and the character set is mostly an ASCII superset.

   Security considerations: Rich text formats such as TeX and Troff
      often contain mechanisms for executing arbitrary commands or file
      system operations, and should not be used automatically unless
      these security problems have been addressed.  Even plain text may
      contain control characters that can be used to exploit the
      capabilities of "intelligent" terminals and cause security
      violations.  User interfaces designed to run on such terminals
      should be aware of and try to prevent such problems.

   ________________________________________________________
   Content-type: multipart

   Subtypes defined by  this  document: mixed, alternative,
        digest, parallel.

   Important Parameters: boundary

   Encoding notes: No content-transfer-encoding is permitted.

   ________________________________________________________
   Content-type: message

   Subtypes defined by this document: rfc822, partial, external-body

   Important Parameters: id, number, total, access-type, expiration,
      size, permission, name, site, directory, mode, server, subject

   Encoding notes: No content-transfer-encoding is permitted.
      Specifically, only "7bit" is permitted for "message/partial" or
      "message/external-body", and only "7bit", "8bit", or "binary" are
      permitted for other subtypes of "message".
   ______________________________________________________________
   Content-type: application

   Subtypes defined by this document:  octet-stream, postscript

   Important Parameters:  type, padding



Borenstein & Freed                                             [Page 74]

RFC 1521                          MIME                    September 1993


   Deprecated Parameters: name and conversions were
                          defined in RFC 1341.

   Encoding notes: base64 preferred for unreadable subtypes.

   Security considerations:  This  type  is  intended  for  the
   transmission  of data to be interpreted by locally-installed
   programs.  If used,  for  example,  to  transmit  executable
   binary  programs  or programs in general-purpose interpreted
   languages, such as LISP programs or  shell  scripts,  severe
   security  problems  could  result.   Authors of mail-reading
   agents are cautioned against giving their systems the  power
   to  execute  mail-based  application  data without carefully
   considering  the  security  implications.    While   it   is
   certainly  possible  to  define safe application formats and
   even safe interpreters for unsafe formats, each  interpreter
   should   be   evaluated  separately  for  possible  security
   problems.
   ________________________________________________________________
   Content-type: image

   Subtypes defined by this document:  jpeg, gif

   Important Parameters: none

   Encoding notes: base64 generally preferred
   ________________________________________________________________
   Content-type: audio

   Subtypes defined by this document:  basic

   Important Parameters: none

   Encoding notes: base64 generally preferred
   ________________________________________________________________
   Content-type: video

   Subtypes defined by this document:  mpeg

   Important Parameters: none

   Encoding notes: base64 generally preferred









Borenstein & Freed                                             [Page 75]

RFC 1521                          MIME                    September 1993


Appendix G -- Canonical Encoding Model

   There was some confusion, in earlier drafts of this memo, regarding
   the model for when email data was to be converted to canonical form
   and encoded, and in particular how this process would affect the
   treatment of CRLFs, given that the representation of newlines varies
   greatly from system to system.  For this reason, a canonical model
   for encoding is presented below.

   The process of composing a MIME entity can be modeled as being done
   in a number of steps.  Note that these steps are roughly similar to
   those steps used in RFC 1421 and are performed for each 'innermost
   level' body:

   Step 1.  Creation of local form.

   The body to be transmitted is created in the system's native format.
   The native character set is used, and where appropriate local end of
   line conventions are used as well.  The body may be a UNIX-style text
   file, or a Sun raster image, or a VMS indexed file, or audio data in
   a system-dependent format stored only in memory, or anything else
   that corresponds to the local model for the representation of some
   form of information.  Fundamentally, the data is created in the
   "native" form specified by the type/subtype information.

   Step 2.  Conversion to canonical form.

   The entire body, including "out-of-band" information such as record
   lengths and possibly file attribute information, is converted to a
   universal canonical form.  The specific content type of the body as
   well as its associated attributes dictate the nature of the canonical
   form that is used.  Conversion to the proper canonical form may
   involve character set conversion, transformation of audio data,
   compression, or various other operations specific to the various
   content types.  If character set conversion is involved, however,
   care must be taken to understand the semantics of the content-type,
   which may have strong implications for any character set conversion,
   e.g.  with regard to syntactically meaningful characters in a text
   subtype other than "plain".

   For example, in the case of text/plain data, the text must be
   converted to a supported character set and lines must be delimited
   with CRLF delimiters in accordance with RFC822.  Note that the
   restriction on line lengths implied by RFC822 is eliminated if the
   next step employs either quoted-printable or base64 encoding.






Borenstein & Freed                                             [Page 76]

RFC 1521                          MIME                    September 1993


   Step 3.  Apply transfer encoding.

   A Content-Transfer-Encoding appropriate for this body is applied.
   Note that there is no fixed relationship between the content type and
   the transfer encoding.  In particular, it may be appropriate to base
   the choice of base64 or quoted-printable on character frequency
   counts which are specific to a given instance of a body.

   Step 4.  Insertion into entity.

   The encoded object is inserted into a MIME entity with appropriate
   headers.  The entity is then inserted into the body of a higher-level
   entity (message or multipart) if needed.

   It is vital to note that these steps are only a model; they are
   specifically NOT a blueprint for how an actual system would be built.
   In particular, the model fails to account for two common designs:

      1.  In many cases the conversion to a canonical form prior to
      encoding will be subsumed into the encoder itself, which
      understands local formats directly.  For example, the local
      newline convention for text bodies might be carried through to the
      encoder itself along with knowledge of what that format is.

      2.  The output of the encoders may have to pass through one or
      more additional steps prior to being transmitted as a message.  As
      such, the output of the encoder may not be conformant with the
      formats specified by RFC822.  In particular, once again it may be
      appropriate for the converter's output to be expressed using local
      newline conventions rather than using the standard RFC822 CRLF
      delimiters.

   Other implementation variations are conceivable as well.  The vital
   aspect of this discussion is that, in spite of any optimizations,
   collapsings of required steps, or insertion of additional processing,
   the resulting messages must be consistent with those produced by the
   model described here.  For example, a message with the following
   header fields:

        Content-type: text/foo; charset=bar
        Content-Transfer-Encoding: base64

   must be first represented in the text/foo form, then (if necessary)
   represented in the "bar" character set, and finally transformed via
   the base64 algorithm into a mail-safe form.






Borenstein & Freed                                             [Page 77]

RFC 1521                          MIME                    September 1993


Appendix H -- Changes from RFC 1341

   This document is a relatively minor revision  of  RFC  1341.  For
   the  convenience  of  those familiar with RFC 1341, the technical
   changes from that document are summarized in  this appendix.

   1.  The definition of "tspecials" has been changed to no longer
   include ".".

   2.  The Content-ID field is now mandatory for message/external-body
   parts.

   3.  The text/richtext type (including the old Section 7.1.3 and
   Appendix D) has been moved to a separate document.

   4.  The rules on header merging for message/partial data have been
   changed to treat the Encrypted and MIME-Version headers as special
   cases.

   5.  The definition of the external-body access-type parameter has
   been changed so that it can only indicate a single access method
   (which was all that made sense).

   6.  There is a new "Subject" parameter for message/external-body,
   access-type mail-server, to permit MIME-based use of mail servers
   that rely on Subject field information.

   7.  The "conversions" parameter for application/octet-stream has been
   removed.

   8.  Section 7.4.1 now deprecates the use of the "name" parameter for
   application/octet-stream, as this will be superseded in the future by
   a Content-Disposition header.

   9.  The formal grammar for multipart bodies has been changed so that
   a CRLF is no longer required before the first boundary line.

   10.  MIME entities of type "message/partial" and "message/external-
   body" are now required to use only the "7bit" transfer-encoding.
   (Specifically, "binary" and "8bit" are not permitted.)

   11.  The "application/oda" content-type has been removed.

   12.  A note has been added to the end of section 7.2.3, explaining
   the semantics of Content-ID in a multipart/alternative MIME entity.

   13.  The formal syntax for the "MIME-Version" field has been
   tightened, but in a way that is completely compatible with the only



Borenstein & Freed                                             [Page 78]

RFC 1521                          MIME                    September 1993


   version number defined in RFC 1341.

   14.  In Section 7.3.1, the definition of message/rfc822 has been
   relaxed regarding mandatory fields.

   All other changes from RFC 1341 were editorial changes and do not
   affect the technical content of MIME.  Considerable formal grammar
   has been added, but this reflects the prose specification that was
   already in place.










































Borenstein & Freed                                             [Page 79]

RFC 1521                          MIME                    September 1993


References

   [US-ASCII] Coded Character Set--7-Bit American Standard Code for
   Information Interchange, ANSI X3.4-1986.

   [ATK] Borenstein, Nathaniel S., Multimedia Applications Development
   with the Andrew Toolkit, Prentice-Hall, 1990.

   [GIF] Graphics Interchange Format (Version 89a), Compuserve, Inc.,
   Columbus, Ohio, 1990.

   [ISO-2022] International Standard--Information Processing--ISO 7-bit
   and 8-bit coded character sets--Code extension techniques, ISO
   2022:1986.

   [ISO-8859] Information Processing -- 8-bit Single-Byte Coded Graphic
   Character Sets -- Part 1: Latin Alphabet No. 1, ISO 8859-1:1987.  Part
   2: Latin alphabet No.  2, ISO 8859-2, 1987.  Part 3: Latin alphabet
   No. 3, ISO 8859-3, 1988.  Part 4: Latin alphabet No.  4, ISO 8859-4,
   1988.  Part 5: Latin/Cyrillic alphabet, ISO 8859-5, 1988.  Part 6:
   Latin/Arabic alphabet, ISO 8859-6, 1987.  Part 7: Latin/Greek
   alphabet, ISO 8859-7, 1987.  Part 8: Latin/Hebrew alphabet, ISO
   8859-8, 1988.  Part 9: Latin alphabet No. 5, ISO 8859-9, 1990.

   [ISO-646] International Standard--Information Processing--ISO 7-bit
   coded character set for information interchange, ISO 646:1983.

   [MPEG] Video Coding Draft Standard ISO 11172 CD, ISO IEC/TJC1/SC2/WG11
   (Motion Picture Experts Group), May, 1991.

   [PCM] CCITT, Fascicle III.4 - Recommendation G.711, Geneva, 1972,
   "Pulse Code Modulation (PCM) of Voice Frequencies".

   [POSTSCRIPT] Adobe Systems, Inc., PostScript Language Reference
   Manual, Addison-Wesley, 1985.

   [POSTSCRIPT2] Adobe Systems, Inc., PostScript Language Reference
   Manual, Addison-Wesley, Second Edition, 1990.

   [X400] Schicker, Pietro, "Message Handling Systems, X.400", Message
   Handling Systems and Distributed Applications, E.  Stefferud, O-j.
   Jacobsen, and P.  Schicker, eds., North-Holland, 1989, pp. 3-41.

   [RFC-783] Sollins, K., "TFTP Protocol (revision 2)", RFC 783, MIT,
   June 1981.

   [RFC-821] Postel, J., "Simple Mail Transfer Protocol", STD 10, RFC
   821, USC/Information Sciences Institute, August 1982.



Borenstein & Freed                                             [Page 80]

RFC 1521                          MIME                    September 1993


   [RFC-822] Crocker, D., "Standard for the Format of ARPA Internet Text
   Messages", STD 11, RFC 822, UDEL, August 1982.

   [RFC-934] Rose, M., and E. Stefferud, "Proposed Standard for Message
   Encapsulation", RFC 934, Delaware and NMA, January 1985.

   [RFC-959] Postel, J. and J. Reynolds, "File Transfer Protocol",
   STD 9, RFC 959, USC/Information Sciences Institute, October 1985.

   [RFC-1049] Sirbu, M., "Content-Type Header Field for Internet
   Messages", STD 11, RFC 1049, CMU, March 1988.

   [RFC-1421] Linn, J., "Privacy Enhancement for Internet Electronic Mail:
   Part I - Message Encryption and Authentication Procedures", RFC
   1421, IAB IRTF PSRG, IETF PEM WG, February 1993.

   [RFC-1154] Robinson, D. and R. Ullmann, "Encoding Header Field for
   Internet Messages", RFC 1154, Prime Computer, Inc., April 1990.

   [RFC-1341] 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.

   [RFC-1342] Moore, K., "Representation of Non-Ascii Text in Internet
   Message Headers", RFC 1342, University of Tennessee, June 1992.

   [RFC-1343] Borenstein, N., "A User Agent Configuration Mechanism
   for Multimedia Mail Format Information", RFC 1343, Bellcore, June
   1992.

   [RFC-1344] Borenstein, N., "Implications of MIME for Internet
   Mail Gateways", RFC 1344, Bellcore, June 1992.

   [RFC-1345] Simonsen, K., "Character Mnemonics & Character Sets",
   RFC 1345, Rationel Almen Planlaegning, June 1992.

   [RFC-1426] Klensin, J., (WG Chair), Freed, N., (Editor), Rose, M.,
   Stefferud, E., and D. Crocker, "SMTP Service Extension for 8bit-MIME
   transport", RFC 1426, United Nations Universit, Innosoft, Dover Beach
   Consulting, Inc., Network Management Associates, Inc., The Branch
   Office, February 1993.

   [RFC-1522] Moore, K., "Representation of Non-Ascii Text in Internet
   Message Headers" RFC 1522, University of Tennessee, September 1993.

   [RFC-1340] Reynolds, J., and J. Postel, "Assigned Numbers", STD 2, RFC
   1340, USC/Information Sciences Institute, July 1992.




Borenstein & Freed                                             [Page 81]


================================================
FILE: doc/notes/rfc/rfc1854.txt
================================================






Network Working Group                                           N. Freed
Request For Comments: 1854                  Innosoft International, Inc.
Category: Standards Track                          A. Cargille, WG Chair
                                                            October 1995


                         SMTP Service Extension
                         for Command Pipelining

Status of this Memo

   This document specifies an Internet standards track protocol for the
   Internet community, and requests discussion and suggestions for
   improvements.  Please refer to the current edition of the "Internet
   Official Protocol Standards" (STD 1) for the standardization state
   and status of this protocol.  Distribution of this memo is unlimited.

Abstract

   This memo defines an extension to the SMTP service whereby a server
   can indicate the extent of its ability to accept multiple commands in
   a single TCP send operation. Using a single TCP send operation for
   multiple commands can improve SMTP performance significantly.

Introduction

   Although SMTP is widely and robustly deployed, certain extensions may
   nevertheless prove useful. In particular, many parts of the Internet
   make use of high latency network links.

   SMTP's intrinsic one command-one response structure is significantly
   penalized by high latency links, often to the point where the factors
   contributing to overall connection time are dominated by the time
   spent waiting for responses to individual commands (turnaround time).

   In the best of all worlds it would be possible to simply deploy SMTP
   client software that makes use of command pipelining: batching up
   multiple commands into single TCP send operations. Unfortunately, the
   original SMTP specification [1] did not explicitly state that SMTP
   servers must support this.  As a result a non-trivial number of
   Internet SMTP servers cannot adequately handle command pipelining.
   Flaws known to exist in deployed servers include:

 (1)   Connection handoff and buffer flushes in the middle of
       the SMTP dialogue.  Creation of server processes for
       incoming SMTP connections is a useful, obvious, and
       harmless implementation technique. However, some SMTP
       servers defer process forking and connection handoff



Freed & Cargille            Standards Track                     [Page 1]

RFC 1854                    SMTP Pipelining                 October 1995


       until some intermediate point in the SMTP dialogue.
       When this is done material read from the TCP connection
       and kept in process buffers can be lost.

 (2)   Flushing the TCP input buffer when an SMTP command
       fails. SMTP commands often fail but there is no reason
       to flush the TCP input buffer when this happens.
       Nevertheless, some SMTP servers do this.

 (3)   Improper processing and promulgation of SMTP command
       failures. For example, some SMTP servers will refuse to
       accept a DATA command if the last RCPT TO command
       fails, paying no attention to the success or failure of
       prior RCPT TO command results. Other servers will
       accept a DATA command even when all previous RCPT TO
       commands have failed. Although it is possible to
       accommodate this sort of behavior in a client that
       employs command pipelining, it does complicate the
       construction of the client unnecessarily.

   This memo uses the mechanism described in [2] to define an extension
   to the SMTP service whereby an SMTP server can declare that it is
   capable of handling pipelined commands. The SMTP client can then
   check for this declaration and use pipelining only when the server
   declares itself capable of handling it.

1.  Framework for the Command Pipelining Extension

   The Command Pipelining extension is defined as follows:

    (1)   the name of the SMTP service extension is Pipelining;

    (2)   the EHLO keyword value associated with the extension is
          PIPELINING;

    (3)   no parameter is used with the PIPELINING EHLO keyword;

    (4)   no additional parameters are added to either the MAIL
          FROM or RCPT TO commands.

    (5)   no additional SMTP verbs are defined by this extension;
          and,

    (6)   the next section specifies how support for the
          extension affects the behavior of a server and client
          SMTP.





Freed & Cargille            Standards Track                     [Page 2]

RFC 1854                    SMTP Pipelining                 October 1995


2.  The Pipelining Service Extension

   When a client SMTP wishes to employ command pipelining, it first
   issues the EHLO command to the server SMTP. If the server SMTP
   responds with code 250 to the EHLO command, and the response includes
   the EHLO keyword value PIPELINING, then the server SMTP has indicated
   that it can accommodate SMTP command pipelining.

2.1.  Client use of pipelining

   Once the client SMTP has confirmed that support exists for the
   pipelining extension, the client SMTP may then elect to transmit
   groups of SMTP commands in batches without waiting for a response to
   each individual command. In particular, the commands RSET, MAIL FROM,
   SEND FROM, SOML FROM, SAML FROM, and RCPT TO can all appear anywhere
   in a pipelined command group.  The EHLO, DATA, VRFY, EXPN, TURN,
   QUIT, and NOOP commands can only appear as the last command in a
   group since their success or failure produces a change of state which
   the client SMTP must accommodate. (NOOP is included in this group so
   it can be used as a synchronization point.)

   Additional commands added by other SMTP extensions may only appear as
   the last command in a group unless otherwise specified by the
   extensions that define the commands.

   The actual transfer of message content is explicitly allowed to be
   the first "command" in a group. That is, the RSET/MAIL FROM sequence
   necessary to initiate a new message transaction can be placed in the
   same group as the final transfer of the headers and body of the
   previous message.

   Client SMTP implementations that employ pipelining MUST check ALL
   statuses associated with each command in a group. For example, if
   none of the RCPT TO recipient addresses were accepted the client must
   then check the response to the DATA command -- the client cannot
   assume that the DATA command will be rejected just because none of
   the RCPT TO commands worked.  If the DATA command was properly
   rejected the client SMTP can just issue RSET, but if the DATA command
   was accepted the client SMTP should send a single dot.

   Command statuses MUST be coordinated with responses by counting each
   separate response and correlating that count with the number of
   commands known to have been issued.  Multiline responses MUST be
   supported. Matching on the basis of either the error code value or
   associated text is expressly forbidden.

   Client SMTP implementations MAY elect to operate in a nonblocking
   fashion, processing server responses immediately upon receipt, even



Freed & Cargille            Standards Track                     [Page 3]

RFC 1854                    SMTP Pipelining                 October 1995


   if there is still data pending transmission from the client's
   previous TCP send operation. If nonblocking operation is not
   supported, however, client SMTP implementations MUST also check the
   TCP window size and make sure that each group of commands fits
   entirely within the window. The window size is usually, but not
   always, 4K octets.  Failure to perform this check can lead to
   deadlock conditions.

   Clients MUST NOT confuse responses to multiple commands with
   multiline responses. Each command requires one or more lines of
   response, the last line not containing a dash between the response
   code and the response string.

2.2.  Server support of pipelining

   A server SMTP implementation that offers the pipelining extension:

    (1)   MUST NOT flush or otherwise lose the contents of the
          TCP input buffer under any circumstances whatsoever.

    (2)   SHOULD issue a positive response to the DATA command if
          and only if one or more valid RCPT TO addresses have
          been previously received.

    (3)   MUST NOT, after issuing a positive response to a DATA
          command with no valid recipients and subsequently
          receiving an empty message, send any message whatsoever
          to anybody.

    (4)   SHOULD elect to store responses to grouped RSET, MAIL
          FROM, SEND FROM, SOML FROM, SAML FROM, and RCPT TO
          commands in an internal buffer so they can sent as a
          unit.

    (5)   MUST NOT buffer responses to EHLO, DATA, VRFY, EXPN,
          TURN, QUIT, and NOOP.

    (6)   MUST NOT buffer responses to unrecognized commands.

    (7)   MUST send all pending responses immediately whenever
          the local TCP input buffer is emptied.

    (8)   MUST NOT make assumptions about commands that are yet
          to be received.

    (9)   SHOULD issue response text that indicates, either
          implicitly or explicitly, what command the response
          matches.



Freed & Cargille            Standards Track                     [Page 4]

RFC 1854                    SMTP Pipelining                 October 1995


   The overriding intent of these server requirements is to make it as
   easy as possible for servers to conform to these pipelining
   extensions.

3.  Examples

   Consider the following SMTP dialogue that does not use pipelining:

   S: <wait for open connection>
   C: <open connection to server>
   S: 220 innosoft.com SMTP service ready
   C: HELO dbc.mtview.ca.us
   S: 250 innosoft.com
   C: MAIL FROM:<mrose@dbc.mtview.ca.us>
   S: 250 sender <mrose@dbc.mtview.ca.us> OK
   C: RCPT TO:<ned@innosoft.com>
   S: 250 recipient <ned@innosoft.com> OK
   C: RCPT TO:<dan@innosoft.com>
   S: 250 recipient <dan@innosoft.com> OK
   C: RCPT TO:<kvc@innosoft.com>
   S: 250 recipient <kvc@innosoft.com> OK
   C: DATA
   S: 354 enter mail, end with line containing only "."
    ...
   C: .
   S: 250 message sent
   C: QUIT
   S: 221 goodbye

   The client waits for a server response a total of 9 times in this
   simple example. But if pipelining is employed the following dialogue
   is possible:

   S: <wait for open connection>
   C: <open connection to server>
   S: 220 innosoft.com SMTP service ready
   C: EHLO dbc.mtview.ca.us
   S: 250-innosoft.com
   S: 250 PIPELINING
   C: MAIL FROM:<mrose@dbc.mtview.ca.us>
   C: RCPT TO:<ned@innosoft.com>
   C: RCPT TO:<dan@innosoft.com>
   C: RCPT TO:<kvc@innosoft.com>
   C: DATA
   S: 250 sender <mrose@dbc.mtview.ca.us> OK
   S: 250 recipient <ned@innosoft.com> OK
   S: 250 recipient <dan@innosoft.com> OK
   S: 250 recipient <kvc@innosoft.com> OK



Freed & Cargille            Standards Track                     [Page 5]

RFC 1854                    SMTP Pipelining                 October 1995


   S: 354 enter mail, end with line containing only "."
    ...
   C: .
   C: QUIT
   S: 250 message sent
   S: 221 goodbye

   The total number of turnarounds has been reduced from 9 to 4.

   The next example illustrates one possible form of behavior when
   pipelining is used and all recipients are rejected:

   S: <wait for open connection>
   C: <open connection to server>
   S: 220 innosoft.com SMTP service ready
   C: EHLO dbc.mtview.ca.us
   S: 250-innosoft.com
   S: 250 PIPELINING
   C: MAIL FROM:<mrose@dbc.mtview.ca.us>
   C: RCPT TO:<nsb@thumper.bellcore.com>
   C: RCPT TO:<galvin@tis.com>
   C: DATA
   S: 250 sender <mrose@dbc.mtview.ca.us> OK
   S: 550 remote mail to <nsb@thumper.bellore.com> not allowed
   S: 550 remote mail to <galvin@tis.com> not allowed
   S: 554 no valid recipients given
   C: QUIT
   S: 221 goodbye

   The client SMTP waits for the server 4 times here as well. If the
   server SMTP does not check for at least one valid recipient prior to
   accepting the DATA command, the following dialogue would result:

   S: <wait for open connection>
   C: <open connection to server>
   S: 220 innosoft.com SMTP service ready
   C: EHLO dbc.mtview.ca.us
   S: 250-innosoft.com
   S: 250 PIPELINING
   C: MAIL FROM:<mrose@dbc.mtview.ca.us>
   C: RCPT TO:<nsb@thumper.bellcore.com>
   C: RCPT TO:<galvin@tis.com>
   C: DATA
   S: 250 sender <mrose@dbc.mtview.ca.us> OK
   S: 550 remote mail to <nsb@thumper.bellore.com> not allowed
   S: 550 remote mail to <galvin@tis.com> not allowed
   S: 354 enter mail, end with line containing only "."
   C: .



Freed & Cargille            Standards Track                     [Page 6]

RFC 1854                    SMTP Pipelining                 October 1995


   C: QUIT
   S: 554 no valid recipients
   S: 221 goodbye

4.  Security Considerations

   This RFC does not discuss security issues and is not believed to
   raise any security issues not endemic in electronic mail and present
   in fully conforming implementations of [1].

5.  Acknowledgements

   This document is based on the SMTP service extension model presented
   in RFC 1425. Marshall Rose's description of SMTP command pipelining
   in his book "The Internet Message" also served as a source of
   inspiration for this extension.

6.  References

   [1]  Postel, J., "Simple Mail Transfer Protocol", STD 10
        RFC 821, USC/Information Sciences Institute, August
        1982.

   [2]  Klensin, J., Freed, N., Rose, M., Stefferud, E.,
        and D. Crocker, "SMTP Service Extensions", RFC 1651,
        MCI, Innosoft, Dover Beach Consulting, Inc.,
        Network Management Associates, Inc., Silicon Graphics,
        Inc., July 1994.

7.  Author's Address

   Ned Freed
   Innosoft International, Inc.
   1050 East Garvey Avenue South
   West Covina, CA 91790
   USA

   Phone: +1 818 919 3600
   Fax: +1 818 919 3614
   EMail: ned@innosoft.com











Freed & Cargille            Standards Track                     [Page 7]



================================================
FILE: doc/notes/rfc/rfc2015.txt
================================================





Network Working Group                                          M. Elkins
Request for Comments: 2015                     The Aerospace Corporation
Category: Standards Track                                   October 1996


              MIME Security with Pretty Good Privacy (PGP)

Status of this Memo

   This document specifies an Internet standards track protocol for the
   Internet community, and requests discussion and suggestions for
   improvements.  Please refer to the current edition of the "Internet
   Official Protocol Standards" (STD 1) for the standardization state
   and status of this protocol.  Distribution of this memo is unlimited.

Abstract

   This document describes how Pretty Good Privacy (PGP) can be used to
   provide privacy and authentication using the Multipurpose Internet
   Mail Extensions (MIME) security content types described in RFC1847.

1.  Introduction

   Previous work on integrating PGP with MIME (including the since
   withdrawn application/pgp content type) has suffered from a number of
   problems, the most significant of which is the inability to recover
   signed message bodies without parsing data structures specific to
   PGP.  This work makes use of the elegant solution proposed in
   RFC1847, which defines security multipart formats for MIME. The
   security multiparts clearly separate the signed message body from the
   signature, and have a number of other desirable properties. This
   document is styled after RFC 1848, which defines MIME Object Security
   Services (MOSS) for providing security and authentication.

   This document defines three new content types for implementing
   security and privacy with PGP: application/pgp-encrypted,
   application/pgp-signature and application/pgp-keys.

1.1  Compliance

   In order for an implementation to be compliant with this
   specification, is it absolutely necessary for it to obey all items
   labeled as MUST or REQUIRED.








Elkins                      Standards Track                     [Page 1]

RFC 2015                 MIME Security with PGP             October 1996


2.  PGP data formats

   PGP can generate either ASCII armor (described in [3]) or 8-bit
   binary output when encrypting data, generating a digital signature,
   or extracting public key data.  The ASCII armor output is the
   REQUIRED method for data transfer.  This allows those users who do
   not have the means to interpret the formats described in this
   document to be able extract and use the PGP information in the
   message.

   When the amount of data to be transmitted requires that it be sent in
   many parts, the MIME message/partial mechanism should be used rather
   than the multipart ASCII armor PGP format.

3.  Content-Transfer-Encoding restrictions

   Multipart/signed and multipart/encrypted are to be treated by agents
   as opaque, meaning that the data is not to be altered in any way [1].
   However, many existing mail gateways will detect if the next hop does
   not support MIME or 8-bit data and perform conversion to either
   Quoted-Printable or Base64.  This presents serious problems for
   multipart/signed, in particular, where the signature is invalidated
   when such an operation occurs.  For this reason all data signed
   according to this protocol MUST be constrained to 7 bits (8- bit data
   should be encoded using either Quoted-Printable or Base64).  Note
   that this also includes the case where a signed object is also
   encrypted (see section 6).  This restriction will increase the
   likelihood that the signature will be valid upon receipt.

   Data that is ONLY to be encrypted is allowed to contain 8-bit
   characters and therefore need not be converted to a 7-bit format.

     Implementor's note: It cannot be stressed enough that applications
     using this standard should follow MIME's suggestion that you "be
     conservative in what you generate, and liberal in what you accept."
     In this particular case it means it would be wise for an
     implementation to accept messages with any content-transfer-
     encoding, but restrict generation to the 7-bit format required by
     this memo.  This will allow future compatibility in the event the
     Internet SMTP framework becomes 8-bit friendly.

4.  PGP encrypted data

   Before encryption with PGP, the data should be written in MIME
   canonical format (body and headers).

   PGP encrypted data is denoted by the "multipart/encrypted" content
   type, described in [1], and MUST have a "protocol" parameter value of



Elkins                      Standards Track                     [Page 2]

RFC 2015                 MIME Security with PGP             October 1996


   "application/pgp-encrypted".  Note that the value of the parameter
   MUST be enclosed in quotes.

   The multipart/encrypted MUST consist of exactly two parts.  The first
   MIME body part must have a content type of "application/pgp-
   encrypted".  This body contains the control information.  A message
   complying with this standard MUST contain a "Version: 1" field in
   this body.  Since the PGP packet format contains all other
   information necessary for decrypting, no other information is
   required here.

   The second MIME body part MUST contain the actual encrypted data.  It
   must be labeled with a content type of "application/octet- stream".

   Example message:

     From: Michael Elkins <elkins@aero.org>
     To: Michael Elkins <elkins@aero.org>
     Mime-Version: 1.0
     Content-Type: multipart/encrypted; boundary=foo;
        protocol="application/pgp-encrypted"

     --foo
     Content-Type: application/pgp-encrypted

     Version: 1

     --foo
     Content-Type: application/octet-stream

     -----BEGIN PGP MESSAGE-----
     Version: 2.6.2

     hIwDY32hYGCE8MkBA/wOu7d45aUxF4Q0RKJprD3v5Z9K1YcRJ2fve87lMlDlx4Oj
     eW4GDdBfLbJE7VUpp13N19GL8e/AqbyyjHH4aS0YoTk10QQ9nnRvjY8nZL3MPXSZ
     g9VGQxFeGqzykzmykU6A26MSMexR4ApeeON6xzZWfo+0yOqAq6lb46wsvldZ96YA
     AABH78hyX7YX4uT1tNCWEIIBoqqvCeIMpp7UQ2IzBrXg6GtukS8NxbukLeamqVW3
     1yt21DYOjuLzcMNe/JNsD9vDVCvOOG3OCi8=
     =zzaA
     -----END PGP MESSAGE-----

     --foo--

5.  PGP signed data

   PGP signed messages are denoted by the "multipart/signed" content
   type, described in [1], with a "protocol" parameter which MUST have a
   value of "application/pgp-signature" (MUST be quoted).  The "micalg"



Elkins                      Standards Track                     [Page 3]

RFC 2015                 MIME Security with PGP             October 1996


   parameter MUST have a value of "pgp-<hash-symbol>", where <hash-
   symbol> identifies the message integrity check (MIC) used to generate
   the signature.  The currently defined values for <hash-symbol> are
   "md5" for the MD5 checksum, and "sha1" for the SHA.1 algorithm.

   The multipart/signed body MUST consist of exactly two parts.  The
   first part contains the signed data in MIME canonical format,
   including a set of appropriate content headers describing the data.

   The second body MUST contain the PGP digital signature.  It MUST be
   labeled with a content type of "application/pgp-signature".

   When the PGP digital signature is generated:

   (1)  The data to be signed must first be converted to its
        type/subtype specific canonical form.  For text/plain, this
        means conversion to an appropriate character set and conversion
        of line endings to the canonical <CR><LF> sequence.

   (2)  An appropriate Content-Transfer-Encoding is then applied. Each
        line of the encoded data MUST end with the canonical <CR><LF>
        sequence.

   (3)  MIME content headers are then added to the body, each ending
        with the canonical <CR><LF> sequence.

   (4)  As described in [1], the digital signature MUST be calculated
        over both the data to be signed and its set of content headers.

   (5)  The signature MUST be generated detached from the signed data
        so that the process does not alter the signed data in any way.

   Example message:

     From: Michael Elkins <elkins@aero.org>
     To: Michael Elkins <elkins@aero.org>
     Mime-Version: 1.0
     Content-Type: multipart/signed; boundary=bar; micalg=pgp-md5;
     protocol="application/pgp-signature"

     --bar
     & Content-Type: text/plain; charset=iso-8859-1
     & Content-Transfer-Encoding: quoted-printable
     &
     & =A1Hola!
     &
     & Did you know that talking to yourself is a sign of senility?
     &



Elkins                      Standards Track                     [Page 4]

RFC 2015                 MIME Security with PGP             October 1996


     & It's generally a good idea to encode lines that begin with
     & From=20because some mail transport agents will insert a greater-
     & than (>) sign, thus invalidating the signature.
     &
     & Also, in some cases it might be desirable to encode any   =20
     &railing whitespace that occurs on lines in order to ensure  =20
     & that the message signature is not invalidated when passing =20
     & a gateway that modifies such whitespace (like BITNET). =20
     &
     & me

     --bar
     Content-Type: application/pgp-signature

    -----BEGIN PGP MESSAGE-----
   Version: 2.6.2

   iQCVAwUBMJrRF2N9oWBghPDJAQE9UQQAtl7LuRVndBjrk4EqYBIb3h5QXIX/LC//
   jJV5bNvkZIGPIcEmI5iFd9boEgvpirHtIREEqLQRkYNoBActFBZmh9GC3C041WGq
   uMbrbxc+nIs1TIKlA08rVi9ig/2Yh7LFrK5Ein57U/W72vgSxLhe/zhdfolT9Brn
   HOxEa44b+EI=
   =ndaj
   -----END PGP MESSAGE-----

   --bar--

   The "&"s in the previous example indicate the portion of the data
   over which the signature was calculated.

   Though not required, it is generally a good idea to use Quoted-
   Printable encoding in the first step (writing out the data to be
   signed in MIME canonical format) if any of the lines in the data
   begin with "From ", and encode the "F".  This will avoid an MTA
   inserting a ">" in front of the line, thus invalidating the
   signature!

   Upon receipt of a signed message, an application MUST:

   (1)  Convert line endings to the canonical <CR><LF> sequence before
        the signature can be verified.  This is necessary since the
        local MTA may have converted to a local end of line convention.

   (2)  Pass both the signed data and its associated content headers
        along with the PGP signature to the signature verification
        service.






Elkins                      Standards Track                     [Page 5]

RFC 2015                 MIME Security with PGP             October 1996


6.  Encrypted and Signed Data

   Sometimes it is desirable to both digitally sign and then encrypt a
   message to be sent.  This protocol allows for two methods of
   accomplishing this task.

6.1  RFC1847 Encapsulation

   [1], it is stated that the data should first be signed as a
   multipart/signature body, and then encrypted to form the final
   multipart/encrypted body, i.e.,

    Content-Type: multipart/encrypted;
       protocol="application/pgp-encrypted"; boundary=foo

    --foo
    Content-Type: application/pgp-encrypted

    Version: 1

    --foo
    Content-Type: application/octet-stream

    -----BEGIN PGP MESSAGE-----
    & Content-Type: multipart/signed; micalg=pgp-md5
    &     protocol="application/pgp-signature"; boundary=bar
    &
    & --bar
    & Content-Type: text/plain; charset=us-ascii
    &
    & This message was first signed, and then encrypted.
    &
    & --bar
    & Content-Type: application/pgp-signature
    &
    & -----BEGIN PGP MESSAGE-----
    & Version: 2.6.2
    &
    & iQCVAwUBMJrRF2N9oWBghPDJAQE9UQQAtl7LuRVndBjrk4EqYBIb3h5QXIX/LC//
    & jJV5bNvkZIGPIcEmI5iFd9boEgvpirHtIREEqLQRkYNoBActFBZmh9GC3C041WGq
    & uMbrbxc+nIs1TIKlA08rVi9ig/2Yh7LFrK5Ein57U/W72vgSxLhe/zhdfolT9Brn
    & HOxEa44b+EI=
    & =ndaj
    & -----END PGP MESSAGE-----
    &
    & --bar--
    -----END PGP MESSAGE-----




Elkins                      Standards Track                     [Page 6]

RFC 2015                 MIME Security with PGP             October 1996


    --foo--

    (The text preceded by '&' indicates that it is really
    encrypted, but presented as text for clarity.)

6.2  Combined method

   Versions 2.x of PGP also allow data to be signed and encrypted in one
   operation.  This method is an acceptable shortcut, and has the
   benefit of less overhead.  The resulting data should be formed as a
   "multipart/encrypted" object as described above.

   Messages which are encrypted and signed in this combined fashion are
   REQUIRED to follow the same canonicalization rules as for
   multipart/signed objects.

   It is explicitly allowed for an agent to decrypt a combined message
   and rewrite it as a multipart/signed object using the signature data
   embedded in the encrypted version.

7.  Distribution of PGP public keys

   Content-Type: application/pgp-keys
   Required parameters: none
   Optional parameters: none

   This is the content type which should be used for relaying public key
   blocks.

8.  Notes

   PGP and Pretty Good Privacy are trademarks of Philip Zimmermann.

9.  Security Considerations

   Use of this protocol has the same security considerations as PGP, and
   is not known to either increase or decrease the security of messages
   using it; see [3] for more information.

10.  Author's Address

        Michael Elkins
        P.O. Box 92957 - M1/102
        Los Angeles, CA 90009-2957

        Phone: +1 310 336 8040
        Fax: +1 310 336 4402




Elkins                      Standards Track                     [Page 7]

RFC 2015                 MIME Security with PGP             October 1996


References

   [1]  Galvin, J., Murphy, G., Crocker, S., and N. Freed, "Security
        Multiparts for MIME: Multipart/Signed and Multipart/Encrypted",
        RFC 1847, October 1995.

   [2]  Galvin, J., Murphy, G., Crocker, S., and N. Freed, "MIME Object
        Security Services", RFC 1848, October 1995.

   [3]  Atkins, D., Stallings, W., and P. Zimmermann, "PGP Message
        Exchange Formats", RFC 1991, August 1996.








































Elkins                      Standards Track                     [Page 8]



================================================
FILE: doc/notes/rfc/rfc2045.txt
================================================






Network Working Group                                          N. Freed
Request for Comments: 2045                                     Innosoft
Obsoletes: 1521, 1522, 1590                               N. Borenstein
Category: Standards Track                                 First Virtual
                                                          November 1996


                 Multipurpose Internet Mail Extensions
                            (MIME) Part One:
                   Format of Internet Message Bodies

Status of this Memo

   This document specifies an Internet standards track protocol for the
   Internet community, and requests discussion and suggestions for
   improvements.  Please refer to the current edition of the "Internet
   Official Protocol Standards" (STD 1) for the standardization state
   and status of this protocol.  Distribution of this memo is unlimited.

Abstract

   STD 11, RFC 822, defines a message representation protocol specifying
   considerable detail about US-ASCII message headers, and leaves the
   message content, or message body, as flat US-ASCII text.  This set of
   documents, collectively called the Multipurpose Internet Mail
   Extensions, or MIME, redefines the format of messages to allow for

    (1)   textual message bodies in character sets other than
          US-ASCII,

    (2)   an extensible set of different formats for non-textual
          message bodies,

    (3)   multi-part message bodies, and

    (4)   textual header information in character sets other than
          US-ASCII.

   These documents are based on earlier work documented in RFC 934, STD
   11, and RFC 1049, but extends and revises them.  Because RFC 822 said
   so little about message bodies, these documents are largely
   orthogonal to (rather than a revision of) RFC 822.

   This initial document specifies the various headers used to describe
   the structure of MIME messages. The second document, RFC 2046,
   defines the general structure of the MIME media typing system and
   defines an initial set of media types. The third document, RFC 2047,
   describes extensions to RFC 822 to allow non-US-ASCII text data in



Freed & Borenstein          Standards Track                     [Page 1]

RFC 2045                Internet Message Bodies            November 1996


   Internet mail header fields. The fourth document, RFC 2048, specifies
   various IANA registration procedures for MIME-related facilities. The
   fifth and final document, RFC 2049, describes MIME conformance
   criteria as well as providing some illustrative examples of MIME
   message formats, acknowledgements, and the bibliography.

   These documents are revisions of RFCs 1521, 1522, and 1590, which
   themselves were revisions of RFCs 1341 and 1342.  An appendix in RFC
   2049 describes differences and changes from previous versions.

Table of Contents

   1. Introduction .........................................    3
   2. Definitions, Conventions, and Generic BNF Grammar ....    5
   2.1 CRLF ................................................    5
   2.2 Character Set .......................................    6
   2.3 Message .............................................    6
   2.4 Entity ..............................................    6
   2.5 Body Part ...........................................    7
   2.6 Body ................................................    7
   2.7 7bit Data ...........................................    7
   2.8 8bit Data ...........................................    7
   2.9 Binary Data .........................................    7
   2.10 Lines ..............................................    7
   3. MIME Header Fields ...................................    8
   4. MIME-Version Header Field ............................    8
   5. Content-Type Header Field ............................   10
   5.1 Syntax of the Content-Type Header Field .............   12
   5.2 Content-Type Defaults ...............................   14
   6. Content-Transfer-Encoding Header Field ...............   14
   6.1 Content-Transfer-Encoding Syntax ....................   14
   6.2 Content-Transfer-Encodings Semantics ................   15
   6.3 New Content-Transfer-Encodings ......................   16
   6.4 Interpretation and Use ..............................   16
   6.5 Translating Encodings ...............................   18
   6.6 Canonical Encoding Model ............................   19
   6.7 Quoted-Printable Content-Transfer-Encoding ..........   19
   6.8 Base64 Content-Transfer-Encoding ....................   24
   7. Content-ID Header Field ..............................   26
   8. Content-Description Header Field .....................   27
   9. Additional MIME Header Fields ........................   27
   10. Summary .............................................   27
   11. Security Considerations .............................   27
   12. Authors' Addresses ..................................   28
   A. Collected Grammar ....................................   29






Freed & Borenstein          Standards Track                     [Page 2]

RFC 2045                Internet Message Bodies            November 1996


1.  Introduction

   Since its publication in 1982, RFC 822 has defined the standard
   format of textual mail messages on the Internet.  Its success has
   been such that the RFC 822 format has been adopted, wholly or
   partially, well beyond the confines of the Internet and the Internet
   SMTP transport defined by RFC 821.  As the format has seen wider use,
   a number of limitations have proven increasingly restrictive for the
   user community.

   RFC 822 was intended to specify a format for text messages.  As such,
   non-text messages, such as multimedia messages that might include
   audio or images, are simply not mentioned.  Even in the case of text,
   however, RFC 822 is inadequate for the needs of mail users whose
   languages require the use of character sets richer than US-ASCII.
   Since RFC 822 does not specify mechanisms for mail containing audio,
   video, Asian language text, or even text in most European languages,
   additional specifications are needed.

   One of the notable limitations of RFC 821/822 based mail systems is
   the fact that they limit the contents of electronic mail messages to
   relatively short lines (e.g. 1000 characters or less [RFC-821]) of
   7bit US-ASCII.  This forces users to convert any non-textual data
   that they may wish to send into seven-bit bytes representable as
   printable US-ASCII characters before invoking a local mail UA (User
   Agent, a program with which human users send and receive mail).
   Examples of such encodings currently used in the Internet include
   pure hexadecimal, uuencode, the 3-in-4 base 64 scheme specified in
   RFC 1421, the Andrew Toolkit Representation [ATK], and many others.

   The limitations of RFC 822 mail become even more apparent as gateways
   are designed to allow for the exchange of mail messages between RFC
   822 hosts and X.400 hosts.  X.400 [X400] specifies mechanisms for the
   inclusion of non-textual material within electronic mail messages.
   The current standards for the mapping of X.400 messages to RFC 822
   messages specify either that X.400 non-textual material must be
   converted to (not encoded in) IA5Text format, or that they must be
   discarded, notifying the RFC 822 user that discarding has occurred.
   This is clearly undesirable, as information that a user may wish to
   receive is lost.  Even though a user agent may not have the
   capability of dealing with the non-textual material, the user might
   have some mechanism external to the UA that can extract useful
   information from the material.  Moreover, it does not allow for the
   fact that the message may eventually be gatewayed back into an X.400
   message handling system (i.e., the X.400 message is "tunneled"
   through Internet mail), where the non-textual information would
   definitely become useful again.




Freed & Borenstein          Standards Track                     [Page 3]

RFC 2045                Internet Message Bodies            November 1996


   This document describes several mechanisms that combine to solve most
   of these problems without introducing any serious incompatibilities
   with the existing world of RFC 822 mail.  In particular, it
   describes:

    (1)   A MIME-Version header field, which uses a version
          number to declare a message to be conformant with MIME
          and allows mail processing agents to distinguish
          between such messages and those generated by older or
          non-conformant software, which are presumed to lack
          such a field.

    (2)   A Content-Type header field, generalized from RFC 1049,
          which can be used to specify the media type and subtype
          of data in the body of a message and to fully specify
          the native representation (canonical form) of such
          data.

    (3)   A Content-Transfer-Encoding header field, which can be
          used to specify both the encoding transformation that
          was applied to the body and the domain of the result.
          Encoding transformations other than the identity
          transformation are usually applied to data in order to
          allow it to pass through mail transport mechanisms
          which may have data or character set limitations.

    (4)   Two additional header fields that can be used to
          further describe the data in a body, the Content-ID and
          Content-Description header fields.

   All of the header fields defined in this document are subject to the
   general syntactic rules for header fields specified in RFC 822.  In
   particular, all of these header fields except for Content-Disposition
   can include RFC 822 comments, which have no semantic content and
   should be ignored during MIME processing.

   Finally, to specify and promote interoperability, RFC 2049 provides a
   basic applicability statement for a subset of the above mechanisms
   that defines a minimal level of "conformance" with this document.

   HISTORICAL NOTE:  Several of the mechanisms described in this set of
   documents may seem somewhat strange or even baroque at first reading.
   It is important to note that compatibility with existing standards
   AND robustness across existing practice were two of the highest
   priorities of the working group that developed this set of documents.
   In particular, compatibility was always favored over elegance.





Freed & Borenstein          Standards Track                     [Page 4]

RFC 2045                Internet Message Bodies            November 1996


   Please refer to the current edition of the "Internet Official
   Protocol Standards" for the standardization state and status of this
   protocol.  RFC 822 and STD 3, RFC 1123 also provide essential
   background for MIME since no conforming implementation of MIME can
   violate them.  In addition, several other informational RFC documents
   will be of interest to the MIME implementor, in particular RFC 1344,
   RFC 1345, and RFC 1524.

2.  Definitions, Conventions, and Generic BNF Grammar

   Although the mechanisms specified in this set of documents are all
   described in prose, most are also described formally in the augmented
   BNF notation of RFC 822. Implementors will need to be familiar with
   this notation in order to understand this set of documents, and are
   referred to RFC 822 for a complete explanation of the augmented BNF
   notation.

   Some of the augmented BNF in this set of documents makes named
   references to syntax rules defined in RFC 822.  A complete formal
   grammar, then, is obtained by combining the collected grammar
   appendices in each document in this set with the BNF of RFC 822 plus
   the modifications to RFC 822 defined in RFC 1123 (which specifically
   changes the syntax for `return', `date' and `mailbox').

   All numeric and octet values are given in decimal notation in this
   set of documents. All media type values, subtype values, and
   parameter names as defined are case-insensitive.  However, parameter
   values are case-sensitive unless otherwise specified for the specific
   parameter.

   FORMATTING NOTE:  Notes, such at this one, provide additional
   nonessential information which may be skipped by the reader without
   missing anything essential.  The primary purpose of these non-
   essential notes is to convey information about the rationale of this
   set of documents, or to place these documents in the proper
   historical or evolutionary context.  Such information may in
   particular be skipped by those who are focused entirely on building a
   conformant implementation, but may be of use to those who wish to
   understand why certain design choices were made.

2.1.  CRLF

   The term CRLF, in this set of documents, refers to the sequence of
   octets corresponding to the two US-ASCII characters CR (decimal value
   13) and LF (decimal value 10) which, taken together, in this order,
   denote a line break in RFC 822 mail.





Freed & Borenstein          Standards Track                     [Page 5]

RFC 2045                Internet Message Bodies            November 1996


2.2.  Character Set

   The term "character set" is used in MIME to refer to a method of
   converting a sequence of octets into a sequence of characters.  Note
   that unconditional and unambiguous conversion in the other direction
   is not required, in that not all characters may be representable by a
   given character set and a character set may provide more than one
   sequence of octets to represent a particular sequence of characters.

   This definition is intended to allow various kinds of character
   encodings, from simple single-table mappings such as US-ASCII to
   complex table switching methods such as those that use ISO 2022's
   techniques, to be used as character sets.  However, the definition
   associated with a MIME character set name must fully specify the
   mapping to be performed.  In particular, use of external profiling
   information to determine the exact mapping is not permitted.

   NOTE: The term "character set" was originally to describe such
   straightforward schemes as US-ASCII and ISO-8859-1 which have a
   simple one-to-one mapping from single octets to single characters.
   Multi-octet coded character sets and switching techniques make the
   situation more complex. For example, some communities use the term
   "character encoding" for what MIME calls a "character set", while
   using the phrase "coded character set" to denote an abstract mapping
   from integers (not octets) to characters.

2.3.  Message

   The term "message", when not further qualified, means either a
   (complete or "top-level") RFC 822 message being transferred on a
   network, or a message encapsulated in a body of type "message/rfc822"
   or "message/partial".

2.4.  Entity

   The term "entity", refers specifically to the MIME-defined header
   fields and contents of either a message or one of the parts in the
   body of a multipart entity.  The specification of such entities is
   the essence of MIME.  Since the contents of an entity are often
   called the "body", it makes sense to speak about the body of an
   entity.  Any sort of field may be present in the header of an entity,
   but only those fields whose names begin with "content-" actually have
   any MIME-related meaning.  Note that this does NOT imply thay they
   have no meaning at all -- an entity that is also a message has non-
   MIME header fields whose meanings are defined by RFC 822.






Freed & Borenstein          Standards Track                     [Page 6]

RFC 2045                Internet Message Bodies            November 1996


2.5.  Body Part

   The term "body part" refers to an entity inside of a multipart
   entity.

2.6.  Body

   The term "body", when not further qualified, means the body of an
   entity, that is, the body of either a message or of a body part.

   NOTE:  The previous four definitions are clearly circular.  This is
   unavoidable, since the overall structure of a MIME message is indeed
   recursive.

2.7.  7bit Data

   "7bit data" refers to data that is all represented as relatively
   short lines with 998 octets or less between CRLF line separation
   sequences [RFC-821].  No octets with decimal values greater than 127
   are allowed and neither are NULs (octets with decimal value 0).  CR
   (decimal value 13) and LF (decimal value 10) octets only occur as
   part of CRLF line separation sequences.

2.8.  8bit Data

   "8bit data" refers to data that is all represented as relatively
   short lines with 998 octets or less between CRLF line separation
   sequences [RFC-821]), but octets with decimal values greater than 127
   may be used.  As with "7bit data" CR and LF octets only occur as part
   of CRLF line separation sequences and no NULs are allowed.

2.9.  Binary Data

   "Binary data" refers to data where any sequence of octets whatsoever
   is allowed.

2.10.  Lines

   "Lines" are defined as sequences of octets separated by a CRLF
   sequences.  This is consistent with both RFC 821 and RFC 822.
   "Lines" only refers to a unit of data in a message, which may or may
   not correspond to something that is actually displayed by a user
   agent.








Freed & Borenstein          Standards Track                     [Page 7]

RFC 2045                Internet Message Bodies            November 1996


3.  MIME Header Fields

   MIME defines a number of new RFC 822 header fields that are used to
   describe the content of a MIME entity.  These header fields occur in
   at least two contexts:

    (1)   As part of a regular RFC 822 message header.

    (2)   In a MIME body part header within a multipart
          construct.

   The formal definition of these header fields is as follows:

     entity-headers := [ content CRLF ]
                       [ encoding CRLF ]
                       [ id CRLF ]
                       [ description CRLF ]
                       *( MIME-extension-field CRLF )

     MIME-message-headers := entity-headers
                             fields
                             version CRLF
                             ; The ordering of the header
                             ; fields implied by this BNF
                             ; definition should be ignored.

     MIME-part-headers := entity-headers
                          [ fields ]
                          ; Any field not beginning with
                          ; "content-" can have no defined
                          ; meaning and may be ignored.
                          ; The ordering of the header
                          ; fields implied by this BNF
                          ; definition should be ignored.

   The syntax of the various specific MIME header fields will be
   described in the following sections.

4.  MIME-Version Header Field

   Since RFC 822 was published in 1982, there has really been only one
   format standard for Internet messages, and there has been little
   perceived need to declare the format standard in use.  This document
   is an independent specification that complements RFC 822.  Although
   the extensions in this document have been defined in such a way as to
   be compatible with RFC 822, there are still circumstances in which it
   might be desirable for a mail-processing agent to know whether a
   message was composed with the new standard in mind.



Freed & Borenstein          Standards Track                     [Page 8]

RFC 2045                Internet Message Bodies            November 1996


   Therefore, this document defines a new header field, "MIME-Version",
   which is to be used to declare the version of the Internet message
   body format standard in use.

   Messages composed in accordance with this document MUST include such
   a header field, with the following verbatim text:

     MIME-Version: 1.0

   The presence of this header field is an assertion that the message
   has been composed in compliance with this document.

   Since it is possible that a future document might extend the message
   format standard again, a formal BNF is given for the content of the
   MIME-Version field:

     version := "MIME-Version" ":" 1*DIGIT "." 1*DIGIT

   Thus, future format specifiers, which might replace or extend "1.0",
   are constrained to be two integer fields, separated by a period.  If
   a message is received with a MIME-version value other than "1.0", it
   cannot be assumed to conform with this document.

   Note that the MIME-Version header field is required at the top level
   of a message.  It is not required for each body part of a multipart
   entity.  It is required for the embedded headers of a body of type
   "message/rfc822" or "message/partial" if and only if the embedded
   message is itself claimed to be MIME-conformant.

   It is not possible to fully specify how a mail reader that conforms
   with MIME as defined in this document should treat a message that
   might arrive in the future with some value of MIME-Version other than
   "1.0".

   It is also worth noting that version control for specific media types
   is not accomplished using the MIME-Version mechanism.  In particular,
   some formats (such as application/postscript) have version numbering
   conventions that are internal to the media format.  Where such
   conventions exist, MIME does nothing to supersede them.  Where no
   such conventions exist, a MIME media type might use a "version"
   parameter in the content-type field if necessary.










Freed & Borenstein          Standards Track                     [Page 9]

RFC 2045                Internet Message Bodies            November 1996


   NOTE TO IMPLEMENTORS:  When checking MIME-Version values any RFC 822
   comment strings that are present must be ignored.  In particular, the
   following four MIME-Version fields are equivalent:

     MIME-Version: 1.0

     MIME-Version: 1.0 (produced by MetaSend Vx.x)

     MIME-Version: (produced by MetaSend Vx.x) 1.0

     MIME-Version: 1.(produced by MetaSend Vx.x)0

   In the absence of a MIME-Version field, a receiving mail user agent
   (whether conforming to MIME requirements or not) may optionally
   choose to interpret the body of the message according to local
   conventions.  Many such conventions are currently in use and it
   should be noted that in practice non-MIME messages can contain just
   about anything.

   It is impossible to be certain that a non-MIME mail message is
   actually plain text in the US-ASCII character set since it might well
   be a message that, using some set of nonstandard local conventions
   that predate MIME, includes text in another character set or non-
   textual data presented in a manner that cannot be automatically
   recognized (e.g., a uuencoded compressed UNIX tar file).

5.  Content-Type Header Field

   The purpose of the Content-Type field is to describe the data
   contained in the body fully enough that the receiving user agent can
   pick an appropriate agent or mechanism to present the data to the
   user, or otherwise deal with the data in an appropriate manner. The
   value in this field is called a media type.

   HISTORICAL NOTE:  The Content-Type header field was first defined in
   RFC 1049.  RFC 1049 used a simpler and less powerful syntax, but one
   that is largely compatible with the mechanism given here.

   The Content-Type header field specifies the nature of the data in the
   body of an entity by giving media type and subtype identifiers, and
   by providing auxiliary information that may be required for certain
   media types.  After the media type and subtype names, the remainder
   of the header field is simply a set of parameters, specified in an
   attribute=value notation.  The ordering of parameters is not
   significant.






Freed & Borenstein          Standards Track                    [Page 10]

RFC 2045                Internet Message Bodies            November 1996


   In general, the top-level media type is used to declare the general
   type of data, while the subtype specifies a specific format for that
   type of data.  Thus, a media type of "image/xyz" is enough to tell a
   user agent that the data is an image, even if the user agent has no
   knowledge of the specific image format "xyz".  Such information can
   be used, for example, to decide whether or not to show a user the raw
   data from an unrecognized subtype -- such an action might be
   reasonable for unrecognized subtypes of text, but not for
   unrecognized subtypes of image or audio.  For this reason, registered
   subtypes of text, image, audio, and video should not contain embedded
   information that is really of a different type.  Such compound
   formats should be represented using the "multipart" or "application"
   types.

   Parameters are modifiers of the media subtype, and as such do not
   fundamentally affect the nature of the content.  The set of
   meaningful parameters depends on the media type and subtype.  Most
   parameters are associated with a single specific subtype.  However, a
   given top-level media type may define parameters which are applicable
   to any subtype of that type.  Parameters may be required by their
   defining content type or subtype or they may be optional. MIME
   implementations must ignore any parameters whose names they do not
   recognize.

   For example, the "charset" parameter is applicable to any subtype of
   "text", while the "boundary" parameter is required for any subtype of
   the "multipart" media type.

   There are NO globally-meaningful parameters that apply to all media
   types.  Truly global mechanisms are best addressed, in the MIME
   model, by the definition of additional Content-* header fields.

   An initial set of seven top-level media types is defined in RFC 2046.
   Five of these are discrete types whose content is essentially opaque
   as far as MIME processing is concerned.  The remaining two are
   composite types whose contents require additional handling by MIME
   processors.

   This set of top-level media types is intended to be substantially
   complete.  It is expected that additions to the larger set of
   supported types can generally be accomplished by the creation of new
   subtypes of these initial types.  In the future, more top-level types
   may be defined only by a standards-track extension to this standard.
   If another top-level type is to be used for any reason, it must be
   given a name starting with "X-" to indicate its non-standard status
   and to avoid a potential conflict with a future official name.





Freed & Borenstein          Standards Track                    [Page 11]

RFC 2045                Internet Message Bodies            November 1996


5.1.  Syntax of the Content-Type Header Field

   In the Augmented BNF notation of RFC 822, a Content-Type header field
   value is defined as follows:

     content := "Content-Type" ":" type "/" subtype
                *(";" parameter)
                ; Matching of media type and subtype
                ; is ALWAYS case-insensitive.

     type := discrete-type / composite-type

     discrete-type := "text" / "image" / "audio" / "video" /
                      "application" / extension-token

     composite-type := "message" / "multipart" / extension-token

     extension-token := ietf-token / x-token

     ietf-token := <An extension token defined by a
                    standards-track RFC and registered
                    with IANA.>

     x-token := <The two characters "X-" or "x-" followed, with
                 no intervening white space, by any token>

     subtype := extension-token / iana-token

     iana-token := <A publicly-defined extension token. Tokens
                    of this form must be registered with IANA
                    as specified in RFC 2048.>

     parameter := attribute "=" value

     attribute := token
                  ; Matching of attributes
                  ; is ALWAYS case-insensitive.

     value := token / quoted-string

     token := 1*<any (US-ASCII) CHAR except SPACE, CTLs,
                 or tspecials>

     tspecials :=  "(" / ")" / "<" / ">" / "@" /
                   "," / ";" / ":" / "\" / <">
                   "/" / "[" / "]" / "?" / "="
                   ; Must be in quoted-string,
                   ; to use within parameter values



Freed & Borenstein          Standards Track                    [Page 12]

RFC 2045                Internet Message Bodies            November 1996


   Note that the definition of "tspecials" is the same as the RFC 822
   definition of "specials" with the addition of the three characters
   "/", "?", and "=", and the removal of ".".

   Note also that a subtype specification is MANDATORY -- it may not be
   omitted from a Content-Type header field.  As such, there are no
   default subtypes.

   The type, subtype, and parameter names are not case sensitive.  For
   example, TEXT, Text, and TeXt are all equivalent top-level media
   types.  Parameter values are normally case sensitive, but sometimes
   are interpreted in a case-insensitive fashion, depending on the
   intended use.  (For example, multipart boundaries are case-sensitive,
   but the "access-type" parameter for message/External-body is not
   case-sensitive.)

   Note that the value of a quoted string parameter does not include the
   quotes.  That is, the quotation marks in a quoted-string are not a
   part of the value of the parameter, but are merely used to delimit
   that parameter value.  In addition, comments are allowed in
   accordance with RFC 822 rules for structured header fields.  Thus the
   following two forms

     Content-type: text/plain; charset=us-ascii (Plain text)

     Content-type: text/plain; charset="us-ascii"

   are completely equivalent.

   Beyond this syntax, the only syntactic constraint on the definition
   of subtype names is the desire that their uses must not conflict.
   That is, it would be undesirable to have two different communities
   using "Content-Type: application/foobar" to mean two different
   things.  The process of defining new media subtypes, then, is not
   intended to be a mechanism for imposing restrictions, but simply a
   mechanism for publicizing their definition and usage.  There are,
   therefore, two acceptable mechanisms for defining new media subtypes:

    (1)   Private values (starting with "X-") may be defined
          bilaterally between two cooperating agents without
          outside registration or standardization. Such values
          cannot be registered or standardized.

    (2)   New standard values should be registered with IANA as
          described in RFC 2048.

   The second document in this set, RFC 2046, defines the initial set of
   media types for MIME.



Freed & Borenstein          Standards Track                    [Page 13]

RFC 2045                Internet Message Bodies            November 1996


5.2.  Content-Type Defaults

   Default RFC 822 messages without a MIME Content-Type header are taken
   by this protocol to be plain text in the US-ASCII character set,
   which can be explicitly specified as:

     Content-type: text/plain; charset=us-ascii

   This default is assumed if no Content-Type header field is specified.
   It is also recommend that this default be assumed when a
   syntactically invalid Content-Type header field is encountered. In
   the presence of a MIME-Version header field and the absence of any
   Content-Type header field, a receiving User Agent can also assume
   that plain US-ASCII text was the sender's intent.  Plain US-ASCII
   text may still be assumed in the absence of a MIME-Version or the
   presence of an syntactically invalid Content-Type header field, but
   the sender's intent might have been otherwise.

6.  Content-Transfer-Encoding Header Field

   Many media types which could be usefully transported via email are
   represented, in their "natural" format, as 8bit character or binary
   data.  Such data cannot be transmitted over some transfer protocols.
   For example, RFC 821 (SMTP) restricts mail messages to 7bit US-ASCII
   data with lines no longer than 1000 characters including any trailing
   CRLF line separator.

   It is necessary, therefore, to define a standard mechanism for
   encoding such data into a 7bit short line format.  Proper labelling
   of unencoded material in less restrictive formats for direct use over
   less restrictive transports is also desireable.  This document
   specifies that such encodings will be indicated by a new "Content-
   Transfer-Encoding" header field.  This field has not been defined by
   any previous standard.

6.1.  Content-Transfer-Encoding Syntax

   The Content-Transfer-Encoding field's value is a single token
   specifying the type of encoding, as enumerated below.  Formally:

     encoding := "Content-Transfer-Encoding" ":" mechanism

     mechanism := "7bit" / "8bit" / "binary" /
                  "quoted-printable" / "base64" /
                  ietf-token / x-token

   These values are not case sensitive -- Base64 and BASE64 and bAsE64
   are all equivalent.  An encoding type of 7BIT requires that the body



Freed & Borenstein          Standards Track                    [Page 14]

RFC 2045                Internet Message Bodies            November 1996


   is already in a 7bit mail-ready representation.  This is the default
   value -- that is, "Content-Transfer-Encoding: 7BIT" is assumed if the
   Content-Transfer-Encoding header field is not present.

6.2.  Content-Transfer-Encodings Semantics

   This single Content-Transfer-Encoding token actually provides two
   pieces of information.  It specifies what sort of encoding
   transformation the body was subjected to and hence what decoding
   operation must be used to restore it to its original form, and it
   specifies what the domain of the result is.

   The transformation part of any Content-Transfer-Encodings specifies,
   either explicitly or implicitly, a single, well-defined decoding
   algorithm, which for any sequence of encoded octets either transforms
   it to the original sequence of octets which was encoded, or shows
   that it is illegal as an encoded sequence.  Content-Transfer-
   Encodings transformations never depend on any additional external
   profile information for proper operation. Note that while decoders
   must produce a single, well-defined output for a valid encoding no
   such restrictions exist for encoders: Encoding a given sequence of
   octets to different, equivalent encoded sequences is perfectly legal.

   Three transformations are currently defined: identity, the "quoted-
   printable" encoding, and the "base64" encoding.  The domains are
   "binary", "8bit" and "7bit".

   The Content-Transfer-Encoding values "7bit", "8bit", and "binary" all
   mean that the identity (i.e. NO) encoding transformation has been
   performed.  As such, they serve simply as indicators of the domain of
   the body data, and provide useful information about the sort of
   encoding that might be needed for transmission in a given transport
   system.  The terms "7bit data", "8bit data", and "binary data" are
   all defined in Section 2.

   The quoted-printable and base64 encodings transform their input from
   an arbitrary domain into material in the "7bit" range, thus making it
   safe to carry over restricted transports.  The specific definition of
   the transformations are given below.

   The proper Content-Transfer-Encoding label must always be used.
   Labelling unencoded data containing 8bit characters as "7bit" is not
   allowed, nor is labelling unencoded non-line-oriented data as
   anything other than "binary" allowed.

   Unlike media subtypes, a proliferation of Content-Transfer-Encoding
   values is both undesirable and unnecessary.  However, establishing
   only a single transformation into the "7bit" domain does not seem



Freed & Borenstein          Standards Track                    [Page 15]

RFC 2045                Internet Message Bodies            November 1996


   possible.  There is a tradeoff between the desire for a compact and
   efficient encoding of largely- binary data and the desire for a
   somewhat readable encoding of data that is mostly, but not entirely,
   7bit.  For this reason, at least two encoding mechanisms are
   necessary: a more or less readable encoding (quoted-printable) and a
   "dense" or "uniform" encoding (base64).

   Mail transport for unencoded 8bit data is defined in RFC 1652.  As of
   the initial publication of this document, there are no standardized
   Internet mail transports for which it is legitimate to include
   unencoded binary data in mail bodies.  Thus there are no
   circumstances in which the "binary" Content-Transfer-Encoding is
   actually valid in Internet mail.  However, in the event that binary
   mail transport becomes a reality in Internet mail, or when MIME is
   used in conjunction with any other binary-capable mail transport
   mechanism, binary bodies must be labelled as such using this
   mechanism.

   NOTE: The five values defined for the Content-Transfer-Encoding field
   imply nothing about the media type other than the algorithm by which
   it was encoded or the transport system requirements if unencoded.

6.3.  New Content-Transfer-Encodings

   Implementors may, if necessary, define private Content-Transfer-
   Encoding values, but must use an x-token, which is a name prefixed by
   "X-", to indicate its non-standard status, e.g., "Content-Transfer-
   Encoding: x-my-new-encoding".  Additional standardized Content-
   Transfer-Encoding values must be specified by a standards-track RFC.
   The requirements such specifications must meet are given in RFC 2048.
   As such, all content-transfer-encoding namespace except that
   beginning with "X-" is explicitly reserved to the IETF for future
   use.

   Unlike media types and subtypes, the creation of new Content-
   Transfer-Encoding values is STRONGLY discouraged, as it seems likely
   to hinder interoperability with little potential benefit

6.4.  Interpretation and Use

   If a Content-Transfer-Encoding header field appears as part of a
   message header, it applies to the entire body of that message.  If a
   Content-Transfer-Encoding header field appears as part of an entity's
   headers, it applies only to the body of that entity.  If an entity is
   of type "multipart" the Content-Transfer-Encoding is not permitted to
   have any value other than "7bit", "8bit" or "binary".  Even more
   severe restrictions apply to some subtypes of the "message" type.




Freed & Borenstein          Standards Track                    [Page 16]

RFC 2045                Internet Message Bodies            November 1996


   It should be noted that most media types are defined in terms of
   octets rather than bits, so that the mechanisms described here are
   mechanisms for encoding arbitrary octet streams, not bit streams.  If
   a bit stream is to be encoded via one of these mechanisms, it must
   first be converted to an 8bit byte stream using the network standard
   bit order ("big-endian"), in which the earlier bits in a stream
   become the higher-order bits in a 8bit byte.  A bit stream not ending
   at an 8bit boundary must be padded with zeroes. RFC 2046 provides a
   mechanism for noting the addition of such padding in the case of the
   application/octet-stream media type, which has a "padding" parameter.

   The encoding mechanisms defined here explicitly encode all data in
   US-ASCII.  Thus, for example, suppose an entity has header fields
   such as:

     Content-Type: text/plain; charset=ISO-8859-1
     Content-transfer-encoding: base64

   This must be interpreted to mean that the body is a base64 US-ASCII
   encoding of data that was originally in ISO-8859-1, and will be in
   that character set again after decoding.

   Certain Content-Transfer-Encoding values may only be used on certain
   media types.  In particular, it is EXPRESSLY FORBIDDEN to use any
   encodings other than "7bit", "8bit", or "binary" with any composite
   media type, i.e. one that recursively includes other Content-Type
   fields.  Currently the only composite media types are "multipart" and
   "message".  All encodings that are desired for bodies of type
   multipart or message must be done at the innermost level, by encoding
   the actual body that needs to be encoded.

   It should also be noted that, by definition, if a composite entity
   has a transfer-encoding value such as "7bit", but one of the enclosed
   entities has a less restrictive value such as "8bit", then either the
   outer "7bit" labelling is in error, because 8bit data are included,
   or the inner "8bit" labelling placed an unnecessarily high demand on
   the transport system because the actual included data were actually
   7bit-safe.

   NOTE ON ENCODING RESTRICTIONS:  Though the prohibition against using
   content-transfer-encodings on composite body data may seem overly
   restrictive, it is necessary to prevent nested encodings, in which
   data are passed through an encoding algorithm multiple times, and
   must be decoded multiple times in order to be properly viewed.
   Nested encodings add considerable complexity to user agents:  Aside
   from the obvious efficiency problems with such multiple encodings,
   they can obscure the basic structure of a message.  In particular,
   they can imply that several decoding operations are necessary simply



Freed & Borenstein          Standards Track                    [Page 17]

RFC 2045                Internet Message Bodies            November 1996


   to find out what types of bodies a message contains.  Banning nested
   encodings may complicate the job of certain mail gateways, but this
   seems less of a problem than the effect of nested encodings on user
   agents.

   Any entity with an unrecognized Content-Transfer-Encoding must be
   treated as if it has a Content-Type of "application/octet-stream",
   regardless of what the Content-Type header field actually says.

   NOTE ON THE RELATIONSHIP BETWEEN CONTENT-TYPE AND CONTENT-TRANSFER-
   ENCODING: It may seem that the Content-Transfer-Encoding could be
   inferred from the characteristics of the media that is to be encoded,
   or, at the very least, that certain Content-Transfer-Encodings could
   be mandated for use with specific media types.  There are several
   reasons why this is not the case. First, given the varying types of
   transports used for mail, some encodings may be appropriate for some
   combinations of media types and transports but not for others.  (For
   example, in an 8bit transport, no encoding would be required for text
   in certain character sets, while such encodings are clearly required
   for 7bit SMTP.)

   Second, certain media types may require different types of transfer
   encoding under different circumstances.  For example, many PostScript
   bodies might consist entirely of short lines of 7bit data and hence
   require no encoding at all.  Other PostScript bodies (especially
   those using Level 2 PostScript's binary encoding mechanism) may only
   be reasonably represented using a binary transport encoding.
   Finally, since the Content-Type field is intended to be an open-ended
   specification mechanism, strict specification of an association
   between media types and encodings effectively couples the
   specification of an application protocol with a specific lower-level
   transport.  This is not desirable since the developers of a media
   type should not have to be aware of all the transports in use and
   what their limitations are.

6.5.  Translating Encodings

   The quoted-printable and base64 encodings are designed so that
   conversion between them is possible.  The only issue that arises in
   such a conversion is the handling of hard line breaks in quoted-
   printable encoding output. When converting from quoted-printable to
   base64 a hard line break in the quoted-printable form represents a
   CRLF sequence in the canonical form of the data. It must therefore be
   converted to a corresponding encoded CRLF in the base64 form of the
   data.  Similarly, a CRLF sequence in the canonical form of the data
   obtained after base64 decoding must be converted to a quoted-
   printable hard line break, but ONLY when converting text data.




Freed & Borenstein          Standards Track                    [Page 18]

RFC 2045                Internet Message Bodies            November 1996


6.6.  Canonical Encoding Model

   There was some confusion, in the previous versions of this RFC,
   regarding the model for when email data was to be converted to
   canonical form and encoded, and in particular how this process would
   affect the treatment of CRLFs, given that the representation of
   newlines varies greatly from system to system, and the relationship
   between content-transfer-encodings and character sets.  A canonical
   model for encoding is presented in RFC 2049 for this reason.

6.7.  Quoted-Printable Content-Transfer-Encoding

   The Quoted-Printable encoding is intended to represent data that
   largely consists of octets that correspond to printable characters in
   the US-ASCII character set.  It encodes the data in such a way that
   the resulting octets are unlikely to be modified by mail transport.
   If the data being encoded are mostly US-ASCII text, the encoded form
   of the data remains largely recognizable by humans.  A body which is
   entirely US-ASCII may also be encoded in Quoted-Printable to ensure
   the integrity of the data should the message pass through a
   character-translating, and/or line-wrapping gateway.

   In this encoding, octets are to be represented as determined by the
   following rules:

    (1)   (General 8bit representation) Any octet, except a CR or
          LF that is part of a CRLF line break of the canonical
          (standard) form of the data being encoded, may be
          represented by an "=" followed by a two digit
          hexadecimal representation of the octet's value.  The
          digits of the hexadecimal alphabet, for this purpose,
          are "0123456789ABCDEF".  Uppercase letters must be
          used; lowercase letters are not allowed.  Thus, for
          example, the decimal value 12 (US-ASCII form feed) can
          be represented by "=0C", and the decimal value 61 (US-
          ASCII EQUAL SIGN) can be represented by "=3D".  This
          rule must be followed except when the following rules
          allow an alternative encoding.

    (2)   (Literal representation) Octets with decimal values of
          33 through 60 inclusive, and 62 through 126, inclusive,
          MAY be represented as the US-ASCII characters which
          correspond to those octets (EXCLAMATION POINT through
          LESS THAN, and GREATER THAN through TILDE,
          respectively).

    (3)   (White Space) Octets with values of 9 and 32 MAY be
          represented as US-ASCII TAB (HT) and SPACE characters,



Freed & Borenstein          Standards Track                    [Page 19]

RFC 2045                Internet Message Bodies            November 1996


          respectively, but MUST NOT be so represented at the end
          of an encoded line.  Any TAB (HT) or SPACE characters
          on an encoded line MUST thus be followed on that line
          by a printable character.  In particular, an "=" at the
          end of an encoded line, indicating a soft line break
          (see rule #5) may follow one or more TAB (HT) or SPACE
          characters.  It follows that an octet with decimal
          value 9 or 32 appearing at the end of an encoded line
          must be represented according to Rule #1.  This rule is
          necessary because some MTAs (Message Transport Agents,
          programs which transport messages from one user to
          another, or perform a portion of such transfers) are
          known to pad lines of text with SPACEs, and others are
          known to remove "white space" characters from the end
          of a line.  Therefore, when decoding a Quoted-Printable
          body, any trailing white space on a line must be
          deleted, as it will necessarily have been added by
          intermediate transport agents.

    (4)   (Line Breaks) A line break in a text body, represented
          as a CRLF sequence in the text canonical form, must be
          represented by a (RFC 822) line break, which is also a
          CRLF sequence, in the Quoted-Printable encoding.  Since
          the canonical representation of media types other than
          text do not generally include the representation of
          line breaks as CRLF sequences, no hard line breaks
          (i.e. line breaks that are intended to be meaningful
          and to be displayed to the user) can occur in the
          quoted-printable encoding of such types.  Sequences
          like "=0D", "=0A", "=0A=0D" and "=0D=0A" will routinely
          appear in non-text data represented in quoted-
          printable, of course.

          Note that many implementations may elect to encode the
          local representation of various content types directly
          rather than converting to canonical form first,
          encoding, and then converting back to local
          representation.  In particular, this may apply to plain
          text material on systems that use newline conventions
          other than a CRLF terminator sequence.  Such an
          implementation optimization is permissible, but only
          when the combined canonicalization-encoding step is
          equivalent to performing the three steps separately.

    (5)   (Soft Line Breaks) The Quoted-Printable encoding
          REQUIRES that encoded lines be no more than 76
          characters long.  If longer lines are to be encoded
          with the Quoted-Printable encoding, "soft" line breaks



Freed & Borenstein          Standards Track                    [Page 20]

RFC 2045                Internet Message Bodies            November 1996


          must be used.  An equal sign as the last character on a
          encoded line indicates such a non-significant ("soft")
          line break in the encoded text.

   Thus if the "raw" form of the line is a single unencoded line that
   says:

     Now's the time for all folk to come to the aid of their country.

   This can be represented, in the Quoted-Printable encoding, as:

     Now's the time =
     for all folk to come=
      to the aid of their country.

   This provides a mechanism with which long lines are encoded in such a
   way as to be restored by the user agent.  The 76 character limit does
   not count the trailing CRLF, but counts all other characters,
   including any equal signs.

   Since the hyphen character ("-") may be represented as itself in the
   Quoted-Printable encoding, care must be taken, when encapsulating a
   quoted-printable encoded body inside one or more multipart entities,
   to ensure that the boundary delimiter does not appear anywhere in the
   encoded body.  (A good strategy is to choose a boundary that includes
   a character sequence such as "=_" which can never appear in a
   quoted-printable body.  See the definition of multipart messages in
   RFC 2046.)

   NOTE: The quoted-printable encoding represents something of a
   compromise between readability and reliability in transport.  Bodies
   encoded with the quoted-printable encoding will work reliably over
   most mail gateways, but may not work perfectly over a few gateways,
   notably those involving translation into EBCDIC.  A higher level of
   confidence is offered by the base64 Content-Transfer-Encoding.  A way
   to get reasonably reliable transport through EBCDIC gateways is to
   also quote the US-ASCII characters

     !"#$@[\]^`{|}~

   according to rule #1.

   Because quoted-printable data is generally assumed to be line-
   oriented, it is to be expected that the representation of the breaks
   between the lines of quoted-printable data may be altered in
   transport, in the same manner that plain text mail has always been
   altered in Internet mail when passing between systems with differing
   newline conventions.  If such alterations are likely to constitute a



Freed & Borenstein          Standards Track                    [Page 21]

RFC 2045                Internet Message Bodies            November 1996


   corruption of the data, it is probably more sensible to use the
   base64 encoding rather than the quoted-printable encoding.

   NOTE: Several kinds of substrings cannot be generated according to
   the encoding rules for the quoted-printable content-transfer-
   encoding, and hence are formally illegal if they appear in the output
   of a quoted-printable encoder. This note enumerates these cases and
   suggests ways to handle such illegal substrings if any are
   encountered in quoted-printable data that is to be decoded.

    (1)   An "=" followed by two hexadecimal digits, one or both
          of which are lowercase letters in "abcdef", is formally
          illegal. A robust implementation might choose to
          recognize them as the corresponding uppercase letters.

    (2)   An "=" followed by a character that is neither a
          hexadecimal digit (including "abcdef") nor the CR
          character of a CRLF pair is illegal.  This case can be
          the result of US-ASCII text having been included in a
          quoted-printable part of a message without itself
          having been subjected to quoted-printable encoding.  A
          reasonable approach by a robust implementation might be
          to include the "=" character and the following
          character in the decoded data without any
          transformation and, if possible, indicate to the user
          that proper decoding was not possible at this point in
          the data.

    (3)   An "=" cannot be the ultimate or penultimate character
          in an encoded object.  This could be handled as in case
          (2) above.

    (4)   Control characters other than TAB, or CR and LF as
          parts of CRLF pairs, must not appear. The same is true
          for octets with decimal values greater than 126.  If
          found in incoming quoted-printable data by a decoder, a
          robust implementation might exclude them from the
          decoded data and warn the user that illegal characters
          were discovered.

    (5)   Encoded lines must not be longer than 76 characters,
          not counting the trailing CRLF. If longer lines are
          found in incoming, encoded data, a robust
          implementation might nevertheless decode the lines, and
          might report the erroneous encoding to the user.






Freed & Borenstein          Standards Track                    [Page 22]

RFC 2045                Internet Message Bodies            November 1996


   WARNING TO IMPLEMENTORS:  If binary data is encoded in quoted-
   printable, care must be taken to encode CR and LF characters as "=0D"
   and "=0A", respectively.  In particular, a CRLF sequence in binary
   data should be encoded as "=0D=0A".  Otherwise, if CRLF were
   represented as a hard line break, it might be incorrectly decoded on
   platforms with different line break conventions.

   For formalists, the syntax of quoted-printable data is described by
   the following grammar:

     quoted-printable := qp-line *(CRLF qp-line)

     qp-line := *(qp-segment transport-padding CRLF)
                qp-part transport-padding

     qp-part := qp-section
                ; Maximum length of 76 characters

     qp-segment := qp-section *(SPACE / TAB) "="
                   ; Maximum length of 76 characters

     qp-section := [*(ptext / SPACE / TAB) ptext]

     ptext := hex-octet / safe-char

     safe-char := <any octet with decimal value of 33 through
                  60 inclusive, and 62 through 126>
                  ; Characters not listed as "mail-safe" in
                  ; RFC 2049 are also not recommended.

     hex-octet := "=" 2(DIGIT / "A" / "B" / "C" / "D" / "E" / "F")
                  ; Octet must be used for characters > 127, =,
                  ; SPACEs or TABs at the ends of lines, and is
                  ; recommended for any character not listed in
                  ; RFC 2049 as "mail-safe".

     transport-padding := *LWSP-char
                          ; Composers MUST NOT generate
                          ; non-zero length transport
                          ; padding, but receivers MUST
                          ; be able to handle padding
                          ; added by message transports.

   IMPORTANT:  The addition of LWSP between the elements shown in this
   BNF is NOT allowed since this BNF does not specify a structured
   header field.





Freed & Borenstein          Standards Track                    [Page 23]

RFC 2045                Internet Message Bodies            November 1996


6.8.  Base64 Content-Transfer-Encoding

   The Base64 Content-Transfer-Encoding is designed to represent
   arbitrary sequences of octets in a form that need not be humanly
   readable.  The encoding and decoding algorithms are simple, but the
   encoded data are consistently only about 33 percent larger than the
   unencoded data.  This encoding is virtually identical to the one used
   in Privacy Enhanced Mail (PEM) applications, as defined in RFC 1421.

   A 65-character subset of US-ASCII is used, enabling 6 bits to be
   represented per printable character. (The extra 65th character, "=",
   is used to signify a special processing function.)

   NOTE:  This subset has the important property that it is represented
   identically in all versions of ISO 646, including US-ASCII, and all
   characters in the subset are also represented identically in all
   versions of EBCDIC. Other popular encodings, such as the encoding
   used by the uuencode utility, Macintosh binhex 4.0 [RFC-1741], and
   the base85 encoding specified as part of Level 2 PostScript, do not
   share these properties, and thus do not fulfill the portability
   requirements a binary transport encoding for mail must meet.

   The encoding process represents 24-bit groups of input bits as output
   strings of 4 encoded characters.  Proceeding from left to right, a
   24-bit input group is formed by concatenating 3 8bit input groups.
   These 24 bits are then treated as 4 concatenated 6-bit groups, each
   of which is translated into a single digit in the base64 alphabet.
   When encoding a bit stream via the base64 encoding, the bit stream
   must be presumed to be ordered with the most-significant-bit first.
   That is, the first bit in the stream will be the high-order bit in
   the first 8bit byte, and the eighth bit will be the low-order bit in
   the first 8bit byte, and so on.

   Each 6-bit group is used as an index into an array of 64 printable
   characters.  The character referenced by the index is placed in the
   output string.  These characters, identified in Table 1, below, are
   selected so as to be universally representable, and the set excludes
   characters with particular significance to SMTP (e.g., ".", CR, LF)
   and to the multipart boundary delimiters defined in RFC 2046 (e.g.,
   "-").











Freed & Borenstein          Standards Track                    [Page 24]

RFC 2045                Internet Message Bodies            November 1996


                    Table 1: The Base64 Alphabet

     Value Encoding  Value Encoding  Value Encoding  Value Encoding
         0 A            17 R            34 i            51 z
         1 B            18 S            35 j            52 0
         2 C            19 T            36 k            53 1
         3 D            20 U            37 l            54 2
         4 E            21 V            38 m            55 3
         5 F            22 W            39 n            56 4
         6 G            23 X            40 o            57 5
         7 H            24 Y            41 p            58 6
         8 I            25 Z            42 q            59 7
         9 J            26 a            43 r            60 8
        10 K            27 b            44 s            61 9
        11 L            28 c            45 t            62 +
        12 M            29 d            46 u            63 /
        13 N            30 e            47 v
        14 O            31 f            48 w         (pad) =
        15 P            32 g            49 x
        16 Q            33 h            50 y

   The encoded output stream must be represented in lines of no more
   than 76 characters each.  All line breaks or other characters not
   found in Table 1 must be ignored by decoding software.  In base64
   data, characters other than those in Table 1, line breaks, and other
   white space probably indicate a transmission error, about which a
   warning message or even a message rejection might be appropriate
   under some circumstances.

   Special processing is performed if fewer than 24 bits are available
   at the end of the data being encoded.  A full encoding quantum is
   always completed at the end of a body.  When fewer than 24 input bits
   are available in an input group, zero bits are added (on the right)
   to form an integral number of 6-bit groups.  Padding at the end of
   the data is performed using the "=" character.  Since all base64
   input is an integral number of octets, only the following cases can
   arise: (1) the final quantum of encoding input is an integral
   multiple of 24 bits; here, the final unit of encoded output will be
   an integral multiple of 4 characters with no "=" padding, (2) the
   final quantum of encoding input is exactly 8 bits; here, the final
   unit of encoded output will be two characters followed by two "="
   padding characters, or (3) the final quantum of encoding input is
   exactly 16 bits; here, the final unit of encoded output will be three
   characters followed by one "=" padding character.

   Because it is used only for padding at the end of the data, the
   occurrence of any "=" characters may be taken as evidence that the
   end of the data has been reached (without truncation in transit).  No



Freed & Borenstein          Standards Track                    [Page 25]

RFC 2045                Internet Message Bodies            November 1996


   such assurance is possible, however, when the number of octets
   transmitted was a multiple of three and no "=" characters are
   present.

   Any characters outside of the base64 alphabet are to be ignored in
   base64-encoded data.

   Care must be taken to use the proper octets for line breaks if base64
   encoding is applied directly to text material that has not been
   converted to canonical form.  In particular, text line breaks must be
   converted into CRLF sequences prior to base64 encoding.  The
   important thing to note is that this may be done directly by the
   encoder rather than in a prior canonicalization step in some
   implementations.

   NOTE: There is no need to worry about quoting potential boundary
   delimiters within base64-encoded bodies within multipart entities
   because no hyphen characters are used in the base64 encoding.

7.  Content-ID Header Field

   In constructing a high-level user agent, it may be desirable to allow
   one body to make reference to another.  Accordingly, bodies may be
   labelled using the "Content-ID" header field, which is syntactically
   identical to the "Message-ID" header field:

     id := "Content-ID" ":" msg-id

   Like the Message-ID values, Content-ID values must be generated to be
   world-unique.

   The Content-ID value may be used for uniquely identifying MIME
   entities in several contexts, particularly for caching data
   referenced by the message/external-body mechanism.  Although the
   Content-ID header is generally optional, its use is MANDATORY in
   implementations which generate data of the optional MIME media type
   "message/external-body".  That is, each message/external-body entity
   must have a Content-ID field to permit caching of such data.

   It is also worth noting that the Content-ID value has special
   semantics in the case of the multipart/alternative media type.  This
   is explained in the section of RFC 2046 dealing with
   multipart/alternative.








Freed & Borenstein          Standards Track                    [Page 26]

RFC 2045                Internet Message Bodies            November 1996


8.  Content-Description Header Field

   The ability to associate some descriptive information with a given
   body is often desirable.  For example, it may be useful to mark an
   "image" body as "a picture of the Space Shuttle Endeavor."  Such text
   may be placed in the Content-Description header field.  This header
   field is always optional.

     description := "Content-Description" ":" *text

   The description is presumed to be given in the US-ASCII character
   set, although the mechanism specified in RFC 2047 may be used for
   non-US-ASCII Content-Description values.

9.  Additional MIME Header Fields

   Future documents may elect to define additional MIME header fields
   for various purposes.  Any new header field that further describes
   the content of a message should begin with the string "Content-" to
   allow such fields which appear in a message header to be
   distinguished from ordinary RFC 822 message header fields.

     MIME-extension-field := <Any RFC 822 header field which
                              begins with the string
                              "Content-">

10.  Summary

   Using the MIME-Version, Content-Type, and Content-Transfer-Encoding
   header fields, it is possible to include, in a standardized way,
   arbitrary types of data with RFC 822 conformant mail messages.  No
   restrictions imposed by either RFC 821 or RFC 822 are violated, and
   care has been taken to avoid problems caused by additional
   restrictions imposed by the characteristics of some Internet mail
   transport mechanisms (see RFC 2049).

   The next document in this set, RFC 2046, specifies the initial set of
   media types that can be labelled and transported using these headers.

11.  Security Considerations

   Security issues are discussed in the second document in this set, RFC
   2046.








Freed & Borenstein          Standards Track                    [Page 27]

RFC 2045                Internet Message Bodies            November 1996


12.  Authors' Addresses

   For more information, the authors of this document are best contacted
   via Internet mail:

   Ned Freed
   Innosoft International, Inc.
   1050 East Garvey Avenue South
   West Covina, CA 91790
   USA

   Phone: +1 818 919 3600
   Fax:   +1 818 919 3614
   EMail: ned@innosoft.com


   Nathaniel S. Borenstein
   First Virtual Holdings
   25 Washington Avenue
   Morristown, NJ 07960
   USA

   Phone: +1 201 540 8967
   Fax:   +1 201 993 3032
   EMail: nsb@nsb.fv.com


   MIME is a result of the work of the Internet Engineering Task Force
   Working Group on RFC 822 Extensions.  The chairman of that group,
   Greg Vaudreuil, may be reached at:

   Gregory M. Vaudreuil
   Octel Network Services
   17080 Dallas Parkway
   Dallas, TX 75248-1905
   USA

   EMail: Greg.Vaudreuil@Octel.Com













Freed & Borenstein          Standards Track                    [Page 28]

RFC 2045                Internet Message Bodies            November 1996


Appendix A -- Collected Grammar

   This appendix contains the complete BNF grammar for all the syntax
   specified by this document.

   By itself, however, this grammar is incomplete.  It refers by name to
   several syntax rules that are defined by RFC 822.  Rather than
   reproduce those definitions here, and risk unintentional differences
   between the two, this document simply refers the reader to RFC 822
   for the remaining definitions. Wherever a term is undefined, it
   refers to the RFC 822 definition.

  attribute := token
               ; Matching of attributes
               ; is ALWAYS case-insensitive.

  composite-type := "message" / "multipart" / extension-token

  content := "Content-Type" ":" type "/" subtype
             *(";" parameter)
             ; Matching of media type and subtype
             ; is ALWAYS case-insensitive.

  description := "Content-Description" ":" *text

  discrete-type := "text" / "image" / "audio" / "video" /
                   "application" / extension-token

  encoding := "Content-Transfer-Encoding" ":" mechanism

  entity-headers := [ content CRLF ]
                    [ encoding CRLF ]
                    [ id CRLF ]
                    [ description CRLF ]
                    *( MIME-extension-field CRLF )

  extension-token := ietf-token / x-token

  hex-octet := "=" 2(DIGIT / "A" / "B" / "C" / "D" / "E" / "F")
               ; Octet must be used for characters > 127, =,
               ; SPACEs or TABs at the ends of lines, and is
               ; recommended for any character not listed in
               ; RFC 2049 as "mail-safe".

  iana-token := <A publicly-defined extension token. Tokens
                 of this form must be registered with IANA
                 as specified in RFC 2048.>




Freed & Borenstein          Standards Track                    [Page 29]

RFC 2045                Internet Message Bodies            November 1996


  ietf-token := <An extension token defined by a
                 standards-track RFC and registered
                 with IANA.>

  id := "Content-ID" ":" msg-id

  mechanism := "7bit" / "8bit" / "binary" /
               "quoted-printable" / "base64" /
               ietf-token / x-token

  MIME-extension-field := <Any RFC 822 header field which
                           begins with the string
                           "Content-">

  MIME-message-headers := entity-headers
                          fields
                          version CRLF
                          ; The ordering of the header
                          ; fields implied by this BNF
                          ; definition should be ignored.

  MIME-part-headers := entity-headers
                       [fields]
                       ; Any field not beginning with
                       ; "content-" can have no defined
                       ; meaning and may be ignored.
                       ; The ordering of the header
                       ; fields implied by this BNF
                       ; definition should be ignored.

  parameter := attribute "=" value

  ptext := hex-octet / safe-char

  qp-line := *(qp-segment transport-padding CRLF)
             qp-part transport-padding

  qp-part := qp-section
             ; Maximum length of 76 characters

  qp-section := [*(ptext / SPACE / TAB) ptext]

  qp-segment := qp-section *(SPACE / TAB) "="
                ; Maximum length of 76 characters

  quoted-printable := qp-line *(CRLF qp-line)





Freed & Borenstein          Standards Track                    [Page 30]

RFC 2045                Internet Message Bodies            November 1996


  safe-char := <any octet with decimal value of 33 through
               60 inclusive, and 62 through 126>
               ; Characters not listed as "mail-safe" in
               ; RFC 2049 are also not recommended.

  subtype := extension-token / iana-token

  token := 1*<any (US-ASCII) CHAR except SPACE, CTLs,
              or tspecials>

  transport-padding := *LWSP-char
                       ; Composers MUST NOT generate
                       ; non-zero length transport
                       ; padding, but receivers MUST
                       ; be able to handle padding
                       ; added by message transports.

  tspecials :=  "(" / ")" / "<" / ">" / "@" /
                "," / ";" / ":" / "\" / <">
                "/" / "[" / "]" / "?" / "="
                ; Must be in quoted-string,
                ; to use within parameter values

  type := discrete-type / composite-type

  value := token / quoted-string

  version := "MIME-Version" ":" 1*DIGIT "." 1*DIGIT

  x-token := <The two characters "X-" or "x-" followed, with
              no  intervening white space, by any token>




















Freed & Borenstein          Standards Track                    [Page 31]



================================================
FILE: doc/notes/rfc/rfc2046.txt
================================================






Network Working Group                                          N. Freed
Request for Comments: 2046                                     Innosoft
Obsoletes: 1521, 1522, 1590                               N. Borenstein
Category: Standards Track                                 First Virtual
                                                          November 1996


                 Multipurpose Internet Mail Extensions
                            (MIME) Part Two:
                              Media Types

Status of this Memo

   This document specifies an Internet standards track protocol for the
   Internet community, and requests discussion and suggestions for
   improvements.  Please refer to the current edition of the "Internet
   Official Protocol Standards" (STD 1) for the standardization state
   and status of this protocol.  Distribution of this memo is unlimited.

Abstract

   STD 11, RFC 822 defines a message representation protocol specifying
   considerable detail about US-ASCII message headers, but which leaves
   the message content, or message body, as flat US-ASCII text.  This
   set of documents, collectively called the Multipurpose Internet Mail
   Extensions, or MIME, redefines the format of messages to allow for

    (1)   textual message bodies in character sets other than
          US-ASCII,

    (2)   an extensible set of different formats for non-textual
          message bodies,

    (3)   multi-part message bodies, and

    (4)   textual header information in character sets other than
          US-ASCII.

   These documents are based on earlier work documented in RFC 934, STD
   11, and RFC 1049, but extends and revises them.  Because RFC 822 said
   so little about message bodies, these documents are largely
   orthogonal to (rather than a revision of) RFC 822.

   The initial document in this set, RFC 2045, specifies the various
   headers used to describe the structure of MIME messages. This second
   document defines the general structure of the MIME media typing
   system and defines an initial set of media types. The third document,
   RFC 2047, describes extensions to RFC 822 to allow non-US-ASCII text



Freed & Borenstein          Standards Track                     [Page 1]

RFC 2046                      Media Types                  November 1996


   data in Internet mail header fields. The fourth document, RFC 2048,
   specifies various IANA registration procedures for MIME-related
   facilities.  The fifth and final document, RFC 2049, describes MIME
   conformance criteria as well as providing some illustrative examples
   of MIME message formats, acknowledgements, and the bibliography.

   These documents are revisions of RFCs 1521 and 1522, which themselves
   were revisions of RFCs 1341 and 1342.  An appendix in RFC 2049
   describes differences and changes from previous versions.

Table of Contents

   1. Introduction .........................................    3
   2. Definition of a Top-Level Media Type .................    4
   3. Overview Of The Initial Top-Level Media Types ........    4
   4. Discrete Media Type Values ...........................    6
   4.1 Text Media Type .....................................    6
   4.1.1 Representation of Line Breaks .....................    7
   4.1.2 Charset Parameter .................................    7
   4.1.3 Plain Subtype .....................................   11
   4.1.4 Unrecognized Subtypes .............................   11
   4.2 Image Media Type ....................................   11
   4.3 Audio Media Type ....................................   11
   4.4 Video Media Type ....................................   12
   4.5 Application Media Type ..............................   12
   4.5.1 Octet-Stream Subtype ..............................   13
   4.5.2 PostScript Subtype ................................   14
   4.5.3 Other Application Subtypes ........................   17
   5. Composite Media Type Values ..........................   17
   5.1 Multipart Media Type ................................   17
   5.1.1 Common Syntax .....................................   19
   5.1.2 Handling Nested Messages and Multiparts ...........   24
   5.1.3 Mixed Subtype .....................................   24
   5.1.4 Alternative Subtype ...............................   24
   5.1.5 Digest Subtype ....................................   26
   5.1.6 Parallel Subtype ..................................   27
   5.1.7 Other Multipart Subtypes ..........................   28
   5.2 Message Media Type ..................................   28
   5.2.1 RFC822 Subtype ....................................   28
   5.2.2 Partial Subtype ...................................   29
   5.2.2.1 Message Fragmentation and Reassembly ............   30
   5.2.2.2 Fragmentation and Reassembly Example ............   31
   5.2.3 External-Body Subtype .............................   33
   5.2.4 Other Message Subtypes ............................   40
   6. Experimental Media Type Values .......................   40
   7. Summary ..............................................   41
   8. Security Considerations ..............................   41
   9. Authors' Addresses ...................................   42



Freed & Borenstein          Standards Track                     [Page 2]

RFC 2046                      Media Types                  November 1996


   A. Collected Grammar ....................................   43

1.  Introduction

   The first document in this set, RFC 2045, defines a number of header
   fields, including Content-Type. The Content-Type field is used to
   specify the nature of the data in the body of a MIME entity, by
   giving media type and subtype identifiers, and by providing auxiliary
   information that may be required for certain media types.  After the
   type and subtype names, the remainder of the header field is simply a
   set of parameters, specified in an attribute/value notation.  The
   ordering of parameters is not significant.

   In general, the top-level media type is used to declare the general
   type of data, while the subtype specifies a specific format for that
   type of data.  Thus, a media type of "image/xyz" is enough to tell a
   user agent that the data is an image, even if the user agent has no
   knowledge of the specific image format "xyz".  Such information can
   be used, for example, to decide whether or not to show a user the raw
   data from an unrecognized subtype -- such an action might be
   reasonable for unrecognized subtypes of "text", but not for
   unrecognized subtypes of "image" or "audio".  For this reason,
   registered subtypes of "text", "image", "audio", and "video" should
   not contain embedded information that is really of a different type.
   Such compound formats should be represented using the "multipart" or
   "application" types.

   Parameters are modifiers of the media subtype, and as such do not
   fundamentally affect the nature of the content.  The set of
   meaningful parameters depends on the media type and subtype.  Most
   parameters are associated with a single specific subtype.  However, a
   given top-level media type may define parameters which are applicable
   to any subtype of that type.  Parameters may be required by their
   defining media type or subtype or they may be optional.  MIME
   implementations must also ignore any parameters whose names they do
   not recognize.

   MIME's Content-Type header field and media type mechanism has been
   carefully designed to be extensible, and it is expected that the set
   of media type/subtype pairs and their associated parameters will grow
   significantly over time.  Several other MIME facilities, such as
   transfer encodings and "message/external-body" access types, are
   likely to have new values defined over time.  In order to ensure that
   the set of such values is developed in an orderly, well-specified,
   and public manner, MIME sets up a registration process which uses the
   Internet Assigned Numbers Authority (IANA) as a central registry for
   MIME's various areas of extensibility.  The registration process for
   these areas is described in a companion document, RFC 2048.



Freed & Borenstein          Standards Track                     [Page 3]

RFC 2046                      Media Types                  November 1996


   The initial seven standard top-level media type are defined and
   described in the remainder of this document.

2.  Definition of a Top-Level Media Type

   The definition of a top-level media type consists of:

    (1)   a name and a description of the type, including
          criteria for whether a particular type would qualify
          under that type,

    (2)   the names and definitions of parameters, if any, which
          are defined for all subtypes of that type (including
          whether such parameters are required or optional),

    (3)   how a user agent and/or gateway should handle unknown
          subtypes of this type,

    (4)   general considerations on gatewaying entities of this
          top-level type, if any, and

    (5)   any restrictions on content-transfer-encodings for
          entities of this top-level type.

3.  Overview Of The Initial Top-Level Media Types

   The five discrete top-level media types are:

    (1)   text -- textual information.  The subtype "plain" in
          particular indicates plain text containing no
          formatting commands or directives of any sort. Plain
          text is intended to be displayed "as-is". No special
          software is required to get the full meaning of the
          text, aside from support for the indicated character
          set. Other subtypes are to be used for enriched text in
          forms where application software may enhance the
          appearance of the text, but such software must not be
          required in order to get the general idea of the
          content.  Possible subtypes of "text" thus include any
          word processor format that can be read without
          resorting to software that understands the format.  In
          particular, formats that employ embeddded binary
          formatting information are not considered directly
          readable. A very simple and portable subtype,
          "richtext", was defined in RFC 1341, with a further
          revision in RFC 1896 under the name "enriched".





Freed & Borenstein          Standards Track                     [Page 4]

RFC 2046                      Media Types                  November 1996


    (2)   image -- image data.  "Image" requires a display device
          (such as a graphical display, a graphics printer, or a
          FAX machine) to view the information. An initial
          subtype is defined for the widely-used image format
          JPEG. .  subtypes are defined for two widely-used image
          formats, jpeg and gif.

    (3)   audio -- audio data.  "Audio" requires an audio output
          device (such as a speaker or a telephone) to "display"
          the contents.  An initial subtype "basic" is defined in
          this document.

    (4)   video -- video data.  "Video" requires the capability
          to display moving images, typically including
          specialized hardware and software.  An initial subtype
          "mpeg" is defined in this document.

    (5)   application -- some other kind of data, typically
          either uninterpreted binary data or information to be
          processed by an application.  The subtype "octet-
          stream" is to be used in the case of uninterpreted
          binary data, in which case the simplest recommended
          action is to offer to write the information into a file
          for the user.  The "PostScript" subtype is also defined
          for the transport of PostScript material.  Other
          expected uses for "application" include spreadsheets,
          data for mail-based scheduling systems, and languages
          for "active" (computational) messaging, and word
          processing formats that are not directly readable.
          Note that security considerations may exist for some
          types of application data, most notably
          "application/PostScript" and any form of active
          messaging.  These issues are discussed later in this
          document.

   The two composite top-level media types are:

    (1)   multipart -- data consisting of multiple entities of
          independent data types.  Four subtypes are initially
          defined, including the basic "mixed" subtype specifying
          a generic mixed set of parts, "alternative" for
          representing the same data in multiple formats,
          "parallel" for parts intended to be viewed
          simultaneously, and "digest" for multipart entities in
          which each part has a default type of "message/rfc822".






Freed & Borenstein          Standards Track                     [Page 5]

RFC 2046                      Media Types                  November 1996


    (2)   message -- an encapsulated message.  A body of media
          type "message" is itself all or a portion of some kind
          of message object.  Such objects may or may not in turn
          contain other entities.  The "rfc822" subtype is used
          when the encapsulated content is itself an RFC 822
          message.  The "partial" subtype is defined for partial
          RFC 822 messages, to permit the fragmented transmission
          of bodies that are thought to be too large to be passed
          through transport facilities in one piece.  Another
          subtype, "external-body", is defined for specifying
          large bodies by reference to an external data source.

   It should be noted that the list of media type values given here may
   be augmented in time, via the mechanisms described above, and that
   the set of subtypes is expected to grow substantially.

4.  Discrete Media Type Values

   Five of the seven initial media type values refer to discrete bodies.
   The content of these types must be handled by non-MIME mechanisms;
   they are opaque to MIME processors.

4.1.  Text Media Type

   The "text" media type is intended for sending material which is
   principally textual in form.  A "charset" parameter may be used to
   indicate the character set of the body text for "text" subtypes,
   notably including the subtype "text/plain", which is a generic
   subtype for plain text.  Plain text does not provide for or allow
   formatting commands, font attribute specifications, processing
   instructions, interpretation directives, or content markup.  Plain
   text is seen simply as a linear sequence of characters, possibly
   interrupted by line breaks or page breaks.  Plain text may allow the
   stacking of several characters in the same position in the text.
   Plain text in scripts like Arabic and Hebrew may also include
   facilitites that allow the arbitrary mixing of text segments with
   opposite writing directions.

   Beyond plain text, there are many formats for representing what might
   be known as "rich text".  An interesting characteristic of many such
   representations is that they are to some extent readable even without
   the software that interprets them.  It is useful, then, to
   distinguish them, at the highest level, from such unreadable data as
   images, audio, or text represented in an unreadable form. In the
   absence of appropriate interpretation software, it is reasonable to
   show subtypes of "text" to the user, while it is not reasonable to do
   so with most nontextual data. Such formatted textual data should be
   represented using subtypes of "text".



Freed & Borenstein          Standards Track                     [Page 6]

RFC 2046                      Media Types                  November 1996


4.1.1.  Representation of Line Breaks

   The canonical form of any MIME "text" subtype MUST always represent a
   line break as a CRLF sequence.  Similarly, any occurrence of CRLF in
   MIME "text" MUST represent a line break.  Use of CR and LF outside of
   line break sequences is also forbidden.

   This rule applies regardless of format or character set or sets
   involved.

   NOTE: The proper interpretation of line breaks when a body is
   displayed depends on the media type. In particular, while it is
   appropriate to treat a line break as a transition to a new line when
   displaying a "text/plain" body, this treatment is actually incorrect
   for other subtypes of "text" like "text/enriched" [RFC-1896].
   Similarly, whether or not line breaks should be added during display
   operations is also a function of the media type. It should not be
   necessary to add any line breaks to display "text/plain" correctly,
   whereas proper display of "text/enriched" requires the appropriate
   addition of line breaks.

   NOTE: Some protocols defines a maximum line length.  E.g. SMTP [RFC-
   821] allows a maximum of 998 octets before the next CRLF sequence.
   To be transported by such protocols, data which includes too long
   segments without CRLF sequences must be encoded with a suitable
   content-transfer-encoding.

4.1.2.  Charset Parameter

   A critical parameter that may be specified in the Content-Type field
   for "text/plain" data is the character set.  This is specified with a
   "charset" parameter, as in:

     Content-type: text/plain; charset=iso-8859-1

   Unlike some other parameter values, the values of the charset
   parameter are NOT case sensitive.  The default character set, which
   must be assumed in the absence of a charset parameter, is US-ASCII.

   The specification for any future subtypes of "text" must specify
   whether or not they will also utilize a "charset" parameter, and may
   possibly restrict its values as well.  For other subtypes of "text"
   than "text/plain", the semantics of the "charset" parameter should be
   defined to be identical to those specified here for "text/plain",
   i.e., the body consists entirely of characters in the given charset.
   In particular, definers of future "text" subtypes should pay close
   attention to the implications of multioctet character sets for their
   subtype definitions.



Freed & Borenstein          Standards Track                     [Page 7]

RFC 2046                      Media Types                  November 1996


   The charset parameter for subtypes of "text" gives a name of a
   character set, as "character set" is defined in RFC 2045.  The rules
   regarding line breaks detailed in the previous section must also be
   observed -- a character set whose definition does not conform to
   these rules cannot be used in a MIME "text" subtype.

   An initial list of predefined character set names can be found at the
   end of this section.  Additional character sets may be registered
   with IANA.

   Other media types than subtypes of "text" might choose to employ the
   charset parameter as defined here, but with the CRLF/line break
   restriction removed.  Therefore, all character sets that conform to
   the general definition of "character set" in RFC 2045 can be
   registered for MIME use.

   Note that if the specified character set includes 8-bit characters
   and such characters are used in the body, a Content-Transfer-Encoding
   header field and a corresponding encoding on the data are required in
   order to transmit the body via some mail transfer protocols, such as
   SMTP [RFC-821].

   The default character set, US-ASCII, has been the subject of some
   confusion and ambiguity in the past.  Not only were there some
   ambiguities in the definition, there have been wide variations in
   practice.  In order to eliminate such ambiguity and variations in the
   future, it is strongly recommended that new user agents explicitly
   specify a character set as a media type parameter in the Content-Type
   header field. "US-ASCII" does not indicate an arbitrary 7-bit
   character set, but specifies that all octets in the body must be
   interpreted as characters according to the US-ASCII character set.
   National and application-oriented versions of ISO 646 [ISO-646] are
   usually NOT identical to US-ASCII, and in that case their use in
   Internet mail is explicitly discouraged.  The omission of the ISO 646
   character set from this document is deliberate in this regard.  The
   character set name of "US-ASCII" explicitly refers to the character
   set defined in ANSI X3.4-1986 [US- ASCII].  The new international
   reference version (IRV) of the 1991 edition of ISO 646 is identical
   to US-ASCII.  The character set name "ASCII" is reserved and must not
   be used for any purpose.

   NOTE: RFC 821 explicitly specifies "ASCII", and references an earlier
   version of the American Standard.  Insofar as one of the purposes of
   specifying a media type and character set is to permit the receiver
   to unambiguously determine how the sender intended the coded message
   to be interpreted, assuming anything other than "strict ASCII" as the
   default would risk unintentional and incompatible changes to the
   semantics of messages now being transmitted.  This also implies that



Freed & Borenstein          Standards Track                     [Page 8]

RFC 2046                      Media Types                  November 1996


   messages containing characters coded according to other versions of
   ISO 646 than US-ASCII and the 1991 IRV, or using code-switching
   procedures (e.g., those of ISO 2022), as well as 8bit or multiple
   octet character encodings MUST use an appropriate character set
   specification to be consistent with MIME.

   The complete US-ASCII character set is listed in ANSI X3.4- 1986.
   Note that the control characters including DEL (0-31, 127) have no
   defined meaning in apart from the combination CRLF (US-ASCII values
   13 and 10) indicating a new line.  Two of the characters have de
   facto meanings in wide use: FF (12) often means "start subsequent
   text on the beginning of a new page"; and TAB or HT (9) often (though
   not always) means "move the cursor to the next available column after
   the current position where the column number is a multiple of 8
   (counting the first column as column 0)."  Aside from these
   conventions, any use of the control characters or DEL in a body must
   either occur

    (1)   because a subtype of text other than "plain"
          specifically assigns some additional meaning, or

    (2)   within the context of a private agreement between the
          sender and recipient. Such private agreements are
          discouraged and should be replaced by the other
          capabilities of this document.

   NOTE: An enormous proliferation of character sets exist beyond US-
   ASCII.  A large number of partially or totally overlapping character
   sets is NOT a good thing.  A SINGLE character set that can be used
   universally for representing all of the world's languages in Internet
   mail would be preferrable.  Unfortunately, existing practice in
   several communities seems to point to the continued use of multiple
   character sets in the near future.  A small number of standard
   character sets are, therefore, defined for Internet use in this
   document.

   The defined charset values are:

    (1)   US-ASCII -- as defined in ANSI X3.4-1986 [US-ASCII].

    (2)   ISO-8859-X -- where "X" is to be replaced, as
          necessary, for the parts of ISO-8859 [ISO-8859].  Note
          that the ISO 646 character sets have deliberately been
          omitted in favor of their 8859 replacements, which are
          the designated character sets for Internet mail.  As of
          the publication of this document, the legitimate values
          for "X" are the digits 1 through 10.




Freed & Borenstein          Standards Track                     [Page 9]

RFC 2046                      Media Types                  November 1996


   Characters in the range 128-159 has no assigned meaning in ISO-8859-
   X.  Characters with values below 128 in ISO-8859-X have the same
   assigned meaning as they do in US-ASCII.

   Part 6 of ISO 8859 (Latin/Arabic alphabet) and part 8 (Latin/Hebrew
   alphabet) includes both characters for which the normal writing
   direction is right to left and characters for which it is left to
   right, but do not define a canonical ordering method for representing
   bi-directional text.  The charset values "ISO-8859-6" and "ISO-8859-
   8", however, specify that the visual method is used [RFC-1556].

   All of these character sets are used as pure 7bit or 8bit sets
   without any shift or escape functions.  The meaning of shift and
   escape sequences in these character sets is not defined.

   The character sets specified above are the ones that were relatively
   uncontroversial during the drafting of MIME.  This document does not
   endorse the use of any particular character set other than US-ASCII,
   and recognizes that the future evolution of world character sets
   remains unclear.

   Note that the character set used, if anything other than US- ASCII,
   must always be explicitly specified in the Content-Type field.

   No character set name other than those defined above may be used in
   Internet mail without the publication of a formal specification and
   its registration with IANA, or by private agreement, in which case
   the character set name must begin with "X-".

   Implementors are discouraged from defining new character sets unless
   absolutely necessary.

   The "charset" parameter has been defined primarily for the purpose of
   textual data, and is described in this section for that reason.
   However, it is conceivable that non-textual data might also wish to
   specify a charset value for some purpose, in which case the same
   syntax and values should be used.

   In general, composition software should always use the "lowest common
   denominator" character set possible.  For example, if a body contains
   only US-ASCII characters, it SHOULD be marked as being in the US-
   ASCII character set, not ISO-8859-1, which, like all the ISO-8859
   family of character sets, is a superset of US-ASCII.  More generally,
   if a widely-used character set is a subset of another character set,
   and a body contains only characters in the widely-used subset, it
   should be labelled as being in that subset.  This will increase the
   chances that the recipient will be able to view the resulting entity
   correctly.



Freed & Borenstein          Standards Track                    [Page 10]

RFC 2046                      Media Types                  November 1996


4.1.3.  Plain Subtype

   The simplest and most important subtype of "text" is "plain".  This
   indicates plain text that does not contain any formatting commands or
   directives. Plain text is intended to be displayed "as-is", that is,
   no interpretation of embedded formatting commands, font attribute
   specifications, processing instructions, interpretation directives,
   or content markup should be necessary for proper display.  The
   default media type of "text/plain; charset=us-ascii" for Internet
   mail describes existing Internet practice.  That is, it is the type
   of body defined by RFC 822.

   No other "text" subtype is defined by this document.

4.1.4.  Unrecognized Subtypes

   Unrecognized subtypes of "text" should be treated as subtype "plain"
   as long as the MIME implementation knows how to handle the charset.
   Unrecognized subtypes which also specify an unrecognized charset
   should be treated as "application/octet- stream".

4.2.  Image Media Type

   A media type of "image" indicates that the body contains an image.
   The subtype names the specific image format.  These names are not
   case sensitive. An initial subtype is "jpeg" for the JPEG format
   using JFIF encoding [JPEG].

   The list of "image" subtypes given here is neither exclusive nor
   exhaustive, and is expected to grow as more types are registered with
   IANA, as described in RFC 2048.

   Unrecognized subtypes of "image" should at a miniumum be treated as
   "application/octet-stream".  Implementations may optionally elect to
   pass subtypes of "image" that they do not specifically recognize to a
   secure and robust general-purpose image viewing application, if such
   an application is available.

   NOTE: Using of a generic-purpose image viewing application this way
   inherits the security problems of the most dangerous type supported
   by the application.

4.3.  Audio Media Type

   A media type of "audio" indicates that the body contains audio data.
   Although there is not yet a consensus on an "ideal" audio format for
   use with computers, there is a pressing need for a format capable of
   providing interoperable behavior.



Freed & Borenstein          Standards Track                    [Page 11]

RFC 2046                      Media Types                  November 1996


   The initial subtype of "basic" is specified to meet this requirement
   by providing an absolutely minimal lowest common denominator audio
   format.  It is expected that richer formats for higher quality and/or
   lower bandwidth audio will be defined by a later document.

   The content of the "audio/basic" subtype is single channel audio
   encoded using 8bit ISDN mu-law [PCM] at a sample rate of 8000 Hz.

   Unrecognized subtypes of "audio" should at a miniumum be treated as
   "application/octet-stream".  Implementations may optionally elect to
   pass subtypes of "audio" that they do not specifically recognize to a
   robust general-purpose audio playing application, if such an
   application is available.

4.4.  Video Media Type

   A media type of "video" indicates that the body contains a time-
   varying-picture image, possibly with color and coordinated sound.
   The term 'video' is used in its most generic sense, rather than with
   reference to any particular technology or format, and is not meant to
   preclude subtypes such as animated drawings encoded compactly.  The
   subtype "mpeg" refers to video coded according to the MPEG standard
   [MPEG].

   Note that although in general this document strongly discourages the
   mixing of multiple media in a single body, it is recognized that many
   so-called video formats include a representation for synchronized
   audio, and this is explicitly permitted for subtypes of "video".

   Unrecognized subtypes of "video" should at a minumum be treated as
   "application/octet-stream".  Implementations may optionally elect to
   pass subtypes of "video" that they do not specifically recognize to a
   robust general-purpose video display application, if such an
   application is available.

4.5.  Application Media Type

   The "application" media type is to be used for discrete data which do
   not fit in any of the other categories, and particularly for data to
   be processed by some type of application program.  This is
   information which must be processed by an application before it is
   viewable or usable by a user.  Expected uses for the "application"
   media type include file transfer, spreadsheets, data for mail-based
   scheduling systems, and languages for "active" (computational)
   material.  (The latter, in particular, can pose security problems
   which must be understood by implementors, and are considered in
   detail in the discussion of the "application/PostScript" media type.)




Freed & Borenstein          Standards Track                    [Page 12]

RFC 2046                      Media Types                  November 1996


   For example, a meeting scheduler might define a standard
   representation for information about proposed meeting dates.  An
   intelligent user agent would use this information to conduct a dialog
   with the user, and might then send additional material based on that
   dialog.  More generally, there have been several "active" messaging
   languages developed in which programs in a suitably specialized
   language are transported to a remote location and automatically run
   in the recipient's environment.

   Such applications may be defined as subtypes of the "application"
   media type. This document defines two subtypes:

   octet-stream, and PostScript.

   The subtype of "application" will often be either the name or include
   part of the name of the application for which the data are intended.
   This does not mean, however, that any application program name may be
   used freely as a subtype of "application".

4.5.1.  Octet-Stream Subtype

   The "octet-stream" subtype is used to indicate that a body contains
   arbitrary binary data.  The set of currently defined parameters is:

    (1)   TYPE -- the general type or category of binary data.
          This is intended as information for the human recipient
          rather than for any automatic processing.

    (2)   PADDING -- the number of bits of padding that were
          appended to the bit-stream comprising the actual
          contents to produce the enclosed 8bit byte-oriented
          data.  This is useful for enclosing a bit-stream in a
          body when the total number of bits is not a multiple of
          8.

   Both of these parameters are optional.

   An additional parameter, "CONVERSIONS", was defined in RFC 1341 but
   has since been removed.  RFC 1341 also defined the use of a "NAME"
   parameter which gave a suggested file name to be used if the data
   were to be written to a file.  This has been deprecated in
   anticipation of a separate Content-Disposition header field, to be
   defined in a subsequent RFC.

   The recommended action for an implementation that receives an
   "application/octet-stream" entity is to simply offer to put the data
   in a file, with any Content-Transfer-Encoding undone, or perhaps to
   use it as input to a user-specified process.



Freed & Borenstein          Standards Track                    [Page 13]

RFC 2046                      Media Types                  November 1996


   To reduce the danger of transmitting rogue programs, it is strongly
   recommended that implementations NOT implement a path-search
   mechanism whereby an arbitrary program named in the Content-Type
   parameter (e.g., an "interpreter=" parameter) is found and executed
   using the message body as input.

4.5.2.  PostScript Subtype

   A media type of "application/postscript" indicates a PostScript
   program.  Currently two variants of the PostScript language are
   allowed; the original level 1 variant is described in [POSTSCRIPT]
   and the more recent level 2 variant is described in [POSTSCRIPT2].

   PostScript is a registered trademark of Adobe Systems, Inc.  Use of
   the MIME media type "application/postscript" implies recognition of
   that trademark and all the rights it entails.

   The PostScript language definition provides facilities for internal
   labelling of the specific language features a given program uses.
   This labelling, called the PostScript document structuring
   conventions, or DSC, is very general and provides substantially more
   information than just the language level.  The use of document
   structuring conventions, while not required, is strongly recommended
   as an aid to interoperability.  Documents which lack proper
   structuring conventions cannot be tested to see whether or not they
   will work in a given environment.  As such, some systems may assume
   the worst and refuse to process unstructured documents.

   The execution of general-purpose PostScript interpreters entails
   serious security risks, and implementors are discouraged from simply
   sending PostScript bodies to "off- the-shelf" interpreters.  While it
   is usually safe to send PostScript to a printer, where the potential
   for harm is greatly constrained by typical printer environments,
   implementors should consider all of the following before they add
   interactive display of PostScript bodies to their MIME readers.

   The remainder of this section outlines some, though probably not all,
   of the possible problems with the transport of PostScript entities.

    (1)   Dangerous operations in the PostScript language
          include, but may not be limited to, the PostScript
          operators "deletefile", "renamefile", "filenameforall",
          and "file".  "File" is only dangerous when applied to
          something other than standard input or output.
          Implementations may also define additional nonstandard
          file operators; these may also pose a threat to
          security. "Filenameforall", the wildcard file search
          operator, may appear at first glance to be harmless.



Freed & Borenstein          Standards Track                    [Page 14]

RFC 2046                      Media Types                  November 1996


          Note, however, that this operator has the potential to
          reveal information about what files the recipient has
          access to, and this information may itself be
          sensitive.  Message senders should avoid the use of
          potentially dangerous file operators, since these
          operators are quite likely to be unavailable in secure
          PostScript implementations.  Message receiving and
          displaying software should either completely disable
          all potentially dangerous file operators or take
          special care not to delegate any special authority to
          their operation.  These operators should be viewed as
          being done by an outside agency when interpreting
          PostScript documents.  Such disabling and/or checking
          should be done completely outside of the reach of the
          PostScript language itself; care should be taken to
          insure that no method exists for re-enabling full-
          function versions of these operators.

    (2)   The PostScript language provides facilities for exiting
          the normal interpreter, or server, loop.  Changes made
          in this "outer" environment are customarily retained
          across documents, and may in some cases be retained
          semipermanently in nonvolatile memory.  The operators
          associated with exiting the interpreter loop have the
          potential to interfere with subsequent document
          processing.  As such, their unrestrained use
          constitutes a threat of service denial.  PostScript
          operators that exit the interpreter loop include, but
          may not be limited to, the exitserver and startjob
          operators.  Message sending software should not
          generate PostScript that depends on exiting the
          interpreter loop to operate, since the ability to exit
          will probably be unavailable in secure PostScript
          implementations.  Message receiving and displaying
          software should completely disable the ability to make
          retained changes to the PostScript environment by
          eliminating or disabling the "startjob" and
          "exitserver" operations.  If these operations cannot be
          eliminated or completely disabled the password
          associated with them should at least be set to a hard-
          to-guess value.

    (3)   PostScript provides operators for setting system-wide
          and device-specific parameters.  These parameter
          settings may be retained across jobs and may
          potentially pose a threat to the correct operation of
          the interpreter.  The PostScript operators that set
          system and device parameters include, but may not be



Freed & Borenstein          Standards Track                    [Page 15]

RFC 2046                      Media Types                  November 1996


          limited to, the "setsystemparams" and "setdevparams"
          operators.  Message sending software should not
          generate PostScript that depends on the setting of
          system or device parameters to operate correctly.  The
          ability to set these parameters will probably be
          unavailable in secure PostScript implementations.
          Message receiving and displaying software should
          disable the ability to change system and device
          parameters.  If these operators cannot be completely
          disabled the password associated with them should at
          least be set to a hard-to-guess value.

    (4)   Some PostScript implementations provide nonstandard
          facilities for the direct loading and execution of
          machine code.  Such facilities are quite obviously open
          to substantial abuse.  Message sending software should
          not make use of such features.  Besides being totally
          hardware-specific, they are also likely to be
          unavailable in secure implementations of PostScript.
          Message receiving and displaying software should not
          allow such operators to be used if they exist.

    (5)   PostScript is an extensible language, and many, if not
          most, implementations of it provide a number of their
          own extensions.  This document does not deal with such
          extensions explicitly since they constitute an unknown
          factor.  Message sending software should not make use
          of nonstandard extensions; they are likely to be
          missing from some implementations.  Message receiving
          and displaying software should make sure that any
          nonstandard PostScript operators are secure and don't
          present any kind of threat.

    (6)   It is possible to write PostScript that consumes huge
          amounts of various system resources.  It is also
          possible to write PostScript programs that loop
          indefinitely.  Both types of programs have the
          potential to cause damage if sent to unsuspecting
          recipients.  Message-sending software should avoid the
          construction and dissemination of such programs, which
          is antisocial.  Message receiving and displaying
          software should provide appropriate mechanisms to abort
          processing after a reasonable amount of time has
          elapsed. In addition, PostScript interpreters should be
          limited to the consumption of only a reasonable amount
          of any given system resource.





Freed & Borenstein          Standards Track                    [Page 16]

RFC 2046                      Media Types                  November 1996


    (7)   It is possible to include raw binary information inside
          PostScript in various forms.  This is not recommended
          for use in Internet mail, both because it is not
          supported by all PostScript interpreters and because it
          significantly complicates the use of a MIME Content-
          Transfer-Encoding.  (Without such binary, PostScript
          may typically be viewed as line-oriented data.  The
          treatment of CRLF sequences becomes extremely
          problematic if binary and line-oriented data are mixed
          in a single Postscript data stream.)

    (8)   Finally, bugs may exist in some PostScript interpreters
          which could possibly be exploited to gain unauthorized
          access to a recipient's system.  Apart from noting this
          possibility, there is no specific action to take to
          prevent this, apart from the timely correction of such
          bugs if any are found.

4.5.3.  Other Application Subtypes

   It is expected that many other subtypes of "application" will be
   defined in the future.  MIME implementations must at a minimum treat
   any unrecognized subtypes as being equivalent to "application/octet-
   stream".

5.  Composite Media Type Values

   The remaining two of the seven initial Content-Type values refer to
   composite entities.  Composite entities are handled using MIME
   mechanisms -- a MIME processor typically handles the body directly.

5.1.  Multipart Media Type

   In the case of multipart entities, in which one or more different
   sets of data are combined in a single body, a "multipart" media type
   field must appear in the entity's header.  The body must then contain
   one or more body parts, each preceded by a boundary delimiter line,
   and the last one followed by a closing boundary delimiter line.
   After its boundary delimiter line, each body part then consists of a
   header area, a blank line, and a body area.  Thus a body part is
   similar to an RFC 822 message in syntax, but different in meaning.

   A body part is an entity and hence is NOT to be interpreted as
   actually being an RFC 822 message.  To begin with, NO header fields
   are actually required in body parts.  A body part that starts with a
   blank line, therefore, is allowed and is a body part for which all
   default values are to be assumed.  In such a case, the absence of a
   Content-Type header usually indicates that the corresponding body has



Freed & Borenstein          Standards Track                    [Page 17]

RFC 2046                      Media Types                  November 1996


   a content-type of "text/plain; charset=US-ASCII".

   The only header fields that have defined meaning for body parts are
   those the names of which begin with "Content-".  All other header
   fields may be ignored in body parts.  Although they should generally
   be retained if at all possible, they may be discarded by gateways if
   necessary.  Such other fields are permitted to appear in body parts
   but must not be depended on.  "X-" fields may be created for
   experimental or private purposes, with the recognition that the
   information they contain may be lost at some gateways.

   NOTE:  The distinction between an RFC 822 message and a body part is
   subtle, but important.  A gateway between Internet and X.400 mail,
   for example, must be able to tell the difference between a body part
   that contains an image and a body part that contains an encapsulated
   message, the body of which is a JPEG image.  In order to represent
   the latter, the body part must have "Content-Type: message/rfc822",
   and its body (after the blank line) must be the encapsulated message,
   with its own "Content-Type: image/jpeg" header field.  The use of
   similar syntax facilitates the conversion of messages to body parts,
   and vice versa, but the distinction between the two must be
   understood by implementors.  (For the special case in which parts
   actually are messages, a "digest" subtype is also defined.)

   As stated previously, each body part is preceded by a boundary
   delimiter line that contains the boundary delimiter.  The boundary
   delimiter MUST NOT appear inside any of the encapsulated parts, on a
   line by itself or as the prefix of any line.  This implies that it is
   crucial that the composing agent be able to choose and specify a
   unique boundary parameter value that does not contain the boundary
   parameter value of an enclosing multipart as a prefix.

   All present and future subtypes of the "multipart" type must use an
   identical syntax.  Subtypes may differ in their semantics, and may
   impose additional restrictions on syntax, but must conform to the
   required syntax for the "multipart" type.  This requirement ensures
   that all conformant user agents will at least be able to recognize
   and separate the parts of any multipart entity, even those of an
   unrecognized subtype.

   As stated in the definition of the Content-Transfer-Encoding field
   [RFC 2045], no encoding other than "7bit", "8bit", or "binary" is
   permitted for entities of type "multipart".  The "multipart" boundary
   delimiters and header fields are always represented as 7bit US-ASCII
   in any case (though the header fields may encode non-US-ASCII header
   text as per RFC 2047) and data within the body parts can be encoded
   on a part-by-part basis, with Content-Transfer-Encoding fields for
   each appropriate body part.



Freed & Borenstein          Standards Track                    [Page 18]

RFC 2046                      Media Types                  November 1996


5.1.1.  Common Syntax

   This section defines a common syntax for subtypes of "multipart".
   All subtypes of "multipart" must use this syntax.  A simple example
   of a multipart message also appears in this section.  An example of a
   more complex multipart message is given in RFC 2049.

   The Content-Type field for multipart entities requires one parameter,
   "boundary". The boundary delimiter line is then defined as a line
   consisting entirely of two hyphen characters ("-", decimal value 45)
   followed by the boundary parameter value from the Content-Type header
   field, optional linear whitespace, and a terminating CRLF.

   NOTE:  The hyphens are for rough compatibility with the earlier RFC
   934 method of message encapsulation, and for ease of searching for
   the boundaries in some implementations.  However, it should be noted
   that multipart messages are NOT completely compatible with RFC 934
   encapsulations; in particular, they do not obey RFC 934 quoting
   conventions for embedded lines that begin with hyphens.  This
   mechanism was chosen over the RFC 934 mechanism because the latter
   causes lines to grow with each level of quoting.  The combination of
   this growth with the fact that SMTP implementations sometimes wrap
   long lines made the RFC 934 mechanism unsuitable for use in the event
   that deeply-nested multipart structuring is ever desired.

   WARNING TO IMPLEMENTORS:  The grammar for parameters on the Content-
   type field is such that it is often necessary to enclose the boundary
   parameter values in quotes on the Content-type line.  This is not
   always necessary, but never hurts. Implementors should be sure to
   study the grammar carefully in order to avoid producing invalid
   Content-type fields.  Thus, a typical "multipart" Content-Type header
   field might look like this:

     Content-Type: multipart/mixed; boundary=gc0p4Jq0M2Yt08j34c0p

   But the following is not valid:

     Content-Type: multipart/mixed; boundary=gc0pJq0M:08jU534c0p

   (because of the colon) and must instead be represented as

     Content-Type: multipart/mixed; boundary="gc0pJq0M:08jU534c0p"

   This Content-Type value indicates that the content consists of one or
   more parts, each with a structure that is syntactically identical to
   an RFC 822 message, except that the header area is allowed to be
   completely empty, and that the parts are each preceded by the line




Freed & Borenstein          Standards Track                    [Page 19]

RFC 2046                      Media Types                  November 1996


     --gc0pJq0M:08jU534c0p

   The boundary delimiter MUST occur at the beginning of a line, i.e.,
   following a CRLF, and the initial CRLF is considered to be attached
   to the boundary delimiter line rather than part of the preceding
   part.  The boundary may be followed by zero or more characters of
   linear whitespace. It is then terminated by either another CRLF and
   the header fields for the next part, or by two CRLFs, in which case
   there are no header fields for the next part.  If no Content-Type
   field is present it is assumed to be "message/rfc822" in a
   "multipart/digest" and "text/plain" otherwise.

   NOTE:  The CRLF preceding the boundary delimiter line is conceptually
   attached to the boundary so that it is possible to have a part that
   does not end with a CRLF (line  break).  Body parts that must be
   considered to end with line breaks, therefore, must have two CRLFs
   preceding the boundary delimiter line, the first of which is part of
   the preceding body part, and the second of which is part of the
   encapsulation boundary.

   Boundary delimiters must not appear within the encapsulated material,
   and must be no longer than 70 characters, not counting the two
   leading hyphens.

   The boundary delimiter line following the last body part is a
   distinguished delimiter that indicates that no further body parts
   will follow.  Such a delimiter line is identical to the previous
   delimiter lines, with the addition of two more hyphens after the
   boundary parameter value.

     --gc0pJq0M:08jU534c0p--

   NOTE TO IMPLEMENTORS:  Boundary string comparisons must compare the
   boundary value with the beginning of each candidate line.  An exact
   match of the entire candidate line is not required; it is sufficient
   that the boundary appear in its entirety following the CRLF.

   There appears to be room for additional information prior to the
   first boundary delimiter line and following the final boundary
   delimiter line.  These areas should generally be left blank, and
   implementations must ignore anything that appears before the first
   boundary delimiter line or after the last one.

   NOTE:  These "preamble" and "epilogue" areas are generally not used
   because of the lack of proper typing of these parts and the lack of
   clear semantics for handling these areas at gateways, particularly
   X.400 gateways.  However, rather than leaving the preamble area
   blank, many MIME implementations have found this to be a convenient



Freed & Borenstein          Standards Track                    [Page 20]

RFC 2046                      Media Types                  November 1996


   place to insert an explanatory note for recipients who read the
   message with pre-MIME software, since such notes will be ignored by
   MIME-compliant software.

   NOTE:  Because boundary delimiters must not appear in the body parts
   being encapsulated, a user agent must exercise care to choose a
   unique boundary parameter value.  The boundary parameter value in the
   example above could have been the result of an algorithm designed to
   produce boundary delimiters with a very low probability of already
   existing in the data to be encapsulated without having to prescan the
   data.  Alternate algorithms might result in more "readable" boundary
   delimiters for a recipient with an old user agent, but would require
   more attention to the possibility that the boundary delimiter might
   appear at the beginning of some line in the encapsulated part.  The
   simplest boundary delimiter line possible is something like "---",
   with a closing boundary delimiter line of "-----".

   As a very simple example, the following multipart message has two
   parts, both of them plain text, one of them explicitly typed and one
   of them implicitly typed:

     From: Nathaniel Borenstein <nsb@bellcore.com>
     To: Ned Freed <ned@innosoft.com>
     Date: Sun, 21 Mar 1993 23:56:48 -0800 (PST)
     Subject: Sample message
     MIME-Version: 1.0
     Content-type: multipart/mixed; boundary="simple boundary"

     This is the preamble.  It is to be ignored, though it
     is a handy place for composition agents to include an
     explanatory note to non-MIME conformant readers.

     --simple boundary

     This is implicitly typed plain US-ASCII text.
     It does NOT end with a linebreak.
     --simple boundary
     Content-type: text/plain; charset=us-ascii

     This is explicitly typed plain US-ASCII text.
     It DOES end with a linebreak.

     --simple boundary--

     This is the epilogue.  It is also to be ignored.






Freed & Borenstein          Standards Track                    [Page 21]

RFC 2046                      Media Types                  November 1996


   The use of a media type of "multipart" in a body part within another
   "multipart" entity is explicitly allowed.  In such cases, for obvious
   reasons, care must be taken to ensure that each nested "multipart"
   entity uses a different boundary delimiter.  See RFC 2049 for an
   example of nested "multipart" entities.

   The use of the "multipart" media type with only a single body part
   may be useful in certain contexts, and is explicitly permitted.

   NOTE: Experience has shown that a "multipart" media type with a
   single body part is useful for sending non-text media types.  It has
   the advantage of providing the preamble as a place to include
   decoding instructions.  In addition, a number of SMTP gateways move
   or remove the MIME headers, and a clever MIME decoder can take a good
   guess at multipart boundaries even in the absence of the Content-Type
   header and thereby successfully decode the message.

   The only mandatory global parameter for the "multipart" media type is
   the boundary parameter, which consists of 1 to 70 characters from a
   set of characters known to be very robust through mail gateways, and
   NOT ending with white space. (If a boundary delimiter line appears to
   end with white space, the white space must be presumed to have been
   added by a gateway, and must be deleted.)  It is formally specified
   by the following BNF:

     boundary := 0*69<bchars> bcharsnospace

     bchars := bcharsnospace / " "

     bcharsnospace := DIGIT / ALPHA / "'" / "(" / ")" /
                      "+" / "_" / "," / "-" / "." /
                      "/" / ":" / "=" / "?"

   Overall, the body of a "multipart" entity may be specified as
   follows:

     dash-boundary := "--" boundary
                      ; boundary taken from the value of
                      ; boundary parameter of the
                      ; Content-Type field.

     multipart-body := [preamble CRLF]
                       dash-boundary transport-padding CRLF
                       body-part *encapsulation
                       close-delimiter transport-padding
                       [CRLF epilogue]





Freed & Borenstein          Standards Track                    [Page 22]

RFC 2046                      Media Types                  November 1996


     transport-padding := *LWSP-char
                          ; Composers MUST NOT generate
                          ; non-zero length transport
                          ; padding, but receivers MUST
                          ; be able to handle padding
                          ; added by message transports.

     encapsulation := delimiter transport-padding
                      CRLF body-part

     delimiter := CRLF dash-boundary

     close-delimiter := delimiter "--"

     preamble := discard-text

     epilogue := discard-text

     discard-text := *(*text CRLF) *text
                     ; May be ignored or discarded.

     body-part := MIME-part-headers [CRLF *OCTET]
                  ; Lines in a body-part must not start
                  ; with the specified dash-boundary and
                  ; the delimiter must not appear anywhere
                  ; in the body part.  Note that the
                  ; semantics of a body-part differ from
                  ; the semantics of a message, as
                  ; described in the text.

     OCTET := <any 0-255 octet value>

   IMPORTANT:  The free insertion of linear-white-space and RFC 822
   comments between the elements shown in this BNF is NOT allowed since
   this BNF does not specify a structured header field.

   NOTE:  In certain transport enclaves, RFC 822 restrictions such as
   the one that limits bodies to printable US-ASCII characters may not
   be in force. (That is, the transport domains may exist that resemble
   standard Internet mail transport as specified in RFC 821 and assumed
   by RFC 822, but without certain restrictions.) The relaxation of
   these restrictions should be construed as locally extending the
   definition of bodies, for example to include octets outside of the
   US-ASCII range, as long as these extensions are supported by the
   transport and adequately documented in the Content- Transfer-Encoding
   header field.  However, in no event are headers (either message
   headers or body part headers) allowed to contain anything other than
   US-ASCII characters.



Freed & Borenstein          Standards Track                    [Page 23]

RFC 2046                      Media Types                  November 1996


   NOTE:  Conspicuously missing from the "multipart" type is a notion of
   structured, related body parts. It is recommended that those wishing
   to provide more structured or integrated multipart messaging
   facilities should define subtypes of multipart that are syntactically
   identical but define relationships between the various parts. For
   example, subtypes of multipart could be defined that include a
   distinguished part which in turn is used to specify the relationships
   between the other parts, probably referring to them by their
   Content-ID field.  Old implementations will not recognize the new
   subtype if this approach is used, but will treat it as
   multipart/mixed and will thus be able to show the user the parts that
   are recognized.

5.1.2.  Handling Nested Messages and Multiparts

   The "message/rfc822" subtype defined in a subsequent section of this
   document has no terminating condition other than running out of data.
   Similarly, an improperly truncated "multipart" entity may not have
   any terminating boundary marker, and can turn up operationally due to
   mail system malfunctions.

   It is essential that such entities be handled correctly when they are
   themselves imbedded inside of another "multipart" structure.  MIME
   implementations are therefore required to recognize outer level
   boundary markers at ANY level of inner nesting.  It is not sufficient
   to only check for the next expected marker or other terminating
   condition.

5.1.3.  Mixed Subtype

   The "mixed" subtype of "multipart" is intended for use when the body
   parts are independent and need to be bundled in a particular order.
   Any "multipart" subtypes that an implementation does not recognize
   must be treated as being of subtype "mixed".

5.1.4.  Alternative Subtype

   The "multipart/alternative" type is syntactically identical to
   "multipart/mixed", but the semantics are different.  In particular,
   each of the body parts is an "alternative" version of the same
   information.

   Systems should recognize that the content of the various parts are
   interchangeable.  Systems should choose the "best" type based on the
   local environment and references, in some cases even through user
   interaction.  As with "multipart/mixed", the order of body parts is
   significant.  In this case, the alternatives appear in an order of
   increasing faithfulness to the original content.  In general, the



Freed & Borenstein          Standards Track                    [Page 24]

RFC 2046                      Media Types                  November 1996


   best choice is the LAST part of a type supported by the recipient
   system's local environment.

   "Multipart/alternative" may be used, for example, to send a message
   in a fancy text format in such a way that it can easily be displayed
   anywhere:

     From: Nathaniel Borenstein <nsb@bellcore.com>
     To: Ned Freed <ned@innosoft.com>
     Date: Mon, 22 Mar 1993 09:41:09 -0800 (PST)
     Subject: Formatted text mail
     MIME-Version: 1.0
     Content-Type: multipart/alternative; boundary=boundary42

     --boundary42
     Content-Type: text/plain; charset=us-ascii

       ... plain text version of message goes here ...

     --boundary42
     Content-Type: text/enriched

       ... RFC 1896 text/enriched version of same message
           goes here ...

     --boundary42
     Content-Type: application/x-whatever

       ... fanciest version of same message goes here ...

     --boundary42--

   In this example, users whose mail systems understood the
   "application/x-whatever" format would see only the fancy version,
   while other users would see only the enriched or plain text version,
   depending on the capabilities of their system.

   In general, user agents that compose "multipart/alternative" entities
   must place the body parts in increasing order of preference, that is,
   with the preferred format last.  For fancy text, the sending user
   agent should put the plainest format first and the richest format
   last.  Receiving user agents should pick and display the last format
   they are capable of displaying.  In the case where one of the
   alternatives is itself of type "multipart" and contains unrecognized
   sub-parts, the user agent may choose either to show that alternative,
   an earlier alternative, or both.





Freed & Borenstein          Standards Track                    [Page 25]

RFC 2046                      Media Types                  November 1996


   NOTE: From an implementor's perspective, it might seem more sensible
   to reverse this ordering, and have the plainest alternative last.
   However, placing the plainest alternative first is the friendliest
   possible option when "multipart/alternative" entities are viewed
   using a non-MIME-conformant viewer.  While this approach does impose
   some burden on conformant MIME viewers, interoperability with older
   mail readers was deemed to be more important in this case.

   It may be the case that some user agents, if they can recognize more
   than one of the formats, will prefer to offer the user the choice of
   which format to view.  This makes sense, for example, if a message
   includes both a nicely- formatted image version and an easily-edited
   text version.  What is most critical, however, is that the user not
   automatically be shown multiple versions of the same data.  Either
   the user should be shown the last recognized version or should be
   given the choice.

   THE SEMANTICS OF CONTENT-ID IN MULTIPART/ALTERNATIVE:  Each part of a
   "multipart/alternative" entity represents the same data, but the
   mappings between the two are not necessarily without information
   loss.  For example, information is lost when translating ODA to
   PostScript or plain text.  It is recommended that each part should
   have a different Content-ID value in the case where the information
   content of the two parts is not identical.  And when the information
   content is identical -- for example, where several parts of type
   "message/external-body" specify alternate ways to access the
   identical data -- the same Content-ID field value should be used, to
   optimize any caching mechanisms that might be present on the
   recipient's end.  However, the Content-ID values used by the parts
   should NOT be the same Content-ID value that describes the
   "multipart/alternative" as a whole, if there is any such Content-ID
   field.  That is, one Content-ID value will refer to the
   "multipart/alternative" entity, while one or more other Content-ID
   values will refer to the parts inside it.

5.1.5.  Digest Subtype

   This document defines a "digest" subtype of the "multipart" Content-
   Type.  This type is syntactically identical to "multipart/mixed", but
   the semantics are different.  In particular, in a digest, the default
   Content-Type value for a body part is changed from "text/plain" to
   "message/rfc822".  This is done to allow a more readable digest
   format that is largely compatible (except for the quoting convention)
   with RFC 934.

   Note: Though it is possible to specify a Content-Type value for a
   body part in a digest which is other than "message/rfc822", such as a
   "text/plain" part containing a description of the material in the



Freed & Borenstein          Standards Track                    [Page 26]

RFC 2046                      Media Types                  November 1996


   digest, actually doing so is undesireble. The "multipart/digest"
   Content-Type is intended to be used to send collections of messages.
   If a "text/plain" part is needed, it should be included as a seperate
   part of a "multipart/mixed" message.

   A digest in this format might, then, look something like this:

     From: Moderator-Address
     To: Recipient-List
     Date: Mon, 22 Mar 1994 13:34:51 +0000
     Subject: Internet Digest, volume 42
     MIME-Version: 1.0
     Content-Type: multipart/mixed;
                   boundary="---- main boundary ----"

     ------ main boundary ----

       ...Introductory text or table of contents...

     ------ main boundary ----
     Content-Type: multipart/digest;
                   boundary="---- next message ----"

     ------ next message ----

     From: someone-else
     Date: Fri, 26 Mar 1993 11:13:32 +0200
     Subject: my opinion

       ...body goes here ...

     ------ next message ----

     From: someone-else-again
     Date: Fri, 26 Mar 1993 10:07:13 -0500
     Subject: my different opinion

       ... another body goes here ...

     ------ next message ------

     ------ main boundary ------

5.1.6.  Parallel Subtype

   This document defines a "parallel" subtype of the "multipart"
   Content-Type.  This type is syntactically identical to
   "multipart/mixed", but the semantics are different.  In particular,



Freed & Borenstein          Standards Track                    [Page 27]

RFC 2046                      Media Types                  November 1996


   in a parallel entity, the order of body parts is not significant.

   A common presentation of this type is to display all of the parts
   simultaneously on hardware and software that are capable of doing so.
   However, composing agents should be aware that many mail readers will
   lack this capability and will show the parts serially in any event.

5.1.7.  Other Multipart Subtypes

   Other "multipart" subtypes are expected in the future.  MIME
   implementations must in general treat unrecognized subtypes of
   "multipart" as being equivalent to "multipart/mixed".

5.2.  Message Media Type

   It is frequently desirable, in sending mail, to encapsulate another
   mail message.  A special media type, "message", is defined to
   facilitate this.  In particular, the "rfc822" subtype of "message" is
   used to encapsulate RFC 822 messages.

   NOTE:  It has been suggested that subtypes of "message" might be
   defined for forwarded or rejected messages.  However, forwarded and
   rejected messages can be handled as multipart messages in which the
   first part contains any control or descriptive information, and a
   second part, of type "message/rfc822", is the forwarded or rejected
   message.  Composing rejection and forwarding messages in this manner
   will preserve the type information on the original message and allow
   it to be correctly presented to the recipient, and hence is strongly
   encouraged.

   Subtypes of "message" often impose restrictions on what encodings are
   allowed.  These restrictions are described in conjunction with each
   specific subtype.

   Mail gateways, relays, and other mail handling agents are commonly
   known to alter the top-level header of an RFC 822 message.  In
   particular, they frequently add, remove, or reorder header fields.
   These operations are explicitly forbidden for the encapsulated
   headers embedded in the bodies of messages of type "message."

5.2.1.  RFC822 Subtype

   A media type of "message/rfc822" indicates that the body contains an
   encapsulated message, with the syntax of an RFC 822 message.
   However, unlike top-level RFC 822 messages, the restriction that each
   "message/rfc822" body must include a "From", "Date", and at least one
   destination header is removed and replaced with the requirement that
   at least one of "From", "Subject", or "Date" must be present.



Freed & Borenstein          Standards Track                    [Page 28]

RFC 2046                      Media Types                  November 1996


   It should be noted that, despite the use of the numbers "822", a
   "message/rfc822" entity isn't restricted to material in strict
   conformance to RFC822, nor are the semantics of "message/rfc822"
   objects restricted to the semantics defined in RFC822. More
   specifically, a "message/rfc822" message could well be a News article
   or a MIME message.

   No encoding other than "7bit", "8bit", or "binary" is permitted for
   the body of a "message/rfc822" entity.  The message header fields are
   always US-ASCII in any case, and data within the body can still be
   encoded, in which case the Content-Transfer-Encoding header field in
   the encapsulated message will reflect this.  Non-US-ASCII text in the
   headers of an encapsulated message can be specified using the
   mechanisms described in RFC 2047.

5.2.2.  Partial Subtype

   The "partial" subtype is defined to allow large entities to be
   delivered as several separate pieces of mail and automatically
   reassembled by a receiving user agent.  (The concept is similar to IP
   fragmentation and reassembly in the basic Internet Protocols.)  This
   mechanism can be used when intermediate transport agents limit the
   size of individual messages that can be sent.  The media type
   "message/partial" thus indicates that the body contains a fragment of
   a larger entity.

   Because data of type "message" may never be encoded in base64 or
   quoted-printable, a problem might arise if "message/partial" entities
   are constructed in an environment that supports binary or 8bit
   transport.  The problem is that the binary data would be split into
   multiple "message/partial" messages, each of them requiring binary
   transport.  If such messages were encountered at a gateway into a
   7bit transport environment, there would be no way to properly encode
   them for the 7bit world, aside from waiting for all of the fragments,
   reassembling the inner message, and then encoding the reassembled
   data in base64 or quoted-printable.  Since it is possible that
   different fragments might go through different gateways, even this is
   not an acceptable solution.  For this reason, it is specified that
   entities of type "message/partial" must always have a content-
   transfer-encoding of 7bit (the default).  In particular, even in
   environments that support binary or 8bit transport, the use of a
   content- transfer-encoding of "8bit" or "binary" is explicitly
   prohibited for MIME entities of type "message/partial". This in turn
   implies that the inner message must not use "8bit" or "binary"
   encoding.






Freed & Borenstein          Standards Track                    [Page 29]

RFC 2046                      Media Types                  November 1996


   Because some message transfer agents may choose to automatically
   fragment large messages, and because such agents may use very
   different fragmentation thresholds, it is possible that the pieces of
   a partial message, upon reassembly, may prove themselves to comprise
   a partial message.  This is explicitly permitted.

   Three parameters must be specified in the Content-Type field of type
   "message/partial":  The first, "id", is a unique identifier, as close
   to a world-unique identifier as possible, to be used to match the
   fragments together. (In general, the identifier is essentially a
   message-id; if placed in double quotes, it can be ANY message-id, in
   accordance with the BNF for "parameter" given in RFC 2045.)  The
   second, "number", an integer, is the fragment number, which indicates
   where this fragment fits into the sequence of fragments.  The third,
   "total", another integer, is the total number of fragments.  This
   third subfield is required on the final fragment, and is optional
   (though encouraged) on the earlier fragments.  Note also that these
   parameters may be given in any order.

   Thus, the second piece of a 3-piece message may have either of the
   following header fields:

     Content-Type: Message/Partial; number=2; total=3;
                   id="oc=jpbe0M2Yt4s@thumper.bellcore.com"

     Content-Type: Message/Partial;
                   id="oc=jpbe0M2Yt4s@thumper.bellcore.com";
                   number=2

   But the third piece MUST specify the total number of fragments:

     Content-Type: Message/Partial; number=3; total=3;
                   id="oc=jpbe0M2Yt4s@thumper.bellcore.com"

   Note that fragment numbering begins with 1, not 0.

   When the fragments of an entity broken up in this manner are put
   together, the result is always a complete MIME entity, which may have
   its own Content-Type header field, and thus may contain any other
   data type.

5.2.2.1.  Message Fragmentation and Reassembly

   The semantics of a reassembled partial message must be those of the
   "inner" message, rather than of a message containing the inner
   message.  This makes it possible, for example, to send a large audio
   message as several partial messages, and still have it appear to the
   recipient as a simple audio message rather than as an encapsulated



Freed & Borenstein          Standards Track                    [Page 30]

RFC 2046                      Media Types                  November 1996


   message containing an audio message.  That is, the encapsulation of
   the message is considered to be "transparent".

   When generating and reassembling the pieces of a "message/partial"
   message, the headers of the encapsulated message must be merged with
   the headers of the enclosing entities.  In this process the following
   rules must be observed:

    (1)   Fragmentation agents must split messages at line
          boundaries only. This restriction is imposed because
          splits at points other than the ends of lines in turn
          depends on message transports being able to preserve
          the semantics of messages that don't end with a CRLF
          sequence. Many transports are incapable of preserving
          such semantics.

    (2)   All of the header fields from the initial enclosing
          message, except those that start with "Content-" and
          the specific header fields "Subject", "Message-ID",
          "Encrypted", and "MIME-Version", must be copied, in
          order, to the new message.

    (3)   The header fields in the enclosed message which start
          with "Content-", plus the "Subject", "Message-ID",
          "Encrypted", and "MIME-Version" fields, must be
          appended, in order, to the header fields of the new
          message.  Any header fields in the enclosed message
          which do not start with "Content-" (except for the
          "Subject", "Message-ID", "Encrypted", and "MIME-
          Version" fields) will be ignored and dropped.

    (4)   All of the header fields from the second and any
          subsequent enclosing messages are discarded by the
          reassembly process.

5.2.2.2.  Fragmentation and Reassembly Example

   If an audio message is broken into two pieces, the first piece might
   look something like this:

     X-Weird-Header-1: Foo
     From: Bill@host.com
     To: joe@otherhost.com
     Date: Fri, 26 Mar 1993 12:59:38 -0500 (EST)
     Subject: Audio mail (part 1 of 2)
     Message-ID: <id1@host.com>
     MIME-Version: 1.0
     Content-type: message/partial; id="ABC@host.com";



Freed & Borenstein          Standards Track                    [Page 31]

RFC 2046                      Media Types                  November 1996


                   number=1; total=2

     X-Weird-Header-1: Bar
     X-Weird-Header-2: Hello
     Message-ID: <anotherid@foo.com>
     Subject: Audio mail
     MIME-Version: 1.0
     Content-type: audio/basic
     Content-transfer-encoding: base64

       ... first half of encoded audio data goes here ...

   and the second half might look something like this:

     From: Bill@host.com
     To: joe@otherhost.com
     Date: Fri, 26 Mar 1993 12:59:38 -0500 (EST)
     Subject: Audio mail (part 2 of 2)
     MIME-Version: 1.0
     Message-ID: <id2@host.com>
     Content-type: message/partial;
                   id="ABC@host.com"; number=2; total=2

       ... second half of encoded audio data goes here ...

   Then, when the fragmented message is reassembled, the resulting
   message to be displayed to the user should look something like this:

     X-Weird-Header-1: Foo
     From: Bill@host.com
     To: joe@otherhost.com
     Date: Fri, 26 Mar 1993 12:59:38 -0500 (EST)
     Subject: Audio mail
     Message-ID: <anotherid@foo.com>
     MIME-Version: 1.0
     Content-type: audio/basic
     Content-transfer-encoding: base64

       ... first half of encoded audio data goes here ...
       ... second half of encoded audio data goes here ...

   The inclusion of a "References" field in the headers of the second
   and subsequent pieces of a fragmented message that references the
   Message-Id on the previous piece may be of benefit to mail readers
   that understand and track references.  However, the generation of
   such "References" fields is entirely optional.





Freed & Borenstein          Standards Track                    [Page 32]

RFC 2046                      Media Types                  November 1996


   Finally, it should be noted that the "Encrypted" header field has
   been made obsolete by Privacy Enhanced Messaging (PEM) [RFC-1421,
   RFC-1422, RFC-1423, RFC-1424], but the rules above are nevertheless
   believed to describe the correct way to treat it if it is encountered
   in the context of conversion to and from "message/partial" fragments.

5.2.3.  External-Body Subtype

   The external-body subtype indicates that the actual body data are not
   included, but merely referenced.  In this case, the parameters
   describe a mechanism for accessing the external data.

   When a MIME entity is of type "message/external-body", it consists of
   a header, two consecutive CRLFs, and the message header for the
   encapsulated message.  If another pair of consecutive CRLFs appears,
   this of course ends the message header for the encapsulated message.
   However, since the encapsulated message's body is itself external, it
   does NOT appear in the area that follows.  For example, consider the
   following message:

     Content-type: message/external-body;
                   access-type=local-file;
                   name="/u/nsb/Me.jpeg"

     Content-type: image/jpeg
     Content-ID: <id42@guppylake.bellcore.com>
     Content-Transfer-Encoding: binary

     THIS IS NOT REALLY THE BODY!

   The area at the end, which might be called the "phantom body", is
   ignored for most external-body messages.  However, it may be used to
   contain auxiliary information for some such messages, as indeed it is
   when the access-type is "mail- server".  The only access-type defined
   in this document that uses the phantom body is "mail-server", but
   other access-types may be defined in the future in other
   specifications that use this area.

   The encapsulated headers in ALL "message/external-body" entities MUST
   include a Content-ID header field to give a unique identifier by
   which to reference the data.  This identifier may be used for caching
   mechanisms, and for recognizing the receipt of the data when the
   access-type is "mail-server".

   Note that, as specified here, the tokens that describe external-body
   data, such as file names and mail server commands, are required to be
   in the US-ASCII character set.




Freed & Borenstein          Standards Track                    [Page 33]

RFC 2046                      Media Types                  November 1996


   If this proves problematic in practice, a new mechanism may be
   required as a future extension to MIME, either as newly defined
   access-types for "message/external-body" or by some other mechanism.

   As with "message/partial", MIME entities of type "message/external-
   body" MUST have a content-transfer-encoding of 7bit (the default).
   In particular, even in environments that support binary or 8bit
   transport, the use of a content- transfer-encoding of "8bit" or
   "binary" is explicitly prohibited for entities of type
   "message/external-body".

5.2.3.1.  General External-Body Parameters

   The parameters that may be used with any "message/external- body"
   are:

    (1)   ACCESS-TYPE -- A word indicating the supported access
          mechanism by which the file or data may be obtained.
          This word is not case sensitive.  Values include, but
          are not limited to, "FTP", "ANON-FTP", "TFTP", "LOCAL-
          FILE", and "MAIL-SERVER".  Future values, except for
          experimental values beginning with "X-", must be
          registered with IANA, as described in RFC 2048.
          This parameter is unconditionally mandatory and MUST be
          present on EVERY "message/external-body".

    (2)   EXPIRATION -- The date (in the RFC 822 "date-time"
          syntax, as extended by RFC 1123 to permit 4 digits in
          the year field) after which the existence of the
          external data is not guaranteed.  This parameter may be
          used with ANY access-type and is ALWAYS optional.

    (3)   SIZE -- The size (in octets) of the data.  The intent
          of this parameter is to help the recipient decide
          whether or not to expend the necessary resources to
          retrieve the external data.  Note that this describes
          the size of the data in its canonical form, that is,
          before any Content-Transfer-Encoding has been applied
          or after the data have been decoded.  This parameter
          may be used with ANY access-type and is ALWAYS
          optional.

    (4)   PERMISSION -- A case-insensitive field that indicates
          whether or not it is expected that clients might also
          attempt to overwrite the data.  By default, or if
          permission is "read", the assumption is that they are
          not, and that if the data is retrieved once, it is
          never needed again.  If PERMISSION is "read-write",



Freed & Borenstein          Standards Track                    [Page 34]

RFC 2046                      Media Types                  November 1996


          this assumption is invalid, and any local copy must be
          considered no more than a cache.  "Read" and "Read-
          write" are the only defined values of permission.  This
          parameter may be used with ANY access-type and is
          ALWAYS optional.

   The precise semantics of the access-types defined here are described
   in the sections that follow.

5.2.3.2.  The 'ftp' and 'tftp' Access-Types

   An access-type of FTP or TFTP indicates that the message body is
   accessible as a file using the FTP [RFC-959] or TFTP [RFC- 783]
   protocols, respectively.  For these access-types, the following
   additional parameters are mandatory:

    (1)   NAME -- The name of the file that contains the actual
          body data.

    (2)   SITE -- A machine from which the file may be obtained,
          using the given protocol.  This must be a fully
          qualified domain name, not a nickname.

    (3)   Before any data are retrieved, using FTP, the user will
          generally need to be asked to provide a login id and a
          password for the machine named by the site parameter.
          For security reasons, such an id and password are not
          specified as content-type parameters, but must be
          obtained from the user.

   In addition, the following parameters are optional:

    (1)   DIRECTORY -- A directory from which the data named by
          NAME should be retrieved.

    (2)   MODE -- A case-insensitive string indicating the mode
          to be used when retrieving the information.  The valid
          values for access-type "TFTP" are "NETASCII", "OCTET",
          and "MAIL", as specified by the TFTP protocol [RFC-
          783].  The valid values for access-type "FTP" are
          "ASCII", "EBCDIC", "IMAGE", and "LOCALn" where "n" is a
          decimal integer, typically 8.  These correspond to the
          representation types "A" "E" "I" and "L n" as specified
          by the FTP protocol [RFC-959].  Note that "BINARY" and
          "TENEX" are not valid values for MODE and that "OCTET"
          or "IMAGE" or "LOCAL8" should be used instead.  IF MODE
          is not specified, the  default value is "NETASCII" for
          TFTP and "ASCII" otherwise.



Freed & Borenstein          Standards Track                    [Page 35]

RFC 2046                      Media Types                  November 1996


5.2.3.3.  The 'anon-ftp' Access-Type

   The "anon-ftp" access-type is identical to the "ftp" access type,
   except that the user need not be asked to provide a name and password
   for the specified site.  Instead, the ftp protocol will be used with
   login "anonymous" and a password that corresponds to the user's mail
   address.

5.2.3.4.  The 'local-file' Access-Type

   An access-type of "local-file" indicates that the actual body is
   accessible as a file on the local machine.  Two additional parameters
   are defined for this access type:

    (1)   NAME -- The name of the file that contains the actual
          body data.  This parameter is mandatory for the
          "local-file" access-type.

    (2)   SITE -- A domain specifier for a machine or set of
          machines that are known to have access to the data
          file.  This optional parameter is used to describe the
          locality of reference for the data, that is, the site
          or sites at which the file is expected to be visible.
          Asterisks may be used for wildcard matching to a part
          of a domain name, such as "*.bellcore.com", to indicate
          a set of machines on which the data should be directly
          visible, while a single asterisk may be used to
          indicate a file that is expected to be universally
          available, e.g., via a global file system.

5.2.3.5.  The 'mail-server' Access-Type

   The "mail-server" access-type indicates that the actual body is
   available from a mail server.  Two additional parameters are defined
   for this access-type:

    (1)   SERVER -- The addr-spec of the mail server from which
          the actual body data can be obtained.  This parameter
          is mandatory for the "mail-server" access-type.

    (2)   SUBJECT -- The subject that is to be used in the mail
          that is sent to obtain the data.  Note that keying mail
          servers on Subject lines is NOT recommended, but such
          mail servers are known to exist.  This is an optional
          parameter.






Freed & Borenstein          Standards Track                    [Page 36]

RFC 2046                      Media Types                  November 1996


   Because mail servers accept a variety of syntaxes, some of which is
   multiline, the full command to be sent to a mail server is not
   included as a parameter in the content-type header field.  Instead,
   it is provided as the "phantom body" when the media type is
   "message/external-body" and the access-type is mail-server.

   Note that MIME does not define a mail server syntax.  Rather, it
   allows the inclusion of arbitrary mail server commands in the phantom
   body.  Implementations must include the phantom body in the body of
   the message it sends to the mail server address to retrieve the
   relevant data.

   Unlike other access-types, mail-server access is asynchronous and
   will happen at an unpredictable time in the future.  For this reason,
   it is important that there be a mechanism by which the returned data
   can be matched up with the original "message/external-body" entity.
   MIME mail servers must use the same Content-ID field on the returned
   message that was used in the original "message/external-body"
   entities, to facilitate such matching.

5.2.3.6.  External-Body Security Issues

   "Message/external-body" entities give rise to two important security
   issues:

    (1)   Accessing data via a "message/external-body" reference
          effectively results in the message recipient performing
          an operation that was specified by the message
          originator.  It is therefore possible for the message
          originator to trick a recipient into doing something
          they would not have done otherwise.  For example, an
          originator could specify a action that attempts
          retrieval of material that the recipient is not
          authorized to obtain, causing the recipient to
          unwittingly violate some security policy.  For this
          reason, user agents capable of resolving external
          references must always take steps to describe the
          action they are to take to the recipient and ask for
          explicit permisssion prior to performing it.

          The 'mail-server' access-type is particularly
          vulnerable, in that it causes the recipient to send a
          new message whose contents are specified by the
          original message's originator.  Given the potential for
          abuse, any such request messages that are constructed
          should contain a clear indication that they were
          generated automatically (e.g. in a Comments: header
          field) in an attempt to resolve a MIME



Freed & Borenstein          Standards Track                    [Page 37]

RFC 2046                      Media Types                  November 1996


          "message/external-body" reference.

    (2)   MIME will sometimes be used in environments that
          provide some guarantee of message integrity and
          authenticity.  If present, such guarantees may apply
          only to the actual direct content of messages -- they
          may or may not apply to data accessed through MIME's
          "message/external-body" mechanism.  In particular, it
          may be possible to subvert certain access mechanisms
          even when the messaging system itself is secure.

          It should be noted that this problem exists either with
          or without the availabilty of MIME mechanisms.  A
          casual reference to an FTP site containing a document
          in the text of a secure message brings up similar
          issues -- the only difference is that MIME provides for
          automatic retrieval of such material, and users may
          place unwarranted trust is such automatic retrieval
          mechanisms.

5.2.3.7.  Examples and Further Explanations

   When the external-body mechanism is used in conjunction with the
   "multipart/alternative" media type it extends the functionality of
   "multipart/alternative" to include the case where the same entity is
   provided in the same format but via different accces mechanisms.
   When this is done the originator of the message must order the parts
   first in terms of preferred formats and then by preferred access
   mechanisms.  The recipient's viewer should then evaluate the list
   both in terms of format and access mechanisms.

   With the emerging possibility of very wide-area file systems, it
   becomes very hard to know in advance the set of machines where a file
   will and will not be accessible directly from the file system.
   Therefore it may make sense to provide both a file name, to be tried
   directly, and the name of one or more sites from which the file is
   known to be accessible.  An implementation can try to retrieve remote
   files using FTP or any other protocol, using anonymous file retrieval
   or prompting the user for the necessary name and password.  If an
   external body is accessible via multiple mechanisms, the sender may
   include multiple entities of type "message/external-body" within the
   body parts of an enclosing "multipart/alternative" entity.

   However, the external-body mechanism is not intended to be limited to
   file retrieval, as shown by the mail-server access-type.  Beyond
   this, one can imagine, for example, using a video server for external
   references to video clips.




Freed & Borenstein          Standards Track                    [Page 38]

RFC 2046                      Media Types                  November 1996


   The embedded message header fields which appear in the body of the
   "message/external-body" data must be used to declare the media type
   of the external body if it is anything other than plain US-ASCII
   text, since the external body does not have a header section to
   declare its type.  Similarly, any Content-transfer-encoding other
   than "7bit" must also be declared here.  Thus a complete
   "message/external-body" message, referring to an object in PostScript
   format, might look like this:

     From: Whomever
     To: Someone
     Date: Whenever
     Subject: whatever
     MIME-Version: 1.0
     Message-ID: <id1@host.com>
     Content-Type: multipart/alternative; boundary=42
     Content-ID: <id001@guppylake.bellcore.com>

     --42
     Content-Type: message/external-body; name="BodyFormats.ps";
                   site="thumper.bellcore.com"; mode="image";
                   access-type=ANON-FTP; directory="pub";
                   expiration="Fri, 14 Jun 1991 19:13:14 -0400 (EDT)"

     Content-type: application/postscript
     Content-ID: <id42@guppylake.bellcore.com>

     --42
     Content-Type: message/external-body; access-type=local-file;
                   name="/u/nsb/writing/rfcs/RFC-MIME.ps";
                   site="thumper.bellcore.com";
                   expiration="Fri, 14 Jun 1991 19:13:14 -0400 (EDT)"

     Content-type: application/postscript
     Content-ID: <id42@guppylake.bellcore.com>

     --42
     Content-Type: message/external-body;
                   access-type=mail-server
                   server="listserv@bogus.bitnet";
                   expiration="Fri, 14 Jun 1991 19:13:14 -0400 (EDT)"

     Content-type: application/postscript
     Content-ID: <id42@guppylake.bellcore.com>

     get RFC-MIME.DOC

     --42--



Freed & Borenstein          Standards Track                    [Page 39]

RFC 2046                      Media Types                  November 1996


   Note that in the above examples, the default Content-transfer-
   encoding of "7bit" is assumed for the external postscript data.

   Like the "message/partial" type, the "message/external-body" media
   type is intended to be transparent, that is, to convey the data type
   in the external body rather than to convey a message with a body of
   that type.  Thus the headers on the outer and inner parts must be
   merged using the same rules as for "message/partial".  In particular,
   this means that the Content-type and Subject fields are overridden,
   but the From field is preserved.

   Note that since the external bodies are not transported along with
   the external body reference, they need not conform to transport
   limitations that apply to the reference itself. In particular,
   Internet mail transports may impose 7bit and line length limits, but
   these do not automatically apply to binary external body references.
   Thus a Content-Transfer-Encoding is not generally necessary, though
   it is permitted.

   Note that the body of a message of type "message/external-body" is
   governed by the basic syntax for an RFC 822 message.  In particular,
   anything before the first consecutive pair of CRLFs is header
   information, while anything after it is body information, which is
   ignored for most access-types.

5.2.4.  Other Message Subtypes

   MIME implementations must in general treat unrecognized subtypes of
   "message" as being equivalent to "application/octet-stream".

   Future subtypes of "message" intended for use with email should be
   restricted to "7bit" encoding. A type other than "message" should be
   used if restriction to "7bit" is not possible.

6.  Experimental Media Type Values

   A media type value beginning with the characters "X-" is a private
   value, to be used by consenting systems by mutual agreement.  Any
   format without a rigorous and public definition must be named with an
   "X-" prefix, and publicly specified values shall never begin with
   "X-".  (Older versions of the widely used Andrew system use the "X-
   BE2" name, so new systems should probably choose a different name.)

   In general, the use of "X-" top-level types is strongly discouraged.
   Implementors should invent subtypes of the existing types whenever
   possible. In many cases, a subtype of "application" will be more
   appropriate than a new top-level type.




Freed & Borenstein          Standards Track                    [Page 40]

RFC 2046                      Media Types                  November 1996


7.  Summary

   The five discrete media types provide provide a standardized
   mechanism for tagging entities as "audio", "image", or several other
   kinds of data. The composite "multipart" and "message" media types
   allow mixing and hierarchical structuring of entities of different
   types in a single message. A distinguished parameter syntax allows
   further specification of data format details, particularly the
   specification of alternate character sets.  Additional optional
   header fields provide mechanisms for certain extensions deemed
   desirable by many implementors. Finally, a number of useful media
   types are defined for general use by consenting user agents, notably
   "message/partial" and "message/external-body".

9.  Security Considerations

   Security issues are discussed in the context of the
   "application/postscript" type, the "message/external-body" type, and
   in RFC 2048.  Implementors should pay special attention to the
   security implications of any media types that can cause the remote
   execution of any actions in the recipient's environment.  In such
   cases, the discussion of the "application/postscript" type may serve
   as a model for considering other media types with remote execution
   capabilities.



























Freed & Borenstein          Standards Track                    [Page 41]

RFC 2046                      Media Types                  November 1996


9.  Authors' Addresses

   For more information, the authors of this document are best contacted
   via Internet mail:

   Ned Freed
   Innosoft International, Inc.
   1050 East Garvey Avenue South
   West Covina, CA 91790
   USA

   Phone: +1 818 919 3600
   Fax:   +1 818 919 3614
   EMail: ned@innosoft.com


   Nathaniel S. Borenstein
   First Virtual Holdings
   25 Washington Avenue
   Morristown, NJ 07960
   USA

   Phone: +1 201 540 8967
   Fax:   +1 201 993 3032
   EMail: nsb@nsb.fv.com


   MIME is a result of the work of the Internet Engineering Task Force
   Working Group on RFC 822 Extensions.  The chairman of that group,
   Greg Vaudreuil, may be reached at:

   Gregory M. Vaudreuil
   Octel Network Services
   17080 Dallas Parkway
   Dallas, TX 75248-1905
   USA

   EMail: Greg.Vaudreuil@Octel.Com













Freed & Borenstein          Standards Track                    [Page 42]

RFC 2046                      Media Types                  November 1996


Appendix A -- Collected Grammar

   This appendix contains the complete BNF grammar for all the syntax
   specified by this document.

   By itself, however, this grammar is incomplete.  It refers by name to
   several syntax rules that are defined by RFC 822.  Rather than
   reproduce those definitions here, and risk unintentional differences
   between the two, this document simply refers the reader to RFC 822
   for the remaining definitions. Wherever a term is undefined, it
   refers to the RFC 822 definition.

     boundary := 0*69<bchars> bcharsnospace

     bchars := bcharsnospace / " "

     bcharsnospace := DIGIT / ALPHA / "'" / "(" / ")" /
                      "+" / "_" / "," / "-" / "." /
                      "/" / ":" / "=" / "?"

     body-part := <"message" as defined in RFC 822, with all
                   header fields optional, not starting with the
                   specified dash-boundary, and with the
                   delimiter not occurring anywhere in the
                   body part.  Note that the semantics of a
                   part differ from the semantics of a message,
                   as described in the text.>

     close-delimiter := delimiter "--"

     dash-boundary := "--" boundary
                      ; boundary taken from the value of
                      ; boundary parameter of the
                      ; Content-Type field.

     delimiter := CRLF dash-boundary

     discard-text := *(*text CRLF)
                     ; May be ignored or discarded.

     encapsulation := delimiter transport-padding
                      CRLF body-part

     epilogue := discard-text

     multipart-body := [preamble CRLF]
                       dash-boundary transport-padding CRLF
                       body-part *encapsulation



Freed & Borenstein          Standards Track                    [Page 43]

RFC 2046                      Media Types                  November 1996


                       close-delimiter transport-padding
                       [CRLF epilogue]

     preamble := discard-text

     transport-padding := *LWSP-char
                          ; Composers MUST NOT generate
                          ; non-zero length transport
                          ; padding, but receivers MUST
                          ; be able to handle padding
                          ; added by message transports.








































Freed & Borenstein          Standards Track                    [Page 44]



================================================
FILE: doc/notes/rfc/rfc2047.txt
================================================






Network Working Group                                           K. Moore
Request for Comments: 2047                       University of Tennessee
Obsoletes: 1521, 1522, 1590                                November 1996
Category: Standards Track


        MIME (Multipurpose Internet Mail Extensions) Part Three:
              Message Header Extensions for Non-ASCII Text

Status of this Memo

   This document specifies an Internet standards track protocol for the
   Internet community, and requests discussion and suggestions for
   improvements.  Please refer to the current edition of the "Internet
   Official Protocol Standards" (STD 1) for the standardization state
   and status of this protocol.  Distribution of this memo is unlimited.

Abstract

   STD 11, RFC 822, defines a message representation protocol specifying
   considerable detail about US-ASCII message headers, and leaves the
   message content, or message body, as flat US-ASCII text.  This set of
   documents, collectively called the Multipurpose Internet Mail
   Extensions, or MIME, redefines the format of messages to allow for

   (1) textual message bodies in character sets other than US-ASCII,

   (2) an extensible set of different formats for non-textual message
       bodies,

   (3) multi-part message bodies, and

   (4) textual header information in character sets other than US-ASCII.

   These documents are based on earlier work documented in RFC 934, STD
   11, and RFC 1049, but extends and revises them.  Because RFC 822 said
   so little about message bodies, these documents are largely
   orthogonal to (rather than a revision of) RFC 822.

   This particular document is the third document in the series.  It
   describes extensions to RFC 822 to allow non-US-ASCII text data in
   Internet mail header fields.









Moore                       Standards Track                     [Page 1]

RFC 2047               Message Header Extensions           November 1996


   Other documents in this series include:

   + RFC 2045, which specifies the various headers used to describe
     the structure of MIME messages.

   + RFC 2046, which defines the general structure of the MIME media
     typing system and defines an initial set of media types,

   + RFC 2048, which specifies various IANA registration procedures
     for MIME-related facilities, and

   + RFC 2049, which describes MIME conformance criteria and
     provides some illustrative examples of MIME message formats,
     acknowledgements, and the bibliography.

   These documents are revisions of RFCs 1521, 1522, and 1590, which
   themselves were revisions of RFCs 1341 and 1342.  An appendix in RFC
   2049 describes differences and changes from previous versions.

1. Introduction

   RFC 2045 describes a mechanism for denoting textual body parts which
   are coded in various character sets, as well as methods for encoding
   such body parts as sequences of printable US-ASCII characters.  This
   memo describes similar techniques to allow the encoding of non-ASCII
   text in various portions of a RFC 822 [2] message header, in a manner
   which is unlikely to confuse existing message handling software.

   Like the encoding techniques described in RFC 2045, the techniques
   outlined here were designed to allow the use of non-ASCII characters
   in message headers in a way which is unlikely to be disturbed by the
   quirks of existing Internet mail handling programs.  In particular,
   some mail relaying programs are known to (a) delete some message
   header fields while retaining others, (b) rearrange the order of
   addresses in To or Cc fields, (c) rearrange the (vertical) order of
   header fields, and/or (d) "wrap" message headers at different places
   than those in the original message.  In addition, some mail reading
   programs are known to have difficulty correctly parsing message
   headers which, while legal according to RFC 822, make use of
   backslash-quoting to "hide" special characters such as "<", ",", or
   ":", or which exploit other infrequently-used features of that
   specification.

   While it is unfortunate that these programs do not correctly
   interpret RFC 822 headers, to "break" these programs would cause
   severe operational problems for the Internet mail system.  The
   extensions described in this memo therefore do not rely on little-
   used features of RFC 822.



Moore                       Standards Track                     [Page 2]

RFC 2047               Message Header Extensions           November 1996


   Instead, certain sequences of "ordinary" printable ASCII characters
   (known as "encoded-words") are reserved for use as encoded data.  The
   syntax of encoded-words is such that they are unlikely to
   "accidentally" appear as normal text in message headers.
   Furthermore, the characters used in encoded-words are restricted to
   those which do not have special meanings in the context in which the
   encoded-word appears.

   Generally, an "encoded-word" is a sequence of printable ASCII
   characters that begins with "=?", ends with "?=", and has two "?"s in
   between.  It specifies a character set and an encoding method, and
   also includes the original text encoded as graphic ASCII characters,
   according to the rules for that encoding method.

   A mail composer that implements this specification will provide a
   means of inputting non-ASCII text in header fields, but will
   translate these fields (or appropriate portions of these fields) into
   encoded-words before inserting them into the message header.

   A mail reader that implements this specification will recognize
   encoded-words when they appear in certain portions of the message
   header.  Instead of displaying the encoded-word "as is", it will
   reverse the encoding and display the original text in the designated
   character set.

NOTES

   This memo relies heavily on notation and terms defined RFC 822 and
   RFC 2045.  In particular, the syntax for the ABNF used in this memo
   is defined in RFC 822, as well as many of the terminal or nonterminal
   symbols from RFC 822 are used in the grammar for the header
   extensions defined here.  Among the symbols defined in RFC 822 and
   referenced in this memo are: 'addr-spec', 'atom', 'CHAR', 'comment',
   'CTLs', 'ctext', 'linear-white-space', 'phrase', 'quoted-pair'.
   'quoted-string', 'SPACE', and 'word'.  Successful implementation of
   this protocol extension requires careful attention to the RFC 822
   definitions of these terms.

   When the term "ASCII" appears in this memo, it refers to the "7-Bit
   American Standard Code for Information Interchange", ANSI X3.4-1986.
   The MIME charset name for this character set is "US-ASCII".  When not
   specifically referring to the MIME charset name, this document uses
   the term "ASCII", both for brevity and for consistency with RFC 822.
   However, implementors are warned that the character set name must be
   spelled "US-ASCII" in MIME message and body part headers.






Moore                       Standards Track                     [Page 3]

RFC 2047               Message Header Extensions           November 1996


   This memo specifies a protocol for the representation of non-ASCII
   text in message headers.  It specifically DOES NOT define any
   translation between "8-bit headers" and pure ASCII headers, nor is
   any such translation assumed to be possible.

2. Syntax of encoded-words

   An 'encoded-word' is defined by the following ABNF grammar.  The
   notation of RFC 822 is used, with the exception that white space
   characters MUST NOT appear between components of an 'encoded-word'.

   encoded-word = "=?" charset "?" encoding "?" encoded-text "?="

   charset = token    ; see section 3

   encoding = token   ; see section 4

   token = 1*<Any CHAR except SPACE, CTLs, and especials>

   especials = "(" / ")" / "<" / ">" / "@" / "," / ";" / ":" / "
               <"> / "/" / "[" / "]" / "?" / "." / "="

   encoded-text = 1*<Any printable ASCII character other than "?"
                     or SPACE>
                  ; (but see "Use of encoded-words in message
                  ; headers", section 5)

   Both 'encoding' and 'charset' names are case-independent.  Thus the
   charset name "ISO-8859-1" is equivalent to "iso-8859-1", and the
   encoding named "Q" may be spelled either "Q" or "q".

   An 'encoded-word' may not be more than 75 characters long, including
   'charset', 'encoding', 'encoded-text', and delimiters.  If it is
   desirable to encode more text than will fit in an 'encoded-word' of
   75 characters, multiple 'encoded-word's (separated by CRLF SPACE) may
   be used.

   While there is no limit to the length of a multiple-line header
   field, each line of a header field that contains one or more
   'encoded-word's is limited to 76 characters.

   The length restrictions are included both to ease interoperability
   through internetwork mail gateways, and to impose a limit on the
   amount of lookahead a header parser must employ (while looking for a
   final ?= delimiter) before it can decide whether a token is an
   "encoded-word" or something else.





Moore                       Standards Track                     [Page 4]

RFC 2047               Message Header Extensions           November 1996


   IMPORTANT: 'encoded-word's are designed to be recognized as 'atom's
   by an RFC 822 parser.  As a consequence, unencoded white space
   characters (such as SPACE and HTAB) are FORBIDDEN within an
   'encoded-word'.  For example, the character sequence

      =?iso-8859-1?q?this is some text?=

   would be parsed as four 'atom's, rather than as a single 'atom' (by
   an RFC 822 parser) or 'encoded-word' (by a parser which understands
   'encoded-words').  The correct way to encode the string "this is some
   text" is to encode the SPACE characters as well, e.g.

      =?iso-8859-1?q?this=20is=20some=20text?=

   The characters which may appear in 'encoded-text' are further
   restricted by the rules in section 5.

3. Character sets

   The 'charset' portion of an 'encoded-word' specifies the character
   set associated with the unencoded text.  A 'charset' can be any of
   the character set names allowed in an MIME "charset" parameter of a
   "text/plain" body part, or any character set name registered with
   IANA for use with the MIME text/plain content-type.

   Some character sets use code-switching techniques to switch between
   "ASCII mode" and other modes.  If unencoded text in an 'encoded-word'
   contains a sequence which causes the charset interpreter to switch
   out of ASCII mode, it MUST contain additional control codes such that
   ASCII mode is again selected at the end of the 'encoded-word'.  (This
   rule applies separately to each 'encoded-word', including adjacent
   'encoded-word's within a single header field.)

   When there is a possibility of using more than one character set to
   represent the text in an 'encoded-word', and in the absence of
   private agreements between sender and recipients of a message, it is
   recommended that members of the ISO-8859-* series be used in
   preference to other character sets.

4. Encodings

   Initially, the legal values for "encoding" are "Q" and "B".  These
   encodings are described below.  The "Q" encoding is recommended for
   use when most of the characters to be encoded are in the ASCII
   character set; otherwise, the "B" encoding should be used.
   Nevertheless, a mail reader which claims to recognize 'encoded-word's
   MUST be able to accept either encoding for any character set which it
   supports.



Moore                       Standards Track                     [Page 5]

RFC 2047               Message Header Extensions           November 1996


   Only a subset of the printable ASCII characters may be used in
   'encoded-text'.  Space and tab characters are not allowed, so that
   the beginning and end of an 'encoded-word' are obvious.  The "?"
   character is used within an 'encoded-word' to separate the various
   portions of the 'encoded-word' from one another, and thus cannot
   appear in the 'encoded-text' portion.  Other characters are also
   illegal in certain contexts.  For example, an 'encoded-word' in a
   'phrase' preceding an address in a From header field may not contain
   any of the "specials" defined in RFC 822.  Finally, certain other
   characters are disallowed in some contexts, to ensure reliability for
   messages that pass through internetwork mail gateways.

   The "B" encoding automatically meets these requirements.  The "Q"
   encoding allows a wide range of printable characters to be used in
   non-critical locations in the message header (e.g., Subject), with
   fewer characters available for use in other locations.

4.1. The "B" encoding

   The "B" encoding is identical to the "BASE64" encoding defined by RFC
   2045.

4.2. The "Q" encoding

   The "Q" encoding is similar to the "Quoted-Printable" content-
   transfer-encoding defined in RFC 2045.  It is designed to allow text
   containing mostly ASCII characters to be decipherable on an ASCII
   terminal without decoding.

   (1) Any 8-bit value may be represented by a "=" followed by two
       hexadecimal digits.  For example, if the character set in use
       were ISO-8859-1, the "=" character would thus be encoded as
       "=3D", and a SPACE by "=20".  (Upper case should be used for
       hexadecimal digits "A" through "F".)

   (2) The 8-bit hexadecimal value 20 (e.g., ISO-8859-1 SPACE) may be
       represented as "_" (underscore, ASCII 95.).  (This character may
       not pass through some internetwork mail gateways, but its use
       will greatly enhance readability of "Q" encoded data with mail
       readers that do not support this encoding.)  Note that the "_"
       always represents hexadecimal 20, even if the SPACE character
       occupies a different code position in the character set in use.

   (3) 8-bit values which correspond to printable ASCII characters other
       than "=", "?", and "_" (underscore), MAY be represented as those
       characters.  (But see section 5 for restrictions.)  In
       particular, SPACE and TAB MUST NOT be represented as themselves
       within encoded words.



Moore                       Standards Track                     [Page 6]

RFC 2047               Message Header Extensions           November 1996


5. Use of encoded-words in message headers

   An 'encoded-word' may appear in a message header or body part header
   according to the following rules:

(1) An 'encoded-word' may replace a 'text' token (as defined by RFC 822)
    in any Subject or Comments header field, any extension message
    header field, or any MIME body part field for which the field body
    is defined as '*text'.  An 'encoded-word' may also appear in any
    user-defined ("X-") message or body part header field.

    Ordinary ASCII text and 'encoded-word's may appear together in the
    same header field.  However, an 'encoded-word' that appears in a
    header field defined as '*text' MUST be separated from any adjacent
    'encoded-word' or 'text' by 'linear-white-space'.

(2) An 'encoded-word' may appear within a 'comment' delimited by "(" and
    ")", i.e., wherever a 'ctext' is allowed.  More precisely, the RFC
    822 ABNF definition for 'comment' is amended as follows:

    comment = "(" *(ctext / quoted-pair / comment / encoded-word) ")"

    A "Q"-encoded 'encoded-word' which appears in a 'comment' MUST NOT
    contain the characters "(", ")" or "
    'encoded-word' that appears in a 'comment' MUST be separated from
    any adjacent 'encoded-word' or 'ctext' by 'linear-white-space'.

    It is important to note that 'comment's are only recognized inside
    "structured" field bodies.  In fields whose bodies are defined as
    '*text', "(" and ")" are treated as ordinary characters rather than
    comment delimiters, and rule (1) of this section applies.  (See RFC
    822, sections 3.1.2 and 3.1.3)

(3) As a replacement for a 'word' entity within a 'phrase', for example,
    one that precedes an address in a From, To, or Cc header.  The ABNF
    definition for 'phrase' from RFC 822 thus becomes:

    phrase = 1*( encoded-word / word )

    In this case the set of characters that may be used in a "Q"-encoded
    'encoded-word' is restricted to: <upper and lower case ASCII
    letters, decimal digits, "!", "*", "+", "-", "/", "=", and "_"
    (underscore, ASCII 95.)>.  An 'encoded-word' that appears within a
    'phrase' MUST be separated from any adjacent 'word', 'text' or
    'special' by 'linear-white-space'.






Moore                       Standards Track                     [Page 7]

RFC 2047               Message Header Extensions           November 1996


   These are the ONLY locations where an 'encoded-word' may appear.  In
   particular:

   + An 'encoded-word' MUST NOT appear in any portion of an 'addr-spec'.

   + An 'encoded-word' MUST NOT appear within a 'quoted-string'.

   + An 'encoded-word' MUST NOT be used in a Received header field.

   + An 'encoded-word' MUST NOT be used in parameter of a MIME
     Content-Type or Content-Disposition field, or in any structured
     field body except within a 'comment' or 'phrase'.

   The 'encoded-text' in an 'encoded-word' must be self-contained;
   'encoded-text' MUST NOT be continued from one 'encoded-word' to
   another.  This implies that the 'encoded-text' portion of a "B"
   'encoded-word' will be a multiple of 4 characters long; for a "Q"
   'encoded-word', any "=" character that appears in the 'encoded-text'
   portion will be followed by two hexadecimal characters.

   Each 'encoded-word' MUST encode an integral number of octets.  The
   'encoded-text' in each 'encoded-word' must be well-formed according
   to the encoding specified; the 'encoded-text' may not be continued in
   the next 'encoded-word'.  (For example, "=?charset?Q?=?=
   =?charset?Q?AB?=" would be illegal, because the two hex digits "AB"
   must follow the "=" in the same 'encoded-word'.)

   Each 'encoded-word' MUST represent an integral number of characters.
   A multi-octet character may not be split across adjacent 'encoded-
   word's.

   Only printable and white space character data should be encoded using
   this scheme.  However, since these encoding schemes allow the
   encoding of arbitrary octet values, mail readers that implement this
   decoding should also ensure that display of the decoded data on the
   recipient's terminal will not cause unwanted side-effects.

   Use of these methods to encode non-textual data (e.g., pictures or
   sounds) is not defined by this memo.  Use of 'encoded-word's to
   represent strings of purely ASCII characters is allowed, but
   discouraged.  In rare cases it may be necessary to encode ordinary
   text that looks like an 'encoded-word'.









Moore                       Standards Track                     [Page 8]

RFC 2047               Message Header Extensions           November 1996


6. Support of 'encoded-word's by mail readers

6.1. Recognition of 'encoded-word's in message headers

   A mail reader must parse the message and body part headers according
   to the rules in RFC 822 to correctly recognize 'encoded-word's.

   'encoded-word's are to be recognized as follows:

   (1) Any message or body part header field defined as '*text', or any
       user-defined header field, should be parsed as follows: Beginning
       at the start of the field-body and immediately following each
       occurrence of 'linear-white-space', each sequence of up to 75
       printable characters (not containing any 'linear-white-space')
       should be examined to see if it is an 'encoded-word' according to
       the syntax rules in section 2.  Any other sequence of printable
       characters should be treated as ordinary ASCII text.

   (2) Any header field not defined as '*text' should be parsed
       according to the syntax rules for that header field.  However,
       any 'word' that appears within a 'phrase' should be treated as an
       'encoded-word' if it meets the syntax rules in section 2.
       Otherwise it should be treated as an ordinary 'word'.

   (3) Within a 'comment', any sequence of up to 75 printable characters
       (not containing 'linear-white-space'), that meets the syntax
       rules in section 2, should be treated as an 'encoded-word'.
       Otherwise it should be treated as normal comment text.

   (4) A MIME-Version header field is NOT required to be present for
       'encoded-word's to be interpreted according to this
       specification.  One reason for this is that the mail reader is
       not expected to parse the entire message header before displaying
       lines that may contain 'encoded-word's.

6.2. Display of 'encoded-word's

   Any 'encoded-word's so recognized are decoded, and if possible, the
   resulting unencoded text is displayed in the original character set.

   NOTE: Decoding and display of encoded-words occurs *after* a
   structured field body is parsed into tokens.  It is therefore
   possible to hide 'special' characters in encoded-words which, when
   displayed, will be indistinguishable from 'special' characters in the
   surrounding text.  For this and other reasons, it is NOT generally
   possible to translate a message header containing 'encoded-word's to
   an unencoded form which can be parsed by an RFC 822 mail reader.




Moore                       Standards Track                     [Page 9]

RFC 2047               Message Header Extensions           November 1996


   When displaying a particular header field that contains multiple
   'encoded-word's, any 'linear-white-space' that separates a pair of
   adjacent 'encoded-word's is ignored.  (This is to allow the use of
   multiple 'encoded-word's to represent long strings of unencoded text,
   without having to separate 'encoded-word's where spaces occur in the
   unencoded text.)

   In the event other encodings are defined in the future, and the mail
   reader does not support the encoding used, it may either (a) display
   the 'encoded-word' as ordinary text, or (b) substitute an appropriate
   message indicating that the text could not be decoded.

   If the mail reader does not support the character set used, it may
   (a) display the 'encoded-word' as ordinary text (i.e., as it appears
   in the header), (b) make a "best effort" to display using such
   characters as are available, or (c) substitute an appropriate message
   indicating that the decoded text could not be displayed.

   If the character set being used employs code-switching techniques,
   display of the encoded text implicitly begins in "ASCII mode".  In
   addition, the mail reader must ensure that the output device is once
   again in "ASCII mode" after the 'encoded-word' is displayed.

6.3. Mail reader handling of incorrectly formed 'encoded-word's

   It is possible that an 'encoded-word' that is legal according to the
   syntax defined in section 2, is incorrectly formed according to the
   rules for the encoding being used.   For example:

   (1) An 'encoded-word' which contains characters which are not legal
       for a particular encoding (for example, a "-" in the "B"
       encoding, or a SPACE or HTAB in either the "B" or "Q" encoding),
       is incorrectly formed.

   (2) Any 'encoded-word' which encodes a non-integral number of
       characters or octets is incorrectly formed.

   A mail reader need not attempt to display the text associated with an
   'encoded-word' that is incorrectly formed.  However, a mail reader
   MUST NOT prevent the display or handling of a message because an
   'encoded-word' is incorrectly formed.

7. Conformance

   A mail composing program claiming compliance with this specification
   MUST ensure that any string of non-white-space printable ASCII
   characters within a '*text' or '*ctext' that begins with "=?" and
   ends with "?=" be a valid 'encoded-word'.  ("begins" means: at the



Moore                       Standards Track                    [Page 10]

RFC 2047               Message Header Extensions           November 1996


   start of the field-body, immediately following 'linear-white-space',
   or immediately following a "(" for an 'encoded-word' within '*ctext';
   "ends" means: at the end of the field-body, immediately preceding
   'linear-white-space', or immediately preceding a ")" for an
   'encoded-word' within '*ctext'.)  In addition, any 'word' within a
   'phrase' that begins with "=?" and ends with "?=" must be a valid
   'encoded-word'.

   A mail reading program claiming compliance with this specification
   must be able to distinguish 'encoded-word's from 'text', 'ctext', or
   'word's, according to the rules in section 6, anytime they appear in
   appropriate places in message headers.  It must support both the "B"
   and "Q" encodings for any character set which it supports.  The
   program must be able to display the unencoded text if the character
   set is "US-ASCII".  For the ISO-8859-* character sets, the mail
   reading program must at least be able to display the characters which
   are also in the ASCII set.

8. Examples

   The following are examples of message headers containing 'encoded-
   word's:

   From: =?US-ASCII?Q?Keith_Moore?= <moore@cs.utk.edu>
   To: =?ISO-8859-1?Q?Keld_J=F8rn_Simonsen?= <keld@dkuug.dk>
   CC: =?ISO-8859-1?Q?Andr=E9?= Pirard <PIRARD@vm1.ulg.ac.be>
   Subject: =?ISO-8859-1?B?SWYgeW91IGNhbiByZWFkIHRoaXMgeW8=?=
    =?ISO-8859-2?B?dSB1bmRlcnN0YW5kIHRoZSBleGFtcGxlLg==?=

      Note: In the first 'encoded-word' of the Subject field above, the
      last "=" at the end of the 'encoded-text' is necessary because each
      'encoded-word' must be self-contained (the "=" character completes a
      group of 4 base64 characters representing 2 octets).  An additional
      octet could have been encoded in the first 'encoded-word' (so that
      the encoded-word would contain an exact multiple of 3 encoded
      octets), except that the second 'encoded-word' uses a different
      'charset' than the first one.

   From: =?ISO-8859-1?Q?Olle_J=E4rnefors?= <ojarnef@admin.kth.se>
   To: ietf-822@dimacs.rutgers.edu, ojarnef@admin.kth.se
   Subject: Time for ISO 10646?

   To: Dave Crocker <dcrocker@mordor.stanford.edu>
   Cc: ietf-822@dimacs.rutgers.edu, paf@comsol.se
   From: =?ISO-8859-1?Q?Patrik_F=E4ltstr=F6m?= <paf@nada.kth.se>
   Subject: Re: RFC-HDR care and feeding





Moore                       Standards Track                    [Page 11]

RFC 2047               Message Header Extensions           November 1996


   From: Nathaniel Borenstein <nsb@thumper.bellcore.com>
         (=?iso-8859-8?b?7eXs+SDv4SDp7Oj08A==?=)
   To: Greg Vaudreuil <gvaudre@NRI.Reston.VA.US>, Ned Freed
      <ned@innosoft.com>, Keith Moore <moore@cs.utk.edu>
   Subject: Test of new header generator
   MIME-Version: 1.0
   Content-type: text/plain; charset=ISO-8859-1

   The following examples illustrate how text containing 'encoded-word's
   which appear in a structured field body.  The rules are slightly
   different for fields defined as '*text' because "(" and ")" are not
   recognized as 'comment' delimiters.  [Section 5, paragraph (1)].

   In each of the following examples, if the same sequence were to occur
   in a '*text' field, the "displayed as" form would NOT be treated as
   encoded words, but be identical to the "encoded form".  This is
   because each of the encoded-words in the following examples is
   adjacent to a "(" or ")" character.

   encoded form                                displayed as
   ---------------------------------------------------------------------
   (=?ISO-8859-1?Q?a?=)                        (a)

   (=?ISO-8859-1?Q?a?= b)                      (a b)

           Within a 'comment', white space MUST appear between an
           'encoded-word' and surrounding text.  [Section 5,
           paragraph (2)].  However, white space is not needed between
           the initial "(" that begins the 'comment', and the
           'encoded-word'.


   (=?ISO-8859-1?Q?a?= =?ISO-8859-1?Q?b?=)     (ab)

           White space between adjacent 'encoded-word's is not
           displayed.

   (=?ISO-8859-1?Q?a?=  =?ISO-8859-1?Q?b?=)    (ab)

        Even multiple SPACEs between 'encoded-word's are ignored
        for the purpose of display.

   (=?ISO-8859-1?Q?a?=                         (ab)
       =?ISO-8859-1?Q?b?=)

           Any amount of linear-space-white between 'encoded-word's,
           even if it includes a CRLF followed by one or more SPACEs,
           is ignored for the purposes of display.



Moore                       Standards Track                    [Page 12]

RFC 2047               Message Header Extensions           November 1996


   (=?ISO-8859-1?Q?a_b?=)                      (a b)

           In order to cause a SPACE to be displayed within a portion
           of encoded text, the SPACE MUST be encoded as part of the
           'encoded-word'.

   (=?ISO-8859-1?Q?a?= =?ISO-8859-2?Q?_b?=)    (a b)

           In order to cause a SPACE to be displayed between two strings
           of encoded text, the SPACE MAY be encoded as part of one of
           the 'encoded-word's.

9. References

   [RFC 822] Crocker, D., "Standard for the Format of ARPA Internet Text
       Messages", STD 11, RFC 822, UDEL, August 1982.

   [RFC 2049] Borenstein, N., and N. Freed, "Multipurpose Internet Mail
       Extensions (MIME) Part Five: Conformance Criteria and Examples",
       RFC 2049, November 1996.

   [RFC 2045] Borenstein, N., and N. Freed, "Multipurpose Internet Mail
       Extensions (MIME) Part One: Format of Internet Message Bodies",
       RFC 2045, November 1996.

   [RFC 2046] Borenstein N., and N. Freed, "Multipurpose Internet Mail
       Extensions (MIME) Part Two: Media Types", RFC 2046,
       November 1996.

   [RFC 2048] Freed, N., Klensin, J., and J. Postel, "Multipurpose
       Internet Mail Extensions (MIME) Part Four: Registration
       Procedures", RFC 2048, November 1996.



















Moore                       Standards Track                    [Page 13]

RFC 2047               Message Header Extensions           November 1996


10. Security Considerations

   Security issues are not discussed in this memo.

11. Acknowledgements

   The author wishes to thank Nathaniel Borenstein, Issac Chan, Lutz
   Donnerhacke, Paul Eggert, Ned Freed, Andreas M. Kirchwitz, Olle
   Jarnefors, Mike Rosin, Yutaka Sato, Bart Schaefer, and Kazuhiko
   Yamamoto, for their helpful advice, insightful comments, and
   illuminating questions in response to earlier versions of this
   specification.

12. Author's Address

   Keith Moore
   University of Tennessee
   107 Ayres Hall
   Knoxville TN 37996-1301

   EMail: moore@cs.utk.edu






























Moore                       Standards Track                    [Page 14]

RFC 2047               Message Header Extensions           November 1996


Appendix - changes since RFC 1522 (in no particular order)

   + explicitly state that the MIME-Version is not requried to use
     'encoded-word's.

   + add explicit note that SPACEs and TABs are not allowed within
     'encoded-word's, explaining that an 'encoded-word' must look like an
     'atom' to an RFC822 parser.values, to be precise).

   + add examples from Olle Jarnefors (thanks!) which illustrate how
     encoded-words with adjacent linear-white-space are displayed.

   + explicitly list terms defined in RFC822 and referenced in this memo

   + fix transcription typos that caused one or two lines and a couple of
     characters to disappear in the resulting text, due to nroff quirks.

   + clarify that encoded-words are allowed in '*text' fields in both
     RFC822 headers and MIME body part headers, but NOT as parameter
     values.

   + clarify the requirement to switch back to ASCII within the encoded
     portion of an 'encoded-word', for any charset that uses code switching
     sequences.

   + add a note about 'encoded-word's being delimited by "(" and ")"
     within a comment, but not in a *text (how bizarre!).

   + fix the Andre Pirard example to get rid of the trailing "_" after
     the =E9.  (no longer needed post-1342).

   + clarification: an 'encoded-word' may appear immediately following
     the initial "(" or immediately before the final ")" that delimits a
     comment, not just adjacent to "(" and ")" *within* *ctext.

   + add a note to explain that a "B" 'encoded-word' will always have a
     multiple of 4 characters in the 'encoded-text' portion.

   + add note about the "=" in the examples

   + note that processing of 'encoded-word's occurs *after* parsing, and
     some of the implications thereof.

   + explicitly state that you can't expect to translate between
     1522 and either vanilla 822 or so-called "8-bit headers".

   + explicitly state that 'encoded-word's are not valid within a
     'quoted-string'.



Moore                       Standards Track                    [Page 15]



================================================
FILE: doc/notes/rfc/rfc2048.txt
================================================






Network Working Group                                           N. Freed
Request for Comments: 2048                                      Innosoft
BCP: 13                                                       J. Klensin
Obsoletes: 1521, 1522, 1590                                          MCI
Category: Best Current Practice                                J. Postel
                                                                     ISI
                                                           November 1996


                 Multipurpose Internet Mail Extensions
                           (MIME) Part Four:
                        Registration Procedures

Status of this Memo

   This document specifies an Internet Best Current Practices for the
   Internet Community, and requests discussion and suggestions for
   improvements.  Distribution of this memo is unlimited.

Abstract

   STD 11, RFC 822, defines a message representation protocol specifying
   considerable detail about US-ASCII message headers, and leaves the
   message content, or message body, as flat US-ASCII text.  This set of
   documents, collectively called the Multipurpose Internet Mail
   Extensions, or MIME, redefines the format of messages to allow for

    (1)   textual message bodies in character sets other than
          US-ASCII,

    (2)   an extensible set of different formats for non-textual
          message bodies,

    (3)   multi-part message bodies, and

    (4)   textual header information in character sets other than
          US-ASCII.

   These documents are based on earlier work documented in RFC 934, STD
   11, and RFC 1049, but extends and revises them.  Because RFC 822 said
   so little about message bodies, these documents are largely
   orthogonal to (rather than a revision of) RFC 822.









Freed, et. al.           Best Current Practice                  [Page 1]

RFC 2048              MIME Registration Procedures         November 1996


   This fourth document, RFC 2048, specifies various IANA registration
   procedures for the following MIME facilities:

    (1)   media types,

    (2)   external body access types,

    (3)   content-transfer-encodings.

   Registration of character sets for use in MIME is covered elsewhere
   and is no longer addressed by this document.

   These documents are revisions of RFCs 1521 and 1522, which themselves
   were revisions of RFCs 1341 and 1342.  An appendix in RFC 2049
   describes differences and changes from previous versions.

Table of Contents

   1. Introduction .........................................    3
   2. Media Type Registration ..............................    4
   2.1 Registration Trees and Subtype Names ................    4
   2.1.1 IETF Tree .........................................    4
   2.1.2 Vendor Tree .......................................    4
   2.1.3 Personal or Vanity Tree ...........................    5
   2.1.4 Special `x.' Tree .................................    5
   2.1.5 Additional Registration Trees .....................    6
   2.2 Registration Requirements ...........................    6
   2.2.1 Functionality Requirement .........................    6
   2.2.2 Naming Requirements ...............................    6
   2.2.3 Parameter Requirements ............................    7
   2.2.4 Canonicalization and Format Requirements ..........    7
   2.2.5 Interchange Recommendations .......................    8
   2.2.6 Security Requirements .............................    8
   2.2.7 Usage and Implementation Non-requirements .........    9
   2.2.8 Publication Requirements ..........................   10
   2.2.9 Additional Information ............................   10
   2.3 Registration Procedure ..............................   11
   2.3.1 Present the Media Type to the Community for  Review   11
   2.3.2 IESG Approval .....................................   12
   2.3.3 IANA Registration .................................   12
   2.4 Comments on Media Type Registrations ................   12
   2.5 Location of Registered Media Type List ..............   12
   2.6 IANA Procedures for Registering Media Types .........   12
   2.7 Change Control ......................................   13
   2.8 Registration Template ...............................   14
   3. External Body Access Types ...........................   14
   3.1 Registration Requirements ...........................   15
   3.1.1 Naming Requirements ...............................   15



Freed, et. al.           Best Current Practice                  [Page 2]

RFC 2048              MIME Registration Procedures         November 1996


   3.1.2 Mechanism Specification Requirements ..............   15
   3.1.3 Publication Requirements ..........................   15
   3.1.4 Security Requirements .............................   15
   3.2 Registration Procedure ..............................   15
   3.2.1 Present the Access Type to the Community ..........   16
   3.2.2 Access Type Reviewer ..............................   16
   3.2.3 IANA Registration .................................   16
   3.3 Location of Registered Access Type List .............   16
   3.4 IANA Procedures for Registering Access Types ........   16
   4. Transfer Encodings ...................................   17
   4.1 Transfer Encoding Requirements ......................   17
   4.1.1 Naming Requirements ...............................   17
   4.1.2 Algorithm Specification Requirements ..............   18
   4.1.3 Input Domain Requirements .........................   18
   4.1.4 Output Range Requirements .........................   18
   4.1.5 Data Integrity and Generality Requirements ........   18
   4.1.6 New Functionality Requirements ....................   18
   4.2 Transfer Encoding Definition Procedure ..............   19
   4.3 IANA Procedures for Transfer Encoding Registration...   19
   4.4 Location of Registered Transfer Encodings List ......   19
   5. Authors' Addresses ...................................   20
   A. Grandfathered Media Types ............................   21

1.  Introduction

   Recent Internet protocols have been carefully designed to be easily
   extensible in certain areas.  In particular, MIME [RFC 2045] is an
   open-ended framework and can accommodate additional object types,
   character sets, and access methods without any changes to the basic
   protocol.  A registration process is needed, however, to ensure that
   the set of such values is developed in an orderly, well-specified,
   and public manner.

   This document defines registration procedures which use the Internet
   Assigned Numbers Authority (IANA) as a central registry for such
   values.

   Historical Note: The registration process for media types was
   initially defined in the context of the asynchronous Internet mail
   environment.  In this mail environment there is a need to limit the
   number of possible media types to increase the likelihood of
   interoperability when the capabilities of the remote mail system are
   not known.  As media types are used in new environments, where the
   proliferation of media types is not a hindrance to interoperability,
   the original procedure was excessively restrictive and had to be
   generalized.





Freed, et. al.           Best Current Practice                  [Page 3]

RFC 2048              MIME Registration Procedures         November 1996


2.  Media Type Registration

   Registration of a new media type or types starts with the
   construction of a registration proposal.  Registration may occur in
   several different registration trees, which have different
   requirements as discussed below.  In general, the new registration
   proposal is circulated and reviewed in a fashion appropriate to the
   tree involved.  The media type is then registered if the proposal is
   acceptable.  The following sections describe the requirements and
   procedures used for each of the different registration trees.

2.1.  Registration Trees and Subtype Names

   In order to increase the efficiency and flexibility of the
   registration process, different structures of subtype names may be
   registered to accomodate the different natural requirements for,
   e.g., a subtype that will be recommended for wide support and
   implementation by the Internet Community or a subtype that is used to
   move files associated with proprietary software.  The following
   subsections define registration "trees", distinguished by the use of
   faceted names (e.g., names of the form "tree.subtree...type").  Note
   that some media types defined prior to this document do not conform
   to the naming conventions described below.  See Appendix A for a
   discussion of them.

2.1.1.  IETF Tree

   The IETF tree is intended for types of general interest to the
   Internet Community. Registration in the IETF tree requires approval
   by the IESG and publication of the media type registration as some
   form of RFC.

   Media types in the IETF tree are normally denoted by names that are
   not explicitly faceted, i.e., do not contain period (".", full stop)
   characters.

   The "owner" of a media type registration in the IETF tree is assumed
   to be the IETF itself.  Modification or alteration of the
   specification requires the same level of processing (e.g.  standards
   track) required for the initial registration.

2.1.2.  Vendor Tree

   The vendor tree is used for media types associated with commercially
   available products.  "Vendor" or "producer" are construed as
   equivalent and very broadly in this context.





Freed, et. al.           Best Current Practice                  [Page 4]

RFC 2048              MIME Registration Procedures         November 1996


   A registration may be placed in the vendor tree by anyone who has
   need to interchange files associated with the particular product.
   However, the registration formally belongs to the vendor or
   organization producing the software or file format.  Changes to the
   specification will be made at their request, as discussed in
   subsequent sections.

   Registrations in the vendor tree will be distinguished by the leading
   facet "vnd.".  That may be followed, at the discretion of the
   registration, by either a media type name from a well-known producer
   (e.g., "vnd.mudpie") or by an IANA-approved designation of the
   producer's name which is then followed by a media type or product
   designation (e.g., vnd.bigcompany.funnypictures).

   While public exposure and review of media types to be registered in
   the vendor tree is not required, using the ietf-types list for review
   is strongly encouraged to improve the quality of those
   specifications. Registrations in the vendor tree may be submitted
   directly to the IANA.

2.1.3.  Personal or Vanity Tree

   Registrations for media types created experimentally or as part of
   products that are not distributed commercially may be registered in
   the personal or vanity tree.  The registrations are distinguished by
   the leading facet "prs.".

   The owner of "personal" registrations and associated specifications
   is the person or entity making the registration, or one to whom
   responsibility has been transferred as described below.

   While public exposure and review of media types to be registered in
   the personal tree is not required, using the ietf-types list for
   review is strongly encouraged to improve the quality of those
   specifications.  Registrations in the personl tree may be submitted
   directly to the IANA.

2.1.4.  Special `x.' Tree

   For convenience and symmetry with this registration scheme, media
   type names with "x." as the first facet may be used for the same
   purposes for which names starting in "x-" are normally used.  These
   types are unregistered, experimental, and should be used only with
   the active agreement of the parties exchanging them.







Freed, et. al.           Best Current Practice                  [Page 5]

RFC 2048              MIME Registration Procedures         November 1996


   However, with the simplified registration procedures described above
   for vendor and personal trees, it should rarely, if ever, be
   necessary to use unregistered experimental types, and as such use of
   both "x-" and "x." forms is discouraged.

2.1.5.  Additional Registration Trees

   From time to time and as required by the community, the IANA may,
   with the advice and consent of the IESG, create new top-level
   registration trees.  It is explicitly assumed that these trees may be
   created for external registration and management by well-known
   permanent bodies, such as scientific societies for media types
   specific to the sciences they cover.  In general, the quality of
   review of specifications for one of these additional registration
   trees is expected to be equivalent to that which IETF would give to
   registrations in its own tree. Establishment of these new trees will
   be announced through RFC publication approved by the IESG.

2.2.  Registration Requirements

   Media type registration proposals are all expected to conform to
   various requirements laid out in the following sections.  Note that
   requirement specifics sometimes vary depending on the registration
   tree, again as detailed in the following sections.

2.2.1.  Functionality Requirement

   Media types must function as an actual media format: Registration of
   things that are better thought of as a transfer encoding, as a
   character set, or as a collection of separate entities of another
   type, is not allowed.  For example, although applications exist to
   decode the base64 transfer encoding [RFC 2045], base64 cannot be
   registered as a media type.

   This requirement applies regardless of the registration tree
   involved.

2.2.2.  Naming Requirements

   All registered media types must be assigned MIME type and subtype
   names. The combination of these names then serves to uniquely
   identify the media type and the format of the subtype name identifies
   the registration tree.

   The choice of top-level type name must take the nature of media type
   involved into account. For example, media normally used for
   representing still images should be a subtype of the image content
   type, whereas media capable of representing audio information belongs



Freed, et. al.           Best Current Practice                  [Page 6]

RFC 2048              MIME Registration Procedures         November 1996


   under the audio content type. See RFC 2046 for additional information
   on the basic set of top-level types and their characteristics.

   New subtypes of top-level types must conform to the restrictions of
   the top-level type, if any. For example, all subtypes of the
   multipart content type must use the same encapsulation syntax.

   In some cases a new media type may not "fit" under any currently
   defined top-level content type. Such cases are expected to be quite
   rare. However, if such a case arises a new top-level type can be
   defined to accommodate it. Such a definition must be done via
   standards-track RFC; no other mechanism can be used to define
   additional top-level content types.

   These requirements apply regardless of the registration tree
   involved.

2.2.3.  Parameter Requirements

   Media types may elect to use one or more MIME content type
   parameters, or some parameters may be automatically made available to
   the media type by virtue of being a subtype of a content type that
   defines a set of parameters applicable to any of its subtypes.  In
   either case, the names, values, and meanings of any parameters must
   be fully specified when a media type is registered in the IETF tree,
   and should be specified as completely as possible when media types
   are registered in the vendor or personal trees.

   New parameters must not be defined as a way to introduce new
   functionality in types registered in the IETF tree, although new
   parameters may be added to convey additional information that does
   not otherwise change existing functionality.  An example of this
   would be a "revision" parameter to indicate a revision level of an
   external specification such as JPEG.  Similar behavior is encouraged
   for media types registered in the vendor or personal trees but is not
   required.

2.2.4.  Canonicalization and Format Requirements

   All registered media types must employ a single, canonical data
   format, regardless of registration tree.

   A precise and openly available specification of the format of each
   media type is required for all types registered in the IETF tree and
   must at a minimum be referenced by, if it isn't actually included in,
   the media type registration proposal itself.





Freed, et. al.           Best Current Practice                  [Page 7]

RFC 2048              MIME Registration Procedures         November 1996


   The specifications of format and processing particulars may or may
   not be publically available for media types registered in the vendor
   tree, and such registration proposals are explicitly permitted to
   include only a specification of which software and version produce or
   process such media types.  References to or inclusion of format
   specifications in registration proposals is encouraged but not
   required.

   Format specifications are still required for registration in the
   personal tree, but may be either published as RFCs or otherwise
   deposited with IANA. The deposited specifications will meet the same
   criteria as those required to register a well-known TCP port and, in
   particular, need not be made public.

   Some media types involve the use of patented technology.  The
   registration of media types involving patented technology is
   specifically permitted.  However, the restrictions set forth in RFC
   1602 on the use of patented technology in standards-track protocols
   must be respected when the specification of a media type is part of a
   standards-track protocol.

2.2.5.  Interchange Recommendations

   Media types should, whenever possible, interoperate across as many
   systems and applications as possible. However, some media types will
   inevitably have problems interoperating across different platforms.
   Problems with different versions, byte ordering, and specifics of
   gateway handling can and will arise.

   Universal interoperability of media types is not required, but known
   interoperability issues should be identified whenever possible.
   Publication of a media type does not require an exhaustive review of
   interoperability, and the interoperability considerations section is
   subject to continuing evaluation.

   These recommendations apply regardless of the registration tree
   involved.

2.2.6.  Security Requirements

   An analysis of security issues is required for for all types
   registered in the IETF Tree.  (This is in accordance with the basic
   requirements for all IETF protocols.) A similar analysis for media
   types registered in the vendor or personal trees is encouraged but
   not required.  However, regardless of what security analysis has or
   has not been done, all descriptions of security issues must be as
   accurate as possible regardless of registration tree.  In particular,
   a statement that there are "no security issues associated with this



Freed, et. al.           Best Current Practice                  [Page 8]

RFC 2048              MIME Registration Procedures         November 1996


   type" must not be confused with "the security issues associates with
   this type have not been assessed".

   There is absolutely no requirement that media types registered in any
   tree be secure or completely free from risks.  Nevertheless, all
   known security risks must be identified in the registration of a
   media type, again regardless of registration tree.

   The security considerations section of all registrations is subject
   to continuing evaluation and modification, and in particular may be
   extended by use of the "comments on media types" mechanism described
   in subsequent sections.

   Some of the issues that should be looked at in a security analysis of
   a media type are:

    (1)   Complex media types may include provisions for
          directives that institute actions on a recipient's
          files or other resources.  In many cases provision is
          made for originators to specify arbitrary actions in an
          unrestricted fashion which may then have devastating
          effects.  See the registration of the
          application/postscript media type in RFC 2046 for
          an example of such directives and how to handle them.

    (2)   Complex media types may include provisions for
          directives that institute actions which, while not
          directly harmful to the recipient, may result in
          disclosure of information that either facilitates a
          subsequent attack or else violates a recipient's
          privacy in some way.  Again, the registration of the
          application/postscript media type illustrates how such
          directives can be handled.

    (3)   A media type might be targeted for applications that
          require some sort of security assurance but not provide
          the necessary security mechanisms themselves. For
          example, a media type could be defined for storage of
          confidential medical information which in turn requires
          an external confidentiality service.

2.2.7.  Usage and Implementation Non-requirements

   In the asynchronous mail environment, where information on the
   capabilities of the remote mail agent is frequently not available to
   the sender, maximum interoperability is attained by restricting the
   number of media types used to those "common" formats expected to be
   widely implemented.  This was asserted in the past as a reason to



Freed, et. al.           Best Current Practice                  [Page 9]

RFC 2048              MIME Registration Procedures         November 1996


   limit the number of possible media types and resulted in a
   registration process with a significant hurdle and delay for those
   registering media types.

   However, the need for "common" media types does not require limiting
   the registration of new media types. If a limited set of media types
   is recommended for a particular application, that should be asserted
   by a separate applicability statement specific for the application
   and/or environment.

   As such, universal support and implementation of a media type is NOT
   a requirement for registration.  If, however, a media type is
   explicitly intended for limited use, this should be noted in its
   registration.

2.2.8.  Publication Requirements

   Proposals for media types registered in the IETF tree must be
   published as RFCs. RFC publication of vendor and personal media type
   proposals is encouraged but not required. In all cases IANA will
   retain copies of all media type proposals and "publish" them as part
   of the media types registration tree itself.

   Other than in the IETF tree, the registration of a data type does not
   imply endorsement, approval, or recommendation by IANA or IETF or
   even certification that the specification is adequate.  To become
   Internet Standards, protocol, data objects, or whatever must go
   through the IETF standards process.  This is too difficult and too
   lengthy a process for the convenient registration of media types.

   The IETF tree exists for media types that do require require a
   substantive review and approval process with the vendor and personal
   trees exist for those that do not. It is expected that applicability
   statements for particular applications will be published from time to
   time that recommend implementation of, and support for, media types
   that have proven particularly useful in those contexts.

   As discussed above, registration of a top-level type requires
   standards-track processing and, hence, RFC publication.

2.2.9.  Additional Information

   Various sorts of optional information may be included in the
   specification of a media type if it is available:

    (1)   Magic number(s) (length, octet values). Magic numbers
          are byte sequences that are always present and thus can
          be used to identify entities as being of a given media



Freed, et. al.           Best Current Practice                 [Page 10]

RFC 2048              MIME Registration Procedures         November 1996


          type.

    (2)   File extension(s) commonly used on one or more
          platforms to indicate that some file containing a given
          type of media.

    (3)   Macintosh File Type code(s) (4 octets) used to label
          files containing a given type of media.

   Such information is often quite useful to implementors and if
   available should be provided.

2.3.  Registration Procedure

   The following procedure has been implemented by the IANA for review
   and approval of new media types.  This is not a formal standards
   process, but rather an administrative procedure intended to allow
   community comment and sanity checking without excessive time delay.
   For registration in the IETF tree, the normal IETF processes should
   be followed, treating posting of an internet-draft and announcement
   on the ietf-types list (as described in the next subsection) as a
   first step.  For registrations in the vendor or personal tree, the
   initial review step described below may be omitted and the type
   registered directly by submitting the template and an explanation
   directly to IANA (at iana@iana.org).  However, authors of vendor or
   personal media type specifications are encouraged to seek community
   review and comment whenever that is feasible.

2.3.1.  Present the Media Type to the Community for Review

   Send a proposed media type registration to the "ietf-types@iana.org"
   mailing list for a two week review period.  This mailing list has
   been established for the purpose of reviewing proposed media and
   access types. Proposed media types are not formally registered and
   must not be used; the "x-" prefix specified in RFC 2045 can be used
   until registration is complete.

   The intent of the public posting is to solicit comments and feedback
   on the choice of type/subtype name, the unambiguity of the references
   with respect to versions and external profiling information, and a
   review of any interoperability or security considerations. The
   submitter may submit a revised registration, or withdraw the
   registration completely, at any time.








Freed, et. al.           Best Current Practice                 [Page 11]

RFC 2048              MIME Registration Procedures         November 1996


2.3.2.  IESG Approval

   Media types registered in the IETF tree must be submitted to the IESG
   for approval.

2.3.3.  IANA Registration

   Provided that the media type meets the requirements for media types
   and has obtained approval that is necessary, the author may submit
   the registration request to the IANA, which will register the media
   type and make the media type registration available to the community.

2.4.  Comments on Media Type Registrations

   Comments on registered media types may be submitted by members of the
   community to IANA.  These comments will be passed on to the "owner"
   of the media type if possible.  Submitters of comments may request
   that their comment be attached to the media type registration itself,
   and if IANA approves of this the comment will be made accessible in
   conjunction with the type registration itself.

2.5.  Location of Registered Media Type List

   Media type registrations will be posted in the anonymous FTP
   directory "ftp://ftp.isi.edu/in-notes/iana/assignments/media-types/"
   and all registered media types will be listed in the periodically
   issued "Assigned Numbers" RFC [currently STD 2, RFC 1700].  The media
   type description and other supporting material may also be published
   as an Informational RFC by sending it to "rfc-editor@isi.edu" (please
   follow the instructions to RFC authors [RFC-1543]).

2.6.  IANA Procedures for Registering Media Types

   The IANA will only register media types in the IETF tree in response
   to a communication from the IESG stating that a given registration
   has been approved. Vendor and personal types will be registered by
   the IANA automatically and without any formal review as long as the
   following minimal conditions are met:

    (1)   Media types must function as an actual media format.
          In particular, character sets and transfer encodings
          may not be registered as media types.

    (2)   All media types must have properly formed type and
          subtype names. All type names must be defined by a
          standards-track RFC. All subtype names must be unique,
          must conform to the MIME grammar for such names, and
          must contain the proper tree prefix.



Freed, et. al.           Best Current Practice                 [Page 12]

RFC 2048              MIME Registration Procedures         November 1996


    (3)   Types registered in the personal tree must either
          provide a format specification or a pointer to one.

    (4)   Any security considerations given must not be obviously
          bogus. (It is neither possible nor necessary for the
          IANA to conduct a comprehensive security review of
          media type registrations.  Nevertheless, IANA has the
          authority to identify obviously incompetent material
          and exclude it.)

2.7.  Change Control

   Once a media type has been published by IANA, the author may request
   a change to its definition. The descriptions of the different
   registration trees above designate the "owners" of each type of
   registration. The change request follows the same procedure as the
   registration request:

    (1)   Publish the revised template on the ietf-types list.

    (2)   Leave at least two weeks for comments.

    (3)   Publish using IANA after formal review if required.

   Changes should be requested only when there are serious omission or
   errors in the published specification. When review is required, a
   change request may be denied if it renders entities that were valid
   under the previous definition invalid under the new definition.

   The owner of a content type may pass responsibility for the content
   type to another person or agency by informing IANA and the ietf-types
   list; this can be done without discussion or review.

   The IESG may reassign responsibility for a media type. The most
   common case of this will be to enable changes to be made to types
   where the author of the registration has died, moved out of contact
   or is otherwise unable to make changes that are important to the
   community.

   Media type registrations may not be deleted; media types which are no
   longer believed appropriate for use can be declared OBSOLETE by a
   change to their "intended use" field; such media types will be
   clearly marked in the lists published by IANA.








Freed, et. al.           Best Current Practice                 [Page 13]

RFC 2048              MIME Registration Procedures         November 1996


2.8.  Registration Template

     To: ietf-types@iana.org
     Subject: Registration of MIME media type XXX/YYY

     MIME media type name:

     MIME subtype name:

     Required parameters:

     Optional parameters:

     Encoding considerations:

     Security considerations:

     Interoperability considerations:

     Published specification:

     Applications which use this media type:

     Additional information:

       Magic number(s):
       File extension(s):
       Macintosh File Type Code(s):

     Person & email address to contact for further information:

     Intended usage:

     (One of COMMON, LIMITED USE or OBSOLETE)

     Author/Change controller:

     (Any other information that the author deems interesting may be
     added below this line.)

3.  External Body Access Types

   RFC 2046 defines the message/external-body media type, whereby a MIME
   entity can act as pointer to the actual body data in lieu of
   including the data directly in the entity body. Each
   message/external-body reference specifies an access type, which
   determines the mechanism used to retrieve the actual body data. RFC
   2046 defines an initial set of access types, but allows for the



Freed, et. al.           Best Current Practice                 [Page 14]

RFC 2048              MIME Registration Procedures         November 1996


   registration of additional access types to accommodate new retrieval
   mechanisms.

3.1.  Registration Requirements

   New access type specifications must conform to a number of
   requirements as described below.

3.1.1.  Naming Requirements

   Each access type must have a unique name.  This name appears in the
   access-type parameter in the message/external-body content-type
   header field, and must conform to MIME content type parameter syntax.

3.1.2.  Mechanism Specification Requirements

   All of the protocols, transports, and procedures used by a given
   access type must be described, either in the specification of the
   access type itself or in some other publicly available specification,
   in sufficient detail for the access type to be implemented by any
   competent implementor.  Use of secret and/or proprietary methods in
   access types are expressly prohibited. The restrictions imposed by
   RFC 1602 on the standardization of patented algorithms must be
   respected as well.

3.1.3.  Publication Requirements

   All access types must be described by an RFC. The RFC may be
   informational rather than standards-track, although standard-track
   review and approval are encouraged for all access types.

3.1.4.  Security Requirements

   Any known security issues that arise from the use of the access type
   must be completely and fully described. It is not required that the
   access type be secure or that it be free from risks, but that the
   known risks be identified.  Publication of a new access type does not
   require an exhaustive security review, and the security
   considerations section is subject to continuing evaluation.
   Additional security considerations should be addressed by publishing
   revised versions of the access type specification.

3.2.  Registration Procedure

   Registration of a new access type starts with the construction of a
   draft of an RFC.





Freed, et. al.           Best Current Practice                 [Page 15]

RFC 2048              MIME Registration Procedures         November 1996


3.2.1.  Present the Access Type to the Community

   Send a proposed access type specification to the "ietf-
   types@iana.org" mailing list for a two week review period.  This
   mailing list has been established for the purpose of reviewing
   proposed access and media types.  Proposed access types are not
   formally registered and must not be used.

   The intent of the public posting is to solicit comments and feedback
   on the access type specification and a review of any security
   considerations.

3.2.2.  Access Type Reviewer

   When the two week period has passed, the access type reviewer, who is
   appointed by the IETF Applications Area Director, either forwards the
   request to iana@isi.edu, or rejects it because of significant
   objections raised on the list.

   Decisions made by the reviewer must be posted to the ietf-types
   mailing list within 14 days. Decisions made by the reviewer may be
   appealed to the IESG.

3.2.3.  IANA Registration

   Provided that the access type has either passed review or has been
   successfully appealed to the IESG, the IANA will register the access
   type and make the registration available to the community. The
   specification of the access type must also be published as an RFC.
   Informational RFCs are published by sending them to "rfc-
   editor@isi.edu" (please follow the instructions to RFC authors [RFC-
   1543]).

3.3.  Location of Registered Access Type List

   Access type registrations will be posted in the anonymous FTP
   directory "ftp://ftp.isi.edu/in-notes/iana/assignments/access-types/"
   and all registered access types will be listed in the periodically
   issued "Assigned Numbers" RFC [currently RFC-1700].

3.4.  IANA Procedures for Registering Access Types

   The identity of the access type reviewer is communicated to the IANA
   by the IESG.  The IANA then only acts in response to access type
   definitions that either are approved by the access type reviewer and
   forwarded by the reviewer to the IANA for registration, or in
   response to a communication from the IESG that an access type
   definition appeal has overturned the access type reviewer's ruling.



Freed, et. al.           Best Current Practice                 [Page 16]

RFC 2048              MIME Registration Procedures         November 1996


4.  Transfer Encodings

   Transfer encodings are tranformations applied to MIME media types
   after conversion to the media type's canonical form.  Transfer
   encodings are used for several purposes:

    (1)   Many transports, especially message transports, can
          only handle data consisting of relatively short lines
          of text. There can also be severe restrictions on what
          characters can be used in these lines of text -- some
          transports are restricted to a small subset of US-ASCII
          and others cannot handle certain character sequences.
          Transfer encodings are used to transform binary data
          into textual form that can survive such transports.
          Examples of this sort of transfer encoding include the
          base64 and quoted-printable transfer encodings defined
          in RFC 2045.

    (2)   Image, audio, video, and even application entities are
          sometimes quite large. Compression algorithms are often
          quite effective in reducing the size of large entities.
          Transfer encodings can be used to apply general-purpose
          non-lossy compression algorithms to MIME entities.

    (3)   Transport encodings can be defined as a means of
          representing existing encoding formats in a MIME
          context.

   IMPORTANT:  The standardization of a large numbers of different
   transfer encodings is seen as a significant barrier to widespread
   interoperability and is expressely discouraged.  Nevertheless, the
   following procedure has been defined to provide a means of defining
   additional transfer encodings, should standardization actually be
   justified.

4.1.  Transfer Encoding Requirements

   Transfer encoding specifications must conform to a number of
   requirements as described below.

4.1.1.  Naming Requirements

   Each transfer encoding must have a unique name.  This name appears in
   the Content-Transfer-Encoding header field and must conform to the
   syntax of that field.






Freed, et. al.           Best Current Practice                 [Page 17]

RFC 2048              MIME Registration Procedures         November 1996


4.1.2.  Algorithm Specification Requirements

   All of the algorithms used in a transfer encoding (e.g.  conversion
   to printable form, compression) must be described in their entirety
   in the transfer encoding specification.  Use of secret and/or
   proprietary algorithms in standardized transfer encodings are
   expressly prohibited. The restrictions imposed by RFC 1602 on the
   standardization of patented algorithms must be respected as well.

4.1.3.  Input Domain Requirements

   All transfer encodings must be applicable to an arbitrary sequence of
   octets of any length.  Dependence on particular input forms is not
   allowed.

   It should be noted that the 7bit and 8bit encodings do not conform to
   this requirement. Aside from the undesireability of having
   specialized encodings, the intent here is to forbid the addition of
   additional encodings along the lines of 7bit and 8bit.

4.1.4.  Output Range Requirements

   There is no requirement that a particular tranfer encoding produce a
   particular form of encoded output.  However, the output format for
   each transfer encoding must be fully and completely documented.  In
   particular, each specification must clearly state whether the output
   format always lies within the confines of 7bit data, 8bit data, or is
   simply pure binary data.

4.1.5.  Data Integrity and Generality Requirements

   All transfer encodings must be fully invertible on any platform; it
   must be possible for anyone to recover the original data by
   performing the corresponding decoding operation.  Note that this
   requirement effectively excludes all forms of lossy compression as
   well as all forms of encryption from use as a transfer encoding.

4.1.6.  New Functionality Requirements

   All transfer encodings must provide some sort of new functionality.
   Some degree of functionality overlap with previously defined transfer
   encodings is acceptable, but any new transfer encoding must also
   offer something no other transfer encoding provides.








Freed, et. al.           Best Current Practice                 [Page 18]

RFC 2048              MIME Registration Procedures         November 1996


4.2.  Transfer Encoding Definition Procedure

   Definition of a new transfer encoding starts with the construction of
   a draft of a standards-track RFC.  The RFC must define the transfer
   encoding precisely and completely, and must also provide substantial
   justification for defining and standardizing a new transfer encoding.
   This specification must then be presented to the IESG for
   consideration.  The IESG can

    (1)   reject the specification outright as being
          inappropriate for standardization,

    (2)   approve the formation of an IETF working group to work
          on the specification in accordance with IETF
          procedures, or,

    (3)   accept the specification as-is and put it directly on
          the standards track.

   Transfer encoding specifications on the standards track follow normal
   IETF rules for standards track documents.  A transfer encoding is
   considered to be defined and available for use once it is on the
   standards track.

4.3.  IANA Procedures for Transfer Encoding Registration

   There is no need for a special procedure for registering Transfer
   Encodings with the IANA. All legitimate transfer encoding
   registrations must appear as a standards-track RFC, so it is the
   IESG's responsibility to notify the IANA when a new transfer encoding
   has been approved.

4.4.  Location of Registered Transfer Encodings List

   Transfer encoding registrations will be posted in the anonymous FTP
   directory "ftp://ftp.isi.edu/in-notes/iana/assignments/transfer-
   encodings/" and all registered transfer encodings will be listed in
   the periodically issued "Assigned Numbers" RFC [currently RFC-1700].













Freed, et. al.           Best Current Practice                 [Page 19]

RFC 2048              MIME Registration Procedures         November 1996


5.  Authors' Addresses

   For more information, the authors of this document are best
   contacted via Internet mail:

   Ned Freed
   Innosoft International, Inc.
   1050 East Garvey Avenue South
   West Covina, CA 91790
   USA

   Phone: +1 818 919 3600
   Fax:   +1 818 919 3614
   EMail: ned@innosoft.com


   John Klensin
   MCI
   2100 Reston Parkway
   Reston, VA 22091

   Phone: +1 703 715-7361
   Fax:   +1 703 715-7436
   EMail: klensin@mci.net


   Jon Postel
   USC/Information Sciences Institute
   4676 Admiralty Way
   Marina del Rey, CA  90292
   USA


   Phone: +1 310 822 1511
   Fax:   +1 310 823 6714
   EMail: Postel@ISI.EDU















Freed, et. al.           Best Current Practice                 [Page 20]

RFC 2048              MIME Registration Procedures         November 1996


Appendix A -- Grandfathered Media Types

   A number of media types, registered prior to 1996, would, if
   registered under the guidelines in this document, be placed into
   either the vendor or personal trees.  Reregistration of those types
   to reflect the appropriate trees is encouraged, but not required.
   Ownership and change control principles outlined in this document
   apply to those types as if they had been registered in the trees
   described above.











































Freed, et. al.           Best Current Practice                 [Page 21]



================================================
FILE: doc/notes/rfc/rfc2049.txt
================================================






Network Working Group                                          N. Freed
Request for Comments: 2049                                     Innosoft
Obsoletes: 1521, 1522, 1590                               N. Borenstein
Category: Standards Track                                 First Virtual
                                                          November 1996


                 Multipurpose Internet Mail Extensions
                           (MIME) Part Five:
                   Conformance Criteria and Examples

Status of this Memo

   This document specifies an Internet standards track protocol for the
   Internet community, and requests discussion and suggestions for
   improvements.  Please refer to the current edition of the "Internet
   Official Protocol Standards" (STD 1) for the standardization state
   and status of this protocol.  Distribution of this memo is unlimited.

Abstract

   STD 11, RFC 822, defines a message representation protocol specifying
   considerable detail about US-ASCII message headers, and leaves the
   message content, or message body, as flat US-ASCII text.  This set of
   documents, collectively called the Multipurpose Internet Mail
   Extensions, or MIME, redefines the format of messages to allow for

    (1)   textual message bodies in character sets other than
          US-ASCII,

    (2)   an extensible set of different formats for non-textual
          message bodies,

    (3)   multi-part message bodies, and

    (4)   textual header information in character sets other than
          US-ASCII.

   These documents are based on earlier work documented in RFC 934, STD
   11, and RFC 1049, but extends and revises them.  Because RFC 822 said
   so little about message bodies, these documents are largely
   orthogonal to (rather than a revision of) RFC 822.

   The initial document in this set, RFC 2045, specifies the various
   headers used to describe the structure of MIME messages. The second
   document defines the general structure of the MIME media typing
   system and defines an initial set of media types.  The third
   document, RFC 2047, describes extensions to RFC 822 to allow non-US-



Freed & Borenstein          Standards Track                     [Page 1]

RFC 2049                    MIME Conformance               November 1996


   ASCII text data in Internet mail header fields. The fourth document,
   RFC 2048, specifies various IANA registration procedures for MIME-
   related facilities. This fifth and final document describes MIME
   conformance criteria as well as providing some illustrative examples
   of MIME message formats, acknowledgements, and the bibliography.

   These documents are revisions of RFCs 1521, 1522, and 1590, which
   themselves were revisions of RFCs 1341 and 1342.  Appendix B of this
   document describes differences and changes from previous versions.

Table of Contents

   1. Introduction ..........................................    2
   2. MIME Conformance ......................................    2
   3. Guidelines for Sending Email Data .....................    6
   4. Canonical Encoding Model ..............................    9
   5. Summary ...............................................   12
   6. Security Considerations ...............................   12
   7. Authors' Addresses ....................................   12
   8. Acknowledgements ......................................   13
   A. A Complex Multipart Example ...........................   15
   B. Changes from RFC 1521, 1522, and 1590 .................   16
   C. References ............................................   20

1.  Introduction

   The first and second documents in this set define MIME header fields
   and the initial set of MIME media types.  The third document
   describes extensions to RFC822 formats to allow for character sets
   other than US-ASCII.  This document describes what portions  of MIME
   must be supported by a conformant MIME implementation. It also
   describes various pitfalls of contemporary messaging systems as well
   as the canonical encoding model MIME is based on.

2.  MIME Conformance

   The mechanisms described in these documents are open-ended.  It is
   definitely not expected that all implementations will support all
   available media types, nor that they will all share the same
   extensions.  In order to promote interoperability, however, it is
   useful to define the concept of "MIME-conformance" to define a
   certain level of implementation that allows the useful interworking
   of messages with content that differs from US-ASCII text.  In this
   section, we specify the requirements for such conformance.







Freed & Borenstein          Standards Track                     [Page 2]

RFC 2049                    MIME Conformance               November 1996


   A mail user agent that is MIME-conformant MUST:

    (1)   Always generate a "MIME-Version: 1.0" header field in
          any message it creates.

    (2)   Recognize the Content-Transfer-Encoding header field
          and decode all received data encoded by either quoted-
          printable or base64 implementations.  The identity
          transformations 7bit, 8bit, and binary must also be
          recognized.

          Any non-7bit data that is sent without encoding must be
          properly labelled with a content-transfer-encoding of
          8bit or binary, as appropriate.  If the underlying
          transport does not support 8bit or binary (as SMTP
          [RFC-821] does not), the sender is required to both
          encode and label data using an appropriate Content-
          Transfer-Encoding such as quoted-printable or base64.

    (3)   Must treat any unrecognized Content-Transfer-Encoding
          as if it had a Content-Type of "application/octet-
          stream", regardless of whether or not the actual
          Content-Type is recognized.

    (4)   Recognize and interpret the Content-Type header field,
          and avoid showing users raw data with a Content-Type
          field other than text.  Implementations  must be able
          to send at least text/plain messages, with the
          character set specified with the charset parameter if
          it is not US-ASCII.

    (5)   Ignore any content type parameters whose names they do
          not recognize.

    (6)   Explicitly handle the following media type values, to
          at least the following extents:

          Text:

            -- Recognize and display "text" mail with the
            character set "US-ASCII."

            -- Recognize other character sets at least to the
            extent of being able to inform the user about what
            character set the message uses.






Freed & Borenstein          Standards Track                     [Page 3]

RFC 2049                    MIME Conformance               November 1996


            -- Recognize the "ISO-8859-*" character sets to the
            extent of being able to display those characters that
            are common to ISO-8859-* and US-ASCII, namely all
            characters represented by octet values 1-127.

            -- For unrecognized subtypes in a known character
            set, show or offer to show the user the "raw" version
            of the data after conversion of the content from
            canonical form to local form.

            -- Treat material in an unknown character set as if
            it were "application/octet-stream".

          Image, audio, and video:

            -- At a minumum provide facilities to treat any
            unrecognized subtypes as if they were
            "application/octet-stream".

          Application:

            -- Offer the ability to remove either of the quoted-
            printable or base64 encodings defined in this
            document if they were used and put the resulting
            information in a user file.

          Multipart:

            -- Recognize the mixed subtype.  Display all relevant
            information on the message level and the body part
            header level and then display or offer to display
            each of the body parts individually.

            -- Recognize the "alternative" subtype, and avoid
            showing the user redundant parts of
            multipart/alternative mail.

            -- Recognize the "multipart/digest" subtype,
            specifically using "message/rfc822" rather than
            "text/plain" as the default media type for body parts
            inside "multipart/digest" entities.

            -- Treat any unrecognized subtypes as if they were
            "mixed".







Freed & Borenstein          Standards Track                     [Page 4]

RFC 2049                    MIME Conformance               November 1996


          Message:

            -- Recognize and display at least the RFC822 message
            encapsulation (message/rfc822) in such a way as to
            preserve any recursive structure, that is, displaying
            or offering to display the encapsulated data in
            accordance with its media type.

            -- Treat any unrecognized subtypes as if they were
            "application/octet-stream".

    (7)   Upon encountering any unrecognized Content-Type field,
          an implementation must treat it as if it had a media
          type of "application/octet-stream" with no parameter
          sub-arguments.  How such data are handled is up to an
          implementation, but likely options for handling such
          unrecognized data include offering the user to write it
          into a file (decoded from its mail transport format) or
          offering the user to name a program to which the
          decoded data should be passed as input.

    (8)   Conformant user agents are required, if they provide
          non-standard support for non-MIME messages employing
          character sets other than US-ASCII, to do so on
          received messages only. Conforming user agents must not
          send non-MIME messages containing anything other than
          US-ASCII text.

          In particular, the use of non-US-ASCII text in mail
          messages without a MIME-Version field is strongly
          discouraged as it impedes interoperability when sending
          messages between regions with different localization
          conventions. Conforming user agents MUST include proper
          MIME labelling when sending anything other than plain
          text in the US-ASCII character set.

          In addition, non-MIME user agents should be upgraded if
          at all possible to include appropriate MIME header
          information in the messages they send even if nothing
          else in MIME is supported.  This upgrade will have
          little, if any, effect on non-MIME recipients and will
          aid MIME in correctly displaying such messages.  It
          also provides a smooth transition path to eventual
          adoption of other MIME capabilities.

    (9)   Conforming user agents must ensure that any string of
          non-white-space printable US-ASCII characters within a
          "*text" or "*ctext" that begins with "=?" and ends with



Freed & Borenstein          Standards Track                     [Page 5]

RFC 2049                    MIME Conformance               November 1996


          "?=" be a valid encoded-word.  ("begins" means: At the
          start of the field-body or immediately following
          linear-white-space; "ends" means: At the end of the
          field-body or immediately preceding linear-white-
          space.) In addition, any "word" within a "phrase" that
          begins with "=?" and ends with "?=" must be a valid
          encoded-word.

    (10)  Conforming user agents must be able to distinguish
          encoded-words from "text", "ctext", or "word"s,
          according to the rules in section 4, anytime they
          appear in appropriate places in message headers.  It
          must support both the "B" and "Q" encodings for any
          character set which it supports.  The program must be
          able to display the unencoded text if the character set
          is "US-ASCII".  For the ISO-8859-* character sets, the
          mail reading program must at least be able to display
          the characters which are also in the US-ASCII set.

   A user agent that meets the above conditions is said to be MIME-
   conformant.  The meaning of this phrase is that it is assumed to be
   "safe" to send virtually any kind of properly-marked data to users of
   such mail systems, because such systems will at least be able to
   treat the data as undifferentiated binary, and will not simply splash
   it onto the screen of unsuspecting users.

   There is another sense in which it is always "safe" to send data in a
   format that is MIME-conformant, which is that such data will not
   break or be broken by any known systems that are conformant with RFC
   821 and RFC 822.  User agents that are MIME-conformant have the
   additional guarantee that the user will not be shown data that were
   never intended to be viewed as text.

3.  Guidelines for Sending Email Data

   Internet email is not a perfect, homogeneous system.  Mail may become
   corrupted at several stages in its travel to a final destination.
   Specifically, email sent throughout the Internet may travel across
   many networking technologies. Many networking and mail technologies
   do not support the full functionality possible in the SMTP transport
   environment.  Mail traversing these systems is likely to be modified
   in order that it can be transported.

   There exist many widely-deployed non-conformant MTAs in the Internet.
   These MTAs, speaking the SMTP protocol, alter messages on the fly to
   take advantage of the internal data structure of the hosts they are
   implemented on, or are just plain broken.




Freed & Borenstein          Standards Track                     [Page 6]

RFC 2049                    MIME Conformance               November 1996


   The following guidelines may be useful to anyone devising a data
   format (media type) that is supposed to survive the widest range of
   networking technologies and known broken MTAs unscathed.  Note that
   anything encoded in the base64 encoding will satisfy these rules, but
   that some well-known mechanisms, notably the UNIX uuencode facility,
   will not.  Note also that anything encoded in the Quoted-Printable
   encoding will survive most gateways intact, but possibly not some
   gateways to systems that use the EBCDIC character set.

    (1)   Under some circumstances the encoding used for data may
          change as part of normal gateway or user agent
          operation.  In particular, conversion from base64 to
          quoted-printable and vice versa may be necessary.  This
          may result in the confusion of CRLF sequences with line
          breaks in text bodies.  As such, the persistence of
          CRLF as something other than a line break must not be
          relied on.

    (2)   Many systems may elect to represent and store text data
          using local newline conventions.  Local newline
          conventions may not match the RFC822 CRLF convention --
          systems are known that use plain CR, plain LF, CRLF, or
          counted records.  The result is that isolated CR and LF
          characters are not well tolerated in general; they may
          be lost or converted to delimiters on some systems, and
          hence must not be relied on.

    (3)   The transmission of NULs (US-ASCII value 0) is
          problematic in Internet mail.  (This is largely the
          result of NULs being used as a termination character by
          many of the standard runtime library routines in the C
          programming language.) The practice of using NULs as
          termination characters is so entrenched now that
          messages should not rely on them being preserved.

    (4)   TAB (HT) characters may be misinterpreted or may be
          automatically converted to variable numbers of spaces.
          This is unavoidable in some environments, notably those
          not based on the US-ASCII character set.  Such
          conversion is STRONGLY DISCOURAGED, but it may occur,
          and mail formats must not rely on the persistence of
          TAB (HT) characters.

    (5)   Lines longer than 76 characters may be wrapped or
          truncated in some environments.  Line wrapping or line
          truncation imposed by mail transports is STRONGLY
          DISCOURAGED, but unavoidable in some cases.
          Applications which require long lines must somehow



Freed & Borenstein          Standards Track                     [Page 7]

RFC 2049                    MIME Conformance               November 1996


          differentiate between soft and hard line breaks.  (A
          simple way to do this is to use the quoted-printable
          encoding.)

    (6)   Trailing "white space" characters (SPACE, TAB (HT)) on
          a line may be discarded by some transport agents, while
          other transport agents may pad lines with these
          characters so that all lines in a mail file are of
          equal length.  The persistence of trailing white space,
          therefore, must not be relied on.

    (7)   Many mail domains use variations on the US-ASCII
          character set, or use character sets such as EBCDIC
          which contain most but not all of the US-ASCII
          characters.  The correct translation of characters not
          in the "invariant" set cannot be depended on across
          character converting gateways.  For example, this
          situation is a problem when sending uuencoded
          information across BITNET, an EBCDIC system.  Similar
          problems can occur without crossing a gateway, since
          many Internet hosts use character sets other than US-
          ASCII internally.  The definition of Printable Strings
          in X.400 adds further restrictions in certain special
          cases.  In particular, the only characters that are
          known to be consistent across all gateways are the 73
          characters that correspond to the upper and lower case
          letters A-Z and a-z, the 10 digits 0-9, and the
          following eleven special characters:

            "'"  (US-ASCII decimal value 39)
            "("  (US-ASCII decimal value 40)
            ")"  (US-ASCII decimal value 41)
            "+"  (US-ASCII decimal value 43)
            ","  (US-ASCII decimal value 44)
            "-"  (US-ASCII decimal value 45)
            "."  (US-ASCII decimal value 46)
            "/"  (US-ASCII decimal value 47)
            ":"  (US-ASCII decimal value 58)
            "="  (US-ASCII decimal value 61)
            "?"  (US-ASCII decimal value 63)

          A maximally portable mail representation will confine
          itself to relatively short lines of text in which the
          only meaningful characters are taken from this set of
          73 characters.  The base64 encoding follows this rule.

    (8)   Some mail transport agents will corrupt data that
          includes certain literal strings.  In particular, a



Freed & Borenstein          Standards Track                     [Page 8]

RFC 2049                    MIME Conformance               November 1996


          period (".") alone on a line is known to be corrupted
          by some (incorrect) SMTP implementations, and a line
          that starts with the five characters "From " (the fifth
          character is a SPACE) are commonly corrupted as well.
          A careful composition agent can prevent these
          corruptions by encoding the data (e.g., in the quoted-
          printable encoding using "=46rom " in place of "From "
          at the start of a line, and "=2E" in place of "." alone
          on a line).

   Please note that the above list is NOT a list of recommended
   practices for MTAs.  RFC 821 MTAs are prohibited from altering the
   character of white space or wrapping long lines.  These BAD and
   invalid practices are known to occur on established networks, and
   implementations should be robust in dealing with the bad effects they
   can cause.

4.  Canonical Encoding Model

   There was some confusion, in earlier versions of these documents,
   regarding the model for when email data was to be converted to
   canonical form and encoded, and in particular how this process would
   affect the treatment of CRLFs, given that the representation of
   newlines varies greatly from system to system.  For this reason, a
   canonical model for encoding is presented below.

   The process of composing a MIME entity can be modeled as being done
   in a number of steps.  Note that these steps are roughly similar to
   those steps used in PEM [RFC-1421] and are performed for each
   "innermost level" body:

    (1)   Creation of local form.

          The body to be transmitted is created in the system's
          native format.  The native character set is used and,
          where appropriate, local end of line conventions are
          used as well.  The body may be a UNIX-style text file,
          or a Sun raster image, or a VMS indexed file, or audio
          data in a system-dependent format stored only in
          memory, or anything else that corresponds to the local
          model for the representation of some form of
          information.  Fundamentally, the data is created in the
          "native" form that corresponds to the type specified by
          the media type.







Freed & Borenstein          Standards Track                     [Page 9]

RFC 2049                    MIME Conformance               November 1996


    (2)   Conversion to canonical form.

          The entire body, including "out-of-band" information
          such as record lengths and possibly file attribute
          information, is converted to a universal canonical
          form.  The specific media type of the body as well as
          its associated attributes dictate the nature of the
          canonical form that is used.  Conversion to the proper
          canonical form may involve character set conversion,
          transformation of audio data, compression, or various
          other operations specific to the various media types.
          If character set conversion is involved, however, care
          must be taken to understand the semantics of the media
          type, which may have strong implications for any
          character set conversion, e.g. with regard to
          syntactically meaningful characters in a text subtype
          other than "plain".

          For example, in the case of text/plain data, the text
          must be converted to a supported character set and
          lines must be delimited with CRLF delimiters in
          accordance with RFC 822.  Note that the restriction on
          line lengths implied by RFC 822 is eliminated if the
          next step employs either quoted-printable or base64
          encoding.

    (3)   Apply transfer encoding.

          A Content-Transfer-Encoding appropriate for this body
          is applied.  Note that there is no fixed relationship
          between the media type and the transfer encoding.  In
          particular, it may be appropriate to base the choice of
          base64 or quoted-printable on character frequency
          counts which are specific to a given instance of a
          body.

    (4)   Insertion into entity.

          The encoded body is inserted into a MIME entity with
          appropriate headers. The entity is then inserted into
          the body of a higher-level entity (message or
          multipart) as needed.

   Conversion from entity form to local form is accomplished by
   reversing these steps. Note that reversal of these steps may produce
   differing results since there is no guarantee that the original and
   final local forms are the same.




Freed & Borenstein          Standards Track                    [Page 10]

RFC 2049                    MIME Conformance               November 1996


   It is vital to note that these steps are only a model; they are
   specifically NOT a blueprint for how an actual system would be built.
   In particular, the model fails to account for two common designs:

    (1)   In many cases the conversion to a canonical form prior
          to encoding will be subsumed into the encoder itself,
          which understands local formats directly.  For example,
          the local newline convention for text bodies might be
          carried through to the encoder itself along with
          knowledge of what that format is.

    (2)   The output of the encoders may have to pass through one
          or more additional steps prior to being transmitted as
          a message.  As such, the output of the encoder may not
          be conformant with the formats specified by RFC 822.
          In particular, once again it may be appropriate for the
          converter's output to be expressed using local newline
          conventions rather than using the standard RFC 822 CRLF
          delimiters.

   Other implementation variations are conceivable as well.  The vital
   aspect of this discussion is that, in spite of any optimizations,
   collapsings of required steps, or insertion of additional processing,
   the resulting messages must be consistent with those produced by the
   model described here.  For example, a message with the following
   header fields:

     Content-type: text/foo; charset=bar
     Content-Transfer-Encoding: base64

   must be first represented in the text/foo form, then (if necessary)
   represented in the "bar" character set, and finally transformed via
   the base64 algorithm into a mail-safe form.

   NOTE: Some confusion has been caused by systems that represent
   messages in a format which uses local newline conventions which
   differ from the RFC822 CRLF convention.  It is important to note that
   these formats are not canonical RFC822/MIME.  These formats are
   instead *encodings* of RFC822, where CRLF sequences in the canonical
   representation of the message are encoded as the local newline
   convention.  Note that formats which encode CRLF sequences as, for
   example, LF are not capable of representing MIME messages containing
   binary data which contains LF octets not part of CRLF line separation
   sequences.







Freed & Borenstein          Standards Track                    [Page 11]

RFC 2049                    MIME Conformance               November 1996


5.  Summary

   This document defines what is meant by MIME Conformance. It also
   details various problems known to exist in the Internet email system
   and how to use MIME to overcome them. Finally, it describes MIME's
   canonical encoding model.

6.  Security Considerations

   Security issues are discussed in the second document in this set, RFC
   2046.

7.  Authors' Addresses

   For more information, the authors of this document are best contacted
   via Internet mail:

   Ned Freed
   Innosoft International, Inc.
   1050 East Garvey Avenue South
   West Covina, CA 91790
   USA

   Phone: +1 818 919 3600
   Fax:   +1 818 919 3614
   EMail: ned@innosoft.com

   Nathaniel S. Borenstein
   First Virtual Holdings
   25 Washington Avenue
   Morristown, NJ 07960
   USA

   Phone: +1 201 540 8967
   Fax:   +1 201 993 3032
   EMail: nsb@nsb.fv.com

   MIME is a result of the work of the Internet Engineering Task Force
   Working Group on RFC 822 Extensions.  The chairman of that group,
   Greg Vaudreuil, may be reached at:

   Gregory M. Vaudreuil
   Octel Network Services
   17080 Dallas Parkway
   Dallas, TX 75248-1905
   USA

   EMail: Greg.Vaudreuil@Octel.Com



Freed & Borenstein          Standards Track                    [Page 12]

RFC 2049                    MIME Conformance               November 1996


8.  Acknowledgements

   This document is the result of the collective effort of a large
   number of people, at several IETF meetings, on the IETF-SMTP and
   IETF-822 mailing lists, and elsewhere.  Although any enumeration
   seems doomed to suffer from egregious omissions, the following are
   among the many contributors to this effort:

     Harald Tveit Alvestrand       Marc Andreessen
     Randall Atkinson              Bob Braden
     Philippe Brandon              Brian Capouch
     Kevin Carosso                 Uhhyung Choi
     Peter Clitherow               Dave Collier-Brown
     Cristian Constantinof         John Coonrod
     Mark Crispin                  Dave Crocker
     Stephen Crocker               Terry Crowley
     Walt Daniels                  Jim Davis
     Frank Dawson                  Axel Deininger
     Hitoshi Doi                   Kevin Donnelly
     Steve Dorner                  Keith Edwards
     Chris Eich                    Dana S. Emery
     Johnny Eriksson               Craig Everhart
     Patrik Faltstrom              Erik E. Fair
     Roger Fajman                  Alain Fontaine
     Martin Forssen                James M. Galvin
     Stephen Gildea                Philip Gladstone
     Thomas Gordon                 Keld Simonsen
     Terry Gray                    Phill Gross
     James Hamilton                David Herron
     Mark Horton                   Bruce Howard
     Bill Janssen                  Olle Jarnefors
     Risto Kankkunen               Phil Karn
     Alan Katz                     Tim Kehres
     Neil Katin                    Steve Kille
     Kyuho Kim                     Anders Klemets
     John Klensin                  Valdis Kletniek
     Jim Knowles                   Stev Knowles
     Bob Kummerfeld                Pekka Kytolaakso
     Stellan Lagerstrom            Vincent Lau
     Timo Lehtinen                 Donald Lindsay
     Warner Losh                   Carlyn Lowery
     Laurence Lundblade            Charles Lynn
     John R. MacMillan             Larry Masinter
     Rick McGowan                  Michael J. McInerny
     Leo Mclaughlin                Goli Montaser-Kohsari
     Tom Moore                     John Gardiner Myers
     Erik Naggum                   Mark Needleman
     Chris Newman                  John Noerenberg



Freed & Borenstein          Standards Track                    [Page 13]

RFC 2049                    MIME Conformance               November 1996


     Mats Ohrman                   Julian Onions
     Michael Patton                David J. Pepper
     Erik van der Poel             Blake C. Ramsdell
     Christer Romson               Luc Rooijakkers
     Marshall T. Rose              Jonathan Rosenberg
     Guido van Rossum              Jan Rynning
     Harri Salminen                Michael Sanderson
     Yutaka Sato                   Markku Savela
     Richard Alan Schafer          Masahiro Sekiguchi
     Mark Sherman                  Bob Smart
     Peter Speck                   Henry Spencer
     Einar Stefferud               Michael Stein
     Klaus Steinberger             Peter Svanberg
     James Thompson                Steve Uhler
     Stuart Vance                  Peter Vanderbilt
     Greg Vaudreuil                Ed Vielmetti
     Larry W. Virden               Ryan Waldron
     Rhys Weatherly                Jay Weber
     Dave Wecker                   Wally Wedel
     Sven-Ove Westberg             Brian Wideen
     John Wobus                    Glenn Wright
     Rayan Zachariassen            David Zimmerman

   The authors apologize for any omissions from this list, which are
   certainly unintentional.


























Freed & Borenstein          Standards Track                    [Page 14]

RFC 2049                    MIME Conformance               November 1996


Appendix A -- A Complex Multipart Example

   What follows is the outline of a complex multipart message.  This
   message contains five parts that are to be displayed serially:  two
   introductory plain text objects, an embedded multipart message, a
   text/enriched object, and a closing encapsulated text message in a
   non-ASCII character set.  The embedded multipart message itself
   contains two objects to be displayed in parallel, a picture and an
   audio fragment.

     MIME-Version: 1.0
     From: Nathaniel Borenstein <nsb@nsb.fv.com>
     To: Ned Freed <ned@innosoft.com>
     Date: Fri, 07 Oct 1994 16:15:05 -0700 (PDT)
     Subject: A multipart example
     Content-Type: multipart/mixed;
                   boundary=unique-boundary-1

     This is the preamble area of a multipart message.
     Mail readers that understand multipart format
     should ignore this preamble.

     If you are reading this text, you might want to
     consider changing to a mail reader that understands
     how to properly display multipart messages.

     --unique-boundary-1

       ... Some text appears here ...

     [Note that the blank between the boundary and the start
      of the text in this part means no header fields were
      given and this is text in the US-ASCII character set.
      It could have been done with explicit typing as in the
      next part.]

     --unique-boundary-1
     Content-type: text/plain; charset=US-ASCII

     This could have been part of the previous part, but
     illustrates explicit versus implicit typing of body
     parts.

     --unique-boundary-1
     Content-Type: multipart/parallel; boundary=unique-boundary-2

     --unique-boundary-2
     Content-Type: audio/basic



Freed & Borenstein          Standards Track                    [Page 15]

RFC 2049                    MIME Conformance               November 1996


     Content-Transfer-Encoding: base64

       ... base64-encoded 8000 Hz single-channel
           mu-law-format audio data goes here ...

     --unique-boundary-2
     Content-Type: image/jpeg
     Content-Transfer-Encoding: base64

       ... base64-encoded image data goes here ...

     --unique-boundary-2--

     --unique-boundary-1
     Content-type: text/enriched

     This is <bold><italic>enriched.</italic></bold>
     <smaller>as defined in RFC 1896</smaller>

     Isn't it
     <bigger><bigger>cool?</bigger></bigger>

     --unique-boundary-1
     Content-Type: message/rfc822

     From: (mailbox in US-ASCII)
     To: (address in US-ASCII)
     Subject: (subject in US-ASCII)
     Content-Type: Text/plain; charset=ISO-8859-1
     Content-Transfer-Encoding: Quoted-printable

       ... Additional text in ISO-8859-1 goes here ...

     --unique-boundary-1--

Appendix B -- Changes from RFC 1521, 1522, and 1590

   These documents are a revision of RFC 1521, 1522, and 1590.  For the
   convenience of those familiar with the earlier documents, the changes
   from those documents are summarized in this appendix.  For further
   history, note that Appendix H in RFC 1521 specified how that document
   differed from its predecessor, RFC 1341.

    (1)   This document has been completely reformatted and split
          into multiple documents.  This was done to improve the
          quality of the plain text version of this document,
          which is required to be the reference copy.




Freed & Borenstein          Standards Track                    [Page 16]

RFC 2049                    MIME Conformance               November 1996


    (2)   BNF describing the overall structure of MIME object
          headers has been added. This is a documentation change
          only -- the underlying syntax has not changed in any
          way.

    (3)   The specific BNF for the seven media types in MIME has
          been removed.  This BNF was incorrect, incomplete, amd
          inconsistent with the type-indendependent BNF.  And
          since the type-independent BNF already fully specifies
          the syntax of the various MIME headers, the type-
          specific BNF was, in the final analysis, completely
          unnecessary and caused more problems than it solved.

    (4)   The more specific "US-ASCII" character set name has
          replaced the use of the informal term ASCII in many
          parts of these documents.

    (5)   The informal concept of a primary subtype has been
          removed.

    (6)   The term "object" was being used inconsistently.  The
          definition of this term has been clarified, along with
          the related terms "body", "body part", and "entity",
          and usage has been corrected where appropriate.

    (7)   The BNF for the multipart media type has been
          rearranged to make it clear that the CRLF preceeding
          the boundary marker is actually part of the marker
          itself rather than the preceeding body part.

    (8)   The prose and BNF describing the multipart media type
          have been changed to make it clear that the body parts
          within a multipart object MUST NOT contain any lines
          beginning with the boundary parameter string.

    (9)   In the rules on reassembling "message/partial" MIME
          entities, "Subject" is added to the list of headers to
          take from the inner message, and the example is
          modified to clarify this point.

    (10)  "Message/partial" fragmenters are restricted to
          splitting MIME objects only at line boundaries.

    (11)  In the discussion of the application/postscript type,
          an additional paragraph has been added warning about
          possible interoperability problems caused by embedding
          of binary data inside a PostScript MIME entity.




Freed & Borenstein          Standards Track                    [Page 17]

RFC 2049                    MIME Conformance               November 1996


    (12)  Added a clarifying note to the basic syntax rules for
          the Content-Type header field to make it clear that the
          following two forms:

            Content-type: text/plain; charset=us-ascii (comment)

            Content-type: text/plain; charset="us-ascii"

          are completely equivalent.

    (13)  The following sentence has been removed from the
          discussion of the MIME-Version header: "However,
          conformant software is encouraged to check the version
          number and at least warn the user if an unrecognized
          MIME-version is encountered."

    (14)  A typo was fixed that said "application/external-body"
          instead of "message/external-body".

    (15)  The definition of a character set has been reorganized
          to make the requirements clearer.

    (16)  The definition of the "image/gif" media type has been
          moved to a separate document. This change was made
          because of potential conflicts with IETF rules
          governing the standardization of patented technology.

    (17)  The definitions of "7bit" and "8bit" have been
          tightened so that use of bare CR, LF can only be used
          as end-of-line sequences.  The document also no longer
          requires that NUL characters be preserved, which brings
          MIME into alignment with real-world implementations.

    (18)  The definition of canonical text in MIME has been
          tightened so that line breaks must be represented by a
          CRLF sequence.  CR and LF characters are not allowed
          outside of this usage.  The definition of quoted-
          printable encoding has been altered accordingly.

    (19)  The definition of the quoted-printable encoding now
          includes a number of suggestions for how quoted-
          printable encoders might best handle improperly encoded
          material.

    (20)  Prose was added to clarify the use of the "7bit",
          "8bit", and "binary" transfer-encodings on multipart or
          message entities encapsulating "8bit" or "binary" data.




Freed & Borenstein          Standards Track                    [Page 18]

RFC 2049                    MIME Conformance               November 1996


    (21)  In the section on MIME Conformance, "multipart/digest"
          support was added to the list of requirements for
          minimal MIME conformance.  Also, the requirement for
          "message/rfc822" support were strengthened to clarify
          the importance of recognizing recursive structure.

    (22)  The various restrictions on subtypes of "message" are
          now specified entirely on a subtype by subtype basis.

    (23)  The definition of "message/rfc822" was changed to
          indicate that at least one of the "From", "Subject", or
          "Date" headers must be present.

    (24)  The required handling of unrecognized subtypes as
          "application/octet-stream" has been made more explicit
          in both the type definitions sections and the
          conformance guidelines.

    (25)  Examples using text/richtext were changed to
          text/enriched.

    (26)  The BNF definition of subtype has been changed to make
          it clear that either an IANA registered subtype or a
          nonstandard "X-" subtype must be used in a Content-Type
          header field.

    (27)  MIME media types that are simply registered for use and
          those that are standardized by the IETF are now
          distinguished in the MIME BNF.

    (28)  All of the various MIME registration procedures have
          been extensively revised. IANA registration procedures
          for character sets have been moved to a separate
          document that is no included in this set of documents.

    (29)  The use of escape and shift mechanisms in the US-ASCII
          and ISO-8859-X character sets these documents define
          have been clarified: Such mechanisms should never be
          used in conjunction with these character sets and their
          effect if they are used is undefined.

    (30)  The definition of the AFS access-type for
          message/external-body has been removed.

    (31)  The handling of the combination of
          multipart/alternative and message/external-body is now
          specifically addressed.




Freed & Borenstein          Standards Track                    [Page 19]

RFC 2049                    MIME Conformance               November 1996


    (32)  Security issues specific to message/external-body are
          now discussed in some detail.

Appendix C -- References

   [ATK]
        Borenstein, Nathaniel S., Multimedia Applications
        Development with the Andrew Toolkit, Prentice-Hall, 1990.

   [ISO-2022]
        International Standard -- Information Processing --
        Character Code Structure and Extension Techniques,
        ISO/IEC 2022:1994, 4th ed.

   [ISO-8859]
        International Standard -- Information Processing -- 8-bit
        Single-Byte Coded Graphic Character Sets
        - Part 1: Latin Alphabet No. 1, ISO 8859-1:1987, 1st ed.
        - Part 2: Latin Alphabet No. 2, ISO 8859-2:1987, 1st ed.
        - Part 3: Latin Alphabet No. 3, ISO 8859-3:1988, 1st ed.
        - Part 4: Latin Alphabet No. 4, ISO 8859-4:1988, 1st ed.
        - Part 5: Latin/Cyrillic Alphabet, ISO 8859-5:1988, 1st
        ed.
        - Part 6: Latin/Arabic Alphabet, ISO 8859-6:1987, 1st ed.
        - Part 7: Latin/Greek Alphabet, ISO 8859-7:1987, 1st ed.
        - Part 8: Latin/Hebrew Alphabet, ISO 8859-8:1988, 1st ed.
        - Part 9: Latin Alphabet No. 5, ISO/IEC 8859-9:1989, 1st
        ed.
        International Standard -- Information Technology -- 8-bit
        Single-Byte Coded Graphic Character Sets
        - Part 10: Latin Alphabet No. 6, ISO/IEC 8859-10:1992,
        1st ed.

   [ISO-646]
        International Standard -- Information Technology -- ISO
        7-bit Coded Character Set for Information Interchange,
        ISO 646:1991, 3rd ed..

   [JPEG]
        JPEG Draft Standard ISO 10918-1 CD.

   [MPEG]
        Video Coding Draft Standard ISO 11172 CD, ISO
        IEC/JTC1/SC2/WG11 (Motion Picture Experts Group), May,
        1991.






Freed & Borenstein          Standards Track                    [Page 20]

RFC 2049                    MIME Conformance               November 1996


   [PCM]
        CCITT, Fascicle III.4 - Recommendation G.711, "Pulse Code
        Modulation (PCM) of Voice Frequencies", Geneva, 1972.

   [POSTSCRIPT]
        Adobe Systems, Inc., PostScript Language Reference
        Manual, Addison-Wesley, 1985.

   [POSTSCRIPT2]
        Adobe Systems, Inc., PostScript Language Reference
        Manual, Addison-Wesley, Second Ed., 1990.

   [RFC-783]
        Sollins, K.R., "TFTP Protocol (revision 2)", RFC-783,
        MIT, June 1981.

   [RFC-821]
        Postel, J.B., "Simple Mail Transfer Protocol", STD 10,
        RFC 821, USC/Information Sciences Institute, August 1982.

   [RFC-822]
        Crocker, D., "Standard for the Format of ARPA Internet
        Text Messages", STD 11, RFC 822, UDEL, August 1982.

   [RFC-934]
        Rose, M. and E. Stefferud, "Proposed Standard for Message
        Encapsulation", RFC 934, Delaware and NMA, January 1985.

   [RFC-959]
        Postel, J. and J. Reynolds, "File Transfer Protocol", STD
        9, RFC 959, USC/Information Sciences Institute, October
        1985.

   [RFC-1049]
        Sirbu, M., "Content-Type Header Field for Internet
        Messages", RFC 1049, CMU, March 1988.

   [RFC-1154]
        Robinson, D., and R. Ullmann, "Encoding Header Field for
        Internet Messages", RFC 1154, Prime Computer, Inc., April
        1990.

   [RFC-1341]
        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.




Freed & Borenstein          Standards Track                    [Page 21]

RFC 2049                    MIME Conformance               November 1996


   [RFC-1342]
        Moore, K., "Representation of Non-Ascii Text in Internet
        Message Headers", RFC 1342, University of Tennessee, June
        1992.

   [RFC-1344]
        Borenstein, N., "Implications of MIME for Internet Mail
        Gateways", RFC 1344, Bellcore, June 1992.

   [RFC-1345]
        Simonsen, K., "Character Mnemonics & Character Sets", RFC
        1345, Rationel Almen Planlaegning, June 1992.

   [RFC-1421]
        Linn, J., "Privacy Enhancement for Internet Electronic
        Mail:  Part I -- Message Encryption and Authentication
        Procedures", RFC 1421, IAB IRTF PSRG, IETF PEM WG,
        February 1993.

   [RFC-1422]
        Kent, S., "Privacy Enhancement for Internet Electronic
        Mail:  Part II -- Certificate-Based Key Management", RFC
        1422, IAB IRTF PSRG, IETF PEM WG, February 1993.

   [RFC-1423]
        Balenson, D., "Privacy Enhancement for Internet
        Electronic Mail:  Part III -- Algorithms, Modes, and
        Identifiers",  IAB IRTF PSRG, IETF PEM WG, February 1993.

   [RFC-1424]
        Kaliski, B., "Privacy Enhancement for Internet Electronic
        Mail:  Part IV -- Key Certification and Related
        Services", IAB IRTF PSRG, IETF PEM WG, February 1993.

   [RFC-1521]
        Borenstein, N., and Freed, N., "MIME (Multipurpose
        Internet Mail Extensions): Mechanisms for Specifying and
        Describing the Format of Internet Message Bodies", RFC
        1521, Bellcore, Innosoft, September, 1993.

   [RFC-1522]
        Moore, K., "Representation of Non-ASCII Text in Internet
        Message Headers", RFC 1522, University of Tennessee,
        September 1993.







Freed & Borenstein          Standards Track                    [Page 22]

RFC 2049                    MIME Conformance               November 1996


   [RFC-1524]
        Borenstein, N., "A User Agent Configuration Mechanism for
        Multimedia Mail Format Information", RFC 1524, Bellcore,
        September 1993.

   [RFC-1543]
        Postel, J., "Instructions to RFC Authors", RFC 1543,
        USC/Information Sciences Institute, October 1993.

   [RFC-1556]
        Nussbacher, H., "Handling of Bi-directional Texts in
        MIME", RFC 1556, Israeli Inter-University Computer
        Center, December 1993.

   [RFC-1590]
        Postel, J., "Media Type Registration Procedure", RFC
        1590, USC/Information Sciences Institute, March 1994.

   [RFC-1602]
        Internet Architecture Board, Internet Engineering
        Steering Group, Huitema, C., Gross, P., "The Internet
        Standards Process -- Revision 2", March 1994.

   [RFC-1652]
        Klensin, J., (WG Chair), Freed, N., (Editor), Rose, M.,
        Stefferud, E., and Crocker, D., "SMTP Service Extension
        for 8bit-MIME transport", RFC 1652, United Nations
        University, Innosoft, Dover Beach Consulting, Inc.,
        Network Management Associates, Inc., The Branch Office,
        March 1994.

   [RFC-1700]
        Reynolds, J. and J. Postel, "Assigned Numbers", STD 2,
        RFC 1700, USC/Information Sciences Institute, October
        1994.

   [RFC-1741]
        Faltstrom, P., Crocker, D., and Fair, E., "MIME Content
        Type for BinHex Encoded Files", December 1994.

   [RFC-1896]
        Resnick, P., and A. Walker, "The text/enriched MIME
        Content-type", RFC 1896, February, 1996.








Freed & Borenstein          Standards Track                    [Page 23]

RFC 2049                    MIME Conformance               November 1996


   [RFC-2045]
        Freed, N., and and N. Borenstein, "Multipurpose Internet Mail
        Extensions (MIME) Part One: Format of Internet Message
        Bodies", RFC 2045, Innosoft, First Virtual Holdings,
        November 1996.

   [RFC-2046]
        Freed, N., and N. Borenstein, "Multipurpose Internet Mail
        Extensions (MIME) Part Two: Media Types", RFC 2046,
        Innosoft, First Virtual Holdings, November 1996.

   [RFC-2047]
        Moore, K., "Multipurpose Internet Mail Extensions (MIME)
        Part Three: Representation of Non-ASCII Text in Internet
        Message Headers", RFC 2047, University of
        Tennessee, November 1996.

   [RFC-2048]
        Freed, N., Klensin, J., and J. Postel, "Multipurpose
        Internet Mail Extensions (MIME) Part Four: MIME
        Registration Procedures", RFC 2048, Innosoft, MCI,
        ISI, November 1996.

   [RFC-2049]
        Freed, N. and N. Borenstein, "Multipurpose Internet Mail
        Extensions (MIME) Part Five: Conformance Criteria and
        Examples", RFC 2049 (this document), Innosoft, First
        Virtual Holdings, November 1996.

   [US-ASCII]
        Coded Character Set -- 7-Bit American Standard Code for
        Information Interchange, ANSI X3.4-1986.

   [X400]
        Schicker, Pietro, "Message Handling Systems, X.400",
        Message Handling Systems and Distributed Applications, E.
        Stefferud, O-j. Jacobsen, and P. Schicker, eds., North-
        Holland, 1989, pp. 3-41.













Freed & Borenstein          Standards Track                    [Page 24]



================================================
FILE: doc/notes/rfc/rfc2183.txt
================================================






Network Working Group                                          R. Troost
Request for Comments: 2183                           New Century Systems
Updates: 1806                                                  S. Dorner
Category: Standards Track                          QUALCOMM Incorporated
                                                        K. Moore, Editor
                                                 University of Tennessee
                                                             August 1997


               Communicating Presentation Information in
                           Internet Messages:
                  The Content-Disposition Header Field

Status of this Memo

   This document specifies an Internet standards track protocol for the
   Internet community, and requests discussion and suggestions for
   improvements.  Please refer to the current edition of the "Internet
   Official Protocol Standards" (STD 1) for the standardization state
   and status of this protocol.  Distribution of this memo is unlimited.

Abstract

   This memo provides a mechanism whereby messages conforming to the
   MIME specifications [RFC 2045, RFC 2046, RFC 2047, RFC 2048, RFC
   2049] can convey presentational information.  It specifies the
   "Content-Disposition" header field, which is optional and valid for
   any MIME entity ("message" or "body part").  Two values for this
   header field are described in this memo; one for the ordinary linear
   presentation of the body part, and another to facilitate the use of
   mail to transfer files.  It is expected that more values will be
   defined in the future, and procedures are defined for extending this
    set of values.

   This document is intended as an extension to MIME.  As such, the
   reader is assumed to be familiar with the MIME specifications, and
   [RFC 822].  The information presented herein supplements but does not
   replace that found in those documents.

   This document is a revision to the Experimental protocol defined in
   RFC 1806.  As compared to RFC 1806, this document contains minor
   editorial updates, adds new parameters needed to support the File
   Transfer Body Part, and references a separate specification for the
   handling of non-ASCII and/or very long parameter values.







Troost, et. al.             Standards Track                     [Page 1]

RFC 2183                  Content-Disposition                August 1997


1.  Introduction

   MIME specifies a standard format for encapsulating multiple pieces of
   data into a single Internet message. That document does not address
   the issue of presentation styles; it provides a framework for the
   interchange of message content, but leaves presentation issues solely
   in the hands of mail user agent (MUA) implementors.

   Two common ways of presenting multipart electronic messages are as a
   main document with a list of separate attachments, and as a single
   document with the various parts expanded (displayed) inline. The
   display of an attachment is generally construed to require positive
   action on the part of the recipient, while inline message components
   are displayed automatically when the message is viewed. A mechanism
   is needed to allow the sender to transmit this sort of presentational
   information to the recipient; the Content-Disposition header provides
   this mechanism, allowing each component of a message to be tagged
   with an indication of its desired presentation semantics.

   Tagging messages in this manner will often be sufficient for basic
   message formatting. However, in many cases a more powerful and
   flexible approach will be necessary. The definition of such
   approaches is beyond the scope of this memo; however, such approaches
   can benefit from additional Content-Disposition values and
   parameters, to be defined at a later date.

   In addition to allowing the sender to specify the presentational
   disposition of a message component, it is desirable to allow her to
   indicate a default archival disposition; a filename. The optional
   "filename" parameter provides for this.  Further, the creation-date,
   modification-date, and read-date parameters allow preservation of
   those file attributes when the file is transmitted over MIME email.

   NB: The keywords MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD,
   SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL, when they appear in this
   document, are to be interpreted as described in [RFC 2119].

2.  The Content-Disposition Header Field

   Content-Disposition is an optional header field. In its absence, the
   MUA may use whatever presentation method it deems suitable.

   It is desirable to keep the set of possible disposition types small
   and well defined, to avoid needless complexity. Even so, evolving
   usage will likely require the definition of additional disposition
   types or parameters, so the set of disposition values is extensible;
   see below.




Troost, et. al.             Standards Track                     [Page 2]

RFC 2183                  Content-Disposition                August 1997


   In the extended BNF notation of [RFC 822], the Content-Disposition
   header field is defined as follows:

     disposition := "Content-Disposition" ":"
                    disposition-type
                    *(";" disposition-parm)

     disposition-type := "inline"
                       / "attachment"
                       / extension-token
                       ; values are not case-sensitive

     disposition-parm := filename-parm
                       / creation-date-parm
                       / modification-date-parm
                       / read-date-parm
                       / size-parm
                       / parameter

     filename-parm := "filename" "=" value

     creation-date-parm := "creation-date" "=" quoted-date-time

     modification-date-parm := "modification-date" "=" quoted-date-time

     read-date-parm := "read-date" "=" quoted-date-time

     size-parm := "size" "=" 1*DIGIT

     quoted-date-time := quoted-string
                      ; contents MUST be an RFC 822 `date-time'
                      ; numeric timezones (+HHMM or -HHMM) MUST be used



   NOTE ON PARAMETER VALUE LENGHTS: A short (length <= 78 characters)
   parameter value containing only non-`tspecials' characters SHOULD be
   represented as a single `token'.  A short parameter value containing
   only ASCII characters, but including `tspecials' characters, SHOULD
   be represented as `quoted-string'.  Parameter values longer than 78
   characters, or which contain non-ASCII characters, MUST be encoded as
   specified in [RFC 2184].

   `Extension-token', `parameter', `tspecials' and `value' are defined
   according to [RFC 2045] (which references [RFC 822] in the definition
   of some of these tokens).  `quoted-string' and `DIGIT' are defined in
   [RFC 822].




Troost, et. al.             Standards Track                     [Page 3]

RFC 2183                  Content-Disposition                August 1997


2.1  The Inline Disposition Type

   A bodypart should be marked `inline' if it is intended to be
   displayed automatically upon display of the message.  Inline
   bodyparts should be presented in the order in which they occur,
   subject to the normal semantics of multipart messages.

2.2  The Attachment Disposition Type

   Bodyparts can be designated `attachment' to indicate that they are
   separate from the main body of the mail message, and that their
   display should not be automatic, but contingent upon some further
   action of the user.  The MUA might instead present the user of a
   bitmap terminal with an iconic representation of the attachments, or,
   on character terminals, with a list of attachments from which the
   user could select for viewing or storage.

2.3  The Filename Parameter

   The sender may want to suggest a filename to be used if the entity is
   detached and stored in a separate file. If the receiving MUA writes
   the entity to a file, the suggested filename should be used as a
   basis for the actual filename, where possible.

   It is important that the receiving MUA not blindly use the suggested
   filename.  The suggested filename SHOULD be checked (and possibly
   changed) to see that it conforms to local filesystem conventions,
   does not overwrite an existing file, and does not present a security
   problem (see Security Considerations below).

   The receiving MUA SHOULD NOT respect any directory path information
   that may seem to be present in the filename parameter.  The filename
   should be treated as a terminal component only.  Portable
   specification of directory paths might possibly be done in the future
   via a separate Content-Disposition parameter, but no provision is
   made for it in this draft.

   Current [RFC 2045] grammar restricts parameter values (and hence
   Content-Disposition filenames) to US-ASCII.  We recognize the great
   desirability of allowing arbitrary character sets in filenames, but
   it is beyond the scope of this document to define the necessary
   mechanisms.  We expect that the basic [RFC 1521] `value'
   specification will someday be amended to allow use of non-US-ASCII
   characters, at which time the same mechanism should be used in the
   Content-Disposition filename parameter.






Troost, et. al.             Standards Track                     [Page 4]

RFC 2183                  Content-Disposition                August 1997


   Beyond the limitation to US-ASCII, the sending MUA may wish to bear
   in mind the limitations of common filesystems.  Many have severe
   length and character set restrictions.  Short alphanumeric filenames
   are least likely to require modification by the receiving system.

   The presence of the filename parameter does not force an
   implementation to write the entity to a separate file. It is
   perfectly acceptable for implementations to leave the entity as part
   of the normal mail stream unless the user requests otherwise. As a
   consequence, the parameter may be used on any MIME entity, even
   `inline' ones. These will not normally be written to files, but the
   parameter could be used to provide a filename if the receiving user
   should choose to write the part to a file.

2.4 The Creation-Date parameter

   The creation-date parameter MAY be used to indicate the date at which
   the file was created.  If this parameter is included, the paramter
   value MUST be a quoted-string which contains a representation of the
   creation date of the file in [RFC 822] `date-time' format.

   UNIX and POSIX implementors are cautioned that the `st_ctime' file
   attribute of the `stat' structure is not the creation time of the
   file; it is thus not appropriate as a source for the creation-date
   parameter value.

2.5 The Modification-Date parameter

   The modification-date parameter MAY be used to indicate the date at
   which the file was last modified.  If the modification-date parameter
   is included, the paramter value MUST be a quoted-string which
   contains a representation of the last modification date of the file
   in [RFC 822] `date-time' format.

2.6 The Read-Date parameter

   The read-date parameter MAY be used to indicate the date at which the
   file was last read.  If the read-date parameter is included, the
   parameter value MUST be a quoted-string which contains a
   representation of the last-read date of the file in [RFC 822] `date-
   time' format.

2.7 The Size parameter

   The size parameter indicates an approximate size of the file in
   octets.  It can be used, for example, to pre-allocate space before
   attempting to store the file, or to determine whether enough space
   exists.



Troost, et. al.             Standards Track                     [Page 5]

RFC 2183                  Content-Disposition                August 1997


2.8  Future Extensions and Unrecognized Disposition Types

   In the likely event that new parameters or disposition types are
   needed, they should be registered with the Internet Assigned Numbers
   Authority (IANA), in the manner specified in Section 9 of this memo.

   Once new disposition types and parameters are defined, there is of
   course the likelihood that implementations will see disposition types
   and parameters they do not understand.  Furthermore, since x-tokens
   are allowed, implementations may also see entirely unregistered
   disposition types and parameters.

   Unrecognized parameters should be ignored. Unrecognized disposition
   types should be treated as `attachment'. The choice of `attachment'
   for unrecognized types is made because a sender who goes to the
   trouble of producing a Content-Disposition header with a new
   disposition type is more likely aiming for something more elaborate
   than inline presentation.

   Unless noted otherwise in the definition of a parameter, Content-
   Disposition parameters are valid for all dispositions.  (In contrast
   to MIME content-type parameters, which are defined on a per-content-
   type basis.) Thus, for example, the `filename' parameter still means
   the name of the file to which the part should be written, even if the
   disposition itself is unrecognized.

2.9  Content-Disposition and Multipart

   If a Content-Disposition header is used on a multipart body part, it
   applies to the multipart as a whole, not the individual subparts.
   The disposition types of the subparts do not need to be consulted
   until the multipart itself is presented.  When the multipart is
   displayed, then the dispositions of the subparts should be respected.

   If the `inline' disposition is used, the multipart should be
   displayed as normal; however, an `attachment' subpart should require
   action from the user to display.

   If the `attachment' disposition is used, presentation of the
   multipart should not proceed without explicit user action.  Once the
   user has chosen to display the multipart, the individual subpart
   dispositions should be consulted to determine how to present the
   subparts.








Troost, et. al.             Standards Track                     [Page 6]

RFC 2183                  Content-Disposition                August 1997


2.10  Content-Disposition and the Main Message

   It is permissible to use Content-Disposition on the main body of an
   [RFC 822] message.

3.  Examples

   Here is a an example of a body part containing a JPEG image that is
   intended to be viewed by the user immediately:

        Content-Type: image/jpeg
        Content-Disposition: inline
        Content-Description: just a small picture of me

         <jpeg data>

   The following body part contains a JPEG image that should be
   displayed to the user only if the user requests it. If the JPEG is
   written to a file, the file should be named "genome.jpg".  The
   recipient's user might also choose to set the last-modified date of
   the stored file to date in the modification-date parameter:

        Content-Type: image/jpeg
        Content-Disposition: attachment; filename=genome.jpeg;
          modification-date="Wed, 12 Feb 1997 16:29:51 -0500";
        Content-Description: a complete map of the human genome

        <jpeg data>

   The following is an example of the use of the `attachment'
   disposition with a multipart body part.  The user should see text-
   part-1 immediately, then take some action to view multipart-2.  After
   taking action to view multipart-2, the user will see text-part-2
   right away, and be required to take action to view jpeg-1.  Subparts
   are indented for clarity; they would not be so indented in a real
   message.















Troost, et. al.             Standards Track                     [Page 7]

RFC 2183                  Content-Disposition                August 1997


        Content-Type: multipart/mixed; boundary=outer
        Content-Description: multipart-1

        --outer
          Content-Type: text/plain
          Content-Disposition: inline
          Content-Description: text-part-1

          Some text goes here

        --outer
          Content-Type: multipart/mixed; boundary=inner
          Content-Disposition: attachment
          Content-Description: multipart-2

          --inner
            Content-Type: text/plain
            Content-Disposition: inline
            Content-Description: text-part-2

            Some more text here.

          --inner
            Content-Type: image/jpeg
            Content-Disposition: attachment
            Content-Description: jpeg-1

            <jpeg data>
          --inner--
        --outer--

4.  Summary

   Content-Disposition takes one of two values, `inline' and
   `attachment'.  `Inline' indicates that the entity should be
   immediately displayed to the user, whereas `attachment' means that
   the user should take additional action to view the entity.

   The `filename' parameter can be used to suggest a filename for
   storing the bodypart, if the user wishes to store it in an external
   file.










Troost, et. al.             Standards Track                     [Page 8]

RFC 2183                  Content-Disposition                August 1997


5.  Security Considerations

   There are security issues involved any time users exchange data.
   While these are not to be minimized, neither does this memo change
   the status quo in that regard, except in one instance.

   Since this memo provides a way for the sender to suggest a filename,
   a receiving MUA must take care that the sender's suggested filename
   does not represent a hazard. Using UNIX as an example, some hazards
   would be:

   +    Creating startup files (e.g., ".login").

   +    Creating or overwriting system files (e.g., "/etc/passwd").

   +    Overwriting any existing file.

   +    Placing executable files into any command search path
        (e.g., "~/bin/more").

   +    Sending the file to a pipe (e.g., "| sh").

   In general, the receiving MUA should not name or place the file such
   that it will get interpreted or executed without the user explicitly
   initiating the action.

   It is very important to note that this is not an exhaustive list; it
   is intended as a small set of examples only.  Implementors must be
   alert to the potential hazards on their target systems.

6.  References

   [RFC 2119]
        Bradner, S., "Key words for use in RFCs to Indicate Requirement
        Levels", RFC 2119, March 1997.

   [RFC 2184]
        Freed, N. and K. Moore, "MIME Parameter value and Encoded Words:
        Character Sets, Lanaguage, and Continuations", RFC 2184, August
        1997.

   [RFC 2045]
        Freed, N. and N. Borenstein, "MIME (Multipurpose Internet Mail
        Extensions) Part One: Format of Internet Message Bodies", RFC
        2045, December 1996.






Troost, et. al.             Standards Track                     [Page 9]

RFC 2183                  Content-Disposition                August 1997


   [RFC 2046]
        Freed, N. and N. Borenstein, "MIME (Multipurpose Internet Mail
        Extensions) Part Two: Media Types", RFC 2046, December 1996.

   [RFC 2047]
        Moore, K., "MIME (Multipurpose Internet Mail Extensions) Part
        Three: Message Header Extensions for non-ASCII Text", RFC 2047,
        December 1996.

   [RFC 2048]
        Freed, N., Klensin, J. and J. Postel, "MIME (Multipurpose
        Internet Mail Extensions) Part Four: Registration Procedures",
        RFC 2048, December 1996.

   [RFC 2049]
        Freed, N. and N. Borenstein, "MIME (Multipurpose Internet Mail
        Extensions) Part Five: Conformance Criteria and Examples", RFC
        2049, December 1996.

   [RFC 822]
        Crocker, D., "Standard for the Format of ARPA Internet Text
        Messages", STD 11, RFC 822, UDEL, August 1982.

7.  Acknowledgements

   We gratefully acknowledge the help these people provided during the
   preparation of this draft:

        Nathaniel Borenstein
        Ned Freed
        Keith Moore
        Dave Crocker
        Dan Pritchett


















Troost, et. al.             Standards Track                    [Page 10]

RFC 2183                  Content-Disposition                August 1997


8.  Authors' Addresses

   You should blame the editor of this version of the document for any
   changes since RFC 1806:

        Keith Moore
        Department of Computer Science
        University of Tennessee, Knoxville
        107 Ayres Hall
        Knoxville TN  37996-1301
        USA

        Phone: +1 (423) 974-5067
        Fax: +1 (423) 974-8296
        Email: moore@cs.utk.edu


        The authors of RFC 1806 are:

        Rens Troost
        New Century Systems
        324 East 41st Street #804
        New York, NY, 10017 USA

        Phone: +1 (212) 557-2050
        Fax: +1 (212) 557-2049
        EMail: rens@century.com


        Steve Dorner
        QUALCOMM Incorporated
        6455 Lusk Boulevard
        San Diego, CA 92121
        USA

        EMail: sdorner@qualcomm.com


9. Registration of New Content-Disposition Values and Parameters

   New Content-Disposition values (besides "inline" and "attachment")
   may be defined only by Internet standards-track documents, or in
   Experimental documents approved by the Internet Engineering Steering
   Group.







Troost, et. al.             Standards Track                    [Page 11]

RFC 2183                  Content-Disposition                August 1997


   New content-disposition parameters may be registered by supplying the
   information in the following template and sending it via electronic
   mail to IANA@IANA.ORG:

     To: IANA@IANA.ORG
     Subject: Registration of new Content-Disposition parameter

     Content-Disposition parameter name:

     Allowable values for this parameter:
          (If the parameter can only assume a small number of values,
          list each of those values.  Otherwise, describe the values
          that the parameter can assume.)
     Description:
          (What is the purpose of this parameter and how is it used?)

10. Changes since RFC 1806

   The following changes have been made since the earlier version of
   this document, published in RFC 1806 as an Experimental protocol:

   +    Updated references to MIME documents.  In some cases this
        involved substituting a reference to one of the current MIME
        RFCs for a reference to RFC 1521; in other cases, a reference to
        RFC 1521 was simply replaced with the word "MIME".

   +    Added  a section on registration procedures, since none of the
        procedures in RFC 2048 seemed to be appropriate.

   +    Added new parameter types: creation-date, modification-date,
        read-date, and size.


   +    Incorporated a reference to draft-freed-pvcsc-* for encoding
        long or non-ASCII parameter values.

   +    Added reference to RFC 2119 to define MUST, SHOULD, etc.
        keywords.













Troost, et. al.             Standards Track                    [Page 12]



================================================
FILE: doc/notes/rfc/rfc2222.txt
================================================






Network Working Group                                           J. Myers
Request for Comments: 2222                       Netscape Communications
Category: Standards Track                                   October 1997


            Simple Authentication and Security Layer (SASL)

Status of this Memo

   This document specifies an Internet standards track protocol for the
   Internet community, and requests discussion and suggestions for
   improvements.  Please refer to the current edition of the "Internet
   Official Protocol Standards" (STD 1) for the standardization state
   and status of this protocol.  Distribution of this memo is unlimited.

Copyright Notice

   Copyright (C) The Internet Society (1997).  All Rights Reserved.

Table of Contents

   1.    Abstract ..............................................    2
   2.    Organization of this Document .........................    2
   2.1.  How to Read This Document .............................    2
   2.2.  Conventions Used in this Document .....................    2
   2.3.  Examples ..............................................    3
   3.    Introduction and Overview .............................    3
   4.    Profiling requirements ................................    4
   5.    Specific issues .......................................    5
   5.1.  Client sends data first ...............................    5
   5.2.  Server returns success with additional data ...........    5
   5.3.  Multiple authentications ..............................    5
   6.    Registration procedures ...............................    6
   6.1.  Comments on SASL mechanism registrations ..............    6
   6.2.  Location of Registered SASL Mechanism List ............    6
   6.3.  Change Control ........................................    7
   6.4.  Registration Template .................................    7
   7.    Mechanism definitions .................................    8
   7.1.  Kerberos version 4 mechanism ..........................    8
   7.2.  GSSAPI mechanism ......................................    9
   7.2.1 Client side of authentication protocol exchange .......    9
   7.2.2 Server side of authentication protocol exchange .......   10
   7.2.3 Security layer ........................................   11
   7.3.  S/Key mechanism .......................................   11
   7.4.  External mechanism ....................................   12
   8.    References ............................................   13
   9.    Security Considerations ...............................   13
   10.   Author's Address ......................................   14



Myers                       Standards Track                     [Page 1]

RFC 2222                          SASL                      October 1997


   Appendix A. Relation of SASL to Transport Security ..........   15
   Full Copyright Statement ....................................   16

1.    Abstract

   This document describes a method for adding authentication support to
   connection-based protocols.  To use this specification, a protocol
   includes a command for identifying and authenticating a user to a
   server and for optionally negotiating protection of subsequent
   protocol interactions.  If its use is negotiated, a security layer is
   inserted between the protocol and the connection.  This document
   describes how a protocol specifies such a command, defines several
   mechanisms for use by the command, and defines the protocol used for
   carrying a negotiated security layer over the connection.

2.    Organization of this Document

2.1.  How to Read This Document

   This document is written to serve two different audiences, protocol
   designers using this specification to support authentication in their
   protocol, and implementors of clients or servers for those protocols
   using this specification.

   The sections "Introduction and Overview", "Profiling requirements",
   and "Security Considerations" cover issues that protocol designers
   need to understand and address in profiling this specification for
   use in a specific protocol.

   Implementors of a protocol using this specification need the
   protocol-specific profiling information in addition to the
   information in this document.

2.2.  Conventions Used in this Document

   In examples, "C:" and "S:" indicate lines sent by the client and
   server respectively.

   The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY"
   in this document are to be interpreted as defined in "Key words for
   use in RFCs to Indicate Requirement Levels" [RFC 2119].










Myers                       Standards Track                     [Page 2]

RFC 2222                          SASL                      October 1997


2.3.  Examples

   Examples in this document are for the IMAP profile [RFC 2060] of this
   specification.  The base64 encoding of challenges and responses, as
   well as the "+ " preceding the responses are part of the IMAP4
   profile, not part of the SASL specification itself.

3.    Introduction and Overview

   The Simple Authentication and Security Layer (SASL) is a method for
   adding authentication support to connection-based protocols.  To use
   this specification, a protocol includes a command for identifying and
   authenticating a user to a server and for optionally negotiating a
   security layer for subsequent protocol interactions.

   The command has a required argument identifying a SASL mechanism.
   SASL mechanisms are named by strings, from 1 to 20 characters in
   length, consisting of upper-case letters, digits, hyphens, and/or
   underscores.  SASL mechanism names must be registered with the IANA.
   Procedures for registering new SASL mechanisms are given in the
   section "Registration procedures"

   If a server supports the requested mechanism, it initiates an
   authentication protocol exchange.  This consists of a series of
   server challenges and client responses that are specific to the
   requested mechanism.  The challenges and responses are defined by the
   mechanisms as binary tokens of arbitrary length.  The protocol's
   profile then specifies how these binary tokens are then encoded for
   transfer over the connection.

   After receiving the authentication command or any client response, a
   server may issue a challenge, indicate failure, or indicate
   completion.  The protocol's profile specifies how the server
   indicates which of the above it is doing.

   After receiving a challenge, a client may issue a response or abort
   the exchange.  The protocol's profile specifies how the client
   indicates which of the above it is doing.

   During the authentication protocol exchange, the mechanism performs
   authentication, transmits an authorization identity (frequently known
   as a userid) from the client to server, and negotiates the use of a
   mechanism-specific security layer.  If the use of a security layer is
   agreed upon, then the mechanism must also define or negotiate the
   maximum cipher-text buffer size that each side is able to receive.






Myers                       Standards Track                     [Page 3]

RFC 2222                          SASL                      October 1997


   The transmitted authorization identity may be different than the
   identity in the client's authentication credentials.  This permits
   agents such as proxy servers to authenticate using their own
   credentials, yet request the access privileges of the identity for
   which they are proxying.  With any mechanism, transmitting an
   authorization identity of the empty string directs the server to
   derive an authorization identity from the client's authentication
   credentials.

   If use of a security layer is negotiated, it is applied to all
   subsequent data sent over the connection.  The security layer takes
   effect immediately following the last response of the authentication
   exchange for data sent by the client and the completion indication
   for data sent by the server.  Once the security layer is in effect,
   the protocol stream is processed by the security layer into buffers
   of cipher-text.  Each buffer is transferred over the connection as a
   stream of octets prepended with a four octet field in network byte
   order that represents the length of the following buffer.  The length
   of the cipher-text buffer must be no larger than the maximum size
   that was defined or negotiated by the other side.

4.    Profiling requirements

   In order to use this specification, a protocol definition must supply
   the following information:

   1. A service name, to be selected from the IANA registry of "service"
      elements for the GSSAPI host-based service name form [RFC 2078].

   2. A definition of the command to initiate the authentication
      protocol exchange.  This command must have as a parameter the
      mechanism name being selected by the client.

      The command SHOULD have an optional parameter giving an initial
      response.  This optional parameter allows the client to avoid a
      round trip when using a mechanism which is defined to have the
      client send data first.  When this initial response is sent by the
      client and the selected mechanism is defined to have the server
      start with an initial challenge, the command fails.  See section
      5.1 of this document for further information.

   3. A definition of the method by which the authentication protocol
      exchange is carried out, including how the challenges and
      responses are encoded, how the server indicates completion or
      failure of the exchange, how the client aborts an exchange, and
      how the exchange method interacts with any line length limits in
      the protocol.




Myers                       Standards Track                     [Page 4]

RFC 2222                          SASL                      October 1997


   4. Identification of the octet where any negotiated security layer
      starts to take effect, in both directions.

   5. A specification of how the authorization identity passed from the
      client to the server is to be interpreted.

5.    Specific issues

5.1.  Client sends data first

   Some mechanisms specify that the first data sent in the
   authentication protocol exchange is from the client to the server.

   If a protocol's profile permits the command which initiates an
   authentication protocol exchange to contain an initial client
   response, this parameter SHOULD be used with such mechanisms.

   If the initial client response parameter is not given, or if a
   protocol's profile does not permit the command which initiates an
   authentication protocol exchange to contain an initial client
   response, then the server issues a challenge with no data.  The
   client's response to this challenge is then used as the initial
   client response.  (The server then proceeds to send the next
   challenge, indicates completion, or indicates failure.)

5.2.  Server returns success with additional data

   Some mechanisms may specify that server challenge data be sent to the
   client along with an indication of successful completion of the
   exchange.  This data would, for example, authenticate the server to
   the client.

   If a protocol's profile does not permit this server challenge to be
   returned with a success indication, then the server issues the server
   challenge without an indication of successful completion.  The client
   then responds with no data.  After receiving this empty response, the
   server then indicates successful completion.

5.3.  Multiple authentications

   Unless otherwise stated by the protocol's profile, only one
   successful SASL negotiation may occur in a protocol session.  In this
   case, once an authentication protocol exchange has successfully
   completed, further attempts to initiate an authentication protocol
   exchange fail.






Myers                       Standards Track                     [Page 5]

RFC 2222                          SASL                      October 1997


   In the case that a profile explicitly permits multiple successful
   SASL negotiations to occur, then in no case may multiple security
   layers be simultaneously in effect.  If a security layer is in effect
   and a subsequent SASL negotiation selects no security layer, the
   original security layer remains in effect.  If a security layer is in
   effect and a subsequent SASL negotiation selects a second security
   layer, then the second security layer replaces the first.

6.    Registration procedures

   Registration of a SASL mechanism is done by filling in the template
   in section 6.4 and sending it in to iana@isi.edu.  IANA has the right
   to reject obviously bogus registrations, but will perform no review
   of clams made in the registration form.

   There is no naming convention for SASL mechanisms; any name that
   conforms to the syntax of a SASL mechanism name can be registered.

   While the registration procedures do not require it, authors of SASL
   mechanisms are encouraged to seek community review and comment
   whenever that is feasible.  Authors may seek community review by
   posting a specification of their proposed mechanism as an internet-
   draft.  SASL mechanisms intended for widespread use should be
   standardized through the normal IETF process, when appropriate.

6.1.  Comments on SASL mechanism registrations

   Comments on registered SASL mechanisms should first be sent to the
   "owner" of the mechanism.  Submitters of comments may, after a
   reasonable attempt to contact the owner, request IANA to attach their
   comment to the SASL mechanism registration itself.  If IANA approves
   of this the comment will be made accessible in conjunction with the
   SASL mechanism registration itself.

6.2.  Location of Registered SASL Mechanism List

   SASL mechanism registrations will be posted in the anonymous FTP
   directory "ftp://ftp.isi.edu/in-notes/iana/assignments/sasl-
   mechanisms/" and all registered SASL mechanisms will be listed in the
   periodically issued "Assigned Numbers" RFC [currently STD 2, RFC
   1700].  The SASL mechanism description and other supporting material
   may also be published as an Informational RFC by sending it to "rfc-
   editor@isi.edu" (please follow the instructions to RFC authors [RFC
   2223]).







Myers                       Standards Track                     [Page 6]

RFC 2222                          SASL                      October 1997


6.3.  Change Control

   Once a SASL mechanism registration has been published by IANA, the
   author may request a change to its definition.  The change request
   follows the same procedure as the registration request.

   The owner of a SASL mechanism may pass responsibility for the SASL
   mechanism to another person or agency by informing IANA; this can be
   done without discussion or review.

   The IESG may reassign responsibility for a SASL mechanism. The most
   common case of this will be to enable changes to be made to
   mechanisms where the author of the registration has died, moved out
   of contact or is otherwise unable to make changes that are important
   to the community.

   SASL mechanism registrations may not be deleted; mechanisms which are
   no longer believed appropriate for use can be declared OBSOLETE by a
   change to their "intended use" field; such SASL mechanisms will be
   clearly marked in the lists published by IANA.

   The IESG is considered to be the owner of all SASL mechanisms which
   are on the IETF standards track.

6.4.  Registration Template

   To: iana@iana.org
   Subject: Registration of SASL mechanism X

   SASL mechanism name:

   Security considerations:

   Published specification (optional, recommended):

   Person & email address to contact for further information:

   Intended usage:

   (One of COMMON, LIMITED USE or OBSOLETE)

   Author/Change controller:

   (Any other information that the author deems interesting may be
   added below this line.)






Myers                       Standards Track                     [Page 7]

RFC 2222                          SASL                      October 1997


7.    Mechanism definitions

   The following mechanisms are hereby defined.

7.1.  Kerberos version 4 mechanism

   The mechanism name associated with Kerberos version 4 is
   "KERBEROS_V4".

   The first challenge consists of a random 32-bit number in network
   byte order.  The client responds with a Kerberos ticket and an
   authenticator for the principal "service.hostname@realm", where
   "service" is the service name specified in the protocol's profile,
   "hostname" is the first component of the host name of the server with
   all letters in lower case, and where "realm" is the Kerberos realm of
   the server.  The encrypted checksum field included within the
   Kerberos authenticator contains the server provided challenge in
   network byte order.

   Upon decrypting and verifying the ticket and authenticator, the
   server verifies that the contained checksum field equals the original
   server provided random 32-bit number.  Should the verification be
   successful, the server must add one to the checksum and construct 8
   octets of data, with the first four octets containing the incremented
   checksum in network byte order, the fifth octet containing a bit-mask
   specifying the security layers supported by the server, and the sixth
   through eighth octets containing, in network byte order, the maximum
   cipher-text buffer size the server is able to receive.  The server
   must encrypt using DES ECB mode the 8 octets of data in the session
   key and issue that encrypted data in a second challenge.  The client
   considers the server authenticated if the first four octets of the
   un-encrypted data is equal to one plus the checksum it previously
   sent.

   The client must construct data with the first four octets containing
   the original server-issued checksum in network byte order, the fifth
   octet containing the bit-mask specifying the selected security layer,
   the sixth through eighth octets containing in network byte order the
   maximum cipher-text buffer size the client is able to receive, and
   the following octets containing the authorization identity.  The
   client must then append from one to eight zero-valued octets so that
   the length of the data is a multiple of eight octets. The client must
   then encrypt using DES PCBC mode the data with the session key and
   respond with the encrypted data.  The server decrypts the data and
   verifies the contained checksum.  The server must verify that the
   principal identified in the Kerberos ticket is authorized to connect
   as that authorization identity.  After this verification, the
   authentication process is complete.



Myers                       Standards Track                     [Page 8]

RFC 2222                          SASL                      October 1997


   The security layers and their corresponding bit-masks are as follows:

      1 No security layer
      2 Integrity (krb_mk_safe) protection
      4 Privacy (krb_mk_priv) protection

   Other bit-masks may be defined in the future; bits which are not
   understood must be negotiated off.

   EXAMPLE: The following are two Kerberos version 4 login scenarios to
   the IMAP4 protocol (note that the line breaks in the sample
   authenticators are for editorial clarity and are not in real
   authenticators)

     S: * OK IMAP4 Server
     C: A001 AUTHENTICATE KERBEROS_V4
     S: + AmFYig==
     C: BAcAQU5EUkVXLkNNVS5FRFUAOCAsho84kLN3/IJmrMG+25a4DT
        +nZImJjnTNHJUtxAA+o0KPKfHEcAFs9a3CL5Oebe/ydHJUwYFd
        WwuQ1MWiy6IesKvjL5rL9WjXUb9MwT9bpObYLGOKi1Qh
     S: + or//EoAADZI=
     C: DiAF5A4gA+oOIALuBkAAmw==
     S: A001 OK Kerberos V4 authentication successful


     S: * OK IMAP4 Server
     C: A001 AUTHENTICATE KERBEROS_V4
     S: + gcfgCA==
     C: BAcAQU5EUkVXLkNNVS5FRFUAOCAsho84kLN3/IJmrMG+25a4DT
        +nZImJjnTNHJUtxAA+o0KPKfHEcAFs9a3CL5Oebe/ydHJUwYFd
        WwuQ1MWiy6IesKvjL5rL9WjXUb9MwT9bpObYLGOKi1Qh
     S: A001 NO Kerberos V4 authentication failed

7.2.  GSSAPI mechanism

   The mechanism name associated with all mechanisms employing the
   GSSAPI [RFC 2078] is "GSSAPI".

7.2.1 Client side of authentication protocol exchange

   The client calls GSS_Init_sec_context, passing in 0 for
   input_context_handle (initially) and a targ_name equal to output_name
   from GSS_Import_Name called with input_name_type of
   GSS_C_NT_HOSTBASED_SERVICE and input_name_string of
   "service@hostname" where "service" is the service name specified in
   the protocol's profile, and "hostname" is the fully qualified host
   name of the server.  The client then responds with the resulting
   output_token.  If GSS_Init_sec_context returns GSS_S_CONTINUE_NEEDED,



Myers                       Standards Track                     [Page 9]

RFC 2222                          SASL                      October 1997


   then the client should expect the server to issue a token in a
   subsequent challenge.  The client must pass the token to another call
   to GSS_Init_sec_context, repeating the actions in this paragraph.

   When GSS_Init_sec_context returns GSS_S_COMPLETE, the client takes
   the following actions: If the last call to GSS_Init_sec_context
   returned an output_token, then the client responds with the
   output_token, otherwise the client responds with no data.  The client
   should then expect the server to issue a token in a subsequent
   challenge.  The client passes this token to GSS_Unwrap and interprets
   the first octet of resulting cleartext as a bit-mask specifying the
   security layers supported by the server and the second through fourth
   octets as the maximum size output_message to send to the server.  The
   client then constructs data, with the first octet containing the
   bit-mask specifying the selected security layer, the second through
   fourth octets containing in network byte order the maximum size
   output_message the client is able to receive, and the remaining
   octets containing the authorization identity.  The client passes the
   data to GSS_Wrap with conf_flag set to FALSE, and responds with the
   generated output_message.  The client can then consider the server
   authenticated.

7.2.2 Server side of authentication protocol exchange

   The server passes the initial client response to
   GSS_Accept_sec_context as input_token, setting input_context_handle
   to 0 (initially).  If GSS_Accept_sec_context returns
   GSS_S_CONTINUE_NEEDED, the server returns the generated output_token
   to the client in challenge and passes the resulting response to
   another call to GSS_Accept_sec_context, repeating the actions in this
   paragraph.

   When GSS_Accept_sec_context returns GSS_S_COMPLETE, the client takes
   the following actions: If the last call to GSS_Accept_sec_context
   returned an output_token, the server returns it to the client in a
   challenge and expects a reply from the client with no data.  Whether
   or not an output_token was returned (and after receipt of any
   response from the client to such an output_token), the server then
   constructs 4 octets of data, with the first octet containing a bit-
   mask specifying the security layers supported by the server and the
   second through fourth octets containing in network byte order the
   maximum size output_token the server is able to receive.  The server
   must then pass the plaintext to GSS_Wrap with conf_flag set to FALSE
   and issue the generated output_message to the client in a challenge.
   The server must then pass the resulting response to GSS_Unwrap and
   interpret the first octet of resulting cleartext as the bit-mask for
   the selected security layer, the second through fourth octets as the
   maximum size output_message to send to the client, and the remaining



Myers                       Standards Track                    [Page 10]

RFC 2222                          SASL                      October 1997


   octets as the authorization identity.  The server must verify that
   the src_name is authorized to authenticate as the authorization
   identity.  After these verifications, the authentication process is
   complete.

7.2.3 Security layer

   The security layers and their corresponding bit-masks are as follows:

     1 No security layer
     2 Integrity protection.
       Sender calls GSS_Wrap with conf_flag set to FALSE
     4 Privacy protection.
       Sender calls GSS_Wrap with conf_flag set to TRUE

   Other bit-masks may be defined in the future; bits which are not
   understood must be negotiated off.

7.3.  S/Key mechanism

   The mechanism name associated with S/Key [RFC 1760] using the MD4
   digest algorithm is "SKEY".

   The client sends an initial response with the authorization identity.

   The server then issues a challenge which contains the decimal
   sequence number followed by a single space and the seed string for
   the indicated authorization identity.  The client responds with the
   one-time-password, as either a 64-bit value in network byte order or
   encoded in the "six English words" format.

   The server must verify the one-time-password.  After this
   verification, the authentication process is complete.

   S/Key authentication does not provide for any security layers.

   EXAMPLE: The following are two S/Key login scenarios in the IMAP4
   protocol.

     S: * OK IMAP4 Server
     C: A001 AUTHENTICATE SKEY
     S: +
     C: bW9yZ2Fu
     S: + OTUgUWE1ODMwOA==
     C: Rk9VUiBNQU5OIFNPT04gRklSIFZBUlkgTUFTSA==
     S: A001 OK S/Key authentication successful





Myers                       Standards Track                    [Page 11]

RFC 2222                          SASL                      October 1997


     S: * OK IMAP4 Server
     C: A001 AUTHENTICATE SKEY
     S: +
     C: c21pdGg=
     S: + OTUgUWE1ODMwOA==
     C: BsAY3g4gBNo=
     S: A001 NO S/Key authentication failed

   The following is an S/Key login scenario in an IMAP4-like protocol
   which has an optional "initial response" argument to the AUTHENTICATE
   command.

     S: * OK IMAP4-Like Server
     C: A001 AUTHENTICATE SKEY bW9yZ2Fu
     S: + OTUgUWE1ODMwOA==
     C: Rk9VUiBNQU5OIFNPT04gRklSIFZBUlkgTUFTSA==
     S: A001 OK S/Key authentication successful

7.4.  External mechanism

   The mechanism name associated with external authentication is
   "EXTERNAL".

   The client sends an initial response with the authorization identity.

   The server uses information, external to SASL, to determine whether
   the client is authorized to authenticate as the authorization
   identity.  If the client is so authorized, the server indicates
   successful completion of the authentication exchange; otherwise the
   server indicates failure.

   The system providing this external information may be, for example,
   IPsec or TLS.

   If the client sends the empty string as the authorization identity
   (thus requesting the authorization identity be derived from the
   client's authentication credentials), the authorization identity is
   to be derived from authentication credentials which exist in the
   system which is providing the external authentication.












Myers                       Standards Track                    [Page 12]

RFC 2222                          SASL                      October 1997


8.    References

   [RFC 2060] Crispin, M., "Internet Message Access Protocol - Version
              4rev1", RFC 2060, December 1996.

   [RFC 2078] Linn, J., "Generic Security Service Application Program
              Interface, Version 2", RFC 2078, January 1997.

   [RFC 2119] Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", RFC 2119, March 1997.

   [RFC 2223] Postel, J., and J. Reynolds, "Instructions to RFC
              Authors", RFC 2223, October 1997.

   [RFC 1760] Haller, N., "The S/Key One-Time Password System", RFC
              1760, February 1995.

   [RFC 1700] Reynolds, J., and J. Postel, "Assigned Numbers", STD 2,
              RFC 1700, October 1994.

9.    Security Considerations

   Security issues are discussed throughout this memo.

   The mechanisms that support integrity protection are designed such
   that the negotiation of the security layer and authorization identity
   is integrity protected.  When the client selects a security layer
   with at least integrity protection, this protects against an active
   attacker hijacking the connection and modifying the authentication
   exchange to negotiate a plaintext connection.

   When a server or client supports multiple authentication mechanisms,
   each of which has a different security strength, it is possible for
   an active attacker to cause a party to use the least secure mechanism
   supported.  To protect against this sort of attack, a client or
   server which supports mechanisms of different strengths should have a
   configurable minimum strength that it will use.  It is not sufficient
   for this minimum strength check to only be on the server, since an
   active attacker can change which mechanisms the client sees as being
   supported, causing the client to send authentication credentials for
   its weakest supported mechanism.










Myers                       Standards Track                    [Page 13]

RFC 2222                          SASL                      October 1997


   The client's selection of a SASL mechanism is done in the clear and
   may be modified by an active attacker.  It is important for any new
   SASL mechanisms to be designed such that an active attacker cannot
   obtain an authentication with weaker security properties by modifying
   the SASL mechanism name and/or the challenges and responses.

   Any protocol interactions prior to authentication are performed in
   the clear and may be modified by an active attacker.  In the case
   where a client selects integrity protection, it is important that any
   security-sensitive protocol negotiations be performed after
   authentication is complete.  Protocols should be designed such that
   negotiations performed prior to authentication should be either
   ignored or revalidated once authentication is complete.

10.   Author's Address

   John G. Myers
   Netscape Communications
   501 E. Middlefield Road
   Mail Stop MV-029
   Mountain View, CA 94043-4042

   EMail: jgmyers@netscape.com




























Myers                       Standards Track                    [Page 14]

RFC 2222                          SASL                      October 1997


Appendix A. Relation of SASL to Transport Security

   Questions have been raised about the relationship between SASL and
   various services (such as IPsec and TLS) which provide a secured
   connection.

   Two of the key features of SASL are:

   1. The separation of the authorization identity from the identity in
      the client's credentials.  This permits agents such as proxy
      servers to authenticate using their own credentials, yet request
      the access privileges of the identity for which they are proxying.

   2. Upon successful completion of an authentication exchange, the
      server knows the authorization identity the client wishes to use.
      This allows servers to move to a "user is authenticated" state in
      the protocol.

   These features are extremely important to some application protocols,
   yet Transport Security services do not always provide them.  To
   define SASL mechanisms based on these services would be a very messy
   task, as the framing of these services would be redundant with the
   framing of SASL and some method of providing these important SASL
   features would have to be devised.

   Sometimes it is desired to enable within an existing connection the
   use of a security service which does not fit the SASL model.  (TLS is
   an example of such a service.)  This can be done by adding a command,
   for example "STARTTLS", to the protocol.  Such a command is outside
   the scope of SASL, and should be different from the command which
   starts a SASL authentication protocol exchange.

   In certain situations, it is reasonable to use SASL underneath one of
   these Transport Security services.  The transport service would
   secure the connection, either service would authenticate the client,
   and SASL would negotiate the authorization identity.  The SASL
   negotiation would be what moves the protocol from "unauthenticated"
   to "authenticated" state.  The "EXTERNAL" SASL mechanism is
   explicitly intended to handle the case where the transport service
   secures the connection and authenticates the client and SASL
   negotiates the authorization identity.

   When using SASL underneath a sufficiently strong Transport Security
   service, a SASL security layer would most likely be redundant.  The
   client and server would thus probably want to negotiate off the use
   of a SASL security layer.





Myers                       Standards Track                    [Page 15]

RFC 2222                          SASL                      October 1997


Full Copyright Statement

   Copyright (C) The Internet Society (1997).  All Rights Reserved.

   This document and translations of it may be copied and furnished to
   others, and derivative works that comment on or otherwise explain it
   or assist in its implmentation may be prepared, copied, published
   andand distributed, in whole or in part, without restriction of any
   kind, provided that the above copyright notice and this paragraph are
   included on all such copies and derivative works.  However, this
   document itself may not be modified in any way, such as by removing
   the copyright notice or references to the Internet Society or other
   Internet organizations, except as needed for the purpose of
   developing Internet standards in which case the procedures for
   copyrights defined in the Internet Standards process must be
   followed, or as required to translate it into languages other than
   English.

   The limited permissions granted above are perpetual and will not be
   revoked by the Internet Society or its successors or assigns.

   This document and the information contained herein is provided on an
   "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
   TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
   BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
   HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
   MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
























Myers                       Standards Track                    [Page 16]



================================================
FILE: doc/notes/rfc/rfc2231.txt
================================================






Network Working Group                                         N. Freed
Request for Comments: 2231                                    Innosoft
Updates: 2045, 2047, 2183                                     K. Moore
Obsoletes: 2184                                University of Tennessee
Category: Standards Track                                November 1997


           MIME Parameter Value and Encoded Word Extensions:
              Character Sets, Languages, and Continuations


Status of this Memo

   This document specifies an Internet standards track protocol for the
   Internet community, and requests discussion and suggestions for
   improvements.  Please refer to the current edition of the "Internet
   Official Protocol Standards" (STD 1) for the standardization state
   and status of this protocol.  Distribution of this memo is unlimited.

Copyright Notice

   Copyright (C) The Internet Society (1997).  All Rights Reserved.

1.  Abstract

   This memo defines extensions to the RFC 2045 media type and RFC 2183
   disposition parameter value mechanisms to provide

    (1)   a means to specify parameter values in character sets
          other than US-ASCII,

    (2)   to specify the language to be used should the value be
          displayed, and

    (3)   a continuation mechanism for long parameter values to
          avoid problems with header line wrapping.

   This memo also defines an extension to the encoded words defined in
   RFC 2047 to allow the specification of the language to be used for
   display as well as the character set.

2.  Introduction

   The Multipurpose Internet Mail Extensions, or MIME [RFC-2045, RFC-
   2046, RFC-2047, RFC-2048, RFC-2049], define a message format that
   allows for:





Freed & Moore               Standards Track                     [Page 1]

RFC 2231         MIME Value and Encoded Word Extensions    November 1997


    (1)   textual message bodies in character sets other than
          US-ASCII,

    (2)   non-textual message bodies,

    (3)   multi-part message bodies, and

    (4)   textual header information in character sets other than
          US-ASCII.

   MIME is now widely deployed and is used by a variety of Internet
   protocols, including, of course, Internet email.  However, MIME's
   success has resulted in the need for additional mechanisms that were
   not provided in the original protocol specification.

   In particular, existing MIME mechanisms provide for named media type
   (content-type field) parameters as well as named disposition
   (content-disposition field).  A MIME media type may specify any
   number of parameters associated with all of its subtypes, and any
   specific subtype may specify additional parameters for its own use. A
   MIME disposition value may specify any number of associated
   parameters, the most important of which is probably the attachment
   disposition's filename parameter.

   These parameter names and values end up appearing in the content-type
   and content-disposition header fields in Internet email.  This
   inherently imposes three crucial limitations:

    (1)   Lines in Internet email header fields are folded
          according to RFC 822 folding rules.  This makes long
          parameter values problematic.

    (2)   MIME headers, like the RFC 822 headers they often
          appear in, are limited to 7bit US-ASCII, and the
          encoded-word mechanisms of RFC 2047 are not available
          to parameter values.  This makes it impossible to have
          parameter values in character sets other than US-ASCII
          without specifying some sort of private per-parameter
          encoding.

    (3)   It has recently become clear that character set
          information is not sufficient to properly display some
          sorts of information -- language information is also
          needed [RFC-2130].  For example, support for
          handicapped users may require reading text string






Freed & Moore               Standards Track                     [Page 2]

RFC 2231         MIME Value and Encoded Word Extensions    November 1997


          aloud. The language the text is written in is needed
          for this to be done correctly.  Some parameter values
          may need to be displayed, hence there is a need to
          allow for the inclusion of language information.

   The last problem on this list is also an issue for the encoded words
   defined by RFC 2047, as encoded words are intended primarily for
   display purposes.

   This document defines extensions that address all of these
   limitations. All of these extensions are implemented in a fashion
   that is completely compatible at a syntactic level with existing MIME
   implementations. In addition, the extensions are designed to have as
   little impact as possible on existing uses of MIME.

   IMPORTANT NOTE:  These mechanisms end up being somewhat gibbous when
   they actually are used. As such, these mechanisms should not be used
   lightly; they should be reserved for situations where a real need for
   them exists.

2.1.  Requirements notation

   This document occasionally uses terms that appear in capital letters.
   When the terms "MUST", "SHOULD", "MUST NOT", "SHOULD NOT", and "MAY"
   appear capitalized, they are being used to indicate particular
   requirements of this specification. A discussion of the meanings of
   these terms appears in [RFC- 2119].

3.  Parameter Value Continuations

   Long MIME media type or disposition parameter values do not interact
   well with header line wrapping conventions.  In particular, proper
   header line wrapping depends on there being places where linear
   whitespace (LWSP) is allowed, which may or may not be present in a
   parameter value, and even if present may not be recognizable as such
   since specific knowledge of parameter value syntax may not be
   available to the agent doing the line wrapping. The result is that
   long parameter values may end up getting truncated or otherwise
   damaged by incorrect line wrapping implementations.

   A mechanism is therefore needed to break up parameter values into
   smaller units that are amenable to line wrapping. Any such mechanism
   MUST be compatible with existing MIME processors. This means that

    (1)   the mechanism MUST NOT change the syntax of MIME media
          type and disposition lines, and





Freed & Moore               Standards Track                     [Page 3]

RFC 2231         MIME Value and Encoded Word Extensions    November 1997


    (2)   the mechanism MUST NOT depend on parameter ordering
          since MIME states that parameters are not order
          sensitive.  Note that while MIME does prohibit
          modification of MIME headers during transport, it is
          still possible that parameters will be reordered when
          user agent level processing is done.

   The obvious solution, then, is to use multiple parameters to contain
   a single parameter value and to use some kind of distinguished name
   to indicate when this is being done.  And this obvious solution is
   exactly what is specified here: The asterisk character ("*") followed
   by a decimal count is employed to indicate that multiple parameters
   are being used to encapsulate a single parameter value.  The count
   starts at 0 and increments by 1 for each subsequent section of the
   parameter value.  Decimal values are used and neither leading zeroes
   nor gaps in the sequence are allowed.

   The original parameter value is recovered by concatenating the
   various sections of the parameter, in order.  For example, the
   content-type field

        Content-Type: message/external-body; access-type=URL;
         URL*0="ftp://";
         URL*1="cs.utk.edu/pub/moore/bulk-mailer/bulk-mailer.tar"

   is semantically identical to

        Content-Type: message/external-body; access-type=URL;
          URL="ftp://cs.utk.edu/pub/moore/bulk-mailer/bulk-mailer.tar"

   Note that quotes around parameter values are part of the value
   syntax; they are NOT part of the value itself.  Furthermore, it is
   explicitly permitted to have a mixture of quoted and unquoted
   continuation fields.

4.  Parameter Value Character Set and Language Information

   Some parameter values may need to be qualified with character set or
   language information.  It is clear that a distinguished parameter
   name is needed to identify when this information is present along
   with a specific syntax for the information in the value itself.  In
   addition, a lightweight encoding mechanism is needed to accommodate 8
   bit information in parameter values.








Freed & Moore               Standards Track                     [Page 4]

RFC 2231         MIME Value and Encoded Word Extensions    November 1997


   Asterisks ("*") are reused to provide the indicator that language and
   character set information is present and encoding is being used. A
   single quote ("'") is used to delimit the character set and language
   information at the beginning of the parameter value. Percent signs
   ("%") are used as the encoding flag, which agrees with RFC 2047.

   Specifically, an asterisk at the end of a parameter name acts as an
   indicator that character set and language information may appear at
   the beginning of the parameter value. A single quote is used to
   separate the character set, language, and actual value information in
   the parameter value string, and an percent sign is used to flag
   octets encoded in hexadecimal.  For example:

        Content-Type: application/x-stuff;
         title*=us-ascii'en-us'This%20is%20%2A%2A%2Afun%2A%2A%2A

   Note that it is perfectly permissible to leave either the character
   set or language field blank.  Note also that the single quote
   delimiters MUST be present even when one of the field values is
   omitted.  This is done when either character set, language, or both
   are not relevant to the parameter value at hand.  This MUST NOT be
   done in order to indicate a default character set or language --
   parameter field definitions MUST NOT assign a default character set
   or language.

4.1.  Combining Character Set, Language, and Parameter Continuations

   Character set and language information may be combined with the
   parameter continuation mechanism. For example:

   Content-Type: application/x-stuff
    title*0*=us-ascii'en'This%20is%20even%20more%20
    title*1*=%2A%2A%2Afun%2A%2A%2A%20
    title*2="isn't it!"

   Note that:

    (1)   Language and character set information only appear at
          the beginning of a given parameter value.

    (2)   Continuations do not provide a facility for using more
          than one character set or language in the same
          parameter value.

    (3)   A value presented using multiple continuations may
          contain a mixture of encoded and unencoded segments.





Freed & Moore               Standards Track                     [Page 5]

RFC 2231         MIME Value and Encoded Word Extensions    November 1997


    (4)   The first segment of a continuation MUST be encoded if
          language and character set information are given.

    (5)   If the first segment of a continued parameter value is
          encoded the language and character set field delimiters
          MUST be present even when the fields are left blank.

5.  Language specification in Encoded Words

   RFC 2047 provides support for non-US-ASCII character sets in RFC 822
   message header comments, phrases, and any unstructured text field.
   This is done by defining an encoded word construct which can appear
   in any of these places.  Given that these are fields intended for
   display, it is sometimes necessary to associate language information
   with encoded words as well as just the character set.  This
   specification extends the definition of an encoded word to allow the
   inclusion of such information.  This is simply done by suffixing the
   character set specification with an asterisk followed by the language
   tag.  For example:

          From: =?US-ASCII*EN?Q?Keith_Moore?= <moore@cs.utk.edu>

6.  IMAP4 Handling of Parameter Values

   IMAP4 [RFC-2060] servers SHOULD decode parameter value continuations
   when generating the BODY and BODYSTRUCTURE fetch attributes.

7.  Modifications to MIME ABNF

   The ABNF for MIME parameter values given in RFC 2045 is:

   parameter := attribute "=" value

   attribute := token
                ; Matching of attributes
                ; is ALWAYS case-insensitive.

   This specification changes this ABNF to:

   parameter := regular-parameter / extended-parameter

   regular-parameter := regular-parameter-name "=" value

   regular-parameter-name := attribute [section]

   attribute := 1*attribute-char





Freed & Moore               Standards Track                     [Page 6]

RFC 2231         MIME Value and Encoded Word Extensions    November 1997


   attribute-char := <any (US-ASCII) CHAR except SPACE, CTLs,
                     "*", "'", "%", or tspecials>

   section := initial-section / other-sections

   initial-section := "*0"

   other-sections := "*" ("1" / "2" / "3" / "4" / "5" /
                          "6" / "7" / "8" / "9") *DIGIT)

   extended-parameter := (extended-initial-name "="
                          extended-value) /
                         (extended-other-names "="
                          extended-other-values)

   extended-initial-name := attribute [initial-section] "*"

   extended-other-names := attribute other-sections "*"

   extended-initial-value := [charset] "'" [language] "'"
                             extended-other-values

   extended-other-values := *(ext-octet / attribute-char)

   ext-octet := "%" 2(DIGIT / "A" / "B" / "C" / "D" / "E" / "F")

   charset := <registered character set name>

   language := <registered language tag [RFC-1766]>

   The ABNF given in RFC 2047 for encoded-words is:

   encoded-word := "=?" charset "?" encoding "?" encoded-text "?="

   This specification changes this ABNF to:

   encoded-word := "=?" charset ["*" language] "?" encoded-text "?="

8.  Character sets which allow specification of language

   In the future it is likely that some character sets will provide
   facilities for inline language labeling. Such facilities are
   inherently more flexible than those defined here as they allow for
   language switching in the middle of a string.







Freed & Moore               Standards Track                     [Page 7]

RFC 2231         MIME Value and Encoded Word Extensions    November 1997


   If and when such facilities are developed they SHOULD be used in
   preference to the language labeling facilities specified here. Note
   that all the mechanisms defined here allow for the omission of
   language labels so as to be able to accommodate this possible future
   usage.

9.  Security Considerations

   This RFC does not discuss security issues and is not believed to
   raise any security issues not already endemic in electronic mail and
   present in fully conforming implementations of MIME.

10.  References

   [RFC-822]
        Crocker, D., "Standard for the Format of ARPA Internet
        Text Messages", STD 11, RFC 822 August 1982.

   [RFC-1766]
        Alvestrand, H., "Tags for the Identification of
        Languages", RFC 1766, March 1995.

   [RFC-2045]
        Freed, N., and N. Borenstein, "Multipurpose Internet Mail
        Extensions (MIME) Part One: Format of Internet Message
        Bodies", RFC 2045, December 1996.

   [RFC-2046]
        Freed, N. and N. Borenstein, "Multipurpose Internet Mail
        Extensions (MIME) Part Two: Media Types", RFC 2046,
        December 1996.

   [RFC-2047]
        Moore, K., "Multipurpose Internet Mail Extensions (MIME)
        Part Three: Representation of Non-ASCII Text in Internet
        Message Headers", RFC 2047, December 1996.

   [RFC-2048]
        Freed, N., Klensin, J. and J. Postel, "Multipurpose
        Internet Mail Extensions (MIME) Part Four: MIME
        Registration Procedures", RFC 2048, December 1996.

   [RFC-2049]
        Freed, N. and N. Borenstein, "Multipurpose Internet Mail
        Extensions (MIME) Part Five: Conformance Criteria and
        Examples", RFC 2049, December 1996.





Freed & Moore               Standards Track                     [Page 8]

RFC 2231         MIME Value and Encoded Word Extensions    November 1997


   [RFC-2060]
        Crispin, M., "Internet Message Access Protocol - Version
        4rev1", RFC 2060, December 1996.

   [RFC-2119]
        Bradner, S., "Key words for use in RFCs to Indicate
        Requirement Levels", RFC 2119, March 1997.

   [RFC-2130]
        Weider, C., Preston, C., Simonsen, K., Alvestrand, H.,
        Atkinson, R., Crispin, M., and P. Svanberg, "Report from the
        IAB Character Set Workshop", RFC 2130, April 1997.

   [RFC-2183]
        Troost, R., Dorner, S. and K. Moore, "Communicating
        Presentation Information in Internet Messages:  The
        Content-Disposition Header", RFC 2183, August 1997.

11.  Authors' Addresses

   Ned Freed
   Innosoft International, Inc.
   1050 Lakes Drive
   West Covina, CA 91790
   USA

   Phone: +1 626 919 3600
   Fax:   +1 626 919 3614
   EMail: ned.freed@innosoft.com


   Keith Moore
   Computer Science Dept.
   University of Tennessee
   107 Ayres Hall
   Knoxville, TN 37996-1301
   USA

   EMail: moore@cs.utk.edu












Freed & Moore               Standards Track                     [Page 9]

RFC 2231         MIME Value and Encoded Word Extensions    November 1997


12.  Full Copyright Statement

   Copyright (C) The Internet Society (1997).  All Rights Reserved.

   This document and translations of it may be copied and furnished to
   others, and derivative works that comment on or otherwise explain it
   or assist in its implementation may be prepared, copied, published
   and distributed, in whole or in part, without restriction of any
   kind, provided that the above copyright notice and this paragraph are
   included on all such copies and derivative works.  However, this
   document itself may not be modified in any way, such as by removing
   the copyright notice or references to the Internet Society or other
   Internet organizations, except as needed for the purpose of
   developing Internet standards in which case the procedures for
   copyrights defined in the Internet Standards process must be
   followed, or as required to translate it into languages other than
   English.

   The limited permissions granted above are perpetual and will not be
   revoked by the Internet Society or its successors or assigns.

   This document and the information contained herein is provided on an
   "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
   TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
   BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
   HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
   MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
























Freed & Moore               Standards Track                    [Page 10]



================================================
FILE: doc/notes/rfc/rfc2234.txt
================================================






Network Working Group                                     D. Crocker, Ed.
Request for Comments: 2234                       Internet Mail Consortium
Category: Standards Track                                      P. Overell
                                                      Demon Internet Ltd.
                                                            November 1997


             Augmented BNF for Syntax Specifications: ABNF


Status of this Memo

   This document specifies an Internet standards track protocol for the
   Internet community, and requests discussion and suggestions for
   improvements.  Please refer to the current edition of the "Internet
   Official Protocol Standards" (STD 1) for the standardization state
   and status of this protocol.  Distribution of this memo is unlimited.

Copyright Notice

   Copyright (C) The Internet Society (1997).  All Rights Reserved.

TABLE OF CONTENTS

   1. INTRODUCTION ..................................................  2

   2. RULE DEFINITION ...............................................  2
   2.1 RULE NAMING ..................................................  2
   2.2 RULE FORM ....................................................  3
   2.3 TERMINAL VALUES ..............................................  3
   2.4 EXTERNAL ENCODINGS ...........................................  5

   3. OPERATORS .....................................................  5
   3.1 CONCATENATION    RULE1     RULE2 .............................  5
   3.2 ALTERNATIVES RULE1 / RULE2 ...................................  6
   3.3 INCREMENTAL ALTERNATIVES   RULE1 =/ RULE2 ....................  6
   3.4 VALUE RANGE ALTERNATIVES   %C##-## ...........................  7
   3.5 SEQUENCE GROUP (RULE1 RULE2) .................................  7
   3.6 VARIABLE REPETITION *RULE ....................................  8
   3.7 SPECIFIC REPETITION NRULE ....................................  8
   3.8 OPTIONAL SEQUENCE [RULE] .....................................  8
   3.9 ; COMMENT ....................................................  8
   3.10 OPERATOR PRECEDENCE .........................................  9

   4. ABNF DEFINITION OF ABNF .......................................  9

   5. SECURITY CONSIDERATIONS ....................................... 10




Crocker & Overell           Standards Track                     [Page 1]

RFC 2234             ABNF for Syntax Specifications        November 1997


   6. APPENDIX A - CORE ............................................. 11
   6.1 CORE RULES ................................................... 11
   6.2 COMMON ENCODING .............................................. 12

   7. ACKNOWLEDGMENTS ............................................... 12

   8. REFERENCES .................................................... 13

   9. CONTACT ....................................................... 13

   10. FULL COPYRIGHT STATEMENT ..................................... 14

1.   INTRODUCTION

   Internet technical specifications often need to define a format
   syntax and are free to employ whatever notation their authors deem
   useful.  Over the years, a modified version of Backus-Naur Form
   (BNF), called Augmented BNF (ABNF), has been popular among many
   Internet specifications.  It balances compactness and simplicity,
   with reasonable representational power.  In the early days of the
   Arpanet, each specification contained its own definition of ABNF.
   This included the email specifications, RFC733 and then RFC822 which
   have come to be the common citations for defining ABNF.  The current
   document separates out that definition, to permit selective
   reference.  Predictably, it also provides some modifications and
   enhancements.

   The differences between standard BNF and ABNF involve naming rules,
   repetition, alternatives, order-independence, and value ranges.
   Appendix A (Core) supplies rule definitions and encoding for a core
   lexical analyzer of the type common to several Internet
   specifications.  It is provided as a convenience and is otherwise
   separate from the meta language defined in the body of this document,
   and separate from its formal status.

2.   RULE DEFINITION

2.1  Rule Naming

   The name of a rule is simply the name itself; that is, a sequence of
   characters, beginning with  an alphabetic character, and followed by
   a combination of alphabetics, digits and hyphens (dashes).

        NOTE:     Rule names are case-insensitive

   The names <rulename>, <Rulename>, <RULENAME> and <rUlENamE> all refer
   to the same rule.




Crocker & Overell           Standards Track                     [Page 2]

RFC 2234             ABNF for Syntax Specifications        November 1997


   Unlike original BNF, angle brackets ("<", ">") are not  required.
   However, angle brackets may be used around a rule name whenever their
   presence will facilitate discerning the use of  a rule name.  This is
   typically restricted to rule name references in free-form prose, or
   to distinguish partial rules that combine into a string not separated
   by white space, such as shown in the discussion about repetition,
   below.

2.2  Rule Form

   A rule is defined by the following sequence:

        name =  elements crlf

   where <name> is the name of the rule, <elements> is one or more rule
   names or terminal specifications and <crlf> is the end-of- line
   indicator, carriage return followed by line feed.  The equal sign
   separates the name from the definition of the rule.  The elements
   form a sequence of one or more rule names and/or value definitions,
   combined according to the various operators, defined in this
   document, such as alternative and repetition.

   For visual ease, rule definitions are left aligned.  When a rule
   requires multiple lines, the continuation lines are indented.  The
   left alignment and indentation are relative to the first lines of the
   ABNF rules and need not match the left margin of the document.

2.3  Terminal Values

   Rules resolve into a string of terminal values, sometimes called
   characters.  In ABNF a character is merely a non-negative integer.
   In certain contexts a specific mapping (encoding) of values into a
   character set (such as ASCII) will be specified.

   Terminals are specified by one or more numeric characters with the
   base interpretation of those characters indicated explicitly.  The
   following bases are currently defined:

        b           =  binary

        d           =  decimal

        x           =  hexadecimal








Crocker & Overell           Standards Track                     [Page 3]

RFC 2234             ABNF for Syntax Specifications        November 1997


   Hence:

        CR          =  %d13

        CR          =  %x0D

   respectively specify the decimal and hexadecimal representation of
   [US-ASCII] for carriage return.

   A concatenated string of such values is specified compactly, using a
   period (".") to indicate separation of characters within that value.
   Hence:

        CRLF        =  %d13.10

   ABNF permits specifying literal text string directly, enclosed in
   quotation-marks.  Hence:

        command     =  "command string"

   Literal text strings are interpreted as a concatenated set of
   printable characters.

        NOTE:     ABNF strings are case-insensitive and
                  the character set for these strings is us-ascii.

   Hence:

        rulename = "abc"

   and:

        rulename = "aBc"

   will match "abc", "Abc", "aBc", "abC", "ABc", "aBC", "AbC" and "ABC".

                To specify a rule which IS case SENSITIVE,
                   specify the characters individually.

   For example:

        rulename    =  %d97 %d98 %d99

   or

        rulename    =  %d97.98.99





Crocker & Overell           Standards Track                     [Page 4]

RFC 2234             ABNF for Syntax Specifications        November 1997


   will match only the string which comprises only lowercased
   characters, abc.

2.4  External Encodings

   External representations of terminal value characters will vary
   according to constraints in the storage or transmission environment.
   Hence, the same ABNF-based grammar may have multiple external
   encodings, such as one for a 7-bit US-ASCII environment, another for
   a binary octet environment and still a different one when 16-bit
   Unicode is used.  Encoding details are beyond the scope of ABNF,
   although Appendix A (Core) provides definitions for a 7-bit US-ASCII
   environment as has been common to much of the Internet.

   By separating external encoding from the syntax, it is intended that
   alternate encoding environments can be used for the same syntax.

3.   OPERATORS

3.1  Concatenation                                  Rule1 Rule2

   A rule can define a simple, ordered string of values -- i.e., a
   concatenation of contiguous characters -- by listing a sequence of
   rule names.  For example:

        foo         =  %x61           ; a

        bar         =  %x62           ; b

        mumble      =  foo bar foo

        So that the rule <mumble> matches the lowercase string "aba".

        LINEAR WHITE SPACE:  Concatenation is at the core of the ABNF
        parsing model.  A string of contiguous characters (values) is
        parsed according to the rules defined in ABNF.  For Internet
        specifications, there is some history of permitting linear white
        space (space and horizontal tab) to be freelyPand
        implicitlyPinterspersed around major constructs, such as
        delimiting special characters or atomic strings.

        NOTE:     This specification for ABNF does not
                  provide for implicit specification of linear white
                  space.

   Any grammar which wishes to permit linear white space around
   delimiters or string segments must specify it explicitly.  It is
   often useful to provide for such white space in "core" rules that are



Crocker & Overell           Standards Track                     [Page 5]

RFC 2234             ABNF for Syntax Specifications        November 1997


   then used variously among higher-level rules.  The "core" rules might
   be formed into a lexical analyzer or simply be part of the main
   ruleset.

3.2  Alternatives                               Rule1 / Rule2

   Elements separated by forward slash ("/") are alternatives.
   Therefore,

        foo / bar

   will accept <foo> or <bar>.

        NOTE:     A quoted string containing alphabetic
                  characters is special form for specifying alternative
                  characters and is interpreted as a non-terminal
                  representing the set of combinatorial strings with the
                  contained characters, in the specified order but with
                  any mixture of upper and lower case..

3.3  Incremental Alternatives                    Rule1 =/ Rule2

   It is sometimes convenient to specify a list of alternatives in
   fragments.  That is, an initial rule may match one or more
   alternatives, with later rule definitions adding to the set of
   alternatives.  This is particularly useful for otherwise- independent
   specifications which derive from the same parent rule set, such as
   often occurs with parameter lists.  ABNF permits this incremental
   definition through the construct:

        oldrule     =/ additional-alternatives

   So that the rule set

        ruleset     =  alt1 / alt2

        ruleset     =/ alt3

        ruleset     =/ alt4 / alt5

   is the same as specifying

        ruleset     =  alt1 / alt2 / alt3 / alt4 / alt5








Crocker & Overell           Standards Track                     [Page 6]

RFC 2234             ABNF for Syntax Specifications        November 1997


3.4  Value Range Alternatives                           %c##-##

   A range of alternative numeric values can be specified compactly,
   using dash ("-") to indicate the range of alternative values.  Hence:

        DIGIT       =  %x30-39

   is equivalent to:

        DIGIT       =  "0" / "1" / "2" / "3" / "4" / "5" / "6" /

                           "7" / "8" / "9"

   Concatenated numeric values and numeric value ranges can not be
   specified in the same string.  A numeric value may use the dotted
   notation for concatenation or it may use the dash notation to specify
   one value range.  Hence, to specify one printable character, between
   end of line sequences, the specification could be:

        char-line = %x0D.0A %x20-7E %x0D.0A

3.5  Sequence Group                             (Rule1 Rule2)

   Elements enclosed in parentheses are treated as a single element,
   whose contents are STRICTLY ORDERED.   Thus,

        elem (foo / bar) blat

   which matches (elem foo blat) or (elem bar blat).

        elem foo / bar blat

   matches (elem foo) or (bar blat).

        NOTE:     It is strongly advised to use grouping
                  notation, rather than to rely on proper reading of
                  "bare" alternations, when alternatives consist of
                  multiple rule names or literals.

   Hence it is recommended that instead of the above form, the form:

        (elem foo) / (bar blat)

   be used.  It will avoid misinterpretation by casual readers.

   The sequence group notation is also used within free text to set off
   an element sequence from the prose.




Crocker & Overell           Standards Track                     [Page 7]

RFC 2234             ABNF for Syntax Specifications        November 1997


3.6  Variable Repetition                                *Rule

   The operator "*" preceding an element indicates repetition. The full
   form is:

        <a>*<b>element

   where <a> and <b> are optional decimal values, indicating at least
   <a> and at most <b> occurrences of element.

   Default values are 0 and infinity so that *<element> allows any
   number, including zero; 1*<element> requires at  least  one;
   3*3<element> allows exactly 3 and 1*2<element> allows one or two.

3.7  Specific Repetition                                  nRule

   A rule of the form:

        <n>element

   is equivalent to

        <n>*<n>element

   That is, exactly  <N>  occurrences  of <element>. Thus 2DIGIT is a
   2-digit number, and 3ALPHA is a string of three alphabetic
   characters.

3.8  Optional Sequence                                   [RULE]

   Square brackets enclose an optional element sequence:

        [foo bar]

   is equivalent to

        *1(foo bar).

3.9  ; Comment

   A semi-colon starts a comment that continues to the end of line.
   This is a simple way of including useful notes in parallel with the
   specifications.








Crocker & Overell           Standards Track                     [Page 8]

RFC 2234             ABNF for Syntax Specifications        November 1997


3.10 Operator Precedence

   The various mechanisms described above have the following precedence,
   from highest (binding tightest) at the top, to lowest and loosest at
   the bottom:

        Strings, Names formation
        Comment
        Value range
        Repetition
        Grouping, Optional
        Concatenation
        Alternative

   Use of the alternative operator, freely mixed with concatenations can
   be confusing.

        Again, it is recommended that the grouping operator be used to
        make explicit concatenation groups.

4.   ABNF DEFINITION OF ABNF

   This syntax uses the rules provided in Appendix A (Core).

        rulelist       =  1*( rule / (*c-wsp c-nl) )

        rule           =  rulename defined-as elements c-nl
                               ; continues if next line starts
                               ;  with white space

        rulename       =  ALPHA *(ALPHA / DIGIT / "-")

        defined-as     =  *c-wsp ("=" / "=/") *c-wsp
                               ; basic rules definition and
                               ;  incremental alternatives

        elements       =  alternation *c-wsp

        c-wsp          =  WSP / (c-nl WSP)

        c-nl           =  comment / CRLF
                               ; comment or newline

        comment        =  ";" *(WSP / VCHAR) CRLF

        alternation    =  concatenation
                          *(*c-wsp "/" *c-wsp concatenation)




Crocker & Overell           Standards Track                     [Page 9]

RFC 2234             ABNF for Syntax Specifications        November 1997


        concatenation  =  repetition *(1*c-wsp repetition)

        repetition     =  [repeat] element

        repeat         =  1*DIGIT / (*DIGIT "*" *DIGIT)

        element        =  rulename / group / option /
                          char-val / num-val / prose-val

        group          =  "(" *c-wsp alternation *c-wsp ")"

        option         =  "[" *c-wsp alternation *c-wsp "]"

        char-val       =  DQUOTE *(%x20-21 / %x23-7E) DQUOTE
                               ; quoted string of SP and VCHAR
                                  without DQUOTE

        num-val        =  "%" (bin-val / dec-val / hex-val)

        bin-val        =  "b" 1*BIT
                          [ 1*("." 1*BIT) / ("-" 1*BIT) ]
                               ; series of concatenated bit values
                               ; or single ONEOF range

        dec-val        =  "d" 1*DIGIT
                          [ 1*("." 1*DIGIT) / ("-" 1*DIGIT) ]

        hex-val        =  "x" 1*HEXDIG
                          [ 1*("." 1*HEXDIG) / ("-" 1*HEXDIG) ]

        prose-val      =  "<" *(%x20-3D / %x3F-7E) ">"
                               ; bracketed string of SP and VCHAR
                                  without angles
                               ; prose description, to be used as
                                  last resort


5.   SECURITY CONSIDERATIONS

   Security is truly believed to be irrelevant to this document.











Crocker & Overell           Standards Track                    [Page 10]

RFC 2234             ABNF for Syntax Specifications        November 1997


6.   APPENDIX A - CORE

   This Appendix is provided as a convenient core for specific grammars.
   The definitions may be used as a core set of rules.

6.1  Core Rules

   Certain  basic  rules  are  in uppercase, such as SP, HTAB, CRLF,
   DIGIT, ALPHA, etc.

        ALPHA          =  %x41-5A / %x61-7A   ; A-Z / a-z

        BIT            =  "0" / "1"

        CHAR           =  %x01-7F
                               ; any 7-bit US-ASCII character,
                                  excluding NUL

        CR             =  %x0D
                               ; carriage return

        CRLF           =  CR LF
                               ; Internet standard newline

        CTL            =  %x00-1F / %x7F
                               ; controls

        DIGIT          =  %x30-39
                               ; 0-9

        DQUOTE         =  %x22
                               ; " (Double Quote)

        HEXDIG         =  DIGIT / "A" / "B" / "C" / "D" / "E" / "F"

        HTAB           =  %x09
                               ; horizontal tab

        LF             =  %x0A
                               ; linefeed

        LWSP           =  *(WSP / CRLF WSP)
                               ; linear white space (past newline)

        OCTET          =  %x00-FF
                               ; 8 bits of data

        SP             =  %x20



Crocker & Overell           Standards Track                    [Page 11]

RFC 2234             ABNF for Syntax Specifications        November 1997


                               ; space

        VCHAR          =  %x21-7E
                               ; visible (printing) characters

        WSP            =  SP / HTAB
                               ; white space

6.2  Common Encoding

   Externally, data are represented as "network virtual ASCII", namely
   7-bit US-ASCII in an 8-bit field, with the high (8th) bit set to
   zero.  A string of values is in "network byte order" with the
   higher-valued bytes represented on the left-hand side and being sent
   over the network first.

7.   ACKNOWLEDGMENTS

   The syntax for ABNF was originally specified in RFC 733.  Ken L.
   Harrenstien, of SRI International, was responsible for re-coding the
   BNF into an augmented BNF that makes the representation smaller and
   easier to understand.

   This recent project began as a simple effort to cull out the portion
   of RFC 822 which has been repeatedly cited by non-email specification
   writers, namely the description of augmented BNF.  Rather than simply
   and blindly converting the existing text into a separate document,
   the working group chose to give careful consideration to the
   deficiencies, as well as benefits, of the existing specification and
   related specifications available over the last 15 years and therefore
   to pursue enhancement.  This turned the project into something rather
   more ambitious than first intended.  Interestingly the result is not
   massively different from that original, although decisions such as
   removing the list notation came as a surprise.

   The current round of specification was part of the DRUMS working
   group, with significant contributions from Jerome Abela , Harald
   Alvestrand, Robert Elz, Roger Fajman, Aviva Garrett, Tom Harsch, Dan
   Kohn, Bill McQuillan, Keith Moore, Chris Newman , Pete Resnick and
   Henning Schulzrinne.











Crocker & Overell           Standards Track                    [Page 12]

RFC 2234             ABNF for Syntax Specifications        November 1997


8.   REFERENCES

   [US-ASCII]     Coded Character Set--7-Bit American Standard Code for
   Information Interchange, ANSI X3.4-1986.

   [RFC733]  Crocker, D., Vittal, J., Pogran, K., and D. Henderson,
   "Standard for the Format of ARPA Network Text Message," RFC 733,
   November 1977.

   [RFC822]  Crocker, D., "Standard for the Format of ARPA Internet Text
   Messages", STD 11, RFC 822, August 1982.

9.   CONTACT

   David H. Crocker                 Paul Overell

   Internet Mail Consortium         Demon Internet Ltd
   675 Spruce Dr.                   Dorking Business Park
   Sunnyvale, CA 94086 USA          Dorking
                                    Surrey, RH4 1HN
                                    UK

   Phone:    +1 408 246 8253
   Fax:      +1 408 249 6205
   EMail:    dcrocker@imc.org       paulo@turnpike.com


























Crocker & Overell           Standards Track                    [Page 13]

RFC 2234             ABNF for Syntax Specifications        November 1997


10.  Full Copyright Statement

   Copyright (C) The Internet Society (1997).  All Rights Reserved.

   This document and translations of it may be copied and furnished to
   others, and derivative works that comment on or otherwise explain it
   or assist in its implementation may be prepared, copied, published
   and distributed, in whole or in part, without restriction of any
   kind, provided that the above copyright notice and this paragraph are
   included on all such copies and derivative works.  However, this
   document itself may not be modified in any way, such as by removing
   the copyright notice or references to the Internet Society or other
   Internet organizations, except as needed for the purpose of
   developing Internet standards in which case the procedures for
   copyrights defined in the Internet Standards process must be
   followed, or as required to translate it into languages other than
   English.

   The limited permissions granted above are perpetual and will not be
   revoked by the Internet Society or its successors or assigns.

   This document and the information contained herein is provided on an
   "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
   TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
   BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
   HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
   MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
























Crocker & Overell           Standards Track                    [Page 14]



================================================
FILE: doc/notes/rfc/rfc2440.txt
================================================





Network Working Group                                         J. Callas
Request for Comments: 2440                           Network Associates
Category: Standards Track                                L. Donnerhacke
                                     IN-Root-CA Individual Network e.V.
                                                              H. Finney
                                                     Network Associates
                                                              R. Thayer
                                                        EIS Corporation
                                                          November 1998


                         OpenPGP Message Format

Status of this Memo

   This document specifies an Internet standards track protocol for the
   Internet community, and requests discussion and suggestions for
   improvements.  Please refer to the current edition of the "Internet
   Official Protocol Standards" (STD 1) for the standardization state
   and status of this protocol.  Distribution of this memo is unlimited.

Copyright Notice

   Copyright (C) The Internet Society (1998).  All Rights Reserved.

IESG Note

   This document defines many tag values, yet it doesn't describe a
   mechanism for adding new tags (for new features).  Traditionally the
   Internet Assigned Numbers Authority (IANA) handles the allocation of
   new values for future expansion and RFCs usually define the procedure
   to be used by the IANA.  However, there are subtle (and not so
   subtle) interactions that may occur in this protocol between new
   features and existing features which result in a significant
   reduction in over all security.  Therefore, this document does not
   define an extension procedure.  Instead requests to define new tag
   values (say for new encryption algorithms for example) should be
   forwarded to the IESG Security Area Directors for consideration or
   forwarding to the appropriate IETF Working Group for consideration.

Abstract

   This document is maintained in order to publish all necessary
   information needed to develop interoperable applications based on the
   OpenPGP format. It is not a step-by-step cookbook for writing an
   application. It describes only the format and methods needed to read,
   check, generate, and write conforming packets crossing any network.
   It does not deal with storage and implementation questions.  It does,



Callas, et. al.             Standards Track                     [Page 1]

RFC 2440                 OpenPGP Message Format            November 1998


   however, discuss implementation issues necessary to avoid security
   flaws.

   Open-PGP software uses a combination of strong public-key and
   symmetric cryptography to provide security services for electronic
   communications and data storage.  These services include
   confidentiality, key management, authentication, and digital
   signatures. This document specifies the message formats used in
   OpenPGP.

Table of Contents

            Status of this Memo                                       1
            IESG Note                                                 1
            Abstract                                                  1
            Table of Contents                                         2
   1.       Introduction                                              4
   1.1.     Terms                                                     5
   2.       General functions                                         5
   2.1.     Confidentiality via Encryption                            5
   2.2.     Authentication via Digital signature                      6
   2.3.     Compression                                               7
   2.4.     Conversion to Radix-64                                    7
   2.5.     Signature-Only Applications                               7
   3.       Data Element Formats                                      7
   3.1.     Scalar numbers                                            8
   3.2.     Multi-Precision Integers                                  8
   3.3.     Key IDs                                                   8
   3.4.     Text                                                      8
   3.5.     Time fields                                               9
   3.6.     String-to-key (S2K) specifiers                            9
   3.6.1.   String-to-key (S2k) specifier types                       9
   3.6.1.1. Simple S2K                                                9
   3.6.1.2. Salted S2K                                               10
   3.6.1.3. Iterated and Salted S2K                                  10
   3.6.2.   String-to-key usage                                      11
   3.6.2.1. Secret key encryption                                    11
   3.6.2.2. Symmetric-key message encryption                         11
   4.       Packet Syntax                                            12
   4.1.     Overview                                                 12
   4.2.     Packet Headers                                           12
   4.2.1.   Old-Format Packet Lengths                                13
   4.2.2.   New-Format Packet Lengths                                13
   4.2.2.1. One-Octet Lengths                                        14
   4.2.2.2. Two-Octet Lengths                                        14
   4.2.2.3. Five-Octet Lengths                                       14
   4.2.2.4. Partial Body Lengths                                     14
   4.2.3.   Packet Length Examples                                   14



Callas, et. al.             Standards Track                     [Page 2]

RFC 2440                 OpenPGP Message Format            November 1998


   4.3.     Packet Tags                                              15
   5.       Packet Types                                             16
   5.1.     Public-Key Encrypted Session Key Packets (Tag 1)         16
   5.2.     Signature Packet (Tag 2)                                 17
   5.2.1.   Signature Types                                          17
   5.2.2.   Version 3 Signature Packet Format                        19
   5.2.3.   Version 4 Signature Packet Format                        21
   5.2.3.1. Signature Subpacket Specification                        22
   5.2.3.2. Signature Subpacket Types                                24
   5.2.3.3. Signature creation time                                  25
   5.2.3.4. Issuer                                                   25
   5.2.3.5. Key expiration time                                      25
   5.2.3.6. Preferred symmetric algorithms                           25
   5.2.3.7. Preferred hash algorithms                                25
   5.2.3.8. Preferred compression algorithms                         26
   5.2.3.9. Signature expiration time                                26
   5.2.3.10.Exportable Certification                                 26
   5.2.3.11.Revocable                                                27
   5.2.3.12.Trust signature                                          27
   5.2.3.13.Regular expression                                       27
   5.2.3.14.Revocation key                                           27
   5.2.3.15.Notation Data                                            28
   5.2.3.16.Key server preferences                                   28
   5.2.3.17.Preferred key server                                     29
   5.2.3.18.Primary user id                                          29
   5.2.3.19.Policy URL                                               29
   5.2.3.20.Key Flags                                                29
   5.2.3.21.Signer's User ID                                         30
   5.2.3.22.Reason for Revocation                                    30
   5.2.4.   Computing Signatures                                     31
   5.2.4.1. Subpacket Hints                                          32
   5.3.     Symmetric-Key Encrypted Session-Key Packets (Tag 3)      32
   5.4.     One-Pass Signature Packets (Tag 4)                       33
   5.5.     Key Material Packet                                      34
   5.5.1.   Key Packet Variants                                      34
   5.5.1.1. Public Key Packet (Tag 6)                                34
   5.5.1.2. Public Subkey Packet (Tag 14)                            34
   5.5.1.3. Secret Key Packet (Tag 5)                                35
   5.5.1.4. Secret Subkey Packet (Tag 7)                             35
   5.5.2.   Public Key Packet Formats                                35
   5.5.3.   Secret Key Packet Formats                                37
   5.6.     Compressed Data Packet (Tag 8)                           38
   5.7.     Symmetrically Encrypted Data Packet (Tag 9)              39
   5.8.     Marker Packet (Obsolete Literal Packet) (Tag 10)         39
   5.9.     Literal Data Packet (Tag 11)                             40
   5.10.    Trust Packet (Tag 12)                                    40
   5.11.    User ID Packet (Tag 13)                                  41
   6.       Radix-64 Conversions                                     41



Callas, et. al.             Standards Track                     [Page 3]

RFC 2440                 OpenPGP Message Format            November 1998


   6.1.     An Implementation of the CRC-24 in "C"                   42
   6.2.     Forming ASCII Armor                                      42
   6.3.     Encoding Binary in Radix-64                              44
   6.4.     Decoding Radix-64                                        46
   6.5.     Examples of Radix-64                                     46
   6.6.     Example of an ASCII Armored Message                      47
   7.       Cleartext signature framework                            47
   7.1.     Dash-Escaped Text                                        47
   8.       Regular Expressions                                      48
   9.       Constants                                                49
   9.1.     Public Key Algorithms                                    49
   9.2.     Symmetric Key Algorithms                                 49
   9.3.     Compression Algorithms                                   50
   9.4.     Hash Algorithms                                          50
   10.      Packet Composition                                       50
   10.1.    Transferable Public Keys                                 50
   10.2.    OpenPGP Messages                                         52
   10.3.    Detached Signatures                                      52
   11.      Enhanced Key Formats                                     52
   11.1.    Key Structures                                           52
   11.2.    Key IDs and Fingerprints                                 53
   12.      Notes on Algorithms                                      54
   12.1.    Symmetric Algorithm Preferences                          54
   12.2.    Other Algorithm Preferences                              55
   12.2.1.  Compression Preferences                                  56
   12.2.2.  Hash Algorithm Preferences                               56
   12.3.    Plaintext                                                56
   12.4.    RSA                                                      56
   12.5.    Elgamal                                                  57
   12.6.    DSA                                                      58
   12.7.    Reserved Algorithm Numbers                               58
   12.8.    OpenPGP CFB mode                                         58
   13.      Security Considerations                                  59
   14.      Implementation Nits                                      60
   15.      Authors and Working Group Chair                          62
   16.      References                                               63
   17.      Full Copyright Statement                                 65

1. Introduction

   This document provides information on the message-exchange packet
   formats used by OpenPGP to provide encryption, decryption, signing,
   and key management functions. It builds on the foundation provided in
   RFC 1991 "PGP Message Exchange Formats."







Callas, et. al.             Standards Track                     [Page 4]

RFC 2440                 OpenPGP Message Format            November 1998


1.1. Terms

     * OpenPGP - This is a definition for security software that uses
       PGP 5.x as a basis.

     * PGP - Pretty Good Privacy. PGP is a family of software systems
       developed by Philip R. Zimmermann from which OpenPGP is based.

     * PGP 2.6.x - This version of PGP has many variants, hence the term
       PGP 2.6.x. It used only RSA, MD5, and IDEA for its cryptographic
       transforms. An informational RFC, RFC 1991, was written
       describing this version of PGP.

     * PGP 5.x - This version of PGP is formerly known as "PGP 3" in the
       community and also in the predecessor of this document, RFC 1991.
       It has new formats and corrects a number of problems in the PGP
       2.6.x design. It is referred to here as PGP 5.x because that
       software was the first release of the "PGP 3" code base.

   "PGP", "Pretty Good", and "Pretty Good Privacy" are trademarks of
   Network Associates, Inc. and are used with permission.

   This document uses the terms "MUST", "SHOULD", and "MAY" as defined
   in RFC 2119, along with the negated forms of those terms.

2. General functions

   OpenPGP provides data integrity services for messages and data files
   by using these core technologies:

     - digital signatures

     - encryption

     - compression

     - radix-64 conversion

   In addition, OpenPGP provides key management and certificate
   services, but many of these are beyond the scope of this document.

2.1. Confidentiality via Encryption

   OpenPGP uses two encryption methods to provide confidentiality:
   symmetric-key encryption and public key encryption. With public-key
   encryption, the object is encrypted using a symmetric encryption
   algorithm.  Each symmetric key is used only once. A new "session key"
   is generated as a random number for each message. Since it is used



Callas, et. al.             Standards Track                     [Page 5]

RFC 2440                 OpenPGP Message Format            November 1998


   only once, the session key is bound to the message and transmitted
   with it.  To protect the key, it is encrypted with the receiver's
   public key. The sequence is as follows:

   1.  The sender creates a message.

   2.  The sending OpenPGP generates a random number to be used as a
       session key for this message only.

   3.  The session key is encrypted using each recipient's public key.
       These "encrypted session keys" start the message.

   4.  The sending OpenPGP encrypts the message using the session key,
       which forms the remainder of the message. Note that the message
       is also usually compressed.

   5.  The receiving OpenPGP decrypts the session key using the
       recipient's private key.

   6.  The receiving OpenPGP decrypts the message using the session key.
       If the message was compressed, it will be decompressed.

   With symmetric-key encryption, an object may be encrypted with a
   symmetric key derived from a passphrase (or other shared secret), or
   a two-stage mechanism similar to the public-key method described
   above in which a session key is itself encrypted with a symmetric
   algorithm keyed from a shared secret.

   Both digital signature and confidentiality services may be applied to
   the same message. First, a signature is generated for the message and
   attached to the message. Then, the message plus signature is
   encrypted using a symmetric session key. Finally, the session key is
   encrypted using public-key encryption and prefixed to the encrypted
   block.

2.2. Authentication via Digital signature

   The digital signature uses a hash code or message digest algorithm,
   and a public-key signature algorithm. The sequence is as follows:

   1.  The sender creates a message.

   2.  The sending software generates a hash code of the message.

   3.  The sending software generates a signature from the hash code
       using the sender's private key.

   4.  The binary signature is attached to the message.



Callas, et. al.             Standards Track                     [Page 6]

RFC 2440                 OpenPGP Message Format            November 1998


   5.  The receiving software keeps a copy of the message signature.

   6.  The receiving software generates a new hash code for the
       received message and verifies it using the message's signature.
       If the verification is successful, the message is accepted as
       authentic.

2.3. Compression

   OpenPGP implementations MAY compress the message after applying the
   signature but before encryption.

2.4. Conversion to Radix-64

   OpenPGP's underlying native representation for encrypted messages,
   signature certificates, and keys is a stream of arbitrary octets.
   Some systems only permit the use of blocks consisting of seven-bit,
   printable text. For transporting OpenPGP's native raw binary octets
   through channels that are not safe to raw binary data, a printable
   encoding of these binary octets is needed.  OpenPGP provides the
   service of converting the raw 8-bit binary octet stream to a stream
   of printable ASCII characters, called Radix-64 encoding or ASCII
   Armor.

   Implementations SHOULD provide Radix-64 conversions.

   Note that many applications, particularly messaging applications,
   will want more advanced features as described in the OpenPGP-MIME
   document, RFC 2015. An application that implements OpenPGP for
   messaging SHOULD implement OpenPGP-MIME.

2.5. Signature-Only Applications

   OpenPGP is designed for applications that use both encryption and
   signatures, but there are a number of problems that are solved by a
   signature-only implementation. Although this specification requires
   both encryption and signatures, it is reasonable for there to be
   subset implementations that are non-comformant only in that they omit
   encryption.

3. Data Element Formats

   This section describes the data elements used by OpenPGP.








Callas, et. al.             Standards Track                     [Page 7]

RFC 2440                 OpenPGP Message Format            November 1998


3.1. Scalar numbers

   Scalar numbers are unsigned, and are always stored in big-endian
   format. Using n[k] to refer to the kth octet being interpreted, the
   value of a two-octet scalar is ((n[0] << 8) + n[1]). The value of a
   four-octet scalar is ((n[0] << 24) + (n[1] << 16) + (n[2] << 8) +
   n[3]).

3.2. Multi-Precision Integers

   Multi-Precision Integers (also called MPIs) are unsigned integers
   used to hold large integers such as the ones used in cryptographic
   calculations.

   An MPI consists of two pieces: a two-octet scalar that is the length
   of the MPI in bits followed by a string of octets that contain the
   actual integer.

   These octets form a big-endian number; a big-endian number can be
   made into an MPI by prefixing it with the appropriate length.

   Examples:

   (all numbers are in hexadecimal)

   The string of octets [00 01 01] forms an MPI with the value 1. The
   string [00 09 01 FF] forms an MPI with the value of 511.

   Additional rules:

   The size of an MPI is ((MPI.length + 7) / 8) + 2 octets.

   The length field of an MPI describes the length starting from its
   most significant non-zero bit. Thus, the MPI [00 02 01] is not formed
   correctly. It should be [00 01 01].

3.3. Key IDs

   A Key ID is an eight-octet scalar that identifies a key.
   Implementations SHOULD NOT assume that Key IDs are unique. The
   section, "Enhanced Key Formats" below describes how Key IDs are
   formed.

3.4. Text

   The default character set for text is the UTF-8 [RFC2279] encoding of
   Unicode [ISO10646].




Callas, et. al.             Standards Track                     [Page 8]

RFC 2440                 OpenPGP Message Format            November 1998


3.5. Time fields

   A time field is an unsigned four-octet number containing the number
   of seconds elapsed since midnight, 1 January 1970 UTC.

3.6. String-to-key (S2K) specifiers

   String-to-key (S2K) specifiers are used to convert passphrase strings
   into symmetric-key encryption/decryption keys.  They are used in two
   places, currently: to encrypt the secret part of private keys in the
   private keyring, and to convert passphrases to encryption keys for
   symmetrically encrypted messages.

3.6.1. String-to-key (S2k) specifier types

   There are three types of S2K specifiers currently supported, as
   follows:

3.6.1.1. Simple S2K

   This directly hashes the string to produce the key data.  See below
   for how this hashing is done.

       Octet 0:        0x00
       Octet 1:        hash algorithm

   Simple S2K hashes the passphrase to produce the session key.  The
   manner in which this is done depends on the size of the session key
   (which will depend on the cipher used) and the size of the hash
   algorithm's output. If the hash size is greater than or equal to the
   session key size, the high-order (leftmost) octets of the hash are
   used as the key.

   If the hash size is less than the key size, multiple instances of the
   hash context are created -- enough to produce the required key data.
   These instances are preloaded with 0, 1, 2, ... octets of zeros (that
   is to say, the first instance has no preloading, the second gets
   preloaded with 1 octet of zero, the third is preloaded with two
   octets of zeros, and so forth).

   As the data is hashed, it is given independently to each hash
   context. Since the contexts have been initialized differently, they
   will each produce different hash output.  Once the passphrase is
   hashed, the output data from the multiple hashes is concatenated,
   first hash leftmost, to produce the key data, with any excess octets
   on the right discarded.





Callas, et. al.             Standards Track                     [Page 9]

RFC 2440                 OpenPGP Message Format            November 1998


3.6.1.2. Salted S2K

   This includes a "salt" value in the S2K specifier -- some arbitrary
   data -- that gets hashed along with the passphrase string, to help
   prevent dictionary attacks.

       Octet 0:        0x01
       Octet 1:        hash algorithm
       Octets 2-9:     8-octet salt value

   Salted S2K is exactly like Simple S2K, except that the input to the
   hash function(s) consists of the 8 octets of salt from the S2K
   specifier, followed by the passphrase.

3.6.1.3. Iterated and Salted S2K

   This includes both a salt and an octet count.  The salt is combined
   with the passphrase and the resulting value is hashed repeatedly.
   This further increases the amount of work an attacker must do to try
   dictionary attacks.

       Octet  0:        0x03
       Octet  1:        hash algorithm
       Octets 2-9:      8-octet salt value
       Octet  10:       count, a one-octet, coded value

   The count is coded into a one-octet number using the following
   formula:

       #define EXPBIAS 6
           count = ((Int32)16 + (c & 15)) << ((c >> 4) + EXPBIAS);

   The above formula is in C, where "Int32" is a type for a 32-bit
   integer, and the variable "c" is the coded count, Octet 10.

   Iterated-Salted S2K hashes the passphrase and salt data multiple
   times. The total number of octets to be hashed is specified in the
   encoded count in the S2K specifier.  Note that the resulting count
   value is an octet count of how many octets will be hashed, not an
   iteration count.

   Initially, one or more hash contexts are set up as with the other S2K
   algorithms, depending on how many octets of key data are needed.
   Then the salt, followed by the passphrase data is repeatedly hashed
   until the number of octets specified by the octet count has been
   hashed.  The one exception is that if the octet count is less than
   the size of the salt plus passphrase, the full salt plus passphrase
   will be hashed even though that is greater than the octet count.



Callas, et. al.             Standards Track                    [Page 10]

RFC 2440                 OpenPGP Message Format            November 1998


   After the hashing is done the data is unloaded from the hash
   context(s) as with the other S2K algorithms.

3.6.2. String-to-key usage

   Implementations SHOULD use salted or iterated-and-salted S2K
   specifiers, as simple S2K specifiers are more vulnerable to
   dictionary attacks.

3.6.2.1. Secret key encryption

   An S2K specifier can be stored in the secret keyring to specify how
   to convert the passphrase to a key that unlocks the secret data.
   Older versions of PGP just stored a cipher algorithm octet preceding
   the secret data or a zero to indicate that the secret data was
   unencrypted. The MD5 hash function was always used to convert the
   passphrase to a key for the specified cipher algorithm.

   For compatibility, when an S2K specifier is used, the special value
   255 is stored in the position where the hash algorithm octet would
   have been in the old data structure.  This is then followed
   immediately by a one-octet algorithm identifier, and then by the S2K
   specifier as encoded above.

   Therefore, preceding the secret data there will be one of these
   possibilities:

       0:           secret data is unencrypted (no pass phrase)
       255:         followed by algorithm octet and S2K specifier
       Cipher alg:  use Simple S2K algorithm using MD5 hash

   This last possibility, the cipher algorithm number with an implicit
   use of MD5 and IDEA, is provided for backward compatibility; it MAY
   be understood, but SHOULD NOT be generated, and is deprecated.

   These are followed by an 8-octet Initial Vector for the decryption of
   the secret values, if they are encrypted, and then the secret key
   values themselves.

3.6.2.2. Symmetric-key message encryption

   OpenPGP can create a Symmetric-key Encrypted Session Key (ESK) packet
   at the front of a message.  This is used to allow S2K specifiers to
   be used for the passphrase conversion or to create messages with a
   mix of symmetric-key ESKs and public-key ESKs. This allows a message
   to be decrypted either with a passphrase or a public key.





Callas, et. al.             Standards Track                    [Page 11]

RFC 2440                 OpenPGP Message Format            November 1998


   PGP 2.X always used IDEA with Simple string-to-key conversion when
   encrypting a message with a symmetric algorithm. This is deprecated,
   but MAY be used for backward-compatibility.

4. Packet Syntax

   This section describes the packets used by OpenPGP.

4.1. Overview

   An OpenPGP message is constructed from a number of records that are
   traditionally called packets. A packet is a chunk of data that has a
   tag specifying its meaning. An OpenPGP message, keyring, certificate,
   and so forth consists of a number of packets. Some of those packets
   may contain other OpenPGP packets (for example, a compressed data
   packet, when uncompressed, contains OpenPGP packets).

   Each packet consists of a packet header, followed by the packet body.
   The packet header is of variable length.

4.2. Packet Headers

   The first octet of the packet header is called the "Packet Tag." It
   determines the format of the header and denotes the packet contents.
   The remainder of the packet header is the length of the packet.

   Note that the most significant bit is the left-most bit, called bit
   7. A mask for this bit is 0x80 in hexadecimal.

              +---------------+
         PTag |7 6 5 4 3 2 1 0|
              +---------------+
         Bit 7 -- Always one
         Bit 6 -- New packet format if set

   PGP 2.6.x only uses old format packets. Thus, software that
   interoperates with those versions of PGP must only use old format
   packets. If interoperability is not an issue, either format may be
   used. Note that old format packets have four bits of content tags,
   and new format packets have six; some features cannot be used and
   still be backward-compatible.

   Old format packets contain:

         Bits 5-2 -- content tag
         Bits 1-0 - length-type





Callas, et. al.             Standards Track                    [Page 12]

RFC 2440                 OpenPGP Message Format            November 1998


   New format packets contain:

         Bits 5-0 -- content tag

4.2.1. Old-Format Packet Lengths

   The meaning of the length-type in old-format packets is:

   0 - The packet has a one-octet length. The header is 2 octets long.

   1 - The packet has a two-octet length. The header is 3 octets long.

   2 - The packet has a four-octet length. The header is 5 octets long.

   3 - The packet is of indeterminate length.  The header is 1 octet
       long, and the implementation must determine how long the packet
       is. If the packet is in a file, this means that the packet
       extends until the end of the file. In general, an implementation
       SHOULD NOT use indeterminate length packets except where the end
       of the data will be clear from the context, and even then it is
       better to use a definite length, or a new-format header. The
       new-format headers described below have a mechanism for precisely
       encoding data of indeterminate length.

4.2.2. New-Format Packet Lengths

   New format packets have four possible ways of encoding length:

    1. A one-octet Body Length header encodes packet lengths of up to
       191 octets.

   2. A two-octet Body Length header encodes packet lengths of 192 to
       8383 octets.

    3. A five-octet Body Length header encodes packet lengths of up to
       4,294,967,295 (0xFFFFFFFF) octets in length. (This actually
       encodes a four-octet scalar number.)

    4. When the length of the packet body is not known in advance by the
       issuer, Partial Body Length headers encode a packet of
       indeterminate length, effectively making it a stream.










Callas, et. al.             Standards Track                    [Page 13]

RFC 2440                 OpenPGP Message Format            November 1998


4.2.2.1. One-Octet Lengths

   A one-octet Body Length header encodes a length of from 0 to 191
   octets. This type of length header is recognized because the one
   octet value is less than 192.  The body length is equal to:

       bodyLen = 1st_octet;

4.2.2.2. Two-Octet Lengths

   A two-octet Body Length header encodes a length of from 192 to 8383
   octets.  It is recognized because its first octet is in the range 192
   to 223.  The body length is equal to:

       bodyLen = ((1st_octet - 192) << 8) + (2nd_octet) + 192

4.2.2.3. Five-Octet Lengths

   A five-octet Body Length header consists of a single octet holding
   the value 255, followed by a four-octet scalar. The body length is
   equal to:

       bodyLen = (2nd_octet << 24) | (3rd_octet << 16) |
                 (4th_octet << 8)  | 5th_octet

4.2.2.4. Partial Body Lengths

   A Partial Body Length header is one octet long and encodes the length
   of only part of the data packet. This length is a power of 2, from 1
   to 1,073,741,824 (2 to the 30th power).  It is recognized by its one
   octet value that is greater than or equal to 224, and less than 255.
   The partial body length is equal to:

       partialBodyLen = 1 << (1st_octet & 0x1f);

   Each Partial Body Length header is followed by a portion of the
   packet body data. The Partial Body Length header specifies this
   portion's length. Another length header (of one of the three types --
   one octet, two-octet, or partial) follows that portion. The last
   length header in the packet MUST NOT be a partial Body Length header.
   Partial Body Length headers may only be used for the non-final parts
   of the packet.

4.2.3. Packet Length Examples

   These examples show ways that new-format packets might encode the
   packet lengths.




Callas, et. al.             Standards Track                    [Page 14]

RFC 2440                 OpenPGP Message Format            November 1998


   A packet with length 100 may have its length encoded in one octet:
   0x64. This is followed by 100 octets of data.

   A packet with length 1723 may have its length coded in two octets:
   0xC5, 0xFB.  This header is followed by the 1723 octets of data.

   A packet with length 100000 may have its length encoded in five
   octets: 0xFF, 0x00, 0x01, 0x86, 0xA0.

   It might also be encoded in the following octet stream: 0xEF, first
   32768 octets of data; 0xE1, next two octets of data; 0xE0, next one
   octet of data; 0xF0, next 65536 octets of data; 0xC5, 0xDD, last 1693
   octets of data.  This is just one possible encoding, and many
   variations are possible on the size of the Partial Body Length
   headers, as long as a regular Body Length header encodes the last
   portion of the data. Note also that the last Body Length header can
   be a zero-length header.

   An implementation MAY use Partial Body Lengths for data packets, be
   they literal, compressed, or encrypted. The first partial length MUST
   be at least 512 octets long. Partial Body Lengths MUST NOT be used
   for any other packet types.

   Please note that in all of these explanations, the total length of
   the packet is the length of the header(s) plus the length of the
   body.

4.3. Packet Tags

   The packet tag denotes what type of packet the body holds. Note that
   old format headers can only have tags less than 16, whereas new
   format headers can have tags as great as 63. The defined tags (in
   decimal) are:

       0        -- Reserved - a packet tag must not have this value
       1        -- Public-Key Encrypted Session Key Packet
       2        -- Signature Packet
       3        -- Symmetric-Key Encrypted Session Key Packet
       4        -- One-Pass Signature Packet
       5        -- Secret Key Packet
       6        -- Public Key Packet
       7        -- Secret Subkey Packet
       8        -- Compressed Data Packet
       9        -- Symmetrically Encrypted Data Packet
       10       -- Marker Packet
       11       -- Literal Data Packet
       12       -- Trust Packet




Callas, et. al.             Standards Track                    [Page 15]

RFC 2440                 OpenPGP Message Format            November 1998


       13       -- User ID Packet
       14       -- Public Subkey Packet
       60 to 63 -- Private or Experimental Values

5. Packet Types

5.1. Public-Key Encrypted Session Key Packets (Tag 1)

   A Public-Key Encrypted Session Key packet holds the session key used
   to encrypt a message. Zero or more Encrypted Session Key packets
   (either Public-Key or Symmetric-Key) may precede a Symmetrically
   Encrypted Data Packet, which holds an encrypted message.  The message
   is encrypted with the session key, and the session key is itself
   encrypted and stored in the Encrypted Session Key packet(s).  The
   Symmetrically Encrypted Data Packet is preceded by one Public-Key
   Encrypted Session Key packet for each OpenPGP key to which the
   message is encrypted.  The recipient of the message finds a session
   key that is encrypted to their public key, decrypts the session key,
   and then uses the session key to decrypt the message.

   The body of this packet consists of:

     - A one-octet number giving the version number of the packet type.
       The currently defined value for packet version is 3. An
       implementation should accept, but not generate a version of 2,
       which is equivalent to V3 in all other respects.

     - An eight-octet number that gives the key ID of the public key
       that the session key is encrypted to.

     - A one-octet number giving the public key algorithm used.

     - A string of octets that is the encrypted session key. This string
       takes up the remainder of the packet, and its contents are
       dependent on the public key algorithm used.

   Algorithm Specific Fields for RSA encryption

     - multiprecision integer (MPI) of RSA encrypted value m**e mod n.

   Algorithm Specific Fields for Elgamal encryption:

     - MPI of Elgamal (Diffie-Hellman) value g**k mod p.

     - MPI of Elgamal (Diffie-Hellman) value m * y**k mod p.






Callas, et. al.             Standards Track                    [Page 16]

RFC 2440                 OpenPGP Message Format            November 1998


   The value "m" in the above formulas is derived from the session key
   as follows.  First the session key is prefixed with a one-octet
   algorithm identifier that specifies the symmetric encryption
   algorithm used to encrypt the following Symmetrically Encrypted Data
   Packet.  Then a two-octet checksum is appended which is equal to the
   sum of the preceding session key octets, not including the algorithm
   identifier, modulo 65536.  This value is then padded as described in
   PKCS-1 block type 02 [RFC2313] to form the "m" value used in the
   formulas above.

   Note that when an implementation forms several PKESKs with one
   session key, forming a message that can be decrypted by several keys,
   the implementation MUST make new PKCS-1 padding for each key.

   An implementation MAY accept or use a Key ID of zero as a "wild card"
   or "speculative" Key ID. In this case, the receiving implementation
   would try all available private keys, checking for a valid decrypted
   session key. This format helps reduce traffic analysis of messages.

5.2. Signature Packet (Tag 2)

   A signature packet describes a binding between some public key and
   some data. The most common signatures are a signature of a file or a
   block of text, and a signature that is a certification of a user ID.

   Two versions of signature packets are defined.  Version 3 provides
   basic signature information, while version 4 provides an expandable
   format with subpackets that can specify more information about the
   signature. PGP 2.6.x only accepts version 3 signatures.

   Implementations MUST accept V3 signatures. Implementations SHOULD
   generate V4 signatures.  Implementations MAY generate a V3 signature
   that can be verified by PGP 2.6.x.

   Note that if an implementation is creating an encrypted and signed
   message that is encrypted to a V3 key, it is reasonable to create a
   V3 signature.

5.2.1. Signature Types

   There are a number of possible meanings for a signature, which are
   specified in a signature type octet in any given signature. These
   meanings are:

   0x00: Signature of a binary document.
         Typically, this means the signer owns it, created it, or
         certifies that it has not been modified.




Callas, et. al.             Standards Track                    [Page 17]

RFC 2440                 OpenPGP Message Format            November 1998


   0x01: Signature of a canonical text document.
         Typically, this means the signer owns it, created it, or
         certifies that it has not been modified.  The signature is
         calculated over the text data with its line endings converted
         to <CR><LF> and trailing blanks removed.

   0x02: Standalone signature.
         This signature is a signature of only its own subpacket
         contents. It is calculated identically to a signature over a
         zero-length binary document. Note that it doesn't make sense to
         have a V3 standalone signature.

   0x10: Generic certification of a User ID and Public Key packet.
         The issuer of this certification does not make any particular
         assertion as to how well the certifier has checked that the
         owner of the key is in fact the person described by the user
         ID.  Note that all PGP "key signatures" are this type of
         certification.

   0x11: Persona certification of a User ID and Public Key packet.
         The issuer of this certification has not done any verification
         of the claim that the owner of this key is the user ID
         specified.

   0x12: Casual certification of a User ID and Public Key packet.
         The issuer of this certification has done some casual
         verification of the claim of identity.

   0x13: Positive certification of a User ID and Public Key packet.
         The issuer of this certification has done substantial
         verification of the claim of identity.

         Please note that the vagueness of these certification claims is
         not a flaw, but a feature of the system. Because PGP places
         final authority for validity upon the receiver of a
         certification, it may be that one authority's casual
         certification might be more rigorous than some other
         authority's positive certification. These classifications allow
         a certification authority to issue fine-grained claims.

   0x18: Subkey Binding Signature
         This signature is a statement by the top-level signing key
         indicates that it owns the subkey. This signature is calculated
         directly on the subkey itself, not on any User ID or other
         packets.






Callas, et. al.             Standards Track                    [Page 18]

RFC 2440                 OpenPGP Message Format            November 1998


   0x1F: Signature directly on a key
         This signature is calculated directly on a key.  It binds the
         information in the signature subpackets to the key, and is
         appropriate to be used for subpackets that provide information
         about the key, such as the revocation key subpacket. It is also
         appropriate for statements that non-self certifiers want to
         make about the key itself, rather than the binding between a
         key and a name.

   0x20: Key revocation signature
         The signature is calculated directly on the key being revoked.
         A revoked key is not to be used.  Only revocation signatures by
         the key being revoked, or by an authorized revocation key,
         should be considered valid revocation signatures.

   0x28: Subkey revocation signature
         The signature is calculated directly on the subkey being
         revoked.  A revoked subkey is not to be used.  Only revocation
         signatures by the top-level signature key that is bound to this
         subkey, or by an authorized revocation key, should be
         considered valid revocation signatures.

   0x30: Certification revocation signature
         This signature revokes an earlier user ID certification
         signature (signature class 0x10 through 0x13). It should be
         issued by the same key that issued the revoked signature or an
         authorized revocation key The signature should have a later
         creation date than the signature it revokes.

   0x40: Timestamp signature.
         This signature is only meaningful for the timestamp contained
         in it.

5.2.2. Version 3 Signature Packet Format

   The body of a version 3 Signature Packet contains:

     - One-octet version number (3).

     - One-octet length of following hashed material.  MUST be 5.

         - One-octet signature type.

         - Four-octet creation time.

     - Eight-octet key ID of signer.

     - One-octet public key algorithm.



Callas, et. al.             Standards Track                    [Page 19]

RFC 2440                 OpenPGP Message Format            November 1998


     - One-octet hash algorithm.

     - Two-octet field holding left 16 bits of signed hash value.

     - One or more multi-precision integers comprising the signature.
       This portion is algorithm specific, as described below.

   The data being signed is hashed, and then the signature type and
   creation time from the signature packet are hashed (5 additional
   octets).  The resulting hash value is used in the signature
   algorithm. The high 16 bits (first two octets) of the hash are
   included in the signature packet to provide a quick test to reject
   some invalid signatures.

   Algorithm Specific Fields for RSA signatures:

     - multiprecision integer (MPI) of RSA signature value m**d.

   Algorithm Specific Fields for DSA signatures:

     - MPI of DSA value r.

     - MPI of DSA value s.

   The signature calculation is based on a hash of the signed data, as
   described above.  The details of the calculation are different for
   DSA signature than for RSA signatures.

   With RSA signatures, the hash value is encoded as described in PKCS-1
   section 10.1.2, "Data encoding", producing an ASN.1 value of type
   DigestInfo, and then padded using PKCS-1 block type 01 [RFC2313].
   This requires inserting the hash value as an octet string into an
   ASN.1 structure. The object identifier for the type of hash being
   used is included in the structure.  The hexadecimal representations
   for the currently defined hash algorithms are:

     - MD2:        0x2A, 0x86, 0x48, 0x86, 0xF7, 0x0D, 0x02, 0x02

     - MD5:        0x2A, 0x86, 0x48, 0x86, 0xF7, 0x0D, 0x02, 0x05

     - RIPEMD-160: 0x2B, 0x24, 0x03, 0x02, 0x01

     - SHA-1:      0x2B, 0x0E, 0x03, 0x02, 0x1A








Callas, et. al.             Standards Track                    [Page 20]

RFC 2440                 OpenPGP Message Format            November 1998


   The ASN.1 OIDs are:

     - MD2:        1.2.840.113549.2.2

     - MD5:        1.2.840.113549.2.5

     - RIPEMD-160: 1.3.36.3.2.1

     - SHA-1:      1.3.14.3.2.26

   The full hash prefixes for these are:

       MD2:        0x30, 0x20, 0x30, 0x0C, 0x06, 0x08, 0x2A, 0x86,
                   0x48, 0x86, 0xF7, 0x0D, 0x02, 0x02, 0x05, 0x00,
                   0x04, 0x10

       MD5:        0x30, 0x20, 0x30, 0x0C, 0x06, 0x08, 0x2A, 0x86,
                   0x48, 0x86, 0xF7, 0x0D, 0x02, 0x05, 0x05, 0x00,
                   0x04, 0x10

       RIPEMD-160: 0x30, 0x21, 0x30, 0x09, 0x06, 0x05, 0x2B, 0x24,
                   0x03, 0x02, 0x01, 0x05, 0x00, 0x04, 0x14

       SHA-1:      0x30, 0x21, 0x30, 0x09, 0x06, 0x05, 0x2b, 0x0E,
                   0x03, 0x02, 0x1A, 0x05, 0x00, 0x04, 0x14

   DSA signatures MUST use hashes with a size of 160 bits, to match q,
   the size of the group generated by the DSA key's generator value.
   The hash function result is treated as a 160 bit number and used
   directly in the DSA signature algorithm.

5.2.3. Version 4 Signature Packet Format

   The body of a version 4 Signature Packet contains:

     - One-octet version number (4).

     - One-octet signature type.

     - One-octet public key algorithm.

     - One-octet hash algorithm.

     - Two-octet scalar octet count for following hashed subpacket
       data. Note that this is the length in octets of all of the hashed
       subpackets; a pointer incremented by this number will skip over
       the hashed subpackets.




Callas, et. al.             Standards Track                    [Page 21]

RFC 2440                 OpenPGP Message Format            November 1998


     - Hashed subpacket data. (zero or more subpackets)

     - Two-octet scalar octet count for following unhashed subpacket
       data. Note that this is the length in octets of all of the
       unhashed subpackets; a pointer incremented by this number will
       skip over the unhashed subpackets.

     - Unhashed subpacket data. (zero or more subpackets)

     - Two-octet field holding left 16 bits of signed hash value.

     - One or more multi-precision integers comprising the signature.
       This portion is algorithm specific, as described above.

   The data being signed is hashed, and then the signature data from the
   version number through the hashed subpacket data (inclusive) is
   hashed. The resulting hash value is what is signed.  The left 16 bits
   of the hash are included in the signature packet to provide a quick
   test to reject some invalid signatures.

   There are two fields consisting of signature subpackets.  The first
   field is hashed with the rest of the signature data, while the second
   is unhashed.  The second set of subpackets is not cryptographically
   protected by the signature and should include only advisory
   information.

   The algorithms for converting the hash function result to a signature
   are described in a section below.

5.2.3.1. Signature Subpacket Specification

   The subpacket fields consist of zero or more signature subpackets.
   Each set of subpackets is preceded by a two-octet scalar count of the
   length of the set of subpackets.

   Each subpacket consists of a subpacket header and a body.  The header
   consists of:

     - the subpacket length (1,  2, or 5 octets)

     - the subpacket type (1 octet)

   and is followed by the subpacket specific data.

   The length includes the type octet but not this length. Its format is
   similar to the "new" format packet header lengths, but cannot have
   partial body lengths. That is:




Callas, et. al.             Standards Track                    [Page 22]

RFC 2440                 OpenPGP Message Format            November 1998


       if the 1st octet <  192, then
           lengthOfLength = 1
           subpacketLen = 1st_octet

       if the 1st octet >= 192 and < 255, then
           lengthOfLength = 2
           subpacketLen = ((1st_octet - 192) << 8) + (2nd_octet) + 192

       if the 1st octet = 255, then
           lengthOfLength = 5
           subpacket length = [four-octet scalar starting at 2nd_octet]

   The value of the subpacket type octet may be:

       2 = signature creation time
       3 = signature expiration time
       4 = exportable certification
       5 = trust signature
       6 = regular expression
       7 = revocable
       9 = key expiration time
       10 = placeholder for backward compatibility
       11 = preferred symmetric algorithms
       12 = revocation key
       16 = issuer key ID
       20 = notation data
       21 = preferred hash algorithms
       22 = preferred compression algorithms
       23 = key server preferences
       24 = preferred key server
       25 = primary user id
       26 = policy URL
       27 = key flags
       28 = signer's user id
       29 = reason for revocation
       100 to 110 = internal or user-defined

   An implementation SHOULD ignore any subpacket of a type that it does
   not recognize.

   Bit 7 of the subpacket type is the "critical" bit.  If set, it
   denotes that the subpacket is one that is critical for the evaluator
   of the signature to recognize.  If a subpacket is encountered that is
   marked critical but is unknown to the evaluating software, the
   evaluator SHOULD consider the signature to be in error.






Callas, et. al.             Standards Track                    [Page 23]

RFC 2440                 OpenPGP Message Format            November 1998


   An evaluator may "recognize" a subpacket, but not implement it. The
   purpose of the critical bit is to allow the signer to tell an
   evaluator that it would prefer a new, unknown feature to generate an
   error than be ignored.

   Implementations SHOULD implement "preferences".

5.2.3.2. Signature Subpacket Types

   A number of subpackets are currently defined.  Some subpackets apply
   to the signature itself and some are attributes of the key.
   Subpackets that are found on a self-signature are placed on a user id
   certification made by the key itself. Note that a key may have more
   than one user id, and thus may have more than one self-signature, and
   differing subpackets.

   A self-signature is a binding signature made by the key the signature
   refers to. There are three types of self-signatures, the
   certification signatures (types 0x10-0x13), the direct-key signature
   (type 0x1f), and the subkey binding signature (type 0x18). For
   certification self-signatures, each user ID may have a self-
   signature, and thus different subpackets in those self-signatures.
   For subkey binding signatures, each subkey in fact has a self-
   signature. Subpackets that appear in a certification self-signature
   apply to the username, and subpackets that appear in the subkey
   self-signature apply to the subkey. Lastly, subpackets on the direct
   key signature apply to the entire key.

   Implementing software should interpret a self-signature's preference
   subpackets as narrowly as possible. For example, suppose a key has
   two usernames, Alice and Bob. Suppose that Alice prefers the
   symmetric algorithm CAST5, and Bob prefers IDEA or Triple-DES. If the
   software locates this key via Alice's name, then the preferred
   algorithm is CAST5, if software locates the key via Bob's name, then
   the preferred algorithm is IDEA. If the key is located by key id,
   then algorithm of the default user id of the key provides the default
   symmetric algorithm.

   A subpacket may be found either in the hashed or unhashed subpacket
   sections of a signature. If a subpacket is not hashed, then the
   information in it cannot be considered definitive because it is not
   part of the signature proper.









Callas, et. al.             Standards Track                    [Page 24]

RFC 2440                 OpenPGP Message Format            November 1998


5.2.3.3. Signature creation time

   (4 octet time field)

   The time the signature was made.

   MUST be present in the hashed area.

5.2.3.4. Issuer

   (8 octet key ID)

   The OpenPGP key ID of the key issuing the signature.

5.2.3.5. Key expiration time

   (4 octet time field)

   The validity period of the key.  This is the number of seconds after
   the key creation time that the key expires.  If this is not present
   or has a value of zero, the key never expires. This is found only on
   a self-signature.

5.2.3.6. Preferred symmetric algorithms

   (sequence of one-octet values)

   Symmetric algorithm numbers that indicate which algorithms the key
   holder prefers to use.  The subpacket body is an ordered list of
   octets with the most preferred listed first. It is assumed that only
   algorithms listed are supported by the recipient's software.
   Algorithm numbers in section 9. This is only found on a self-
   signature.

5.2.3.7. Preferred hash algorithms

   (array of one-octet values)

   Message digest algorithm numbers that indicate which algorithms the
   key holder prefers to receive. Like the preferred symmetric
   algorithms, the list is ordered. Algorithm numbers are in section 6.
   This is only found on a self-signature.









Callas, et. al.             Standards Track                    [Page 25]

RFC 2440                 OpenPGP Message Format            November 1998


5.2.3.8. Preferred compression algorithms

   (array of one-octet values)

   Compression algorithm numbers that indicate which algorithms the key
   holder prefers to use. Like the preferred symmetric algorithms, the
   list is ordered. Algorithm numbers are in section 6. If this
   subpacket is not included, ZIP is preferred. A zero denotes that
   uncompressed data is preferred; the key holder's software might have
   no compression software in that implementation. This is only found on
   a self-signature.

5.2.3.9. Signature expiration time

   (4 octet time field)

   The validity period of the signature.  This is the number of seconds
   after the signature creation time that the signature expires. If this
   is not present or has a value of zero, it never expires.

5.2.3.10. Exportable Certification

   (1 octet of exportability, 0 for not, 1 for exportable)

   This subpacket denotes whether a certification signature is
   "exportable", to be used by other users than the signature's issuer.
   The packet body contains a boolean flag indicating whether the
   signature is exportable. If this packet is not present, the
   certification is exportable; it is equivalent to a flag containing a
   1.

   Non-exportable, or "local", certifications are signatures made by a
   user to mark a key as valid within that user's implementation only.
   Thus, when an implementation prepares a user's copy of a key for
   transport to another user (this is the process of "exporting" the
   key), any local certification signatures are deleted from the key.

   The receiver of a transported key "imports" it, and likewise trims
   any local certifications. In normal operation, there won't be any,
   assuming the import is performed on an exported key. However, there
   are instances where this can reasonably happen. For example, if an
   implementation allows keys to be imported from a key database in
   addition to an exported key, then this situation can arise.

   Some implementations do not represent the interest of a single user
   (for example, a key server). Such implementations always trim local
   certifications from any key they handle.




Callas, et. al.             Standards Track                    [Page 26]

RFC 2440                 OpenPGP Message Format            November 1998


5.2.3.11. Revocable

   (1 octet of revocability, 0 for not, 1 for revocable)

   Signature's revocability status.  Packet body contains a boolean flag
   indicating whether the signature is revocable.  Signatures that are
   not revocable have any later revocation signatures ignored.  They
   represent a commitment by the signer that he cannot revoke his
   signature for the life of his key.  If this packet is not present,
   the signature is revocable.

5.2.3.12. Trust signature

   (1 octet "level" (depth), 1 octet of trust amount)

   Signer asserts that the key is not only valid, but also trustworthy,
   at the specified level.  Level 0 has the same meaning as an ordinary
   validity signature.  Level 1 means that the signed key is asserted to
   be a valid trusted introducer, with the 2nd octet of the body
   specifying the degree of trust. Level 2 means that the signed key is
   asserted to be trusted to issue level 1 trust signatures, i.e. that
   it is a "meta introducer". Generally, a level n trust signature
   asserts that a key is trusted to issue level n-1 trust signatures.
   The trust amount is in a range from 0-255, interpreted such that
   values less than 120 indicate partial trust and values of 120 or
   greater indicate complete trust.  Implementations SHOULD emit values
   of 60 for partial trust and 120 for complete trust.

5.2.3.13. Regular expression

   (null-terminated regular expression)

   Used in conjunction with trust signature packets (of level > 0) to
   limit the scope of trust that is extended.  Only signatures by the
   target key on user IDs that match the regular expression in the body
   of this packet have trust extended by the trust signature subpacket.
   The regular expression uses the same syntax as the Henry Spencer's
   "almost public domain" regular expression package. A description of
   the syntax is found in a section below.

5.2.3.14. Revocation key

   (1 octet of class, 1 octet of algid, 20 octets of fingerprint)

   Authorizes the specified key to issue revocation signatures for this
   key.  Class octet must have bit 0x80 set. If the bit 0x40 is set,
   then this means that the revocation information is sensitive.  Other
   bits are for future expansion to other kinds of authorizations. This



Callas, et. al.             Standards Track                    [Page 27]

RFC 2440                 OpenPGP Message Format            November 1998


   is found on a self-signature.

   If the "sensitive" flag is set, the keyholder feels this subpacket
   contains private trust information that describes a real-world
   sensitive relationship. If this flag is set, implementations SHOULD
   NOT export this signature to other users except in cases where the
   data needs to be available: when the signature is being sent to the
   designated revoker, or when it is accompanied by a revocation
   signature from that revoker.  Note that it may be appropriate to
   isolate this subpacket within a separate signature so that it is not
   combined with other subpackets that need to be exported.

5.2.3.15. Notation Data

       (4 octets of flags, 2 octets of name length (M),
                           2 octets of value length (N),
                           M octets of name data,
                           N octets of value data)

   This subpacket describes a "notation" on the signature that the
   issuer wishes to make. The notation has a name and a value, each of
   which are strings of octets. There may be more than one notation in a
   signature. Notations can be used for any extension the issuer of the
   signature cares to make. The "flags" field holds four octets of
   flags.

   All undefined flags MUST be zero. Defined flags are:

       First octet: 0x80 = human-readable. This note is text, a note
                           from one person to another, and has no
                           meaning to software.
       Other octets: none.

5.2.3.16. Key server preferences

   (N octets of flags)

   This is a list of flags that indicate preferences that the key holder
   has about how the key is handled on a key server. All undefined flags
   MUST be zero.

   First octet: 0x80 = No-modify
       the key holder requests that this key only be modified or updated
       by the key holder or an administrator of the key server.

   This is found only on a self-signature.





Callas, et. al.             Standards Track                    [Page 28]

RFC 2440                 OpenPGP Message Format            November 1998


5.2.3.17. Preferred key server

   (String)

   This is a URL of a key server that the key holder prefers be used for
   updates. Note that keys with multiple user ids can have a preferred
   key server for each user id. Note also that since this is a URL, the
   key server can actually be a copy of the key retrieved by ftp, http,
   finger, etc.

5.2.3.18. Primary user id

   (1 octet, boolean)

   This is a flag in a user id's self signature that states whether this
   user id is the main user id for this key. It is reasonable for an
   implementation to resolve ambiguities in preferences, etc. by
   referring to the primary user id. If this flag is absent, its value
   is zero. If more than one user id in a key is marked as primary, the
   implementation may resolve the ambiguity in any way it sees fit.

5.2.3.19. Policy URL

   (String)

   This subpacket contains a URL of a document that describes the policy
   that the signature was issued under.

5.2.3.20. Key Flags

   (Octet string)

   This subpacket contains a list of binary flags that hold information
   about a key. It is a string of octets, and an implementation MUST NOT
   assume a fixed size. This is so it can grow over time. If a list is
   shorter than an implementation expects, the unstated flags are
   considered to be zero. The defined flags are:

       First octet:

       0x01 - This key may be used to certify other keys.

       0x02 - This key may be used to sign data.

       0x04 - This key may be used to encrypt communications.

       0x08 - This key may be used to encrypt storage.




Callas, et. al.             Standards Track                    [Page 29]

RFC 2440                 OpenPGP Message Format            November 1998


       0x10 - The private component of this key may have been split by a
       secret-sharing mechanism.

       0x80 - The private component of this key may be in the possession
       of more than one person.

   Usage notes:

   The flags in this packet may appear in self-signatures or in
   certification signatures. They mean different things depending on who
   is making the statement -- for example, a certification signature
   that has the "sign data" flag is stating that the certification is
   for that use. On the other hand, the "communications encryption" flag
   in a self-signature is stating a preference that a given key be used
   for communications. Note however, that it is a thorny issue to
   determine what is "communications" and what is "storage." This
   decision is left wholly up to the implementation; the authors of this
   document do not claim any special wisdom on the issue, and realize
   that accepted opinion may change.

   The "split key" (0x10) and "group key" (0x80) flags are placed on a
   self-signature only; they are meaningless on a certification
   signature. They SHOULD be placed only on a direct-key signature (type
   0x1f) or a subkey signature (type 0x18), one that refers to the key
   the flag applies to.

5.2.3.21. Signer's User ID

   This subpacket allows a keyholder to state which user id is
   responsible for the signing. Many keyholders use a single key for
   different purposes, such as business communications as well as
   personal communications. This subpacket allows such a keyholder to
   state which of their roles is making a signature.

5.2.3.22. Reason for Revocation

   (1 octet of revocation code, N octets of reason string)

   This subpacket is used only in key revocation and certification
   revocation signatures. It describes the reason why the key or
   certificate was revoked.

   The first octet contains a machine-readable code that denotes the
   reason for the revocation:







Callas, et. al.             Standards Track                    [Page 30]

RFC 2440                 OpenPGP Message Format            November 1998


       0x00 - No reason specified (key revocations or cert revocations)
       0x01 - Key is superceded (key revocations)
       0x02 - Key material has been compromised (key revocations)
       0x03 - Key is no longer used (key revocations)
       0x20 - User id information is no longer valid (cert revocations)

   Following the revocation code is a string of octets which gives
   information about the reason for revocation in human-readable form
   (UTF-8). The string may be null, that is, of zero length. The length
   of the subpacket is the length of the reason string plus one.

5.2.4. Computing Signatures

   All signatures are formed by producing a hash over the signature
   data, and then using the resulting hash in the signature algorithm.

   The signature data is simple to compute for document signatures
   (types 0x00 and 0x01), for which the document itself is the data.
   For standalone signatures, this is a null string.

   When a signature is made over a key, the hash data starts with the
   octet 0x99, followed by a two-octet length of the key, and then body
   of the key packet. (Note that this is an old-style packet header for
   a key packet with two-octet length.) A subkey signature (type 0x18)
   then hashes the subkey, using the same format as the main key. Key
   revocation signatures (types 0x20 and 0x28) hash only the key being
   revoked.

   A certification signature (type 0x10 through 0x13) hashes the user id
   being bound to the key into the hash context after the above data. A
   V3 certification hashes the contents of the name packet, without any
   header. A V4 certification hashes the constant 0xb4 (which is an
   old-style packet header with the length-of-length set to zero), a
   four-octet number giving the length of the username, and then the
   username data.

   Once the data body is hashed, then a trailer is hashed. A V3
   signature hashes five octets of the packet body, starting from the
   signature type field. This data is the signature type, followed by
   the four-octet signature time. A V4 signature hashes the packet body
   starting from its first field, the version number, through the end of
   the hashed subpacket data. Thus, the fields hashed are the signature
   version, the signature type, the public key algorithm, the hash
   algorithm, the hashed subpacket length, and the hashed subpacket
   body.






Callas, et. al.             Standards Track                    [Page 31]

RFC 2440                 OpenPGP Message Format            November 1998


   V4 signatures also hash in a final trailer of six octets: the version
   of the signature packet, i.e. 0x04; 0xFF; a four-octet, big-endian
   number that is the length of the hashed data from the signature
   packet (note that this number does not include these final six
   octets.

   After all this has been hashed, the resulting hash field is used in
   the signature algorithm, and placed at the end of the signature
   packet.

5.2.4.1. Subpacket Hints

   An implementation SHOULD put the two mandatory subpackets, creation
   time and issuer, as the first subpackets in the subpacket list,
   simply to make it easier for the implementer to find them.

   It is certainly possible for a signature to contain conflicting
   information in subpackets. For example, a signature may contain
   multiple copies of a preference or multiple expiration times. In most
   cases, an implementation SHOULD use the last subpacket in the
   signature, but MAY use any conflict resolution scheme that makes more
   sense. Please note that we are intentionally leaving conflict
   resolution to the implementer; most conflicts are simply syntax
   errors, and the wishy-washy language here allows a receiver to be
   generous in what they accept, while putting pressure on a creator to
   be stingy in what they generate.

   Some apparent conflicts may actually make sense -- for example,
   suppose a keyholder has an V3 key and a V4 key that share the same
   RSA key material. Either of these keys can verify a signature created
   by the other, and it may be reasonable for a signature to contain an
   issuer subpacket for each key, as a way of explicitly tying those
   keys to the signature.

5.3. Symmetric-Key Encrypted Session-Key Packets (Tag 3)

   The Symmetric-Key Encrypted Session Key packet holds the symmetric-
   key encryption of a session key used to encrypt a message.  Zero or
   more Encrypted Session Key packets and/or Symmetric-Key Encrypted
   Session Key packets may precede a Symmetrically Encrypted Data Packet
   that holds an encrypted message.  The message is encrypted with a
   session key, and the session key is itself encrypted and stored in
   the Encrypted Session Key packet or the Symmetric-Key Encrypted
   Session Key packet.

   If the Symmetrically Encrypted Data Packet is preceded by one or more
   Symmetric-Key Encrypted Session Key packets, each specifies a
   passphrase that may be used to decrypt the message.  This allows a



Callas, et. al.             Standards Track                    [Page 32]

RFC 2440                 OpenPGP Message Format            November 1998


   message to be encrypted to a number of public keys, and also to one
   or more pass phrases. This packet type is new, and is not generated
   by PGP 2.x or PGP 5.0.

   The body of this packet consists of:

     - A one-octet version number. The only currently defined version
       is 4.

     - A one-octet number describing the symmetric algorithm used.

     - A string-to-key (S2K) specifier, length as defined above.

     - Optionally, the encrypted session key itself, which is decrypted
       with the string-to-key object.

   If the encrypted session key is not present (which can be detected on
   the basis of packet length and S2K specifier size), then the S2K
   algorithm applied to the passphrase produces the session key for
   decrypting the file, using the symmetric cipher algorithm from the
   Symmetric-Key Encrypted Session Key packet.

   If the encrypted session key is present, the result of applying the
   S2K algorithm to the passphrase is used to decrypt just that
   encrypted session key field, using CFB mode with an IV of all zeros.
    The decryption result consists of a one-octet algorithm identifier
   that specifies the symmetric-key encryption algorithm used to encrypt
   the following Symmetrically Encrypted Data Packet, followed by the
   session key octets themselves.

   Note: because an all-zero IV is used for this decryption, the S2K
   specifier MUST use a salt value, either a Salted S2K or an Iterated-
   Salted S2K.  The salt value will insure that the decryption key is
   not repeated even if the passphrase is reused.

5.4. One-Pass Signature Packets (Tag 4)

   The One-Pass Signature packet precedes the signed data and contains
   enough information to allow the receiver to begin calculating any
   hashes needed to verify the signature.  It allows the Signature
   Packet to be placed at the end of the message, so that the signer can
   compute the entire signed message in one pass.

   A One-Pass Signature does not interoperate with PGP 2.6.x or earlier.

   The body of this packet consists of:





Callas, et. al.             Standards Track                    [Page 33]

RFC 2440                 OpenPGP Message Format            November 1998


     - A one-octet version number. The current version is 3.

     - A one-octet signature type. Signature types are described in
       section 5.2.1.

     - A one-octet number describing the hash algorithm used.

     - A one-octet number describing the public key algorithm used.

     - An eight-octet number holding the key ID of the signing key.

     - A one-octet number holding a flag showing whether the signature
       is nested.  A zero value indicates that the next packet is
       another One-Pass Signature packet that describes another
       signature to be applied to the same message data.

   Note that if a message contains more than one one-pass signature,
   then the signature packets bracket the message; that is, the first
   signature packet after the message corresponds to the last one-pass
   packet and the final signature packet corresponds to the first one-
   pass packet.

5.5. Key Material Packet

   A key material packet contains all the information about a public or
   private key.  There are four variants of this packet type, and two
   major versions. Consequently, this section is complex.

5.5.1. Key Packet Variants

5.5.1.1. Public Key Packet (Tag 6)

   A Public Key packet starts a series of packets that forms an OpenPGP
   key (sometimes called an OpenPGP certificate).

5.5.1.2. Public Subkey Packet (Tag 14)

   A Public Subkey packet (tag 14) has exactly the same format as a
   Public Key packet, but denotes a subkey. One or more subkeys may be
   associated with a top-level key.  By convention, the top-level key
   provides signature services, and the subkeys provide encryption
   services.

   Note: in PGP 2.6.x, tag 14 was intended to indicate a comment packet.
   This tag was selected for reuse because no previous version of PGP
   ever emitted comment packets but they did properly ignore them.
   Public Subkey packets are ignored by PGP 2.6.x and do not cause it to
   fail, providing a limited degree of backward compatibility.



Callas, et. al.             Standards Track                    [Page 34]

RFC 2440                 OpenPGP Message Format            November 1998


5.5.1.3. Secret Key Packet (Tag 5)

   A Secret Key packet contains all the information that is found in a
   Public Key packet, including the public key material, but also
   includes the secret key material after all the public key fields.

5.5.1.4. Secret Subkey Packet (Tag 7)

   A Secret Subkey packet (tag 7) is the subkey analog of the Secret Key
   packet, and has exactly the same format.

5.5.2. Public Key Packet Formats

   There are two versions of key-material packets. Version 3 packets
   were first generated by PGP 2.6. Version 2 packets are identical in
   format to Version 3 packets, but are generated by PGP 2.5 or before.
   V2 packets are deprecated and they MUST NOT be generated.  PGP 5.0
   introduced version 4 packets, with new fields and semantics.  PGP
   2.6.x will not accept key-material packets with versions greater than
   3.

   OpenPGP implementations SHOULD create keys with version 4 format. An
   implementation MAY generate a V3 key to ensure interoperability with
   old software; note, however, that V4 keys correct some security
   deficiencies in V3 keys. These deficiencies are described below. An
   implementation MUST NOT create a V3 key with a public key algorithm
   other than RSA.

   A version 3 public key or public subkey packet contains:

     - A one-octet version number (3).

     - A four-octet number denoting the time that the key was created.

     - A two-octet number denoting the time in days that this key is
       valid. If this number is zero, then it does not expire.

     - A one-octet number denoting the public key algorithm of this key

     - A series of multi-precision integers comprising the key
       material:

         - a multiprecision integer (MPI) of RSA public modulus n;

         - an MPI of RSA public encryption exponent e.






Callas, et. al.             Standards Track                    [Page 35]

RFC 2440                 OpenPGP Message Format            November 1998


   V3 keys SHOULD only be used for backward compatibility because of
   three weaknesses in them. First, it is relatively easy to construct a
   V3 key that has the same key ID as any other key because the key ID
   is simply the low 64 bits of the public modulus. Secondly, because
   the fingerprint of a V3 key hashes the key material, but not its
   length, which increases the opportunity for fingerprint collisions.
   Third, there are minor weaknesses in the MD5 hash algorithm that make
   developers prefer other algorithms. See below for a fuller discussion
   of key IDs and fingerprints.

   The version 4 format is similar to the version 3 format except for
   the absence of a validity period.  This has been moved to the
   signature packet.  In addition, fingerprints of version 4 keys are
   calculated differently from version 3 keys, as described in section
   "Enhanced Key Formats."

   A version 4 packet contains:

     - A one-octet version number (4).

     - A four-octet number denoting the time that the key was created.

     - A one-octet number denoting the public key algorithm of this key

     - A series of multi-precision integers comprising the key
       material.  This algorithm-specific portion is:

       Algorithm Specific Fields for RSA public keys:

         - multiprecision integer (MPI) of RSA public modulus n;

         - MPI of RSA public encryption exponent e.

       Algorithm Specific Fields for DSA public keys:

         - MPI of DSA prime p;

         - MPI of DSA group order q (q is a prime divisor of p-1);

         - MPI of DSA group generator g;

         - MPI of DSA public key value y (= g**x where x is secret).

       Algorithm Specific Fields for Elgamal public keys:

         - MPI of Elgamal prime p;

         - MPI of Elgamal group generator g;



Callas, et. al.             Standards Track                    [Page 36]

RFC 2440                 OpenPGP Message Format            November 1998


         - MPI of Elgamal public key value y (= g**x where x is
           secret).

5.5.3. Secret Key Packet Formats

   The Secret Key and Secret Subkey packets contain all the data of the
   Public Key and Public Subkey packets, with additional algorithm-
   specific secret key data appended, in encrypted form.

   The packet contains:

     - A Public Key or Public Subkey packet, as described above

     - One octet indicating string-to-key usage conventions.  0
       indicates that the secret key data is not encrypted.  255
       indicates that a string-to-key specifier is being given.  Any
       other value is a symmetric-key encryption algorithm specifier.

     - [Optional] If string-to-key usage octet was 255, a one-octet
       symmetric encryption algorithm.

     - [Optional] If string-to-key usage octet was 255, a string-to-key
       specifier.  The length of the string-to-key specifier is implied
       by its type, as described above.

     - [Optional] If secret data is encrypted, eight-octet Initial
       Vector (IV).

     - Encrypted multi-precision integers comprising the secret key
       data. These algorithm-specific fields are as described below.

     - Two-octet checksum of the plaintext of the algorithm-specific
       portion (sum of all octets, mod 65536).

       Algorithm Specific Fields for RSA secret keys:

       - multiprecision integer (MPI) of RSA secret exponent d.

       - MPI of RSA secret prime value p.

       - MPI of RSA secret prime value q (p < q).

       - MPI of u, the multiplicative inverse of p, mod q.

       Algorithm Specific Fields for DSA secret keys:

       - MPI of DSA secret exponent x.




Callas, et. al.             Standards Track                    [Page 37]

RFC 2440                 OpenPGP Message Format            November 1998


       Algorithm Specific Fields for Elgamal secret keys:

       - MPI of Elgamal secret exponent x.

   Secret MPI values can be encrypted using a passphrase.  If a string-
   to-key specifier is given, that describes the algorithm for
   converting the passphrase to a key, else a simple MD5 hash of the
   passphrase is used.  Implementations SHOULD use a string-to-key
   specifier; the simple hash is for backward compatibility. The cipher
   for encrypting the MPIs is specified in the secret key packet.

   Encryption/decryption of the secret data is done in CFB mode using
   the key created from the passphrase and the Initial Vector from the
   packet. A different mode is used with V3 keys (which are only RSA)
   than with other key formats. With V3 keys, the MPI bit count prefix
   (i.e., the first two octets) is not encrypted.  Only the MPI non-
   prefix data is encrypted.  Furthermore, the CFB state is
   resynchronized at the beginning of each new MPI value, so that the
   CFB block boundary is aligned with the start of the MPI data.

   With V4 keys, a simpler method is used.  All secret MPI values are
   encrypted in CFB mode, including the MPI bitcount prefix.

   The 16-bit checksum that follows the algorithm-specific portion is
   the algebraic sum, mod 65536, of the plaintext of all the algorithm-
   specific octets (including MPI prefix and data).  With V3 keys, the
   checksum is stored in the clear.  With V4 keys, the checksum is
   encrypted like the algorithm-specific data.  This value is used to
   check that the passphrase was correct.

5.6. Compressed Data Packet (Tag 8)

   The Compressed Data packet contains compressed data. Typically, this
   packet is found as the contents of an encrypted packet, or following
   a Signature or One-Pass Signature packet, and contains literal data
   packets.

   The body of this packet consists of:

     - One octet that gives the algorithm used to compress the packet.

     - The remainder of the packet is compressed data.

   A Compressed Data Packet's body contains an block that compresses
   some set of packets. See section "Packet Composition" for details on
   how messages are formed.





Callas, et. al.             Standards Track                    [Page 38]

RFC 2440                 OpenPGP Message Format            November 1998


   ZIP-compressed packets are compressed with raw RFC 1951 DEFLATE
   blocks. Note that PGP V2.6 uses 13 bits of compression. If an
   implementation uses more bits of compression, PGP V2.6 cannot
   decompress it.

   ZLIB-compressed packets are compressed with RFC 1950 ZLIB-style
   blocks.

5.7. Symmetrically Encrypted Data Packet (Tag 9)

   The Symmetrically Encrypted Data packet contains data encrypted with
   a symmetric-key algorithm. When it has been decrypted, it will
   typically contain other packets (often literal data packets or
   compressed data packets).

   The body of this packet consists of:

     - Encrypted data, the output of the selected symmetric-key cipher
       operating in PGP's variant of Cipher Feedback (CFB) mode.

   The symmetric cipher used may be specified in an Public-Key or
   Symmetric-Key Encrypted Session Key packet that precedes the
   Symmetrically Encrypted Data Packet.  In that case, the cipher
   algorithm octet is prefixed to the session key before it is
   encrypted.  If no packets of these types precede the encrypted data,
   the IDEA algorithm is used with the session key calculated as the MD5
   hash of the passphrase.

   The data is encrypted in CFB mode, with a CFB shift size equal to the
   cipher's block size.  The Initial Vector (IV) is specified as all
   zeros.  Instead of using an IV, OpenPGP prefixes a 10-octet string to
   the data before it is encrypted.  The first eight octets are random,
   and the 9th and 10th octets are copies of the 7th and 8th octets,
   respectively. After encrypting the first 10 octets, the CFB state is
   resynchronized if the cipher block size is 8 octets or less.  The
   last 8 octets of ciphertext are passed through the cipher and the
   block boundary is reset.

   The repetition of 16 bits in the 80 bits of random data prefixed to
   the message allows the receiver to immediately check whether the
   session key is incorrect.

5.8. Marker Packet (Obsolete Literal Packet) (Tag 10)

   An experimental version of PGP used this packet as the Literal
   packet, but no released version of PGP generated Literal packets with
   this tag. With PGP 5.x, this packet has been re-assigned and is
   reserved for use as the Marker packet.



Callas, et. al.             Standards Track                    [Page 39]

RFC 2440                 OpenPGP Message Format            November 1998


   The body of this packet consists of:

     - The three octets 0x50, 0x47, 0x50 (which spell "PGP" in UTF-8).

   Such a packet MUST be ignored when received.  It may be placed at the
   beginning of a message that uses features not available in PGP 2.6.x
   in order to cause that version to report that newer software is
   necessary to process the message.

5.9. Literal Data Packet (Tag 11)

   A Literal Data packet contains the body of a message; data that is
   not to be further interpreted.

   The body of this packet consists of:

     - A one-octet field that describes how the data is formatted.

   If it is a 'b' (0x62), then the literal packet contains binary data.
   If it is a 't' (0x74), then it contains text data, and thus may need
   line ends converted to local form, or other text-mode changes.  RFC
   1991 also defined a value of 'l' as a 'local' mode for machine-local
   conversions.  This use is now deprecated.

     - File name as a string (one-octet length, followed by file name),
       if the encrypted data should be saved as a file.

   If the special name "_CONSOLE" is used, the message is considered to
   be "for your eyes only".  This advises that the message data is
   unusually sensitive, and the receiving program should process it more
   carefully, perhaps avoiding storing the received data to disk, for
   example.

     - A four-octet number that indicates the modification date of the
       file, or the creation time of the packet, or a zero that
       indicates the present time.

     - The remainder of the packet is literal data.

   Text data is stored with <CR><LF> text endings (i.e. network-normal
   line endings).  These should be converted to native line endings by
   the receiving software.

5.10. Trust Packet (Tag 12)

   The Trust packet is used only within keyrings and is not normally
   exported.  Trust packets contain data that record the user's
   specifications of which key holders are trustworthy introducers,



Callas, et. al.             Standards Track                    [Page 40]

RFC 2440                 OpenPGP Message Format            November 1998


   along with other information that implementing software uses for
   trust information.

   Trust packets SHOULD NOT be emitted to output streams that are
   transferred to other users, and they SHOULD be ignored on any input
   other than local keyring files.

5.11. User ID Packet (Tag 13)

   A User ID packet consists of data that is intended to represent the
   name and email address of the key holder.  By convention, it includes
   an RFC 822 mail name, but there are no restrictions on its content.
   The packet length in the header specifies the length of the user id.
   If it is text, it is encoded in UTF-8.

6. Radix-64 Conversions

   As stated in the introduction, OpenPGP's underlying native
   representation for objects is a stream of arbitrary octets, and some
   systems desire these objects to be immune to damage caused by
   character set translation, data conversions, etc.

   In principle, any printable encoding scheme that met the requirements
   of the unsafe channel would suffice, since it would not change the
   underlying binary bit streams of the native OpenPGP data structures.
   The OpenPGP standard specifies one such printable encoding scheme to
   ensure interoperability.

   OpenPGP's Radix-64 encoding is composed of two parts: a base64
   encoding of the binary data, and a checksum.  The base64 encoding is
   identical to the MIME base64 content-transfer-encoding [RFC2231,
   Section 6.8]. An OpenPGP implementation MAY use ASCII Armor to
   protect the raw binary data.

   The checksum is a 24-bit CRC converted to four characters of radix-64
   encoding by the same MIME base64 transformation, preceded by an
   equals sign (=).  The CRC is computed by using the generator 0x864CFB
   and an initialization of 0xB704CE.  The accumulation is done on the
   data before it is converted to radix-64, rather than on the converted
   data.  A sample implementation of this algorithm is in the next
   section.

   The checksum with its leading equal sign MAY appear on the first line
   after the Base64 encoded data.

   Rationale for CRC-24: The size of 24 bits fits evenly into printable
   base64.  The nonzero initialization can detect more errors than a
   zero initialization.



Callas, et. al.             Standards Track                    [Page 41]

RFC 2440                 OpenPGP Message Format            November 1998


6.1. An Implementation of the CRC-24 in "C"

       #define CRC24_INIT 0xb704ceL
       #define CRC24_POLY 0x1864cfbL

       typedef long crc24;
       crc24 crc_octets(unsigned char *octets, size_t len)
       {
           crc24 crc = CRC24_INIT;
           int i;

           while (len--) {
               crc ^= (*octets++) << 16;
               for (i = 0; i < 8; i++) {
                   crc <<= 1;
                   if (crc & 0x1000000)
                       crc ^= CRC24_POLY;
               }
           }
           return crc & 0xffffffL;
       }

6.2. Forming ASCII Armor

   When OpenPGP encodes data into ASCII Armor, it puts specific headers
   around the data, so OpenPGP can reconstruct the data later. OpenPGP
   informs the user what kind of data is encoded in the ASCII armor
   through the use of the headers.

   Concatenating the following data creates ASCII Armor:

     - An Armor Header Line, appropriate for the type of data

     - Armor Headers

     - A blank (zero-length, or containing only whitespace) line

     - The ASCII-Armored data

     - An Armor Checksum

     - The Armor Tail, which depends on the Armor Header Line.

   An Armor Header Line consists of the appropriate header line text
   surrounded by five (5) dashes ('-', 0x2D) on either side of the
   header line text.  The header line text is chosen based upon the type
   of data that is being encoded in Armor, and how it is being encoded.
   Header line texts include the following strings:



Callas, et. al.             Standards Track                    [Page 42]

RFC 2440                 OpenPGP Message Format            November 1998


   BEGIN PGP MESSAGE
       Used for signed, encrypted, or compressed files.

   BEGIN PGP PUBLIC KEY BLOCK
       Used for armoring public keys

   BEGIN PGP PRIVATE KEY BLOCK
       Used for armoring private keys

   BEGIN PGP MESSAGE, PART X/Y
       Used for multi-part messages, where the armor is split amongst Y
       parts, and this is the Xth part out of Y.

   BEGIN PGP MESSAGE, PART X
       Used for multi-part messages, where this is the Xth part of an
       unspecified number of parts. Requires the MESSAGE-ID Armor Header
       to be used.

   BEGIN PGP SIGNATURE
       Used for detached signatures, OpenPGP/MIME signatures, and
       natures following clearsigned messages. Note that PGP 2.x s BEGIN
       PGP MESSAGE for detached signatures.

   The Armor Headers are pairs of strings that can give the user or the
   receiving OpenPGP implementation some information about how to decode
   or use the message.  The Armor Headers are a part of the armor, not a
   part of the message, and hence are not protected by any signatures
   applied to the message.

   The format of an Armor Header is that of a key-value pair.  A colon
   (':' 0x38) and a single space (0x20) separate the key and value.
   OpenPGP should consider improperly formatted Armor Headers to be
   corruption of the ASCII Armor.  Unknown keys should be reported to
   the user, but OpenPGP should continue to process the message.

   Currently defined Armor Header Keys are:

     - "Version", that states the OpenPGP Version used to encode the
       message.

     - "Comment", a user-defined comment.

     - "MessageID", a 32-character string of printable characters.  The
       string must be the same for all parts of a multi-part message
       that uses the "PART X" Armor Header.  MessageID strings should be






Callas, et. al.             Standards Track                    [Page 43]

RFC 2440                 OpenPGP Message Format            November 1998


       unique enough that the recipient of the mail can associate all
       the parts of a message with each other. A good checksum or
       cryptographic hash function is sufficient.

     - "Hash", a comma-separated list of hash algorithms used in this
       message. This is used only in clear-signed messages.

     - "Charset", a description of the character set that the plaintext
       is in. Please note that OpenPGP defines text to be in UTF-8 by
       default. An implementation will get best results by translating
       into and out of UTF-8. However, there are many instances where
       this is easier said than done. Also, there are communities of
       users who have no need for UTF-8 because they are all happy with
       a character set like ISO Latin-5 or a Japanese character set. In
       such instances, an implementation MAY override the UTF-8 default
       by using this header key. An implementation MAY implement this
       key and any translations it cares to; an implementation MAY
       ignore it and assume all text is UTF-8.

       The MessageID SHOULD NOT appear unless it is in a multi-part
       message. If it appears at all, it MUST be computed from the
       finished (encrypted, signed, etc.) message in a deterministic
       fashion, rather than contain a purely random value.  This is to
       allow the legitimate recipient to determine that the MessageID
       cannot serve as a covert means of leaking cryptographic key
       information.

   The Armor Tail Line is composed in the same manner as the Armor
   Header Line, except the string "BEGIN" is replaced by the string
   "END."

6.3. Encoding Binary in Radix-64

   The encoding process represents 24-bit groups of input bits as output
   strings of 4 encoded characters. Proceeding from left to right, a
   24-bit input group is formed by concatenating three 8-bit input
   groups. These 24 bits are then treated as four concatenated 6-bit
   groups, each of which is translated into a single digit in the
   Radix-64 alphabet. When encoding a bit stream with the Radix-64
   encoding, the bit stream must be presumed to be ordered with the
   most-significant-bit first. That is, the first bit in the stream will
   be the high-order bit in the first 8-bit octet, and the eighth bit
   will be the low-order bit in the first 8-bit octet, and so on.








Callas, et. al.             Standards Track                    [Page 44]

RFC 2440                 OpenPGP Message Format            November 1998


         +--first octet--+-second octet--+--third octet--+
         |7 6 5 4 3 2 1 0|7 6 5 4 3 2 1 0|7 6 5 4 3 2 1 0|
         +-----------+---+-------+-------+---+-----------+
         |5 4 3 2 1 0|5 4 3 2 1 0|5 4 3 2 1 0|5 4 3 2 1 0|
         +--1.index--+--2.index--+--3.index--+--4.index--+

   Each 6-bit group is used as an index into an array of 64 printable
   characters from the table below. The character referenced by the
   index is placed in the output string.

     Value Encoding  Value Encoding  Value Encoding  Value Encoding
         0 A            17 R            34 i            51 z
         1 B            18 S            35 j            52 0
         2 C            19 T            36 k            53 1
         3 D            20 U            37 l            54 2
         4 E            21 V            38 m            55 3
         5 F            22 W            39 n            56 4
         6 G            23 X            40 o            57 5
         7 H            24 Y            41 p            58 6
         8 I            25 Z            42 q            59 7
         9 J            26 a            43 r            60 8
        10 K            27 b            44 s            61 9
        11 L            28 c            45 t            62 +
        12 M            29 d            46 u            63 /
        13 N            30 e            47 v
        14 O            31 f            48 w         (pad) =
        15 P            32 g            49 x
        16 Q            33 h            50 y

   The encoded output stream must be represented in lines of no more
   than 76 characters each.

   Special processing is performed if fewer than 24 bits are available
   at the end of the data being encoded. There are three possibilities:

    1. The last data group has 24 bits (3 octets). No special
       processing is needed.

    2. The last data group has 16 bits (2 octets). The first two 6-bit
       groups are processed as above. The third (incomplete) data group
       has two zero-value bits added to it, and is processed as above.
       A pad character (=) is added to the output.

    3. The last data group has 8 bits (1 octet). The first 6-bit group
       is processed as above. The second (incomplete) data group has
       four zero-value bits added to it, and is processed as above. Two
       pad characters (=) are added to the output.




Callas, et. al.             Standards Track                    [Page 45]

RFC 2440                 OpenPGP Message Format            November 1998


6.4. Decoding Radix-64

   Any characters outside of the base64 alphabet are ignored in Radix-64
   data. Decoding software must ignore all line breaks or other
   characters not found in the table above.

   In Radix-64 data, characters other than those in the table, line
   breaks, and other white space probably indicate a transmission error,
   about which a warning message or even a message rejection might be
   appropriate under some circumstances.

   Because it is used only for padding at the end of the data, the
   occurrence of any "=" characters may be taken as evidence that the
   end of the data has been reached (without truncation in transit). No
   such assurance is possible, however, when the number of octets
   transmitted was a multiple of three and no "=" characters are
   present.

6.5. Examples of Radix-64

       Input data:  0x14fb9c03d97e
       Hex:     1   4    f   b    9   c     | 0   3    d   9    7   e
       8-bit:   00010100 11111011 10011100  | 00000011 11011001
       11111110
       6-bit:   000101 001111 101110 011100 | 000000 111101 100111
       111110
       Decimal: 5      15     46     28       0      61     37     62
       Output:  F      P      u      c        A      9      l      +

       Input data:  0x14fb9c03d9
       Hex:     1   4    f   b    9   c     | 0   3    d   9
       8-bit:   00010100 11111011 10011100  | 00000011 11011001
                                                       pad with 00
       6-bit:   000101 001111 101110 011100 | 000000 111101 100100
       Decimal: 5      15     46     28       0      61     36
                                                          pad with =
       Output:  F      P      u      c        A      9      k      =

       Input data:  0x14fb9c03
       Hex:     1   4    f   b    9   c     | 0   3
       8-bit:   00010100 11111011 10011100  | 00000011
                                              pad with 0000
       6-bit:   000101 001111 101110 011100 | 000000 110000
       Decimal: 5      15     46     28       0      48
                                                   pad with =      =
       Output:  F      P      u      c        A      w      =      =





Callas, et. al.             Standards Track                    [Page 46]

RFC 2440                 OpenPGP Message Format            November 1998


6.6. Example of an ASCII Armored Message


  -----BEGIN PGP MESSAGE-----
  Version: OpenPrivacy 0.99

  yDgBO22WxBHv7O8X7O/jygAEzol56iUKiXmV+XmpCtmpqQUKiQrFqclFqUDBovzS
  vBSFjNSiVHsuAA==
  =njUN
  -----END PGP MESSAGE-----

   Note that this example is indented by two spaces.

7. Cleartext signature framework

   It is desirable to sign a textual octet stream without ASCII armoring
   the stream itself, so the signed text is still readable without
   special software. In order to bind a signature to such a cleartext,
   this framework is used.  (Note that RFC 2015 defines another way to
   clear sign messages for environments that support MIME.)

   The cleartext signed message consists of:

     - The cleartext header '-----BEGIN PGP SIGNED MESSAGE-----' on a
       single line,

     - One or more "Hash" Armor Headers,

     - Exactly one empty line not included into the message digest,

     - The dash-escaped cleartext that is included into the message
       digest,

     - The ASCII armored signature(s) including the '-----BEGIN PGP
       SIGNATURE-----' Armor Header and Armor Tail Lines.

   If the "Hash" armor header is given, the specified message digest
   algorithm is used for the signature. If there are no such headers,
   MD5 is used, an implementation MAY omit them for V2.x compatibility.
   If more than one message digest is used in the signature, the "Hash"
   armor header contains a comma-delimited list of used message digests.

   Current message digest names are described below with the algorithm
   IDs.

7.1. Dash-Escaped Text

   The cleartext content of the message must also be dash-escaped.



Callas, et. al.             Standards Track                    [Page 47]

RFC 2440                 OpenPGP Message Format            November 1998


   Dash escaped cleartext is the ordinary cleartext where every line
   starting with a dash '-' (0x2D) is prefixed by the sequence dash '-'
   (0x2D) and space ' ' (0x20). This prevents the parser from
   recognizing armor headers of the cleartext itself. The message digest
   is computed using the cleartext itself, not the dash escaped form.

   As with binary signatures on text documents, a cleartext signature is
   calculated on the text using canonical <CR><LF> line endings.  The
   line ending (i.e. the <CR><LF>) before the '-----BEGIN PGP
   SIGNATURE-----' line that terminates the signed text is not
   considered part of the signed text.

   Also, any trailing whitespace (spaces, and tabs, 0x09) at the end of
   any line is ignored when the cleartext signature is calculated.

8. Regular Expressions

   A regular expression is zero or more branches, separated by '|'. It
   matches anything that matches one of the branches.

   A branch is zero or more pieces, concatenated. It matches a match for
   the first, followed by a match for the second, etc.

   A piece is an atom possibly followed by '*', '+', or '?'. An atom
   followed by '*' matches a sequence of 0 or more matches of the atom.
   An atom followed by '+' matches a sequence of 1 or more matches of
   the atom. An atom followed by '?' matches a match of the atom, or the
   null string.

   An atom is a regular expression in parentheses (matching a match for
   the regular expression), a range (see below), '.' (matching any
   single character), '^' (matching the null string at the beginning of
   the input string), '$' (matching the null string at the end of the
   input string), a '\' followed by a single character (matching that
   character), or a single character with no other significance
   (matching that character).

   A range is a sequence of characters enclosed in '[]'. It normally
   matches any single character from the sequence. If the sequence
   begins with '^', it matches any single character not from the rest of
   the sequence. If two characters in the sequence are separated by '-',
   this is shorthand for the full list of ASCII characters between them
   (e.g. '[0-9]' matches any decimal digit). To include a literal ']' in
   the sequence, make it the first character (following a possible '^').
   To include a literal '-', make it the first or last character.






Callas, et. al.             Standards Track                    [Page 48]

RFC 2440                 OpenPGP Message Format            November 1998


9. Constants

   This section describes the constants used in OpenPGP.

   Note that these tables are not exhaustive lists; an implementation
   MAY implement an algorithm not on these lists.

   See the section "Notes on Algorithms" below for more discussion of
   the algorithms.

9.1. Public Key Algorithms

       ID           Algorithm
       --           ---------
       1          - RSA (Encrypt or Sign)
       2          - RSA Encrypt-Only
       3          - RSA Sign-Only
       16         - Elgamal (Encrypt-Only), see [ELGAMAL]
       17         - DSA (Digital Signature Standard)
       18         - Reserved for Elliptic Curve
       19         - Reserved for ECDSA
       20         - Elgamal (Encrypt or Sign)





       21         - Reserved for Diffie-Hellman (X9.42,
                    as defined for IETF-S/MIME)
       100 to 110 - Private/Experimental algorithm.

   Implementations MUST implement DSA for signatures, and Elgamal for
   encryption. Implementations SHOULD implement RSA keys.
   Implementations MAY implement any other algorithm.

9.2. Symmetric Key Algorithms

       ID           Algorithm
       --           ---------
       0          - Plaintext or unencrypted data
       1          - IDEA [IDEA]
       2          - Triple-DES (DES-EDE, as per spec -
                    168 bit key derived from 192)
       3          - CAST5 (128 bit key, as per RFC 2144)
       4          - Blowfish (128 bit key, 16 rounds) [BLOWFISH]
       5          - SAFER-SK128 (13 rounds) [SAFER]
       6          - Reserved for DES/SK
       7          - Reserved for AES with 128-bit key



Callas, et. al.             Standards Track                    [Page 49]

RFC 2440                 OpenPGP Message Format            November 1998


       8          - Reserved for AES with 192-bit key
       9          - Reserved for AES with 256-bit key
       100 to 110 - Private/Experimental algorithm.

   Implementations MUST implement Triple-DES. Implementations SHOULD
   implement IDEA and CAST5.Implementations MAY implement any other
   algorithm.

9.3. Compression Algorithms

       ID           Algorithm
       --           ---------
       0          - Uncompressed
       1          - ZIP (RFC 1951)
       2          - ZLIB (RFC 1950)
       100 to 110 - Private/Experimental algorithm.

   Implementations MUST implement uncompressed data. Implementations
   SHOULD implement ZIP. Implementations MAY implement ZLIB.

9.4. Hash Algorithms

       ID           Algorithm                              Text Name
       --           ---------                              ---- ----
       1          - MD5                                    "MD5"
       2          - SHA-1                                  "SHA1"
       3          - RIPE-MD/160                            "RIPEMD160"
       4          - Reserved for double-width SHA (experimental)
       5          - MD2                                    "MD2"
       6          - Reserved for TIGER/192                 "TIGER192"
       7          - Reserved for HAVAL (5 pass, 160-bit)
       "HAVAL-5-160"
       100 to 110 - Private/Experimental algorithm.

   Implementations MUST implement SHA-1. Implementations SHOULD
   implement MD5.

10. Packet Composition

   OpenPGP packets are assembled into sequences in order to create
   messages and to transfer keys.  Not all possible packet sequences are
   meaningful and correct.  This describes the rules for how packets
   should be placed into sequences.

10.1. Transferable Public Keys

   OpenPGP users may transfer public keys. The essential elements of a
   transferable public key are:



Callas, et. al.             Standards Track                    [Page 50]

RFC 2440                 OpenPGP Message Format            November 1998


     - One Public Key packet

     - Zero or more revocation signatures

     - One or more User ID packets

     - After each User ID packet, zero or more signature packets
       (certifications)

     - Zero or more Subkey packets

     - After each Subkey packet, one signature packet, optionally a
       revocation.

   The Public Key packet occurs first.  Each of the following User ID
   packets provides the identity of the owner of this public key.  If
   there are multiple User ID packets, this corresponds to multiple
   means of identifying the same unique individual user; for example, a
   user may have more than one email address, and construct a User ID
   for each one.

   Immediately following each User ID packet, there are zero or more
   signature packets. Each signature packet is calculated on the
   immediately preceding User ID packet and the initial Public Key
   packet. The signature serves to certify the corresponding public key
   and user ID.  In effect, the signer is testifying to his or her
   belief that this public key belongs to the user identified by this
   user ID.

   After the User ID packets there may be one or more Subkey packets.
   In general, subkeys are provided in cases where the top-level public
   key is a signature-only key.  However, any V4 key may have subkeys,
   and the subkeys may be encryption-only keys, signature-only keys, or
   general-purpose keys.

   Each Subkey packet must be followed by one Signature packet, which
   should be a subkey binding signature issued by the top level key.

   Subkey and Key packets may each be followed by a revocation Signature
   packet to indicate that the key is revoked.  Revocation signatures
   are only accepted if they are issued by the key itself, or by a key
   that is authorized to issue revocations via a revocation key
   subpacket in a self-signature by the top level key.

   Transferable public key packet sequences may be concatenated to allow
   transferring multiple public keys in one operation.





Callas, et. al.             Standards Track                    [Page 51]

RFC 2440                 OpenPGP Message Format            November 1998


10.2. OpenPGP Messages

   An OpenPGP message is a packet or sequence of packets that
   corresponds to the following grammatical rules (comma represents
   sequential composition, and vertical bar separates alternatives):

   OpenPGP Message :- Encrypted Message | Signed Message |
                      Compressed Message | Literal Message.

   Compressed Message :- Compressed Data Packet.

   Literal Message :- Literal Data Packet.

   ESK :- Public Key Encrypted Session Key Packet |
          Symmetric-Key Encrypted Session Key Packet.

   ESK Sequence :- ESK | ESK Sequence, ESK.

   Encrypted Message :- Symmetrically Encrypted Data Packet |
               ESK Sequence, Symmetrically Encrypted Data Packet.

   One-Pass Signed Message :- One-Pass Signature Packet,
               OpenPGP Message, Corresponding Signature Packet.

   Signed Message :- Signature Packet, OpenPGP Message |
               One-Pass Signed Message.

   In addition, decrypting a Symmetrically Encrypted Data packet and

   decompressing a Compressed Data packet must yield a valid OpenPGP
   Message.

10.3. Detached Signatures

   Some OpenPGP applications use so-called "detached signatures." For
   example, a program bundle may contain a file, and with it a second
   file that is a detached signature of the first file. These detached
   signatures are simply a signature packet stored separately from the
   data that they are a signature of.

11. Enhanced Key Formats

11.1. Key Structures

   The format of an OpenPGP V3 key is as follows.  Entries in square
   brackets are optional and ellipses indicate repetition.





Callas, et. al.             Standards Track                    [Page 52]

RFC 2440                 OpenPGP Message Format            November 1998


           RSA Public Key
              [Revocation Self Signature]
               User ID [Signature ...]
              [User ID [Signature ...] ...]

   Each signature certifies the RSA public key and the preceding user
   ID. The RSA public key can have many user IDs and each user ID can
   have many signatures.

   The format of an OpenPGP V4 key that uses two public keys is similar
   except that the other keys are added to the end as 'subkeys' of the
   primary key.

           Primary-Key
              [Revocation Self Signature]
              [Direct Key Self Signature...]
               User ID [Signature ...]
              [User ID [Signature ...] ...]
              [[Subkey [Binding-Signature-Revocation]
                      Primary-Key-Binding-Signature] ...]

   A subkey always has a single signature after it that is issued using
   the primary key to tie the two keys together.  This binding signature
   may be in either V3 or V4 format, but V4 is preferred, of course.

   In the above diagram, if the binding signature of a subkey has been
   revoked, the revoked binding signature may be removed, leaving only
   one signature.

   In a key that has a main key and subkeys, the primary key MUST be a
   key capable of signing. The subkeys may be keys of any other type.
   There may be other constructions of V4 keys, too. For example, there
   may be a single-key RSA key in V4 format, a DSA primary key with an
   RSA encryption key, or RSA primary key with an Elgamal subkey, etc.

   It is also possible to have a signature-only subkey. This permits a
   primary key that collects certifications (key signatures) but is used
   only used for certifying subkeys that are used for encryption and
   signatures.

11.2. Key IDs and Fingerprints

   For a V3 key, the eight-octet key ID consists of the low 64 bits of
   the public modulus of the RSA key.

   The fingerprint of a V3 key is formed by hashing the body (but not
   the two-octet length) of the MPIs that form the key material (public
   modulus n, followed by exponent e) with MD5.



Callas, et. al.             Standards Track                    [Page 53]

RFC 2440                 OpenPGP Message Format            November 1998


   A V4 fingerprint is the 160-bit SHA-1 hash of the one-octet Packet
   Tag, followed by the two-octet packet length, followed by the entire
   Public Key packet starting with the version field.  The key ID is the
   low order 64 bits of the fingerprint.  Here are the fields of the
   hash material, with the example of a DSA key:

  a.1) 0x99 (1 octet)

  a.2) high order length octet of (b)-(f) (1 octet)

  a.3) low order length octet of (b)-(f) (1 octet)

    b) version number = 4 (1 octet);

    c) time stamp of key creation (4 octets);

    d) algorithm (1 octet): 17 = DSA (example);

    e) Algorithm specific fields.

   Algorithm Specific Fields for DSA keys (example):

  e.1) MPI of DSA prime p;

  e.2) MPI of DSA group order q (q is a prime divisor of p-1);

  e.3) MPI of DSA group generator g;

  e.4) MPI of DSA public key value y (= g**x where x is secret).

   Note that it is possible for there to be collisions of key IDs -- two
   different keys with the same key ID. Note that there is a much
   smaller, but still non-zero probability that two different keys have
   the same fingerprint.

   Also note that if V3 and V4 format keys share the same RSA key
   material, they will have different key ids as well as different
   fingerprints.

12. Notes on Algorithms

12.1. Symmetric Algorithm Preferences

   The symmetric algorithm preference is an ordered list of algorithms
   that the keyholder accepts. Since it is found on a self-signature, it
   is possible that a keyholder may have different preferences. For
   example, Alice may have TripleDES only specified for "alice@work.com"
   but CAST5, Blowfish, and TripleDES specified for "alice@home.org".



Callas, et. al.             Standards Track                    [Page 54]

RFC 2440                 OpenPGP Message Format            November 1998


   Note that it is also possible for preferences to be in a subkey's
   binding signature.

   Since TripleDES is the MUST-implement algorithm, if it is not
   explicitly in the list, it is tacitly at the end. However, it is good
   form to place it there explicitly. Note also that if an
   implementation does not implement the preference, then it is
   implicitly a TripleDES-only implementation.

   An implementation MUST not use a symmetric algorithm that is not in
   the recipient's preference list. When encrypting to more than one
   recipient, the implementation finds a suitable algorithm by taking
   the intersection of the preferences of the recipients. Note that the
   MUST-implement algorithm, TripleDES, ensures that the intersection is
   not null. The implementation may use any mechanism to pick an
   algorithm in the intersection.

   If an implementation can decrypt a message that a keyholder doesn't
   have in their preferences, the implementation SHOULD decrypt the
   message anyway, but MUST warn the keyholder than protocol has been
   violated. (For example, suppose that Alice, above, has software that
   implements all algorithms in this specification. Nonetheless, she
   prefers subsets for work or home. If she is sent a message encrypted
   with IDEA, which is not in her preferences, the software warns her
   that someone sent her an IDEA-encrypted message, but it would ideally
   decrypt it anyway.)

   An implementation that is striving for backward compatibility MAY
   consider a V3 key with a V3 self-signature to be an implicit
   preference for IDEA, and no ability to do TripleDES. This is
   technically non-compliant, but an implementation MAY violate the
   above rule in this case only and use IDEA to encrypt the message,
   provided that the message creator is warned. Ideally, though, the
   implementation would follow the rule by actually generating two
   messages, because it is possible that the OpenPGP user's
   implementation does not have IDEA, and thus could not read the
   message. Consequently, an implementation MAY, but SHOULD NOT use IDEA
   in an algorithm conflict with a V3 key.

12.2. Other Algorithm Preferences

   Other algorithm preferences work similarly to the symmetric algorithm
   preference, in that they specify which algorithms the keyholder
   accepts. There are two interesting cases that other comments need to
   be made about, though, the compression preferences and the hash
   preferences.





Callas, et. al.             Standards Track                    [Page 55]

RFC 2440                 OpenPGP Message Format            November 1998


12.2.1. Compression Preferences

   Compression has been an integral part of PGP since its first days.
   OpenPGP and all previous versions of PGP have offered compression.
   And in this specification, the default is for messages to be
   compressed, although an implementation is not required to do so.
   Consequently, the compression preference gives a way for a keyholder
   to request that messages not be compressed, presumably because they
   are using a minimal implementation that does not include compression.
   Additionally, this gives a keyholder a way to state that it can
   support alternate algorithms.

   Like the algorithm preferences, an implementation MUST NOT use an
   algorithm that is not in the preference vector. If the preferences
   are not present, then they are assumed to be [ZIP(1),
   UNCOMPRESSED(0)].

12.2.2. Hash Algorithm Preferences

   Typically, the choice of a hash algorithm is something the signer
   does, rather than the verifier, because a signer does not typically
   know who is going to be verifying the signature. This preference,
   though, allows a protocol based upon digital signatures ease in
   negotiation.

   Thus, if Alice is authenticating herself to Bob with a signature, it
   makes sense for her to use a hash algorithm that Bob's software uses.
   This preference allows Bob to state in his key which algorithms Alice
   may use.

12.3. Plaintext

   Algorithm 0, "plaintext", may only be used to denote secret keys that
   are stored in the clear. Implementations must not use plaintext in
   Symmetrically Encrypted Data Packets; they must use Literal Data
   Packets to encode unencrypted or literal data.

12.4. RSA

   There are algorithm types for RSA-signature-only, and RSA-encrypt-
   only keys. These types are deprecated. The "key flags" subpacket in a
   signature is a much better way to express the same idea, and
   generalizes it to all algorithms. An implementation SHOULD NOT create
   such a key, but MAY interpret it.

   An implementation SHOULD NOT implement RSA keys of size less than 768
   bits.




Callas, et. al.             Standards Track                    [Page 56]

RFC 2440                 OpenPGP Message Format            November 1998


   It is permissible for an implementation to support RSA merely for
   backward compatibility; for example, such an implementation would
   support V3 keys with IDEA symmetric cryptography. Note that this is
   an exception to the other MUST-implement rules. An implementation
   that supports RSA in V4 keys MUST implement the MUST-implement
   features.

12.5. Elgamal

   If an Elgamal key is to be used for both signing and encryption,
   extra care must be taken in creating the key.

   An ElGamal key consists of a generator g, a prime modulus p, a secret
   exponent x, and a public value y = g^x mod p.

   The generator and prime must be chosen so that solving the discrete
   log problem is intractable.  The group g should generate the
   multiplicative group mod p-1 or a large subgroup of it, and the order
   of g should have at least one large prime factor.  A good choice is
   to use a "strong" Sophie-Germain prime in choosing p, so that both p
   and (p-1)/2 are primes. In fact, this choice is so good that
   implementors SHOULD do it, as it avoids a small subgroup attack.

   In addition, a result of Bleichenbacher [BLEICHENBACHER] shows that
   if the generator g has only small prime factors, and if g divides the
   order of the group it generates, then signatures can be forged.  In
   particular, choosing g=2 is a bad choice if the group order may be
   even. On the other hand, a generator of 2 is a fine choice for an
   encryption-only key, as this will make the encryption faster.

   While verifying Elgamal signatures, note that it is important to test
   that r and s are less than p.  If this test is not done then
   signatures can be trivially forged by using large r values of
   approximately twice the length of p.  This attack is also discussed
   in the Bleichenbacher paper.

   Details on safe use of Elgamal signatures may be found in [MENEZES],
   which discusses all the weaknesses described above.

   If an implementation allows Elgamal signatures, then it MUST use the
   algorithm identifier 20 for an Elgamal public key that can sign.

   An implementation SHOULD NOT implement Elgamal keys of size less than
   768 bits. For long-term security, Elgamal keys should be 1024 bits or
   longer.






Callas, et. al.             Standards Track                    [Page 57]

RFC 2440                 OpenPGP Message Format            November 1998


12.6. DSA

   An implementation SHOULD NOT implement DSA keys of size less than 768
   bits. Note that present DSA is limited to a maximum of 1024 bit keys,
   which are recommended for long-term use.

12.7. Reserved Algorithm Numbers

   A number of algorithm IDs have been reserved for algorithms that
   would be useful to use in an OpenPGP implementation, yet there are
   issues that prevent an implementor from actually implementing the
   algorithm. These are marked in the Public Algorithms section as
   "(reserved for)".

   The reserved public key algorithms, Elliptic Curve (18), ECDSA (19),
   and X9.42 (21) do not have the necessary parameters, parameter order,
   or semantics defined.

   The reserved symmetric key algorithm, DES/SK (6), does not have
   semantics defined.

   The reserved hash algorithms, TIGER192 (6), and HAVAL-5-160 (7), do
   not have OIDs. The reserved algorithm number 4, reserved for a
   double-width variant of SHA1, is not presently defined.

   We have reserver three algorithm IDs for the US NIST's Advanced
   Encryption Standard. This algorithm will work with (at least) 128,
   192, and 256-bit keys. We expect that this algorithm will be selected
   from the candidate algorithms in the year 2000.

12.8. OpenPGP CFB mode

   OpenPGP does symmetric encryption using a variant of Cipher Feedback
   Mode (CFB mode). This section describes the procedure it uses in
   detail. This mode is what is used for Symmetrically Encrypted Data
   Packets; the mechanism used for encrypting secret key material is
   similar, but described in those sections above.

   OpenPGP CFB mode uses an initialization vector (IV) of all zeros, and
   prefixes the plaintext with ten octets of random data, such that
   octets 9 and 10 match octets 7 and 8.  It does a CFB "resync" after
   encrypting those ten octets.

   Note that for an algorithm that has a larger block size than 64 bits,
   the equivalent function will be done with that entire block.  For
   example, a 16-octet block algorithm would operate on 16 octets, and
   then produce two octets of check, and then work on 16-octet blocks.




Callas, et. al.             Standards Track                    [Page 58]

RFC 2440                 OpenPGP Message Format            November 1998


   Step by step, here is the procedure:

   1.  The feedback register (FR) is set to the IV, which is all zeros.

   2.  FR is encrypted to produce FRE (FR Encrypted).  This is the
       encryption of an all-zero value.

   3.  FRE is xored with the first 8 octets of random data prefixed to
       the plaintext to produce C1-C8, the first 8 octets of ciphertext.

   4.  FR is loaded with C1-C8.

   5.  FR is encrypted to produce FRE, the encryption of the first 8
       octets of ciphertext.

   6.  The left two octets of FRE get xored with the next two octets of
       data that were prefixed to the plaintext.  This produces C9-C10,
       the next two octets of ciphertext.

   7.  (The resync step) FR is loaded with C3-C10.

   8.  FR is encrypted to produce FRE.

   9.  FRE is xored with the first 8 octets of the given plaintext, now
       that we have finished encrypting the 10 octets of prefixed data.
       This produces C11-C18, the next 8 octets of ciphertext.

   10.  FR is loaded with C11-C18

   11.  FR is encrypted to produce FRE.

   12.  FRE is xored with the next 8 octets of plaintext, to produce the
       next 8 octets of ciphertext.  These are loaded into FR and the
       process is repeated until the plaintext is used up.

13. Security Considerations

   As with any technology involving cryptography, you should check the
   current literature to determine if any algorithms used here have been
   found to be vulnerable to attack.

   This specification uses Public Key Cryptography technologies.
   Possession of the private key portion of a public-private key pair is
   assumed to be controlled by the proper party or parties.

   Certain operations in this specification involve the use of random
   numbers.  An appropriate entropy source should be used to generate
   these numbers.  See RFC 1750.



Callas, et. al.             Standards Track                    [Page 59]

RFC 2440                 OpenPGP Message Format            November 1998


   The MD5 hash algorithm has been found to have weaknesses (pseudo-
   collisions in the compress function) that make some people deprecate
   its use.  They consider the SHA-1 algorithm better.

   Many security protocol designers think that it is a bad idea to use a
   single key for both privacy (encryption) and integrity (signatures).
   In fact, this was one of the motivating forces behind the V4 key
   format with separate signature and encryption keys. If you as an
   implementor promote dual-use keys, you should at least be aware of
   this controversy.

   The DSA algorithm will work with any 160-bit hash, but it is
   sensitive to the quality of the hash algorithm, if the hash algorithm
   is broken, it can leak the secret key. The Digital Signature Standard
   (DSS) specifies that DSA be used with SHA-1.  RIPEMD-160 is
   considered by many cryptographers to be as strong. An implementation
   should take care which hash algorithms are used with DSA, as a weak
   hash can not only allow a signature to be forged, but could leak the
   secret key. These same considerations about the quality of the hash
   algorithm apply to Elgamal signatures.

   If you are building an authentication system, the recipient may
   specify a preferred signing algorithm. However, the signer would be
   foolish to use a weak algorithm simply because the recipient requests
   it.

   Some of the encryption algorithms mentioned in this document have
   been analyzed less than others.  For example, although CAST5 is
   presently considered strong, it has been analyzed less than Triple-
   DES. Other algorithms may have other controversies surrounding them.

   Some technologies mentioned here may be subject to government control
   in some countries.

14. Implementation Nits

   This section is a collection of comments to help an implementer,
   particularly with an eye to backward compatibility. Previous
   implementations of PGP are not OpenPGP-compliant. Often the
   differences are small, but small differences are frequently more
   vexing than large differences. Thus, this list of potential problems
   and gotchas for a developer who is trying to be backward-compatible.

     * PGP 5.x does not accept V4 signatures for anything other than
       key material.

     * PGP 5.x does not recognize the "five-octet" lengths in new-format
       headers or in signature subpacket lengths.



Callas, et. al.             Standards Track                    [Page 60]

RFC 2440                 OpenPGP Message Format            November 1998


     * PGP 5.0 rejects an encrypted session key if the keylength differs
       from the S2K symmetric algorithm. This is a bug in its validation
       function.

     * PGP 5.0 does not handle multiple one-pass signature headers and
       trailers. Signing one will compress the one-pass signed literal
       and prefix a V3 signature instead of doing a nested one-pass
       signature.

     * When exporting a private key, PGP 2.x generates the header "BEGIN
       PGP SECRET KEY BLOCK" instead of "BEGIN PGP PRIVATE KEY BLOCK".
       All previous versions ignore the implied data type, and look
       directly at the packet data type.

     * In a clear-signed signature, PGP 5.0 will figure out the correct
       hash algorithm if there is no "Hash:" header, but it will reject
       a mismatch between the header and the actual algorithm used. The
       "standard" (i.e. Zimmermann/Finney/et al.) version of PGP 2.x
       rejects the "Hash:" header and assumes MD5. There are a number of
       enhanced variants of PGP 2.6.x that have been modified for SHA-1
       signatures.

     * PGP 5.0 can read an RSA key in V4 format, but can only recognize
       it with a V3 keyid, and can properly use only a V3 format RSA
       key.

     * Neither PGP 5.x nor PGP 6.0 recognize Elgamal Encrypt and Sign
       keys. They only handle Elgamal Encrypt-only keys.

     * There are many ways possible for two keys to have the same key
       material, but different fingerprints (and thus key ids). Perhaps
       the most interesting is an RSA key that has been "upgraded" to V4
       format, but since a V4 fingerprint is constructed by hashing the
       key creation time along with other things, two V4 keys created at
       different times, yet with the same key material will have
       different fingerprints.

     * If an implementation is using zlib to interoperate with PGP 2.x,
       then the "windowBits" parameter should be set to -13.












Callas, et. al.             Standards Track                    [Page 61]

RFC 2440                 OpenPGP Message Format            November 1998


15. Authors and Working Group Chair

   The working group can be contacted via the current chair:

   John W. Noerenberg, II
   Qualcomm, Inc
   6455 Lusk Blvd
   San Diego, CA 92131 USA

   Phone: +1 619-658-3510
   EMail: jwn2@qualcomm.com


   The principal authors of this memo are:

   Jon Callas
   Network Associates, Inc.
   3965 Freedom Circle
   Santa Clara, CA 95054, USA

   Phone: +1 408-346-5860
   EMail: jon@pgp.com, jcallas@nai.com


   Lutz Donnerhacke
   IKS GmbH
   Wildenbruchstr. 15
   07745 Jena, Germany

   Phone: +49-3641-675642
   EMail: lutz@iks-jena.de


   Hal Finney
   Network Associates, Inc.
   3965 Freedom Circle
   Santa Clara, CA 95054, USA

   EMail: hal@pgp.com


   Rodney Thayer
   EIS Corporation
   Clearwater, FL 33767, USA

   EMail: rodney@unitran.com





Callas, et. al.             Standards Track                    [Page 62]

RFC 2440                 OpenPGP Message Format            November 1998


   This memo also draws on much previous work from a number of other
   authors who include: Derek Atkins, Charles Breed, Dave Del Torto,
   Marc Dyksterhouse, Gail Haspert, Gene Hoffman, Paul Hoffman, Raph
   Levien, Colin Plumb, Will Price, William Stallings, Mark Weaver, and
   Philip R. Zimmermann.

16. References

   [BLEICHENBACHER] Bleichenbacher, Daniel, "Generating ElGamal
                    signatures without knowing the secret key,"
                    Eurocrypt 96.  Note that the version in the
                    proceedings has an error.  A revised version is
                    available at the time of writing from
                    <ftp://ftp.inf.ethz.ch/pub/publications/papers/ti/isc
                    /ElGamal.ps>

   [BLOWFISH]       Schneier, B. "Description of a New Variable-Length
                    Key, 64-Bit Block Cipher (Blowfish)" Fast Software
                    Encryption, Cambridge Security Workshop Proceedings
                    (December 1993), Springer-Verlag, 1994, pp191-204

                    <http://www.counterpane.com/bfsverlag.html>

   [DONNERHACKE]    Donnerhacke, L., et. al, "PGP263in - an improved
                    international version of PGP", ftp://ftp.iks-
                    jena.de/mitarb/lutz/crypt/software/pgp/

   [ELGAMAL]        T. ElGamal, "A Public-Key Cryptosystem and a
                    Signature Scheme Based on Discrete Logarithms," IEEE
                    Transactions on Information Theory, v. IT-31, n. 4,
                    1985, pp. 469-472.

   [IDEA]           Lai, X, "On the design and security of block
                    ciphers", ETH Series in Information Processing, J.L.
                    Massey (editor), Vol. 1, Hartung-Gorre Verlag
                    Knostanz, Technische Hochschule (Zurich), 1992

   [ISO-10646]      ISO/IEC 10646-1:1993. International Standard --
                    Information technology -- Universal Multiple-Octet
                    Coded Character Set (UCS) -- Part 1: Architecture
                    and Basic Multilingual Plane.  UTF-8 is described in
                    Annex R, adopted but not yet published.  UTF-16 is
                    described in Annex Q, adopted but not yet published.

   [MENEZES]        Alfred Menezes, Paul van Oorschot, and Scott
                    Vanstone, "Handbook of Applied Cryptography," CRC
                    Press, 1996.




Callas, et. al.             Standards Track                    [Page 63]

RFC 2440                 OpenPGP Message Format            November 1998


   [RFC822]         Crocker, D., "Standard for the format of ARPA
                    Internet text messages", STD 11, RFC 822, August
                    1982.

   [RFC1423]        Balenson, D., "Privacy Enhancement for Internet
                    Electronic Mail: Part III: Algorithms, Modes, and
                    Identifiers", RFC 1423, October 1993.

   [RFC1641]        Goldsmith, D. and M. Davis, "Using Unicode with
                    MIME", RFC 1641, July 1994.

   [RFC1750]        Eastlake, D., Crocker, S. and J. Schiller,
                    "Randomness Recommendations for Security", RFC 1750,
                    December 1994.

   [RFC1951]        Deutsch, P., "DEFLATE Compressed Data Format
                    Specification version 1.3.", RFC 1951, May 1996.

   [RFC1983]        Malkin, G., "Internet Users' Glossary", FYI 18, RFC
                    1983, August 1996.

   [RFC1991]        Atkins, D., Stallings, W. and P. Zimmermann, "PGP
                    Message Exchange Formats", RFC 1991, August 1996.

   [RFC2015]        Elkins, M., "MIME Security with Pretty Good Privacy
                    (PGP)", RFC 2015, October 1996.

   [RFC2231]        Borenstein, N. and N. Freed, "Multipurpose Internet
                    Mail Extensions (MIME) Part One: Format of Internet
                    Message Bodies.", RFC 2231, November 1996.

   [RFC2119]        Bradner, S., "Key words for use in RFCs to Indicate
                    Requirement Level", BCP 14, RFC 2119, March 1997.

   [RFC2144]        Adams, C., "The CAST-128 Encryption Algorithm", RFC
                    2144, May 1997.

   [RFC2279]        Yergeau., F., "UTF-8, a transformation format of
                    Unicode and ISO 10646", RFC 2279, January 1998.

   [RFC2313]        Kaliski, B., "PKCS #1: RSA Encryption Standard
                    version 1.5", RFC 2313, March 1998.

   [SAFER]          Massey, J.L. "SAFER K-64: One Year Later", B.
                    Preneel, editor, Fast Software Encryption, Second
                    International Workshop (LNCS 1008) pp212-241,
                    Springer-Verlag 1995




Callas, et. al.             Standards Track                    [Page 64]

RFC 2440                 OpenPGP Message Format            November 1998


17.  Full Copyright Statement

   Copyright (C) The Internet Society (1998).  All Rights Reserved.

   This document and translations of it may be copied and furnished to
   others, and derivative works that comment on or otherwise explain it
   or assist in its implementation may be prepared, copied, published
   and distributed, in whole or in part, without restriction of any
   kind, provided that the above copyright notice and this paragraph are
   included on all such copies and derivative works.  However, this
   document itself may not be modified in any way, such as by removing
   the copyright notice or references to the Internet Society or other
   Internet organizations, except as needed for the purpose of
   developing Internet standards in which case the procedures for
   copyrights defined in the Internet Standards process must be
   followed, or as required to translate it into languages other than
   English.

   The limited permissions granted above are perpetual and will not be
   revoked by the Internet Society or its successors or assigns.

   This document and the information contained herein is provided on an
   "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
   TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
   BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
   HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
   MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
























Callas, et. al.             Standards Track                    [Page 65]



================================================
FILE: doc/notes/rfc/rfc2487.txt
================================================






Network Working Group                                     P. Hoffman
Request for Comments: 2487                  Internet Mail Consortium
Category: Standards Track                               January 1999


            SMTP Service Extension for Secure SMTP over TLS

Status of this Memo

   This document specifies an Internet standards track protocol for the
   Internet community, and requests discussion and suggestions for
   improvements.  Please refer to the current edition of the "Internet
   Official Protocol Standards" (STD 1) for the standardization state
   and status of this protocol.  Distribution of this memo is unlimited.

Copyright Notice

   Copyright (C) The Internet Society (1999).  All Rights Reserved.

1. Abstract

   This document describes an extension to the SMTP service that allows
   an SMTP server and client to use transport-layer security to provide
   private, authenticated communication over the Internet. This gives
   SMTP agents the ability to protect some or all of their
   communications from eavesdroppers and attackers.

2. Introduction

   SMTP [RFC-821] servers and clients normally communicate in the clear
   over the Internet. In many cases, this communication goes through one
   or more router that is not controlled or trusted by either entity.
   Such an untrusted router might allow a third party to monitor or
   alter the communications between the server and client.

   Further, there is often a desire for two SMTP agents to be able to
   authenticate each others' identities. For example, a secure SMTP
   server might only allow communications from other SMTP agents it
   knows, or it might act differently for messages received from an
   agent it knows than from one it doesn't know.

   TLS [TLS], more commonly known as SSL, is a popular mechanism for
   enhancing TCP communications with privacy and authentication. TLS is
   in wide use with the HTTP protocol, and is also being used for adding
   security to many other common protocols that run over TCP.






Hoffman                     Standards Track                     [Page 1]

RFC 2487                 SMTP Service Extension             January 1999


2.1 Terminology

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in [RFC-2119].

3. STARTTLS Extension

   The STARTTLS extension to SMTP is laid out as follows:

   (1) the name of the SMTP service defined here is STARTTLS;

   (2) the EHLO keyword value associated with the extension is STARTTLS;

   (3) the STARTTLS keyword has no parameters;

   (4) a new SMTP verb, "STARTTLS", is defined;

   (5) no additional parameters are added to any SMTP command.

4. The STARTTLS Keyword

   The STARTTLS keyword is used to tell the SMTP client that the SMTP
   server allows use of TLS. It takes no parameters.

5. The STARTTLS Command

   The format for the STARTTLS command is:

   STARTTLS

   with no parameters.

   After the client gives the STARTTLS command, the server responds with
   one of the following reply codes:

   220 Ready to start TLS
   501 Syntax error (no parameters allowed)
   454 TLS not available due to temporary reason

   A publicly-referenced SMTP server MUST NOT require use of the
   STARTTLS extension in order to deliver mail locally. This rule
   prevents the STARTTLS extension from damaging the interoperability of
   the Internet's SMTP infrastructure. A publicly-referenced SMTP server
   is an SMTP server which runs on port 25 of an Internet host listed in
   the MX record (or A record if an MX record is not present) for the
   domain name on the right hand side of an Internet mail address.




Hoffman                     Standards Track                     [Page 2]

RFC 2487                 SMTP Service Extension             January 1999


   Any SMTP server may refuse to accept messages for relay based on
   authentication supplied during the TLS negotiation. An SMTP server
   that is not publicly referenced may refuse to accept any messages for
   relay or local delivery based on authentication supplied during the
   TLS negotiation.

   A SMTP server that is not publicly referenced may choose to require
   that the client perform a TLS negotiation before accepting any
   commands. In this case, the server SHOULD return the reply code:

   530 Must issue a STARTTLS command first

   to every command other than NOOP, EHLO, STARTTLS, or QUIT. If the
   client and server are using the ENHANCEDSTATUSCODES ESMTP extension
   [RFC-2034], the status code to be returned SHOULD be 5.7.0.

   After receiving a 220 response to a STARTTLS command, the client
   SHOULD start the TLS negotiation before giving any other SMTP
   commands.

   If the SMTP client is using pipelining as defined in RFC 1854, the
   STARTTLS command must be the last command in a group.

5.1 Processing After the STARTTLS Command

   After the TLS handshake has been completed, both parties MUST
   immediately decide whether or not to continue based on the
   authentication and privacy achieved. The SMTP client and server may
   decide to move ahead even if the TLS negotiation ended with no
   authentication and/or no privacy because most SMTP services are
   performed with no authentication and no privacy, but some SMTP
   clients or servers may want to continue only if a particular level of
   authentication and/or privacy was achieved.

   If the SMTP client decides that the level of authentication or
   privacy is not high enough for it to continue, it SHOULD issue an
   SMTP QUIT command immediately after the TLS negotiation is complete.
   If the SMTP server decides that the level of authentication or
   privacy is not high enough for it to continue, it SHOULD reply to
   every SMTP command from the client (other than a QUIT command) with
   the 554 reply code (with a possible text string such as "Command
   refused due to lack of security").

   The decision of whether or not to believe the authenticity of the
   other party in a TLS negotiation is a local matter. However, some
   general rules for the decisions are:





Hoffman                     Standards Track                     [Page 3]

RFC 2487                 SMTP Service Extension             January 1999


    - A SMTP client would probably only want to authenticate an SMTP
      server whose server certificate has a domain name that is the
      domain name that the client thought it was connecting to.
    - A publicly-referenced  SMTP server would probably want to accept
      any certificate from an SMTP client, and would possibly want to
      put distinguishing information about the certificate in the
      Received header of messages that were relayed or submitted from
      the client.

5.2 Result of the STARTTLS Command

   Upon completion of the TLS handshake, the SMTP protocol is reset to
   the initial state (the state in SMTP after a server issues a 220
   service ready greeting). The server MUST discard any knowledge
   obtained from the client, such as the argument to the EHLO command,
   which was not obtained from the TLS negotiation itself. The client
   MUST discard any knowledge obtained from the server, such as the list
   of SMTP service extensions, which was not obtained from the TLS
   negotiation itself. The client SHOULD send an EHLO command as the
   first command after a successful TLS negotiation.

   The list of SMTP service extensions returned in response to an EHLO
   command received after the TLS handshake MAY be different than the
   list returned before the TLS handshake. For example, an SMTP server
   might not want to advertise support for a particular SASL mechanism
   [SASL] unless a client has sent an appropriate client certificate
   during a TLS handshake.

   Both the client and the server MUST know if there is a TLS session
   active.  A client MUST NOT attempt to start a TLS session if a TLS
   session is already active. A server MUST NOT return the TLS extension
   in response to an EHLO command received after a TLS handshake has
   completed.

6. Usage Example

   The following dialog illustrates how a client and server can start a
   TLS session:

   S: <waits for connection on TCP port 25>
   C: <opens connection>
   S: 220 mail.imc.org SMTP service ready
   C: EHLO mail.ietf.org
   S: 250-mail.imc.org offers a warm hug of welcome
   S: 250 STARTTLS
   C: STARTTLS
   S: 220 Go ahead
   C: <starts TLS negotiation>



Hoffman                     Standards Track                     [Page 4]

RFC 2487                 SMTP Service Extension             January 1999


   C & S: <negotiate a TLS session>
   C & S: <check result of negotiation>
   C: <continues by sending an SMTP command>
   . . .

7. Security Considerations

   It should be noted that SMTP is not an end-to-end mechanism. Thus, if
   an SMTP client/server pair decide to add TLS privacy, they are not
   securing the transport from the originating mail user agent to the
   recipient.  Further, because delivery of a single piece of mail may
   go between more than two SMTP servers, adding TLS privacy to one pair
   of servers does not mean that the entire SMTP chain has been made
   private. Further, just because an SMTP server can authenticate an
   SMTP client, it does not mean that the mail from the SMTP client was
   authenticated by the SMTP client when the client received it.

   Both the STMP client and server must check the result of the TLS
   negotiation to see whether acceptable authentication or privacy was
   achieved. Ignoring this step completely invalidates using TLS for
   security.  The decision about whether acceptable authentication or
   privacy was achieved is made locally, is implementation-dependant,
   and is beyond the scope of this document.

   The SMTP client and server should note carefully the result of the
   TLS negotiation. If the negotiation results in no privacy, or if it
   results in privacy using algorithms or key lengths that are deemed
   not strong enough, or if the authentication is not good enough for
   either party, the client may choose to end the SMTP session with an
   immediate QUIT command, or the server may choose to not accept any
   more SMTP commands.

   A server announcing in an EHLO response that it uses a particular TLS
   protocol should not pose any security issues, since any use of TLS
   will be at least as secure as no use of TLS.

   A man-in-the-middle attack can be launched by deleting the "250
   STARTTLS" response from the server. This would cause the client not
   to try to start a TLS session. An SMTP client can protect against
   this attack by recording the fact that a particular SMTP server
   offers TLS during one session and generating an alarm if it does not
   appear in the EHLO response for a later session. The lack of TLS
   during a session SHOULD NOT result in the bouncing of email, although
   it could result in delayed processing.







Hoffman                     Standards Track                     [Page 5]

RFC 2487                 SMTP Service Extension             January 1999


   Before the TLS handshake has begun, any protocol interactions are
   performed in the clear and may be modified by an active attacker. For
   this reason, clients and servers MUST discard any knowledge obtained
   prior to the start of the TLS handshake upon completion of the TLS
   handshake.

   The STARTTLS extension is not suitable for authenticating the author
   of an email message unless every hop in the delivery chain, including
   the submission to the first SMTP server, is authenticated. Another
   proposal [SMTP-AUTH] can be used to authenticate delivery and MIME
   security multiparts [MIME-SEC] can be used to authenticate the author
   of an email message. In addition, the [SMTP-AUTH] proposal offers
   simpler and more flexible options to authenticate an SMTP client and
   the SASL EXTERNAL mechanism [SASL] MAY be used in conjunction with
   the STARTTLS command to provide an authorization identity.




































Hoffman                     Standards Track                     [Page 6]

RFC 2487                 SMTP Service Extension             January 1999


A. References

   [RFC-821]   Postel, J., "Simple Mail Transfer Protocol", RFC 821,
               August 1982.

   [RFC-1869]  Klensin, J., Freed, N, Rose, M, Stefferud, E. and D.
               Crocker, "SMTP Service Extensions", STD 10, RFC 1869,
               November 1995.

   [RFC-2034]  Freed, N., "SMTP Service Extension for Returning Enhanced
               Error Codes", RFC 2034, October 1996.

   [RFC-2119]  Bradner, S., "Key words for use in RFCs to Indicate
               Requirement Levels", BCP 14, RFC 2119, March 1997.

   [SASL]      Myers, J., "Simple Authentication and Security Layer
               (SASL)", RFC 2222, October 1997.

   [SMTP-AUTH] "SMTP Service Extension for Authentication", Work in
               Progress.

   [TLS]       Dierks, T. and C. Allen, "The TLS Protocol Version 1.0",
               RFC 2246, January 1999.

B. Author's Address

   Paul Hoffman
   Internet Mail Consortium
   127 Segre Place
   Santa Cruz, CA  95060

   Phone: (831) 426-9827
   EMail: phoffman@imc.org


















Hoffman                     Standards Track                     [Page 7]

RFC 2487                 SMTP Service Extension             January 1999


C.  Full Copyright Statement

   Copyright (C) The Internet Society (1999).  All Rights Reserved.

   This document and translations of it may be copied and furnished to
   others, and derivative works that comment on or otherwise explain it
   or assist in its implementation may be prepared, copied, published
   and distributed, in whole or in part, without restriction of any
   kind, provided that the above copyright notice and this paragraph are
   included on all such copies and derivative works.  However, this
   document itself may not be modified in any way, such as by removing
   the copyright notice or references to the Internet Society or other
   Internet organizations, except as needed for the purpose of
   developing Internet standards in which case the procedures for
   copyrights defined in the Internet Standards process must be
   followed, or as required to translate it into languages other than
   English.

   The limited permissions granted above are perpetual and will not be
   revoked by the Internet Society or its successors or assigns.

   This document and the information contained herein is provided on an
   "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
   TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
   BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
   HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
   MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
























Hoffman                     Standards Track                     [Page 8]



================================================
FILE: doc/notes/rfc/rfc2554.txt
================================================






Network Working Group                                           J. Myers
Request for Comments: 2554                       Netscape Communications
Category: Standards Track                                     March 1999


                         SMTP Service Extension
                           for Authentication

Status of this Memo

   This document specifies an Internet standards track protocol for the
   Internet community, and requests discussion and suggestions for
   improvements.  Please refer to the current edition of the "Internet
   Official Protocol Standards" (STD 1) for the standardization state
   and status of this protocol.  Distribution of this memo is unlimited.

Copyright Notice

   Copyright (C) The Internet Society (1999).  All Rights Reserved.


1. Introduction

   This document defines an SMTP service extension [ESMTP] whereby an
   SMTP client may indicate an authentication mechanism to the server,
   perform an authentication protocol exchange, and optionally negotiate
   a security layer for subsequent protocol interactions.  This
   extension is a profile of the Simple Authentication and Security
   Layer [SASL].


2. Conventions Used in this Document

   In examples, "C:" and "S:" indicate lines sent by the client and
   server respectively.

   The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY"
   in this document are to be interpreted as defined in "Key words for
   use in RFCs to Indicate Requirement Levels" [KEYWORDS].


3. The Authentication service extension


   (1) the name of the SMTP service extension is "Authentication"

   (2) the EHLO keyword value associated with this extension is "AUTH"




Myers                       Standards Track                     [Page 1]

RFC 2554                  SMTP Authentication                 March 1999


   (3) The AUTH EHLO keyword contains as a parameter a space separated
       list of the names of supported SASL mechanisms.

   (4) a new SMTP verb "AUTH" is defined

   (5) an optional parameter using the keyword "AUTH" is added to the
       MAIL FROM command, and extends the maximum line length of the
       MAIL FROM command by 500 characters.

   (6) this extension is appropriate for the submission protocol
       [SUBMIT].


4. The AUTH command

   AUTH mechanism [initial-response]

     Arguments:
         a string identifying a SASL authentication mechanism.
         an optional base64-encoded response

     Restrictions:
         After an AUTH command has successfully completed, no more AUTH
         commands may be issued in the same session.  After a successful
         AUTH command completes, a server MUST reject any further AUTH
         commands with a 503 reply.

         The AUTH command is not permitted during a mail transaction.

     Discussion:
         The AUTH command indicates an authentication mechanism to the
         server.  If the server supports the requested authentication
         mechanism, it performs an authentication protocol exchange to
         authenticate and identify the user.  Optionally, it also
         negotiates a security layer for subsequent protocol
         interactions.  If the requested authentication mechanism is not
         supported, the server rejects the AUTH command with a 504
         reply.

         The authentication protocol exchange consists of a series of
         server challenges and client answers that are specific to the
         authentication mechanism.  A server challenge, otherwise known
         as a ready response, is a 334 reply with the text part
         containing a BASE64 encoded string.  The client answer consists
         of a line containing a BASE64 encoded string.  If the client
         wishes to cancel an authentication exchange, it issues a line
         with a single "*".  If the server receives such an answer, it
         MUST reject the AUTH command by sending a 501 reply.



Myers                       Standards Track                     [Page 2]

RFC 2554                  SMTP Authentication                 March 1999


         The optional initial-response argument to the AUTH command is
         used to save a round trip when using authentication mechanisms
         that are defined to send no data in the initial challenge.
         When the initial-response argument is used with such a
         mechanism, the initial empty challenge is not sent to the
         client and the server uses the data in the initial-response
         argument as if it were sent in response to the empty challenge.
         Unlike a zero-length client answer to a 334 reply, a zero-
         length initial response is sent as a single equals sign ("=").
         If the client uses an initial-response argument to the AUTH
         command with a mechanism that sends data in the initial
         challenge, the server rejects the AUTH command with a 535
         reply.

         If the server cannot BASE64 decode the argument, it rejects the
         AUTH command with a 501 reply.  If the server rejects the
         authentication data, it SHOULD reject the AUTH command with a
         535 reply unless a more specific error code, such as one listed
         in section 6, is appropriate.  Should the client successfully
         complete the authentication exchange, the SMTP server issues a
         235 reply.

         The service name specified by this protocol's profile of SASL
         is "smtp".

         If a security layer is negotiated through the SASL
         authentication exchange, it takes effect immediately following
         the CRLF that concludes the authentication exchange for the
         client, and the CRLF of the success reply for the server.  Upon
         a security layer's taking effect, the SMTP protocol is reset to
         the initial state (the state in SMTP after a server issues a
         220 service ready greeting).  The server MUST discard any
         knowledge obtained from the client, such as the argument to the
         EHLO command, which was not obtained from the SASL negotiation
         itself.  The client MUST discard any knowledge obtained from
         the server, such as the list of SMTP service extensions, which
         was not obtained from the SASL negotiation itself (with the
         exception that a client MAY compare the list of advertised SASL
         mechanisms before and after authentication in order to detect
         an active down-negotiation attack).  The client SHOULD send an
         EHLO command as the first command after a successful SASL
         negotiation which results in the enabling of a security layer.

         The server is not required to support any particular
         authentication mechanism, nor are authentication mechanisms
         required to support any security layers.  If an AUTH command
         fails, the client may try another authentication mechanism by
         issuing another AUTH command.



Myers                       Standards Track                     [Page 3]

RFC 2554                  SMTP Authentication                 March 1999


         If an AUTH command fails, the server MUST behave the same as if
         the client had not issued the AUTH command.

         The BASE64 string may in general be arbitrarily long.  Clients
         and servers MUST be able to support challenges and responses
         that are as long as are generated by the authentication
         mechanisms they support, independent of any line length
         limitations the client or server may have in other parts of its
         protocol implementation.

     Examples:
         S: 220 smtp.example.com ESMTP server ready
         C: EHLO jgm.example.com
         S: 250-smtp.example.com
         S: 250 AUTH CRAM-MD5 DIGEST-MD5
         C: AUTH FOOBAR
         S: 504 Unrecognized authentication type.
         C: AUTH CRAM-MD5
         S: 334
         PENCeUxFREJoU0NnbmhNWitOMjNGNndAZWx3b29kLmlubm9zb2Z0LmNvbT4=
         C: ZnJlZCA5ZTk1YWVlMDljNDBhZjJiODRhMGMyYjNiYmFlNzg2ZQ==
         S: 235 Authentication successful.



5. The AUTH parameter to the MAIL FROM command

   AUTH=addr-spec

   Arguments:
       An addr-spec containing the identity which submitted the message
       to the delivery system, or the two character sequence "<>"
       indicating such an identity is unknown or insufficiently
       authenticated.  To comply with the restrictions imposed on ESMTP
       parameters, the addr-spec is encoded inside an xtext.  The syntax
       of an xtext is described in section 5 of [ESMTP-DSN].

   Discussion:
       The optional AUTH parameter to the MAIL FROM command allows
       cooperating agents in a trusted environment to communicate the
       authentication of individual messages.

       If the server trusts the authenticated identity of the client to
       assert that the message was originally submitted by the supplied
       addr-spec, then the server SHOULD supply the same addr-spec in an
       AUTH parameter when relaying the message to any server which
       supports the AUTH extension.




Myers                       Standards Track                     [Page 4]

RFC 2554                  SMTP Authentication                 March 1999


       A MAIL FROM parameter of AUTH=<> indicates that the original
       submitter of the message is not known.  The server MUST NOT treat
       the message as having been originally submitted by the client.

       If the AUTH parameter to the MAIL FROM is not supplied, the
       client has authenticated, and the server believes the message is
       an original submission by the client, the server MAY supply the
       client's identity in the addr-spec in an AUTH parameter when
       relaying the message to any server which supports the AUTH
       extension.

       If the server does not sufficiently trust the authenticated
       identity of the client, or if the client is not authenticated,
       then the server MUST behave as if the AUTH=<> parameter was
       supplied.  The server MAY, however, write the value of the AUTH
       parameter to a log file.

       If an AUTH=<> parameter was supplied, either explicitly or due to
       the requirement in the previous paragraph, then the server MUST
       supply the AUTH=<> parameter when relaying the message to any
       server which it has authenticated to using the AUTH extension.

       A server MAY treat expansion of a mailing list as a new
       submission, setting the AUTH parameter to the mailing list
       address or mailing list administration address when relaying the
       message to list subscribers.

       It is conforming for an implementation to be hard-coded to treat
       all clients as being insufficiently trusted.  In that case, the
       implementation does nothing more than parse and discard
       syntactically valid AUTH parameters to the MAIL FROM command and
       supply AUTH=<> parameters to any servers to which it
       authenticates using the AUTH extension.

   Examples:
       C: MAIL FROM:<e=mc2@example.com> AUTH=e+3Dmc2@example.com
       S: 250 OK














Myers                       Standards Track                     [Page 5]

RFC 2554                  SMTP Authentication                 March 1999


6. Error Codes

   The following error codes may be used to indicate various conditions
   as described.

   432 A password transition is needed

   This response to the AUTH command indicates that the user needs to
   transition to the selected authentication mechanism.  This typically
   done by authenticating once using the PLAIN authentication mechanism.

   534 Authentication mechanism is too weak

   This response to the AUTH command indicates that the selected
   authentication mechanism is weaker than server policy permits for
   that user.

   538 Encryption required for requested authentication mechanism

   This response to the AUTH command indicates that the selected
   authentication mechanism may only be used when the underlying SMTP
   connection is encrypted.

   454 Temporary authentication failure

   This response to the AUTH command indicates that the authentication
   failed due to a temporary server failure.

   530 Authentication required

   This response may be returned by any command other than AUTH, EHLO,
   HELO, NOOP, RSET, or QUIT.  It indicates that server policy requires
   authentication in order to perform the requested action.


















Myers                       Standards Track                     [Page 6]

RFC 2554                  SMTP Authentication                 March 1999


7. Formal Syntax

   The following syntax specification uses the augmented Backus-Naur
   Form (BNF) notation as specified in [ABNF].

   Except as noted otherwise, all alphabetic characters are case-
   insensitive.  The use of upper or lower case characters to define
   token strings is for editorial clarity only.  Implementations MUST
   accept these strings in a case-insensitive fashion.

   UPALPHA         = %x41-5A            ;; Uppercase: A-Z

   LOALPHA         = %x61-7A            ;; Lowercase: a-z

   ALPHA           = UPALPHA / LOALPHA  ;; case insensitive

   DIGIT           = %x30-39            ;; Digits 0-9

   HEXDIGIT        = %x41-46 / DIGIT    ;; hexidecimal digit (uppercase)

   hexchar         = "+" HEXDIGIT HEXDIGIT

   xchar           = %x21-2A / %x2C-3C / %x3E-7E
                     ;; US-ASCII except for "+", "=", SPACE and CTL

   xtext           = *(xchar / hexchar)

   AUTH_CHAR       = ALPHA / DIGIT / "-" / "_"

   auth_type       = 1*20AUTH_CHAR

   auth_command    = "AUTH" SPACE auth_type [SPACE (base64 / "=")]
                     *(CRLF [base64]) CRLF

   auth_param      = "AUTH=" xtext
                       ;; The decoded form of the xtext MUST be either
                       ;; an addr-spec or the two characters "<>"

   base64          = base64_terminal /
                     ( 1*(4base64_CHAR) [base64_terminal] )

   base64_char     = UPALPHA / LOALPHA / DIGIT / "+" / "/"
                     ;; Case-sensitive

   base64_terminal = (2base64_char "==") / (3base64_char "=")

   continue_req    = "334" SPACE [base64] CRLF




Myers                       Standards Track                     [Page 7]

RFC 2554                  SMTP Authentication                 March 1999


   CR              = %x0C           ;; ASCII CR, carriage return

   CRLF            = CR LF

   CTL             = %x00-1F / %x7F ;; any ASCII control character and DEL

   LF              = %x0A           ;; ASCII LF, line feed

   SPACE           = %x20           ;; ASCII SP, space




8. References

   [ABNF]      Crocker, D. and P. Overell, "Augmented BNF for Syntax
               Specifications: ABNF", RFC 2234, November 1997.

   [CRAM-MD5]  Klensin, J., Catoe, R. and P. Krumviede, "IMAP/POP
               AUTHorize Extension for Simple Challenge/Response", RFC
               2195, September 1997.

   [ESMTP]     Klensin, J., Freed, N., Rose, M., Stefferud, E. and D.
               Crocker, "SMTP Service Extensions", RFC 1869, November
               1995.

   [ESMTP-DSN] Moore, K, "SMTP Service Extension for Delivery Status
               Notifications", RFC 1891, January 1996.

   [KEYWORDS]  Bradner, S., "Key words for use in RFCs to Indicate
               Requirement Levels", BCP 14, RFC 2119, March 1997.

   [SASL]      Myers, J., "Simple Authentication and Security Layer
               (SASL)", RFC 2222, October 1997.

   [SUBMIT]    Gellens, R. and J. Klensin, "Message Submission", RFC
               2476, December 1998.

   [RFC821]    Postel, J., "Simple Mail Transfer Protocol", STD 10, RFC
               821, August 1982.

   [RFC822]    Crocker, D., "Standard for the Format of ARPA Internet
               Text Messages", STD 11, RFC 822, August 1982.








Myers                       Standards Track                     [Page 8]

RFC 2554                  SMTP Authentication                 March 1999


9. Security Considerations

   Security issues are discussed throughout this memo.

   If a client uses this extension to get an encrypted tunnel through an
   insecure network to a cooperating server, it needs to be configured
   to never send mail to that server when the connection is not mutually
   authenticated and encrypted.  Otherwise, an attacker could steal the
   client's mail by hijacking the SMTP connection and either pretending
   the server does not support the Authentication extension or causing
   all AUTH commands to fail.

   Before the SASL negotiation has begun, any protocol interactions are
   performed in the clear and may be modified by an active attacker.
   For this reason, clients and servers MUST discard any knowledge
   obtained prior to the start of the SASL negotiation upon completion
   of a SASL negotiation which results in a security layer.

   This mechanism does not protect the TCP port, so an active attacker
   may redirect a relay connection attempt to the submission port
   [SUBMIT].  The AUTH=<> parameter prevents such an attack from causing
   an relayed message without an envelope authentication to pick up the
   authentication of the relay client.

   A message submission client may require the user to authenticate
   whenever a suitable SASL mechanism is advertised.  Therefore, it may
   not be desirable for a submission server [SUBMIT] to advertise a SASL
   mechanism when use of that mechanism grants the client no benefits
   over anonymous submission.

   This extension is not intended to replace or be used instead of end-
   to-end message signature and encryption systems such as S/MIME or
   PGP.  This extension addresses a different problem than end-to-end
   systems; it has the following key differences:

      (1) it is generally useful only within a trusted enclave

      (2) it protects the entire envelope of a message, not just the
          message's body.

      (3) it authenticates the message submission, not authorship of the
          message content

      (4) it can give the sender some assurance the message was
          delivered to the next hop in the case where the sender
          mutually authenticates with the next hop and negotiates an
          appropriate security layer.




Myers                       Standards Track                     [Page 9]

RFC 2554                  SMTP Authentication                 March 1999


   Additional security considerations are mentioned in the SASL
   specification [SASL].



10. Author's Address

   John Gardiner Myers
   Netscape Communications
   501 East Middlefield Road
   Mail Stop MV-029
   Mountain View, CA 94043

   EMail: jgmyers@netscape.com





































Myers                       Standards Track                    [Page 10]

RFC 2554                  SMTP Authentication                 March 1999


11.  Full Copyright Statement

   Copyright (C) The Internet Society (1999).  All Rights Reserved.

   This document and translations of it may be copied and furnished to
   others, and derivative works that comment on or otherwise explain it
   or assist in its implementation may be prepared, copied, published
   and distributed, in whole or in part, without restriction of any
   kind, provided that the above copyright notice and this paragraph are
   included on all such copies and derivative works.  However, this
   document itself may not be modified in any way, such as by removing
   the copyright notice or references to the Internet Society or other
   Internet organizations, except as needed for the purpose of
   developing Internet standards in which case the procedures for
   copyrights defined in the Internet Standards process must be
   followed, or as required to translate it into languages other than
   English.

   The limited permissions granted above are perpetual and will not be
   revoked by the Internet Society or its successors or assigns.

   This document and the information contained herein is provided on an
   "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
   TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
   BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
   HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
   MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
























Myers                       Standards Track                    [Page 11]



================================================
FILE: doc/notes/rfc/rfc2821.txt
================================================






Network Working Group                                 J. Klensin, Editor
Request for Comments: 2821                             AT&T Laboratories
Obsoletes: 821, 974, 1869                                     April 2001
Updates: 1123
Category: Standards Track


                     Simple Mail Transfer Protocol

Status of this Memo

   This document specifies an Internet standards track protocol for the
   Internet community, and requests discussion and suggestions for
   improvements.  Please refer to the current edition of the "Internet
   Official Protocol Standards" (STD 1) for the standardization state
   and status of this protocol.  Distribution of this memo is unlimited.

Copyright Notice

   Copyright (C) The Internet Society (2001).  All Rights Reserved.

Abstract

   This document is a self-contained specification of the basic protocol
   for the Internet electronic mail transport.  It consolidates, updates
   and clarifies, but doesn't add new or change existing functionality
   of the following:

   -  the original SMTP (Simple Mail Transfer Protocol) specification of
      RFC 821 [30],

   -  domain name system requirements and implications for mail
      transport from RFC 1035 [22] and RFC 974 [27],

   -  the clarifications and applicability statements in RFC 1123 [2],
      and

   -  material drawn from the SMTP Extension mechanisms [19].

   It obsoletes RFC 821, RFC 974, and updates RFC 1123 (replaces the
   mail transport materials of RFC 1123).  However, RFC 821 specifies
   some features that were not in significant use in the Internet by the
   mid-1990s and (in appendices) some additional transport models.
   Those sections are omitted here in the interest of clarity and
   brevity; readers needing them should refer to RFC 821.






Klensin                     Standards Track                     [Page 1]

RFC 2821             Simple Mail Transfer Protocol            April 2001


   It also includes some additional material from RFC 1123 that required
   amplification.  This material has been identified in multiple ways,
   mostly by tracking flaming on various lists and newsgroups and
   problems of unusual readings or interpretations that have appeared as
   the SMTP extensions have been deployed.  Where this specification
   moves beyond consolidation and actually differs from earlier
   documents, it supersedes them technically as well as textually.

   Although SMTP was designed as a mail transport and delivery protocol,
   this specification also contains information that is important to its
   use as a 'mail submission' protocol, as recommended for POP [3, 26]
   and IMAP [6].  Additional submission issues are discussed in RFC 2476
   [15].

   Section 2.3 provides definitions of terms specific to this document.
   Except when the historical terminology is necessary for clarity, this
   document uses the current 'client' and 'server' terminology to
   identify the sending and receiving SMTP processes, respectively.

   A companion document [32] discusses message headers, message bodies
   and formats and structures for them, and their relationship.

Table of Contents

   1. Introduction ..................................................  4
   2. The SMTP Model ................................................  5
   2.1 Basic Structure ..............................................  5
   2.2 The Extension Model ..........................................  7
   2.2.1 Background .................................................  7
   2.2.2 Definition and Registration of Extensions ..................  8
   2.3 Terminology ..................................................  9
   2.3.1 Mail Objects ............................................... 10
   2.3.2 Senders and Receivers ...................................... 10
   2.3.3 Mail Agents and Message Stores ............................. 10
   2.3.4 Host ....................................................... 11
   2.3.5 Domain ..................................................... 11
   2.3.6 Buffer and State Table ..................................... 11
   2.3.7 Lines ...................................................... 12
   2.3.8 Originator, Delivery, Relay, and Gateway Systems ........... 12
   2.3.9 Message Content and Mail Data .............................. 13
   2.3.10 Mailbox and Address ....................................... 13
   2.3.11 Reply ..................................................... 13
   2.4 General Syntax Principles and Transaction Model .............. 13
   3. The SMTP Procedures: An Overview .............................. 15
   3.1 Session Initiation ........................................... 15
   3.2 Client Initiation ............................................ 16
   3.3 Mail Transactions ............................................ 16
   3.4 Forwarding for Address Correction or Updating ................ 19



Klensin                     Standards Track                     [Page 2]

RFC 2821             Simple Mail Transfer Protocol            April 2001


   3.5 Commands for Debugging Addresses ............................. 20
   3.5.1 Overview ................................................... 20
   3.5.2 VRFY Normal Response ....................................... 22
   3.5.3 Meaning of VRFY or EXPN Success Response ................... 22
   3.5.4 Semantics and Applications of EXPN ......................... 23
   3.6 Domains ...................................................... 23
   3.7 Relaying ..................................................... 24
   3.8 Mail Gatewaying .............................................. 25
   3.8.1 Header Fields in Gatewaying ................................ 26
   3.8.2 Received Lines in Gatewaying ............................... 26
   3.8.3 Addresses in Gatewaying .................................... 26
   3.8.4 Other Header Fields in Gatewaying .......................... 27
   3.8.5 Envelopes in Gatewaying .................................... 27
   3.9 Terminating Sessions and Connections ......................... 27
   3.10 Mailing Lists and Aliases ................................... 28
   3.10.1 Alias ..................................................... 28
   3.10.2 List ...................................................... 28
   4. The SMTP Specifications ....................................... 29
   4.1 SMTP Commands ................................................ 29
   4.1.1 Command Semantics and Syntax ............................... 29
   4.1.1.1  Extended HELLO (EHLO) or HELLO (HELO) ................... 29
   4.1.1.2 MAIL (MAIL) .............................................. 31
   4.1.1.3 RECIPIENT (RCPT) ......................................... 31
   4.1.1.4 DATA (DATA) .............................................. 33
   4.1.1.5 RESET (RSET) ............................................. 34
   4.1.1.6 VERIFY (VRFY) ............................................ 35
   4.1.1.7 EXPAND (EXPN) ............................................ 35
   4.1.1.8 HELP (HELP) .............................................. 35
   4.1.1.9 NOOP (NOOP) .............................................. 35
   4.1.1.10 QUIT (QUIT) ............................................. 36
   4.1.2 Command Argument Syntax .................................... 36
   4.1.3 Address Literals ........................................... 38
   4.1.4 Order of Commands .......................................... 39
   4.1.5 Private-use Commands ....................................... 40
   4.2  SMTP Replies ................................................ 40
   4.2.1 Reply Code Severities and Theory ........................... 42
   4.2.2 Reply Codes by Function Groups ............................. 44
   4.2.3  Reply Codes in Numeric Order .............................. 45
   4.2.4 Reply Code 502 ............................................. 46
   4.2.5 Reply Codes After DATA and the Subsequent <CRLF>.<CRLF> .... 46
   4.3 Sequencing of Commands and Replies ........................... 47
   4.3.1 Sequencing Overview ........................................ 47
   4.3.2 Command-Reply Sequences .................................... 48
   4.4 Trace Information ............................................ 49
   4.5 Additional Implementation Issues ............................. 53
   4.5.1 Minimum Implementation ..................................... 53
   4.5.2 Transparency ............................................... 53
   4.5.3 Sizes and Timeouts ......................................... 54



Klensin                     Standards Track                     [Page 3]

RFC 2821             Simple Mail Transfer Protocol            April 2001


   4.5.3.1 Size limits and minimums ................................. 54
   4.5.3.2 Timeouts ................................................. 56
   4.5.4 Retry Strategies ........................................... 57
   4.5.4.1 Sending Strategy ......................................... 58
   4.5.4.2 Receiving Strategy ....................................... 59
   4.5.5 Messages with a null reverse-path .......................... 59
   5. Address Resolution and Mail Handling .......................... 60
   6. Problem Detection and Handling ................................ 62
   6.1 Reliable Delivery and Replies by Email ....................... 62
   6.2 Loop Detection ............................................... 63
   6.3 Compensating for Irregularities .............................. 63
   7. Security Considerations ....................................... 64
   7.1 Mail Security and Spoofing ................................... 64
   7.2 "Blind" Copies ............................................... 65
   7.3 VRFY, EXPN, and Security ..................................... 65
   7.4 Information Disclosure in Announcements ...................... 66
   7.5 Information Disclosure in Trace Fields ....................... 66
   7.6 Information Disclosure in Message Forwarding ................. 67
   7.7 Scope of Operation of SMTP Servers ........................... 67
   8. IANA Considerations ........................................... 67
   9. References .................................................... 68
   10. Editor's Address ............................................. 70
   11. Acknowledgments .............................................. 70
   Appendices ....................................................... 71
   A. TCP Transport Service ......................................... 71
   B. Generating SMTP Commands from RFC 822 Headers ................. 71
   C. Source Routes ................................................. 72
   D. Scenarios ..................................................... 73
   E. Other Gateway Issues .......................................... 76
   F. Deprecated Features of RFC 821 ................................ 76
   Full Copyright Statement ......................................... 79

1. Introduction

   The objective of the Simple Mail Transfer Protocol (SMTP) is to
   transfer mail reliably and efficiently.

   SMTP is independent of the particular transmission subsystem and
   requires only a reliable ordered data stream channel.  While this
   document specifically discusses transport over TCP, other transports
   are possible.  Appendices to RFC 821 describe some of them.

   An important feature of SMTP is its capability to transport mail
   across networks, usually referred to as "SMTP mail relaying" (see
   section 3.8).  A network consists of the mutually-TCP-accessible
   hosts on the public Internet, the mutually-TCP-accessible hosts on a
   firewall-isolated TCP/IP Intranet, or hosts in some other LAN or WAN
   environment utilizing a non-TCP transport-level protocol.  Using



Klensin                     Standards Track                     [Page 4]

RFC 2821             Simple Mail Transfer Protocol            April 2001


   SMTP, a process can transfer mail to another process on the same
   network or to some other network via a relay or gateway process
   accessible to both networks.

   In this way, a mail message may pass through a number of intermediate
   relay or gateway hosts on its path from sender to ultimate recipient.
   The Mail eXchanger mechanisms of the domain name system [22, 27] (and
   section 5 of this document) are used to identify the appropriate
   next-hop destination for a message being transported.

2. The SMTP Model

2.1 Basic Structure

   The SMTP design can be pictured as:

               +----------+                +----------+
   +------+    |          |                |          |
   | User |<-->|          |      SMTP      |          |
   +------+    |  Client- |Commands/Replies| Server-  |
   +------+    |   SMTP   |<-------------->|    SMTP  |    +------+
   | File |<-->|          |    and Mail    |          |<-->| File |
   |System|    |          |                |          |    |System|
   +------+    +----------+                +----------+    +------+
                SMTP client                SMTP server

   When an SMTP client has a message to transmit, it establishes a two-
   way transmission channel to an SMTP server.  The responsibility of an
   SMTP client is to transfer mail messages to one or more SMTP servers,
   or report its failure to do so.

   The means by which a mail message is presented to an SMTP client, and
   how that client determines the domain name(s) to which mail messages
   are to be transferred is a local matter, and is not addressed by this
   document.  In some cases, the domain name(s) transferred to, or
   determined by, an SMTP client will identify the final destination(s)
   of the mail message.  In other cases, common with SMTP clients
   associated with implementations of the POP [3, 26] or IMAP [6]
   protocols, or when the SMTP client is inside an isolated transport
   service environment, the domain name determined will identify an
   intermediate destination through which all mail messages are to be
   relayed.  SMTP clients that transfer all traffic, regardless of the
   target domain names associated with the individual messages, or that
   do not maintain queues for retrying message transmissions that
   initially cannot be completed, may otherwise conform to this
   specification but are not considered fully-capable.  Fully-capable
   SMTP implementations, including the relays used by these less capable




Klensin                     Standards Track                     [Page 5]

RFC 2821             Simple Mail Transfer Protocol            April 2001


   ones, and their destinations, are expected to support all of the
   queuing, retrying, and alternate address functions discussed in this
   specification.

   The means by which an SMTP client, once it has determined a target
   domain name, determines the identity of an SMTP server to which a
   copy of a message is to be transferred, and then performs that
   transfer, is covered by this document.  To effect a mail transfer to
   an SMTP server, an SMTP client establishes a two-way transmission
   channel to that SMTP server.  An SMTP client determines the address
   of an appropriate host running an SMTP server by resolving a
   destination domain name to either an intermediate Mail eXchanger host
   or a final target host.

   An SMTP server may be either the ultimate destination or an
   intermediate "relay" (that is, it may assume the role of an SMTP
   client after receiving the message) or "gateway" (that is, it may
   transport the message further using some protocol other than SMTP).
   SMTP commands are generated by the SMTP client and sent to the SMTP
   server.  SMTP replies are sent from the SMTP server to the SMTP
   client in response to the commands.

   In other words, message transfer can occur in a single connection
   between the original SMTP-sender and the final SMTP-recipient, or can
   occur in a series of hops through intermediary systems.  In either
   case, a formal handoff of responsibility for the message occurs: the
   protocol requires that a server accept responsibility for either
   delivering a message or properly reporting the failure to do so.

   Once the transmission channel is established and initial handshaking
   completed, the SMTP client normally initiates a mail transaction.
   Such a transaction consists of a series of commands to specify the
   originator and destination of the mail and transmission of the
   message content (including any headers or other structure) itself.
   When the same message is sent to multiple recipients, this protocol
   encourages the transmission of only one copy of the data for all
   recipients at the same destination (or intermediate relay) host.

   The server responds to each command with a reply; replies may
   indicate that the command was accepted, that additional commands are
   expected, or that a temporary or permanent error condition exists.
   Commands specifying the sender or recipients may include server-
   permitted SMTP service extension requests as discussed in section
   2.2.  The dialog is purposely lock-step, one-at-a-time, although this
   can be modified by mutually-agreed extension requests such as command
   pipelining [13].





Klensin                     Standards Track                     [Page 6]

RFC 2821             Simple Mail Transfer Protocol            April 2001


   Once a given mail message has been transmitted, the client may either
   request that the connection be shut down or may initiate other mail
   transactions.  In addition, an SMTP client may use a connection to an
   SMTP server for ancillary services such as verification of email
   addresses or retrieval of mailing list subscriber addresses.

   As suggested above, this protocol provides mechanisms for the
   transmission of mail.  This transmission normally occurs directly
   from the sending user's host to the receiving user's host when the
   two hosts are connected to the same transport service.  When they are
   not connected to the same transport service, transmission occurs via
   one or more relay SMTP servers.  An intermediate host that acts as
   either an SMTP relay or as a gateway into some other transmission
   environment is usually selected through the use of the domain name
   service (DNS) Mail eXchanger mechanism.

   Usually, intermediate hosts are determined via the DNS MX record, not
   by explicit "source" routing (see section 5 and appendices C and
   F.2).

2.2 The Extension Model

2.2.1 Background

   In an effort that started in 1990, approximately a decade after RFC
   821 was completed, the protocol was modified with a "service
   extensions" model that permits the client and server to agree to
   utilize shared functionality beyond the original SMTP requirements.
   The SMTP extension mechanism defines a means whereby an extended SMTP
   client and server may recognize each other, and the server can inform
   the client as to the service extensions that it supports.

   Contemporary SMTP implementations MUST support the basic extension
   mechanisms.  For instance, servers MUST support the EHLO command even
   if they do not implement any specific extensions and clients SHOULD
   preferentially utilize EHLO rather than HELO.  (However, for
   compatibility with older conforming implementations, SMTP clients and
   servers MUST support the original HELO mechanisms as a fallback.)
   Unless the different characteristics of HELO must be identified for
   interoperability purposes, this document discusses only EHLO.

   SMTP is widely deployed and high-quality implementations have proven
   to be very robust.  However, the Internet community now considers
   some services to be important that were not anticipated when the
   protocol was first designed.  If support for those services is to be
   added, it must be done in a way that permits older implementations to
   continue working acceptably.  The extension framework consists of:




Klensin                     Standards Track                     [Page 7]

RFC 2821             Simple Mail Transfer Protocol            April 2001


   -  The SMTP command EHLO, superseding the earlier HELO,

   -  a registry of SMTP service extensions,

   -  additional parameters to the SMTP MAIL and RCPT commands, and

   -  optional replacements for commands defined in this protocol, such
      as for DATA in non-ASCII transmissions [33].

   SMTP's strength comes primarily from its simplicity.  Experience with
   many protocols has shown that protocols with few options tend towards
   ubiquity, whereas protocols with many options tend towards obscurity.

   Each and every extension, regardless of its benefits, must be
   carefully scrutinized with respect to its implementation, deployment,
   and interoperability costs.  In many cases, the cost of extending the
   SMTP service will likely outweigh the benefit.

2.2.2 Definition and Registration of Extensions

   The IANA maintains a registry of SMTP service extensions.  A
   corresponding EHLO keyword value is associated with each extension.
   Each service extension registered with the IANA must be defined in a
   formal standards-track or IESG-approved experimental protocol
   document.  The definition must include:

   -  the textual name of the SMTP service extension;

   -  the EHLO keyword value associated with the extension;

   -  the syntax and possible values of parameters associated with the
      EHLO keyword value;

   -  any additional SMTP verbs associated with the extension
      (additional verbs will usually be, but are not required to be, the
      same as the EHLO keyword value);

   -  any new parameters the extension associates with the MAIL or RCPT
      verbs;

   -  a description of how support for the extension affects the
      behavior of a server and client SMTP; and,

   -  the increment by which the extension is increasing the maximum
      length of the commands MAIL and/or RCPT, over that specified in
      this standard.





Klensin                     Standards Track                     [Page 8]

RFC 2821             Simple Mail Transfer Protocol            April 2001


   In addition, any EHLO keyword value starting with an upper or lower
   case "X" refers to a local SMTP service extension used exclusively
   through bilateral agreement.  Keywords beginning with "X" MUST NOT be
   used in a registered service extension.  Conversely, keyword values
   presented in the EHLO response that do not begin with "X" MUST
   correspond to a standard, standards-track, or IESG-approved
   experimental SMTP service extension registered with IANA.  A
   conforming server MUST NOT offer non-"X"-prefixed keyword values that
   are not described in a registered extension.

   Additional verbs and parameter names are bound by the same rules as
   EHLO keywords; specifically, verbs beginning with "X" are local
   extensions that may not be registered or standardized.  Conversely,
   verbs not beginning with "X" must always be registered.

2.3 Terminology

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   document are to be interpreted as described below.

   1. MUST   This word, or the terms "REQUIRED" or "SHALL", mean that
      the definition is an absolute requirement of the specification.

   2. MUST NOT   This phrase, or the phrase "SHALL NOT", mean that the
      definition is an absolute prohibition of the specification.

   3. SHOULD   This word, or the adjective "RECOMMENDED", mean that
      there may exist valid reasons in particular circumstances to
      ignore a particular item, but the full implications must be
      understood and carefully weighed before choosing a different
      course.

   4. SHOULD NOT   This phrase, or the phrase "NOT RECOMMENDED" mean
      that there may exist valid reasons in particular circumstances
      when the particular behavior is acceptable or even useful, but the
      full implications should be understood and the case carefully
      weighed before implementing any behavior described with this
      label.

   5. MAY   This word, or the adjective "OPTIONAL", mean that an item is
      truly optional.  One vendor may choose to include the item because
      a particular marketplace requires it or because the vendor feels
      that it enhances the product while another vendor may omit the
      same item.  An implementation which does not include a particular
      option MUST be prepared to interoperate with another
      implementation which does include the option, though perhaps with
      reduced functionality.  In the same vein an implementation which



Klensin                     Standards Track                     [Page 9]

RFC 2821             Simple Mail Transfer Protocol            April 2001


      does include a particular option MUST be prepared to interoperate
      with another implementation which does not include the option
      (except, of course, for the feature the option provides.)

2.3.1 Mail Objects

   SMTP transports a mail object.  A mail object contains an envelope
   and content.

   The SMTP envelope is sent as a series of SMTP protocol units
   (described in section 3).  It consists of an originator address (to
   which error reports should be directed); one or more recipient
   addresses; and optional protocol extension material.  Historically,
   variations on the recipient address specification command (RCPT TO)
   could be used to specify alternate delivery modes, such as immediate
   display; those variations have now been deprecated (see appendix F,
   section F.6).

   The SMTP content is sent in the SMTP DATA protocol unit and has two
   parts:  the headers and the body.  If the content conforms to other
   contemporary standards, the headers form a collection of field/value
   pairs structured as in the message format specification [32]; the
   body, if structured, is defined according to MIME [12].  The content
   is textual in nature, expressed using the US-ASCII repertoire [1].
   Although SMTP extensions (such as "8BITMIME" [20]) may relax this
   restriction for the content body, the content headers are always
   encoded using the US-ASCII repertoire.  A MIME extension [23] defines
   an algorithm for representing header values outside the US-ASCII
   repertoire, while still encoding them using the US-ASCII repertoire.

2.3.2 Senders and Receivers

   In RFC 821, the two hosts participating in an SMTP transaction were
   described as the "SMTP-sender" and "SMTP-receiver".  This document
   has been changed to reflect current industry terminology and hence
   refers to them as the "SMTP client" (or sometimes just "the client")
   and "SMTP server" (or just "the server"), respectively.  Since a
   given host may act both as server and client in a relay situation,
   "receiver" and "sender" terminology is still used where needed for
   clarity.

2.3.3 Mail Agents and Message Stores

   Additional mail system terminology became common after RFC 821 was
   published and, where convenient, is used in this specification.  In
   particular, SMTP servers and clients provide a mail transport service
   and therefore act as "Mail Transfer Agents" (MTAs).  "Mail User
   Agents" (MUAs or UAs) are normally thought of as the sources and



Klensin                     Standards Track                    [Page 10]

RFC 2821             Simple Mail Transfer Protocol            April 2001


   targets of mail.  At the source, an MUA might collect mail to be
   transmitted from a user and hand it off to an MTA; the final
   ("delivery") MTA would be thought of as handing the mail off to an
   MUA (or at least transferring responsibility to it, e.g., by
   depositing the message in a "message store").  However, while these
   terms are used with at least the appearance of great precision in
   other environments, the implied boundaries between MUAs and MTAs
   often do not accurately match common, and conforming, practices with
   Internet mail.  Hence, the reader should be cautious about inferring
   the strong relationships and responsibilities that might be implied
   if these terms were used elsewhere.

2.3.4 Host

   For the purposes of this specification, a host is a computer system
   attached to the Internet (or, in some cases, to a private TCP/IP
   network) and supporting the SMTP protocol.  Hosts are known by names
   (see "domain"); identifying them by numerical address is discouraged.

2.3.5 Domain

   A domain (or domain name) consists of one or more dot-separated
   components.  These components ("labels" in DNS terminology [22]) are
   restricted for SMTP purposes to consist of a sequence of letters,
   digits, and hyphens drawn from the ASCII character set [1].  Domain
   names are used as names of hosts and of other entities in the domain
   name hierarchy.  For example, a domain may refer to an alias (label
   of a CNAME RR) or the label of Mail eXchanger records to be used to
   deliver mail instead of representing a host name.  See [22] and
   section 5 of this specification.

   The domain name, as described in this document and in [22], is the
   entire, fully-qualified name (often referred to as an "FQDN").  A
   domain name that is not in FQDN form is no more than a local alias.
   Local aliases MUST NOT appear in any SMTP transaction.

2.3.6 Buffer and State Table

   SMTP sessions are stateful, with both parties carefully maintaining a
   common view of the current state.  In this document we model this
   state by a virtual "buffer" and a "state table" on the server which
   may be used by the client to, for example, "clear the buffer" or
   "reset the state table," causing the information in the buffer to be
   discarded and the state to be returned to some previous state.







Klensin                     Standards Track                    [Page 11]

RFC 2821             Simple Mail Transfer Protocol            April 2001


2.3.7 Lines

   SMTP commands and, unless altered by a service extension, message
   data, are transmitted in "lines".  Lines consist of zero or more data
   characters terminated by the sequence ASCII character "CR" (hex value
   0D) followed immediately by ASCII character "LF" (hex value 0A).
   This termination sequence is denoted as <CRLF> in this document.
   Conforming implementations MUST NOT recognize or generate any other
   character or character sequence as a line terminator.  Limits MAY be
   imposed on line lengths by servers (see section 4.5.3).

   In addition, the appearance of "bare" "CR" or "LF" characters in text
   (i.e., either without the other) has a long history of causing
   problems in mail implementations and applications that use the mail
   system as a tool.  SMTP client implementations MUST NOT transmit
   these characters except when they are intended as line terminators
   and then MUST, as indicated above, transmit them only as a <CRLF>
   sequence.

2.3.8 Originator, Delivery, Relay, and Gateway Systems

   This specification makes a distinction among four types of SMTP
   systems, based on the role those systems play in transmitting
   electronic mail.  An "originating" system (sometimes called an SMTP
   originator) introduces mail into the Internet or, more generally,
   into a transport service environment.  A "delivery" SMTP system is
   one that receives mail from a transport service environment and
   passes it to a mail user agent or deposits it in a message store
   which a mail user agent is expected to subsequently access.  A
   "relay" SMTP system (usually referred to just as a "relay") receives
   mail from an SMTP client and transmits it, without modification to
   the message data other than adding trace information, to another SMTP
   server for further relaying or for delivery.

   A "gateway" SMTP system (usually referred to just as a "gateway")
   receives mail from a client system in one transport environment and
   transmits it to a server system in another transport environment.
   Differences in protocols or message semantics between the transport
   environments on either side of a gateway may require that the gateway
   system perform transformations to the message that are not permitted
   to SMTP relay systems.  For the purposes of this specification,
   firewalls that rewrite addresses should be considered as gateways,
   even if SMTP is used on both sides of them (see [11]).








Klensin                     Standards Track                    [Page 12]

RFC 2821             Simple Mail Transfer Protocol            April 2001


2.3.9 Message Content and Mail Data

   The terms "message content" and "mail data" are used interchangeably
   in this document to describe the material transmitted after the DATA
   command is accepted and before the end of data indication is
   transmitted.  Message content includes message headers and the
   possibly-structured message body.  The MIME specification [12]
   provides the standard mechanisms for structured message bodies.

2.3.10 Mailbox and Address

   As used in this specification, an "address" is a character string
   that identifies a user to whom mail will be sent or a location into
   which mail will be deposited.  The term "mailbox" refers to that
   depository.  The two terms are typically used interchangeably unless
   the distinction between the location in which mail is placed (the
   mailbox) and a reference to it (the address) is important.  An
   address normally consists of user and domain specifications.  The
   standard mailbox naming convention is defined to be "local-
   part@domain": contemporary usage permits a much broader set of
   applications than simple "user names".  Consequently, and due to a
   long history of problems when intermediate hosts have attempted to
   optimize transport by modifying them, the local-part MUST be
   interpreted and assigned semantics only by the host specified in the
   domain part of the address.

2.3.11 Reply

   An SMTP reply is an acknowledgment (positive or negative) sent from
   receiver to sender via the transmission channel in response to a
   command.  The general form of a reply is a numeric completion code
   (indicating failure or success) usually followed by a text string.
   The codes are for use by programs and the text is usually intended
   for human users.  Recent work [34] has specified further structuring
   of the reply strings, including the use of supplemental and more
   specific completion codes.

2.4 General Syntax Principles and Transaction Model

   SMTP commands and replies have a rigid syntax.  All commands begin
   with a command verb.  All Replies begin with a three digit numeric
   code.  In some commands and replies, arguments MUST follow the verb
   or reply code.  Some commands do not accept arguments (after the
   verb), and some reply codes are followed, sometimes optionally, by
   free form text.  In both cases, where text appears, it is separated
   from the verb or reply code by a space character.  Complete
   definitions of commands and replies appear in section 4.




Klensin                     Standards Track                    [Page 13]

RFC 2821             Simple Mail Transfer Protocol            April 2001


   Verbs and argument values (e.g., "TO:" or "to:" in the RCPT command
   and extension name keywords) are not case sensitive, with the sole
   exception in this specification of a mailbox local-part (SMTP
   Extensions may explicitly specify case-sensitive elements).  That is,
   a command verb, an argument value other than a mailbox local-part,
   and free form text MAY be encoded in upper case, lower case, or any
   mixture of upper and lower case with no impact on its meaning.  This
   is NOT true of a mailbox local-part.  The local-part of a mailbox
   MUST BE treated as case sensitive.  Therefore, SMTP implementations
   MUST take care to preserve the case of mailbox local-parts.  Mailbox
   domains are not case sensitive.  In particular, for some hosts the
   user "smith" is different from the user "Smith".  However, exploiting
   the case sensitivity of mailbox local-parts impedes interoperability
   and is discouraged.

   A few SMTP servers, in violation of this specification (and RFC 821)
   require that command verbs be encoded by clients in upper case.
   Implementations MAY wish to employ this encoding to accommodate those
   servers.

   The argument field consists of a variable length character string
   ending with the end of the line, i.e., with the character sequence
   <CRLF>.  The receiver will take no action until this sequence is
   received.

   The syntax for each command is shown with the discussion of that
   command.  Common elements and parameters are shown in section 4.1.2.

   Commands and replies are composed of characters from the ASCII
   character set [1].  When the transport service provides an 8-bit byte
   (octet) transmission channel, each 7-bit character is transmitted
   right justified in an octet with the high order bit cleared to zero.
   More specifically, the unextended SMTP service provides seven bit
   transport only.  An originating SMTP client which has not
   successfully negotiated an appropriate extension with a particular
   server MUST NOT transmit messages with information in the high-order
   bit of octets.  If such messages are transmitted in violation of this
   rule, receiving SMTP servers MAY clear the high-order bit or reject
   the message as invalid.  In general, a relay SMTP SHOULD assume that
   the message content it has received is valid and, assuming that the
   envelope permits doing so, relay it without inspecting that content.
   Of course, if the content is mislabeled and the data path cannot
   accept the actual content, this may result in ultimate delivery of a
   severely garbled message to the recipient.  Delivery SMTP systems MAY
   reject ("bounce") such messages rather than deliver them.  No sending
   SMTP system is permitted to send envelope commands in any character





Klensin                     Standards Track                    [Page 14]

RFC 2821             Simple Mail Transfer Protocol            April 2001


   set other than US-ASCII; receiving systems SHOULD reject such
   commands, normally using "500 syntax error - invalid character"
   replies.

   Eight-bit message content transmission MAY be requested of the server
   by a client using extended SMTP facilities, notably the "8BITMIME"
   extension [20].  8BITMIME SHOULD be supported by SMTP servers.
   However, it MUST not be construed as authorization to transmit
   unrestricted eight bit material.  8BITMIME MUST NOT be requested by
   senders for material with the high bit on that is not in MIME format
   with an appropriate content-transfer encoding; servers MAY reject
   such messages.

   The metalinguistic notation used in this document corresponds to the
   "Augmented BNF" used in other Internet mail system documents.  The
   reader who is not familiar with that syntax should consult the ABNF
   specification [8].  Metalanguage terms used in running text are
   surrounded by pointed brackets (e.g., <CRLF>) for clarity.

3. The SMTP Procedures: An Overview

   This section contains descriptions of the procedures used in SMTP:
   session initiation, the mail transaction, forwarding mail, verifying
   mailbox names and expanding mailing lists, and the opening and
   closing exchanges.  Comments on relaying, a note on mail domains, and
   a discussion of changing roles are included at the end of this
   section.  Several complete scenarios are presented in appendix D.

3.1 Session Initiation

   An SMTP session is initiated when a client opens a connection to a
   server and the server responds with an opening message.

   SMTP server implementations MAY include identification of their
   software and version information in the connection greeting reply
   after the 220 code, a practice that permits more efficient isolation
   and repair of any problems.  Implementations MAY make provision for
   SMTP servers to disable the software and version announcement where
   it causes security concerns.  While some systems also identify their
   contact point for mail problems, this is not a substitute for
   maintaining the required "postmaster" address (see section 4.5.1).

   The SMTP protocol allows a server to formally reject a transaction
   while still allowing the initial connection as follows: a 554
   response MAY be given in the initial connection opening message
   instead of the 220.  A server taking this approach MUST still wait
   for the client to send a QUIT (see section 4.1.1.10) before closing
   the connection and SHOULD respond to any intervening commands with



Klensin                     Standards Track                    [Page 15]

RFC 2821             Simple Mail Transfer Protocol            April 2001


   "503 bad sequence of commands".  Since an attempt to make an SMTP
   connection to such a system is probably in error, a server returning
   a 554 response on connection opening SHOULD provide enough
   information in the reply text to facilitate debugging of the sending
   system.

3.2 Client Initiation

   Once the server has sent the welcoming message and the client has
   received it, the client normally sends the EHLO command to the
   server, indicating the client's identity.  In addition to opening the
   session, use of EHLO indicates that the client is able to process
   service extensions and requests that the server provide a list of the
   extensions it supports.  Older SMTP systems which are unable to
   support service extensions and contemporary clients which do not
   require service extensions in the mail session being initiated, MAY
   use HELO instead of EHLO.  Servers MUST NOT return the extended
   EHLO-style response to a HELO command.  For a particular connection
   attempt, if the server returns a "command not recognized" response to
   EHLO, the client SHOULD be able to fall back and send HELO.

   In the EHLO command the host sending the command identifies itself;
   the command may be interpreted as saying "Hello, I am <domain>" (and,
   in the case of EHLO, "and I support service extension requests").

3.3 Mail Transactions

   There are three steps to SMTP mail transactions.  The transaction
   starts with a MAIL command which gives the sender identification.
   (In general, the MAIL command may be sent only when no mail
   transaction is in progress; see section 4.1.4.)  A series of one or
   more RCPT commands follows giving the receiver information.  Then a
   DATA command initiates transfer of the mail data and is terminated by
   the "end of mail" data indicator, which also confirms the
   transaction.

   The first step in the procedure is the MAIL command.

      MAIL FROM:<reverse-path> [SP <mail-parameters> ] <CRLF>

   This command tells the SMTP-receiver that a new mail transaction is
   starting and to reset all its state tables and buffers, including any
   recipients or mail data.  The <reverse-path> portion of the first or
   only argument contains the source mailbox (between "<" and ">"
   brackets), which can be used to report errors (see section 4.2 for a
   discussion of error reporting).  If accepted, the SMTP server returns
   a 250 OK reply.  If the mailbox specification is not acceptable for
   some reason, the server MUST return a reply indicating whether the



Klensin                     Standards Track                    [Page 16]

RFC 2821             Simple Mail Transfer Protocol            April 2001


   failure is permanent (i.e., will occur again if the client tries to
   send the same address again) or temporary (i.e., the address might be
   accepted if the client tries again later).  Despite the apparent
   scope of this requirement, there are circumstances in which the
   acceptability of the reverse-path may not be determined until one or
   more forward-paths (in RCPT commands) can be examined.  In those
   cases, the server MAY reasonably accept the reverse-path (with a 250
   reply) and then report problems after the forward-paths are received
   and examined.  Normally, failures produce 550 or 553 replies.

   Historically, the <reverse-path> can contain more than just a
   mailbox, however, contemporary systems SHOULD NOT use source routing
   (see appendix C).

   The optional <mail-parameters> are associated with negotiated SMTP
   service extensions (see section 2.2).

   The second step in the procedure is the RCPT command.

      RCPT TO:<forward-path> [ SP <rcpt-parameters> ] <CRLF>

   The first or only argument to this command includes a forward-path
   (normally a mailbox and domain, always surrounded by "<" and ">"
   brackets) identifying one recipient.  If accepted, the SMTP server
   returns a 250 OK reply and stores the forward-path.  If the recipient
   is known not to be a deliverable address, the SMTP server returns a
   550 reply, typically with a string such as "no such user - " and the
   mailbox name (other circumstances and reply codes are possible).
   This step of the procedure can be repeated any number of times.

   The <forward-path> can contain more than just a mailbox.
   Historically, the <forward-path> can be a source routing list of
   hosts and the destination mailbox, however, contemporary SMTP clients
   SHOULD NOT utilize source routes (see appendix C).  Servers MUST be
   prepared to encounter a list of source routes in the forward path,
   but SHOULD ignore the routes or MAY decline to support the relaying
   they imply.  Similarly, servers MAY decline to accept mail that is
   destined for other hosts or systems.  These restrictions make a
   server useless as a relay for clients that do not support full SMTP
   functionality.  Consequently, restricted-capability clients MUST NOT
   assume that any SMTP server on the Internet can be used as their mail
   processing (relaying) site.  If a RCPT command appears without a
   previous MAIL command, the server MUST return a 503 "Bad sequence of
   commands" response.  The optional <rcpt-parameters> are associated
   with negotiated SMTP service extensions (see section 2.2).

   The third step in the procedure is the DATA command (or some
   alternative specified in a service extension).



Klensin                     Standards Track                    [Page 17]

RFC 2821             Simple Mail Transfer Protocol            April 2001


      DATA <CRLF>

   If accepted, the SMTP server returns a 354 Intermediate reply and
   considers all succeeding lines up to but not including the end of
   mail data indicator to be the message text.  When the end of text is
   successfully received and stored the SMTP-receiver sends a 250 OK
   reply.

   Since the mail data is sent on the transmission channel, the end of
   mail data must be indicated so that the command and reply dialog can
   be resumed.  SMTP indicates the end of the mail data by sending a
   line containing only a "." (period or full stop).  A transparency
   procedure is used to prevent this from interfering with the user's
   text (see section 4.5.2).

   The end of mail data indicator also confirms the mail transaction and
   tells the SMTP server to now process the stored recipients and mail
   data.  If accepted, the SMTP server returns a 250 OK reply.  The DATA
   command can fail at only two points in the protocol exchange:

   -  If there was no MAIL, or no RCPT, command, or all such commands
      were rejected, the server MAY return a "command out of sequence"
      (503) or "no valid recipients" (554) reply in response to the DATA
      command.  If one of those replies (or any other 5yz reply) is
      received, the client MUST NOT send the message data; more
      generally, message data MUST NOT be sent unless a 354 reply is
      received.

   -  If the verb is initially accepted and the 354 reply issued, the
      DATA command should fail only if the mail transaction was
      incomplete (for example, no recipients), or if resources were
      unavailable (including, of course, the server unexpectedly
      becoming unavailable), or if the server determines that the
      message should be rejected for policy or other reasons.

   However, in practice, some servers do not perform recipient
   verification until after the message text is received.  These servers
   SHOULD treat a failure for one or more recipients as a "subsequent
   failure" and return a mail message as discussed in section 6.  Using
   a "550 mailbox not found" (or equivalent) reply code after the data
   are accepted makes it difficult or impossible for the client to
   determine which recipients failed.

   When RFC 822 format [7, 32] is being used, the mail data include the
   memo header items such as Date, Subject, To, Cc, From.  Server SMTP
   systems SHOULD NOT reject messages based on perceived defects in the
   RFC 822 or MIME [12] message header or message body.  In particular,




Klensin                     Standards Track                    [Page 18]

RFC 2821             Simple Mail Transfer Protocol            April 2001


   they MUST NOT reject messages in which the numbers of Resent-fields
   do not match or Resent-to appears without Resent-from and/or Resent-
   date.

   Mail transaction commands MUST be used in the order discussed above.

3.4 Forwarding for Address Correction or Updating

   Forwarding support is most often required to consolidate and simplify
   addresses within, or relative to, some enterprise and less frequently
   to establish addresses to link a person's prior address with current
   one.  Silent forwarding of messages (without server notification to
   the sender), for security or non-disclosure purposes, is common in
   the contemporary Internet.

   In both the enterprise and the "new address" cases, information
   hiding (and sometimes security) considerations argue against exposure
   of the "final" address through the SMTP protocol as a side-effect of
   the forwarding activity.  This may be especially important when the
   final address may not even be reachable by the sender.  Consequently,
   the "forwarding" mechanisms described in section 3.2 of RFC 821, and
   especially the 251 (corrected destination) and 551 reply codes from
   RCPT must be evaluated carefully by implementers and, when they are
   available, by those configuring systems.

   In particular:

   *  Servers MAY forward messages when they are aware of an address
      change.  When they do so, they MAY either provide address-updating
      information with a 251 code, or may forward "silently" and return
      a 250 code.  But, if a 251 code is used, they MUST NOT assume that
      the client will actually update address information or even return
      that information to the user.

   Alternately,

   *  Servers MAY reject or bounce messages when they are not
      deliverable when addressed.  When they do so, they MAY either
      provide address-updating information with a 551 code, or may
      reject the message as undeliverable with a 550 code and no
      address-specific information.  But, if a 551 code is used, they
      MUST NOT assume that the client will actually update address
      information or even return that information to the user.

   SMTP server implementations that support the 251 and/or 551 reply
   codes are strongly encouraged to provide configuration mechanisms so
   that sites which conclude that they would undesirably disclose
   information can disable or restrict their use.



Klensin                     Standards Track                    [Page 19]

RFC 2821             Simple Mail Transfer Protocol            April 2001


3.5 Commands for Debugging Addresses

3.5.1 Overview

   SMTP provides commands to verify a user name or obtain the content of
   a mailing list.  This is done with the VRFY and EXPN commands, which
   have character string arguments.  Implementations SHOULD support VRFY
   and EXPN (however, see section 3.5.2 and 7.3).

   For the VRFY command, the string is a user name or a user name and
   domain (see below).  If a normal (i.e., 250) response is returned,
   the response MAY include the full name of the user and MUST include
   the mailbox of the user.  It MUST be in either of the following
   forms:

      User Name <local-part@domain>
      local-part@domain

   When a name that is the argument to VRFY could identify more than one
   mailbox, the server MAY either note the ambiguity or identify the
   alternatives.  In other words, any of the following are legitimate
   response to VRFY:

      553 User ambiguous

   or

      553- Ambiguous;  Possibilities are
      553-Joe Smith <jsmith@foo.com>
      553-Harry Smith <hsmith@foo.com>
      553 Melvin Smith <dweep@foo.com>

   or

      553-Ambiguous;  Possibilities
      553- <jsmith@foo.com>
      553- <hsmith@foo.com>
      553 <dweep@foo.com>

   Under normal circumstances, a client receiving a 553 reply would be
   expected to expose the result to the user.  Use of exactly the forms
   given, and the "user ambiguous" or "ambiguous" keywords, possibly
   supplemented by extended reply codes such as those described in [34],
   will facilitate automated translation into other languages as needed.
   Of course, a client that was highly automated or that was operating
   in another language than English, might choose to try to translate
   the response, to return some other indication to the user than the




Klensin                     Standards Track                    [Page 20]

RFC 2821             Simple Mail Transfer Protocol            April 2001


   literal text of the reply, or to take some automated action such as
   consulting a directory service for additional information before
   reporting to the user.

   For the EXPN command, the string identifies a mailing list, and the
   successful (i.e., 250) multiline response MAY include the full name
   of the users and MUST give the mailboxes on the mailing list.

   In some hosts the distinction between a mailing list and an alias for
   a single mailbox is a bit fuzzy, since a common data structure may
   hold both types of entries, and it is possible to have mailing lists
   containing only one mailbox.  If a request is made to apply VRFY to a
   mailing list, a positive response MAY be given if a message so
   addressed would be delivered to everyone on the list, otherwise an
   error SHOULD be reported (e.g., "550 That is a mailing list, not a
   user" or "252 Unable to verify members of mailing list").  If a
   request is made to expand a user name, the server MAY return a
   positive response consisting of a list containing one name, or an
   error MAY be reported (e.g., "550 That is a user name, not a mailing
   list").

   In the case of a successful multiline reply (normal for EXPN) exactly
   one mailbox is to be specified on each line of the reply.  The case
   of an ambiguous request is discussed above.

   "User name" is a fuzzy term and has been used deliberately.  An
   implementation of the VRFY or EXPN commands MUST include at least
   recognition of local mailboxes as "user names".  However, since
   current Internet practice often results in a single host handling
   mail for multiple domains, hosts, especially hosts that provide this
   functionality, SHOULD accept the "local-part@domain" form as a "user
   name"; hosts MAY also choose to recognize other strings as "user
   names".

   The case of expanding a mailbox list requires a multiline reply, such
   as:

      C: EXPN Example-People
      S: 250-Jon Postel <Postel@isi.edu>
      S: 250-Fred Fonebone <Fonebone@physics.foo-u.edu>
      S: 250 Sam Q. Smith <SQSmith@specific.generic.com>

   or

      C: EXPN Executive-Washroom-List
      S: 550 Access Denied to You.





Klensin                     Standards Track                    [Page 21]

RFC 2821             Simple Mail Transfer Protocol            April 2001


   The character string arguments of the VRFY and EXPN commands cannot
   be further restricted due to the variety of implementations of the
   user name and mailbox list concepts.  On some systems it may be
   appropriate for the argument of the EXPN command to be a file name
   for a file containing a mailing list, but again there are a variety
   of file naming conventions in the Internet.  Similarly, historical
   variations in what is returned by these commands are such that the
   response SHOULD be interpreted very carefully, if at all, and SHOULD
   generally only be used for diagnostic purposes.

3.5.2 VRFY Normal Response

   When normal (2yz or 551) responses are returned from a VRFY or EXPN
   request, the reply normally includes the mailbox name, i.e.,
   "<local-part@domain>", where "domain" is a fully qualified domain
   name, MUST appear in the syntax.  In circumstances exceptional enough
   to justify violating the intent of this specification, free-form text
   MAY be returned.  In order to facilitate parsing by both computers
   and people, addresses SHOULD appear in pointed brackets.  When
   addresses, rather than free-form debugging information, are returned,
   EXPN and VRFY MUST return only valid domain addresses that are usable
   in SMTP RCPT commands.  Consequently, if an address implies delivery
   to a program or other system, the mailbox name used to reach that
   target MUST be given.  Paths (explicit source routes) MUST NOT be
   returned by VRFY or EXPN.

   Server implementations SHOULD support both VRFY and EXPN.  For
   security reasons, implementations MAY provide local installations a
   way to disable either or both of these commands through configuration
   options or the equivalent.  When these commands are supported, they
   are not required to work across relays when relaying is supported.
   Since they were both optional in RFC 821, they MUST be listed as
   service extensions in an EHLO response, if they are supported.

3.5.3 Meaning of VRFY or EXPN Success Response

   A server MUST NOT return a 250 code in response to a VRFY or EXPN
   command unless it has actually verified the address.  In particular,
   a server MUST NOT return 250 if all it has done is to verify that the
   syntax given is valid.  In that case, 502 (Command not implemented)
   or 500 (Syntax error, command unrecognized) SHOULD be returned.  As
   stated elsewhere, implementation (in the sense of actually validating
   addresses and returning information) of VRFY and EXPN are strongly
   recommended.  Hence, implementations that return 500 or 502 for VRFY
   are not in full compliance with this specification.






Klensin                     Standards Track                    [Page 22]

RFC 2821             Simple Mail Transfer Protocol            April 2001


   There may be circumstances where an address appears to be valid but
   cannot reasonably be verified in real time, particularly when a
   server is acting as a mail exchanger for another server or domain.
   "Apparent validity" in this case would normally involve at least
   syntax checking and might involve verification that any domains
   specified were ones to which the host expected to be able to relay
   mail.  In these situations, reply code 252 SHOULD be returned.  These
   cases parallel the discussion of RCPT verification discussed in
   section 2.1.  Similarly, the discussion in section 3.4 applies to the
   use of reply codes 251 and 551 with VRFY (and EXPN) to indicate
   addresses that are recognized but that would be forwarded or bounced
   were mail received for them.  Implementations generally SHOULD be
   more aggressive about address verification in the case of VRFY than
   in the case of RCPT, even if it takes a little longer to do so.

3.5.4 Semantics and Applications of EXPN

   EXPN is often very useful in debugging and understanding problems
   with mailing lists and multiple-target-address aliases.  Some systems
   have attempted to use source expansion of mailing lists as a means of
   eliminating duplicates.  The propagation of aliasing systems with
   mail on the Internet, for hosts (typically with MX and CNAME DNS
   records), for mailboxes (various types of local host aliases), and in
   various proxying arrangements, has made it nearly impossible for
   these strategies to work consistently, and mail systems SHOULD NOT
   attempt them.

3.6 Domains

   Only resolvable, fully-qualified, domain names (FQDNs) are permitted
   when domain names are used in SMTP.  In other words, names that can
   be resolved to MX RRs or A RRs (as discussed in section 5) are
   permitted, as are CNAME RRs whose targets can be resolved, in turn,
   to MX or A RRs.  Local nicknames or unqualified names MUST NOT be
   used.  There are two exceptions to the rule requiring FQDNs:

   -  The domain name given in the EHLO command MUST BE either a primary
      host name (a domain name that resolves to an A RR) or, if the host
      has no name, an address literal as described in section 4.1.1.1.

   -  The reserved mailbox name "postmaster" may be used in a RCPT
      command without domain qualification (see section 4.1.1.3) and
      MUST be accepted if so used.








Klensin                     Standards Track                    [Page 23]

RFC 2821             Simple Mail Transfer Protocol            April 2001


3.7 Relaying

   In general, the availability of Mail eXchanger records in the domain
   name system [22, 27] makes the use of explicit source routes in the
   Internet mail system unnecessary.  Many historical problems with
   their interpretation have made their use undesirable.  SMTP clients
   SHOULD NOT generate explicit source routes except under unusual
   circumstances.  SMTP servers MAY decline to act as mail relays or to
   accept addresses that specify source routes.  When route information
   is encountered, SMTP servers are also permitted to ignore the route
   information and simply send to the final destination specified as the
   last element in the route and SHOULD do so.  There has been an
   invalid practice of using names that do not appear in the DNS as
   destination names, with the senders counting on the intermediate
   hosts specified in source routing to resolve any problems.  If source
   routes are stripped, this practice will cause failures.  This is one
   of several reasons why SMTP clients MUST NOT generate invalid source
   routes or depend on serial resolution of names.

   When source routes are not used, the process described in RFC 821 for
   constructing a reverse-path from the forward-path is not applicable
   and the reverse-path at the time of delivery will simply be the
   address that appeared in the MAIL command.

   A relay SMTP server is usually the target of a DNS MX record that
   designates it, rather than the final delivery system.  The relay
   server may accept or reject the task of relaying the mail in the same
   way it accepts or rejects mail for a local user.  If it accepts the
   task, it then becomes an SMTP client, establishes a transmission
   channel to the next SMTP server specified in the DNS (according to
   the rules in section 5), and sends it the mail.  If it declines to
   relay mail to a particular address for policy reasons, a 550 response
   SHOULD be returned.

   Many mail-sending clients exist, especially in conjunction with
   facilities that receive mail via POP3 or IMAP, that have limited
   capability to support some of the requirements of this specification,
   such as the ability to queue messages for subsequent delivery
   attempts.  For these clients, it is common practice to make private
   arrangements to send all messages to a single server for processing
   and subsequent distribution.  SMTP, as specified here, is not ideally
   suited for this role, and work is underway on standardized mail
   submission protocols that might eventually supercede the current
   practices.  In any event, because these arrangements are private and
   fall outside the scope of this specification, they are not described
   here.





Klensin                     Standards Track                    [Page 24]

RFC 2821             Simple Mail Transfer Protocol            April 2001


   It is important to note that MX records can point to SMTP servers
   which act as gateways into other environments, not just SMTP relays
   and final delivery systems; see sections 3.8 and 5.

   If an SMTP server has accepted the task of relaying the mail and
   later finds that the destination is incorrect or that the mail cannot
   be delivered for some other reason, then it MUST construct an
   "undeliverable mail" notification message and send it to the
   originator of the undeliverable mail (as indicated by the reverse-
   path).  Formats specified for non-delivery reports by other standards
   (see, for example, [24, 25]) SHOULD be used if possible.

   This notification message must be from the SMTP server at the relay
   host or the host that first determines that delivery cannot be
   accomplished.  Of course, SMTP servers MUST NOT send notification
   messages about problems transporting notification messages.  One way
   to prevent loops in error reporting is to specify a null reverse-path
   in the MAIL command of a notification message.  When such a message
   is transmitted the reverse-path MUST be set to null (see section
   4.5.5 for additional discussion).  A MAIL command with a null
   reverse-path appears as follows:

      MAIL FROM:<>

   As discussed in section 2.4.1, a relay SMTP has no need to inspect or
   act upon the headers or body of the message data and MUST NOT do so
   except to add its own "Received:" header (section 4.4) and,
   optionally, to attempt to detect looping in the mail system (see
   section 6.2).

3.8 Mail Gatewaying

   While the relay function discussed above operates within the Internet
   SMTP transport service environment, MX records or various forms of
   explicit routing may require that an intermediate SMTP server perform
   a translation function between one transport service and another.  As
   discussed in section 2.3.8, when such a system is at the boundary
   between two transport service environments, we refer to it as a
   "gateway" or "gateway SMTP".

   Gatewaying mail between different mail environments, such as
   different mail formats and protocols, is complex and does not easily
   yield to standardization.  However, some general requirements may be
   given for a gateway between the Internet and another mail
   environment.






Klensin                     Standards Track                    [Page 25]

RFC 2821             Simple Mail Transfer Protocol            April 2001


3.8.1 Header Fields in Gatewaying

   Header fields MAY be rewritten when necessary as messages are
   gatewayed across mail environment boundaries.  This may involve
   inspecting the message body or interpreting the local-part of the
   destination address in spite of the prohibitions in section 2.4.1.

   Other mail systems gatewayed to the Internet often use a subset of
   RFC 822 headers or provide similar functionality with a different
   syntax, but some of these mail systems do not have an equivalent to
   the SMTP envelope.  Therefore, when a message leaves the Internet
   environment, it may be necessary to fold the SMTP envelope
   information into the message header.  A possible solution would be to
   create new header fields to carry the envelope information (e.g.,
   "X-SMTP-MAIL:"  and "X-SMTP-RCPT:"); however, this would require
   changes in mail programs in foreign environments and might risk
   disclosure of private information (see section 7.2).

3.8.2 Received Lines in Gatewaying

   When forwarding a message into or out of the Internet environment, a
   gateway MUST prepend a Received: line, but it MUST NOT alter in any
   way a Received: line that is already in the header.

   "Received:" fields of messages originating from other environments
   may not conform exactly to this specification.  However, the most
   important use of Received: lines is for debugging mail faults, and
   this debugging can be severely hampered by well-meaning gateways that
   try to "fix" a Received: line.  As another consequence of trace
   fields arising in non-SMTP environments, receiving systems MUST NOT
   reject mail based on the format of a trace field and SHOULD be
   extremely robust in the light of unexpected information or formats in
   those fields.

   The gateway SHOULD indicate the environment and protocol in the "via"
   clauses of Received field(s) that it supplies.

3.8.3 Addresses in Gatewaying

   From the Internet side, the gateway SHOULD accept all valid address
   formats in SMTP commands and in RFC 822 headers, and all valid RFC
   822 messages.  Addresses and headers generated by gateways MUST
   conform to applicable Internet standards (including this one and RFC
   822).  Gateways are, of course, subject to the same rules for
   handling source routes as those described for other SMTP systems in
   section 3.3.





Klensin                     Standards Track                    [Page 26]

RFC 2821             Simple Mail Transfer Protocol            April 2001


3.8.4 Other Header Fields in Gatewaying

   The gateway MUST ensure that all header fields of a message that it
   forwards into the Internet mail environment meet the requirements for
   Internet mail.  In particular, all addresses in "From:", "To:",
   "Cc:", etc., fields MUST be transformed (if necessary) to satisfy RFC
   822 syntax, MUST reference only fully-qualified domain names, and
   MUST be effective and useful for sending replies.  The translation
   algorithm used to convert mail from the Internet protocols to another
   environment's protocol SHOULD ensure that error messages from the
   foreign mail environment are delivered to the return path from the
   SMTP envelope, not to the sender listed in the "From:" field (or
   other fields) of the RFC 822 message.

3.8.5 Envelopes in Gatewaying

   Similarly, when forwarding a message from another environment into
   the Internet, the gateway SHOULD set the envelope return path in
   accordance with an error message return address, if supplied by the
   foreign environment.  If the foreign environment has no equivalent
   concept, the gateway must select and use a best approximation, with
   the message originator's address as the default of last resort.

3.9 Terminating Sessions and Connections

   An SMTP connection is terminated when the client sends a QUIT
   command.  The server responds with a positive reply code, after which
   it closes the connection.

   An SMTP server MUST NOT intentionally close the connection except:

   -  After receiving a QUIT command and responding with a 221 reply.

   -  After detecting the need to shut down the SMTP service and
      returning a 421 response code.  This response code can be issued
      after the server receives any command or, if necessary,
      asynchronously from command receipt (on the assumption that the
      client will receive it after the next command is issued).

   In particular, a server that closes connections in response to
   commands that are not understood is in violation of this
   specification.  Servers are expected to be tolerant of unknown
   commands, issuing a 500 reply and awaiting further instructions from
   the client.







Klensin                     Standards Track                    [Page 27]

RFC 2821             Simple Mail Transfer Protocol            April 2001


   An SMTP server which is forcibly shut down via external means SHOULD
   attempt to send a line containing a 421 response code to the SMTP
   client before exiting.  The SMTP client will normally read the 421
   response code after sending its next command.

   SMTP clients that experience a connection close, reset, or other
   communications failure due to circumstances not under their control
   (in violation of the intent of this specification but sometimes
   unavoidable) SHOULD, to maintain the robustness of the mail system,
   treat the mail transaction as if a 451 response had been received and
   act accordingly.

3.10 Mailing Lists and Aliases

   An SMTP-capable host SHOULD support both the alias and the list
   models of address expansion for multiple delivery.  When a message is
   delivered or forwarded to each address of an expanded list form, the
   return address in the envelope ("MAIL FROM:") MUST be changed to be
   the address of a person or other entity who administers the list.
   However, in this case, the message header [32] MUST be left
   unchanged; in particular, the "From" field of the message header is
   unaffected.

   An important mail facility is a mechanism for multi-destination
   delivery of a single message, by transforming (or "expanding" or
   "exploding") a pseudo-mailbox address into a list of destination
   mailbox addresses.  When a message is sent to such a pseudo-mailbox
   (sometimes called an "exploder"), copies are forwarded or
   redistributed to each mailbox in the expanded list.  Servers SHOULD
   simply utilize the addresses on the list; application of heuristics
   or other matching rules to eliminate some addresses, such as that of
   the originator, is strongly discouraged.  We classify such a pseudo-
   mailbox as an "alias" or a "list", depending upon the expansion
   rules.

3.10.1 Alias

   To expand an alias, the recipient mailer simply replaces the pseudo-
   mailbox address in the envelope with each of the expanded addresses
   in turn; the rest of the envelope and the message body are left
   unchanged.  The message is then delivered or forwarded to each
   expanded address.

3.10.2 List

   A mailing list may be said to operate by "redistribution" rather than
   by "forwarding".  To expand a list, the recipient mailer replaces the
   pseudo-mailbox address in the envelope with all of the expanded



Klensin                     Standards Track                    [Page 28]

RFC 2821             Simple Mail Transfer Protocol            April 2001


   addresses.  The return address in the envelope is changed so that all
   error messages generated by the final deliveries will be returned to
   a list administrator, not to the message originator, who generally
   has no control over the contents of the list and will typically find
   error messages annoying.

4. The SMTP Specifications

4.1 SMTP Commands

4.1.1 Command Semantics and Syntax

   The SMTP commands define the mail transfer or the mail system
   function requested by the user.  SMTP commands are character strings
   terminated by <CRLF>.  The commands themselves are alphabetic
   characters terminated by <SP> if parameters follow and <CRLF>
   otherwise.  (In the interest of improved interoperability, SMTP
   receivers are encouraged to tolerate trailing white space before the
   terminating <CRLF>.)  The syntax of the local part of a mailbox must
   conform to receiver site conventions and the syntax specified in
   section 4.1.2.  The SMTP commands are discussed below.  The SMTP
   replies are discussed in section 4.2.

   A mail transaction involves several data objects which are
   communicated as arguments to different commands.  The reverse-path is
   the argument of the MAIL command, the forward-path is the argument of
   the RCPT command, and the mail data is the argument of the DATA
   command.  These arguments or data objects must be transmitted and
   held pending the confirmation communicated by the end of mail data
   indication which finalizes the transaction.  The model for this is
   that distinct buffers are provided to hold the types of data objects,
   that is, there is a reverse-path buffer, a forward-path buffer, and a
   mail data buffer.  Specific commands cause information to be appended
   to a specific buffer, or cause one or more buffers to be cleared.

   Several commands (RSET, DATA, QUIT) are specified as not permitting
   parameters.  In the absence of specific extensions offered by the
   server and accepted by the client, clients MUST NOT send such
   parameters and servers SHOULD reject commands containing them as
   having invalid syntax.

4.1.1.1  Extended HELLO (EHLO) or HELLO (HELO)

   These commands are used to identify the SMTP client to the SMTP
   server.  The argument field contains the fully-qualified domain name
   of the SMTP client if one is available.  In situations in which the
   SMTP client system does not have a meaningful domain name (e.g., when
   its address is dynamically allocated and no reverse mapping record is



Klensin                     Standards Track                    [Page 29]

RFC 2821             Simple Mail Transfer Protocol            April 2001


   available), the client SHOULD send an address literal (see section
   4.1.3), optionally followed by information that will help to identify
   the client system.  y The SMTP server identifies itself to the SMTP
   client in the connection greeting reply and in the response to this
   command.

   A client SMTP SHOULD start an SMTP session by issuing the EHLO
   command.  If the SMTP server supports the SMTP service extensions it
   will give a successful response, a failure response, or an error
   response.  If the SMTP server, in violation of this specification,
   does not support any SMTP service extensions it will generate an
   error response.  Older client SMTP systems MAY, as discussed above,
   use HELO (as specified in RFC 821) instead of EHLO, and servers MUST
   support the HELO command and reply properly to it.  In any event, a
   client MUST issue HELO or EHLO before starting a mail transaction.

   These commands, and a "250 OK" reply to one of them, confirm that
   both the SMTP client and the SMTP server are in the initial state,
   that is, there is no transaction in progress and all state tables and
   buffers are cleared.

   Syntax:

      ehlo            = "EHLO" SP Domain CRLF
      helo            = "HELO" SP Domain CRLF

   Normally, the response to EHLO will be a multiline reply.  Each line
   of the response contains a keyword and, optionally, one or more
   parameters.  Following the normal syntax for multiline replies, these
   keyworks follow the code (250) and a hyphen for all but the last
   line, and the code and a space for the last line.  The syntax for a
   positive response, using the ABNF notation and terminal symbols of
   [8], is:

      ehlo-ok-rsp  =    ( "250"    domain [ SP ehlo-greet ] CRLF )
                   / (    "250-"   domain [ SP ehlo-greet ] CRLF
                       *( "250-"   ehlo-line                CRLF )
                          "250"    SP ehlo-line             CRLF  )

      ehlo-greet   = 1*(%d0-9 / %d11-12 / %d14-127)
                   ; string of any characters other than CR or LF

      ehlo-line    = ehlo-keyword *( SP ehlo-param )

      ehlo-keyword = (ALPHA / DIGIT) *(ALPHA / DIGIT / "-")
                   ; additional syntax of ehlo-params depends on
                   ; ehlo-keyword




Klensin                     Standards Track                    [Page 30]

RFC 2821             Simple Mail Transfer Protocol            April 2001


      ehlo-param   = 1*(%d33-127)
                   ; any CHAR excluding <SP> and all
                   ; control characters (US-ASCII 0-31 inclusive)

   Although EHLO keywords may be specified in upper, lower, or mixed
   case, they MUST always be recognized and processed in a case-
   insensitive manner.  This is simply an extension of practices
   specified in RFC 821 and section 2.4.1.

4.1.1.2 MAIL (MAIL)

   This command is used to initiate a mail transaction in which the mail
   data is delivered to an SMTP server which may, in turn, deliver it to
   one or more mailboxes or pass it on to another system (possibly using
   SMTP).  The argument field contains a reverse-path and may contain
   optional parameters.  In general, the MAIL command may be sent only
   when no mail transaction is in progress, see section 4.1.4.

   The reverse-path consists of the sender mailbox.  Historically, that
   mailbox might optionally have been preceded by a list of hosts, but
   that behavior is now deprecated (see appendix C).  In some types of
   reporting messages for which a reply is likely to cause a mail loop
   (for example, mail delivery and nondelivery notifications), the
   reverse-path may be null (see section 3.7).

   This command clears the reverse-path buffer, the forward-path buffer,
   and the mail data buffer; and inserts the reverse-path information
   from this command into the reverse-path buffer.

   If service extensions were negotiated, the MAIL command may also
   carry parameters associated with a particular service extension.

   Syntax:

      "MAIL FROM:" ("<>" / Reverse-Path)
                       [SP Mail-parameters] CRLF

4.1.1.3 RECIPIENT (RCPT)

   This command is used to identify an individual recipient of the mail
   data; multiple recipients are specified by multiple use of this
   command.  The argument field contains a forward-path and may contain
   optional parameters.

   The forward-path normally consists of the required destination
   mailbox.  Sending systems SHOULD not generate the optional list of
   hosts known as a source route.  Receiving systems MUST recognize




Klensin                     Standards Track                    [Page 31]

RFC 2821             Simple Mail Transfer Protocol            April 2001


   source route syntax but SHOULD strip off the source route
   specification and utilize the domain name associated with the mailbox
   as if the source route had not been provided.

   Similarly, relay hosts SHOULD strip or ignore source routes, and
   names MUST NOT be copied into the reverse-path.  When mail reaches
   its ultimate destination (the forward-path contains only a
   destination mailbox), the SMTP server inserts it into the destination
   mailbox in accordance with its host mail conventions.

   For example, mail received at relay host xyz.com with envelope
   commands

      MAIL FROM:<userx@y.foo.org>
      RCPT TO:<@hosta.int,@jkl.org:userc@d.bar.org>

   will normally be sent directly on to host d.bar.org with envelope
   commands

      MAIL FROM:<userx@y.foo.org>
      RCPT TO:<userc@d.bar.org>

   As provided in appendix C, xyz.com MAY also choose to relay the
   message to hosta.int, using the envelope commands

      MAIL FROM:<userx@y.foo.org>
      RCPT TO:<@hosta.int,@jkl.org:userc@d.bar.org>

   or to jkl.org, using the envelope commands

      MAIL FROM:<userx@y.foo.org>
      RCPT TO:<@jkl.org:userc@d.bar.org>

   Of course, since hosts are not required to relay mail at all, xyz.com
   may also reject the message entirely when the RCPT command is
   received, using a 550 code (since this is a "policy reason").

   If service extensions were negotiated, the RCPT command may also
   carry parameters associated with a particular service extension
   offered by the server.  The client MUST NOT transmit parameters other
   than those associated with a service extension offered by the server
   in its EHLO response.

Syntax:
   "RCPT TO:" ("<Postmaster@" domain ">" / "<Postmaster>" / Forward-Path)
                    [SP Rcpt-parameters] CRLF





Klensin                     Standards Track                    [Page 32]

RFC 2821             Simple Mail Transfer Protocol            April 2001


4.1.1.4 DATA (DATA)

   The receiver normally sends a 354 response to DATA, and then treats
   the lines (strings ending in <CRLF> sequences, as described in
   section 2.3.7) following the command as mail data from the sender.
   This command causes the mail data to be appended to the mail data
   buffer.  The mail data may contain any of the 128 ASCII character
   codes, although experience has indicated that use of control
   characters other than SP, HT, CR, and LF may cause problems and
   SHOULD be avoided when possible.

   The mail data is terminated by a line containing only a period, that
   is, the character sequence "<CRLF>.<CRLF>" (see section 4.5.2).  This
   is the end of mail data indication.  Note that the first <CRLF> of
   this terminating sequence is also the <CRLF> that ends the final line
   of the data (message text) or, if there was no data, ends the DATA
   command itself.  An extra <CRLF> MUST NOT be added, as that would
   cause an empty line to be added to the message.  The only exception
   to this rule would arise if the message body were passed to the
   originating SMTP-sender with a final "line" that did not end in
   <CRLF>; in that case, the originating SMTP system MUST either reject
   the message as invalid or add <CRLF> in order to have the receiving
   SMTP server recognize the "end of data" condition.

   The custom of accepting lines ending only in <LF>, as a concession to
   non-conforming behavior on the part of some UNIX systems, has proven
   to cause more interoperability problems than it solves, and SMTP
   server systems MUST NOT do this, even in the name of improved
   robustness.  In particular, the sequence "<LF>.<LF>" (bare line
   feeds, without carriage returns) MUST NOT be treated as equivalent to
   <CRLF>.<CRLF> as the end of mail data indication.

   Receipt of the end of mail data indication requires the server to
   process the stored mail transaction information.  This processing
   consumes the information in the reverse-path buffer, the forward-path
   buffer, and the mail data buffer, and on the completion of this
   command these buffers are cleared.  If the processing is successful,
   the receiver MUST send an OK reply.  If the processing fails the
   receiver MUST send a failure reply.  The SMTP model does not allow
   for partial failures at this point: either the message is accepted by
   the server for delivery and a positive response is returned or it is
   not accepted and a failure reply is returned.  In sending a positive
   completion reply to the end of data indication, the receiver takes
   full responsibility for the message (see section 6.1).  Errors that
   are diagnosed subsequently MUST be reported in a mail message, as
   discussed in section 4.4.





Klensin                     Standards Track                    [Page 33]

RFC 2821             Simple Mail Transfer Protocol            April 2001


   When the SMTP server accepts a message either for relaying or for
   final delivery, it inserts a trace record (also referred to
   interchangeably as a "time stamp line" or "Received" line) at the top
   of the mail data.  This trace record indicates the identity of the
   host that sent the message, the identity of the host that received
   the message (and is inserting this time stamp), and the date and time
   the message was received.  Relayed messages will have multiple time
   stamp lines.  Details for formation of these lines, including their
   syntax, is specified in section 4.4.

   Additional discussion about the operation of the DATA command appears
   in section 3.3.

   Syntax:
      "DATA" CRLF

4.1.1.5 RESET (RSET)

   This command specifies that the current mail transaction will be
   aborted.  Any stored sender, recipients, and mail data MUST be
   discarded, and all buffers and state tables cleared.  The receiver
   MUST send a "250 OK" reply to a RSET command with no arguments.  A
   reset command may be issued by the client at any time.  It is
   effectively equivalent to a NOOP (i.e., if has no effect) if issued
   immediately after EHLO, before EHLO is issued in the session, after
   an end-of-data indicator has been sent and acknowledged, or
   immediately before a QUIT.  An SMTP server MUST NOT close the
   connection as the result of receiving a RSET; that action is reserved
   for QUIT (see section 4.1.1.10).

   Since EHLO implies some additional processing and response by the
   server, RSET will normally be more efficient than reissuing that
   command, even though the formal semantics are the same.

   There are circumstances, contrary to the intent of this
   specification, in which an SMTP server may receive an indication that
   the underlying TCP connection has been closed or reset.  To preserve
   the robustness of the mail system, SMTP servers SHOULD be prepared
   for this condition and SHOULD treat it as if a QUIT had been received
   before the connection disappeared.

   Syntax:
      "RSET" CRLF








Klensin                     Standards Track                    [Page 34]

RFC 2821             Simple Mail Transfer Protocol            April 2001


4.1.1.6 VERIFY (VRFY)

   This command asks the receiver to confirm that the argument
   identifies a user or mailbox.  If it is a user name, information is
   returned as specified in section 3.5.

   This command has no effect on the reverse-path buffer, the forward-
   path buffer, or the mail data buffer.

   Syntax:
      "VRFY" SP String CRLF

4.1.1.7 EXPAND (EXPN)

   This command asks the receiver to confirm that the argument
   identifies a mailing list, and if so, to return the membership of
   that list.  If the command is successful, a reply is returned
   containing information as described in section 3.5.  This reply will
   have multiple lines except in the trivial case of a one-member list.

   This command has no effect on the reverse-path buffer, the forward-
   path buffer, or the mail data buffer and may be issued at any time.

   Syntax:
      "EXPN" SP String CRLF

4.1.1.8 HELP (HELP)

   This command causes the server to send helpful information to the
   client.  The command MAY take an argument (e.g., any command name)
   and return more specific information as a response.

   This command has no effect on the reverse-path buffer, the forward-
   path buffer, or the mail data buffer and may be issued at any time.

   SMTP servers SHOULD support HELP without arguments and MAY support it
   with arguments.

   Syntax:
      "HELP" [ SP String ] CRLF

4.1.1.9 NOOP (NOOP)

   This command does not affect any parameters or previously entered
   commands.  It specifies no action other than that the receiver send
   an OK reply.





Klensin                     Standards Track                    [Page 35]

RFC 2821             Simple Mail Transfer Protocol            April 2001


   This command has no effect on the reverse-path buffer, the forward-
   path buffer, or the mail data buffer and may be issued at any time.
   If a parameter string is specified, servers SHOULD ignore it.

   Syntax:
      "NOOP" [ SP String ] CRLF

4.1.1.10 QUIT (QUIT)

   This command specifies that the receiver MUST send an OK reply, and
   then close the transmission channel.

   The receiver MUST NOT intentionally close the transmission channel
   until it receives and replies to a QUIT command (even if there was an
   error).  The sender MUST NOT intentionally close the transmission
   channel until it sends a QUIT command and SHOULD wait until it
   receives the reply (even if there was an error response to a previous
   command).  If the connection is closed prematurely due to violations
   of the above or system or network failure, the server MUST cancel any
   pending transaction, but not undo any previously completed
   transaction, and generally MUST act as if the command or transaction
   in progress had received a temporary error (i.e., a 4yz response).

   The QUIT command may be issued at any time.

   Syntax:
      "QUIT" CRLF

4.1.2 Command Argument Syntax

   The syntax of the argument fields of the above commands (using the
   syntax specified in [8] where applicable) is given below.  Some of
   the productions given below are used only in conjunction with source
   routes as described in appendix C.  Terminals not defined in this
   document, such as ALPHA, DIGIT, SP, CR, LF, CRLF, are as defined in
   the "core" syntax [8 (section 6)] or in the message format syntax
   [32].

      Reverse-path = Path
      Forward-path = Path
      Path = "<" [ A-d-l ":" ] Mailbox ">"
      A-d-l = At-domain *( "," A-d-l )
            ; Note that this form, the so-called "source route",
            ; MUST BE accepted, SHOULD NOT be generated, and SHOULD be
            ; ignored.
      At-domain = "@" domain
      Mail-parameters = esmtp-param *(SP esmtp-param)
      Rcpt-parameters = esmtp-param *(SP esmtp-param)



Klensin                     Standards Track                    [Page 36]

RFC 2821             Simple Mail Transfer Protocol            April 2001


      esmtp-param     = esmtp-keyword ["=" esmtp-value]
      esmtp-keyword   = (ALPHA / DIGIT) *(ALPHA / DIGIT / "-")
      esmtp-value     = 1*(%d33-60 / %d62-127)
            ; any CHAR excluding "=", SP, and control characters
      Keyword  = Ldh-str
      Argument = Atom
      Domain = (sub-domain 1*("." sub-domain)) / address-literal
      sub-domain = Let-dig [Ldh-str]

      address-literal = "[" IPv4-address-literal /
                            IPv6-address-literal /
                            General-address-literal "]"
            ; See section 4.1.3

      Mailbox = Local-part "@" Domain

      Local-part = Dot-string / Quoted-string
            ; MAY be case-sensitive

      Dot-string = Atom *("." Atom)

      Atom = 1*atext

      Quoted-string = DQUOTE *qcontent DQUOTE

      String = Atom / Quoted-string

   While the above definition for Local-part is relatively permissive,
   for maximum interoperability, a host that expects to receive mail
   SHOULD avoid defining mailboxes where the Local-part requires (or
   uses) the Quoted-string form or where the Local-part is case-
   sensitive.  For any purposes that require generating or comparing
   Local-parts (e.g., to specific mailbox names), all quoted forms MUST
   be treated as equivalent and the sending system SHOULD transmit the
   form that uses the minimum quoting possible.

   Systems MUST NOT define mailboxes in such a way as to require the use
   in SMTP of non-ASCII characters (octets with the high order bit set
   to one) or ASCII "control characters" (decimal value 0-31 and 127).
   These characters MUST NOT be used in MAIL or RCPT commands or other
   commands that require mailbox names.

   Note that the backslash, "\", is a quote character, which is used to
   indicate that the next character is to be used literally (instead of
   its normal interpretation).  For example, "Joe\,Smith" indicates a
   single nine character user field with the comma being the fourth
   character of the field.




Klensin                     Standards Track                    [Page 37]

RFC 2821             Simple Mail Transfer Protocol            April 2001


   To promote interoperability and consistent with long-standing
   guidance about conservative use of the DNS in naming and applications
   (e.g., see section 2.3.1 of the base DNS document, RFC1035 [22]),
   characters outside the set of alphas, digits, and hyphen MUST NOT
   appear in domain name labels for SMTP clients or servers.  In
   particular, the underscore character is not permitted.  SMTP servers
   that receive a command in which invalid character codes have been
   employed, and for which there are no other reasons for rejection,
   MUST reject that command with a 501 response.

4.1.3 Address Literals

   Sometimes a host is not known to the domain name system and
   communication (and, in particular, communication to report and repair
   the error) is blocked.  To bypass this barrier a special literal form
   of the address is allowed as an alternative to a domain name.  For
   IPv4 addresses, this form uses four small decimal integers separated
   by dots and enclosed by brackets such as [123.255.37.2], which
   indicates an (IPv4) Internet Address in sequence-of-octets form.  For
   IPv6 and other forms of addressing that might eventually be
   standardized, the form consists of a standardized "tag" that
   identifies the address syntax, a colon, and the address itself, in a
   format specified as part of the IPv6 standards [17].

   Specifically:

      IPv4-address-literal = Snum 3("." Snum)
      IPv6-address-literal = "IPv6:" IPv6-addr
      General-address-literal = Standardized-tag ":" 1*dcontent
      Standardized-tag = Ldh-str
            ; MUST be specified in a standards-track RFC
            ; and registered with IANA

      Snum = 1*3DIGIT  ; representing a decimal integer
            ; value in the range 0 through 255
      Let-dig = ALPHA / DIGIT
      Ldh-str = *( ALPHA / DIGIT / "-" ) Let-dig

      IPv6-addr = IPv6-full / IPv6-comp / IPv6v4-full / IPv6v4-comp
      IPv6-hex  = 1*4HEXDIG
      IPv6-full = IPv6-hex 7(":" IPv6-hex)
      IPv6-comp = [IPv6-hex *5(":" IPv6-hex)] "::" [IPv6-hex *5(":"
                 IPv6-hex)]
            ; The "::" represents at least 2 16-bit groups of zeros
            ; No more than 6 groups in addition to the "::" may be
            ; present
      IPv6v4-full = IPv6-hex 5(":" IPv6-hex) ":" IPv4-address-literal
      IPv6v4-comp = [IPv6-hex *3(":" IPv6-hex)] "::"



Klensin                     Standards Track                    [Page 38]

RFC 2821             Simple Mail Transfer Protocol            April 2001


                   [IPv6-hex *3(":" IPv6-hex) ":"] IPv4-address-literal
            ; The "::" represents at least 2 16-bit groups of zeros
            ; No more than 4 groups in addition to the "::" and
            ; IPv4-address-literal may be present

4.1.4 Order of Commands

   There are restrictions on the order in which these commands may be
   used.

   A session that will contain mail transactions MUST first be
   initialized by the use of the EHLO command.  An SMTP server SHOULD
   accept commands for non-mail transactions (e.g., VRFY or EXPN)
   without this initialization.

   An EHLO command MAY be issued by a client later in the session.  If
   it is issued after the session begins, the SMTP server MUST clear all
   buffers and reset the state exactly as if a RSET command had been
   issued.  In other words, the sequence of RSET followed immediately by
   EHLO is redundant, but not harmful other than in the performance cost
   of executing unnecessary commands.

   If the EHLO command is not acceptable to the SMTP server, 501, 500,
   or 502 failure replies MUST be returned as appropriate.  The SMTP
   server MUST stay in the same state after transmitting these replies
   that it was in before the EHLO was received.

   The SMTP client MUST, if possible, ensure that the domain parameter
   to the EHLO command is a valid principal host name (not a CNAME or MX
   name) for its host.  If this is not possible (e.g., when the client's
   address is dynamically assigned and the client does not have an
   obvious name), an address literal SHOULD be substituted for the
   domain name and supplemental information provided that will assist in
   identifying the client.

   An SMTP server MAY verify that the domain name parameter in the EHLO
   command actually corresponds to the IP address of the client.
   However, the server MUST NOT refuse to accept a message for this
   reason if the verification fails: the information about verification
   failure is for logging and tracing only.

   The NOOP, HELP, EXPN, VRFY, and RSET commands can be used at any time
   during a session, or without previously initializing a session.  SMTP
   servers SHOULD process these normally (that is, not return a 503
   code) even if no EHLO command has yet been received; clients SHOULD
   open a session with EHLO before sending these commands.





Klensin                     Standards Track                    [Page 39]

RFC 2821             Simple Mail Transfer Protocol            April 2001


   If these rules are followed, the example in RFC 821 that shows "550
   access denied to you" in response to an EXPN command is incorrect
   unless an EHLO command precedes the EXPN or the denial of access is
   based on the client's IP address or other authentication or
   authorization-determining mechanisms.

   The MAIL command (or the obsolete SEND, SOML, or SAML commands)
   begins a mail transaction.  Once started, a mail transaction consists
   of a transaction beginning command, one or more RCPT commands, and a
   DATA command, in that order.  A mail transaction may be aborted by
   the RSET (or a new EHLO) command.  There may be zero or more
   transactions in a session.  MAIL (or SEND, SOML, or SAML) MUST NOT be
   sent if a mail transaction is already open, i.e., it should be sent
   only if no mail transaction had been started in the session, or it
   the previous one successfully concluded with a successful DATA
   command, or if the previous one was aborted with a RSET.

   If the transaction beginning command argument is not acceptable, a
   501 failure reply MUST be returned and the SMTP server MUST stay in
   the same state.  If the commands in a transaction are out of order to
   the degree that they cannot be processed by the server, a 503 failure
   reply MUST be returned and the SMTP server MUST stay in the same
   state.

   The last command in a session MUST be the QUIT command.  The QUIT
   command cannot be used at any other time in a session, but SHOULD be
   used by the client SMTP to request connection closure, even when no
   session opening command was sent and accepted.

4.1.5 Private-use Commands

   As specified in section 2.2.2, commands starting in "X" may be used
   by bilateral agreement between the client (sending) and server
   (receiving) SMTP agents.  An SMTP server that does not recognize such
   a command is expected to reply with "500 Command not recognized".  An
   extended SMTP server MAY list the feature names associated with these
   private commands in the response to the EHLO command.

   Commands sent or accepted by SMTP systems that do not start with "X"
   MUST conform to the requirements of section 2.2.2.

4.2 SMTP Replies

   Replies to SMTP commands serve to ensure the synchronization of
   requests and actions in the process of mail transfer and to guarantee
   that the SMTP client always knows the state of the SMTP server.
   Every command MUST generate exactly one reply.




Klensin                     Standards Track                    [Page 40]

RFC 2821             Simple Mail Transfer Protocol            April 2001


   The details of the command-reply sequence are described in section
   4.3.

   An SMTP reply consists of a three digit number (transmitted as three
   numeric characters) followed by some text unless specified otherwise
   in this document.  The number is for use by automata to determine
   what state to enter next; the text is for the human user.  The three
   digits contain enough encoded information that the SMTP client need
   not examine the text and may either discard it or pass it on to the
   user, as appropriate.  Exceptions are as noted elsewhere in this
   document.  In particular, the 220, 221, 251, 421, and 551 reply codes
   are associated with message text that must be parsed and interpreted
   by machines.  In the general case, the text may be receiver dependent
   and context dependent, so there are likely to be varying texts for
   each reply code.  A discussion of the theory of reply codes is given
   in section 4.2.1.  Formally, a reply is defined to be the sequence: a
   three-digit code, <SP>, one line of text, and <CRLF>, or a multiline
   reply (as defined in section 4.2.1).  Since, in violation of this
   specification, the text is sometimes not sent, clients which do not
   receive it SHOULD be prepared to process the code alone (with or
   without a trailing space character).  Only the EHLO, EXPN, and HELP
   commands are expected to result in multiline replies in normal
   circumstances, however, multiline replies are allowed for any
   command.

   In ABNF, server responses are:

      Greeting = "220 " Domain [ SP text ] CRLF
      Reply-line = Reply-code [ SP text ] CRLF

   where "Greeting" appears only in the 220 response that announces that
   the server is opening its part of the connection.

   An SMTP server SHOULD send only the reply codes listed in this
   document.  An SMTP server SHOULD use the text shown in the examples
   whenever appropriate.

   An SMTP client MUST determine its actions only by the reply code, not
   by the text (except for the "change of address" 251 and 551 and, if
   necessary, 220, 221, and 421 replies); in the general case, any text,
   including no text at all (although senders SHOULD NOT send bare
   codes), MUST be acceptable.  The space (blank) following the reply
   code is considered part of the text.  Whenever possible, a receiver-
   SMTP SHOULD test the first digit (severity indication) of the reply
   code.






Klensin                     Standards Track                    [Page 41]

RFC 2821             Simple Mail Transfer Protocol            April 2001


   The list of codes that appears below MUST NOT be construed as
   permanent.  While the addition of new codes should be a rare and
   significant activity, with supplemental information in the textual
   part of the response being preferred, new codes may be added as the
   result of new Standards or Standards-track specifications.
   Consequently, a sender-SMTP MUST be prepared to handle codes not
   specified in this document and MUST do so by interpreting the first
   digit only.

4.2.1 Reply Code Severities and Theory

   The three digits of the reply each have a special significance.  The
   first digit denotes whether the response is good, bad or incomplete.
   An unsophisticated SMTP client, or one that receives an unexpected
   code, will be able to determine its next action (proceed as planned,
   redo, retrench, etc.) by examining this first digit.  An SMTP client
   that wants to know approximately what kind of error occurred (e.g.,
   mail system error, command syntax error) may examine the second
   digit.  The third digit and any supplemental information that may be
   present is reserved for the finest gradation of information.

   There are five values for the first digit of the reply code:

   1yz   Positive Preliminary reply
      The command has been accepted, but the requested action is being
      held in abeyance, pending confirmation of the information in this
      reply.  The SMTP client should send another command specifying
      whether to continue or abort the action.  Note: unextended SMTP
      does not have any commands that allow this type of reply, and so
      does not have continue or abort commands.

   2yz   Positive Completion reply
      The requested action has been successfully completed.  A new
      request may be initiated.

   3yz   Positive Intermediate reply
      The command has been accepted, but the requested action is being
      held in abeyance, pending receipt of further information.  The
      SMTP client should send another command specifying this
      information.  This reply is used in command sequence groups (i.e.,
      in DATA).

   4yz   Transient Negative Completion reply
      The command was not accepted, and the requested action did not
      occur.  However, the error condition is temporary and the action
      may be requested again.  The sender should return to the beginning
      of the command sequence (if any).  It is difficult to assign a
      meaning to "transient" when two different sites (receiver- and



Klensin                     Standards Track                    [Page 42]

RFC 2821             Simple Mail Transfer Protocol            April 2001


      sender-SMTP agents) must agree on the interpretation.  Each reply
      in this category might have a different time value, but the SMTP
      client is encouraged to try again.  A rule of thumb to determine
      whether a reply fits into the 4yz or the 5yz category (see below)
      is that replies are 4yz if they can be successful if repeated
      without any change in command form or in properties of the sender
      or receiver (that is, the command is repeated identically and the
      receiver does not put up a new implementation.)

   5yz   Permanent Negative Completion reply
      The command was not accepted and the requested action did not
      occur.  The SMTP client is discouraged from repeating the exact
      request (in the same sequence).  Even some "permanent" error
      conditions can be corrected, so the human user may want to direct
      the SMTP client to reinitiate the command sequence by direct
      action at some point in the future (e.g., after the spelling has
      been changed, or the user has altered the account status).

   The second digit encodes responses in specific categories:

   x0z   Syntax: These replies refer to syntax errors, syntactically
      correct commands that do not fit any functional category, and
      unimplemented or superfluous commands.

   x1z   Information:  These are replies to requests for information,
      such as status or help.

   x2z   Connections: These are replies referring to the transmission
      channel.

   x3z   Unspecified.

   x4z   Unspecified.

   x5z   Mail system: These replies indicate the status of the receiver
      mail system vis-a-vis the requested transfer or other mail system
      action.

   The third digit gives a finer gradation of meaning in each category
   specified by the second digit.  The list of replies illustrates this.
   Each reply text is recommended rather than mandatory, and may even
   change according to the command with which it is associated.  On the
   other hand, the reply codes must strictly follow the specifications
   in this section.  Receiver implementations should not invent new
   codes for slightly different situations from the ones described here,
   but rather adapt codes already defined.





Klensin                     Standards Track                    [Page 43]

RFC 2821             Simple Mail Transfer Protocol            April 2001


   For example, a command such as NOOP, whose successful execution does
   not offer the SMTP client any new information, will return a 250
   reply.  The reply is 502 when the command requests an unimplemented
   non-site-specific action.  A refinement of that is the 504 reply for
   a command that is implemented, but that requests an unimplemented
   parameter.

   The reply text may be longer than a single line; in these cases the
   complete text must be marked so the SMTP client knows when it can
   stop reading the reply.  This requires a special format to indicate a
   multiple line reply.

   The format for multiline replies requires that every line, except the
   last, begin with the reply code, followed immediately by a hyphen,
   "-" (also known as minus), followed by text.  The last line will
   begin with the reply code, followed immediately by <SP>, optionally
   some text, and <CRLF>.  As noted above, servers SHOULD send the <SP>
   if subsequent text is not sent, but clients MUST be prepared for it
   to be omitted.

   For example:

      123-First line
      123-Second line
      123-234 text beginning with numbers
      123 The last line

   In many cases the SMTP client then simply needs to search for a line
   beginning with the reply code followed by <SP> or <CRLF> and ignore
   all preceding lines.  In a few cases, there is important data for the
   client in the reply "text".  The client will be able to identify
   these cases from the current context.

4.2.2 Reply Codes by Function Groups

      500 Syntax error, command unrecognized
         (This may include errors such as command line too long)
      501 Syntax error in parameters or arguments
      502 Command not implemented  (see section 4.2.4)
      503 Bad sequence of commands
      504 Command parameter not implemented

      211 System status, or system help reply
      214 Help message
         (Information on how to use the receiver or the meaning of a
         particular non-standard command; this reply is useful only
         to the human user)




Klensin                     Standards Track                    [Page 44]

RFC 2821             Simple Mail Transfer Protocol            April 2001


      220 <domain> Service ready
      221 <domain> Service closing transmission channel
      421 <domain> Service not available, closing transmission channel
         (This may be a reply to any command if the service knows it
         must shut down)

      250 Requested mail action okay, completed
      251 User not local; will forward to <forward-path>
         (See section 3.4)
      252 Cannot VRFY user, but will accept message and attempt
          delivery
         (See section 3.5.3)
      450 Requested mail action not taken: mailbox unavailable
         (e.g., mailbox busy)
      550 Requested action not taken: mailbox unavailable
         (e.g., mailbox not found, no access, or command rejected
         for policy reasons)
      451 Requested action aborted: error in processing
      551 User not local; please try <forward-path>
         (See section 3.4)
      452 Requested action not taken: insufficient system storage
      552 Requested mail action aborted: exceeded storage allocation
      553 Requested action not taken: mailbox name not allowed
         (e.g., mailbox syntax incorrect)
      354 Start mail input; end with <CRLF>.<CRLF>
      554 Transaction failed (Or, in the case of a connection-opening
          response, "No SMTP service here")

4.2.3  Reply Codes in Numeric Order

      211 System status, or system help reply
      214 Help message
         (Information on how to use the receiver or the meaning of a
         particular non-standard command; this reply is useful only
         to the human user)
      220 <domain> Service ready
      221 <domain> Service closing transmission channel
      250 Requested mail action okay, completed
      251 User not local; will forward to <forward-path>
         (See section 3.4)
      252 Cannot VRFY user, but will accept message and attempt
         delivery
         (See section 3.5.3)

      354 Start mail input; end with <CRLF>.<CRLF>






Klensin                     Standards Track                    [Page 45]

RFC 2821             Simple Mail Transfer Protocol            April 2001


      421 <domain> Service not available, closing transmission channel
         (This may be a reply to any command if the service knows it
         must shut down)
      450 Requested mail action not taken: mailbox unavailable
         (e.g., mailbox busy)
      451 Requested action aborted: local error in processing
      452 Requested action not taken: insufficient system storage
      500 Syntax error, command unrecognized
         (This may include errors such as command line too long)
      501 Syntax error in parameters or arguments
      502 Command not implemented (see section 4.2.4)
      503 Bad sequence of commands
      504 Command parameter not implemented
      550 Requested action not taken: mailbox unavailable
         (e.g., mailbox not found, no access, or command rejected
         for policy reasons)
      551 User not local; please try <forward-path>
         (See section 3.4)
      552 Requested mail action aborted: exceeded storage allocation
      553 Requested action not taken: mailbox name not allowed
         (e.g., mailbox syntax incorrect)
      554 Transaction failed  (Or, in the case of a connection-opening
          response, "No SMTP service here")

4.2.4 Reply Code 502

   Questions have been raised as to when reply code 502 (Command not
   implemented) SHOULD be returned in preference to other codes.  502
   SHOULD be used when the command is actually recognized by the SMTP
   server, but not implemented.  If the command is not recognized, code
   500 SHOULD be returned.  Extended SMTP systems MUST NOT list
   capabilities in response to EHLO for which they will return 502 (or
   500) replies.

4.2.5 Reply Codes After DATA and the Subsequent <CRLF>.<CRLF>

   When an SMTP server returns a positive completion status (2yz code)
   after the DATA command is completed with <CRLF>.<CRLF>, it accepts
   responsibility for:

   -  delivering the message (if the recipient mailbox exists), or

   -  if attempts to deliver the message fail due to transient
      conditions, retrying delivery some reasonable number of times at
      intervals as specified in section 4.5.4.






Klensin                     Standards Track                    [Page 46]

RFC 2821             Simple Mail Transfer Protocol            April 2001


   -  if attempts to deliver the message fail due to permanent
      conditions, or if repeated attempts to deliver the message fail
      due to transient conditions, returning appropriate notification to
      the sender of the original message (using the address in the SMTP
      MAIL command).

   When an SMTP server returns a permanent error status (5yz) code after
   the DATA command is completed with <CRLF>.<CRLF>, it MUST NOT make
   any subsequent attempt to deliver that message.  The SMTP client
   retains responsibility for delivery of that message and may either
   return it to the user or requeue it for a subsequent attempt (see
   section 4.5.4.1).

   The user who originated the message SHOULD be able to interpret the
   return of a transient failure status (by mail message or otherwise)
   as a non-delivery indication, just as a permanent failure would be
   interpreted.  I.e., if the client SMTP successfully handles these
   conditions, the user will not receive such a reply.

   When an SMTP server returns a permanent error status (5yz) code after
   the DATA command is completely with <CRLF>.<CRLF>, it MUST NOT make
   any subsequent attempt to deliver the message.  As with temporary
   error status codes, the SMTP client retains responsibility for the
   message, but SHOULD not again attempt delivery to the same server
   without user review and intervention of the message.

4.3 Sequencing of Commands and Replies

4.3.1 Sequencing Overview

   The communication between the sender and receiver is an alternating
   dialogue, controlled by the sender.  As such, the sender issues a
   command and the receiver responds with a reply.  Unless other
   arrangements are negotiated through service extensions, the sender
   MUST wait for this response before sending further commands.

   One important reply is the connection greeting.  Normally, a receiver
   will send a 220 "Service ready" reply when the connection is
   completed.  The sender SHOULD wait for this greeting message before
   sending any commands.

   Note: all the greeting-type replies have the official name (the
   fully-qualified primary domain name) of the server host as the first
   word following the reply code.  Sometimes the host will have no
   meaningful name.  See 4.1.3 for a discussion of alternatives in these
   situations.





Klensin                     Standards Track                    [Page 47]

RFC 2821             Simple Mail Transfer Protocol            April 2001


   For example,

      220 ISIF.USC.EDU Service ready
   or
      220 mail.foo.com SuperSMTP v 6.1.2 Service ready
   or
      220 [10.0.0.1] Clueless host service ready

   The table below lists alternative success and failure replies for
   each command.  These SHOULD be strictly adhered to: a receiver may
   substitute text in the replies, but the meaning and action implied by
   the code numbers and by the specific command reply sequence cannot be
   altered.

4.3.2 Command-Reply Sequences

   Each command is listed with its usual possible replies.  The prefixes
   used before the possible replies are "I" for intermediate, "S" for
   success, and "E" for error.  Since some servers may generate other
   replies under special circumstances, and to allow for future
   extension, SMTP clients SHOULD, when possible, interpret only the
   first digit of the reply and MUST be prepared to deal with
   unrecognized reply codes by interpreting the first digit only.
   Unless extended using the mechanisms described in section 2.2, SMTP
   servers MUST NOT transmit reply codes to an SMTP client that are
   other than three digits or that do not start in a digit between 2 and
   5 inclusive.

   These sequencing rules and, in principle, the codes themselves, can
   be extended or modified by SMTP extensions offered by the server and
   accepted (requested) by the client.

   In addition to the codes listed below, any SMTP command can return
   any of the following codes if the corresponding unusual circumstances
   are encountered:

   500  For the "command line too long" case or if the command name was
      not recognized.  Note that producing a "command not recognized"
      error in response to the required subset of these commands is a
      violation of this specification.

   501  Syntax error in command or arguments.  In order to provide for
      future extensions, commands that are specified in this document as
      not accepting arguments (DATA, RSET, QUIT) SHOULD return a 501
      message if arguments are supplied in the absence of EHLO-
      advertised extensions.

   421  Service shutting down and closing transmission channel



Klensin                     Standards Track                    [Page 48]

RFC 2821             Simple Mail Transfer Protocol            April 2001


   Specific sequences are:

   CONNECTION ESTABLISHMENT
      S: 220
      E: 554
   EHLO or HELO
      S: 250
      E: 504, 550
   MAIL
      S: 250
      E: 552, 451, 452, 550, 553, 503
   RCPT
      S: 250, 251 (but see section 3.4 for discussion of 251 and 551)
      E: 550, 551, 552, 553, 450, 451, 452, 503, 550
   DATA
      I: 354 -> data -> S: 250
                        E: 552, 554, 451, 452
      E: 451, 554, 503
   RSET
      S: 250
   VRFY
      S: 250, 251, 252
      E: 550, 551, 553, 502, 504
   EXPN
      S: 250, 252
      E: 550, 500, 502, 504
   HELP
      S: 211, 214
      E: 502, 504
   NOOP
      S: 250
   QUIT
      S: 221

4.4 Trace Information

   When an SMTP server receives a message for delivery or further
   processing, it MUST insert trace ("time stamp" or "Received")
   information at the beginning of the message content, as discussed in
   section 4.1.1.4.

   This line MUST be structured as follows:

   -  The FROM field, which MUST be supplied in an SMTP environment,
      SHOULD contain both (1) the name of the source host as presented
      in the EHLO command and (2) an address literal containing the IP
      address of the source, determined from the TCP connection.




Klensin                     Standards Track                    [Page 49]

RFC 2821             Simple Mail Transfer Protocol            April 2001


   -  The ID field MAY contain an "@" as suggested in RFC 822, but this
      is not required.

   -  The FOR field MAY contain a list of <path> entries when multiple
      RCPT commands have been given.  This may raise some security
      issues and is usually not desirable; see section 7.2.

   An Internet mail program MUST NOT change a Received: line that was
   previously added to the message header.  SMTP servers MUST prepend
   Received lines to messages; they MUST NOT change the order of
   existing lines or insert Received lines in any other location.

   As the Internet grows, comparability of Received fields is important
   for detecting problems, especially slow relays.  SMTP servers that
   create Received fields SHOULD use explicit offsets in the dates
   (e.g., -0800), rather than time zone names of any type.  Local time
   (with an offset) is preferred to UT when feasible.  This formulation
   allows slightly more information about local circumstances to be
   specified.  If UT is needed, the receiver need merely do some simple
   arithmetic to convert the values.  Use of UT loses information about
   the time zone-location of the server.  If it is desired to supply a
   time zone name, it SHOULD be included in a comment.

   When the delivery SMTP server makes the "final delivery" of a
   message, it inserts a return-path line at the beginning of the mail
   data.  This use of return-path is required; mail systems MUST support
   it.  The return-path line preserves the information in the <reverse-
   path> from the MAIL command.  Here, final delivery means the message
   has left the SMTP environment.  Normally, this would mean it had been
   delivered to the destination user or an associated mail drop, but in
   some cases it may be further processed and transmitted by another
   mail system.

   It is possible for the mailbox in the return path to be different
   from the actual sender's mailbox, for example, if error responses are
   to be delivered to a special error handling mailbox rather than to
   the message sender.  When mailing lists are involved, this
   arrangement is common and useful as a means of directing errors to
   the list maintainer rather than the message originator.

   The text above implies that the final mail data will begin with a
   return path line, followed by one or more time stamp lines.  These
   lines will be followed by the mail data headers and body [32].

   It is sometimes difficult for an SMTP server to determine whether or
   not it is making final delivery since forwarding or other operations
   may occur after the message is accepted for delivery.  Consequently,




Klensin                     Standards Track                    [Page 50]

RFC 2821             Simple Mail Transfer Protocol            April 2001


   any further (forwarding, gateway, or relay) systems MAY remove the
   return path and rebuild the MAIL command as needed to ensure that
   exactly one such line appears in a delivered message.

   A message-originating SMTP system SHOULD NOT send a message that
   already contains a Return-path header.  SMTP servers performing a
   relay function MUST NOT inspect the message data, and especially not
   to the extent needed to determine if Return-path headers are present.
   SMTP servers making final delivery MAY remove Return-path headers
   before adding their own.

   The primary purpose of the Return-path is to designate the address to
   which messages indicating non-delivery or other mail system failures
   are to be sent.  For this to be unambiguous, exactly one return path
   SHOULD be present when the message is delivered.  Systems using RFC
   822 syntax with non-SMTP transports SHOULD designate an unambiguous
   address, associated with the transport envelope, to which error
   reports (e.g., non-delivery messages) should be sent.

   Historical note: Text in RFC 822 that appears to contradict the use
   of the Return-path header (or the envelope reverse path address from
   the MAIL command) as the destination for error messages is not
   applicable on the Internet.  The reverse path address (as copied into
   the Return-path) MUST be used as the target of any mail containing
   delivery error messages.

   In particular:

   -  a gateway from SMTP->elsewhere SHOULD insert a return-path header,
      unless it is known that the "elsewhere" transport also uses
      Internet domain addresses and maintains the envelope sender
      address separately.

   -  a gateway from elsewhere->SMTP SHOULD delete any return-path
      header present in the message, and either copy that information to
      the SMTP envelope or combine it with information present in the
      envelope of the other transport system to construct the reverse
      path argument to the MAIL command in the SMTP envelope.

   The server must give special treatment to cases in which the
   processing following the end of mail data indication is only
   partially successful.  This could happen if, after accepting several
   recipients and the mail data, the SMTP server finds that the mail
   data could be successfully delivered to some, but not all, of the
   recipients.  In such cases, the response to the DATA command MUST be
   an OK reply.  However, the SMTP server MUST compose and send an
   "undeliverable mail" notification message to the originator of the
   message.



Klensin                     Standards Track                    [Page 51]

RFC 2821             Simple Mail Transfer Protocol            April 2001


   A single notification listing all of the failed recipients or
   separate notification messages MUST be sent for each failed
   recipient.  For economy of processing by the sender, the former is
   preferred when possible.  All undeliverable mail notification
   messages are sent using the MAIL command (even if they result from
   processing the obsolete SEND, SOML, or SAML commands) and use a null
   return path as discussed in section 3.7.

   The time stamp line and the return path line are formally defined as
   follows:

Return-path-line = "Return-Path:" FWS Reverse-path <CRLF>

Time-stamp-line = "Received:" FWS Stamp <CRLF>

Stamp = From-domain By-domain Opt-info ";"  FWS date-time

      ; where "date-time" is as defined in [32]
      ; but the "obs-" forms, especially two-digit
      ; years, are prohibited in SMTP and MUST NOT be used.

From-domain = "FROM" FWS Extended-Domain CFWS

By-domain = "BY" FWS Extended-Domain CFWS

Extended-Domain = Domain /
           ( Domain FWS "(" TCP-info ")" ) /
           ( Address-literal FWS "(" TCP-info ")" )

TCP-info = Address-literal / ( Domain FWS Address-literal )
      ; Information derived by server from TCP connection
      ; not client EHLO.

Opt-info = [Via] [With] [ID] [For]

Via = "VIA" FWS Link CFWS

With = "WITH" FWS Protocol CFWS

ID = "ID" FWS String / msg-id CFWS

For = "FOR" FWS 1*( Path / Mailbox ) CFWS

Link = "TCP" / Addtl-Link
Addtl-Link = Atom
      ; Additional standard names for links are registered with the
         ; Internet Assigned Numbers Authority (IANA).  "Via" is
         ; primarily of value with non-Internet transports.  SMTP



Klensin                     Standards Track                    [Page 52]

RFC 2821             Simple Mail Transfer Protocol            April 2001


         ; servers SHOULD NOT use unregistered names.
Protocol = "ESMTP" / "SMTP" / Attdl-Protocol
Attdl-Protocol = Atom
      ; Additional standard names for protocols are registered with the
         ; Internet Assigned Numbers Authority (IANA).  SMTP servers
         ; SHOULD NOT use unregistered names.

4.5 Additional Implementation Issues

4.5.1 Minimum Implementation

   In order to make SMTP workable, the following minimum implementation
   is required for all receivers.  The following commands MUST be
   supported to conform to this specification:

      EHLO
      HELO
      MAIL
      RCPT
      DATA
      RSET
      NOOP
      QUIT
      VRFY

   Any system that includes an SMTP server supporting mail relaying or
   delivery MUST support the reserved mailbox "postmaster" as a case-
   insensitive local name.  This postmaster address is not strictly
   necessary if the server always returns 554 on connection opening (as
   described in section 3.1).  The requirement to accept mail for
   postmaster implies that RCPT commands which specify a mailbox for
   postmaster at any of the domains for which the SMTP server provides
   mail service, as well as the special case of "RCPT TO:<Postmaster>"
   (with no domain specification), MUST be supported.

   SMTP systems are expected to make every reasonable effort to accept
   mail directed to Postmaster from any other system on the Internet.
   In extreme cases --such as to contain a denial of service attack or
   other breach of security-- an SMTP server may block mail directed to
   Postmaster.  However, such arrangements SHOULD be narrowly tailored
   so as to avoid blocking messages which are not part of such attacks.

4.5.2 Transparency

   Without some provision for data transparency, the character sequence
   "<CRLF>.<CRLF>" ends the mail text and cannot be sent by the user.
   In general, users are not aware of such "forbidden" sequences.  To




Klensin                     Standards Track                    [Page 53]

RFC 2821             Simple Mail Transfer Protocol            April 2001


   allow all user composed text to be transmitted transparently, the
   following procedures are used:

   -  Before sending a line of mail text, the SMTP client checks the
      first character of the line.  If it is a period, one additional
      period is inserted at the beginning of the line.

   -  When a line of mail text is received by the SMTP server, it checks
      the line.  If the line is composed of a single period, it is
      treated as the end of mail indicator.  If the first character is a
      period and there are other characters on the line, the first
      character is deleted.

   The mail data may contain any of the 128 ASCII characters.  All
   characters are to be delivered to the recipient's mailbox, including
   spaces, vertical and horizontal tabs, and other control characters.
   If the transmission channel provides an 8-bit byte (octet) data
   stream, the 7-bit ASCII codes are transmitted right justified in the
   octets, with the high order bits cleared to zero.  See 3.7 for
   special treatment of these conditions in SMTP systems serving a relay
   function.

   In some systems it may be necessary to transform the data as it is
   received and stored.  This may be necessary for hosts that use a
   different character set than ASCII as their local character set, that
   store data in records rather than strings, or which use special
   character sequences as delimiters inside mailboxes.  If such
   transformations are necessary, they MUST be reversible, especially if
   they are applied to mail being relayed.

4.5.3 Sizes and Timeouts

4.5.3.1 Size limits and minimums

   There are several objects that have required minimum/maximum sizes.
   Every implementation MUST be able to receive objects of at least
   these sizes.  Objects larger than these sizes SHOULD be avoided when
   possible.  However, some Internet mail constructs such as encoded
   X.400 addresses [16] will often require larger objects: clients MAY
   attempt to transmit these, but MUST be prepared for a server to
   reject them if they cannot be handled by it.  To the maximum extent
   possible, implementation techniques which impose no limits on the
   length of these objects should be used.

   local-part
      The maximum total length of a user name or other local-part is 64
      characters.




Klensin                     Standards Track                    [Page 54]

RFC 2821             Simple Mail Transfer Protocol            April 2001


   domain
      The maximum total length of a domain name or number is 255
      characters.

   path
      The maximum total length of a reverse-path or forward-path is 256
      characters (including the punctuation and element separators).

   command line
      The maximum total length of a command line including the command
      word and the <CRLF> is 512 characters.  SMTP extensions may be
      used to increase this limit.

   reply line
      The maximum total length of a reply line including the reply code
      and the <CRLF> is 512 characters.  More information may be
      conveyed through multiple-line replies.

   text line
      The maximum total length of a text line including the <CRLF> is
      1000 characters (not counting the leading dot duplicated for
      transparency).  This number may be increased by the use of SMTP
      Service Extensions.

   message content
      The maximum total length of a message content (including any
      message headers as well as the message body) MUST BE at least 64K
      octets.  Since the introduction of Internet standards for
      multimedia mail [12], message lengths on the Internet have grown
      dramatically, and message size restrictions should be avoided if
      at all possible.  SMTP server systems that must impose
      restrictions SHOULD implement the "SIZE" service extension [18],
      and SMTP client systems that will send large messages SHOULD
      utilize it when possible.

   recipients buffer
      The minimum total number of recipients that must be buffered is
      100 recipients.  Rejection of messages (for excessive recipients)
      with fewer than 100 RCPT commands is a violation of this
      specification.  The general principle that relaying SMTP servers
      MUST NOT, and delivery SMTP servers SHOULD NOT, perform validation
      tests on message headers suggests that rejecting a message based
      on the total number of recipients shown in header fields is to be
      discouraged.  A server which imposes a limit on the number of
      recipients MUST behave in an orderly fashion,  such as to reject
      additional addresses over its limit rather than silently
      discarding addresses previously accepted.  A client that needs to




Klensin                     Standards Track                    [Page 55]

RFC 2821             Simple Mail Transfer Protocol            April 2001


      deliver a message containing over 100 RCPT commands SHOULD be
      prepared to transmit in 100-recipient "chunks" if the server
      declines to accept more than 100 recipients in a single message.

   Errors due to exceeding these limits may be reported by using the
   reply codes.  Some examples of reply codes are:

      500 Line too long.
   or
      501 Path too long
   or
      452 Too many recipients  (see below)
   or
      552 Too much mail data.

   RFC 821 [30] incorrectly listed the error where an SMTP server
   exhausts its implementation limit on the number of RCPT commands
   ("too many recipients") as having reply code 552.  The correct reply
   code for this condition is 452.  Clients SHOULD treat a 552 code in
   this case as a temporary, rather than permanent, failure so the logic
   below works.

   When a conforming SMTP server encounters this condition, it has at
   least 100 successful RCPT commands in its recipients buffer.  If the
   server is able to accept the message, then at least these 100
   addresses will be removed from the SMTP client's queue.  When the
   client attempts retransmission of those addresses which received 452
   responses, at least 100 of these will be able to fit in the SMTP
   server's recipients buffer.  Each retransmission attempt which is
   able to deliver anything will be able to dispose of at least 100 of
   these recipients.

   If an SMTP server has an implementation limit on the number of RCPT
   commands and this limit is exhausted, it MUST use a response code of
   452 (but the client SHOULD also be prepared for a 552, as noted
   above).  If the server has a configured site-policy limitation on the
   number of RCPT commands, it MAY instead use a 5XX response code.
   This would be most appropriate if the policy limitation was intended
   to apply if the total recipient count for a particular message body
   were enforced even if that message body was sent in multiple mail
   transactions.

4.5.3.2 Timeouts

   An SMTP client MUST provide a timeout mechanism.  It MUST use per-
   command timeouts rather than somehow trying to time the entire mail
   transaction.  Timeouts SHOULD be easily reconfigurable, preferably
   without recompiling the SMTP code.  To implement this, a timer is set



Klensin                     Standards Track                    [Page 56]

RFC 2821             Simple Mail Transfer Protocol            April 2001


   for each SMTP command and for each buffer of the data transfer.  The
   latter means that the overall timeout is inherently proportional to
   the size of the message.

   Based on extensive experience with busy mail-relay hosts, the minimum
   per-command timeout values SHOULD be as follows:

   Initial 220 Message: 5 minutes
      An SMTP client process needs to distinguish between a failed TCP
      connection and a delay in receiving the initial 220 greeting
      message.  Many SMTP servers accept a TCP connection but delay
      delivery of the 220 message until their system load permits more
      mail to be processed.

   MAIL Command: 5 minutes

   RCPT Command: 5 minutes
      A longer timeout is required if processing of mailing lists and
      aliases is not deferred until after the message was accepted.

   DATA Initiation: 2 minutes
      This is while awaiting the "354 Start Input" reply to a DATA
      command.

   Data Block: 3 minutes
      This is while awaiting the completion of each TCP SEND call
      transmitting a chunk of data.

   DATA Termination: 10 minutes.
      This is while awaiting the "250 OK" reply.  When the receiver gets
      the final period terminating the message data, it typically
      performs processing to deliver the message to a user mailbox.  A
      spurious timeout at this point would be very wasteful and would
      typically result in delivery of multiple copies of the message,
      since it has been successfully sent and the server has accepted
      responsibility for delivery.  See section 6.1 for additional
      discussion.

   An SMTP server SHOULD have a timeout of at least 5 minutes while it
   is awaiting the next command from the sender.

4.5.4 Retry Strategies

   The common structure of a host SMTP implementation includes user
   mailboxes, one or more areas for queuing messages in transit, and one
   or more daemon processes for sending and receiving mail.  The exact
   structure will vary depending on the needs of the users on the host




Klensin                     Standards Track                    [Page 57]

RFC 2821             Simple Mail Transfer Protocol            April 2001


   and the number and size of mailing lists supported by the host.  We
   describe several optimizations that have proved helpful, particularly
   for mailers supporting high traffic levels.

   Any queuing strategy MUST include timeouts on all activities on a
   per-command basis.  A queuing strategy MUST NOT send error messages
   in response to error messages under any circumstances.

4.5.4.1 Sending Strategy

   The general model for an SMTP client is one or more processes that
   periodically attempt to transmit outgoing mail.  In a typical system,
   the program that composes a message has some method for requesting
   immediate attention for a new piece of outgoing mail, while mail that
   cannot be transmitted immediately MUST be queued and periodically
   retried by the sender.  A mail queue entry will include not only the
   message itself but also the envelope information.

   The sender MUST delay retrying a particular destination after one
   attempt has failed.  In general, the retry interval SHOULD be at
   least 30 minutes; however, more sophisticated and variable strategies
   will be beneficial when the SMTP client can determine the reason for
   non-delivery.

   Retries continue until the message is transmitted or the sender gives
   up; the give-up time generally needs to be at least 4-5 days.  The
   parameters to the retry algorithm MUST be configurable.

   A client SHOULD keep a list of hosts it cannot reach and
   corresponding connection timeouts, rather than just retrying queued
   mail items.

   Experience suggests that failures are typically transient (the target
   system or its connection has crashed), favoring a policy of two
   connection attempts in the first hour the message is in the queue,
   and then backing off to one every two or three hours.

   The SMTP client can shorten the queuing delay in cooperation with the
   SMTP server.  For example, if mail is received from a particular
   address, it is likely that mail queued for that host can now be sent.
   Application of this principle may, in many cases, eliminate the
   requirement for an explicit "send queues now" function such as ETRN
   [9].

   The strategy may be further modified as a result of multiple
   addresses per host (see below) to optimize delivery time vs. resource
   usage.




Klensin                     Standards Track                    [Page 58]

RFC 2821             Simple Mail Transfer Protocol            April 2001


   An SMTP client may have a large queue of messages for each
   unavailable destination host.  If all of these messages were retried
   in every retry cycle, there would be excessive Internet overhead and
   the sending system would be blocked for a long period.  Note that an
   SMTP client can generally determine that a delivery attempt has
   failed only after a timeout of several minutes and even a one-minute
   timeout per connection will result in a very large delay if retries
   are repeated for dozens, or even hundreds, of queued messages to the
   same host.

   At the same time, SMTP clients SHOULD use great care in caching
   negative responses from servers.  In an extreme case, if EHLO is
   issued multiple times during the same SMTP connection, different
   answers may be returned by the server.  More significantly, 5yz
   responses to the MAIL command MUST NOT be cached.

   When a mail message is to be delivered to multiple recipients, and
   the SMTP server to which a copy of the message is to be sent is the
   same for multiple recipients, then only one copy of the message
   SHOULD be transmitted.  That is, the SMTP client SHOULD use the
   command sequence:  MAIL, RCPT, RCPT,... RCPT, DATA instead of the
   sequence: MAIL, RCPT, DATA, ..., MAIL, RCPT, DATA.  However, if there
   are very many addresses, a limit on the number of RCPT commands per
   MAIL command MAY be imposed.  Implementation of this efficiency
   feature is strongly encouraged.

   Similarly, to achieve timely delivery, the SMTP client MAY support
   multiple concurrent outgoing mail transactions.  However, some limit
   may be appropriate to protect the host from devoting all its
   resources to mail.

4.5.4.2 Receiving Strategy

   The SMTP server SHOULD attempt to keep a pending listen on the SMTP
   port at all times.  This requires the support of multiple incoming
   TCP connections for SMTP.  Some limit MAY be imposed but servers that
   cannot handle more than one SMTP transaction at a time are not in
   conformance with the intent of this specification.

   As discussed above, when the SMTP server receives mail from a
   particular host address, it could activate its own SMTP queuing
   mechanisms to retry any mail pending for that host address.

4.5.5   Messages with a null reverse-path

   There are several types of notification messages which are required
   by existing and proposed standards to be sent with a null reverse
   path, namely non-delivery notifications as discussed in section 3.7,



Klensin                     Standards Track                    [Page 59]

RFC 2821             Simple Mail Transfer Protocol            April 2001


   other kinds of Delivery Status Notifications (DSNs) [24], and also
   Message Disposition Notifications (MDNs) [10].  All of these kinds of
   messages are notifications about a previous message, and they are
   sent to the reverse-path of the previous mail message.  (If the
   delivery of such a notification message fails, that usually indicates
   a problem with the mail system of the host to which the notification
   message is addressed.  For this reason, at some hosts the MTA is set
   up to forward such failed notification messages to someone who is
   able to fix problems with the mail system, e.g., via the postmaster
   alias.)

   All other types of messages (i.e., any message which is not required
   by a standards-track RFC to have a null reverse-path) SHOULD be sent
   with with a valid, non-null reverse-path.

   Implementors of automated email processors should be careful to make
   sure that the various kinds of messages with null reverse-path are
   handled correctly, in particular such systems SHOULD NOT reply to
   messages with null reverse-path.

5. Address Resolution and Mail Handling

   Once an SMTP client lexically identifies a domain to which mail will
   be delivered for processing (as described in sections 3.6 and 3.7), a
   DNS lookup MUST be performed to resolve the domain name [22].  The
   names are expected to be fully-qualified domain names (FQDNs):
   mechanisms for inferring FQDNs from partial names or local aliases
   are outside of this specification and, due to a history of problems,
   are generally discouraged.  The lookup first attempts to locate an MX
   record associated with the name.  If a CNAME record is found instead,
   the resulting name is processed as if it were the initial name.  If
   no MX records are found, but an A RR is found, the A RR is treated as
   if it was associated with an implicit MX RR, with a preference of 0,
   pointing to that host.  If one or more MX RRs are found for a given
   name, SMTP systems MUST NOT utilize any A RRs associated with that
   name unless they are located using the MX RRs; the "implicit MX" rule
   above applies only if there are no MX records present.  If MX records
   are present, but none of them are usable, this situation MUST be
   reported as an error.

   When the lookup succeeds, the mapping can result in a list of
   alternative delivery addresses rather than a single address, because
   of multiple MX records, multihoming, or both.  To provide reliable
   mail transmission, the SMTP client MUST be able to try (and retry)
   each of the relevant addresses in this list in order, until a
   delivery attempt succeeds.  However, there MAY also be a configurable
   limit on the number of alternate addresses that can be tried.  In any
   case, the SMTP client SHOULD try at least two addresses.



Klensin                     Standards Track                    [Page 60]

RFC 2821             Simple Mail Transfer Protocol            April 2001


   Two types of information is used to rank the host addresses: multiple
   MX records, and multihomed hosts.

   Multiple MX records contain a preference indication that MUST be used
   in sorting (see below).  Lower numbers are more preferred than higher
   ones.  If there are multiple destinations with the same preference
   and there is no clear reason to favor one (e.g., by recognition of an
   easily-reached address), then the sender-SMTP MUST randomize them to
   spread the load across multiple mail exchangers for a specific
   organization.

   The destination host (perhaps taken from the preferred MX record) may
   be multihomed, in which case the domain name resolver will return a
   list of alternative IP addresses.  It is the responsibility of the
   domain name resolver interface to have ordered this list by
   decreasing preference if necessary, and SMTP MUST try them in the
   order presented.

   Although the capability to try multiple alternative addresses is
   required, specific installations may want to limit or disable the use
   of alternative addresses.  The question of whether a sender should
   attempt retries using the different addresses of a multihomed host
   has been controversial.  The main argument for using the multiple
   addresses is that it maximizes the probability of timely delivery,
   and indeed sometimes the probability of any delivery; the counter-
   argument is that it may result in unnecessary resource use.  Note
   that resource use is also strongly determined by the sending strategy
   discussed in section 4.5.4.1.

   If an SMTP server receives a message with a destination for which it
   is a designated Mail eXchanger, it MAY relay the message (potentially
   after having rewritten the MAIL FROM and/or RCPT TO addresses), make
   final delivery of the message, or hand it off using some mechanism
   outside the SMTP-provided transport environment.  Of course, neither
   of the latter require that the list of MX records be examined
   further.

   If it determines that it should relay the message without rewriting
   the address, it MUST sort the MX records to determine candidates for
   delivery.  The records are first ordered by preference, with the
   lowest-numbered records being most preferred.  The relay host MUST
   then inspect the list for any of the names or addresses by which it
   might be known in mail transactions.  If a matching record is found,
   all records at that preference level and higher-numbered ones MUST be
   discarded from consideration.  If there are no records left at that
   point, it is an error condition, and the message MUST be returned as
   undeliverable.  If records do remain, they SHOULD be tried, best
   preference first, as described above.



Klensin                     Standards Track                    [Page 61]

RFC 2821             Simple Mail Transfer Protocol            April 2001


6. Problem Detection and Handling

6.1 Reliable Delivery and Replies by Email

   When the receiver-SMTP accepts a piece of mail (by sending a "250 OK"
   message in response to DATA), it is accepting responsibility for
   delivering or relaying the message.  It must take this responsibility
   seriously.  It MUST NOT lose the message for frivolous reasons, such
   as because the host later crashes or because of a predictable
   resource shortage.

   If there is a delivery failure after acceptance of a message, the
   receiver-SMTP MUST formulate and mail a notification message.  This
   notification MUST be sent using a null ("<>") reverse path in the
   envelope.  The recipient of this notification MUST be the address
   from the envelope return path (or the Return-Path: line).  However,
   if this address is null ("<>"), the receiver-SMTP MUST NOT send a
   notification.  Obviously, nothing in this section can or should
   prohibit local decisions (i.e., as part of the same system
   environment as the receiver-SMTP) to log or otherwise transmit
   information about null address events locally if that is desired.  If
   the address is an explicit source route, it MUST be stripped down to
   its final hop.

   For example, suppose that an error notification must be sent for a
   message that arrived with:

      MAIL FROM:<@a,@b:user@d>

   The notification message MUST be sent using:

      RCPT TO:<user@d>

   Some delivery failures after the message is accepted by SMTP will be
   unavoidable.  For example, it may be impossible for the receiving
   SMTP server to validate all the delivery addresses in RCPT command(s)
   due to a "soft" domain system error, because the target is a mailing
   list (see earlier discussion of RCPT), or because the server is
   acting as a relay and has no immediate access to the delivering
   system.

   To avoid receiving duplicate messages as the result of timeouts, a
   receiver-SMTP MUST seek to minimize the time required to respond to
   the final <CRLF>.<CRLF> end of data indicator.  See RFC 1047 [28] for
   a discussion of this problem.






Klensin                     Standards Track                    [Page 62]

RFC 2821             Simple Mail Transfer Protocol            April 2001


6.2 Loop Detection

   Simple counting of the number of "Received:" headers in a message has
   proven to be an effective, although rarely optimal, method of
   detecting loops in mail systems.  SMTP servers using this technique
   SHOULD use a large rejection threshold, normally at least 100
   Received entries.  Whatever mechanisms are used, servers MUST contain
   provisions for detecting and stopping trivial loops.

6.3 Compensating for Irregularities

   Unfortunately, variations, creative interpretations, and outright
   violations of Internet mail protocols do occur; some would suggest
   that they occur quite frequently.  The debate as to whether a well-
   behaved SMTP receiver or relay should reject a malformed message,
   attempt to pass it on unchanged, or attempt to repair it to increase
   the odds of successful delivery (or subsequent reply) began almost
   with the dawn of structured network mail and shows no signs of
   abating.  Advocates of rejection claim that attempted repairs are
   rarely completely adequate and that rejection of bad messages is the
   only way to get the offending software repaired.  Advocates of
   "repair" or "deliver no matter what" argue that users prefer that
   mail go through it if at all possible and that there are significant
   market pressures in that direction.  In practice, these market
   pressures may be more important to particular vendors than strict
   conformance to the standards, regardless of the preference of the
   actual developers.

   The problems associated with ill-formed messages were exacerbated by
   the introduction of the split-UA mail reading protocols [3, 26, 5,
   21].  These protocols have encouraged the use of SMTP as a posting
   protocol, and SMTP servers as relay systems for these client hosts
   (which are often only intermittently connected to the Internet).
   Historically, many of those client machines lacked some of the
   mechanisms and information assumed by SMTP (and indeed, by the mail
   format protocol [7]).  Some could not keep adequate track of time;
   others had no concept of time zones; still others could not identify
   their own names or addresses; and, of course, none could satisfy the
   assumptions that underlay RFC 822's conception of authenticated
   addresses.

   In response to these weak SMTP clients, many SMTP systems now
   complete messages that are delivered to them in incomplete or
   incorrect form.  This strategy is generally considered appropriate
   when the server can identify or authenticate the client, and there
   are prior agreements between them.  By contrast, there is at best
   great concern about fixes applied by a relay or delivery SMTP server
   that has little or no knowledge of the user or client machine.



Klensin                     Standards Track                    [Page 63]

RFC 2821             Simple Mail Transfer Protocol            April 2001


   The following changes to a message being processed MAY be applied
   when necessary by an originating SMTP server, or one used as the
   target of SMTP as an initial posting protocol:

   -  Addition of a message-id field when none appears

   -  Addition of a date, time or time zone when none appears

   -  Correction of addresses to proper FQDN format

   The less information the server has about the client, the less likely
   these changes are to be correct and the more caution and conservatism
   should be applied when considering whether or not to perform fixes
   and how.  These changes MUST NOT be applied by an SMTP server that
   provides an intermediate relay function.

   In all cases, properly-operating clients supplying correct
   information are preferred to corrections by the SMTP server.  In all
   cases, documentation of actions performed by the servers (in trace
   fields and/or header comments) is strongly encouraged.

7. Security Considerations

7.1 Mail Security and Spoofing

   SMTP mail is inherently insecure in that it is feasible for even
   fairly casual users to negotiate directly with receiving and relaying
   SMTP servers and create messages that will trick a naive recipient
   into believing that they came from somewhere else.  Constructing such
   a message so that the "spoofed" behavior cannot be detected by an
   expert is somewhat more difficult, but not sufficiently so as to be a
   deterrent to someone who is determined and knowledgeable.
   Consequently, as knowledge of Internet mail increases, so does the
   knowledge that SMTP mail inherently cannot be authenticated, or
   integrity checks provided, at the transport level.  Real mail
   security lies only in end-to-end methods involving the message
   bodies, such as those which use digital signatures (see [14] and,
   e.g., PGP [4] or S/MIME [31]).

   Various protocol extensions and configuration options that provide
   authentication at the transport level (e.g., from an SMTP client to
   an SMTP server) improve somewhat on the traditional situation
   described above.  However, unless they are accompanied by careful
   handoffs of responsibility in a carefully-designed trust environment,
   they remain inherently weaker than end-to-end mechanisms which use
   digitally signed messages rather than depending on the integrity of
   the transport system.




Klensin                     Standards Track                    [Page 64]

RFC 2821             Simple Mail Transfer Protocol            April 2001


   Efforts to make it more difficult for users to set envelope return
   path and header "From" fields to point to valid addresses other than
   their own are largely misguided: they frustrate legitimate
   applications in which mail is sent by one user on behalf of another
   or in which error (or normal) replies should be directed to a special
   address.  (Systems that provide convenient ways for users to alter
   these fields on a per-message basis should attempt to establish a
   primary and permanent mailbox address for the user so that Sender
   fields within the message data can be generated sensibly.)

   This specification does not further address the authentication issues
   associated with SMTP other than to advocate that useful functionality
   not be disabled in the hope of providing some small margin of
   protection against an ignorant user who is trying to fake mail.

7.2 "Blind" Copies

   Addresses that do not appear in the message headers may appear in the
   RCPT commands to an SMTP server for a number of reasons.  The two
   most common involve the use of a mailing address as a "list exploder"
   (a single address that resolves into multiple addresses) and the
   appearance of "blind copies".  Especially when more than one RCPT
   command is present, and in order to avoid defeating some of the
   purpose of these mechanisms, SMTP clients and servers SHOULD NOT copy
   the full set of RCPT command arguments into the headers, either as
   part of trace headers or as informational or private-extension
   headers.  Since this rule is often violated in practice, and cannot
   be enforced, sending SMTP systems that are aware of "bcc" use MAY
   find it helpful to send each blind copy as a separate message
   transaction containing only a single RCPT command.

   There is no inherent relationship between either "reverse" (from
   MAIL, SAML, etc., commands) or "forward" (RCPT) addresses in the SMTP
   transaction ("envelope") and the addresses in the headers.  Receiving
   systems SHOULD NOT attempt to deduce such relationships and use them
   to alter the headers of the message for delivery.  The popular
   "Apparently-to" header is a violation of this principle as well as a
   common source of unintended information disclosure and SHOULD NOT be
   used.

7.3 VRFY, EXPN, and Security

   As discussed in section 3.5, individual sites may want to disable
   either or both of VRFY or EXPN for security reasons.  As a corollary
   to the above, implementations that permit this MUST NOT appear to
   have verified addresses that are not, in fact, verified.  If a site





Klensin                     Standards Track                    [Page 65]

RFC 2821             Simple Mail Transfer Protocol            April 2001


   disables these commands for security reasons, the SMTP server MUST
   return a 252 response, rather than a code that could be confused with
   successful or unsuccessful verification.

   Returning a 250 reply code with the address listed in the VRFY
   command after having checked it only for syntax violates this rule.
   Of course, an implementation that "supports" VRFY by always returning
   550 whether or not the address is valid is equally not in
   conformance.

   Within the last few years, the contents of mailing lists have become
   popular as an address information source for so-called "spammers."
   The use of EXPN to "harvest" addresses has increased as list
   administrators have installed protections against inappropriate uses
   of the lists themselves.  Implementations SHOULD still provide
   support for EXPN, but sites SHOULD carefully evaluate the tradeoffs.
   As authentication mechanisms are introduced into SMTP, some sites may
   choose to make EXPN available only to authenticated requestors.

7.4 Information Disclosure in Announcements

   There has been an ongoing debate about the tradeoffs between the
   debugging advantages of announcing server type and version (and,
   sometimes, even server domain name) in the greeting response or in
   response to the HELP command and the disadvantages of exposing
   information that might be useful in a potential hostile attack.  The
   utility of the debugging information is beyond doubt.  Those who
   argue for making it available point out that it is far better to
   actually secure an SMTP server rather than hope that trying to
   conceal known vulnerabilities by hiding the server's precise identity
   will provide more protection.  Sites are encouraged to evaluate the
   tradeoff with that issue in mind; implementations are strongly
   encouraged to minimally provide for making type and version
   information available in some way to other network hosts.

7.5 Information Disclosure in Trace Fields

   In some circumstances, such as when mail originates from within a LAN
   whose hosts are not directly on the public Internet, trace
   ("Received") fields produced in conformance with this specification
   may disclose host names and similar information that would not
   normally be available.  This ordinarily does not pose a problem, but
   sites with special concerns about name disclosure should be aware of
   it.  Also, the optional FOR clause should be supplied with caution or
   not at all when multiple recipients are involved lest it
   inadvertently disclose the identities of "blind copy" recipients to
   others.




Klensin                     Standards Track                    [Page 66]

RFC 2821             Simple Mail Transfer Protocol            April 2001


7.6 Information Disclosure in Message Forwarding

   As discussed in section 3.4, use of the 251 or 551 reply codes to
   identify the replacement address associated with a mailbox may
   inadvertently disclose sensitive information.  Sites that are
   concerned about those issues should ensure that they select and
   configure servers appropriately.

7.7 Scope of Operation of SMTP Servers

   It is a well-established principle that an SMTP server may refuse to
   accept mail for any operational or technical reason that makes sense
   to the site providing the server.  However, cooperation among sites
   and installations makes the Internet possible.  If sites take
   excessive advantage of the right to reject traffic, the ubiquity of
   email availability (one of the strengths of the Internet) will be
   threatened; considerable care should be taken and balance maintained
   if a site decides to be selective about the traffic it will accept
   and process.

   In recent years, use of the relay function through arbitrary sites
   has been used as part of hostile efforts to hide the actual origins
   of mail.  Some sites have decided to limit the use of the relay
   function to known or identifiable sources, and implementations SHOULD
   provide the capability to perform this type of filtering.  When mail
   is rejected for these or other policy reasons, a 550 code SHOULD be
   used in response to EHLO, MAIL, or RCPT as appropriate.

8. IANA Considerations

   IANA will maintain three registries in support of this specification.
   The first consists of SMTP service extensions with the associated
   keywords, and, as needed, parameters and verbs.  As specified in
   section 2.2.2, no entry may be made in this registry that starts in
   an "X".  Entries may be made only for service extensions (and
   associated keywords, parameters, or verbs) that are defined in
   standards-track or experimental RFCs specifically approved by the
   IESG for this purpose.

   The second registry consists of "tags" that identify forms of domain
   literals other than those for IPv4 addresses (specified in RFC 821
   and in this document) and IPv6 addresses (specified in this
   document).  Additional literal types require standardization before
   being used; none are anticipated at this time.

   The third, established by RFC 821 and renewed by this specification,
   is a registry of link and protocol identifiers to be used with the
   "via" and "with" subclauses of the time stamp ("Received: header")



Klensin                     Standards Track                    [Page 67]

RFC 2821             Simple Mail Transfer Protocol            April 2001


   described in section 4.4.  Link and protocol identifiers in addition
   to those specified in this document may be registered only by
   standardization or by way of an RFC-documented, IESG-approved,
   Experimental protocol extension.

9. References

   [1]  American National Standards Institute (formerly United States of
        America Standards Institute), X3.4, 1968, "USA Code for
        Information Interchange". ANSI X3.4-1968 has been replaced by
        newer versions with slight modifications, but the 1968 version
        remains definitive for the Internet.

   [2]  Braden, R., "Requirements for Internet hosts - application and
        support", STD 3, RFC 1123, October 1989.

   [3]  Butler, M., Chase, D., Goldberger, J., Postel, J. and J.
        Reynolds, "Post Office Protocol - version 2", RFC 937, February
        1985.

   [4]  Callas, J., Donnerhacke, L., Finney, H. and R. Thayer, "OpenPGP
        Message Format", RFC 2440, November 1998.

   [5]  Crispin, M., "Interactive Mail Access Protocol - Version 2", RFC
        1176, August 1990.

   [6]  Crispin, M., "Internet Message Access Protocol - Version 4", RFC
        2060, December 1996.

   [7]  Crocker, D., "Standard for the Format of ARPA Internet Text
        Messages", RFC 822, August 1982.

   [8]  Crocker, D. and P. Overell, Eds., "Augmented BNF for Syntax
        Specifications: ABNF", RFC 2234, November 1997.

   [9]  De Winter, J., "SMTP Service Extension for Remote Message Queue
        Starting", RFC 1985, August 1996.

   [10] Fajman, R., "An Extensible Message Format for Message
        Disposition Notifications", RFC 2298, March 1998.

   [11] Freed, N, "Behavior of and Requirements for Internet Firewalls",
        RFC 2979, October 2000.

   [12] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
        Extensions (MIME) Part One: Format of Internet Message Bodies",
        RFC 2045, December 1996.




Klensin                     Standards Track                    [Page 68]

RFC 2821             Simple Mail Transfer Protocol            April 2001


   [13] Freed, N., "SMTP Service Extension for Command Pipelining", RFC
        2920, September 2000.

   [14] Galvin, J., Murphy, S., Crocker, S. and N. Freed, "Security
        Multiparts for MIME: Multipart/Signed and Multipart/Encrypted",
        RFC 1847, October 1995.

   [15] Gellens, R. and J. Klensin, "Message Submission", RFC 2476,
        December 1998.

   [16] Kille, S., "Mapping between X.400 and RFC822/MIME", RFC 2156,
        January 1998.

   [17] Hinden, R and S. Deering, Eds. "IP Version 6 Addressing
        Architecture", RFC 2373, July 1998.

   [18] Klensin, J., Freed, N. and K. Moore, "SMTP Service Extension for
        Message Size Declaration", STD 10, RFC 1870, November 1995.

   [19] Klensin, J., Freed, N., Rose, M., Stefferud, E. and D. Crocker,
        "SMTP Service Extensions", STD 10, RFC 1869, November 1995.

   [20] Klensin, J., Freed, N., Rose, M., Stefferud, E. and D. Crocker,
        "SMTP Service Extension for 8bit-MIMEtransport", RFC 1652, July
        1994.

   [21] Lambert, M., "PCMAIL: A distributed mail system for personal
        computers", RFC 1056, July 1988.

   [22] Mockapetris, P., "Domain names - implementation and
        specification", STD 13, RFC 1035, November 1987.

        Mockapetris, P., "Domain names - concepts and facilities", STD
        13, RFC 1034, November 1987.

   [23] Moore, K., "MIME (Multipurpose Internet Mail Extensions) Part
        Three: Message Header Extensions for Non-ASCII Text", RFC 2047,
        December 1996.

   [24] Moore, K., "SMTP Service Extension for Delivery Status
        Notifications", RFC 1891, January 1996.

   [25] Moore, K., and G. Vaudreuil, "An Extensible Message Format for
        Delivery Status Notifications", RFC 1894, January 1996.

   [26] Myers, J. and M. Rose, "Post Office Protocol - Version 3", STD
        53, RFC 1939, May 1996.




Klensin                     Standards Track                    [Page 69]

RFC 2821             Simple Mail Transfer Protocol            April 2001


   [27] Partridge, C., "Mail routing and the domain system", RFC 974,
        January 1986.

   [28] Partridge, C., "Duplicate messages and SMTP", RFC 1047, February
        1988.

   [29] Postel, J., ed., "Transmission Control Protocol - DARPA Internet
        Program Protocol Specification", STD 7, RFC 793, September 1981.

   [30] Postel, J., "Simple Mail Transfer Protocol", RFC 821, August
        1982.

   [31] Ramsdell, B., Ed., "S/MIME Version 3 Message Specification", RFC
        2633, June 1999.

   [32] Resnick, P., Ed., "Internet Message Format", RFC 2822, April
        2001.

   [33] Vaudreuil, G., "SMTP Service Extensions for Transmission of
        Large and Binary MIME Messages", RFC 1830, August 1995.

   [34] Vaudreuil, G., "Enhanced Mail System Status Codes", RFC 1893,
        January 1996.

10. Editor's Address

   John C. Klensin
   AT&T Laboratories
   99 Bedford St
   Boston, MA 02111 USA

   Phone: 617-574-3076
   EMail: klensin@research.att.com

11. Acknowledgments

   Many people worked long and hard on the many iterations of this
   document.  There was wide-ranging debate in the IETF DRUMS Working
   Group, both on its mailing list and in face to face discussions,
   about many technical issues and the role of a revised standard for
   Internet mail transport, and many contributors helped form the
   wording in this specification.  The hundreds of participants in the
   many discussions since RFC 821 was produced are too numerous to
   mention, but they all helped this document become what it is.







Klensin                     Standards Track                    [Page 70]

RFC 2821             Simple Mail Transfer Protocol            April 2001


APPENDICES

A. TCP Transport Service

   The TCP connection supports the transmission of 8-bit bytes.  The
   SMTP data is 7-bit ASCII characters.  Each character is transmitted
   as an 8-bit byte with the high-order bit cleared to zero.  Service
   extensions may modify this rule to permit transmission of full 8-bit
   data bytes as part of the message body, but not in SMTP commands or
   responses.

B. Generating SMTP Commands from RFC 822 Headers

   Some systems use RFC 822 headers (only) in a mail submission
   protocol, or otherwise generate SMTP commands from RFC 822 headers
   when such a message is handed to an MTA from a UA.  While the MTA-UA
   protocol is a private matter, not covered by any Internet Standard,
   there are problems with this approach.  For example, there have been
   repeated problems with proper handling of "bcc" copies and
   redistribution lists when information that conceptually belongs to a
   mail envelopes is not separated early in processing from header
   information (and kept separate).

   It is recommended that the UA provide its initial ("submission
   client") MTA with an envelope separate from the message itself.
   However, if the envelope is not supplied, SMTP commands SHOULD be
   generated as follows:

   1. Each recipient address from a TO, CC, or BCC header field SHOULD
      be copied to a RCPT command (generating multiple message copies if
      that is required for queuing or delivery).  This includes any
      addresses listed in a RFC 822 "group".  Any BCC fields SHOULD then
      be removed from the headers.  Once this process is completed, the
      remaining headers SHOULD be checked to verify that at least one
      To:, Cc:, or Bcc: header remains.  If none do, then a bcc: header
      with no additional information SHOULD be inserted as specified in
      [32].

   2. The return address in the MAIL command SHOULD, if possible, be
      derived from the system's identity for the submitting (local)
      user, and the "From:" header field otherwise.  If there is a
      system identity available, it SHOULD also be copied to the Sender
      header field if it is different from the address in the From
      header field.  (Any Sender field that was already there SHOULD be
      removed.)  Systems may provide a way for submitters to override
      the envelope return address, but may want to restrict its use to
      privileged users.  This will not prevent mail forgery, but may
      lessen its incidence; see section 7.1.



Klensin                     Standards Track                    [Page 71]

RFC 2821             Simple Mail Transfer Protocol            April 2001


   When an MTA is being used in this way, it bears responsibility for
   ensuring that the message being transmitted is valid.  The mechanisms
   for checking that validity, and for handling (or returning) messages
   that are not valid at the time of arrival, are part of the MUA-MTA
   interface and not covered by this specification.

   A submission protocol based on Standard RFC 822 information alone
   MUST NOT be used to gateway a message from a foreign (non-SMTP) mail
   system into an SMTP environment.  Additional information to construct
   an envelope must come from some source in the other environment,
   whether supplemental headers or the foreign system's envelope.

   Attempts to gateway messages using only their header "to" and "cc"
   fields have repeatedly caused mail loops and other behavior adverse
   to the proper functioning of the Internet mail environment.  These
   problems have been especially common when the message originates from
   an Internet mailing list and is distributed into the foreign
   environment using envelope information.  When these messages are then
   processed by a header-only remailer, loops back to the Internet
   environment (and the mailing list) are almost inevitable.

C. Source Routes

   Historically, the <reverse-path> was a reverse source routing list of
   hosts and a source mailbox.  The first host in the <reverse-path>
   SHOULD be the host sending the MAIL command.  Similarly, the
   <forward-path> may be a source routing lists of hosts and a
   destination mailbox.  However, in general, the <forward-path> SHOULD
   contain only a mailbox and domain name, relying on the domain name
   system to supply routing information if required.  The use of source
   routes is deprecated; while servers MUST be prepared to receive and
   handle them as discussed in section 3.3 and F.2, clients SHOULD NOT
   transmit them and this section was included only to provide context.

   For relay purposes, the forward-path may be a source route of the
   form "@ONE,@TWO:JOE@THREE", where ONE, TWO, and THREE MUST BE fully-
   qualified domain names.  This form is used to emphasize the
   distinction between an address and a route.  The mailbox is an
   absolute address, and the route is information about how to get
   there.  The two concepts should not be confused.

   If source routes are used, RFC 821 and the text below should be
   consulted for the mechanisms for constructing and updating the
   forward- and reverse-paths.







Klensin                     Standards Track                    [Page 72]

RFC 2821             Simple Mail Transfer Protocol            April 2001


   The SMTP server transforms the command arguments by moving its own
   identifier (its domain name or that of any domain for which it is
   acting as a mail exchanger), if it appears, from the forward-path to
   the beginning of the reverse-path.

   Notice that the forward-path and reverse-path appear in the SMTP
   commands and replies, but not necessarily in the message.  That is,
   there is no need for these paths and especially this syntax to appear
   in the "To:" , "From:", "CC:", etc. fields of the message header.
   Conversely, SMTP servers MUST NOT derive final message delivery
   information from message header fields.

   When the list of hosts is present, it is a "reverse" source route and
   indicates that the mail was relayed through each host on the list
   (the first host in the list was the most recent relay).  This list is
   used as a source route to return non-delivery notices to the sender.
   As each relay host adds itself to the beginning of the list, it MUST
   use its name as known in the transport environment to which it is
   relaying the mail rather than that of the transport environment from
   which the mail came (if they are different).

D. Scenarios

   This section presents complete scenarios of several types of SMTP
   sessions.  In the examples, "C:" indicates what is said by the SMTP
   client, and "S:" indicates what is said by the SMTP server.

D.1 A Typical SMTP Transaction Scenario

   This SMTP example shows mail sent by Smith at host bar.com, to Jones,
   Green, and Brown at host foo.com.  Here we assume that host bar.com
   contacts host foo.com directly.  The mail is accepted for Jones and
   Brown.  Green does not have a mailbox at host foo.com.

      S: 220 foo.com Simple Mail Transfer Service Ready
      C: EHLO bar.com
      S: 250-foo.com greets bar.com
      S: 250-8BITMIME
      S: 250-SIZE
      S: 250-DSN
      S: 250 HELP
      C: MAIL FROM:<Smith@bar.com>
      S: 250 OK
      C: RCPT TO:<Jones@foo.com>
      S: 250 OK
      C: RCPT TO:<Green@foo.com>
      S: 550 No such user here
      C: RCPT TO:<Brown@foo.com>



Klensin                     Standards Track                    [Page 73]

RFC 2821             Simple Mail Transfer Protocol            April 2001


      S: 250 OK
      C: DATA
      S: 354 Start mail input; end with <CRLF>.<CRLF>
      C: Blah blah blah...
      C: ...etc. etc. etc.
      C: .
      S: 250 OK
      C: QUIT
      S: 221 foo.com Service closing transmission channel

D.2 Aborted SMTP Transaction Scenario

      S: 220 foo.com Simple Mail Transfer Service Ready
      C: EHLO bar.com
      S: 250-foo.com greets bar.com
      S: 250-8BITMIME
      S: 250-SIZE
      S: 250-DSN
      S: 250 HELP
      C: MAIL FROM:<Smith@bar.com>
      S: 250 OK
      C: RCPT TO:<Jones@foo.com>
      S: 250 OK
      C: RCPT TO:<Green@foo.com>
      S: 550 No such user here
      C: RSET
      S: 250 OK
      C: QUIT
      S: 221 foo.com Service closing transmission channel

D.3 Relayed Mail Scenario

   Step 1  --  Source Host to Relay Host

      S: 220 foo.com Simple Mail Transfer Service Ready
      C: EHLO bar.com
      S: 250-foo.com greets bar.com
      S: 250-8BITMIME
      S: 250-SIZE
      S: 250-DSN
      S: 250 HELP
      C: MAIL FROM:<JQP@bar.com>
      S: 250 OK
      C: RCPT TO:<@foo.com:Jones@XYZ.COM>
      S: 250 OK
      C: DATA
      S: 354 Start mail input; end with <CRLF>.<CRLF>
      C: Date: Thu, 21 May 1998 05:33:29 -0700



Klensin                     Standards Track                    [Page 74]

RFC 2821             Simple Mail Transfer Protocol            April 2001


      C: From: John Q. Public <JQP@bar.com>
      C: Subject:  The Next Meeting of the Board
      C: To: Jones@xyz.com
      C:
      C: Bill:
      C: The next meeting of the board of directors will be
      C: on Tuesday.
      C:                         John.
      C: .
      S: 250 OK
      C: QUIT
      S: 221 foo.com Service closing transmission channel

   Step 2  --  Relay Host to Destination Host

      S: 220 xyz.com Simple Mail Transfer Service Ready
      C: EHLO foo.com
      S: 250 xyz.com is on the air
      C: MAIL FROM:<@foo.com:JQP@bar.com>
      S: 250 OK
      C: RCPT TO:<Jones@XYZ.COM>
      S: 250 OK
      C: DATA
      S: 354 Start mail input; end with <CRLF>.<CRLF>
      C: Received: from bar.com by foo.com ; Thu, 21 May 1998
      C:     05:33:29 -0700
      C: Date: Thu, 21 May 1998 05:33:22 -0700
      C: From: John Q. Public <JQP@bar.com>
      C: Subject:  The Next Meeting of the Board
      C: To: Jones@xyz.com
      C:
      C: Bill:
      C: The next meeting of the board of directors will be
      C: on Tuesday.
      C:                         John.
      C: .
      S: 250 OK
      C: QUIT
      S: 221 foo.com Service closing transmission channel

D.4 Verifying and Sending Scenario

      S: 220 foo.com Simple Mail Transfer Service Ready
      C: EHLO bar.com
      S: 250-foo.com greets bar.com
      S: 250-8BITMIME
      S: 250-SIZE
      S: 250-DSN



Klensin                     Standards Track                    [Page 75]

RFC 2821             Simple Mail Transfer Protocol            April 2001


      S: 250-VRFY
      S: 250 HELP
      C: VRFY Crispin
      S: 250 Mark Crispin <Admin.MRC@foo.com>
      C: SEND FROM:<EAK@bar.com>
      S: 250 OK
      C: RCPT TO:<Admin.MRC@foo.com>
      S: 250 OK
      C: DATA
      S: 354 Start mail input; end with <CRLF>.<CRLF>
      C: Blah blah blah...
      C: ...etc. etc. etc.
      C: .
      S: 250 OK
      C: QUIT
      S: 221 foo.com Service closing transmission channel

E. Other Gateway Issues

   In general, gateways between the Internet and other mail systems
   SHOULD attempt to preserve any layering semantics across the
   boundaries between the two mail systems involved.  Gateway-
   translation approaches that attempt to take shortcuts by mapping,
   (such as envelope information from one system to the message headers
   or body of another) have generally proven to be inadequate in
   important ways.  Systems translating between environments that do not
   support both envelopes and headers and Internet mail must be written
   with the understanding that some information loss is almost
   inevitable.

F. Deprecated Features of RFC 821

   A few features of RFC 821 have proven to be problematic and SHOULD
   NOT be used in Internet mail.

F.1 TURN

   This command, described in RFC 821, raises important security issues
   since, in the absence of strong authentication of the host requesting
   that the client and server switch roles, it can easily be used to
   divert mail from its correct destination.  Its use is deprecated;
   SMTP systems SHOULD NOT use it unless the server can authenticate the
   client.








Klensin                     Standards Track                    [Page 76]

RFC 2821             Simple Mail Transfer Protocol            April 2001


F.2 Source Routing

   RFC 821 utilized the concept of explicit source routing to get mail
   from one host to another via a series of relays.  The requirement to
   utilize source routes in regular mail traffic was eliminated by the
   introduction of the domain name system "MX" record and the last
   significant justification for them was eliminated by the
   introduction, in RFC 1123, of a clear requirement that addresses
   following an "@" must all be fully-qualified domain names.
   Consequently, the only remaining justifications for the use of source
   routes are support for very old SMTP clients or MUAs and in mail
   system debugging.  They can, however, still be useful in the latter
   circumstance and for routing mail around serious, but temporary,
   problems such as problems with the relevant DNS records.

   SMTP servers MUST continue to accept source route syntax as specified
   in the main body of this document and in RFC 1123.  They MAY, if
   necessary, ignore the routes and utilize only the target domain in
   the address.  If they do utilize the source route, the message MUST
   be sent to the first domain shown in the address.  In particular, a
   server MUST NOT guess at shortcuts within the source route.

   Clients SHOULD NOT utilize explicit source routing except under
   unusual circumstances, such as debugging or potentially relaying
   around firewall or mail system configuration errors.

F.3 HELO

   As discussed in sections 3.1 and 4.1.1, EHLO is strongly preferred to
   HELO when the server will accept the former.  Servers must continue
   to accept and process HELO in order to support older clients.

F.4 #-literals

   RFC 821 provided for specifying an Internet address as a decimal
   integer host number prefixed by a pound sign, "#".  In practice, that
   form has been obsolete since the introduction of TCP/IP.  It is
   deprecated and MUST NOT be used.

F.5 Dates and Years

   When dates are inserted into messages by SMTP clients or servers
   (e.g., in trace fields), four-digit years MUST BE used.  Two-digit
   years are deprecated; three-digit years were never permitted in the
   Internet mail system.






Klensin                     Standards Track                    [Page 77]

RFC 2821             Simple Mail Transfer Protocol            April 2001


F.6 Sending versus Mailing

   In addition to specifying a mechanism for delivering messages to
   user's mailboxes, RFC 821 provided additional, optional, commands to
   deliver messages directly to the user's terminal screen.  These
   commands (SEND, SAML, SOML) were rarely implemented, and changes in
   workstation technology and the introduction of other protocols may
   have rendered them obsolete even where they are implemented.

   Clients SHOULD NOT provide SEND, SAML, or SOML as services.  Servers
   MAY implement them.  If they are implemented by servers, the
   implementation model specified in RFC 821 MUST be used and the
   command names MUST be published in the response to the EHLO command.






































Klensin                     Standards Track                    [Page 78]

RFC 2821             Simple Mail Transfer Protocol            April 2001


Full Copyright Statement

   Copyright (C) The Internet Society (2001).  All Rights Reserved.

   This document and translations of it may be copied and furnished to
   others, and derivative works that comment on or otherwise explain it
   or assist in its implementation may be prepared, copied, published
   and distributed, in whole or in part, without restriction of any
   kind, provided that the above copyright notice and this paragraph are
   included on all such copies and derivative works.  However, this
   document itself may not be modified in any way, such as by removing
   the copyright notice or references to the Internet Society or other
   Internet organizations, except as needed for the purpose of
   developing Internet standards in which case the procedures for
   copyrights defined in the Internet Standards process must be
   followed, or as required to translate it into languages other than
   English.

   The limited permissions granted above are perpetual and will not be
   revoked by the Internet Society or its successors or assigns.

   This document and the information contained herein is provided on an
   "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
   TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
   BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
   HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
   MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Acknowledgement

   Funding for the RFC Editor function is currently provided by the
   Internet Society.



















Klensin                     Standards Track                    [Page 79]



================================================
FILE: doc/notes/rfc/rfc2822.txt
================================================






Network Working Group                                 P. Resnick, Editor
Request for Comments: 2822                         QUALCOMM Incorporated
Obsoletes: 822                                                April 2001
Category: Standards Track


                        Internet Message Format

Status of this Memo

   This document specifies an Internet standards track protocol for the
   Internet community, and requests discussion and suggestions for
   improvements.  Please refer to the current edition of the "Internet
   Official Protocol Standards" (STD 1) for the standardization state
   and status of this protocol.  Distribution of this memo is unlimited.

Copyright Notice

   Copyright (C) The Internet Society (2001).  All Rights Reserved.

Abstract

   This standard specifies a syntax for text messages that are sent
   between computer users, within the framework of "electronic mail"
   messages.  This standard supersedes the one specified in Request For
   Comments (RFC) 822, "Standard for the Format of ARPA Internet Text
   Messages", updating it to reflect current practice and incorporating
   incremental changes that were specified in other RFCs.

Table of Contents

   1. Introduction ............................................... 3
   1.1. Scope .................................................... 3
   1.2. Notational conventions ................................... 4
   1.2.1. Requirements notation .................................. 4
   1.2.2. Syntactic notation ..................................... 4
   1.3. Structure of this document ............................... 4
   2. Lexical Analysis of Messages ............................... 5
   2.1. General Description ...................................... 5
   2.1.1. Line Length Limits ..................................... 6
   2.2. Header Fields ............................................ 7
   2.2.1. Unstructured Header Field Bodies ....................... 7
   2.2.2. Structured Header Field Bodies ......................... 7
   2.2.3. Long Header Fields ..................................... 7
   2.3. Body ..................................................... 8
   3. Syntax ..................................................... 9
   3.1. Introduction ............................................. 9
   3.2. Lexical Tokens ........................................... 9



Resnick                     Standards Track                     [Page 1]

RFC 2822                Internet Message Format               April 2001


   3.2.1. Primitive Tokens ....................................... 9
   3.2.2. Quoted characters ......................................10
   3.2.3. Folding white space and comments .......................11
   3.2.4. Atom ...................................................12
   3.2.5. Quoted strings .........................................13
   3.2.6. Miscellaneous tokens ...................................13
   3.3. Date and Time Specification ..............................14
   3.4. Address Specification ....................................15
   3.4.1. Addr-spec specification ................................16
   3.5 Overall message syntax ....................................17
   3.6. Field definitions ........................................18
   3.6.1. The origination date field .............................20
   3.6.2. Originator fields ......................................21
   3.6.3. Destination address fields .............................22
   3.6.4. Identification fields ..................................23
   3.6.5. Informational fields ...................................26
   3.6.6. Resent fields ..........................................26
   3.6.7. Trace fields ...........................................28
   3.6.8. Optional fields ........................................29
   4. Obsolete Syntax ............................................29
   4.1. Miscellaneous obsolete tokens ............................30
   4.2. Obsolete folding white space .............................31
   4.3. Obsolete Date and Time ...................................31
   4.4. Obsolete Addressing ......................................33
   4.5. Obsolete header fields ...................................33
   4.5.1. Obsolete origination date field ........................34
   4.5.2. Obsolete originator fields .............................34
   4.5.3. Obsolete destination address fields ....................34
   4.5.4. Obsolete identification fields .........................35
   4.5.5. Obsolete informational fields ..........................35
   4.5.6. Obsolete resent fields .................................35
   4.5.7. Obsolete trace fields ..................................36
   4.5.8. Obsolete optional fields ...............................36
   5. Security Considerations ....................................36
   6. Bibliography ...............................................37
   7. Editor's Address ...........................................38
   8. Acknowledgements ...........................................39
   Appendix A. Example messages ..................................41
   A.1. Addressing examples ......................................41
   A.1.1. A message from one person to another with simple
          addressing .............................................41
   A.1.2. Different types of mailboxes ...........................42
   A.1.3. Group addresses ........................................43
   A.2. Reply messages ...........................................43
   A.3. Resent messages ..........................................44
   A.4. Messages with trace fields ...............................46
   A.5. White space, comments, and other oddities ................47
   A.6. Obsoleted forms ..........................................47



Resnick                     Standards Track                     [Page 2]

RFC 2822                Internet Message Format               April 2001


   A.6.1. Obsolete addressing ....................................48
   A.6.2. Obsolete dates .........................................48
   A.6.3. Obsolete white space and comments ......................48
   Appendix B. Differences from earlier standards ................49
   Appendix C. Notices ...........................................50
   Full Copyright Statement ......................................51

1. Introduction

1.1. Scope

   This standard specifies a syntax for text messages that are sent
   between computer users, within the framework of "electronic mail"
   messages.  This standard supersedes the one specified in Request For
   Comments (RFC) 822, "Standard for the Format of ARPA Internet Text
   Messages" [RFC822], updating it to reflect current practice and
   incorporating incremental changes that were specified in other RFCs
   [STD3].

   This standard specifies a syntax only for text messages.  In
   particular, it makes no provision for the transmission of images,
   audio, or other sorts of structured data in electronic mail messages.
   There are several extensions published, such as the MIME document
   series [RFC2045, RFC2046, RFC2049], which describe mechanisms for the
   transmission of such data through electronic mail, either by
   extending the syntax provided here or by structuring such messages to
   conform to this syntax.  Those mechanisms are outside of the scope of
   this standard.

   In the context of electronic mail, messages are viewed as having an
   envelope and contents.  The envelope contains whatever information is
   needed to accomplish transmission and delivery.  (See [RFC2821] for a
   discussion of the envelope.)  The contents comprise the object to be
   delivered to the recipient.  This standard applies only to the format
   and some of the semantics of message contents.  It contains no
   specification of the information in the envelope.

   However, some message systems may use information from the contents
   to create the envelope.  It is intended that this standard facilitate
   the acquisition of such information by programs.

   This specification is intended as a definition of what message
   content format is to be passed between systems.  Though some message
   systems locally store messages in this format (which eliminates the
   need for translation between formats) and others use formats that
   differ from the one specified in this standard, local storage is
   outside of the scope of this standard.




Resnick                     Standards Track                     [Page 3]

RFC 2822                Internet Message Format               April 2001


   Note: This standard is not intended to dictate the internal formats
   used by sites, the specific message system features that they are
   expected to support, or any of the characteristics of user interface
   programs that create or read messages.  In addition, this standard
   does not specify an encoding of the characters for either transport
   or storage; that is, it does not specify the number of bits used or
   how those bits are specifically transferred over the wire or stored
   on disk.

1.2. Notational conventions

1.2.1. Requirements notation

   This document occasionally uses terms that appear in capital letters.
   When the terms "MUST", "SHOULD", "RECOMMENDED", "MUST NOT", "SHOULD
   NOT", and "MAY" appear capitalized, they are being used to indicate
   particular requirements of this specification.  A discussion of the
   meanings of these terms appears in [RFC2119].

1.2.2. Syntactic notation

   This standard uses the Augmented Backus-Naur Form (ABNF) notation
   specified in [RFC2234] for the formal definitions of the syntax of
   messages.  Characters will be specified either by a decimal value
   (e.g., the value %d65 for uppercase A and %d97 for lowercase A) or by
   a case-insensitive literal value enclosed in quotation marks (e.g.,
   "A" for either uppercase or lowercase A).  See [RFC2234] for the full
   description of the notation.

1.3. Structure of this document

   This document is divided into several sections.

   This section, section 1, is a short introduction to the document.

   Section 2 lays out the general description of a message and its
   constituent parts.  This is an overview to help the reader understand
   some of the general principles used in the later portions of this
   document.  Any examples in this section MUST NOT be taken as
   specification of the formal syntax of any part of a message.

   Section 3 specifies formal ABNF rules for the structure of each part
   of a message (the syntax) and describes the relationship between
   those parts and their meaning in the context of a message (the
   semantics).  That is, it describes the actual rules for the structure
   of each part of a message (the syntax) as well as a description of
   the parts and instructions on how they ought to be interpreted (the
   semantics).  This includes analysis of the syntax and semantics of



Resnick                     Standards Track                     [Page 4]

RFC 2822                Internet Message Format               April 2001


   subparts of messages that have specific structure.  The syntax
   included in section 3 represents messages as they MUST be created.
   There are also notes in section 3 to indicate if any of the options
   specified in the syntax SHOULD be used over any of the others.

   Both sections 2 and 3 describe messages that are legal to generate
   for purposes of this standard.

   Section 4 of this document specifies an "obsolete" syntax.  There are
   references in section 3 to these obsolete syntactic elements.  The
   rules of the obsolete syntax are elements that have appeared in
   earlier revisions of this standard or have previously been widely
   used in Internet messages.  As such, these elements MUST be
   interpreted by parsers of messages in order to be conformant to this
   standard.  However, since items in this syntax have been determined
   to be non-interoperable or to cause significant problems for
   recipients of messages, they MUST NOT be generated by creators of
   conformant messages.

   Section 5 details security considerations to take into account when
   implementing this standard.

   Section 6 is a bibliography of references in this document.

   Section 7 contains the editor's address.

   Section 8 contains acknowledgements.

   Appendix A lists examples of different sorts of messages.  These
   examples are not exhaustive of the types of messages that appear on
   the Internet, but give a broad overview of certain syntactic forms.

   Appendix B lists the differences between this standard and earlier
   standards for Internet messages.

   Appendix C has copyright and intellectual property notices.

2. Lexical Analysis of Messages

2.1. General Description

   At the most basic level, a message is a series of characters.  A
   message that is conformant with this standard is comprised of
   characters with values in the range 1 through 127 and interpreted as
   US-ASCII characters [ASCII].  For brevity, this document sometimes
   refers to this range of characters as simply "US-ASCII characters".





Resnick                     Standards Track                     [Page 5]

RFC 2822                Internet Message Format               April 2001


   Note: This standard specifies that messages are made up of characters
   in the US-ASCII range of 1 through 127.  There are other documents,
   specifically the MIME document series [RFC2045, RFC2046, RFC2047,
   RFC2048, RFC2049], that extend this standard to allow for values
   outside of that range.  Discussion of those mechanisms is not within
   the scope of this standard.

   Messages are divided into lines of characters.  A line is a series of
   characters that is delimited with the two characters carriage-return
   and line-feed; that is, the carriage return (CR) character (ASCII
   value 13) followed immediately by the line feed (LF) character (ASCII
   value 10).  (The carriage-return/line-feed pair is usually written in
   this document as "CRLF".)

   A message consists of header fields (collectively called "the header
   of the message") followed, optionally, by a body.  The header is a
   sequence of lines of characters with special syntax as defined in
   this standard. The body is simply a sequence of characters that
   follows the header and is separated from the header by an empty line
   (i.e., a line with nothing preceding the CRLF).

2.1.1. Line Length Limits

   There are two limits that this standard places on the number of
   characters in a line. Each line of characters MUST be no more than
   998 characters, and SHOULD be no more than 78 characters, excluding
   the CRLF.

   The 998 character limit is due to limitations in many implementations
   which send, receive, or store Internet Message Format messages that
   simply cannot handle more than 998 characters on a line. Receiving
   implementations would do well to handle an arbitrarily large number
   of characters in a line for robustness sake. However, there are so
   many implementations which (in compliance with the transport
   requirements of [RFC2821]) do not accept messages containing more
   than 1000 character including the CR and LF per line, it is important
   for implementations not to create such messages.

   The more conservative 78 character recommendation is to accommodate
   the many implementations of user interfaces that display these
   messages which may truncate, or disastrously wrap, the display of
   more than 78 characters per line, in spite of the fact that such
   implementations are non-conformant to the intent of this
   specification (and that of [RFC2821] if they actually cause
   information to be lost). Again, even though this limitation is put on
   messages, it is encumbant upon implementations which display messages





Resnick                     Standards Track                     [Page 6]

RFC 2822                Internet Message Format               April 2001


   to handle an arbitrarily large number of characters in a line
   (certainly at least up to the 998 character limit) for the sake of
   robustness.

2.2. Header Fields

   Header fields are lines composed of a field name, followed by a colon
   (":"), followed by a field body, and terminated by CRLF.  A field
   name MUST be composed of printable US-ASCII characters (i.e.,
   characters that have values between 33 and 126, inclusive), except
   colon.  A field body may be composed of any US-ASCII characters,
   except for CR and LF.  However, a field body may contain CRLF when
   used in header "folding" and  "unfolding" as described in section
   2.2.3.  All field bodies MUST conform to the syntax described in
   sections 3 and 4 of this standard.

2.2.1. Unstructured Header Field Bodies

   Some field bodies in this standard are defined simply as
   "unstructured" (which is specified below as any US-ASCII characters,
   except for CR and LF) with no further restrictions.  These are
   referred to as unstructured field bodies.  Semantically, unstructured
   field bodies are simply to be treated as a single line of characters
   with no further processing (except for header "folding" and
   "unfolding" as described in section 2.2.3).

2.2.2. Structured Header Field Bodies

   Some field bodies in this standard have specific syntactical
   structure more restrictive than the unstructured field bodies
   described above. These are referred to as "structured" field bodies.
   Structured field bodies are sequences of specific lexical tokens as
   described in sections 3 and 4 of this standard.  Many of these tokens
   are allowed (according to their syntax) to be introduced or end with
   comments (as described in section 3.2.3) as well as the space (SP,
   ASCII value 32) and horizontal tab (HTAB, ASCII value 9) characters
   (together known as the white space characters, WSP), and those WSP
   characters are subject to header "folding" and "unfolding" as
   described in section 2.2.3.  Semantic analysis of structured field
   bodies is given along with their syntax.

2.2.3. Long Header Fields

   Each header field is logically a single line of characters comprising
   the field name, the colon, and the field body.  For convenience
   however, and to deal with the 998/78 character limitations per line,
   the field body portion of a header field can be split into a multiple
   line representation; this is called "folding".  The general rule is



Resnick                     Standards Track                     [Page 7]

RFC 2822                Internet Message Format               April 2001


   that wherever this standard allows for folding white space (not
   simply WSP characters), a CRLF may be inserted before any WSP.  For
   example, the header field:

           Subject: This is a test

   can be represented as:

           Subject: This
            is a test

   Note: Though structured field bodies are defined in such a way that
   folding can take place between many of the lexical tokens (and even
   within some of the lexical tokens), folding SHOULD be limited to
   placing the CRLF at higher-level syntactic breaks.  For instance, if
   a field body is defined as comma-separated values, it is recommended
   that folding occur after the comma separating the structured items in
   preference to other places where the field could be folded, even if
   it is allowed elsewhere.

   The process of moving from this folded multiple-line representation
   of a header field to its single line representation is called
   "unfolding". Unfolding is accomplished by simply removing any CRLF
   that is immediately followed by WSP.  Each header field should be
   treated in its unfolded form for further syntactic and semantic
   evaluation.

2.3. Body

   The body of a message is simply lines of US-ASCII characters.  The
   only two limitations on the body are as follows:

   - CR and LF MUST only occur together as CRLF; they MUST NOT appear
     independently in the body.

   - Lines of characters in the body MUST be limited to 998 characters,
     and SHOULD be limited to 78 characters, excluding the CRLF.

   Note: As was stated earlier, there are other standards documents,
   specifically the MIME documents [RFC2045, RFC2046, RFC2048, RFC2049]
   that extend this standard to allow for different sorts of message
   bodies.  Again, these mechanisms are beyond the scope of this
   document.








Resnick                     Standards Track                     [Page 8]

RFC 2822                Internet Message Format               April 2001


3. Syntax

3.1. Introduction

   The syntax as given in this section defines the legal syntax of
   Internet messages.  Messages that are conformant to this standard
   MUST conform to the syntax in this section.  If there are options in
   this section where one option SHOULD be generated, that is indicated
   either in the prose or in a comment next to the syntax.

   For the defined expressions, a short description of the syntax and
   use is given, followed by the syntax in ABNF, followed by a semantic
   analysis.  Primitive tokens that are used but otherwise unspecified
   come from [RFC2234].

   In some of the definitions, there will be nonterminals whose names
   start with "obs-".  These "obs-" elements refer to tokens defined in
   the obsolete syntax in section 4.  In all cases, these productions
   are to be ignored for the purposes of generating legal Internet
   messages and MUST NOT be used as part of such a message.  However,
   when interpreting messages, these tokens MUST be honored as part of
   the legal syntax.  In this sense, section 3 defines a grammar for
   generation of messages, with "obs-" elements that are to be ignored,
   while section 4 adds grammar for interpretation of messages.

3.2. Lexical Tokens

   The following rules are used to define an underlying lexical
   analyzer, which feeds tokens to the higher-level parsers.  This
   section defines the tokens used in structured header field bodies.

   Note: Readers of this standard need to pay special attention to how
   these lexical tokens are used in both the lower-level and
   higher-level syntax later in the document.  Particularly, the white
   space tokens and the comment tokens defined in section 3.2.3 get used
   in the lower-level tokens defined here, and those lower-level tokens
   are in turn used as parts of the higher-level tokens defined later.
   Therefore, the white space and comments may be allowed in the
   higher-level tokens even though they may not explicitly appear in a
   particular definition.

3.2.1. Primitive Tokens

   The following are primitive tokens referred to elsewhere in this
   standard, but not otherwise defined in [RFC2234].  Some of them will
   not appear anywhere else in the syntax, but they are convenient to
   refer to in other parts of this document.




Resnick                     Standards Track                     [Page 9]

RFC 2822                Internet Message Format               April 2001


   Note: The "specials" below are just such an example.  Though the
   specials token does not appear anywhere else in this standard, it is
   useful for implementers who use tools that lexically analyze
   messages.  Each of the characters in specials can be used to indicate
   a tokenization point in lexical analysis.

NO-WS-CTL       =       %d1-8 /         ; US-ASCII control characters
                        %d11 /          ;  that do not include the
                        %d12 /          ;  carriage return, line feed,
                        %d14-31 /       ;  and white space characters
                        %d127

text            =       %d1-9 /         ; Characters excluding CR and LF
                        %d11 /
                        %d12 /
                        %d14-127 /
                        obs-text

specials        =       "(" / ")" /     ; Special characters used in
                        "<" / ">" /     ;  other parts of the syntax
                        "[" / "]" /
                        ":" / ";" /
                        "@" / "\" /
                        "," / "." /
                        DQUOTE

   No special semantics are attached to these tokens.  They are simply
   single characters.

3.2.2. Quoted characters

   Some characters are reserved for special interpretation, such as
   delimiting lexical tokens.  To permit use of these characters as
   uninterpreted data, a quoting mechanism is provided.

quoted-pair     =       ("\" text) / obs-qp

   Where any quoted-pair appears, it is to be interpreted as the text
   character alone.  That is to say, the "\" character that appears as
   part of a quoted-pair is semantically "invisible".

   Note: The "\" character may appear in a message where it is not part
   of a quoted-pair.  A "\" character that does not appear in a
   quoted-pair is not semantically invisible.  The only places in this
   standard where quoted-pair currently appears are ccontent, qcontent,
   dcontent, no-fold-quote, and no-fold-literal.





Resnick                     Standards Track                    [Page 10]

RFC 2822                Internet Message Format               April 2001


3.2.3. Folding white space and comments

   White space characters, including white space used in folding
   (described in section 2.2.3), may appear between many elements in
   header field bodies.  Also, strings of characters that are treated as
   comments may be included in structured field bodies as characters
   enclosed in parentheses.  The following defines the folding white
   space (FWS) and comment constructs.

   Strings of characters enclosed in parentheses are considered comments
   so long as they do not appear within a "quoted-string", as defined in
   section 3.2.5.  Comments may nest.

   There are several places in this standard where comments and FWS may
   be freely inserted.  To accommodate that syntax, an additional token
   for "CFWS" is defined for places where comments and/or FWS can occur.
   However, where CFWS occurs in this standard, it MUST NOT be inserted
   in such a way that any line of a folded header field is made up
   entirely of WSP characters and nothing else.

FWS             =       ([*WSP CRLF] 1*WSP) /   ; Folding white space
                        obs-FWS

ctext           =       NO-WS-CTL /     ; Non white space controls

                        %d33-39 /       ; The rest of the US-ASCII
                        %d42-91 /       ;  characters not including "(",
                        %d93-126        ;  ")", or "\"

ccontent        =       ctext / quoted-pair / comment

comment         =       "(" *([FWS] ccontent) [FWS] ")"

CFWS            =       *([FWS] comment) (([FWS] comment) / FWS)

   Throughout this standard, where FWS (the folding white space token)
   appears, it indicates a place where header folding, as discussed in
   section 2.2.3, may take place.  Wherever header folding appears in a
   message (that is, a header field body containing a CRLF followed by
   any WSP), header unfolding (removal of the CRLF) is performed before
   any further lexical analysis is performed on that header field
   according to this standard.  That is to say, any CRLF that appears in
   FWS is semantically "invisible."

   A comment is normally used in a structured field body to provide some
   human readable informational text.  Since a comment is allowed to
   contain FWS, folding is permitted within the comment.  Also note that
   since quoted-pair is allowed in a comment, the parentheses and



Resnick                     Standards Track                    [Page 11]

RFC 2822                Internet Message Format               April 2001


   backslash characters may appear in a comment so long as they appear
   as a quoted-pair.  Semantically, the enclosing parentheses are not
   part of the comment; the comment is what is contained between the two
   parentheses.  As stated earlier, the "\" in any quoted-pair and the
   CRLF in any FWS that appears within the comment are semantically
   "invisible" and therefore not part of the comment either.

   Runs of FWS, comment or CFWS that occur between lexical tokens in a
   structured field header are semantically interpreted as a single
   space character.

3.2.4. Atom

   Several productions in structured header field bodies are simply
   strings of certain basic characters.  Such productions are called
   atoms.

   Some of the structured header field bodies also allow the period
   character (".", ASCII value 46) within runs of atext.  An additional
   "dot-atom" token is defined for those purposes.

atext           =       ALPHA / DIGIT / ; Any character except controls,
                        "!" / "#" /     ;  SP, and specials.
                        "$" / "%" /     ;  Used for atoms
                        "&" / "'" /
                        "*" / "+" /
                        "-" / "/" /
                        "=" / "?" /
                        "^" / "_" /
                        "`" / "{" /
                        "|" / "}" /
                        "~"

atom            =       [CFWS] 1*atext [CFWS]

dot-atom        =       [CFWS] dot-atom-text [CFWS]

dot-atom-text   =       1*atext *("." 1*atext)

   Both atom and dot-atom are interpreted as a single unit, comprised of
   the string of characters that make it up.  Semantically, the optional
   comments and FWS surrounding the rest of the characters are not part
   of the atom; the atom is only the run of atext characters in an atom,
   or the atext and "." characters in a dot-atom.







Resnick                     Standards Track                    [Page 12]

RFC 2822                Internet Message Format               April 2001


3.2.5. Quoted strings

   Strings of characters that include characters other than those
   allowed in atoms may be represented in a quoted string format, where
   the characters are surrounded by quote (DQUOTE, ASCII value 34)
   characters.

qtext           =       NO-WS-CTL /     ; Non white space controls

                        %d33 /          ; The rest of the US-ASCII
                        %d35-91 /       ;  characters not including "\"
                        %d93-126        ;  or the quote character

qcontent        =       qtext / quoted-pair

quoted-string   =       [CFWS]
                        DQUOTE *([FWS] qcontent) [FWS] DQUOTE
                        [CFWS]

   A quoted-string is treated as a unit.  That is, quoted-string is
   identical to atom, semantically.  Since a quoted-string is allowed to
   contain FWS, folding is permitted.  Also note that since quoted-pair
   is allowed in a quoted-string, the quote and backslash characters may
   appear in a quoted-string so long as they appear as a quoted-pair.

   Semantically, neither the optional CFWS outside of the quote
   characters nor the quote characters themselves are part of the
   quoted-string; the quoted-string is what is contained between the two
   quote characters.  As stated earlier, the "\" in any quoted-pair and
   the CRLF in any FWS/CFWS that appears within the quoted-string are
   semantically "invisible" and therefore not part of the quoted-string
   either.

3.2.6. Miscellaneous tokens

   Three additional tokens are defined, word and phrase for combinations
   of atoms and/or quoted-strings, and unstructured for use in
   unstructured header fields and in some places within structured
   header fields.

word            =       atom / quoted-string

phrase          =       1*word / obs-phrase








Resnick                     Standards Track                    [Page 13]

RFC 2822                Internet Message Format               April 2001


utext           =       NO-WS-CTL /     ; Non white space controls
                        %d33-126 /      ; The rest of US-ASCII
                        obs-utext

unstructured    =       *([FWS] utext) [FWS]

3.3. Date and Time Specification

   Date and time occur in several header fields.  This section specifies
   the syntax for a full date and time specification.  Though folding
   white space is permitted throughout the date-time specification, it
   is RECOMMENDED that a single space be used in each place that FWS
   appears (whether it is required or optional); some older
   implementations may not interpret other occurrences of folding white
   space correctly.

date-time       =       [ day-of-week "," ] date FWS time [CFWS]

day-of-week     =       ([FWS] day-name) / obs-day-of-week

day-name        =       "Mon" / "Tue" / "Wed" / "Thu" /
                        "Fri" / "Sat" / "Sun"

date            =       day month year

year            =       4*DIGIT / obs-year

month           =       (FWS month-name FWS) / obs-month

month-name      =       "Jan" / "Feb" / "Mar" / "Apr" /
                        "May" / "Jun" / "Jul" / "Aug" /
                        "Sep" / "Oct" / "Nov" / "Dec"

day             =       ([FWS] 1*2DIGIT) / obs-day

time            =       time-of-day FWS zone

time-of-day     =       hour ":" minute [ ":" second ]

hour            =       2DIGIT / obs-hour

minute          =       2DIGIT / obs-minute

second          =       2DIGIT / obs-second

zone            =       (( "+" / "-" ) 4DIGIT) / obs-zone





Resnick                     Standards Track                    [Page 14]

RFC 2822                Internet Message Format               April 2001


   The day is the numeric day of the month.  The year is any numeric
   year 1900 or later.

   The time-of-day specifies the number of hours, minutes, and
   optionally seconds since midnight of the date indicated.

   The date and time-of-day SHOULD express local time.

   The zone specifies the offset from Coordinated Universal Time (UTC,
   formerly referred to as "Greenwich Mean Time") that the date and
   time-of-day represent.  The "+" or "-" indicates whether the
   time-of-day is ahead of (i.e., east of) or behind (i.e., west of)
   Universal Time.  The first two digits indicate the number of hours
   difference from Universal Time, and the last two digits indicate the
   number of minutes difference from Universal Time.  (Hence, +hhmm
   means +(hh * 60 + mm) minutes, and -hhmm means -(hh * 60 + mm)
   minutes).  The form "+0000" SHOULD be used to indicate a time zone at
   Universal Time.  Though "-0000" also indicates Universal Time, it is
   used to indicate that the time was generated on a system that may be
   in a local time zone other than Universal Time and therefore
   indicates that the date-time contains no information about the local
   time zone.

   A date-time specification MUST be semantically valid.  That is, the
   day-of-the-week (if included) MUST be the day implied by the date,
   the numeric day-of-month MUST be between 1 and the number of days
   allowed for the specified month (in the specified year), the
   time-of-day MUST be in the range 00:00:00 through 23:59:60 (the
   number of seconds allowing for a leap second; see [STD12]), and the
   zone MUST be within the range -9959 through +9959.

3.4. Address Specification

   Addresses occur in several message header fields to indicate senders
   and recipients of messages.  An address may either be an individual
   mailbox, or a group of mailboxes.

address         =       mailbox / group

mailbox         =       name-addr / addr-spec

name-addr       =       [display-name] angle-addr

angle-addr      =       [CFWS] "<" addr-spec ">" [CFWS] / obs-angle-addr

group           =       display-name ":" [mailbox-list / CFWS] ";"
                        [CFWS]




Resnick                     Standards Track                    [Page 15]

RFC 2822                Internet Message Format               April 2001


display-name    =       phrase

mailbox-list    =       (mailbox *("," mailbox)) / obs-mbox-list

address-list    =       (address *("," address)) / obs-addr-list

   A mailbox receives mail.  It is a conceptual entity which does not
   necessarily pertain to file storage.  For example, some sites may
   choose to print mail on a printer and deliver the output to the
   addressee's desk.  Normally, a mailbox is comprised of two parts: (1)
   an optional display name that indicates the name of the recipient
   (which could be a person or a system) that could be displayed to the
   user of a mail application, and (2) an addr-spec address enclosed in
   angle brackets ("<" and ">").  There is also an alternate simple form
   of a mailbox where the addr-spec address appears alone, without the
   recipient's name or the angle brackets.  The Internet addr-spec
   address is described in section 3.4.1.

   Note: Some legacy implementations used the simple form where the
   addr-spec appears without the angle brackets, but included the name
   of the recipient in parentheses as a comment following the addr-spec.
   Since the meaning of the information in a comment is unspecified,
   implementations SHOULD use the full name-addr form of the mailbox,
   instead of the legacy form, to specify the display name associated
   with a mailbox.  Also, because some legacy implementations interpret
   the comment, comments generally SHOULD NOT be used in address fields
   to avoid confusing such implementations.

   When it is desirable to treat several mailboxes as a single unit
   (i.e., in a distribution list), the group construct can be used.  The
   group construct allows the sender to indicate a named group of
   recipients. This is done by giving a display name for the group,
   followed by a colon, followed by a comma separated list of any number
   of mailboxes (including zero and one), and ending with a semicolon.
   Because the list of mailboxes can be empty, using the group construct
   is also a simple way to communicate to recipients that the message
   was sent to one or more named sets of recipients, without actually
   providing the individual mailbox address for each of those
   recipients.

3.4.1. Addr-spec specification

   An addr-spec is a specific Internet identifier that contains a
   locally interpreted string followed by the at-sign character ("@",
   ASCII value 64) followed by an Internet domain.  The locally
   interpreted string is either a quoted-string or a dot-atom.  If the
   string can be represented as a dot-atom (that is, it contains no
   characters other than atext characters or "." surrounded by atext



Resnick                     Standards Track                    [Page 16]

RFC 2822                Internet Message Format               April 2001


   characters), then the dot-atom form SHOULD be used and the
   quoted-string form SHOULD NOT be used. Comments and folding white
   space SHOULD NOT be used around the "@" in the addr-spec.

addr-spec       =       local-part "@" domain

local-part      =       dot-atom / quoted-string / obs-local-part

domain          =       dot-atom / domain-literal / obs-domain

domain-literal  =       [CFWS] "[" *([FWS] dcontent) [FWS] "]" [CFWS]

dcontent        =       dtext / quoted-pair

dtext           =       NO-WS-CTL /     ; Non white space controls

                        %d33-90 /       ; The rest of the US-ASCII
                        %d94-126        ;  characters not including "[",
                                        ;  "]", or "\"

   The domain portion identifies the point to which the mail is
   delivered. In the dot-atom form, this is interpreted as an Internet
   domain name (either a host name or a mail exchanger name) as
   described in [STD3, STD13, STD14].  In the domain-literal form, the
   domain is interpreted as the literal Internet address of the
   particular host.  In both cases, how addressing is used and how
   messages are transported to a particular host is covered in the mail
   transport document [RFC2821].  These mechanisms are outside of the
   scope of this document.

   The local-part portion is a domain dependent string.  In addresses,
   it is simply interpreted on the particular host as a name of a
   particular mailbox.

3.5 Overall message syntax

   A message consists of header fields, optionally followed by a message
   body.  Lines in a message MUST be a maximum of 998 characters
   excluding the CRLF, but it is RECOMMENDED that lines be limited to 78
   characters excluding the CRLF.  (See section 2.1.1 for explanation.)
   In a message body, though all of the characters listed in the text
   rule MAY be used, the use of US-ASCII control characters (values 1
   through 8, 11, 12, and 14 through 31) is discouraged since their
   interpretation by receivers for display is not guaranteed.







Resnick                     Standards Track                    [Page 17]

RFC 2822                Internet Message Format               April 2001


message         =       (fields / obs-fields)
                        [CRLF body]

body            =       *(*998text CRLF) *998text

   The header fields carry most of the semantic information and are
   defined in section 3.6.  The body is simply a series of lines of text
   which are uninterpreted for the purposes of this standard.

3.6. Field definitions

   The header fields of a message are defined here.  All header fields
   have the same general syntactic structure: A field name, followed by
   a colon, followed by the field body.  The specific syntax for each
   header field is defined in the subsequent sections.

   Note: In the ABNF syntax for each field in subsequent sections, each
   field name is followed by the required colon.  However, for brevity
   sometimes the colon is not referred to in the textual description of
   the syntax.  It is, nonetheless, required.

   It is important to note that the header fields are not guaranteed to
   be in a particular order.  They may appear in any order, and they
   have been known to be reordered occasionally when transported over
   the Internet.  However, for the purposes of this standard, header
   fields SHOULD NOT be reordered when a message is transported or
   transformed.  More importantly, the trace header fields and resent
   header fields MUST NOT be reordered, and SHOULD be kept in blocks
   prepended to the message.  See sections 3.6.6 and 3.6.7 for more
   information.

   The only required header fields are the origination date field and
   the originator address field(s).  All other header fields are
   syntactically optional.  More information is contained in the table
   following this definition.

fields          =       *(trace
                          *(resent-date /
                           resent-from /
                           resent-sender /
                           resent-to /
                           resent-cc /
                           resent-bcc /
                           resent-msg-id))
                        *(orig-date /
                        from /
                        sender /
                        reply-to /



Resnick                     Standards Track                    [Page 18]

RFC 2822                Internet Message Format               April 2001


                        to /
                        cc /
                        bcc /
                        message-id /
                        in-reply-to /
                        references /
                        subject /
                        comments /
                        keywords /
                        optional-field)

   The following table indicates limits on the number of times each
   field may occur in a message header as well as any special
   limitations on the use of those fields.  An asterisk next to a value
   in the minimum or maximum column indicates that a special restriction
   appears in the Notes column.

Field           Min number      Max number      Notes

trace           0               unlimited       Block prepended - see
                                                3.6.7

resent-date     0*              unlimited*      One per block, required
                                                if other resent fields
                                                present - see 3.6.6

resent-from     0               unlimited*      One per block - see
                                                3.6.6

resent-sender   0*              unlimited*      One per block, MUST
                                                occur with multi-address
                                                resent-from - see 3.6.6

resent-to       0               unlimited*      One per block - see
                                                3.6.6

resent-cc       0               unlimited*      One per block - see
                                                3.6.6

resent-bcc      0               unlimited*      One per block - see
                                                3.6.6

resent-msg-id   0               unlimited*      One per block - see
                                                3.6.6

orig-date       1               1

from            1               1               See sender and 3.6.2



Resnick                     Standards Track                    [Page 19]

RFC 2822                Internet Message Format               April 2001


sender          0*              1               MUST occur with multi-
                                                address from - see 3.6.2

reply-to        0               1

to              0               1

cc              0               1

bcc             0               1

message-id      0*              1               SHOULD be present - see
                                                3.6.4

in-reply-to     0*              1               SHOULD occur in some
                                                replies - see 3.6.4

references      0*              1               SHOULD occur in some
                                                replies - see 3.6.4

subject         0               1

comments        0               unlimited

keywords        0               unlimited

optional-field  0               unlimited

   The exact interpretation of each field is described in subsequent
   sections.

3.6.1. The origination date field

   The origination date field consists of the field name "Date" followed
   by a date-time specification.

orig-date       =       "Date:" date-time CRLF

   The origination date specifies the date and time at which the creator
   of the message indicated that the message was complete and ready to
   enter the mail delivery system.  For instance, this might be the time
   that a user pushes the "send" or "submit" button in an application
   program.  In any case, it is specifically not intended to convey the
   time that the message is actually transported, but rather the time at
   which the human or other creator of the message has put the message
   into its final form, ready for transport.  (For example, a portable
   computer user who is not connected to a network might queue a message




Resnick                     Standards Track                    [Page 20]

RFC 2822                Internet Message Format               April 2001


   for delivery.  The origination date is intended to contain the date
   and time that the user queued the message, not the time when the user
   connected to the network to send the message.)

3.6.2. Originator fields

   The originator fields of a message consist of the from field, the
   sender field (when applicable), and optionally the reply-to field.
   The from field consists of the field name "From" and a
   comma-separated list of one or more mailbox specifications.  If the
   from field contains more than one mailbox specification in the
   mailbox-list, then the sender field, containing the field name
   "Sender" and a single mailbox specification, MUST appear in the
   message.  In either case, an optional reply-to field MAY also be
   included, which contains the field name "Reply-To" and a
   comma-separated list of one or more addresses.

from            =       "From:" mailbox-list CRLF

sender          =       "Sender:" mailbox CRLF

reply-to        =       "Reply-To:" address-list CRLF

   The originator fields indicate the mailbox(es) of the source of the
   message.  The "From:" field specifies the author(s) of the message,
   that is, the mailbox(es) of the person(s) or system(s) responsible
   for the writing of the message.  The "Sender:" field specifies the
   mailbox of the agent responsible for the actual transmission of the
   message.  For example, if a secretary were to send a message for
   another person, the mailbox of the secretary would appear in the
   "Sender:" field and the mailbox of the actual author would appear in
   the "From:" field.  If the originator of the message can be indicated
   by a single mailbox and the author and transmitter are identical, the
   "Sender:" field SHOULD NOT be used.  Otherwise, both fields SHOULD
   appear.

   The originator fields also provide the information required when
   replying to a message.  When the "Reply-To:" field is present, it
   indicates the mailbox(es) to which the author of the message suggests
   that replies be sent.  In the absence of the "Reply-To:" field,
   replies SHOULD by default be sent to the mailbox(es) specified in the
   "From:" field unless otherwise specified by the person composing the
   reply.

   In all cases, the "From:" field SHOULD NOT contain any mailbox that
   does not belong to the author(s) of the message.  See also section
   3.6.3 for more information on forming the destination addresses for a
   reply.



Resnick                     Standards Track                    [Page 21]

RFC 2822                Internet Message Format               April 2001


3.6.3. Destination address fields

   The destination fields of a message consist of three possible fields,
   each of the same form: The field name, which is either "To", "Cc", or
   "Bcc", followed by a comma-separated list of one or more addresses
   (either mailbox or group syntax).

to              =       "To:" address-list CRLF

cc              =       "Cc:" address-list CRLF

bcc             =       "Bcc:" (address-list / [CFWS]) CRLF

   The destination fields specify the recipients of the message.  Each
   destination field may have one or more addresses, and each of the
   addresses indicate the intended recipients of the message.  The only
   difference between the three fields is how each is used.

   The "To:" field contains the address(es) of the primary recipient(s)
   of the message.

   The "Cc:" field (where the "Cc" means "Carbon Copy" in the sense of
   making a copy on a typewriter using carbon paper) contains the
   addresses of others who are to receive the message, though the
   content of the message may not be directed at them.

   The "Bcc:" field (where the "Bcc" means "Blind Carbon Copy") contains
   addresses of recipients of the message whose addresses are not to be
   revealed to other recipients of the message.  There are three ways in
   which the "Bcc:" field is used.  In the first case, when a message
   containing a "Bcc:" field is prepared to be sent, the "Bcc:" line is
   removed even though all of the recipients (including those specified
   in the "Bcc:" field) are sent a copy of the message.  In the second
   case, recipients specified in the "To:" and "Cc:" lines each are sent
   a copy of the message with the "Bcc:" line removed as above, but the
   recipients on the "Bcc:" line get a separate copy of the message
   containing a "Bcc:" line.  (When there are multiple recipient
   addresses in the "Bcc:" field, some implementations actually send a
   separate copy of the message to each recipient with a "Bcc:"
   containing only the address of that particular recipient.) Finally,
   since a "Bcc:" field may contain no addresses, a "Bcc:" field can be
   sent without any addresses indicating to the recipients that blind
   copies were sent to someone.  Which method to use with "Bcc:" fields
   is implementation dependent, but refer to the "Security
   Considerations" section of this document for a discussion of each.






Resnick                     Standards Track                    [Page 22]

RFC 2822                Internet Message Format               April 2001


   When a message is a reply to another message, the mailboxes of the
   authors of the original message (the mailboxes in the "From:" field)
   or mailboxes specified in the "Reply-To:" field (if it exists) MAY
   appear in the "To:" field of the reply since these would normally be
   the primary recipients of the reply.  If a reply is sent to a message
   that has destination fields, it is often desirable to send a copy of
   the reply to all of the recipients of the message, in addition to the
   author.  When such a reply is formed, addresses in the "To:" and
   "Cc:" fields of the original message MAY appear in the "Cc:" field of
   the reply, since these are normally secondary recipients of the
   reply.  If a "Bcc:" field is present in the original message,
   addresses in that field MAY appear in the "Bcc:" field of the reply,
   but SHOULD NOT appear in the "To:" or "Cc:" fields.

   Note: Some mail applications have automatic reply commands that
   include the destination addresses of the original message in the
   destination addresses of the reply.  How those reply commands behave
   is implementation dependent and is beyond the scope of this document.
   In particular, whether or not to include the original destination
   addresses when the original message had a "Reply-To:" field is not
   addressed here.

3.6.4. Identification fields

   Though optional, every message SHOULD have a "Message-ID:" field.
   Furthermore, reply messages SHOULD have "In-Reply-To:" and
   "References:" fields as appropriate, as described below.

   The "Message-ID:" field contains a single unique message identifier.
   The "References:" and "In-Reply-To:" field each contain one or more
   unique message identifiers, optionally separated by CFWS.

   The message identifier (msg-id) is similar in syntax to an angle-addr
   construct without the internal CFWS.

message-id      =       "Message-ID:" msg-id CRLF

in-reply-to     =       "In-Reply-To:" 1*msg-id CRLF

references      =       "References:" 1*msg-id CRLF

msg-id          =       [CFWS] "<" id-left "@" id-right ">" [CFWS]

id-left         =       dot-atom-text / no-fold-quote / obs-id-left

id-right        =       dot-atom-text / no-fold-literal / obs-id-right

no-fold-quote   =       DQUOTE *(qtext / quoted-pair) DQUOTE



Resnick                     Standards Track                    [Page 23]

RFC 2822                Internet Message Format               April 2001


no-fold-literal =       "[" *(dtext / quoted-pair) "]"

   The "Message-ID:" field provides a unique message identifier that
   refers to a particular version of a particular message.  The
   uniqueness of the message identifier is guaranteed by the host that
   generates it (see below).  This message identifier is intended to be
   machine readable and not necessarily meaningful to humans.  A message
   identifier pertains to exactly one instantiation of a particular
   message; subsequent revisions to the message each receive new message
   identifiers.

   Note: There are many instances when messages are "changed", but those
   changes do not constitute a new instantiation of that message, and
   therefore the message would not get a new message identifier.  For
   example, when messages are introduced into the transport system, they
   are often prepended with additional header fields such as trace
   fields (described in section 3.6.7) and resent fields (described in
   section 3.6.6).  The addition of such header fields does not change
   the identity of the message and therefore the original "Message-ID:"
   field is retained.  In all cases, it is the meaning that the sender
   of the message wishes to convey (i.e., whether this is the same
   message or a different message) that determines whether or not the
   "Message-ID:" field changes, not any particular syntactic difference
   that appears (or does not appear) in the message.

   The "In-Reply-To:" and "References:" fields are used when creating a
   reply to a message.  They hold the message identifier of the original
   message and the message identifiers of other messages (for example,
   in the case of a reply to a message which was itself a reply).  The
   "In-Reply-To:" field may be used to identify the message (or
   messages) to which the new message is a reply, while the
   "References:" field may be used to identify a "thread" of
   conversation.

   When creating a reply to a message, the "In-Reply-To:" and
   "References:" fields of the resultant message are constructed as
   follows:

   The "In-Reply-To:" field will contain the contents of the "Message-
   ID:" field of the message to which this one is a reply (the "parent
   message").  If there is more than one parent message, then the "In-
   Reply-To:" field will contain the contents of all of the parents'
   "Message-ID:" fields.  If there is no "Message-ID:" field in any of
   the parent messages, then the new message will have no "In-Reply-To:"
   field.






Resnick                     Standards Track                    [Page 24]

RFC 2822                Internet Message Format               April 2001


   The "References:" field will contain the contents of the parent's
   "References:" field (if any) followed by the contents of the parent's
   "Message-ID:" field (if any).  If the parent message does not contain
   a "References:" field but does have an "In-Reply-To:" field
   containing a single message identifier, then the "References:" field
   will contain the contents of the parent's "In-Reply-To:" field
   followed by the contents of the parent's "Message-ID:" field (if
   any).  If the parent has none of the "References:", "In-Reply-To:",
   or "Message-ID:" fields, then the new message will have no
   "References:" field.

   Note: Some implementations parse the "References:" field to display
   the "thread of the discussion".  These implementations assume that
   each new message is a reply to a single parent and hence that they
   can walk backwards through the "References:" field to find the parent
   of each message listed there.  Therefore, trying to form a
   "References:" field for a reply that has multiple parents is
   discouraged and how to do so is not defined in this document.

   The message identifier (msg-id) itself MUST be a globally unique
   identifier for a message.  The generator of the message identifier
   MUST guarantee that the msg-id is unique.  There are several
   algorithms that can be used to accomplish this.  Since the msg-id has
   a similar syntax to angle-addr (identical except that comments and
   folding white space are not allowed), a good method is to put the
   domain name (or a domain literal IP address) of the host on which the
   message identifier was created on the right hand side of the "@", and
   put a combination of the current absolute date and time along with
   some other currently unique (perhaps sequential) identifier available
   on the system (for example, a process id number) on the left hand
   side.  Using a date on the left hand side and a domain name or domain
   literal on the right hand side makes it possible to guarantee
   uniqueness since no two hosts use the same domain name or IP address
   at the same time.  Though other algorithms will work, it is
   RECOMMENDED that the right hand side contain some domain identifier
   (either of the host itself or otherwise) such that the generator of
   the message identifier can guarantee the uniqueness of the left hand
   side within the scope of that domain.

   Semantically, the angle bracket characters are not part of the
   msg-id; the msg-id is what is contained between the two angle bracket
   characters.









Resnick                     Standards Track                    [Page 25]

RFC 2822                Internet Message Format               April 2001


3.6.5. Informational fields

   The informational fields are all optional.  The "Keywords:" field
   contains a comma-separated list of one or more words or
   quoted-strings. The "Subject:" and "Comments:" fields are
   unstructured fields as defined in section 2.2.1, and therefore may
   contain text or folding white space.

subject         =       "Subject:" unstructured CRLF

comments        =       "Comments:" unstructured CRLF

keywords        =       "Keywords:" phrase *("," phrase) CRLF

   These three fields are intended to have only human-readable content
   with information about the message.  The "Subject:" field is the most
   common and contains a short string identifying the topic of the
   message.  When used in a reply, the field body MAY start with the
   string "Re: " (from the Latin "res", in the matter of) followed by
   the contents of the "Subject:" field body of the original message.
   If this is done, only one instance of the literal string "Re: " ought
   to be used since use of other strings or more than one instance can
   lead to undesirable consequences.  The "Comments:" field contains any
   additional comments on the text of the body of the message.  The
   "Keywords:" field contains a comma-separated list of important words
   and phrases that might be useful for the recipient.

3.6.6. Resent fields

   Resent fields SHOULD be added to any message that is reintroduced by
   a user into the transport system.  A separate set of resent fields
   SHOULD be added each time this is done.  All of the resent fields
   corresponding to a particular resending of the message SHOULD be
   together.  Each new set of resent fields is prepended to the message;
   that is, the most recent set of resent fields appear earlier in the
   message.  No other fields in the message are changed when resent
   fields are added.

   Each of the resent fields corresponds to a particular field elsewhere
   in the syntax.  For instance, the "Resent-Date:" field corresponds to
   the "Date:" field and the "Resent-To:" field corresponds to the "To:"
   field.  In each case, the syntax for the field body is identical to
   the syntax given previously for the corresponding field.

   When resent fields are used, the "Resent-From:" and "Resent-Date:"
   fields MUST be sent.  The "Resent-Message-ID:" field SHOULD be sent.
   "Resent-Sender:" SHOULD NOT be used if "Resent-Sender:" would be
   identical to "Resent-From:".



Resnick                     Standards Track                    [Page 26]

RFC 2822                Internet Message Format               April 2001


resent-date     =       "Resent-Date:" date-time CRLF

resent-from     =       "Resent-From:" mailbox-list CRLF

resent-sender   =       "Resent-Sender:" mailbox CRLF

resent-to       =       "Resent-To:" address-list CRLF

resent-cc       =       "Resent-Cc:" address-list CRLF

resent-bcc      =       "Resent-Bcc:" (address-list / [CFWS]) CRLF

resent-msg-id   =       "Resent-Message-ID:" msg-id CRLF

   Resent fields are used to identify a message as having been
   reintroduced into the transport system by a user.  The purpose of
   using resent fields is to have the message appear to the final
   recipient as if it were sent directly by the original sender, with
   all of the original fields remaining the same.  Each set of resent
   fields correspond to a particular resending event.  That is, if a
   message is resent multiple times, each set of resent fields gives
   identifying information for each individual time.  Resent fields are
   strictly informational.  They MUST NOT be used in the normal
   processing of replies or other such automatic actions on messages.

   Note: Reintroducing a message into the transport system and using
   resent fields is a different operation from "forwarding".
   "Forwarding" has two meanings: One sense of forwarding is that a mail
   reading program can be told by a user to forward a copy of a message
   to another person, making the forwarded message the body of the new
   message.  A forwarded message in this sense does not appear to have
   come from the original sender, but is an entirely new message from
   the forwarder of the message.  On the other hand, forwarding is also
   used to mean when a mail transport program gets a message and
   forwards it on to a different destination for final delivery.  Resent
   header fields are not intended for use with either type of
   forwarding.

   The resent originator fields indicate the mailbox of the person(s) or
   system(s) that resent the message.  As with the regular originator
   fields, there are two forms: a simple "Resent-From:" form which
   contains the mailbox of the individual doing the resending, and the
   more complex form, when one individual (identified in the
   "Resent-Sender:" field) resends a message on behalf of one or more
   others (identified in the "Resent-From:" field).

   Note: When replying to a resent message, replies behave just as they
   would with any other message, using the original "From:",



Resnick                     Standards Track                    [Page 27]

RFC 2822                Internet Message Format               April 2001


   "Reply-To:", "Message-ID:", and other fields.  The resent fields are
   only informational and MUST NOT be used in the normal processing of
   replies.

   The "Resent-Date:" indicates the date and time at which the resent
   message is dispatched by the resender of the message.  Like the
   "Date:" field, it is not the date and time that the message was
   actually transported.

   The "Resent-To:", "Resent-Cc:", and "Resent-Bcc:" fields function
   identically to the "To:", "Cc:", and "Bcc:" fields respectively,
   except that they indicate the recipients of the resent message, not
   the recipients of the original message.

   The "Resent-Message-ID:" field provides a unique identifier for the
   resent message.

3.6.7. Trace fields

   The trace fields are a group of header fields consisting of an
   optional "Return-Path:" field, and one or more "Received:" fields.
   The "Return-Path:" header field contains a pair of angle brackets
   that enclose an optional addr-spec.  The "Received:" field contains a
   (possibly empty) list of name/value pairs followed by a semicolon and
   a date-time specification.  The first item of the name/value pair is
   defined by item-name, and the second item is either an addr-spec, an
   atom, a domain, or a msg-id.  Further restrictions may be applied to
   the syntax of the trace fields by standards that provide for their
   use, such as [RFC2821].

trace           =       [return]
                        1*received

return          =       "Return-Path:" path CRLF

path            =       ([CFWS] "<" ([CFWS] / addr-spec) ">" [CFWS]) /
                        obs-path

received        =       "Received:" name-val-list ";" date-time CRLF

name-val-list   =       [CFWS] [name-val-pair *(CFWS name-val-pair)]

name-val-pair   =       item-name CFWS item-value

item-name       =       ALPHA *(["-"] (ALPHA / DIGIT))

item-value      =       1*angle-addr / addr-spec /
                         atom / domain / msg-id



Resnick                     Standards Track                    [Page 28]

RFC 2822                Internet Message Format               April 2001


   A full discussion of the Internet mail use of trace fields is
   contained in [RFC2821].  For the purposes of this standard, the trace
   fields are strictly informational, and any formal interpretation of
   them is outside of the scope of this document.

3.6.8. Optional fields

   Fields may appear in messages that are otherwise unspecified in this
   standard.  They MUST conform to the syntax of an optional-field.
   This is a field name, made up of the printable US-ASCII characters
   except SP and colon, followed by a colon, followed by any text which
   conforms to unstructured.

   The field names of any optional-field MUST NOT be identical to any
   field name specified elsewhere in this standard.

optional-field  =       field-name ":" unstructured CRLF

field-name      =       1*ftext

ftext           =       %d33-57 /               ; Any character except
                        %d59-126                ;  controls, SP, and
                                                ;  ":".

   For the purposes of this standard, any optional field is
   uninterpreted.

4. Obsolete Syntax

   Earlier versions of this standard allowed for different (usually more
   liberal) syntax than is allowed in this version.  Also, there have
   been syntactic elements used in messages on the Internet whose
   interpretation have never been documented.  Though some of these
   syntactic forms MUST NOT be generated according to the grammar in
   section 3, they MUST be accepted and parsed by a conformant receiver.
   This section documents many of these syntactic elements.  Taking the
   grammar in section 3 and adding the definitions presented in this
   section will result in the grammar to use for interpretation of
   messages.

   Note: This section identifies syntactic forms that any implementation
   MUST reasonably interpret.  However, there are certainly Internet
   messages which do not conform to even the additional syntax given in
   this section.  The fact that a particular form does not appear in any
   section of this document is not justification for computer programs
   to crash or for malformed data to be irretrievably lost by any
   implementation.  To repeat an example, though this document requires
   lines in messages to be no longer than 998 characters, silently



Resnick                     Standards Track                    [Page 29]

RFC 2822                Internet Message Format               April 2001


   discarding the 999th and subsequent characters in a line without
   warning would still be bad behavior for an implementation.  It is up
   to the implementation to deal with messages robustly.

   One important difference between the obsolete (interpreting) and the
   current (generating) syntax is that in structured header field bodies
   (i.e., between the colon and the CRLF of any structured header
   field), white space characters, including folding white space, and
   comments can be freely inserted between any syntactic tokens.  This
   allows many complex forms that have proven difficult for some
   implementations to parse.

   Another key difference between the obsolete and the current syntax is
   that the rule in section 3.2.3 regarding lines composed entirely of
   white space in comments and folding white space does not apply.  See
   the discussion of folding white space in section 4.2 below.

   Finally, certain characters that were formerly allowed in messages
   appear in this section.  The NUL character (ASCII value 0) was once
   allowed, but is no longer for compatibility reasons.  CR and LF were
   allowed to appear in messages other than as CRLF; this use is also
   shown here.

   Other differences in syntax and semantics are noted in the following
   sections.

4.1. Miscellaneous obsolete tokens

   These syntactic elements are used elsewhere in the obsolete syntax or
   in the main syntax.  The obs-char and obs-qp elements each add ASCII
   value 0. Bare CR and bare LF are added to obs-text and obs-utext.
   The period character is added to obs-phrase. The obs-phrase-list
   provides for "empty" elements in a comma-separated list of phrases.

   Note: The "period" (or "full stop") character (".") in obs-phrase is
   not a form that was allowed in earlier versions of this or any other
   standard.  Period (nor any other character from specials) was not
   allowed in phrase because it introduced a parsing difficulty
   distinguishing between phrases and portions of an addr-spec (see
   section 4.4).  It appears here because the period character is
   currently used in many messages in the display-name portion of
   addresses, especially for initials in names, and therefore must be
   interpreted properly.  In the future, period may appear in the
   regular syntax of phrase.

obs-qp          =       "\" (%d0-127)

obs-text        =       *LF *CR *(obs-char *LF *CR)



Resnick                     Standards Track                    [Page 30]

RFC 2822                Internet Message Format               April 2001


obs-char        =       %d0-9 / %d11 /          ; %d0-127 except CR and
                        %d12 / %d14-127         ;  LF

obs-utext       =       obs-text

obs-phrase      =       word *(word / "." / CFWS)

obs-phrase-list =       phrase / 1*([phrase] [CFWS] "," [CFWS]) [phrase]

   Bare CR and bare LF appear in messages with two different meanings.
   In many cases, bare CR or bare LF are used improperly instead of CRLF
   to indicate line separators.  In other cases, bare CR and bare LF are
   used simply as ASCII control characters with their traditional ASCII
   meanings.

4.2. Obsolete folding white space

   In the obsolete syntax, any amount of folding white space MAY be
   inserted where the obs-FWS rule is allowed.  This creates the
   possibility of having two consecutive "folds" in a line, and
   therefore the possibility that a line which makes up a folded header
   field could be composed entirely of white space.

   obs-FWS         =       1*WSP *(CRLF 1*WSP)

4.3. Obsolete Date and Time

   The syntax for the obsolete date format allows a 2 digit year in the
   date field and allows for a list of alphabetic time zone
   specifications that were used in earlier versions of this standard.
   It also permits comments and folding white space between many of the
   tokens.

obs-day-of-week =       [CFWS] day-name [CFWS]

obs-year        =       [CFWS] 2*DIGIT [CFWS]

obs-month       =       CFWS month-name CFWS

obs-day         =       [CFWS] 1*2DIGIT [CFWS]

obs-hour        =       [CFWS] 2DIGIT [CFWS]

obs-minute      =       [CFWS] 2DIGIT [CFWS]

obs-second      =       [CFWS] 2DIGIT [CFWS]

obs-zone        =       "UT" / "GMT" /          ; Universal Time



Resnick                     Standards Track                    [Page 31]

RFC 2822                Internet Message Format               April 2001


                                                ; North American UT
                                                ; offsets
                        "EST" / "EDT" /         ; Eastern:  - 5/ - 4
                        "CST" / "CDT" /         ; Central:  - 6/ - 5
                        "MST" / "MDT" /         ; Mountain: - 7/ - 6
                        "PST" / "PDT" /         ; Pacific:  - 8/ - 7

                        %d65-73 /               ; Military zones - "A"
                        %d75-90 /               ; through "I" and "K"
                        %d97-105 /              ; through "Z", both
                        %d107-122               ; upper and lower case

   Where a two or three digit year occurs in a date, the year is to be
   interpreted as follows: If a two digit year is encountered whose
   value is between 00 and 49, the year is interpreted by adding 2000,
   ending up with a value between 2000 and 2049.  If a two digit year is
   encountered with a value between 50 and 99, or any three digit year
   is encountered, the year is interpreted by adding 1900.

   In the obsolete time zone, "UT" and "GMT" are indications of
   "Universal Time" and "Greenwich Mean Time" respectively and are both
   semantically identical to "+0000".

   The remaining three character zones are the US time zones.  The first
   letter, "E", "C", "M", or "P" stands for "Eastern", "Central",
   "Mountain" and "Pacific".  The second letter is either "S" for
   "Standard" time, or "D" for "Daylight" (or summer) time.  Their
   interpretations are as follows:

   EDT is semantically equivalent to -0400
   EST is semantically equivalent to -0500
   CDT is semantically equivalent to -0500
   CST is semantically equivalent to -0600
   MDT is semantically equivalent to -0600
   MST is semantically equivalent to -0700
   PDT is semantically equivalent to -0700
   PST is semantically equivalent to -0800

   The 1 character military time zones were defined in a non-standard
   way in [RFC822] and are therefore unpredictable in their meaning.
   The original definitions of the military zones "A" through "I" are
   equivalent to "+0100" through "+0900" respectively; "K", "L", and "M"
   are equivalent to  "+1000", "+1100", and "+1200" respectively; "N"
   through "Y" are equivalent to "-0100" through "-1200" respectively;
   and "Z" is equivalent to "+0000".  However, because of the error in
   [RFC822], they SHOULD all be considered equivalent to "-0000" unless
   there is out-of-band information confirming their meaning.




Resnick                     Standards Track                    [Page 32]

RFC 2822                Internet Message Format               April 2001


   Other multi-character (usually between 3 and 5) alphabetic time zones
   have been used in Internet messages.  Any such time zone whose
   meaning is not known SHOULD be considered equivalent to "-0000"
   unless there is out-of-band information confirming their meaning.

4.4. Obsolete Addressing

   There are three primary differences in addressing.  First, mailbox
   addresses were allowed to have a route portion before the addr-spec
   when enclosed in "<" and ">".  The route is simply a comma-separated
   list of domain names, each preceded by "@", and the list terminated
   by a colon.  Second, CFWS were allowed between the period-separated
   elements of local-part and domain (i.e., dot-atom was not used).  In
   addition, local-part is allowed to contain quoted-string in addition
   to just atom.  Finally, mailbox-list and address-list were allowed to
   have "null" members.  That is, there could be two or more commas in
   such a list with nothing in between them.

obs-angle-addr  =       [CFWS] "<" [obs-route] addr-spec ">" [CFWS]

obs-route       =       [CFWS] obs-domain-list ":" [CFWS]

obs-domain-list =       "@" domain *(*(CFWS / "," ) [CFWS] "@" domain)

obs-local-part  =       word *("." word)

obs-domain      =       atom *("." atom)

obs-mbox-list   =       1*([mailbox] [CFWS] "," [CFWS]) [mailbox]

obs-addr-list   =       1*([address] [CFWS] "," [CFWS]) [address]

   When interpreting addresses, the route portion SHOULD be ignored.

4.5. Obsolete header fields

   Syntactically, the primary difference in the obsolete field syntax is
   that it allows multiple occurrences of any of the fields and they may
   occur in any order.  Also, any amount of white space is allowed
   before the ":" at the end of the field name.

obs-fields      =       *(obs-return /
                        obs-received /
                        obs-orig-date /
                        obs-from /
                        obs-sender /
                        obs-reply-to /
                        obs-to /



Resnick                     Standards Track                    [Page 33]

RFC 2822                Internet Message Format               April 2001


                        obs-cc /
                        obs-bcc /
                        obs-message-id /
                        obs-in-reply-to /
                        obs-references /
                        obs-subject /
                        obs-comments /
                        obs-keywords /
                        obs-resent-date /
                        obs-resent-from /
                        obs-resent-send /
                        obs-resent-rply /
                        obs-resent-to /
                        obs-resent-cc /
                        obs-resent-bcc /
                        obs-resent-mid /
                        obs-optional)

   Except for destination address fields (described in section 4.5.3),
   the interpretation of multiple occurrences of fields is unspecified.
   Also, the interpretation of trace fields and resent fields which do
   not occur in blocks prepended to the message is unspecified as well.
   Unless otherwise noted in the following sections, interpretation of
   other fields is identical to the interpretation of their non-obsolete
   counterparts in section 3.

4.5.1. Obsolete origination date field

obs-orig-date   =       "Date" *WSP ":" date-time CRLF

4.5.2. Obsolete originator fields

obs-from        =       "From" *WSP ":" mailbox-list CRLF

obs-sender      =       "Sender" *WSP ":" mailbox CRLF

obs-reply-to    =       "Reply-To" *WSP ":" mailbox-list CRLF

4.5.3. Obsolete destination address fields

obs-to          =       "To" *WSP ":" address-list CRLF

obs-cc          =       "Cc" *WSP ":" address-list CRLF

obs-bcc         =       "Bcc" *WSP ":" (address-list / [CFWS]) CRLF






Resnick                     Standards Track                    [Page 34]

RFC 2822                Internet Message Format               April 2001


   When multiple occurrences of destination address fields occur in a
   message, they SHOULD be treated as if the address-list in the first
   occurrence of the field is combined with the address lists of the
   subsequent occurrences by adding a comma and concatenating.

4.5.4. Obsolete identification fields

   The obsolete "In-Reply-To:" and "References:" fields differ from the
   current syntax in that they allow phrase (words or quoted strings) to
   appear.  The obsolete forms of the left and right sides of msg-id
   allow interspersed CFWS, making them syntactically identical to
   local-part and domain respectively.

obs-message-id  =       "Message-ID" *WSP ":" msg-id CRLF

obs-in-reply-to =       "In-Reply-To" *WSP ":" *(phrase / msg-id) CRLF

obs-references  =       "References" *WSP ":" *(phrase / msg-id) CRLF

obs-id-left     =       local-part

obs-id-right    =       domain

   For purposes of interpretation, the phrases in the "In-Reply-To:" and
   "References:" fields are ignored.

   Semantically, none of the optional CFWS surrounding the local-part
   and the domain are part of the obs-id-left and obs-id-right
   respectively.

4.5.5. Obsolete informational fields

obs-subject     =       "Subject" *WSP ":" unstructured CRLF

obs-comments    =       "Comments" *WSP ":" unstructured CRLF

obs-keywords    =       "Keywords" *WSP ":" obs-phrase-list CRLF

4.5.6. Obsolete resent fields

   The obsolete syntax adds a "Resent-Reply-To:" field, which consists
   of the field name, the optional comments and folding white space, the
   colon, and a comma separated list of addresses.

obs-resent-from =       "Resent-From" *WSP ":" mailbox-list CRLF

obs-resent-send =       "Resent-Sender" *WSP ":" mailbox CRLF




Resnick                     Standards Track                    [Page 35]

RFC 2822                Internet Message Format               April 2001


obs-resent-date =       "Resent-Date" *WSP ":" date-time CRLF

obs-resent-to   =       "Resent-To" *WSP ":" address-list CRLF

obs-resent-cc   =       "Resent-Cc" *WSP ":" address-list CRLF

obs-resent-bcc  =       "Resent-Bcc" *WSP ":"
                         (address-list / [CFWS]) CRLF

obs-resent-mid  =       "Resent-Message-ID" *WSP ":" msg-id CRLF

obs-resent-rply =       "Resent-Reply-To" *WSP ":" address-list CRLF

   As with other resent fields, the "Resent-Reply-To:" field is to be
   treated as trace information only.

4.5.7. Obsolete trace fields

   The obs-return and obs-received are again given here as template
   definitions, just as return and received are in section 3.  Their
   full syntax is given in [RFC2821].

obs-return      =       "Return-Path" *WSP ":" path CRLF

obs-received    =       "Received" *WSP ":" name-val-list CRLF

obs-path        =       obs-angle-addr

4.5.8. Obsolete optional fields

obs-optional    =       field-name *WSP ":" unstructured CRLF

5. Security Considerations

   Care needs to be taken when displaying messages on a terminal or
   terminal emulator.  Powerful terminals may act on escape sequences
   and other combinations of ASCII control characters with a variety of
   consequences.  They can remap the keyboard or permit other
   modifications to the terminal which could lead to denial of service
   or even damaged data.  They can trigger (sometimes programmable)
   answerback messages which can allow a message to cause commands to be
   issued on the recipient's behalf.  They can also effect the operation
   of terminal attached devices such as printers.  Message viewers may
   wish to strip potentially dangerous terminal escape sequences from
   the message prior to display.  However, other escape sequences appear
   in messages for useful purposes (cf. [RFC2045, RFC2046, RFC2047,
   RFC2048, RFC2049, ISO2022]) and therefore should not be stripped
   indiscriminately.



Resnick                     Standards Track                    [Page 36]

RFC 2822                Internet Message Format               April 2001


   Transmission of non-text objects in messages raises additional
   security issues.  These issues are discussed in [RFC2045, RFC2046,
   RFC2047, RFC2048, RFC2049].

   Many implementations use the "Bcc:" (blind carbon copy) field
   described in section 3.6.3 to facilitate sending messages to
   recipients without revealing the addresses of one or more of the
   addressees to the other recipients.  Mishandling this use of "Bcc:"
   has implications for confidential information that might be revealed,
   which could eventually lead to security problems through knowledge of
   even the existence of a particular mail address.  For example, if
   using the first method described in section 3.6.3, where the "Bcc:"
   line is removed from the message, blind recipients have no explicit
   indication that they have been sent a blind copy, except insofar as
   their address does not appear in the message header.  Because of
   this, one of the blind addressees could potentially send a reply to
   all of the shown recipients and accidentally reveal that the message
   went to the blind recipient.  When the second method from section
   3.6.3 is used, the blind recipient's address appears in the "Bcc:"
   field of a separate copy of the message. If the "Bcc:" field sent
   contains all of the blind addressees, all of the "Bcc:" recipients
   will be seen by each "Bcc:" recipient.  Even if a separate message is
   sent to each "Bcc:" recipient with only the individual's address,
   implementations still need to be careful to process replies to the
   message as per section 3.6.3 so as not to accidentally reveal the
   blind recipient to other recipients.

6. Bibliography

   [ASCII]    American National Standards Institute (ANSI), Coded
              Character Set - 7-Bit American National Standard Code for
              Information Interchange, ANSI X3.4, 1986.

   [ISO2022] International Organization for Standardization (ISO),
              Information processing - ISO 7-bit and 8-bit coded
              character sets - Code extension techniques, Third edition
              - 1986-05-01, ISO 2022, 1986.

   [RFC822]   Crocker, D., "Standard for the Format of ARPA Internet
              Text Messages", RFC 822, August 1982.

   [RFC2045]  Freed, N. and  N. Borenstein, "Multipurpose Internet Mail
              Extensions (MIME) Part One: Format of Internet Message
              Bodies", RFC 2045, November 1996.

   [RFC2046]  Freed, N. and N. Borenstein, "Multipurpose Internet Mail
              Extensions (MIME) Part Two: Media Types", RFC 2046,
              November 1996.



Resnick                     Standards Track                    [Page 37]

RFC 2822                Internet Message Format               April 2001


   [RFC2047]  Moore, K., "Multipurpose Internet Mail Extensions (MIME)
              Part Three: Message Header Extensions for Non-ASCII Text",
              RFC 2047, November 1996.

   [RFC2048]  Freed, N., Klensin, J. and J. Postel, "Multipurpose
              Internet Mail Extensions (MIME) Part Four: Format of
              Internet Message Bodies", RFC 2048, November 1996.

   [RFC2049]  Freed, N. and N. Borenstein, "Multipurpose Internet Mail
              Extensions (MIME) Part Five: Conformance Criteria and
              Examples", RFC 2049, November 1996.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, March 1997.

   [RFC2234]  Crocker, D., Editor, and P. Overell, "Augmented BNF for
              Syntax Specifications: ABNF", RFC 2234, November 1997.

   [RFC2821]  Klensin, J., Editor, "Simple Mail Transfer Protocol", RFC
              2821, March 2001.

   [STD3]     Braden, R., "Host Requirements", STD 3, RFC 1122 and RFC
              1123, October 1989.

   [STD12]    Mills, D., "Network Time Protocol", STD 12, RFC 1119,
              September 1989.

   [STD13]    Mockapetris, P., "Domain Name System", STD 13, RFC 1034
              and RFC 1035,  November 1987.

   [STD14]    Partridge, C., "Mail Routing and the Domain System", STD
              14, RFC 974, January 1986.

7. Editor's Address

   Peter W. Resnick
   QUALCOMM Incorporated
   5775 Morehouse Drive
   San Diego, CA 92121-1714
   USA

   Phone: +1 858 651 4478
   Fax:   +1 858 651 1102
   EMail: presnick@qualcomm.com







Resnick                     Standards Track                    [Page 38]

RFC 2822                Internet Message Format               April 2001


8. Acknowledgements

   Many people contributed to this document.  They included folks who
   participated in the Detailed Revision and Update of Messaging
   Standards (DRUMS) Working Group of the Internet Engineering Task
   Force (IETF), the chair of DRUMS, the Area Directors of the IETF, and
   people who simply sent their comments in via e-mail.  The editor is
   deeply indebted to them all and thanks them sincerely.  The below
   list includes everyone who sent e-mail concerning this document.
   Hopefully, everyone who contributed is named here:

   Matti Aarnio              Barry Finkel           Larry Masinter
   Tanaka Akira              Erik Forsberg          Denis McKeon
   Russ Allbery              Chuck Foster           William P McQuillan
   Eric Allman               Paul Fox               Alexey Melnikov
   Harald Tveit Alvestrand   Klaus M. Frank         Perry E. Metzger
   Ran Atkinson              Ned Freed              Steven Miller
   Jos Backus                Jochen Friedrich       Keith Moore
   Bruce Balden              Randall C. Gellens     John Gardiner Myers
   Dave Barr                 Sukvinder Singh Gill   Chris Newman
   Alan Barrett              Tim Goodwin            John W. Noerenberg
   John Beck                 Philip Guenther        Eric Norman
   J. Robert von Behren      Tony Hansen            Mike O'Dell
   Jos den Bekker            John Hawkinson         Larry Osterman
   D. J. Bernstein           Philip Hazel           Paul Overell
   James Berriman            Kai Henningsen         Jacob Palme
   Norbert Bollow            Robert Herriot         Michael A. Patton
   Raj Bose                  Paul Hethmon           Uzi Paz
   Antony Bowesman           Jim Hill               Michael A. Quinlan
   Scott Bradner             Paul E. Hoffman        Eric S. Raymond
   Randy Bush                Steve Hole             Sam Roberts
   Tom Byrer                 Kari Hurtta            Hugh Sasse
   Bruce Campbell            Marco S. Hyman         Bart Schaefer
   Larry Campbell            Ofer Inbar             Tom Scola
   W. J. Carpenter           Olle Jarnefors         Wolfgang Segmuller
   Michael Chapman           Kevin Johnson          Nick Shelness
   Richard Clayton           Sudish Joseph          John Stanley
   Maurizio Codogno          Maynard Kang           Einar Stefferud
   Jim Conklin               Prabhat Keni           Jeff Stephenson
   R. Kelley Cook            John C. Klensin        Bernard Stern
   Steve Coya                Graham Klyne           Peter Sylvester
   Mark Crispin              Brad Knowles           Mark Symons
   Dave Crocker              Shuhei Kobayashi       Eric Thomas
   Matt Curtin               Peter Koch             Lee Thompson
   Michael D'Errico          Dan Kohn               Karel De Vriendt
   Cyrus Daboo               Christian Kuhtz        Matthew Wall
   Jutta Degener             Anand Kumria           Rolf Weber
   Mark Delany               Steen Larsen           Brent B. Welch



Resnick                     Standards Track                    [Page 39]

RFC 2822                Internet Message Format               April 2001


   Steve Dorner              Eliot Lear             Dan Wing
   Harold A. Driscoll        Barry Leiba            Jack De Winter
   Michael Elkins            Jay Levitt             Gregory J. Woodhouse
   Robert Elz                Lars-Johan Liman       Greg A. Woods
   Johnny Eriksson           Charles Lindsey        Kazu Yamamoto
   Erik E. Fair              Pete Loshin            Alain Zahm
   Roger Fajman              Simon Lyall            Jamie Zawinski
   Patrik Faltstrom          Bill Manning           Timothy S. Zurcher
   Claus Andre Farber        John Martin










































Resnick                     Standards Track                    [Page 40]

RFC 2822                Internet Message Format               April 2001


Appendix A. Example messages

   This section presents a selection of messages.  These are intended to
   assist in the implementation of this standard, but should not be
   taken as normative; that is to say, although the examples in this
   section were carefully reviewed, if there happens to be a conflict
   between these examples and the syntax described in sections 3 and 4
   of this document, the syntax in those sections is to be taken as
   correct.

   Messages are delimited in this section between lines of "----".  The
   "----" lines are not part of the message itself.

A.1. Addressing examples

   The following are examples of messages that might be sent between two
   individuals.

A.1.1. A message from one person to another with simple addressing

   This could be called a canonical message.  It has a single author,
   John Doe, a single recipient, Mary Smith, a subject, the date, a
   message identifier, and a textual message in the body.

----
From: John Doe <jdoe@machine.example>
To: Mary Smith <mary@example.net>
Subject: Saying Hello
Date: Fri, 21 Nov 1997 09:55:06 -0600
Message-ID: <1234@local.machine.example>

This is a message just to say hello.
So, "Hello".
----

















Resnick                     Standards Track                    [Page 41]

RFC 2822                Internet Message Format               April 2001


   If John's secretary Michael actually sent the message, though John
   was the author and replies to this message should go back to him, the
   sender field would be used:

----
From: John Doe <jdoe@machine.example>
Sender: Michael Jones <mjones@machine.example>
To: Mary Smith <mary@example.net>
Subject: Saying Hello
Date: Fri, 21 Nov 1997 09:55:06 -0600
Message-ID: <1234@local.machine.example>

This is a message just to say hello.
So, "Hello".
----

A.1.2. Different types of mailboxes

   This message includes multiple addresses in the destination fields
   and also uses several different forms of addresses.

----
From: "Joe Q. Public" <john.q.public@example.com>
To: Mary Smith <mary@x.test>, jdoe@example.org, Who? <one@y.test>
Cc: <boss@nil.test>, "Giant; \"Big\" Box" <sysservices@example.net>
Date: Tue, 1 Jul 2003 10:52:37 +0200
Message-ID: <5678.21-Nov-1997@example.com>

Hi everyone.
----

   Note that the display names for Joe Q. Public and Giant; "Big" Box
   needed to be enclosed in double-quotes because the former contains
   the period and the latter contains both semicolon and double-quote
   characters (the double-quote characters appearing as quoted-pair
   construct).  Conversely, the display name for Who? could appear
   without them because the question mark is legal in an atom.  Notice
   also that jdoe@example.org and boss@nil.test have no display names
   associated with them at all, and jdoe@example.org uses the simpler
   address form without the angle brackets.











Resnick                     Standards Track                    [Page 42]

RFC 2822                Internet Message Format               April 2001


A.1.3. Group addresses

----
From: Pete <pete@silly.example>
To: A Group:Chris Jones <c@a.test>,joe@where.test,John <jdoe@one.test>;
Cc: Undisclosed recipients:;
Date: Thu, 13 Feb 1969 23:32:54 -0330
Message-ID: <testabcd.1234@silly.example>

Testing.
----

   In this message, the "To:" field has a single group recipient named A
   Group which contains 3 addresses, and a "Cc:" field with an empty
   group recipient named Undisclosed recipients.

A.2. Reply messages

   The following is a series of three messages that make up a
   conversation thread between John and Mary.  John firsts sends a
   message to Mary, Mary then replies to John's message, and then John
   replies to Mary's reply message.

   Note especially the "Message-ID:", "References:", and "In-Reply-To:"
   fields in each message.

----
From: John Doe <jdoe@machine.example>
To: Mary Smith <mary@example.net>
Subject: Saying Hello
Date: Fri, 21 Nov 1997 09:55:06 -0600
Message-ID: <1234@local.machine.example>

This is a message just to say hello.
So, "Hello".
----















Resnick                     Standards Track                    [Page 43]

RFC 2822                Internet Message Format               April 2001


   When sending replies, the Subject field is often retained, though
   prepended with "Re: " as described in section 3.6.5.

----
From: Mary Smith <mary@example.net>
To: John Doe <jdoe@machine.example>
Reply-To: "Mary Smith: Personal Account" <smith@home.example>
Subject: Re: Saying Hello
Date: Fri, 21 Nov 1997 10:01:10 -0600
Message-ID: <3456@example.net>
In-Reply-To: <1234@local.machine.example>
References: <1234@local.machine.example>

This is a reply to your hello.
----

   Note the "Reply-To:" field in the above message.  When John replies
   to Mary's message above, the reply should go to the address in the
   "Reply-To:" field instead of the address in the "From:" field.

----
To: "Mary Smith: Personal Account" <smith@home.example>
From: John Doe <jdoe@machine.example>
Subject: Re: Saying Hello
Date: Fri, 21 Nov 1997 11:00:00 -0600
Message-ID: <abcd.1234@local.machine.tld>
In-Reply-To: <3456@example.net>
References: <1234@local.machine.example> <3456@example.net>

This is a reply to your reply.
----

A.3. Resent messages

   Start with the message that has been used as an example several
   times:

----
From: John Doe <jdoe@machine.example>
To: Mary Smith <mary@example.net>
Subject: Saying Hello
Date: Fri, 21 Nov 1997 09:55:06 -0600
Message-ID: <1234@local.machine.example>

This is a message just to say hello.
So, "Hello".
----




Resnick                     Standards Track                    [Page 44]

RFC 2822                Internet Message Format               April 2001


   Say that Mary, upon receiving this message, wishes to send a copy of
   the message to Jane such that (a) the message would appear to have
   come straight from John; (b) if Jane replies to the message, the
   reply should go back to John; and (c) all of the original
   information, like the date the message was originally sent to Mary,
   the message identifier, and the original addressee, is preserved.  In
   this case, resent fields are prepended to the message:

----
Resent-From: Mary Smith <mary@example.net>
Resent-To: Jane Brown <j-brown@other.example>
Resent-Date: Mon, 24 Nov 1997 14:22:01 -0800
Resent-Message-ID: <78910@example.net>
From: John Doe <jdoe@machine.example>
To: Mary Smith <mary@example.net>
Subject: Saying Hello
Date: Fri, 21 Nov 1997 09:55:06 -0600
Message-ID: <1234@local.machine.example>

This is a message just to say hello.
So, "Hello".
----

   If Jane, in turn, wished to resend this message to another person,
   she would prepend her own set of resent header fields to the above
   and send that.

























Resnick                     Standards Track                    [Page 45]

RFC 2822                Internet Message Format               April 2001


A.4. Messages with trace fields

   As messages are sent through the transport system as described in
   [RFC2821], trace fields are prepended to the message.  The following
   is an example of what those trace fields might look like.  Note that
   there is some folding white space in the first one since these lines
   can be long.

----
Received: from x.y.test
   by example.net
   via TCP
   with ESMTP
   id ABC12345
   for <mary@example.net>;  21 Nov 1997 10:05:43 -0600
Received: from machine.example by x.y.test; 21 Nov 1997 10:01:22 -0600
From: John Doe <jdoe@machine.example>
To: Mary Smith <mary@example.net>
Subject: Saying Hello
Date: Fri, 21 Nov 1997 09:55:06 -0600
Message-ID: <1234@local.machine.example>

This is a message just to say hello.
So, "Hello".
----


























Resnick                     Standards Track                    [Page 46]

RFC 2822                Internet Message Format               April 2001


A.5. White space, comments, and other oddities

   White space, including folding white space, and comments can be
   inserted between many of the tokens of fields.  Taking the example
   from A.1.3, white space and comments can be inserted into all of the
   fields.

----
From: Pete(A wonderful \) chap) <pete(his account)@silly.test(his host)>
To:A Group(Some people)
     :Chris Jones <c@(Chris's host.)public.example>,
         joe@example.org,
  John <jdoe@one.test> (my dear friend); (the end of the group)
Cc:(Empty list)(start)Undisclosed recipients  :(nobody(that I know))  ;
Date: Thu,
      13
        Feb
          1969
      23:32
               -0330 (Newfoundland Time)
Message-ID:              <testabcd.1234@silly.test>

Testing.
----

   The above example is aesthetically displeasing, but perfectly legal.
   Note particularly (1) the comments in the "From:" field (including
   one that has a ")" character appearing as part of a quoted-pair); (2)
   the white space absent after the ":" in the "To:" field as well as
   the comment and folding white space after the group name, the special
   character (".") in the comment in Chris Jones's address, and the
   folding white space before and after "joe@example.org,"; (3) the
   multiple and nested comments in the "Cc:" field as well as the
   comment immediately following the ":" after "Cc"; (4) the folding
   white space (but no comments except at the end) and the missing
   seconds in the time of the date field; and (5) the white space before
   (but not within) the identifier in the "Message-ID:" field.

A.6. Obsoleted forms

   The following are examples of obsolete (that is, the "MUST NOT
   generate") syntactic elements described in section 4 of this
   document.








Resnick                     Standards Track                    [Page 47]

RFC 2822                Internet Message Format               April 2001


A.6.1. Obsolete addressing

   Note in the below example the lack of quotes around Joe Q. Public,
   the route that appears in the address for Mary Smith, the two commas
   that appear in the "To:" field, and the spaces that appear around the
   "." in the jdoe address.

----
From: Joe Q. Public <john.q.public@example.com>
To: Mary Smith <@machine.tld:mary@example.net>, , jdoe@test   . example
Date: Tue, 1 Jul 2003 10:52:37 +0200
Message-ID: <5678.21-Nov-1997@example.com>

Hi everyone.
----

A.6.2. Obsolete dates

   The following message uses an obsolete date format, including a non-
   numeric time zone and a two digit year.  Note that although the
   day-of-week is missing, that is not specific to the obsolete syntax;
   it is optional in the current syntax as well.

----
From: John Doe <jdoe@machine.example>
To: Mary Smith <mary@example.net>
Subject: Saying Hello
Date: 21 Nov 97 09:55:06 GMT
Message-ID: <1234@local.machine.example>

This is a message just to say hello.
So, "Hello".
----

A.6.3. Obsolete white space and comments

   White space and comments can appear between many more elements than
   in the current syntax.  Also, folding lines that are made up entirely
   of white space are legal.












Resnick                     Standards Track                    [Page 48]

RFC 2822                Internet Message Format               April 2001


----
From  : John Doe <jdoe@machine(comment).  example>
To    : Mary Smith
__
          <mary@example.net>
Subject     : Saying Hello
Date  : Fri, 21 Nov 1997 09(comment):   55  :  06 -0600
Message-ID  : <1234   @   local(blah)  .machine .example>

This is a message just to say hello.
So, "Hello".
----

   Note especially the second line of the "To:" field.  It starts with
   two space characters.  (Note that "__" represent blank spaces.)
   Therefore, it is considered part of the folding as described in
   section 4.2.  Also, the comments and white space throughout
   addresses, dates, and message identifiers are all part of the
   obsolete syntax.

Appendix B. Differences from earlier standards

   This appendix contains a list of changes that have been made in the
   Internet Message Format from earlier standards, specifically [RFC822]
   and [STD3].  Items marked with an asterisk (*) below are items which
   appear in section 4 of this document and therefore can no longer be
   generated.

   1. Period allowed in obsolete form of phrase.
   2. ABNF moved out of document to [RFC2234].
   3. Four or more digits allowed for year.
   4. Header field ordering (and lack thereof) made explicit.
   5. Encrypted header field removed.
   6. Received syntax loosened to allow any token/value pair.
   7. Specifically allow and give meaning to "-0000" time zone.
   8. Folding white space is not allowed between every token.
   9. Requirement for destinations removed.
   10. Forwarding and resending redefined.
   11. Extension header fields no longer specifically called out.
   12. ASCII 0 (null) removed.*
   13. Folding continuation lines cannot contain only white space.*
   14. Free insertion of comments not allowed in date.*
   15. Non-numeric time zones not allowed.*
   16. Two digit years not allowed.*
   17. Three digit years interpreted, but not allowed for generation.
   18. Routes in addresses not allowed.*
   19. CFWS within local-parts and domains not allowed.*
   20. Empty members of address lists not allowed.*



Resnick                     Standards Track                    [Page 49]

RFC 2822                Internet Message Format               April 2001


   21. Folding white space between field name and colon not allowed.*
   22. Comments between field name and colon not allowed.
   23. Tightened syntax of in-reply-to and references.*
   24. CFWS within msg-id not allowed.*
   25. Tightened semantics of resent fields as informational only.
   26. Resent-Reply-To not allowed.*
   27. No multiple occurrences of fields (except resent and received).*
   28. Free CR and LF not allowed.*
   29. Routes in return path not allowed.*
   30. Line length limits specified.
   31. Bcc more clearly specified.

Appendix C. Notices

   Intellectual Property

   The IETF takes no position regarding the validity or scope of any
   intellectual property or other rights that might be claimed to
   pertain to the implementation or use of the technology described in
   this document or the extent to which any license under such rights
   might or might not be available; neither does it represent that it
   has made any effort to identify any such rights.  Information on the
   IETF's procedures with respect to rights in standards-track and
   standards-related documentation can be found in BCP-11.  Copies of
   claims of rights made available for publication and any assurances of
   licenses to be made available, or the result of an attempt made to
   obtain a general license or permission for the use of such
   proprietary rights by implementors or users of this specification can
   be obtained from the IETF Secretariat.






















Resnick                     Standards Track                    [Page 50]

RFC 2822                Internet Message Format               April 2001


Full Copyright Statement

   Copyright (C) The Internet Society (2001).  All Rights Reserved.

   This document and translations of it may be copied and furnished to
   others, and derivative works that comment on or otherwise explain it
   or assist in its implementation may be prepared, copied, published
   and distributed, in whole or in part, without restriction of any
   kind, provided that the above copyright notice and this paragraph are
   included on all such copies and derivative works.  However, this
   document itself may not be modified in any way, such as by removing
   the copyright notice or references to the Internet Society or other
   Internet organizations, except as needed for the purpose of
   developing Internet standards in which case the procedures for
   copyrights defined in the Internet Standards process must be
   followed, or as required to translate it into languages other than
   English.

   The limited permissions granted above are perpetual and will not be
   revoked by the Internet Society or its successors or assigns.

   This document and the information contained herein is provided on an
   "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
   TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
   BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
   HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
   MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Acknowledgement

   Funding for the RFC Editor function is currently provided by the
   Internet Society.



















Resnick                     Standards Track                    [Page 51]



================================================
FILE: doc/notes/rfc/rfc3156.txt
================================================





Network Working Group                                          M. Elkins
Request for Comments: 3156                      Network Associates, Inc.
Updates: 2015                                               D. Del Torto
Category: Standards Track                        CryptoRights Foundation
                                                               R. Levien
                                    University of California at Berkeley
                                                             T. Roessler
                                                             August 2001


                       MIME Security with OpenPGP

Status of this Memo

   This document specifies an Internet standards track protocol for the
   Internet community, and requests discussion and suggestions for
   improvements.  Please refer to the current edition of the "Internet
   Official Protocol Standards" (STD 1) for the standardization state
   and status of this protocol.  Distribution of this memo is unlimited.

Copyright Notice

   Copyright (C) The Internet Society (2001).  All Rights Reserved.

Abstract

   This document describes how the OpenPGP Message Format can be used to
   provide privacy and authentication using the Multipurpose Internet
   Mail Extensions (MIME) security content types described in RFC 1847.

1.  Introduction

   Work on integrating PGP (Pretty Good Privacy) with MIME [3]
   (including the since withdrawn "application/pgp" content type) prior
   to RFC 2015 suffered from a number of problems, the most significant
   of which is the inability to recover signed message bodies without
   parsing data structures specific to PGP.  RFC 2015 makes use of the
   elegant solution proposed in RFC 1847, which defines security
   multipart formats for MIME.  The security multiparts clearly separate
   the signed message body from the signature, and have a number of
   other desirable properties.  This document revises RFC 2015 to adopt
   the integration of PGP and MIME to the needs which emerged during the
   work on the OpenPGP specification.

   This document defines three content types for implementing security
   and privacy with OpenPGP: "application/pgp-encrypted",
   "application/pgp-signature" and "application/pgp-keys".




Elkins, et al.              Standards Track                     [Page 1]

RFC 3156               MIME Security with OpenPGP            August 2001


   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in RFC 2119.

2.  OpenPGP data formats

   OpenPGP implementations can generate either ASCII armor (described in
   [1]) or 8-bit binary output when encrypting data, generating a
   digital signature, or extracting public key data.  The ASCII armor
   output is the REQUIRED method for data transfer.  This allows those
   users who do not have the means to interpret the formats described in
   this document to be able to extract and use the OpenPGP information
   in the message.

   When the amount of data to be transmitted requires that it be sent in
   many parts, the MIME message/partial mechanism SHOULD be used rather
   than the multi-part ASCII armor OpenPGP format.

3.  Content-Transfer-Encoding restrictions

   Multipart/signed and multipart/encrypted are to be treated by agents
   as opaque, meaning that the data is not to be altered in any way [2],
   [7].  However, many existing mail gateways will detect if the next
   hop does not support MIME or 8-bit data and perform conversion to
   either Quoted-Printable or Base64.  This presents serious problems
   for multipart/signed, in particular, where the signature is
   invalidated when such an operation occurs.  For this reason all data
   signed according to this protocol MUST be constrained to 7 bits (8-
   bit data MUST be encoded using either Quoted-Printable or Base64).
   Note that this also includes the case where a signed object is also
   encrypted (see section 6).  This restriction will increase the
   likelihood that the signature will be valid upon receipt.

   Additionally, implementations MUST make sure that no trailing
   whitespace is present after the MIME encoding has been applied.

      Note: In most cases, trailing whitespace can either be removed, or
      protected by applying an appropriate content-transfer-encoding.
      However, special care must be taken when any header lines - either
      in MIME entity headers, or in embedded RFC 822 headers - are
      present which only consist of whitespace: Such lines must be
      removed entirely, since replacing them by empty lines would turn
      them into header delimiters, and change the semantics of the
      message.  The restrictions on whitespace are necessary in order to
      make the hash calculated invariant under the text and binary mode
      signature mechanisms provided by OpenPGP [1].  Also, they help to
      avoid compatibility problems with PGP implementations which
      predate the OpenPGP specification.



Elkins, et al.              Standards Track                     [Page 2]

RFC 3156               MIME Security with OpenPGP            August 2001


      Note: If any line begins with the string "From ", it is strongly
      suggested that either the Quoted-Printable or Base64 MIME encoding
      be applied.  If Quoted-Printable is used, at least one of the
      characters in the string should be encoded using the hexadecimal
      coding rule.  This is because many mail transfer and delivery
      agents treat "From " (the word "from" followed immediately by a
      space character) as the start of a new message and thus insert a
      right angle-bracket (>) in front of any line beginning with
      "From " to distinguish this case, invalidating the signature.

   Data that is ONLY to be encrypted is allowed to contain 8-bit
   characters and trailing whitespace and therefore need not undergo the
   conversion to a 7bit format, and the stripping of whitespace.

      Implementor's note: It cannot be stressed enough that applications
      using this standard follow MIME's suggestion that you "be
      conservative in what you generate, and liberal in what you
      accept."  In this particular case it means it would be wise for an
      implementation to accept messages with any content-transfer-
      encoding, but restrict generation to the 7-bit format required by
      this memo.  This will allow future compatibility in the event the
      Internet SMTP framework becomes 8-bit friendly.

4.  OpenPGP encrypted data

   Before OpenPGP encryption, the data is written in MIME canonical
   format (body and headers).

   OpenPGP encrypted data is denoted by the "multipart/encrypted"
   content type, described in [2], and MUST have a "protocol" parameter
   value of "application/pgp-encrypted".  Note that the value of the
   parameter MUST be enclosed in quotes.

   The multipart/encrypted MIME body MUST consist of exactly two body
   parts, the first with content type "application/pgp-encrypted".  This
   body contains the control information.  A message complying with this
   standard MUST contain a "Version: 1" field in this body.  Since the
   OpenPGP packet format contains all other information necessary for
   decrypting, no other information is required here.

   The second MIME body part MUST contain the actual encrypted data.  It
   MUST be labeled with a content type of "application/octet-stream".

   Example message:

      From: Michael Elkins <elkins@aero.org>
      To: Michael Elkins <elkins@aero.org>
      Mime-Version: 1.0



Elkins, et al.              Standards Track                     [Page 3]

RFC 3156               MIME Security with OpenPGP            August 2001


      Content-Type: multipart/encrypted; boundary=foo;
         protocol="application/pgp-encrypted"

      --foo
      Content-Type: application/pgp-encrypted

      Version: 1

      --foo
      Content-Type: application/octet-stream

      -----BEGIN PGP MESSAGE-----
      Version: 2.6.2

      hIwDY32hYGCE8MkBA/wOu7d45aUxF4Q0RKJprD3v5Z9K1YcRJ2fve87lMlDlx4Oj
      eW4GDdBfLbJE7VUpp13N19GL8e/AqbyyjHH4aS0YoTk10QQ9nnRvjY8nZL3MPXSZ
      g9VGQxFeGqzykzmykU6A26MSMexR4ApeeON6xzZWfo+0yOqAq6lb46wsvldZ96YA
      AABH78hyX7YX4uT1tNCWEIIBoqqvCeIMpp7UQ2IzBrXg6GtukS8NxbukLeamqVW3
      1yt21DYOjuLzcMNe/JNsD9vDVCvOOG3OCi8=
      =zzaA
      -----END PGP MESSAGE-----

      --foo--

5.  OpenPGP signed data

   OpenPGP signed messages are denoted by the "multipart/signed" content
   type, described in [2], with a "protocol" parameter which MUST have a
   value of "application/pgp-signature" (MUST be quoted).

   The "micalg" parameter for the "application/pgp-signature" protocol
   MUST contain exactly one hash-symbol of the format "pgp-<hash-
   identifier>", where <hash-identifier> identifies the Message
   Integrity Check (MIC) algorithm used to generate the signature.
   Hash-symbols are constructed from the text names registered in [1] or
   according to the mechanism defined in that document by converting the
   text name to lower case and prefixing it with the four characters
   "pgp-".

   Currently defined values are "pgp-md5", "pgp-sha1", "pgp-ripemd160",
   "pgp-md2", "pgp-tiger192", and "pgp-haval-5-160".

   The multipart/signed body MUST consist of exactly two parts.  The
   first part contains the signed data in MIME canonical format,
   including a set of appropriate content headers describing the data.

   The second body MUST contain the OpenPGP digital signature.  It MUST
   be labeled with a content type of "application/pgp-signature".



Elkins, et al.              Standards Track                     [Page 4]

RFC 3156               MIME Security with OpenPGP            August 2001


      Note: Implementations can either generate "signatures of a
      canonical text document" or "signatures of a binary document", as
      defined in [1].  The restrictions on the signed material put forth
      in section 3 and in this section will make sure that the various
      MIC algorithm variants specified in [1] and [5] will all produce
      the same result.

   When the OpenPGP digital signature is generated:

   (1)   The data to be signed MUST first be converted to its content-
         type specific canonical form.  For text/plain, this means
         conversion to an appropriate character set and conversion of
         line endings to the canonical <CR><LF> sequence.

   (2)   An appropriate Content-Transfer-Encoding is then applied; see
         section 3.  In particular, line endings in the encoded data
         MUST use the canonical <CR><LF> sequence where appropriate
         (note that the canonical line ending may or may not be present
         on the last line of encoded data and MUST NOT be included in
         the signature if absent).

   (3)   MIME content headers are then added to the body, each ending
         with the canonical <CR><LF> sequence.

   (4)   As described in section 3 of this document, any trailing
         whitespace MUST then be removed from the signed material.

   (5)   As described in [2], the digital signature MUST be calculated
         over both the data to be signed and its set of content headers.

   (6)   The signature MUST be generated detached from the signed data
         so that the process does not alter the signed data in any way.

      Note: The accepted OpenPGP convention is for signed data to end
      with a <CR><LF> sequence.  Note that the <CR><LF> sequence
      immediately preceding a MIME boundary delimiter line is considered
      to be part of the delimiter in [3], 5.1.  Thus, it is not part of
      the signed data preceding the delimiter line.  An implementation
      which elects to adhere to the OpenPGP convention has to make sure
      it inserts a <CR><LF> pair on the last line of the data to be
      signed and transmitted (signed message and transmitted message
      MUST be identical).

   Example message:

         From: Michael Elkins <elkins@aero.org>
         To: Michael Elkins <elkins@aero.org>
         Mime-Version: 1.0



Elkins, et al.              Standards Track                     [Page 5]

RFC 3156               MIME Security with OpenPGP            August 2001


         Content-Type: multipart/signed; boundary=bar; micalg=pgp-md5;
           protocol="application/pgp-signature"

         --bar
      & Content-Type: text/plain; charset=iso-8859-1
      & Content-Transfer-Encoding: quoted-printable
      &
      & =A1Hola!
      &
      & Did you know that talking to yourself is a sign of senility?
      &
      & It's generally a good idea to encode lines that begin with
      & From=20because some mail transport agents will insert a greater-
      & than (>) sign, thus invalidating the signature.
      &
      & Also, in some cases it might be desirable to encode any   =20
      & trailing whitespace that occurs on lines in order to ensure  =20
      & that the message signature is not invalidated when passing =20
      & a gateway that modifies such whitespace (like BITNET). =20
      &
      & me

      --bar

      Content-Type: application/pgp-signature

      -----BEGIN PGP MESSAGE-----
      Version: 2.6.2

      iQCVAwUBMJrRF2N9oWBghPDJAQE9UQQAtl7LuRVndBjrk4EqYBIb3h5QXIX/LC//
      jJV5bNvkZIGPIcEmI5iFd9boEgvpirHtIREEqLQRkYNoBActFBZmh9GC3C041WGq
      uMbrbxc+nIs1TIKlA08rVi9ig/2Yh7LFrK5Ein57U/W72vgSxLhe/zhdfolT9Brn
      HOxEa44b+EI=
      =ndaj
      -----END PGP MESSAGE-----

      --bar--

   The "&"s in the previous example indicate the portion of the data
   over which the signature was calculated.

   Upon receipt of a signed message, an application MUST:

   (1)   Convert line endings to the canonical <CR><LF> sequence before
         the signature can be verified.  This is necessary since the
         local MTA may have converted to a local end of line convention.





Elkins, et al.              Standards Track                     [Page 6]

RFC 3156               MIME Security with OpenPGP            August 2001


   (2)   Pass both the signed data and its associated content headers
         along with the OpenPGP signature to the signature verification
         service.

6.  Encrypted and Signed Data

   Sometimes it is desirable to both digitally sign and then encrypt a
   message to be sent.  This protocol allows for two methods of
   accomplishing this task.

6.1.  RFC 1847 Encapsulation

   In [2], it is stated that the data is first signed as a
   multipart/signature body, and then encrypted to form the final
   multipart/encrypted body.  This is most useful for standard MIME-
   compliant message forwarding.

   Example:

         Content-Type: multipart/encrypted;
            protocol="application/pgp-encrypted"; boundary=foo

         --foo
         Content-Type: application/pgp-encrypted

         Version: 1

         --foo
         Content-Type: application/octet-stream

         -----BEGIN PGP MESSAGE-----
      & Content-Type: multipart/signed; micalg=pgp-md5
      &     protocol="application/pgp-signature"; boundary=bar
      &
      & --bar
      & Content-Type: text/plain; charset=us-ascii
      &
      & This message was first signed, and then encrypted.
      &
      & --bar
      & Content-Type: application/pgp-signature
      &
      & -----BEGIN PGP MESSAGE-----
      & Version: 2.6.2
      &
      & iQCVAwUBMJrRF2N9oWBghPDJAQE9UQQAtl7LuRVndBjrk4EqYBIb3h5QXIX/LC//
      & jJV5bNvkZIGPIcEmI5iFd9boEgvpirHtIREEqLQRkYNoBActFBZmh9GC3C041WGq
      & uMbrbxc+nIs1TIKlA08rVi9ig/2Yh7LFrK5Ein57U/W72vgSxLhe/zhdfolT9Brn



Elkins, et al.              Standards Track                     [Page 7]

RFC 3156               MIME Security with OpenPGP            August 2001


      & HOxEa44b+EI=
      & =ndaj
      & -----END PGP MESSAGE-----
      &
      & --bar--
        -----END PGP MESSAGE-----

        --foo--

   (The text preceded by '&' indicates that it is really encrypted, but
   presented as text for clarity.)

6.2.  Combined method

   The OpenPGP packet format [1] describes a method for signing and
   encrypting data in a single OpenPGP message.  This method is allowed
   in order to reduce processing overhead and increase compatibility
   with non-MIME implementations of OpenPGP.  The resulting data is
   formatted as a "multipart/encrypted" object as described in Section
   4.

   Messages which are encrypted and signed in this combined fashion are
   REQUIRED to follow the same canonicalization rules as
   multipart/signed objects.

   It is explicitly allowed for an agent to decrypt a combined message
   and rewrite it as a multipart/signed object using the signature data
   embedded in the encrypted version.

7.  Distribution of OpenPGP public keys

   Content-Type: application/pgp-keys
   Required parameters: none
   Optional parameters: none

   A MIME body part of the content type "application/pgp-keys" contains
   ASCII-armored transferable Public Key Packets as defined in [1],
   section 10.1.

8.  Security Considerations

   Signatures of a canonical text document as defined in [1] ignore
   trailing white space in signed material.  Implementations which
   choose to use signatures of canonical text documents will not be able
   to detect the addition of whitespace in transit.

   See [3], [4] for more information on the security considerations
   concerning the underlying protocols.



Elkins, et al.              Standards Track                     [Page 8]

RFC 3156               MIME Security with OpenPGP            August 2001


9.  IANA Considerations

   This document defines three media types: "application/pgp-encrypted",
   "application/pgp-signature" and "application/pgp-keys".  The
   following sections specify the IANA registrations for these types.

9.1.  Registration of the application/pgp-encrypted media type

   MIME media type name: application
   MIME subtype name: pgp-encrypted
   Required parameters: none
   Optional parameters: none

   Encoding considerations:

      Currently this media type always consists of a single 7bit text
      string.

   Security considerations:

      See Section 8 and RFC 2440 Section 13.

   Interoperability considerations: none

   Published specification:

      This document.

   Additional information:

      Magic number(s): none
      File extension(s): none
      Macintosh File Type Code(s): none

   Person & email address to contact for further information:

      Michael Elkins
      Email: me@cs.hmc.edu

   Intended usage: common

   Author/Change controller:

      Michael Elkins
      Email: me@cs.hmc.edu






Elkins, et al.              Standards Track                     [Page 9]

RFC 3156               MIME Security with OpenPGP            August 2001


9.2.  Registration of the application/pgp-signature media type

   MIME media type name: application
   MIME subtype name: pgp-signature
   Required parameters: none
   Optional parameters: none

   Encoding considerations:

      The content of this media type always consists of 7bit text.

   Security considerations:

      See Section 8 and RFC 2440 Section 13.

   Interoperability considerations: none

   Published specification:

      RFC 2440 and this document.

   Additional information:

      Magic number(s): none
      File extension(s): asc, sig
      Macintosh File Type Code(s): pgDS

   Person & email address to contact for further information:

      Michael Elkins
      Email: me@cs.hmc.edu

   Intended usage: common

   Author/Change controller:

      Michael Elkins
      Email: me@cs.hmc.edu

9.3.  Registration of the application/pgp-keys media type

   MIME media type name: application
   MIME subtype name: pgp-keys
   Required parameters: none
   Optional parameters: none






Elkins, et al.              Standards Track                    [Page 10]

RFC 3156               MIME Security with OpenPGP            August 2001


   Encoding considerations:

      The content of this media type always consists of 7bit text.

   Security considerations:

      See Section 8 and RFC 2440 Section 13.

   Interoperability considerations: none

   Published specification:

      RFC 2440 and this document.

   Additional information:

      Magic number(s): none
      File extension(s): asc
      Macintosh File Type Code(s): none

   Person & email address to contact for further information:

      Michael Elkins
      Email: me@cs.hmc.edu

   Intended usage: common

   Author/Change controller:

      Michael Elkins
      Email: me@cs.hmc.edu




















Elkins, et al.              Standards Track                    [Page 11]

RFC 3156               MIME Security with OpenPGP            August 2001


10.  Notes

   "PGP" and "Pretty Good Privacy" are registered trademarks of Network
   Associates, Inc.

11.  Acknowledgements

   This document relies on the work of the IETF's OpenPGP Working
   Group's definitions of the OpenPGP Message Format.  The OpenPGP
   message format is currently described in RFC 2440 [1].

   Special thanks are due: to Philip Zimmermann for his original and
   ongoing work on PGP; to Charles Breed, Jon Callas and Dave Del Torto
   for originally proposing the formation of the OpenPGP Working Group;
   and to Steve Schoenfeld for helpful feedback during the draft
   process.  The authors would also like to thank the engineers at
   Pretty Good Privacy, Inc (now Network Associates, Inc), including
   Colin Plumb, Hal Finney, Jon Callas, Mark Elrod, Mark Weaver and
   Lloyd Chambers, for their technical commentary.

   Additional thanks are due to Jeff Schiller and Derek Atkins for their
   continuing support of strong cryptography and PGP freeware at MIT; to
   Rodney Thayer of Sable Technology; to John Noerenberg, Steve Dorner
   and Laurence Lundblade of the Eudora team at QUALCOMM, Inc; to Bodo
   Moeller for proposing the approach followed with respect to trailing
   whitespace; to John Gilmore, Hugh Daniel and Fred Ringel (at
   Rivertown) and Ian Bell (at Turnpike) for their timely critical
   commentary; and to the international members of the IETF's OpenPGP
   mailing list, including William Geiger, Lutz Donnerhacke and Kazu
   Yamamoto.  The idea to use multipart/mixed with multipart/signed has
   been attributed to James Galvin.  Finally, our gratitude is due to
   the many members of the "Cypherpunks," "Coderpunks" and "pgp-users"
   <http://cryptorights.org/pgp-users> mailing lists and the many users
   of PGP worldwide for helping keep the path to privacy open.

















Elkins, et al.              Standards Track                    [Page 12]

RFC 3156               MIME Security with OpenPGP            August 2001


12.  Addresses of the Authors and OpenPGP Working Group Chair

   The OpenPGP working group can be contacted via the current chair:

   John W. Noerenberg II
   Qualcomm, Inc.
   5775 Morehouse Dr.
   San Diego, CA 92121 USA

   Phone: +1 619 658 3510
   EMail: jwn2@qualcomm.com

   The principal authors of this document are:

   Dave Del Torto
   CryptoRights Foundation
   80 Alviso Street, Mailstop: CRF
   San Francisco, CA 94127 USA

   Phone: +1.415.334.5533, vm: #2
   EMail: ddt@cryptorights.org, ddt@openpgp.net


   Michael Elkins
   Network Associates, Inc.
   3415 S. Sepulveda Blvd Suite 700
   Los Angeles, CA 90034 USA

   Phone: +1.310.737.1663
   Fax:   +1.310.737.1755
   Email: me@cs.hmc.edu, Michael_Elkins@NAI.com


   Raph Levien
   University of California at Berkeley
   579 Soda Hall
   Berkeley, CA 94720 USA

   Phone: +1.510.642.6509
   EMail: raph@acm.org


   Thomas Roessler
   Nordstrasse 99
   D-53111 Bonn, Germany

   Phone: +49-228-638007
   EMail: roessler@does-not-exist.org



Elkins, et al.              Standards Track                    [Page 13]

RFC 3156               MIME Security with OpenPGP            August 2001


References

   [1]   Callas, J., Donnerhacke, L., Finney, H. and R. Thayer, "OpenPGP
         Message Format", RFC 2440, November 1998.

   [2]   Galvin, J., Murphy, G., Crocker, S. and N. Freed, "Security
         Multiparts for MIME: Multipart/Signed and Multipart/Encrypted",
         RFC 1847, October 1995.

   [3]   Freed, N. and N. Borenstein, "Multipurpose Internet Mail
         Extensions (MIME) Part Two: Media Types", RFC 2046, November
         1996.

   [4]   Galvin, J., Murphy, G., Crocker, S. and N. Freed, "MIME Object
         Security Services", RFC 1848, October 1995.

   [5]   Atkins, D., Stallings, W. and P. Zimmermann, "PGP Message
         Exchange Formats", RFC 1991, August 1996.

   [6]   Elkins, M., "MIME Security with Pretty Good Privacy (PGP)", RFC
         2015, October 1996.

   [7]   Freed, N., "Gateways and MIME Security Multiparts", RFC 2480,
         January 1999.



























Elkins, et al.              Standards Track                    [Page 14]

RFC 3156               MIME Security with OpenPGP            August 2001


Full Copyright Statement

   Copyright (C) The Internet Society (2001).  All Rights Reserved.

   This document and translations of it may be copied and furnished to
   others, and derivative works that comment on or otherwise explain it
   or assist in its implementation may be prepared, copied, published
   and distributed, in whole or in part, without restriction of any
   kind, provided that the above copyright notice and this paragraph are
   included on all such copies and derivative works.  However, this
   document itself may not be modified in any way, such as by removing
   the copyright notice or references to the Internet Society or other
   Internet organizations, except as needed for the purpose of
   developing Internet standards in which case the procedures for
   copyrights defined in the Internet Standards process must be
   followed, or as required to translate it into languages other than
   English.

   The limited permissions granted above are perpetual and will not be
   revoked by the Internet Society or its successors or assigns.

   This document and the information contained herein is provided on an
   "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
   TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
   BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
   HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
   MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Acknowledgement

   Funding for the RFC Editor function is currently provided by the
   Internet Society.



















Elkins, et al.              Standards Track                    [Page 15]



================================================
FILE: doc/notes/rfc/rfc3676.txt
================================================






Network Working Group                                         R. Gellens
Request for Comments: 3676                                      Qualcomm
Obsoletes: 2646                                            February 2004
Category: Standards Track


               The Text/Plain Format and DelSp Parameters

Status of this Memo

   This document specifies an Internet standards track protocol for the
   Internet community, and requests discussion and suggestions for
   improvements.  Please refer to the current edition of the "Internet
   Official Protocol Standards" (STD 1) for the standardization state
   and status of this protocol.  Distribution of this memo is unlimited.

Copyright Notice

   Copyright (C) The Internet Society (2004).  All Rights Reserved.

Abstract

   This specification establishes two parameters (Format and DelSP) to
   be used with the Text/Plain media type.  In the presence of these
   parameters, trailing whitespace is used to indicate flowed lines and
   a canonical quote indicator is used to indicate quoted lines.  This
   results in an encoding which appears as normal Text/Plain in older
   implementations, since it is in fact normal Text/Plain, yet provides
   for superior wrapping/flowing, and quoting.

   This document supersedes the one specified in RFC 2646, "The
   Text/Plain Format Parameter", and adds the DelSp parameter to
   accommodate languages/coded character sets in which ASCII spaces are
   not used or appear rarely.

Table of Contents

   1.  Introduction. . . . . . . . . . . . . . . . . . . . . . . . .   2
   2.  Conventions Used in this Document . . . . . . . . . . . . . .   2
   3.  The Problem . . . . . . . . . . . . . . . . . . . . . . . . .   3
       3.1.  Paragraph Text. . . . . . . . . . . . . . . . . . . . .   3
       3.2.  Embarrassing Line Wrap  . . . . . . . . . . . . . . . .   3
       3.3.  New Media Types . . . . . . . . . . . . . . . . . . . .   4
   4.  The Format and DelSp Parameters . . . . . . . . . . . . . . .   5
       4.1.  Interpreting Format=Flowed. . . . . . . . . . . . . . .   6
       4.2.  Generating Format=Flowed  . . . . . . . . . . . . . . .   7
       4.3.  Usenet Signature Convention . . . . . . . . . . . . . .   9
       4.4.  Space-Stuffing  . . . . . . . . . . . . . . . . . . . .   9



Gellens                     Standards Track                     [Page 1]

RFC 3676         Text/Plain Format and DelSp Parameters    February 2004


       4.5.  Quoting . . . . . . . . . . . . . . . . . . . . . . . .   9
       4.6.  Digital Signatures and Encryption . . . . . . . . . . .  11
       4.7.  Examples. . . . . . . . . . . . . . . . . . . . . . . .  12
   5.  Interoperability. . . . . . . . . . . . . . . . . . . . . . .  12
   6.  ABNF. . . . . . . . . . . . . . . . . . . . . . . . . . . . .  13
   7.  Failure Modes . . . . . . . . . . . . . . . . . . . . . . . .  14
       7.1.  Trailing White Space Corruption . . . . . . . . . . . .  14
   8.  Security Considerations . . . . . . . . . . . . . . . . . . .  15
   9.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  15
   10. Internationalization Considerations . . . . . . . . . . . . .  15
   11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . .  15
   12. Normative References. . . . . . . . . . . . . . . . . . . . .  16
   13. Informative References. . . . . . . . . . . . . . . . . . . .  16
   Appendix A: Changes from RFC 2646 . . . . . . . . . . . . . . . .  18
   Author's Address. . . . . . . . . . . . . . . . . . . . . . . . .  19
   Full Copyright Statement. . . . . . . . . . . . . . . . . . . . .  20

1.  Introduction

   Interoperability problems have been observed with erroneous labelling
   of paragraph text as Text/Plain, and with various forms of
   "embarrassing line wrap".  (See Section 3.)

   Attempts to deploy new media types, such as Text/Enriched [Rich] and
   Text/HTML [HTML] have suffered from a lack of backwards compatibility
   and an often hostile user reaction at the receiving end.

   What is required is a format which is in all significant ways
   Text/Plain, and therefore is quite suitable for display as
   Text/Plain, and yet allows the sender to express to the receiver
   which lines are quoted and which lines are considered a logical
   paragraph, and thus eligible to be flowed (wrapped and joined) as
   appropriate.

2.  Conventions Used in this Document

   The key words "REQUIRED", "MUST", "MUST NOT", "SHOULD", "SHOULD NOT",
   and "MAY" in this document are to be interpreted as described in "Key
   words for use in RFCs to Indicate Requirement Levels" [KEYWORDS].

   The term "paragraph" is used here to mean a series of lines which are
   logically to be treated as a unit for display purposes and eligible
   to be flowed (wrapped and joined) as appropriate to fit in the
   display window and when creating text for replies, forwarding, etc.







Gellens                     Standards Track                     [Page 2]

RFC 3676         Text/Plain Format and DelSp Parameters    February 2004


3.  The Problem

   The Text/Plain media type is the lowest common denominator of
   Internet email, with lines of no more than 998 characters (by
   convention usually no more than 78), and where the carriage-return
   and line-feed (CRLF) sequence represents a line break (see [MIME-IMT]
   and [MSG-FMT]).

   Text/Plain is usually displayed as preformatted text, often in a
   fixed font.  That is, the characters start at the left margin of the
   display window, and advance to the right until a CRLF sequence is
   seen, at which point a new line is started, again at the left margin.
   When a line length exceeds the display window, some clients will wrap
   the line, while others invoke a horizontal scroll bar.

   Text which meets this description is defined by this memo as "fixed".

   Some interoperability problems have been observed with this format:

3.1.  Paragraph Text

   Many modern programs use a proportional-spaced font, and use CRLF to
   represent paragraph breaks.  Line breaks are "soft", occurring as
   needed on display.  That is, characters are grouped into a paragraph
   until a CRLF sequence is seen, at which point a new paragraph is
   started.  Each paragraph is displayed, starting at the left margin
   (or paragraph indent), and continuing to the right until a word is
   encountered which does not fit in the remaining display width.  This
   word is displayed at the left margin of the next line.  This
   continues until the paragraph ends (a CRLF is seen).  Extra vertical
   space is left between paragraphs.

   Text which meets this description is defined by this memo as
   "flowed".

   Numerous software products erroneously label this format as
   Text/Plain, resulting in much user discomfort.

3.2.  Embarrassing Line Wrap

   As Text/Plain messages are quoted in replies or forwarded messages,
   each line gradually increases in length, eventually being arbitrarily
   hard wrapped, resulting in "embarrassing line wrap".  This produces
   text which is, at best, hard to read, and often confuses
   attributions.






Gellens                     Standards Track                     [Page 3]

RFC 3676         Text/Plain Format and DelSp Parameters    February 2004


   Example:

      >>>>>>This is a comment from the first message to show a
      >quoting example.
      >>>>>This is a comment from the second message to show a
      >quoting example.
      >>>>This is a comment from the third message.
      >>>This is a comment from the fourth message.

   It can be confusing to assign attribution to lines 2 and 4 above.

   In addition, as devices with display widths smaller than 79 or 80
   characters become more popular, embarrassing line wrap has become
   even more prevalent, even with unquoted text.

   Example:

      This is paragraph text that is
      meant to be flowed across
      several lines.
      However, the sending mailer is
      converting it to fixed text at
      a width of 72
      characters, which causes it to
      look like this when shown on a
      PDA with only
      30 character lines.

3.3.  New Media Types

   Attempts to deploy new media types, such as Text/Enriched [Rich] and
   Text/HTML [HTML] have suffered from a lack of backwards compatibility
   and an often hostile user reaction at the receiving end.

   In particular, Text/Enriched requires that open angle brackets ("<")
   and hard line breaks be doubled, with resulting user unhappiness when
   viewed as Text/Plain.  Text/HTML requires even more alteration of
   text, with a corresponding increase in user complaints.

   A proposal to define a new media type to explicitly represent the
   paragraph form suffered from a lack of interoperability with
   currently deployed software.  Some programs treat unknown subtypes of
   TEXT as an attachment.








Gellens                     Standards Track                     [Page 4]

RFC 3676         Text/Plain Format and DelSp Parameters    February 2004


   What is desired is a format which is in all significant ways
   Text/Plain, and therefore is quite suitable for display as
   Text/Plain, and yet allows the sender to express to the receiver
   which lines can be considered a logical paragraph, and thus flowed
   (wrapped and joined) as appropriate.

4.  The Format and DelSp Parameters

   This specification defines two MIME parameters for use with
   Text/Plain:

      Name:  Format
      Value:  Fixed, Flowed

      Name:  DelSp
      Value:  Yes, No

   (Neither the parameter names nor values are case sensitive.)

   If Format is not specified, or if the value is not recognized, a
   value of Fixed is assumed.  The semantics of the Fixed value are the
   usual associated with Text/Plain [MIME-IMT].

   A Format value of Flowed indicates that the definition of flowed text
   (as specified in this memo) was used on generation, and MAY be used
   on reception.

   Note that because Format is a parameter of the Text/Plain content-
   type, any content-transfer-encoding used is irrelevant to the
   processing of flowed text.

   If DelSp is not specified, or if its value is not recognized, a value
   of No is assumed.  The use of DelSp without a Format value of Flowed
   is undefined.  When creating messages, DelSp SHOULD NOT be specified
   in Text content types other than Text/Plain with Format = Flowed.
   When receiving messages, DelSp SHOULD be ignored if used in a Text
   content type other than Text/Plain with Format = Flowed.

   This section discusses flowed text; section 6 provides a formal
   definition.

   Section 5 discusses interoperability.

   Note that this memo describes an on-the-wire format.  It does not
   address formats for local file storage.






Gellens                     Standards Track                     [Page 5]

RFC 3676         Text/Plain Format and DelSp Parameters    February 2004


4.1.  Interpreting Format=Flowed

   If the first character of a line is a quote mark (">"), the line is
   considered to be quoted (see Section 4.5).  Logically, all quote
   marks are counted and deleted, resulting in a line with a non-zero
   quote depth, and content.  (The agent is of course free to display
   the content with quote marks or excerpt bars or anything else.)
   Logically, this test for quoted lines is done before any other tests
   (that is, before checking for space-stuffed and flowed).

   If the first character of a line is a space, the line has been
   space-stuffed (see Section 4.4).  Logically, this leading space is
   deleted before examining the line further (that is, before checking
   for flowed).

   If the line ends in a space, the line is flowed.  Otherwise it is
   fixed.  The exception to this rule is a signature separator line,
   described in Section 4.3.  Such lines end in a space but are neither
   flowed nor fixed.

   If the line is flowed and DelSp is "yes", the trailing space
   immediately prior to the line's CRLF is logically deleted.  If the
   DelSp parameter is "no" (or not specified, or set to an unrecognized
   value), the trailing space is not deleted.

   Any remaining trailing spaces are part of the line's content, but the
   CRLF of a soft line break is not.

   A series of one or more flowed lines followed by one fixed line is
   considered a paragraph, and MAY be flowed (wrapped and unwrapped) as
   appropriate on display and in the construction of new messages (see
   Section 4.5).

   An interpreting agent SHOULD allow for three exceptions to the rule
   that paragraphs end with a fixed line.  These exceptions are
   improperly constructed messages: a flowed line SHOULD be considered
   to end the paragraph if it is followed by a line of a different quote
   depth (see 4.5) or by a signature separator (see 4.3); the end of the
   body also ends the paragraph.

   A line consisting of one or more spaces (after deleting a space
   acting as stuffing) is considered a flowed line.

   An empty line (just a CRLF) is a fixed line.

   Note that, for Unicode text, [Annex-14] provides guidance for
   choosing at which characters to wrap a line.




Gellens                     Standards Track                     [Page 6]

RFC 3676         Text/Plain Format and DelSp Parameters    February 2004


4.2.  Generating Format=Flowed

   When generating Format=Flowed text, lines SHOULD be 78 characters or
   shorter, including any trailing white space and also including any
   space added as part of stuffing (see Section 4.4).  As suggested
   values, any paragraph longer than 78 characters in total length could
   be wrapped using lines of 72 or fewer characters.  While the specific
   line length used is a matter of aesthetics and preference, longer
   lines are more likely to require rewrapping and to encounter
   difficulties with older mailers.  (It has been suggested that 66
   character lines are the most readable.)

   The restriction to 78 or fewer characters between CRLFs on the wire
   is to conform to [MSG-FMT].

   (In addition to conformance to [MSG-FMT], there is a historical need
   that all lines, even when displayed by a non-flowed-aware program,
   will fit in a standard 79- or 80-column screen without having to be
   wrapped.  The limit is 78, not 79 or 80, because while 79 or 80 fit
   on a line, the last column is often reserved for a line-wrap
   indicator.)

   When creating flowed text, the generating agent wraps, that is,
   inserts 'soft' line breaks as needed.  Soft line breaks are added at
   natural wrapping points, such as between words.  A soft line break is
   a SP CRLF sequence.

   There are two techniques for inserting soft line breaks.  The older
   technique, established by RFC 2646, creates a soft line break by
   inserting a CRLF after the occurrence of a space.  With this
   technique, soft line breaks are only possible where spaces already
   occur.  When this technique is used, the DelSp parameter SHOULD be
   used; if used it MUST be set to "no".

   The newer technique, suitable for use even with languages/coded
   character sets in which the ASCII space character is rare or not
   used, creates a soft line break by inserting a SP CRLF sequence.
   When this technique is used, the DelSp parameter MUST be used and
   MUST be set to "yes".  Note that because of space-stuffing (see
   Section 4.4), when this technique is used and a soft line break is
   inserted at a point where a SP already exists (such as between
   words), if the SP CRLF sequence is added immediately before the SP,
   the pre-existing SP becomes leading and thus requires stuffing.  It
   is RECOMMENDED that agents avoid this by inserting the SP CRLF
   sequence following the existing SP.

   Generating agents MAY use either method within each Text/Plain body
   part.



Gellens                     Standards Track                     [Page 7]

RFC 3676         Text/Plain Format and DelSp Parameters    February 2004


   Regardless of which technique is used, a generating agent SHOULD NOT
   insert a space in an unnatural location, such as into a word (a
   sequence of printable characters, not containing spaces, in a
   language/coded character set in which spaces are common).  If faced
   with such a word which exceeds 78 characters (but less than 998
   characters, the [SMTP] limit on line length), the agent SHOULD send
   the word as is and exceed the 78-character limit on line length.

   A generating agent SHOULD:

   o  Ensure all lines (fixed and flowed) are 78 characters or fewer in
      length, counting any trailing space as well as a space added as
      stuffing, but not counting the CRLF, unless a word by itself
      exceeds 78 characters.

   o  Trim spaces before user-inserted hard line breaks.

   A generating agent MUST:

   o  Space-stuff lines which start with a space, "From ", or ">".

   In order to create messages which do not require space-stuffing, and
   are thus more aesthetically pleasing when viewed as Format=Fixed, a
   generating agent MAY avoid wrapping immediately before ">", "From ",
   or space.

   (See Sections 4.4 and 4.5 for more information on space-stuffing and
   quoting, respectively.)

   A Format=Flowed message consists of zero or more paragraphs, each
   containing one or more flowed lines followed by one fixed line.  The
   usual case is a series of flowed text lines with blank (empty) fixed
   lines between them.

   Any number of fixed lines can appear between paragraphs.

   When placing soft line breaks in a paragraph, generating agents MUST
   NOT place them in a way that causes any line of the paragraph to be a
   signature separator line, because paragraphs cannot contain signature
   separator lines (see Sections 4.3 and 6).

   [Quoted-Printable] encoding SHOULD NOT be used with Format=Flowed
   unless absolutely necessary (for example, non-US-ASCII (8-bit)
   characters over a strictly 7-bit transport such as unextended
   [SMTP]).  In particular, a message SHOULD NOT be encoded in Quoted-
   Printable for the sole purpose of protecting the trailing space on
   flowed lines unless the body part is cryptographically signed or
   encrypted (see Section 4.6).



Gellens                     Standards Track                     [Page 8]

RFC 3676         Text/Plain Format and DelSp Parameters    February 2004


   The intent of Format=Flowed is to allow user agents to generate
   flowed text which is non-obnoxious when viewed as pure, raw
   Text/Plain (without any decoding); use of Quoted-Printable hinders
   this and may cause Format=Flowed to be rejected by end users.

4.3.  Usenet Signature Convention

   There is a long-standing convention in Usenet news which also
   commonly appears in Internet mail of using "-- " as the separator
   line between the body and the signature of a message.  When
   generating a Format=Flowed message containing a Usenet-style
   separator before the signature, the separator line is sent as-is.
   This is a special case; an (optionally quoted or quoted and stuffed)
   line consisting of DASH DASH SP is neither fixed nor flowed.

   Generating agents MUST NOT end a paragraph with such a signature
   line.

   A receiving agent needs to test for a signature line both before the
   test for a quoted line (see Section 4.5) and also after logically
   counting and deleting quote marks and stuffing (see Section 4.4) from
   a quoted line.

4.4.  Space-Stuffing

   In order to allow for unquoted lines which start with ">", and to
   protect against systems which "From-munge" in-transit messages
   (modifying any line which starts with "From " to ">From "),
   Format=Flowed provides for space-stuffing.

   Space-stuffing adds a single space to the start of any line which
   needs protection when the message is generated.  On reception, if the
   first character of a line is a space, it is logically deleted.  This
   occurs after the test for a quoted line (which logically counts and
   deletes any quote marks), and before the test for a flowed line.

   On generation, any unquoted lines which start with ">", and any lines
   which start with a space or "From " MUST be space-stuffed.  Other
   lines MAY be space-stuffed as desired.

   (Note that space-stuffing is conceptually similar to dot-stuffing as
   specified in [SMTP].)

4.5.  Quoting

   In Format=Flowed, the canonical quote indicator (or quote mark) is
   one or more close angle bracket (">") characters.  Lines which start
   with the quote indicator are considered quoted.  The number of ">"



Gellens                     Standards Track                     [Page 9]

RFC 3676         Text/Plain Format and DelSp Parameters    February 2004


   characters at the start of the line specifies the quote depth.
   Flowed lines which are also quoted may require special handling on
   display and when copied to new messages.

   When creating quoted flowed lines, each such line starts with the
   quote indicator.

   Note that because of space-stuffing, the lines
       >> Exit, Stage Left
   and
       >>Exit, Stage Left
   are semantically identical; both have a quote-depth of two, and a
   content of "Exit, Stage Left".

   However, the line
       > > Exit, Stage Left
   is different.  It has a quote-depth of one, and a content of
   "> Exit, Stage Left".

   When generating quoted flowed lines, an agent needs to pay attention
   to changes in quote depth.  All lines of a paragraph MUST be
   unquoted, or else they MUST all be quoted and have the same quote
   depth.  Therefore, whenever there is a change in quote depth, or a
   change from quoted to unquoted, or change from unquoted to quoted,
   the line immediately preceding the change MUST NOT be a flowed line.

   If a receiving agent wishes to reformat flowed quoted lines (joining
   and/or wrapping them) on display or when generating new messages, the
   lines SHOULD be de-quoted, reformatted, and then re-quoted.  To de-
   quote, the number of close angle brackets in the quote indicator at
   the start of each line is counted.  To re-quote after reformatting, a
   quote indicator containing the same number of close angle brackets
   originally present are prefixed to each line.

   On reception, if a change in quote depth occurs on a flowed line,
   this is an improperly formatted message.  The receiver SHOULD handle
   this error by using the 'quote-depth-wins' rule, which is to consider
   the paragraph to end with the flowed line immediately preceding the
   change in quote depth.

   In other words, whenever two adjacent lines have different quote
   depths, senders MUST ensure that the earlier line is not flowed (does
   not end in a space), and receivers finding a flowed line there SHOULD
   treat it as the last line of a paragraph.

   For example, consider the following sequence of lines (using '*' to
   indicate a soft line break, i.e., SP CRLF, and '#' to indicate a hard
   line break, i.e., CRLF):



Gellens                     Standards Track                    [Page 10]

RFC 3676         Text/Plain Format and DelSp Parameters    February 2004


      > Thou villainous ill-breeding spongy dizzy-eyed*
      > reeky elf-skinned pigeon-egg!*     <--- problem ---<
      >> Thou artless swag-bellied milk-livered*
      >> dismal-dreaming idle-headed scut!#
      >>> Thou errant folly-fallen spleeny reeling-ripe*
      >>> unmuzzled ratsbane!#
      >>>> Henceforth, the coding style is to be strictly*
      >>>> enforced, including the use of only upper case.#
      >>>>> I've noticed a lack of adherence to the coding*
      >>>>> styles, of late.#
      >>>>>> Any complaints?#

   The second line ends in a soft line break, even though it is the last
   line of the one-deep quote block.  The question then arises as to how
   this line is to be interpreted, considering that the next line is the
   first line of the two-deep quote block.

   The example text above, when processed according to quote-depth wins,
   results in the first two lines being considered as one quoted, flowed
   section, with a quote depth of 1; the third and fourth lines become a
   quoted, flowed section, with a quote depth of 2.

   A generating agent MUST NOT create this situation; a receiving agent
   SHOULD handle it by giving preference to the quote depth.

4.6.  Digital Signatures and Encryption

   If a message is digitally signed or encrypted it is important that
   cryptographic processing use the same text for signature verification
   and/or decryption as was used for signature generation and/or
   encryption.  Since the use of format=flowed allows text to be altered
   (by adding or removing line breaks and trailing spaces) between
   composition and transmission, and between reception and display,
   interoperability problems or security vulnerabilities may arise if
   originator and recipient do not both use the on-the-wire format for
   cryptographic processing.

   The implications of the interaction between format=flowed and any
   specific cryptographic process depend on the details of the
   cryptographic processing and should be understood before using
   format=flowed in conjunction with signed and/or encrypted messages.

   Note that [OpenPGP] specifies (in Section 7.1) that "any trailing
   whitespace (spaces, and tabs, 0x09) at the end of any line is ignored
   when the cleartext signature is calculated."






Gellens                     Standards Track                    [Page 11]

RFC 3676         Text/Plain Format and DelSp Parameters    February 2004


   Thus it would be possible to add, in transit, a format=flowed header
   to a regular, format=fixed vanilla PGP (not [OpenPGP-MIME]) signed
   message and add arbitrary trailing space characters without this
   addition being detected.  This would change the rendering of the
   article by a client which supported format=flowed.

   Therefore, the use of [OpenPGP] with format=flowed messages is
   strongly discouraged. [OpenPGP-MIME] is recommended instead.

4.7.  Examples

   The following example contains three paragraphs:

      `Take some more tea,' the March Hare said to Alice, very
      earnestly.

      `I've had nothing yet,' Alice replied in an offended tone, `so I
      can't take more.'

      `You mean you can't take LESS,' said the Hatter: `it's very easy
      to take MORE than nothing.'

   This could be encoded as follows (using '*' to indicate a soft line
   break, that is, SP CRLF sequence, and '#' to indicate a hard line
   break, that is, CRLF):

      `Take some more tea,' the March Hare said to Alice, very*
      earnestly.#
      #
      `I've had nothing yet,' Alice replied in an offended tone, `so*
      I can't take more.'#
      #
      `You mean you can't take LESS,' said the Hatter: `it's very*
      easy to take MORE than nothing.'#

   To show an example of quoting, here we have the same exchange,
   presented as a series of direct quotes:

      >>>Take some more tea.#
      >>I've had nothing yet, so I can't take more.#
      >You mean you can't take LESS, it's very easy to take*
      >MORE than nothing.#

5.  Interoperability

   Because flowed lines are all-but-indistinguishable from fixed lines,
   software which does not recognize Format=Flowed treats flowed lines
   as normal Text/Plain (which is what they are).  Thus, Format=Flowed



Gellens                     Standards Track                    [Page 12]

RFC 3676         Text/Plain Format and DelSp Parameters    February 2004


   interoperates with older clients, although flowed lines will have
   trailing white space inserted.

   If a space-stuffed message is received by an agent which handles
   Format=Flowed, the space-stuffing is reversed and thus the message
   appears unchanged.  An agent which is not aware of Format=Flowed will
   of course not undo any space-stuffing; thus Format=Flowed messages
   may appear with a leading space on some lines (those which start with
   a space, ">" which is not a quote indicator, or "From ").  Since
   lines which require space-stuffing rarely occur, and the aesthetic
   consequences of unreversed space-stuffing are minimal, this is not
   expected to be a significant problem.

   If some lines begin with one or more spaces, the generating agent MAY
   space-stuff all lines, to maintain the relative indentation of the
   lines when viewed by clients which are not aware of Format=Flowed.

   Messages generated with DelSp=yes and received by clients which are
   aware of Format=Flowed but are not aware of the DelSp parameter will
   have an extra space remaining after removal of soft line breaks.
   Thus, when generating text in languages/coded character sets in which
   spaces are common, the generating agent MAY always use the DelSp=no
   method.

   Hand-aligned text, such as ASCII tables or art, source code, etc.,
   SHOULD be sent as fixed, not flowed lines.

6.  ABNF

   The constructs used in Text/Plain; Format=Flowed body parts are
   described using Augmented Backus-Naur Form [ABNF], including the core
   rules defined in Appendix A.

   Note that the SP (space) and ">" characters are encoded according to
   the charset parameter.

flowed-body      = *( paragraph / fixed-line / sig-sep )
paragraph        = 1*flowed-line fixed-line
                   ; all lines in paragraph MUST be unquoted or
                   ; have same quote depth
flowed-line      = ( flowed-line-qt / flowed-line-unqt ) flow CRLF
flowed-line-qt   = quote ( ( stuffing stuffed-flowed ) /
                           unstuffed-flowed )
flowed-line-unqt = ( stuffing stuffed-flowed ) / unstuffed-flowed
stuffed-flowed   = *text-char
unstuffed-flowed = non-sp-quote *text-char
fixed-line       = fixed-line-qt / fixed-line-unqt
fixed-line-qt    = quote ( ( stuffing stuffed-fixed ) /



Gellens                     Standards Track                    [Page 13]

RFC 3676         Text/Plain Format and DelSp Parameters    February 2004


                           unstuffed-fixed ) CRLF
fixed-line-unqt  = ( stuffed-fixed / unstuffed-fixed ) CRLF
stuffed-fixed    = *text-char non-sp
unstuffed-fixed  = non-sp-quote [ *text-char non-sp ]
sig-sep          = [ quote [stuffing] ] "--" SP CRLF
quote-mark       = ">"
quote            = 1*quote-mark
stuffing         = SP ; space-stuffed, added on generation if
                      ; needed, deleted on reception
flow             = SP ; space before CRLF indicates flowed line,
                      ; if DelSp=yes, space was added on generation
                      ; and is deleted on reception
non-sp-quote     = < any character except NUL, CR, LF, SP, quote-mark >
non-sp           = non-sp-quote / quote-mark
text-char        = non-sp / SP

   That is, a Format=Flowed message body consists of any number of
   paragraphs and/or fixed lines and/or signature separator lines;
   paragraphs need at least one flowed line and are terminated by a
   fixed line; the fixed line terminating the paragraph is part of the
   paragraph.  (There are some exceptions to this described in the
   text.)

   Without at least one flowed line, there is a series of fixed lines,
   each independent.  There is no paragraph.

   With at least one flowed line, there is a paragraph, and the received
   lines can be reformed and flowed to fit the display window size.
   This can only be done if the lines are part of a logical grouping,
   the paragraph.

   Note that the definitions of flowed-line and sig-sep are potentially
   ambiguous: a signature separator line matches both, but is treated as
   a signature separator line and not a flowed line.

7.  Failure Modes

7.1.  Trailing White Space Corruption

   There are systems in existence which alter trailing whitespace on
   messages which pass through them.  Such systems may strip, or in
   rarer cases, add trailing whitespace, in violation of RFC 2821 [SMTP]
   Section 4.5.2.

   Stripping trailing whitespace has the effect of converting flowed
   lines to fixed lines, which results in a message no worse than if
   Format=Flowed had not been used.




Gellens                     Standards Track                    [Page 14]

RFC 3676         Text/Plain Format and DelSp Parameters    February 2004


   Adding trailing whitespace to a Format=Flowed message may result in a
   malformed display or reply.

   Since most systems which add trailing white space do so to create a
   line which fills an internal record format, the result is almost
   always a line which contains an even number of characters (counting
   the added trailing white space).

   One possible avoidance, therefore, would be to define Format=Flowed
   lines to use either one or two trailing space characters to indicate
   a flowed line, such that the total line length is odd.  However,
   considering the scarcity of such systems today, it is not worth the
   added complexity.

8.  Security Considerations

   Any security considerations which apply to Text/Plain also apply to
   Text/Plain with Format=Flowed.

   Section 4.6 discusses the interaction between Format=Flowed and
   digital signatures or encryption.

9.  IANA Considerations

   IANA has added a reference to this specification in the Text/Plain
   Media Type registration.

10.  Internationalization Considerations

   The line wrap and quoting specifications of Format=Flowed may not be
   suitable for certain charsets, such as for Arabic and Hebrew
   characters that read from right to left.  Care needs to be taken in
   applying format=flowed in these cases, as format=fixed combined with
   [quoted-printable] encoding may be more suitable.

   The DelSp parameter was added specifically to permit Format=Flowed to
   be used with languages/coded character sets in which the ASCII space
   character is rarely used, or not used at all.

11.  Acknowledgments

   The DelSp parameter was developed during a series of discussions
   among a number of people, including Harald Alvestrand, Grant Baillie,
   Ian Bell, Steve Dorner, Patrik Faltstrom, Eric Fischer, Ned Freed,
   Alexey Melnikov, John Myers, and Pete Resnick.






Gellens                     Standards Track                    [Page 15]

RFC 3676         Text/Plain Format and DelSp Parameters    February 2004


   Corrections and clarifications to RFC 2646 and early versions of this
   document were pointed out by several people, including Adam Costello,
   Jutta Degener, Tony Hansen, Simon Josefsson, Dan Kohn, Ragho
   Mahalingam, Keith Moore, Greg Troxel, and Dan Wing.

   I'm told that NeXT's mail application used a very similar mechanism
   (without support for non-Western languages) in 1992.

12.  Normative References

   [ABNF]             Crocker, D., Ed. and P. Overell, "Augmented BNF
                      for Syntax Specifications: ABNF", RFC 2234,
                      November 1997.

   [KEYWORDS]         Bradner, S., "Key words for use in RFCs to
                      Indicate Requirement Levels", BCP 14, RFC 2119,
                      March 1997.

   [MIME-IMT]         Freed, N. and N. Borenstein, "Multipurpose
                      Internet Mail Extensions (MIME) Part Two:  Media
                      Types", RFC 2046, November 1996.

   [Quoted-Printable] Freed, N. and N. Borenstein, "Multipurpose
                      Internet Mail Extensions (MIME) Part One:  Format
                      of Internet Message Bodies", RFC 2045, November
                      1996.

13.  Informative References

   [Annex-14]         Unicode Standard Annex #14, "Line Breaking
                      Properties"
                      <URL:http://www.unicode.org/unicode/reports/tr14/>

   [MSG-FMT]          Resnick, P., Ed., "Internet Message Format", RFC
                      2822, April 2001.

   [OpenPGP]          Callas, J., Donnerhacke, L., Finney, H. and R.
                      Thayer, "OpenPGP Message Format", RFC 2440,
                      November 1998.

   [OpenPGP-MIME]     Elkins, M., "MIME Security with Pretty Good
                      Privacy (PGP)", RFC 2015, October 1996.

                      Elkins, M., Del Torto, D., Levien, R. and J.
                      Roessler, "MIME Security with OpenPGP", RFC 3156,
                      August 2001.





Gellens                     Standards Track                    [Page 16]

RFC 3676         Text/Plain Format and DelSp Parameters    February 2004


   [Rich]             Resnick, P. and A. Walker, "The text/enriched MIME
                      Content-type", RFC 1896, February 1996.

   [SMTP]             Klensin, J., Ed., "Simple Mail Transfer Protocol",
                      RFC 2821, April 2001.














































Gellens                     Standards Track                    [Page 17]

RFC 3676         Text/Plain Format and DelSp Parameters    February 2004


Appendix A:  Changes from RFC 2646

   Substantive:

   o  Added DelSp parameter to handle languages and coded character sets
      in which space is less common or not used.
   o  Updated text on generating and interpreting to accommodate the
      DelSp parameter.
   o  Changed the limits of 79 or 80 to be 78 in conformance with RFC
      2822.
   o  Added text on generating to clarify that the 78-character limit
      includes trailing white space and stuffing.
   o  Changed sig-sep in ABNF to allow stuffing.
   o  Changed fixed-line to allow empty lines in ABNF.
   o  Added explanatory text following ABNF.
   o  Moved text from Abstract to new Introduction; rewrote Abstract.
   o  Moved interoperability text to new section, and updated.
   o  Clarified Security Considerations.
   o  Text on digital signatures now discusses that OpenPGP ignores
      trailing white space.
   o  Mention Unicode Annex 14.
   o  Added mention of quoting to Abstract and Introduction.
   o  Deleted line analysis table.
   o  Added recommendations for OpenPGP and OpenPGP-MIME.
   o  Rewrote ABNF rules to remove most ambiguity and note remaining
      case.
   o  Added note that c-t-e is irrelevant to flowed text processing.
   o  Added text indicating that end of data terminates a paragraph.
   o  Moved sig-sep out of fixed-line ABNF.
   o  Changed some SHOULDs to MUSTs (space-stuffing, quoted paragraphs).
   o  Added note to ABNF that space and ">" are encoded according to
      charset.
   o  Mentioned exceptions in section on interpreting.
   o  Clarified and made consistent treatment of signature separator
      lines.

   Editorial:

   o  Added mention of NeXT's mail application to Acknowledgments.
   o  Updated Acknowledgments.
   o  Updated [SMTP] reference to 2821.
   o  Added Notices.
   o  Split References into Normative and Informative.
   o  Improved text wording in some areas.
   o  Standardize on "quote depth", not "quoting depth".
   o  Moved section on interpreting before section on generating.
   o  Reworded non-normative "should"s.
   o  Noted meaning of "paragraph".



Gellens                     Standards Track                    [Page 18]

RFC 3676         Text/Plain Format and DelSp Parameters    February 2004


   The DelSp parameter was added specifically to permit Format=Flowed to
   be used with languages/coded character sets in which the ASCII space
   character is rarely used, or not used at all.  The DelSp mechanism
   was selected despite having been initially rejected as too much of a
   kludge, because among the many different techniques proposed, it
   allows for maximum interoperability among clients which support
   neither this specification nor RFC 2646, those which do support RFC
   2646 but not this specification, and those that do support this
   specification; this set is multiplied by those that handle
   languages/coded character sets in which spaces are common, and in
   which they are uncommon or not used.

Author's Address

   Randall Gellens
   QUALCOMM Incorporated
   5775 Morehouse Drive
   San Diego, CA  92121
   USA

   Phone: +1 858 651 5115
   EMail: randy@qualcomm.com





























Gellens                     Standards Track                    [Page 19]

RFC 3676         Text/Plain Format and DelSp Parameters    February 2004


Full Copyright Statement

   Copyright (C) The Internet Society (2004).  This document is subject
   to the rights, licenses and restrictions contained in BCP 78 and
   except as set forth therein, the authors retain all their rights.

   This document and the information contained herein are provided on an
   "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE
   REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE
   INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR
   IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
   THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
   WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Intellectual Property

   The IETF takes no position regarding the validity or scope of any
   Intellectual Property Rights or other rights that might be claimed
   to pertain to the implementation or use of the technology
   described in this document or the extent to which any license
   under such rights might or might not be available; nor does it
   represent that it has made any independent effort to identify any
   such rights.  Information on the procedures with respect to
   rights in RFC documents can be found in BCP 78 and BCP 79.

   Copies of IPR disclosures made to the IETF Secretariat and any
   assurances of licenses to be made available, or the result of an
   attempt made to obtain a general license or permission for the use
   of such proprietary rights by implementers or users of this
   specification can be obtained from the IETF on-line IPR repository
   at http://www.ietf.org/ipr.

   The IETF invites any interested party to bring to its attention
   any copyrights, patents or patent applications, or other
   proprietary rights that may cover technology that may be required
   to implement this standard.  Please address the information to the
   IETF at ietf-ipr@ietf.org.

Acknowledgement

   Funding for the RFC Editor function is currently provided by the
   Internet Society.









Gellens                     Standards Track                    [Page 20]



================================================
FILE: doc/notes/rfc/rfc4505.txt
================================================






Network Working Group                                   K. Zeilenga, Ed.
Request for Comments: 4505                           OpenLDAP Foundation
Obsoletes: 2245                                                June 2006
Category: Standards Track


  Anonymous Simple Authentication and Security Layer (SASL) Mechanism

Status of This Memo

   This document specifies an Internet standards track protocol for the
   Internet community, and requests discussion and suggestions for
   improvements.  Please refer to the current edition of the "Internet
   Official Protocol Standards" (STD 1) for the standardization state
   and status of this protocol.  Distribution of this memo is unlimited.

Copyright Notice

   Copyright (C) The Internet Society (2006).

Abstract

   On the Internet, it is common practice to permit anonymous access to
   various services.  Traditionally, this has been done with a plain-
   text password mechanism using "anonymous" as the user name and using
   optional trace information, such as an email address, as the
   password.  As plain-text login commands are not permitted in new IETF
   protocols, a new way to provide anonymous login is needed within the
   context of the Simple Authentication and Security Layer (SASL)
   framework.

1.  Introduction

   This document defines an anonymous mechanism for the Simple
   Authentication and Security Layer ([SASL]) framework.  The name
   associated with this mechanism is "ANONYMOUS".

   Unlike many other SASL mechanisms, whose purpose is to authenticate
   and identify the user to a server, the purpose of this SASL mechanism
   is to allow the user to gain access to services or resources without
   requiring the user to establish or otherwise disclose their identity
   to the server.  That is, this mechanism provides an anonymous login
   method.

   This mechanism does not provide a security layer.

   This document replaces RFC 2245.  Changes since RFC 2245 are detailed
   in Appendix A.



Zeilenga                    Standards Track                     [Page 1]

RFC 4505                Anonymous SASL Mechanism               June 2006


2.  The Anonymous Mechanism

   The mechanism consists of a single message from the client to the
   server.  The client may include in this message trace information in
   the form of a string of [UTF-8]-encoded [Unicode] characters prepared
   in accordance with [StringPrep] and the "trace" stringprep profile
   defined in Section 3 of this document.  The trace information, which
   has no semantical value, should take one of two forms: an Internet
   email address, or an opaque string that does not contain the '@'
   (U+0040) character and that can be interpreted by the system
   administrator of the client's domain.  For privacy reasons, an
   Internet email address or other information identifying the user
   should only be used with permission from the user.

   A server that permits anonymous access will announce support for the
   ANONYMOUS mechanism and allow anyone to log in using that mechanism,
   usually with restricted access.

   A formal grammar for the client message using Augmented BNF [ABNF] is
   provided below as a tool for understanding this technical
   specification.

      message     = [ email / token ]
                    ;; to be prepared in accordance with Section 3

      UTF1        = %x00-3F / %x41-7F ;; less '@' (U+0040)
      UTF2        = %xC2-DF UTF0
      UTF3        = %xE0 %xA0-BF UTF0 / %xE1-EC 2(UTF0) /
                    %xED %x80-9F UTF0 / %xEE-EF 2(UTF0)
      UTF4        = %xF0 %x90-BF 2(UTF0) / %xF1-F3 3(UTF0) /
                    %xF4 %x80-8F 2(UTF0)
      UTF0        = %x80-BF

      TCHAR       = UTF1 / UTF2 / UTF3 / UTF4
                    ;; any UTF-8 encoded Unicode character
                    ;; except '@' (U+0040)

      email       = addr-spec
                    ;; as defined in [IMAIL]

      token       = 1*255TCHAR

   Note to implementors:
      The <token> production is restricted to 255 UTF-8-encoded Unicode
      characters.  As the encoding of a characters uses a sequence of 1
      to 4 octets, a token may be as long as 1020 octets.





Zeilenga                    Standards Track                     [Page 2]

RFC 4505                Anonymous SASL Mechanism               June 2006


3.  The "trace" Profile of "Stringprep"

   This section defines the "trace" profile of [StringPrep].  This
   profile is designed for use with the SASL ANONYMOUS Mechanism.
   Specifically, the client is to prepare the <message> production in
   accordance with this profile.

   The character repertoire of this profile is Unicode 3.2 [Unicode].

   No mapping is required by this profile.

   No Unicode normalization is required by this profile.

   The list of unassigned code points for this profile is that provided
   in Appendix A of [StringPrep].  Unassigned code points are not
   prohibited.

   Characters from the following tables of [StringPrep] are prohibited:

      - C.2.1 (ASCII control characters)
      - C.2.2 (Non-ASCII control characters)
      - C.3 (Private use characters)
      - C.4 (Non-character code points)
      - C.5 (Surrogate codes)
      - C.6 (Inappropriate for plain text)
      - C.8 (Change display properties are deprecated)
      - C.9 (Tagging characters)

   No additional characters are prohibited.

   This profile requires bidirectional character checking per Section 6
   of [StringPrep].

4.  Example

   Here is a sample ANONYMOUS login between an IMAP client and server.
   In this example, "C:" and "S:" indicate lines sent by the client and
   server, respectively.  If such lines are wrapped without a new "C:"
   or "S:" label, then the wrapping is for editorial clarity and is not
   part of the command.

   Note that this example uses the IMAP profile [IMAP4] of SASL.  The
   base64 encoding of challenges and responses as well as the "+ "
   preceding the responses are part of the IMAP4 profile, not part of
   SASL itself.  Additionally, protocols with SASL profiles permitting
   an initial client response will be able to avoid the extra round trip
   below (the server response with an empty "+ ").




Zeilenga                    Standards Track                     [Page 3]

RFC 4505                Anonymous SASL Mechanism               June 2006


   In this example, the trace information is "sirhc".

      S: * OK IMAP4 server ready
      C: A001 CAPABILITY
      S: * CAPABILITY IMAP4 IMAP4rev1 AUTH=DIGEST-MD5 AUTH=ANONYMOUS
      S: A001 OK done
      C: A002 AUTHENTICATE ANONYMOUS
      S: +
      C: c2lyaGM=
      S: A003 OK Welcome, trace information has been logged.

5.  Security Considerations

   The ANONYMOUS mechanism grants access to services and/or resources by
   anyone.  For this reason, it should be disabled by default so that
   the administrator can make an explicit decision to enable it.

   If the anonymous user has any write privileges, a denial-of-service
   attack is possible by filling up all available space.  This can be
   prevented by disabling all write access by anonymous users.

   If anonymous users have read and write access to the same area, the
   server can be used as a communication mechanism to exchange
   information anonymously.  Servers that accept anonymous submissions
   should implement the common "drop box" model, which forbids anonymous
   read access to the area where anonymous submissions are accepted.

   If the anonymous user can run many expensive operations (e.g., an
   IMAP SEARCH BODY command), this could enable a denial-of-service
   attack.  Servers are encouraged to reduce the priority of anonymous
   users or limit their resource usage.

   While servers may impose a limit on the number of anonymous users,
   note that such limits enable denial-of-service attacks and should be
   used with caution.

   The trace information is not authenticated, so it can be falsified.
   This can be used as an attempt to get someone else in trouble for
   access to questionable information.  Administrators investigating
   abuse need to realize that this trace information may be falsified.

   A client that uses the user's correct email address as trace
   information without explicit permission may violate that user's
   privacy.  Anyone who accesses an anonymous archive on a sensitive
   subject (e.g., sexual abuse) likely has strong privacy needs.
   Clients should not send the email address without the explicit
   permission of the user and should offer the option of supplying no
   trace information, thus only exposing the source IP address and time.



Zeilenga                    Standards Track                     [Page 4]

RFC 4505                Anonymous SASL Mechanism               June 2006


   Anonymous proxy servers could enhance this privacy but would have to
   consider the resulting potential denial-of-service attacks.

   Anonymous connections are susceptible to man-in-the-middle attacks
   that view or alter the data transferred.  Clients and servers are
   encouraged to support external data security services.

   Protocols that fail to require an explicit anonymous login are more
   susceptible to break-ins given certain common implementation
   techniques.  Specifically, Unix servers that offer user login may
   initially start up as root and switch to the appropriate user id
   after an explicit login command.  Normally, such servers refuse all
   data access commands prior to explicit login and may enter a
   restricted security environment (e.g., the Unix chroot(2) function)
   for anonymous users.  If anonymous access is not explicitly
   requested, the entire data access machinery is exposed to external
   security attacks without the chance for explicit protective measures.
   Protocols that offer restricted data access should not allow
   anonymous data access without an explicit login step.

   General [SASL] security considerations apply to this mechanism.

   [StringPrep] security considerations and [Unicode] security
   considerations discussed in [StringPrep] apply to this mechanism.
   [UTF-8] security considerations also apply.

6.  IANA Considerations

   The SASL Mechanism registry [IANA-SASL] entry for the ANONYMOUS
   mechanism has been updated by the IANA to reflect that this document
   now provides its technical specification.

      To: iana@iana.org
      Subject: Updated Registration of SASL mechanism ANONYMOUS

      SASL mechanism name: ANONYMOUS
      Security considerations: See RFC 4505.
      Published specification (optional, recommended): RFC 4505
      Person & email address to contact for further information:
           Kurt Zeilenga <Kurt@OpenLDAP.org>
           Chris Newman <Chris.Newman@sun.com>
      Intended usage: COMMON
      Author/Change controller: IESG <iesg@ietf.org>
      Note: Updates existing entry for ANONYMOUS







Zeilenga                    Standards Track                     [Page 5]

RFC 4505                Anonymous SASL Mechanism               June 2006


   The [StringPrep] profile "trace", first defined in this RFC, has been
   registered:

      To: iana@iana.org
      Subject: Initial Registration of Stringprep "trace" profile

      Stringprep profile: trace
      Published specification: RFC 4505
      Person & email address to contact for further information:
          Kurt Zeilenga <kurt@openldap.org>

7.  Acknowledgement

   This document is a revision of RFC 2245 by Chris Newman.  Portions of
   the grammar defined in Section 1 were borrowed from RFC 3629 by
   Francois Yergeau.

   This document is a product of the IETF SASL WG.

8.  Normative References

   [ABNF]       Crocker, D. and P. Overell, "Augmented BNF for Syntax
                Specifications: ABNF", RFC 4234, October 2005.

   [IMAIL]      Resnick, P., "Internet Message Format", RFC 2822, April
                2001.

   [SASL]       Melnikov, A., Ed. and K. Zeilenga, Ed., "Simple
                Authentication and Security Layer (SASL)", RFC 4422,
                June 2006.

   [StringPrep] Hoffman, P. and M. Blanchet, "Preparation of
                Internationalized Strings ('stringprep')", RFC 3454,
                December 2002.

   [Unicode]    The Unicode Consortium, "The Unicode Standard, Version
                3.2.0" is defined by "The Unicode Standard, Version 3.0"
                (Reading, MA, Addison-Wesley, 2000. ISBN 0-201-61633-5),
                as amended by the "Unicode Standard Annex #27: Unicode
                3.1" (http://www.unicode.org/reports/tr27/) and by the
                "Unicode Standard Annex #28: Unicode 3.2"
                (http://www.unicode.org/reports/tr28/).

   [UTF-8]      Yergeau, F., "UTF-8, a transformation format of ISO
                10646", RFC 3629 (also STD 63), November 2003.






Zeilenga                    Standards Track                     [Page 6]

RFC 4505                Anonymous SASL Mechanism               June 2006


9.  Informative References

   [IMAP4]      Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION
                4rev1", RFC 3501, March 2003.

   [IANA-SASL]  IANA, "SIMPLE AUTHENTICATION AND SECURITY LAYER (SASL)
                MECHANISMS", <http://www.iana.org/assignments/sasl-
                mechanisms>.











































Zeilenga                    Standards Track                     [Page 7]

RFC 4505                Anonymous SASL Mechanism               June 2006


Appendix A.  Changes since RFC 2245

   This appendix is non-normative.

   RFC 2245 allows the client to include optional trace information in
   the form of a human readable string.  RFC 2245 restricted this string
   to US-ASCII.  As the Internet is international, this document uses a
   string restricted to UTF-8 encoded Unicode characters.  A
   "stringprep" profile is defined to precisely define which Unicode
   characters are allowed in this string.  While the string remains
   restricted to 255 characters, the encoded length of each character
   may now range from 1 to 4 octets.

   Additionally, a number of editorial changes were made.

Editor's Address

   Kurt D. Zeilenga
   OpenLDAP Foundation

   EMail: Kurt@OpenLDAP.org






























Zeilenga                    Standards Track                     [Page 8]

RFC 4505                Anonymous SASL Mechanism               June 2006


Full Copyright Statement

   Copyright (C) The Internet Society (2006).

   This document is subject to the rights, licenses and restrictions
   contained in BCP 78, and except as set forth therein, the authors
   retain all their rights.

   This document and the information contained herein are provided on an
   "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
   OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
   ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
   INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
   INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
   WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Intellectual Property

   The IETF takes no position regarding the validity or scope of any
   Intellectual Property Rights or other rights that might be claimed to
   pertain to the implementation or use of the technology described in
   this document or the extent to which any license under such rights
   might or might not be available; nor does it represent that it has
   made any independent effort to identify any such rights.  Information
   on the procedures with respect to rights in RFC documents can be
   found in BCP 78 and BCP 79.

   Copies of IPR disclosures made to the IETF Secretariat and any
   assurances of licenses to be made available, or the result of an
   attempt made to obtain a general license or permission for the use of
   such proprietary rights by implementers or users of this
   specification can be obtained from the IETF on-line IPR repository at
   http://www.ietf.org/ipr.

   The IETF invites any interested party to bring to its attention any
   copyrights, patents or patent applications, or other proprietary
   rights that may cover technology that may be required to implement
   this standard.  Please address the information to the IETF at
   ietf-ipr@ietf.org.

Acknowledgement

   Funding for the RFC Editor function is provided by the IETF
   Administrative Support Activity (IASA).







Zeilenga                    Standards Track                     [Page 9]



================================================
FILE: doc/notes/rfc/rfc4616.txt
================================================






Network Working Group                                   K. Zeilenga, Ed.
Request for Comments: 4616                           OpenLDAP Foundation
Updates: 2595                                                August 2006
Category: Standards Track


  The PLAIN Simple Authentication and Security Layer (SASL) Mechanism

Status of This Memo

   This document specifies an Internet standards track protocol for the
   Internet community, and requests discussion and suggestions for
   improvements.  Please refer to the current edition of the "Internet
   Official Protocol Standards" (STD 1) for the standardization state
   and status of this protocol.  Distribution of this memo is unlimited.

Copyright Notice

   Copyright (C) The Internet Society (2006).

Abstract

   This document defines a simple clear-text user/password Simple
   Authentication and Security Layer (SASL) mechanism called the PLAIN
   mechanism.  The PLAIN mechanism is intended to be used, in
   combination with data confidentiality services provided by a lower
   layer, in protocols that lack a simple password authentication
   command.























Zeilenga                    Standards Track                     [Page 1]

RFC 4616                The PLAIN SASL Mechanism             August 2006


1.  Introduction

   Clear-text, multiple-use passwords are simple, interoperate with
   almost all existing operating system authentication databases, and
   are useful for a smooth transition to a more secure password-based
   authentication mechanism.  The drawback is that they are unacceptable
   for use over network connections where data confidentiality is not
   ensured.

   This document defines the PLAIN Simple Authentication and Security
   Layer ([SASL]) mechanism for use in protocols with no clear-text
   login command (e.g., [ACAP] or [SMTP-AUTH]).  This document updates
   RFC 2595, replacing Section 6.  Changes since RFC 2595 are detailed
   in Appendix A.

   The name associated with this mechanism is "PLAIN".

   The PLAIN SASL mechanism does not provide a security layer.

   The PLAIN mechanism should not be used without adequate data security
   protection as this mechanism affords no integrity or confidentiality
   protections itself.  The mechanism is intended to be used with data
   security protections provided by application-layer protocol,
   generally through its use of Transport Layer Security ([TLS])
   services.

   By default, implementations SHOULD advertise and make use of the
   PLAIN mechanism only when adequate data security services are in
   place.  Specifications for IETF protocols that indicate that this
   mechanism is an applicable authentication mechanism MUST mandate that
   implementations support an strong data security service, such as TLS.

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in [Keywords].

2.  PLAIN SASL Mechanism

   The mechanism consists of a single message, a string of [UTF-8]
   encoded [Unicode] characters, from the client to the server.  The
   client presents the authorization identity (identity to act as),
   followed by a NUL (U+0000) character, followed by the authentication
   identity (identity whose password will be used), followed by a NUL
   (U+0000) character, followed by the clear-text password.  As with
   other SASL mechanisms, the client does not provide an authorization
   identity when it wishes the server to derive an identity from the
   credentials and use that as the authorization identity.




Zeilenga                    Standards Track                     [Page 2]

RFC 4616                The PLAIN SASL Mechanism             August 2006


   The formal grammar for the client message using Augmented BNF [ABNF]
   follows.

   message   = [authzid] UTF8NUL authcid UTF8NUL passwd
   authcid   = 1*SAFE ; MUST accept up to 255 octets
   authzid   = 1*SAFE ; MUST accept up to 255 octets
   passwd    = 1*SAFE ; MUST accept up to 255 octets
   UTF8NUL   = %x00 ; UTF-8 encoded NUL character

   SAFE      = UTF1 / UTF2 / UTF3 / UTF4
               ;; any UTF-8 encoded Unicode character except NUL

   UTF1      = %x01-7F ;; except NUL
   UTF2      = %xC2-DF UTF0
   UTF3      = %xE0 %xA0-BF UTF0 / %xE1-EC 2(UTF0) /
               %xED %x80-9F UTF0 / %xEE-EF 2(UTF0)
   UTF4      = %xF0 %x90-BF 2(UTF0) / %xF1-F3 3(UTF0) /
               %xF4 %x80-8F 2(UTF0)
   UTF0      = %x80-BF

   The authorization identity (authzid), authentication identity
   (authcid), password (passwd), and NUL character deliminators SHALL be
   transferred as [UTF-8] encoded strings of [Unicode] characters.  As
   the NUL (U+0000) character is used as a deliminator, the NUL (U+0000)
   character MUST NOT appear in authzid, authcid, or passwd productions.

   The form of the authzid production is specific to the application-
   level protocol's SASL profile [SASL].  The authcid and passwd
   productions are form-free.  Use of non-visible characters or
   characters that a user may be unable to enter on some keyboards is
   discouraged.

   Servers MUST be capable of accepting authzid, authcid, and passwd
   productions up to and including 255 octets.  It is noted that the
   UTF-8 encoding of a Unicode character may be as long as 4 octets.

   Upon receipt of the message, the server will verify the presented (in
   the message) authentication identity (authcid) and password (passwd)
   with the system authentication database, and it will verify that the
   authentication credentials permit the client to act as the (presented
   or derived) authorization identity (authzid).  If both steps succeed,
   the user is authenticated.

   The presented authentication identity and password strings, as well
   as the database authentication identity and password strings, are to
   be prepared before being used in the verification process.  The
   [SASLPrep] profile of the [StringPrep] algorithm is the RECOMMENDED
   preparation algorithm.  The SASLprep preparation algorithm is



Zeilenga                    Standards Track                     [Page 3]

RFC 4616                The PLAIN SASL Mechanism             August 2006


   recommended to improve the likelihood that comparisons behave in an
   expected manner.  The SASLprep preparation algorithm is not mandatory
   so as to allow the server to employ other preparation algorithms
   (including none) when appropriate.  For instance, use of a different
   preparation algorithm may be necessary for the server to interoperate
   with an external system.

   When preparing the presented strings using [SASLPrep], the presented
   strings are to be treated as "query" strings (Section 7 of
   [StringPrep]) and hence unassigned code points are allowed to appear
   in their prepared output.  When preparing the database strings using
   [SASLPrep], the database strings are to be treated as "stored"
   strings (Section 7 of [StringPrep]) and hence unassigned code points
   are prohibited from appearing in their prepared output.

   Regardless of the preparation algorithm used, if the output of a
   non-invertible function (e.g., hash) of the expected string is
   stored, the string MUST be prepared before input to that function.

   Regardless of the preparation algorithm used, if preparation fails or
   results in an empty string, verification SHALL fail.

   When no authorization identity is provided, the server derives an
   authorization identity from the prepared representation of the
   provided authentication identity string.  This ensures that the
   derivation of different representations of the authentication
   identity produces the same authorization identity.

   The server MAY use the credentials to initialize any new
   authentication database, such as one suitable for [CRAM-MD5] or
   [DIGEST-MD5].

3.  Pseudo-Code

   This section provides pseudo-code illustrating the verification
   process (using hashed passwords and the SASLprep preparation
   function) discussed above.  This section is not definitive.

   boolean Verify(string authzid, string authcid, string passwd) {
     string pAuthcid = SASLprep(authcid, true); # prepare authcid
     string pPasswd = SASLprep(passwd, true);   # prepare passwd
     if (pAuthcid == NULL || pPasswd == NULL) {
       return false;     # preparation failed
     }
     if (pAuthcid == "" || pPasswd == "") {
       return false;     # empty prepared string
     }




Zeilenga                    Standards Track                     [Page 4]

RFC 4616                The PLAIN SASL Mechanism             August 2006


     storedHash = FetchPasswordHash(pAuthcid);
     if (storedHash == NULL || storedHash == "") {
       return false;     # error or unknown authcid
     }

     if (!Compare(storedHash, Hash(pPasswd))) {
       return false;     # incorrect password
     }

     if (authzid == NULL ) {
       authzid = DeriveAuthzid(pAuthcid);
       if (authzid == NULL || authzid == "") {
           return false; # could not derive authzid
       }
     }

     if (!Authorize(pAuthcid, authzid)) {
       return false;     # not authorized
     }

     return true;
   }

   The second parameter of the SASLprep function, when true, indicates
   that unassigned code points are allowed in the input.  When the
   SASLprep function is called to prepare the password prior to
   computing the stored hash, the second parameter would be false.

   The second parameter provided to the Authorize function is not
   prepared by this code.  The application-level SASL profile should be
   consulted to determine what, if any, preparation is necessary.

   Note that the DeriveAuthzid and Authorize functions (whether
   implemented as one function or two, whether designed in a manner in
   which these functions or whether the mechanism implementation can be
   reused elsewhere) require knowledge and understanding of mechanism
   and the application-level protocol specification and/or
   implementation details to implement.

   Note that the Authorize function outcome is clearly dependent on
   details of the local authorization model and policy.  Both functions
   may be dependent on other factors as well.









Zeilenga                    Standards Track                     [Page 5]

RFC 4616                The PLAIN SASL Mechanism             August 2006


4.  Examples

   This section provides examples of PLAIN authentication exchanges.
   The examples are intended to help the readers understand the above
   text.  The examples are not definitive.

   "C:" and "S:" indicate lines sent by the client and server,
   respectively.  "<NUL>" represents a single NUL (U+0000) character.
   The Application Configuration Access Protocol ([ACAP]) is used in the
   examples.

   The first example shows how the PLAIN mechanism might be used for
   user authentication.

   S: * ACAP (SASL "CRAM-MD5") (STARTTLS)
   C: a001 STARTTLS
   S: a001 OK "Begin TLS negotiation now"
   <TLS negotiation, further commands are under TLS layer>
   S: * ACAP (SASL "CRAM-MD5" "PLAIN")
   C: a002 AUTHENTICATE "PLAIN"
   S: + ""
   C: {21}
   C: <NUL>tim<NUL>tanstaaftanstaaf
   S: a002 OK "Authenticated"

   The second example shows how the PLAIN mechanism might be used to
   attempt to assume the identity of another user.  In this example, the
   server rejects the request.  Also, this example makes use of the
   protocol optional initial response capability to eliminate a round-
   trip.

   S: * ACAP (SASL "CRAM-MD5") (STARTTLS)
   C: a001 STARTTLS
   S: a001 OK "Begin TLS negotiation now"
   <TLS negotiation, further commands are under TLS layer>
   S: * ACAP (SASL "CRAM-MD5" "PLAIN")
   C: a002 AUTHENTICATE "PLAIN" {20+}
   C: Ursel<NUL>Kurt<NUL>xipj3plmq
   S: a002 NO "Not authorized to requested authorization identity"

5.  Security Considerations

   As the PLAIN mechanism itself provided no integrity or
   confidentiality protections, it should not be used without adequate
   external data security protection, such as TLS services provided by
   many application-layer protocols.  By default, implementations SHOULD
   NOT advertise and SHOULD NOT make use of the PLAIN mechanism unless
   adequate data security services are in place.



Zeilenga                    Standards Track                     [Page 6]

RFC 4616                The PLAIN SASL Mechanism             August 2006


   When the PLAIN mechanism is used, the server gains the ability to
   impersonate the user to all services with the same password
   regardless of any encryption provided by TLS or other confidentiality
   protection mechanisms.  Whereas many other authentication mechanisms
   have similar weaknesses, stronger SASL mechanisms address this issue.
   Clients are encouraged to have an operational mode where all
   mechanisms that are likely to reveal the user's password to the
   server are disabled.

   General [SASL] security considerations apply to this mechanism.

   Unicode, [UTF-8], and [StringPrep] security considerations also
   apply.

6.  IANA Considerations

   The SASL Mechanism registry [IANA-SASL] entry for the PLAIN mechanism
   has been updated by the IANA to reflect that this document now
   provides its technical specification.

   To: iana@iana.org
   Subject: Updated Registration of SASL mechanism PLAIN

   SASL mechanism name: PLAIN
   Security considerations: See RFC 4616.
   Published specification (optional, recommended): RFC 4616
   Person & email address to contact for further information:
        Kurt Zeilenga <kurt@openldap.org>
        IETF SASL WG <ietf-sasl@imc.org>
   Intended usage: COMMON
   Author/Change controller: IESG <iesg@ietf.org>
   Note: Updates existing entry for PLAIN

7.  Acknowledgements

   This document is a revision of RFC 2595 by Chris Newman.  Portions of
   the grammar defined in Section 2 were borrowed from [UTF-8] by
   Francois Yergeau.

   This document is a product of the IETF Simple Authentication and
   Security Layer (SASL) Working Group.










Zeilenga                    Standards Track                     [Page 7]

RFC 4616                The PLAIN SASL Mechanism             August 2006


8.  Normative References

   [ABNF]        Crocker, D., Ed. and P. Overell, "Augmented BNF for
                 Syntax Specifications: ABNF", RFC 4234, October 2005.

   [Keywords]    Bradner, S., "Key words for use in RFCs to Indicate
                 Requirement Levels", BCP 14, RFC 2119, March 1997.

   [SASL]        Melnikov, A., Ed., and K. Zeilenga, Ed., "Simple
                 Authentication and Security Layer (SASL)", RFC 4422,
                 June 2006.

   [SASLPrep]    Zeilenga, K., "SASLprep: Stringprep Profile for User
                 Names and Passwords", RFC 4013, February 2005.

   [StringPrep]  Hoffman, P. and M. Blanchet, "Preparation of
                 Internationalized Strings ("stringprep")", RFC 3454,
                 December 2002.

   [Unicode]     The Unicode Consortium, "The Unicode Standard, Version
                 3.2.0" is defined by "The Unicode Standard, Version
                 3.0" (Reading, MA, Addison-Wesley, 2000. ISBN 0-201-
                 61633-5), as amended by the "Unicode Standard Annex
                 #27: Unicode 3.1"
                 (http://www.unicode.org/reports/tr27/) and by the
                 "Unicode Standard Annex #28: Unicode 3.2"
                 (http://www.unicode.org/reports/tr28/).

   [UTF-8]       Yergeau, F., "UTF-8, a transformation format of ISO
                 10646", STD 63, RFC 3629, November 2003.

   [TLS]         Dierks, T. and E. Rescorla, "The Transport Layer
                 Security (TLS) Protocol Version 1.1", RFC 4346, April
                 2006.

9.  Informative References

   [ACAP]        Newman, C. and J. Myers, "ACAP -- Application
                 Configuration Access Protocol", RFC 2244, November
                 1997.

   [CRAM-MD5]    Nerenberg, L., Ed., "The CRAM-MD5 SASL Mechanism", Work
                 in Progress, June 2006.

   [DIGEST-MD5]  Melnikov, A., Ed., "Using Digest Authentication as a
                 SASL Mechanism", Work in Progress, June 2006.





Zeilenga                    Standards Track                     [Page 8]

RFC 4616                The PLAIN SASL Mechanism             August 2006


   [IANA-SASL]   IANA, "SIMPLE AUTHENTICATION AND SECURITY LAYER (SASL)
                 MECHANISMS",
                 <http://www.iana.org/assignments/sasl-mechanisms>.

   [SMTP-AUTH]   Myers, J., "SMTP Service Extension for Authentication",
                 RFC 2554, March 1999.













































Zeilenga                    Standards Track                     [Page 9]

RFC 4616                The PLAIN SASL Mechanism             August 2006


Appendix A.  Changes since RFC 2595

   This appendix is non-normative.

   This document replaces Section 6 of RFC 2595.

   The specification details how the server is to compare client-
   provided character strings with stored character strings.

   The ABNF grammar was updated.  In particular, the grammar now allows
   LINE FEED (U+000A) and CARRIAGE RETURN (U+000D) characters in the
   authzid, authcid, passwd productions.  However, whether these control
   characters may be used depends on the string preparation rules
   applicable to the production.  For passwd and authcid productions,
   control characters are prohibited.  For authzid, one must consult the
   application-level SASL profile.  This change allows PLAIN to carry
   all possible authorization identity strings allowed in SASL.

   Pseudo-code was added.

   The example section was expanded to illustrate more features of the
   PLAIN mechanism.

Editor's Address

   Kurt D. Zeilenga
   OpenLDAP Foundation

   EMail: Kurt@OpenLDAP.org






















Zeilenga                    Standards Track                    [Page 10]

RFC 4616                The PLAIN SASL Mechanism             August 2006


Full Copyright Statement

   Copyright (C) The Internet Society (2006).

   This document is subject to the rights, licenses and restrictions
   contained in BCP 78, and except as set forth therein, the authors
   retain all their rights.

   This document and the information contained herein are provided on an
   "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
   OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
   ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
   INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
   INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
   WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Intellectual Property

   The IETF takes no position regarding the validity or scope of any
   Intellectual Property Rights or other rights that might be claimed to
   pertain to the implementation or use of the technology described in
   this document or the extent to which any license under such rights
   might or might not be available; nor does it represent that it has
   made any independent effort to identify any such rights.  Information
   on the procedures with respect to rights in RFC documents can be
   found in BCP 78 and BCP 79.

   Copies of IPR disclosures made to the IETF Secretariat and any
   assurances of licenses to be made available, or the result of an
   attempt made to obtain a general license or permission for the use of
   such proprietary rights by implementers or users of this
   specification can be obtained from the IETF on-line IPR repository at
   http://www.ietf.org/ipr.

   The IETF invites any interested party to bring to its attention any
   copyrights, patents or patent applications, or other proprietary
   rights that may cover technology that may be required to implement
   this standard.  Please address the information to the IETF at
   ietf-ipr@ietf.org.

Acknowledgement

   Funding for the RFC Editor function is provided by the IETF
   Administrative Support Activity (IASA).







Zeilenga                    Standards Track                    [Page 11]



================================================
FILE: doc/notes/rfc/rfc4870.txt
================================================





Network Working Group                                          M. Delany
Request for Comments: 4870                                    Yahoo! Inc
Obsoleted By: 4871                                              May 2007
Category: Historic


          Domain-Based Email Authentication Using Public Keys
                   Advertised in the DNS (DomainKeys)

Status of This Memo

   This memo defines a Historic Document for the Internet community.  It
   does not specify an Internet standard of any kind.  Distribution of
   this memo is unlimited.

Copyright Notice

   Copyright (C) The IETF Trust (2007).

Abstract

   "DomainKeys" creates a domain-level authentication framework for
   email by using public key technology and the DNS to prove the
   provenance and contents of an email.

   This document defines a framework for digitally signing email on a
   per-domain basis.  The ultimate goal of this framework is to
   unequivocally prove and protect identity while retaining the
   semantics of Internet email as it is known today.

   Proof and protection of email identity may assist in the global
   control of "spam" and "phishing".



















Delany                          Historic                        [Page 1]

RFC 4870                       DomainKeys                       May 2007


Table of Contents

   1. Introduction ....................................................3
      1.1. Lack of Authentication Is Damaging Internet Email ..........3
      1.2. Digitally Signing Email Creates Credible Domain
           Authentication .............................................4
      1.3. Public Keys in the DNS .....................................4
      1.4. Initial Deployment Is Likely at the Border MTA .............5
      1.5. Conveying Verification Results to MUAs .....................5
      1.6. Technical Minutiae Are Not Completely Covered ..............5
      1.7. Motivation .................................................6
      1.8. Benefits of DomainKeys .....................................6
      1.9. Definitions ................................................7
      1.10. Requirements Notation .....................................8
   2. DomainKeys Overview .............................................8
   3. DomainKeys Detailed View ........................................8
      3.1. Determining the Sending Address of an Email ................9
      3.2. Retrieving the Public Key Given the Sending Domain ........10
           3.2.1. Introducing "selectors" ............................10
           3.2.2. Public Key Signing and Verification Algorithm ......11
           3.2.3. Public key Representation in the DNS ...............13
           3.2.4. Key Sizes ..........................................14
      3.3. Storing the Signature in the Email Header .................15
      3.4. Preparation of Email for Transit and Signing ..............17
           3.4.1. Preparation for Transit ............................18
           3.4.2. Canonicalization for Signing .......................18
                  3.4.2.1. The "simple" Canonicalization Algorithm ...19
                  3.4.2.2. The "nofws" Canonicalization Algorithm ....19
      3.5. The Signing Process .......................................20
           3.5.1. Identifying the Sending Domain .....................20
           3.5.2. Determining Whether an Email Should Be Signed ......21
           3.5.3. Selecting a Private Key and Corresponding
                  Selector Information ...............................21
           3.5.4. Calculating the Signature Value ....................21
           3.5.5. Prepending the "DomainKey-Signature:" Header .......21
      3.6. Policy Statement of Sending Domain ........................22
      3.7. The Verification Process ..................................23
           3.7.1. Presumption that Headers Are Not Reordered .........24
           3.7.2. Verification Should Render a Binary Result .........24
           3.7.3. Selecting the Most Appropriate
                  "DomainKey-Signature:" Header ......................24
           3.7.4. Retrieve the Public Key Based on the
                  Signature Information ..............................26
           3.7.5. Verify the Signature ...............................27
           3.7.6. Retrieving Sending Domain Policy ...................27
           3.7.7. Applying Local Policy ..............................27
      3.8. Conveying Verification Results to MUAs ....................27




Delany                          Historic                        [Page 2]

RFC 4870                       DomainKeys                       May 2007


   4. Example of Use .................................................29
      4.1. The User Composes an Email ................................29
      4.2. The Email Is Signed .......................................29
      4.3. The Email Signature Is Verified ...........................30
   5. Association with a Certificate Authority .......................31
      5.1. The "DomainKey-X509:" Header ..............................31
   6. Topics for Discussion ..........................................32
      6.1. The Benefits of Selectors .................................32
      6.2. Canonicalization of Email .................................33
      6.3. Mailing Lists .............................................33
      6.4. Roving Users ..............................................33
   7. Security Considerations ........................................34
      7.1. DNS .......................................................34
           7.1.1. The DNS Is Not Currently Secure ....................34
           7.1.2. DomainKeys Creates Additional DNS Load .............35
      7.2. Key Management ............................................35
      7.3. Implementation Risks ......................................35
      7.4. Privacy Assumptions with Forwarding Addresses .............35
      7.5. Cryptographic Processing Is Computationally Intensive .....36
   8. The Trial ......................................................36
      8.1. Goals .....................................................36
      8.2. Results of Trial ..........................................37
   9. Note to Implementors Regarding TXT Records .....................37
   10. References ....................................................37
      10.1. Normative References .....................................37
      10.2. Informative References ...................................38
      Appendix A - Syntax Rules for the Tag=Value Format .............39
      Acknowledgments ................................................40

1.  Introduction

   This document proposes an authentication framework for email that
   stores public keys in the DNS and digitally signs email on a domain
   basis.  Separate documents discuss how this framework can be extended
   to validate the delivery path of email as well as facilitate per-user
   authentication.

   The DomainKeys specification was a primary source from which the
   DomainKeys Identified Mail [DKIM] specification has been derived.
   The purpose in submitting this document is as an historical reference
   for deployed implementations written prior to the DKIM specification.

1.1.  Lack of Authentication Is Damaging Internet Email

   Authentication of email is not currently widespread.  Not only is it
   difficult to prove your own identity, it is impossible to prevent
   others from abusing your identity.




Delany                          Historic                        [Page 3]

RFC 4870                       DomainKeys                       May 2007


   While most email exchanges do not intrinsically need authentication
   beyond context, it is the rampant abuse of identity by "spammers",
   "phishers", and their criminal ilk that makes proof necessary.  In
   other words, authentication is as much about protection as proof.

   Importantly, the inability to authenticate email effectively
   delegates much of the control of the disposition of inbound email to
   the sender, since senders can trivially assume any email address.
   Creating email authentication is the first step to returning
   dispositional control of email to the recipient.

   For the purposes of this document, authentication is seen from a user
   perspective, and is intended to answer the question "who sent this
   email?" where "who" is the email address the recipient sees and "this
   email" is the content that the recipient sees.

1.2.  Digitally Signing Email Creates Credible Domain Authentication

   DomainKeys combines public key cryptography and the DNS to provide
   credible domain-level authentication for email.

   When an email claims to originate from a certain domain, DomainKeys
   provides a mechanism by which the recipient system can credibly
   determine that the email did in fact originate from a person or
   system authorized to send email for that domain.

   The authentication provided by DomainKeys works in a number of
   scenarios in which other authentication systems fail or create
   complex operational requirements.  These include the following:

      o forwarded email

      o distributed sending systems

      o authorized third-party sending

   This base definition of DomainKeys is intended to primarily enable
   domain-level authenticity.  Whether a given message is really sent by
   the purported user within the domain is outside the scope of the base
   definition.  Having said that, this specification includes the
   possibility that some domains may wish to delegate fine-grained
   authentication to individual users.

1.3.  Public Keys in the DNS

   DomainKeys differs from traditional hierarchical public key systems
   in that it leverages the DNS for public key management, placing
   complete and direct control of key generation and management with the



Delany                          Historic                        [Page 4]

RFC 4870                       DomainKeys                       May 2007


   owner of the domain.  That is, if you have control over the DNS for a
   given domain, you have control over your DomainKeys for that domain.

   The DNS is proposed as the initial mechanism for publishing public
   keys.  DomainKeys is specifically designed to be extensible to other
   key-fetching services as they become available.

1.4.  Initial Deployment Is Likely at the Border MTA

   For practical reasons, it is expected that initial implementations of
   DomainKeys will be deployed on Mail Transfer Agents (MTAs) that
   accept or relay email across administrative or organizational
   boundaries.  There are numerous advantages to deployment at the
   border MTA, including:

      o  a reduction in the number of MTAs that have to be changed to
         support an implementation of DomainKeys

      o  a reduction in the number of MTAs involved in transmitting the
         email between a signing system and a verifying system, thus
         reducing the number of places that can make accidental changes
         to the contents

      o  removing the need to implement DomainKeys within an internal
         email network.

   However, there is no necessity to deploy DomainKeys at the border as
   signing and verifying can effectively occur anywhere from the border
   MTA right back to the Mail User Agent (MUA).  In particular, the best
   place to sign an email for many domains is likely to be at the point
   of SUBMISSION where the sender is often authenticated through SMTP
   AUTH or other identifying mechanisms.

1.5.  Conveying Verification Results to MUAs

   It follows that testing the authenticity of an email results in some
   action based on the results of the test.  Oftentimes, the action is
   to notify the MUA in some way -- typically via a header line.

   The "Domainkey-Status:" header is defined in this specification for
   recording authentication results in the email.

1.6.  Technical Minutiae Are Not Completely Covered

   The intent of this specification is to communicate the fundamental
   characteristics of DomainKeys for an implementor.  However, some
   aspects are derived from the functionality of the openssl command
   [OPENSSL] and, rather than duplicate that documentation, implementors



Delany                          Historic                        [Page 5]

RFC 4870                       DomainKeys                       May 2007


   are expected to understand the mechanics of the openssl command,
   sufficient to complete the implementation.

1.7.  Motivation

   The motivation for DomainKeys is to define a simple, cheap, and
   "sufficiently effective" mechanism by which domain owners can control
   who has authority to send email using their domain.  To this end, the
   designers of DomainKeys set out to build a framework that:

      o  is transparent and compatible with the existing email
         infrastructure

      o  requires no new infrastructure

      o  can be implemented independently of clients in order to reduce
         deployment time

      o  does not require the use of a central certificate authority
         that might impose fees for certificates or introduce delays to
         deployment

      o  can be deployed incrementally

   While we believe that DomainKeys meets these criteria, it is by no
   means a perfect solution.  The current Internet imposes considerable
   compromises on any similar scheme, and readers should be careful not
   to misinterpret the information provided in this document to imply
   that DomainKeys makes stronger credibility statements than it is able
   to do.

1.8.  Benefits of DomainKeys

   As the reader will discover, DomainKeys is solely an authentication
   system.  It is not a magic bullet for spam, nor is it an
   authorization system, a reputation system, a certification system, or
   a trust system.

   However, a strong authentication system such as DomainKeys creates an
   unimpeachable framework within which comprehensive authorization
   systems, reputations systems, and their ilk can be developed.










Delany                          Historic                        [Page 6]

RFC 4870                       DomainKeys                       May 2007


1.9.  Definitions

   With reference to the following sample email:

   Line   Data
   Number Bytes               Content
   ----   --- --------------------------------------------
     01    46 From: "Joe SixPack" <joe@football.example.com>
     02    40 To: "Suzie Q" <suzie@shopping.example.net>
     03    25 Subject: Is dinner ready?
     04    43 Date: Fri, 11 Jul 2003 21:00:37 -0700 (PDT)
     05    40 Comment: This comment has a continuation
     06    51   because this line begins with folding white space
     07    60 Message-ID: <20030712040037.46341@football.example.com>
     08    00
     09    03 Hi.
     10    00
     11    37 We lost the game. Are you hungry yet?
     12    00
     13    04 Joe.
     14    00
     15    00

   Line 01 is the first line of the email and the first line of the
         headers.

   Lines 05 and 06 constitute the "Comment:" header.

   Line 06 is a continuation header line.

   Line 07 is the last line of the headers.

   Line 08 is the empty line that separates the header from the body.

   Line 09 is the first line of the body.

   Lines 10, 12, 14, and 15 are empty lines.

   Line 13 is the last non-empty line of the email.

   Line 15 is the last line of the body and the last line of the email.

   Lines 01 to 15 constitute the complete email.

   Line 01 is earlier than line 02, and line 02 is later than line 01.






Delany                          Historic                        [Page 7]

RFC 4870                       DomainKeys                       May 2007


1.10.  Requirements Notation

   This document occasionally uses terms that appear in capital letters.
   When the terms "MUST", "SHOULD", "RECOMMENDED", "MUST NOT", "SHOULD
   NOT", and "MAY" appear capitalized, they are being used to indicate
   particular requirements of this specification.  A discussion of the
   meanings of these terms appears in [RFC2119].

2.  DomainKeys Overview

   Under DomainKeys, a domain owner generates one or more private/public
   key pairs that will be used to sign messages originating from that
   domain.  The domain owner places the public key in his domain
   namespace (i.e., in a DNS record associated with that domain), and
   makes the private key available to the outbound email system.  When
   an email is submitted by an authorized user of that domain, the email
   system uses the private key to digitally sign the email associated
   with the sending domain.  The signature is added as a header to the
   email, and the message is transferred to its recipients in the usual
   way.

   When a message is received with a DomainKey signature header, the
   receiving system can verify the signature as follows:

      1. Extract the signature and claimed sending domain from the
         email.

      2. Fetch the public key from the claimed sending domain namespace.

      3. Use public key to determine whether the signature of the email
         has been generated with the corresponding private key, and thus
         whether the email was sent with the authority of the claimed
         sending domain.

   In the event that an email arrives without a signature or when the
   signature verification fails, the receiving system retrieves the
   policy of the claimed sending domain to ascertain the preferred
   disposition of such email.

   Armed with this information, the recipient system can apply local
   policy based on the results of the signature test.

3.  DomainKeys Detailed View

   This section discusses the specifics of DomainKeys that are needed to
   create interoperable implementations.  This section answers the
   following questions:




Delany                          Historic                        [Page 8]

RFC 4870                       DomainKeys                       May 2007


      Given an email, how is the sending domain determined?

      How is the public key retrieved for a sending domain?

      As email transits the email system, it can potentially go through
      a number of changes.  Which parts of the email are included in the
      signature and how are they protected from such transformations?

      How is the signature represented in the email?

      If a signature is not present, or a verification fails, how does
      the recipient determine the policy intent of the sending domain?

      Finally, on verifying the authenticity of an email, how is that
      result conveyed to participating MUAs?

   While there are many alternative design choices, most lead to
   comparable functionality.  The overriding selection criteria used to
   choose among the alternatives are as follows:

      o  use deployed technology whenever possible

      o  prefer ease of implementation

      o  avoid trading risk for excessive flexibility or
         interoperability

      o  include basic flexibility

   Adherence to these criteria implies that some existing email
   implementations will require changes to participate in DomainKeys.
   Ultimately, some hard choices need to be made regarding which
   requirements are more important.

3.1.  Determining the Sending Address of an Email

   The goal of DomainKeys is to give the recipient confidence that the
   email originated from the claimed sender.  As with much of Internet
   email, agreement over what constitutes the "sender" is no easy
   matter.  Forwarding systems and mailing lists add serious
   complications to an overtly simple question.  From the point of view
   of the recipient, the authenticity claim should be directed at the
   domain most visible to the recipient.

   In the first instance, the most visible address is clearly the RFC
   2822 "From:" address [RFC2822].  Therefore, a conforming email MUST
   contain a single "From:" header from which an email address with a
   domain name can be extracted.



Delany                          Historic                        [Page 9]

RFC 4870                       DomainKeys                       May 2007


   A conforming email MAY contain a single RFC 2822 "Sender:" header
   from which an email address with a domain name can be extracted.

   If the email has a valid "From:" and a valid "Sender:" header, then
   the signer MUST use the sending address in the "Sender:" header.

   If the email has a valid "From:" and no "Sender:" header, then the
   signer MUST use the first sending address in the "From:" header.

   In all other cases, a signer MUST NOT sign the email.  Implementors
   should note that an email with a "Sender:" header and no "From:"
   header MUST NOT be signed.

   The domain name in the sending address constitutes the "sending
   domain".

3.2.  Retrieving the Public Key Given the Sending Domain

   To avoid namespace conflicts, it is proposed that the DNS namespace
   "_domainkey." be reserved within the sending domain for storing
   public keys, e.g., if the sending domain is example.net, then the
   public keys for that domain are stored in the _domainkey.example.net
   namespace.

3.2.1.  Introducing "selectors"

   To support multiple concurrent public keys per sending domain, the
   DNS namespace is further subdivided with "selectors".  Selectors are
   arbitrary names below the "_domainkey." namespace.  A selector value
   and length MUST be legal in the DNS namespace and in email headers
   with the additional provision that they cannot contain a semicolon.

   Examples of namespaces using selectors are as follows:

      "coolumbeach._domainkey.example.net"
      "sebastopol._domainkey.example.net"
      "reykjavik._domainkey.example.net"
      "default._domainkey.example.net"

   and

      "2005.pao._domainkey.example.net"
      "2005.sql._domainkey.example.net"
      "2005.rhv._domainkey.example.net"

   Periods are allowed in selectors and are to be treated as component
   separators.  In the case of DNS queries, that means the period
   defines subdomain boundaries.



Delany                          Historic                       [Page 10]

RFC 4870                       DomainKeys                       May 2007


   The number of public keys and corresponding selectors for each domain
   is determined by the domain owner.  Many domain owners will be
   satisfied with just one selector, whereas administratively
   distributed organizations may choose to manage disparate selectors
   and key pairs in different regions, or on different email servers.

   Beyond administrative convenience, selectors make it possible to
   seamlessly replace public keys on a routine basis.  If a domain
   wishes to change from using a public key associated with selector
   "2005" to a public key associated with selector "2006", it merely
   makes sure that both public keys are advertised in the DNS
   concurrently for the transition period during which email may be in
   transit prior to verification.  At the start of the transition
   period, the outbound email servers are configured to sign with the
   "2006" private key.  At the end of the transition period, the "2005"
   public key is removed from the DNS.

   While some domains may wish to make selector values well known,
   others will want to take care not to allocate selector names in a way
   that allows harvesting of data by outside parties.  For example, if
   per-user keys are issued, the domain owner will need to make the
   decision as to whether to make this selector associated directly with
   the user name or make it some unassociated random value, such as the
   fingerprint of the public key.

3.2.2.  Public Key Signing and Verification Algorithm

   The default signature is an RSA signed SHA1 digest of the complete
   email.

   For ease of explanation, the openssl command is used throughout this
   document to describe the mechanism by which keys and signatures are
   managed.

   One way to generate a 768-bit private key suitable for DomainKeys is
   to use openssl like this:

   $ openssl genrsa -out rsa.private 768













Delany                          Historic                       [Page 11]

RFC 4870                       DomainKeys                       May 2007


   which results in the file rsa.private containing the key information
   similar to this:

   -----BEGIN RSA PRIVATE KEY-----
   MIIByQIBAAJhAKJ2lzDLZ8XlVambQfMXn3LRGKOD5o6lMIgulclWjZwP56LRqdg5
   ZX15bhc/GsvW8xW/R5Sh1NnkJNyL/cqY1a+GzzL47t7EXzVc+nRLWT1kwTvFNGIo
   AUsFUq+J6+OprwIDAQABAmBOX0UaLdWWusYzNol++nNZ0RLAtr1/LKMX3tk1MkLH
   +Ug13EzB2RZjjDOWlUOY98yxW9/hX05Uc9V5MPo+q2Lzg8wBtyRLqlORd7pfxYCn
   Kapi2RPMcR1CxEJdXOkLCFECMQDTO0fzuShRvL8q0m5sitIHlLA/L+0+r9KaSRM/
   3WQrmUpV+fAC3C31XGjhHv2EuAkCMQDE5U2nP2ZWVlSbxOKBqX724amoL7rrkUew
   ti9TEjfaBndGKF2yYF7/+g53ZowRkfcCME/xOJr58VN17pejSl1T8Icj88wGNHCs
   FDWGAH4EKNwDSMnfLMG4WMBqd9rzYpkvGQIwLhAHDq2CX4hq2tZAt1zT2yYH7tTb
   weiHAQxeHe0RK+x/UuZ2pRhuoSv63mwbMLEZAjAP2vy6Yn+f9SKw2mKuj1zLjEhG
   6ppw+nKD50ncnPoP322UMxVNG4Eah0GYJ4DLP0U=
   -----END RSA PRIVATE KEY-----

   Once a private key has been generated, the openssl command can be
   used to sign an appropriately prepared email, like this:

   $ openssl dgst -sign rsa.private -sha1 <input.file

   which results in signature data similar to this when represented in
   Base64 [BASE64] format:

   aoiDeX42BB/gP4ScqTdIQJcpAObYr+54yvctqc4rSEFYby9+omKD3pJ/TVxATeTz
   msybuW3WZiamb+mvn7f3rhmnozHJ0yORQbnn4qJQhPbbPbWEQKW09AMJbyz/0lsl

   How this signature is added to the email is discussed later in this
   document.

   To extract the public key component from the private key, use openssl
   like this:

   $ openssl rsa -in rsa.private -out rsa.public -pubout -outform PEM

   which results in the file rsa.public containing the key information
   similar to this:

   -----BEGIN PUBLIC KEY-----
   MHwwDQYJKoZIhvcNAQEBBQADawAwaAJhAKJ2lzDLZ8XlVambQfMXn3LRGKOD5o6l
   MIgulclWjZwP56LRqdg5ZX15bhc/GsvW8xW/R5Sh1NnkJNyL/cqY1a+GzzL47t7E
   XzVc+nRLWT1kwTvFNGIoAUsFUq+J6+OprwIDAQAB
   -----END PUBLIC KEY-----

   This public key data is placed in the DNS.






Delany                          Historic                       [Page 12]

RFC 4870                       DomainKeys                       May 2007


   With the signature, canonical email contents and public key, a
   verifying system can test the validity of the signature.  The openssl
   invocation to verify a signature looks like this:

 $ openssl dgst -verify rsa.public -sha1 -signature sig.file <input.file

3.2.3.  Public key Representation in the DNS

   There is currently no standard method defined for storing public keys
   in the DNS.  As an interim measure, the public key is stored as a TXT
   record derived from a Privacy-Enhanced Mail (PEM) format [PEM], that
   is, as a Base64 representation of a DER encoded key.  Here is an
   example of a 768-bit RSA key in PEM form:

   -----BEGIN PUBLIC KEY-----
   MHwwDQYJKoZIhvcNAQEBBQADawAwaAJhAKJ2lzDLZ8XlVambQfMXn3LRGKOD5o6l
   MIgulclWjZwP56LRqdg5ZX15bhc/GsvW8xW/R5Sh1NnkJNyL/cqY1a+GzzL47t7E
   XzVc+nRLWT1kwTvFNGIoAUsFUq+J6+OprwIDAQAB
   -----END PUBLIC KEY-----

   To save scarce DNS packet space and aid extensibility, the PEM
   wrapping MUST be removed and the remaining public key data along with
   other attributes relevant to DomainKeys functionality are stored as
   tag=value pairs separated by semicolons, for example, as in the
   following:

   brisbane._domainkey IN TXT "g=; k=rsa; p=MHww ... IDAQAB"

   Verifiers MUST support key sizes of 512, 768, 1024, 1536 and 2048
   bits.  Signers MUST support at least one of the verifier supported
   key sizes.

   The current valid tags are as follows:

      g = granularity of the key.  If present with a non-zero length
          value, this value MUST exactly match the local part of the
          sending address.  This tag is optional.

          The intent of this tag is to constrain which sending address
          can legitimately use this selector.  An email with a sending
          address that does not match the value of this tag constitutes
          a failed verification.

      k = key type (rsa is the default).  Signers and verifiers MUST
          support the 'rsa' key type.  This tag is optional.






Delany                          Historic                       [Page 13]

RFC 4870                       DomainKeys                       May 2007


      n = Notes that may be of interest to a human.  No interpretation
          is made by any program.  This tag is optional.

      p = public key data, encoded as a Base64 string.  An empty value
          means that this public key has been revoked.  This tag MUST be
          present.

      t = a set of flags that define boolean attributes.  Valid
          attributes are as follows:

          y = testing mode.  This domain is testing DomainKeys and
              unverified email MUST NOT be treated differently from
              verified email.  Recipient systems MAY wish to track
              testing mode results to assist the sender.

          This tag is optional.

   (Syntax rules for the tag=value format are discussed in Appendix A.)

   Keeping the size of the TXT record to a minimum is important as some
   implementations of content and caching DNS servers are reported to
   have problems supporting large TXT records.  In the example above,
   the encoding generates a 182-byte TXT record.  That this encoding is
   less than 512 bytes is of particular significance as it fits within a
   single UDP response packet.  With careful selection of query values,
   a TXT record can accommodate a 2048 bit key.

   For the same size restriction reason, the "n" tag SHOULD be used
   sparingly.  The most likely use of this tag is to convey a reason why
   a public key might have been revoked.  In this case, set the "n" tag
   to the explanation and remove the public key value from the "p" tag.

3.2.4.  Key Sizes

   Selecting appropriate key sizes is a trade-off between cost,
   performance, and risk.  This specification does not define either
   minimum or maximum key sizes -- that decision is a matter for each
   domain owner.

   Factors that should influence this decision include the following:

      o  the practical constraint that a 2048-bit key is the largest key
         that fits within a 512-byte DNS UDP response packet

      o  larger keys impose higher CPU costs to verify and sign email

      o  keys can be replaced on a regular basis; thus, their lifetime
         can be relatively short



Delany                          Historic                       [Page 14]

RFC 4870                       DomainKeys                       May 2007


      o  the security goals of this specification are modest compared to
         typical goals of public key systems

   In general, it is expected that most domain owners will use keys that
   are no larger than 1024 bits.

3.3.  Storing the Signature in the Email Header

   The signature of the email is stored in the "DomainKey-Signature:"
   header.  This header contains all of the signature and key-fetching
   data.

   When generating the signed email, the "DomainKey-Signature:" header
   MUST precede the original email headers presented to the signature
   algorithm.

   The "DomainKey-Signature:" header is not included in the signature
   calculation.

   For extensibility, the "DomainKey-Signature:" header contains
   tag=value pairs separated by semicolons, for example, as in the
   following:

   DomainKey-Signature: a=rsa-sha1; s=brisbane; d=example.net;
     q=dns; c=simple

   The current valid tags are as follows:

      a = The algorithm used to generate the signature.  The default is
          "rsa-sha1", an RSA signed SHA1 digest.  Signers and verifiers
          MUST support "rsa-sha1".

      b = The signature data, encoded as a Base64 string.  This tag MUST
          be present.

          Whitespace is ignored in this value and MUST be removed when
          reassembling the original signature.  This is another way of
          saying that the signing process can safely insert folding
          whitespace in this value to conform to line-length limits.

      c = Canonicalization algorithm.  The method by which the headers
          and content are prepared for presentation to the signing
          algorithm.  This tag MUST be present.  Verifiers MUST support
          "simple" and "nofws".  Signers MUST support at least one of
          the verifier-supported algorithms.






Delany                          Historic                       [Page 15]

RFC 4870                       DomainKeys                       May 2007


      d = The domain name of the signing domain.  This tag MUST be
          present.  In conjunction with the selector tag, this domain
          forms the basis of the public key query.  The value in this
          tag MUST match the domain of the sending email address or MUST
          be one of the parent domains of the sending email address.
          Domain name comparison is case insensitive.

             The matching process for this tag is called subdomain
             matching, as the sending email address must be the domain
             or subdomain of the value.

      h = A colon-separated list of header field names that identify the
          headers presented to the signing algorithm.  If present, the
          value MUST contain the complete list of headers in the order
          presented to the signing algorithm.

          If present, this tag MUST include the header that was used to
          identify the sending domain, i.e., the "From:" or "Sender:"
          header; thus, this tag can never contain an empty value.

          If this tag is not present, all headers subsequent to the
          signature header are included in the order found in the email.

          A verifier MUST support this tag.  A signer MAY support this
          tag.  If a signer generates this tag, it MUST include all
          email headers in the original email, as a verifier MAY remove
          or render suspicious, lines that are not included in the
          signature.

          In the presence of duplicate headers, a signer may include
          duplicate entries in the list of headers in this tag.  If a
          header is included in this list, a verifier must include all
          occurrences of that header, subsequent to the "DomainKey-
          Signature:" header in the verification.

          If a header identified in this list is not found after the
          "DomainKey-Signature:" header in the verification process, a
          verifier may "look" for a matching header prior to the
          "DomainKey-Signature:" header; however, signers should not
          rely on this as early experience suggests that most verifiers
          do not try to "look" back before the "DomainKey-Signature:"
          header.

          Whitespace is ignored in this value and header comparisons are
          case insensitive.






Delany                          Historic                       [Page 16]

RFC 4870                       DomainKeys                       May 2007


      q = The query method used to retrieve the public key.  This tag
          MUST be present.  Currently, the only valid value is "dns",
          which defines the DNS lookup algorithm described in this
          document.  Verifiers and signers MUST support "dns".

      s = The selector used to form the query for the public key.  This
          tag MUST be present.  In the DNS query type, this value is
          prepended to the "_domainkey." namespace of the sending
          domain.

   (Syntax rules for the tag=value format are discussed in Appendix A.)

   Here is an example of a signature header spread across multiple
   continuation lines:

      DomainKey-Signature: a=rsa-sha1; s=brisbane; d=example.net;
       c=simple; q=dns;
       b=dzdVyOfAKCdLXdJOc9G2q8LoXSlEniSbav+yuU4zGeeruD00lszZ
         VoG4ZHRNiYzR;

   Extreme care must be taken to ensure that any new tags added to this
   header are defined and used solely for the purpose of fetching and
   verifying the signature.  Any semantics beyond verification cannot be
   trusted, as this header is not protected by the signature.

   If additional semantics not pertaining directly to signature
   verification are required, they must only be added as subsequent
   headers protected by the signature.  Semantic additions might include
   audit information describing the initial submission.

3.4.  Preparation of Email for Transit and Signing

   The fundamental purpose of a cryptographic signature is to ensure
   that the signed content matches the contents presented for
   verification.  However, unlike just about every other Internet
   protocol, the email content is routinely modified as it enters and
   transits the email system.

   Fortunately most of the modifications typically made to email can be
   predicted and consequently accounted for when signing and verifying.

   To maximize the chance of a successful verification, submitted email
   should be prepared for transport prior to signing, and the data
   presented to the signing algorithm is canonicalized to exclude the
   most common and minor changes made to email.






Delany                          Historic                       [Page 17]

RFC 4870                       DomainKeys                       May 2007


3.4.1.  Preparation for Transit

   The SMTP protocol defines a number of potential limitations to email
   transport, particularly pertaining to line lengths and 8-bit content.

   While the editor has observed that most modern SMTP implementations
   accept 8-bit email and long lines, some implementations still do not.
   Consequently, a DomainKeys implementation SHOULD prepare an email to
   be suitable for the lowest common denominator of SMTP prior to
   presenting the email for signing.

3.4.2.  Canonicalization for Signing

   DomainKeys is initially expected to be deployed at, or close to, the
   email borders of an organization rather than in MUAs or SUBMISSION
   servers.  In other words, the signing and verifying algorithms
   normally apply after an email has been packaged, transmogrified, and
   generally prepared for transmission across the Internet via SMTP and,
   thus the likelihood of the email being subsequently modified is
   reduced.

   Nonetheless, empirical evidence suggests that some mail servers and
   relay systems modify email in transit, potentially invalidating a
   signature.

   There are two competing perspectives on such modifications.  For most
   senders, mild modification of email is immaterial to the
   authentication status of the email.  For such senders, a
   canonicalization algorithm that survives modest in-transit
   modification is preferred.

   For other senders however, any modification of the email - however
   minor -- results in a desire for the authentication to fail.  In
   other words, such senders do not want a modified email to be seen as
   being authorized by them.  These senders prefer a canonicalization
   algorithm that does not tolerate in-transit modification of the
   signed email.

   To satisfy both requirements, two canonicalization algorithms are
   defined.  A "simple" algorithm that tolerates almost no modification
   and a "nofws" algorithm that tolerates common modifications as
   whitespace replacement and header line rewrapping.

   A sender may choose either algorithm when signing an email.  A
   verifier MUST be able to process email using either algorithm.

   Either algorithm can be used in conjunction with the "h" tag in the
   "DomainKey-Signature:" header.



Delany                          Historic                       [Page 18]

RFC 4870                       DomainKeys                       May 2007


   Canonicalization simply prepares the email for the signing or
   verification algorithm.  It does not change the transmitted data in
   any way.

3.4.2.1.  The "simple" Canonicalization Algorithm

   o  Each line of the email is presented to the signing algorithm in
      the order it occurs in the complete email, from the first line of
      the headers to the last line of the body.

   o  If the "h" tag is used, only those header lines (and their
      continuation lines if any) added to the "h" tag list are included.

   o  The "h" tag only constrains header lines.  It has no bearing on
      body lines, which are always included.

   o  Remove any local line terminator.

   o  Append CRLF to the resulting line.

   o  All trailing empty lines are ignored.  An empty line is a line of
      zero length after removal of the local line terminator.

      If the body consists entirely of empty lines, then the header/body
      line is similarly ignored.

3.4.2.2.  The "nofws" Canonicalization Algorithm

   The "No Folding Whitespace" algorithm (nofws) is more complicated
   than the "simple" algorithm for two reasons; folding whitespace is
   removed from all lines and header continuation lines are unwrapped.

      o  Each line of the email is presented to the signing algorithm in
         the order it occurs in the complete email, from the first line
         of the headers to the last line of the body.

      o  Header continuation lines are unwrapped so that header lines
         are processed as a single line.

      o  If the "h" tag is used, only those header lines (and their
         continuation lines if any) added to the "h" tag list are
         included.

      o  The "h" tag only constrains header lines.  It has no bearing on
         body lines, which are always included.






Delany                          Historic                       [Page 19]

RFC 4870                       DomainKeys                       May 2007


      o  For each line in the email, remove all folding whitespace
         characters.  Folding whitespace is defined in RFC 2822 as being
         the decimal ASCII values 9 (HTAB), 10 (NL), 13 (CR), and 32
         (SP).

      o  Append CRLF to the resulting line.

      o  Trailing empty lines are ignored.  An empty line is a line of
         zero length after removal of the local line terminator.  Note
         that the test for an empty line occurs after removing all
         folding whitespace characters.

         If the body consists entirely of empty lines, then the
         header/body line is similarly ignored.

3.5.  The Signing Process

   The previous sections defined the various components and mechanisms
   needed to sign an email.  This section brings those together to
   define the complete process of signing an email.

   A signer MUST only sign email from submissions that are authorized to
   use the sending address.

   Once authorization of the submission has been determined, the signing
   process consists of the following steps:

      o  identifying the sending domain

      o  determining if an email should be signed

      o  selecting a private key and corresponding selector information

      o  calculating the signature value

      o  prepending the "DomainKey-Signature:" header

   If an email cannot be signed for some reason, it is a local policy
   decision as to what to do with that email.

3.5.1.  Identifying the Sending Domain

   The sending domain is determined by finding the email address in the
   "Sender:" header, or, if the "Sender:" header is not present, the
   first email address of the "From:" header is used to determine the
   sending domain.





Delany                          Historic                       [Page 20]

RFC 4870                       DomainKeys                       May 2007


   If the email has an invalid "From:" or an invalid "Sender:" header,
   it MUST NOT be signed.

   If the signer adds the "h" tag to the "DomainKey-Signature:" header,
   that tag MUST include the header that was used to determine the
   sending domain.

3.5.2.  Determining Whether an Email Should Be Signed

   A signer can obviously only sign email for domains for which it has a
   private key and the necessary knowledge of the corresponding public
   key and selector information, however there are a number of other
   reasons why a signer may choose not to sign an email.

   A signer MUST NOT sign an email if the email submission is not
   authorized to use the sending domain.

   A signer MUST NOT sign an email that already contains a "DomainKey-
   Signature:" header unless a "Sender:" header has been added that was
   not included in the original signature.  The most obvious case where
   this occurs is with mailing lists.

   A signer SHOULD NOT remove an existing "DomainKey-Signature:" header.

3.5.3.  Selecting a Private Key and Corresponding Selector Information

   This specification does not define the basis by which a signer should
   choose which private key and selector information to use.  Currently,
   all selectors are equal as far as this specification is concerned, so
   the decision should largely be a matter of administrative
   convenience.

3.5.4.  Calculating the Signature Value

   The signer MUST use one of the defined canonicalization algorithms to
   present the email to the signing algorithm.  Canonicalization is only
   used to prepare the email for signing.  It does not affect the
   transmitted email in any way.

   To avoid possible ambiguity, a signing server may choose to remove
   any pre-existing "DomainKey-Status:" headers from the email prior to
   preparation for signing and transmission.

3.5.5.  Prepending the "DomainKey-Signature:" Header

   The final step in the signing process is that the signer MUST prepend
   the "DomainKey-Signature:" header prior to continuing with the
   process of transmitting the email.



Delany                          Historic                       [Page 21]

RFC 4870                       DomainKeys                       May 2007


3.6.  Policy Statement of Sending Domain

   While the disposition of inbound email is ultimately a matter for the
   receiving system, the introduction of authentication in email creates
   a need for the sender domain to indicate their signing policy and
   preferred disposition of unsigned email, in particular, whether a
   domain is participating in DomainKeys, whether it is testing, and
   whether it signs all outbound email.

   The sending domain policy is very simple and is expressed in the
   _domainkey TXT record in the DNS of the sending domain.  For example,
   in the example.com domain, the record is called
   _domainkey.example.com.

   The contents of this TXT record are stored as tag=value pairs
   separated by semicolons, for example, as in the following:

   _domainkey   IN TXT "t=y; o=-; n=notes; r=emailAddress"

   All tags are optional.  The current valid tags are as follows:

      n = Notes that may be of interest to a human.  No interpretation
          is made by any program.

      o = Outbound Signing policy ("-" means that this domain signs all
          email; "~" is the default and means that this domain may sign
          some email with DomainKeys).

      r = A reporting email address.  If present, this defines the email
          address where invalid verification results are reported.  This
          tag is primarily intended for early implementers -- the
          content and frequency of the reports will be defined in a
          separate document.

      t = a set of flags that define boolean attributes.  Valid
          attributes are as follows:

          y = testing mode.  This domain is testing DomainKeys, and
              unverified email MUST NOT be treated differently from
              verified email.  Recipient systems MAY wish to track
              testing mode results to assist the sender).

          Note that testing mode cannot be turned off by this tag;
          thus, policy cannot revert the testing mode setting of a
          Selector.

          This tag is optional.




Delany                          Historic                       [Page 22]

RFC 4870                       DomainKeys                       May 2007


   (Syntax rules for the tag=value format are discussed in Appendix A.)

   Recipient systems SHOULD only retrieve this policy TXT record to
   determine policy when an email fails to verify or does not include a
   signature.  Recipient systems SHOULD not retrieve this policy TXT
   record for email that successfully verifies.  Note that "testing
   mode" SHOULD also be in the Selector TXT record if the domain owner
   is running a DomainKeys test.

   If the policy TXT record does not exist, recipient systems MUST
   assume the default values.

   There is an important implication when a domain states that it signs
   all email with the "o=-" setting, namely that the sending domain
   prefers that the recipient system treat unsigned mail with a great
   deal of suspicion.  Such suspicion could reasonably extend to
   rejecting such email.  A verifying system MAY reject unverified email
   if a domain policy indicates that it signs all email.

   Of course, nothing compels a recipient MTA to abide by the policy of
   the sender.  In fact, during the trial, a sending domain would want
   to be very certain about setting this policy, as processing by
   recipient MTAs may be unpredictable.  Nonetheless, a domain that
   states that it signs all email MUST expect that unverified email may
   be rejected by some receiving MTAs.

3.7.  The Verification Process

   There is no defined or recommended limit on the lifetime of a
   selector and corresponding public key; however, it is recommended
   that verification occur in a timely manner with the most timely place
   being during acceptance or local delivery by the MTA.

   Verifying a signature consists of the following three steps:

      o  extract signature information from the headers

      o  retrieve the public key based on the signature information

      o  check that the signature verifies against the contents

   In the event that any of these steps fails, the sending domain policy
   is ascertained to assist in applying local policy.








Delany                          Historic                       [Page 23]

RFC 4870                       DomainKeys                       May 2007


3.7.1.  Presumption that Headers Are Not Reordered

   Indications from deployment of previous versions of this
   specification suggest that the canonicalization algorithms in
   conjunction with the "h" tag in the "DomainKey-Signature:" header
   allows most email to cryptographically survive intact between signing
   and verifying.

   The one assumption that most of the early deployments make is that
   the headers included in the signature are not reordered prior to
   verification.

   While nothing in this specification precludes a verifier from
   "looking" for a header that may have been reordered, including being
   moved to a position prior to the "DomainKey-Signature:" header, such
   reordered email is unlikely to be successfully verified by most
   implementations.

   A second consequence of this assumption -- particularly in the
   presence of multiple "DomainKey-Signature:" headers -- is that the
   first "DomainKey-Signature:" header in the email was the last
   signature added to the email and thus is the one to be verified.

3.7.2.  Verification Should Render a Binary Result

   While the symptoms of a failed verification are obvious -- the
   signature doesn't verify -- establishing the exact cause can be more
   difficult.  If a selector cannot be found, is that because the
   selector has been removed, or was the value changed somehow in
   transit? If the signature line is missing, is that because it was
   never there, or was it removed by an overzealous filter?

   For diagnostic purposes, the exact reason why the verification fails
   SHOULD be recorded; however, in terms of presentation to the end
   user, the result SHOULD be presented as a simple binary result:
   either the email is verified or it is not.  If the email cannot be
   verified, then it SHOULD be rendered the same as all unverified email
   regardless of whether or not it looks like it was signed.

3.7.3.  Selecting the Most Appropriate "DomainKey-Signature:" Header

   In most cases, a signed email is expected to have just one signature
   -- that is, one "DomainKey-Signature:" header.  However, it is
   entirely possible that an email can contain multiple signatures.  In
   such cases, a verifier MUST find the most appropriate signature to
   use and SHOULD ignore all other signatures.





Delany                          Historic                       [Page 24]

RFC 4870                       DomainKeys                       May 2007


   The process of finding the most appropriate signature consists of the
   following "best match" rules.  The rules are to be evaluated in
   order.

      1. Selecting the sending domain

         If the email contains a "Sender:" header, the sending domain is
         extracted from the "Sender:" address.  If this extraction
         fails, the email SHALL fail verification.

         If no "Sender:" header is present, the sending domain is
         extracted from the first address of the "From:" header.  If
         this extraction fails, the email SHALL fail verification.

      2. Domain matching

         A signature can only match if the sending domain matches the
         "d" tag domain -- according to the "d" tag subdomain matching
         rules.

      3. "h" tag matching

         If the signature contains the "h" tag list of headers, that
         list must include the header used to extract the sending domain
         in rule 1, above.

      4. Most secure signing algorithm

         While it is not yet the case, in the event that additional
         algorithms are added to this specification, a verifier MUST use
         the signature that contains the most secure algorithm as
         defined by the future specification.  For current
         implementations, that means verifiers MUST ignore signatures
         that are coded with an unrecognized signing algorithm.

      5. Earlier signatures are preferred

         If multiple signatures are equal as far as these rules apply,
         the signature from the earlier header MUST be used in
         preference to later signature headers.

   Implementors MUST meticulously validate the format and values in the
   "DomainKey-Signature:" header; any inconsistency or unexpected values
   MUST result in ignoring that header.  Being "liberal in what you
   accept" is definitely a bad strategy in this security context.






Delany                          Historic                       [Page 25]

RFC 4870                       DomainKeys                       May 2007


   In all cases, if a verification fails, the "DomainKey-Status:" header
   SHOULD be generated and include a message to help explain the reason
   for failure.

3.7.4.  Retrieve the Public Key Based on the Signature Information

   The public key is needed to complete the verification process.  The
   process of retrieving the public key depends on the query type as
   defined by the "q" tag in the "DomainKey-Signature:" header line.
   Obviously, a public key should only be retrieved if the process of
   extracting the signature information is completely successful.

   Currently, the only valid query type is "dns".  The public key
   retrieval process for this type is as follows:

      1. Using the selector name defined by the "s" tag, the
         "_domainkey" namespace and the domain name defined by the "d"
         tag, construct and issue the DNS TXT record query string.

         For example, if s=brisbane and d=example.net, the query string
         is "brisbane._domainkey.example.net".

      2. If the query for the public key fails to respond, the verifier
         SHOULD defer acceptance of this email (normally this will be
         achieved with a 4XX SMTP response code).

      3. If the query for the public key fails because the corresponding
         data does not exist, the verifier MUST treat the email as
         unverified.

      4. If the result returned from the query does not adhere to the
         format defined in this specification, the verifier MUST treat
         the email as unverified.

      5. If the public key data is not suitable for use with the
         algorithm type defined by the "a" tag in the "DomainKey-
         Signature:" header, the verifier MUST treat the email as
         unverified.

   Implementors MUST meticulously validate the format and values
   returned by the public key query.  Any inconsistency or unexpected
   values MUST result in an unverified email.  Being "liberal in what
   you accept" is definitely a bad strategy in this security context.

   Latency critical implementations may wish to initiate the public key
   query in parallel with calculating the SHA-1 hash, as the public key
   is not needed until the final RSA is calculated.




Delany                          Historic                       [Page 26]

RFC 4870                       DomainKeys                       May 2007


3.7.5.  Verify the Signature

   Armed with the signature information from the "DomainKey-Signature:"
   header and the public key information returned by the query, the
   signature of the email can now be verified.

   The canonicalization algorithm defined by the "c" tag in the
   "DomainKey-Signature:" header defines how the data is prepared for
   the verification algorithm, and the "a" tag in the same header
   defines which verification algorithm to use.

3.7.6.  Retrieving Sending Domain Policy

   In the event that an email fails to verify, the policy of the sending
   domain MUST be consulted.  For now, that means consulting the
   _domainkey TXT record in the DNS of the domain in the sending domain
   as defined in Section 3.5.1.  For example, if example.net is the
   sending domain the TXT query is:

      _domainkey.example.net

   A verifier SHOULD consider the sending domain policy statement and
   act accordingly.  The range of possibilities is up to the receiver,
   but it MAY include rejecting the email.

3.7.7.  Applying Local Policy

   After all verification processes are complete, the recipient system
   has authentication information that can help it decide what to do
   with the email.

   It is beyond the scope of this specification to describe what actions
   a recipient system should take, but an authenticated email presents
   an opportunity to a receiving system that unauthenticated email
   cannot.  Specifically, an authenticated email creates a predictable
   identifier by which other decisions can reliably be managed, such as
   trust and reputation.

   Conversely, unauthenticated email lacks a reliable identifier that
   can be used to assign trust and reputation.  It is not unreasonable
   to treat unauthenticated email as lacking any trust and having no
   positive reputation.

3.8.  Conveying Verification Results to MUAs

   Apart from the application of automated policy, the result of a
   signature verification should be conveyed to the user reading the
   email.



Delany                          Historic                       [Page 27]

RFC 4870                       DomainKeys                       May 2007


   Most email clients can be configured to recognize specific headers
   and apply simple rules, e.g., filing into a particular folder.  Since
   DomainKey signatures are expected to be initially verified at the
   border MTA, the results of the verification need to be conveyed to
   the email client.  This is done with the "DomainKey-Status:" header
   line prepended to the email.

   The "DomainKey-Status:" header starts with a string that indicate the
   result of the verification.  Valid values are as follows:

   "good"         - the signature was verified at the time of testing
   "bad"          - the signature failed the verification
   "no key"       - the public key query failed as the key does not
                    exist
   "revoked"      - the public key query failed as the key has been
                    revoked
   "no signature" - this email has no "DomainKey-Signature:" header
   "bad format"   - the signature or the public key contains unexpected
                    data
   "non-participant" - this sending domain has indicated that it does
                       not participate in DomainKeys

   Verifiers may append additional data that expands on the reason for
   the particular status value.

   A client SHOULD just look for "good" and assume that all other values
   imply that the verification could not be performed for some reason.
   Policy action as a consequence of this header is entirely a local
   matter.

   Here are some examples:

      DomainKey-Status: good
      DomainKey-Status: bad format

   Although it is expected that MTAs will be DomainKey aware before
   MUAs, it is nonetheless possible that a DomainKey-aware MUA can be
   fooled by a spoofed "DomainKey-Status:" header that passes through a
   non-DomainKey-aware MTA.

   If this is perceived to be a serious problem, then it may make sense
   to preclude the "good" value and only have values that effectively
   demote the email as far as the UA is concerned.  That way successful
   spoofing attempts can only serve to demote themselves.







Delany                          Historic                       [Page 28]

RFC 4870                       DomainKeys                       May 2007


4.  Example of Use

   This section shows the complete flow of an email from submission to
   final delivery, demonstrating how the various components fit
   together.

4.1.  The User Composes an Email

   From: "Joe SixPack" <joe@football.example.com>
   To: "Suzie Q" <suzie@shopping.example.net>
   Subject: Is dinner ready?
   Date: Fri, 11 Jul 2003 21:00:37 -0700 (PDT)
   Message-ID: <20030712040037.46341.5F8J@football.example.com>

   Hi.

   We lost the game. Are you hungry yet?

   Joe.

4.2.  The Email Is Signed

   This email is signed by the football.example.com outbound email
   server and now looks like this:

   DomainKey-Signature: a=rsa-sha1; s=brisbane; d=football.example.com;
     c=simple; q=dns;
     b=dzdVyOfAKCdLXdJOc9G2q8LoXSlEniSbav+yuU4zGeeruD00lszZ
       VoG4ZHRNiYzR;
   Received: from dsl-10.2.3.4.football.example.com  [10.2.3.4]
        by submitserver.football.example.com with SUBMISSION;
        Fri, 11 Jul 2003 21:01:54 -0700 (PDT)
   From: "Joe SixPack" <joe@football.example.com>
   To: "Suzie Q" <suzie@shopping.example.net>
   Subject: Is dinner ready?
   Date: Fri, 11 Jul 2003 21:00:37 -0700 (PDT)
   Message-ID: <20030712040037.46341.5F8J@football.example.com>

   Hi.

   We lost the game. Are you hungry yet?

   Joe.

   The signing email server requires access to the private key
   associated with the "brisbane" selector to generate this signature.
   Distribution and management of private keys are outside the scope of
   this document.



Delany                          Historic                       [Page 29]

RFC 4870                       DomainKeys                       May 2007


4.3.  The Email Signature Is Verified

   The signature is normally verified by an inbound SMTP server or
   possibly the final delivery agent.  However, intervening MTAs can
   also perform this verification if they choose to do so.

   The verification process uses the domain "football.example.com"
   extracted from the "From:" header and the selector "brisbane" from
   the "DomainKey-Signature:" header to form the DNS TXT query for:

      brisbane._domainkey.football.example.com

   Since there is no "h" tag in the "DomainKey-Signature:" header,
   signature verification starts with the line following the
   "DomainKey-Signature:" line.  The email is canonically prepared for
   verifying with the "simple" method.

   The result of the query and subsequent verification of the signature
   is stored in the "DomainKey-Status:" header line.  After successful
   verification, the email looks like this:

   DomainKey-Status: good
    from=joe@football.example.com; domainkeys=pass
   Received: from mout23.brisbane.football.example.com (192.168.1.1)
             by shopping.example.net with SMTP;
             Fri, 11 Jul 2003 21:01:59 -0700 (PDT)
   DomainKey-Signature: a=rsa-sha1; s=brisbane; d=football.example.com;
    c=simple; q=dns;
    b=dzdVyOfAKCdLXdJOc9G2q8LoXSlEniSbav+yuU4zGeeruD00lszZ
      VoG4ZHRNiYzR;
   Received: from dsl-10.2.3.4.network.example.com  [10.2.3.4]
        by submitserver.example.com with SUBMISSION;
        Fri, 11 Jul 2003 21:01:54 -0700 (PDT)
   From: "Joe SixPack" <joe@football.example.com>
   To: "Suzie Q" <suzie@shopping.example.net>
   Subject: Is dinner ready?
   Date: Fri, 11 Jul 2003 21:00:37 -0700 (PDT)
   Message-ID: <20030712040037.46341.5F8J@football.example.com>

   Hi.

   We lost the game. Are you hungry yet?

   Joe.







Delany                          Historic                       [Page 30]

RFC 4870                       DomainKeys                       May 2007


5.  Association with a Certificate Authority

   A fundamental aspect of DomainKeys is that public keys are generated
   and advertised by each domain at no additional cost.  This
   accessibility markedly differs from traditional Public Key
   Infrastructures where there is typically a Certificate Authority (CA)
   who validates an applicant and issues a signed certificate --
   containing their public key -- often for a recurring fee.

   While CAs do impose costs, they also have the potential to provide
   additional value as part of their certification process.  Consider
   financial institutions, public utilities, law enforcement agencies,
   and the like.  In many cases, such entities justifiably need to
   discriminate themselves above and beyond the authentication that
   DomainKeys offers.

   Creating a link between DomainKeys and CA-issued certificates has the
   potential to access additional authentication mechanisms that are
   more authoritative than domain-owner-issued authentication.  It is
   well beyond the scope of this specification to describe such
   authorities apart from defining how the linkage could be achieved
   with the "DomainKey-X509:" header.

5.1.  The "DomainKey-X509:" Header

   The "DomainKey-X509:" header provides a link between the public key
   used to sign the email and the certificate issued by a CA.

   The exact content, syntax, and semantics of this header are yet to be
   resolved.  One possibility is that this header contains an encoding
   of the certificate issued by a CA.  Another possibility is that this
   header contains a URL that points to a certificate issued by a CA.

   In either case, this header can only be consulted if the signature
   verifies and MUST be part of the content signed by the corresponding
   "DomainKey-Signature:" header.  Furthermore, it is likely that MUAs
   rather than MTAs will confirm that the link to the CA-issued
   certificate is valid.  In part, this is because many MUAs already
   have built-in capabilities as a consequence of Secure/Multipurpose
   Internet Mail Extensions (S/MIME) [SMIME] and Secure Socket Layer
   (SSL) [SSL] support.

   The proof of linkage is made by testing that the public key in the
   certificate matches the public key used to sign the email.







Delany                          Historic                       [Page 31]

RFC 4870                       DomainKeys                       May 2007


   An example of an email containing the "DomainKey-X509:" header is:

      DomainKey-Signature: a=rsa-sha1; s=statements;
        d=largebank.example.com; c=simple; q=dns;
        b=dzdVyOfAKCdLXdJOc9G2q8LoXSlEniSbav+yuU4zGeeruD00lszZ
          VoG4ZHRNiYzR;
      DomainKey-X509: https://ca.example.net/largebank.example.com
      From: "Large Bank" <statements@largebank.example.com>
      To: "Suzie Q" <suzie@shopping.example.net>
      Subject: Statement for Account: 1234-5678
      ...

   The format of the retrieved value from the URL is not yet defined,
   nor is the determination of valid CAs.

   The whole matter of linkage to CA-issued certificates is one aspect
   of DomainKeys that needs to be resolved with relevant CA's and
   certificate-issuing entities.  The primary point is that a link is
   possible to a higher authority.

6.  Topics for Discussion

6.1.  The Benefits of Selectors

   Selectors are at the heart of the flexibility of DomainKeys.  A
   domain administrator is free to use a single DomainKey for all
   outbound mail.  Alternatively, the domain administrator may use many
   DomainKeys differentiated by selector and assign each key to
   different servers.

   For example, a large outbound email farm might have a unique
   DomainKey for each server, and thus their DNS will advertise
   potentially hundreds of keys via their unique selectors.

   Another example is a corporate email administrator who might generate
   a separate DomainKey for each regional office email server.

   In essence, selectors allow a domain owner to distribute authority to
   send on behalf of that domain.  Combined with the ability to revoke
   by removal or Time to Live (TTL) expiration, a domain owner has
   coarse-grained control over the duration of the distributed
   authority.

   Selectors are particularly useful for domain owners who want to
   contract a third-party mailing system to send a particular set of
   mail.  The domain owner can generate a special key pair and selector
   just for this mail-out.  The domain owner has to provide the private
   key and selector to the third party for the life of the mail-out.



Delany                          Historic                       [Page 32]

RFC 4870                       DomainKeys                       May 2007


   However, as soon as the mail-out is completely delivered, the domain
   owner can revoke the public key by the simple expedient of removing
   the entry from the DNS.

6.2.  Canonicalization of Email

   It is an unfortunate fact that some email software routinely (and
   often unnecessarily) transforms email as it transits through the
   network.  Such transformations conflict with the fundamental purpose
   of cryptographic signatures - to detect modifications.

   While two canonicalization algorithms are defined in this
   specification, the primary goal of "nofws" is to provide a transition
   path to "simple".  With a mixture of "simple" and "nofws" email, a
   receiver can determine which systems are modifying email in ways that
   cause the signature to fail and thus provide feedback to the
   modifying system.

6.3.  Mailing Lists

   Integrating existing Mailing List Managers (MLMs) into the DomainKeys
   authentication system is a complicated area, as the behavior of MLMs
   is highly variable.  Essentially, there are two types of MLMs under
   consideration: those that modify email to such an extent that
   verification of the original content is not possible, and those that
   make minimal or no modifications to an email.

   MLMs that modify email in a way that causes verification to fail MUST
   prepend a "Sender:" header and SHOULD prepend a "List-ID:"  header
   prior to signing for distribution to list recipients.

   A participating SUBMISSION server can deduce the need to re-sign such
   an email by the presence of a "Sender:" or "List-ID:" header from an
   authorized submission.

   MLMs that do not modify email in a way that causes verification to
   fail MAY perform the same actions as a modifying MLM.

6.4.  Roving Users

   One scenario that presents a particular problem with any form of
   email authentication, including DomainKeys, is the roving user: a
   user who is obliged to use a third-party SUBMISSION service when
   unable to connect to the user's own SUBMISSION service.  The classic
   example cited is a traveling salesperson being redirected to a hotel
   email server to send email.





Delany                          Historic                       [Page 33]

RFC 4870                       DomainKeys                       May 2007


   As far as DomainKeys is concerned, email of this nature clearly
   originates from an email server that does not have authority to send
   on behalf of the domain of the salesperson and is therefore
   indistinguishable from a forgery.  While DomainKeys does not
   prescribe any specific action for such email, it is likely that over
   time, such email will be treated as second-class email.

   The typical solution offered to roving users is to submit email via
   an authorized server for their domain -- perhaps via a Virtual
   Private Network (VPN) or a web interface or even SMTP AUTH back to a
   SUBMISSION server.

   While these are perfectly acceptable solutions for many, they are not
   necessarily solutions that are available or possible for all such
   users.

   One possible way to address the needs of this contingent of
   potentially disenfranchised users is for the domain to issue per-user
   DomainKeys.  Per-user DomainKeys are identified by a non-empty "g"
   tag value in the corresponding DNS record.

7.  Security Considerations

7.1.  DNS

   DomainKeys is primarily a security mechanism.  Its core purpose is to
   make claims about email authentication in a credible way.  However,
   DomainKeys, like virtually all Internet applications, relies on the
   DNS, which has well-known security flaws [RFC3833].

7.1.1.  The DNS Is Not Currently Secure

   While the DNS is currently insecure, it is expected that the security
   problems should and will be solved by DNS Security (DNSSEC) [DNSSEC],
   and all users of the DNS will reap the benefit of that work.

   Secondly, the types of DNS attacks relevant to DomainKeys are very
   costly and are far less rewarding than DNS attacks on other Internet
   applications.

   To systematically thwart the intent of DomainKeys, an attacker must
   conduct a very costly and very extensive attack on many parts of the
   DNS over an extended period.  No one knows for sure how attackers
   will respond; however, the cost/benefit of conducting prolonged DNS
   attacks of this nature is expected to be uneconomical.

   Finally, DomainKeys is only intended as a "sufficient" method of
   proving authenticity.  It is not intended to provide strong



Delany                          Historic                       [Page 34]

RFC 4870                       DomainKeys                       May 2007


   cryptographic proof about authorship or contents.  Other technologies
   such as GnuPG and S/MIME address those requirements.

7.1.2.  DomainKeys Creates Additional DNS Load

   A second security issue related to the DNS revolves around the
   increased DNS traffic as a consequence of fetching selector-based
   data, as well as fetching sending domain policy.  Widespread
   deployment of DomainKeys will result in a significant increase in DNS
   queries to the claimed sending domain.  In the case of forgeries on a
   large scale, DNS servers could see a substantial increase in queries.

7.2.  Key Management

   All public key systems require management of key pairs.  Private keys
   in particular need to be securely distributed to each signing mail
   server and protected on those servers.  For those familiar with SSL,
   the key management issues are similar to those of managing SSL
   certificates.  Poor key management may result in unauthorized access
   to private keys, which in essence gives unauthorized access to your
   identity.

7.3.  Implementation Risks

   It is well recognized in cryptographic circles that many security
   failures are caused by poor implementations rather than poor
   algorithms.  For example, early SSL implementations were vulnerable
   because the implementors used predictable "random numbers".

   While some MTA software already supports various cryptographic
   techniques, such as TLS, many do not.  This proposal introduces
   cryptographic requirements into MTA software that implies a much
   higher duty of care to manage the increased risk.

   There are numerous articles, books, courses, and consultants that
   help programming security applications.  Potential implementors are
   strongly encouraged to avail themselves of all possible resources to
   ensure secure implementations.

7.4.  Privacy Assumptions with Forwarding Addresses

   Some people believe that they can achieve anonymity by using an email
   forwarding service.  While this has never been particularly true, as
   bounces, over-quota messages, vacation messages, and web bugs all
   conspire to expose IP addresses and domain names associated with the
   delivery path, the DNS queries that are required to verify DomainKeys
   signature can provide additional information to the sender.




Delany                          Historic                       [Page 35]

RFC 4870                       DomainKeys                       May 2007


   In particular, as mail is forwarded through the mail network, the DNS
   queries for the selector will typically identify the DNS cache used
   by the forwarding and delivery MTAs.

7.5.  Cryptographic Processing Is Computationally Intensive

   Verifying a signature is computationally significant.  Early
   indications are that a typical mail server can expect to increase CPU
   demands by 8-15 percent.  While this increased demand is modest
   compared to other common mail processing costs -- such as Bayesian
   filtering -- any increase in resource requirements can make a
   denial-of-service attack more effective against a mail system.

   A constraining factor of such attacks is that the net computational
   cost of verifying is bounded by the maximum key size allowed by this
   specification and is essentially linear to the rate at which mail is
   accepted by the verifying system.  Consequently, the additional
   computational cost may augment a denial-of-service attack, but it
   does not add a non-linear component to such attacks.

8.  The Trial

   The DomainKeys protocol was deployed as a trial to better understand
   the implications of deploying wide-scale cryptographic email
   authentication.

   Open Source implementations were made available at various places,
   particularly Source Forge [SOURCEFORGE], which includes links to
   numerous implementations, both Open Source and commercial.

8.1.  Goals

   The primary goals of the trial were to:

      o  understand the operational implications of running a DNS-based
         public key system for email

      o  measure the effectiveness of the canonicalization algorithms

      o  experiment with possible per-user key deployment models

      o  fully define the semantics of the "DomainKey-X509:" header









Delany                          Historic                       [Page 36]

RFC 4870                       DomainKeys                       May 2007


8.2.  Results of Trial

   The DomainKeys trial ran for approximately 2 years, in which time
   numerous large ISPs and many thousands of smaller domains
   participated in signing or verifying with DomainKeys.  The low order
   numbers are that at least one billion DomainKey signed emails transit
   the Internet each day between some 12,000 participating domains.

   The operational and development experience of that trial was applied
   to DKIM.

9.  Note to Implementors Regarding TXT Records

   The DNS is very flexible in that it is possible to have multiple TXT
   records for a single name and for those TXT records to contain
   multiple strings.

   In all cases, implementors of DomainKeys should expect a single TXT
   record for any particular name.  If multiple TXT records are
   returned, the implementation is free to pick any single TXT record as
   the authoritative data.  In other words, if a name server returns
   different TXT records for the same name, it can expect unpredictable
   results.

   Within a single TXT record, implementors should concatenate multiple
   strings in the order presented and ignore string boundaries.  Note
   that a number of popular DNS command-line tools render multiple
   strings as separately quoted strings, which can be misleading to a
   novice implementor.

10.  References

10.1.  Normative References

   [BASE64]      Josefsson, S., "The Base16, Base32, and Base64 Data
                 Encodings", RFC 4648, October 2006.

   [RFC2119]     Bradner, S., "Key words for use in RFCs to Indicate
                 Requirement Levels", BCP 14, RFC 2119, March 1997.

   [PEM]         Linn, J., "Privacy Enhancement for Internet Electronic
                 Mail: Part I: Message Encryption and Authentication
                 Procedures", RFC 1421 February, 1993.








Delany                          Historic                       [Page 37]

RFC 4870                       DomainKeys                       May 2007


10.2.  Informative References

   [DKIM]        Allman, E., Callas, J., Delany, M., Libbey, M., Fenton,
                 J., and M. Thomas, "DomainKeys Identified Mail (DKIM)
                 Signatures", RFC 4871, May 2007.

   [DNSSEC]      http://www.ietf.org/html.charters/dnsext-charter.html

   [OPENSSL]     http://www.openssl.org

   [RFC2822]     Resnick, P., Editor, "Internet Message Format", RFC
                               2822, April 2001.

   [RFC3833]     Atkins, D. and R. Austein, "Threat Analysis of the
                 Domain Name System (DNS)", RFC 3833, August 2004.

   [SMIME]       Ramsdell, B., Ed., "Secure/Multipurpose Internet Mail
                 Extensions (S/MIME) Version 3.1 Message Specification",
                 RFC 3851, July 2004.

   [SOURCEFORGE] http://domainkeys.sourceforge.net

   [SSL]         http://wp.netscape.com/security/techbriefs/ssl.html




























Delany                          Historic                       [Page 38]

RFC 4870                       DomainKeys                       May 2007


Appendix A - Syntax Rules for the Tag=Value Format

   A simple tag=value syntax is used to encode data in the response
   values for DNS queries as well as headers embedded in emails.  This
   section summarized the syntactic rules for this encoding:

      o  A tag=value pair consists of three tokens, a "tag", the "="
         character, and the "value"

      o  A tag MUST be one character long and MUST be a lowercase
         alphabetic character

      o  Duplicate tags are not allowed

      o  A value MUST only consist of characters that are valid in RFC
         2822 headers and DNS TXT records and are within the ASCII range
         of characters from SPACE (0x20) to TILDE (0x7E) inclusive.
         Values MUST NOT contain a semicolon but they may contain "="
         characters.

      o  A tag=value pair MUST be terminated by a semicolon or the end
         of the data

      o  Values MUST be processed as case sensitive unless the specific
         tag description of semantics imply case insensitivity.

      o  Values MAY be zero bytes long

      o  Whitespace MAY surround any of the tokens; however, whitespace
         within a value MUST be retained unless explicitly excluded by
         the specific tag description.  Currently, the only tags that
         specifically ignore embedded whitespace are the "b" and "h"
         tags in the "DomainKey-Signature:" header.

      o  Tag=value pairs that represent the default value MAY be
         included to aid legibility.

      o  Unrecognized tags MUST be ignored













Delany                          Historic                       [Page 39]

RFC 4870                       DomainKeys                       May 2007


Acknowledgments

   The editor wishes to thank Russ Allbery, Eric Allman, Edwin Aoki,
   Claus Asmann, Steve Atkins, Jon Callas, Dave Crocker, Michael Cudahy,
   Jutta Degener, Timothy Der, Jim Fenton, Duncan Findlay, Phillip
   Hallam-Baker, Murray S. Kucherawy, John Levine, Miles Libbey, David
   Margrave, Justin Mason, David Mayne, Russell Nelson, Juan Altmayer
   Pizzorno, Blake Ramsdell, Scott Renfro, the Spamhaus.org team, Malte
   S. Stretz, Robert Sanders, Bradley Taylor, and Rand Wacker for their
   valuable suggestions and constructive criticism.

Author's Address

   Mark Delany
   Yahoo! Inc
   701 First Avenue
   Sunnyvale, CA 95087
   USA

   EMail: markd+domainkeys@yahoo-inc.com































Delany                          Historic                       [Page 40]

RFC 4870                       DomainKeys                       May 2007


Full Copyright Statement

   Copyright (C) The IETF Trust (2007).

   This document is subject to the rights, licenses and restrictions
   contained in BCP 78, and except as set forth therein, the authors
   retain all their rights.

   This document and the information contained herein are provided on an
   "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
   OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND
   THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS
   OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
   THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
   WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Intellectual Property

   The IETF takes no position regarding the validity or scope of any
   Intellectual Property Rights or other rights that might be claimed to
   pertain to the implementation or use of the technology described in
   this document or the extent to which any license under such rights
   might or might not be available; nor does it represent that it has
   made any independent effort to identify any such rights.  Information
   on the procedures with respect to rights in RFC documents can be
   found in BCP 78 and BCP 79.

   Copies of IPR disclosures made to the IETF Secretariat and any
   assurances of licenses to be made available, or the result of an
   attempt made to obtain a general license or permission for the use of
   such proprietary rights by implementers or users of this
   specification can be obtained from the IETF on-line IPR repository at
   http://www.ietf.org/ipr.

   The IETF invites any interested party to bring to its attention any
   copyrights, patents or patent applications, or other proprietary
   rights that may cover technology that may be required to implement
   this standard.  Please address the information to the IETF at
   ietf-ipr@ietf.org.

Acknowledgement

   Funding for the RFC Editor function is currently provided by the
   Internet Society.







Delany                          Historic                       [Page 41]



================================================
FILE: doc/notes/rfc/rfc4871.txt
================================================






Network Working Group                                          E. Allman
Request for Comments: 4871                                Sendmail, Inc.
Obsoletes: 4870                                                J. Callas
Category: Standards Track                                PGP Corporation
                                                               M. Delany
                                                               M. Libbey
                                                              Yahoo! Inc
                                                               J. Fenton
                                                               M. Thomas
                                                     Cisco Systems, Inc.
                                                                May 2007


              DomainKeys Identified Mail (DKIM) Signatures

Status of This Memo

   This document specifies an Internet standards track protocol for the
   Internet community, and requests discussion and suggestions for
   improvements.  Please refer to the current edition of the "Internet
   Official Protocol Standards" (STD 1) for the standardization state
   and status of this protocol.  Distribution of this memo is unlimited.

Copyright Notice

   Copyright (C) The IETF Trust (2007).

Abstract

   DomainKeys Identified Mail (DKIM) defines a domain-level
   authentication framework for email using public-key cryptography and
   key server technology to permit verification of the source and
   contents of messages by either Mail Transfer Agents (MTAs) or Mail
   User Agents (MUAs).  The ultimate goal of this framework is to permit
   a signing domain to assert responsibility for a message, thus
   protecting message signer identity and the integrity of the messages
   they convey while retaining the functionality of Internet email as it
   is known today.  Protection of email identity may assist in the
   global control of "spam" and "phishing".












Allman, et al.              Standards Track                     [Page 1]

RFC 4871                    DKIM Signatures                     May 2007


Table of Contents

   1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  4
     1.1.  Signing Identity . . . . . . . . . . . . . . . . . . . . .  5
     1.2.  Scalability  . . . . . . . . . . . . . . . . . . . . . . .  5
     1.3.  Simple Key Management  . . . . . . . . . . . . . . . . . .  5
   2.  Terminology and Definitions  . . . . . . . . . . . . . . . . .  5
     2.1.  Signers  . . . . . . . . . . . . . . . . . . . . . . . . .  6
     2.2.  Verifiers  . . . . . . . . . . . . . . . . . . . . . . . .  6
     2.3.  Whitespace . . . . . . . . . . . . . . . . . . . . . . . .  6
     2.4.  Common ABNF Tokens . . . . . . . . . . . . . . . . . . . .  6
     2.5.  Imported ABNF Tokens . . . . . . . . . . . . . . . . . . .  7
     2.6.  DKIM-Quoted-Printable  . . . . . . . . . . . . . . . . . .  7
   3.  Protocol Elements  . . . . . . . . . . . . . . . . . . . . . .  8
     3.1.  Selectors  . . . . . . . . . . . . . . . . . . . . . . . .  8
     3.2.  Tag=Value Lists  . . . . . . . . . . . . . . . . . . . . . 10
     3.3.  Signing and Verification Algorithms  . . . . . . . . . . . 11
     3.4.  Canonicalization . . . . . . . . . . . . . . . . . . . . . 13
     3.5.  The DKIM-Signature Header Field  . . . . . . . . . . . . . 17
     3.6.  Key Management and Representation  . . . . . . . . . . . . 25
     3.7.  Computing the Message Hashes . . . . . . . . . . . . . . . 29
     3.8.  Signing by Parent Domains  . . . . . . . . . . . . . . . . 31
   4.  Semantics of Multiple Signatures . . . . . . . . . . . . . . . 32
     4.1.  Example Scenarios  . . . . . . . . . . . . . . . . . . . . 32
     4.2.  Interpretation . . . . . . . . . . . . . . . . . . . . . . 33
   5.  Signer Actions . . . . . . . . . . . . . . . . . . . . . . . . 34
     5.1.  Determine Whether the Email Should Be Signed and by
           Whom . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
     5.2.  Select a Private Key and Corresponding Selector
           Information  . . . . . . . . . . . . . . . . . . . . . . . 35
     5.3.  Normalize the Message to Prevent Transport Conversions . . 35
     5.4.  Determine the Header Fields to Sign  . . . . . . . . . . . 36
     5.5.  Recommended Signature Content  . . . . . . . . . . . . . . 38
     5.6.  Compute the Message Hash and Signature . . . . . . . . . . 39
     5.7.  Insert the DKIM-Signature Header Field . . . . . . . . . . 40
   6.  Verifier Actions . . . . . . . . . . . . . . . . . . . . . . . 40
     6.1.  Extract Signatures from the Message  . . . . . . . . . . . 41
     6.2.  Communicate Verification Results . . . . . . . . . . . . . 46
     6.3.  Interpret Results/Apply Local Policy . . . . . . . . . . . 47
   7.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . . 48
     7.1.  DKIM-Signature Tag Specifications  . . . . . . . . . . . . 48
     7.2.  DKIM-Signature Query Method Registry . . . . . . . . . . . 49
     7.3.  DKIM-Signature Canonicalization Registry . . . . . . . . . 49
     7.4.  _domainkey DNS TXT Record Tag Specifications . . . . . . . 50
     7.5.  DKIM Key Type Registry . . . . . . . . . . . . . . . . . . 50
     7.6.  DKIM Hash Algorithms Registry  . . . . . . . . . . . . . . 51
     7.7.  DKIM Service Types Registry  . . . . . . . . . . . . . . . 51
     7.8.  DKIM Selector Flags Registry . . . . . . . . . . . . . . . 52



Allman, et al.              Standards Track                     [Page 2]

RFC 4871                    DKIM Signatures                     May 2007


     7.9.  DKIM-Signature Header Field  . . . . . . . . . . . . . . . 52
   8.  Security Considerations  . . . . . . . . . . . . . . . . . . . 52
     8.1.  Misuse of Body Length Limits ("l=" Tag)  . . . . . . . . . 52
     8.2.  Misappropriated Private Key  . . . . . . . . . . . . . . . 53
     8.3.  Key Server Denial-of-Service Attacks . . . . . . . . . . . 54
     8.4.  Attacks Against the DNS  . . . . . . . . . . . . . . . . . 54
     8.5.  Replay Attacks . . . . . . . . . . . . . . . . . . . . . . 55
     8.6.  Limits on Revoking Keys  . . . . . . . . . . . . . . . . . 55
     8.7.  Intentionally Malformed Key Records  . . . . . . . . . . . 56
     8.8.  Intentionally Malformed DKIM-Signature Header Fields . . . 56
     8.9.  Information Leakage  . . . . . . . . . . . . . . . . . . . 56
     8.10. Remote Timing Attacks  . . . . . . . . . . . . . . . . . . 56
     8.11. Reordered Header Fields  . . . . . . . . . . . . . . . . . 56
     8.12. RSA Attacks  . . . . . . . . . . . . . . . . . . . . . . . 56
     8.13. Inappropriate Signing by Parent Domains  . . . . . . . . . 57
   9.  References . . . . . . . . . . . . . . . . . . . . . . . . . . 57
     9.1.  Normative References . . . . . . . . . . . . . . . . . . . 57
     9.2.  Informative References . . . . . . . . . . . . . . . . . . 58
   Appendix A.  Example of Use (INFORMATIVE)  . . . . . . . . . . . . 60
     A.1.  The user composes an email . . . . . . . . . . . . . . . . 60
     A.2.  The email is signed  . . . . . . . . . . . . . . . . . . . 61
     A.3.  The email signature is verified  . . . . . . . . . . . . . 61
   Appendix B.  Usage Examples (INFORMATIVE)  . . . . . . . . . . . . 62
     B.1.  Alternate Submission Scenarios . . . . . . . . . . . . . . 63
     B.2.  Alternate Delivery Scenarios . . . . . . . . . . . . . . . 65
   Appendix C.  Creating a Public Key (INFORMATIVE) . . . . . . . . . 67
   Appendix D.  MUA Considerations  . . . . . . . . . . . . . . . . . 68
   Appendix E.  Acknowledgements  . . . . . . . . . . . . . . . . . . 69























Allman, et al.              Standards Track                     [Page 3]

RFC 4871                    DKIM Signatures                     May 2007


1.  Introduction

   DomainKeys Identified Mail (DKIM) defines a mechanism by which email
   messages can be cryptographically signed, permitting a signing domain
   to claim responsibility for the introduction of a message into the
   mail stream.  Message recipients can verify the signature by querying
   the signer's domain directly to retrieve the appropriate public key,
   and thereby confirm that the message was attested to by a party in
   possession of the private key for the signing domain.

   The approach taken by DKIM differs from previous approaches to
   message signing (e.g., Secure/Multipurpose Internet Mail Extensions
   (S/MIME) [RFC1847], OpenPGP [RFC2440]) in that:

   o  the message signature is written as a message header field so that
      neither human recipients nor existing MUA (Mail User Agent)
      software is confused by signature-related content appearing in the
      message body;

   o  there is no dependency on public and private key pairs being
      issued by well-known, trusted certificate authorities;

   o  there is no dependency on the deployment of any new Internet
      protocols or services for public key distribution or revocation;

   o  signature verification failure does not force rejection of the
      message;

   o  no attempt is made to include encryption as part of the mechanism;

   o  message archiving is not a design goal.

   DKIM:

   o  is compatible with the existing email infrastructure and
      transparent to the fullest extent possible;

   o  requires minimal new infrastructure;

   o  can be implemented independently of clients in order to reduce
      deployment time;

   o  can be deployed incrementally;

   o  allows delegation of signing to third parties.






Allman, et al.              Standards Track                     [Page 4]

RFC 4871                    DKIM Signatures                     May 2007


1.1.  Signing Identity

   DKIM separates the question of the identity of the signer of the
   message from the purported author of the message.  In particular, a
   signature includes the identity of the signer.  Verifiers can use the
   signing information to decide how they want to process the message.
   The signing identity is included as part of the signature header
   field.

      INFORMATIVE RATIONALE: The signing identity specified by a DKIM
      signature is not required to match an address in any particular
      header field because of the broad methods of interpretation by
      recipient mail systems, including MUAs.

1.2.  Scalability

   DKIM is designed to support the extreme scalability requirements that
   characterize the email identification problem.  There are currently
   over 70 million domains and a much larger number of individual
   addresses.  DKIM seeks to preserve the positive aspects of the
   current email infrastructure, such as the ability for anyone to
   communicate with anyone else without introduction.

1.3.  Simple Key Management

   DKIM differs from traditional hierarchical public-key systems in that
   no Certificate Authority infrastructure is required; the verifier
   requests the public key from a repository in the domain of the
   claimed signer directly rather than from a third party.

   The DNS is proposed as the initial mechanism for the public keys.
   Thus, DKIM currently depends on DNS administration and the security
   of the DNS system.  DKIM is designed to be extensible to other key
   fetching services as they become available.

2.  Terminology and Definitions

   This section defines terms used in the rest of the document.  Syntax
   descriptions use the form described in Augmented BNF for Syntax
   Specifications [RFC4234].

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in [RFC2119].







Allman, et al.              Standards Track                     [Page 5]

RFC 4871                    DKIM Signatures                     May 2007


2.1.  Signers

   Elements in the mail system that sign messages on behalf of a domain
   are referred to as signers.  These may be MUAs (Mail User Agents),
   MSAs (Mail Submission Agents), MTAs (Mail Transfer Agents), or other
   agents such as mailing list exploders.  In general, any signer will
   be involved in the injection of a message into the message system in
   some way.  The key issue is that a message must be signed before it
   leaves the administrative domain of the signer.

2.2.  Verifiers

   Elements in the mail system that verify signatures are referred to as
   verifiers.  These may be MTAs, Mail Delivery Agents (MDAs), or MUAs.
   In most cases it is expected that verifiers will be close to an end
   user (reader) of the message or some consuming agent such as a
   mailing list exploder.

2.3.  Whitespace

   There are three forms of whitespace:

   o  WSP represents simple whitespace, i.e., a space or a tab character
      (formal definition in [RFC4234]).

   o  LWSP is linear whitespace, defined as WSP plus CRLF (formal
      definition in [RFC4234]).

   o  FWS is folding whitespace.  It allows multiple lines separated by
      CRLF followed by at least one whitespace, to be joined.

   The formal ABNF for these are (WSP and LWSP are given for information
   only):

       WSP =   SP / HTAB
       LWSP =  *(WSP / CRLF WSP)
       FWS =   [*WSP CRLF] 1*WSP

   The definition of FWS is identical to that in [RFC2822] except for
   the exclusion of obs-FWS.

2.4.  Common ABNF Tokens

   The following ABNF tokens are used elsewhere in this document:
     hyphenated-word =  ALPHA [ *(ALPHA / DIGIT / "-") (ALPHA / DIGIT) ]
     base64string =     1*(ALPHA / DIGIT / "+" / "/" / [FWS])
                        [ "=" [FWS] [ "=" [FWS] ] ]




Allman, et al.              Standards Track                     [Page 6]

RFC 4871                    DKIM Signatures                     May 2007


2.5.  Imported ABNF Tokens

   The following tokens are imported from other RFCs as noted.  Those
   RFCs should be considered definitive.

   The following tokens are imported from [RFC2821]:

   o  "Local-part" (implementation warning: this permits quoted strings)

   o  "sub-domain"

   The following tokens are imported from [RFC2822]:

   o  "field-name" (name of a header field)

   o  "dot-atom-text" (in the Local-part of an email address)

   The following tokens are imported from [RFC2045]:

   o  "qp-section" (a single line of quoted-printable-encoded text)

   o  "hex-octet" (a quoted-printable encoded octet)

      INFORMATIVE NOTE: Be aware that the ABNF in RFC 2045 does not obey
      the rules of RFC 4234 and must be interpreted accordingly,
      particularly as regards case folding.

   Other tokens not defined herein are imported from [RFC4234].  These
   are intuitive primitives such as SP, HTAB, WSP, ALPHA, DIGIT, CRLF,
   etc.

2.6.  DKIM-Quoted-Printable

   The DKIM-Quoted-Printable encoding syntax resembles that described in
   Quoted-Printable [RFC2045], Section 6.7: any character MAY be encoded
   as an "=" followed by two hexadecimal digits from the alphabet
   "0123456789ABCDEF" (no lowercase characters permitted) representing
   the hexadecimal-encoded integer value of that character.  All control
   characters (those with values < %x20), 8-bit characters (values >
   %x7F), and the characters DEL (%x7F), SPACE (%x20), and semicolon
   (";", %x3B) MUST be encoded.  Note that all whitespace, including
   SPACE, CR, and LF characters, MUST be encoded.  After encoding, FWS
   MAY be added at arbitrary locations in order to avoid excessively
   long lines; such whitespace is NOT part of the value, and MUST be
   removed before decoding.






Allman, et al.              Standards Track                     [Page 7]

RFC 4871                    DKIM Signatures                     May 2007


   ABNF:

       dkim-quoted-printable =
                          *(FWS / hex-octet / dkim-safe-char)
                     ; hex-octet is from RFC 2045
       dkim-safe-char =   %x21-3A / %x3C / %x3E-7E
                     ; '!' - ':', '<', '>' - '~'
                     ; Characters not listed as "mail-safe" in
                     ; RFC 2049 are also not recommended.

      INFORMATIVE NOTE: DKIM-Quoted-Printable differs from Quoted-
      Printable as defined in RFC 2045 in several important ways:

      1.  Whitespace in the input text, including CR and LF, must be
          encoded.  RFC 2045 does not require such encoding, and does
          not permit encoding of CR or LF characters that are part of a
          CRLF line break.

      2.  Whitespace in the encoded text is ignored.  This is to allow
          tags encoded using DKIM-Quoted-Printable to be wrapped as
          needed.  In particular, RFC 2045 requires that line breaks in
          the input be represented as physical line breaks; that is not
          the case here.

      3.  The "soft line break" syntax ("=" as the last non-whitespace
          character on the line) does not apply.

      4.  DKIM-Quoted-Printable does not require that encoded lines be
          no more than 76 characters long (although there may be other
          requirements depending on the context in which the encoded
          text is being used).

3.  Protocol Elements

   Protocol Elements are conceptual parts of the protocol that are not
   specific to either signers or verifiers.  The protocol descriptions
   for signers and verifiers are described in later sections (Signer
   Actions (Section 5) and Verifier Actions (Section 6)).  NOTE: This
   section must be read in the context of those sections.

3.1.  Selectors

   To support multiple concurrent public keys per signing domain, the
   key namespace is subdivided using "selectors".  For example,
   selectors might indicate the names of office locations (e.g.,
   "sanfrancisco", "coolumbeach", and "reykjavik"), the signing date
   (e.g., "january2005", "february2005", etc.), or even the individual
   user.



Allman, et al.              Standards Track                     [Page 8]

RFC 4871                    DKIM Signatures                     May 2007


   Selectors are needed to support some important use cases.  For
   example:

   o  Domains that want to delegate signing capability for a specific
      address for a given duration to a partner, such as an advertising
      provider or other outsourced function.

   o  Domains that want to allow frequent travelers to send messages
      locally without the need to connect with a particular MSA.

   o  "Affinity" domains (e.g., college alumni associations) that
      provide forwarding of incoming mail, but that do not operate a
      mail submission agent for outgoing mail.

   Periods are allowed in selectors and are component separators.  When
   keys are retrieved from the DNS, periods in selectors define DNS
   label boundaries in a manner similar to the conventional use in
   domain names.  Selector components might be used to combine dates
   with locations, for example, "march2005.reykjavik".  In a DNS
   implementation, this can be used to allow delegation of a portion of
   the selector namespace.

   ABNF:

      selector =   sub-domain *( "." sub-domain )

   The number of public keys and corresponding selectors for each domain
   is determined by the domain owner.  Many domain owners will be
   satisfied with just one selector, whereas administratively
   distributed organizations may choose to manage disparate selectors
   and key pairs in different regions or on different email servers.

   Beyond administrative convenience, selectors make it possible to
   seamlessly replace public keys on a routine basis.  If a domain
   wishes to change from using a public key associated with selector
   "january2005" to a public key associated with selector
   "february2005", it merely makes sure that both public keys are
   advertised in the public-key repository concurrently for the
   transition period during which email may be in transit prior to
   verification.  At the start of the transition period, the outbound
   email servers are configured to sign with the "february2005" private
   key.  At the end of the transition period, the "january2005" public
   key is removed from the public-key repository.

      INFORMATIVE NOTE: A key may also be revoked as described below.
      The distinction between revoking and removing a key selector
      record is subtle.  When phasing out keys as described above, a
      signing domain would probably simply remove the key record after



Allman, et al.              Standards Track                     [Page 9]

RFC 4871                    DKIM Signatures                     May 2007


      the transition period.  However, a signing domain could elect to
      revoke the key (but maintain the key record) for a further period.
      There is no defined semantic difference between a revoked key and
      a removed key.

   While some domains may wish to make selector values well known,
   others will want to take care not to allocate selector names in a way
   that allows harvesting of data by outside parties.  For example, if
   per-user keys are issued, the domain owner will need to make the
   decision as to whether to associate this selector directly with the
   user name, or make it some unassociated random value, such as a
   fingerprint of the public key.

      INFORMATIVE OPERATIONS NOTE: Reusing a selector with a new key
      (for example, changing the key associated with a user's name)
      makes it impossible to tell the difference between a message that
      didn't verify because the key is no longer valid versus a message
      that is actually forged.  For this reason, signers are ill-advised
      to reuse selectors for new keys.  A better strategy is to assign
      new keys to new selectors.

3.2.  Tag=Value Lists

   DKIM uses a simple "tag=value" syntax in several contexts, including
   in messages and domain signature records.

   Values are a series of strings containing either plain text, "base64"
   text (as defined in [RFC2045], Section 6.8), "qp-section" (ibid,
   Section 6.7), or "dkim-quoted-printable" (as defined in Section 2.6).
   The name of the tag will determine the encoding of each value.
   Unencoded semicolon (";") characters MUST NOT occur in the tag value,
   since that separates tag-specs.

      INFORMATIVE IMPLEMENTATION NOTE: Although the "plain text" defined
      below (as "tag-value") only includes 7-bit characters, an
      implementation that wished to anticipate future standards would be
      advised not to preclude the use of UTF8-encoded text in tag=value
      lists.













Allman, et al.              Standards Track                    [Page 10]

RFC 4871                    DKIM Signatures                     May 2007


   Formally, the syntax rules are as follows:

        tag-list  =  tag-spec 0*( ";" tag-spec ) [ ";" ]
        tag-spec  =  [FWS] tag-name [FWS] "=" [FWS] tag-value [FWS]
        tag-name  =  ALPHA 0*ALNUMPUNC
        tag-value =  [ tval 0*( 1*(WSP / FWS) tval ) ]
                          ; WSP and FWS prohibited at beginning and end
        tval      =  1*VALCHAR
        VALCHAR   =  %x21-3A / %x3C-7E
                          ; EXCLAMATION to TILDE except SEMICOLON
        ALNUMPUNC =  ALPHA / DIGIT / "_"

   Note that WSP is allowed anywhere around tags.  In particular, any
   WSP after the "=" and any WSP before the terminating ";" is not part
   of the value; however, WSP inside the value is significant.

   Tags MUST be interpreted in a case-sensitive manner.  Values MUST be
   processed as case sensitive unless the specific tag description of
   semantics specifies case insensitivity.

   Tags with duplicate names MUST NOT occur within a single tag-list; if
   a tag name does occur more than once, the entire tag-list is invalid.

   Whitespace within a value MUST be retained unless explicitly excluded
   by the specific tag description.

   Tag=value pairs that represent the default value MAY be included to
   aid legibility.

   Unrecognized tags MUST be ignored.

   Tags that have an empty value are not the same as omitted tags.  An
   omitted tag is treated as having the default value; a tag with an
   empty value explicitly designates the empty string as the value.  For
   example, "g=" does not mean "g=*", even though "g=*" is the default
   for that tag.

3.3.  Signing and Verification Algorithms

   DKIM supports multiple digital signature algorithms.  Two algorithms
   are defined by this specification at this time: rsa-sha1 and rsa-
   sha256.  The rsa-sha256 algorithm is the default if no algorithm is
   specified.  Verifiers MUST implement both rsa-sha1 and rsa-sha256.
   Signers MUST implement and SHOULD sign using rsa-sha256.







Allman, et al.              Standards Track                    [Page 11]

RFC 4871                    DKIM Signatures                     May 2007


      INFORMATIVE NOTE: Although sha256 is strongly encouraged, some
      senders of low-security messages (such as routine newsletters) may
      prefer to use sha1 because of reduced CPU requirements to compute
      a sha1 hash.  In general, sha256 should always be used whenever
      possible.

3.3.1.  The rsa-sha1 Signing Algorithm

   The rsa-sha1 Signing Algorithm computes a message hash as described
   in Section 3.7 below using SHA-1 [FIPS.180-2.2002] as the hash-alg.
   That hash is then signed by the signer using the RSA algorithm
   (defined in PKCS#1 version 1.5 [RFC3447]) as the crypt-alg and the
   signer's private key.  The hash MUST NOT be truncated or converted
   into any form other than the native binary form before being signed.
   The signing algorithm SHOULD use a public exponent of 65537.

3.3.2.  The rsa-sha256 Signing Algorithm

   The rsa-sha256 Signing Algorithm computes a message hash as described
   in Section 3.7 below using SHA-256 [FIPS.180-2.2002] as the hash-alg.
   That hash is then signed by the signer using the RSA algorithm
   (defined in PKCS#1 version 1.5 [RFC3447]) as the crypt-alg and the
   signer's private key.  The hash MUST NOT be truncated or converted
   into any form other than the native binary form before being signed.

3.3.3.  Key Sizes

   Selecting appropriate key sizes is a trade-off between cost,
   performance, and risk.  Since short RSA keys more easily succumb to
   off-line attacks, signers MUST use RSA keys of at least 1024 bits for
   long-lived keys.  Verifiers MUST be able to validate signatures with
   keys ranging from 512 bits to 2048 bits, and they MAY be able to
   validate signatures with larger keys.  Verifier policies may use the
   length of the signing key as one metric for determining whether a
   signature is acceptable.

   Factors that should influence the key size choice include the
   following:

   o  The practical constraint that large (e.g., 4096 bit) keys may not
      fit within a 512-byte DNS UDP response packet

   o  The security constraint that keys smaller than 1024 bits are
      subject to off-line attacks

   o  Larger keys impose higher CPU costs to verify and sign email





Allman, et al.              Standards Track                    [Page 12]

RFC 4871                    DKIM Signatures                     May 2007


   o  Keys can be replaced on a regular basis, thus their lifetime can
      be relatively short

   o  The security goals of this specification are modest compared to
      typical goals of other systems that employ digital signatures

   See [RFC3766] for further discussion on selecting key sizes.

3.3.4.  Other Algorithms

   Other algorithms MAY be defined in the future.  Verifiers MUST ignore
   any signatures using algorithms that they do not implement.

3.4.  Canonicalization

   Empirical evidence demonstrates that some mail servers and relay
   systems modify email in transit, potentially invalidating a
   signature.  There are two competing perspectives on such
   modifications.  For most signers, mild modification of email is
   immaterial to the authentication status of the email.  For such
   signers, a canonicalization algorithm that survives modest in-transit
   modification is preferred.

   Other signers demand that any modification of the email, however
   minor, result in a signature verification failure.  These signers
   prefer a canonicalization algorithm that does not tolerate in-transit
   modification of the signed email.

   Some signers may be willing to accept modifications to header fields
   that are within the bounds of email standards such as [RFC2822], but
   are unwilling to accept any modification to the body of messages.

   To satisfy all requirements, two canonicalization algorithms are
   defined for each of the header and the body: a "simple" algorithm
   that tolerates almost no modification and a "relaxed" algorithm that
   tolerates common modifications such as whitespace replacement and
   header field line rewrapping.  A signer MAY specify either algorithm
   for header or body when signing an email.  If no canonicalization
   algorithm is specified by the signer, the "simple" algorithm defaults
   for both header and body.  Verifiers MUST implement both
   canonicalization algorithms.  Note that the header and body may use
   different canonicalization algorithms.  Further canonicalization
   algorithms MAY be defined in the future; verifiers MUST ignore any
   signatures that use unrecognized canonicalization algorithms.

   Canonicalization simply prepares the email for presentation to the
   signing or verification algorithm.  It MUST NOT change the




Allman, et al.              Standards Track                    [Page 13]

RFC 4871                    DKIM Signatures                     May 2007


   transmitted data in any way.  Canonicalization of header fields and
   body are described below.

   NOTE: This section assumes that the message is already in "network
   normal" format (text is ASCII encoded, lines are separated with CRLF
   characters, etc.).  See also Section 5.3 for information about
   normalizing the message.

3.4.1.  The "simple" Header Canonicalization Algorithm

   The "simple" header canonicalization algorithm does not change header
   fields in any way.  Header fields MUST be presented to the signing or
   verification algorithm exactly as they are in the message being
   signed or verified.  In particular, header field names MUST NOT be
   case folded and whitespace MUST NOT be changed.

3.4.2.  The "relaxed" Header Canonicalization Algorithm

   The "relaxed" header canonicalization algorithm MUST apply the
   following steps in order:

   o  Convert all header field names (not the header field values) to
      lowercase.  For example, convert "SUBJect: AbC" to "subject: AbC".

   o  Unfold all header field continuation lines as described in
      [RFC2822]; in particular, lines with terminators embedded in
      continued header field values (that is, CRLF sequences followed by
      WSP) MUST be interpreted without the CRLF.  Implementations MUST
      NOT remove the CRLF at the end of the header field value.

   o  Convert all sequences of one or more WSP characters to a single SP
      character.  WSP characters here include those before and after a
      line folding boundary.

   o  Delete all WSP characters at the end of each unfolded header field
      value.

   o  Delete any WSP characters remaining before and after the colon
      separating the header field name from the header field value.  The
      colon separator MUST be retained.

3.4.3.  The "simple" Body Canonicalization Algorithm

   The "simple" body canonicalization algorithm ignores all empty lines
   at the end of the message body.  An empty line is a line of zero
   length after removal of the line terminator.  If there is no body or
   no trailing CRLF on the message body, a CRLF is added.  It makes no




Allman, et al.              Standards Track                    [Page 14]

RFC 4871                    DKIM Signatures                     May 2007


   other changes to the message body.  In more formal terms, the
   "simple" body canonicalization algorithm converts "0*CRLF" at the end
   of the body to a single "CRLF".

   Note that a completely empty or missing body is canonicalized as a
   single "CRLF"; that is, the canonicalized length will be 2 octets.

3.4.4.  The "relaxed" Body Canonicalization Algorithm

   The "relaxed" body canonicalization algorithm:

   o  Ignores all whitespace at the end of lines.  Implementations MUST
      NOT remove the CRLF at the end of the line.

   o  Reduces all sequences of WSP within a line to a single SP
      character.

   o  Ignores all empty lines at the end of the message body.  "Empty
      line" is defined in Section 3.4.3.

      INFORMATIVE NOTE: It should be noted that the relaxed body
      canonicalization algorithm may enable certain types of extremely
      crude "ASCII Art" attacks where a message may be conveyed by
      adjusting the spacing between words.  If this is a concern, the
      "simple" body canonicalization algorithm should be used instead.

3.4.5.  Body Length Limits

   A body length count MAY be specified to limit the signature
   calculation to an initial prefix of the body text, measured in
   octets.  If the body length count is not specified, the entire
   message body is signed.

      INFORMATIVE RATIONALE: This capability is provided because it is
      very common for mailing lists to add trailers to messages (e.g.,
      instructions how to get off the list).  Until those messages are
      also signed, the body length count is a useful tool for the
      verifier since it may as a matter of policy accept messages having
      valid signatures with extraneous data.

      INFORMATIVE IMPLEMENTATION NOTE: Using body length limits enables
      an attack in which an attacker modifies a message to include
      content that solely benefits the attacker.  It is possible for the
      appended content to completely replace the original content in the
      end recipient's eyes and to defeat duplicate message detection
      algorithms.  To avoid this attack, signers should be wary of using





Allman, et al.              Standards Track                    [Page 15]

RFC 4871                    DKIM Signatures                     May 2007


      this tag, and verifiers might wish to ignore the tag or remove
      text that appears after the specified content length, perhaps
      based on other criteria.

   The body length count allows the signer of a message to permit data
   to be appended to the end of the body of a signed message.  The body
   length count MUST be calculated following the canonicalization
   algorithm; for example, any whitespace ignored by a canonicalization
   algorithm is not included as part of the body length count.  Signers
   of MIME messages that include a body length count SHOULD be sure that
   the length extends to the closing MIME boundary string.

      INFORMATIVE IMPLEMENTATION NOTE: A signer wishing to ensure that
      the only acceptable modifications are to add to the MIME postlude
      would use a body length count encompassing the entire final MIME
      boundary string, including the final "--CRLF".  A signer wishing
      to allow additional MIME parts but not modification of existing
      parts would use a body length count extending through the final
      MIME boundary string, omitting the final "--CRLF".  Note that this
      only works for some MIME types, e.g., multipart/mixed but not
      multipart/signed.

   A body length count of zero means that the body is completely
   unsigned.

   Signers wishing to ensure that no modification of any sort can occur
   should specify the "simple" canonicalization algorithm for both
   header and body and omit the body length count.

3.4.6.  Canonicalization Examples (INFORMATIVE)

   In the following examples, actual whitespace is used only for
   clarity.  The actual input and output text is designated using
   bracketed descriptors: "<SP>" for a space character, "<HTAB>" for a
   tab character, and "<CRLF>" for a carriage-return/line-feed sequence.
   For example, "X <SP> Y" and "X<SP>Y" represent the same three
   characters.

   Example 1: A message reading:

       A: <SP> X <CRLF>
       B <SP> : <SP> Y <HTAB><CRLF>
       <HTAB> Z <SP><SP><CRLF>
       <CRLF>
       <SP> C <SP><CRLF>
       D <SP><HTAB><SP> E <CRLF>
       <CRLF>
       <CRLF>



Allman, et al.              Standards Track                    [Page 16]

RFC 4871                    DKIM Signatures                     May 2007


   when canonicalized using relaxed canonicalization for both header and
   body results in a header reading:

       a:X <CRLF>
       b:Y <SP> Z <CRLF>

   and a body reading:

       <SP> C <CRLF>
       D <SP> E <CRLF>

   Example 2: The same message canonicalized using simple
   canonicalization for both header and body results in a header
   reading:

       A: <SP> X <CRLF>
       B <SP> : <SP> Y <HTAB><CRLF>
       <HTAB> Z <SP><SP><CRLF>

   and a body reading:

       <SP> C <SP><CRLF>
       D <SP><HTAB><SP> E <CRLF>

   Example 3: When processed using relaxed header canonicalization and
   simple body canonicalization, the canonicalized version has a header
   of:

       a:X <CRLF>
       b:Y <SP> Z <CRLF>

   and a body reading:

       <SP> C <SP><CRLF>
       D <SP><HTAB><SP> E <CRLF>

3.5.  The DKIM-Signature Header Field

   The signature of the email is stored in the DKIM-Signature header
   field.  This header field contains all of the signature and key-
   fetching data.  The DKIM-Signature value is a tag-list as described
   in Section 3.2.

   The DKIM-Signature header field SHOULD be treated as though it were a
   trace header field as defined in Section 3.6 of [RFC2822], and hence
   SHOULD NOT be reordered and SHOULD be prepended to the message.





Allman, et al.              Standards Track                    [Page 17]

RFC 4871                    DKIM Signatures                     May 2007


   The DKIM-Signature header field being created or verified is always
   included in the signature calculation, after the rest of the header
   fields being signed; however, when calculating or verifying the
   signature, the value of the "b=" tag (signature value) of that DKIM-
   Signature header field MUST be treated as though it were an empty
   string.  Unknown tags in the DKIM-Signature header field MUST be
   included in the signature calculation but MUST be otherwise ignored
   by verifiers.  Other DKIM-Signature header fields that are included
   in the signature should be treated as normal header fields; in
   particular, the "b=" tag is not treated specially.

   The encodings for each field type are listed below.  Tags described
   as qp-section are encoded as described in Section 6.7 of MIME Part
   One [RFC2045], with the additional conversion of semicolon characters
   to "=3B"; intuitively, this is one line of quoted-printable encoded
   text.  The dkim-quoted-printable syntax is defined in Section 2.6.

   Tags on the DKIM-Signature header field along with their type and
   requirement status are shown below.  Unrecognized tags MUST be
   ignored.

   v=  Version (MUST be included).  This tag defines the version of this
       specification that applies to the signature record.  It MUST have
       the value "1".  Note that verifiers must do a string comparison
       on this value; for example, "1" is not the same as "1.0".

   ABNF:

       sig-v-tag   = %x76 [FWS] "=" [FWS] "1"

           INFORMATIVE NOTE: DKIM-Signature version numbers are expected
           to increase arithmetically as new versions of this
           specification are released.

   a=  The algorithm used to generate the signature (plain-text;
       REQUIRED).  Verifiers MUST support "rsa-sha1" and "rsa-sha256";
       signers SHOULD sign using "rsa-sha256".  See Section 3.3 for a
       description of algorithms.

   ABNF:

       sig-a-tag       = %x61 [FWS] "=" [FWS] sig-a-tag-alg
       sig-a-tag-alg   = sig-a-tag-k "-" sig-a-tag-h
       sig-a-tag-k     = "rsa" / x-sig-a-tag-k
       sig-a-tag-h     = "sha1" / "sha256" / x-sig-a-tag-h
       x-sig-a-tag-k   = ALPHA *(ALPHA / DIGIT)   ; for later extension
       x-sig-a-tag-h   = ALPHA *(ALPHA / DIGIT)   ; for later extension




Allman, et al.              Standards Track                    [Page 18]

RFC 4871                    DKIM Signatures                     May 2007


   b=  The signature data (base64; REQUIRED).  Whitespace is ignored in
       this value and MUST be ignored when reassembling the original
       signature.  In particular, the signing process can safely insert
       FWS in this value in arbitrary places to conform to line-length
       limits.  See Signer Actions (Section 5) for how the signature is
       computed.

   ABNF:

       sig-b-tag       = %x62 [FWS] "=" [FWS] sig-b-tag-data
       sig-b-tag-data  = base64string

   bh= The hash of the canonicalized body part of the message as limited
       by the "l=" tag (base64; REQUIRED).  Whitespace is ignored in
       this value and MUST be ignored when reassembling the original
       signature.  In particular, the signing process can safely insert
       FWS in this value in arbitrary places to conform to line-length
       limits.  See Section 3.7 for how the body hash is computed.

   ABNF:

       sig-bh-tag      = %x62 %x68 [FWS] "=" [FWS] sig-bh-tag-data
       sig-bh-tag-data = base64string

   c=  Message canonicalization (plain-text; OPTIONAL, default is
       "simple/simple").  This tag informs the verifier of the type of
       canonicalization used to prepare the message for signing.  It
       consists of two names separated by a "slash" (%d47) character,
       corresponding to the header and body canonicalization algorithms
       respectively.  These algorithms are described in Section 3.4.  If
       only one algorithm is named, that algorithm is used for the
       header and "simple" is used for the body.  For example,
       "c=relaxed" is treated the same as "c=relaxed/simple".

   ABNF:

       sig-c-tag       = %x63 [FWS] "=" [FWS] sig-c-tag-alg
                     ["/" sig-c-tag-alg]
       sig-c-tag-alg   = "simple" / "relaxed" / x-sig-c-tag-alg
       x-sig-c-tag-alg = hyphenated-word    ; for later extension

   d=  The domain of the signing entity (plain-text; REQUIRED).  This is
       the domain that will be queried for the public key.  This domain
       MUST be the same as or a parent domain of the "i=" tag (the
       signing identity, as described below), or it MUST meet the
       requirements for parent domain signing described in Section 3.8.
       When presented with a signature that does not meet these
       requirement, verifiers MUST consider the signature invalid.



Allman, et al.              Standards Track                    [Page 19]

RFC 4871                    DKIM Signatures                     May 2007


   Internationalized domain names MUST be encoded as described in
       [RFC3490].

   ABNF:

       sig-d-tag       = %x64 [FWS] "=" [FWS] domain-name
       domain-name     = sub-domain 1*("." sub-domain)
                ; from RFC 2821 Domain, but excluding address-literal

   h=  Signed header fields (plain-text, but see description; REQUIRED).
       A colon-separated list of header field names that identify the
       header fields presented to the signing algorithm.  The field MUST
       contain the complete list of header fields in the order presented
       to the signing algorithm.  The field MAY contain names of header
       fields that do not exist when signed; nonexistent header fields
       do not contribute to the signature computation (that is, they are
       treated as the null input, including the header field name, the
       separating colon, the header field value, and any CRLF
       terminator).  The field MUST NOT include the DKIM-Signature
       header field that is being created or verified, but may include
       others.  Folding whitespace (FWS) MAY be included on either side
       of the colon separator.  Header field names MUST be compared
       against actual header field names in a case-insensitive manner.
       This list MUST NOT be empty.  See Section 5.4 for a discussion of
       choosing header fields to sign.

   ABNF:

       sig-h-tag       = %x68 [FWS] "=" [FWS] hdr-name
                     0*( *FWS ":" *FWS hdr-name )
       hdr-name        = field-name

       INFORMATIVE EXPLANATION: By "signing" header fields that do not
           actually exist, a signer can prevent insertion of those
           header fields before verification.  However, since a signer
           cannot possibly know what header fields might be created in
           the future, and that some MUAs might present header fields
           that are embedded inside a message (e.g., as a message/rfc822
           content type), the security of this solution is not total.

       INFORMATIVE EXPLANATION: The exclusion of the header field name
           and colon as well as the header field value for non-existent
           header fields prevents an attacker from inserting an actual
           header field with a null value.







Allman, et al.              Standards Track                    [Page 20]

RFC 4871                    DKIM Signatures                     May 2007


   i=  Identity of the user or agent (e.g., a mailing list manager) on
       behalf of which this message is signed (dkim-quoted-printable;
       OPTIONAL, default is an empty Local-part followed by an "@"
       followed by the domain from the "d=" tag).  The syntax is a
       standard email address where the Local-part MAY be omitted.  The
       domain part of the address MUST be the same as or a subdomain of
       the value of the "d=" tag.

   Internationalized domain names MUST be converted using the steps
       listed in Section 4 of [RFC3490] using the "ToASCII" function.

   ABNF:

       sig-i-tag =   %x69 [FWS] "=" [FWS] [ Local-part ] "@" domain-name

       INFORMATIVE NOTE: The Local-part of the "i=" tag is optional
           because in some cases a signer may not be able to establish a
           verified individual identity.  In such cases, the signer may
           wish to assert that although it is willing to go as far as
           signing for the domain, it is unable or unwilling to commit
           to an individual user name within their domain.  It can do so
           by including the domain part but not the Local-part of the
           identity.

       INFORMATIVE DISCUSSION: This document does not require the value
           of the "i=" tag to match the identity in any message header
           fields.  This is considered to be a verifier policy issue.
           Constraints between the value of the "i=" tag and other
           identities in other header fields seek to apply basic
           authentication into the semantics of trust associated with a
           role such as content author.  Trust is a broad and complex
           topic and trust mechanisms are subject to highly creative
           attacks.  The real-world efficacy of any but the most basic
           bindings between the "i=" value and other identities is not
           well established, nor is its vulnerability to subversion by
           an attacker.  Hence reliance on the use of these options
           should be strictly limited.  In particular, it is not at all
           clear to what extent a typical end-user recipient can rely on
           any assurances that might be made by successful use of the
           "i=" options.

   l=  Body length count (plain-text unsigned decimal integer; OPTIONAL,
       default is entire body).  This tag informs the verifier of the
       number of octets in the body of the email after canonicalization
       included in the cryptographic hash, starting from 0 immediately
       following the CRLF preceding the body.  This value MUST NOT be
       larger than the actual number of octets in the canonicalized
       message body.



Allman, et al.              Standards Track                    [Page 21]

RFC 4871                    DKIM Signatures                     May 2007


       INFORMATIVE IMPLEMENTATION WARNING: Use of the "l=" tag might
           allow display of fraudulent content without appropriate
           warning to end users.  The "l=" tag is intended for
           increasing signature robustness when sending to mailing lists
           that both modify their content and do not sign their
           messages.  However, using the "l=" tag enables attacks in
           which an intermediary with malicious intent modifies a
           message to include content that solely benefits the attacker.
           It is possible for the appended content to completely replace
           the original content in the end recipient's eyes and to
           defeat duplicate message detection algorithms.  Examples are
           described in Security Considerations (Section 8).  To avoid
           this attack, signers should be extremely wary of using this
           tag, and verifiers might wish to ignore the tag or remove
           text that appears after the specified content length.

       INFORMATIVE NOTE: The value of the "l=" tag is constrained to 76
           decimal digits.  This constraint is not intended to predict
           the size of future messages or to require implementations to
           use an integer representation large enough to represent the
           maximum possible value, but is intended to remind the
           implementer to check the length of this and all other tags
           during verification and to test for integer overflow when
           decoding the value.  Implementers may need to limit the
           actual value expressed to a value smaller than 10^76, e.g.,
           to allow a message to fit within the available storage space.

   ABNF:

   sig-l-tag    = %x6c [FWS] "=" [FWS] 1*76DIGIT

   q=  A colon-separated list of query methods used to retrieve the
       public key (plain-text; OPTIONAL, default is "dns/txt").  Each
       query method is of the form "type[/options]", where the syntax
       and semantics of the options depend on the type and specified
       options.  If there are multiple query mechanisms listed, the
       choice of query mechanism MUST NOT change the interpretation of
       the signature.  Implementations MUST use the recognized query
       mechanisms in the order presented.

   Currently, the only valid value is "dns/txt", which defines the DNS
       TXT record lookup algorithm described elsewhere in this document.
       The only option defined for the "dns" query type is "txt", which
       MUST be included.  Verifiers and signers MUST support "dns/txt".







Allman, et al.              Standards Track                    [Page 22]

RFC 4871                    DKIM Signatures                     May 2007


   ABNF:

       sig-q-tag        = %x71 [FWS] "=" [FWS] sig-q-tag-method
                      *([FWS] ":" [FWS] sig-q-tag-method)
       sig-q-tag-method = "dns/txt" / x-sig-q-tag-type
                      ["/" x-sig-q-tag-args]
       x-sig-q-tag-type = hyphenated-word  ; for future extension
       x-sig-q-tag-args = qp-hdr-value

   s=  The selector subdividing the namespace for the "d=" (domain) tag
       (plain-text; REQUIRED).

   ABNF:

       sig-s-tag    = %x73 [FWS] "=" [FWS] selector

   t=  Signature Timestamp (plain-text unsigned decimal integer;
       RECOMMENDED, default is an unknown creation time).  The time that
       this signature was created.  The format is the number of seconds
       since 00:00:00 on January 1, 1970 in the UTC time zone.  The
       value is expressed as an unsigned integer in decimal ASCII.  This
       value is not constrained to fit into a 31- or 32-bit integer.
       Implementations SHOULD be prepared to handle values up to at
       least 10^12 (until approximately AD 200,000; this fits into 40
       bits).  To avoid denial-of-service attacks, implementations MAY
       consider any value longer than 12 digits to be infinite.  Leap
       seconds are not counted.  Implementations MAY ignore signatures
       that have a timestamp in the future.

   ABNF:

       sig-t-tag    = %x74 [FWS] "=" [FWS] 1*12DIGIT

   x=  Signature Expiration (plain-text unsigned decimal integer;
       RECOMMENDED, default is no expiration).  The format is the same
       as in the "t=" tag, represented as an absolute date, not as a
       time delta from the signing timestamp.  The value is expressed as
       an unsigned integer in decimal ASCII, with the same constraints
       on the value in the "t=" tag.  Signatures MAY be considered
       invalid if the verification time at the verifier is past the
       expiration date.  The verification time should be the time that
       the message was first received at the administrative domain of
       the verifier if that time is reliably available; otherwise the
       current time should be used.  The value of the "x=" tag MUST be
       greater than the value of the "t=" tag if both are present.






Allman, et al.              Standards Track                    [Page 23]

RFC 4871                    DKIM Signatures                     May 2007


       INFORMATIVE NOTE: The "x=" tag is not intended as an anti-replay
           defense.

   ABNF:

       sig-x-tag    = %x78 [FWS] "=" [FWS] 1*12DIGIT

   z=  Copied header fields (dkim-quoted-printable, but see description;
       OPTIONAL, default is null).  A vertical-bar-separated list of
       selected header fields present when the message was signed,
       including both the field name and value.  It is not required to
       include all header fields present at the time of signing.  This
       field need not contain the same header fields listed in the "h="
       tag.  The header field text itself must encode the vertical bar
       ("|", %x7C) character (i.e., vertical bars in the "z=" text are
       metacharacters, and any actual vertical bar characters in a
       copied header field must be encoded).  Note that all whitespace
       must be encoded, including whitespace between the colon and the
       header field value.  After encoding, FWS MAY be added at
       arbitrary locations in order to avoid excessively long lines;
       such whitespace is NOT part of the value of the header field, and
       MUST be removed before decoding.

   The header fields referenced by the "h=" tag refer to the fields in
       the RFC 2822 header of the message, not to any copied fields in
       the "z=" tag.  Copied header field values are for diagnostic use.

   Header fields with characters requiring conversion (perhaps from
       legacy MTAs that are not [RFC2822] compliant) SHOULD be converted
       as described in MIME Part Three [RFC2047].

   ABNF:
       sig-z-tag      = %x7A [FWS] "=" [FWS] sig-z-tag-copy
                    *( [FWS] "|" sig-z-tag-copy )
   sig-z-tag-copy = hdr-name ":" qp-hdr-value
   qp-hdr-value   = dkim-quoted-printable    ; with "|" encoded

      INFORMATIVE EXAMPLE of a signature header field spread across
      multiple continuation lines:












Allman, et al.              Standards Track                    [Page 24]

RFC 4871                    DKIM Signatures                     May 2007


   DKIM-Signature: a=rsa-sha256; d=example.net; s=brisbane;
      c=simple; q=dns/txt; i=@eng.example.net;
      t=1117574938; x=1118006938;
      h=from:to:subject:date;
      z=From:foo@eng.example.net|To:joe@example.com|
        Subject:demo=20run|Date:July=205,=202005=203:44:08=20PM=20-0700;
      bh=MTIzNDU2Nzg5MDEyMzQ1Njc4OTAxMjM0NTY3ODkwMTI=;
      b=dzdVyOfAKCdLXdJOc9G2q8LoXSlEniSbav+yuU4zGeeruD00lszZ
               VoG4ZHRNiYzR

3.6.  Key Management and Representation

   Signature applications require some level of assurance that the
   verification public key is associated with the claimed signer.  Many
   applications achieve this by using public key certificates issued by
   a trusted third party.  However, DKIM can achieve a sufficient level
   of security, with significantly enhanced scalability, by simply
   having the verifier query the purported signer's DNS entry (or some
   security-equivalent) in order to retrieve the public key.

   DKIM keys can potentially be stored in multiple types of key servers
   and in multiple formats.  The storage and format of keys are
   irrelevant to the remainder of the DKIM algorithm.

   Parameters to the key lookup algorithm are the type of the lookup
   (the "q=" tag), the domain of the signer (the "d=" tag of the DKIM-
   Signature header field), and the selector (the "s=" tag).

       public_key = dkim_find_key(q_val, d_val, s_val)

   This document defines a single binding, using DNS TXT records to
   distribute the keys.  Other bindings may be defined in the future.

3.6.1.  Textual Representation

   It is expected that many key servers will choose to present the keys
   in an otherwise unstructured text format (for example, an XML form
   would not be considered to be unstructured text for this purpose).
   The following definition MUST be used for any DKIM key represented in
   an otherwise unstructured textual form.

   The overall syntax is a tag-list as described in Section 3.2.  The
   current valid tags are described below.  Other tags MAY be present
   and MUST be ignored by any implementation that does not understand
   them.






Allman, et al.              Standards Track                    [Page 25]

RFC 4871                    DKIM Signatures                     May 2007


   v=  Version of the DKIM key record (plain-text; RECOMMENDED, default
       is "DKIM1").  If specified, this tag MUST be set to "DKIM1"
       (without the quotes).  This tag MUST be the first tag in the
       record.  Records beginning with a "v=" tag with any other value
       MUST be discarded.  Note that verifiers must do a string
       comparison on this value; for example, "DKIM1" is not the same as
       "DKIM1.0".

       ABNF:

       key-v-tag    = %x76 [FWS] "=" [FWS] "DKIM1"

   g=  Granularity of the key (plain-text; OPTIONAL, default is "*").
       This value MUST match the Local-part of the "i=" tag of the DKIM-
       Signature header field (or its default value of the empty string
       if "i=" is not specified), with a single, optional "*" character
       matching a sequence of zero or more arbitrary characters
       ("wildcarding").  An email with a signing address that does not
       match the value of this tag constitutes a failed verification.
       The intent of this tag is to constrain which signing address can
       legitimately use this selector, for example, when delegating a
       key to a third party that should only be used for special
       purposes.  Wildcarding allows matching for addresses such as
       "user+*" or "*-offer".  An empty "g=" value never matches any
       addresses.

   ABNF:

       key-g-tag       = %x67 [FWS] "=" [FWS] key-g-tag-lpart
       key-g-tag-lpart = [dot-atom-text] ["*" [dot-atom-text] ]

   h=  Acceptable hash algorithms (plain-text; OPTIONAL, defaults to
       allowing all algorithms).  A colon-separated list of hash
       algorithms that might be used.  Signers and Verifiers MUST
       support the "sha256" hash algorithm.  Verifiers MUST also support
       the "sha1" hash algorithm.

       ABNF:

       key-h-tag       = %x68 [FWS] "=" [FWS] key-h-tag-alg
                     0*( [FWS] ":" [FWS] key-h-tag-alg )
       key-h-tag-alg   = "sha1" / "sha256" / x-key-h-tag-alg
       x-key-h-tag-alg = hyphenated-word   ; for future extension








Allman, et al.              Standards Track                    [Page 26]

RFC 4871                    DKIM Signatures                     May 2007


   k=  Key type (plain-text; OPTIONAL, default is "rsa").  Signers and
       verifiers MUST support the "rsa" key type.  The "rsa" key type
       indicates that an ASN.1 DER-encoded [ITU.X660.1997] RSAPublicKey
       [RFC3447] (see Sections 3.1 and A.1.1) is being used in the "p="
       tag.  (Note: the "p=" tag further encodes the value using the
       base64 algorithm.)

       ABNF:

       key-k-tag        = %x76 [FWS] "=" [FWS] key-k-tag-type
       key-k-tag-type   = "rsa" / x-key-k-tag-type
       x-key-k-tag-type = hyphenated-word   ; for future extension

   n=  Notes that might be of interest to a human (qp-section; OPTIONAL,
       default is empty).  No interpretation is made by any program.
       This tag should be used sparingly in any key server mechanism
       that has space limitations (notably DNS).  This is intended for
       use by administrators, not end users.

   ABNF:

       key-n-tag    = %x6e [FWS] "=" [FWS] qp-section

   p=  Public-key data (base64; REQUIRED).  An empty value means that
       this public key has been revoked.  The syntax and semantics of
       this tag value before being encoded in base64 are defined by the
       "k=" tag.

           INFORMATIVE RATIONALE: If a private key has been compromised
           or otherwise disabled (e.g., an outsourcing contract has been
           terminated), a signer might want to explicitly state that it
           knows about the selector, but all messages using that
           selector should fail verification.  Verifiers should ignore
           any DKIM-Signature header fields with a selector referencing
           a revoked key.

   ABNF:

       key-p-tag    = %x70 [FWS] "=" [ [FWS] base64string ]

       INFORMATIVE NOTE: A base64string is permitted to include white
           space (FWS) at arbitrary places; however, any CRLFs must be
           followed by at least one WSP character.  Implementors and
           administrators are cautioned to ensure that selector TXT
           records conform to this specification.






Allman, et al.              Standards Track                    [Page 27]

RFC 4871                    DKIM Signatures                     May 2007


   s=  Service Type (plain-text; OPTIONAL; default is "*").  A colon-
       separated list of service types to which this record applies.
       Verifiers for a given service type MUST ignore this record if the
       appropriate type is not listed.  Currently defined service types
       are as follows:

       *   matches all service types

       email   electronic mail (not necessarily limited to SMTP)

       This tag is intended to constrain the use of keys for other
       purposes, should use of DKIM be defined by other services in the
       future.

   ABNF:

       key-s-tag        = %x73 [FWS] "=" [FWS] key-s-tag-type
                       0*( [FWS] ":" [FWS] key-s-tag-type )
       key-s-tag-type   = "email" / "*" / x-key-s-tag-type
       x-key-s-tag-type = hyphenated-word   ; for future extension

   t=  Flags, represented as a colon-separated list of names (plain-
       text; OPTIONAL, default is no flags set).  The defined flags are
       as follows:

       y   This domain is testing DKIM.  Verifiers MUST NOT treat
           messages from signers in testing mode differently from
           unsigned email, even should the signature fail to verify.
           Verifiers MAY wish to track testing mode results to assist
           the signer.

       s   Any DKIM-Signature header fields using the "i=" tag MUST have
           the same domain value on the right-hand side of the "@" in
           the "i=" tag and the value of the "d=" tag.  That is, the
           "i=" domain MUST NOT be a subdomain of "d=".  Use of this
           flag is RECOMMENDED unless subdomaining is required.

   ABNF:

       key-t-tag        = %x74 [FWS] "=" [FWS] key-t-tag-flag
                      0*( [FWS] ":" [FWS] key-t-tag-flag )
       key-t-tag-flag   = "y" / "s" / x-key-t-tag-flag
       x-key-t-tag-flag = hyphenated-word   ; for future extension

   Unrecognized flags MUST be ignored.






Allman, et al.              Standards Track                    [Page 28]

RFC 4871                    DKIM Signatures                     May 2007


3.6.2.  DNS Binding

   A binding using DNS TXT records as a key service is hereby defined.
   All implementations MUST support this binding.

3.6.2.1.  Namespace

   All DKIM keys are stored in a subdomain named "_domainkey".  Given a
   DKIM-Signature field with a "d=" tag of "example.com" and an "s=" tag
   of "foo.bar", the DNS query will be for
   "foo.bar._domainkey.example.com".

      INFORMATIVE OPERATIONAL NOTE: Wildcard DNS records (e.g.,
      *.bar._domainkey.example.com) do not make sense in this context
      and should not be used.  Note also that wildcards within domains
      (e.g., s._domainkey.*.example.com) are not supported by the DNS.

3.6.2.2.  Resource Record Types for Key Storage

   The DNS Resource Record type used is specified by an option to the
   query-type ("q=") tag.  The only option defined in this base
   specification is "txt", indicating the use of a TXT Resource Record
   (RR).  A later extension of this standard may define another RR type.

   Strings in a TXT RR MUST be concatenated together before use with no
   intervening whitespace.  TXT RRs MUST be unique for a particular
   selector name; that is, if there are multiple records in an RRset,
   the results are undefined.

   TXT RRs are encoded as described in Section 3.6.1.

3.7.  Computing the Message Hashes

   Both signing and verifying message signatures start with a step of
   computing two cryptographic hashes over the message.  Signers will
   choose the parameters of the signature as described in Signer Actions
   (Section 5); verifiers will use the parameters specified in the DKIM-
   Signature header field being verified.  In the following discussion,
   the names of the tags in the DKIM-Signature header field that either
   exists (when verifying) or will be created (when signing) are used.
   Note that canonicalization (Section 3.4) is only used to prepare the
   email for signing or verifying; it does not affect the transmitted
   email in any way.

   The signer/verifier MUST compute two hashes, one over the body of the
   message and one over the selected header fields of the message.





Allman, et al.              Standards Track                    [Page 29]

RFC 4871                    DKIM Signatures                     May 2007


   Signers MUST compute them in the order shown.  Verifiers MAY compute
   them in any order convenient to the verifier, provided that the
   result is semantically identical to the semantics that would be the
   case had they been computed in this order.

   In hash step 1, the signer/verifier MUST hash the message body,
   canonicalized using the body canonicalization algorithm specified in
   the "c=" tag and then truncated to the length specified in the "l="
   tag.  That hash value is then converted to base64 form and inserted
   into (signers) or compared to (verifiers) the "bh=" tag of the DKIM-
   Signature header field.

   In hash step 2, the signer/verifier MUST pass the following to the
   hash algorithm in the indicated order.

   1.  The header fields specified by the "h=" tag, in the order
       specified in that tag, and canonicalized using the header
       canonicalization algorithm specified in the "c=" tag.  Each
       header field MUST be terminated with a single CRLF.

   2.  The DKIM-Signature header field that exists (verifying) or will
       be inserted (signing) in the message, with the value of the "b="
       tag deleted (i.e., treated as the empty string), canonicalized
       using the header canonicalization algorithm specified in the "c="
       tag, and without a trailing CRLF.

   All tags and their values in the DKIM-Signature header field are
   included in the cryptographic hash with the sole exception of the
   value portion of the "b=" (signature) tag, which MUST be treated as
   the null string.  All tags MUST be included even if they might not be
   understood by the verifier.  The header field MUST be presented to
   the hash algorithm after the body of the message rather than with the
   rest of the header fields and MUST be canonicalized as specified in
   the "c=" (canonicalization) tag.  The DKIM-Signature header field
   MUST NOT be included in its own h= tag, although other DKIM-Signature
   header fields MAY be signed (see Section 4).

   When calculating the hash on messages that will be transmitted using
   base64 or quoted-printable encoding, signers MUST compute the hash
   after the encoding.  Likewise, the verifier MUST incorporate the
   values into the hash before decoding the base64 or quoted-printable
   text.  However, the hash MUST be computed before transport level
   encodings such as SMTP "dot-stuffing" (the modification of lines
   beginning with a "." to avoid confusion with the SMTP end-of-message
   marker, as specified in [RFC2821]).

   With the exception of the canonicalization procedure described in
   Section 3.4, the DKIM signing process treats the body of messages as



Allman, et al.              Standards Track                    [Page 30]

RFC 4871                    DKIM Signatures                     May 2007


   simply a string of octets.  DKIM messages MAY be either in plain-text
   or in MIME format; no special treatment is afforded to MIME content.
   Message attachments in MIME format MUST be included in the content
   that is signed.

   More formally, the algorithm for the signature is as follows:
       body-hash = hash-alg(canon_body)
       header-hash = hash-alg(canon_header || DKIM-SIG)
       signature = sig-alg(header-hash, key)

   where "sig-alg" is the signature algorithm specified by the "a=" tag,
   "hash-alg" is the hash algorithm specified by the "a=" tag,
   "canon_header" and "canon_body" are the canonicalized message header
   and body (respectively) as defined in Section 3.4 (excluding the
   DKIM-Signature header field), and "DKIM-SIG" is the canonicalized
   DKIM-Signature header field sans the signature value itself, but with
   "body-hash" included as the "bh=" tag.

      INFORMATIVE IMPLEMENTERS' NOTE: Many digital signature APIs
      provide both hashing and application of the RSA private key using
      a single "sign()" primitive.  When using such an API, the last two
      steps in the algorithm would probably be combined into a single
      call that would perform both the "hash-alg" and the "sig-alg".

3.8.  Signing by Parent Domains

   In some circumstances, it is desirable for a domain to apply a
   signature on behalf of any of its subdomains without the need to
   maintain separate selectors (key records) in each subdomain.  By
   default, private keys corresponding to key records can be used to
   sign messages for any subdomain of the domain in which they reside;
   e.g., a key record for the domain example.com can be used to verify
   messages where the signing identity ("i=" tag of the signature) is
   sub.example.com, or even sub1.sub2.example.com.  In order to limit
   the capability of such keys when this is not intended, the "s" flag
   may be set in the "t=" tag of the key record to constrain the
   validity of the record to exactly the domain of the signing identity.
   If the referenced key record contains the "s" flag as part of the
   "t=" tag, the domain of the signing identity ("i=" flag) MUST be the
   same as that of the d= domain.  If this flag is absent, the domain of
   the signing identity MUST be the same as, or a subdomain of, the d=
   domain.  Key records that are not intended for use with subdomains
   SHOULD specify the "s" flag in the "t=" tag.








Allman, et al.              Standards Track                    [Page 31]

RFC 4871                    DKIM Signatures                     May 2007


4.  Semantics of Multiple Signatures

4.1.  Example Scenarios

   There are many reasons why a message might have multiple signatures.
   For example, a given signer might sign multiple times, perhaps with
   different hashing or signing algorithms during a transition phase.

      INFORMATIVE EXAMPLE: Suppose SHA-256 is in the future found to be
      insufficiently strong, and DKIM usage transitions to SHA-1024.  A
      signer might immediately sign using the newer algorithm, but
      continue to sign using the older algorithm for interoperability
      with verifiers that had not yet upgraded.  The signer would do
      this by adding two DKIM-Signature header fields, one using each
      algorithm.  Older verifiers that did not recognize SHA-1024 as an
      acceptable algorithm would skip that signature and use the older
      algorithm; newer verifiers could use either signature at their
      option, and all other things being equal might not even attempt to
      verify the other signature.

   Similarly, a signer might sign a message including all headers and no
   "l=" tag (to satisfy strict verifiers) and a second time with a
   limited set of headers and an "l=" tag (in anticipation of possible
   message modifications in route to other verifiers).  Verifiers could
   then choose which signature they preferred.

      INFORMATIVE EXAMPLE: A verifier might receive a message with two
      signatures, one covering more of the message than the other.  If
      the signature covering more of the message verified, then the
      verifier could make one set of policy decisions; if that signature
      failed but the signature covering less of the message verified,
      the verifier might make a different set of policy decisions.

   Of course, a message might also have multiple signatures because it
   passed through multiple signers.  A common case is expected to be
   that of a signed message that passes through a mailing list that also
   signs all messages.  Assuming both of those signatures verify, a
   recipient might choose to accept the message if either of those
   signatures were known to come from trusted sources.

      INFORMATIVE EXAMPLE: Recipients might choose to whitelist mailing
      lists to which they have subscribed and that have acceptable anti-
      abuse policies so as to accept messages sent to that list even
      from unknown authors.  They might also subscribe to less trusted
      mailing lists (e.g., those without anti-abuse protection) and be
      willing to accept all messages from specific authors, but insist
      on doing additional abuse scanning for other messages.




Allman, et al.              Standards Track                    [Page 32]

RFC 4871                    DKIM Signatures                     May 2007


   Another related example of multiple signers might be forwarding
   services, such as those commonly associated with academic alumni
   sites.

      INFORMATIVE EXAMPLE: A recipient might have an address at
      members.example.org, a site that has anti-abuse protection that is
      somewhat less effective than the recipient would prefer.  Such a
      recipient might have specific authors whose messages would be
      trusted absolutely, but messages from unknown authors that had
      passed the forwarder's scrutiny would have only medium trust.

4.2.  Interpretation

   A signer that is adding a signature to a message merely creates a new
   DKIM-Signature header, using the usual semantics of the h= option.  A
   signer MAY sign previously existing DKIM-Signature header fields
   using the method described in Section 5.4 to sign trace header
   fields.

      INFORMATIVE NOTE: Signers should be cognizant that signing DKIM-
      Signature header fields may result in signature failures with
      intermediaries that do not recognize that DKIM-Signature header
      fields are trace header fields and unwittingly reorder them, thus
      breaking such signatures.  For this reason, signing existing DKIM-
      Signature header fields is unadvised, albeit legal.

      INFORMATIVE NOTE: If a header field with multiple instances is
      signed, those header fields are always signed from the bottom up.
      Thus, it is not possible to sign only specific DKIM-Signature
      header fields.  For example, if the message being signed already
      contains three DKIM-Signature header fields A, B, and C, it is
      possible to sign all of them, B and C only, or C only, but not A
      only, B only, A and B only, or A and C only.

   A signer MAY add more than one DKIM-Signature header field using
   different parameters.  For example, during a transition period a
   signer might want to produce signatures using two different hash
   algorithms.

   Signers SHOULD NOT remove any DKIM-Signature header fields from
   messages they are signing, even if they know that the signatures
   cannot be verified.

   When evaluating a message with multiple signatures, a verifier SHOULD
   evaluate signatures independently and on their own merits.  For
   example, a verifier that by policy chooses not to accept signatures
   with deprecated cryptographic algorithms would consider such
   signatures invalid.  Verifiers MAY process signatures in any order of



Allman, et al.              Standards Track                    [Page 33]

RFC 4871                    DKIM Signatures                     May 2007


   their choice; for example, some verifiers might choose to process
   signatures corresponding to the From field in the message header
   before other signatures.  See Section 6.1 for more information about
   signature choices.

      INFORMATIVE IMPLEMENTATION NOTE: Verifier attempts to correlate
      valid signatures with invalid signatures in an attempt to guess
      why a signature failed are ill-advised.  In particular, there is
      no general way that a verifier can determine that an invalid
      signature was ever valid.

   Verifiers SHOULD ignore failed signatures as though they were not
   present in the message.  Verifiers SHOULD continue to check
   signatures until a signature successfully verifies to the
   satisfaction of the verifier.  To limit potential denial-of-service
   attacks, verifiers MAY limit the total number of signatures they will
   attempt to verify.

5.  Signer Actions

   The following steps are performed in order by signers.

5.1.  Determine Whether the Email Should Be Signed and by Whom

   A signer can obviously only sign email for domains for which it has a
   private key and the necessary knowledge of the corresponding public
   key and selector information.  However, there are a number of other
   reasons beyond the lack of a private key why a signer could choose
   not to sign an email.

      INFORMATIVE NOTE: Signing modules may be incorporated into any
      portion of the mail system as deemed appropriate, including an
      MUA, a SUBMISSION server, or an MTA.  Wherever implemented,
      signers should beware of signing (and thereby asserting
      responsibility for) messages that may be problematic.  In
      particular, within a trusted enclave the signing address might be
      derived from the header according to local policy; SUBMISSION
      servers might only sign messages from users that are properly
      authenticated and authorized.

      INFORMATIVE IMPLEMENTER ADVICE: SUBMISSION servers should not sign
      Received header fields if the outgoing gateway MTA obfuscates
      Received header fields, for example, to hide the details of
      internal topology.

   If an email cannot be signed for some reason, it is a local policy
   decision as to what to do with that email.




Allman, et al.              Standards Track                    [Page 34]

RFC 4871                    DKIM Signatures                     May 2007


5.2.  Select a Private Key and Corresponding Selector Information

   This specification does not define the basis by which a signer should
   choose which private key and selector information to use.  Currently,
   all selectors are equal as far as this specification is concerned, so
   the decision should largely be a matter of administrative
   convenience.  Distribution and management of private keys is also
   outside the scope of this document.

      INFORMATIVE OPERATIONS ADVICE: A signer should not sign with a
      private key when the selector containing the corresponding public
      key is expected to be revoked or removed before the verifier has
      an opportunity to validate the signature.  The signer should
      anticipate that verifiers may choose to defer validation, perhaps
      until the message is actually read by the final recipient.  In
      particular, when rotating to a new key pair, signing should
      immediately commence with the new private key and the old public
      key should be retained for a reasonable validation interval before
      being removed from the key server.

5.3.  Normalize the Message to Prevent Transport Conversions

   Some messages, particularly those using 8-bit characters, are subject
   to modification during transit, notably conversion to 7-bit form.
   Such conversions will break DKIM signatures.  In order to minimize
   the chances of such breakage, signers SHOULD convert the message to a
   suitable MIME content transfer encoding such as quoted-printable or
   base64 as described in MIME Part One [RFC2045] before signing.  Such
   conversion is outside the scope of DKIM; the actual message SHOULD be
   converted to 7-bit MIME by an MUA or MSA prior to presentation to the
   DKIM algorithm.

   If the message is submitted to the signer with any local encoding
   that will be modified before transmission, that modification to
   canonical [RFC2822] form MUST be done before signing.  In particular,
   bare CR or LF characters (used by some systems as a local line
   separator convention) MUST be converted to the SMTP-standard CRLF
   sequence before the message is signed.  Any conversion of this sort
   SHOULD be applied to the message actually sent to the recipient(s),
   not just to the version presented to the signing algorithm.

   More generally, the signer MUST sign the message as it is expected to
   be received by the verifier rather than in some local or internal
   form.







Allman, et al.              Standards Track                    [Page 35]

RFC 4871                    DKIM Signatures                     May 2007


5.4.  Determine the Header Fields to Sign

   The From header field MUST be signed (that is, included in the "h="
   tag of the resulting DKIM-Signature header field).  Signers SHOULD
   NOT sign an existing header field likely to be legitimately modified
   or removed in transit.  In particular, [RFC2821] explicitly permits
   modification or removal of the Return-Path header field in transit.
   Signers MAY include any other header fields present at the time of
   signing at the discretion of the signer.

      INFORMATIVE OPERATIONS NOTE: The choice of which header fields to
      sign is non-obvious.  One strategy is to sign all existing, non-
      repeatable header fields.  An alternative strategy is to sign only
      header fields that are likely to be displayed to or otherwise be
      likely to affect the processing of the message at the receiver.  A
      third strategy is to sign only "well known" headers.  Note that
      verifiers may treat unsigned header fields with extreme
      skepticism, including refusing to display them to the end user or
      even ignoring the signature if it does not cover certain header
      fields.  For this reason, signing fields present in the message
      such as Date, Subject, Reply-To, Sender, and all MIME header
      fields are highly advised.

   The DKIM-Signature header field is always implicitly signed and MUST
   NOT be included in the "h=" tag except to indicate that other
   preexisting signatures are also signed.

   Signers MAY claim to have signed header fields that do not exist
   (that is, signers MAY include the header field name in the "h=" tag
   even if that header field does not exist in the message).  When
   computing the signature, the non-existing header field MUST be
   treated as the null string (including the header field name, header
   field value, all punctuation, and the trailing CRLF).

      INFORMATIVE RATIONALE: This allows signers to explicitly assert
      the absence of a header field; if that header field is added later
      the signature will fail.

      INFORMATIVE NOTE: A header field name need only be listed once
      more than the actual number of that header field in a message at
      the time of signing in order to prevent any further additions.
      For example, if there is a single Comments header field at the
      time of signing, listing Comments twice in the "h=" tag is
      sufficient to prevent any number of Comments header fields from
      being appended; it is not necessary (but is legal) to list
      Comments three or more times in the "h=" tag.





Allman, et al.              Standards Track                    [Page 36]

RFC 4871                    DKIM Signatures                     May 2007


   Signers choosing to sign an existing header field that occurs more
   than once in the message (such as Received) MUST sign the physically
   last instance of that header field in the header block.  Signers
   wishing to sign multiple instances of such a header field MUST
   include the header field name multiple times in the h= tag of the
   DKIM-Signature header field, and MUST sign such header fields in
   order from the bottom of the header field block to the top.  The
   signer MAY include more instances of a header field name in h= than
   there are actual corresponding header fields to indicate that
   additional header fields of that name SHOULD NOT be added.

      INFORMATIVE EXAMPLE:

      If the signer wishes to sign two existing Received header fields,
      and the existing header contains:

       Received: <A>
       Received: <B>
       Received: <C>

      then the resulting DKIM-Signature header field should read:

       DKIM-Signature: ... h=Received : Received : ...

      and Received header fields <C> and <B> will be signed in that
      order.

   Signers should be careful of signing header fields that might have
   additional instances added later in the delivery process, since such
   header fields might be inserted after the signed instance or
   otherwise reordered.  Trace header fields (such as Received) and
   Resent-* blocks are the only fields prohibited by [RFC2822] from
   being reordered.  In particular, since DKIM-Signature header fields
   may be reordered by some intermediate MTAs, signing existing DKIM-
   Signature header fields is error-prone.

      INFORMATIVE ADMONITION: Despite the fact that [RFC2822] permits
      header fields to be reordered (with the exception of Received
      header fields), reordering of signed header fields with multiple
      instances by intermediate MTAs will cause DKIM signatures to be
      broken; such anti-social behavior should be avoided.

      INFORMATIVE IMPLEMENTER'S NOTE: Although not required by this
      specification, all end-user visible header fields should be signed
      to avoid possible "indirect spamming".  For example, if the
      Subject header field is not signed, a spammer can resend a
      previously signed mail, replacing the legitimate subject with a
      one-line spam.



Allman, et al.              Standards Track                    [Page 37]

RFC 4871                    DKIM Signatures                     May 2007


5.5.  Recommended Signature Content

   In order to maximize compatibility with a variety of verifiers, it is
   recommended that signers follow the practices outlined in this
   section when signing a message.  However, these are generic
   recommendations applying to the general case; specific senders may
   wish to modify these guidelines as required by their unique
   situations.  Verifiers MUST be capable of verifying signatures even
   if one or more of the recommended header fields is not signed (with
   the exception of From, which must always be signed) or if one or more
   of the disrecommended header fields is signed.  Note that verifiers
   do have the option of ignoring signatures that do not cover a
   sufficient portion of the header or body, just as they may ignore
   signatures from an identity they do not trust.

   The following header fields SHOULD be included in the signature, if
   they are present in the message being signed:

   o  From (REQUIRED in all signatures)

   o  Sender, Reply-To

   o  Subject

   o  Date, Message-ID

   o  To, Cc

   o  MIME-Version

   o  Content-Type, Content-Transfer-Encoding, Content-ID, Content-
      Description

   o  Resent-Date, Resent-From, Resent-Sender, Resent-To, Resent-Cc,
      Resent-Message-ID

   o  In-Reply-To, References

   o  List-Id, List-Help, List-Unsubscribe, List-Subscribe, List-Post,
      List-Owner, List-Archive

   The following header fields SHOULD NOT be included in the signature:

   o  Return-Path

   o  Received

   o  Comments, Keywords



Allman, et al.              Standards Track                    [Page 38]

RFC 4871                    DKIM Signatures                     May 2007


   o  Bcc, Resent-Bcc

   o  DKIM-Signature

   Optional header fields (those not mentioned above) normally SHOULD
   NOT be included in the signature, because of the potential for
   additional header fields of the same name to be legitimately added or
   reordered prior to verification.  There are likely to be legitimate
   exceptions to this rule, because of the wide variety of application-
   specific header fields that may be applied to a message, some of
   which are unlikely to be duplicated, modified, or reordered.

   Signers SHOULD choose canonicalization algorithms based on the types
   of messages they process and their aversion to risk.  For example,
   e-commerce sites sending primarily purchase receipts, which are not
   expected to be processed by mailing lists or other software likely to
   modify messages, will generally prefer "simple" canonicalization.
   Sites sending primarily person-to-person email will likely prefer to
   be more resilient to modification during transport by using "relaxed"
   canonicalization.

   Signers SHOULD NOT use "l=" unless they intend to accommodate
   intermediate mail processors that append text to a message.  For
   example, many mailing list processors append "unsubscribe"
   information to message bodies.  If signers use "l=", they SHOULD
   include the entire message body existing at the time of signing in
   computing the count.  In particular, signers SHOULD NOT specify a
   body length of 0 since this may be interpreted as a meaningless
   signature by some verifiers.

5.6.  Compute the Message Hash and Signature

   The signer MUST compute the message hash as described in Section 3.7
   and then sign it using the selected public-key algorithm.  This will
   result in a DKIM-Signature header field that will include the body
   hash and a signature of the header hash, where that header includes
   the DKIM-Signature header field itself.

   Entities such as mailing list managers that implement DKIM and that
   modify the message or a header field (for example, inserting
   unsubscribe information) before retransmitting the message SHOULD
   check any existing signature on input and MUST make such
   modifications before re-signing the message.

   The signer MAY elect to limit the number of bytes of the body that
   will be included in the hash and hence signed.  The length actually
   hashed should be inserted in the "l=" tag of the DKIM-Signature
   header field.



Allman, et al.              Standards Track                    [Page 39]

RFC 4871                    DKIM Signatures                     May 2007


5.7.  Insert the DKIM-Signature Header Field

   Finally, the signer MUST insert the DKIM-Signature header field
   created in the previous step prior to transmitting the email.  The
   DKIM-Signature header field MUST be the same as used to compute the
   hash as described above, except that the value of the "b=" tag MUST
   be the appropriately signed hash computed in the previous step,
   signed using the algorithm specified in the "a=" tag of the DKIM-
   Signature header field and using the private key corresponding to the
   selector given in the "s=" tag of the DKIM-Signature header field, as
   chosen above in Section 5.2

   The DKIM-Signature header field MUST be inserted before any other
   DKIM-Signature fields in the header block.

      INFORMATIVE IMPLEMENTATION NOTE: The easiest way to achieve this
      is to insert the DKIM-Signature header field at the beginning of
      the header block.  In particular, it may be placed before any
      existing Received header fields.  This is consistent with treating
      DKIM-Signature as a trace header field.

6.  Verifier Actions

   Since a signer MAY remove or revoke a public key at any time, it is
   recommended that verification occur in a timely manner.  In many
   configurations, the most timely place is during acceptance by the
   border MTA or shortly thereafter.  In particular, deferring
   verification until the message is accessed by the end user is
   discouraged.

   A border or intermediate MTA MAY verify the message signature(s).  An
   MTA who has performed verification MAY communicate the result of that
   verification by adding a verification header field to incoming
   messages.  This considerably simplifies things for the user, who can
   now use an existing mail user agent.  Most MUAs have the ability to
   filter messages based on message header fields or content; these
   filters would be used to implement whatever policy the user wishes
   with respect to unsigned mail.

   A verifying MTA MAY implement a policy with respect to unverifiable
   mail, regardless of whether or not it applies the verification header
   field to signed messages.

   Verifiers MUST produce a result that is semantically equivalent to
   applying the following steps in the order listed.  In practice,
   several of these steps can be performed in parallel in order to
   improve performance.




Allman, et al.              Standards Track                    [Page 40]

RFC 4871                    DKIM Signatures                     May 2007


6.1.  Extract Signatures from the Message

   The order in which verifiers try DKIM-Signature header fields is not
   defined; verifiers MAY try signatures in any order they like.  For
   example, one implementation might try the signatures in textual
   order, whereas another might try signatures by identities that match
   the contents of the From header field before trying other signatures.
   Verifiers MUST NOT attribute ultimate meaning to the order of
   multiple DKIM-Signature header fields.  In particular, there is
   reason to believe that some relays will reorder the header fields in
   potentially arbitrary ways.

      INFORMATIVE IMPLEMENTATION NOTE: Verifiers might use the order as
      a clue to signing order in the absence of any other information.
      However, other clues as to the semantics of multiple signatures
      (such as correlating the signing host with Received header fields)
      may also be considered.

   A verifier SHOULD NOT treat a message that has one or more bad
   signatures and no good signatures differently from a message with no
   signature at all; such treatment is a matter of local policy and is
   beyond the scope of this document.

   When a signature successfully verifies, a verifier will either stop
   processing or attempt to verify any other signatures, at the
   discretion of the implementation.  A verifier MAY limit the number of
   signatures it tries to avoid denial-of-service attacks.

      INFORMATIVE NOTE: An attacker could send messages with large
      numbers of faulty signatures, each of which would require a DNS
      lookup and corresponding CPU time to verify the message.  This
      could be an attack on the domain that receives the message, by
      slowing down the verifier by requiring it to do a large number of
      DNS lookups and/or signature verifications.  It could also be an
      attack against the domains listed in the signatures, essentially
      by enlisting innocent verifiers in launching an attack against the
      DNS servers of the actual victim.

   In the following description, text reading "return status
   (explanation)" (where "status" is one of "PERMFAIL" or "TEMPFAIL")
   means that the verifier MUST immediately cease processing that
   signature.  The verifier SHOULD proceed to the next signature, if any
   is present, and completely ignore the bad signature.  If the status
   is "PERMFAIL", the signature failed and should not be reconsidered.
   If the status is "TEMPFAIL", the signature could not be verified at
   this time but may be tried again later.  A verifier MAY either defer
   the message for later processing, perhaps by queueing it locally or
   issuing a 451/4.7.5 SMTP reply, or try another signature; if no good



Allman, et al.              Standards Track                    [Page 41]

RFC 4871                    DKIM Signatures                     May 2007


   signature is found and any of the signatures resulted in a TEMPFAIL
   status, the verifier MAY save the message for later processing.  The
   "(explanation)" is not normative text; it is provided solely for
   clarification.

   Verifiers SHOULD ignore any DKIM-Signature header fields where the
   signature does not validate.  Verifiers that are prepared to validate
   multiple signature header fields SHOULD proceed to the next signature
   header field, should it exist.  However, verifiers MAY make note of
   the fact that an invalid signature was present for consideration at a
   later step.

      INFORMATIVE NOTE: The rationale of this requirement is to permit
      messages that have invalid signatures but also a valid signature
      to work.  For example, a mailing list exploder might opt to leave
      the original submitter signature in place even though the exploder
      knows that it is modifying the message in some way that will break
      that signature, and the exploder inserts its own signature.  In
      this case, the message should succeed even in the presence of the
      known-broken signature.

   For each signature to be validated, the following steps should be
   performed in such a manner as to produce a result that is
   semantically equivalent to performing them in the indicated order.

6.1.1.  Validate the Signature Header Field

   Implementers MUST meticulously validate the format and values in the
   DKIM-Signature header field; any inconsistency or unexpected values
   MUST cause the header field to be completely ignored and the verifier
   to return PERMFAIL (signature syntax error).  Being "liberal in what
   you accept" is definitely a bad strategy in this security context.
   Note however that this does not include the existence of unknown tags
   in a DKIM-Signature header field, which are explicitly permitted.

   Verifiers MUST ignore DKIM-Signature header fields with a "v=" tag
   that is inconsistent with this specification and return PERMFAIL
   (incompatible version).

      INFORMATIVE IMPLEMENTATION NOTE: An implementation may, of course,
      choose to also verify signatures generated by older versions of
      this specification.

   If any tag listed as "required" in Section 3.5 is omitted from the
   DKIM-Signature header field, the verifier MUST ignore the DKIM-
   Signature header field and return PERMFAIL (signature missing
   required tag).




Allman, et al.              Standards Track                    [Page 42]

RFC 4871                    DKIM Signatures                     May 2007


      INFORMATIONAL NOTE: The tags listed as required in Section 3.5 are
      "v=", "a=", "b=", "bh=", "d=", "h=", and "s=".  Should there be a
      conflict between this note and Section 3.5, Section 3.5 is
      normative.

   If the DKIM-Signature header field does not contain the "i=" tag, the
   verifier MUST behave as though the value of that tag were "@d", where
   "d" is the value from the "d=" tag.

   Verifiers MUST confirm that the domain specified in the "d=" tag is
   the same as or a parent domain of the domain part of the "i=" tag.
   If not, the DKIM-Signature header field MUST be ignored and the
   verifier should return PERMFAIL (domain mismatch).

   If the "h=" tag does not include the From header field, the verifier
   MUST ignore the DKIM-Signature header field and return PERMFAIL (From
   field not signed).

   Verifiers MAY ignore the DKIM-Signature header field and return
   PERMFAIL (signature expired) if it contains an "x=" tag and the
   signature has expired.

   Verifiers MAY ignore the DKIM-Signature header field if the domain
   used by the signer in the "d=" tag is not associated with a valid
   signing entity.  For example, signatures with "d=" values such as
   "com" and "co.uk" may be ignored.  The list of unacceptable domains
   SHOULD be configurable.

   Verifiers MAY ignore the DKIM-Signature header field and return
   PERMFAIL (unacceptable signature header) for any other reason, for
   example, if the signature does not sign header fields that the
   verifier views to be essential.  As a case in point, if MIME header
   fields are not signed, certain attacks may be possible that the
   verifier would prefer to avoid.

6.1.2.  Get the Public Key

   The public key for a signature is needed to complete the verification
   process.  The process of retrieving the public key depends on the
   query type as defined by the "q=" tag in the DKIM-Signature header
   field.  Obviously, a public key need only be retrieved if the process
   of extracting the signature information is completely successful.
   Details of key management and representation are described in
   Section 3.6.  The verifier MUST validate the key record and MUST
   ignore any public key records that are malformed.

   When validating a message, a verifier MUST perform the following
   steps in a manner that is semantically the same as performing them in



Allman, et al.              Standards Track                    [Page 43]

RFC 4871                    DKIM Signatures                     May 2007


   the order indicated (in some cases, the implementation may
   parallelize or reorder these steps, as long as the semantics remain
   unchanged):

   1.  Retrieve the public key as described in Section 3.6 using the
       algorithm in the "q=" tag, the domain from the "d=" tag, and the
       selector from the "s=" tag.

   2.  If the query for the public key fails to respond, the verifier
       MAY defer acceptance of this email and return TEMPFAIL (key
       unavailable).  If verification is occurring during the incoming
       SMTP session, this MAY be achieved with a 451/4.7.5 SMTP reply
       code.  Alternatively, the verifier MAY store the message in the
       local queue for later trial or ignore the signature.  Note that
       storing a message in the local queue is subject to denial-of-
       service attacks.

   3.  If the query for the public key fails because the corresponding
       key record does not exist, the verifier MUST immediately return
       PERMFAIL (no key for signature).

   4.  If the query for the public key returns multiple key records, the
       verifier may choose one of the key records or may cycle through
       the key records performing the remainder of these steps on each
       record at the discretion of the implementer.  The order of the
       key records is unspecified.  If the verifier chooses to cycle
       through the key records, then the "return ..." wording in the
       remainder of this section means "try the next key record, if any;
       if none, return to try another signature in the usual way".

   5.  If the result returned from the query does not adhere to the
       format defined in this specification, the verifier MUST ignore
       the key record and return PERMFAIL (key syntax error).  Verifiers
       are urged to validate the syntax of key records carefully to
       avoid attempted attacks.  In particular, the verifier MUST ignore
       keys with a version code ("v=" tag) that they do not implement.

   6.  If the "g=" tag in the public key does not match the Local-part
       of the "i=" tag in the message signature header field, the
       verifier MUST ignore the key record and return PERMFAIL
       (inapplicable key).  If the Local-part of the "i=" tag on the
       message signature is not present, the "g=" tag must be "*" (valid
       for all addresses in the domain) or the entire g= tag must be
       omitted (which defaults to "g=*"), otherwise the verifier MUST
       ignore the key record and return PERMFAIL (inapplicable key).
       Other than this test, verifiers SHOULD NOT treat a message signed
       with a key record having a "g=" tag any differently than one
       without; in particular, verifiers SHOULD NOT prefer messages that



Allman, et al.              Standards Track                    [Page 44]

RFC 4871                    DKIM Signatures                     May 2007


       seem to have an individual signature by virtue of a "g=" tag
       versus a domain signature.

   7.  If the "h=" tag exists in the public key record and the hash
       algorithm implied by the a= tag in the DKIM-Signature header
       field is not included in the contents of the "h=" tag, the
       verifier MUST ignore the key record and return PERMFAIL
       (inappropriate hash algorithm).

   8.  If the public key data (the "p=" tag) is empty, then this key has
       been revoked and the verifier MUST treat this as a failed
       signature check and return PERMFAIL (key revoked).  There is no
       defined semantic difference between a key that has been revoked
       and a key record that has been removed.

   9.  If the public key data is not suitable for use with the algorithm
       and key types defined by the "a=" and "k=" tags in the DKIM-
       Signature header field, the verifier MUST immediately return
       PERMFAIL (inappropriate key algorithm).

6.1.3.  Compute the Verification

   Given a signer and a public key, verifying a signature consists of
   actions semantically equivalent to the following steps.

   1.  Based on the algorithm defined in the "c=" tag, the body length
       specified in the "l=" tag, and the header field names in the "h="
       tag, prepare a canonicalized version of the message as is
       described in Section 3.7 (note that this version does not
       actually need to be instantiated).  When matching header field
       names in the "h=" tag against the actual message header field,
       comparisons MUST be case-insensitive.

   2.  Based on the algorithm indicated in the "a=" tag, compute the
       message hashes from the canonical copy as described in
       Section 3.7.

   3.  Verify that the hash of the canonicalized message body computed
       in the previous step matches the hash value conveyed in the "bh="
       tag.  If the hash does not match, the verifier SHOULD ignore the
       signature and return PERMFAIL (body hash did not verify).

   4.  Using the signature conveyed in the "b=" tag, verify the
       signature against the header hash using the mechanism appropriate
       for the public key algorithm described in the "a=" tag.  If the
       signature does not validate, the verifier SHOULD ignore the
       signature and return PERMFAIL (signature did not verify).




Allman, et al.              Standards Track                    [Page 45]

RFC 4871                    DKIM Signatures                     May 2007


   5.  Otherwise, the signature has correctly verified.

      INFORMATIVE IMPLEMENTER'S NOTE: Implementations might wish to
      initiate the public-key query in parallel with calculating the
      hash as the public key is not needed until the final decryption is
      calculated.  Implementations may also verify the signature on the
      message header before validating that the message hash listed in
      the "bh=" tag in the DKIM-Signature header field matches that of
      the actual message body; however, if the body hash does not match,
      the entire signature must be considered to have failed.

   A body length specified in the "l=" tag of the signature limits the
   number of bytes of the body passed to the verification algorithm.
   All data beyond that limit is not validated by DKIM.  Hence,
   verifiers might treat a message that contains bytes beyond the
   indicated body length with suspicion, such as by truncating the
   message at the indicated body length, declaring the signature invalid
   (e.g., by returning PERMFAIL (unsigned content)), or conveying the
   partial verification to the policy module.

      INFORMATIVE IMPLEMENTATION NOTE: Verifiers that truncate the body
      at the indicated body length might pass on a malformed MIME
      message if the signer used the "N-4" trick (omitting the final
      "--CRLF") described in the informative note in Section 3.4.5.
      Such verifiers may wish to check for this case and include a
      trailing "--CRLF" to avoid breaking the MIME structure.  A simple
      way to achieve this might be to append "--CRLF" to any "multipart"
      message with a body length; if the MIME structure is already
      correctly formed, this will appear in the postlude and will not be
      displayed to the end user.

6.2.  Communicate Verification Results

   Verifiers wishing to communicate the results of verification to other
   parts of the mail system may do so in whatever manner they see fit.
   For example, implementations might choose to add an email header
   field to the message before passing it on.  Any such header field
   SHOULD be inserted before any existing DKIM-Signature or preexisting
   authentication status header fields in the header field block.

      INFORMATIVE ADVICE to MUA filter writers: Patterns intended to
      search for results header fields to visibly mark authenticated
      mail for end users should verify that such header field was added
      by the appropriate verifying domain and that the verified identity
      matches the author identity that will be displayed by the MUA.  In
      particular, MUA filters should not be influenced by bogus results





Allman, et al.              Standards Track                    [Page 46]

RFC 4871                    DKIM Signatures                     May 2007


      header fields added by attackers.  To circumvent this attack,
      verifiers may wish to delete existing results header fields after
      verification and before adding a new header field.

6.3.  Interpret Results/Apply Local Policy

   It is beyond the scope of this specification to describe what actions
   a verifier system should make, but an authenticated email presents an
   opportunity to a receiving system that unauthenticated email cannot.
   Specifically, an authenticated email creates a predictable identifier
   by which other decisions can reliably be managed, such as trust and
   reputation.  Conversely, unauthenticated email lacks a reliable
   identifier that can be used to assign trust and reputation.  It is
   reasonable to treat unauthenticated email as lacking any trust and
   having no positive reputation.

   In general, verifiers SHOULD NOT reject messages solely on the basis
   of a lack of signature or an unverifiable signature; such rejection
   would cause severe interoperability problems.  However, if the
   verifier does opt to reject such messages (for example, when
   communicating with a peer who, by prior agreement, agrees to only
   send signed messages), and the verifier runs synchronously with the
   SMTP session and a signature is missing or does not verify, the MTA
   SHOULD use a 550/5.7.x reply code.

   If it is not possible to fetch the public key, perhaps because the
   key server is not available, a temporary failure message MAY be
   generated using a 451/4.7.5 reply code, such as:

      451 4.7.5 Unable to verify signature - key server unavailable

   Temporary failures such as inability to access the key server or
   other external service are the only conditions that SHOULD use a 4xx
   SMTP reply code.  In particular, cryptographic signature verification
   failures MUST NOT return 4xx SMTP replies.

   Once the signature has been verified, that information MUST be
   conveyed to higher-level systems (such as explicit allow/whitelists
   and reputation systems) and/or to the end user.  If the message is
   signed on behalf of any address other than that in the From: header
   field, the mail system SHOULD take pains to ensure that the actual
   signing identity is clear to the reader.

   The verifier MAY treat unsigned header fields with extreme
   skepticism, including marking them as untrusted or even deleting them
   before display to the end user.





Allman, et al.              Standards Track                    [Page 47]

RFC 4871                    DKIM Signatures                     May 2007


   While the symptoms of a failed verification are obvious -- the
   signature doesn't verify -- establishing the exact cause can be more
   difficult.  If a selector cannot be found, is that because the
   selector has been removed, or was the value changed somehow in
   transit?  If the signature line is missing, is that because it was
   never there, or was it removed by an overzealous filter?  For
   diagnostic purposes, the exact reason why the verification fails
   SHOULD be made available to the policy module and possibly recorded
   in the system logs.  If the email cannot be verified, then it SHOULD
   be rendered the same as all unverified email regardless of whether or
   not it looks like it was signed.

7.  IANA Considerations

   DKIM introduces some new namespaces that have been registered with
   IANA.  In all cases, new values are assigned only for values that
   have been documented in a published RFC that has IETF Consensus
   [RFC2434].

7.1.  DKIM-Signature Tag Specifications

   A DKIM-Signature provides for a list of tag specifications.  IANA has
   established the DKIM-Signature Tag Specification Registry for tag
   specifications that can be used in DKIM-Signature fields.

               The initial entries in the registry comprise:

                        +------+-----------------+
                        | TYPE | REFERENCE       |
                        +------+-----------------+
                        | v    | (this document) |
                        | a    | (this document) |
                        | b    | (this document) |
                        | bh   | (this document) |
                        | c    | (this document) |
                        | d    | (this document) |
                        | h    | (this document) |
                        | i    | (this document) |
                        | l    | (this document) |
                        | q    | (this document) |
                        | s    | (this document) |
                        | t    | (this document) |
                        | x    | (this document) |
                        | z    | (this document) |
                        +------+-----------------+

         DKIM-Signature Tag Specification Registry Initial Values




Allman, et al.              Standards Track                    [Page 48]

RFC 4871                    DKIM Signatures                     May 2007


7.2.  DKIM-Signature Query Method Registry

   The "q=" tag-spec (specified in Section 3.5) provides for a list of
   query methods.

   IANA has established the DKIM-Signature Query Method Registry for
   mechanisms that can be used to retrieve the key that will permit
   validation processing of a message signed using DKIM.

               The initial entry in the registry comprises:

                    +------+--------+-----------------+
                    | TYPE | OPTION | REFERENCE       |
                    +------+--------+-----------------+
                    | dns  | txt    | (this document) |
                    +------+--------+-----------------+

            DKIM-Signature Query Method Registry Initial Values

7.3.  DKIM-Signature Canonicalization Registry

   The "c=" tag-spec (specified in Section 3.5) provides for a specifier
   for canonicalization algorithms for the header and body of the
   message.

   IANA has established the DKIM-Signature Canonicalization Algorithm
   Registry for algorithms for converting a message into a canonical
   form before signing or verifying using DKIM.

           The initial entries in the header registry comprise:

                       +---------+-----------------+
                       | TYPE    | REFERENCE       |
                       +---------+-----------------+
                       | simple  | (this document) |
                       | relaxed | (this document) |
                       +---------+-----------------+

        DKIM-Signature Header Canonicalization Algorithm Registry
                              Initial Values











Allman, et al.              Standards Track                    [Page 49]

RFC 4871                    DKIM Signatures                     May 2007


            The initial entries in the body registry comprise:

                       +---------+-----------------+
                       | TYPE    | REFERENCE       |
                       +---------+-----------------+
                       | simple  | (this document) |
                       | relaxed | (this document) |
                       +---------+-----------------+

         DKIM-Signature Body Canonicalization Algorithm Registry
                              Initial Values

7.4.  _domainkey DNS TXT Record Tag Specifications

   A _domainkey DNS TXT record provides for a list of tag
   specifications.  IANA has established the DKIM _domainkey DNS TXT Tag
   Specification Registry for tag specifications that can be used in DNS
   TXT Records.

               The initial entries in the registry comprise:

                        +------+-----------------+
                        | TYPE | REFERENCE       |
                        +------+-----------------+
                        | v    | (this document) |
                        | g    | (this document) |
                        | h    | (this document) |
                        | k    | (this document) |
                        | n    | (this document) |
                        | p    | (this document) |
                        | s    | (this document) |
                        | t    | (this document) |
                        +------+-----------------+

         DKIM _domainkey DNS TXT Record Tag Specification Registry
                              Initial Values

7.5.  DKIM Key Type Registry

   The "k=" <key-k-tag> (specified in Section 3.6.1) and the "a=" <sig-
   a-tag-k> (specified in Section 3.5) tags provide for a list of
   mechanisms that can be used to decode a DKIM signature.

   IANA has established the DKIM Key Type Registry for such mechanisms.







Allman, et al.              Standards Track                    [Page 50]

RFC 4871                    DKIM Signatures                     May 2007


               The initial entry in the registry comprises:

                           +------+-----------+
                           | TYPE | REFERENCE |
                           +------+-----------+
                           | rsa  | [RFC3447] |
                           +------+-----------+

                       DKIM Key Type Initial Values

7.6.  DKIM Hash Algorithms Registry

   The "h=" <key-h-tag> (specified in Section 3.6.1) and the "a=" <sig-
   a-tag-h> (specified in Section 3.5) tags provide for a list of
   mechanisms that can be used to produce a digest of message data.

   IANA has established the DKIM Hash Algorithms Registry for such
   mechanisms.

               The initial entries in the registry comprise:

                      +--------+-------------------+
                      | TYPE   | REFERENCE         |
                      +--------+-------------------+
                      | sha1   | [FIPS.180-2.2002] |
                      | sha256 | [FIPS.180-2.2002] |
                      +--------+-------------------+

                    DKIM Hash Algorithms Initial Values

7.7.  DKIM Service Types Registry

   The "s=" <key-s-tag> tag (specified in Section 3.6.1) provides for a
   list of service types to which this selector may apply.

   IANA has established the DKIM Service Types Registry for service
   types.

               The initial entries in the registry comprise:

                        +-------+-----------------+
                        | TYPE  | REFERENCE       |
                        +-------+-----------------+
                        | email | (this document) |
                        | *     | (this document) |
                        +-------+-----------------+

                DKIM Service Types Registry Initial Values



Allman, et al.              Standards Track                    [Page 51]

RFC 4871                    DKIM Signatures                     May 2007


7.8.  DKIM Selector Flags Registry

   The "t=" <key-t-tag> tag (specified in Section 3.6.1) provides for a
   list of flags to modify interpretation of the selector.

   IANA has established the DKIM Selector Flags Registry for additional
   flags.

               The initial entries in the registry comprise:

                        +------+-----------------+
                        | TYPE | REFERENCE       |
                        +------+-----------------+
                        | y    | (this document) |
                        | s    | (this document) |
                        +------+-----------------+

                DKIM Selector Flags Registry Initial Values

7.9.  DKIM-Signature Header Field

   IANA has added DKIM-Signature to the "Permanent Message Header
   Fields" registry (see [RFC3864]) for the "mail" protocol, using this
   document as the reference.

8.  Security Considerations

   It has been observed that any mechanism that is introduced that
   attempts to stem the flow of spam is subject to intensive attack.
   DKIM needs to be carefully scrutinized to identify potential attack
   vectors and the vulnerability to each.  See also [RFC4686].

8.1.  Misuse of Body Length Limits ("l=" Tag)

   Body length limits (in the form of the "l=" tag) are subject to
   several potential attacks.

8.1.1.  Addition of New MIME Parts to Multipart/*

   If the body length limit does not cover a closing MIME multipart
   section (including the trailing "--CRLF" portion), then it is
   possible for an attacker to intercept a properly signed multipart
   message and add a new body part.  Depending on the details of the
   MIME type and the implementation of the verifying MTA and the
   receiving MUA, this could allow an attacker to change the information
   displayed to an end user from an apparently trusted source.





Allman, et al.              Standards Track                    [Page 52]

RFC 4871                    DKIM Signatures                     May 2007


   For example, if attackers can append information to a "text/html"
   body part, they may be able to exploit a bug in some MUAs that
   continue to read after a "</html>" marker, and thus display HTML text
   on top of already displayed text.  If a message has a
   "multipart/alternative" body part, they might be able to add a new
   body part that is preferred by the displaying MUA.

8.1.2.  Addition of new HTML content to existing content

   Several receiving MUA implementations do not cease display after a
   ""</html>"" tag.  In particular, this allows attacks involving
   overlaying images on top of existing text.

      INFORMATIVE EXAMPLE: Appending the following text to an existing,
      properly closed message will in many MUAs result in inappropriate
      data being rendered on top of existing, correct data:
   <div style="position: relative; bottom: 350px; z-index: 2;">
   <img src="http://www.ietf.org/images/ietflogo2e.gif"
     width=578 height=370>
   </div>

8.2.  Misappropriated Private Key

   If the private key for a user is resident on their computer and is
   not protected by an appropriately secure mechanism, it is possible
   for malware to send mail as that user and any other user sharing the
   same private key.  The malware would not, however, be able to
   generate signed spoofs of other signers' addresses, which would aid
   in identification of the infected user and would limit the
   possibilities for certain types of attacks involving socially
   engineered messages.  This threat applies mainly to MUA-based
   implementations; protection of private keys on servers can be easily
   achieved through the use of specialized cryptographic hardware.

   A larger problem occurs if malware on many users' computers obtains
   the private keys for those users and transmits them via a covert
   channel to a site where they can be shared.  The compromised users
   would likely not know of the misappropriation until they receive
   "bounce" messages from messages they are purported to have sent.
   Many users might not understand the significance of these bounce
   messages and would not take action.

   One countermeasure is to use a user-entered passphrase to encrypt the
   private key, although users tend to choose weak passphrases and often
   reuse them for different purposes, possibly allowing an attack
   against DKIM to be extended into other domains.  Nevertheless, the
   decoded private key might be briefly available to compromise by
   malware when it is entered, or might be discovered via keystroke



Allman, et al.              Standards Track                    [Page 53]

RFC 4871                    DKIM Signatures                     May 2007


   logging.  The added complexity of entering a passphrase each time one
   sends a message would also tend to discourage the use of a secure
   passphrase.

   A somewhat more effective countermeasure is to send messages through
   an outgoing MTA that can authenticate the submitter using existing
   techniques (e.g., SMTP Authentication), possibly validate the message
   itself (e.g., verify that the header is legitimate and that the
   content passes a spam content check), and sign the message using a
   key appropriate for the submitter address.  Such an MTA can also
   apply controls on the volume of outgoing mail each user is permitted
   to originate in order to further limit the ability of malware to
   generate bulk email.

8.3.  Key Server Denial-of-Service Attacks

   Since the key servers are distributed (potentially separate for each
   domain), the number of servers that would need to be attacked to
   defeat this mechanism on an Internet-wide basis is very large.
   Nevertheless, key servers for individual domains could be attacked,
   impeding the verification of messages from that domain.  This is not
   significantly different from the ability of an attacker to deny
   service to the mail exchangers for a given domain, although it
   affects outgoing, not incoming, mail.

   A variation on this attack is that if a very large amount of mail
   were to be sent using spoofed addresses from a given domain, the key
   servers for that domain could be overwhelmed with requests.  However,
   given the low overhead of verification compared with handling of the
   email message itself, such an attack would be difficult to mount.

8.4.  Attacks Against the DNS

   Since the DNS is a required binding for key services, specific
   attacks against the DNS must be considered.

   While the DNS is currently insecure [RFC3833], these security
   problems are the motivation behind DNS Security (DNSSEC) [RFC4033],
   and all users of the DNS will reap the benefit of that work.

   DKIM is only intended as a "sufficient" method of proving
   authenticity.  It is not intended to provide strong cryptographic
   proof about authorship or contents.  Other technologies such as
   OpenPGP [RFC2440] and S/MIME [RFC3851] address those requirements.

   A second security issue related to the DNS revolves around the
   increased DNS traffic as a consequence of fetching selector-based
   data as well as fetching signing domain policy.  Widespread



Allman, et al.              Standards Track                    [Page 54]

RFC 4871                    DKIM Signatures                     May 2007


   deployment of DKIM will result in a significant increase in DNS
   queries to the claimed signing domain.  In the case of forgeries on a
   large scale, DNS servers could see a substantial increase in queries.

   A specific DNS security issue that should be considered by DKIM
   verifiers is the name chaining attack described in Section 2.3 of the
   DNS Threat Analysis [RFC3833].  A DKIM verifier, while verifying a
   DKIM-Signature header field, could be prompted to retrieve a key
   record of an attacker's choosing.  This threat can be minimized by
   ensuring that name servers, including recursive name servers, used by
   the verifier enforce strict checking of "glue" and other additional
   information in DNS responses and are therefore not vulnerable to this
   attack.

8.5.  Replay Attacks

   In this attack, a spammer sends a message to be spammed to an
   accomplice, which results in the message being signed by the
   originating MTA.  The accomplice resends the message, including the
   original signature, to a large number of recipients, possibly by
   sending the message to many compromised machines that act as MTAs.
   The messages, not having been modified by the accomplice, have valid
   signatures.

   Partial solutions to this problem involve the use of reputation
   services to convey the fact that the specific email address is being
   used for spam and that messages from that signer are likely to be
   spam.  This requires a real-time detection mechanism in order to
   react quickly enough.  However, such measures might be prone to
   abuse, if for example an attacker resent a large number of messages
   received from a victim in order to make them appear to be a spammer.

   Large verifiers might be able to detect unusually large volumes of
   mails with the same signature in a short time period.  Smaller
   verifiers can get substantially the same volume of information via
   existing collaborative systems.

8.6.  Limits on Revoking Keys

   When a large domain detects undesirable behavior on the part of one
   of its users, it might wish to revoke the key used to sign that
   user's messages in order to disavow responsibility for messages that
   have not yet been verified or that are the subject of a replay
   attack.  However, the ability of the domain to do so can be limited
   if the same key, for scalability reasons, is used to sign messages
   for many other users.  Mechanisms for explicitly revoking keys on a
   per-address basis have been proposed but require further study as to
   their utility and the DNS load they represent.



Allman, et al.              Standards Track                    [Page 55]

RFC 4871                    DKIM Signatures                     May 2007


8.7.  Intentionally Malformed Key Records

   It is possible for an attacker to publish key records in DNS that are
   intentionally malformed, with the intent of causing a denial-of-
   service attack on a non-robust verifier implementation.  The attacker
   could then cause a verifier to read the malformed key record by
   sending a message to one of its users referencing the malformed
   record in a (not necessarily valid) signature.  Verifiers MUST
   thoroughly verify all key records retrieved from the DNS and be
   robust against intentionally as well as unintentionally malformed key
   records.

8.8.  Intentionally Malformed DKIM-Signature Header Fields

   Verifiers MUST be prepared to receive messages with malformed DKIM-
   Signature header fields, and thoroughly verify the header field
   before depending on any of its contents.

8.9.  Information Leakage

   An attacker could determine when a particular signature was verified
   by using a per-message selector and then monitoring their DNS traffic
   for the key lookup.  This would act as the equivalent of a "web bug"
   for verification time rather than when the message was read.

8.10.  Remote Timing Attacks

   In some cases, it may be possible to extract private keys using a
   remote timing attack [BONEH03].  Implementations should consider
   obfuscating the timing to prevent such attacks.

8.11.  Reordered Header Fields

   Existing standards allow intermediate MTAs to reorder header fields.
   If a signer signs two or more header fields of the same name, this
   can cause spurious verification errors on otherwise legitimate
   messages.  In particular, signers that sign any existing DKIM-
   Signature fields run the risk of having messages incorrectly fail to
   verify.

8.12.  RSA Attacks

   An attacker could create a large RSA signing key with a small
   exponent, thus requiring that the verification key have a large
   exponent.  This will force verifiers to use considerable computing
   resources to verify the signature.  Verifiers might avoid this attack
   by refusing to verify signatures that reference selectors with public
   keys having unreasonable exponents.



Allman, et al.              Standards Track                    [Page 56]

RFC 4871                    DKIM Signatures                     May 2007


   In general, an attacker might try to overwhelm a verifier by flooding
   it with messages requiring verification.  This is similar to other
   MTA denial-of-service attacks and should be dealt with in a similar
   fashion.

8.13.  Inappropriate Signing by Parent Domains

   The trust relationship described in Section 3.8 could conceivably be
   used by a parent domain to sign messages with identities in a
   subdomain not administratively related to the parent.  For example,
   the ".com" registry could create messages with signatures using an
   "i=" value in the example.com domain.  There is no general solution
   to this problem, since the administrative cut could occur anywhere in
   the domain name.  For example, in the domain "example.podunk.ca.us"
   there are three administrative cuts (podunk.ca.us, ca.us, and us),
   any of which could create messages with an identity in the full
   domain.

      INFORMATIVE NOTE: This is considered an acceptable risk for the
      same reason that it is acceptable for domain delegation.  For
      example, in the example above any of the domains could potentially
      simply delegate "example.podunk.ca.us" to a server of their choice
      and completely replace all DNS-served information.  Note that a
      verifier MAY ignore signatures that come from an unlikely domain
      such as ".com", as discussed in Section 6.1.1.

9.  References

9.1.  Normative References

   [FIPS.180-2.2002]  U.S. Department of Commerce, "Secure Hash
                      Standard", FIPS PUB 180-2, August 2002.

   [ITU.X660.1997]    "Information Technology - ASN.1 encoding rules:
                      Specification of Basic Encoding Rules (BER),
                      Canonical Encoding Rules (CER) and Distinguished
                      Encoding Rules (DER)", ITU-T Recommendation X.660,
                      1997.

   [RFC2045]          Freed, N. and N. Borenstein, "Multipurpose
                      Internet Mail Extensions (MIME) Part One: Format
                      of Internet Message Bodies", RFC 2045,
                      November 1996.

   [RFC2047]          Moore, K., "MIME (Multipurpose Internet Mail
                      Extensions) Part Three: Message header field
                      Extensions for Non-ASCII Text", RFC 2047,
                      November 1996.



Allman, et al.              Standards Track                    [Page 57]

RFC 4871                    DKIM Signatures                     May 2007


   [RFC2119]          Bradner, S., "Key words for use in RFCs to
                      Indicate Requirement Levels", BCP 14, RFC 2119,
                      March 1997.

   [RFC2821]          Klensin, J., "Simple Mail Transfer Protocol",
                      RFC 2821, April 2001.

   [RFC2822]          Resnick, P., "Internet Message Format", RFC 2822,
                      April 2001.

   [RFC3447]          Jonsson, J. and B. Kaliski, "Public-Key
                      Cryptography Standards (PKCS) #1: RSA Cryptography
                      Specifications Version 2.1", RFC 3447,
                      February 2003.

   [RFC3490]          Faltstrom, P., Hoffman, P., and A. Costello,
                      "Internationalizing Domain Names in Applications
                      (IDNA)", RFC 3490, March 2003.

   [RFC4234]          Crocker, D., Ed. and P. Overell, "Augmented BNF
                      for Syntax Specifications: ABNF", RFC 4234,
                      October 2005.

9.2.  Informative References

   [BONEH03]          Proc. 12th USENIX Security Symposium, "Remote
                      Timing Attacks are Practical", 2003.

   [RFC1847]          Galvin, J., Murphy, S., Crocker, S., and N. Freed,
                      "Security Multiparts for MIME: Multipart/Signed
                      and Multipart/Encrypted", RFC 1847, October 1995.

   [RFC2434]          Narten, T. and H. Alvestrand, "Guidelines for
                      Writing an IANA Considerations Section in RFCs",
                      BCP 26, RFC 2434, October 1998.

   [RFC2440]          Callas, J., Donnerhacke, L., Finney, H., and R.
                      Thayer, "OpenPGP Message Format", RFC 2440,
                      November 1998.

   [RFC3766]          Orman, H. and P. Hoffman, "Determining Strengths
                      for Public Keys Used For Exchanging Symmetric
                      Keys", RFC 3766, April 2004.

   [RFC3833]          Atkins, D. and R. Austein, "Threat Analysis of the
                      Domain Name System (DNS)", RFC 3833, August 2004.





Allman, et al.              Standards Track                    [Page 58]

RFC 4871                    DKIM Signatures                     May 2007


   [RFC3851]          Ramsdell, B., "S/MIME Version 3 Message
                      Specification", RFC 3851, June 1999.

   [RFC3864]          Klyne, G., Nottingham, M., and J. Mogul,
                      "Registration Procedures for Message Header
                      Fields", BCP 90, September 2004.

   [RFC4033]          Arends, R., Austein, R., Larson, M., Massey, D.,
                      and S. Rose, "DNS Security Introduction and
                      Requirements", RFC 4033, March 2005.

   [RFC4686]          Fenton, J., "Analysis of Threats Motivating
                      DomainKeys Identified Mail (DKIM)", RFC 4686,
                      September 2006.

   [RFC4870]          Delany, M., "Domain-Based Email Authentication
                      Using Public Keys Advertised in the DNS
                      (DomainKeys)", RFC 4870, May 2007.

































Allman, et al.              Standards Track                    [Page 59]

RFC 4871                    DKIM Signatures                     May 2007


Appendix A.  Example of Use (INFORMATIVE)

   This section shows the complete flow of an email from submission to
   final delivery, demonstrating how the various components fit
   together.  The key used in this example is shown in Appendix C.

A.1.  The User Composes an Email


   From: Joe SixPack <joe@football.example.com>
   To: Suzie Q <suzie@shopping.example.net>
   Subject: Is dinner ready?
   Date: Fri, 11 Jul 2003 21:00:37 -0700 (PDT)
   Message-ID: <20030712040037.46341.5F8J@football.example.com>

   Hi.

   We lost the game. Are you hungry yet?

   Joe.































Allman, et al.              Standards Track                    [Page 60]

RFC 4871                    DKIM Signatures                     May 2007


A.2.  The Email Is Signed

   This email is signed by the example.com outbound email server and now
   looks like this:

   DKIM-Signature: v=1; a=rsa-sha256; s=brisbane; d=example.com;
         c=simple/simple; q=dns/txt; i=joe@football.example.com;
         h=Received : From : To : Subject : Date : Message-ID;
         bh=2jUSOH9NhtVGCQWNr9BrIAPreKQjO6Sn7XIkfJVOzv8=;
         b=AuUoFEfDxTDkHlLXSZEpZj79LICEps6eda7W3deTVFOk4yAUoqOB
           4nujc7YopdG5dWLSdNg6xNAZpOPr+kHxt1IrE+NahM6L/LbvaHut
           KVdkLLkpVaVVQPzeRDI009SO2Il5Lu7rDNH6mZckBdrIx0orEtZV
           4bmp/YzhwvcubU4=;
   Received: from client1.football.example.com  [192.0.2.1]
         by submitserver.example.com with SUBMISSION;
         Fri, 11 Jul 2003 21:01:54 -0700 (PDT)
   From: Joe SixPack <joe@football.example.com>
   To: Suzie Q <suzie@shopping.example.net>
   Subject: Is dinner ready?
   Date: Fri, 11 Jul 2003 21:00:37 -0700 (PDT)
   Message-ID: <20030712040037.46341.5F8J@football.example.com>

   Hi.

   We lost the game. Are you hungry yet?

   Joe.

   The signing email server requires access to the private key
   associated with the "brisbane" selector to generate this signature.

A.3.  The Email Signature Is Verified

   The signature is normally verified by an inbound SMTP server or
   possibly the final delivery agent.  However, intervening MTAs can
   also perform this verification if they choose to do so.  The
   verification process uses the domain "example.com" extracted from the
   "d=" tag and the selector "brisbane" from the "s=" tag in the DKIM-
   Signature header field to form the DNS DKIM query for:

   brisbane._domainkey.example.com

   Signature verification starts with the physically last Received
   header field, the From header field, and so forth, in the order
   listed in the "h=" tag.  Verification follows with a single CRLF
   followed by the body (starting with "Hi.").  The email is canonically
   prepared for verifying with the "simple" method.  The result of the
   query and subsequent verification of the signature is stored (in this



Allman, et al.              Standards Track                    [Page 61]

RFC 4871                    DKIM Signatures                     May 2007


   example) in the X-Authentication-Results header field line.  After
   successful verification, the email looks like this:

   X-Authentication-Results: shopping.example.net
         header.from=joe@football.example.com; dkim=pass
   Received: from mout23.football.example.com (192.168.1.1)
         by shopping.example.net with SMTP;
         Fri, 11 Jul 2003 21:01:59 -0700 (PDT)
   DKIM-Signature: v=1; a=rsa-sha256; s=brisbane; d=example.com;
         c=simple/simple; q=dns/txt; i=joe@football.example.com;
         h=Received : From : To : Subject : Date : Message-ID;
         bh=2jUSOH9NhtVGCQWNr9BrIAPreKQjO6Sn7XIkfJVOzv8=;
         b=AuUoFEfDxTDkHlLXSZEpZj79LICEps6eda7W3deTVFOk4yAUoqOB
           4nujc7YopdG5dWLSdNg6xNAZpOPr+kHxt1IrE+NahM6L/LbvaHut
           KVdkLLkpVaVVQPzeRDI009SO2Il5Lu7rDNH6mZckBdrIx0orEtZV
           4bmp/YzhwvcubU4=;
   Received: from client1.football.example.com  [192.0.2.1]
         by submitserver.example.com with SUBMISSION;
         Fri, 11 Jul 2003 21:01:54 -0700 (PDT)
   From: Joe SixPack <joe@football.example.com>
   To: Suzie Q <suzie@shopping.example.net>
   Subject: Is dinner ready?
   Date: Fri, 11 Jul 2003 21:00:37 -0700 (PDT)
   Message-ID: <20030712040037.46341.5F8J@football.example.com>

   Hi.

   We lost the game. Are you hungry yet?

   Joe.

Appendix B.  Usage Examples (INFORMATIVE)

   DKIM signing and validating can be used in different ways, for
   different operational scenarios.  This Appendix discusses some common
   examples.

      NOTE: Descriptions in this Appendix are for informational purposes
      only.  They describe various ways that DKIM can be used, given
      particular constraints and needs.  In no case are these examples
      intended to be taken as providing explanation or guidance
      concerning DKIM specification details, when creating an
      implementation.








Allman, et al.              Standards Track                    [Page 62]

RFC 4871                    DKIM Signatures                     May 2007


B.1.  Alternate Submission Scenarios

   In the most simple scenario, a user's MUA, MSA, and Internet
   (boundary) MTA are all within the same administrative environment,
   using the same domain name.  Therefore, all of the components
   involved in submission and initial transfer are related.  However, it
   is common for two or more of the components to be under independent
   administrative control.  This creates challenges for choosing and
   administering the domain name to use for signing, and for its
   relationship to common email identity header fields.

B.1.1.  Delegated Business Functions

   Some organizations assign specific business functions to discrete
   groups, inside or outside the organization.  The goal, then, is to
   authorize that group to sign some mail, but to constrain what
   signatures they can generate.  DKIM selectors (the "s=" signature
   tag) and granularity (the "g=" key tag) facilitate this kind of
   restricted authorization.  Examples of these outsourced business
   functions are legitimate email marketing providers and corporate
   benefits providers.

   Here, the delegated group needs to be able to send messages that are
   signed, using the email domain of the client company.  At the same
   time, the client often is reluctant to register a key for the
   provider that grants the ability to send messages for arbitrary
   addresses in the domain.

   There are multiple ways to administer these usage scenarios.  In one
   case, the client organization provides all of the public query
   service (for example, DNS) administration, and in another it uses DNS
   delegation to enable all ongoing administration of the DKIM key
   record by the delegated group.

   If the client organization retains responsibility for all of the DNS
   administration, the outsourcing company can generate a key pair,
   supplying the public key to the client company, which then registers
   it in the query service, using a unique selector that authorizes a
   specific From header field Local-part.  For example, a client with
   the domain "example.com" could have the selector record specify
   "g=winter-promotions" so that this signature is only valid for mail
   with a From address of "winter-promotions@example.com".  This would
   enable the provider to send messages using that specific address and
   have them verify properly.  The client company retains control over
   the email address because it retains the ability to revoke the key at
   any time.





Allman, et al.              Standards Track                    [Page 63]

RFC 4871                    DKIM Signatures                     May 2007


   If the client wants the delegated group to do the DNS administration,
   it can have the domain name that is specified with the selector point
   to the provider's DNS server.  The provider then creates and
   maintains all of the DKIM signature information for that selector.
   Hence, the client cannot provide constraints on the Local-part of
   addresses that get signed, but it can revoke the provider's signing
   rights by removing the DNS delegation record.

B.1.2.  PDAs and Similar Devices

   PDAs demonstrate the need for using multiple keys per domain.
   Suppose that John Doe wanted to be able to send messages using his
   corporate email address, jdoe@example.com, and his email device did
   not have the ability to make a Virtual Private Network (VPN)
   connection to the corporate network, either because the device is
   limited or because there are restrictions enforced by his Internet
   access provider.  If the device was equipped with a private key
   registered for jdoe@example.com by the administrator of the
   example.com domain, and appropriate software to sign messages, John
   could sign the message on the device itself before transmission
   through the outgoing network of the access service provider.

B.1.3.  Roaming Users

   Roaming users often find themselves in circumstances where it is
   convenient or necessary to use an SMTP server other than their home
   server; examples are conferences and many hotels.  In such
   circumstances, a signature that is added by the submission service
   will use an identity that is different from the user's home system.

   Ideally, roaming users would connect back to their home server using
   either a VPN or a SUBMISSION server running with SMTP AUTHentication
   on port 587.  If the signing can be performed on the roaming user's
   laptop, then they can sign before submission, although the risk of
   further modification is high.  If neither of these are possible,
   these roaming users will not be able to send mail signed using their
   own domain key.

B.1.4.  Independent (Kiosk) Message Submission

   Stand-alone services, such as walk-up kiosks and web-based
   information services, have no enduring email service relationship
   with the user, but users occasionally request that mail be sent on
   their behalf.  For example, a website providing news often allows the
   reader to forward a copy of the article to a friend.  This is
   typically done using the reader's own email address, to indicate who
   the author is.  This is sometimes referred to as the "Evite problem",




Allman, et al.              Standards Track                    [Page 64]

RFC 4871                    DKIM Signatures                     May 2007


   named after the website of the same name that allows a user to send
   invitations to friends.

   A common way this is handled is to continue to put the reader's email
   address in the From header field of the message, but put an address
   owned by the email posting site into the Sender header field.  The
   posting site can then sign the message, using the domain that is in
   the Sender field.  This provides useful information to the receiving
   email site, which is able to correlate the signing domain with the
   initial submission email role.

   Receiving sites often wish to provide their end users with
   information about mail that is mediated in this fashion.  Although
   the real efficacy of different approaches is a subject for human
   factors usability research, one technique that is used is for the
   verifying system to rewrite the From header field, to indicate the
   address that was verified.  For example: From: John Doe via
   news@news-site.com <jdoe@example.com>.  (Note that such rewriting
   will break a signature, unless it is done after the verification pass
   is complete.)

B.2.  Alternate Delivery Scenarios

   Email is often received at a mailbox that has an address different
   from the one used during initial submission.  In these cases, an
   intermediary mechanism operates at the address originally used and it
   then passes the message on to the final destination.  This mediation
   process presents some challenges for DKIM signatures.

B.2.1.  Affinity Addresses

   "Affinity addresses" allow a user to have an email address that
   remains stable, even as the user moves among different email
   providers.  They are typically associated with college alumni
   associations, professional organizations, and recreational
   organizations with which they expect to have a long-term
   relationship.  These domains usually provide forwarding of incoming
   email, and they often have an associated Web application that
   authenticates the user and allows the forwarding address to be
   changed.  However, these services usually depend on users sending
   outgoing messages through their own service providers' MTAs.  Hence,
   mail that is signed with the domain of the affinity address is not
   signed by an entity that is administered by the organization owning
   that domain.

   With DKIM, affinity domains could use the Web application to allow
   users to register per-user keys to be used to sign messages on behalf
   of their affinity address.  The user would take away the secret half



Allman, et al.              Standards Track                    [Page 65]

RFC 4871                    DKIM Signatures                     May 2007


   of the key pair for signing, and the affinity domain would publish
   the public half in DNS for access by verifiers.

   This is another application that takes advantage of user-level
   keying, and domains used for affinity addresses would typically have
   a very large number of user-level keys.  Alternatively, the affinity
   domain could handle outgoing mail, operating a mail submission agent
   that authenticates users before accepting and signing messages for
   them.  This is of course dependent on the user's service provider not
   blocking the relevant TCP ports used for mail submission.

B.2.2.  Simple Address Aliasing (.forward)

   In some cases, a recipient is allowed to configure an email address
   to cause automatic redirection of email messages from the original
   address to another, such as through the use of a Unix .forward file.
   In this case, messages are typically redirected by the mail handling
   service of the recipient's domain, without modification, except for
   the addition of a Received header field to the message and a change
   in the envelope recipient address.  In this case, the recipient at
   the final address' mailbox is likely to be able to verify the
   original signature since the signed content has not changed, and DKIM
   is able to validate the message signature.

B.2.3.  Mailing Lists and Re-Posters

   There is a wide range of behaviors in services that take delivery of
   a message and then resubmit it.  A primary example is with mailing
   lists (collectively called "forwarders" below), ranging from those
   that make no modification to the message itself, other than to add a
   Received header field and change the envelope information, to those
   that add header fields, change the Subject header field, add content
   to the body (typically at the end), or reformat the body in some
   manner.  The simple ones produce messages that are quite similar to
   the automated alias services.  More elaborate systems essentially
   create a new message.

   A Forwarder that does not modify the body or signed header fields of
   a message is likely to maintain the validity of the existing
   signature.  It also could choose to add its own signature to the
   message.

   Forwarders which modify a message in a way that could make an
   existing signature invalid are particularly good candidates for
   adding their own signatures (e.g., mailing-list-name@example.net).
   Since (re-)signing is taking responsibility for the content of the
   message, these signing forwarders are likely to be selective, and
   forward or re-sign a message only if it is received with a valid



Allman, et al.              Standards Track                    [Page 66]

RFC 4871                    DKIM Signatures                     May 2007


   signature or if they have some other basis for knowing that the
   message is not spoofed.

   A common practice among systems that are primarily redistributors of
   mail is to add a Sender header field to the message, to identify the
   address being used to sign the message.  This practice will remove
   any preexisting Sender header field as required by [RFC2822].  The
   forwarder applies a new DKIM-Signature header field with the
   signature, public key, and related information of the forwarder.

Appendix C.  Creating a Public Key (INFORMATIVE)

   The default signature is an RSA signed SHA256 digest of the complete
   email.  For ease of explanation, the openssl command is used to
   describe the mechanism by which keys and signatures are managed.  One
   way to generate a 1024-bit, unencrypted private key suitable for DKIM
   is to use openssl like this:

   $ openssl genrsa -out rsa.private 1024

   For increased security, the "-passin" parameter can also be added to
   encrypt the private key.  Use of this parameter will require entering
   a password for several of the following steps.  Servers may prefer to
   use hardware cryptographic support.

   The "genrsa" step results in the file rsa.private containing the key
   information similar to this:

    -----BEGIN RSA PRIVATE KEY-----
    MIICXwIBAAKBgQDwIRP/UC3SBsEmGqZ9ZJW3/DkMoGeLnQg1fWn7/zYtIxN2SnFC
    jxOCKG9v3b4jYfcTNh5ijSsq631uBItLa7od+v/RtdC2UzJ1lWT947qR+Rcac2gb
    to/NMqJ0fzfVjH4OuKhitdY9tf6mcwGjaNBcWToIMmPSPDdQPNUYckcQ2QIDAQAB
    AoGBALmn+XwWk7akvkUlqb+dOxyLB9i5VBVfje89Teolwc9YJT36BGN/l4e0l6QX
    /1//6DWUTB3KI6wFcm7TWJcxbS0tcKZX7FsJvUz1SbQnkS54DJck1EZO/BLa5ckJ
    gAYIaqlA9C0ZwM6i58lLlPadX/rtHb7pWzeNcZHjKrjM461ZAkEA+itss2nRlmyO
    n1/5yDyCluST4dQfO8kAB3toSEVc7DeFeDhnC1mZdjASZNvdHS4gbLIA1hUGEF9m
    3hKsGUMMPwJBAPW5v/U+AWTADFCS22t72NUurgzeAbzb1HWMqO4y4+9Hpjk5wvL/
    eVYizyuce3/fGke7aRYw/ADKygMJdW8H/OcCQQDz5OQb4j2QDpPZc0Nc4QlbvMsj
    7p7otWRO5xRa6SzXqqV3+F0VpqvDmshEBkoCydaYwc2o6WQ5EBmExeV8124XAkEA
    qZzGsIxVP+sEVRWZmW6KNFSdVUpk3qzK0Tz/WjQMe5z0UunY9Ax9/4PVhp/j61bf
    eAYXunajbBSOLlx4D+TunwJBANkPI5S9iylsbLs6NkaMHV6k5ioHBBmgCak95JGX
    GMot/L2x0IYyMLAz6oLWh2hm7zwtb0CgOrPo1ke44hFYnfc=
    -----END RSA PRIVATE KEY-----

   To extract the public-key component from the private key, use openssl
   like this:

   $ openssl rsa -in rsa.private -out rsa.public -pubout -outform PEM



Allman, et al.              Standards Track                    [Page 67]

RFC 4871                    DKIM Signatures                     May 2007


   This results in the file rsa.public containing the key information
   similar to this:

   -----BEGIN PUBLIC KEY-----
   MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDwIRP/UC3SBsEmGqZ9ZJW3/DkM
   oGeLnQg1fWn7/zYtIxN2SnFCjxOCKG9v3b4jYfcTNh5ijSsq631uBItLa7od+v/R
   tdC2UzJ1lWT947qR+Rcac2gbto/NMqJ0fzfVjH4OuKhitdY9tf6mcwGjaNBcWToI
   MmPSPDdQPNUYckcQ2QIDAQAB
   -----END PUBLIC KEY-----

   This public-key data (without the BEGIN and END tags) is placed in
   the DNS:

   brisbane IN  TXT  ("v=DKIM1; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQ"
                      "KBgQDwIRP/UC3SBsEmGqZ9ZJW3/DkMoGeLnQg1fWn7/zYt"
                      "IxN2SnFCjxOCKG9v3b4jYfcTNh5ijSsq631uBItLa7od+v"
                      "/RtdC2UzJ1lWT947qR+Rcac2gbto/NMqJ0fzfVjH4OuKhi"
                      "tdY9tf6mcwGjaNBcWToIMmPSPDdQPNUYckcQ2QIDAQAB")

Appendix D.  MUA Considerations

   When a DKIM signature is verified, the processing system sometimes
   makes the result available to the recipient user's MUA.  How to
   present this information to the user in a way that helps them is a
   matter of continuing human factors usability research.  The tendency
   is to have the MUA highlight the address associated with this signing
   identity in some way, in an attempt to show the user the address from
   which the mail was sent.  An MUA might do this with visual cues such
   as graphics, or it might include the address in an alternate view, or
   it might even rewrite the original From address using the verified
   information.  Some MUAs might indicate which header fields were
   protected by the validated DKIM signature.  This could be done with a
   positive indication on the signed header fields, with a negative
   indication on the unsigned header fields, by visually hiding the
   unsigned header fields, or some combination of these.  If an MUA uses
   visual indications for signed header fields, the MUA probably needs
   to be careful not to display unsigned header fields in a way that
   might be construed by the end user as having been signed.  If the
   message has an l= tag whose value does not extend to the end of the
   message, the MUA might also hide or mark the portion of the message
   body that was not signed.

   The aforementioned information is not intended to be exhaustive.  The
   MUA may choose to highlight, accentuate, hide, or otherwise display
   any other information that may, in the opinion of the MUA author, be
   deemed important to the end user.





Allman, et al.              Standards Track                    [Page 68]

RFC 4871                    DKIM Signatures                     May 2007


Appendix E.  Acknowledgements

   The authors wish to thank Russ Allbery, Edwin Aoki, Claus Assmann,
   Steve Atkins, Rob Austein, Fred Baker, Mark Baugher, Steve Bellovin,
   Nathaniel Borenstein, Dave Crocker, Michael Cudahy, Dennis Dayman,
   Jutta Degener, Frank Ellermann, Patrik Faeltstroem, Mark Fanto,
   Stephen Farrell, Duncan Findlay, Elliot Gillum, Olafur
   Gu[eth]mundsson, Phillip Hallam-Baker, Tony Hansen, Sam Hartman,
   Arvel Hathcock, Amir Herzberg, Paul Hoffman, Russ Housley, Craig
   Hughes, Cullen Jennings, Don Johnsen, Harry Katz, Murray S.
   Kucherawy, Barry Leiba, John Levine, Charles Lindsey, Simon
   Longsdale, David Margrave, Justin Mason, David Mayne, Thierry Moreau,
   Steve Murphy, Russell Nelson, Dave Oran, Doug Otis, Shamim Pirzada,
   Juan Altmayer Pizzorno, Sanjay Pol, Blake Ramsdell, Christian Renaud,
   Scott Renfro, Neil Rerup, Eric Rescorla, Dave Rossetti, Hector
   Santos, Jim Schaad, the Spamhaus.org team, Malte S. Stretz, Robert
   Sanders, Rand Wacker, Sam Weiler, and Dan Wing for their valuable
   suggestions and constructive criticism.

   The DomainKeys specification was a primary source from which this
   specification has been derived.  Further information about DomainKeys
   is at [RFC4870].

Authors' Addresses

   Eric Allman
   Sendmail, Inc.
   6425 Christie Ave, Suite 400
   Emeryville, CA  94608
   USA

   Phone: +1 510 594 5501
   EMail: eric+dkim@sendmail.org
   URI:


   Jon Callas
   PGP Corporation
   3460 West Bayshore
   Palo Alto, CA  94303
   USA

   Phone: +1 650 319 9016
   EMail: jon@pgp.com







Allman, et al.              Standards Track                    [Page 69]

RFC 4871                    DKIM Signatures                     May 2007


   Mark Delany
   Yahoo! Inc
   701 First Avenue
   Sunnyvale, CA  95087
   USA

   Phone: +1 408 349 6831
   EMail: markd+dkim@yahoo-inc.com
   URI:


   Miles Libbey
   Yahoo! Inc
   701 First Avenue
   Sunnyvale, CA  95087
   USA

   EMail: mlibbeymail-mailsig@yahoo.com
   URI:


   Jim Fenton
   Cisco Systems, Inc.
   MS SJ-9/2
   170 W. Tasman Drive
   San Jose, CA  95134-1706
   USA

   Phone: +1 408 526 5914
   EMail: fenton@cisco.com
   URI:


   Michael Thomas
   Cisco Systems, Inc.
   MS SJ-9/2
   170 W. Tasman Drive
   San Jose, CA  95134-1706

   Phone: +1 408 525 5386
   EMail: mat@cisco.com










Allman, et al.              Standards Track                    [Page 70]

RFC 4871                    DKIM Signatures                     May 2007


Full Copyright Statement

   Copyright (C) The IETF Trust (2007).

   This document is subject to the rights, licenses and restrictions
   contained in BCP 78, and except as set forth therein, the authors
   retain all their rights.

   This document and the information contained herein are provided on an
   "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
   OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND
   THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS
   OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
   THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
   WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Intellectual Property

   The IETF takes no position regarding the validity or scope of any
   Intellectual Property Rights or other rights that might be claimed to
   pertain to the implementation or use of the technology described in
   this document or the extent to which any license under such rights
   might or might not be available; nor does it represent that it has
   made any independent effort to identify any such rights.  Information
   on the procedures with respect to rights in RFC documents can be
   found in BCP 78 and BCP 79.

   Copies of IPR disclosures made to the IETF Secretariat and any
   assurances of licenses to be made available, or the result of an
   attempt made to obtain a general license or permission for the use of
   such proprietary rights by implementers or users of this
   specification can be obtained from the IETF on-line IPR repository at
   http://www.ietf.org/ipr.

   The IETF invites any interested party to bring to its attention any
   copyrights, patents or patent applications, or other proprietary
   rights that may cover technology that may be required to implement
   this standard.  Please address the information to the IETF at
   ietf-ipr@ietf.org.

Acknowledgement

   Funding for the RFC Editor function is currently provided by the
   Internet Society.







Allman, et al.              Standards Track                    [Page 71]



================================================
FILE: doc/notes/rfc/rfc4880.txt
================================================





Network Working Group                                          J. Callas
Request for Comments: 4880                               PGP Corporation
Obsoletes: 1991, 2440                                     L. Donnerhacke
Category: Standards Track                                       IKS GmbH
                                                               H. Finney
                                                         PGP Corporation
                                                                 D. Shaw
                                                               R. Thayer
                                                           November 2007


                         OpenPGP Message Format

Status of This Memo

   This document specifies an Internet standards track protocol for the
   Internet community, and requests discussion and suggestions for
   improvements.  Please refer to the current edition of the "Internet
   Official Protocol Standards" (STD 1) for the standardization state
   and status of this protocol.  Distribution of this memo is unlimited.

Abstract

   This document is maintained in order to publish all necessary
   information needed to develop interoperable applications based on the
   OpenPGP format.  It is not a step-by-step cookbook for writing an
   application.  It describes only the format and methods needed to
   read, check, generate, and write conforming packets crossing any
   network.  It does not deal with storage and implementation questions.
   It does, however, discuss implementation issues necessary to avoid
   security flaws.

   OpenPGP software uses a combination of strong public-key and
   symmetric cryptography to provide security services for electronic
   communications and data storage.  These services include
   confidentiality, key management, authentication, and digital
   signatures.  This document specifies the message formats used in
   OpenPGP.













Callas, et al               Standards Track                     [Page 1]

RFC 4880                 OpenPGP Message Format            November 2007


Table of Contents

   1. Introduction ....................................................5
      1.1. Terms ......................................................5
   2. General functions ...............................................6
      2.1. Confidentiality via Encryption .............................6
      2.2. Authentication via Digital Signature .......................7
      2.3. Compression ................................................7
      2.4. Conversion to Radix-64 .....................................8
      2.5. Signature-Only Applications ................................8
   3. Data Element Formats ............................................8
      3.1. Scalar Numbers .............................................8
      3.2. Multiprecision Integers ....................................9
      3.3. Key IDs ....................................................9
      3.4. Text .......................................................9
      3.5. Time Fields ...............................................10
      3.6. Keyrings ..................................................10
      3.7. String-to-Key (S2K) Specifiers ............................10
           3.7.1. String-to-Key (S2K) Specifier Types ................10
                  3.7.1.1. Simple S2K ................................10
                  3.7.1.2. Salted S2K ................................11
                  3.7.1.3. Iterated and Salted S2K ...................11
           3.7.2. String-to-Key Usage ................................12
                  3.7.2.1. Secret-Key Encryption .....................12
                  3.7.2.2. Symmetric-Key Message Encryption ..........13
   4. Packet Syntax ..................................................13
      4.1. Overview ..................................................13
      4.2. Packet Headers ............................................13
           4.2.1. Old Format Packet Lengths ..........................14
           4.2.2. New Format Packet Lengths ..........................15
                  4.2.2.1. One-Octet Lengths .........................15
                  4.2.2.2. Two-Octet Lengths .........................15
                  4.2.2.3. Five-Octet Lengths ........................15
                  4.2.2.4. Partial Body Lengths ......................16
           4.2.3. Packet Length Examples .............................16
      4.3. Packet Tags ...............................................17
   5. Packet Types ...................................................17
      5.1. Public-Key Encrypted Session Key Packets (Tag 1) ..........17
      5.2. Signature Packet (Tag 2) ..................................19
           5.2.1. Signature Types ....................................19
           5.2.2. Version 3 Signature Packet Format ..................21
           5.2.3. Version 4 Signature Packet Format ..................24
                  5.2.3.1. Signature Subpacket Specification .........25
                  5.2.3.2. Signature Subpacket Types .................27
                  5.2.3.3. Notes on Self-Signatures ..................27
                  5.2.3.4. Signature Creation Time ...................28
                  5.2.3.5. Issuer ....................................28
                  5.2.3.6. Key Expiration Time .......................28



Callas, et al               Standards Track                     [Page 2]

RFC 4880                 OpenPGP Message Format            November 2007


                  5.2.3.7. Preferred Symmetric Algorithms ............28
                  5.2.3.8. Preferred Hash Algorithms .................29
                  5.2.3.9. Preferred Compression Algorithms ..........29
                  5.2.3.10. Signature Expiration Time ................29
                  5.2.3.11. Exportable Certification .................29
                  5.2.3.12. Revocable ................................30
                  5.2.3.13. Trust Signature ..........................30
                  5.2.3.14. Regular Expression .......................31
                  5.2.3.15. Revocation Key ...........................31
                  5.2.3.16. Notation Data ............................31
                  5.2.3.17. Key Server Preferences ...................32
                  5.2.3.18. Preferred Key Server .....................33
                  5.2.3.19. Primary User ID ..........................33
                  5.2.3.20. Policy URI ...............................33
                  5.2.3.21. Key Flags ................................33
                  5.2.3.22. Signer's User ID .........................34
                  5.2.3.23. Reason for Revocation ....................35
                  5.2.3.24. Features .................................36
                  5.2.3.25. Signature Target .........................36
                  5.2.3.26. Embedded Signature .......................37
           5.2.4. Computing Signatures ...............................37
                  5.2.4.1. Subpacket Hints ...........................38
      5.3. Symmetric-Key Encrypted Session Key Packets (Tag 3) .......38
      5.4. One-Pass Signature Packets (Tag 4) ........................39
      5.5. Key Material Packet .......................................40
           5.5.1. Key Packet Variants ................................40
                  5.5.1.1. Public-Key Packet (Tag 6) .................40
                  5.5.1.2. Public-Subkey Packet (Tag 14) .............40
                  5.5.1.3. Secret-Key Packet (Tag 5) .................41
                  5.5.1.4. Secret-Subkey Packet (Tag 7) ..............41
           5.5.2. Public-Key Packet Formats ..........................41
           5.5.3. Secret-Key Packet Formats ..........................43
      5.6. Compressed Data Packet (Tag 8) ............................45
      5.7. Symmetrically Encrypted Data Packet (Tag 9) ...............45
      5.8. Marker Packet (Obsolete Literal Packet) (Tag 10) ..........46
      5.9. Literal Data Packet (Tag 11) ..............................46
      5.10. Trust Packet (Tag 12) ....................................47
      5.11. User ID Packet (Tag 13) ..................................48
      5.12. User Attribute Packet (Tag 17) ...........................48
           5.12.1. The Image Attribute Subpacket .....................48
      5.13. Sym. Encrypted Integrity Protected Data Packet (Tag 18) ..49
      5.14. Modification Detection Code Packet (Tag 19) ..............52
   6. Radix-64 Conversions ...........................................53
      6.1. An Implementation of the CRC-24 in "C" ....................54
      6.2. Forming ASCII Armor .......................................54
      6.3. Encoding Binary in Radix-64 ...............................57
      6.4. Decoding Radix-64 .........................................58
      6.5. Examples of Radix-64 ......................................59



Callas, et al               Standards Track                     [Page 3]

RFC 4880                 OpenPGP Message Format            November 2007


      6.6. Example of an ASCII Armored Message .......................59
   7. Cleartext Signature Framework ..................................59
      7.1. Dash-Escaped Text .........................................60
   8. Regular Expressions ............................................61
   9. Constants ......................................................61
      9.1. Public-Key Algorithms .....................................62
      9.2. Symmetric-Key Algorithms ..................................62
      9.3. Compression Algorithms ....................................63
      9.4. Hash Algorithms ...........................................63
   10. IANA Considerations ...........................................63
      10.1. New String-to-Key Specifier Types ........................64
      10.2. New Packets ..............................................64
           10.2.1. User Attribute Types ..............................64
                  10.2.1.1. Image Format Subpacket Types .............64
           10.2.2. New Signature Subpackets ..........................64
                  10.2.2.1. Signature Notation Data Subpackets .......65
                  10.2.2.2. Key Server Preference Extensions .........65
                  10.2.2.3. Key Flags Extensions .....................65
                  10.2.2.4. Reason For Revocation Extensions .........65
                  10.2.2.5. Implementation Features ..................66
           10.2.3. New Packet Versions ...............................66
      10.3. New Algorithms ...........................................66
           10.3.1. Public-Key Algorithms .............................66
           10.3.2. Symmetric-Key Algorithms ..........................67
           10.3.3. Hash Algorithms ...................................67
           10.3.4. Compression Algorithms ............................67
   11. Packet Composition ............................................67
      11.1. Transferable Public Keys .................................67
      11.2. Transferable Secret Keys .................................69
      11.3. OpenPGP Messages .........................................69
      11.4. Detached Signatures ......................................70
   12. Enhanced Key Formats ..........................................70
      12.1. Key Structures ...........................................70
      12.2. Key IDs and Fingerprints .................................71
   13. Notes on Algorithms ...........................................72
      13.1. PKCS#1 Encoding in OpenPGP ...............................72
           13.1.1. EME-PKCS1-v1_5-ENCODE .............................73
           13.1.2. EME-PKCS1-v1_5-DECODE .............................73
           13.1.3. EMSA-PKCS1-v1_5 ...................................74
      13.2. Symmetric Algorithm Preferences ..........................75
      13.3. Other Algorithm Preferences ..............................76
           13.3.1. Compression Preferences ...........................76
           13.3.2. Hash Algorithm Preferences ........................76
      13.4. Plaintext ................................................77
      13.5. RSA ......................................................77
      13.6. DSA ......................................................77
      13.7. Elgamal ..................................................78
      13.8. Reserved Algorithm Numbers ...............................78



Callas, et al               Standards Track                     [Page 4]

RFC 4880                 OpenPGP Message Format            November 2007


      13.9. OpenPGP CFB Mode .........................................78
      13.10. Private or Experimental Parameters ......................79
      13.11. Extension of the MDC System .............................80
      13.12. Meta-Considerations for Expansion .......................80
   14. Security Considerations .......................................81
   15. Implementation Nits ...........................................84
   16. References ....................................................86
      16.1. Normative References .....................................86
      16.2. Informative References ...................................88

1.  Introduction

   This document provides information on the message-exchange packet
   formats used by OpenPGP to provide encryption, decryption, signing,
   and key management functions.  It is a revision of RFC 2440, "OpenPGP
   Message Format", which itself replaces RFC 1991, "PGP Message
   Exchange Formats" [RFC1991] [RFC2440].

1.1.  Terms

     * OpenPGP - This is a term for security software that uses PGP 5.x
       as a basis, formalized in RFC 2440 and this document.

     * PGP - Pretty Good Privacy.  PGP is a family of software systems
       developed by Philip R. Zimmermann from which OpenPGP is based.

     * PGP 2.6.x - This version of PGP has many variants, hence the term
       PGP 2.6.x.  It used only RSA, MD5, and IDEA for its cryptographic
       transforms.  An informational RFC, RFC 1991, was written
       describing this version of PGP.

     * PGP 5.x - This version of PGP is formerly known as "PGP 3" in the
       community and also in the predecessor of this document, RFC 1991.
       It has new formats and corrects a number of problems in the PGP
       2.6.x design.  It is referred to here as PGP 5.x because that
       software was the first release of the "PGP 3" code base.

     * GnuPG - GNU Privacy Guard, also called GPG.  GnuPG is an OpenPGP
       implementation that avoids all encumbered algorithms.
       Consequently, early versions of GnuPG did not include RSA public
       keys.  GnuPG may or may not have (depending on version) support
       for IDEA or other encumbered algorithms.

   "PGP", "Pretty Good", and "Pretty Good Privacy" are trademarks of PGP
   Corporation and are used with permission.  The term "OpenPGP" refers
   to the protocol described in this and related documents.





Callas, et al               Standards Track                     [Page 5]

RFC 4880                 OpenPGP Message Format            November 2007


   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in [RFC2119].

   The key words "PRIVATE USE", "HIERARCHICAL ALLOCATION", "FIRST COME
   FIRST SERVED", "EXPERT REVIEW", "SPECIFICATION REQUIRED", "IESG
   APPROVAL", "IETF CONSENSUS", and "STANDARDS ACTION" that appear in
   this document when used to describe namespace allocation are to be
   interpreted as described in [RFC2434].

2.  General functions

   OpenPGP provides data integrity services for messages and data files
   by using these core technologies:

     - digital signatures

     - encryption

     - compression

     - Radix-64 conversion

   In addition, OpenPGP provides key management and certificate
   services, but many of these are beyond the scope of this document.

2.1.  Confidentiality via Encryption

   OpenPGP combines symmetric-key encryption and public-key encryption
   to provide confidentiality.  When made confidential, first the object
   is encrypted using a symmetric encryption algorithm.  Each symmetric
   key is used only once, for a single object.  A new "session key" is
   generated as a random number for each object (sometimes referred to
   as a session).  Since it is used only once, the session key is bound
   to the message and transmitted with it.  To protect the key, it is
   encrypted with the receiver's public key.  The sequence is as
   follows:

   1.  The sender creates a message.

   2.  The sending OpenPGP generates a random number to be used as a
       session key for this message only.

   3.  The session key is encrypted using each recipient's public key.
       These "encrypted session keys" start the message.






Callas, et al               Standards Track                     [Page 6]

RFC 4880                 OpenPGP Message Format            November 2007


   4.  The sending OpenPGP encrypts the message using the session key,
       which forms the remainder of the message.  Note that the message
       is also usually compressed.

   5.  The receiving OpenPGP decrypts the session key using the
       recipient's private key.

   6.  The receiving OpenPGP decrypts the message using the session key.
       If the message was compressed, it will be decompressed.

   With symmetric-key encryption, an object may be encrypted with a
   symmetric key derived from a passphrase (or other shared secret), or
   a two-stage mechanism similar to the public-key method described
   above in which a session key is itself encrypted with a symmetric
   algorithm keyed from a shared secret.

   Both digital signature and confidentiality services may be applied to
   the same message.  First, a signature is generated for the message
   and attached to the message.  Then the message plus signature is
   encrypted using a symmetric session key.  Finally, the session key is
   encrypted using public-key encryption and prefixed to the encrypted
   block.

2.2.  Authentication via Digital Signature

   The digital signature uses a hash code or message digest algorithm,
   and a public-key signature algorithm.  The sequence is as follows:

   1.  The sender creates a message.

   2.  The sending software generates a hash code of the message.

   3.  The sending software generates a signature from the hash code
       using the sender's private key.

   4.  The binary signature is attached to the message.

   5.  The receiving software keeps a copy of the message signature.

   6.  The receiving software generates a new hash code for the received
       message and verifies it using the message's signature.  If the
       verification is successful, the message is accepted as authentic.

2.3.  Compression

   OpenPGP implementations SHOULD compress the message after applying
   the signature but before encryption.




Callas, et al               Standards Track                     [Page 7]

RFC 4880                 OpenPGP Message Format            November 2007


   If an implementation does not implement compression, its authors
   should be aware that most OpenPGP messages in the world are
   compressed.  Thus, it may even be wise for a space-constrained
   implementation to implement decompression, but not compression.

   Furthermore, compression has the added side effect that some types of
   attacks can be thwarted by the fact that slightly altered, compressed
   data rarely uncompresses without severe errors.  This is hardly
   rigorous, but it is operationally useful.  These attacks can be
   rigorously prevented by implementing and using Modification Detection
   Codes as described in sections following.

2.4.  Conversion to Radix-64

   OpenPGP's underlying native representation for encrypted messages,
   signature certificates, and keys is a stream of arbitrary octets.
   Some systems only permit the use of blocks consisting of seven-bit,
   printable text.  For transporting OpenPGP's native raw binary octets
   through channels that are not safe to raw binary data, a printable
   encoding of these binary octets is needed.  OpenPGP provides the
   service of converting the raw 8-bit binary octet stream to a stream
   of printable ASCII characters, called Radix-64 encoding or ASCII
   Armor.

   Implementations SHOULD provide Radix-64 conversions.

2.5.  Signature-Only Applications

   OpenPGP is designed for applications that use both encryption and
   signatures, but there are a number of problems that are solved by a
   signature-only implementation.  Although this specification requires
   both encryption and signatures, it is reasonable for there to be
   subset implementations that are non-conformant only in that they omit
   encryption.

3.  Data Element Formats

   This section describes the data elements used by OpenPGP.

3.1.  Scalar Numbers

   Scalar numbers are unsigned and are always stored in big-endian
   format.  Using n[k] to refer to the kth octet being interpreted, the
   value of a two-octet scalar is ((n[0] << 8) + n[1]).  The value of a
   four-octet scalar is ((n[0] << 24) + (n[1] << 16) + (n[2] << 8) +
   n[3]).





Callas, et al               Standards Track                     [Page 8]

RFC 4880                 OpenPGP Message Format            November 2007


3.2.  Multiprecision Integers

   Multiprecision integers (also called MPIs) are unsigned integers used
   to hold large integers such as the ones used in cryptographic
   calculations.

   An MPI consists of two pieces: a two-octet scalar that is the length
   of the MPI in bits followed by a string of octets that contain the
   actual integer.

   These octets form a big-endian number; a big-endian number can be
   made into an MPI by prefixing it with the appropriate length.

   Examples:

   (all numbers are in hexadecimal)

   The string of octets [00 01 01] forms an MPI with the value 1.  The
   string [00 09 01 FF] forms an MPI with the value of 511.

   Additional rules:

   The size of an MPI is ((MPI.length + 7) / 8) + 2 octets.

   The length field of an MPI describes the length starting from its
   most significant non-zero bit.  Thus, the MPI [00 02 01] is not
   formed correctly.  It should be [00 01 01].

   Unused bits of an MPI MUST be zero.

   Also note that when an MPI is encrypted, the length refers to the
   plaintext MPI.  It may be ill-formed in its ciphertext.

3.3.  Key IDs

   A Key ID is an eight-octet scalar that identifies a key.
   Implementations SHOULD NOT assume that Key IDs are unique.  The
   section "Enhanced Key Formats" below describes how Key IDs are
   formed.

3.4.  Text

   Unless otherwise specified, the character set for text is the UTF-8
   [RFC3629] encoding of Unicode [ISO10646].







Callas, et al               Standards Track                     [Page 9]

RFC 4880                 OpenPGP Message Format            November 2007


3.5.  Time Fields

   A time field is an unsigned four-octet number containing the number
   of seconds elapsed since midnight, 1 January 1970 UTC.

3.6.  Keyrings

   A keyring is a collection of one or more keys in a file or database.
   Traditionally, a keyring is simply a sequential list of keys, but may
   be any suitable database.  It is beyond the scope of this standard to
   discuss the details of keyrings or other databases.

3.7.  String-to-Key (S2K) Specifiers

   String-to-key (S2K) specifiers are used to convert passphrase strings
   into symmetric-key encryption/decryption keys.  They are used in two
   places, currently: to encrypt the secret part of private keys in the
   private keyring, and to convert passphrases to encryption keys for
   symmetrically encrypted messages.

3.7.1.  String-to-Key (S2K) Specifier Types

   There are three types of S2K specifiers currently supported, and
   some reserved values:

       ID          S2K Type
       --          --------
       0           Simple S2K
       1           Salted S2K
       2           Reserved value
       3           Iterated and Salted S2K
       100 to 110  Private/Experimental S2K

   These are described in Sections 3.7.1.1 - 3.7.1.3.

3.7.1.1.  Simple S2K

   This directly hashes the string to produce the key data.  See below
   for how this hashing is done.

       Octet 0:        0x00
       Octet 1:        hash algorithm

   Simple S2K hashes the passphrase to produce the session key.  The
   manner in which this is done depends on the size of the session key
   (which will depend on the cipher used) and the size of the hash





Callas, et al               Standards Track                    [Page 10]

RFC 4880                 OpenPGP Message Format            November 2007


   algorithm's output.  If the hash size is greater than the session key
   size, the high-order (leftmost) octets of the hash are used as the
   key.

   If the hash size is less than the key size, multiple instances of the
   hash context are created -- enough to produce the required key data.
   These instances are preloaded with 0, 1, 2, ... octets of zeros (that
   is to say, the first instance has no preloading, the second gets
   preloaded with 1 octet of zero, the third is preloaded with two
   octets of zeros, and so forth).

   As the data is hashed, it is given independently to each hash
   context.  Since the contexts have been initialized differently, they
   will each produce different hash output.  Once the passphrase is
   hashed, the output data from the multiple hashes is concatenated,
   first hash leftmost, to produce the key data, with any excess octets
   on the right discarded.

3.7.1.2.  Salted S2K

   This includes a "salt" value in the S2K specifier -- some arbitrary
   data -- that gets hashed along with the passphrase string, to help
   prevent dictionary attacks.

       Octet 0:        0x01
       Octet 1:        hash algorithm
       Octets 2-9:     8-octet salt value

   Salted S2K is exactly like Simple S2K, except that the input to the
   hash function(s) consists of the 8 octets of salt from the S2K
   specifier, followed by the passphrase.

3.7.1.3.  Iterated and Salted S2K

   This includes both a salt and an octet count.  The salt is combined
   with the passphrase and the resulting value is hashed repeatedly.
   This further increases the amount of work an attacker must do to try
   dictionary attacks.

       Octet  0:        0x03
       Octet  1:        hash algorithm
       Octets 2-9:      8-octet salt value
       Octet  10:       count, a one-octet, coded value








Callas, et al               Standards Track                    [Page 11]

RFC 4880                 OpenPGP Message Format            November 2007


   The count is coded into a one-octet number using the following
   formula:

       #define EXPBIAS 6
           count = ((Int32)16 + (c & 15)) << ((c >> 4) + EXPBIAS);

   The above formula is in C, where "Int32" is a type for a 32-bit
   integer, and the variable "c" is the coded count, Octet 10.

   Iterated-Salted S2K hashes the passphrase and salt data multiple
   times.  The total number of octets to be hashed is specified in the
   encoded count in the S2K specifier.  Note that the resulting count
   value is an octet count of how many octets will be hashed, not an
   iteration count.

   Initially, one or more hash contexts are set up as with the other S2K
   algorithms, depending on how many octets of key data are needed.
   Then the salt, followed by the passphrase data, is repeatedly hashed
   until the number of octets specified by the octet count has been
   hashed.  The one exception is that if the octet count is less than
   the size of the salt plus passphrase, the full salt plus passphrase
   will be hashed even though that is greater than the octet count.
   After the hashing is done, the data is unloaded from the hash
   context(s) as with the other S2K algorithms.

3.7.2.  String-to-Key Usage

   Implementations SHOULD use salted or iterated-and-salted S2K
   specifiers, as simple S2K specifiers are more vulnerable to
   dictionary attacks.

3.7.2.1.  Secret-Key Encryption

   An S2K specifier can be stored in the secret keyring to specify how
   to convert the passphrase to a key that unlocks the secret data.
   Older versions of PGP just stored a cipher algorithm octet preceding
   the secret data or a zero to indicate that the secret data was
   unencrypted.  The MD5 hash function was always used to convert the
   passphrase to a key for the specified cipher algorithm.

   For compatibility, when an S2K specifier is used, the special value
   254 or 255 is stored in the position where the hash algorithm octet
   would have been in the old data structure.  This is then followed
   immediately by a one-octet algorithm identifier, and then by the S2K
   specifier as encoded above.






Callas, et al               Standards Track                    [Page 12]

RFC 4880                 OpenPGP Message Format            November 2007


   Therefore, preceding the secret data there will be one of these
   possibilities:

       0:           secret data is unencrypted (no passphrase)
       255 or 254:  followed by algorithm octet and S2K specifier
       Cipher alg:  use Simple S2K algorithm using MD5 hash

   This last possibility, the cipher algorithm number with an implicit
   use of MD5 and IDEA, is provided for backward compatibility; it MAY
   be understood, but SHOULD NOT be generated, and is deprecated.

   These are followed by an Initial Vector of the same length as the
   block size of the cipher for the decryption of the secret values, if
   they are encrypted, and then the secret-key values themselves.

3.7.2.2.  Symmetric-Key Message Encryption

   OpenPGP can create a Symmetric-key Encrypted Session Key (ESK) packet
   at the front of a message.  This is used to allow S2K specifiers to
   be used for the passphrase conversion or to create messages with a
   mix of symmetric-key ESKs and public-key ESKs.  This allows a message
   to be decrypted either with a passphrase or a public-key pair.

   PGP 2.X always used IDEA with Simple string-to-key conversion when
   encrypting a message with a symmetric algorithm.  This is deprecated,
   but MAY be used for backward-compatibility.

4.  Packet Syntax

   This section describes the packets used by OpenPGP.

4.1.  Overview

   An OpenPGP message is constructed from a number of records that are
   traditionally called packets.  A packet is a chunk of data that has a
   tag specifying its meaning.  An OpenPGP message, keyring,
   certificate, and so forth consists of a number of packets.  Some of
   those packets may contain other OpenPGP packets (for example, a
   compressed data packet, when uncompressed, contains OpenPGP packets).

   Each packet consists of a packet header, followed by the packet body.
   The packet header is of variable length.

4.2.  Packet Headers

   The first octet of the packet header is called the "Packet Tag".  It
   determines the format of the header and denotes the packet contents.
   The remainder of the packet header is the length of the packet.



Callas, et al               Standards Track                    [Page 13]

RFC 4880                 OpenPGP Message Format            November 2007


   Note that the most significant bit is the leftmost bit, called bit 7.
   A mask for this bit is 0x80 in hexadecimal.

              +---------------+
         PTag |7 6 5 4 3 2 1 0|
              +---------------+
         Bit 7 -- Always one
         Bit 6 -- New packet format if set

   PGP 2.6.x only uses old format packets.  Thus, software that
   interoperates with those versions of PGP must only use old format
   packets.  If interoperability is not an issue, the new packet format
   is RECOMMENDED.  Note that old format packets have four bits of
   packet tags, and new format packets have six; some features cannot be
   used and still be backward-compatible.

   Also note that packets with a tag greater than or equal to 16 MUST
   use new format packets.  The old format packets can only express tags
   less than or equal to 15.

   Old format packets contain:

         Bits 5-2 -- packet tag
         Bits 1-0 -- length-type

   New format packets contain:

         Bits 5-0 -- packet tag

4.2.1.  Old Format Packet Lengths

   The meaning of the length-type in old format packets is:

   0 - The packet has a one-octet length.  The header is 2 octets long.

   1 - The packet has a two-octet length.  The header is 3 octets long.

   2 - The packet has a four-octet length.  The header is 5 octets long.

   3 - The packet is of indeterminate length.  The header is 1 octet
       long, and the implementation must determine how long the packet
       is.  If the packet is in a file, this means that the packet
       extends until the end of the file.  In general, an implementation
       SHOULD NOT use indeterminate-length packets except where the end
       of the data will be clear from the context, and even then it is
       better to use a definite length, or a new format header.  The new
       format headers described below have a mechanism for precisely
       encoding data of indeterminate length.



Callas, et al               Standards Track                    [Page 14]

RFC 4880                 OpenPGP Message Format            November 2007


4.2.2.  New Format Packet Lengths

   New format packets have four possible ways of encoding length:

   1. A one-octet Body Length header encodes packet lengths of up to 191
      octets.

   2. A two-octet Body Length header encodes packet lengths of 192 to
      8383 octets.

   3. A five-octet Body Length header encodes packet lengths of up to
      4,294,967,295 (0xFFFFFFFF) octets in length.  (This actually
      encodes a four-octet scalar number.)

   4. When the length of the packet body is not known in advance by the
      issuer, Partial Body Length headers encode a packet of
      indeterminate length, effectively making it a stream.

4.2.2.1.  One-Octet Lengths

   A one-octet Body Length header encodes a length of 0 to 191 octets.
   This type of length header is recognized because the one octet value
   is less than 192.  The body length is equal to:

       bodyLen = 1st_octet;

4.2.2.2.  Two-Octet Lengths

   A two-octet Body Length header encodes a length of 192 to 8383
   octets.  It is recognized because its first octet is in the range 192
   to 223.  The body length is equal to:

       bodyLen = ((1st_octet - 192) << 8) + (2nd_octet) + 192

4.2.2.3.  Five-Octet Lengths

   A five-octet Body Length header consists of a single octet holding
   the value 255, followed by a four-octet scalar.  The body length is
   equal to:

       bodyLen = (2nd_octet << 24) | (3rd_octet << 16) |
                 (4th_octet << 8)  | 5th_octet

   This basic set of one, two, and five-octet lengths is also used
   internally to some packets.






Callas, et al               Standards Track                    [Page 15]

RFC 4880                 OpenPGP Message Format            November 2007


4.2.2.4.  Partial Body Lengths

   A Partial Body Length header is one octet long and encodes the length
   of only part of the data packet.  This length is a power of 2, from 1
   to 1,073,741,824 (2 to the 30th power).  It is recognized by its one
   octet value that is greater than or equal to 224, and less than 255.
   The Partial Body Length is equal to:

       partialBodyLen = 1 << (1st_octet & 0x1F);

   Each Partial Body Length header is followed by a portion of the
   packet body data.  The Partial Body Length header specifies this
   portion's length.  Another length header (one octet, two-octet,
   five-octet, or partial) follows that portion.  The last length header
   in the packet MUST NOT be a Partial Body Length header.  Partial Body
   Length headers may only be used for the non-final parts of the
   packet.

   Note also that the last Body Length header can be a zero-length
   header.

   An implementation MAY use Partial Body Lengths for data packets, be
   they literal, compressed, or encrypted.  The first partial length
   MUST be at least 512 octets long.  Partial Body Lengths MUST NOT be
   used for any other packet types.

4.2.3.  Packet Length Examples

   These examples show ways that new format packets might encode the
   packet lengths.

   A packet with length 100 may have its length encoded in one octet:
   0x64.  This is followed by 100 octets of data.

   A packet with length 1723 may have its length encoded in two octets:
   0xC5, 0xFB.  This header is followed by the 1723 octets of data.

   A packet with length 100000 may have its length encoded in five
   octets: 0xFF, 0x00, 0x01, 0x86, 0xA0.

   It might also be encoded in the following octet stream: 0xEF, first
   32768 octets of data; 0xE1, next two octets of data; 0xE0, next one
   octet of data; 0xF0, next 65536 octets of data; 0xC5, 0xDD, last 1693
   octets of data.  This is just one possible encoding, and many
   variations are possible on the size of the Partial Body Length
   headers, as long as a regular Body Length header encodes the last
   portion of the data.




Callas, et al               Standards Track                    [Page 16]

RFC 4880                 OpenPGP Message Format            November 2007


   Please note that in all of these explanations, the total length of
   the packet is the length of the header(s) plus the length of the
   body.

4.3.  Packet Tags

   The packet tag denotes what type of packet the body holds.  Note that
   old format headers can only have tags less than 16, whereas new
   format headers can have tags as great as 63.  The defined tags (in
   decimal) are as follows:

       0        -- Reserved - a packet tag MUST NOT have this value
       1        -- Public-Key Encrypted Session Key Packet
       2        -- Signature Packet
       3        -- Symmetric-Key Encrypted Session Key Packet
       4        -- One-Pass Signature Packet
       5        -- Secret-Key Packet
       6        -- Public-Key Packet
       7        -- Secret-Subkey Packet
       8        -- Compressed Data Packet
       9        -- Symmetrically Encrypted Data Packet
       10       -- Marker Packet
       11       -- Literal Data Packet
       12       -- Trust Packet
       13       -- User ID Packet
       14       -- Public-Subkey Packet
       17       -- User Attribute Packet
       18       -- Sym. Encrypted and Integrity Protected Data Packet
       19       -- Modification Detection Code Packet
       60 to 63 -- Private or Experimental Values

5.  Packet Types

5.1.  Public-Key Encrypted Session Key Packets (Tag 1)

   A Public-Key Encrypted Session Key packet holds the session key used
   to encrypt a message.  Zero or more Public-Key Encrypted Session Key
   packets and/or Symmetric-Key Encrypted Session Key packets may
   precede a Symmetrically Encrypted Data Packet, which holds an
   encrypted message.  The message is encrypted with the session key,
   and the session key is itself encrypted and stored in the Encrypted
   Session Key packet(s).  The Symmetrically Encrypted Data Packet is
   preceded by one Public-Key Encrypted Session Key packet for each
   OpenPGP key to which the message is encrypted.  The recipient of the
   message finds a session key that is encrypted to their public key,
   decrypts the session key, and then uses the session key to decrypt
   the message.




Callas, et al               Standards Track                    [Page 17]

RFC 4880                 OpenPGP Message Format            November 2007


   The body of this packet consists of:

     - A one-octet number giving the version number of the packet type.
       The currently defined value for packet version is 3.

     - An eight-octet number that gives the Key ID of the public key to
       which the session key is encrypted.  If the session key is
       encrypted to a subkey, then the Key ID of this subkey is used
       here instead of the Key ID of the primary key.

     - A one-octet number giving the public-key algorithm used.

     - A string of octets that is the encrypted session key.  This
       string takes up the remainder of the packet, and its contents are
       dependent on the public-key algorithm used.

   Algorithm Specific Fields for RSA encryption

     - multiprecision integer (MPI) of RSA encrypted value m**e mod n.

   Algorithm Specific Fields for Elgamal encryption:

     - MPI of Elgamal (Diffie-Hellman) value g**k mod p.

     - MPI of Elgamal (Diffie-Hellman) value m * y**k mod p.

   The value "m" in the above formulas is derived from the session key
   as follows.  First, the session key is prefixed with a one-octet
   algorithm identifier that specifies the symmetric encryption
   algorithm used to encrypt the following Symmetrically Encrypted Data
   Packet.  Then a two-octet checksum is appended, which is equal to the
   sum of the preceding session key octets, not including the algorithm
   identifier, modulo 65536.  This value is then encoded as described in
   PKCS#1 block encoding EME-PKCS1-v1_5 in Section 7.2.1 of [RFC3447] to
   form the "m" value used in the formulas above.  See Section 13.1 of
   this document for notes on OpenPGP's use of PKCS#1.

   Note that when an implementation forms several PKESKs with one
   session key, forming a message that can be decrypted by several keys,
   the implementation MUST make a new PKCS#1 encoding for each key.

   An implementation MAY accept or use a Key ID of zero as a "wild card"
   or "speculative" Key ID.  In this case, the receiving implementation
   would try all available private keys, checking for a valid decrypted
   session key.  This format helps reduce traffic analysis of messages.






Callas, et al               Standards Track                    [Page 18]

RFC 4880                 OpenPGP Message Format            November 2007


5.2.  Signature Packet (Tag 2)

   A Signature packet describes a binding between some public key and
   some data.  The most common signatures are a signature of a file or a
   block of text, and a signature that is a certification of a User ID.

   Two versions of Signature packets are defined.  Version 3 provides
   basic signature information, while version 4 provides an expandable
   format with subpackets that can specify more information about the
   signature.  PGP 2.6.x only accepts version 3 signatures.

   Implementations SHOULD accept V3 signatures.  Implementations SHOULD
   generate V4 signatures.

   Note that if an implementation is creating an encrypted and signed
   message that is encrypted to a V3 key, it is reasonable to create a
   V3 signature.

5.2.1.  Signature Types

   There are a number of possible meanings for a signature, which are
   indicated in a signature type octet in any given signature.  Please
   note that the vagueness of these meanings is not a flaw, but a
   feature of the system.  Because OpenPGP places final authority for
   validity upon the receiver of a signature, it may be that one
   signer's casual act might be more rigorous than some other
   authority's positive act.  See Section 5.2.4, "Computing Signatures",
   for detailed information on how to compute and verify signatures of
   each type.

   These meanings are as follows:

   0x00: Signature of a binary document.
       This means the signer owns it, created it, or certifies that it
       has not been modified.

   0x01: Signature of a canonical text document.
       This means the signer owns it, created it, or certifies that it
       has not been modified.  The signature is calculated over the text
       data with its line endings converted to <CR><LF>.

   0x02: Standalone signature.
       This signature is a signature of only its own subpacket contents.
       It is calculated identically to a signature over a zero-length
       binary document.  Note that it doesn't make sense to have a V3
       standalone signature.





Callas, et al               Standards Track                    [Page 19]

RFC 4880                 OpenPGP Message Format            November 2007


   0x10: Generic certification of a User ID and Public-Key packet.
       The issuer of this certification does not make any particular
       assertion as to how well the certifier has checked that the owner
       of the key is in fact the person described by the User ID.

   0x11: Persona certification of a User ID and Public-Key packet.
       The issuer of this certification has not done any verification of
       the claim that the owner of this key is the User ID specified.

   0x12: Casual certification of a User ID and Public-Key packet.
       The issuer of this certification has done some casual
       verification of the claim of identity.

   0x13: Positive certification of a User ID and Public-Key packet.
       The issuer of this certification has done substantial
       verification of the claim of identity.

       Most OpenPGP implementations make their "key signatures" as 0x10
       certifications.  Some implementations can issue 0x11-0x13
       certifications, but few differentiate between the types.

   0x18: Subkey Binding Signature
       This signature is a statement by the top-level signing key that
       indicates that it owns the subkey.  This signature is calculated
       directly on the primary key and subkey, and not on any User ID or
       other packets.  A signature that binds a signing subkey MUST have
       an Embedded Signature subpacket in this binding signature that
       contains a 0x19 signature made by the signing subkey on the
       primary key and subkey.

   0x19: Primary Key Binding Signature
       This signature is a statement by a signing subkey, indicating
       that it is owned by the primary key and subkey.  This signature
       is calculated the same way as a 0x18 signature: directly on the
       primary key and subkey, and not on any User ID or other packets.

   0x1F: Signature directly on a key
       This signature is calculated directly on a key.  It binds the
       information in the Signature subpackets to the key, and is
       appropriate to be used for subpackets that provide information
       about the key, such as the Revocation Key subpacket.  It is also
       appropriate for statements that non-self certifiers want to make
       about the key itself, rather than the binding between a key and a
       name.







Callas, et al               Standards Track                    [Page 20]

RFC 4880                 OpenPGP Message Format            November 2007


   0x20: Key revocation signature
       The signature is calculated directly on the key being revoked.  A
       revoked key is not to be used.  Only revocation signatures by the
       key being revoked, or by an authorized revocation key, should be
       considered valid revocation signatures.

   0x28: Subkey revocation signature
       The signature is calculated directly on the subkey being revoked.
       A revoked subkey is not to be used.  Only revocation signatures
       by the top-level signature key that is bound to this subkey, or
       by an authorized revocation key, should be considered valid
       revocation signatures.

   0x30: Certification revocation signature
       This signature revokes an earlier User ID certification signature
       (signature class 0x10 through 0x13) or direct-key signature
       (0x1F).  It should be issued by the same key that issued the
       revoked signature or an authorized revocation key.  The signature
       is computed over the same data as the certificate that it
       revokes, and should have a later creation date than that
       certificate.

   0x40: Timestamp signature.
       This signature is only meaningful for the timestamp contained in
       it.

   0x50: Third-Party Confirmation signature.
       This signature is a signature over some other OpenPGP Signature
       packet(s).  It is analogous to a notary seal on the signed data.
       A third-party signature SHOULD include Signature Target
       subpacket(s) to give easy identification.  Note that we really do
       mean SHOULD.  There are plausible uses for this (such as a blind
       party that only sees the signature, not the key or source
       document) that cannot include a target subpacket.

5.2.2.  Version 3 Signature Packet Format

   The body of a version 3 Signature Packet contains:

     - One-octet version number (3).

     - One-octet length of following hashed material.  MUST be 5.

         - One-octet signature type.

         - Four-octet creation time.

     - Eight-octet Key ID of signer.



Callas, et al               Standards Track                    [Page 21]

RFC 4880                 OpenPGP Message Format            November 2007


     - One-octet public-key algorithm.

     - One-octet hash algorithm.

     - Two-octet field holding left 16 bits of signed hash value.

     - One or more multiprecision integers comprising the signature.
       This portion is algorithm specific, as described below.

   The concatenation of the data to be signed, the signature type, and
   creation time from the Signature packet (5 additional octets) is
   hashed.  The resulting hash value is used in the signature algorithm.
   The high 16 bits (first two octets) of the hash are included in the
   Signature packet to provide a quick test to reject some invalid
   signatures.

   Algorithm-Specific Fields for RSA signatures:

     - multiprecision integer (MPI) of RSA signature value m**d mod n.

   Algorithm-Specific Fields for DSA signatures:

     - MPI of DSA value r.

     - MPI of DSA value s.

   The signature calculation is based on a hash of the signed data, as
   described above.  The details of the calculation are different for
   DSA signatures than for RSA signatures.

   With RSA signatures, the hash value is encoded using PKCS#1 encoding
   type EMSA-PKCS1-v1_5 as described in Section 9.2 of RFC 3447.  This
   requires inserting the hash value as an octet string into an ASN.1
   structure.  The object identifier for the type of hash being used is
   included in the structure.  The hexadecimal representations for the
   currently defined hash algorithms are as follows:

     - MD5:        0x2A, 0x86, 0x48, 0x86, 0xF7, 0x0D, 0x02, 0x05

     - RIPEMD-160: 0x2B, 0x24, 0x03, 0x02, 0x01

     - SHA-1:      0x2B, 0x0E, 0x03, 0x02, 0x1A

     - SHA224:     0x60, 0x86, 0x48, 0x01, 0x65, 0x03, 0x04, 0x02, 0x04

     - SHA256:     0x60, 0x86, 0x48, 0x01, 0x65, 0x03, 0x04, 0x02, 0x01

     - SHA384:     0x60, 0x86, 0x48, 0x01, 0x65, 0x03, 0x04, 0x02, 0x02



Callas, et al               Standards Track                    [Page 22]

RFC 4880                 OpenPGP Message Format            November 2007


     - SHA512:     0x60, 0x86, 0x48, 0x01, 0x65, 0x03, 0x04, 0x02, 0x03

   The ASN.1 Object Identifiers (OIDs) are as follows:

     - MD5:        1.2.840.113549.2.5

     - RIPEMD-160: 1.3.36.3.2.1

     - SHA-1:      1.3.14.3.2.26

     - SHA224:     2.16.840.1.101.3.4.2.4

     - SHA256:     2.16.840.1.101.3.4.2.1

     - SHA384:     2.16.840.1.101.3.4.2.2

     - SHA512:     2.16.840.1.101.3.4.2.3

   The full hash prefixes for these are as follows:

       MD5:        0x30, 0x20, 0x30, 0x0C, 0x06, 0x08, 0x2A, 0x86,
                   0x48, 0x86, 0xF7, 0x0D, 0x02, 0x05, 0x05, 0x00,
                   0x04, 0x10

       RIPEMD-160: 0x30, 0x21, 0x30, 0x09, 0x06, 0x05, 0x2B, 0x24,
                   0x03, 0x02, 0x01, 0x05, 0x00, 0x04, 0x14

       SHA-1:      0x30, 0x21, 0x30, 0x09, 0x06, 0x05, 0x2b, 0x0E,
                   0x03, 0x02, 0x1A, 0x05, 0x00, 0x04, 0x14

       SHA224:     0x30, 0x31, 0x30, 0x0d, 0x06, 0x09, 0x60, 0x86,
                   0x48, 0x01, 0x65, 0x03, 0x04, 0x02, 0x04, 0x05,
                   0x00, 0x04, 0x1C

       SHA256:     0x30, 0x31, 0x30, 0x0d, 0x06, 0x09, 0x60, 0x86,
                   0x48, 0x01, 0x65, 0x03, 0x04, 0x02, 0x01, 0x05,
                   0x00, 0x04, 0x20

       SHA384:     0x30, 0x41, 0x30, 0x0d, 0x06, 0x09, 0x60, 0x86,
                   0x48, 0x01, 0x65, 0x03, 0x04, 0x02, 0x02, 0x05,
                   0x00, 0x04, 0x30

       SHA512:     0x30, 0x51, 0x30, 0x0d, 0x06, 0x09, 0x60, 0x86,
                   0x48, 0x01, 0x65, 0x03, 0x04, 0x02, 0x03, 0x05,
                   0x00, 0x04, 0x40

   DSA signatures MUST use hashes that are equal in size to the number
   of bits of q, the group generated by the DSA key's generator value.



Callas, et al               Standards Track                    [Page 23]

RFC 4880                 OpenPGP Message Format            November 2007


   If the output size of the chosen hash is larger than the number of
   bits of q, the hash result is truncated to fit by taking the number
   of leftmost bits equal to the number of bits of q.  This (possibly
   truncated) hash function result is treated as a number and used
   directly in the DSA signature algorithm.

5.2.3.  Version 4 Signature Packet Format

   The body of a version 4 Signature packet contains:

     - One-octet version number (4).

     - One-octet signature type.

     - One-octet public-key algorithm.

     - One-octet hash algorithm.

     - Two-octet scalar octet count for following hashed subpacket data.
       Note that this is the length in octets of all of the hashed
       subpackets; a pointer incremented by this number will skip over
       the hashed subpackets.

     - Hashed subpacket data set (zero or more subpackets).

     - Two-octet scalar octet count for the following unhashed subpacket
       data.  Note that this is the length in octets of all of the
       unhashed subpackets; a pointer incremented by this number will
       skip over the unhashed subpackets.

     - Unhashed subpacket data set (zero or more subpackets).

     - Two-octet field holding the left 16 bits of the signed hash
       value.

     - One or more multiprecision integers comprising the signature.
       This portion is algorithm specific, as described above.

   The concatenation of the data being signed and the signature data
   from the version number through the hashed subpacket data (inclusive)
   is hashed.  The resulting hash value is what is signed.  The left 16
   bits of the hash are included in the Signature packet to provide a
   quick test to reject some invalid signatures.

   There are two fields consisting of Signature subpackets.  The first
   field is hashed with the rest of the signature data, while the second
   is unhashed.  The second set of subpackets is not cryptographically




Callas, et al               Standards Track                    [Page 24]

RFC 4880                 OpenPGP Message Format            November 2007


   protected by the signature and should include only advisory
   information.

   The algorithms for converting the hash function result to a signature
   are described in a section below.

5.2.3.1.  Signature Subpacket Specification

   A subpacket data set consists of zero or more Signature subpackets.
   In Signature packets, the subpacket data set is preceded by a two-
   octet scalar count of the length in octets of all the subpackets.  A
   pointer incremented by this number will skip over the subpacket data
   set.

   Each subpacket consists of a subpacket header and a body.  The header
   consists of:

     - the subpacket length (1, 2, or 5 octets),

     - the subpacket type (1 octet),

   and is followed by the subpacket-specific data.

   The length includes the type octet but not this length.  Its format
   is similar to the "new" format packet header lengths, but cannot have
   Partial Body Lengths.  That is:

       if the 1st octet <  192, then
           lengthOfLength = 1
           subpacketLen = 1st_octet

       if the 1st octet >= 192 and < 255, then
           lengthOfLength = 2
           subpacketLen = ((1st_octet - 192) << 8) + (2nd_octet) + 192

       if the 1st octet = 255, then
           lengthOfLength = 5
           subpacket length = [four-octet scalar starting at 2nd_octet]

   The value of the subpacket type octet may be:

            0 = Reserved
            1 = Reserved
            2 = Signature Creation Time
            3 = Signature Expiration Time
            4 = Exportable Certification
            5 = Trust Signature
            6 = Regular Expression



Callas, et al               Standards Track                    [Page 25]

RFC 4880                 OpenPGP Message Format            November 2007


            7 = Revocable
            8 = Reserved
            9 = Key Expiration Time
           10 = Placeholder for backward compatibility
           11 = Preferred Symmetric Algorithms
           12 = Revocation Key
           13 = Reserved
           14 = Reserved
           15 = Reserved
           16 = Issuer
           17 = Reserved
           18 = Reserved
           19 = Reserved
           20 = Notation Data
           21 = Preferred Hash Algorithms
           22 = Preferred Compression Algorithms
           23 = Key Server Preferences
           24 = Preferred Key Server
           25 = Primary User ID
           26 = Policy URI
           27 = Key Flags
           28 = Signer's User ID
           29 = Reason for Revocation
           30 = Features
           31 = Signature Target
           32 = Embedded Signature
   100 To 110 = Private or experimental

   An implementation SHOULD ignore any subpacket of a type that it does
   not recognize.

   Bit 7 of the subpacket type is the "critical" bit.  If set, it
   denotes that the subpacket is one that is critical for the evaluator
   of the signature to recognize.  If a subpacket is encountered that is
   marked critical but is unknown to the evaluating software, the
   evaluator SHOULD consider the signature to be in error.

   An evaluator may "recognize" a subpacket, but not implement it.  The
   purpose of the critical bit is to allow the signer to tell an
   evaluator that it would prefer a new, unknown feature to generate an
   error than be ignored.

   Implementations SHOULD implement the three preferred algorithm
   subpackets (11, 21, and 22), as well as the "Reason for Revocation"
   subpacket.  Note, however, that if an implementation chooses not to
   implement some of the preferences, it is required to behave in a
   polite manner to respect the wishes of those users who do implement
   these preferences.



Callas, et al               Standards Track                    [Page 26]

RFC 4880                 OpenPGP Message Format            November 2007


5.2.3.2.  Signature Subpacket Types

   A number of subpackets are currently defined.  Some subpackets apply
   to the signature itself and some are attributes of the key.
   Subpackets that are found on a self-signature are placed on a
   certification made by the key itself.  Note that a key may have more
   than one User ID, and thus may have more than one self-signature, and
   differing subpackets.

   A subpacket may be found either in the hashed or unhashed subpacket
   sections of a signature.  If a subpacket is not hashed, then the
   information in it cannot be considered definitive because it is not
   part of the signature proper.

5.2.3.3.  Notes on Self-Signatures

   A self-signature is a binding signature made by the key to which the
   signature refers.  There are three types of self-signatures, the
   certification signatures (types 0x10-0x13), the direct-key signature
   (type 0x1F), and the subkey binding signature (type 0x18).  For
   certification self-signatures, each User ID may have a self-
   signature, and thus different subpackets in those self-signatures.
   For subkey binding signatures, each subkey in fact has a self-
   signature.  Subpackets that appear in a certification self-signature
   apply to the user name, and subpackets that appear in the subkey
   self-signature apply to the subkey.  Lastly, subpackets on the
   direct-key signature apply to the entire key.

   Implementing software should interpret a self-signature's preference
   subpackets as narrowly as possible.  For example, suppose a key has
   two user names, Alice and Bob.  Suppose that Alice prefers the
   symmetric algorithm CAST5, and Bob prefers IDEA or TripleDES.  If the
   software locates this key via Alice's name, then the preferred
   algorithm is CAST5; if software locates the key via Bob's name, then
   the preferred algorithm is IDEA.  If the key is located by Key ID,
   the algorithm of the primary User ID of the key provides the
   preferred symmetric algorithm.

   Revoking a self-signature or allowing it to expire has a semantic
   meaning that varies with the signature type.  Revoking the self-
   signature on a User ID effectively retires that user name.  The
   self-signature is a statement, "My name X is tied to my signing key
   K" and is corroborated by other users' certifications.  If another
   user revokes their certification, they are effectively saying that
   they no longer believe that name and that key are tied together.
   Similarly, if the users themselves revoke their self-signature, then
   the users no longer go by that name, no longer have that email
   address, etc.  Revoking a binding signature effectively retires that



Callas, et al               Standards Track                    [Page 27]

RFC 4880                 OpenPGP Message Format            November 2007


   subkey.  Revoking a direct-key signature cancels that signature.
   Please see the "Reason for Revocation" subpacket (Section 5.2.3.23)
   for more relevant detail.

   Since a self-signature contains important information about the key's
   use, an implementation SHOULD allow the user to rewrite the self-
   signature, and important information in it, such as preferences and
   key expiration.

   It is good practice to verify that a self-signature imported into an
   implementation doesn't advertise features that the implementation
   doesn't support, rewriting the signature as appropriate.

   An implementation that encounters multiple self-signatures on the
   same object may resolve the ambiguity in any way it sees fit, but it
   is RECOMMENDED that priority be given to the most recent self-
   signature.

5.2.3.4.  Signature Creation Time

   (4-octet time field)

   The time the signature was made.

   MUST be present in the hashed area.

5.2.3.5.  Issuer

   (8-octet Key ID)

   The OpenPGP Key ID of the key issuing the signature.

5.2.3.6.  Key Expiration Time

   (4-octet time field)

   The validity period of the key.  This is the number of seconds after
   the key creation time that the key expires.  If this is not present
   or has a value of zero, the key never expires.  This is found only on
   a self-signature.

5.2.3.7.  Preferred Symmetric Algorithms

   (array of one-octet values)

   Symmetric algorithm numbers that indicate which algorithms the key
   holder prefers to use.  The subpacket body is an ordered list of
   octets with the most preferred listed first.  It is assumed that only



Callas, et al               Standards Track                    [Page 28]

RFC 4880                 OpenPGP Message Format            November 2007


   algorithms listed are supported by the recipient's software.
   Algorithm numbers are in Section 9.  This is only found on a self-
   signature.

5.2.3.8.  Preferred Hash Algorithms

   (array of one-octet values)

   Message digest algorithm numbers that indicate which algorithms the
   key holder prefers to receive.  Like the preferred symmetric
   algorithms, the list is ordered.  Algorithm numbers are in Section 9.
   This is only found on a self-signature.

5.2.3.9.  Preferred Compression Algorithms

   (array of one-octet values)

   Compression algorithm numbers that indicate which algorithms the key
   holder prefers to use.  Like the preferred symmetric algorithms, the
   list is ordered.  Algorithm numbers are in Section 9.  If this
   subpacket is not included, ZIP is preferred.  A zero denotes that
   uncompressed data is preferred; the key holder's software might have
   no compression software in that implementation.  This is only found
   on a self-signature.

5.2.3.10.  Signature Expiration Time

   (4-octet time field)

   The validity period of the signature.  This is the number of seconds
   after the signature creation time that the signature expires.  If
   this is not present or has a value of zero, it never expires.

5.2.3.11.  Exportable Certification

   (1 octet of exportability, 0 for not, 1 for exportable)

   This subpacket denotes whether a certification signature is
   "exportable", to be used by other users than the signature's issuer.
   The packet body contains a Boolean flag indicating whether the
   signature is exportable.  If this packet is not present, the
   certification is exportable; it is equivalent to a flag containing a
   1.

   Non-exportable, or "local", certifications are signatures made by a
   user to mark a key as valid within that user's implementation only.





Callas, et al               Standards Track                    [Page 29]

RFC 4880                 OpenPGP Message Format            November 2007


   Thus, when an implementation prepares a user's copy of a key for
   transport to another user (this is the process of "exporting" the
   key), any local certification signatures are deleted from the key.

   The receiver of a transported key "imports" it, and likewise trims
   any local certifications.  In normal operation, there won't be any,
   assuming the import is performed on an exported key.  However, there
   are instances where this can reasonably happen.  For example, if an
   implementation allows keys to be imported from a key database in
   addition to an exported key, then this situation can arise.

   Some implementations do not represent the interest of a single user
   (for example, a key server).  Such implementations always trim local
   certifications from any key they handle.

5.2.3.12.  Revocable

   (1 octet of revocability, 0 for not, 1 for revocable)

   Signature's revocability status.  The packet body contains a Boolean
   flag indicating whether the signature is revocable.  Signatures that
   are not revocable have any later revocation signatures ignored.  They
   represent a commitment by the signer that he cannot revoke his
   signature for the life of his key.  If this packet is not present,
   the signature is revocable.

5.2.3.13.  Trust Signature

   (1 octet "level" (depth), 1 octet of trust amount)

   Signer asserts that the key is not only valid but also trustworthy at
   the specified level.  Level 0 has the same meaning as an ordinary
   validity signature.  Level 1 means that the signed key is asserted to
   be a valid trusted introducer, with the 2nd octet of the body
   specifying the degree of trust.  Level 2 means that the signed key is
   asserted to be trusted to issue level 1 trust signatures, i.e., that
   it is a "meta introducer".  Generally, a level n trust signature
   asserts that a key is trusted to issue level n-1 trust signatures.
   The trust amount is in a range from 0-255, interpreted such that
   values less than 120 indicate partial trust and values of 120 or
   greater indicate complete trust.  Implementations SHOULD emit values
   of 60 for partial trust and 120 for complete trust.









Callas, et al               Standards Track                    [Page 30]

RFC 4880                 OpenPGP Message Format            November 2007


5.2.3.14.  Regular Expression

   (null-terminated regular expression)

   Used in conjunction with trust Signature packets (of level > 0) to
   limit the scope of trust that is extended.  Only signatures by the
   target key on User IDs that match the regular expression in the body
   of this packet have trust extended by the trust Signature subpacket.
   The regular expression uses the same syntax as the Henry Spencer's
   "almost public domain" regular expression [REGEX] package.  A
   description of the syntax is found in Section 8 below.

5.2.3.15.  Revocation Key

   (1 octet of class, 1 octet of public-key algorithm ID, 20 octets of
   fingerprint)

   Authorizes the specified key to issue revocation signatures for this
   key.  Class octet must have bit 0x80 set.  If the bit 0x40 is set,
   then this means that the revocation information is sensitive.  Other
   bits are for future expansion to other kinds of authorizations.  This
   is found on a self-signature.

   If the "sensitive" flag is set, the keyholder feels this subpacket
   contains private trust information that describes a real-world
   sensitive relationship.  If this flag is set, implementations SHOULD
   NOT export this signature to other users except in cases where the
   data needs to be available: when the signature is being sent to the
   designated revoker, or when it is accompanied by a revocation
   signature from that revoker.  Note that it may be appropriate to
   isolate this subpacket within a separate signature so that it is not
   combined with other subpackets that need to be exported.

5.2.3.16.  Notation Data

       (4 octets of flags, 2 octets of name length (M),
                           2 octets of value length (N),
                           M octets of name data,
                           N octets of value data)

   This subpacket describes a "notation" on the signature that the
   issuer wishes to make.  The notation has a name and a value, each of
   which are strings of octets.  There may be more than one notation in
   a signature.  Notations can be used for any extension the issuer of
   the signature cares to make.  The "flags" field holds four octets of
   flags.





Callas, et al               Standards Track                    [Page 31]

RFC 4880                 OpenPGP Message Format            November 2007


   All undefined flags MUST be zero.  Defined flags are as follows:

       First octet: 0x80 = human-readable.  This note value is text.
       Other octets: none.

   Notation names are arbitrary strings encoded in UTF-8.  They reside
   in two namespaces: The IETF namespace and the user namespace.

   The IETF namespace is registered with IANA.  These names MUST NOT
   contain the "@" character (0x40).  This is a tag for the user
   namespace.

   Names in the user namespace consist of a UTF-8 string tag followed by
   "@" followed by a DNS domain name.  Note that the tag MUST NOT
   contain an "@" character.  For example, the "sample" tag used by
   Example Corporation could be "sample@example.com".

   Names in a user space are owned and controlled by the owners of that
   domain.  Obviously, it's bad form to create a new name in a DNS space
   that you don't own.

   Since the user namespace is in the form of an email address,
   implementers MAY wish to arrange for that address to reach a person
   who can be consulted about the use of the named tag.  Note that due
   to UTF-8 encoding, not all valid user space name tags are valid email
   addresses.

   If there is a critical notation, the criticality applies to that
   specific notation and not to notations in general.

5.2.3.17.  Key Server Preferences

   (N octets of flags)

   This is a list of one-bit flags that indicate preferences that the
   key holder has about how the key is handled on a key server.  All
   undefined flags MUST be zero.

   First octet: 0x80 = No-modify
       the key holder requests that this key only be modified or updated
       by the key holder or an administrator of the key server.

   This is found only on a self-signature.








Callas, et al               Standards Track                    [Page 32]

RFC 4880                 OpenPGP Message Format            November 2007


5.2.3.18.  Preferred Key Server

   (String)

   This is a URI of a key server that the key holder prefers be used for
   updates.  Note that keys with multiple User IDs can have a preferred
   key server for each User ID.  Note also that since this is a URI, the
   key server can actually be a copy of the key retrieved by ftp, http,
   finger, etc.

5.2.3.19.  Primary User ID

   (1 octet, Boolean)

   This is a flag in a User ID's self-signature that states whether this
   User ID is the main User ID for this key.  It is reasonable for an
   implementation to resolve ambiguities in preferences, etc. by
   referring to the primary User ID.  If this flag is absent, its value
   is zero.  If more than one User ID in a key is marked as primary, the
   implementation may resolve the ambiguity in any way it sees fit, but
   it is RECOMMENDED that priority be given to the User ID with the most
   recent self-signature.

   When appearing on a self-signature on a User ID packet, this
   subpacket applies only to User ID packets.  When appearing on a
   self-signature on a User Attribute packet, this subpacket applies
   only to User Attribute packets.  That is to say, there are two
   different and independent "primaries" -- one for User IDs, and one
   for User Attributes.

5.2.3.20.  Policy URI

   (String)

   This subpacket contains a URI of a document that describes the policy
   under which the signature was issued.

5.2.3.21.  Key Flags

   (N octets of flags)

   This subpacket contains a list of binary flags that hold information
   about a key.  It is a string of octets, and an implementation MUST
   NOT assume a fixed size.  This is so it can grow over time.  If a
   list is shorter than an implementation expects, the unstated flags
   are considered to be zero.  The defined flags are as follows:





Callas, et al               Standards Track                    [Page 33]

RFC 4880                 OpenPGP Message Format            November 2007


       First octet:

       0x01 - This key may be used to certify other keys.

       0x02 - This key may be used to sign data.

       0x04 - This key may be used to encrypt communications.

       0x08 - This key may be used to encrypt storage.

       0x10 - The private component of this key may have been split
              by a secret-sharing mechanism.

       0x20 - This key may be used for authentication.

       0x80 - The private component of this key may be in the
              possession of more than one person.

   Usage notes:

   The flags in this packet may appear in self-signatures or in
   certification signatures.  They mean different things depending on
   who is making the statement -- for example, a certification signature
   that has the "sign data" flag is stating that the certification is
   for that use.  On the other hand, the "communications encryption"
   flag in a self-signature is stating a preference that a given key be
   used for communications.  Note however, that it is a thorny issue to
   determine what is "communications" and what is "storage".  This
   decision is left wholly up to the implementation; the authors of this
   document do not claim any special wisdom on the issue and realize
   that accepted opinion may change.

   The "split key" (0x10) and "group key" (0x80) flags are placed on a
   self-signature only; they are meaningless on a certification
   signature.  They SHOULD be placed only on a direct-key signature
   (type 0x1F) or a subkey signature (type 0x18), one that refers to the
   key the flag applies to.

5.2.3.22.  Signer's User ID

   (String)

   This subpacket allows a keyholder to state which User ID is
   responsible for the signing.  Many keyholders use a single key for
   different purposes, such as business communications as well as
   personal communications.  This subpacket allows such a keyholder to
   state which of their roles is making a signature.




Callas, et al               Standards Track                    [Page 34]

RFC 4880                 OpenPGP Message Format            November 2007


   This subpacket is not appropriate to use to refer to a User Attribute
   packet.

5.2.3.23.  Reason for Revocation

   (1 octet of revocation code, N octets of reason string)

   This subpacket is used only in key revocation and certification
   revocation signatures.  It describes the reason why the key or
   certificate was revoked.

   The first octet contains a machine-readable code that denotes the
   reason for the revocation:

        0  - No reason specified (key revocations or cert revocations)
        1  - Key is superseded (key revocations)
        2  - Key material has been compromised (key revocations)
        3  - Key is retired and no longer used (key revocations)
        32 - User ID information is no longer valid (cert revocations)
   100-110 - Private Use

   Following the revocation code is a string of octets that gives
   information about the Reason for Revocation in human-readable form
   (UTF-8).  The string may be null, that is, of zero length.  The
   length of the subpacket is the length of the reason string plus one.
   An implementation SHOULD implement this subpacket, include it in all
   revocation signatures, and interpret revocations appropriately.
   There are important semantic differences between the reasons, and
   there are thus important reasons for revoking signatures.

   If a key has been revoked because of a compromise, all signatures
   created by that key are suspect.  However, if it was merely
   superseded or retired, old signatures are still valid.  If the
   revoked signature is the self-signature for certifying a User ID, a
   revocation denotes that that user name is no longer in use.  Such a
   revocation SHOULD include a 0x20 code.

   Note that any signature may be revoked, including a certification on
   some other person's key.  There are many good reasons for revoking a
   certification signature, such as the case where the keyholder leaves
   the employ of a business with an email address.  A revoked
   certification is no longer a part of validity calculations.









Callas, et al               Standards Track                    [Page 35]

RFC 4880                 OpenPGP Message Format            November 2007


5.2.3.24.  Features

   (N octets of flags)

   The Features subpacket denotes which advanced OpenPGP features a
   user's implementation supports.  This is so that as features are
   added to OpenPGP that cannot be backwards-compatible, a user can
   state that they can use that feature.  The flags are single bits that
   indicate that a given feature is supported.

   This subpacket is similar to a preferences subpacket, and only
   appears in a self-signature.

   An implementation SHOULD NOT use a feature listed when sending to a
   user who does not state that they can use it.

   Defined features are as follows:

       First octet:

       0x01 - Modification Detection (packets 18 and 19)

   If an implementation implements any of the defined features, it
   SHOULD implement the Features subpacket, too.

   An implementation may freely infer features from other suitable
   implementation-dependent mechanisms.

5.2.3.25.  Signature Target

   (1 octet public-key algorithm, 1 octet hash algorithm, N octets hash)

   This subpacket identifies a specific target signature to which a
   signature refers.  For revocation signatures, this subpacket
   provides explicit designation of which signature is being revoked.
   For a third-party or timestamp signature, this designates what
   signature is signed.  All arguments are an identifier of that target
   signature.

   The N octets of hash data MUST be the size of the hash of the
   signature.  For example, a target signature with a SHA-1 hash MUST
   have 20 octets of hash data.









Callas, et al               Standards Track                    [Page 36]

RFC 4880                 OpenPGP Message Format            November 2007


5.2.3.26.  Embedded Signature

   (1 signature packet body)

   This subpacket contains a complete Signature packet body as
   specified in Section 5.2 above.  It is useful when one signature
   needs to refer to, or be incorporated in, another signature.

5.2.4.  Computing Signatures

   All signatures are formed by producing a hash over the signature
   data, and then using the resulting hash in the signature algorithm.

   For binary document signatures (type 0x00), the document data is
   hashed directly.  For text document signatures (type 0x01), the
   document is canonicalized by converting line endings to <CR><LF>,
   and the resulting data is hashed.

   When a signature is made over a key, the hash data starts with the
   octet 0x99, followed by a two-octet length of the key, and then body
   of the key packet.  (Note that this is an old-style packet header for
   a key packet with two-octet length.)  A subkey binding signature
   (type 0x18) or primary key binding signature (type 0x19) then hashes
   the subkey using the same format as the main key (also using 0x99 as
   the first octet).  Key revocation signatures (types 0x20 and 0x28)
   hash only the key being revoked.

   A certification signature (type 0x10 through 0x13) hashes the User
   ID being bound to the key into the hash context after the above
   data.  A V3 certification hashes the contents of the User ID or
   attribute packet packet, without any header.  A V4 certification
   hashes the constant 0xB4 for User ID certifications or the constant
   0xD1 for User Attribute certifications, followed by a four-octet
   number giving the length of the User ID or User Attribute data, and
   then the User ID or User Attribute data.

   When a signature is made over a Signature packet (type 0x50), the
   hash data starts with the octet 0x88, followed by the four-octet
   length of the signature, and then the body of the Signature packet.
   (Note that this is an old-style packet header for a Signature packet
   with the length-of-length set to zero.)  The unhashed subpacket data
   of the Signature packet being hashed is not included in the hash, and
   the unhashed subpacket data length value is set to zero.

   Once the data body is hashed, then a trailer is hashed.  A V3
   signature hashes five octets of the packet body, starting from the
   signature type field.  This data is the signature type, followed by
   the four-octet signature time.  A V4 signature hashes the packet body



Callas, et al               Standards Track                    [Page 37]

RFC 4880                 OpenPGP Message Format            November 2007


   starting from its first field, the version number, through the end
   of the hashed subpacket data.  Thus, the fields hashed are the
   signature version, the signature type, the public-key algorithm, the
   hash algorithm, the hashed subpacket length, and the hashed
   subpacket body.

   V4 signatures also hash in a final trailer of six octets: the
   version of the Signature packet, i.e., 0x04; 0xFF; and a four-octet,
   big-endian number that is the length of the hashed data from the
   Signature packet (note that this number does not include these final
   six octets).

   After all this has been hashed in a single hash context, the
   resulting hash field is used in the signature algorithm and placed
   at the end of the Signature packet.

5.2.4.1.  Subpacket Hints

   It is certainly possible for a signature to contain conflicting
   information in subpackets.  For example, a signature may contain
   multiple copies of a preference or multiple expiration times.  In
   most cases, an implementation SHOULD use the last subpacket in the
   signature, but MAY use any conflict resolution scheme that makes
   more sense.  Please note that we are intentionally leaving conflict
   resolution to the implementer; most conflicts are simply syntax
   errors, and the wishy-washy language here allows a receiver to be
   generous in what they accept, while putting pressure on a creator to
   be stingy in what they generate.

   Some apparent conflicts may actually make sense -- for example,
   suppose a keyholder has a V3 key and a V4 key that share the same
   RSA key material.  Either of these keys can verify a signature
   created by the other, and it may be reasonable for a signature to
   contain an issuer subpacket for each key, as a way of explicitly
   tying those keys to the signature.

5.3.  Symmetric-Key Encrypted Session Key Packets (Tag 3)

   The Symmetric-Key Encrypted Session Key packet holds the
   symmetric-key encryption of a session key used to encrypt a message.
   Zero or more Public-Key Encrypted Session Key packets and/or
   Symmetric-Key Encrypted Session Key packets may precede a
   Symmetrically Encrypted Data packet that holds an encrypted message.
   The message is encrypted with a session key, and the session key is
   itself encrypted and stored in the Encrypted Session Key packet or
   the Symmetric-Key Encrypted Session Key packet.





Callas, et al               Standards Track                    [Page 38]

RFC 4880                 OpenPGP Message Format            November 2007


   If the Symmetrically Encrypted Data packet is preceded by one or
   more Symmetric-Key Encrypted Session Key packets, each specifies a
   passphrase that may be used to decrypt the message.  This allows a
   message to be encrypted to a number of public keys, and also to one
   or more passphrases.  This packet type is new and is not generated
   by PGP 2.x or PGP 5.0.

   The body of this packet consists of:

     - A one-octet version number.  The only currently defined version
       is 4.

     - A one-octet number describing the symmetric algorithm used.

     - A string-to-key (S2K) specifier, length as defined above.

     - Optionally, the encrypted session key itself, which is decrypted
       with the string-to-key object.

   If the encrypted session key is not present (which can be detected
   on the basis of packet length and S2K specifier size), then the S2K
   algorithm applied to the passphrase produces the session key for
   decrypting the file, using the symmetric cipher algorithm from the
   Symmetric-Key Encrypted Session Key packet.

   If the encrypted session key is present, the result of applying the
   S2K algorithm to the passphrase is used to decrypt just that
   encrypted session key field, using CFB mode with an IV of all zeros.
   The decryption result consists of a one-octet algorithm identifier
   that specifies the symmetric-key encryption algorithm used to
   encrypt the following Symmetrically Encrypted Data packet, followed
   by the session key octets themselves.

   Note: because an all-zero IV is used for this decryption, the S2K
   specifier MUST use a salt value, either a Salted S2K or an
   Iterated-Salted S2K.  The salt value will ensure that the decryption
   key is not repeated even if the passphrase is reused.

5.4.  One-Pass Signature Packets (Tag 4)

   The One-Pass Signature packet precedes the signed data and contains
   enough information to allow the receiver to begin calculating any
   hashes needed to verify the signature.  It allows the Signature
   packet to be placed at the end of the message, so that the signer
   can compute the entire signed message in one pass.

   A One-Pass Signature does not interoperate with PGP 2.6.x or
   earlier.



Callas, et al               Standards Track                    [Page 39]

RFC 4880                 OpenPGP Message Format            November 2007


   The body of this packet consists of:

     - A one-octet version number.  The current version is 3.

     - A one-octet signature type.  Signature types are described in
       Section 5.2.1.

     - A one-octet number describing the hash algorithm used.

     - A one-octet number describing the public-key algorithm used.

     - An eight-octet number holding the Key ID of the signing key.

     - A one-octet number holding a flag showing whether the signature
       is nested.  A zero value indicates that the next packet is
       another One-Pass Signature packet that describes another
       signature to be applied to the same message data.

   Note that if a message contains more than one one-pass signature,
   then the Signature packets bracket the message; that is, the first
   Signature packet after the message corresponds to the last one-pass
   packet and the final Signature packet corresponds to the first
   one-pass packet.

5.5.  Key Material Packet

   A key material packet contains all the information about a public or
   private key.  There are four variants of this packet type, and two
   major versions.  Consequently, this section is complex.

5.5.1.  Key Packet Variants

5.5.1.1.  Public-Key Packet (Tag 6)

   A Public-Key packet starts a series of packets that forms an OpenPGP
   key (sometimes called an OpenPGP certificate).

5.5.1.2.  Public-Subkey Packet (Tag 14)

   A Public-Subkey packet (tag 14) has exactly the same format as a
   Public-Key packet, but denotes a subkey.  One or more subkeys may be
   associated with a top-level key.  By convention, the top-level key
   provides signature services, and the subkeys provide encryption
   services.

   Note: in PGP 2.6.x, tag 14 was intended to indicate a comment
   packet.  This tag was selected for reuse because no previous version
   of PGP ever emitted comment packets but they did properly ignore



Callas, et al               Standards Track                    [Page 40]

RFC 4880                 OpenPGP Message Format            November 2007


   them.  Public-Subkey packets are ignored by PGP 2.6.x and do not
   cause it to fail, providing a limited degree of backward
   compatibility.

5.5.1.3.  Secret-Key Packet (Tag 5)

   A Secret-Key packet contains all the information that is found in a
   Public-Key packet, including the public-key material, but also
   includes the secret-key material after all the public-key fields.

5.5.1.4.  Secret-Subkey Packet (Tag 7)

   A Secret-Subkey packet (tag 7) is the subkey analog of the Secret
   Key packet and has exactly the same format.

5.5.2.  Public-Key Packet Formats

   There are two versions of key-material packets.  Version 3 packets
   were first generated by PGP 2.6.  Version 4 keys first appeared in
   PGP 5.0 and are the preferred key version for OpenPGP.

   OpenPGP implementations MUST create keys with version 4 format.  V3
   keys are deprecated; an implementation MUST NOT generate a V3 key,
   but MAY accept it.

   A version 3 public key or public-subkey packet contains:

     - A one-octet version number (3).

     - A four-octet number denoting the time that the key was created.

     - A two-octet number denoting the time in days that this key is
       valid.  If this number is zero, then it does not expire.

     - A one-octet number denoting the public-key algorithm of this key.

     - A series of multiprecision integers comprising the key material:

           - a multiprecision integer (MPI) of RSA public modulus n;

           - an MPI of RSA public encryption exponent e.

   V3 keys are deprecated.  They contain three weaknesses.  First, it is
   relatively easy to construct a V3 key that has the same Key ID as any
   other key because the Key ID is simply the low 64 bits of the public
   modulus.  Secondly, because the fingerprint of a V3 key hashes the
   key material, but not its length, there is an increased opportunity
   for fingerprint collisions.  Third, there are weaknesses in the MD5



Callas, et al               Standards Track                    [Page 41]

RFC 4880                 OpenPGP Message Format            November 2007


   hash algorithm that make developers prefer other algorithms.  See
   below for a fuller discussion of Key IDs and fingerprints.

   V2 keys are identical to the deprecated V3 keys except for the
   version number.  An implementation MUST NOT generate them and MAY
   accept or reject them as it sees fit.

   The version 4 format is similar to the version 3 format except for
   the absence of a validity period.  This has been moved to the
   Signature packet.  In addition, fingerprints of version 4 keys are
   calculated differently from version 3 keys, as described in the
   section "Enhanced Key Formats".

   A version 4 packet contains:

     - A one-octet version number (4).

     - A four-octet number denoting the time that the key was created.

     - A one-octet number denoting the public-key algorithm of this key.

     - A series of multiprecision integers comprising the key material.
       This algorithm-specific portion is:

       Algorithm-Specific Fields for RSA public keys:

         - multiprecision integer (MPI) of RSA public modulus n;

         - MPI of RSA public encryption exponent e.

       Algorithm-Specific Fields for DSA public keys:

         - MPI of DSA prime p;

         - MPI of DSA group order q (q is a prime divisor of p-1);

         - MPI of DSA group generator g;

         - MPI of DSA public-key value y (= g**x mod p where x
           is secret).

       Algorithm-Specific Fields for Elgamal public keys:

         - MPI of Elgamal prime p;

         - MPI of Elgamal group generator g;





Callas, et al               Standards Track                    [Page 42]

RFC 4880                 OpenPGP Message Format            November 2007


         - MPI of Elgamal public key value y (= g**x mod p where x
           is secret).

5.5.3.  Secret-Key Packet Formats

   The Secret-Key and Secret-Subkey packets contain all the data of the
   Public-Key and Public-Subkey packets, with additional algorithm-
   specific secret-key data appended, usually in encrypted form.

   The packet contains:

     - A Public-Key or Public-Subkey packet, as described above.

     - One octet indicating string-to-key usage conventions.  Zero
       indicates that the secret-key data is not encrypted.  255 or 254
       indicates that a string-to-key specifier is being given.  Any
       other value is a symmetric-key encryption algorithm identifier.

     - [Optional] If string-to-key usage octet was 255 or 254, a one-
       octet symmetric encryption algorithm.

     - [Optional] If string-to-key usage octet was 255 or 254, a
       string-to-key specifier.  The length of the string-to-key
       specifier is implied by its type, as described above.

     - [Optional] If secret data is encrypted (string-to-key usage octet
       not zero), an Initial Vector (IV) of the same length as the
       cipher's block size.

     - Plain or encrypted multiprecision integers comprising the secret
       key data.  These algorithm-specific fields are as described
       below.

     - If the string-to-key usage octet is zero or 255, then a two-octet
       checksum of the plaintext of the algorithm-specific portion (sum
       of all octets, mod 65536).  If the string-to-key usage octet was
       254, then a 20-octet SHA-1 hash of the plaintext of the
       algorithm-specific portion.  This checksum or hash is encrypted
       together with the algorithm-specific fields (if string-to-key
       usage octet is not zero).  Note that for all other values, a
       two-octet checksum is required.

       Algorithm-Specific Fields for RSA secret keys:

       - multiprecision integer (MPI) of RSA secret exponent d.

       - MPI of RSA secret prime value p.




Callas, et al               Standards Track                    [Page 43]

RFC 4880                 OpenPGP Message Format            November 2007


       - MPI of RSA secret prime value q (p < q).

       - MPI of u, the multiplicative inverse of p, mod q.

       Algorithm-Specific Fields for DSA secret keys:

       - MPI of DSA secret exponent x.

       Algorithm-Specific Fields for Elgamal secret keys:

       - MPI of Elgamal secret exponent x.

   Secret MPI values can be encrypted using a passphrase.  If a string-
   to-key specifier is given, that describes the algorithm for
   converting the passphrase to a key, else a simple MD5 hash of the
   passphrase is used.  Implementations MUST use a string-to-key
   specifier; the simple hash is for backward compatibility and is
   deprecated, though implementations MAY continue to use existing
   private keys in the old format.  The cipher for encrypting the MPIs
   is specified in the Secret-Key packet.

   Encryption/decryption of the secret data is done in CFB mode using
   the key created from the passphrase and the Initial Vector from the
   packet.  A different mode is used with V3 keys (which are only RSA)
   than with other key formats.  With V3 keys, the MPI bit count prefix
   (i.e., the first two octets) is not encrypted.  Only the MPI non-
   prefix data is encrypted.  Furthermore, the CFB state is
   resynchronized at the beginning of each new MPI value, so that the
   CFB block boundary is aligned with the start of the MPI data.

   With V4 keys, a simpler method is used.  All secret MPI values are
   encrypted in CFB mode, including the MPI bitcount prefix.

   The two-octet checksum that follows the algorithm-specific portion is
   the algebraic sum, mod 65536, of the plaintext of all the algorithm-
   specific octets (including MPI prefix and data).  With V3 keys, the
   checksum is stored in the clear.  With V4 keys, the checksum is
   encrypted like the algorithm-specific data.  This value is used to
   check that the passphrase was correct.  However, this checksum is
   deprecated; an implementation SHOULD NOT use it, but should rather
   use the SHA-1 hash denoted with a usage octet of 254.  The reason for
   this is that there are some attacks that involve undetectably
   modifying the secret key.








Callas, et al               Standards Track                    [Page 44]

RFC 4880                 OpenPGP Message Format            November 2007


5.6.  Compressed Data Packet (Tag 8)

   The Compressed Data packet contains compressed data.  Typically, this
   packet is found as the contents of an encrypted packet, or following
   a Signature or One-Pass Signature packet, and contains a literal data
   packet.

   The body of this packet consists of:

     - One octet that gives the algorithm used to compress the packet.

     - Compressed data, which makes up the remainder of the packet.

   A Compressed Data Packet's body contains an block that compresses
   some set of packets.  See section "Packet Composition" for details on
   how messages are formed.

   ZIP-compressed packets are compressed with raw RFC 1951 [RFC1951]
   DEFLATE blocks.  Note that PGP V2.6 uses 13 bits of compression.  If
   an implementation uses more bits of compression, PGP V2.6 cannot
   decompress it.

   ZLIB-compressed packets are compressed with RFC 1950 [RFC1950] ZLIB-
   style blocks.

   BZip2-compressed packets are compressed using the BZip2 [BZ2]
   algorithm.

5.7.  Symmetrically Encrypted Data Packet (Tag 9)

   The Symmetrically Encrypted Data packet contains data encrypted with
   a symmetric-key algorithm.  When it has been decrypted, it contains
   other packets (usually a literal data packet or compressed data
   packet, but in theory other Symmetrically Encrypted Data packets or
   sequences of packets that form whole OpenPGP messages).

   The body of this packet consists of:

     - Encrypted data, the output of the selected symmetric-key cipher
       operating in OpenPGP's variant of Cipher Feedback (CFB) mode.

   The symmetric cipher used may be specified in a Public-Key or
   Symmetric-Key Encrypted Session Key packet that precedes the
   Symmetrically Encrypted Data packet.  In that case, the cipher
   algorithm octet is prefixed to the session key before it is
   encrypted.  If no packets of these types precede the encrypted data,
   the IDEA algorithm is used with the session key calculated as the MD5
   hash of the passphrase, though this use is deprecated.



Callas, et al               Standards Track                    [Page 45]

RFC 4880                 OpenPGP Message Format            November 2007


   The data is encrypted in CFB mode, with a CFB shift size equal to the
   cipher's block size.  The Initial Vector (IV) is specified as all
   zeros.  Instead of using an IV, OpenPGP prefixes a string of length
   equal to the block size of the cipher plus two to the data before it
   is encrypted.  The first block-size octets (for example, 8 octets for
   a 64-bit block length) are random, and the following two octets are
   copies of the last two octets of the IV.  For example, in an 8-octet
   block, octet 9 is a repeat of octet 7, and octet 10 is a repeat of
   octet 8.  In a cipher of length 16, octet 17 is a repeat of octet 15
   and octet 18 is a repeat of octet 16.  As a pedantic clarification,
   in both these examples, we consider the first octet to be numbered 1.

   After encrypting the first block-size-plus-two octets, the CFB state
   is resynchronized.  The last block-size octets of ciphertext are
   passed through the cipher and the block boundary is reset.

   The repetition of 16 bits in the random data prefixed to the message
   allows the receiver to immediately check whether the session key is
   incorrect.  See the "Security Considerations" section for hints on
   the proper use of this "quick check".

5.8.  Marker Packet (Obsolete Literal Packet) (Tag 10)

   An experimental version of PGP used this packet as the Literal
   packet, but no released version of PGP generated Literal packets with
   this tag.  With PGP 5.x, this packet has been reassigned and is
   reserved for use as the Marker packet.

   The body of this packet consists of:

     - The three octets 0x50, 0x47, 0x50 (which spell "PGP" in UTF-8).

   Such a packet MUST be ignored when received.  It may be placed at the
   beginning of a message that uses features not available in PGP 2.6.x
   in order to cause that version to report that newer software is
   necessary to process the message.

5.9.  Literal Data Packet (Tag 11)

   A Literal Data packet contains the body of a message; data that is
   not to be further interpreted.

   The body of this packet consists of:

     - A one-octet field that describes how the data is formatted.






Callas, et al               Standards Track                    [Page 46]

RFC 4880                 OpenPGP Message Format            November 2007


   If it is a 'b' (0x62), then the Literal packet contains binary data.
   If it is a 't' (0x74), then it contains text data, and thus may need
   line ends converted to local form, or other text-mode changes.  The
   tag 'u' (0x75) means the same as 't', but also indicates that
   implementation believes that the literal data contains UTF-8 text.

   Early versions of PGP also defined a value of 'l' as a 'local' mode
   for machine-local conversions.  RFC 1991 [RFC1991] incorrectly stated
   this local mode flag as '1' (ASCII numeral one).  Both of these local
   modes are deprecated.

     - File name as a string (one-octet length, followed by a file
       name).  This may be a zero-length string.  Commonly, if the
       source of the encrypted data is a file, this will be the name of
       the encrypted file.  An implementation MAY consider the file name
       in the Literal packet to be a more authoritative name than the
       actual file name.

   If the special name "_CONSOLE" is used, the message is considered to
   be "for your eyes only".  This advises that the message data is
   unusually sensitive, and the receiving program should process it more
   carefully, perhaps avoiding storing the received data to disk, for
   example.

     - A four-octet number that indicates a date associated with the
       literal data.  Commonly, the date might be the modification date
       of a file, or the time the packet was created, or a zero that
       indicates no specific time.

     - The remainder of the packet is literal data.

       Text data is stored with <CR><LF> text endings (i.e., network-
       normal line endings).  These should be converted to native line
       endings by the receiving software.

5.10.  Trust Packet (Tag 12)

   The Trust packet is used only within keyrings and is not normally
   exported.  Trust packets contain data that record the user's
   specifications of which key holders are trustworthy introducers,
   along with other information that implementing software uses for
   trust information.  The format of Trust packets is defined by a given
   implementation.

   Trust packets SHOULD NOT be emitted to output streams that are
   transferred to other users, and they SHOULD be ignored on any input
   other than local keyring files.




Callas, et al               Standards Track                    [Page 47]

RFC 4880                 OpenPGP Message Format            November 2007


5.11.  User ID Packet (Tag 13)

   A User ID packet consists of UTF-8 text that is intended to represent
   the name and email address of the key holder.  By convention, it
   includes an RFC 2822 [RFC2822] mail name-addr, but there are no
   restrictions on its content.  The packet length in the header
   specifies the length of the User ID.

5.12.  User Attribute Packet (Tag 17)

   The User Attribute packet is a variation of the User ID packet.  It
   is capable of storing more types of data than the User ID packet,
   which is limited to text.  Like the User ID packet, a User Attribute
   packet may be certified by the key owner ("self-signed") or any other
   key owner who cares to certify it.  Except as noted, a User Attribute
   packet may be used anywhere that a User ID packet may be used.

   While User Attribute packets are not a required part of the OpenPGP
   standard, implementations SHOULD provide at least enough
   compatibility to properly handle a certification signature on the
   User Attribute packet.  A simple way to do this is by treating the
   User Attribute packet as a User ID packet with opaque contents, but
   an implementation may use any method desired.

   The User Attribute packet is made up of one or more attribute
   subpackets.  Each subpacket consists of a subpacket header and a
   body.  The header consists of:

     - the subpacket length (1, 2, or 5 octets)

     - the subpacket type (1 octet)

   and is followed by the subpacket specific data.

   The only currently defined subpacket type is 1, signifying an image.
   An implementation SHOULD ignore any subpacket of a type that it does
   not recognize.  Subpacket types 100 through 110 are reserved for
   private or experimental use.

5.12.1.  The Image Attribute Subpacket

   The Image Attribute subpacket is used to encode an image, presumably
   (but not required to be) that of the key owner.

   The Image Attribute subpacket begins with an image header.  The first
   two octets of the image header contain the length of the image
   header.  Note that unlike other multi-octet numerical values in this
   document, due to a historical accident this value is encoded as a



Callas, et al               Standards Track                    [Page 48]

RFC 4880                 OpenPGP Message Format            November 2007


   little-endian number.  The image header length is followed by a
   single octet for the image header version.  The only currently
   defined version of the image header is 1, which is a 16-octet image
   header.  The first three octets of a version 1 image header are thus
   0x10, 0x00, 0x01.

   The fourth octet of a version 1 image header designates the encoding
   format of the image.  The only currently defined encoding format is
   the value 1 to indicate JPEG.  Image format types 100 through 110 are
   reserved for private or experimental use.  The rest of the version 1
   image header is made up of 12 reserved octets, all of which MUST be
   set to 0.

   The rest of the image subpacket contains the image itself.  As the
   only currently defined image type is JPEG, the image is encoded in
   the JPEG File Interchange Format (JFIF), a standard file format for
   JPEG images [JFIF].

   An implementation MAY try to determine the type of an image by
   examination of the image data if it is unable to handle a particular
   version of the image header or if a specified encoding format value
   is not recognized.

5.13.  Sym. Encrypted Integrity Protected Data Packet (Tag 18)

   The Symmetrically Encrypted Integrity Protected Data packet is a
   variant of the Symmetrically Encrypted Data packet.  It is a new
   feature created for OpenPGP that addresses the problem of detecting a
   modification to encrypted data.  It is used in combination with a
   Modification Detection Code packet.

   There is a corresponding feature in the features Signature subpacket
   that denotes that an implementation can properly use this packet
   type.  An implementation MUST support decrypting these packets and
   SHOULD prefer generating them to the older Symmetrically Encrypted
   Data packet when possible.  Since this data packet protects against
   modification attacks, this standard encourages its proliferation.
   While blanket adoption of this data packet would create
   interoperability problems, rapid adoption is nevertheless important.
   An implementation SHOULD specifically denote support for this packet,
   but it MAY infer it from other mechanisms.

   For example, an implementation might infer from the use of a cipher
   such as Advanced Encryption Standard (AES) or Twofish that a user
   supports this feature.  It might place in the unhashed portion of
   another user's key signature a Features subpacket.  It might also
   present a user with an opportunity to regenerate their own self-
   signature with a Features subpacket.



Callas, et al               Standards Track                    [Page 49]

RFC 4880                 OpenPGP Message Format            November 2007


   This packet contains data encrypted with a symmetric-key algorithm
   and protected against modification by the SHA-1 hash algorithm.  When
   it has been decrypted, it will typically contain other packets (often
   a Literal Data packet or Compressed Data packet).  The last decrypted
   packet in this packet's payload MUST be a Modification Detection Code
   packet.

   The body of this packet consists of:

     - A one-octet version number.  The only currently defined value is
       1.

     - Encrypted data, the output of the selected symmetric-key cipher
       operating in Cipher Feedback mode with shift amount equal to the
       block size of the cipher (CFB-n where n is the block size).

   The symmetric cipher used MUST be specified in a Public-Key or
   Symmetric-Key Encrypted Session Key packet that precedes the
   Symmetrically Encrypted Data packet.  In either case, the cipher
   algorithm octet is prefixed to the session key before it is
   encrypted.

   The data is encrypted in CFB mode, with a CFB shift size equal to the
   cipher's block size.  The Initial Vector (IV) is specified as all
   zeros.  Instead of using an IV, OpenPGP prefixes an octet string to
   the data before it is encrypted.  The length of the octet string
   equals the block size of the cipher in octets, plus two.  The first
   octets in the group, of length equal to the block size of the cipher,
   are random; the last two octets are each copies of their 2nd
   preceding octet.  For example, with a cipher whose block size is 128
   bits or 16 octets, the prefix data will contain 16 random octets,
   then two more octets, which are copies of the 15th and 16th octets,
   respectively.  Unlike the Symmetrically Encrypted Data Packet, no
   special CFB resynchronization is done after encrypting this prefix
   data.  See "OpenPGP CFB Mode" below for more details.

   The repetition of 16 bits in the random data prefixed to the message
   allows the receiver to immediately check whether the session key is
   incorrect.

   The plaintext of the data to be encrypted is passed through the SHA-1
   hash function, and the result of the hash is appended to the
   plaintext in a Modification Detection Code packet.  The input to the
   hash function includes the prefix data described above; it includes
   all of the plaintext, and then also includes two octets of values
   0xD3, 0x14.  These represent the encoding of a Modification Detection
   Code packet tag and length field of 20 octets.




Callas, et al               Standards Track                    [Page 50]

RFC 4880                 OpenPGP Message Format            November 2007


   The resulting hash value is stored in a Modification Detection Code
   (MDC) packet, which MUST use the two octet encoding just given to
   represent its tag and length field.  The body of the MDC packet is
   the 20-octet output of the SHA-1 hash.

   The Modification Detection Code packet is appended to the plaintext
   and encrypted along with the plaintext using the same CFB context.

   During decryption, the plaintext data should be hashed with SHA-1,
   including the prefix data as well as the packet tag and length field
   of the Modification Detection Code packet.  The body of the MDC
   packet, upon decryption, is compared with the result of the SHA-1
   hash.

   Any failure of the MDC indicates that the message has been modified
   and MUST be treated as a security problem.  Failures include a
   difference in the hash values, but also the absence of an MDC packet,
   or an MDC packet in any position other than the end of the plaintext.
   Any failure SHOULD be reported to the user.

   Note: future designs of new versions of this packet should consider
   rollback attacks since it will be possible for an attacker to change
   the version back to 1.

      NON-NORMATIVE EXPLANATION

      The MDC system, as packets 18 and 19 are called, were created to
      provide an integrity mechanism that is less strong than a
      signature, yet stronger than bare CFB encryption.

      It is a limitation of CFB encryption that damage to the ciphertext
      will corrupt the affected cipher blocks and the block following.
      Additionally, if data is removed from the end of a CFB-encrypted
      block, that removal is undetectable.  (Note also that CBC mode has
      a similar limitation, but data removed from the front of the block
      is undetectable.)

      The obvious way to protect or authenticate an encrypted block is
      to digitally sign it.  However, many people do not wish to
      habitually sign data, for a large number of reasons beyond the
      scope of this document.  Suffice it to say that many people
      consider properties such as deniability to be as valuable as
      integrity.

      OpenPGP addresses this desire to have more security than raw
      encryption and yet preserve deniability with the MDC system.  An
      MDC is intentionally not a MAC.  Its name was not selected by
      accident.  It is analogous to a checksum.



Callas, et al               Standards Track                    [Page 51]

RFC 4880                 OpenPGP Message Format            November 2007


      Despite the fact that it is a relatively modest system, it has
      proved itself in the real world.  It is an effective defense to
      several attacks that have surfaced since it has been created.  It
      has met its modest goals admirably.

      Consequently, because it is a modest security system, it has
      modest requirements on the hash function(s) it employs.  It does
      not rely on a hash function being collision-free, it relies on a
      hash function being one-way.  If a forger, Frank, wishes to send
      Alice a (digitally) unsigned message that says, "I've always
      secretly loved you, signed Bob", it is far easier for him to
      construct a new message than it is to modify anything intercepted
      from Bob.  (Note also that if Bob wishes to communicate secretly
      with Alice, but without authentication or identification and with
      a threat model that includes forgers, he has a problem that
      transcends mere cryptography.)

      Note also that unlike nearly every other OpenPGP subsystem, there
      are no parameters in the MDC system.  It hard-defines SHA-1 as its
      hash function.  This is not an accident.  It is an intentional
      choice to avoid downgrade and cross-grade attacks while making a
      simple, fast system.  (A downgrade attack would be an attack that
      replaced SHA-256 with SHA-1, for example.  A cross-grade attack
      would replace SHA-1 with another 160-bit hash, such as RIPE-
      MD/160, for example.)

      However, given the present state of hash function cryptanalysis
      and cryptography, it may be desirable to upgrade the MDC system to
      a new hash function.  See Section 13.11 in the "IANA
      Considerations" for guidance.

5.14.  Modification Detection Code Packet (Tag 19)

   The Modification Detection Code packet contains a SHA-1 hash of
   plaintext data, which is used to detect message modification.  It is
   only used with a Symmetrically Encrypted Integrity Protected Data
   packet.  The Modification Detection Code packet MUST be the last
   packet in the plaintext data that is encrypted in the Symmetrically
   Encrypted Integrity Protected Data packet, and MUST appear in no
   other place.

   A Modification Detection Code packet MUST have a length of 20 octets.









Callas, et al               Standards Track                    [Page 52]

RFC 4880                 OpenPGP Message Format            November 2007


   The body of this packet consists of:

     - A 20-octet SHA-1 hash of the preceding plaintext data of the
       Symmetrically Encrypted Integrity Protected Data packet,
       including prefix data, the tag octet, and length octet of the
       Modification Detection Code packet.

   Note that the Modification Detection Code packet MUST always use a
   new format encoding of the packet tag, and a one-octet encoding of
   the packet length.  The reason for this is that the hashing rules for
   modification detection include a one-octet tag and one-octet length
   in the data hash.  While this is a bit restrictive, it reduces
   complexity.

6.  Radix-64 Conversions

   As stated in the introduction, OpenPGP's underlying native
   representation for objects is a stream of arbitrary octets, and some
   systems desire these objects to be immune to damage caused by
   character set translation, data conversions, etc.

   In principle, any printable encoding scheme that met the requirements
   of the unsafe channel would suffice, since it would not change the
   underlying binary bit streams of the native OpenPGP data structures.
   The OpenPGP standard specifies one such printable encoding scheme to
   ensure interoperability.

   OpenPGP's Radix-64 encoding is composed of two parts: a base64
   encoding of the binary data and a checksum.  The base64 encoding is
   identical to the MIME base64 content-transfer-encoding [RFC2045].

   The checksum is a 24-bit Cyclic Redundancy Check (CRC) converted to
   four characters of radix-64 encoding by the same MIME base64
   transformation, preceded by an equal sign (=).  The CRC is computed
   by using the generator 0x864CFB and an initialization of 0xB704CE.
   The accumulation is done on the data before it is converted to
   radix-64, rather than on the converted data.  A sample implementation
   of this algorithm is in the next section.

   The checksum with its leading equal sign MAY appear on the first line
   after the base64 encoded data.

   Rationale for CRC-24: The size of 24 bits fits evenly into printable
   base64.  The nonzero initialization can detect more errors than a
   zero initialization.






Callas, et al               Standards Track                    [Page 53]

RFC 4880                 OpenPGP Message Format            November 2007


6.1.  An Implementation of the CRC-24 in "C"

      #define CRC24_INIT 0xB704CEL
      #define CRC24_POLY 0x1864CFBL

      typedef long crc24;
      crc24 crc_octets(unsigned char *octets, size_t len)
      {
          crc24 crc = CRC24_INIT;
          int i;
          while (len--) {
              crc ^= (*octets++) << 16;
              for (i = 0; i < 8; i++) {
                  crc <<= 1;
                  if (crc & 0x1000000)
                      crc ^= CRC24_POLY;
              }
          }
          return crc & 0xFFFFFFL;
      }

6.2.  Forming ASCII Armor

   When OpenPGP encodes data into ASCII Armor, it puts specific headers
   around the Radix-64 encoded data, so OpenPGP can reconstruct the data
   later.  An OpenPGP implementation MAY use ASCII armor to protect raw
   binary data.  OpenPGP informs the user what kind of data is encoded
   in the ASCII armor through the use of the headers.

   Concatenating the following data creates ASCII Armor:

     - An Armor Header Line, appropriate for the type of data

     - Armor Headers

     - A blank (zero-length, or containing only whitespace) line

     - The ASCII-Armored data

     - An Armor Checksum

     - The Armor Tail, which depends on the Armor Header Line

   An Armor Header Line consists of the appropriate header line text
   surrounded by five (5) dashes ('-', 0x2D) on either side of the
   header line text.  The header line text is chosen based upon the type
   of data that is being encoded in Armor, and how it is being encoded.
   Header line texts include the following strings:



Callas, et al               Standards Track                    [Page 54]

RFC 4880                 OpenPGP Message Format            November 2007


   BEGIN PGP MESSAGE
       Used for signed, encrypted, or compressed files.

   BEGIN PGP PUBLIC KEY BLOCK
       Used for armoring public keys.

   BEGIN PGP PRIVATE KEY BLOCK
       Used for armoring private keys.

   BEGIN PGP MESSAGE, PART X/Y
       Used for multi-part messages, where the armor is split amongst Y
       parts, and this is the Xth part out of Y.

   BEGIN PGP MESSAGE, PART X
       Used for multi-part messages, where this is the Xth part of an
       unspecified number of parts.  Requires the MESSAGE-ID Armor
       Header to be used.

   BEGIN PGP SIGNATURE
       Used for detached signatures, OpenPGP/MIME signatures, and
       cleartext signatures.  Note that PGP 2.x uses BEGIN PGP MESSAGE
       for detached signatures.

   Note that all these Armor Header Lines are to consist of a complete
   line.  That is to say, there is always a line ending preceding the
   starting five dashes, and following the ending five dashes.  The
   header lines, therefore, MUST start at the beginning of a line, and
   MUST NOT have text other than whitespace following them on the same
   line.  These line endings are considered a part of the Armor Header
   Line for the purposes of determining the content they delimit.  This
   is particularly important when computing a cleartext signature (see
   below).

   The Armor Headers are pairs of strings that can give the user or the
   receiving OpenPGP implementation some information about how to decode
   or use the message.  The Armor Headers are a part of the armor, not a
   part of the message, and hence are not protected by any signatures
   applied to the message.

   The format of an Armor Header is that of a key-value pair.  A colon
   (':' 0x38) and a single space (0x20) separate the key and value.
   OpenPGP should consider improperly formatted Armor Headers to be
   corruption of the ASCII Armor.  Unknown keys should be reported to
   the user, but OpenPGP should continue to process the message.

   Note that some transport methods are sensitive to line length.  While
   there is a limit of 76 characters for the Radix-64 data (Section
   6.3), there is no limit to the length of Armor Headers.  Care should



Callas, et al               Standards Track                    [Page 55]

RFC 4880                 OpenPGP Message Format            November 2007


   be taken that the Armor Headers are short enough to survive
   transport.  One way to do this is to repeat an Armor Header key
   multiple times with different values for each so that no one line is
   overly long.

   Currently defined Armor Header Keys are as follows:

     - "Version", which states the OpenPGP implementation and version
       used to encode the message.

     - "Comment", a user-defined comment.  OpenPGP defines all text to
       be in UTF-8.  A comment may be any UTF-8 string.  However, the
       whole point of armoring is to provide seven-bit-clean data.
       Consequently, if a comment has characters that are outside the
       US-ASCII range of UTF, they may very well not survive transport.

     - "MessageID", a 32-character string of printable characters.  The
       string must be the same for all parts of a multi-part message
       that uses the "PART X" Armor Header.  MessageID strings should be
       unique enough that the recipient of the mail can associate all
       the parts of a message with each other.  A good checksum or
       cryptographic hash function is sufficient.

       The MessageID SHOULD NOT appear unless it is in a multi-part
       message.  If it appears at all, it MUST be computed from the
       finished (encrypted, signed, etc.) message in a deterministic
       fashion, rather than contain a purely random value.  This is to
       allow the legitimate recipient to determine that the MessageID
       cannot serve as a covert means of leaking cryptographic key
       information.

     - "Hash", a comma-separated list of hash algorithms used in this
       message.  This is used only in cleartext signed messages.

     - "Charset", a description of the character set that the plaintext
       is in.  Please note that OpenPGP defines text to be in UTF-8.  An
       implementation will get best results by translating into and out
       of UTF-8.  However, there are many instances where this is easier
       said than done.  Also, there are communities of users who have no
       need for UTF-8 because they are all happy with a character set
       like ISO Latin-5 or a Japanese character set.  In such instances,
       an implementation MAY override the UTF-8 default by using this
       header key.  An implementation MAY implement this key and any
       translations it cares to; an implementation MAY ignore it and
       assume all text is UTF-8.






Callas, et al               Standards Track                    [Page 56]

RFC 4880                 OpenPGP Message Format            November 2007


       The Armor Tail Line is composed in the same manner as the Armor
       Header Line, except the string "BEGIN" is replaced by the string
       "END".

6.3.  Encoding Binary in Radix-64

   The encoding process represents 24-bit groups of input bits as output
   strings of 4 encoded characters.  Proceeding from left to right, a
   24-bit input group is formed by concatenating three 8-bit input
   groups.  These 24 bits are then treated as four concatenated 6-bit
   groups, each of which is translated into a single digit in the
   Radix-64 alphabet.  When encoding a bit stream with the Radix-64
   encoding, the bit stream must be presumed to be ordered with the most
   significant bit first.  That is, the first bit in the stream will be
   the high-order bit in the first 8-bit octet, and the eighth bit will
   be the low-order bit in the first 8-bit octet, and so on.

         +--first octet--+-second octet--+--third octet--+
         |7 6 5 4 3 2 1 0|7 6 5 4 3 2 1 0|7 6 5 4 3 2 1 0|
         +-----------+---+-------+-------+---+-----------+
         |5 4 3 2 1 0|5 4 3 2 1 0|5 4 3 2 1 0|5 4 3 2 1 0|
         +--1.index--+--2.index--+--3.index--+--4.index--+

   Each 6-bit group is used as an index into an array of 64 printable
   characters from the table below.  The character referenced by the
   index is placed in the output string.

     Value Encoding  Value Encoding  Value Encoding  Value Encoding
         0 A            17 R            34 i            51 z
         1 B            18 S            35 j            52 0
         2 C            19 T            36 k            53 1
         3 D            20 U            37 l            54 2
         4 E            21 V            38 m            55 3
         5 F            22 W            39 n            56 4
         6 G            23 X            40 o            57 5
         7 H            24 Y            41 p            58 6
         8 I            25 Z            42 q            59 7
         9 J            26 a            43 r            60 8
        10 K            27 b            44 s            61 9
        11 L            28 c            45 t            62 +
        12 M            29 d            46 u            63 /
        13 N            30 e            47 v
        14 O            31 f            48 w         (pad) =
        15 P            32 g            49 x
        16 Q            33 h            50 y

   The encoded output stream must be represented in lines of no more
   than 76 characters each.



Callas, et al               Standards Track                    [Page 57]

RFC 4880                 OpenPGP Message Format            November 2007


   Special processing is performed if fewer than 24 bits are available
   at the end of the data being encoded.  There are three possibilities:

   1. The last data group has 24 bits (3 octets).  No special processing
      is needed.

   2. The last data group has 16 bits (2 octets).  The first two 6-bit
      groups are processed as above.  The third (incomplete) data group
      has two zero-value bits added to it, and is processed as above.  A
      pad character (=) is added to the output.

   3. The last data group has 8 bits (1 octet).  The first 6-bit group
      is processed as above.  The second (incomplete) data group has
      four zero-value bits added to it, and is processed as above.  Two
      pad characters (=) are added to the output.

6.4.  Decoding Radix-64

   In Radix-64 data, characters other than those in the table, line
   breaks, and other white space probably indicate a transmission error,
   about which a warning message or even a message rejection might be
   appropriate under some circumstances.  Decoding software must ignore
   all white space.

   Because it is used only for padding at the end of the data, the
   occurrence of any "=" characters may be taken as evidence that the
   end of the data has been reached (without truncation in transit).  No
   such assurance is possible, however, when the number of octets
   transmitted was a multiple of three and no "=" characters are
   present.





















Callas, et al               Standards Track                    [Page 58]

RFC 4880                 OpenPGP Message Format            November 2007


6.5.  Examples of Radix-64

   Input data:  0x14FB9C03D97E
   Hex:     1   4    F   B    9   C     | 0   3    D   9    7   E
   8-bit:   00010100 11111011 10011100  | 00000011 11011001 11111110
   6-bit:   000101 001111 101110 011100 | 000000 111101 100111 111110
   Decimal: 5      15     46     28       0      61     37     62
   Output:  F      P      u      c        A      9      l      +
   Input data:  0x14FB9C03D9
   Hex:     1   4    F   B    9   C     | 0   3    D   9
   8-bit:   00010100 11111011 10011100  | 00000011 11011001
                                                   pad with 00
   6-bit:   000101 001111 101110 011100 | 000000 111101 100100
   Decimal: 5      15     46     28       0      61     36
                                                      pad with =
   Output:  F      P      u      c        A      9      k      =
   Input data:  0x14FB9C03
   Hex:     1   4    F   B    9   C     | 0   3
   8-bit:   00010100 11111011 10011100  | 00000011
                                          pad with 0000
   6-bit:   000101 001111 101110 011100 | 000000 110000
   Decimal: 5      15     46     28       0      48
                                               pad with =      =
   Output:  F      P      u      c        A      w      =      =

6.6.  Example of an ASCII Armored Message

   -----BEGIN PGP MESSAGE-----
   Version: OpenPrivacy 0.99

   yDgBO22WxBHv7O8X7O/jygAEzol56iUKiXmV+XmpCtmpqQUKiQrFqclFqUDBovzS
   vBSFjNSiVHsuAA==
   =njUN
   -----END PGP MESSAGE-----

   Note that this example has extra indenting; an actual armored message
   would have no leading whitespace.

7.  Cleartext Signature Framework

   It is desirable to be able to sign a textual octet stream without
   ASCII armoring the stream itself, so the signed text is still
   readable without special software.  In order to bind a signature to
   such a cleartext, this framework is used.  (Note that this framework
   is not intended to be reversible.  RFC 3156 [RFC3156] defines another
   way to sign cleartext messages for environments that support MIME.)





Callas, et al               Standards Track                    [Page 59]

RFC 4880                 OpenPGP Message Format            November 2007


   The cleartext signed message consists of:

     - The cleartext header '-----BEGIN PGP SIGNED MESSAGE-----' on a
       single line,

     - One or more "Hash" Armor Headers,

     - Exactly one empty line not included into the message digest,

     - The dash-escaped cleartext that is included into the message
       digest,

     - The ASCII armored signature(s) including the '-----BEGIN PGP
       SIGNATURE-----' Armor Header and Armor Tail Lines.

   If the "Hash" Armor Header is given, the specified message digest
   algorithm(s) are used for the signature.  If there are no such
   headers, MD5 is used.  If MD5 is the only hash used, then an
   implementation MAY omit this header for improved V2.x compatibility.
   If more than one message digest is used in the signature, the "Hash"
   armor header contains a comma-delimited list of used message digests.

   Current message digest names are described below with the algorithm
   IDs.

   An implementation SHOULD add a line break after the cleartext, but
   MAY omit it if the cleartext ends with a line break.  This is for
   visual clarity.

7.1.  Dash-Escaped Text

   The cleartext content of the message must also be dash-escaped.

   Dash-escaped cleartext is the ordinary cleartext where every line
   starting with a dash '-' (0x2D) is prefixed by the sequence dash '-'
   (0x2D) and space ' ' (0x20).  This prevents the parser from
   recognizing armor headers of the cleartext itself.  An implementation
   MAY dash-escape any line, SHOULD dash-escape lines commencing "From"
   followed by a space, and MUST dash-escape any line commencing in a
   dash.  The message digest is computed using the cleartext itself, not
   the dash-escaped form.

   As with binary signatures on text documents, a cleartext signature is
   calculated on the text using canonical <CR><LF> line endings.  The
   line ending (i.e., the <CR><LF>) before the '-----BEGIN PGP
   SIGNATURE-----' line that terminates the signed text is not
   considered part of the signed text.




Callas, et al               Standards Track                    [Page 60]

RFC 4880                 OpenPGP Message Format            November 2007


   When reversing dash-escaping, an implementation MUST strip the string
   "- " if it occurs at the beginning of a line, and SHOULD warn on "-"
   and any character other than a space at the beginning of a line.

   Also, any trailing whitespace -- spaces (0x20) and tabs (0x09) -- at
   the end of any line is removed when the cleartext signature is
   generated.

8.  Regular Expressions

   A regular expression is zero or more branches, separated by '|'.  It
   matches anything that matches one of the branches.

   A branch is zero or more pieces, concatenated.  It matches a match
   for the first, followed by a match for the second, etc.

   A piece is an atom possibly followed by '*', '+', or '?'.  An atom
   followed by '*' matches a sequence of 0 or more matches of the atom.
   An atom followed by '+' matches a sequence of 1 or more matches of
   the atom.  An atom followed by '?' matches a match of the atom, or
   the null string.

   An atom is a regular expression in parentheses (matching a match for
   the regular expression), a range (see below), '.' (matching any
   single character), '^' (matching the null string at the beginning of
   the input string), '$' (matching the null string at the end of the
   input string), a '\' followed by a single character (matching that
   character), or a single character with no other significance
   (matching that character).

   A range is a sequence of characters enclosed in '[]'.  It normally
   matches any single character from the sequence.  If the sequence
   begins with '^', it matches any single character not from the rest of
   the sequence.  If two characters in the sequence are separated
   by '-', this is shorthand for the full list of ASCII characters
   between them (e.g., '[0-9]' matches any decimal digit).  To include a
   literal ']' in the sequence, make it the first character (following a
   possible '^').  To include a literal '-', make it the first or last
   character.

9.  Constants

   This section describes the constants used in OpenPGP.

   Note that these tables are not exhaustive lists; an implementation
   MAY implement an algorithm not on these lists, so long as the
   algorithm numbers are chosen from the private or experimental
   algorithm range.



Callas, et al               Standards Track                    [Page 61]

RFC 4880                 OpenPGP Message Format            November 2007


   See the section "Notes on Algorithms" below for more discussion of
   the algorithms.

9.1.  Public-Key Algorithms

      ID           Algorithm
      --           ---------
      1          - RSA (Encrypt or Sign) [HAC]
      2          - RSA Encrypt-Only [HAC]
      3          - RSA Sign-Only [HAC]
      16         - Elgamal (Encrypt-Only) [ELGAMAL] [HAC]
      17         - DSA (Digital Signature Algorithm) [FIPS186] [HAC]
      18         - Reserved for Elliptic Curve
      19         - Reserved for ECDSA
      20         - Reserved (formerly Elgamal Encrypt or Sign)
      21         - Reserved for Diffie-Hellman (X9.42,
                   as defined for IETF-S/MIME)
      100 to 110 - Private/Experimental algorithm

   Implementations MUST implement DSA for signatures, and Elgamal for
   encryption.  Implementations SHOULD implement RSA keys (1).  RSA
   Encrypt-Only (2) and RSA Sign-Only are deprecated and SHOULD NOT be
   generated, but may be interpreted.  See Section 13.5.  See Section
   13.8 for notes on Elliptic Curve (18), ECDSA (19), Elgamal Encrypt or
   Sign (20), and X9.42 (21).  Implementations MAY implement any other
   algorithm.

9.2.  Symmetric-Key Algorithms

       ID           Algorithm
       --           ---------
       0          - Plaintext or unencrypted data
       1          - IDEA [IDEA]
       2          - TripleDES (DES-EDE, [SCHNEIER] [HAC] -
                    168 bit key derived from 192)
       3          - CAST5 (128 bit key, as per [RFC2144])
       4          - Blowfish (128 bit key, 16 rounds) [BLOWFISH]
       5          - Reserved
       6          - Reserved
       7          - AES with 128-bit key [AES]
       8          - AES with 192-bit key
       9          - AES with 256-bit key
       10         - Twofish with 256-bit key [TWOFISH]
       100 to 110 - Private/Experimental algorithm

   Implementations MUST implement TripleDES.  Implementations SHOULD
   implement AES-128 and CAST5.  Implementations that interoperate with




Callas, et al               Standards Track                    [Page 62]

RFC 4880                 OpenPGP Message Format            November 2007


   PGP 2.6 or earlier need to support IDEA, as that is the only
   symmetric cipher those versions use.  Implementations MAY implement
   any other algorithm.

9.3.  Compression Algorithms

       ID           Algorithm
       --           ---------
       0          - Uncompressed
       1          - ZIP [RFC1951]
       2          - ZLIB [RFC1950]
       3          - BZip2 [BZ2]
       100 to 110 - Private/Experimental algorithm

   Implementations MUST implement uncompressed data.  Implementations
   SHOULD implement ZIP.  Implementations MAY implement any other
   algorithm.

9.4.  Hash Algorithms

      ID           Algorithm                             Text Name
      --           ---------                             ---------
      1          - MD5 [HAC]                             "MD5"
      2          - SHA-1 [FIPS180]                       "SHA1"
      3          - RIPE-MD/160 [HAC]                     "RIPEMD160"
      4          - Reserved
      5          - Reserved
      6          - Reserved
      7          - Reserved
      8          - SHA256 [FIPS180]                      "SHA256"
      9          - SHA384 [FIPS180]                      "SHA384"
      10         - SHA512 [FIPS180]                      "SHA512"
      11         - SHA224 [FIPS180]                      "SHA224"
      100 to 110 - Private/Experimental algorithm

   Implementations MUST implement SHA-1.  Implementations MAY implement
   other algorithms.  MD5 is deprecated.

10.  IANA Considerations

   OpenPGP is highly parameterized, and consequently there are a number
   of considerations for allocating parameters for extensions.  This
   section describes how IANA should look at extensions to the protocol
   as described in this document.







Callas, et al               Standards Track                    [Page 63]

RFC 4880                 OpenPGP Message Format            November 2007


10.1.  New String-to-Key Specifier Types

   OpenPGP S2K specifiers contain a mechanism for new algorithms to turn
   a string into a key.  This specification creates a registry of S2K
   specifier types.  The registry includes the S2K type, the name of the
   S2K, and a reference to the defining specification.  The initial
   values for this registry can be found in Section 3.7.1.  Adding a new
   S2K specifier MUST be done through the IETF CONSENSUS method, as
   described in [RFC2434].

10.2.  New Packets

   Major new features of OpenPGP are defined through new packet types.
   This specification creates a registry of packet types.  The registry
   includes the packet type, the name of the packet, and a reference to
   the defining specification.  The initial values for this registry can
   be found in Section 4.3.  Adding a new packet type MUST be done
   through the IETF CONSENSUS method, as described in [RFC2434].

10.2.1.  User Attribute Types

   The User Attribute packet permits an extensible mechanism for other
   types of certificate identification.  This specification creates a
   registry of User Attribute types.  The registry includes the User
   Attribute type, the name of the User Attribute, and a reference to
   the defining specification.  The initial values for this registry can
   be found in Section 5.12.  Adding a new User Attribute type MUST be
   done through the IETF CONSENSUS method, as described in [RFC2434].

10.2.1.1.  Image Format Subpacket Types

   Within User Attribute packets, there is an extensible mechanism for
   other types of image-based user attributes.  This specification
   creates a registry of Image Attribute subpacket types.  The registry
   includes the Image Attribute subpacket type, the name of the Image
   Attribute subpacket, and a reference to the defining specification.
   The initial values for this registry can be found in Section 5.12.1.
   Adding a new Image Attribute subpacket type MUST be done through the
   IETF CONSENSUS method, as described in [RFC2434].

10.2.2.  New Signature Subpackets

   OpenPGP signatures contain a mechanism for signed (or unsigned) data
   to be added to them for a variety of purposes in the Signature
   subpackets as discussed in Section 5.2.3.1.  This specification
   creates a registry of Signature subpacket types.  The registry
   includes the Signature subpacket type, the name of the subpacket, and
   a reference to the defining specification.  The initial values for



Callas, et al               Standards Track                    [Page 64]

RFC 4880                 OpenPGP Message Format            November 2007


   this registry can be found in Section 5.2.3.1.  Adding a new
   Signature subpacket MUST be done through the IETF CONSENSUS method,
   as described in [RFC2434].

10.2.2.1.  Signature Notation Data Subpackets

   OpenPGP signatures further contain a mechanism for extensions in
   signatures.  These are the Notation Data subpackets, which contain a
   key/value pair.  Notations contain a user space that is completely
   unmanaged and an IETF space.

   This specification creates a registry of Signature Notation Data
   types.  The registry includes the Signature Notation Data type, the
   name of the Signature Notation Data, its allowed values, and a
   reference to the defining specification.  The initial values for this
   registry can be found in Section 5.2.3.16.  Adding a new Signature
   Notation Data subpacket MUST be done through the EXPERT REVIEW
   method, as described in [RFC2434].

10.2.2.2.  Key Server Preference Extensions

   OpenPGP signatures contain a mechanism for preferences to be
   specified about key servers.  This specification creates a registry
   of key server preferences.  The registry includes the key server
   preference, the name of the preference, and a reference to the
   defining specification.  The initial values for this registry can be
   found in Section 5.2.3.17.  Adding a new key server preference MUST
   be done through the IETF CONSENSUS method, as described in [RFC2434].

10.2.2.3.  Key Flags Extensions

   OpenPGP signatures contain a mechanism for flags to be specified
   about key usage.  This specification creates a registry of key usage
   flags.  The registry includes the key flags value, the name of the
   flag, and a reference to the defining specification.  The initial
   values for this registry can be found in Section 5.2.3.21.  Adding a
   new key usage flag MUST be done through the IETF CONSENSUS method, as
   described in [RFC2434].

10.2.2.4.  Reason for Revocation Extensions

   OpenPGP signatures contain a mechanism for flags to be specified
   about why a key was revoked.  This specification creates a registry
   of "Reason for Revocation" flags.  The registry includes the "Reason
   for Revocation" flags value, the name of the flag, and a reference to
   the defining specification.  The initial values for this registry can
   be found in Section 5.2.3.23.  Adding a new feature flag MUST be done
   through the IETF CONSENSUS method, as described in [RFC2434].



Callas, et al               Standards Track                    [Page 65]

RFC 4880                 OpenPGP Message Format            November 2007


10.2.2.5.  Implementation Features

   OpenPGP signatures contain a mechanism for flags to be specified
   stating which optional features an implementation supports.  This
   specification creates a registry of feature-implementation flags.
   The registry includes the feature-implementation flags value, the
   name of the flag, and a reference to the defining specification.  The
   initial values for this registry can be found in Section 5.2.3.24.
   Adding a new feature-implementation flag MUST be done through the
   IETF CONSENSUS method, as described in [RFC2434].

   Also see Section 13.12 for more information about when feature flags
   are needed.

10.2.3.  New Packet Versions

   The core OpenPGP packets all have version numbers, and can be revised
   by introducing a new version of an existing packet.  This
   specification creates a registry of packet types.  The registry
   includes the packet type, the number of the version, and a reference
   to the defining specification.  The initial values for this registry
   can be found in Section 5.  Adding a new packet version MUST be done
   through the IETF CONSENSUS method, as described in [RFC2434].

10.3.  New Algorithms

   Section 9 lists the core algorithms that OpenPGP uses.  Adding in a
   new algorithm is usually simple.  For example, adding in a new
   symmetric cipher usually would not need anything more than allocating
   a constant for that cipher.  If that cipher had other than a 64-bit
   or 128-bit block size, there might need to be additional
   documentation describing how OpenPGP-CFB mode would be adjusted.
   Similarly, when DSA was expanded from a maximum of 1024-bit public
   keys to 3072-bit public keys, the revision of FIPS 186 contained
   enough information itself to allow implementation.  Changes to this
   document were made mainly for emphasis.

10.3.1.  Public-Key Algorithms

   OpenPGP specifies a number of public-key algorithms.  This
   specification creates a registry of public-key algorithm identifiers.
   The registry includes the algorithm name, its key sizes and
   parameters, and a reference to the defining specification.  The
   initial values for this registry can be found in Section 9.  Adding a
   new public-key algorithm MUST be done through the IETF CONSENSUS
   method, as described in [RFC2434].





Callas, et al               Standards Track                    [Page 66]

RFC 4880                 OpenPGP Message Format            November 2007


10.3.2.  Symmetric-Key Algorithms

   OpenPGP specifies a number of symmetric-key algorithms.  This
   specification creates a registry of symmetric-key algorithm
   identifiers.  The registry includes the algorithm name, its key sizes
   and block size, and a reference to the defining specification.  The
   initial values for this registry can be found in Section 9.  Adding a
   new symmetric-key algorithm MUST be done through the IETF CONSENSUS
   method, as described in [RFC2434].

10.3.3.  Hash Algorithms

   OpenPGP specifies a number of hash algorithms.  This specification
   creates a registry of hash algorithm identifiers.  The registry
   includes the algorithm name, a text representation of that name, its
   block size, an OID hash prefix, and a reference to the defining
   specification.  The initial values for this registry can be found in
   Section 9 for the algorithm identifiers and text names, and Section
   5.2.2 for the OIDs and expanded signature prefixes.  Adding a new
   hash algorithm MUST be done through the IETF CONSENSUS method, as
   described in [RFC2434].

10.3.4.  Compression Algorithms

   OpenPGP specifies a number of compression algorithms.  This
   specification creates a registry of compression algorithm
   identifiers.  The registry includes the algorithm name and a
   reference to the defining specification.  The initial values for this
   registry can be found in Section 9.3.  Adding a new compression key
   algorithm MUST be done through the IETF CONSENSUS method, as
   described in [RFC2434].

11.  Packet Composition

   OpenPGP packets are assembled into sequences in order to create
   messages and to transfer keys.  Not all possible packet sequences are
   meaningful and correct.  This section describes the rules for how
   packets should be placed into sequences.

11.1.  Transferable Public Keys

   OpenPGP users may transfer public keys.  The essential elements of a
   transferable public key are as follows:

     - One Public-Key packet

     - Zero or more revocation signatures




Callas, et al               Standards Track                    [Page 67]

RFC 4880                 OpenPGP Message Format            November 2007


     - One or more User ID packets

     - After each User ID packet, zero or more Signature packets
       (certifications)

     - Zero or more User Attribute packets

     - After each User Attribute packet, zero or more Signature packets
       (certifications)

     - Zero or more Subkey packets

     - After each Subkey packet, one Signature packet, plus optionally a
       revocation

   The Public-Key packet occurs first.  Each of the following User ID
   packets provides the identity of the owner of this public key.  If
   there are multiple User ID packets, this corresponds to multiple
   means of identifying the same unique individual user; for example, a
   user may have more than one email address, and construct a User ID
   for each one.

   Immediately following each User ID packet, there are zero or more
   Signature packets.  Each Signature packet is calculated on the
   immediately preceding User ID packet and the initial Public-Key
   packet.  The signature serves to certify the corresponding public key
   and User ID.  In effect, the signer is testifying to his or her
   belief that this public key belongs to the user identified by this
   User ID.

   Within the same section as the User ID packets, there are zero or
   more User Attribute packets.  Like the User ID packets, a User
   Attribute packet is followed by zero or more Signature packets
   calculated on the immediately preceding User Attribute packet and the
   initial Public-Key packet.

   User Attribute packets and User ID packets may be freely intermixed
   in this section, so long as the signatures that follow them are
   maintained on the proper User Attribute or User ID packet.

   After the User ID packet or Attribute packet, there may be zero or
   more Subkey packets.  In general, subkeys are provided in cases where
   the top-level public key is a signature-only key.  However, any V4
   key may have subkeys, and the subkeys may be encryption-only keys,
   signature-only keys, or general-purpose keys.  V3 keys MUST NOT have
   subkeys.





Callas, et al               Standards Track                    [Page 68]

RFC 4880                 OpenPGP Message Format            November 2007


   Each Subkey packet MUST be followed by one Signature packet, which
   should be a subkey binding signature issued by the top-level key.
   For subkeys that can issue signatures, the subkey binding signature
   MUST contain an Embedded Signature subpacket with a primary key
   binding signature (0x19) issued by the subkey on the top-level key.

   Subkey and Key packets may each be followed by a revocation Signature
   packet to indicate that the key is revoked.  Revocation signatures
   are only accepted if they are issued by the key itself, or by a key
   that is authorized to issue revocations via a Revocation Key
   subpacket in a self-signature by the top-level key.

   Transferable public-key packet sequences may be concatenated to allow
   transferring multiple public keys in one operation.

11.2.  Transferable Secret Keys

   OpenPGP users may transfer secret keys.  The format of a transferable
   secret key is the same as a transferable public key except that
   secret-key and secret-subkey packets are used instead of the public
   key and public-subkey packets.  Implementations SHOULD include self-
   signatures on any user IDs and subkeys, as this allows for a complete
   public key to be automatically extracted from the transferable secret
   key.  Implementations MAY choose to omit the self-signatures,
   especially if a transferable public key accompanies the transferable
   secret key.

11.3.  OpenPGP Messages

   An OpenPGP message is a packet or sequence of packets that
   corresponds to the following grammatical rules (comma represents
   sequential composition, and vertical bar separates alternatives):

   OpenPGP Message :- Encrypted Message | Signed Message |
                      Compressed Message | Literal Message.

   Compressed Message :- Compressed Data Packet.

   Literal Message :- Literal Data Packet.

   ESK :- Public-Key Encrypted Session Key Packet |
          Symmetric-Key Encrypted Session Key Packet.

   ESK Sequence :- ESK | ESK Sequence, ESK.

   Encrypted Data :- Symmetrically Encrypted Data Packet |
         Symmetrically Encrypted Integrity Protected Data Packet




Callas, et al               Standards Track                    [Page 69]

RFC 4880                 OpenPGP Message Format            November 2007


   Encrypted Message :- Encrypted Data | ESK Sequence, Encrypted Data.

   One-Pass Signed Message :- One-Pass Signature Packet,
               OpenPGP Message, Corresponding Signature Packet.

   Signed Message :- Signature Packet, OpenPGP Message |
               One-Pass Signed Message.

   In addition, decrypting a Symmetrically Encrypted Data packet or a
   Symmetrically Encrypted Integrity Protected Data packet as well as
   decompressing a Compressed Data packet must yield a valid OpenPGP
   Message.

11.4.  Detached Signatures

   Some OpenPGP applications use so-called "detached signatures".  For
   example, a program bundle may contain a file, and with it a second
   file that is a detached signature of the first file.  These detached
   signatures are simply a Signature packet stored separately from the
   data for which they are a signature.

12.  Enhanced Key Formats

12.1.  Key Structures

   The format of an OpenPGP V3 key is as follows.  Entries in square
   brackets are optional and ellipses indicate repetition.

           RSA Public Key
              [Revocation Self Signature]
               User ID [Signature ...]
              [User ID [Signature ...] ...]

   Each signature certifies the RSA public key and the preceding User
   ID.  The RSA public key can have many User IDs and each User ID can
   have many signatures.  V3 keys are deprecated.  Implementations MUST
   NOT generate new V3 keys, but MAY continue to use existing ones.

   The format of an OpenPGP V4 key that uses multiple public keys is
   similar except that the other keys are added to the end as "subkeys"
   of the primary key.










Callas, et al               Standards Track                    [Page 70]

RFC 4880                 OpenPGP Message Format            November 2007


           Primary-Key
              [Revocation Self Signature]
              [Direct Key Signature...]
               User ID [Signature ...]
              [User ID [Signature ...] ...]
              [User Attribute [Signature ...] ...]
              [[Subkey [Binding-Signature-Revocation]
                      Primary-Key-Binding-Signature] ...]

   A subkey always has a single signature after it that is issued using
   the primary key to tie the two keys together.  This binding signature
   may be in either V3 or V4 format, but SHOULD be V4.  Subkeys that can
   issue signatures MUST have a V4 binding signature due to the REQUIRED
   embedded primary key binding signature.

   In the above diagram, if the binding signature of a subkey has been
   revoked, the revoked key may be removed, leaving only one key.

   In a V4 key, the primary key MUST be a key capable of certification.
   The subkeys may be keys of any other type.  There may be other
   constructions of V4 keys, too.  For example, there may be a single-
   key RSA key in V4 format, a DSA primary key with an RSA encryption
   key, or RSA primary key with an Elgamal subkey, etc.

   It is also possible to have a signature-only subkey.  This permits a
   primary key that collects certifications (key signatures), but is
   used only for certifying subkeys that are used for encryption and
   signatures.

12.2.  Key IDs and Fingerprints

   For a V3 key, the eight-octet Key ID consists of the low 64 bits of
   the public modulus of the RSA key.

   The fingerprint of a V3 key is formed by hashing the body (but not
   the two-octet length) of the MPIs that form the key material (public
   modulus n, followed by exponent e) with MD5.  Note that both V3 keys
   and MD5 are deprecated.

   A V4 fingerprint is the 160-bit SHA-1 hash of the octet 0x99,
   followed by the two-octet packet length, followed by the entire
   Public-Key packet starting with the version field.  The Key ID is the
   low-order 64 bits of the fingerprint.  Here are the fields of the
   hash material, with the example of a DSA key:

   a.1) 0x99 (1 octet)

   a.2) high-order length octet of (b)-(e) (1 octet)



Callas, et al               Standards Track                    [Page 71]

RFC 4880                 OpenPGP Message Format            November 2007


   a.3) low-order length octet of (b)-(e) (1 octet)

     b) version number = 4 (1 octet);

     c) timestamp of key creation (4 octets);

     d) algorithm (1 octet): 17 = DSA (example);

     e) Algorithm-specific fields.

   Algorithm-Specific Fields for DSA keys (example):

   e.1) MPI of DSA prime p;

   e.2) MPI of DSA group order q (q is a prime divisor of p-1);

   e.3) MPI of DSA group generator g;

   e.4) MPI of DSA public-key value y (= g**x mod p where x is secret).

   Note that it is possible for there to be collisions of Key IDs -- two
   different keys with the same Key ID.  Note that there is a much
   smaller, but still non-zero, probability that two different keys have
   the same fingerprint.

   Also note that if V3 and V4 format keys share the same RSA key
   material, they will have different Key IDs as well as different
   fingerprints.

   Finally, the Key ID and fingerprint of a subkey are calculated in the
   same way as for a primary key, including the 0x99 as the first octet
   (even though this is not a valid packet ID for a public subkey).

13.  Notes on Algorithms

13.1.  PKCS#1 Encoding in OpenPGP

   This standard makes use of the PKCS#1 functions EME-PKCS1-v1_5 and
   EMSA-PKCS1-v1_5.  However, the calling conventions of these functions
   has changed in the past.  To avoid potential confusion and
   interoperability problems, we are including local copies in this
   document, adapted from those in PKCS#1 v2.1 [RFC3447].  RFC 3447
   should be treated as the ultimate authority on PKCS#1 for OpenPGP.
   Nonetheless, we believe that there is value in having a self-
   contained document that avoids problems in the future with needed
   changes in the conventions.





Callas, et al               Standards Track                    [Page 72]

RFC 4880                 OpenPGP Message Format            November 2007


13.1.1.  EME-PKCS1-v1_5-ENCODE

   Input:

   k  = the length in octets of the key modulus

   M  = message to be encoded, an octet string of length mLen, where
        mLen <= k - 11

   Output:

   EM = encoded message, an octet string of length k

   Error:   "message too long"

     1. Length checking: If mLen > k - 11, output "message too long" and
        stop.

     2. Generate an octet string PS of length k - mLen - 3 consisting of
        pseudo-randomly generated nonzero octets.  The length of PS will
        be at least eight octets.

     3. Concatenate PS, the message M, and other padding to form an
        encoded message EM of length k octets as

        EM = 0x00 || 0x02 || PS || 0x00 || M.

     4. Output EM.

13.1.2.  EME-PKCS1-v1_5-DECODE

   Input:

   EM = encoded message, an octet string

   Output:

   M  = message, an octet string

   Error:   "decryption error"

   To decode an EME-PKCS1_v1_5 message, separate the encoded message EM
   into an octet string PS consisting of nonzero octets and a message M
   as follows

     EM = 0x00 || 0x02 || PS || 0x00 || M.





Callas, et al               Standards Track                    [Page 73]

RFC 4880                 OpenPGP Message Format            November 2007


   If the first octet of EM does not have hexadecimal value 0x00, if the
   second octet of EM does not have hexadecimal value 0x02, if there is
   no octet with hexadecimal value 0x00 to separate PS from M, or if the
   length of PS is less than 8 octets, output "decryption error" and
   stop.  See also the security note in Section 14 regarding differences
   in reporting between a decryption error and a padding error.

13.1.3.  EMSA-PKCS1-v1_5

   This encoding method is deterministic and only has an encoding
   operation.

   Option:

   Hash - a hash function in which hLen denotes the length in octets of
         the hash function output

   Input:

   M  = message to be encoded

   mL = intended length in octets of the encoded message, at least tLen
        + 11, where tLen is the octet length of the DER encoding T of a
        certain value computed during the encoding operation

   Output:

   EM = encoded message, an octet string of length emLen

   Errors: "message too long"; "intended encoded message length too
   short"

   Steps:

     1. Apply the hash function to the message M to produce a hash value
        H:

        H = Hash(M).

        If the hash function outputs "message too long," output "message
        too long" and stop.

     2. Using the list in Section 5.2.2, produce an ASN.1 DER value for
        the hash function used.  Let T be the full hash prefix from
        Section 5.2.2, and let tLen be the length in octets of T.

     3. If emLen < tLen + 11, output "intended encoded message length
        too short" and stop.



Callas, et al               Standards Track                    [Page 74]

RFC 4880                 OpenPGP Message Format            November 2007


     4. Generate an octet string PS consisting of emLen - tLen - 3
        octets with hexadecimal value 0xFF.  The length of PS will be at
        least 8 octets.

     5. Concatenate PS, the hash prefix T, and other padding to form the
        encoded message EM as

        EM = 0x00 || 0x01 || PS || 0x00 || T.

     6. Output EM.

13.2.  Symmetric Algorithm Preferences

   The symmetric algorithm preference is an ordered list of algorithms
   that the keyholder accepts.  Since it is found on a self-signature,
   it is possible that a keyholder may have multiple, different
   preferences.  For example, Alice may have TripleDES only specified
   for "alice@work.com" but CAST5, Blowfish, and TripleDES specified for
   "alice@home.org".  Note that it is also possible for preferences to
   be in a subkey's binding signature.

   Since TripleDES is the MUST-implement algorithm, if it is not
   explicitly in the list, it is tacitly at the end.  However, it is
   good form to place it there explicitly.  Note also that if an
   implementation does not implement the preference, then it is
   implicitly a TripleDES-only implementation.

   An implementation MUST NOT use a symmetric algorithm that is not in
   the recipient's preference list.  When encrypting to more than one
   recipient, the implementation finds a suitable algorithm by taking
   the intersection of the preferences of the recipients.  Note that the
   MUST-implement algorithm, TripleDES, ensures that the intersection is
   not null.  The implementation may use any mechanism to pick an
   algorithm in the intersection.

   If an implementation can decrypt a message that a keyholder doesn't
   have in their preferences, the implementation SHOULD decrypt the
   message anyway, but MUST warn the keyholder that the protocol has
   been violated.  For example, suppose that Alice, above, has software
   that implements all algorithms in this specification.  Nonetheless,
   she prefers subsets for work or home.  If she is sent a message
   encrypted with IDEA, which is not in her preferences, the software
   warns her that someone sent her an IDEA-encrypted message, but it
   would ideally decrypt it anyway.







Callas, et al               Standards Track                    [Page 75]

RFC 4880                 OpenPGP Message Format            November 2007


13.3.  Other Algorithm Preferences

   Other algorithm preferences work similarly to the symmetric algorithm
   preference, in that they specify which algorithms the keyholder
   accepts.  There are two interesting cases that other comments need to
   be made about, though, the compression preferences and the hash
   preferences.

13.3.1.  Compression Preferences

   Compression has been an integral part of PGP since its first days.
   OpenPGP and all previous versions of PGP have offered compression.
   In this specification, the default is for messages to be compressed,
   although an implementation is not required to do so.  Consequently,
   the compression preference gives a way for a keyholder to request
   that messages not be compressed, presumably because they are using a
   minimal implementation that does not include compression.
   Additionally, this gives a keyholder a way to state that it can
   support alternate algorithms.

   Like the algorithm preferences, an implementation MUST NOT use an
   algorithm that is not in the preference vector.  If the preferences
   are not present, then they are assumed to be [ZIP(1),
   Uncompressed(0)].

   Additionally, an implementation MUST implement this preference to the
   degree of recognizing when to send an uncompressed message.  A robust
   implementation would satisfy this requirement by looking at the
   recipient's preference and acting accordingly.  A minimal
   implementation can satisfy this requirement by never generating a
   compressed message, since all implementations can handle messages
   that have not been compressed.

13.3.2.  Hash Algorithm Preferences

   Typically, the choice of a hash algorithm is something the signer
   does, rather than the verifier, because a signer rarely knows who is
   going to be verifying the signature.  This preference, though, allows
   a protocol based upon digital signatures ease in negotiation.

   Thus, if Alice is authenticating herself to Bob with a signature, it
   makes sense for her to use a hash algorithm that Bob's software uses.
   This preference allows Bob to state in his key which algorithms Alice
   may use.

   Since SHA1 is the MUST-implement hash algorithm, if it is not
   explicitly in the list, it is tacitly at the end.  However, it is
   good form to place it there explicitly.



Callas, et al               Standards Track                    [Page 76]

RFC 4880                 OpenPGP Message Format            November 2007


13.4.  Plaintext

   Algorithm 0, "plaintext", may only be used to denote secret keys that
   are stored in the clear.  Implementations MUST NOT use plaintext in
   Symmetrically Encrypted Data packets; they must use Literal Data
   packets to encode unencrypted or literal data.

13.5.  RSA

   There are algorithm types for RSA Sign-Only, and RSA Encrypt-Only
   keys.  These types are deprecated.  The "key flags" subpacket in a
   signature is a much better way to express the same idea, and
   generalizes it to all algorithms.  An implementation SHOULD NOT
   create such a key, but MAY interpret it.

   An implementation SHOULD NOT implement RSA keys of size less than
   1024 bits.

13.6.  DSA

   An implementation SHOULD NOT implement DSA keys of size less than
   1024 bits.  It MUST NOT implement a DSA key with a q size of less
   than 160 bits.  DSA keys MUST also be a multiple of 64 bits, and the
   q size MUST be a multiple of 8 bits.  The Digital Signature Standard
   (DSS) [FIPS186] specifies that DSA be used in one of the following
   ways:

     * 1024-bit key, 160-bit q, SHA-1, SHA-224, SHA-256, SHA-384, or
       SHA-512 hash

     * 2048-bit key, 224-bit q, SHA-224, SHA-256, SHA-384, or SHA-512
       hash

     * 2048-bit key, 256-bit q, SHA-256, SHA-384, or SHA-512 hash

     * 3072-bit key, 256-bit q, SHA-256, SHA-384, or SHA-512 hash

   The above key and q size pairs were chosen to best balance the
   strength of the key with the strength of the hash.  Implementations
   SHOULD use one of the above key and q size pairs when generating DSA
   keys.  If DSS compliance is desired, one of the specified SHA hashes
   must be used as well.  [FIPS186] is the ultimate authority on DSS,
   and should be consulted for all questions of DSS compliance.

   Note that earlier versions of this standard only allowed a 160-bit q
   with no truncation allowed, so earlier implementations may not be
   able to handle signatures with a different q size or a truncated
   hash.



Callas, et al               Standards Track                    [Page 77]

RFC 4880                 OpenPGP Message Format            November 2007


13.7.  Elgamal

   An implementation SHOULD NOT implement Elgamal keys of size less than
   1024 bits.

13.8.  Reserved Algorithm Numbers

   A number of algorithm IDs have been reserved for algorithms that
   would be useful to use in an OpenPGP implementation, yet there are
   issues that prevent an implementer from actually implementing the
   algorithm.  These are marked in Section 9.1, "Public-Key Algorithms",
   as "reserved for".

   The reserved public-key algorithms, Elliptic Curve (18), ECDSA (19),
   and X9.42 (21), do not have the necessary parameters, parameter
   order, or semantics defined.

   Previous versions of OpenPGP permitted Elgamal [ELGAMAL] signatures
   with a public-key identifier of 20.  These are no longer permitted.
   An implementation MUST NOT generate such keys.  An implementation
   MUST NOT generate Elgamal signatures.  See [BLEICHENBACHER].

13.9.  OpenPGP CFB Mode

   OpenPGP does symmetric encryption using a variant of Cipher Feedback
   mode (CFB mode).  This section describes the procedure it uses in
   detail.  This mode is what is used for Symmetrically Encrypted Data
   Packets; the mechanism used for encrypting secret-key material is
   similar, and is described in the sections above.

   In the description below, the value BS is the block size in octets of
   the cipher.  Most ciphers have a block size of 8 octets.  The AES and
   Twofish have a block size of 16 octets.  Also note that the
   description below assumes that the IV and CFB arrays start with an
   index of 1 (unlike the C language, which assumes arrays start with a
   zero index).

   OpenPGP CFB mode uses an initialization vector (IV) of all zeros, and
   prefixes the plaintext with BS+2 octets of random data, such that
   octets BS+1 and BS+2 match octets BS-1 and BS.  It does a CFB
   resynchronization after encrypting those BS+2 octets.

   Thus, for an algorithm that has a block size of 8 octets (64 bits),
   the IV is 10 octets long and octets 7 and 8 of the IV are the same as
   octets 9 and 10.  For an algorithm with a block size of 16 octets
   (128 bits), the IV is 18 octets long, and octets 17 and 18 replicate
   octets 15 and 16.  Those extra two octets are an easy check for a
   correct key.



Callas, et al               Standards Track                    [Page 78]

RFC 4880                 OpenPGP Message Format            November 2007


   Step by step, here is the procedure:

   1.  The feedback register (FR) is set to the IV, which is all zeros.

   2.  FR is encrypted to produce FRE (FR Encrypted).  This is the
       encryption of an all-zero value.

   3.  FRE is xored with the first BS octets of random data prefixed to
       the plaintext to produce C[1] through C[BS], the first BS octets
       of ciphertext.

   4.  FR is loaded with C[1] through C[BS].

   5.  FR is encrypted to produce FRE, the encryption of the first BS
       octets of ciphertext.

   6.  The left two octets of FRE get xored with the next two octets of
       data that were prefixed to the plaintext.  This produces C[BS+1]
       and C[BS+2], the next two octets of ciphertext.

   7.  (The resynchronization step) FR is loaded with C[3] through
       C[BS+2].

   8.  FR is encrypted to produce FRE.

   9.  FRE is xored with the first BS octets of the given plaintext, now
       that we have finished encrypting the BS+2 octets of prefixed
       data.  This produces C[BS+3] through C[BS+(BS+2)], the next BS
       octets of ciphertext.

   10. FR is loaded with C[BS+3] to C[BS + (BS+2)] (which is C11-C18 for
       an 8-octet block).

       11. FR is encrypted to produce FRE.

       12. FRE is xored with the next BS octets of plaintext, to produce
       the next BS octets of ciphertext.  These are loaded into FR, and
       the process is repeated until the plaintext is used up.

13.10.  Private or Experimental Parameters

   S2K specifiers, Signature subpacket types, user attribute types,
   image format types, and algorithms described in Section 9 all reserve
   the range 100 to 110 for private and experimental use.  Packet types
   reserve the range 60 to 63 for private and experimental use.  These
   are intentionally managed with the PRIVATE USE method, as described
   in [RFC2434].




Callas, et al               Standards Track                    [Page 79]

RFC 4880                 OpenPGP Message Format            November 2007


   However, implementations need to be careful with these and promote
   them to full IANA-managed parameters when they grow beyond the
   original, limited system.

13.11.  Extension of the MDC System

   As described in the non-normative explanation in Section 5.13, the
   MDC system is uniquely unparameterized in OpenPGP.  This was an
   intentional decision to avoid cross-grade attacks.  If the MDC system
   is extended to a stronger hash function, care must be taken to avoid
   downgrade and cross-grade attacks.

   One simple way to do this is to create new packets for a new MDC.
   For example, instead of the MDC system using packets 18 and 19, a new
   MDC could use 20 and 21.  This has obvious drawbacks (it uses two
   packet numbers for each new hash function in a space that is limited
   to a maximum of 60).

   Another simple way to extend the MDC system is to create new versions
   of packet 18, and reflect this in packet 19.  For example, suppose
   that V2 of packet 18 implicitly used SHA-256.  This would require
   packet 19 to have a length of 32 octets.  The change in the version
   in packet 18 and the size of packet 19 prevent a downgrade attack.

   There are two drawbacks to this latter approach.  The first is that
   using the version number of a packet to carry algorithm information
   is not tidy from a protocol-design standpoint.  It is possible that
   there might be several versions of the MDC system in common use, but
   this untidiness would reflect untidiness in cryptographic consensus
   about hash function security.  The second is that different versions
   of packet 19 would have to have unique sizes.  If there were two
   versions each with 256-bit hashes, they could not both have 32-octet
   packet 19s without admitting the chance of a cross-grade attack.

   Yet another, complex approach to extend the MDC system would be a
   hybrid of the two above -- create a new pair of MDC packets that are
   fully parameterized, and yet protected from downgrade and cross-
   grade.

   Any change to the MDC system MUST be done through the IETF CONSENSUS
   method, as described in [RFC2434].

13.12.  Meta-Considerations for Expansion

   If OpenPGP is extended in a way that is not backwards-compatible,
   meaning that old implementations will not gracefully handle their





Callas, et al               Standards Track                    [Page 80]

RFC 4880                 OpenPGP Message Format            November 2007


   absence of a new feature, the extension proposal can be declared in
   the key holder's self-signature as part of the Features signature
   subpacket.

   We cannot state definitively what extensions will not be upwards-
   compatible, but typically new algorithms are upwards-compatible,
   whereas new packets are not.

   If an extension proposal does not update the Features system, it
   SHOULD include an explanation of why this is unnecessary.  If the
   proposal contains neither an extension to the Features system nor an
   explanation of why such an extension is unnecessary, the proposal
   SHOULD be rejected.

14.  Security Considerations

   * As with any technology involving cryptography, you should check the
     current literature to determine if any algorithms used here have
     been found to be vulnerable to attack.

   * This specification uses Public-Key Cryptography technologies.  It
     is assumed that the private key portion of a public-private key
     pair is controlled and secured by the proper party or parties.

   * Certain operations in this specification involve the use of random
     numbers.  An appropriate entropy source should be used to generate
     these numbers (see [RFC4086]).

   * The MD5 hash algorithm has been found to have weaknesses, with
     collisions found in a number of cases.  MD5 is deprecated for use
     in OpenPGP.  Implementations MUST NOT generate new signatures using
     MD5 as a hash function.  They MAY continue to consider old
     signatures that used MD5 as valid.

   * SHA-224 and SHA-384 require the same work as SHA-256 and SHA-512,
     respectively.  In general, there are few reasons to use them
     outside of DSS compatibility.  You need a situation where one needs
     more security than smaller hashes, but does not want to have the
     full 256-bit or 512-bit data length.

   * Many security protocol designers think that it is a bad idea to use
     a single key for both privacy (encryption) and integrity
     (signatures).  In fact, this was one of the motivating forces
     behind the V4 key format with separate signature and encryption
     keys.  If you as an implementer promote dual-use keys, you should
     at least be aware of this controversy.





Callas, et al               Standards Track                    [Page 81]

RFC 4880                 OpenPGP Message Format            November 2007


   * The DSA algorithm will work with any hash, but is sensitive to the
     quality of the hash algorithm.  Verifiers should be aware that even
     if the signer used a strong hash, an attacker could have modified
     the signature to use a weak one.  Only signatures using acceptably
     strong hash algorithms should be accepted as valid.

   * As OpenPGP combines many different asymmetric, symmetric, and hash
     algorithms, each with different measures of strength, care should
     be taken that the weakest element of an OpenPGP message is still
     sufficiently strong for the purpose at hand.  While consensus about
     the strength of a given algorithm may evolve, NIST Special
     Publication 800-57 [SP800-57] recommends the following list of
     equivalent strengths:

           Asymmetric  |  Hash  |  Symmetric
            key size   |  size  |   key size
           ------------+--------+-----------
              1024        160         80
              2048        224        112
              3072        256        128
              7680        384        192
             15360        512        256

   * There is a somewhat-related potential security problem in
     signatures.  If an attacker can find a message that hashes to the
     same hash with a different algorithm, a bogus signature structure
     can be constructed that evaluates correctly.

     For example, suppose Alice DSA signs message M using hash algorithm
     H.  Suppose that Mallet finds a message M' that has the same hash
     value as M with H'.  Mallet can then construct a signature block
     that verifies as Alice's signature of M' with H'.  However, this
     would also constitute a weakness in either H or H' or both.  Should
     this ever occur, a revision will have to be made to this document
     to revise the allowed hash algorithms.

   * If you are building an authentication system, the recipient may
     specify a preferred signing algorithm.  However, the signer would
     be foolish to use a weak algorithm simply because the recipient
     requests it.

   * Some of the encryption algorithms mentioned in this document have
     been analyzed less than others.  For example, although CAST5 is
     presently considered strong, it has been analyzed less than
     TripleDES.  Other algorithms may have other controversies
     surrounding them.





Callas, et al               Standards Track                    [Page 82]

RFC 4880                 OpenPGP Message Format            November 2007


   * In late summer 2002, Jallad, Katz, and Schneier published an
     interesting attack on the OpenPGP protocol and some of its
     implementations [JKS02].  In this attack, the attacker modifies a
     message and sends it to a user who then returns the erroneously
     decrypted message to the attacker.  The attacker is thus using the
     user as a random oracle, and can often decrypt the message.

     Compressing data can ameliorate this attack.  The incorrectly
     decrypted data nearly always decompresses in ways that defeat the
     attack.  However, this is not a rigorous fix, and leaves open some
     small vulnerabilities.  For example, if an implementation does not
     compress a message before encryption (perhaps because it knows it
     was already compressed), then that message is vulnerable.  Because
     of this happenstance -- that modification attacks can be thwarted
     by decompression errors -- an implementation SHOULD treat a
     decompression error as a security problem, not merely a data
     problem.

     This attack can be defeated by the use of Modification Detection,
     provided that the implementation does not let the user naively
     return the data to the attacker.  An implementation MUST treat an
     MDC failure as a security problem, not merely a data problem.

     In either case, the implementation MAY allow the user access to the
     erroneous data, but MUST warn the user as to potential security
     problems should that data be returned to the sender.

     While this attack is somewhat obscure, requiring a special set of
     circumstances to create it, it is nonetheless quite serious as it
     permits someone to trick a user to decrypt a message.
     Consequently, it is important that:

      1. Implementers treat MDC errors and decompression failures as
         security problems.

      2. Implementers implement Modification Detection with all due
         speed and encourage its spread.

      3. Users migrate to implementations that support Modification
         Detection with all due speed.

   * PKCS#1 has been found to be vulnerable to attacks in which a system
     that reports errors in padding differently from errors in
     decryption becomes a random oracle that can leak the private key in
     mere millions of queries.  Implementations must be aware of this
     attack and prevent it from happening.  The simplest solution is to
     report a single error code for all variants of decryption errors so
     as not to leak information to an attacker.



Callas, et al               Standards Track                    [Page 83]

RFC 4880                 OpenPGP Message Format            November 2007


   * Some technologies mentioned here may be subject to government
     control in some countries.

   * In winter 2005, Serge Mister and Robert Zuccherato from Entrust
     released a paper describing a way that the "quick check" in OpenPGP
     CFB mode can be used with a random oracle to decrypt two octets of
     every cipher block [MZ05].  They recommend as prevention not using
     the quick check at all.

     Many implementers have taken this advice to heart for any data that
     is symmetrically encrypted and for which the session key is
     public-key encrypted.  In this case, the quick check is not needed
     as the public-key encryption of the session key should guarantee
     that it is the right session key.  In other cases, the
     implementation should use the quick check with care.

     On the one hand, there is a danger to using it if there is a random
     oracle that can leak information to an attacker.  In plainer
     language, there is a danger to using the quick check if timing
     information about the check can be exposed to an attacker,
     particularly via an automated service that allows rapidly repeated
     queries.

     On the other hand, it is inconvenient to the user to be informed
     that they typed in the wrong passphrase only after a petabyte of
     data is decrypted.  There are many cases in cryptographic
     engineering where the implementer must use care and wisdom, and
     this is one.

15.  Implementation Nits

   This section is a collection of comments to help an implementer,
   particularly with an eye to backward compatibility.  Previous
   implementations of PGP are not OpenPGP compliant.  Often the
   differences are small, but small differences are frequently more
   vexing than large differences.  Thus, this is a non-comprehensive
   list of potential problems and gotchas for a developer who is trying
   to be backward-compatible.

     * The IDEA algorithm is patented, and yet it is required for PGP
       2.x interoperability.  It is also the de-facto preferred
       algorithm for a V3 key with a V3 self-signature (or no self-
       signature).

     * When exporting a private key, PGP 2.x generates the header "BEGIN
       PGP SECRET KEY BLOCK" instead of "BEGIN PGP PRIVATE KEY BLOCK".
       All previous versions ignore the implied data type, and look
       directly at the packet data type.



Callas, et al               Standards Track                    [Page 84]

RFC 4880                 OpenPGP Message Format            November 2007


     * PGP 2.0 through 2.5 generated V2 Public-Key packets.  These are
       identical to the deprecated V3 keys except for the version
       number.  An implementation MUST NOT generate them and may accept
       or reject them as it sees fit.  Some older PGP versions generated
       V2 PKESK packets (Tag 1) as well.  An implementation may accept
       or reject V2 PKESK packets as it sees fit, and MUST NOT generate
       them.

     * PGP 2.6.x will not accept key-material packets with versions
       greater than 3.

     * There are many ways possible for two keys to have the same key
       material, but different fingerprints (and thus Key IDs).  Perhaps
       the most interesting is an RSA key that has been "upgraded" to V4
       format, but since a V4 fingerprint is constructed by hashing the
       key creation time along with other things, two V4 keys created at
       different times, yet with the same key material will have
       different fingerprints.

     * If an implementation is using zlib to interoperate with PGP 2.x,
       then the "windowBits" parameter should be set to -13.

     * The 0x19 back signatures were not required for signing subkeys
       until relatively recently.  Consequently, there may be keys in
       the wild that do not have these back signatures.  Implementing
       software may handle these keys as it sees fit.

     * OpenPGP does not put limits on the size of public keys.  However,
       larger keys are not necessarily better keys.  Larger keys take
       more computation time to use, and this can quickly become
       impractical.  Different OpenPGP implementations may also use
       different upper bounds for public key sizes, and so care should
       be taken when choosing sizes to maintain interoperability.  As of
       2007 most implementations have an upper bound of 4096 bits.

     * ASCII armor is an optional feature of OpenPGP.  The OpenPGP
       working group strives for a minimal set of mandatory-to-implement
       features, and since there could be useful implementations that
       only use binary object formats, this is not a "MUST" feature for
       an implementation.  For example, an implementation that is using
       OpenPGP as a mechanism for file signatures may find ASCII armor
       unnecessary. OpenPGP permits an implementation to declare what
       features it does and does not support, but ASCII armor is not one
       of these.  Since most implementations allow binary and armored
       objects to be used indiscriminately, an implementation that does
       not implement ASCII armor may find itself with compatibility
       issues with general-purpose implementations.  Moreover,
       implementations of OpenPGP-MIME [RFC3156] already have a



Callas, et al               Standards Track                    [Page 85]

RFC 4880                 OpenPGP Message Format            November 2007


       requirement for ASCII armor so those implementations will
       necessarily have support.

16.  References

16.1.  Normative References

   [AES]            NIST, FIPS PUB 197, "Advanced Encryption Standard
                    (AES)," November 2001.
                    http://csrc.nist.gov/publications/fips/fips197/fips-
                    197.{ps,pdf}

   [BLOWFISH]       Schneier, B. "Description of a New Variable-Length
                    Key, 64-Bit Block Cipher (Blowfish)" Fast Software
                    Encryption, Cambridge Security Workshop Proceedings
                    (December 1993), Springer-Verlag, 1994, pp191-204
                    <http://www.counterpane.com/bfsverlag.html>

   [BZ2]            J. Seward, jseward@acm.org, "The Bzip2 and libbzip2
                    home page" <http://www.bzip.org/>

   [ELGAMAL]        T. Elgamal, "A Public-Key Cryptosystem and a
                    Signature Scheme Based on Discrete Logarithms," IEEE
                    Transactions on Information Theory, v. IT-31, n. 4,
                    1985, pp. 469-472.

   [FIPS180]        Secure Hash Signature Standard (SHS) (FIPS PUB 180-
                    2).
                    <http://csrc.nist.gov/publications/fips/fips180-
                    2/fips180-2withchangenotice.pdf>

   [FIPS186]        Digital Signature Standard (DSS) (FIPS PUB 186-2).
                    <http://csrc.nist.gov/publications/fips/fips186-2/
                     fips186-2-change1.pdf> FIPS 186-3 describes keys
                    greater than 1024 bits.  The latest draft is at:
                    <http://csrc.nist.gov/publications/drafts/
                    fips_186-3/Draft-FIPS-186-3%20_March2006.pdf>

   [HAC]            Alfred Menezes, Paul van Oorschot, and Scott
                    Vanstone, "Handbook of Applied Cryptography," CRC
                    Press, 1996.
                    <http://www.cacr.math.uwaterloo.ca/hac/>

   [IDEA]           Lai, X, "On the design and security of block
                    ciphers", ETH Series in Information Processing, J.L.
                    Massey (editor), Vol. 1, Hartung-Gorre Verlag
                    Knostanz, Technische Hochschule (Zurich), 1992




Callas, et al               Standards Track                    [Page 86]

RFC 4880                 OpenPGP Message Format            November 2007


   [ISO10646]       ISO/IEC 10646-1:1993. International Standard --
                    Information technology -- Universal Multiple-Octet
                    Coded Character Set (UCS) -- Part 1: Architecture
                    and Basic Multilingual Plane.

   [JFIF]           JPEG File Interchange Format (Version 1.02).  Eric
                    Hamilton, C-Cube Microsystems, Milpitas, CA,
                    September 1, 1992.

   [RFC1950]        Deutsch, P. and J-L. Gailly, "ZLIB Compressed Data
                    Format Specification version 3.3", RFC 1950, May
                    1996.

   [RFC1951]        Deutsch, P., "DEFLATE Compressed Data Format
                    Specification version 1.3", RFC 1951, May 1996.

   [RFC2045]        Freed, N. and N. Borenstein, "Multipurpose Internet
                    Mail Extensions (MIME) Part One: Format of Internet
                    Message Bodies", RFC 2045, November 1996

   [RFC2119]        Bradner, S., "Key words for use in RFCs to Indicate
                    Requirement Levels", BCP 14, RFC 2119, March 1997.

   [RFC2144]        Adams, C., "The CAST-128 Encryption Algorithm", RFC
                    2144, May 1997.

   [RFC2434]        Narten, T. and H. Alvestrand, "Guidelines for
                    Writing an IANA Considerations Section in RFCs", BCP
                    26, RFC 2434, October 1998.

   [RFC2822]        Resnick, P., "Internet Message Format", RFC 2822,
                    April 2001.

   [RFC3156]        Elkins, M., Del Torto, D., Levien, R., and T.
                    Roessler, "MIME Security with OpenPGP", RFC 3156,
                    August 2001.

   [RFC3447]        Jonsson, J. and B. Kaliski, "Public-Key Cryptography
                    Standards (PKCS) #1: RSA Cryptography Specifications
                    Version 2.1", RFC 3447, February 2003.

   [RFC3629]        Yergeau, F., "UTF-8, a transformation format of ISO
                    10646", STD 63, RFC 3629, November 2003.

   [RFC4086]        Eastlake, D., 3rd, Schiller, J., and S. Crocker,
                    "Randomness Requirements for Security", BCP 106, RFC
                    4086, June 2005.




Callas, et al               Standards Track                    [Page 87]

RFC 4880                 OpenPGP Message Format            November 2007


   [SCHNEIER]      Schneier, B., "Applied Cryptography Second Edition:
                    protocols, algorithms, and source code in C", 1996.

   [TWOFISH]        B. Schneier, J. Kelsey, D. Whiting, D. Wagner, C.
                    Hall, and N. Ferguson, "The Twofish Encryption
                    Algorithm", John Wiley & Sons, 1999.

16.2.  Informative References

   [BLEICHENBACHER] Bleichenbacher, Daniel, "Generating Elgamal
                    signatures without knowing the secret key,"
                    Eurocrypt 96. Note that the version in the
                    proceedings has an error. A revised version is
                    available at the time of writing from
                    <ftp://ftp.inf.ethz.ch/pub/publications/papers/ti
                    /isc/ElGamal.ps>

   [JKS02]          Kahil Jallad, Jonathan Katz, Bruce Schneier
                    "Implementation of Chosen-Ciphertext Attacks against
                    PGP and GnuPG" http://www.counterpane.com/pgp-
                    attack.html

   [MAURER]         Ueli Maurer, "Modelling a Public-Key
                    Infrastructure", Proc. 1996 European Symposium on
                    Research in Computer Security (ESORICS' 96), Lecture
                    Notes in Computer Science, Springer-Verlag, vol.
                    1146, pp. 325-350, Sep 1996.

   [MZ05]           Serge Mister, Robert Zuccherato, "An Attack on CFB
                    Mode Encryption As Used By OpenPGP," IACR ePrint
                    Archive: Report 2005/033, 8 Feb 2005
                    http://eprint.iacr.org/2005/033

   [REGEX]          Jeffrey Friedl, "Mastering Regular Expressions,"
                    O'Reilly, ISBN 0-596-00289-0.

   [RFC1423]        Balenson, D., "Privacy Enhancement for Internet
                    Electronic Mail: Part III: Algorithms, Modes, and
                    Identifiers", RFC 1423, February 1993.

   [RFC1991]        Atkins, D., Stallings, W., and P. Zimmermann, "PGP
                    Message Exchange Formats", RFC 1991, August 1996.

   [RFC2440]        Callas, J., Donnerhacke, L., Finney, H., and R.
                    Thayer, "OpenPGP Message Format", RFC 2440, November
                    1998.





Callas, et al               Standards Track                    [Page 88]

RFC 4880                 OpenPGP Message Format            November 2007


   [SP800-57]       NIST Special Publication 800-57, Recommendation on
                    Key Management
                    <http://csrc.nist.gov/publications/nistpubs/ 800-
                    57/SP800-57-Part1.pdf>
                    <http://csrc.nist.gov/publications/nistpubs/ 800-
                    57/SP800-57-Part2.pdf>

Acknowledgements

   This memo also draws on much previous work from a number of other
   authors, including: Derek Atkins, Charles Breed, Dave Del Torto, Marc
   Dyksterhouse, Gail Haspert, Gene Hoffman, Paul Hoffman, Ben Laurie,
   Raph Levien, Colin Plumb, Will Price, David Shaw, William Stallings,
   Mark Weaver, and Philip R. Zimmermann.

Authors' Addresses

   The working group can be contacted via the current chair:

      Derek Atkins
      IHTFP Consulting, Inc.
      4 Farragut Ave
      Somerville, MA  02144  USA

      EMail: derek@ihtfp.com
      Tel: +1 617 623 3745

   The principal authors of this document are as follows:

      Jon Callas
      EMail: jon@callas.org

      Lutz Donnerhacke
      IKS GmbH
      Wildenbruchstr. 15
      07745 Jena, Germany
      EMail: lutz@iks-jena.de

      Hal Finney
      EMail: hal@finney.org

      David Shaw
      EMail: dshaw@jabberwocky.com

      Rodney Thayer
      EMail: rodney@canola-jones.com





Callas, et al               Standards Track                    [Page 89]

RFC 4880                 OpenPGP Message Format            November 2007


Full Copyright Statement

   Copyright (C) The IETF Trust (2007).

   This document is subject to the rights, licenses and restrictions
   contained in BCP 78, and except as set forth therein, the authors
   retain all their rights.

   This document and the information contained herein are provided on an
   "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
   OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND
   THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS
   OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
   THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
   WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Intellectual Property

   The IETF takes no position regarding the validity or scope of any
   Intellectual Property Rights or other rights that might be claimed to
   pertain to the implementation or use of the technology described in
   this document or the extent to which any license under such rights
   might or might not be available; nor does it represent that it has
   made any independent effort to identify any such rights.  Information
   on the procedures with respect to rights in RFC documents can be
   found in BCP 78 and BCP 79.

   Copies of IPR disclosures made to the IETF Secretariat and any
   assurances of licenses to be made available, or the result of an
   attempt made to obtain a general license or permission for the use of
   such proprietary rights by implementers or users of this
   specification can be obtained from the IETF on-line IPR repository at
   http://www.ietf.org/ipr.

   The IETF invites any interested party to bring to its attention any
   copyrights, patents or patent applications, or other proprietary
   rights that may cover technology that may be required to implement
   this standard.  Please address the information to the IETF at
   ietf-ipr@ietf.org.












Callas, et al               Standards Track                    [Page 90]



================================================
FILE: doc/notes/rfc/rfc4954.txt
================================================






Network Working Group                                 R. Siemborski, Ed.
Request for Comments: 4954                                  Google, Inc.
Obsoletes: 2554                                         A. Melnikov, Ed.
Updates: 3463                                              Isode Limited
Category: Standards Track                                      July 2007


               SMTP Service Extension for Authentication

Status of This Memo

   This document specifies an Internet standards track protocol for the
   Internet community, and requests discussion and suggestions for
   improvements.  Please refer to the current edition of the "Internet
   Official Protocol Standards" (STD 1) for the standardization state
   and status of this protocol.  Distribution of this memo is unlimited.

Copyright Notice

   Copyright (C) The IETF Trust (2007).

Abstract

   This document defines a Simple Mail Transport Protocol (SMTP)
   extension whereby an SMTP client may indicate an authentication
   mechanism to the server, perform an authentication protocol exchange,
   and optionally negotiate a security layer for subsequent protocol
   interactions during this session.  This extension includes a profile
   of the Simple Authentication and Security Layer (SASL) for SMTP.

   This document obsoletes RFC 2554.




















Siemborski & Melnikov       Standards Track                     [Page 1]

RFC 4954       SMTP Service Extension for Authentication       July 2007


Table of Contents

   1. Introduction ....................................................2
   2. How to Read This Document .......................................2
   3. The Authentication Service Extension ............................3
   4. The AUTH Command ................................................3
      4.1. Examples ...................................................7
   5. The AUTH Parameter to the MAIL FROM command .....................9
      5.1. Examples ..................................................10
   6. Status Codes ...................................................11
   7. Additional requirements on servers .............................12
   8. Formal Syntax ..................................................13
   9. Security Considerations ........................................14
   10. IANA Considerations ...........................................15
   11. Normative References ..........................................15
   12. Informative References ........................................16
   13. Acknowledgments ...............................................17
   14. Additional Requirements When Using SASL PLAIN over TLS ........17
   15. Changes since RFC 2554 ........................................18

1.  Introduction

   This document defines a Simple Mail Transport Protocol (SMTP)
   extension whereby an SMTP client may indicate an authentication
   mechanism to the server, perform an authentication protocol exchange,
   optionally negotiate a security layer for subsequent protocol
   interactions during this session and, during a mail transaction,
   optionally specify a mailbox associated with the identity that
   submitted the message to the mail delivery system.

   This extension includes a profile of the Simple Authentication and
   Security Layer (SASL) for SMTP.

   When compared to RFC 2554, this document deprecates use of the 538
   response code, adds a new Enhanced Status Code, adds a requirement to
   support SASLprep profile for preparing authorization identities,
   recommends use of RFC 3848 transmission types in the Received trace
   header field, and clarifies interaction with SMTP PIPELINING
   [PIPELINING] extension.

2.  How to Read This Document

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in [KEYWORDS].

   In examples, "C:" and "S:" indicate lines sent by the client and
   server, respectively.



Siemborski & Melnikov       Standards Track                     [Page 2]

RFC 4954       SMTP Service Extension for Authentication       July 2007


3.  The Authentication Service Extension

   1.  The name of this [SMTP] service extension is "Authentication".

   2.  The EHLO keyword value associated with this extension is "AUTH".

   3.  The AUTH EHLO keyword contains as a parameter a space-separated
       list of the names of available [SASL] mechanisms.  The list of
       available mechanisms MAY change after a successful STARTTLS
       command [SMTP-TLS].

   4.  A new [SMTP] verb "AUTH" is defined.

   5.  An optional parameter using the keyword "AUTH" is added to the
       MAIL FROM command, and extends the maximum line length of the
       MAIL FROM command by 500 characters.

   6.  This extension is appropriate for the submission protocol
       [SUBMIT].

4.  The AUTH Command

   AUTH mechanism [initial-response]

      Arguments:
          mechanism: A string identifying a [SASL] authentication
          mechanism.

          initial-response: An optional initial client response.  If
          present, this response MUST be encoded as described in Section
          4 of [BASE64] or contain a single character "=".

      Restrictions:
          After an AUTH command has been successfully completed, no more
          AUTH commands may be issued in the same session.  After a
          successful AUTH command completes, a server MUST reject any
          further AUTH commands with a 503 reply.

          The AUTH command is not permitted during a mail transaction.
          An AUTH command issued during a mail transaction MUST be
          rejected with a 503 reply.

      Discussion:
          The AUTH command initiates a [SASL] authentication exchange
          between the client and the server.  The client identifies the
          SASL mechanism to use with the first parameter of the AUTH
          command.  If the server supports the requested authentication
          mechanism, it performs the SASL exchange to authenticate the



Siemborski & Melnikov       Standards Track                     [Page 3]

RFC 4954       SMTP Service Extension for Authentication       July 2007


          user.  Optionally, it also negotiates a security layer for
          subsequent protocol interactions during this session.  If the
          requested authentication mechanism is invalid (e.g., is not
          supported or requires an encryption layer), the server rejects
          the AUTH command with a 504 reply.  If the server supports the
          [ESMTP-CODES] extension, it SHOULD return a 5.5.4 enhanced
          response code.

          The SASL authentication exchange consists of a series of
          server challenges and client responses that are specific to
          the chosen [SASL] mechanism.

          A server challenge is sent as a 334 reply with the text part
          containing the [BASE64] encoded string supplied by the SASL
          mechanism.  This challenge MUST NOT contain any text other
          than the BASE64 encoded challenge.

          A client response consists of a line containing a [BASE64]
          encoded string.  If the client wishes to cancel the
          authentication exchange, it issues a line with a single "*".
          If the server receives such a response, it MUST reject the
          AUTH command by sending a 501 reply.

          The optional initial response argument to the AUTH command is
          used to save a round-trip when using authentication mechanisms
          that support an initial client response.  If the initial
          response argument is omitted and the chosen mechanism requires
          an initial client response, the server MUST proceed as defined
          in Section 5.1 of [SASL].  In SMTP, a server challenge that
          contains no data is defined as a 334 reply with no text part.
          Note that there is still a space following the reply code, so
          the complete response line is "334 ".

          Note that the AUTH command is still subject to the line length
          limitations defined in [SMTP].  If use of the initial response
          argument would cause the AUTH command to exceed this length,
          the client MUST NOT use the initial response parameter (and
          instead proceed as defined in Section 5.1 of [SASL]).

          If the client is transmitting an initial response of zero
          length, it MUST instead transmit the response as a single
          equals sign ("=").  This indicates that the response is
          present, but contains no data.

          If the client uses an initial-response argument to the AUTH
          command with a SASL mechanism in which the client does not
          begin the authentication exchange, the server MUST reject the




Siemborski & Melnikov       Standards Track                     [Page 4]

RFC 4954       SMTP Service Extension for Authentication       July 2007


          AUTH command with a 501 reply.  Servers using the enhanced
          status codes extension [ESMTP-CODES] SHOULD return an enhanced
          status code of 5.7.0 in this case.

          If the server cannot [BASE64] decode any client response, it
          MUST reject the AUTH command with a 501 reply (and an enhanced
          status code of 5.5.2).  If the client cannot BASE64 decode any
          of the server's challenges, it MUST cancel the authentication
          using the "*" response.  In particular, servers and clients
          MUST reject (and not ignore) any character not explicitly
          allowed by the BASE64 alphabet, and MUST reject any sequence
          of BASE64 characters that contains the pad character ('=')
          anywhere other than the end of the string (e.g., "=AAA" and
          "AAA=BBB" are not allowed).

          Note that these [BASE64] strings can be much longer than
          normal SMTP commands.  Clients and servers MUST be able to
          handle the maximum encoded size of challenges and responses
          generated by their supported authentication mechanisms.  This
          requirement is independent of any line length limitations the
          client or server may have in other parts of its protocol
          implementation.  (At the time of writing of this document,
          12288 octets is considered to be a sufficient line length
          limit for handling of deployed authentication mechanisms.)
          If, during an authentication exchange, the server receives a
          line that is longer than the server's authentication buffer,
          the server fails the AUTH command with the 500 reply.  Servers
          using the enhanced status codes extension [ESMTP-CODES] SHOULD
          return an enhanced status code of 5.5.6 in this case.

          The authorization identity generated by this [SASL] exchange
          is a "simple username" (in the sense defined in [SASLprep]),
          and both client and server SHOULD (*) use the [SASLprep]
          profile of the [StringPrep] algorithm to prepare these names
          for transmission or comparison.  If preparation of the
          authorization identity fails or results in an empty string
          (unless it was transmitted as the empty string), the server
          MUST fail the authentication.

      (*) Note: Future revision of this specification may change this
      requirement to MUST.  Currently, the SHOULD is used in order to
      avoid breaking the majority of existing implementations.

   If the server is unable to authenticate the client, it SHOULD reject
   the AUTH command with a 535 reply unless a more specific error code
   is appropriate.  Should the client successfully complete the
   exchange, the SMTP server issues a 235 reply.  (Note that the SMTP
   protocol doesn't support the SASL feature of returning additional



Siemborski & Melnikov       Standards Track                     [Page 5]

RFC 4954       SMTP Service Extension for Authentication       July 2007


   data with a successful outcome.)  These status codes, along with
   others defined by this extension, are discussed in Section 6 of this
   document.

   If a security layer is negotiated during the SASL exchange, it takes
   effect for the client on the octet immediately following the CRLF
   that concludes the last response generated by the client.  For the
   server, it takes effect immediately following the CRLF of its success
   reply.

   When a security layer takes effect, the SMTP protocol is reset to the
   initial state (the state in SMTP after a server issues a 220 service
   ready greeting).  The server MUST discard any knowledge obtained from
   the client, such as the EHLO argument, which was not obtained from
   the SASL negotiation itself.  Likewise, the client MUST discard any
   knowledge obtained from the server, such as the list of SMTP service
   extensions, which was not obtained from the SASL negotiation itself.
   (Note that a client MAY compare the advertised SASL mechanisms before
   and after authentication in order to detect an active down-
   negotiation attack).

   The client SHOULD send an EHLO command as the first command after a
   successful SASL negotiation that results in the enabling of a
   security layer.

   When an entity (whether it is the client or the server end) is
   sending data, and both [TLS] and SASL security layers are in effect,
   the TLS encoding MUST be applied after the SASL encoding, regardless
   of the order in which the layers were negotiated.

   The service name specified by this protocol's profile of SASL is
   "smtp".  This service name is also to be used for the [SUBMIT]
   protocol.

   If an AUTH command fails, the client MAY proceed without
   authentication.  Alternatively, the client MAY try another
   authentication mechanism or present different credentials by issuing
   another AUTH

   Note: A server implementation MUST implement a configuration in which
   it does NOT permit any plaintext password mechanisms, unless either
   the STARTTLS [SMTP-TLS] command has been negotiated or some other
   mechanism that protects the session from password snooping has been
   provided.  Server sites SHOULD NOT use any configuration which
   permits a plaintext password mechanism without such a protection
   mechanism against password snooping.





Siemborski & Melnikov       Standards Track                     [Page 6]

RFC 4954       SMTP Service Extension for Authentication       July 2007


   To ensure interoperability, client and server implementations of this
   extension MUST implement the [PLAIN] SASL mechanism running over TLS
   [TLS] [SMTP-TLS].  See also Section 15 for additional requirements on
   implementations of [PLAIN] over [TLS].

   Note that many existing client and server implementations implement
   CRAM-MD5 [CRAM-MD5] SASL mechanism.  In order to ensure
   interoperability with deployed software, new implementations MAY
   implement it; however, implementations should be aware that this SASL
   mechanism doesn't provide any server authentication.  Note that at
   the time of writing of this document the SASL Working Group is
   working on several replacement SASL mechanisms that provide server
   authentication and other features.

   When the AUTH command is used together with the [PIPELINING]
   extension, it MUST be the last command in a pipelined group of
   commands.  The only exception to this rule is when the AUTH command
   contains an initial response for a SASL mechanism that allows the
   client to send data first, the SASL mechanism is known to complete in
   one round-trip, and a security layer is not negotiated by the client.
   Two examples of such SASL mechanisms are PLAIN [PLAIN] and EXTERNAL
   [SASL].

4.1. Examples

   Here is an example of a client attempting AUTH using the [PLAIN] SASL
   mechanism under a TLS layer, and making use of the initial client
   response:

   S: 220-smtp.example.com ESMTP Server
   C: EHLO client.example.com
   S: 250-smtp.example.com Hello client.example.com
   S: 250-AUTH GSSAPI DIGEST-MD5
   S: 250-ENHANCEDSTATUSCODES
   S: 250 STARTTLS
   C: STARTTLS
   S: 220 Ready to start TLS
     ... TLS negotiation proceeds, further commands
         protected by TLS layer ...
   C: EHLO client.example.com
   S: 250-smtp.example.com Hello client.example.com
   S: 250 AUTH GSSAPI DIGEST-MD5 PLAIN
   C: AUTH PLAIN dGVzdAB0ZXN0ADEyMzQ=
   S: 235 2.7.0 Authentication successful

   Here is another client that is attempting AUTH PLAIN under a TLS
   layer, this time without the initial response.  Parts of the
   negotiation before the TLS layer was established have been omitted:



Siemborski & Melnikov       Standards Track                     [Page 7]

RFC 4954       SMTP Service Extension for Authentication       July 2007


     ... TLS negotiation proceeds, further commands
         protected by TLS layer ...
   C: EHLO client.example.com
   S: 250-smtp.example.com Hello client.example.com
   S: 250 AUTH GSSAPI DIGEST-MD5 PLAIN
   C: AUTH PLAIN
    (note: there is a single space following the 334
     on the following line)
   S: 334
   C: dGVzdAB0ZXN0ADEyMzQ=
   S: 235 2.7.0 Authentication successful

   Here is an example using CRAM-MD5 [CRAM-MD5], a mechanism in which
   the client does not begin the authentication exchange, and includes a
   server challenge:

   S: 220-smtp.example.com ESMTP Server
   C: EHLO client.example.com
   S: 250-smtp.example.com Hello client.example.com
   S: 250-AUTH DIGEST-MD5 CRAM-MD5
   S: 250-ENHANCEDSTATUSCODES
   S: 250 STARTTLS
   C: AUTH CRAM-MD5
   S: 334 PDQxOTI5NDIzNDEuMTI4Mjg0NzJAc291cmNlZm91ci5hbmRyZXcuY211LmVk
      dT4=
   C: cmpzMyBlYzNhNTlmZWQzOTVhYmExZWM2MzY3YzRmNGI0MWFjMA==
   S: 235 2.7.0 Authentication successful

   Here is an example of a client attempting AUTH EXTERNAL under TLS,
   using the derived authorization ID (and thus a zero-length initial
   client response).

   S: 220-smtp.example.com ESMTP Server
   C: EHLO client.example.com
   S: 250-smtp.example.com Hello client.example.com
   S: 250-AUTH GSSAPI DIGEST-MD5
   S: 250-ENHANCEDSTATUSCODES
   S: 250 STARTTLS
   C: STARTTLS
   S: 220 Ready to start TLS
     ... TLS negotiation proceeds, further commands
         protected by TLS layer ...
   C: EHLO client.example.com
   S: 250-smtp.example.com Hello client.example.com
   S: 250 AUTH EXTERNAL GSSAPI DIGEST-MD5 PLAIN
   C: AUTH EXTERNAL =
   S: 235 2.7.0 Authentication successful




Siemborski & Melnikov       Standards Track                     [Page 8]

RFC 4954       SMTP Service Extension for Authentication       July 2007


5.  The AUTH Parameter to the MAIL FROM command

   AUTH=mailbox

   Arguments:
        A <mailbox> (see Section 4.1.2 of [SMTP]) that is associated
        with the identity that submitted the message to the delivery
        system, or the two character sequence "<>" indicating such an
        identity is unknown or insufficiently authenticated.  To comply
        with restrictions imposed on ESMTP parameters, the <mailbox> is
        encoded inside an xtext.  The syntax of an xtext is described in
        Section 4 of [ESMTP-DSN].

   Note:
        For the purposes of this discussion, "authenticated identity"
        refers to the identity (if any) derived from the authorization
        identity of previous AUTH command, while the terms "authorized
        identity" and "supplied <mailbox>" refer to the sender identity
        that is being associated with a particular message.  Note that
        one authenticated identity may be able to identify messages as
        being sent by any number of authorized identities within a
        single session.  For example, this may be the case when an SMTP
        server (one authenticated identity) is processing its queue
        (many messages with distinct authorized identities).

   Discussion:
        The optional AUTH parameter to the MAIL FROM command allows
        cooperating agents in a trusted environment to communicate the
        authorization identity associated with individual messages.

        If the server trusts the authenticated identity of the client to
        assert that the message was originally submitted by the supplied
        <mailbox>, then the server SHOULD supply the same <mailbox> in
        an AUTH parameter when relaying the message to any other server
        which supports the AUTH extension.

        For this reason, servers that advertise support for this
        extension MUST support the AUTH parameter to the MAIL FROM
        command even when the client has not authenticated itself to the
        server.

        A MAIL FROM parameter of AUTH=<> indicates that the original
        submitter of the message is not known.  The server MUST NOT
        treat the message as having been originally submitted by the
        authenticated identity that resulted from the AUTH command.






Siemborski & Melnikov       Standards Track                     [Page 9]

RFC 4954       SMTP Service Extension for Authentication       July 2007


        If the AUTH parameter to the MAIL FROM command is not supplied,
        the client has authenticated, and the server believes the
        message is an original submission, the server MAY generate a
        <mailbox> from the user's authenticated identity for use in an
        AUTH parameter when relaying the message to any server which
        supports the AUTH extension.  The generated <mailbox> is
        implementation specific, but it MUST conform to the syntax of
        [SMTP].  If the implementation cannot generate a valid
        <mailbox>, it MUST transmit AUTH=<> when relaying this message.

        If the server does not sufficiently trust the authenticated
        identity of the client, or if the client is not authenticated,
        then the server MUST behave as if the AUTH=<> parameter was
        supplied.  The server MAY, however, write the value of any
        supplied AUTH parameter to a log file.

        If an AUTH=<> parameter was supplied, either explicitly or due
        to the requirement in the previous paragraph, then the server
        MUST supply the AUTH=<> parameter when relaying the message to
        any server which it has authenticated to using the AUTH
        extension.

        A server MAY treat expansion of a mailing list as a new
        submission, setting the AUTH parameter to the mailing list
        address or mailing list administration address when relaying the
        message to list subscribers.

        Note that an implementation which is hard-coded to treat all
        clients as being insufficiently trusted is compliant with this
        specification.  In that case, the implementation does nothing
        more than parse and discard syntactically valid AUTH parameters
        to the MAIL FROM command, and supply AUTH=<> parameters to any
        servers that it authenticates to.

5.1.  Examples

   An example where the original identity of the sender is trusted and
   known:

   C: MAIL FROM:<e=mc2@example.com> AUTH=e+3Dmc2@example.com
   S: 250 OK

   One example where the identity of the sender is not trusted or is
   otherwise being suppressed by the client:

   C: MAIL FROM:<john+@example.org> AUTH=<>
   S: 250 OK




Siemborski & Melnikov       Standards Track                    [Page 10]

RFC 4954       SMTP Service Extension for Authentication       July 2007


6.  Status Codes

   The following error codes may be used to indicate various success or
   failure conditions.  Servers that return enhanced status codes
   [ESMTP-CODES] SHOULD use the enhanced codes suggested here.

   235 2.7.0  Authentication Succeeded

   This response to the AUTH command indicates that the authentication
   was successful.

   432 4.7.12  A password transition is needed

   This response to the AUTH command indicates that the user needs to
   transition to the selected authentication mechanism.  This is
   typically done by authenticating once using the [PLAIN]
   authentication mechanism.  The selected mechanism SHOULD then work
   for authentications in subsequent sessions.

   454 4.7.0  Temporary authentication failure

   This response to the AUTH command indicates that the authentication
   failed due to a temporary server failure.  The client SHOULD NOT
   prompt the user for another password in this case, and should instead
   notify the user of server failure.

   534 5.7.9  Authentication mechanism is too weak

   This response to the AUTH command indicates that the selected
   authentication mechanism is weaker than server policy permits for
   that user.  The client SHOULD retry with a new authentication
   mechanism.

   535 5.7.8  Authentication credentials invalid

   This response to the AUTH command indicates that the authentication
   failed due to invalid or insufficient authentication credentials.  In
   this case, the client SHOULD ask the user to supply new credentials
   (such as by presenting a password dialog box).

   500 5.5.6  Authentication Exchange line is too long

   This response to the AUTH command indicates that the authentication
   failed due to the client sending a [BASE64] response that is longer
   than the maximum buffer size available for the currently selected
   SASL mechanism.





Siemborski & Melnikov       Standards Track                    [Page 11]

RFC 4954       SMTP Service Extension for Authentication       July 2007


   530 5.7.0  Authentication required

   This response SHOULD be returned by any command other than AUTH,
   EHLO, HELO, NOOP, RSET, or QUIT when server policy requires
   authentication in order to perform the requested action and
   authentication is not currently in force.

   538 5.7.11  Encryption required for requested authentication
               mechanism

   This response to the AUTH command indicates that the selected
   authentication mechanism may only be used when the underlying SMTP
   connection is encrypted.  Note that this response code is documented
   here for historical purposes only.  Modern implementations SHOULD NOT
   advertise mechanisms that are not permitted due to lack of
   encryption, unless an encryption layer of sufficient strength is
   currently being employed.

   This document adds several new enhanced status codes to the list
   defined in [ENHANCED]:

   The following 3 Enhanced Status Codes were defined above:

       5.7.8 Authentication credentials invalid
       5.7.9 Authentication mechanism is too weak
       5.7.11 Encryption required for requested authentication mechanism

   X.5.6     Authentication Exchange line is too long

   This enhanced status code SHOULD be returned when the server fails
   the AUTH command due to the client sending a [BASE64] response which
   is longer than the maximum buffer size available for the currently
   selected SASL mechanism.  This is useful for both permanent and
   persistent transient errors.

7.  Additional Requirements on Servers

   As described in Section 4.4 of [SMTP], an SMTP server that receives a
   message for delivery or further processing MUST insert the
   "Received:" header field at the beginning of the message content.
   This document places additional requirements on the content of a
   generated "Received:" header field.  Upon successful authentication,
   a server SHOULD use the "ESMTPA" or the "ESMTPSA" [SMTP-TT] (when
   appropriate) keyword in the "with" clause of the Received header
   field.






Siemborski & Melnikov       Standards Track                    [Page 12]

RFC 4954       SMTP Service Extension for Authentication       July 2007


8.  Formal Syntax

   The following syntax specification uses the Augmented Backus-Naur
   Form notation as specified in [ABNF].  Non-terminals referenced but
   not defined below are as defined by [ABNF] or [SASL].  The non-
   terminal <mailbox> is defined in [SMTP].

   Except as noted otherwise, all alphabetic characters are case-
   insensitive.  The use of upper or lower case characters to define
   token strings is for editorial clarity only.  Implementations MUST
   accept these strings in a case-insensitive fashion.

      hexchar         = "+" HEXDIG HEXDIG

      xchar           = %x21-2A / %x2C-3C / %x3E-7E
                        ;; US-ASCII except for "+", "=", SP, and CTL

      xtext           = *(xchar / hexchar)
                        ;; non-US-ASCII is only allowed as hexchar

      auth-command    = "AUTH" SP sasl-mech [SP initial-response]
                        *(CRLF [base64]) [CRLF cancel-response]
                        CRLF
                        ;; <sasl-mech> is defined in [SASL]

      auth-param      = "AUTH=" xtext
                        ;; Parameter to the MAIL FROM command.
                        ;; This non-terminal complies with
                        ;; syntax defined by esmtp-param [SMTP].
                        ;;
                        ;; The decoded form of the xtext MUST be
                        ;; either a <mailbox> or the two
                        ;; characters "<>"

      base64          = base64-terminal /
                        ( 1*(4base64-char) [base64-terminal] )

      base64-char     = ALPHA / DIGIT / "+" / "/"
                        ;; Case-sensitive

      base64-terminal = (2base64-char "==") / (3base64-char "=")

      continue-req    = "334" SP [base64] CRLF
                        ;; Intermediate response to the AUTH
                        ;; command.
                        ;; This non-terminal complies with
                        ;; syntax defined by Reply-line [SMTP].




Siemborski & Melnikov       Standards Track                    [Page 13]

RFC 4954       SMTP Service Extension for Authentication       July 2007


      initial-response= base64 / "="

      cancel-response = "*"

9.  Security Considerations

   Security issues are discussed throughout this memo.

   If a client uses this extension to get an encrypted tunnel through an
   insecure network to a cooperating server, it needs to be configured
   to never send mail to that server when the connection is not mutually
   authenticated and encrypted.  Otherwise, an attacker could steal the
   client's mail by hijacking the [SMTP] connection and either
   pretending the server does not support the Authentication extension
   or causing all AUTH commands to fail.

   Before the [SASL] negotiation has begun, any protocol interactions
   are performed in the clear and may be modified by an active attacker.
   For this reason, clients and servers MUST discard any knowledge
   obtained prior to the start of the SASL negotiation upon the
   establishment of a security layer.

   This mechanism does not protect the TCP port, so an active attacker
   may redirect a relay connection attempt (i.e., a connection between
   two Mail Transfer Agents (MTAs)) to the submission port [SUBMIT].
   The AUTH=<> parameter prevents such an attack from causing a relayed
   message and, in the absence of other envelope authentication, from
   picking up the authentication of the relay client.

   A message submission client may require the user to authenticate
   whenever a suitable [SASL] mechanism is advertised.  Therefore, it
   may not be desirable for a submission server [SUBMIT] to advertise a
   SASL mechanism when use of that mechanism grants the clients no
   benefits over anonymous submission.

   Servers MAY implement a policy whereby the connection is dropped
   after a number of failed authentication attempts.  If they do so,
   they SHOULD NOT drop the connection until at least 3 attempts to
   authenticate have failed.

   If an implementation supports SASL mechanisms that are vulnerable to
   passive eavesdropping attacks (such as [PLAIN]), then the
   implementation MUST support at least one configuration where these
   SASL mechanisms are not advertised or used without the presence of an
   external security layer such as [TLS].






Siemborski & Melnikov       Standards Track                    [Page 14]

RFC 4954       SMTP Service Extension for Authentication       July 2007


   This extension is not intended to replace or be used instead of end-
   to-end message signature and encryption systems such as [S/MIME] or
   [PGP].  This extension addresses a different problem than end-to-end
   systems; it has the following key differences:

   1.  It is generally useful only within a trusted enclave.

   2.  It protects the entire envelope of a message, not just the
       message's body.

   3.  It authenticates the message submission, not authorship of the
       message content.

   4.  When mutual authentication is used along with a security layer,
       it can give the sender some assurance that the message was
       successfully delivered to the next hop.

   Additional security considerations are mentioned in the [SASL]
   specification.  Additional security considerations specific to a
   particular SASL mechanism are described in the relevant
   specification.  Additional security considerations for [PLAIN] over
   [TLS] are mentioned in Section 15 of this document.

10.  IANA Considerations

   IANA updated the entry for the "smtp" SASL protocol name to point at
   this document.

   IANA updated the registration of the Authentication SMTP service
   extension as defined in Section 3 of this document.  This registry is
   currently located at <http://www.iana.org/assignments/mail-
   parameters>.

11.  Normative References

   [ABNF]        Crocker, D. and P. Overell, "Augmented BNF for Syntax
                 Specifications: ABNF", RFC 4234, October 2005.

   [BASE64]      Josefsson, S., "The Base16, Base32, and Base64 Data
                 Encodings", RFC 4648, October 2006.

   [ESMTP-CODES] Freed, N., "SMTP Service Extension for Returning
                 Enhanced Error Codes", RFC 2034, October 1996.

   [ENHANCED]    Vaudreuil, G., "Enhanced Mail System Status Codes", RFC
                 3463, January 2003.





Siemborski & Melnikov       Standards Track                    [Page 15]

RFC 4954       SMTP Service Extension for Authentication       July 2007


   [ESMTP-DSN]   Moore, K., "Simple Mail Transfer Protocol (SMTP)
                 Service Extension Delivery Status Notifications
                 (DSNs)", RFC 3461, January 2003.

   [KEYWORDS]    Bradner, S., "Key words for use in RFCs to Indicate
                 Requirement Levels", BCP 14, RFC 2119, March 1997.

   [SASL]        Melnikov, A. and K. Zeilenga, "Simple Authentication
                 and Security Layer (SASL)", RFC 4422, June 2006.

   [SASLprep]    Zeilenga, K., "SASLprep: Stringprep Profile for User
                 Names and Passwords", RFC 4013, February 2005.

   [SMTP]        Klensin, J., "Simple Mail Transfer Protocol", RFC 2821,
                 April 2001.

   [SMTP-TLS]    Hoffman, P., "SMTP Service Extension for Secure SMTP
                 over Transport Layer Security", RFC 3207, February
                 2002.

   [StringPrep]  Hoffman, P. and M. Blanchet, "Preparation of
                 Internationalized Strings ("stringprep")", RFC 3454,
                 December 2002.

   [SUBMIT]      Gellens, R. and J. Klensin, "Message Submission for
                 Mail", RFC 4409, April 2006.

   [SMTP-TT]     Newman, C., "ESMTP and LMTP Transmission Types
                 Registration", RFC 3848, July 2004.

   [PLAIN]       Zeilenga, K., Ed., "The PLAIN Simple Authentication and
                 Security Layer (SASL) Mechanism", RFC 4616, August
                 2006.

   [X509]        Housley, R., Polk, W., Ford, W., and D. Solo, "Internet
                 X.509 Public Key Infrastructure Certificate and
                 Certificate Revocation List (CRL) Profile", RFC 3280,
                 April 2002.

12.  Informative References

   [PGP]         Elkins, M., "MIME Security with Pretty Good Privacy
                 (PGP)", RFC 2015, October 1996.

   [S/MIME]      Ramsdell, B., Ed., "Secure/Multipurpose Internet Mail
                 Extensions (S/MIME) Version 3.1 Message Specification",
                 RFC 3851, July 2004.




Siemborski & Melnikov       Standards Track                    [Page 16]

RFC 4954       SMTP Service Extension for Authentication       July 2007


   [TLS]         Dierks, T. and E. Rescorla, "The Transport Layer
                 Security (TLS) Protocol Version 1.1", RFC 4346, April
                 2006.

   [PIPELINING]  Freed, N., "SMTP Service Extension for Command
                 Pipelining", STD 60, RFC 2920, September 2000.

   [CRAM-MD5]    Klensin, J., Catoe, R., and P. Krumviede, "IMAP/POP
                 AUTHorize Extension for Simple Challenge/Response", RFC
                 2195, September 1997.

13.  Acknowledgments

   The editors would like to acknowledge the contributions of John Myers
   and other contributors to RFC 2554, on which this document draws from
   heavily.

   The editors would also like to thank Ken Murchison, Mark Crispin,
   Chris Newman, David Wilson, Dave Cridland, Frank Ellermann, Ned
   Freed, John Klensin, Tony Finch, Abhijit Menon-Sen, Philip Guenther,
   Sam Hartman, Russ Housley, Cullen Jennings, and Lisa Dusseault for
   the time they devoted to reviewing of this document and/or for the
   comments received.

14.  Additional Requirements When Using SASL PLAIN over TLS

   This section is normative for SMTP implementations that support SASL
   [PLAIN] over [TLS].

   If an SMTP client is willing to use SASL PLAIN over TLS to
   authenticate to the SMTP server, the client verifies the server
   certificate according to the rules of [X509].  If the server has not
   provided any certificate, or if the certificate verification fails,
   the client MUST NOT attempt to authenticate using the SASL PLAIN
   mechanism.

   After a successful [TLS] negotiation, the client MUST check its
   understanding of the server hostname against the server's identity as
   presented in the server Certificate message, in order to prevent
   man-in-the-middle attacks.  If the match fails, the client MUST NOT
   attempt to authenticate using the SASL PLAIN mechanism.  Matching is
   performed according to the following rules:

        The client MUST use the server hostname it used to open the
        connection as the value to compare against the server name as
        expressed in the server certificate.  The client MUST NOT use





Siemborski & Melnikov       Standards Track                    [Page 17]

RFC 4954       SMTP Service Extension for Authentication       July 2007


        any form of the server hostname derived from an insecure remote
        source (e.g., insecure DNS lookup).  CNAME canonicalization is
        not done.

        If a subjectAltName extension of type dNSName is present in the
        certificate, it SHOULD be used as the source of the server's
        identity.

        Matching is case-insensitive.

        A "*" wildcard character MAY be used as the leftmost name
        component in the certificate.  For example, *.example.com would
        match a.example.com, foo.example.com, etc., but would not match
        example.com.

        If the certificate contains multiple names (e.g., more than one
        dNSName field), then a match with any one of the fields is
        considered acceptable.

15.  Changes since RFC 2554

   1.  Clarified that servers MUST support the use of the AUTH=mailbox
       parameter to MAIL FROM, even when the client is not
       authenticated.

   2.  Clarified the initial-client-send requirements, and give
       additional examples.

   3.  Updated references to newer versions of various specifications.

   4.  Required SASL PLAIN (over TLS) as mandatory-to-implement.

   5.  Clarified that the mechanism list can change.

   6.  Deprecated the use of the 538 response code.

   7.  Added the use of the SASLprep profile for preparing authorization
       identities.

   8.  Substantial cleanup of response codes and indicated suggested
       enhanced response codes.  Also indicated what response codes
       should result in a client prompting the user for new credentials.

   9.  Updated ABNF section to use RFC 4234.

   10. Clarified interaction with SMTP PIPELINING extension.

   11. Added a reference to RFC 3848.



Siemborski & Melnikov       Standards Track                    [Page 18]

RFC 4954       SMTP Service Extension for Authentication       July 2007


   12. Added a new Enhanced Status Code for "authentication line too
       long" case.

   13. Other general editorial clarifications.

Editors' Addresses

   Robert Siemborski
   Google, Inc.
   1600 Ampitheatre Parkway
   Mountain View, CA 94043, USA

   Phone: +1 650 623 6925
   EMail: robsiemb@google.com


   Alexey Melnikov
   Isode Limited
   5 Castle Business Village, 36 Station Road,
   Hampton, Middlesex, TW12 2BX, UK

   EMail: Alexey.Melnikov@isode.com





























Siemborski & Melnikov       Standards Track                    [Page 19]

RFC 4954       SMTP Service Extension for Authentication       July 2007


Full Copyright Statement

   Copyright (C) The IETF Trust (2007).

   This document is subject to the rights, licenses and restrictions
   contained in BCP 78, and except as set forth therein, the authors
   retain all their rights.

   This document and the information contained herein are provided on an
   "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
   OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND
   THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS
   OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
   THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
   WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Intellectual Property

   The IETF takes no position regarding the validity or scope of any
   Intellectual Property Rights or other rights that might be claimed to
   pertain to the implementation or use of the technology described in
   this document or the extent to which any license under such rights
   might or might not be available; nor does it represent that it has
   made any independent effort to identify any such rights.  Information
   on the procedures with respect to rights in RFC documents can be
   found in BCP 78 and BCP 79.

   Copies of IPR disclosures made to the IETF Secretariat and any
   assurances of licenses to be made available, or the result of an
   attempt made to obtain a general license or permission for the use of
   such proprietary rights by implementers or users of this
   specification can be obtained from the IETF on-line IPR repository at
   http://www.ietf.org/ipr.

   The IETF invites any interested party to bring to its attention any
   copyrights, patents or patent applications, or other proprietary
   rights that may cover technology that may be required to implement
   this standard.  Please address the information to the IETF at
   ietf-ipr@ietf.org.

Acknowledgement

   Funding for the RFC Editor function is currently provided by the
   Internet Society.







Siemborski & Melnikov       Standards Track                    [Page 20]



================================================
FILE: doc/notes/rfc/rfc5751.txt
================================================






Internet Engineering Task Force (IETF)                       B. Ramsdell
Request for Comments: 5751                              Brute Squad Labs
Obsoletes: 3851                                                S. Turner
Category: Standards Track                                           IECA
ISSN: 2070-1721                                             January 2010


   Secure/Multipurpose Internet Mail Extensions (S/MIME) Version 3.2
                         Message Specification

Abstract

   This document defines Secure/Multipurpose Internet Mail Extensions
   (S/MIME) version 3.2.  S/MIME provides a consistent way to send and
   receive secure MIME data.  Digital signatures provide authentication,
   message integrity, and non-repudiation with proof of origin.
   Encryption provides data confidentiality.  Compression can be used to
   reduce data size.  This document obsoletes RFC 3851.

Status of This Memo

   This is an Internet Standards Track document.

   This document is a product of the Internet Engineering Task Force
   (IETF).  It represents the consensus of the IETF community.  It has
   received public review and has been approved for publication by
   the Internet Engineering Steering Group (IESG).  Further
   information on Internet Standards is available in Section 2 of
   RFC 5741.

   Information about the current status of this document, any
   errata, and how to provide feedback on it may be obtained at
   http://www.rfc-editor.org/info/rfc5751.


















Ramsdell & Turner            Standards Track                    [Page 1]

RFC 5751            S/MIME 3.2 Message Specification        January 2010


Copyright Notice

   Copyright (c) 2010 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (http://trustee.ietf.org/license-info) in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.  Code Components extracted from this document must
   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

   This document may contain material from IETF Documents or IETF
   Contributions published or made publicly available before November
   10, 2008.  The person(s) controlling the copyright in some of this
   material may not have granted the IETF Trust the right to allow
   modifications of such material outside the IETF Standards Process.
   Without obtaining an adequate license from the person(s) controlling
   the copyright in such materials, this document may not be modified
   outside the IETF Standards Process, and derivative works of it may
   not be created outside the IETF Standards Process, except to format
   it for publication as an RFC or to translate it into languages other
   than English.

























Ramsdell & Turner            Standards Track                    [Page 2]

RFC 5751            S/MIME 3.2 Message Specification        January 2010


Table of Contents

   1. Introduction ....................................................4
      1.1. Specification Overview .....................................4
      1.2. Definitions ................................................5
      1.3. Conventions Used in This Document ..........................6
      1.4. Compatibility with Prior Practice of S/MIME ................7
      1.5. Changes from S/MIME v3 to S/MIME v3.1 ......................7
      1.6. Changes since S/MIME v3.1 ..................................7
   2. CMS Options .....................................................9
      2.1. DigestAlgorithmIdentifier ..................................9
      2.2. SignatureAlgorithmIdentifier ...............................9
      2.3. KeyEncryptionAlgorithmIdentifier ..........................10
      2.4. General Syntax ............................................11
      2.5. Attributes and the SignerInfo Type ........................12
      2.6. SignerIdentifier SignerInfo Type ..........................16
      2.7. ContentEncryptionAlgorithmIdentifier ......................16
   3. Creating S/MIME Messages .......................................18
      3.1. Preparing the MIME Entity for Signing, Enveloping,
           or Compressing ............................................19
      3.2. The application/pkcs7-mime Media Type .....................23
      3.3. Creating an Enveloped-Only Message ........................25
      3.4. Creating a Signed-Only Message ............................26
      3.5. Creating a Compressed-Only Message ........................30
      3.6. Multiple Operations .......................................30
      3.7. Creating a Certificate Management Message .................31
      3.8. Registration Requests .....................................32
      3.9. Identifying an S/MIME Message .............................32
   4. Certificate Processing .........................................32
      4.1. Key Pair Generation .......................................33
      4.2. Signature Generation ......................................33
      4.3. Signature Verification ....................................34
      4.4. Encryption ................................................34
      4.5. Decryption ................................................34
   5. IANA Considerations ............................................34
      5.1. Media Type for application/pkcs7-mime .....................34
      5.2. Media Type for application/pkcs7-signature ................35
   6. Security Considerations ........................................36
   7. References .....................................................38
      7.1. Reference Conventions .....................................38
      7.2. Normative References ......................................39
      7.3. Informative References ....................................41
   Appendix A. ASN.1 Module ..........................................43
   Appendix B. Moving S/MIME v2 Message Specification to Historic
               Status ................................................45
   Appendix C. Acknowledgments .......................................45





Ramsdell & Turner            Standards Track                    [Page 3]

RFC 5751            S/MIME 3.2 Message Specification        January 2010


1.  Introduction

   S/MIME (Secure/Multipurpose Internet Mail Extensions) provides a
   consistent way to send and receive secure MIME data.  Based on the
   popular Internet MIME standard, S/MIME provides the following
   cryptographic security services for electronic messaging
   applications:  authentication, message integrity and non-repudiation
   of origin (using digital signatures), and data confidentiality (using
   encryption).  As a supplementary service, S/MIME provides for message
   compression.

   S/MIME can be used by traditional mail user agents (MUAs) to add
   cryptographic security services to mail that is sent, and to
   interpret cryptographic security services in mail that is received.
   However, S/MIME is not restricted to mail; it can be used with any
   transport mechanism that transports MIME data, such as HTTP or SIP.
   As such, S/MIME takes advantage of the object-based features of MIME
   and allows secure messages to be exchanged in mixed-transport
   systems.

   Further, S/MIME can be used in automated message transfer agents that
   use cryptographic security services that do not require any human
   intervention, such as the signing of software-generated documents and
   the encryption of FAX messages sent over the Internet.

1.1.  Specification Overview

   This document describes a protocol for adding cryptographic signature
   and encryption services to MIME data.  The MIME standard [MIME-SPEC]
   provides a general structure for the content of Internet messages and
   allows extensions for new content-type-based applications.

   This specification defines how to create a MIME body part that has
   been cryptographically enhanced according to the Cryptographic
   Message Syntax (CMS) RFC 5652 [CMS], which is derived from PKCS #7
   [PKCS-7].  This specification also defines the application/pkcs7-mime
   media type that can be used to transport those body parts.

   This document also discusses how to use the multipart/signed media
   type defined in [MIME-SECURE] to transport S/MIME signed messages.
   multipart/signed is used in conjunction with the application/pkcs7-
   signature media type, which is used to transport a detached S/MIME
   signature.








Ramsdell & Turner            Standards Track                    [Page 4]

RFC 5751            S/MIME 3.2 Message Specification        January 2010


   In order to create S/MIME messages, an S/MIME agent MUST follow the
   specifications in this document, as well as the specifications listed
   in the Cryptographic Message Syntax document [CMS], [CMSALG],
   [RSAPSS], [RSAOAEP], and [CMS-SHA2].

   Throughout this specification, there are requirements and
   recommendations made for how receiving agents handle incoming
   messages.  There are separate requirements and recommendations for
   how sending agents create outgoing messages.  In general, the best
   strategy is to "be liberal in what you receive and conservative in
   what you send".  Most of the requirements are placed on the handling
   of incoming messages, while the recommendations are mostly on the
   creation of outgoing messages.

   The separation for requirements on receiving agents and sending
   agents also derives from the likelihood that there will be S/MIME
   systems that involve software other than traditional Internet mail
   clients.  S/MIME can be used with any system that transports MIME
   data.  An automated process that sends an encrypted message might not
   be able to receive an encrypted message at all, for example.  Thus,
   the requirements and recommendations for the two types of agents are
   listed separately when appropriate.

1.2.  Definitions

   For the purposes of this specification, the following definitions
   apply.

   ASN.1:             Abstract Syntax Notation One, as defined in ITU-T
                      Recommendation X.680 [X.680].

   BER:               Basic Encoding Rules for ASN.1, as defined in ITU-
                      T Recommendation X.690 [X.690].

   Certificate:       A type that binds an entity's name to a public key
                      with a digital signature.

   DER:               Distinguished Encoding Rules for ASN.1, as defined
                      in ITU-T Recommendation X.690 [X.690].

   7-bit data:        Text data with lines less than 998 characters
                      long, where none of the characters have the 8th
                      bit set, and there are no NULL characters.  <CR>
                      and <LF> occur only as part of a <CR><LF> end-of-
                      line delimiter.






Ramsdell & Turner            Standards Track                    [Page 5]

RFC 5751            S/MIME 3.2 Message Specification        January 2010


   8-bit data:        Text data with lines less than 998 characters, and
                      where none of the characters are NULL characters.
                      <CR> and <LF> occur only as part of a <CR><LF>
                      end-of-line delimiter.

   Binary data:       Arbitrary data.

   Transfer encoding: A reversible transformation made on data so 8-bit
                      or binary data can be sent via a channel that only
                      transmits 7-bit data.

   Receiving agent:   Software that interprets and processes S/MIME CMS
                      objects, MIME body parts that contain CMS content
                      types, or both.

   Sending agent:     Software that creates S/MIME CMS content types,
                      MIME body parts that contain CMS content types, or
                      both.

   S/MIME agent:      User software that is a receiving agent, a sending
                      agent, or both.

1.3.  Conventions Used in This Document

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in [MUSTSHOULD].

   We define some additional terms here:

   SHOULD+   This term means the same as SHOULD.  However, the authors
             expect that a requirement marked as SHOULD+ will be
             promoted at some future time to be a MUST.

   SHOULD-   This term means the same as SHOULD.  However, the authors
             expect that a requirement marked as SHOULD- will be demoted
             to a MAY in a future version of this document.

   MUST-     This term means the same as MUST.  However, the authors
             expect that this requirement will no longer be a MUST in a
             future document.  Although its status will be determined at
             a later time, it is reasonable to expect that if a future
             revision of a document alters the status of a MUST-
             requirement, it will remain at least a SHOULD or a SHOULD-.







Ramsdell & Turner            Standards Track                    [Page 6]

RFC 5751            S/MIME 3.2 Message Specification        January 2010


1.4.  Compatibility with Prior Practice of S/MIME

   S/MIME version 3.2 agents ought to attempt to have the greatest
   interoperability possible with agents for prior versions of S/MIME.
   S/MIME version 2 is described in RFC 2311 through RFC 2315 inclusive
   [SMIMEv2], S/MIME version 3 is described in RFC 2630 through RFC 2634
   inclusive and RFC 5035 [SMIMEv3], and S/MIME version 3.1 is described
   in RFC 3850, RFC 3851, RFC 3852, RFC 2634, and RFC 5035 [SMIMEv3.1].
   RFC 2311 also has historical information about the development of
   S/MIME.

1.5.  Changes from S/MIME v3 to S/MIME v3.1

   The RSA public key algorithm was changed to a MUST implement key
   wrapping algorithm, and the Diffie-Hellman (DH) algorithm changed to
   a SHOULD implement.

   The AES symmetric encryption algorithm has been included as a SHOULD
   implement.

   The RSA public key algorithm was changed to a MUST implement
   signature algorithm.

   Ambiguous language about the use of "empty" SignedData messages to
   transmit certificates was clarified to reflect that transmission of
   Certificate Revocation Lists is also allowed.

   The use of binary encoding for some MIME entities is now explicitly
   discussed.

   Header protection through the use of the message/rfc822 media type
   has been added.

   Use of the CompressedData CMS type is allowed, along with required
   media type and file extension additions.

1.6.  Changes since S/MIME v3.1

   Editorial changes, e.g., replaced "MIME type" with "media type",
   content-type with Content-Type.

   Moved "Conventions Used in This Document" to Section 1.3.  Added
   definitions for SHOULD+, SHOULD-, and MUST-.

   Section 1.1 and Appendix A: Added references to RFCs for RSASSA-PSS,
   RSAES-OAEP, and SHA2 CMS algorithms.  Added CMS Multiple Signers
   Clarification to CMS reference.




Ramsdell & Turner            Standards Track                    [Page 7]

RFC 5751            S/MIME 3.2 Message Specification        January 2010


   Section 1.2: Updated references to ASN.1 to X.680 and BER and DER to
   X.690.

   Section 1.4: Added references to S/MIME MSG 3.1 RFCs.

   Section 2.1 (digest algorithm): SHA-256 added as MUST, SHA-1 and MD5
   made SHOULD-.

   Section 2.2 (signature algorithms): RSA with SHA-256 added as MUST,
   and DSA with SHA-256 added as SHOULD+, RSA with SHA-1, DSA with
   SHA-1, and RSA with MD5 changed to SHOULD-, and RSASSA-PSS with
   SHA-256 added as SHOULD+.  Also added note about what S/MIME v3.1
   clients support.

   Section 2.3 (key encryption): DH changed to SHOULD-, and RSAES-OAEP
   added as SHOULD+.  Elaborated requirements for key wrap algorithm.

   Section 2.5.1: Added requirement that receiving agents MUST support
   both GeneralizedTime and UTCTime.

   Section 2.5.2: Replaced reference "sha1WithRSAEncryption" with
   "sha256WithRSAEncryption", "DES-3EDE-CBC" with "AES-128 CBC", and
   deleted the RC5 example.

   Section 2.5.2.1: Deleted entire section (discussed deprecated RC2).

   Section 2.7, 2.7.1, Appendix A: references to RC2/40 removed.

   Section 2.7 (content encryption): AES-128 CBC added as MUST, AES-192
   and AES-256 CBC SHOULD+, tripleDES now SHOULD-.

   Section 2.7.1: Updated pointers from 2.7.2.1 through 2.7.2.4 to
   2.7.1.1 to 2.7.1.2.

   Section 3.1.1: Removed text about MIME character sets.

   Section 3.2.2 and 3.6: Replaced "encrypted" with "enveloped".  Update
   OID example to use AES-128 CBC oid.

   Section 3.4.3.2: Replace micalg parameter for SHA-1 with sha-1.

   Section 4: Updated reference to CERT v3.2.

   Section 4.1: Updated RSA and DSA key size discussion.  Moved last
   four sentences to security considerations.  Updated reference to
   randomness requirements for security.





Ramsdell & Turner            Standards Track                    [Page 8]

RFC 5751            S/MIME 3.2 Message Specification        January 2010


   Section 5: Added IANA registration templates to update media type
   registry to point to this document as opposed to RFC 2311.

   Section 6: Updated security considerations.

   Section 7: Moved references from Appendix B to this section.  Updated
   references.  Added informational references to SMIMEv2, SMIMEv3, and
   SMIMEv3.1.

   Appendix B: Added Appendix B to move S/MIME v2 to Historic status.

2.  CMS Options

   CMS allows for a wide variety of options in content, attributes, and
   algorithm support.  This section puts forth a number of support
   requirements and recommendations in order to achieve a base level of
   interoperability among all S/MIME implementations.  [CMSALG] and
   [CMS-SHA2] provides additional details regarding the use of the
   cryptographic algorithms.  [ESS] provides additional details
   regarding the use of additional attributes.

2.1.  DigestAlgorithmIdentifier

   Sending and receiving agents MUST support SHA-256 [CMS-SHA2] and
   SHOULD- support SHA-1 [CMSALG].  Receiving agents SHOULD- support MD5
   [CMSALG] for the purpose of providing backward compatibility with
   MD5-digested S/MIME v2 SignedData objects.

2.2.  SignatureAlgorithmIdentifier

   Receiving agents:

      - MUST support RSA with SHA-256.

      - SHOULD+ support DSA with SHA-256.

      - SHOULD+ support RSASSA-PSS with SHA-256.

      - SHOULD- support RSA with SHA-1.

      - SHOULD- support DSA with SHA-1.

      - SHOULD- support RSA with MD5.








Ramsdell & Turner            Standards Track                    [Page 9]

RFC 5751            S/MIME 3.2 Message Specification        January 2010


   Sending agents:

      - MUST support RSA with SHA-256.

      - SHOULD+ support DSA with SHA-256.

      - SHOULD+ support RSASSA-PSS with SHA-256.

      - SHOULD- support RSA with SHA-1 or DSA with SHA-1.

      - SHOULD- support RSA with MD5.

   See Section 4.1 for information on key size and algorithm references.

   Note that S/MIME v3.1 clients support verifying id-dsa-with-sha1 and
   rsaEncryption and might not implement sha256withRSAEncryption.  Note
   that S/MIME v3 clients might only implement signing or signature
   verification using id-dsa-with-sha1, and might also use id-dsa as an
   AlgorithmIdentifier in this field.  Receiving clients SHOULD
   recognize id-dsa as equivalent to id-dsa-with-sha1, and sending
   clients MUST use id-dsa-with-sha1 if using that algorithm.  Also note
   that S/MIME v2 clients are only required to verify digital signatures
   using the rsaEncryption algorithm with SHA-1 or MD5, and might not
   implement id-dsa-with-sha1 or id-dsa at all.

2.3.  KeyEncryptionAlgorithmIdentifier

   Receiving and sending agents:

      - MUST support RSA Encryption, as specified in [CMSALG].

      - SHOULD+ support RSAES-OAEP, as specified in [RSAOAEP].

      - SHOULD- support DH ephemeral-static mode, as specified in
        [CMSALG] and [SP800-57].

   When DH ephemeral-static is used, a key wrap algorithm is also
   specified in the KeyEncryptionAlgorithmIdentifier [CMS].  The
   underlying encryption functions for the key wrap and content
   encryption algorithm ([CMSALG] and [CMSAES]) and the key sizes for
   the two algorithms MUST be the same (e.g., AES-128 key wrap algorithm
   with AES-128 content encryption algorithm).  As AES-128 CBC is the
   mandatory-to-implement content encryption algorithm, the AES-128 key
   wrap algorithm MUST also be supported when DH ephemeral-static is
   used.






Ramsdell & Turner            Standards Track                   [Page 10]

RFC 5751            S/MIME 3.2 Message Specification        January 2010


   Note that S/MIME v3.1 clients might only implement key encryption and
   decryption using the rsaEncryption algorithm.  Note that S/MIME v3
   clients might only implement key encryption and decryption using the
   Diffie-Hellman algorithm.  Also note that S/MIME v2 clients are only
   capable of decrypting content-encryption keys using the rsaEncryption
   algorithm.

2.4.  General Syntax

   There are several CMS content types.  Of these, only the Data,
   SignedData, EnvelopedData, and CompressedData content types are
   currently used for S/MIME.

2.4.1.  Data Content Type

   Sending agents MUST use the id-data content type identifier to
   identify the "inner" MIME message content.  For example, when
   applying a digital signature to MIME data, the CMS SignedData
   encapContentInfo eContentType MUST include the id-data object
   identifier and the media type MUST be stored in the SignedData
   encapContentInfo eContent OCTET STRING (unless the sending agent is
   using multipart/signed, in which case the eContent is absent, per
   Section 3.4.3 of this document).  As another example, when applying
   encryption to MIME data, the CMS EnvelopedData encryptedContentInfo
   contentType MUST include the id-data object identifier and the
   encrypted MIME content MUST be stored in the EnvelopedData
   encryptedContentInfo encryptedContent OCTET STRING.

2.4.2.  SignedData Content Type

   Sending agents MUST use the SignedData content type to apply a
   digital signature to a message or, in a degenerate case where there
   is no signature information, to convey certificates.  Applying a
   signature to a message provides authentication, message integrity,
   and non-repudiation of origin.

2.4.3.  EnvelopedData Content Type

   This content type is used to apply data confidentiality to a message.
   A sender needs to have access to a public key for each intended
   message recipient to use this service.

2.4.4.  CompressedData Content Type

   This content type is used to apply data compression to a message.
   This content type does not provide authentication, message integrity,
   non-repudiation, or data confidentiality, and is only used to reduce
   the message's size.



Ramsdell & Turner            Standards Track                   [Page 11]

RFC 5751            S/MIME 3.2 Message Specification        January 2010


   See Section 3.6 for further guidance on the use of this type in
   conjunction with other CMS types.

2.5.  Attributes and the SignerInfo Type

   The SignerInfo type allows the inclusion of unsigned and signed
   attributes along with a signature.

   Receiving agents MUST be able to handle zero or one instance of each
   of the signed attributes listed here.  Sending agents SHOULD generate
   one instance of each of the following signed attributes in each
   S/MIME message:

      - Signing Time (section (Section 2.5.1 in this document)

      - SMIME Capabilities (section (Section 2.5.2 in this document)

      - Encryption Key Preference (section (Section 2.5.3 in this
        document)

      - Message Digest (section (Section 11.2 in [CMS])

      - Content Type (section (Section 11.1 in [CMS])

   Further, receiving agents SHOULD be able to handle zero or one
   instance of the signingCertificate and signingCertificatev2 signed
   attributes, as defined in Section 5 of RFC 2634 [ESS] and Section 3
   of RFC 5035 [ESS].

   Sending agents SHOULD generate one instance of the signingCertificate
   or signingCertificatev2 signed attribute in each SignerInfo
   structure.

   Additional attributes and values for these attributes might be
   defined in the future.  Receiving agents SHOULD handle attributes or
   values that they do not recognize in a graceful manner.

   Interactive sending agents that include signed attributes that are
   not listed here SHOULD display those attributes to the user, so that
   the user is aware of all of the data being signed.

2.5.1.  Signing Time Attribute

   The signing-time attribute is used to convey the time that a message
   was signed.  The time of signing will most likely be created by a
   message originator and therefore is only as trustworthy as the
   originator.




Ramsdell & Turner            Standards Track                   [Page 12]

RFC 5751            S/MIME 3.2 Message Specification        January 2010


   Sending agents MUST encode signing time through the year 2049 as
   UTCTime; signing times in 2050 or later MUST be encoded as
   GeneralizedTime.  When the UTCTime CHOICE is used, S/MIME agents MUST
   interpret the year field (YY) as follows:

      If YY is greater than or equal to 50, the year is interpreted as
      19YY; if YY is less than 50, the year is interpreted as 20YY.

   Receiving agents MUST be able to process signing-time attributes that
   are encoded in either UTCTime or GeneralizedTime.

2.5.2.  SMIME Capabilities Attribute

   The SMIMECapabilities attribute includes signature algorithms (such
   as "sha256WithRSAEncryption"), symmetric algorithms (such as "AES-128
   CBC"), and key encipherment algorithms (such as "rsaEncryption").
   There are also several identifiers that indicate support for other
   optional features such as binary encoding and compression.  The
   SMIMECapabilities were designed to be flexible and extensible so
   that, in the future, a means of identifying other capabilities and
   preferences such as certificates can be added in a way that will not
   cause current clients to break.

   If present, the SMIMECapabilities attribute MUST be a
   SignedAttribute; it MUST NOT be an UnsignedAttribute.  CMS defines
   SignedAttributes as a SET OF Attribute.  The SignedAttributes in a
   signerInfo MUST NOT include multiple instances of the
   SMIMECapabilities attribute.  CMS defines the ASN.1 syntax for
   Attribute to include attrValues SET OF AttributeValue.  A
   SMIMECapabilities attribute MUST only include a single instance of
   AttributeValue.  There MUST NOT be zero or multiple instances of
   AttributeValue present in the attrValues SET OF AttributeValue.

   The semantics of the SMIMECapabilities attribute specify a partial
   list as to what the client announcing the SMIMECapabilities can
   support.  A client does not have to list every capability it
   supports, and need not list all its capabilities so that the
   capabilities list doesn't get too long.  In an SMIMECapabilities
   attribute, the object identifiers (OIDs) are listed in order of their
   preference, but SHOULD be separated logically along the lines of
   their categories (signature algorithms, symmetric algorithms, key
   encipherment algorithms, etc.).

   The structure of the SMIMECapabilities attribute is to facilitate
   simple table lookups and binary comparisons in order to determine
   matches.  For instance, the DER-encoding for the SMIMECapability for
   AES-128 CBC MUST be identically encoded regardless of the
   implementation.  Because of the requirement for identical encoding,



Ramsdell & Turner            Standards Track                   [Page 13]

RFC 5751            S/MIME 3.2 Message Specification        January 2010


   individuals documenting algorithms to be used in the
   SMIMECapabilities attribute SHOULD explicitly document the correct
   byte sequence for the common cases.

   For any capability, the associated parameters for the OID MUST
   specify all of the parameters necessary to differentiate between two
   instances of the same algorithm.

   The OIDs that correspond to algorithms SHOULD use the same OID as the
   actual algorithm, except in the case where the algorithm usage is
   ambiguous from the OID.  For instance, in an earlier specification,
   rsaEncryption was ambiguous because it could refer to either a
   signature algorithm or a key encipherment algorithm.  In the event
   that an OID is ambiguous, it needs to be arbitrated by the maintainer
   of the registered SMIMECapabilities list as to which type of
   algorithm will use the OID, and a new OID MUST be allocated under the
   smimeCapabilities OID to satisfy the other use of the OID.

   The registered SMIMECapabilities list specifies the parameters for
   OIDs that need them, most notably key lengths in the case of
   variable-length symmetric ciphers.  In the event that there are no
   differentiating parameters for a particular OID, the parameters MUST
   be omitted, and MUST NOT be encoded as NULL.  Additional values for
   the SMIMECapabilities attribute might be defined in the future.
   Receiving agents MUST handle a SMIMECapabilities object that has
   values that it does not recognize in a graceful manner.

   Section 2.7.1 explains a strategy for caching capabilities.

2.5.3.  Encryption Key Preference Attribute

   The encryption key preference attribute allows the signer to
   unambiguously describe which of the signer's certificates has the
   signer's preferred encryption key.  This attribute is designed to
   enhance behavior for interoperating with those clients that use
   separate keys for encryption and signing.  This attribute is used to
   convey to anyone viewing the attribute which of the listed
   certificates is appropriate for encrypting a session key for future
   encrypted messages.

   If present, the SMIMEEncryptionKeyPreference attribute MUST be a
   SignedAttribute; it MUST NOT be an UnsignedAttribute.  CMS defines
   SignedAttributes as a SET OF Attribute.  The SignedAttributes in a
   signerInfo MUST NOT include multiple instances of the
   SMIMEEncryptionKeyPreference attribute.  CMS defines the ASN.1 syntax
   for Attribute to include attrValues SET OF AttributeValue.  A
   SMIMEEncryptionKeyPreference attribute MUST only include a single




Ramsdell & Turner            Standards Track                   [Page 14]

RFC 5751            S/MIME 3.2 Message Specification        January 2010


   instance of AttributeValue.  There MUST NOT be zero or multiple
   instances of AttributeValue present in the attrValues SET OF
   AttributeValue.

   The sending agent SHOULD include the referenced certificate in the
   set of certificates included in the signed message if this attribute
   is used.  The certificate MAY be omitted if it has been previously
   made available to the receiving agent.  Sending agents SHOULD use
   this attribute if the commonly used or preferred encryption
   certificate is not the same as the certificate used to sign the
   message.

   Receiving agents SHOULD store the preference data if the signature on
   the message is valid and the signing time is greater than the
   currently stored value.  (As with the SMIMECapabilities, the clock
   skew SHOULD be checked and the data not used if the skew is too
   great.)  Receiving agents SHOULD respect the sender's encryption key
   preference attribute if possible.  This, however, represents only a
   preference and the receiving agent can use any certificate in
   replying to the sender that is valid.

   Section 2.7.1 explains a strategy for caching preference data.

2.5.3.1.  Selection of Recipient Key Management Certificate

   In order to determine the key management certificate to be used when
   sending a future CMS EnvelopedData message for a particular
   recipient, the following steps SHOULD be followed:

   - If an SMIMEEncryptionKeyPreference attribute is found in a
     SignedData object received from the desired recipient, this
     identifies the X.509 certificate that SHOULD be used as the X.509
     key management certificate for the recipient.

   - If an SMIMEEncryptionKeyPreference attribute is not found in a
     SignedData object received from the desired recipient, the set of
     X.509 certificates SHOULD be searched for a X.509 certificate with
     the same subject name as the signer of a X.509 certificate that can
     be used for key management.

   - Or use some other method of determining the user's key management
     key.  If a X.509 key management certificate is not found, then
     encryption cannot be done with the signer of the message.  If
     multiple X.509 key management certificates are found, the S/MIME
     agent can make an arbitrary choice between them.






Ramsdell & Turner            Standards Track                   [Page 15]

RFC 5751            S/MIME 3.2 Message Specification        January 2010


2.6.  SignerIdentifier SignerInfo Type

   S/MIME v3.2 implementations MUST support both issuerAndSerialNumber
   and subjectKeyIdentifier.  Messages that use the subjectKeyIdentifier
   choice cannot be read by S/MIME v2 clients.

   It is important to understand that some certificates use a value for
   subjectKeyIdentifier that is not suitable for uniquely identifying a
   certificate.  Implementations MUST be prepared for multiple
   certificates for potentially different entities to have the same
   value for subjectKeyIdentifier, and MUST be prepared to try each
   matching certificate during signature verification before indicating
   an error condition.

2.7.  ContentEncryptionAlgorithmIdentifier

   Sending and receiving agents:

      - MUST support encryption and decryption with AES-128 CBC
        [CMSAES].

      - SHOULD+ support encryption and decryption with AES-192 CBC and
        AES-256 CBC [CMSAES].

      - SHOULD- support encryption and decryption with DES EDE3 CBC,
        hereinafter called "tripleDES" [CMSALG].

2.7.1.  Deciding Which Encryption Method to Use

   When a sending agent creates an encrypted message, it has to decide
   which type of encryption to use.  The decision process involves using
   information garnered from the capabilities lists included in messages
   received from the recipient, as well as out-of-band information such
   as private agreements, user preferences, legal restrictions, and so
   on.

   Section 2.5.2 defines a method by which a sending agent can
   optionally announce, among other things, its decrypting capabilities
   in its order of preference.  The following method for processing and
   remembering the encryption capabilities attribute in incoming signed
   messages SHOULD be used.

      - If the receiving agent has not yet created a list of
        capabilities for the sender's public key, then, after verifying
        the signature on the incoming message and checking the
        timestamp, the receiving agent SHOULD create a new list
        containing at least the signing time and the symmetric
        capabilities.



Ramsdell & Turner            Standards Track                   [Page 16]

RFC 5751            S/MIME 3.2 Message Specification        January 2010


      - If such a list already exists, the receiving agent SHOULD verify
        that the signing time in the incoming message is greater than
        the signing time stored in the list and that the signature is
        valid.  If so, the receiving agent SHOULD update both the
        signing time and capabilities in the list.  Values of the
        signing time that lie far in the future (that is, a greater
        discrepancy than any reasonable clock skew), or a capabilities
        list in messages whose signature could not be verified, MUST NOT
        be accepted.

   The list of capabilities SHOULD be stored for future use in creating
   messages.

   Before sending a message, the sending agent MUST decide whether it is
   willing to use weak encryption for the particular data in the
   message.  If the sending agent decides that weak encryption is
   unacceptable for this data, then the sending agent MUST NOT use a
   weak algorithm.  The decision to use or not use weak encryption
   overrides any other decision in this section about which encryption
   algorithm to use.

   Sections 2.7.1.1 through 2.7.1.2 describe the decisions a sending
   agent SHOULD use in deciding which type of encryption will be applied
   to a message.  These rules are ordered, so the sending agent SHOULD
   make its decision in the order given.

2.7.1.1.  Rule 1: Known Capabilities

   If the sending agent has received a set of capabilities from the
   recipient for the message the agent is about to encrypt, then the
   sending agent SHOULD use that information by selecting the first
   capability in the list (that is, the capability most preferred by the
   intended recipient) that the sending agent knows how to encrypt.  The
   sending agent SHOULD use one of the capabilities in the list if the
   agent reasonably expects the recipient to be able to decrypt the
   message.

2.7.1.2.  Rule 2: Unknown Capabilities, Unknown Version of S/MIME

   If the following two conditions are met:

      - the sending agent has no knowledge of the encryption
        capabilities of the recipient, and

      - the sending agent has no knowledge of the version of S/MIME of
        the recipient,





Ramsdell & Turner            Standards Track                   [Page 17]

RFC 5751            S/MIME 3.2 Message Specification        January 2010


   then the sending agent SHOULD use AES-128 because it is a stronger
   algorithm and is required by S/MIME v3.2.  If the sending agent
   chooses not to use AES-128 in this step, it SHOULD use tripleDES.

2.7.2.  Choosing Weak Encryption

   All algorithms that use 40-bit keys are considered by many to be weak
   encryption.  A sending agent that is controlled by a human SHOULD
   allow a human sender to determine the risks of sending data using a
   weak encryption algorithm before sending the data, and possibly allow
   the human to use a stronger encryption method such as tripleDES or
   AES.

2.7.3.  Multiple Recipients

   If a sending agent is composing an encrypted message to a group of
   recipients where the encryption capabilities of some of the
   recipients do not overlap, the sending agent is forced to send more
   than one message.  Please note that if the sending agent chooses to
   send a message encrypted with a strong algorithm, and then send the
   same message encrypted with a weak algorithm, someone watching the
   communications channel could learn the contents of the strongly
   encrypted message simply by decrypting the weakly encrypted message.

3.  Creating S/MIME Messages

   This section describes the S/MIME message formats and how they are
   created.  S/MIME messages are a combination of MIME bodies and CMS
   content types.  Several media types as well as several CMS content
   types are used.  The data to be secured is always a canonical MIME
   entity.  The MIME entity and other data, such as certificates and
   algorithm identifiers, are given to CMS processing facilities that
   produce a CMS object.  Finally, the CMS object is wrapped in MIME.
   The Enhanced Security Services for S/MIME [ESS] document provides
   descriptions of how nested, secured S/MIME messages are formatted.
   ESS provides a description of how a triple-wrapped S/MIME message is
   formatted using multipart/signed and application/pkcs7-mime for the
   signatures.

   S/MIME provides one format for enveloped-only data, several formats
   for signed-only data, and several formats for signed and enveloped
   data.  Several formats are required to accommodate several
   environments, in particular for signed messages.  The criteria for
   choosing among these formats are also described.

   The reader of this section is expected to understand MIME as
   described in [MIME-SPEC] and [MIME-SECURE].




Ramsdell & Turner            Standards Track                   [Page 18]

RFC 5751            S/MIME 3.2 Message Specification        January 2010


3.1.  Preparing the MIME Entity for Signing, Enveloping, or Compressing

   S/MIME is used to secure MIME entities.  A MIME entity can be a sub-
   part, sub-parts of a message, or the whole message with all its sub-
   parts.  A MIME entity that is the whole message includes only the
   MIME message headers and MIME body, and does not include the RFC-822
   header.  Note that S/MIME can also be used to secure MIME entities
   used in applications other than Internet mail.  If protection of the
   RFC-822 header is required, the use of the message/rfc822 media type
   is explained later in this section.

   The MIME entity that is secured and described in this section can be
   thought of as the "inside" MIME entity.  That is, it is the
   "innermost" object in what is possibly a larger MIME message.
   Processing "outside" MIME entities into CMS content types is
   described in Sections 3.2, 3.4, and elsewhere.

   The procedure for preparing a MIME entity is given in [MIME-SPEC].
   The same procedure is used here with some additional restrictions
   when signing.  The description of the procedures from [MIME-SPEC] is
   repeated here, but it is suggested that the reader refer to that
   document for the exact procedure.  This section also describes
   additional requirements.

   A single procedure is used for creating MIME entities that are to
   have any combination of signing, enveloping, and compressing applied.
   Some additional steps are recommended to defend against known
   corruptions that can occur during mail transport that are of
   particular importance for clear-signing using the multipart/signed
   format.  It is recommended that these additional steps be performed
   on enveloped messages, or signed and enveloped messages, so that the
   message can be forwarded to any environment without modification.

   These steps are descriptive rather than prescriptive.  The
   implementer is free to use any procedure as long as the result is the
   same.

   Step 1.  The MIME entity is prepared according to the local
            conventions.

   Step 2.  The leaf parts of the MIME entity are converted to canonical
            form.

   Step 3.  Appropriate transfer encoding is applied to the leaves of
            the MIME entity.






Ramsdell & Turner            Standards Track                   [Page 19]

RFC 5751            S/MIME 3.2 Message Specification        January 2010


   When an S/MIME message is received, the security services on the
   message are processed, and the result is the MIME entity.  That MIME
   entity is typically passed to a MIME-capable user agent where it is
   further decoded and presented to the user or receiving application.

   In order to protect outer, non-content-related message header fields
   (for instance, the "Subject", "To", "From", and "Cc" fields), the
   sending client MAY wrap a full MIME message in a message/rfc822
   wrapper in order to apply S/MIME security services to these header
   fields.  It is up to the receiving client to decide how to present
   this "inner" header along with the unprotected "outer" header.

   When an S/MIME message is received, if the top-level protected MIME
   entity has a Content-Type of message/rfc822, it can be assumed that
   the intent was to provide header protection.  This entity SHOULD be
   presented as the top-level message, taking into account header
   merging issues as previously discussed.

3.1.1.  Canonicalization

   Each MIME entity MUST be converted to a canonical form that is
   uniquely and unambiguously representable in the environment where the
   signature is created and the environment where the signature will be
   verified.  MIME entities MUST be canonicalized for enveloping and
   compressing as well as signing.

   The exact details of canonicalization depend on the actual media type
   and subtype of an entity, and are not described here.  Instead, the
   standard for the particular media type SHOULD be consulted.  For
   example, canonicalization of type text/plain is different from
   canonicalization of audio/basic.  Other than text types, most types
   have only one representation regardless of computing platform or
   environment that can be considered their canonical representation.
   In general, canonicalization will be performed by the non-security
   part of the sending agent rather than the S/MIME implementation.

   The most common and important canonicalization is for text, which is
   often represented differently in different environments.  MIME
   entities of major type "text" MUST have both their line endings and
   character set canonicalized.  The line ending MUST be the pair of
   characters <CR><LF>, and the charset SHOULD be a registered charset
   [CHARSETS].  The details of the canonicalization are specified in
   [MIME-SPEC].

   Note that some charsets such as ISO-2022 have multiple
   representations for the same characters.  When preparing such text
   for signing, the canonical representation specified for the charset
   MUST be used.



Ramsdell & Turner            Standards Track                   [Page 20]

RFC 5751            S/MIME 3.2 Message Specification        January 2010


3.1.2.  Transfer Encoding

   When generating any of the secured MIME entities below, except the
   signing using the multipart/signed format, no transfer encoding is
   required at all.  S/MIME implementations MUST be able to deal with
   binary MIME objects.  If no Content-Transfer-Encoding header field is
   present, the transfer encoding is presumed to be 7BIT.

   S/MIME implementations SHOULD however use transfer encoding described
   in Section 3.1.3 for all MIME entities they secure.  The reason for
   securing only 7-bit MIME entities, even for enveloped data that are
   not exposed to the transport, is that it allows the MIME entity to be
   handled in any environment without changing it.  For example, a
   trusted gateway might remove the envelope, but not the signature, of
   a message, and then forward the signed message on to the end
   recipient so that they can verify the signatures directly.  If the
   transport internal to the site is not 8-bit clean, such as on a wide-
   area network with a single mail gateway, verifying the signature will
   not be possible unless the original MIME entity was only 7-bit data.

   S/MIME implementations that "know" that all intended recipients are
   capable of handling inner (all but the outermost) binary MIME objects
   SHOULD use binary encoding as opposed to a 7-bit-safe transfer
   encoding for the inner entities.  The use of a 7-bit-safe encoding
   (such as base64) would unnecessarily expand the message size.
   Implementations MAY "know" that recipient implementations are capable
   of handling inner binary MIME entities either by interpreting the id-
   cap-preferBinaryInside SMIMECapabilities attribute, by prior
   agreement, or by other means.

   If one or more intended recipients are unable to handle inner binary
   MIME objects, or if this capability is unknown for any of the
   intended recipients, S/MIME implementations SHOULD use transfer
   encoding described in Section 3.1.3 for all MIME entities they
   secure.

3.1.3.  Transfer Encoding for Signing Using multipart/signed

   If a multipart/signed entity is ever to be transmitted over the
   standard Internet SMTP infrastructure or other transport that is
   constrained to 7-bit text, it MUST have transfer encoding applied so
   that it is represented as 7-bit text.  MIME entities that are 7-bit
   data already need no transfer encoding.  Entities such as 8-bit text
   and binary data can be encoded with quoted-printable or base-64
   transfer encoding.






Ramsdell & Turner            Standards Track                   [Page 21]

RFC 5751            S/MIME 3.2 Message Specification        January 2010


   The primary reason for the 7-bit requirement is that the Internet
   mail transport infrastructure cannot guarantee transport of 8-bit or
   binary data.  Even though many segments of the transport
   infrastructure now handle 8-bit and even binary data, it is sometimes
   not possible to know whether the transport path is 8-bit clean.  If a
   mail message with 8-bit data were to encounter a message transfer
   agent that cannot transmit 8-bit or binary data, the agent has three
   options, none of which are acceptable for a clear-signed message:

    - The agent could change the transfer encoding; this would
      invalidate the signature.

    - The agent could transmit the data anyway, which would most likely
      result in the 8th bit being corrupted; this too would invalidate
      the signature.

    - The agent could return the message to the sender.

   [MIME-SECURE] prohibits an agent from changing the transfer encoding
   of the first part of a multipart/signed message.  If a compliant
   agent that cannot transmit 8-bit or binary data encounters a
   multipart/signed message with 8-bit or binary data in the first part,
   it would have to return the message to the sender as undeliverable.

3.1.4.  Sample Canonical MIME Entity

   This example shows a multipart/mixed message with full transfer
   encoding.  This message contains a text part and an attachment.  The
   sample message text includes characters that are not US-ASCII and
   thus need to be transfer encoded.  Though not shown here, the end of
   each line is <CR><LF>.  The line ending of the MIME headers, the
   text, and the transfer encoded parts, all MUST be <CR><LF>.

   Note that this example is not of an S/MIME message.

      Content-Type: multipart/mixed; boundary=bar

      --bar
      Content-Type: text/plain; charset=iso-8859-1
      Content-Transfer-Encoding: quoted-printable

      =A1Hola Michael!

      How do you like the new S/MIME specification?

      It's generally a good idea to encode lines that begin with
      From=20because some mail transport agents will insert a greater-
      than (>) sign, thus invalidating the signature.



Ramsdell & Turner            Standards Track                   [Page 22]

RFC 5751            S/MIME 3.2 Message Specification        January 2010


      Also, in some cases it might be desirable to encode any =20
      trailing whitespace that occurs on lines in order to ensure =20
      that the message signature is not invalidated when passing =20
      a gateway that modifies such whitespace (like BITNET). =20

      --bar
      Content-Type: image/jpeg
      Content-Transfer-Encoding: base64

      iQCVAwUBMJrRF2N9oWBghPDJAQE9UQQAtl7LuRVndBjrk4EqYBIb3h5QXIX/LC//
      jJV5bNvkZIGPIcEmI5iFd9boEgvpirHtIREEqLQRkYNoBActFBZmh9GC3C041WGq
      uMbrbxc+nIs1TIKlA08rVi9ig/2Yh7LFrK5Ein57U/W72vgSxLhe/zhdfolT9Brn
      HOxEa44b+EI=

      --bar--

3.2.  The application/pkcs7-mime Media Type

   The application/pkcs7-mime media type is used to carry CMS content
   types including EnvelopedData, SignedData, and CompressedData.  The
   details of constructing these entities are described in subsequent
   sections.  This section describes the general characteristics of the
   application/pkcs7-mime media type.

   The carried CMS object always contains a MIME entity that is prepared
   as described in Section 3.1 if the eContentType is id-data.  Other
   contents MAY be carried when the eContentType contains different
   values.  See [ESS] for an example of this with signed receipts.

   Since CMS content types are binary data, in most cases base-64
   transfer encoding is appropriate, in particular, when used with SMTP
   transport.  The transfer encoding used depends on the transport
   through which the object is to be sent, and is not a characteristic
   of the media type.

   Note that this discussion refers to the transfer encoding of the CMS
   object or "outside" MIME entity.  It is completely distinct from, and
   unrelated to, the transfer encoding of the MIME entity secured by the
   CMS object, the "inside" object, which is described in Section 3.1.

   Because there are several types of application/pkcs7-mime objects, a
   sending agent SHOULD do as much as possible to help a receiving agent
   know about the contents of the object without forcing the receiving
   agent to decode the ASN.1 for the object.  The Content-Type header
   field of all application/pkcs7-mime objects SHOULD include the
   optional "smime-type" parameter, as described in the following
   sections.




Ramsdell & Turner            Standards Track                   [Page 23]

RFC 5751            S/MIME 3.2 Message Specification        January 2010


3.2.1.  The name and filename Parameters

   For the application/pkcs7-mime, sending agents SHOULD emit the
   optional "name" parameter to the Content-Type field for compatibility
   with older systems.  Sending agents SHOULD also emit the optional
   Content-Disposition field [CONTDISP] with the "filename" parameter.
   If a sending agent emits the above parameters, the value of the
   parameters SHOULD be a file name with the appropriate extension:

   Media Type                                            File Extension
     application/pkcs7-mime (SignedData, EnvelopedData)      .p7m
     application/pkcs7-mime (degenerate SignedData           .p7c
        certificate management message)
     application/pkcs7-mime (CompressedData)                 .p7z
     application/pkcs7-signature (SignedData)                .p7s

   In addition, the file name SHOULD be limited to eight characters
   followed by a three-letter extension.  The eight-character filename
   base can be any distinct name; the use of the filename base "smime"
   SHOULD be used to indicate that the MIME entity is associated with
   S/MIME.

   Including a file name serves two purposes.  It facilitates easier use
   of S/MIME objects as files on disk.  It also can convey type
   information across gateways.  When a MIME entity of type
   application/pkcs7-mime (for example) arrives at a gateway that has no
   special knowledge of S/MIME, it will default the entity's media type
   to application/octet-stream and treat it as a generic attachment,
   thus losing the type information.  However, the suggested filename
   for an attachment is often carried across a gateway.  This often
   allows the receiving systems to determine the appropriate application
   to hand the attachment off to, in this case, a stand-alone S/MIME
   processing application.  Note that this mechanism is provided as a
   convenience for implementations in certain environments.  A proper
   S/MIME implementation MUST use the media types and MUST NOT rely on
   the file extensions.

3.2.2.  The smime-type Parameter

   The application/pkcs7-mime content type defines the optional "smime-
   type" parameter.  The intent of this parameter is to convey details
   about the security applied (signed or enveloped) along with
   information about the contained content.  This specification defines
   the following smime-types.







Ramsdell & Turner            Standards Track                   [Page 24]

RFC 5751            S/MIME 3.2 Message Specification        January 2010


      Name                   CMS Type                Inner Content
      enveloped-data         EnvelopedData           id-data
      signed-data            SignedData              id-data
      certs-only             SignedData              none
      compressed-data        CompressedData          id-data

   In order for consistency to be obtained with future specifications,
   the following guidelines SHOULD be followed when assigning a new
   smime-type parameter.

      1. If both signing and encryption can be applied to the content,
         then two values for smime-type SHOULD be assigned "signed-*"
         and "enveloped-*".  If one operation can be assigned, then this
         can be omitted.  Thus, since "certs-only" can only be signed,
         "signed-" is omitted.

      2. A common string for a content OID SHOULD be assigned.  We use
         "data" for the id-data content OID when MIME is the inner
         content.

      3. If no common string is assigned, then the common string of
         "OID.<oid>" is recommended (for example,
         "OID.2.16.840.1.101.3.4.1.2" would be AES-128 CBC).

   It is explicitly intended that this field be a suitable hint for mail
   client applications to indicate whether a message is "signed" or
   "enveloped" without having to tunnel into the CMS payload.

3.3.  Creating an Enveloped-Only Message

   This section describes the format for enveloping a MIME entity
   without signing it.  It is important to note that sending enveloped
   but not signed messages does not provide for data integrity.  It is
   possible to replace ciphertext in such a way that the processed
   message will still be valid, but the meaning can be altered.

   Step 1.  The MIME entity to be enveloped is prepared according to
            Section 3.1.

   Step 2.  The MIME entity and other required data is processed into a
            CMS object of type EnvelopedData.  In addition to encrypting
            a copy of the content-encryption key for each recipient, a
            copy of the content-encryption key SHOULD be encrypted for
            the originator and included in the EnvelopedData (see [CMS],
            Section 6).

   Step 3.  The EnvelopedData object is wrapped in a CMS ContentInfo
            object.



Ramsdell & Turner            Standards Track                   [Page 25]

RFC 5751            S/MIME 3.2 Message Specification        January 2010


   Step 4.  The ContentInfo object is inserted into an
            application/pkcs7-mime MIME entity.

   The smime-type parameter for enveloped-only messages is "enveloped-
   data".  The file extension for this type of message is ".p7m".

   A sample message would be:

      Content-Type: application/pkcs7-mime; smime-type=enveloped-data;
           name=smime.p7m
      Content-Transfer-Encoding: base64
      Content-Disposition: attachment; filename=smime.p7m

      rfvbnj756tbBghyHhHUujhJhjH77n8HHGT9HG4VQpfyF467GhIGfHfYT6
      7n8HHGghyHhHUujhJh4VQpfyF467GhIGfHfYGTrfvbnjT6jH7756tbB9H
      f8HHGTrfvhJhjH776tbB9HG4VQbnj7567GhIGfHfYT6ghyHhHUujpfyF4
      0GhIGfHfQbnj756YT64V

3.4.  Creating a Signed-Only Message

   There are two formats for signed messages defined for S/MIME:

      - application/pkcs7-mime with SignedData.

      - multipart/signed.

   In general, the multipart/signed form is preferred for sending, and
   receiving agents MUST be able to handle both.

3.4.1.  Choosing a Format for Signed-Only Messages

   There are no hard-and-fast rules as to when a particular signed-only
   format is chosen.  It depends on the capabilities of all the
   receivers and the relative importance of receivers with S/MIME
   facilities being able to verify the signature versus the importance
   of receivers without S/MIME software being able to view the message.

   Messages signed using the multipart/signed format can always be
   viewed by the receiver whether or not they have S/MIME software.
   They can also be viewed whether they are using a MIME-native user
   agent or they have messages translated by a gateway.  In this
   context, "be viewed" means the ability to process the message
   essentially as if it were not a signed message, including any other
   MIME structure the message might have.







Ramsdell & Turner            Standards Track                   [Page 26]

RFC 5751            S/MIME 3.2 Message Specification        January 2010


   Messages signed using the SignedData format cannot be viewed by a
   recipient unless they have S/MIME facilities.  However, the
   SignedData format protects the message content from being changed by
   benign intermediate agents.  Such agents might do line wrapping or
   content-transfer encoding changes that would break the signature.

3.4.2.  Signing Using application/pkcs7-mime with SignedData

   This signing format uses the application/pkcs7-mime media type.  The
   steps to create this format are:

   Step 1.  The MIME entity is prepared according to Section 3.1.

   Step 2.  The MIME entity and other required data are processed into a
            CMS object of type SignedData.

   Step 3.  The SignedData object is wrapped in a CMS ContentInfo
            object.

   Step 4.  The ContentInfo object is inserted into an
            application/pkcs7-mime MIME entity.

   The smime-type parameter for messages using application/pkcs7-mime
   with SignedData is "signed-data".  The file extension for this type
   of message is ".p7m".

   A sample message would be:

      Content-Type: application/pkcs7-mime; smime-type=signed-data;
           name=smime.p7m
      Content-Transfer-Encoding: base64
      Content-Disposition: attachment; filename=smime.p7m

      567GhIGfHfYT6ghyHhHUujpfyF4f8HHGTrfvhJhjH776tbB9HG4VQbnj7
      77n8HHGT9HG4VQpfyF467GhIGfHfYT6rfvbnj756tbBghyHhHUujhJhjH
      HUujhJh4VQpfyF467GhIGfHfYGTrfvbnjT6jH7756tbB9H7n8HHGghyHh
      6YT64V0GhIGfHfQbnj75

3.4.3.  Signing Using the multipart/signed Format

   This format is a clear-signing format.  Recipients without any S/MIME
   or CMS processing facilities are able to view the message.  It makes
   use of the multipart/signed media type described in [MIME-SECURE].
   The multipart/signed media type has two parts.  The first part
   contains the MIME entity that is signed; the second part contains the
   "detached signature" CMS SignedData object in which the
   encapContentInfo eContent field is absent.




Ramsdell & Turner            Standards Track                   [Page 27]

RFC 5751            S/MIME 3.2 Message Specification        January 2010


3.4.3.1.  The application/pkcs7-signature Media Type

   This media type always contains a CMS ContentInfo containing a single
   CMS object of type SignedData.  The SignedData encapContentInfo
   eContent field MUST be absent.  The signerInfos field contains the
   signatures for the MIME entity.

   The file extension for signed-only messages using application/pkcs7-
   signature is ".p7s".

3.4.3.2.  Creating a multipart/signed Message

   Step 1.  The MIME entity to be signed is prepared according to
            Section 3.1, taking special care for clear-signing.

   Step 2.  The MIME entity is presented to CMS processing in order to
            obtain an object of type SignedData in which the
            encapContentInfo eContent field is absent.

   Step 3.  The MIME entity is inserted into the first part of a
            multipart/signed message with no processing other than that
            described in Section 3.1.

   Step 4.  Transfer encoding is applied to the "detached signature" CMS
            SignedData object, and it is inserted into a MIME entity of
            type application/pkcs7-signature.

   Step 5.  The MIME entity of the application/pkcs7-signature is
            inserted into the second part of the multipart/signed
            entity.

   The multipart/signed Content-Type has two required parameters: the
   protocol parameter and the micalg parameter.

   The protocol parameter MUST be "application/pkcs7-signature".  Note
   that quotation marks are required around the protocol parameter
   because MIME requires that the "/" character in the parameter value
   MUST be quoted.

   The micalg parameter allows for one-pass processing when the
   signature is being verified.  The value of the micalg parameter is
   dependent on the message digest algorithm(s) used in the calculation
   of the Message Integrity Check.  If multiple message digest
   algorithms are used, they MUST be separated by commas per [MIME-
   SECURE].  The values to be placed in the micalg parameter SHOULD be
   from the following:





Ramsdell & Turner            Standards Track                   [Page 28]

RFC 5751            S/MIME 3.2 Message Specification        January 2010


      Algorithm   Value Used

      MD5         md5
      SHA-1       sha-1
      SHA-224     sha-224
      SHA-256     sha-256
      SHA-384     sha-384
      SHA-512     sha-512
      Any other   (defined separately in algorithm profile or "unknown"
                   if not defined)

   (Historical note: some early implementations of S/MIME emitted and
   expected "rsa-md5", "rsa-sha1", and "sha1" for the micalg parameter.)
   Receiving agents SHOULD be able to recover gracefully from a micalg
   parameter value that they do not recognize.  Future names for this
   parameter will be consistent with the IANA "Hash Function Textual
   Names" registry.

3.4.3.3.  Sample multipart/signed Message

       Content-Type: multipart/signed;
          protocol="application/pkcs7-signature";
          micalg=sha1; boundary=boundary42

       --boundary42
       Content-Type: text/plain

       This is a clear-signed message.

       --boundary42
       Content-Type: application/pkcs7-signature; name=smime.p7s
       Content-Transfer-Encoding: base64
       Content-Disposition: attachment; filename=smime.p7s

       ghyHhHUujhJhjH77n8HHGTrfvbnj756tbB9HG4VQpfyF467GhIGfHfYT6
       4VQpfyF467GhIGfHfYT6jH77n8HHGghyHhHUujhJh756tbB9HGTrfvbnj
       n8HHGTrfvhJhjH776tbB9HG4VQbnj7567GhIGfHfYT6ghyHhHUujpfyF4
       7GhIGfHfYT64VQbnj756

      --boundary42--

   The content that is digested (the first part of the multipart/signed)
   consists of the bytes:

   43 6f 6e 74 65 6e 74 2d 54 79 70 65 3a 20 74 65 78 74 2f 70 6c 61 69
   6e 0d 0a 0d 0a 54 68 69 73 20 69 73 20 61 20 63 6c 65 61 72 2d 73 69
   67 6e 65 64 20 6d 65 73 73 61 67 65 2e 0d 0a




Ramsdell & Turner            Standards Track                   [Page 29]

RFC 5751            S/MIME 3.2 Message Specification        January 2010


3.5.  Creating a Compressed-Only Message

   This section describes the format for compressing a MIME entity.
   Please note that versions of S/MIME prior to version 3.1 did not
   specify any use of CompressedData, and will not recognize it.  The
   use of a capability to indicate the ability to receive CompressedData
   is described in [CMSCOMPR] and is the preferred method for
   compatibility.

   Step 1.  The MIME entity to be compressed is prepared according to
            Section 3.1.

   Step 2.  The MIME entity and other required data are processed into a
            CMS object of type CompressedData.

   Step 3.  The CompressedData object is wrapped in a CMS ContentInfo
            object.

   Step 4.  The ContentInfo object is inserted into an
            application/pkcs7-mime MIME entity.

   The smime-type parameter for compressed-only messages is "compressed-
   data".  The file extension for this type of message is ".p7z".

   A sample message would be:

   Content-Type: application/pkcs7-mime; smime-type=compressed-data;
      name=smime.p7z
   Content-Transfer-Encoding: base64
   Content-Disposition: attachment; filename=smime.p7z

   rfvbnj756tbBghyHhHUujhJhjH77n8HHGT9HG4VQpfyF467GhIGfHfYT6
   7n8HHGghyHhHUujhJh4VQpfyF467GhIGfHfYGTrfvbnjT6jH7756tbB9H
   f8HHGTrfvhJhjH776tbB9HG4VQbnj7567GhIGfHfYT6ghyHhHUujpfyF4
   0GhIGfHfQbnj756YT64V

3.6.  Multiple Operations

   The signed-only, enveloped-only, and compressed-only MIME formats can
   be nested.  This works because these formats are all MIME entities
   that encapsulate other MIME entities.

   An S/MIME implementation MUST be able to receive and process
   arbitrarily nested S/MIME within reasonable resource limits of the
   recipient computer.






Ramsdell & Turner            Standards Track                   [Page 30]

RFC 5751            S/MIME 3.2 Message Specification        January 2010


   It is possible to apply any of the signing, encrypting, and
   compressing operations in any order.  It is up to the implementer and
   the user to choose.  When signing first, the signatories are then
   securely obscured by the enveloping.  When enveloping first the
   signatories are exposed, but it is possible to verify signatures
   without removing the enveloping.  This can be useful in an
   environment where automatic signature verification is desired, as no
   private key material is required to verify a signature.

   There are security ramifications to choosing whether to sign first or
   encrypt first.  A recipient of a message that is encrypted and then
   signed can validate that the encrypted block was unaltered, but
   cannot determine any relationship between the signer and the
   unencrypted contents of the message.  A recipient of a message that
   is signed then encrypted can assume that the signed message itself
   has not been altered, but that a careful attacker could have changed
   the unauthenticated portions of the encrypted message.

   When using compression, keep the following guidelines in mind:

      - Compression of binary encoded encrypted data is discouraged,
        since it will not yield significant compression.  Base64
        encrypted data could very well benefit, however.

      - If a lossy compression algorithm is used with signing, you will
        need to compress first, then sign.

3.7.  Creating a Certificate Management Message

   The certificate management message or MIME entity is used to
   transport certificates and/or Certificate Revocation Lists, such as
   in response to a registration request.

   Step 1.  The certificates and/or Certificate Revocation Lists are
            made available to the CMS generating process that creates a
            CMS object of type SignedData.  The SignedData
            encapContentInfo eContent field MUST be absent and
            signerInfos field MUST be empty.

   Step 2.  The SignedData object is wrapped in a CMS ContentInfo
            object.

   Step 3.  The ContentInfo object is enclosed in an
            application/pkcs7-mime MIME entity.

   The smime-type parameter for a certificate management message is
   "certs-only".  The file extension for this type of message is ".p7c".




Ramsdell & Turner            Standards Track                   [Page 31]

RFC 5751            S/MIME 3.2 Message Specification        January 2010


3.8.  Registration Requests

   A sending agent that signs messages MUST have a certificate for the
   signature so that a receiving agent can verify the signature.  There
   are many ways of getting certificates, such as through an exchange
   with a certification authority, through a hardware token or diskette,
   and so on.

   S/MIME v2 [SMIMEv2] specified a method for "registering" public keys
   with certificate authorities using an application/pkcs10 body part.
   Since that time, the IETF PKIX Working Group has developed other
   methods for requesting certificates.  However, S/MIME v3.2 does not
   require a particular certificate request mechanism.

3.9.  Identifying an S/MIME Message

   Because S/MIME takes into account interoperation in non-MIME
   environments, several different mechanisms are employed to carry the
   type information, and it becomes a bit difficult to identify S/MIME
   messages.  The following table lists criteria for determining whether
   or not a message is an S/MIME message.  A message is considered an
   S/MIME message if it matches any of the criteria listed below.

   The file suffix in the table below comes from the "name" parameter in
   the Content-Type header field, or the "filename" parameter on the
   Content-Disposition header field.  These parameters that give the
   file suffix are not listed below as part of the parameter section.

   Media type:  application/pkcs7-mime
   parameters:  any
   file suffix: any

   Media type:  multipart/signed
   parameters:  protocol="application/pkcs7-signature"
   file suffix: any

   Media type:  application/octet-stream
   parameters:  any
   file suffix: p7m, p7s, p7c, p7z

4.  Certificate Processing

   A receiving agent MUST provide some certificate retrieval mechanism
   in order to gain access to certificates for recipients of digital
   envelopes.  This specification does not cover how S/MIME agents
   handle certificates, only what they do after a certificate has been
   validated or rejected.  S/MIME certificate issues are covered in
   [CERT32].



Ramsdell & Turner            Standards Track                   [Page 32]

RFC 5751            S/MIME 3.2 Message Specification        January 2010


   At a minimum, for initial S/MIME deployment, a user agent could
   automatically generate a message to an intended recipient requesting
   that recipient's certificate in a signed return message.  Receiving
   and sending agents SHOULD also provide a mechanism to allow a user to
   "store and protect" certificates for correspondents in such a way so
   as to guarantee their later retrieval.

4.1.  Key Pair Generation

   All generated key pairs MUST be generated from a good source of non-
   deterministic random input [RANDOM] and the private key MUST be
   protected in a secure fashion.

   An S/MIME user agent MUST NOT generate asymmetric keys less than 512
   bits for use with the RSA or DSA signature algorithms.

   For 512-bit RSA with SHA-1 see [CMSALG] and [FIPS186-2] without
   Change Notice 1, for 512-bit RSA with SHA-256 see [CMS-SHA2] and
   [FIPS186-2] without Change Notice 1, and for 1024-bit through
   2048-bit RSA with SHA-256 see [CMS-SHA2] and [FIPS186-2] with Change
   Notice 1.  The first reference provides the signature algorithm's
   object identifier, and the second provides the signature algorithm's
   definition.

   For 512-bit DSA with SHA-1 see [CMSALG] and [FIPS186-2] without
   Change Notice 1, for 512-bit DSA with SHA-256 see [CMS-SHA2] and
   [FIPS186-2] without Change Notice 1, for 1024-bit DSA with SHA-1 see
   [CMSALG] and [FIPS186-2] with Change Notice 1, for 1024-bit and above
   DSA with SHA-256 see [CMS-SHA2] and [FIPS186-3].  The first reference
   provides the signature algorithm's object identifier and the second
   provides the signature algorithm's definition.

   For RSASSA-PSS with SHA-256, see [RSAPSS].  For 1024-bit DH, see
   [CMSALG].  For 1024-bit and larger DH, see [SP800-56A]; regardless,
   use the KDF, which is from X9.42, specified in [CMSALG].  For RSAES-
   OAEP, see [RSAOAEP].

4.2.  Signature Generation

   The following are the requirements for an S/MIME agent generated RSA,
   RSASSA-PSS, and DSA signatures:

           key size <= 1023 : SHOULD NOT (see Security Considerations)
   1024 <= key size <= 2048 : SHOULD     (see Security Considerations)
   2048 <  key size         : MAY        (see Security Considerations)






Ramsdell & Turner            Standards Track                   [Page 33]

RFC 5751            S/MIME 3.2 Message Specification        January 2010


4.3.  Signature Verification

   The following are the requirements for S/MIME receiving agents during
   signature verification of RSA, RSASSA-PSS, and DSA signatures:

           key size <= 1023 : MAY        (see Security Considerations)
   1024 <= key size <= 2048 : MUST       (see Security Considerations)
   2048 <  key size         : MAY        (see Security Considerations)

4.4.  Encryption

   The following are the requirements for an S/MIME agent when
   establishing keys for content encryption using the RSA, RSA-OAEP, and
   DH algorithms:

           key size <= 1023 : SHOULD NOT (see Security Considerations)
   1024 <= key size <= 2048 : SHOULD     (see Security Considerations)
   2048 <  key size         : MAY        (see Security Considerations)

4.5.  Decryption

   The following are the requirements for an S/MIME agent when
   establishing keys for content decryption using the RSA, RSAES-OAEP,
   and DH algorithms:

           key size <= 1023 : MAY        (see Security Considerations)
   1024 <= key size <= 2048 : MUST       (see Security Considerations)
   2048 <  key size         : MAY        (see Security Considerations)

5.  IANA Considerations

   The following information updates the media type registration for
   application/pkcs7-mime and application/pkcs7-signature to refer to
   this document as opposed to RFC 2311.

   Note that other documents can define additional MIME media types for
   S/MIME.

5.1.  Media Type for application/pkcs7-mime

   Type name: application

   Subtype Name: pkcs7-mime

   Required Parameters: NONE






Ramsdell & Turner            Standards Track                   [Page 34]

RFC 5751            S/MIME 3.2 Message Specification        January 2010


   Optional Parameters: smime-type/signed-data
                        smime-type/enveloped-data
                        smime-type/compressed-data
                        smime-type/certs-only
                        name

   Encoding Considerations: See Section 3 of this document

   Security Considerations: See Section 6 of this document

   Interoperability Considerations: See Sections 1-6 of this document

   Published Specification: RFC 2311, RFC 2633, and this document

   Applications that use this media type: Security applications

   Additional information: NONE

   Person & email to contact for further information:
      S/MIME working group chairs smime-chairs@tools.ietf.org

   Intended usage: COMMON

   Restrictions on usage: NONE

   Author: Sean Turner

   Change Controller: S/MIME working group delegated from the IESG

5.2.  Media Type for application/pkcs7-signature

   Type name: application

   Subtype Name: pkcs7-signature

   Required Parameters: NONE

   Optional Parameters: NONE

   Encoding Considerations: See Section 3 of this document

   Security Considerations: See Section 6 of this document

   Interoperability Considerations: See Sections 1-6 of this document

   Published Specification: RFC 2311, RFC 2633, and this document

   Applications that use this media type: Security applications



Ramsdell & Turner            Standards Track                   [Page 35]

RFC 5751            S/MIME 3.2 Message Specification        January 2010


   Additional information: NONE

   Person & email to contact for further information:
      S/MIME working group chairs smime-chairs@tools.ietf.org

   Intended usage: COMMON

   Restrictions on usage: NONE

   Author: Sean Turner

   Change Controller: S/MIME working group delegated from the IESG

6.  Security Considerations

   Cryptographic algorithms will be broken or weakened over time.
   Implementers and users need to check that the cryptographic
   algorithms listed in this document continue to provide the expected
   level of security.  The IETF from time to time may issue documents
   dealing with the current state of the art.  For example:

      - The Million Message Attack described in RFC 3218 [MMA].

      - The Diffie-Hellman "small-subgroup" attacks described in RFC
        2785 [DHSUB].

      - The attacks against hash algorithms described in RFC 4270 [HASH-
        ATTACK].

   This specification uses Public-Key Cryptography technologies.  It is
   assumed that the private key is protected to ensure that it is not
   accessed or altered by unauthorized parties.

   It is impossible for most people or software to estimate the value of
   a message's content.  Further, it is impossible for most people or
   software to estimate the actual cost of recovering an encrypted
   message content that is encrypted with a key of a particular size.
   Further, it is quite difficult to determine the cost of a failed
   decryption if a recipient cannot process a message's content.  Thus,
   choosing between different key sizes (or choosing whether to just use
   plaintext) is also impossible for most people or software.  However,
   decisions based on these criteria are made all the time, and
   therefore this specification gives a framework for using those
   estimates in choosing algorithms.

   The choice of 2048 bits as the RSA asymmetric key size in this
   specification is based on the desire to provide at least 100 bits of
   security.  The key sizes that must be supported to conform to this



Ramsdell & Turner            Standards Track                   [Page 36]

RFC 5751            S/MIME 3.2 Message Specification        January 2010


   specification seem appropriate for the Internet based on [STRENGTH].
   Of course, there are environments, such as financial and medical
   systems, that may select different key sizes.  For this reason, an
   implementation MAY support key sizes beyond those recommended in this
   specification.

   Receiving agents that validate signatures and sending agents that
   encrypt messages need to be cautious of cryptographic processing
   usage when validating signatures and encrypting messages using keys
   larger than those mandated in this specification.  An attacker could
   send certificates with keys that would result in excessive
   cryptographic processing, for example, keys larger than those
   mandated in this specification, which could swamp the processing
   element.  Agents that use such keys without first validating the
   certificate to a trust anchor are advised to have some sort of
   cryptographic resource management system to prevent such attacks.

   Using weak cryptography in S/MIME offers little actual security over
   sending plaintext.  However, other features of S/MIME, such as the
   specification of AES and the ability to announce stronger
   cryptographic capabilities to parties with whom you communicate,
   allow senders to create messages that use strong encryption.  Using
   weak cryptography is never recommended unless the only alternative is
   no cryptography.

   RSA and DSA keys of less than 1024 bits are now considered by many
   experts to be cryptographically insecure (due to advances in
   computing power), and should no longer be used to protect messages.
   Such keys were previously considered secure, so processing previously
   received signed and encrypted mail will often result in the use of
   weak keys.  Implementations that wish to support previous versions of
   S/MIME or process old messages need to consider the security risks
   that result from smaller key sizes (e.g., spoofed messages) versus
   the costs of denial of service.  If an implementation supports
   verification of digital signatures generated with RSA and DSA keys of
   less than 1024 bits, it MUST warn the user.  Implementers should
   consider providing different warnings for newly received messages and
   previously stored messages.  Server implementations (e.g., secure
   mail list servers) where user warnings are not appropriate SHOULD
   reject messages with weak signatures.

   Implementers SHOULD be aware that multiple active key pairs can be
   associated with a single individual.  For example, one key pair can
   be used to support confidentiality, while a different key pair can be
   used for digital signatures.






Ramsdell & Turner            Standards Track                   [Page 37]

RFC 5751            S/MIME 3.2 Message Specification        January 2010


   If a sending agent is sending the same message using different
   strengths of cryptography, an attacker watching the communications
   channel might be able to determine the contents of the strongly
   encrypted message by decrypting the weakly encrypted version.  In
   other words, a sender SHOULD NOT send a copy of a message using
   weaker cryptography than they would use for the original of the
   message.

   Modification of the ciphertext can go undetected if authentication is
   not also used, which is the case when sending EnvelopedData without
   wrapping it in SignedData or enclosing SignedData within it.

   If an implementation is concerned about compliance with National
   Institute of Standards and Technology (NIST) key size
   recommendations, then see [SP800-57].

   If messaging environments make use of the fact that a message is
   signed to change the behavior of message processing (examples would
   be running rules or UI display hints), without first verifying that
   the message is actually signed and knowing the state of the
   signature, this can lead to incorrect handling of the message.
   Visual indicators on messages may need to have the signature
   validation code checked periodically if the indicator is supposed to
   give information on the current status of a message.

7.  References

7.1.  Reference Conventions

   [CMS] refers to [RFC5652].

   [ESS] refers to [RFC2634] and [RFC5035].

   [MIME] refers to [RFC2045], [RFC2046],  [RFC2047], [RFC2049],
   [RFC4288], and [RFC4289].

   [SMIMEv2] refers to [RFC2311], [RFC2312], [RFC2313], [RFC2314], and
   [RFC2315].

   [SMIMEv3] refers to [RFC2630], [RFC2631], [RFC2632], [RFC2633],
   [RFC2634], and [RFC5035].

   [SMIMv3.1] refers to [RFC2634], [RFC3850], [RFC3851], [RFC3852], and
   [RFC5035].







Ramsdell & Turner            Standards Track                   [Page 38]

RFC 5751            S/MIME 3.2 Message Specification        January 2010


7.2.  Normative References

   [CERT32]      Ramsdell, B. and S. Turner, "Secure/Multipurpose
                 Internet Mail Extensions (S/MIME) Version 3.2
                 Certificate Handling", RFC 5750, January 2010.

   [CHARSETS]    Character sets assigned by IANA.  See
                 http://www.iana.org/assignments/character-sets.

   [CMSAES]      Schaad, J., "Use of the Advanced Encryption Standard
                 (AES) Encryption Algorithm in Cryptographic Message
                 Syntax (CMS)", RFC 3565, July 2003.

   [CMSALG]      Housley, R., "Cryptographic Message Syntax (CMS)
                 Algorithms", RFC 3370, August 2002.

   [CMSCOMPR]    Gutmann, P., "Compressed Data Content Type for
                 Cryptographic Message Syntax (CMS)", RFC 3274, June
                 2002.

   [CMS-SHA2]    Turner, S., "Using SHA2 Algorithms with Cryptographic
                 Message Syntax", RFC 5754, January 2010.

   [CONTDISP]    Troost, R., Dorner, S., and K. Moore, Ed.,
                 "Communicating Presentation Information in Internet
                 Messages: The Content-Disposition Header Field", RFC
                 2183, August 1997.

   [FIPS186-2]   National Institute of Standards and Technology (NIST),
                 "Digital Signature Standard (DSS)", FIPS Publication
                 186-2, January 2000. [With Change Notice 1].

   [FIPS186-3]   National Institute of Standards and Technology (NIST),
                 FIPS Publication 186-3: Digital Signature Standard,
                 June 2009.

   [MIME-SECURE] Galvin, J., Murphy, S., Crocker, S., and N. Freed,
                 "Security Multiparts for MIME: Multipart/Signed and
                 Multipart/Encrypted", RFC 1847, October 1995.

   [MUSTSHOULD]  Bradner, S., "Key words for use in RFCs to Indicate
                 Requirement Levels", BCP 14, RFC 2119, March 1997.

   [RANDOM]      Eastlake, D., 3rd, Schiller, J., and S. Crocker,
                 "Randomness Requirements for Security", BCP 106, RFC
                 4086, June 2005.





Ramsdell & Turner            Standards Track                   [Page 39]

RFC 5751            S/MIME 3.2 Message Specification        January 2010


   [RFC2045]     Freed, N. and N. Borenstein, "Multipurpose Internet
                 Mail Extensions (MIME) Part One: Format of Internet
                 Message Bodies", RFC 2045, November 1996.

   [RFC2046]     Freed, N. and N. Borenstein, "Multipurpose Internet
                 Mail Extensions (MIME) Part Two: Media Types", RFC
                 2046, November 1996.

   [RFC2047]     Moore, K., "MIME (Multipurpose Internet Mail
                 Extensions) Part Three: Message Header Extensions for
                 Non-ASCII Text", RFC 2047, November 1996.

   [RFC2049]     Freed, N. and N. Borenstein, "Multipurpose Internet
                 Mail Extensions (MIME) Part Five: Conformance Criteria
                 and Examples", RFC 2049, November 1996.

   [RFC2634]     Hoffman, P. Ed., "Enhanced Security Services for
                 S/MIME", RFC 2634, June 1999.

   [RFC4288]     Freed, N. and J. Klensin, "Media Type Specifications
                 and Registration Procedures", BCP 13, RFC 4288,
                 December 2005.

   [RFC4289]     Freed, N. and J. Klensin, "Multipurpose Internet Mail
                 Extensions (MIME) Part Four: Registration Procedures",
                 BCP 13, RFC 4289, December 2005.

   [RFC5035]     Schaad, J., "Enhanced Security Services (ESS) Update:
                 Adding CertID Algorithm Agility", RFC 5035, August
                 2007.

   [RFC5652]     Housley, R., "Cryptographic Message Syntax (CMS)", RFC
                 5652, September 2009.

   [RSAOAEP]     Housley, R. "Use of the RSAES-OAEP Key Transport
                 Algorithm in the Cryptographic Message Syntax (CMS)",
                 RFC 3560, July 2003.

   [RSAPSS]      Schaad, J., "Use of the RSASSA-PSS Signature Algorithm
                 in Cryptographic Message Syntax (CMS)", RFC 4056, June
                 2005.

   [SP800-56A]   National Institute of Standards and Technology (NIST),
                 Special Publication 800-56A: Recommendation Pair-Wise
                 Key Establishment Schemes Using Discrete Logarithm
                 Cryptography (Revised), March 2007.





Ramsdell & Turner            Standards Track                   [Page 40]

RFC 5751            S/MIME 3.2 Message Specification        January 2010


   [X.680]       ITU-T Recommendation X.680 (2002) | ISO/IEC
                 8824-1:2002. Information Technology - Abstract Syntax
                 Notation One (ASN.1):  Specification of basic notation.

   [X.690]       ITU-T Recommendation X.690 (2002) | ISO/IEC
                 8825-1:2002.  Information Technology - ASN.1 encoding
                 rules: Specification of Basic Encoding Rules (BER),
                 Canonical Encoding Rules (CER) and Distinguished
                 Encoding Rules (DER).

7.3.  Informative References

   [DHSUB]       Zuccherato, R., "Methods for Avoiding the "Small-
                 Subgroup" Attacks on the Diffie-Hellman Key Agreement
                 Method for S/MIME", RFC 2785, March 2000.

   [HASH-ATTACK] Hoffman, P. and B. Schneier, "Attacks on Cryptographic
                 Hashes in Internet Protocols", RFC 4270, November 2005.

   [MMA]         Rescorla, E., "Preventing the Million Message Attack on
                 Cryptographic Message Syntax", RFC 3218, January 2002.

   [PKCS-7]      Kaliski, B., "PKCS #7: Cryptographic Message Syntax
                 Version 1.5", RFC 2315, March 1998.

   [RFC2311]     Dusse, S., Hoffman, P., Ramsdell, B., Lundblade, L.,
                 and L. Repka, "S/MIME Version 2 Message Specification",
                 RFC 2311, March 1998.

   [RFC2312]     Dusse, S., Hoffman, P., Ramsdell, B., and J.
                 Weinstein, "S/MIME Version 2 Certificate Handling", RFC
                 2312, March 1998.

   [RFC2313]     Kaliski, B., "PKCS #1: RSA Encryption Version 1.5", RFC
                 2313, March 1998.

   [RFC2314]     Kaliski, B., "PKCS #10: Certification Request Syntax
                 Version 1.5", RFC 2314, March 1998.

   [RFC2315]     Kaliski, B., "PKCS #7: Certification Message Syntax
                 Version 1.5", RFC 2315, March 1998.

   [RFC2630]     Housley, R., "Cryptographic Message Syntax", RFC 2630,
                 June 1999.

   [RFC2631]     Rescorla, E., "Diffie-Hellman Key Agreement Method",
                 RFC 2631, June 1999.




Ramsdell & Turner            Standards Track                   [Page 41]

RFC 5751            S/MIME 3.2 Message Specification        January 2010


   [RFC2632]     Ramsdell, B., Ed., "S/MIME Version 3 Certificate
                 Handling", RFC 2632, June 1999.

   [RFC2633]     Ramsdell, B., Ed., "S/MIME Version 3 Message
                 Specification", RFC 2633, June 1999.

   [RFC3850]     Ramsdell, B., Ed., "Secure/Multipurpose Internet Mail
                 Extensions (S/MIME) Version 3.1 Certificate Handling",
                 RFC 3850, July 2004.

   [RFC3851]     Ramsdell, B., Ed., "Secure/Multipurpose Internet Mail
                 Extensions (S/MIME) Version 3.1 Message Specification",
                 RFC 3851, July 2004.

   [RFC3852]     Housley, R., "Cryptographic Message Syntax (CMS)", RFC
                 3852, July 2004.

   [SP800-57]    National Institute of Standards and Technology (NIST),
                 Special Publication 800-57: Recommendation for Key
                 Management, August 2005.

   [STRENGTH]    Orman, H., and P. Hoffman, "Determining Strengths For
                 Public Keys Used For Exchanging Symmetric Keys", BCP
                 86, RFC 3766, April 2004.



























Ramsdell & Turner            Standards Track                   [Page 42]

RFC 5751            S/MIME 3.2 Message Specification        January 2010


Appendix A.  ASN.1 Module

   Note: The ASN.1 module contained herein is unchanged from RFC 3851
   [SMIMEv3.1] with the exception of a change to the prefersBinaryInside
   ASN.1 comment.  This module uses the 1988 version of ASN.1.

   SecureMimeMessageV3dot1

     { iso(1) member-body(2) us(840) rsadsi(113549)
            pkcs(1) pkcs-9(9) smime(16) modules(0) msg-v3dot1(21) }

   DEFINITIONS IMPLICIT TAGS ::=

   BEGIN

   IMPORTS

   -- Cryptographic Message Syntax [CMS]
      SubjectKeyIdentifier, IssuerAndSerialNumber,
      RecipientKeyIdentifier
          FROM  CryptographicMessageSyntax
                { iso(1) member-body(2) us(840) rsadsi(113549)
                  pkcs(1) pkcs-9(9) smime(16) modules(0) cms-2001(14) };

   --  id-aa is the arc with all new authenticated and unauthenticated
   --  attributes produced by the S/MIME Working Group

   id-aa OBJECT IDENTIFIER ::= {iso(1) member-body(2) usa(840)
           rsadsi(113549) pkcs(1) pkcs-9(9) smime(16) attributes(2)}

   -- S/MIME Capabilities provides a method of broadcasting the
   -- symmetric capabilities understood.  Algorithms SHOULD be ordered
   -- by preference and grouped by type

   smimeCapabilities OBJECT IDENTIFIER ::= {iso(1) member-body(2)
           us(840) rsadsi(113549) pkcs(1) pkcs-9(9) 15}

   SMIMECapability ::= SEQUENCE {
      capabilityID OBJECT IDENTIFIER,
      parameters ANY DEFINED BY capabilityID OPTIONAL }

   SMIMECapabilities ::= SEQUENCE OF SMIMECapability

   -- Encryption Key Preference provides a method of broadcasting the
   -- preferred encryption certificate.

   id-aa-encrypKeyPref OBJECT IDENTIFIER ::= {id-aa 11}




Ramsdell & Turner            Standards Track                   [Page 43]

RFC 5751            S/MIME 3.2 Message Specification        January 2010


   SMIMEEncryptionKeyPreference ::= CHOICE {
      issuerAndSerialNumber   [0] IssuerAndSerialNumber,
      receipentKeyId          [1] RecipientKeyIdentifier,
      subjectAltKeyIdentifier [2] SubjectKeyIdentifier
   }

   -- receipentKeyId is spelt incorrectly, but kept for historical
   -- reasons.

   id-smime OBJECT IDENTIFIER ::= { iso(1) member-body(2) us(840)
           rsadsi(113549) pkcs(1) pkcs9(9) 16 }

   id-cap  OBJECT IDENTIFIER ::= { id-smime 11 }

   -- The preferBinaryInside OID indicates an ability to receive
   -- messages with binary encoding inside the CMS wrapper.
   -- The preferBinaryInside attribute's value field is ABSENT.

   id-cap-preferBinaryInside  OBJECT IDENTIFIER ::= { id-cap 1 }

   --  The following list OIDs to be used with S/MIME V3

   -- Signature Algorithms Not Found in [CMSALG], [CMS-SHA2], [RSAPSS],
   -- and [RSAOAEP]

   --
   -- md2WithRSAEncryption OBJECT IDENTIFIER ::=
   --    {iso(1) member-body(2) us(840) rsadsi(113549) pkcs(1) pkcs-1(1)
   --     2}

   --
   -- Other Signed Attributes
   --
   -- signingTime OBJECT IDENTIFIER ::=
   --    {iso(1) member-body(2) us(840) rsadsi(113549) pkcs(1) pkcs-9(9)
   --     5}
   --    See [CMS] for a description of how to encode the attribute
   --    value.

   SMIMECapabilitiesParametersForRC2CBC ::= INTEGER
   --        (RC2 Key Length (number of bits))

   END








Ramsdell & Turner            Standards Track                   [Page 44]

RFC 5751            S/MIME 3.2 Message Specification        January 2010


Appendix B.  Moving S/MIME v2 Message Specification to Historic Status

   The S/MIME v3 [SMIMEv3], v3.1 [SMIMEv3.1], and v3.2 (this document)
   are backwards compatible with the S/MIME v2 Message Specification
   [SMIMEv2], with the exception of the algorithms (dropped RC2/40
   requirement and added DSA and RSASSA-PSS requirements).  Therefore,
   it is recommended that RFC 2311 [SMIMEv2] be moved to Historic
   status.

Appendix C.  Acknowledgments

   Many thanks go out to the other authors of the S/MIME version 2
   Message Specification RFC: Steve Dusse, Paul Hoffman, Laurence
   Lundblade, and Lisa Repka.  Without v2, there wouldn't be a v3, v3.1,
   or v3.2.

   A number of the members of the S/MIME Working Group have also worked
   very hard and contributed to this document.  Any list of people is
   doomed to omission, and for that I apologize.  In alphabetical order,
   the following people stand out in my mind because they made direct
   contributions to this document:

   Tony Capel, Piers Chivers, Dave Crocker, Bill Flanigan, Peter
   Gutmann, Alfred Hoenes, Paul Hoffman, Russ Housley, William Ottaway,
   John Pawling, and Jim Schaad.

Authors' Addresses

   Blake Ramsdell
   Brute Squad Labs, Inc.

   EMail: blaker@gmail.com


   Sean Turner
   IECA, Inc.
   3057 Nutley Street, Suite 106
   Fairfax, VA 22031
   USA

   EMail: turners@ieca.com










Ramsdell & Turner            Standards Track                   [Page 45]



================================================
FILE: doc/notes/rfc/whats_where.txt
================================================
RFC 1854:
---------
PIPELINING extension

RFC 2222:
---------
SASL

RFC 4505:
---------
ANYNONYMOUS SASL

RFC 4616:
---------
PLAIN SASL

RFC 2487:
---------
STARTTLS extension

RFC 2554 & 4954:
----------------
AUTH extension

RFC 2821:
---------
SMTP protocol

RFC 2822:
---------
General message structure (focusing on important headers)

RFC 2045:
---------
Quoted Printable Encoding
Base 64 Encoding
Detailed message structure

RFC 2046:
---------
Media types (for subparts)

RFC 2047:
---------
Header Encoding

RFC 2183:
---------
The Content-Disposition header

RFC 2231:
---------
Encoded Text header/attribute extensions

RFC 2234:
---------
ABNF definitions

RFC 3676:
---------
Flowed formatting/delsp parameters

RFC 2015:
---------
Original Mime Security with OpenPGP

RFC 2440:
---------
Original OpenPGP message format

RFC 3156:
---------
Current (30/01/2009) Mime Security with OpenPGP

RFC 4880:
---------
Current (30/01/2009) OpenPGP Message format revision (fun, it's exactly original *2 --sorry)

RFC 5751:
--------
Secure/Multipurpose Internet Mail Extensions (S/MIME) Version 3.2

RFC 4870:
---------
DomainKeys (historic), but still used by a few people.

RFC 4871: (Obsoleted by 6376)
---------
DomainKeys Identified Mail (DKIM) Signatures

RFC 5672: (Obsoleted by 6376)
---------
DomainKeys Identified Mail (DKIM) Signatures -- Update

RFC 6376:
---------
DomainKeys Identified Mail (DKIM) Signatures


================================================
FILE: doc/notes/rfc5672.txt
================================================






Network Working Group                                    D. Crocker, Ed.
Request for Comments: 5672                   Brandenburg InternetWorking
Updates: 4871                                                August 2009
Category: Standards Track


    RFC 4871 DomainKeys Identified Mail (DKIM) Signatures -- Update

Abstract

   This document updates RFC 4871, "DomainKeys Identified Mail (DKIM)
   Signatures".  Specifically, the document clarifies the nature, roles,
   and relationship of the two DKIM identifier tag values that are
   candidates for payload delivery to a receiving processing module.
   The Update is in the style of an Errata entry, albeit a rather long
   one.

Status of This Memo

   This document specifies an Internet standards track protocol for the
   Internet community, and requests discussion and suggestions for
   improvements.  Please refer to the current edition of the "Internet
   Official Protocol Standards" (STD 1) for the standardization state
   and status of this protocol.  Distribution of this memo is unlimited.

Copyright Notice

   Copyright (c) 2009 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents in effect on the date of
   publication of this document (http://trustee.ietf.org/license-info).
   Please review these documents carefully, as they describe your rights
   and restrictions with respect to this document.

   This document may contain material from IETF Documents or IETF
   Contributions published or made publicly available before November
   10, 2008.  The person(s) controlling the copyright in some of this
   material may not have granted the IETF Trust the right to allow
   modifications of such material outside the IETF Standards Process.
   Without obtaining an adequate license from the person(s) controlling
   the copyright in such materials, this document may not be modified
   outside the IETF Standards Process, and derivative works of it may
   not be created outside the IETF Standards Process, except to format
   it for publication as an RFC or to translate it into languages other
   than English.




Crocker                     Standards Track                     [Page 1]

RFC 5672                    RFC 4871 Update                  August 2009


Table of Contents

   1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  2
   2.  RFC 4871, Abstract . . . . . . . . . . . . . . . . . . . . . .  4
   3.  RFC 4871, Section 1, Introduction  . . . . . . . . . . . . . .  4
   4.  RFC 4871, Section 2.7, Identity  . . . . . . . . . . . . . . .  4
   5.  RFC 4871, Section 2.8, Identifier  . . . . . . . . . . . . . .  5
   6.  RFC 4871, Section 2.9, Signing Domain Identifier (SDID)  . . .  5
   7.  RFC 4871, Section 2.10, Agent or User Identifier (AUID)  . . .  5
   8.  RFC 4871, Section 2.11, Identity Assessor  . . . . . . . . . .  6
   9.  RFC 4871, Section 3.5, The DKIM-Signature Header Field . . . .  6
   10. RFC 4871, Section 3.5, The DKIM-Signature Header Field . . . .  7
   11. RFC 4871, Section 3.8, Signing by Parent Domains  . . . . . . . 9
   12. RFC 4871, Section 3.9, Relationship between SDID and AUID  . . 10
   13. RFC 4871, Section 6.3, Interpret Results/Apply Local Policy  . 11
   14. RFC 4871, Section 6.3, Interpret Results/Apply Local Policy  . 11
   15. RFC 4871, Appendix D, MUA Considerations . . . . . . . . . . . 12
   16. Security Considerations  . . . . . . . . . . . . . . . . . . . 12
   17. Normative References . . . . . . . . . . . . . . . . . . . . . 12
   Appendix A.  ABNF Fragments  . . . . . . . . . . . . . . . . . . . 13
   Appendix B.  Acknowledgements  . . . . . . . . . . . . . . . . . . 14


1.  Introduction

   About the purpose for DKIM, [RFC4871] states:

      The ultimate goal of this framework is to permit a signing domain
      to assert responsibility for a message, thus protecting message
      signer identity...

   Hence, DKIM has a signer that produces a signed message, a verifier
   that confirms the signature, and an assessor that consumes the
   validated signing domain.  So, the simple purpose of DKIM is to
   communicate an identifier to a receive-side assessor module.  The
   identifier is in the form of a domain name that refers to a
   responsible identity.  For DKIM to be interoperable and useful, the
   signer and assessor must share the same understanding of the details
   about the identifier.

   However, the RFC 4871 specification defines two, potentially
   different, identifiers that are carried in the DKIM-Signature: header
   field, d= and i=.  Either might be delivered to a receiving
   processing module that consumes validated payload.  The DKIM
   specification fails to clearly define which is the "payload" to be
   delivered to a consuming module, versus what is internal and merely
   in support of achieving payload delivery.




Crocker                     Standards Track                     [Page 2]

RFC 5672                    RFC 4871 Update                  August 2009


   This currently leaves signers and assessors with the potential for
   making different interpretations between the two identifiers and may
   lead to interoperability problems.  A signer could intend one to be
   used for assessment, and have a different intent in setting the value
   in the other.  However the verifier might choose the wrong value to
   deliver to the assessor, thereby producing an unintended (and
   inaccurate) assessment.

   This Update resolves that confusion.  It defines additional, semantic
   labels for the two values, clarifies their nature, and specifies
   their relationship.  More specifically, it clarifies that the
   identifier intended for delivery to the assessor -- such as one that
   consults a whitelist -- is the value of the "d=" tag.  However, this
   does not prohibit message filtering engines from using the "i=" tag,
   or any other information in the message's header, for filtering
   decisions.

   For signers and verifiers that have been using the i= tag as the
   primary value that is delivered to the assessor, a software change to
   using the d= tag is intended.

   So, this Update clarifies the formal interface to DKIM, after
   signature verification has been performed.  It distinguishes DKIM's
   internal signing and verification activity, from its standardized
   delivery of data to that interface.

   The focus of the Update is on the portion of DKIM that is much like
   an API definition.  If DKIM is implemented as a software library for
   use by others, it needs to define what outputs are provided, that is,
   what data that an application developer who uses the library can
   expect to obtain as a result of invoking DKIM on a message.

   This Update defines the output of that library to include the yes/no
   result of the verification and the "d=" value.  In other words, it
   says what (one) identifier was formally specified for use by the
   signer and whether the use of that identifier has been validated.
   For a particular library, other information can be provided at the
   discretion of the library developer, since developers of assessors --
   these are the consumers of the DKIM library -- well might want more
   information than the standardized two pieces of information.
   However, that standardized set is the minimum that is required to be
   provided to a consuming module, in order to be able to claim that the
   library is DKIM compliant.

   This does not state what the implicit value of "i=" is, relative to
   "d=".  In this context, that fact is irrelevant.





Crocker                     Standards Track                     [Page 3]

RFC 5672                    RFC 4871 Update                  August 2009


   Another example is the difference between the socket interface to TCP
   versus the TCP protocol itself.  There is the activity within the
   protocol stack, and then there is the activity within in the software
   libraries that are actually used.

   NOTE: The text provided here updates [RFC4871].  Text appearing in
      the "Corrected Text:" replaces text in RFC 4871.  Hence,
      references that appear in the "Original Text:" can be found in RFC
      4871, and are not duplicated in this document.

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in [RFC2119].

2.  RFC 4871, Abstract

   Original Text:

      The ultimate goal of this framework is to permit a signing domain
      to assert responsibility for a message,

   Corrected Text:

      The ultimate goal of this framework is to permit a person, role or
      organization that owns the signing domain to assert responsibility
      for a message,

3.  RFC 4871, Section 1, Introduction

   Original Text:

      ...permitting a signing domain to claim responsibility

   Corrected Text:

      permitting a person, role, or organization that owns the signing
      domain to claim responsibility

4.  RFC 4871, Section 2.7, Identity

   Original Text:

      (None.  New section.  Additional text.)








Crocker                     Standards Track                     [Page 4]

RFC 5672                    RFC 4871 Update                  August 2009


   Corrected Text:

      A person, role, or organization.  In the context of DKIM, examples
      include author, author's organization, an ISP along the handling
      path, an independent trust assessment service, and a mailing list
      operator.

5.  RFC 4871, Section 2.8, Identifier

   Original Text:

      (None.  New section.  Additional text.)

   Corrected Text:

      A label that refers to an identity.

6.  RFC 4871, Section 2.9, Signing Domain Identifier (SDID)

   Original Text:

      (None.  New section.  Additional text.)

   Corrected Text:

      A single domain name that is the mandatory payload output of DKIM
      and that refers to the identity claiming responsibility for
      introduction of a message into the mail stream.  For DKIM
      processing, the name has only basic domain name semantics; any
      possible owner-specific semantics are outside the scope of DKIM.
      It is specified in Section 3.5.

7.  RFC 4871, Section 2.10, Agent or User Identifier (AUID)

   Original Text:

      (None.  New section.  Additional text.)

   Corrected Text:

      A single identifier that refers to the agent or user on behalf of
      whom the Signing Domain Identifier (SDID) has taken
      responsibility.  The AUID comprises a domain name and an optional
      <Local-part>.  The domain name is the same as that used for the
      SDID or is a sub-domain of it.  For DKIM processing, the domain
      name portion of the AUID has only basic domain name semantics; any
      possible owner-specific semantics are outside the scope of DKIM.
      It is specified in Section 3.5.



Crocker                     Standards Track                     [Page 5]

RFC 5672                    RFC 4871 Update                  August 2009


8.  RFC 4871, Section 2.11, Identity Assessor

   Original Text:

      (None.  New section.  Additional text.)

   Corrected Text:

      A module that consumes DKIM's mandatory payload, which is the
      responsible Signing Domain Identifier (SDID).  The module is
      dedicated to the assessment of the delivered identifier.  Other
      DKIM (and non-DKIM) values can also be delivered to this module as
      well as to a more general message evaluation filtering engine.
      However, this additional activity is outside the scope of the DKIM
      signature specification.

9.  RFC 4871, Section 3.5, The DKIM-Signature Header Field

   Original Text:

   d=  The domain of the signing entity (plain-text; REQUIRED).  This is
      the domain that will be queried for the public key.  This domain
      MUST be the same as or a parent domain of the "i=" tag (the
      signing identity, as described below), or it MUST meet the
      requirements for parent domain signing described in Section 3.8.
      When presented with a signature that does not meet these
      requirement, verifiers MUST consider the signature invalid.

      Internationalized domain names MUST be encoded as described in
      [RFC3490].

      ABNF:

         sig-d-tag       = %x64 [FWS] "=" [FWS] domain-name
         domain-name     = sub-domain 1*("." sub-domain)
                  ; from RFC 2821 Domain,
                    but excluding address-literal

   Corrected Text:

      d=

         Specifies the SDID claiming responsibility for an introduction
         of a message into the mail stream (plain-text; REQUIRED).
         Hence, the SDID value is used to form the query for the public
         key.  The SDID MUST correspond to a valid DNS name under which
         the DKIM key record is published.  The conventions and
         semantics used by a signer to create and use a specific SDID



Crocker                     Standards Track                     [Page 6]

RFC 5672                    RFC 4871 Update                  August 2009


         are outside the scope of the DKIM Signing specification, as is
         any use of those conventions and semantics.  When presented
         with a signature that does not meet these requirements,
         verifiers MUST consider the signature invalid.

         Internationalized domain names MUST be encoded as described in
         [RFC3490].

         ABNF:

            sig-d-tag   = %x64 [FWS] "=" [FWS] domain-name
           domain-name = sub-domain 1*("." sub-domain)
                         ; from RFC 5321 Domain,
                           but excluding address-literal

10.  RFC 4871, Section 3.5, The DKIM-Signature Header Field

   Original Text:

   i=  Identity of the user or agent (e.g., a mailing list manager) on
      behalf of which this message is signed (dkim-quoted-printable;
      OPTIONAL, default is an empty Local-part followed by an "@"
      followed by the domain from the "d=" tag).  The syntax is a
      standard email address where the Local-part MAY be omitted.  The
      domain part of the address MUST be the same as or a subdomain of
      the value of the "d=" tag.

      Internationalized domain names MUST be converted using the steps
      listed in Section 4 of [RFC3490] using the "ToASCII" function.

      ABNF:

         sig-i-tag =  %x69 [FWS] "=" [FWS]
                      [ Local-part ] "@" domain-name

      INFORMATIVE NOTE: The Local-part of the "i=" tag is optional
      because in some cases a signer may not be able to establish a
      verified individual identity.  In such cases, the signer may
      wish to assert that although it is willing to go as far as
      signing for the domain, it is unable or unwilling to commit
      to an individual user name within their domain.  It can do so
      by including the domain part but not the Local-part of the
      identity.

      INFORMATIVE DISCUSSION: This document does not require the value
      of the "i=" tag to match the identity in any message header
      fields.  This is considered to be a verifier policy issue.
      Constraints between the value of the "i=" tag and other



Crocker                     Standards Track                     [Page 7]

RFC 5672                    RFC 4871 Update                  August 2009


      identities in other header fields seek to apply basic
      authentication into the semantics of trust associated with a
      role such as content author.  Trust is a broad and complex
      topic and trust mechanisms are subject to highly creative
      attacks.  The real-world efficacy of
      bindings between the "i=" value and other identities is not
      well established, nor is its vulnerability to subversion by
      an attacker.  Hence reliance on the use of these options
      should be strictly limited.  In particular, it is not at all
      clear to what extent a typical end-user recipient can rely on
      any assurances that might be made by successful use of the
      "i=" options.

   Corrected Text:

      i=

         The Agent or User Identifier (AUID) on behalf of which the SDID
         is taking responsibility (dkim-quoted-printable; OPTIONAL,
         default is an empty Local-part followed by an "@" followed by
         the domain from the "d=" tag).

         The syntax is a standard email address where the Local-part MAY
         be omitted.  The domain part of the address MUST be the same
         as, or a subdomain of the value of, the "d=" tag.

         Internationalized domain names MUST be converted using the
         steps listed in Section 4 of [RFC3490] using the "ToASCII"
         function.

         ABNF:

            sig-i-tag =  %x69 [FWS] "=" [FWS]
                        [ Local-part ] "@" domain-name

         The AUID is specified as having the same syntax as an email
         address, but is not required to have the same semantics.
         Notably, the domain name is not required to be registered in
         the DNS -- so it might not resolve in a query -- and the Local-
         part MAY be drawn from a namespace that does not contain the
         user's mailbox.  The details of the structure and semantics for
         the namespace are determined by the Signer.  Any knowledge or
         use of those details by verifiers or assessors is outside the
         scope of the DKIM Signing specification.  The Signer MAY choose
         to use the same namespace for its AUIDs as its users' email
         addresses or MAY choose other means of representing its users.
         However, the signer SHOULD use the same AUID for each message
         intended to be evaluated as being within the same sphere of



Crocker                     Standards Track                     [Page 8]

RFC 5672                    RFC 4871 Update                  August 2009


         responsibility, if it wishes to offer receivers the option of
         using the AUID as a stable identifier that is finer grained
         than the SDID.

         INFORMATIVE NOTE: The Local-part of the "i=" tag is optional
         because, in some cases, a signer may not be able to establish a
         verified individual identity.  In such cases, the signer might
         wish to assert that although it is willing to go as far as
         signing for the domain, it is unable or unwilling to commit to
         an individual user name within their domain.  It can do so by
         including the domain part but not the Local-part of the
         identity.

11.  RFC 4871, Section 3.8, Signing by Parent Domains

   Original Text:

      e.g., a key record for the domain example.com can be used to
      verify messages where the signing identity ("i=" tag of the
      signature) is sub.example.com, or even sub1.sub2.example.com.  In
      order to limit the capability of such keys when this is not
      intended, the "s" flag may be set in the "t=" tag of the key
      record to constrain the validity of the record to exactly the
      domain of the signing identity.  If the referenced key record
      contains the "s" flag as part of the "t=" tag, the domain of the
      signing identity ("i=" flag) MUST be the same as that of the d=
      domain.  If this flag is absent, the domain of the signing
      identity MUST be the same as, or a subdomain of, the d= domain.

   Corrected Text:

      ...for example, a key record for the domain example.com can be
      used to verify messages where the AUID ("i=" tag of the signature)
      is sub.example.com, or even sub1.sub2.example.com.  In order to
      limit the capability of such keys when this is not intended, the
      "s" flag MAY be set in the "t=" tag of the key record, to
      constrain the validity of the domain of the AUID.  If the
      referenced key record contains the "s" flag as part of the "t="
      tag, the domain of the AUID ("i=" flag) MUST be the same as that
      of the SDID (d=) domain.  If this flag is absent, the domain of
      the AUID MUST be the same as, or a subdomain of, the SDID.










Crocker                     Standards Track                     [Page 9]

RFC 5672                    RFC 4871 Update                  August 2009


12.  RFC 4871, Section 3.9, Relationship between SDID and AUID

   Original Text:   (None.  New section.  Additional text.)

   Corrected Text:

      DKIM's primary task is to communicate from the Signer to a
      recipient-side Identity Assessor a single Signing Domain
      Identifier (SDID) that refers to a responsible identity.  DKIM MAY
      optionally provide a single responsible Agent or User Identifier
      (AUID).

      Hence, DKIM's mandatory output to a receive-side Identity Assessor
      is a single domain name.  Within the scope of its use as DKIM
      output, the name has only basic domain name semantics; any
      possible owner-specific semantics are outside the scope of DKIM.
      That is, within its role as a DKIM identifier, additional
      semantics cannot be assumed by an Identity Assessor.

      A receive-side DKIM verifier MUST communicate the Signing Domain
      Identifier (d=) to a consuming Identity Assessor module and MAY
      communicate the Agent or User Identifier (i=) if present.

      To the extent that a receiver attempts to intuit any structured
      semantics for either of the identifiers, this is a heuristic
      function that is outside the scope of DKIM's specification and
      semantics.  Hence, it is relegated to a higher-level service, such
      as a delivery handling filter that integrates a variety of inputs
      and performs heuristic analysis of them.

      INFORMATIVE DISCUSSION: This document does not require the value
      of the SDID or AUID to match the identifier in any other message
      header field.  This requirement is, instead, an assessor policy
      issue.  The purpose of such a linkage would be to authenticate the
      value in that other header field.  This, in turn, is the basis for
      applying a trust assessment based on the identifier value.  Trust
      is a broad and complex topic and trust mechanisms are subject to
      highly creative attacks.  The real-world efficacy of any but the
      most basic bindings between the SDID or AUID and other identities
      is not well established, nor is its vulnerability to subversion by
      an attacker.  Hence, reliance on the use of such bindings should
      be strictly limited.  In particular, it is not at all clear to
      what extent a typical end-user recipient can rely on any
      assurances that might be made by successful use of the SDID or
      AUID.






Crocker                     Standards Track                    [Page 10]

RFC 5672                    RFC 4871 Update                  August 2009


13.  RFC 4871, Section 6.3, Interpret Results/Apply Local Policy

   Original Text:

      It is beyond the scope of this specification to describe what
      actions a verifier system should make, but an authenticated email
      presents an opportunity to a receiving system that unauthenticated
      email cannot.  Specifically, an authenticated email creates a
      predictable identifier by which other decisions can reliably be
      managed, such as trust and reputation.  Conversely,
      unauthenticated email lacks a reliable identifier that can be used
      to assign trust and reputation.

   Corrected Text:

      It is beyond the scope of this specification to describe what
      actions an Identity Assessor can make, but mail carrying a
      validated SDID presents an opportunity to an Identity Assessor
      that unauthenticated email does not.  Specifically, an
      authenticated email creates a predictable identifier by which
      other decisions can reliably be managed, such as trust and
      reputation.

14.  RFC 4871, Section 6.3, Interpret Results/Apply Local Policy

   Original Text:

      Once the signature has been verified, that information MUST be
      conveyed to higher-level systems (such as explicit allow/
      whitelists and reputation systems) and/or to the end user.  If the
      message is signed on behalf of any address other than that in the
      From: header field, the mail system SHOULD take pains to ensure
      that the actual signing identity is clear to the reader.

   Corrected Text:

      Once the signature has been verified, that information MUST be
      conveyed to the Identity Assessor (such as an explicit allow/
      whitelist and reputation system) and/or to the end user.  If the
      SDID is not the same as the address in the From: header field, the
      mail system SHOULD take pains to ensure that the actual SDID is
      clear to the reader.









Crocker                     Standards Track                    [Page 11]

RFC 5672                    RFC 4871 Update                  August 2009


15.  RFC 4871, Appendix D, MUA Considerations

   Original Text:

      The tendency is to have the MUA highlight the address associated
      with this signing identity in some way, in an attempt to show the
      user the address from which the mail was sent.

   Corrected Text:

      The tendency is to have the MUA highlight the SDID, in an attempt
      to show the user the identity that is claiming responsibility for
      the message.

16.  Security Considerations

   This Update clarifies core details about DKIM's payload.  As such, it
   affects interoperability, semantic characterization, and the
   expectations for the identifiers carried with a DKIM signature.
   Clarification of these details is likely to limit misinterpretation
   of DKIM's semantics.  Since DKIM is fundamentally a security
   protocol, this should improve its security characteristics.

17.  Normative References

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, March 1997.

   [RFC3490]  Faltstrom, P., Hoffman, P., and A. Costello,
              "Internationalizing Domain Names in Applications (IDNA)",
              RFC 3490, March 2003.

   [RFC4871]  Allman, E., Callas, J., Delany, M., Libbey, M., Fenton,
              J., and M. Thomas, "DomainKeys Identified Mail (DKIM)
              Signatures", RFC 4871, May 2007.
















Crocker                     Standards Track                    [Page 12]

RFC 5672                    RFC 4871 Update                  August 2009


Appendix A.  ABNF Fragments

   This appendix contains the full set of corrected ABNF fragments
   defined in this document.

   Copyright (c) 2009 IETF Trust and the persons identified as authors
   of the code.  All rights reserved.

   Redistribution and use in source and binary forms, with or without
   modification, are permitted provided that the following conditions
   are met:

   - Redistributions of source code must retain the above copyright
     notice, this list of conditions and the following disclaimer.

   - Redistributions in binary form must reproduce the above copyright
     notice, this list of conditions and the following disclaimer in the
     documentation and/or other materials provided with the
     distribution.

   - Neither the name of Internet Society, IETF or IETF Trust, nor the
     names of specific contributors, may be used to endorse or promote
     products derived from this software without specific prior written
     permission.

   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
   'AS IS' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
   A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT
   OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

   This version of this MIB module is part of RFC 5672; see the RFC
   itself for full legal notices.

            sig-d-tag   = %x64 [FWS] "=" [FWS] domain-name
           domain-name = sub-domain 1*("." sub-domain)
                         ; from RFC 5321 Domain,
                           but excluding address-literal

            sig-i-tag =  %x69 [FWS] "=" [FWS]
                        [ Local-part ] "@" domain-name




Crocker                     Standards Track                    [Page 13]

RFC 5672                    RFC 4871 Update                  August 2009


Appendix B.  Acknowledgements

   This document was initially formulated by an ad hoc design team,
   comprising: Jon Callas, D. Crocker, J. D. Falk, Michael Hammer, Tony
   Hansen, Murray Kucherawy, John Levine, Jeff Macdonald, Ellen Siegel,
   and Wietse Venema.  The final version of the document was developed
   through vigorous discussion in the IETF DKIM working group.

Author's Address

   D. Crocker (editor)
   Brandenburg InternetWorking

   Phone: +1.408.246.8253
   EMail: dcrocker@bbiw.net




































Crocker                     Standards Track                    [Page 14]



================================================
FILE: doc/notes/rfc6376.txt
================================================






Internet Engineering Task Force (IETF)                   D. Crocker, Ed.
Request for Comments: 6376                   Brandenburg InternetWorking
Obsoletes: 4871, 5672                                     T. Hansen, Ed.
Category: Standards Track                              AT&T Laboratories
ISSN: 2070-1721                                        M. Kucherawy, Ed.
                                                               Cloudmark
                                                          September 2011


              DomainKeys Identified Mail (DKIM) Signatures

Abstract

   DomainKeys Identified Mail (DKIM) permits a person, role, or
   organization that owns the signing domain to claim some
   responsibility for a message by associating the domain with the
   message.  This can be an author's organization, an operational relay,
   or one of their agents.  DKIM separates the question of the identity
   of the Signer of the message from the purported author of the
   message.  Assertion of responsibility is validated through a
   cryptographic signature and by querying the Signer's domain directly
   to retrieve the appropriate public key.  Message transit from author
   to recipient is through relays that typically make no substantive
   change to the message content and thus preserve the DKIM signature.

   This memo obsoletes RFC 4871 and RFC 5672.

Status of This Memo

   This is an Internet Standards Track document.

   This document is a product of the Internet Engineering Task Force
   (IETF).  It represents the consensus of the IETF community.  It has
   received public review and has been approved for publication by the
   Internet Engineering Steering Group (IESG).  Further information on
   Internet Standards is available in Section 2 of RFC 5741.

   Information about the current status of this document, any errata,
   and how to provide feedback on it may be obtained at
   http://www.rfc-editor.org/info/rfc6376.

Copyright Notice

   Copyright (c) 2011 IETF Trust and the persons identified as the
   document authors.  All rights reserved.






Crocker, et al.              Standards Track                    [Page 1]

RFC 6376                     DKIM Signatures              September 2011


   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (http://trustee.ietf.org/license-info) in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.  Code Components extracted from this document must
   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

   This document may contain material from IETF Documents or IETF
   Contributions published or made publicly available before November
   10, 2008.  The person(s) controlling the copyright in some of this
   material may not have granted the IETF Trust the right to allow
   modifications of such material outside the IETF Standards Process.
   Without obtaining an adequate license from the person(s) controlling
   the copyright in such materials, this document may not be modified
   outside the IETF Standards Process, and derivative works of it may
   not be created outside the IETF Standards Process, except to format
   it for publication as an RFC or to translate it into languages other
   than English.

Table of Contents

   1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  4
     1.1.  DKIM Architecture Documents  . . . . . . . . . . . . . . .  5
     1.2.  Signing Identity . . . . . . . . . . . . . . . . . . . . .  5
     1.3.  Scalability  . . . . . . . . . . . . . . . . . . . . . . .  5
     1.4.  Simple Key Management  . . . . . . . . . . . . . . . . . .  6
     1.5.  Data Integrity . . . . . . . . . . . . . . . . . . . . . .  6
   2.  Terminology and Definitions  . . . . . . . . . . . . . . . . .  6
     2.1.  Signers  . . . . . . . . . . . . . . . . . . . . . . . . .  6
     2.2.  Verifiers  . . . . . . . . . . . . . . . . . . . . . . . .  7
     2.3.  Identity . . . . . . . . . . . . . . . . . . . . . . . . .  7
     2.4.  Identifier . . . . . . . . . . . . . . . . . . . . . . . .  7
     2.5.  Signing Domain Identifier (SDID) . . . . . . . . . . . . .  7
     2.6.  Agent or User Identifier (AUID)  . . . . . . . . . . . . .  7
     2.7.  Identity Assessor  . . . . . . . . . . . . . . . . . . . .  7
     2.8.  Whitespace . . . . . . . . . . . . . . . . . . . . . . . .  8
     2.9.  Imported ABNF Tokens . . . . . . . . . . . . . . . . . . .  8
     2.10. Common ABNF Tokens . . . . . . . . . . . . . . . . . . . .  9
     2.11. DKIM-Quoted-Printable  . . . . . . . . . . . . . . . . . .  9
   3.  Protocol Elements  . . . . . . . . . . . . . . . . . . . . . . 10
     3.1.  Selectors  . . . . . . . . . . . . . . . . . . . . . . . . 10
     3.2.  Tag=Value Lists  . . . . . . . . . . . . . . . . . . . . . 12
     3.3.  Signing and Verification Algorithms  . . . . . . . . . . . 13
     3.4.  Canonicalization . . . . . . . . . . . . . . . . . . . . . 14
     3.5.  The DKIM-Signature Header Field  . . . . . . . . . . . . . 18



Crocker, et al.              Standards Track                    [Page 2]

RFC 6376                     DKIM Signatures              September 2011


     3.6.  Key Management and Representation  . . . . . . . . . . . . 26
     3.7.  Computing the Message Hashes . . . . . . . . . . . . . . . 29
     3.8.  Input Requirements . . . . . . . . . . . . . . . . . . . . 32
     3.9.  Output Requirements  . . . . . . . . . . . . . . . . . . . 32
     3.10. Signing by Parent Domains  . . . . . . . . . . . . . . . . 33
     3.11. Relationship between SDID and AUID . . . . . . . . . . . . 33
   4.  Semantics of Multiple Signatures . . . . . . . . . . . . . . . 34
     4.1.  Example Scenarios  . . . . . . . . . . . . . . . . . . . . 34
     4.2.  Interpretation . . . . . . . . . . . . . . . . . . . . . . 35
   5.  Signer Actions . . . . . . . . . . . . . . . . . . . . . . . . 36
     5.1.  Determine Whether the Email Should Be Signed and by
           Whom . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
     5.2.  Select a Private Key and Corresponding Selector
           Information  . . . . . . . . . . . . . . . . . . . . . . . 37
     5.3.  Normalize the Message to Prevent Transport Conversions . . 37
     5.4.  Determine the Header Fields to Sign  . . . . . . . . . . . 38
     5.5.  Compute the Message Hash and Signature . . . . . . . . . . 43
     5.6.  Insert the DKIM-Signature Header Field . . . . . . . . . . 43
   6.  Verifier Actions . . . . . . . . . . . . . . . . . . . . . . . 43
     6.1.  Extract Signatures from the Message  . . . . . . . . . . . 44
     6.2.  Communicate Verification Results . . . . . . . . . . . . . 49
     6.3.  Interpret Results/Apply Local Policy . . . . . . . . . . . 50
   7.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . . 51
     7.1.  Email Authentication Methods Registry  . . . . . . . . . . 51
     7.2.  DKIM-Signature Tag Specifications  . . . . . . . . . . . . 51
     7.3.  DKIM-Signature Query Method Registry . . . . . . . . . . . 52
     7.4.  DKIM-Signature Canonicalization Registry . . . . . . . . . 52
     7.5.  _domainkey DNS TXT Resource Record Tag Specifications  . . 53
     7.6.  DKIM Key Type Registry . . . . . . . . . . . . . . . . . . 53
     7.7.  DKIM Hash Algorithms Registry  . . . . . . . . . . . . . . 54
     7.8.  DKIM Service Types Registry  . . . . . . . . . . . . . . . 54
     7.9.  DKIM Selector Flags Registry . . . . . . . . . . . . . . . 55
     7.10. DKIM-Signature Header Field  . . . . . . . . . . . . . . . 55
   8.  Security Considerations  . . . . . . . . . . . . . . . . . . . 55
     8.1.  ASCII Art Attacks  . . . . . . . . . . . . . . . . . . . . 55
     8.2.  Misuse of Body Length Limits ("l=" Tag)  . . . . . . . . . 55
     8.3.  Misappropriated Private Key  . . . . . . . . . . . . . . . 56
     8.4.  Key Server Denial-of-Service Attacks . . . . . . . . . . . 56
     8.5.  Attacks against the DNS  . . . . . . . . . . . . . . . . . 57
     8.6.  Replay/Spam Attacks  . . . . . . . . . . . . . . . . . . . 57
     8.7.  Limits on Revoking Keys  . . . . . . . . . . . . . . . . . 58
     8.8.  Intentionally Malformed Key Records  . . . . . . . . . . . 58
     8.9.  Intentionally Malformed DKIM-Signature Header Fields . . . 58
     8.10. Information Leakage  . . . . . . . . . . . . . . . . . . . 58
     8.11. Remote Timing Attacks  . . . . . . . . . . . . . . . . . . 59
     8.12. Reordered Header Fields  . . . . . . . . . . . . . . . . . 59
     8.13. RSA Attacks  . . . . . . . . . . . . . . . . . . . . . . . 59
     8.14. Inappropriate Signing by Parent Domains  . . . . . . . . . 59



Crocker, et al.              Standards Track                    [Page 3]

RFC 6376                     DKIM Signatures              September 2011


     8.15. Attacks Involving Extra Header Fields  . . . . . . . . . . 60
   9.  References . . . . . . . . . . . . . . . . . . . . . . . . . . 61
     9.1.  Normative References . . . . . . . . . . . . . . . . . . . 61
     9.2.  Informative References . . . . . . . . . . . . . . . . . . 62
   Appendix A.  Example of Use (INFORMATIVE)  . . . . . . . . . . . . 64
     A.1.  The User Composes an Email . . . . . . . . . . . . . . . . 64
     A.2.  The Email is Signed  . . . . . . . . . . . . . . . . . . . 65
     A.3.  The Email Signature is Verified  . . . . . . . . . . . . . 66
   Appendix B.  Usage Examples (INFORMATIVE)  . . . . . . . . . . . . 67
     B.1.  Alternate Submission Scenarios . . . . . . . . . . . . . . 67
     B.2.  Alternate Delivery Scenarios . . . . . . . . . . . . . . . 69
   Appendix C.  Creating a Public Key (INFORMATIVE) . . . . . . . . . 71
     C.1.  Compatibility with DomainKeys Key Records  . . . . . . . . 72
     C.2.  RFC 4871 Compatibility . . . . . . . . . . . . . . . . . . 73
   Appendix D.  MUA Considerations (INFORMATIVE)  . . . . . . . . . . 73
   Appendix E.  Changes since RFC 4871  . . . . . . . . . . . . . . . 73
   Appendix F.  Acknowledgments . . . . . . . . . . . . . . . . . . . 75

1.  Introduction

   DomainKeys Identified Mail (DKIM) permits a person, role, or
   organization to claim some responsibility for a message by
   associating a domain name [RFC1034] with the message [RFC5322], which
   they are authorized to use.  This can be an author's organization, an
   operational relay, or one of their agents.  Assertion of
   responsibility is validated through a cryptographic signature and by
   querying the Signer's domain directly to retrieve the appropriate
   public key.  Message transit from author to recipient is through
   relays that typically make no substantive change to the message
   content and thus preserve the DKIM signature.  A message can contain
   multiple signatures, from the same or different organizations
   involved with the message.

   The approach taken by DKIM differs from previous approaches to
   message signing (e.g., Secure/Multipurpose Internet Mail Extensions
   (S/MIME) [RFC5751], OpenPGP [RFC4880]) in that:

   o  the message signature is written as a message header field so that
      neither human recipients nor existing MUA (Mail User Agent)
      software is confused by signature-related content appearing in the
      message body;

   o  there is no dependency on public- and private-key pairs being
      issued by well-known, trusted certificate authorities;

   o  there is no dependency on the deployment of any new Internet
      protocols or services for public-key distribution or revocation;




Crocker, et al.              Standards Track                    [Page 4]

RFC 6376                     DKIM Signatures              September 2011


   o  signature verification failure does not force rejection of the
      message;

   o  no attempt is made to include encryption as part of the mechanism;
      and

   o  message archiving is not a design goal.

   DKIM:

   o  is compatible with the existing email infrastructure and
      transparent to the fullest extent possible;

   o  requires minimal new infrastructure;

   o  can be implemented independently of clients in order to reduce
      deployment time;

   o  can be deployed incrementally; and

   o  allows delegation of signing to third parties.

1.1.  DKIM Architecture Documents

   Readers are advised to be familiar with the material in [RFC4686],
   [RFC5585], and [RFC5863], which provide the background for the
   development of DKIM, an overview of the service, and deployment and
   operations guidance and advice, respectively.

1.2.  Signing Identity

   DKIM separates the question of the identity of the Signer of the
   message from the purported author of the message.  In particular, a
   signature includes the identity of the Signer.  Verifiers can use the
   signing information to decide how they want to process the message.
   The signing identity is included as part of the signature header
   field.

      INFORMATIVE RATIONALE: The signing identity specified by a DKIM
      signature is not required to match an address in any particular
      header field because of the broad methods of interpretation by
      recipient mail systems, including MUAs.

1.3.  Scalability

   DKIM is designed to support the extreme scalability requirements that
   characterize the email identification problem.  There are many
   millions of domains and a much larger number of individual addresses.



Crocker, et al.              Standards Track                    [Page 5]

RFC 6376                     DKIM Signatures              September 2011


   DKIM seeks to preserve the positive aspects of the current email
   infrastructure, such as the ability for anyone to communicate with
   anyone else without introduction.

1.4.  Simple Key Management

   DKIM differs from traditional hierarchical public-key systems in that
   no certificate authority infrastructure is required; the Verifier
   requests the public key from a repository in the domain of the
   claimed Signer directly rather than from a third party.

   The DNS is proposed as the initial mechanism for the public keys.
   Thus, DKIM currently depends on DNS administration and the security
   of the DNS system.  DKIM is designed to be extensible to other key
   fetching services as they become available.

1.5.  Data Integrity

   A DKIM signature associates the "d=" name with the computed hash of
   some or all of the message (see Section 3.7) in order to prevent the
   reuse of the signature with different messages.  Verifying the
   signature asserts that the hashed content has not changed since it
   was signed and asserts nothing else about "protecting" the end-to-end
   integrity of the message.

2.  Terminology and Definitions

   This section defines terms used in the rest of the document.

   DKIM is designed to operate within the Internet Mail service, as
   defined in [RFC5598].  Basic email terminology is taken from that
   specification.

   Syntax descriptions use Augmented BNF (ABNF) [RFC5234].

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
   "OPTIONAL" in this document are to be interpreted as described in
   [RFC2119].  These words take their normative meanings only when they
   are presented in ALL UPPERCASE.

2.1.  Signers

   Elements in the mail system that sign messages on behalf of a domain
   are referred to as Signers.  These may be MUAs (Mail User Agents),
   MSAs (Mail Submission Agents), MTAs (Mail Transfer Agents), or other
   agents such as mailing list exploders.  In general, any Signer will




Crocker, et al.              Standards Track                    [Page 6]

RFC 6376                     DKIM Signatures              September 2011


   be involved in the injection of a message into the message system in
   some way.  The key issue is that a message must be signed before it
   leaves the administrative domain of the Signer.

2.2.  Verifiers

   Elements in the mail system that verify signatures are referred to as
   Verifiers.  These may be MTAs, Mail Delivery Agents (MDAs), or MUAs.
   In most cases, it is expected that Verifiers will be close to an end
   user (reader) of the message or some consuming agent such as a
   mailing list exploder.

2.3.  Identity

   A person, role, or organization.  In the context of DKIM, examples
   include the author, the author's organization, an ISP along the
   handling path, an independent trust assessment service, and a mailing
   list operator.

2.4.  Identifier

   A label that refers to an identity.

2.5.  Signing Domain Identifier (SDID)

   A single domain name that is the mandatory payload output of DKIM and
   that refers to the identity claiming some responsibility for the
   message by signing it.  It is specified in Section 3.5.

2.6.  Agent or User Identifier (AUID)

   A single identifier that refers to the agent or user on behalf of
   whom the Signing Domain Identifier (SDID) has taken responsibility.
   The AUID comprises a domain name and an optional <local-part>.  The
   domain name is the same as that used for the SDID or is a subdomain
   of it.  For DKIM processing, the domain name portion of the AUID has
   only basic domain name semantics; any possible owner-specific
   semantics are outside the scope of DKIM.  It is specified in
   Section 3.5.

   Note that acceptable values for the AUID may be constrained via a
   flag in the public-key record.  (See Section 3.6.1.)

2.7.  Identity Assessor

   An element in the mail system that consumes DKIM's payload, which is
   the responsible Signing Domain Identifier (SDID).  The Identity
   Assessor is dedicated to the assessment of the delivered identifier.



Crocker, et al.              Standards Track                    [Page 7]

RFC 6376                     DKIM Signatures              September 2011


   Other DKIM (and non-DKIM) values can also be used by the Identity
   Assessor (if they are available) to provide a more general message
   evaluation filtering engine.  However, this additional activity is
   outside the scope of this specification.

2.8.  Whitespace

   There are three forms of whitespace:

   o  WSP represents simple whitespace, i.e., a space or a tab character
      (formal definition in [RFC5234]).

   o  LWSP is linear whitespace, defined as WSP plus CRLF (formal
      definition in [RFC5234]).

   o  FWS is folding whitespace.  It allows multiple lines separated by
      CRLF followed by at least one whitespace, to be joined.

   The formal ABNF for these are (WSP and LWSP are given for information
   only):

   WSP =   SP / HTAB
   LWSP =  *(WSP / CRLF WSP)
   FWS =   [*WSP CRLF] 1*WSP

   The definition of FWS is identical to that in [RFC5322] except for
   the exclusion of obs-FWS.

2.9.  Imported ABNF Tokens

   The following tokens are imported from other RFCs as noted.  Those
   RFCs should be considered definitive.

   The following tokens are imported from [RFC5321]:

   o  "local-part" (implementation warning: this permits quoted strings)

   o  "sub-domain"

   The following tokens are imported from [RFC5322]:

   o  "field-name" (name of a header field)

   o  "dot-atom-text" (in the local-part of an email address)

   The following tokens are imported from [RFC2045]:

   o  "qp-section" (a single line of quoted-printable-encoded text)



Crocker, et al.              Standards Track                    [Page 8]

RFC 6376                     DKIM Signatures              September 2011


   o  "hex-octet" (a quoted-printable encoded octet)

      INFORMATIVE NOTE: Be aware that the ABNF in [RFC2045] does not
      obey the rules of [RFC5234] and must be interpreted accordingly,
      particularly as regards case folding.

   Other tokens not defined herein are imported from [RFC5234].  These
   are intuitive primitives such as SP, HTAB, WSP, ALPHA, DIGIT, CRLF,
   etc.

2.10.  Common ABNF Tokens

   The following ABNF tokens are used elsewhere in this document:

   hyphenated-word =  ALPHA [ *(ALPHA / DIGIT / "-") (ALPHA / DIGIT) ]
   ALPHADIGITPS    =  (ALPHA / DIGIT / "+" / "/")
   base64string    =  ALPHADIGITPS *([FWS] ALPHADIGITPS)
                      [ [FWS] "=" [ [FWS] "=" ] ]
   hdr-name        =  field-name
   qp-hdr-value    =  dkim-quoted-printable    ; with "|" encoded

2.11.  DKIM-Quoted-Printable

   The DKIM-Quoted-Printable encoding syntax resembles that described in
   Quoted-Printable [RFC2045], Section 6.7: any character MAY be encoded
   as an "=" followed by two hexadecimal digits from the alphabet
   "0123456789ABCDEF" (no lowercase characters permitted) representing
   the hexadecimal-encoded integer value of that character.  All control
   characters (those with values < %x20), 8-bit characters (values >
   %x7F), and the characters DEL (%x7F), SPACE (%x20), and semicolon
   (";", %x3B) MUST be encoded.  Note that all whitespace, including
   SPACE, CR, and LF characters, MUST be encoded.  After encoding, FWS
   MAY be added at arbitrary locations in order to avoid excessively
   long lines; such whitespace is NOT part of the value, and MUST be
   removed before decoding.  Use of characters not listed as "mail-safe"
   in [RFC2049] is NOT RECOMMENDED.

   ABNF:

   dkim-quoted-printable =  *(FWS / hex-octet / dkim-safe-char)
                               ; hex-octet is from RFC2045
   dkim-safe-char        =  %x21-3A / %x3C / %x3E-7E
                               ; '!' - ':', '<', '>' - '~'








Crocker, et al.              Standards Track                    [Page 9]

RFC 6376                     DKIM Signatures              September 2011


      INFORMATIVE NOTE: DKIM-Quoted-Printable differs from Quoted-
      Printable as defined in [RFC2045] in several important ways:

      1.  Whitespace in the input text, including CR and LF, must be
          encoded.  [RFC2045] does not require such encoding, and does
          not permit encoding of CR or LF characters that are part of a
          CRLF line break.

      2.  Whitespace in the encoded text is ignored.  This is to allow
          tags encoded using DKIM-Quoted-Printable to be wrapped as
          needed.  In particular, [RFC2045] requires that line breaks in
          the input be represented as physical line breaks; that is not
          the case here.

      3.  The "soft line break" syntax ("=" as the last non-whitespace
          character on the line) does not apply.

      4.  DKIM-Quoted-Printable does not require that encoded lines be
          no more than 76 characters long (although there may be other
          requirements depending on the context in which the encoded
          text is being used).

3.  Protocol Elements

   Protocol Elements are conceptual parts of the protocol that are not
   specific to either Signers or Verifiers.  The protocol descriptions
   for Signers and Verifiers are described in later sections ("Signer
   Actions" (Section 5) and "Verifier Actions" (Section 6)).  NOTE: This
   section must be read in the context of those sections.

3.1.  Selectors

   To support multiple concurrent public keys per signing domain, the
   key namespace is subdivided using "selectors".  For example,
   selectors might indicate the names of office locations (e.g.,
   "sanfrancisco", "coolumbeach", and "reykjavik"), the signing date
   (e.g., "january2005", "february2005", etc.), or even an individual
   user.

   Selectors are needed to support some important use cases.  For
   example:

   o  Domains that want to delegate signing capability for a specific
      address for a given duration to a partner, such as an advertising
      provider or other outsourced function.

   o  Domains that want to allow frequent travelers to send messages
      locally without the need to connect with a particular MSA.



Crocker, et al.              Standards Track                   [Page 10]

RFC 6376                     DKIM Signatures              September 2011


   o  "Affinity" domains (e.g., college alumni associations) that
      provide forwarding of incoming mail, but that do not operate a
      mail submission agent for outgoing mail.

   Periods are allowed in selectors and are component separators.  When
   keys are retrieved from the DNS, periods in selectors define DNS
   label boundaries in a manner similar to the conventional use in
   domain names.  Selector components might be used to combine dates
   with locations, for example, "march2005.reykjavik".  In a DNS
   implementation, this can be used to allow delegation of a portion of
   the selector namespace.

   ABNF:

   selector =   sub-domain *( "." sub-domain )

   The number of public keys and corresponding selectors for each domain
   is determined by the domain owner.  Many domain owners will be
   satisfied with just one selector, whereas administratively
   distributed organizations can choose to manage disparate selectors
   and key pairs in different regions or on different email servers.

   Beyond administrative convenience, selectors make it possible to
   seamlessly replace public keys on a routine basis.  If a domain
   wishes to change from using a public key associated with selector
   "january2005" to a public key associated with selector
   "february2005", it merely makes sure that both public keys are
   advertised in the public-key repository concurrently for the
   transition period during which email may be in transit prior to
   verification.  At the start of the transition period, the outbound
   email servers are configured to sign with the "february2005" private
   key.  At the end of the transition period, the "january2005" public
   key is removed from the public-key repository.

      INFORMATIVE NOTE: A key may also be revoked as described below.
      The distinction between revoking and removing a key selector
      record is subtle.  When phasing out keys as described above, a
      signing domain would probably simply remove the key record after
      the transition period.  However, a signing domain could elect to
      revoke the key (but maintain the key record) for a further period.
      There is no defined semantic difference between a revoked key and
      a removed key.

   While some domains may wish to make selector values well-known,
   others will want to take care not to allocate selector names in a way
   that allows harvesting of data by outside parties.  For example, if
   per-user keys are issued, the domain owner will need to decide




Crocker, et al.              Standards Track                   [Page 11]

RFC 6376                     DKIM Signatures              September 2011


   whether to associate this selector directly with the name of a
   registered end user or make it some unassociated random value, such
   as a fingerprint of the public key.

      INFORMATIVE OPERATIONS NOTE: Reusing a selector with a new key
      (for example, changing the key associated with a user's name)
      makes it impossible to tell the difference between a message that
      didn't verify because the key is no longer valid and a message
      that is actually forged.  For this reason, Signers are ill-advised
      to reuse selectors for new keys.  A better strategy is to assign
      new keys to new selectors.

3.2.  Tag=Value Lists

   DKIM uses a simple "tag=value" syntax in several contexts, including
   in messages and domain signature records.

   Values are a series of strings containing either plain text, "base64"
   text (as defined in [RFC2045], Section 6.8), "qp-section" (ibid,
   Section 6.7), or "dkim-quoted-printable" (as defined in
   Section 2.11).  The name of the tag will determine the encoding of
   each value.  Unencoded semicolon (";") characters MUST NOT occur in
   the tag value, since that separates tag-specs.

      INFORMATIVE IMPLEMENTATION NOTE: Although the "plain text" defined
      below (as "tag-value") only includes 7-bit characters, an
      implementation that wished to anticipate future standards would be
      advised not to preclude the use of UTF-8-encoded ([RFC3629]) text
      in tag=value lists.

   Formally, the ABNF syntax rules are as follows:

   tag-list  =  tag-spec *( ";" tag-spec ) [ ";" ]
   tag-spec  =  [FWS] tag-name [FWS] "=" [FWS] tag-value [FWS]
   tag-name  =  ALPHA *ALNUMPUNC
   tag-value =  [ tval *( 1*(WSP / FWS) tval ) ]
                     ; Prohibits WSP and FWS at beginning and end
   tval      =  1*VALCHAR
   VALCHAR   =  %x21-3A / %x3C-7E
                     ; EXCLAMATION to TILDE except SEMICOLON
   ALNUMPUNC =  ALPHA / DIGIT / "_"

   Note that WSP is allowed anywhere around tags.  In particular, any
   WSP after the "=" and any WSP before the terminating ";" is not part
   of the value; however, WSP inside the value is significant.






Crocker, et al.              Standards Track                   [Page 12]

RFC 6376                     DKIM Signatures              September 2011


   Tags MUST be interpreted in a case-sensitive manner.  Values MUST be
   processed as case sensitive unless the specific tag description of
   semantics specifies case insensitivity.

   Tags with duplicate names MUST NOT occur within a single tag-list; if
   a tag name does occur more than once, the entire tag-list is invalid.

   Whitespace within a value MUST be retained unless explicitly excluded
   by the specific tag description.

   Tag=value pairs that represent the default value MAY be included to
   aid legibility.

   Unrecognized tags MUST be ignored.

   Tags that have an empty value are not the same as omitted tags.  An
   omitted tag is treated as having the default value; a tag with an
   empty value explicitly designates the empty string as the value.

3.3.  Signing and Verification Algorithms

   DKIM supports multiple digital signature algorithms.  Two algorithms
   are defined by this specification at this time: rsa-sha1 and rsa-
   sha256.  Signers MUST implement and SHOULD sign using rsa-sha256.
   Verifiers MUST implement both rsa-sha1 and rsa-sha256.

      INFORMATIVE NOTE: Although rsa-sha256 is strongly encouraged, some
      senders might prefer to use rsa-sha1 when balancing security
      strength against performance, complexity, or other needs.  In
      general, however, rsa-sha256 should always be used whenever
      possible.

3.3.1.  The rsa-sha1 Signing Algorithm

   The rsa-sha1 Signing Algorithm computes a message hash as described
   in Section 3.7 using SHA-1 [FIPS-180-3-2008] as the hash-alg.  That
   hash is then signed by the Signer using the RSA algorithm (defined in
   Public-Key Cryptography Standards (PKCS) #1 version 1.5 [RFC3447]) as
   the crypt-alg and the Signer's private key.  The hash MUST NOT be
   truncated or converted into any form other than the native binary
   form before being signed.  The signing algorithm SHOULD use a public
   exponent of 65537.

3.3.2.  The rsa-sha256 Signing Algorithm

   The rsa-sha256 Signing Algorithm computes a message hash as described
   in Section 3.7 using SHA-256 [FIPS-180-3-2008] as the hash-alg.  That
   hash is then signed by the Signer using the RSA algorithm (defined in



Crocker, et al.              Standards Track                   [Page 13]

RFC 6376                     DKIM Signatures              September 2011


   PKCS#1 version 1.5 [RFC3447]) as the crypt-alg and the Signer's
   private key.  The hash MUST NOT be truncated or converted into any
   form other than the native binary form before being signed.  The
   signing algorithm SHOULD use a public exponent of 65537.

3.3.3.  Key Sizes

   Selecting appropriate key sizes is a trade-off between cost,
   performance, and risk.  Since short RSA keys more easily succumb to
   off-line attacks, Signers MUST use RSA keys of at least 1024 bits for
   long-lived keys.  Verifiers MUST be able to validate signatures with
   keys ranging from 512 bits to 2048 bits, and they MAY be able to
   validate signatures with larger keys.  Verifier policies may use the
   length of the signing key as one metric for determining whether a
   signature is acceptable.

   Factors that should influence the key size choice include the
   following:

   o  The practical constraint that large (e.g., 4096-bit) keys might
      not fit within a 512-byte DNS UDP response packet

   o  The security constraint that keys smaller than 1024 bits are
      subject to off-line attacks

   o  Larger keys impose higher CPU costs to verify and sign email

   o  Keys can be replaced on a regular basis; thus, their lifetime can
      be relatively short

   o  The security goals of this specification are modest compared to
      typical goals of other systems that employ digital signatures

   See [RFC3766] for further discussion on selecting key sizes.

3.3.4.  Other Algorithms

   Other algorithms MAY be defined in the future.  Verifiers MUST ignore
   any signatures using algorithms that they do not implement.

3.4.  Canonicalization

   Some mail systems modify email in transit, potentially invalidating a
   signature.  For most Signers, mild modification of email is
   immaterial to validation of the DKIM domain name's use.  For such
   Signers, a canonicalization algorithm that survives modest in-transit
   modification is preferred.




Crocker, et al.              Standards Track                   [Page 14]

RFC 6376                     DKIM Signatures              September 2011


   Other Signers demand that any modification of the email, however
   minor, result in a signature verification failure.  These Signers
   prefer a canonicalization algorithm that does not tolerate in-transit
   modification of the signed email.

   Some Signers may be willing to accept modifications to header fields
   that are within the bounds of email standards such as [RFC5322], but
   are unwilling to accept any modification to the body of messages.

   To satisfy all requirements, two canonicalization algorithms are
   defined for each of the header and the body: a "simple" algorithm
   that tolerates almost no modification and a "relaxed" algorithm that
   tolerates common modifications such as whitespace replacement and
   header field line rewrapping.  A Signer MAY specify either algorithm
   for header or body when signing an email.  If no canonicalization
   algorithm is specified by the Signer, the "simple" algorithm defaults
   for both header and body.  Verifiers MUST implement both
   canonicalization algorithms.  Note that the header and body may use
   different canonicalization algorithms.  Further canonicalization
   algorithms MAY be defined in the future; Verifiers MUST ignore any
   signatures that use unrecognized canonicalization algorithms.

   Canonicalization simply prepares the email for presentation to the
   signing or verification algorithm.  It MUST NOT change the
   transmitted data in any way.  Canonicalization of header fields and
   body are described below.

   NOTE: This section assumes that the message is already in "network
   normal" format (text is ASCII encoded, lines are separated with CRLF
   characters, etc.).  See also Section 5.3 for information about
   normalizing the message.

3.4.1.  The "simple" Header Canonicalization Algorithm

   The "simple" header canonicalization algorithm does not change header
   fields in any way.  Header fields MUST be presented to the signing or
   verification algorithm exactly as they are in the message being
   signed or verified.  In particular, header field names MUST NOT be
   case folded and whitespace MUST NOT be changed.

3.4.2.  The "relaxed" Header Canonicalization Algorithm

   The "relaxed" header canonicalization algorithm MUST apply the
   following steps in order:

   o  Convert all header field names (not the header field values) to
      lowercase.  For example, convert "SUBJect: AbC" to "subject: AbC".




Crocker, et al.              Standards Track                   [Page 15]

RFC 6376                     DKIM Signatures              September 2011


   o  Unfold all header field continuation lines as described in
      [RFC5322]; in particular, lines with terminators embedded in
      continued header field values (that is, CRLF sequences followed by
      WSP) MUST be interpreted without the CRLF.  Implementations MUST
      NOT remove the CRLF at the end of the header field value.

   o  Convert all sequences of one or more WSP characters to a single SP
      character.  WSP characters here include those before and after a
      line folding boundary.

   o  Delete all WSP characters at the end of each unfolded header field
      value.

   o  Delete any WSP characters remaining before and after the colon
      separating the header field name from the header field value.  The
      colon separator MUST be retained.

3.4.3.  The "simple" Body Canonicalization Algorithm

   The "simple" body canonicalization algorithm ignores all empty lines
   at the end of the message body.  An empty line is a line of zero
   length after removal of the line terminator.  If there is no body or
   no trailing CRLF on the message body, a CRLF is added.  It makes no
   other changes to the message body.  In more formal terms, the
   "simple" body canonicalization algorithm converts "*CRLF" at the end
   of the body to a single "CRLF".

   Note that a completely empty or missing body is canonicalized as a
   single "CRLF"; that is, the canonicalized length will be 2 octets.

   The SHA-1 value (in base64) for an empty body (canonicalized to a
   "CRLF") is:

   uoq1oCgLlTqpdDX/iUbLy7J1Wic=

   The SHA-256 value is:

   frcCV1k9oG9oKj3dpUqdJg1PxRT2RSN/XKdLCPjaYaY=

3.4.4.  The "relaxed" Body Canonicalization Algorithm

   The "relaxed" body canonicalization algorithm MUST apply the
   following steps (a) and (b) in order:

   a.  Reduce whitespace:

       *  Ignore all whitespace at the end of lines.  Implementations
          MUST NOT remove the CRLF at the end of the line.



Crocker, et al.              Standards Track                   [Page 16]

RFC 6376                     DKIM Signatures              September 2011


       *  Reduce all sequences of WSP within a line to a single SP
          character.

   b.  Ignore all empty lines at the end of the message body.  "Empty
       line" is defined in Section 3.4.3.  If the body is non-empty but
       does not end with a CRLF, a CRLF is added.  (For email, this is
       only possible when using extensions to SMTP or non-SMTP transport
       mechanisms.)

   The SHA-1 value (in base64) for an empty body (canonicalized to a
   null input) is:

   2jmj7l5rSw0yVb/vlWAYkK/YBwk=

   The SHA-256 value is:

   47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=

3.4.5.  Canonicalization Examples (INFORMATIVE)

   In the following examples, actual whitespace is used only for
   clarity.  The actual input and output text is designated using
   bracketed descriptors: "<SP>" for a space character, "<HTAB>" for a
   tab character, and "<CRLF>" for a carriage-return/line-feed sequence.
   For example, "X <SP> Y" and "X<SP>Y" represent the same three
   characters.

   Example 1: A message reading:

   A: <SP> X <CRLF>
   B <SP> : <SP> Y <HTAB><CRLF>
                   <HTAB> Z <SP><SP><CRLF>
   <CRLF>
   <SP> C <SP><CRLF>
   D <SP><HTAB><SP> E <CRLF>
   <CRLF>
   <CRLF>

   when canonicalized using relaxed canonicalization for both header and
   body results in a header reading:

   a:X <CRLF>
   b:Y <SP> Z <CRLF>

   and a body reading:

   <SP> C <CRLF>
   D <SP> E <CRLF>



Crocker, et al.              Standards Track                   [Page 17]

RFC 6376                     DKIM Signatures              September 2011


   Example 2: The same message canonicalized using simple
   canonicalization for both header and body results in a header
   reading:

   A: <SP> X <CRLF>
   B <SP> : <SP> Y <HTAB><CRLF>
          <HTAB> Z <SP><SP><CRLF>

   and a body reading:

   <SP> C <SP><CRLF>
   D <SP><HTAB><SP> E <CRLF>

   Example 3: When processed using relaxed header canonicalization and
   simple body canonicalization, the canonicalized version has a header
   of:

   a:X <CRLF>
   b:Y <SP> Z <CRLF>

   and a body reading:

   <SP> C <SP><CRLF>
   D <SP><HTAB><SP> E <CRLF>

3.5.  The DKIM-Signature Header Field

   The signature of the email is stored in the DKIM-Signature header
   field.  This header field contains all of the signature and key-
   fetching data.  The DKIM-Signature value is a tag-list as described
   in Section 3.2.

   The DKIM-Signature header field SHOULD be treated as though it were a
   trace header field as defined in Section 3.6 of [RFC5322] and hence
   SHOULD NOT be reordered and SHOULD be prepended to the message.

   The DKIM-Signature header field being created or verified is always
   included in the signature calculation, after the rest of the header
   fields being signed; however, when calculating or verifying the
   signature, the value of the "b=" tag (signature value) of that DKIM-
   Signature header field MUST be treated as though it were an empty
   string.  Unknown tags in the DKIM-Signature header field MUST be
   included in the signature calculation but MUST be otherwise ignored
   by Verifiers.  Other DKIM-Signature header fields that are included
   in the signature should be treated as normal header fields; in
   particular, the "b=" tag is not treated specially.





Crocker, et al.              Standards Track                   [Page 18]

RFC 6376                     DKIM Signatures              September 2011


   The encodings for each field type are listed below.  Tags described
   as qp-section are encoded as described in Section 6.7 of MIME Part
   One [RFC2045], with the additional conversion of semicolon characters
   to "=3B"; intuitively, this is one line of quoted-printable encoded
   text.  The dkim-quoted-printable syntax is defined in Section 2.11.

   Tags on the DKIM-Signature header field along with their type and
   requirement status are shown below.  Unrecognized tags MUST be
   ignored.

   v= Version (plain-text; REQUIRED).  This tag defines the version of
      this specification that applies to the signature record.  It MUST
      have the value "1" for implementations compliant with this version
      of DKIM.

      ABNF:

      sig-v-tag       = %x76 [FWS] "=" [FWS] 1*DIGIT

         INFORMATIVE NOTE: DKIM-Signature version numbers may increase
         arithmetically as new versions of this specification are
         released.

   a= The algorithm used to generate the signature (plain-text;
      REQUIRED).  Verifiers MUST support "rsa-sha1" and "rsa-sha256";
      Signers SHOULD sign using "rsa-sha256".  See Section 3.3 for a
      description of the algorithms.

      ABNF:

      sig-a-tag       = %x61 [FWS] "=" [FWS] sig-a-tag-alg
      sig-a-tag-alg   = sig-a-tag-k "-" sig-a-tag-h
      sig-a-tag-k     = "rsa" / x-sig-a-tag-k
      sig-a-tag-h     = "sha1" / "sha256" / x-sig-a-tag-h
      x-sig-a-tag-k   = ALPHA *(ALPHA / DIGIT)
                           ; for later extension
      x-sig-a-tag-h   = ALPHA *(ALPHA / DIGIT)
                           ; for later extension

   b= The signature data (base64; REQUIRED).  Whitespace is ignored in
      this value and MUST be ignored when reassembling the original
      signature.  In particular, the signing process can safely insert
      FWS in this value in arbitrary places to conform to line-length
      limits.  See "Signer Actions" (Section 5) for how the signature is
      computed.






Crocker, et al.              Standards Track                   [Page 19]

RFC 6376                     DKIM Signatures              September 2011


      ABNF:

      sig-b-tag       = %x62 [FWS] "=" [FWS] sig-b-tag-data
      sig-b-tag-data  = base64string

   bh=  The hash of the canonicalized body part of the message as
      limited by the "l=" tag (base64; REQUIRED).  Whitespace is ignored
      in this value and MUST be ignored when reassembling the original
      signature.  In particular, the signing process can safely insert
      FWS in this value in arbitrary places to conform to line-length
      limits.  See Section 3.7 for how the body hash is computed.

      ABNF:

      sig-bh-tag      = %x62 %x68 [FWS] "=" [FWS] sig-bh-tag-data
      sig-bh-tag-data = base64string

   c= Message canonicalization (plain-text; OPTIONAL, default is
      "simple/simple").  This tag informs the Verifier of the type of
      canonicalization used to prepare the message for signing.  It
      consists of two names separated by a "slash" (%d47) character,
      corresponding to the header and body canonicalization algorithms,
      respectively.  These algorithms are described in Section 3.4.  If
      only one algorithm is named, that algorithm is used for the header
      and "simple" is used for the body.  For example, "c=relaxed" is
      treated the same as "c=relaxed/simple".

      ABNF:

      sig-c-tag       = %x63 [FWS] "=" [FWS] sig-c-tag-alg
                        ["/" sig-c-tag-alg]
      sig-c-tag-alg   = "simple" / "relaxed" / x-sig-c-tag-alg
      x-sig-c-tag-alg = hyphenated-word    ; for later extension

   d= The SDID claiming responsibility for an introduction of a message
      into the mail stream (plain-text; REQUIRED).  Hence, the SDID
      value is used to form the query for the public key.  The SDID MUST
      correspond to a valid DNS name under which the DKIM key record is
      published.  The conventions and semantics used by a Signer to
      create and use a specific SDID are outside the scope of this
      specification, as is any use of those conventions and semantics.
      When presented with a signature that does not meet these
      requirements, Verifiers MUST consider the signature invalid.

      Internationalized domain names MUST be encoded as A-labels, as
      described in Section 2.3 of [RFC5890].





Crocker, et al.              Standards Track                   [Page 20]

RFC 6376                     DKIM Signatures              September 2011


      ABNF:

      sig-d-tag       = %x64 [FWS] "=" [FWS] domain-name
      domain-name     = sub-domain 1*("." sub-domain)
                        ; from [RFC5321] Domain,
                        ; excluding address-literal

   h= Signed header fields (plain-text, but see description; REQUIRED).
      A colon-separated list of header field names that identify the
      header fields presented to the signing algorithm.  The field MUST
      contain the complete list of header fields in the order presented
      to the signing algorithm.  The field MAY contain names of header
      fields that do not exist when signed; nonexistent header fields do
      not contribute to the signature computation (that is, they are
      treated as the null input, including the header field name, the
      separating colon, the header field value, and any CRLF
      terminator).  The field MAY contain multiple instances of a header
      field name, meaning multiple occurrences of the corresponding
      header field are included in the header hash.  The field MUST NOT
      include the DKIM-Signature header field that is being created or
      verified but may include others.  Folding whitespace (FWS) MAY be
      included on either side of the colon separator.  Header field
      names MUST be compared against actual header field names in a
      case-insensitive manner.  This list MUST NOT be empty.  See
      Section 5.4 for a discussion of choosing header fields to sign and
      Section 5.4.2 for requirements when signing multiple instances of
      a single field.

      ABNF:

      sig-h-tag       = %x68 [FWS] "=" [FWS] hdr-name
                         *( [FWS] ":" [FWS] hdr-name )

         INFORMATIVE EXPLANATION: By "signing" header fields that do not
         actually exist, a Signer can allow a Verifier to detect
         insertion of those header fields after signing.  However, since
         a Signer cannot possibly know what header fields might be
         defined in the future, this mechanism cannot be used to prevent
         the addition of any possible unknown header fields.

         INFORMATIVE NOTE: "Signing" fields that are not present at the
         time of signing not only prevents fields and values from being
         added but also prevents adding fields with no values.

   i= The Agent or User Identifier (AUID) on behalf of which the SDID is
      taking responsibility (dkim-quoted-printable; OPTIONAL, default is
      an empty local-part followed by an "@" followed by the domain from
      the "d=" tag).



Crocker, et al.              Standards Track                   [Page 21]

RFC 6376                     DKIM Signatures              September 2011


      The syntax is a standard email address where the local-part MAY be
      omitted.  The domain part of the address MUST be the same as, or a
      subdomain of, the value of the "d=" tag.

      Internationalized domain names MUST be encoded as A-labels, as
      described in Section 2.3 of [RFC5890].

      ABNF:

      sig-i-tag       = %x69 [FWS] "=" [FWS] [ Local-part ]
                                 "@" domain-name

      The AUID is specified as having the same syntax as an email
      address but it need not have the same semantics.  Notably, the
      domain name need not be registered in the DNS -- so it might not
      resolve in a query -- and the local-part MAY be drawn from a
      namespace unrelated to any mailbox.  The details of the structure
      and semantics for the namespace are determined by the Signer.  Any
      knowledge or use of those details by Verifiers or Assessors is
      outside the scope of this specification.  The Signer MAY choose to
      use the same namespace for its AUIDs as its users' email addresses
      or MAY choose other means of representing its users.  However, the
      Signer SHOULD use the same AUID for each message intended to be
      evaluated as being within the same sphere of responsibility, if it
      wishes to offer receivers the option of using the AUID as a stable
      identifier that is finer grained than the SDID.

         INFORMATIVE NOTE: The local-part of the "i=" tag is optional
         because in some cases a Signer may not be able to establish a
         verified individual identity.  In such cases, the Signer might
         wish to assert that although it is willing to go as far as
         signing for the domain, it is unable or unwilling to commit to
         an individual user name within the domain.  It can do so by
         including the domain part but not the local-part of the
         identity.

         INFORMATIVE DISCUSSION: This specification does not require the
         value of the "i=" tag to match the identity in any message
         header fields.  This is considered to be a Verifier policy
         issue.  Constraints between the value of the "i=" tag and other
         identities in other header fields seek to apply basic
         authentication into the semantics of trust associated with a
         role such as content author.  Trust is a broad and complex
         topic, and trust mechanisms are subject to highly creative
         attacks.  The real-world efficacy of any but the most basic
         bindings between the "i=" value and other identities is not
         well established, nor is its vulnerability to subversion by an
         attacker.  Hence, reliance on the use of these options should



Crocker, et al.              Standards Track                   [Page 22]

RFC 6376                     DKIM Signatures              September 2011


         be strictly limited.  In particular, it is not at all clear to
         what extent a typical end-user recipient can rely on any
         assurances that might be made by successful use of the "i="
         options.

   l= Body length count (plain-text unsigned decimal integer; OPTIONAL,
      default is entire body).  This tag informs the Verifier of the
      number of octets in the body of the email after canonicalization
      included in the cryptographic hash, starting from 0 immediately
      following the CRLF preceding the body.  This value MUST NOT be
      larger than the actual number of octets in the canonicalized
      message body.  See further discussion in Section 8.2.

         INFORMATIVE NOTE: The value of the "l=" tag is constrained to
         76 decimal digits.  This constraint is not intended to predict
         the size of future messages or to require implementations to
         use an integer representation large enough to represent the
         maximum possible value but is intended to remind the
         implementer to check the length of this and all other tags
         during verification and to test for integer overflow when
         decoding the value.  Implementers may need to limit the actual
         value expressed to a value smaller than 10^76, e.g., to allow a
         message to fit within the available storage space.

      ABNF:

      sig-l-tag    = %x6c [FWS] "=" [FWS]
                     1*76DIGIT

   q= A colon-separated list of query methods used to retrieve the
      public key (plain-text; OPTIONAL, default is "dns/txt").  Each
      query method is of the form "type[/options]", where the syntax and
      semantics of the options depend on the type and specified options.
      If there are multiple query mechanisms listed, the choice of query
      mechanism MUST NOT change the interpretation of the signature.
      Implementations MUST use the recognized query mechanisms in the
      order presented.  Unrecognized query mechanisms MUST be ignored.

      Currently, the only valid value is "dns/txt", which defines the
      DNS TXT resource record (RR) lookup algorithm described elsewhere
      in this document.  The only option defined for the "dns" query
      type is "txt", which MUST be included.  Verifiers and Signers MUST
      support "dns/txt".

      ABNF:

      sig-q-tag        = %x71 [FWS] "=" [FWS] sig-q-tag-method
                            *([FWS] ":" [FWS] sig-q-tag-method)



Crocker, et al.              Standards Track                   [Page 23]

RFC 6376                     DKIM Signatures              September 2011


      sig-q-tag-method = "dns/txt" / x-sig-q-tag-type
                         ["/" x-sig-q-tag-args]
      x-sig-q-tag-type = hyphenated-word  ; for future extension
      x-sig-q-tag-args = qp-hdr-value

   s= The selector subdividing the namespace for the "d=" (domain) tag
      (plain-text; REQUIRED).

      Internationalized selector names MUST be encoded as A-labels, as
      described in Section 2.3 of [RFC5890].

      ABNF:

      sig-s-tag    = %x73 [FWS] "=" [FWS] selector

   t= Signature Timestamp (plain-text unsigned decimal integer;
      RECOMMENDED, default is an unknown creation time).  The time that
      this signature was created.  The format is the number of seconds
      since 00:00:00 on January 1, 1970 in the UTC time zone.  The value
      is expressed as an unsigned integer in decimal ASCII.  This value
      is not constrained to fit into a 31- or 32-bit integer.
      Implementations SHOULD be prepared to handle values up to at least
      10^12 (until approximately AD 200,000; this fits into 40 bits).
      To avoid denial-of-service attacks, implementations MAY consider
      any value longer than 12 digits to be infinite.  Leap seconds are
      not counted.  Implementations MAY ignore signatures that have a
      timestamp in the future.

      ABNF:

      sig-t-tag    = %x74 [FWS] "=" [FWS] 1*12DIGIT

   x= Signature Expiration (plain-text unsigned decimal integer;
      RECOMMENDED, default is no expiration).  The format is the same as
      in the "t=" tag, represented as an absolute date, not as a time
      delta from the signing timestamp.  The value is expressed as an
      unsigned integer in decimal ASCII, with the same constraints on
      the value in the "t=" tag.  Signatures MAY be considered invalid
      if the verification time at the Verifier is past the expiration
      date.  The verification time should be the time that the message
      was first received at the administrative domain of the Verifier if
      that time is reliably available; otherwise, the current time
      should be used.  The value of the "x=" tag MUST be greater than
      the value of the "t=" tag if both are present.

         INFORMATIVE NOTE: The "x=" tag is not intended as an anti-
         replay defense.




Crocker, et al.              Standards Track                   [Page 24]

RFC 6376                     DKIM Signatures              September 2011


         INFORMATIVE NOTE: Due to clock drift, the receiver's notion of
         when to consider the signature expired may not exactly match
         what the sender is expecting.  Receivers MAY add a 'fudge
         factor' to allow for such possible drift.

      ABNF:

      sig-x-tag    = %x78 [FWS] "=" [FWS]
                                    1*12DIGIT

   z= Copied header fields (dkim-quoted-printable, but see description;
      OPTIONAL, default is null).  A vertical-bar-separated list of
      selected header fields present when the message was signed,
      including both the field name and value.  It is not required to
      include all header fields present at the time of signing.  This
      field need not contain the same header fields listed in the "h="
      tag.  The header field text itself must encode the vertical bar
      ("|", %x7C) character (i.e., vertical bars in the "z=" text are
      meta-characters, and any actual vertical bar characters in a
      copied header field must be encoded).  Note that all whitespace
      must be encoded, including whitespace between the colon and the
      header field value.  After encoding, FWS MAY be added at arbitrary
      locations in order to avoid excessively long lines; such
      whitespace is NOT part of the value of the header field and MUST
      be removed before decoding.

      The header fields referenced by the "h=" tag refer to the fields
      in the [RFC5322] header of the message, not to any copied fields
      in the "z=" tag.  Copied header field values are for diagnostic
      use.

      ABNF:

      sig-z-tag      = %x7A [FWS] "=" [FWS] sig-z-tag-copy
                       *( "|" [FWS] sig-z-tag-copy )
      sig-z-tag-copy = hdr-name [FWS] ":" qp-hdr-value

         INFORMATIVE EXAMPLE of a signature header field spread across
         multiple continuation lines:

   DKIM-Signature: v=1; a=rsa-sha256; d=example.net; s=brisbane;
      c=simple; q=dns/txt; i=@eng.example.net;
      t=1117574938; x=1118006938;
      h=from:to:subject:date;
      z=From:foo@eng.example.net|To:joe@example.com|
       Subject:demo=20run|Date:July=205,=202005=203:44:08=20PM=20-0700;
      bh=MTIzNDU2Nzg5MDEyMzQ1Njc4OTAxMjM0NTY3ODkwMTI=;
      b=dzdVyOfAKCdLXdJOc9G2q8LoXSlEniSbav+yuU4zGeeruD00lszZVoG4ZHRNiYzR



Crocker, et al.              Standards Track                   [Page 25]

RFC 6376                     DKIM Signatures              September 2011


3.6.  Key Management and Representation

   Signature applications require some level of assurance that the
   verification public key is associated with the claimed Signer.  Many
   applications achieve this by using public-key certificates issued by
   a trusted third party.  However, DKIM can achieve a sufficient level
   of security, with significantly enhanced scalability, by simply
   having the Verifier query the purported Signer's DNS entry (or some
   security-equivalent) in order to retrieve the public key.

   DKIM keys can potentially be stored in multiple types of key servers
   and in multiple formats.  The storage and format of keys are
   irrelevant to the remainder of the DKIM algorithm.

   Parameters to the key lookup algorithm are the type of the lookup
   (the "q=" tag), the domain of the Signer (the "d=" tag of the DKIM-
   Signature header field), and the selector (the "s=" tag).

   public_key = dkim_find_key(q_val, d_val, s_val)

   This document defines a single binding, using DNS TXT RRs to
   distribute the keys.  Other bindings may be defined in the future.

3.6.1.  Textual Representation

   It is expected that many key servers will choose to present the keys
   in an otherwise unstructured text format (for example, an XML form
   would not be considered to be unstructured text for this purpose).
   The following definition MUST be used for any DKIM key represented in
   an otherwise unstructured textual form.

   The overall syntax is a tag-list as described in Section 3.2.  The
   current valid tags are described below.  Other tags MAY be present
   and MUST be ignored by any implementation that does not understand
   them.

   v= Version of the DKIM key record (plain-text; RECOMMENDED, default
      is "DKIM1").  If specified, this tag MUST be set to "DKIM1"
      (without the quotes).  This tag MUST be the first tag in the
      record.  Records beginning with a "v=" tag with any other value
      MUST be discarded.  Note that Verifiers must do a string
      comparison on this value; for example, "DKIM1" is not the same as
      "DKIM1.0".

      ABNF:

      key-v-tag    = %x76 [FWS] "=" [FWS] %x44.4B.49.4D.31




Crocker, et al.              Standards Track                   [Page 26]

RFC 6376                     DKIM Signatures              September 2011


   h= Acceptable hash algorithms (plain-text; OPTIONAL, defaults to
      allowing all algorithms).  A colon-separated list of hash
      algorithms that might be used.  Unrecognized algorithms MUST be
      ignored.  Refer to Section 3.3 for a discussion of the hash
      algorithms implemented by Signers and Verifiers.  The set of
      algorithms listed in this tag in each record is an operational
      choice made by the Signer.

      ABNF:

      key-h-tag       = %x68 [FWS] "=" [FWS] key-h-tag-alg
                        *( [FWS] ":" [FWS] key-h-tag-alg )
      key-h-tag-alg   = "sha1" / "sha256" / x-key-h-tag-alg
      x-key-h-tag-alg = hyphenated-word   ; for future extension

   k= Key type (plain-text; OPTIONAL, default is "rsa").  Signers and
      Verifiers MUST support the "rsa" key type.  The "rsa" key type
      indicates that an ASN.1 DER-encoded [ITU-X660-1997] RSAPublicKey
      (see [RFC3447], Sections 3.1 and A.1.1) is being used in the "p="
      tag.  (Note: the "p=" tag further encodes the value using the
      base64 algorithm.)  Unrecognized key types MUST be ignored.

      ABNF:

      key-k-tag        = %x76 [FWS] "=" [FWS] key-k-tag-type
      key-k-tag-type   = "rsa" / x-key-k-tag-type
      x-key-k-tag-type = hyphenated-word   ; for future extension

   n= Notes that might be of interest to a human (qp-section; OPTIONAL,
      default is empty).  No interpretation is made by any program.
      This tag should be used sparingly in any key server mechanism that
      has space limitations (notably DNS).  This is intended for use by
      administrators, not end users.

      ABNF:

      key-n-tag    = %x6e [FWS] "=" [FWS] qp-section

   p= Public-key data (base64; REQUIRED).  An empty value means that
      this public key has been revoked.  The syntax and semantics of
      this tag value before being encoded in base64 are defined by the
      "k=" tag.

         INFORMATIVE RATIONALE: If a private key has been compromised or
         otherwise disabled (e.g., an outsourcing contract has been
         terminated), a Signer might want to explicitly state that it
         knows about the selector, but all messages using that selector




Crocker, et al.              Standards Track                   [Page 27]

RFC 6376                     DKIM Signatures              September 2011


         should fail verification.  Verifiers SHOULD return an error
         code for any DKIM-Signature header field with a selector
         referencing a revoked key.  (See Section 6.1.2 for details.)

      ABNF:

      key-p-tag    = %x70 [FWS] "=" [ [FWS] base64string]

         INFORMATIVE NOTE: A base64string is permitted to include
         whitespace (FWS) at arbitrary places; however, any CRLFs must
         be followed by at least one WSP character.  Implementers and
         administrators are cautioned to ensure that selector TXT RRs
         conform to this specification.

   s= Service Type (plain-text; OPTIONAL; default is "*").  A colon-
      separated list of service types to which this record applies.
      Verifiers for a given service type MUST ignore this record if the
      appropriate type is not listed.  Unrecognized service types MUST
      be ignored.  Currently defined service types are as follows:

      *  matches all service types

      email   electronic mail (not necessarily limited to SMTP)

      This tag is intended to constrain the use of keys for other
      purposes, should use of DKIM be defined by other services in the
      future.

      ABNF:

      key-s-tag        = %x73 [FWS] "=" [FWS] key-s-tag-type
                         *( [FWS] ":" [FWS] key-s-tag-type )
      key-s-tag-type   = "email" / "*" / x-key-s-tag-type
      x-key-s-tag-type = hyphenated-word   ; for future extension

   t= Flags, represented as a colon-separated list of names (plain-
      text; OPTIONAL, default is no flags set).  Unrecognized flags MUST
      be ignored.  The defined flags are as follows:

      y  This domain is testing DKIM.  Verifiers MUST NOT treat messages
         from Signers in testing mode differently from unsigned email,
         even should the signature fail to verify.  Verifiers MAY wish
         to track testing mode results to assist the Signer.








Crocker, et al.              Standards Track                   [Page 28]

RFC 6376                     DKIM Signatures              September 2011


      s  Any DKIM-Signature header fields using the "i=" tag MUST have
         the same domain value on the right-hand side of the "@" in the
         "i=" tag and the value of the "d=" tag.  That is, the "i="
         domain MUST NOT be a subdomain of "d=".  Use of this flag is
         RECOMMENDED unless subdomaining is required.

      ABNF:

      key-t-tag        = %x74 [FWS] "=" [FWS] key-t-tag-flag
                         *( [FWS] ":" [FWS] key-t-tag-flag )
      key-t-tag-flag   = "y" / "s" / x-key-t-tag-flag
      x-key-t-tag-flag = hyphenated-word   ; for future extension

3.6.2.  DNS Binding

   A binding using DNS TXT RRs as a key service is hereby defined.  All
   implementations MUST support this binding.

3.6.2.1.  Namespace

   All DKIM keys are stored in a subdomain named "_domainkey".  Given a
   DKIM-Signature field with a "d=" tag of "example.com" and an "s=" tag
   of "foo.bar", the DNS query will be for
   "foo.bar._domainkey.example.com".

3.6.2.2.  Resource Record Types for Key Storage

   The DNS Resource Record type used is specified by an option to the
   query-type ("q=") tag.  The only option defined in this base
   specification is "txt", indicating the use of a TXT RR.  A later
   extension of this standard may define another RR type.

   Strings in a TXT RR MUST be concatenated together before use with no
   intervening whitespace.  TXT RRs MUST be unique for a particular
   selector name; that is, if there are multiple records in an RRset,
   the results are undefined.

   TXT RRs are encoded as described in Section 3.6.1.

3.7.  Computing the Message Hashes

   Both signing and verifying message signatures start with a step of
   computing two cryptographic hashes over the message.  Signers will
   choose the parameters of the signature as described in "Signer
   Actions" (Section 5); Verifiers will use the parameters specified in
   the DKIM-Signature header field being verified.  In the following
   discussion, the names of the tags in the DKIM-Signature header field
   that either exists (when verifying) or will be created (when signing)



Crocker, et al.              Standards Track                   [Page 29]

RFC 6376                     DKIM Signatures              September 2011


   are used.  Note that canonicalization (Section 3.4) is only used to
   prepare the email for signing or verifying; it does not affect the
   transmitted email in any way.

   The Signer/Verifier MUST compute two hashes: one over the body of the
   message and one over the selected header fields of the message.

   Signers MUST compute them in the order shown.  Verifiers MAY compute
   them in any order convenient to the Verifier, provided that the
   result is semantically identical to the semantics that would be the
   case had they been computed in this order.

   In hash step 1, the Signer/Verifier MUST hash the message body,
   canonicalized using the body canonicalization algorithm specified in
   the "c=" tag and then truncated to the length specified in the "l="
   tag.  That hash value is then converted to base64 form and inserted
   into (Signers) or compared to (Verifiers) the "bh=" tag of the DKIM-
   Signature header field.

   In hash step 2, the Signer/Verifier MUST pass the following to the
   hash algorithm in the indicated order.

   1.  The header fields specified by the "h=" tag, in the order
       specified in that tag, and canonicalized using the header
       canonicalization algorithm specified in the "c=" tag.  Each
       header field MUST be terminated with a single CRLF.

   2.  The DKIM-Signature header field that exists (verifying) or will
       be inserted (signing) in the message, with the value of the "b="
       tag (including all surrounding whitespace) deleted (i.e., treated
       as the empty string), canonicalized using the header
       canonicalization algorithm specified in the "c=" tag, and without
       a trailing CRLF.

   All tags and their values in the DKIM-Signature header field are
   included in the cryptographic hash with the sole exception of the
   value portion of the "b=" (signature) tag, which MUST be treated as
   the null string.  All tags MUST be included even if they might not be
   understood by the Verifier.  The header field MUST be presented to
   the hash algorithm after the body of the message rather than with the
   rest of the header fields and MUST be canonicalized as specified in
   the "c=" (canonicalization) tag.  The DKIM-Signature header field
   MUST NOT be included in its own "h=" tag, although other DKIM-
   Signature header fields MAY be signed (see Section 4).

   When calculating the hash on messages that will be transmitted using
   base64 or quoted-printable encoding, Signers MUST compute the hash
   after the encoding.  Likewise, the Verifier MUST incorporate the



Crocker, et al.              Standards Track                   [Page 30]

RFC 6376                     DKIM Signatures              September 2011


   values into the hash before decoding the base64 or quoted-printable
   text.  However, the hash MUST be computed before transport-level
   encodings such as SMTP "dot-stuffing" (the modification of lines
   beginning with a "." to avoid confusion with the SMTP end-of-message
   marker, as specified in [RFC5321]).

   With the exception of the canonicalization procedure described in
   Section 3.4, the DKIM signing process treats the body of messages as
   simply a string of octets.  DKIM messages MAY be either in plain-text
   or in MIME format; no special treatment is afforded to MIME content.
   Message attachments in MIME format MUST be included in the content
   that is signed.

   More formally, pseudo-code for the signature algorithm is:

   body-hash    =  hash-alg (canon-body, l-param)
   data-hash    =  hash-alg (h-headers, D-SIG, body-hash)
   signature    =  sig-alg (d-domain, selector, data-hash)

   where:

   body-hash:  is the output from hashing the body, using hash-alg.

   hash-alg:   is the hashing algorithm specified in the "a" parameter.

   canon-body: is a canonicalized representation of the body, produced
               using the body algorithm specified in the "c" parameter,
               as defined in Section 3.4 and excluding the
               DKIM-Signature field.

   l-param:    is the length-of-body value of the "l" parameter.

   data-hash:  is the output from using the hash-alg algorithm, to hash
               the header including the DKIM-Signature header, and the
               body hash.

   h-headers:  is the list of headers to be signed, as specified in the
               "h" parameter.

   D-SIG:      is the canonicalized DKIM-Signature field itself without
               the signature value portion of the parameter, that is, an
               empty parameter value.

   signature:  is the signature value produced by the signing algorithm.

   sig-alg:    is the signature algorithm specified by the "a"
               parameter.




Crocker, et al.              Standards Track                   [Page 31]

RFC 6376                     DKIM Signatures              September 2011


   d-domain:   is the domain name specified in the "d" parameter.

   selector:   is the selector value specified in the "s" parameter.

      NOTE: Many digital signature APIs provide both hashing and
      application of the RSA private key using a single "sign()"
      primitive.  When using such an API, the last two steps in the
      algorithm would probably be combined into a single call that would
      perform both the "a-hash-alg" and the "sig-alg".

3.8.  Input Requirements

   A message that is not compliant with [RFC5322], [RFC2045], and
   [RFC2047] can be subject to attempts by intermediaries to correct or
   interpret such content.  See Section 8 of [RFC4409] for examples of
   changes that are commonly made.  Such "corrections" may invalidate
   DKIM signatures or have other undesirable effects, including some
   that involve changes to the way a message is presented to an end
   user.

   Accordingly, DKIM's design is predicated on valid input.  Therefore,
   Signers and Verifiers SHOULD take reasonable steps to ensure that the
   messages they are processing are valid according to [RFC5322],
   [RFC2045], and any other relevant message format standards.

   See Section 8.15 for additional discussion.

3.9.  Output Requirements

   The evaluation of each signature ends in one of three states, which
   this document refers to as follows:

   SUCCESS:  a successful verification

   PERMFAIL:  a permanent, non-recoverable error such as a signature
      verification failure

   TEMPFAIL:  a temporary, recoverable error such as a DNS query timeout

   For each signature that verifies successfully or produces a TEMPFAIL
   result, output of the DKIM algorithm MUST include the set of:

   o  The domain name, taken from the "d=" signature tag; and

   o  The result of the verification attempt for that signature.






Crocker, et al.              Standards Track                   [Page 32]

RFC 6376                     DKIM Signatures              September 2011


   The output MAY include other signature properties or result meta-
   data, including PERMFAILed or otherwise ignored signatures, for use
   by modules that consume those results.

   See Section 6.1 for discussion of signature validation result codes.

3.10.  Signing by Parent Domains

   In some circumstances, it is desirable for a domain to apply a
   signature on behalf of any of its subdomains without the need to
   maintain separate selectors (key records) in each subdomain.  By
   default, private keys corresponding to key records can be used to
   sign messages for any subdomain of the domain in which they reside;
   for example, a key record for the domain example.com can be used to
   verify messages where the AUID ("i=" tag of the signature) is
   sub.example.com, or even sub1.sub2.example.com.  In order to limit
   the capability of such keys when this is not intended, the "s" flag
   MAY be set in the "t=" tag of the key record, to constrain the
   validity of the domain of the AUID.  If the referenced key record
   contains the "s" flag as part of the "t=" tag, the domain of the AUID
   ("i=" flag) MUST be the same as that of the SDID (d=) domain.  If
   this flag is absent, the domain of the AUID MUST be the same as, or a
   subdomain of, the SDID.

3.11.  Relationship between SDID and AUID

   DKIM's primary task is to communicate from the Signer to a recipient-
   side Identity Assessor a single Signing Domain Identifier (SDID) that
   refers to a responsible identity.  DKIM MAY optionally provide a
   single responsible Agent or User Identifier (AUID).

   Hence, DKIM's mandatory output to a receive-side Identity Assessor is
   a single domain name.  Within the scope of its use as DKIM output,
   the name has only basic domain name semantics; any possible owner-
   specific semantics are outside the scope of DKIM.  That is, within
   its role as a DKIM identifier, additional semantics cannot be assumed
   by an Identity Assessor.

   Upon successfully verifying the signature, a receive-side DKIM
   Verifier MUST communicate the Signing Domain Identifier (d=) to a
   consuming Identity Assessor module and MAY communicate the Agent or
   User Identifier (i=) if present.

   To the extent that a receiver attempts to intuit any structured
   semantics for either of the identifiers, this is a heuristic function
   that is outside the scope of DKIM's specification and semantics.





Crocker, et al.              Standards Track                   [Page 33]

RFC 6376                     DKIM Signatures              September 2011


   Hence, it is relegated to a higher-level service, such as a delivery-
   handling filter that integrates a variety of inputs and performs
   heuristic analysis of them.

      INFORMATIVE DISCUSSION: This document does not require the value
      of the SDID or AUID to match an identifier in any other message
      header field.  This requirement is, instead, an Assessor policy
      issue.  The purpose of such a linkage would be to authenticate the
      value in that other header field.  This, in turn, is the basis for
      applying a trust assessment based on the identifier value.  Trust
      is a broad and complex topic, and trust mechanisms are subject to
      highly creative attacks.  The real-world efficacy of any but the
      most basic bindings between the SDID or AUID and other identities
      is not well established, nor is its vulnerability to subversion by
      an attacker.  Hence, reliance on the use of such bindings should
      be strictly limited.  In particular, it is not at all clear to
      what extent a typical end-user recipient can rely on any
      assurances that might be made by successful use of the SDID or
      AUID.

4.  Semantics of Multiple Signatures

4.1.  Example Scenarios

   There are many reasons why a message might have multiple signatures.
   For example, suppose SHA-256 is in the future found to be
   insufficiently strong, and DKIM usage transitions to SHA-1024.  A
   Signer might immediately sign using the newer algorithm but also
   continue to sign using the older algorithm for interoperability with
   Verifiers that had not yet upgraded.  The Signer would do this by
   adding two DKIM-Signature header fields, one using each algorithm.
   Older Verifiers that did not recognize SHA-1024 as an acceptable
   algorithm would skip that signature and use the older algorithm;
   newer Verifiers could use either signature at their option and, all
   other things being equal, might not even attempt to verify the other
   signature.

   Similarly, a Signer might sign a message including all header fields
   and no "l=" tag (to satisfy strict Verifiers) and a second time with
   a limited set of header fields and an "l=" tag (in anticipation of
   possible message modifications en route to other Verifiers).
   Verifiers could then choose which signature they prefer.

   Of course, a message might also have multiple signatures because it
   passed through multiple Signers.  A common case is expected to be
   that of a signed message that passes through a mailing list that also





Crocker, et al.              Standards Track                   [Page 34]

RFC 6376                     DKIM Signatures              September 2011


   signs all messages.  Assuming both of those signatures verify, a
   recipient might choose to accept the message if either of those
   signatures were known to come from trusted sources.

   In particular, recipients might choose to whitelist mailing lists to
   which they have subscribed and that have acceptable anti-abuse
   policies so as to accept messages sent to that list even from unknown
   authors.  They might also subscribe to less trusted mailing lists
   (e.g., those without anti-abuse protection) and be willing to accept
   all messages from specific authors but insist on doing additional
   abuse scanning for other messages.

   Another related example of multiple Signers might be forwarding
   services, such as those commonly associated with academic alumni
   sites.  For example, a recipient might have an address at
   members.example.org, a site that has anti-abuse protection that is
   somewhat less effective than the recipient would prefer.  Such a
   recipient might have specific authors whose messages would be trusted
   absolutely, but messages from unknown authors that had passed the
   forwarder's scrutiny would have only medium trust.

4.2.  Interpretation

   A Signer that is adding a signature to a message merely creates a new
   DKIM-Signature header, using the usual semantics of the "h=" option.
   A Signer MAY sign previously existing DKIM-Signature header fields
   using the method described in Section 5.4 to sign trace header
   fields.

   Note that Signers should be cognizant that signing DKIM-Signature
   header fields may result in signature failures with intermediaries
   that do not recognize that DKIM-Signature header fields are trace
   header fields and unwittingly reorder them, thus breaking such
   signatures.  For this reason, signing existing DKIM-Signature header
   fields is unadvised, albeit legal.

      INFORMATIVE NOTE: If a header field with multiple instances is
      signed, those header fields are always signed from the bottom up.
      Thus, it is not possible to sign only specific DKIM-Signature
      header fields.  For example, if the message being signed already
      contains three DKIM-Signature header fields A, B, and C, it is
      possible to sign all of them, B and C only, or C only, but not A
      only, B only, A and B only, or A and C only.

   A Signer MAY add more than one DKIM-Signature header field using
   different parameters.  For example, during a transition period, a
   Signer might want to produce signatures using two different hash
   algorithms.



Crocker, et al.              Standards Track                   [Page 35]

RFC 6376                     DKIM Signatures              September 2011


   Signers SHOULD NOT remove any DKIM-Signature header fields from
   messages they are signing, even if they know that the signatures
   cannot be verified.

   When evaluating a message with multiple signatures, a Verifier SHOULD
   evaluate signatures independently and on their own merits.  For
   example, a Verifier that by policy chooses not to accept signatures
   with deprecated cryptographic algorithms would consider such
   signatures invalid.  Verifiers MAY process signatures in any order of
   their choice; for example, some Verifiers might choose to process
   signatures corresponding to the From field in the message header
   before other signatures.  See Section 6.1 for more information about
   signature choices.

      INFORMATIVE IMPLEMENTATION NOTE: Verifier attempts to correlate
      valid signatures with invalid signatures in an attempt to guess
      why a signature failed are ill-advised.  In particular, there is
      no general way that a Verifier can determine that an invalid
      signature was ever valid.

   Verifiers SHOULD continue to check signatures until a signature
   successfully verifies to the satisfaction of the Verifier.  To limit
   potential denial-of-service attacks, Verifiers MAY limit the total
   number of signatures they will attempt to verify.

   If a Verifier module reports signatures whose evaluations produced
   PERMFAIL results, Identity Assessors SHOULD ignore those signatures
   (see Section 6.1), acting as though they were not present in the
   message.

5.  Signer Actions

   The following steps are performed in order by Signers.

5.1.  Determine Whether the Email Should Be Signed and by Whom

   A Signer can obviously only sign email for domains for which it has a
   private key and the necessary knowledge of the corresponding public
   key and selector information.  However, there are a number of other
   reasons beyond the lack of a private key why a Signer could choose
   not to sign an email.

      INFORMATIVE NOTE: A Signer can be implemented as part of any
      portion of the mail system as deemed appropriate, including an
      MUA, a SUBMISSION server, or an MTA.  Wherever implemented,
      Signers should beware of signing (and thereby asserting
      responsibility for) messages that may be problematic.  In
      particular, within a trusted enclave, the signing domain might be



Crocker, et al.              Standards Track                   [Page 36]

RFC 6376                     DKIM Signatures              September 2011


      derived from the header according to local policy; SUBMISSION
      servers might only sign messages from users that are properly
      authenticated and authorized.

      INFORMATIVE IMPLEMENTER ADVICE: SUBMISSION servers should not sign
      Received header fields if the outgoing gateway MTA obfuscates
      Received header fields, for example, to hide the details of
      internal topology.

   If an email cannot be signed for some reason, it is a local policy
   decision as to what to do with that email.

5.2.  Select a Private Key and Corresponding Selector Information

   This specification does not define the basis by which a Signer should
   choose which private key and selector information to use.  Currently,
   all selectors are equal as far as this specification is concerned, so
   the decision should largely be a matter of administrative
   convenience.  Distribution and management of private keys is also
   outside the scope of this document.

      INFORMATIVE OPERATIONS ADVICE: A Signer should not sign with a
      private key when the selector containing the corresponding public
      key is expected to be revoked or removed before the Verifier has
      an opportunity to validate the signature.  The Signer should
      anticipate that Verifiers can choose to defer validation, perhaps
      until the message is actually read by the final recipient.  In
      particular, when rotating to a new key pair, signing should
      immediately commence with the new private key, and the old public
      key should be retained for a reasonable validation interval before
      being removed from the key server.

5.3.  Normalize the Message to Prevent Transport Conversions

   Some messages, particularly those using 8-bit characters, are subject
   to modification during transit, notably conversion to 7-bit form.
   Such conversions will break DKIM signatures.  In order to minimize
   the chances of such breakage, Signers SHOULD convert the message to a
   suitable MIME content-transfer encoding such as quoted-printable or
   base64 as described in [RFC2045] before signing.  Such conversion is
   outside the scope of DKIM; the actual message SHOULD be converted to
   7-bit MIME by an MUA or MSA prior to presentation to the DKIM
   algorithm.

   If the message is submitted to the Signer with any local encoding
   that will be modified before transmission, that modification to
   canonical [RFC5322] form MUST be done before signing.  In particular,
   bare CR or LF characters (used by some systems as a local line



Crocker, et al.              Standards Track                   [Page 37]

RFC 6376                     DKIM Signatures              September 2011


   separator convention) MUST be converted to the SMTP-standard CRLF
   sequence before the message is signed.  Any conversion of this sort
   SHOULD be applied to the message actually sent to the recipient(s),
   not just to the version presented to the signing algorithm.

   More generally, the Signer MUST sign the message as it is expected to
   be received by the Verifier rather than in some local or internal
   form.

5.3.1.  Body Length Limits

   A body length count MAY be specified to limit the signature
   calculation to an initial prefix of the body text, measured in
   octets.  If the body length count is not specified, the entire
   message body is signed.

      INFORMATIVE RATIONALE: This capability is provided because it is
      very common for mailing lists to add trailers to messages (e.g.,
      instructions on how to get off the list).  Until those messages
      are also signed, the body length count is a useful tool for the
      Verifier since it can, as a matter of policy, accept messages
      having valid signatures with extraneous data.

   The length actually hashed should be inserted in the "l=" tag of the
   DKIM-Signature header field.  (See Section 3.5.)

   The body length count allows the Signer of a message to permit data
   to be appended to the end of the body of a signed message.  The body
   length count MUST be calculated following the canonicalization
   algorithm; for example, any whitespace ignored by a canonicalization
   algorithm is not included as part of the body length count.

   A body length count of zero means that the body is completely
   unsigned.

   Signers wishing to ensure that no modification of any sort can occur
   should specify the "simple" canonicalization algorithm for both
   header and body and omit the body length count.

   See Section 8.2 for further discussion.

5.4.  Determine the Header Fields to Sign

   The From header field MUST be signed (that is, included in the "h="
   tag of the resulting DKIM-Signature header field).  Signers SHOULD
   NOT sign an existing header field likely to be legitimately modified
   or removed in transit.  In particular, [RFC5321] explicitly permits




Crocker, et al.              Standards Track                   [Page 38]

RFC 6376                     DKIM Signatures              September 2011


   modification or removal of the Return-Path header field in transit.
   Signers MAY include any other header fields present at the time of
   signing at the discretion of the Signer.

      INFORMATIVE OPERATIONS NOTE: The choice of which header fields to
      sign is non-obvious.  One strategy is to sign all existing, non-
      repeatable header fields.  An alternative strategy is to sign only
      header fields that are likely to be displayed to or otherwise be
      likely to affect the processing of the message at the receiver.  A
      third strategy is to sign only "well-known" headers.  Note that
      Verifiers may treat unsigned header fields with extreme
      skepticism, including refusing to display them to the end user or
      even ignoring the signature if it does not cover certain header
      fields.  For this reason, signing fields present in the message
      such as Date, Subject, Reply-To, Sender, and all MIME header
      fields are highly advised.

   The DKIM-Signature header field is always implicitly signed and MUST
   NOT be included in the "h=" tag except to indicate that other
   preexisting signatures are also signed.

   Signers MAY claim to have signed header fields that do not exist
   (that is, Signers MAY include the header field name in the "h=" tag
   even if that header field does not exist in the message).  When
   computing the signature, the nonexisting header field MUST be treated
   as the null string (including the header field name, header field
   value, all punctuation, and the trailing CRLF).

      INFORMATIVE RATIONALE: This allows Signers to explicitly assert
      the absence of a header field; if that header field is added
      later, the signature will fail.

      INFORMATIVE NOTE: A header field name need only be listed once
      more than the actual number of that header field in a message at
      the time of signing in order to prevent any further additions.
      For example, if there is a single Comments header field at the
      time of signing, listing Comments twice in the "h=" tag is
      sufficient to prevent any number of Comments header fields from
      being appended; it is not necessary (but is legal) to list
      Comments three or more times in the "h=" tag.

   Refer to Section 5.4.2 for a discussion of the procedure to be
   followed when canonicalizing a header with more than one instance of
   a particular header field name.

   Signers need to be careful of signing header fields that might have
   additional instances added later in the delivery process, since such
   header fields might be inserted after the signed instance or



Crocker, et al.              Standards Track                   [Page 39]

RFC 6376                     DKIM Signatures              September 2011


   otherwise reordered.  Trace header fields (such as Received) and
   Resent-* blocks are the only fields prohibited by [RFC5322] from
   being reordered.  In particular, since DKIM-Signature header fields
   may be reordered by some intermediate MTAs, signing existing DKIM-
   Signature header fields is error-prone.

      INFORMATIVE ADMONITION: Despite the fact that [RFC5322] does not
      prohibit the reordering of header fields, reordering of signed
      header fields with multiple instances by intermediate MTAs will
      cause DKIM signatures to be broken; such antisocial behavior
      should be avoided.

      INFORMATIVE IMPLEMENTER'S NOTE: Although not required by this
      specification, all end-user visible header fields should be signed
      to avoid possible "indirect spamming".  For example, if the
      Subject header field is not signed, a spammer can resend a
      previously signed mail, replacing the legitimate subject with a
      one-line spam.

5.4.1.  Recommended Signature Content

   The purpose of the DKIM cryptographic algorithm is to affix an
   identifier to the message in a way that is both robust against normal
   transit-related changes and resistant to kinds of replay attacks.  An
   essential aspect of satisfying these requirements is choosing what
   header fields to include in the hash and what fields to exclude.

   The basic rule for choosing fields to include is to select those
   fields that constitute the "core" of the message content.  Hence, any
   replay attack will have to include these in order to have the
   signature succeed; however, with these included, the core of the
   message is valid, even if sent on to new recipients.

   Common examples of fields with addresses and fields with textual
   content related to the body are:

   o  From (REQUIRED; see Section 5.4)

   o  Reply-To

   o  Subject

   o  Date

   o  To, Cc

   o  Resent-Date, Resent-From, Resent-To, Resent-Cc




Crocker, et al.              Standards Track                   [Page 40]

RFC 6376                     DKIM Signatures              September 2011


   o  In-Reply-To, References

   o  List-Id, List-Help, List-Unsubscribe, List-Subscribe, List-Post,
      List-Owner, List-Archive

   If the "l=" signature tag is in use (see Section 3.5), the Content-
   Type field is also a candidate for being included as it could be
   replaced in a way that causes completely different content to be
   rendered to the receiving user.

   There are trade-offs in the decision of what constitutes the "core"
   of the message, which for some fields is a subjective concept.
   Including fields such as "Message-ID", for example, is useful if one
   considers a mechanism for being able to distinguish separate
   instances of the same message to be core content.  Similarly, "In-
   Reply-To" and "References" might be desirable to include if one
   considers message threading to be a core part of the message.

   Another class of fields that may be of interest are those that convey
   security-related information about the message, such as
   Authentication-Results [RFC5451].

   The basic rule for choosing fields to exclude is to select those
   fields for which there are multiple fields with the same name and
   fields that are modified in transit.  Examples of these are:

   o  Return-Path

   o  Received

   o  Comments, Keywords

   Note that the DKIM-Signature field is also excluded from the header
   hash because its handling is specified separately.

   Typically, it is better to exclude other optional fields because of
   the potential that additional fields of the same name will be
   legitimately added or reordered prior to verification.  There are
   likely to be legitimate exceptions to this rule because of the wide
   variety of application-specific header fields that might be applied
   to a message, some of which are unlikely to be duplicated, modified,
   or reordered.

   Signers SHOULD choose canonicalization algorithms based on the types
   of messages they process and their aversion to risk.  For example,
   e-commerce sites sending primarily purchase receipts, which are not
   expected to be processed by mailing lists or other software likely to
   modify messages, will generally prefer "simple" canonicalization.



Crocker, et al.              Standards Track                   [Page 41]

RFC 6376                     DKIM Signatures              September 2011


   Sites sending primarily person-to-person email will likely prefer to
   be more resilient to modification during transport by using "relaxed"
   canonicalization.

   Unless mail is processed through intermediaries, such as mailing
   lists that might add "unsubscribe" instructions to the bottom of the
   message body, the "l=" tag is likely to convey no additional benefit
   while providing an avenue for unauthorized addition of text to a
   message.  The use of "l=0" takes this to the extreme, allowing
   complete alteration of the text of the message without invalidating
   the signature.  Moreover, a Verifier would be within its rights to
   consider a partly signed message body as unacceptable.  Judicious use
   is advised.

5.4.2.  Signatures Involving Multiple Instances of a Field

   Signers choosing to sign an existing header field that occurs more
   than once in the message (such as Received) MUST sign the physically
   last instance of that header field in the header block.  Signers
   wishing to sign multiple instances of such a header field MUST
   include the header field name multiple times in the "h=" tag of the
   DKIM-Signature header field and MUST sign such header fields in order
   from the bottom of the header field block to the top.  The Signer MAY
   include more instances of a header field name in "h=" than there are
   actual corresponding header fields so that the signature will not
   verify if additional header fields of that name are added.

      INFORMATIVE EXAMPLE:

      If the Signer wishes to sign two existing Received header fields,
      and the existing header contains:

      Received: <A>
      Received: <B>
      Received: <C>

      then the resulting DKIM-Signature header field should read:

      DKIM-Signature: ... h=Received : Received :...

      and Received header fields <C> and <B> will be signed in that
      order.









Crocker, et al.              Standards Track                   [Page 42]

RFC 6376                     DKIM Signatures              September 2011


5.5.  Compute the Message Hash and Signature

   The Signer MUST compute the message hash as described in Section 3.7
   and then sign it using the selected public-key algorithm.  This will
   result in a DKIM-Signature header field that will include the body
   hash and a signature of the header hash, where that header includes
   the DKIM-Signature header field itself.

   Entities such as mailing list managers that implement DKIM and that
   modify the message or a header field (for example, inserting
   unsubscribe information) before retransmitting the message SHOULD
   check any existing signature on input and MUST make such
   modifications before re-signing the message.

5.6.  Insert the DKIM-Signature Header Field

   Finally, the Signer MUST insert the DKIM-Signature header field
   created in the previous step prior to transmitting the email.  The
   DKIM-Signature header field MUST be the same as used to compute the
   hash as described above, except that the value of the "b=" tag MUST
   be the appropriately signed hash computed in the previous step,
   signed using the algorithm specified in the "a=" tag of the DKIM-
   Signature header field and using the private key corresponding to the
   selector given in the "s=" tag of the DKIM-Signature header field, as
   chosen above in Section 5.2.

   The DKIM-Signature header field MUST be inserted before any other
   DKIM-Signature fields in the header block.

      INFORMATIVE IMPLEMENTATION NOTE: The easiest way to achieve this
      is to insert the DKIM-Signature header field at the beginning of
      the header block.  In particular, it may be placed before any
      existing Received header fields.  This is consistent with treating
      DKIM-Signature as a trace header field.

6.  Verifier Actions

   Since a Signer MAY remove or revoke a public key at any time, it is
   advised that verification occur in a timely manner.  In many
   configurations, the most timely place is during acceptance by the
   border MTA or shortly thereafter.  In particular, deferring
   verification until the message is accessed by the end user is
   discouraged.

   A border or intermediate MTA MAY verify the message signature(s).  An
   MTA who has performed verification MAY communicate the result of that
   verification by adding a verification header field to incoming
   messages.  This simplifies things considerably for the user, who can



Crocker, et al.              Standards Track                   [Page 43]

RFC 6376                     DKIM Signatures              September 2011


   now use an existing mail user agent.  Most MUAs have the ability to
   filter messages based on message header fields or content; these
   filters would be used to implement whatever policy the user wishes
   with respect to unsigned mail.

   A verifying MTA MAY implement a policy with respect to unverifiable
   mail, regardless of whether or not it applies the verification header
   field to signed messages.

   Verifiers MUST produce a result that is semantically equivalent to
   applying the steps listed in Sections 6.1, 6.1.1, and 6.1.2 in order.
   In practice, several of these steps can be performed in parallel in
   order to improve performance.

6.1.  Extract Signatures from the Message

   The order in which Verifiers try DKIM-Signature header fields is not
   defined; Verifiers MAY try signatures in any order they like.  For
   example, one implementation might try the signatures in textual
   order, whereas another might try signatures by identities that match
   the contents of the From header field before trying other signatures.
   Verifiers MUST NOT attribute ultimate meaning to the order of
   multiple DKIM-Signature header fields.  In particular, there is
   reason to believe that some relays will reorder the header fields in
   potentially arbitrary ways.

      INFORMATIVE IMPLEMENTATION NOTE: Verifiers might use the order as
      a clue to signing order in the absence of any other information.
      However, other clues as to the semantics of multiple signatures
      (such as correlating the signing host with Received header fields)
      might also be considered.

   Survivability of signatures after transit is not guaranteed, and
   signatures can fail to verify through no fault of the Signer.
   Therefore, a Verifier SHOULD NOT treat a message that has one or more
   bad signatures and no good signatures differently from a message with
   no signature at all.

   When a signature successfully verifies, a Verifier will either stop
   processing or attempt to verify any other signatures, at the
   discretion of the implementation.  A Verifier MAY limit the number of
   signatures it tries, in order to avoid denial-of-service attacks (see
   Section 8.4 for further discussion).

   In the following description, text reading "return status
   (explanation)" (where "status" is one of "PERMFAIL" or "TEMPFAIL")
   means that the Verifier MUST immediately cease processing that
   signature.  The Verifier SHOULD proceed to the next signature, if one



Crocker, et al.              Standards Track                   [Page 44]

RFC 6376                     DKIM Signatures              September 2011


   is present, and completely ignore the bad signature.  If the status
   is "PERMFAIL", the signature failed and should not be reconsidered.
   If the status is "TEMPFAIL", the signature could not be verified at
   this time but may be tried again later.  A Verifier MAY either
   arrange to defer the message for later processing or try another
   signature; if no good signature is found and any of the signatures
   resulted in a TEMPFAIL status, the Verifier MAY arrange to defer the
   message for later processing.  The "(explanation)" is not normative
   text; it is provided solely for clarification.

   Verifiers that are prepared to validate multiple signature header
   fields SHOULD proceed to the next signature header field, if one
   exists.  However, Verifiers MAY make note of the fact that an invalid
   signature was present for consideration at a later step.

      INFORMATIVE NOTE: The rationale of this requirement is to permit
      messages that have invalid signatures but also a valid signature
      to work.  For example, a mailing list exploder might opt to leave
      the original submitter signature in place even though the exploder
      knows that it is modifying the message in some way that will break
      that signature, and the exploder inserts its own signature.  In
      this case, the message should succeed even in the presence of the
      known-broken signature.

   For each signature to be validated, the following steps should be
   performed in such a manner as to produce a result that is
   semantically equivalent to performing them in the indicated order.

6.1.1.  Validate the Signature Header Field

   Implementers MUST meticulously validate the format and values in the
   DKIM-Signature header field; any inconsistency or unexpected values
   MUST cause the header field to be completely ignored and the Verifier
   to return PERMFAIL (signature syntax error).  Being "liberal in what
   you accept" is definitely a bad strategy in this security context.
   Note, however, that this does not include the existence of unknown
   tags in a DKIM-Signature header field, which are explicitly
   permitted.  Verifiers MUST return PERMFAIL (incompatible version)
   when presented a DKIM-Signature header field with a "v=" tag that is
   inconsistent with this specification.

      INFORMATIVE IMPLEMENTATION NOTE: An implementation may, of course,
      choose to also verify signatures generated by older versions of
      this specification.







Crocker, et al.              Standards Track                   [Page 45]

RFC 6376                     DKIM Signatures              September 2011


   If any tag listed as "required" in Section 3.5 is omitted from the
   DKIM-Signature header field, the Verifier MUST ignore the DKIM-
   Signature header field and return PERMFAIL (signature missing
   required tag).

      INFORMATIVE NOTE: The tags listed as required in Section 3.5 are
      "v=", "a=", "b=", "bh=", "d=", "h=", and "s=".  Should there be a
      conflict between this note and Section 3.5, Section 3.5 is
      normative.

   If the DKIM-Signature header field does not contain the "i=" tag, the
   Verifier MUST behave as though the value of that tag were "@d", where
   "d" is the value from the "d=" tag.

   Verifiers MUST confirm that the domain specified in the "d=" tag is
   the same as or a parent domain of the domain part of the "i=" tag.
   If not, the DKIM-Signature header field MUST be ignored, and the
   Verifier should return PERMFAIL (domain mismatch).

   If the "h=" tag does not include the From header field, the Verifier
   MUST ignore the DKIM-Signature header field and return PERMFAIL (From
   field not signed).

   Verifiers MAY ignore the DKIM-Signature header field and return
   PERMFAIL (signature expired) if it contains an "x=" tag and the
   signature has expired.

   Verifiers MAY ignore the DKIM-Signature header field if the domain
   used by the Signer in the "d=" tag is not associated with a valid
   signing entity.  For example, signatures with "d=" values such as
   "com" and "co.uk" could be ignored.  The list of unacceptable domains
   SHOULD be configurable.

   Verifiers MAY ignore the DKIM-Signature header field and return
   PERMFAIL (unacceptable signature header) for any other reason, for
   example, if the signature does not sign header fields that the
   Verifier views to be essential.  As a case in point, if MIME header
   fields are not signed, certain attacks may be possible that the
   Verifier would prefer to avoid.

6.1.2.  Get the Public Key

   The public key for a signature is needed to complete the verification
   process.  The process of retrieving the public key depends on the
   query type as defined by the "q=" tag in the DKIM-Signature header
   field.  Obviously, a public key need only be retrieved if the process
   of extracting the signature information is completely successful.




Crocker, et al.              Standards Track                   [Page 46]

RFC 6376                     DKIM Signatures              September 2011


   Details of key management and representation are described in
   Section 3.6.  The Verifier MUST validate the key record and MUST
   ignore any public-key records that are malformed.

      NOTE: The use of a wildcard TXT RR that covers a queried DKIM
      domain name will produce a response to a DKIM query that is
      unlikely to be a valid DKIM key record.  This problem is not
      specific to DKIM and applies to many other types of queries.
      Client software that processes DNS responses needs to take this
      problem into account.

   When validating a message, a Verifier MUST perform the following
   steps in a manner that is semantically the same as performing them in
   the order indicated; in some cases, the implementation may
   parallelize or reorder these steps, as long as the semantics remain
   unchanged:

   1.  The Verifier retrieves the public key as described in Section 3.6
       using the algorithm in the "q=" tag, the domain from the "d="
       tag, and the selector from the "s=" tag.

   2.  If the query for the public key fails to respond, the Verifier
       MAY seek a later verification attempt by returning TEMPFAIL (key
       unavailable).

   3.  If the query for the public key fails because the corresponding
       key record does not exist, the Verifier MUST immediately return
       PERMFAIL (no key for signature).

   4.  If the query for the public key returns multiple key records, the
       Verifier can choose one of the key records or may cycle through
       the key records, performing the remainder of these steps on each
       record at the discretion of the implementer.  The order of the
       key records is unspecified.  If the Verifier chooses to cycle
       through the key records, then the "return ..." wording in the
       remainder of this section means "try the next key record, if any;
       if none, return to try another signature in the usual way".

   5.  If the result returned from the query does not adhere to the
       format defined in this specification, the Verifier MUST ignore
       the key record and return PERMFAIL (key syntax error).  Verifiers
       are urged to validate the syntax of key records carefully to
       avoid attempted attacks.  In particular, the Verifier MUST ignore
       keys with a version code ("v=" tag) that they do not implement.







Crocker, et al.              Standards Track                   [Page 47]

RFC 6376                     DKIM Signatures              September 2011


   6.  If the "h=" tag exists in the public-key record and the hash
       algorithm implied by the "a=" tag in the DKIM-Signature header
       field is not included in the contents of the "h=" tag, the
       Verifier MUST ignore the key record and return PERMFAIL
       (inappropriate hash algorithm).

   7.  If the public-key data (the "p=" tag) is empty, then this key has
       been revoked and the Verifier MUST treat this as a failed
       signature check and return PERMFAIL (key revoked).  There is no
       defined semantic difference between a key that has been revoked
       and a key record that has been removed.

   8.  If the public-key data is not suitable for use with the algorithm
       and key types defined by the "a=" and "k=" tags in the DKIM-
       Signature header field, the Verifier MUST immediately return
       PERMFAIL (inappropriate key algorithm).

6.1.3.  Compute the Verification

   Given a Signer and a public key, verifying a signature consists of
   actions semantically equivalent to the following steps.

   1.  Based on the algorithm defined in the "c=" tag, the body length
       specified in the "l=" tag, and the header field names in the "h="
       tag, prepare a canonicalized version of the message as is
       described in Section 3.7 (note that this canonicalized version
       does not actually replace the original content).  When matching
       header field names in the "h=" tag against the actual message
       header field, comparisons MUST be case-insensitive.

   2.  Based on the algorithm indicated in the "a=" tag, compute the
       message hashes from the canonical copy as described in
       Section 3.7.

   3.  Verify that the hash of the canonicalized message body computed
       in the previous step matches the hash value conveyed in the "bh="
       tag.  If the hash does not match, the Verifier SHOULD ignore the
       signature and return PERMFAIL (body hash did not verify).

   4.  Using the signature conveyed in the "b=" tag, verify the
       signature against the header hash using the mechanism appropriate
       for the public-key algorithm described in the "a=" tag.  If the
       signature does not validate, the Verifier SHOULD ignore the
       signature and return PERMFAIL (signature did not verify).







Crocker, et al.              Standards Track                   [Page 48]

RFC 6376                     DKIM Signatures              September 2011


   5.  Otherwise, the signature has correctly verified.

      INFORMATIVE IMPLEMENTER'S NOTE: Implementations might wish to
      initiate the public-key query in parallel with calculating the
      hash as the public key is not needed until the final decryption is
      calculated.  Implementations may also verify the signature on the
      message header before validating that the message hash listed in
      the "bh=" tag in the DKIM-Signature header field matches that of
      the actual message body; however, if the body hash does not match,
      the entire signature must be considered to have failed.

   A body length specified in the "l=" tag of the signature limits the
   number of bytes of the body passed to the verification algorithm.
   All data beyond that limit is not validated by DKIM.  Hence,
   Verifiers might treat a message that contains bytes beyond the
   indicated body length with suspicion and can choose to treat the
   signature as if it were invalid (e.g., by returning PERMFAIL
   (unsigned content)).

   Should the algorithm reach this point, the verification has
   succeeded, and DKIM reports SUCCESS for this signature.

6.2.  Communicate Verification Results

   Verifiers wishing to communicate the results of verification to other
   parts of the mail system may do so in whatever manner they see fit.
   For example, implementations might choose to add an email header
   field to the message before passing it on.  Any such header field
   SHOULD be inserted before any existing DKIM-Signature or preexisting
   authentication status header fields in the header field block.  The
   Authentication-Results: header field ([RFC5451]) MAY be used for this
   purpose.

      INFORMATIVE ADVICE to MUA filter writers: Patterns intended to
      search for results header fields to visibly mark authenticated
      mail for end users should verify that such a header field was
      added by the appropriate verifying domain and that the verified
      identity matches the author identity that will be displayed by the
      MUA.  In particular, MUA filters should not be influenced by bogus
      results header fields added by attackers.  To circumvent this
      attack, Verifiers MAY wish to request deletion of existing results
      header fields after verification and before arranging to add a new
      header field.








Crocker, et al.              Standards Track                   [Page 49]

RFC 6376                     DKIM Signatures              September 2011


6.3.  Interpret Results/Apply Local Policy

   It is beyond the scope of this specification to describe what actions
   an Identity Assessor can make, but mail carrying a validated SDID
   presents an opportunity to an Identity Assessor that unauthenticated
   email does not.  Specifically, an authenticated email creates a
   predictable identifier by which other decisions can reliably be
   managed, such as trust and reputation.  Conversely, unauthenticated
   email lacks a reliable identifier that can be used to assign trust
   and reputation.  It is reasonable to treat unauthenticated email as
   lacking any trust and having no positive reputation.

   In general, modules that consume DKIM verification output SHOULD NOT
   determine message acceptability based solely on a lack of any
   signature or on an unverifiable signature; such rejection would cause
   severe interoperability problems.  If an MTA does wish to reject such
   messages during an SMTP session (for example, when communicating with
   a peer who, by prior agreement, agrees to only send signed messages),
   and a signature is missing or does not verify, the handling MTA
   SHOULD use a 550/5.7.x reply code.

   Where the Verifier is integrated within the MTA and it is not
   possible to fetch the public key, perhaps because the key server is
   not available, a temporary failure message MAY be generated using a
   451/4.7.5 reply code, such as:

   451 4.7.5 Unable to verify signature - key server unavailable

   Temporary failures such as inability to access the key server or
   other external service are the only conditions that SHOULD use a 4xx
   SMTP reply code.  In particular, cryptographic signature verification
   failures MUST NOT provoke 4xx SMTP replies.

   Once the signature has been verified, that information MUST be
   conveyed to the Identity Assessor (such as an explicit allow/
   whitelist and reputation system) and/or to the end user.  If the SDID
   is not the same as the address in the From: header field, the mail
   system SHOULD take pains to ensure that the actual SDID is clear to
   the reader.

   While the symptoms of a failed verification are obvious -- the
   signature doesn't verify -- establishing the exact cause can be more
   difficult.  If a selector cannot be found, is that because the
   selector has been removed, or was the value changed somehow in
   transit?  If the signature line is missing, is that because it was
   never there, or was it removed by an overzealous filter?  For
   diagnostic purposes, the exact reason why the verification fails
   SHOULD be made available and possibly recorded in the system logs.



Crocker, et al.              Standards Track                   [Page 50]

RFC 6376                     DKIM Signatures              September 2011


   If the email cannot be verified, then it SHOULD be treated the same
   as all unverified email, regardless of whether or not it looks like
   it was signed.

   See Section 8.15 for additional discussion.

7.  IANA Considerations

   DKIM has registered namespaces with IANA.  In all cases, new values
   are assigned only for values that have been documented in a published
   RFC that has IETF Consensus [RFC5226].

   This memo updates these registries as described below.  Of note is
   the addition of a new "status" column.  All registrations into these
   namespaces MUST include the name being registered, the document in
   which it was registered or updated, and an indication of its current
   status, which MUST be one of "active" (in current use) or "historic"
   (no longer in current use).

   No new tags are defined in this specification compared to [RFC4871],
   but one has been designated as "historic".

   Also, the "Email Authentication Methods" registry is revised to refer
   to this update.

7.1.  Email Authentication Methods Registry

   The "Email Authentication Methods" registry is updated to indicate
   that "dkim" is defined in this memo.

7.2.  DKIM-Signature Tag Specifications

   A DKIM-Signature provides for a list of tag specifications.  IANA has
   established the "DKIM-Signature Tag Specifications" registry for tag
   specifications that can be used in DKIM-Signature fields.
















Crocker, et al.              Standards Track                   [Page 51]

RFC 6376                     DKIM Signatures              September 2011


                    +------+-----------------+--------+
                    | TYPE | REFERENCE       | STATUS |
                    +------+-----------------+--------+
                    |   v  | (this document) | active |
                    |   a  | (this document) | active |
                    |   b  | (this document) | active |
                    |  bh  | (this document) | active |
                    |   c  | (this document) | active |
                    |   d  | (this document) | active |
                    |   h  | (this document) | active |
                    |   i  | (this document) | active |
                    |   l  | (this document) | active |
                    |   q  | (this document) | active |
                    |   s  | (this document) | active |
                    |   t  | (this document) | active |
                    |   x  | (this document) | active |
                    |   z  | (this document) | active |
                    +------+-----------------+--------+

    Table 1: DKIM-Signature Tag Specifications Registry Updated Values

7.3.  DKIM-Signature Query Method Registry

   The "q=" tag-spec (specified in Section 3.5) provides for a list of
   query methods.

   IANA has established the "DKIM-Signature Query Method" registry for
   mechanisms that can be used to retrieve the key that will permit
   validation processing of a message signed using DKIM.

               +------+--------+-----------------+--------+
               | TYPE | OPTION | REFERENCE       | STATUS |
               +------+--------+-----------------+--------+
               |  dns |   txt  | (this document) | active |
               +------+--------+-----------------+--------+

       Table 2: DKIM-Signature Query Method Registry Updated Values

7.4.  DKIM-Signature Canonicalization Registry

   The "c=" tag-spec (specified in Section 3.5) provides for a specifier
   for canonicalization algorithms for the header and body of the
   message.

   IANA has established the "DKIM-Signature Canonicalization Header"
   Registry for algorithms for converting a message into a canonical
   form before signing or verifying using DKIM.




Crocker, et al.              Standards Track                   [Page 52]

RFC 6376                     DKIM Signatures              September 2011


                  +---------+-----------------+--------+
                  |   TYPE  | REFERENCE       | STATUS |
                  +---------+-----------------+--------+
                  |  simple | (this document) | active |
                  | relaxed | (this document) | active |
                  +---------+-----------------+--------+

     Table 3: DKIM-Signature Canonicalization Header Registry Updated
                                  Values

                  +---------+-----------------+--------+
                  |   TYPE  | REFERENCE       | STATUS |
                  +---------+-----------------+--------+
                  |  simple | (this document) | active |
                  | relaxed | (this document) | active |
                  +---------+-----------------+--------+

   Table 4: DKIM-Signature Canonicalization Body Registry Updated Values

7.5.  _domainkey DNS TXT Resource Record Tag Specifications

   A _domainkey DNS TXT RR provides for a list of tag specifications.
   IANA has established the DKIM "_domainkey DNS TXT Record Tag
   Specifications" registry for tag specifications that can be used in
   DNS TXT resource records.

                   +------+-----------------+----------+
                   | TYPE | REFERENCE       | STATUS   |
                   +------+-----------------+----------+
                   |   v  | (this document) | active   |
                   |   g  | [RFC4871]       | historic |
                   |   h  | (this document) | active   |
                   |   k  | (this document) | active   |
                   |   n  | (this document) | active   |
                   |   p  | (this document) | active   |
                   |   s  | (this document) | active   |
                   |   t  | (this document) | active   |
                   +------+-----------------+----------+

      Table 5: _domainkey DNS TXT Record Tag Specifications Registry
                              Updated Values

7.6.  DKIM Key Type Registry

   The "k=" <key-k-tag> (specified in Section 3.6.1) and the "a=" <sig-
   a-tag-k> (specified in Section 3.5) tags provide for a list of
   mechanisms that can be used to decode a DKIM signature.




Crocker, et al.              Standards Track                   [Page 53]

RFC 6376                     DKIM Signatures              September 2011


   IANA has established the "DKIM Key Type" registry for such
   mechanisms.

                       +------+-----------+--------+
                       | TYPE | REFERENCE | STATUS |
                       +------+-----------+--------+
                       |  rsa | [RFC3447] | active |
                       +------+-----------+--------+

              Table 6: DKIM Key Type Registry Updated Values

7.7.  DKIM Hash Algorithms Registry

   The "h=" <key-h-tag> (specified in Section 3.6.1) and the "a=" <sig-
   a-tag-h> (specified in Section 3.5) tags provide for a list of
   mechanisms that can be used to produce a digest of message data.

   IANA has established the "DKIM Hash Algorithms" registry for such
   mechanisms.

                  +--------+-------------------+--------+
                  |  TYPE  | REFERENCE         | STATUS |
                  +--------+-------------------+--------+
                  |  sha1  | [FIPS-180-3-2008] | active |
                  | sha256 | [FIPS-180-3-2008] | active |
                  +--------+-------------------+--------+

           Table 7: DKIM Hash Algorithms Registry Updated Values

7.8.  DKIM Service Types Registry

   The "s=" <key-s-tag> tag (specified in Section 3.6.1) provides for a
   list of service types to which this selector may apply.

   IANA has established the "DKIM Service Types" registry for service
   types.

                   +-------+-----------------+--------+
                   |  TYPE | REFERENCE       | STATUS |
                   +-------+-----------------+--------+
                   | email | (this document) | active |
                   |   *   | (this document) | active |
                   +-------+-----------------+--------+

            Table 8: DKIM Service Types Registry Updated Values






Crocker, et al.              Standards Track                   [Page 54]

RFC 6376                     DKIM Signatures              September 2011


7.9.  DKIM Selector Flags Registry

   The "t=" <key-t-tag> tag (specified in Section 3.6.1) provides for a
   list of flags to modify interpretation of the selector.

   IANA has established the "DKIM Selector Flags" registry for
   additional flags.

                    +------+-----------------+--------+
                    | TYPE | REFERENCE       | STATUS |
                    +------+-----------------+--------+
                    |   y  | (this document) | active |
                    |   s  | (this document) | active |
                    +------+-----------------+--------+

           Table 9: DKIM Selector Flags Registry Updated Values

7.10.  DKIM-Signature Header Field

   IANA has added DKIM-Signature to the "Permanent Message Header Field
   Names" registry (see [RFC3864]) for the "mail" protocol, using this
   document as the reference.

8.  Security Considerations

   It has been observed that any introduced mechanism that attempts to
   stem the flow of spam is subject to intensive attack.  DKIM needs to
   be carefully scrutinized to identify potential attack vectors and the
   vulnerability to each.  See also [RFC4686].

8.1.  ASCII Art Attacks

   The relaxed body canonicalization algorithm may enable certain types
   of extremely crude "ASCII Art" attacks where a message may be
   conveyed by adjusting the spacing between words.  If this is a
   concern, the "simple" body canonicalization algorithm should be used
   instead.

8.2.  Misuse of Body Length Limits ("l=" Tag)

   Use of the "l=" tag might allow display of fraudulent content without
   appropriate warning to end users.  The "l=" tag is intended for
   increasing signature robustness when sending to mailing lists that
   both modify their content and do not sign their modified messages.
   However, using the "l=" tag enables attacks in which an intermediary
   with malicious intent can modify a message to include content that
   solely benefits the attacker.  It is possible for the appended




Crocker, et al.              Standards Track                   [Page 55]

RFC 6376                     DKIM Signatures              September 2011


   content to completely replace the original content in the end
   recipient's eyes and to defeat duplicate message detection
   algorithms.

   An example of such an attack includes altering the MIME structure,
   exploiting lax HTML parsing in the MUA, and defeating duplicate
   message detection algorithms.

   To avoid this attack, Signers should be extremely wary of using this
   tag, and Assessors might wish to ignore signatures that use the tag.

8.3.  Misappropriated Private Key

   As with any other security application that uses private- or public-
   key pairs, DKIM requires caution around the handling and protection
   of keys.  A compromised private key or access to one means an
   intruder or malware can send mail signed by the domain that
   advertises the matching public key.

   Thus, private keys issued to users, rather than one used by an
   ADministrative Management Domain (ADMD) itself, create the usual
   problem of securing data stored on personal resources that can affect
   the ADMD.

   A more secure architecture involves sending messages through an
   outgoing MTA that can authenticate the submitter using existing
   techniques (e.g., SMTP Authentication), possibly validate the message
   itself (e.g., verify that the header is legitimate and that the
   content passes a spam content check), and sign the message using a
   key appropriate for the submitter address.  Such an MTA can also
   apply controls on the volume of outgoing mail each user is permitted
   to originate in order to further limit the ability of malware to
   generate bulk email.

8.4.  Key Server Denial-of-Service Attacks

   Since the key servers are distributed (potentially separate for each
   domain), the number of servers that would need to be attacked to
   defeat this mechanism on an Internet-wide basis is very large.
   Nevertheless, key servers for individual domains could be attacked,
   impeding the verification of messages from that domain.  This is not
   significantly different from the ability of an attacker to deny
   service to the mail exchangers for a given domain, although it
   affects outgoing, not incoming, mail.

   A variation on this attack involves a very large amount of mail being
   sent using spoofed signatures from a given domain: the key servers
   for that domain could be overwhelmed with requests in a denial-of-



Crocker, et al.              Standards Track                   [Page 56]

RFC 6376                     DKIM Signatures              September 2011


   service attack (see [RFC4732]).  However, given the low overhead of
   verification compared with handling of the email message itself, such
   an attack would be difficult to mount.

8.5.  Attacks against the DNS

   Since the DNS is a required binding for key services, specific
   attacks against the DNS must be considered.

   While the DNS is currently insecure [RFC3833], these security
   problems are the motivation behind DNS Security (DNSSEC) [RFC4033],
   and all users of the DNS will reap the benefit of that work.

   DKIM is only intended as a "sufficient" method of proving
   authenticity.  It is not intended to provide strong cryptographic
   proof about authorship or contents.  Other technologies such as
   OpenPGP [RFC4880] and S/MIME [RFC5751] address those requirements.

   A second security issue related to the DNS revolves around the
   increased DNS traffic as a consequence of fetching selector-based
   data as well as fetching signing domain policy.  Widespread
   deployment of DKIM will result in a significant increase in DNS
   queries to the claimed signing domain.  In the case of forgeries on a
   large scale, DNS servers could see a substantial increase in queries.

   A specific DNS security issue that should be considered by DKIM
   Verifiers is the name chaining attack described in Section 2.3 of
   [RFC3833].  A DKIM Verifier, while verifying a DKIM-Signature header
   field, could be prompted to retrieve a key record of an attacker's
   choosing.  This threat can be minimized by ensuring that name
   servers, including recursive name servers, used by the Verifier
   enforce strict checking of "glue" and other additional information in
   DNS responses and are therefore not vulnerable to this attack.

8.6.  Replay/Spam Attacks

   In this attack, a spammer sends a piece of spam through an MTA that
   signs it, banking on the reputation of the signing domain (e.g., a
   large popular mailbox provider) rather than its own, and then re-
   sends that message to a large number of intended recipients.  The
   recipients observe the valid signature from the well-known domain,
   elevating their trust in the message and increasing the likelihood of
   delivery and presentation to the user.

   Partial solutions to this problem involve the use of reputation
   services to convey the fact that the specific email address is being
   used for spam and that messages from that Signer are likely to be
   spam.  This requires a real-time detection mechanism in order to



Crocker, et al.              Standards Track                   [Page 57]

RFC 6376                     DKIM Signatures              September 2011


   react quickly enough.  However, such measures might be prone to
   abuse, if, for example, an attacker re-sent a large number of
   messages received from a victim in order to make the victim appear to
   be a spammer.

   Large Verifiers might be able to detect unusually large volumes of
   mails with the same signature in a short time period.  Smaller
   Verifiers can get substantially the same volume of information via
   existing collaborative systems.

8.7.  Limits on Revoking Keys

   When a large domain detects undesirable behavior on the part of one
   of its users, it might wish to revoke the key used to sign that
   user's messages in order to disavow responsibility for messages that
   have not yet been verified or that are the subject of a replay
   attack.  However, the ability of the domain to do so can be limited
   if the same key, for scalability reasons, is used to sign messages
   for many other users.  Mechanisms for explicitly revoking keys on a
   per-address basis have been proposed but require further study as to
   their utility and the DNS load they represent.

8.8.  Intentionally Malformed Key Records

   It is possible for an attacker to publish key records in DNS that are
   intentionally malformed, with the intent of causing a denial-of-
   service attack on a non-robust Verifier implementation.  The attacker
   could then cause a Verifier to read the malformed key record by
   sending a message to one of its users referencing the malformed
   record in a (not necessarily valid) signature.  Verifiers MUST
   thoroughly verify all key records retrieved from the DNS and be
   robust against intentionally as well as unintentionally malformed key
   records.

8.9.  Intentionally Malformed DKIM-Signature Header Fields

   Verifiers MUST be prepared to receive messages with malformed DKIM-
   Signature header fields and thoroughly verify the header field before
   depending on any of its contents.

8.10.  Information Leakage

   An attacker could determine when a particular signature was verified
   by using a per-message selector and then monitoring their DNS traffic
   for the key lookup.  This would act as the equivalent of a "web bug"
   for verification time rather than the time the message was read.





Crocker, et al.              Standards Track                   [Page 58]

RFC 6376                     DKIM Signatures              September 2011


8.11.  Remote Timing Attacks

   In some cases, it may be possible to extract private keys using a
   remote timing attack [BONEH03].  Implementations should consider
   obfuscating the timing to prevent such attacks.

8.12.  Reordered Header Fields

   Existing standards allow intermediate MTAs to reorder header fields.
   If a Signer signs two or more header fields of the same name, this
   can cause spurious verification errors on otherwise legitimate
   messages.  In particular, Signers that sign any existing DKIM-
   Signature fields run the risk of having messages incorrectly fail to
   verify.

8.13.  RSA Attacks

   An attacker could create a large RSA signing key with a small
   exponent, thus requiring that the verification key have a large
   exponent.  This will force Verifiers to use considerable computing
   resources to verify the signature.  Verifiers might avoid this attack
   by refusing to verify signatures that reference selectors with public
   keys having unreasonable exponents.

   In general, an attacker might try to overwhelm a Verifier by flooding
   it with messages requiring verification.  This is similar to other
   MTA denial-of-service attacks and should be dealt with in a similar
   fashion.

8.14.  Inappropriate Signing by Parent Domains

   The trust relationship described in Section 3.10 could conceivably be
   used by a parent domain to sign messages with identities in a
   subdomain not administratively related to the parent.  For example,
   the ".com" registry could create messages with signatures using an
   "i=" value in the example.com domain.  There is no general solution
   to this problem, since the administrative cut could occur anywhere in
   the domain name.  For example, in the domain "example.podunk.ca.us",
   there are three administrative cuts (podunk.ca.us, ca.us, and us),
   any of which could create messages with an identity in the full
   domain.

      INFORMATIVE NOTE: This is considered an acceptable risk for the
      same reason that it is acceptable for domain delegation.  For
      example, in the case above, any of the domains could potentially
      simply delegate "example.podunk.ca.us" to a server of their choice





Crocker, et al.              Standards Track                   [Page 59]

RFC 6376                     DKIM Signatures              September 2011


      and completely replace all DNS-served information.  Note that a
      Verifier MAY ignore signatures that come from an unlikely domain
      such as ".com", as discussed in Section 6.1.1.

8.15.  Attacks Involving Extra Header Fields

   Many email components, including MTAs, MSAs, MUAs, and filtering
   modules, implement message format checks only loosely.  This is done
   out of years of industry pressure to be liberal in what is accepted
   into the mail stream for the sake of reducing support costs;
   improperly formed messages are often silently fixed in transit,
   delivered unrepaired, or displayed inappropriately (e.g., by showing
   only the first of multiple From: fields).

   Agents that evaluate or apply DKIM output need to be aware that a
   DKIM Signer can sign messages that are malformed (e.g., violate
   [RFC5322], such as by having multiple instances of a field that is
   only permitted once), that become malformed in transit, or that
   contain header or body content that is not true or valid.  Use of
   DKIM on such messages might constitute an attack against a receiver,
   especially where additional credence is given to a signed message
   without adequate evaluation of the Signer.

   These can represent serious attacks, but they have nothing to do with
   DKIM; they are attacks on the recipient or on the wrongly identified
   author.

   Moreover, an agent would be incorrect to infer that all instances of
   a header field are signed just because one is.

   A genuine signature from the domain under attack can be obtained by
   legitimate means, but extra header fields can then be added, either
   by interception or by replay.  In this scenario, DKIM can aid in
   detecting addition of specific fields in transit.  This is done by
   having the Signer list the field name(s) in the "h=" tag an extra
   time (e.g., "h=from:from:..." for a message with one From field), so
   that addition of an instance of that field downstream will render the
   signature unable to be verified.  (See Section 3.5 for details.)
   This, in essence, is an explicit indication that the Signer
   repudiates responsibility for such a malformed message.

   DKIM signs and validates the data it is told to and works correctly.
   So in this case, DKIM has done its job of delivering a validated
   domain (the "d=" value) and, given the semantics of a DKIM signature,
   essentially the Signer has taken some responsibility for a
   problematic message.  It is up to the Identity Assessor or some other





Crocker, et al.              Standards Track                   [Page 60]

RFC 6376                     DKIM Signatures              September 2011


   subsequent agent to act on such messages as needed, such as degrading
   the trust of the message (or, indeed, of the Signer), warning the
   recipient, or even refusing delivery.

   All components of the mail system that perform loose enforcement of
   other mail standards will need to revisit that posture when
   incorporating DKIM, especially when considering matters of potential
   attacks such as those described.

9.  References

9.1.  Normative References

   [FIPS-180-3-2008]
              U.S. Department of Commerce, "Secure Hash Standard", FIPS
              PUB 180-3, October 2008.

   [ITU-X660-1997]
              "Information Technology - ASN.1 encoding rules:
              Specification of Basic Encoding Rules (BER), Canonical
              Encoding Rules (CER) and Distinguished Encoding Rules
              (DER)", 1997.

   [RFC1034]  Mockapetris, P., "Domain names - concepts and facilities",
              STD 13, RFC 1034, November 1987.

   [RFC2045]  Freed, N. and N. Borenstein, "Multipurpose Internet Mail
              Extensions (MIME) Part One: Format of Internet Message
              Bodies", RFC 2045, November 1996.

   [RFC2049]  Freed, N. and N. Borenstein, "Multipurpose Internet Mail
              Extensions (MIME) Part Five: Conformance Criteria and
              Examples", RFC 2049, November 1996.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, March 1997.

   [RFC3447]  Jonsson, J. and B. Kaliski, "Public-Key Cryptography
              Standards (PKCS) #1: RSA Cryptography Specifications
              Version 2.1", RFC 3447, February 2003.

   [RFC5234]  Crocker, D. and P. Overell, "Augmented BNF for Syntax
              Specifications: ABNF", STD 68, RFC 5234, January 2008.

   [RFC5321]  Klensin, J., "Simple Mail Transfer Protocol", RFC 5321,
              October 2008.





Crocker, et al.              Standards Track                   [Page 61]

RFC 6376                     DKIM Signatures              September 2011


   [RFC5322]  Resnick, P., Ed., "Internet Message Format", RFC 5322,
              October 2008.

   [RFC5598]  Crocker, D., "Internet Mail Architecture", RFC 5598,
              July 2009.

   [RFC5890]  Klensin, J., "Internationalized Domain Names for
              Applications (IDNA): Definitions and Document Framework",
              RFC 5890, August 2010.

9.2.  Informative References

   [BONEH03]  "Remote Timing Attacks are Practical", Proceedings 12th
              USENIX Security Symposium, 2003.

   [RFC2047]  Moore, K., "MIME (Multipurpose Internet Mail Extensions)
              Part Three: Message Header Extensions for Non-ASCII Text",
              RFC 2047, November 1996.

   [RFC3629]  Yergeau, F., "UTF-8, a transformation format of ISO
              10646", STD 63, RFC 3629, November 2003.

   [RFC3766]  Orman, H. and P. Hoffman, "Determining Strengths For
              Public Keys Used For Exchanging Symmetric Keys", BCP 86,
              RFC 3766, April 2004.

   [RFC3833]  Atkins, D. and R. Austein, "Threat Analysis of the Domain
              Name System (DNS)", RFC 3833, August 2004.

   [RFC3864]  Klyne, G., Nottingham, M., and J. Mogul, "Registration
              Procedures for Message Header Fields", BCP 90, RFC 3864,
              September 2004.

   [RFC4033]  Arends, R., Austein, R., Larson, M., Massey, D., and S.
              Rose, "DNS Security Introduction and Requirements",
              RFC 4033, March 2005.

   [RFC4409]  Gellens, R. and J. Klensin, "Message Submission for Mail",
              RFC 4409, April 2006.

   [RFC4686]  Fenton, J., "Analysis of Threats Motivating DomainKeys
              Identified Mail (DKIM)", RFC 4686, September 2006.

   [RFC4732]  Handley, M., Rescorla, E., and IAB, "Internet Denial-of-
              Service Considerations", RFC 4732, December 2006.






Crocker, et al.              Standards Track                   [Page 62]

RFC 6376                     DKIM Signatures              September 2011


   [RFC4870]  Delany, M., "Domain-Based Email Authentication Using
              Public Keys Advertised in the DNS (DomainKeys)", RFC 4870,
              May 2007.

   [RFC4871]  Allman, E., Callas, J., Delany, M., Libbey, M., Fenton,
              J., and M. Thomas, "DomainKeys Identified Mail (DKIM)
              Signatures", RFC 4871, May 2007.

   [RFC4880]  Callas, J., Donnerhacke, L., Finney, H., Shaw, D., and R.
              Thayer, "OpenPGP Message Format", RFC 4880, November 2007.

   [RFC5226]  Narten, T. and H. Alvestrand, "Guidelines for Writing an
              IANA Considerations Section in RFCs", BCP 26, RFC 5226,
              May 2008.

   [RFC5451]  Kucherawy, M., "Message Header Field for Indicating
              Message Authentication Status", RFC 5451, April 2009.

   [RFC5585]  Hansen, T., Crocker, D., and P. Hallam-Baker, "DomainKeys
              Identified Mail (DKIM) Service Overview", RFC 5585,
              July 2009.

   [RFC5672]  Crocker, D., "RFC 4871 DomainKeys Identified Mail (DKIM)
              Signatures -- Update", RFC 5672, August 2009.

   [RFC5751]  Ramsdell, B. and S. Turner, "Secure/Multipurpose Internet
              Mail Extensions (S/MIME) Version 3.2 Message
              Specification", RFC 5751, January 2010.

   [RFC5863]  Hansen, T., Siegel, E., Hallam-Baker, P., and D. Crocker,
              "DomainKeys Identified Mail (DKIM) Development,
              Deployment, and Operations", RFC 5863, May 2010.

   [RFC6377]  Kucherawy, M., "DomainKeys Identified Mail (DKIM) and
              Mailing Lists", RFC 6377, September 2011.
















Crocker, et al.              Standards Track                   [Page 63]

RFC 6376                     DKIM Signatures              September 2011


Appendix A.  Example of Use (INFORMATIVE)

   This section shows the complete flow of an email from submission to
   final delivery, demonstrating how the various components fit
   together.  The key used in this example is shown in Appendix C.

A.1.  The User Composes an Email

   From: Joe SixPack <joe@football.example.com>
   To: Suzie Q <suzie@shopping.example.net>
   Subject: Is dinner ready?
   Date: Fri, 11 Jul 2003 21:00:37 -0700 (PDT)
   Message-ID: <20030712040037.46341.5F8J@football.example.com>

   Hi.

   We lost the game.  Are you hungry yet?

   Joe.

                   Figure 1: The User Composes an Email






























Crocker, et al.              Standards Track                   [Page 64]

RFC 6376                     DKIM Signatures              September 2011


A.2.  The Email is Signed

   This email is signed by the example.com outbound email server and now
   looks like this:

   DKIM-Signature: v=1; a=rsa-sha256; s=brisbane; d=example.com;
        c=simple/simple; q=dns/txt; i=joe@football.example.com;
        h=Received : From : To : Subject : Date : Message-ID;
        bh=2jUSOH9NhtVGCQWNr9BrIAPreKQjO6Sn7XIkfJVOzv8=;
        b=AuUoFEfDxTDkHlLXSZEpZj79LICEps6eda7W3deTVFOk4yAUoqOB
        4nujc7YopdG5dWLSdNg6xNAZpOPr+kHxt1IrE+NahM6L/LbvaHut
        KVdkLLkpVaVVQPzeRDI009SO2Il5Lu7rDNH6mZckBdrIx0orEtZV
        4bmp/YzhwvcubU4=;
   Received: from client1.football.example.com  [192.0.2.1]
        by submitserver.example.com with SUBMISSION;
        Fri, 11 Jul 2003 21:01:54 -0700 (PDT)
   From: Joe SixPack <joe@football.example.com>
   To: Suzie Q <suzie@shopping.example.net>
   Subject: Is dinner ready?
   Date: Fri, 11 Jul 2003 21:00:37 -0700 (PDT)
   Message-ID: <20030712040037.46341.5F8J@football.example.com>

   Hi.

   We lost the game.  Are you hungry yet?

   Joe.

                       Figure 2: The Email is Signed

   The signing email server requires access to the private key
   associated with the "brisbane" selector to generate this signature.



















Crocker, et al.              Standards Track                   [Page 65]

RFC 6376                     DKIM Signatures              September 2011


A.3.  The Email Signature is Verified

   The signature is normally verified by an inbound SMTP server or
   possibly the final delivery agent.  However, intervening MTAs can
   also perform this verification if they choose to do so.  The
   verification process uses the domain "example.com" extracted from the
   "d=" tag and the selector "brisbane" from the "s=" tag in the DKIM-
   Signature header field to form the DNS DKIM query for:
   brisbane._domainkey.example.com

   Signature verification starts with the physically last Received
   header field, the From header field, and so forth, in the order
   listed in the "h=" tag.  Verification follows with a single CRLF
   followed by the body (starting with "Hi.").  The email is canonically
   prepared for verifying with the "simple" method.  The result of the
   query and subsequent verification of the signature is stored (in this
   example) in the X-Authentication-Results header field line.  After
   successful verification, the email looks like this:

   X-Authentication-Results: shopping.example.net
     header.from=joe@football.example.com; dkim=pass
   Received: from mout23.football.example.com (192.168.1.1)
     by shopping.example.net with SMTP;
     Fri, 11 Jul 2003 21:01:59 -0700 (PDT)
   DKIM-Signature: v=1; a=rsa-sha256; s=brisbane; d=example.com;
     c=simple/simple; q=dns/txt; i=joe@football.example.com;
     h=Received : From : To : Subject : Date : Message-ID;
     bh=2jUSOH9NhtVGCQWNr9BrIAPreKQjO6Sn7XIkfJVOzv8=;
     b=AuUoFEfDxTDkHlLXSZEpZj79LICEps6eda7W3deTVFOk4yAUoqOB
       4nujc7YopdG5dWLSdNg6xNAZpOPr+kHxt1IrE+NahM6L/LbvaHut
       KVdkLLkpVaVVQPzeRDI009SO2Il5Lu7rDNH6mZckBdrIx0orEtZV
       4bmp/YzhwvcubU4=;
   Received: from client1.football.example.com  [192.0.2.1]
     by submitserver.example.com with SUBMISSION;
     Fri, 11 Jul 2003 21:01:54 -0700 (PDT)
   From: Joe SixPack <joe@football.example.com>
   To: Suzie Q <suzie@shopping.example.net>
   Subject: Is dinner ready?
   Date: Fri, 11 Jul 2003 21:00:37 -0700 (PDT)
   Message-ID: <20030712040037.46341.5F8J@football.example.com>

   Hi.

   We lost the game.  Are you hungry yet?

   Joe.

                     Figure 3: Successful Verification



Crocker, et al.              Standards Track                   [Page 66]

RFC 6376                     DKIM Signatures              September 2011


Appendix B.  Usage Examples (INFORMATIVE)

   DKIM signing and validating can be used in different ways, for
   different operational scenarios.  This Appendix discusses some common
   examples.

      NOTE: Descriptions in this Appendix are for informational purposes
      only.  They describe various ways that DKIM can be used, given
      particular constraints and needs.  In no case are these examples
      intended to be taken as providing explanation or guidance
      concerning DKIM specification details when creating an
      implementation.

B.1.  Alternate Submission Scenarios

   In the most simple scenario, a user's MUA, MSA, and Internet
   (boundary) MTA are all within the same administrative environment,
   using the same domain name.  Therefore, all of the components
   involved in submission and initial transfer are related.  However, it
   is common for two or more of the components to be under independent
   administrative control.  This creates challenges for choosing and
   administering the domain name to use for signing and for its
   relationship to common email identity header fields.

B.1.1.  Delegated Business Functions

   Some organizations assign specific business functions to discrete
   groups, inside or outside the organization.  The goal, then, is to
   authorize that group to sign some mail but to constrain what
   signatures they can generate.  DKIM selectors (the "s=" signature
   tag) facilitate this kind of restricted authorization.  Examples of
   these outsourced business functions are legitimate email marketing
   providers and corporate benefits providers.

   Here, the delegated group needs to be able to send messages that are
   signed, using the email domain of the client company.  At the same
   time, the client often is reluctant to register a key for the
   provider that grants the ability to send messages for arbitrary
   addresses in the domain.

   There are multiple ways to administer these usage scenarios.  In one
   case, the client organization provides all of the public query
   service (for example, DNS) administration, and in another, it uses
   DNS delegation to enable all ongoing administration of the DKIM key
   record by the delegated group.






Crocker, et al.              Standards Track                   [Page 67]

RFC 6376                     DKIM Signatures              September 2011


   If the client organization retains responsibility for all of the DNS
   administration, the outsourcing company can generate a key pair,
   supplying the public key to the client company, which then registers
   it in the query service using a unique selector.  The client company
   retains control over the use of the delegated key because it retains
   the ability to revoke the key at any time.

   If the client wants the delegated group to do the DNS administration,
   it can have the domain name that is specified with the selector point
   to the provider's DNS server.  The provider then creates and
   maintains all of the DKIM signature information for that selector.
   Hence, the client cannot provide constraints on the local-part of
   addresses that get signed, but it can revoke the provider's signing
   rights by removing the DNS delegation record.

B.1.2.  PDAs and Similar Devices

   PDAs demonstrate the need for using multiple keys per domain.
   Suppose that John Doe wants to be able to send messages using his
   corporate email address, jdoe@example.com, and his email device does
   not have the ability to make a Virtual Private Network (VPN)
   connection to the corporate network, either because the device is
   limited or because there are restrictions enforced by his Internet
   access provider.  If the device is equipped with a private key
   registered for jdoe@example.com by the administrator of the
   example.com domain and appropriate software to sign messages, John
   could sign the message on the device itself before transmission
   through the outgoing network of the access service provider.

B.1.3.  Roaming Users

   Roaming users often find themselves in circumstances where it is
   convenient or necessary to use an SMTP server other than their home
   server; examples are conferences and many hotels.  In such
   circumstances, a signature that is added by the submission service
   will use an identity that is different from the user's home system.

   Ideally, roaming users would connect back to their home server using
   either a VPN or a SUBMISSION server running with SMTP AUTHentication
   on port 587.  If the signing can be performed on the roaming user's
   laptop, then they can sign before submission, although the risk of
   further modification is high.  If neither of these are possible,
   these roaming users will not be able to send mail signed using their
   own domain key.







Crocker, et al.              Standards Track                   [Page 68]

RFC 6376                     DKIM Signatures              September 2011


B.1.4.  Independent (Kiosk) Message Submission

   Stand-alone services, such as walk-up kiosks and web-based
   information services, have no enduring email service relationship
   with the user, but users occasionally request that mail be sent on
   their behalf.  For example, a website providing news often allows the
   reader to forward a copy of the article to a friend.  This is
   typically done using the reader's own email address, to indicate who
   the author is.  This is sometimes referred to as the "Evite" problem,
   named after the website of the same name that allows a user to send
   invitations to friends.

   A common way this is handled is to continue to put the reader's email
   address in the From header field of the message but put an address
   owned by the email posting site into the Sender header field.  The
   posting site can then sign the message, using the domain that is in
   the Sender field.  This provides useful information to the receiving
   email site, which is able to correlate the signing domain with the
   initial submission email role.

   Receiving sites often wish to provide their end users with
   information about mail that is mediated in this fashion.  Although
   the real efficacy of different approaches is a subject for human
   factors usability research, one technique that is used is for the
   verifying system to rewrite the From header field to indicate the
   address that was verified, for example: From: John Doe via
   news@news-site.example <jdoe@example.com>.  (Note that such rewriting
   will break a signature, unless it is done after the verification pass
   is complete.)

B.2.  Alternate Delivery Scenarios

   Email is often received at a mailbox that has an address different
   from the one used during initial submission.  In these cases, an
   intermediary mechanism operates at the address originally used, and
   it then passes the message on to the final destination.  This
   mediation process presents some challenges for DKIM signatures.

B.2.1.  Affinity Addresses

   "Affinity addresses" allow a user to have an email address that
   remains stable, even as the user moves among different email
   providers.  They are typically associated with college alumni
   associations, professional organizations, and recreational
   organizations with which they expect to have a long-term
   relationship.  These domains usually provide forwarding of incoming
   email, and they often have an associated Web application that
   authenticates the user and allows the forwarding address to be



Crocker, et al.              Standards Track                   [Page 69]

RFC 6376                     DKIM Signatures              September 2011


   changed.  However, these services usually depend on users sending
   outgoing messages through their own service provider's MTAs.  Hence,
   mail that is signed with the domain of the affinity address is not
   signed by an entity that is administered by the organization owning
   that domain.

   With DKIM, affinity domains could use the Web application to allow
   users to register per-user keys to be used to sign messages on behalf
   of their affinity address.  The user would take away the secret half
   of the key pair for signing, and the affinity domain would publish
   the public half in DNS for access by Verifiers.

   This is another application that takes advantage of user-level
   keying, and domains used for affinity addresses would typically have
   a very large number of user-level keys.  Alternatively, the affinity
   domain could handle outgoing mail, operating a mail submission agent
   that authenticates users before accepting and signing messages for
   them.  This is, of course, dependent on the user's service provider
   not blocking the relevant TCP ports used for mail submission.

B.2.2.  Simple Address Aliasing (.forward)

   In some cases, a recipient is allowed to configure an email address
   to cause automatic redirection of email messages from the original
   address to another, such as through the use of a Unix .forward file.
   In this case, messages are typically redirected by the mail handling
   service of the recipient's domain, without modification, except for
   the addition of a Received header field to the message and a change
   in the envelope recipient address.  In this case, the recipient at
   the final address' mailbox is likely to be able to verify the
   original signature since the signed content has not changed, and DKIM
   is able to validate the message signature.

B.2.3.  Mailing Lists and Re-Posters

   There is a wide range of behaviors in services that take delivery of
   a message and then resubmit it.  A primary example is with mailing
   lists (collectively called "forwarders" below), ranging from those
   that make no modification to the message itself, other than to add a
   Received header field and change the envelope information, to those
   that add header fields, change the Subject header field, add content
   to the body (typically at the end), or reformat the body in some
   manner.  The simple ones produce messages that are quite similar to
   the automated alias services.  More elaborate systems essentially
   create a new message.






Crocker, et al.              Standards Track                   [Page 70]

RFC 6376                     DKIM Signatures              September 2011


   A Forwarder that does not modify the body or signed header fields of
   a message is likely to maintain the validity of the existing
   signature.  It also could choose to add its own signature to the
   message.

   Forwarders that modify a message in a way that could make an existing
   signature invalid are particularly good candidates for adding their
   own signatures (e.g., mailing-list-name@example.net).  Since
   (re-)signing is taking responsibility for the content of the message,
   these signing forwarders are likely to be selective and forward or
   re-sign a message only if it is received with a valid signature or if
   they have some other basis for knowing that the message is not
   spoofed.

   A common practice among systems that are primarily redistributors of
   mail is to add a Sender header field to the message to identify the
   address being used to sign the message.  This practice will remove
   any preexisting Sender header field as required by [RFC5322].  The
   forwarder applies a new DKIM-Signature header field with the
   signature, public key, and related information of the forwarder.

   See [RFC6377] for additional related topics and discussion.

Appendix C.  Creating a Public Key (INFORMATIVE)

   The default signature is an RSA-signed SHA-256 digest of the complete
   email.  For ease of explanation, the openssl command is used to
   describe the mechanism by which keys and signatures are managed.  One
   way to generate a 1024-bit, unencrypted private key suitable for DKIM
   is to use openssl like this:

   $ openssl genrsa -out rsa.private 1024

   For increased security, the "-passin" parameter can also be added to
   encrypt the private key.  Use of this parameter will require entering
   a password for several of the following steps.  Servers may prefer to
   use hardware cryptographic support.

   The "genrsa" step results in the file rsa.private containing the key
   information similar to this:











Crocker, et al.              Standards Track                   [Page 71]

RFC 6376                     DKIM Signatures              September 2011


   -----BEGIN RSA PRIVATE KEY-----
   MIICXwIBAAKBgQDwIRP/UC3SBsEmGqZ9ZJW3/DkMoGeLnQg1fWn7/zYtIxN2SnFC
   jxOCKG9v3b4jYfcTNh5ijSsq631uBItLa7od+v/RtdC2UzJ1lWT947qR+Rcac2gb
   to/NMqJ0fzfVjH4OuKhitdY9tf6mcwGjaNBcWToIMmPSPDdQPNUYckcQ2QIDAQAB
   AoGBALmn+XwWk7akvkUlqb+dOxyLB9i5VBVfje89Teolwc9YJT36BGN/l4e0l6QX
   /1//6DWUTB3KI6wFcm7TWJcxbS0tcKZX7FsJvUz1SbQnkS54DJck1EZO/BLa5ckJ
   gAYIaqlA9C0ZwM6i58lLlPadX/rtHb7pWzeNcZHjKrjM461ZAkEA+itss2nRlmyO
   n1/5yDyCluST4dQfO8kAB3toSEVc7DeFeDhnC1mZdjASZNvdHS4gbLIA1hUGEF9m
   3hKsGUMMPwJBAPW5v/U+AWTADFCS22t72NUurgzeAbzb1HWMqO4y4+9Hpjk5wvL/
   eVYizyuce3/fGke7aRYw/ADKygMJdW8H/OcCQQDz5OQb4j2QDpPZc0Nc4QlbvMsj
   7p7otWRO5xRa6SzXqqV3+F0VpqvDmshEBkoCydaYwc2o6WQ5EBmExeV8124XAkEA
   qZzGsIxVP+sEVRWZmW6KNFSdVUpk3qzK0Tz/WjQMe5z0UunY9Ax9/4PVhp/j61bf
   eAYXunajbBSOLlx4D+TunwJBANkPI5S9iylsbLs6NkaMHV6k5ioHBBmgCak95JGX
   GMot/L2x0IYyMLAz6oLWh2hm7zwtb0CgOrPo1ke44hFYnfc=
   -----END RSA PRIVATE KEY-----

   To extract the public-key component from the private key, use openssl
   like this:

   $ openssl rsa -in rsa.private -out rsa.public -pubout -outform PEM

   This results in the file rsa.public containing the key information
   similar to this:

   -----BEGIN PUBLIC KEY-----
   MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDwIRP/UC3SBsEmGqZ9ZJW3/DkM
   oGeLnQg1fWn7/zYtIxN2SnFCjxOCKG9v3b4jYfcTNh5ijSsq631uBItLa7od+v/R
   tdC2UzJ1lWT947qR+Rcac2gbto/NMqJ0fzfVjH4OuKhitdY9tf6mcwGjaNBcWToI
   MmPSPDdQPNUYckcQ2QIDAQAB
   -----END PUBLIC KEY-----

   This public-key data (without the BEGIN and END tags) is placed in
   the DNS:

   $ORIGIN _domainkey.example.org.
   brisbane IN  TXT  ("v=DKIM1; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQ"
                      "KBgQDwIRP/UC3SBsEmGqZ9ZJW3/DkMoGeLnQg1fWn7/zYt"
                      "IxN2SnFCjxOCKG9v3b4jYfcTNh5ijSsq631uBItLa7od+v"
                      "/RtdC2UzJ1lWT947qR+Rcac2gbto/NMqJ0fzfVjH4OuKhi"
                      "tdY9tf6mcwGjaNBcWToIMmPSPDdQPNUYckcQ2QIDAQAB")

C.1.  Compatibility with DomainKeys Key Records

   DKIM key records were designed to be backward compatible in many
   cases with key records used by DomainKeys [RFC4870] (sometimes
   referred to as "selector records" in the DomainKeys context).  One
   area of incompatibility warrants particular attention.  The "g=" tag
   value may be used in DomainKeys and [RFC4871] key records to provide



Crocker, et al.              Standards Track                   [Page 72]

RFC 6376                     DKIM Signatures              September 2011


   finer granularity of the validity of the key record to a specific
   local-part.  A null "g=" value in DomainKeys is valid for all
   addresses in the domain.  This differs from the usage in the original
   DKIM specification ([RFC4871]), where a null "g=" value is not valid
   for any address.  In particular, see the example public-key record in
   Section 3.2.3 of [RFC4870].

C.2.  RFC 4871 Compatibility

   Although the "g=" tag has been deprecated in this version of the DKIM
   specification (and thus MUST now be ignored), Signers are advised not
   to include the "g=" tag in key records because some [RFC4871]-
   compliant Verifiers will be in use for a considerable period to come.

Appendix D.  MUA Considerations (INFORMATIVE)

   When a DKIM signature is verified, the processing system sometimes
   makes the result available to the recipient user's MUA.  How to
   present this information to users in a way that helps them is a
   matter of continuing human factors usability research.  The tendency
   is to have the MUA highlight the SDID, in an attempt to show the user
   the identity that is claiming responsibility for the message.  An MUA
   might do this with visual cues such as graphics, might include the
   address in an alternate view, or might even rewrite the original From
   address using the verified information.  Some MUAs might indicate
   which header fields were protected by the validated DKIM signature.
   This could be done with a positive indication on the signed header
   fields, with a negative indication on the unsigned header fields, by
   visually hiding the unsigned header fields, or some combination of
   these.  If an MUA uses visual indications for signed header fields,
   the MUA probably needs to be careful not to display unsigned header
   fields in a way that might be construed by the end user as having
   been signed.  If the message has an "l=" tag whose value does not
   extend to the end of the message, the MUA might also hide or mark the
   portion of the message body that was not signed.

   The aforementioned information is not intended to be exhaustive.  The
   MUA can choose to highlight, accentuate, hide, or otherwise display
   any other information that may, in the opinion of the MUA author, be
   deemed important to the end user.

Appendix E.  Changes since RFC 4871

   o  Abstract and introduction refined based on accumulated experience.

   o  Various references updated.





Crocker, et al.              Standards Track                   [Page 73]

RFC 6376                     DKIM Signatures              September 2011


   o  Several errata resolved (see http://www.rfc-editor.org/):

      *  1376 applied

      *  1377 applied

      *  1378 applied

      *  1379 applied

      *  1380 applied

      *  1381 applied

      *  1382 applied

      *  1383 discarded (no longer applies)

      *  1384 applied

      *  1386 applied

      *  1461 applied

      *  1487 applied

      *  1532 applied

      *  1596 applied

   o  Introductory section enumerating relevant architectural documents
      added.

   o  Introductory section briefly discussing the matter of data
      integrity added.

   o  Allowed tolerance of some clock drift.

   o  Dropped "g=" tag from key records.  The implementation report
      indicates that it is not in use.

   o  Removed errant note about wildcards in the DNS.

   o  Removed SMTP-specific advice in most places.

   o  Reduced (non-normative) recommended signature content list, and
      reworked the text in that section.




Crocker, et al.              Standards Track                   [Page 74]

RFC 6376                     DKIM Signatures              September 2011


   o  Clarified signature generation algorithm by rewriting its pseudo-
      code.

   o  Numerous terminology subsections added, imported from [RFC5672].
      Also, began using these terms throughout the document (e.g., SDID,
      AUID).

   o  Sections added that specify input and output requirements.  Input
      requirements address a security concern raised by the working
      group (see also new sections in Security Considerations).  Output
      requirements are imported from [RFC5672].

   o  Appendix subsection added discussing compatibility with DomainKeys
      ([RFC4870]) records.

   o  Referred to [RFC5451] as an example method of communicating the
      results of DKIM verification.

   o  Removed advice about possible uses of the "l=" signature tag.

   o  IANA registry updated.

   o  Added two new Security Considerations sections talking about
      malformed message attacks.

   o  Various copy editing.

Appendix F.  Acknowledgments

   The previous IETF version of DKIM [RFC4871] was edited by Eric
   Allman, Jon Callas, Mark Delany, Miles Libbey, Jim Fenton, and
   Michael Thomas.

   That specification was the result of an extended collaborative
   effort, including participation by Russ Allbery, Edwin Aoki, Claus
   Assmann, Steve Atkins, Rob Austein, Fred Baker, Mark Baugher, Steve
   Bellovin, Nathaniel Borenstein, Dave Crocker, Michael Cudahy, Dennis
   Dayman, Jutta Degener, Frank Ellermann, Patrik Faeltstroem, Mark
   Fanto, Stephen Farrell, Duncan Findlay, Elliot Gillum, Olafur
   Gudmundsson, Phillip Hallam-Baker, Tony Hansen, Sam Hartman, Arvel
   Hathcock, Amir Herzberg, Paul Hoffman, Russ Housley, Craig Hughes,
   Cullen Jennings, Don Johnsen, Harry Katz, Murray S. Kucherawy, Barry
   Leiba, John Levine, Charles Lindsey, Simon Longsdale, David Margrave,
   Justin Mason, David Mayne, Thierry Moreau, Steve Murphy, Russell
   Nelson, Dave Oran, Doug Otis, Shamim Pirzada, Juan Altmayer Pizzorno,
   Sanjay Pol, Blake Ramsdell, Christian Renaud, Scott Renfro, Neil





Crocker, et al.              Standards Track                   [Page 75]

RFC 6376                     DKIM Signatures              September 2011


   Rerup, Eric Rescorla, Dave Rossetti, Hector Santos, Jim Schaad, the
   Spamhaus.org team, Malte S. Stretz, Robert Sanders, Rand Wacker, Sam
   Weiler, and Dan Wing.

   The earlier DomainKeys was a primary source from which DKIM was
   derived.  Further information about DomainKeys is at [RFC4870].

   This revision received contributions from Steve Atkins, Mark Delany,
   J.D. Falk, Jim Fenton, Michael Hammer, Barry Leiba, John Levine,
   Charles Lindsey, Jeff Macdonald, Franck Martin, Brett McDowell, Doug
   Otis, Bill Oxley, Hector Santos, Rolf Sonneveld, Michael Thomas, and
   Alessandro Vesely.

Authors' Addresses

   Dave Crocker (editor)
   Brandenburg InternetWorking
   675 Spruce Dr.
   Sunnyvale, CA  94086
   USA

   Phone: +1.408.246.8253
   EMail: dcrocker@bbiw.net
   URI:   http://bbiw.net


   Tony Hansen (editor)
   AT&T Laboratories
   200 Laurel Ave. South
   Middletown, NJ  07748
   USA

   EMail: tony+dkimsig@maillennium.att.com


   Murray S. Kucherawy (editor)
   Cloudmark
   128 King St., 2nd Floor
   San Francisco, CA  94107
   USA

   EMail: msk@cloudmark.com









Crocker, et al.              Standards Track                   [Page 76]



================================================
FILE: doc/notes/smtp.txt
================================================
General Notes
--------------
 * MX is NOT required, but an A record, or CNAME to a MX MUST be present at the least.
 * EHLO should be tried, then fall back to HELO
 * The 250 return code from RCPT TO is not actually clear-cut. A 251 may be
   returned if the message was forwarded to another address.  This could be a
   useful indicator to end-users that an address should be updated.
 * RCPT TO can accpet just "postmaster" without a domain name
 * Server MUST not close connection before:
   - QUIT and returning 221 response
   - Forced requirement, and only after returning a 421 response
   - Clients expriencing a forced connection closure, without prior warning should
     just treat it like a 451 closure regardless
 * ALWAYS use blocking sockets for the initial connection (this should prevent
   Exim4's whining about sync).

Response codes
--------------
 * From RFC2821, 4.2.
   - In particular, the 220, 221, 251, 421, and 551 reply codes
     are associated with message text that must be parsed and interpreted
     by machines.

Error Codes
------------
 * Numeric 5yz = Error
   - 550/RCPT TO = Relay denied
   - 500 = Unknown command
 * Numeric 2yz = Normal
 * Numeric 4yz = Temporary failure??

<?php

class EsmtpTransport implements Transport, EsmtpCommandWriter {
}

interface EsmtpCommandWriter {
  public function getBuffer();
  public function executeCommand($command, $expectedCodes);
}

interface Extension {
  public function getKeyword();
  public function afterEhlo($commandWriter);
  public function getRcptParams();
  public function getMailParams();
  public function atCommand($commandWriter, $command, $expectedResponse) throws CommandSentException;
}


================================================
FILE: doc/plugins.rst
================================================
Plugins
=======

Plugins exist to extend, or modify the behaviour of Swift Mailer. They respond
to Events that are fired within the Transports during sending.

There are a number of Plugins provided as part of the base Swift Mailer package
and they all follow a common interface to respond to Events fired within the
library. Interfaces are provided to "listen" to each type of Event fired and to
act as desired when a listened-to Event occurs.

Although several plugins are provided with Swift Mailer out-of-the-box, the
Events system has been specifically designed to make it easy for experienced
object-oriented developers to write their own plugins in order to achieve
goals that may not be possible with the base library.

AntiFlood Plugin
----------------

Many SMTP servers have limits on the number of messages that may be sent during
any single SMTP connection. The AntiFlood plugin provides a way to stay within
this limit while still managing a large number of emails.

A typical limit for a single connection is 100 emails. If the server you
connect to imposes such a limit, it expects you to disconnect after that number
of emails has been sent. You could manage this manually within a loop, but the
AntiFlood plugin provides the necessary wrapper code so that you don't need to
worry about this logic.

Regardless of limits imposed by the server, it's usually a good idea to be
conservative with the resources of the SMTP server. Sending will become
sluggish if the server is being over-used so using the AntiFlood plugin will
not be a bad idea even if no limits exist.

The AntiFlood plugin's logic is basically to disconnect and the immediately
re-connect with the SMTP server every X number of emails sent, where X is a
number you specify to the plugin.

You can also specify a time period in seconds that Swift Mailer should pause
for between the disconnect/re-connect process. It's a good idea to pause for a
short time (say 30 seconds every 100 emails) simply to give the SMTP server a
chance to process its queue and recover some resources.

Using the AntiFlood Plugin
~~~~~~~~~~~~~~~~~~~~~~~~~~

The AntiFlood Plugin -- like all plugins -- is added with the Mailer class's
``registerPlugin()`` method. It takes two constructor parameters: the number of
emails to pause after, and optionally the number of seconds to pause for.

When Swift Mailer sends messages it will count the number of messages that have
been sent since the last re-connect. Once the number hits your specified
threshold it will disconnect and re-connect, optionally pausing for a specified
amount of time::

    // Create the Mailer using any Transport
    $mailer = new Swift_Mailer(
      new Swift_SmtpTransport('smtp.example.org', 25)
    );

    // Use AntiFlood to re-connect after 100 emails
    $mailer->registerPlugin(new Swift_Plugins_AntiFloodPlugin(100));

    // And specify a time in seconds to pause for (30 secs)
    $mailer->registerPlugin(new Swift_Plugins_AntiFloodPlugin(100, 30));

    // Continue sending as normal
    for ($lotsOfRecipients as $recipient) {
      ...

      $mailer->send( ... );
    }

Throttler Plugin
----------------

If your SMTP server has restrictions in place to limit the rate at which you
send emails, then your code will need to be aware of this rate-limiting. The
Throttler plugin makes Swift Mailer run at a rate-limited speed.

Many shared hosts don't open their SMTP servers as a free-for-all. Usually they
have policies in place (probably to discourage spammers) that only allow you to
send a fixed number of emails per-hour/day.

The Throttler plugin supports two modes of rate-limiting and with each, you
will need to do that math to figure out the values you want. The plugin can
limit based on the number of emails per minute, or the number of
bytes-transferred per-minute.

Using the Throttler Plugin
~~~~~~~~~~~~~~~~~~~~~~~~~~

The Throttler Plugin -- like all plugins -- is added with the Mailer class'
``registerPlugin()`` method. It has two required constructor parameters that
tell it how to do its rate-limiting.

When Swift Mailer sends messages it will keep track of the rate at which
sending messages is occurring. If it realises that sending is happening too
fast, it will cause your program to ``sleep()`` for enough time to average out
the rate::

    // Create the Mailer using any Transport
    $mailer = new Swift_Mailer(
      new Swift_SmtpTransport('smtp.example.org', 25)
    );

    // Rate limit to 100 emails per-minute
    $mailer->registerPlugin(new Swift_Plugins_ThrottlerPlugin(
      100, Swift_Plugins_ThrottlerPlugin::MESSAGES_PER_MINUTE
    ));

    // Rate limit to 10MB per-minute
    $mailer->registerPlugin(new Swift_Plugins_ThrottlerPlugin(
      1024 * 1024 * 10, Swift_Plugins_ThrottlerPlugin::BYTES_PER_MINUTE
    ));

    // Continue sending as normal
    for ($lotsOfRecipients as $recipient) {
      ...

      $mailer->send( ... );
    }

Logger Plugin
-------------

The Logger plugins helps with debugging during the process of sending. It can
help to identify why an SMTP server is rejecting addresses, or any other
hard-to-find problems that may arise.

The Logger plugin comes in two parts. There's the plugin itself, along with one
of a number of possible Loggers that you may choose to use. For example, the
logger may output messages directly in realtime, or it may capture messages in
an array.

One other notable feature is the way in which the Logger plugin changes
Exception messages. If Exceptions are being thrown but the error message does
not provide conclusive information as to the source of the problem (such as an
ambiguous SMTP error) the Logger plugin includes the entire SMTP transcript in
the error message so that debugging becomes a simpler task.

There are a few available Loggers included with Swift Mailer, but writing your
own implementation is incredibly simple and is achieved by creating a short
class that implements the ``Swift_Plugins_Logger`` interface.

* ``Swift_Plugins_Loggers_ArrayLogger``: Keeps a collection of log messages
  inside an array. The array content can be cleared or dumped out to the screen.

* ``Swift_Plugins_Loggers_EchoLogger``: Prints output to the screen in
  realtime. Handy for very rudimentary debug output.

Using the Logger Plugin
~~~~~~~~~~~~~~~~~~~~~~~

The Logger Plugin -- like all plugins -- is added with the Mailer class'
``registerPlugin()`` method. It accepts an instance of ``Swift_Plugins_Logger``
in its constructor.

When Swift Mailer sends messages it will keep a log of all the interactions
with the underlying Transport being used. Depending upon the Logger that has
been used the behaviour will differ, but all implementations offer a way to get
the contents of the log::

    // Create the Mailer using any Transport
    $mailer = new Swift_Mailer(
     new Swift_SmtpTransport('smtp.example.org', 25)
    );

    // To use the ArrayLogger
    $logger = new Swift_Plugins_Loggers_ArrayLogger();
    $mailer->registerPlugin(new Swift_Plugins_LoggerPlugin($logger));

    // Or to use the Echo Logger
    $logger = new Swift_Plugins_Loggers_EchoLogger();
    $mailer->registerPlugin(new Swift_Plugins_LoggerPlugin($logger));

    // Continue sending as normal
    for ($lotsOfRecipients as $recipient) {
     ...

     $mailer->send( ... );
    }

    // Dump the log contents
    // NOTE: The EchoLogger dumps in realtime so dump() does nothing for it
    echo $logger->dump();

Decorator Plugin
----------------

Often there's a need to send the same message to multiple recipients, but with
tiny variations such as the recipient's name being used inside the message
body. The Decorator plugin aims to provide a solution for allowing these small
differences.

The decorator plugin works by intercepting the sending process of Swift Mailer,
reading the email address in the To: field and then looking up a set of
replacements for a template.

While the use of this plugin is simple, it is probably the most commonly
misunderstood plugin due to the way in which it works. The typical mistake
users make is to try registering the plugin multiple times (once for each
recipient) -- inside a loop for example. This is incorrect.

The Decorator plugin should be registered just once, but containing the list of
all recipients prior to sending. It will use this list of recipients to find
the required replacements during sending.

Using the Decorator Plugin
~~~~~~~~~~~~~~~~~~~~~~~~~~

To use the Decorator plugin, simply create an associative array of replacements
based on email addresses and then use the mailer's ``registerPlugin()`` method
to add the plugin.

First create an associative array of replacements based on the email addresses
you'll be sending the message to.

.. note::

    The replacements array becomes a 2-dimensional array whose keys are the
    email addresses and whose values are an associative array of replacements
    for that email address. The curly braces used in this example can be any
    type of syntax you choose, provided they match the placeholders in your
    email template::

        $replacements = [];
        foreach ($users as $user) {
          $replacements[$user['email']] = [
            '{username}'=>$user['username'],
            '{resetcode}'=>$user['resetcode']
          ];
        }

Now create an instance of the Decorator plugin using this array of replacements
and then register it with the Mailer. Do this only once!

::

    $decorator = new Swift_Plugins_DecoratorPlugin($replacements);

    $mailer->registerPlugin($decorator);

When you create your message, replace elements in the body (and/or the subject
line) with your placeholders::

    $message = (new Swift_Message())
      ->setSubject('Important notice for {username}')
      ->setBody(
        "Hello {username}, you requested to reset your password.\n" .
        "Please visit https://example.com/pwreset and use the reset code {resetcode} to set a new password."
      )
      ;

    foreach ($users as $user) {
      $message->addTo($user['email']);
    }

When you send this message to each of your recipients listed in your
``$replacements`` array they will receive a message customized for just
themselves. For example, the message used above when received may appear like
this to one user:

.. code-block:: text

    Subject: Important notice for smilingsunshine2009

    Hello smilingsunshine2009, you requested to reset your password.
    Please visit https://example.com/pwreset and use the reset code 183457 to set a new password.

While another use may receive the message as:

.. code-block:: text

    Subject: Important notice for billy-bo-bob

    Hello billy-bo-bob, you requested to reset your password.
    Please visit https://example.com/pwreset and use the reset code 539127 to set a new password.

While the decorator plugin provides a means to solve this problem, there are
various ways you could tackle this problem without the need for a plugin. We're
trying to come up with a better way ourselves and while we have several
(obvious) ideas we don't quite have the perfect solution to go ahead and
implement it. Watch this space.

Providing Your Own Replacements Lookup for the Decorator
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Filling an array with replacements may not be the best solution for providing
replacement information to the decorator. If you have a more elegant algorithm
that performs replacement lookups on-the-fly you may provide your own
implementation.

Providing your own replacements lookup implementation for the Decorator is
simply a matter of passing an instance of
``Swift_Plugins_Decorator_Replacements`` to the decorator plugin's constructor,
rather than passing in an array.

The Replacements interface is very simple to implement since it has just one
method: ``getReplacementsFor($address)``.

Imagine you want to look up replacements from a database on-the-fly, you might
provide an implementation that does this. You need to create a small class::

    class DbReplacements implements Swift_Plugins_Decorator_Replacements {
      public function getReplacementsFor($address) {
        global $db; // Your PDO instance with a connection to your database
        $query = $db->prepare(
          "SELECT * FROM `users` WHERE `email` = ?"
        );

        $query->execute([$address]);

        if ($row = $query->fetch(PDO::FETCH_ASSOC)) {
          return [
            '{username}'=>$row['username'],
            '{resetcode}'=>$row['resetcode']
          ];
        }
      }
    }

Now all you need to do is pass an instance of your class into the Decorator
plugin's constructor instead of passing an array::

    $decorator = new Swift_Plugins_DecoratorPlugin(new DbReplacements());

    $mailer->registerPlugin($decorator);

For each message sent, the plugin will call your class'
``getReplacementsFor()`` method to find the array of replacements it needs.

.. note::

    If your lookup algorithm is case sensitive, you should transform the
    ``$address`` argument as appropriate -- for example by passing it through
    ``strtolower()``.


================================================
FILE: doc/sending.rst
================================================
Sending Messages
================

Quick Reference for Sending a Message
-------------------------------------

Sending a message is very straightforward. You create a Transport, use it to
create the Mailer, then you use the Mailer to send the message.

When using ``send()`` the message will be sent just like it would be sent if
you used your mail client. An integer is returned which includes the number of
successful recipients. If none of the recipients could be sent to then zero
will be returned, which equates to a boolean ``false``. If you set two ``To:``
recipients and three ``Bcc:`` recipients in the message and all of the
recipients are delivered to successfully then the value 5 will be returned::

    // Create the Transport
    $transport = (new Swift_SmtpTransport('smtp.example.org', 25))
      ->setUsername('your username')
      ->setPassword('your password')
      ;

    /*
    You could alternatively use a different transport such as Sendmail:

    // Sendmail
    $transport = new Swift_SendmailTransport('/usr/sbin/sendmail -bs');
    */

    // Create the Mailer using your created Transport
    $mailer = new Swift_Mailer($transport);

    // Create a message
    $message = (new Swift_Message('Wonderful Subject'))
      ->setFrom(['john@doe.com' => 'John Doe'])
      ->setTo(['receiver@domain.org', 'other@domain.org' => 'A name'])
      ->setBody('Here is the message itself')
      ;

    // Send the message
    $result = $mailer->send($message);

Transport Types
~~~~~~~~~~~~~~~

Transports are the classes in Swift Mailer that are responsible for
communicating with a service in order to deliver a Message. There are several
types of Transport in Swift Mailer, all of which implement the
``Swift_Transport`` interface::

* ``Swift_SmtpTransport``: Sends messages over SMTP; Supports Authentication;
  Supports Encryption. Very portable; Pleasingly predictable results; Provides
  good feedback;

* ``Swift_SendmailTransport``: Communicates with a locally installed
  ``sendmail`` executable (Linux/UNIX). Quick time-to-run; Provides
  less-accurate feedback than SMTP; Requires ``sendmail`` installation;

* ``Swift_LoadBalancedTransport``: Cycles through a collection of the other
  Transports to manage load-reduction. Provides graceful fallback if one
  Transport fails (e.g. an SMTP server is down); Keeps the load on remote
  services down by spreading the work;

* ``Swift_FailoverTransport``: Works in conjunction with a collection of the
  other Transports to provide high-availability. Provides graceful fallback if
  one Transport fails (e.g. an SMTP server is down).

The SMTP Transport
..................

The SMTP Transport sends messages over the (standardized) Simple Message
Transfer Protocol. It can deal with encryption and authentication.

The SMTP Transport, ``Swift_SmtpTransport`` is without doubt the most commonly
used Transport because it will work on 99% of web servers (I just made that
number up, but you get the idea). All the server needs is the ability to
connect to a remote (or even local) SMTP server on the correct port number
(usually 25).

SMTP servers often require users to authenticate with a username and password
before any mail can be sent to other domains. This is easily achieved using
Swift Mailer with the SMTP Transport.

SMTP is a protocol -- in other words it's a "way" of communicating a job to be
done (i.e. sending a message). The SMTP protocol is the fundamental basis on
which messages are delivered all over the internet 7 days a week, 365 days a
year. For this reason it's the most "direct" method of sending messages you can
use and it's the one that will give you the most power and feedback (such as
delivery failures) when using Swift Mailer.

Because SMTP is generally run as a remote service (i.e. you connect to it over
the network/internet) it's extremely portable from server-to-server. You can
easily store the SMTP server address and port number in a configuration file
within your application and adjust the settings accordingly if the code is
moved or if the SMTP server is changed.

Some SMTP servers -- Google for example -- use encryption for security reasons.
Swift Mailer supports using both ``ssl`` (SMTPS = SMTP over TLS) and ``tls``
(SMTP with STARTTLS) encryption settings.

Using the SMTP Transport
^^^^^^^^^^^^^^^^^^^^^^^^

The SMTP Transport is easy to use. Most configuration options can be set with
the constructor.

To use the SMTP Transport you need to know which SMTP server your code needs to
connect to. Ask your web host if you're not sure. Lots of people ask me who to
connect to -- I really can't answer that since it's a setting that's extremely
specific to your hosting environment.

A connection to the SMTP server will be established upon the first call to
``send()``::

    // Create the Transport
    $transport = new Swift_SmtpTransport('smtp.example.org', 25);

    // Create the Mailer using your created Transport
    $mailer = new Swift_Mailer($transport);

    /*
    It's also possible to use multiple method calls

    $transport = (new Swift_SmtpTransport())
      ->setHost('smtp.example.org')
      ->setPort(25)
      ;
    */

Encrypted SMTP
^^^^^^^^^^^^^^

You can use ``ssl`` (SMTPS) or ``tls`` (STARTTLS) encryption with the SMTP Transport
by specifying it as a parameter or with a method call::

    // Create the Transport
    // Option #1: SMTPS = SMTP over TLS (always encrypted):
    $transport = new Swift_SmtpTransport('smtp.example.org', 587, 'ssl');
    // Option #2: SMTP with STARTTLS (best effort encryption):
    $transport = new Swift_SmtpTransport('smtp.example.org', 587, 'tls');

    // Create the Mailer using your created Transport
    $mailer = new Swift_Mailer($transport);

A connection to the SMTP server will be established upon the first call to
``send()``. The connection will be initiated with the correct encryption
settings.

.. note::
    For SMTPS or STARTTLS encryption to work your PHP installation must have
    appropriate OpenSSL transports wrappers. You can check if "tls" and/or
    "ssl" are present in your PHP installation by using the PHP function
    ``stream_get_transports()``.

.. note::
    If you are using Mailcatcher_, make sure you do not set the encryption
    for the ``Swift_SmtpTransport``, since Mailcatcher does not support encryption.

.. note::
    When in doubt, try ``ssl`` first for higher security, since the communication
    is always encrypted.

.. note::
    Usually, port 587 or 465 is used for encrypted SMTP. Check the documentation
    of your mail provider.

SMTP with a Username and Password
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Some servers require authentication. You can provide a username and password
with ``setUsername()`` and ``setPassword()`` methods::

    // Create the Transport the call setUsername() and setPassword()
    $transport = (new Swift_SmtpTransport('smtp.example.org', 25))
      ->setUsername('username')
      ->setPassword('password')
      ;

    // Create the Mailer using your created Transport
    $mailer = new Swift_Mailer($transport);

Your username and password will be used to authenticate upon first connect when
``send()`` are first used on the Mailer.

If authentication fails, an Exception of type ``Swift_TransportException`` will
be thrown.

.. note::

    If you need to know early whether or not authentication has failed and an
    Exception is going to be thrown, call the ``start()`` method on the
    created Transport.

The Sendmail Transport
......................

The Sendmail Transport sends messages by communicating with a locally installed
MTA -- such as ``sendmail``.

The Sendmail Transport, ``Swift_SendmailTransport`` does not directly connect
to any remote services. It is designed for Linux servers that have ``sendmail``
installed. The Transport starts a local ``sendmail`` process and sends messages
to it. Usually the ``sendmail`` process will respond quickly as it spools your
messages to disk before sending them.

The Transport is named the Sendmail Transport for historical reasons
(``sendmail`` was the "standard" UNIX tool for sending e-mail for years). It
will send messages using other transfer agents such as Exim or Postfix despite
its name, provided they have the relevant sendmail wrappers so that they can be
started with the correct command-line flags.

It's a common misconception that because the Sendmail Transport returns a
result very quickly it must therefore deliver messages to recipients quickly --
this is not true. It's not slow by any means, but it's certainly not faster
than SMTP when it comes to getting messages to the intended recipients. This is
because sendmail itself sends the messages over SMTP once they have been
quickly spooled to disk.

The Sendmail Transport has the potential to be just as smart of the SMTP
Transport when it comes to notifying Swift Mailer about which recipients were
rejected, but in reality the majority of locally installed ``sendmail``
instances are not configured well enough to provide any useful feedback. As
such Swift Mailer may report successful deliveries where they did in fact fail
before they even left your server.

You can run the Sendmail Transport in two different modes specified by command
line flags:

* "``-bs``" runs in SMTP mode so theoretically it will act like the SMTP
  Transport

* "``-t``" runs in piped mode with no feedback, but theoretically faster,
  though not advised

You can think of the Sendmail Transport as a sort of asynchronous SMTP
Transport -- though if you have problems with delivery failures you should try
using the SMTP Transport instead. Swift Mailer isn't doing the work here, it's
simply passing the work to somebody else (i.e. ``sendmail``).

Using the Sendmail Transport
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

To use the Sendmail Transport you simply need to call ``new
Swift_SendmailTransport()`` with the command as a parameter.

To use the Sendmail Transport you need to know where ``sendmail`` or another
MTA exists on the server. Swift Mailer uses a default value of
``/usr/sbin/sendmail``, which should work on most systems.

You specify the entire command as a parameter (i.e. including the command line
flags). Swift Mailer supports operational modes of "``-bs``" (default) and
"``-t``".

.. note::

    If you run sendmail in "``-t``" mode you will get no feedback as to whether
    or not sending has succeeded. Use "``-bs``" unless you have a reason not to.

A sendmail process will be started upon the first call to ``send()``. If the
process cannot be started successfully an Exception of type
``Swift_TransportException`` will be thrown::

    // Create the Transport
    $transport = new Swift_SendmailTransport('/usr/sbin/exim -bs');

    // Create the Mailer using your created Transport
    $mailer = new Swift_Mailer($transport);

Available Methods for Sending Messages
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The Mailer class offers one method for sending Messages -- ``send()``.

When a message is sent in Swift Mailer, the Mailer class communicates with
whichever Transport class you have chosen to use.

Each recipient in the message should either be accepted or rejected by the
Transport. For example, if the domain name on the email address is not
reachable the SMTP Transport may reject the address because it cannot process
it. ``send()`` will return an integer indicating the number of accepted
recipients.

.. note::

    It's possible to find out which recipients were rejected -- we'll cover that
    later in this chapter.

Using the ``send()`` Method
...........................

The ``send()`` method of the ``Swift_Mailer`` class sends a message using
exactly the same logic as your Desktop mail client would use. Just pass it a
Message and get a result.

The message will be sent just like it would be sent if you used your mail
client. An integer is returned which includes the number of successful
recipients. If none of the recipients could be sent to then zero will be
returned, which equates to a boolean ``false``. If you set two
``To:`` recipients and three ``Bcc:`` recipients in the message and all of the
recipients are delivered to successfully then the value 5 will be returned::

    // Create the Transport
    $transport = new Swift_SmtpTransport('localhost', 25);

    // Create the Mailer using your created Transport
    $mailer = new Swift_Mailer($transport);

    // Create a message
    $message = (new Swift_Message('Wonderful Subject'))
      ->setFrom(['john@doe.com' => 'John Doe'])
      ->setTo(['receiver@domain.org', 'other@domain.org' => 'A name'])
      ->setBody('Here is the message itself')
      ;

    // Send the message
    $numSent = $mailer->send($message);

    printf("Sent %d messages\n", $numSent);

    /* Note that often that only the boolean equivalent of the
       return value is of concern (zero indicates FALSE)

    if ($mailer->send($message))
    {
      echo "Sent\n";
    }
    else
    {
      echo "Failed\n";
    }

    */

Sending Emails in Batch
.......................

If you want to send a separate message to each recipient so that only their own
address shows up in the ``To:`` field, follow the following recipe:

* Create a Transport from one of the provided Transports --
  ``Swift_SmtpTransport``, ``Swift_SendmailTransport``,
  or one of the aggregate Transports.

* Create an instance of the ``Swift_Mailer`` class, using the Transport as
  it's constructor parameter.

* Create a Message.

* Iterate over the recipients and send message via the ``send()`` method on
  the Mailer object.

Each recipient of the messages receives a different copy with only their own
email address on the ``To:`` field.

Make sure to add only valid email addresses as recipients. If you try to add an
invalid email address with ``setTo()``, ``setCc()`` or ``setBcc()``, Swift
Mailer will throw a ``Swift_RfcComplianceException``.

If you add recipients automatically based on a data source that may contain
invalid email addresses, you can prevent possible exceptions by validating the
addresses using ``Egulias\EmailValidator\EmailValidator`` (a dependency that is
installed with Swift Mailer) and only adding addresses that validate. Another
way would be to wrap your ``setTo()``, ``setCc()`` and ``setBcc()`` calls in a
try-catch block and handle the ``Swift_RfcComplianceException`` in the catch
block.

Handling invalid addresses properly is especially important when sending emails
in large batches since a single invalid address might cause an unhandled
exception and stop the execution or your script early.

.. note::

    In the following example, two emails are sent. One to each of
    ``receiver@domain.org`` and ``other@domain.org``. These recipients will
    not be aware of each other::

        // Create the Transport
        $transport = new Swift_SmtpTransport('localhost', 25);

        // Create the Mailer using your created Transport
        $mailer = new Swift_Mailer($transport);

        // Create a message
        $message = (new Swift_Message('Wonderful Subject'))
          ->setFrom(['john@doe.com' => 'John Doe'])
          ->setBody('Here is the message itself')
          ;

        // Send the message
        $failedRecipients = [];
        $numSent = 0;
        $to = ['receiver@domain.org', 'other@domain.org' => 'A name'];

        foreach ($to as $address => $name)
        {
          if (is_int($address)) {
            $message->setTo($name);
          } else {
            $message->setTo([$address => $name]);
          }

          $numSent += $mailer->send($message, $failedRecipients);
        }

        printf("Sent %d messages\n", $numSent);

Finding out Rejected Addresses
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

It's possible to get a list of addresses that were rejected by the Transport by
using a by-reference parameter to ``send()``.

As Swift Mailer attempts to send the message to each address given to it, if a
recipient is rejected it will be added to the array. You can pass an existing
array, otherwise one will be created by-reference.

Collecting the list of recipients that were rejected can be useful in
circumstances where you need to "prune" a mailing list for example when some
addresses cannot be delivered to.

Getting Failures By-reference
.............................

Collecting delivery failures by-reference with the ``send()`` method is as
simple as passing a variable name to the method call::

    $mailer = new Swift_Mailer( ... );

    $message = (new Swift_Message( ... ))
      ->setFrom( ... )
      ->setTo([
        'receiver@bad-domain.org' => 'Receiver Name',
        'other@domain.org' => 'A name',
        'other-receiver@bad-domain.org' => 'Other Name'
      ))
      ->setBody( ... )
      ;

    // Pass a variable name to the send() method
    if (!$mailer->send($message, $failures))
    {
      echo "Failures:";
      print_r($failures);
    }

    /*
    Failures:
    Array (
      0 => receiver@bad-domain.org,
      1 => other-receiver@bad-domain.org
    )
    */

If the Transport rejects any of the recipients, the culprit addresses will be
added to the array provided by-reference.

.. note::

    If the variable name does not yet exist, it will be initialized as an
    empty array and then failures will be added to that array. If the variable
    already exists it will be type-cast to an array and failures will be added
    to it.

.. _Mailcatcher: https://mailcatcher.me/


================================================
FILE: lib/classes/Swift/AddressEncoder/IdnAddressEncoder.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2018 Christian Schmidt
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * An IDN email address encoder.
 *
 * Encodes the domain part of an address using IDN. This is compatible will all
 * SMTP servers.
 *
 * This encoder does not support email addresses with non-ASCII characters in
 * local-part (the substring before @). To send to such addresses, use
 * Swift_AddressEncoder_Utf8AddressEncoder together with
 * Swift_Transport_Esmtp_SmtpUtf8Handler. Your outbound SMTP server must support
 * the SMTPUTF8 extension.
 *
 * @author Christian Schmidt
 */
class Swift_AddressEncoder_IdnAddressEncoder implements Swift_AddressEncoder
{
    /**
     * Encodes the domain part of an address using IDN.
     *
     * @throws Swift_AddressEncoderException If local-part contains non-ASCII characters
     */
    public function encodeString(string $address): string
    {
        $i = strrpos($address, '@');
        if (false !== $i) {
            $local = substr($address, 0, $i);
            $domain = substr($address, $i + 1);

            if (preg_match('/[^\x00-\x7F]/', $local)) {
                throw new Swift_AddressEncoderException('Non-ASCII characters not supported in local-part', $address);
            }

            if (preg_match('/[^\x00-\x7F]/', $domain)) {
                $address = sprintf('%s@%s', $local, idn_to_ascii($domain, 0, INTL_IDNA_VARIANT_UTS46));
            }
        }

        return $address;
    }
}


================================================
FILE: lib/classes/Swift/AddressEncoder/Utf8AddressEncoder.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2018 Christian Schmidt
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * A UTF-8 email address encoder.
 *
 * Returns the email address verbatimly in UTF-8 as permitted by RFC 6531 and
 * RFC 6532. It supports addresses containing non-ASCII characters in both
 * local-part and domain (i.e. on both sides of @).
 *
 * This encoder must be used together with Swift_Transport_Esmtp_SmtpUtf8Handler
 * and requires that the outbound SMTP server supports the SMTPUTF8 extension.
 *
 * If your outbound SMTP server does not support SMTPUTF8, use
 * Swift_AddressEncoder_IdnAddressEncoder instead. This allows sending to email
 * addresses with non-ASCII characters in the domain, but not in local-part.
 *
 * @author Christian Schmidt
 */
class Swift_AddressEncoder_Utf8AddressEncoder implements Swift_AddressEncoder
{
    /**
     * Returns the address verbatimly.
     */
    public function encodeString(string $address): string
    {
        return $address;
    }
}


================================================
FILE: lib/classes/Swift/AddressEncoder.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2018 Christian Schmidt
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Email address encoder.
 *
 * @author Christian Schmidt
 */
interface Swift_AddressEncoder
{
    /**
     * Encodes an email address.
     *
     * @throws Swift_AddressEncoderException if the email cannot be represented in
     *                                       the encoding implemented by this class
     */
    public function encodeString(string $address): string;
}


================================================
FILE: lib/classes/Swift/AddressEncoderException.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2018 Christian Schmidt
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * AddressEncoderException when the specified email address is in a format that
 * cannot be encoded by a given address encoder.
 *
 * @author Christian Schmidt
 */
class Swift_AddressEncoderException extends Swift_RfcComplianceException
{
    protected $address;

    public function __construct(string $message, string $address)
    {
        parent::__construct($message);

        $this->address = $address;
    }

    public function getAddress(): string
    {
        return $this->address;
    }
}


================================================
FILE: lib/classes/Swift/Attachment.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Attachment class for attaching files to a {@link Swift_Mime_SimpleMessage}.
 *
 * @author Chris Corbyn
 */
class Swift_Attachment extends Swift_Mime_Attachment
{
    /**
     * Create a new Attachment.
     *
     * Details may be optionally provided to the constructor.
     *
     * @param string|Swift_OutputByteStream $data
     * @param string                        $filename
     * @param string                        $contentType
     */
    public function __construct($data = null, $filename = null, $contentType = null)
    {
        \call_user_func_array(
            [$this, 'Swift_Mime_Attachment::__construct'],
            Swift_DependencyContainer::getInstance()
                ->createDependenciesFor('mime.attachment')
            );

        $this->setBody($data, $contentType);
        $this->setFilename($filename);
    }

    /**
     * Create a new Attachment from a filesystem path.
     *
     * @param string $path
     * @param string $contentType optional
     *
     * @return self
     */
    public static function fromPath($path, $contentType = null)
    {
        return (new self())->setFile(
            new Swift_ByteStream_FileByteStream($path),
            $contentType
        );
    }
}


================================================
FILE: lib/classes/Swift/ByteStream/AbstractFilterableInputStream.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Provides the base functionality for an InputStream supporting filters.
 *
 * @author Chris Corbyn
 */
abstract class Swift_ByteStream_AbstractFilterableInputStream implements Swift_InputByteStream, Swift_Filterable
{
    /**
     * Write sequence.
     */
    protected $sequence = 0;

    /**
     * StreamFilters.
     *
     * @var Swift_StreamFilter[]
     */
    private $filters = [];

    /**
     * A buffer for writing.
     */
    private $writeBuffer = '';

    /**
     * Bound streams.
     *
     * @var Swift_InputByteStream[]
     */
    private $mirrors = [];

    /**
     * Commit the given bytes to the storage medium immediately.
     *
     * @param string $bytes
     */
    abstract protected function doCommit($bytes);

    /**
     * Flush any buffers/content with immediate effect.
     */
    abstract protected function flush();

    /**
     * Add a StreamFilter to this InputByteStream.
     *
     * @param string $key
     */
    public function addFilter(Swift_StreamFilter $filter, $key)
    {
        $this->filters[$key] = $filter;
    }

    /**
     * Remove an already present StreamFilter based on its $key.
     *
     * @param string $key
     */
    public function removeFilter($key)
    {
        unset($this->filters[$key]);
    }

    /**
     * Writes $bytes to the end of the stream.
     *
     * @param string $bytes
     *
     * @throws Swift_IoException
     *
     * @return int
     */
    public function write($bytes)
    {
        $this->writeBuffer .= $bytes;
        foreach ($this->filters as $filter) {
            if ($filter->shouldBuffer($this->writeBuffer)) {
                return;
            }
        }
        $this->doWrite($this->writeBuffer);

        return ++$this->sequence;
    }

    /**
     * For any bytes that are currently buffered inside the stream, force them
     * off the buffer.
     *
     * @throws Swift_IoException
     */
    public function commit()
    {
        $this->doWrite($this->writeBuffer);
    }

    /**
     * Attach $is to this stream.
     *
     * The stream acts as an observer, receiving all data that is written.
     * All {@link write()} and {@link flushBuffers()} operations will be mirrored.
     */
    public function bind(Swift_InputByteStream $is)
    {
        $this->mirrors[] = $is;
    }

    /**
     * Remove an already bound stream.
     *
     * If $is is not bound, no errors will be raised.
     * If the stream currently has any buffered data it will be written to $is
     * before unbinding occurs.
     */
    public function unbind(Swift_InputByteStream $is)
    {
        foreach ($this->mirrors as $k => $stream) {
            if ($is === $stream) {
                if ('' !== $this->writeBuffer) {
                    $stream->write($this->writeBuffer);
                }
                unset($this->mirrors[$k]);
            }
        }
    }

    /**
     * Flush the contents of the stream (empty it) and set the internal pointer
     * to the beginning.
     *
     * @throws Swift_IoException
     */
    public function flushBuffers()
    {
        if ('' !== $this->writeBuffer) {
            $this->doWrite($this->writeBuffer);
        }
        $this->flush();

        foreach ($this->mirrors as $stream) {
            $stream->flushBuffers();
        }
    }

    /** Run $bytes through all filters */
    private function filter($bytes)
    {
        foreach ($this->filters as $filter) {
            $bytes = $filter->filter($bytes);
        }

        return $bytes;
    }

    /** Just write the bytes to the stream */
    private function doWrite($bytes)
    {
        $this->doCommit($this->filter($bytes));

        foreach ($this->mirrors as $stream) {
            $stream->write($bytes);
        }

        $this->writeBuffer = '';
    }
}


================================================
FILE: lib/classes/Swift/ByteStream/ArrayByteStream.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Allows reading and writing of bytes to and from an array.
 *
 * @author     Chris Corbyn
 */
class Swift_ByteStream_ArrayByteStream implements Swift_InputByteStream, Swift_OutputByteStream
{
    /**
     * The internal stack of bytes.
     *
     * @var string[]
     */
    private $array = [];

    /**
     * The size of the stack.
     *
     * @var int
     */
    private $arraySize = 0;

    /**
     * The internal pointer offset.
     *
     * @var int
     */
    private $offset = 0;

    /**
     * Bound streams.
     *
     * @var Swift_InputByteStream[]
     */
    private $mirrors = [];

    /**
     * Create a new ArrayByteStream.
     *
     * If $stack is given the stream will be populated with the bytes it contains.
     *
     * @param mixed $stack of bytes in string or array form, optional
     */
    public function __construct($stack = null)
    {
        if (\is_array($stack)) {
            $this->array = $stack;
            $this->arraySize = \count($stack);
        } elseif (\is_string($stack)) {
            $this->write($stack);
        } else {
            $this->array = [];
        }
    }

    /**
     * Reads $length bytes from the stream into a string and moves the pointer
     * through the stream by $length.
     *
     * If less bytes exist than are requested the
     * remaining bytes are given instead. If no bytes are remaining at all, boolean
     * false is returned.
     *
     * @param int $length
     *
     * @return string
     */
    public function read($length)
    {
        if ($this->offset == $this->arraySize) {
            return false;
        }

        // Don't use array slice
        $end = $length + $this->offset;
        $end = $this->arraySize < $end ? $this->arraySize : $end;
        $ret = '';
        for (; $this->offset < $end; ++$this->offset) {
            $ret .= $this->array[$this->offset];
        }

        return $ret;
    }

    /**
     * Writes $bytes to the end of the stream.
     *
     * @param string $bytes
     */
    public function write($bytes)
    {
        $to_add = str_split($bytes);
        foreach ($to_add as $value) {
            $this->array[] = $value;
        }
        $this->arraySize = \count($this->array);

        foreach ($this->mirrors as $stream) {
            $stream->write($bytes);
        }
    }

    /**
     * Not used.
     */
    public function commit()
    {
    }

    /**
     * Attach $is to this stream.
     *
     * The stream acts as an observer, receiving all data that is written.
     * All {@link write()} and {@link flushBuffers()} operations will be mirrored.
     */
    public function bind(Swift_InputByteStream $is)
    {
        $this->mirrors[] = $is;
    }

    /**
     * Remove an already bound stream.
     *
     * If $is is not bound, no errors will be raised.
     * If the stream currently has any buffered data it will be written to $is
     * before unbinding occurs.
     */
    public function unbind(Swift_InputByteStream $is)
    {
        foreach ($this->mirrors as $k => $stream) {
            if ($is === $stream) {
                unset($this->mirrors[$k]);
            }
        }
    }

    /**
     * Move the internal read pointer to $byteOffset in the stream.
     *
     * @param int $byteOffset
     *
     * @return bool
     */
    public function setReadPointer($byteOffset)
    {
        if ($byteOffset > $this->arraySize) {
            $byteOffset = $this->arraySize;
        } elseif ($byteOffset < 0) {
            $byteOffset = 0;
        }

        $this->offset = $byteOffset;
    }

    /**
     * Flush the contents of the stream (empty it) and set the internal pointer
     * to the beginning.
     */
    public function flushBuffers()
    {
        $this->offset = 0;
        $this->array = [];
        $this->arraySize = 0;

        foreach ($this->mirrors as $stream) {
            $stream->flushBuffers();
        }
    }
}


================================================
FILE: lib/classes/Swift/ByteStream/FileByteStream.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Allows reading and writing of bytes to and from a file.
 *
 * @author     Chris Corbyn
 */
class Swift_ByteStream_FileByteStream extends Swift_ByteStream_AbstractFilterableInputStream implements Swift_FileStream
{
    /** The internal pointer offset */
    private $offset = 0;

    /** The path to the file */
    private $path;

    /** The mode this file is opened in for writing */
    private $mode;

    /** A lazy-loaded resource handle for reading the file */
    private $reader;

    /** A lazy-loaded resource handle for writing the file */
    private $writer;

    /** If stream is seekable true/false, or null if not known */
    private $seekable = null;

    /**
     * Create a new FileByteStream for $path.
     *
     * @param string $path
     * @param bool   $writable if true
     */
    public function __construct($path, $writable = false)
    {
        if (empty($path)) {
            throw new Swift_IoException('The path cannot be empty');
        }
        $this->path = $path;
        $this->mode = $writable ? 'w+b' : 'rb';
    }

    /**
     * Get the complete path to the file.
     *
     * @return string
     */
    public function getPath()
    {
        return $this->path;
    }

    /**
     * Reads $length bytes from the stream into a string and moves the pointer
     * through the stream by $length.
     *
     * If less bytes exist than are requested the
     * remaining bytes are given instead. If no bytes are remaining at all, boolean
     * false is returned.
     *
     * @param int $length
     *
     * @return string|bool
     *
     * @throws Swift_IoException
     */
    public function read($length)
    {
        $fp = $this->getReadHandle();
        if (!feof($fp)) {
            $bytes = fread($fp, $length);
            $this->offset = ftell($fp);

            // If we read one byte after reaching the end of the file
            // feof() will return false and an empty string is returned
            if ((false === $bytes || '' === $bytes) && feof($fp)) {
                $this->resetReadHandle();

                return false;
            }

            return $bytes;
        }

        $this->resetReadHandle();

        return false;
    }

    /**
     * Move the internal read pointer to $byteOffset in the stream.
     *
     * @param int $byteOffset
     *
     * @return bool
     */
    public function setReadPointer($byteOffset)
    {
        if (isset($this->reader)) {
            $this->seekReadStreamToPosition($byteOffset);
        }
        $this->offset = $byteOffset;
    }

    /** Just write the bytes to the file */
    protected function doCommit($bytes)
    {
        fwrite($this->getWriteHandle(), $bytes);
        $this->resetReadHandle();
    }

    /** Not used */
    protected function flush()
    {
    }

    /** Get the resource for reading */
    private function getReadHandle()
    {
        if (!isset($this->reader)) {
            $pointer = @fopen($this->path, 'rb');
            if (!$pointer) {
                throw new Swift_IoException('Unable to open file for reading ['.$this->path.']');
            }
            $this->reader = $pointer;
            if (0 != $this->offset) {
                $this->getReadStreamSeekableStatus();
                $this->seekReadStreamToPosition($this->offset);
            }
        }

        return $this->reader;
    }

    /** Get the resource for writing */
    private function getWriteHandle()
    {
        if (!isset($this->writer)) {
            if (!$this->writer = fopen($this->path, $this->mode)) {
                throw new Swift_IoException('Unable to open file for writing ['.$this->path.']');
            }
        }

        return $this->writer;
    }

    /** Force a reload of the resource for reading */
    private function resetReadHandle()
    {
        if (isset($this->reader)) {
            fclose($this->reader);
            $this->reader = null;
        }
    }

    /** Check if ReadOnly Stream is seekable */
    private function getReadStreamSeekableStatus()
    {
        $metas = stream_get_meta_data($this->reader);
        $this->seekable = $metas['seekable'];
    }

    /** Streams in a readOnly stream ensuring copy if needed */
    private function seekReadStreamToPosition($offset)
    {
        if (null === $this->seekable) {
            $this->getReadStreamSeekableStatus();
        }
        if (false === $this->seekable) {
            $currentPos = ftell($this->reader);
            if ($currentPos < $offset) {
                $toDiscard = $offset - $currentPos;
                fread($this->reader, $toDiscard);

                return;
            }
            $this->copyReadStream();
        }
        fseek($this->reader, $offset, SEEK_SET);
    }

    /** Copy a readOnly Stream to ensure seekability */
    private function copyReadStream()
    {
        if ($tmpFile = fopen('php://temp/maxmemory:4096', 'w+b')) {
            /* We have opened a php:// Stream Should work without problem */
        } elseif (\function_exists('sys_get_temp_dir') && is_writable(sys_get_temp_dir()) && ($tmpFile = tmpfile())) {
            /* We have opened a tmpfile */
        } else {
            throw new Swift_IoException('Unable to copy the file to make it seekable, sys_temp_dir is not writable, php://memory not available');
        }
        $currentPos = ftell($this->reader);
        fclose($this->reader);
        $source = fopen($this->path, 'rb');
        if (!$source) {
            throw new Swift_IoException('Unable to open file for copying ['.$this->path.']');
        }
        fseek($tmpFile, 0, SEEK_SET);
        while (!feof($source)) {
            fwrite($tmpFile, fread($source, 4096));
        }
        fseek($tmpFile, $currentPos, SEEK_SET);
        fclose($source);
        $this->reader = $tmpFile;
    }
}


================================================
FILE: lib/classes/Swift/ByteStream/TemporaryFileByteStream.php
================================================
<?php

/*
* This file is part of SwiftMailer.
* (c) 2004-2009 Chris Corbyn
*
* For the full copyright and license information, please view the LICENSE
* file that was distributed with this source code.
*/

/**
 * @author Romain-Geissler
 */
class Swift_ByteStream_TemporaryFileByteStream extends Swift_ByteStream_FileByteStream
{
    public function __construct()
    {
        $filePath = tempnam(sys_get_temp_dir(), 'FileByteStream');

        if (false === $filePath) {
            throw new Swift_IoException('Failed to retrieve temporary file name.');
        }

        parent::__construct($filePath, true);
    }

    public function getContent()
    {
        if (false === ($content = file_get_contents($this->getPath()))) {
            throw new Swift_IoException('Failed to get temporary file content.');
        }

        return $content;
    }

    public function __destruct()
    {
        if (file_exists($this->getPath())) {
            @unlink($this->getPath());
        }
    }

    public function __sleep()
    {
        throw new \BadMethodCallException('Cannot serialize '.__CLASS__);
    }

    public function __wakeup()
    {
        throw new \BadMethodCallException('Cannot unserialize '.__CLASS__);
    }
}


================================================
FILE: lib/classes/Swift/CharacterReader/GenericFixedWidthReader.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Provides fixed-width byte sizes for reading fixed-width character sets.
 *
 * @author     Chris Corbyn
 * @author     Xavier De Cock <xdecock@gmail.com>
 */
class Swift_CharacterReader_GenericFixedWidthReader implements Swift_CharacterReader
{
    /**
     * The number of bytes in a single character.
     *
     * @var int
     */
    private $width;

    /**
     * Creates a new GenericFixedWidthReader using $width bytes per character.
     *
     * @param int $width
     */
    public function __construct($width)
    {
        $this->width = $width;
    }

    /**
     * Returns the complete character map.
     *
     * @param string $string
     * @param int    $startOffset
     * @param array  $currentMap
     * @param mixed  $ignoredChars
     *
     * @return int
     */
    public function getCharPositions($string, $startOffset, &$currentMap, &$ignoredChars)
    {
        $strlen = \strlen($string);
        // % and / are CPU intensive, so, maybe find a better way
        $ignored = $strlen % $this->width;
        $ignoredChars = $ignored ? substr($string, -$ignored) : '';
        $currentMap = $this->width;

        return ($strlen - $ignored) / $this->width;
    }

    /**
     * Returns the mapType.
     *
     * @return int
     */
    public function getMapType()
    {
        return self::MAP_TYPE_FIXED_LEN;
    }

    /**
     * Returns an integer which specifies how many more bytes to read.
     *
     * A positive integer indicates the number of more bytes to fetch before invoking
     * this method again.
     *
     * A value of zero means this is already a valid character.
     * A value of -1 means this cannot possibly be a valid character.
     *
     * @param string $bytes
     * @param int    $size
     *
     * @return int
     */
    public function validateByteSequence($bytes, $size)
    {
        $needed = $this->width - $size;

        return $needed > -1 ? $needed : -1;
    }

    /**
     * Returns the number of bytes which should be read to start each character.
     *
     * @return int
     */
    public function getInitialByteSize()
    {
        return $this->width;
    }
}


================================================
FILE: lib/classes/Swift/CharacterReader/UsAsciiReader.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Analyzes US-ASCII characters.
 *
 * @author Chris Corbyn
 */
class Swift_CharacterReader_UsAsciiReader implements Swift_CharacterReader
{
    /**
     * Returns the complete character map.
     *
     * @param string $string
     * @param int    $startOffset
     * @param array  $currentMap
     * @param string $ignoredChars
     *
     * @return int
     */
    public function getCharPositions($string, $startOffset, &$currentMap, &$ignoredChars)
    {
        $strlen = \strlen($string);
        $ignoredChars = '';
        for ($i = 0; $i < $strlen; ++$i) {
            if ($string[$i] > "\x07F") {
                // Invalid char
                $currentMap[$i + $startOffset] = $string[$i];
            }
        }

        return $strlen;
    }

    /**
     * Returns mapType.
     *
     * @return int mapType
     */
    public function getMapType()
    {
        return self::MAP_TYPE_INVALID;
    }

    /**
     * Returns an integer which specifies how many more bytes to read.
     *
     * A positive integer indicates the number of more bytes to fetch before invoking
     * this method again.
     * A value of zero means this is already a valid character.
     * A value of -1 means this cannot possibly be a valid character.
     *
     * @param string $bytes
     * @param int    $size
     *
     * @return int
     */
    public function validateByteSequence($bytes, $size)
    {
        $byte = reset($bytes);
        if (1 == \count($bytes) && $byte >= 0x00 && $byte <= 0x7F) {
            return 0;
        }

        return -1;
    }

    /**
     * Returns the number of bytes which should be read to start each character.
     *
     * @return int
     */
    public function getInitialByteSize()
    {
        return 1;
    }
}


================================================
FILE: lib/classes/Swift/CharacterReader/Utf8Reader.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Analyzes UTF-8 characters.
 *
 * @author Chris Corbyn
 * @author Xavier De Cock <xdecock@gmail.com>
 */
class Swift_CharacterReader_Utf8Reader implements Swift_CharacterReader
{
    /** Pre-computed for optimization */
    private static $length_map = [
        // N=0,1,2,3,4,5,6,7,8,9,A,B,C,D,E,F
        1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, // 0x0N
        1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, // 0x1N
        1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, // 0x2N
        1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, // 0x3N
        1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, // 0x4N
        1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, // 0x5N
        1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, // 0x6N
        1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, // 0x7N
        0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, // 0x8N
        0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, // 0x9N
        0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, // 0xAN
        0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, // 0xBN
        2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, // 0xCN
        2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, // 0xDN
        3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, // 0xEN
        4, 4, 4, 4, 4, 4, 4, 4, 5, 5, 5, 5, 6, 6, 0, 0, // 0xFN
    ];

    private static $s_length_map = [
        "\x00" => 1, "\x01" => 1, "\x02" => 1, "\x03" => 1, "\x04" => 1, "\x05" => 1, "\x06" => 1, "\x07" => 1,
        "\x08" => 1, "\x09" => 1, "\x0a" => 1, "\x0b" => 1, "\x0c" => 1, "\x0d" => 1, "\x0e" => 1, "\x0f" => 1,
        "\x10" => 1, "\x11" => 1, "\x12" => 1, "\x13" => 1, "\x14" => 1, "\x15" => 1, "\x16" => 1, "\x17" => 1,
        "\x18" => 1, "\x19" => 1, "\x1a" => 1, "\x1b" => 1, "\x1c" => 1, "\x1d" => 1, "\x1e" => 1, "\x1f" => 1,
        "\x20" => 1, "\x21" => 1, "\x22" => 1, "\x23" => 1, "\x24" => 1, "\x25" => 1, "\x26" => 1, "\x27" => 1,
        "\x28" => 1, "\x29" => 1, "\x2a" => 1, "\x2b" => 1, "\x2c" => 1, "\x2d" => 1, "\x2e" => 1, "\x2f" => 1,
        "\x30" => 1, "\x31" => 1, "\x32" => 1, "\x33" => 1, "\x34" => 1, "\x35" => 1, "\x36" => 1, "\x37" => 1,
        "\x38" => 1, "\x39" => 1, "\x3a" => 1, "\x3b" => 1, "\x3c" => 1, "\x3d" => 1, "\x3e" => 1, "\x3f" => 1,
        "\x40" => 1, "\x41" => 1, "\x42" => 1, "\x43" => 1, "\x44" => 1, "\x45" => 1, "\x46" => 1, "\x47" => 1,
        "\x48" => 1, "\x49" => 1, "\x4a" => 1, "\x4b" => 1, "\x4c" => 1, "\x4d" => 1, "\x4e" => 1, "\x4f" => 1,
        "\x50" => 1, "\x51" => 1, "\x52" => 1, "\x53" => 1, "\x54" => 1, "\x55" => 1, "\x56" => 1, "\x57" => 1,
        "\x58" => 1, "\x59" => 1, "\x5a" => 1, "\x5b" => 1, "\x5c" => 1, "\x5d" => 1, "\x5e" => 1, "\x5f" => 1,
        "\x60" => 1, "\x61" => 1, "\x62" => 1, "\x63" => 1, "\x64" => 1, "\x65" => 1, "\x66" => 1, "\x67" => 1,
        "\x68" => 1, "\x69" => 1, "\x6a" => 1, "\x6b" => 1, "\x6c" => 1, "\x6d" => 1, "\x6e" => 1, "\x6f" => 1,
        "\x70" => 1, "\x71" => 1, "\x72" => 1, "\x73" => 1, "\x74" => 1, "\x75" => 1, "\x76" => 1, "\x77" => 1,
        "\x78" => 1, "\x79" => 1, "\x7a" => 1, "\x7b" => 1, "\x7c" => 1, "\x7d" => 1, "\x7e" => 1, "\x7f" => 1,
        "\x80" => 0, "\x81" => 0, "\x82" => 0, "\x83" => 0, "\x84" => 0, "\x85" => 0, "\x86" => 0, "\x87" => 0,
        "\x88" => 0, "\x89" => 0, "\x8a" => 0, "\x8b" => 0, "\x8c" => 0, "\x8d" => 0, "\x8e" => 0, "\x8f" => 0,
        "\x90" => 0, "\x91" => 0, "\x92" => 0, "\x93" => 0, "\x94" => 0, "\x95" => 0, "\x96" => 0, "\x97" => 0,
        "\x98" => 0, "\x99" => 0, "\x9a" => 0, "\x9b" => 0, "\x9c" => 0, "\x9d" => 0, "\x9e" => 0, "\x9f" => 0,
        "\xa0" => 0, "\xa1" => 0, "\xa2" => 0, "\xa3" => 0, "\xa4" => 0, "\xa5" => 0, "\xa6" => 0, "\xa7" => 0,
        "\xa8" => 0, "\xa9" => 0, "\xaa" => 0, "\xab" => 0, "\xac" => 0, "\xad" => 0, "\xae" => 0, "\xaf" => 0,
        "\xb0" => 0, "\xb1" => 0, "\xb2" => 0, "\xb3" => 0, "\xb4" => 0, "\xb5" => 0, "\xb6" => 0, "\xb7" => 0,
        "\xb8" => 0, "\xb9" => 0, "\xba" => 0, "\xbb" => 0, "\xbc" => 0, "\xbd" => 0, "\xbe" => 0, "\xbf" => 0,
        "\xc0" => 2, "\xc1" => 2, "\xc2" => 2, "\xc3" => 2, "\xc4" => 2, "\xc5" => 2, "\xc6" => 2, "\xc7" => 2,
        "\xc8" => 2, "\xc9" => 2, "\xca" => 2, "\xcb" => 2, "\xcc" => 2, "\xcd" => 2, "\xce" => 2, "\xcf" => 2,
        "\xd0" => 2, "\xd1" => 2, "\xd2" => 2, "\xd3" => 2, "\xd4" => 2, "\xd5" => 2, "\xd6" => 2, "\xd7" => 2,
        "\xd8" => 2, "\xd9" => 2, "\xda" => 2, "\xdb" => 2, "\xdc" => 2, "\xdd" => 2, "\xde" => 2, "\xdf" => 2,
        "\xe0" => 3, "\xe1" => 3, "\xe2" => 3, "\xe3" => 3, "\xe4" => 3, "\xe5" => 3, "\xe6" => 3, "\xe7" => 3,
        "\xe8" => 3, "\xe9" => 3, "\xea" => 3, "\xeb" => 3, "\xec" => 3, "\xed" => 3, "\xee" => 3, "\xef" => 3,
        "\xf0" => 4, "\xf1" => 4, "\xf2" => 4, "\xf3" => 4, "\xf4" => 4, "\xf5" => 4, "\xf6" => 4, "\xf7" => 4,
        "\xf8" => 5, "\xf9" => 5, "\xfa" => 5, "\xfb" => 5, "\xfc" => 6, "\xfd" => 6, "\xfe" => 0, "\xff" => 0,
     ];

    /**
     * Returns the complete character map.
     *
     * @param string $string
     * @param int    $startOffset
     * @param array  $currentMap
     * @param mixed  $ignoredChars
     *
     * @return int
     */
    public function getCharPositions($string, $startOffset, &$currentMap, &$ignoredChars)
    {
        if (!isset($currentMap['i']) || !isset($currentMap['p'])) {
            $currentMap['p'] = $currentMap['i'] = [];
        }

        $strlen = \strlen($string);
        $charPos = \count($currentMap['p']);
        $foundChars = 0;
        $invalid = false;
        for ($i = 0; $i < $strlen; ++$i) {
            $char = $string[$i];
            $size = self::$s_length_map[$char];
            if (0 == $size) {
                /* char is invalid, we must wait for a resync */
                $invalid = true;
                continue;
            } else {
                if (true === $invalid) {
                    /* We mark the chars as invalid and start a new char */
                    $currentMap['p'][$charPos + $foundChars] = $startOffset + $i;
                    $currentMap['i'][$charPos + $foundChars] = true;
                    ++$foundChars;
                    $invalid = false;
                }
                if (($i + $size) > $strlen) {
                    $ignoredChars = substr($string, $i);
                    break;
                }
                for ($j = 1; $j < $size; ++$j) {
                    $char = $string[$i + $j];
                    if ($char > "\x7F" && $char < "\xC0") {
                        // Valid - continue parsing
                    } else {
                        /* char is invalid, we must wait for a resync */
                        $invalid = true;
                        continue 2;
                    }
                }
                /* Ok we got a complete char here */
                $currentMap['p'][$charPos + $foundChars] = $startOffset + $i + $size;
                $i += $j - 1;
                ++$foundChars;
            }
        }

        return $foundChars;
    }

    /**
     * Returns mapType.
     *
     * @return int mapType
     */
    public function getMapType()
    {
        return self::MAP_TYPE_POSITIONS;
    }

    /**
     * Returns an integer which specifies how many more bytes to read.
     *
     * A positive integer indicates the number of more bytes to fetch before invoking
     * this method again.
     * A value of zero means this is already a valid character.
     * A value of -1 means this cannot possibly be a valid character.
     *
     * @param string $bytes
     * @param int    $size
     *
     * @return int
     */
    public function validateByteSequence($bytes, $size)
    {
        if ($size < 1) {
            return -1;
        }
        $needed = self::$length_map[$bytes[0]] - $size;

        return $needed > -1 ? $needed : -1;
    }

    /**
     * Returns the number of bytes which should be read to start each character.
     *
     * @return int
     */
    public function getInitialByteSize()
    {
        return 1;
    }
}


================================================
FILE: lib/classes/Swift/CharacterReader.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Analyzes characters for a specific character set.
 *
 * @author Chris Corbyn
 * @author Xavier De Cock <xdecock@gmail.com>
 */
interface Swift_CharacterReader
{
    const MAP_TYPE_INVALID = 0x01;
    const MAP_TYPE_FIXED_LEN = 0x02;
    const MAP_TYPE_POSITIONS = 0x03;

    /**
     * Returns the complete character map.
     *
     * @param string $string
     * @param int    $startOffset
     * @param array  $currentMap
     * @param mixed  $ignoredChars
     *
     * @return int
     */
    public function getCharPositions($string, $startOffset, &$currentMap, &$ignoredChars);

    /**
     * Returns the mapType, see constants.
     *
     * @return int
     */
    public function getMapType();

    /**
     * Returns an integer which specifies how many more bytes to read.
     *
     * A positive integer indicates the number of more bytes to fetch before invoking
     * this method again.
     *
     * A value of zero means this is already a valid character.
     * A value of -1 means this cannot possibly be a valid character.
     *
     * @param int[] $bytes
     * @param int   $size
     *
     * @return int
     */
    public function validateByteSequence($bytes, $size);

    /**
     * Returns the number of bytes which should be read to start each character.
     *
     * For fixed width character sets this should be the number of octets-per-character.
     * For multibyte character sets this will probably be 1.
     *
     * @return int
     */
    public function getInitialByteSize();
}


================================================
FILE: lib/classes/Swift/CharacterReaderFactory/SimpleCharacterReaderFactory.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Standard factory for creating CharacterReaders.
 *
 * @author Chris Corbyn
 */
class Swift_CharacterReaderFactory_SimpleCharacterReaderFactory implements Swift_CharacterReaderFactory
{
    /**
     * A map of charset patterns to their implementation classes.
     *
     * @var array
     */
    private static $map = [];

    /**
     * Factories which have already been loaded.
     *
     * @var Swift_CharacterReaderFactory[]
     */
    private static $loaded = [];

    /**
     * Creates a new CharacterReaderFactory.
     */
    public function __construct()
    {
        $this->init();
    }

    public function __wakeup()
    {
        $this->init();
    }

    public function init()
    {
        if (\count(self::$map) > 0) {
            return;
        }

        $prefix = 'Swift_CharacterReader_';

        $singleByte = [
            'class' => $prefix.'GenericFixedWidthReader',
            'constructor' => [1],
            ];

        $doubleByte = [
            'class' => $prefix.'GenericFixedWidthReader',
            'constructor' => [2],
            ];

        $fourBytes = [
            'class' => $prefix.'GenericFixedWidthReader',
            'constructor' => [4],
            ];

        // Utf-8
        self::$map['utf-?8'] = [
            'class' => $prefix.'Utf8Reader',
            'constructor' => [],
            ];

        //7-8 bit charsets
        self::$map['(us-)?ascii'] = $singleByte;
        self::$map['(iso|iec)-?8859-?[0-9]+'] = $singleByte;
        self::$map['windows-?125[0-9]'] = $singleByte;
        self::$map['cp-?[0-9]+'] = $singleByte;
        self::$map['ansi'] = $singleByte;
        self::$map['macintosh'] = $singleByte;
        self::$map['koi-?7'] = $singleByte;
        self::$map['koi-?8-?.+'] = $singleByte;
        self::$map['mik'] = $singleByte;
        self::$map['(cork|t1)'] = $singleByte;
        self::$map['v?iscii'] = $singleByte;

        //16 bits
        self::$map['(ucs-?2|utf-?16)'] = $doubleByte;

        //32 bits
        self::$map['(ucs-?4|utf-?32)'] = $fourBytes;

        // Fallback
        self::$map['.*'] = $singleByte;
    }

    /**
     * Returns a CharacterReader suitable for the charset applied.
     *
     * @param string $charset
     *
     * @return Swift_CharacterReader
     */
    public function getReaderFor($charset)
    {
        $charset = strtolower(trim($charset ?? ''));
        foreach (self::$map as $pattern => $spec) {
            $re = '/^'.$pattern.'$/D';
            if (preg_match($re, $charset)) {
                if (!\array_key_exists($pattern, self::$loaded)) {
                    $reflector = new ReflectionClass($spec['class']);
                    if ($reflector->getConstructor()) {
                        $reader = $reflector->newInstanceArgs($spec['constructor']);
                    } else {
                        $reader = $reflector->newInstance();
                    }
                    self::$loaded[$pattern] = $reader;
                }

                return self::$loaded[$pattern];
            }
        }
    }
}


================================================
FILE: lib/classes/Swift/CharacterReaderFactory.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * A factory for creating CharacterReaders.
 *
 * @author Chris Corbyn
 */
interface Swift_CharacterReaderFactory
{
    /**
     * Returns a CharacterReader suitable for the charset applied.
     *
     * @param string $charset
     *
     * @return Swift_CharacterReader
     */
    public function getReaderFor($charset);
}


================================================
FILE: lib/classes/Swift/CharacterStream/ArrayCharacterStream.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * A CharacterStream implementation which stores characters in an internal array.
 *
 * @author Chris Corbyn
 */
class Swift_CharacterStream_ArrayCharacterStream implements Swift_CharacterStream
{
    /** A map of byte values and their respective characters */
    private static $charMap;

    /** A map of characters and their derivative byte values */
    private static $byteMap;

    /** The char reader (lazy-loaded) for the current charset */
    private $charReader;

    /** A factory for creating CharacterReader instances */
    private $charReaderFactory;

    /** The character set this stream is using */
    private $charset;

    /** Array of characters */
    private $array = [];

    /** Size of the array of character */
    private $array_size = [];

    /** The current character offset in the stream */
    private $offset = 0;

    /**
     * Create a new CharacterStream with the given $chars, if set.
     *
     * @param Swift_CharacterReaderFactory $factory for loading validators
     * @param string                       $charset used in the stream
     */
    public function __construct(Swift_CharacterReaderFactory $factory, $charset)
    {
        self::initializeMaps();
        $this->setCharacterReaderFactory($factory);
        $this->setCharacterSet($charset);
    }

    /**
     * Set the character set used in this CharacterStream.
     *
     * @param string $charset
     */
    public function setCharacterSet($charset)
    {
        $this->charset = $charset;
        $this->charReader = null;
    }

    /**
     * Set the CharacterReaderFactory for multi charset support.
     */
    public function setCharacterReaderFactory(Swift_CharacterReaderFactory $factory)
    {
        $this->charReaderFactory = $factory;
    }

    /**
     * Overwrite this character stream using the byte sequence in the byte stream.
     *
     * @param Swift_OutputByteStream $os output stream to read from
     */
    public function importByteStream(Swift_OutputByteStream $os)
    {
        if (!isset($this->charReader)) {
            $this->charReader = $this->charReaderFactory
                ->getReaderFor($this->charset);
        }

        $startLength = $this->charReader->getInitialByteSize();
        while (false !== $bytes = $os->read($startLength)) {
            $c = [];
            for ($i = 0, $len = \strlen($bytes); $i < $len; ++$i) {
                $c[] = self::$byteMap[$bytes[$i]];
            }
            $size = \count($c);
            $need = $this->charReader
                ->validateByteSequence($c, $size);
            if ($need > 0 &&
                false !== $bytes = $os->read($need)) {
                for ($i = 0, $len = \strlen($bytes); $i < $len; ++$i) {
                    $c[] = self::$byteMap[$bytes[$i]];
                }
            }
            $this->array[] = $c;
            ++$this->array_size;
        }
    }

    /**
     * Import a string a bytes into this CharacterStream, overwriting any existing
     * data in the stream.
     *
     * @param string $string
     */
    public function importString($string)
    {
        $this->flushContents();
        $this->write($string);
    }

    /**
     * Read $length characters from the stream and move the internal pointer
     * $length further into the stream.
     *
     * @param int $length
     *
     * @return string
     */
    public function read($length)
    {
        if ($this->offset == $this->array_size) {
            return false;
        }

        // Don't use array slice
        $arrays = [];
        $end = $length + $this->offset;
        for ($i = $this->offset; $i < $end; ++$i) {
            if (!isset($this->array[$i])) {
                break;
            }
            $arrays[] = $this->array[$i];
        }
        $this->offset += $i - $this->offset; // Limit function calls
        $chars = false;
        foreach ($arrays as $array) {
            $chars .= implode('', array_map('chr', $array));
        }

        return $chars;
    }

    /**
     * Read $length characters from the stream and return a 1-dimensional array
     * containing there octet values.
     *
     * @param int $length
     *
     * @return int[]
     */
    public function readBytes($length)
    {
        if ($this->offset == $this->array_size) {
            return false;
        }
        $arrays = [];
        $end = $length + $this->offset;
        for ($i = $this->offset; $i < $end; ++$i) {
            if (!isset($this->array[$i])) {
                break;
            }
            $arrays[] = $this->array[$i];
        }
        $this->offset += ($i - $this->offset); // Limit function calls

        return array_merge(...$arrays);
    }

    /**
     * Write $chars to the end of the stream.
     *
     * @param string $chars
     */
    public function write($chars)
    {
        if (!isset($this->charReader)) {
            $this->charReader = $this->charReaderFactory->getReaderFor(
                $this->charset);
        }

        $startLength = $this->charReader->getInitialByteSize();

        $fp = fopen('php://memory', 'w+b');
        fwrite($fp, $chars);
        unset($chars);
        fseek($fp, 0, SEEK_SET);

        $buffer = [0];
        $buf_pos = 1;
        $buf_len = 1;
        $has_datas = true;
        do {
            $bytes = [];
            // Buffer Filing
            if ($buf_len - $buf_pos < $startLength) {
                $buf = array_splice($buffer, $buf_pos);
                $new = $this->reloadBuffer($fp, 100);
                if ($new) {
                    $buffer = array_merge($buf, $new);
                    $buf_len = \count($buffer);
                    $buf_pos = 0;
                } else {
                    $has_datas = false;
                }
            }
            if ($buf_len - $buf_pos > 0) {
                $size = 0;
                for ($i = 0; $i < $startLength && isset($buffer[$buf_pos]); ++$i) {
                    ++$size;
                    $bytes[] = $buffer[$buf_pos++];
                }
                $need = $this->charReader->validateByteSequence(
                    $bytes, $size);
                if ($need > 0) {
                    if ($buf_len - $buf_pos < $need) {
                        $new = $this->reloadBuffer($fp, $need);

                        if ($new) {
                            $buffer = array_merge($buffer, $new);
                            $buf_len = \count($buffer);
                        }
                    }
                    for ($i = 0; $i < $need && isset($buffer[$buf_pos]); ++$i) {
                        $bytes[] = $buffer[$buf_pos++];
                    }
                }
                $this->array[] = $bytes;
                ++$this->array_size;
            }
        } while ($has_datas);

        fclose($fp);
    }

    /**
     * Move the internal pointer to $charOffset in the stream.
     *
     * @param int $charOffset
     */
    public function setPointer($charOffset)
    {
        if ($charOffset > $this->array_size) {
            $charOffset = $this->array_size;
        } elseif ($charOffset < 0) {
            $charOffset = 0;
        }
        $this->offset = $charOffset;
    }

    /**
     * Empty the stream and reset the internal pointer.
     */
    public function flushContents()
    {
        $this->offset = 0;
        $this->array = [];
        $this->array_size = 0;
    }

    private function reloadBuffer($fp, $len)
    {
        if (!feof($fp) && false !== ($bytes = fread($fp, $len))) {
            $buf = [];
            for ($i = 0, $len = \strlen($bytes); $i < $len; ++$i) {
                $buf[] = self::$byteMap[$bytes[$i]];
            }

            return $buf;
        }

        return false;
    }

    private static function initializeMaps()
    {
        if (!isset(self::$charMap)) {
            self::$charMap = [];
            for ($byte = 0; $byte < 256; ++$byte) {
                self::$charMap[$byte] = \chr($byte);
            }
            self::$byteMap = array_flip(self::$charMap);
        }
    }
}


================================================
FILE: lib/classes/Swift/CharacterStream/NgCharacterStream.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * A CharacterStream implementation which stores characters in an internal array.
 *
 * @author     Xavier De Cock <xdecock@gmail.com>
 */
class Swift_CharacterStream_NgCharacterStream implements Swift_CharacterStream
{
    /**
     * The char reader (lazy-loaded) for the current charset.
     *
     * @var Swift_CharacterReader
     */
    private $charReader;

    /**
     * A factory for creating CharacterReader instances.
     *
     * @var Swift_CharacterReaderFactory
     */
    private $charReaderFactory;

    /**
     * The character set this stream is using.
     *
     * @var string
     */
    private $charset;

    /**
     * The data's stored as-is.
     *
     * @var string
     */
    private $datas = '';

    /**
     * Number of bytes in the stream.
     *
     * @var int
     */
    private $datasSize = 0;

    /**
     * Map.
     *
     * @var mixed
     */
    private $map;

    /**
     * Map Type.
     *
     * @var int
     */
    private $mapType = 0;

    /**
     * Number of characters in the stream.
     *
     * @var int
     */
    private $charCount = 0;

    /**
     * Position in the stream.
     *
     * @var int
     */
    private $currentPos = 0;

    /**
     * Constructor.
     *
     * @param string $charset
     */
    public function __construct(Swift_CharacterReaderFactory $factory, $charset)
    {
        $this->setCharacterReaderFactory($factory);
        $this->setCharacterSet($charset);
    }

    /* -- Changing parameters of the stream -- */

    /**
     * Set the character set used in this CharacterStream.
     *
     * @param string $charset
     */
    public function setCharacterSet($charset)
    {
        $this->charset = $charset;
        $this->charReader = null;
        $this->mapType = 0;
    }

    /**
     * Set the CharacterReaderFactory for multi charset support.
     */
    public function setCharacterReaderFactory(Swift_CharacterReaderFactory $factory)
    {
        $this->charReaderFactory = $factory;
    }

    /**
     * @see Swift_CharacterStream::flushContents()
     */
    public function flushContents()
    {
        $this->datas = null;
        $this->map = null;
        $this->charCount = 0;
        $this->currentPos = 0;
        $this->datasSize = 0;
    }

    /**
     * @see Swift_CharacterStream::importByteStream()
     */
    public function importByteStream(Swift_OutputByteStream $os)
    {
        $this->flushContents();
        $blocks = 512;
        $os->setReadPointer(0);
        while (false !== ($read = $os->read($blocks))) {
            $this->write($read);
        }
    }

    /**
     * @see Swift_CharacterStream::importString()
     *
     * @param string $string
     */
    public function importString($string)
    {
        $this->flushContents();
        $this->write($string);
    }

    /**
     * @see Swift_CharacterStream::read()
     *
     * @param int $length
     *
     * @return string
     */
    public function read($length)
    {
        if ($this->currentPos >= $this->charCount) {
            return false;
        }
        $ret = false;
        $length = ($this->currentPos + $length > $this->charCount) ? $this->charCount - $this->currentPos : $length;
        switch ($this->mapType) {
            case Swift_CharacterReader::MAP_TYPE_FIXED_LEN:
                $len = $length * $this->map;
                $ret = substr($this->datas,
                        $this->currentPos * $this->map,
                        $len);
                $this->currentPos += $length;
                break;

            case Swift_CharacterReader::MAP_TYPE_INVALID:
                $ret = '';
                for (; $this->currentPos < $length; ++$this->currentPos) {
                    if (isset($this->map[$this->currentPos])) {
                        $ret .= '?';
                    } else {
                        $ret .= $this->datas[$this->currentPos];
                    }
                }
                break;

            case Swift_CharacterReader::MAP_TYPE_POSITIONS:
                $end = $this->currentPos + $length;
                $end = $end > $this->charCount ? $this->charCount : $end;
                $ret = '';
                $start = 0;
                if ($this->currentPos > 0) {
                    $start = $this->map['p'][$this->currentPos - 1];
                }
                $to = $start;
                for (; $this->currentPos < $end; ++$this->currentPos) {
                    if (isset($this->map['i'][$this->currentPos])) {
                        $ret .= substr($this->datas, $start, $to - $start).'?';
                        $start = $this->map['p'][$this->currentPos];
                    } else {
                        $to = $this->map['p'][$this->currentPos];
                    }
                }
                $ret .= substr($this->datas, $start, $to - $start);
                break;
        }

        return $ret;
    }

    /**
     * @see Swift_CharacterStream::readBytes()
     *
     * @param int $length
     *
     * @return int[]
     */
    public function readBytes($length)
    {
        $read = $this->read($length);
        if (false !== $read) {
            $ret = array_map('ord', str_split($read, 1));

            return $ret;
        }

        return false;
    }

    /**
     * @see Swift_CharacterStream::setPointer()
     *
     * @param int $charOffset
     */
    public function setPointer($charOffset)
    {
        if ($this->charCount < $charOffset) {
            $charOffset = $this->charCount;
        }
        $this->currentPos = $charOffset;
    }

    /**
     * @see Swift_CharacterStream::write()
     *
     * @param string $chars
     */
    public function write($chars)
    {
        if (!isset($this->charReader)) {
            $this->charReader = $this->charReaderFactory->getReaderFor(
                $this->charset);
            $this->map = [];
            $this->mapType = $this->charReader->getMapType();
        }
        $ignored = '';
        $this->datas .= $chars;
        $this->charCount += $this->charReader->getCharPositions(substr($this->datas, $this->datasSize), $this->datasSize, $this->map, $ignored);
        if (false !== $ignored) {
            $this->datasSize = \strlen($this->datas) - \strlen($ignored);
        } else {
            $this->datasSize = \strlen($this->datas);
        }
    }
}


================================================
FILE: lib/classes/Swift/CharacterStream.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * An abstract means of reading and writing data in terms of characters as opposed
 * to bytes.
 *
 * Classes implementing this interface may use a subsystem which requires less
 * memory than working with large strings of data.
 *
 * @author Chris Corbyn
 */
interface Swift_CharacterStream
{
    /**
     * Set the character set used in this CharacterStream.
     *
     * @param string $charset
     */
    public function setCharacterSet($charset);

    /**
     * Set the CharacterReaderFactory for multi charset support.
     */
    public function setCharacterReaderFactory(Swift_CharacterReaderFactory $factory);

    /**
     * Overwrite this character stream using the byte sequence in the byte stream.
     *
     * @param Swift_OutputByteStream $os output stream to read from
     */
    public function importByteStream(Swift_OutputByteStream $os);

    /**
     * Import a string a bytes into this CharacterStream, overwriting any existing
     * data in the stream.
     *
     * @param string $string
     */
    public function importString($string);

    /**
     * Read $length characters from the stream and move the internal pointer
     * $length further into the stream.
     *
     * @param int $length
     *
     * @return string
     */
    public function read($length);

    /**
     * Read $length characters from the stream and return a 1-dimensional array
     * containing there octet values.
     *
     * @param int $length
     *
     * @return int[]
     */
    public function readBytes($length);

    /**
     * Write $chars to the end of the stream.
     *
     * @param string $chars
     */
    public function write($chars);

    /**
     * Move the internal pointer to $charOffset in the stream.
     *
     * @param int $charOffset
     */
    public function setPointer($charOffset);

    /**
     * Empty the stream and reset the internal pointer.
     */
    public function flushContents();
}


================================================
FILE: lib/classes/Swift/ConfigurableSpool.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2009 Fabien Potencier <fabien.potencier@gmail.com>
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Base class for Spools (implements time and message limits).
 *
 * @author Fabien Potencier
 */
abstract class Swift_ConfigurableSpool implements Swift_Spool
{
    /** The maximum number of messages to send per flush */
    private $message_limit;

    /** The time limit per flush */
    private $time_limit;

    /**
     * Sets the maximum number of messages to send per flush.
     *
     * @param int $limit
     */
    public function setMessageLimit($limit)
    {
        $this->message_limit = (int) $limit;
    }

    /**
     * Gets the maximum number of messages to send per flush.
     *
     * @return int The limit
     */
    public function getMessageLimit()
    {
        return $this->message_limit;
    }

    /**
     * Sets the time limit (in seconds) per flush.
     *
     * @param int $limit The limit
     */
    public function setTimeLimit($limit)
    {
        $this->time_limit = (int) $limit;
    }

    /**
     * Gets the time limit (in seconds) per flush.
     *
     * @return int The limit
     */
    public function getTimeLimit()
    {
        return $this->time_limit;
    }
}


================================================
FILE: lib/classes/Swift/DependencyContainer.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Dependency Injection container.
 *
 * @author  Chris Corbyn
 */
class Swift_DependencyContainer
{
    /** Constant for literal value types */
    const TYPE_VALUE = 0x00001;

    /** Constant for new instance types */
    const TYPE_INSTANCE = 0x00010;

    /** Constant for shared instance types */
    const TYPE_SHARED = 0x00100;

    /** Constant for aliases */
    const TYPE_ALIAS = 0x01000;

    /** Constant for arrays */
    const TYPE_ARRAY = 0x10000;

    /** Singleton instance */
    private static $instance = null;

    /** The data container */
    private $store = [];

    /** The current endpoint in the data container */
    private $endPoint;

    /**
     * Constructor should not be used.
     *
     * Use {@link getInstance()} instead.
     */
    public function __construct()
    {
    }

    /**
     * Returns a singleton of the DependencyContainer.
     *
     * @return self
     */
    public static function getInstance()
    {
        if (!isset(self::$instance)) {
            self::$instance = new self();
        }

        return self::$instance;
    }

    /**
     * List the names of all items stored in the Container.
     *
     * @return array
     */
    public function listItems()
    {
        return array_keys($this->store);
    }

    /**
     * Test if an item is registered in this container with the given name.
     *
     * @see register()
     *
     * @param string $itemName
     *
     * @return bool
     */
    public function has($itemName)
    {
        return \array_key_exists($itemName, $this->store)
            && isset($this->store[$itemName]['lookupType']);
    }

    /**
     * Lookup the item with the given $itemName.
     *
     * @see register()
     *
     * @param string $itemName
     *
     * @return mixed
     *
     * @throws Swift_DependencyException If the dependency is not found
     */
    public function lookup($itemName)
    {
        if (!$this->has($itemName)) {
            throw new Swift_DependencyException('Cannot lookup dependency "'.$itemName.'" since it is not registered.');
        }

        switch ($this->store[$itemName]['lookupType']) {
            case self::TYPE_ALIAS:
                return $this->createAlias($itemName);
            case self::TYPE_VALUE:
                return $this->getValue($itemName);
            case self::TYPE_INSTANCE:
                return $this->createNewInstance($itemName);
            case self::TYPE_SHARED:
                return $this->createSharedInstance($itemName);
            case self::TYPE_ARRAY:
                return $this->createDependenciesFor($itemName);
        }
    }

    /**
     * Create an array of arguments passed to the constructor of $itemName.
     *
     * @param string $itemName
     *
     * @return array
     */
    public function createDependenciesFor($itemName)
    {
        $args = [];
        if (isset($this->store[$itemName]['args'])) {
            $args = $this->resolveArgs($this->store[$itemName]['args']);
        }

        return $args;
    }

    /**
     * Register a new dependency with $itemName.
     *
     * This method returns the current DependencyContainer instance because it
     * requires the use of the fluid interface to set the specific details for the
     * dependency.
     *
     * @see asNewInstanceOf(), asSharedInstanceOf(), asValue()
     *
     * @param string $itemName
     *
     * @return $this
     */
    public function register($itemName)
    {
        $this->store[$itemName] = [];
        $this->endPoint = &$this->store[$itemName];

        return $this;
    }

    /**
     * Specify the previously registered item as a literal value.
     *
     * {@link register()} must be called before this will work.
     *
     * @param mixed $value
     *
     * @return $this
     */
    public function asValue($value)
    {
        $endPoint = &$this->getEndPoint();
        $endPoint['lookupType'] = self::TYPE_VALUE;
        $endPoint['value'] = $value;

        return $this;
    }

    /**
     * Specify the previously registered item as an alias of another item.
     *
     * @param string $lookup
     *
     * @return $this
     */
    public function asAliasOf($lookup)
    {
        $endPoint = &$this->getEndPoint();
        $endPoint['lookupType'] = self::TYPE_ALIAS;
        $endPoint['ref'] = $lookup;

        return $this;
    }

    /**
     * Specify the previously registered item as a new instance of $className.
     *
     * {@link register()} must be called before this will work.
     * Any arguments can be set with {@link withDependencies()},
     * {@link addConstructorValue()} or {@link addConstructorLookup()}.
     *
     * @see withDependencies(), addConstructorValue(), addConstructorLookup()
     *
     * @param string $className
     *
     * @return $this
     */
    public function asNewInstanceOf($className)
    {
        $endPoint = &$this->getEndPoint();
        $endPoint['lookupType'] = self::TYPE_INSTANCE;
        $endPoint['className'] = $className;

        return $this;
    }

    /**
     * Specify the previously registered item as a shared instance of $className.
     *
     * {@link register()} must be called before this will work.
     *
     * @param string $className
     *
     * @return $this
     */
    public function asSharedInstanceOf($className)
    {
        $endPoint = &$this->getEndPoint();
        $endPoint['lookupType'] = self::TYPE_SHARED;
        $endPoint['className'] = $className;

        return $this;
    }

    /**
     * Specify the previously registered item as array of dependencies.
     *
     * {@link register()} must be called before this will work.
     *
     * @return $this
     */
    public function asArray()
    {
        $endPoint = &$this->getEndPoint();
        $endPoint['lookupType'] = self::TYPE_ARRAY;

        return $this;
    }

    /**
     * Specify a list of injected dependencies for the previously registered item.
     *
     * This method takes an array of lookup names.
     *
     * @see addConstructorValue(), addConstructorLookup()
     *
     * @return $this
     */
    public function withDependencies(array $lookups)
    {
        $endPoint = &$this->getEndPoint();
        $endPoint['args'] = [];
        foreach ($lookups as $lookup) {
            $this->addConstructorLookup($lookup);
        }

        return $this;
    }

    /**
     * Specify a literal (non looked up) value for the constructor of the
     * previously registered item.
     *
     * @see withDependencies(), addConstructorLookup()
     *
     * @param mixed $value
     *
     * @return $this
     */
    public function addConstructorValue($value)
    {
        $endPoint = &$this->getEndPoint();
        if (!isset($endPoint['args'])) {
            $endPoint['args'] = [];
        }
        $endPoint['args'][] = ['type' => 'value', 'item' => $value];

        return $this;
    }

    /**
     * Specify a dependency lookup for the constructor of the previously
     * registered item.
     *
     * @see withDependencies(), addConstructorValue()
     *
     * @param string $lookup
     *
     * @return $this
     */
    public function addConstructorLookup($lookup)
    {
        $endPoint = &$this->getEndPoint();
        if (!isset($this->endPoint['args'])) {
            $endPoint['args'] = [];
        }
        $endPoint['args'][] = ['type' => 'lookup', 'item' => $lookup];

        return $this;
    }

    /** Get the literal value with $itemName */
    private function getValue($itemName)
    {
        return $this->store[$itemName]['value'];
    }

    /** Resolve an alias to another item */
    private function createAlias($itemName)
    {
        return $this->lookup($this->store[$itemName]['ref']);
    }

    /** Create a fresh instance of $itemName */
    private function createNewInstance($itemName)
    {
        $reflector = new ReflectionClass($this->store[$itemName]['className']);
        if ($reflector->getConstructor()) {
            return $reflector->newInstanceArgs(
                $this->createDependenciesFor($itemName)
                );
        }

        return $reflector->newInstance();
    }

    /** Create and register a shared instance of $itemName */
    private function createSharedInstance($itemName)
    {
        if (!isset($this->store[$itemName]['instance'])) {
            $this->store[$itemName]['instance'] = $this->createNewInstance($itemName);
        }

        return $this->store[$itemName]['instance'];
    }

    /** Get the current endpoint in the store */
    private function &getEndPoint()
    {
        if (!isset($this->endPoint)) {
            throw new BadMethodCallException('Component must first be registered by calling register()');
        }

        return $this->endPoint;
    }

    /** Get an argument list with dependencies resolved */
    private function resolveArgs(array $args)
    {
        $resolved = [];
        foreach ($args as $argDefinition) {
            switch ($argDefinition['type']) {
                case 'lookup':
                    $resolved[] = $this->lookupRecursive($argDefinition['item']);
                    break;
                case 'value':
                    $resolved[] = $argDefinition['item'];
                    break;
            }
        }

        return $resolved;
    }

    /** Resolve a single dependency with an collections */
    private function lookupRecursive($item)
    {
        if (\is_array($item)) {
            $collection = [];
            foreach ($item as $k => $v) {
                $collection[$k] = $this->lookupRecursive($v);
            }

            return $collection;
        }

        return $this->lookup($item);
    }
}


================================================
FILE: lib/classes/Swift/DependencyException.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * DependencyException gets thrown when a requested dependency is missing.
 *
 * @author Chris Corbyn
 */
class Swift_DependencyException extends Swift_SwiftException
{
    /**
     * Create a new DependencyException with $message.
     *
     * @param string $message
     */
    public function __construct($message)
    {
        parent::__construct($message);
    }
}


================================================
FILE: lib/classes/Swift/EmbeddedFile.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * An embedded file, in a multipart message.
 *
 * @author Chris Corbyn
 */
class Swift_EmbeddedFile extends Swift_Mime_EmbeddedFile
{
    /**
     * Create a new EmbeddedFile.
     *
     * Details may be optionally provided to the constructor.
     *
     * @param string|Swift_OutputByteStream $data
     * @param string                        $filename
     * @param string                        $contentType
     */
    public function __construct($data = null, $filename = null, $contentType = null)
    {
        \call_user_func_array(
            [$this, 'Swift_Mime_EmbeddedFile::__construct'],
            Swift_DependencyContainer::getInstance()
                ->createDependenciesFor('mime.embeddedfile')
            );

        $this->setBody($data);
        $this->setFilename($filename);
        if ($contentType) {
            $this->setContentType($contentType);
        }
    }

    /**
     * Create a new EmbeddedFile from a filesystem path.
     *
     * @param string $path
     *
     * @return Swift_Mime_EmbeddedFile
     */
    public static function fromPath($path)
    {
        return (new self())->setFile(new Swift_ByteStream_FileByteStream($path));
    }
}


================================================
FILE: lib/classes/Swift/Encoder/Base64Encoder.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Handles Base 64 Encoding in Swift Mailer.
 *
 * @author Chris Corbyn
 */
class Swift_Encoder_Base64Encoder implements Swift_Encoder
{
    /**
     * Takes an unencoded string and produces a Base64 encoded string from it.
     *
     * Base64 encoded strings have a maximum line length of 76 characters.
     * If the first line needs to be shorter, indicate the difference with
     * $firstLineOffset.
     *
     * @param string $string          to encode
     * @param int    $firstLineOffset
     * @param int    $maxLineLength   optional, 0 indicates the default of 76 bytes
     *
     * @return string
     */
    public function encodeString($string, $firstLineOffset = 0, $maxLineLength = 0)
    {
        if (0 >= $maxLineLength || 76 < $maxLineLength) {
            $maxLineLength = 76;
        }

        $encodedString = base64_encode($string ?? '');
        $firstLine = '';

        if (0 != $firstLineOffset) {
            $firstLine = substr(
                $encodedString, 0, $maxLineLength - $firstLineOffset
                )."\r\n";
            $encodedString = substr(
                $encodedString, $maxLineLength - $firstLineOffset
                );
        }

        return $firstLine.trim(chunk_split($encodedString, $maxLineLength, "\r\n"));
    }

    /**
     * Does nothing.
     */
    public function charsetChanged($charset)
    {
    }
}


================================================
FILE: lib/classes/Swift/Encoder/QpEncoder.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Handles Quoted Printable (QP) Encoding in Swift Mailer.
 *
 * Possibly the most accurate RFC 2045 QP implementation found in PHP.
 *
 * @author     Chris Corbyn
 */
class Swift_Encoder_QpEncoder implements Swift_Encoder
{
    /**
     * The CharacterStream used for reading characters (as opposed to bytes).
     *
     * @var Swift_CharacterStream
     */
    protected $charStream;

    /**
     * A filter used if input should be canonicalized.
     *
     * @var Swift_StreamFilter
     */
    protected $filter;

    /**
     * Pre-computed QP for HUGE optimization.
     *
     * @var string[]
     */
    protected static $qpMap = [
        0 => '=00', 1 => '=01', 2 => '=02', 3 => '=03', 4 => '=04',
        5 => '=05', 6 => '=06', 7 => '=07', 8 => '=08', 9 => '=09',
        10 => '=0A', 11 => '=0B', 12 => '=0C', 13 => '=0D', 14 => '=0E',
        15 => '=0F', 16 => '=10', 17 => '=11', 18 => '=12', 19 => '=13',
        20 => '=14', 21 => '=15', 22 => '=16', 23 => '=17', 24 => '=18',
        25 => '=19', 26 => '=1A', 27 => '=1B', 28 => '=1C', 29 => '=1D',
        30 => '=1E', 31 => '=1F', 32 => '=20', 33 => '=21', 34 => '=22',
        35 => '=23', 36 => '=24', 37 => '=25', 38 => '=26', 39 => '=27',
        40 => '=28', 41 => '=29', 42 => '=2A', 43 => '=2B', 44 => '=2C',
        45 => '=2D', 46 => '=2E', 47 => '=2F', 48 => '=30', 49 => '=31',
        50 => '=32', 51 => '=33', 52 => '=34', 53 => '=35', 54 => '=36',
        55 => '=37', 56 => '=38', 57 => '=39', 58 => '=3A', 59 => '=3B',
        60 => '=3C', 61 => '=3D', 62 => '=3E', 63 => '=3F', 64 => '=40',
        65 => '=41', 66 => '=42', 67 => '=43', 68 => '=44', 69 => '=45',
        70 => '=46', 71 => '=47', 72 => '=48', 73 => '=49', 74 => '=4A',
        75 => '=4B', 76 => '=4C', 77 => '=4D', 78 => '=4E', 79 => '=4F',
        80 => '=50', 81 => '=51', 82 => '=52', 83 => '=53', 84 => '=54',
        85 => '=55', 86 => '=56', 87 => '=57', 88 => '=58', 89 => '=59',
        90 => '=5A', 91 => '=5B', 92 => '=5C', 93 => '=5D', 94 => '=5E',
        95 => '=5F', 96 => '=60', 97 => '=61', 98 => '=62', 99 => '=63',
        100 => '=64', 101 => '=65', 102 => '=66', 103 => '=67', 104 => '=68',
        105 => '=69', 106 => '=6A', 107 => '=6B', 108 => '=6C', 109 => '=6D',
        110 => '=6E', 111 => '=6F', 112 => '=70', 113 => '=71', 114 => '=72',
        115 => '=73', 116 => '=74', 117 => '=75', 118 => '=76', 119 => '=77',
        120 => '=78', 121 => '=79', 122 => '=7A', 123 => '=7B', 124 => '=7C',
        125 => '=7D', 126 => '=7E', 127 => '=7F', 128 => '=80', 129 => '=81',
        130 => '=82', 131 => '=83', 132 => '=84', 133 => '=85', 134 => '=86',
        135 => '=87', 136 => '=88', 137 => '=89', 138 => '=8A', 139 => '=8B',
        140 => '=8C', 141 => '=8D', 142 => '=8E', 143 => '=8F', 144 => '=90',
        145 => '=91', 146 => '=92', 147 => '=93', 148 => '=94', 149 => '=95',
        150 => '=96', 151 => '=97', 152 => '=98', 153 => '=99', 154 => '=9A',
        155 => '=9B', 156 => '=9C', 157 => '=9D', 158 => '=9E', 159 => '=9F',
        160 => '=A0', 161 => '=A1', 162 => '=A2', 163 => '=A3', 164 => '=A4',
        165 => '=A5', 166 => '=A6', 167 => '=A7', 168 => '=A8', 169 => '=A9',
        170 => '=AA', 171 => '=AB', 172 => '=AC', 173 => '=AD', 174 => '=AE',
        175 => '=AF', 176 => '=B0', 177 => '=B1', 178 => '=B2', 179 => '=B3',
        180 => '=B4', 181 => '=B5', 182 => '=B6', 183 => '=B7', 184 => '=B8',
        185 => '=B9', 186 => '=BA', 187 => '=BB', 188 => '=BC', 189 => '=BD',
        190 => '=BE', 191 => '=BF', 192 => '=C0', 193 => '=C1', 194 => '=C2',
        195 => '=C3', 196 => '=C4', 197 => '=C5', 198 => '=C6', 199 => '=C7',
        200 => '=C8', 201 => '=C9', 202 => '=CA', 203 => '=CB', 204 => '=CC',
        205 => '=CD', 206 => '=CE', 207 => '=CF', 208 => '=D0', 209 => '=D1',
        210 => '=D2', 211 => '=D3', 212 => '=D4', 213 => '=D5', 214 => '=D6',
        215 => '=D7', 216 => '=D8', 217 => '=D9', 218 => '=DA', 219 => '=DB',
        220 => '=DC', 221 => '=DD', 222 => '=DE', 223 => '=DF', 224 => '=E0',
        225 => '=E1', 226 => '=E2', 227 => '=E3', 228 => '=E4', 229 => '=E5',
        230 => '=E6', 231 => '=E7', 232 => '=E8', 233 => '=E9', 234 => '=EA',
        235 => '=EB', 236 => '=EC', 237 => '=ED', 238 => '=EE', 239 => '=EF',
        240 => '=F0', 241 => '=F1', 242 => '=F2', 243 => '=F3', 244 => '=F4',
        245 => '=F5', 246 => '=F6', 247 => '=F7', 248 => '=F8', 249 => '=F9',
        250 => '=FA', 251 => '=FB', 252 => '=FC', 253 => '=FD', 254 => '=FE',
        255 => '=FF',
        ];

    protected static $safeMapShare = [];

    /**
     * A map of non-encoded ascii characters.
     *
     * @var string[]
     */
    protected $safeMap = [];

    /**
     * Creates a new QpEncoder for the given CharacterStream.
     *
     * @param Swift_CharacterStream $charStream to use for reading characters
     * @param Swift_StreamFilter    $filter     if input should be canonicalized
     */
    public function __construct(Swift_CharacterStream $charStream, Swift_StreamFilter $filter = null)
    {
        $this->charStream = $charStream;
        if (!isset(self::$safeMapShare[$this->getSafeMapShareId()])) {
            $this->initSafeMap();
            self::$safeMapShare[$this->getSafeMapShareId()] = $this->safeMap;
        } else {
            $this->safeMap = self::$safeMapShare[$this->getSafeMapShareId()];
        }
        $this->filter = $filter;
    }

    public function __sleep()
    {
        return ['charStream', 'filter'];
    }

    public function __wakeup()
    {
        if (!isset(self::$safeMapShare[$this->getSafeMapShareId()])) {
            $this->initSafeMap();
            self::$safeMapShare[$this->getSafeMapShareId()] = $this->safeMap;
        } else {
            $this->safeMap = self::$safeMapShare[$this->getSafeMapShareId()];
        }
    }

    protected function getSafeMapShareId()
    {
        return static::class;
    }

    protected function initSafeMap()
    {
        foreach (array_merge(
            [0x09, 0x20], range(0x21, 0x3C), range(0x3E, 0x7E)) as $byte) {
            $this->safeMap[$byte] = \chr($byte);
        }
    }

    /**
     * Takes an unencoded string and produces a QP encoded string from it.
     *
     * QP encoded strings have a maximum line length of 76 characters.
     * If the first line needs to be shorter, indicate the difference with
     * $firstLineOffset.
     *
     * @param string $string          to encode
     * @param int    $firstLineOffset optional
     * @param int    $maxLineLength   optional 0 indicates the default of 76 chars
     *
     * @return string
     */
    public function encodeString($string, $firstLineOffset = 0, $maxLineLength = 0)
    {
        if ($maxLineLength > 76 || $maxLineLength <= 0) {
            $maxLineLength = 76;
        }

        $thisLineLength = $maxLineLength - $firstLineOffset;

        $lines = [];
        $lNo = 0;
        $lines[$lNo] = '';
        $currentLine = &$lines[$lNo++];
        $size = $lineLen = 0;

        $this->charStream->flushContents();
        $this->charStream->importString($string);

        // Fetching more than 4 chars at one is slower, as is fetching fewer bytes
        // Conveniently 4 chars is the UTF-8 safe number since UTF-8 has up to 6
        // bytes per char and (6 * 4 * 3 = 72 chars per line) * =NN is 3 bytes
        while (false !== $bytes = $this->nextSequence()) {
            // If we're filtering the input
            if (isset($this->filter)) {
                // If we can't filter because we need more bytes
                while ($this->filter->shouldBuffer($bytes)) {
                    // Then collect bytes into the buffer
                    if (false === $moreBytes = $this->nextSequence(1)) {
                        break;
                    }

                    foreach ($moreBytes as $b) {
                        $bytes[] = $b;
                    }
                }
                // And filter them
                $bytes = $this->filter->filter($bytes);
            }

            $enc = $this->encodeByteSequence($bytes, $size);

            $i = strpos($enc, '=0D=0A');
            $newLineLength = $lineLen + (false === $i ? $size : $i);

            if ($currentLine && $newLineLength >= $thisLineLength) {
                $lines[$lNo] = '';
                $currentLine = &$lines[$lNo++];
                $thisLineLength = $maxLineLength;
                $lineLen = 0;
            }

            $currentLine .= $enc;

            if (false === $i) {
                $lineLen += $size;
            } else {
                // 6 is the length of '=0D=0A'.
                $lineLen = $size - strrpos($enc, '=0D=0A') - 6;
            }
        }

        return $this->standardize(implode("=\r\n", $lines));
    }

    /**
     * Updates the charset used.
     *
     * @param string $charset
     */
    public function charsetChanged($charset)
    {
        $this->charStream->setCharacterSet($charset);
    }

    /**
     * Encode the given byte array into a verbatim QP form.
     *
     * @param int[] $bytes
     * @param int   $size
     *
     * @return string
     */
    protected function encodeByteSequence(array $bytes, &$size)
    {
        $ret = '';
        $size = 0;
        foreach ($bytes as $b) {
            if (isset($this->safeMap[$b])) {
                $ret .= $this->safeMap[$b];
                ++$size;
            } else {
                $ret .= self::$qpMap[$b];
                $size += 3;
            }
        }

        return $ret;
    }

    /**
     * Get the next sequence of bytes to read from the char stream.
     *
     * @param int $size number of bytes to read
     *
     * @return int[]
     */
    protected function nextSequence($size = 4)
    {
        return $this->charStream->readBytes($size);
    }

    /**
     * Make sure CRLF is correct and HT/SPACE are in valid places.
     *
     * @param string $string
     *
     * @return string
     */
    protected function standardize($string)
    {
        $string = str_replace(["\t=0D=0A", ' =0D=0A', '=0D=0A'],
            ["=09\r\n", "=20\r\n", "\r\n"], $string
            );
        switch ($end = \ord(substr($string, -1))) {
            case 0x09:
            case 0x20:
                $string = substr_replace($string, self::$qpMap[$end], -1);
        }

        return $string;
    }

    /**
     * Make a deep copy of object.
     */
    public function __clone()
    {
        $this->charStream = clone $this->charStream;
    }
}


================================================
FILE: lib/classes/Swift/Encoder/Rfc2231Encoder.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Handles RFC 2231 specified Encoding in Swift Mailer.
 *
 * @author Chris Corbyn
 */
class Swift_Encoder_Rfc2231Encoder implements Swift_Encoder
{
    /**
     * A character stream to use when reading a string as characters instead of bytes.
     *
     * @var Swift_CharacterStream
     */
    private $charStream;

    /**
     * Creates a new Rfc2231Encoder using the given character stream instance.
     */
    public function __construct(Swift_CharacterStream $charStream)
    {
        $this->charStream = $charStream;
    }

    /**
     * Takes an unencoded string and produces a string encoded according to
     * RFC 2231 from it.
     *
     * @param string $string
     * @param int    $firstLineOffset
     * @param int    $maxLineLength   optional, 0 indicates the default of 75 bytes
     *
     * @return string
     */
    public function encodeString($string, $firstLineOffset = 0, $maxLineLength = 0)
    {
        $lines = [];
        $lineCount = 0;
        $lines[] = '';
        $currentLine = &$lines[$lineCount++];

        if (0 >= $maxLineLength) {
            $maxLineLength = 75;
        }

        $this->charStream->flushContents();
        $this->charStream->importString($string);

        $thisLineLength = $maxLineLength - $firstLineOffset;

        while (false !== $char = $this->charStream->read(4)) {
            $encodedChar = rawurlencode($char);
            if (0 != \strlen($currentLine)
                && \strlen($currentLine.$encodedChar) > $thisLineLength) {
                $lines[] = '';
                $currentLine = &$lines[$lineCount++];
                $thisLineLength = $maxLineLength;
            }
            $currentLine .= $encodedChar;
        }

        return implode("\r\n", $lines);
    }

    /**
     * Updates the charset used.
     *
     * @param string $charset
     */
    public function charsetChanged($charset)
    {
        $this->charStream->setCharacterSet($charset);
    }

    /**
     * Make a deep copy of object.
     */
    public function __clone()
    {
        $this->charStream = clone $this->charStream;
    }
}


================================================
FILE: lib/classes/Swift/Encoder.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Interface for all Encoder schemes.
 *
 * @author Chris Corbyn
 */
interface Swift_Encoder extends Swift_Mime_CharsetObserver
{
    /**
     * Encode a given string to produce an encoded string.
     *
     * @param string $string
     * @param int    $firstLineOffset if first line needs to be shorter
     * @param int    $maxLineLength   - 0 indicates the default length for this encoding
     *
     * @return string
     */
    public function encodeString($string, $firstLineOffset = 0, $maxLineLength = 0);
}


================================================
FILE: lib/classes/Swift/Events/CommandEvent.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Generated when a command is sent over an SMTP connection.
 *
 * @author Chris Corbyn
 */
class Swift_Events_CommandEvent extends Swift_Events_EventObject
{
    /**
     * The command sent to the server.
     *
     * @var string
     */
    private $command;

    /**
     * An array of codes which a successful response will contain.
     *
     * @var int[]
     */
    private $successCodes = [];

    /**
     * Create a new CommandEvent for $source with $command.
     *
     * @param string $command
     * @param array  $successCodes
     */
    public function __construct(Swift_Transport $source, $command, $successCodes = [])
    {
        parent::__construct($source);
        $this->command = $command;
        $this->successCodes = $successCodes;
    }

    /**
     * Get the command which was sent to the server.
     *
     * @return string
     */
    public function getCommand()
    {
        return $this->command;
    }

    /**
     * Get the numeric response codes which indicate success for this command.
     *
     * @return int[]
     */
    public function getSuccessCodes()
    {
        return $this->successCodes;
    }
}


================================================
FILE: lib/classes/Swift/Events/CommandListener.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Listens for Transports to send commands to the server.
 *
 * @author Chris Corbyn
 */
interface Swift_Events_CommandListener extends Swift_Events_EventListener
{
    /**
     * Invoked immediately following a command being sent.
     */
    public function commandSent(Swift_Events_CommandEvent $evt);
}


================================================
FILE: lib/classes/Swift/Events/Event.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * The minimum interface for an Event.
 *
 * @author Chris Corbyn
 */
interface Swift_Events_Event
{
    /**
     * Get the source object of this event.
     *
     * @return object
     */
    public function getSource();

    /**
     * Prevent this Event from bubbling any further up the stack.
     *
     * @param bool $cancel, optional
     */
    public function cancelBubble($cancel = true);

    /**
     * Returns true if this Event will not bubble any further up the stack.
     *
     * @return bool
     */
    public function bubbleCancelled();
}


================================================
FILE: lib/classes/Swift/Events/EventDispatcher.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Interface for the EventDispatcher which handles the event dispatching layer.
 *
 * @author Chris Corbyn
 */
interface Swift_Events_EventDispatcher
{
    /**
     * Create a new SendEvent for $source and $message.
     *
     * @return Swift_Events_SendEvent
     */
    public function createSendEvent(Swift_Transport $source, Swift_Mime_SimpleMessage $message);

    /**
     * Create a new CommandEvent for $source and $command.
     *
     * @param string $command      That will be executed
     * @param array  $successCodes That are needed
     *
     * @return Swift_Events_CommandEvent
     */
    public function createCommandEvent(Swift_Transport $source, $command, $successCodes = []);

    /**
     * Create a new ResponseEvent for $source and $response.
     *
     * @param string $response
     * @param bool   $valid    If the response is valid
     *
     * @return Swift_Events_ResponseEvent
     */
    public function createResponseEvent(Swift_Transport $source, $response, $valid);

    /**
     * Create a new TransportChangeEvent for $source.
     *
     * @return Swift_Events_TransportChangeEvent
     */
    public function createTransportChangeEvent(Swift_Transport $source);

    /**
     * Create a new TransportExceptionEvent for $source.
     *
     * @return Swift_Events_TransportExceptionEvent
     */
    public function createTransportExceptionEvent(Swift_Transport $source, Swift_TransportException $ex);

    /**
     * Bind an event listener to this dispatcher.
     */
    public function bindEventListener(Swift_Events_EventListener $listener);

    /**
     * Dispatch the given Event to all suitable listeners.
     *
     * @param string $target method
     */
    public function dispatchEvent(Swift_Events_EventObject $evt, $target);
}


================================================
FILE: lib/classes/Swift/Events/EventListener.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * An identity interface which all EventListeners must extend.
 *
 * @author Chris Corbyn
 */
interface Swift_Events_EventListener
{
}


================================================
FILE: lib/classes/Swift/Events/EventObject.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * A base Event which all Event classes inherit from.
 *
 * @author Chris Corbyn
 */
class Swift_Events_EventObject implements Swift_Events_Event
{
    /** The source of this Event */
    private $source;

    /** The state of this Event (should it bubble up the stack?) */
    private $bubbleCancelled = false;

    /**
     * Create a new EventObject originating at $source.
     *
     * @param object $source
     */
    public function __construct($source)
    {
        $this->source = $source;
    }

    /**
     * Get the source object of this event.
     *
     * @return object
     */
    public function getSource()
    {
        return $this->source;
    }

    /**
     * Prevent this Event from bubbling any further up the stack.
     */
    public function cancelBubble($cancel = true)
    {
        $this->bubbleCancelled = $cancel;
    }

    /**
     * Returns true if this Event will not bubble any further up the stack.
     *
     * @return bool
     */
    public function bubbleCancelled()
    {
        return $this->bubbleCancelled;
    }
}


================================================
FILE: lib/classes/Swift/Events/ResponseEvent.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Generated when a response is received on a SMTP connection.
 *
 * @author Chris Corbyn
 */
class Swift_Events_ResponseEvent extends Swift_Events_EventObject
{
    /**
     * The overall result.
     *
     * @var bool
     */
    private $valid;

    /**
     * The response received from the server.
     *
     * @var string
     */
    private $response;

    /**
     * Create a new ResponseEvent for $source and $response.
     *
     * @param string $response
     * @param bool   $valid
     */
    public function __construct(Swift_Transport $source, $response, $valid = false)
    {
        parent::__construct($source);
        $this->response = $response;
        $this->valid = $valid;
    }

    /**
     * Get the response which was received from the server.
     *
     * @return string
     */
    public function getResponse()
    {
        return $this->response;
    }

    /**
     * Get the success status of this Event.
     *
     * @return bool
     */
    public function isValid()
    {
        return $this->valid;
    }
}


================================================
FILE: lib/classes/Swift/Events/ResponseListener.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Listens for responses from a remote SMTP server.
 *
 * @author Chris Corbyn
 */
interface Swift_Events_ResponseListener extends Swift_Events_EventListener
{
    /**
     * Invoked immediately following a response coming back.
     */
    public function responseReceived(Swift_Events_ResponseEvent $evt);
}


================================================
FILE: lib/classes/Swift/Events/SendEvent.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Generated when a message is being sent.
 *
 * @author Chris Corbyn
 */
class Swift_Events_SendEvent extends Swift_Events_EventObject
{
    /** Sending has yet to occur */
    const RESULT_PENDING = 0x0001;

    /** Email is spooled, ready to be sent */
    const RESULT_SPOOLED = 0x0011;

    /** Sending was successful */
    const RESULT_SUCCESS = 0x0010;

    /** Sending worked, but there were some failures */
    const RESULT_TENTATIVE = 0x0100;

    /** Sending failed */
    const RESULT_FAILED = 0x1000;

    /**
     * The Message being sent.
     *
     * @var Swift_Mime_SimpleMessage
     */
    private $message;

    /**
     * Any recipients which failed after sending.
     *
     * @var string[]
     */
    private $failedRecipients = [];

    /**
     * The overall result as a bitmask from the class constants.
     *
     * @var int
     */
    private $result;

    /**
     * Create a new SendEvent for $source and $message.
     */
    public function __construct(Swift_Transport $source, Swift_Mime_SimpleMessage $message)
    {
        parent::__construct($source);
        $this->message = $message;
        $this->result = self::RESULT_PENDING;
    }

    /**
     * Get the Transport used to send the Message.
     *
     * @return Swift_Transport
     */
    public function getTransport()
    {
        return $this->getSource();
    }

    /**
     * Get the Message being sent.
     *
     * @return Swift_Mime_SimpleMessage
     */
    public function getMessage()
    {
        return $this->message;
    }

    /**
     * Set the array of addresses that failed in sending.
     *
     * @param array $recipients
     */
    public function setFailedRecipients($recipients)
    {
        $this->failedRecipients = $recipients;
    }

    /**
     * Get an recipient addresses which were not accepted for delivery.
     *
     * @return string[]
     */
    public function getFailedRecipients()
    {
        return $this->failedRecipients;
    }

    /**
     * Set the result of sending.
     *
     * @param int $result
     */
    public function setResult($result)
    {
        $this->result = $result;
    }

    /**
     * Get the result of this Event.
     *
     * The return value is a bitmask from
     * {@see RESULT_PENDING, RESULT_SUCCESS, RESULT_TENTATIVE, RESULT_FAILED}
     *
     * @return int
     */
    public function getResult()
    {
        return $this->result;
    }
}


================================================
FILE: lib/classes/Swift/Events/SendListener.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Listens for Messages being sent from within the Transport system.
 *
 * @author Chris Corbyn
 */
interface Swift_Events_SendListener extends Swift_Events_EventListener
{
    /**
     * Invoked immediately before the Message is sent.
     */
    public function beforeSendPerformed(Swift_Events_SendEvent $evt);

    /**
     * Invoked immediately after the Message is sent.
     */
    public function sendPerformed(Swift_Events_SendEvent $evt);
}


================================================
FILE: lib/classes/Swift/Events/SimpleEventDispatcher.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * The EventDispatcher which handles the event dispatching layer.
 *
 * @author Chris Corbyn
 */
class Swift_Events_SimpleEventDispatcher implements Swift_Events_EventDispatcher
{
    /** A map of event types to their associated listener types */
    private $eventMap = [];

    /** Event listeners bound to this dispatcher */
    private $listeners = [];

    /**
     * Create a new EventDispatcher.
     */
    public function __construct()
    {
        $this->eventMap = [
            'Swift_Events_CommandEvent' => 'Swift_Events_CommandListener',
            'Swift_Events_ResponseEvent' => 'Swift_Events_ResponseListener',
            'Swift_Events_SendEvent' => 'Swift_Events_SendListener',
            'Swift_Events_TransportChangeEvent' => 'Swift_Events_TransportChangeListener',
            'Swift_Events_TransportExceptionEvent' => 'Swift_Events_TransportExceptionListener',
            ];
    }

    /**
     * Create a new SendEvent for $source and $message.
     *
     * @return Swift_Events_SendEvent
     */
    public function createSendEvent(Swift_Transport $source, Swift_Mime_SimpleMessage $message)
    {
        return new Swift_Events_SendEvent($source, $message);
    }

    /**
     * Create a new CommandEvent for $source and $command.
     *
     * @param string $command      That will be executed
     * @param array  $successCodes That are needed
     *
     * @return Swift_Events_CommandEvent
     */
    public function createCommandEvent(Swift_Transport $source, $command, $successCodes = [])
    {
        return new Swift_Events_CommandEvent($source, $command, $successCodes);
    }

    /**
     * Create a new ResponseEvent for $source and $response.
     *
     * @param string $response
     * @param bool   $valid    If the response is valid
     *
     * @return Swift_Events_ResponseEvent
     */
    public function createResponseEvent(Swift_Transport $source, $response, $valid)
    {
        return new Swift_Events_ResponseEvent($source, $response, $valid);
    }

    /**
     * Create a new TransportChangeEvent for $source.
     *
     * @return Swift_Events_TransportChangeEvent
     */
    public function createTransportChangeEvent(Swift_Transport $source)
    {
        return new Swift_Events_TransportChangeEvent($source);
    }

    /**
     * Create a new TransportExceptionEvent for $source.
     *
     * @return Swift_Events_TransportExceptionEvent
     */
    public function createTransportExceptionEvent(Swift_Transport $source, Swift_TransportException $ex)
    {
        return new Swift_Events_TransportExceptionEvent($source, $ex);
    }

    /**
     * Bind an event listener to this dispatcher.
     */
    public function bindEventListener(Swift_Events_EventListener $listener)
    {
        foreach ($this->listeners as $l) {
            // Already loaded
            if ($l === $listener) {
                return;
            }
        }
        $this->listeners[] = $listener;
    }

    /**
     * Dispatch the given Event to all suitable listeners.
     *
     * @param string $target method
     */
    public function dispatchEvent(Swift_Events_EventObject $evt, $target)
    {
        $bubbleQueue = $this->prepareBubbleQueue($evt);
        $this->bubble($bubbleQueue, $evt, $target);
    }

    /** Queue listeners on a stack ready for $evt to be bubbled up it */
    private function prepareBubbleQueue(Swift_Events_EventObject $evt)
    {
        $bubbleQueue = [];
        $evtClass = \get_class($evt);
        foreach ($this->listeners as $listener) {
            if (\array_key_exists($evtClass, $this->eventMap)
                && ($listener instanceof $this->eventMap[$evtClass])) {
                $bubbleQueue[] = $listener;
            }
        }

        return $bubbleQueue;
    }

    /** Bubble $evt up the stack calling $target() on each listener */
    private function bubble(array &$bubbleQueue, Swift_Events_EventObject $evt, $target)
    {
        if (!$evt->bubbleCancelled() && $listener = array_shift($bubbleQueue)) {
            $listener->$target($evt);
            $this->bubble($bubbleQueue, $evt, $target);
        }
    }
}


================================================
FILE: lib/classes/Swift/Events/TransportChangeEvent.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Generated when the state of a Transport is changed (i.e. stopped/started).
 *
 * @author Chris Corbyn
 */
class Swift_Events_TransportChangeEvent extends Swift_Events_EventObject
{
    /**
     * Get the Transport.
     *
     * @return Swift_Transport
     */
    public function getTransport()
    {
        return $this->getSource();
    }
}


================================================
FILE: lib/classes/Swift/Events/TransportChangeListener.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Listens for changes within the Transport system.
 *
 * @author Chris Corbyn
 */
interface Swift_Events_TransportChangeListener extends Swift_Events_EventListener
{
    /**
     * Invoked just before a Transport is started.
     */
    public function beforeTransportStarted(Swift_Events_TransportChangeEvent $evt);

    /**
     * Invoked immediately after the Transport is started.
     */
    public function transportStarted(Swift_Events_TransportChangeEvent $evt);

    /**
     * Invoked just before a Transport is stopped.
     */
    public function beforeTransportStopped(Swift_Events_TransportChangeEvent $evt);

    /**
     * Invoked immediately after the Transport is stopped.
     */
    public function transportStopped(Swift_Events_TransportChangeEvent $evt);
}


================================================
FILE: lib/classes/Swift/Events/TransportExceptionEvent.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Generated when a TransportException is thrown from the Transport system.
 *
 * @author Chris Corbyn
 */
class Swift_Events_TransportExceptionEvent extends Swift_Events_EventObject
{
    /**
     * The Exception thrown.
     *
     * @var Swift_TransportException
     */
    private $exception;

    /**
     * Create a new TransportExceptionEvent for $transport.
     */
    public function __construct(Swift_Transport $transport, Swift_TransportException $ex)
    {
        parent::__construct($transport);
        $this->exception = $ex;
    }

    /**
     * Get the TransportException thrown.
     *
     * @return Swift_TransportException
     */
    public function getException()
    {
        return $this->exception;
    }
}


================================================
FILE: lib/classes/Swift/Events/TransportExceptionListener.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Listens for Exceptions thrown from within the Transport system.
 *
 * @author Chris Corbyn
 */
interface Swift_Events_TransportExceptionListener extends Swift_Events_EventListener
{
    /**
     * Invoked as a TransportException is thrown in the Transport system.
     */
    public function exceptionThrown(Swift_Events_TransportExceptionEvent $evt);
}


================================================
FILE: lib/classes/Swift/FailoverTransport.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Contains a list of redundant Transports so when one fails, the next is used.
 *
 * @author Chris Corbyn
 */
class Swift_FailoverTransport extends Swift_Transport_FailoverTransport
{
    /**
     * Creates a new FailoverTransport with $transports.
     *
     * @param Swift_Transport[] $transports
     */
    public function __construct($transports = [])
    {
        \call_user_func_array(
            [$this, 'Swift_Transport_FailoverTransport::__construct'],
            Swift_DependencyContainer::getInstance()
                ->createDependenciesFor('transport.failover')
            );

        $this->setTransports($transports);
    }
}


================================================
FILE: lib/classes/Swift/FileSpool.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2009 Fabien Potencier <fabien.potencier@gmail.com>
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Stores Messages on the filesystem.
 *
 * @author Fabien Potencier
 * @author Xavier De Cock <xdecock@gmail.com>
 */
class Swift_FileSpool extends Swift_ConfigurableSpool
{
    /** The spool directory */
    private $path;

    /**
     * File WriteRetry Limit.
     *
     * @var int
     */
    private $retryLimit = 10;

    /**
     * Create a new FileSpool.
     *
     * @param string $path
     *
     * @throws Swift_IoException
     */
    public function __construct($path)
    {
        $this->path = $path;

        if (!file_exists($this->path)) {
            if (!mkdir($this->path, 0777, true)) {
                throw new Swift_IoException(sprintf('Unable to create path "%s".', $this->path));
            }
        }
    }

    /**
     * Tests if this Spool mechanism has started.
     *
     * @return bool
     */
    public function isStarted()
    {
        return true;
    }

    /**
     * Starts this Spool mechanism.
     */
    public function start()
    {
    }

    /**
     * Stops this Spool mechanism.
     */
    public function stop()
    {
    }

    /**
     * Allow to manage the enqueuing retry limit.
     *
     * Default, is ten and allows over 64^20 different fileNames
     *
     * @param int $limit
     */
    public function setRetryLimit($limit)
    {
        $this->retryLimit = $limit;
    }

    /**
     * Queues a message.
     *
     * @param Swift_Mime_SimpleMessage $message The message to store
     *
     * @throws Swift_IoException
     *
     * @return bool
     */
    public function queueMessage(Swift_Mime_SimpleMessage $message)
    {
        $ser = serialize($message);
        $fileName = $this->path.'/'.$this->getRandomString(10);
        for ($i = 0; $i < $this->retryLimit; ++$i) {
            /* We try an exclusive creation of the file. This is an atomic operation, it avoid locking mechanism */
            $fp = @fopen($fileName.'.message', 'xb');
            if (false !== $fp) {
                if (false === fwrite($fp, $ser)) {
                    return false;
                }

                return fclose($fp);
            } else {
                /* The file already exists, we try a longer fileName */
                $fileName .= $this->getRandomString(1);
            }
        }

        throw new Swift_IoException(sprintf('Unable to create a file for enqueuing Message in "%s".', $this->path));
    }

    /**
     * Execute a recovery if for any reason a process is sending for too long.
     *
     * @param int $timeout in second Defaults is for very slow smtp responses
     */
    public function recover($timeout = 900)
    {
        foreach (new DirectoryIterator($this->path) as $file) {
            $file = $file->getRealPath();

            if ('.message.sending' == substr($file, -16)) {
                $lockedtime = filectime($file);
                if ((time() - $lockedtime) > $timeout) {
                    rename($file, substr($file, 0, -8));
                }
            }
        }
    }

    /**
     * Sends messages using the given transport instance.
     *
     * @param Swift_Transport $transport        A transport instance
     * @param string[]        $failedRecipients An array of failures by-reference
     *
     * @return int The number of sent e-mail's
     */
    public function flushQueue(Swift_Transport $transport, &$failedRecipients = null)
    {
        $directoryIterator = new DirectoryIterator($this->path);

        /* Start the transport only if there are queued files to send */
        if (!$transport->isStarted()) {
            foreach ($directoryIterator as $file) {
                if ('.message' == substr($file->getRealPath(), -8)) {
                    $transport->start();
                    break;
                }
            }
        }

        $failedRecipients = (array) $failedRecipients;
        $count = 0;
        $time = time();
        foreach ($directoryIterator as $file) {
            $file = $file->getRealPath();

            if ('.message' != substr($file, -8)) {
                continue;
            }

            /* We try a rename, it's an atomic operation, and avoid locking the file */
            if (rename($file, $file.'.sending')) {
                $message = unserialize(file_get_contents($file.'.sending'));

                $count += $transport->send($message, $failedRecipients);

                unlink($file.'.sending');
            } else {
                /* This message has just been catched by another process */
                continue;
            }

            if ($this->getMessageLimit() && $count >= $this->getMessageLimit()) {
                break;
            }

            if ($this->getTimeLimit() && (time() - $time) >= $this->getTimeLimit()) {
                break;
            }
        }

        return $count;
    }

    /**
     * Returns a random string needed to generate a fileName for the queue.
     *
     * @param int $count
     *
     * @return string
     */
    protected function getRandomString($count)
    {
        // This string MUST stay FS safe, avoid special chars
        $base = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_-';
        $ret = '';
        $strlen = \strlen($base);
        for ($i = 0; $i < $count; ++$i) {
            $ret .= $base[random_int(0, $strlen - 1)];
        }

        return $ret;
    }
}


================================================
FILE: lib/classes/Swift/FileStream.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * An OutputByteStream which specifically reads from a file.
 *
 * @author Chris Corbyn
 */
interface Swift_FileStream extends Swift_OutputByteStream
{
    /**
     * Get the complete path to the file.
     *
     * @return string
     */
    public function getPath();
}


================================================
FILE: lib/classes/Swift/Filterable.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Allows StreamFilters to operate on a stream.
 *
 * @author Chris Corbyn
 */
interface Swift_Filterable
{
    /**
     * Add a new StreamFilter, referenced by $key.
     *
     * @param string $key
     */
    public function addFilter(Swift_StreamFilter $filter, $key);

    /**
     * Remove an existing filter using $key.
     *
     * @param string $key
     */
    public function removeFilter($key);
}


================================================
FILE: lib/classes/Swift/IdGenerator.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Message ID generator.
 */
interface Swift_IdGenerator
{
    /**
     * Returns a globally unique string to use for Message-ID or Content-ID.
     *
     * @return string
     */
    public function generateId();
}


================================================
FILE: lib/classes/Swift/Image.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * An image, embedded in a multipart message.
 *
 * @author Chris Corbyn
 */
class Swift_Image extends Swift_EmbeddedFile
{
    /**
     * Create a new EmbeddedFile.
     *
     * Details may be optionally provided to the constructor.
     *
     * @param string|Swift_OutputByteStream $data
     * @param string                        $filename
     * @param string                        $contentType
     */
    public function __construct($data = null, $filename = null, $contentType = null)
    {
        parent::__construct($data, $filename, $contentType);
    }

    /**
     * Create a new Image from a filesystem path.
     *
     * @param string $path
     *
     * @return self
     */
    public static function fromPath($path)
    {
        return (new self())->setFile(new Swift_ByteStream_FileByteStream($path));
    }
}


================================================
FILE: lib/classes/Swift/InputByteStream.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * An abstract means of writing data.
 *
 * Classes implementing this interface may use a subsystem which requires less
 * memory than working with large strings of data.
 *
 * @author Chris Corbyn
 */
interface Swift_InputByteStream
{
    /**
     * Writes $bytes to the end of the stream.
     *
     * Writing may not happen immediately if the stream chooses to buffer.  If
     * you want to write these bytes with immediate effect, call {@link commit()}
     * after calling write().
     *
     * This method returns the sequence ID of the write (i.e. 1 for first, 2 for
     * second, etc etc).
     *
     * @param string $bytes
     *
     * @throws Swift_IoException
     *
     * @return int
     */
    public function write($bytes);

    /**
     * For any bytes that are currently buffered inside the stream, force them
     * off the buffer.
     *
     * @throws Swift_IoException
     */
    public function commit();

    /**
     * Attach $is to this stream.
     *
     * The stream acts as an observer, receiving all data that is written.
     * All {@link write()} and {@link flushBuffers()} operations will be mirrored.
     *
     * @param Swift_InputByteStream $is
     */
    public function bind(self $is);

    /**
     * Remove an already bound stream.
     *
     * If $is is not bound, no errors will be raised.
     * If the stream currently has any buffered data it will be written to $is
     * before unbinding occurs.
     *
     * @param Swift_InputByteStream $is
     */
    public function unbind(self $is);

    /**
     * Flush the contents of the stream (empty it) and set the internal pointer
     * to the beginning.
     *
     * @throws Swift_IoException
     */
    public function flushBuffers();
}


================================================
FILE: lib/classes/Swift/IoException.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * I/O Exception class.
 *
 * @author Chris Corbyn
 */
class Swift_IoException extends Swift_SwiftException
{
    /**
     * Create a new IoException with $message.
     *
     * @param string $message
     * @param int    $code
     */
    public function __construct($message, $code = 0, Exception $previous = null)
    {
        parent::__construct($message, $code, $previous);
    }
}


================================================
FILE: lib/classes/Swift/KeyCache/ArrayKeyCache.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * A basic KeyCache backed by an array.
 *
 * @author Chris Corbyn
 */
class Swift_KeyCache_ArrayKeyCache implements Swift_KeyCache
{
    /**
     * Cache contents.
     *
     * @var array
     */
    private $contents = [];

    /**
     * An InputStream for cloning.
     *
     * @var Swift_KeyCache_KeyCacheInputStream
     */
    private $stream;

    /**
     * Create a new ArrayKeyCache with the given $stream for cloning to make
     * InputByteStreams.
     */
    public function __construct(Swift_KeyCache_KeyCacheInputStream $stream)
    {
        $this->stream = $stream;
    }

    /**
     * Set a string into the cache under $itemKey for the namespace $nsKey.
     *
     * @see MODE_WRITE, MODE_APPEND
     *
     * @param string $nsKey
     * @param string $itemKey
     * @param string $string
     * @param int    $mode
     */
    public function setString($nsKey, $itemKey, $string, $mode)
    {
        $this->prepareCache($nsKey);
        switch ($mode) {
            case self::MODE_WRITE:
                $this->contents[$nsKey][$itemKey] = $string;
                break;
            case self::MODE_APPEND:
                if (!$this->hasKey($nsKey, $itemKey)) {
                    $this->contents[$nsKey][$itemKey] = '';
                }
                $this->contents[$nsKey][$itemKey] .= $string;
                break;
            default:
                throw new Swift_SwiftException('Invalid mode ['.$mode.'] used to set nsKey='.$nsKey.', itemKey='.$itemKey);
        }
    }

    /**
     * Set a ByteStream into the cache under $itemKey for the namespace $nsKey.
     *
     * @see MODE_WRITE, MODE_APPEND
     *
     * @param string $nsKey
     * @param string $itemKey
     * @param int    $mode
     */
    public function importFromByteStream($nsKey, $itemKey, Swift_OutputByteStream $os, $mode)
    {
        $this->prepareCache($nsKey);
        switch ($mode) {
            case self::MODE_WRITE:
                $this->clearKey($nsKey, $itemKey);
                // no break
            case self::MODE_APPEND:
                if (!$this->hasKey($nsKey, $itemKey)) {
                    $this->contents[$nsKey][$itemKey] = '';
                }
                while (false !== $bytes = $os->read(8192)) {
                    $this->contents[$nsKey][$itemKey] .= $bytes;
                }
                break;
            default:
                throw new Swift_SwiftException('Invalid mode ['.$mode.'] used to set nsKey='.$nsKey.', itemKey='.$itemKey);
        }
    }

    /**
     * Provides a ByteStream which when written to, writes data to $itemKey.
     *
     * NOTE: The stream will always write in append mode.
     *
     * @param string $nsKey
     * @param string $itemKey
     *
     * @return Swift_InputByteStream
     */
    public function getInputByteStream($nsKey, $itemKey, Swift_InputByteStream $writeThrough = null)
    {
        $is = clone $this->stream;
        $is->setKeyCache($this);
        $is->setNsKey($nsKey);
        $is->setItemKey($itemKey);
        if (isset($writeThrough)) {
            $is->setWriteThroughStream($writeThrough);
        }

        return $is;
    }

    /**
     * Get data back out of the cache as a string.
     *
     * @param string $nsKey
     * @param string $itemKey
     *
     * @return string
     */
    public function getString($nsKey, $itemKey)
    {
        $this->prepareCache($nsKey);
        if ($this->hasKey($nsKey, $itemKey)) {
            return $this->contents[$nsKey][$itemKey];
        }
    }

    /**
     * Get data back out of the cache as a ByteStream.
     *
     * @param string                $nsKey
     * @param string                $itemKey
     * @param Swift_InputByteStream $is      to write the data to
     */
    public function exportToByteStream($nsKey, $itemKey, Swift_InputByteStream $is)
    {
        $this->prepareCache($nsKey);
        $is->write($this->getString($nsKey, $itemKey));
    }

    /**
     * Check if the given $itemKey exists in the namespace $nsKey.
     *
     * @param string $nsKey
     * @param string $itemKey
     *
     * @return bool
     */
    public function hasKey($nsKey, $itemKey)
    {
        $this->prepareCache($nsKey);

        return \array_key_exists($itemKey, $this->contents[$nsKey]);
    }

    /**
     * Clear data for $itemKey in the namespace $nsKey if it exists.
     *
     * @param string $nsKey
     * @param string $itemKey
     */
    public function clearKey($nsKey, $itemKey)
    {
        unset($this->contents[$nsKey][$itemKey]);
    }

    /**
     * Clear all data in the namespace $nsKey if it exists.
     *
     * @param string $nsKey
     */
    public function clearAll($nsKey)
    {
        unset($this->contents[$nsKey]);
    }

    /**
     * Initialize the namespace of $nsKey if needed.
     *
     * @param string $nsKey
     */
    private function prepareCache($nsKey)
    {
        if (!\array_key_exists($nsKey, $this->contents)) {
            $this->contents[$nsKey] = [];
        }
    }
}


================================================
FILE: lib/classes/Swift/KeyCache/DiskKeyCache.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * A KeyCache which streams to and from disk.
 *
 * @author Chris Corbyn
 */
class Swift_KeyCache_DiskKeyCache implements Swift_KeyCache
{
    /** Signal to place pointer at start of file */
    const POSITION_START = 0;

    /** Signal to place pointer at end of file */
    const POSITION_END = 1;

    /** Signal to leave pointer in whatever position it currently is */
    const POSITION_CURRENT = 2;

    /**
     * An InputStream for cloning.
     *
     * @var Swift_KeyCache_KeyCacheInputStream
     */
    private $stream;

    /**
     * A path to write to.
     *
     * @var string
     */
    private $path;

    /**
     * Stored keys.
     *
     * @var array
     */
    private $keys = [];

    /**
     * Create a new DiskKeyCache with the given $stream for cloning to make
     * InputByteStreams, and the given $path to save to.
     *
     * @param string $path to save to
     */
    public function __construct(Swift_KeyCache_KeyCacheInputStream $stream, $path)
    {
        $this->stream = $stream;
        $this->path = $path;
    }

    /**
     * Set a string into the cache under $itemKey for the namespace $nsKey.
     *
     * @see MODE_WRITE, MODE_APPEND
     *
     * @param string $nsKey
     * @param string $itemKey
     * @param string $string
     * @param int    $mode
     *
     * @throws Swift_IoException
     */
    public function setString($nsKey, $itemKey, $string, $mode)
    {
        $this->prepareCache($nsKey);
        switch ($mode) {
            case self::MODE_WRITE:
                $fp = $this->getHandle($nsKey, $itemKey, self::POSITION_START);
                break;
            case self::MODE_APPEND:
                $fp = $this->getHandle($nsKey, $itemKey, self::POSITION_END);
                break;
            default:
                throw new Swift_SwiftException('Invalid mode ['.$mode.'] used to set nsKey='.$nsKey.', itemKey='.$itemKey);
                break;
        }
        fwrite($fp, $string);
        $this->freeHandle($nsKey, $itemKey);
    }

    /**
     * Set a ByteStream into the cache under $itemKey for the namespace $nsKey.
     *
     * @see MODE_WRITE, MODE_APPEND
     *
     * @param string $nsKey
     * @param string $itemKey
     * @param int    $mode
     *
     * @throws Swift_IoException
     */
    public function importFromByteStream($nsKey, $itemKey, Swift_OutputByteStream $os, $mode)
    {
        $this->prepareCache($nsKey);
        switch ($mode) {
            case self::MODE_WRITE:
                $fp = $this->getHandle($nsKey, $itemKey, self::POSITION_START);
                break;
            case self::MODE_APPEND:
                $fp = $this->getHandle($nsKey, $itemKey, self::POSITION_END);
                break;
            default:
                throw new Swift_SwiftException('Invalid mode ['.$mode.'] used to set nsKey='.$nsKey.', itemKey='.$itemKey);
                break;
        }
        while (false !== $bytes = $os->read(8192)) {
            fwrite($fp, $bytes);
        }
        $this->freeHandle($nsKey, $itemKey);
    }

    /**
     * Provides a ByteStream which when written to, writes data to $itemKey.
     *
     * NOTE: The stream will always write in append mode.
     *
     * @param string $nsKey
     * @param string $itemKey
     *
     * @return Swift_InputByteStream
     */
    public function getInputByteStream($nsKey, $itemKey, Swift_InputByteStream $writeThrough = null)
    {
        $is = clone $this->stream;
        $is->setKeyCache($this);
        $is->setNsKey($nsKey);
        $is->setItemKey($itemKey);
        if (isset($writeThrough)) {
            $is->setWriteThroughStream($writeThrough);
        }

        return $is;
    }

    /**
     * Get data back out of the cache as a string.
     *
     * @param string $nsKey
     * @param string $itemKey
     *
     * @throws Swift_IoException
     *
     * @return string
     */
    public function getString($nsKey, $itemKey)
    {
        $this->prepareCache($nsKey);
        if ($this->hasKey($nsKey, $itemKey)) {
            $fp = $this->getHandle($nsKey, $itemKey, self::POSITION_START);
            $str = '';
            while (!feof($fp) && false !== $bytes = fread($fp, 8192)) {
                $str .= $bytes;
            }
            $this->freeHandle($nsKey, $itemKey);

            return $str;
        }
    }

    /**
     * Get data back out of the cache as a ByteStream.
     *
     * @param string                $nsKey
     * @param string                $itemKey
     * @param Swift_InputByteStream $is      to write the data to
     */
    public function exportToByteStream($nsKey, $itemKey, Swift_InputByteStream $is)
    {
        if ($this->hasKey($nsKey, $itemKey)) {
            $fp = $this->getHandle($nsKey, $itemKey, self::POSITION_START);
            while (!feof($fp) && false !== $bytes = fread($fp, 8192)) {
                $is->write($bytes);
            }
            $this->freeHandle($nsKey, $itemKey);
        }
    }

    /**
     * Check if the given $itemKey exists in the namespace $nsKey.
     *
     * @param string $nsKey
     * @param string $itemKey
     *
     * @return bool
     */
    public function hasKey($nsKey, $itemKey)
    {
        return is_file($this->path.'/'.$nsKey.'/'.$itemKey);
    }

    /**
     * Clear data for $itemKey in the namespace $nsKey if it exists.
     *
     * @param string $nsKey
     * @param string $itemKey
     */
    public function clearKey($nsKey, $itemKey)
    {
        if ($this->hasKey($nsKey, $itemKey)) {
            $this->freeHandle($nsKey, $itemKey);
            unlink($this->path.'/'.$nsKey.'/'.$itemKey);
        }
    }

    /**
     * Clear all data in the namespace $nsKey if it exists.
     *
     * @param string $nsKey
     */
    public function clearAll($nsKey)
    {
        if (\array_key_exists($nsKey, $this->keys)) {
            foreach ($this->keys[$nsKey] as $itemKey => $null) {
                $this->clearKey($nsKey, $itemKey);
            }
            if (is_dir($this->path.'/'.$nsKey)) {
                rmdir($this->path.'/'.$nsKey);
            }
            unset($this->keys[$nsKey]);
        }
    }

    /**
     * Initialize the namespace of $nsKey if needed.
     *
     * @param string $nsKey
     */
    private function prepareCache($nsKey)
    {
        $cacheDir = $this->path.'/'.$nsKey;
        if (!is_dir($cacheDir)) {
            if (!mkdir($cacheDir)) {
                throw new Swift_IoException('Failed to create cache directory '.$cacheDir);
            }
            $this->keys[$nsKey] = [];
        }
    }

    /**
     * Get a file handle on the cache item.
     *
     * @param string $nsKey
     * @param string $itemKey
     * @param int    $position
     *
     * @return resource
     */
    private function getHandle($nsKey, $itemKey, $position)
    {
        if (!isset($this->keys[$nsKey][$itemKey])) {
            $openMode = $this->hasKey($nsKey, $itemKey) ? 'r+b' : 'w+b';
            $fp = fopen($this->path.'/'.$nsKey.'/'.$itemKey, $openMode);
            $this->keys[$nsKey][$itemKey] = $fp;
        }
        if (self::POSITION_START == $position) {
            fseek($this->keys[$nsKey][$itemKey], 0, SEEK_SET);
        } elseif (self::POSITION_END == $position) {
            fseek($this->keys[$nsKey][$itemKey], 0, SEEK_END);
        }

        return $this->keys[$nsKey][$itemKey];
    }

    private function freeHandle($nsKey, $itemKey)
    {
        $fp = $this->getHandle($nsKey, $itemKey, self::POSITION_CURRENT);
        fclose($fp);
        $this->keys[$nsKey][$itemKey] = null;
    }

    /**
     * Destructor.
     */
    public function __destruct()
    {
        foreach ($this->keys as $nsKey => $null) {
            $this->clearAll($nsKey);
        }
    }

    public function __wakeup()
    {
        $this->keys = [];
    }
}


================================================
FILE: lib/classes/Swift/KeyCache/KeyCacheInputStream.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Writes data to a KeyCache using a stream.
 *
 * @author Chris Corbyn
 */
interface Swift_KeyCache_KeyCacheInputStream extends Swift_InputByteStream
{
    /**
     * Set the KeyCache to wrap.
     */
    public function setKeyCache(Swift_KeyCache $keyCache);

    /**
     * Set the nsKey which will be written to.
     *
     * @param string $nsKey
     */
    public function setNsKey($nsKey);

    /**
     * Set the itemKey which will be written to.
     *
     * @param string $itemKey
     */
    public function setItemKey($itemKey);

    /**
     * Specify a stream to write through for each write().
     */
    public function setWriteThroughStream(Swift_InputByteStream $is);

    /**
     * Any implementation should be cloneable, allowing the clone to access a
     * separate $nsKey and $itemKey.
     */
    public function __clone();
}


================================================
FILE: lib/classes/Swift/KeyCache/NullKeyCache.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * A null KeyCache that does not cache at all.
 *
 * @author Chris Corbyn
 */
class Swift_KeyCache_NullKeyCache implements Swift_KeyCache
{
    /**
     * Set a string into the cache under $itemKey for the namespace $nsKey.
     *
     * @see MODE_WRITE, MODE_APPEND
     *
     * @param string $nsKey
     * @param string $itemKey
     * @param string $string
     * @param int    $mode
     */
    public function setString($nsKey, $itemKey, $string, $mode)
    {
    }

    /**
     * Set a ByteStream into the cache under $itemKey for the namespace $nsKey.
     *
     * @see MODE_WRITE, MODE_APPEND
     *
     * @param string $nsKey
     * @param string $itemKey
     * @param int    $mode
     */
    public function importFromByteStream($nsKey, $itemKey, Swift_OutputByteStream $os, $mode)
    {
    }

    /**
     * Provides a ByteStream which when written to, writes data to $itemKey.
     *
     * NOTE: The stream will always write in append mode.
     *
     * @param string $nsKey
     * @param string $itemKey
     *
     * @return Swift_InputByteStream
     */
    public function getInputByteStream($nsKey, $itemKey, Swift_InputByteStream $writeThrough = null)
    {
    }

    /**
     * Get data back out of the cache as a string.
     *
     * @param string $nsKey
     * @param string $itemKey
     *
     * @return string
     */
    public function getString($nsKey, $itemKey)
    {
    }

    /**
     * Get data back out of the cache as a ByteStream.
     *
     * @param string                $nsKey
     * @param string                $itemKey
     * @param Swift_InputByteStream $is      to write the data to
     */
    public function exportToByteStream($nsKey, $itemKey, Swift_InputByteStream $is)
    {
    }

    /**
     * Check if the given $itemKey exists in the namespace $nsKey.
     *
     * @param string $nsKey
     * @param string $itemKey
     *
     * @return bool
     */
    public function hasKey($nsKey, $itemKey)
    {
        return false;
    }

    /**
     * Clear data for $itemKey in the namespace $nsKey if it exists.
     *
     * @param string $nsKey
     * @param string $itemKey
     */
    public function clearKey($nsKey, $itemKey)
    {
    }

    /**
     * Clear all data in the namespace $nsKey if it exists.
     *
     * @param string $nsKey
     */
    public function clearAll($nsKey)
    {
    }
}


================================================
FILE: lib/classes/Swift/KeyCache/SimpleKeyCacheInputStream.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Writes data to a KeyCache using a stream.
 *
 * @author Chris Corbyn
 */
class Swift_KeyCache_SimpleKeyCacheInputStream implements Swift_KeyCache_KeyCacheInputStream
{
    /** The KeyCache being written to */
    private $keyCache;

    /** The nsKey of the KeyCache being written to */
    private $nsKey;

    /** The itemKey of the KeyCache being written to */
    private $itemKey;

    /** A stream to write through on each write() */
    private $writeThrough = null;

    /**
     * Set the KeyCache to wrap.
     */
    public function setKeyCache(Swift_KeyCache $keyCache)
    {
        $this->keyCache = $keyCache;
    }

    /**
     * Specify a stream to write through for each write().
     */
    public function setWriteThroughStream(Swift_InputByteStream $is)
    {
        $this->writeThrough = $is;
    }

    /**
     * Writes $bytes to the end of the stream.
     *
     * @param string                $bytes
     * @param Swift_InputByteStream $is    optional
     */
    public function write($bytes, Swift_InputByteStream $is = null)
    {
        $this->keyCache->setString(
            $this->nsKey, $this->itemKey, $bytes, Swift_KeyCache::MODE_APPEND
            );
        if (isset($is)) {
            $is->write($bytes);
        }
        if (isset($this->writeThrough)) {
            $this->writeThrough->write($bytes);
        }
    }

    /**
     * Not used.
     */
    public function commit()
    {
    }

    /**
     * Not used.
     */
    public function bind(Swift_InputByteStream $is)
    {
    }

    /**
     * Not used.
     */
    public function unbind(Swift_InputByteStream $is)
    {
    }

    /**
     * Flush the contents of the stream (empty it) and set the internal pointer
     * to the beginning.
     */
    public function flushBuffers()
    {
        $this->keyCache->clearKey($this->nsKey, $this->itemKey);
    }

    /**
     * Set the nsKey which will be written to.
     *
     * @param string $nsKey
     */
    public function setNsKey($nsKey)
    {
        $this->nsKey = $nsKey;
    }

    /**
     * Set the itemKey which will be written to.
     *
     * @param string $itemKey
     */
    public function setItemKey($itemKey)
    {
        $this->itemKey = $itemKey;
    }

    /**
     * Any implementation should be cloneable, allowing the clone to access a
     * separate $nsKey and $itemKey.
     */
    public function __clone()
    {
        $this->writeThrough = null;
    }
}


================================================
FILE: lib/classes/Swift/KeyCache.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Provides a mechanism for storing data using two keys.
 *
 * @author Chris Corbyn
 */
interface Swift_KeyCache
{
    /** Mode for replacing existing cached data */
    const MODE_WRITE = 1;

    /** Mode for appending data to the end of existing cached data */
    const MODE_APPEND = 2;

    /**
     * Set a string into the cache under $itemKey for the namespace $nsKey.
     *
     * @see MODE_WRITE, MODE_APPEND
     *
     * @param string $nsKey
     * @param string $itemKey
     * @param string $string
     * @param int    $mode
     */
    public function setString($nsKey, $itemKey, $string, $mode);

    /**
     * Set a ByteStream into the cache under $itemKey for the namespace $nsKey.
     *
     * @see MODE_WRITE, MODE_APPEND
     *
     * @param string $nsKey
     * @param string $itemKey
     * @param int    $mode
     */
    public function importFromByteStream($nsKey, $itemKey, Swift_OutputByteStream $os, $mode);

    /**
     * Provides a ByteStream which when written to, writes data to $itemKey.
     *
     * NOTE: The stream will always write in append mode.
     * If the optional third parameter is passed all writes will go through $is.
     *
     * @param string                $nsKey
     * @param string                $itemKey
     * @param Swift_InputByteStream $is      optional input stream
     *
     * @return Swift_InputByteStream
     */
    public function getInputByteStream($nsKey, $itemKey, Swift_InputByteStream $is = null);

    /**
     * Get data back out of the cache as a string.
     *
     * @param string $nsKey
     * @param string $itemKey
     *
     * @return string
     */
    public function getString($nsKey, $itemKey);

    /**
     * Get data back out of the cache as a ByteStream.
     *
     * @param string                $nsKey
     * @param string                $itemKey
     * @param Swift_InputByteStream $is      stream to write the data to
     */
    public function exportToByteStream($nsKey, $itemKey, Swift_InputByteStream $is);

    /**
     * Check if the given $itemKey exists in the namespace $nsKey.
     *
     * @param string $nsKey
     * @param string $itemKey
     *
     * @return bool
     */
    public function hasKey($nsKey, $itemKey);

    /**
     * Clear data for $itemKey in the namespace $nsKey if it exists.
     *
     * @param string $nsKey
     * @param string $itemKey
     */
    public function clearKey($nsKey, $itemKey);

    /**
     * Clear all data in the namespace $nsKey if it exists.
     *
     * @param string $nsKey
     */
    public function clearAll($nsKey);
}


================================================
FILE: lib/classes/Swift/LoadBalancedTransport.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Redundantly and rotationally uses several Transport implementations when sending.
 *
 * @author Chris Corbyn
 */
class Swift_LoadBalancedTransport extends Swift_Transport_LoadBalancedTransport
{
    /**
     * Creates a new LoadBalancedTransport with $transports.
     *
     * @param array $transports
     */
    public function __construct($transports = [])
    {
        \call_user_func_array(
            [$this, 'Swift_Transport_LoadBalancedTransport::__construct'],
            Swift_DependencyContainer::getInstance()
                ->createDependenciesFor('transport.loadbalanced')
            );

        $this->setTransports($transports);
    }
}


================================================
FILE: lib/classes/Swift/Mailer/ArrayRecipientIterator.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Wraps a standard PHP array in an iterator.
 *
 * @author Chris Corbyn
 */
class Swift_Mailer_ArrayRecipientIterator implements Swift_Mailer_RecipientIterator
{
    /**
     * The list of recipients.
     *
     * @var array
     */
    private $recipients = [];

    /**
     * Create a new ArrayRecipientIterator from $recipients.
     */
    public function __construct(array $recipients)
    {
        $this->recipients = $recipients;
    }

    /**
     * Returns true only if there are more recipients to send to.
     *
     * @return bool
     */
    public function hasNext()
    {
        return !empty($this->recipients);
    }

    /**
     * Returns an array where the keys are the addresses of recipients and the
     * values are the names. e.g. ('foo@bar' => 'Foo') or ('foo@bar' => NULL).
     *
     * @return array
     */
    public function nextRecipient()
    {
        return array_splice($this->recipients, 0, 1);
    }
}


================================================
FILE: lib/classes/Swift/Mailer/RecipientIterator.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Provides an abstract way of specifying recipients for batch sending.
 *
 * @author Chris Corbyn
 */
interface Swift_Mailer_RecipientIterator
{
    /**
     * Returns true only if there are more recipients to send to.
     *
     * @return bool
     */
    public function hasNext();

    /**
     * Returns an array where the keys are the addresses of recipients and the
     * values are the names. e.g. ('foo@bar' => 'Foo') or ('foo@bar' => NULL).
     *
     * @return array
     */
    public function nextRecipient();
}


================================================
FILE: lib/classes/Swift/Mailer.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Swift Mailer class.
 *
 * @author Chris Corbyn
 */
class Swift_Mailer
{
    /** The Transport used to send messages */
    private $transport;

    /**
     * Create a new Mailer using $transport for delivery.
     */
    public function __construct(Swift_Transport $transport)
    {
        $this->transport = $transport;
    }

    /**
     * Create a new class instance of one of the message services.
     *
     * For example 'mimepart' would create a 'message.mimepart' instance
     *
     * @param string $service
     *
     * @return object
     */
    public function createMessage($service = 'message')
    {
        return Swift_DependencyContainer::getInstance()
            ->lookup('message.'.$service);
    }

    /**
     * Send the given Message like it would be sent in a mail client.
     *
     * All recipients (with the exception of Bcc) will be able to see the other
     * recipients this message was sent to.
     *
     * Recipient/sender data will be retrieved from the Message object.
     *
     * The return value is the number of recipients who were accepted for
     * delivery.
     *
     * @param array $failedRecipients An array of failures by-reference
     *
     * @return int The number of successful recipients. Can be 0 which indicates failure
     */
    public function send(Swift_Mime_SimpleMessage $message, &$failedRecipients = null)
    {
        $failedRecipients = (array) $failedRecipients;

        // FIXME: to be removed in 7.0 (as transport must now start itself on send)
        if (!$this->transport->isStarted()) {
            $this->transport->start();
        }

        $sent = 0;

        try {
            $sent = $this->transport->send($message, $failedRecipients);
        } catch (Swift_RfcComplianceException $e) {
            foreach ($message->getTo() as $address => $name) {
                $failedRecipients[] = $address;
            }
        }

        return $sent;
    }

    /**
     * Register a plugin using a known unique key (e.g. myPlugin).
     */
    public function registerPlugin(Swift_Events_EventListener $plugin)
    {
        $this->transport->registerPlugin($plugin);
    }

    /**
     * The Transport used to send messages.
     *
     * @return Swift_Transport
     */
    public function getTransport()
    {
        return $this->transport;
    }
}


================================================
FILE: lib/classes/Swift/MemorySpool.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2011 Fabien Potencier <fabien.potencier@gmail.com>
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Stores Messages in memory.
 *
 * @author Fabien Potencier
 */
class Swift_MemorySpool implements Swift_Spool
{
    protected $messages = [];
    private $flushRetries = 3;

    /**
     * Tests if this Transport mechanism has started.
     *
     * @return bool
     */
    public function isStarted()
    {
        return true;
    }

    /**
     * Starts this Transport mechanism.
     */
    public function start()
    {
    }

    /**
     * Stops this Transport mechanism.
     */
    public function stop()
    {
    }

    /**
     * @param int $retries
     */
    public function setFlushRetries($retries)
    {
        $this->flushRetries = $retries;
    }

    /**
     * Stores a message in the queue.
     *
     * @param Swift_Mime_SimpleMessage $message The message to store
     *
     * @return bool Whether the operation has succeeded
     */
    public function queueMessage(Swift_Mime_SimpleMessage $message)
    {
        //clone the message to make sure it is not changed while in the queue
        $this->messages[] = clone $message;

        return true;
    }

    /**
     * Sends messages using the given transport instance.
     *
     * @param Swift_Transport $transport        A transport instance
     * @param string[]        $failedRecipients An array of failures by-reference
     *
     * @return int The number of sent emails
     */
    public function flushQueue(Swift_Transport $transport, &$failedRecipients = null)
    {
        if (!$this->messages) {
            return 0;
        }

        if (!$transport->isStarted()) {
            $transport->start();
        }

        $count = 0;
        $retries = $this->flushRetries;
        while ($retries--) {
            try {
                while ($message = array_pop($this->messages)) {
                    $count += $transport->send($message, $failedRecipients);
                }
            } catch (Swift_TransportException $exception) {
                if ($retries) {
                    // re-queue the message at the end of the queue to give a chance
                    // to the other messages to be sent, in case the failure was due to
                    // this message and not just the transport failing
                    array_unshift($this->messages, $message);

                    // wait half a second before we try again
                    usleep(500000);
                } else {
                    throw $exception;
                }
            }
        }

        return $count;
    }
}


================================================
FILE: lib/classes/Swift/Message.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * The Message class for building emails.
 *
 * @author Chris Corbyn
 */
class Swift_Message extends Swift_Mime_SimpleMessage
{
    /**
     * @var Swift_Signers_HeaderSigner[]
     */
    private $headerSigners = [];

    /**
     * @var Swift_Signers_BodySigner[]
     */
    private $bodySigners = [];

    /**
     * @var array
     */
    private $savedMessage = [];

    /**
     * Create a new Message.
     *
     * Details may be optionally passed into the constructor.
     *
     * @param string $subject
     * @param string $body
     * @param string $contentType
     * @param string $charset
     */
    public function __construct($subject = null, $body = null, $contentType = null, $charset = null)
    {
        \call_user_func_array(
            [$this, 'Swift_Mime_SimpleMessage::__construct'],
            Swift_DependencyContainer::getInstance()
                ->createDependenciesFor('mime.message')
            );

        if (!isset($charset)) {
            $charset = Swift_DependencyContainer::getInstance()
                ->lookup('properties.charset');
        }
        $this->setSubject($subject);
        $this->setBody($body);
        $this->setCharset($charset);
        if ($contentType) {
            $this->setContentType($contentType);
        }
    }

    /**
     * Add a MimePart to this Message.
     *
     * @param string|Swift_OutputByteStream $body
     * @param string                        $contentType
     * @param string                        $charset
     *
     * @return $this
     */
    public function addPart($body, $contentType = null, $charset = null)
    {
        return $this->attach((new Swift_MimePart($body, $contentType, $charset))->setEncoder($this->getEncoder()));
    }

    /**
     * Attach a new signature handler to the message.
     *
     * @return $this
     */
    public function attachSigner(Swift_Signer $signer)
    {
        if ($signer instanceof Swift_Signers_HeaderSigner) {
            $this->headerSigners[] = $signer;
        } elseif ($signer instanceof Swift_Signers_BodySigner) {
            $this->bodySigners[] = $signer;
        }

        return $this;
    }

    /**
     * Detach a signature handler from a message.
     *
     * @return $this
     */
    public function detachSigner(Swift_Signer $signer)
    {
        if ($signer instanceof Swift_Signers_HeaderSigner) {
            foreach ($this->headerSigners as $k => $headerSigner) {
                if ($headerSigner === $signer) {
                    unset($this->headerSigners[$k]);

                    return $this;
                }
            }
        } elseif ($signer instanceof Swift_Signers_BodySigner) {
            foreach ($this->bodySigners as $k => $bodySigner) {
                if ($bodySigner === $signer) {
                    unset($this->bodySigners[$k]);

                    return $this;
                }
            }
        }

        return $this;
    }

    /**
     * Clear all signature handlers attached to the message.
     *
     * @return $this
     */
    public function clearSigners()
    {
        $this->headerSigners = [];
        $this->bodySigners = [];

        return $this;
    }

    /**
     * Get this message as a complete string.
     *
     * @return string
     */
    public function toString()
    {
        if (empty($this->headerSigners) && empty($this->bodySigners)) {
            return parent::toString();
        }

        $this->saveMessage();

        $this->doSign();

        $string = parent::toString();

        $this->restoreMessage();

        return $string;
    }

    /**
     * Write this message to a {@link Swift_InputByteStream}.
     */
    public function toByteStream(Swift_InputByteStream $is)
    {
        if (empty($this->headerSigners) && empty($this->bodySigners)) {
            parent::toByteStream($is);

            return;
        }

        $this->saveMessage();

        $this->doSign();

        parent::toByteStream($is);

        $this->restoreMessage();
    }

    public function __wakeup()
    {
        Swift_DependencyContainer::getInstance()->createDependenciesFor('mime.message');
    }

    /**
     * loops through signers and apply the signatures.
     */
    protected function doSign()
    {
        foreach ($this->bodySigners as $signer) {
            $altered = $signer->getAlteredHeaders();
            $this->saveHeaders($altered);
            $signer->signMessage($this);
        }

        foreach ($this->headerSigners as $signer) {
            $altered = $signer->getAlteredHeaders();
            $this->saveHeaders($altered);
            $signer->reset();

            $signer->setHeaders($this->getHeaders());

            $signer->startBody();
            $this->bodyToByteStream($signer);
            $signer->endBody();

            $signer->addSignature($this->getHeaders());
        }
    }

    /**
     * save the message before any signature is applied.
     */
    protected function saveMessage()
    {
        $this->savedMessage = ['headers' => []];
        $this->savedMessage['body'] = $this->getBody();
        $this->savedMessage['children'] = $this->getChildren();
        if (\count($this->savedMessage['children']) > 0 && '' != $this->getBody()) {
            $this->setChildren(array_merge([$this->becomeMimePart()], $this->savedMessage['children']));
            $this->setBody('');
        }
    }

    /**
     * save the original headers.
     */
    protected function saveHeaders(array $altered)
    {
        foreach ($altered as $head) {
            $lc = strtolower($head ?? '');

            if (!isset($this->savedMessage['headers'][$lc])) {
                $this->savedMessage['headers'][$lc] = $this->getHeaders()->getAll($head);
            }
        }
    }

    /**
     * Remove or restore altered headers.
     */
    protected function restoreHeaders()
    {
        foreach ($this->savedMessage['headers'] as $name => $savedValue) {
            $headers = $this->getHeaders()->getAll($name);

            foreach ($headers as $key => $value) {
                if (!isset($savedValue[$key])) {
                    $this->getHeaders()->remove($name, $key);
                }
            }
        }
    }

    /**
     * Restore message body.
     */
    protected function restoreMessage()
    {
        $this->setBody($this->savedMessage['body']);
        $this->setChildren($this->savedMessage['children']);

        $this->restoreHeaders();
        $this->savedMessage = [];
    }

    /**
     * Clone Message Signers.
     *
     * @see Swift_Mime_SimpleMimeEntity::__clone()
     */
    public function __clone()
    {
        parent::__clone();
        foreach ($this->bodySigners as $key => $bodySigner) {
            $this->bodySigners[$key] = clone $bodySigner;
        }

        foreach ($this->headerSigners as $key => $headerSigner) {
            $this->headerSigners[$key] = clone $headerSigner;
        }
    }
}


================================================
FILE: lib/classes/Swift/Mime/Attachment.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * An attachment, in a multipart message.
 *
 * @author Chris Corbyn
 */
class Swift_Mime_Attachment extends Swift_Mime_SimpleMimeEntity
{
    /** Recognized MIME types */
    private $mimeTypes = [];

    /**
     * Create a new Attachment with $headers, $encoder and $cache.
     *
     * @param array $mimeTypes
     */
    public function __construct(Swift_Mime_SimpleHeaderSet $headers, Swift_Mime_ContentEncoder $encoder, Swift_KeyCache $cache, Swift_IdGenerator $idGenerator, $mimeTypes = [])
    {
        parent::__construct($headers, $encoder, $cache, $idGenerator);
        $this->setDisposition('attachment');
        $this->setContentType('application/octet-stream');
        $this->mimeTypes = $mimeTypes;
    }

    /**
     * Get the nesting level used for this attachment.
     *
     * Always returns {@link LEVEL_MIXED}.
     *
     * @return int
     */
    public function getNestingLevel()
    {
        return self::LEVEL_MIXED;
    }

    /**
     * Get the Content-Disposition of this attachment.
     *
     * By default attachments have a disposition of "attachment".
     *
     * @return string
     */
    public function getDisposition()
    {
        return $this->getHeaderFieldModel('Content-Disposition');
    }

    /**
     * Set the Content-Disposition of this attachment.
     *
     * @param string $disposition
     *
     * @return $this
     */
    public function setDisposition($disposition)
    {
        if (!$this->setHeaderFieldModel('Content-Disposition', $disposition)) {
            $this->getHeaders()->addParameterizedHeader('Content-Disposition', $disposition);
        }

        return $this;
    }

    /**
     * Get the filename of this attachment when downloaded.
     *
     * @return string
     */
    public function getFilename()
    {
        return $this->getHeaderParameter('Content-Disposition', 'filename');
    }

    /**
     * Set the filename of this attachment.
     *
     * @param string $filename
     *
     * @return $this
     */
    public function setFilename($filename)
    {
        $this->setHeaderParameter('Content-Disposition', 'filename', $filename);
        $this->setHeaderParameter('Content-Type', 'name', $filename);

        return $this;
    }

    /**
     * Get the file size of this attachment.
     *
     * @return int
     */
    public function getSize()
    {
        return $this->getHeaderParameter('Content-Disposition', 'size');
    }

    /**
     * Set the file size of this attachment.
     *
     * @param int $size
     *
     * @return $this
     */
    public function setSize($size)
    {
        $this->setHeaderParameter('Content-Disposition', 'size', $size);

        return $this;
    }

    /**
     * Set the file that this attachment is for.
     *
     * @param string $contentType optional
     *
     * @return $this
     */
    public function setFile(Swift_FileStream $file, $contentType = null)
    {
        $this->setFilename(basename($file->getPath()));
        $this->setBody($file, $contentType);
        if (!isset($contentType)) {
            $extension = strtolower(substr($file->getPath(), strrpos($file->getPath(), '.') + 1));

            if (\array_key_exists($extension, $this->mimeTypes)) {
                $this->setContentType($this->mimeTypes[$extension]);
            }
        }

        return $this;
    }
}


================================================
FILE: lib/classes/Swift/Mime/CharsetObserver.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Observes changes in an Mime entity's character set.
 *
 * @author Chris Corbyn
 */
interface Swift_Mime_CharsetObserver
{
    /**
     * Notify this observer that the entity's charset has changed.
     *
     * @param string $charset
     */
    public function charsetChanged($charset);
}


================================================
FILE: lib/classes/Swift/Mime/ContentEncoder/Base64ContentEncoder.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Handles Base 64 Transfer Encoding in Swift Mailer.
 *
 * @author Chris Corbyn
 */
class Swift_Mime_ContentEncoder_Base64ContentEncoder extends Swift_Encoder_Base64Encoder implements Swift_Mime_ContentEncoder
{
    /**
     * Encode stream $in to stream $out.
     *
     * @param int $firstLineOffset
     */
    public function encodeByteStream(Swift_OutputByteStream $os, Swift_InputByteStream $is, $firstLineOffset = 0, $maxLineLength = 0)
    {
        if (0 >= $maxLineLength || 76 < $maxLineLength) {
            $maxLineLength = 76;
        }

        $remainder = 0;
        $base64ReadBufferRemainderBytes = '';

        // To reduce memory usage, the output buffer is streamed to the input buffer like so:
        //   Output Stream => base64encode => wrap line length => Input Stream
        // HOWEVER it's important to note that base64_encode() should only be passed whole triplets of data (except for the final chunk of data)
        // otherwise it will assume the input data has *ended* and it will incorrectly pad/terminate the base64 data mid-stream.
        // We use $base64ReadBufferRemainderBytes to carry over 1-2 "remainder" bytes from the each chunk from OutputStream and pre-pend those onto the
        // chunk of bytes read in the next iteration.
        // When the OutputStream is empty, we must flush any remainder bytes.
        while (true) {
            $readBytes = $os->read(8192);
            $atEOF = (false === $readBytes);

            if ($atEOF) {
                $streamTheseBytes = $base64ReadBufferRemainderBytes;
            } else {
                $streamTheseBytes = $base64ReadBufferRemainderBytes.$readBytes;
            }
            $base64ReadBufferRemainderBytes = '';
            $bytesLength = \strlen($streamTheseBytes);

            if (0 === $bytesLength) { // no data left to encode
                break;
            }

            // if we're not on the last block of the ouput stream, make sure $streamTheseBytes ends with a complete triplet of data
            // and carry over remainder 1-2 bytes to the next loop iteration
            if (!$atEOF) {
                $excessBytes = $bytesLength % 3;
                if (0 !== $excessBytes) {
                    $base64ReadBufferRemainderBytes = substr($streamTheseBytes, -$excessBytes);
                    $streamTheseBytes = substr($streamTheseBytes, 0, $bytesLength - $excessBytes);
                }
            }

            $encoded = base64_encode($streamTheseBytes);
            $encodedTransformed = '';
            $thisMaxLineLength = $maxLineLength - $remainder - $firstLineOffset;

            while ($thisMaxLineLength < \strlen($encoded)) {
                $encodedTransformed .= substr($encoded, 0, $thisMaxLineLength)."\r\n";
                $firstLineOffset = 0;
                $encoded = substr($encoded, $thisMaxLineLength);
                $thisMaxLineLength = $maxLineLength;
                $remainder = 0;
            }

            if (0 < $remainingLength = \strlen($encoded)) {
                $remainder += $remainingLength;
                $encodedTransformed .= $encoded;
                $encoded = null;
            }

            $is->write($encodedTransformed);

            if ($atEOF) {
                break;
            }
        }
    }

    /**
     * Get the name of this encoding scheme.
     * Returns the string 'base64'.
     *
     * @return string
     */
    public function getName()
    {
        return 'base64';
    }
}


================================================
FILE: lib/classes/Swift/Mime/ContentEncoder/NativeQpContentEncoder.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Handles Quoted Printable (QP) Transfer Encoding in Swift Mailer using the PHP core function.
 *
 * @author Lars Strojny
 */
class Swift_Mime_ContentEncoder_NativeQpContentEncoder implements Swift_Mime_ContentEncoder
{
    /**
     * @var string|null
     */
    private $charset;

    /**
     * @param string|null $charset
     */
    public function __construct($charset = null)
    {
        $this->charset = $charset ?: 'utf-8';
    }

    /**
     * Notify this observer that the entity's charset has changed.
     *
     * @param string $charset
     */
    public function charsetChanged($charset)
    {
        $this->charset = $charset;
    }

    /**
     * Encode $in to $out.
     *
     * @param Swift_OutputByteStream $os              to read from
     * @param Swift_InputByteStream  $is              to write to
     * @param int                    $firstLineOffset
     * @param int                    $maxLineLength   0 indicates the default length for this encoding
     *
     * @throws RuntimeException
     */
    public function encodeByteStream(Swift_OutputByteStream $os, Swift_InputByteStream $is, $firstLineOffset = 0, $maxLineLength = 0)
    {
        if ('utf-8' !== $this->charset) {
            throw new RuntimeException(sprintf('Charset "%s" not supported. NativeQpContentEncoder only supports "utf-8"', $this->charset));
        }

        $string = '';

        while (false !== $bytes = $os->read(8192)) {
            $string .= $bytes;
        }

        $is->write($this->encodeString($string));
    }

    /**
     * Get the MIME name of this content encoding scheme.
     *
     * @return string
     */
    public function getName()
    {
        return 'quoted-printable';
    }

    /**
     * Encode a given string to produce an encoded string.
     *
     * @param string $string
     * @param int    $firstLineOffset if first line needs to be shorter
     * @param int    $maxLineLength   0 indicates the default length for this encoding
     *
     * @throws RuntimeException
     *
     * @return string
     */
    public function encodeString($string, $firstLineOffset = 0, $maxLineLength = 0)
    {
        if ('utf-8' !== $this->charset) {
            throw new RuntimeException(sprintf('Charset "%s" not supported. NativeQpContentEncoder only supports "utf-8"', $this->charset));
        }

        return $this->standardize(quoted_printable_encode($string));
    }

    /**
     * Make sure CRLF is correct and HT/SPACE are in valid places.
     *
     * @param string $string
     *
     * @return string
     */
    protected function standardize($string)
    {
        // transform CR or LF to CRLF
        $string = preg_replace('~=0D(?!=0A)|(?<!=0D)=0A~', '=0D=0A', $string);
        // transform =0D=0A to CRLF
        $string = str_replace(["\t=0D=0A", ' =0D=0A', '=0D=0A'], ["=09\r\n", "=20\r\n", "\r\n"], $string);

        switch (\ord(substr($string, -1))) {
            case 0x09:
                $string = substr_replace($string, '=09', -1);
                break;
            case 0x20:
                $string = substr_replace($string, '=20', -1);
                break;
        }

        return $string;
    }
}


================================================
FILE: lib/classes/Swift/Mime/ContentEncoder/NullContentEncoder.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Handles the case where the email body is already encoded and you just need specify the correct
 * encoding without actually changing the encoding of the body.
 *
 * @author Jan Flora <jf@penneo.com>
 */
class Swift_Mime_ContentEncoder_NullContentEncoder implements Swift_Mime_ContentEncoder
{
    /**
     * The name of this encoding scheme (probably 7bit or 8bit).
     *
     * @var string
     */
    private $name;

    /**
     * Creates a new NullContentEncoder with $name (probably 7bit or 8bit).
     *
     * @param string $name
     */
    public function __construct($name)
    {
        $this->name = $name;
    }

    /**
     * Encode a given string to produce an encoded string.
     *
     * @param string $string
     * @param int    $firstLineOffset ignored
     * @param int    $maxLineLength   ignored
     *
     * @return string
     */
    public function encodeString($string, $firstLineOffset = 0, $maxLineLength = 0)
    {
        return $string;
    }

    /**
     * Encode stream $in to stream $out.
     *
     * @param int $firstLineOffset ignored
     * @param int $maxLineLength   ignored
     */
    public function encodeByteStream(Swift_OutputByteStream $os, Swift_InputByteStream $is, $firstLineOffset = 0, $maxLineLength = 0)
    {
        while (false !== ($bytes = $os->read(8192))) {
            $is->write($bytes);
        }
    }

    /**
     * Get the name of this encoding scheme.
     *
     * @return string
     */
    public function getName()
    {
        return $this->name;
    }

    /**
     * Not used.
     */
    public function charsetChanged($charset)
    {
    }
}


================================================
FILE: lib/classes/Swift/Mime/ContentEncoder/PlainContentEncoder.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Handles binary/7/8-bit Transfer Encoding in Swift Mailer.
 *
 * When sending 8-bit content over SMTP, you should use
 * Swift_Transport_Esmtp_EightBitMimeHandler to enable the 8BITMIME SMTP
 * extension.
 *
 * @author Chris Corbyn
 */
class Swift_Mime_ContentEncoder_PlainContentEncoder implements Swift_Mime_ContentEncoder
{
    /**
     * The name of this encoding scheme (probably 7bit or 8bit).
     *
     * @var string
     */
    private $name;

    /**
     * True if canonical transformations should be done.
     *
     * @var bool
     */
    private $canonical;

    /**
     * Creates a new PlainContentEncoder with $name (probably 7bit or 8bit).
     *
     * @param string $name
     * @param bool   $canonical if canonicalization transformation should be done
     */
    public function __construct($name, $canonical = false)
    {
        $this->name = $name;
        $this->canonical = $canonical;
    }

    /**
     * Encode a given string to produce an encoded string.
     *
     * @param string $string
     * @param int    $firstLineOffset ignored
     * @param int    $maxLineLength   - 0 means no wrapping will occur
     *
     * @return string
     */
    public function encodeString($string, $firstLineOffset = 0, $maxLineLength = 0)
    {
        if ($this->canonical) {
            $string = $this->canonicalize($string);
        }

        return $this->safeWordwrap($string, $maxLineLength, "\r\n");
    }

    /**
     * Encode stream $in to stream $out.
     *
     * @param int $firstLineOffset ignored
     * @param int $maxLineLength   optional, 0 means no wrapping will occur
     */
    public function encodeByteStream(Swift_OutputByteStream $os, Swift_InputByteStream $is, $firstLineOffset = 0, $maxLineLength = 0)
    {
        $leftOver = '';
        while (false !== $bytes = $os->read(8192)) {
            $toencode = $leftOver.$bytes;
            if ($this->canonical) {
                $toencode = $this->canonicalize($toencode);
            }
            $wrapped = $this->safeWordwrap($toencode, $maxLineLength, "\r\n");
            $lastLinePos = strrpos($wrapped, "\r\n");
            $leftOver = substr($wrapped, $lastLinePos);
            $wrapped = substr($wrapped, 0, $lastLinePos);

            $is->write($wrapped);
        }
        if (\strlen($leftOver)) {
            $is->write($leftOver);
        }
    }

    /**
     * Get the name of this encoding scheme.
     *
     * @return string
     */
    public function getName()
    {
        return $this->name;
    }

    /**
     * Not used.
     */
    public function charsetChanged($charset)
    {
    }

    /**
     * A safer (but weaker) wordwrap for unicode.
     *
     * @param string $string
     * @param int    $length
     * @param string $le
     *
     * @return string
     */
    private function safeWordwrap($string, $length = 75, $le = "\r\n")
    {
        if (0 >= $length) {
            return $string;
        }

        $originalLines = explode($le, $string);

        $lines = [];
        $lineCount = 0;

        foreach ($originalLines as $originalLine) {
            $lines[] = '';
            $currentLine = &$lines[$lineCount++];

            //$chunks = preg_split('/(?<=[\ \t,\.!\?\-&\+\/])/', $originalLine);
            $chunks = preg_split('/(?<=\s)/', $originalLine);

            foreach ($chunks as $chunk) {
                if (0 != \strlen($currentLine)
                    && \strlen($currentLine.$chunk) > $length) {
                    $lines[] = '';
                    $currentLine = &$lines[$lineCount++];
                }
                $currentLine .= $chunk;
            }
        }

        return implode("\r\n", $lines);
    }

    /**
     * Canonicalize string input (fix CRLF).
     *
     * @param string $string
     *
     * @return string
     */
    private function canonicalize($string)
    {
        return str_replace(
            ["\r\n", "\r", "\n"],
            ["\n", "\n", "\r\n"],
            $string
            );
    }
}


================================================
FILE: lib/classes/Swift/Mime/ContentEncoder/QpContentEncoder.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Handles Quoted Printable (QP) Transfer Encoding in Swift Mailer.
 *
 * @author     Chris Corbyn
 */
class Swift_Mime_ContentEncoder_QpContentEncoder extends Swift_Encoder_QpEncoder implements Swift_Mime_ContentEncoder
{
    protected $dotEscape;

    /**
     * Creates a new QpContentEncoder for the given CharacterStream.
     *
     * @param Swift_CharacterStream $charStream to use for reading characters
     * @param Swift_StreamFilter    $filter     if canonicalization should occur
     * @param bool                  $dotEscape  if dot stuffing workaround must be enabled
     */
    public function __construct(Swift_CharacterStream $charStream, Swift_StreamFilter $filter = null, $dotEscape = false)
    {
        $this->dotEscape = $dotEscape;
        parent::__construct($charStream, $filter);
    }

    public function __sleep()
    {
        return ['charStream', 'filter', 'dotEscape'];
    }

    protected function getSafeMapShareId()
    {
        return static::class.($this->dotEscape ? '.dotEscape' : '');
    }

    protected function initSafeMap()
    {
        parent::initSafeMap();
        if ($this->dotEscape) {
            /* Encode . as =2e for buggy remote servers */
            unset($this->safeMap[0x2e]);
        }
    }

    /**
     * Encode stream $in to stream $out.
     *
     * QP encoded strings have a maximum line length of 76 characters.
     * If the first line needs to be shorter, indicate the difference with
     * $firstLineOffset.
     *
     * @param Swift_OutputByteStream $os              output stream
     * @param Swift_InputByteStream  $is              input stream
     * @param int                    $firstLineOffset
     * @param int                    $maxLineLength
     */
    public function encodeByteStream(Swift_OutputByteStream $os, Swift_InputByteStream $is, $firstLineOffset = 0, $maxLineLength = 0)
    {
        if ($maxLineLength > 76 || $maxLineLength <= 0) {
            $maxLineLength = 76;
        }

        $thisLineLength = $maxLineLength - $firstLineOffset;

        $this->charStream->flushContents();
        $this->charStream->importByteStream($os);

        $currentLine = '';
        $prepend = '';
        $size = $lineLen = 0;

        while (false !== $bytes = $this->nextSequence()) {
            // If we're filtering the input
            if (isset($this->filter)) {
                // If we can't filter because we need more bytes
                while ($this->filter->shouldBuffer($bytes)) {
                    // Then collect bytes into the buffer
                    if (false === $moreBytes = $this->nextSequence(1)) {
                        break;
                    }

                    foreach ($moreBytes as $b) {
                        $bytes[] = $b;
                    }
                }
                // And filter them
                $bytes = $this->filter->filter($bytes);
            }

            $enc = $this->encodeByteSequence($bytes, $size);

            $i = strpos($enc, '=0D=0A');
            $newLineLength = $lineLen + (false === $i ? $size : $i);

            if ($currentLine && $newLineLength >= $thisLineLength) {
                $is->write($prepend.$this->standardize($currentLine));
                $currentLine = '';
                $prepend = "=\r\n";
                $thisLineLength = $maxLineLength;
                $lineLen = 0;
            }

            $currentLine .= $enc;

            if (false === $i) {
                $lineLen += $size;
            } else {
                // 6 is the length of '=0D=0A'.
                $lineLen = $size - strrpos($enc, '=0D=0A') - 6;
            }
        }
        if (\strlen($currentLine)) {
            $is->write($prepend.$this->standardize($currentLine));
        }
    }

    /**
     * Get the name of this encoding scheme.
     * Returns the string 'quoted-printable'.
     *
     * @return string
     */
    public function getName()
    {
        return 'quoted-printable';
    }
}


================================================
FILE: lib/classes/Swift/Mime/ContentEncoder/QpContentEncoderProxy.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Proxy for quoted-printable content encoders.
 *
 * Switches on the best QP encoder implementation for current charset.
 *
 * @author Jean-François Simon <jeanfrancois.simon@sensiolabs.com>
 */
class Swift_Mime_ContentEncoder_QpContentEncoderProxy implements Swift_Mime_ContentEncoder
{
    /**
     * @var Swift_Mime_ContentEncoder_QpContentEncoder
     */
    private $safeEncoder;

    /**
     * @var Swift_Mime_ContentEncoder_NativeQpContentEncoder
     */
    private $nativeEncoder;

    /**
     * @var string|null
     */
    private $charset;

    /**
     * Constructor.
     *
     * @param string|null $charset
     */
    public function __construct(Swift_Mime_ContentEncoder_QpContentEncoder $safeEncoder, Swift_Mime_ContentEncoder_NativeQpContentEncoder $nativeEncoder, $charset)
    {
        $this->safeEncoder = $safeEncoder;
        $this->nativeEncoder = $nativeEncoder;
        $this->charset = $charset;
    }

    /**
     * Make a deep copy of object.
     */
    public function __clone()
    {
        $this->safeEncoder = clone $this->safeEncoder;
        $this->nativeEncoder = clone $this->nativeEncoder;
    }

    /**
     * {@inheritdoc}
     */
    public function charsetChanged($charset)
    {
        $this->charset = $charset;
        $this->safeEncoder->charsetChanged($charset);
    }

    /**
     * {@inheritdoc}
     */
    public function encodeByteStream(Swift_OutputByteStream $os, Swift_InputByteStream $is, $firstLineOffset = 0, $maxLineLength = 0)
    {
        $this->getEncoder()->encodeByteStream($os, $is, $firstLineOffset, $maxLineLength);
    }

    /**
     * {@inheritdoc}
     */
    public function getName()
    {
        return 'quoted-printable';
    }

    /**
     * {@inheritdoc}
     */
    public function encodeString($string, $firstLineOffset = 0, $maxLineLength = 0)
    {
        return $this->getEncoder()->encodeString($string, $firstLineOffset, $maxLineLength);
    }

    /**
     * @return Swift_Mime_ContentEncoder
     */
    private function getEncoder()
    {
        return 'utf-8' === $this->charset ? $this->nativeEncoder : $this->safeEncoder;
    }
}


================================================
FILE: lib/classes/Swift/Mime/ContentEncoder/RawContentEncoder.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Handles raw Transfer Encoding in Swift Mailer.
 *
 * When sending 8-bit content over SMTP, you should use
 * Swift_Transport_Esmtp_EightBitMimeHandler to enable the 8BITMIME SMTP
 * extension.
 *
 * @author Sebastiaan Stok <s.stok@rollerscapes.net>
 */
class Swift_Mime_ContentEncoder_RawContentEncoder implements Swift_Mime_ContentEncoder
{
    /**
     * Encode a given string to produce an encoded string.
     *
     * @param string $string
     * @param int    $firstLineOffset ignored
     * @param int    $maxLineLength   ignored
     *
     * @return string
     */
    public function encodeString($string, $firstLineOffset = 0, $maxLineLength = 0)
    {
        return $string;
    }

    /**
     * Encode stream $in to stream $out.
     *
     * @param int $firstLineOffset ignored
     * @param int $maxLineLength   ignored
     */
    public function encodeByteStream(Swift_OutputByteStream $os, Swift_InputByteStream $is, $firstLineOffset = 0, $maxLineLength = 0)
    {
        while (false !== ($bytes = $os->read(8192))) {
            $is->write($bytes);
        }
    }

    /**
     * Get the name of this encoding scheme.
     *
     * @return string
     */
    public function getName()
    {
        return 'raw';
    }

    /**
     * Not used.
     */
    public function charsetChanged($charset)
    {
    }
}


================================================
FILE: lib/classes/Swift/Mime/ContentEncoder.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Interface for all Transfer Encoding schemes.
 *
 * @author Chris Corbyn
 */
interface Swift_Mime_ContentEncoder extends Swift_Encoder
{
    /**
     * Encode $in to $out.
     *
     * @param Swift_OutputByteStream $os              to read from
     * @param Swift_InputByteStream  $is              to write to
     * @param int                    $firstLineOffset
     * @param int                    $maxLineLength   - 0 indicates the default length for this encoding
     */
    public function encodeByteStream(Swift_OutputByteStream $os, Swift_InputByteStream $is, $firstLineOffset = 0, $maxLineLength = 0);

    /**
     * Get the MIME name of this content encoding scheme.
     *
     * @return string
     */
    public function getName();
}


================================================
FILE: lib/classes/Swift/Mime/EmbeddedFile.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * An embedded file, in a multipart message.
 *
 * @author Chris Corbyn
 */
class Swift_Mime_EmbeddedFile extends Swift_Mime_Attachment
{
    /**
     * Creates a new Attachment with $headers and $encoder.
     *
     * @param array $mimeTypes optional
     */
    public function __construct(Swift_Mime_SimpleHeaderSet $headers, Swift_Mime_ContentEncoder $encoder, Swift_KeyCache $cache, Swift_IdGenerator $idGenerator, $mimeTypes = [])
    {
        parent::__construct($headers, $encoder, $cache, $idGenerator, $mimeTypes);
        $this->setDisposition('inline');
        $this->setId($this->getId());
    }

    /**
     * Get the nesting level of this EmbeddedFile.
     *
     * Returns {@see LEVEL_RELATED}.
     *
     * @return int
     */
    public function getNestingLevel()
    {
        return self::LEVEL_RELATED;
    }
}


================================================
FILE: lib/classes/Swift/Mime/EncodingObserver.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Observes changes for a Mime entity's ContentEncoder.
 *
 * @author Chris Corbyn
 */
interface Swift_Mime_EncodingObserver
{
    /**
     * Notify this observer that the observed entity's ContentEncoder has changed.
     */
    public function encoderChanged(Swift_Mime_ContentEncoder $encoder);
}


================================================
FILE: lib/classes/Swift/Mime/Header.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * A MIME Header.
 *
 * @author Chris Corbyn
 */
interface Swift_Mime_Header
{
    /** Text headers */
    const TYPE_TEXT = 2;

    /**  headers (text + params) */
    const TYPE_PARAMETERIZED = 6;

    /** Mailbox and address headers */
    const TYPE_MAILBOX = 8;

    /** Date and time headers */
    const TYPE_DATE = 16;

    /** Identification headers */
    const TYPE_ID = 32;

    /** Address path headers */
    const TYPE_PATH = 64;

    /**
     * Get the type of Header that this instance represents.
     *
     * @see TYPE_TEXT, TYPE_PARAMETERIZED, TYPE_MAILBOX
     * @see TYPE_DATE, TYPE_ID, TYPE_PATH
     *
     * @return int
     */
    public function getFieldType();

    /**
     * Set the model for the field body.
     *
     * The actual types needed will vary depending upon the type of Header.
     *
     * @param mixed $model
     */
    public function setFieldBodyModel($model);

    /**
     * Set the charset used when rendering the Header.
     *
     * @param string $charset
     */
    public function setCharset($charset);

    /**
     * Get the model for the field body.
     *
     * The return type depends on the specifics of the Header.
     *
     * @return mixed
     */
    public function getFieldBodyModel();

    /**
     * Get the name of this header (e.g. Subject).
     *
     * The name is an identifier and as such will be immutable.
     *
     * @return string
     */
    public function getFieldName();

    /**
     * Get the field body, prepared for folding into a final header value.
     *
     * @return string
     */
    public function getFieldBody();

    /**
     * Get this Header rendered as a compliant string, including trailing CRLF.
     *
     * @return string
     */
    public function toString();
}


================================================
FILE: lib/classes/Swift/Mime/HeaderEncoder/Base64HeaderEncoder.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Handles Base64 (B) Header Encoding in Swift Mailer.
 *
 * @author Chris Corbyn
 */
class Swift_Mime_HeaderEncoder_Base64HeaderEncoder extends Swift_Encoder_Base64Encoder implements Swift_Mime_HeaderEncoder
{
    /**
     * Get the name of this encoding scheme.
     * Returns the string 'B'.
     *
     * @return string
     */
    public function getName()
    {
        return 'B';
    }

    /**
     * Takes an unencoded string and produces a Base64 encoded string from it.
     *
     * If the charset is iso-2022-jp, it uses mb_encode_mimeheader instead of
     * default encodeString, otherwise pass to the parent method.
     *
     * @param string $string          string to encode
     * @param int    $firstLineOffset
     * @param int    $maxLineLength   optional, 0 indicates the default of 76 bytes
     * @param string $charset
     *
     * @return string
     */
    public function encodeString($string, $firstLineOffset = 0, $maxLineLength = 0, $charset = 'utf-8')
    {
        if ('iso-2022-jp' === strtolower($charset ?? '')) {
            $old = mb_internal_encoding();
            mb_internal_encoding('utf-8');
            $newstring = mb_encode_mimeheader($string, $charset, $this->getName(), "\r\n");
            mb_internal_encoding($old);

            return $newstring;
        }

        return parent::encodeString($string, $firstLineOffset, $maxLineLength);
    }
}


================================================
FILE: lib/classes/Swift/Mime/HeaderEncoder/QpHeaderEncoder.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Handles Quoted Printable (Q) Header Encoding in Swift Mailer.
 *
 * @author Chris Corbyn
 */
class Swift_Mime_HeaderEncoder_QpHeaderEncoder extends Swift_Encoder_QpEncoder implements Swift_Mime_HeaderEncoder
{
    /**
     * Creates a new QpHeaderEncoder for the given CharacterStream.
     *
     * @param Swift_CharacterStream $charStream to use for reading characters
     */
    public function __construct(Swift_CharacterStream $charStream)
    {
        parent::__construct($charStream);
    }

    protected function initSafeMap()
    {
        foreach (array_merge(
            range(0x61, 0x7A), range(0x41, 0x5A),
            range(0x30, 0x39), [0x20, 0x21, 0x2A, 0x2B, 0x2D, 0x2F]
        ) as $byte) {
            $this->safeMap[$byte] = \chr($byte);
        }
    }

    /**
     * Get the name of this encoding scheme.
     *
     * Returns the string 'Q'.
     *
     * @return string
     */
    public function getName()
    {
        return 'Q';
    }

    /**
     * Takes an unencoded string and produces a QP encoded string from it.
     *
     * @param string $string          string to encode
     * @param int    $firstLineOffset optional
     * @param int    $maxLineLength   optional, 0 indicates the default of 76 chars
     *
     * @return string
     */
    public function encodeString($string, $firstLineOffset = 0, $maxLineLength = 0)
    {
        return str_replace([' ', '=20', "=\r\n"], ['_', '_', "\r\n"],
            parent::encodeString($string, $firstLineOffset, $maxLineLength)
        );
    }
}


================================================
FILE: lib/classes/Swift/Mime/HeaderEncoder.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Interface for all Header Encoding schemes.
 *
 * @author Chris Corbyn
 */
interface Swift_Mime_HeaderEncoder extends Swift_Encoder
{
    /**
     * Get the MIME name of this content encoding scheme.
     *
     * @return string
     */
    public function getName();
}


================================================
FILE: lib/classes/Swift/Mime/Headers/AbstractHeader.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * An abstract base MIME Header.
 *
 * @author     Chris Corbyn
 */
abstract class Swift_Mime_Headers_AbstractHeader implements Swift_Mime_Header
{
    const PHRASE_PATTERN = '(?:(?:(?:(?:(?:(?:(?:[ \t]*(?:\r\n))?[ \t])?(\((?:(?:(?:[ \t]*(?:\r\n))?[ \t])|(?:(?:[\x01-\x08\x0B\x0C\x0E-\x19\x7F]|[\x21-\x27\x2A-\x5B\x5D-\x7E])|(?:\\[\x00-\x08\x0B\x0C\x0E-\x7F])|(?1)))*(?:(?:[ \t]*(?:\r\n))?[ \t])?\)))*(?:(?:(?:(?:[ \t]*(?:\r\n))?[ \t])?(\((?:(?:(?:[ \t]*(?:\r\n))?[ \t])|(?:(?:[\x01-\x08\x0B\x0C\x0E-\x19\x7F]|[\x21-\x27\x2A-\x5B\x5D-\x7E])|(?:\\[\x00-\x08\x0B\x0C\x0E-\x7F])|(?1)))*(?:(?:[ \t]*(?:\r\n))?[ \t])?\)))|(?:(?:[ \t]*(?:\r\n))?[ \t])))?[a-zA-Z0-9!#\$%&\'\*\+\-\/=\?\^_`\{\}\|~]+(?:(?:(?:(?:[ \t]*(?:\r\n))?[ \t])?(\((?:(?:(?:[ \t]*(?:\r\n))?[ \t])|(?:(?:[\x01-\x08\x0B\x0C\x0E-\x19\x7F]|[\x21-\x27\x2A-\x5B\x5D-\x7E])|(?:\\[\x00-\x08\x0B\x0C\x0E-\x7F])|(?1)))*(?:(?:[ \t]*(?:\r\n))?[ \t])?\)))*(?:(?:(?:(?:[ \t]*(?:\r\n))?[ \t])?(\((?:(?:(?:[ \t]*(?:\r\n))?[ \t])|(?:(?:[\x01-\x08\x0B\x0C\x0E-\x19\x7F]|[\x21-\x27\x2A-\x5B\x5D-\x7E])|(?:\\[\x00-\x08\x0B\x0C\x0E-\x7F])|(?1)))*(?:(?:[ \t]*(?:\r\n))?[ \t])?\)))|(?:(?:[ \t]*(?:\r\n))?[ \t])))?)|(?:(?:(?:(?:(?:[ \t]*(?:\r\n))?[ \t])?(\((?:(?:(?:[ \t]*(?:\r\n))?[ \t])|(?:(?:[\x01-\x08\x0B\x0C\x0E-\x19\x7F]|[\x21-\x27\x2A-\x5B\x5D-\x7E])|(?:\\[\x00-\x08\x0B\x0C\x0E-\x7F])|(?1)))*(?:(?:[ \t]*(?:\r\n))?[ \t])?\)))*(?:(?:(?:(?:[ \t]*(?:\r\n))?[ \t])?(\((?:(?:(?:[ \t]*(?:\r\n))?[ \t])|(?:(?:[\x01-\x08\x0B\x0C\x0E-\x19\x7F]|[\x21-\x27\x2A-\x5B\x5D-\x7E])|(?:\\[\x00-\x08\x0B\x0C\x0E-\x7F])|(?1)))*(?:(?:[ \t]*(?:\r\n))?[ \t])?\)))|(?:(?:[ \t]*(?:\r\n))?[ \t])))?"((?:(?:[ \t]*(?:\r\n))?[ \t])?(?:(?:[\x01-\x08\x0B\x0C\x0E-\x19\x7F]|[\x21\x23-\x5B\x5D-\x7E])|(?:\\[\x00-\x08\x0B\x0C\x0E-\x7F])))*(?:(?:[ \t]*(?:\r\n))?[ \t])?"(?:(?:(?:(?:[ \t]*(?:\r\n))?[ \t])?(\((?:(?:(?:[ \t]*(?:\r\n))?[ \t])|(?:(?:[\x01-\x08\x0B\x0C\x0E-\x19\x7F]|[\x21-\x27\x2A-\x5B\x5D-\x7E])|(?:\\[\x00-\x08\x0B\x0C\x0E-\x7F])|(?1)))*(?:(?:[ \t]*(?:\r\n))?[ \t])?\)))*(?:(?:(?:(?:[ \t]*(?:\r\n))?[ \t])?(\((?:(?:(?:[ \t]*(?:\r\n))?[ \t])|(?:(?:[\x01-\x08\x0B\x0C\x0E-\x19\x7F]|[\x21-\x27\x2A-\x5B\x5D-\x7E])|(?:\\[\x00-\x08\x0B\x0C\x0E-\x7F])|(?1)))*(?:(?:[ \t]*(?:\r\n))?[ \t])?\)))|(?:(?:[ \t]*(?:\r\n))?[ \t])))?))+?)';

    /**
     * The name of this Header.
     *
     * @var string
     */
    private $name;

    /**
     * The Encoder used to encode this Header.
     *
     * @var Swift_Encoder
     */
    private $encoder;

    /**
     * The maximum length of a line in the header.
     *
     * @var int
     */
    private $lineLength = 78;

    /**
     * The language used in this Header.
     *
     * @var string
     */
    private $lang;

    /**
     * The character set of the text in this Header.
     *
     * @var string
     */
    private $charset = 'utf-8';

    /**
     * The value of this Header, cached.
     *
     * @var string
     */
    private $cachedValue = null;

    /**
     * Set the character set used in this Header.
     *
     * @param string $charset
     */
    public function setCharset($charset)
    {
        $this->clearCachedValueIf($charset != $this->charset);
        $this->charset = $charset;
        if (isset($this->encoder)) {
            $this->encoder->charsetChanged($charset);
        }
    }

    /**
     * Get the character set used in this Header.
     *
     * @return string
     */
    public function getCharset()
    {
        return $this->charset;
    }

    /**
     * Set the language used in this Header.
     *
     * For example, for US English, 'en-us'.
     * This can be unspecified.
     *
     * @param string $lang
     */
    public function setLanguage($lang)
    {
        $this->clearCachedValueIf($this->lang != $lang);
        $this->lang = $lang;
    }

    /**
     * Get the language used in this Header.
     *
     * @return string
     */
    public function getLanguage()
    {
        return $this->lang;
    }

    /**
     * Set the encoder used for encoding the header.
     */
    public function setEncoder(Swift_Mime_HeaderEncoder $encoder)
    {
        $this->encoder = $encoder;
        $this->setCachedValue(null);
    }

    /**
     * Get the encoder used for encoding this Header.
     *
     * @return Swift_Mime_HeaderEncoder
     */
    public function getEncoder()
    {
        return $this->encoder;
    }

    /**
     * Get the name of this header (e.g. charset).
     *
     * @return string
     */
    public function getFieldName()
    {
        return $this->name;
    }

    /**
     * Set the maximum length of lines in the header (excluding EOL).
     *
     * @param int $lineLength
     */
    public function setMaxLineLength($lineLength)
    {
        $this->clearCachedValueIf($this->lineLength != $lineLength);
        $this->lineLength = $lineLength;
    }

    /**
     * Get the maximum permitted length of lines in this Header.
     *
     * @return int
     */
    public function getMaxLineLength()
    {
        return $this->lineLength;
    }

    /**
     * Get this Header rendered as a RFC 2822 compliant string.
     *
     * @return string
     *
     * @throws Swift_RfcComplianceException
     */
    public function toString()
    {
        return $this->tokensToString($this->toTokens());
    }

    /**
     * Returns a string representation of this object.
     *
     * @return string
     *
     * @see toString()
     */
    public function __toString()
    {
        return $this->toString();
    }

    /**
     * Set the name of this Header field.
     *
     * @param string $name
     */
    protected function setFieldName($name)
    {
        $this->name = $name;
    }

    /**
     * Produces a compliant, formatted RFC 2822 'phrase' based on the string given.
     *
     * @param string $string  as displayed
     * @param string $charset of the text
     * @param bool   $shorten the first line to make remove for header name
     *
     * @return string
     */
    protected function createPhrase(Swift_Mime_Header $header, $string, $charset, Swift_Mime_HeaderEncoder $encoder = null, $shorten = false)
    {
        // Treat token as exactly what was given
        $phraseStr = $string;
        // If it's not valid

        if (!preg_match('/^'.self::PHRASE_PATTERN.'$/D', $phraseStr)) {
            // .. but it is just ascii text, try escaping some characters
            // and make it a quoted-string
            if (preg_match('/^[\x00-\x08\x0B\x0C\x0E-\x7F]*$/D', $phraseStr)) {
                $phraseStr = $this->escapeSpecials($phraseStr, ['"']);
                $phraseStr = '"'.$phraseStr.'"';
            } else {
                // ... otherwise it needs encoding
                // Determine space remaining on line if first line
                if ($shorten) {
                    $usedLength = \strlen($header->getFieldName().': ');
                } else {
                    $usedLength = 0;
                }
                $phraseStr = $this->encodeWords($header, $string, $usedLength);
            }
        }

        return $phraseStr;
    }

    /**
     * Escape special characters in a string (convert to quoted-pairs).
     *
     * @param string   $token
     * @param string[] $include additional chars to escape
     *
     * @return string
     */
    private function escapeSpecials($token, $include = [])
    {
        foreach (array_merge(['\\'], $include) as $char) {
            $token = str_replace($char, '\\'.$char, $token);
        }

        return $token;
    }

    /**
     * Encode needed word tokens within a string of input.
     *
     * @param string $input
     * @param string $usedLength optional
     *
     * @return string
     */
    protected function encodeWords(Swift_Mime_Header $header, $input, $usedLength = -1)
    {
        $value = '';

        $tokens = $this->getEncodableWordTokens($input);

        foreach ($tokens as $token) {
            // See RFC 2822, Sect 2.2 (really 2.2 ??)
            if ($this->tokenNeedsEncoding($token)) {
                // Don't encode starting WSP
                $firstChar = substr($token, 0, 1);
                switch ($firstChar) {
                    case ' ':
                    case "\t":
                        $value .= $firstChar;
                        $token = substr($token, 1);
                }

                if (-1 == $usedLength) {
                    $usedLength = \strlen($header->getFieldName().': ') + \strlen($value);
                }
                $value .= $this->getTokenAsEncodedWord($token, $usedLength);

                $header->setMaxLineLength(76); // Forcefully override
            } else {
                $value .= $token;
            }
        }

        return $value;
    }

    /**
     * Test if a token needs to be encoded or not.
     *
     * @param string $token
     *
     * @return bool
     */
    protected function tokenNeedsEncoding($token)
    {
        return preg_match('~[\x00-\x08\x10-\x19\x7F-\xFF\r\n]~', $token);
    }

    /**
     * Splits a string into tokens in blocks of words which can be encoded quickly.
     *
     * @param string $string
     *
     * @return string[]
     */
    protected function getEncodableWordTokens($string)
    {
        $tokens = [];

        $encodedToken = '';
        // Split at all whitespace boundaries
        foreach (preg_split('~(?=[\t ])~', $string ?? '') as $token) {
            if ($this->tokenNeedsEncoding($token)) {
                $encodedToken .= $token;
            } else {
                if (\strlen($encodedToken) > 0) {
                    $tokens[] = $encodedToken;
                    $encodedToken = '';
                }
                $tokens[] = $token;
            }
        }
        if (\strlen($encodedToken)) {
            $tokens[] = $encodedToken;
        }

        return $tokens;
    }

    /**
     * Get a token as an encoded word for safe insertion into headers.
     *
     * @param string $token           token to encode
     * @param int    $firstLineOffset optional
     *
     * @return string
     */
    protected function getTokenAsEncodedWord($token, $firstLineOffset = 0)
    {
        // Adjust $firstLineOffset to account for space needed for syntax
        $charsetDecl = $this->charset;
        if (isset($this->lang)) {
            $charsetDecl .= '*'.$this->lang;
        }
        $encodingWrapperLength = \strlen(
            '=?'.$charsetDecl.'?'.$this->encoder->getName().'??='
            );

        if ($firstLineOffset >= 75) {
            //Does this logic need to be here?
            $firstLineOffset = 0;
        }

        $encodedTextLines = explode("\r\n",
            $this->encoder->encodeString(
                $token, $firstLineOffset, 75 - $encodingWrapperLength, $this->charset
            ) ?? ''
        );

        if ('iso-2022-jp' !== strtolower($this->charset ?? '')) {
            // special encoding for iso-2022-jp using mb_encode_mimeheader
            foreach ($encodedTextLines as $lineNum => $line) {
                $encodedTextLines[$lineNum] = '=?'.$charsetDecl.
                    '?'.$this->encoder->getName().
                    '?'.$line.'?=';
            }
        }

        return implode("\r\n ", $encodedTextLines);
    }

    /**
     * Generates tokens from the given string which include CRLF as individual tokens.
     *
     * @param string $token
     *
     * @return string[]
     */
    protected function generateTokenLines($token)
    {
        return preg_split('~(\r\n)~', $token ?? '', -1, PREG_SPLIT_DELIM_CAPTURE);
    }

    /**
     * Set a value into the cache.
     *
     * @param string $value
     */
    protected function setCachedValue($value)
    {
        $this->cachedValue = $value;
    }

    /**
     * Get the value in the cache.
     *
     * @return string
     */
    protected function getCachedValue()
    {
        return $this->cachedValue;
    }

    /**
     * Clear the cached value if $condition is met.
     *
     * @param bool $condition
     */
    protected function clearCachedValueIf($condition)
    {
        if ($condition) {
            $this->setCachedValue(null);
        }
    }

    /**
     * Generate a list of all tokens in the final header.
     *
     * @param string $string The string to tokenize
     *
     * @return array An array of tokens as strings
     */
    protected function toTokens($string = null)
    {
        if (null === $string) {
            $string = $this->getFieldBody();
        }

        $tokens = [];

        // Generate atoms; split at all invisible boundaries followed by WSP
        foreach (preg_split('~(?=[ \t])~', $string ?? '') as $token) {
            $newTokens = $this->generateTokenLines($token);
            foreach ($newTokens as $newToken) {
                $tokens[] = $newToken;
            }
        }

        return $tokens;
    }

    /**
     * Takes an array of tokens which appear in the header and turns them into
     * an RFC 2822 compliant string, adding FWSP where needed.
     *
     * @param string[] $tokens
     *
     * @return string
     */
    private function tokensToString(array $tokens)
    {
        $lineCount = 0;
        $headerLines = [];
        $headerLines[] = $this->name.': ';
        $currentLine = &$headerLines[$lineCount++];

        // Build all tokens back into compliant header
        foreach ($tokens as $i => $token) {
            // Line longer than specified maximum or token was just a new line
            if (("\r\n" == $token) ||
                ($i > 0 && \strlen($currentLine.$token) > $this->lineLength)
                && 0 < \strlen($currentLine)) {
                $headerLines[] = '';
                $currentLine = &$headerLines[$lineCount++];
            }

            // Append token to the line
            if ("\r\n" != $token) {
                $currentLine .= $token;
            }
        }

        // Implode with FWS (RFC 2822, 2.2.3)
        return implode("\r\n", $headerLines)."\r\n";
    }

    /**
     * Make a deep copy of object.
     */
    public function __clone()
    {
        if ($this->encoder) {
            $this->encoder = clone $this->encoder;
        }
    }
}


================================================
FILE: lib/classes/Swift/Mime/Headers/DateHeader.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * A Date MIME Header for Swift Mailer.
 *
 * @author Chris Corbyn
 */
class Swift_Mime_Headers_DateHeader extends Swift_Mime_Headers_AbstractHeader
{
    /**
     * Date-time value of this Header.
     *
     * @var DateTimeImmutable
     */
    private $dateTime;

    /**
     * Creates a new DateHeader with $name.
     *
     * @param string $name of Header
     */
    public function __construct($name)
    {
        $this->setFieldName($name);
    }

    /**
     * Get the type of Header that this instance represents.
     *
     * @see TYPE_TEXT, TYPE_PARAMETERIZED, TYPE_MAILBOX
     * @see TYPE_DATE, TYPE_ID, TYPE_PATH
     *
     * @return int
     */
    public function getFieldType()
    {
        return self::TYPE_DATE;
    }

    /**
     * Set the model for the field body.
     *
     * @param DateTimeInterface $model
     */
    public function setFieldBodyModel($model)
    {
        $this->setDateTime($model);
    }

    /**
     * Get the model for the field body.
     *
     * @return DateTimeImmutable
     */
    public function getFieldBodyModel()
    {
        return $this->getDateTime();
    }

    /**
     * Get the date-time representing the Date in this Header.
     *
     * @return DateTimeImmutable
     */
    public function getDateTime()
    {
        return $this->dateTime;
    }

    /**
     * Set the date-time of the Date in this Header.
     *
     * If a DateTime instance is provided, it is converted to DateTimeImmutable.
     */
    public function setDateTime(DateTimeInterface $dateTime)
    {
        $this->clearCachedValueIf($this->getCachedValue() != $dateTime->format(DateTime::RFC2822));
        if ($dateTime instanceof DateTime) {
            $immutable = new DateTimeImmutable('@'.$dateTime->getTimestamp());
            $dateTime = $immutable->setTimezone($dateTime->getTimezone());
        }
        $this->dateTime = $dateTime;
    }

    /**
     * Get the string value of the body in this Header.
     *
     * This is not necessarily RFC 2822 compliant since folding white space will
     * not be added at this stage (see {@link toString()} for that).
     *
     * @see toString()
     *
     * @return string
     */
    public function getFieldBody()
    {
        if (!$this->getCachedValue()) {
            if (isset($this->dateTime)) {
                $this->setCachedValue($this->dateTime->format(DateTime::RFC2822));
            }
        }

        return $this->getCachedValue();
    }
}


================================================
FILE: lib/classes/Swift/Mime/Headers/IdentificationHeader.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

use Egulias\EmailValidator\EmailValidator;
use Egulias\EmailValidator\Validation\MessageIDValidation;
use Egulias\EmailValidator\Validation\RFCValidation;

/**
 * An ID MIME Header for something like Message-ID or Content-ID.
 *
 * @author Chris Corbyn
 */
class Swift_Mime_Headers_IdentificationHeader extends Swift_Mime_Headers_AbstractHeader
{
    /**
     * The IDs used in the value of this Header.
     *
     * This may hold multiple IDs or just a single ID.
     *
     * @var string[]
     */
    private $ids = [];

    /**
     * The strict EmailValidator.
     *
     * @var EmailValidator
     */
    private $emailValidator;

    private $addressEncoder;

    /**
     * Creates a new IdentificationHeader with the given $name and $id.
     *
     * @param string $name
     */
    public function __construct($name, EmailValidator $emailValidator, Swift_AddressEncoder $addressEncoder = null)
    {
        $this->setFieldName($name);
        $this->emailValidator = $emailValidator;
        $this->addressEncoder = $addressEncoder ?? new Swift_AddressEncoder_IdnAddressEncoder();
    }

    /**
     * Get the type of Header that this instance represents.
     *
     * @see TYPE_TEXT, TYPE_PARAMETERIZED, TYPE_MAILBOX
     * @see TYPE_DATE, TYPE_ID, TYPE_PATH
     *
     * @return int
     */
    public function getFieldType()
    {
        return self::TYPE_ID;
    }

    /**
     * Set the model for the field body.
     *
     * This method takes a string ID, or an array of IDs.
     *
     * @param mixed $model
     *
     * @throws Swift_RfcComplianceException
     */
    public function setFieldBodyModel($model)
    {
        $this->setId($model);
    }

    /**
     * Get the model for the field body.
     *
     * This method returns an array of IDs
     *
     * @return array
     */
    public function getFieldBodyModel()
    {
        return $this->getIds();
    }

    /**
     * Set the ID used in the value of this header.
     *
     * @param string|array $id
     *
     * @throws Swift_RfcComplianceException
     */
    public function setId($id)
    {
        $this->setIds(\is_array($id) ? $id : [$id]);
    }

    /**
     * Get the ID used in the value of this Header.
     *
     * If multiple IDs are set only the first is returned.
     *
     * @return string
     */
    public function getId()
    {
        if (\count($this->ids) > 0) {
            return $this->ids[0];
        }
    }

    /**
     * Set a collection of IDs to use in the value of this Header.
     *
     * @param string[] $ids
     *
     * @throws Swift_RfcComplianceException
     */
    public function setIds(array $ids)
    {
        $actualIds = [];

        foreach ($ids as $id) {
            $this->assertValidId($id);
            $actualIds[] = $id;
        }

        $this->clearCachedValueIf($this->ids != $actualIds);
        $this->ids = $actualIds;
    }

    /**
     * Get the list of IDs used in this Header.
     *
     * @return string[]
     */
    public function getIds()
    {
        return $this->ids;
    }

    /**
     * Get the string value of the body in this Header.
     *
     * This is not necessarily RFC 2822 compliant since folding white space will
     * not be added at this stage (see {@see toString()} for that).
     *
     * @see toString()
     *
     * @throws Swift_RfcComplianceException
     *
     * @return string
     */
    public function getFieldBody()
    {
        if (!$this->getCachedValue()) {
            $angleAddrs = [];

            foreach ($this->ids as $id) {
                $angleAddrs[] = '<'.$this->addressEncoder->encodeString($id).'>';
            }

            $this->setCachedValue(implode(' ', $angleAddrs));
        }

        return $this->getCachedValue();
    }

    /**
     * Throws an Exception if the id passed does not comply with RFC 2822.
     *
     * @param string $id
     *
     * @throws Swift_RfcComplianceException
     */
    private function assertValidId($id)
    {
        $emailValidation = class_exists(MessageIDValidation::class) ? new MessageIDValidation() : new RFCValidation();

        if (!$this->emailValidator->isValid($id, $emailValidation)) {
            throw new Swift_RfcComplianceException('Invalid ID given <'.$id.'>');
        }
    }
}


================================================
FILE: lib/classes/Swift/Mime/Headers/MailboxHeader.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

use Egulias\EmailValidator\EmailValidator;
use Egulias\EmailValidator\Validation\RFCValidation;

/**
 * A Mailbox Address MIME Header for something like From or Sender.
 *
 * @author Chris Corbyn
 */
class Swift_Mime_Headers_MailboxHeader extends Swift_Mime_Headers_AbstractHeader
{
    /**
     * The mailboxes used in this Header.
     *
     * @var string[]
     */
    private $mailboxes = [];

    /**
     * The strict EmailValidator.
     *
     * @var EmailValidator
     */
    private $emailValidator;

    private $addressEncoder;

    /**
     * Creates a new MailboxHeader with $name.
     *
     * @param string $name of Header
     */
    public function __construct($name, Swift_Mime_HeaderEncoder $encoder, EmailValidator $emailValidator, Swift_AddressEncoder $addressEncoder = null)
    {
        $this->setFieldName($name);
        $this->setEncoder($encoder);
        $this->emailValidator = $emailValidator;
        $this->addressEncoder = $addressEncoder ?? new Swift_AddressEncoder_IdnAddressEncoder();
    }

    /**
     * Get the type of Header that this instance represents.
     *
     * @see TYPE_TEXT, TYPE_PARAMETERIZED, TYPE_MAILBOX
     * @see TYPE_DATE, TYPE_ID, TYPE_PATH
     *
     * @return int
     */
    public function getFieldType()
    {
        return self::TYPE_MAILBOX;
    }

    /**
     * Set the model for the field body.
     *
     * This method takes a string, or an array of addresses.
     *
     * @param mixed $model
     *
     * @throws Swift_RfcComplianceException
     */
    public function setFieldBodyModel($model)
    {
        $this->setNameAddresses($model);
    }

    /**
     * Get the model for the field body.
     *
     * This method returns an associative array like {@link getNameAddresses()}
     *
     * @throws Swift_RfcComplianceException
     *
     * @return array
     */
    public function getFieldBodyModel()
    {
        return $this->getNameAddresses();
    }

    /**
     * Set a list of mailboxes to be shown in this Header.
     *
     * The mailboxes can be a simple array of addresses, or an array of
     * key=>value pairs where (email => personalName).
     * Example:
     * <code>
     * <?php
     * //Sets two mailboxes in the Header, one with a personal name
     * $header->setNameAddresses(array(
     *  'chris@swiftmailer.org' => 'Chris Corbyn',
     *  'mark@swiftmailer.org' //No associated personal name
     *  ));
     * ?>
     * </code>
     *
     * @see __construct()
     * @see setAddresses()
     * @see setValue()
     *
     * @param string|string[] $mailboxes
     *
     * @throws Swift_RfcComplianceException
     */
    public function setNameAddresses($mailboxes)
    {
        $this->mailboxes = $this->normalizeMailboxes((array) $mailboxes);
        $this->setCachedValue(null); //Clear any cached value
    }

    /**
     * Get the full mailbox list of this Header as an array of valid RFC 2822 strings.
     *
     * Example:
     * <code>
     * <?php
     * $header = new Swift_Mime_Headers_MailboxHeader('From',
     *  array('chris@swiftmailer.org' => 'Chris Corbyn',
     *  'mark@swiftmailer.org' => 'Mark Corbyn')
     *  );
     * print_r($header->getNameAddressStrings());
     * // array (
     * // 0 => Chris Corbyn <chris@swiftmailer.org>,
     * // 1 => Mark Corbyn <mark@swiftmailer.org>
     * // )
     * ?>
     * </code>
     *
     * @see getNameAddresses()
     * @see toString()
     *
     * @throws Swift_RfcComplianceException
     *
     * @return string[]
     */
    public function getNameAddressStrings()
    {
        return $this->createNameAddressStrings($this->getNameAddresses());
    }

    /**
     * Get all mailboxes in this Header as key=>value pairs.
     *
     * The key is the address and the value is the name (or null if none set).
     * Example:
     * <code>
     * <?php
     * $header = new Swift_Mime_Headers_MailboxHeader('From',
     *  array('chris@swiftmailer.org' => 'Chris Corbyn',
     *  'mark@swiftmailer.org' => 'Mark Corbyn')
     *  );
     * print_r($header->getNameAddresses());
     * // array (
     * // chris@swiftmailer.org => Chris Corbyn,
     * // mark@swiftmailer.org => Mark Corbyn
     * // )
     * ?>
     * </code>
     *
     * @see getAddresses()
     * @see getNameAddressStrings()
     *
     * @return string[]
     */
    public function getNameAddresses()
    {
        return $this->mailboxes;
    }

    /**
     * Makes this Header represent a list of plain email addresses with no names.
     *
     * Example:
     * <code>
     * <?php
     * //Sets three email addresses as the Header data
     * $header->setAddresses(
     *  array('one@domain.tld', 'two@domain.tld', 'three@domain.tld')
     *  );
     * ?>
     * </code>
     *
     * @see setNameAddresses()
     * @see setValue()
     *
     * @param string[] $addresses
     *
     * @throws Swift_RfcComplianceException
     */
    public function setAddresses($addresses)
    {
        $this->setNameAddresses(array_values((array) $addresses));
    }

    /**
     * Get all email addresses in this Header.
     *
     * @see getNameAddresses()
     *
     * @return string[]
     */
    public function getAddresses()
    {
        return array_keys($this->mailboxes);
    }

    /**
     * Remove one or more addresses from this Header.
     *
     * @param string|string[] $addresses
     */
    public function removeAddresses($addresses)
    {
        $this->setCachedValue(null);
        foreach ((array) $addresses as $address) {
            unset($this->mailboxes[$address]);
        }
    }

    /**
     * Get the string value of the body in this Header.
     *
     * This is not necessarily RFC 2822 compliant since folding white space will
     * not be added at this stage (see {@link toString()} for that).
     *
     * @see toString()
     *
     * @throws Swift_RfcComplianceException
     *
     * @return string
     */
    public function getFieldBody()
    {
        // Compute the string value of the header only if needed
        if (null === $this->getCachedValue()) {
            $this->setCachedValue($this->createMailboxListString($this->mailboxes));
        }

        return $this->getCachedValue();
    }

    /**
     * Normalizes a user-input list of mailboxes into consistent key=>value pairs.
     *
     * @param string[] $mailboxes
     *
     * @return string[]
     */
    protected function normalizeMailboxes(array $mailboxes)
    {
        $actualMailboxes = [];

        foreach ($mailboxes as $key => $value) {
            if (\is_string($key)) {
                //key is email addr
                $address = $key;
                $name = $value;
            } else {
                $address = $value;
                $name = null;
            }
            $this->assertValidAddress($address);
            $actualMailboxes[$address] = $name;
        }

        return $actualMailboxes;
    }

    /**
     * Produces a compliant, formatted display-name based on the string given.
     *
     * @param string $displayName as displayed
     * @param bool   $shorten     the first line to make remove for header name
     *
     * @return string
     */
    protected function createDisplayNameString($displayName, $shorten = false)
    {
        return $this->createPhrase($this, $displayName, $this->getCharset(), $this->getEncoder(), $shorten);
    }

    /**
     * Creates a string form of all the mailboxes in the passed array.
     *
     * @param string[] $mailboxes
     *
     * @throws Swift_RfcComplianceException
     *
     * @return string
     */
    protected function createMailboxListString(array $mailboxes)
    {
        return implode(', ', $this->createNameAddressStrings($mailboxes));
    }

    /**
     * Redefine the encoding requirements for mailboxes.
     *
     * All "specials" must be encoded as the full header value will not be quoted
     *
     * @see RFC 2822 3.2.1
     *
     * @param string $token
     *
     * @return bool
     */
    protected function tokenNeedsEncoding($token)
    {
        return preg_match('/[()<>\[\]:;@\,."]/', $token) || parent::tokenNeedsEncoding($token);
    }

    /**
     * Return an array of strings conforming the the name-addr spec of RFC 2822.
     *
     * @param string[] $mailboxes
     *
     * @return string[]
     */
    private function createNameAddressStrings(array $mailboxes)
    {
        $strings = [];

        foreach ($mailboxes as $email => $name) {
            $mailboxStr = $this->addressEncoder->encodeString($email);
            if (null !== $name) {
                $nameStr = $this->createDisplayNameString($name, empty($strings));
                $mailboxStr = $nameStr.' <'.$mailboxStr.'>';
            }
            $strings[] = $mailboxStr;
        }

        return $strings;
    }

    /**
     * Throws an Exception if the address passed does not comply with RFC 2822.
     *
     * @param string $address
     *
     * @throws Swift_RfcComplianceException if invalid
     */
    private function assertValidAddress($address)
    {
        if (!$this->emailValidator->isValid($address, new RFCValidation())) {
            throw new Swift_RfcComplianceException('Address in mailbox given ['.$address.'] does not comply with RFC 2822, 3.6.2.');
        }
    }
}


================================================
FILE: lib/classes/Swift/Mime/Headers/OpenDKIMHeader.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * An OpenDKIM Specific Header using only raw header datas without encoding.
 *
 * @author De Cock Xavier <xdecock@gmail.com>
 *
 * @deprecated since SwiftMailer 6.1.0; use Swift_Signers_DKIMSigner instead.
 */
class Swift_Mime_Headers_OpenDKIMHeader implements Swift_Mime_Header
{
    /**
     * The value of this Header.
     *
     * @var string
     */
    private $value;

    /**
     * The name of this Header.
     *
     * @var string
     */
    private $fieldName;

    /**
     * @param string $name
     */
    public function __construct($name)
    {
        $this->fieldName = $name;
    }

    /**
     * Get the type of Header that this instance represents.
     *
     * @see TYPE_TEXT, TYPE_PARAMETERIZED, TYPE_MAILBOX
     * @see TYPE_DATE, TYPE_ID, TYPE_PATH
     *
     * @return int
     */
    public function getFieldType()
    {
        return self::TYPE_TEXT;
    }

    /**
     * Set the model for the field body.
     *
     * This method takes a string for the field value.
     *
     * @param string $model
     */
    public function setFieldBodyModel($model)
    {
        $this->setValue($model);
    }

    /**
     * Get the model for the field body.
     *
     * This method returns a string.
     *
     * @return string
     */
    public function getFieldBodyModel()
    {
        return $this->getValue();
    }

    /**
     * Get the (unencoded) value of this header.
     *
     * @return string
     */
    public function getValue()
    {
        return $this->value;
    }

    /**
     * Set the (unencoded) value of this header.
     *
     * @param string $value
     */
    public function setValue($value)
    {
        $this->value = $value;
    }

    /**
     * Get the value of this header prepared for rendering.
     *
     * @return string
     */
    public function getFieldBody()
    {
        return $this->value;
    }

    /**
     * Get this Header rendered as a RFC 2822 compliant string.
     *
     * @return string
     */
    public function toString()
    {
        return $this->fieldName.': '.$this->value."\r\n";
    }

    /**
     * Set the Header FieldName.
     *
     * @see Swift_Mime_Header::getFieldName()
     */
    public function getFieldName()
    {
        return $this->fieldName;
    }

    /**
     * Ignored.
     */
    public function setCharset($charset)
    {
    }
}


================================================
FILE: lib/classes/Swift/Mime/Headers/ParameterizedHeader.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * An abstract base MIME Header.
 *
 * @author Chris Corbyn
 */
class Swift_Mime_Headers_ParameterizedHeader extends Swift_Mime_Headers_UnstructuredHeader
{
    /**
     * RFC 2231's definition of a token.
     *
     * @var string
     */
    const TOKEN_REGEX = '(?:[\x21\x23-\x27\x2A\x2B\x2D\x2E\x30-\x39\x41-\x5A\x5E-\x7E]+)';

    /**
     * The Encoder used to encode the parameters.
     *
     * @var Swift_Encoder
     */
    private $paramEncoder;

    /**
     * The parameters as an associative array.
     *
     * @var string[]
     */
    private $params = [];

    /**
     * Creates a new ParameterizedHeader with $name.
     *
     * @param string $name
     */
    public function __construct($name, Swift_Mime_HeaderEncoder $encoder, Swift_Encoder $paramEncoder = null)
    {
        parent::__construct($name, $encoder);
        $this->paramEncoder = $paramEncoder;
    }

    /**
     * Get the type of Header that this instance represents.
     *
     * @see TYPE_TEXT, TYPE_PARAMETERIZED, TYPE_MAILBOX
     * @see TYPE_DATE, TYPE_ID, TYPE_PATH
     *
     * @return int
     */
    public function getFieldType()
    {
        return self::TYPE_PARAMETERIZED;
    }

    /**
     * Set the character set used in this Header.
     *
     * @param string $charset
     */
    public function setCharset($charset)
    {
        parent::setCharset($charset);
        if (isset($this->paramEncoder)) {
            $this->paramEncoder->charsetChanged($charset);
        }
    }

    /**
     * Set the value of $parameter.
     *
     * @param string $parameter
     * @param string $value
     */
    public function setParameter($parameter, $value)
    {
        $this->setParameters(array_merge($this->getParameters(), [$parameter => $value]));
    }

    /**
     * Get the value of $parameter.
     *
     * @param string $parameter
     *
     * @return string
     */
    public function getParameter($parameter)
    {
        $params = $this->getParameters();

        return $params[$parameter] ?? null;
    }

    /**
     * Set an associative array of parameter names mapped to values.
     *
     * @param string[] $parameters
     */
    public function setParameters(array $parameters)
    {
        $this->clearCachedValueIf($this->params != $parameters);
        $this->params = $parameters;
    }

    /**
     * Returns an associative array of parameter names mapped to values.
     *
     * @return string[]
     */
    public function getParameters()
    {
        return $this->params;
    }

    /**
     * Get the value of this header prepared for rendering.
     *
     * @return string
     */
    public function getFieldBody() //TODO: Check caching here
    {
        $body = parent::getFieldBody();
        foreach ($this->params as $name => $value) {
            if (null !== $value) {
                // Add the parameter
                $body .= '; '.$this->createParameter($name, $value);
            }
        }

        return $body;
    }

    /**
     * Generate a list of all tokens in the final header.
     *
     * This doesn't need to be overridden in theory, but it is for implementation
     * reasons to prevent potential breakage of attributes.
     *
     * @param string $string The string to tokenize
     *
     * @return array An array of tokens as strings
     */
    protected function toTokens($string = null)
    {
        $tokens = parent::toTokens(parent::getFieldBody());

        // Try creating any parameters
        foreach ($this->params as $name => $value) {
            if (null !== $value) {
                // Add the semi-colon separator
                $tokens[\count($tokens) - 1] .= ';';
                $tokens = array_merge($tokens, $this->generateTokenLines(
                    ' '.$this->createParameter($name, $value)
                    ));
            }
        }

        return $tokens;
    }

    /**
     * Render a RFC 2047 compliant header parameter from the $name and $value.
     *
     * @param string $name
     * @param string $value
     *
     * @return string
     */
    private function createParameter($name, $value)
    {
        $origValue = $value;

        $encoded = false;
        // Allow room for parameter name, indices, "=" and DQUOTEs
        $maxValueLength = $this->getMaxLineLength() - \strlen($name.'=*N"";') - 1;
        $firstLineOffset = 0;

        // If it's not already a valid parameter value...
        if (!preg_match('/^'.self::TOKEN_REGEX.'$/D', $value)) {
            // TODO: text, or something else??
            // ... and it's not ascii
            if (!preg_match('/^[\x00-\x08\x0B\x0C\x0E-\x7F]*$/D', $value)) {
                $encoded = true;
                // Allow space for the indices, charset and language
                $maxValueLength = $this->getMaxLineLength() - \strlen($name.'*N*="";') - 1;
                $firstLineOffset = \strlen(
                    $this->getCharset()."'".$this->getLanguage()."'"
                    );
            }
        }

        // Encode if we need to
        if ($encoded || \strlen($value) > $maxValueLength) {
            if (isset($this->paramEncoder)) {
                $value = $this->paramEncoder->encodeString(
                    $origValue, $firstLineOffset, $maxValueLength, $this->getCharset()
                    );
            } else {
                // We have to go against RFC 2183/2231 in some areas for interoperability
                $value = $this->getTokenAsEncodedWord($origValue);
                $encoded = false;
            }
        }

        $valueLines = isset($this->paramEncoder) ? explode("\r\n", $value) : [$value];

        // Need to add indices
        if (\count($valueLines) > 1) {
            $paramLines = [];
            foreach ($valueLines as $i => $line) {
                $paramLines[] = $name.'*'.$i.
                    $this->getEndOfParameterValue($line, true, 0 == $i);
            }

            return implode(";\r\n ", $paramLines);
        } else {
            return $name.$this->getEndOfParameterValue(
                $valueLines[0], $encoded, true
                );
        }
    }

    /**
     * Returns the parameter value from the "=" and beyond.
     *
     * @param string $value     to append
     * @param bool   $encoded
     * @param bool   $firstLine
     *
     * @return string
     */
    private function getEndOfParameterValue($value, $encoded = false, $firstLine = false)
    {
        if (!preg_match('/^'.self::TOKEN_REGEX.'$/D', $value)) {
            $value = '"'.$value.'"';
        }
        $prepend = '=';
        if ($encoded) {
            $prepend = '*=';
            if ($firstLine) {
                $prepend = '*='.$this->getCharset()."'".$this->getLanguage().
                    "'";
            }
        }

        return $prepend.$value;
    }
}


================================================
FILE: lib/classes/Swift/Mime/Headers/PathHeader.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

use Egulias\EmailValidator\EmailValidator;
use Egulias\EmailValidator\Validation\RFCValidation;

/**
 * A Path Header in Swift Mailer, such a Return-Path.
 *
 * @author Chris Corbyn
 */
class Swift_Mime_Headers_PathHeader extends Swift_Mime_Headers_AbstractHeader
{
    /**
     * The address in this Header (if specified).
     *
     * @var string
     */
    private $address;

    /**
     * The strict EmailValidator.
     *
     * @var EmailValidator
     */
    private $emailValidator;

    private $addressEncoder;

    /**
     * Creates a new PathHeader with the given $name.
     *
     * @param string $name
     */
    public function __construct($name, EmailValidator $emailValidator, Swift_AddressEncoder $addressEncoder = null)
    {
        $this->setFieldName($name);
        $this->emailValidator = $emailValidator;
        $this->addressEncoder = $addressEncoder ?? new Swift_AddressEncoder_IdnAddressEncoder();
    }

    /**
     * Get the type of Header that this instance represents.
     *
     * @see TYPE_TEXT, TYPE_PARAMETERIZED, TYPE_MAILBOX
     * @see TYPE_DATE, TYPE_ID, TYPE_PATH
     *
     * @return int
     */
    public function getFieldType()
    {
        return self::TYPE_PATH;
    }

    /**
     * Set the model for the field body.
     * This method takes a string for an address.
     *
     * @param string $model
     *
     * @throws Swift_RfcComplianceException
     */
    public function setFieldBodyModel($model)
    {
        $this->setAddress($model);
    }

    /**
     * Get the model for the field body.
     * This method returns a string email address.
     *
     * @return mixed
     */
    public function getFieldBodyModel()
    {
        return $this->getAddress();
    }

    /**
     * Set the Address which should appear in this Header.
     *
     * @param string $address
     *
     * @throws Swift_RfcComplianceException
     */
    public function setAddress($address)
    {
        if (null === $address) {
            $this->address = null;
        } elseif ('' == $address) {
            $this->address = '';
        } else {
            $this->assertValidAddress($address);
            $this->address = $address;
        }
        $this->setCachedValue(null);
    }

    /**
     * Get the address which is used in this Header (if any).
     *
     * Null is returned if no address is set.
     *
     * @return string
     */
    public function getAddress()
    {
        return $this->address;
    }

    /**
     * Get the string value of the body in this Header.
     *
     * This is not necessarily RFC 2822 compliant since folding white space will
     * not be added at this stage (see {@link toString()} for that).
     *
     * @see toString()
     *
     * @return string
     */
    public function getFieldBody()
    {
        if (!$this->getCachedValue()) {
            if (isset($this->address)) {
                $address = $this->addressEncoder->encodeString($this->address);
                $this->setCachedValue('<'.$address.'>');
            }
        }

        return $this->getCachedValue();
    }

    /**
     * Throws an Exception if the address passed does not comply with RFC 2822.
     *
     * @param string $address
     *
     * @throws Swift_RfcComplianceException If address is invalid
     */
    private function assertValidAddress($address)
    {
        if (!$this->emailValidator->isValid($address, new RFCValidation())) {
            throw new Swift_RfcComplianceException('Address set in PathHeader does not comply with addr-spec of RFC 2822.');
        }
    }
}


================================================
FILE: lib/classes/Swift/Mime/Headers/UnstructuredHeader.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * A Simple MIME Header.
 *
 * @author Chris Corbyn
 */
class Swift_Mime_Headers_UnstructuredHeader extends Swift_Mime_Headers_AbstractHeader
{
    /**
     * The value of this Header.
     *
     * @var string
     */
    private $value;

    /**
     * Creates a new SimpleHeader with $name.
     *
     * @param string $name
     */
    public function __construct($name, Swift_Mime_HeaderEncoder $encoder)
    {
        $this->setFieldName($name);
        $this->setEncoder($encoder);
    }

    /**
     * Get the type of Header that this instance represents.
     *
     * @see TYPE_TEXT, TYPE_PARAMETERIZED, TYPE_MAILBOX
     * @see TYPE_DATE, TYPE_ID, TYPE_PATH
     *
     * @return int
     */
    public function getFieldType()
    {
        return self::TYPE_TEXT;
    }

    /**
     * Set the model for the field body.
     *
     * This method takes a string for the field value.
     *
     * @param string $model
     */
    public function setFieldBodyModel($model)
    {
        $this->setValue($model);
    }

    /**
     * Get the model for the field body.
     *
     * This method returns a string.
     *
     * @return string
     */
    public function getFieldBodyModel()
    {
        return $this->getValue();
    }

    /**
     * Get the (unencoded) value of this header.
     *
     * @return string
     */
    public function getValue()
    {
        return $this->value;
    }

    /**
     * Set the (unencoded) value of this header.
     *
     * @param string $value
     */
    public function setValue($value)
    {
        $this->clearCachedValueIf($this->value != $value);
        $this->value = $value;
    }

    /**
     * Get the value of this header prepared for rendering.
     *
     * @return string
     */
    public function getFieldBody()
    {
        if (!$this->getCachedValue()) {
            $this->setCachedValue(
                $this->encodeWords($this, $this->value)
                );
        }

        return $this->getCachedValue();
    }
}


================================================
FILE: lib/classes/Swift/Mime/IdGenerator.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Message ID generator.
 */
class Swift_Mime_IdGenerator implements Swift_IdGenerator
{
    private $idRight;

    /**
     * @param string $idRight
     */
    public function __construct($idRight)
    {
        $this->idRight = $idRight;
    }

    /**
     * Returns the right-hand side of the "@" used in all generated IDs.
     *
     * @return string
     */
    public function getIdRight()
    {
        return $this->idRight;
    }

    /**
     * Sets the right-hand side of the "@" to use in all generated IDs.
     *
     * @param string $idRight
     */
    public function setIdRight($idRight)
    {
        $this->idRight = $idRight;
    }

    /**
     * @return string
     */
    public function generateId()
    {
        // 32 hex values for the left part
        return bin2hex(random_bytes(16)).'@'.$this->idRight;
    }
}


================================================
FILE: lib/classes/Swift/Mime/MimePart.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * A MIME part, in a multipart message.
 *
 * @author Chris Corbyn
 */
class Swift_Mime_MimePart extends Swift_Mime_SimpleMimeEntity
{
    /** The format parameter last specified by the user */
    protected $userFormat;

    /** The charset last specified by the user */
    protected $userCharset;

    /** The delsp parameter last specified by the user */
    protected $userDelSp;

    /** The nesting level of this MimePart */
    private $nestingLevel = self::LEVEL_ALTERNATIVE;

    /**
     * Create a new MimePart with $headers, $encoder and $cache.
     *
     * @param string $charset
     */
    public function __construct(Swift_Mime_SimpleHeaderSet $headers, Swift_Mime_ContentEncoder $encoder, Swift_KeyCache $cache, Swift_IdGenerator $idGenerator, $charset = null)
    {
        parent::__construct($headers, $encoder, $cache, $idGenerator);
        $this->setContentType('text/plain');
        if (null !== $charset) {
            $this->setCharset($charset);
        }
    }

    /**
     * Set the body of this entity, either as a string, or as an instance of
     * {@link Swift_OutputByteStream}.
     *
     * @param mixed  $body
     * @param string $contentType optional
     * @param string $charset     optional
     *
     * @return $this
     */
    public function setBody($body, $contentType = null, $charset = null)
    {
        if (isset($charset)) {
            $this->setCharset($charset);
        }
        $body = $this->convertString($body);

        parent::setBody($body, $contentType);

        return $this;
    }

    /**
     * Get the character set of this entity.
     *
     * @return string
     */
    public function getCharset()
    {
        return $this->getHeaderParameter('Content-Type', 'charset');
    }

    /**
     * Set the character set of this entity.
     *
     * @param string $charset
     *
     * @return $this
     */
    public function setCharset($charset)
    {
        $this->setHeaderParameter('Content-Type', 'charset', $charset);
        if ($charset !== $this->userCharset) {
            $this->clearCache();
        }
        $this->userCharset = $charset;
        parent::charsetChanged($charset);

        return $this;
    }

    /**
     * Get the format of this entity (i.e. flowed or fixed).
     *
     * @return string
     */
    public function getFormat()
    {
        return $this->getHeaderParameter('Content-Type', 'format');
    }

    /**
     * Set the format of this entity (flowed or fixed).
     *
     * @param string $format
     *
     * @return $this
     */
    public function setFormat($format)
    {
        $this->setHeaderParameter('Content-Type', 'format', $format);
        $this->userFormat = $format;

        return $this;
    }

    /**
     * Test if delsp is being used for this entity.
     *
     * @return bool
     */
    public function getDelSp()
    {
        return 'yes' === $this->getHeaderParameter('Content-Type', 'delsp');
    }

    /**
     * Turn delsp on or off for this entity.
     *
     * @param bool $delsp
     *
     * @return $this
     */
    public function setDelSp($delsp = true)
    {
        $this->setHeaderParameter('Content-Type', 'delsp', $delsp ? 'yes' : null);
        $this->userDelSp = $delsp;

        return $this;
    }

    /**
     * Get the nesting level of this entity.
     *
     * @see LEVEL_TOP, LEVEL_ALTERNATIVE, LEVEL_MIXED, LEVEL_RELATED
     *
     * @return int
     */
    public function getNestingLevel()
    {
        return $this->nestingLevel;
    }

    /**
     * Receive notification that the charset has changed on this document, or a
     * parent document.
     *
     * @param string $charset
     */
    public function charsetChanged($charset)
    {
        $this->setCharset($charset);
    }

    /** Fix the content-type and encoding of this entity */
    protected function fixHeaders()
    {
        parent::fixHeaders();
        if (\count($this->getChildren())) {
            $this->setHeaderParameter('Content-Type', 'charset', null);
            $this->setHeaderParameter('Content-Type', 'format', null);
            $this->setHeaderParameter('Content-Type', 'delsp', null);
        } else {
            $this->setCharset($this->userCharset);
            $this->setFormat($this->userFormat);
            $this->setDelSp($this->userDelSp);
        }
    }

    /** Set the nesting level of this entity */
    protected function setNestingLevel($level)
    {
        $this->nestingLevel = $level;
    }

    /** Encode charset when charset is not utf-8 */
    protected function convertString($string)
    {
        $charset = strtolower($this->getCharset() ?? '');
        if (!\in_array($charset, ['utf-8', 'iso-8859-1', 'iso-8859-15', ''])) {
            return mb_convert_encoding($string, $charset, 'utf-8');
        }

        return $string;
    }
}


================================================
FILE: lib/classes/Swift/Mime/SimpleHeaderFactory.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

use Egulias\EmailValidator\EmailValidator;

/**
 * Creates MIME headers.
 *
 * @author Chris Corbyn
 */
class Swift_Mime_SimpleHeaderFactory implements Swift_Mime_CharsetObserver
{
    /** The HeaderEncoder used by these headers */
    private $encoder;

    /** The Encoder used by parameters */
    private $paramEncoder;

    /** Strict EmailValidator */
    private $emailValidator;

    /** The charset of created Headers */
    private $charset;

    /** Swift_AddressEncoder */
    private $addressEncoder;

    /**
     * Creates a new SimpleHeaderFactory using $encoder and $paramEncoder.
     *
     * @param string|null $charset
     */
    public function __construct(Swift_Mime_HeaderEncoder $encoder, Swift_Encoder $paramEncoder, EmailValidator $emailValidator, $charset = null, Swift_AddressEncoder $addressEncoder = null)
    {
        $this->encoder = $encoder;
        $this->paramEncoder = $paramEncoder;
        $this->emailValidator = $emailValidator;
        $this->charset = $charset;
        $this->addressEncoder = $addressEncoder ?? new Swift_AddressEncoder_IdnAddressEncoder();
    }

    /**
     * Create a new Mailbox Header with a list of $addresses.
     *
     * @param string            $name
     * @param array|string|null $addresses
     *
     * @return Swift_Mime_Header
     */
    public function createMailboxHeader($name, $addresses = null)
    {
        $header = new Swift_Mime_Headers_MailboxHeader($name, $this->encoder, $this->emailValidator, $this->addressEncoder);
        if (isset($addresses)) {
            $header->setFieldBodyModel($addresses);
        }
        $this->setHeaderCharset($header);

        return $header;
    }

    /**
     * Create a new Date header using $dateTime.
     *
     * @param string $name
     *
     * @return Swift_Mime_Header
     */
    public function createDateHeader($name, DateTimeInterface $dateTime = null)
    {
        $header = new Swift_Mime_Headers_DateHeader($name);
        if (isset($dateTime)) {
            $header->setFieldBodyModel($dateTime);
        }
        $this->setHeaderCharset($header);

        return $header;
    }

    /**
     * Create a new basic text header with $name and $value.
     *
     * @param string $name
     * @param string $value
     *
     * @return Swift_Mime_Header
     */
    public function createTextHeader($name, $value = null)
    {
        $header = new Swift_Mime_Headers_UnstructuredHeader($name, $this->encoder);
        if (isset($value)) {
            $header->setFieldBodyModel($value);
        }
        $this->setHeaderCharset($header);

        return $header;
    }

    /**
     * Create a new ParameterizedHeader with $name, $value and $params.
     *
     * @param string $name
     * @param string $value
     * @param array  $params
     *
     * @return Swift_Mime_Headers_ParameterizedHeader
     */
    public function createParameterizedHeader($name, $value = null, $params = [])
    {
        $header = new Swift_Mime_Headers_ParameterizedHeader($name, $this->encoder, ('content-disposition' == strtolower($name ?? '')) ? $this->paramEncoder : null);
        if (isset($value)) {
            $header->setFieldBodyModel($value);
        }
        foreach ($params as $k => $v) {
            $header->setParameter($k, $v);
        }
        $this->setHeaderCharset($header);

        return $header;
    }

    /**
     * Create a new ID header for Message-ID or Content-ID.
     *
     * @param string       $name
     * @param string|array $ids
     *
     * @return Swift_Mime_Header
     */
    public function createIdHeader($name, $ids = null)
    {
        $header = new Swift_Mime_Headers_IdentificationHeader($name, $this->emailValidator);
        if (isset($ids)) {
            $header->setFieldBodyModel($ids);
        }
        $this->setHeaderCharset($header);

        return $header;
    }

    /**
     * Create a new Path header with an address (path) in it.
     *
     * @param string $name
     * @param string $path
     *
     * @return Swift_Mime_Header
     */
    public function createPathHeader($name, $path = null)
    {
        $header = new Swift_Mime_Headers_PathHeader($name, $this->emailValidator);
        if (isset($path)) {
            $header->setFieldBodyModel($path);
        }
        $this->setHeaderCharset($header);

        return $header;
    }

    /**
     * Notify this observer that the entity's charset has changed.
     *
     * @param string $charset
     */
    public function charsetChanged($charset)
    {
        $this->charset = $charset;
        $this->encoder->charsetChanged($charset);
        $this->paramEncoder->charsetChanged($charset);
    }

    /**
     * Make a deep copy of object.
     */
    public function __clone()
    {
        $this->encoder = clone $this->encoder;
        $this->paramEncoder = clone $this->paramEncoder;
        $this->addressEncoder = clone $this->addressEncoder;
    }

    /** Apply the charset to the Header */
    private function setHeaderCharset(Swift_Mime_Header $header)
    {
        if (isset($this->charset)) {
            $header->setCharset($this->charset);
        }
    }
}


================================================
FILE: lib/classes/Swift/Mime/SimpleHeaderSet.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * A collection of MIME headers.
 *
 * @author Chris Corbyn
 */
class Swift_Mime_SimpleHeaderSet implements Swift_Mime_CharsetObserver
{
    /** HeaderFactory */
    private $factory;

    /** Collection of set Headers */
    private $headers = [];

    /** Field ordering details */
    private $order = [];

    /** List of fields which are required to be displayed */
    private $required = [];

    /** The charset used by Headers */
    private $charset;

    /**
     * Create a new SimpleHeaderSet with the given $factory.
     *
     * @param string $charset
     */
    public function __construct(Swift_Mime_SimpleHeaderFactory $factory, $charset = null)
    {
        $this->factory = $factory;
        if (isset($charset)) {
            $this->setCharset($charset);
        }
    }

    public function newInstance()
    {
        return new self($this->factory);
    }

    /**
     * Set the charset used by these headers.
     *
     * @param string $charset
     */
    public function setCharset($charset)
    {
        $this->charset = $charset;
        $this->factory->charsetChanged($charset);
        $this->notifyHeadersOfCharset($charset);
    }

    /**
     * Add a new Mailbox Header with a list of $addresses.
     *
     * @param string       $name
     * @param array|string $addresses
     */
    public function addMailboxHeader($name, $addresses = null)
    {
        $this->storeHeader($name, $this->factory->createMailboxHeader($name, $addresses));
    }

    /**
     * Add a new Date header using $dateTime.
     *
     * @param string $name
     */
    public function addDateHeader($name, DateTimeInterface $dateTime = null)
    {
        $this->storeHeader($name, $this->factory->createDateHeader($name, $dateTime));
    }

    /**
     * Add a new basic text header with $name and $value.
     *
     * @param string $name
     * @param string $value
     */
    public function addTextHeader($name, $value = null)
    {
        $this->storeHeader($name, $this->factory->createTextHeader($name, $value));
    }

    /**
     * Add a new ParameterizedHeader with $name, $value and $params.
     *
     * @param string $name
     * @param string $value
     * @param array  $params
     */
    public function addParameterizedHeader($name, $value = null, $params = [])
    {
        $this->storeHeader($name, $this->factory->createParameterizedHeader($name, $value, $params));
    }

    /**
     * Add a new ID header for Message-ID or Content-ID.
     *
     * @param string       $name
     * @param string|array $ids
     */
    public function addIdHeader($name, $ids = null)
    {
        $this->storeHeader($name, $this->factory->createIdHeader($name, $ids));
    }

    /**
     * Add a new Path header with an address (path) in it.
     *
     * @param string $name
     * @param string $path
     */
    public function addPathHeader($name, $path = null)
    {
        $this->storeHeader($name, $this->factory->createPathHeader($name, $path));
    }

    /**
     * Returns true if at least one header with the given $name exists.
     *
     * If multiple headers match, the actual one may be specified by $index.
     *
     * @param string $name
     * @param int    $index
     *
     * @return bool
     */
    public function has($name, $index = 0)
    {
        $lowerName = strtolower($name ?? '');

        if (!\array_key_exists($lowerName, $this->headers)) {
            return false;
        }

        if (\func_num_args() < 2) {
            // index was not specified, so we only need to check that there is at least one header value set
            return (bool) \count($this->headers[$lowerName]);
        }

        return \array_key_exists($index, $this->headers[$lowerName]);
    }

    /**
     * Set a header in the HeaderSet.
     *
     * The header may be a previously fetched header via {@link get()} or it may
     * be one that has been created separately.
     *
     * If $index is specified, the header will be inserted into the set at this
     * offset.
     *
     * @param int $index
     */
    public function set(Swift_Mime_Header $header, $index = 0)
    {
        $this->storeHeader($header->getFieldName(), $header, $index);
    }

    /**
     * Get the header with the given $name.
     *
     * If multiple headers match, the actual one may be specified by $index.
     * Returns NULL if none present.
     *
     * @param string $name
     * @param int    $index
     *
     * @return Swift_Mime_Header|null
     */
    public function get($name, $index = 0)
    {
        $name = strtolower($name ?? '');

        if (\func_num_args() < 2) {
            if ($this->has($name)) {
                $values = array_values($this->headers[$name]);

                return array_shift($values);
            }
        } else {
            if ($this->has($name, $index)) {
                return $this->headers[$name][$index];
            }
        }
    }

    /**
     * Get all headers with the given $name.
     *
     * @param string $name
     *
     * @return array
     */
    public function getAll($name = null)
    {
        if (!isset($name)) {
            $headers = [];
            foreach ($this->headers as $collection) {
                $headers = array_merge($headers, $collection);
            }

            return $headers;
        }

        $lowerName = strtolower($name ?? '');
        if (!\array_key_exists($lowerName, $this->headers)) {
            return [];
        }

        return $this->headers[$lowerName];
    }

    /**
     * Return the name of all Headers.
     *
     * @return array
     */
    public function listAll()
    {
        $headers = $this->headers;
        if ($this->canSort()) {
            uksort($headers, [$this, 'sortHeaders']);
        }

        return array_keys($headers);
    }

    /**
     * Remove the header with the given $name if it's set.
     *
     * If multiple headers match, the actual one may be specified by $index.
     *
     * @param string $name
     * @param int    $index
     */
    public function remove($name, $index = 0)
    {
        $lowerName = strtolower($name ?? '');
        unset($this->headers[$lowerName][$index]);
    }

    /**
     * Remove all headers with the given $name.
     *
     * @param string $name
     */
    public function removeAll($name)
    {
        $lowerName = strtolower($name ?? '');
        unset($this->headers[$lowerName]);
    }

    /**
     * Define a list of Header names as an array in the correct order.
     *
     * These Headers will be output in the given order where present.
     */
    public function defineOrdering(array $sequence)
    {
        $this->order = array_flip(array_map('strtolower', $sequence));
    }

    /**
     * Set a list of header names which must always be displayed when set.
     *
     * Usually headers without a field value won't be output unless set here.
     */
    public function setAlwaysDisplayed(array $names)
    {
        $this->required = array_flip(array_map('strtolower', $names));
    }

    /**
     * Notify this observer that the entity's charset has changed.
     *
     * @param string $charset
     */
    public function charsetChanged($charset)
    {
        $this->setCharset($charset);
    }

    /**
     * Returns a string with a representation of all headers.
     *
     * @return string
     */
    public function toString()
    {
        $string = '';
        $headers = $this->headers;
        if ($this->canSort()) {
            uksort($headers, [$this, 'sortHeaders']);
        }
        foreach ($headers as $collection) {
            foreach ($collection as $header) {
                if ($this->isDisplayed($header) || '' != $header->getFieldBody()) {
                    $string .= $header->toString();
                }
            }
        }

        return $string;
    }

    /**
     * Returns a string representation of this object.
     *
     * @return string
     *
     * @see toString()
     */
    public function __toString()
    {
        return $this->toString();
    }

    /** Save a Header to the internal collection */
    private function storeHeader($name, Swift_Mime_Header $header, $offset = null)
    {
        if (!isset($this->headers[strtolower($name ?? '')])) {
            $this->headers[strtolower($name ?? '')] = [];
        }
        if (!isset($offset)) {
            $this->headers[strtolower($name ?? '')][] = $header;
        } else {
            $this->headers[strtolower($name ?? '')][$offset] = $header;
        }
    }

    /** Test if the headers can be sorted */
    private function canSort()
    {
        return \count($this->order) > 0;
    }

    /** uksort() algorithm for Header ordering */
    private function sortHeaders($a, $b)
    {
        $lowerA = strtolower($a ?? '');
        $lowerB = strtolower($b ?? '');
        $aPos = \array_key_exists($lowerA, $this->order) ? $this->order[$lowerA] : -1;
        $bPos = \array_key_exists($lowerB, $this->order) ? $this->order[$lowerB] : -1;

        if (-1 === $aPos && -1 === $bPos) {
            // just be sure to be determinist here
            return $a > $b ? -1 : 1;
        }

        if (-1 == $aPos) {
            return 1;
        } elseif (-1 == $bPos) {
            return -1;
        }

        return $aPos < $bPos ? -1 : 1;
    }

    /** Test if the given Header is always displayed */
    private function isDisplayed(Swift_Mime_Header $header)
    {
        return \array_key_exists(strtolower($header->getFieldName() ?? ''), $this->required);
    }

    /** Notify all Headers of the new charset */
    private function notifyHeadersOfCharset($charset)
    {
        foreach ($this->headers as $headerGroup) {
            foreach ($headerGroup as $header) {
                $header->setCharset($charset);
            }
        }
    }

    /**
     * Make a deep copy of object.
     */
    public function __clone()
    {
        $this->factory = clone $this->factory;
        foreach ($this->headers as $groupKey => $headerGroup) {
            foreach ($headerGroup as $key => $header) {
                $this->headers[$groupKey][$key] = clone $header;
            }
        }
    }
}


================================================
FILE: lib/classes/Swift/Mime/SimpleMessage.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * The default email message class.
 *
 * @author Chris Corbyn
 */
class Swift_Mime_SimpleMessage extends Swift_Mime_MimePart
{
    const PRIORITY_HIGHEST = 1;
    const PRIORITY_HIGH = 2;
    const PRIORITY_NORMAL = 3;
    const PRIORITY_LOW = 4;
    const PRIORITY_LOWEST = 5;

    /**
     * Create a new SimpleMessage with $headers, $encoder and $cache.
     *
     * @param string $charset
     */
    public function __construct(Swift_Mime_SimpleHeaderSet $headers, Swift_Mime_ContentEncoder $encoder, Swift_KeyCache $cache, Swift_IdGenerator $idGenerator, $charset = null)
    {
        parent::__construct($headers, $encoder, $cache, $idGenerator, $charset);
        $this->getHeaders()->defineOrdering([
            'Return-Path',
            'Received',
            'DKIM-Signature',
            'DomainKey-Signature',
            'Sender',
            'Message-ID',
            'Date',
            'Subject',
            'From',
            'Reply-To',
            'To',
            'Cc',
            'Bcc',
            'MIME-Version',
            'Content-Type',
            'Content-Transfer-Encoding',
            ]);
        $this->getHeaders()->setAlwaysDisplayed(['Date', 'Message-ID', 'From']);
        $this->getHeaders()->addTextHeader('MIME-Version', '1.0');
        $this->setDate(new DateTimeImmutable());
        $this->setId($this->getId());
        $this->getHeaders()->addMailboxHeader('From');
    }

    /**
     * Always returns {@link LEVEL_TOP} for a message instance.
     *
     * @return int
     */
    public function getNestingLevel()
    {
        return self::LEVEL_TOP;
    }

    /**
     * Set the subject of this message.
     *
     * @param string $subject
     *
     * @return $this
     */
    public function setSubject($subject)
    {
        if (!$this->setHeaderFieldModel('Subject', $subject)) {
            $this->getHeaders()->addTextHeader('Subject', $subject);
        }

        return $this;
    }

    /**
     * Get the subject of this message.
     *
     * @return string
     */
    public function getSubject()
    {
        return $this->getHeaderFieldModel('Subject');
    }

    /**
     * Set the date at which this message was created.
     *
     * @return $this
     */
    public function setDate(DateTimeInterface $dateTime)
    {
        if (!$this->setHeaderFieldModel('Date', $dateTime)) {
            $this->getHeaders()->addDateHeader('Date', $dateTime);
        }

        return $this;
    }

    /**
     * Get the date at which this message was created.
     *
     * @return DateTimeInterface
     */
    public function getDate()
    {
        return $this->getHeaderFieldModel('Date');
    }

    /**
     * Set the return-path (the bounce address) of this message.
     *
     * @param string $address
     *
     * @return $this
     */
    public function setReturnPath($address)
    {
        if (!$this->setHeaderFieldModel('Return-Path', $address)) {
            $this->getHeaders()->addPathHeader('Return-Path', $address);
        }

        return $this;
    }

    /**
     * Get the return-path (bounce address) of this message.
     *
     * @return string
     */
    public function getReturnPath()
    {
        return $this->getHeaderFieldModel('Return-Path');
    }

    /**
     * Set the sender of this message.
     *
     * This does not override the From field, but it has a higher significance.
     *
     * @param string $address
     * @param string $name    optional
     *
     * @return $this
     */
    public function setSender($address, $name = null)
    {
        if (!\is_array($address) && isset($name)) {
            $address = [$address => $name];
        }

        if (!$this->setHeaderFieldModel('Sender', (array) $address)) {
            $this->getHeaders()->addMailboxHeader('Sender', (array) $address);
        }

        return $this;
    }

    /**
     * Get the sender of this message.
     *
     * @return string
     */
    public function getSender()
    {
        return $this->getHeaderFieldModel('Sender');
    }

    /**
     * Add a From: address to this message.
     *
     * If $name is passed this name will be associated with the address.
     *
     * @param string $address
     * @param string $name    optional
     *
     * @return $this
     */
    public function addFrom($address, $name = null)
    {
        $current = $this->getFrom();
        $current[$address] = $name;

        return $this->setFrom($current);
    }

    /**
     * Set the from address of this message.
     *
     * You may pass an array of addresses if this message is from multiple people.
     *
     * If $name is passed and the first parameter is a string, this name will be
     * associated with the address.
     *
     * @param string|array $addresses
     * @param string       $name      optional
     *
     * @return $this
     */
    public function setFrom($addresses, $name = null)
    {
        if (!\is_array($addresses) && isset($name)) {
            $addresses = [$addresses => $name];
        }

        if (!$this->setHeaderFieldModel('From', (array) $addresses)) {
            $this->getHeaders()->addMailboxHeader('From', (array) $addresses);
        }

        return $this;
    }

    /**
     * Get the from address of this message.
     *
     * @return mixed
     */
    public function getFrom()
    {
        return $this->getHeaderFieldModel('From');
    }

    /**
     * Add a Reply-To: address to this message.
     *
     * If $name is passed this name will be associated with the address.
     *
     * @param string $address
     * @param string $name    optional
     *
     * @return $this
     */
    public function addReplyTo($address, $name = null)
    {
        $current = $this->getReplyTo();
        $current[$address] = $name;

        return $this->setReplyTo($current);
    }

    /**
     * Set the reply-to address of this message.
     *
     * You may pass an array of addresses if replies will go to multiple people.
     *
     * If $name is passed and the first parameter is a string, this name will be
     * associated with the address.
     *
     * @param mixed  $addresses
     * @param string $name      optional
     *
     * @return $this
     */
    public function setReplyTo($addresses, $name = null)
    {
        if (!\is_array($addresses) && isset($name)) {
            $addresses = [$addresses => $name];
        }

        if (!$this->setHeaderFieldModel('Reply-To', (array) $addresses)) {
            $this->getHeaders()->addMailboxHeader('Reply-To', (array) $addresses);
        }

        return $this;
    }

    /**
     * Get the reply-to address of this message.
     *
     * @return string
     */
    public function getReplyTo()
    {
        return $this->getHeaderFieldModel('Reply-To');
    }

    /**
     * Add a To: address to this message.
     *
     * If $name is passed this name will be associated with the address.
     *
     * @param string $address
     * @param string $name    optional
     *
     * @return $this
     */
    public function addTo($address, $name = null)
    {
        $current = $this->getTo();
        $current[$address] = $name;

        return $this->setTo($current);
    }

    /**
     * Set the to addresses of this message.
     *
     * If multiple recipients will receive the message an array should be used.
     * Example: array('receiver@domain.org', 'other@domain.org' => 'A name')
     *
     * If $name is passed and the first parameter is a string, this name will be
     * associated with the address.
     *
     * @param mixed  $addresses
     * @param string $name      optional
     *
     * @return $this
     */
    public function setTo($addresses, $name = null)
    {
        if (!\is_array($addresses) && isset($name)) {
            $addresses = [$addresses => $name];
        }

        if (!$this->setHeaderFieldModel('To', (array) $addresses)) {
            $this->getHeaders()->addMailboxHeader('To', (array) $addresses);
        }

        return $this;
    }

    /**
     * Get the To addresses of this message.
     *
     * @return array
     */
    public function getTo()
    {
        return $this->getHeaderFieldModel('To');
    }

    /**
     * Add a Cc: address to this message.
     *
     * If $name is passed this name will be associated with the address.
     *
     * @param string $address
     * @param string $name    optional
     *
     * @return $this
     */
    public function addCc($address, $name = null)
    {
        $current = $this->getCc();
        $current[$address] = $name;

        return $this->setCc($current);
    }

    /**
     * Set the Cc addresses of this message.
     *
     * If $name is passed and the first parameter is a string, this name will be
     * associated with the address.
     *
     * @param mixed  $addresses
     * @param string $name      optional
     *
     * @return $this
     */
    public function setCc($addresses, $name = null)
    {
        if (!\is_array($addresses) && isset($name)) {
            $addresses = [$addresses => $name];
        }

        if (!$this->setHeaderFieldModel('Cc', (array) $addresses)) {
            $this->getHeaders()->addMailboxHeader('Cc', (array) $addresses);
        }

        return $this;
    }

    /**
     * Get the Cc address of this message.
     *
     * @return array
     */
    public function getCc()
    {
        return $this->getHeaderFieldModel('Cc');
    }

    /**
     * Add a Bcc: address to this message.
     *
     * If $name is passed this name will be associated with the address.
     *
     * @param string $address
     * @param string $name    optional
     *
     * @return $this
     */
    public function addBcc($address, $name = null)
    {
        $current = $this->getBcc();
        $current[$address] = $name;

        return $this->setBcc($current);
    }

    /**
     * Set the Bcc addresses of this message.
     *
     * If $name is passed and the first parameter is a string, this name will be
     * associated with the address.
     *
     * @param mixed  $addresses
     * @param string $name      optional
     *
     * @return $this
     */
    public function setBcc($addresses, $name = null)
    {
        if (!\is_array($addresses) && isset($name)) {
            $addresses = [$addresses => $name];
        }

        if (!$this->setHeaderFieldModel('Bcc', (array) $addresses)) {
            $this->getHeaders()->addMailboxHeader('Bcc', (array) $addresses);
        }

        return $this;
    }

    /**
     * Get the Bcc addresses of this message.
     *
     * @return array
     */
    public function getBcc()
    {
        return $this->getHeaderFieldModel('Bcc');
    }

    /**
     * Set the priority of this message.
     *
     * The value is an integer where 1 is the highest priority and 5 is the lowest.
     *
     * @param int $priority
     *
     * @return $this
     */
    public function setPriority($priority)
    {
        $priorityMap = [
            self::PRIORITY_HIGHEST => 'Highest',
            self::PRIORITY_HIGH => 'High',
            self::PRIORITY_NORMAL => 'Normal',
            self::PRIORITY_LOW => 'Low',
            self::PRIORITY_LOWEST => 'Lowest',
            ];
        $pMapKeys = array_keys($priorityMap);
        if ($priority > max($pMapKeys)) {
            $priority = max($pMapKeys);
        } elseif ($priority < min($pMapKeys)) {
            $priority = min($pMapKeys);
        }
        if (!$this->setHeaderFieldModel('X-Priority',
            sprintf('%d (%s)', $priority, $priorityMap[$priority]))) {
            $this->getHeaders()->addTextHeader('X-Priority',
                sprintf('%d (%s)', $priority, $priorityMap[$priority]));
        }

        return $this;
    }

    /**
     * Get the priority of this message.
     *
     * The returned value is an integer where 1 is the highest priority and 5
     * is the lowest.
     *
     * @return int
     */
    public function getPriority()
    {
        list($priority) = sscanf($this->getHeaderFieldModel('X-Priority'),
            '%[1-5]'
            );

        return $priority ?? 3;
    }

    /**
     * Ask for a delivery receipt from the recipient to be sent to $addresses.
     *
     * @param array $addresses
     *
     * @return $this
     */
    public function setReadReceiptTo($addresses)
    {
        if (!$this->setHeaderFieldModel('Disposition-Notification-To', $addresses)) {
            $this->getHeaders()
                ->addMailboxHeader('Disposition-Notification-To', $addresses);
        }

        return $this;
    }

    /**
     * Get the addresses to which a read-receipt will be sent.
     *
     * @return string
     */
    public function getReadReceiptTo()
    {
        return $this->getHeaderFieldModel('Disposition-Notification-To');
    }

    /**
     * Attach a {@link Swift_Mime_SimpleMimeEntity} such as an Attachment or MimePart.
     *
     * @return $this
     */
    public function attach(Swift_Mime_SimpleMimeEntity $entity)
    {
        $this->setChildren(array_merge($this->getChildren(), [$entity]));

        return $this;
    }

    /**
     * Remove an already attached entity.
     *
     * @return $this
     */
    public function detach(Swift_Mime_SimpleMimeEntity $entity)
    {
        $newChildren = [];
        foreach ($this->getChildren() as $child) {
            if ($entity !== $child) {
                $newChildren[] = $child;
            }
        }
        $this->setChildren($newChildren);

        return $this;
    }

    /**
     * Attach a {@link Swift_Mime_SimpleMimeEntity} and return it's CID source.
     *
     * This method should be used when embedding images or other data in a message.
     *
     * @return string
     */
    public function embed(Swift_Mime_SimpleMimeEntity $entity)
    {
        $this->attach($entity);

        return 'cid:'.$entity->getId();
    }

    /**
     * Get this message as a complete string.
     *
     * @return string
     */
    public function toString()
    {
        if (\count($children = $this->getChildren()) > 0 && '' != $this->getBody()) {
            $this->setChildren(array_merge([$this->becomeMimePart()], $children));
            $string = parent::toString();
            $this->setChildren($children);
        } else {
            $string = parent::toString();
        }

        return $string;
    }

    /**
     * Returns a string representation of this object.
     *
     * @see toString()
     *
     * @return string
     */
    public function __toString()
    {
        return $this->toString();
    }

    /**
     * Write this message to a {@link Swift_InputByteStream}.
     */
    public function toByteStream(Swift_InputByteStream $is)
    {
        if (\count($children = $this->getChildren()) > 0 && '' != $this->getBody()) {
            $this->setChildren(array_merge([$this->becomeMimePart()], $children));
            parent::toByteStream($is);
            $this->setChildren($children);
        } else {
            parent::toByteStream($is);
        }
    }

    /** @see Swift_Mime_SimpleMimeEntity::getIdField() */
    protected function getIdField()
    {
        return 'Message-ID';
    }

    /** Turn the body of this message into a child of itself if needed */
    protected function becomeMimePart()
    {
        $part = new parent($this->getHeaders()->newInstance(), $this->getEncoder(),
            $this->getCache(), $this->getIdGenerator(), $this->userCharset
            );
        $part->setContentType($this->userContentType);
        $part->setBody($this->getBody());
        $part->setFormat($this->userFormat);
        $part->setDelSp($this->userDelSp);
        $part->setNestingLevel($this->getTopNestingLevel());

        return $part;
    }

    /** Get the highest nesting level nested inside this message */
    private function getTopNestingLevel()
    {
        $highestLevel = $this->getNestingLevel();
        foreach ($this->getChildren() as $child) {
            $childLevel = $child->getNestingLevel();
            if ($highestLevel < $childLevel) {
                $highestLevel = $childLevel;
            }
        }

        return $highestLevel;
    }
}


================================================
FILE: lib/classes/Swift/Mime/SimpleMimeEntity.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * A MIME entity, in a multipart message.
 *
 * @author Chris Corbyn
 */
class Swift_Mime_SimpleMimeEntity implements Swift_Mime_CharsetObserver, Swift_Mime_EncodingObserver
{
    /** Main message document; there can only be one of these */
    const LEVEL_TOP = 16;

    /** An entity which nests with the same precedence as an attachment */
    const LEVEL_MIXED = 256;

    /** An entity which nests with the same precedence as a mime part */
    const LEVEL_ALTERNATIVE = 4096;

    /** An entity which nests with the same precedence as embedded content */
    const LEVEL_RELATED = 65536;

    /** A collection of Headers for this mime entity */
    private $headers;

    /** The body as a string, or a stream */
    private $body;

    /** The encoder that encodes the body into a streamable format */
    private $encoder;

    /** Message ID generator */
    private $idGenerator;

    /** A mime boundary, if any is used */
    private $boundary;

    /** Mime types to be used based on the nesting level */
    private $compositeRanges = [
        'multipart/mixed' => [self::LEVEL_TOP, self::LEVEL_MIXED],
        'multipart/alternative' => [self::LEVEL_MIXED, self::LEVEL_ALTERNATIVE],
        'multipart/related' => [self::LEVEL_ALTERNATIVE, self::LEVEL_RELATED],
    ];

    /** A set of filter rules to define what level an entity should be nested at */
    private $compoundLevelFilters = [];

    /** The nesting level of this entity */
    private $nestingLevel = self::LEVEL_ALTERNATIVE;

    /** A KeyCache instance used during encoding and streaming */
    private $cache;

    /** Direct descendants of this entity */
    private $immediateChildren = [];

    /** All descendants of this entity */
    private $children = [];

    /** The maximum line length of the body of this entity */
    private $maxLineLength = 78;

    /** The order in which alternative mime types should appear */
    private $alternativePartOrder = [
        'text/plain' => 1,
        'text/html' => 2,
        'multipart/related' => 3,
    ];

    /** The CID of this entity */
    private $id;

    /** The key used for accessing the cache */
    private $cacheKey;

    protected $userContentType;

    /**
     * Create a new SimpleMimeEntity with $headers, $encoder and $cache.
     */
    public function __construct(Swift_Mime_SimpleHeaderSet $headers, Swift_Mime_ContentEncoder $encoder, Swift_KeyCache $cache, Swift_IdGenerator $idGenerator)
    {
        $this->cacheKey = bin2hex(random_bytes(16)); // set 32 hex values
        $this->cache = $cache;
        $this->headers = $headers;
        $this->idGenerator = $idGenerator;
        $this->setEncoder($encoder);
        $this->headers->defineOrdering(['Content-Type', 'Content-Transfer-Encoding']);

        // This array specifies that, when the entire MIME document contains
        // $compoundLevel, then for each child within $level, if its Content-Type
        // is $contentType then it should be treated as if it's level is
        // $neededLevel instead.  I tried to write that unambiguously! :-\
        // Data Structure:
        // array (
        //   $compoundLevel => array(
        //     $level => array(
        //       $contentType => $neededLevel
        //     )
        //   )
        // )

        $this->compoundLevelFilters = [
            (self::LEVEL_ALTERNATIVE + self::LEVEL_RELATED) => [
                self::LEVEL_ALTERNATIVE => [
                    'text/plain' => self::LEVEL_ALTERNATIVE,
                    'text/html' => self::LEVEL_RELATED,
                    ],
                ],
            ];

        $this->id = $this->idGenerator->generateId();
    }

    /**
     * Generate a new Content-ID or Message-ID for this MIME entity.
     *
     * @return string
     */
    public function generateId()
    {
        $this->setId($this->idGenerator->generateId());

        return $this->id;
    }

    /**
     * Get the {@link Swift_Mime_SimpleHeaderSet} for this entity.
     *
     * @return Swift_Mime_SimpleHeaderSet
     */
    public function getHeaders()
    {
        return $this->headers;
    }

    /**
     * Get the nesting level of this entity.
     *
     * @see LEVEL_TOP, LEVEL_MIXED, LEVEL_RELATED, LEVEL_ALTERNATIVE
     *
     * @return int
     */
    public function getNestingLevel()
    {
        return $this->nestingLevel;
    }

    /**
     * Get the Content-type of this entity.
     *
     * @return string
     */
    public function getContentType()
    {
        return $this->getHeaderFieldModel('Content-Type');
    }

    /**
     * Get the Body Content-type of this entity.
     *
     * @return string
     */
    public function getBodyContentType()
    {
        return $this->userContentType;
    }

    /**
     * Set the Content-type of this entity.
     *
     * @param string $type
     *
     * @return $this
     */
    public function setContentType($type)
    {
        $this->setContentTypeInHeaders($type);
        // Keep track of the value so that if the content-type changes automatically
        // due to added child entities, it can be restored if they are later removed
        $this->userContentType = $type;

        return $this;
    }

    /**
     * Get the CID of this entity.
     *
     * The CID will only be present in headers if a Content-ID header is present.
     *
     * @return string
     */
    public function getId()
    {
        $tmp = (array) $this->getHeaderFieldModel($this->getIdField());

        return $this->headers->has($this->getIdField()) ? current($tmp) : $this->id;
    }

    /**
     * Set the CID of this entity.
     *
     * @param string $id
     *
     * @return $this
     */
    public function setId($id)
    {
        if (!$this->setHeaderFieldModel($this->getIdField(), $id)) {
            $this->headers->addIdHeader($this->getIdField(), $id);
        }
        $this->id = $id;

        return $this;
    }

    /**
     * Get the description of this entity.
     *
     * This value comes from the Content-Description header if set.
     *
     * @return string
     */
    public function getDescription()
    {
        return $this->getHeaderFieldModel('Content-Description');
    }

    /**
     * Set the description of this entity.
     *
     * This method sets a value in the Content-ID header.
     *
     * @param string $description
     *
     * @return $this
     */
    public function setDescription($description)
    {
        if (!$this->setHeaderFieldModel('Content-Description', $description)) {
            $this->headers->addTextHeader('Content-Description', $description);
        }

        return $this;
    }

    /**
     * Get the maximum line length of the body of this entity.
     *
     * @return int
     */
    public function getMaxLineLength()
    {
        return $this->maxLineLength;
    }

    /**
     * Set the maximum line length of lines in this body.
     *
     * Though not enforced by the library, lines should not exceed 1000 chars.
     *
     * @param int $length
     *
     * @return $this
     */
    public function setMaxLineLength($length)
    {
        $this->maxLineLength = $length;

        return $this;
    }

    /**
     * Get all children added to this entity.
     *
     * @return Swift_Mime_SimpleMimeEntity[]
     */
    public function getChildren()
    {
        return $this->children;
    }

    /**
     * Set all children of this entity.
     *
     * @param Swift_Mime_SimpleMimeEntity[] $children
     * @param int                           $compoundLevel For internal use only
     *
     * @return $this
     */
    public function setChildren(array $children, $compoundLevel = null)
    {
        // TODO: Try to refactor this logic
        $compoundLevel = $compoundLevel ?? $this->getCompoundLevel($children);
        $immediateChildren = [];
        $grandchildren = [];
        $newContentType = $this->userContentType;

        foreach ($children as $child) {
            $level = $this->getNeededChildLevel($child, $compoundLevel);
            if (empty($immediateChildren)) {
                //first iteration
                $immediateChildren = [$child];
            } else {
                $nextLevel = $this->getNeededChildLevel($immediateChildren[0], $compoundLevel);
                if ($nextLevel == $level) {
                    $immediateChildren[] = $child;
                } elseif ($level < $nextLevel) {
                    // Re-assign immediateChildren to grandchildren
                    $grandchildren = array_merge($grandchildren, $immediateChildren);
                    // Set new children
                    $immediateChildren = [$child];
                } else {
                    $grandchildren[] = $child;
                }
            }
        }

        if ($immediateChildren) {
            $lowestLevel = $this->getNeededChildLevel($immediateChildren[0], $compoundLevel);

            // Determine which composite media type is needed to accommodate the
            // immediate children
            foreach ($this->compositeRanges as $mediaType => $range) {
                if ($lowestLevel > $range[0] && $lowestLevel <= $range[1]) {
                    $newContentType = $mediaType;

                    break;
                }
            }

            // Put any grandchildren in a subpart
            if (!empty($grandchildren)) {
                $subentity = $this->createChild();
                $subentity->setNestingLevel($lowestLevel);
                $subentity->setChildren($grandchildren, $compoundLevel);
                array_unshift($immediateChildren, $subentity);
            }
        }

        $this->immediateChildren = $immediateChildren;
        $this->children = $children;
        $this->setContentTypeInHeaders($newContentType);
        $this->fixHeaders();
        $this->sortChildren();

        return $this;
    }

    /**
     * Get the body of this entity as a string.
     *
     * @return string
     */
    public function getBody()
    {
        return $this->body instanceof Swift_OutputByteStream ? $this->readStream($this->body) : $this->body;
    }

    /**
     * Set the body of this entity, either as a string, or as an instance of
     * {@link Swift_OutputByteStream}.
     *
     * @param mixed  $body
     * @param string $contentType optional
     *
     * @return $this
     */
    public function setBody($body, $contentType = null)
    {
        if ($body !== $this->body) {
            $this->clearCache();
        }

        $this->body = $body;
        if (null !== $contentType) {
            $this->setContentType($contentType);
        }

        return $this;
    }

    /**
     * Get the encoder used for the body of this entity.
     *
     * @return Swift_Mime_ContentEncoder
     */
    public function getEncoder()
    {
        return $this->encoder;
    }

    /**
     * Set the encoder used for the body of this entity.
     *
     * @return $this
     */
    public function setEncoder(Swift_Mime_ContentEncoder $encoder)
    {
        if ($encoder !== $this->encoder) {
            $this->clearCache();
        }

        $this->encoder = $encoder;
        $this->setEncoding($encoder->getName());
        $this->notifyEncoderChanged($encoder);

        return $this;
    }

    /**
     * Get the boundary used to separate children in this entity.
     *
     * @return string
     */
    public function getBoundary()
    {
        if (!isset($this->boundary)) {
            $this->boundary = '_=_swift_'.time().'_'.bin2hex(random_bytes(16)).'_=_';
        }

        return $this->boundary;
    }

    /**
     * Set the boundary used to separate children in this entity.
     *
     * @param string $boundary
     *
     * @throws Swift_RfcComplianceException
     *
     * @return $this
     */
    public function setBoundary($boundary)
    {
        $this->assertValidBoundary($boundary);
        $this->boundary = $boundary;

        return $this;
    }

    /**
     * Receive notification that the charset of this entity, or a parent entity
     * has changed.
     *
     * @param string $charset
     */
    public function charsetChanged($charset)
    {
        $this->notifyCharsetChanged($charset);
    }

    /**
     * Receive notification that the encoder of this entity or a parent entity
     * has changed.
     */
    public function encoderChanged(Swift_Mime_ContentEncoder $encoder)
    {
        $this->notifyEncoderChanged($encoder);
    }

    /**
     * Get this entire entity as a string.
     *
     * @return string
     */
    public function toString()
    {
        $string = $this->headers->toString();
        $string .= $this->bodyToString();

        return $string;
    }

    /**
     * Get this entire entity as a string.
     *
     * @return string
     */
    protected function bodyToString()
    {
        $string = '';

        if (isset($this->body) && empty($this->immediateChildren)) {
            if ($this->cache->hasKey($this->cacheKey, 'body')) {
                $body = $this->cache->getString($this->cacheKey, 'body');
            } else {
                $body = "\r\n".$this->encoder->encodeString($this->getBody(), 0, $this->getMaxLineLength());
                $this->cache->setString($this->cacheKey, 'body', $body, Swift_KeyCache::MODE_WRITE);
            }
            $string .= $body;
        }

        if (!empty($this->immediateChildren)) {
            foreach ($this->immediateChildren as $child) {
                $string .= "\r\n\r\n--".$this->getBoundary()."\r\n";
                $string .= $child->toString();
            }
            $string .= "\r\n\r\n--".$this->getBoundary()."--\r\n";
        }

        return $string;
    }

    /**
     * Returns a string representation of this object.
     *
     * @see toString()
     *
     * @return string
     */
    public function __toString()
    {
        return $this->toString();
    }

    /**
     * Write this entire entity to a {@see Swift_InputByteStream}.
     */
    public function toByteStream(Swift_InputByteStream $is)
    {
        $is->write($this->headers->toString());
        $is->commit();

        $this->bodyToByteStream($is);
    }

    /**
     * Write this entire entity to a {@link Swift_InputByteStream}.
     */
    protected function bodyToByteStream(Swift_InputByteStream $is)
    {
        if (empty($this->immediateChildren)) {
            if (isset($this->body)) {
                if ($this->cache->hasKey($this->cacheKey, 'body')) {
                    $this->cache->exportToByteStream($this->cacheKey, 'body', $is);
                } else {
                    $cacheIs = $this->cache->getInputByteStream($this->cacheKey, 'body');
                    if ($cacheIs) {
                        $is->bind($cacheIs);
                    }

                    $is->write("\r\n");

                    if ($this->body instanceof Swift_OutputByteStream) {
                        $this->body->setReadPointer(0);

                        $this->encoder->encodeByteStream($this->body, $is, 0, $this->getMaxLineLength());
                    } else {
                        $is->write($this->encoder->encodeString($this->getBody(), 0, $this->getMaxLineLength()));
                    }

                    if ($cacheIs) {
                        $is->unbind($cacheIs);
                    }
                }
            }
        }

        if (!empty($this->immediateChildren)) {
            foreach ($this->immediateChildren as $child) {
                $is->write("\r\n\r\n--".$this->getBoundary()."\r\n");
                $child->toByteStream($is);
            }
            $is->write("\r\n\r\n--".$this->getBoundary()."--\r\n");
        }
    }

    /**
     * Get the name of the header that provides the ID of this entity.
     */
    protected function getIdField()
    {
        return 'Content-ID';
    }

    /**
     * Get the model data (usually an array or a string) for $field.
     */
    protected function getHeaderFieldModel($field)
    {
        if ($this->headers->has($field)) {
            return $this->headers->get($field)->getFieldBodyModel();
        }
    }

    /**
     * Set the model data for $field.
     */
    protected function setHeaderFieldModel($field, $model)
    {
        if ($this->headers->has($field)) {
            $this->headers->get($field)->setFieldBodyModel($model);

            return true;
        }

        return false;
    }

    /**
     * Get the parameter value of $parameter on $field header.
     */
    protected function getHeaderParameter($field, $parameter)
    {
        if ($this->headers->has($field)) {
            return $this->headers->get($field)->getParameter($parameter);
        }
    }

    /**
     * Set the parameter value of $parameter on $field header.
     */
    protected function setHeaderParameter($field, $parameter, $value)
    {
        if ($this->headers->has($field)) {
            $this->headers->get($field)->setParameter($parameter, $value);

            return true;
        }

        return false;
    }

    /**
     * Re-evaluate what content type and encoding should be used on this entity.
     */
    protected function fixHeaders()
    {
        if (\count($this->immediateChildren)) {
            $this->setHeaderParameter('Content-Type', 'boundary',
                $this->getBoundary()
                );
            $this->headers->remove('Content-Transfer-Encoding');
        } else {
            $this->setHeaderParameter('Content-Type', 'boundary', null);
            $this->setEncoding($this->encoder->getName());
        }
    }

    /**
     * Get the KeyCache used in this entity.
     *
     * @return Swift_KeyCache
     */
    protected function getCache()
    {
        return $this->cache;
    }

    /**
     * Get the ID generator.
     *
     * @return Swift_IdGenerator
     */
    protected function getIdGenerator()
    {
        return $this->idGenerator;
    }

    /**
     * Empty the KeyCache for this entity.
     */
    protected function clearCache()
    {
        $this->cache->clearKey($this->cacheKey, 'body');
    }

    private function readStream(Swift_OutputByteStream $os)
    {
        $string = '';
        while (false !== $bytes = $os->read(8192)) {
            $string .= $bytes;
        }

        $os->setReadPointer(0);

        return $string;
    }

    private function setEncoding($encoding)
    {
        if (!$this->setHeaderFieldModel('Content-Transfer-Encoding', $encoding)) {
            $this->headers->addTextHeader('Content-Transfer-Encoding', $encoding);
        }
    }

    private function assertValidBoundary($boundary)
    {
        if (!preg_match('/^[a-z0-9\'\(\)\+_\-,\.\/:=\?\ ]{0,69}[a-z0-9\'\(\)\+_\-,\.\/:=\?]$/Di', $boundary)) {
            throw new Swift_RfcComplianceException('Mime boundary set is not RFC 2046 compliant.');
        }
    }

    private function setContentTypeInHeaders($type)
    {
        if (!$this->setHeaderFieldModel('Content-Type', $type)) {
            $this->headers->addParameterizedHeader('Content-Type', $type);
        }
    }

    private function setNestingLevel($level)
    {
        $this->nestingLevel = $level;
    }

    private function getCompoundLevel($children)
    {
        $level = 0;
        foreach ($children as $child) {
            $level |= $child->getNestingLevel();
        }

        return $level;
    }

    private function getNeededChildLevel($child, $compoundLevel)
    {
        $filter = [];
        foreach ($this->compoundLevelFilters as $bitmask => $rules) {
            if (($compoundLevel & $bitmask) === $bitmask) {
                $filter = $rules + $filter;
            }
        }

        $realLevel = $child->getNestingLevel();
        $lowercaseType = strtolower($child->getContentType() ?? '');

        if (isset($filter[$realLevel]) && isset($filter[$realLevel][$lowercaseType])) {
            return $filter[$realLevel][$lowercaseType];
        }

        return $realLevel;
    }

    private function createChild()
    {
        return new self($this->headers->newInstance(), $this->encoder, $this->cache, $this->idGenerator);
    }

    private function notifyEncoderChanged(Swift_Mime_ContentEncoder $encoder)
    {
        foreach ($this->immediateChildren as $child) {
            $child->encoderChanged($encoder);
        }
    }

    private function notifyCharsetChanged($charset)
    {
        $this->encoder->charsetChanged($charset);
        $this->headers->charsetChanged($charset);
        foreach ($this->immediateChildren as $child) {
            $child->charsetChanged($charset);
        }
    }

    private function sortChildren()
    {
        $shouldSort = false;
        foreach ($this->immediateChildren as $child) {
            // NOTE: This include alternative parts moved into a related part
            if (self::LEVEL_ALTERNATIVE == $child->getNestingLevel()) {
                $shouldSort = true;
                break;
            }
        }

        // Sort in order of preference, if there is one
        if ($shouldSort) {
            // Group the messages by order of preference
            $sorted = [];
            foreach ($this->immediateChildren as $child) {
                $type = $child->getContentType();
                $level = \array_key_exists($type, $this->alternativePartOrder) ? $this->alternativePartOrder[$type] : max($this->alternativePartOrder) + 1;

                if (empty($sorted[$level])) {
                    $sorted[$level] = [];
                }

                $sorted[$level][] = $child;
            }

            ksort($sorted);

            $this->immediateChildren = array_reduce($sorted, 'array_merge', []);
        }
    }

    /**
     * Empties it's own contents from the cache.
     */
    public function __destruct()
    {
        if ($this->cache instanceof Swift_KeyCache) {
            $this->cache->clearAll($this->cacheKey);
        }
    }

    /**
     * Make a deep copy of object.
     */
    public function __clone()
    {
        $this->headers = clone $this->headers;
        $this->encoder = clone $this->encoder;
        $this->cacheKey = bin2hex(random_bytes(16)); // set 32 hex values
        $children = [];
        foreach ($this->children as $pos => $child) {
            $children[$pos] = clone $child;
        }
        $this->setChildren($children);
    }

    public function __wakeup()
    {
        $this->cacheKey = bin2hex(random_bytes(16)); // set 32 hex values
        $this->cache = new Swift_KeyCache_ArrayKeyCache(new Swift_KeyCache_SimpleKeyCacheInputStream());
    }
}


================================================
FILE: lib/classes/Swift/MimePart.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * A MIME part, in a multipart message.
 *
 * @author Chris Corbyn
 */
class Swift_MimePart extends Swift_Mime_MimePart
{
    /**
     * Create a new MimePart.
     *
     * Details may be optionally passed into the constructor.
     *
     * @param string $body
     * @param string $contentType
     * @param string $charset
     */
    public function __construct($body = null, $contentType = null, $charset = null)
    {
        \call_user_func_array(
            [$this, 'Swift_Mime_MimePart::__construct'],
            Swift_DependencyContainer::getInstance()
                ->createDependenciesFor('mime.part')
            );

        if (!isset($charset)) {
            $charset = Swift_DependencyContainer::getInstance()
                ->lookup('properties.charset');
        }
        $this->setBody($body);
        $this->setCharset($charset);
        if ($contentType) {
            $this->setContentType($contentType);
        }
    }
}


================================================
FILE: lib/classes/Swift/NullTransport.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2009 Fabien Potencier <fabien.potencier@gmail.com>
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Pretends messages have been sent, but just ignores them.
 *
 * @author Fabien Potencier
 */
class Swift_NullTransport extends Swift_Transport_NullTransport
{
    public function __construct()
    {
        \call_user_func_array(
            [$this, 'Swift_Transport_NullTransport::__construct'],
            Swift_DependencyContainer::getInstance()
                ->createDependenciesFor('transport.null')
        );
    }
}


================================================
FILE: lib/classes/Swift/OutputByteStream.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * An abstract means of reading data.
 *
 * Classes implementing this interface may use a subsystem which requires less
 * memory than working with large strings of data.
 *
 * @author Chris Corbyn
 */
interface Swift_OutputByteStream
{
    /**
     * Reads $length bytes from the stream into a string and moves the pointer
     * through the stream by $length.
     *
     * If less bytes exist than are requested the remaining bytes are given instead.
     * If no bytes are remaining at all, boolean false is returned.
     *
     * @param int $length
     *
     * @throws Swift_IoException
     *
     * @return string|bool
     */
    public function read($length);

    /**
     * Move the internal read pointer to $byteOffset in the stream.
     *
     * @param int $byteOffset
     *
     * @throws Swift_IoException
     *
     * @return bool
     */
    public function setReadPointer($byteOffset);
}


================================================
FILE: lib/classes/Swift/Plugins/AntiFloodPlugin.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Reduces network flooding when sending large amounts of mail.
 *
 * @author Chris Corbyn
 */
class Swift_Plugins_AntiFloodPlugin implements Swift_Events_SendListener, Swift_Plugins_Sleeper
{
    /**
     * The number of emails to send before restarting Transport.
     *
     * @var int
     */
    private $threshold;

    /**
     * The number of seconds to sleep for during a restart.
     *
     * @var int
     */
    private $sleep;

    /**
     * The internal counter.
     *
     * @var int
     */
    private $counter = 0;

    /**
     * The Sleeper instance for sleeping.
     *
     * @var Swift_Plugins_Sleeper
     */
    private $sleeper;

    /**
     * Create a new AntiFloodPlugin with $threshold and $sleep time.
     *
     * @param int                   $threshold
     * @param int                   $sleep     time
     * @param Swift_Plugins_Sleeper $sleeper   (not needed really)
     */
    public function __construct($threshold = 99, $sleep = 0, Swift_Plugins_Sleeper $sleeper = null)
    {
        $this->setThreshold($threshold);
        $this->setSleepTime($sleep);
        $this->sleeper = $sleeper;
    }

    /**
     * Set the number of emails to send before restarting.
     *
     * @param int $threshold
     */
    public function setThreshold($threshold)
    {
        $this->threshold = $threshold;
    }

    /**
     * Get the number of emails to send before restarting.
     *
     * @return int
     */
    public function getThreshold()
    {
        return $this->threshold;
    }

    /**
     * Set the number of seconds to sleep for during a restart.
     *
     * @param int $sleep time
     */
    public function setSleepTime($sleep)
    {
        $this->sleep = $sleep;
    }

    /**
     * Get the number of seconds to sleep for during a restart.
     *
     * @return int
     */
    public function getSleepTime()
    {
        return $this->sleep;
    }

    /**
     * Invoked immediately before the Message is sent.
     */
    public function beforeSendPerformed(Swift_Events_SendEvent $evt)
    {
    }

    /**
     * Invoked immediately after the Message is sent.
     */
    public function sendPerformed(Swift_Events_SendEvent $evt)
    {
        ++$this->counter;
        if ($this->counter >= $this->threshold) {
            $transport = $evt->getTransport();
            $transport->stop();
            if ($this->sleep) {
                $this->sleep($this->sleep);
            }
            $transport->start();
            $this->counter = 0;
        }
    }

    /**
     * Sleep for $seconds.
     *
     * @param int $seconds
     */
    public function sleep($seconds)
    {
        if (isset($this->sleeper)) {
            $this->sleeper->sleep($seconds);
        } else {
            sleep($seconds);
        }
    }
}


================================================
FILE: lib/classes/Swift/Plugins/BandwidthMonitorPlugin.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Reduces network flooding when sending large amounts of mail.
 *
 * @author Chris Corbyn
 */
class Swift_Plugins_BandwidthMonitorPlugin implements Swift_Events_SendListener, Swift_Events_CommandListener, Swift_Events_ResponseListener, Swift_InputByteStream
{
    /**
     * The outgoing traffic counter.
     *
     * @var int
     */
    private $out = 0;

    /**
     * The incoming traffic counter.
     *
     * @var int
     */
    private $in = 0;

    /** Bound byte streams */
    private $mirrors = [];

    /**
     * Not used.
     */
    public function beforeSendPerformed(Swift_Events_SendEvent $evt)
    {
    }

    /**
     * Invoked immediately after the Message is sent.
     */
    public function sendPerformed(Swift_Events_SendEvent $evt)
    {
        $message = $evt->getMessage();
        $message->toByteStream($this);
    }

    /**
     * Invoked immediately following a command being sent.
     */
    public function commandSent(Swift_Events_CommandEvent $evt)
    {
        $command = $evt->getCommand();
        $this->out += \strlen($command);
    }

    /**
     * Invoked immediately following a response coming back.
     */
    public function responseReceived(Swift_Events_ResponseEvent $evt)
    {
        $response = $evt->getResponse();
        $this->in += \strlen($response);
    }

    /**
     * Called when a message is sent so that the outgoing counter can be increased.
     *
     * @param string $bytes
     */
    public function write($bytes)
    {
        $this->out += \strlen($bytes);
        foreach ($this->mirrors as $stream) {
            $stream->write($bytes);
        }
    }

    /**
     * Not used.
     */
    public function commit()
    {
    }

    /**
     * Attach $is to this stream.
     *
     * The stream acts as an observer, receiving all data that is written.
     * All {@link write()} and {@link flushBuffers()} operations will be mirrored.
     */
    public function bind(Swift_InputByteStream $is)
    {
        $this->mirrors[] = $is;
    }

    /**
     * Remove an already bound stream.
     *
     * If $is is not bound, no errors will be raised.
     * If the stream currently has any buffered data it will be written to $is
     * before unbinding occurs.
     */
    public function unbind(Swift_InputByteStream $is)
    {
        foreach ($this->mirrors as $k => $stream) {
            if ($is === $stream) {
                unset($this->mirrors[$k]);
            }
        }
    }

    /**
     * Not used.
     */
    public function flushBuffers()
    {
        foreach ($this->mirrors as $stream) {
            $stream->flushBuffers();
        }
    }

    /**
     * Get the total number of bytes sent to the server.
     *
     * @return int
     */
    public function getBytesOut()
    {
        return $this->out;
    }

    /**
     * Get the total number of bytes received from the server.
     *
     * @return int
     */
    public function getBytesIn()
    {
        return $this->in;
    }

    /**
     * Reset the internal counters to zero.
     */
    public function reset()
    {
        $this->out = 0;
        $this->in = 0;
    }
}


================================================
FILE: lib/classes/Swift/Plugins/Decorator/Replacements.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Allows customization of Messages on-the-fly.
 *
 * @author Chris Corbyn
 */
interface Swift_Plugins_Decorator_Replacements
{
    /**
     * Return the array of replacements for $address.
     *
     * This method is invoked once for every single recipient of a message.
     *
     * If no replacements can be found, an empty value (NULL) should be returned
     * and no replacements will then be made on the message.
     *
     * @param string $address
     *
     * @return array
     */
    public function getReplacementsFor($address);
}


================================================
FILE: lib/classes/Swift/Plugins/DecoratorPlugin.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Allows customization of Messages on-the-fly.
 *
 * @author Chris Corbyn
 * @author Fabien Potencier
 */
class Swift_Plugins_DecoratorPlugin implements Swift_Events_SendListener, Swift_Plugins_Decorator_Replacements
{
    /** The replacement map */
    private $replacements;

    /** The body as it was before replacements */
    private $originalBody;

    /** The original headers of the message, before replacements */
    private $originalHeaders = [];

    /** Bodies of children before they are replaced */
    private $originalChildBodies = [];

    /** The Message that was last replaced */
    private $lastMessage;

    /**
     * Create a new DecoratorPlugin with $replacements.
     *
     * The $replacements can either be an associative array, or an implementation
     * of {@link Swift_Plugins_Decorator_Replacements}.
     *
     * When using an array, it should be of the form:
     * <code>
     * $replacements = array(
     *  "address1@domain.tld" => array("{a}" => "b", "{c}" => "d"),
     *  "address2@domain.tld" => array("{a}" => "x", "{c}" => "y")
     * )
     * </code>
     *
     * When using an instance of {@link Swift_Plugins_Decorator_Replacements},
     * the object should return just the array of replacements for the address
     * given to {@link Swift_Plugins_Decorator_Replacements::getReplacementsFor()}.
     *
     * @param mixed $replacements Array or Swift_Plugins_Decorator_Replacements
     */
    public function __construct($replacements)
    {
        $this->setReplacements($replacements);
    }

    /**
     * Sets replacements.
     *
     * @param mixed $replacements Array or Swift_Plugins_Decorator_Replacements
     *
     * @see __construct()
     */
    public function setReplacements($replacements)
    {
        if (!($replacements instanceof Swift_Plugins_Decorator_Replacements)) {
            $this->replacements = (array) $replacements;
        } else {
            $this->replacements = $replacements;
        }
    }

    /**
     * Invoked immediately before the Message is sent.
     */
    public function beforeSendPerformed(Swift_Events_SendEvent $evt)
    {
        $message = $evt->getMessage();
        $this->restoreMessage($message);
        $to = array_keys($message->getTo());
        $address = array_shift($to);
        if ($replacements = $this->getReplacementsFor($address)) {
            $body = $message->getBody();
            $search = array_keys($replacements);
            $replace = array_values($replacements);
            $bodyReplaced = str_replace(
                $search, $replace, $body
                );
            if ($body != $bodyReplaced) {
                $this->originalBody = $body;
                $message->setBody($bodyReplaced);
            }

            foreach ($message->getHeaders()->getAll() as $header) {
                $body = $header->getFieldBodyModel();
                $count = 0;
                if (\is_array($body)) {
                    $bodyReplaced = [];
                    foreach ($body as $key => $value) {
                        $count1 = 0;
                        $count2 = 0;
                        $key = \is_string($key) ? str_replace($search, $replace, $key, $count1) : $key;
                        $value = \is_string($value) ? str_replace($search, $replace, $value, $count2) : $value;
                        $bodyReplaced[$key] = $value;

                        if (!$count && ($count1 || $count2)) {
                            $count = 1;
                        }
                    }
                } elseif (\is_string($body)) {
                    $bodyReplaced = str_replace($search, $replace, $body, $count);
                }

                if ($count) {
                    $this->originalHeaders[$header->getFieldName()] = $body;
                    $header->setFieldBodyModel($bodyReplaced);
                }
            }

            $children = (array) $message->getChildren();
            foreach ($children as $child) {
                list($type) = sscanf($child->getContentType(), '%[^/]/%s');
                if ('text' == $type) {
                    $body = $child->getBody();
                    $bodyReplaced = str_replace(
                        $search, $replace, $body
                        );
                    if ($body != $bodyReplaced) {
                        $child->setBody($bodyReplaced);
                        $this->originalChildBodies[$child->getId()] = $body;
                    }
                }
            }
            $this->lastMessage = $message;
        }
    }

    /**
     * Find a map of replacements for the address.
     *
     * If this plugin was provided with a delegate instance of
     * {@link Swift_Plugins_Decorator_Replacements} then the call will be
     * delegated to it.  Otherwise, it will attempt to find the replacements
     * from the array provided in the constructor.
     *
     * If no replacements can be found, an empty value (NULL) is returned.
     *
     * @param string $address
     *
     * @return array
     */
    public function getReplacementsFor($address)
    {
        if ($this->replacements instanceof Swift_Plugins_Decorator_Replacements) {
            return $this->replacements->getReplacementsFor($address);
        }

        return $this->replacements[$address] ?? null;
    }

    /**
     * Invoked immediately after the Message is sent.
     */
    public function sendPerformed(Swift_Events_SendEvent $evt)
    {
        $this->restoreMessage($evt->getMessage());
    }

    /** Restore a changed message back to its original state */
    private function restoreMessage(Swift_Mime_SimpleMessage $message)
    {
        if ($this->lastMessage === $message) {
            if (isset($this->originalBody)) {
                $message->setBody($this->originalBody);
                $this->originalBody = null;
            }
            if (!empty($this->originalHeaders)) {
                foreach ($message->getHeaders()->getAll() as $header) {
                    if (\array_key_exists($header->getFieldName(), $this->originalHeaders)) {
                        $header->setFieldBodyModel($this->originalHeaders[$header->getFieldName()]);
                    }
                }
                $this->originalHeaders = [];
            }
            if (!empty($this->originalChildBodies)) {
                $children = (array) $message->getChildren();
                foreach ($children as $child) {
                    $id = $child->getId();
                    if (\array_key_exists($id, $this->originalChildBodies)) {
                        $child->setBody($this->originalChildBodies[$id]);
                    }
                }
                $this->originalChildBodies = [];
            }
            $this->lastMessage = null;
        }
    }
}


================================================
FILE: lib/classes/Swift/Plugins/ImpersonatePlugin.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2009 Fabien Potencier
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Replaces the sender of a message.
 *
 * @author Arjen Brouwer
 */
class Swift_Plugins_ImpersonatePlugin implements Swift_Events_SendListener
{
    /**
     * The sender to impersonate.
     *
     * @var string
     */
    private $sender;

    /**
     * Create a new ImpersonatePlugin to impersonate $sender.
     *
     * @param string $sender address
     */
    public function __construct($sender)
    {
        $this->sender = $sender;
    }

    /**
     * Invoked immediately before the Message is sent.
     */
    public function beforeSendPerformed(Swift_Events_SendEvent $evt)
    {
        $message = $evt->getMessage();
        $headers = $message->getHeaders();

        // save current recipients
        $headers->addPathHeader('X-Swift-Return-Path', $message->getReturnPath());

        // replace them with the one to send to
        $message->setReturnPath($this->sender);
    }

    /**
     * Invoked immediately after the Message is sent.
     */
    public function sendPerformed(Swift_Events_SendEvent $evt)
    {
        $message = $evt->getMessage();

        // restore original headers
        $headers = $message->getHeaders();

        if ($headers->has('X-Swift-Return-Path')) {
            $message->setReturnPath($headers->get('X-Swift-Return-Path')->getAddress());
            $headers->removeAll('X-Swift-Return-Path');
        }
    }
}


================================================
FILE: lib/classes/Swift/Plugins/Logger.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Logs events in the Transport system.
 *
 * @author Chris Corbyn
 */
interface Swift_Plugins_Logger
{
    /**
     * Add a log entry.
     *
     * @param string $entry
     */
    public function add($entry);

    /**
     * Clear the log contents.
     */
    public function clear();

    /**
     * Get this log as a string.
     *
     * @return string
     */
    public function dump();
}


================================================
FILE: lib/classes/Swift/Plugins/LoggerPlugin.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Does real time logging of Transport level information.
 *
 * @author     Chris Corbyn
 */
class Swift_Plugins_LoggerPlugin implements Swift_Events_CommandListener, Swift_Events_ResponseListener, Swift_Events_TransportChangeListener, Swift_Events_TransportExceptionListener, Swift_Plugins_Logger
{
    /** The logger which is delegated to */
    private $logger;

    /**
     * Create a new LoggerPlugin using $logger.
     */
    public function __construct(Swift_Plugins_Logger $logger)
    {
        $this->logger = $logger;
    }

    /**
     * Add a log entry.
     *
     * @param string $entry
     */
    public function add($entry)
    {
        $this->logger->add($entry);
    }

    /**
     * Clear the log contents.
     */
    public function clear()
    {
        $this->logger->clear();
    }

    /**
     * Get this log as a string.
     *
     * @return string
     */
    public function dump()
    {
        return $this->logger->dump();
    }

    /**
     * Invoked immediately following a command being sent.
     */
    public function commandSent(Swift_Events_CommandEvent $evt)
    {
        $command = $evt->getCommand();
        $this->logger->add(sprintf('>> %s', $command));
    }

    /**
     * Invoked immediately following a response coming back.
     */
    public function responseReceived(Swift_Events_ResponseEvent $evt)
    {
        $response = $evt->getResponse();
        $this->logger->add(sprintf('<< %s', $response));
    }

    /**
     * Invoked just before a Transport is started.
     */
    public function beforeTransportStarted(Swift_Events_TransportChangeEvent $evt)
    {
        $transportName = \get_class($evt->getSource());
        $this->logger->add(sprintf('++ Starting %s', $transportName));
    }

    /**
     * Invoked immediately after the Transport is started.
     */
    public function transportStarted(Swift_Events_TransportChangeEvent $evt)
    {
        $transportName = \get_class($evt->getSource());
        $this->logger->add(sprintf('++ %s started', $transportName));
    }

    /**
     * Invoked just before a Transport is stopped.
     */
    public function beforeTransportStopped(Swift_Events_TransportChangeEvent $evt)
    {
        $transportName = \get_class($evt->getSource());
        $this->logger->add(sprintf('++ Stopping %s', $transportName));
    }

    /**
     * Invoked immediately after the Transport is stopped.
     */
    public function transportStopped(Swift_Events_TransportChangeEvent $evt)
    {
        $transportName = \get_class($evt->getSource());
        $this->logger->add(sprintf('++ %s stopped', $transportName));
    }

    /**
     * Invoked as a TransportException is thrown in the Transport system.
     */
    public function exceptionThrown(Swift_Events_TransportExceptionEvent $evt)
    {
        $e = $evt->getException();
        $message = $e->getMessage();
        $code = $e->getCode();
        $this->logger->add(sprintf('!! %s (code: %s)', $message, $code));
        $message .= PHP_EOL;
        $message .= 'Log data:'.PHP_EOL;
        $message .= $this->logger->dump();
        $evt->cancelBubble();
        throw new Swift_TransportException($message, $code, $e->getPrevious());
    }
}


================================================
FILE: lib/classes/Swift/Plugins/Loggers/ArrayLogger.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Logs to an Array backend.
 *
 * @author Chris Corbyn
 */
class Swift_Plugins_Loggers_ArrayLogger implements Swift_Plugins_Logger
{
    /**
     * The log contents.
     *
     * @var array
     */
    private $log = [];

    /**
     * Max size of the log.
     *
     * @var int
     */
    private $size = 0;

    /**
     * Create a new ArrayLogger with a maximum of $size entries.
     *
     * @var int
     */
    public function __construct($size = 50)
    {
        $this->size = $size;
    }

    /**
     * Add a log entry.
     *
     * @param string $entry
     */
    public function add($entry)
    {
        $this->log[] = $entry;
        while (\count($this->log) > $this->size) {
            array_shift($this->log);
        }
    }

    /**
     * Clear the log contents.
     */
    public function clear()
    {
        $this->log = [];
    }

    /**
     * Get this log as a string.
     *
     * @return string
     */
    public function dump()
    {
        return implode(PHP_EOL, $this->log);
    }
}


================================================
FILE: lib/classes/Swift/Plugins/Loggers/EchoLogger.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Prints all log messages in real time.
 *
 * @author Chris Corbyn
 */
class Swift_Plugins_Loggers_EchoLogger implements Swift_Plugins_Logger
{
    /** Whether or not HTML should be output */
    private $isHtml;

    /**
     * Create a new EchoLogger.
     *
     * @param bool $isHtml
     */
    public function __construct($isHtml = true)
    {
        $this->isHtml = $isHtml;
    }

    /**
     * Add a log entry.
     *
     * @param string $entry
     */
    public function add($entry)
    {
        if ($this->isHtml) {
            printf('%s%s%s', htmlspecialchars($entry, ENT_QUOTES), '<br />', PHP_EOL);
        } else {
            printf('%s%s', $entry, PHP_EOL);
        }
    }

    /**
     * Not implemented.
     */
    public function clear()
    {
    }

    /**
     * Not implemented.
     */
    public function dump()
    {
    }
}


================================================
FILE: lib/classes/Swift/Plugins/MessageLogger.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2011 Fabien Potencier
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Stores all sent emails for further usage.
 *
 * @author Fabien Potencier
 */
class Swift_Plugins_MessageLogger implements Swift_Events_SendListener
{
    /**
     * @var Swift_Mime_SimpleMessage[]
     */
    private $messages;

    public function __construct()
    {
        $this->messages = [];
    }

    /**
     * Get the message list.
     *
     * @return Swift_Mime_SimpleMessage[]
     */
    public function getMessages()
    {
        return $this->messages;
    }

    /**
     * Get the message count.
     *
     * @return int count
     */
    public function countMessages()
    {
        return \count($this->messages);
    }

    /**
     * Empty the message list.
     */
    public function clear()
    {
        $this->messages = [];
    }

    /**
     * Invoked immediately before the Message is sent.
     */
    public function beforeSendPerformed(Swift_Events_SendEvent $evt)
    {
        $this->messages[] = clone $evt->getMessage();
    }

    /**
     * Invoked immediately after the Message is sent.
     */
    public function sendPerformed(Swift_Events_SendEvent $evt)
    {
    }
}


================================================
FILE: lib/classes/Swift/Plugins/Pop/Pop3Connection.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Pop3Connection interface for connecting and disconnecting to a POP3 host.
 *
 * @author Chris Corbyn
 */
interface Swift_Plugins_Pop_Pop3Connection
{
    /**
     * Connect to the POP3 host and throw an Exception if it fails.
     *
     * @throws Swift_Plugins_Pop_Pop3Exception
     */
    public function connect();

    /**
     * Disconnect from the POP3 host and throw an Exception if it fails.
     *
     * @throws Swift_Plugins_Pop_Pop3Exception
     */
    public function disconnect();
}


================================================
FILE: lib/classes/Swift/Plugins/Pop/Pop3Exception.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Pop3Exception thrown when an error occurs connecting to a POP3 host.
 *
 * @author Chris Corbyn
 */
class Swift_Plugins_Pop_Pop3Exception extends Swift_IoException
{
    /**
     * Create a new Pop3Exception with $message.
     *
     * @param string $message
     */
    public function __construct($message)
    {
        parent::__construct($message);
    }
}


================================================
FILE: lib/classes/Swift/Plugins/PopBeforeSmtpPlugin.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Makes sure a connection to a POP3 host has been established prior to connecting to SMTP.
 *
 * @author     Chris Corbyn
 */
class Swift_Plugins_PopBeforeSmtpPlugin implements Swift_Events_TransportChangeListener, Swift_Plugins_Pop_Pop3Connection
{
    /** A delegate connection to use (mostly a test hook) */
    private $connection;

    /** Hostname of the POP3 server */
    private $host;

    /** Port number to connect on */
    private $port;

    /** Encryption type to use (if any) */
    private $crypto;

    /** Username to use (if any) */
    private $username;

    /** Password to use (if any) */
    private $password;

    /** Established connection via TCP socket */
    private $socket;

    /** Connect timeout in seconds */
    private $timeout = 10;

    /** SMTP Transport to bind to */
    private $transport;

    /**
     * Create a new PopBeforeSmtpPlugin for $host and $port.
     *
     * @param string $host   Hostname or IP. Literal IPv6 addresses should be
     *                       wrapped in square brackets.
     * @param int    $port
     * @param string $crypto as "tls" or "ssl"
     */
    public function __construct($host, $port = 110, $crypto = null)
    {
        $this->host = $host;
        $this->port = $port;
        $this->crypto = $crypto;
    }

    /**
     * Set a Pop3Connection to delegate to instead of connecting directly.
     *
     * @return $this
     */
    public function setConnection(Swift_Plugins_Pop_Pop3Connection $connection)
    {
        $this->connection = $connection;

        return $this;
    }

    /**
     * Bind this plugin to a specific SMTP transport instance.
     */
    public function bindSmtp(Swift_Transport $smtp)
    {
        $this->transport = $smtp;
    }

    /**
     * Set the connection timeout in seconds (default 10).
     *
     * @param int $timeout
     *
     * @return $this
     */
    public function setTimeout($timeout)
    {
        $this->timeout = (int) $timeout;

        return $this;
    }

    /**
     * Set the username to use when connecting (if needed).
     *
     * @param string $username
     *
     * @return $this
     */
    public function setUsername($username)
    {
        $this->username = $username;

        return $this;
    }

    /**
     * Set the password to use when connecting (if needed).
     *
     * @param string $password
     *
     * @return $this
     */
    public function setPassword($password)
    {
        $this->password = $password;

        return $this;
    }

    /**
     * Connect to the POP3 host and authenticate.
     *
     * @throws Swift_Plugins_Pop_Pop3Exception if connection fails
     */
    public function connect()
    {
        if (isset($this->connection)) {
            $this->connection->connect();
        } else {
            if (!isset($this->socket)) {
                if (!$socket = fsockopen(
                    $this->getHostString(), $this->port, $errno, $errstr, $this->timeout)) {
                    throw new Swift_Plugins_Pop_Pop3Exception(sprintf('Failed to connect to POP3 host [%s]: %s', $this->host, $errstr));
                }
                $this->socket = $socket;

                if (false === $greeting = fgets($this->socket)) {
                    throw new Swift_Plugins_Pop_Pop3Exception(sprintf('Failed to connect to POP3 host [%s]', trim($greeting ?? '')));
                }

                $this->assertOk($greeting);

                if ($this->username) {
                    $this->command(sprintf("USER %s\r\n", $this->username));
                    $this->command(sprintf("PASS %s\r\n", $this->password));
                }
            }
        }
    }

    /**
     * Disconnect from the POP3 host.
     */
    public function disconnect()
    {
        if (isset($this->connection)) {
            $this->connection->disconnect();
        } else {
            $this->command("QUIT\r\n");
            if (!fclose($this->socket)) {
                throw new Swift_Plugins_Pop_Pop3Exception(sprintf('POP3 host [%s] connection could not be stopped', $this->host));
            }
            $this->socket = null;
        }
    }

    /**
     * Invoked just before a Transport is started.
     */
    public function beforeTransportStarted(Swift_Events_TransportChangeEvent $evt)
    {
        if (isset($this->transport)) {
            if ($this->transport !== $evt->getTransport()) {
                return;
            }
        }

        $this->connect();
        $this->disconnect();
    }

    /**
     * Not used.
     */
    public function transportStarted(Swift_Events_TransportChangeEvent $evt)
    {
    }

    /**
     * Not used.
     */
    public function beforeTransportStopped(Swift_Events_TransportChangeEvent $evt)
    {
    }

    /**
     * Not used.
     */
    public function transportStopped(Swift_Events_TransportChangeEvent $evt)
    {
    }

    private function command($command)
    {
        if (!fwrite($this->socket, $command)) {
            throw new Swift_Plugins_Pop_Pop3Exception(sprintf('Failed to write command [%s] to POP3 host', trim($command ?? '')));
        }

        if (false === $response = fgets($this->socket)) {
            throw new Swift_Plugins_Pop_Pop3Exception(sprintf('Failed to read from POP3 host after command [%s]', trim($command ?? '')));
        }

        $this->assertOk($response);

        return $response;
    }

    private function assertOk($response)
    {
        if ('+OK' != substr($response, 0, 3)) {
            throw new Swift_Plugins_Pop_Pop3Exception(sprintf('POP3 command failed [%s]', trim($response ?? '')));
        }
    }

    private function getHostString()
    {
        $host = $this->host;
        switch (strtolower($this->crypto ?? '')) {
            case 'ssl':
                $host = 'ssl://'.$host;
                break;

            case 'tls':
                $host = 'tls://'.$host;
                break;
        }

        return $host;
    }
}


================================================
FILE: lib/classes/Swift/Plugins/RedirectingPlugin.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2009 Fabien Potencier
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Redirects all email to a single recipient.
 *
 * @author     Fabien Potencier
 */
class Swift_Plugins_RedirectingPlugin implements Swift_Events_SendListener
{
    /**
     * The recipient who will receive all messages.
     *
     * @var mixed
     */
    private $recipient;

    /**
     * List of regular expression for recipient whitelisting.
     *
     * @var array
     */
    private $whitelist = [];

    /**
     * Create a new RedirectingPlugin.
     *
     * @param mixed $recipient
     */
    public function __construct($recipient, array $whitelist = [])
    {
        $this->recipient = $recipient;
        $this->whitelist = $whitelist;
    }

    /**
     * Set the recipient of all messages.
     *
     * @param mixed $recipient
     */
    public function setRecipient($recipient)
    {
        $this->recipient = $recipient;
    }

    /**
     * Get the recipient of all messages.
     *
     * @return mixed
     */
    public function getRecipient()
    {
        return $this->recipient;
    }

    /**
     * Set a list of regular expressions to whitelist certain recipients.
     */
    public function setWhitelist(array $whitelist)
    {
        $this->whitelist = $whitelist;
    }

    /**
     * Get the whitelist.
     *
     * @return array
     */
    public function getWhitelist()
    {
        return $this->whitelist;
    }

    /**
     * Invoked immediately before the Message is sent.
     */
    public function beforeSendPerformed(Swift_Events_SendEvent $evt)
    {
        $message = $evt->getMessage();
        $headers = $message->getHeaders();

        // conditionally save current recipients

        if ($headers->has('to')) {
            $headers->addMailboxHeader('X-Swift-To', $message->getTo());
        }

        if ($headers->has('cc')) {
            $headers->addMailboxHeader('X-Swift-Cc', $message->getCc());
        }

        if ($headers->has('bcc')) {
            $headers->addMailboxHeader('X-Swift-Bcc', $message->getBcc());
        }

        // Filter remaining headers against whitelist
        $this->filterHeaderSet($headers, 'To');
        $this->filterHeaderSet($headers, 'Cc');
        $this->filterHeaderSet($headers, 'Bcc');

        // Add each hard coded recipient
        $to = $message->getTo();
        if (null === $to) {
            $to = [];
        }

        foreach ((array) $this->recipient as $recipient) {
            if (!\array_key_exists($recipient, $to)) {
                $message->addTo($recipient);
            }
        }
    }

    /**
     * Filter header set against a whitelist of regular expressions.
     *
     * @param string $type
     */
    private function filterHeaderSet(Swift_Mime_SimpleHeaderSet $headerSet, $type)
    {
        foreach ($headerSet->getAll($type) as $headers) {
            $headers->setNameAddresses($this->filterNameAddresses($headers->getNameAddresses()));
        }
    }

    /**
     * Filtered list of addresses => name pairs.
     *
     * @return array
     */
    private function filterNameAddresses(array $recipients)
    {
        $filtered = [];

        foreach ($recipients as $address => $name) {
            if ($this->isWhitelisted($address)) {
                $filtered[$address] = $name;
            }
        }

        return $filtered;
    }

    /**
     * Matches address against whitelist of regular expressions.
     *
     * @return bool
     */
    protected function isWhitelisted($recipient)
    {
        if (\in_array($recipient, (array) $this->recipient)) {
            return true;
        }

        foreach ($this->whitelist as $pattern) {
            if (preg_match($pattern, $recipient)) {
                return true;
            }
        }

        return false;
    }

    /**
     * Invoked immediately after the Message is sent.
     */
    public function sendPerformed(Swift_Events_SendEvent $evt)
    {
        $this->restoreMessage($evt->getMessage());
    }

    private function restoreMessage(Swift_Mime_SimpleMessage $message)
    {
        // restore original headers
        $headers = $message->getHeaders();

        if ($headers->has('X-Swift-To')) {
            $message->setTo($headers->get('X-Swift-To')->getNameAddresses());
            $headers->removeAll('X-Swift-To');
        } else {
            $message->setTo(null);
        }

        if ($headers->has('X-Swift-Cc')) {
            $message->setCc($headers->get('X-Swift-Cc')->getNameAddresses());
            $headers->removeAll('X-Swift-Cc');
        }

        if ($headers->has('X-Swift-Bcc')) {
            $message->setBcc($headers->get('X-Swift-Bcc')->getNameAddresses());
            $headers->removeAll('X-Swift-Bcc');
        }
    }
}


================================================
FILE: lib/classes/Swift/Plugins/Reporter.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * The Reporter plugin sends pass/fail notification to a Reporter.
 *
 * @author Chris Corbyn
 */
interface Swift_Plugins_Reporter
{
    /** The recipient was accepted for delivery */
    const RESULT_PASS = 0x01;

    /** The recipient could not be accepted */
    const RESULT_FAIL = 0x10;

    /**
     * Notifies this ReportNotifier that $address failed or succeeded.
     *
     * @param string $address
     * @param int    $result  from {@link RESULT_PASS, RESULT_FAIL}
     */
    public function notify(Swift_Mime_SimpleMessage $message, $address, $result);
}


================================================
FILE: lib/classes/Swift/Plugins/ReporterPlugin.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Does real time reporting of pass/fail for each recipient.
 *
 * @author Chris Corbyn
 */
class Swift_Plugins_ReporterPlugin implements Swift_Events_SendListener
{
    /**
     * The reporter backend which takes notifications.
     *
     * @var Swift_Plugins_Reporter
     */
    private $reporter;

    /**
     * Create a new ReporterPlugin using $reporter.
     */
    public function __construct(Swift_Plugins_Reporter $reporter)
    {
        $this->reporter = $reporter;
    }

    /**
     * Not used.
     */
    public function beforeSendPerformed(Swift_Events_SendEvent $evt)
    {
    }

    /**
     * Invoked immediately after the Message is sent.
     */
    public function sendPerformed(Swift_Events_SendEvent $evt)
    {
        $message = $evt->getMessage();
        $failures = array_flip($evt->getFailedRecipients());
        foreach ((array) $message->getTo() as $address => $null) {
            $this->reporter->notify($message, $address, (\array_key_exists($address, $failures) ? Swift_Plugins_Reporter::RESULT_FAIL : Swift_Plugins_Reporter::RESULT_PASS));
        }
        foreach ((array) $message->getCc() as $address => $null) {
            $this->reporter->notify($message, $address, (\array_key_exists($address, $failures) ? Swift_Plugins_Reporter::RESULT_FAIL : Swift_Plugins_Reporter::RESULT_PASS));
        }
        foreach ((array) $message->getBcc() as $address => $null) {
            $this->reporter->notify($message, $address, (\array_key_exists($address, $failures) ? Swift_Plugins_Reporter::RESULT_FAIL : Swift_Plugins_Reporter::RESULT_PASS));
        }
    }
}


================================================
FILE: lib/classes/Swift/Plugins/Reporters/HitReporter.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * A reporter which "collects" failures for the Reporter plugin.
 *
 * @author Chris Corbyn
 */
class Swift_Plugins_Reporters_HitReporter implements Swift_Plugins_Reporter
{
    /**
     * The list of failures.
     *
     * @var array
     */
    private $failures = [];

    private $failures_cache = [];

    /**
     * Notifies this ReportNotifier that $address failed or succeeded.
     *
     * @param string $address
     * @param int    $result  from {@link RESULT_PASS, RESULT_FAIL}
     */
    public function notify(Swift_Mime_SimpleMessage $message, $address, $result)
    {
        if (self::RESULT_FAIL == $result && !isset($this->failures_cache[$address])) {
            $this->failures[] = $address;
            $this->failures_cache[$address] = true;
        }
    }

    /**
     * Get an array of addresses for which delivery failed.
     *
     * @return array
     */
    public function getFailedRecipients()
    {
        return $this->failures;
    }

    /**
     * Clear the buffer (empty the list).
     */
    public function clear()
    {
        $this->failures = $this->failures_cache = [];
    }
}


================================================
FILE: lib/classes/Swift/Plugins/Reporters/HtmlReporter.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * A HTML output reporter for the Reporter plugin.
 *
 * @author Chris Corbyn
 */
class Swift_Plugins_Reporters_HtmlReporter implements Swift_Plugins_Reporter
{
    /**
     * Notifies this ReportNotifier that $address failed or succeeded.
     *
     * @param string $address
     * @param int    $result  from {@see RESULT_PASS, RESULT_FAIL}
     */
    public function notify(Swift_Mime_SimpleMessage $message, $address, $result)
    {
        if (self::RESULT_PASS == $result) {
            echo '<div style="color: #fff; background: #006600; padding: 2px; margin: 2px;">'.PHP_EOL;
            echo 'PASS '.$address.PHP_EOL;
            echo '</div>'.PHP_EOL;
            flush();
        } else {
            echo '<div style="color: #fff; background: #880000; padding: 2px; margin: 2px;">'.PHP_EOL;
            echo 'FAIL '.$address.PHP_EOL;
            echo '</div>'.PHP_EOL;
            flush();
        }
    }
}


================================================
FILE: lib/classes/Swift/Plugins/Sleeper.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Sleeps for a duration of time.
 *
 * @author Chris Corbyn
 */
interface Swift_Plugins_Sleeper
{
    /**
     * Sleep for $seconds.
     *
     * @param int $seconds
     */
    public function sleep($seconds);
}


================================================
FILE: lib/classes/Swift/Plugins/ThrottlerPlugin.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Throttles the rate at which emails are sent.
 *
 * @author Chris Corbyn
 */
class Swift_Plugins_ThrottlerPlugin extends Swift_Plugins_BandwidthMonitorPlugin implements Swift_Plugins_Sleeper, Swift_Plugins_Timer
{
    /** Flag for throttling in bytes per minute */
    const BYTES_PER_MINUTE = 0x01;

    /** Flag for throttling in emails per second (Amazon SES) */
    const MESSAGES_PER_SECOND = 0x11;

    /** Flag for throttling in emails per minute */
    const MESSAGES_PER_MINUTE = 0x10;

    /**
     * The Sleeper instance for sleeping.
     *
     * @var Swift_Plugins_Sleeper
     */
    private $sleeper;

    /**
     * The Timer instance which provides the timestamp.
     *
     * @var Swift_Plugins_Timer
     */
    private $timer;

    /**
     * The time at which the first email was sent.
     *
     * @var int
     */
    private $start;

    /**
     * The rate at which messages should be sent.
     *
     * @var int
     */
    private $rate;

    /**
     * The mode for throttling.
     *
     * This is {@link BYTES_PER_MINUTE} or {@link MESSAGES_PER_MINUTE}
     *
     * @var int
     */
    private $mode;

    /**
     * An internal counter of the number of messages sent.
     *
     * @var int
     */
    private $messages = 0;

    /**
     * Create a new ThrottlerPlugin.
     *
     * @param int                   $rate
     * @param int                   $mode    defaults to {@link BYTES_PER_MINUTE}
     * @param Swift_Plugins_Sleeper $sleeper (only needed in testing)
     * @param Swift_Plugins_Timer   $timer   (only needed in testing)
     */
    public function __construct($rate, $mode = self::BYTES_PER_MINUTE, Swift_Plugins_Sleeper $sleeper = null, Swift_Plugins_Timer $timer = null)
    {
        $this->rate = $rate;
        $this->mode = $mode;
        $this->sleeper = $sleeper;
        $this->timer = $timer;
    }

    /**
     * Invoked immediately before the Message is sent.
     */
    public function beforeSendPerformed(Swift_Events_SendEvent $evt)
    {
        $time = $this->getTimestamp();
        if (!isset($this->start)) {
            $this->start = $time;
        }
        $duration = $time - $this->start;

        switch ($this->mode) {
            case self::BYTES_PER_MINUTE:
                $sleep = $this->throttleBytesPerMinute($duration);
                break;
            case self::MESSAGES_PER_SECOND:
                $sleep = $this->throttleMessagesPerSecond($duration);
                break;
            case self::MESSAGES_PER_MINUTE:
                $sleep = $this->throttleMessagesPerMinute($duration);
                break;
            default:
                $sleep = 0;
                break;
        }

        if ($sleep > 0) {
            $this->sleep($sleep);
        }
    }

    /**
     * Invoked when a Message is sent.
     */
    public function sendPerformed(Swift_Events_SendEvent $evt)
    {
        parent::sendPerformed($evt);
        ++$this->messages;
    }

    /**
     * Sleep for $seconds.
     *
     * @param int $seconds
     */
    public function sleep($seconds)
    {
        if (isset($this->sleeper)) {
            $this->sleeper->sleep($seconds);
        } else {
            sleep($seconds);
        }
    }

    /**
     * Get the current UNIX timestamp.
     *
     * @return int
     */
    public function getTimestamp()
    {
        if (isset($this->timer)) {
            return $this->timer->getTimestamp();
        }

        return time();
    }

    /**
     * Get a number of seconds to sleep for.
     *
     * @param int $timePassed
     *
     * @return int
     */
    private function throttleBytesPerMinute($timePassed)
    {
        $expectedDuration = $this->getBytesOut() / ($this->rate / 60);

        return (int) ceil($expectedDuration - $timePassed);
    }

    /**
     * Get a number of seconds to sleep for.
     *
     * @param int $timePassed
     *
     * @return int
     */
    private function throttleMessagesPerSecond($timePassed)
    {
        $expectedDuration = $this->messages / $this->rate;

        return (int) ceil($expectedDuration - $timePassed);
    }

    /**
     * Get a number of seconds to sleep for.
     *
     * @param int $timePassed
     *
     * @return int
     */
    private function throttleMessagesPerMinute($timePassed)
    {
        $expectedDuration = $this->messages / ($this->rate / 60);

        return (int) ceil($expectedDuration - $timePassed);
    }
}


================================================
FILE: lib/classes/Swift/Plugins/Timer.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Provides timestamp data.
 *
 * @author Chris Corbyn
 */
interface Swift_Plugins_Timer
{
    /**
     * Get the current UNIX timestamp.
     *
     * @return int
     */
    public function getTimestamp();
}


================================================
FILE: lib/classes/Swift/Preferences.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Changes some global preference settings in Swift Mailer.
 *
 * @author Chris Corbyn
 */
class Swift_Preferences
{
    /** Singleton instance */
    private static $instance = null;

    /** Constructor not to be used */
    private function __construct()
    {
    }

    /**
     * Gets the instance of Preferences.
     *
     * @return self
     */
    public static function getInstance()
    {
        if (!isset(self::$instance)) {
            self::$instance = new self();
        }

        return self::$instance;
    }

    /**
     * Set the default charset used.
     *
     * @param string $charset
     *
     * @return $this
     */
    public function setCharset($charset)
    {
        Swift_DependencyContainer::getInstance()->register('properties.charset')->asValue($charset);

        return $this;
    }

    /**
     * Set the directory where temporary files can be saved.
     *
     * @param string $dir
     *
     * @return $this
     */
    public function setTempDir($dir)
    {
        Swift_DependencyContainer::getInstance()->register('tempdir')->asValue($dir);

        return $this;
    }

    /**
     * Set the type of cache to use (i.e. "disk" or "array").
     *
     * @param string $type
     *
     * @return $this
     */
    public function setCacheType($type)
    {
        Swift_DependencyContainer::getInstance()->register('cache')->asAliasOf(sprintf('cache.%s', $type));

        return $this;
    }

    /**
     * Set the QuotedPrintable dot escaper preference.
     *
     * @param bool $dotEscape
     *
     * @return $this
     */
    public function setQPDotEscape($dotEscape)
    {
        $dotEscape = !empty($dotEscape);
        Swift_DependencyContainer::getInstance()
            ->register('mime.qpcontentencoder')
            ->asNewInstanceOf('Swift_Mime_ContentEncoder_QpContentEncoder')
            ->withDependencies(['mime.charstream', 'mime.bytecanonicalizer'])
            ->addConstructorValue($dotEscape);

        return $this;
    }
}


================================================
FILE: lib/classes/Swift/ReplacementFilterFactory.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Creates StreamFilters.
 *
 * @author Chris Corbyn
 */
interface Swift_ReplacementFilterFactory
{
    /**
     * Create a filter to replace $search with $replace.
     *
     * @param mixed $search
     * @param mixed $replace
     *
     * @return Swift_StreamFilter
     */
    public function createFilter($search, $replace);
}


================================================
FILE: lib/classes/Swift/RfcComplianceException.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * RFC Compliance Exception class.
 *
 * @author Chris Corbyn
 */
class Swift_RfcComplianceException extends Swift_SwiftException
{
    /**
     * Create a new RfcComplianceException with $message.
     *
     * @param string $message
     */
    public function __construct($message)
    {
        parent::__construct($message);
    }
}


================================================
FILE: lib/classes/Swift/SendmailTransport.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * SendmailTransport for sending mail through a Sendmail/Postfix (etc..) binary.
 *
 * @author Chris Corbyn
 */
class Swift_SendmailTransport extends Swift_Transport_SendmailTransport
{
    /**
     * Create a new SendmailTransport, optionally using $command for sending.
     *
     * @param string $command
     */
    public function __construct($command = '/usr/sbin/sendmail -bs')
    {
        \call_user_func_array(
            [$this, 'Swift_Transport_SendmailTransport::__construct'],
            Swift_DependencyContainer::getInstance()
                ->createDependenciesFor('transport.sendmail')
            );

        $this->setCommand($command);
    }
}


================================================
FILE: lib/classes/Swift/Signer.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Base Class of Signer Infrastructure.
 *
 * @author Xavier De Cock <xdecock@gmail.com>
 */
interface Swift_Signer
{
    public function reset();
}


================================================
FILE: lib/classes/Swift/Signers/BodySigner.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Body Signer Interface used to apply Body-Based Signature to a message.
 *
 * @author Xavier De Cock <xdecock@gmail.com>
 */
interface Swift_Signers_BodySigner extends Swift_Signer
{
    /**
     * Change the Swift_Signed_Message to apply the singing.
     *
     * @return self
     */
    public function signMessage(Swift_Message $message);

    /**
     * Return the list of header a signer might tamper.
     *
     * @return array
     */
    public function getAlteredHeaders();
}


================================================
FILE: lib/classes/Swift/Signers/DKIMSigner.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * DKIM Signer used to apply DKIM Signature to a message.
 *
 * @author     Xavier De Cock <xdecock@gmail.com>
 */
class Swift_Signers_DKIMSigner implements Swift_Signers_HeaderSigner
{
    /**
     * PrivateKey.
     *
     * @var string
     */
    protected $privateKey;

    /**
     * DomainName.
     *
     * @var string
     */
    protected $domainName;

    /**
     * Selector.
     *
     * @var string
     */
    protected $selector;

    private $passphrase = '';

    /**
     * Hash algorithm used.
     *
     * @see RFC6376 3.3: Signers MUST implement and SHOULD sign using rsa-sha256.
     *
     * @var string
     */
    protected $hashAlgorithm = 'rsa-sha256';

    /**
     * Body canon method.
     *
     * @var string
     */
    protected $bodyCanon = 'simple';

    /**
     * Header canon method.
     *
     * @var string
     */
    protected $headerCanon = 'simple';

    /**
     * Headers not being signed.
     *
     * @var array
     */
    protected $ignoredHeaders = ['return-path' => true];

    /**
     * Signer identity.
     *
     * @var string
     */
    protected $signerIdentity;

    /**
     * BodyLength.
     *
     * @var int
     */
    protected $bodyLen = 0;

    /**
     * Maximum signedLen.
     *
     * @var int
     */
    protected $maxLen = PHP_INT_MAX;

    /**
     * Embbed bodyLen in signature.
     *
     * @var bool
     */
    protected $showLen = false;

    /**
     * When the signature has been applied (true means time()), false means not embedded.
     *
     * @var mixed
     */
    protected $signatureTimestamp = true;

    /**
     * When will the signature expires false means not embedded, if sigTimestamp is auto
     * Expiration is relative, otherwise it's absolute.
     *
     * @var int
     */
    protected $signatureExpiration = false;

    /**
     * Must we embed signed headers?
     *
     * @var bool
     */
    protected $debugHeaders = false;

    // work variables
    /**
     * Headers used to generate hash.
     *
     * @var array
     */
    protected $signedHeaders = [];

    /**
     * If debugHeaders is set store debugData here.
     *
     * @var string[]
     */
    private $debugHeadersData = [];

    /**
     * Stores the bodyHash.
     *
     * @var string
     */
    private $bodyHash = '';

    /**
     * Stores the signature header.
     *
     * @var Swift_Mime_Headers_ParameterizedHeader
     */
    protected $dkimHeader;

    private $bodyHashHandler;

    private $headerHash;

    private $headerCanonData = '';

    private $bodyCanonEmptyCounter = 0;

    private $bodyCanonIgnoreStart = 2;

    private $bodyCanonSpace = false;

    private $bodyCanonLastChar = null;

    private $bodyCanonLine = '';

    private $bound = [];

    /**
     * Constructor.
     *
     * @param string $privateKey
     * @param string $domainName
     * @param string $selector
     * @param string $passphrase
     */
    public function __construct($privateKey, $domainName, $selector, $passphrase = '')
    {
        $this->privateKey = $privateKey;
        $this->domainName = $domainName;
        $this->signerIdentity = '@'.$domainName;
        $this->selector = $selector;
        $this->passphrase = $passphrase;
    }

    /**
     * Reset the Signer.
     *
     * @see Swift_Signer::reset()
     */
    public function reset()
    {
        $this->headerHash = null;
        $this->signedHeaders = [];
        $this->bodyHash = null;
        $this->bodyHashHandler = null;
        $this->bodyCanonIgnoreStart = 2;
        $this->bodyCanonEmptyCounter = 0;
        $this->bodyCanonLastChar = null;
        $this->bodyCanonSpace = false;
    }

    /**
     * Writes $bytes to the end of the stream.
     *
     * Writing may not happen immediately if the stream chooses to buffer.  If
     * you want to write these bytes with immediate effect, call {@link commit()}
     * after calling write().
     *
     * This method returns the sequence ID of the write (i.e. 1 for first, 2 for
     * second, etc etc).
     *
     * @param string $bytes
     *
     * @return int
     *
     * @throws Swift_IoException
     */
    // TODO fix return
    public function write($bytes)
    {
        $this->canonicalizeBody($bytes);
        foreach ($this->bound as $is) {
            $is->write($bytes);
        }
    }

    /**
     * For any bytes that are currently buffered inside the stream, force them
     * off the buffer.
     */
    public function commit()
    {
        // Nothing to do
        return;
    }

    /**
     * Attach $is to this stream.
     *
     * The stream acts as an observer, receiving all data that is written.
     * All {@link write()} and {@link flushBuffers()} operations will be mirrored.
     */
    public function bind(Swift_InputByteStream $is)
    {
        // Don't have to mirror anything
        $this->bound[] = $is;

        return;
    }

    /**
     * Remove an already bound stream.
     *
     * If $is is not bound, no errors will be raised.
     * If the stream currently has any buffered data it will be written to $is
     * before unbinding occurs.
     */
    public function unbind(Swift_InputByteStream $is)
    {
        // Don't have to mirror anything
        foreach ($this->bound as $k => $stream) {
            if ($stream === $is) {
                unset($this->bound[$k]);

                return;
            }
        }
    }

    /**
     * Flush the contents of the stream (empty it) and set the internal pointer
     * to the beginning.
     *
     * @throws Swift_IoException
     */
    public function flushBuffers()
    {
        $this->reset();
    }

    /**
     * Set hash_algorithm, must be one of rsa-sha256 | rsa-sha1.
     *
     * @param string $hash 'rsa-sha1' or 'rsa-sha256'
     *
     * @throws Swift_SwiftException
     *
     * @return $this
     */
    public function setHashAlgorithm($hash)
    {
        switch ($hash) {
            case 'rsa-sha1':
                $this->hashAlgorithm = 'rsa-sha1';
                break;
            case 'rsa-sha256':
                $this->hashAlgorithm = 'rsa-sha256';
                if (!\defined('OPENSSL_ALGO_SHA256')) {
                    throw new Swift_SwiftException('Unable to set sha256 as it is not supported by OpenSSL.');
                }
                break;
            default:
                throw new Swift_SwiftException('Unable to set the hash algorithm, must be one of rsa-sha1 or rsa-sha256 (%s given).', $hash);
        }

        return $this;
    }

    /**
     * Set the body canonicalization algorithm.
     *
     * @param string $canon
     *
     * @return $this
     */
    public function setBodyCanon($canon)
    {
        if ('relaxed' == $canon) {
            $this->bodyCanon = 'relaxed';
        } else {
            $this->bodyCanon = 'simple';
        }

        return $this;
    }

    /**
     * Set the header canonicalization algorithm.
     *
     * @param string $canon
     *
     * @return $this
     */
    public function setHeaderCanon($canon)
    {
        if ('relaxed' == $canon) {
            $this->headerCanon = 'relaxed';
        } else {
            $this->headerCanon = 'simple';
        }

        return $this;
    }

    /**
     * Set the signer identity.
     *
     * @param string $identity
     *
     * @return $this
     */
    public function setSignerIdentity($identity)
    {
        $this->signerIdentity = $identity;

        return $this;
    }

    /**
     * Set the length of the body to sign.
     *
     * @param mixed $len (bool or int)
     *
     * @return $this
     */
    public function setBodySignedLen($len)
    {
        if (true === $len) {
            $this->showLen = true;
            $this->maxLen = PHP_INT_MAX;
        } elseif (false === $len) {
            $this->showLen = false;
            $this->maxLen = PHP_INT_MAX;
        } else {
            $this->showLen = true;
            $this->maxLen = (int) $len;
        }

        return $this;
    }

    /**
     * Set the signature timestamp.
     *
     * @param int $time A timestamp
     *
     * @return $this
     */
    public function setSignatureTimestamp($time)
    {
        $this->signatureTimestamp = $time;

        return $this;
    }

    /**
     * Set the signature expiration timestamp.
     *
     * @param int $time A timestamp
     *
     * @return $this
     */
    public function setSignatureExpiration($time)
    {
        $this->signatureExpiration = $time;

        return $this;
    }

    /**
     * Enable / disable the DebugHeaders.
     *
     * @param bool $debug
     *
     * @return Swift_Signers_DKIMSigner
     */
    public function setDebugHeaders($debug)
    {
        $this->debugHeaders = (bool) $debug;

        return $this;
    }

    /**
     * Start Body.
     */
    public function startBody()
    {
        // Init
        switch ($this->hashAlgorithm) {
            case 'rsa-sha256':
                $this->bodyHashHandler = hash_init('sha256');
                break;
            case 'rsa-sha1':
                $this->bodyHashHandler = hash_init('sha1');
                break;
        }
        $this->bodyCanonLine = '';
    }

    /**
     * End Body.
     */
    public function endBody()
    {
        $this->endOfBody();
    }

    /**
     * Returns the list of Headers Tampered by this plugin.
     *
     * @return array
     */
    public function getAlteredHeaders()
    {
        if ($this->debugHeaders) {
            return ['DKIM-Signature', 'X-DebugHash'];
        } else {
            return ['DKIM-Signature'];
        }
    }

    /**
     * Adds an ignored Header.
     *
     * @param string $header_name
     *
     * @return Swift_Signers_DKIMSigner
     */
    public function ignoreHeader($header_name)
    {
        $this->ignoredHeaders[strtolower($header_name ?? '')] = true;

        return $this;
    }

    /**
     * Set the headers to sign.
     *
     * @return Swift_Signers_DKIMSigner
     */
    public function setHeaders(Swift_Mime_SimpleHeaderSet $headers)
    {
        $this->headerCanonData = '';
        // Loop through Headers
        $listHeaders = $headers->listAll();
        foreach ($listHeaders as $hName) {
            // Check if we need to ignore Header
            if (!isset($this->ignoredHeaders[strtolower($hName ?? '')])) {
                if ($headers->has($hName)) {
                    $tmp = $headers->getAll($hName);
                    foreach ($tmp as $header) {
                        if ('' != $header->getFieldBody()) {
                            $this->addHeader($header->toString());
                            $this->signedHeaders[] = $header->getFieldName();
                        }
                    }
                }
            }
        }

        return $this;
    }

    /**
     * Add the signature to the given Headers.
     *
     * @return Swift_Signers_DKIMSigner
     */
    public function addSignature(Swift_Mime_SimpleHeaderSet $headers)
    {
        // Prepare the DKIM-Signature
        $params = ['v' => '1', 'a' => $this->hashAlgorithm, 'bh' => base64_encode($this->bodyHash ?? ''), 'd' => $this->domainName, 'h' => implode(': ', $this->signedHeaders), 'i' => $this->signerIdentity, 's' => $this->selector];
        if ('simple' != $this->bodyCanon) {
            $params['c'] = $this->headerCanon.'/'.$this->bodyCanon;
        } elseif ('simple' != $this->headerCanon) {
            $params['c'] = $this->headerCanon;
        }
        if ($this->showLen) {
            $params['l'] = $this->bodyLen;
        }
        if (true === $this->signatureTimestamp) {
            $params['t'] = time();
            if (false !== $this->signatureExpiration) {
                $params['x'] = $params['t'] + $this->signatureExpiration;
            }
        } else {
            if (false !== $this->signatureTimestamp) {
                $params['t'] = $this->signatureTimestamp;
            }
            if (false !== $this->signatureExpiration) {
                $params['x'] = $this->signatureExpiration;
            }
        }
        if ($this->debugHeaders) {
            $params['z'] = implode('|', $this->debugHeadersData);
        }
        $string = '';
        foreach ($params as $k => $v) {
            $string .= $k.'='.$v.'; ';
        }
        $string = trim($string);
        $headers->addTextHeader('DKIM-Signature', $string);
        // Add the last DKIM-Signature
        $tmp = $headers->getAll('DKIM-Signature');
        $this->dkimHeader = end($tmp);
        $this->addHeader(trim($this->dkimHeader->toString() ?? '')."\r\n b=", true);
        if ($this->debugHeaders) {
            $headers->addTextHeader('X-DebugHash', base64_encode($this->headerHash ?? ''));
        }
        $this->dkimHeader->setValue($string.' b='.trim(chunk_split(base64_encode($this->getEncryptedHash() ?? ''), 73, ' ')));

        return $this;
    }

    /* Private helpers */

    protected function addHeader($header, $is_sig = false)
    {
        switch ($this->headerCanon) {
            case 'relaxed':
                // Prepare Header and cascade
                $exploded = explode(':', $header, 2);
                $name = strtolower(trim($exploded[0]));
                $value = str_replace("\r\n", '', $exploded[1]);
                $value = preg_replace("/[ \t][ \t]+/", ' ', $value);
                $header = $name.':'.trim($value).($is_sig ? '' : "\r\n");
                // no break
            case 'simple':
                // Nothing to do
        }
        $this->addToHeaderHash($header);
    }

    protected function canonicalizeBody($string)
    {
        $len = \strlen($string);
        $canon = '';
        $method = ('relaxed' == $this->bodyCanon);
        for ($i = 0; $i < $len; ++$i) {
            if ($this->bodyCanonIgnoreStart > 0) {
                --$this->bodyCanonIgnoreStart;
                continue;
            }
            switch ($string[$i]) {
                case "\r":
                    $this->bodyCanonLastChar = "\r";
                    break;
                case "\n":
                    if ("\r" == $this->bodyCanonLastChar) {
                        if ($method) {
                            $this->bodyCanonSpace = false;
                        }
                        if ('' == $this->bodyCanonLine) {
                            ++$this->bodyCanonEmptyCounter;
                        } else {
                            $this->bodyCanonLine = '';
                            $canon .= "\r\n";
                        }
                    } else {
                        // Wooops Error
                        // todo handle it but should never happen
                    }
                    break;
                case ' ':
                case "\t":
                    if ($method) {
                        $this->bodyCanonSpace = true;
                        break;
                    }
                    // no break
                default:
                    if ($this->bodyCanonEmptyCounter > 0) {
                        $canon .= str_repeat("\r\n", $this->bodyCanonEmptyCounter);
                        $this->bodyCanonEmptyCounter = 0;
                    }
                    if ($this->bodyCanonSpace) {
                        $this->bodyCanonLine .= ' ';
                        $canon .= ' ';
                        $this->bodyCanonSpace = false;
                    }
                    $this->bodyCanonLine .= $string[$i];
                    $canon .= $string[$i];
            }
        }
        $this->addToBodyHash($canon);
    }

    protected function endOfBody()
    {
        // Add trailing Line return if last line is non empty
        if (\strlen($this->bodyCanonLine) > 0) {
            $this->addToBodyHash("\r\n");
        }
        $this->bodyHash = hash_final($this->bodyHashHandler, true);
    }

    private function addToBodyHash($string)
    {
        $len = \strlen($string);
        if ($len > ($new_len = ($this->maxLen - $this->bodyLen))) {
            $string = substr($string, 0, $new_len);
            $len = $new_len;
        }
        hash_update($this->bodyHashHandler, $string);
        $this->bodyLen += $len;
    }

    private function addToHeaderHash($header)
    {
        if ($this->debugHeaders) {
            $this->debugHeadersData[] = trim($header ?? '');
        }
        $this->headerCanonData .= $header;
    }

    /**
     * @throws Swift_SwiftException
     *
     * @return string
     */
    private function getEncryptedHash()
    {
        $signature = '';
        switch ($this->hashAlgorithm) {
            case 'rsa-sha1':
                $algorithm = OPENSSL_ALGO_SHA1;
                break;
            case 'rsa-sha256':
                $algorithm = OPENSSL_ALGO_SHA256;
                break;
        }
        $pkeyId = openssl_get_privatekey($this->privateKey, $this->passphrase);
        if (!$pkeyId) {
            throw new Swift_SwiftException('Unable to load DKIM Private Key ['.openssl_error_string().']');
        }
        if (openssl_sign($this->headerCanonData, $signature, $pkeyId, $algorithm)) {
            return $signature;
        }
        throw new Swift_SwiftException('Unable to sign DKIM Hash ['.openssl_error_string().']');
    }
}


================================================
FILE: lib/classes/Swift/Signers/DomainKeySigner.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * DomainKey Signer used to apply DomainKeys Signature to a message.
 *
 * @author     Xavier De Cock <xdecock@gmail.com>
 */
class Swift_Signers_DomainKeySigner implements Swift_Signers_HeaderSigner
{
    /**
     * PrivateKey.
     *
     * @var string
     */
    protected $privateKey;

    /**
     * DomainName.
     *
     * @var string
     */
    protected $domainName;

    /**
     * Selector.
     *
     * @var string
     */
    protected $selector;

    /**
     * Hash algorithm used.
     *
     * @var string
     */
    protected $hashAlgorithm = 'rsa-sha1';

    /**
     * Canonisation method.
     *
     * @var string
     */
    protected $canon = 'simple';

    /**
     * Headers not being signed.
     *
     * @var array
     */
    protected $ignoredHeaders = [];

    /**
     * Signer identity.
     *
     * @var string
     */
    protected $signerIdentity;

    /**
     * Must we embed signed headers?
     *
     * @var bool
     */
    protected $debugHeaders = false;

    // work variables
    /**
     * Headers used to generate hash.
     *
     * @var array
     */
    private $signedHeaders = [];

    /**
     * Stores the signature header.
     *
     * @var Swift_Mime_Headers_ParameterizedHeader
     */
    protected $domainKeyHeader;

    /**
     * Hash Handler.
     *
     * @var resource|null
     */
    private $hashHandler;

    private $canonData = '';

    private $bodyCanonEmptyCounter = 0;

    private $bodyCanonIgnoreStart = 2;

    private $bodyCanonSpace = false;

    private $bodyCanonLastChar = null;

    private $bodyCanonLine = '';

    private $bound = [];

    /**
     * Constructor.
     *
     * @param string $privateKey
     * @param string $domainName
     * @param string $selector
     */
    public function __construct($privateKey, $domainName, $selector)
    {
        $this->privateKey = $privateKey;
        $this->domainName = $domainName;
        $this->signerIdentity = '@'.$domainName;
        $this->selector = $selector;
    }

    /**
     * Resets internal states.
     *
     * @return $this
     */
    public function reset()
    {
        $this->hashHandler = null;
        $this->bodyCanonIgnoreStart = 2;
        $this->bodyCanonEmptyCounter = 0;
        $this->bodyCanonLastChar = null;
        $this->bodyCanonSpace = false;

        return $this;
    }

    /**
     * Writes $bytes to the end of the stream.
     *
     * Writing may not happen immediately if the stream chooses to buffer.  If
     * you want to write these bytes with immediate effect, call {@link commit()}
     * after calling write().
     *
     * This method returns the sequence ID of the write (i.e. 1 for first, 2 for
     * second, etc etc).
     *
     * @param string $bytes
     *
     * @return int
     *
     * @throws Swift_IoException
     *
     * @return $this
     */
    public function write($bytes)
    {
        $this->canonicalizeBody($bytes);
        foreach ($this->bound as $is) {
            $is->write($bytes);
        }

        return $this;
    }

    /**
     * For any bytes that are currently buffered inside the stream, force them
     * off the buffer.
     *
     * @throws Swift_IoException
     *
     * @return $this
     */
    public function commit()
    {
        // Nothing to do
        return $this;
    }

    /**
     * Attach $is to this stream.
     *
     * The stream acts as an observer, receiving all data that is written.
     * All {@link write()} and {@link flushBuffers()} operations will be mirrored.
     *
     * @return $this
     */
    public function bind(Swift_InputByteStream $is)
    {
        // Don't have to mirror anything
        $this->bound[] = $is;

        return $this;
    }

    /**
     * Remove an already bound stream.
     *
     * If $is is not bound, no errors will be raised.
     * If the stream currently has any buffered data it will be written to $is
     * before unbinding occurs.
     *
     * @return $this
     */
    public function unbind(Swift_InputByteStream $is)
    {
        // Don't have to mirror anything
        foreach ($this->bound as $k => $stream) {
            if ($stream === $is) {
                unset($this->bound[$k]);

                break;
            }
        }

        return $this;
    }

    /**
     * Flush the contents of the stream (empty it) and set the internal pointer
     * to the beginning.
     *
     * @throws Swift_IoException
     *
     * @return $this
     */
    public function flushBuffers()
    {
        $this->reset();

        return $this;
    }

    /**
     * Set hash_algorithm, must be one of rsa-sha256 | rsa-sha1 defaults to rsa-sha256.
     *
     * @param string $hash
     *
     * @return $this
     */
    public function setHashAlgorithm($hash)
    {
        $this->hashAlgorithm = 'rsa-sha1';

        return $this;
    }

    /**
     * Set the canonicalization algorithm.
     *
     * @param string $canon simple | nofws defaults to simple
     *
     * @return $this
     */
    public function setCanon($canon)
    {
        if ('nofws' == $canon) {
            $this->canon = 'nofws';
        } else {
            $this->canon = 'simple';
        }

        return $this;
    }

    /**
     * Set the signer identity.
     *
     * @param string $identity
     *
     * @return $this
     */
    public function setSignerIdentity($identity)
    {
        $this->signerIdentity = $identity;

        return $this;
    }

    /**
     * Enable / disable the DebugHeaders.
     *
     * @param bool $debug
     *
     * @return $this
     */
    public function setDebugHeaders($debug)
    {
        $this->debugHeaders = (bool) $debug;

        return $this;
    }

    /**
     * Start Body.
     */
    public function startBody()
    {
    }

    /**
     * End Body.
     */
    public function endBody()
    {
        $this->endOfBody();
    }

    /**
     * Returns the list of Headers Tampered by this plugin.
     *
     * @return array
     */
    public function getAlteredHeaders()
    {
        if ($this->debugHeaders) {
            return ['DomainKey-Signature', 'X-DebugHash'];
        }

        return ['DomainKey-Signature'];
    }

    /**
     * Adds an ignored Header.
     *
     * @param string $header_name
     *
     * @return $this
     */
    public function ignoreHeader($header_name)
    {
        $this->ignoredHeaders[strtolower($header_name ?? '')] = true;

        return $this;
    }

    /**
     * Set the headers to sign.
     *
     * @return $this
     */
    public function setHeaders(Swift_Mime_SimpleHeaderSet $headers)
    {
        $this->startHash();
        $this->canonData = '';
        // Loop through Headers
        $listHeaders = $headers->listAll();
        foreach ($listHeaders as $hName) {
            // Check if we need to ignore Header
            if (!isset($this->ignoredHeaders[strtolower($hName ?? '')])) {
                if ($headers->has($hName)) {
                    $tmp = $headers->getAll($hName);
                    foreach ($tmp as $header) {
                        if ('' != $header->getFieldBody()) {
                            $this->addHeader($header->toString());
                            $this->signedHeaders[] = $header->getFieldName();
                        }
                    }
                }
            }
        }
        $this->endOfHeaders();

        return $this;
    }

    /**
     * Add the signature to the given Headers.
     *
     * @return $this
     */
    public function addSignature(Swift_Mime_SimpleHeaderSet $headers)
    {
        // Prepare the DomainKey-Signature Header
        $params = ['a' => $this->hashAlgorithm, 'b' => chunk_split(base64_encode($this->getEncryptedHash() ?? ''), 73, ' '), 'c' => $this->canon, 'd' => $this->domainName, 'h' => implode(': ', $this->signedHeaders), 'q' => 'dns', 's' => $this->selector];
        $string = '';
        foreach ($params as $k => $v) {
            $string .= $k.'='.$v.'; ';
        }
        $string = trim($string);
        $headers->addTextHeader('DomainKey-Signature', $string);

        return $this;
    }

    /* Private helpers */

    protected function addHeader($header)
    {
        switch ($this->canon) {
            case 'nofws':
                // Prepare Header and cascade
                $exploded = explode(':', $header, 2);
                $name = strtolower(trim($exploded[0]));
                $value = str_replace("\r\n", '', $exploded[1]);
                $value = preg_replace("/[ \t][ \t]+/", ' ', $value);
                $header = $name.':'.trim($value)."\r\n";
                // no break
            case 'simple':
                // Nothing to do
        }
        $this->addToHash($header);
    }

    protected function endOfHeaders()
    {
        $this->bodyCanonEmptyCounter = 1;
    }

    protected function canonicalizeBody($string)
    {
        $len = \strlen($string);
        $canon = '';
        $nofws = ('nofws' == $this->canon);
        for ($i = 0; $i < $len; ++$i) {
            if ($this->bodyCanonIgnoreStart > 0) {
                --$this->bodyCanonIgnoreStart;
                continue;
            }
            switch ($string[$i]) {
                case "\r":
                    $this->bodyCanonLastChar = "\r";
                    break;
                case "\n":
                    if ("\r" == $this->bodyCanonLastChar) {
                        if ($nofws) {
                            $this->bodyCanonSpace = false;
                        }
                        if ('' == $this->bodyCanonLine) {
                            ++$this->bodyCanonEmptyCounter;
                        } else {
                            $this->bodyCanonLine = '';
                            $canon .= "\r\n";
                        }
                    } else {
                        // Wooops Error
                        throw new Swift_SwiftException('Invalid new line sequence in mail found \n without preceding \r');
                    }
                    break;
                case ' ':
                case "\t":
                case "\x09": //HTAB
                    if ($nofws) {
                        $this->bodyCanonSpace = true;
                        break;
                    }
                    // no break
                default:
                    if ($this->bodyCanonEmptyCounter > 0) {
                        $canon .= str_repeat("\r\n", $this->bodyCanonEmptyCounter);
                        $this->bodyCanonEmptyCounter = 0;
                    }
                    $this->bodyCanonLine .= $string[$i];
                    $canon .= $string[$i];
            }
        }
        $this->addToHash($canon);
    }

    protected function endOfBody()
    {
        if (\strlen($this->bodyCanonLine) > 0) {
            $this->addToHash("\r\n");
        }
    }

    private function addToHash($string)
    {
        $this->canonData .= $string;
        hash_update($this->hashHandler, $string);
    }

    private function startHash()
    {
        // Init
        switch ($this->hashAlgorithm) {
            case 'rsa-sha1':
                $this->hashHandler = hash_init('sha1');
                break;
        }
        $this->bodyCanonLine = '';
    }

    /**
     * @throws Swift_SwiftException
     *
     * @return string
     */
    private function getEncryptedHash()
    {
        $signature = '';
        $pkeyId = openssl_get_privatekey($this->privateKey);
        if (!$pkeyId) {
            throw new Swift_SwiftException('Unable to load DomainKey Private Key ['.openssl_error_string().']');
        }
        if (openssl_sign($this->canonData, $signature, $pkeyId, OPENSSL_ALGO_SHA1)) {
            return $signature;
        }
        throw new Swift_SwiftException('Unable to sign DomainKey Hash  ['.openssl_error_string().']');
    }
}


================================================
FILE: lib/classes/Swift/Signers/HeaderSigner.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Header Signer Interface used to apply Header-Based Signature to a message.
 *
 * @author Xavier De Cock <xdecock@gmail.com>
 */
interface Swift_Signers_HeaderSigner extends Swift_Signer, Swift_InputByteStream
{
    /**
     * Exclude an header from the signed headers.
     *
     * @param string $header_name
     *
     * @return self
     */
    public function ignoreHeader($header_name);

    /**
     * Prepare the Signer to get a new Body.
     *
     * @return self
     */
    public function startBody();

    /**
     * Give the signal that the body has finished streaming.
     *
     * @return self
     */
    public function endBody();

    /**
     * Give the headers already given.
     *
     * @return self
     */
    public function setHeaders(Swift_Mime_SimpleHeaderSet $headers);

    /**
     * Add the header(s) to the headerSet.
     *
     * @return self
     */
    public function addSignature(Swift_Mime_SimpleHeaderSet $headers);

    /**
     * Return the list of header a signer might tamper.
     *
     * @return array
     */
    public function getAlteredHeaders();
}


================================================
FILE: lib/classes/Swift/Signers/OpenDKIMSigner.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * DKIM Signer used to apply DKIM Signature to a message
 * Takes advantage of pecl extension.
 *
 * @author     Xavier De Cock <xdecock@gmail.com>
 *
 * @deprecated since SwiftMailer 6.1.0; use Swift_Signers_DKIMSigner instead.
 */
class Swift_Signers_OpenDKIMSigner extends Swift_Signers_DKIMSigner
{
    private $peclLoaded = false;

    private $dkimHandler = null;

    private $dropFirstLF = true;

    const CANON_RELAXED = 1;
    const CANON_SIMPLE = 2;
    const SIG_RSA_SHA1 = 3;
    const SIG_RSA_SHA256 = 4;

    public function __construct($privateKey, $domainName, $selector)
    {
        if (!\extension_loaded('opendkim')) {
            throw new Swift_SwiftException('php-opendkim extension not found');
        }

        $this->peclLoaded = true;

        parent::__construct($privateKey, $domainName, $selector);
    }

    public function addSignature(Swift_Mime_SimpleHeaderSet $headers)
    {
        $header = new Swift_Mime_Headers_OpenDKIMHeader('DKIM-Signature');
        $headerVal = $this->dkimHandler->getSignatureHeader();
        if (false === $headerVal || \is_int($headerVal)) {
            throw new Swift_SwiftException('OpenDKIM Error: '.$this->dkimHandler->getError());
        }
        $header->setValue($headerVal);
        $headers->set($header);

        return $this;
    }

    public function setHeaders(Swift_Mime_SimpleHeaderSet $headers)
    {
        $hash = 'rsa-sha1' == $this->hashAlgorithm ? OpenDKIMSign::ALG_RSASHA1 : OpenDKIMSign::ALG_RSASHA256;
        $bodyCanon = 'simple' == $this->bodyCanon ? OpenDKIMSign::CANON_SIMPLE : OpenDKIMSign::CANON_RELAXED;
        $headerCanon = 'simple' == $this->headerCanon ? OpenDKIMSign::CANON_SIMPLE : OpenDKIMSign::CANON_RELAXED;
        $this->dkimHandler = new OpenDKIMSign($this->privateKey, $this->selector, $this->domainName, $headerCanon, $bodyCanon, $hash, -1);
        // Hardcode signature Margin for now
        $this->dkimHandler->setMargin(78);

        if (!is_numeric($this->signatureTimestamp)) {
            OpenDKIM::setOption(OpenDKIM::OPTS_FIXEDTIME, time());
        } else {
            if (!OpenDKIM::setOption(OpenDKIM::OPTS_FIXEDTIME, $this->signatureTimestamp)) {
                throw new Swift_SwiftException('Unable to force signature timestamp ['.openssl_error_string().']');
            }
        }
        if (isset($this->signerIdentity)) {
            $this->dkimHandler->setSigner($this->signerIdentity);
        }
        $listHeaders = $headers->listAll();
        foreach ($listHeaders as $hName) {
            // Check if we need to ignore Header
            if (!isset($this->ignoredHeaders[strtolower($hName ?? '')])) {
                $tmp = $headers->getAll($hName);
                if ($headers->has($hName)) {
                    foreach ($tmp as $header) {
                        if ('' != $header->getFieldBody()) {
                            $htosign = $header->toString();
                            $this->dkimHandler->header($htosign);
                            $this->signedHeaders[] = $header->getFieldName();
                        }
                    }
                }
            }
        }

        return $this;
    }

    public function startBody()
    {
        if (!$this->peclLoaded) {
            return parent::startBody();
        }
        $this->dropFirstLF = true;
        $this->dkimHandler->eoh();

        return $this;
    }

    public function endBody()
    {
        if (!$this->peclLoaded) {
            return parent::endBody();
        }
        $this->dkimHandler->eom();

        return $this;
    }

    public function reset()
    {
        $this->dkimHandler = null;
        parent::reset();

        return $this;
    }

    /**
     * Set the signature timestamp.
     *
     * @param int $time
     *
     * @return $this
     */
    public function setSignatureTimestamp($time)
    {
        $this->signatureTimestamp = $time;

        return $this;
    }

    /**
     * Set the signature expiration timestamp.
     *
     * @param int $time
     *
     * @return $this
     */
    public function setSignatureExpiration($time)
    {
        $this->signatureExpiration = $time;

        return $this;
    }

    /**
     * Enable / disable the DebugHeaders.
     *
     * @param bool $debug
     *
     * @return $this
     */
    public function setDebugHeaders($debug)
    {
        $this->debugHeaders = (bool) $debug;

        return $this;
    }

    // Protected

    protected function canonicalizeBody($string)
    {
        if (!$this->peclLoaded) {
            return parent::canonicalizeBody($string);
        }
        if (true === $this->dropFirstLF) {
            if ("\r" == $string[0] && "\n" == $string[1]) {
                $string = substr($string, 2);
            }
        }
        $this->dropFirstLF = false;
        if (\strlen($string)) {
            $this->dkimHandler->body($string);
        }
    }
}


================================================
FILE: lib/classes/Swift/Signers/SMimeSigner.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * MIME Message Signer used to apply S/MIME Signature/Encryption to a message.
 *
 * @author Romain-Geissler
 * @author Sebastiaan Stok <s.stok@rollerscapes.net>
 * @author Jan Flora <jf@penneo.com>
 */
class Swift_Signers_SMimeSigner implements Swift_Signers_BodySigner
{
    protected $signCertificate;
    protected $signPrivateKey;
    protected $encryptCert;
    protected $signThenEncrypt = true;
    protected $signLevel;
    protected $encryptLevel;
    protected $signOptions;
    protected $encryptOptions;
    protected $encryptCipher;
    protected $extraCerts = null;
    protected $wrapFullMessage = false;

    /**
     * @var Swift_StreamFilters_StringReplacementFilterFactory
     */
    protected $replacementFactory;

    /**
     * @var Swift_Mime_SimpleHeaderFactory
     */
    protected $headerFactory;

    /**
     * Constructor.
     *
     * @param string|null $signCertificate
     * @param string|null $signPrivateKey
     * @param string|null $encryptCertificate
     */
    public function __construct($signCertificate = null, $signPrivateKey = null, $encryptCertificate = null)
    {
        if (null !== $signPrivateKey) {
            $this->setSignCertificate($signCertificate, $signPrivateKey);
        }

        if (null !== $encryptCertificate) {
            $this->setEncryptCertificate($encryptCertificate);
        }

        $this->replacementFactory = Swift_DependencyContainer::getInstance()
            ->lookup('transport.replacementfactory');

        $this->signOptions = PKCS7_DETACHED;
        $this->encryptCipher = OPENSSL_CIPHER_AES_128_CBC;
    }

    /**
     * Set the certificate location to use for signing.
     *
     * @see https://secure.php.net/manual/en/openssl.pkcs7.flags.php
     *
     * @param string       $certificate
     * @param string|array $privateKey  If the key needs an passphrase use array('file-location', 'passphrase') instead
     * @param int          $signOptions Bitwise operator options for openssl_pkcs7_sign()
     * @param string       $extraCerts  A file containing intermediate certificates needed by the signing certificate
     *
     * @return $this
     */
    public function setSignCertificate($certificate, $privateKey = null, $signOptions = PKCS7_DETACHED, $extraCerts = null)
    {
        $this->signCertificate = 'file://'.str_replace('\\', '/', realpath($certificate));

        if (null !== $privateKey) {
            if (\is_array($privateKey)) {
                $this->signPrivateKey = $privateKey;
                $this->signPrivateKey[0] = 'file://'.str_replace('\\', '/', realpath($privateKey[0]));
            } else {
                $this->signPrivateKey = 'file://'.str_replace('\\', '/', realpath($privateKey));
            }
        }

        $this->signOptions = $signOptions;
        $this->extraCerts = $extraCerts ? realpath($extraCerts) : null;

        return $this;
    }

    /**
     * Set the certificate location to use for encryption.
     *
     * @see https://secure.php.net/manual/en/openssl.pkcs7.flags.php
     * @see https://secure.php.net/manual/en/openssl.ciphers.php
     *
     * @param string|array $recipientCerts Either an single X.509 certificate, or an assoc array of X.509 certificates.
     * @param int          $cipher
     *
     * @return $this
     */
    public function setEncryptCertificate($recipientCerts, $cipher = null)
    {
        if (\is_array($recipientCerts)) {
            $this->encryptCert = [];

            foreach ($recipientCerts as $cert) {
                $this->encryptCert[] = 'file://'.str_replace('\\', '/', realpath($cert));
            }
        } else {
            $this->encryptCert = 'file://'.str_replace('\\', '/', realpath($recipientCerts));
        }

        if (null !== $cipher) {
            $this->encryptCipher = $cipher;
        }

        return $this;
    }

    /**
     * @return string
     */
    public function getSignCertificate()
    {
        return $this->signCertificate;
    }

    /**
     * @return string
     */
    public function getSignPrivateKey()
    {
        return $this->signPrivateKey;
    }

    /**
     * Set perform signing before encryption.
     *
     * The default is to first sign the message and then encrypt.
     * But some older mail clients, namely Microsoft Outlook 2000 will work when the message first encrypted.
     * As this goes against the official specs, its recommended to only use 'encryption -> signing' when specifically targeting these 'broken' clients.
     *
     * @param bool $signThenEncrypt
     *
     * @return $this
     */
    public function setSignThenEncrypt($signThenEncrypt = true)
    {
        $this->signThenEncrypt = $signThenEncrypt;

        return $this;
    }

    /**
     * @return bool
     */
    public function isSignThenEncrypt()
    {
        return $this->signThenEncrypt;
    }

    /**
     * Resets internal states.
     *
     * @return $this
     */
    public function reset()
    {
        return $this;
    }

    /**
     * Specify whether to wrap the entire MIME message in the S/MIME message.
     *
     * According to RFC5751 section 3.1:
     * In order to protect outer, non-content-related message header fields
     * (for instance, the "Subject", "To", "From", and "Cc" fields), the
     * sending client MAY wrap a full MIME message in a message/rfc822
     * wrapper in order to apply S/MIME security services to these header
     * fields.  It is up to the receiving client to decide how to present
     * this "inner" header along with the unprotected "outer" header.
     *
     * @param bool $wrap
     *
     * @return $this
     */
    public function setWrapFullMessage($wrap)
    {
        $this->wrapFullMessage = $wrap;
    }

    /**
     * Change the Swift_Message to apply the signing.
     *
     * @return $this
     */
    public function signMessage(Swift_Message $message)
    {
        if (null === $this->signCertificate && null === $this->encryptCert) {
            return $this;
        }

        if ($this->signThenEncrypt) {
            $this->smimeSignMessage($message);
            $this->smimeEncryptMessage($message);
        } else {
            $this->smimeEncryptMessage($message);
            $this->smimeSignMessage($message);
        }
    }

    /**
     * Return the list of header a signer might tamper.
     *
     * @return array
     */
    public function getAlteredHeaders()
    {
        return ['Content-Type', 'Content-Transfer-Encoding', 'Content-Disposition'];
    }

    /**
     * Sign a Swift message.
     */
    protected function smimeSignMessage(Swift_Message $message)
    {
        // If we don't have a certificate we can't sign the message
        if (null === $this->signCertificate) {
            return;
        }

        // Work on a clone of the original message
        $signMessage = clone $message;
        $signMessage->clearSigners();

        if ($this->wrapFullMessage) {
            // The original message essentially becomes the body of the new
            // wrapped message
            $signMessage = $this->wrapMimeMessage($signMessage);
        } else {
            // Only keep header needed to parse the body correctly
            $this->clearAllHeaders($signMessage);
            $this->copyHeaders(
                $message,
                $signMessage,
                [
                    'Content-Type',
                    'Content-Transfer-Encoding',
                    'Content-Disposition',
                ]
            );
        }

        // Copy the cloned message into a temporary file stream
        $messageStream = new Swift_ByteStream_TemporaryFileByteStream();
        $signMessage->toByteStream($messageStream);
        $messageStream->commit();
        $signedMessageStream = new Swift_ByteStream_TemporaryFileByteStream();

        // Sign the message using openssl
        if (!openssl_pkcs7_sign(
                $messageStream->getPath(),
                $signedMessageStream->getPath(),
                $this->signCertificate,
                $this->signPrivateKey,
                [],
                $this->signOptions,
                $this->extraCerts
            )
        ) {
            throw new Swift_IoException(sprintf('Failed to sign S/Mime message. Error: "%s".', openssl_error_string()));
        }

        // Parse the resulting signed message content back into the Swift message
        // preserving the original headers
        $this->parseSSLOutput($signedMessageStream, $message);
    }

    /**
     * Encrypt a Swift message.
     */
    protected function smimeEncryptMessage(Swift_Message $message)
    {
        // If we don't have a certificate we can't encrypt the message
        if (null === $this->encryptCert) {
            return;
        }

        // Work on a clone of the original message
        $encryptMessage = clone $message;
        $encryptMessage->clearSigners();

        if ($this->wrapFullMessage) {
            // The original message essentially becomes the body of the new
            // wrapped message
            $encryptMessage = $this->wrapMimeMessage($encryptMessage);
        } else {
            // Only keep header needed to parse the body correctly
            $this->clearAllHeaders($encryptMessage);
            $this->copyHeaders(
                $message,
                $encryptMessage,
                [
                    'Content-Type',
                    'Content-Transfer-Encoding',
                    'Content-Disposition',
                ]
            );
        }

        // Convert the message content (including headers) to a string
        // and place it in a temporary file
        $messageStream = new Swift_ByteStream_TemporaryFileByteStream();
        $encryptMessage->toByteStream($messageStream);
        $messageStream->commit();
        $encryptedMessageStream = new Swift_ByteStream_TemporaryFileByteStream();

        // Encrypt the message
        if (!openssl_pkcs7_encrypt(
                $messageStream->getPath(),
                $encryptedMessageStream->getPath(),
                $this->encryptCert,
                [],
                0,
                $this->encryptCipher
            )
        ) {
            throw new Swift_IoException(sprintf('Failed to encrypt S/Mime message. Error: "%s".', openssl_error_string()));
        }

        // Parse the resulting signed message content back into the Swift message
        // preserving the original headers
        $this->parseSSLOutput($encryptedMessageStream, $message);
    }

    /**
     * Copy named headers from one Swift message to another.
     */
    protected function copyHeaders(
        Swift_Message $fromMessage,
        Swift_Message $toMessage,
        array $headers = []
    ) {
        foreach ($headers as $header) {
            $this->copyHeader($fromMessage, $toMessage, $header);
        }
    }

    /**
     * Copy a single header from one Swift message to another.
     *
     * @param string $headerName
     */
    protected function copyHeader(Swift_Message $fromMessage, Swift_Message $toMessage, $headerName)
    {
        $header = $fromMessage->getHeaders()->get($headerName);
        if (!$header) {
            return;
        }
        $headers = $toMessage->getHeaders();
        switch ($header->getFieldType()) {
            case Swift_Mime_Header::TYPE_TEXT:
                $headers->addTextHeader($header->getFieldName(), $header->getValue());
                break;
            case Swift_Mime_Header::TYPE_PARAMETERIZED:
                $headers->addParameterizedHeader(
                    $header->getFieldName(),
                    $header->getValue(),
                    $header->getParameters()
                );
                break;
        }
    }

    /**
     * Remove all headers from a Swift message.
     */
    protected function clearAllHeaders(Swift_Message $message)
    {
        $headers = $message->getHeaders();
        foreach ($headers->listAll() as $header) {
            $headers->removeAll($header);
        }
    }

    /**
     * Wraps a Swift_Message in a message/rfc822 MIME part.
     *
     * @return Swift_MimePart
     */
    protected function wrapMimeMessage(Swift_Message $message)
    {
        // Start by copying the original message into a message stream
        $messageStream = new Swift_ByteStream_TemporaryFileByteStream();
        $message->toByteStream($messageStream);
        $messageStream->commit();

        // Create a new MIME part that wraps the original stream
        $wrappedMessage = new Swift_MimePart($messageStream, 'message/rfc822');
        $wrappedMessage->setEncoder(new Swift_Mime_ContentEncoder_PlainContentEncoder('7bit'));

        return $wrappedMessage;
    }

    protected function parseSSLOutput(Swift_InputByteStream $inputStream, Swift_Message $message)
    {
        $messageStream = new Swift_ByteStream_TemporaryFileByteStream();
        $this->copyFromOpenSSLOutput($inputStream, $messageStream);

        $this->streamToMime($messageStream, $message);
    }

    /**
     * Merges an OutputByteStream from OpenSSL to a Swift_Message.
     */
    protected function streamToMime(Swift_OutputByteStream $fromStream, Swift_Message $message)
    {
        // Parse the stream into headers and body
        list($headers, $messageStream) = $this->parseStream($fromStream);

        // Get the original message headers
        $messageHeaders = $message->getHeaders();

        // Let the stream determine the headers describing the body content,
        // since the body of the original message is overwritten by the body
        // coming from the stream.
        // These are all content-* headers.

        // Default transfer encoding is 7bit if not set
        $encoding = '';
        // Remove all existing transfer encoding headers
        $messageHeaders->removeAll('Content-Transfer-Encoding');
        // See whether the stream sets the transfer encoding
        if (isset($headers['content-transfer-encoding'])) {
            $encoding = $headers['content-transfer-encoding'];
        }

        // We use the null content encoder, since the body is already encoded
        // according to the transfer encoding specified in the stream
        $message->setEncoder(new Swift_Mime_ContentEncoder_NullContentEncoder($encoding));

        // Set the disposition, if present
        if (isset($headers['content-disposition'])) {
            $messageHeaders->addTextHeader('Content-Disposition', $headers['content-disposition']);
        }

        // Copy over the body from the stream using the content type dictated
        // by the stream content
        $message->setChildren([]);
        $message->setBody($messageStream, $headers['content-type']);
    }

    /**
     * This message will parse the headers of a MIME email byte stream
     * and return an array that contains the headers as an associative
     * array and the email body as a string.
     *
     * @return array
     */
    protected function parseStream(Swift_OutputByteStream $emailStream)
    {
        $bufferLength = 78;
        $headerData = '';
        $headerBodySeparator = "\r\n\r\n";

        $emailStream->setReadPointer(0);

        // Read out the headers section from the stream to a string
        while (false !== ($buffer = $emailStream->read($bufferLength))) {
            $headerData .= $buffer;

            $headersPosEnd = strpos($headerData, $headerBodySeparator);

            // Stop reading if we found the end of the headers
            if (false !== $headersPosEnd) {
                break;
            }
        }

        // Split the header data into lines
        $headerData = trim(substr($headerData, 0, $headersPosEnd));
        $headerLines = explode("\r\n", $headerData);
        unset($headerData);

        $headers = [];
        $currentHeaderName = '';

        // Transform header lines into an associative array
        foreach ($headerLines as $headerLine) {
            // Handle headers that span multiple lines
            if (false === strpos($headerLine, ':')) {
                $headers[$currentHeaderName] .= ' '.trim($headerLine ?? '');
                continue;
            }

            $header = explode(':', $headerLine, 2);
            $currentHeaderName = strtolower($header[0] ?? '');
            $headers[$currentHeaderName] = trim($header[1] ?? '');
        }

        // Read the entire email body into a byte stream
        $bodyStream = new Swift_ByteStream_TemporaryFileByteStream();

        // Skip the header and separator and point to the body
        $emailStream->setReadPointer($headersPosEnd + \strlen($headerBodySeparator));

        while (false !== ($buffer = $emailStream->read($bufferLength))) {
            $bodyStream->write($buffer);
        }

        $bodyStream->commit();

        return [$headers, $bodyStream];
    }

    protected function copyFromOpenSSLOutput(Swift_OutputByteStream $fromStream, Swift_InputByteStream $toStream)
    {
        $bufferLength = 4096;
        $filteredStream = new Swift_ByteStream_TemporaryFileByteStream();
        $filteredStream->addFilter($this->replacementFactory->createFilter("\r\n", "\n"), 'CRLF to LF');
        $filteredStream->addFilter($this->replacementFactory->createFilter("\n", "\r\n"), 'LF to CRLF');

        while (false !== ($buffer = $fromStream->read($bufferLength))) {
            $filteredStream->write($buffer);
        }

        $filteredStream->flushBuffers();

        while (false !== ($buffer = $filteredStream->read($bufferLength))) {
            $toStream->write($buffer);
        }

        $toStream->commit();
    }
}


================================================
FILE: lib/classes/Swift/SmtpTransport.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Sends Messages over SMTP with ESMTP support.
 *
 * @author     Chris Corbyn
 *
 * @method Swift_SmtpTransport setUsername(string $username) Set the username to authenticate with.
 * @method string              getUsername()                 Get the username to authenticate with.
 * @method Swift_SmtpTransport setPassword(string $password) Set the password to authenticate with.
 * @method string              getPassword()                 Get the password to authenticate with.
 * @method Swift_SmtpTransport setAuthMode(string $mode)     Set the auth mode to use to authenticate.
 * @method string              getAuthMode()                 Get the auth mode to use to authenticate.
 */
class Swift_SmtpTransport extends Swift_Transport_EsmtpTransport
{
    /**
     * @param string $host
     * @param int    $port
     * @param string|null $encryption SMTP encryption mode:
     *        - null for plain SMTP (no encryption),
     *        - 'tls' for SMTP with STARTTLS (best effort encryption),
     *        - 'ssl' for SMTPS = SMTP over TLS (always encrypted).
     */
    public function __construct($host = 'localhost', $port = 25, $encryption = null)
    {
        \call_user_func_array(
            [$this, 'Swift_Transport_EsmtpTransport::__construct'],
            Swift_DependencyContainer::getInstance()
                ->createDependenciesFor('transport.smtp')
        );

        $this->setHost($host);
        $this->setPort($port);
        $this->setEncryption($encryption);
    }
}


================================================
FILE: lib/classes/Swift/Spool.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2009 Fabien Potencier <fabien.potencier@gmail.com>
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Interface for spools.
 *
 * @author Fabien Potencier
 */
interface Swift_Spool
{
    /**
     * Starts this Spool mechanism.
     */
    public function start();

    /**
     * Stops this Spool mechanism.
     */
    public function stop();

    /**
     * Tests if this Spool mechanism has started.
     *
     * @return bool
     */
    public function isStarted();

    /**
     * Queues a message.
     *
     * @param Swift_Mime_SimpleMessage $message The message to store
     *
     * @return bool Whether the operation has succeeded
     */
    public function queueMessage(Swift_Mime_SimpleMessage $message);

    /**
     * Sends messages using the given transport instance.
     *
     * @param Swift_Transport $transport        A transport instance
     * @param string[]        $failedRecipients An array of failures by-reference
     *
     * @return int The number of sent emails
     */
    public function flushQueue(Swift_Transport $transport, &$failedRecipients = null);
}


================================================
FILE: lib/classes/Swift/SpoolTransport.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2009 Fabien Potencier <fabien.potencier@gmail.com>
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Stores Messages in a queue.
 *
 * @author Fabien Potencier
 */
class Swift_SpoolTransport extends Swift_Transport_SpoolTransport
{
    /**
     * Create a new SpoolTransport.
     */
    public function __construct(Swift_Spool $spool)
    {
        $arguments = Swift_DependencyContainer::getInstance()
            ->createDependenciesFor('transport.spool');

        $arguments[] = $spool;

        \call_user_func_array(
            [$this, 'Swift_Transport_SpoolTransport::__construct'],
            $arguments
        );
    }
}


================================================
FILE: lib/classes/Swift/StreamFilter.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Processes bytes as they pass through a stream and performs filtering.
 *
 * @author Chris Corbyn
 */
interface Swift_StreamFilter
{
    /**
     * Based on the buffer given, this returns true if more buffering is needed.
     *
     * @param mixed $buffer
     *
     * @return bool
     */
    public function shouldBuffer($buffer);

    /**
     * Filters $buffer and returns the changes.
     *
     * @param mixed $buffer
     *
     * @return mixed
     */
    public function filter($buffer);
}


================================================
FILE: lib/classes/Swift/StreamFilters/ByteArrayReplacementFilter.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Processes bytes as they pass through a buffer and replaces sequences in it.
 *
 * This stream filter deals with Byte arrays rather than simple strings.
 *
 * @author  Chris Corbyn
 */
class Swift_StreamFilters_ByteArrayReplacementFilter implements Swift_StreamFilter
{
    /** The replacement(s) to make */
    private $replace;

    /** The Index for searching */
    private $index;

    /** The Search Tree */
    private $tree = [];

    /**  Gives the size of the largest search */
    private $treeMaxLen = 0;

    private $repSize;

    /**
     * Create a new ByteArrayReplacementFilter with $search and $replace.
     *
     * @param array $search
     * @param array $replace
     */
    public function __construct($search, $replace)
    {
        $this->index = [];
        $this->tree = [];
        $this->replace = [];
        $this->repSize = [];

        $tree = null;
        $i = null;
        $last_size = $size = 0;
        foreach ($search as $i => $search_element) {
            if (null !== $tree) {
                $tree[-1] = min(\count($replace) - 1, $i - 1);
                $tree[-2] = $last_size;
            }
            $tree = &$this->tree;
            if (\is_array($search_element)) {
                foreach ($search_element as $k => $char) {
                    $this->index[$char] = true;
                    if (!isset($tree[$char])) {
                        $tree[$char] = [];
                    }
                    $tree = &$tree[$char];
                }
                $last_size = $k + 1;
                $size = max($size, $last_size);
            } else {
                $last_size = 1;
                if (!isset($tree[$search_element])) {
                    $tree[$search_element] = [];
                }
                $tree = &$tree[$search_element];
                $size = max($last_size, $size);
                $this->index[$search_element] = true;
            }
        }
        if (null !== $i) {
            $tree[-1] = min(\count($replace) - 1, $i);
            $tree[-2] = $last_size;
            $this->treeMaxLen = $size;
        }
        foreach ($replace as $rep) {
            if (!\is_array($rep)) {
                $rep = [$rep];
            }
            $this->replace[] = $rep;
        }
        for ($i = \count($this->replace) - 1; $i >= 0; --$i) {
            $this->replace[$i] = $rep = $this->filter($this->replace[$i], $i);
            $this->repSize[$i] = \count($rep);
        }
    }

    /**
     * Returns true if based on the buffer passed more bytes should be buffered.
     *
     * @param array $buffer
     *
     * @return bool
     */
    public function shouldBuffer($buffer)
    {
        $endOfBuffer = end($buffer);

        return isset($this->index[$endOfBuffer]);
    }

    /**
     * Perform the actual replacements on $buffer and return the result.
     *
     * @param array $buffer
     * @param int   $minReplaces
     *
     * @return array
     */
    public function filter($buffer, $minReplaces = -1)
    {
        if (0 == $this->treeMaxLen) {
            return $buffer;
        }

        $newBuffer = [];
        $buf_size = \count($buffer);
        $last_size = 0;
        for ($i = 0; $i < $buf_size; ++$i) {
            $search_pos = $this->tree;
            $last_found = PHP_INT_MAX;
            // We try to find if the next byte is part of a search pattern
            for ($j = 0; $j <= $this->treeMaxLen; ++$j) {
                // We have a new byte for a search pattern
                if (isset($buffer[$p = $i + $j]) && isset($search_pos[$buffer[$p]])) {
                    $search_pos = $search_pos[$buffer[$p]];
                    // We have a complete pattern, save, in case we don't find a better match later
                    if (isset($search_pos[-1]) && $search_pos[-1] < $last_found
                        && $search_pos[-1] > $minReplaces) {
                        $last_found = $search_pos[-1];
                        $last_size = $search_pos[-2];
                    }
                }
                // We got a complete pattern
                elseif (PHP_INT_MAX !== $last_found) {
                    // Adding replacement datas to output buffer
                    $rep_size = $this->repSize[$last_found];
                    for ($j = 0; $j < $rep_size; ++$j) {
                        $newBuffer[] = $this->replace[$last_found][$j];
                    }
                    // We Move cursor forward
                    $i += $last_size - 1;
                    // Edge Case, last position in buffer
                    if ($i >= $buf_size) {
                        $newBuffer[] = $buffer[$i];
                    }

                    // We start the next loop
                    continue 2;
                } else {
                    // this byte is not in a pattern and we haven't found another pattern
                    break;
                }
            }
            // Normal byte, move it to output buffer
            $newBuffer[] = $buffer[$i];
        }

        return $newBuffer;
    }
}


================================================
FILE: lib/classes/Swift/StreamFilters/StringReplacementFilter.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Processes bytes as they pass through a buffer and replaces sequences in it.
 *
 * @author Chris Corbyn
 */
class Swift_StreamFilters_StringReplacementFilter implements Swift_StreamFilter
{
    /** The needle(s) to search for */
    private $search;

    /** The replacement(s) to make */
    private $replace;

    /**
     * Create a new StringReplacementFilter with $search and $replace.
     *
     * @param string|array $search
     * @param string|array $replace
     */
    public function __construct($search, $replace)
    {
        $this->search = $search;
        $this->replace = $replace;
    }

    /**
     * Returns true if based on the buffer passed more bytes should be buffered.
     *
     * @param string $buffer
     *
     * @return bool
     */
    public function shouldBuffer($buffer)
    {
        if ('' === $buffer) {
            return false;
        }

        $endOfBuffer = substr($buffer, -1);
        foreach ((array) $this->search as $needle) {
            if (false !== strpos($needle, $endOfBuffer)) {
                return true;
            }
        }

        return false;
    }

    /**
     * Perform the actual replacements on $buffer and return the result.
     *
     * @param string $buffer
     *
     * @return string
     */
    public function filter($buffer)
    {
        return str_replace($this->search, $this->replace, $buffer);
    }
}


================================================
FILE: lib/classes/Swift/StreamFilters/StringReplacementFilterFactory.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Creates filters for replacing needles in a string buffer.
 *
 * @author Chris Corbyn
 */
class Swift_StreamFilters_StringReplacementFilterFactory implements Swift_ReplacementFilterFactory
{
    /** Lazy-loaded filters */
    private $filters = [];

    /**
     * Create a new StreamFilter to replace $search with $replace in a string.
     *
     * @param string $search
     * @param string $replace
     *
     * @return Swift_StreamFilter
     */
    public function createFilter($search, $replace)
    {
        if (!isset($this->filters[$search][$replace])) {
            if (!isset($this->filters[$search])) {
                $this->filters[$search] = [];
            }

            if (!isset($this->filters[$search][$replace])) {
                $this->filters[$search][$replace] = [];
            }

            $this->filters[$search][$replace] = new Swift_StreamFilters_StringReplacementFilter($search, $replace);
        }

        return $this->filters[$search][$replace];
    }
}


================================================
FILE: lib/classes/Swift/SwiftException.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Base Exception class.
 *
 * @author Chris Corbyn
 */
class Swift_SwiftException extends Exception
{
    /**
     * Create a new SwiftException with $message.
     *
     * @param string $message
     * @param int    $code
     */
    public function __construct($message, $code = 0, Exception $previous = null)
    {
        parent::__construct($message, $code, $previous);
    }
}


================================================
FILE: lib/classes/Swift/Transport/AbstractSmtpTransport.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Sends Messages over SMTP.
 *
 * @author Chris Corbyn
 */
abstract class Swift_Transport_AbstractSmtpTransport implements Swift_Transport
{
    /** Input-Output buffer for sending/receiving SMTP commands and responses */
    protected $buffer;

    /** Connection status */
    protected $started = false;

    /** The domain name to use in HELO command */
    protected $domain = '[127.0.0.1]';

    /** The event dispatching layer */
    protected $eventDispatcher;

    protected $addressEncoder;

    /** Whether the PIPELINING SMTP extension is enabled (RFC 2920) */
    protected $pipelining = null;

    /** The pipelined commands waiting for response */
    protected $pipeline = [];

    /** Source Ip */
    protected $sourceIp;

    /** Return an array of params for the Buffer */
    abstract protected function getBufferParams();

    /**
     * Creates a new EsmtpTransport using the given I/O buffer.
     *
     * @param string $localDomain
     */
    public function __construct(Swift_Transport_IoBuffer $buf, Swift_Events_EventDispatcher $dispatcher, $localDomain = '127.0.0.1', Swift_AddressEncoder $addressEncoder = null)
    {
        $this->buffer = $buf;
        $this->eventDispatcher = $dispatcher;
        $this->addressEncoder = $addressEncoder ?? new Swift_AddressEncoder_IdnAddressEncoder();
        $this->setLocalDomain($localDomain);
    }

    /**
     * Set the name of the local domain which Swift will identify itself as.
     *
     * This should be a fully-qualified domain name and should be truly the domain
     * you're using.
     *
     * If your server does not have a domain name, use the IP address. This will
     * automatically be wrapped in square brackets as described in RFC 5321,
     * section 4.1.3.
     *
     * @param string $domain
     *
     * @return $this
     */
    public function setLocalDomain($domain)
    {
        if ('[' !== substr($domain, 0, 1)) {
            if (filter_var($domain, FILTER_VALIDATE_IP, FILTER_FLAG_IPV4)) {
                $domain = '['.$domain.']';
            } elseif (filter_var($domain, FILTER_VALIDATE_IP, FILTER_FLAG_IPV6)) {
                $domain = '[IPv6:'.$domain.']';
            }
        }

        $this->domain = $domain;

        return $this;
    }

    /**
     * Get the name of the domain Swift will identify as.
     *
     * If an IP address was specified, this will be returned wrapped in square
     * brackets as described in RFC 5321, section 4.1.3.
     *
     * @return string
     */
    public function getLocalDomain()
    {
        return $this->domain;
    }

    /**
     * Sets the source IP.
     *
     * @param string $source
     */
    public function setSourceIp($source)
    {
        $this->sourceIp = $source;
    }

    /**
     * Returns the IP used to connect to the destination.
     *
     * @return string
     */
    public function getSourceIp()
    {
        return $this->sourceIp;
    }

    public function setAddressEncoder(Swift_AddressEncoder $addressEncoder)
    {
        $this->addressEncoder = $addressEncoder;
    }

    public function getAddressEncoder()
    {
        return $this->addressEncoder;
    }

    /**
     * Start the SMTP connection.
     */
    public function start()
    {
        if (!$this->started) {
            if ($evt = $this->eventDispatcher->createTransportChangeEvent($this)) {
                $this->eventDispatcher->dispatchEvent($evt, 'beforeTransportStarted');
                if ($evt->bubbleCancelled()) {
                    return;
                }
            }

            try {
                $this->buffer->initialize($this->getBufferParams());
            } catch (Swift_TransportException $e) {
                $this->throwException($e);
            }
            $this->readGreeting();
            $this->doHeloCommand();

            if ($evt) {
                $this->eventDispatcher->dispatchEvent($evt, 'transportStarted');
            }

            $this->started = true;
        }
    }

    /**
     * Test if an SMTP connection has been established.
     *
     * @return bool
     */
    public function isStarted()
    {
        return $this->started;
    }

    /**
     * Send the given Message.
     *
     * Recipient/sender data will be retrieved from the Message API.
     * The return value is the number of recipients who were accepted for delivery.
     *
     * @param string[] $failedRecipients An array of failures by-reference
     *
     * @return int
     */
    public function send(Swift_Mime_SimpleMessage $message, &$failedRecipients = null)
    {
        if (!$this->isStarted()) {
            $this->start();
        }

        $sent = 0;
        $failedRecipients = (array) $failedRecipients;

        if ($evt = $this->eventDispatcher->createSendEvent($this, $message)) {
            $this->eventDispatcher->dispatchEvent($evt, 'beforeSendPerformed');
            if ($evt->bubbleCancelled()) {
                return 0;
            }
        }

        if (!$reversePath = $this->getReversePath($message)) {
            $this->throwException(new Swift_TransportException('Cannot send message without a sender address'));
        }

        $to = (array) $message->getTo();
        $cc = (array) $message->getCc();
        $bcc = (array) $message->getBcc();
        $tos = array_merge($to, $cc, $bcc);

        $message->setBcc([]);

        try {
            $sent += $this->sendTo($message, $reversePath, $tos, $failedRecipients);
        } finally {
            $message->setBcc($bcc);
        }

        if ($evt) {
            if ($sent == \count($to) + \count($cc) + \count($bcc)) {
                $evt->setResult(Swift_Events_SendEvent::RESULT_SUCCESS);
            } elseif ($sent > 0) {
                $evt->setResult(Swift_Events_SendEvent::RESULT_TENTATIVE);
            } else {
                $evt->setResult(Swift_Events_SendEvent::RESULT_FAILED);
            }
            $evt->setFailedRecipients($failedRecipients);
            $this->eventDispatcher->dispatchEvent($evt, 'sendPerformed');
        }

        $message->generateId(); //Make sure a new Message ID is used

        return $sent;
    }

    /**
     * Stop the SMTP connection.
     */
    public function stop()
    {
        if ($this->started) {
            if ($evt = $this->eventDispatcher->createTransportChangeEvent($this)) {
                $this->eventDispatcher->dispatchEvent($evt, 'beforeTransportStopped');
                if ($evt->bubbleCancelled()) {
                    return;
                }
            }

            try {
                $this->executeCommand("QUIT\r\n", [221]);
            } catch (Swift_TransportException $e) {
            }

            try {
                $this->buffer->terminate();

                if ($evt) {
                    $this->eventDispatcher->dispatchEvent($evt, 'transportStopped');
                }
            } catch (Swift_TransportException $e) {
                $this->throwException($e);
            }
        }
        $this->started = false;
    }

    /**
     * {@inheritdoc}
     */
    public function ping()
    {
        try {
            if (!$this->isStarted()) {
                $this->start();
            }

            $this->executeCommand("NOOP\r\n", [250]);
        } catch (Swift_TransportException $e) {
            try {
                $this->stop();
            } catch (Swift_TransportException $e) {
            }

            return false;
        }

        return true;
    }

    /**
     * Register a plugin.
     */
    public function registerPlugin(Swift_Events_EventListener $plugin)
    {
        $this->eventDispatcher->bindEventListener($plugin);
    }

    /**
     * Reset the current mail transaction.
     */
    public function reset()
    {
        $this->executeCommand("RSET\r\n", [250], $failures, true);
    }

    /**
     * Get the IoBuffer where read/writes are occurring.
     *
     * @return Swift_Transport_IoBuffer
     */
    public function getBuffer()
    {
        return $this->buffer;
    }

    /**
     * Run a command against the buffer, expecting the given response codes.
     *
     * If no response codes are given, the response will not be validated.
     * If codes are given, an exception will be thrown on an invalid response.
     * If the command is RCPT TO, and the pipeline is non-empty, no exception
     * will be thrown; instead the failing address is added to $failures.
     *
     * @param string   $command
     * @param int[]    $codes
     * @param string[] $failures An array of failures by-reference
     * @param bool     $pipeline Do not wait for response
     * @param string   $address  the address, if command is RCPT TO
     *
     * @return string|null The server response, or null if pipelining is enabled
     */
    public function executeCommand($command, $codes = [], &$failures = null, $pipeline = false, $address = null)
    {
        $failures = (array) $failures;
        $seq = $this->buffer->write($command);
        if ($evt = $this->eventDispatcher->createCommandEvent($this, $command, $codes)) {
            $this->eventDispatcher->dispatchEvent($evt, 'commandSent');
        }

        $this->pipeline[] = [$command, $seq, $codes, $address];

        if ($pipeline && $this->pipelining) {
            return null;
        }

        $response = null;

        while ($this->pipeline) {
            list($command, $seq, $codes, $address) = array_shift($this->pipeline);
            $response = $this->getFullResponse($seq);
            try {
                $this->assertResponseCode($response, $codes);
            } catch (Swift_TransportException $e) {
                if ($this->pipeline && $address) {
                    $failures[] = $address;
                } else {
                    $this->throwException($e);
                }
            }
        }

        return $response;
    }

    /** Read the opening SMTP greeting */
    protected function readGreeting()
    {
        $this->assertResponseCode($this->getFullResponse(0), [220]);
    }

    /** Send the HELO welcome */
    protected function doHeloCommand()
    {
        $this->executeCommand(
            sprintf("HELO %s\r\n", $this->domain), [250]
            );
    }

    /** Send the MAIL FROM command */
    protected function doMailFromCommand($address)
    {
        $address = $this->addressEncoder->encodeString($address);
        $this->executeCommand(
            sprintf("MAIL FROM:<%s>\r\n", $address), [250], $failures, true
            );
    }

    /** Send the RCPT TO command */
    protected function doRcptToCommand($address)
    {
        $address = $this->addressEncoder->encodeString($address);
        $this->executeCommand(
            sprintf("RCPT TO:<%s>\r\n", $address), [250, 251, 252], $failures, true, $address
            );
    }

    /** Send the DATA command */
    protected function doDataCommand(&$failedRecipients)
    {
        $this->executeCommand("DATA\r\n", [354], $failedRecipients);
    }

    /** Stream the contents of the message over the buffer */
    protected function streamMessage(Swift_Mime_SimpleMessage $message)
    {
        $this->buffer->setWriteTranslations(["\r\n." => "\r\n.."]);
        try {
            $message->toByteStream($this->buffer);
            $this->buffer->flushBuffers();
        } catch (Swift_TransportException $e) {
            $this->throwException($e);
        }
        $this->buffer->setWriteTranslations([]);
        $this->executeCommand("\r\n.\r\n", [250]);
    }

    /** Determine the best-use reverse path for this message */
    protected function getReversePath(Swift_Mime_SimpleMessage $message)
    {
        $return = $message->getReturnPath();
        $sender = $message->getSender();
        $from = $message->getFrom();
        $path = null;
        if (!empty($return)) {
            $path = $return;
        } elseif (!empty($sender)) {
            // Don't use array_keys
            reset($sender); // Reset Pointer to first pos
            $path = key($sender); // Get key
        } elseif (!empty($from)) {
            reset($from); // Reset Pointer to first pos
            $path = key($from); // Get key
        }

        return $path;
    }

    /** Throw a TransportException, first sending it to any listeners */
    protected function throwException(Swift_TransportException $e)
    {
        if ($evt = $this->eventDispatcher->createTransportExceptionEvent($this, $e)) {
            $this->eventDispatcher->dispatchEvent($evt, 'exceptionThrown');
            if (!$evt->bubbleCancelled()) {
                throw $e;
            }
        } else {
            throw $e;
        }
    }

    /** Throws an Exception if a response code is incorrect */
    protected function assertResponseCode($response, $wanted)
    {
        if (!$response) {
            $this->throwException(new Swift_TransportException('Expected response code '.implode('/', $wanted).' but got an empty response'));
        }

        list($code) = sscanf($response, '%3d');
        $valid = (empty($wanted) || \in_array($code, $wanted));

        if ($evt = $this->eventDispatcher->createResponseEvent($this, $response,
            $valid)) {
            $this->eventDispatcher->dispatchEvent($evt, 'responseReceived');
        }

        if (!$valid) {
            $this->throwException(new Swift_TransportException('Expected response code '.implode('/', $wanted).' but got code "'.$code.'", with message "'.$response.'"', $code));
        }
    }

    /** Get an entire multi-line response using its sequence number */
    protected function getFullResponse($seq)
    {
        $response = '';
        try {
            do {
                $line = $this->buffer->readLine($seq);
                $response .= $line;
            } while (null !== $line && false !== $line && ' ' != $line[3]);
        } catch (Swift_TransportException $e) {
            $this->throwException($e);
        } catch (Swift_IoException $e) {
            $this->throwException(new Swift_TransportException($e->getMessage(), 0, $e));
        }

        return $response;
    }

    /** Send an email to the given recipients from the given reverse path */
    private function doMailTransaction($message, $reversePath, array $recipients, array &$failedRecipients)
    {
        $sent = 0;
        $this->doMailFromCommand($reversePath);
        foreach ($recipients as $forwardPath) {
            try {
                $this->doRcptToCommand($forwardPath);
                ++$sent;
            } catch (Swift_TransportException $e) {
                $failedRecipients[] = $forwardPath;
            } catch (Swift_AddressEncoderException $e) {
                $failedRecipients[] = $forwardPath;
            }
        }

        if (0 != $sent) {
            $sent += \count($failedRecipients);
            $this->doDataCommand($failedRecipients);
            $sent -= \count($failedRecipients);

            $this->streamMessage($message);
        } else {
            $this->reset();
        }

        return $sent;
    }

    /** Send a message to the given To: recipients */
    private function sendTo(Swift_Mime_SimpleMessage $message, $reversePath, array $to, array &$failedRecipients)
    {
        if (empty($to)) {
            return 0;
        }

        return $this->doMailTransaction($message, $reversePath, array_keys($to),
            $failedRecipients);
    }

    /**
     * Destructor.
     */
    public function __destruct()
    {
        try {
            $this->stop();
        } catch (Exception $e) {
        }
    }

    public function __sleep()
    {
        throw new \BadMethodCallException('Cannot serialize '.__CLASS__);
    }

    public function __wakeup()
    {
        throw new \BadMethodCallException('Cannot unserialize '.__CLASS__);
    }
}


================================================
FILE: lib/classes/Swift/Transport/Esmtp/Auth/CramMd5Authenticator.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Handles CRAM-MD5 authentication.
 *
 * @author Chris Corbyn
 */
class Swift_Transport_Esmtp_Auth_CramMd5Authenticator implements Swift_Transport_Esmtp_Authenticator
{
    /**
     * Get the name of the AUTH mechanism this Authenticator handles.
     *
     * @return string
     */
    public function getAuthKeyword()
    {
        return 'CRAM-MD5';
    }

    /**
     * {@inheritdoc}
     */
    public function authenticate(Swift_Transport_SmtpAgent $agent, $username, $password)
    {
        try {
            $challenge = $agent->executeCommand("AUTH CRAM-MD5\r\n", [334]);
            $challenge = base64_decode(substr($challenge, 4));
            $message = base64_encode(
                $username.' '.$this->getResponse($password, $challenge)
            );
            $agent->executeCommand(sprintf("%s\r\n", $message), [235]);

            return true;
        } catch (Swift_TransportException $e) {
            $agent->executeCommand("RSET\r\n", [250]);

            throw $e;
        }
    }

    /**
     * Generate a CRAM-MD5 response from a server challenge.
     *
     * @param string $secret
     * @param string $challenge
     *
     * @return string
     */
    private function getResponse($secret, $challenge)
    {
        if (\strlen($secret) > 64) {
            $secret = pack('H32', md5($secret));
        }

        if (\strlen($secret) < 64) {
            $secret = str_pad($secret, 64, \chr(0));
        }

        $k_ipad = substr($secret, 0, 64) ^ str_repeat(\chr(0x36), 64);
        $k_opad = substr($secret, 0, 64) ^ str_repeat(\chr(0x5C), 64);

        $inner = pack('H32', md5($k_ipad.$challenge));
        $digest = md5($k_opad.$inner);

        return $digest;
    }
}


================================================
FILE: lib/classes/Swift/Transport/Esmtp/Auth/LoginAuthenticator.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Handles LOGIN authentication.
 *
 * @author Chris Corbyn
 */
class Swift_Transport_Esmtp_Auth_LoginAuthenticator implements Swift_Transport_Esmtp_Authenticator
{
    /**
     * Get the name of the AUTH mechanism this Authenticator handles.
     *
     * @return string
     */
    public function getAuthKeyword()
    {
        return 'LOGIN';
    }

    /**
     * {@inheritdoc}
     */
    public function authenticate(Swift_Transport_SmtpAgent $agent, $username, $password)
    {
        try {
            $agent->executeCommand("AUTH LOGIN\r\n", [334]);
            $agent->executeCommand(sprintf("%s\r\n", base64_encode($username ?? '')), [334]);
            $agent->executeCommand(sprintf("%s\r\n", base64_encode($password ?? '')), [235]);

            return true;
        } catch (Swift_TransportException $e) {
            $agent->executeCommand("RSET\r\n", [250]);

            throw $e;
        }
    }
}


================================================
FILE: lib/classes/Swift/Transport/Esmtp/Auth/NTLMAuthenticator.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * This authentication is for Exchange servers. We support version 1 & 2.
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Handles NTLM authentication.
 *
 * @author     Ward Peeters <ward@coding-tech.com>
 */
class Swift_Transport_Esmtp_Auth_NTLMAuthenticator implements Swift_Transport_Esmtp_Authenticator
{
    const NTLMSIG = "NTLMSSP\x00";
    const DESCONST = 'KGS!@#$%';

    /**
     * Get the name of the AUTH mechanism this Authenticator handles.
     *
     * @return string
     */
    public function getAuthKeyword()
    {
        return 'NTLM';
    }

    /**
     * {@inheritdoc}
     *
     * @throws \LogicException
     */
    public function authenticate(Swift_Transport_SmtpAgent $agent, $username, $password)
    {
        if (!\function_exists('openssl_encrypt')) {
            throw new LogicException('The OpenSSL extension must be enabled to use the NTLM authenticator.');
        }

        if (!\function_exists('bcmul')) {
            throw new LogicException('The BCMath functions must be enabled to use the NTLM authenticator.');
        }

        try {
            // execute AUTH command and filter out the code at the beginning
            // AUTH NTLM xxxx
            $response = base64_decode(substr(trim($this->sendMessage1($agent) ?? ''), 4));

            // extra parameters for our unit cases
            $timestamp = \func_num_args() > 3 ? func_get_arg(3) : $this->getCorrectTimestamp(bcmul(microtime(true), '1000'));
            $client = \func_num_args() > 4 ? func_get_arg(4) : random_bytes(8);

            // Message 3 response
            $this->sendMessage3($response, $username, $password, $timestamp, $client, $agent);

            return true;
        } catch (Swift_TransportException $e) {
            $agent->executeCommand("RSET\r\n", [250]);

            throw $e;
        }
    }

    protected function si2bin($si, $bits = 32)
    {
        $bin = null;
        if ($si >= -2 ** ($bits - 1) && ($si <= 2 ** ($bits - 1))) {
            // positive or zero
            if ($si >= 0) {
                $bin = base_convert($si, 10, 2);
                // pad to $bits bit
                $bin_length = \strlen($bin);
                if ($bin_length < $bits) {
                    $bin = str_repeat('0', $bits - $bin_length).$bin;
                }
            } else {
                // negative
                $si = -$si - 2 ** $bits;
                $bin = base_convert($si, 10, 2);
                $bin_length = \strlen($bin);
                if ($bin_length > $bits) {
                    $bin = str_repeat('1', $bits - $bin_length).$bin;
                }
            }
        }

        return $bin;
    }

    /**
     * Send our auth message and returns the response.
     *
     * @return string SMTP Response
     */
    protected function sendMessage1(Swift_Transport_SmtpAgent $agent)
    {
        $message = $this->createMessage1();

        return $agent->executeCommand(sprintf("AUTH %s %s\r\n", $this->getAuthKeyword(), base64_encode($message)), [334]);
    }

    /**
     * Fetch all details of our response (message 2).
     *
     * @param string $response
     *
     * @return array our response parsed
     */
    protected function parseMessage2($response)
    {
        $responseHex = bin2hex($response);
        $length = floor(hexdec(substr($responseHex, 28, 4)) / 256) * 2;
        $offset = floor(hexdec(substr($responseHex, 32, 4)) / 256) * 2;
        $challenge = hex2bin(substr($responseHex, 48, 16));
        $context = hex2bin(substr($responseHex, 64, 16));
        $targetInfoH = hex2bin(substr($responseHex, 80, 16));
        $targetName = hex2bin(substr($responseHex, $offset, $length));
        $offset = floor(hexdec(substr($responseHex, 88, 4)) / 256) * 2;
        $targetInfoBlock = substr($responseHex, $offset);
        list($domainName, $serverName, $DNSDomainName, $DNSServerName, $terminatorByte) = $this->readSubBlock($targetInfoBlock);

        return [
            $challenge,
            $context,
            $targetInfoH,
            $targetName,
            $domainName,
            $serverName,
            $DNSDomainName,
            $DNSServerName,
            hex2bin($targetInfoBlock),
            $terminatorByte,
        ];
    }

    /**
     * Read the blob information in from message2.
     *
     * @return array
     */
    protected function readSubBlock($block)
    {
        // remove terminatorByte cause it's always the same
        $block = substr($block, 0, -8);

        $length = \strlen($block);
        $offset = 0;
        $data = [];
        while ($offset < $length) {
            $blockLength = hexdec(substr(substr($block, $offset, 8), -4)) / 256;
            $offset += 8;
            $data[] = hex2bin(substr($block, $offset, $blockLength * 2));
            $offset += $blockLength * 2;
        }

        if (3 == \count($data)) {
            $data[] = $data[2];
            $data[2] = '';
        }

        $data[] = $this->createByte('00');

        return $data;
    }

    /**
     * Send our final message with all our data.
     *
     * @param string $response  Message 1 response (message 2)
     * @param string $username
     * @param string $password
     * @param string $timestamp
     * @param string $client
     * @param bool   $v2        Use version2 of the protocol
     *
     * @return string
     */
    protected function sendMessage3($response, $username, $password, $timestamp, $client, Swift_Transport_SmtpAgent $agent, $v2 = true)
    {
        list($domain, $username) = $this->getDomainAndUsername($username);
        //$challenge, $context, $targetInfoH, $targetName, $domainName, $workstation, $DNSDomainName, $DNSServerName, $blob, $ter
        list($challenge, , , , , $workstation, , , $blob) = $this->parseMessage2($response);

        if (!$v2) {
            // LMv1
            $lmResponse = $this->createLMPassword($password, $challenge);
            // NTLMv1
            $ntlmResponse = $this->createNTLMPassword($password, $challenge);
        } else {
            // LMv2
            $lmResponse = $this->createLMv2Password($password, $username, $domain, $challenge, $client);
            // NTLMv2
            $ntlmResponse = $this->createNTLMv2Hash($password, $username, $domain, $challenge, $blob, $timestamp, $client);
        }

        $message = $this->createMessage3($domain, $username, $workstation, $lmResponse, $ntlmResponse);

        return $agent->executeCommand(sprintf("%s\r\n", base64_encode($message)), [235]);
    }

    /**
     * Create our message 1.
     *
     * @return string
     */
    protected function createMessage1()
    {
        return self::NTLMSIG
        .$this->createByte('01') // Message 1
.$this->createByte('0702'); // Flags
    }

    /**
     * Create our message 3.
     *
     * @param string $domain
     * @param string $username
     * @param string $workstation
     * @param string $lmResponse
     * @param string $ntlmResponse
     *
     * @return string
     */
    protected function createMessage3($domain, $username, $workstation, $lmResponse, $ntlmResponse)
    {
        // Create security buffers
        $domainSec = $this->createSecurityBuffer($domain, 64);
        $domainInfo = $this->readSecurityBuffer(bin2hex($domainSec));
        $userSec = $this->createSecurityBuffer($username, ($domainInfo[0] + $domainInfo[1]) / 2);
        $userInfo = $this->readSecurityBuffer(bin2hex($userSec));
        $workSec = $this->createSecurityBuffer($workstation, ($userInfo[0] + $userInfo[1]) / 2);
        $workInfo = $this->readSecurityBuffer(bin2hex($workSec));
        $lmSec = $this->createSecurityBuffer($lmResponse, ($workInfo[0] + $workInfo[1]) / 2, true);
        $lmInfo = $this->readSecurityBuffer(bin2hex($lmSec));
        $ntlmSec = $this->createSecurityBuffer($ntlmResponse, ($lmInfo[0] + $lmInfo[1]) / 2, true);

        return self::NTLMSIG
        .$this->createByte('03') // TYPE 3 message
.$lmSec // LM response header
.$ntlmSec // NTLM response header
.$domainSec // Domain header
.$userSec // User header
.$workSec // Workstation header
.$this->createByte('000000009a', 8) // session key header (empty)
.$this->createByte('01020000') // FLAGS
.$this->convertTo16bit($domain) // domain name
.$this->convertTo16bit($username) // username
.$this->convertTo16bit($workstation) // workstation
.$lmResponse
        .$ntlmResponse;
    }

    /**
     * @param string $timestamp  Epoch timestamp in microseconds
     * @param string $client     Random bytes
     * @param string $targetInfo
     *
     * @return string
     */
    protected function createBlob($timestamp, $client, $targetInfo)
    {
        return $this->createByte('0101')
        .$this->createByte('00')
        .$timestamp
        .$client
        .$this->createByte('00')
        .$targetInfo
        .$this->createByte('00');
    }

    /**
     * Get domain and username from our username.
     *
     * @example DOMAIN\username
     *
     * @param string $name
     *
     * @return array
     */
    protected function getDomainAndUsername($name)
    {
        if (false !== strpos($name, '\\')) {
            return explode('\\', $name);
        }

        if (false !== strpos($name, '@')) {
            list($user, $domain) = explode('@', $name);

            return [$domain, $user];
        }

        // no domain passed
        return ['', $name];
    }

    /**
     * Create LMv1 response.
     *
     * @param string $password
     * @param string $challenge
     *
     * @return string
     */
    protected function createLMPassword($password, $challenge)
    {
        // FIRST PART
        $password = $this->createByte(strtoupper($password), 14, false);
        list($key1, $key2) = str_split($password, 7);

        $desKey1 = $this->createDesKey($key1);
        $desKey2 = $this->createDesKey($key2);

        $constantDecrypt = $this->createByte($this->desEncrypt(self::DESCONST, $desKey1).$this->desEncrypt(self::DESCONST, $desKey2), 21, false);

        // SECOND PART
        list($key1, $key2, $key3) = str_split($constantDecrypt, 7);

        $desKey1 = $this->createDesKey($key1);
        $desKey2 = $this->createDesKey($key2);
        $desKey3 = $this->createDesKey($key3);

        return $this->desEncrypt($challenge, $desKey1).$this->desEncrypt($challenge, $desKey2).$this->desEncrypt($challenge, $desKey3);
    }

    /**
     * Create NTLMv1 response.
     *
     * @param string $password
     * @param string $challenge
     *
     * @return string
     */
    protected function createNTLMPassword($password, $challenge)
    {
        // FIRST PART
        $ntlmHash = $this->createByte($this->md4Encrypt($password), 21, false);
        list($key1, $key2, $key3) = str_split($ntlmHash, 7);

        $desKey1 = $this->createDesKey($key1);
        $desKey2 = $this->createDesKey($key2);
        $desKey3 = $this->createDesKey($key3);

        return $this->desEncrypt($challenge, $desKey1).$this->desEncrypt($challenge, $desKey2).$this->desEncrypt($challenge, $desKey3);
    }

    /**
     * Convert a normal timestamp to a tenth of a microtime epoch time.
     *
     * @param string $time
     *
     * @return string
     */
    protected function getCorrectTimestamp($time)
    {
        // Get our timestamp (tricky!)
        $time = number_format($time, 0, '.', ''); // save microtime to string
        $time = bcadd($time, '11644473600000', 0); // add epoch time
        $time = bcmul($time, 10000, 0); // tenths of a microsecond.

        $binary = $this->si2bin($time, 64); // create 64 bit binary string
        $timestamp = '';
        for ($i = 0; $i < 8; ++$i) {
            $timestamp .= \chr(bindec(substr($binary, -(($i + 1) * 8), 8)));
        }

        return $timestamp;
    }

    /**
     * Create LMv2 response.
     *
     * @param string $password
     * @param string $username
     * @param string $domain
     * @param string $challenge NTLM Challenge
     * @param string $client    Random string
     *
     * @return string
     */
    protected function createLMv2Password($password, $username, $domain, $challenge, $client)
    {
        $lmPass = '00'; // by default 00
        // if $password > 15 than we can't use this method
        if (\strlen($password) <= 15) {
            $ntlmHash = $this->md4Encrypt($password);
            $ntml2Hash = $this->md5Encrypt($ntlmHash, $this->convertTo16bit(strtoupper($username).$domain));

            $lmPass = bin2hex($this->md5Encrypt($ntml2Hash, $challenge.$client).$client);
        }

        return $this->createByte($lmPass, 24);
    }

    /**
     * Create NTLMv2 response.
     *
     * @param string $password
     * @param string $username
     * @param string $domain
     * @param string $challenge  Hex values
     * @param string $targetInfo Hex values
     * @param string $timestamp
     * @param string $client     Random bytes
     *
     * @return string
     *
     * @see http://davenport.sourceforge.net/ntlm.html#theNtlmResponse
     */
    protected function createNTLMv2Hash($password, $username, $domain, $challenge, $targetInfo, $timestamp, $client)
    {
        $ntlmHash = $this->md4Encrypt($password);
        $ntml2Hash = $this->md5Encrypt($ntlmHash, $this->convertTo16bit(strtoupper($username).$domain));

        // create blob
        $blob = $this->createBlob($timestamp, $client, $targetInfo);

        $ntlmv2Response = $this->md5Encrypt($ntml2Hash, $challenge.$blob);

        return $ntlmv2Response.$blob;
    }

    protected function createDesKey($key)
    {
        $material = [bin2hex($key[0])];
        $len = \strlen($key);
        for ($i = 1; $i < $len; ++$i) {
            list($high, $low) = str_split(bin2hex($key[$i]));
            $v = $this->castToByte(\ord($key[$i - 1]) << (7 + 1 - $i) | $this->uRShift(hexdec(dechex(hexdec($high) & 0xf).dechex(hexdec($low) & 0xf)), $i));
            $material[] = str_pad(substr(dechex($v), -2), 2, '0', STR_PAD_LEFT); // cast to byte
        }
        $material[] = str_pad(substr(dechex($this->castToByte(\ord($key[6]) << 1)), -2), 2, '0');

        // odd parity
        foreach ($material as $k => $v) {
            $b = $this->castToByte(hexdec($v));
            $needsParity = 0 == (($this->uRShift($b, 7) ^ $this->uRShift($b, 6) ^ $this->uRShift($b, 5)
                        ^ $this->uRShift($b, 4) ^ $this->uRShift($b, 3) ^ $this->uRShift($b, 2)
                        ^ $this->uRShift($b, 1)) & 0x01);

            list($high, $low) = str_split($v);
            if ($needsParity) {
                $material[$k] = dechex(hexdec($high) | 0x0).dechex(hexdec($low) | 0x1);
            } else {
                $material[$k] = dechex(hexdec($high) & 0xf).dechex(hexdec($low) & 0xe);
            }
        }

        return hex2bin(implode('', $material));
    }

    /** HELPER FUNCTIONS */

    /**
     * Create our security buffer depending on length and offset.
     *
     * @param string $value  Value we want to put in
     * @param int    $offset start of value
     * @param bool   $is16   Do we 16bit string or not?
     *
     * @return string
     */
    protected function createSecurityBuffer($value, $offset, $is16 = false)
    {
        $length = \strlen(bin2hex($value));
        $length = $is16 ? $length / 2 : $length;
        $length = $this->createByte(str_pad(dechex($length), 2, '0', STR_PAD_LEFT), 2);

        return $length.$length.$this->createByte(dechex($offset), 4);
    }

    /**
     * Read our security buffer to fetch length and offset of our value.
     *
     * @param string $value Securitybuffer in hex
     *
     * @return array array with length and offset
     */
    protected function readSecurityBuffer($value)
    {
        $length = floor(hexdec(substr($value, 0, 4)) / 256) * 2;
        $offset = floor(hexdec(substr($value, 8, 4)) / 256) * 2;

        return [$length, $offset];
    }

    /**
     * Cast to byte java equivalent to (byte).
     *
     * @param int $v
     *
     * @return int
     */
    protected function castToByte($v)
    {
        return (($v + 128) % 256) - 128;
    }

    /**
     * Java unsigned right bitwise
     * $a >>> $b.
     *
     * @param int $a
     * @param int $b
     *
     * @return int
     */
    protected function uRShift($a, $b)
    {
        if (0 == $b) {
            return $a;
        }

        return ($a >> $b) & ~(1 << (8 * PHP_INT_SIZE - 1) >> ($b - 1));
    }

    /**
     * Right padding with 0 to certain length.
     *
     * @param string $input
     * @param int    $bytes Length of bytes
     * @param bool   $isHex Did we provided hex value
     *
     * @return string
     */
    protected function createByte($input, $bytes = 4, $isHex = true)
    {
        if ($isHex) {
            $byte = hex2bin(str_pad($input, $bytes * 2, '00'));
        } else {
            $byte = str_pad($input, $bytes, "\x00");
        }

        return $byte;
    }

    /** ENCRYPTION ALGORITHMS */

    /**
     * DES Encryption.
     *
     * @param string $value An 8-byte string
     * @param string $key
     *
     * @return string
     */
    protected function desEncrypt($value, $key)
    {
        return substr(openssl_encrypt($value, 'DES-ECB', $key, \OPENSSL_RAW_DATA), 0, 8);
    }

    /**
     * MD5 Encryption.
     *
     * @param string $key Encryption key
     * @param string $msg Message to encrypt
     *
     * @return string
     */
    protected function md5Encrypt($key, $msg)
    {
        $blocksize = 64;
        if (\strlen($key) > $blocksize) {
            $key = pack('H*', md5($key));
        }

        $key = str_pad($key, $blocksize, "\0");
        $ipadk = $key ^ str_repeat("\x36", $blocksize);
        $opadk = $key ^ str_repeat("\x5c", $blocksize);

        return pack('H*', md5($opadk.pack('H*', md5($ipadk.$msg))));
    }

    /**
     * MD4 Encryption.
     *
     * @param string $input
     *
     * @return string
     *
     * @see https://secure.php.net/manual/en/ref.hash.php
     */
    protected function md4Encrypt($input)
    {
        $input = $this->convertTo16bit($input);

        return \function_exists('hash') ? hex2bin(hash('md4', $input)) : mhash(MHASH_MD4, $input);
    }

    /**
     * Convert UTF-8 to UTF-16.
     *
     * @param string $input
     *
     * @return string
     */
    protected function convertTo16bit($input)
    {
        return iconv('UTF-8', 'UTF-16LE', $input);
    }

    /**
     * @param string $message
     */
    protected function debug($message)
    {
        $message = bin2hex($message);
        $messageId = substr($message, 16, 8);
        echo substr($message, 0, 16)." NTLMSSP Signature<br />\n";
        echo $messageId." Type Indicator<br />\n";

        if ('02000000' == $messageId) {
            $map = [
                'Challenge',
                'Context',
                'Target Information Security Buffer',
                'Target Name Data',
                'NetBIOS Domain Name',
                'NetBIOS Server Name',
                'DNS Domain Name',
                'DNS Server Name',
                'BLOB',
                'Target Information Terminator',
            ];

            $data = $this->parseMessage2(hex2bin($message));

            foreach ($map as $key => $value) {
                echo bin2hex($data[$key]).' - '.$data[$key].' ||| '.$value."<br />\n";
            }
        } elseif ('03000000' == $messageId) {
            $i = 0;
            $data[$i++] = substr($message, 24, 16);
            list($lmLength, $lmOffset) = $this->readSecurityBuffer($data[$i - 1]);

            $data[$i++] = substr($message, 40, 16);
            list($ntmlLength, $ntmlOffset) = $this->readSecurityBuffer($data[$i - 1]);

            $data[$i++] = substr($message, 56, 16);
            list($targetLength, $targetOffset) = $this->readSecurityBuffer($data[$i - 1]);

            $data[$i++] = substr($message, 72, 16);
            list($userLength, $userOffset) = $this->readSecurityBuffer($data[$i - 1]);

            $data[$i++] = substr($message, 88, 16);
            list($workLength, $workOffset) = $this->readSecurityBuffer($data[$i - 1]);

            $data[$i++] = substr($message, 104, 16);
            $data[$i++] = substr($message, 120, 8);
            $data[$i++] = substr($message, $targetOffset, $targetLength);
            $data[$i++] = substr($message, $userOffset, $userLength);
            $data[$i++] = substr($message, $workOffset, $workLength);
            $data[$i++] = substr($message, $lmOffset, $lmLength);
            $data[$i] = substr($message, $ntmlOffset, $ntmlLength);

            $map = [
                'LM Response Security Buffer',
                'NTLM Response Security Buffer',
                'Target Name Security Buffer',
                'User Name Security Buffer',
                'Workstation Name Security Buffer',
                'Session Key Security Buffer',
                'Flags',
                'Target Name Data',
                'User Name Data',
                'Workstation Name Data',
                'LM Response Data',
                'NTLM Response Data',
            ];

            foreach ($map as $key => $value) {
                echo $data[$key].' - '.hex2bin($data[$key]).' ||| '.$value."<br />\n";
            }
        }

        echo '<br /><br />';
    }
}


================================================
FILE: lib/classes/Swift/Transport/Esmtp/Auth/PlainAuthenticator.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Handles PLAIN authentication.
 *
 * @author Chris Corbyn
 */
class Swift_Transport_Esmtp_Auth_PlainAuthenticator implements Swift_Transport_Esmtp_Authenticator
{
    /**
     * Get the name of the AUTH mechanism this Authenticator handles.
     *
     * @return string
     */
    public function getAuthKeyword()
    {
        return 'PLAIN';
    }

    /**
     * {@inheritdoc}
     */
    public function authenticate(Swift_Transport_SmtpAgent $agent, $username, $password)
    {
        try {
            $message = base64_encode($username.\chr(0).$username.\chr(0).$password);
            $agent->executeCommand(sprintf("AUTH PLAIN %s\r\n", $message), [235]);

            return true;
        } catch (Swift_TransportException $e) {
            $agent->executeCommand("RSET\r\n", [250]);

            throw $e;
        }
    }
}


================================================
FILE: lib/classes/Swift/Transport/Esmtp/Auth/XOAuth2Authenticator.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Handles XOAUTH2 authentication.
 *
 * Example:
 * <code>
 * $transport = (new Swift_SmtpTransport('smtp.gmail.com', 587, 'tls'))
 *   ->setAuthMode('XOAUTH2')
 *   ->setUsername('YOUR_EMAIL_ADDRESS')
 *   ->setPassword('YOUR_ACCESS_TOKEN');
 * </code>
 *
 * @author xu.li<AthenaLightenedMyPath@gmail.com>
 *
 * @see        https://developers.google.com/google-apps/gmail/xoauth2_protocol
 */
class Swift_Transport_Esmtp_Auth_XOAuth2Authenticator implements Swift_Transport_Esmtp_Authenticator
{
    /**
     * Get the name of the AUTH mechanism this Authenticator handles.
     *
     * @return string
     */
    public function getAuthKeyword()
    {
        return 'XOAUTH2';
    }

    /**
     * {@inheritdoc}
     */
    public function authenticate(Swift_Transport_SmtpAgent $agent, $email, $token)
    {
        try {
            $param = $this->constructXOAuth2Params($email, $token);
            $agent->executeCommand('AUTH XOAUTH2 '.$param."\r\n", [235]);

            return true;
        } catch (Swift_TransportException $e) {
            $agent->executeCommand("RSET\r\n", [250]);

            throw $e;
        }
    }

    /**
     * Construct the auth parameter.
     *
     * @see https://developers.google.com/google-apps/gmail/xoauth2_protocol#the_sasl_xoauth2_mechanism
     */
    protected function constructXOAuth2Params($email, $token)
    {
        return base64_encode("user=$email\1auth=Bearer $token\1\1");
    }
}


================================================
FILE: lib/classes/Swift/Transport/Esmtp/AuthHandler.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * An ESMTP handler for AUTH support (RFC 5248).
 *
 * @author Chris Corbyn
 */
class Swift_Transport_Esmtp_AuthHandler implements Swift_Transport_EsmtpHandler
{
    /**
     * Authenticators available to process the request.
     *
     * @var Swift_Transport_Esmtp_Authenticator[]
     */
    private $authenticators = [];

    /**
     * The username for authentication.
     *
     * @var string
     */
    private $username;

    /**
     * The password for authentication.
     *
     * @var string
     */
    private $password;

    /**
     * The auth mode for authentication.
     *
     * @var string
     */
    private $auth_mode;

    /**
     * The ESMTP AUTH parameters available.
     *
     * @var string[]
     */
    private $esmtpParams = [];

    /**
     * Create a new AuthHandler with $authenticators for support.
     *
     * @param Swift_Transport_Esmtp_Authenticator[] $authenticators
     */
    public function __construct(array $authenticators)
    {
        $this->setAuthenticators($authenticators);
    }

    /**
     * Set the Authenticators which can process a login request.
     *
     * @param Swift_Transport_Esmtp_Authenticator[] $authenticators
     */
    public function setAuthenticators(array $authenticators)
    {
        $this->authenticators = $authenticators;
    }

    /**
     * Get the Authenticators which can process a login request.
     *
     * @return Swift_Transport_Esmtp_Authenticator[]
     */
    public function getAuthenticators()
    {
        return $this->authenticators;
    }

    /**
     * Set the username to authenticate with.
     *
     * @param string $username
     */
    public function setUsername($username)
    {
        $this->username = $username;
    }

    /**
     * Get the username to authenticate with.
     *
     * @return string
     */
    public function getUsername()
    {
        return $this->username;
    }

    /**
     * Set the password to authenticate with.
     *
     * @param string $password
     */
    public function setPassword($password)
    {
        $this->password = $password;
    }

    /**
     * Get the password to authenticate with.
     *
     * @return string
     */
    public function getPassword()
    {
        return $this->password;
    }

    /**
     * Set the auth mode to use to authenticate.
     *
     * @param string $mode
     */
    public function setAuthMode($mode)
    {
        $this->auth_mode = $mode;
    }

    /**
     * Get the auth mode to use to authenticate.
     *
     * @return string
     */
    public function getAuthMode()
    {
        return $this->auth_mode;
    }

    /**
     * Get the name of the ESMTP extension this handles.
     *
     * @return string
     */
    public function getHandledKeyword()
    {
        return 'AUTH';
    }

    /**
     * Set the parameters which the EHLO greeting indicated.
     *
     * @param string[] $parameters
     */
    public function setKeywordParams(array $parameters)
    {
        $this->esmtpParams = $parameters;
    }

    /**
     * Runs immediately after a EHLO has been issued.
     *
     * @param Swift_Transport_SmtpAgent $agent to read/write
     */
    public function afterEhlo(Swift_Transport_SmtpAgent $agent)
    {
        if ($this->username) {
            $count = 0;
            $errors = [];
            foreach ($this->getAuthenticatorsForAgent() as $authenticator) {
                if (\in_array(strtolower($authenticator->getAuthKeyword() ?? ''), array_map('strtolower', $this->esmtpParams))) {
                    ++$count;
                    try {
                        if ($authenticator->authenticate($agent, $this->username, $this->password)) {
                            return;
                        }
                    } catch (Swift_TransportException $e) {
                        // keep the error message, but tries the other authenticators
                        $errors[] = [$authenticator->getAuthKeyword(), $e->getMessage()];
                    }
                }
            }

            $message = 'Failed to authenticate on SMTP server with username "'.$this->username.'" using '.$count.' possible authenticators.';
            foreach ($errors as $error) {
                $message .= ' Authenticator '.$error[0].' returned '.$error[1].'.';
            }
            throw new Swift_TransportException($message);
        }
    }

    /**
     * Not used.
     */
    public function getMailParams()
    {
        return [];
    }

    /**
     * Not used.
     */
    public function getRcptParams()
    {
        return [];
    }

    /**
     * Not used.
     */
    public function onCommand(Swift_Transport_SmtpAgent $agent, $command, $codes = [], &$failedRecipients = null, &$stop = false)
    {
    }

    /**
     * Returns +1, -1 or 0 according to the rules for usort().
     *
     * This method is called to ensure extensions can be execute in an appropriate order.
     *
     * @param string $esmtpKeyword to compare with
     *
     * @return int
     */
    public function getPriorityOver($esmtpKeyword)
    {
        return 0;
    }

    /**
     * Returns an array of method names which are exposed to the Esmtp class.
     *
     * @return string[]
     */
    public function exposeMixinMethods()
    {
        return ['setUsername', 'getUsername', 'setPassword', 'getPassword', 'setAuthMode', 'getAuthMode'];
    }

    /**
     * Not used.
     */
    public function resetState()
    {
    }

    /**
     * Returns the authenticator list for the given agent.
     *
     * @return array
     */
    protected function getAuthenticatorsForAgent()
    {
        if (!$mode = strtolower($this->auth_mode ?? '')) {
            return $this->authenticators;
        }

        foreach ($this->authenticators as $authenticator) {
            if (strtolower($authenticator->getAuthKeyword() ?? '') == $mode) {
                return [$authenticator];
            }
        }

        throw new Swift_TransportException('Auth mode '.$mode.' is invalid');
    }
}


================================================
FILE: lib/classes/Swift/Transport/Esmtp/Authenticator.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * An Authentication mechanism.
 *
 * @author Chris Corbyn
 */
interface Swift_Transport_Esmtp_Authenticator
{
    /**
     * Get the name of the AUTH mechanism this Authenticator handles.
     *
     * @return string
     */
    public function getAuthKeyword();

    /**
     * Try to authenticate the user with $username and $password.
     *
     * @param string $username
     * @param string $password
     *
     * @return bool true if authentication worked (returning false is deprecated, throw a Swift_TransportException instead)
     *
     * @throws Swift_TransportException Allows the message to bubble up when authentication was not successful
     */
    public function authenticate(Swift_Transport_SmtpAgent $agent, $username, $password);
}


================================================
FILE: lib/classes/Swift/Transport/Esmtp/EightBitMimeHandler.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2018 Christian Schmidt
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * An ESMTP handler for 8BITMIME support (RFC 6152).
 *
 * 8BITMIME is required when sending 8-bit content to over SMTP, e.g. when using
 * Swift_Mime_ContentEncoder_PlainContentEncoder in "8bit" mode.
 *
 * 8BITMIME mode is enabled unconditionally, even when sending ASCII-only
 * messages, so it should only be used with an outbound SMTP server that will
 * convert the message to 7-bit MIME if the next hop does not support 8BITMIME.
 *
 * @author Christian Schmidt
 */
class Swift_Transport_Esmtp_EightBitMimeHandler implements Swift_Transport_EsmtpHandler
{
    protected $encoding;

    /**
     * @param string $encoding The parameter so send with the MAIL FROM command;
     *                         either "8BITMIME" or "7BIT"
     */
    public function __construct(string $encoding = '8BITMIME')
    {
        $this->encoding = $encoding;
    }

    /**
     * Get the name of the ESMTP extension this handles.
     *
     * @return string
     */
    public function getHandledKeyword()
    {
        return '8BITMIME';
    }

    /**
     * Not used.
     */
    public function setKeywordParams(array $parameters)
    {
    }

    /**
     * Not used.
     */
    public function afterEhlo(Swift_Transport_SmtpAgent $agent)
    {
    }

    /**
     * Get params which are appended to MAIL FROM:<>.
     *
     * @return string[]
     */
    public function getMailParams()
    {
        return ['BODY='.$this->encoding];
    }

    /**
     * Not used.
     */
    public function getRcptParams()
    {
        return [];
    }

    /**
     * Not used.
     */
    public function onCommand(Swift_Transport_SmtpAgent $agent, $command, $codes = [], &$failedRecipients = null, &$stop = false)
    {
    }

    /**
     * Returns +1, -1 or 0 according to the rules for usort().
     *
     * This method is called to ensure extensions can be execute in an appropriate order.
     *
     * @param string $esmtpKeyword to compare with
     *
     * @return int
     */
    public function getPriorityOver($esmtpKeyword)
    {
        return 0;
    }

    /**
     * Not used.
     */
    public function exposeMixinMethods()
    {
        return [];
    }

    /**
     * Not used.
     */
    public function resetState()
    {
    }
}


================================================
FILE: lib/classes/Swift/Transport/Esmtp/SmtpUtf8Handler.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2018 Christian Schmidt
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * An ESMTP handler for SMTPUTF8 support (RFC 6531).
 *
 * SMTPUTF8 is required when sending to email addresses containing non-ASCII
 * characters in local-part (the substring before @). This handler should be
 * used together with Swift_AddressEncoder_Utf8AddressEncoder.
 *
 * SMTPUTF8 mode is enabled unconditionally, even when sending to ASCII-only
 * addresses, so it should only be used with an outbound SMTP server that will
 * deliver ASCII-only messages even if the next hop does not support SMTPUTF8.
 *
 * @author Christian Schmidt
 */
class Swift_Transport_Esmtp_SmtpUtf8Handler implements Swift_Transport_EsmtpHandler
{
    public function __construct()
    {
    }

    /**
     * Get the name of the ESMTP extension this handles.
     *
     * @return string
     */
    public function getHandledKeyword()
    {
        return 'SMTPUTF8';
    }

    /**
     * Not used.
     */
    public function setKeywordParams(array $parameters)
    {
    }

    /**
     * Not used.
     */
    public function afterEhlo(Swift_Transport_SmtpAgent $agent)
    {
    }

    /**
     * Get params which are appended to MAIL FROM:<>.
     *
     * @return string[]
     */
    public function getMailParams()
    {
        return ['SMTPUTF8'];
    }

    /**
     * Not used.
     */
    public function getRcptParams()
    {
        return [];
    }

    /**
     * Not used.
     */
    public function onCommand(Swift_Transport_SmtpAgent $agent, $command, $codes = [], &$failedRecipients = null, &$stop = false)
    {
    }

    /**
     * Returns +1, -1 or 0 according to the rules for usort().
     *
     * This method is called to ensure extensions can be execute in an appropriate order.
     *
     * @param string $esmtpKeyword to compare with
     *
     * @return int
     */
    public function getPriorityOver($esmtpKeyword)
    {
        return 0;
    }

    /**
     * Not used.
     */
    public function exposeMixinMethods()
    {
        return [];
    }

    /**
     * Not used.
     */
    public function resetState()
    {
    }
}


================================================
FILE: lib/classes/Swift/Transport/EsmtpHandler.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * An ESMTP handler.
 *
 * @author Chris Corbyn
 */
interface Swift_Transport_EsmtpHandler
{
    /**
     * Get the name of the ESMTP extension this handles.
     *
     * @return string
     */
    public function getHandledKeyword();

    /**
     * Set the parameters which the EHLO greeting indicated.
     *
     * @param string[] $parameters
     */
    public function setKeywordParams(array $parameters);

    /**
     * Runs immediately after a EHLO has been issued.
     *
     * @param Swift_Transport_SmtpAgent $agent to read/write
     */
    public function afterEhlo(Swift_Transport_SmtpAgent $agent);

    /**
     * Get params which are appended to MAIL FROM:<>.
     *
     * @return string[]
     */
    public function getMailParams();

    /**
     * Get params which are appended to RCPT TO:<>.
     *
     * @return string[]
     */
    public function getRcptParams();

    /**
     * Runs when a command is due to be sent.
     *
     * @param Swift_Transport_SmtpAgent $agent            to read/write
     * @param string                    $command          to send
     * @param int[]                     $codes            expected in response
     * @param string[]                  $failedRecipients to collect failures
     * @param bool                      $stop             to be set true  by-reference if the command is now sent
     */
    public function onCommand(Swift_Transport_SmtpAgent $agent, $command, $codes = [], &$failedRecipients = null, &$stop = false);

    /**
     * Returns +1, -1 or 0 according to the rules for usort().
     *
     * This method is called to ensure extensions can be execute in an appropriate order.
     *
     * @param string $esmtpKeyword to compare with
     *
     * @return int
     */
    public function getPriorityOver($esmtpKeyword);

    /**
     * Returns an array of method names which are exposed to the Esmtp class.
     *
     * @return string[]
     */
    public function exposeMixinMethods();

    /**
     * Tells this handler to clear any buffers and reset its state.
     */
    public function resetState();
}


================================================
FILE: lib/classes/Swift/Transport/EsmtpTransport.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Sends Messages over SMTP with ESMTP support.
 *
 * @author Chris Corbyn
 */
class Swift_Transport_EsmtpTransport extends Swift_Transport_AbstractSmtpTransport implements Swift_Transport_SmtpAgent
{
    /**
     * ESMTP extension handlers.
     *
     * @var Swift_Transport_EsmtpHandler[]
     */
    private $handlers = [];

    /**
     * ESMTP capabilities.
     *
     * @var string[]
     */
    private $capabilities = [];

    /**
     * Connection buffer parameters.
     *
     * @var array
     */
    private $params = [
        'protocol' => 'tcp',
        'host' => 'localhost',
        'port' => 25,
        'timeout' => 30,
        'blocking' => 1,
        'tls' => false,
        'type' => Swift_Transport_IoBuffer::TYPE_SOCKET,
        'stream_context_options' => [],
        ];

    /**
     * Creates a new EsmtpTransport using the given I/O buffer.
     *
     * @param Swift_Transport_EsmtpHandler[] $extensionHandlers
     * @param string                         $localDomain
     */
    public function __construct(Swift_Transport_IoBuffer $buf, array $extensionHandlers, Swift_Events_EventDispatcher $dispatcher, $localDomain = '127.0.0.1', Swift_AddressEncoder $addressEncoder = null)
    {
        parent::__construct($buf, $dispatcher, $localDomain, $addressEncoder);
        $this->setExtensionHandlers($extensionHandlers);
    }

    /**
     * Set the host to connect to.
     *
     * Literal IPv6 addresses should be wrapped in square brackets.
     *
     * @param string $host
     *
     * @return $this
     */
    public function setHost($host)
    {
        $this->params['host'] = $host;

        return $this;
    }

    /**
     * Get the host to connect to.
     *
     * @return string
     */
    public function getHost()
    {
        return $this->params['host'];
    }

    /**
     * Set the port to connect to.
     *
     * @param int $port
     *
     * @return $this
     */
    public function setPort($port)
    {
        $this->params['port'] = (int) $port;

        return $this;
    }

    /**
     * Get the port to connect to.
     *
     * @return int
     */
    public function getPort()
    {
        return $this->params['port'];
    }

    /**
     * Set the connection timeout.
     *
     * @param int $timeout seconds
     *
     * @return $this
     */
    public function setTimeout($timeout)
    {
        $this->params['timeout'] = (int) $timeout;
        $this->buffer->setParam('timeout', (int) $timeout);

        return $this;
    }

    /**
     * Get the connection timeout.
     *
     * @return int
     */
    public function getTimeout()
    {
        return $this->params['timeout'];
    }

    /**
     * Set the encryption type (tls or ssl).
     *
     * @param string $encryption
     *
     * @return $this
     */
    public function setEncryption($encryption)
    {
        $encryption = strtolower($encryption ?? '');
        if ('tls' == $encryption) {
            $this->params['protocol'] = 'tcp';
            $this->params['tls'] = true;
        } else {
            $this->params['protocol'] = $encryption;
            $this->params['tls'] = false;
        }

        return $this;
    }

    /**
     * Get the encryption type.
     *
     * @return string
     */
    public function getEncryption()
    {
        return $this->params['tls'] ? 'tls' : $this->params['protocol'];
    }

    /**
     * Sets the stream context options.
     *
     * @param array $options
     *
     * @return $this
     */
    public function setStreamOptions($options)
    {
        $this->params['stream_context_options'] = $options;

        return $this;
    }

    /**
     * Returns the stream context options.
     *
     * @return array
     */
    public function getStreamOptions()
    {
        return $this->params['stream_context_options'];
    }

    /**
     * Sets the source IP.
     *
     * IPv6 addresses should be wrapped in square brackets.
     *
     * @param string $source
     *
     * @return $this
     */
    public function setSourceIp($source)
    {
        $this->params['sourceIp'] = $source;

        return $this;
    }

    /**
     * Returns the IP used to connect to the destination.
     *
     * @return string
     */
    public function getSourceIp()
    {
        return $this->params['sourceIp'] ?? null;
    }

    /**
     * Sets whether SMTP pipelining is enabled.
     *
     * By default, support is auto-detected using the PIPELINING SMTP extension.
     * Use this function to override that in the unlikely event of compatibility
     * issues.
     *
     * @param bool $enabled
     *
     * @return $this
     */
    public function setPipelining($enabled)
    {
        $this->pipelining = $enabled;

        return $this;
    }

    /**
     * Returns whether SMTP pipelining is enabled.
     *
     * @return bool|null a boolean if pipelining is explicitly enabled or disabled,
     *                   or null if support is auto-detected
     */
    public function getPipelining()
    {
        return $this->pipelining;
    }

    /**
     * Set ESMTP extension handlers.
     *
     * @param Swift_Transport_EsmtpHandler[] $handlers
     *
     * @return $this
     */
    public function setExtensionHandlers(array $handlers)
    {
        $assoc = [];
        foreach ($handlers as $handler) {
            $assoc[$handler->getHandledKeyword()] = $handler;
        }
        uasort($assoc, function ($a, $b) {
            return $a->getPriorityOver($b->getHandledKeyword());
        });
        $this->handlers = $assoc;
        $this->setHandlerParams();

        return $this;
    }

    /**
     * Get ESMTP extension handlers.
     *
     * @return Swift_Transport_EsmtpHandler[]
     */
    public function getExtensionHandlers()
    {
        return array_values($this->handlers);
    }

    /**
     * Run a command against the buffer, expecting the given response codes.
     *
     * If no response codes are given, the response will not be validated.
     * If codes are given, an exception will be thrown on an invalid response.
     *
     * @param string   $command
     * @param int[]    $codes
     * @param string[] $failures An array of failures by-reference
     * @param bool     $pipeline Do not wait for response
     * @param string   $address  the address, if command is RCPT TO
     *
     * @return string|null The server response, or null if pipelining is enabled
     */
    public function executeCommand($command, $codes = [], &$failures = null, $pipeline = false, $address = null)
    {
        $failures = (array) $failures;
        $stopSignal = false;
        $response = null;
        foreach ($this->getActiveHandlers() as $handler) {
            $response = $handler->onCommand(
                $this, $command, $codes, $failures, $stopSignal
                );
            if ($stopSignal) {
                return $response;
            }
        }

        return parent::executeCommand($command, $codes, $failures, $pipeline, $address);
    }

    /** Mixin handling method for ESMTP handlers */
    public function __call($method, $args)
    {
        foreach ($this->handlers as $handler) {
            if (\in_array(strtolower($method),
                array_map('strtolower', (array) $handler->exposeMixinMethods())
                )) {
                $return = \call_user_func_array([$handler, $method], $args);
                // Allow fluid method calls
                if (null === $return && 'set' == substr($method, 0, 3)) {
                    return $this;
                } else {
                    return $return;
                }
            }
        }
        trigger_error('Call to undefined method '.$method, E_USER_ERROR);
    }

    /** Get the params to initialize the buffer */
    protected function getBufferParams()
    {
        return $this->params;
    }

    /** Overridden to perform EHLO instead */
    protected function doHeloCommand()
    {
        try {
            $response = $this->executeCommand(
                sprintf("EHLO %s\r\n", $this->domain), [250]
                );
        } catch (Swift_TransportException $e) {
            return parent::doHeloCommand();
        }

        if ($this->params['tls']) {
            try {
                $this->executeCommand("STARTTLS\r\n", [220]);

                if (!$this->buffer->startTLS()) {
                    throw new Swift_TransportException('Unable to connect with TLS encryption');
                }

                try {
                    $response = $this->executeCommand(
                        sprintf("EHLO %s\r\n", $this->domain), [250]
                        );
                } catch (Swift_TransportException $e) {
                    return parent::doHeloCommand();
                }
            } catch (Swift_TransportException $e) {
                $this->throwException($e);
            }
        }

        $this->capabilities = $this->getCapabilities($response);
        if (!isset($this->pipelining)) {
            $this->pipelining = isset($this->capabilities['PIPELINING']);
        }

        $this->setHandlerParams();
        foreach ($this->getActiveHandlers() as $handler) {
            $handler->afterEhlo($this);
        }
    }

    /** Overridden to add Extension support */
    protected function doMailFromCommand($address)
    {
        $address = $this->addressEncoder->encodeString($address);
        $handlers = $this->getActiveHandlers();
        $params = [];
        foreach ($handlers as $handler) {
            $params = array_merge($params, (array) $handler->getMailParams());
        }
        $paramStr = !empty($params) ? ' '.implode(' ', $params) : '';
        $this->executeCommand(
            sprintf("MAIL FROM:<%s>%s\r\n", $address, $paramStr), [250], $failures, true
            );
    }

    /** Overridden to add Extension support */
    protected function doRcptToCommand($address)
    {
        $address = $this->addressEncoder->encodeString($address);
        $handlers = $this->getActiveHandlers();
        $params = [];
        foreach ($handlers as $handler) {
            $params = array_merge($params, (array) $handler->getRcptParams());
        }
        $paramStr = !empty($params) ? ' '.implode(' ', $params) : '';
        $this->executeCommand(
            sprintf("RCPT TO:<%s>%s\r\n", $address, $paramStr), [250, 251, 252], $failures, true, $address
            );
    }

    /** Determine ESMTP capabilities by function group */
    private function getCapabilities($ehloResponse)
    {
        $capabilities = [];
        $ehloResponse = trim($ehloResponse ?? '');
        $lines = explode("\r\n", $ehloResponse);
        array_shift($lines);
        foreach ($lines as $line) {
            if (preg_match('/^[0-9]{3}[ -]([A-Z0-9-]+)((?:[ =].*)?)$/Di', $line, $matches)) {
                $keyword = strtoupper($matches[1]);
                $paramStr = strtoupper(ltrim($matches[2], ' ='));
                $params = !empty($paramStr) ? explode(' ', $paramStr) : [];
                $capabilities[$keyword] = $params;
            }
        }

        return $capabilities;
    }

    /** Set parameters which are used by each extension handler */
    private function setHandlerParams()
    {
        foreach ($this->handlers as $keyword => $handler) {
            if (\array_key_exists($keyword, $this->capabilities)) {
                $handler->setKeywordParams($this->capabilities[$keyword]);
            }
        }
    }

    /** Get ESMTP handlers which are currently ok to use */
    private function getActiveHandlers()
    {
        $handlers = [];
        foreach ($this->handlers as $keyword => $handler) {
            if (\array_key_exists($keyword, $this->capabilities)) {
                $handlers[] = $handler;
            }
        }

        return $handlers;
    }
}


================================================
FILE: lib/classes/Swift/Transport/FailoverTransport.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Contains a list of redundant Transports so when one fails, the next is used.
 *
 * @author Chris Corbyn
 */
class Swift_Transport_FailoverTransport extends Swift_Transport_LoadBalancedTransport
{
    /**
     * Registered transport currently used.
     *
     * @var Swift_Transport
     */
    private $currentTransport;

    // needed as __construct is called from elsewhere explicitly
    public function __construct()
    {
        parent::__construct();
    }

    /**
     * {@inheritdoc}
     */
    public function ping()
    {
        $maxTransports = \count($this->transports);
        for ($i = 0; $i < $maxTransports
            && $transport = $this->getNextTransport(); ++$i) {
            if ($transport->ping()) {
                return true;
            } else {
                $this->killCurrentTransport();
            }
        }

        return \count($this->transports) > 0;
    }

    /**
     * Send the given Message.
     *
     * Recipient/sender data will be retrieved from the Message API.
     * The return value is the number of recipients who were accepted for delivery.
     *
     * @param string[] $failedRecipients An array of failures by-reference
     *
     * @return int
     */
    public function send(Swift_Mime_SimpleMessage $message, &$failedRecipients = null)
    {
        $maxTransports = \count($this->transports);
        $sent = 0;
        $this->lastUsedTransport = null;

        for ($i = 0; $i < $maxTransports
            && $transport = $this->getNextTransport(); ++$i) {
            try {
                if (!$transport->isStarted()) {
                    $transport->start();
                }

                if ($sent = $transport->send($message, $failedRecipients)) {
                    $this->lastUsedTransport = $transport;

                    return $sent;
                }
            } catch (Swift_TransportException $e) {
                $this->killCurrentTransport();
            }
        }

        if (0 == \count($this->transports)) {
            throw new Swift_TransportException('All Transports in FailoverTransport failed, or no Transports available');
        }

        return $sent;
    }

    protected function getNextTransport()
    {
        if (!isset($this->currentTransport)) {
            $this->currentTransport = parent::getNextTransport();
        }

        return $this->currentTransport;
    }

    protected function killCurrentTransport()
    {
        $this->currentTransport = null;
        parent::killCurrentTransport();
    }
}


================================================
FILE: lib/classes/Swift/Transport/IoBuffer.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Buffers input and output to a resource.
 *
 * @author Chris Corbyn
 */
interface Swift_Transport_IoBuffer extends Swift_InputByteStream, Swift_OutputByteStream
{
    /** A socket buffer over TCP */
    const TYPE_SOCKET = 0x0001;

    /** A process buffer with I/O support */
    const TYPE_PROCESS = 0x0010;

    /**
     * Perform any initialization needed, using the given $params.
     *
     * Parameters will vary depending upon the type of IoBuffer used.
     */
    public function initialize(array $params);

    /**
     * Set an individual param on the buffer (e.g. switching to SSL).
     *
     * @param string $param
     * @param mixed  $value
     */
    public function setParam($param, $value);

    /**
     * Perform any shutdown logic needed.
     */
    public function terminate();

    /**
     * Set an array of string replacements which should be made on data written
     * to the buffer.
     *
     * This could replace LF with CRLF for example.
     *
     * @param string[] $replacements
     */
    public function setWriteTranslations(array $replacements);

    /**
     * Get a line of output (including any CRLF).
     *
     * The $sequence number comes from any writes and may or may not be used
     * depending upon the implementation.
     *
     * @param int $sequence of last write to scan from
     *
     * @return string
     */
    public function readLine($sequence);
}


================================================
FILE: lib/classes/Swift/Transport/LoadBalancedTransport.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Redundantly and rotationally uses several Transports when sending.
 *
 * @author Chris Corbyn
 */
class Swift_Transport_LoadBalancedTransport implements Swift_Transport
{
    /**
     * Transports which are deemed useless.
     *
     * @var Swift_Transport[]
     */
    private $deadTransports = [];

    /**
     * The Transports which are used in rotation.
     *
     * @var Swift_Transport[]
     */
    protected $transports = [];

    /**
     * The Transport used in the last successful send operation.
     *
     * @var Swift_Transport
     */
    protected $lastUsedTransport = null;

    // needed as __construct is called from elsewhere explicitly
    public function __construct()
    {
    }

    /**
     * Set $transports to delegate to.
     *
     * @param Swift_Transport[] $transports
     */
    public function setTransports(array $transports)
    {
        $this->transports = $transports;
        $this->deadTransports = [];
    }

    /**
     * Get $transports to delegate to.
     *
     * @return Swift_Transport[]
     */
    public function getTransports()
    {
        return array_merge($this->transports, $this->deadTransports);
    }

    /**
     * Get the Transport used in the last successful send operation.
     *
     * @return Swift_Transport
     */
    public function getLastUsedTransport()
    {
        return $this->lastUsedTransport;
    }

    /**
     * Test if this Transport mechanism has started.
     *
     * @return bool
     */
    public function isStarted()
    {
        return \count($this->transports) > 0;
    }

    /**
     * Start this Transport mechanism.
     */
    public function start()
    {
        $this->transports = array_merge($this->transports, $this->deadTransports);
    }

    /**
     * Stop this Transport mechanism.
     */
    public function stop()
    {
        foreach ($this->transports as $transport) {
            $transport->stop();
        }
    }

    /**
     * {@inheritdoc}
     */
    public function ping()
    {
        foreach ($this->transports as $transport) {
            if (!$transport->ping()) {
                $this->killCurrentTransport();
            }
        }

        return \count($this->transports) > 0;
    }

    /**
     * Send the given Message.
     *
     * Recipient/sender data will be retrieved from the Message API.
     * The return value is the number of recipients who were accepted for delivery.
     *
     * @param string[] $failedRecipients An array of failures by-reference
     *
     * @return int
     */
    public function send(Swift_Mime_SimpleMessage $message, &$failedRecipients = null)
    {
        $maxTransports = \count($this->transports);
        $sent = 0;
        $this->lastUsedTransport = null;

        for ($i = 0; $i < $maxTransports
            && $transport = $this->getNextTransport(); ++$i) {
            try {
                if (!$transport->isStarted()) {
                    $transport->start();
                }
                if ($sent = $transport->send($message, $failedRecipients)) {
                    $this->lastUsedTransport = $transport;
                    break;
                }
            } catch (Swift_TransportException $e) {
                $this->killCurrentTransport();
            }
        }

        if (0 == \count($this->transports)) {
            throw new Swift_TransportException('All Transports in LoadBalancedTransport failed, or no Transports available');
        }

        return $sent;
    }

    /**
     * Register a plugin.
     */
    public function registerPlugin(Swift_Events_EventListener $plugin)
    {
        foreach ($this->transports as $transport) {
            $transport->registerPlugin($plugin);
        }
    }

    /**
     * Rotates the transport list around and returns the first instance.
     *
     * @return Swift_Transport
     */
    protected function getNextTransport()
    {
        if ($next = array_shift($this->transports)) {
            $this->transports[] = $next;
        }

        return $next;
    }

    /**
     * Tag the currently used (top of stack) transport as dead/useless.
     */
    protected function killCurrentTransport()
    {
        if ($transport = array_pop($this->transports)) {
            try {
                $transport->stop();
            } catch (Exception $e) {
            }
            $this->deadTransports[] = $transport;
        }
    }
}


================================================
FILE: lib/classes/Swift/Transport/NullTransport.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2009 Fabien Potencier <fabien.potencier@gmail.com>
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Pretends messages have been sent, but just ignores them.
 *
 * @author Fabien Potencier
 */
class Swift_Transport_NullTransport implements Swift_Transport
{
    /** The event dispatcher from the plugin API */
    private $eventDispatcher;

    /**
     * Constructor.
     */
    public function __construct(Swift_Events_EventDispatcher $eventDispatcher)
    {
        $this->eventDispatcher = $eventDispatcher;
    }

    /**
     * Tests if this Transport mechanism has started.
     *
     * @return bool
     */
    public function isStarted()
    {
        return true;
    }

    /**
     * Starts this Transport mechanism.
     */
    public function start()
    {
    }

    /**
     * Stops this Transport mechanism.
     */
    public function stop()
    {
    }

    /**
     * {@inheritdoc}
     */
    public function ping()
    {
        return true;
    }

    /**
     * Sends the given message.
     *
     * @param string[] $failedRecipients An array of failures by-reference
     *
     * @return int The number of sent emails
     */
    public function send(Swift_Mime_SimpleMessage $message, &$failedRecipients = null)
    {
        if ($evt = $this->eventDispatcher->createSendEvent($this, $message)) {
            $this->eventDispatcher->dispatchEvent($evt, 'beforeSendPerformed');
            if ($evt->bubbleCancelled()) {
                return 0;
            }
        }

        if ($evt) {
            $evt->setResult(Swift_Events_SendEvent::RESULT_SUCCESS);
            $this->eventDispatcher->dispatchEvent($evt, 'sendPerformed');
        }

        $count = (
            \count((array) $message->getTo())
            + \count((array) $message->getCc())
            + \count((array) $message->getBcc())
            );

        return $count;
    }

    /**
     * Register a plugin.
     */
    public function registerPlugin(Swift_Events_EventListener $plugin)
    {
        $this->eventDispatcher->bindEventListener($plugin);
    }
}


================================================
FILE: lib/classes/Swift/Transport/SendmailTransport.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * SendmailTransport for sending mail through a Sendmail/Postfix (etc..) binary.
 *
 * Supported modes are -bs and -t, with any additional flags desired.
 * It is advised to use -bs mode since error reporting with -t mode is not
 * possible.
 *
 * @author Chris Corbyn
 */
class Swift_Transport_SendmailTransport extends Swift_Transport_AbstractSmtpTransport
{
    /**
     * Connection buffer parameters.
     *
     * @var array
     */
    private $params = [
        'timeout' => 30,
        'blocking' => 1,
        'command' => '/usr/sbin/sendmail -bs',
        'type' => Swift_Transport_IoBuffer::TYPE_PROCESS,
        ];

    /**
     * Create a new SendmailTransport with $buf for I/O.
     *
     * @param string $localDomain
     */
    public function __construct(Swift_Transport_IoBuffer $buf, Swift_Events_EventDispatcher $dispatcher, $localDomain = '127.0.0.1', Swift_AddressEncoder $addressEncoder = null)
    {
        parent::__construct($buf, $dispatcher, $localDomain, $addressEncoder);
    }

    /**
     * Start the standalone SMTP session if running in -bs mode.
     */
    public function start()
    {
        if (false !== strpos($this->getCommand(), ' -bs')) {
            parent::start();
        }
    }

    /**
     * Set the command to invoke.
     *
     * If using -t mode you are strongly advised to include -oi or -i in the flags.
     * For example: /usr/sbin/sendmail -oi -t
     * Swift will append a -f<sender> flag if one is not present.
     *
     * The recommended mode is "-bs" since it is interactive and failure notifications
     * are hence possible.
     *
     * @param string $command
     *
     * @return $this
     */
    public function setCommand($command)
    {
        $this->params['command'] = $command;

        return $this;
    }

    /**
     * Get the sendmail command which will be invoked.
     *
     * @return string
     */
    public function getCommand()
    {
        return $this->params['command'];
    }

    /**
     * Send the given Message.
     *
     * Recipient/sender data will be retrieved from the Message API.
     *
     * The return value is the number of recipients who were accepted for delivery.
     * NOTE: If using 'sendmail -t' you will not be aware of any failures until
     * they bounce (i.e. send() will always return 100% success).
     *
     * @param string[] $failedRecipients An array of failures by-reference
     *
     * @return int
     */
    public function send(Swift_Mime_SimpleMessage $message, &$failedRecipients = null)
    {
        $failedRecipients = (array) $failedRecipients;
        $command = $this->getCommand();
        $buffer = $this->getBuffer();
        $count = 0;

        if (false !== strpos($command, ' -t')) {
            if ($evt = $this->eventDispatcher->createSendEvent($this, $message)) {
                $this->eventDispatcher->dispatchEvent($evt, 'beforeSendPerformed');
                if ($evt->bubbleCancelled()) {
                    return 0;
                }
            }

            if (false === strpos($command, ' -f')) {
                $command .= ' -f'.escapeshellarg($this->getReversePath($message) ?? '');
            }

            $buffer->initialize(array_merge($this->params, ['command' => $command]));

            if (false === strpos($command, ' -i') && false === strpos($command, ' -oi')) {
                $buffer->setWriteTranslations(["\r\n" => "\n", "\n." => "\n.."]);
            } else {
                $buffer->setWriteTranslations(["\r\n" => "\n"]);
            }

            $count = \count((array) $message->getTo())
                + \count((array) $message->getCc())
                + \count((array) $message->getBcc())
                ;
            $message->toByteStream($buffer);
            $buffer->flushBuffers();
            $buffer->setWriteTranslations([]);
            $buffer->terminate();

            if ($evt) {
                $evt->setResult(Swift_Events_SendEvent::RESULT_SUCCESS);
                $evt->setFailedRecipients($failedRecipients);
                $this->eventDispatcher->dispatchEvent($evt, 'sendPerformed');
            }

            $message->generateId();
        } elseif (false !== strpos($command, ' -bs')) {
            $count = parent::send($message, $failedRecipients);
        } else {
            $this->throwException(new Swift_TransportException(
                'Unsupported sendmail command flags ['.$command.']. '.
                'Must be one of "-bs" or "-t" but can include additional flags.'
                ));
        }

        return $count;
    }

    /** Get the params to initialize the buffer */
    protected function getBufferParams()
    {
        return $this->params;
    }
}


================================================
FILE: lib/classes/Swift/Transport/SmtpAgent.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Wraps an IoBuffer to send/receive SMTP commands/responses.
 *
 * @author Chris Corbyn
 */
interface Swift_Transport_SmtpAgent
{
    /**
     * Get the IoBuffer where read/writes are occurring.
     *
     * @return Swift_Transport_IoBuffer
     */
    public function getBuffer();

    /**
     * Run a command against the buffer, expecting the given response codes.
     *
     * If no response codes are given, the response will not be validated.
     * If codes are given, an exception will be thrown on an invalid response.
     *
     * @param string   $command
     * @param int[]    $codes
     * @param string[] $failures An array of failures by-reference
     */
    public function executeCommand($command, $codes = [], &$failures = null);
}


================================================
FILE: lib/classes/Swift/Transport/SpoolTransport.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2009 Fabien Potencier <fabien.potencier@gmail.com>
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Stores Messages in a queue.
 *
 * @author Fabien Potencier
 */
class Swift_Transport_SpoolTransport implements Swift_Transport
{
    /** The spool instance */
    private $spool;

    /** The event dispatcher from the plugin API */
    private $eventDispatcher;

    /**
     * Constructor.
     */
    public function __construct(Swift_Events_EventDispatcher $eventDispatcher, Swift_Spool $spool = null)
    {
        $this->eventDispatcher = $eventDispatcher;
        $this->spool = $spool;
    }

    /**
     * Sets the spool object.
     *
     * @return $this
     */
    public function setSpool(Swift_Spool $spool)
    {
        $this->spool = $spool;

        return $this;
    }

    /**
     * Get the spool object.
     *
     * @return Swift_Spool
     */
    public function getSpool()
    {
        return $this->spool;
    }

    /**
     * Tests if this Transport mechanism has started.
     *
     * @return bool
     */
    public function isStarted()
    {
        return true;
    }

    /**
     * Starts this Transport mechanism.
     */
    public function start()
    {
    }

    /**
     * Stops this Transport mechanism.
     */
    public function stop()
    {
    }

    /**
     * {@inheritdoc}
     */
    public function ping()
    {
        return true;
    }

    /**
     * Sends the given message.
     *
     * @param string[] $failedRecipients An array of failures by-reference
     *
     * @return int The number of sent e-mail's
     */
    public function send(Swift_Mime_SimpleMessage $message, &$failedRecipients = null)
    {
        if ($evt = $this->eventDispatcher->createSendEvent($this, $message)) {
            $this->eventDispatcher->dispatchEvent($evt, 'beforeSendPerformed');
            if ($evt->bubbleCancelled()) {
                return 0;
            }
        }

        $success = $this->spool->queueMessage($message);

        if ($evt) {
            $evt->setResult($success ? Swift_Events_SendEvent::RESULT_SPOOLED : Swift_Events_SendEvent::RESULT_FAILED);
            $this->eventDispatcher->dispatchEvent($evt, 'sendPerformed');
        }

        return 1;
    }

    /**
     * Register a plugin.
     */
    public function registerPlugin(Swift_Events_EventListener $plugin)
    {
        $this->eventDispatcher->bindEventListener($plugin);
    }
}


================================================
FILE: lib/classes/Swift/Transport/StreamBuffer.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * A generic IoBuffer implementation supporting remote sockets and local processes.
 *
 * @author     Chris Corbyn
 */
class Swift_Transport_StreamBuffer extends Swift_ByteStream_AbstractFilterableInputStream implements Swift_Transport_IoBuffer
{
    /** A primary socket */
    private $stream;

    /** The input stream */
    private $in;

    /** The output stream */
    private $out;

    /** Buffer initialization parameters */
    private $params = [];

    /** The ReplacementFilterFactory */
    private $replacementFactory;

    /** Translations performed on data being streamed into the buffer */
    private $translations = [];

    /**
     * Create a new StreamBuffer using $replacementFactory for transformations.
     */
    public function __construct(Swift_ReplacementFilterFactory $replacementFactory)
    {
        $this->replacementFactory = $replacementFactory;
    }

    /**
     * Perform any initialization needed, using the given $params.
     *
     * Parameters will vary depending upon the type of IoBuffer used.
     */
    public function initialize(array $params)
    {
        $this->params = $params;
        switch ($params['type']) {
            case self::TYPE_PROCESS:
                $this->establishProcessConnection();
                break;
            case self::TYPE_SOCKET:
            default:
                $this->establishSocketConnection();
                break;
        }
    }

    /**
     * Set an individual param on the buffer (e.g. switching to SSL).
     *
     * @param string $param
     * @param mixed  $value
     */
    public function setParam($param, $value)
    {
        if (isset($this->stream)) {
            switch ($param) {
                case 'timeout':
                    if ($this->stream) {
                        stream_set_timeout($this->stream, $value);
                    }
                    break;

                case 'blocking':
                    if ($this->stream) {
                        stream_set_blocking($this->stream, 1);
                    }
            }
        }
        $this->params[$param] = $value;
    }

    public function startTLS()
    {
        // STREAM_CRYPTO_METHOD_TLS_CLIENT only allow tls1.0 connections (some php versions)
        // To support modern tls we allow explicit tls1.0, tls1.1, tls1.2
        // Ssl3 and older are not allowed because they are vulnerable
        // @TODO make tls arguments configurable
        return stream_socket_enable_crypto($this->stream, true, STREAM_CRYPTO_METHOD_TLSv1_0_CLIENT | STREAM_CRYPTO_METHOD_TLSv1_1_CLIENT | STREAM_CRYPTO_METHOD_TLSv1_2_CLIENT);
    }

    /**
     * Perform any shutdown logic needed.
     */
    public function terminate()
    {
        if (isset($this->stream)) {
            switch ($this->params['type']) {
                case self::TYPE_PROCESS:
                    fclose($this->in);
                    fclose($this->out);
                    proc_close($this->stream);
                    break;
                case self::TYPE_SOCKET:
                default:
                    fclose($this->stream);
                    break;
            }
        }
        $this->stream = null;
        $this->out = null;
        $this->in = null;
    }

    /**
     * Set an array of string replacements which should be made on data written
     * to the buffer.
     *
     * This could replace LF with CRLF for example.
     *
     * @param string[] $replacements
     */
    public function setWriteTranslations(array $replacements)
    {
        foreach ($this->translations as $search => $replace) {
            if (!isset($replacements[$search])) {
                $this->removeFilter($search);
                unset($this->translations[$search]);
            }
        }

        foreach ($replacements as $search => $replace) {
            if (!isset($this->translations[$search])) {
                $this->addFilter(
                    $this->replacementFactory->createFilter($search, $replace), $search
                    );
                $this->translations[$search] = true;
            }
        }
    }

    /**
     * Get a line of output (including any CRLF).
     *
     * The $sequence number comes from any writes and may or may not be used
     * depending upon the implementation.
     *
     * @param int $sequence of last write to scan from
     *
     * @return string
     *
     * @throws Swift_IoException
     */
    public function readLine($sequence)
    {
        if (isset($this->out) && !feof($this->out)) {
            $line = fgets($this->out);
            if (0 == \strlen($line)) {
                $metas = stream_get_meta_data($this->out);
                if ($metas['timed_out']) {
                    throw new Swift_IoException('Connection to '.$this->getReadConnectionDescription().' Timed Out');
                }
            }

            return $line;
        }
    }

    /**
     * Reads $length bytes from the stream into a string and moves the pointer
     * through the stream by $length.
     *
     * If less bytes exist than are requested the remaining bytes are given instead.
     * If no bytes are remaining at all, boolean false is returned.
     *
     * @param int $length
     *
     * @return string|bool
     *
     * @throws Swift_IoException
     */
    public function read($length)
    {
        if (isset($this->out) && !feof($this->out)) {
            $ret = fread($this->out, $length);
            if (0 == \strlen($ret)) {
                $metas = stream_get_meta_data($this->out);
                if ($metas['timed_out']) {
                    throw new Swift_IoException('Connection to '.$this->getReadConnectionDescription().' Timed Out');
                }
            }

            return $ret;
        }
    }

    /** Not implemented */
    public function setReadPointer($byteOffset)
    {
    }

    /** Flush the stream contents */
    protected function flush()
    {
        if (isset($this->in)) {
            fflush($this->in);
        }
    }

    /** Write this bytes to the stream */
    protected function doCommit($bytes)
    {
        if (isset($this->in)) {
            $bytesToWrite = \strlen($bytes);
            $totalBytesWritten = 0;

            while ($totalBytesWritten < $bytesToWrite) {
                $bytesWritten = fwrite($this->in, substr($bytes, $totalBytesWritten));
                if (false === $bytesWritten || 0 === $bytesWritten) {
                    break;
                }

                $totalBytesWritten += $bytesWritten;
            }

            if ($totalBytesWritten > 0) {
                return ++$this->sequence;
            }
        }
    }

    /**
     * Establishes a connection to a remote server.
     */
    private function establishSocketConnection()
    {
        $host = $this->params['host'];
        if (!empty($this->params['protocol'])) {
            $host = $this->params['protocol'].'://'.$host;
        }
        $timeout = 15;
        if (!empty($this->params['timeout'])) {
            $timeout = $this->params['timeout'];
        }
        $options = [];
        if (!empty($this->params['sourceIp'])) {
            $options['socket']['bindto'] = $this->params['sourceIp'].':0';
        }

        if (isset($this->params['stream_context_options'])) {
            $options = array_merge($options, $this->params['stream_context_options']);
        }
        $streamContext = stream_context_create($options);

        set_error_handler(function ($type, $msg) {
            throw new Swift_TransportException('Connection could not be established with host '.$this->params['host'].' :'.$msg);
        });
        try {
            $this->stream = stream_socket_client($host.':'.$this->params['port'], $errno, $errstr, $timeout, STREAM_CLIENT_CONNECT, $streamContext);
        } finally {
            restore_error_handler();
        }

        if (!empty($this->params['blocking'])) {
            stream_set_blocking($this->stream, 1);
        } else {
            stream_set_blocking($this->stream, 0);
        }
        stream_set_timeout($this->stream, $timeout);
        $this->in = &$this->stream;
        $this->out = &$this->stream;
    }

    /**
     * Opens a process for input/output.
     */
    private function establishProcessConnection()
    {
        $command = $this->params['command'];
        $descriptorSpec = [
            0 => ['pipe', 'r'],
            1 => ['pipe', 'w'],
            2 => ['pipe', 'w'],
            ];
        $pipes = [];
        $this->stream = proc_open($command, $descriptorSpec, $pipes);
        stream_set_blocking($pipes[2], 0);
        if ($err = stream_get_contents($pipes[2])) {
            throw new Swift_TransportException('Process could not be started ['.$err.']');
        }
        $this->in = &$pipes[0];
        $this->out = &$pipes[1];
    }

    private function getReadConnectionDescription()
    {
        switch ($this->params['type']) {
            case self::TYPE_PROCESS:
                return 'Process '.$this->params['command'];
                break;

            case self::TYPE_SOCKET:
            default:
                $host = $this->params['host'];
                if (!empty($this->params['protocol'])) {
                    $host = $this->params['protocol'].'://'.$host;
                }
                $host .= ':'.$this->params['port'];

                return $host;
                break;
        }
    }
}


================================================
FILE: lib/classes/Swift/Transport.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * Sends Messages via an abstract Transport subsystem.
 *
 * @author Chris Corbyn
 */
interface Swift_Transport
{
    /**
     * Test if this Transport mechanism has started.
     *
     * @return bool
     */
    public function isStarted();

    /**
     * Start this Transport mechanism.
     */
    public function start();

    /**
     * Stop this Transport mechanism.
     */
    public function stop();

    /**
     * Check if this Transport mechanism is alive.
     *
     * If a Transport mechanism session is no longer functional, the method
     * returns FALSE. It is the responsibility of the developer to handle this
     * case and restart the Transport mechanism manually.
     *
     * @example
     *
     *   if (!$transport->ping()) {
     *      $transport->stop();
     *      $transport->start();
     *   }
     *
     * The Transport mechanism will be started, if it is not already.
     *
     * It is undefined if the Transport mechanism attempts to restart as long as
     * the return value reflects whether the mechanism is now functional.
     *
     * @return bool TRUE if the transport is alive
     */
    public function ping();

    /**
     * Send the given Message.
     *
     * Recipient/sender data will be retrieved from the Message API.
     * The return value is the number of recipients who were accepted for delivery.
     *
     * This is the responsibility of the send method to start the transport if needed.
     *
     * @param string[] $failedRecipients An array of failures by-reference
     *
     * @return int
     */
    public function send(Swift_Mime_SimpleMessage $message, &$failedRecipients = null);

    /**
     * Register a plugin in the Transport.
     */
    public function registerPlugin(Swift_Events_EventListener $plugin);
}


================================================
FILE: lib/classes/Swift/TransportException.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * TransportException thrown when an error occurs in the Transport subsystem.
 *
 * @author Chris Corbyn
 */
class Swift_TransportException extends Swift_IoException
{
    /**
     * Create a new TransportException with $message.
     *
     * @param string $message
     * @param int    $code
     */
    public function __construct($message, $code = 0, Exception $previous = null)
    {
        parent::__construct($message, $code, $previous);
    }
}


================================================
FILE: lib/classes/Swift.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

/**
 * General utility class in Swift Mailer, not to be instantiated.
 *
 * @author Chris Corbyn
 */
abstract class Swift
{
    const VERSION = '6.3.0';

    public static $initialized = false;
    public static $inits = [];

    /**
     * Registers an initializer callable that will be called the first time
     * a SwiftMailer class is autoloaded.
     *
     * This enables you to tweak the default configuration in a lazy way.
     *
     * @param mixed $callable A valid PHP callable that will be called when autoloading the first Swift class
     */
    public static function init($callable)
    {
        self::$inits[] = $callable;
    }

    /**
     * Internal autoloader for spl_autoload_register().
     *
     * @param string $class
     */
    public static function autoload($class)
    {
        // Don't interfere with other autoloaders
        if (0 !== strpos($class, 'Swift_')) {
            return;
        }

        $path = __DIR__.'/'.str_replace('_', '/', $class).'.php';

        if (!file_exists($path)) {
            return;
        }

        require $path;

        if (self::$inits && !self::$initialized) {
            self::$initialized = true;
            foreach (self::$inits as $init) {
                \call_user_func($init);
            }
        }
    }

    /**
     * Configure autoloading using Swift Mailer.
     *
     * This is designed to play nicely with other autoloaders.
     *
     * @param mixed $callable A valid PHP callable that will be called when autoloading the first Swift class
     */
    public static function registerAutoload($callable = null)
    {
        if (null !== $callable) {
            self::$inits[] = $callable;
        }
        spl_autoload_register(['Swift', 'autoload']);
    }
}


================================================
FILE: lib/dependency_maps/cache_deps.php
================================================
<?php

Swift_DependencyContainer::getInstance()
    ->register('cache')
    ->asAliasOf('cache.array')

    ->register('tempdir')
    ->asValue('/tmp')

    ->register('cache.null')
    ->asSharedInstanceOf('Swift_KeyCache_NullKeyCache')

    ->register('cache.array')
    ->asSharedInstanceOf('Swift_KeyCache_ArrayKeyCache')
    ->withDependencies(['cache.inputstream'])

    ->register('cache.disk')
    ->asSharedInstanceOf('Swift_KeyCache_DiskKeyCache')
    ->withDependencies(['cache.inputstream', 'tempdir'])

    ->register('cache.inputstream')
    ->asNewInstanceOf('Swift_KeyCache_SimpleKeyCacheInputStream')
;


================================================
FILE: lib/dependency_maps/message_deps.php
================================================
<?php

Swift_DependencyContainer::getInstance()
    ->register('message.message')
    ->asNewInstanceOf('Swift_Message')

    ->register('message.mimepart')
    ->asNewInstanceOf('Swift_MimePart')
;


================================================
FILE: lib/dependency_maps/mime_deps.php
================================================
<?php

require __DIR__.'/../mime_types.php';

Swift_DependencyContainer::getInstance()
    ->register('properties.charset')
    ->asValue('utf-8')

    ->register('email.validator')
    ->asSharedInstanceOf('Egulias\EmailValidator\EmailValidator')

    ->register('mime.idgenerator.idright')
    // As SERVER_NAME can come from the user in certain configurations, check that
    // it does not contain forbidden characters (see RFC 952 and RFC 2181). Use
    // preg_replace() instead of preg_match() to prevent DoS attacks with long host names.
    ->asValue(!empty($_SERVER['SERVER_NAME']) && '' === preg_replace('/(?:^\[)?[a-zA-Z0-9-:\]_]+\.?/', '', $_SERVER['SERVER_NAME']) ? $_SERVER['SERVER_NAME'] : 'swift.generated')

    ->register('mime.idgenerator')
    ->asSharedInstanceOf('Swift_Mime_IdGenerator')
    ->withDependencies([
        'mime.idgenerator.idright',
    ])

    ->register('mime.message')
    ->asNewInstanceOf('Swift_Mime_SimpleMessage')
    ->withDependencies([
        'mime.headerset',
        'mime.textcontentencoder',
        'cache',
        'mime.idgenerator',
        'properties.charset',
    ])

    ->register('mime.part')
    ->asNewInstanceOf('Swift_Mime_MimePart')
    ->withDependencies([
        'mime.headerset',
        'mime.textcontentencoder',
        'cache',
        'mime.idgenerator',
        'properties.charset',
    ])

    ->register('mime.attachment')
    ->asNewInstanceOf('Swift_Mime_Attachment')
    ->withDependencies([
        'mime.headerset',
        'mime.base64contentencoder',
        'cache',
        'mime.idgenerator',
    ])
    ->addConstructorValue($swift_mime_types)

    ->register('mime.embeddedfile')
    ->asNewInstanceOf('Swift_Mime_EmbeddedFile')
    ->withDependencies([
        'mime.headerset',
        'mime.base64contentencoder',
        'cache',
        'mime.idgenerator',
    ])
    ->addConstructorValue($swift_mime_types)

    ->register('mime.headerfactory')
    ->asNewInstanceOf('Swift_Mime_SimpleHeaderFactory')
    ->withDependencies([
        'mime.qpheaderencoder',
        'mime.rfc2231encoder',
        'email.validator',
        'properties.charset',
        'address.idnaddressencoder',
    ])

    ->register('mime.headerset')
    ->asNewInstanceOf('Swift_Mime_SimpleHeaderSet')
    ->withDependencies(['mime.headerfactory', 'properties.charset'])

    ->register('mime.qpheaderencoder')
    ->asNewInstanceOf('Swift_Mime_HeaderEncoder_QpHeaderEncoder')
    ->withDependencies(['mime.charstream'])

    ->register('mime.base64headerencoder')
    ->asNewInstanceOf('Swift_Mime_HeaderEncoder_Base64HeaderEncoder')
    ->withDependencies(['mime.charstream'])

    ->register('mime.charstream')
    ->asNewInstanceOf('Swift_CharacterStream_NgCharacterStream')
    ->withDependencies(['mime.characterreaderfactory', 'properties.charset'])

    ->register('mime.bytecanonicalizer')
    ->asSharedInstanceOf('Swift_StreamFilters_ByteArrayReplacementFilter')
    ->addConstructorValue([[0x0D, 0x0A], [0x0D], [0x0A]])
    ->addConstructorValue([[0x0A], [0x0A], [0x0D, 0x0A]])

    ->register('mime.characterreaderfactory')
    ->asSharedInstanceOf('Swift_CharacterReaderFactory_SimpleCharacterReaderFactory')

    ->register('mime.textcontentencoder')
    ->asAliasOf('mime.qpcontentencoder')

    ->register('mime.safeqpcontentencoder')
    ->asNewInstanceOf('Swift_Mime_ContentEncoder_QpContentEncoder')
    ->withDependencies(['mime.charstream', 'mime.bytecanonicalizer'])

    ->register('mime.rawcontentencoder')
    ->asNewInstanceOf('Swift_Mime_ContentEncoder_RawContentEncoder')

    ->register('mime.nativeqpcontentencoder')
    ->withDependencies(['properties.charset'])
    ->asNewInstanceOf('Swift_Mime_ContentEncoder_NativeQpContentEncoder')

    ->register('mime.qpcontentencoder')
    ->asNewInstanceOf('Swift_Mime_ContentEncoder_QpContentEncoderProxy')
    ->withDependencies(['mime.safeqpcontentencoder', 'mime.nativeqpcontentencoder', 'properties.charset'])

    ->register('mime.7bitcontentencoder')
    ->asNewInstanceOf('Swift_Mime_ContentEncoder_PlainContentEncoder')
    ->addConstructorValue('7bit')
    ->addConstructorValue(true)

    ->register('mime.8bitcontentencoder')
    ->asNewInstanceOf('Swift_Mime_ContentEncoder_PlainContentEncoder')
    ->addConstructorValue('8bit')
    ->addConstructorValue(true)

    ->register('mime.base64contentencoder')
    ->asSharedInstanceOf('Swift_Mime_ContentEncoder_Base64ContentEncoder')

    ->register('mime.rfc2231encoder')
    ->asNewInstanceOf('Swift_Encoder_Rfc2231Encoder')
    ->withDependencies(['mime.charstream'])
;

unset($swift_mime_types);


================================================
FILE: lib/dependency_maps/transport_deps.php
================================================
<?php

Swift_DependencyContainer::getInstance()
    ->register('transport.localdomain')
    // As SERVER_NAME can come from the user in certain configurations, check that
    // it does not contain forbidden characters (see RFC 952 and RFC 2181). Use
    // preg_replace() instead of preg_match() to prevent DoS attacks with long host names.
    ->asValue(!empty($_SERVER['SERVER_NAME']) && '' === preg_replace('/(?:^\[)?[a-zA-Z0-9-:\]_]+\.?/', '', $_SERVER['SERVER_NAME']) ? trim($_SERVER['SERVER_NAME'], '[]') : '127.0.0.1')

    ->register('transport.smtp')
    ->asNewInstanceOf('Swift_Transport_EsmtpTransport')
    ->withDependencies([
        'transport.buffer',
        'transport.smtphandlers',
        'transport.eventdispatcher',
        'transport.localdomain',
        'address.idnaddressencoder',
    ])

    ->register('transport.sendmail')
    ->asNewInstanceOf('Swift_Transport_SendmailTransport')
    ->withDependencies([
        'transport.buffer',
        'transport.eventdispatcher',
        'transport.localdomain',
    ])

    ->register('transport.loadbalanced')
    ->asNewInstanceOf('Swift_Transport_LoadBalancedTransport')

    ->register('transport.failover')
    ->asNewInstanceOf('Swift_Transport_FailoverTransport')

    ->register('transport.spool')
    ->asNewInstanceOf('Swift_Transport_SpoolTransport')
    ->withDependencies(['transport.eventdispatcher'])

    ->register('transport.null')
    ->asNewInstanceOf('Swift_Transport_NullTransport')
    ->withDependencies(['transport.eventdispatcher'])

    ->register('transport.buffer')
    ->asNewInstanceOf('Swift_Transport_StreamBuffer')
    ->withDependencies(['transport.replacementfactory'])

    ->register('transport.smtphandlers')
    ->asArray()
    ->withDependencies(['transport.authhandler'])

    ->register('transport.authhandler')
    ->asNewInstanceOf('Swift_Transport_Esmtp_AuthHandler')
    ->withDependencies(['transport.authhandlers'])

    ->register('transport.authhandlers')
    ->asArray()
    ->withDependencies([
        'transport.crammd5auth',
        'transport.loginauth',
        'transport.plainauth',
        'transport.ntlmauth',
        'transport.xoauth2auth',
    ])

    ->register('transport.smtputf8handler')
    ->asNewInstanceOf('Swift_Transport_Esmtp_SmtpUtf8Handler')

    ->register('transport.8bitmimehandler')
    ->asNewInstanceOf('Swift_Transport_Esmtp_EightBitMimeHandler')
    ->addConstructorValue('8BITMIME')

    ->register('transport.crammd5auth')
    ->asNewInstanceOf('Swift_Transport_Esmtp_Auth_CramMd5Authenticator')

    ->register('transport.loginauth')
    ->asNewInstanceOf('Swift_Transport_Esmtp_Auth_LoginAuthenticator')

    ->register('transport.plainauth')
    ->asNewInstanceOf('Swift_Transport_Esmtp_Auth_PlainAuthenticator')

    ->register('transport.xoauth2auth')
    ->asNewInstanceOf('Swift_Transport_Esmtp_Auth_XOAuth2Authenticator')

    ->register('transport.ntlmauth')
    ->asNewInstanceOf('Swift_Transport_Esmtp_Auth_NTLMAuthenticator')

    ->register('transport.eventdispatcher')
    ->asNewInstanceOf('Swift_Events_SimpleEventDispatcher')

    ->register('transport.replacementfactory')
    ->asSharedInstanceOf('Swift_StreamFilters_StringReplacementFilterFactory')

    ->register('address.idnaddressencoder')
    ->asNewInstanceOf('Swift_AddressEncoder_IdnAddressEncoder')

    ->register('address.utf8addressencoder')
    ->asNewInstanceOf('Swift_AddressEncoder_Utf8AddressEncoder')
;


================================================
FILE: lib/mime_types.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 *
 * autogenerated using https://svn.apache.org/repos/asf/httpd/httpd/trunk/docs/conf/mime.types
 * and https://raw.github.com/minad/mimemagic/master/script/freedesktop.org.xml
 */

/*
 * List of MIME type automatically detected in Swift Mailer.
 */

// You may add or take away what you like (lowercase required)

$swift_mime_types = [
    '3dml' => 'text/vnd.in3d.3dml',
    '3ds' => 'image/x-3ds',
    '3g2' => 'video/3gpp2',
    '3gp' => 'video/3gpp',
    '7z' => 'application/x-7z-compressed',
    'aab' => 'application/x-authorware-bin',
    'aac' => 'audio/x-aac',
    'aam' => 'application/x-authorware-map',
    'aas' => 'application/x-authorware-seg',
    'abw' => 'application/x-abiword',
    'ac' => 'application/pkix-attr-cert',
    'acc' => 'application/vnd.americandynamics.acc',
    'ace' => 'application/x-ace-compressed',
    'acu' => 'application/vnd.acucobol',
    'acutc' => 'application/vnd.acucorp',
    'adp' => 'audio/adpcm',
    'aep' => 'application/vnd.audiograph',
    'afm' => 'application/x-font-type1',
    'afp' => 'application/vnd.ibm.modcap',
    'ahead' => 'application/vnd.ahead.space',
    'ai' => 'application/postscript',
    'aif' => 'audio/x-aiff',
    'aifc' => 'audio/x-aiff',
    'aiff' => 'audio/x-aiff',
    'air' => 'application/vnd.adobe.air-application-installer-package+zip',
    'ait' => 'application/vnd.dvb.ait',
    'ami' => 'application/vnd.amiga.ami',
    'apk' => 'application/vnd.android.package-archive',
    'appcache' => 'text/cache-manifest',
    'apr' => 'application/vnd.lotus-approach',
    'aps' => 'application/postscript',
    'arc' => 'application/x-freearc',
    'asc' => 'application/pgp-signature',
    'asf' => 'video/x-ms-asf',
    'asm' => 'text/x-asm',
    'aso' => 'application/vnd.accpac.simply.aso',
    'asx' => 'video/x-ms-asf',
    'atc' => 'application/vnd.acucorp',
    'atom' => 'application/atom+xml',
    'atomcat' => 'application/atomcat+xml',
    'atomsvc' => 'application/atomsvc+xml',
    'atx' => 'application/vnd.antix.game-component',
    'au' => 'audio/basic',
    'avi' => 'video/x-msvideo',
    'aw' => 'application/applixware',
    'azf' => 'application/vnd.airzip.filesecure.azf',
    'azs' => 'application/vnd.airzip.filesecure.azs',
    'azw' => 'application/vnd.amazon.ebook',
    'bat' => 'application/x-msdownload',
    'bcpio' => 'application/x-bcpio',
    'bdf' => 'application/x-font-bdf',
    'bdm' => 'application/vnd.syncml.dm+wbxml',
    'bed' => 'application/vnd.realvnc.bed',
    'bh2' => 'application/vnd.fujitsu.oasysprs',
    'bin' => 'application/octet-stream',
    'blb' => 'application/x-blorb',
    'blorb' => 'application/x-blorb',
    'bmi' => 'application/vnd.bmi',
    'bmp' => 'image/bmp',
    'book' => 'application/vnd.framemaker',
    'box' => 'application/vnd.previewsystems.box',
    'boz' => 'application/x-bzip2',
    'bpk' => 'application/octet-stream',
    'btif' => 'image/prs.btif',
    'bz' => 'application/x-bzip',
    'bz2' => 'application/x-bzip2',
    'c' => 'text/x-c',
    'c11amc' => 'application/vnd.cluetrust.cartomobile-config',
    'c11amz' => 'application/vnd.cluetrust.cartomobile-config-pkg',
    'c4d' => 'application/vnd.clonk.c4group',
    'c4f' => 'application/vnd.clonk.c4group',
    'c4g' => 'application/vnd.clonk.c4group',
    'c4p' => 'application/vnd.clonk.c4group',
    'c4u' => 'application/vnd.clonk.c4group',
    'cab' => 'application/vnd.ms-cab-compressed',
    'caf' => 'audio/x-caf',
    'cap' => 'application/vnd.tcpdump.pcap',
    'car' => 'application/vnd.curl.car',
    'cat' => 'application/vnd.ms-pki.seccat',
    'cb7' => 'application/x-cbr',
    'cba' => 'application/x-cbr',
    'cbr' => 'application/x-cbr',
    'cbt' => 'application/x-cbr',
    'cbz' => 'application/x-cbr',
    'cc' => 'text/x-c',
    'cct' => 'application/x-director',
    'ccxml' => 'application/ccxml+xml',
    'cdbcmsg' => 'application/vnd.contact.cmsg',
    'cdf' => 'application/x-netcdf',
    'cdkey' => 'application/vnd.mediastation.cdkey',
    'cdmia' => 'application/cdmi-capability',
    'cdmic' => 'application/cdmi-container',
    'cdmid' => 'application/cdmi-domain',
    'cdmio' => 'application/cdmi-object',
    'cdmiq' => 'application/cdmi-queue',
    'cdx' => 'chemical/x-cdx',
    'cdxml' => 'application/vnd.chemdraw+xml',
    'cdy' => 'application/vnd.cinderella',
    'cer' => 'application/pkix-cert',
    'cfs' => 'application/x-cfs-compressed',
    'cgm' => 'image/cgm',
    'chat' => 'application/x-chat',
    'chm' => 'application/vnd.ms-htmlhelp',
    'chrt' => 'application/vnd.kde.kchart',
    'cif' => 'chemical/x-cif',
    'cii' => 'application/vnd.anser-web-certificate-issue-initiation',
    'cil' => 'application/vnd.ms-artgalry',
    'cla' => 'application/vnd.claymore',
    'class' => 'application/java-vm',
    'clkk' => 'application/vnd.crick.clicker.keyboard',
    'clkp' => 'application/vnd.crick.clicker.palette',
    'clkt' => 'application/vnd.crick.clicker.template',
    'clkw' => 'application/vnd.crick.clicker.wordbank',
    'clkx' => 'application/vnd.crick.clicker',
    'clp' => 'application/x-msclip',
    'cmc' => 'application/vnd.cosmocaller',
    'cmdf' => 'chemical/x-cmdf',
    'cml' => 'chemical/x-cml',
    'cmp' => 'application/vnd.yellowriver-custom-menu',
    'cmx' => 'image/x-cmx',
    'cod' => 'application/vnd.rim.cod',
    'com' => 'application/x-msdownload',
    'conf' => 'text/plain',
    'cpio' => 'application/x-cpio',
    'cpp' => 'text/x-c',
    'cpt' => 'application/mac-compactpro',
    'crd' => 'application/x-mscardfile',
    'crl' => 'application/pkix-crl',
    'crt' => 'application/x-x509-ca-cert',
    'csh' => 'application/x-csh',
    'csml' => 'chemical/x-csml',
    'csp' => 'application/vnd.commonspace',
    'css' => 'text/css',
    'cst' => 'application/x-director',
    'csv' => 'text/csv',
    'cu' => 'application/cu-seeme',
    'curl' => 'text/vnd.curl',
    'cww' => 'application/prs.cww',
    'cxt' => 'application/x-director',
    'cxx' => 'text/x-c',
    'dae' => 'model/vnd.collada+xml',
    'daf' => 'application/vnd.mobius.daf',
    'dart' => 'application/vnd.dart',
    'dataless' => 'application/vnd.fdsn.seed',
    'davmount' => 'application/davmount+xml',
    'dbk' => 'application/docbook+xml',
    'dcr' => 'application/x-director',
    'dcurl' => 'text/vnd.curl.dcurl',
    'dd2' => 'application/vnd.oma.dd2+xml',
    'ddd' => 'application/vnd.fujixerox.ddd',
    'deb' => 'application/x-debian-package',
    'def' => 'text/plain',
    'deploy' => 'application/octet-stream',
    'der' => 'application/x-x509-ca-cert',
    'dfac' => 'application/vnd.dreamfactory',
    'dgc' => 'application/x-dgc-compressed',
    'dic' => 'text/x-c',
    'dir' => 'application/x-director',
    'dis' => 'application/vnd.mobius.dis',
    'dist' => 'application/octet-stream',
    'distz' => 'application/octet-stream',
    'djv' => 'image/vnd.djvu',
    'djvu' => 'image/vnd.djvu',
    'dll' => 'application/x-msdownload',
    'dmg' => 'application/x-apple-diskimage',
    'dmp' => 'application/vnd.tcpdump.pcap',
    'dms' => 'application/octet-stream',
    'dna' => 'application/vnd.dna',
    'doc' => 'application/msword',
    'docm' => 'application/vnd.ms-word.document.macroenabled.12',
    'docx' => 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
    'dot' => 'application/msword',
    'dotm' => 'application/vnd.ms-word.template.macroenabled.12',
    'dotx' => 'application/vnd.openxmlformats-officedocument.wordprocessingml.template',
    'dp' => 'application/vnd.osgi.dp',
    'dpg' => 'application/vnd.dpgraph',
    'dra' => 'audio/vnd.dra',
    'dsc' => 'text/prs.lines.tag',
    'dssc' => 'application/dssc+der',
    'dtb' => 'application/x-dtbook+xml',
    'dtd' => 'application/xml-dtd',
    'dts' => 'audio/vnd.dts',
    'dtshd' => 'audio/vnd.dts.hd',
    'dump' => 'application/octet-stream',
    'dvb' => 'video/vnd.dvb.file',
    'dvi' => 'application/x-dvi',
    'dwf' => 'model/vnd.dwf',
    'dwg' => 'image/vnd.dwg',
    'dxf' => 'image/vnd.dxf',
    'dxp' => 'application/vnd.spotfire.dxp',
    'dxr' => 'application/x-director',
    'ecelp4800' => 'audio/vnd.nuera.ecelp4800',
    'ecelp7470' => 'audio/vnd.nuera.ecelp7470',
    'ecelp9600' => 'audio/vnd.nuera.ecelp9600',
    'ecma' => 'application/ecmascript',
    'edm' => 'application/vnd.novadigm.edm',
    'edx' => 'application/vnd.novadigm.edx',
    'efif' => 'application/vnd.picsel',
    'ei6' => 'application/vnd.pg.osasli',
    'elc' => 'application/octet-stream',
    'emf' => 'application/x-msmetafile',
    'eml' => 'message/rfc822',
    'emma' => 'application/emma+xml',
    'emz' => 'application/x-msmetafile',
    'eol' => 'audio/vnd.digital-winds',
    'eot' => 'application/vnd.ms-fontobject',
    'eps' => 'application/postscript',
    'epub' => 'application/epub+zip',
    'es3' => 'application/vnd.eszigno3+xml',
    'esa' => 'application/vnd.osgi.subsystem',
    'esf' => 'application/vnd.epson.esf',
    'et3' => 'application/vnd.eszigno3+xml',
    'etx' => 'text/x-setext',
    'eva' => 'application/x-eva',
    'evy' => 'application/x-envoy',
    'exe' => 'application/x-msdownload',
    'exi' => 'application/exi',
    'ext' => 'application/vnd.novadigm.ext',
    'ez' => 'application/andrew-inset',
    'ez2' => 'application/vnd.ezpix-album',
    'ez3' => 'application/vnd.ezpix-package',
    'f' => 'text/x-fortran',
    'f4v' => 'video/x-f4v',
    'f77' => 'text/x-fortran',
    'f90' => 'text/x-fortran',
    'fbs' => 'image/vnd.fastbidsheet',
    'fcdt' => 'application/vnd.adobe.formscentral.fcdt',
    'fcs' => 'application/vnd.isac.fcs',
    'fdf' => 'application/vnd.fdf',
    'fe_launch' => 'application/vnd.denovo.fcselayout-link',
    'fg5' => 'application/vnd.fujitsu.oasysgp',
    'fgd' => 'application/x-director',
    'fh' => 'image/x-freehand',
    'fh4' => 'image/x-freehand',
    'fh5' => 'image/x-freehand',
    'fh7' => 'image/x-freehand',
    'fhc' => 'image/x-freehand',
    'fig' => 'application/x-xfig',
    'flac' => 'audio/x-flac',
    'fli' => 'video/x-fli',
    'flo' => 'application/vnd.micrografx.flo',
    'flv' => 'video/x-flv',
    'flw' => 'application/vnd.kde.kivio',
    'flx' => 'text/vnd.fmi.flexstor',
    'fly' => 'text/vnd.fly',
    'fm' => 'application/vnd.framemaker',
    'fnc' => 'application/vnd.frogans.fnc',
    'for' => 'text/x-fortran',
    'fpx' => 'image/vnd.fpx',
    'frame' => 'application/vnd.framemaker',
    'fsc' => 'application/vnd.fsc.weblaunch',
    'fst' => 'image/vnd.fst',
    'ftc' => 'application/vnd.fluxtime.clip',
    'fti' => 'application/vnd.anser-web-funds-transfer-initiation',
    'fvt' => 'video/vnd.fvt',
    'fxp' => 'application/vnd.adobe.fxp',
    'fxpl' => 'application/vnd.adobe.fxp',
    'fzs' => 'application/vnd.fuzzysheet',
    'g2w' => 'application/vnd.geoplan',
    'g3' => 'image/g3fax',
    'g3w' => 'application/vnd.geospace',
    'gac' => 'application/vnd.groove-account',
    'gam' => 'application/x-tads',
    'gbr' => 'application/rpki-ghostbusters',
    'gca' => 'application/x-gca-compressed',
    'gdl' => 'model/vnd.gdl',
    'geo' => 'application/vnd.dynageo',
    'gex' => 'application/vnd.geometry-explorer',
    'ggb' => 'application/vnd.geogebra.file',
    'ggt' => 'application/vnd.geogebra.tool',
    'ghf' => 'application/vnd.groove-help',
    'gif' => 'image/gif',
    'gim' => 'application/vnd.groove-identity-message',
    'gml' => 'application/gml+xml',
    'gmx' => 'application/vnd.gmx',
    'gnumeric' => 'application/x-gnumeric',
    'gph' => 'application/vnd.flographit',
    'gpx' => 'application/gpx+xml',
    'gqf' => 'application/vnd.grafeq',
    'gqs' => 'application/vnd.grafeq',
    'gram' => 'application/srgs',
    'gramps' => 'application/x-gramps-xml',
    'gre' => 'application/vnd.geometry-explorer',
    'grv' => 'application/vnd.groove-injector',
    'grxml' => 'application/srgs+xml',
    'gsf' => 'application/x-font-ghostscript',
    'gtar' => 'application/x-gtar',
    'gtm' => 'application/vnd.groove-tool-message',
    'gtw' => 'model/vnd.gtw',
    'gv' => 'text/vnd.graphviz',
    'gxf' => 'application/gxf',
    'gxt' => 'application/vnd.geonext',
    'gz' => 'application/x-gzip',
    'h' => 'text/x-c',
    'h261' => 'video/h261',
    'h263' => 'video/h263',
    'h264' => 'video/h264',
    'hal' => 'application/vnd.hal+xml',
    'hbci' => 'application/vnd.hbci',
    'hdf' => 'application/x-hdf',
    'hh' => 'text/x-c',
    'hlp' => 'application/winhlp',
    'hpgl' => 'application/vnd.hp-hpgl',
    'hpid' => 'application/vnd.hp-hpid',
    'hps' => 'application/vnd.hp-hps',
    'hqx' => 'application/mac-binhex40',
    'htke' => 'application/vnd.kenameaapp',
    'htm' => 'text/html',
    'html' => 'text/html',
    'hvd' => 'application/vnd.yamaha.hv-dic',
    'hvp' => 'application/vnd.yamaha.hv-voice',
    'hvs' => 'application/vnd.yamaha.hv-script',
    'i2g' => 'application/vnd.intergeo',
    'icc' => 'application/vnd.iccprofile',
    'ice' => 'x-conference/x-cooltalk',
    'icm' => 'application/vnd.iccprofile',
    'ico' => 'image/x-icon',
    'ics' => 'text/calendar',
    'ief' => 'image/ief',
    'ifb' => 'text/calendar',
    'ifm' => 'application/vnd.shana.informed.formdata',
    'iges' => 'model/iges',
    'igl' => 'application/vnd.igloader',
    'igm' => 'application/vnd.insors.igm',
    'igs' => 'model/iges',
    'igx' => 'application/vnd.micrografx.igx',
    'iif' => 'application/vnd.shana.informed.interchange',
    'imp' => 'application/vnd.accpac.simply.imp',
    'ims' => 'application/vnd.ms-ims',
    'in' => 'text/plain',
    'ink' => 'application/inkml+xml',
    'inkml' => 'application/inkml+xml',
    'install' => 'application/x-install-instructions',
    'iota' => 'application/vnd.astraea-software.iota',
    'ipfix' => 'application/ipfix',
    'ipk' => 'application/vnd.shana.informed.package',
    'irm' => 'application/vnd.ibm.rights-management',
    'irp' => 'application/vnd.irepository.package+xml',
    'iso' => 'application/x-iso9660-image',
    'itp' => 'application/vnd.shana.informed.formtemplate',
    'ivp' => 'application/vnd.immervision-ivp',
    'ivu' => 'application/vnd.immervision-ivu',
    'jad' => 'text/vnd.sun.j2me.app-descriptor',
    'jam' => 'application/vnd.jam',
    'jar' => 'application/java-archive',
    'java' => 'text/x-java-source',
    'jisp' => 'application/vnd.jisp',
    'jlt' => 'application/vnd.hp-jlyt',
    'jnlp' => 'application/x-java-jnlp-file',
    'joda' => 'application/vnd.joost.joda-archive',
    'jpe' => 'image/jpeg',
    'jpeg' => 'image/jpeg',
    'jpg' => 'image/jpeg',
    'jpgm' => 'video/jpm',
    'jpgv' => 'video/jpeg',
    'jpm' => 'video/jpm',
    'js' => 'application/javascript',
    'json' => 'application/json',
    'jsonml' => 'application/jsonml+json',
    'kar' => 'audio/midi',
    'karbon' => 'application/vnd.kde.karbon',
    'kfo' => 'application/vnd.kde.kformula',
    'kia' => 'application/vnd.kidspiration',
    'kml' => 'application/vnd.google-earth.kml+xml',
    'kmz' => 'application/vnd.google-earth.kmz',
    'kne' => 'application/vnd.kinar',
    'knp' => 'application/vnd.kinar',
    'kon' => 'application/vnd.kde.kontour',
    'kpr' => 'application/vnd.kde.kpresenter',
    'kpt' => 'application/vnd.kde.kpresenter',
    'kpxx' => 'application/vnd.ds-keypoint',
    'ksp' => 'application/vnd.kde.kspread',
    'ktr' => 'application/vnd.kahootz',
    'ktx' => 'image/ktx',
    'ktz' => 'application/vnd.kahootz',
    'kwd' => 'application/vnd.kde.kword',
    'kwt' => 'application/vnd.kde.kword',
    'lasxml' => 'application/vnd.las.las+xml',
    'latex' => 'application/x-latex',
    'lbd' => 'application/vnd.llamagraphics.life-balance.desktop',
    'lbe' => 'application/vnd.llamagraphics.life-balance.exchange+xml',
    'les' => 'application/vnd.hhe.lesson-player',
    'lha' => 'application/x-lzh-compressed',
    'link66' => 'application/vnd.route66.link66+xml',
    'list' => 'text/plain',
    'list3820' => 'application/vnd.ibm.modcap',
    'listafp' => 'application/vnd.ibm.modcap',
    'lnk' => 'application/x-ms-shortcut',
    'log' => 'text/plain',
    'lostxml' => 'application/lost+xml',
    'lrf' => 'application/octet-stream',
    'lrm' => 'application/vnd.ms-lrm',
    'ltf' => 'application/vnd.frogans.ltf',
    'lvp' => 'audio/vnd.lucent.voice',
    'lwp' => 'application/vnd.lotus-wordpro',
    'lzh' => 'application/x-lzh-compressed',
    'm13' => 'application/x-msmediaview',
    'm14' => 'application/x-msmediaview',
    'm1v' => 'video/mpeg',
    'm21' => 'application/mp21',
    'm2a' => 'audio/mpeg',
    'm2v' => 'video/mpeg',
    'm3a' => 'audio/mpeg',
    'm3u' => 'audio/x-mpegurl',
    'm3u8' => 'application/vnd.apple.mpegurl',
    'm4a' => 'audio/mp4',
    'm4u' => 'video/vnd.mpegurl',
    'm4v' => 'video/x-m4v',
    'ma' => 'application/mathematica',
    'mads' => 'application/mads+xml',
    'mag' => 'application/vnd.ecowin.chart',
    'maker' => 'application/vnd.framemaker',
    'man' => 'text/troff',
    'mar' => 'application/octet-stream',
    'mathml' => 'application/mathml+xml',
    'mb' => 'application/mathematica',
    'mbk' => 'application/vnd.mobius.mbk',
    'mbox' => 'application/mbox',
    'mc1' => 'application/vnd.medcalcdata',
    'mcd' => 'application/vnd.mcd',
    'mcurl' => 'text/vnd.curl.mcurl',
    'mdb' => 'application/x-msaccess',
    'mdi' => 'image/vnd.ms-modi',
    'me' => 'text/troff',
    'mesh' => 'model/mesh',
    'meta4' => 'application/metalink4+xml',
    'metalink' => 'application/metalink+xml',
    'mets' => 'application/mets+xml',
    'mfm' => 'application/vnd.mfmp',
    'mft' => 'application/rpki-manifest',
    'mgp' => 'application/vnd.osgeo.mapguide.package',
    'mgz' => 'application/vnd.proteus.magazine',
    'mid' => 'audio/midi',
    'midi' => 'audio/midi',
    'mie' => 'application/x-mie',
    'mif' => 'application/vnd.mif',
    'mime' => 'message/rfc822',
    'mj2' => 'video/mj2',
    'mjp2' => 'video/mj2',
    'mk3d' => 'video/x-matroska',
    'mka' => 'audio/x-matroska',
    'mks' => 'video/x-matroska',
    'mkv' => 'video/x-matroska',
    'mlp' => 'application/vnd.dolby.mlp',
    'mmd' => 'application/vnd.chipnuts.karaoke-mmd',
    'mmf' => 'application/vnd.smaf',
    'mmr' => 'image/vnd.fujixerox.edmics-mmr',
    'mng' => 'video/x-mng',
    'mny' => 'application/x-msmoney',
    'mobi' => 'application/x-mobipocket-ebook',
    'mods' => 'application/mods+xml',
    'mov' => 'video/quicktime',
    'movie' => 'video/x-sgi-movie',
    'mp2' => 'audio/mpeg',
    'mp21' => 'application/mp21',
    'mp2a' => 'audio/mpeg',
    'mp3' => 'audio/mpeg',
    'mp4' => 'video/mp4',
    'mp4a' => 'audio/mp4',
    'mp4s' => 'application/mp4',
    'mp4v' => 'video/mp4',
    'mpc' => 'application/vnd.mophun.certificate',
    'mpe' => 'video/mpeg',
    'mpeg' => 'video/mpeg',
    'mpg' => 'video/mpeg',
    'mpg4' => 'video/mp4',
    'mpga' => 'audio/mpeg',
    'mpkg' => 'application/vnd.apple.installer+xml',
    'mpm' => 'application/vnd.blueice.multipass',
    'mpn' => 'application/vnd.mophun.application',
    'mpp' => 'application/vnd.ms-project',
    'mpt' => 'application/vnd.ms-project',
    'mpy' => 'application/vnd.ibm.minipay',
    'mqy' => 'application/vnd.mobius.mqy',
    'mrc' => 'application/marc',
    'mrcx' => 'application/marcxml+xml',
    'ms' => 'text/troff',
    'mscml' => 'application/mediaservercontrol+xml',
    'mseed' => 'application/vnd.fdsn.mseed',
    'mseq' => 'application/vnd.mseq',
    'msf' => 'application/vnd.epson.msf',
    'msh' => 'model/mesh',
    'msi' => 'application/x-msdownload',
    'msl' => 'application/vnd.mobius.msl',
    'msty' => 'application/vnd.muvee.style',
    'mts' => 'model/vnd.mts',
    'mus' => 'application/vnd.musician',
    'musicxml' => 'application/vnd.recordare.musicxml+xml',
    'mvb' => 'application/x-msmediaview',
    'mwf' => 'application/vnd.mfer',
    'mxf' => 'application/mxf',
    'mxl' => 'application/vnd.recordare.musicxml',
    'mxml' => 'application/xv+xml',
    'mxs' => 'application/vnd.triscape.mxs',
    'mxu' => 'video/vnd.mpegurl',
    'n-gage' => 'application/vnd.nokia.n-gage.symbian.install',
    'n3' => 'text/n3',
    'nb' => 'application/mathematica',
    'nbp' => 'application/vnd.wolfram.player',
    'nc' => 'application/x-netcdf',
    'ncx' => 'application/x-dtbncx+xml',
    'nfo' => 'text/x-nfo',
    'ngdat' => 'application/vnd.nokia.n-gage.data',
    'nitf' => 'application/vnd.nitf',
    'nlu' => 'application/vnd.neurolanguage.nlu',
    'nml' => 'application/vnd.enliven',
    'nnd' => 'application/vnd.noblenet-directory',
    'nns' => 'application/vnd.noblenet-sealer',
    'nnw' => 'application/vnd.noblenet-web',
    'npx' => 'image/vnd.net-fpx',
    'nsc' => 'application/x-conference',
    'nsf' => 'application/vnd.lotus-notes',
    'ntf' => 'application/vnd.nitf',
    'nzb' => 'application/x-nzb',
    'oa2' => 'application/vnd.fujitsu.oasys2',
    'oa3' => 'application/vnd.fujitsu.oasys3',
    'oas' => 'application/vnd.fujitsu.oasys',
    'obd' => 'application/x-msbinder',
    'obj' => 'application/x-tgif',
    'oda' => 'application/oda',
    'odb' => 'application/vnd.oasis.opendocument.database',
    'odc' => 'application/vnd.oasis.opendocument.chart',
    'odf' => 'application/vnd.oasis.opendocument.formula',
    'odft' => 'application/vnd.oasis.opendocument.formula-template',
    'odg' => 'application/vnd.oasis.opendocument.graphics',
    'odi' => 'application/vnd.oasis.opendocument.image',
    'odm' => 'application/vnd.oasis.opendocument.text-master',
    'odp' => 'application/vnd.oasis.opendocument.presentation',
    'ods' => 'application/vnd.oasis.opendocument.spreadsheet',
    'odt' => 'application/vnd.oasis.opendocument.text',
    'oga' => 'audio/ogg',
    'ogg' => 'audio/ogg',
    'ogv' => 'video/ogg',
    'ogx' => 'application/ogg',
    'omdoc' => 'application/omdoc+xml',
    'onepkg' => 'application/onenote',
    'onetmp' => 'application/onenote',
    'onetoc' => 'application/onenote',
    'onetoc2' => 'application/onenote',
    'opf' => 'application/oebps-package+xml',
    'opml' => 'text/x-opml',
    'oprc' => 'application/vnd.palm',
    'org' => 'application/vnd.lotus-organizer',
    'osf' => 'application/vnd.yamaha.openscoreformat',
    'osfpvg' => 'application/vnd.yamaha.openscoreformat.osfpvg+xml',
    'otc' => 'application/vnd.oasis.opendocument.chart-template',
    'otf' => 'application/x-font-otf',
    'otg' => 'application/vnd.oasis.opendocument.graphics-template',
    'oth' => 'application/vnd.oasis.opendocument.text-web',
    'oti' => 'application/vnd.oasis.opendocument.image-template',
    'otp' => 'application/vnd.oasis.opendocument.presentation-template',
    'ots' => 'application/vnd.oasis.opendocument.spreadsheet-template',
    'ott' => 'application/vnd.oasis.opendocument.text-template',
    'oxps' => 'application/oxps',
    'oxt' => 'application/vnd.openofficeorg.extension',
    'p' => 'text/x-pascal',
    'p10' => 'application/pkcs10',
    'p12' => 'application/x-pkcs12',
    'p7b' => 'application/x-pkcs7-certificates',
    'p7c' => 'application/pkcs7-mime',
    'p7m' => 'application/pkcs7-mime',
    'p7r' => 'application/x-pkcs7-certreqresp',
    'p7s' => 'application/pkcs7-signature',
    'p8' => 'application/pkcs8',
    'pas' => 'text/x-pascal',
    'paw' => 'application/vnd.pawaafile',
    'pbd' => 'application/vnd.powerbuilder6',
    'pbm' => 'image/x-portable-bitmap',
    'pcap' => 'application/vnd.tcpdump.pcap',
    'pcf' => 'application/x-font-pcf',
    'pcl' => 'application/vnd.hp-pcl',
    'pclxl' => 'application/vnd.hp-pclxl',
    'pct' => 'image/x-pict',
    'pcurl' => 'application/vnd.curl.pcurl',
    'pcx' => 'image/x-pcx',
    'pdb' => 'application/vnd.palm',
    'pdf' => 'application/pdf',
    'pfa' => 'application/x-font-type1',
    'pfb' => 'application/x-font-type1',
    'pfm' => 'application/x-font-type1',
    'pfr' => 'application/font-tdpfr',
    'pfx' => 'application/x-pkcs12',
    'pgm' => 'image/x-portable-graymap',
    'pgn' => 'application/x-chess-pgn',
    'pgp' => 'application/pgp-encrypted',
    'php' => 'application/x-php',
    'php3' => 'application/x-php',
    'php4' => 'application/x-php',
    'php5' => 'application/x-php',
    'pic' => 'image/x-pict',
    'pkg' => 'application/octet-stream',
    'pki' => 'application/pkixcmp',
    'pkipath' => 'application/pkix-pkipath',
    'plb' => 'application/vnd.3gpp.pic-bw-large',
    'plc' => 'application/vnd.mobius.plc',
    'plf' => 'application/vnd.pocketlearn',
    'pls' => 'application/pls+xml',
    'pml' => 'application/vnd.ctc-posml',
    'png' => 'image/png',
    'pnm' => 'image/x-portable-anymap',
    'portpkg' => 'application/vnd.macports.portpkg',
    'pot' => 'application/vnd.ms-powerpoint',
    'potm' => 'application/vnd.ms-powerpoint.template.macroenabled.12',
    'potx' => 'application/vnd.openxmlformats-officedocument.presentationml.template',
    'ppam' => 'application/vnd.ms-powerpoint.addin.macroenabled.12',
    'ppd' => 'application/vnd.cups-ppd',
    'ppm' => 'image/x-portable-pixmap',
    'pps' => 'application/vnd.ms-powerpoint',
    'ppsm' => 'application/vnd.ms-powerpoint.slideshow.macroenabled.12',
    'ppsx' => 'application/vnd.openxmlformats-officedocument.presentationml.slideshow',
    'ppt' => 'application/vnd.ms-powerpoint',
    'pptm' => 'application/vnd.ms-powerpoint.presentation.macroenabled.12',
    'pptx' => 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
    'pqa' => 'application/vnd.palm',
    'prc' => 'application/x-mobipocket-ebook',
    'pre' => 'application/vnd.lotus-freelance',
    'prf' => 'application/pics-rules',
    'ps' => 'application/postscript',
    'psb' => 'application/vnd.3gpp.pic-bw-small',
    'psd' => 'image/vnd.adobe.photoshop',
    'psf' => 'application/x-font-linux-psf',
    'pskcxml' => 'application/pskc+xml',
    'ptid' => 'application/vnd.pvi.ptid1',
    'pub' => 'application/x-mspublisher',
    'pvb' => 'application/vnd.3gpp.pic-bw-var',
    'pwn' => 'application/vnd.3m.post-it-notes',
    'pya' => 'audio/vnd.ms-playready.media.pya',
    'pyv' => 'video/vnd.ms-playready.media.pyv',
    'qam' => 'application/vnd.epson.quickanime',
    'qbo' => 'application/vnd.intu.qbo',
    'qfx' => 'application/vnd.intu.qfx',
    'qps' => 'application/vnd.publishare-delta-tree',
    'qt' => 'video/quicktime',
    'qwd' => 'application/vnd.quark.quarkxpress',
    'qwt' => 'application/vnd.quark.quarkxpress',
    'qxb' => 'application/vnd.quark.quarkxpress',
    'qxd' => 'application/vnd.quark.quarkxpress',
    'qxl' => 'application/vnd.quark.quarkxpress',
    'qxt' => 'application/vnd.quark.quarkxpress',
    'ra' => 'audio/x-pn-realaudio',
    'ram' => 'audio/x-pn-realaudio',
    'rar' => 'application/x-rar-compressed',
    'ras' => 'image/x-cmu-raster',
    'rcprofile' => 'application/vnd.ipunplugged.rcprofile',
    'rdf' => 'application/rdf+xml',
    'rdz' => 'application/vnd.data-vision.rdz',
    'rep' => 'application/vnd.businessobjects',
    'res' => 'application/x-dtbresource+xml',
    'rgb' => 'image/x-rgb',
    'rif' => 'application/reginfo+xml',
    'rip' => 'audio/vnd.rip',
    'ris' => 'application/x-research-info-systems',
    'rl' => 'application/resource-lists+xml',
    'rlc' => 'image/vnd.fujixerox.edmics-rlc',
    'rld' => 'application/resource-lists-diff+xml',
    'rm' => 'application/vnd.rn-realmedia',
    'rmi' => 'audio/midi',
    'rmp' => 'audio/x-pn-realaudio-plugin',
    'rms' => 'application/vnd.jcp.javame.midlet-rms',
    'rmvb' => 'application/vnd.rn-realmedia-vbr',
    'rnc' => 'application/relax-ng-compact-syntax',
    'roa' => 'application/rpki-roa',
    'roff' => 'text/troff',
    'rp9' => 'application/vnd.cloanto.rp9',
    'rpss' => 'application/vnd.nokia.radio-presets',
    'rpst' => 'application/vnd.nokia.radio-preset',
    'rq' => 'application/sparql-query',
    'rs' => 'application/rls-services+xml',
    'rsd' => 'application/rsd+xml',
    'rss' => 'application/rss+xml',
    'rtf' => 'application/rtf',
    'rtx' => 'text/richtext',
    's' => 'text/x-asm',
    's3m' => 'audio/s3m',
    'saf' => 'application/vnd.yamaha.smaf-audio',
    'sbml' => 'application/sbml+xml',
    'sc' => 'application/vnd.ibm.secure-container',
    'scd' => 'application/x-msschedule',
    'scm' => 'application/vnd.lotus-screencam',
    'scq' => 'application/scvp-cv-request',
    'scs' => 'application/scvp-cv-response',
    'scurl' => 'text/vnd.curl.scurl',
    'sda' => 'application/vnd.stardivision.draw',
    'sdc' => 'application/vnd.stardivision.calc',
    'sdd' => 'application/vnd.stardivision.impress',
    'sdkd' => 'application/vnd.solent.sdkm+xml',
    'sdkm' => 'application/vnd.solent.sdkm+xml',
    'sdp' => 'application/sdp',
    'sdw' => 'application/vnd.stardivision.writer',
    'see' => 'application/vnd.seemail',
    'seed' => 'application/vnd.fdsn.seed',
    'sema' => 'application/vnd.sema',
    'semd' => 'application/vnd.semd',
    'semf' => 'application/vnd.semf',
    'ser' => 'application/java-serialized-object',
    'setpay' => 'application/set-payment-initiation',
    'setreg' => 'application/set-registration-initiation',
    'sfd-hdstx' => 'application/vnd.hydrostatix.sof-data',
    'sfs' => 'application/vnd.spotfire.sfs',
    'sfv' => 'text/x-sfv',
    'sgi' => 'image/sgi',
    'sgl' => 'application/vnd.stardivision.writer-global',
    'sgm' => 'text/sgml',
    'sgml' => 'text/sgml',
    'sh' => 'application/x-sh',
    'shar' => 'application/x-shar',
    'shf' => 'application/shf+xml',
    'sid' => 'image/x-mrsid-image',
    'sig' => 'application/pgp-signature',
    'sil' => 'audio/silk',
    'silo' => 'model/mesh',
    'sis' => 'application/vnd.symbian.install',
    'sisx' => 'application/vnd.symbian.install',
    'sit' => 'application/x-stuffit',
    'sitx' => 'application/x-stuffitx',
    'skd' => 'application/vnd.koan',
    'skm' => 'application/vnd.koan',
    'skp' => 'application/vnd.koan',
    'skt' => 'application/vnd.koan',
    'sldm' => 'application/vnd.ms-powerpoint.slide.macroenabled.12',
    'sldx' => 'application/vnd.openxmlformats-officedocument.presentationml.slide',
    'slt' => 'application/vnd.epson.salt',
    'sm' => 'application/vnd.stepmania.stepchart',
    'smf' => 'application/vnd.stardivision.math',
    'smi' => 'application/smil+xml',
    'smil' => 'application/smil+xml',
    'smv' => 'video/x-smv',
    'smzip' => 'application/vnd.stepmania.package',
    'snd' => 'audio/basic',
    'snf' => 'application/x-font-snf',
    'so' => 'application/octet-stream',
    'spc' => 'application/x-pkcs7-certificates',
    'spf' => 'application/vnd.yamaha.smaf-phrase',
    'spl' => 'application/x-futuresplash',
    'spot' => 'text/vnd.in3d.spot',
    'spp' => 'application/scvp-vp-response',
    'spq' => 'application/scvp-vp-request',
    'spx' => 'audio/ogg',
    'sql' => 'application/x-sql',
    'src' => 'application/x-wais-source',
    'srt' => 'application/x-subrip',
    'sru' => 'application/sru+xml',
    'srx' => 'application/sparql-results+xml',
    'ssdl' => 'application/ssdl+xml',
    'sse' => 'application/vnd.kodak-descriptor',
    'ssf' => 'application/vnd.epson.ssf',
    'ssml' => 'application/ssml+xml',
    'st' => 'application/vnd.sailingtracker.track',
    'stc' => 'application/vnd.sun.xml.calc.template',
    'std' => 'application/vnd.sun.xml.draw.template',
    'stf' => 'application/vnd.wt.stf',
    'sti' => 'application/vnd.sun.xml.impress.template',
    'stk' => 'application/hyperstudio',
    'stl' => 'application/vnd.ms-pki.stl',
    'str' => 'application/vnd.pg.format',
    'stw' => 'application/vnd.sun.xml.writer.template',
    'sub' => 'text/vnd.dvb.subtitle',
    'sus' => 'application/vnd.sus-calendar',
    'susp' => 'application/vnd.sus-calendar',
    'sv4cpio' => 'application/x-sv4cpio',
    'sv4crc' => 'application/x-sv4crc',
    'svc' => 'application/vnd.dvb.service',
    'svd' => 'application/vnd.svd',
    'svg' => 'image/svg+xml',
    'svgz' => 'image/svg+xml',
    'swa' => 'application/x-director',
    'swf' => 'application/x-shockwave-flash',
    'swi' => 'application/vnd.aristanetworks.swi',
    'sxc' => 'application/vnd.sun.xml.calc',
    'sxd' => 'application/vnd.sun.xml.draw',
    'sxg' => 'application/vnd.sun.xml.writer.global',
    'sxi' => 'application/vnd.sun.xml.impress',
    'sxm' => 'application/vnd.sun.xml.math',
    'sxw' => 'application/vnd.sun.xml.writer',
    't' => 'text/troff',
    't3' => 'application/x-t3vm-image',
    'taglet' => 'application/vnd.mynfc',
    'tao' => 'application/vnd.tao.intent-module-archive',
    'tar' => 'application/x-tar',
    'tcap' => 'application/vnd.3gpp2.tcap',
    'tcl' => 'application/x-tcl',
    'teacher' => 'application/vnd.smart.teacher',
    'tei' => 'application/tei+xml',
    'teicorpus' => 'application/tei+xml',
    'tex' => 'application/x-tex',
    'texi' => 'application/x-texinfo',
    'texinfo' => 'application/x-texinfo',
    'text' => 'text/plain',
    'tfi' => 'application/thraud+xml',
    'tfm' => 'application/x-tex-tfm',
    'tga' => 'image/x-tga',
    'thmx' => 'application/vnd.ms-officetheme',
    'tif' => 'image/tiff',
    'tiff' => 'image/tiff',
    'tmo' => 'application/vnd.tmobile-livetv',
    'torrent' => 'application/x-bittorrent',
    'tpl' => 'application/vnd.groove-tool-template',
    'tpt' => 'application/vnd.trid.tpt',
    'tr' => 'text/troff',
    'tra' => 'application/vnd.trueapp',
    'trm' => 'application/x-msterminal',
    'tsd' => 'application/timestamped-data',
    'tsv' => 'text/tab-separated-values',
    'ttc' => 'application/x-font-ttf',
    'ttf' => 'application/x-font-ttf',
    'ttl' => 'text/turtle',
    'twd' => 'application/vnd.simtech-mindmapper',
    'twds' => 'application/vnd.simtech-mindmapper',
    'txd' => 'application/vnd.genomatix.tuxedo',
    'txf' => 'application/vnd.mobius.txf',
    'txt' => 'text/plain',
    'u32' => 'application/x-authorware-bin',
    'udeb' => 'application/x-debian-package',
    'ufd' => 'application/vnd.ufdl',
    'ufdl' => 'application/vnd.ufdl',
    'ulx' => 'application/x-glulx',
    'umj' => 'application/vnd.umajin',
    'unityweb' => 'application/vnd.unity',
    'uoml' => 'application/vnd.uoml+xml',
    'uri' => 'text/uri-list',
    'uris' => 'text/uri-list',
    'urls' => 'text/uri-list',
    'ustar' => 'application/x-ustar',
    'utz' => 'application/vnd.uiq.theme',
    'uu' => 'text/x-uuencode',
    'uva' => 'audio/vnd.dece.audio',
    'uvd' => 'application/vnd.dece.data',
    'uvf' => 'application/vnd.dece.data',
    'uvg' => 'image/vnd.dece.graphic',
    'uvh' => 'video/vnd.dece.hd',
    'uvi' => 'image/vnd.dece.graphic',
    'uvm' => 'video/vnd.dece.mobile',
    'uvp' => 'video/vnd.dece.pd',
    'uvs' => 'video/vnd.dece.sd',
    'uvt' => 'application/vnd.dece.ttml+xml',
    'uvu' => 'video/vnd.uvvu.mp4',
    'uvv' => 'video/vnd.dece.video',
    'uvva' => 'audio/vnd.dece.audio',
    'uvvd' => 'application/vnd.dece.data',
    'uvvf' => 'application/vnd.dece.data',
    'uvvg' => 'image/vnd.dece.graphic',
    'uvvh' => 'video/vnd.dece.hd',
    'uvvi' => 'image/vnd.dece.graphic',
    'uvvm' => 'video/vnd.dece.mobile',
    'uvvp' => 'video/vnd.dece.pd',
    'uvvs' => 'video/vnd.dece.sd',
    'uvvt' => 'application/vnd.dece.ttml+xml',
    'uvvu' => 'video/vnd.uvvu.mp4',
    'uvvv' => 'video/vnd.dece.video',
    'uvvx' => 'application/vnd.dece.unspecified',
    'uvvz' => 'application/vnd.dece.zip',
    'uvx' => 'application/vnd.dece.unspecified',
    'uvz' => 'application/vnd.dece.zip',
    'vcard' => 'text/vcard',
    'vcd' => 'application/x-cdlink',
    'vcf' => 'text/x-vcard',
    'vcg' => 'application/vnd.groove-vcard',
    'vcs' => 'text/x-vcalendar',
    'vcx' => 'application/vnd.vcx',
    'vis' => 'application/vnd.visionary',
    'viv' => 'video/vnd.vivo',
    'vob' => 'video/x-ms-vob',
    'vor' => 'application/vnd.stardivision.writer',
    'vox' => 'application/x-authorware-bin',
    'vrml' => 'model/vrml',
    'vsd' => 'application/vnd.visio',
    'vsf' => 'application/vnd.vsf',
    'vss' => 'application/vnd.visio',
    'vst' => 'application/vnd.visio',
    'vsw' => 'application/vnd.visio',
    'vtu' => 'model/vnd.vtu',
    'vxml' => 'application/voicexml+xml',
    'w3d' => 'application/x-director',
    'wad' => 'application/x-doom',
    'wav' => 'audio/x-wav',
    'wax' => 'audio/x-ms-wax',
    'wbmp' => 'image/vnd.wap.wbmp',
    'wbs' => 'application/vnd.criticaltools.wbs+xml',
    'wbxml' => 'application/vnd.wap.wbxml',
    'wcm' => 'application/vnd.ms-works',
    'wdb' => 'application/vnd.ms-works',
    'wdp' => 'image/vnd.ms-photo',
    'weba' => 'audio/webm',
    'webm' => 'video/webm',
    'webp' => 'image/webp',
    'wg' => 'application/vnd.pmi.widget',
    'wgt' => 'application/widget',
    'wks' => 'application/vnd.ms-works',
    'wm' => 'video/x-ms-wm',
    'wma' => 'audio/x-ms-wma',
    'wmd' => 'application/x-ms-wmd',
    'wmf' => 'application/x-msmetafile',
    'wml' => 'text/vnd.wap.wml',
    'wmlc' => 'application/vnd.wap.wmlc',
    'wmls' => 'text/vnd.wap.wmlscript',
    'wmlsc' => 'application/vnd.wap.wmlscriptc',
    'wmv' => 'video/x-ms-wmv',
    'wmx' => 'video/x-ms-wmx',
    'wmz' => 'application/x-msmetafile',
    'woff' => 'application/font-woff',
    'wpd' => 'application/vnd.wordperfect',
    'wpl' => 'application/vnd.ms-wpl',
    'wps' => 'application/vnd.ms-works',
    'wqd' => 'application/vnd.wqd',
    'wri' => 'application/x-mswrite',
    'wrl' => 'model/vrml',
    'wsdl' => 'application/wsdl+xml',
    'wspolicy' => 'application/wspolicy+xml',
    'wtb' => 'application/vnd.webturbo',
    'wvx' => 'video/x-ms-wvx',
    'x32' => 'application/x-authorware-bin',
    'x3d' => 'model/x3d+xml',
    'x3db' => 'model/x3d+binary',
    'x3dbz' => 'model/x3d+binary',
    'x3dv' => 'model/x3d+vrml',
    'x3dvz' => 'model/x3d+vrml',
    'x3dz' => 'model/x3d+xml',
    'xaml' => 'application/xaml+xml',
    'xap' => 'application/x-silverlight-app',
    'xar' => 'application/vnd.xara',
    'xbap' => 'application/x-ms-xbap',
    'xbd' => 'application/vnd.fujixerox.docuworks.binder',
    'xbm' => 'image/x-xbitmap',
    'xdf' => 'application/xcap-diff+xml',
    'xdm' => 'application/vnd.syncml.dm+xml',
    'xdp' => 'application/vnd.adobe.xdp+xml',
    'xdssc' => 'application/dssc+xml',
    'xdw' => 'application/vnd.fujixerox.docuworks',
    'xenc' => 'application/xenc+xml',
    'xer' => 'application/patch-ops-error+xml',
    'xfdf' => 'application/vnd.adobe.xfdf',
    'xfdl' => 'application/vnd.xfdl',
    'xht' => 'application/xhtml+xml',
    'xhtml' => 'application/xhtml+xml',
    'xhvml' => 'application/xv+xml',
    'xif' => 'image/vnd.xiff',
    'xla' => 'application/vnd.ms-excel',
    'xlam' => 'application/vnd.ms-excel.addin.macroenabled.12',
    'xlc' => 'application/vnd.ms-excel',
    'xlf' => 'application/x-xliff+xml',
    'xlm' => 'application/vnd.ms-excel',
    'xls' => 'application/vnd.ms-excel',
    'xlsb' => 'application/vnd.ms-excel.sheet.binary.macroenabled.12',
    'xlsm' => 'application/vnd.ms-excel.sheet.macroenabled.12',
    'xlsx' => 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
    'xlt' => 'application/vnd.ms-excel',
    'xltm' => 'application/vnd.ms-excel.template.macroenabled.12',
    'xltx' => 'application/vnd.openxmlformats-officedocument.spreadsheetml.template',
    'xlw' => 'application/vnd.ms-excel',
    'xm' => 'audio/xm',
    'xml' => 'application/xml',
    'xo' => 'application/vnd.olpc-sugar',
    'xop' => 'application/xop+xml',
    'xpi' => 'application/x-xpinstall',
    'xpl' => 'application/xproc+xml',
    'xpm' => 'image/x-xpixmap',
    'xpr' => 'application/vnd.is-xpr',
    'xps' => 'application/vnd.ms-xpsdocument',
    'xpw' => 'application/vnd.intercon.formnet',
    'xpx' => 'application/vnd.intercon.formnet',
    'xsl' => 'application/xml',
    'xslt' => 'application/xslt+xml',
    'xsm' => 'application/vnd.syncml+xml',
    'xspf' => 'application/xspf+xml',
    'xul' => 'application/vnd.mozilla.xul+xml',
    'xvm' => 'application/xv+xml',
    'xvml' => 'application/xv+xml',
    'xwd' => 'image/x-xwindowdump',
    'xyz' => 'chemical/x-xyz',
    'xz' => 'application/x-xz',
    'yang' => 'application/yang',
    'yin' => 'application/yin+xml',
    'z1' => 'application/x-zmachine',
    'z2' => 'application/x-zmachine',
    'z3' => 'application/x-zmachine',
    'z4' => 'application/x-zmachine',
    'z5' => 'application/x-zmachine',
    'z6' => 'application/x-zmachine',
    'z7' => 'application/x-zmachine',
    'z8' => 'application/x-zmachine',
    'zaz' => 'application/vnd.zzazz.deck+xml',
    'zip' => 'application/zip',
    'zir' => 'application/vnd.zul',
    'zirz' => 'application/vnd.zul',
    'zmm' => 'application/vnd.handheld-entertainment+xml',
    '123' => 'application/vnd.lotus-1-2-3',
];


================================================
FILE: lib/preferences.php
================================================
<?php

/****************************************************************************/
/*                                                                          */
/* YOU MAY WISH TO MODIFY OR REMOVE THE FOLLOWING LINES WHICH SET DEFAULTS  */
/*                                                                          */
/****************************************************************************/

$preferences = Swift_Preferences::getInstance();

// Sets the default charset so that setCharset() is not needed elsewhere
$preferences->setCharset('utf-8');

// Without these lines the default caching mechanism is "array" but this uses a lot of memory.
// If possible, use a disk cache to enable attaching large attachments etc.
// You can override the default temporary directory by setting the TMPDIR environment variable.
if (@is_writable($tmpDir = sys_get_temp_dir())) {
    $preferences->setTempDir($tmpDir)->setCacheType('disk');
}


================================================
FILE: lib/swift_required.php
================================================
<?php

/*
 * This file is part of SwiftMailer.
 * (c) 2004-2009 Chris Corbyn
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

require __DIR__.'/classes/Swift.php';

Swift::registerAutoload(function () {
    // Load in dependency maps
    require __DIR__.'/dependency_maps/cache_deps.php';
    require __DIR__.'/dependency_maps/mime_deps.php';
    require __DIR__.'/dependency_maps/message_deps.php';
    require __DIR__.'/dependency_maps/transport_deps.php';

    // Load in global library preferences
    require __DIR__.'/preferences.php';
});


================================================
FILE: lib/swiftmailer_generate_mimes_config.php
================================================
#!/usr/bin/php

<?php
\define('APACHE_MIME_TYPES_URL', 'https://svn.apache.org/repos/asf/httpd/httpd/trunk/docs/conf/mime.types');
\define('FREEDESKTOP_XML_URL', 'https://raw.github.com/minad/mimemagic/master/script/freedesktop.org.xml');

function generateUpToDateMimeArray()
{
    $preamble = "<?php\n\n";
    $preamble .= "/*\n";
    $preamble .= " * This file is part of SwiftMailer.\n";
    $preamble .= " * (c) 2004-2009 Chris Corbyn\n *\n";
    $preamble .= " * For the full copyright and license information, please view the LICENSE\n";
    $preamble .= " * file that was distributed with this source code.\n *\n";
    $preamble .= " * autogenerated using https://svn.apache.org/repos/asf/httpd/httpd/trunk/docs/conf/mime.types\n";
    $preamble .= " * and https://raw.github.com/minad/mimemagic/master/script/freedesktop.org.xml\n";
    $preamble .= " */\n\n";
    $preamble .= "/*\n";
    $preamble .= " * List of MIME type automatically detected in Swift Mailer.\n";
    $preamble .= " */\n\n";
    $preamble .= "// You may add or take away what you like (lowercase required)\n\n";

    // get current mime types files
    $mime_types = @file_get_contents(APACHE_MIME_TYPES_URL);
    $mime_xml = @file_get_contents(FREEDESKTOP_XML_URL);

    // prepare valid mime types
    $valid_mime_types = [];

    // split mime type and extensions eg. "video/x-matroska        mkv mk3d mks"
    if (false !== preg_match_all('/^#?([a-z0-9\-\+\/\.]+)[\t]+(.*)$/miu', $mime_types, $matches)) {
        // collection of predefined mimetypes (bugfix for wrong resolved or missing mime types)
        $valid_mime_types_preset = [
            'php' => 'application/x-php',
            'php3' => 'application/x-php',
            'php4' => 'application/x-php',
            'php5' => 'application/x-php',
            'zip' => 'application/zip',
            'gif' => 'image/gif',
            'png' => 'image/png',
            'css' => 'text/css',
            'js' => 'text/javascript',
            'txt' => 'text/plain',
            'aif' => 'audio/x-aiff',
            'aiff' => 'audio/x-aiff',
            'avi' => 'video/avi',
            'bmp' => 'image/bmp',
            'bz2' => 'application/x-bz2',
            'csv' => 'text/csv',
            'dmg' => 'application/x-apple-diskimage',
            'doc' => 'application/msword',
            'docx' => 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
            'eml' => 'message/rfc822',
            'aps' => 'application/postscript',
            'exe' => 'application/x-ms-dos-executable',
            'flv' => 'video/x-flv',
            'gz' => 'application/x-gzip',
            'hqx' => 'application/stuffit',
            'htm' => 'text/html',
            'html' => 'text/html',
            'jar' => 'application/x-java-archive',
            'jpeg' => 'image/jpeg',
            'jpg' => 'image/jpeg',
            'm3u' => 'audio/x-mpegurl',
            'm4a' => 'audio/mp4',
            'mdb' => 'application/x-msaccess',
            'mid' => 'audio/midi',
            'midi' => 'audio/midi',
            'mov' => 'video/quicktime',
            'mp3' => 'audio/mpeg',
            'mp4' => 'video/mp4',
            'mpeg' => 'video/mpeg',
            'mpg' => 'video/mpeg',
            'odg' => 'vnd.oasis.opendocument.graphics',
            'odp' => 'vnd.oasis.opendocument.presentation',
            'odt' => 'vnd.oasis.opendocument.text',
            'ods' => 'vnd.oasis.opendocument.spreadsheet',
            'ogg' => 'audio/ogg',
            'pdf' => 'application/pdf',
            'ppt' => 'application/vnd.ms-powerpoint',
            'pptx' => 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
            'ps' => 'application/postscript',
            'rar' => 'application/x-rar-compressed',
            'rtf' => 'application/rtf',
            'tar' => 'application/x-tar',
            'sit' => 'application/x-stuffit',
            'svg' => 'image/svg+xml',
            'tif' => 'image/tiff',
            'tiff' => 'image/tiff',
            'ttf' => 'application/x-font-truetype',
            'vcf' => 'text/x-vcard',
            'wav' => 'audio/wav',
            'wma' => 'audio/x-ms-wma',
            'wmv' => 'audio/x-ms-wmv',
            'xls' => 'application/vnd.ms-excel',
            'xlsx' => 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
            'xml' => 'application/xml',
        ];

        // wrap array for generating file
        foreach ($valid_mime_types_preset as $extension => $mime_type) {
            // generate array for mimetype to extension resolver (only first match)
            $valid_mime_types[$extension] = "'{$extension}' => '{$mime_type}'";
        }

        // all extensions from second match
        foreach ($matches[2] as $i => $extensions) {
            // explode multiple extensions from string
            $extensions = explode(' ', strtolower($extensions ?? ''));

            // force array for foreach
            if (!\is_array($extensions)) {
                $extensions = [$extensions];
            }

            foreach ($extensions as $extension) {
                // get mime type
                $mime_type = $matches[1][$i];

                // check if string length lower than 10
                if (\strlen($extension) < 10) {
                    if (!isset($valid_mime_types[$mime_type])) {
                        // generate array for mimetype to extension resolver (only first match)
                        $valid_mime_types[$extension] = "'{$extension}' => '{$mime_type}'";
                    }
                }
            }
        }
    }

    $xml = simplexml_load_string($mime_xml);

    foreach ($xml as $node) {
        // check if there is no pattern
        if (!isset($node->glob['pattern'])) {
            continue;
        }

        // get all matching extensions from match
        foreach ((array) $node->glob['pattern'] as $extension) {
            // skip none glob extensions
            if (false === strpos($extension ?? '', '.')) {
                continue;
            }

            // remove get only last part
            $extension = explode('.', strtolower($extension ?? ''));
            $extension = end($extension);
        }

        if (isset($node->glob['pattern'][0])) {
            // mime type
            $mime_type = strtolower((string) $node['type'] ?? '');

            // get first extension
            $extension = strtolower(trim($node->glob['ddpattern'][0] ?? '', '*.'));

            // skip none glob extensions and check if string length between 1 and 10
            if (false !== strpos($extension, '.') || \strlen($extension) < 1 || \strlen($extension) > 9) {
                continue;
            }

            // check if string length lower than 10
            if (!isset($valid_mime_types[$mime_type])) {
                // generate array for mimetype to extension resolver (only first match)
                $valid_mime_types[$extension] = "'{$extension}' => '{$mime_type}'";
            }
        }
    }

    // full list of valid extensions only
    $valid_mime_types = array_unique($valid_mime_types);
    ksort($valid_mime_types);

    // combine mime types and extensions array
    $output = "$preamble\$swift_mime_types = array(\n    ".implode(",\n    ", $valid_mime_types)."\n);";

    // write mime_types.php config file
    @file_put_contents('./mime_types.php', $output);
}

generateUpToDateMimeArray();


================================================
FILE: phpunit.xml.dist
================================================
<?xml version="1.0" encoding="UTF-8"?>
<phpunit backupGlobals="false"
         backupStaticAttributes="false"
         colors="true"
         convertErrorsToExceptions="true"
         convertNoticesToExceptions="true"
         convertWarningsToExceptions="true"
         processIsolation="false"
         stopOnFailure="false"
         bootstrap="tests/bootstrap.php"
>
    <php>
        <ini name="intl.default_locale" value="en"/>
        <ini name="intl.error_level" value="0"/>
        <ini name="memory_limit" value="-1"/>
        <ini name="error_reporting" value="-1" />
    </php>

    <testsuites>
        <testsuite name="SwiftMailer unit tests">
            <directory>tests/unit</directory>
        </testsuite>
        <testsuite name="SwiftMailer acceptance tests">
            <directory>tests/acceptance</directory>
        </testsuite>
        <testsuite name="SwiftMailer bug">
            <directory>tests/bug</directory>
        </testsuite>
        <testsuite name="SwiftMailer smoke tests">
            <directory>tests/smoke</directory>
        </testsuite>
    </testsuites>

    <listeners>
        <listener class="Symfony\Bridge\PhpUnit\SymfonyTestsListener" />
        <listener class="Mockery\Adapter\Phpunit\TestListener" />
    </listeners>
</phpunit>


================================================
FILE: tests/IdenticalBinaryConstraint.php
================================================
<?php

/**
 * A binary safe string comparison.
 *
 * @author Chris Corbyn
 */
class IdenticalBinaryConstraint extends \PHPUnit\Framework\Constraint\Constraint
{
    protected $value;

    public function __construct($value)
    {
        $this->value = $value;
    }

    /**
     * Evaluates the constraint for parameter $other. Returns TRUE if the
     * constraint is met, FALSE otherwise.
     *
     * @param mixed $other value or object to evaluate
     */
    public function matches($other): bool
    {
        $aHex = $this->asHexString($this->value);
        $bHex = $this->asHexString($other);

        return $aHex === $bHex;
    }

    /**
     * Returns a string representation of the constraint.
     */
    public function toString(): string
    {
        return 'identical binary';
    }

    /**
     * Get the given string of bytes as a stirng of Hexadecimal sequences.
     *
     * @param string $binary
     *
     * @return string
     */
    private function asHexString($binary)
    {
        $hex = '';

        $bytes = unpack('H*', $binary);

        foreach ($bytes as &$byte) {
            $byte = strtoupper($byte);
        }

        return implode('', $bytes);
    }
}


================================================
FILE: tests/StreamCollector.php
================================================
<?php

class Swift_StreamCollector
{
    public $content = '';

    public function __invoke($arg)
    {
        $this->content .= $arg;
    }
}


================================================
FILE: tests/SwiftMailerSmokeTestCase.php
================================================
<?php

/**
 * Base test for smoke tests.
 *
 * @author Rouven Weßling
 */
class SwiftMailerSmokeTestCase extends SwiftMailerTestCase
{
    protected function setUp()
    {
        if (!\defined('SWIFT_SMOKE_TRANSPORT_TYPE')) {
            $this->markTestSkipped(
                'Smoke tests are skipped if tests/smoke.conf.php is not edited'
             );
        }
    }

    protected function getMailer()
    {
        switch (SWIFT_SMOKE_TRANSPORT_TYPE) {
            case 'smtp':
                $transport = Swift_DependencyContainer::getInstance()->lookup('transport.smtp')
                    ->setHost(SWIFT_SMOKE_SMTP_HOST)
                    ->setPort(SWIFT_SMOKE_SMTP_PORT)
                    ->setUsername(SWIFT_SMOKE_SMTP_USER)
                    ->setPassword(SWIFT_SMOKE_SMTP_PASS)
                    ->setEncryption(SWIFT_SMOKE_SMTP_ENCRYPTION)
                    ;
                break;
            case 'sendmail':
                $transport = Swift_DependencyContainer::getInstance()->lookup('transport.sendmail')
                    ->setCommand(SWIFT_SMOKE_SENDMAIL_COMMAND)
                    ;
                break;
            case 'mail':
            case 'nativemail':
                $transport = Swift_DependencyContainer::getInstance()->lookup('transport.mail');
                break;
            default:
                throw new Exception('Undefined transport ['.SWIFT_SMOKE_TRANSPORT_TYPE.']');
        }

        return new Swift_Mailer($transport);
    }
}


================================================
FILE: tests/SwiftMailerTestCase.php
================================================
<?php

use Mockery\Adapter\Phpunit\MockeryPHPUnitIntegration;

/**
 * A base test case with some custom expectations.
 *
 * @author Rouven Weßling
 */
class SwiftMailerTestCase extends \PHPUnit\Framework\TestCase
{
    use MockeryPHPUnitIntegration;

    public static function regExp($pattern)
    {
        if (!\is_string($pattern)) {
            throw PHPUnit\Util\InvalidArgumentHelper::factory(1, 'string');
        }

        return new \PHPUnit\Framework\Constraint\RegularExpression($pattern);
    }

    public function assertIdenticalBinary($expected, $actual, $message = '')
    {
        $constraint = new IdenticalBinaryConstraint($expected);
        self::assertThat($actual, $constraint, $message);
    }

    protected function getMockery($class)
    {
        return \Mockery::mock($class);
    }
}


================================================
FILE: tests/_samples/charsets/iso-2022-jp/one.txt
================================================
ISO-2022-JPは、インターネット上(特に電子メール)などで使われる日本の文字用の文字符号化方式。ISO/IEC 2022のエスケープシーケンスを利用して文字集合を切り替える7ビットのコードであることを特徴とする (アナウンス機能のエスケープシーケンスは省略される)。俗に「JISコード」と呼ばれることもある。

概要
日本語表記への利用が想定されている文字コードであり、日本語の利用されるネットワークにおいて、日本の規格を応用したものである。また文字集合としては、日本語で用いられる漢字、ひらがな、カタカナはもちろん、ラテン文字、ギリシア文字、キリル文字なども含んでおり、学術や産業の分野での利用も考慮たものとなっている。規格名に、ISOの日本語の言語コードであるjaではなく、国・地域名コードのJPが示されているゆえんである。
文字集合としてJIS X 0201のC0集合（制御文字）、JIS X 0201のラテン文字集合、ISO 646の国際基準版図形文字、JIS X 0208の1978年版（JIS C 6226-1978）と1983年および1990年版が利用できる。JIS X 0201の片仮名文字集合は利用できない。1986年以降、日本の電子メールで用いられてきたJUNETコードを、村井純・Mark Crispin・Erik van der Poelが1993年にRFC化したもの(RFC 1468)。後にJIS X 0208:1997の附属書2としてJISに規定された。MIMEにおける文字符号化方式の識別用の名前として IANA に登録されている。
なお、符号化の仕様についてはISO/IEC 2022#ISO-2022-JPも参照。

ISO-2022-JPと非標準的拡張使用
「JISコード」（または「ISO-2022-JP」）というコード名の規定下では、その仕様通りの使用が求められる。しかし、Windows OS上では、実際にはCP932コード (MicrosoftによるShift JISを拡張した亜種。ISO-2022-JP規定外文字が追加されている。）による独自拡張（の文字）を断りなく使うアプリケーションが多い。この例としてInternet ExplorerやOutlook Expressがある。また、EmEditor、秀丸エディタやThunderbirdのようなMicrosoft社以外のWindowsアプリケーションでも同様の場合がある。この場合、ISO-2022-JPの範囲外の文字を使ってしまうと、異なる製品間では未定義不明文字として認識されるか、もしくは文字化けを起こす原因となる。そのため、Windows用の電子メールクライアントであっても独自拡張の文字を使用すると警告を出したり、あえて使えないように制限しているものも存在する。さらにはISO-2022-JPの範囲内であってもCP932は非標準文字（FULLWIDTH TILDE等）を持つので文字化けの原因になり得る。
また、符号化方式名をISO-2022-JPとしているのに、文字集合としてはJIS X 0212 (いわゆる補助漢字) やJIS X 0201の片仮名文字集合 (いわゆる半角カナ) をも符号化している例があるが、ISO-2022-JPではこれらの文字を許容していない。これらの符号化は独自拡張の実装であり、中にはISO/IEC 2022の仕様に準拠すらしていないものもある[2]。従って受信側の電子メールクライアントがこれらの独自拡張に対応していない場合、その文字あるいはその文字を含む行、時にはテキスト全体が文字化けすることがある。



================================================
FILE: tests/_samples/charsets/iso-8859-1/one.txt
================================================
Op mat eraus hinnen beschte, rou zënne schaddreg ké. Ké sin Eisen Kaffi prächteg, den haut esou Fielse wa, Well zielen d'Welt am dir. Aus grousse rëschten d'Stroos do, as dat Kléder gewëss d'Kàchen. Schied gehéiert d'Vioule net hu, rou ke zënter Säiten d'Hierz. Ze eise Fletschen mat, gei as gréng d'Lëtzebuerger. Wäit räich no mat.

Säiten d'Liewen aus en. Un gëtt bléit lossen wee, da wéi alle weisen Kolrettchen. Et deser d'Pan d'Kirmes vun, en wuel Benn rëschten méi. En get drem ménger beschte, da wär Stad welle. Nun Dach d'Pied do, mä gét ruffen gehéiert. Ze onser ugedon fir, d'Liewen Plett'len ech no, si Räis wielen bereet wat. Iwer spilt fir jo.

An hin däischter Margréitchen, eng ke Frot brommt, vu den Räis néierens. Da hir Hunn Frot nozegon, rout Fläiß Himmel zum si, net gutt Kaffi Gesträich fu. Vill lait Gaart sou wa, Land Mamm Schuebersonndeg rei do. Gei geet Minutt en, gei d'Leit beschte Kolrettchen et, Mamm fergiess un hun.

Et gutt Heck kommen oft, Lann rëscht rei um, Hunn rëscht schéinste ke der. En lait zielen schnéiwäiss hir, fu rou botze éiweg Minutt, rem fest gudden schaddreg en. Noper bereet Margréitchen mat op, dem denkt d'Leit d'Vioule no, oft ké Himmel Hämmel. En denkt blénken Fréijor net, Gart Schiet d'Natur no wou. No hin Ierd Frot d'Kirmes. Hire aremt un rou, ké den éiweg wielen Milliounen.

Mir si Hunn Blénkeg. Ké get ston derfir d'Kàchen. Haut d'Pan fu ons, dé frou löschteg d'Meereische rei. Sou op wuel Léift. Stret schlon grousse gin hu. Mä denkt d'Leit hinnen net, ké gét haut fort rëscht.

Koum d'Pan hannendrun ass ké, ké den brét Kaffi geplot. Schéi Hären d'Pied fu gét, do d'Mier néierens bei. Rëm päift Hämmel am, wee Engel beschéngt mä. Brommt klinzecht der ke, wa rout jeitzt dén. Get Zalot d'Vioule däischter da, jo fir Bänk päift duerch, bei d'Beem schéinen Plett'len jo. Den haut Faarwen ze, eng en Biereg Kirmesdag, um sin alles Faarwen d'Vioule.

Eng Hunn Schied et, wat wa Frot fest gebotzt. Bei jo bleiwe ruffen Klarinett. Un Feld klinzecht gét, rifft Margréitchen rem ke. Mir dé Noper duurch gewëss, ston sech kille sin en. Gei Stret d'Wise um, Haus Gart wee as. Monn ménger an blo, wat da Gart gefällt Hämmelsbrot.

Brommt geplot och ze, dat wa Räis Well Kaffi. Do get spilt prächteg, as wär kille bleiwe gewalteg. Onser frësch Margréitchen rem ke, blo en huet ugedon. Onser Hemecht wär de, hu eraus d'Sonn dat, eise deser hannendrun da och.

As durch Himmel hun, no fest iw'rem schéinste mir, Hunn séngt Hierz ke zum. Séngt iw'rem d'Natur zum an. Ke wär gutt Grénge. Kënnt gudden prächteg mä rei. Dé dir Blénkeg Klarinett Kolrettchen, da fort muerges d'Kanner wou, main Feld ruffen vu wéi. Da gin esou Zalot gewalteg, gét vill Hemecht blénken dé.

Haut gréng nun et, nei vu Bass gréng d'Gaassen. Fest d'Beem uechter si gin. Oft vu sinn wellen kréien. Et ass lait Zalot schéinen.

================================================
FILE: tests/_samples/charsets/utf-8/one.txt
================================================
Код одно гринспана руководишь на. Его вы знания движение. Ты две начать
одиночку, сказать основатель удовольствием но миф. Бы какие система тем.
Полностью использует три мы, человек клоунов те нас, бы давать творческую
эзотерическая шеф.

Мог не помнить никакого сэкономленного, две либо какие пишите бы. Должен
компанию кто те, этот заключалась проектировщик не ты. Глупые периоды ты
для. Вам который хороший он. Те любых кремния концентрируются мог,
собирать принадлежите без вы.

Джоэла меньше хорошего вы миф, за тем году разработки. Даже управляющим
руководители был не. Три коде выпускать заботиться ну. То его система
удовольствием безостановочно, или ты главной процессорах. Мы без джоэл
знания получат, статьи остальные мы ещё.

Них русском касается поскольку по, образование должником
систематизированный ну мои. Прийти кандидата университет но нас, для бы
должны никакого, биг многие причин интервьюирования за.

Тем до плиту почему. Вот учёт такие одного бы, об биг разным внешних
промежуток. Вас до какому возможностей безответственный, были погодите бы
его, по них глупые долгий количества.


================================================
FILE: tests/_samples/charsets/utf-8/three.txt
================================================
Αν ήδη διάβασε γλιτώσει μεταγλωτίσει, αυτήν θυμάμαι μου μα. Την κατάσταση χρησιμοποίησέ να! Τα διαφορά φαινόμενο διολισθήσεις πες, υψηλότερη προκαλείς περισσότερες όχι κι. Με ελέγχου γίνεται σας, μικρής δημιουργούν τη του. Τις τα γράψει εικόνες απαράδεκτη?

Να ότι πρώτοι απαραίτητο. Άμεση πετάνε κακόκεφος τον ώς, να χώρου πιθανότητες του. Το μέχρι ορίστε λιγότερους σας. Πω ναί φυσικά εικόνες.

Μου οι κώδικα αποκλειστικούς, λες το μάλλον συνεχώς. Νέου σημεία απίστευτα σας μα. Χρόνου μεταγλωτιστής σε νέα, τη τις πιάνει μπορούσες προγραμματιστές. Των κάνε βγαίνει εντυπωσιακό τα? Κρατάει τεσσαρών δυστυχώς της κι, ήδη υψηλότερη εξακολουθεί τα?

Ώρα πετάνε μπορούσε λιγότερους αν, τα απαράδεκτη συγχωνευτεί ροή. Τη έγραψες συνηθίζουν σαν. Όλα με υλικό στήλες χειρότερα. Ανώδυνη δουλέψει επί ως, αν διαδίκτυο εσωτερικών παράγοντες από. Κεντρικό επιτυχία πες το.

Πω ναι λέει τελειώσει, έξι ως έργων τελειώσει. Με αρχεία βουτήξουν ανταγωνιστής ώρα, πολύ γραφικά σελίδων τα στη. Όρο οέλεγχος δημιουργούν δε, ας θέλεις ελέγχου συντακτικό όρο! Της θυμάμαι επιδιόρθωση τα. Για μπορούσε περισσότερο αν, μέγιστη σημαίνει αποφάσισε τα του, άτομο αποτελέσει τι στα.

Τι στην αφήσεις διοίκηση στη. Τα εσφαλμένη δημιουργια επιχείριση έξι! Βήμα μαγικά εκτελέσει ανά τη. Όλη αφήσεις συνεχώς εμπορικά αν, το λες κόλπα επιτυχία. Ότι οι ζώνη κειμένων. Όρο κι ρωτάει γραμμής πελάτες, τελειώσει διολισθήσεις καθυστερούσε αν εγώ? Τι πετούν διοίκηση προβλήματα ήδη.

Τη γλιτώσει αποθηκευτικού μια. Πω έξι δημιουργια πιθανότητες, ως πέντε ελέγχους εκτελείται λες. Πως ερωτήσεις διοικητικό συγκεντρωμένοι οι, ας συνεχώς διοικητικό αποστηθίσει σαν. Δε πρώτες συνεχώς διολισθήσεις έχω, από τι κανένας βουτήξουν, γειτονιάς προσεκτικά ανταγωνιστής κι σαν.

Δημιουργια συνηθίζουν κλπ τι? Όχι ποσοστό διακοπής κι. Κλπ φακέλους δεδομένη εξοργιστικά θα? Υποψήφιο καθορίζουν με όλη, στα πήρε προσοχή εταιρείες πω, ώς τον συνάδελφος διοικητικό δημιουργήσεις! Δούλευε επιτίθενται σας θα, με ένας παραγωγικής ένα, να ναι σημεία μέγιστη απαράδεκτη?

Σας τεσσαρών συνεντεύξης τη, αρπάζεις σίγουρος μη για', επί τοπικές εντολές ακούσει θα? Ως δυστυχής μεταγλωτιστής όλη, να την είχαν σφάλμα απαραίτητο! Μην ώς άτομο διορθώσει χρησιμοποιούνταν. Δεν τα κόλπα πετάξαμε, μη που άγχος υόρκη άμεση, αφού δυστυχώς διακόψουμε όρο αν! Όλη μαγικά πετάνε επιδιορθώσεις δε, ροή φυσικά αποτελέσει πω.

Άπειρα παραπάνω φαινόμενο πω ώρα, σαν πόρτες κρατήσουν συνηθίζουν ως. Κι ώρα τρέξει είχαμε εφαρμογή. Απλό σχεδιαστής μεταγλωτιστής ας επί, τις τα όταν έγραψες γραμμής? Όλα κάνεις συνάδελφος εργαζόμενοι θα, χαρτιού χαμηλός τα ροή. Ως ναι όροφο έρθει, μην πελάτες αποφάσισε μεταφραστής με, να βιαστικά εκδόσεις αναζήτησης λες. Των φταίει εκθέσεις προσπαθήσεις οι, σπίτι αποστηθίσει ας λες?

Ώς που υπηρεσία απαραίτητο δημιουργείς. Μη άρα χαρά καθώς νύχτας, πω ματ μπουν είχαν. Άμεση δημιουργείς ώς ροή, γράψει γραμμής σίγουρος στα τι! Αν αφού πρώτοι εργαζόμενων ναί.

Άμεση διορθώσεις με δύο? Έχουν παράδειγμα των θα, μου έρθει θυμάμαι περισσότερο το. Ότι θα αφού χρειάζονται περισσότερες. Σαν συνεχώς περίπου οι.

Ώς πρώτης πετάξαμε λες, όρο κι πρώτες ζητήσεις δυστυχής. Ανά χρόνου διακοπή επιχειρηματίες ας, ώς μόλις άτομο χειρότερα όρο, κρατάει σχεδιαστής προσπαθήσεις νέο το. Πουλάς προσθέσει όλη πω, τύπου χαρακτηριστικό εγώ σε, πω πιο δούλευε αναζήτησης? Αναφορά δίνοντας σαν μη, μάθε δεδομένη εσωτερικών με ναι, αναφέρονται περιβάλλοντος ώρα αν. Και λέει απόλαυσε τα, που το όροφο προσπαθούν?

Πάντα χρόνου χρήματα ναι το, σαν σωστά θυμάμαι σκεφτείς τα. Μα αποτελέσει ανεπιθύμητη την, πιο το τέτοιο ατόμου, τη των τρόπο εργαλείων επιδιόρθωσης. Περιβάλλον παραγωγικής σου κι, κλπ οι τύπου κακόκεφους αποστηθίσει, δε των πλέον τρόποι. Πιθανότητες χαρακτηριστικών σας κι, γραφικά δημιουργήσεις μια οι, πω πολλοί εξαρτάται προσεκτικά εδώ. Σταματάς παράγοντες για' ώς, στις ρωτάει το ναι! Καρέκλα ζητήσεις συνδυασμούς τη ήδη!

Για μαγικά συνεχώς ακούσει το. Σταματάς προϊόντα βουτήξουν ώς ροή. Είχαν πρώτες οι ναι, μα λες αποστηθίσει ανακαλύπτεις. Όροφο άλγεβρα παραπάνω εδώ τη, πρόσληψη λαμβάνουν καταλάθος ήδη ας? Ως και εισαγωγή κρατήσουν, ένας κακόκεφους κι μας, όχι κώδικάς παίξουν πω. Πω νέα κρατάει εκφράσουν, τότε τελικών τη όχι, ας της τρέξει αλλάζοντας αποκλειστικούς.

Ένας βιβλίο σε άρα, ναι ως γράψει ταξινομεί διορθώσεις! Εδώ να γεγονός συγγραφείς, ώς ήδη διακόψουμε επιχειρηματίες? Ότι πακέτων εσφαλμένη κι, θα όρο κόλπα παραγωγικής? Αν έχω κεντρικό υψηλότερη, κι δεν ίδιο πετάνε παρατηρούμενη! Που λοιπόν σημαντικό μα, προκαλείς χειροκροτήματα ως όλα, μα επί κόλπα άγχος γραμμές! Δε σου κάνεις βουτήξουν, μη έργων επενδυτής χρησιμοποίησέ στα, ως του πρώτες διάσημα σημαντικό.

Βιβλίο τεράστιο προκύπτουν σαν το, σαν τρόπο επιδιόρθωση ας. Είχαν προσοχή προσπάθεια κι ματ, εδώ ως έτσι σελίδων συζήτηση. Και στην βγαίνει εσφαλμένη με, δυστυχής παράδειγμα δε μας, από σε υόρκη επιδιόρθωσης. Νέα πω νέου πιθανό, στήλες συγγραφείς μπαίνοντας μα για', το ρωτήσει κακόκεφους της? Μου σε αρέσει συγγραφής συγχωνευτεί, μη μου υόρκη ξέχασε διακοπής! Ώς επί αποφάσισε αποκλειστικούς χρησιμοποιώντας, χρήματα σελίδων ταξινομεί ναι με.

Μη ανά γραμμή απόλαυσε, πω ναι μάτσο διασφαλίζεται. Τη έξι μόλις εργάστηκε δημιουργούν, έκδοση αναφορά δυσκολότερο οι νέο. Σας ως μπορούσε παράδειγμα, αν ότι δούλευε μπορούσε αποκλειστικούς, πιο λέει βουτήξουν διορθώσει ως. Έχω τελευταία κακόκεφους ας, όσο εργαζόμενων δημιουργήσεις τα.

Του αν δουλέψει μπορούσε, πετούν χαμηλός εδώ ας? Κύκλο τύπους με που, δεν σε έχουν συνεχώς χειρότερα, τις τι απαράδεκτη συνηθίζουν? Θα μην τους αυτήν, τη ένα πήρε πακέτων, κι προκύπτουν περιβάλλον πως. Μα για δουλέψει απόλαυσε εφαμοργής, ώς εδώ σημαίνει μπορούσες, άμεση ακούσει προσοχή τη εδώ?

Στα δώσε αθόρυβες λιγότερους οι, δε αναγκάζονται αποκλειστικούς όλα! Ας μπουν διοικητικό μια, πάντα ελέγχου διορθώσεις ώς τον. Ότι πήρε κανόνα μα. Που άτομα κάνεις δημιουργίες τα, οι μας αφού κόλπα προγραμματιστής, αφού ωραίο προκύπτουν στα ως. Θέμα χρησιμοποιήσει αν όλα, του τα άλγεβρα σελίδων. Τα ότι ανώδυνη δυστυχώς συνδυασμούς, μας οι πάντα γνωρίζουμε ανταγωνιστής, όχι τα δοκιμάσεις σχεδιαστής! Στην συνεντεύξης επιδιόρθωση πιο τα, μα από πουλάς περιβάλλον παραγωγικής.

Έχουν μεταγλωτίσει σε σας, σε πάντα πρώτης μειώσει των, γράψει ρουτίνα δυσκολότερο ήδη μα? Ταξινομεί διορθώσεις να μας. Θα της προσπαθούν περιεχόμενα, δε έχω τοπικές στέλνοντάς. Ανά δε αλφα άμεση, κάποιο ρωτάει γνωρίζουμε πω στη, φράση μαγικά συνέχεια δε δύο! Αν είχαμε μειώσει ροή, μας μετράει καθυστερούσε επιδιορθώσεις μη. Χάος υόρκη κεντρικό έχω σε, ανά περίπου αναγκάζονται πω.

Όσο επιστρέφουν χρονοδιαγράμματα μη. Πως ωραίο κακόκεφος διαχειριστής ως, τις να διακοπής αναζήτησης. Κάποιο ποσοστό ταξινομεί επί τη? Μάθε άμεση αλλάζοντας δύο με, μου νέου πάντα να.

Πω του δυστυχώς πιθανότητες. Κι ρωτάει υψηλότερη δημιουργια ότι, πω εισαγωγή τελευταία απομόνωση ναι. Των ζητήσεις γνωρίζουμε ώς? Για' μη παραδοτέου αναφέρονται! Ύψος παραγωγικά ροή ως, φυσικά διάβασε εικόνες όσο σε? Δεν υόρκη διορθώσεις επεξεργασία θα, ως μέση σύστημα χρησιμοποιήσει τις.

================================================
FILE: tests/_samples/charsets/utf-8/two.txt
================================================
रखति आवश्यकत प्रेरना मुख्यतह हिंदी किएलोग असक्षम कार्यलय करते विवरण किके मानसिक दिनांक पुर्व संसाध एवम् कुशलता अमितकुमार प्रोत्साहित जनित देखने उदेशीत विकसित बलवान ब्रौशर किएलोग विश्लेषण लोगो कैसे जागरुक प्रव्रुति प्रोत्साहित सदस्य आवश्यकत प्रसारन उपलब्धता अथवा हिंदी जनित दर्शाता यन्त्रालय बलवान अतित सहयोग शुरुआत सभीकुछ माहितीवानीज्य लिये खरिदे है।अभी एकत्रित सम्पर्क रिती मुश्किल प्राथमिक भेदनक्षमता विश्व उन्हे गटको द्वारा तकरीबन

विश्व द्वारा व्याख्या सके। आजपर वातावरण व्याख्यान पहोच। हमारी कीसे प्राथमिक विचारशिलता पुर्व करती कम्प्युटर भेदनक्षमता लिये बलवान और्४५० यायेका वार्तालाप सुचना भारत शुरुआत लाभान्वित पढाए संस्था वर्णित मार्गदर्शन चुनने

================================================
FILE: tests/_samples/dkim/dkim.test.priv
================================================
-----BEGIN RSA PRIVATE KEY-----
MIICXAIBAAKBgQDZeUdi1RKnm9cRYNn6E24xxrRTouh3Va8JOEHQ5SB018lvbjwH
2lW5mZ/I0kh/dHsTN0zcN0VE62WIbnLreMk/af/4Pg1i93+c9TmfXmoropsmdLos
w0tjq50jGbBqtHZNJYAokP/u3uUuRw8g0V/O4zlQ3GlO/PDH7xDQzekl9wIDAQAB
AoGAaoCBXD5a72hbb/BNb7HaUlgscZUjYWW93bcGTGYZef8/b+m9Tl83gjhgzvlk
db62k1eOtX3/11uskp78eqLhctv7yWc0mQQhgOogY2qCwHTCH8wja8kJkUAnKQhs
P9sa5iJvgckiuX3SdxgTMwib9d1VyGq6YywiORiZF9rxyhECQQD/xhiZSi7y0ciB
g4bassy0GVMS7EDRumMHc8wC23E1H2mj5yPE/QLqkW4ddmCv2BbJnYmyNvOaK9tk
T2W+mn3/AkEA2aqDGja9CaTlY4BCXfiT166n+xVl5+d+1DENQ4FK9O2jpSi1265J
tjEkXVxUOpV1ZEcUVOdK6RpvsKpc7vVICQJBALEFO5UsQJ4SD0GD9Ft8kCy9sj9Q
f/Qnmc5YmIQJuKpZmVW07Y6yxcfu61U8zuIlHnBftiM/4Q18+RTN1s86QaUCQHoL
9MTfCnH85q46/XuJZQRbp07O+bvlfqTl+CTwuyHImaiCwi2ydRxWQ6ihm4zZvuAC
RvEwWz2HGDc73y4RlFkCQDDdnN9e46l1nMDLDI4cyyGBVg4Z2IZ3IAu5GaoUCGjM
a8w6kxE8f1d8DD5vvqVbmfK89TA/DjT+7/arBNBCiCM=
-----END RSA PRIVATE KEY-----


================================================
FILE: tests/_samples/dkim/dkim.test.pub
================================================
-----BEGIN PUBLIC KEY-----
MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDZeUdi1RKnm9cRYNn6E24xxrRT
ouh3Va8JOEHQ5SB018lvbjwH2lW5mZ/I0kh/dHsTN0zcN0VE62WIbnLreMk/af/4
Pg1i93+c9TmfXmoropsmdLosw0tjq50jGbBqtHZNJYAokP/u3uUuRw8g0V/O4zlQ
3GlO/PDH7xDQzekl9wIDAQAB
-----END PUBLIC KEY-----


================================================
FILE: tests/_samples/files/data.txt
================================================
<data>

================================================
FILE: tests/_samples/smime/CA.srl
================================================
D42DA34CF90FA0DE


================================================
FILE: tests/_samples/smime/ca.crt
================================================
-----BEGIN CERTIFICATE-----
MIIDazCCAlOgAwIBAgIJAKJCGQYLxWT1MA0GCSqGSIb3DQEBBQUAMEwxFzAVBgNV
BAMMDlN3aWZ0bWFpbGVyIENBMRQwEgYDVQQKDAtTd2lmdG1haWxlcjEOMAwGA1UE
BwwFUGFyaXMxCzAJBgNVBAYTAkZSMB4XDTEzMTEyNzA4MzkxMFoXDTE3MTEyNjA4
MzkxMFowTDEXMBUGA1UEAwwOU3dpZnRtYWlsZXIgQ0ExFDASBgNVBAoMC1N3aWZ0
bWFpbGVyMQ4wDAYDVQQHDAVQYXJpczELMAkGA1UEBhMCRlIwggEiMA0GCSqGSIb3
DQEBAQUAA4IBDwAwggEKAoIBAQC7RLdHE3OWo9aZwv1xA/cYyPui/gegxpTqClRp
gGcVQ+jxIfnJQDQndyoAvFDiqOiZ+gAjZGJeUHDp9C/2IZp05MLh+omt9N8pBykm
3nj/3ZwPXOAO0uyDPAOHhISITAxEuZCqDnq7iYujywtwfQ7bpW1hCK9PfNZYMStM
kw7LsGr5BqcKkPuOWTvxE3+NqK8HxydYolsoApEGhgonyImVh1Pg1Kjkt5ojvwAX
zOdjfw5poY5NArwuLORUH+XocetRo8DC6S42HkU/MoqcYxa9EuRuwuQh7GtE6baR
PgrDsEYaY4Asy43sK81V51F/8Q1bHZKN/goQdxQwzv+/nOLTAgMBAAGjUDBOMB0G
A1UdDgQWBBRHgqkl543tKhsVAvcx1I0JFU7JuDAfBgNVHSMEGDAWgBRHgqkl543t
KhsVAvcx1I0JFU7JuDAMBgNVHRMEBTADAQH/MA0GCSqGSIb3DQEBBQUAA4IBAQAz
OJiEQcygKGkkXXDiXGBvP/cSznj3nG9FolON0yHUBgdvLfNnctRMStGzPke0siLt
RJvjqiL0Uw+blmLJU8lgMyLJ9ctXkiLJ/WflabN7VzmwYRWe5HzafGQJAg5uFjae
VtAAHQgvbmdXB6brWvcMQmB8di7wjVedeigZvkt1z2V0FtBy8ybJaT5H6bX9Bf5C
dS9r4mLhk/0ThthpRhRxsmupSL6e49nJaIk9q0UTEQVnorJXPcs4SPTIY51bCp6u
cOebhNgndSxCiy0zSD7vRjNiyB/YNGZ9Uv/3DNTLleMZ9kZgfoKVpwYKrRL0IFT/
cfS2OV1wxRxq668qaOfK
-----END CERTIFICATE-----


================================================
FILE: tests/_samples/smime/ca.key
================================================
-----BEGIN RSA PRIVATE KEY-----
MIIEogIBAAKCAQEAu0S3RxNzlqPWmcL9cQP3GMj7ov4HoMaU6gpUaYBnFUPo8SH5
yUA0J3cqALxQ4qjomfoAI2RiXlBw6fQv9iGadOTC4fqJrfTfKQcpJt54/92cD1zg
DtLsgzwDh4SEiEwMRLmQqg56u4mLo8sLcH0O26VtYQivT3zWWDErTJMOy7Bq+Qan
CpD7jlk78RN/jaivB8cnWKJbKAKRBoYKJ8iJlYdT4NSo5LeaI78AF8znY38OaaGO
TQK8LizkVB/l6HHrUaPAwukuNh5FPzKKnGMWvRLkbsLkIexrROm2kT4Kw7BGGmOA
LMuN7CvNVedRf/ENWx2Sjf4KEHcUMM7/v5zi0wIDAQABAoIBAGyaWkvu/O7Uz2TW
z1JWgVuvWzfYaKYV5FCicvfITn/npVUKZikPge+NTR+mFqaMXHDHqoLb+axGrGUR
hysPq9q0vEx/lo763tyVWYlAJh4E8Dd8njganK0zBbz23kGJEOheUYY95XGTQBda
bqTq8c3x7zAB8GGBvXDh+wFqm38GLyMF6T+YEzWJZqXfg31f1ldRvf6+VFwlLfz6
cvTR7oUpYIsUeGE47kBs13SN7Oju6a355o/7wy9tOCRiu+r/ikXFh8rFGLfeTiwv
R1dhYjcEYGxZUD8u64U+Cj4qR1P0gHJL0kbh22VMMqgALOc8FpndkjNdg1Nun2X8
BWpsPwECgYEA7C9PfTOIZfxGBlCl05rmWex++/h5E5PbH1Cw/NGjIH1HjmAkO3+5
WyMXhySOJ8yWyCBQ/nxqc0w7+TO4C7wQcEdZdUak25KJ74v0sfmWWrVw6kcnLU6k
oawW/L2F2w7ET3zDoxKh4fOF34pfHpSbZk7XJ68YOfHpYVnP4efkQVMCgYEAyvrM
KA7xjnsKumWh206ag3QEI0M/9uPHWmrh2164p7w1MtawccZTxYYJ5o5SsjTwbxkf
0cAamp4qLInmRUxU1gk76tPYC3Ndp6Yf1C+dt0q/vtzyJetCDrdz8HHT1SpKbW0l
g6z1I5FMwa6oWvWsfS++W51vsxUheNsOJ4uxKIECgYBwM7GRiw+7U3N4wItm0Wmp
Qp642Tu7vzwTzmOmV3klkB6UVrwfv/ewgiVFQGqAIcNn42JW44g2qfq70oQWnws4
K80l15+t6Bm7QUPH4Qg6o4O26IKGFZxEadqpyudyP7um/2B5cfqRuvzYS4YQowyI
N+AirB3YOUJjyyTk7yMSnQKBgGNLpSvDg6+ryWe96Bwcq8G6s3t8noHsk81LlAl4
oOSNUYj5NX+zAbATDizXWuUKuMPgioxVaa5RyVfYbelgme/KvKD32Sxg12P4BIIM
eR79VifMdjjOiZYhcHojdPlGovo89qkfpxwrLF1jT8CPhj4HaRvwPIBiyekRYC9A
Sv4BAoGAXCIC1xxAJP15osUuQjcM8KdsL1qw+LiPB2+cJJ2VMAZGV7CR2K0aCsis
OwRaYM0jZKUpxzp1uwtfrfqbhdYsv+jIBkfwoShYZuo6MhbUrj0sffkhJC3WrT2z
xafCFLFv1idzGvvNxatlp1DNKrndG2NS3syVAox9MnL5OMsvGM8=
-----END RSA PRIVATE KEY-----


================================================
FILE: tests/_samples/smime/create-cert.sh
================================================
#!/bin/sh

openssl genrsa -out CA.key 2048
openssl req -x509 -new -nodes -key CA.key -days 1460 -subj '/CN=Swiftmailer CA/O=Swiftmailer/L=Paris/C=FR' -out CA.crt
openssl x509 -in CA.crt -clrtrust -out CA.crt

openssl genrsa -out sign.key 2048
openssl req -new -key sign.key -subj '/CN=Swiftmailer-User/O=Swiftmailer/L=Paris/C=FR' -out sign.csr
openssl x509 -req -in sign.csr -CA CA.crt -CAkey CA.key -out sign.crt -days 1460 -addtrust emailProtection
openssl x509 -in sign.crt -clrtrust -out sign.crt

rm sign.csr

openssl genrsa -out intermediate.key 2048
openssl req -new -key intermediate.key -subj '/CN=Swiftmailer Intermediate/O=Swiftmailer/L=Paris/C=FR' -out intermediate.csr
openssl x509 -req -in intermediate.csr -CA CA.crt -CAkey CA.key -set_serial 01 -out intermediate.crt -days 1460
openssl x509 -in intermediate.crt -clrtrust -out intermediate.crt

rm intermediate.csr

openssl genrsa -out sign2.key 2048
openssl req -new -key sign2.key -subj '/CN=Swiftmailer-User2/O=Swiftmailer/L=Paris/C=FR' -out sign2.csr
openssl x509 -req -in sign2.csr -CA intermediate.crt -CAkey intermediate.key -set_serial 01 -out sign2.crt -days 1460 -addtrust emailProtection
openssl x509 -in sign2.crt -clrtrust -out sign2.crt

rm sign2.csr

openssl genrsa -out encrypt.key 2048
openssl req -new -key encrypt.key -subj '/CN=Swiftmailer-User/O=Swiftmailer/L=Paris/C=FR' -out encrypt.csr
openssl x509 -req -in encrypt.csr -CA CA.crt -CAkey CA.key -CAcreateserial -out encrypt.crt -days 1460 -addtrust emailProtection
openssl x509 -in encrypt.crt -clrtrust -out encrypt.crt

rm encrypt.csr

openssl genrsa -out encrypt2.key 2048
openssl req -new -key encrypt2.key -subj '/CN=Swiftmailer-User2/O=Swiftmailer/L=Paris/C=FR' -out encrypt2.csr
openssl x509 -req -in encrypt2.csr -CA CA.crt -CAkey CA.key -CAcreateserial -out encrypt2.crt -days 1460 -addtrust emailProtection
openssl x509 -in encrypt2.crt -clrtrust -out encrypt2.crt

rm encrypt2.csr


================================================
FILE: tests/_samples/smime/encrypt.crt
================================================
-----BEGIN CERTIFICATE-----
MIIDFjCCAf4CCQDULaNM+Q+g3TANBgkqhkiG9w0BAQUFADBMMRcwFQYDVQQDDA5T
d2lmdG1haWxlciBDQTEUMBIGA1UECgwLU3dpZnRtYWlsZXIxDjAMBgNVBAcMBVBh
cmlzMQswCQYDVQQGEwJGUjAeFw0xMzExMjcwODM5MTFaFw0xNzExMjYwODM5MTFa
ME4xGTAXBgNVBAMMEFN3aWZ0bWFpbGVyLVVzZXIxFDASBgNVBAoMC1N3aWZ0bWFp
bGVyMQ4wDAYDVQQHDAVQYXJpczELMAkGA1UEBhMCRlIwggEiMA0GCSqGSIb3DQEB
AQUAA4IBDwAwggEKAoIBAQCcNO+fVZBT2znmVwXXZ08n3G5WA1kyvqh9z4RBBZOD
V46Gc1X9MMXr9+wzZBFkAckKaa6KsTkeUr4pC8XUBpQnakxH/kW9CaDPdOE+7wNo
FkPfc6pjWWgpAVxdkrtk7pb4/aGQ++HUkqVu0cMpIcj/7ht7H+3QLZHybn+oMr2+
FDnn8vPmHxVioinSrxKTlUITuLWS9ZZUTrDa0dG8UAv55A/Tba4T4McCPDpJSA4m
9jrW321NGQUntQoItOJxagaueSvh6PveGV826gTXoU5X+YJ3I2OZUEQ2l6yByAzf
nT+QlxPj5ikotFwL72HsenYtetynOO/k43FblAF/V/l7AgMBAAEwDQYJKoZIhvcN
AQEFBQADggEBAJ048Sdb9Sw5OJM5L00OtGHgcT1B/phqdzSjkM/s64cg3Q20VN+F
fZIIkOnxgyYWcpOWXcdNw2tm5OWhWPGsBcYgMac7uK/ukgoOJSjICg+TTS5kRo96
iHtmImqkWc6WjNODh7uMnQ6DsZsscdl7Bkx5pKhgGnEdHr5GW8sztgXgyPQO5LUs
YzCmR1RK1WoNMxwbPrGLgYdcpJw69ns5hJbZbMWwrdufiMjYWvTfBPABkk1JRCcY
K6rRTAx4fApsw1kEIY8grGxyAzfRXLArpro7thJr0SIquZ8GpXkQT/mgRR8JD9Hp
z9yhr98EnKzITE/yclGN4pUsuk9S3jiyzUU=
-----END CERTIFICATE-----


================================================
FILE: tests/_samples/smime/encrypt.key
================================================
-----BEGIN RSA PRIVATE KEY-----
MIIEpAIBAAKCAQEAnDTvn1WQU9s55lcF12dPJ9xuVgNZMr6ofc+EQQWTg1eOhnNV
/TDF6/fsM2QRZAHJCmmuirE5HlK+KQvF1AaUJ2pMR/5FvQmgz3ThPu8DaBZD33Oq
Y1loKQFcXZK7ZO6W+P2hkPvh1JKlbtHDKSHI/+4bex/t0C2R8m5/qDK9vhQ55/Lz
5h8VYqIp0q8Sk5VCE7i1kvWWVE6w2tHRvFAL+eQP022uE+DHAjw6SUgOJvY61t9t
TRkFJ7UKCLTicWoGrnkr4ej73hlfNuoE16FOV/mCdyNjmVBENpesgcgM350/kJcT
4+YpKLRcC+9h7Hp2LXrcpzjv5ONxW5QBf1f5ewIDAQABAoIBADmuMm2botfUM+Ui
bT3FIC2P8A5C3kUmsgEDB8sazAXL5w0uuanswKkJu2aepO1Q23PE4nbESlswIpf1
iO9qHnsPfWt4MThEveTdO++JQrDEx/tTMq/M6/F4VysWa6wxjf4Taf2nhRSBsiTh
wDcICri2q98jQyWELkhfFTR+yCHPsn6iNtzE2OpNv9ojKiSqck/sVjC39Z+uU/HD
N4v0CPf9pDGkO+modaVGKf2TpvZT7Hpq/jsPzkk1h7BY7aWdZiIY4YkBkWYqZk8f
0dsxKkOR2glfuEYNtcywG+4UGx3i1AY0mMu96hH5M1ACFmFrTCoodmWDnWy9wUpm
leLmG8ECgYEAywWdryqcvLyhcmqHbnmUhCL9Vl4/5w5fr/5/FNvqArxSGwd2CxcN
Jtkvu22cxWAUoe155eMc6GlPIdNRG8KdWg4sg0TN3Jb2jiHQ3QkHXUJlWU6onjP1
g2n5h052JxVNGBEb7hr3U7ZMW6wnuYnGdYwCB9P3r5oGxxtfVRB8ygUCgYEAxPfy
tAd3SNT8Sv/cciw76GYKbztUjJRXkLo6GOBGq/AQxP1NDWMuL2AES11YIahidMsF
TMmM+zhkNHsd5P69p87FTMWx0cLoH0M9iQNK7Q6C1luTjLf5DTFuk+nHGErM4Drs
+6Ly1Z4KLXfXgBDD8Ce6U9+W3RrCc36poGZvjX8CgYEAna0P6WJr9r19mhIYevmc
Gf/ex7xNXxMvx80dP8MIfPVrwyhJSpWtljVpt+SKtFRJ0fVRDfUUl4Bqf/fR74B3
muCVO6ItTBxHAt5Ki9CeUpTlh7XqiWwLSvP8Y1TRuMr3ZDCtg4CYBAD6Ttxmwde6
NcL2NMQwgsZaazrcEIHMmU0CgYEAl/Mn2tZ/oUIdt8YWzEVvmeNOXW0J1sGBo/bm
ZtZt7qpuZWl7jb5bnNSXu4QxPxXljnAokIpUJmHke9AWydfze4c6EfXZLhcMd0Gq
MQ7HOIWfTbqr4zzx9smRoq4Ql57s2nba521XpJAdDeKL7xH/9j7PsXCls8C3Dd5D
AajEmgUCgYAGEdn6tYxIdX7jF39E3x7zHQf8jHIoQ7+cLTLtd944mSGgeqMfbiww
CoUa+AAUqjdAD5ViAyJrA+gmDtWpkFnJZtToXYwfUF2o3zRo4k1DeBrVbFqwSQkE
omrfiBGtviYIPdqQLE34LYpWEooNPraqO9qTyc+9w5038u2OFS+WmQ==
-----END RSA PRIVATE KEY-----


================================================
FILE: tests/_samples/smime/encrypt2.crt
================================================
-----BEGIN CERTIFICATE-----
MIIDFzCCAf8CCQDULaNM+Q+g3jANBgkqhkiG9w0BAQUFADBMMRcwFQYDVQQDDA5T
d2lmdG1haWxlciBDQTEUMBIGA1UECgwLU3dpZnRtYWlsZXIxDjAMBgNVBAcMBVBh
cmlzMQswCQYDVQQGEwJGUjAeFw0xMzExMjcwODM5MTJaFw0xNzExMjYwODM5MTJa
ME8xGjAYBgNVBAMMEVN3aWZ0bWFpbGVyLVVzZXIyMRQwEgYDVQQKDAtTd2lmdG1h
aWxlcjEOMAwGA1UEBwwFUGFyaXMxCzAJBgNVBAYTAkZSMIIBIjANBgkqhkiG9w0B
AQEFAAOCAQ8AMIIBCgKCAQEAw4AoYVYss2sa1BWJAJpK6gVemjXrp1mVXVpb1/z6
SH15AGsp3kiNXsMpgvsdofbqC/5HXrw2G8gWqo+uh6GuK67+Tvp7tO2aD4+8CZzU
K1cffj7Pbx95DUPwXckv79PT5ZcuyeFaVo92aug11+gS/P8n0WXSlzZxNuZ1f3G2
r/IgwfNKZlarEf1Ih781L2SwmyveW/dtsV2pdrd4IZwsV5SOF2zBFIXSuhPN0c+m
mtwSJe+Ow1udLX4KJkAX8sGVFJ5P5q4s2nS9vLkkj7X6YRQscbyJO9L7e1TksRqL
DLxZwiko6gUhp4/bIs1wDj5tzkQBi4qXviRq3i7A9b2d0QIDAQABMA0GCSqGSIb3
DQEBBQUAA4IBAQAj8iARhPB2DA3YfT5mJJrgU156Sm0Z3mekAECsr+VqFZtU/9Dz
pPFYEf0hg61cjvwhLtOmaTB+50hu1KNNlu8QlxAfPJqNxtH85W0CYiZHJwW9eSTr
z1swaHpRHLDUgo3oAXdh5syMbdl0MWos0Z14WP5yYu4IwJXs+j2JRW70BICyrNjm
d+AjCzoYjKMdJkSj4uxQEOuW2/5veAoDyU+kHDdfT7SmbyoKu+Pw4Xg/XDuKoWYg
w5/sRiw5vxsmOr9+anspDHdP9rUe1JEfwAJqZB3fwdqEyxu54Xw/GedG4wZBEJf0
ZcS1eh31emcjYUHQa1IA93jcFSmXzJ+ftJrY
-----END CERTIFICATE-----


================================================
FILE: tests/_samples/smime/encrypt2.key
================================================
-----BEGIN RSA PRIVATE KEY-----
MIIEpAIBAAKCAQEAw4AoYVYss2sa1BWJAJpK6gVemjXrp1mVXVpb1/z6SH15AGsp
3kiNXsMpgvsdofbqC/5HXrw2G8gWqo+uh6GuK67+Tvp7tO2aD4+8CZzUK1cffj7P
bx95DUPwXckv79PT5ZcuyeFaVo92aug11+gS/P8n0WXSlzZxNuZ1f3G2r/IgwfNK
ZlarEf1Ih781L2SwmyveW/dtsV2pdrd4IZwsV5SOF2zBFIXSuhPN0c+mmtwSJe+O
w1udLX4KJkAX8sGVFJ5P5q4s2nS9vLkkj7X6YRQscbyJO9L7e1TksRqLDLxZwiko
6gUhp4/bIs1wDj5tzkQBi4qXviRq3i7A9b2d0QIDAQABAoIBAH8RvK1PmqxfkEeL
W8oVf13OcafgJjRW6NuNkKa5mmAlldFs1gDRvXl7dm7ZE3CjkYqMEw2DXdP+4KSp
0TH9J7zi+A6ThnaZ/QniTcEdu1YUQbcH0kIS/dZec0wyKUNDtrXC5zl2jQY4Jyrj
laOpBzaEDfhvq0p3q2yYrIRSgACpSEVEsfPoHrxtlLhfMkVNe8P0nkQkzdwou5MQ
MZKV4JUopLHLgPH6IXQCqA1wzlU32yZ86w88GFcBVLkwlLJCKbuAo7yxMCD+nzvA
xm5NuF1kzpP0gk+kZRXF+rFEV4av/2kSS+n8IeUBQZrxovLBuQHVDvJXoqcEjmlh
ZUltznUCgYEA4inwieePfb7kh7L/ma5OLLn+uCNwzVw9LayzXT1dyPravOnkHl6h
MgaoTspqDyU8k8pStedRrr5dVYbseni/A4WSMGvi4innqSXBQGp64TyeJy/e+LrS
ypSWQ6RSJkCxI5t8s4mOpR7FMcdE34I5qeA4G5RS1HIacn7Hxc7uXtcCgYEA3Uqn
E7EDfNfYdZm6AikvE6x64oihWI0x47rlkLu6lf6ihiF1dbfaEN+IAaIxQ/unGYwU
130F0TUwarXnVkeBIRlij4fXhExyd7USSQH1VpqmIqDwsS2ojrzQVMo5UcH+A22G
bbHPtwJNmw8a7yzTPWo2/vnjgV2OaXEQ9vCVG5cCgYEAu1kEoihJDGBijSqxY4wp
xBE7OSxamDNtlnV2i6l3FDMBmfaieqnnHDq5l7NDklJFUSQLyhXZ60hUprHDGV0G
1pMCW8wzQSh3d/4HjSXnrsd5N3sHWMHiNeBKbbQkPP3f/2AhN9SebpgDwE2S9xe4
TsmnkOkYiFYRJIFzWaAmhDcCgYEAwxRCgZt0xaPKULG6RpljxOYyVm24PsYKCwYB
xjuYWw5k2/W3BJWVCXblAPuojpPUVTMmVGkErc9D5W6Ch471iOZF+t334cs6xci8
W9v8GeKvPqu+Q5NKmrpctcKoESkA8qik7yLnSCAhpeYFCn/roKJ35QMJyktddhqU
p/yilfUCgYBxZ6YmFjYH6l5SxQdcfa5JQ2To8lZCfRJwB65EyWj4pKH4TaWFS7vb
50WOGTBwJgyhTKLCO3lOmXIUyIwC+OO9xzaeRCBjqEhpup/Ih3MsfMEd6BZRVK5E
IxtmIWba5HQ52k8FKHeRrRB7PSVSADUN2pUFkLudH+j/01kSZyJoLA==
-----END RSA PRIVATE KEY-----


================================================
FILE: tests/_samples/smime/intermediate.crt
================================================
-----BEGIN CERTIFICATE-----
MIIDFjCCAf4CAQEwDQYJKoZIhvcNAQEFBQAwTDEXMBUGA1UEAwwOU3dpZnRtYWls
ZXIgQ0ExFDASBgNVBAoMC1N3aWZ0bWFpbGVyMQ4wDAYDVQQHDAVQYXJpczELMAkG
A1UEBhMCRlIwHhcNMTQxMTIwMTMyNTQxWhcNMTgxMTE5MTMyNTQxWjBWMSEwHwYD
VQQDDBhTd2lmdG1haWxlciBJbnRlcm1lZGlhdGUxFDASBgNVBAoMC1N3aWZ0bWFp
bGVyMQ4wDAYDVQQHDAVQYXJpczELMAkGA1UEBhMCRlIwggEiMA0GCSqGSIb3DQEB
AQUAA4IBDwAwggEKAoIBAQDSgEhftX6f1wV+uqWl4J+zwCn8fHaLZT6GZ0Gs9ThE
4e+4mkLG1rvSEIJon8U0ic8Zph1UGa1Grveh5bgbldHlFxYSsCCyDGgixRvRWNhI
KuO+SxaIZChqqKwVn3aNQ4BZOSo/MjJ/jQyr9BMgMmdxlHR3e1wkkeAkW//sOsfu
xQGF1h9yeQvuu/GbG6K7vHSGOGd5O3G7bftfQ7l78TMqeJ7jV32AdJeuO5MD4dRn
W4CQLTaeribLN0MKn35UdSiFoZxKHqqWcgtl5xcJWPOmq6CsAJ2Eo90kW/BHOrLv
10h6Oan9R1PdXSvSCvVnXY3Kz30zofw305oA/KJk/hVzAgMBAAEwDQYJKoZIhvcN
AQEFBQADggEBABijZ2NNd05Js5VFNr4uyaydam9Yqu/nnrxbPRbAXPlCduydu2Gd
d1ekn3nblMJ87Bc7zVyHdAQD8/AfS1LOKuoWHpTzmlpIL+8T5sbCYG5J1jKdeLkh
7L/UD5v1ACgA33oKtN8GzcrIq8Zp73r0n+c3hFCfDYRSZRCxGyIf3qgU2LBOD0A3
wTff/N8E/p3WaJX9VnuQ7xyRMOubDuqJnlo5YsFv7wjyGOIAz9afZzcEbH6czt/t
g0Xc/kGr/fkAjUu+z3ZfE4247Gut5m3hEVwWkpEEzQo4osX/BEX20Q2nPz9WBq4a
pK3qNNGwAqS4gdE3ihOExMWxAKgr9d2CcU4=
-----END CERTIFICATE-----


================================================
FILE: tests/_samples/smime/intermediate.key
================================================
-----BEGIN RSA PRIVATE KEY-----
MIIEpQIBAAKCAQEA0oBIX7V+n9cFfrqlpeCfs8Ap/Hx2i2U+hmdBrPU4ROHvuJpC
xta70hCCaJ/FNInPGaYdVBmtRq73oeW4G5XR5RcWErAgsgxoIsUb0VjYSCrjvksW
iGQoaqisFZ92jUOAWTkqPzIyf40Mq/QTIDJncZR0d3tcJJHgJFv/7DrH7sUBhdYf
cnkL7rvxmxuiu7x0hjhneTtxu237X0O5e/EzKnie41d9gHSXrjuTA+HUZ1uAkC02
nq4myzdDCp9+VHUohaGcSh6qlnILZecXCVjzpqugrACdhKPdJFvwRzqy79dIejmp
/UdT3V0r0gr1Z12Nys99M6H8N9OaAPyiZP4VcwIDAQABAoIBAQDLJiKyu2XIvKsA
8wCKZY262+mpUjTVso/1BhHL6Zy0XZgMgFORsgrxYB16+zZGzfiguD/1uhIP9Svn
gtt7Q8udW/phbrkfG/okFDYUg7m3bCz+qVjFqGOZC8+Hzq2LB2oGsbSj6L3zexyP
lq4elIZghvUfml4CrQW0EVWbld79/kF7XHABcIOk2+3f63XAQWkjdFNxj5+z6TR0
52Rv7SmRioAsukW9wr77G3Luv/0cEzDFXgGW5s0wO+rJg28smlsIaj+Y0KsptTig
reQvReAT/S5ZxEp4H6WtXQ1WmaliMB0Gcu4TKB0yE8DoTeCePuslo9DqGokXYT66
oqtcVMqBAoGBAPoOL9byNNU/bBNDWSCiq8PqhSjl0M4vYBGqtgMXM4GFOJU+W2nX
YRJbbxoSd/DKjnxEsR6V0vDTDHj4ZSkgmpEmVhEdAiwUwaZ0T8YUaCPhdiAENo5+
zRBWVJcvAC2XKTK1hy5D7Z5vlC32HHygYqitU+JsK4ylvhrdeOcGx5cfAoGBANeB
X0JbeuqBEwwEHZqYSpzmtB+IEiuYc9ARTttHEvIWgCThK4ldAzbXhDUIQy3Hm0sL
PzDA33furNl2WwB+vmOuioYMNjArKrfg689Aim1byg4AHM5XVQcqoDSOABtI55iP
E0hYDe/d4ema2gk1uR/mT4pnLnk2VzRKsHUbP9stAoGBAKjyIuJwPMADnMqbC0Hg
hnrVHejW9TAJlDf7hgQqjdMppmQ3gF3PdjeH7VXJOp5GzOQrKRxIEABEJ74n3Xlf
HO+K3kWrusb7syb6mNd0/DOZ5kyVbCL0iypJmdeXmuAyrFQlj9LzdD1Cl/RBv1d4
qY/bo7xsZzQc24edMU2uJ/XzAoGBAMHChA95iK5HlwR6vtM8kfk4REMFaLDhxV8R
8MCeyp33NQfzm91JT5aDd07nOt9yVGHInuwKveFrKuXq0C9FxZCCYfHcEOyGI0Zo
aBxTfyKMIMMtvriXNM/Yt2oJMndVuUUlfsTQxtcfu/r5S4h0URopTOK3msVI4mcV
sEnaUjORAoGAGDnslKYtROQMXTe4sh6CoJ32J8UZVV9M+8NLus9rO0v/eZ/pIFxo
MXGrrrl51ScqahCQ+DXHzpLvInsdlAJvDP3ymhb7H2xGsyvb3x2YgsLmr1YVOnli
ISbCssno3vZyFU1TDjeEIKqZHc92byHNMjMuhmlaA25g8kb0cCO76EA=
-----END RSA PRIVATE KEY-----


================================================
FILE: tests/_samples/smime/sign.crt
================================================
-----BEGIN CERTIFICATE-----
MIIDFjCCAf4CCQDULaNM+Q+g3DANBgkqhkiG9w0BAQUFADBMMRcwFQYDVQQDDA5T
d2lmdG1haWxlciBDQTEUMBIGA1UECgwLU3dpZnRtYWlsZXIxDjAMBgNVBAcMBVBh
cmlzMQswCQYDVQQGEwJGUjAeFw0xMzExMjcwODM5MTBaFw0xNzExMjYwODM5MTBa
ME4xGTAXBgNVBAMMEFN3aWZ0bWFpbGVyLVVzZXIxFDASBgNVBAoMC1N3aWZ0bWFp
bGVyMQ4wDAYDVQQHDAVQYXJpczELMAkGA1UEBhMCRlIwggEiMA0GCSqGSIb3DQEB
AQUAA4IBDwAwggEKAoIBAQCTe8ZouyjVGgqlljhaswYqLj7icMoHq+Qg13CE+zJg
tl2/UzyPhAd3WWOIvlQ0lu+E/n0bXrS6+q28DrQ3UgJ9BskzzLz15qUO12b92AvG
vLJ+9kKuiM5KXDljOAsXc7/A9UUGwEFA1D0mkeMmkHuiQavAMkzBLha22hGpg/hz
VbE6W9MGna0szd8yh38IY1M5uR+OZ0dG3KbVZb7H3N0OLOP8j8n+4YtAGAW+Onz/
2CGPfZ1kaDMvY/WTZwyGeA4FwCPy1D8tfeswqKnWDB9Sfl8hns5VxnoJ3dqKQHeX
iC4OMfQ0U4CcuM5sVYJZRNNwP7/TeUh3HegnOnuZ1hy9AgMBAAEwDQYJKoZIhvcN
AQEFBQADggEBAAEPjGt98GIK6ecAEat52aG+8UP7TuZaxoH3cbZdhFTafrP8187F
Rk5G3LCPTeA/QIzbHppA4fPAiS07OVSwVCknpTJbtKKn0gmtTZxThacFHF2NlzTH
XxM5bIbkK3jzIF+WattyTSj34UHHfaNAmvmS7Jyq6MhjSDbcQ+/dZ9eo2tF/AmrC
+MBhyH8aUYwKhTOQQh8yC11niziHhGO99FQ4tpuD9AKlun5snHq4uK9AOFe8VhoR
q2CqX5g5v8OAtdlvzhp50IqD4BNOP+JrUxjGLHDG76BZZIK2Ai1eBz+GhRlIQru/
8EhQzd94mdFEPblGbmuD2QXWLFFKLiYOwOc=
-----END CERTIFICATE-----


================================================
FILE: tests/_samples/smime/sign.key
================================================
-----BEGIN RSA PRIVATE KEY-----
MIIEowIBAAKCAQEAk3vGaLso1RoKpZY4WrMGKi4+4nDKB6vkINdwhPsyYLZdv1M8
j4QHd1ljiL5UNJbvhP59G160uvqtvA60N1ICfQbJM8y89ealDtdm/dgLxryyfvZC
rojOSlw5YzgLF3O/wPVFBsBBQNQ9JpHjJpB7okGrwDJMwS4WttoRqYP4c1WxOlvT
Bp2tLM3fMod/CGNTObkfjmdHRtym1WW+x9zdDizj/I/J/uGLQBgFvjp8/9ghj32d
ZGgzL2P1k2cMhngOBcAj8tQ/LX3rMKip1gwfUn5fIZ7OVcZ6Cd3aikB3l4guDjH0
NFOAnLjObFWCWUTTcD+/03lIdx3oJzp7mdYcvQIDAQABAoIBAH2vrw/T6GFrlwU0
twP8q1VJIghCDLpq77hZQafilzU6VTxWyDaaUu6QPDXt1b8Xnjnd02p+1FDAj0zD
zyuR9VLtdIxzf9mj3KiAQ2IzOx3787YlUgCB0CQo4jM/MJyk5RahL1kogLOp7A8x
pr5XxTUq+B6L/0Nmbq8XupOXRyWp53amZ5N8sgWDv4oKh9fqgAhxbSG6KUkTmhYs
DLinWg86Q28pSn+eivf4dehR56YwtTBVguXW3WKO70+GW1RotSrS6e6SSxfKYksZ
a7/J1hCmJkEE3+4C8BpcI0MelgaK66ocN0pOqDF9ByxphARqyD7tYCfoS2P8gi81
XoiZJaECgYEAwqx4AnDX63AANsfKuKVsEQfMSAG47SnKOVwHB7prTAgchTRcDph1
EVOPtJ+4ssanosXzLcN/dCRlvqLEqnKYAOizy3C56CyRguCpO1AGbRpJjRmHTRgA
w8iArhM07HgJ3XLFn99V/0bsPCMxW8dje1ZMjKjoQtDrXRQMtWaVY+UCgYEAwfGi
f0If6z7wJj9gQUkGimWDAg/bxDkvEeh3nSD/PQyNiW0XDclcb3roNPQsal2ZoMwt
f1bwkclw7yUCIZBvXWEkZapjKCdseTp6nglScxr8GAzfN9p5KQl+OS3GzC6xZf6C
BsZQ5ucsHTHsCAi3WbwGK829z9c7x0qRwgwu9/kCgYEAsqwEwYi8Q/RZ3e1lXC9H
jiHwFi6ugc2XMyoJscghbnkLZB54V1UKLUraXFcz97FobnbsCJajxf8Z+uv9QMtI
Q51QV2ow1q0BKHP2HuAF5eD4nK5Phix/lzHRGPO74UUTGNKcG22pylBXxaIvTSMl
ZTABth/YfGqvepBKUbvDZRkCgYB5ykbUCW9H6D8glZ3ZgYU09ag+bD0CzTIs2cH7
j1QZPz/GdBYNF00PyKv3TPpzVRH7cxyDIdJyioB7/M6Iy03T4wPbQBOCjLdGrZ2A
jrQTCngSlkq6pVx+k7KLL57ua8gFF70JihIV3kfKkaX6KZcSJ8vsSAgRc8TbUo2T
wNjh6QKBgDyxw4bG2ULs+LVaHcnp7nizLgRGXJsCkDICjla6y0eCgAnG8fSt8CcG
s5DIfJeVs/NXe/NVNuVrfwsUx0gBOirtFwQStvi5wJnY/maGAyjmgafisNFgAroT
aM5f+wyGPQeGCs7bj7JWY7Nx9lkyuUV7DdKBTZNMOe51K3+PTEL3
-----END RSA PRIVATE KEY-----


================================================
FILE: tests/_samples/smime/sign2.crt
================================================
-----BEGIN CERTIFICATE-----
MIIDGTCCAgECAQEwDQYJKoZIhvcNAQEFBQAwVjEhMB8GA1UEAwwYU3dpZnRtYWls
ZXIgSW50ZXJtZWRpYXRlMRQwEgYDVQQKDAtTd2lmdG1haWxlcjEOMAwGA1UEBwwF
UGFyaXMxCzAJBgNVBAYTAkZSMB4XDTE0MTEyMDEzMjYyNloXDTE4MTExOTEzMjYy
NlowTzEaMBgGA1UEAwwRU3dpZnRtYWlsZXItVXNlcjIxFDASBgNVBAoMC1N3aWZ0
bWFpbGVyMQ4wDAYDVQQHDAVQYXJpczELMAkGA1UEBhMCRlIwggEiMA0GCSqGSIb3
DQEBAQUAA4IBDwAwggEKAoIBAQDbr1m4z/rzFS/DxUUQIhKNx19oAeGYLt3niaEP
twfvBMNB80gMgM9d+XtqrPAMPeY/2C8t5NlChNPKMcR70JBKdmlSH4/aTjaIfWmD
PoZJjvRRXINZgSHNKIt4ZGAN/EPFr19CBisV4iPxzu+lyIbbkaZJ/qtyatlP7m/q
8TnykFRlyxNEveCakpcXeRd3YTFGKWoED+/URhVc0cCPZVjoeSTtPHAYBnC29lG5
VFbq6NBQiyF4tpjOHRarq6G8PtQFH9CpAZg5bPk3bqka9C8mEr5jWfrM4EHtUkTl
CwVLOQRBsz/nMBT27pXZh18GU0hc3geNDN4kqaeqgNBo0mblAgMBAAEwDQYJKoZI
hvcNAQEFBQADggEBAAHDMuv6oxWPsTQWWGWWFIk7QZu3iogMqFuxhhQxg8BE37CT
Vt1mBVEjYGMkWhMSwWBMWuP6yuOZecWtpp6eOie/UKGg1XoW7Y7zq2aQaP7YPug0
8Lgq1jIo7iO2b6gZeMtLiTZrxyte0z1XzS3wy7ZC9mZjYd7QE7mZ+/rzQ0x5zjOp
G8b3msS/yYYJCMN+HtHln++HOGmm6uhvbsHTfvvZvtl7F5vJ5WhGGlUfjhanSEtZ
1RKx+cbgIv1eFOGO1OTuZfEuKdLb0T38d/rjLeI99nVVKEIGtLmX4dj327GHe/D3
aPr2blF2gOvlzkfN9Vz6ZUE2s3rVBeCg2AVseYQ=
-----END CERTIFICATE-----


================================================
FILE: tests/_samples/smime/sign2.key
================================================
-----BEGIN RSA PRIVATE KEY-----
MIIEpAIBAAKCAQEA269ZuM/68xUvw8VFECISjcdfaAHhmC7d54mhD7cH7wTDQfNI
DIDPXfl7aqzwDD3mP9gvLeTZQoTTyjHEe9CQSnZpUh+P2k42iH1pgz6GSY70UVyD
WYEhzSiLeGRgDfxDxa9fQgYrFeIj8c7vpciG25GmSf6rcmrZT+5v6vE58pBUZcsT
RL3gmpKXF3kXd2ExRilqBA/v1EYVXNHAj2VY6Hkk7TxwGAZwtvZRuVRW6ujQUIsh
eLaYzh0Wq6uhvD7UBR/QqQGYOWz5N26pGvQvJhK+Y1n6zOBB7VJE5QsFSzkEQbM/
5zAU9u6V2YdfBlNIXN4HjQzeJKmnqoDQaNJm5QIDAQABAoIBAAM2FvuqnqJ7Bs23
zoCj3t2PsodUr7WHydqemmoeZNFLoocORVlZcK6Q/QrcKE4lgX4hbN8g30QnqOjl
vVeJ/vH3tSZsK7AnQIjSPH6cpV3h5xRhY9IlHxdepltGLFlH/L2hCKVwbaTOP3RD
cCFeQwpmoKWoQV1UzoRqmdw3Vn+DMaUULomLVR9aSW9PnKeFL+tPWShf7GmVISfM
2H6xKw/qT0XAX59ZHA1laxSFVvbV5ZcKrBOFMV407Vzw2d3ojmfEzNsHjUVBXX8j
B5nK1VeJiTVmcoVhnRX7tXESDaZy+Kv38pqOmc8Svn70lDJ35SM2EpWnX39w5LsQ
29NsIUECgYEA/vNKiMfVmmZNQrpcuHQe5adlmz9+I4xJ4wbRzrS7czpbKF0/iaPf
dKoVz67yYHOJCBHTVaXWkElQsq1mkyuFt/cc0ReJXO8709+t+6ULsE50cLQm/HN5
npg3gw0Ls/9dy/cHM5SdVIHMBm9oQ65rXup/dqWC8Dz2cAAOQhIPwx0CgYEA3Jbk
DPdUlrj4sXcE3V/CtmBuK9Xq1xolJt026fYCrle0YhdMKmchRBDCc6BzM+F/vDyC
llPfQu8TDXK40Oan7GbxMdoLqKK9gSIq1dvfG1YMMz8OrBcX8xKe61KFRWd7QSBJ
BcY575NzYHapOHVGnUJ68j8zCow0gfb7q6iK4GkCgYEAz2mUuKSCxYL21hORfUqT
HFjMU7oa38axEa6pn9XvLjZKlRMPruWP1HTPG9ADRa6Yy+TcnrA1V9sdeM+TRKXC
usCiRAU27lF+xccS30gNs1iQaGRX10gGqJzDhK1nWP+nClmlFTSRrn+OQan/FBjh
Jy31lsveM54VC1cwQlY5Vo0CgYEArtjfnLNzFiE55xjq/znHUd4vlYlzItrzddHE
lEBOsbiNH29ODRI/2P7b0uDsT8Q/BoqEC/ohLqHn3TIA8nzRv91880HdGecdBL17
bJZiSv2yn/AshhWsAxzQYMDBKFk05lNb7jrIc3DR9DU6PqketsoaP+f+Yi7t89I8
fD0VD3kCgYAaJCoQshng/ijiHF/RJXLrXXHJSUmaOfbweX/mzFup0YR1LxUjcv85
cxvwc41Y2iI5MwUXyX97/GYKeoobzWZy3XflNWtg04rcInVaPsb/OOFDDqI+MkzT
B4PcCurOmjzcxHMVE34CYvl3YVwWrPb5JO1rYG9T2gKUJnLU6qG4Bw==
-----END RSA PRIVATE KEY-----


================================================
FILE: tests/acceptance/Swift/AttachmentAcceptanceTest.php
================================================
<?php

require_once 'swift_required.php';
require_once __DIR__.'/Mime/AttachmentAcceptanceTest.php';

class Swift_AttachmentAcceptanceTest extends Swift_Mime_AttachmentAcceptanceTest
{
    protected function createAttachment()
    {
        return new Swift_Attachment();
    }
}


================================================
FILE: tests/acceptance/Swift/ByteStream/FileByteStreamAcceptanceTest.php
================================================
<?php

class Swift_ByteStream_FileByteStreamAcceptanceTest extends \PHPUnit\Framework\TestCase
{
    private $testFile;

    protected function setUp()
    {
        $this->testFile = sys_get_temp_dir().'/swift-test-file'.__CLASS__;
        file_put_contents($this->testFile, 'abcdefghijklm');
    }

    protected function tearDown()
    {
        unlink($this->testFile);
    }

    public function testFileDataCanBeRead()
    {
        $file = $this->createFileStream($this->testFile);
        $str = '';
        while (false !== $bytes = $file->read(8192)) {
            $str .= $bytes;
        }
        $this->assertEquals('abcdefghijklm', $str);
    }

    public function testFileDataCanBeReadSequentially()
    {
        $file = $this->createFileStream($this->testFile);
        $this->assertEquals('abcde', $file->read(5));
        $this->assertEquals('fghijklm', $file->read(8));
        $this->assertFalse($file->read(1));
    }

    public function testFilenameIsReturned()
    {
        $file = $this->createFileStream($this->testFile);
        $this->assertEquals($this->testFile, $file->getPath());
    }

    public function testFileCanBeWrittenTo()
    {
        $file = $this->createFileStream($this->testFile, true);
        $file->write('foobar');
        $this->assertEquals('foobar', $file->read(8192));
    }

    public function testReadingFromThenWritingToFile()
    {
        $file = $this->createFileStream($this->testFile, true);
        $file->write('foobar');
        $this->assertEquals('foobar', $file->read(8192));
        $file->write('zipbutton');
        $this->assertEquals('zipbutton', $file->read(8192));
    }

    public function testWritingToFileWithCanonicalization()
    {
        $file = $this->createFileStream($this->testFile, true);
        $file->addFilter($this->createFilter(["\r\n", "\r"], "\n"), 'allToLF');
        $file->write("foo\r\nbar\r");
        $file->write("\nzip\r\ntest\r");
        $file->flushBuffers();
        $this->assertEquals("foo\nbar\nzip\ntest\n", file_get_contents($this->testFile));
    }

    public function testWritingWithFulleMessageLengthOfAMultipleOf8192()
    {
        $file = $this->createFileStream($this->testFile, true);
        $file->addFilter($this->createFilter(["\r\n", "\r"], "\n"), 'allToLF');
        $file->write('');
        $file->flushBuffers();
        $this->assertEquals('', file_get_contents($this->testFile));
    }

    public function testBindingOtherStreamsMirrorsWriteOperations()
    {
        $file = $this->createFileStream($this->testFile, true);
        $is1 = $this->createMockInputStream();
        $is2 = $this->createMockInputStream();

        $is1->expects($this->exactly(2))
            ->method('write')
            ->withConsecutive(
                ['x'],
                ['y']
            );
        $is2->expects($this->exactly(2))
            ->method('write')
            ->withConsecutive(
                ['x'],
                ['y']
            );

        $file->bind($is1);
        $file->bind($is2);

        $file->write('x');
        $file->write('y');
    }

    public function testBindingOtherStreamsMirrorsFlushOperations()
    {
        $file = $this->createFileStream(
            $this->testFile, true
            );
        $is1 = $this->createMockInputStream();
        $is2 = $this->createMockInputStream();

        $is1->expects($this->once())
            ->method('flushBuffers');
        $is2->expects($this->once())
            ->method('flushBuffers');

        $file->bind($is1);
        $file->bind($is2);

        $file->flushBuffers();
    }

    public function testUnbindingStreamPreventsFurtherWrites()
    {
        $file = $this->createFileStream($this->testFile, true);
        $is1 = $this->createMockInputStream();
        $is2 = $this->createMockInputStream();

        $is1->expects($this->exactly(2))
            ->method('write')
            ->withConsecutive(
                ['x'],
                ['y']
            );
        $is2->expects($this->once())
            ->method('write')
            ->with('x');

        $file->bind($is1);
        $file->bind($is2);

        $file->write('x');

        $file->unbind($is2);

        $file->write('y');
    }

    private function createFilter($search, $replace)
    {
        return new Swift_StreamFilters_StringReplacementFilter($search, $replace);
    }

    private function createMockInputStream()
    {
        return $this->getMockBuilder('Swift_InputByteStream')->getMock();
    }

    private function createFileStream($file, $writable = false)
    {
        return new Swift_ByteStream_FileByteStream($file, $writable);
    }
}


================================================
FILE: tests/acceptance/Swift/CharacterReaderFactory/SimpleCharacterReaderFactoryAcceptanceTest.php
================================================
<?php

class Swift_CharacterReaderFactory_SimpleCharacterReaderFactoryAcceptanceTest extends \PHPUnit\Framework\TestCase
{
    private $factory;
    private $prefix = 'Swift_CharacterReader_';

    protected function setUp()
    {
        $this->factory = new Swift_CharacterReaderFactory_SimpleCharacterReaderFactory();
    }

    public function testCreatingUtf8Reader()
    {
        foreach (['utf8', 'utf-8', 'UTF-8', 'UTF8'] as $utf8) {
            $reader = $this->factory->getReaderFor($utf8);
            $this->assertInstanceOf($this->prefix.'Utf8Reader', $reader);
        }
    }

    public function testCreatingIso8859XReaders()
    {
        $charsets = [];
        foreach (range(1, 16) as $number) {
            foreach (['iso', 'iec'] as $body) {
                $charsets[] = $body.'-8859-'.$number;
                $charsets[] = $body.'8859-'.$number;
                $charsets[] = strtoupper($body).'-8859-'.$number;
                $charsets[] = strtoupper($body).'8859-'.$number;
            }
        }

        foreach ($charsets as $charset) {
            $reader = $this->factory->getReaderFor($charset);
            $this->assertInstanceOf($this->prefix.'GenericFixedWidthReader', $reader);
            $this->assertEquals(1, $reader->getInitialByteSize());
        }
    }

    public function testCreatingWindows125XReaders()
    {
        $charsets = [];
        foreach (range(0, 8) as $number) {
            $charsets[] = 'windows-125'.$number;
            $charsets[] = 'windows125'.$number;
            $charsets[] = 'WINDOWS-125'.$number;
            $charsets[] = 'WINDOWS125'.$number;
        }

        foreach ($charsets as $charset) {
            $reader = $this->factory->getReaderFor($charset);
            $this->assertInstanceOf($this->prefix.'GenericFixedWidthReader', $reader);
            $this->assertEquals(1, $reader->getInitialByteSize());
        }
    }

    public function testCreatingCodePageReaders()
    {
        $charsets = [];
        foreach (range(0, 8) as $number) {
            $charsets[] = 'cp-125'.$number;
            $charsets[] = 'cp125'.$number;
            $charsets[] = 'CP-125'.$number;
            $charsets[] = 'CP125'.$number;
        }

        foreach ([437, 737, 850, 855, 857, 858, 860,
            861, 863, 865, 866, 869, ] as $number) {
            $charsets[] = 'cp-'.$number;
            $charsets[] = 'cp'.$number;
            $charsets[] = 'CP-'.$number;
            $charsets[] = 'CP'.$number;
        }

        foreach ($charsets as $charset) {
            $reader = $this->factory->getReaderFor($charset);
            $this->assertInstanceOf($this->prefix.'GenericFixedWidthReader', $reader);
            $this->assertEquals(1, $reader->getInitialByteSize());
        }
    }

    public function testCreatingAnsiReader()
    {
        foreach (['ansi', 'ANSI'] as $ansi) {
            $reader = $this->factory->getReaderFor($ansi);
            $this->assertInstanceOf($this->prefix.'GenericFixedWidthReader', $reader);
            $this->assertEquals(1, $reader->getInitialByteSize());
        }
    }

    public function testCreatingMacintoshReader()
    {
        foreach (['macintosh', 'MACINTOSH'] as $mac) {
            $reader = $this->factory->getReaderFor($mac);
            $this->assertInstanceOf($this->prefix.'GenericFixedWidthReader', $reader);
            $this->assertEquals(1, $reader->getInitialByteSize());
        }
    }

    public function testCreatingKOIReaders()
    {
        $charsets = [];
        foreach (['7', '8-r', '8-u', '8u', '8r'] as $end) {
            $charsets[] = 'koi-'.$end;
            $charsets[] = 'koi'.$end;
            $charsets[] = 'KOI-'.$end;
            $charsets[] = 'KOI'.$end;
        }

        foreach ($charsets as $charset) {
            $reader = $this->factory->getReaderFor($charset);
            $this->assertInstanceOf($this->prefix.'GenericFixedWidthReader', $reader);
            $this->assertEquals(1, $reader->getInitialByteSize());
        }
    }

    public function testCreatingIsciiReaders()
    {
        foreach (['iscii', 'ISCII', 'viscii', 'VISCII'] as $charset) {
            $reader = $this->factory->getReaderFor($charset);
            $this->assertInstanceOf($this->prefix.'GenericFixedWidthReader', $reader);
            $this->assertEquals(1, $reader->getInitialByteSize());
        }
    }

    public function testCreatingMIKReader()
    {
        foreach (['mik', 'MIK'] as $charset) {
            $reader = $this->factory->getReaderFor($charset);
            $this->assertInstanceOf($this->prefix.'GenericFixedWidthReader', $reader);
            $this->assertEquals(1, $reader->getInitialByteSize());
        }
    }

    public function testCreatingCorkReader()
    {
        foreach (['cork', 'CORK', 't1', 'T1'] as $charset) {
            $reader = $this->factory->getReaderFor($charset);
            $this->assertInstanceOf($this->prefix.'GenericFixedWidthReader', $reader);
            $this->assertEquals(1, $reader->getInitialByteSize());
        }
    }

    public function testCreatingUcs2Reader()
    {
        foreach (['ucs-2', 'UCS-2', 'ucs2', 'UCS2'] as $charset) {
            $reader = $this->factory->getReaderFor($charset);
            $this->assertInstanceOf($this->prefix.'GenericFixedWidthReader', $reader);
            $this->assertEquals(2, $reader->getInitialByteSize());
        }
    }

    public function testCreatingUtf16Reader()
    {
        foreach (['utf-16', 'UTF-16', 'utf16', 'UTF16'] as $charset) {
            $reader = $this->factory->getReaderFor($charset);
            $this->assertInstanceOf($this->prefix.'GenericFixedWidthReader', $reader);
            $this->assertEquals(2, $reader->getInitialByteSize());
        }
    }

    public function testCreatingUcs4Reader()
    {
        foreach (['ucs-4', 'UCS-4', 'ucs4', 'UCS4'] as $charset) {
            $reader = $this->factory->getReaderFor($charset);
            $this->assertInstanceOf($this->prefix.'GenericFixedWidthReader', $reader);
            $this->assertEquals(4, $reader->getInitialByteSize());
        }
    }

    public function testCreatingUtf32Reader()
    {
        foreach (['utf-32', 'UTF-32', 'utf32', 'UTF32'] as $charset) {
            $reader = $this->factory->getReaderFor($charset);
            $this->assertInstanceOf($this->prefix.'GenericFixedWidthReader', $reader);
            $this->assertEquals(4, $reader->getInitialByteSize());
        }
    }
}


================================================
FILE: tests/acceptance/Swift/DependencyContainerAcceptanceTest.php
================================================
<?php

require_once 'swift_required.php';

//This is more of a "cross your fingers and hope it works" test!

class Swift_DependencyContainerAcceptanceTest extends PHPUnit\Framework\TestCase
{
    public function testNoLookupsFail()
    {
        $di = Swift_DependencyContainer::getInstance();
        foreach ($di->listItems() as $itemName) {
            try {
                $di->lookup($itemName);
            } catch (Swift_DependencyException $e) {
                $this->fail($e->getMessage());
            }
        }
        // previous loop would fail if there is an issue
        $this->addToAssertionCount(1);
    }
}


================================================
FILE: tests/acceptance/Swift/EmbeddedFileAcceptanceTest.php
================================================
<?php

require_once 'swift_required.php';
require_once __DIR__.'/Mime/EmbeddedFileAcceptanceTest.php';

class Swift_EmbeddedFileAcceptanceTest extends Swift_Mime_EmbeddedFileAcceptanceTest
{
    protected function createEmbeddedFile()
    {
        return new Swift_EmbeddedFile();
    }
}


================================================
FILE: tests/acceptance/Swift/Encoder/Base64EncoderAcceptanceTest.php
================================================
<?php

class Swift_Encoder_Base64EncoderAcceptanceTest extends \PHPUnit\Framework\TestCase
{
    private $samplesDir;
    private $encoder;

    protected function setUp()
    {
        $this->samplesDir = realpath(__DIR__.'/../../../_samples/charsets');
        $this->encoder = new Swift_Encoder_Base64Encoder();
    }

    public function testEncodingAndDecodingSamples()
    {
        $sampleFp = opendir($this->samplesDir);
        while (false !== $encodingDir = readdir($sampleFp)) {
            if ('.' == substr($encodingDir, 0, 1)) {
                continue;
            }

            $sampleDir = $this->samplesDir.'/'.$encodingDir;

            if (is_dir($sampleDir)) {
                $fileFp = opendir($sampleDir);
                while (false !== $sampleFile = readdir($fileFp)) {
                    if ('.' == substr($sampleFile, 0, 1)) {
                        continue;
                    }

                    $text = file_get_contents($sampleDir.'/'.$sampleFile);
                    $encodedText = $this->encoder->encodeString($text);

                    $this->assertEquals(
                        base64_decode($encodedText), $text,
                        '%s: Encoded string should decode back to original string for sample '.
                        $sampleDir.'/'.$sampleFile
                        );
                }
                closedir($fileFp);
            }
        }
        closedir($sampleFp);
    }
}


================================================
FILE: tests/acceptance/Swift/Encoder/QpEncoderAcceptanceTest.php
================================================
<?php

class Swift_Encoder_QpEncoderAcceptanceTest extends \PHPUnit\Framework\TestCase
{
    private $samplesDir;
    private $factory;

    protected function setUp()
    {
        $this->samplesDir = realpath(__DIR__.'/../../../_samples/charsets');
        $this->factory = new Swift_CharacterReaderFactory_SimpleCharacterReaderFactory();
    }

    public function testEncodingAndDecodingSamples()
    {
        $sampleFp = opendir($this->samplesDir);
        while (false !== $encodingDir = readdir($sampleFp)) {
            if ('.' == substr($encodingDir, 0, 1)) {
                continue;
            }

            $encoding = $encodingDir;
            $charStream = new Swift_CharacterStream_ArrayCharacterStream(
                $this->factory, $encoding);
            $encoder = new Swift_Encoder_QpEncoder($charStream);

            $sampleDir = $this->samplesDir.'/'.$encodingDir;

            if (is_dir($sampleDir)) {
                $fileFp = opendir($sampleDir);
                while (false !== $sampleFile = readdir($fileFp)) {
                    if ('.' == substr($sampleFile, 0, 1)) {
                        continue;
                    }

                    $text = file_get_contents($sampleDir.'/'.$sampleFile);
                    $encodedText = $encoder->encodeString($text);

                    foreach (explode("\r\n", $encodedText) as $line) {
                        $this->assertLessThanOrEqual(76, \strlen($line));
                    }

                    $this->assertEquals(
                        quoted_printable_decode($encodedText), $text,
                        '%s: Encoded string should decode back to original string for sample '.
                        $sampleDir.'/'.$sampleFile
                        );
                }
                closedir($fileFp);
            }
        }
        closedir($sampleFp);
    }
}


================================================
FILE: tests/acceptance/Swift/Encoder/Rfc2231EncoderAcceptanceTest.php
================================================
<?php

class Swift_Encoder_Rfc2231EncoderAcceptanceTest extends \PHPUnit\Framework\TestCase
{
    private $samplesDir;
    private $factory;

    protected function setUp()
    {
        $this->samplesDir = realpath(__DIR__.'/../../../_samples/charsets');
        $this->factory = new Swift_CharacterReaderFactory_SimpleCharacterReaderFactory();
    }

    public function testEncodingAndDecodingSamples()
    {
        $sampleFp = opendir($this->samplesDir);
        while (false !== $encodingDir = readdir($sampleFp)) {
            if ('.' == substr($encodingDir, 0, 1)) {
                continue;
            }

            $encoding = $encodingDir;
            $charStream = new Swift_CharacterStream_ArrayCharacterStream(
                $this->factory, $encoding);
            $encoder = new Swift_Encoder_Rfc2231Encoder($charStream);

            $sampleDir = $this->samplesDir.'/'.$encodingDir;

            if (is_dir($sampleDir)) {
                $fileFp = opendir($sampleDir);
                while (false !== $sampleFile = readdir($fileFp)) {
                    if ('.' == substr($sampleFile, 0, 1)) {
                        continue;
                    }

                    $text = file_get_contents($sampleDir.'/'.$sampleFile);
                    $encodedText = $encoder->encodeString($text);

                    $this->assertEquals(
                        urldecode(implode('', explode("\r\n", $encodedText))), $text,
                        '%s: Encoded string should decode back to original string for sample '.
                        $sampleDir.'/'.$sampleFile
                        );
                }
                closedir($fileFp);
            }
        }
        closedir($sampleFp);
    }
}


================================================
FILE: tests/acceptance/Swift/KeyCache/ArrayKeyCacheAcceptanceTest.php
================================================
<?php

class Swift_KeyCache_ArrayKeyCacheAcceptanceTest extends \PHPUnit\Framework\TestCase
{
    private $cache;
    private $key1 = 'key1';
    private $key2 = 'key2';

    protected function setUp()
    {
        $this->cache = new Swift_KeyCache_ArrayKeyCache(
            new Swift_KeyCache_SimpleKeyCacheInputStream()
            );
    }

    public function testStringDataCanBeSetAndFetched()
    {
        $this->cache->setString(
            $this->key1, 'foo', 'test', Swift_KeyCache::MODE_WRITE
            );
        $this->assertEquals('test', $this->cache->getString($this->key1, 'foo'));
    }

    public function testStringDataCanBeOverwritten()
    {
        $this->cache->setString(
            $this->key1, 'foo', 'test', Swift_KeyCache::MODE_WRITE
            );
        $this->cache->setString(
            $this->key1, 'foo', 'whatever', Swift_KeyCache::MODE_WRITE
            );
        $this->assertEquals('whatever', $this->cache->getString($this->key1, 'foo'));
    }

    public function testStringDataCanBeAppended()
    {
        $this->cache->setString(
            $this->key1, 'foo', 'test', Swift_KeyCache::MODE_WRITE
            );
        $this->cache->setString(
            $this->key1, 'foo', 'ing', Swift_KeyCache::MODE_APPEND
            );
        $this->assertEquals('testing', $this->cache->getString($this->key1, 'foo'));
    }

    public function testHasKeyReturnValue()
    {
        $this->assertFalse($this->cache->hasKey($this->key1, 'foo'));
        $this->cache->setString(
            $this->key1, 'foo', 'test', Swift_KeyCache::MODE_WRITE
            );
        $this->assertTrue($this->cache->hasKey($this->key1, 'foo'));
    }

    public function testNsKeyIsWellPartitioned()
    {
        $this->cache->setString(
            $this->key1, 'foo', 'test', Swift_KeyCache::MODE_WRITE
            );
        $this->cache->setString(
            $this->key2, 'foo', 'ing', Swift_KeyCache::MODE_WRITE
            );
        $this->assertEquals('test', $this->cache->getString($this->key1, 'foo'));
        $this->assertEquals('ing', $this->cache->getString($this->key2, 'foo'));
    }

    public function testItemKeyIsWellPartitioned()
    {
        $this->cache->setString(
            $this->key1, 'foo', 'test', Swift_KeyCache::MODE_WRITE
            );
        $this->cache->setString(
            $this->key1, 'bar', 'ing', Swift_KeyCache::MODE_WRITE
            );
        $this->assertEquals('test', $this->cache->getString($this->key1, 'foo'));
        $this->assertEquals('ing', $this->cache->getString($this->key1, 'bar'));
    }

    public function testByteStreamCanBeImported()
    {
        $os = new Swift_ByteStream_ArrayByteStream();
        $os->write('abcdef');

        $this->cache->importFromByteStream(
            $this->key1, 'foo', $os, Swift_KeyCache::MODE_WRITE
            );
        $this->assertEquals('abcdef', $this->cache->getString($this->key1, 'foo'));
    }

    public function testByteStreamCanBeAppended()
    {
        $os1 = new Swift_ByteStream_ArrayByteStream();
        $os1->write('abcdef');

        $os2 = new Swift_ByteStream_ArrayByteStream();
        $os2->write('xyzuvw');

        $this->cache->importFromByteStream(
            $this->key1, 'foo', $os1, Swift_KeyCache::MODE_APPEND
            );
        $this->cache->importFromByteStream(
            $this->key1, 'foo', $os2, Swift_KeyCache::MODE_APPEND
            );

        $this->assertEquals('abcdefxyzuvw', $this->cache->getString($this->key1, 'foo'));
    }

    public function testByteStreamAndStringCanBeAppended()
    {
        $this->cache->setString(
            $this->key1, 'foo', 'test', Swift_KeyCache::MODE_APPEND
            );

        $os = new Swift_ByteStream_ArrayByteStream();
        $os->write('abcdef');

        $this->cache->importFromByteStream(
            $this->key1, 'foo', $os, Swift_KeyCache::MODE_APPEND
            );
        $this->assertEquals('testabcdef', $this->cache->getString($this->key1, 'foo'));
    }

    public function testDataCanBeExportedToByteStream()
    {
        $this->cache->setString(
            $this->key1, 'foo', 'test', Swift_KeyCache::MODE_WRITE
            );

        $is = new Swift_ByteStream_ArrayByteStream();

        $this->cache->exportToByteStream($this->key1, 'foo', $is);

        $string = '';
        while (false !== $bytes = $is->read(8192)) {
            $string .= $bytes;
        }

        $this->assertEquals('test', $string);
    }

    public function testKeyCanBeCleared()
    {
        $this->cache->setString(
            $this->key1, 'foo', 'test', Swift_KeyCache::MODE_WRITE
            );
        $this->assertTrue($this->cache->hasKey($this->key1, 'foo'));
        $this->cache->clearKey($this->key1, 'foo');
        $this->assertFalse($this->cache->hasKey($this->key1, 'foo'));
    }

    public function testNsKeyCanBeCleared()
    {
        $this->cache->setString(
            $this->key1, 'foo', 'test', Swift_KeyCache::MODE_WRITE
            );
        $this->cache->setString(
            $this->key1, 'bar', 'xyz', Swift_KeyCache::MODE_WRITE
            );
        $this->assertTrue($this->cache->hasKey($this->key1, 'foo'));
        $this->assertTrue($this->cache->hasKey($this->key1, 'bar'));
        $this->cache->clearAll($this->key1);
        $this->assertFalse($this->cache->hasKey($this->key1, 'foo'));
        $this->assertFalse($this->cache->hasKey($this->key1, 'bar'));
    }

    public function testKeyCacheInputStream()
    {
        $is = $this->cache->getInputByteStream($this->key1, 'foo');
        $is->write('abc');
        $is->write('xyz');
        $this->assertEquals('abcxyz', $this->cache->getString($this->key1, 'foo'));
    }
}


================================================
FILE: tests/acceptance/Swift/KeyCache/DiskKeyCacheAcceptanceTest.php
================================================
<?php

class Swift_KeyCache_DiskKeyCacheAcceptanceTest extends \PHPUnit\Framework\TestCase
{
    private $cache;
    private $key1;
    private $key2;

    protected function setUp()
    {
        $this->key1 = uniqid(microtime(true), true);
        $this->key2 = uniqid(microtime(true), true);
        $this->cache = new Swift_KeyCache_DiskKeyCache(new Swift_KeyCache_SimpleKeyCacheInputStream(), sys_get_temp_dir());
    }

    public function testStringDataCanBeSetAndFetched()
    {
        $this->cache->setString(
            $this->key1, 'foo', 'test', Swift_KeyCache::MODE_WRITE
            );
        $this->assertEquals('test', $this->cache->getString($this->key1, 'foo'));
    }

    public function testStringDataCanBeOverwritten()
    {
        $this->cache->setString(
            $this->key1, 'foo', 'test', Swift_KeyCache::MODE_WRITE
            );
        $this->cache->setString(
            $this->key1, 'foo', 'whatever', Swift_KeyCache::MODE_WRITE
            );
        $this->assertEquals('whatever', $this->cache->getString($this->key1, 'foo'));
    }

    public function testStringDataCanBeAppended()
    {
        $this->cache->setString(
            $this->key1, 'foo', 'test', Swift_KeyCache::MODE_WRITE
            );
        $this->cache->setString(
            $this->key1, 'foo', 'ing', Swift_KeyCache::MODE_APPEND
            );
        $this->assertEquals('testing', $this->cache->getString($this->key1, 'foo'));
    }

    public function testHasKeyReturnValue()
    {
        $this->assertFalse($this->cache->hasKey($this->key1, 'foo'));
        $this->cache->setString(
            $this->key1, 'foo', 'test', Swift_KeyCache::MODE_WRITE
            );
        $this->assertTrue($this->cache->hasKey($this->key1, 'foo'));
    }

    public function testNsKeyIsWellPartitioned()
    {
        $this->cache->setString(
            $this->key1, 'foo', 'test', Swift_KeyCache::MODE_WRITE
            );
        $this->cache->setString(
            $this->key2, 'foo', 'ing', Swift_KeyCache::MODE_WRITE
            );
        $this->assertEquals('test', $this->cache->getString($this->key1, 'foo'));
        $this->assertEquals('ing', $this->cache->getString($this->key2, 'foo'));
    }

    public function testItemKeyIsWellPartitioned()
    {
        $this->cache->setString(
            $this->key1, 'foo', 'test', Swift_KeyCache::MODE_WRITE
            );
        $this->cache->setString(
            $this->key1, 'bar', 'ing', Swift_KeyCache::MODE_WRITE
            );
        $this->assertEquals('test', $this->cache->getString($this->key1, 'foo'));
        $this->assertEquals('ing', $this->cache->getString($this->key1, 'bar'));
    }

    public function testByteStreamCanBeImported()
    {
        $os = new Swift_ByteStream_ArrayByteStream();
        $os->write('abcdef');

        $this->cache->importFromByteStream(
            $this->key1, 'foo', $os, Swift_KeyCache::MODE_WRITE
            );
        $this->assertEquals('abcdef', $this->cache->getString($this->key1, 'foo'));
    }

    public function testByteStreamCanBeAppended()
    {
        $os1 = new Swift_ByteStream_ArrayByteStream();
        $os1->write('abcdef');

        $os2 = new Swift_ByteStream_ArrayByteStream();
        $os2->write('xyzuvw');

        $this->cache->importFromByteStream(
            $this->key1, 'foo', $os1, Swift_KeyCache::MODE_APPEND
            );
        $this->cache->importFromByteStream(
            $this->key1, 'foo', $os2, Swift_KeyCache::MODE_APPEND
            );

        $this->assertEquals('abcdefxyzuvw', $this->cache->getString($this->key1, 'foo'));
    }

    public function testByteStreamAndStringCanBeAppended()
    {
        $this->cache->setString(
            $this->key1, 'foo', 'test', Swift_KeyCache::MODE_APPEND
            );

        $os = new Swift_ByteStream_ArrayByteStream();
        $os->write('abcdef');

        $this->cache->importFromByteStream(
            $this->key1, 'foo', $os, Swift_KeyCache::MODE_APPEND
            );
        $this->assertEquals('testabcdef', $this->cache->getString($this->key1, 'foo'));
    }

    public function testDataCanBeExportedToByteStream()
    {
        $this->cache->setString(
            $this->key1, 'foo', 'test', Swift_KeyCache::MODE_WRITE
            );

        $is = new Swift_ByteStream_ArrayByteStream();

        $this->cache->exportToByteStream($this->key1, 'foo', $is);

        $string = '';
        while (false !== $bytes = $is->read(8192)) {
            $string .= $bytes;
        }

        $this->assertEquals('test', $string);
    }

    public function testKeyCanBeCleared()
    {
        $this->cache->setString(
            $this->key1, 'foo', 'test', Swift_KeyCache::MODE_WRITE
            );
        $this->assertTrue($this->cache->hasKey($this->key1, 'foo'));
        $this->cache->clearKey($this->key1, 'foo');
        $this->assertFalse($this->cache->hasKey($this->key1, 'foo'));
    }

    public function testNsKeyCanBeCleared()
    {
        $this->cache->setString(
            $this->key1, 'foo', 'test', Swift_KeyCache::MODE_WRITE
            );
        $this->cache->setString(
            $this->key1, 'bar', 'xyz', Swift_KeyCache::MODE_WRITE
            );
        $this->assertTrue($this->cache->hasKey($this->key1, 'foo'));
        $this->assertTrue($this->cache->hasKey($this->key1, 'bar'));
        $this->cache->clearAll($this->key1);
        $this->assertFalse($this->cache->hasKey($this->key1, 'foo'));
        $this->assertFalse($this->cache->hasKey($this->key1, 'bar'));
    }

    public function testKeyCacheInputStream()
    {
        $is = $this->cache->getInputByteStream($this->key1, 'foo');
        $is->write('abc');
        $is->write('xyz');
        $this->assertEquals('abcxyz', $this->cache->getString($this->key1, 'foo'));
    }
}


================================================
FILE: tests/acceptance/Swift/MessageAcceptanceTest.php
================================================
<?php

require_once 'swift_required.php';
require_once __DIR__.'/Mime/SimpleMessageAcceptanceTest.php';

class Swift_MessageAcceptanceTest extends Swift_Mime_SimpleMessageAcceptanceTest
{
    public function testAddPartWrapper()
    {
        $message = $this->createMessage();
        $message->setSubject('just a test subject');
        $message->setFrom([
            'chris.corbyn@swiftmailer.org' => 'Chris Corbyn', ]);

        $id = $message->getId();
        $date = $message->getDate();
        $boundary = $message->getBoundary();

        $message->addPart('foo', 'text/plain', 'iso-8859-1');
        $message->addPart('test <b>foo</b>', 'text/html', 'iso-8859-1');

        $this->assertEquals(
            'Message-ID: <'.$id.'>'."\r\n".
            'Date: '.$date->format('r')."\r\n".
            'Subject: just a test subject'."\r\n".
            'From: Chris Corbyn <chris.corbyn@swiftmailer.org>'."\r\n".
            'MIME-Version: 1.0'."\r\n".
            'Content-Type: multipart/alternative;'."\r\n".
            ' boundary="'.$boundary.'"'."\r\n".
            "\r\n\r\n".
            '--'.$boundary."\r\n".
            'Content-Type: text/plain; charset=iso-8859-1'."\r\n".
            'Content-Transfer-Encoding: quoted-printable'."\r\n".
            "\r\n".
            'foo'.
            "\r\n\r\n".
            '--'.$boundary."\r\n".
            'Content-Type: text/html; charset=iso-8859-1'."\r\n".
            'Content-Transfer-Encoding: quoted-printable'."\r\n".
            "\r\n".
            'test <b>foo</b>'.
            "\r\n\r\n".
            '--'.$boundary.'--'."\r\n",
            $message->toString()
            );
    }

    protected function createMessage()
    {
        Swift_DependencyContainer::getInstance()
            ->register('properties.charset')->asValue(null);

        return new Swift_Message();
    }
}


================================================
FILE: tests/acceptance/Swift/Mime/AttachmentAcceptanceTest.php
================================================
<?php

use Egulias\EmailValidator\EmailValidator;

class Swift_Mime_AttachmentAcceptanceTest extends \PHPUnit\Framework\TestCase
{
    private $contentEncoder;
    private $cache;
    private $headers;
    private $emailValidator;

    protected function setUp()
    {
        $this->cache = new Swift_KeyCache_ArrayKeyCache(
            new Swift_KeyCache_SimpleKeyCacheInputStream()
            );
        $factory = new Swift_CharacterReaderFactory_SimpleCharacterReaderFactory();
        $this->contentEncoder = new Swift_Mime_ContentEncoder_Base64ContentEncoder();

        $headerEncoder = new Swift_Mime_HeaderEncoder_QpHeaderEncoder(
            new Swift_CharacterStream_ArrayCharacterStream($factory, 'utf-8')
            );
        $paramEncoder = new Swift_Encoder_Rfc2231Encoder(
            new Swift_CharacterStream_ArrayCharacterStream($factory, 'utf-8')
            );
        $this->emailValidator = new EmailValidator();
        $this->idGenerator = new Swift_Mime_IdGenerator('example.com');
        $this->headers = new Swift_Mime_SimpleHeaderSet(
            new Swift_Mime_SimpleHeaderFactory($headerEncoder, $paramEncoder, $this->emailValidator)
            );
    }

    public function testDispositionIsSetInHeader()
    {
        $attachment = $this->createAttachment();
        $attachment->setContentType('application/pdf');
        $attachment->setDisposition('inline');
        $this->assertEquals(
            'Content-Type: application/pdf'."\r\n".
            'Content-Transfer-Encoding: base64'."\r\n".
            'Content-Disposition: inline'."\r\n",
            $attachment->toString()
            );
    }

    public function testDispositionIsAttachmentByDefault()
    {
        $attachment = $this->createAttachment();
        $attachment->setContentType('application/pdf');
        $this->assertEquals(
            'Content-Type: application/pdf'."\r\n".
            'Content-Transfer-Encoding: base64'."\r\n".
            'Content-Disposition: attachment'."\r\n",
            $attachment->toString()
            );
    }

    public function testFilenameIsSetInHeader()
    {
        $attachment = $this->createAttachment();
        $attachment->setContentType('application/pdf');
        $attachment->setFilename('foo.pdf');
        $this->assertEquals(
            'Content-Type: application/pdf; name=foo.pdf'."\r\n".
            'Content-Transfer-Encoding: base64'."\r\n".
            'Content-Disposition: attachment; filename=foo.pdf'."\r\n",
            $attachment->toString()
            );
    }

    public function testSizeIsSetInHeader()
    {
        $attachment = $this->createAttachment();
        $attachment->setContentType('application/pdf');
        $attachment->setSize(12340);
        $this->assertEquals(
            'Content-Type: application/pdf'."\r\n".
            'Content-Transfer-Encoding: base64'."\r\n".
            'Content-Disposition: attachment; size=12340'."\r\n",
            $attachment->toString()
            );
    }

    public function testMultipleParametersInHeader()
    {
        $attachment = $this->createAttachment();
        $attachment->setContentType('application/pdf');
        $attachment->setFilename('foo.pdf');
        $attachment->setSize(12340);
        $this->assertEquals(
            'Content-Type: application/pdf; name=foo.pdf'."\r\n".
            'Content-Transfer-Encoding: base64'."\r\n".
            'Content-Disposition: attachment; filename=foo.pdf; size=12340'."\r\n",
            $attachment->toString()
            );
    }

    public function testEndToEnd()
    {
        $attachment = $this->createAttachment();
        $attachment->setContentType('application/pdf');
        $attachment->setFilename('foo.pdf');
        $attachment->setSize(12340);
        $attachment->setBody('abcd');
        $this->assertEquals(
            'Content-Type: application/pdf; name=foo.pdf'."\r\n".
            'Content-Transfer-Encoding: base64'."\r\n".
            'Content-Disposition: attachment; filename=foo.pdf; size=12340'."\r\n".
            "\r\n".
            base64_encode('abcd'),
            $attachment->toString()
            );
    }

    protected function createAttachment()
    {
        $entity = new Swift_Mime_Attachment(
            $this->headers,
            $this->contentEncoder,
            $this->cache,
            $this->idGenerator
            );

        return $entity;
    }
}


================================================
FILE: tests/acceptance/Swift/Mime/ContentEncoder/Base64ContentEncoderAcceptanceTest.php
================================================
<?php

class Swift_Mime_ContentEncoder_Base64ContentEncoderAcceptanceTest extends \PHPUnit\Framework\TestCase
{
    private $samplesDir;
    private $encoder;

    protected function setUp()
    {
        $this->samplesDir = realpath(__DIR__.'/../../../../_samples/charsets');
        $this->encoder = new Swift_Mime_ContentEncoder_Base64ContentEncoder();
    }

    public function testEncodingAndDecodingSamples()
    {
        $sampleFp = opendir($this->samplesDir);
        while (false !== $encodingDir = readdir($sampleFp)) {
            if ('.' == substr($encodingDir, 0, 1)) {
                continue;
            }

            $sampleDir = $this->samplesDir.'/'.$encodingDir;

            if (is_dir($sampleDir)) {
                $fileFp = opendir($sampleDir);
                while (false !== $sampleFile = readdir($fileFp)) {
                    if ('.' == substr($sampleFile, 0, 1)) {
                        continue;
                    }

                    $text = file_get_contents($sampleDir.'/'.$sampleFile);

                    $os = new Swift_ByteStream_ArrayByteStream();
                    $os->write($text);

                    $is = new Swift_ByteStream_ArrayByteStream();

                    $this->encoder->encodeByteStream($os, $is);

                    $encoded = '';
                    while (false !== $bytes = $is->read(8192)) {
                        $encoded .= $bytes;
                    }

                    $this->assertEquals(
                        base64_decode($encoded), $text,
                        '%s: Encoded string should decode back to original string for sample '.
                        $sampleDir.'/'.$sampleFile
                        );
                }
                closedir($fileFp);
            }
        }
        closedir($sampleFp);
    }
}


================================================
FILE: tests/acceptance/Swift/Mime/ContentEncoder/NativeQpContentEncoderAcceptanceTest.php
================================================
<?php

class Swift_Mime_ContentEncoder_NativeQpContentEncoderAcceptanceTest extends \PHPUnit\Framework\TestCase
{
    protected $samplesDir;

    /**
     * @var Swift_Mime_ContentEncoder_NativeQpContentEncoder
     */
    protected $encoder;

    protected function setUp()
    {
        $this->samplesDir = realpath(__DIR__.'/../../../../_samples/charsets');
        $this->encoder = new Swift_Mime_ContentEncoder_NativeQpContentEncoder();
    }

    public function testEncodingAndDecodingSamples()
    {
        $sampleFp = opendir($this->samplesDir);
        while (false !== $encodingDir = readdir($sampleFp)) {
            if ('.' == substr($encodingDir, 0, 1)) {
                continue;
            }

            $sampleDir = $this->samplesDir.'/'.$encodingDir;

            if (is_dir($sampleDir)) {
                $fileFp = opendir($sampleDir);
                while (false !== $sampleFile = readdir($fileFp)) {
                    if ('.' == substr($sampleFile, 0, 1)) {
                        continue;
                    }

                    $text = file_get_contents($sampleDir.'/'.$sampleFile);

                    $os = new Swift_ByteStream_ArrayByteStream();
                    $os->write($text);

                    $is = new Swift_ByteStream_ArrayByteStream();
                    $this->encoder->encodeByteStream($os, $is);

                    $encoded = '';
                    while (false !== $bytes = $is->read(8192)) {
                        $encoded .= $bytes;
                    }

                    $this->assertEquals(
                        quoted_printable_decode($encoded),
                        // CR and LF are converted to CRLF
                        preg_replace('~\r(?!\n)|(?<!\r)\n~', "\r\n", $text),
                        '%s: Encoded string should decode back to original string for sample '.$sampleDir.'/'.$sampleFile
                    );
                }
                closedir($fileFp);
            }
        }
        closedir($sampleFp);
    }

    public function testEncodingAndDecodingSamplesFromDiConfiguredInstance()
    {
        $encoder = $this->createEncoderFromContainer();
        $this->assertSame('=C3=A4=C3=B6=C3=BC=C3=9F', $encoder->encodeString('äöüß'));
    }

    public function testCharsetChangeNotImplemented()
    {
        $this->expectException(\RuntimeException::class);

        $this->encoder->charsetChanged('utf-8');
        $this->encoder->charsetChanged('charset');
        $this->encoder->encodeString('foo');
    }

    public function testGetName()
    {
        $this->assertSame('quoted-printable', $this->encoder->getName());
    }

    private function createEncoderFromContainer()
    {
        return Swift_DependencyContainer::getInstance()
            ->lookup('mime.nativeqpcontentencoder')
            ;
    }
}


================================================
FILE: tests/acceptance/Swift/Mime/ContentEncoder/PlainContentEncoderAcceptanceTest.php
================================================
<?php

class Swift_Mime_ContentEncoder_PlainContentEncoderAcceptanceTest extends \PHPUnit\Framework\TestCase
{
    private $samplesDir;
    private $encoder;

    protected function setUp()
    {
        $this->samplesDir = realpath(__DIR__.'/../../../../_samples/charsets');
        $this->encoder = new Swift_Mime_ContentEncoder_PlainContentEncoder('8bit');
    }

    public function testEncodingAndDecodingSamplesString()
    {
        $sampleFp = opendir($this->samplesDir);
        while (false !== $encodingDir = readdir($sampleFp)) {
            if ('.' == substr($encodingDir, 0, 1)) {
                continue;
            }

            $sampleDir = $this->samplesDir.'/'.$encodingDir;

            if (is_dir($sampleDir)) {
                $fileFp = opendir($sampleDir);
                while (false !== $sampleFile = readdir($fileFp)) {
                    if ('.' == substr($sampleFile, 0, 1)) {
                        continue;
                    }

                    $text = file_get_contents($sampleDir.'/'.$sampleFile);
                    $encodedText = $this->encoder->encodeString($text);

                    $this->assertEquals(
                        $encodedText, $text,
                        '%s: Encoded string should be identical to original string for sample '.
                        $sampleDir.'/'.$sampleFile
                        );
                }
                closedir($fileFp);
            }
        }
        closedir($sampleFp);
    }

    public function testEncodingAndDecodingSamplesByteStream()
    {
        $sampleFp = opendir($this->samplesDir);
        while (false !== $encodingDir = readdir($sampleFp)) {
            if ('.' == substr($encodingDir, 0, 1)) {
                continue;
            }

            $sampleDir = $this->samplesDir.'/'.$encodingDir;

            if (is_dir($sampleDir)) {
                $fileFp = opendir($sampleDir);
                while (false !== $sampleFile = readdir($fileFp)) {
                    if ('.' == substr($sampleFile, 0, 1)) {
                        continue;
                    }

                    $text = file_get_contents($sampleDir.'/'.$sampleFile);

                    $os = new Swift_ByteStream_ArrayByteStream();
                    $os->write($text);

                    $is = new Swift_ByteStream_ArrayByteStream();

                    $this->encoder->encodeByteStream($os, $is);

                    $encoded = '';
                    while (false !== $bytes = $is->read(8192)) {
                        $encoded .= $bytes;
                    }

                    $this->assertEquals(
                        $encoded, $text,
                        '%s: Encoded string should be identical to original string for sample '.
                        $sampleDir.'/'.$sampleFile
                        );
                }
                closedir($fileFp);
            }
        }
        closedir($sampleFp);
    }
}


================================================
FILE: tests/acceptance/Swift/Mime/ContentEncoder/QpContentEncoderAcceptanceTest.php
================================================
<?php

class Swift_Mime_ContentEncoder_QpContentEncoderAcceptanceTest extends \PHPUnit\Framework\TestCase
{
    private $samplesDir;
    private $factory;

    protected function setUp()
    {
        $this->samplesDir = realpath(__DIR__.'/../../../../_samples/charsets');
        $this->factory = new Swift_CharacterReaderFactory_SimpleCharacterReaderFactory();
    }

    protected function tearDown()
    {
        Swift_Preferences::getInstance()->setQPDotEscape(false);
    }

    public function testEncodingAndDecodingSamples()
    {
        $sampleFp = opendir($this->samplesDir);
        while (false !== $encodingDir = readdir($sampleFp)) {
            if ('.' == substr($encodingDir, 0, 1)) {
                continue;
            }

            $encoding = $encodingDir;
            $charStream = new Swift_CharacterStream_NgCharacterStream(
                $this->factory, $encoding);
            $encoder = new Swift_Mime_ContentEncoder_QpContentEncoder($charStream);

            $sampleDir = $this->samplesDir.'/'.$encodingDir;

            if (is_dir($sampleDir)) {
                $fileFp = opendir($sampleDir);
                while (false !== $sampleFile = readdir($fileFp)) {
                    if ('.' == substr($sampleFile, 0, 1)) {
                        continue;
                    }

                    $text = file_get_contents($sampleDir.'/'.$sampleFile);

                    $os = new Swift_ByteStream_ArrayByteStream();
                    $os->write($text);

                    $is = new Swift_ByteStream_ArrayByteStream();
                    $encoder->encodeByteStream($os, $is);

                    $encoded = '';
                    while (false !== $bytes = $is->read(8192)) {
                        $encoded .= $bytes;
                    }

                    $this->assertEquals(
                        quoted_printable_decode($encoded), $text,
                        '%s: Encoded string should decode back to original string for sample '.
                        $sampleDir.'/'.$sampleFile
                        );
                }
                closedir($fileFp);
            }
        }
        closedir($sampleFp);
    }

    public function testEncodingAndDecodingSamplesFromDiConfiguredInstance()
    {
        $sampleFp = opendir($this->samplesDir);
        while (false !== $encodingDir = readdir($sampleFp)) {
            if ('.' == substr($encodingDir, 0, 1)) {
                continue;
            }

            $encoding = $encodingDir;
            $encoder = $this->createEncoderFromContainer();

            $sampleDir = $this->samplesDir.'/'.$encodingDir;

            if (is_dir($sampleDir)) {
                $fileFp = opendir($sampleDir);
                while (false !== $sampleFile = readdir($fileFp)) {
                    if ('.' == substr($sampleFile, 0, 1)) {
                        continue;
                    }

                    $text = file_get_contents($sampleDir.'/'.$sampleFile);

                    $os = new Swift_ByteStream_ArrayByteStream();
                    $os->write($text);

                    $is = new Swift_ByteStream_ArrayByteStream();
                    $encoder->encodeByteStream($os, $is);

                    $encoded = '';
                    while (false !== $bytes = $is->read(8192)) {
                        $encoded .= $bytes;
                    }

                    $this->assertEquals(
                        str_replace("\r\n", "\n", quoted_printable_decode($encoded)), str_replace("\r\n", "\n", $text),
                        '%s: Encoded string should decode back to original string for sample '.
                        $sampleDir.'/'.$sampleFile
                        );
                }
                closedir($fileFp);
            }
        }
        closedir($sampleFp);
    }

    public function testEncodingLFTextWithDiConfiguredInstance()
    {
        $encoder = $this->createEncoderFromContainer();
        $this->assertEquals("a\r\nb\r\nc", $encoder->encodeString("a\nb\nc"));
    }

    public function testEncodingCRTextWithDiConfiguredInstance()
    {
        $encoder = $this->createEncoderFromContainer();
        $this->assertEquals("a\r\nb\r\nc", $encoder->encodeString("a\rb\rc"));
    }

    public function testEncodingLFCRTextWithDiConfiguredInstance()
    {
        $encoder = $this->createEncoderFromContainer();
        $this->assertEquals("a\r\n\r\nb\r\n\r\nc", $encoder->encodeString("a\n\rb\n\rc"));
    }

    public function testEncodingCRLFTextWithDiConfiguredInstance()
    {
        $encoder = $this->createEncoderFromContainer();
        $this->assertEquals("a\r\nb\r\nc", $encoder->encodeString("a\r\nb\r\nc"));
    }

    public function testEncodingDotStuffingWithDiConfiguredInstance()
    {
        // Enable DotEscaping
        Swift_Preferences::getInstance()->setQPDotEscape(true);
        $encoder = $this->createEncoderFromContainer();
        $this->assertEquals("a=2E\r\n=2E\r\n=2Eb\r\nc", $encoder->encodeString("a.\r\n.\r\n.b\r\nc"));
        // Return to default
        Swift_Preferences::getInstance()->setQPDotEscape(false);
        $encoder = $this->createEncoderFromContainer();
        $this->assertEquals("a.\r\n.\r\n.b\r\nc", $encoder->encodeString("a.\r\n.\r\n.b\r\nc"));
    }

    public function testDotStuffingEncodingAndDecodingSamplesFromDiConfiguredInstance()
    {
        // Enable DotEscaping
        Swift_Preferences::getInstance()->setQPDotEscape(true);
        $this->testEncodingAndDecodingSamplesFromDiConfiguredInstance();
    }

    private function createEncoderFromContainer()
    {
        return Swift_DependencyContainer::getInstance()
            ->lookup('mime.qpcontentencoder')
            ;
    }
}


================================================
FILE: tests/acceptance/Swift/Mime/EmbeddedFileAcceptanceTest.php
================================================
<?php

use Egulias\EmailValidator\EmailValidator;

class Swift_Mime_EmbeddedFileAcceptanceTest extends \PHPUnit\Framework\TestCase
{
    private $contentEncoder;
    private $cache;
    private $headers;
    private $emailValidator;

    protected function setUp()
    {
        $this->cache = new Swift_KeyCache_ArrayKeyCache(
            new Swift_KeyCache_SimpleKeyCacheInputStream()
            );
        $factory = new Swift_CharacterReaderFactory_SimpleCharacterReaderFactory();
        $this->contentEncoder = new Swift_Mime_ContentEncoder_Base64ContentEncoder();

        $headerEncoder = new Swift_Mime_HeaderEncoder_QpHeaderEncoder(
            new Swift_CharacterStream_ArrayCharacterStream($factory, 'utf-8')
            );
        $paramEncoder = new Swift_Encoder_Rfc2231Encoder(
            new Swift_CharacterStream_ArrayCharacterStream($factory, 'utf-8')
            );
        $this->emailValidator = new EmailValidator();
        $this->idGenerator = new Swift_Mime_IdGenerator('example.com');
        $this->headers = new Swift_Mime_SimpleHeaderSet(
            new Swift_Mime_SimpleHeaderFactory($headerEncoder, $paramEncoder, $this->emailValidator)
            );
    }

    public function testContentIdIsSetInHeader()
    {
        $file = $this->createEmbeddedFile();
        $file->setContentType('application/pdf');
        $file->setId('foo@bar');
        $this->assertEquals(
            'Content-Type: application/pdf'."\r\n".
            'Content-Transfer-Encoding: base64'."\r\n".
            'Content-ID: <foo@bar>'."\r\n".
            'Content-Disposition: inline'."\r\n",
            $file->toString()
            );
    }

    public function testDispositionIsSetInHeader()
    {
        $file = $this->createEmbeddedFile();
        $id = $file->getId();
        $file->setContentType('application/pdf');
        $file->setDisposition('attachment');
        $this->assertEquals(
            'Content-Type: application/pdf'."\r\n".
            'Content-Transfer-Encoding: base64'."\r\n".
            'Content-ID: <'.$id.'>'."\r\n".
            'Content-Disposition: attachment'."\r\n",
            $file->toString()
            );
    }

    public function testFilenameIsSetInHeader()
    {
        $file = $this->createEmbeddedFile();
        $id = $file->getId();
        $file->setContentType('application/pdf');
        $file->setFilename('foo.pdf');
        $this->assertEquals(
            'Content-Type: application/pdf; name=foo.pdf'."\r\n".
            'Content-Transfer-Encoding: base64'."\r\n".
            'Content-ID: <'.$id.'>'."\r\n".
            'Content-Disposition: inline; filename=foo.pdf'."\r\n",
            $file->toString()
            );
    }

    public function testSizeIsSetInHeader()
    {
        $file = $this->createEmbeddedFile();
        $id = $file->getId();
        $file->setContentType('application/pdf');
        $file->setSize(12340);
        $this->assertEquals(
            'Content-Type: application/pdf'."\r\n".
            'Content-Transfer-Encoding: base64'."\r\n".
            'Content-ID: <'.$id.'>'."\r\n".
            'Content-Disposition: inline; size=12340'."\r\n",
            $file->toString()
            );
    }

    public function testMultipleParametersInHeader()
    {
        $file = $this->createEmbeddedFile();
        $id = $file->getId();
        $file->setContentType('application/pdf');
        $file->setFilename('foo.pdf');
        $file->setSize(12340);

        $this->assertEquals(
            'Content-Type: application/pdf; name=foo.pdf'."\r\n".
            'Content-Transfer-Encoding: base64'."\r\n".
            'Content-ID: <'.$id.'>'."\r\n".
            'Content-Disposition: inline; filename=foo.pdf; size=12340'."\r\n",
            $file->toString()
            );
    }

    public function testEndToEnd()
    {
        $file = $this->createEmbeddedFile();
        $id = $file->getId();
        $file->setContentType('application/pdf');
        $file->setFilename('foo.pdf');
        $file->setSize(12340);
        $file->setBody('abcd');
        $this->assertEquals(
            'Content-Type: application/pdf; name=foo.pdf'."\r\n".
            'Content-Transfer-Encoding: base64'."\r\n".
            'Content-ID: <'.$id.'>'."\r\n".
            'Content-Disposition: inline; filename=foo.pdf; size=12340'."\r\n".
            "\r\n".
            base64_encode('abcd'),
            $file->toString()
            );
    }

    protected function createEmbeddedFile()
    {
        $entity = new Swift_Mime_EmbeddedFile(
            $this->headers,
            $this->contentEncoder,
            $this->cache,
            $this->idGenerator
            );

        return $entity;
    }
}


================================================
FILE: tests/acceptance/Swift/Mime/HeaderEncoder/Base64HeaderEncoderAcceptanceTest.php
================================================
<?php

class Swift_Mime_HeaderEncoder_Base64HeaderEncoderAcceptanceTest extends \PHPUnit\Framework\TestCase
{
    private $encoder;

    protected function setUp()
    {
        $this->encoder = new Swift_Mime_HeaderEncoder_Base64HeaderEncoder();
    }

    public function testEncodingJIS()
    {
        if (\function_exists('mb_convert_encoding')) {
            // base64_encode and split cannot handle long JIS text to fold
            $subject = '長い長い長い長い長い長い長い長い長い長い長い長い長い長い長い長い長い長い長い長い件名';

            $encodedWrapperLength = \strlen('=?iso-2022-jp?'.$this->encoder->getName().'??=');

            $old = mb_internal_encoding();
            mb_internal_encoding('utf-8');
            $newstring = mb_encode_mimeheader($subject, 'iso-2022-jp', 'B', "\r\n");
            mb_internal_encoding($old);

            $encoded = $this->encoder->encodeString($subject, 0, 75 - $encodedWrapperLength, 'iso-2022-jp');
            $this->assertEquals(
                $encoded, $newstring,
                'Encoded string should decode back to original string for sample '
            );
        }
    }
}


================================================
FILE: tests/acceptance/Swift/Mime/MimePartAcceptanceTest.php
================================================
<?php

use Egulias\EmailValidator\EmailValidator;

class Swift_Mime_MimePartAcceptanceTest extends \PHPUnit\Framework\TestCase
{
    private $contentEncoder;
    private $cache;
    private $headers;
    private $emailValidator;

    protected function setUp()
    {
        $this->cache = new Swift_KeyCache_ArrayKeyCache(
            new Swift_KeyCache_SimpleKeyCacheInputStream()
            );
        $factory = new Swift_CharacterReaderFactory_SimpleCharacterReaderFactory();
        $this->contentEncoder = new Swift_Mime_ContentEncoder_QpContentEncoder(
            new Swift_CharacterStream_ArrayCharacterStream($factory, 'utf-8'),
            new Swift_StreamFilters_ByteArrayReplacementFilter(
                [[0x0D, 0x0A], [0x0D], [0x0A]],
                [[0x0A], [0x0A], [0x0D, 0x0A]]
                )
            );

        $headerEncoder = new Swift_Mime_HeaderEncoder_QpHeaderEncoder(
            new Swift_CharacterStream_ArrayCharacterStream($factory, 'utf-8')
            );
        $paramEncoder = new Swift_Encoder_Rfc2231Encoder(
            new Swift_CharacterStream_ArrayCharacterStream($factory, 'utf-8')
            );
        $this->emailValidator = new EmailValidator();
        $this->idGenerator = new Swift_Mime_IdGenerator('example.com');
        $this->headers = new Swift_Mime_SimpleHeaderSet(
            new Swift_Mime_SimpleHeaderFactory($headerEncoder, $paramEncoder, $this->emailValidator)
            );
    }

    public function testCharsetIsSetInHeader()
    {
        $part = $this->createMimePart();
        $part->setContentType('text/plain');
        $part->setCharset('utf-8');
        $part->setBody('foobar');
        $this->assertEquals(
            'Content-Type: text/plain; charset=utf-8'."\r\n".
            'Content-Transfer-Encoding: quoted-printable'."\r\n".
            "\r\n".
            'foobar',
            $part->toString()
            );
    }

    public function testFormatIsSetInHeaders()
    {
        $part = $this->createMimePart();
        $part->setContentType('text/plain');
        $part->setFormat('flowed');
        $part->setBody('> foobar');
        $this->assertEquals(
            'Content-Type: text/plain; format=flowed'."\r\n".
            'Content-Transfer-Encoding: quoted-printable'."\r\n".
            "\r\n".
            '> foobar',
            $part->toString()
            );
    }

    public function testDelSpIsSetInHeaders()
    {
        $part = $this->createMimePart();
        $part->setContentType('text/plain');
        $part->setDelSp(true);
        $part->setBody('foobar');
        $this->assertEquals(
            'Content-Type: text/plain; delsp=yes'."\r\n".
            'Content-Transfer-Encoding: quoted-printable'."\r\n".
            "\r\n".
            'foobar',
            $part->toString()
            );
    }

    public function testAll3ParamsInHeaders()
    {
        $part = $this->createMimePart();
        $part->setContentType('text/plain');
        $part->setCharset('utf-8');
        $part->setFormat('fixed');
        $part->setDelSp(true);
        $part->setBody('foobar');
        $this->assertEquals(
            'Content-Type: text/plain; charset=utf-8; format=fixed; delsp=yes'."\r\n".
            'Content-Transfer-Encoding: quoted-printable'."\r\n".
            "\r\n".
            'foobar',
            $part->toString()
            );
    }

    public function testBodyIsCanonicalized()
    {
        $part = $this->createMimePart();
        $part->setContentType('text/plain');
        $part->setCharset('utf-8');
        $part->setBody("foobar\r\rtest\ning\r");
        $this->assertEquals(
            'Content-Type: text/plain; charset=utf-8'."\r\n".
            'Content-Transfer-Encoding: quoted-printable'."\r\n".
            "\r\n".
            "foobar\r\n".
            "\r\n".
            "test\r\n".
            "ing\r\n",
            $part->toString()
            );
    }

    protected function createMimePart()
    {
        $entity = new Swift_Mime_MimePart(
            $this->headers,
            $this->contentEncoder,
            $this->cache,
            $this->idGenerator
        );

        return $entity;
    }
}


================================================
FILE: tests/acceptance/Swift/Mime/SimpleMessageAcceptanceTest.php
================================================
<?php

class Swift_Mime_SimpleMessageAcceptanceTest extends \PHPUnit\Framework\TestCase
{
    protected function setUp()
    {
        Swift_Preferences::getInstance()->setCharset(null); //TODO: Test with the charset defined
    }

    public function testBasicHeaders()
    {
        /* -- RFC 2822, 3.6.
     */

        $message = $this->createMessage();
        $id = $message->getId();
        $date = $message->getDate();
        $this->assertEquals(
            'Message-ID: <'.$id.'>'."\r\n".
            'Date: '.$date->format('r')."\r\n".
            'From: '."\r\n".
            'MIME-Version: 1.0'."\r\n".
            'Content-Type: text/plain'."\r\n".
            'Content-Transfer-Encoding: quoted-printable'."\r\n",
            $message->toString(),
            '%s: Only required headers, and non-empty headers should be displayed'
            );
    }

    public function testSubjectIsDisplayedIfSet()
    {
        $message = $this->createMessage();
        $message->setSubject('just a test subject');
        $id = $message->getId();
        $date = $message->getDate();
        $this->assertEquals(
            'Message-ID: <'.$id.'>'."\r\n".
            'Date: '.$date->format('r')."\r\n".
            'Subject: just a test subject'."\r\n".
            'From: '."\r\n".
            'MIME-Version: 1.0'."\r\n".
            'Content-Type: text/plain'."\r\n".
            'Content-Transfer-Encoding: quoted-printable'."\r\n",
            $message->toString()
            );
    }

    public function testDateCanBeSet()
    {
        $message = $this->createMessage();
        $message->setSubject('just a test subject');
        $id = $message->getId();
        $date = new DateTimeImmutable();
        $message->setDate($date);
        $this->assertEquals(
            'Message-ID: <'.$id.'>'."\r\n".
            'Date: '.$date->format('r')."\r\n".
            'Subject: just a test subject'."\r\n".
            'From: '."\r\n".
            'MIME-Version: 1.0'."\r\n".
            'Content-Type: text/plain'."\r\n".
            'Content-Transfer-Encoding: quoted-printable'."\r\n",
            $message->toString()
            );
    }

    public function testMessageIdCanBeSet()
    {
        $message = $this->createMessage();
        $message->setSubject('just a test subject');
        $message->setId('foo@bar');
        $date = $message->getDate();
        $this->assertEquals(
            'Message-ID: <foo@bar>'."\r\n".
            'Date: '.$date->format('r')."\r\n".
            'Subject: just a test subject'."\r\n".
            'From: '."\r\n".
            'MIME-Version: 1.0'."\r\n".
            'Content-Type: text/plain'."\r\n".
            'Content-Transfer-Encoding: quoted-printable'."\r\n",
            $message->toString()
            );
    }

    public function testContentTypeCanBeChanged()
    {
        $message = $this->createMessage();
        $message->setSubject('just a test subject');
        $message->setContentType('text/html');
        $id = $message->getId();
        $date = $message->getDate();
        $this->assertEquals(
            'Message-ID: <'.$id.'>'."\r\n".
            'Date: '.$date->format('r')."\r\n".
            'Subject: just a test subject'."\r\n".
            'From: '."\r\n".
            'MIME-Version: 1.0'."\r\n".
            'Content-Type: text/html'."\r\n".
            'Content-Transfer-Encoding: quoted-printable'."\r\n",
            $message->toString()
            );
    }

    public function testCharsetCanBeSet()
    {
        $message = $this->createMessage();
        $message->setSubject('just a test subject');
        $message->setContentType('text/html');
        $message->setCharset('iso-8859-1');
        $id = $message->getId();
        $date = $message->getDate();
        $this->assertEquals(
            'Message-ID: <'.$id.'>'."\r\n".
            'Date: '.$date->format('r')."\r\n".
            'Subject: just a test subject'."\r\n".
            'From: '."\r\n".
            'MIME-Version: 1.0'."\r\n".
            'Content-Type: text/html; charset=iso-8859-1'."\r\n".
            'Content-Transfer-Encoding: quoted-printable'."\r\n",
            $message->toString()
            );
    }

    public function testFormatCanBeSet()
    {
        $message = $this->createMessage();
        $message->setSubject('just a test subject');
        $message->setFormat('flowed');
        $id = $message->getId();
        $date = $message->getDate();
        $this->assertEquals(
            'Message-ID: <'.$id.'>'."\r\n".
            'Date: '.$date->format('r')."\r\n".
            'Subject: just a test subject'."\r\n".
            'From: '."\r\n".
            'MIME-Version: 1.0'."\r\n".
            'Content-Type: text/plain; format=flowed'."\r\n".
            'Content-Transfer-Encoding: quoted-printable'."\r\n",
            $message->toString()
            );
    }

    public function testEncoderCanBeSet()
    {
        $message = $this->createMessage();
        $message->setSubject('just a test subject');
        $message->setContentType('text/html');
        $message->setEncoder(
            new Swift_Mime_ContentEncoder_PlainContentEncoder('7bit')
            );
        $id = $message->getId();
        $date = $message->getDate();
        $this->assertEquals(
            'Message-ID: <'.$id.'>'."\r\n".
            'Date: '.$date->format('r')."\r\n".
            'Subject: just a test subject'."\r\n".
            'From: '."\r\n".
            'MIME-Version: 1.0'."\r\n".
            'Content-Type: text/html'."\r\n".
            'Content-Transfer-Encoding: 7bit'."\r\n",
            $message->toString()
            );
    }

    public function testFromAddressCanBeSet()
    {
        $message = $this->createMessage();
        $message->setSubject('just a test subject');
        $message->setFrom('chris.corbyn@swiftmailer.org');
        $id = $message->getId();
        $date = $message->getDate();
        $this->assertEquals(
            'Message-ID: <'.$id.'>'."\r\n".
            'Date: '.$date->format('r')."\r\n".
            'Subject: just a test subject'."\r\n".
            'From: chris.corbyn@swiftmailer.org'."\r\n".
            'MIME-Version: 1.0'."\r\n".
            'Content-Type: text/plain'."\r\n".
            'Content-Transfer-Encoding: quoted-printable'."\r\n",
            $message->toString()
            );
    }

    public function testFromAddressCanBeSetWithName()
    {
        $message = $this->createMessage();
        $message->setSubject('just a test subject');
        $message->setFrom(['chris.corbyn@swiftmailer.org' => 'Chris Corbyn']);
        $id = $message->getId();
        $date = $message->getDate();
        $this->assertEquals(
            'Message-ID: <'.$id.'>'."\r\n".
            'Date: '.$date->format('r')."\r\n".
            'Subject: just a test subject'."\r\n".
            'From: Chris Corbyn <chris.corbyn@swiftmailer.org>'."\r\n".
            'MIME-Version: 1.0'."\r\n".
            'Content-Type: text/plain'."\r\n".
            'Content-Transfer-Encoding: quoted-printable'."\r\n",
            $message->toString()
            );
    }

    public function testMultipleFromAddressesCanBeSet()
    {
        $message = $this->createMessage();
        $message->setSubject('just a test subject');
        $message->setFrom([
            'chris.corbyn@swiftmailer.org' => 'Chris Corbyn',
            'mark@swiftmailer.org',
            ]);
        $id = $message->getId();
        $date = $message->getDate();
        $this->assertEquals(
            'Message-ID: <'.$id.'>'."\r\n".
            'Date: '.$date->format('r')."\r\n".
            'Subject: just a test subject'."\r\n".
            'From: Chris Corbyn <chris.corbyn@swiftmailer.org>, mark@swiftmailer.org'."\r\n".
            'MIME-Version: 1.0'."\r\n".
            'Content-Type: text/plain'."\r\n".
            'Content-Transfer-Encoding: quoted-printable'."\r\n",
            $message->toString()
            );
    }

    public function testReturnPathAddressCanBeSet()
    {
        $message = $this->createMessage();
        $message->setReturnPath('chris@w3style.co.uk');
        $message->setSubject('just a test subject');
        $message->setFrom([
            'chris.corbyn@swiftmailer.org' => 'Chris Corbyn', ]);
        $id = $message->getId();
        $date = $message->getDate();
        $this->assertEquals(
            'Return-Path: <chris@w3style.co.uk>'."\r\n".
            'Message-ID: <'.$id.'>'."\r\n".
            'Date: '.$date->format('r')."\r\n".
            'Subject: just a test subject'."\r\n".
            'From: Chris Corbyn <chris.corbyn@swiftmailer.org>'."\r\n".
            'MIME-Version: 1.0'."\r\n".
            'Content-Type: text/plain'."\r\n".
            'Content-Transfer-Encoding: quoted-printable'."\r\n",
            $message->toString()
            );
    }

    public function testEmptyReturnPathHeaderCanBeUsed()
    {
        $message = $this->createMessage();
        $message->setReturnPath('');
        $message->setSubject('just a test subject');
        $message->setFrom([
            'chris.corbyn@swiftmailer.org' => 'Chris Corbyn', ]);
        $id = $message->getId();
        $date = $message->getDate();
        $this->assertEquals(
            'Return-Path: <>'."\r\n".
            'Message-ID: <'.$id.'>'."\r\n".
            'Date: '.$date->format('r')."\r\n".
            'Subject: just a test subject'."\r\n".
            'From: Chris Corbyn <chris.corbyn@swiftmailer.org>'."\r\n".
            'MIME-Version: 1.0'."\r\n".
            'Content-Type: text/plain'."\r\n".
            'Content-Transfer-Encoding: quoted-printable'."\r\n",
            $message->toString()
            );
    }

    public function testSenderCanBeSet()
    {
        $message = $this->createMessage();
        $message->setSubject('just a test subject');
        $message->setSender('chris.corbyn@swiftmailer.org');
        $id = $message->getId();
        $date = $message->getDate();
        $this->assertEquals(
            'Sender: chris.corbyn@swiftmailer.org'."\r\n".
            'Message-ID: <'.$id.'>'."\r\n".
            'Date: '.$date->format('r')."\r\n".
            'Subject: just a test subject'."\r\n".
            'From: '."\r\n".
            'MIME-Version: 1.0'."\r\n".
            'Content-Type: text/plain'."\r\n".
            'Content-Transfer-Encoding: quoted-printable'."\r\n",
            $message->toString()
            );
    }

    public function testSenderCanBeSetWithName()
    {
        $message = $this->createMessage();
        $message->setSubject('just a test subject');
        $message->setSender(['chris.corbyn@swiftmailer.org' => 'Chris']);
        $id = $message->getId();
        $date = $message->getDate();
        $this->assertEquals(
            'Sender: Chris <chris.corbyn@swiftmailer.org>'."\r\n".
            'Message-ID: <'.$id.'>'."\r\n".
            'Date: '.$date->format('r')."\r\n".
            'Subject: just a test subject'."\r\n".
            'From: '."\r\n".
            'MIME-Version: 1.0'."\r\n".
            'Content-Type: text/plain'."\r\n".
            'Content-Transfer-Encoding: quoted-printable'."\r\n",
            $message->toString()
            );
    }

    public function testReplyToCanBeSet()
    {
        $message = $this->createMessage();
        $message->setSubject('just a test subject');
        $message->setFrom(['chris.corbyn@swiftmailer.org' => 'Chris']);
        $message->setReplyTo(['chris@w3style.co.uk' => 'Myself']);
        $id = $message->getId();
        $date = $message->getDate();
        $this->assertEquals(
            'Message-ID: <'.$id.'>'."\r\n".
            'Date: '.$date->format('r')."\r\n".
            'Subject: just a test subject'."\r\n".
            'From: Chris <chris.corbyn@swiftmailer.org>'."\r\n".
            'Reply-To: Myself <chris@w3style.co.uk>'."\r\n".
            'MIME-Version: 1.0'."\r\n".
            'Content-Type: text/plain'."\r\n".
            'Content-Transfer-Encoding: quoted-printable'."\r\n",
            $message->toString()
            );
    }

    public function testMultipleReplyAddressCanBeUsed()
    {
        $message = $this->createMessage();
        $message->setSubject('just a test subject');
        $message->setFrom(['chris.corbyn@swiftmailer.org' => 'Chris']);
        $message->setReplyTo([
            'chris@w3style.co.uk' => 'Myself',
            'my.other@address.com' => 'Me',
            ]);
        $id = $message->getId();
        $date = $message->getDate();
        $this->assertEquals(
            'Message-ID: <'.$id.'>'."\r\n".
            'Date: '.$date->format('r')."\r\n".
            'Subject: just a test subject'."\r\n".
            'From: Chris <chris.corbyn@swiftmailer.org>'."\r\n".
            'Reply-To: Myself <chris@w3style.co.uk>, Me <my.other@address.com>'."\r\n".
            'MIME-Version: 1.0'."\r\n".
            'Content-Type: text/plain'."\r\n".
            'Content-Transfer-Encoding: quoted-printable'."\r\n",
            $message->toString()
            );
    }

    public function testToAddressCanBeSet()
    {
        $message = $this->createMessage();
        $message->setSubject('just a test subject');
        $message->setFrom(['chris.corbyn@swiftmailer.org' => 'Chris']);
        $message->setReplyTo([
            'chris@w3style.co.uk' => 'Myself',
            'my.other@address.com' => 'Me',
            ]);
        $message->setTo('mark@swiftmailer.org');
        $id = $message->getId();
        $date = $message->getDate();
        $this->assertEquals(
            'Message-ID: <'.$id.'>'."\r\n".
            'Date: '.$date->format('r')."\r\n".
            'Subject: just a test subject'."\r\n".
            'From: Chris <chris.corbyn@swiftmailer.org>'."\r\n".
            'Reply-To: Myself <chris@w3style.co.uk>, Me <my.other@address.com>'."\r\n".
            'To: mark@swiftmailer.org'."\r\n".
            'MIME-Version: 1.0'."\r\n".
            'Content-Type: text/plain'."\r\n".
            'Content-Transfer-Encoding: quoted-printable'."\r\n",
            $message->toString()
            );
    }

    public function testMultipleToAddressesCanBeSet()
    {
        $message = $this->createMessage();
        $message->setSubject('just a test subject');
        $message->setFrom(['chris.corbyn@swiftmailer.org' => 'Chris']);
        $message->setReplyTo([
            'chris@w3style.co.uk' => 'Myself',
            'my.other@address.com' => 'Me',
            ]);
        $message->setTo([
            'mark@swiftmailer.org', 'chris@swiftmailer.org' => 'Chris Corbyn',
            ]);
        $id = $message->getId();
        $date = $message->getDate();
        $this->assertEquals(
            'Message-ID: <'.$id.'>'."\r\n".
            'Date: '.$date->format('r')."\r\n".
            'Subject: just a test subject'."\r\n".
            'From: Chris <chris.corbyn@swiftmailer.org>'."\r\n".
            'Reply-To: Myself <chris@w3style.co.uk>, Me <my.other@address.com>'."\r\n".
            'To: mark@swiftmailer.org, Chris Corbyn <chris@swiftmailer.org>'."\r\n".
            'MIME-Version: 1.0'."\r\n".
            'Content-Type: text/plain'."\r\n".
            'Content-Transfer-Encoding: quoted-printable'."\r\n",
            $message->toString()
            );
    }

    public function testCcAddressCanBeSet()
    {
        $message = $this->createMessage();
        $message->setSubject('just a test subject');
        $message->setFrom(['chris.corbyn@swiftmailer.org' => 'Chris']);
        $message->setReplyTo([
            'chris@w3style.co.uk' => 'Myself',
            'my.other@address.com' => 'Me',
            ]);
        $message->setTo([
            'mark@swiftmailer.org', 'chris@swiftmailer.org' => 'Chris Corbyn',
            ]);
        $message->setCc('john@some-site.com');
        $id = $message->getId();
        $date = $message->getDate();
        $this->assertEquals(
            'Message-ID: <'.$id.'>'."\r\n".
            'Date: '.$date->format('r')."\r\n".
            'Subject: just a test subject'."\r\n".
            'From: Chris <chris.corbyn@swiftmailer.org>'."\r\n".
            'Reply-To: Myself <chris@w3style.co.uk>, Me <my.other@address.com>'."\r\n".
            'To: mark@swiftmailer.org, Chris Corbyn <chris@swiftmailer.org>'."\r\n".
            'Cc: john@some-site.com'."\r\n".
            'MIME-Version: 1.0'."\r\n".
            'Content-Type: text/plain'."\r\n".
            'Content-Transfer-Encoding: quoted-printable'."\r\n",
            $message->toString()
            );
    }

    public function testMultipleCcAddressesCanBeSet()
    {
        $message = $this->createMessage();
        $message->setSubject('just a test subject');
        $message->setFrom(['chris.corbyn@swiftmailer.org' => 'Chris']);
        $message->setReplyTo([
            'chris@w3style.co.uk' => 'Myself',
            'my.other@address.com' => 'Me',
            ]);
        $message->setTo([
            'mark@swiftmailer.org', 'chris@swiftmailer.org' => 'Chris Corbyn',
            ]);
        $message->setCc([
            'john@some-site.com' => 'John West',
            'fred@another-site.co.uk' => 'Big Fred',
            ]);
        $id = $message->getId();
        $date = $message->getDate();
        $this->assertEquals(
            'Message-ID: <'.$id.'>'."\r\n".
            'Date: '.$date->format('r')."\r\n".
            'Subject: just a test subject'."\r\n".
            'From: Chris <chris.corbyn@swiftmailer.org>'."\r\n".
            'Reply-To: Myself <chris@w3style.co.uk>, Me <my.other@address.com>'."\r\n".
            'To: mark@swiftmailer.org, Chris Corbyn <chris@swiftmailer.org>'."\r\n".
            'Cc: John West <john@some-site.com>, Big Fred <fred@another-site.co.uk>'."\r\n".
            'MIME-Version: 1.0'."\r\n".
            'Content-Type: text/plain'."\r\n".
            'Content-Transfer-Encoding: quoted-printable'."\r\n",
            $message->toString()
            );
    }

    public function testBccAddressCanBeSet()
    {
        //Obviously Transports need to setBcc(array()) and send to each Bcc recipient
        // separately in accordance with RFC 2822/2821
        $message = $this->createMessage();
        $message->setSubject('just a test subject');
        $message->setFrom(['chris.corbyn@swiftmailer.org' => 'Chris']);
        $message->setReplyTo([
            'chris@w3style.co.uk' => 'Myself',
            'my.other@address.com' => 'Me',
            ]);
        $message->setTo([
            'mark@swiftmailer.org', 'chris@swiftmailer.org' => 'Chris Corbyn',
            ]);
        $message->setCc([
            'john@some-site.com' => 'John West',
            'fred@another-site.co.uk' => 'Big Fred',
            ]);
        $message->setBcc('x@alphabet.tld');
        $id = $message->getId();
        $date = $message->getDate();
        $this->assertEquals(
            'Message-ID: <'.$id.'>'."\r\n".
            'Date: '.$date->format('r')."\r\n".
            'Subject: just a test subject'."\r\n".
            'From: Chris <chris.corbyn@swiftmailer.org>'."\r\n".
            'Reply-To: Myself <chris@w3style.co.uk>, Me <my.other@address.com>'."\r\n".
            'To: mark@swiftmailer.org, Chris Corbyn <chris@swiftmailer.org>'."\r\n".
            'Cc: John West <john@some-site.com>, Big Fred <fred@another-site.co.uk>'."\r\n".
            'Bcc: x@alphabet.tld'."\r\n".
            'MIME-Version: 1.0'."\r\n".
            'Content-Type: text/plain'."\r\n".
            'Content-Transfer-Encoding: quoted-printable'."\r\n",
            $message->toString()
            );
    }

    public function testMultipleBccAddressesCanBeSet()
    {
        //Obviously Transports need to setBcc(array()) and send to each Bcc recipient
        // separately in accordance with RFC 2822/2821
        $message = $this->createMessage();
        $message->setSubject('just a test subject');
        $message->setFrom(['chris.corbyn@swiftmailer.org' => 'Chris']);
        $message->setReplyTo([
            'chris@w3style.co.uk' => 'Myself',
            'my.other@address.com' => 'Me',
            ]);
        $message->setTo([
            'mark@swiftmailer.org', 'chris@swiftmailer.org' => 'Chris Corbyn',
            ]);
        $message->setCc([
            'john@some-site.com' => 'John West',
            'fred@another-site.co.uk' => 'Big Fred',
            ]);
        $message->setBcc(['x@alphabet.tld', 'a@alphabet.tld' => 'A']);
        $id = $message->getId();
        $date = $message->getDate();
        $this->assertEquals(
            'Message-ID: <'.$id.'>'."\r\n".
            'Date: '.$date->format('r')."\r\n".
            'Subject: just a test subject'."\r\n".
            'From: Chris <chris.corbyn@swiftmailer.org>'."\r\n".
            'Reply-To: Myself <chris@w3style.co.uk>, Me <my.other@address.com>'."\r\n".
            'To: mark@swiftmailer.org, Chris Corbyn <chris@swiftmailer.org>'."\r\n".
            'Cc: John West <john@some-site.com>, Big Fred <fred@another-site.co.uk>'."\r\n".
            'Bcc: x@alphabet.tld, A <a@alphabet.tld>'."\r\n".
            'MIME-Version: 1.0'."\r\n".
            'Content-Type: text/plain'."\r\n".
            'Content-Transfer-Encoding: quoted-printable'."\r\n",
            $message->toString()
            );
    }

    public function testStringBodyIsAppended()
    {
        $message = $this->createMessage();
        $message->setReturnPath('chris@w3style.co.uk');
        $message->setSubject('just a test subject');
        $message->setFrom([
            'chris.corbyn@swiftmailer.org' => 'Chris Corbyn', ]);
        $message->setBody(
            'just a test body'."\r\n".
            'with a new line'
            );
        $id = $message->getId();
        $date = $message->getDate();
        $this->assertEquals(
            'Return-Path: <chris@w3style.co.uk>'."\r\n".
            'Message-ID: <'.$id.'>'."\r\n".
            'Date: '.$date->format('r')."\r\n".
            'Subject: just a test subject'."\r\n".
            'From: Chris Corbyn <chris.corbyn@swiftmailer.org>'."\r\n".
            'MIME-Version: 1.0'."\r\n".
            'Content-Type: text/plain'."\r\n".
            'Content-Transfer-Encoding: quoted-printable'."\r\n".
            "\r\n".
            'just a test body'."\r\n".
            'with a new line',
            $message->toString()
            );
    }

    public function testStringBodyIsEncoded()
    {
        $message = $this->createMessage();
        $message->setReturnPath('chris@w3style.co.uk');
        $message->setSubject('just a test subject');
        $message->setFrom([
            'chris.corbyn@swiftmailer.org' => 'Chris Corbyn', ]);
        $message->setBody(
            'Just s'.pack('C*', 0xC2, 0x01, 0x01).'me multi-'."\r\n".
            'line message!'
            );
        $id = $message->getId();
        $date = $message->getDate();
        $this->assertEquals(
            'Return-Path: <chris@w3style.co.uk>'."\r\n".
            'Message-ID: <'.$id.'>'."\r\n".
            'Date: '.$date->format('r')."\r\n".
            'Subject: just a test subject'."\r\n".
            'From: Chris Corbyn <chris.corbyn@swiftmailer.org>'."\r\n".
            'MIME-Version: 1.0'."\r\n".
            'Content-Type: text/plain'."\r\n".
            'Content-Transfer-Encoding: quoted-printable'."\r\n".
            "\r\n".
            'Just s=C2=01=01me multi-'."\r\n".
            'line message!',
            $message->toString()
            );
    }

    public function testChildrenCanBeAttached()
    {
        $message = $this->createMessage();
        $message->setReturnPath('chris@w3style.co.uk');
        $message->setSubject('just a test subject');
        $message->setFrom([
            'chris.corbyn@swiftmailer.org' => 'Chris Corbyn', ]);

        $id = $message->getId();
        $date = $message->getDate();
        $boundary = $message->getBoundary();

        $part1 = $this->createMimePart();
        $part1->setContentType('text/plain');
        $part1->setCharset('iso-8859-1');
        $part1->setBody('foo');

        $message->attach($part1);

        $part2 = $this->createMimePart();
        $part2->setContentType('text/html');
        $part2->setCharset('iso-8859-1');
        $part2->setBody('test <b>foo</b>');

        $message->attach($part2);

        $this->assertEquals(
            'Return-Path: <chris@w3style.co.uk>'."\r\n".
            'Message-ID: <'.$id.'>'."\r\n".
            'Date: '.$date->format('r')."\r\n".
            'Subject: just a test subject'."\r\n".
            'From: Chris Corbyn <chris.corbyn@swiftmailer.org>'."\r\n".
            'MIME-Version: 1.0'."\r\n".
            'Content-Type: multipart/alternative;'."\r\n".
            ' boundary="'.$boundary.'"'."\r\n".
            "\r\n\r\n".
            '--'.$boundary."\r\n".
            'Content-Type: text/plain; charset=iso-8859-1'."\r\n".
            'Content-Transfer-Encoding: quoted-printable'."\r\n".
            "\r\n".
            'foo'.
            "\r\n\r\n".
            '--'.$boundary."\r\n".
            'Content-Type: text/html; charset=iso-8859-1'."\r\n".
            'Content-Transfer-Encoding: quoted-printable'."\r\n".
            "\r\n".
            'test <b>foo</b>'.
            "\r\n\r\n".
            '--'.$boundary.'--'."\r\n",
            $message->toString()
            );
    }

    public function testAttachmentsBeingAttached()
    {
        $message = $this->createMessage();
        $message->setReturnPath('chris@w3style.co.uk');
        $message->setSubject('just a test subject');
        $message->setFrom([
            'chris.corbyn@swiftmailer.org' => 'Chris Corbyn', ]);

        $id = $message->getId();
        $date = preg_quote($message->getDate()->format('r'), '~');
        $boundary = $message->getBoundary();

        $part = $this->createMimePart();
        $part->setContentType('text/plain');
        $part->setCharset('iso-8859-1');
        $part->setBody('foo');

        $message->attach($part);

        $attachment = $this->createAttachment();
        $attachment->setContentType('application/pdf');
        $attachment->setFilename('foo.pdf');
        $attachment->setBody('<pdf data>');

        $message->attach($attachment);

        $this->assertMatchesRegularExpression(
            '~^'.
            'Return-Path: <chris@w3style.co.uk>'."\r\n".
            'Message-ID: <'.$id.'>'."\r\n".
            'Date: '.$date."\r\n".
            'Subject: just a test subject'."\r\n".
            'From: Chris Corbyn <chris.corbyn@swiftmailer.org>'."\r\n".
            'MIME-Version: 1.0'."\r\n".
            'Content-Type: multipart/mixed;'."\r\n".
            ' boundary="'.$boundary.'"'."\r\n".
            "\r\n\r\n".
            '--'.$boundary."\r\n".
            'Content-Type: multipart/alternative;'."\r\n".
            ' boundary="(.*?)"'."\r\n".
            "\r\n\r\n".
            '--\\1'."\r\n".
            'Content-Type: text/plain; charset=iso-8859-1'."\r\n".
            'Content-Transfer-Encoding: quoted-printable'."\r\n".
            "\r\n".
            'foo'.
            "\r\n\r\n".
            '--\\1--'."\r\n".
            "\r\n\r\n".
            '--'.$boundary."\r\n".
            'Content-Type: application/pdf; name=foo.pdf'."\r\n".
            'Content-Transfer-Encoding: base64'."\r\n".
            'Content-Disposition: attachment; filename=foo.pdf'."\r\n".
            "\r\n".
            preg_quote(base64_encode('<pdf data>'), '~').
            "\r\n\r\n".
            '--'.$boundary.'--'."\r\n".
            '$~D',
            $message->toString()
            );
    }

    public function testAttachmentsAndEmbeddedFilesBeingAttached()
    {
        $message = $this->createMessage();
        $message->setReturnPath('chris@w3style.co.uk');
        $message->setSubject('just a test subject');
        $message->setFrom([
            'chris.corbyn@swiftmailer.org' => 'Chris Corbyn', ]);

        $id = $message->getId();
        $date = preg_quote($message->getDate()->format('r'), '~');
        $boundary = $message->getBoundary();

        $part = $this->createMimePart();
        $part->setContentType('text/plain');
        $part->setCharset('iso-8859-1');
        $part->setBody('foo');

        $message->attach($part);

        $attachment = $this->createAttachment();
        $attachment->setContentType('application/pdf');
        $attachment->setFilename('foo.pdf');
        $attachment->setBody('<pdf data>');

        $message->attach($attachment);

        $file = $this->createEmbeddedFile();
        $file->setContentType('image/jpeg');
        $file->setFilename('myimage.jpg');
        $file->setBody('<image data>');

        $message->attach($file);

        $cid = $file->getId();

        $this->assertMatchesRegularExpression(
            '~^'.
            'Return-Path: <chris@w3style.co.uk>'."\r\n".
            'Message-ID: <'.$id.'>'."\r\n".
            'Date: '.$date."\r\n".
            'Subject: just a test subject'."\r\n".
            'From: Chris Corbyn <chris.corbyn@swiftmailer.org>'."\r\n".
            'MIME-Version: 1.0'."\r\n".
            'Content-Type: multipart/mixed;'."\r\n".
            ' boundary="'.$boundary.'"'."\r\n".
            "\r\n\r\n".
            '--'.$boundary."\r\n".
            'Content-Type: multipart/alternative;'."\r\n".
            ' boundary="(.*?)"'."\r\n".
            "\r\n\r\n".
            '--\\1'."\r\n".
            'Content-Type: text/plain; charset=iso-8859-1'."\r\n".
            'Content-Transfer-Encoding: quoted-printable'."\r\n".
            "\r\n".
            'foo'.

            "\r\n\r\n".
            '--\\1'."\r\n".
            'Content-Type: multipart/related;'."\r\n".
            ' boundary="(.*?)"'."\r\n".
            "\r\n\r\n".
            '--\\2'."\r\n".
            'Content-Type: image/jpeg; name=myimage.jpg'."\r\n".
            'Content-Transfer-Encoding: base64'."\r\n".
            'Content-ID: <'.$cid.'>'."\r\n".
            'Content-Disposition: inline; filename=myimage.jpg'."\r\n".
            "\r\n".
            preg_quote(base64_encode('<image data>'), '~').
            "\r\n\r\n".
            '--\\2--'."\r\n".
            "\r\n\r\n".
            '--\\1--'."\r\n".
            "\r\n\r\n".
            '--'.$boundary."\r\n".
            'Content-Type: application/pdf; name=foo.pdf'."\r\n".
            'Content-Transfer-Encoding: base64'."\r\n".
            'Content-Disposition: attachment; filename=foo.pdf'."\r\n".
            "\r\n".
            preg_quote(base64_encode('<pdf data>'), '~').
            "\r\n\r\n".
            '--'.$boundary.'--'."\r\n".
            '$~D',
            $message->toString()
            );
    }

    public function testComplexEmbeddingOfContent()
    {
        $message = $this->createMessage();
        $message->setReturnPath('chris@w3style.co.uk');
        $message->setSubject('just a test subject');
        $message->setFrom([
            'chris.corbyn@swiftmailer.org' => 'Chris Corbyn', ]);

        $id = $message->getId();
        $date = preg_quote($message->getDate()->format('r'), '~');
        $boundary = $message->getBoundary();

        $attachment = $this->createAttachment();
        $attachment->setContentType('application/pdf');
        $attachment->setFilename('foo.pdf');
        $attachment->setBody('<pdf data>');

        $message->attach($attachment);

        $file = $this->createEmbeddedFile();
        $file->setContentType('image/jpeg');
        $file->setFilename('myimage.jpg');
        $file->setBody('<image data>');

        $part = $this->createMimePart();
        $part->setContentType('text/html');
        $part->setCharset('iso-8859-1');
        $part->setBody('foo <img src="'.$message->embed($file).'" />');

        $message->attach($part);

        $cid = $file->getId();

        $this->assertMatchesRegularExpression(
            '~^'.
            'Return-Path: <chris@w3style.co.uk>'."\r\n".
            'Message-ID: <'.$id.'>'."\r\n".
            'Date: '.$date."\r\n".
            'Subject: just a test subject'."\r\n".
            'From: Chris Corbyn <chris.corbyn@swiftmailer.org>'."\r\n".
            'MIME-Version: 1.0'."\r\n".
            'Content-Type: multipart/mixed;'."\r\n".
            ' boundary="'.$boundary.'"'."\r\n".
            "\r\n\r\n".
            '--'.$boundary."\r\n".
            'Content-Type: multipart/related;'."\r\n".
            ' boundary="(.*?)"'."\r\n".
            "\r\n\r\n".
            '--\\1'."\r\n".
            'Content-Type: text/html; charset=iso-8859-1'."\r\n".
            'Content-Transfer-Encoding: quoted-printable'."\r\n".
            "\r\n".
            'foo <img src=3D"cid:'.$cid.'" />'.//=3D is just = in QP
            "\r\n\r\n".
            '--\\1'."\r\n".
            'Content-Type: image/jpeg; name=myimage.jpg'."\r\n".
            'Content-Transfer-Encoding: base64'."\r\n".
            'Content-ID: <'.$cid.'>'."\r\n".
            'Content-Disposition: inline; filename=myimage.jpg'."\r\n".
            "\r\n".
            preg_quote(base64_encode('<image data>'), '~').
            "\r\n\r\n".
            '--\\1--'."\r\n".
            "\r\n\r\n".
            '--'.$boundary."\r\n".
            'Content-Type: application/pdf; name=foo.pdf'."\r\n".
            'Content-Transfer-Encoding: base64'."\r\n".
            'Content-Disposition: attachment; filename=foo.pdf'."\r\n".
            "\r\n".
            preg_quote(base64_encode('<pdf data>'), '~').
            "\r\n\r\n".
            '--'.$boundary.'--'."\r\n".
            '$~D',
            $message->toString()
            );
    }

    public function testAttachingAndDetachingContent()
    {
        $message = $this->createMessage();
        $message->setReturnPath('chris@w3style.co.uk');
        $message->setSubject('just a test subject');
        $message->setFrom([
            'chris.corbyn@swiftmailer.org' => 'Chris Corbyn', ]);

        $id = $message->getId();
        $date = preg_quote($message->getDate()->format('r'), '~');
        $boundary = $message->getBoundary();

        $part = $this->createMimePart();
        $part->setContentType('text/plain');
        $part->setCharset('iso-8859-1');
        $part->setBody('foo');

        $message->attach($part);

        $attachment = $this->createAttachment();
        $attachment->setContentType('application/pdf');
        $attachment->setFilename('foo.pdf');
        $attachment->setBody('<pdf data>');

        $message->attach($attachment);

        $file = $this->createEmbeddedFile();
        $file->setContentType('image/jpeg');
        $file->setFilename('myimage.jpg');
        $file->setBody('<image data>');

        $message->attach($file);

        $cid = $file->getId();

        $message->detach($attachment);

        $this->assertMatchesRegularExpression(
            '~^'.
            'Return-Path: <chris@w3style.co.uk>'."\r\n".
            'Message-ID: <'.$id.'>'."\r\n".
            'Date: '.$date."\r\n".
            'Subject: just a test subject'."\r\n".
            'From: Chris Corbyn <chris.corbyn@swiftmailer.org>'."\r\n".
            'MIME-Version: 1.0'."\r\n".
            'Content-Type: multipart/alternative;'."\r\n".
            ' boundary="'.$boundary.'"'."\r\n".
            "\r\n\r\n".
            '--'.$boundary."\r\n".
            'Content-Type: text/plain; charset=iso-8859-1'."\r\n".
            'Content-Transfer-Encoding: quoted-printable'."\r\n".
            "\r\n".
            'foo'.
            "\r\n\r\n".
            '--'.$boundary."\r\n".
            'Content-Type: multipart/related;'."\r\n".
            ' boundary="(.*?)"'."\r\n".
            "\r\n\r\n".
            '--\\1'."\r\n".
            'Content-Type: image/jpeg; name=myimage.jpg'."\r\n".
            'Content-Transfer-Encoding: base64'."\r\n".
            'Content-ID: <'.$cid.'>'."\r\n".
            'Content-Disposition: inline; filename=myimage.jpg'."\r\n".
            "\r\n".
            preg_quote(base64_encode('<image data>'), '~').
            "\r\n\r\n".
            '--\\1--'."\r\n".
            "\r\n\r\n".
            '--'.$boundary.'--'."\r\n".
            '$~D',
            $message->toString(),
            '%s: Attachment should have been detached'
            );
    }

    public function testBoundaryDoesNotAppearAfterAllPartsAreDetached()
    {
        $message = $this->createMessage();
        $message->setReturnPath('chris@w3style.co.uk');
        $message->setSubject('just a test subject');
        $message->setFrom([
            'chris.corbyn@swiftmailer.org' => 'Chris Corbyn', ]);

        $id = $message->getId();
        $date = $message->getDate();
        $boundary = $message->getBoundary();

        $part1 = $this->createMimePart();
        $part1->setContentType('text/plain');
        $part1->setCharset('iso-8859-1');
        $part1->setBody('foo');

        $message->attach($part1);

        $part2 = $this->createMimePart();
        $part2->setContentType('text/html');
        $part2->setCharset('iso-8859-1');
        $part2->setBody('test <b>foo</b>');

        $message->attach($part2);

        $message->detach($part1);
        $message->detach($part2);

        $this->assertEquals(
            'Return-Path: <chris@w3style.co.uk>'."\r\n".
            'Message-ID: <'.$id.'>'."\r\n".
            'Date: '.$date->format('r')."\r\n".
            'Subject: just a test subject'."\r\n".
            'From: Chris Corbyn <chris.corbyn@swiftmailer.org>'."\r\n".
            'MIME-Version: 1.0'."\r\n".
            'Content-Type: text/plain'."\r\n".
            'Content-Transfer-Encoding: quoted-printable'."\r\n",
            $message->toString(),
            '%s: Message should be restored to orignal state after parts are detached'
            );
    }

    public function testCharsetFormatOrDelSpAreNotShownWhenBoundaryIsSet()
    {
        $message = $this->createMessage();
        $message->setReturnPath('chris@w3style.co.uk');
        $message->setSubject('just a test subject');
        $message->setFrom([
            'chris.corbyn@swiftmailer.org' => 'Chris Corbyn', ]);
        $message->setCharset('utf-8');
        $message->setFormat('flowed');
        $message->setDelSp(true);

        $id = $message->getId();
        $date = $message->getDate();
        $boundary = $message->getBoundary();

        $part1 = $this->createMimePart();
        $part1->setContentType('text/plain');
        $part1->setCharset('iso-8859-1');
        $part1->setBody('foo');

        $message->attach($part1);

        $part2 = $this->createMimePart();
        $part2->setContentType('text/html');
        $part2->setCharset('iso-8859-1');
        $part2->setBody('test <b>foo</b>');

        $message->attach($part2);

        $this->assertEquals(
            'Return-Path: <chris@w3style.co.uk>'."\r\n".
            'Message-ID: <'.$id.'>'."\r\n".
            'Date: '.$date->format('r')."\r\n".
            'Subject: just a test subject'."\r\n".
            'From: Chris Corbyn <chris.corbyn@swiftmailer.org>'."\r\n".
            'MIME-Version: 1.0'."\r\n".
            'Content-Type: multipart/alternative;'."\r\n".
            ' boundary="'.$boundary.'"'."\r\n".
            "\r\n\r\n".
            '--'.$boundary."\r\n".
            'Content-Type: text/plain; charset=iso-8859-1'."\r\n".
            'Content-Transfer-Encoding: quoted-printable'."\r\n".
            "\r\n".
            'foo'.
            "\r\n\r\n".
            '--'.$boundary."\r\n".
            'Content-Type: text/html; charset=iso-8859-1'."\r\n".
            'Content-Transfer-Encoding: quoted-printable'."\r\n".
            "\r\n".
            'test <b>foo</b>'.
            "\r\n\r\n".
            '--'.$boundary.'--'."\r\n",
            $message->toString()
            );
    }

    public function testBodyCanBeSetWithAttachments()
    {
        $message = $this->createMessage();
        $message->setReturnPath('chris@w3style.co.uk');
        $message->setSubject('just a test subject');
        $message->setFrom([
            'chris.corbyn@swiftmailer.org' => 'Chris Corbyn', ]);
        $message->setContentType('text/html');
        $message->setCharset('iso-8859-1');
        $message->setBody('foo');

        $id = $message->getId();
        $date = $message->getDate()->format('r');
        $boundary = $message->getBoundary();

        $attachment = $this->createAttachment();
        $attachment->setContentType('application/pdf');
        $attachment->setFilename('foo.pdf');
        $attachment->setBody('<pdf data>');

        $message->attach($attachment);

        $this->assertEquals(
            'Return-Path: <chris@w3style.co.uk>'."\r\n".
            'Message-ID: <'.$id.'>'."\r\n".
            'Date: '.$date."\r\n".
            'Subject: just a test subject'."\r\n".
            'From: Chris Corbyn <chris.corbyn@swiftmailer.org>'."\r\n".
            'MIME-Version: 1.0'."\r\n".
            'Content-Type: multipart/mixed;'."\r\n".
            ' boundary="'.$boundary.'"'."\r\n".
            "\r\n\r\n".
            '--'.$boundary."\r\n".
            'Content-Type: text/html; charset=iso-8859-1'."\r\n".
            'Content-Transfer-Encoding: quoted-printable'."\r\n".
            "\r\n".
            'foo'.
            "\r\n\r\n".
            '--'.$boundary."\r\n".
            'Content-Type: application/pdf; name=foo.pdf'."\r\n".
            'Content-Transfer-Encoding: base64'."\r\n".
            'Content-Disposition: attachment; filename=foo.pdf'."\r\n".
            "\r\n".
            base64_encode('<pdf data>').
            "\r\n\r\n".
            '--'.$boundary.'--'."\r\n",
            $message->toString()
            );
    }

    public function testHtmlPartAlwaysAppearsLast()
    {
        $message = $this->createMessage();
        $message->setReturnPath('chris@w3style.co.uk');
        $message->setSubject('just a test subject');
        $message->setFrom([
            'chris.corbyn@swiftmailer.org' => 'Chris Corbyn', ]);

        $id = $message->getId();
        $date = $message->getDate()->format('r');
        $boundary = $message->getBoundary();

        $part1 = $this->createMimePart();
        $part1->setContentType('text/html');
        $part1->setBody('foo');

        $part2 = $this->createMimePart();
        $part2->setContentType('text/plain');
        $part2->setBody('bar');

        $message->attach($part1);
        $message->attach($part2);

        $this->assertEquals(
            'Return-Path: <chris@w3style.co.uk>'."\r\n".
            'Message-ID: <'.$id.'>'."\r\n".
            'Date: '.$date."\r\n".
            'Subject: just a test subject'."\r\n".
            'From: Chris Corbyn <chris.corbyn@swiftmailer.org>'."\r\n".
            'MIME-Version: 1.0'."\r\n".
            'Content-Type: multipart/alternative;'."\r\n".
            ' boundary="'.$boundary.'"'."\r\n".
            "\r\n\r\n".
            '--'.$boundary."\r\n".
            'Content-Type: text/plain'."\r\n".
            'Content-Transfer-Encoding: quoted-printable'."\r\n".
            "\r\n".
            'bar'.
            "\r\n\r\n".
            '--'.$boundary."\r\n".
            'Content-Type: text/html'."\r\n".
            'Content-Transfer-Encoding: quoted-printable'."\r\n".
            "\r\n".
            'foo'.
            "\r\n\r\n".
            '--'.$boundary.'--'."\r\n",
            $message->toString()
            );
    }

    public function testBodyBecomesPartIfOtherPartsAttached()
    {
        $message = $this->createMessage();
        $message->setReturnPath('chris@w3style.co.uk');
        $message->setSubject('just a test subject');
        $message->setFrom([
            'chris.corbyn@swiftmailer.org' => 'Chris Corbyn', ]);
        $message->setContentType('text/html');
        $message->setBody('foo');

        $id = $message->getId();
        $date = $message->getDate()->format('r');
        $boundary = $message->getBoundary();

        $part2 = $this->createMimePart();
        $part2->setContentType('text/plain');
        $part2->setBody('bar');

        $message->attach($part2);

        $this->assertEquals(
            'Return-Path: <chris@w3style.co.uk>'."\r\n".
            'Message-ID: <'.$id.'>'."\r\n".
            'Date: '.$date."\r\n".
            'Subject: just a test subject'."\r\n".
            'From: Chris Corbyn <chris.corbyn@swiftmailer.org>'."\r\n".
            'MIME-Version: 1.0'."\r\n".
            'Content-Type: multipart/alternative;'."\r\n".
            ' boundary="'.$boundary.'"'."\r\n".
            "\r\n\r\n".
            '--'.$boundary."\r\n".
            'Content-Type: text/plain'."\r\n".
            'Content-Transfer-Encoding: quoted-printable'."\r\n".
            "\r\n".
            'bar'.
            "\r\n\r\n".
            '--'.$boundary."\r\n".
            'Content-Type: text/html'."\r\n".
            'Content-Transfer-Encoding: quoted-printable'."\r\n".
            "\r\n".
            'foo'.
            "\r\n\r\n".
            '--'.$boundary.'--'."\r\n",
            $message->toString()
            );
    }

    public function testBodyIsCanonicalized()
    {
        $message = $this->createMessage();
        $message->setReturnPath('chris@w3style.co.uk');
        $message->setSubject('just a test subject');
        $message->setFrom([
            'chris.corbyn@swiftmailer.org' => 'Chris Corbyn', ]);
        $message->setBody(
            'just a test body'."\n".
            'with a new line'
            );
        $id = $message->getId();
        $date = $message->getDate();
        $this->assertEquals(
            'Return-Path: <chris@w3style.co.uk>'."\r\n".
            'Message-ID: <'.$id.'>'."\r\n".
            'Date: '.$date->format('r')."\r\n".
            'Subject: just a test subject'."\r\n".
            'From: Chris Corbyn <chris.corbyn@swiftmailer.org>'."\r\n".
            'MIME-Version: 1.0'."\r\n".
            'Content-Type: text/plain'."\r\n".
            'Content-Transfer-Encoding: quoted-printable'."\r\n".
            "\r\n".
            'just a test body'."\r\n".
            'with a new line',
            $message->toString()
            );
    }

    protected function createMessage()
    {
        return new Swift_Message();
    }

    protected function createMimePart()
    {
        return new Swift_MimePart();
    }

    protected function createAttachment()
    {
        return new Swift_Attachment();
    }

    protected function createEmbeddedFile()
    {
        return new Swift_EmbeddedFile();
    }
}


================================================
FILE: tests/acceptance/Swift/MimePartAcceptanceTest.php
================================================
<?php

require_once 'swift_required.php';
require_once __DIR__.'/Mime/MimePartAcceptanceTest.php';

class Swift_MimePartAcceptanceTest extends Swift_Mime_MimePartAcceptanceTest
{
    protected function createMimePart()
    {
        Swift_DependencyContainer::getInstance()
            ->register('properties.charset')->asValue(null);

        return new Swift_MimePart();
    }
}


================================================
FILE: tests/acceptance/Swift/Transport/StreamBuffer/AbstractStreamBufferAcceptanceTest.php
================================================
<?php

abstract class Swift_Transport_StreamBuffer_AbstractStreamBufferAcceptanceTest extends \PHPUnit\Framework\TestCase
{
    protected $buffer;

    abstract protected function initializeBuffer();

    protected function setUp()
    {
        if (true == getenv('TRAVIS')) {
            $this->markTestSkipped(
                'Will fail on travis-ci if not skipped due to travis blocking '.
                'socket mailing tcp connections.'
             );
        }

        $this->buffer = new Swift_Transport_StreamBuffer(
            $this->getMockBuilder('Swift_ReplacementFilterFactory')->getMock()
        );
    }

    public function testReadLine()
    {
        $this->initializeBuffer();

        $line = $this->buffer->readLine(0);
        $this->assertMatchesRegularExpression('/^[0-9]{3}.*?\r\n$/D', $line);
        $seq = $this->buffer->write("QUIT\r\n");
        $this->assertTrue((bool) $seq);
        $line = $this->buffer->readLine($seq);
        $this->assertMatchesRegularExpression('/^[0-9]{3}.*?\r\n$/D', $line);
        $this->buffer->terminate();
    }

    public function testWrite()
    {
        $this->initializeBuffer();

        $line = $this->buffer->readLine(0);
        $this->assertMatchesRegularExpression('/^[0-9]{3}.*?\r\n$/D', $line);

        $seq = $this->buffer->write("HELO foo\r\n");
        $this->assertTrue((bool) $seq);
        $line = $this->buffer->readLine($seq);
        $this->assertMatchesRegularExpression('/^[0-9]{3}.*?\r\n$/D', $line);

        $seq = $this->buffer->write("QUIT\r\n");
        $this->assertTrue((bool) $seq);
        $line = $this->buffer->readLine($seq);
        $this->assertMatchesRegularExpression('/^[0-9]{3}.*?\r\n$/D', $line);
        $this->buffer->terminate();
    }

    public function testBindingOtherStreamsMirrorsWriteOperations()
    {
        $this->initializeBuffer();

        $is1 = $this->createMockInputStream();
        $is2 = $this->createMockInputStream();

        $is1->expects($this->exactly(2))
            ->method('write')
            ->withConsecutive(
                ['x'],
                ['y']
            );
        $is2->expects($this->exactly(2))
            ->method('write')
            ->withConsecutive(
                ['x'],
                ['y']
            );

        $this->buffer->bind($is1);
        $this->buffer->bind($is2);

        $this->buffer->write('x');
        $this->buffer->write('y');
    }

    public function testBindingOtherStreamsMirrorsFlushOperations()
    {
        $this->initializeBuffer();

        $is1 = $this->createMockInputStream();
        $is2 = $this->createMockInputStream();

        $is1->expects($this->once())
            ->method('flushBuffers');
        $is2->expects($this->once())
            ->method('flushBuffers');

        $this->buffer->bind($is1);
        $this->buffer->bind($is2);

        $this->buffer->flushBuffers();
    }

    public function testUnbindingStreamPreventsFurtherWrites()
    {
        $this->initializeBuffer();

        $is1 = $this->createMockInputStream();
        $is2 = $this->createMockInputStream();

        $is1->expects($this->exactly(2))
            ->method('write')
            ->withConsecutive(
                ['x'],
                ['y']
            );
        $is2->expects($this->once())
            ->method('write')
            ->with('x');

        $this->buffer->bind($is1);
        $this->buffer->bind($is2);

        $this->buffer->write('x');

        $this->buffer->unbind($is2);

        $this->buffer->write('y');
    }

    private function createMockInputStream()
    {
        return $this->getMockBuilder('Swift_InputByteStream')->getMock();
    }
}


================================================
FILE: tests/acceptance/Swift/Transport/StreamBuffer/BasicSocketAcceptanceTest.php
================================================
<?php

require_once __DIR__.'/AbstractStreamBufferAcceptanceTest.php';

class Swift_Transport_StreamBuffer_BasicSocketAcceptanceTest extends Swift_Transport_StreamBuffer_AbstractStreamBufferAcceptanceTest
{
    protected function setUp()
    {
        if (!\defined('SWIFT_SMTP_HOST')) {
            $this->markTestSkipped(
                'Cannot run test without an SMTP host to connect to (define '.
                'SWIFT_SMTP_HOST in tests/acceptance.conf.php if you wish to run this test)'
             );
        }
        parent::setUp();
    }

    protected function initializeBuffer()
    {
        $parts = explode(':', SWIFT_SMTP_HOST);
        $host = $parts[0];
        $port = $parts[1] ?? 25;

        $this->buffer->initialize([
            'type' => Swift_Transport_IoBuffer::TYPE_SOCKET,
            'host' => $host,
            'port' => $port,
            'protocol' => 'tcp',
            'blocking' => 1,
            'timeout' => 15,
        ]);
    }
}


================================================
FILE: tests/acceptance/Swift/Transport/StreamBuffer/ProcessAcceptanceTest.php
================================================
<?php

require_once __DIR__.'/AbstractStreamBufferAcceptanceTest.php';

class Swift_Transport_StreamBuffer_ProcessAcceptanceTest extends Swift_Transport_StreamBuffer_AbstractStreamBufferAcceptanceTest
{
    protected function setUp()
    {
        if (!\defined('SWIFT_SENDMAIL_PATH')) {
            $this->markTestSkipped(
                'Cannot run test without a path to sendmail (define '.
                'SWIFT_SENDMAIL_PATH in tests/acceptance.conf.php if you wish to run this test)'
            );
        }

        parent::setUp();
    }

    public function testReadLine()
    {
        if (true == getenv('GITHUB_ACTIONS')) {
            $this->markTestSkipped(
                'Cannot run test on CI due to unknown PCRE pattern failure'
            );
        }
    }

    public function testWrite()
    {
        if (true == getenv('GITHUB_ACTIONS')) {
            $this->markTestSkipped(
                'Cannot run test on CI due to unknown PCRE pattern failure'
            );
        }
    }

    protected function initializeBuffer()
    {
        $this->buffer->initialize([
            'type' => Swift_Transport_IoBuffer::TYPE_PROCESS,
            'command' => SWIFT_SENDMAIL_PATH.' -bs',
        ]);
    }
}


================================================
FILE: tests/acceptance/Swift/Transport/StreamBuffer/SocketTimeoutTest.php
================================================
<?php

class Swift_Transport_StreamBuffer_SocketTimeoutTest extends \PHPUnit\Framework\TestCase
{
    protected $buffer;
    protected $server;
    protected $randomHighPort;

    protected function setUp()
    {
        if (!\defined('SWIFT_SMTP_HOST')) {
            $this->markTestSkipped(
                'Cannot run test without an SMTP host to connect to (define '.
                'SWIFT_SMTP_HOST in tests/acceptance.conf.php if you wish to run this test)'
             );
        }

        $serverStarted = false;
        for ($i = 0; $i < 5; ++$i) {
            $this->randomHighPort = random_int(50000, 65000);
            $this->server = stream_socket_server('tcp://127.0.0.1:'.$this->randomHighPort);
            if ($this->server) {
                $serverStarted = true;
            }
        }

        $this->buffer = new Swift_Transport_StreamBuffer(
            $this->getMockBuilder('Swift_ReplacementFilterFactory')->getMock()
        );
    }

    protected function initializeBuffer()
    {
        $host = '127.0.0.1';
        $port = $this->randomHighPort;

        $this->buffer->initialize([
            'type' => Swift_Transport_IoBuffer::TYPE_SOCKET,
            'host' => $host,
            'port' => $port,
            'protocol' => 'tcp',
            'blocking' => 1,
            'timeout' => 1,
        ]);
    }

    public function testTimeoutException()
    {
        $this->initializeBuffer();
        $e = null;
        try {
            $line = $this->buffer->readLine(0);
        } catch (Exception $e) {
        }
        $this->assertInstanceOf('Swift_IoException', $e, 'IO Exception Not Thrown On Connection Timeout');
        $this->assertMatchesRegularExpression('/Connection to .* Timed Out/', $e->getMessage());
    }

    protected function tearDown()
    {
        if ($this->server) {
            stream_socket_shutdown($this->server, STREAM_SHUT_RDWR);
        }
    }
}


================================================
FILE: tests/acceptance/Swift/Transport/StreamBuffer/SslSocketAcceptanceTest.php
================================================
<?php

require_once __DIR__.'/AbstractStreamBufferAcceptanceTest.php';

class Swift_Transport_StreamBuffer_SslSocketAcceptanceTest extends Swift_Transport_StreamBuffer_AbstractStreamBufferAcceptanceTest
{
    protected function setUp()
    {
        $streams = stream_get_transports();
        if (!\in_array('ssl', $streams)) {
            $this->markTestSkipped(
                'SSL is not configured for your system.  It is not possible to run this test'
             );
        }
        if (!\defined('SWIFT_SSL_HOST')) {
            $this->markTestSkipped(
                'Cannot run test without an SSL enabled SMTP host to connect to (define '.
                'SWIFT_SSL_HOST in tests/acceptance.conf.php if you wish to run this test)'
             );
        }

        parent::setUp();
    }

    protected function initializeBuffer()
    {
        $parts = explode(':', SWIFT_SSL_HOST);
        $host = $parts[0];
        $port = $parts[1] ?? 25;

        $this->buffer->initialize([
            'type' => Swift_Transport_IoBuffer::TYPE_SOCKET,
            'host' => $host,
            'port' => $port,
            'protocol' => 'ssl',
            'blocking' => 1,
            'timeout' => 15,
        ]);
    }
}


================================================
FILE: tests/acceptance/Swift/Transport/StreamBuffer/TlsSocketAcceptanceTest.php
================================================
<?php

require_once __DIR__.'/AbstractStreamBufferAcceptanceTest.php';

class Swift_Transport_StreamBuffer_TlsSocketAcceptanceTest extends Swift_Transport_StreamBuffer_AbstractStreamBufferAcceptanceTest
{
    protected function setUp()
    {
        $streams = stream_get_transports();
        if (!\in_array('tls', $streams)) {
            $this->markTestSkipped(
                'TLS is not configured for your system.  It is not possible to run this test'
            );
        }
        if (!\defined('SWIFT_TLS_HOST')) {
            $this->markTestSkipped(
                'Cannot run test without a TLS enabled SMTP host to connect to (define '.
                'SWIFT_TLS_HOST in tests/acceptance.conf.php if you wish to run this test)'
            );
        }
        if (\PHP_VERSION_ID < 70200) {
            $this->markTestSkipped(
                'Tests fail on PHP 7.1 and below.'
            );
        }
        parent::setUp();
    }

    protected function initializeBuffer()
    {
        $parts = explode(':', SWIFT_TLS_HOST);
        $host = $parts[0];
        $port = $parts[1] ?? 25;

        $this->buffer->initialize([
            'type' => Swift_Transport_IoBuffer::TYPE_SOCKET,
            'host' => $host,
            'port' => $port,
            'protocol' => 'tls',
            'blocking' => 1,
            'timeout' => 15,
            ]);
    }
}


================================================
FILE: tests/acceptance.conf.php.default
================================================
<?php

/*
 Swift Mailer acceptance test configuration.

 YOU ONLY NEED TO EDIT THIS FILE IF YOU WISH TO RUN THE ACCEPTANCE TESTS.

 The acceptance tests are run by default when "All Tests" are run with the
 testing suite, however, without configuration options here only the unit tests
 will be run and the acceptance tests will be skipped.
 
 You can fill out only the parts you know and leave the other bits.
 */

/*
 Defines: The name and port of a SMTP server you can connect to.
 Recommended: smtp.gmail.com:25
 */
define('SWIFT_SMTP_HOST', 'localhost:4456');

/*
 Defines: An SMTP server and port which uses TLS encryption.
 Recommended: smtp.gmail.com:465
 */
define('SWIFT_TLS_HOST', 'smtp.gmail.com:465');

/*
 Defines: An SMTP server and port which uses SSL encryption.
 Recommended: smtp.gmail.com:465
 */
define('SWIFT_SSL_HOST', 'smtp.gmail.com:465');

/*
 Defines: The path to a sendmail binary (one which can run in -bs mode).
 Recommended: /usr/sbin/sendmail
 */
define('SWIFT_SENDMAIL_PATH', '/usr/sbin/sendmail -bs');


================================================
FILE: tests/bootstrap.php
================================================
<?php

require_once \dirname(__DIR__).'/vendor/autoload.php';

// Disable garbage collector to prevent segfaults
gc_disable();

set_include_path(get_include_path().PATH_SEPARATOR.\dirname(__DIR__).'/lib');

Mockery::getConfiguration()->allowMockingNonExistentMethods(true);

if (is_file(__DIR__.'/acceptance.conf.php')) {
    require_once __DIR__.'/acceptance.conf.php';
}
if (is_file(__DIR__.'/smoke.conf.php')) {
    require_once __DIR__.'/smoke.conf.php';
}
require_once __DIR__.'/StreamCollector.php';
require_once __DIR__.'/IdenticalBinaryConstraint.php';
require_once __DIR__.'/SwiftMailerTestCase.php';
require_once __DIR__.'/SwiftMailerSmokeTestCase.php';


================================================
FILE: tests/bug/Swift/Bug111Test.php
================================================
<?php

class Swift_Bug111Test extends \PHPUnit\Framework\TestCase
{
    public function testUnstructuredHeaderSlashesShouldNotBeEscaped()
    {
        $complicated_header = [
            'to' => [
                'email1@example.com',
                'email2@example.com',
                'email3@example.com',
                'email4@example.com',
                'email5@example.com',
            ],
            'sub' => [
                '-name-' => [
                    'email1',
                    '"email2"',
                    'email3\\',
                    'email4',
                    'email5',
                ],
                '-url-' => [
                    'http://google.com',
                    'http://yahoo.com',
                    'http://hotmail.com',
                    'http://aol.com',
                    'http://facebook.com',
                ],
            ],
        ];
        $json = json_encode($complicated_header);

        $message = new Swift_Message();
        $headers = $message->getHeaders();
        $headers->addTextHeader('X-SMTPAPI', $json);
        $header = $headers->get('X-SMTPAPI');

        $this->assertEquals('Swift_Mime_Headers_UnstructuredHeader', \get_class($header));
        $this->assertEquals($json, $header->getFieldBody());
    }
}


================================================
FILE: tests/bug/Swift/Bug118Test.php
================================================
<?php

class Swift_Bug118Test extends \PHPUnit\Framework\TestCase
{
    private $message;

    protected function setUp()
    {
        $this->message = new Swift_Message();
    }

    public function testCallingGenerateIdChangesTheMessageId()
    {
        $currentId = $this->message->getId();
        $this->message->generateId();
        $newId = $this->message->getId();

        $this->assertNotEquals($currentId, $newId);
    }
}


================================================
FILE: tests/bug/Swift/Bug206Test.php
================================================
<?php

use Egulias\EmailValidator\EmailValidator;

class Swift_Bug206Test extends \PHPUnit\Framework\TestCase
{
    private $factory;

    protected function setUp()
    {
        $factory = new Swift_CharacterReaderFactory_SimpleCharacterReaderFactory();
        $headerEncoder = new Swift_Mime_HeaderEncoder_QpHeaderEncoder(
            new Swift_CharacterStream_ArrayCharacterStream($factory, 'utf-8')
        );
        $paramEncoder = new Swift_Encoder_Rfc2231Encoder(
            new Swift_CharacterStream_ArrayCharacterStream($factory, 'utf-8')
        );
        $emailValidator = new EmailValidator();
        $this->factory = new Swift_Mime_SimpleHeaderFactory($headerEncoder, $paramEncoder, $emailValidator);
    }

    public function testMailboxHeaderEncoding()
    {
        $this->doTestHeaderIsFullyEncoded('email@example.org', 'Family Name, Name', ' "Family Name, Name" <email@example.org>');
        $this->doTestHeaderIsFullyEncoded('email@example.org', 'Family Namé, Name', ' Family =?utf-8?Q?Nam=C3=A9=2C?= Name');
        $this->doTestHeaderIsFullyEncoded('email@example.org', 'Family Namé , Name', ' Family =?utf-8?Q?Nam=C3=A9_=2C?= Name');
        $this->doTestHeaderIsFullyEncoded('email@example.org', 'Family Namé ;Name', ' Family =?utf-8?Q?Nam=C3=A9_=3BName?= ');
    }

    private function doTestHeaderIsFullyEncoded($email, $name, $expected)
    {
        $mailboxHeader = $this->factory->createMailboxHeader('To', [
            $email => $name,
        ]);

        $headerBody = substr($mailboxHeader->toString(), 3, \strlen($expected));

        $this->assertEquals($expected, $headerBody);
    }
}


================================================
FILE: tests/bug/Swift/Bug274Test.php
================================================
<?php

class Swift_Bug274Test extends \PHPUnit\Framework\TestCase
{
    public function testEmptyFileNameAsAttachment()
    {
        $this->expectException(\Swift_IoException::class);
        $this->expectExceptionMessage('The path cannot be empty');

        $message = new Swift_Message();
        $message->attach(Swift_Attachment::fromPath(''));
    }

    public function testNonEmptyFileNameAsAttachment()
    {
        $message = new Swift_Message();
        try {
            $message->attach(Swift_Attachment::fromPath(__FILE__));
        } catch (Exception $e) {
            $this->fail('Path should not be empty');
        }
        $this->addToAssertionCount(1);
    }
}


================================================
FILE: tests/bug/Swift/Bug34Test.php
================================================
<?php

class Swift_Bug34Test extends \PHPUnit\Framework\TestCase
{
    protected function setUp()
    {
        Swift_Preferences::getInstance()->setCharset('utf-8');
    }

    public function testEmbeddedFilesWithMultipartDataCreateMultipartRelatedContentAsAnAlternative()
    {
        $message = new Swift_Message();
        $message->setCharset('utf-8');
        $message->setSubject('test subject');
        $message->addPart('plain part', 'text/plain');

        $image = new Swift_Image('<image data>', 'image.gif', 'image/gif');
        $cid = $message->embed($image);

        $message->setBody('<img src="'.$cid.'" />', 'text/html');

        $message->setTo(['user@domain.tld' => 'User']);

        $message->setFrom(['other@domain.tld' => 'Other']);
        $message->setSender(['other@domain.tld' => 'Other']);

        $id = $message->getId();
        $date = preg_quote($message->getDate()->format('r'), '~');
        $boundary = $message->getBoundary();
        $cidVal = $image->getId();

        $this->assertMatchesRegularExpression(
        '~^'.
        'Sender: Other <other@domain.tld>'."\r\n".
        'Message-ID: <'.$id.'>'."\r\n".
        'Date: '.$date."\r\n".
        'Subject: test subject'."\r\n".
        'From: Other <other@domain.tld>'."\r\n".
        'To: User <user@domain.tld>'."\r\n".
        'MIME-Version: 1.0'."\r\n".
        'Content-Type: multipart/alternative;'."\r\n".
        ' boundary="'.$boundary.'"'."\r\n".
        "\r\n\r\n".
        '--'.$boundary."\r\n".
        'Content-Type: text/plain; charset=utf-8'."\r\n".
        'Content-Transfer-Encoding: quoted-printable'."\r\n".
        "\r\n".
        'plain part'.
        "\r\n\r\n".
        '--'.$boundary."\r\n".
        'Content-Type: multipart/related;'."\r\n".
        ' boundary="(.*?)"'."\r\n".
        "\r\n\r\n".
        '--\\1'."\r\n".
        'Content-Type: text/html; charset=utf-8'."\r\n".
        'Content-Transfer-Encoding: quoted-printable'."\r\n".
        "\r\n".
        '<img.*?/>'.
        "\r\n\r\n".
        '--\\1'."\r\n".
        'Content-Type: image/gif; name=image.gif'."\r\n".
        'Content-Transfer-Encoding: base64'."\r\n".
        'Content-ID: <'.$cidVal.'>'."\r\n".
        'Content-Disposition: inline; filename=image.gif'."\r\n".
        "\r\n".
        preg_quote(base64_encode('<image data>'), '~').
        "\r\n\r\n".
        '--\\1--'."\r\n".
        "\r\n\r\n".
        '--'.$boundary.'--'."\r\n".
        '$~D',
        $message->toString()
        );
    }
}


================================================
FILE: tests/bug/Swift/Bug35Test.php
================================================
<?php

class Swift_Bug35Test extends \PHPUnit\Framework\TestCase
{
    protected function setUp()
    {
        Swift_Preferences::getInstance()->setCharset('utf-8');
    }

    public function testHTMLPartAppearsLastEvenWhenAttachmentsAdded()
    {
        $message = new Swift_Message();
        $message->setCharset('utf-8');
        $message->setSubject('test subject');
        $message->addPart('plain part', 'text/plain');

        $attachment = new Swift_Attachment('<data>', 'image.gif', 'image/gif');
        $message->attach($attachment);

        $message->setBody('HTML part', 'text/html');

        $message->setTo(['user@domain.tld' => 'User']);

        $message->setFrom(['other@domain.tld' => 'Other']);
        $message->setSender(['other@domain.tld' => 'Other']);

        $id = $message->getId();
        $date = preg_quote($message->getDate()->format('r'), '~');
        $boundary = $message->getBoundary();

        $this->assertMatchesRegularExpression(
        '~^'.
        'Sender: Other <other@domain.tld>'."\r\n".
        'Message-ID: <'.$id.'>'."\r\n".
        'Date: '.$date."\r\n".
        'Subject: test subject'."\r\n".
        'From: Other <other@domain.tld>'."\r\n".
        'To: User <user@domain.tld>'."\r\n".
        'MIME-Version: 1.0'."\r\n".
        'Content-Type: multipart/mixed;'."\r\n".
        ' boundary="'.$boundary.'"'."\r\n".
        "\r\n\r\n".
        '--'.$boundary."\r\n".
        'Content-Type: multipart/alternative;'."\r\n".
        ' boundary="(.*?)"'."\r\n".
        "\r\n\r\n".
        '--\\1'."\r\n".
        'Content-Type: text/plain; charset=utf-8'."\r\n".
        'Content-Transfer-Encoding: quoted-printable'."\r\n".
        "\r\n".
        'plain part'.
        "\r\n\r\n".
        '--\\1'."\r\n".
        'Content-Type: text/html; charset=utf-8'."\r\n".
        'Content-Transfer-Encoding: quoted-printable'."\r\n".
        "\r\n".
        'HTML part'.
        "\r\n\r\n".
        '--\\1--'."\r\n".
        "\r\n\r\n".
        '--'.$boundary."\r\n".
        'Content-Type: image/gif; name=image.gif'."\r\n".
        'Content-Transfer-Encoding: base64'."\r\n".
        'Content-Disposition: attachment; filename=image.gif'."\r\n".
        "\r\n".
        preg_quote(base64_encode('<data>'), '~').
        "\r\n\r\n".
        '--'.$boundary.'--'."\r\n".
        '$~D',
        $message->toString()
        );
    }
}


================================================
FILE: tests/bug/Swift/Bug38Test.php
================================================
<?php

class Swift_Bug38Test extends \PHPUnit\Framework\TestCase
{
    private $attFile;
    private $attFileName;
    private $attFileType;

    protected function setUp()
    {
        $this->attFileName = 'data.txt';
        $this->attFileType = 'text/plain';
        $this->attFile = __DIR__.'/../../_samples/files/data.txt';
        Swift_Preferences::getInstance()->setCharset('utf-8');
    }

    public function testWritingMessageToByteStreamProducesCorrectStructure()
    {
        $message = new Swift_Message();
        $message->setSubject('test subject');
        $message->setTo('user@domain.tld');
        $message->setCc('other@domain.tld');
        $message->setFrom('user@domain.tld');

        $image = new Swift_Image('<data>', 'image.gif', 'image/gif');

        $cid = $message->embed($image);
        $message->setBody('HTML part', 'text/html');

        $id = $message->getId();
        $date = preg_quote($message->getDate()->format('r'), '~');
        $boundary = $message->getBoundary();
        $imgId = $image->getId();

        $stream = new Swift_ByteStream_ArrayByteStream();

        $message->toByteStream($stream);

        $this->assertPatternInStream(
            '~^'.
            'Message-ID: <'.$id.'>'."\r\n".
            'Date: '.$date."\r\n".
            'Subject: test subject'."\r\n".
            'From: user@domain.tld'."\r\n".
            'To: user@domain.tld'."\r\n".
            'Cc: other@domain.tld'."\r\n".
            'MIME-Version: 1.0'."\r\n".
            'Content-Type: multipart/related;'."\r\n".
            ' boundary="'.$boundary.'"'."\r\n".
            "\r\n\r\n".
            '--'.$boundary."\r\n".
            'Content-Type: text/html; charset=utf-8'."\r\n".
            'Content-Transfer-Encoding: quoted-printable'."\r\n".
            "\r\n".
            'HTML part'.
            "\r\n\r\n".
            '--'.$boundary."\r\n".
            'Content-Type: image/gif; name=image.gif'."\r\n".
            'Content-Transfer-Encoding: base64'."\r\n".
            'Content-ID: <'.preg_quote($imgId, '~').'>'."\r\n".
            'Content-Disposition: inline; filename=image.gif'."\r\n".
            "\r\n".
            preg_quote(base64_encode('<data>'), '~').
            "\r\n\r\n".
            '--'.$boundary.'--'."\r\n".
            '$~D',
            $stream
        );
    }

    public function testWritingMessageToByteStreamTwiceProducesCorrectStructure()
    {
        $message = new Swift_Message();
        $message->setSubject('test subject');
        $message->setTo('user@domain.tld');
        $message->setCc('other@domain.tld');
        $message->setFrom('user@domain.tld');

        $image = new Swift_Image('<data>', 'image.gif', 'image/gif');

        $cid = $message->embed($image);
        $message->setBody('HTML part', 'text/html');

        $id = $message->getId();
        $date = preg_quote($message->getDate()->format('r'), '~');
        $boundary = $message->getBoundary();
        $imgId = $image->getId();

        $pattern = '~^'.
        'Message-ID: <'.$id.'>'."\r\n".
        'Date: '.$date."\r\n".
        'Subject: test subject'."\r\n".
        'From: user@domain.tld'."\r\n".
        'To: user@domain.tld'."\r\n".
        'Cc: other@domain.tld'."\r\n".
        'MIME-Version: 1.0'."\r\n".
        'Content-Type: multipart/related;'."\r\n".
        ' boundary="'.$boundary.'"'."\r\n".
        "\r\n\r\n".
        '--'.$boundary."\r\n".
        'Content-Type: text/html; charset=utf-8'."\r\n".
        'Content-Transfer-Encoding: quoted-printable'."\r\n".
        "\r\n".
        'HTML part'.
        "\r\n\r\n".
        '--'.$boundary."\r\n".
        'Content-Type: image/gif; name=image.gif'."\r\n".
        'Content-Transfer-Encoding: base64'."\r\n".
        'Content-ID: <'.preg_quote($imgId, '~').'>'."\r\n".
        'Content-Disposition: inline; filename=image.gif'."\r\n".
        "\r\n".
        preg_quote(base64_encode('<data>'), '~').
        "\r\n\r\n".
        '--'.$boundary.'--'."\r\n".
        '$~D'
        ;

        $streamA = new Swift_ByteStream_ArrayByteStream();
        $streamB = new Swift_ByteStream_ArrayByteStream();

        $message->toByteStream($streamA);
        $message->toByteStream($streamB);

        $this->assertPatternInStream($pattern, $streamA);
        $this->assertPatternInStream($pattern, $streamB);
    }

    public function testWritingMessageToByteStreamTwiceUsingAFileAttachment()
    {
        $message = new Swift_Message();
        $message->setSubject('test subject');
        $message->setTo('user@domain.tld');
        $message->setCc('other@domain.tld');
        $message->setFrom('user@domain.tld');

        $attachment = Swift_Attachment::fromPath($this->attFile);

        $message->attach($attachment);

        $message->setBody('HTML part', 'text/html');

        $id = $message->getId();
        $date = preg_quote($message->getDate()->format('r'), '~');
        $boundary = $message->getBoundary();

        $streamA = new Swift_ByteStream_ArrayByteStream();
        $streamB = new Swift_ByteStream_ArrayByteStream();

        $pattern = '~^'.
            'Message-ID: <'.$id.'>'."\r\n".
            'Date: '.$date."\r\n".
            'Subject: test subject'."\r\n".
            'From: user@domain.tld'."\r\n".
            'To: user@domain.tld'."\r\n".
            'Cc: other@domain.tld'."\r\n".
            'MIME-Version: 1.0'."\r\n".
            'Content-Type: multipart/mixed;'."\r\n".
            ' boundary="'.$boundary.'"'."\r\n".
            "\r\n\r\n".
            '--'.$boundary."\r\n".
            'Content-Type: text/html; charset=utf-8'."\r\n".
            'Content-Transfer-Encoding: quoted-printable'."\r\n".
            "\r\n".
            'HTML part'.
            "\r\n\r\n".
            '--'.$boundary."\r\n".
            'Content-Type: '.$this->attFileType.'; name='.$this->attFileName."\r\n".
            'Content-Transfer-Encoding: base64'."\r\n".
            'Content-Disposition: attachment; filename='.$this->attFileName."\r\n".
            "\r\n".
            preg_quote(base64_encode(file_get_contents($this->attFile)), '~').
            "\r\n\r\n".
            '--'.$boundary.'--'."\r\n".
            '$~D'
            ;

        $message->toByteStream($streamA);
        $message->toByteStream($streamB);

        $this->assertPatternInStream($pattern, $streamA);
        $this->assertPatternInStream($pattern, $streamB);
    }

    public function assertPatternInStream($pattern, $stream, $message = '%s')
    {
        $string = '';
        while (false !== $bytes = $stream->read(8192)) {
            $string .= $bytes;
        }
        $this->assertMatchesRegularExpression($pattern, $string, $message);
    }
}


================================================
FILE: tests/bug/Swift/Bug518Test.php
================================================
<?php

use Mockery as m;

class Swift_Bug518Test extends \SwiftMailerTestCase
{
    public function testIfEmailChangesAfterQueued()
    {
        $failedRecipients = 'value';
        $message = new Swift_Message();
        $message->setTo('foo@bar.com');

        $that = $this;
        $messageValidation = function ($m) use ($that) {
            //the getTo should return the same value as we put in
            $that->assertEquals('foo@bar.com', key($m->getTo()), 'The message has changed after it was put to the memory queue');

            return true;
        };

        $transport = m::mock('Swift_Transport');
        $transport->shouldReceive('isStarted')->andReturn(true);
        $transport->shouldReceive('send')
            ->with(m::on($messageValidation), $failedRecipients)
            ->andReturn(1);

        $memorySpool = new Swift_MemorySpool();
        $memorySpool->queueMessage($message);

        /*
         * The message is queued in memory.
         * Lets change the message
         */
        $message->setTo('other@value.com');

        $memorySpool->flushQueue($transport, $failedRecipients);
    }
}


================================================
FILE: tests/bug/Swift/Bug51Test.php
================================================
<?php

class Swift_Bug51Test extends \SwiftMailerTestCase
{
    private $attachmentFile;
    private $outputFile;

    protected function setUp()
    {
        $this->attachmentFile = sys_get_temp_dir().'/attach.rand.bin';
        file_put_contents($this->attachmentFile, '');

        $this->outputFile = sys_get_temp_dir().'/attach.out.bin';
        file_put_contents($this->outputFile, '');
    }

    protected function tearDown()
    {
        unlink($this->attachmentFile);
        unlink($this->outputFile);
    }

    public function testAttachmentsDoNotGetTruncatedUsingToByteStream()
    {
        //Run 100 times with 10KB attachments
        for ($i = 0; $i < 10; ++$i) {
            $message = $this->createMessageWithRandomAttachment(
                10000, $this->attachmentFile
            );

            file_put_contents($this->outputFile, '');
            $message->toByteStream(
                new Swift_ByteStream_FileByteStream($this->outputFile, true)
            );

            $emailSource = file_get_contents($this->outputFile);

            $this->assertAttachmentFromSourceMatches(
                file_get_contents($this->attachmentFile),
                $emailSource
            );
        }
    }

    public function testAttachmentsDoNotGetTruncatedUsingToString()
    {
        //Run 100 times with 10KB attachments
        for ($i = 0; $i < 10; ++$i) {
            $message = $this->createMessageWithRandomAttachment(
                10000, $this->attachmentFile
            );

            $emailSource = $message->toString();

            $this->assertAttachmentFromSourceMatches(
                file_get_contents($this->attachmentFile),
                $emailSource
            );
        }
    }

    public function assertAttachmentFromSourceMatches($attachmentData, $source)
    {
        $encHeader = 'Content-Transfer-Encoding: base64';
        $base64declaration = strpos($source, $encHeader);

        $attachmentDataStart = strpos($source, "\r\n\r\n", $base64declaration);
        $attachmentDataEnd = strpos($source, "\r\n--", $attachmentDataStart);

        if (false === $attachmentDataEnd) {
            $attachmentBase64 = trim(substr($source, $attachmentDataStart));
        } else {
            $attachmentBase64 = trim(substr(
                $source, $attachmentDataStart,
                $attachmentDataEnd - $attachmentDataStart
            ));
        }

        $this->assertIdenticalBinary($attachmentData, base64_decode($attachmentBase64));
    }

    private function fillFileWithRandomBytes($byteCount, $file)
    {
        // I was going to use dd with if=/dev/random but this way seems more
        // cross platform even if a hella expensive!!

        file_put_contents($file, '');
        $fp = fopen($file, 'wb');
        for ($i = 0; $i < $byteCount; ++$i) {
            $byteVal = random_int(0, 255);
            fwrite($fp, pack('i', $byteVal));
        }
        fclose($fp);
    }

    private function createMessageWithRandomAttachment($size, $attachmentPath)
    {
        $this->fillFileWithRandomBytes($size, $attachmentPath);

        $message = (new Swift_Message())
            ->setSubject('test')
            ->setBody('test')
            ->setFrom('a@b.c')
            ->setTo('d@e.f')
            ->attach(Swift_Attachment::fromPath($attachmentPath))
            ;

        return $message;
    }
}


================================================
FILE: tests/bug/Swift/Bug534Test.php
================================================
<?php

use Mockery as m;

class Swift_Bug534Test extends \SwiftMailerTestCase
{
    public function testEmbeddedImagesAreEmbedded()
    {
        $message = (new Swift_Message())
            ->setFrom('from@example.com')
            ->setTo('to@example.com')
            ->setSubject('test')
        ;
        $cid = $message->embed(Swift_Image::fromPath(__DIR__.'/../../_samples/files/swiftmailer.png'));
        $message->setBody('<img src="'.$cid.'" />', 'text/html');

        $that = $this;
        $messageValidation = function (Swift_Mime_SimpleMessage $message) use ($that) {
            preg_match('/cid:(.*)"/', $message->toString(), $matches);
            $cid = $matches[1];
            preg_match('/Content-ID: <(.*)>/', $message->toString(), $matches);
            $contentId = $matches[1];
            $that->assertEquals($cid, $contentId, 'cid in body and mime part Content-ID differ');

            return true;
        };

        $failedRecipients = [];

        $transport = m::mock('Swift_Transport');
        $transport->shouldReceive('isStarted')->andReturn(true);
        $transport->shouldReceive('send')->with(m::on($messageValidation), $failedRecipients)->andReturn(1);

        $memorySpool = new Swift_MemorySpool();
        $memorySpool->queueMessage($message);
        $memorySpool->flushQueue($transport, $failedRecipients);
    }
}


================================================
FILE: tests/bug/Swift/Bug650Test.php
================================================
<?php

use Egulias\EmailValidator\EmailValidator;

class Swift_Bug650Test extends \PHPUnit\Framework\TestCase
{
    /**
     * @dataProvider encodingDataProvider
     *
     * @param string $name
     * @param string $expectedEncodedName
     */
    public function testMailboxHeaderEncoding($name, $expectedEncodedName)
    {
        $factory = new Swift_CharacterReaderFactory_SimpleCharacterReaderFactory();
        $charStream = new Swift_CharacterStream_NgCharacterStream($factory, 'utf-8');
        $encoder = new Swift_Mime_HeaderEncoder_QpHeaderEncoder($charStream);
        $header = new Swift_Mime_Headers_MailboxHeader('To', $encoder, new EmailValidator());
        $header->setCharset('utf-8');

        $header->setNameAddresses([
            'test@example.com' => $name,
        ]);

        $this->assertSame('To: '.$expectedEncodedName." <test@example.com>\r\n", $header->toString());
    }

    public function encodingDataProvider()
    {
        return [
            ['this is " a test ö', 'this is =?utf-8?Q?=22?= a test =?utf-8?Q?=C3=B6?='],
            [': this is a test ö', '=?utf-8?Q?=3A?= this is a test =?utf-8?Q?=C3=B6?='],
            ['( test ö', '=?utf-8?Q?=28?= test =?utf-8?Q?=C3=B6?='],
            ['[ test ö', '=?utf-8?Q?=5B?= test =?utf-8?Q?=C3=B6?='],
            ['@ test ö)', '=?utf-8?Q?=40?= test =?utf-8?Q?=C3=B6=29?='],
        ];
    }
}


================================================
FILE: tests/bug/Swift/Bug71Test.php
================================================
<?php

class Swift_Bug71Test extends \PHPUnit\Framework\TestCase
{
    private $message;

    protected function setUp()
    {
        $this->message = new Swift_Message('test');
    }

    public function testCallingToStringAfterSettingNewBodyReflectsChanges()
    {
        $this->message->setBody('BODY1');
        $this->assertMatchesRegularExpression('/BODY1/', $this->message->toString());

        $this->message->setBody('BODY2');
        $this->assertMatchesRegularExpression('/BODY2/', $this->message->toString());
    }
}


================================================
FILE: tests/bug/Swift/Bug76Test.php
================================================
<?php

class Swift_Bug76Test extends \PHPUnit\Framework\TestCase
{
    private $inputFile;
    private $outputFile;
    private $encoder;

    protected function setUp()
    {
        $this->inputFile = sys_get_temp_dir().'/in.bin';
        file_put_contents($this->inputFile, '');

        $this->outputFile = sys_get_temp_dir().'/out.bin';
        file_put_contents($this->outputFile, '');

        $this->encoder = $this->createEncoder();
    }

    protected function tearDown()
    {
        unlink($this->inputFile);
        unlink($this->outputFile);
    }

    public function testBase64EncodedLineLengthNeverExceeds76CharactersEvenIfArgsDo()
    {
        $this->fillFileWithRandomBytes(1000, $this->inputFile);

        $os = $this->createStream($this->inputFile);
        $is = $this->createStream($this->outputFile);

        $this->encoder->encodeByteStream($os, $is, 0, 80); //Exceeds 76

        $this->assertMaxLineLength(76, $this->outputFile,
            '%s: Line length should not exceed 76 characters'
        );
    }

    public function assertMaxLineLength($length, $filePath, $message = '%s')
    {
        $lines = file($filePath);
        foreach ($lines as $line) {
            $this->assertTrue((\strlen(trim($line)) <= 76), $message);
        }
    }

    private function fillFileWithRandomBytes($byteCount, $file)
    {
        // I was going to use dd with if=/dev/random but this way seems more
        // cross platform even if a hella expensive!!

        file_put_contents($file, '');
        $fp = fopen($file, 'wb');
        for ($i = 0; $i < $byteCount; ++$i) {
            $byteVal = random_int(0, 255);
            fwrite($fp, pack('i', $byteVal));
        }
        fclose($fp);
    }

    private function createEncoder()
    {
        return new Swift_Mime_ContentEncoder_Base64ContentEncoder();
    }

    private function createStream($file)
    {
        return new Swift_ByteStream_FileByteStream($file, true);
    }
}


================================================
FILE: tests/bug/Swift/BugFileByteStreamConsecutiveReadCallsTest.php
================================================
<?php

class Swift_FileByteStreamConsecutiveReadCalls extends \PHPUnit\Framework\TestCase
{
    public function testShouldThrowExceptionOnConsecutiveRead()
    {
        $this->expectException(\Swift_IoException::class);

        $fbs = new \Swift_ByteStream_FileByteStream('does not exist');
        try {
            $fbs->read(100);
        } catch (\Swift_IoException $exc) {
            $fbs->read(100);
        }
    }
}


================================================
FILE: tests/fixtures/MimeEntityFixture.php
================================================
<?php

class MimeEntityFixture extends Swift_Mime_SimpleMimeEntity
{
    private $level;
    private $string;
    private $contentType;

    public function __construct($level = null, $string = '', $contentType = null)
    {
        $this->level = $level;
        $this->string = $string;
        $this->contentType = $contentType;
    }

    public function getNestingLevel()
    {
        return $this->level;
    }

    public function toString()
    {
        return $this->string;
    }

    public function getContentType()
    {
        return $this->contentType;
    }

    // These methods are here to account for the implemented interfaces
    public function getId()
    {
    }

    public function getHeaders()
    {
    }

    public function getBody()
    {
    }

    public function setBody($body, $contentType = null)
    {
    }

    public function toByteStream(Swift_InputByteStream $is)
    {
    }

    public function charsetChanged($charset)
    {
    }

    public function encoderChanged(Swift_Mime_ContentEncoder $encoder)
    {
    }

    public function getChildren()
    {
    }

    public function setChildren(array $children, $compoundLevel = null)
    {
    }
}


================================================
FILE: tests/smoke/Swift/Smoke/AttachmentSmokeTest.php
================================================
<?php

/**
 * @group smoke
 */
class Swift_Smoke_AttachmentSmokeTest extends SwiftMailerSmokeTestCase
{
    private $attFile;

    protected function setUp()
    {
        parent::setUp(); // For skip
        $this->attFile = __DIR__.'/../../../_samples/files/textfile.zip';
    }

    public function testAttachmentSending()
    {
        $mailer = $this->getMailer();
        $message = (new Swift_Message())
            ->setSubject('[Swift Mailer] AttachmentSmokeTest')
            ->setFrom([SWIFT_SMOKE_EMAIL_ADDRESS => 'Swift Mailer'])
            ->setTo(SWIFT_SMOKE_EMAIL_ADDRESS)
            ->setBody('This message should contain an attached ZIP file (named "textfile.zip").'.PHP_EOL.
                'When unzipped, the archive should produce a text file which reads:'.PHP_EOL.
                '"This is part of a Swift Mailer smoke test."'
                )
            ->attach(Swift_Attachment::fromPath($this->attFile))
            ;
        $this->assertEquals(1, $mailer->send($message),
            '%s: The smoke test should send a single message'
            );
    }
}


================================================
FILE: tests/smoke/Swift/Smoke/BasicSmokeTest.php
================================================
<?php

/**
 * @group smoke
 */
class Swift_Smoke_BasicSmokeTest extends SwiftMailerSmokeTestCase
{
    public function testBasicSending()
    {
        $mailer = $this->getMailer();
        $message = (new Swift_Message())
            ->setSubject('[Swift Mailer] BasicSmokeTest')
            ->setFrom([SWIFT_SMOKE_EMAIL_ADDRESS => 'Swift Mailer'])
            ->setTo(SWIFT_SMOKE_EMAIL_ADDRESS)
            ->setBody('One, two, three, four, five...'.PHP_EOL.
                'six, seven, eight...'
                )
            ;
        $this->assertEquals(1, $mailer->send($message),
            '%s: The smoke test should send a single message'
            );
    }
}


================================================
FILE: tests/smoke/Swift/Smoke/HtmlWithAttachmentSmokeTest.php
================================================
<?php

/**
 * @group smoke
 */
class Swift_Smoke_HtmlWithAttachmentSmokeTest extends SwiftMailerSmokeTestCase
{
    private $attFile;

    protected function setUp()
    {
        parent::setUp();

        $this->attFile = __DIR__.'/../../../_samples/files/textfile.zip';
    }

    public function testAttachmentSending()
    {
        $mailer = $this->getMailer();
        $message = (new Swift_Message('[Swift Mailer] HtmlWithAttachmentSmokeTest'))
            ->setFrom([SWIFT_SMOKE_EMAIL_ADDRESS => 'Swift Mailer'])
            ->setTo(SWIFT_SMOKE_EMAIL_ADDRESS)
            ->attach(Swift_Attachment::fromPath($this->attFile))
            ->setBody('<p>This HTML-formatted message should contain an attached ZIP file (named "textfile.zip").'.PHP_EOL.
                'When unzipped, the archive should produce a text file which reads:</p>'.PHP_EOL.
                '<p><q>This is part of a Swift Mailer smoke test.</q></p>', 'text/html'
            )
            ;
        $this->assertEquals(1, $mailer->send($message),
            '%s: The smoke test should send a single message'
            );
    }
}


================================================
FILE: tests/smoke/Swift/Smoke/InternationalSmokeTest.php
================================================
<?php

/**
 * @group smoke
 */
class Swift_Smoke_InternationalSmokeTest extends SwiftMailerSmokeTestCase
{
    private $attFile;

    protected function setUp()
    {
        parent::setUp(); // For skip
        $this->attFile = __DIR__.'/../../../_samples/files/textfile.zip';
    }

    public function testAttachmentSending()
    {
        $mailer = $this->getMailer();
        $message = (new Swift_Message())
            ->setCharset('utf-8')
            ->setSubject('[Swift Mailer] InternationalSmokeTest (διεθνής)')
            ->setFrom([SWIFT_SMOKE_EMAIL_ADDRESS => 'Χριστοφορου (Swift Mailer)'])
            ->setTo(SWIFT_SMOKE_EMAIL_ADDRESS)
            ->setBody('This message should contain an attached ZIP file (named "κείμενο, εδάφιο, θέμα.zip").'.PHP_EOL.
                'When unzipped, the archive should produce a text file which reads:'.PHP_EOL.
                '"This is part of a Swift Mailer smoke test."'.PHP_EOL.
                PHP_EOL.
                'Following is some arbitrary Greek text:'.PHP_EOL.
                'Δεν βρέθηκαν λέξεις.'
                )
            ->attach(Swift_Attachment::fromPath($this->attFile)
                ->setContentType('application/zip')
                ->setFilename('κείμενο, εδάφιο, θέμα.zip')
                )
            ;
        $this->assertEquals(1, $mailer->send($message),
            '%s: The smoke test should send a single message'
            );
    }
}


================================================
FILE: tests/smoke.conf.php.default
================================================
<?php

/*
 Swift Mailer smoke test configuration.

 YOU ONLY NEED TO EDIT THIS FILE IF YOU WISH TO RUN THE SMOKE TESTS.

 The smoke tests are run by default when "All Tests" are run with the
 testing suite, however, without configuration options here only the unit tests
 will be run and the smoke tests will be skipped.
 */

/*
 Defines: The an address which Swift can send to (it will also send "from" this address).
 Recommended: (your own email address?)
 */
define('SWIFT_SMOKE_EMAIL_ADDRESS', 'test@swiftmailer.org');

/*
 Defines: The specific transport you want to mail with.
 Recommended: Any of 'smtp', 'sendmail' or 'mail'
 */
define('SWIFT_SMOKE_TRANSPORT_TYPE', 'smtp');

// SMTP-specific settings

/*
 Defines: An SMTP server to connect to
 Recommended: smtp.your-isp.com (varies wildly!)
 */
define('SWIFT_SMOKE_SMTP_HOST', 'localhost');

/*
 Defines: The SMTP port to connect to
 Recommended: 25
 */
define('SWIFT_SMOKE_SMTP_PORT', '4456');

/*
 Defines: A username to authenticate with SMTP (if needed).
 Recommended: (none)
 */
define('SWIFT_SMOKE_SMTP_USER', '');

/*
 Defines: A password to authenticate with SMTP (if needed).
 Recommended: (none)
 */
define('SWIFT_SMOKE_SMTP_PASS', '');

/*
 Defines: The encryption needed on your SMTP server.
 Recommended: (none), or 'tls' or 'ssl'
 */
define('SWIFT_SMOKE_SMTP_ENCRYPTION', '');

// Sendmail specific settings

/*
 Defines: The command to use when sending via sendmail
 Recommended: /usr/sbin/sendmail -bs (or "-oi -t")
 */
define('SWIFT_SMOKE_SENDMAIL_COMMAND', '/usr/sbin/sendmail -bs');


================================================
FILE: tests/unit/Swift/ByteStream/ArrayByteStreamTest.php
================================================
<?php

class Swift_ByteStream_ArrayByteStreamTest extends \PHPUnit\Framework\TestCase
{
    public function testReadingSingleBytesFromBaseInput()
    {
        $input = ['a', 'b', 'c'];
        $bs = $this->createArrayStream($input);
        $output = [];
        while (false !== $bytes = $bs->read(1)) {
            $output[] = $bytes;
        }
        $this->assertEquals($input, $output,
            '%s: Bytes read from stream should be the same as bytes in constructor'
            );
    }

    public function testReadingMultipleBytesFromBaseInput()
    {
        $input = ['a', 'b', 'c', 'd'];
        $bs = $this->createArrayStream($input);
        $output = [];
        while (false !== $bytes = $bs->read(2)) {
            $output[] = $bytes;
        }
        $this->assertEquals(['ab', 'cd'], $output,
            '%s: Bytes read from stream should be in pairs'
            );
    }

    public function testReadingOddOffsetOnLastByte()
    {
        $input = ['a', 'b', 'c', 'd', 'e'];
        $bs = $this->createArrayStream($input);
        $output = [];
        while (false !== $bytes = $bs->read(2)) {
            $output[] = $bytes;
        }
        $this->assertEquals(['ab', 'cd', 'e'], $output,
            '%s: Bytes read from stream should be in pairs except final read'
            );
    }

    public function testSettingPointerPartway()
    {
        $input = ['a', 'b', 'c'];
        $bs = $this->createArrayStream($input);
        $bs->setReadPointer(1);
        $this->assertEquals('b', $bs->read(1),
            '%s: Byte should be second byte since pointer as at offset 1'
            );
    }

    public function testResettingPointerAfterExhaustion()
    {
        $input = ['a', 'b', 'c'];

        $bs = $this->createArrayStream($input);
        while (false !== $bs->read(1));

        $bs->setReadPointer(0);
        $this->assertEquals('a', $bs->read(1),
            '%s: Byte should be first byte since pointer as at offset 0'
            );
    }

    public function testPointerNeverSetsBelowZero()
    {
        $input = ['a', 'b', 'c'];
        $bs = $this->createArrayStream($input);

        $bs->setReadPointer(-1);
        $this->assertEquals('a', $bs->read(1),
            '%s: Byte should be first byte since pointer should be at offset 0'
            );
    }

    public function testPointerNeverSetsAboveStackSize()
    {
        $input = ['a', 'b', 'c'];
        $bs = $this->createArrayStream($input);

        $bs->setReadPointer(3);
        $this->assertFalse($bs->read(1),
            '%s: Stream should be at end and thus return false'
            );
    }

    public function testBytesCanBeWrittenToStream()
    {
        $input = ['a', 'b', 'c'];
        $bs = $this->createArrayStream($input);

        $bs->write('de');

        $output = [];
        while (false !== $bytes = $bs->read(1)) {
            $output[] = $bytes;
        }
        $this->assertEquals(['a', 'b', 'c', 'd', 'e'], $output,
            '%s: Bytes read from stream should be from initial stack + written'
            );
    }

    public function testContentsCanBeFlushed()
    {
        $input = ['a', 'b', 'c'];
        $bs = $this->createArrayStream($input);

        $bs->flushBuffers();

        $this->assertFalse($bs->read(1),
            '%s: Contents have been flushed so read() should return false'
            );
    }

    public function testConstructorCanTakeStringArgument()
    {
        $bs = $this->createArrayStream('abc');
        $output = [];
        while (false !== $bytes = $bs->read(1)) {
            $output[] = $bytes;
        }
        $this->assertEquals(['a', 'b', 'c'], $output,
            '%s: Bytes read from stream should be the same as bytes in constructor'
            );
    }

    public function testBindingOtherStreamsMirrorsWriteOperations()
    {
        $bs = $this->createArrayStream('');
        $is1 = $this->getMockBuilder('Swift_InputByteStream')->getMock();
        $is2 = $this->getMockBuilder('Swift_InputByteStream')->getMock();

        $is1->expects($this->exactly(2))
            ->method('write')
            ->withConsecutive(
                ['x'],
                ['y']
            );
        $is2->expects($this->exactly(2))
            ->method('write')
            ->withConsecutive(
                ['x'],
                ['y']
            );

        $bs->bind($is1);
        $bs->bind($is2);

        $bs->write('x');
        $bs->write('y');
    }

    public function testBindingOtherStreamsMirrorsFlushOperations()
    {
        $bs = $this->createArrayStream('');
        $is1 = $this->getMockBuilder('Swift_InputByteStream')->getMock();
        $is2 = $this->getMockBuilder('Swift_InputByteStream')->getMock();

        $is1->expects($this->once())
            ->method('flushBuffers');
        $is2->expects($this->once())
            ->method('flushBuffers');

        $bs->bind($is1);
        $bs->bind($is2);

        $bs->flushBuffers();
    }

    public function testUnbindingStreamPreventsFurtherWrites()
    {
        $bs = $this->createArrayStream('');
        $is1 = $this->getMockBuilder('Swift_InputByteStream')->getMock();
        $is2 = $this->getMockBuilder('Swift_InputByteStream')->getMock();

        $is1->expects($this->exactly(2))
            ->method('write')
            ->withConsecutive(
                ['x'],
                ['y']
            );
        $is2->expects($this->once())
            ->method('write')
            ->with('x');

        $bs->bind($is1);
        $bs->bind($is2);

        $bs->write('x');

        $bs->unbind($is2);

        $bs->write('y');
    }

    private function createArrayStream($input)
    {
        return new Swift_ByteStream_ArrayByteStream($input);
    }
}


================================================
FILE: tests/unit/Swift/CharacterReader/GenericFixedWidthReaderTest.php
================================================
<?php

class Swift_CharacterReader_GenericFixedWidthReaderTest extends \PHPUnit\Framework\TestCase
{
    public function testInitialByteSizeMatchesWidth()
    {
        $reader = new Swift_CharacterReader_GenericFixedWidthReader(1);
        $this->assertSame(1, $reader->getInitialByteSize());

        $reader = new Swift_CharacterReader_GenericFixedWidthReader(4);
        $this->assertSame(4, $reader->getInitialByteSize());
    }

    public function testValidationValueIsBasedOnOctetCount()
    {
        $reader = new Swift_CharacterReader_GenericFixedWidthReader(4);

        $this->assertSame(
            1, $reader->validateByteSequence([0x01, 0x02, 0x03], 3)
            ); //3 octets

        $this->assertSame(
            2, $reader->validateByteSequence([0x01, 0x0A], 2)
            ); //2 octets

        $this->assertSame(
            3, $reader->validateByteSequence([0xFE], 1)
            ); //1 octet

        $this->assertSame(
            0, $reader->validateByteSequence([0xFE, 0x03, 0x67, 0x9A], 4)
            ); //All 4 octets
    }

    public function testValidationFailsIfTooManyOctets()
    {
        $reader = new Swift_CharacterReader_GenericFixedWidthReader(6);

        $this->assertSame(-1, $reader->validateByteSequence(
            [0xFE, 0x03, 0x67, 0x9A, 0x10, 0x09, 0x85], 7
            )); //7 octets
    }
}


================================================
FILE: tests/unit/Swift/CharacterReader/UsAsciiReaderTest.php
================================================
<?php

class Swift_CharacterReader_UsAsciiReaderTest extends \PHPUnit\Framework\TestCase
{
    /*

    for ($c = '', $size = 1; false !== $bytes = $os->read($size); ) {
        $c .= $bytes;
        $size = $v->validateCharacter($c);
        if (-1 == $size) {
            throw new Exception( ... invalid char .. );
        } elseif (0 == $size) {
            return $c; //next character in $os
        }
    }

    */

    private $reader;

    protected function setUp()
    {
        $this->reader = new Swift_CharacterReader_UsAsciiReader();
    }

    public function testAllValidAsciiCharactersReturnZero()
    {
        for ($ordinal = 0x00; $ordinal <= 0x7F; ++$ordinal) {
            $this->assertSame(
                0, $this->reader->validateByteSequence([$ordinal], 1)
                );
        }
    }

    public function testMultipleBytesAreInvalid()
    {
        for ($ordinal = 0x00; $ordinal <= 0x7F; $ordinal += 2) {
            $this->assertSame(
                -1, $this->reader->validateByteSequence([$ordinal, $ordinal + 1], 2)
                );
        }
    }

    public function testBytesAboveAsciiRangeAreInvalid()
    {
        for ($ordinal = 0x80; $ordinal <= 0xFF; ++$ordinal) {
            $this->assertSame(
                -1, $this->reader->validateByteSequence([$ordinal], 1)
                );
        }
    }
}


================================================
FILE: tests/unit/Swift/CharacterReader/Utf8ReaderTest.php
================================================
<?php

class Swift_CharacterReader_Utf8ReaderTest extends \PHPUnit\Framework\TestCase
{
    private $reader;

    protected function setUp()
    {
        $this->reader = new Swift_CharacterReader_Utf8Reader();
    }

    public function testLeading7BitOctetCausesReturnZero()
    {
        for ($ordinal = 0x00; $ordinal <= 0x7F; ++$ordinal) {
            $this->assertSame(
                0, $this->reader->validateByteSequence([$ordinal], 1)
                );
        }
    }

    public function testLeadingByteOf2OctetCharCausesReturn1()
    {
        for ($octet = 0xC0; $octet <= 0xDF; ++$octet) {
            $this->assertSame(
                1, $this->reader->validateByteSequence([$octet], 1)
                );
        }
    }

    public function testLeadingByteOf3OctetCharCausesReturn2()
    {
        for ($octet = 0xE0; $octet <= 0xEF; ++$octet) {
            $this->assertSame(
                2, $this->reader->validateByteSequence([$octet], 1)
                );
        }
    }

    public function testLeadingByteOf4OctetCharCausesReturn3()
    {
        for ($octet = 0xF0; $octet <= 0xF7; ++$octet) {
            $this->assertSame(
                3, $this->reader->validateByteSequence([$octet], 1)
                );
        }
    }

    public function testLeadingByteOf5OctetCharCausesReturn4()
    {
        for ($octet = 0xF8; $octet <= 0xFB; ++$octet) {
            $this->assertSame(
                4, $this->reader->validateByteSequence([$octet], 1)
                );
        }
    }

    public function testLeadingByteOf6OctetCharCausesReturn5()
    {
        for ($octet = 0xFC; $octet <= 0xFD; ++$octet) {
            $this->assertSame(
                5, $this->reader->validateByteSequence([$octet], 1)
                );
        }
    }
}


================================================
FILE: tests/unit/Swift/CharacterStream/ArrayCharacterStreamTest.php
================================================
<?php

class Swift_CharacterStream_ArrayCharacterStreamTest extends \SwiftMailerTestCase
{
    public function testValidatorAlgorithmOnImportString()
    {
        $reader = $this->getReader();
        $factory = $this->getFactory($reader);

        $stream = new Swift_CharacterStream_ArrayCharacterStream($factory, 'utf-8');

        $reader->shouldReceive('getInitialByteSize')
               ->zeroOrMoreTimes()
               ->andReturn(1);
        $reader->shouldReceive('validateByteSequence')->once()->with([0xD0], 1)->andReturn(1);
        $reader->shouldReceive('validateByteSequence')->once()->with([0xD0], 1)->andReturn(1);
        $reader->shouldReceive('validateByteSequence')->once()->with([0xD0], 1)->andReturn(1);
        $reader->shouldReceive('validateByteSequence')->once()->with([0xD1], 1)->andReturn(1);
        $reader->shouldReceive('validateByteSequence')->once()->with([0xD0], 1)->andReturn(1);
        $reader->shouldReceive('validateByteSequence')->once()->with([0xD0], 1)->andReturn(1);

        $stream->importString(pack('C*',
            0xD0, 0x94,
            0xD0, 0xB6,
            0xD0, 0xBE,
            0xD1, 0x8D,
            0xD0, 0xBB,
            0xD0, 0xB0
            )
        );
    }

    public function testCharactersWrittenUseValidator()
    {
        $reader = $this->getReader();
        $factory = $this->getFactory($reader);

        $stream = new Swift_CharacterStream_ArrayCharacterStream($factory, 'utf-8');

        $reader->shouldReceive('getInitialByteSize')
               ->zeroOrMoreTimes()
               ->andReturn(1);
        $reader->shouldReceive('validateByteSequence')->once()->with([0xD0], 1)->andReturn(1);
        $reader->shouldReceive('validateByteSequence')->once()->with([0xD0], 1)->andReturn(1);
        $reader->shouldReceive('validateByteSequence')->once()->with([0xD0], 1)->andReturn(1);
        $reader->shouldReceive('validateByteSequence')->once()->with([0xD0], 1)->andReturn(1);
        $reader->shouldReceive('validateByteSequence')->once()->with([0xD1], 1)->andReturn(1);
        $reader->shouldReceive('validateByteSequence')->once()->with([0xD0], 1)->andReturn(1);
        $reader->shouldReceive('validateByteSequence')->once()->with([0xD1], 1)->andReturn(1);
        $reader->shouldReceive('validateByteSequence')->once()->with([0xD1], 1)->andReturn(1);

        $stream->importString(pack('C*', 0xD0, 0x94, 0xD0, 0xB6, 0xD0, 0xBE));

        $stream->write(pack('C*',
            0xD0, 0xBB,
            0xD1, 0x8E,
            0xD0, 0xB1,
            0xD1, 0x8B,
            0xD1, 0x85
            )
        );
    }

    public function testReadCharactersAreInTact()
    {
        $reader = $this->getReader();
        $factory = $this->getFactory($reader);

        $stream = new Swift_CharacterStream_ArrayCharacterStream($factory, 'utf-8');

        $reader->shouldReceive('getInitialByteSize')
               ->zeroOrMoreTimes()
               ->andReturn(1);
        //String
        $reader->shouldReceive('validateByteSequence')->once()->with([0xD0], 1)->andReturn(1);
        $reader->shouldReceive('validateByteSequence')->once()->with([0xD0], 1)->andReturn(1);
        $reader->shouldReceive('validateByteSequence')->once()->with([0xD0], 1)->andReturn(1);
        //Stream
        $reader->shouldReceive('validateByteSequence')->once()->with([0xD0], 1)->andReturn(1);
        $reader->shouldReceive('validateByteSequence')->once()->with([0xD1], 1)->andReturn(1);
        $reader->shouldReceive('validateByteSequence')->once()->with([0xD0], 1)->andReturn(1);
        $reader->shouldReceive('validateByteSequence')->once()->with([0xD1], 1)->andReturn(1);
        $reader->shouldReceive('validateByteSequence')->once()->with([0xD1], 1)->andReturn(1);

        $stream->importString(pack('C*', 0xD0, 0x94, 0xD0, 0xB6, 0xD0, 0xBE));

        $stream->write(pack('C*',
            0xD0, 0xBB,
            0xD1, 0x8E,
            0xD0, 0xB1,
            0xD1, 0x8B,
            0xD1, 0x85
            )
        );

        $this->assertIdenticalBinary(pack('C*', 0xD0, 0x94), $stream->read(1));
        $this->assertIdenticalBinary(
            pack('C*', 0xD0, 0xB6, 0xD0, 0xBE), $stream->read(2)
            );
        $this->assertIdenticalBinary(pack('C*', 0xD0, 0xBB), $stream->read(1));
        $this->assertIdenticalBinary(
            pack('C*', 0xD1, 0x8E, 0xD0, 0xB1, 0xD1, 0x8B), $stream->read(3)
            );
        $this->assertIdenticalBinary(pack('C*', 0xD1, 0x85), $stream->read(1));

        $this->assertFalse($stream->read(1));
    }

    public function testCharactersCanBeReadAsByteArrays()
    {
        $reader = $this->getReader();
        $factory = $this->getFactory($reader);

        $stream = new Swift_CharacterStream_ArrayCharacterStream($factory, 'utf-8');

        $reader->shouldReceive('getInitialByteSize')
               ->zeroOrMoreTimes()
               ->andReturn(1);
        //String
        $reader->shouldReceive('validateByteSequence')->once()->with([0xD0], 1)->andReturn(1);
        $reader->shouldReceive('validateByteSequence')->once()->with([0xD0], 1)->andReturn(1);
        $reader->shouldReceive('validateByteSequence')->once()->with([0xD0], 1)->andReturn(1);
        //Stream
        $reader->shouldReceive('validateByteSequence')->once()->with([0xD0], 1)->andReturn(1);
        $reader->shouldReceive('validateByteSequence')->once()->with([0xD1], 1)->andReturn(1);
        $reader->shouldReceive('validateByteSequence')->once()->with([0xD0], 1)->andReturn(1);
        $reader->shouldReceive('validateByteSequence')->once()->with([0xD1], 1)->andReturn(1);
        $reader->shouldReceive('validateByteSequence')->once()->with([0xD1], 1)->andReturn(1);

        $stream->importString(pack('C*', 0xD0, 0x94, 0xD0, 0xB6, 0xD0, 0xBE));

        $stream->write(pack('C*',
            0xD0, 0xBB,
            0xD1, 0x8E,
            0xD0, 0xB1,
            0xD1, 0x8B,
            0xD1, 0x85
            )
        );

        $this->assertEquals([0xD0, 0x94], $stream->readBytes(1));
        $this->assertEquals([0xD0, 0xB6, 0xD0, 0xBE], $stream->readBytes(2));
        $this->assertEquals([0xD0, 0xBB], $stream->readBytes(1));
        $this->assertEquals(
            [0xD1, 0x8E, 0xD0, 0xB1, 0xD1, 0x8B], $stream->readBytes(3)
            );
        $this->assertEquals([0xD1, 0x85], $stream->readBytes(1));

        $this->assertFalse($stream->readBytes(1));
    }

    public function testRequestingLargeCharCountPastEndOfStream()
    {
        $reader = $this->getReader();
        $factory = $this->getFactory($reader);

        $stream = new Swift_CharacterStream_ArrayCharacterStream($factory, 'utf-8');

        $reader->shouldReceive('getInitialByteSize')
               ->zeroOrMoreTimes()
               ->andReturn(1);
        $reader->shouldReceive('validateByteSequence')->once()->with([0xD0], 1)->andReturn(1);
        $reader->shouldReceive('validateByteSequence')->once()->with([0xD0], 1)->andReturn(1);
        $reader->shouldReceive('validateByteSequence')->once()->with([0xD0], 1)->andReturn(1);

        $stream->importString(pack('C*', 0xD0, 0x94, 0xD0, 0xB6, 0xD0, 0xBE));

        $this->assertIdenticalBinary(pack('C*', 0xD0, 0x94, 0xD0, 0xB6, 0xD0, 0xBE),
            $stream->read(100)
            );

        $this->assertFalse($stream->read(1));
    }

    public function testRequestingByteArrayCountPastEndOfStream()
    {
        $reader = $this->getReader();
        $factory = $this->getFactory($reader);

        $stream = new Swift_CharacterStream_ArrayCharacterStream($factory, 'utf-8');

        $reader->shouldReceive('getInitialByteSize')
               ->zeroOrMoreTimes()
               ->andReturn(1);
        $reader->shouldReceive('validateByteSequence')->once()->with([0xD0], 1)->andReturn(1);
        $reader->shouldReceive('validateByteSequence')->once()->with([0xD0], 1)->andReturn(1);
        $reader->shouldReceive('validateByteSequence')->once()->with([0xD0], 1)->andReturn(1);

        $stream->importString(pack('C*', 0xD0, 0x94, 0xD0, 0xB6, 0xD0, 0xBE));

        $this->assertEquals([0xD0, 0x94, 0xD0, 0xB6, 0xD0, 0xBE],
            $stream->readBytes(100)
            );

        $this->assertFalse($stream->readBytes(1));
    }

    public function testPointerOffsetCanBeSet()
    {
        $reader = $this->getReader();
        $factory = $this->getFactory($reader);

        $stream = new Swift_CharacterStream_ArrayCharacterStream($factory, 'utf-8');

        $reader->shouldReceive('getInitialByteSize')
               ->zeroOrMoreTimes()
               ->andReturn(1);
        $reader->shouldReceive('validateByteSequence')->once()->with([0xD0], 1)->andReturn(1);
        $reader->shouldReceive('validateByteSequence')->once()->with([0xD0], 1)->andReturn(1);
        $reader->shouldReceive('validateByteSequence')->once()->with([0xD0], 1)->andReturn(1);

        $stream->importString(pack('C*', 0xD0, 0x94, 0xD0, 0xB6, 0xD0, 0xBE));

        $this->assertIdenticalBinary(pack('C*', 0xD0, 0x94), $stream->read(1));

        $stream->setPointer(0);

        $this->assertIdenticalBinary(pack('C*', 0xD0, 0x94), $stream->read(1));

        $stream->setPointer(2);

        $this->assertIdenticalBinary(pack('C*', 0xD0, 0xBE), $stream->read(1));
    }

    public function testContentsCanBeFlushed()
    {
        $reader = $this->getReader();
        $factory = $this->getFactory($reader);

        $stream = new Swift_CharacterStream_ArrayCharacterStream($factory, 'utf-8');

        $reader->shouldReceive('getInitialByteSize')
               ->zeroOrMoreTimes()
               ->andReturn(1);
        $reader->shouldReceive('validateByteSequence')->once()->with([0xD0], 1)->andReturn(1);
        $reader->shouldReceive('validateByteSequence')->once()->with([0xD0], 1)->andReturn(1);
        $reader->shouldReceive('validateByteSequence')->once()->with([0xD0], 1)->andReturn(1);

        $stream->importString(pack('C*', 0xD0, 0x94, 0xD0, 0xB6, 0xD0, 0xBE));

        $stream->flushContents();

        $this->assertFalse($stream->read(1));
    }

    public function testByteStreamCanBeImportingUsesValidator()
    {
        $reader = $this->getReader();
        $factory = $this->getFactory($reader);
        $os = $this->getByteStream();

        $stream = new Swift_CharacterStream_ArrayCharacterStream($factory, 'utf-8');

        $os->shouldReceive('setReadPointer')
           ->between(0, 1)
           ->with(0);
        $os->shouldReceive('read')->once()->andReturn(pack('C*', 0xD0));
        $os->shouldReceive('read')->once()->andReturn(pack('C*', 0x94));
        $os->shouldReceive('read')->once()->andReturn(pack('C*', 0xD0));
        $os->shouldReceive('read')->once()->andReturn(pack('C*', 0xB6));
        $os->shouldReceive('read')->once()->andReturn(pack('C*', 0xD0));
        $os->shouldReceive('read')->once()->andReturn(pack('C*', 0xBE));
        $os->shouldReceive('read')
           ->zeroOrMoreTimes()
           ->andReturn(false);

        $reader->shouldReceive('getInitialByteSize')
               ->zeroOrMoreTimes()
               ->andReturn(1);
        $reader->shouldReceive('validateByteSequence')->once()->with([0xD0], 1)->andReturn(1);
        $reader->shouldReceive('validateByteSequence')->once()->with([0xD0], 1)->andReturn(1);
        $reader->shouldReceive('validateByteSequence')->once()->with([0xD0], 1)->andReturn(1);

        $stream->flushContents();
        $stream->importByteStream($os);
    }

    public function testImportingStreamProducesCorrectCharArray()
    {
        $reader = $this->getReader();
        $factory = $this->getFactory($reader);
        $os = $this->getByteStream();

        $stream = new Swift_CharacterStream_ArrayCharacterStream($factory, 'utf-8');

        $os->shouldReceive('setReadPointer')
           ->between(0, 1)
           ->with(0);
        $os->shouldReceive('read')->once()->andReturn(pack('C*', 0xD0));
        $os->shouldReceive('read')->once()->andReturn(pack('C*', 0x94));
        $os->shouldReceive('read')->once()->andReturn(pack('C*', 0xD0));
        $os->shouldReceive('read')->once()->andReturn(pack('C*', 0xB6));
        $os->shouldReceive('read')->once()->andReturn(pack('C*', 0xD0));
        $os->shouldReceive('read')->once()->andReturn(pack('C*', 0xBE));
        $os->shouldReceive('read')
           ->zeroOrMoreTimes()
           ->andReturn(false);

        $reader->shouldReceive('getInitialByteSize')
               ->zeroOrMoreTimes()
               ->andReturn(1);
        $reader->shouldReceive('validateByteSequence')->once()->with([0xD0], 1)->andReturn(1);
        $reader->shouldReceive('validateByteSequence')->once()->with([0xD0], 1)->andReturn(1);
        $reader->shouldReceive('validateByteSequence')->once()->with([0xD0], 1)->andReturn(1);

        $stream->flushContents();
        $stream->importByteStream($os);

        $this->assertIdenticalBinary(pack('C*', 0xD0, 0x94), $stream->read(1));
        $this->assertIdenticalBinary(pack('C*', 0xD0, 0xB6), $stream->read(1));
        $this->assertIdenticalBinary(pack('C*', 0xD0, 0xBE), $stream->read(1));

        $this->assertFalse($stream->read(1));
    }

    public function testAlgorithmWithFixedWidthCharsets()
    {
        $reader = $this->getReader();
        $factory = $this->getFactory($reader);

        $reader->shouldReceive('getInitialByteSize')
               ->zeroOrMoreTimes()
               ->andReturn(2);
        $reader->shouldReceive('validateByteSequence')->once()->with([0xD1, 0x8D], 2);
        $reader->shouldReceive('validateByteSequence')->once()->with([0xD0, 0xBB], 2);
        $reader->shouldReceive('validateByteSequence')->once()->with([0xD0, 0xB0], 2);

        $stream = new Swift_CharacterStream_ArrayCharacterStream(
            $factory, 'utf-8'
        );
        $stream->importString(pack('C*', 0xD1, 0x8D, 0xD0, 0xBB, 0xD0, 0xB0));

        $this->assertIdenticalBinary(pack('C*', 0xD1, 0x8D), $stream->read(1));
        $this->assertIdenticalBinary(pack('C*', 0xD0, 0xBB), $stream->read(1));
        $this->assertIdenticalBinary(pack('C*', 0xD0, 0xB0), $stream->read(1));

        $this->assertFalse($stream->read(1));
    }

    private function getReader()
    {
        return $this->getMockery('Swift_CharacterReader');
    }

    private function getFactory($reader)
    {
        $factory = $this->getMockery('Swift_CharacterReaderFactory');
        $factory->shouldReceive('getReaderFor')
                ->zeroOrMoreTimes()
                ->with('utf-8')
                ->andReturn($reader);

        return $factory;
    }

    private function getByteStream()
    {
        return $this->getMockery('Swift_OutputByteStream');
    }
}


================================================
FILE: tests/unit/Swift/DependencyContainerTest.php
================================================
<?php

class One
{
    public $arg1;
    public $arg2;

    public function __construct($arg1 = null, $arg2 = null)
    {
        $this->arg1 = $arg1;
        $this->arg2 = $arg2;
    }
}

class Swift_DependencyContainerTest extends \PHPUnit\Framework\TestCase
{
    private $container;

    protected function setUp()
    {
        $this->container = new Swift_DependencyContainer();
    }

    public function testRegisterAndLookupValue()
    {
        $this->container->register('foo')->asValue('bar');
        $this->assertEquals('bar', $this->container->lookup('foo'));
    }

    public function testHasReturnsTrueForRegisteredValue()
    {
        $this->container->register('foo')->asValue('bar');
        $this->assertTrue($this->container->has('foo'));
    }

    public function testHasReturnsFalseForUnregisteredValue()
    {
        $this->assertFalse($this->container->has('foo'));
    }

    public function testRegisterAndLookupNewInstance()
    {
        $this->container->register('one')->asNewInstanceOf('One');
        $this->assertInstanceOf('One', $this->container->lookup('one'));
    }

    public function testHasReturnsTrueForRegisteredInstance()
    {
        $this->container->register('one')->asNewInstanceOf('One');
        $this->assertTrue($this->container->has('one'));
    }

    public function testNewInstanceIsAlwaysNew()
    {
        $this->container->register('one')->asNewInstanceOf('One');
        $a = $this->container->lookup('one');
        $b = $this->container->lookup('one');
        $this->assertEquals($a, $b);
    }

    public function testRegisterAndLookupSharedInstance()
    {
        $this->container->register('one')->asSharedInstanceOf('One');
        $this->assertInstanceOf('One', $this->container->lookup('one'));
    }

    public function testHasReturnsTrueForSharedInstance()
    {
        $this->container->register('one')->asSharedInstanceOf('One');
        $this->assertTrue($this->container->has('one'));
    }

    public function testMultipleSharedInstancesAreSameInstance()
    {
        $this->container->register('one')->asSharedInstanceOf('One');
        $a = $this->container->lookup('one');
        $b = $this->container->lookup('one');
        $this->assertEquals($a, $b);
    }

    public function testRegisterAndLookupArray()
    {
        $this->container->register('One')->asArray();
        $this->assertSame([], $this->container->lookup('One'));
    }

    public function testNewInstanceWithDependencies()
    {
        $this->container->register('foo')->asValue('FOO');
        $this->container->register('one')->asNewInstanceOf('One')
            ->withDependencies(['foo']);
        $obj = $this->container->lookup('one');
        $this->assertSame('FOO', $obj->arg1);
    }

    public function testNewInstanceWithMultipleDependencies()
    {
        $this->container->register('foo')->asValue('FOO');
        $this->container->register('bar')->asValue(42);
        $this->container->register('one')->asNewInstanceOf('One')
            ->withDependencies(['foo', 'bar']);
        $obj = $this->container->lookup('one');
        $this->assertSame('FOO', $obj->arg1);
        $this->assertSame(42, $obj->arg2);
    }

    public function testNewInstanceWithInjectedObjects()
    {
        $this->container->register('foo')->asValue('FOO');
        $this->container->register('one')->asNewInstanceOf('One');
        $this->container->register('two')->asNewInstanceOf('One')
            ->withDependencies(['one', 'foo']);
        $obj = $this->container->lookup('two');
        $this->assertEquals($this->container->lookup('one'), $obj->arg1);
        $this->assertSame('FOO', $obj->arg2);
    }

    public function testNewInstanceWithAddConstructorValue()
    {
        $this->container->register('one')->asNewInstanceOf('One')
            ->addConstructorValue('x')
            ->addConstructorValue(99);
        $obj = $this->container->lookup('one');
        $this->assertSame('x', $obj->arg1);
        $this->assertSame(99, $obj->arg2);
    }

    public function testNewInstanceWithAddConstructorLookup()
    {
        $this->container->register('foo')->asValue('FOO');
        $this->container->register('bar')->asValue(42);
        $this->container->register('one')->asNewInstanceOf('One')
            ->addConstructorLookup('foo')
            ->addConstructorLookup('bar');

        $obj = $this->container->lookup('one');
        $this->assertSame('FOO', $obj->arg1);
        $this->assertSame(42, $obj->arg2);
    }

    public function testResolvedDependenciesCanBeLookedUp()
    {
        $this->container->register('foo')->asValue('FOO');
        $this->container->register('one')->asNewInstanceOf('One');
        $this->container->register('two')->asNewInstanceOf('One')
            ->withDependencies(['one', 'foo']);
        $deps = $this->container->createDependenciesFor('two');
        $this->assertEquals(
            [$this->container->lookup('one'), 'FOO'], $deps
            );
    }

    public function testArrayOfDependenciesCanBeSpecified()
    {
        $this->container->register('foo')->asValue('FOO');
        $this->container->register('one')->asNewInstanceOf('One');
        $this->container->register('two')->asNewInstanceOf('One')
            ->withDependencies([['one', 'foo'], 'foo']);

        $obj = $this->container->lookup('two');
        $this->assertEquals([$this->container->lookup('one'), 'FOO'], $obj->arg1);
        $this->assertSame('FOO', $obj->arg2);
    }

    public function testArrayWithDependencies()
    {
        $this->container->register('foo')->asValue('FOO');
        $this->container->register('bar')->asValue(42);
        $this->container->register('one')->asArray('One')
            ->withDependencies(['foo', 'bar']);
        $this->assertSame(['FOO', 42], $this->container->lookup('one'));
    }

    public function testAliasCanBeSet()
    {
        $this->container->register('foo')->asValue('FOO');
        $this->container->register('bar')->asAliasOf('foo');

        $this->assertSame('FOO', $this->container->lookup('bar'));
    }

    public function testAliasOfAliasCanBeSet()
    {
        $this->container->register('foo')->asValue('FOO');
        $this->container->register('bar')->asAliasOf('foo');
        $this->container->register('zip')->asAliasOf('bar');
        $this->container->register('button')->asAliasOf('zip');

        $this->assertSame('FOO', $this->container->lookup('button'));
    }
}


================================================
FILE: tests/unit/Swift/Encoder/Base64EncoderTest.php
================================================
<?php

class Swift_Encoder_Base64EncoderTest extends \PHPUnit\Framework\TestCase
{
    private $encoder;

    protected function setUp()
    {
        $this->encoder = new Swift_Encoder_Base64Encoder();
    }

    /*
    There's really no point in testing the entire base64 encoding to the
    level QP encoding has been tested.  base64_encode() has been in PHP for
    years.
    */

    public function testInputOutputRatioIs3to4Bytes()
    {
        /*
        RFC 2045, 6.8

         The encoding process represents 24-bit groups of input bits as output
         strings of 4 encoded characters.  Proceeding from left to right, a
         24-bit input group is formed by concatenating 3 8bit input groups.
         These 24 bits are then treated as 4 concatenated 6-bit groups, each
         of which is translated into a single digit in the base64 alphabet.
         */

        $this->assertEquals(
            'MTIz', $this->encoder->encodeString('123'),
            '%s: 3 bytes of input should yield 4 bytes of output'
            );
        $this->assertEquals(
            'MTIzNDU2', $this->encoder->encodeString('123456'),
            '%s: 6 bytes in input should yield 8 bytes of output'
            );
        $this->assertEquals(
            'MTIzNDU2Nzg5', $this->encoder->encodeString('123456789'),
            '%s: 9 bytes in input should yield 12 bytes of output'
            );
    }

    public function testPadLength()
    {
        /*
        RFC 2045, 6.8

       Special processing is performed if fewer than 24 bits are available
       at the end of the data being encoded.  A full encoding quantum is
       always completed at the end of a body.  When fewer than 24 input bits
       are available in an input group, zero bits are added (on the right)
       to form an integral number of 6-bit groups.  Padding at the end of
       the data is performed using the "=" character.  Since all base64
       input is an integral number of octets, only the following cases can
       arise: (1) the final quantum of encoding input is an integral
       multiple of 24 bits; here, the final unit of encoded output will be
       an integral multiple of 4 characters with no "=" padding, (2) the
       final quantum of encoding input is exactly 8 bits; here, the final
       unit of encoded output will be two characters followed by two "="
       padding characters, or (3) the final quantum of encoding input is
       exactly 16 bits; here, the final unit of encoded output will be three
       characters followed by one "=" padding character.
       */

        for ($i = 0; $i < 30; ++$i) {
            $input = pack('C', random_int(0, 255));
            $this->assertMatchesRegularExpression(
                '~^[a-zA-Z0-9/\+]{2}==$~', $this->encoder->encodeString($input),
                '%s: A single byte should have 2 bytes of padding'
                );
        }

        for ($i = 0; $i < 30; ++$i) {
            $input = pack('C*', random_int(0, 255), random_int(0, 255));
            $this->assertMatchesRegularExpression(
                '~^[a-zA-Z0-9/\+]{3}=$~', $this->encoder->encodeString($input),
                '%s: Two bytes should have 1 byte of padding'
                );
        }

        for ($i = 0; $i < 30; ++$i) {
            $input = pack('C*', random_int(0, 255), random_int(0, 255), random_int(0, 255));
            $this->assertMatchesRegularExpression(
                '~^[a-zA-Z0-9/\+]{4}$~', $this->encoder->encodeString($input),
                '%s: Three bytes should have no padding'
                );
        }
    }

    public function testMaximumLineLengthIs76Characters()
    {
        /*
         The encoded output stream must be represented in lines of no more
         than 76 characters each.  All line breaks or other characters not
         found in Table 1 must be ignored by decoding software.
         */

        $input =
        'abcdefghijklmnopqrstuvwxyz'.
        'ABCDEFGHIJKLMNOPQRSTUVWXYZ'.
        '1234567890'.
        'abcdefghijklmnopqrstuvwxyz'.
        'ABCDEFGHIJKLMNOPQRSTUVWXYZ'.
        '1234567890'.
        'ABCDEFGHIJKLMNOPQRSTUVWXYZ';

        $output =
        'YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXpBQk'.//38
        'NERUZHSElKS0xNTk9QUVJTVFVWV1hZWjEyMzQ1'."\r\n".//76 *
        'Njc4OTBhYmNkZWZnaGlqa2xtbm9wcXJzdHV2d3'.//38
        'h5ekFCQ0RFRkdISUpLTE1OT1BRUlNUVVZXWFla'."\r\n".//76 *
        'MTIzNDU2Nzg5MEFCQ0RFRkdISUpLTE1OT1BRUl'.//38
        'NUVVZXWFla';                                       //48

        $this->assertEquals(
            $output, $this->encoder->encodeString($input),
            '%s: Lines should be no more than 76 characters'
            );
    }

    public function testMaximumLineLengthCanBeSpecified()
    {
        $input =
        'abcdefghijklmnopqrstuvwxyz'.
        'ABCDEFGHIJKLMNOPQRSTUVWXYZ'.
        '1234567890'.
        'abcdefghijklmnopqrstuvwxyz'.
        'ABCDEFGHIJKLMNOPQRSTUVWXYZ'.
        '1234567890'.
        'ABCDEFGHIJKLMNOPQRSTUVWXYZ';

        $output =
        'YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXpBQk'.//38
        'NERUZHSElKS0'."\r\n".//50 *
        'xNTk9QUVJTVFVWV1hZWjEyMzQ1Njc4OTBhYmNk'.//38
        'ZWZnaGlqa2xt'."\r\n".//50 *
        'bm9wcXJzdHV2d3h5ekFCQ0RFRkdISUpLTE1OT1'.//38
        'BRUlNUVVZXWF'."\r\n".//50 *
        'laMTIzNDU2Nzg5MEFCQ0RFRkdISUpLTE1OT1BR'.//38
        'UlNUVVZXWFla';                                     //50 *

        $this->assertEquals(
            $output, $this->encoder->encodeString($input, 0, 50),
            '%s: Lines should be no more than 100 characters'
            );
    }

    public function testFirstLineLengthCanBeDifferent()
    {
        $input =
        'abcdefghijklmnopqrstuvwxyz'.
        'ABCDEFGHIJKLMNOPQRSTUVWXYZ'.
        '1234567890'.
        'abcdefghijklmnopqrstuvwxyz'.
        'ABCDEFGHIJKLMNOPQRSTUVWXYZ'.
        '1234567890'.
        'ABCDEFGHIJKLMNOPQRSTUVWXYZ';

        $output =
        'YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXpBQk'.//38
        'NERUZHSElKS0xNTk9QU'."\r\n".//57 *
        'VJTVFVWV1hZWjEyMzQ1Njc4OTBhYmNkZWZnaGl'.//38
        'qa2xtbm9wcXJzdHV2d3h5ekFCQ0RFRkdISUpLT'."\r\n".//76 *
        'E1OT1BRUlNUVVZXWFlaMTIzNDU2Nzg5MEFCQ0R'.//38
        'FRkdISUpLTE1OT1BRUlNUVVZXWFla';                    //67

        $this->assertEquals(
            $output, $this->encoder->encodeString($input, 19),
            '%s: First line offset is 19 so first line should be 57 chars long'
            );
    }
}


================================================
FILE: tests/unit/Swift/Encoder/QpEncoderTest.php
================================================
<?php

class Swift_Encoder_QpEncoderTest extends \SwiftMailerTestCase
{
    /* -- RFC 2045, 6.7 --
    (1)   (General 8bit representation) Any octet, except a CR or
                    LF that is part of a CRLF line break of the canonical
                    (standard) form of the data being encoded, may be
                    represented by an "=" followed by a two digit
                    hexadecimal representation of the octet's value.  The
                    digits of the hexadecimal alphabet, for this purpose,
                    are "0123456789ABCDEF".  Uppercase letters must be
                    used; lowercase letters are not allowed.  Thus, for
                    example, the decimal value 12 (US-ASCII form feed) can
                    be represented by "=0C", and the decimal value 61 (US-
                    ASCII EQUAL SIGN) can be represented by "=3D".  This
                    rule must be followed except when the following rules
                    allow an alternative encoding.
                    */

    public function testPermittedCharactersAreNotEncoded()
    {
        /* -- RFC 2045, 6.7 --
        (2)   (Literal representation) Octets with decimal values of
                    33 through 60 inclusive, and 62 through 126, inclusive,
                    MAY be represented as the US-ASCII characters which
                    correspond to those octets (EXCLAMATION POINT through
                    LESS THAN, and GREATER THAN through TILDE,
                    respectively).
                    */

        foreach (array_merge(range(33, 60), range(62, 126)) as $ordinal) {
            $char = \chr($ordinal);

            $charStream = $this->createCharStream();
            $charStream->shouldReceive('flushContents')
                       ->once();
            $charStream->shouldReceive('importString')
                       ->once()
                       ->with($char);
            $charStream->shouldReceive('readBytes')
                       ->once()
                       ->andReturn([$ordinal]);
            $charStream->shouldReceive('readBytes')
                       ->atLeast()->times(1)
                       ->andReturn(false);

            $encoder = new Swift_Encoder_QpEncoder($charStream);

            $this->assertIdenticalBinary($char, $encoder->encodeString($char));
        }
    }

    public function testWhiteSpaceAtLineEndingIsEncoded()
    {
        /* -- RFC 2045, 6.7 --
        (3)   (White Space) Octets with values of 9 and 32 MAY be
                    represented as US-ASCII TAB (HT) and SPACE characters,
                    respectively, but MUST NOT be so represented at the end
                    of an encoded line.  Any TAB (HT) or SPACE characters
                    on an encoded line MUST thus be followed on that line
                    by a printable character.  In particular, an "=" at the
                    end of an encoded line, indicating a soft line break
                    (see rule #5) may follow one or more TAB (HT) or SPACE
                    characters.  It follows that an octet with decimal
                    value 9 or 32 appearing at the end of an encoded line
                    must be represented according to Rule #1.  This rule is
                    necessary because some MTAs (Message Transport Agents,
                    programs which transport messages from one user to
                    another, or perform a portion of such transfers) are
                    known to pad lines of text with SPACEs, and others are
                    known to remove "white space" characters from the end
                    of a line.  Therefore, when decoding a Quoted-Printable
                    body, any trailing white space on a line must be
                    deleted, as it will necessarily have been added by
                    intermediate transport agents.
                    */

        $HT = \chr(0x09); //9
        $SPACE = \chr(0x20); //32

        //HT
        $string = 'a'.$HT.$HT."\r\n".'b';

        $charStream = $this->createCharStream();
        $charStream->shouldReceive('flushContents')
                    ->once();
        $charStream->shouldReceive('importString')
                    ->once()
                    ->with($string);

        $charStream->shouldReceive('readBytes')->once()->andReturn([\ord('a')]);
        $charStream->shouldReceive('readBytes')->once()->andReturn([0x09]);
        $charStream->shouldReceive('readBytes')->once()->andReturn([0x09]);
        $charStream->shouldReceive('readBytes')->once()->andReturn([0x0D]);
        $charStream->shouldReceive('readBytes')->once()->andReturn([0x0A]);
        $charStream->shouldReceive('readBytes')->once()->andReturn([\ord('b')]);
        $charStream->shouldReceive('readBytes')->once()->andReturn(false);

        $encoder = new Swift_Encoder_QpEncoder($charStream);
        $this->assertEquals(
            'a'.$HT.'=09'."\r\n".'b',
            $encoder->encodeString($string)
            );

        //SPACE
        $string = 'a'.$SPACE.$SPACE."\r\n".'b';

        $charStream = $this->createCharStream();
        $charStream->shouldReceive('flushContents')
                    ->once();
        $charStream->shouldReceive('importString')
                    ->once()
                    ->with($string);

        $charStream->shouldReceive('readBytes')->once()->andReturn([\ord('a')]);
        $charStream->shouldReceive('readBytes')->once()->andReturn([0x20]);
        $charStream->shouldReceive('readBytes')->once()->andReturn([0x20]);
        $charStream->shouldReceive('readBytes')->once()->andReturn([0x0D]);
        $charStream->shouldReceive('readBytes')->once()->andReturn([0x0A]);
        $charStream->shouldReceive('readBytes')->once()->andReturn([\ord('b')]);
        $charStream->shouldReceive('readBytes')->once()->andReturn(false);

        $encoder = new Swift_Encoder_QpEncoder($charStream);
        $this->assertEquals(
            'a'.$SPACE.'=20'."\r\n".'b',
            $encoder->encodeString($string)
            );
    }

    public function testCRLFIsLeftAlone()
    {
        /*
        (4)   (Line Breaks) A line break in a text body, represented
                    as a CRLF sequence in the text canonical form, must be
                    represented by a (RFC 822) line break, which is also a
                    CRLF sequence, in the Quoted-Printable encoding.  Since
                    the canonical representation of media types other than
                    text do not generally include the representation of
                    line breaks as CRLF sequences, no hard line breaks
                    (i.e. line breaks that are intended to be meaningful
                    and to be displayed to the user) can occur in the
                    quoted-printable encoding of such types.  Sequences
                    like "=0D", "=0A", "=0A=0D" and "=0D=0A" will routinely
                    appear in non-text data represented in quoted-
                    printable, of course.

                    Note that many implementations may elect to encode the
                    local representation of various content types directly
                    rather than converting to canonical form first,
                    encoding, and then converting back to local
                    representation.  In particular, this may apply to plain
                    text material on systems that use newline conventions
                    other than a CRLF terminator sequence.  Such an
                    implementation optimization is permissible, but only
                    when the combined canonicalization-encoding step is
                    equivalent to performing the three steps separately.
                    */

        $string = 'a'."\r\n".'b'."\r\n".'c'."\r\n";

        $charStream = $this->createCharStream();
        $charStream->shouldReceive('flushContents')
                    ->once();
        $charStream->shouldReceive('importString')
                    ->once()
                    ->with($string);

        $charStream->shouldReceive('readBytes')->once()->andReturn([\ord('a')]);
        $charStream->shouldReceive('readBytes')->once()->andReturn([0x0D]);
        $charStream->shouldReceive('readBytes')->once()->andReturn([0x0A]);
        $charStream->shouldReceive('readBytes')->once()->andReturn([\ord('b')]);
        $charStream->shouldReceive('readBytes')->once()->andReturn([0x0D]);
        $charStream->shouldReceive('readBytes')->once()->andReturn([0x0A]);
        $charStream->shouldReceive('readBytes')->once()->andReturn([\ord('c')]);
        $charStream->shouldReceive('readBytes')->once()->andReturn([0x0D]);
        $charStream->shouldReceive('readBytes')->once()->andReturn([0x0A]);
        $charStream->shouldReceive('readBytes')->once()->andReturn(false);

        $encoder = new Swift_Encoder_QpEncoder($charStream);
        $this->assertEquals($string, $encoder->encodeString($string));
    }

    public function testLinesLongerThan76CharactersAreSoftBroken()
    {
        /*
        (5)   (Soft Line Breaks) The Quoted-Printable encoding
                    REQUIRES that encoded lines be no more than 76
                    characters long.  If longer lines are to be encoded
                    with the Quoted-Printable encoding, "soft" line breaks
                    must be used.  An equal sign as the last character on a
                    encoded line indicates such a non-significant ("soft")
                    line break in the encoded text.
                    */

        $input = str_repeat('a', 140);

        $charStream = $this->createCharStream();
        $charStream->shouldReceive('flushContents')
                    ->once();
        $charStream->shouldReceive('importString')
                    ->once()
                    ->with($input);

        $output = '';
        for ($i = 0; $i < 140; ++$i) {
            $charStream->shouldReceive('readBytes')
                       ->once()
                       ->andReturn([\ord('a')]);

            if (75 == $i) {
                $output .= "=\r\n";
            }
            $output .= 'a';
        }

        $charStream->shouldReceive('readBytes')
                    ->once()
                    ->andReturn(false);

        $encoder = new Swift_Encoder_QpEncoder($charStream);
        $this->assertEquals($output, $encoder->encodeString($input));
    }

    public function testMaxLineLengthCanBeSpecified()
    {
        $input = str_repeat('a', 100);

        $charStream = $this->createCharStream();
        $charStream->shouldReceive('flushContents')
                    ->once();
        $charStream->shouldReceive('importString')
                    ->once()
                    ->with($input);

        $output = '';
        for ($i = 0; $i < 100; ++$i) {
            $charStream->shouldReceive('readBytes')
                       ->once()
                       ->andReturn([\ord('a')]);

            if (53 == $i) {
                $output .= "=\r\n";
            }
            $output .= 'a';
        }
        $charStream->shouldReceive('readBytes')
                    ->once()
                    ->andReturn(false);

        $encoder = new Swift_Encoder_QpEncoder($charStream);
        $this->assertEquals($output, $encoder->encodeString($input, 0, 54));
    }

    public function testBytesBelowPermittedRangeAreEncoded()
    {
        /*
        According to Rule (1 & 2)
        */

        foreach (range(0, 32) as $ordinal) {
            $char = \chr($ordinal);

            $charStream = $this->createCharStream();
            $charStream->shouldReceive('flushContents')
                       ->once();
            $charStream->shouldReceive('importString')
                       ->once()
                       ->with($char);
            $charStream->shouldReceive('readBytes')
                       ->once()
                       ->andReturn([$ordinal]);
            $charStream->shouldReceive('readBytes')
                       ->atLeast()->times(1)
                       ->andReturn(false);

            $encoder = new Swift_Encoder_QpEncoder($charStream);

            $this->assertEquals(
                sprintf('=%02X', $ordinal), $encoder->encodeString($char)
                );
        }
    }

    public function testDecimalByte61IsEncoded()
    {
        /*
        According to Rule (1 & 2)
        */

        $char = '=';

        $charStream = $this->createCharStream();
        $charStream->shouldReceive('flushContents')
                    ->once();
        $charStream->shouldReceive('importString')
                    ->once()
                    ->with($char);
        $charStream->shouldReceive('readBytes')
                    ->once()
                    ->andReturn([61]);
        $charStream->shouldReceive('readBytes')
                    ->atLeast()->times(1)
                    ->andReturn(false);

        $encoder = new Swift_Encoder_QpEncoder($charStream);

        $this->assertEquals('=3D', $encoder->encodeString('='));
    }

    public function testBytesAbovePermittedRangeAreEncoded()
    {
        /*
        According to Rule (1 & 2)
        */

        foreach (range(127, 255) as $ordinal) {
            $char = \chr($ordinal);

            $charStream = $this->createCharStream();
            $charStream->shouldReceive('flushContents')
                       ->once();
            $charStream->shouldReceive('importString')
                       ->once()
                       ->with($char);
            $charStream->shouldReceive('readBytes')
                       ->once()
                       ->andReturn([$ordinal]);
            $charStream->shouldReceive('readBytes')
                       ->atLeast()->times(1)
                       ->andReturn(false);

            $encoder = new Swift_Encoder_QpEncoder($charStream);

            $this->assertEquals(
                sprintf('=%02X', $ordinal), $encoder->encodeString($char)
                );
        }
    }

    public function testFirstLineLengthCanBeDifferent()
    {
        $input = str_repeat('a', 140);

        $charStream = $this->createCharStream();
        $charStream->shouldReceive('flushContents')
                    ->once();
        $charStream->shouldReceive('importString')
                    ->once()
                    ->with($input);

        $output = '';
        for ($i = 0; $i < 140; ++$i) {
            $charStream->shouldReceive('readBytes')
                       ->once()
                       ->andReturn([\ord('a')]);

            if (53 == $i || 53 + 75 == $i) {
                $output .= "=\r\n";
            }
            $output .= 'a';
        }

        $charStream->shouldReceive('readBytes')
                    ->once()
                    ->andReturn(false);

        $encoder = new Swift_Encoder_QpEncoder($charStream);
        $this->assertEquals(
            $output, $encoder->encodeString($input, 22),
            '%s: First line should start at offset 22 so can only have max length 54'
            );
    }

    public function testTextIsPreWrapped()
    {
        $encoder = $this->createEncoder();

        $input = str_repeat('a', 70)."\r\n".
                 str_repeat('a', 70)."\r\n".
                 str_repeat('a', 70);

        $this->assertEquals(
            $input, $encoder->encodeString($input)
            );
    }

    private function createCharStream()
    {
        return $this->getMockery('Swift_CharacterStream')->shouldIgnoreMissing();
    }

    private function createEncoder()
    {
        $factory = new Swift_CharacterReaderFactory_SimpleCharacterReaderFactory();
        $charStream = new Swift_CharacterStream_NgCharacterStream($factory, 'utf-8');

        return new Swift_Encoder_QpEncoder($charStream);
    }
}


================================================
FILE: tests/unit/Swift/Encoder/Rfc2231EncoderTest.php
================================================
<?php

class Swift_Encoder_Rfc2231EncoderTest extends \SwiftMailerTestCase
{
    private $rfc2045Token = '/^[\x21\x23-\x27\x2A\x2B\x2D\x2E\x30-\x39\x41-\x5A\x5E-\x7E]+$/D';

    /* --
    This algorithm is described in RFC 2231, but is barely touched upon except
    for mentioning bytes can be represented as their octet values (e.g. %20 for
    the SPACE character).

    The tests here focus on how to use that representation to always generate text
    which matches RFC 2045's definition of "token".
    */

    public function testEncodingAsciiCharactersProducesValidToken()
    {
        $charStream = $this->getMockery('Swift_CharacterStream');

        $string = '';
        foreach (range(0x00, 0x7F) as $octet) {
            $char = pack('C', $octet);
            $string .= $char;
            $charStream->shouldReceive('read')
                       ->once()
                       ->andReturn($char);
        }

        $charStream->shouldReceive('flushContents')
                    ->once();
        $charStream->shouldReceive('importString')
                    ->once()
                    ->with($string);
        $charStream->shouldReceive('read')
                    ->atLeast()->times(1)
                    ->andReturn(false);

        $encoder = new Swift_Encoder_Rfc2231Encoder($charStream);
        $encoded = $encoder->encodeString($string);

        foreach (explode("\r\n", $encoded) as $line) {
            $this->assertMatchesRegularExpression($this->rfc2045Token, $line,
                '%s: Encoder should always return a valid RFC 2045 token.');
        }
    }

    public function testEncodingNonAsciiCharactersProducesValidToken()
    {
        $charStream = $this->getMockery('Swift_CharacterStream');

        $string = '';
        foreach (range(0x80, 0xFF) as $octet) {
            $char = pack('C', $octet);
            $string .= $char;
            $charStream->shouldReceive('read')
                       ->once()
                       ->andReturn($char);
        }
        $charStream->shouldReceive('flushContents')
                    ->once();
        $charStream->shouldReceive('importString')
                    ->once()
                    ->with($string);
        $charStream->shouldReceive('read')
                    ->atLeast()->times(1)
                    ->andReturn(false);
        $encoder = new Swift_Encoder_Rfc2231Encoder($charStream);

        $encoded = $encoder->encodeString($string);

        foreach (explode("\r\n", $encoded) as $line) {
            $this->assertMatchesRegularExpression($this->rfc2045Token, $line,
                '%s: Encoder should always return a valid RFC 2045 token.');
        }
    }

    public function testMaximumLineLengthCanBeSet()
    {
        $charStream = $this->getMockery('Swift_CharacterStream');

        $string = '';
        for ($x = 0; $x < 200; ++$x) {
            $char = 'a';
            $string .= $char;
            $charStream->shouldReceive('read')
                       ->once()
                       ->andReturn($char);
        }
        $charStream->shouldReceive('flushContents')
                    ->once();
        $charStream->shouldReceive('importString')
                    ->once()
                    ->with($string);
        $charStream->shouldReceive('read')
                    ->atLeast()->times(1)
                    ->andReturn(false);
        $encoder = new Swift_Encoder_Rfc2231Encoder($charStream);

        $encoded = $encoder->encodeString($string, 0, 75);

        $this->assertEquals(
            str_repeat('a', 75)."\r\n".
            str_repeat('a', 75)."\r\n".
            str_repeat('a', 50),
            $encoded,
            '%s: Lines should be wrapped at each 75 characters'
            );
    }

    public function testFirstLineCanHaveShorterLength()
    {
        $charStream = $this->getMockery('Swift_CharacterStream');

        $string = '';
        for ($x = 0; $x < 200; ++$x) {
            $char = 'a';
            $string .= $char;
            $charStream->shouldReceive('read')
                       ->once()
                       ->andReturn($char);
        }
        $charStream->shouldReceive('flushContents')
                    ->once();
        $charStream->shouldReceive('importString')
                    ->once()
                    ->with($string);
        $charStream->shouldReceive('read')
                    ->atLeast()->times(1)
                    ->andReturn(false);
        $encoder = new Swift_Encoder_Rfc2231Encoder($charStream);
        $encoded = $encoder->encodeString($string, 25, 75);

        $this->assertEquals(
            str_repeat('a', 50)."\r\n".
            str_repeat('a', 75)."\r\n".
            str_repeat('a', 75),
            $encoded,
            '%s: First line should be 25 bytes shorter than the others.'
            );
    }
}


================================================
FILE: tests/unit/Swift/Events/CommandEventTest.php
================================================
<?php

class Swift_Events_CommandEventTest extends \PHPUnit\Framework\TestCase
{
    public function testCommandCanBeFetchedByGetter()
    {
        $evt = $this->createEvent($this->createTransport(), "FOO\r\n");
        $this->assertEquals("FOO\r\n", $evt->getCommand());
    }

    public function testSuccessCodesCanBeFetchedViaGetter()
    {
        $evt = $this->createEvent($this->createTransport(), "FOO\r\n", [250]);
        $this->assertEquals([250], $evt->getSuccessCodes());
    }

    public function testSourceIsBuffer()
    {
        $transport = $this->createTransport();
        $evt = $this->createEvent($transport, "FOO\r\n");
        $ref = $evt->getSource();
        $this->assertEquals($transport, $ref);
    }

    private function createEvent(Swift_Transport $source, $command, $successCodes = [])
    {
        return new Swift_Events_CommandEvent($source, $command, $successCodes);
    }

    private function createTransport()
    {
        return $this->getMockBuilder('Swift_Transport')->getMock();
    }
}


================================================
FILE: tests/unit/Swift/Events/EventObjectTest.php
================================================
<?php

class Swift_Events_EventObjectTest extends \PHPUnit\Framework\TestCase
{
    public function testEventSourceCanBeReturnedViaGetter()
    {
        $source = new stdClass();
        $evt = $this->createEvent($source);
        $ref = $evt->getSource();
        $this->assertEquals($source, $ref);
    }

    public function testEventDoesNotHaveCancelledBubbleWhenNew()
    {
        $source = new stdClass();
        $evt = $this->createEvent($source);
        $this->assertFalse($evt->bubbleCancelled());
    }

    public function testBubbleCanBeCancelledInEvent()
    {
        $source = new stdClass();
        $evt = $this->createEvent($source);
        $evt->cancelBubble();
        $this->assertTrue($evt->bubbleCancelled());
    }

    private function createEvent($source)
    {
        return new Swift_Events_EventObject($source);
    }
}


================================================
FILE: tests/unit/Swift/Events/ResponseEventTest.php
================================================
<?php

class Swift_Events_ResponseEventTest extends \PHPUnit\Framework\TestCase
{
    public function testResponseCanBeFetchViaGetter()
    {
        $evt = $this->createEvent($this->createTransport(), "250 Ok\r\n", true);
        $this->assertEquals("250 Ok\r\n", $evt->getResponse(),
            '%s: Response should be available via getResponse()'
            );
    }

    public function testResultCanBeFetchedViaGetter()
    {
        $evt = $this->createEvent($this->createTransport(), "250 Ok\r\n", false);
        $this->assertFalse($evt->isValid(),
            '%s: Result should be checkable via isValid()'
            );
    }

    public function testSourceIsBuffer()
    {
        $transport = $this->createTransport();
        $evt = $this->createEvent($transport, "250 Ok\r\n", true);
        $ref = $evt->getSource();
        $this->assertEquals($transport, $ref);
    }

    private function createEvent(Swift_Transport $source, $response, $result)
    {
        return new Swift_Events_ResponseEvent($source, $response, $result);
    }

    private function createTransport()
    {
        return $this->getMockBuilder('Swift_Transport')->getMock();
    }
}


================================================
FILE: tests/unit/Swift/Events/SendEventTest.php
================================================
<?php

class Swift_Events_SendEventTest extends \PHPUnit\Framework\TestCase
{
    public function testMessageCanBeFetchedViaGetter()
    {
        $message = $this->createMessage();
        $transport = $this->createTransport();

        $evt = $this->createEvent($transport, $message);

        $ref = $evt->getMessage();
        $this->assertEquals($message, $ref,
            '%s: Message should be returned from getMessage()'
            );
    }

    public function testTransportCanBeFetchViaGetter()
    {
        $message = $this->createMessage();
        $transport = $this->createTransport();

        $evt = $this->createEvent($transport, $message);

        $ref = $evt->getTransport();
        $this->assertEquals($transport, $ref,
            '%s: Transport should be returned from getTransport()'
            );
    }

    public function testTransportCanBeFetchViaGetSource()
    {
        $message = $this->createMessage();
        $transport = $this->createTransport();

        $evt = $this->createEvent($transport, $message);

        $ref = $evt->getSource();
        $this->assertEquals($transport, $ref,
            '%s: Transport should be returned from getSource()'
            );
    }

    public function testResultCanBeSetAndGet()
    {
        $message = $this->createMessage();
        $transport = $this->createTransport();

        $evt = $this->createEvent($transport, $message);

        $evt->setResult(
            Swift_Events_SendEvent::RESULT_SUCCESS | Swift_Events_SendEvent::RESULT_TENTATIVE
            );

        $this->assertTrue((bool) ($evt->getResult() & Swift_Events_SendEvent::RESULT_SUCCESS));
        $this->assertTrue((bool) ($evt->getResult() & Swift_Events_SendEvent::RESULT_TENTATIVE));
    }

    public function testFailedRecipientsCanBeSetAndGet()
    {
        $message = $this->createMessage();
        $transport = $this->createTransport();

        $evt = $this->createEvent($transport, $message);

        $evt->setFailedRecipients(['foo@bar', 'zip@button']);

        $this->assertEquals(['foo@bar', 'zip@button'], $evt->getFailedRecipients(),
            '%s: FailedRecipients should be returned from getter'
            );
    }

    public function testFailedRecipientsGetsPickedUpCorrectly()
    {
        $message = $this->createMessage();
        $transport = $this->createTransport();

        $evt = $this->createEvent($transport, $message);
        $this->assertEquals([], $evt->getFailedRecipients());
    }

    private function createEvent(Swift_Transport $source, Swift_Mime_SimpleMessage $message)
    {
        return new Swift_Events_SendEvent($source, $message);
    }

    private function createTransport()
    {
        return $this->getMockBuilder('Swift_Transport')->getMock();
    }

    private function createMessage()
    {
        return $this->getMockBuilder('Swift_Mime_SimpleMessage')->disableOriginalConstructor()->getMock();
    }
}


================================================
FILE: tests/unit/Swift/Events/SimpleEventDispatcherTest.php
================================================
<?php

class Swift_Events_SimpleEventDispatcherTest extends \PHPUnit\Framework\TestCase
{
    private $dispatcher;

    protected function setUp()
    {
        $this->dispatcher = new Swift_Events_SimpleEventDispatcher();
    }

    public function testSendEventCanBeCreated()
    {
        $transport = $this->getMockBuilder('Swift_Transport')->getMock();
        $message = $this->getMockBuilder('Swift_Mime_SimpleMessage')->disableOriginalConstructor()->getMock();
        $evt = $this->dispatcher->createSendEvent($transport, $message);
        $this->assertInstanceOf('Swift_Events_SendEvent', $evt);
        $this->assertSame($message, $evt->getMessage());
        $this->assertSame($transport, $evt->getTransport());
    }

    public function testCommandEventCanBeCreated()
    {
        $buf = $this->getMockBuilder('Swift_Transport')->getMock();
        $evt = $this->dispatcher->createCommandEvent($buf, "FOO\r\n", [250]);
        $this->assertInstanceOf('Swift_Events_CommandEvent', $evt);
        $this->assertSame($buf, $evt->getSource());
        $this->assertEquals("FOO\r\n", $evt->getCommand());
        $this->assertEquals([250], $evt->getSuccessCodes());
    }

    public function testResponseEventCanBeCreated()
    {
        $buf = $this->getMockBuilder('Swift_Transport')->getMock();
        $evt = $this->dispatcher->createResponseEvent($buf, "250 Ok\r\n", true);
        $this->assertInstanceOf('Swift_Events_ResponseEvent', $evt);
        $this->assertSame($buf, $evt->getSource());
        $this->assertEquals("250 Ok\r\n", $evt->getResponse());
        $this->assertTrue($evt->isValid());
    }

    public function testTransportChangeEventCanBeCreated()
    {
        $transport = $this->getMockBuilder('Swift_Transport')->getMock();
        $evt = $this->dispatcher->createTransportChangeEvent($transport);
        $this->assertInstanceOf('Swift_Events_TransportChangeEvent', $evt);
        $this->assertSame($transport, $evt->getSource());
    }

    public function testTransportExceptionEventCanBeCreated()
    {
        $transport = $this->getMockBuilder('Swift_Transport')->getMock();
        $ex = new Swift_TransportException('');
        $evt = $this->dispatcher->createTransportExceptionEvent($transport, $ex);
        $this->assertInstanceOf('Swift_Events_TransportExceptionEvent', $evt);
        $this->assertSame($transport, $evt->getSource());
        $this->assertSame($ex, $evt->getException());
    }

    public function testListenersAreNotifiedOfDispatchedEvent()
    {
        $transport = $this->getMockBuilder('Swift_Transport')->getMock();

        $evt = $this->dispatcher->createTransportChangeEvent($transport);

        $listenerA = $this->getMockBuilder('Swift_Events_TransportChangeListener')->getMock();
        $listenerB = $this->getMockBuilder('Swift_Events_TransportChangeListener')->getMock();

        $this->dispatcher->bindEventListener($listenerA);
        $this->dispatcher->bindEventListener($listenerB);

        $listenerA->expects($this->once())
                  ->method('transportStarted')
                  ->with($evt);
        $listenerB->expects($this->once())
                  ->method('transportStarted')
                  ->with($evt);

        $this->dispatcher->dispatchEvent($evt, 'transportStarted');
    }

    public function testListenersAreOnlyCalledIfImplementingCorrectInterface()
    {
        $transport = $this->getMockBuilder('Swift_Transport')->getMock();
        $message = $this->getMockBuilder('Swift_Mime_SimpleMessage')->disableOriginalConstructor()->getMock();

        $evt = $this->dispatcher->createSendEvent($transport, $message);

        $targetListener = $this->getMockBuilder('Swift_Events_SendListener')->getMock();
        $otherListener = $this->getMockBuilder('DummyListener')->getMock();

        $this->dispatcher->bindEventListener($targetListener);
        $this->dispatcher->bindEventListener($otherListener);

        $targetListener->expects($this->once())
                       ->method('sendPerformed')
                       ->with($evt);
        $otherListener->expects($this->never())
                    ->method('sendPerformed');

        $this->dispatcher->dispatchEvent($evt, 'sendPerformed');
    }

    public function testListenersCanCancelBubblingOfEvent()
    {
        $transport = $this->getMockBuilder('Swift_Transport')->getMock();
        $message = $this->getMockBuilder('Swift_Mime_SimpleMessage')->disableOriginalConstructor()->getMock();

        $evt = $this->dispatcher->createSendEvent($transport, $message);

        $listenerA = $this->getMockBuilder('Swift_Events_SendListener')->getMock();
        $listenerB = $this->getMockBuilder('Swift_Events_SendListener')->getMock();

        $this->dispatcher->bindEventListener($listenerA);
        $this->dispatcher->bindEventListener($listenerB);

        $listenerA->expects($this->once())
                  ->method('sendPerformed')
                  ->with($evt)
                  ->willReturnCallback(function ($object) {
                      $object->cancelBubble(true);
                  });
        $listenerB->expects($this->never())
                  ->method('sendPerformed');

        $this->dispatcher->dispatchEvent($evt, 'sendPerformed');

        $this->assertTrue($evt->bubbleCancelled());
    }

    public function testPreventFlushingQueueBubbleOnInternalEventsRising()
    {
        $transport = $this->getMockBuilder('Swift_Transport')->getMock();
        $message = $this->getMockBuilder('Swift_Mime_SimpleMessage')->disableOriginalConstructor()->getMock();

        $evtA = $this->dispatcher->createSendEvent($transport, $message);

        $evtB = $this->dispatcher->createTransportChangeEvent($transport);

        $listenerB = $this->getMockBuilder('Swift_Events_TransportChangeListener')->getMock();

        $this->dispatcher->bindEventListener($listenerB);

        $listenerA1 = $this->getMockBuilder('Swift_Events_SendListener')->getMock();
        $listenerA2 = $this->getMockBuilder('Swift_Events_SendListener')->getMock();

        $this->dispatcher->bindEventListener($listenerA1);
        $this->dispatcher->bindEventListener($listenerA2);

        $listenerA1->expects($this->once())
                  ->method('sendPerformed')
                  ->with($evtA)
                  ->will($this->returnCallback(function ($object) use ($evtB) {
                      $this->dispatcher->dispatchEvent($evtB, 'beforeTransportStarted');
                  }));
        $listenerA2->expects($this->once())
                  ->method('sendPerformed')
                  ->with($evtA);
        $listenerB->expects($this->once())
                  ->method('beforeTransportStarted')
                  ->with($evtB);

        $this->dispatcher->dispatchEvent($evtA, 'sendPerformed');
    }

    private function createDispatcher(array $map)
    {
        return new Swift_Events_SimpleEventDispatcher($map);
    }
}

class DummyListener implements Swift_Events_EventListener
{
    public function sendPerformed(Swift_Events_SendEvent $evt)
    {
    }
}


================================================
FILE: tests/unit/Swift/Events/TransportChangeEventTest.php
================================================
<?php

class Swift_Events_TransportChangeEventTest extends \PHPUnit\Framework\TestCase
{
    public function testGetTransportReturnsTransport()
    {
        $transport = $this->createTransport();
        $evt = $this->createEvent($transport);
        $ref = $evt->getTransport();
        $this->assertEquals($transport, $ref);
    }

    public function testSourceIsTransport()
    {
        $transport = $this->createTransport();
        $evt = $this->createEvent($transport);
        $ref = $evt->getSource();
        $this->assertEquals($transport, $ref);
    }

    private function createEvent(Swift_Transport $source)
    {
        return new Swift_Events_TransportChangeEvent($source);
    }

    private function createTransport()
    {
        return $this->getMockBuilder('Swift_Transport')->getMock();
    }
}


================================================
FILE: tests/unit/Swift/Events/TransportExceptionEventTest.php
================================================
<?php

class Swift_Events_TransportExceptionEventTest extends \PHPUnit\Framework\TestCase
{
    public function testExceptionCanBeFetchViaGetter()
    {
        $ex = $this->createException();
        $transport = $this->createTransport();
        $evt = $this->createEvent($transport, $ex);
        $ref = $evt->getException();
        $this->assertEquals($ex, $ref,
            '%s: Exception should be available via getException()'
            );
    }

    public function testSourceIsTransport()
    {
        $ex = $this->createException();
        $transport = $this->createTransport();
        $evt = $this->createEvent($transport, $ex);
        $ref = $evt->getSource();
        $this->assertEquals($transport, $ref,
            '%s: Transport should be available via getSource()'
            );
    }

    private function createEvent(Swift_Transport $transport, Swift_TransportException $ex)
    {
        return new Swift_Events_TransportExceptionEvent($transport, $ex);
    }

    private function createTransport()
    {
        return $this->getMockBuilder('Swift_Transport')->getMock();
    }

    private function createException()
    {
        return new Swift_TransportException('');
    }
}


================================================
FILE: tests/unit/Swift/KeyCache/ArrayKeyCacheTest.php
================================================
<?php

class Swift_KeyCache_ArrayKeyCacheTest extends \PHPUnit\Framework\TestCase
{
    private $key1 = 'key1';
    private $key2 = 'key2';

    public function testStringDataCanBeSetAndFetched()
    {
        $is = $this->createKeyCacheInputStream();
        $cache = $this->createCache($is);
        $cache->setString(
            $this->key1, 'foo', 'test', Swift_KeyCache::MODE_WRITE
            );
        $this->assertEquals('test', $cache->getString($this->key1, 'foo'));
    }

    public function testStringDataCanBeOverwritten()
    {
        $is = $this->createKeyCacheInputStream();
        $cache = $this->createCache($is);
        $cache->setString(
            $this->key1, 'foo', 'test', Swift_KeyCache::MODE_WRITE
            );
        $cache->setString(
            $this->key1, 'foo', 'whatever', Swift_KeyCache::MODE_WRITE
            );

        $this->assertEquals('whatever', $cache->getString($this->key1, 'foo'));
    }

    public function testStringDataCanBeAppended()
    {
        $is = $this->createKeyCacheInputStream();
        $cache = $this->createCache($is);
        $cache->setString(
            $this->key1, 'foo', 'test', Swift_KeyCache::MODE_WRITE
            );
        $cache->setString(
            $this->key1, 'foo', 'ing', Swift_KeyCache::MODE_APPEND
            );

        $this->assertEquals('testing', $cache->getString($this->key1, 'foo'));
    }

    public function testHasKeyReturnValue()
    {
        $is = $this->createKeyCacheInputStream();
        $cache = $this->createCache($is);
        $cache->setString(
            $this->key1, 'foo', 'test', Swift_KeyCache::MODE_WRITE
            );

        $this->assertTrue($cache->hasKey($this->key1, 'foo'));
    }

    public function testNsKeyIsWellPartitioned()
    {
        $is = $this->createKeyCacheInputStream();
        $cache = $this->createCache($is);
        $cache->setString(
            $this->key1, 'foo', 'test', Swift_KeyCache::MODE_WRITE
            );
        $cache->setString(
            $this->key2, 'foo', 'ing', Swift_KeyCache::MODE_WRITE
            );

        $this->assertEquals('test', $cache->getString($this->key1, 'foo'));
        $this->assertEquals('ing', $cache->getString($this->key2, 'foo'));
    }

    public function testItemKeyIsWellPartitioned()
    {
        $is = $this->createKeyCacheInputStream();
        $cache = $this->createCache($is);
        $cache->setString(
            $this->key1, 'foo', 'test', Swift_KeyCache::MODE_WRITE
            );
        $cache->setString(
            $this->key1, 'bar', 'ing', Swift_KeyCache::MODE_WRITE
            );

        $this->assertEquals('test', $cache->getString($this->key1, 'foo'));
        $this->assertEquals('ing', $cache->getString($this->key1, 'bar'));
    }

    public function testByteStreamCanBeImported()
    {
        $os = $this->createOutputStream();
        $os->expects($this->exactly(3))
           ->method('read')
           ->willReturnOnConsecutiveCalls('abc', 'def', false);

        $is = $this->createKeyCacheInputStream();
        $cache = $this->createCache($is);
        $cache->importFromByteStream(
            $this->key1, 'foo', $os, Swift_KeyCache::MODE_WRITE
            );
        $this->assertEquals('abcdef', $cache->getString($this->key1, 'foo'));
    }

    public function testByteStreamCanBeAppended()
    {
        $os1 = $this->createOutputStream();
        $os1->expects($this->exactly(3))
            ->method('read')
            ->willReturnOnConsecutiveCalls('abc', 'def', false);

        $os2 = $this->createOutputStream();
        $os2->expects($this->exactly(3))
            ->method('read')
            ->willReturnOnConsecutiveCalls('xyz', 'uvw', false);

        $is = $this->createKeyCacheInputStream(true);

        $cache = $this->createCache($is);

        $cache->importFromByteStream(
            $this->key1, 'foo', $os1, Swift_KeyCache::MODE_APPEND
            );
        $cache->importFromByteStream(
            $this->key1, 'foo', $os2, Swift_KeyCache::MODE_APPEND
            );

        $this->assertEquals('abcdefxyzuvw', $cache->getString($this->key1, 'foo'));
    }

    public function testByteStreamAndStringCanBeAppended()
    {
        $os = $this->createOutputStream();
        $os->expects($this->exactly(3))
           ->method('read')
           ->willReturnOnConsecutiveCalls('abc', 'def', false);

        $is = $this->createKeyCacheInputStream(true);

        $cache = $this->createCache($is);

        $cache->setString(
            $this->key1, 'foo', 'test', Swift_KeyCache::MODE_APPEND
            );
        $cache->importFromByteStream(
            $this->key1, 'foo', $os, Swift_KeyCache::MODE_APPEND
            );
        $this->assertEquals('testabcdef', $cache->getString($this->key1, 'foo'));
    }

    public function testDataCanBeExportedToByteStream()
    {
        //See acceptance test for more detail
        $is = $this->createInputStream();
        $is->expects($this->atLeastOnce())
           ->method('write');

        $kcis = $this->createKeyCacheInputStream(true);

        $cache = $this->createCache($kcis);

        $cache->setString(
            $this->key1, 'foo', 'test', Swift_KeyCache::MODE_WRITE
            );

        $cache->exportToByteStream($this->key1, 'foo', $is);
    }

    public function testKeyCanBeCleared()
    {
        $is = $this->createKeyCacheInputStream();
        $cache = $this->createCache($is);

        $cache->setString(
            $this->key1, 'foo', 'test', Swift_KeyCache::MODE_WRITE
            );
        $this->assertTrue($cache->hasKey($this->key1, 'foo'));
        $cache->clearKey($this->key1, 'foo');
        $this->assertFalse($cache->hasKey($this->key1, 'foo'));
    }

    public function testNsKeyCanBeCleared()
    {
        $is = $this->createKeyCacheInputStream();
        $cache = $this->createCache($is);

        $cache->setString(
            $this->key1, 'foo', 'test', Swift_KeyCache::MODE_WRITE
            );
        $cache->setString(
            $this->key1, 'bar', 'xyz', Swift_KeyCache::MODE_WRITE
            );
        $this->assertTrue($cache->hasKey($this->key1, 'foo'));
        $this->assertTrue($cache->hasKey($this->key1, 'bar'));
        $cache->clearAll($this->key1);
        $this->assertFalse($cache->hasKey($this->key1, 'foo'));
        $this->assertFalse($cache->hasKey($this->key1, 'bar'));
    }

    private function createCache($is)
    {
        return new Swift_KeyCache_ArrayKeyCache($is);
    }

    private function createKeyCacheInputStream()
    {
        return $this->getMockBuilder('Swift_KeyCache_KeyCacheInputStream')->getMock();
    }

    private function createOutputStream()
    {
        return $this->getMockBuilder('Swift_OutputByteStream')->getMock();
    }

    private function createInputStream()
    {
        return $this->getMockBuilder('Swift_InputByteStream')->getMock();
    }
}


================================================
FILE: tests/unit/Swift/KeyCache/SimpleKeyCacheInputStreamTest.php
================================================
<?php

class Swift_KeyCache_SimpleKeyCacheInputStreamTest extends \PHPUnit\Framework\TestCase
{
    private $nsKey = 'ns1';

    public function testStreamWritesToCacheInAppendMode()
    {
        $cache = $this->getMockBuilder('Swift_KeyCache')->getMock();
        $cache->expects($this->exactly(3))
              ->method('setString')
              ->withConsecutive(
                  [$this->nsKey, 'foo', 'a', Swift_KeyCache::MODE_APPEND],
                  [$this->nsKey, 'foo', 'b', Swift_KeyCache::MODE_APPEND],
                  [$this->nsKey, 'foo', 'c', Swift_KeyCache::MODE_APPEND]
              );

        $stream = new Swift_KeyCache_SimpleKeyCacheInputStream();
        $stream->setKeyCache($cache);
        $stream->setNsKey($this->nsKey);
        $stream->setItemKey('foo');

        $stream->write('a');
        $stream->write('b');
        $stream->write('c');
    }

    public function testFlushContentClearsKey()
    {
        $cache = $this->getMockBuilder('Swift_KeyCache')->getMock();
        $cache->expects($this->once())
              ->method('clearKey')
              ->with($this->nsKey, 'foo');

        $stream = new Swift_KeyCache_SimpleKeyCacheInputStream();
        $stream->setKeyCache($cache);
        $stream->setNsKey($this->nsKey);
        $stream->setItemKey('foo');

        $stream->flushBuffers();
    }

    public function testClonedStreamStillReferencesSameCache()
    {
        $cache = $this->getMockBuilder('Swift_KeyCache')->getMock();
        $cache->expects($this->exactly(3))
              ->method('setString')
              ->withConsecutive(
                  [$this->nsKey, 'foo', 'a', Swift_KeyCache::MODE_APPEND],
                  [$this->nsKey, 'foo', 'b', Swift_KeyCache::MODE_APPEND],
                  ['test', 'bar', 'x', Swift_KeyCache::MODE_APPEND]
              );

        $stream = new Swift_KeyCache_SimpleKeyCacheInputStream();
        $stream->setKeyCache($cache);
        $stream->setNsKey($this->nsKey);
        $stream->setItemKey('foo');

        $stream->write('a');
        $stream->write('b');

        $newStream = clone $stream;
        $newStream->setKeyCache($cache);
        $newStream->setNsKey('test');
        $newStream->setItemKey('bar');

        $newStream->write('x');
    }
}


================================================
FILE: tests/unit/Swift/Mailer/ArrayRecipientIteratorTest.php
================================================
<?php

class Swift_Mailer_ArrayRecipientIteratorTest extends \PHPUnit\Framework\TestCase
{
    public function testHasNextReturnsFalseForEmptyArray()
    {
        $it = new Swift_Mailer_ArrayRecipientIterator([]);
        $this->assertFalse($it->hasNext());
    }

    public function testHasNextReturnsTrueIfItemsLeft()
    {
        $it = new Swift_Mailer_ArrayRecipientIterator(['foo@bar' => 'Foo']);
        $this->assertTrue($it->hasNext());
    }

    public function testReadingToEndOfListCausesHasNextToReturnFalse()
    {
        $it = new Swift_Mailer_ArrayRecipientIterator(['foo@bar' => 'Foo']);
        $this->assertTrue($it->hasNext());
        $it->nextRecipient();
        $this->assertFalse($it->hasNext());
    }

    public function testReturnedValueHasPreservedKeyValuePair()
    {
        $it = new Swift_Mailer_ArrayRecipientIterator(['foo@bar' => 'Foo']);
        $this->assertEquals(['foo@bar' => 'Foo'], $it->nextRecipient());
    }

    public function testIteratorMovesNextAfterEachIteration()
    {
        $it = new Swift_Mailer_ArrayRecipientIterator([
            'foo@bar' => 'Foo',
            'zip@button' => 'Zip thing',
            'test@test' => null,
            ]);
        $this->assertEquals(['foo@bar' => 'Foo'], $it->nextRecipient());
        $this->assertEquals(['zip@button' => 'Zip thing'], $it->nextRecipient());
        $this->assertEquals(['test@test' => null], $it->nextRecipient());
    }
}


================================================
FILE: tests/unit/Swift/MailerTest.php
================================================
<?php

class Swift_MailerTest extends \SwiftMailerTestCase
{
    public function testTransportIsStartedWhenSending()
    {
        $transport = $this->createTransport();
        $message = $this->createMessage();

        $started = false;
        $transport->shouldReceive('isStarted')
                  ->zeroOrMoreTimes()
                  ->andReturnUsing(function () use (&$started) {
                      return $started;
                  });
        $transport->shouldReceive('start')
                  ->once()
                  ->andReturnUsing(function () use (&$started) {
                      $started = true;

                      return;
                  });

        $mailer = $this->createMailer($transport);
        $mailer->send($message);
    }

    public function testTransportIsOnlyStartedOnce()
    {
        $transport = $this->createTransport();
        $message = $this->createMessage();

        $started = false;
        $transport->shouldReceive('isStarted')
                  ->zeroOrMoreTimes()
                  ->andReturnUsing(function () use (&$started) {
                      return $started;
                  });
        $transport->shouldReceive('start')
                  ->once()
                  ->andReturnUsing(function () use (&$started) {
                      $started = true;

                      return;
                  });

        $mailer = $this->createMailer($transport);
        for ($i = 0; $i < 10; ++$i) {
            $mailer->send($message);
        }
    }

    public function testMessageIsPassedToTransport()
    {
        $transport = $this->createTransport();
        $message = $this->createMessage();
        $transport->shouldReceive('send')
                  ->once()
                  ->with($message, \Mockery::any());

        $mailer = $this->createMailer($transport);
        $mailer->send($message);
    }

    public function testSendReturnsCountFromTransport()
    {
        $transport = $this->createTransport();
        $message = $this->createMessage();
        $transport->shouldReceive('send')
                  ->once()
                  ->with($message, \Mockery::any())
                  ->andReturn(57);

        $mailer = $this->createMailer($transport);
        $this->assertEquals(57, $mailer->send($message));
    }

    public function testFailedRecipientReferenceIsPassedToTransport()
    {
        $failures = [];

        $transport = $this->createTransport();
        $message = $this->createMessage();
        $transport->shouldReceive('send')
                  ->once()
                  ->with($message, $failures)
                  ->andReturn(57);

        $mailer = $this->createMailer($transport);
        $mailer->send($message, $failures);
    }

    public function testSendRecordsRfcComplianceExceptionAsEntireSendFailure()
    {
        $failures = [];

        $rfcException = new Swift_RfcComplianceException('test');
        $transport = $this->createTransport();
        $message = $this->createMessage();
        $message->shouldReceive('getTo')
                  ->once()
                  ->andReturn(['foo&invalid' => 'Foo', 'bar@valid.tld' => 'Bar']);
        $transport->shouldReceive('send')
                  ->once()
                  ->with($message, $failures)
                  ->andThrow($rfcException);

        $mailer = $this->createMailer($transport);
        $this->assertEquals(0, $mailer->send($message, $failures), '%s: Should return 0');
        $this->assertEquals(['foo&invalid', 'bar@valid.tld'], $failures, '%s: Failures should contain all addresses since the entire message failed to compile');
    }

    public function testRegisterPluginDelegatesToTransport()
    {
        $plugin = $this->createPlugin();
        $transport = $this->createTransport();
        $mailer = $this->createMailer($transport);

        $transport->shouldReceive('registerPlugin')
                  ->once()
                  ->with($plugin);

        $mailer->registerPlugin($plugin);
    }

    private function createPlugin()
    {
        return $this->getMockery('Swift_Events_EventListener')->shouldIgnoreMissing();
    }

    private function createTransport()
    {
        return $this->getMockery('Swift_Transport')->shouldIgnoreMissing();
    }

    private function createMessage()
    {
        return $this->getMockery('Swift_Mime_SimpleMessage')->shouldIgnoreMissing();
    }

    private function createMailer(Swift_Transport $transport)
    {
        return new Swift_Mailer($transport);
    }
}


================================================
FILE: tests/unit/Swift/MessageTest.php
================================================
<?php

class Swift_MessageTest extends \PHPUnit\Framework\TestCase
{
    public function testCloning()
    {
        $message1 = new Swift_Message('subj', 'body', 'ctype');
        $message2 = new Swift_Message('subj', 'body', 'ctype');
        $message1_clone = clone $message1;

        $this->recursiveObjectCloningCheck($message1, $message2, $message1_clone);
        // the test above will fail if the two messages are not identical
        $this->addToAssertionCount(1);
    }

    public function testCloningWithSigners()
    {
        $message1 = new Swift_Message('subj', 'body', 'ctype');
        $signer = new Swift_Signers_DKIMSigner(\dirname(__DIR__, 2).'/_samples/dkim/dkim.test.priv', 'test.example', 'example');
        $message1->attachSigner($signer);
        $message2 = new Swift_Message('subj', 'body', 'ctype');
        $signer = new Swift_Signers_DKIMSigner(\dirname(__DIR__, 2).'/_samples/dkim/dkim.test.priv', 'test.example', 'example');
        $message2->attachSigner($signer);
        $message1_clone = clone $message1;

        $this->recursiveObjectCloningCheck($message1, $message2, $message1_clone);
        // the test above will fail if the two messages are not identical
        $this->addToAssertionCount(1);
    }

    public function testBodySwap()
    {
        $message1 = new Swift_Message('Test');
        $html = new Swift_MimePart('<html></html>', 'text/html');
        $html->getHeaders()->addTextHeader('X-Test-Remove', 'Test-Value');
        $html->getHeaders()->addTextHeader('X-Test-Alter', 'Test-Value');
        $message1->attach($html);
        $source = $message1->toString();
        $message2 = clone $message1;
        $message2->setSubject('Message2');
        foreach ($message2->getChildren() as $child) {
            $child->setBody('Test');
            $child->getHeaders()->removeAll('X-Test-Remove');
            $child->getHeaders()->get('X-Test-Alter')->setValue('Altered');
        }
        $final = $message1->toString();
        if ($source != $final) {
            $this->fail("Difference although object cloned \n [".$source."]\n[".$final."]\n");
        }
        $final = $message2->toString();
        if ($final == $source) {
            $this->fail('Two body matches although they should differ'."\n [".$source."]\n[".$final."]\n");
        }
        $id_1 = $message1->getId();
        $id_2 = $message2->getId();
        $this->assertEquals($id_1, $id_2, 'Message Ids differ');
        $id_2 = $message2->generateId();
        $this->assertNotEquals($id_1, $id_2, 'Message Ids are the same');
    }

    protected function recursiveObjectCloningCheck($obj1, $obj2, $obj1_clone)
    {
        $obj1_properties = (array) $obj1;
        $obj2_properties = (array) $obj2;
        $obj1_clone_properties = (array) $obj1_clone;

        foreach ($obj1_properties as $property => $value) {
            if (\is_object($value)) {
                $obj1_value = $obj1_properties[$property];
                $obj2_value = $obj2_properties[$property];
                $obj1_clone_value = $obj1_clone_properties[$property];

                if ($obj1_value !== $obj2_value) {
                    // two separetely instanciated objects property not referencing same object
                    $this->assertFalse(
                        // but object's clone does - not everything copied
                        $obj1_value === $obj1_clone_value,
                        "Property `$property` cloning error: source and cloned objects property is referencing same object"
                    );
                } else {
                    // two separetely instanciated objects have same reference
                    $this->assertFalse(
                        // but object's clone doesn't - overdone making copies
                        $obj1_value !== $obj1_clone_value,
                        "Property `$property` not properly cloned: it should reference same object as cloning source (overdone copping)"
                    );
                }
                // recurse
                $this->recursiveObjectCloningCheck($obj1_value, $obj2_value, $obj1_clone_value);
            } elseif (\is_array($value)) {
                $obj1_value = $obj1_properties[$property];
                $obj2_value = $obj2_properties[$property];
                $obj1_clone_value = $obj1_clone_properties[$property];

                return $this->recursiveArrayCloningCheck($obj1_value, $obj2_value, $obj1_clone_value);
            }
        }
    }

    protected function recursiveArrayCloningCheck($array1, $array2, $array1_clone)
    {
        foreach ($array1 as $key => $value) {
            if (\is_object($value)) {
                $arr1_value = $array1[$key];
                $arr2_value = $array2[$key];
                $arr1_clone_value = $array1_clone[$key];
                if ($arr1_value !== $arr2_value) {
                    // two separetely instanciated objects property not referencing same object
                    $this->assertFalse(
                        // but object's clone does - not everything copied
                        $arr1_value === $arr1_clone_value,
                        "Key `$key` cloning error: source and cloned objects property is referencing same object"
                    );
                } else {
                    // two separetely instanciated objects have same reference
                    $this->assertFalse(
                        // but object's clone doesn't - overdone making copies
                        $arr1_value !== $arr1_clone_value,
                        "Key `$key` not properly cloned: it should reference same object as cloning source (overdone copping)"
                    );
                }
                // recurse
                $this->recursiveObjectCloningCheck($arr1_value, $arr2_value, $arr1_clone_value);
            } elseif (\is_array($value)) {
                $arr1_value = $array1[$key];
                $arr2_value = $array2[$key];
                $arr1_clone_value = $array1_clone[$key];

                return $this->recursiveArrayCloningCheck($arr1_value, $arr2_value, $arr1_clone_value);
            }
        }
    }
}


================================================
FILE: tests/unit/Swift/Mime/AbstractMimeEntityTest.php
================================================
<?php

require_once \dirname(__DIR__, 3).'/fixtures/MimeEntityFixture.php';

abstract class Swift_Mime_AbstractMimeEntityTest extends \SwiftMailerTestCase
{
    public function testGetHeadersReturnsHeaderSet()
    {
        $headers = $this->createHeaderSet();
        $entity = $this->createEntity($headers, $this->createEncoder(),
            $this->createCache()
            );
        $this->assertSame($headers, $entity->getHeaders());
    }

    public function testContentTypeIsReturnedFromHeader()
    {
        $ctype = $this->createHeader('Content-Type', 'image/jpeg-test');
        $headers = $this->createHeaderSet(['Content-Type' => $ctype]);
        $entity = $this->createEntity($headers, $this->createEncoder(),
            $this->createCache()
            );
        $this->assertEquals('image/jpeg-test', $entity->getContentType());
    }

    public function testContentTypeIsSetInHeader()
    {
        $ctype = $this->createHeader('Content-Type', 'text/plain', [], false);
        $headers = $this->createHeaderSet(['Content-Type' => $ctype]);

        $ctype->shouldReceive('setFieldBodyModel')
              ->once()
              ->with('image/jpeg');
        $ctype->shouldReceive('setFieldBodyModel')
              ->zeroOrMoreTimes()
              ->with(\Mockery::not('image/jpeg'));

        $entity = $this->createEntity($headers, $this->createEncoder(),
            $this->createCache()
            );
        $entity->setContentType('image/jpeg');
    }

    public function testContentTypeHeaderIsAddedIfNoneSet()
    {
        $headers = $this->createHeaderSet([], false);
        $headers->shouldReceive('addParameterizedHeader')
                ->once()
                ->with('Content-Type', 'image/jpeg');
        $headers->shouldReceive('addParameterizedHeader')
                ->zeroOrMoreTimes();

        $entity = $this->createEntity($headers, $this->createEncoder(),
            $this->createCache()
            );
        $entity->setContentType('image/jpeg');
    }

    public function testContentTypeCanBeSetViaSetBody()
    {
        $headers = $this->createHeaderSet([], false);
        $headers->shouldReceive('addParameterizedHeader')
                ->once()
                ->with('Content-Type', 'text/html');
        $headers->shouldReceive('addParameterizedHeader')
                ->zeroOrMoreTimes();

        $entity = $this->createEntity($headers, $this->createEncoder(),
            $this->createCache()
            );
        $entity->setBody('<b>foo</b>', 'text/html');
    }

    public function testGetEncoderFromConstructor()
    {
        $encoder = $this->createEncoder('base64');
        $entity = $this->createEntity($this->createHeaderSet(), $encoder,
            $this->createCache()
            );
        $this->assertSame($encoder, $entity->getEncoder());
    }

    public function testSetAndGetEncoder()
    {
        $encoder = $this->createEncoder('base64');
        $headers = $this->createHeaderSet();
        $entity = $this->createEntity($headers, $this->createEncoder(),
            $this->createCache()
            );
        $entity->setEncoder($encoder);
        $this->assertSame($encoder, $entity->getEncoder());
    }

    public function testSettingEncoderUpdatesTransferEncoding()
    {
        $encoder = $this->createEncoder('base64');
        $encoding = $this->createHeader(
            'Content-Transfer-Encoding', '8bit', [], false
            );
        $headers = $this->createHeaderSet([
            'Content-Transfer-Encoding' => $encoding,
            ]);
        $encoding->shouldReceive('setFieldBodyModel')
                 ->once()
                 ->with('base64');
        $encoding->shouldReceive('setFieldBodyModel')
                 ->zeroOrMoreTimes();

        $entity = $this->createEntity($headers, $this->createEncoder(),
            $this->createCache()
            );
        $entity->setEncoder($encoder);
    }

    public function testSettingEncoderAddsEncodingHeaderIfNonePresent()
    {
        $headers = $this->createHeaderSet([], false);
        $headers->shouldReceive('addTextHeader')
                ->once()
                ->with('Content-Transfer-Encoding', 'something');
        $headers->shouldReceive('addTextHeader')
                ->zeroOrMoreTimes();

        $entity = $this->createEntity($headers, $this->createEncoder(),
            $this->createCache()
            );
        $entity->setEncoder($this->createEncoder('something'));
    }

    public function testIdIsReturnedFromHeader()
    {
        /* -- RFC 2045, 7.
        In constructing a high-level user agent, it may be desirable to allow
        one body to make reference to another.  Accordingly, bodies may be
        labelled using the "Content-ID" header field, which is syntactically
        identical to the "Message-ID" header field
        */

        $cid = $this->createHeader('Content-ID', 'zip@button');
        $headers = $this->createHeaderSet(['Content-ID' => $cid]);
        $entity = $this->createEntity($headers, $this->createEncoder(),
            $this->createCache()
            );
        $this->assertEquals('zip@button', $entity->getId());
    }

    public function testIdIsSetInHeader()
    {
        $cid = $this->createHeader('Content-ID', 'zip@button', [], false);
        $headers = $this->createHeaderSet(['Content-ID' => $cid]);

        $cid->shouldReceive('setFieldBodyModel')
            ->once()
            ->with('foo@bar');
        $cid->shouldReceive('setFieldBodyModel')
            ->zeroOrMoreTimes();

        $entity = $this->createEntity($headers, $this->createEncoder(),
            $this->createCache()
            );
        $entity->setId('foo@bar');
    }

    public function testIdIsAutoGenerated()
    {
        $entity = $this->createEntity($this->createHeaderSet(),
            $this->createEncoder(), $this->createCache()
            );
        $this->assertMatchesRegularExpression('/^.*?@.*?$/D', $entity->getId());
    }

    public function testGenerateIdCreatesNewId()
    {
        $headers = $this->createHeaderSet();
        $entity = $this->createEntity($headers, $this->createEncoder(),
            $this->createCache()
            );
        $id1 = $entity->generateId();
        $id2 = $entity->generateId();
        $this->assertNotEquals($id1, $id2);
    }

    public function testGenerateIdSetsNewId()
    {
        $headers = $this->createHeaderSet();
        $entity = $this->createEntity($headers, $this->createEncoder(),
            $this->createCache()
            );
        $id = $entity->generateId();
        $this->assertEquals($id, $entity->getId());
    }

    public function testDescriptionIsReadFromHeader()
    {
        /* -- RFC 2045, 8.
        The ability to associate some descriptive information with a given
        body is often desirable.  For example, it may be useful to mark an
        "image" body as "a picture of the Space Shuttle Endeavor."  Such text
        may be placed in the Content-Description header field.  This header
        field is always optional.
        */

        $desc = $this->createHeader('Content-Description', 'something');
        $headers = $this->createHeaderSet(['Content-Description' => $desc]);
        $entity = $this->createEntity($headers, $this->createEncoder(),
            $this->createCache()
            );
        $this->assertEquals('something', $entity->getDescription());
    }

    public function testDescriptionIsSetInHeader()
    {
        $desc = $this->createHeader('Content-Description', '', [], false);
        $desc->shouldReceive('setFieldBodyModel')->once()->with('whatever');

        $headers = $this->createHeaderSet(['Content-Description' => $desc]);

        $entity = $this->createEntity($headers, $this->createEncoder(),
            $this->createCache()
            );
        $entity->setDescription('whatever');
    }

    public function testDescriptionHeaderIsAddedIfNotPresent()
    {
        $headers = $this->createHeaderSet([], false);
        $headers->shouldReceive('addTextHeader')
                ->once()
                ->with('Content-Description', 'whatever');
        $headers->shouldReceive('addTextHeader')
                ->zeroOrMoreTimes();

        $entity = $this->createEntity($headers, $this->createEncoder(),
            $this->createCache()
            );
        $entity->setDescription('whatever');
    }

    public function testSetAndGetMaxLineLength()
    {
        $entity = $this->createEntity($this->createHeaderSet(),
            $this->createEncoder(), $this->createCache()
            );
        $entity->setMaxLineLength(60);
        $this->assertEquals(60, $entity->getMaxLineLength());
    }

    public function testEncoderIsUsedForStringGeneration()
    {
        $encoder = $this->createEncoder('base64', false);
        $encoder->expects($this->once())
                ->method('encodeString')
                ->with('blah');

        $entity = $this->createEntity($this->createHeaderSet(),
            $encoder, $this->createCache()
            );
        $entity->setBody('blah');
        $entity->toString();
    }

    public function testMaxLineLengthIsProvidedWhenEncoding()
    {
        $encoder = $this->createEncoder('base64', false);
        $encoder->expects($this->once())
                ->method('encodeString')
                ->with('blah', 0, 65);

        $entity = $this->createEntity($this->createHeaderSet(),
            $encoder, $this->createCache()
            );
        $entity->setBody('blah');
        $entity->setMaxLineLength(65);
        $entity->toString();
    }

    public function testHeadersAppearInString()
    {
        $headers = $this->createHeaderSet([], false);
        $headers->shouldReceive('toString')
                ->once()
                ->andReturn(
                    "Content-Type: text/plain; charset=utf-8\r\n".
                    "X-MyHeader: foobar\r\n"
                );

        $entity = $this->createEntity($headers, $this->createEncoder(),
            $this->createCache()
            );
        $this->assertEquals(
            "Content-Type: text/plain; charset=utf-8\r\n".
            "X-MyHeader: foobar\r\n",
            $entity->toString()
            );
    }

    public function testSetAndGetBody()
    {
        $entity = $this->createEntity($this->createHeaderSet(),
            $this->createEncoder(), $this->createCache()
            );
        $entity->setBody("blah\r\nblah!");
        $this->assertEquals("blah\r\nblah!", $entity->getBody());
    }

    public function testBodyIsAppended()
    {
        $headers = $this->createHeaderSet([], false);
        $headers->shouldReceive('toString')
                ->once()
                ->andReturn("Content-Type: text/plain; charset=utf-8\r\n");

        $entity = $this->createEntity($headers, $this->createEncoder(),
            $this->createCache()
            );
        $entity->setBody("blah\r\nblah!");
        $this->assertEquals(
            "Content-Type: text/plain; charset=utf-8\r\n".
            "\r\n".
            "blah\r\nblah!",
            $entity->toString()
            );
    }

    public function testGetBodyReturnsStringFromByteStream()
    {
        $os = $this->createOutputStream('byte stream string');
        $entity = $this->createEntity($this->createHeaderSet(),
            $this->createEncoder(), $this->createCache()
            );
        $entity->setBody($os);
        $this->assertEquals('byte stream string', $entity->getBody());
    }

    public function testByteStreamBodyIsAppended()
    {
        $headers = $this->createHeaderSet([], false);
        $os = $this->createOutputStream('streamed');
        $headers->shouldReceive('toString')
                ->once()
                ->andReturn("Content-Type: text/plain; charset=utf-8\r\n");

        $entity = $this->createEntity($headers, $this->createEncoder(),
            $this->createCache()
            );
        $entity->setBody($os);
        $this->assertEquals(
            "Content-Type: text/plain; charset=utf-8\r\n".
            "\r\n".
            'streamed',
            $entity->toString()
            );
    }

    public function testBoundaryCanBeRetrieved()
    {
        /* -- RFC 2046, 5.1.1.
     boundary := 0*69<bchars> bcharsnospace

     bchars := bcharsnospace / " "

     bcharsnospace := DIGIT / ALPHA / "'" / "(" / ")" /
                                            "+" / "_" / "," / "-" / "." /
                                            "/" / ":" / "=" / "?"
        */

        $entity = $this->createEntity($this->createHeaderSet(),
            $this->createEncoder(), $this->createCache()
            );
        $this->assertMatchesRegularExpression(
            '/^[a-zA-Z0-9\'\(\)\+_\-,\.\/:=\?\ ]{0,69}[a-zA-Z0-9\'\(\)\+_\-,\.\/:=\?]$/D',
            $entity->getBoundary()
            );
    }

    public function testBoundaryNeverChanges()
    {
        $entity = $this->createEntity($this->createHeaderSet(),
            $this->createEncoder(), $this->createCache()
            );
        $firstBoundary = $entity->getBoundary();
        for ($i = 0; $i < 10; ++$i) {
            $this->assertEquals($firstBoundary, $entity->getBoundary());
        }
    }

    public function testBoundaryCanBeSet()
    {
        $entity = $this->createEntity($this->createHeaderSet(),
            $this->createEncoder(), $this->createCache()
            );
        $entity->setBoundary('foobar');
        $this->assertEquals('foobar', $entity->getBoundary());
    }

    public function testAddingChildrenGeneratesBoundaryInHeaders()
    {
        $child = $this->createChild();
        $cType = $this->createHeader('Content-Type', 'text/plain', [], false);
        $cType->shouldReceive('setParameter')
              ->once()
              ->with('boundary', \Mockery::any());
        $cType->shouldReceive('setParameter')
              ->zeroOrMoreTimes();

        $entity = $this->createEntity($this->createHeaderSet([
            'Content-Type' => $cType,
            ]),
            $this->createEncoder(), $this->createCache()
            );
        $entity->setChildren([$child]);
    }

    public function testChildrenOfLevelAttachmentAndLessCauseMultipartMixed()
    {
        for ($level = Swift_Mime_SimpleMimeEntity::LEVEL_MIXED;
            $level > Swift_Mime_SimpleMimeEntity::LEVEL_TOP; $level /= 2) {
            $child = $this->createChild($level);
            $cType = $this->createHeader(
                'Content-Type', 'text/plain', [], false
                );
            $cType->shouldReceive('setFieldBodyModel')
                  ->once()
                  ->with('multipart/mixed');
            $cType->shouldReceive('setFieldBodyModel')
                  ->zeroOrMoreTimes();

            $entity = $this->createEntity($this->createHeaderSet([
                'Content-Type' => $cType, ]),
                $this->createEncoder(), $this->createCache()
                );
            $entity->setChildren([$child]);
        }
    }

    public function testChildrenOfLevelAlternativeAndLessCauseMultipartAlternative()
    {
        for ($level = Swift_Mime_SimpleMimeEntity::LEVEL_ALTERNATIVE;
            $level > Swift_Mime_SimpleMimeEntity::LEVEL_MIXED; $level /= 2) {
            $child = $this->createChild($level);
            $cType = $this->createHeader(
                'Content-Type', 'text/plain', [], false
                );
            $cType->shouldReceive('setFieldBodyModel')
                  ->once()
                  ->with('multipart/alternative');
            $cType->shouldReceive('setFieldBodyModel')
                  ->zeroOrMoreTimes();

            $entity = $this->createEntity($this->createHeaderSet([
                'Content-Type' => $cType, ]),
                $this->createEncoder(), $this->createCache()
                );
            $entity->setChildren([$child]);
        }
    }

    public function testChildrenOfLevelRelatedAndLessCauseMultipartRelated()
    {
        for ($level = Swift_Mime_SimpleMimeEntity::LEVEL_RELATED;
            $level > Swift_Mime_SimpleMimeEntity::LEVEL_ALTERNATIVE; $level /= 2) {
            $child = $this->createChild($level);
            $cType = $this->createHeader(
                'Content-Type', 'text/plain', [], false
                );
            $cType->shouldReceive('setFieldBodyModel')
                  ->once()
                  ->with('multipart/related');
            $cType->shouldReceive('setFieldBodyModel')
                  ->zeroOrMoreTimes();

            $entity = $this->createEntity($this->createHeaderSet([
                'Content-Type' => $cType, ]),
                $this->createEncoder(), $this->createCache()
                );
            $entity->setChildren([$child]);
        }
    }

    public function testHighestLevelChildDeterminesContentType()
    {
        $combinations = [
            ['levels' => [Swift_Mime_SimpleMimeEntity::LEVEL_MIXED,
                Swift_Mime_SimpleMimeEntity::LEVEL_ALTERNATIVE,
                Swift_Mime_SimpleMimeEntity::LEVEL_RELATED,
                ],
                'type' => 'multipart/mixed',
                ],
            ['levels' => [Swift_Mime_SimpleMimeEntity::LEVEL_MIXED,
                Swift_Mime_SimpleMimeEntity::LEVEL_RELATED,
                ],
                'type' => 'multipart/mixed',
                ],
            ['levels' => [Swift_Mime_SimpleMimeEntity::LEVEL_MIXED,
                Swift_Mime_SimpleMimeEntity::LEVEL_ALTERNATIVE,
                ],
                'type' => 'multipart/mixed',
                ],
            ['levels' => [Swift_Mime_SimpleMimeEntity::LEVEL_ALTERNATIVE,
                Swift_Mime_SimpleMimeEntity::LEVEL_RELATED,
                ],
                'type' => 'multipart/alternative',
                ],
            ];

        foreach ($combinations as $combination) {
            $children = [];
            foreach ($combination['levels'] as $level) {
                $children[] = $this->createChild($level);
            }

            $cType = $this->createHeader(
                'Content-Type', 'text/plain', [], false
                );
            $cType->shouldReceive('setFieldBodyModel')
                  ->once()
                  ->with($combination['type']);

            $headerSet = $this->createHeaderSet(['Content-Type' => $cType]);
            $headerSet->shouldReceive('newInstance')
                      ->zeroOrMoreTimes()
                      ->andReturnUsing(function () use ($headerSet) {
                          return $headerSet;
                      });
            $entity = $this->createEntity($headerSet,
                $this->createEncoder(), $this->createCache()
                );
            $entity->setChildren($children);
        }
    }

    public function testChildrenAppearNestedInString()
    {
        /* -- RFC 2046, 5.1.1.
     (excerpt too verbose to paste here)
     */

        $headers = $this->createHeaderSet([], false);

        $child1 = new MimeEntityFixture(Swift_Mime_SimpleMimeEntity::LEVEL_ALTERNATIVE,
            "Content-Type: text/plain\r\n".
            "\r\n".
            'foobar', 'text/plain'
            );

        $child2 = new MimeEntityFixture(Swift_Mime_SimpleMimeEntity::LEVEL_ALTERNATIVE,
            "Content-Type: text/html\r\n".
            "\r\n".
            '<b>foobar</b>', 'text/html'
            );

        $headers->shouldReceive('toString')
              ->zeroOrMoreTimes()
              ->andReturn("Content-Type: multipart/alternative; boundary=\"xxx\"\r\n");

        $entity = $this->createEntity($headers, $this->createEncoder(),
            $this->createCache()
            );
        $entity->setBoundary('xxx');
        $entity->setChildren([$child1, $child2]);

        $this->assertEquals(
            "Content-Type: multipart/alternative; boundary=\"xxx\"\r\n".
            "\r\n".
            "\r\n--xxx\r\n".
            "Content-Type: text/plain\r\n".
            "\r\n".
            "foobar\r\n".
            "\r\n--xxx\r\n".
            "Content-Type: text/html\r\n".
            "\r\n".
            "<b>foobar</b>\r\n".
            "\r\n--xxx--\r\n",
            $entity->toString()
            );
    }

    public function testMixingLevelsIsHierarchical()
    {
        $headers = $this->createHeaderSet([], false);
        $newHeaders = $this->createHeaderSet([], false);

        $part = $this->createChild(Swift_Mime_SimpleMimeEntity::LEVEL_ALTERNATIVE,
            "Content-Type: text/plain\r\n".
            "\r\n".
            'foobar'
            );

        $attachment = $this->createChild(Swift_Mime_SimpleMimeEntity::LEVEL_MIXED,
            "Content-Type: application/octet-stream\r\n".
            "\r\n".
            'data'
            );

        $headers->shouldReceive('toString')
              ->zeroOrMoreTimes()
              ->andReturn("Content-Type: multipart/mixed; boundary=\"xxx\"\r\n");
        $headers->shouldReceive('newInstance')
              ->zeroOrMoreTimes()
              ->andReturn($newHeaders);
        $newHeaders->shouldReceive('toString')
              ->zeroOrMoreTimes()
              ->andReturn("Content-Type: multipart/alternative; boundary=\"yyy\"\r\n");

        $entity = $this->createEntity($headers, $this->createEncoder(),
            $this->createCache()
            );
        $entity->setBoundary('xxx');
        $entity->setChildren([$part, $attachment]);

        $this->assertMatchesRegularExpression(
            '~^'.
            "Content-Type: multipart/mixed; boundary=\"xxx\"\r\n".
            "\r\n\r\n--xxx\r\n".
            "Content-Type: multipart/alternative; boundary=\"yyy\"\r\n".
            "\r\n\r\n--(.*?)\r\n".
            "Content-Type: text/plain\r\n".
            "\r\n".
            'foobar'.
            "\r\n\r\n--\\1--\r\n".
            "\r\n\r\n--xxx\r\n".
            "Content-Type: application/octet-stream\r\n".
            "\r\n".
            'data'.
            "\r\n\r\n--xxx--\r\n".
            '$~',
            $entity->toString()
            );
    }

    public function testSettingEncoderNotifiesChildren()
    {
        $child = $this->createChild(0, '', false);
        $encoder = $this->createEncoder('base64');

        $child->shouldReceive('encoderChanged')
              ->once()
              ->with($encoder);

        $entity = $this->createEntity($this->createHeaderSet(),
            $this->createEncoder(), $this->createCache()
            );
        $entity->setChildren([$child]);
        $entity->setEncoder($encoder);
    }

    public function testReceiptOfEncoderChangeNotifiesChildren()
    {
        $child = $this->createChild(0, '', false);
        $encoder = $this->createEncoder('base64');

        $child->shouldReceive('encoderChanged')
              ->once()
              ->with($encoder);

        $entity = $this->createEntity($this->createHeaderSet(),
            $this->createEncoder(), $this->createCache()
            );
        $entity->setChildren([$child]);
        $entity->encoderChanged($encoder);
    }

    public function testReceiptOfCharsetChangeNotifiesChildren()
    {
        $child = $this->createChild(0, '', false);
        $child->shouldReceive('charsetChanged')
              ->once()
              ->with('windows-874');

        $entity = $this->createEntity($this->createHeaderSet(),
            $this->createEncoder(), $this->createCache()
            );
        $entity->setChildren([$child]);
        $entity->charsetChanged('windows-874');
    }

    public function testEntityIsWrittenToByteStream()
    {
        $entity = $this->createEntity($this->createHeaderSet(),
            $this->createEncoder(), $this->createCache()
            );
        $is = $this->createInputStream(false);
        $is->expects($this->atLeastOnce())
           ->method('write');

        $entity->toByteStream($is);
    }

    public function testEntityHeadersAreComittedToByteStream()
    {
        $entity = $this->createEntity($this->createHeaderSet(),
            $this->createEncoder(), $this->createCache()
            );
        $is = $this->createInputStream(false);
        $is->expects($this->atLeastOnce())
           ->method('write');
        $is->expects($this->atLeastOnce())
           ->method('commit');

        $entity->toByteStream($is);
    }

    public function testOrderingTextBeforeHtml()
    {
        $htmlChild = new MimeEntityFixture(Swift_Mime_SimpleMimeEntity::LEVEL_ALTERNATIVE,
            "Content-Type: text/html\r\n".
            "\r\n".
            'HTML PART',
            'text/html'
            );
        $textChild = new MimeEntityFixture(Swift_Mime_SimpleMimeEntity::LEVEL_ALTERNATIVE,
            "Content-Type: text/plain\r\n".
            "\r\n".
            'TEXT PART',
            'text/plain'
            );
        $headers = $this->createHeaderSet([], false);
        $headers->shouldReceive('toString')
                ->zeroOrMoreTimes()
                ->andReturn("Content-Type: multipart/alternative; boundary=\"xxx\"\r\n");

        $entity = $this->createEntity($headers, $this->createEncoder(),
            $this->createCache()
            );
        $entity->setBoundary('xxx');
        $entity->setChildren([$htmlChild, $textChild]);

        $this->assertEquals(
            "Content-Type: multipart/alternative; boundary=\"xxx\"\r\n".
            "\r\n\r\n--xxx\r\n".
            "Content-Type: text/plain\r\n".
            "\r\n".
            'TEXT PART'.
            "\r\n\r\n--xxx\r\n".
            "Content-Type: text/html\r\n".
            "\r\n".
            'HTML PART'.
            "\r\n\r\n--xxx--\r\n",
            $entity->toString()
            );
    }

    public function testOrderingEqualContentTypesMaintainsOriginalOrdering()
    {
        $firstChild = new MimeEntityFixture(Swift_Mime_SimpleMimeEntity::LEVEL_ALTERNATIVE,
            "Content-Type: text/plain\r\n".
            "\r\n".
            'PART 1',
            'text/plain'
        );
        $secondChild = new MimeEntityFixture(Swift_Mime_SimpleMimeEntity::LEVEL_ALTERNATIVE,
            "Content-Type: text/plain\r\n".
            "\r\n".
            'PART 2',
            'text/plain'
        );
        $headers = $this->createHeaderSet([], false);
        $headers->shouldReceive('toString')
            ->zeroOrMoreTimes()
            ->andReturn("Content-Type: multipart/alternative; boundary=\"xxx\"\r\n");

        $entity = $this->createEntity($headers, $this->createEncoder(),
            $this->createCache()
        );
        $entity->setBoundary('xxx');
        $entity->setChildren([$firstChild, $secondChild]);

        $this->assertEquals(
            "Content-Type: multipart/alternative; boundary=\"xxx\"\r\n".
            "\r\n\r\n--xxx\r\n".
            "Content-Type: text/plain\r\n".
            "\r\n".
            'PART 1'.
            "\r\n\r\n--xxx\r\n".
            "Content-Type: text/plain\r\n".
            "\r\n".
            'PART 2'.
            "\r\n\r\n--xxx--\r\n",
            $entity->toString()
        );
    }

    public function testUnsettingChildrenRestoresContentType()
    {
        $cType = $this->createHeader('Content-Type', 'text/plain', [], false);
        $child = $this->createChild(Swift_Mime_SimpleMimeEntity::LEVEL_ALTERNATIVE);

        $cType->shouldReceive('setFieldBodyModel')
              ->twice()
              ->with('image/jpeg');
        $cType->shouldReceive('setFieldBodyModel')
              ->once()
              ->with('multipart/alternative');
        $cType->shouldReceive('setFieldBodyModel')
              ->zeroOrMoreTimes()
              ->with(\Mockery::not('multipart/alternative', 'image/jpeg'));

        $entity = $this->createEntity($this->createHeaderSet([
            'Content-Type' => $cType,
            ]),
            $this->createEncoder(), $this->createCache()
            );

        $entity->setContentType('image/jpeg');
        $entity->setChildren([$child]);
        $entity->setChildren([]);
    }

    public function testBodyIsReadFromCacheWhenUsingToStringIfPresent()
    {
        $headers = $this->createHeaderSet([], false);
        $headers->shouldReceive('toString')
                ->zeroOrMoreTimes()
                ->andReturn("Content-Type: text/plain; charset=utf-8\r\n");

        $cache = $this->createCache(false);
        $cache->shouldReceive('hasKey')
              ->once()
              ->with(\Mockery::any(), 'body')
              ->andReturn(true);
        $cache->shouldReceive('getString')
              ->once()
              ->with(\Mockery::any(), 'body')
              ->andReturn("\r\ncache\r\ncache!");

        $entity = $this->createEntity($headers, $this->createEncoder(),
            $cache
            );

        $entity->setBody("blah\r\nblah!");
        $this->assertEquals(
            "Content-Type: text/plain; charset=utf-8\r\n".
            "\r\n".
            "cache\r\ncache!",
            $entity->toString()
            );
    }

    public function testBodyIsAddedToCacheWhenUsingToString()
    {
        $headers = $this->createHeaderSet([], false);
        $headers->shouldReceive('toString')
                ->zeroOrMoreTimes()
                ->andReturn("Content-Type: text/plain; charset=utf-8\r\n");

        $cache = $this->createCache(false);
        $cache->shouldReceive('hasKey')
              ->once()
              ->with(\Mockery::any(), 'body')
              ->andReturn(false);
        $cache->shouldReceive('setString')
              ->once()
              ->with(\Mockery::any(), 'body', "\r\nblah\r\nblah!", Swift_KeyCache::MODE_WRITE);

        $entity = $this->createEntity($headers, $this->createEncoder(),
            $cache
            );

        $entity->setBody("blah\r\nblah!");
        $entity->toString();
    }

    public function testBodyIsClearedFromCacheIfNewBodySet()
    {
        $headers = $this->createHeaderSet([], false);
        $headers->shouldReceive('toString')
                ->zeroOrMoreTimes()
                ->andReturn("Content-Type: text/plain; charset=utf-8\r\n");

        $cache = $this->createCache(false);
        $entity = $this->createEntity($headers, $this->createEncoder(),
            $cache
            );

        $entity->setBody("blah\r\nblah!");
        $entity->toString();

        // We set the expectation at this point because we only care what happens when calling setBody()
        $cache->shouldReceive('clearKey')
              ->once()
              ->with(\Mockery::any(), 'body');

        $entity->setBody("new\r\nnew!");
    }

    public function testBodyIsNotClearedFromCacheIfSameBodySet()
    {
        $headers = $this->createHeaderSet([], false);
        $headers->shouldReceive('toString')
                ->zeroOrMoreTimes()
                ->andReturn("Content-Type: text/plain; charset=utf-8\r\n");

        $cache = $this->createCache(false);
        $entity = $this->createEntity($headers, $this->createEncoder(),
            $cache
            );

        $entity->setBody("blah\r\nblah!");
        $entity->toString();

        // We set the expectation at this point because we only care what happens when calling setBody()
        $cache->shouldReceive('clearKey')
              ->never();

        $entity->setBody("blah\r\nblah!");
    }

    public function testBodyIsClearedFromCacheIfNewEncoderSet()
    {
        $headers = $this->createHeaderSet([], false);
        $headers->shouldReceive('toString')
                ->zeroOrMoreTimes()
                ->andReturn("Content-Type: text/plain; charset=utf-8\r\n");

        $cache = $this->createCache(false);
        $otherEncoder = $this->createEncoder();
        $entity = $this->createEntity($headers, $this->createEncoder(),
            $cache
            );

        $entity->setBody("blah\r\nblah!");
        $entity->toString();

        // We set the expectation at this point because we only care what happens when calling setEncoder()
        $cache->shouldReceive('clearKey')
              ->once()
              ->with(\Mockery::any(), 'body');

        $entity->setEncoder($otherEncoder);
    }

    public function testBodyIsReadFromCacheWhenUsingToByteStreamIfPresent()
    {
        $is = $this->createInputStream();
        $cache = $this->createCache(false);
        $cache->shouldReceive('hasKey')
              ->once()
              ->with(\Mockery::any(), 'body')
              ->andReturn(true);
        $cache->shouldReceive('exportToByteStream')
              ->once()
              ->with(\Mockery::any(), 'body', $is);

        $entity = $this->createEntity($this->createHeaderSet(),
            $this->createEncoder(), $cache
            );
        $entity->setBody('foo');

        $entity->toByteStream($is);
    }

    public function testBodyIsAddedToCacheWhenUsingToByteStream()
    {
        $is = $this->createInputStream();
        $cache = $this->createCache(false);
        $cache->shouldReceive('hasKey')
              ->once()
              ->with(\Mockery::any(), 'body')
              ->andReturn(false);
        $cache->shouldReceive('getInputByteStream')
              ->once()
              ->with(\Mockery::any(), 'body');

        $entity = $this->createEntity($this->createHeaderSet(),
            $this->createEncoder(), $cache
            );
        $entity->setBody('foo');

        $entity->toByteStream($is);
    }

    public function testFluidInterface()
    {
        $entity = $this->createEntity($this->createHeaderSet(),
            $this->createEncoder(), $this->createCache()
            );

        $this->assertSame($entity,
            $entity
            ->setContentType('text/plain')
            ->setEncoder($this->createEncoder())
            ->setId('foo@bar')
            ->setDescription('my description')
            ->setMaxLineLength(998)
            ->setBody('xx')
            ->setBoundary('xyz')
            ->setChildren([])
            );
    }

    abstract protected function createEntity($headers, $encoder, $cache);

    protected function createChild($level = null, $string = '', $stub = true)
    {
        $child = $this->getMockery('Swift_Mime_SimpleMimeEntity')->shouldIgnoreMissing();
        if (isset($level)) {
            $child->shouldReceive('getNestingLevel')
                  ->zeroOrMoreTimes()
                  ->andReturn($level);
        }
        $child->shouldReceive('toString')
              ->zeroOrMoreTimes()
              ->andReturn($string);

        return $child;
    }

    protected function createEncoder($name = 'quoted-printable', $stub = true)
    {
        $encoder = $this->getMockBuilder('Swift_Mime_ContentEncoder')->getMock();
        $encoder->expects($this->any())
                ->method('getName')
                ->willReturn($name);
        $encoder->expects($this->any())
                ->method('encodeString')
                ->willReturnCallback(function () {
                    $args = \func_get_args();

                    return array_shift($args);
                });

        return $encoder;
    }

    protected function createCache($stub = true)
    {
        return $this->getMockery('Swift_KeyCache')->shouldIgnoreMissing();
    }

    protected function createHeaderSet($headers = [], $stub = true)
    {
        $set = $this->getMockery('Swift_Mime_SimpleHeaderSet')->shouldIgnoreMissing();
        $set->shouldReceive('get')
            ->zeroOrMoreTimes()
            ->andReturnUsing(function ($key) use ($headers) {
                return $headers[$key];
            });
        $set->shouldReceive('has')
            ->zeroOrMoreTimes()
            ->andReturnUsing(function ($key) use ($headers) {
                return \array_key_exists($key, $headers);
            });

        return $set;
    }

    protected function createHeader($name, $model = null, $params = [], $stub = true)
    {
        $header = $this->getMockery('Swift_Mime_Headers_ParameterizedHeader')->shouldIgnoreMissing();
        $header->shouldReceive('getFieldName')
               ->zeroOrMoreTimes()
               ->andReturn($name);
        $header->shouldReceive('getFieldBodyModel')
               ->zeroOrMoreTimes()
               ->andReturn($model);
        $header->shouldReceive('getParameter')
               ->zeroOrMoreTimes()
               ->andReturnUsing(function ($key) use ($params) {
                   return $params[$key];
               });

        return $header;
    }

    protected function createOutputStream($data = null, $stub = true)
    {
        $os = $this->getMockery('Swift_OutputByteStream');
        if (isset($data)) {
            $os->shouldReceive('read')
               ->zeroOrMoreTimes()
               ->andReturnUsing(function () use ($data) {
                   static $first = true;
                   if (!$first) {
                       return false;
                   }

                   $first = false;

                   return $data;
               });
            $os->shouldReceive('setReadPointer')
              ->zeroOrMoreTimes();
        }

        return $os;
    }

    protected function createInputStream($stub = true)
    {
        return $this->getMockBuilder('Swift_InputByteStream')->getMock();
    }
}


================================================
FILE: tests/unit/Swift/Mime/AttachmentTest.php
================================================
<?php

class Swift_Mime_AttachmentTest extends Swift_Mime_AbstractMimeEntityTest
{
    public function testNestingLevelIsAttachment()
    {
        $attachment = $this->createAttachment($this->createHeaderSet(),
            $this->createEncoder(), $this->createCache()
            );
        $this->assertEquals(
            Swift_Mime_SimpleMimeEntity::LEVEL_MIXED, $attachment->getNestingLevel()
            );
    }

    public function testDispositionIsReturnedFromHeader()
    {
        /* -- RFC 2183, 2.1, 2.2.
     */

        $disposition = $this->createHeader('Content-Disposition', 'attachment');
        $attachment = $this->createAttachment($this->createHeaderSet([
            'Content-Disposition' => $disposition, ]),
            $this->createEncoder(), $this->createCache()
            );
        $this->assertEquals('attachment', $attachment->getDisposition());
    }

    public function testDispositionIsSetInHeader()
    {
        $disposition = $this->createHeader('Content-Disposition', 'attachment',
            [], false
            );
        $disposition->shouldReceive('setFieldBodyModel')
                    ->once()
                    ->with('inline');
        $disposition->shouldReceive('setFieldBodyModel')
                    ->zeroOrMoreTimes();

        $attachment = $this->createAttachment($this->createHeaderSet([
            'Content-Disposition' => $disposition, ]),
            $this->createEncoder(), $this->createCache()
            );
        $attachment->setDisposition('inline');
    }

    public function testDispositionIsAddedIfNonePresent()
    {
        $headers = $this->createHeaderSet([], false);
        $headers->shouldReceive('addParameterizedHeader')
                ->once()
                ->with('Content-Disposition', 'inline');
        $headers->shouldReceive('addParameterizedHeader')
                ->zeroOrMoreTimes();

        $attachment = $this->createAttachment($headers, $this->createEncoder(),
            $this->createCache()
            );
        $attachment->setDisposition('inline');
    }

    public function testDispositionIsAutoDefaultedToAttachment()
    {
        $headers = $this->createHeaderSet([], false);
        $headers->shouldReceive('addParameterizedHeader')
                ->once()
                ->with('Content-Disposition', 'attachment');
        $headers->shouldReceive('addParameterizedHeader')
                ->zeroOrMoreTimes();

        $attachment = $this->createAttachment($headers, $this->createEncoder(),
            $this->createCache()
            );
    }

    public function testDefaultContentTypeInitializedToOctetStream()
    {
        $cType = $this->createHeader('Content-Type', '',
            [], false
            );
        $cType->shouldReceive('setFieldBodyModel')
              ->once()
              ->with('application/octet-stream');
        $cType->shouldReceive('setFieldBodyModel')
              ->zeroOrMoreTimes();

        $attachment = $this->createAttachment($this->createHeaderSet([
            'Content-Type' => $cType, ]),
            $this->createEncoder(), $this->createCache()
            );
    }

    public function testFilenameIsReturnedFromHeader()
    {
        /* -- RFC 2183, 2.3.
     */

        $disposition = $this->createHeader('Content-Disposition', 'attachment',
            ['filename' => 'foo.txt']
            );
        $attachment = $this->createAttachment($this->createHeaderSet([
            'Content-Disposition' => $disposition, ]),
            $this->createEncoder(), $this->createCache()
            );
        $this->assertEquals('foo.txt', $attachment->getFilename());
    }

    public function testFilenameIsSetInHeader()
    {
        $disposition = $this->createHeader('Content-Disposition', 'attachment',
            ['filename' => 'foo.txt'], false
            );
        $disposition->shouldReceive('setParameter')
                    ->once()
                    ->with('filename', 'bar.txt');
        $disposition->shouldReceive('setParameter')
                    ->zeroOrMoreTimes();

        $attachment = $this->createAttachment($this->createHeaderSet([
            'Content-Disposition' => $disposition, ]),
            $this->createEncoder(), $this->createCache()
            );
        $attachment->setFilename('bar.txt');
    }

    public function testSettingFilenameSetsNameInContentType()
    {
        /*
     This is a legacy requirement which isn't covered by up-to-date RFCs.
     */

        $cType = $this->createHeader('Content-Type', 'text/plain',
            [], false
            );
        $cType->shouldReceive('setParameter')
              ->once()
              ->with('name', 'bar.txt');
        $cType->shouldReceive('setParameter')
              ->zeroOrMoreTimes();

        $attachment = $this->createAttachment($this->createHeaderSet([
            'Content-Type' => $cType, ]),
            $this->createEncoder(), $this->createCache()
            );
        $attachment->setFilename('bar.txt');
    }

    public function testSizeIsReturnedFromHeader()
    {
        /* -- RFC 2183, 2.7.
     */

        $disposition = $this->createHeader('Content-Disposition', 'attachment',
            ['size' => 1234]
            );
        $attachment = $this->createAttachment($this->createHeaderSet([
            'Content-Disposition' => $disposition, ]),
            $this->createEncoder(), $this->createCache()
            );
        $this->assertEquals(1234, $attachment->getSize());
    }

    public function testSizeIsSetInHeader()
    {
        $disposition = $this->createHeader('Content-Disposition', 'attachment',
            [], false
            );
        $disposition->shouldReceive('setParameter')
                    ->once()
                    ->with('size', 12345);
        $disposition->shouldReceive('setParameter')
                    ->zeroOrMoreTimes();

        $attachment = $this->createAttachment($this->createHeaderSet([
            'Content-Disposition' => $disposition, ]),
            $this->createEncoder(), $this->createCache()
            );
        $attachment->setSize(12345);
    }

    public function testFilnameCanBeReadFromFileStream()
    {
        $file = $this->createFileStream('/bar/file.ext', '');
        $disposition = $this->createHeader('Content-Disposition', 'attachment',
            ['filename' => 'foo.txt'], false
            );
        $disposition->shouldReceive('setParameter')
                    ->once()
                    ->with('filename', 'file.ext');

        $attachment = $this->createAttachment($this->createHeaderSet([
            'Content-Disposition' => $disposition, ]),
            $this->createEncoder(), $this->createCache()
            );
        $attachment->setFile($file);
    }

    public function testContentTypeCanBeSetViaSetFile()
    {
        $file = $this->createFileStream('/bar/file.ext', '');
        $disposition = $this->createHeader('Content-Disposition', 'attachment',
            ['filename' => 'foo.txt'], false
            );
        $disposition->shouldReceive('setParameter')
                    ->once()
                    ->with('filename', 'file.ext');

        $ctype = $this->createHeader('Content-Type', 'text/plain', [], false);
        $ctype->shouldReceive('setFieldBodyModel')
              ->once()
              ->with('text/html');
        $ctype->shouldReceive('setFieldBodyModel')
              ->zeroOrMoreTimes();

        $headers = $this->createHeaderSet([
            'Content-Disposition' => $disposition,
            'Content-Type' => $ctype,
            ]);

        $attachment = $this->createAttachment($headers, $this->createEncoder(),
            $this->createCache()
            );
        $attachment->setFile($file, 'text/html');
    }

    public function XtestContentTypeCanBeLookedUpFromCommonListIfNotProvided()
    {
        $file = $this->createFileStream('/bar/file.zip', '');
        $disposition = $this->createHeader('Content-Disposition', 'attachment',
            ['filename' => 'foo.zip'], false
            );
        $disposition->shouldReceive('setParameter')
                    ->once()
                    ->with('filename', 'file.zip');

        $ctype = $this->createHeader('Content-Type', 'text/plain', [], false);
        $ctype->shouldReceive('setFieldBodyModel')
              ->once()
              ->with('application/zip');
        $ctype->shouldReceive('setFieldBodyModel')
              ->zeroOrMoreTimes();

        $headers = $this->createHeaderSet([
            'Content-Disposition' => $disposition,
            'Content-Type' => $ctype,
            ]);

        $attachment = $this->createAttachment($headers, $this->createEncoder(),
            $this->createCache(), ['zip' => 'application/zip', 'txt' => 'text/plain']
            );
        $attachment->setFile($file);
    }

    public function testDataCanBeReadFromFile()
    {
        $file = $this->createFileStream('/foo/file.ext', '<some data>');
        $attachment = $this->createAttachment($this->createHeaderSet(),
            $this->createEncoder(), $this->createCache()
            );
        $attachment->setFile($file);
        $this->assertEquals('<some data>', $attachment->getBody());
    }

    public function testFluidInterface()
    {
        $attachment = $this->createAttachment($this->createHeaderSet(),
            $this->createEncoder(), $this->createCache()
            );
        $this->assertSame($attachment,
            $attachment
            ->setContentType('application/pdf')
            ->setEncoder($this->createEncoder())
            ->setId('foo@bar')
            ->setDescription('my pdf')
            ->setMaxLineLength(998)
            ->setBody('xx')
            ->setBoundary('xyz')
            ->setChildren([])
            ->setDisposition('inline')
            ->setFilename('afile.txt')
            ->setSize(123)
            ->setFile($this->createFileStream('foo.txt', ''))
            );
    }

    protected function createEntity($headers, $encoder, $cache)
    {
        return $this->createAttachment($headers, $encoder, $cache);
    }

    protected function createAttachment($headers, $encoder, $cache, $mimeTypes = [])
    {
        $idGenerator = new Swift_Mime_IdGenerator('example.com');

        return new Swift_Mime_Attachment($headers, $encoder, $cache, $idGenerator, $mimeTypes);
    }

    protected function createFileStream($path, $data, $stub = true)
    {
        $file = $this->getMockery('Swift_FileStream');
        $file->shouldReceive('getPath')
             ->zeroOrMoreTimes()
             ->andReturn($path);
        $file->shouldReceive('read')
             ->zeroOrMoreTimes()
             ->andReturnUsing(function () use ($data) {
                 static $first = true;
                 if (!$first) {
                     return false;
                 }

                 $first = false;

                 return $data;
             });
        $file->shouldReceive('setReadPointer')
             ->zeroOrMoreTimes();

        return $file;
    }
}


================================================
FILE: tests/unit/Swift/Mime/ContentEncoder/Base64ContentEncoderTest.php
================================================
<?php

class Swift_Mime_ContentEncoder_Base64ContentEncoderTest extends \SwiftMailerTestCase
{
    private $encoder;

    protected function setUp()
    {
        $this->encoder = new Swift_Mime_ContentEncoder_Base64ContentEncoder();
    }

    public function testNameIsBase64()
    {
        $this->assertEquals('base64', $this->encoder->getName());
    }

    /*
    There's really no point in testing the entire base64 encoding to the
    level QP encoding has been tested.  base64_encode() has been in PHP for
    years.
    */

    public function testInputOutputRatioIs3to4Bytes()
    {
        /*
        RFC 2045, 6.8

         The encoding process represents 24-bit groups of input bits as output
         strings of 4 encoded characters.  Proceeding from left to right, a
         24-bit input group is formed by concatenating 3 8bit input groups.
         These 24 bits are then treated as 4 concatenated 6-bit groups, each
         of which is translated into a single digit in the base64 alphabet.
         */

        $os = $this->createOutputByteStream();
        $is = $this->createInputByteStream();
        $collection = new Swift_StreamCollector();

        $is->shouldReceive('write')
           ->zeroOrMoreTimes()
           ->andReturnUsing($collection);
        $os->shouldReceive('read')
           ->once()
           ->andReturn('123');
        $os->shouldReceive('read')
           ->zeroOrMoreTimes()
           ->andReturn(false);

        $this->encoder->encodeByteStream($os, $is);
        $this->assertEquals('MTIz', $collection->content);
    }

    public function testPadLength()
    {
        /*
        RFC 2045, 6.8

       Special processing is performed if fewer than 24 bits are available
       at the end of the data being encoded.  A full encoding quantum is
       always completed at the end of a body.  When fewer than 24 input bits
       are available in an input group, zero bits are added (on the right)
       to form an integral number of 6-bit groups.  Padding at the end of
       the data is performed using the "=" character.  Since all base64
       input is an integral number of octets, only the following cases can
       arise: (1) the final quantum of encoding input is an integral
       multiple of 24 bits; here, the final unit of encoded output will be
       an integral multiple of 4 characters with no "=" padding, (2) the
       final quantum of encoding input is exactly 8 bits; here, the final
       unit of encoded output will be two characters followed by two "="
       padding characters, or (3) the final quantum of encoding input is
       exactly 16 bits; here, the final unit of encoded output will be three
       characters followed by one "=" padding character.
       */

        for ($i = 0; $i < 30; ++$i) {
            $os = $this->createOutputByteStream();
            $is = $this->createInputByteStream();
            $collection = new Swift_StreamCollector();

            $is->shouldReceive('write')
               ->zeroOrMoreTimes()
               ->andReturnUsing($collection);
            $os->shouldReceive('read')
               ->once()
               ->andReturn(pack('C', random_int(0, 255)));
            $os->shouldReceive('read')
               ->zeroOrMoreTimes()
               ->andReturn(false);

            $this->encoder->encodeByteStream($os, $is);
            $this->assertMatchesRegularExpression('~^[a-zA-Z0-9/\+]{2}==$~', $collection->content,
                '%s: A single byte should have 2 bytes of padding'
                );
        }

        for ($i = 0; $i < 30; ++$i) {
            $os = $this->createOutputByteStream();
            $is = $this->createInputByteStream();
            $collection = new Swift_StreamCollector();

            $is->shouldReceive('write')
               ->zeroOrMoreTimes()
               ->andReturnUsing($collection);
            $os->shouldReceive('read')
               ->once()
               ->andReturn(pack('C*', random_int(0, 255), random_int(0, 255)));
            $os->shouldReceive('read')
               ->zeroOrMoreTimes()
               ->andReturn(false);

            $this->encoder->encodeByteStream($os, $is);
            $this->assertMatchesRegularExpression('~^[a-zA-Z0-9/\+]{3}=$~', $collection->content,
                '%s: Two bytes should have 1 byte of padding'
                );
        }

        for ($i = 0; $i < 30; ++$i) {
            $os = $this->createOutputByteStream();
            $is = $this->createInputByteStream();
            $collection = new Swift_StreamCollector();

            $is->shouldReceive('write')
               ->zeroOrMoreTimes()
               ->andReturnUsing($collection);
            $os->shouldReceive('read')
               ->once()
               ->andReturn(pack('C*', random_int(0, 255), random_int(0, 255), random_int(0, 255)));
            $os->shouldReceive('read')
               ->zeroOrMoreTimes()
               ->andReturn(false);

            $this->encoder->encodeByteStream($os, $is);
            $this->assertMatchesRegularExpression('~^[a-zA-Z0-9/\+]{4}$~', $collection->content,
                '%s: Three bytes should have no padding'
                );
        }
    }

    public function testMaximumLineLengthIs76Characters()
    {
        /*
         The encoded output stream must be represented in lines of no more
         than 76 characters each.  All line breaks or other characters not
         found in Table 1 must be ignored by decoding software.
         */

        $os = $this->createOutputByteStream();
        $is = $this->createInputByteStream();
        $collection = new Swift_StreamCollector();

        $is->shouldReceive('write')
           ->zeroOrMoreTimes()
           ->andReturnUsing($collection);
        $os->shouldReceive('read')
           ->once()
           ->andReturn('abcdefghijkl'); //12
        $os->shouldReceive('read')
           ->once()
           ->andReturn('mnopqrstuvwx'); //24
        $os->shouldReceive('read')
           ->once()
           ->andReturn('yzabc1234567'); //36
        $os->shouldReceive('read')
           ->once()
           ->andReturn('890ABCDEFGHI'); //48
        $os->shouldReceive('read')
           ->once()
           ->andReturn('JKLMNOPQRSTU'); //60
        $os->shouldReceive('read')
           ->once()
           ->andReturn('VWXYZ1234567'); //72
        $os->shouldReceive('read')
           ->once()
           ->andReturn('abcdefghijkl'); //84
        $os->shouldReceive('read')
           ->zeroOrMoreTimes()
           ->andReturn(false);

        $this->encoder->encodeByteStream($os, $is);
        $this->assertEquals(
            "YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXphYmMxMjM0NTY3ODkwQUJDREVGR0hJSktMTU5PUFFS\r\n".
            'U1RVVldYWVoxMjM0NTY3YWJjZGVmZ2hpamts',
            $collection->content
            );
    }

    public function testMaximumLineLengthCanBeDifferent()
    {
        $os = $this->createOutputByteStream();
        $is = $this->createInputByteStream();
        $collection = new Swift_StreamCollector();

        $is->shouldReceive('write')
           ->zeroOrMoreTimes()
           ->andReturnUsing($collection);
        $os->shouldReceive('read')
           ->once()
           ->andReturn('abcdefghijkl'); //12
        $os->shouldReceive('read')
           ->once()
           ->andReturn('mnopqrstuvwx'); //24
        $os->shouldReceive('read')
           ->once()
           ->andReturn('yzabc1234567'); //36
        $os->shouldReceive('read')
           ->once()
           ->andReturn('890ABCDEFGHI'); //48
        $os->shouldReceive('read')
           ->once()
           ->andReturn('JKLMNOPQRSTU'); //60
        $os->shouldReceive('read')
           ->once()
           ->andReturn('VWXYZ1234567'); //72
        $os->shouldReceive('read')
           ->once()
           ->andReturn('abcdefghijkl'); //84
        $os->shouldReceive('read')
           ->zeroOrMoreTimes()
           ->andReturn(false);

        $this->encoder->encodeByteStream($os, $is, 0, 50);
        $this->assertEquals(
            "YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXphYmMxMjM0NTY3OD\r\n".
            "kwQUJDREVGR0hJSktMTU5PUFFSU1RVVldYWVoxMjM0NTY3YWJj\r\n".
            'ZGVmZ2hpamts',
            $collection->content
            );
    }

    public function testMaximumLineLengthIsNeverMoreThan76Chars()
    {
        $os = $this->createOutputByteStream();
        $is = $this->createInputByteStream();
        $collection = new Swift_StreamCollector();

        $is->shouldReceive('write')
           ->zeroOrMoreTimes()
           ->andReturnUsing($collection);
        $os->shouldReceive('read')
           ->once()
           ->andReturn('abcdefghijkl'); //12
        $os->shouldReceive('read')
           ->once()
           ->andReturn('mnopqrstuvwx'); //24
        $os->shouldReceive('read')
           ->once()
           ->andReturn('yzabc1234567'); //36
        $os->shouldReceive('read')
           ->once()
           ->andReturn('890ABCDEFGHI'); //48
        $os->shouldReceive('read')
           ->once()
           ->andReturn('JKLMNOPQRSTU'); //60
        $os->shouldReceive('read')
           ->once()
           ->andReturn('VWXYZ1234567'); //72
        $os->shouldReceive('read')
           ->once()
           ->andReturn('abcdefghijkl'); //84
        $os->shouldReceive('read')
           ->zeroOrMoreTimes()
           ->andReturn(false);

        $this->encoder->encodeByteStream($os, $is, 0, 100);
        $this->assertEquals(
            "YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXphYmMxMjM0NTY3ODkwQUJDREVGR0hJSktMTU5PUFFS\r\n".
            'U1RVVldYWVoxMjM0NTY3YWJjZGVmZ2hpamts',
            $collection->content
            );
    }

    public function testFirstLineLengthCanBeDifferent()
    {
        $os = $this->createOutputByteStream();
        $is = $this->createInputByteStream();
        $collection = new Swift_StreamCollector();

        $is->shouldReceive('write')
           ->zeroOrMoreTimes()
           ->andReturnUsing($collection);
        $os->shouldReceive('read')
           ->once()
           ->andReturn('abcdefghijkl'); //12
        $os->shouldReceive('read')
           ->once()
           ->andReturn('mnopqrstuvwx'); //24
        $os->shouldReceive('read')
           ->once()
           ->andReturn('yzabc1234567'); //36
        $os->shouldReceive('read')
           ->once()
           ->andReturn('890ABCDEFGHI'); //48
        $os->shouldReceive('read')
           ->once()
           ->andReturn('JKLMNOPQRSTU'); //60
        $os->shouldReceive('read')
           ->once()
           ->andReturn('VWXYZ1234567'); //72
        $os->shouldReceive('read')
           ->once()
           ->andReturn('abcdefghijkl'); //84
        $os->shouldReceive('read')
           ->zeroOrMoreTimes()
           ->andReturn(false);

        $this->encoder->encodeByteStream($os, $is, 19);
        $this->assertEquals(
            "YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXphYmMxMjM0NTY3ODkwQUJDR\r\n".
            'EVGR0hJSktMTU5PUFFSU1RVVldYWVoxMjM0NTY3YWJjZGVmZ2hpamts',
            $collection->content
            );
    }

    private function createOutputByteStream($stub = false)
    {
        return $this->getMockery('Swift_OutputByteStream')->shouldIgnoreMissing();
    }

    private function createInputByteStream($stub = false)
    {
        return $this->getMockery('Swift_InputByteStream')->shouldIgnoreMissing();
    }
}


================================================
FILE: tests/unit/Swift/Mime/ContentEncoder/PlainContentEncoderTest.php
================================================
<?php

class Swift_Mime_ContentEncoder_PlainContentEncoderTest extends \SwiftMailerTestCase
{
    public function testNameCanBeSpecifiedInConstructor()
    {
        $encoder = $this->getEncoder('7bit');
        $this->assertEquals('7bit', $encoder->getName());

        $encoder = $this->getEncoder('8bit');
        $this->assertEquals('8bit', $encoder->getName());
    }

    public function testNoOctetsAreModifiedInString()
    {
        $encoder = $this->getEncoder('7bit');
        foreach (range(0x00, 0xFF) as $octet) {
            $byte = pack('C', $octet);
            $this->assertIdenticalBinary($byte, $encoder->encodeString($byte));
        }
    }

    public function testNoOctetsAreModifiedInByteStream()
    {
        $encoder = $this->getEncoder('7bit');
        foreach (range(0x00, 0xFF) as $octet) {
            $byte = pack('C', $octet);

            $os = $this->createOutputByteStream();
            $is = $this->createInputByteStream();
            $collection = new Swift_StreamCollector();

            $is->shouldReceive('write')
               ->zeroOrMoreTimes()
               ->andReturnUsing($collection);
            $os->shouldReceive('read')
               ->once()
               ->andReturn($byte);
            $os->shouldReceive('read')
               ->zeroOrMoreTimes()
               ->andReturn(false);

            $encoder->encodeByteStream($os, $is);
            $this->assertIdenticalBinary($byte, $collection->content);
        }
    }

    public function testLineLengthCanBeSpecified()
    {
        $encoder = $this->getEncoder('7bit');

        $chars = [];
        for ($i = 0; $i < 50; ++$i) {
            $chars[] = 'a';
        }
        $input = implode(' ', $chars); //99 chars long

        $this->assertEquals(
            'a a a a a a a a a a a a a a a a a a a a a a a a a '."\r\n".//50 *
            'a a a a a a a a a a a a a a a a a a a a a a a a a',            //99
            $encoder->encodeString($input, 0, 50),
            '%s: Lines should be wrapped at 50 chars'
            );
    }

    public function testLineLengthCanBeSpecifiedInByteStream()
    {
        $encoder = $this->getEncoder('7bit');

        $os = $this->createOutputByteStream();
        $is = $this->createInputByteStream();
        $collection = new Swift_StreamCollector();

        $is->shouldReceive('write')
           ->zeroOrMoreTimes()
           ->andReturnUsing($collection);

        for ($i = 0; $i < 50; ++$i) {
            $os->shouldReceive('read')
               ->once()
               ->andReturn('a ');
        }

        $os->shouldReceive('read')
           ->zeroOrMoreTimes()
           ->andReturn(false);

        $encoder->encodeByteStream($os, $is, 0, 50);
        $this->assertEquals(
            str_repeat('a ', 25)."\r\n".str_repeat('a ', 25),
            $collection->content
            );
    }

    public function testencodeStringGeneratesCorrectCrlf()
    {
        $encoder = $this->getEncoder('7bit', true);
        $this->assertEquals("a\r\nb", $encoder->encodeString("a\rb"),
            '%s: Line endings should be standardized'
            );
        $this->assertEquals("a\r\nb", $encoder->encodeString("a\nb"),
            '%s: Line endings should be standardized'
            );
        $this->assertEquals("a\r\n\r\nb", $encoder->encodeString("a\n\rb"),
            '%s: Line endings should be standardized'
            );
        $this->assertEquals("a\r\n\r\nb", $encoder->encodeString("a\r\rb"),
            '%s: Line endings should be standardized'
            );
        $this->assertEquals("a\r\n\r\nb", $encoder->encodeString("a\n\nb"),
            '%s: Line endings should be standardized'
            );
    }

    public function crlfProvider()
    {
        return [
            ["\r", "a\r\nb"],
            ["\n", "a\r\nb"],
            ["\n\r", "a\r\n\r\nb"],
            ["\n\n", "a\r\n\r\nb"],
            ["\r\r", "a\r\n\r\nb"],
        ];
    }

    /**
     * @dataProvider crlfProvider
     */
    public function testCanonicEncodeByteStreamGeneratesCorrectCrlf($test, $expected)
    {
        $encoder = $this->getEncoder('7bit', true);

        $os = $this->createOutputByteStream();
        $is = $this->createInputByteStream();
        $collection = new Swift_StreamCollector();

        $is->shouldReceive('write')
           ->zeroOrMoreTimes()
           ->andReturnUsing($collection);
        $os->shouldReceive('read')
           ->once()
           ->andReturn('a');
        $os->shouldReceive('read')
           ->once()
           ->andReturn($test);
        $os->shouldReceive('read')
           ->once()
           ->andReturn('b');
        $os->shouldReceive('read')
           ->zeroOrMoreTimes()
           ->andReturn(false);

        $encoder->encodeByteStream($os, $is);
        $this->assertEquals($expected, $collection->content);
    }

    private function getEncoder($name, $canonical = false)
    {
        return new Swift_Mime_ContentEncoder_PlainContentEncoder($name, $canonical);
    }

    private function createOutputByteStream($stub = false)
    {
        return $this->getMockery('Swift_OutputByteStream')->shouldIgnoreMissing();
    }

    private function createInputByteStream($stub = false)
    {
        return $this->getMockery('Swift_InputByteStream')->shouldIgnoreMissing();
    }
}


================================================
FILE: tests/unit/Swift/Mime/ContentEncoder/QpContentEncoderTest.php
================================================
<?php

class Swift_Mime_ContentEncoder_QpContentEncoderTest extends \SwiftMailerTestCase
{
    public function testNameIsQuotedPrintable()
    {
        $encoder = new Swift_Mime_ContentEncoder_QpContentEncoder(
            $this->createCharacterStream(true)
            );
        $this->assertEquals('quoted-printable', $encoder->getName());
    }

    /* -- RFC 2045, 6.7 --
    (1)   (General 8bit representation) Any octet, except a CR or
                    LF that is part of a CRLF line break of the canonical
                    (standard) form of the data being encoded, may be
                    represented by an "=" followed by a two digit
                    hexadecimal representation of the octet's value.  The
                    digits of the hexadecimal alphabet, for this purpose,
                    are "0123456789ABCDEF".  Uppercase letters must be
                    used; lowercase letters are not allowed.  Thus, for
                    example, the decimal value 12 (US-ASCII form feed) can
                    be represented by "=0C", and the decimal value 61 (US-
                    ASCII EQUAL SIGN) can be represented by "=3D".  This
                    rule must be followed except when the following rules
                    allow an alternative encoding.
                    */

    public function testPermittedCharactersAreNotEncoded()
    {
        /* -- RFC 2045, 6.7 --
        (2)   (Literal representation) Octets with decimal values of
                    33 through 60 inclusive, and 62 through 126, inclusive,
                    MAY be represented as the US-ASCII characters which
                    correspond to those octets (EXCLAMATION POINT through
                    LESS THAN, and GREATER THAN through TILDE,
                    respectively).
                    */

        foreach (array_merge(range(33, 60), range(62, 126)) as $ordinal) {
            $char = \chr($ordinal);

            $os = $this->createOutputByteStream(true);
            $charStream = $this->createCharacterStream();
            $is = $this->createInputByteStream();
            $collection = new Swift_StreamCollector();

            $is->shouldReceive('write')
               ->zeroOrMoreTimes()
               ->andReturnUsing($collection);
            $charStream->shouldReceive('flushContents')
                       ->once();
            $charStream->shouldReceive('importByteStream')
                       ->once()
                       ->with($os);
            $charStream->shouldReceive('readBytes')
                       ->once()
                       ->andReturn([$ordinal]);
            $charStream->shouldReceive('readBytes')
                       ->zeroOrMoreTimes()
                       ->andReturn(false);

            $encoder = new Swift_Mime_ContentEncoder_QpContentEncoder($charStream);
            $encoder->encodeByteStream($os, $is);
            $this->assertIdenticalBinary($char, $collection->content);
        }
    }

    public function testLinearWhiteSpaceAtLineEndingIsEncoded()
    {
        /* -- RFC 2045, 6.7 --
        (3)   (White Space) Octets with values of 9 and 32 MAY be
                    represented as US-ASCII TAB (HT) and SPACE characters,
                    respectively, but MUST NOT be so represented at the end
                    of an encoded line.  Any TAB (HT) or SPACE characters
                    on an encoded line MUST thus be followed on that line
                    by a printable character.  In particular, an "=" at the
                    end of an encoded line, indicating a soft line break
                    (see rule #5) may follow one or more TAB (HT) or SPACE
                    characters.  It follows that an octet with decimal
                    value 9 or 32 appearing at the end of an encoded line
                    must be represented according to Rule #1.  This rule is
                    necessary because some MTAs (Message Transport Agents,
                    programs which transport messages from one user to
                    another, or perform a portion of such transfers) are
                    known to pad lines of text with SPACEs, and others are
                    known to remove "white space" characters from the end
                    of a line.  Therefore, when decoding a Quoted-Printable
                    body, any trailing white space on a line must be
                    deleted, as it will necessarily have been added by
                    intermediate transport agents.
                    */

        $HT = \chr(0x09); //9
        $SPACE = \chr(0x20); //32

        //HT
        $os = $this->createOutputByteStream(true);
        $charStream = $this->createCharacterStream();
        $is = $this->createInputByteStream();
        $collection = new Swift_StreamCollector();

        $is->shouldReceive('write')
               ->zeroOrMoreTimes()
               ->andReturnUsing($collection);
        $charStream->shouldReceive('flushContents')
                   ->once();
        $charStream->shouldReceive('importByteStream')
                   ->once()
                   ->with($os);
        $charStream->shouldReceive('readBytes')
                   ->once()
                   ->andReturn([\ord('a')]);
        $charStream->shouldReceive('readBytes')
                   ->once()
                   ->andReturn([0x09]);
        $charStream->shouldReceive('readBytes')
                   ->once()
                   ->andReturn([0x09]);
        $charStream->shouldReceive('readBytes')
                   ->once()
                   ->andReturn([0x0D]);
        $charStream->shouldReceive('readBytes')
                   ->once()
                   ->andReturn([0x0A]);
        $charStream->shouldReceive('readBytes')
                   ->once()
                   ->andReturn([\ord('b')]);
        $charStream->shouldReceive('readBytes')
                   ->zeroOrMoreTimes()
                   ->andReturn(false);

        $encoder = new Swift_Mime_ContentEncoder_QpContentEncoder($charStream);
        $encoder->encodeByteStream($os, $is);

        $this->assertEquals("a\t=09\r\nb", $collection->content);

        //SPACE
        $os = $this->createOutputByteStream(true);
        $charStream = $this->createCharacterStream();
        $is = $this->createInputByteStream();
        $collection = new Swift_StreamCollector();

        $is->shouldReceive('write')
               ->zeroOrMoreTimes()
               ->andReturnUsing($collection);
        $charStream->shouldReceive('flushContents')
                   ->once();
        $charStream->shouldReceive('importByteStream')
                   ->once()
                   ->with($os);
        $charStream->shouldReceive('readBytes')
                   ->once()
                   ->andReturn([\ord('a')]);
        $charStream->shouldReceive('readBytes')
                   ->once()
                   ->andReturn([0x20]);
        $charStream->shouldReceive('readBytes')
                   ->once()
                   ->andReturn([0x20]);
        $charStream->shouldReceive('readBytes')
                   ->once()
                   ->andReturn([0x0D]);
        $charStream->shouldReceive('readBytes')
                   ->once()
                   ->andReturn([0x0A]);
        $charStream->shouldReceive('readBytes')
                   ->once()
                   ->andReturn([\ord('b')]);
        $charStream->shouldReceive('readBytes')
                   ->zeroOrMoreTimes()
                   ->andReturn(false);

        $encoder = new Swift_Mime_ContentEncoder_QpContentEncoder($charStream);
        $encoder->encodeByteStream($os, $is);

        $this->assertEquals("a =20\r\nb", $collection->content);
    }

    public function testCRLFIsLeftAlone()
    {
        /*
        (4)   (Line Breaks) A line break in a text body, represented
                    as a CRLF sequence in the text canonical form, must be
                    represented by a (RFC 822) line break, which is also a
                    CRLF sequence, in the Quoted-Printable encoding.  Since
                    the canonical representation of media types other than
                    text do not generally include the representation of
                    line breaks as CRLF sequences, no hard line breaks
                    (i.e. line breaks that are intended to be meaningful
                    and to be displayed to the user) can occur in the
                    quoted-printable encoding of such types.  Sequences
                    like "=0D", "=0A", "=0A=0D" and "=0D=0A" will routinely
                    appear in non-text data represented in quoted-
                    printable, of course.

                    Note that many implementations may elect to encode the
                    local representation of various content types directly
                    rather than converting to canonical form first,
                    encoding, and then converting back to local
                    representation.  In particular, this may apply to plain
                    text material on systems that use newline conventions
                    other than a CRLF terminator sequence.  Such an
                    implementation optimization is permissible, but only
                    when the combined canonicalization-encoding step is
                    equivalent to performing the three steps separately.
                    */

        $os = $this->createOutputByteStream(true);
        $charStream = $this->createCharacterStream();
        $is = $this->createInputByteStream();
        $collection = new Swift_StreamCollector();

        $is->shouldReceive('write')
               ->zeroOrMoreTimes()
               ->andReturnUsing($collection);
        $charStream->shouldReceive('flushContents')
                   ->once();
        $charStream->shouldReceive('importByteStream')
                   ->once()
                   ->with($os);
        $charStream->shouldReceive('readBytes')
                   ->once()
                   ->andReturn([\ord('a')]);
        $charStream->shouldReceive('readBytes')
                   ->once()
                   ->andReturn([0x0D]);
        $charStream->shouldReceive('readBytes')
                   ->once()
                   ->andReturn([0x0A]);
        $charStream->shouldReceive('readBytes')
                   ->once()
                   ->andReturn([\ord('b')]);
        $charStream->shouldReceive('readBytes')
                   ->once()
                   ->andReturn([0x0D]);
        $charStream->shouldReceive('readBytes')
                   ->once()
                   ->andReturn([0x0A]);
        $charStream->shouldReceive('readBytes')
                   ->once()
                   ->andReturn([\ord('c')]);
        $charStream->shouldReceive('readBytes')
                   ->once()
                   ->andReturn([0x0D]);
        $charStream->shouldReceive('readBytes')
                   ->once()
                   ->andReturn([0x0A]);
        $charStream->shouldReceive('readBytes')
                   ->zeroOrMoreTimes()
                   ->andReturn(false);

        $encoder = new Swift_Mime_ContentEncoder_QpContentEncoder($charStream);
        $encoder->encodeByteStream($os, $is);
        $this->assertEquals("a\r\nb\r\nc\r\n", $collection->content);
    }

    public function testLinesLongerThan76CharactersAreSoftBroken()
    {
        /*
        (5)   (Soft Line Breaks) The Quoted-Printable encoding
                    REQUIRES that encoded lines be no more than 76
                    characters long.  If longer lines are to be encoded
                    with the Quoted-Printable encoding, "soft" line breaks
                    must be used.  An equal sign as the last character on a
                    encoded line indicates such a non-significant ("soft")
                    line break in the encoded text.
                    */

        $os = $this->createOutputByteStream(true);
        $charStream = $this->createCharacterStream();
        $is = $this->createInputByteStream();
        $collection = new Swift_StreamCollector();

        $is->shouldReceive('write')
           ->zeroOrMoreTimes()
           ->andReturnUsing($collection);
        $charStream->shouldReceive('flushContents')
                   ->once();
        $charStream->shouldReceive('importByteStream')
                   ->once()
                   ->with($os);

        for ($seq = 0; $seq <= 140; ++$seq) {
            $charStream->shouldReceive('readBytes')
                       ->once()
                       ->andReturn([\ord('a')]);
        }
        $charStream->shouldReceive('readBytes')
                   ->zeroOrMoreTimes()
                   ->andReturn(false);

        $encoder = new Swift_Mime_ContentEncoder_QpContentEncoder($charStream);
        $encoder->encodeByteStream($os, $is);
        $this->assertEquals(str_repeat('a', 75)."=\r\n".str_repeat('a', 66), $collection->content);
    }

    public function testMaxLineLengthCanBeSpecified()
    {
        $os = $this->createOutputByteStream(true);
        $charStream = $this->createCharacterStream();
        $is = $this->createInputByteStream();
        $collection = new Swift_StreamCollector();

        $is->shouldReceive('write')
           ->zeroOrMoreTimes()
           ->andReturnUsing($collection);
        $charStream->shouldReceive('flushContents')
                   ->once();
        $charStream->shouldReceive('importByteStream')
                   ->once()
                   ->with($os);

        for ($seq = 0; $seq <= 100; ++$seq) {
            $charStream->shouldReceive('readBytes')
                       ->once()
                       ->andReturn([\ord('a')]);
        }
        $charStream->shouldReceive('readBytes')
                   ->zeroOrMoreTimes()
                   ->andReturn(false);

        $encoder = new Swift_Mime_ContentEncoder_QpContentEncoder($charStream);
        $encoder->encodeByteStream($os, $is, 0, 54);
        $this->assertEquals(str_repeat('a', 53)."=\r\n".str_repeat('a', 48), $collection->content);
    }

    public function testBytesBelowPermittedRangeAreEncoded()
    {
        /*
        According to Rule (1 & 2)
        */

        foreach (range(0, 32) as $ordinal) {
            $char = \chr($ordinal);

            $os = $this->createOutputByteStream(true);
            $charStream = $this->createCharacterStream();
            $is = $this->createInputByteStream();
            $collection = new Swift_StreamCollector();

            $is->shouldReceive('write')
               ->zeroOrMoreTimes()
               ->andReturnUsing($collection);
            $charStream->shouldReceive('flushContents')
                       ->once();
            $charStream->shouldReceive('importByteStream')
                       ->once()
                       ->with($os);
            $charStream->shouldReceive('readBytes')
                       ->once()
                       ->andReturn([$ordinal]);
            $charStream->shouldReceive('readBytes')
                       ->zeroOrMoreTimes()
                       ->andReturn(false);

            $encoder = new Swift_Mime_ContentEncoder_QpContentEncoder($charStream);
            $encoder->encodeByteStream($os, $is);
            $this->assertEquals(sprintf('=%02X', $ordinal), $collection->content);
        }
    }

    public function testDecimalByte61IsEncoded()
    {
        /*
        According to Rule (1 & 2)
        */

        $char = \chr(61);

        $os = $this->createOutputByteStream(true);
        $charStream = $this->createCharacterStream();
        $is = $this->createInputByteStream();
        $collection = new Swift_StreamCollector();

        $is->shouldReceive('write')
               ->zeroOrMoreTimes()
               ->andReturnUsing($collection);
        $charStream->shouldReceive('flushContents')
                       ->once();
        $charStream->shouldReceive('importByteStream')
                       ->once()
                       ->with($os);
        $charStream->shouldReceive('readBytes')
                       ->once()
                       ->andReturn([61]);
        $charStream->shouldReceive('readBytes')
                       ->zeroOrMoreTimes()
                       ->andReturn(false);

        $encoder = new Swift_Mime_ContentEncoder_QpContentEncoder($charStream);
        $encoder->encodeByteStream($os, $is);
        $this->assertEquals(sprintf('=%02X', 61), $collection->content);
    }

    public function testBytesAbovePermittedRangeAreEncoded()
    {
        /*
        According to Rule (1 & 2)
        */

        foreach (range(127, 255) as $ordinal) {
            $char = \chr($ordinal);

            $os = $this->createOutputByteStream(true);
            $charStream = $this->createCharacterStream();
            $is = $this->createInputByteStream();
            $collection = new Swift_StreamCollector();

            $is->shouldReceive('write')
               ->zeroOrMoreTimes()
               ->andReturnUsing($collection);
            $charStream->shouldReceive('flushContents')
                       ->once();
            $charStream->shouldReceive('importByteStream')
                       ->once()
                       ->with($os);
            $charStream->shouldReceive('readBytes')
                       ->once()
                       ->andReturn([$ordinal]);
            $charStream->shouldReceive('readBytes')
                       ->zeroOrMoreTimes()
                       ->andReturn(false);

            $encoder = new Swift_Mime_ContentEncoder_QpContentEncoder($charStream);
            $encoder->encodeByteStream($os, $is);
            $this->assertEquals(sprintf('=%02X', $ordinal), $collection->content);
        }
    }

    public function testFirstLineLengthCanBeDifferent()
    {
        $os = $this->createOutputByteStream(true);
        $charStream = $this->createCharacterStream();
        $is = $this->createInputByteStream();
        $collection = new Swift_StreamCollector();

        $is->shouldReceive('write')
               ->zeroOrMoreTimes()
               ->andReturnUsing($collection);
        $charStream->shouldReceive('flushContents')
                    ->once();
        $charStream->shouldReceive('importByteStream')
                    ->once()
                    ->with($os);

        for ($seq = 0; $seq <= 140; ++$seq) {
            $charStream->shouldReceive('readBytes')
                       ->once()
                       ->andReturn([\ord('a')]);
        }
        $charStream->shouldReceive('readBytes')
                    ->zeroOrMoreTimes()
                    ->andReturn(false);

        $encoder = new Swift_Mime_ContentEncoder_QpContentEncoder($charStream);
        $encoder->encodeByteStream($os, $is, 22);
        $this->assertEquals(
            str_repeat('a', 53)."=\r\n".str_repeat('a', 75)."=\r\n".str_repeat('a', 13),
            $collection->content
            );
    }

    public function testObserverInterfaceCanChangeCharset()
    {
        $stream = $this->createCharacterStream();
        $stream->shouldReceive('setCharacterSet')
               ->once()
               ->with('windows-1252');

        $encoder = new Swift_Mime_ContentEncoder_QpContentEncoder($stream);
        $encoder->charsetChanged('windows-1252');
    }

    public function testTextIsPreWrapped()
    {
        $encoder = $this->createEncoder();

        $input = str_repeat('a', 70)."\r\n".
                 str_repeat('a', 70)."\r\n".
                 str_repeat('a', 70);

        $os = new Swift_ByteStream_ArrayByteStream();
        $is = new Swift_ByteStream_ArrayByteStream();
        $is->write($input);

        $encoder->encodeByteStream($is, $os);

        $this->assertEquals(
            $input, $os->read(PHP_INT_MAX)
            );
    }

    private function createCharacterStream($stub = false)
    {
        return $this->getMockery('Swift_CharacterStream')->shouldIgnoreMissing();
    }

    private function createEncoder()
    {
        $factory = new Swift_CharacterReaderFactory_SimpleCharacterReaderFactory();
        $charStream = new Swift_CharacterStream_NgCharacterStream($factory, 'utf-8');

        return new Swift_Mime_ContentEncoder_QpContentEncoder($charStream);
    }

    private function createOutputByteStream($stub = false)
    {
        return $this->getMockery('Swift_OutputByteStream')->shouldIgnoreMissing();
    }

    private function createInputByteStream($stub = false)
    {
        return $this->getMockery('Swift_InputByteStream')->shouldIgnoreMissing();
    }
}


================================================
FILE: tests/unit/Swift/Mime/EmbeddedFileTest.php
================================================
<?php

class Swift_Mime_EmbeddedFileTest extends Swift_Mime_AttachmentTest
{
    public function testNestingLevelIsAttachment()
    {
        // previous loop would fail if there is an issue
        $this->addToAssertionCount(1);
    }

    public function testNestingLevelIsEmbedded()
    {
        $file = $this->createEmbeddedFile($this->createHeaderSet(),
            $this->createEncoder(), $this->createCache()
            );
        $this->assertEquals(
            Swift_Mime_SimpleMimeEntity::LEVEL_RELATED, $file->getNestingLevel()
            );
    }

    public function testIdIsAutoGenerated()
    {
        $headers = $this->createHeaderSet([], false);
        $headers->shouldReceive('addIdHeader')
                ->once()
                ->with('Content-ID', \Mockery::pattern('/^.*?@.*?$/D'));

        $file = $this->createEmbeddedFile($headers, $this->createEncoder(),
            $this->createCache()
            );
    }

    public function testDefaultDispositionIsInline()
    {
        $headers = $this->createHeaderSet([], false);
        $headers->shouldReceive('addParameterizedHeader')
                ->once()
                ->with('Content-Disposition', 'inline');
        $headers->shouldReceive('addParameterizedHeader')
                ->zeroOrMoreTimes();

        $file = $this->createEmbeddedFile($headers, $this->createEncoder(),
            $this->createCache()
            );
    }

    protected function createAttachment($headers, $encoder, $cache, $mimeTypes = [])
    {
        return $this->createEmbeddedFile($headers, $encoder, $cache, $mimeTypes);
    }

    private function createEmbeddedFile($headers, $encoder, $cache)
    {
        $idGenerator = new Swift_Mime_IdGenerator('example.com');

        return new Swift_Mime_EmbeddedFile($headers, $encoder, $cache, $idGenerator);
    }
}


================================================
FILE: tests/unit/Swift/Mime/HeaderEncoder/Base64HeaderEncoderTest.php
================================================
<?php

class Swift_Mime_HeaderEncoder_Base64HeaderEncoderTest extends \PHPUnit\Framework\TestCase
{
    //Most tests are already covered in Base64EncoderTest since this subclass only
    // adds a getName() method

    public function testNameIsB()
    {
        $encoder = new Swift_Mime_HeaderEncoder_Base64HeaderEncoder();
        $this->assertEquals('B', $encoder->getName());
    }
}


================================================
FILE: tests/unit/Swift/Mime/HeaderEncoder/QpHeaderEncoderTest.php
================================================
<?php

class Swift_Mime_HeaderEncoder_QpHeaderEncoderTest extends \SwiftMailerTestCase
{
    //Most tests are already covered in QpEncoderTest since this subclass only
    // adds a getName() method

    public function testNameIsQ()
    {
        $encoder = $this->createEncoder(
            $this->createCharacterStream(true)
            );
        $this->assertEquals('Q', $encoder->getName());
    }

    public function testSpaceAndTabNeverAppear()
    {
        /* -- RFC 2047, 4.
     Only a subset of the printable ASCII characters may be used in
     'encoded-text'.  Space and tab characters are not allowed, so that
     the beginning and end of an 'encoded-word' are obvious.
     */

        $charStream = $this->createCharacterStream();
        $charStream->shouldReceive('readBytes')
                   ->atLeast()->times(6)
                   ->andReturn([\ord('a')], [0x20], [0x09], [0x20], [\ord('b')], false);

        $encoder = $this->createEncoder($charStream);
        $this->assertDoesNotMatchRegularExpression('~[ \t]~', $encoder->encodeString("a \t b"),
            '%s: encoded-words in headers cannot contain LWSP as per RFC 2047.'
            );
    }

    public function testSpaceIsRepresentedByUnderscore()
    {
        /* -- RFC 2047, 4.2.
        (2) The 8-bit hexadecimal value 20 (e.g., ISO-8859-1 SPACE) may be
       represented as "_" (underscore, ASCII 95.).  (This character may
       not pass through some internetwork mail gateways, but its use
       will greatly enhance readability of "Q" encoded data with mail
       readers that do not support this encoding.)  Note that the "_"
       always represents hexadecimal 20, even if the SPACE character
       occupies a different code position in the character set in use.
       */
        $charStream = $this->createCharacterStream();
        $charStream->shouldReceive('readBytes')
                   ->once()
                   ->andReturn([\ord('a')]);
        $charStream->shouldReceive('readBytes')
                   ->once()
                   ->andReturn([0x20]);
        $charStream->shouldReceive('readBytes')
                   ->once()
                   ->andReturn([\ord('b')]);
        $charStream->shouldReceive('readBytes')
                   ->zeroOrMoreTimes()
                   ->andReturn(false);

        $encoder = $this->createEncoder($charStream);
        $this->assertEquals('a_b', $encoder->encodeString('a b'),
            '%s: Spaces can be represented by more readable underscores as per RFC 2047.'
            );
    }

    public function testEqualsAndQuestionAndUnderscoreAreEncoded()
    {
        /* -- RFC 2047, 4.2.
        (3) 8-bit values which correspond to printable ASCII characters other
       than "=", "?", and "_" (underscore), MAY be represented as those
       characters.  (But see section 5 for restrictions.)  In
       particular, SPACE and TAB MUST NOT be represented as themselves
       within encoded words.
       */
        $charStream = $this->createCharacterStream();
        $charStream->shouldReceive('readBytes')
                   ->once()
                   ->andReturn([\ord('=')]);
        $charStream->shouldReceive('readBytes')
                   ->once()
                   ->andReturn([\ord('?')]);
        $charStream->shouldReceive('readBytes')
                   ->once()
                   ->andReturn([\ord('_')]);
        $charStream->shouldReceive('readBytes')
                   ->zeroOrMoreTimes()
                   ->andReturn(false);

        $encoder = $this->createEncoder($charStream);
        $this->assertEquals('=3D=3F=5F', $encoder->encodeString('=?_'),
            '%s: Chars =, ? and _ (underscore) may not appear as per RFC 2047.'
            );
    }

    public function testParensAndQuotesAreEncoded()
    {
        /* -- RFC 2047, 5 (2).
     A "Q"-encoded 'encoded-word' which appears in a 'comment' MUST NOT
     contain the characters "(", ")" or "
     */

        $charStream = $this->createCharacterStream();
        $charStream->shouldReceive('readBytes')
                   ->once()
                   ->andReturn([\ord('(')]);
        $charStream->shouldReceive('readBytes')
                   ->once()
                   ->andReturn([\ord('"')]);
        $charStream->shouldReceive('readBytes')
                   ->once()
                   ->andReturn([\ord(')')]);
        $charStream->shouldReceive('readBytes')
                   ->zeroOrMoreTimes()
                   ->andReturn(false);

        $encoder = $this->createEncoder($charStream);
        $this->assertEquals('=28=22=29', $encoder->encodeString('(")'),
            '%s: Chars (, " (DQUOTE) and ) may not appear as per RFC 2047.'
            );
    }

    public function testOnlyCharactersAllowedInPhrasesAreUsed()
    {
        /* -- RFC 2047, 5.
        (3) As a replacement for a 'word' entity within a 'phrase', for example,
        one that precedes an address in a From, To, or Cc header.  The ABNF
        definition for 'phrase' from RFC 822 thus becomes:

        phrase = 1*( encoded-word / word )

        In this case the set of characters that may be used in a "Q"-encoded
        'encoded-word' is restricted to: <upper and lower case ASCII
        letters, decimal digits, "!", "*", "+", "-", "/", "=", and "_"
        (underscore, ASCII 95.)>.  An 'encoded-word' that appears within a
        'phrase' MUST be separated from any adjacent 'word', 'text' or
        'special' by 'linear-white-space'.
        */

        $allowedBytes = array_merge(
            range(\ord('a'), \ord('z')), range(\ord('A'), \ord('Z')),
            range(\ord('0'), \ord('9')),
            [\ord('!'), \ord('*'), \ord('+'), \ord('-'), \ord('/')]
            );

        foreach (range(0x00, 0xFF) as $byte) {
            $char = pack('C', $byte);

            $charStream = $this->createCharacterStream();
            $charStream->shouldReceive('readBytes')
                   ->once()
                   ->andReturn([$byte]);
            $charStream->shouldReceive('readBytes')
                   ->zeroOrMoreTimes()
                   ->andReturn(false);

            $encoder = $this->createEncoder($charStream);
            $encodedChar = $encoder->encodeString($char);

            if (\in_array($byte, $allowedBytes)) {
                $this->assertEquals($char, $encodedChar,
                    '%s: Character '.$char.' should not be encoded.'
                    );
            } elseif (0x20 == $byte) {
                //Special case
                $this->assertEquals('_', $encodedChar,
                    '%s: Space character should be replaced.'
                    );
            } else {
                $this->assertEquals(sprintf('=%02X', $byte), $encodedChar,
                    '%s: Byte '.$byte.' should be encoded.'
                    );
            }
        }
    }

    public function testEqualsNeverAppearsAtEndOfLine()
    {
        /* -- RFC 2047, 5 (3).
        The 'encoded-text' in an 'encoded-word' must be self-contained;
        'encoded-text' MUST NOT be continued from one 'encoded-word' to
        another.  This implies that the 'encoded-text' portion of a "B"
        'encoded-word' will be a multiple of 4 characters long; for a "Q"
        'encoded-word', any "=" character that appears in the 'encoded-text'
        portion will be followed by two hexadecimal characters.
        */

        $input = str_repeat('a', 140);

        $charStream = $this->createCharacterStream();

        $output = '';
        $seq = 0;
        for (; $seq < 140; ++$seq) {
            $charStream->shouldReceive('readBytes')
                       ->once()
                       ->andReturn([\ord('a')]);

            if (75 == $seq) {
                $output .= "\r\n"; // =\r\n
            }
            $output .= 'a';
        }

        $charStream->shouldReceive('readBytes')
                   ->zeroOrMoreTimes()
                   ->andReturn(false);

        $encoder = $this->createEncoder($charStream);
        $this->assertEquals($output, $encoder->encodeString($input));
    }

    private function createEncoder($charStream)
    {
        return new Swift_Mime_HeaderEncoder_QpHeaderEncoder($charStream);
    }

    private function createCharacterStream($stub = false)
    {
        return $this->getMockery('Swift_CharacterStream')->shouldIgnoreMissing();
    }
}


================================================
FILE: tests/unit/Swift/Mime/Headers/DateHeaderTest.php
================================================
<?php

class Swift_Mime_Headers_DateHeaderTest extends \PHPUnit\Framework\TestCase
{
    /* --
    The following tests refer to RFC 2822, section 3.6.1 and 3.3.
    */

    public function testTypeIsDateHeader()
    {
        $header = $this->getHeader('Date');
        $this->assertEquals(Swift_Mime_Header::TYPE_DATE, $header->getFieldType());
    }

    public function testGetDateTime()
    {
        $dateTime = new DateTimeImmutable();
        $header = $this->getHeader('Date');
        $header->setDateTime($dateTime);
        $this->assertSame($dateTime, $header->getDateTime());
    }

    public function testDateTimeCanBeSetBySetter()
    {
        $dateTime = new DateTimeImmutable();
        $header = $this->getHeader('Date');
        $header->setDateTime($dateTime);
        $this->assertSame($dateTime, $header->getDateTime());
    }

    public function testDateTimeIsConvertedToImmutable()
    {
        $dateTime = new DateTime();
        $header = $this->getHeader('Date');
        $header->setDateTime($dateTime);
        $this->assertInstanceOf('DateTimeImmutable', $header->getDateTime());
        $this->assertEquals($dateTime->getTimestamp(), $header->getDateTime()->getTimestamp());
        $this->assertEquals($dateTime->getTimezone(), $header->getDateTime()->getTimezone());
    }

    public function testDateTimeIsImmutable()
    {
        $dateTime = new DateTime('2000-01-01 12:00:00 Europe/Berlin');
        $header = $this->getHeader('Date');
        $header->setDateTime($dateTime);

        $dateTime->setDate(2002, 2, 2);
        $this->assertEquals('Sat, 01 Jan 2000 12:00:00 +0100', $header->getDateTime()->format('r'));
        $this->assertEquals('Sat, 01 Jan 2000 12:00:00 +0100', $header->getFieldBody());
    }

    public function testDateTimeIsConvertedToRfc2822Date()
    {
        $dateTime = new DateTimeImmutable('2000-01-01 12:00:00 Europe/Berlin');
        $header = $this->getHeader('Date');
        $header->setDateTime($dateTime);
        $this->assertEquals('Sat, 01 Jan 2000 12:00:00 +0100', $header->getFieldBody());
    }

    public function testSetBodyModel()
    {
        $dateTime = new DateTimeImmutable();
        $header = $this->getHeader('Date');
        $header->setFieldBodyModel($dateTime);
        $this->assertEquals($dateTime->format('r'), $header->getFieldBody());
    }

    public function testGetBodyModel()
    {
        $dateTime = new DateTimeImmutable();
        $header = $this->getHeader('Date');
        $header->setDateTime($dateTime);
        $this->assertEquals($dateTime, $header->getFieldBodyModel());
    }

    public function testToString()
    {
        $dateTime = new DateTimeImmutable('2000-01-01 12:00:00 Europe/Berlin');
        $header = $this->getHeader('Date');
        $header->setDateTime($dateTime);
        $this->assertEquals("Date: Sat, 01 Jan 2000 12:00:00 +0100\r\n",
            $header->toString()
            );
    }

    private function getHeader($name)
    {
        return new Swift_Mime_Headers_DateHeader($name);
    }
}


================================================
FILE: tests/unit/Swift/Mime/Headers/IdentificationHeaderTest.php
================================================
<?php

use Egulias\EmailValidator\EmailValidator;

class Swift_Mime_Headers_IdentificationHeaderTest extends \PHPUnit\Framework\TestCase
{
    public function testTypeIsIdHeader()
    {
        $header = $this->getHeader('Message-ID');
        $this->assertEquals(Swift_Mime_Header::TYPE_ID, $header->getFieldType());
    }

    public function testValueMatchesMsgIdSpec()
    {
        /* -- RFC 2822, 3.6.4.
     message-id      =       "Message-ID:" msg-id CRLF

     in-reply-to     =       "In-Reply-To:" 1*msg-id CRLF

     references      =       "References:" 1*msg-id CRLF

     msg-id          =       [CFWS] "<" id-left "@" id-right ">" [CFWS]

     id-left         =       dot-atom-text / no-fold-quote / obs-id-left

     id-right        =       dot-atom-text / no-fold-literal / obs-id-right

     no-fold-quote   =       DQUOTE *(qtext / quoted-pair) DQUOTE

     no-fold-literal =       "[" *(dtext / quoted-pair) "]"
     */

        $header = $this->getHeader('Message-ID');
        $header->setId('id-left@id-right');
        $this->assertEquals('<id-left@id-right>', $header->getFieldBody());
    }

    public function testIdCanBeRetrievedVerbatim()
    {
        $header = $this->getHeader('Message-ID');
        $header->setId('id-left@id-right');
        $this->assertEquals('id-left@id-right', $header->getId());
    }

    public function testMultipleIdsCanBeSet()
    {
        $header = $this->getHeader('References');
        $header->setIds(['a@b', 'x@y']);
        $this->assertEquals(['a@b', 'x@y'], $header->getIds());
    }

    public function testSettingMultipleIdsProducesAListValue()
    {
        /* -- RFC 2822, 3.6.4.
     The "References:" and "In-Reply-To:" field each contain one or more
     unique message identifiers, optionally separated by CFWS.

     .. SNIP ..

     in-reply-to     =       "In-Reply-To:" 1*msg-id CRLF

     references      =       "References:" 1*msg-id CRLF
     */

        $header = $this->getHeader('References');
        $header->setIds(['a@b', 'x@y']);
        $this->assertEquals('<a@b> <x@y>', $header->getFieldBody());
    }

    public function testIdLeftCanBeQuoted()
    {
        /* -- RFC 2822, 3.6.4.
     id-left         =       dot-atom-text / no-fold-quote / obs-id-left
     */

        $header = $this->getHeader('References');
        $header->setId('"ab"@c');
        $this->assertEquals('"ab"@c', $header->getId());
        $this->assertEquals('<"ab"@c>', $header->getFieldBody());
    }

    public function testIdLeftCanContainAnglesAsQuotedPairs()
    {
        /* -- RFC 2822, 3.6.4.
     no-fold-quote   =       DQUOTE *(qtext / quoted-pair) DQUOTE
     */

        $header = $this->getHeader('References');
        $header->setId('"a\\<\\>b"@c');
        $this->assertEquals('"a\\<\\>b"@c', $header->getId());
        $this->assertEquals('<"a\\<\\>b"@c>', $header->getFieldBody());
    }

    public function testIdLeftCanBeDotAtom()
    {
        $header = $this->getHeader('References');
        $header->setId('a.b+&%$.c@d');
        $this->assertEquals('a.b+&%$.c@d', $header->getId());
        $this->assertEquals('<a.b+&%$.c@d>', $header->getFieldBody());
    }

    public function testInvalidIdLeftThrowsException()
    {
        $this->expectException(\Swift_RfcComplianceException::class);
        $this->expectExceptionMessage('Invalid ID given <a b c@d>');

        $header = $this->getHeader('References');
        $header->setId('a b c@d');
    }

    public function testIdRightCanBeDotAtom()
    {
        /* -- RFC 2822, 3.6.4.
     id-right        =       dot-atom-text / no-fold-literal / obs-id-right
     */

        $header = $this->getHeader('References');
        $header->setId('a@b.c+&%$.d');
        $this->assertEquals('a@b.c+&%$.d', $header->getId());
        $this->assertEquals('<a@b.c+&%$.d>', $header->getFieldBody());
    }

    public function testIdRightCanBeLiteral()
    {
        /* -- RFC 2822, 3.6.4.
     no-fold-literal =       "[" *(dtext / quoted-pair) "]"
     */

        $header = $this->getHeader('References');
        $header->setId('a@[1.2.3.4]');
        $this->assertEquals('a@[1.2.3.4]', $header->getId());
        $this->assertEquals('<a@[1.2.3.4]>', $header->getFieldBody());
    }

    public function testIdRigthIsIdnEncoded()
    {
        $header = $this->getHeader('References');
        $header->setId('a@ä');
        $this->assertEquals('a@ä', $header->getId());
        $this->assertEquals('<a@xn--4ca>', $header->getFieldBody());
    }

    public function testInvalidIdRightThrowsException()
    {
        $this->expectException(\Swift_RfcComplianceException::class);
        $this->expectExceptionMessage('Invalid ID given <a@b c d>');

        $header = $this->getHeader('References');
        $header->setId('a@b c d');
    }

    public function testMissingAtSignThrowsException()
    {
        $this->expectException(\Swift_RfcComplianceException::class);
        $this->expectExceptionMessage('Invalid ID given <abc>');

        /* -- RFC 2822, 3.6.4.
     msg-id          =       [CFWS] "<" id-left "@" id-right ">" [CFWS]
     */
        $header = $this->getHeader('References');
        $header->setId('abc');
    }

    public function testSetBodyModel()
    {
        $header = $this->getHeader('Message-ID');
        $header->setFieldBodyModel('a@b');
        $this->assertEquals(['a@b'], $header->getIds());
    }

    public function testGetBodyModel()
    {
        $header = $this->getHeader('Message-ID');
        $header->setId('a@b');
        $this->assertEquals(['a@b'], $header->getFieldBodyModel());
    }

    public function testStringValue()
    {
        $header = $this->getHeader('References');
        $header->setIds(['a@b', 'x@y']);
        $this->assertEquals('References: <a@b> <x@y>'."\r\n", $header->toString());
    }

    private function getHeader($name)
    {
        return new Swift_Mime_Headers_IdentificationHeader($name, new EmailValidator(), new Swift_AddressEncoder_IdnAddressEncoder());
    }
}


================================================
FILE: tests/unit/Swift/Mime/Headers/MailboxHeaderTest.php
================================================
<?php

use Egulias\EmailValidator\EmailValidator;

class Swift_Mime_Headers_MailboxHeaderTest extends \SwiftMailerTestCase
{
    /* -- RFC 2822, 3.6.2 for all tests.
     */

    private $charset = 'utf-8';

    public function testTypeIsMailboxHeader()
    {
        $header = $this->getHeader('To');
        $this->assertEquals(Swift_Mime_Header::TYPE_MAILBOX, $header->getFieldType());
    }

    public function testMailboxIsSetForAddress()
    {
        $header = $this->getHeader('From');
        $header->setAddresses('chris@swiftmailer.org');
        $this->assertEquals(['chris@swiftmailer.org'],
            $header->getNameAddressStrings()
            );
    }

    public function testMailboxIsRenderedForNameAddress()
    {
        $header = $this->getHeader('From');
        $header->setNameAddresses(['chris@swiftmailer.org' => 'Chris Corbyn']);
        $this->assertEquals(
            ['Chris Corbyn <chris@swiftmailer.org>'], $header->getNameAddressStrings()
            );
    }

    public function testAddressCanBeReturnedForAddress()
    {
        $header = $this->getHeader('From');
        $header->setAddresses('chris@swiftmailer.org');
        $this->assertEquals(['chris@swiftmailer.org'], $header->getAddresses());
    }

    public function testAddressCanBeReturnedForNameAddress()
    {
        $header = $this->getHeader('From');
        $header->setNameAddresses(['chris@swiftmailer.org' => 'Chris Corbyn']);
        $this->assertEquals(['chris@swiftmailer.org'], $header->getAddresses());
    }

    public function testQuotesInNameAreQuoted()
    {
        $header = $this->getHeader('From');
        $header->setNameAddresses([
            'chris@swiftmailer.org' => 'Chris Corbyn, "DHE"',
            ]);
        $this->assertEquals(
            ['"Chris Corbyn, \"DHE\"" <chris@swiftmailer.org>'],
            $header->getNameAddressStrings()
            );
    }

    public function testEscapeCharsInNameAreQuoted()
    {
        $header = $this->getHeader('From');
        $header->setNameAddresses([
            'chris@swiftmailer.org' => 'Chris Corbyn, \\escaped\\',
            ]);
        $this->assertEquals(
            ['"Chris Corbyn, \\\\escaped\\\\" <chris@swiftmailer.org>'],
            $header->getNameAddressStrings()
            );
    }

    public function testUtf8CharsInDomainAreIdnEncoded()
    {
        $header = $this->getHeader('From');
        $header->setNameAddresses([
            'chris@swïftmailer.org' => 'Chris Corbyn',
            ]);
        $this->assertEquals(
            ['Chris Corbyn <chris@xn--swftmailer-78a.org>'],
            $header->getNameAddressStrings()
            );
    }

    public function testUtf8CharsInLocalPartThrows()
    {
        $this->expectException(\Swift_AddressEncoderException::class);

        $header = $this->getHeader('From');
        $header->setNameAddresses([
            'chrïs@swiftmailer.org' => 'Chris Corbyn',
            ]);
        $header->getNameAddressStrings();
    }

    public function testUtf8CharsInEmail()
    {
        $header = $this->getHeader('From', null, new Swift_AddressEncoder_Utf8AddressEncoder());
        $header->setNameAddresses([
            'chrïs@swïftmailer.org' => 'Chris Corbyn',
            ]);
        $this->assertEquals(
            ['Chris Corbyn <chrïs@swïftmailer.org>'],
            $header->getNameAddressStrings()
            );
    }

    public function testGetMailboxesReturnsNameValuePairs()
    {
        $header = $this->getHeader('From');
        $header->setNameAddresses([
            'chris@swiftmailer.org' => 'Chris Corbyn, DHE',
            ]);
        $this->assertEquals(
            ['chris@swiftmailer.org' => 'Chris Corbyn, DHE'], $header->getNameAddresses()
            );
    }

    public function testMultipleAddressesCanBeSetAndFetched()
    {
        $header = $this->getHeader('From');
        $header->setAddresses([
            'chris@swiftmailer.org', 'mark@swiftmailer.org',
            ]);
        $this->assertEquals(
            ['chris@swiftmailer.org', 'mark@swiftmailer.org'],
            $header->getAddresses()
            );
    }

    public function testMultipleAddressesAsMailboxes()
    {
        $header = $this->getHeader('From');
        $header->setAddresses([
            'chris@swiftmailer.org', 'mark@swiftmailer.org',
            ]);
        $this->assertEquals(
            ['chris@swiftmailer.org' => null, 'mark@swiftmailer.org' => null],
            $header->getNameAddresses()
            );
    }

    public function testMultipleAddressesAsMailboxStrings()
    {
        $header = $this->getHeader('From');
        $header->setAddresses([
            'chris@swiftmailer.org', 'mark@swiftmailer.org',
            ]);
        $this->assertEquals(
            ['chris@swiftmailer.org', 'mark@swiftmailer.org'],
            $header->getNameAddressStrings()
            );
    }

    public function testMultipleNamedMailboxesReturnsMultipleAddresses()
    {
        $header = $this->getHeader('From');
        $header->setNameAddresses([
            'chris@swiftmailer.org' => 'Chris Corbyn',
            'mark@swiftmailer.org' => 'Mark Corbyn',
            ]);
        $this->assertEquals(
            ['chris@swiftmailer.org', 'mark@swiftmailer.org'],
            $header->getAddresses()
            );
    }

    public function testMultipleNamedMailboxesReturnsMultipleMailboxes()
    {
        $header = $this->getHeader('From');
        $header->setNameAddresses([
            'chris@swiftmailer.org' => 'Chris Corbyn',
            'mark@swiftmailer.org' => 'Mark Corbyn',
            ]);
        $this->assertEquals([
                'chris@swiftmailer.org' => 'Chris Corbyn',
                'mark@swiftmailer.org' => 'Mark Corbyn',
                ],
            $header->getNameAddresses()
            );
    }

    public function testMultipleMailboxesProducesMultipleMailboxStrings()
    {
        $header = $this->getHeader('From');
        $header->setNameAddresses([
            'chris@swiftmailer.org' => 'Chris Corbyn',
            'mark@swiftmailer.org' => 'Mark Corbyn',
            ]);
        $this->assertEquals([
                'Chris Corbyn <chris@swiftmailer.org>',
                'Mark Corbyn <mark@swiftmailer.org>',
                ],
            $header->getNameAddressStrings()
            );
    }

    public function testSetAddressesOverwritesAnyMailboxes()
    {
        $header = $this->getHeader('From');
        $header->setNameAddresses([
            'chris@swiftmailer.org' => 'Chris Corbyn',
            'mark@swiftmailer.org' => 'Mark Corbyn',
            ]);
        $this->assertEquals(
            ['chris@swiftmailer.org' => 'Chris Corbyn',
            'mark@swiftmailer.org' => 'Mark Corbyn', ],
            $header->getNameAddresses()
            );
        $this->assertEquals(
            ['chris@swiftmailer.org', 'mark@swiftmailer.org'],
            $header->getAddresses()
            );

        $header->setAddresses(['chris@swiftmailer.org', 'mark@swiftmailer.org']);

        $this->assertEquals(
            ['chris@swiftmailer.org' => null, 'mark@swiftmailer.org' => null],
            $header->getNameAddresses()
            );
        $this->assertEquals(
            ['chris@swiftmailer.org', 'mark@swiftmailer.org'],
            $header->getAddresses()
            );
    }

    public function testNameIsEncodedIfNonAscii()
    {
        $name = 'C'.pack('C', 0x8F).'rbyn';

        $encoder = $this->getEncoder('Q');
        $encoder->shouldReceive('encodeString')
                ->once()
                ->with($name, \Mockery::any(), \Mockery::any(), \Mockery::any())
                ->andReturn('C=8Frbyn');

        $header = $this->getHeader('From', $encoder);
        $header->setNameAddresses(['chris@swiftmailer.org' => 'Chris '.$name]);

        $addresses = $header->getNameAddressStrings();
        $this->assertEquals(
            'Chris =?'.$this->charset.'?Q?C=8Frbyn?= <chris@swiftmailer.org>',
            array_shift($addresses)
            );
    }

    public function testEncodingLineLengthCalculations()
    {
        /* -- RFC 2047, 2.
        An 'encoded-word' may not be more than 75 characters long, including
        'charset', 'encoding', 'encoded-text', and delimiters.
        */

        $name = 'C'.pack('C', 0x8F).'rbyn';

        $encoder = $this->getEncoder('Q');
        $encoder->shouldReceive('encodeString')
                ->once()
                ->with($name, \Mockery::any(), \Mockery::any(), \Mockery::any())
                ->andReturn('C=8Frbyn');

        $header = $this->getHeader('From', $encoder);
        $header->setNameAddresses(['chris@swiftmailer.org' => 'Chris '.$name]);

        $header->getNameAddressStrings();
    }

    public function testGetValueReturnsMailboxStringValue()
    {
        $header = $this->getHeader('From');
        $header->setNameAddresses([
            'chris@swiftmailer.org' => 'Chris Corbyn',
            ]);
        $this->assertEquals(
            'Chris Corbyn <chris@swiftmailer.org>', $header->getFieldBody()
            );
    }

    public function testGetValueReturnsMailboxStringValueForMultipleMailboxes()
    {
        $header = $this->getHeader('From');
        $header->setNameAddresses([
            'chris@swiftmailer.org' => 'Chris Corbyn',
            'mark@swiftmailer.org' => 'Mark Corbyn',
            ]);
        $this->assertEquals(
            'Chris Corbyn <chris@swiftmailer.org>, Mark Corbyn <mark@swiftmailer.org>',
            $header->getFieldBody()
            );
    }

    public function testRemoveAddressesWithSingleValue()
    {
        $header = $this->getHeader('From');
        $header->setNameAddresses([
            'chris@swiftmailer.org' => 'Chris Corbyn',
            'mark@swiftmailer.org' => 'Mark Corbyn',
            ]);
        $header->removeAddresses('chris@swiftmailer.org');
        $this->assertEquals(['mark@swiftmailer.org'],
            $header->getAddresses()
            );
    }

    public function testRemoveAddressesWithList()
    {
        $header = $this->getHeader('From');
        $header->setNameAddresses([
            'chris@swiftmailer.org' => 'Chris Corbyn',
            'mark@swiftmailer.org' => 'Mark Corbyn',
            ]);
        $header->removeAddresses(
            ['chris@swiftmailer.org', 'mark@swiftmailer.org']
            );
        $this->assertEquals([], $header->getAddresses());
    }

    public function testSetBodyModel()
    {
        $header = $this->getHeader('From');
        $header->setFieldBodyModel('chris@swiftmailer.org');
        $this->assertEquals(['chris@swiftmailer.org' => null], $header->getNameAddresses());
    }

    public function testGetBodyModel()
    {
        $header = $this->getHeader('From');
        $header->setAddresses(['chris@swiftmailer.org']);
        $this->assertEquals(['chris@swiftmailer.org' => null], $header->getFieldBodyModel());
    }

    public function testToString()
    {
        $header = $this->getHeader('From');
        $header->setNameAddresses([
            'chris@swiftmailer.org' => 'Chris Corbyn',
            'mark@swiftmailer.org' => 'Mark Corbyn',
            ]);
        $this->assertEquals(
            'From: Chris Corbyn <chris@swiftmailer.org>, '.
            'Mark Corbyn <mark@swiftmailer.org>'."\r\n",
            $header->toString()
            );
    }

    private function getHeader($name, $encoder = null, $addressEncoder = null)
    {
        $encoder = $encoder ?? $this->getEncoder('Q', true);
        $addressEncoder = $addressEncoder ?? new Swift_AddressEncoder_IdnAddressEncoder();
        $header = new Swift_Mime_Headers_MailboxHeader($name, $encoder, new EmailValidator(), $addressEncoder);
        $header->setCharset($this->charset);

        return $header;
    }

    private function getEncoder($type)
    {
        $encoder = $this->getMockery('Swift_Mime_HeaderEncoder')->shouldIgnoreMissing();
        $encoder->shouldReceive('getName')
                ->zeroOrMoreTimes()
                ->andReturn($type);

        return $encoder;
    }
}


================================================
FILE: tests/unit/Swift/Mime/Headers/ParameterizedHeaderTest.php
================================================
<?php

class Swift_Mime_Headers_ParameterizedHeaderTest extends \SwiftMailerTestCase
{
    private $charset = 'utf-8';
    private $lang = 'en-us';

    public function testTypeIsParameterizedHeader()
    {
        $header = $this->getHeader('Content-Type',
            $this->getHeaderEncoder('Q', true), $this->getParameterEncoder(true)
            );
        $this->assertEquals(Swift_Mime_Header::TYPE_PARAMETERIZED, $header->getFieldType());
    }

    public function testValueIsReturnedVerbatim()
    {
        $header = $this->getHeader('Content-Type',
            $this->getHeaderEncoder('Q', true), $this->getParameterEncoder(true)
            );
        $header->setValue('text/plain');
        $this->assertEquals('text/plain', $header->getValue());
    }

    public function testParametersAreAppended()
    {
        /* -- RFC 2045, 5.1
        parameter := attribute "=" value

     attribute := token
                                    ; Matching of attributes
                                    ; is ALWAYS case-insensitive.

     value := token / quoted-string

     token := 1*<any (US-ASCII) CHAR except SPACE, CTLs,
                 or tspecials>

     tspecials :=  "(" / ")" / "<" / ">" / "@" /
                   "," / ";" / ":" / "\" / <">
                   "/" / "[" / "]" / "?" / "="
                   ; Must be in quoted-string,
                   ; to use within parameter values
        */

        $header = $this->getHeader('Content-Type',
            $this->getHeaderEncoder('Q', true), $this->getParameterEncoder(true)
            );
        $header->setValue('text/plain');
        $header->setParameters(['charset' => 'utf-8']);
        $this->assertEquals('text/plain; charset=utf-8', $header->getFieldBody());
    }

    public function testSpaceInParamResultsInQuotedString()
    {
        $header = $this->getHeader('Content-Disposition',
            $this->getHeaderEncoder('Q', true), $this->getParameterEncoder(true)
            );
        $header->setValue('attachment');
        $header->setParameters(['filename' => 'my file.txt']);
        $this->assertEquals('attachment; filename="my file.txt"',
            $header->getFieldBody()
            );
    }

    public function testLongParamsAreBrokenIntoMultipleAttributeStrings()
    {
        /* -- RFC 2231, 3.
        The asterisk character ("*") followed
        by a decimal count is employed to indicate that multiple parameters
        are being used to encapsulate a single parameter value.  The count
        starts at 0 and increments by 1 for each subsequent section of the
        parameter value.  Decimal values are used and neither leading zeroes
        nor gaps in the sequence are allowed.

        The original parameter value is recovered by concatenating the
        various sections of the parameter, in order.  For example, the
        content-type field

                Content-Type: message/external-body; access-type=URL;
         URL*0="ftp://";
         URL*1="cs.utk.edu/pub/moore/bulk-mailer/bulk-mailer.tar"

        is semantically identical to

                Content-Type: message/external-body; access-type=URL;
                    URL="ftp://cs.utk.edu/pub/moore/bulk-mailer/bulk-mailer.tar"

        Note that quotes around parameter values are part of the value
        syntax; they are NOT part of the value itself.  Furthermore, it is
        explicitly permitted to have a mixture of quoted and unquoted
        continuation fields.
        */

        $value = str_repeat('a', 180);

        $encoder = $this->getParameterEncoder();
        $encoder->shouldReceive('encodeString')
                ->once()
                ->with($value, \Mockery::any(), 63, \Mockery::any())
                ->andReturn(str_repeat('a', 63)."\r\n".
                    str_repeat('a', 63)."\r\n".str_repeat('a', 54));

        $header = $this->getHeader('Content-Disposition',
            $this->getHeaderEncoder('Q', true), $encoder
            );
        $header->setValue('attachment');
        $header->setParameters(['filename' => $value]);
        $header->setMaxLineLength(78);
        $this->assertEquals(
            'attachment; '.
            'filename*0*=utf-8\'\''.str_repeat('a', 63).";\r\n ".
            'filename*1*='.str_repeat('a', 63).";\r\n ".
            'filename*2*='.str_repeat('a', 54),
            $header->getFieldBody()
            );
    }

    public function testEncodedParamDataIncludesCharsetAndLanguage()
    {
        /* -- RFC 2231, 4.
        Asterisks ("*") are reused to provide the indicator that language and
        character set information is present and encoding is being used. A
        single quote ("'") is used to delimit the character set and language
        information at the beginning of the parameter value. Percent signs
        ("%") are used as the encoding flag, which agrees with RFC 2047.

        Specifically, an asterisk at the end of a parameter name acts as an
        indicator that character set and language information may appear at
        the beginning of the parameter value. A single quote is used to
        separate the character set, language, and actual value information in
        the parameter value string, and an percent sign is used to flag
        octets encoded in hexadecimal.  For example:

                Content-Type: application/x-stuff;
         title*=us-ascii'en-us'This%20is%20%2A%2A%2Afun%2A%2A%2A

        Note that it is perfectly permissible to leave either the character
        set or language field blank.  Note also that the single quote
        delimiters MUST be present even when one of the field values is
        omitted.
        */

        $value = str_repeat('a', 20).pack('C', 0x8F).str_repeat('a', 10);

        $encoder = $this->getParameterEncoder();
        $encoder->shouldReceive('encodeString')
                ->once()
                ->with($value, 12, 62, \Mockery::any())
                ->andReturn(str_repeat('a', 20).'%8F'.str_repeat('a', 10));

        $header = $this->getHeader('Content-Disposition',
            $this->getHeaderEncoder('Q', true), $encoder
            );
        $header->setValue('attachment');
        $header->setParameters(['filename' => $value]);
        $header->setMaxLineLength(78);
        $header->setLanguage($this->lang);
        $this->assertEquals(
            'attachment; filename*='.$this->charset."'".$this->lang."'".
            str_repeat('a', 20).'%8F'.str_repeat('a', 10),
            $header->getFieldBody()
            );
    }

    public function testMultipleEncodedParamLinesAreFormattedCorrectly()
    {
        /* -- RFC 2231, 4.1.
        Character set and language information may be combined with the
        parameter continuation mechanism. For example:

        Content-Type: application/x-stuff
     title*0*=us-ascii'en'This%20is%20even%20more%20
     title*1*=%2A%2A%2Afun%2A%2A%2A%20
     title*2="isn't it!"

        Note that:

     (1)   Language and character set information only appear at
           the beginning of a given parameter value.

     (2)   Continuations do not provide a facility for using more
           than one character set or language in the same
           parameter value.

     (3)   A value presented using multiple continuations may
           contain a mixture of encoded and unencoded segments.

     (4)   The first segment of a continuation MUST be encoded if
           language and character set information are given.

     (5)   If the first segment of a continued parameter value is
           encoded the language and character set field delimiters
           MUST be present even when the fields are left blank.
        */

        $value = str_repeat('a', 20).pack('C', 0x8F).str_repeat('a', 60);

        $encoder = $this->getParameterEncoder();
        $encoder->shouldReceive('encodeString')
                ->once()
                ->with($value, 12, 62, \Mockery::any())
                ->andReturn(str_repeat('a', 20).'%8F'.str_repeat('a', 28)."\r\n".
                    str_repeat('a', 32));

        $header = $this->getHeader('Content-Disposition',
            $this->getHeaderEncoder('Q', true), $encoder
            );
        $header->setValue('attachment');
        $header->setParameters(['filename' => $value]);
        $header->setMaxLineLength(78);
        $header->setLanguage($this->lang);
        $this->assertEquals(
            'attachment; filename*0*='.$this->charset."'".$this->lang."'".
            str_repeat('a', 20).'%8F'.str_repeat('a', 28).";\r\n ".
            'filename*1*='.str_repeat('a', 32),
            $header->getFieldBody()
            );
    }

    public function testToString()
    {
        $header = $this->getHeader('Content-Type',
            $this->getHeaderEncoder('Q', true), $this->getParameterEncoder(true)
            );
        $header->setValue('text/html');
        $header->setParameters(['charset' => 'utf-8']);
        $this->assertEquals('Content-Type: text/html; charset=utf-8'."\r\n",
            $header->toString()
            );
    }

    public function testValueCanBeEncodedIfNonAscii()
    {
        $value = 'fo'.pack('C', 0x8F).'bar';

        $encoder = $this->getHeaderEncoder('Q');
        $encoder->shouldReceive('encodeString')
                ->once()
                ->with($value, \Mockery::any(), \Mockery::any(), \Mockery::any())
                ->andReturn('fo=8Fbar');

        $header = $this->getHeader('X-Foo', $encoder, $this->getParameterEncoder(true));
        $header->setValue($value);
        $header->setParameters(['lookslike' => 'foobar']);
        $this->assertEquals('X-Foo: =?utf-8?Q?fo=8Fbar?=; lookslike=foobar'."\r\n",
            $header->toString()
            );
    }

    public function testValueAndParamCanBeEncodedIfNonAscii()
    {
        $value = 'fo'.pack('C', 0x8F).'bar';

        $encoder = $this->getHeaderEncoder('Q');
        $encoder->shouldReceive('encodeString')
                ->once()
                ->with($value, \Mockery::any(), \Mockery::any(), \Mockery::any())
                ->andReturn('fo=8Fbar');

        $paramEncoder = $this->getParameterEncoder();
        $paramEncoder->shouldReceive('encodeString')
                     ->once()
                     ->with($value, \Mockery::any(), \Mockery::any(), \Mockery::any())
                     ->andReturn('fo%8Fbar');

        $header = $this->getHeader('X-Foo', $encoder, $paramEncoder);
        $header->setValue($value);
        $header->setParameters(['says' => $value]);
        $this->assertEquals("X-Foo: =?utf-8?Q?fo=8Fbar?=; says*=utf-8''fo%8Fbar\r\n",
            $header->toString()
            );
    }

    public function testParamsAreEncodedWithEncodedWordsIfNoParamEncoderSet()
    {
        $value = 'fo'.pack('C', 0x8F).'bar';

        $encoder = $this->getHeaderEncoder('Q');
        $encoder->shouldReceive('encodeString')
                ->once()
                ->with($value, \Mockery::any(), \Mockery::any(), \Mockery::any())
                ->andReturn('fo=8Fbar');

        $header = $this->getHeader('X-Foo', $encoder, null);
        $header->setValue('bar');
        $header->setParameters(['says' => $value]);
        $this->assertEquals("X-Foo: bar; says=\"=?utf-8?Q?fo=8Fbar?=\"\r\n",
            $header->toString()
            );
    }

    public function testLanguageInformationAppearsInEncodedWords()
    {
        /* -- RFC 2231, 5.
        5.  Language specification in Encoded Words

        RFC 2047 provides support for non-US-ASCII character sets in RFC 822
        message header comments, phrases, and any unstructured text field.
        This is done by defining an encoded word construct which can appear
        in any of these places.  Given that these are fields intended for
        display, it is sometimes necessary to associate language information
        with encoded words as well as just the character set.  This
        specification extends the definition of an encoded word to allow the
        inclusion of such information.  This is simply done by suffixing the
        character set specification with an asterisk followed by the language
        tag.  For example:

                    From: =?US-ASCII*EN?Q?Keith_Moore?= <moore@cs.utk.edu>
        */

        $value = 'fo'.pack('C', 0x8F).'bar';

        $encoder = $this->getHeaderEncoder('Q');
        $encoder->shouldReceive('encodeString')
                ->once()
                ->with($value, \Mockery::any(), \Mockery::any(), \Mockery::any())
                ->andReturn('fo=8Fbar');

        $paramEncoder = $this->getParameterEncoder();
        $paramEncoder->shouldReceive('encodeString')
                     ->once()
                     ->with($value, \Mockery::any(), \Mockery::any(), \Mockery::any())
                     ->andReturn('fo%8Fbar');

        $header = $this->getHeader('X-Foo', $encoder, $paramEncoder);
        $header->setLanguage('en');
        $header->setValue($value);
        $header->setParameters(['says' => $value]);
        $this->assertEquals("X-Foo: =?utf-8*en?Q?fo=8Fbar?=; says*=utf-8'en'fo%8Fbar\r\n",
            $header->toString()
            );
    }

    public function testSetBodyModel()
    {
        $header = $this->getHeader('Content-Type',
            $this->getHeaderEncoder('Q', true), $this->getParameterEncoder(true)
            );
        $header->setFieldBodyModel('text/html');
        $this->assertEquals('text/html', $header->getValue());
    }

    public function testGetBodyModel()
    {
        $header = $this->getHeader('Content-Type',
            $this->getHeaderEncoder('Q', true), $this->getParameterEncoder(true)
            );
        $header->setValue('text/plain');
        $this->assertEquals('text/plain', $header->getFieldBodyModel());
    }

    public function testSetParameter()
    {
        $header = $this->getHeader('Content-Type',
            $this->getHeaderEncoder('Q', true), $this->getParameterEncoder(true)
            );
        $header->setParameters(['charset' => 'utf-8', 'delsp' => 'yes']);
        $header->setParameter('delsp', 'no');
        $this->assertEquals(['charset' => 'utf-8', 'delsp' => 'no'],
            $header->getParameters()
            );
    }

    public function testGetParameter()
    {
        $header = $this->getHeader('Content-Type',
            $this->getHeaderEncoder('Q', true), $this->getParameterEncoder(true)
            );
        $header->setParameters(['charset' => 'utf-8', 'delsp' => 'yes']);
        $this->assertEquals('utf-8', $header->getParameter('charset'));
    }

    private function getHeader($name, $encoder, $paramEncoder)
    {
        $header = new Swift_Mime_Headers_ParameterizedHeader($name, $encoder, $paramEncoder);
        $header->setCharset($this->charset);

        return $header;
    }

    private function getHeaderEncoder($type, $stub = false)
    {
        $encoder = $this->getMockery('Swift_Mime_HeaderEncoder')->shouldIgnoreMissing();
        $encoder->shouldReceive('getName')
                ->zeroOrMoreTimes()
                ->andReturn($type);

        return $encoder;
    }

    private function getParameterEncoder($stub = false)
    {
        return $this->getMockery('Swift_Encoder')->shouldIgnoreMissing();
    }
}


================================================
FILE: tests/unit/Swift/Mime/Headers/PathHeaderTest.php
================================================
<?php

use Egulias\EmailValidator\EmailValidator;

class Swift_Mime_Headers_PathHeaderTest extends \PHPUnit\Framework\TestCase
{
    public function testTypeIsPathHeader()
    {
        $header = $this->getHeader('Return-Path');
        $this->assertEquals(Swift_Mime_Header::TYPE_PATH, $header->getFieldType());
    }

    public function testSingleAddressCanBeSetAndFetched()
    {
        $header = $this->getHeader('Return-Path');
        $header->setAddress('chris@swiftmailer.org');
        $this->assertEquals('chris@swiftmailer.org', $header->getAddress());
    }

    public function testAddressMustComplyWithRfc2822()
    {
        $this->expectException(\Exception::class);

        $header = $this->getHeader('Return-Path');
        $header->setAddress('chr is@swiftmailer.org');
    }

    public function testValueIsAngleAddrWithValidAddress()
    {
        /* -- RFC 2822, 3.6.7.

            return          =       "Return-Path:" path CRLF

            path            =       ([CFWS] "<" ([CFWS] / addr-spec) ">" [CFWS]) /
                                                            obs-path
     */

        $header = $this->getHeader('Return-Path');
        $header->setAddress('chris@swiftmailer.org');
        $this->assertEquals('<chris@swiftmailer.org>', $header->getFieldBody());
    }

    public function testAddressIsIdnEncoded()
    {
        $header = $this->getHeader('Return-Path');
        $header->setAddress('chris@swïftmailer.org');
        $this->assertEquals('<chris@xn--swftmailer-78a.org>', $header->getFieldBody());
    }

    public function testAddressMustBeEncodable()
    {
        $this->expectException(\Swift_AddressEncoderException::class);

        $header = $this->getHeader('Return-Path');
        $header->setAddress('chrïs@swiftmailer.org');
        $header->getFieldBody();
    }

    public function testValueIsEmptyAngleBracketsIfEmptyAddressSet()
    {
        $header = $this->getHeader('Return-Path');
        $header->setAddress('');
        $this->assertEquals('<>', $header->getFieldBody());
    }

    public function testSetBodyModel()
    {
        $header = $this->getHeader('Return-Path');
        $header->setFieldBodyModel('foo@bar.tld');
        $this->assertEquals('foo@bar.tld', $header->getAddress());
    }

    public function testGetBodyModel()
    {
        $header = $this->getHeader('Return-Path');
        $header->setAddress('foo@bar.tld');
        $this->assertEquals('foo@bar.tld', $header->getFieldBodyModel());
    }

    public function testToString()
    {
        $header = $this->getHeader('Return-Path');
        $header->setAddress('chris@swiftmailer.org');
        $this->assertEquals('Return-Path: <chris@swiftmailer.org>'."\r\n",
            $header->toString()
            );
    }

    private function getHeader($name)
    {
        return new Swift_Mime_Headers_PathHeader($name, new EmailValidator(), new Swift_AddressEncoder_IdnAddressEncoder());
    }
}


================================================
FILE: tests/unit/Swift/Mime/Headers/UnstructuredHeaderTest.php
================================================
<?php

class Swift_Mime_Headers_UnstructuredHeaderTest extends \SwiftMailerTestCase
{
    private $charset = 'utf-8';

    public function testTypeIsTextHeader()
    {
        $header = $this->getHeader('Subject', $this->getEncoder('Q', true));
        $this->assertEquals(Swift_Mime_Header::TYPE_TEXT, $header->getFieldType());
    }

    public function testGetNameReturnsNameVerbatim()
    {
        $header = $this->getHeader('Subject', $this->getEncoder('Q', true));
        $this->assertEquals('Subject', $header->getFieldName());
    }

    public function testGetValueReturnsValueVerbatim()
    {
        $header = $this->getHeader('Subject', $this->getEncoder('Q', true));
        $header->setValue('Test');
        $this->assertEquals('Test', $header->getValue());
    }

    public function testBasicStructureIsKeyValuePair()
    {
        /* -- RFC 2822, 2.2
        Header fields are lines composed of a field name, followed by a colon
        (":"), followed by a field body, and terminated by CRLF.
        */
        $header = $this->getHeader('Subject', $this->getEncoder('Q', true));
        $header->setValue('Test');
        $this->assertEquals('Subject: Test'."\r\n", $header->toString());
    }

    public function testLongHeadersAreFoldedAtWordBoundary()
    {
        /* -- RFC 2822, 2.2.3
        Each header field is logically a single line of characters comprising
        the field name, the colon, and the field body.  For convenience
        however, and to deal with the 998/78 character limitations per line,
        the field body portion of a header field can be split into a multiple
        line representation; this is called "folding".  The general rule is
        that wherever this standard allows for folding white space (not
        simply WSP characters), a CRLF may be inserted before any WSP.
        */

        $value = 'The quick brown fox jumped over the fence, he was a very very '.
            'scary brown fox with a bushy tail';
        $header = $this->getHeader('X-Custom-Header',
            $this->getEncoder('Q', true)
            );
        $header->setValue($value);
        $header->setMaxLineLength(78); //A safe [RFC 2822, 2.2.3] default
        /*
        X-Custom-Header: The quick brown fox jumped over the fence, he was a very very
     scary brown fox with a bushy tail
        */
        $this->assertEquals(
            'X-Custom-Header: The quick brown fox jumped over the fence, he was a'.
            ' very very'."\r\n".//Folding
            ' scary brown fox with a bushy tail'."\r\n",
            $header->toString(), '%s: The header should have been folded at 78th char'
            );
    }

    public function testPrintableAsciiOnlyAppearsInHeaders()
    {
        /* -- RFC 2822, 2.2.
        A field name MUST be composed of printable US-ASCII characters (i.e.,
        characters that have values between 33 and 126, inclusive), except
        colon.  A field body may be composed of any US-ASCII characters,
        except for CR and LF.
        */

        $nonAsciiChar = pack('C', 0x8F);
        $header = $this->getHeader('X-Test', $this->getEncoder('Q', true));
        $header->setValue($nonAsciiChar);
        $this->assertMatchesRegularExpression(
            '~^[^:\x00-\x20\x80-\xFF]+: [^\x80-\xFF\r\n]+\r\n$~s',
            $header->toString()
            );
    }

    public function testEncodedWordsFollowGeneralStructure()
    {
        /* -- RFC 2047, 1.
        Generally, an "encoded-word" is a sequence of printable ASCII
        characters that begins with "=?", ends with "?=", and has two "?"s in
        between.
        */

        $nonAsciiChar = pack('C', 0x8F);
        $header = $this->getHeader('X-Test', $this->getEncoder('Q', true));
        $header->setValue($nonAsciiChar);
        $this->assertMatchesRegularExpression(
            '~^X-Test: \=?.*?\?.*?\?.*?\?=\r\n$~s',
            $header->toString()
            );
    }

    public function testEncodedWordIncludesCharsetAndEncodingMethodAndText()
    {
        /* -- RFC 2047, 2.
        An 'encoded-word' is defined by the following ABNF grammar.  The
        notation of RFC 822 is used, with the exception that white space
        characters MUST NOT appear between components of an 'encoded-word'.

        encoded-word = "=?" charset "?" encoding "?" encoded-text "?="
        */

        $nonAsciiChar = pack('C', 0x8F);

        $encoder = $this->getEncoder('Q');
        $encoder->shouldReceive('encodeString')
                ->once()
                ->with($nonAsciiChar, \Mockery::any(), \Mockery::any(), \Mockery::any())
                ->andReturn('=8F');

        $header = $this->getHeader('X-Test', $encoder);
        $header->setValue($nonAsciiChar);
        $this->assertEquals(
            'X-Test: =?'.$this->charset.'?Q?=8F?='."\r\n",
            $header->toString()
            );
    }

    public function testEncodedWordsAreUsedToEncodedNonPrintableAscii()
    {
        //SPACE and TAB permitted
        $nonPrintableBytes = array_merge(
            range(0x00, 0x08), range(0x10, 0x19), [0x7F]
            );

        foreach ($nonPrintableBytes as $byte) {
            $char = pack('C', $byte);
            $encodedChar = sprintf('=%02X', $byte);

            $encoder = $this->getEncoder('Q');
            $encoder->shouldReceive('encodeString')
                ->once()
                ->with($char, \Mockery::any(), \Mockery::any(), \Mockery::any())
                ->andReturn($encodedChar);

            $header = $this->getHeader('X-A', $encoder);
            $header->setValue($char);

            $this->assertEquals(
                'X-A: =?'.$this->charset.'?Q?'.$encodedChar.'?='."\r\n",
                $header->toString(), '%s: Non-printable ascii should be encoded'
                );
        }
    }

    public function testEncodedWordsAreUsedToEncode8BitOctets()
    {
        foreach (range(0x80, 0xFF) as $byte) {
            $char = pack('C', $byte);
            $encodedChar = sprintf('=%02X', $byte);

            $encoder = $this->getEncoder('Q');
            $encoder->shouldReceive('encodeString')
                ->once()
                ->with($char, \Mockery::any(), \Mockery::any(), \Mockery::any())
                ->andReturn($encodedChar);

            $header = $this->getHeader('X-A', $encoder);
            $header->setValue($char);

            $this->assertEquals(
                'X-A: =?'.$this->charset.'?Q?'.$encodedChar.'?='."\r\n",
                $header->toString(), '%s: 8-bit octets should be encoded'
                );
        }
    }

    public function testEncodedWordsAreNoMoreThan75CharsPerLine()
    {
        /* -- RFC 2047, 2.
        An 'encoded-word' may not be more than 75 characters long, including
        'charset', 'encoding', 'encoded-text', and delimiters.

        ... SNIP ...

        While there is no limit to the length of a multiple-line header
        field, each line of a header field that contains one or more
        'encoded-word's is limited to 76 characters.
        */

        $nonAsciiChar = pack('C', 0x8F);

        $encoder = $this->getEncoder('Q');
        $encoder->shouldReceive('encodeString')
                ->once()
                ->with($nonAsciiChar, \Mockery::any(), \Mockery::any(), \Mockery::any())
                ->andReturn('=8F');
        //Note that multi-line headers begin with LWSP which makes 75 + 1 = 76
        //Note also that =?utf-8?q??= is 12 chars which makes 75 - 12 = 63

        //* X-Test: is 8 chars
        $header = $this->getHeader('X-Test', $encoder);
        $header->setValue($nonAsciiChar);

        $this->assertEquals(
            'X-Test: =?'.$this->charset.'?Q?=8F?='."\r\n",
            $header->toString()
            );
    }

    public function testFWSPIsUsedWhenEncoderReturnsMultipleLines()
    {
        /* --RFC 2047, 2.
        If it is desirable to encode more text than will fit in an 'encoded-word' of
        75 characters, multiple 'encoded-word's (separated by CRLF SPACE) may
        be used.
        */

        //Note the Mock does NOT return 8F encoded, the 8F merely triggers
        // encoding for the sake of testing
        $nonAsciiChar = pack('C', 0x8F);

        $encoder = $this->getEncoder('Q');
        $encoder->shouldReceive('encodeString')
                ->once()
                ->with($nonAsciiChar, 8, 63, \Mockery::any())
                ->andReturn('line_one_here'."\r\n".'line_two_here');

        //Note that multi-line headers begin with LWSP which makes 75 + 1 = 76
        //Note also that =?utf-8?q??= is 12 chars which makes 75 - 12 = 63

        //* X-Test: is 8 chars
        $header = $this->getHeader('X-Test', $encoder);
        $header->setValue($nonAsciiChar);

        $this->assertEquals(
            'X-Test: =?'.$this->charset.'?Q?line_one_here?='."\r\n".
            ' =?'.$this->charset.'?Q?line_two_here?='."\r\n",
            $header->toString()
            );
    }

    public function testAdjacentWordsAreEncodedTogether()
    {
        /* -- RFC 2047, 5 (1)
     Ordinary ASCII text and 'encoded-word's may appear together in the
     same header field.  However, an 'encoded-word' that appears in a
     header field defined as '*text' MUST be separated from any adjacent
     'encoded-word' or 'text' by 'linear-white-space'.

     -- RFC 2047, 2.
     IMPORTANT: 'encoded-word's are designed to be recognized as 'atom's
     by an RFC 822 parser.  As a consequence, unencoded white space
     characters (such as SPACE and HTAB) are FORBIDDEN within an
     'encoded-word'.
     */

        //It would be valid to encode all words needed, however it's probably
        // easiest to encode the longest amount required at a time

        $word = 'w'.pack('C', 0x8F).'rd';
        $text = 'start '.$word.' '.$word.' then end '.$word;
        // 'start', ' word word', ' and end', ' word'

        $encoder = $this->getEncoder('Q');
        $encoder->shouldReceive('encodeString')
                ->once()
                ->with($word.' '.$word, \Mockery::any(), \Mockery::any(), \Mockery::any())
                ->andReturn('w=8Frd_w=8Frd');
        $encoder->shouldReceive('encodeString')
                ->once()
                ->with($word, \Mockery::any(), \Mockery::any(), \Mockery::any())
                ->andReturn('w=8Frd');

        $header = $this->getHeader('X-Test', $encoder);
        $header->setValue($text);

        $headerString = $header->toString();

        $this->assertEquals('X-Test: start =?'.$this->charset.'?Q?'.
            'w=8Frd_w=8Frd?= then end =?'.$this->charset.'?Q?'.
            'w=8Frd?='."\r\n", $headerString,
            '%s: Adjacent encoded words should appear grouped with WSP encoded'
            );
    }

    public function testLanguageInformationAppearsInEncodedWords()
    {
        /* -- RFC 2231, 5.
        5.  Language specification in Encoded Words

        RFC 2047 provides support for non-US-ASCII character sets in RFC 822
        message header comments, phrases, and any unstructured text field.
        This is done by defining an encoded word construct which can appear
        in any of these places.  Given that these are fields intended for
        display, it is sometimes necessary to associate language information
        with encoded words as well as just the character set.  This
        specification extends the definition of an encoded word to allow the
        inclusion of such information.  This is simply done by suffixing the
        character set specification with an asterisk followed by the language
        tag.  For example:

                    From: =?US-ASCII*EN?Q?Keith_Moore?= <moore@cs.utk.edu>
        */

        $value = 'fo'.pack('C', 0x8F).'bar';

        $encoder = $this->getEncoder('Q');
        $encoder->shouldReceive('encodeString')
                ->once()
                ->with($value, \Mockery::any(), \Mockery::any(), \Mockery::any())
                ->andReturn('fo=8Fbar');

        $header = $this->getHeader('Subject', $encoder);
        $header->setLanguage('en');
        $header->setValue($value);
        $this->assertEquals("Subject: =?utf-8*en?Q?fo=8Fbar?=\r\n",
            $header->toString()
            );
    }

    public function testSetBodyModel()
    {
        $header = $this->getHeader('Subject', $this->getEncoder('Q', true));
        $header->setFieldBodyModel('test');
        $this->assertEquals('test', $header->getValue());
    }

    public function testGetBodyModel()
    {
        $header = $this->getHeader('Subject', $this->getEncoder('Q', true));
        $header->setValue('test');
        $this->assertEquals('test', $header->getFieldBodyModel());
    }

    private function getHeader($name, $encoder)
    {
        $header = new Swift_Mime_Headers_UnstructuredHeader($name, $encoder);
        $header->setCharset($this->charset);

        return $header;
    }

    private function getEncoder($type, $stub = false)
    {
        $encoder = $this->getMockery('Swift_Mime_HeaderEncoder')->shouldIgnoreMissing();
        $encoder->shouldReceive('getName')
                ->zeroOrMoreTimes()
                ->andReturn($type);

        return $encoder;
    }
}


================================================
FILE: tests/unit/Swift/Mime/IdGeneratorTest.php
================================================
<?php

use Egulias\EmailValidator\EmailValidator;
use Egulias\EmailValidator\Validation\RFCValidation;

class Swift_Mime_IdGeneratorTest extends \PHPUnit\Framework\TestCase
{
    protected $emailValidator;
    protected $originalServerName;

    public function testIdGeneratorSetRightId()
    {
        $idGenerator = new Swift_Mime_IdGenerator('example.net');
        $this->assertEquals('example.net', $idGenerator->getIdRight());

        $idGenerator->setIdRight('example.com');
        $this->assertEquals('example.com', $idGenerator->getIdRight());
    }

    public function testIdGenerateId()
    {
        $idGenerator = new Swift_Mime_IdGenerator('example.net');
        $emailValidator = new EmailValidator();

        $id = $idGenerator->generateId();
        $this->assertTrue($emailValidator->isValid($id, new RFCValidation()));
        $this->assertMatchesRegularExpression('/^.{32}@example.net$/', $id);

        $anotherId = $idGenerator->generateId();
        $this->assertNotEquals($id, $anotherId);
    }
}


================================================
FILE: tests/unit/Swift/Mime/MimePartTest.php
================================================
<?php

class Swift_Mime_MimePartTest extends Swift_Mime_AbstractMimeEntityTest
{
    public function testNestingLevelIsSubpart()
    {
        $part = $this->createMimePart($this->createHeaderSet(),
            $this->createEncoder(), $this->createCache()
            );
        $this->assertEquals(
            Swift_Mime_SimpleMimeEntity::LEVEL_ALTERNATIVE, $part->getNestingLevel()
            );
    }

    public function testCharsetIsReturnedFromHeader()
    {
        /* -- RFC 2046, 4.1.2.
        A critical parameter that may be specified in the Content-Type field
        for "text/plain" data is the character set.  This is specified with a
        "charset" parameter, as in:

     Content-type: text/plain; charset=iso-8859-1

        Unlike some other parameter values, the values of the charset
        parameter are NOT case sensitive.  The default character set, which
        must be assumed in the absence of a charset parameter, is US-ASCII.
        */

        $cType = $this->createHeader('Content-Type', 'text/plain',
            ['charset' => 'iso-8859-1']
            );
        $part = $this->createMimePart($this->createHeaderSet([
            'Content-Type' => $cType, ]),
            $this->createEncoder(), $this->createCache()
            );
        $this->assertEquals('iso-8859-1', $part->getCharset());
    }

    public function testCharsetIsSetInHeader()
    {
        $cType = $this->createHeader('Content-Type', 'text/plain',
            ['charset' => 'iso-8859-1'], false
            );
        $cType->shouldReceive('setParameter')->once()->with('charset', 'utf-8');

        $part = $this->createMimePart($this->createHeaderSet([
            'Content-Type' => $cType, ]),
            $this->createEncoder(), $this->createCache()
            );
        $part->setCharset('utf-8');
    }

    public function testCharsetIsSetInHeaderIfPassedToSetBody()
    {
        $cType = $this->createHeader('Content-Type', 'text/plain',
            ['charset' => 'iso-8859-1'], false
            );
        $cType->shouldReceive('setParameter')->once()->with('charset', 'utf-8');

        $part = $this->createMimePart($this->createHeaderSet([
            'Content-Type' => $cType, ]),
            $this->createEncoder(), $this->createCache()
            );
        $part->setBody('', 'text/plian', 'utf-8');
    }

    public function testSettingCharsetNotifiesEncoder()
    {
        $encoder = $this->createEncoder('quoted-printable', false);
        $encoder->expects($this->once())
                ->method('charsetChanged')
                ->with('utf-8');

        $part = $this->createMimePart($this->createHeaderSet(),
            $encoder, $this->createCache()
            );
        $part->setCharset('utf-8');
    }

    public function testSettingCharsetNotifiesHeaders()
    {
        $headers = $this->createHeaderSet([], false);
        $headers->shouldReceive('charsetChanged')
                ->zeroOrMoreTimes()
                ->with('utf-8');

        $part = $this->createMimePart($headers, $this->createEncoder(),
            $this->createCache()
            );
        $part->setCharset('utf-8');
    }

    public function testSettingCharsetNotifiesChildren()
    {
        $child = $this->createChild(0, '', false);
        $child->shouldReceive('charsetChanged')
              ->once()
              ->with('windows-874');

        $part = $this->createMimePart($this->createHeaderSet(),
            $this->createEncoder(), $this->createCache()
            );
        $part->setChildren([$child]);
        $part->setCharset('windows-874');
    }

    public function testCharsetChangeUpdatesCharset()
    {
        $cType = $this->createHeader('Content-Type', 'text/plain',
            ['charset' => 'iso-8859-1'], false
            );
        $cType->shouldReceive('setParameter')->once()->with('charset', 'utf-8');

        $part = $this->createMimePart($this->createHeaderSet([
            'Content-Type' => $cType, ]),
            $this->createEncoder(), $this->createCache()
            );
        $part->charsetChanged('utf-8');
    }

    public function testSettingCharsetClearsCache()
    {
        $headers = $this->createHeaderSet([], false);
        $headers->shouldReceive('toString')
                ->zeroOrMoreTimes()
                ->andReturn("Content-Type: text/plain; charset=utf-8\r\n");

        $cache = $this->createCache(false);

        $entity = $this->createEntity($headers, $this->createEncoder(),
            $cache
            );

        $entity->setBody("blah\r\nblah!");
        $entity->toString();

        // Initialize the expectation here because we only care about what happens in setCharset()
        $cache->shouldReceive('clearKey')
                ->once()
                ->with(\Mockery::any(), 'body');

        $entity->setCharset('iso-2022');
    }

    public function testFormatIsReturnedFromHeader()
    {
        /* -- RFC 3676.
     */

        $cType = $this->createHeader('Content-Type', 'text/plain',
            ['format' => 'flowed']
            );
        $part = $this->createMimePart($this->createHeaderSet([
            'Content-Type' => $cType, ]),
            $this->createEncoder(), $this->createCache()
            );
        $this->assertEquals('flowed', $part->getFormat());
    }

    public function testFormatIsSetInHeader()
    {
        $cType = $this->createHeader('Content-Type', 'text/plain', [], false);
        $cType->shouldReceive('setParameter')->once()->with('format', 'fixed');

        $part = $this->createMimePart($this->createHeaderSet([
            'Content-Type' => $cType, ]),
            $this->createEncoder(), $this->createCache()
            );
        $part->setFormat('fixed');
    }

    public function testDelSpIsReturnedFromHeader()
    {
        /* -- RFC 3676.
     */

        $cType = $this->createHeader('Content-Type', 'text/plain',
            ['delsp' => 'no']
            );
        $part = $this->createMimePart($this->createHeaderSet([
            'Content-Type' => $cType, ]),
            $this->createEncoder(), $this->createCache()
            );
        $this->assertFalse($part->getDelSp());
    }

    public function testDelSpIsSetInHeader()
    {
        $cType = $this->createHeader('Content-Type', 'text/plain', [], false);
        $cType->shouldReceive('setParameter')->once()->with('delsp', 'yes');

        $part = $this->createMimePart($this->createHeaderSet([
            'Content-Type' => $cType, ]),
            $this->createEncoder(), $this->createCache()
            );
        $part->setDelSp(true);
    }

    public function testFluidInterface()
    {
        $part = $this->createMimePart($this->createHeaderSet(),
            $this->createEncoder(), $this->createCache()
            );

        $this->assertSame($part,
            $part
            ->setContentType('text/plain')
            ->setEncoder($this->createEncoder())
            ->setId('foo@bar')
            ->setDescription('my description')
            ->setMaxLineLength(998)
            ->setBody('xx')
            ->setBoundary('xyz')
            ->setChildren([])
            ->setCharset('utf-8')
            ->setFormat('flowed')
            ->setDelSp(true)
            );
    }

    //abstract
    protected function createEntity($headers, $encoder, $cache)
    {
        return $this->createMimePart($headers, $encoder, $cache);
    }

    protected function createMimePart($headers, $encoder, $cache)
    {
        $idGenerator = new Swift_Mime_IdGenerator('example.com');

        return new Swift_Mime_MimePart($headers, $encoder, $cache, $idGenerator);
    }
}


================================================
FILE: tests/unit/Swift/Mime/SimpleHeaderFactoryTest.php
================================================
<?php

use Egulias\EmailValidator\EmailValidator;

class Swift_Mime_SimpleHeaderFactoryTest extends \PHPUnit\Framework\TestCase
{
    private $factory;

    protected function setUp()
    {
        $this->factory = $this->createFactory();
    }

    public function testMailboxHeaderIsCorrectType()
    {
        $header = $this->factory->createMailboxHeader('X-Foo');
        $this->assertInstanceOf('Swift_Mime_Headers_MailboxHeader', $header);
    }

    public function testMailboxHeaderHasCorrectName()
    {
        $header = $this->factory->createMailboxHeader('X-Foo');
        $this->assertEquals('X-Foo', $header->getFieldName());
    }

    public function testMailboxHeaderHasCorrectModel()
    {
        $header = $this->factory->createMailboxHeader('X-Foo',
            ['foo@bar' => 'FooBar']
            );
        $this->assertEquals(['foo@bar' => 'FooBar'], $header->getFieldBodyModel());
    }

    public function testDateHeaderHasCorrectType()
    {
        $header = $this->factory->createDateHeader('X-Date');
        $this->assertInstanceOf('Swift_Mime_Headers_DateHeader', $header);
    }

    public function testDateHeaderHasCorrectName()
    {
        $header = $this->factory->createDateHeader('X-Date');
        $this->assertEquals('X-Date', $header->getFieldName());
    }

    public function testDateHeaderHasCorrectModel()
    {
        $dateTime = new \DateTimeImmutable();
        $header = $this->factory->createDateHeader('X-Date', $dateTime);
        $this->assertEquals($dateTime, $header->getFieldBodyModel());
    }

    public function testTextHeaderHasCorrectType()
    {
        $header = $this->factory->createTextHeader('X-Foo');
        $this->assertInstanceOf('Swift_Mime_Headers_UnstructuredHeader', $header);
    }

    public function testTextHeaderHasCorrectName()
    {
        $header = $this->factory->createTextHeader('X-Foo');
        $this->assertEquals('X-Foo', $header->getFieldName());
    }

    public function testTextHeaderHasCorrectModel()
    {
        $header = $this->factory->createTextHeader('X-Foo', 'bar');
        $this->assertEquals('bar', $header->getFieldBodyModel());
    }

    public function testParameterizedHeaderHasCorrectType()
    {
        $header = $this->factory->createParameterizedHeader('X-Foo');
        $this->assertInstanceOf('Swift_Mime_Headers_ParameterizedHeader', $header);
    }

    public function testParameterizedHeaderHasCorrectName()
    {
        $header = $this->factory->createParameterizedHeader('X-Foo');
        $this->assertEquals('X-Foo', $header->getFieldName());
    }

    public function testParameterizedHeaderHasCorrectModel()
    {
        $header = $this->factory->createParameterizedHeader('X-Foo', 'bar');
        $this->assertEquals('bar', $header->getFieldBodyModel());
    }

    public function testParameterizedHeaderHasCorrectParams()
    {
        $header = $this->factory->createParameterizedHeader('X-Foo', 'bar',
            ['zip' => 'button']
            );
        $this->assertEquals(['zip' => 'button'], $header->getParameters());
    }

    public function testIdHeaderHasCorrectType()
    {
        $header = $this->factory->createIdHeader('X-ID');
        $this->assertInstanceOf('Swift_Mime_Headers_IdentificationHeader', $header);
    }

    public function testIdHeaderHasCorrectName()
    {
        $header = $this->factory->createIdHeader('X-ID');
        $this->assertEquals('X-ID', $header->getFieldName());
    }

    public function testIdHeaderHasCorrectModel()
    {
        $header = $this->factory->createIdHeader('X-ID', 'xyz@abc');
        $this->assertEquals(['xyz@abc'], $header->getFieldBodyModel());
    }

    public function testPathHeaderHasCorrectType()
    {
        $header = $this->factory->createPathHeader('X-Path');
        $this->assertInstanceOf('Swift_Mime_Headers_PathHeader', $header);
    }

    public function testPathHeaderHasCorrectName()
    {
        $header = $this->factory->createPathHeader('X-Path');
        $this->assertEquals('X-Path', $header->getFieldName());
    }

    public function testPathHeaderHasCorrectModel()
    {
        $header = $this->factory->createPathHeader('X-Path', 'foo@bar');
        $this->assertEquals('foo@bar', $header->getFieldBodyModel());
    }

    public function testCharsetChangeNotificationNotifiesEncoders()
    {
        $encoder = $this->createHeaderEncoder();
        $encoder->expects($this->once())
                ->method('charsetChanged')
                ->with('utf-8');
        $paramEncoder = $this->createParamEncoder();
        $paramEncoder->expects($this->once())
                     ->method('charsetChanged')
                     ->with('utf-8');

        $factory = $this->createFactory($encoder, $paramEncoder);

        $factory->charsetChanged('utf-8');
    }

    private function createFactory($encoder = null, $paramEncoder = null)
    {
        return new Swift_Mime_SimpleHeaderFactory(
            $encoder
                ?: $this->createHeaderEncoder(),
            $paramEncoder
                ?: $this->createParamEncoder(),
            new EmailValidator()
            );
    }

    private function createHeaderEncoder()
    {
        return $this->getMockBuilder('Swift_Mime_HeaderEncoder')->getMock();
    }

    private function createParamEncoder()
    {
        return $this->getMockBuilder('Swift_Encoder')->getMock();
    }
}


================================================
FILE: tests/unit/Swift/Mime/SimpleHeaderSetTest.php
================================================
<?php

class Swift_Mime_SimpleHeaderSetTest extends \PHPUnit\Framework\TestCase
{
    public function testAddMailboxHeaderDelegatesToFactory()
    {
        $factory = $this->createFactory();
        $factory->expects($this->once())
                ->method('createMailboxHeader')
                ->with('From', ['person@domain' => 'Person'])
                ->willReturn($this->createHeader('From'));

        $set = $this->createSet($factory);
        $set->addMailboxHeader('From', ['person@domain' => 'Person']);
    }

    public function testAddDateHeaderDelegatesToFactory()
    {
        $dateTime = new DateTimeImmutable();

        $factory = $this->createFactory();
        $factory->expects($this->once())
                ->method('createDateHeader')
                ->with('Date', $dateTime)
                ->willReturn($this->createHeader('Date'));

        $set = $this->createSet($factory);
        $set->addDateHeader('Date', $dateTime);
    }

    public function testAddTextHeaderDelegatesToFactory()
    {
        $factory = $this->createFactory();
        $factory->expects($this->once())
                ->method('createTextHeader')
                ->with('Subject', 'some text')
                ->willReturn($this->createHeader('Subject'));

        $set = $this->createSet($factory);
        $set->addTextHeader('Subject', 'some text');
    }

    public function testAddParameterizedHeaderDelegatesToFactory()
    {
        $factory = $this->createFactory();
        $factory->expects($this->once())
                ->method('createParameterizedHeader')
                ->with('Content-Type', 'text/plain', ['charset' => 'utf-8'])
                ->willReturn($this->createHeader('Content-Type'));

        $set = $this->createSet($factory);
        $set->addParameterizedHeader('Content-Type', 'text/plain',
            ['charset' => 'utf-8']
            );
    }

    public function testAddIdHeaderDelegatesToFactory()
    {
        $factory = $this->createFactory();
        $factory->expects($this->once())
                ->method('createIdHeader')
                ->with('Message-ID', 'some@id')
                ->willReturn($this->createHeader('Message-ID'));

        $set = $this->createSet($factory);
        $set->addIdHeader('Message-ID', 'some@id');
    }

    public function testAddPathHeaderDelegatesToFactory()
    {
        $factory = $this->createFactory();
        $factory->expects($this->once())
                ->method('createPathHeader')
                ->with('Return-Path', 'some@path')
                ->willReturn($this->createHeader('Return-Path'));

        $set = $this->createSet($factory);
        $set->addPathHeader('Return-Path', 'some@path');
    }

    public function testHasReturnsFalseWhenNoHeaders()
    {
        $set = $this->createSet($this->createFactory());
        $this->assertFalse($set->has('Some-Header'));
    }

    public function testAddedMailboxHeaderIsSeenByHas()
    {
        $factory = $this->createFactory();
        $factory->expects($this->once())
                ->method('createMailboxHeader')
                ->with('From', ['person@domain' => 'Person'])
                ->willReturn($this->createHeader('From'));

        $set = $this->createSet($factory);
        $set->addMailboxHeader('From', ['person@domain' => 'Person']);
        $this->assertTrue($set->has('From'));
    }

    public function testAddedDateHeaderIsSeenByHas()
    {
        $dateTime = new DateTimeImmutable();

        $factory = $this->createFactory();
        $factory->expects($this->once())
                ->method('createDateHeader')
                ->with('Date', $dateTime)
                ->willReturn($this->createHeader('Date'));

        $set = $this->createSet($factory);
        $set->addDateHeader('Date', $dateTime);
        $this->assertTrue($set->has('Date'));
    }

    public function testAddedTextHeaderIsSeenByHas()
    {
        $factory = $this->createFactory();
        $factory->expects($this->once())
                ->method('createTextHeader')
                ->with('Subject', 'some text')
                ->willReturn($this->createHeader('Subject'));

        $set = $this->createSet($factory);
        $set->addTextHeader('Subject', 'some text');
        $this->assertTrue($set->has('Subject'));
    }

    public function testAddedParameterizedHeaderIsSeenByHas()
    {
        $factory = $this->createFactory();
        $factory->expects($this->once())
                ->method('createParameterizedHeader')
                ->with('Content-Type', 'text/plain', ['charset' => 'utf-8'])
                ->willReturn($this->createHeader('Content-Type'));

        $set = $this->createSet($factory);
        $set->addParameterizedHeader('Content-Type', 'text/plain',
            ['charset' => 'utf-8']
            );
        $this->assertTrue($set->has('Content-Type'));
    }

    public function testAddedIdHeaderIsSeenByHas()
    {
        $factory = $this->createFactory();
        $factory->expects($this->once())
                ->method('createIdHeader')
                ->with('Message-ID', 'some@id')
                ->willReturn($this->createHeader('Message-ID'));

        $set = $this->createSet($factory);
        $set->addIdHeader('Message-ID', 'some@id');
        $this->assertTrue($set->has('Message-ID'));
    }

    public function testAddedPathHeaderIsSeenByHas()
    {
        $factory = $this->createFactory();
        $factory->expects($this->once())
                ->method('createPathHeader')
                ->with('Return-Path', 'some@path')
                ->willReturn($this->createHeader('Return-Path'));

        $set = $this->createSet($factory);
        $set->addPathHeader('Return-Path', 'some@path');
        $this->assertTrue($set->has('Return-Path'));
    }

    public function testNewlySetHeaderIsSeenByHas()
    {
        $factory = $this->createFactory();
        $header = $this->createHeader('X-Foo', 'bar');
        $set = $this->createSet($factory);
        $set->set($header);
        $this->assertTrue($set->has('X-Foo'));
    }

    public function testHasCanAcceptOffset()
    {
        $factory = $this->createFactory();
        $factory->expects($this->once())
                ->method('createIdHeader')
                ->with('Message-ID', 'some@id')
                ->willReturn($this->createHeader('Message-ID'));

        $set = $this->createSet($factory);
        $set->addIdHeader('Message-ID', 'some@id');
        $this->assertTrue($set->has('Message-ID', 0));
    }

    public function testHasWithIllegalOffsetReturnsFalse()
    {
        $factory = $this->createFactory();
        $factory->expects($this->once())
                ->method('createIdHeader')
                ->with('Message-ID', 'some@id')
                ->willReturn($this->createHeader('Message-ID'));

        $set = $this->createSet($factory);
        $set->addIdHeader('Message-ID', 'some@id');
        $this->assertFalse($set->has('Message-ID', 1));
    }

    public function testHasCanDistinguishMultipleHeaders()
    {
        $factory = $this->createFactory();
        $factory->expects($this->exactly(2))
                ->method('createIdHeader')
                ->withConsecutive(
                    ['Message-ID', 'some@id'],
                    ['Message-ID', 'other@id']
                )
                ->willReturnOnConsecutiveCalls(
                    $this->createHeader('Message-ID'),
                    $this->createHeader('Message-ID')
                );

        $set = $this->createSet($factory);
        $set->addIdHeader('Message-ID', 'some@id');
        $set->addIdHeader('Message-ID', 'other@id');
        $this->assertTrue($set->has('Message-ID', 1));
    }

    public function testGetWithUnspecifiedOffset()
    {
        $header = $this->createHeader('Message-ID');
        $factory = $this->createFactory();
        $factory->expects($this->once())
                ->method('createIdHeader')
                ->with('Message-ID', 'some@id')
                ->willReturn($header);

        $set = $this->createSet($factory);
        $set->addIdHeader('Message-ID', 'some@id');
        $this->assertSame($header, $set->get('Message-ID'));
    }

    public function testGetWithSpeiciedOffset()
    {
        $header0 = $this->createHeader('Message-ID');
        $header1 = $this->createHeader('Message-ID');
        $header2 = $this->createHeader('Message-ID');
        $factory = $this->createFactory();
        $factory->expects($this->exactly(3))
                ->method('createIdHeader')
                ->withConsecutive(
                    ['Message-ID', 'some@id'],
                    ['Message-ID', 'other@id'],
                    ['Message-ID', 'more@id']
                )
                ->willReturnOnConsecutiveCalls(
                    $header0,
                    $header1,
                    $header2
                );

        $set = $this->createSet($factory);
        $set->addIdHeader('Message-ID', 'some@id');
        $set->addIdHeader('Message-ID', 'other@id');
        $set->addIdHeader('Message-ID', 'more@id');
        $this->assertSame($header1, $set->get('Message-ID', 1));
    }

    public function testGetReturnsNullIfHeaderNotSet()
    {
        $set = $this->createSet($this->createFactory());
        $this->assertNull($set->get('Message-ID', 99));
    }

    public function testGetAllReturnsAllHeadersMatchingName()
    {
        $header0 = $this->createHeader('Message-ID');
        $header1 = $this->createHeader('Message-ID');
        $header2 = $this->createHeader('Message-ID');
        $factory = $this->createFactory();
        $factory->expects($this->exactly(3))
                ->method('createIdHeader')
                ->withConsecutive(
                    ['Message-ID', 'some@id'],
                    ['Message-ID', 'other@id'],
                    ['Message-ID', 'more@id']
                )
                ->willReturnOnConsecutiveCalls(
                    $header0,
                    $header1,
                    $header2
                );

        $set = $this->createSet($factory);
        $set->addIdHeader('Message-ID', 'some@id');
        $set->addIdHeader('Message-ID', 'other@id');
        $set->addIdHeader('Message-ID', 'more@id');

        $this->assertEquals([$header0, $header1, $header2],
            $set->getAll('Message-ID')
            );
    }

    public function testGetAllReturnsAllHeadersIfNoArguments()
    {
        $header0 = $this->createHeader('Message-ID');
        $header1 = $this->createHeader('Subject');
        $header2 = $this->createHeader('To');
        $factory = $this->createFactory();
        $factory->expects($this->exactly(3))
                ->method('createIdHeader')
                ->withConsecutive(
                    ['Message-ID', 'some@id'],
                    ['Subject', 'thing'],
                    ['To', 'person@example.org']
                )
                ->willReturnOnConsecutiveCalls(
                    $header0,
                    $header1,
                    $header2
                );

        $set = $this->createSet($factory);
        $set->addIdHeader('Message-ID', 'some@id');
        $set->addIdHeader('Subject', 'thing');
        $set->addIdHeader('To', 'person@example.org');

        $this->assertEquals([$header0, $header1, $header2],
            $set->getAll()
            );
    }

    public function testGetAllReturnsEmptyArrayIfNoneSet()
    {
        $set = $this->createSet($this->createFactory());
        $this->assertEquals([], $set->getAll('Received'));
    }

    public function testRemoveWithUnspecifiedOffset()
    {
        $header = $this->createHeader('Message-ID');
        $factory = $this->createFactory();
        $factory->expects($this->once())
                ->method('createIdHeader')
                ->with('Message-ID', 'some@id')
                ->willReturn($header);

        $set = $this->createSet($factory);
        $set->addIdHeader('Message-ID', 'some@id');
        $set->remove('Message-ID');
        $this->assertFalse($set->has('Message-ID'));
    }

    public function testRemoveWithSpecifiedIndexRemovesHeader()
    {
        $header0 = $this->createHeader('Message-ID');
        $header1 = $this->createHeader('Message-ID');
        $factory = $this->createFactory();
        $factory->expects($this->exactly(2))
                ->method('createIdHeader')
                ->withConsecutive(
                    ['Message-ID', 'some@id'],
                    ['Message-ID', 'other@id']
                )
                ->willReturnOnConsecutiveCalls(
                    $header0,
                    $header1
                );

        $set = $this->createSet($factory);
        $set->addIdHeader('Message-ID', 'some@id');
        $set->addIdHeader('Message-ID', 'other@id');
        $set->remove('Message-ID', 0);
        $this->assertFalse($set->has('Message-ID', 0));
        $this->assertTrue($set->has('Message-ID', 1));
        $this->assertTrue($set->has('Message-ID'));
        $set->remove('Message-ID', 1);
        $this->assertFalse($set->has('Message-ID', 1));
        $this->assertFalse($set->has('Message-ID'));
    }

    public function testRemoveWithSpecifiedIndexLeavesOtherHeaders()
    {
        $header0 = $this->createHeader('Message-ID');
        $header1 = $this->createHeader('Message-ID');
        $factory = $this->createFactory();
        $factory->expects($this->exactly(2))
                ->method('createIdHeader')
                ->withConsecutive(
                    ['Message-ID', 'some@id'],
                    ['Message-ID', 'other@id']
                )
                ->willReturnOnConsecutiveCalls(
                    $header0,
                    $header1
                );

        $set = $this->createSet($factory);
        $set->addIdHeader('Message-ID', 'some@id');
        $set->addIdHeader('Message-ID', 'other@id');
        $set->remove('Message-ID', 1);
        $this->assertTrue($set->has('Message-ID', 0));
    }

    public function testRemoveWithInvalidOffsetDoesNothing()
    {
        $header = $this->createHeader('Message-ID');
        $factory = $this->createFactory();
        $factory->expects($this->once())
                ->method('createIdHeader')
                ->with('Message-ID', 'some@id')
                ->willReturn($header);

        $set = $this->createSet($factory);
        $set->addIdHeader('Message-ID', 'some@id');
        $set->remove('Message-ID', 50);
        $this->assertTrue($set->has('Message-ID'));
    }

    public function testRemoveAllRemovesAllHeadersWithName()
    {
        $header0 = $this->createHeader('Message-ID');
        $header1 = $this->createHeader('Message-ID');
        $factory = $this->createFactory();
        $factory->expects($this->exactly(2))
                ->method('createIdHeader')
                ->withConsecutive(
                    ['Message-ID', 'some@id'],
                    ['Message-ID', 'other@id']
                )
                ->willReturnOnConsecutiveCalls(
                    $header0,
                    $header1
                );

        $set = $this->createSet($factory);
        $set->addIdHeader('Message-ID', 'some@id');
        $set->addIdHeader('Message-ID', 'other@id');
        $set->removeAll('Message-ID');
        $this->assertFalse($set->has('Message-ID', 0));
        $this->assertFalse($set->has('Message-ID', 1));
    }

    public function testHasIsNotCaseSensitive()
    {
        $header = $this->createHeader('Message-ID');
        $factory = $this->createFactory();
        $factory->expects($this->once())
                ->method('createIdHeader')
                ->with('Message-ID', 'some@id')
                ->willReturn($header);

        $set = $this->createSet($factory);
        $set->addIdHeader('Message-ID', 'some@id');
        $this->assertTrue($set->has('message-id'));
    }

    public function testGetIsNotCaseSensitive()
    {
        $header = $this->createHeader('Message-ID');
        $factory = $this->createFactory();
        $factory->expects($this->once())
                ->method('createIdHeader')
                ->with('Message-ID', 'some@id')
                ->willReturn($header);

        $set = $this->createSet($factory);
        $set->addIdHeader('Message-ID', 'some@id');
        $this->assertSame($header, $set->get('message-id'));
    }

    public function testGetAllIsNotCaseSensitive()
    {
        $header = $this->createHeader('Message-ID');
        $factory = $this->createFactory();
        $factory->expects($this->once())
                ->method('createIdHeader')
                ->with('Message-ID', 'some@id')
                ->willReturn($header);

        $set = $this->createSet($factory);
        $set->addIdHeader('Message-ID', 'some@id');
        $this->assertEquals([$header], $set->getAll('message-id'));
    }

    public function testRemoveIsNotCaseSensitive()
    {
        $header = $this->createHeader('Message-ID');
        $factory = $this->createFactory();
        $factory->expects($this->once())
                ->method('createIdHeader')
                ->with('Message-ID', 'some@id')
                ->willReturn($header);

        $set = $this->createSet($factory);
        $set->addIdHeader('Message-ID', 'some@id');
        $set->remove('message-id');
        $this->assertFalse($set->has('Message-ID'));
    }

    public function testRemoveAllIsNotCaseSensitive()
    {
        $header = $this->createHeader('Message-ID');
        $factory = $this->createFactory();
        $factory->expects($this->once())
                ->method('createIdHeader')
                ->with('Message-ID', 'some@id')
                ->willReturn($header);

        $set = $this->createSet($factory);
        $set->addIdHeader('Message-ID', 'some@id');
        $set->removeAll('message-id');
        $this->assertFalse($set->has('Message-ID'));
    }

    public function testToStringJoinsHeadersTogether()
    {
        $factory = $this->createFactory();
        $factory->expects($this->exactly(2))
                ->method('createTextHeader')
                ->withConsecutive(
                    ['Foo', 'bar'],
                    ['Zip', 'buttons']
                )
                ->willReturnOnConsecutiveCalls(
                    $this->createHeader('Foo', 'bar'),
                    $this->createHeader('Zip', 'buttons')
                );

        $set = $this->createSet($factory);
        $set->addTextHeader('Foo', 'bar');
        $set->addTextHeader('Zip', 'buttons');
        $this->assertEquals(
            "Foo: bar\r\n".
            "Zip: buttons\r\n",
            $set->toString()
            );
    }

    public function testHeadersWithoutBodiesAreNotDisplayed()
    {
        $factory = $this->createFactory();
        $factory->expects($this->exactly(2))
                ->method('createTextHeader')
                ->withConsecutive(
                    ['Foo', 'bar'],
                    ['Zip', '']
                )
                ->willReturnOnConsecutiveCalls(
                    $this->createHeader('Foo', 'bar'),
                    $this->createHeader('Zip', '')
                );

        $set = $this->createSet($factory);
        $set->addTextHeader('Foo', 'bar');
        $set->addTextHeader('Zip', '');
        $this->assertEquals(
            "Foo: bar\r\n",
            $set->toString()
            );
    }

    public function testHeadersWithoutBodiesCanBeForcedToDisplay()
    {
        $factory = $this->createFactory();
        $factory->expects($this->exactly(2))
                ->method('createTextHeader')
                ->withConsecutive(
                    ['Foo', ''],
                    ['Zip', '']
                )
                ->willReturnOnConsecutiveCalls(
                    $this->createHeader('Foo', ''),
                    $this->createHeader('Zip', '')
                );

        $set = $this->createSet($factory);
        $set->addTextHeader('Foo', '');
        $set->addTextHeader('Zip', '');
        $set->setAlwaysDisplayed(['Foo', 'Zip']);
        $this->assertEquals(
            "Foo: \r\n".
            "Zip: \r\n",
            $set->toString()
            );
    }

    public function testHeaderSequencesCanBeSpecified()
    {
        $factory = $this->createFactory();
        $factory->expects($this->exactly(3))
                ->method('createTextHeader')
                ->withConsecutive(
                    ['Third', 'three'],
                    ['First', 'one'],
                    ['Second', 'two']
                )
                ->willReturnOnConsecutiveCalls(
                    $this->createHeader('Third', 'three'),
                    $this->createHeader('First', 'one'),
                    $this->createHeader('Second', 'two')
                );

        $set = $this->createSet($factory);
        $set->addTextHeader('Third', 'three');
        $set->addTextHeader('First', 'one');
        $set->addTextHeader('Second', 'two');

        $set->defineOrdering(['First', 'Second', 'Third']);

        $this->assertEquals(
            "First: one\r\n".
            "Second: two\r\n".
            "Third: three\r\n",
            $set->toString()
            );
    }

    public function testUnsortedHeadersAppearAtEnd()
    {
        $factory = $this->createFactory();
        $factory->expects($this->exactly(5))
                ->method('createTextHeader')
                ->withConsecutive(
                    ['Fourth', 'four'],
                    ['Fifth', 'five'],
                    ['Third', 'three'],
                    ['First', 'one'],
                    ['Second', 'two']
                )
                ->willReturnOnConsecutiveCalls(
                    $this->createHeader('Fourth', 'four'),
                    $this->createHeader('Fifth', 'five'),
                    $this->createHeader('Third', 'three'),
                    $this->createHeader('First', 'one'),
                    $this->createHeader('Second', 'two')
                );

        $set = $this->createSet($factory);
        $set->addTextHeader('Fourth', 'four');
        $set->addTextHeader('Fifth', 'five');
        $set->addTextHeader('Third', 'three');
        $set->addTextHeader('First', 'one');
        $set->addTextHeader('Second', 'two');

        $set->defineOrdering(['First', 'Second', 'Third']);

        $this->assertEquals(
            "First: one\r\n".
            "Second: two\r\n".
            "Third: three\r\n".
            "Fourth: four\r\n".
            "Fifth: five\r\n",
            $set->toString()
            );
    }

    public function testSettingCharsetNotifiesAlreadyExistingHeaders()
    {
        $subject = $this->createHeader('Subject', 'some text');
        $xHeader = $this->createHeader('X-Header', 'some text');
        $factory = $this->createFactory();
        $factory->expects($this->exactly(2))
                ->method('createTextHeader')
                ->withConsecutive(
                    ['Subject', 'some text'],
                    ['X-Header', 'some text']
                )
                ->willReturnOnConsecutiveCalls(
                    $subject,
                    $xHeader
                );
        $subject->expects($this->once())
                ->method('setCharset')
                ->with('utf-8');
        $xHeader->expects($this->once())
                ->method('setCharset')
                ->with('utf-8');

        $set = $this->createSet($factory);
        $set->addTextHeader('Subject', 'some text');
        $set->addTextHeader('X-Header', 'some text');

        $set->setCharset('utf-8');
    }

    public function testCharsetChangeNotifiesAlreadyExistingHeaders()
    {
        $subject = $this->createHeader('Subject', 'some text');
        $xHeader = $this->createHeader('X-Header', 'some text');
        $factory = $this->createFactory();
        $factory->expects($this->exactly(2))
                ->method('createTextHeader')
                ->withConsecutive(
                    ['Subject', 'some text'],
                    ['X-Header', 'some text']
                )
                ->willReturnOnConsecutiveCalls(
                    $subject,
                    $xHeader
                );
        $subject->expects($this->once())
                ->method('setCharset')
                ->with('utf-8');
        $xHeader->expects($this->once())
                ->method('setCharset')
                ->with('utf-8');

        $set = $this->createSet($factory);
        $set->addTextHeader('Subject', 'some text');
        $set->addTextHeader('X-Header', 'some text');

        $set->charsetChanged('utf-8');
    }

    public function testCharsetChangeNotifiesFactory()
    {
        $factory = $this->createFactory();
        $factory->expects($this->once())
                ->method('charsetChanged')
                ->with('utf-8');

        $set = $this->createSet($factory);

        $set->setCharset('utf-8');
    }

    private function createSet($factory)
    {
        return new Swift_Mime_SimpleHeaderSet($factory);
    }

    private function createFactory()
    {
        return $this->getMockBuilder('Swift_Mime_SimpleHeaderFactory')->disableOriginalConstructor()->getMock();
    }

    private function createHeader($name, $body = '')
    {
        $header = $this->getMockBuilder('Swift_Mime_Header')->getMock();
        $header->expects($this->any())
               ->method('getFieldName')
               ->willReturn($name);
        $header->expects($this->any())
               ->method('toString')
               ->willReturn(sprintf("%s: %s\r\n", $name, $body));
        $header->expects($this->any())
               ->method('getFieldBody')
               ->willReturn($body);

        return $header;
    }
}


================================================
FILE: tests/unit/Swift/Mime/SimpleMessageTest.php
================================================
<?php

class Swift_Mime_SimpleMessageTest extends Swift_Mime_MimePartTest
{
    public function testNestingLevelIsSubpart()
    {
        // not relevant
        $this->addToAssertionCount(1);
    }

    public function testNestingLevelIsTop()
    {
        $message = $this->createMessage($this->createHeaderSet(),
            $this->createEncoder(), $this->createCache()
            );
        $this->assertEquals(
            Swift_Mime_SimpleMimeEntity::LEVEL_TOP, $message->getNestingLevel()
            );
    }

    public function testDateIsReturnedFromHeader()
    {
        $dateTime = new DateTimeImmutable();

        $date = $this->createHeader('Date', $dateTime);
        $message = $this->createMessage(
            $this->createHeaderSet(['Date' => $date]),
            $this->createEncoder(), $this->createCache()
            );
        $this->assertEquals($dateTime, $message->getDate());
    }

    public function testDateIsSetInHeader()
    {
        $dateTime = new DateTimeImmutable();

        $date = $this->createHeader('Date', new DateTimeImmutable(), [], false);
        $date->shouldReceive('setFieldBodyModel')
             ->once()
             ->with($dateTime);
        $date->shouldReceive('setFieldBodyModel')
             ->zeroOrMoreTimes();

        $message = $this->createMessage(
            $this->createHeaderSet(['Date' => $date]),
            $this->createEncoder(), $this->createCache()
            );
        $message->setDate($dateTime);
    }

    public function testDateHeaderIsCreatedIfNonePresent()
    {
        $dateTime = new DateTimeImmutable();

        $headers = $this->createHeaderSet([], false);
        $headers->shouldReceive('addDateHeader')
                ->once()
                ->with('Date', $dateTime);
        $headers->shouldReceive('addDateHeader')
                ->zeroOrMoreTimes();

        $message = $this->createMessage($headers, $this->createEncoder(),
            $this->createCache()
            );
        $message->setDate($dateTime);
    }

    public function testDateHeaderIsAddedDuringConstruction()
    {
        $headers = $this->createHeaderSet([], false);
        $headers->shouldReceive('addDateHeader')
                ->once()
                ->with('Date', Mockery::type('DateTimeImmutable'));

        $message = $this->createMessage($headers, $this->createEncoder(),
            $this->createCache()
            );
    }

    public function testIdIsReturnedFromHeader()
    {
        /* -- RFC 2045, 7.
        In constructing a high-level user agent, it may be desirable to allow
        one body to make reference to another.  Accordingly, bodies may be
        labelled using the "Content-ID" header field, which is syntactically
        identical to the "Message-ID" header field
        */

        $messageId = $this->createHeader('Message-ID', 'a@b');
        $message = $this->createMessage(
            $this->createHeaderSet(['Message-ID' => $messageId]),
            $this->createEncoder(), $this->createCache()
            );
        $this->assertEquals('a@b', $message->getId());
    }

    public function testIdIsSetInHeader()
    {
        $messageId = $this->createHeader('Message-ID', 'a@b', [], false);
        $messageId->shouldReceive('setFieldBodyModel')
                  ->once()
                  ->with('x@y');
        $messageId->shouldReceive('setFieldBodyModel')
                  ->zeroOrMoreTimes();

        $message = $this->createMessage(
            $this->createHeaderSet(['Message-ID' => $messageId]),
            $this->createEncoder(), $this->createCache()
            );
        $message->setId('x@y');
    }

    public function testIdIsAutoGenerated()
    {
        $headers = $this->createHeaderSet([], false);
        $headers->shouldReceive('addIdHeader')
                ->once()
                ->with('Message-ID', \Mockery::pattern('/^.*?@.*?$/D'));

        $message = $this->createMessage($headers, $this->createEncoder(),
            $this->createCache()
            );
    }

    public function testSubjectIsReturnedFromHeader()
    {
        /* -- RFC 2822, 3.6.5.
     */

        $subject = $this->createHeader('Subject', 'example subject');
        $message = $this->createMessage(
            $this->createHeaderSet(['Subject' => $subject]),
            $this->createEncoder(), $this->createCache()
            );
        $this->assertEquals('example subject', $message->getSubject());
    }

    public function testSubjectIsSetInHeader()
    {
        $subject = $this->createHeader('Subject', '', [], false);
        $subject->shouldReceive('setFieldBodyModel')
                ->once()
                ->with('foo');

        $message = $this->createMessage(
            $this->createHeaderSet(['Subject' => $subject]),
            $this->createEncoder(), $this->createCache()
            );
        $message->setSubject('foo');
    }

    public function testSubjectHeaderIsCreatedIfNotPresent()
    {
        $headers = $this->createHeaderSet([], false);
        $headers->shouldReceive('addTextHeader')
                ->once()
                ->with('Subject', 'example subject');
        $headers->shouldReceive('addTextHeader')
                ->zeroOrMoreTimes();

        $message = $this->createMessage($headers, $this->createEncoder(),
            $this->createCache()
            );
        $message->setSubject('example subject');
    }

    public function testReturnPathIsReturnedFromHeader()
    {
        /* -- RFC 2822, 3.6.7.
     */

        $path = $this->createHeader('Return-Path', 'bounces@domain');
        $message = $this->createMessage(
            $this->createHeaderSet(['Return-Path' => $path]),
            $this->createEncoder(), $this->createCache()
            );
        $this->assertEquals('bounces@domain', $message->getReturnPath());
    }

    public function testReturnPathIsSetInHeader()
    {
        $path = $this->createHeader('Return-Path', '', [], false);
        $path->shouldReceive('setFieldBodyModel')
             ->once()
             ->with('bounces@domain');

        $message = $this->createMessage(
            $this->createHeaderSet(['Return-Path' => $path]),
            $this->createEncoder(), $this->createCache()
            );
        $message->setReturnPath('bounces@domain');
    }

    public function testReturnPathHeaderIsAddedIfNoneSet()
    {
        $headers = $this->createHeaderSet([], false);
        $headers->shouldReceive('addPathHeader')
                ->once()
                ->with('Return-Path', 'bounces@domain');

        $message = $this->createMessage($headers, $this->createEncoder(),
            $this->createCache()
            );
        $message->setReturnPath('bounces@domain');
    }

    public function testSenderIsReturnedFromHeader()
    {
        /* -- RFC 2822, 3.6.2.
     */

        $sender = $this->createHeader('Sender', ['sender@domain' => 'Name']);
        $message = $this->createMessage(
            $this->createHeaderSet(['Sender' => $sender]),
            $this->createEncoder(), $this->createCache()
            );
        $this->assertEquals(['sender@domain' => 'Name'], $message->getSender());
    }

    public function testSenderIsSetInHeader()
    {
        $sender = $this->createHeader('Sender', ['sender@domain' => 'Name'],
            [], false
            );
        $sender->shouldReceive('setFieldBodyModel')
               ->once()
               ->with(['other@domain' => 'Other']);

        $message = $this->createMessage(
            $this->createHeaderSet(['Sender' => $sender]),
            $this->createEncoder(), $this->createCache()
            );
        $message->setSender(['other@domain' => 'Other']);
    }

    public function testSenderHeaderIsAddedIfNoneSet()
    {
        $headers = $this->createHeaderSet([], false);
        $headers->shouldReceive('addMailboxHeader')
                ->once()
                ->with('Sender', (array) 'sender@domain');
        $headers->shouldReceive('addMailboxHeader')
                ->zeroOrMoreTimes();

        $message = $this->createMessage($headers, $this->createEncoder(),
            $this->createCache()
            );
        $message->setSender('sender@domain');
    }

    public function testNameCanBeUsedInSenderHeader()
    {
        $headers = $this->createHeaderSet([], false);
        $headers->shouldReceive('addMailboxHeader')
                ->once()
                ->with('Sender', ['sender@domain' => 'Name']);
        $headers->shouldReceive('addMailboxHeader')
                ->zeroOrMoreTimes();

        $message = $this->createMessage($headers, $this->createEncoder(),
            $this->createCache()
            );
        $message->setSender('sender@domain', 'Name');
    }

    public function testFromIsReturnedFromHeader()
    {
        /* -- RFC 2822, 3.6.2.
     */

        $from = $this->createHeader('From', ['from@domain' => 'Name']);
        $message = $this->createMessage(
            $this->createHeaderSet(['From' => $from]),
            $this->createEncoder(), $this->createCache()
            );
        $this->assertEquals(['from@domain' => 'Name'], $message->getFrom());
    }

    public function testFromIsSetInHeader()
    {
        $from = $this->createHeader('From', ['from@domain' => 'Name'],
            [], false
            );
        $from->shouldReceive('setFieldBodyModel')
             ->once()
             ->with(['other@domain' => 'Other']);

        $message = $this->createMessage(
            $this->createHeaderSet(['From' => $from]),
            $this->createEncoder(), $this->createCache()
            );
        $message->setFrom(['other@domain' => 'Other']);
    }

    public function testFromIsAddedToHeadersDuringAddFrom()
    {
        $from = $this->createHeader('From', ['from@domain' => 'Name'],
            [], false
            );
        $from->shouldReceive('setFieldBodyModel')
             ->once()
             ->with(['from@domain' => 'Name', 'other@domain' => 'Other']);

        $message = $this->createMessage(
            $this->createHeaderSet(['From' => $from]),
            $this->createEncoder(), $this->createCache()
            );
        $message->addFrom('other@domain', 'Other');
    }

    public function testFromHeaderIsAddedIfNoneSet()
    {
        $headers = $this->createHeaderSet([], false);
        $headers->shouldReceive('addMailboxHeader')
                ->once()
                ->with('From', (array) 'from@domain');
        $headers->shouldReceive('addMailboxHeader')
                ->zeroOrMoreTimes();

        $message = $this->createMessage($headers, $this->createEncoder(),
            $this->createCache()
            );
        $message->setFrom('from@domain');
    }

    public function testPersonalNameCanBeUsedInFromAddress()
    {
        $headers = $this->createHeaderSet([], false);
        $headers->shouldReceive('addMailboxHeader')
                ->once()
                ->with('From', ['from@domain' => 'Name']);
        $headers->shouldReceive('addMailboxHeader')
                ->zeroOrMoreTimes();

        $message = $this->createMessage($headers, $this->createEncoder(),
            $this->createCache()
            );
        $message->setFrom('from@domain', 'Name');
    }

    public function testReplyToIsReturnedFromHeader()
    {
        /* -- RFC 2822, 3.6.2.
     */

        $reply = $this->createHeader('Reply-To', ['reply@domain' => 'Name']);
        $message = $this->createMessage(
            $this->createHeaderSet(['Reply-To' => $reply]),
            $this->createEncoder(), $this->createCache()
            );
        $this->assertEquals(['reply@domain' => 'Name'], $message->getReplyTo());
    }

    public function testReplyToIsSetInHeader()
    {
        $reply = $this->createHeader('Reply-To', ['reply@domain' => 'Name'],
            [], false
            );
        $reply->shouldReceive('setFieldBodyModel')
              ->once()
              ->with(['other@domain' => 'Other']);

        $message = $this->createMessage(
            $this->createHeaderSet(['Reply-To' => $reply]),
            $this->createEncoder(), $this->createCache()
            );
        $message->setReplyTo(['other@domain' => 'Other']);
    }

    public function testReplyToIsAddedToHeadersDuringAddReplyTo()
    {
        $replyTo = $this->createHeader('Reply-To', ['from@domain' => 'Name'],
            [], false
            );
        $replyTo->shouldReceive('setFieldBodyModel')
                ->once()
                ->with(['from@domain' => 'Name', 'other@domain' => 'Other']);

        $message = $this->createMessage(
            $this->createHeaderSet(['Reply-To' => $replyTo]),
            $this->createEncoder(), $this->createCache()
            );
        $message->addReplyTo('other@domain', 'Other');
    }

    public function testReplyToHeaderIsAddedIfNoneSet()
    {
        $headers = $this->createHeaderSet([], false);
        $headers->shouldReceive('addMailboxHeader')
                ->once()
                ->with('Reply-To', (array) 'reply@domain');
        $headers->shouldReceive('addMailboxHeader')
                ->zeroOrMoreTimes();

        $message = $this->createMessage($headers, $this->createEncoder(),
            $this->createCache()
            );
        $message->setReplyTo('reply@domain');
    }

    public function testNameCanBeUsedInReplyTo()
    {
        $headers = $this->createHeaderSet([], false);
        $headers->shouldReceive('addMailboxHeader')
                ->once()
                ->with('Reply-To', ['reply@domain' => 'Name']);
        $headers->shouldReceive('addMailboxHeader')
                ->zeroOrMoreTimes();

        $message = $this->createMessage($headers, $this->createEncoder(),
            $this->createCache()
            );
        $message->setReplyTo('reply@domain', 'Name');
    }

    public function testToIsReturnedFromHeader()
    {
        /* -- RFC 2822, 3.6.3.
     */

        $to = $this->createHeader('To', ['to@domain' => 'Name']);
        $message = $this->createMessage(
            $this->createHeaderSet(['To' => $to]),
            $this->createEncoder(), $this->createCache()
            );
        $this->assertEquals(['to@domain' => 'Name'], $message->getTo());
    }

    public function testToIsSetInHeader()
    {
        $to = $this->createHeader('To', ['to@domain' => 'Name'],
            [], false
            );
        $to->shouldReceive('setFieldBodyModel')
           ->once()
           ->with(['other@domain' => 'Other']);

        $message = $this->createMessage(
            $this->createHeaderSet(['To' => $to]),
            $this->createEncoder(), $this->createCache()
            );
        $message->setTo(['other@domain' => 'Other']);
    }

    public function testToIsAddedToHeadersDuringAddTo()
    {
        $to = $this->createHeader('To', ['from@domain' => 'Name'],
            [], false
            );
        $to->shouldReceive('setFieldBodyModel')
           ->once()
           ->with(['from@domain' => 'Name', 'other@domain' => 'Other']);

        $message = $this->createMessage(
            $this->createHeaderSet(['To' => $to]),
            $this->createEncoder(), $this->createCache()
            );
        $message->addTo('other@domain', 'Other');
    }

    public function testToHeaderIsAddedIfNoneSet()
    {
        $headers = $this->createHeaderSet([], false);
        $headers->shouldReceive('addMailboxHeader')
                ->once()
                ->with('To', (array) 'to@domain');
        $headers->shouldReceive('addMailboxHeader')
                ->zeroOrMoreTimes();

        $message = $this->createMessage($headers, $this->createEncoder(),
            $this->createCache()
            );
        $message->setTo('to@domain');
    }

    public function testNameCanBeUsedInToHeader()
    {
        $headers = $this->createHeaderSet([], false);
        $headers->shouldReceive('addMailboxHeader')
                ->once()
                ->with('To', ['to@domain' => 'Name']);
        $headers->shouldReceive('addMailboxHeader')
                ->zeroOrMoreTimes();

        $message = $this->createMessage($headers, $this->createEncoder(),
            $this->createCache()
            );
        $message->setTo('to@domain', 'Name');
    }

    public function testCcIsReturnedFromHeader()
    {
        /* -- RFC 2822, 3.6.3.
     */

        $cc = $this->createHeader('Cc', ['cc@domain' => 'Name']);
        $message = $this->createMessage(
            $this->createHeaderSet(['Cc' => $cc]),
            $this->createEncoder(), $this->createCache()
            );
        $this->assertEquals(['cc@domain' => 'Name'], $message->getCc());
    }

    public function testCcIsSetInHeader()
    {
        $cc = $this->createHeader('Cc', ['cc@domain' => 'Name'],
            [], false
            );
        $cc->shouldReceive('setFieldBodyModel')
           ->once()
           ->with(['other@domain' => 'Other']);

        $message = $this->createMessage(
            $this->createHeaderSet(['Cc' => $cc]),
            $this->createEncoder(), $this->createCache()
            );
        $message->setCc(['other@domain' => 'Other']);
    }

    public function testCcIsAddedToHeadersDuringAddCc()
    {
        $cc = $this->createHeader('Cc', ['from@domain' => 'Name'],
            [], false
            );
        $cc->shouldReceive('setFieldBodyModel')
           ->once()
           ->with(['from@domain' => 'Name', 'other@domain' => 'Other']);

        $message = $this->createMessage(
            $this->createHeaderSet(['Cc' => $cc]),
            $this->createEncoder(), $this->createCache()
            );
        $message->addCc('other@domain', 'Other');
    }

    public function testCcHeaderIsAddedIfNoneSet()
    {
        $headers = $this->createHeaderSet([], false);
        $headers->shouldReceive('addMailboxHeader')
                ->once()
                ->with('Cc', (array) 'cc@domain');
        $headers->shouldReceive('addMailboxHeader')
                ->zeroOrMoreTimes();

        $message = $this->createMessage($headers, $this->createEncoder(),
            $this->createCache()
            );
        $message->setCc('cc@domain');
    }

    public function testNameCanBeUsedInCcHeader()
    {
        $headers = $this->createHeaderSet([], false);
        $headers->shouldReceive('addMailboxHeader')
                ->once()
                ->with('Cc', ['cc@domain' => 'Name']);
        $headers->shouldReceive('addMailboxHeader')
                ->zeroOrMoreTimes();

        $message = $this->createMessage($headers, $this->createEncoder(),
            $this->createCache()
            );
        $message->setCc('cc@domain', 'Name');
    }

    public function testBccIsReturnedFromHeader()
    {
        /* -- RFC 2822, 3.6.3.
     */

        $bcc = $this->createHeader('Bcc', ['bcc@domain' => 'Name']);
        $message = $this->createMessage(
            $this->createHeaderSet(['Bcc' => $bcc]),
            $this->createEncoder(), $this->createCache()
            );
        $this->assertEquals(['bcc@domain' => 'Name'], $message->getBcc());
    }

    public function testBccIsSetInHeader()
    {
        $bcc = $this->createHeader('Bcc', ['bcc@domain' => 'Name'],
            [], false
            );
        $bcc->shouldReceive('setFieldBodyModel')
            ->once()
            ->with(['other@domain' => 'Other']);

        $message = $this->createMessage(
            $this->createHeaderSet(['Bcc' => $bcc]),
            $this->createEncoder(), $this->createCache()
            );
        $message->setBcc(['other@domain' => 'Other']);
    }

    public function testBccIsAddedToHeadersDuringAddBcc()
    {
        $bcc = $this->createHeader('Bcc', ['from@domain' => 'Name'],
            [], false
            );
        $bcc->shouldReceive('setFieldBodyModel')
            ->once()
            ->with(['from@domain' => 'Name', 'other@domain' => 'Other']);

        $message = $this->createMessage(
            $this->createHeaderSet(['Bcc' => $bcc]),
            $this->createEncoder(), $this->createCache()
            );
        $message->addBcc('other@domain', 'Other');
    }

    public function testBccHeaderIsAddedIfNoneSet()
    {
        $headers = $this->createHeaderSet([], false);
        $headers->shouldReceive('addMailboxHeader')
                ->once()
                ->with('Bcc', (array) 'bcc@domain');
        $headers->shouldReceive('addMailboxHeader')
                ->zeroOrMoreTimes();

        $message = $this->createMessage($headers, $this->createEncoder(),
            $this->createCache()
            );
        $message->setBcc('bcc@domain');
    }

    public function testNameCanBeUsedInBcc()
    {
        $headers = $this->createHeaderSet([], false);
        $headers->shouldReceive('addMailboxHeader')
                ->once()
                ->with('Bcc', ['bcc@domain' => 'Name']);
        $headers->shouldReceive('addMailboxHeader')
                ->zeroOrMoreTimes();

        $message = $this->createMessage($headers, $this->createEncoder(),
            $this->createCache()
            );
        $message->setBcc('bcc@domain', 'Name');
    }

    public function testPriorityIsReadFromHeader()
    {
        $prio = $this->createHeader('X-Priority', '2 (High)');
        $message = $this->createMessage(
            $this->createHeaderSet(['X-Priority' => $prio]),
            $this->createEncoder(), $this->createCache()
            );
        $this->assertEquals(2, $message->getPriority());
    }

    public function testPriorityIsSetInHeader()
    {
        $prio = $this->createHeader('X-Priority', '2 (High)', [], false);
        $prio->shouldReceive('setFieldBodyModel')
             ->once()
             ->with('5 (Lowest)');

        $message = $this->createMessage(
            $this->createHeaderSet(['X-Priority' => $prio]),
            $this->createEncoder(), $this->createCache()
            );
        $message->setPriority($message::PRIORITY_LOWEST);
    }

    public function testPriorityHeaderIsAddedIfNoneSet()
    {
        $headers = $this->createHeaderSet([], false);
        $headers->shouldReceive('addTextHeader')
                ->once()
                ->with('X-Priority', '4 (Low)');
        $headers->shouldReceive('addTextHeader')
                ->zeroOrMoreTimes();

        $message = $this->createMessage($headers, $this->createEncoder(),
            $this->createCache()
            );
        $message->setPriority($message::PRIORITY_LOW);
    }

    public function testReadReceiptAddressReadFromHeader()
    {
        $rcpt = $this->createHeader('Disposition-Notification-To',
            ['chris@swiftmailer.org' => 'Chris']
            );
        $message = $this->createMessage(
            $this->createHeaderSet(['Disposition-Notification-To' => $rcpt]),
            $this->createEncoder(), $this->createCache()
            );
        $this->assertEquals(['chris@swiftmailer.org' => 'Chris'],
            $message->getReadReceiptTo()
            );
    }

    public function testReadReceiptIsSetInHeader()
    {
        $rcpt = $this->createHeader('Disposition-Notification-To', [], [], false);
        $rcpt->shouldReceive('setFieldBodyModel')
             ->once()
             ->with('mark@swiftmailer.org');

        $message = $this->createMessage(
            $this->createHeaderSet(['Disposition-Notification-To' => $rcpt]),
            $this->createEncoder(), $this->createCache()
            );
        $message->setReadReceiptTo('mark@swiftmailer.org');
    }

    public function testReadReceiptHeaderIsAddedIfNoneSet()
    {
        $headers = $this->createHeaderSet([], false);
        $headers->shouldReceive('addMailboxHeader')
                ->once()
                ->with('Disposition-Notification-To', 'mark@swiftmailer.org');
        $headers->shouldReceive('addMailboxHeader')
                ->zeroOrMoreTimes();

        $message = $this->createMessage($headers, $this->createEncoder(),
            $this->createCache()
            );
        $message->setReadReceiptTo('mark@swiftmailer.org');
    }

    public function testChildrenCanBeAttached()
    {
        $child1 = $this->createChild();
        $child2 = $this->createChild();

        $message = $this->createMessage($this->createHeaderSet(),
            $this->createEncoder(), $this->createCache()
            );

        $message->attach($child1);
        $message->attach($child2);

        $this->assertEquals([$child1, $child2], $message->getChildren());
    }

    public function testChildrenCanBeDetached()
    {
        $child1 = $this->createChild();
        $child2 = $this->createChild();

        $message = $this->createMessage($this->createHeaderSet(),
            $this->createEncoder(), $this->createCache()
            );

        $message->attach($child1);
        $message->attach($child2);

        $message->detach($child1);

        $this->assertEquals([$child2], $message->getChildren());
    }

    public function testEmbedAttachesChild()
    {
        $child = $this->createChild();

        $message = $this->createMessage($this->createHeaderSet(),
            $this->createEncoder(), $this->createCache()
            );

        $message->embed($child);

        $this->assertEquals([$child], $message->getChildren());
    }

    public function testEmbedReturnsValidCid()
    {
        $child = $this->createChild(Swift_Mime_SimpleMimeEntity::LEVEL_RELATED, '',
            false
            );
        $child->shouldReceive('getId')
              ->zeroOrMoreTimes()
              ->andReturn('foo@bar');

        $message = $this->createMessage($this->createHeaderSet(),
            $this->createEncoder(), $this->createCache()
            );

        $this->assertEquals('cid:foo@bar', $message->embed($child));
    }

    public function testFluidInterface()
    {
        $child = $this->createChild();
        $message = $this->createMessage($this->createHeaderSet(),
            $this->createEncoder(), $this->createCache()
            );
        $this->assertSame($message,
            $message
            ->setContentType('text/plain')
            ->setEncoder($this->createEncoder())
            ->setId('foo@bar')
            ->setDescription('my description')
            ->setMaxLineLength(998)
            ->setBody('xx')
            ->setBoundary('xyz')
            ->setChildren([])
            ->setCharset('iso-8859-1')
            ->setFormat('flowed')
            ->setDelSp(false)
            ->setSubject('subj')
            ->setDate(new DateTimeImmutable())
            ->setReturnPath('foo@bar')
            ->setSender('foo@bar')
            ->setFrom(['x@y' => 'XY'])
            ->setReplyTo(['ab@cd' => 'ABCD'])
            ->setTo(['chris@site.tld', 'mark@site.tld'])
            ->setCc('john@somewhere.tld')
            ->setBcc(['one@site', 'two@site' => 'Two'])
            ->setPriority($message::PRIORITY_LOW)
            ->setReadReceiptTo('a@b')
            ->attach($child)
            ->detach($child)
            );
    }

    //abstract
    protected function createEntity($headers, $encoder, $cache)
    {
        return $this->createMessage($headers, $encoder, $cache);
    }

    protected function createMimePart($headers, $encoder, $cache)
    {
        return $this->createMessage($headers, $encoder, $cache);
    }

    private function createMessage($headers, $encoder, $cache)
    {
        $idGenerator = new Swift_Mime_IdGenerator('example.com');

        return new Swift_Mime_SimpleMessage($headers, $encoder, $cache, $idGenerator);
    }
}


================================================
FILE: tests/unit/Swift/Mime/SimpleMimeEntityTest.php
================================================
<?php

class Swift_Mime_SimpleMimeEntityTest extends Swift_Mime_AbstractMimeEntityTest
{
    protected function createEntity($headerFactory, $encoder, $cache)
    {
        $idGenerator = new Swift_Mime_IdGenerator('example.com');

        return new Swift_Mime_SimpleMimeEntity($headerFactory, $encoder, $cache, $idGenerator);
    }
}


================================================
FILE: tests/unit/Swift/Plugins/AntiFloodPluginTest.php
================================================
<?php

class Swift_Plugins_AntiFloodPluginTest extends \PHPUnit\Framework\TestCase
{
    public function testThresholdCanBeSetAndFetched()
    {
        $plugin = new Swift_Plugins_AntiFloodPlugin(10);
        $this->assertEquals(10, $plugin->getThreshold());
        $plugin->setThreshold(100);
        $this->assertEquals(100, $plugin->getThreshold());
    }

    public function testSleepTimeCanBeSetAndFetched()
    {
        $plugin = new Swift_Plugins_AntiFloodPlugin(10, 5);
        $this->assertEquals(5, $plugin->getSleepTime());
        $plugin->setSleepTime(1);
        $this->assertEquals(1, $plugin->getSleepTime());
    }

    public function testPluginStopsConnectionAfterThreshold()
    {
        $transport = $this->createTransport();
        $transport->expects($this->once())
                  ->method('start');
        $transport->expects($this->once())
                  ->method('stop');

        $evt = $this->createSendEvent($transport);

        $plugin = new Swift_Plugins_AntiFloodPlugin(10);
        for ($i = 0; $i < 12; ++$i) {
            $plugin->sendPerformed($evt);
        }
    }

    public function testPluginCanStopAndStartMultipleTimes()
    {
        $transport = $this->createTransport();
        $transport->expects($this->exactly(5))
                  ->method('start');
        $transport->expects($this->exactly(5))
                  ->method('stop');

        $evt = $this->createSendEvent($transport);

        $plugin = new Swift_Plugins_AntiFloodPlugin(2);
        for ($i = 0; $i < 11; ++$i) {
            $plugin->sendPerformed($evt);
        }
    }

    public function testPluginCanSleepDuringRestart()
    {
        $sleeper = $this->getMockBuilder('Swift_Plugins_Sleeper')->getMock();
        $sleeper->expects($this->once())
                ->method('sleep')
                ->with(10);

        $transport = $this->createTransport();
        $transport->expects($this->once())
                  ->method('start');
        $transport->expects($this->once())
                  ->method('stop');

        $evt = $this->createSendEvent($transport);

        $plugin = new Swift_Plugins_AntiFloodPlugin(99, 10, $sleeper);
        for ($i = 0; $i < 101; ++$i) {
            $plugin->sendPerformed($evt);
        }
    }

    private function createTransport()
    {
        return $this->getMockBuilder('Swift_Transport')->getMock();
    }

    private function createSendEvent($transport)
    {
        $evt = $this->getMockBuilder('Swift_Events_SendEvent')
                    ->disableOriginalConstructor()
                    ->getMock();
        $evt->expects($this->any())
            ->method('getSource')
            ->willReturn($transport);
        $evt->expects($this->any())
            ->method('getTransport')
            ->willReturn($transport);

        return $evt;
    }
}


================================================
FILE: tests/unit/Swift/Plugins/BandwidthMonitorPluginTest.php
================================================
<?php

class Swift_Plugins_BandwidthMonitorPluginTest extends \PHPUnit\Framework\TestCase
{
    private $monitor;

    private $bytes = 0;

    protected function setUp()
    {
        $this->monitor = new Swift_Plugins_BandwidthMonitorPlugin();
    }

    public function testBytesOutIncreasesWhenCommandsSent()
    {
        $evt = $this->createCommandEvent("RCPT TO:<foo@bar.com>\r\n");

        $this->assertEquals(0, $this->monitor->getBytesOut());
        $this->monitor->commandSent($evt);
        $this->assertEquals(23, $this->monitor->getBytesOut());
        $this->monitor->commandSent($evt);
        $this->assertEquals(46, $this->monitor->getBytesOut());
    }

    public function testBytesInIncreasesWhenResponsesReceived()
    {
        $evt = $this->createResponseEvent("250 Ok\r\n");

        $this->assertEquals(0, $this->monitor->getBytesIn());
        $this->monitor->responseReceived($evt);
        $this->assertEquals(8, $this->monitor->getBytesIn());
        $this->monitor->responseReceived($evt);
        $this->assertEquals(16, $this->monitor->getBytesIn());
    }

    public function testCountersCanBeReset()
    {
        $evt = $this->createResponseEvent("250 Ok\r\n");

        $this->assertEquals(0, $this->monitor->getBytesIn());
        $this->monitor->responseReceived($evt);
        $this->assertEquals(8, $this->monitor->getBytesIn());
        $this->monitor->responseReceived($evt);
        $this->assertEquals(16, $this->monitor->getBytesIn());

        $evt = $this->createCommandEvent("RCPT TO:<foo@bar.com>\r\n");

        $this->assertEquals(0, $this->monitor->getBytesOut());
        $this->monitor->commandSent($evt);
        $this->assertEquals(23, $this->monitor->getBytesOut());
        $this->monitor->commandSent($evt);
        $this->assertEquals(46, $this->monitor->getBytesOut());

        $this->monitor->reset();

        $this->assertEquals(0, $this->monitor->getBytesOut());
        $this->assertEquals(0, $this->monitor->getBytesIn());
    }

    public function testBytesOutIncreasesAccordingToMessageLength()
    {
        $message = $this->createMessageWithByteCount(6);
        $evt = $this->createSendEvent($message);

        $this->assertEquals(0, $this->monitor->getBytesOut());
        $this->monitor->sendPerformed($evt);
        $this->assertEquals(6, $this->monitor->getBytesOut());
        $this->monitor->sendPerformed($evt);
        $this->assertEquals(12, $this->monitor->getBytesOut());
    }

    private function createSendEvent($message)
    {
        $evt = $this->getMockBuilder('Swift_Events_SendEvent')
                    ->disableOriginalConstructor()
                    ->getMock();
        $evt->expects($this->any())
            ->method('getMessage')
            ->willReturn($message);

        return $evt;
    }

    private function createCommandEvent($command)
    {
        $evt = $this->getMockBuilder('Swift_Events_CommandEvent')
                    ->disableOriginalConstructor()
                    ->getMock();
        $evt->expects($this->any())
            ->method('getCommand')
            ->willReturn($command);

        return $evt;
    }

    private function createResponseEvent($response)
    {
        $evt = $this->getMockBuilder('Swift_Events_ResponseEvent')
                    ->disableOriginalConstructor()
                    ->getMock();
        $evt->expects($this->any())
            ->method('getResponse')
            ->willReturn($response);

        return $evt;
    }

    private function createMessageWithByteCount($bytes)
    {
        $this->bytes = $bytes;
        $msg = $this->getMockBuilder('Swift_Mime_SimpleMessage')->disableOriginalConstructor()->getMock();
        $msg->expects($this->any())
            ->method('toByteStream')
            ->willReturnCallback([$this, 'write']);
        /*  $this->checking(Expectations::create()
              -> ignoring($msg)->toByteStream(any()) -> calls(array($this, 'write'))
          ); */

        return $msg;
    }

    public function write($is)
    {
        for ($i = 0; $i < $this->bytes; ++$i) {
            $is->write('x');
        }
    }
}


================================================
FILE: tests/unit/Swift/Plugins/DecoratorPluginTest.php
================================================
<?php

class Swift_Plugins_DecoratorPluginTest extends \SwiftMailerTestCase
{
    public function testMessageBodyReceivesReplacements()
    {
        $message = $this->createMessage(
            $this->createHeaders(),
            ['zip@button.tld' => 'Zipathon'],
            ['chris.corbyn@swiftmailer.org' => 'Chris'],
            'Subject',
            'Hello {name}, you are customer #{id}'
            );
        $message->shouldReceive('setBody')
                ->once()
                ->with('Hello Zip, you are customer #456');
        $message->shouldReceive('setBody')
                ->zeroOrMoreTimes();

        $plugin = $this->createPlugin(
            ['zip@button.tld' => ['{name}' => 'Zip', '{id}' => '456']]
            );

        $evt = $this->createSendEvent($message);

        $plugin->beforeSendPerformed($evt);
        $plugin->sendPerformed($evt);
    }

    public function testReplacementsCanBeAppliedToSameMessageMultipleTimes()
    {
        $message = $this->createMessage(
            $this->createHeaders(),
            ['zip@button.tld' => 'Zipathon', 'foo@bar.tld' => 'Foo'],
            ['chris.corbyn@swiftmailer.org' => 'Chris'],
            'Subject',
            'Hello {name}, you are customer #{id}'
            );
        $message->shouldReceive('setBody')
                ->once()
                ->with('Hello Zip, you are customer #456');
        $message->shouldReceive('setBody')
                ->once()
                ->with('Hello {name}, you are customer #{id}');
        $message->shouldReceive('setBody')
                ->once()
                ->with('Hello Foo, you are customer #123');
        $message->shouldReceive('setBody')
                ->zeroOrMoreTimes();

        $plugin = $this->createPlugin(
            [
                'foo@bar.tld' => ['{name}' => 'Foo', '{id}' => '123'],
                'zip@button.tld' => ['{name}' => 'Zip', '{id}' => '456'],
                ]
            );

        $evt = $this->createSendEvent($message);

        $plugin->beforeSendPerformed($evt);
        $plugin->sendPerformed($evt);
        $plugin->beforeSendPerformed($evt);
        $plugin->sendPerformed($evt);
    }

    public function testReplacementsCanBeMadeInHeaders()
    {
        $headers = $this->createHeaders([
            $returnPathHeader = $this->createHeader('Return-Path', 'foo-{id}@swiftmailer.org'),
            $toHeader = $this->createHeader('Subject', 'A message for {name}!'),
        ]);

        $message = $this->createMessage(
            $headers,
            ['zip@button.tld' => 'Zipathon'],
            ['chris.corbyn@swiftmailer.org' => 'Chris'],
            'A message for {name}!',
            'Hello {name}, you are customer #{id}'
            );

        $message->shouldReceive('setBody')
                ->once()
                ->with('Hello Zip, you are customer #456');
        $toHeader->shouldReceive('setFieldBodyModel')
                 ->once()
                 ->with('A message for Zip!');
        $returnPathHeader->shouldReceive('setFieldBodyModel')
                         ->once()
                         ->with('foo-456@swiftmailer.org');
        $message->shouldReceive('setBody')
                ->zeroOrMoreTimes();
        $toHeader->shouldReceive('setFieldBodyModel')
                 ->zeroOrMoreTimes();
        $returnPathHeader->shouldReceive('setFieldBodyModel')
                         ->zeroOrMoreTimes();

        $plugin = $this->createPlugin(
            ['zip@button.tld' => ['{name}' => 'Zip', '{id}' => '456']]
            );
        $evt = $this->createSendEvent($message);

        $plugin->beforeSendPerformed($evt);
        $plugin->sendPerformed($evt);
    }

    public function testReplacementsAreMadeOnSubparts()
    {
        $part1 = $this->createPart('text/plain', 'Your name is {name}?', '1@x');
        $part2 = $this->createPart('text/html', 'Your <em>name</em> is {name}?', '2@x');
        $message = $this->createMessage(
            $this->createHeaders(),
            ['zip@button.tld' => 'Zipathon'],
            ['chris.corbyn@swiftmailer.org' => 'Chris'],
            'A message for {name}!',
            'Subject'
            );
        $message->shouldReceive('getChildren')
                ->zeroOrMoreTimes()
                ->andReturn([$part1, $part2]);
        $part1->shouldReceive('setBody')
              ->once()
              ->with('Your name is Zip?');
        $part2->shouldReceive('setBody')
              ->once()
              ->with('Your <em>name</em> is Zip?');
        $part1->shouldReceive('setBody')
              ->zeroOrMoreTimes();
        $part2->shouldReceive('setBody')
              ->zeroOrMoreTimes();

        $plugin = $this->createPlugin(
            ['zip@button.tld' => ['{name}' => 'Zip', '{id}' => '456']]
            );

        $evt = $this->createSendEvent($message);

        $plugin->beforeSendPerformed($evt);
        $plugin->sendPerformed($evt);
    }

    public function testReplacementsCanBeTakenFromCustomReplacementsObject()
    {
        $message = $this->createMessage(
            $this->createHeaders(),
            ['foo@bar' => 'Foobar', 'zip@zap' => 'Zip zap'],
            ['chris.corbyn@swiftmailer.org' => 'Chris'],
            'Subject',
            'Something {a}'
            );

        $replacements = $this->createReplacements();

        $message->shouldReceive('setBody')
                ->once()
                ->with('Something b');
        $message->shouldReceive('setBody')
                ->once()
                ->with('Something c');
        $message->shouldReceive('setBody')
                ->zeroOrMoreTimes();
        $replacements->shouldReceive('getReplacementsFor')
                     ->once()
                     ->with('foo@bar')
                     ->andReturn(['{a}' => 'b']);
        $replacements->shouldReceive('getReplacementsFor')
                     ->once()
                     ->with('zip@zap')
                     ->andReturn(['{a}' => 'c']);

        $plugin = $this->createPlugin($replacements);

        $evt = $this->createSendEvent($message);

        $plugin->beforeSendPerformed($evt);
        $plugin->sendPerformed($evt);
        $plugin->beforeSendPerformed($evt);
        $plugin->sendPerformed($evt);
    }

    public function testReplacementsWithAMessageWithImmutableDate()
    {
        $message = (new Swift_Message('subject foo'))
            ->setBody('body foo')
            ->addTo('somebody@hostname.tld')
            ->addFrom('somebody@hostname.tld');

        $evt = $this->createSendEvent($message);

        $plugin = $this->createPlugin(['somebody@hostname.tld' => ['foo' => 'bar']]);

        $plugin->beforeSendPerformed($evt);

        $this->assertEquals('subject bar', $message->getSubject());
        $this->assertEquals('body bar', $message->getBody());
    }

    private function createMessage($headers, $to = [], $from = null, $subject = null,
        $body = null)
    {
        $message = $this->getMockery('Swift_Mime_SimpleMessage')->shouldIgnoreMissing();
        foreach ($to as $addr => $name) {
            $message->shouldReceive('getTo')
                    ->once()
                    ->andReturn([$addr => $name]);
        }
        $message->shouldReceive('getHeaders')
                ->zeroOrMoreTimes()
                ->andReturn($headers);
        $message->shouldReceive('getFrom')
                ->zeroOrMoreTimes()
                ->andReturn($from);
        $message->shouldReceive('getSubject')
                ->zeroOrMoreTimes()
                ->andReturn($subject);
        $message->shouldReceive('getBody')
                ->zeroOrMoreTimes()
                ->andReturn($body);

        return $message;
    }

    private function createPlugin($replacements)
    {
        return new Swift_Plugins_DecoratorPlugin($replacements);
    }

    private function createReplacements()
    {
        return $this->getMockery('Swift_Plugins_Decorator_Replacements')->shouldIgnoreMissing();
    }

    private function createSendEvent(Swift_Mime_SimpleMessage $message)
    {
        $evt = $this->getMockery('Swift_Events_SendEvent')->shouldIgnoreMissing();
        $evt->shouldReceive('getMessage')
            ->zeroOrMoreTimes()
            ->andReturn($message);

        return $evt;
    }

    private function createPart($type, $body, $id)
    {
        $part = $this->getMockery('Swift_Mime_SimpleMimeEntity')->shouldIgnoreMissing();
        $part->shouldReceive('getContentType')
             ->zeroOrMoreTimes()
             ->andReturn($type);
        $part->shouldReceive('getBody')
             ->zeroOrMoreTimes()
             ->andReturn($body);
        $part->shouldReceive('getId')
             ->zeroOrMoreTimes()
             ->andReturn($id);

        return $part;
    }

    private function createHeaders($headers = [])
    {
        $set = $this->getMockery('Swift_Mime_SimpleHeaderSet')->shouldIgnoreMissing();
        $set->shouldReceive('getAll')
            ->zeroOrMoreTimes()
            ->andReturn($headers);

        foreach ($headers as $header) {
            $set->set($header);
        }

        return $set;
    }

    private function createHeader($name, $body = '')
    {
        $header = $this->getMockery('Swift_Mime_Header')->shouldIgnoreMissing();
        $header->shouldReceive('getFieldName')
               ->zeroOrMoreTimes()
               ->andReturn($name);
        $header->shouldReceive('getFieldBodyModel')
               ->zeroOrMoreTimes()
               ->andReturn($body);

        return $header;
    }
}


================================================
FILE: tests/unit/Swift/Plugins/LoggerPluginTest.php
================================================
<?php

class Swift_Plugins_LoggerPluginTest extends \SwiftMailerTestCase
{
    public function testLoggerDelegatesAddingEntries()
    {
        $logger = $this->createLogger();
        $logger->expects($this->once())
               ->method('add')
               ->with('foo');

        $plugin = $this->createPlugin($logger);
        $plugin->add('foo');
    }

    public function testLoggerDelegatesDumpingEntries()
    {
        $logger = $this->createLogger();
        $logger->expects($this->once())
               ->method('dump')
               ->willReturn('foobar');

        $plugin = $this->createPlugin($logger);
        $this->assertEquals('foobar', $plugin->dump());
    }

    public function testLoggerDelegatesClearingEntries()
    {
        $logger = $this->createLogger();
        $logger->expects($this->once())
               ->method('clear');

        $plugin = $this->createPlugin($logger);
        $plugin->clear();
    }

    public function testCommandIsSentToLogger()
    {
        $evt = $this->createCommandEvent("foo\r\n");
        $logger = $this->createLogger();
        $logger->expects($this->once())
               ->method('add')
               ->with(static::regExp('~foo\r\n~'));

        $plugin = $this->createPlugin($logger);
        $plugin->commandSent($evt);
    }

    public function testResponseIsSentToLogger()
    {
        $evt = $this->createResponseEvent("354 Go ahead\r\n");
        $logger = $this->createLogger();
        $logger->expects($this->once())
               ->method('add')
               ->with(static::regExp('~354 Go ahead\r\n~'));

        $plugin = $this->createPlugin($logger);
        $plugin->responseReceived($evt);
    }

    public function testTransportBeforeStartChangeIsSentToLogger()
    {
        $evt = $this->createTransportChangeEvent();
        $logger = $this->createLogger();
        $logger->expects($this->once())
               ->method('add')
               ->with($this->anything());

        $plugin = $this->createPlugin($logger);
        $plugin->beforeTransportStarted($evt);
    }

    public function testTransportStartChangeIsSentToLogger()
    {
        $evt = $this->createTransportChangeEvent();
        $logger = $this->createLogger();
        $logger->expects($this->once())
               ->method('add')
               ->with($this->anything());

        $plugin = $this->createPlugin($logger);
        $plugin->transportStarted($evt);
    }

    public function testTransportStopChangeIsSentToLogger()
    {
        $evt = $this->createTransportChangeEvent();
        $logger = $this->createLogger();
        $logger->expects($this->once())
               ->method('add')
               ->with($this->anything());

        $plugin = $this->createPlugin($logger);
        $plugin->transportStopped($evt);
    }

    public function testTransportBeforeStopChangeIsSentToLogger()
    {
        $evt = $this->createTransportChangeEvent();
        $logger = $this->createLogger();
        $logger->expects($this->once())
               ->method('add')
               ->with($this->anything());

        $plugin = $this->createPlugin($logger);
        $plugin->beforeTransportStopped($evt);
    }

    public function testExceptionsArePassedToDelegateAndLeftToBubbleUp()
    {
        $transport = $this->createTransport();
        $evt = $this->createTransportExceptionEvent();
        $logger = $this->createLogger();
        $logger->expects($this->once())
               ->method('add')
               ->with($this->anything());

        $plugin = $this->createPlugin($logger);
        try {
            $plugin->exceptionThrown($evt);
            $this->fail('Exception should bubble up.');
        } catch (Swift_TransportException $ex) {
        }
    }

    private function createLogger()
    {
        return $this->getMockBuilder('Swift_Plugins_Logger')->getMock();
    }

    private function createPlugin($logger)
    {
        return new Swift_Plugins_LoggerPlugin($logger);
    }

    private function createCommandEvent($command)
    {
        $evt = $this->getMockBuilder('Swift_Events_CommandEvent')
                    ->disableOriginalConstructor()
                    ->getMock();
        $evt->expects($this->any())
            ->method('getCommand')
            ->willReturn($command);

        return $evt;
    }

    private function createResponseEvent($response)
    {
        $evt = $this->getMockBuilder('Swift_Events_ResponseEvent')
                    ->disableOriginalConstructor()
                    ->getMock();
        $evt->expects($this->any())
            ->method('getResponse')
            ->willReturn($response);

        return $evt;
    }

    private function createTransport()
    {
        return $this->getMockBuilder('Swift_Transport')->getMock();
    }

    private function createTransportChangeEvent()
    {
        $evt = $this->getMockBuilder('Swift_Events_TransportChangeEvent')
                    ->disableOriginalConstructor()
                    ->getMock();
        $evt->expects($this->any())
            ->method('getSource')
            ->willReturn($this->createTransport());

        return $evt;
    }

    public function createTransportExceptionEvent()
    {
        $evt = $this->getMockBuilder('Swift_Events_TransportExceptionEvent')
                    ->disableOriginalConstructor()
                    ->getMock();
        $evt->expects($this->any())
            ->method('getException')
            ->willReturn(new Swift_TransportException(''));

        return $evt;
    }
}


================================================
FILE: tests/unit/Swift/Plugins/Loggers/ArrayLoggerTest.php
================================================
<?php

class Swift_Plugins_Loggers_ArrayLoggerTest extends \PHPUnit\Framework\TestCase
{
    public function testAddingSingleEntryDumpsSingleLine()
    {
        $logger = new Swift_Plugins_Loggers_ArrayLogger();
        $logger->add(">> Foo\r\n");
        $this->assertEquals(">> Foo\r\n", $logger->dump());
    }

    public function testAddingMultipleEntriesDumpsMultipleLines()
    {
        $logger = new Swift_Plugins_Loggers_ArrayLogger();
        $logger->add(">> FOO\r\n");
        $logger->add("<< 502 That makes no sense\r\n");
        $logger->add(">> RSET\r\n");
        $logger->add("<< 250 OK\r\n");

        $this->assertEquals(
            ">> FOO\r\n".PHP_EOL.
            "<< 502 That makes no sense\r\n".PHP_EOL.
            ">> RSET\r\n".PHP_EOL.
            "<< 250 OK\r\n",
            $logger->dump()
            );
    }

    public function testLogCanBeCleared()
    {
        $logger = new Swift_Plugins_Loggers_ArrayLogger();
        $logger->add(">> FOO\r\n");
        $logger->add("<< 502 That makes no sense\r\n");
        $logger->add(">> RSET\r\n");
        $logger->add("<< 250 OK\r\n");

        $this->assertEquals(
            ">> FOO\r\n".PHP_EOL.
            "<< 502 That makes no sense\r\n".PHP_EOL.
            ">> RSET\r\n".PHP_EOL.
            "<< 250 OK\r\n",
            $logger->dump()
            );

        $logger->clear();

        $this->assertEquals('', $logger->dump());
    }

    public function testLengthCanBeTruncated()
    {
        $logger = new Swift_Plugins_Loggers_ArrayLogger(2);
        $logger->add(">> FOO\r\n");
        $logger->add("<< 502 That makes no sense\r\n");
        $logger->add(">> RSET\r\n");
        $logger->add("<< 250 OK\r\n");

        $this->assertEquals(
            ">> RSET\r\n".PHP_EOL.
            "<< 250 OK\r\n",
            $logger->dump(),
            '%s: Log should be truncated to last 2 entries'
            );
    }
}


================================================
FILE: tests/unit/Swift/Plugins/Loggers/EchoLoggerTest.php
================================================
<?php

class Swift_Plugins_Loggers_EchoLoggerTest extends \PHPUnit\Framework\TestCase
{
    public function testAddingEntryDumpsSingleLineWithoutHtml()
    {
        $logger = new Swift_Plugins_Loggers_EchoLogger(false);
        ob_start();
        $logger->add('>> Foo');
        $data = ob_get_clean();

        $this->assertEquals('>> Foo'.PHP_EOL, $data);
    }

    public function testAddingEntryDumpsEscapedLineWithHtml()
    {
        $logger = new Swift_Plugins_Loggers_EchoLogger(true);
        ob_start();
        $logger->add('>> Foo');
        $data = ob_get_clean();

        $this->assertEquals('&gt;&gt; Foo<br />'.PHP_EOL, $data);
    }
}


================================================
FILE: tests/unit/Swift/Plugins/PopBeforeSmtpPluginTest.php
================================================
<?php

class Swift_Plugins_PopBeforeSmtpPluginTest extends \PHPUnit\Framework\TestCase
{
    public function testPluginConnectsToPop3HostBeforeTransportStarts()
    {
        $connection = $this->createConnection();
        $connection->expects($this->once())
                   ->method('connect');

        $plugin = $this->createPlugin('pop.host.tld', 110);
        $plugin->setConnection($connection);

        $transport = $this->createTransport();
        $evt = $this->createTransportChangeEvent($transport);

        $plugin->beforeTransportStarted($evt);
    }

    public function testPluginDisconnectsFromPop3HostBeforeTransportStarts()
    {
        $connection = $this->createConnection();
        $connection->expects($this->once())
                   ->method('disconnect');

        $plugin = $this->createPlugin('pop.host.tld', 110);
        $plugin->setConnection($connection);

        $transport = $this->createTransport();
        $evt = $this->createTransportChangeEvent($transport);

        $plugin->beforeTransportStarted($evt);
    }

    public function testPluginDoesNotConnectToSmtpIfBoundToDifferentTransport()
    {
        $connection = $this->createConnection();
        $connection->expects($this->never())
                   ->method('disconnect');
        $connection->expects($this->never())
                   ->method('connect');

        $smtp = $this->createTransport();

        $plugin = $this->createPlugin('pop.host.tld', 110);
        $plugin->setConnection($connection);
        $plugin->bindSmtp($smtp);

        $transport = $this->createTransport();
        $evt = $this->createTransportChangeEvent($transport);

        $plugin->beforeTransportStarted($evt);
    }

    public function testPluginCanBindToSpecificTransport()
    {
        $connection = $this->createConnection();
        $connection->expects($this->once())
                   ->method('connect');

        $smtp = $this->createTransport();

        $plugin = $this->createPlugin('pop.host.tld', 110);
        $plugin->setConnection($connection);
        $plugin->bindSmtp($smtp);

        $evt = $this->createTransportChangeEvent($smtp);

        $plugin->beforeTransportStarted($evt);
    }

    private function createTransport()
    {
        return $this->getMockBuilder('Swift_Transport')->getMock();
    }

    private function createTransportChangeEvent($transport)
    {
        $evt = $this->getMockBuilder('Swift_Events_TransportChangeEvent')
                    ->disableOriginalConstructor()
                    ->getMock();
        $evt->expects($this->any())
            ->method('getSource')
            ->willReturn($transport);
        $evt->expects($this->any())
            ->method('getTransport')
            ->willReturn($transport);

        return $evt;
    }

    public function createConnection()
    {
        return $this->getMockBuilder('Swift_Plugins_Pop_Pop3Connection')->getMock();
    }

    public function createPlugin($host, $port, $crypto = null)
    {
        return new Swift_Plugins_PopBeforeSmtpPlugin($host, $port, $crypto);
    }
}


================================================
FILE: tests/unit/Swift/Plugins/RedirectingPluginTest.php
================================================
<?php

class Swift_Plugins_RedirectingPluginTest extends \PHPUnit\Framework\TestCase
{
    public function testRecipientCanBeSetAndFetched()
    {
        $plugin = new Swift_Plugins_RedirectingPlugin('fabien@example.com');
        $this->assertEquals('fabien@example.com', $plugin->getRecipient());
        $plugin->setRecipient('chris@example.com');
        $this->assertEquals('chris@example.com', $plugin->getRecipient());
    }

    public function testPluginChangesRecipients()
    {
        $message = (new Swift_Message())
            ->setSubject('...')
            ->setFrom(['john@example.com' => 'John Doe'])
            ->setTo($to = [
                'fabien-to@example.com' => 'Fabien (To)',
                'chris-to@example.com' => 'Chris (To)',
            ])
            ->setCc($cc = [
                'fabien-cc@example.com' => 'Fabien (Cc)',
                'chris-cc@example.com' => 'Chris (Cc)',
            ])
            ->setBcc($bcc = [
                'fabien-bcc@example.com' => 'Fabien (Bcc)',
                'chris-bcc@example.com' => 'Chris (Bcc)',
            ])
            ->setBody('...')
        ;

        $plugin = new Swift_Plugins_RedirectingPlugin('god@example.com');

        $evt = $this->createSendEvent($message);

        $plugin->beforeSendPerformed($evt);

        $this->assertEquals($message->getTo(), ['god@example.com' => '']);
        $this->assertEquals($message->getCc(), []);
        $this->assertEquals($message->getBcc(), []);

        $plugin->sendPerformed($evt);

        $this->assertEquals($message->getTo(), $to);
        $this->assertEquals($message->getCc(), $cc);
        $this->assertEquals($message->getBcc(), $bcc);
    }

    public function testPluginRespectsUnsetToList()
    {
        $message = (new Swift_Message())
            ->setSubject('...')
            ->setFrom(['john@example.com' => 'John Doe'])
            ->setCc($cc = [
                'fabien-cc@example.com' => 'Fabien (Cc)',
                'chris-cc@example.com' => 'Chris (Cc)',
            ])
            ->setBcc($bcc = [
                'fabien-bcc@example.com' => 'Fabien (Bcc)',
                'chris-bcc@example.com' => 'Chris (Bcc)',
            ])
            ->setBody('...')
        ;

        $plugin = new Swift_Plugins_RedirectingPlugin('god@example.com');

        $evt = $this->createSendEvent($message);

        $plugin->beforeSendPerformed($evt);

        $this->assertEquals($message->getTo(), ['god@example.com' => '']);
        $this->assertEquals($message->getCc(), []);
        $this->assertEquals($message->getBcc(), []);

        $plugin->sendPerformed($evt);

        $this->assertEquals($message->getTo(), []);
        $this->assertEquals($message->getCc(), $cc);
        $this->assertEquals($message->getBcc(), $bcc);
    }

    public function testPluginRespectsAWhitelistOfPatterns()
    {
        $message = (new Swift_Message())
            ->setSubject('...')
            ->setFrom(['john@example.com' => 'John Doe'])
            ->setTo($to = [
                'fabien-to@example.com' => 'Fabien (To)',
                'chris-to@example.com' => 'Chris (To)',
                'lars-to@internal.com' => 'Lars (To)',
            ])
            ->setCc($cc = [
                'fabien-cc@example.com' => 'Fabien (Cc)',
                'chris-cc@example.com' => 'Chris (Cc)',
                'lars-cc@internal.org' => 'Lars (Cc)',
            ])
            ->setBcc($bcc = [
                'fabien-bcc@example.com' => 'Fabien (Bcc)',
                'chris-bcc@example.com' => 'Chris (Bcc)',
                'john-bcc@example.org' => 'John (Bcc)',
            ])
            ->setBody('...')
        ;

        $recipient = 'god@example.com';
        $patterns = ['/^.*@internal.[a-z]+$/', '/^john-.*$/'];

        $plugin = new Swift_Plugins_RedirectingPlugin($recipient, $patterns);

        $this->assertEquals($recipient, $plugin->getRecipient());
        $this->assertEquals($plugin->getWhitelist(), $patterns);

        $evt = $this->createSendEvent($message);

        $plugin->beforeSendPerformed($evt);

        $this->assertEquals($message->getTo(), ['lars-to@internal.com' => 'Lars (To)', 'god@example.com' => null]);
        $this->assertEquals($message->getCc(), ['lars-cc@internal.org' => 'Lars (Cc)']);
        $this->assertEquals($message->getBcc(), ['john-bcc@example.org' => 'John (Bcc)']);

        $plugin->sendPerformed($evt);

        $this->assertEquals($message->getTo(), $to);
        $this->assertEquals($message->getCc(), $cc);
        $this->assertEquals($message->getBcc(), $bcc);
    }

    public function testArrayOfRecipientsCanBeExplicitlyDefined()
    {
        $message = (new Swift_Message())
            ->setSubject('...')
            ->setFrom(['john@example.com' => 'John Doe'])
            ->setTo([
            'fabien@example.com' => 'Fabien',
            'chris@example.com' => 'Chris (To)',
            'lars-to@internal.com' => 'Lars (To)',
        ])
            ->setCc([
            'fabien@example.com' => 'Fabien',
            'chris-cc@example.com' => 'Chris (Cc)',
            'lars-cc@internal.org' => 'Lars (Cc)',
        ])
            ->setBcc([
            'fabien@example.com' => 'Fabien',
            'chris-bcc@example.com' => 'Chris (Bcc)',
            'john-bcc@example.org' => 'John (Bcc)',
        ])
            ->setBody('...')
        ;

        $recipients = ['god@example.com', 'fabien@example.com'];
        $patterns = ['/^.*@internal.[a-z]+$/'];

        $plugin = new Swift_Plugins_RedirectingPlugin($recipients, $patterns);

        $evt = $this->createSendEvent($message);

        $plugin->beforeSendPerformed($evt);

        $this->assertEquals(
            $message->getTo(),
            ['fabien@example.com' => 'Fabien', 'lars-to@internal.com' => 'Lars (To)', 'god@example.com' => null]
        );
        $this->assertEquals(
            $message->getCc(),
            ['fabien@example.com' => 'Fabien', 'lars-cc@internal.org' => 'Lars (Cc)']
        );
        $this->assertEquals($message->getBcc(), ['fabien@example.com' => 'Fabien']);
    }

    private function createSendEvent(Swift_Mime_SimpleMessage $message)
    {
        $evt = $this->getMockBuilder('Swift_Events_SendEvent')
                    ->disableOriginalConstructor()
                    ->getMock();
        $evt->expects($this->any())
            ->method('getMessage')
            ->willReturn($message);

        return $evt;
    }
}


================================================
FILE: tests/unit/Swift/Plugins/ReporterPluginTest.php
================================================
<?php

class Swift_Plugins_ReporterPluginTest extends \SwiftMailerTestCase
{
    public function testReportingPasses()
    {
        $message = $this->createMessage();
        $evt = $this->createSendEvent();
        $reporter = $this->createReporter();

        $message->shouldReceive('getTo')->zeroOrMoreTimes()->andReturn(['foo@bar.tld' => 'Foo']);
        $evt->shouldReceive('getMessage')->zeroOrMoreTimes()->andReturn($message);
        $evt->shouldReceive('getFailedRecipients')->zeroOrMoreTimes()->andReturn([]);
        $reporter->shouldReceive('notify')->once()->with($message, 'foo@bar.tld', Swift_Plugins_Reporter::RESULT_PASS);

        $plugin = new Swift_Plugins_ReporterPlugin($reporter);
        $plugin->sendPerformed($evt);
    }

    public function testReportingFailedTo()
    {
        $message = $this->createMessage();
        $evt = $this->createSendEvent();
        $reporter = $this->createReporter();

        $message->shouldReceive('getTo')->zeroOrMoreTimes()->andReturn(['foo@bar.tld' => 'Foo', 'zip@button' => 'Zip']);
        $evt->shouldReceive('getMessage')->zeroOrMoreTimes()->andReturn($message);
        $evt->shouldReceive('getFailedRecipients')->zeroOrMoreTimes()->andReturn(['zip@button']);
        $reporter->shouldReceive('notify')->once()->with($message, 'foo@bar.tld', Swift_Plugins_Reporter::RESULT_PASS);
        $reporter->shouldReceive('notify')->once()->with($message, 'zip@button', Swift_Plugins_Reporter::RESULT_FAIL);

        $plugin = new Swift_Plugins_ReporterPlugin($reporter);
        $plugin->sendPerformed($evt);
    }

    public function testReportingFailedCc()
    {
        $message = $this->createMessage();
        $evt = $this->createSendEvent();
        $reporter = $this->createReporter();

        $message->shouldReceive('getTo')->zeroOrMoreTimes()->andReturn(['foo@bar.tld' => 'Foo']);
        $message->shouldReceive('getCc')->zeroOrMoreTimes()->andReturn(['zip@button' => 'Zip', 'test@test.com' => 'Test']);
        $evt->shouldReceive('getMessage')->zeroOrMoreTimes()->andReturn($message);
        $evt->shouldReceive('getFailedRecipients')->zeroOrMoreTimes()->andReturn(['zip@button']);
        $reporter->shouldReceive('notify')->once()->with($message, 'foo@bar.tld', Swift_Plugins_Reporter::RESULT_PASS);
        $reporter->shouldReceive('notify')->once()->with($message, 'zip@button', Swift_Plugins_Reporter::RESULT_FAIL);
        $reporter->shouldReceive('notify')->once()->with($message, 'test@test.com', Swift_Plugins_Reporter::RESULT_PASS);

        $plugin = new Swift_Plugins_ReporterPlugin($reporter);
        $plugin->sendPerformed($evt);
    }

    public function testReportingFailedBcc()
    {
        $message = $this->createMessage();
        $evt = $this->createSendEvent();
        $reporter = $this->createReporter();

        $message->shouldReceive('getTo')->zeroOrMoreTimes()->andReturn(['foo@bar.tld' => 'Foo']);
        $message->shouldReceive('getBcc')->zeroOrMoreTimes()->andReturn(['zip@button' => 'Zip', 'test@test.com' => 'Test']);
        $evt->shouldReceive('getMessage')->zeroOrMoreTimes()->andReturn($message);
        $evt->shouldReceive('getFailedRecipients')->zeroOrMoreTimes()->andReturn(['zip@button']);
        $reporter->shouldReceive('notify')->once()->with($message, 'foo@bar.tld', Swift_Plugins_Reporter::RESULT_PASS);
        $reporter->shouldReceive('notify')->once()->with($message, 'zip@button', Swift_Plugins_Reporter::RESULT_FAIL);
        $reporter->shouldReceive('notify')->once()->with($message, 'test@test.com', Swift_Plugins_Reporter::RESULT_PASS);

        $plugin = new Swift_Plugins_ReporterPlugin($reporter);
        $plugin->sendPerformed($evt);
    }

    private function createMessage()
    {
        return $this->getMockery('Swift_Mime_SimpleMessage')->shouldIgnoreMissing();
    }

    private function createSendEvent()
    {
        return $this->getMockery('Swift_Events_SendEvent')->shouldIgnoreMissing();
    }

    private function createReporter()
    {
        return $this->getMockery('Swift_Plugins_Reporter')->shouldIgnoreMissing();
    }
}


================================================
FILE: tests/unit/Swift/Plugins/Reporters/HitReporterTest.php
================================================
<?php

class Swift_Plugins_Reporters_HitReporterTest extends \PHPUnit\Framework\TestCase
{
    private $hitReporter;
    private $message;

    protected function setUp()
    {
        $this->hitReporter = new Swift_Plugins_Reporters_HitReporter();
        $this->message = $this->getMockBuilder('Swift_Mime_SimpleMessage')->disableOriginalConstructor()->getMock();
    }

    public function testReportingFail()
    {
        $this->hitReporter->notify($this->message, 'foo@bar.tld',
            Swift_Plugins_Reporter::RESULT_FAIL
            );
        $this->assertEquals(['foo@bar.tld'],
            $this->hitReporter->getFailedRecipients()
            );
    }

    public function testMultipleReports()
    {
        $this->hitReporter->notify($this->message, 'foo@bar.tld',
            Swift_Plugins_Reporter::RESULT_FAIL
            );
        $this->hitReporter->notify($this->message, 'zip@button',
            Swift_Plugins_Reporter::RESULT_FAIL
            );
        $this->assertEquals(['foo@bar.tld', 'zip@button'],
            $this->hitReporter->getFailedRecipients()
            );
    }

    public function testReportingPassIsIgnored()
    {
        $this->hitReporter->notify($this->message, 'foo@bar.tld',
            Swift_Plugins_Reporter::RESULT_FAIL
            );
        $this->hitReporter->notify($this->message, 'zip@button',
            Swift_Plugins_Reporter::RESULT_PASS
            );
        $this->assertEquals(['foo@bar.tld'],
            $this->hitReporter->getFailedRecipients()
            );
    }

    public function testBufferCanBeCleared()
    {
        $this->hitReporter->notify($this->message, 'foo@bar.tld',
            Swift_Plugins_Reporter::RESULT_FAIL
            );
        $this->hitReporter->notify($this->message, 'zip@button',
            Swift_Plugins_Reporter::RESULT_FAIL
            );
        $this->assertEquals(['foo@bar.tld', 'zip@button'],
            $this->hitReporter->getFailedRecipients()
            );
        $this->hitReporter->clear();
        $this->assertEquals([], $this->hitReporter->getFailedRecipients());
    }
}


================================================
FILE: tests/unit/Swift/Plugins/Reporters/HtmlReporterTest.php
================================================
<?php

class Swift_Plugins_Reporters_HtmlReporterTest extends \PHPUnit\Framework\TestCase
{
    private $html;
    private $message;

    protected function setUp()
    {
        $this->html = new Swift_Plugins_Reporters_HtmlReporter();
        $this->message = $this->getMockBuilder('Swift_Mime_SimpleMessage')->disableOriginalConstructor()->getMock();
    }

    public function testReportingPass()
    {
        ob_start();
        $this->html->notify($this->message, 'foo@bar.tld',
            Swift_Plugins_Reporter::RESULT_PASS
            );
        $html = ob_get_clean();

        $this->assertMatchesRegularExpression('~ok|pass~i', $html, '%s: Reporter should indicate pass');
        $this->assertMatchesRegularExpression('~foo@bar\.tld~', $html, '%s: Reporter should show address');
    }

    public function testReportingFail()
    {
        ob_start();
        $this->html->notify($this->message, 'zip@button',
            Swift_Plugins_Reporter::RESULT_FAIL
            );
        $html = ob_get_clean();

        $this->assertMatchesRegularExpression('~fail~i', $html, '%s: Reporter should indicate fail');
        $this->assertMatchesRegularExpression('~zip@button~', $html, '%s: Reporter should show address');
    }

    public function testMultipleReports()
    {
        ob_start();
        $this->html->notify($this->message, 'foo@bar.tld',
            Swift_Plugins_Reporter::RESULT_PASS
            );
        $this->html->notify($this->message, 'zip@button',
            Swift_Plugins_Reporter::RESULT_FAIL
            );
        $html = ob_get_clean();

        $this->assertMatchesRegularExpression('~ok|pass~i', $html, '%s: Reporter should indicate pass');
        $this->assertMatchesRegularExpression('~foo@bar\.tld~', $html, '%s: Reporter should show address');
        $this->assertMatchesRegularExpression('~fail~i', $html, '%s: Reporter should indicate fail');
        $this->assertMatchesRegularExpression('~zip@button~', $html, '%s: Reporter should show address');
    }
}


================================================
FILE: tests/unit/Swift/Plugins/ThrottlerPluginTest.php
================================================
<?php

class Swift_Plugins_ThrottlerPluginTest extends \SwiftMailerTestCase
{
    public function testBytesPerMinuteThrottling()
    {
        $sleeper = $this->createSleeper();
        $timer = $this->createTimer();

        //10MB/min
        $plugin = new Swift_Plugins_ThrottlerPlugin(
            10000000, Swift_Plugins_ThrottlerPlugin::BYTES_PER_MINUTE,
            $sleeper, $timer
            );

        $timer->shouldReceive('getTimestamp')->once()->andReturn(0);
        $timer->shouldReceive('getTimestamp')->once()->andReturn(1); //expected 0.6
        $timer->shouldReceive('getTimestamp')->once()->andReturn(1); //expected 1.2 (sleep 1)
        $timer->shouldReceive('getTimestamp')->once()->andReturn(2); //expected 1.8
        $timer->shouldReceive('getTimestamp')->once()->andReturn(2); //expected 2.4 (sleep 1)
        $sleeper->shouldReceive('sleep')->twice()->with(1);

        //10,000,000 bytes per minute
        //100,000 bytes per email

        // .: (10,000,000/100,000)/60 emails per second = 1.667 emais/sec

        $message = $this->createMessageWithByteCount(100000); //100KB

        $evt = $this->createSendEvent($message);

        for ($i = 0; $i < 5; ++$i) {
            $plugin->beforeSendPerformed($evt);
            $plugin->sendPerformed($evt);
        }
    }

    public function testMessagesPerMinuteThrottling()
    {
        $sleeper = $this->createSleeper();
        $timer = $this->createTimer();

        //60/min
        $plugin = new Swift_Plugins_ThrottlerPlugin(
            60, Swift_Plugins_ThrottlerPlugin::MESSAGES_PER_MINUTE,
            $sleeper, $timer
            );

        $timer->shouldReceive('getTimestamp')->once()->andReturn(0);
        $timer->shouldReceive('getTimestamp')->once()->andReturn(0); //expected 1 (sleep 1)
        $timer->shouldReceive('getTimestamp')->once()->andReturn(2); //expected 2
        $timer->shouldReceive('getTimestamp')->once()->andReturn(2); //expected 3 (sleep 1)
        $timer->shouldReceive('getTimestamp')->once()->andReturn(4); //expected 4
        $sleeper->shouldReceive('sleep')->twice()->with(1);

        //60 messages per minute
        //1 message per second

        $message = $this->createMessageWithByteCount(10);

        $evt = $this->createSendEvent($message);

        for ($i = 0; $i < 5; ++$i) {
            $plugin->beforeSendPerformed($evt);
            $plugin->sendPerformed($evt);
        }
    }

    private function createSleeper()
    {
        return $this->getMockery('Swift_Plugins_Sleeper');
    }

    private function createTimer()
    {
        return $this->getMockery('Swift_Plugins_Timer');
    }

    private function createMessageWithByteCount($bytes)
    {
        $msg = $this->getMockery('Swift_Mime_SimpleMessage');
        $msg->shouldReceive('toByteStream')
            ->zeroOrMoreTimes()
            ->andReturnUsing(function ($is) use ($bytes) {
                for ($i = 0; $i < $bytes; ++$i) {
                    $is->write('x');
                }
            });

        return $msg;
    }

    private function createSendEvent($message)
    {
        $evt = $this->getMockery('Swift_Events_SendEvent');
        $evt->shouldReceive('getMessage')
            ->zeroOrMoreTimes()
            ->andReturn($message);

        return $evt;
    }
}


================================================
FILE: tests/unit/Swift/Signers/DKIMSignerTest.php
================================================
<?php

use Egulias\EmailValidator\EmailValidator;

class Swift_Signers_DKIMSignerTest extends \SwiftMailerTestCase
{
    public function testBasicSigningHeaderManipulation()
    {
        $headers = $this->createHeaders();
        $messageContent = 'Hello World';
        $signer = new Swift_Signers_DKIMSigner(file_get_contents(\dirname(__DIR__, 3).'/_samples/dkim/dkim.test.priv'), 'dummy.nxdomain.be', 'dummySelector');
        /* @var $signer Swift_Signers_HeaderSigner */
        $altered = $signer->getAlteredHeaders();
        $signer->reset();
        // Headers
        $signer->setHeaders($headers);
        // Body
        $signer->startBody();
        $signer->write($messageContent);
        $signer->endBody();
        // Signing
        $signer->addSignature($headers);
    }

    // SHA1 Signing
    public function testSigningSHA1()
    {
        $headerSet = $this->createHeaderSet();
        $messageContent = 'Hello World';
        $signer = new Swift_Signers_DKIMSigner(file_get_contents(\dirname(__DIR__, 3).'/_samples/dkim/dkim.test.priv'), 'dummy.nxdomain.be', 'dummySelector');
        $signer->setHashAlgorithm('rsa-sha1');
        $signer->setSignatureTimestamp('1299879181');
        $altered = $signer->getAlteredHeaders();
        $this->assertEquals(['DKIM-Signature'], $altered);
        $signer->reset();
        $signer->setHeaders($headerSet);
        $this->assertFalse($headerSet->has('DKIM-Signature'));
        $signer->startBody();
        $signer->write($messageContent);
        $signer->endBody();
        $signer->addSignature($headerSet);
        $this->assertTrue($headerSet->has('DKIM-Signature'));
        $dkim = $headerSet->getAll('DKIM-Signature');
        $sig = reset($dkim);
        $this->assertEquals($sig->getValue(), 'v=1; a=rsa-sha1; bh=wlbYcY9O9OPInGJ4D0E/rGsvMLE=; d=dummy.nxdomain.be; h=; i=@dummy.nxdomain.be; s=dummySelector; t=1299879181; b=RMSNelzM2O5MAAnMjT3G3/VF36S3DGJXoPCXR001F1WDReu0prGphWjuzK/m6V1pwqQL8cCNg Hi74mTx2bvyAvmkjvQtJf1VMUOCc9WHGcm1Yec66I3ZWoNMGSWZ1EKAm2CtTzyG0IFw4ml9DI wSkyAFxlgicckDD6FibhqwX4w=');
    }

    // SHA256 Signing
    public function testSigning256()
    {
        $headerSet = $this->createHeaderSet();
        $messageContent = 'Hello World';
        $signer = new Swift_Signers_DKIMSigner(file_get_contents(\dirname(__DIR__, 3).'/_samples/dkim/dkim.test.priv'), 'dummy.nxdomain.be', 'dummySelector');
        $signer->setHashAlgorithm('rsa-sha256');
        $signer->setSignatureTimestamp('1299879181');
        $altered = $signer->getAlteredHeaders();
        $this->assertEquals(['DKIM-Signature'], $altered);
        $signer->reset();
        $signer->setHeaders($headerSet);
        $this->assertFalse($headerSet->has('DKIM-Signature'));
        $signer->startBody();
        $signer->write($messageContent);
        $signer->endBody();
        $signer->addSignature($headerSet);
        $this->assertTrue($headerSet->has('DKIM-Signature'));
        $dkim = $headerSet->getAll('DKIM-Signature');
        $sig = reset($dkim);
        $this->assertEquals($sig->getValue(), 'v=1; a=rsa-sha256; bh=f+W+hu8dIhf2VAni89o8lF6WKTXi7nViA4RrMdpD5/U=; d=dummy.nxdomain.be; h=; i=@dummy.nxdomain.be; s=dummySelector; t=1299879181; b=jqPmieHzF5vR9F4mXCAkowuphpO4iJ8IAVuioh1BFZ3VITXZj5jlOFxULJMBiiApm2keJirnh u4mzogj444QkpT3lJg8/TBGAYQPdcvkG3KC0jdyN6QpSgpITBJG2BwWa+keXsv2bkQgLRAzNx qRhP45vpHCKun0Tg9LrwW/KCg=');
    }

    // Relaxed/Relaxed Hash Signing
    public function testSigningRelaxedRelaxed256()
    {
        $headerSet = $this->createHeaderSet();
        $messageContent = 'Hello World';
        $signer = new Swift_Signers_DKIMSigner(file_get_contents(\dirname(__DIR__, 3).'/_samples/dkim/dkim.test.priv'), 'dummy.nxdomain.be', 'dummySelector');
        $signer->setHashAlgorithm('rsa-sha256');
        $signer->setSignatureTimestamp('1299879181');
        $signer->setBodyCanon('relaxed');
        $signer->setHeaderCanon('relaxed');
        $altered = $signer->getAlteredHeaders();
        $this->assertEquals(['DKIM-Signature'], $altered);
        $signer->reset();
        $signer->setHeaders($headerSet);
        $this->assertFalse($headerSet->has('DKIM-Signature'));
        $signer->startBody();
        $signer->write($messageContent);
        $signer->endBody();
        $signer->addSignature($headerSet);
        $this->assertTrue($headerSet->has('DKIM-Signature'));
        $dkim = $headerSet->getAll('DKIM-Signature');
        $sig = reset($dkim);
        $this->assertEquals($sig->getValue(), 'v=1; a=rsa-sha256; bh=f+W+hu8dIhf2VAni89o8lF6WKTXi7nViA4RrMdpD5/U=; d=dummy.nxdomain.be; h=; i=@dummy.nxdomain.be; s=dummySelector; c=relaxed/relaxed; t=1299879181; b=gzOI+PX6HpZKQFzwwmxzcVJsyirdLXOS+4pgfCpVHQIdqYusKLrhlLeFBTNoz75HrhNvGH6T0 Rt3w5aTqkrWfUuAEYt0Ns14GowLM7JojaFN+pZ4eYnRB3CBBgW6fee4NEMD5WPca3uS09tr1E 10RYh9ILlRtl+84sovhx5id3Y=');
    }

    // Relaxed/Simple Hash Signing
    public function testSigningRelaxedSimple256()
    {
        $headerSet = $this->createHeaderSet();
        $messageContent = 'Hello World';
        $signer = new Swift_Signers_DKIMSigner(file_get_contents(\dirname(__DIR__, 3).'/_samples/dkim/dkim.test.priv'), 'dummy.nxdomain.be', 'dummySelector');
        $signer->setHashAlgorithm('rsa-sha256');
        $signer->setSignatureTimestamp('1299879181');
        $signer->setHeaderCanon('relaxed');
        $altered = $signer->getAlteredHeaders();
        $this->assertEquals(['DKIM-Signature'], $altered);
        $signer->reset();
        $signer->setHeaders($headerSet);
        $this->assertFalse($headerSet->has('DKIM-Signature'));
        $signer->startBody();
        $signer->write($messageContent);
        $signer->endBody();
        $signer->addSignature($headerSet);
        $this->assertTrue($headerSet->has('DKIM-Signature'));
        $dkim = $headerSet->getAll('DKIM-Signature');
        $sig = reset($dkim);
        $this->assertEquals($sig->getValue(), 'v=1; a=rsa-sha256; bh=f+W+hu8dIhf2VAni89o8lF6WKTXi7nViA4RrMdpD5/U=; d=dummy.nxdomain.be; h=; i=@dummy.nxdomain.be; s=dummySelector; c=relaxed; t=1299879181; b=dLPJNec5v81oelyzGOY0qPqTlGnQeNfUNBOrV/JKbStr3NqWGI9jH4JAe2YvO2V32lfPNoby1 4MMzZ6EPkaZkZDDSPa+53YbCPQAlqiD9QZZIUe2UNM33HN8yAMgiWEF5aP7MbQnxeVZMfVLEl 9S8qOImu+K5JZqhQQTL0dgLwA=');
    }

    // Simple/Relaxed Hash Signing
    public function testSigningSimpleRelaxed256()
    {
        $headerSet = $this->createHeaderSet();
        $messageContent = 'Hello World';
        $signer = new Swift_Signers_DKIMSigner(file_get_contents(\dirname(__DIR__, 3).'/_samples/dkim/dkim.test.priv'), 'dummy.nxdomain.be', 'dummySelector');
        $signer->setHashAlgorithm('rsa-sha256');
        $signer->setSignatureTimestamp('1299879181');
        $signer->setBodyCanon('relaxed');
        $altered = $signer->getAlteredHeaders();
        $this->assertEquals(['DKIM-Signature'], $altered);
        $signer->reset();
        $signer->setHeaders($headerSet);
        $this->assertFalse($headerSet->has('DKIM-Signature'));
        $signer->startBody();
        $signer->write($messageContent);
        $signer->endBody();
        $signer->addSignature($headerSet);
        $this->assertTrue($headerSet->has('DKIM-Signature'));
        $dkim = $headerSet->getAll('DKIM-Signature');
        $sig = reset($dkim);
        $this->assertEquals($sig->getValue(), 'v=1; a=rsa-sha256; bh=f+W+hu8dIhf2VAni89o8lF6WKTXi7nViA4RrMdpD5/U=; d=dummy.nxdomain.be; h=; i=@dummy.nxdomain.be; s=dummySelector; c=simple/relaxed; t=1299879181; b=M5eomH/zamyzix9kOes+6YLzQZxuJdBP4x3nP9zF2N26eMLG2/cBKbnNyqiOTDhJdYfWPbLIa 1CWnjST0j5p4CpeOkGYuiE+M4TWEZwhRmRWootlPO3Ii6XpbBJKFk1o9zviS7OmXblUUE4aqb yRSIMDhtLdCK5GlaCneFLN7RQ=');
    }

    private function createHeaderSet()
    {
        $cache = new Swift_KeyCache_ArrayKeyCache(new Swift_KeyCache_SimpleKeyCacheInputStream());
        $factory = new Swift_CharacterReaderFactory_SimpleCharacterReaderFactory();
        $contentEncoder = new Swift_Mime_ContentEncoder_Base64ContentEncoder();

        $headerEncoder = new Swift_Mime_HeaderEncoder_QpHeaderEncoder(new Swift_CharacterStream_ArrayCharacterStream($factory, 'utf-8'));
        $paramEncoder = new Swift_Encoder_Rfc2231Encoder(new Swift_CharacterStream_ArrayCharacterStream($factory, 'utf-8'));
        $emailValidator = new EmailValidator();
        $headers = new Swift_Mime_SimpleHeaderSet(new Swift_Mime_SimpleHeaderFactory($headerEncoder, $paramEncoder, $emailValidator));

        return $headers;
    }

    /**
     * @return Swift_Mime_Headers
     */
    private function createHeaders()
    {
        $x = 0;
        $cache = new Swift_KeyCache_ArrayKeyCache(new Swift_KeyCache_SimpleKeyCacheInputStream());
        $factory = new Swift_CharacterReaderFactory_SimpleCharacterReaderFactory();
        $contentEncoder = new Swift_Mime_ContentEncoder_Base64ContentEncoder();

        $headerEncoder = new Swift_Mime_HeaderEncoder_QpHeaderEncoder(new Swift_CharacterStream_ArrayCharacterStream($factory, 'utf-8'));
        $paramEncoder = new Swift_Encoder_Rfc2231Encoder(new Swift_CharacterStream_ArrayCharacterStream($factory, 'utf-8'));
        $emailValidator = new EmailValidator();
        $headerFactory = new Swift_Mime_SimpleHeaderFactory($headerEncoder, $paramEncoder, $emailValidator);
        $headers = $this->getMockery('Swift_Mime_SimpleHeaderSet');

        $headers->shouldReceive('listAll')
                ->zeroOrMoreTimes()
                ->andReturn(['From', 'To', 'Date', 'Subject']);
        $headers->shouldReceive('has')
                ->zeroOrMoreTimes()
                ->with('From')
                ->andReturn(true);
        $headers->shouldReceive('getAll')
                ->zeroOrMoreTimes()
                ->with('From')
                ->andReturn([$headerFactory->createMailboxHeader('From', 'test@test.test')]);
        $headers->shouldReceive('has')
                ->zeroOrMoreTimes()
                ->with('To')
                ->andReturn(true);
        $headers->shouldReceive('getAll')
                ->zeroOrMoreTimes()
                ->with('To')
                ->andReturn([$headerFactory->createMailboxHeader('To', 'test@test.test')]);
        $headers->shouldReceive('has')
                ->zeroOrMoreTimes()
                ->with('Date')
                ->andReturn(true);
        $headers->shouldReceive('getAll')
                ->zeroOrMoreTimes()
                ->with('Date')
                ->andReturn([$headerFactory->createTextHeader('Date', 'Fri, 11 Mar 2011 20:56:12 +0000 (GMT)')]);
        $headers->shouldReceive('has')
                ->zeroOrMoreTimes()
                ->with('Subject')
                ->andReturn(true);
        $headers->shouldReceive('getAll')
                ->zeroOrMoreTimes()
                ->with('Subject')
                ->andReturn([$headerFactory->createTextHeader('Subject', 'Foo Bar Text Message')]);
        $headers->shouldReceive('addTextHeader')
                ->zeroOrMoreTimes()
                ->with('DKIM-Signature', \Mockery::any())
                ->andReturn(true);
        $headers->shouldReceive('getAll')
                ->zeroOrMoreTimes()
                ->with('DKIM-Signature')
                ->andReturn([$headerFactory->createTextHeader('DKIM-Signature', 'Foo Bar Text Message')]);

        return $headers;
    }
}


================================================
FILE: tests/unit/Swift/Signers/OpenDKIMSignerTest.php
================================================
<?php

/**
 * @todo
 */
class Swift_Signers_OpenDKIMSignerTest extends \SwiftMailerTestCase
{
    protected function setUp()
    {
        if (!\extension_loaded('opendkim')) {
            $this->markTestSkipped(
                'Need OpenDKIM extension run these tests.'
             );
        }
    }

    public function testBasicSigningHeaderManipulation()
    {
    }

    // Default Signing
    public function testSigningDefaults()
    {
    }

    // SHA256 Signing
    public function testSigning256()
    {
    }

    // Relaxed/Relaxed Hash Signing
    public function testSigningRelaxedRelaxed256()
    {
    }

    // Relaxed/Simple Hash Signing
    public function testSigningRelaxedSimple256()
    {
    }

    // Simple/Relaxed Hash Signing
    public function testSigningSimpleRelaxed256()
    {
    }
}


================================================
FILE: tests/unit/Swift/Signers/SMimeSignerTest.php
================================================
<?php

class Swift_Signers_SMimeSignerTest extends \PHPUnit\Framework\TestCase
{
    /**
     * @var Swift_StreamFilters_StringReplacementFilterFactory
     */
    protected $replacementFactory;

    protected $samplesDir;

    protected function setUp()
    {
        $this->replacementFactory = Swift_DependencyContainer::getInstance()
            ->lookup('transport.replacementfactory');

        $this->samplesDir = str_replace('\\', '/', realpath(__DIR__.'/../../../_samples/')).'/';
    }

    public function testUnSignedMessage()
    {
        $message = (new Swift_Message('Wonderful Subject'))
          ->setFrom(['john@doe.com' => 'John Doe'])
          ->setTo(['receiver@domain.org', 'other@domain.org' => 'A name'])
          ->setBody('Here is the message itself');

        $this->assertEquals('Here is the message itself', $message->getBody());
    }

    public function testSignedMessage()
    {
        $message = (new Swift_Message('Wonderful Subject'))
          ->setFrom(['john@doe.com' => 'John Doe'])
          ->setTo(['receiver@domain.org', 'other@domain.org' => 'A name'])
          ->setBody('Here is the message itself');

        $signer = new Swift_Signers_SMimeSigner();
        $signer->setSignCertificate($this->samplesDir.'smime/sign.crt', $this->samplesDir.'smime/sign.key');
        $message->attachSigner($signer);

        $messageStream = $this->newFilteredStream();
        $message->toByteStream($messageStream);
        $messageStream->commit();

        $entityString = $messageStream->getContent();
        $headers = self::getHeadersOfMessage($entityString);

        if (!($boundary = $this->getBoundary($headers['content-type']))) {
            return false;
        }

        $expectedBody = <<<OEL
This is an S/MIME signed message

--$boundary
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: quoted-printable

Here is the message itself
--$boundary
Content-Type: application/(x\-)?pkcs7-signature; name="smime\.p7s"
Content-Transfer-Encoding: base64
Content-Disposition: attachment; filename="smime\.p7s"

(?:^[a-zA-Z0-9\/\\r\\n+]*={0,2})

--$boundary--
OEL;
        $this->assertValidVerify($expectedBody, $messageStream);
        unset($messageStream);
    }

    public function testSignedMessageWithFullyWrappedMessage()
    {
        $message = (new Swift_Message('Middle-out compression secrets'))
          ->setFrom(['richard@piedpiper.com' => 'Richard Hendricks'])
          ->setTo(['jared@piedpiper.com' => 'Jared Dunn'])
          ->setBody('Here goes the entire algorithm...');

        $signer = new Swift_Signers_SMimeSigner();
        $signer->setSignCertificate($this->samplesDir.'smime/sign.crt', $this->samplesDir.'smime/sign.key');

        // Tell the signer to wrap the full MIME message
        $signer->setWrapFullMessage(true);
        $message->attachSigner($signer);

        $messageStream = $this->newFilteredStream();
        $message->toByteStream($messageStream);
        $messageStream->commit();

        $entityString = $messageStream->getContent();
        $headers = self::getHeadersOfMessage($entityString);

        if (!($boundary = $this->getBoundary($headers['content-type']))) {
            return false;
        }

        $expectedBody = <<<OEL
This is an S/MIME signed message

--$boundary
Content-Type: message/rfc822; charset=utf-8
Content-Transfer-Encoding: 7bit

Message-ID: <[a-f0-9]+@swift.generated>
Date: .*
Subject: Middle-out compression secrets
From: Richard Hendricks <richard@piedpiper.com>
To: Jared Dunn <jared@piedpiper.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: quoted-printable

Here goes the entire algorithm...
--$boundary
Content-Type: application/(x\-)?pkcs7-signature; name="smime\.p7s"
Content-Transfer-Encoding: base64
Content-Disposition: attachment; filename="smime\.p7s"

(?:^[a-zA-Z0-9\/\\r\\n+]*={0,2})

--$boundary--
OEL;
        $this->assertValidVerify($expectedBody, $messageStream);
        unset($messageStream);
    }

    public function testSignedMessageExtraCerts()
    {
        $message = (new Swift_Message('Wonderful Subject'))
          ->setFrom(['john@doe.com' => 'John Doe'])
          ->setTo(['receiver@domain.org', 'other@domain.org' => 'A name'])
          ->setBody('Here is the message itself');

        $signer = new Swift_Signers_SMimeSigner();
        $signer->setSignCertificate($this->samplesDir.'smime/sign2.crt', $this->samplesDir.'smime/sign2.key', PKCS7_DETACHED, $this->samplesDir.'smime/intermediate.crt');
        $message->attachSigner($signer);

        $messageStream = $this->newFilteredStream();
        $message->toByteStream($messageStream);
        $messageStream->commit();

        $entityString = $messageStream->getContent();
        $headers = self::getHeadersOfMessage($entityString);

        if (!($boundary = $this->getBoundary($headers['content-type']))) {
            return false;
        }

        $expectedBody = <<<OEL
This is an S/MIME signed message

--$boundary
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: quoted-printable

Here is the message itself
--$boundary
Content-Type: application/(x\-)?pkcs7-signature; name="smime\.p7s"
Content-Transfer-Encoding: base64
Content-Disposition: attachment; filename="smime\.p7s"

(?:^[a-zA-Z0-9\/\\r\\n+]*={0,2})

--$boundary--
OEL;
        $this->assertValidVerify($expectedBody, $messageStream);
        unset($messageStream);
    }

    public function testSignedMessageBinary()
    {
        $message = (new Swift_Message('Wonderful Subject'))
          ->setFrom(['john@doe.com' => 'John Doe'])
          ->setTo(['receiver@domain.org', 'other@domain.org' => 'A name'])
          ->setBody('Here is the message itself');

        $signer = new Swift_Signers_SMimeSigner();
        $signer->setSignCertificate($this->samplesDir.'smime/sign.crt', $this->samplesDir.'smime/sign.key', PKCS7_BINARY);
        $message->attachSigner($signer);

        $messageStream = $this->newFilteredStream();
        $message->toByteStream($messageStream);
        $messageStream->commit();

        $entityString = $messageStream->getContent();
        $headers = self::getHeadersOfMessage($entityString);

        if (!preg_match('#^application/(x\-)?pkcs7-mime; smime-type=signed\-data;#', $headers['content-type'])) {
            $this->fail('Content-type does not match.');

            return false;
        }

        $this->assertEquals($headers['content-transfer-encoding'], 'base64');
        $this->assertEquals($headers['content-disposition'], 'attachment; filename="smime.p7m"');

        $expectedBody = '(?:^[a-zA-Z0-9\/\\r\\n+]*={0,2})';

        $messageStreamClean = $this->newFilteredStream();

        $this->assertValidVerify($expectedBody, $messageStream);
        unset($messageStreamClean, $messageStream);
    }

    public function testSignedMessageWithAttachments()
    {
        $message = (new Swift_Message('Wonderful Subject'))
          ->setFrom(['john@doe.com' => 'John Doe'])
          ->setTo(['receiver@domain.org', 'other@domain.org' => 'A name'])
          ->setBody('Here is the message itself');

        $message->attach(Swift_Attachment::fromPath($this->samplesDir.'/files/textfile.zip'));

        $signer = new Swift_Signers_SMimeSigner();
        $signer->setSignCertificate($this->samplesDir.'smime/sign.crt', $this->samplesDir.'smime/sign.key');
        $message->attachSigner($signer);

        $messageStream = $this->newFilteredStream();
        $message->toByteStream($messageStream);
        $messageStream->commit();

        $entityString = $messageStream->getContent();
        $headers = self::getHeadersOfMessage($entityString);

        if (!($boundary = $this->getBoundary($headers['content-type']))) {
            return false;
        }

        $expectedBody = <<<OEL
This is an S/MIME signed message

--$boundary
Content-Type: multipart/mixed;
 boundary="([a-z0-9\\'\\(\\)\\+_\\-,\\.\\/:=\\?\\ ]{0,69}[a-z0-9\\'\\(\\)\\+_\\-,\\.\\/:=\\?])"


--\\1
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: quoted-printable

Here is the message itself

--\\1
Content-Type: application/zip; name=textfile\\.zip
Content-Transfer-Encoding: base64
Content-Disposition: attachment; filename=textfile\\.zip

UEsDBAoAAgAAAMi6VjiOTiKwLgAAAC4AAAAMABUAdGV4dGZpbGUudHh0VVQJAAN3vr5Hd76\\+R1V4
BAD1AfUBVGhpcyBpcyBwYXJ0IG9mIGEgU3dpZnQgTWFpbGVyIHY0IHNtb2tlIHRlc3QuClBLAQIX
AwoAAgAAAMi6VjiOTiKwLgAAAC4AAAAMAA0AAAAAAAEAAACkgQAAAAB0ZXh0ZmlsZS50eHRVVAUA
A3e\\+vkdVeAAAUEsFBgAAAAABAAEARwAAAG0AAAAAAA==

--\\1--

--$boundary
Content-Type: application/(x\-)?pkcs7-signature; name="smime\\.p7s"
Content-Transfer-Encoding: base64
Content-Disposition: attachment; filename="smime\\.p7s"

(?:^[a-zA-Z0-9\/\\r\\n+]*={0,2})

--$boundary--
OEL;

        $this->assertValidVerify($expectedBody, $messageStream);
        unset($messageStream);
    }

    public function testEncryptedMessage()
    {
        $message = (new Swift_Message('Wonderful Subject'))
          ->setFrom(['john@doe.com' => 'John Doe'])
          ->setTo(['receiver@domain.org', 'other@domain.org' => 'A name'])
          ->setBody('Here is the message itself');

        $originalMessage = $this->cleanMessage($message->toString());

        $signer = new Swift_Signers_SMimeSigner();
        $signer->setEncryptCertificate($this->samplesDir.'smime/encrypt.crt');
        $message->attachSigner($signer);

        $messageStream = new Swift_ByteStream_TemporaryFileByteStream();
        $message->toByteStream($messageStream);
        $messageStream->commit();

        $entityString = $messageStream->getContent();
        $headers = self::getHeadersOfMessage($entityString);

        if (!preg_match('#^application/(x\-)?pkcs7-mime; smime-type=enveloped\-data;#', $headers['content-type'])) {
            $this->fail('Content-type does not match.');

            return false;
        }

        $expectedBody = '(?:^[a-zA-Z0-9\/\\r\\n+]*={0,2})';

        $decryptedMessageStream = new Swift_ByteStream_TemporaryFileByteStream();

        if (!openssl_pkcs7_decrypt($messageStream->getPath(), $decryptedMessageStream->getPath(), 'file://'.$this->samplesDir.'smime/encrypt.crt', ['file://'.$this->samplesDir.'smime/encrypt.key', 'swift'])) {
            $this->fail(sprintf('Decrypt of the message failed. Internal error "%s".', openssl_error_string()));
        }

        $this->assertEquals($originalMessage, $decryptedMessageStream->getContent());
        unset($decryptedMessageStream, $messageStream);
    }

    public function testEncryptedMessageWithFullyWrappedMessage()
    {
        $message = (new Swift_Message('Middle-out compression secrets'))
          ->setFrom(['richard@piedpiper.com' => 'Richard Hendricks'])
          ->setTo(['jared@piedpiper.com' => 'Jared Dunn'])
          ->setBody('Here goes the entire algorithm...');

        $originalMessage = $message->toString();

        $signer = new Swift_Signers_SMimeSigner();
        $signer->setEncryptCertificate($this->samplesDir.'smime/encrypt.crt');
        $signer->setWrapFullMessage(true);
        $message->attachSigner($signer);

        $messageStream = new Swift_ByteStream_TemporaryFileByteStream();
        $message->toByteStream($messageStream);
        $messageStream->commit();

        $entityString = $messageStream->getContent();
        $headers = self::getHeadersOfMessage($entityString);

        if (!preg_match('#^application/(x\-)?pkcs7-mime; smime-type=enveloped\-data;#', $headers['content-type'])) {
            $this->fail('Content-type does not match.');

            return false;
        }

        $expectedBody = '(?:^[a-zA-Z0-9\/\\r\\n+]*={0,2})';

        $decryptedMessageStream = new Swift_ByteStream_TemporaryFileByteStream();

        if (!openssl_pkcs7_decrypt($messageStream->getPath(), $decryptedMessageStream->getPath(), 'file://'.$this->samplesDir.'smime/encrypt.crt', ['file://'.$this->samplesDir.'smime/encrypt.key', 'swift'])) {
            $this->fail(sprintf('Decrypt of the message failed. Internal error "%s".', openssl_error_string()));
        }

        $decryptedMessage = $decryptedMessageStream->getContent();
        $decryptedHeaders = self::getHeadersOfMessage($decryptedMessage);
        $this->assertEquals('message/rfc822; charset=utf-8', $decryptedHeaders['content-type']);
        $this->assertEquals('7bit', $decryptedHeaders['content-transfer-encoding']);

        $decryptedMessageBody = self::getBodyOfMessage($decryptedMessage);
        $this->assertEquals($originalMessage, $decryptedMessageBody);
        unset($decryptedMessageStream, $messageStream);
    }

    public function testEncryptedMessageWithMultipleCerts()
    {
        $message = (new Swift_Message('Wonderful Subject'))
          ->setFrom(['john@doe.com' => 'John Doe'])
          ->setTo(['receiver@domain.org', 'other@domain.org' => 'A name'])
          ->setBody('Here is the message itself');

        $originalMessage = $this->cleanMessage($message->toString());

        $signer = new Swift_Signers_SMimeSigner();
        $signer->setEncryptCertificate([$this->samplesDir.'smime/encrypt.crt', $this->samplesDir.'smime/encrypt2.crt']);
        $message->attachSigner($signer);

        $messageStream = new Swift_ByteStream_TemporaryFileByteStream();
        $message->toByteStream($messageStream);
        $messageStream->commit();

        $entityString = $messageStream->getContent();
        $headers = self::getHeadersOfMessage($entityString);

        if (!preg_match('#^application/(x\-)?pkcs7-mime; smime-type=enveloped\-data;#', $headers['content-type'])) {
            $this->fail('Content-type does not match.');

            return false;
        }

        $expectedBody = '(?:^[a-zA-Z0-9\/\\r\\n+]*={0,2})';

        $decryptedMessageStream = new Swift_ByteStream_TemporaryFileByteStream();

        if (!openssl_pkcs7_decrypt($messageStream->getPath(), $decryptedMessageStream->getPath(), 'file://'.$this->samplesDir.'smime/encrypt.crt', ['file://'.$this->samplesDir.'smime/encrypt.key', 'swift'])) {
            $this->fail(sprintf('Decrypt of the message failed. Internal error "%s".', openssl_error_string()));
        }

        $this->assertEquals($originalMessage, $decryptedMessageStream->getContent());
        unset($decryptedMessageStream);

        $decryptedMessageStream = new Swift_ByteStream_TemporaryFileByteStream();

        if (!openssl_pkcs7_decrypt($messageStream->getPath(), $decryptedMessageStream->getPath(), 'file://'.$this->samplesDir.'smime/encrypt2.crt', ['file://'.$this->samplesDir.'smime/encrypt2.key', 'swift'])) {
            $this->fail(sprintf('Decrypt of the message failed. Internal error "%s".', openssl_error_string()));
        }

        $this->assertEquals($originalMessage, $decryptedMessageStream->getContent());
        unset($decryptedMessageStream, $messageStream);
    }

    public function testSignThenEncryptedMessage()
    {
        $message = (new Swift_Message('Wonderful Subject'))
          ->setFrom(['john@doe.com' => 'John Doe'])
          ->setTo(['receiver@domain.org', 'other@domain.org' => 'A name'])
          ->setBody('Here is the message itself');

        $signer = new Swift_Signers_SMimeSigner();
        $signer->setSignCertificate($this->samplesDir.'smime/sign.crt', $this->samplesDir.'smime/sign.key');
        $signer->setEncryptCertificate($this->samplesDir.'smime/encrypt.crt');
        $message->attachSigner($signer);

        $messageStream = new Swift_ByteStream_TemporaryFileByteStream();
        $message->toByteStream($messageStream);
        $messageStream->commit();

        $entityString = $messageStream->getContent();
        $headers = self::getHeadersOfMessage($entityString);

        if (!preg_match('#^application/(x\-)?pkcs7-mime; smime-type=enveloped\-data;#', $headers['content-type'])) {
            $this->fail('Content-type does not match.');

            return false;
        }

        $expectedBody = '(?:^[a-zA-Z0-9\/\\r\\n+]*={0,2})';

        $decryptedMessageStream = new Swift_ByteStream_TemporaryFileByteStream();

        if (!openssl_pkcs7_decrypt($messageStream->getPath(), $decryptedMessageStream->getPath(), 'file://'.$this->samplesDir.'smime/encrypt.crt', ['file://'.$this->samplesDir.'smime/encrypt.key', 'swift'])) {
            $this->fail(sprintf('Decrypt of the message failed. Internal error "%s".', openssl_error_string()));
        }

        $entityString = $decryptedMessageStream->getContent();
        $headers = self::getHeadersOfMessage($entityString);

        if (!($boundary = $this->getBoundary($headers['content-type']))) {
            return false;
        }

        $expectedBody = <<<OEL
This is an S/MIME signed message

--$boundary
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: quoted-printable

Here is the message itself
--$boundary
Content-Type: application/(x\-)?pkcs7-signature; name="smime\.p7s"
Content-Transfer-Encoding: base64
Content-Disposition: attachment; filename="smime\.p7s"

(?:^[a-zA-Z0-9\/\\r\\n+]*={0,2})

--$boundary--
OEL;

        if (!$this->assertValidVerify($expectedBody, $decryptedMessageStream)) {
            return false;
        }

        unset($decryptedMessageStream, $messageStream);
    }

    public function testEncryptThenSignMessage()
    {
        $message = (new Swift_Message('Wonderful Subject'))
          ->setFrom(['john@doe.com' => 'John Doe'])
          ->setTo(['receiver@domain.org', 'other@domain.org' => 'A name'])
          ->setBody('Here is the message itself');

        $originalMessage = $message->toString();

        $signer = new Swift_Signers_SMimeSigner();
        $signer->setSignCertificate($this->samplesDir.'smime/sign.crt', $this->samplesDir.'smime/sign.key');
        $signer->setEncryptCertificate($this->samplesDir.'smime/encrypt.crt');
        $signer->setSignThenEncrypt(false);
        $message->attachSigner($signer);

        $messageStream = $this->newFilteredStream();
        $message->toByteStream($messageStream);
        $messageStream->commit();

        $entityString = $messageStream->getContent();
        $headers = self::getHeadersOfMessage($entityString);

        if (!($boundary = $this->getBoundary($headers['content-type']))) {
            return false;
        }

        $expectedBody = <<<OEL
This is an S/MIME signed message

--$boundary
(?P<encrypted_message>Content-Type: application/(x\-)?pkcs7-mime; smime-type=enveloped-data;
 name="smime\.p7m"; charset=utf-8
Content-Transfer-Encoding: base64
Content-Disposition: attachment; filename="smime\.p7m"

(?:^[a-zA-Z0-9\/\\r\\n+]*={0,2})


)--$boundary
Content-Type: application/(x\-)?pkcs7-signature; name="smime\.p7s"
Content-Transfer-Encoding: base64
Content-Disposition: attachment; filename="smime\.p7s"

(?:^[a-zA-Z0-9\/\\r\\n+]*={0,2})

--$boundary--
OEL;

        if (!$this->assertValidVerify($expectedBody, $messageStream)) {
            return false;
        }

        $expectedBody = str_replace("\n", "\r\n", $expectedBody);
        if (!preg_match('%'.$expectedBody.'*%m', $entityString, $entities)) {
            $this->fail('Failed regex match.');

            return false;
        }

        $messageStreamClean = new Swift_ByteStream_TemporaryFileByteStream();
        $messageStreamClean->write($entities['encrypted_message']);

        $decryptedMessageStream = new Swift_ByteStream_TemporaryFileByteStream();

        if (!openssl_pkcs7_decrypt($messageStreamClean->getPath(), $decryptedMessageStream->getPath(), 'file://'.$this->samplesDir.'smime/encrypt.crt', ['file://'.$this->samplesDir.'smime/encrypt.key', 'swift'])) {
            $this->fail(sprintf('Decrypt of the message failed. Internal error "%s".', openssl_error_string()));
        }

        $this->assertEquals($originalMessage, $decryptedMessageStream->getContent());
        unset($messageStreamClean, $messageStream, $decryptedMessageStream);
    }

    protected function assertValidVerify($expected, Swift_ByteStream_TemporaryFileByteStream $messageStream)
    {
        $actual = $messageStream->getContent();

        // File is UNIX encoded so convert them to correct line ending
        $expected = str_replace("\n", "\r\n", $expected);

        $actual = self::getBodyOfMessage($actual);
        if (!$this->assertMatchesRegularExpression('%^'.$expected.'$\s*%m', $actual)) {
            return false;
        }

        $opensslOutput = new Swift_ByteStream_TemporaryFileByteStream();
        $verify = openssl_pkcs7_verify($messageStream->getPath(), null, $opensslOutput->getPath(), [$this->samplesDir.'smime/ca.crt']);

        if (false === $verify) {
            $this->fail('Verification of the message failed.');

            return false;
        } elseif (-1 === $verify) {
            $this->fail(sprintf('Verification of the message failed. Internal error "%s".', openssl_error_string()));

            return false;
        }

        return true;
    }

    protected function getBoundary($contentType)
    {
        if (!preg_match('/boundary=("[^"]+"|(?:[^\s]+|$))/is', $contentType, $contentTypeData)) {
            $this->fail('Failed to find Boundary parameter');

            return false;
        }

        return trim($contentTypeData[1], '"');
    }

    protected function newFilteredStream()
    {
        $messageStream = new Swift_ByteStream_TemporaryFileByteStream();
        $messageStream->addFilter($this->replacementFactory->createFilter("\r\n", "\n"), 'CRLF to LF');
        $messageStream->addFilter($this->replacementFactory->createFilter("\n", "\r\n"), 'LF to CRLF');

        return $messageStream;
    }

    protected static function getBodyOfMessage($message)
    {
        return trim(substr($message, strpos($message, "\r\n\r\n")));
    }

    /**
     * Strips of the sender headers and Mime-Version.
     */
    protected function cleanMessage($content)
    {
        $newContent = '';

        $headers = self::getHeadersOfMessage($content);
        foreach ($headers as $headerName => $value) {
            if (!\in_array($headerName, ['content-type', 'content-transfer-encoding', 'content-disposition'])) {
                continue;
            }

            $headerName = explode('-', $headerName);
            $headerName = array_map('ucfirst', $headerName);
            $headerName = implode('-', $headerName);

            if (\strlen($value) > 62) {
                $value = wordwrap($value, 62, "\n ");
            }

            $newContent .= "$headerName: $value\r\n";
        }

        return $newContent."\r\n".self::getBodyOfMessage($content);
    }

    /**
     * Returns the headers of the message.
     *
     * Header-names are lowercase.
     *
     * @param string $message
     *
     * @return array
     */
    protected static function getHeadersOfMessage($message)
    {
        $headersPosEnd = strpos($message, "\r\n\r\n");
        $headerData = trim(substr($message, 0, $headersPosEnd));
        $headerLines = explode("\r\n", $headerData);
        $headers = [];

        if (false === $headerLines) {
            return $headers;
        }

        // Transform header lines into an associative array
        $currentHeaderName = '';
        foreach ($headerLines as $headerLine) {
            // Handle headers that span multiple lines
            if (false === strpos($headerLine, ':')) {
                $headers[$currentHeaderName] .= ' '.trim($headerLine);
                continue;
            }

            $header = explode(':', $headerLine, 2);
            $currentHeaderName = strtolower($header[0] ?? '');
            $headers[$currentHeaderName] = trim($header[1]);
        }

        return $headers;
    }
}


================================================
FILE: tests/unit/Swift/StreamFilters/ByteArrayReplacementFilterTest.php
================================================
<?php

class Swift_StreamFilters_ByteArrayReplacementFilterTest extends \PHPUnit\Framework\TestCase
{
    public function testBasicReplacementsAreMade()
    {
        $filter = $this->createFilter([0x61, 0x62], [0x63, 0x64]);
        $this->assertEquals(
            [0x59, 0x60, 0x63, 0x64, 0x65],
            $filter->filter([0x59, 0x60, 0x61, 0x62, 0x65])
            );
    }

    public function testShouldBufferReturnsTrueIfPartialMatchAtEndOfBuffer()
    {
        $filter = $this->createFilter([0x61, 0x62], [0x63, 0x64]);
        $this->assertTrue($filter->shouldBuffer([0x59, 0x60, 0x61]),
            '%s: Filter should buffer since 0x61 0x62 is the needle and the ending '.
            '0x61 could be from 0x61 0x62'
            );
    }

    public function testFilterCanMakeMultipleReplacements()
    {
        $filter = $this->createFilter([[0x61], [0x62]], [0x63]);
        $this->assertEquals(
            [0x60, 0x63, 0x60, 0x63, 0x60],
            $filter->filter([0x60, 0x61, 0x60, 0x62, 0x60])
            );
    }

    public function testMultipleReplacementsCanBeDifferent()
    {
        $filter = $this->createFilter([[0x61], [0x62]], [[0x63], [0x64]]);
        $this->assertEquals(
            [0x60, 0x63, 0x60, 0x64, 0x60],
            $filter->filter([0x60, 0x61, 0x60, 0x62, 0x60])
            );
    }

    public function testShouldBufferReturnsFalseIfPartialMatchNotAtEndOfString()
    {
        $filter = $this->createFilter([0x0D, 0x0A], [0x0A]);
        $this->assertFalse($filter->shouldBuffer([0x61, 0x62, 0x0D, 0x0A, 0x63]),
            '%s: Filter should not buffer since x0Dx0A is the needle and is not at EOF'
            );
    }

    public function testShouldBufferReturnsTrueIfAnyOfMultipleMatchesAtEndOfString()
    {
        $filter = $this->createFilter([[0x61, 0x62], [0x63]], [0x64]);
        $this->assertTrue($filter->shouldBuffer([0x59, 0x60, 0x61]),
            '%s: Filter should buffer since 0x61 0x62 is a needle and the ending '.
            '0x61 could be from 0x61 0x62'
            );
    }

    public function testConvertingAllLineEndingsToCRLFWhenInputIsLF()
    {
        $filter = $this->createFilter(
            [[0x0D, 0x0A], [0x0D], [0x0A]],
            [[0x0A], [0x0A], [0x0D, 0x0A]]
            );

        $this->assertEquals(
            [0x60, 0x0D, 0x0A, 0x61, 0x0D, 0x0A, 0x62, 0x0D, 0x0A, 0x63],
            $filter->filter([0x60, 0x0A, 0x61, 0x0A, 0x62, 0x0A, 0x63])
            );
    }

    public function testConvertingAllLineEndingsToCRLFWhenInputIsCR()
    {
        $filter = $this->createFilter(
            [[0x0D, 0x0A], [0x0D], [0x0A]],
            [[0x0A], [0x0A], [0x0D, 0x0A]]
            );

        $this->assertEquals(
            [0x60, 0x0D, 0x0A, 0x61, 0x0D, 0x0A, 0x62, 0x0D, 0x0A, 0x63],
            $filter->filter([0x60, 0x0D, 0x61, 0x0D, 0x62, 0x0D, 0x63])
            );
    }

    public function testConvertingAllLineEndingsToCRLFWhenInputIsCRLF()
    {
        $filter = $this->createFilter(
            [[0x0D, 0x0A], [0x0D], [0x0A]],
            [[0x0A], [0x0A], [0x0D, 0x0A]]
            );

        $this->assertEquals(
            [0x60, 0x0D, 0x0A, 0x61, 0x0D, 0x0A, 0x62, 0x0D, 0x0A, 0x63],
            $filter->filter([0x60, 0x0D, 0x0A, 0x61, 0x0D, 0x0A, 0x62, 0x0D, 0x0A, 0x63])
            );
    }

    public function testConvertingAllLineEndingsToCRLFWhenInputIsLFCR()
    {
        $filter = $this->createFilter(
            [[0x0D, 0x0A], [0x0D], [0x0A]],
            [[0x0A], [0x0A], [0x0D, 0x0A]]
            );

        $this->assertEquals(
            [0x60, 0x0D, 0x0A, 0x0D, 0x0A, 0x61, 0x0D, 0x0A, 0x0D, 0x0A, 0x62, 0x0D, 0x0A, 0x0D, 0x0A, 0x63],
            $filter->filter([0x60, 0x0A, 0x0D, 0x61, 0x0A, 0x0D, 0x62, 0x0A, 0x0D, 0x63])
            );
    }

    public function testConvertingAllLineEndingsToCRLFWhenInputContainsLFLF()
    {
        //Lighthouse Bug #23

        $filter = $this->createFilter(
            [[0x0D, 0x0A], [0x0D], [0x0A]],
            [[0x0A], [0x0A], [0x0D, 0x0A]]
            );

        $this->assertEquals(
            [0x60, 0x0D, 0x0A, 0x0D, 0x0A, 0x61, 0x0D, 0x0A, 0x0D, 0x0A, 0x62, 0x0D, 0x0A, 0x0D, 0x0A, 0x63],
            $filter->filter([0x60, 0x0A, 0x0A, 0x61, 0x0A, 0x0A, 0x62, 0x0A, 0x0A, 0x63])
            );
    }

    private function createFilter($search, $replace)
    {
        return new Swift_StreamFilters_ByteArrayReplacementFilter($search, $replace);
    }
}


================================================
FILE: tests/unit/Swift/StreamFilters/StringReplacementFilterFactoryTest.php
================================================
<?php

class Swift_StreamFilters_StringReplacementFilterFactoryTest extends \PHPUnit\Framework\TestCase
{
    public function testInstancesOfStringReplacementFilterAreCreated()
    {
        $factory = $this->createFactory();
        $this->assertInstanceOf(
            'Swift_StreamFilters_StringReplacementFilter',
            $factory->createFilter('a', 'b')
        );
    }

    public function testSameInstancesAreCached()
    {
        $factory = $this->createFactory();
        $filter1 = $factory->createFilter('a', 'b');
        $filter2 = $factory->createFilter('a', 'b');
        $this->assertSame($filter1, $filter2, '%s: Instances should be cached');
    }

    public function testDifferingInstancesAreNotCached()
    {
        $factory = $this->createFactory();
        $filter1 = $factory->createFilter('a', 'b');
        $filter2 = $factory->createFilter('a', 'c');
        $this->assertNotEquals($filter1, $filter2,
            '%s: Differing instances should not be cached'
            );
    }

    private function createFactory()
    {
        return new Swift_StreamFilters_StringReplacementFilterFactory();
    }
}


================================================
FILE: tests/unit/Swift/StreamFilters/StringReplacementFilterTest.php
================================================
<?php

class Swift_StreamFilters_StringReplacementFilterTest extends \PHPUnit\Framework\TestCase
{
    public function testBasicReplacementsAreMade()
    {
        $filter = $this->createFilter('foo', 'bar');
        $this->assertEquals('XbarYbarZ', $filter->filter('XfooYfooZ'));
    }

    public function testShouldBufferReturnsTrueIfPartialMatchAtEndOfBuffer()
    {
        $filter = $this->createFilter('foo', 'bar');
        $this->assertTrue($filter->shouldBuffer('XfooYf'),
            '%s: Filter should buffer since "foo" is the needle and the ending '.
            '"f" could be from "foo"'
            );
    }

    public function testFilterCanMakeMultipleReplacements()
    {
        $filter = $this->createFilter(['a', 'b'], 'foo');
        $this->assertEquals('XfooYfooZ', $filter->filter('XaYbZ'));
    }

    public function testMultipleReplacementsCanBeDifferent()
    {
        $filter = $this->createFilter(['a', 'b'], ['foo', 'zip']);
        $this->assertEquals('XfooYzipZ', $filter->filter('XaYbZ'));
    }

    public function testShouldBufferReturnsFalseIfPartialMatchNotAtEndOfString()
    {
        $filter = $this->createFilter("\r\n", "\n");
        $this->assertFalse($filter->shouldBuffer("foo\r\nbar"),
            '%s: Filter should not buffer since x0Dx0A is the needle and is not at EOF'
            );
    }

    public function testShouldBufferReturnsTrueIfAnyOfMultipleMatchesAtEndOfString()
    {
        $filter = $this->createFilter(['foo', 'zip'], 'bar');
        $this->assertTrue($filter->shouldBuffer('XfooYzi'),
            '%s: Filter should buffer since "zip" is a needle and the ending '.
            '"zi" could be from "zip"'
            );
    }

    public function testShouldBufferReturnsFalseOnEmptyBuffer()
    {
        $filter = $this->createFilter("\r\n", "\n");
        $this->assertFalse($filter->shouldBuffer(''));
    }

    private function createFilter($search, $replace)
    {
        return new Swift_StreamFilters_StringReplacementFilter($search, $replace);
    }
}


================================================
FILE: tests/unit/Swift/Transport/AbstractSmtpEventSupportTest.php
================================================
<?php

require_once __DIR__.'/AbstractSmtpTest.php';

abstract class Swift_Transport_AbstractSmtpEventSupportTest extends Swift_Transport_AbstractSmtpTest
{
    public function testRegisterPluginLoadsPluginInEventDispatcher()
    {
        $buf = $this->getBuffer();
        $dispatcher = $this->createEventDispatcher(false);
        $listener = $this->getMockery('Swift_Events_EventListener');
        $smtp = $this->getTransport($buf, $dispatcher);
        $dispatcher->shouldReceive('bindEventListener')
                   ->once()
                   ->with($listener);

        $smtp->registerPlugin($listener);
    }

    public function testSendingDispatchesBeforeSendEvent()
    {
        $buf = $this->getBuffer();
        $dispatcher = $this->createEventDispatcher(false);
        $message = $this->createMessage();
        $smtp = $this->getTransport($buf, $dispatcher);
        $evt = $this->getMockery('Swift_Events_SendEvent')->shouldIgnoreMissing();

        $message->shouldReceive('getFrom')
                ->zeroOrMoreTimes()
                ->andReturn(['chris@swiftmailer.org' => null]);
        $message->shouldReceive('getTo')
                ->zeroOrMoreTimes()
                ->andReturn(['mark@swiftmailer.org' => 'Mark']);
        $dispatcher->shouldReceive('createSendEvent')
                   ->once()
                   ->andReturn($evt);
        $dispatcher->shouldReceive('dispatchEvent')
                   ->once()
                   ->with($evt, 'beforeSendPerformed');
        $dispatcher->shouldReceive('dispatchEvent')
                   ->zeroOrMoreTimes();
        $evt->shouldReceive('bubbleCancelled')
            ->zeroOrMoreTimes()
            ->andReturn(false);

        $this->finishBuffer($buf);
        $smtp->start();
        $this->assertEquals(1, $smtp->send($message));
    }

    public function testSendingDispatchesSendEvent()
    {
        $buf = $this->getBuffer();
        $dispatcher = $this->createEventDispatcher(false);
        $message = $this->createMessage();
        $smtp = $this->getTransport($buf, $dispatcher);
        $evt = $this->getMockery('Swift_Events_SendEvent')->shouldIgnoreMissing();

        $message->shouldReceive('getFrom')
                ->zeroOrMoreTimes()
                ->andReturn(['chris@swiftmailer.org' => null]);
        $message->shouldReceive('getTo')
                ->zeroOrMoreTimes()
                ->andReturn(['mark@swiftmailer.org' => 'Mark']);
        $dispatcher->shouldReceive('createSendEvent')
                   ->once()
                   ->andReturn($evt);
        $dispatcher->shouldReceive('dispatchEvent')
                   ->once()
                   ->with($evt, 'sendPerformed');
        $dispatcher->shouldReceive('dispatchEvent')
                   ->zeroOrMoreTimes();
        $evt->shouldReceive('bubbleCancelled')
            ->zeroOrMoreTimes()
            ->andReturn(false);

        $this->finishBuffer($buf);
        $smtp->start();
        $this->assertEquals(1, $smtp->send($message));
    }

    public function testSendEventCapturesFailures()
    {
        $buf = $this->getBuffer();
        $dispatcher = $this->createEventDispatcher(false);
        $evt = $this->getMockery('Swift_Events_SendEvent')->shouldIgnoreMissing();
        $smtp = $this->getTransport($buf, $dispatcher);
        $message = $this->createMessage();

        $message->shouldReceive('getFrom')
                ->zeroOrMoreTimes()
                ->andReturn(['chris@swiftmailer.org' => null]);
        $message->shouldReceive('getTo')
                ->zeroOrMoreTimes()
                ->andReturn(['mark@swiftmailer.org' => 'Mark']);
        $buf->shouldReceive('write')
            ->once()
            ->with("MAIL FROM:<chris@swiftmailer.org>\r\n")
            ->andReturn(1);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(1)
            ->andReturn("250 OK\r\n");
        $buf->shouldReceive('write')
            ->once()
            ->with("RCPT TO:<mark@swiftmailer.org>\r\n")
            ->andReturn(2);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(2)
            ->andReturn("500 Not now\r\n");
        $dispatcher->shouldReceive('createSendEvent')
                   ->zeroOrMoreTimes()
                   ->with($smtp, \Mockery::any())
                   ->andReturn($evt);
        $dispatcher->shouldReceive('dispatchEvent')
                   ->once()
                   ->with($evt, 'sendPerformed');
        $dispatcher->shouldReceive('dispatchEvent')
                   ->zeroOrMoreTimes();
        $evt->shouldReceive('bubbleCancelled')
            ->zeroOrMoreTimes()
            ->andReturn(false);
        $evt->shouldReceive('setFailedRecipients')
            ->once()
            ->with(['mark@swiftmailer.org']);

        $this->finishBuffer($buf);
        $smtp->start();
        $this->assertEquals(0, $smtp->send($message));
    }

    public function testSendEventHasResultFailedIfAllFailures()
    {
        $buf = $this->getBuffer();
        $dispatcher = $this->createEventDispatcher(false);
        $evt = $this->getMockery('Swift_Events_SendEvent')->shouldIgnoreMissing();
        $smtp = $this->getTransport($buf, $dispatcher);
        $message = $this->createMessage();

        $message->shouldReceive('getFrom')
                ->zeroOrMoreTimes()
                ->andReturn(['chris@swiftmailer.org' => null]);
        $message->shouldReceive('getTo')
                ->zeroOrMoreTimes()
                ->andReturn(['mark@swiftmailer.org' => 'Mark']);
        $buf->shouldReceive('write')
            ->once()
            ->with("MAIL FROM:<chris@swiftmailer.org>\r\n")
            ->andReturn(1);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(1)
            ->andReturn("250 OK\r\n");
        $buf->shouldReceive('write')
            ->once()
            ->with("RCPT TO:<mark@swiftmailer.org>\r\n")
            ->andReturn(2);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(2)
            ->andReturn("500 Not now\r\n");
        $dispatcher->shouldReceive('createSendEvent')
                   ->zeroOrMoreTimes()
                   ->with($smtp, \Mockery::any())
                   ->andReturn($evt);
        $dispatcher->shouldReceive('dispatchEvent')
                   ->once()
                   ->with($evt, 'sendPerformed');
        $dispatcher->shouldReceive('dispatchEvent')
                   ->zeroOrMoreTimes();
        $evt->shouldReceive('bubbleCancelled')
            ->zeroOrMoreTimes()
            ->andReturn(false);
        $evt->shouldReceive('setResult')
            ->once()
            ->with(Swift_Events_SendEvent::RESULT_FAILED);

        $this->finishBuffer($buf);
        $smtp->start();
        $this->assertEquals(0, $smtp->send($message));
    }

    public function testSendEventHasResultTentativeIfSomeFailures()
    {
        $buf = $this->getBuffer();
        $dispatcher = $this->createEventDispatcher(false);
        $evt = $this->getMockery('Swift_Events_SendEvent')->shouldIgnoreMissing();
        $smtp = $this->getTransport($buf, $dispatcher);
        $message = $this->createMessage();

        $message->shouldReceive('getFrom')
                ->zeroOrMoreTimes()
                ->andReturn(['chris@swiftmailer.org' => null]);
        $message->shouldReceive('getTo')
                ->zeroOrMoreTimes()
                ->andReturn([
                    'mark@swiftmailer.org' => 'Mark',
                    'chris@site.tld' => 'Chris',
                ]);
        $buf->shouldReceive('write')
            ->once()
            ->with("MAIL FROM:<chris@swiftmailer.org>\r\n")
            ->andReturn(1);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(1)
            ->andReturn("250 OK\r\n");
        $buf->shouldReceive('write')
            ->once()
            ->with("RCPT TO:<mark@swiftmailer.org>\r\n")
            ->andReturn(2);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(2)
            ->andReturn("500 Not now\r\n");
        $dispatcher->shouldReceive('createSendEvent')
                   ->zeroOrMoreTimes()
                   ->with($smtp, \Mockery::any())
                   ->andReturn($evt);
        $dispatcher->shouldReceive('dispatchEvent')
                   ->once()
                   ->with($evt, 'sendPerformed');
        $dispatcher->shouldReceive('dispatchEvent')
                   ->zeroOrMoreTimes();
        $evt->shouldReceive('bubbleCancelled')
            ->zeroOrMoreTimes()
            ->andReturn(false);
        $evt->shouldReceive('setResult')
            ->once()
            ->with(Swift_Events_SendEvent::RESULT_TENTATIVE);

        $this->finishBuffer($buf);
        $smtp->start();
        $this->assertEquals(1, $smtp->send($message));
    }

    public function testSendEventHasResultSuccessIfNoFailures()
    {
        $buf = $this->getBuffer();
        $dispatcher = $this->createEventDispatcher(false);
        $evt = $this->getMockery('Swift_Events_SendEvent')->shouldIgnoreMissing();
        $smtp = $this->getTransport($buf, $dispatcher);
        $message = $this->createMessage();

        $message->shouldReceive('getFrom')
                ->zeroOrMoreTimes()
                ->andReturn(['chris@swiftmailer.org' => null]);
        $message->shouldReceive('getTo')
                ->zeroOrMoreTimes()
                ->andReturn([
                    'mark@swiftmailer.org' => 'Mark',
                    'chris@site.tld' => 'Chris',
                ]);
        $dispatcher->shouldReceive('createSendEvent')
                   ->zeroOrMoreTimes()
                   ->with($smtp, \Mockery::any())
                   ->andReturn($evt);
        $dispatcher->shouldReceive('dispatchEvent')
                   ->once()
                   ->with($evt, 'sendPerformed');
        $dispatcher->shouldReceive('dispatchEvent')
                   ->zeroOrMoreTimes();
        $evt->shouldReceive('bubbleCancelled')
            ->zeroOrMoreTimes()
            ->andReturn(false);
        $evt->shouldReceive('setResult')
            ->once()
            ->with(Swift_Events_SendEvent::RESULT_SUCCESS);

        $this->finishBuffer($buf);
        $smtp->start();
        $this->assertEquals(2, $smtp->send($message));
    }

    public function testCancellingEventBubbleBeforeSendStopsEvent()
    {
        $buf = $this->getBuffer();
        $dispatcher = $this->createEventDispatcher(false);
        $evt = $this->getMockery('Swift_Events_SendEvent')->shouldIgnoreMissing();
        $smtp = $this->getTransport($buf, $dispatcher);
        $message = $this->createMessage();

        $message->shouldReceive('getFrom')
                ->zeroOrMoreTimes()
                ->andReturn(['chris@swiftmailer.org' => null]);
        $message->shouldReceive('getTo')
                ->zeroOrMoreTimes()
                ->andReturn(['mark@swiftmailer.org' => 'Mark']);
        $dispatcher->shouldReceive('createSendEvent')
                   ->zeroOrMoreTimes()
                   ->with($smtp, \Mockery::any())
                   ->andReturn($evt);
        $dispatcher->shouldReceive('dispatchEvent')
                   ->once()
                   ->with($evt, 'beforeSendPerformed');
        $dispatcher->shouldReceive('dispatchEvent')
                   ->zeroOrMoreTimes();
        $evt->shouldReceive('bubbleCancelled')
            ->atLeast()->once()
            ->andReturn(true);

        $this->finishBuffer($buf);
        $smtp->start();
        $this->assertEquals(0, $smtp->send($message));
    }

    public function testStartingTransportDispatchesTransportChangeEvent()
    {
        $buf = $this->getBuffer();
        $dispatcher = $this->createEventDispatcher(false);
        $evt = $this->getMockery('Swift_Events_TransportChangeEvent');
        $smtp = $this->getTransport($buf, $dispatcher);

        $dispatcher->shouldReceive('createTransportChangeEvent')
                   ->atLeast()->once()
                   ->with($smtp)
                   ->andReturn($evt);
        $dispatcher->shouldReceive('dispatchEvent')
                   ->once()
                   ->with($evt, 'transportStarted');
        $dispatcher->shouldReceive('dispatchEvent')
                   ->zeroOrMoreTimes();
        $evt->shouldReceive('bubbleCancelled')
            ->atLeast()->once()
            ->andReturn(false);

        $this->finishBuffer($buf);
        $smtp->start();
    }

    public function testStartingTransportDispatchesBeforeTransportChangeEvent()
    {
        $buf = $this->getBuffer();
        $dispatcher = $this->createEventDispatcher(false);
        $evt = $this->getMockery('Swift_Events_TransportChangeEvent');
        $smtp = $this->getTransport($buf, $dispatcher);

        $dispatcher->shouldReceive('createTransportChangeEvent')
                   ->atLeast()->once()
                   ->with($smtp)
                   ->andReturn($evt);
        $dispatcher->shouldReceive('dispatchEvent')
                   ->once()
                   ->with($evt, 'beforeTransportStarted');
        $dispatcher->shouldReceive('dispatchEvent')
                   ->zeroOrMoreTimes();
        $evt->shouldReceive('bubbleCancelled')
            ->atLeast()->once()
            ->andReturn(false);

        $this->finishBuffer($buf);
        $smtp->start();
    }

    public function testCancellingBubbleBeforeTransportStartStopsEvent()
    {
        $buf = $this->getBuffer();
        $dispatcher = $this->createEventDispatcher(false);
        $evt = $this->getMockery('Swift_Events_TransportChangeEvent');
        $smtp = $this->getTransport($buf, $dispatcher);

        $dispatcher->shouldReceive('createTransportChangeEvent')
                   ->atLeast()->once()
                   ->with($smtp)
                   ->andReturn($evt);
        $dispatcher->shouldReceive('dispatchEvent')
                   ->once()
                   ->with($evt, 'beforeTransportStarted');
        $dispatcher->shouldReceive('dispatchEvent')
                   ->zeroOrMoreTimes();
        $evt->shouldReceive('bubbleCancelled')
            ->atLeast()->once()
            ->andReturn(true);

        $this->finishBuffer($buf);
        $smtp->start();

        $this->assertFalse($smtp->isStarted(),
            '%s: Transport should not be started since event bubble was cancelled'
        );
    }

    public function testStoppingTransportDispatchesTransportChangeEvent()
    {
        $buf = $this->getBuffer();
        $dispatcher = $this->createEventDispatcher(false);
        $evt = $this->getMockery('Swift_Events_TransportChangeEvent')->shouldIgnoreMissing();
        $smtp = $this->getTransport($buf, $dispatcher);

        $dispatcher->shouldReceive('createTransportChangeEvent')
                   ->atLeast()->once()
                   ->with($smtp)
                   ->andReturn($evt);
        $dispatcher->shouldReceive('dispatchEvent')
                   ->once()
                   ->with($evt, 'transportStopped');
        $dispatcher->shouldReceive('dispatchEvent')
                   ->zeroOrMoreTimes();

        $this->finishBuffer($buf);
        $smtp->start();
        $smtp->stop();
    }

    public function testStoppingTransportDispatchesBeforeTransportChangeEvent()
    {
        $buf = $this->getBuffer();
        $dispatcher = $this->createEventDispatcher(false);
        $evt = $this->getMockery('Swift_Events_TransportChangeEvent')->shouldIgnoreMissing();
        $smtp = $this->getTransport($buf, $dispatcher);

        $dispatcher->shouldReceive('createTransportChangeEvent')
                   ->atLeast()->once()
                   ->with($smtp)
                   ->andReturn($evt);
        $dispatcher->shouldReceive('dispatchEvent')
                   ->once()
                   ->with($evt, 'beforeTransportStopped');
        $dispatcher->shouldReceive('dispatchEvent')
                   ->zeroOrMoreTimes();

        $this->finishBuffer($buf);
        $smtp->start();
        $smtp->stop();
    }

    public function testCancellingBubbleBeforeTransportStoppedStopsEvent()
    {
        $buf = $this->getBuffer();
        $dispatcher = $this->createEventDispatcher(false);
        $evt = $this->getMockery('Swift_Events_TransportChangeEvent');
        $smtp = $this->getTransport($buf, $dispatcher);

        $hasRun = false;
        $dispatcher->shouldReceive('createTransportChangeEvent')
                   ->atLeast()->once()
                   ->with($smtp)
                   ->andReturn($evt);
        $dispatcher->shouldReceive('dispatchEvent')
                   ->once()
                   ->with($evt, 'beforeTransportStopped')
                   ->andReturnUsing(function () use (&$hasRun) {
                       $hasRun = true;
                   });
        $dispatcher->shouldReceive('dispatchEvent')
                   ->zeroOrMoreTimes();
        $evt->shouldReceive('bubbleCancelled')
            ->zeroOrMoreTimes()
            ->andReturnUsing(function () use (&$hasRun) {
                return $hasRun;
            });

        $this->finishBuffer($buf);
        $smtp->start();
        $smtp->stop();

        $this->assertTrue($smtp->isStarted(),
            '%s: Transport should not be stopped since event bubble was cancelled'
        );
    }

    public function testResponseEventsAreGenerated()
    {
        $buf = $this->getBuffer();
        $dispatcher = $this->createEventDispatcher(false);
        $evt = $this->getMockery('Swift_Events_ResponseEvent');
        $smtp = $this->getTransport($buf, $dispatcher);

        $dispatcher->shouldReceive('createResponseEvent')
                   ->atLeast()->once()
                   ->with($smtp, \Mockery::any(), \Mockery::any())
                   ->andReturn($evt);
        $dispatcher->shouldReceive('dispatchEvent')
                   ->atLeast()->once()
                   ->with($evt, 'responseReceived');

        $this->finishBuffer($buf);
        $smtp->start();
    }

    public function testCommandEventsAreGenerated()
    {
        $buf = $this->getBuffer();
        $dispatcher = $this->createEventDispatcher(false);
        $evt = $this->getMockery('Swift_Events_CommandEvent');
        $smtp = $this->getTransport($buf, $dispatcher);

        $dispatcher->shouldReceive('createCommandEvent')
                   ->once()
                   ->with($smtp, \Mockery::any(), \Mockery::any())
                   ->andReturn($evt);
        $dispatcher->shouldReceive('dispatchEvent')
                   ->once()
                   ->with($evt, 'commandSent');

        $this->finishBuffer($buf);
        $smtp->start();
    }

    public function testExceptionsCauseExceptionEvents()
    {
        $buf = $this->getBuffer();
        $dispatcher = $this->createEventDispatcher(false);
        $evt = $this->getMockery('Swift_Events_TransportExceptionEvent');
        $smtp = $this->getTransport($buf, $dispatcher);

        $buf->shouldReceive('readLine')
            ->atLeast()->once()
            ->andReturn("503 I'm sleepy, go away!\r\n");
        $dispatcher->shouldReceive('createTransportExceptionEvent')
                   ->zeroOrMoreTimes()
                   ->with($smtp, \Mockery::any())
                   ->andReturn($evt);
        $dispatcher->shouldReceive('dispatchEvent')
                   ->once()
                   ->with($evt, 'exceptionThrown');
        $evt->shouldReceive('bubbleCancelled')
            ->atLeast()->once()
            ->andReturn(false);

        try {
            $smtp->start();
            $this->fail('TransportException should be thrown on invalid response');
        } catch (Swift_TransportException $e) {
        }
    }

    public function testExceptionBubblesCanBeCancelled()
    {
        $buf = $this->getBuffer();
        $dispatcher = $this->createEventDispatcher(false);
        $evt = $this->getMockery('Swift_Events_TransportExceptionEvent');
        $smtp = $this->getTransport($buf, $dispatcher);

        $buf->shouldReceive('readLine')
            ->atLeast()->once()
            ->andReturn("503 I'm sleepy, go away!\r\n");
        $dispatcher->shouldReceive('createTransportExceptionEvent')
                   ->twice()
                   ->with($smtp, \Mockery::any())
                   ->andReturn($evt);
        $dispatcher->shouldReceive('dispatchEvent')
                   ->twice()
                   ->with($evt, 'exceptionThrown');
        $evt->shouldReceive('bubbleCancelled')
            ->atLeast()->once()
            ->andReturn(true);

        $this->finishBuffer($buf);
        $smtp->start();
    }

    protected function createEventDispatcher($stub = true)
    {
        return $this->getMockery('Swift_Events_EventDispatcher')->shouldIgnoreMissing();
    }
}


================================================
FILE: tests/unit/Swift/Transport/AbstractSmtpTest.php
================================================
<?php

abstract class Swift_Transport_AbstractSmtpTest extends \SwiftMailerTestCase
{
    abstract protected function getTransport($buf);

    public function testStartAccepts220ServiceGreeting()
    {
        /* -- RFC 2821, 4.2.

     Greeting = "220 " Domain [ SP text ] CRLF

     -- RFC 2822, 4.3.2.

     CONNECTION ESTABLISHMENT
         S: 220
         E: 554
        */

        $buf = $this->getBuffer();
        $smtp = $this->getTransport($buf);
        $buf->shouldReceive('initialize')
            ->once();
        $buf->shouldReceive('readLine')
            ->once()
            ->with(0)
            ->andReturn("220 some.server.tld bleh\r\n");

        $this->finishBuffer($buf);
        try {
            $this->assertFalse($smtp->isStarted(), '%s: SMTP should begin non-started');
            $smtp->start();
            $this->assertTrue($smtp->isStarted(), '%s: start() should have started connection');
        } catch (Exception $e) {
            $this->fail('220 is a valid SMTP greeting and should be accepted');
        }
    }

    public function testBadGreetingCausesException()
    {
        $buf = $this->getBuffer();
        $smtp = $this->getTransport($buf);
        $buf->shouldReceive('initialize')
            ->once();
        $buf->shouldReceive('readLine')
            ->once()
            ->with(0)
            ->andReturn("554 I'm busy\r\n");
        $this->finishBuffer($buf);
        try {
            $this->assertFalse($smtp->isStarted(), '%s: SMTP should begin non-started');
            $smtp->start();
            $this->fail('554 greeting indicates an error and should cause an exception');
        } catch (Swift_TransportException $e) {
            $this->assertFalse($smtp->isStarted(), '%s: start() should have failed');
        }
    }

    public function testStartSendsHeloToInitiate()
    {
        /* -- RFC 2821, 3.2.

            3.2 Client Initiation

         Once the server has sent the welcoming message and the client has
         received it, the client normally sends the EHLO command to the
         server, indicating the client's identity.  In addition to opening the
         session, use of EHLO indicates that the client is able to process
         service extensions and requests that the server provide a list of the
         extensions it supports.  Older SMTP systems which are unable to
         support service extensions and contemporary clients which do not
         require service extensions in the mail session being initiated, MAY
         use HELO instead of EHLO.  Servers MUST NOT return the extended
         EHLO-style response to a HELO command.  For a particular connection
         attempt, if the server returns a "command not recognized" response to
         EHLO, the client SHOULD be able to fall back and send HELO.

         In the EHLO command the host sending the command identifies itself;
         the command may be interpreted as saying "Hello, I am <domain>" (and,
         in the case of EHLO, "and I support service extension requests").

       -- RFC 2281, 4.1.1.1.

       ehlo            = "EHLO" SP Domain CRLF
       helo            = "HELO" SP Domain CRLF

       -- RFC 2821, 4.3.2.

       EHLO or HELO
           S: 250
           E: 504, 550

     */

        $buf = $this->getBuffer();
        $smtp = $this->getTransport($buf);

        $buf->shouldReceive('initialize')
            ->once();
        $buf->shouldReceive('readLine')
            ->once()
            ->with(0)
            ->andReturn("220 some.server.tld bleh\r\n");
        $buf->shouldReceive('write')
            ->once()
            ->with(Mockery::pattern('~^HELO example.org\r\n$~D'))
            ->andReturn(1);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(1)
            ->andReturn('250 ServerName'."\r\n");

        $this->finishBuffer($buf);
        try {
            $smtp->start();
        } catch (Exception $e) {
            $this->fail('Starting SMTP should send HELO and accept 250 response');
        }
    }

    public function testInvalidHeloResponseCausesException()
    {
        $buf = $this->getBuffer();
        $smtp = $this->getTransport($buf);

        $buf->shouldReceive('initialize')
            ->once();
        $buf->shouldReceive('readLine')
            ->once()
            ->with(0)
            ->andReturn("220 some.server.tld bleh\r\n");
        $buf->shouldReceive('write')
            ->once()
            ->with(Mockery::pattern('~^HELO example.org\r\n$~D'))
            ->andReturn(1);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(1)
            ->andReturn('504 WTF'."\r\n");

        $this->finishBuffer($buf);
        try {
            $this->assertFalse($smtp->isStarted(), '%s: SMTP should begin non-started');
            $smtp->start();
            $this->fail('Non 250 HELO response should raise Exception');
        } catch (Swift_TransportException $e) {
            $this->assertFalse($smtp->isStarted(), '%s: SMTP start() should have failed');
        }
    }

    public function testDomainNameIsPlacedInHelo()
    {
        /* -- RFC 2821, 4.1.4.

       The SMTP client MUST, if possible, ensure that the domain parameter
       to the EHLO command is a valid principal host name (not a CNAME or MX
       name) for its host.  If this is not possible (e.g., when the client's
       address is dynamically assigned and the client does not have an
       obvious name), an address literal SHOULD be substituted for the
       domain name and supplemental information provided that will assist in
       identifying the client.
        */

        $buf = $this->getBuffer();
        $smtp = $this->getTransport($buf);

        $buf->shouldReceive('initialize')
            ->once();
        $buf->shouldReceive('readLine')
            ->once()
            ->with(0)
            ->andReturn("220 some.server.tld bleh\r\n");
        $buf->shouldReceive('write')
            ->once()
            ->with("HELO mydomain.com\r\n")
            ->andReturn(1);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(1)
            ->andReturn('250 ServerName'."\r\n");

        $this->finishBuffer($buf);
        $smtp->setLocalDomain('mydomain.com');
        $smtp->start();
    }

    public function testSuccessfulMailCommand()
    {
        /* -- RFC 2821, 3.3.

        There are three steps to SMTP mail transactions.  The transaction
        starts with a MAIL command which gives the sender identification.

        .....

        The first step in the procedure is the MAIL command.

            MAIL FROM:<reverse-path> [SP <mail-parameters> ] <CRLF>

        -- RFC 2821, 4.1.1.2.

        Syntax:

            "MAIL FROM:" ("<>" / Reverse-Path)
                       [SP Mail-parameters] CRLF
        -- RFC 2821, 4.1.2.

        Reverse-path = Path
            Forward-path = Path
            Path = "<" [ A-d-l ":" ] Mailbox ">"
            A-d-l = At-domain *( "," A-d-l )
                        ; Note that this form, the so-called "source route",
                        ; MUST BE accepted, SHOULD NOT be generated, and SHOULD be
                        ; ignored.
            At-domain = "@" domain

        -- RFC 2821, 4.3.2.

        MAIL
            S: 250
            E: 552, 451, 452, 550, 553, 503
        */

        $buf = $this->getBuffer();
        $smtp = $this->getTransport($buf);
        $message = $this->createMessage();
        $message->shouldReceive('getFrom')
                ->once()
                ->andReturn(['me@domain.com' => 'Me']);
        $message->shouldReceive('getTo')
                ->once()
                ->andReturn(['foo@bar' => null]);
        $buf->shouldReceive('initialize')
            ->once();
        $buf->shouldReceive('write')
            ->once()
            ->with("MAIL FROM:<me@domain.com>\r\n")
            ->andReturn(1);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(1)
            ->andReturn("250 OK\r\n");

        $this->finishBuffer($buf);
        try {
            $smtp->start();
            $smtp->send($message);
        } catch (Exception $e) {
            $this->fail('MAIL FROM should accept a 250 response');
        }
    }

    public function testInvalidResponseCodeFromMailCausesException()
    {
        $buf = $this->getBuffer();
        $smtp = $this->getTransport($buf);
        $message = $this->createMessage();

        $message->shouldReceive('getFrom')
                ->once()
                ->andReturn(['me@domain.com' => 'Me']);
        $message->shouldReceive('getTo')
                ->once()
                ->andReturn(['foo@bar' => null]);
        $buf->shouldReceive('write')
            ->once()
            ->with("MAIL FROM:<me@domain.com>\r\n")
            ->andReturn(1);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(1)
            ->andReturn('553 Bad'."\r\n");

        $this->finishBuffer($buf);
        try {
            $smtp->start();
            $smtp->send($message);
            $this->fail('MAIL FROM should accept a 250 response');
        } catch (Swift_TransportException $e) {
        }
    }

    public function testSenderIsPreferredOverFrom()
    {
        $buf = $this->getBuffer();
        $smtp = $this->getTransport($buf);
        $message = $this->createMessage();

        $message->shouldReceive('getFrom')
                ->once()
                ->andReturn(['me@domain.com' => 'Me']);
        $message->shouldReceive('getSender')
                ->once()
                ->andReturn(['another@domain.com' => 'Someone']);
        $message->shouldReceive('getTo')
                ->once()
                ->andReturn(['foo@bar' => null]);
        $buf->shouldReceive('write')
            ->once()
            ->with("MAIL FROM:<another@domain.com>\r\n")
            ->andReturn(1);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(1)
            ->andReturn('250 OK'."\r\n");

        $this->finishBuffer($buf);
        $smtp->start();
        $smtp->send($message);
    }

    public function testReturnPathIsPreferredOverSender()
    {
        $buf = $this->getBuffer();
        $smtp = $this->getTransport($buf);
        $message = $this->createMessage();

        $message->shouldReceive('getFrom')
                ->once()
                ->andReturn(['me@domain.com' => 'Me']);
        $message->shouldReceive('getSender')
                ->once()
                ->andReturn(['another@domain.com' => 'Someone']);
        $message->shouldReceive('getReturnPath')
                ->once()
                ->andReturn('more@domain.com');
        $message->shouldReceive('getTo')
                ->once()
                ->andReturn(['foo@bar' => null]);
        $buf->shouldReceive('write')
            ->once()
            ->with("MAIL FROM:<more@domain.com>\r\n")
            ->andReturn(1);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(1)
            ->andReturn('250 OK'."\r\n");

        $this->finishBuffer($buf);
        $smtp->start();
        $smtp->send($message);
    }

    public function testSuccessfulRcptCommandWith250Response()
    {
        /* -- RFC 2821, 3.3.

     The second step in the procedure is the RCPT command.

            RCPT TO:<forward-path> [ SP <rcpt-parameters> ] <CRLF>

     The first or only argument to this command includes a forward-path
     (normally a mailbox and domain, always surrounded by "<" and ">"
     brackets) identifying one recipient.  If accepted, the SMTP server
     returns a 250 OK reply and stores the forward-path.  If the recipient
     is known not to be a deliverable address, the SMTP server returns a
     550 reply, typically with a string such as "no such user - " and the
     mailbox name (other circumstances and reply codes are possible).
     This step of the procedure can be repeated any number of times.

        -- RFC 2821, 4.1.1.3.

        This command is used to identify an individual recipient of the mail
        data; multiple recipients are specified by multiple use of this
        command.  The argument field contains a forward-path and may contain
        optional parameters.

        The forward-path normally consists of the required destination
        mailbox.  Sending systems SHOULD not generate the optional list of
        hosts known as a source route.

        .......

        "RCPT TO:" ("<Postmaster@" domain ">" / "<Postmaster>" / Forward-Path)
                                        [SP Rcpt-parameters] CRLF

        -- RFC 2821, 4.2.2.

            250 Requested mail action okay, completed
            251 User not local; will forward to <forward-path>
         (See section 3.4)
            252 Cannot VRFY user, but will accept message and attempt
                    delivery

        -- RFC 2821, 4.3.2.

        RCPT
            S: 250, 251 (but see section 3.4 for discussion of 251 and 551)
            E: 550, 551, 552, 553, 450, 451, 452, 503, 550
        */

        //We'll treat 252 as accepted since it isn't really a failure

        $buf = $this->getBuffer();
        $smtp = $this->getTransport($buf);
        $message = $this->createMessage();

        $message->shouldReceive('getFrom')
                ->once()
                ->andReturn(['me@domain.com' => 'Me']);
        $message->shouldReceive('getTo')
                ->once()
                ->andReturn(['foo@bar' => null]);
        $buf->shouldReceive('write')
            ->once()
            ->with("MAIL FROM:<me@domain.com>\r\n")
            ->andReturn(1);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(1)
            ->andReturn('250 OK'."\r\n");
        $buf->shouldReceive('write')
            ->once()
            ->with("RCPT TO:<foo@bar>\r\n")
            ->andReturn(2);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(2)
            ->andReturn('250 OK'."\r\n");

        $this->finishBuffer($buf);
        try {
            $smtp->start();
            $smtp->send($message);
        } catch (Exception $e) {
            $this->fail('RCPT TO should accept a 250 response');
        }
    }

    public function testUtf8AddressWithIdnEncoder()
    {
        $buf = $this->getBuffer();
        $smtp = $this->getTransport($buf);
        $message = $this->createMessage();

        $message->shouldReceive('getFrom')
                ->once()
                ->andReturn(['me@dömain.com' => 'Me']);
        $message->shouldReceive('getTo')
                ->once()
                ->andReturn(['foo@bär' => null]);
        $buf->shouldReceive('write')
            ->once()
            ->with("MAIL FROM:<me@xn--dmain-jua.com>\r\n")
            ->andReturn(1);
        $buf->shouldReceive('write')
            ->once()
            ->with("RCPT TO:<foo@xn--br-via>\r\n")
            ->andReturn(1);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(1)
            ->andReturn('250 OK'."\r\n");

        $this->finishBuffer($buf);
        $smtp->start();
        $smtp->send($message);
    }

    public function testUtf8AddressWithUtf8Encoder()
    {
        $buf = $this->getBuffer();
        $smtp = $this->getTransport($buf, null, new Swift_AddressEncoder_Utf8AddressEncoder());
        $message = $this->createMessage();

        $message->shouldReceive('getFrom')
                ->once()
                ->andReturn(['më@dömain.com' => 'Me']);
        $message->shouldReceive('getTo')
                ->once()
                ->andReturn(['föö@bär' => null]);
        $buf->shouldReceive('write')
            ->once()
            ->with("MAIL FROM:<më@dömain.com>\r\n")
            ->andReturn(1);
        $buf->shouldReceive('write')
            ->once()
            ->with("RCPT TO:<föö@bär>\r\n")
            ->andReturn(1);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(1)
            ->andReturn('250 OK'."\r\n");

        $this->finishBuffer($buf);
        $smtp->start();
        $smtp->send($message);
    }

    public function testNonEncodableSenderCausesException()
    {
        $buf = $this->getBuffer();
        $smtp = $this->getTransport($buf);
        $message = $this->createMessage();

        $message->shouldReceive('getFrom')
                ->once()
                ->andReturn(['më@domain.com' => 'Me']);
        $message->shouldReceive('getTo')
                ->once()
                ->andReturn(['foo@bar' => null]);

        $this->finishBuffer($buf);
        try {
            $smtp->start();
            $smtp->send($message);
            $this->fail('më@domain.com cannot be encoded (not observed)');
        } catch (Swift_AddressEncoderException $e) {
            $this->assertEquals('më@domain.com', $e->getAddress());
        }
    }

    public function testMailFromCommandIsOnlySentOncePerMessage()
    {
        $buf = $this->getBuffer();
        $smtp = $this->getTransport($buf);
        $message = $this->createMessage();

        $message->shouldReceive('getFrom')
                ->once()
                ->andReturn(['me@domain.com' => 'Me']);
        $message->shouldReceive('getTo')
                ->once()
                ->andReturn(['foo@bar' => null]);
        $buf->shouldReceive('write')
            ->once()
            ->with("MAIL FROM:<me@domain.com>\r\n")
            ->andReturn(1);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(1)
            ->andReturn('250 OK'."\r\n");
        $buf->shouldReceive('write')
            ->once()
            ->with("RCPT TO:<foo@bar>\r\n")
            ->andReturn(2);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(2)
            ->andReturn('250 OK'."\r\n");
        $buf->shouldReceive('write')
            ->never()
            ->with("MAIL FROM:<me@domain.com>\r\n");

        $this->finishBuffer($buf);
        $smtp->start();
        $smtp->send($message);
    }

    public function testMultipleRecipientsSendsMultipleRcpt()
    {
        $buf = $this->getBuffer();
        $smtp = $this->getTransport($buf);
        $message = $this->createMessage();

        $message->shouldReceive('getFrom')
                ->once()
                ->andReturn(['me@domain.com' => 'Me']);
        $message->shouldReceive('getTo')
                ->once()
                ->andReturn([
                    'foo@bar' => null,
                    'zip@button' => 'Zip Button',
                    'test@domain' => 'Test user',
                    'tëst@domain' => 'Test user',
                ]);
        $buf->shouldReceive('write')
            ->once()
            ->with("RCPT TO:<foo@bar>\r\n")
            ->andReturn(1);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(1)
            ->andReturn('250 OK'."\r\n");
        $buf->shouldReceive('write')
            ->once()
            ->with("RCPT TO:<zip@button>\r\n")
            ->andReturn(2);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(2)
            ->andReturn('250 OK'."\r\n");
        $buf->shouldReceive('write')
            ->once()
            ->with("RCPT TO:<test@domain>\r\n")
            ->andReturn(3);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(3)
            ->andReturn('250 OK'."\r\n");

        $this->finishBuffer($buf);
        $smtp->start();
        $smtp->send($message);
    }

    public function testCcRecipientsSendsMultipleRcpt()
    {
        $buf = $this->getBuffer();
        $smtp = $this->getTransport($buf);
        $message = $this->createMessage();

        $message->shouldReceive('getFrom')
                ->once()
                ->andReturn(['me@domain.com' => 'Me']);
        $message->shouldReceive('getTo')
                ->once()
                ->andReturn(['foo@bar' => null]);
        $message->shouldReceive('getCc')
                ->once()
                ->andReturn([
                    'zip@button' => 'Zip Button',
                    'test@domain' => 'Test user',
                ]);
        $buf->shouldReceive('write')
            ->once()
            ->with("RCPT TO:<foo@bar>\r\n")
            ->andReturn(1);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(1)
            ->andReturn('250 OK'."\r\n");
        $buf->shouldReceive('write')
            ->once()
            ->with("RCPT TO:<zip@button>\r\n")
            ->andReturn(2);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(2)
            ->andReturn('250 OK'."\r\n");
        $buf->shouldReceive('write')
            ->once()
            ->with("RCPT TO:<test@domain>\r\n")
            ->andReturn(3);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(3)
            ->andReturn('250 OK'."\r\n");

        $this->finishBuffer($buf);
        $smtp->start();
        $smtp->send($message);
    }

    public function testSendReturnsNumberOfSuccessfulRecipients()
    {
        $buf = $this->getBuffer();
        $smtp = $this->getTransport($buf);
        $message = $this->createMessage();

        $message->shouldReceive('getFrom')
                ->once()
                ->andReturn(['me@domain.com' => 'Me']);
        $message->shouldReceive('getTo')
                ->once()
                ->andReturn(['foo@bar' => null]);
        $message->shouldReceive('getCc')
                ->once()
                ->andReturn([
                    'zip@button' => 'Zip Button',
                    'test@domain' => 'Test user',
                ]);
        $buf->shouldReceive('write')
            ->once()
            ->with("RCPT TO:<foo@bar>\r\n")
            ->andReturn(1);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(1)
            ->andReturn('250 OK'."\r\n");
        $buf->shouldReceive('write')
            ->once()
            ->with("RCPT TO:<zip@button>\r\n")
            ->andReturn(2);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(2)
            ->andReturn('501 Nobody here'."\r\n");
        $buf->shouldReceive('write')
            ->once()
            ->with("RCPT TO:<test@domain>\r\n")
            ->andReturn(3);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(3)
            ->andReturn('250 OK'."\r\n");

        $this->finishBuffer($buf);
        $smtp->start();
        $this->assertEquals(2, $smtp->send($message),
            '%s: 1 of 3 recipients failed so 2 should be returned'
            );
    }

    public function testRsetIsSentIfNoSuccessfulRecipients()
    {
        /* --RFC 2821, 4.1.1.5.

        This command specifies that the current mail transaction will be
        aborted.  Any stored sender, recipients, and mail data MUST be
        discarded, and all buffers and state tables cleared.  The receiver
        MUST send a "250 OK" reply to a RSET command with no arguments.  A
        reset command may be issued by the client at any time.

        -- RFC 2821, 4.3.2.

        RSET
            S: 250
        */

        $buf = $this->getBuffer();
        $smtp = $this->getTransport($buf);
        $message = $this->createMessage();

        $message->shouldReceive('getFrom')
                ->once()
                ->andReturn(['me@domain.com' => 'Me']);
        $message->shouldReceive('getTo')
                ->once()
                ->andReturn(['foo@bar' => null]);
        $buf->shouldReceive('write')
            ->once()
            ->with("RCPT TO:<foo@bar>\r\n")
            ->andReturn(1);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(1)
            ->andReturn('503 Bad'."\r\n");
        $buf->shouldReceive('write')
            ->once()
            ->with("RSET\r\n")
            ->andReturn(2);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(2)
            ->andReturn('250 OK'."\r\n");

        $this->finishBuffer($buf);
        $smtp->start();
        $this->assertEquals(0, $smtp->send($message),
            '%s: 1 of 1 recipients failed so 0 should be returned'
            );
    }

    public function testSuccessfulDataCommand()
    {
        /* -- RFC 2821, 3.3.

        The third step in the procedure is the DATA command (or some
        alternative specified in a service extension).

                    DATA <CRLF>

        If accepted, the SMTP server returns a 354 Intermediate reply and
        considers all succeeding lines up to but not including the end of
        mail data indicator to be the message text.

        -- RFC 2821, 4.1.1.4.

        The receiver normally sends a 354 response to DATA, and then treats
        the lines (strings ending in <CRLF> sequences, as described in
        section 2.3.7) following the command as mail data from the sender.
        This command causes the mail data to be appended to the mail data
        buffer.  The mail data may contain any of the 128 ASCII character
        codes, although experience has indicated that use of control
        characters other than SP, HT, CR, and LF may cause problems and
        SHOULD be avoided when possible.

        -- RFC 2821, 4.3.2.

        DATA
            I: 354 -> data -> S: 250
                                                E: 552, 554, 451, 452
            E: 451, 554, 503
        */

        $buf = $this->getBuffer();
        $smtp = $this->getTransport($buf);
        $message = $this->createMessage();

        $message->shouldReceive('getFrom')
                ->once()
                ->andReturn(['me@domain.com' => 'Me']);
        $message->shouldReceive('getTo')
                ->once()
                ->andReturn(['foo@bar' => null]);
        $buf->shouldReceive('write')
            ->once()
            ->with("DATA\r\n")
            ->andReturn(1);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(1)
            ->andReturn('354 Go ahead'."\r\n");

        $this->finishBuffer($buf);
        try {
            $smtp->start();
            $smtp->send($message);
        } catch (Exception $e) {
            $this->fail('354 is the expected response to DATA');
        }
    }

    public function testBadDataResponseCausesException()
    {
        $buf = $this->getBuffer();
        $smtp = $this->getTransport($buf);
        $message = $this->createMessage();

        $message->shouldReceive('getFrom')
                ->once()
                ->andReturn(['me@domain.com' => 'Me']);
        $message->shouldReceive('getTo')
                ->once()
                ->andReturn(['foo@bar' => null]);
        $buf->shouldReceive('write')
            ->once()
            ->with("DATA\r\n")
            ->andReturn(1);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(1)
            ->andReturn('451 Bad'."\r\n");

        $this->finishBuffer($buf);
        try {
            $smtp->start();
            $smtp->send($message);
            $this->fail('354 is the expected response to DATA (not observed)');
        } catch (Swift_TransportException $e) {
        }
    }

    public function testMessageIsStreamedToBufferForData()
    {
        $buf = $this->getBuffer();
        $smtp = $this->getTransport($buf);
        $message = $this->createMessage();

        $message->shouldReceive('getFrom')
                ->once()
                ->andReturn(['me@domain.com' => 'Me']);
        $message->shouldReceive('getTo')
                ->once()
                ->andReturn(['foo@bar' => null]);
        $buf->shouldReceive('write')
            ->once()
            ->with("DATA\r\n")
            ->andReturn(1);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(1)
            ->andReturn('354 OK'."\r\n");
        $buf->shouldReceive('write')
            ->once()
            ->with("\r\n.\r\n")
            ->andReturn(2);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(2)
            ->andReturn('250 OK'."\r\n");

        $this->finishBuffer($buf);
        $smtp->start();
        $smtp->send($message);
    }

    public function testBadResponseAfterDataTransmissionCausesException()
    {
        $buf = $this->getBuffer();
        $smtp = $this->getTransport($buf);
        $message = $this->createMessage();

        $message->shouldReceive('getFrom')
                ->once()
                ->andReturn(['me@domain.com' => 'Me']);
        $message->shouldReceive('getTo')
                ->once()
                ->andReturn(['foo@bar' => null]);
        $buf->shouldReceive('write')
            ->once()
            ->with("DATA\r\n")
            ->andReturn(1);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(1)
            ->andReturn('354 OK'."\r\n");
        $buf->shouldReceive('write')
            ->once()
            ->with("\r\n.\r\n")
            ->andReturn(2);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(2)
            ->andReturn('554 Error'."\r\n");

        $this->finishBuffer($buf);
        try {
            $smtp->start();
            $smtp->send($message);
            $this->fail('250 is the expected response after a DATA transmission (not observed)');
        } catch (Swift_TransportException $e) {
        }
    }

    public function testBccRecipientsAreRemovedFromHeaders()
    {
        /* -- RFC 2821, 7.2.

     Addresses that do not appear in the message headers may appear in the
     RCPT commands to an SMTP server for a number of reasons.  The two
     most common involve the use of a mailing address as a "list exploder"
     (a single address that resolves into multiple addresses) and the
     appearance of "blind copies".  Especially when more than one RCPT
     command is present, and in order to avoid defeating some of the
     purpose of these mechanisms, SMTP clients and servers SHOULD NOT copy
     the full set of RCPT command arguments into the headers, either as
     part of trace headers or as informational or private-extension
     headers.  Since this rule is often violated in practice, and cannot
     be enforced, sending SMTP systems that are aware of "bcc" use MAY
     find it helpful to send each blind copy as a separate message
     transaction containing only a single RCPT command.
     */

        $buf = $this->getBuffer();
        $smtp = $this->getTransport($buf);
        $message = $this->createMessage();
        $message->shouldReceive('getFrom')
                ->zeroOrMoreTimes()
                ->andReturn(['me@domain.com' => 'Me']);
        $message->shouldReceive('getTo')
                ->zeroOrMoreTimes()
                ->andReturn(['foo@bar' => null]);
        $message->shouldReceive('getBcc')
                ->zeroOrMoreTimes()
                ->andReturn([
                    'zip@button' => 'Zip Button',
                    'test@domain' => 'Test user',
                ]);
        $message->shouldReceive('setBcc')
                ->once()
                ->with([]);
        $message->shouldReceive('setBcc')
                ->zeroOrMoreTimes();

        $this->finishBuffer($buf);
        $smtp->start();
        $smtp->send($message);
    }

    public function testMessageStateIsRestoredOnFailure()
    {
        $buf = $this->getBuffer();
        $smtp = $this->getTransport($buf);
        $message = $this->createMessage();

        $message->shouldReceive('getFrom')
                ->zeroOrMoreTimes()
                ->andReturn(['me@domain.com' => 'Me']);
        $message->shouldReceive('getTo')
                ->zeroOrMoreTimes()
                ->andReturn(['foo@bar' => null]);
        $message->shouldReceive('getBcc')
                ->zeroOrMoreTimes()
                ->andReturn([
                    'zip@button' => 'Zip Button',
                    'test@domain' => 'Test user',
                ]);
        $message->shouldReceive('setBcc')
                ->once()
                ->with([]);
        $message->shouldReceive('setBcc')
                ->once()
                ->with([
                    'zip@button' => 'Zip Button',
                    'test@domain' => 'Test user',
                ]);
        $buf->shouldReceive('write')
            ->once()
            ->with("MAIL FROM:<me@domain.com>\r\n")
            ->andReturn(1);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(1)
            ->andReturn("250 OK\r\n");
        $buf->shouldReceive('write')
            ->once()
            ->with("RCPT TO:<foo@bar>\r\n")
            ->andReturn(2);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(2)
            ->andReturn("250 OK\r\n");
        $buf->shouldReceive('write')
            ->once()
            ->with("DATA\r\n")
            ->andReturn(3);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(3)
            ->andReturn("451 No\r\n");

        $this->finishBuffer($buf);

        $smtp->start();
        try {
            $smtp->send($message);
            $this->fail('A bad response was given so exception is expected');
        } catch (Swift_TransportException $e) {
        }
    }

    public function testStopSendsQuitCommand()
    {
        /* -- RFC 2821, 4.1.1.10.

        This command specifies that the receiver MUST send an OK reply, and
        then close the transmission channel.

        The receiver MUST NOT intentionally close the transmission channel
        until it receives and replies to a QUIT command (even if there was an
        error).  The sender MUST NOT intentionally close the transmission
        channel until it sends a QUIT command and SHOULD wait until it
        receives the reply (even if there was an error response to a previous
        command).  If the connection is closed prematurely due to violations
        of the above or system or network failure, the server MUST cancel any
        pending transaction, but not undo any previously completed
        transaction, and generally MUST act as if the command or transaction
        in progress had received a temporary error (i.e., a 4yz response).

        The QUIT command may be issued at any time.

        Syntax:
            "QUIT" CRLF
        */

        $buf = $this->getBuffer();
        $smtp = $this->getTransport($buf);
        $message = $this->createMessage();
        $buf->shouldReceive('initialize')
            ->once();
        $buf->shouldReceive('write')
            ->once()
            ->with("QUIT\r\n")
            ->andReturn(1);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(1)
            ->andReturn("221 Bye\r\n");
        $buf->shouldReceive('terminate')
            ->once();

        $this->finishBuffer($buf);

        $this->assertFalse($smtp->isStarted());
        $smtp->start();
        $this->assertTrue($smtp->isStarted());
        $smtp->stop();
        $this->assertFalse($smtp->isStarted());
    }

    public function testBufferCanBeFetched()
    {
        $buf = $this->getBuffer();
        $smtp = $this->getTransport($buf);
        $ref = $smtp->getBuffer();
        $this->assertEquals($buf, $ref);
    }

    public function testBufferCanBeWrittenToUsingExecuteCommand()
    {
        $buf = $this->getBuffer();
        $smtp = $this->getTransport($buf);
        $message = $this->createMessage();
        $buf->shouldReceive('write')
            ->zeroOrMoreTimes()
            ->with("FOO\r\n")
            ->andReturn(1);
        $buf->shouldReceive('readLine')
            ->zeroOrMoreTimes()
            ->with(1)
            ->andReturn("250 OK\r\n");

        $res = $smtp->executeCommand("FOO\r\n");
        $this->assertEquals("250 OK\r\n", $res);
    }

    public function testResponseCodesAreValidated()
    {
        $buf = $this->getBuffer();
        $smtp = $this->getTransport($buf);
        $message = $this->createMessage();
        $buf->shouldReceive('write')
            ->zeroOrMoreTimes()
            ->with("FOO\r\n")
            ->andReturn(1);
        $buf->shouldReceive('readLine')
            ->zeroOrMoreTimes()
            ->with(1)
            ->andReturn("551 Not ok\r\n");

        try {
            $smtp->executeCommand("FOO\r\n", [250, 251]);
            $this->fail('A 250 or 251 response was needed but 551 was returned.');
        } catch (Swift_TransportException $e) {
        }
    }

    public function testFailedRecipientsCanBeCollectedByReference()
    {
        $buf = $this->getBuffer();
        $smtp = $this->getTransport($buf);
        $message = $this->createMessage();

        $message->shouldReceive('getFrom')
                ->zeroOrMoreTimes()
                ->andReturn(['me@domain.com' => 'Me']);
        $message->shouldReceive('getTo')
                ->zeroOrMoreTimes()
                ->andReturn(['foo@bar' => null]);
        $message->shouldReceive('getBcc')
                ->zeroOrMoreTimes()
                ->andReturn([
                    'zip@button' => 'Zip Button',
                    'test@domain' => 'Test user',
                ]);
        $message->shouldReceive('setBcc')
                ->atLeast()->once()
                ->with([]);
        $message->shouldReceive('setBcc')
                ->atLeast()->once()
                ->with([
                    'zip@button' => 'Zip Button',
                    'test@domain' => 'Test user',
                ]);

        $buf->shouldReceive('write')->once()->with("MAIL FROM:<me@domain.com>\r\n")->andReturn(1);
        $buf->shouldReceive('readLine')->once()->with(1)->andReturn("250 OK\r\n");
        $buf->shouldReceive('write')->once()->with("RCPT TO:<foo@bar>\r\n")->andReturn(2);
        $buf->shouldReceive('readLine')->once()->with(2)->andReturn("250 OK\r\n");
        $buf->shouldReceive('write')->once()->with("RCPT TO:<zip@button>\r\n")->andReturn(3);
        $buf->shouldReceive('readLine')->once()->with(3)->andReturn("500 Bad\r\n");
        $buf->shouldReceive('write')->once()->with("RCPT TO:<test@domain>\r\n")->andReturn(4);
        $buf->shouldReceive('readLine')->once()->with(4)->andReturn("500 Bad\r\n");

        $this->finishBuffer($buf);
        $smtp->start();
        $this->assertEquals(1, $smtp->send($message, $failures));
    }

    public function testSendingRegeneratesMessageId()
    {
        $buf = $this->getBuffer();
        $smtp = $this->getTransport($buf);
        $message = $this->createMessage();
        $message->shouldReceive('getFrom')
                ->zeroOrMoreTimes()
                ->andReturn(['me@domain.com' => 'Me']);
        $message->shouldReceive('getTo')
                ->zeroOrMoreTimes()
                ->andReturn(['foo@bar' => null]);
        $message->shouldReceive('generateId')
                ->once();

        $this->finishBuffer($buf);
        $smtp->start();
        $smtp->send($message);
    }

    public function testPing()
    {
        $buf = $this->getBuffer();
        $smtp = $this->getTransport($buf);

        $buf->shouldReceive('initialize')
            ->once();
        $buf->shouldReceive('readLine')
            ->once()
            ->with(0)
            ->andReturn("220 some.server.tld bleh\r\n");
        $buf->shouldReceive('write')
            ->once()
            ->with(Mockery::pattern('~^NOOP\r\n$~D'))
            ->andReturn(1);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(1)
            ->andReturn('250 OK'."\r\n");

        $this->finishBuffer($buf);
        $this->assertTrue($smtp->ping());
    }

    public function testPingOnDeadConnection()
    {
        $buf = $this->getBuffer();
        $smtp = $this->getTransport($buf);

        $buf->shouldReceive('initialize')
            ->once();
        $buf->shouldReceive('readLine')
            ->once()
            ->with(0)
            ->andReturn("220 some.server.tld bleh\r\n");
        $buf->shouldReceive('write')
            ->once()
            ->with(Mockery::pattern('~^NOOP\r\n$~D'))
            ->andThrow('Swift_TransportException');

        $this->finishBuffer($buf);
        $smtp->start();
        $this->assertTrue($smtp->isStarted());
        $this->assertFalse($smtp->ping());
        $this->assertFalse($smtp->isStarted());
    }

    public function testSetLocalDomain()
    {
        $buf = $this->getBuffer();
        $smtp = $this->getTransport($buf);

        $smtp->setLocalDomain('example.com');
        $this->assertEquals('example.com', $smtp->getLocalDomain());

        $smtp->setLocalDomain('192.168.0.1');
        $this->assertEquals('[192.168.0.1]', $smtp->getLocalDomain());

        $smtp->setLocalDomain('[192.168.0.1]');
        $this->assertEquals('[192.168.0.1]', $smtp->getLocalDomain());

        $smtp->setLocalDomain('fd00::');
        $this->assertEquals('[IPv6:fd00::]', $smtp->getLocalDomain());

        $smtp->setLocalDomain('[IPv6:fd00::]');
        $this->assertEquals('[IPv6:fd00::]', $smtp->getLocalDomain());
    }

    protected function getBuffer()
    {
        return $this->getMockery('Swift_Transport_IoBuffer')->shouldIgnoreMissing();
    }

    protected function createMessage()
    {
        return $this->getMockery('Swift_Mime_SimpleMessage')->shouldIgnoreMissing();
    }

    protected function finishBuffer($buf)
    {
        $buf->shouldReceive('readLine')
            ->zeroOrMoreTimes()
            ->with(0)
            ->andReturn('220 server.com foo'."\r\n");
        $buf->shouldReceive('write')
            ->zeroOrMoreTimes()
            ->with(Mockery::pattern('~^(EH|HE)LO .*?\r\n$~D'))
            ->andReturn($x = uniqid('', true));
        $buf->shouldReceive('readLine')
            ->zeroOrMoreTimes()
            ->with($x)
            ->andReturn('250 ServerName'."\r\n");
        $buf->shouldReceive('write')
            ->zeroOrMoreTimes()
            ->with(Mockery::pattern('~^MAIL FROM:<.*?>\r\n$~D'))
            ->andReturn($x = uniqid('', true));
        $buf->shouldReceive('readLine')
            ->zeroOrMoreTimes()
            ->with($x)
            ->andReturn("250 OK\r\n");
        $buf->shouldReceive('write')
            ->zeroOrMoreTimes()
            ->with(Mockery::pattern('~^RCPT TO:<.*?>\r\n$~D'))
            ->andReturn($x = uniqid('', true));
        $buf->shouldReceive('readLine')
            ->zeroOrMoreTimes()
            ->with($x)
            ->andReturn("250 OK\r\n");
        $buf->shouldReceive('write')
            ->zeroOrMoreTimes()
            ->with("DATA\r\n")
            ->andReturn($x = uniqid('', true));
        $buf->shouldReceive('readLine')
            ->zeroOrMoreTimes()
            ->with($x)
            ->andReturn("354 OK\r\n");
        $buf->shouldReceive('write')
            ->zeroOrMoreTimes()
            ->with("\r\n.\r\n")
            ->andReturn($x = uniqid('', true));
        $buf->shouldReceive('readLine')
            ->zeroOrMoreTimes()
            ->with($x)
            ->andReturn("250 OK\r\n");
        $buf->shouldReceive('write')
            ->zeroOrMoreTimes()
            ->with("RSET\r\n")
            ->andReturn($x = uniqid('', true));
        $buf->shouldReceive('readLine')
            ->zeroOrMoreTimes()
            ->with($x)
            ->andReturn("250 OK\r\n");

        $buf->shouldReceive('write')
            ->zeroOrMoreTimes()
            ->andReturn(false);
        $buf->shouldReceive('readLine')
            ->zeroOrMoreTimes()
            ->andReturn(false);
    }
}


================================================
FILE: tests/unit/Swift/Transport/Esmtp/Auth/CramMd5AuthenticatorTest.php
================================================
<?php

class Swift_Transport_Esmtp_Auth_CramMd5AuthenticatorTest extends \SwiftMailerTestCase
{
    private $agent;

    protected function setUp()
    {
        $this->agent = $this->getMockery('Swift_Transport_SmtpAgent')->shouldIgnoreMissing();
    }

    public function testKeywordIsCramMd5()
    {
        /* -- RFC 2195, 2.
        The authentication type associated with CRAM is "CRAM-MD5".
        */

        $cram = $this->getAuthenticator();
        $this->assertEquals('CRAM-MD5', $cram->getAuthKeyword());
    }

    public function testSuccessfulAuthentication()
    {
        $cram = $this->getAuthenticator();

        $this->agent->shouldReceive('executeCommand')
             ->once()
             ->with("AUTH CRAM-MD5\r\n", [334])
             ->andReturn('334 '.base64_encode('<foo@bar>')."\r\n");
        $this->agent->shouldReceive('executeCommand')
             ->once()
             ->with(\Mockery::any(), [235]);

        $this->assertTrue($cram->authenticate($this->agent, 'jack', 'pass'),
            '%s: The buffer accepted all commands authentication should succeed'
            );
    }

    public function testAuthenticationFailureSendRset()
    {
        $this->expectException(\Swift_TransportException::class);

        $cram = $this->getAuthenticator();

        $this->agent->shouldReceive('executeCommand')
             ->once()
             ->with("AUTH CRAM-MD5\r\n", [334])
             ->andReturn('334 '.base64_encode('<foo@bar>')."\r\n");
        $this->agent->shouldReceive('executeCommand')
             ->once()
             ->with(\Mockery::any(), [235])
             ->andThrow(new Swift_TransportException(''));
        $this->agent->shouldReceive('executeCommand')
             ->once()
             ->with("RSET\r\n", [250]);

        $cram->authenticate($this->agent, 'jack', 'pass');
    }

    private function getAuthenticator()
    {
        return new Swift_Transport_Esmtp_Auth_CramMd5Authenticator();
    }
}


================================================
FILE: tests/unit/Swift/Transport/Esmtp/Auth/LoginAuthenticatorTest.php
================================================
<?php

class Swift_Transport_Esmtp_Auth_LoginAuthenticatorTest extends \SwiftMailerTestCase
{
    private $agent;

    protected function setUp()
    {
        $this->agent = $this->getMockery('Swift_Transport_SmtpAgent')->shouldIgnoreMissing();
    }

    public function testKeywordIsLogin()
    {
        $login = $this->getAuthenticator();
        $this->assertEquals('LOGIN', $login->getAuthKeyword());
    }

    public function testSuccessfulAuthentication()
    {
        $login = $this->getAuthenticator();

        $this->agent->shouldReceive('executeCommand')
             ->once()
             ->with("AUTH LOGIN\r\n", [334]);
        $this->agent->shouldReceive('executeCommand')
             ->once()
             ->with(base64_encode('jack')."\r\n", [334]);
        $this->agent->shouldReceive('executeCommand')
             ->once()
             ->with(base64_encode('pass')."\r\n", [235]);

        $this->assertTrue($login->authenticate($this->agent, 'jack', 'pass'),
            '%s: The buffer accepted all commands authentication should succeed'
            );
    }

    public function testAuthenticationFailureSendRset()
    {
        $this->expectException(\Swift_TransportException::class);

        $login = $this->getAuthenticator();

        $this->agent->shouldReceive('executeCommand')
             ->once()
             ->with("AUTH LOGIN\r\n", [334]);
        $this->agent->shouldReceive('executeCommand')
             ->once()
             ->with(base64_encode('jack')."\r\n", [334]);
        $this->agent->shouldReceive('executeCommand')
             ->once()
             ->with(base64_encode('pass')."\r\n", [235])
             ->andThrow(new Swift_TransportException(''));
        $this->agent->shouldReceive('executeCommand')
             ->once()
             ->with("RSET\r\n", [250]);

        $login->authenticate($this->agent, 'jack', 'pass');
    }

    private function getAuthenticator()
    {
        return new Swift_Transport_Esmtp_Auth_LoginAuthenticator();
    }
}


================================================
FILE: tests/unit/Swift/Transport/Esmtp/Auth/NTLMAuthenticatorTest.php
================================================
<?php

class Swift_Transport_Esmtp_Auth_NTLMAuthenticatorTest extends \SwiftMailerTestCase
{
    private $message1 = '4e544c4d535350000100000007020000';
    private $message2 = '4e544c4d53535000020000000c000c003000000035828980514246973ea892c10000000000000000460046003c00000054004500530054004e00540002000c0054004500530054004e00540001000c004d0045004d0042004500520003001e006d0065006d006200650072002e0074006500730074002e0063006f006d0000000000';
    private $message3 = '4e544c4d5353500003000000180018006000000076007600780000000c000c0040000000080008004c0000000c000c0054000000000000009a0000000102000054004500530054004e00540074006500730074004d0045004d00420045005200bf2e015119f6bdb3f6fdb768aa12d478f5ce3d2401c8f6e9caa4da8f25d5e840974ed8976d3ada46010100000000000030fa7e3c677bc301f5ce3d2401c8f6e90000000002000c0054004500530054004e00540001000c004d0045004d0042004500520003001e006d0065006d006200650072002e0074006500730074002e0063006f006d000000000000000000';

    protected function setUp()
    {
        if (!\function_exists('openssl_encrypt') || !\function_exists('bcmul')) {
            $this->markTestSkipped('One of the required functions is not available.');
        }
    }

    public function testKeywordIsNtlm()
    {
        $login = $this->getAuthenticator();
        $this->assertEquals('NTLM', $login->getAuthKeyword());
    }

    public function testMessage1Generator()
    {
        $login = $this->getAuthenticator();
        $message1 = $this->invokePrivateMethod('createMessage1', $login);

        $this->assertEquals($this->message1, bin2hex($message1), '%s: We send the smallest ntlm message which should never fail.');
    }

    public function testLMv1Generator()
    {
        $password = 'test1234';
        $challenge = 'b019d38bad875c9d';
        $lmv1 = '1879f60127f8a877022132ec221bcbf3ca016a9f76095606';

        $login = $this->getAuthenticator();
        $lmv1Result = $this->invokePrivateMethod('createLMPassword', $login, [$password, hex2bin($challenge)]);

        $this->assertEquals($lmv1, bin2hex($lmv1Result), '%s: The keys should be the same cause we use the same values to generate them.');
    }

    public function testLMv2Generator()
    {
        $username = 'user';
        $password = 'SecREt01';
        $domain = 'DOMAIN';
        $challenge = '0123456789abcdef';
        $lmv2 = 'd6e6152ea25d03b7c6ba6629c2d6aaf0ffffff0011223344';

        $login = $this->getAuthenticator();
        $lmv2Result = $this->invokePrivateMethod('createLMv2Password', $login, [$password, $username, $domain, hex2bin($challenge), hex2bin('ffffff0011223344')]);

        $this->assertEquals($lmv2, bin2hex($lmv2Result), '%s: The keys should be the same cause we use the same values to generate them.');
    }

    public function testMessage3v1Generator()
    {
        $username = 'test';
        $domain = 'TESTNT';
        $workstation = 'MEMBER';
        $lmResponse = '1879f60127f8a877022132ec221bcbf3ca016a9f76095606';
        $ntlmResponse = 'e6285df3287c5d194f84df1a94817c7282d09754b6f9e02a';
        $message3T = '4e544c4d5353500003000000180018006000000018001800780000000c000c0040000000080008004c0000000c000c0054000000000000009a0000000102000054004500530054004e00540074006500730074004d0045004d004200450052001879f60127f8a877022132ec221bcbf3ca016a9f76095606e6285df3287c5d194f84df1a94817c7282d09754b6f9e02a';

        $login = $this->getAuthenticator();
        $message3 = $this->invokePrivateMethod('createMessage3', $login, [$domain, $username, $workstation, hex2bin($lmResponse), hex2bin($ntlmResponse)]);

        $this->assertEquals($message3T, bin2hex($message3), '%s: We send the same information as the example is created with so this should be the same');
    }

    public function testMessage3v2Generator()
    {
        $username = 'test';
        $domain = 'TESTNT';
        $workstation = 'MEMBER';
        $lmResponse = 'bf2e015119f6bdb3f6fdb768aa12d478f5ce3d2401c8f6e9';
        $ntlmResponse = 'caa4da8f25d5e840974ed8976d3ada46010100000000000030fa7e3c677bc301f5ce3d2401c8f6e90000000002000c0054004500530054004e00540001000c004d0045004d0042004500520003001e006d0065006d006200650072002e0074006500730074002e0063006f006d000000000000000000';

        $login = $this->getAuthenticator();
        $message3 = $this->invokePrivateMethod('createMessage3', $login, [$domain, $username, $workstation, hex2bin($lmResponse), hex2bin($ntlmResponse)]);

        $this->assertEquals($this->message3, bin2hex($message3), '%s: We send the same information as the example is created with so this should be the same');
    }

    public function testGetDomainAndUsername()
    {
        $username = "DOMAIN\user";

        $login = $this->getAuthenticator();
        list($domain, $user) = $this->invokePrivateMethod('getDomainAndUsername', $login, [$username]);

        $this->assertEquals('DOMAIN', $domain, '%s: the fetched domain did not match');
        $this->assertEquals('user', $user, '%s: the fetched user did not match');
    }

    public function testGetDomainAndUsernameWithExtension()
    {
        $username = "domain.com\user";

        $login = $this->getAuthenticator();
        list($domain, $user) = $this->invokePrivateMethod('getDomainAndUsername', $login, [$username]);

        $this->assertEquals('domain.com', $domain, '%s: the fetched domain did not match');
        $this->assertEquals('user', $user, '%s: the fetched user did not match');
    }

    public function testGetDomainAndUsernameWithAtSymbol()
    {
        $username = 'user@DOMAIN';

        $login = $this->getAuthenticator();
        list($domain, $user) = $this->invokePrivateMethod('getDomainAndUsername', $login, [$username]);

        $this->assertEquals('DOMAIN', $domain, '%s: the fetched domain did not match');
        $this->assertEquals('user', $user, '%s: the fetched user did not match');
    }

    public function testGetDomainAndUsernameWithAtSymbolAndExtension()
    {
        $username = 'user@domain.com';

        $login = $this->getAuthenticator();
        list($domain, $user) = $this->invokePrivateMethod('getDomainAndUsername', $login, [$username]);

        $this->assertEquals('domain.com', $domain, '%s: the fetched domain did not match');
        $this->assertEquals('user', $user, '%s: the fetched user did not match');
    }

    public function testGetDomainAndUsernameWithoutDomain()
    {
        $username = 'user';

        $login = $this->getAuthenticator();
        list($domain, $user) = $this->invokePrivateMethod('getDomainAndUsername', $login, [$username]);

        $this->assertEquals('', $domain, '%s: the fetched domain did not match');
        $this->assertEquals('user', $user, '%s: the fetched user did not match');
    }

    public function testSuccessfulAuthentication()
    {
        $domain = 'TESTNT';
        $username = 'test';
        $secret = 'test1234';

        $ntlm = $this->getAuthenticator();
        $agent = $this->getAgent();
        $agent->shouldReceive('executeCommand')
              ->once()
              ->with('AUTH NTLM '.base64_encode(
                        $this->invokePrivateMethod('createMessage1', $ntlm)
                    )."\r\n", [334])
              ->andReturn('334 '.base64_encode(hex2bin('4e544c4d53535000020000000c000c003000000035828980514246973ea892c10000000000000000460046003c00000054004500530054004e00540002000c0054004500530054004e00540001000c004d0045004d0042004500520003001e006d0065006d006200650072002e0074006500730074002e0063006f006d0000000000')));
        $agent->shouldReceive('executeCommand')
              ->once()
              ->with(base64_encode(
                        $this->invokePrivateMethod('createMessage3', $ntlm, [$domain, $username, hex2bin('4d0045004d00420045005200'), hex2bin('bf2e015119f6bdb3f6fdb768aa12d478f5ce3d2401c8f6e9'), hex2bin('caa4da8f25d5e840974ed8976d3ada46010100000000000030fa7e3c677bc301f5ce3d2401c8f6e90000000002000c0054004500530054004e00540001000c004d0045004d0042004500520003001e006d0065006d006200650072002e0074006500730074002e0063006f006d000000000000000000')]
                    ))."\r\n", [235]);

        $this->assertTrue($ntlm->authenticate($agent, $username.'@'.$domain, $secret, hex2bin('30fa7e3c677bc301'), hex2bin('f5ce3d2401c8f6e9')), '%s: The buffer accepted all commands authentication should succeed');
    }

    public function testAuthenticationFailureSendRset()
    {
        $this->expectException(\Swift_TransportException::class);

        $domain = 'TESTNT';
        $username = 'test';
        $secret = 'test1234';

        $ntlm = $this->getAuthenticator();
        $agent = $this->getAgent();
        $agent->shouldReceive('executeCommand')
              ->once()
              ->with('AUTH NTLM '.base64_encode(
                        $this->invokePrivateMethod('createMessage1', $ntlm)
                    )."\r\n", [334])
              ->andThrow(new Swift_TransportException(''));
        $agent->shouldReceive('executeCommand')
              ->once()
              ->with("RSET\r\n", [250]);

        $ntlm->authenticate($agent, $username.'@'.$domain, $secret, hex2bin('30fa7e3c677bc301'), hex2bin('f5ce3d2401c8f6e9'));
    }

    private function getAuthenticator()
    {
        return new Swift_Transport_Esmtp_Auth_NTLMAuthenticator();
    }

    private function getAgent()
    {
        return $this->getMockery('Swift_Transport_SmtpAgent')->shouldIgnoreMissing();
    }

    private function invokePrivateMethod($method, $instance, array $args = [])
    {
        $methodC = new ReflectionMethod($instance, trim($method));
        $methodC->setAccessible(true);

        return $methodC->invokeArgs($instance, $args);
    }
}


================================================
FILE: tests/unit/Swift/Transport/Esmtp/Auth/PlainAuthenticatorTest.php
================================================
<?php

class Swift_Transport_Esmtp_Auth_PlainAuthenticatorTest extends \SwiftMailerTestCase
{
    private $agent;

    protected function setUp()
    {
        $this->agent = $this->getMockery('Swift_Transport_SmtpAgent')->shouldIgnoreMissing();
    }

    public function testKeywordIsPlain()
    {
        /* -- RFC 4616, 1.
        The name associated with this mechanism is "PLAIN".
        */

        $login = $this->getAuthenticator();
        $this->assertEquals('PLAIN', $login->getAuthKeyword());
    }

    public function testSuccessfulAuthentication()
    {
        /* -- RFC 4616, 2.
        The client presents the authorization identity (identity to act as),
        followed by a NUL (U+0000) character, followed by the authentication
        identity (identity whose password will be used), followed by a NUL
        (U+0000) character, followed by the clear-text password.
        */

        $plain = $this->getAuthenticator();

        $this->agent->shouldReceive('executeCommand')
             ->once()
             ->with('AUTH PLAIN '.base64_encode(
                        'jack'.\chr(0).'jack'.\chr(0).'pass'
                    )."\r\n", [235]);

        $this->assertTrue($plain->authenticate($this->agent, 'jack', 'pass'),
            '%s: The buffer accepted all commands authentication should succeed'
            );
    }

    public function testAuthenticationFailureSendRset()
    {
        $this->expectException(\Swift_TransportException::class);

        $plain = $this->getAuthenticator();

        $this->agent->shouldReceive('executeCommand')
             ->once()
             ->with('AUTH PLAIN '.base64_encode(
                        'jack'.\chr(0).'jack'.\chr(0).'pass'
                    )."\r\n", [235])
             ->andThrow(new Swift_TransportException(''));
        $this->agent->shouldReceive('executeCommand')
             ->once()
             ->with("RSET\r\n", [250]);

        $plain->authenticate($this->agent, 'jack', 'pass');
    }

    private function getAuthenticator()
    {
        return new Swift_Transport_Esmtp_Auth_PlainAuthenticator();
    }
}


================================================
FILE: tests/unit/Swift/Transport/Esmtp/AuthHandlerTest.php
================================================
<?php

class Swift_Transport_Esmtp_AuthHandlerTest extends \SwiftMailerTestCase
{
    private $agent;

    protected function setUp()
    {
        $this->agent = $this->getMockery('Swift_Transport_SmtpAgent')->shouldIgnoreMissing();
    }

    public function testKeywordIsAuth()
    {
        $auth = $this->createHandler([]);
        $this->assertEquals('AUTH', $auth->getHandledKeyword());
    }

    public function testUsernameCanBeSetAndFetched()
    {
        $auth = $this->createHandler([]);
        $auth->setUsername('jack');
        $this->assertEquals('jack', $auth->getUsername());
    }

    public function testPasswordCanBeSetAndFetched()
    {
        $auth = $this->createHandler([]);
        $auth->setPassword('pass');
        $this->assertEquals('pass', $auth->getPassword());
    }

    public function testAuthModeCanBeSetAndFetched()
    {
        $auth = $this->createHandler([]);
        $auth->setAuthMode('PLAIN');
        $this->assertEquals('PLAIN', $auth->getAuthMode());
    }

    public function testMixinMethods()
    {
        $auth = $this->createHandler([]);
        $mixins = $auth->exposeMixinMethods();
        $this->assertTrue(\in_array('getUsername', $mixins),
            '%s: getUsername() should be accessible via mixin'
            );
        $this->assertTrue(\in_array('setUsername', $mixins),
            '%s: setUsername() should be accessible via mixin'
            );
        $this->assertTrue(\in_array('getPassword', $mixins),
            '%s: getPassword() should be accessible via mixin'
            );
        $this->assertTrue(\in_array('setPassword', $mixins),
            '%s: setPassword() should be accessible via mixin'
            );
        $this->assertTrue(\in_array('setAuthMode', $mixins),
            '%s: setAuthMode() should be accessible via mixin'
            );
        $this->assertTrue(\in_array('getAuthMode', $mixins),
            '%s: getAuthMode() should be accessible via mixin'
            );
    }

    public function testAuthenticatorsAreCalledAccordingToParamsAfterEhlo()
    {
        $a1 = $this->createMockAuthenticator('PLAIN');
        $a2 = $this->createMockAuthenticator('LOGIN');

        $a1->shouldReceive('authenticate')
           ->never()
           ->with($this->agent, 'jack', 'pass');
        $a2->shouldReceive('authenticate')
           ->once()
           ->with($this->agent, 'jack', 'pass')
           ->andReturn(true);

        $auth = $this->createHandler([$a1, $a2]);
        $auth->setUsername('jack');
        $auth->setPassword('pass');

        $auth->setKeywordParams(['CRAM-MD5', 'LOGIN']);
        $auth->afterEhlo($this->agent);
    }

    public function testAuthenticatorsAreNotUsedIfNoUsernameSet()
    {
        $a1 = $this->createMockAuthenticator('PLAIN');
        $a2 = $this->createMockAuthenticator('LOGIN');

        $a1->shouldReceive('authenticate')
           ->never()
           ->with($this->agent, 'jack', 'pass');
        $a2->shouldReceive('authenticate')
           ->never()
           ->with($this->agent, 'jack', 'pass')
           ->andReturn(true);

        $auth = $this->createHandler([$a1, $a2]);

        $auth->setKeywordParams(['CRAM-MD5', 'LOGIN']);
        $auth->afterEhlo($this->agent);
    }

    public function testSeveralAuthenticatorsAreTriedIfNeeded()
    {
        $a1 = $this->createMockAuthenticator('PLAIN');
        $a2 = $this->createMockAuthenticator('LOGIN');

        $a1->shouldReceive('authenticate')
           ->once()
           ->with($this->agent, 'jack', 'pass')
           ->andReturn(false);
        $a2->shouldReceive('authenticate')
           ->once()
           ->with($this->agent, 'jack', 'pass')
           ->andReturn(true);

        $auth = $this->createHandler([$a1, $a2]);
        $auth->setUsername('jack');
        $auth->setPassword('pass');

        $auth->setKeywordParams(['PLAIN', 'LOGIN']);
        $auth->afterEhlo($this->agent);
    }

    public function testFirstAuthenticatorToPassBreaksChain()
    {
        $a1 = $this->createMockAuthenticator('PLAIN');
        $a2 = $this->createMockAuthenticator('LOGIN');
        $a3 = $this->createMockAuthenticator('CRAM-MD5');

        $a1->shouldReceive('authenticate')
           ->once()
           ->with($this->agent, 'jack', 'pass')
           ->andReturn(false);
        $a2->shouldReceive('authenticate')
           ->once()
           ->with($this->agent, 'jack', 'pass')
           ->andReturn(true);
        $a3->shouldReceive('authenticate')
           ->never()
           ->with($this->agent, 'jack', 'pass');

        $auth = $this->createHandler([$a1, $a2]);
        $auth->setUsername('jack');
        $auth->setPassword('pass');

        $auth->setKeywordParams(['PLAIN', 'LOGIN', 'CRAM-MD5']);
        $auth->afterEhlo($this->agent);
    }

    private function createHandler($authenticators)
    {
        return new Swift_Transport_Esmtp_AuthHandler($authenticators);
    }

    private function createMockAuthenticator($type)
    {
        $authenticator = $this->getMockery('Swift_Transport_Esmtp_Authenticator')->shouldIgnoreMissing();
        $authenticator->shouldReceive('getAuthKeyword')
                      ->zeroOrMoreTimes()
                      ->andReturn($type);

        return $authenticator;
    }
}


================================================
FILE: tests/unit/Swift/Transport/EsmtpTransport/ExtensionSupportTest.php
================================================
<?php

require_once \dirname(__DIR__).'/EsmtpTransportTest.php';

interface Swift_Transport_EsmtpHandlerMixin extends Swift_Transport_EsmtpHandler
{
    public function setUsername($user);

    public function setPassword($pass);
}

class Swift_Transport_EsmtpTransport_ExtensionSupportTest extends Swift_Transport_EsmtpTransportTest
{
    public function testExtensionHandlersAreSortedAsNeeded()
    {
        $buf = $this->getBuffer();
        $smtp = $this->getTransport($buf);
        $ext1 = $this->getMockery('Swift_Transport_EsmtpHandler')->shouldIgnoreMissing();
        $ext2 = $this->getMockery('Swift_Transport_EsmtpHandler')->shouldIgnoreMissing();

        $ext1->shouldReceive('getHandledKeyword')
             ->zeroOrMoreTimes()
             ->andReturn('AUTH');
        $ext1->shouldReceive('getPriorityOver')
             ->zeroOrMoreTimes()
             ->with('STARTTLS')
             ->andReturn(1);
        $ext2->shouldReceive('getHandledKeyword')
             ->zeroOrMoreTimes()
             ->andReturn('STARTTLS');
        $ext2->shouldReceive('getPriorityOver')
             ->zeroOrMoreTimes()
             ->with('AUTH')
             ->andReturn(-1);
        $this->finishBuffer($buf);

        $smtp->setExtensionHandlers([$ext1, $ext2]);
        $this->assertEquals([$ext2, $ext1], $smtp->getExtensionHandlers());
    }

    public function testHandlersAreNotifiedOfParams()
    {
        $buf = $this->getBuffer();
        $smtp = $this->getTransport($buf);
        $ext1 = $this->getMockery('Swift_Transport_EsmtpHandler')->shouldIgnoreMissing();
        $ext2 = $this->getMockery('Swift_Transport_EsmtpHandler')->shouldIgnoreMissing();

        $buf->shouldReceive('readLine')
            ->once()
            ->with(0)
            ->andReturn("220 server.com foo\r\n");
        $buf->shouldReceive('write')
            ->once()
            ->with(Mockery::pattern('~^EHLO .*?\r\n$~D'))
            ->andReturn(1);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(1)
            ->andReturn("250-ServerName.tld\r\n");
        $buf->shouldReceive('readLine')
            ->once()
            ->with(1)
            ->andReturn("250-AUTH PLAIN LOGIN\r\n");
        $buf->shouldReceive('readLine')
            ->once()
            ->with(1)
            ->andReturn("250 SIZE=123456\r\n");

        $ext1->shouldReceive('getHandledKeyword')
             ->zeroOrMoreTimes()
             ->andReturn('AUTH');
        $ext1->shouldReceive('setKeywordParams')
             ->once()
             ->with(['PLAIN', 'LOGIN']);
        $ext2->shouldReceive('getHandledKeyword')
             ->zeroOrMoreTimes()
             ->andReturn('SIZE');
        $ext2->shouldReceive('setKeywordParams')
             ->zeroOrMoreTimes()
             ->with(['123456']);
        $this->finishBuffer($buf);

        $smtp->setExtensionHandlers([$ext1, $ext2]);
        $smtp->start();
    }

    public function testSupportedExtensionHandlersAreRunAfterEhlo()
    {
        $buf = $this->getBuffer();
        $smtp = $this->getTransport($buf);
        $ext1 = $this->getMockery('Swift_Transport_EsmtpHandler')->shouldIgnoreMissing();
        $ext2 = $this->getMockery('Swift_Transport_EsmtpHandler')->shouldIgnoreMissing();
        $ext3 = $this->getMockery('Swift_Transport_EsmtpHandler')->shouldIgnoreMissing();

        $buf->shouldReceive('readLine')
            ->once()
            ->with(0)
            ->andReturn("220 server.com foo\r\n");
        $buf->shouldReceive('write')
            ->once()
            ->with(Mockery::pattern('~^EHLO .*?\r\n$~D'))
            ->andReturn(1);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(1)
            ->andReturn("250-ServerName.tld\r\n");
        $buf->shouldReceive('readLine')
            ->once()
            ->with(1)
            ->andReturn("250-AUTH PLAIN LOGIN\r\n");
        $buf->shouldReceive('readLine')
            ->once()
            ->with(1)
            ->andReturn("250 SIZE=123456\r\n");

        $ext1->shouldReceive('getHandledKeyword')
             ->zeroOrMoreTimes()
             ->andReturn('AUTH');
        $ext1->shouldReceive('afterEhlo')
             ->once()
             ->with($smtp);
        $ext2->shouldReceive('getHandledKeyword')
             ->zeroOrMoreTimes()
             ->andReturn('SIZE');
        $ext2->shouldReceive('afterEhlo')
             ->zeroOrMoreTimes()
             ->with($smtp);
        $ext3->shouldReceive('getHandledKeyword')
             ->zeroOrMoreTimes()
             ->andReturn('STARTTLS');
        $ext3->shouldReceive('afterEhlo')
             ->never()
             ->with($smtp);
        $this->finishBuffer($buf);

        $smtp->setExtensionHandlers([$ext1, $ext2, $ext3]);
        $smtp->start();
    }

    public function testExtensionsCanModifyMailFromParams()
    {
        $buf = $this->getBuffer();
        $dispatcher = $this->createEventDispatcher();
        $smtp = new Swift_Transport_EsmtpTransport($buf, [], $dispatcher, 'example.org');
        $ext1 = $this->getMockery('Swift_Transport_EsmtpHandler')->shouldIgnoreMissing();
        $ext2 = $this->getMockery('Swift_Transport_EsmtpHandler')->shouldIgnoreMissing();
        $ext3 = $this->getMockery('Swift_Transport_EsmtpHandler')->shouldIgnoreMissing();
        $message = $this->createMessage();

        $message->shouldReceive('getFrom')
                ->zeroOrMoreTimes()
                ->andReturn(['me@domain' => 'Me']);
        $message->shouldReceive('getTo')
                ->zeroOrMoreTimes()
                ->andReturn(['foo@bar' => null]);

        $buf->shouldReceive('readLine')
            ->once()
            ->with(0)
            ->andReturn("220 server.com foo\r\n");
        $buf->shouldReceive('write')
            ->once()
            ->with(Mockery::pattern('~^EHLO .*?\r\n$~D'))
            ->andReturn(1);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(1)
            ->andReturn("250-ServerName.tld\r\n");
        $buf->shouldReceive('readLine')
            ->once()
            ->with(1)
            ->andReturn("250-AUTH PLAIN LOGIN\r\n");
        $buf->shouldReceive('readLine')
            ->once()
            ->with(1)
            ->andReturn("250 SIZE=123456\r\n");
        $buf->shouldReceive('write')
            ->once()
            ->with("MAIL FROM:<me@domain> FOO ZIP\r\n")
            ->andReturn(2);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(2)
            ->andReturn("250 OK\r\n");
        $buf->shouldReceive('write')
            ->once()
            ->with("RCPT TO:<foo@bar>\r\n")
            ->andReturn(3);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(3)
            ->andReturn("250 OK\r\n");
        $this->finishBuffer($buf);

        $ext1->shouldReceive('getHandledKeyword')
             ->zeroOrMoreTimes()
             ->andReturn('AUTH');
        $ext1->shouldReceive('getMailParams')
             ->once()
             ->andReturn('FOO');
        $ext1->shouldReceive('getPriorityOver')
             ->zeroOrMoreTimes()
             ->with('STARTTLS')
             ->andReturn(1);
        $ext1->shouldReceive('getPriorityOver')
             ->zeroOrMoreTimes()
             ->with('SIZE')
             ->andReturn(-1);
        $ext2->shouldReceive('getHandledKeyword')
             ->zeroOrMoreTimes()
             ->andReturn('SIZE');
        $ext2->shouldReceive('getMailParams')
             ->once()
             ->andReturn('ZIP');
        $ext2->shouldReceive('getPriorityOver')
             ->zeroOrMoreTimes()
             ->with('AUTH')
             ->andReturn(1);
        $ext2->shouldReceive('getPriorityOver')
             ->zeroOrMoreTimes()
             ->with('STARTTLS')
             ->andReturn(1);
        $ext3->shouldReceive('getHandledKeyword')
             ->zeroOrMoreTimes()
             ->andReturn('STARTTLS');
        $ext3->shouldReceive('getMailParams')
             ->never();
        $ext3->shouldReceive('getPriorityOver')
             ->zeroOrMoreTimes()
             ->with('AUTH')
             ->andReturn(-1);
        $ext3->shouldReceive('getPriorityOver')
             ->zeroOrMoreTimes()
             ->with('SIZE')
             ->andReturn(-1);

        $smtp->setExtensionHandlers([$ext1, $ext2, $ext3]);
        $smtp->start();
        $smtp->send($message);
    }

    public function testExtensionsCanModifyRcptParams()
    {
        $buf = $this->getBuffer();
        $dispatcher = $this->createEventDispatcher();
        $smtp = new Swift_Transport_EsmtpTransport($buf, [], $dispatcher, 'example.org');
        $ext1 = $this->getMockery('Swift_Transport_EsmtpHandler')->shouldIgnoreMissing();
        $ext2 = $this->getMockery('Swift_Transport_EsmtpHandler')->shouldIgnoreMissing();
        $ext3 = $this->getMockery('Swift_Transport_EsmtpHandler')->shouldIgnoreMissing();
        $message = $this->createMessage();

        $message->shouldReceive('getFrom')
                ->zeroOrMoreTimes()
                ->andReturn(['me@domain' => 'Me']);
        $message->shouldReceive('getTo')
                ->zeroOrMoreTimes()
                ->andReturn(['foo@bar' => null]);

        $buf->shouldReceive('readLine')
            ->once()
            ->with(0)
            ->andReturn("220 server.com foo\r\n");
        $buf->shouldReceive('write')
            ->once()
            ->with(Mockery::pattern('~^EHLO .+?\r\n$~D'))
            ->andReturn(1);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(1)
            ->andReturn("250-ServerName.tld\r\n");
        $buf->shouldReceive('readLine')
            ->once()
            ->with(1)
            ->andReturn("250-AUTH PLAIN LOGIN\r\n");
        $buf->shouldReceive('readLine')
            ->once()
            ->with(1)
            ->andReturn("250 SIZE=123456\r\n");
        $buf->shouldReceive('write')
            ->once()
            ->with("MAIL FROM:<me@domain>\r\n")
            ->andReturn(2);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(2)
            ->andReturn("250 OK\r\n");
        $buf->shouldReceive('write')
            ->once()
            ->with("RCPT TO:<foo@bar> FOO ZIP\r\n")
            ->andReturn(3);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(3)
            ->andReturn("250 OK\r\n");
        $this->finishBuffer($buf);

        $ext1->shouldReceive('getHandledKeyword')
             ->zeroOrMoreTimes()
             ->andReturn('AUTH');
        $ext1->shouldReceive('getRcptParams')
             ->once()
             ->andReturn('FOO');
        $ext1->shouldReceive('getPriorityOver')
             ->zeroOrMoreTimes()
             ->with('STARTTLS')
             ->andReturn(1);
        $ext1->shouldReceive('getPriorityOver')
             ->zeroOrMoreTimes()
             ->with('SIZE')
             ->andReturn(-1);
        $ext2->shouldReceive('getHandledKeyword')
             ->zeroOrMoreTimes()
             ->andReturn('SIZE');
        $ext2->shouldReceive('getRcptParams')
             ->once()
             ->andReturn('ZIP');
        $ext2->shouldReceive('getPriorityOver')
             ->zeroOrMoreTimes()
             ->with('STARTTLS')
             ->andReturn(1);
        $ext2->shouldReceive('getPriorityOver')
             ->zeroOrMoreTimes()
             ->with('AUTH')
             ->andReturn(1);
        $ext3->shouldReceive('getHandledKeyword')
             ->zeroOrMoreTimes()
             ->andReturn('STARTTLS');
        $ext3->shouldReceive('getRcptParams')
             ->never();
        $ext3->shouldReceive('getPriorityOver')
             ->zeroOrMoreTimes()
             ->with('AUTH')
             ->andReturn(-1);
        $ext3->shouldReceive('getPriorityOver')
             ->zeroOrMoreTimes()
             ->with('SIZE')
             ->andReturn(-1);

        $smtp->setExtensionHandlers([$ext1, $ext2, $ext3]);
        $smtp->start();
        $smtp->send($message);
    }

    public function testExtensionsAreNotifiedOnCommand()
    {
        $buf = $this->getBuffer();
        $smtp = $this->getTransport($buf);
        $ext1 = $this->getMockery('Swift_Transport_EsmtpHandler')->shouldIgnoreMissing();
        $ext2 = $this->getMockery('Swift_Transport_EsmtpHandler')->shouldIgnoreMissing();
        $ext3 = $this->getMockery('Swift_Transport_EsmtpHandler')->shouldIgnoreMissing();

        $buf->shouldReceive('readLine')
            ->once()
            ->with(0)
            ->andReturn("220 server.com foo\r\n");
        $buf->shouldReceive('write')
            ->once()
            ->with(Mockery::pattern('~^EHLO .+?\r\n$~D'))
            ->andReturn(1);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(1)
            ->andReturn("250-ServerName.tld\r\n");
        $buf->shouldReceive('readLine')
            ->once()
            ->with(1)
            ->andReturn("250-AUTH PLAIN LOGIN\r\n");
        $buf->shouldReceive('readLine')
            ->once()
            ->with(1)
            ->andReturn("250 SIZE=123456\r\n");
        $buf->shouldReceive('write')
            ->once()
            ->with("FOO\r\n")
            ->andReturn(2);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(2)
            ->andReturn("250 Cool\r\n");
        $this->finishBuffer($buf);

        $ext1->shouldReceive('getHandledKeyword')
             ->zeroOrMoreTimes()
             ->andReturn('AUTH');
        $ext1->shouldReceive('onCommand')
             ->once()
             ->with($smtp, "FOO\r\n", [250, 251], \Mockery::any(), \Mockery::any());
        $ext2->shouldReceive('getHandledKeyword')
             ->zeroOrMoreTimes()
             ->andReturn('SIZE');
        $ext2->shouldReceive('onCommand')
             ->once()
             ->with($smtp, "FOO\r\n", [250, 251], \Mockery::any(), \Mockery::any());
        $ext3->shouldReceive('getHandledKeyword')
             ->zeroOrMoreTimes()
             ->andReturn('STARTTLS');
        $ext3->shouldReceive('onCommand')
             ->never()
             ->with(\Mockery::any(), \Mockery::any(), \Mockery::any(), \Mockery::any(), \Mockery::any());

        $smtp->setExtensionHandlers([$ext1, $ext2, $ext3]);
        $smtp->start();
        $smtp->executeCommand("FOO\r\n", [250, 251]);
    }

    public function testChainOfCommandAlgorithmWhenNotifyingExtensions()
    {
        $buf = $this->getBuffer();
        $smtp = $this->getTransport($buf);
        $ext1 = $this->getMockery('Swift_Transport_EsmtpHandler')->shouldIgnoreMissing();
        $ext2 = $this->getMockery('Swift_Transport_EsmtpHandler')->shouldIgnoreMissing();
        $ext3 = $this->getMockery('Swift_Transport_EsmtpHandler')->shouldIgnoreMissing();

        $buf->shouldReceive('readLine')
            ->once()
            ->with(0)
            ->andReturn("220 server.com foo\r\n");
        $buf->shouldReceive('write')
            ->once()
            ->with(Mockery::pattern('~^EHLO .+?\r\n$~D'))
            ->andReturn(1);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(1)
            ->andReturn("250-ServerName.tld\r\n");
        $buf->shouldReceive('readLine')
            ->once()
            ->with(1)
            ->andReturn("250-AUTH PLAIN LOGIN\r\n");
        $buf->shouldReceive('readLine')
            ->once()
            ->with(1)
            ->andReturn("250 SIZE=123456\r\n");
        $buf->shouldReceive('write')
            ->never()
            ->with("FOO\r\n");
        $this->finishBuffer($buf);

        $ext1->shouldReceive('getHandledKeyword')
             ->zeroOrMoreTimes()
             ->andReturn('AUTH');
        $ext1->shouldReceive('onCommand')
             ->once()
             ->with($smtp, "FOO\r\n", [250, 251], \Mockery::any(), \Mockery::any())
             ->andReturnUsing(function ($a, $b, $c, $d, &$e) {
                 $e = true;

                 return '250 ok';
             });
        $ext2->shouldReceive('getHandledKeyword')
             ->zeroOrMoreTimes()
             ->andReturn('SIZE');
        $ext2->shouldReceive('onCommand')
             ->never()
             ->with(\Mockery::any(), \Mockery::any(), \Mockery::any(), \Mockery::any());

        $ext3->shouldReceive('getHandledKeyword')
             ->zeroOrMoreTimes()
             ->andReturn('STARTTLS');
        $ext3->shouldReceive('onCommand')
             ->never()
             ->with(\Mockery::any(), \Mockery::any(), \Mockery::any(), \Mockery::any());

        $smtp->setExtensionHandlers([$ext1, $ext2, $ext3]);
        $smtp->start();
        $smtp->executeCommand("FOO\r\n", [250, 251]);
    }

    public function testExtensionsCanExposeMixinMethods()
    {
        $buf = $this->getBuffer();
        $smtp = $this->getTransport($buf);
        $ext1 = $this->getMockery('Swift_Transport_EsmtpHandlerMixin')->shouldIgnoreMissing();
        $ext2 = $this->getMockery('Swift_Transport_EsmtpHandler')->shouldIgnoreMissing();

        $ext1->shouldReceive('getHandledKeyword')
             ->zeroOrMoreTimes()
             ->andReturn('AUTH');
        $ext1->shouldReceive('exposeMixinMethods')
             ->zeroOrMoreTimes()
             ->andReturn(['setUsername', 'setPassword']);
        $ext1->shouldReceive('setUsername')
             ->once()
             ->with('mick');
        $ext1->shouldReceive('setPassword')
             ->once()
             ->with('pass');
        $ext2->shouldReceive('getHandledKeyword')
             ->zeroOrMoreTimes()
             ->andReturn('STARTTLS');
        $this->finishBuffer($buf);

        $smtp->setExtensionHandlers([$ext1, $ext2]);
        $smtp->setUsername('mick');
        $smtp->setPassword('pass');
    }

    public function testMixinMethodsBeginningWithSetAndNullReturnAreFluid()
    {
        $buf = $this->getBuffer();
        $smtp = $this->getTransport($buf);
        $ext1 = $this->getMockery('Swift_Transport_EsmtpHandlerMixin')->shouldIgnoreMissing();
        $ext2 = $this->getMockery('Swift_Transport_EsmtpHandler')->shouldIgnoreMissing();

        $ext1->shouldReceive('getHandledKeyword')
             ->zeroOrMoreTimes()
             ->andReturn('AUTH');
        $ext1->shouldReceive('exposeMixinMethods')
             ->zeroOrMoreTimes()
             ->andReturn(['setUsername', 'setPassword']);
        $ext1->shouldReceive('setUsername')
             ->once()
             ->with('mick')
             ->andReturn(null);
        $ext1->shouldReceive('setPassword')
             ->once()
             ->with('pass')
             ->andReturn(null);
        $ext2->shouldReceive('getHandledKeyword')
             ->zeroOrMoreTimes()
             ->andReturn('STARTTLS');
        $this->finishBuffer($buf);

        $smtp->setExtensionHandlers([$ext1, $ext2]);
        $ret = $smtp->setUsername('mick');
        $this->assertEquals($smtp, $ret);
        $ret = $smtp->setPassword('pass');
        $this->assertEquals($smtp, $ret);
    }

    public function testMixinSetterWhichReturnValuesAreNotFluid()
    {
        $buf = $this->getBuffer();
        $smtp = $this->getTransport($buf);
        $ext1 = $this->getMockery('Swift_Transport_EsmtpHandlerMixin')->shouldIgnoreMissing();
        $ext2 = $this->getMockery('Swift_Transport_EsmtpHandler')->shouldIgnoreMissing();

        $ext1->shouldReceive('getHandledKeyword')
             ->zeroOrMoreTimes()
             ->andReturn('AUTH');
        $ext1->shouldReceive('exposeMixinMethods')
             ->zeroOrMoreTimes()
             ->andReturn(['setUsername', 'setPassword']);
        $ext1->shouldReceive('setUsername')
             ->once()
             ->with('mick')
             ->andReturn('x');
        $ext1->shouldReceive('setPassword')
             ->once()
             ->with('pass')
             ->andReturn('x');
        $ext2->shouldReceive('getHandledKeyword')
             ->zeroOrMoreTimes()
             ->andReturn('STARTTLS');
        $this->finishBuffer($buf);

        $smtp->setExtensionHandlers([$ext1, $ext2]);
        $this->assertEquals('x', $smtp->setUsername('mick'));
        $this->assertEquals('x', $smtp->setPassword('pass'));
    }
}


================================================
FILE: tests/unit/Swift/Transport/EsmtpTransportTest.php
================================================
<?php

class Swift_Transport_EsmtpTransportTest extends Swift_Transport_AbstractSmtpEventSupportTest
{
    protected function getTransport($buf, $dispatcher = null, $addressEncoder = null)
    {
        $dispatcher = $dispatcher ?? $this->createEventDispatcher();
        $addressEncoder = $addressEncoder ?? new Swift_AddressEncoder_IdnAddressEncoder();

        return new Swift_Transport_EsmtpTransport($buf, [], $dispatcher, 'example.org', $addressEncoder);
    }

    public function testHostCanBeSetAndFetched()
    {
        $buf = $this->getBuffer();
        $smtp = $this->getTransport($buf);
        $smtp->setHost('foo');
        $this->assertEquals('foo', $smtp->getHost(), '%s: Host should be returned');
    }

    public function testPortCanBeSetAndFetched()
    {
        $buf = $this->getBuffer();
        $smtp = $this->getTransport($buf);
        $smtp->setPort(25);
        $this->assertEquals(25, $smtp->getPort(), '%s: Port should be returned');
    }

    public function testTimeoutCanBeSetAndFetched()
    {
        $buf = $this->getBuffer();
        $buf->shouldReceive('setParam')
            ->once()
            ->with('timeout', 10);

        $smtp = $this->getTransport($buf);
        $smtp->setTimeout(10);
        $this->assertEquals(10, $smtp->getTimeout(), '%s: Timeout should be returned');
    }

    public function testEncryptionCanBeSetAndFetched()
    {
        $buf = $this->getBuffer();
        $smtp = $this->getTransport($buf);
        $smtp->setEncryption('tls');
        $this->assertEquals('tls', $smtp->getEncryption(), '%s: Crypto should be returned');
    }

    public function testStartSendsHeloToInitiate()
    {
        // previous loop would fail if there is an issue
        $this->addToAssertionCount(1);
    }

    public function testStartSendsEhloToInitiate()
    {
        /* -- RFC 2821, 3.2.

            3.2 Client Initiation

         Once the server has sent the welcoming message and the client has
         received it, the client normally sends the EHLO command to the
         server, indicating the client's identity.  In addition to opening the
         session, use of EHLO indicates that the client is able to process
         service extensions and requests that the server provide a list of the
         extensions it supports.  Older SMTP systems which are unable to
         support service extensions and contemporary clients which do not
         require service extensions in the mail session being initiated, MAY
         use HELO instead of EHLO.  Servers MUST NOT return the extended
         EHLO-style response to a HELO command.  For a particular connection
         attempt, if the server returns a "command not recognized" response to
         EHLO, the client SHOULD be able to fall back and send HELO.

         In the EHLO command the host sending the command identifies itself;
         the command may be interpreted as saying "Hello, I am <domain>" (and,
         in the case of EHLO, "and I support service extension requests").

       -- RFC 2281, 4.1.1.1.

       ehlo            = "EHLO" SP Domain CRLF
       helo            = "HELO" SP Domain CRLF

       -- RFC 2821, 4.3.2.

       EHLO or HELO
           S: 250
           E: 504, 550

     */

        $buf = $this->getBuffer();
        $smtp = $this->getTransport($buf);

        $buf->shouldReceive('initialize')
            ->once();
        $buf->shouldReceive('readLine')
            ->once()
            ->with(0)
            ->andReturn("220 some.server.tld bleh\r\n");
        $buf->shouldReceive('write')
            ->once()
            ->with(Mockery::pattern('~^EHLO .+?\r\n$~D'))
            ->andReturn(1);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(1)
            ->andReturn('250 ServerName'."\r\n");

        $this->finishBuffer($buf);
        try {
            $smtp->start();
        } catch (Exception $e) {
            $this->fail('Starting Esmtp should send EHLO and accept 250 response: '.$e->getMessage());
        }
    }

    public function testHeloIsUsedAsFallback()
    {
        /* -- RFC 2821, 4.1.4.

       If the EHLO command is not acceptable to the SMTP server, 501, 500,
       or 502 failure replies MUST be returned as appropriate.  The SMTP
       server MUST stay in the same state after transmitting these replies
       that it was in before the EHLO was received.
        */

        $buf = $this->getBuffer();
        $smtp = $this->getTransport($buf);

        $buf->shouldReceive('initialize')
            ->once();
        $buf->shouldReceive('readLine')
            ->once()
            ->with(0)
            ->andReturn("220 some.server.tld bleh\r\n");
        $buf->shouldReceive('write')
            ->once()
            ->with(Mockery::pattern('~^EHLO .+?\r\n$~D'))
            ->andReturn(1);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(1)
            ->andReturn('501 WTF'."\r\n");
        $buf->shouldReceive('write')
            ->once()
            ->with(Mockery::pattern('~^HELO .+?\r\n$~D'))
            ->andReturn(2);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(2)
            ->andReturn('250 HELO'."\r\n");

        $this->finishBuffer($buf);
        try {
            $smtp->start();
        } catch (Exception $e) {
            $this->fail(
                'Starting Esmtp should fallback to HELO if needed and accept 250 response'
                );
        }
    }

    public function testInvalidHeloResponseCausesException()
    {
        //Overridden to first try EHLO
        $buf = $this->getBuffer();
        $smtp = $this->getTransport($buf);

        $buf->shouldReceive('initialize')
            ->once();
        $buf->shouldReceive('readLine')
            ->once()
            ->with(0)
            ->andReturn("220 some.server.tld bleh\r\n");
        $buf->shouldReceive('write')
            ->once()
            ->with(Mockery::pattern('~^EHLO .+?\r\n$~D'))
            ->andReturn(1);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(1)
            ->andReturn('501 WTF'."\r\n");
        $buf->shouldReceive('write')
            ->once()
            ->with(Mockery::pattern('~^HELO .+?\r\n$~D'))
            ->andReturn(2);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(2)
            ->andReturn('504 WTF'."\r\n");
        $this->finishBuffer($buf);

        try {
            $this->assertFalse($smtp->isStarted(), '%s: SMTP should begin non-started');
            $smtp->start();
            $this->fail('Non 250 HELO response should raise Exception');
        } catch (Exception $e) {
            $this->assertFalse($smtp->isStarted(), '%s: SMTP start() should have failed');
        }
    }

    public function testDomainNameIsPlacedInEhlo()
    {
        /* -- RFC 2821, 4.1.4.

       The SMTP client MUST, if possible, ensure that the domain parameter
       to the EHLO command is a valid principal host name (not a CNAME or MX
       name) for its host.  If this is not possible (e.g., when the client's
       address is dynamically assigned and the client does not have an
       obvious name), an address literal SHOULD be substituted for the
       domain name and supplemental information provided that will assist in
       identifying the client.
        */

        $buf = $this->getBuffer();
        $smtp = $this->getTransport($buf);
        $buf->shouldReceive('initialize')
            ->once();
        $buf->shouldReceive('readLine')
            ->once()
            ->with(0)
            ->andReturn("220 some.server.tld bleh\r\n");
        $buf->shouldReceive('write')
            ->once()
            ->with("EHLO mydomain.com\r\n")
            ->andReturn(1);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(1)
            ->andReturn('250 ServerName'."\r\n");

        $this->finishBuffer($buf);
        $smtp->setLocalDomain('mydomain.com');
        $smtp->start();
    }

    public function testDomainNameIsPlacedInHelo()
    {
        //Overridden to include ESMTP
        /* -- RFC 2821, 4.1.4.

       The SMTP client MUST, if possible, ensure that the domain parameter
       to the EHLO command is a valid principal host name (not a CNAME or MX
       name) for its host.  If this is not possible (e.g., when the client's
       address is dynamically assigned and the client does not have an
       obvious name), an address literal SHOULD be substituted for the
       domain name and supplemental information provided that will assist in
       identifying the client.
        */

        $buf = $this->getBuffer();
        $smtp = $this->getTransport($buf);
        $buf->shouldReceive('initialize')
            ->once();
        $buf->shouldReceive('readLine')
            ->once()
            ->with(0)
            ->andReturn("220 some.server.tld bleh\r\n");
        $buf->shouldReceive('write')
            ->once()
            ->with(Mockery::pattern('~^EHLO .+?\r\n$~D'))
            ->andReturn(1);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(1)
            ->andReturn('501 WTF'."\r\n");
        $buf->shouldReceive('write')
            ->once()
            ->with("HELO mydomain.com\r\n")
            ->andReturn(2);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(2)
            ->andReturn('250 ServerName'."\r\n");

        $this->finishBuffer($buf);
        $smtp->setLocalDomain('mydomain.com');
        $smtp->start();
    }

    public function testPipelining()
    {
        $buf = $this->getBuffer();
        $smtp = $this->getTransport($buf);
        $this->assertNull($smtp->getPipelining());

        $message = $this->createMessage();
        $message->shouldReceive('getFrom')
                ->zeroOrMoreTimes()
                ->andReturn(['me@domain.com' => 'Me']);
        $message->shouldReceive('getTo')
                ->zeroOrMoreTimes()
                ->andReturn(['foo@bar' => null]);

        $buf->shouldReceive('initialize')
            ->once();
        $buf->shouldReceive('readLine')
            ->once()
            ->with(0)
            ->andReturn("220 some.server.tld bleh\r\n");
        $buf->shouldReceive('write')
            ->once()
            ->with(Mockery::pattern('~^EHLO .+?\r\n$~D'))
            ->andReturn(1);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(1)
            ->andReturn('250-ServerName'."\r\n");
        $buf->shouldReceive('readLine')
            ->once()
            ->with(1)
            ->andReturn('250 PIPELINING'."\r\n");

        $buf->shouldReceive('write')
            ->ordered()
            ->once()
            ->with("MAIL FROM:<me@domain.com>\r\n")
            ->andReturn(1);
        $buf->shouldReceive('write')
            ->ordered()
            ->once()
            ->with("RCPT TO:<foo@bar>\r\n")
            ->andReturn(2);
        $buf->shouldReceive('write')
            ->ordered()
            ->once()
            ->with("DATA\r\n")->andReturn(3);
        $buf->shouldReceive('readLine')
            ->ordered()
            ->once()
            ->with(1)->andReturn("250 OK\r\n");
        $buf->shouldReceive('readLine')
            ->ordered()
            ->once()
            ->with(2)->andReturn("250 OK\r\n");
        $buf->shouldReceive('readLine')
            ->ordered()
            ->once()
            ->with(3)->andReturn("354 OK\r\n");

        $this->finishBuffer($buf);
        $smtp->start();
        $sent = $smtp->send($message, $failedRecipients);

        $this->assertEquals(1, $sent);
        $this->assertEmpty($failedRecipients);

        $this->assertTrue($smtp->getPipelining());
    }

    public function testPipeliningWithRecipientFailure()
    {
        $buf = $this->getBuffer();
        $smtp = $this->getTransport($buf);
        $this->assertNull($smtp->getPipelining());

        $message = $this->createMessage();
        $message->shouldReceive('getFrom')
                ->zeroOrMoreTimes()
                ->andReturn(['me@domain.com' => 'Me']);
        $message->shouldReceive('getTo')
                ->zeroOrMoreTimes()
                ->andReturn([
                    'good@foo' => null,
                    'bad@foo' => null,
                    'good@bar' => null,
                ]);

        $buf->shouldReceive('initialize')
            ->once();
        $buf->shouldReceive('readLine')
            ->once()
            ->with(0)
            ->andReturn("220 some.server.tld bleh\r\n");
        $buf->shouldReceive('write')
            ->once()
            ->with(Mockery::pattern('~^EHLO .+?\r\n$~D'))
            ->andReturn(1);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(1)
            ->andReturn('250-ServerName'."\r\n");
        $buf->shouldReceive('readLine')
            ->once()
            ->with(1)
            ->andReturn('250 PIPELINING'."\r\n");

        $buf->shouldReceive('write')
            ->ordered()
            ->once()
            ->with("MAIL FROM:<me@domain.com>\r\n")
            ->andReturn(1);
        $buf->shouldReceive('write')
            ->ordered()
            ->once()
            ->with("RCPT TO:<good@foo>\r\n")
            ->andReturn(2);
        $buf->shouldReceive('write')
            ->ordered()
            ->once()
            ->with("RCPT TO:<bad@foo>\r\n")
            ->andReturn(3);
        $buf->shouldReceive('write')
            ->ordered()
            ->once()
            ->with("RCPT TO:<good@bar>\r\n")
            ->andReturn(4);
        $buf->shouldReceive('write')
            ->ordered()
            ->once()
            ->with("DATA\r\n")
            ->andReturn(5);
        $buf->shouldReceive('readLine')
            ->ordered()
            ->once()
            ->with(1)
            ->andReturn("250 OK\r\n");
        $buf->shouldReceive('readLine')
            ->ordered()
            ->once()
            ->with(2)
            ->andReturn("250 OK\r\n");
        $buf->shouldReceive('readLine')
            ->ordered()
            ->once()
            ->with(3)
            ->andReturn("450 Unknown address bad@foo\r\n");
        $buf->shouldReceive('readLine')
            ->ordered()
            ->once()
            ->with(4)
            ->andReturn("250 OK\r\n");
        $buf->shouldReceive('readLine')
            ->ordered()
            ->once()
            ->with(5)
            ->andReturn("354 OK\r\n");

        $this->finishBuffer($buf);
        $smtp->start();
        $sent = $smtp->send($message, $failedRecipients);

        $this->assertEquals(2, $sent);
        $this->assertEquals(['bad@foo'], $failedRecipients);

        $this->assertTrue($smtp->getPipelining());
    }

    public function testPipeliningWithSenderFailure()
    {
        $buf = $this->getBuffer();
        $smtp = $this->getTransport($buf);
        $this->assertNull($smtp->getPipelining());

        $message = $this->createMessage();
        $message->shouldReceive('getFrom')
                ->zeroOrMoreTimes()
                ->andReturn(['me@domain.com' => 'Me']);
        $message->shouldReceive('getTo')
                ->zeroOrMoreTimes()
                ->andReturn(['foo@bar' => null]);

        $buf->shouldReceive('initialize')
            ->once();
        $buf->shouldReceive('readLine')
            ->once()
            ->with(0)
            ->andReturn("220 some.server.tld bleh\r\n");
        $buf->shouldReceive('write')
            ->once()
            ->with(Mockery::pattern('~^EHLO .+?\r\n$~D'))
            ->andReturn(1);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(1)
            ->andReturn('250-ServerName'."\r\n");
        $buf->shouldReceive('readLine')
            ->once()
            ->with(1)
            ->andReturn('250 PIPELINING'."\r\n");

        $buf->shouldReceive('write')
            ->ordered()
            ->once()
            ->with("MAIL FROM:<me@domain.com>\r\n")
            ->andReturn(1);
        $buf->shouldReceive('write')
            ->ordered()
            ->once()
            ->with("RCPT TO:<foo@bar>\r\n")
            ->andReturn(2);
        $buf->shouldReceive('write')
            ->ordered()
            ->once()
            ->with("DATA\r\n")->andReturn(3);
        $buf->shouldReceive('readLine')
            ->ordered()
            ->once()
            ->with(1)
            ->andReturn("550 Unknown address me@domain.com\r\n");

        $smtp->start();

        $this->expectException('Swift_TransportException');
        $this->expectExceptionMessage('Expected response code 250 but got code "550"');
        $smtp->send($message, $failedRecipients);
    }

    public function testPipeliningWithDataFailure()
    {
        $buf = $this->getBuffer();
        $smtp = $this->getTransport($buf);
        $this->assertNull($smtp->getPipelining());

        $message = $this->createMessage();
        $message->shouldReceive('getFrom')
                ->zeroOrMoreTimes()
                ->andReturn(['me@domain.com' => 'Me']);
        $message->shouldReceive('getTo')
                ->zeroOrMoreTimes()
                ->andReturn(['foo@bar' => null]);

        $buf->shouldReceive('initialize')
            ->once();
        $buf->shouldReceive('readLine')
            ->once()
            ->with(0)
            ->andReturn("220 some.server.tld bleh\r\n");
        $buf->shouldReceive('write')
            ->once()
            ->with(Mockery::pattern('~^EHLO .+?\r\n$~D'))
            ->andReturn(1);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(1)
            ->andReturn('250-ServerName'."\r\n");
        $buf->shouldReceive('readLine')
            ->once()
            ->with(1)
            ->andReturn('250 PIPELINING'."\r\n");

        $buf->shouldReceive('write')
            ->ordered()
            ->once()
            ->with("MAIL FROM:<me@domain.com>\r\n")
            ->andReturn(1);
        $buf->shouldReceive('write')
            ->ordered()
            ->once()
            ->with("RCPT TO:<foo@bar>\r\n")
            ->andReturn(2);
        $buf->shouldReceive('write')
            ->ordered()
            ->once()
            ->with("DATA\r\n")->andReturn(3);
        $buf->shouldReceive('readLine')
            ->ordered()
            ->once()
            ->with(1)
            ->andReturn("250 OK\r\n");
        $buf->shouldReceive('readLine')
            ->ordered()
            ->once()
            ->with(2)
            ->andReturn("250 OK\r\n");
        $buf->shouldReceive('readLine')
            ->ordered()
            ->once()
            ->with(3)
            ->andReturn("452 Insufficient system storage\r\n");

        $smtp->start();

        $this->expectException('Swift_TransportException');
        $this->expectExceptionMessage('Expected response code 354 but got code "452"');
        $smtp->send($message, $failedRecipients);
    }

    public function providerPipeliningOverride()
    {
        return [
            [null, true, true],
            [null, false, false],
            [true, false, true],
            [true, true, true],
            [false, false, false],
            [false, true, false],
        ];
    }

    /**
     * @dataProvider providerPipeliningOverride
     */
    public function testPipeliningOverride($enabled, bool $supported, bool $expected)
    {
        $buf = $this->getBuffer();
        $smtp = $this->getTransport($buf);
        $this->assertNull($smtp->getPipelining());

        $smtp->setPipelining($enabled);
        $this->assertSame($enabled, $smtp->getPipelining());

        $message = $this->createMessage();
        $message->shouldReceive('getFrom')
                ->zeroOrMoreTimes()
                ->andReturn(['me@domain.com' => 'Me']);

        $buf->shouldReceive('initialize')
            ->once();
        $buf->shouldReceive('readLine')
            ->once()
            ->with(0)
            ->andReturn("220 some.server.tld bleh\r\n");
        $buf->shouldReceive('write')
            ->once()
            ->with(Mockery::pattern('~^EHLO .+?\r\n$~D'))
            ->andReturn(1);
        $buf->shouldReceive('readLine')
            ->once()
            ->with(1)
            ->andReturn('250-ServerName'."\r\n");
        $buf->shouldReceive('readLine')
            ->once()
            ->with(1)
            ->andReturn('250 '.($supported ? 'PIPELINING' : 'FOOBAR')."\r\n");

        $this->finishBuffer($buf);
        $smtp->start();
        $smtp->send($message);

        $this->assertSame($expected, $smtp->getPipelining());
    }

    public function testFluidInterface()
    {
        $buf = $this->getBuffer();
        $smtp = $this->getTransport($buf);
        $buf->shouldReceive('setParam')
            ->once()
            ->with('timeout', 30);

        $ref = $smtp
            ->setHost('foo')
            ->setPort(25)
            ->setEncryption('tls')
            ->setTimeout(30)
            ->setPipelining(false)
            ;
        $this->assertEquals($ref, $smtp);
    }
}


================================================
FILE: tests/unit/Swift/Transport/FailoverTransportTest.php
================================================
<?php

class Swift_Transport_FailoverTransportTest extends \SwiftMailerTestCase
{
    public function testFirstTransportIsUsed()
    {
        $message1 = $this->getMockery('Swift_Mime_SimpleMessage');
        $message2 = $this->getMockery('Swift_Mime_SimpleMessage');
        $t1 = $this->getMockery('Swift_Transport');
        $t2 = $this->getMockery('Swift_Transport');
        $connectionState = false;

        $t1->shouldReceive('isStarted')
           ->zeroOrMoreTimes()
           ->andReturnUsing(function () use (&$connectionState) {
               return $connectionState;
           });
        $t1->shouldReceive('start')
           ->once()
           ->andReturnUsing(function () use (&$connectionState) {
               if (!$connectionState) {
                   $connectionState = true;
               }
           });
        $t1->shouldReceive('send')
           ->twice()
           ->with(\Mockery::anyOf($message1, $message2), \Mockery::any())
           ->andReturnUsing(function () use (&$connectionState) {
               if ($connectionState) {
                   return 1;
               }
           });
        $t2->shouldReceive('start')->never();
        $t2->shouldReceive('send')->never();

        $transport = $this->getTransport([$t1, $t2]);
        $transport->start();
        $this->assertEquals(1, $transport->send($message1));
        $this->assertEquals(1, $transport->send($message2));
    }

    public function testMessageCanBeTriedOnNextTransportIfExceptionThrown()
    {
        $e = new Swift_TransportException('b0rken');

        $message = $this->getMockery('Swift_Mime_SimpleMessage');
        $t1 = $this->getMockery('Swift_Transport');
        $t2 = $this->getMockery('Swift_Transport');
        $connectionState1 = false;
        $connectionState2 = false;

        $t1->shouldReceive('isStarted')
           ->zeroOrMoreTimes()
           ->andReturnUsing(function () use (&$connectionState1) {
               return $connectionState1;
           });
        $t1->shouldReceive('start')
           ->once()
           ->andReturnUsing(function () use (&$connectionState1) {
               if (!$connectionState1) {
                   $connectionState1 = true;
               }
           });
        $t1->shouldReceive('send')
           ->once()
           ->with($message, \Mockery::any())
           ->andReturnUsing(function () use (&$connectionState1, $e) {
               if ($connectionState1) {
                   throw $e;
               }
           });

        $t2->shouldReceive('isStarted')
           ->zeroOrMoreTimes()
           ->andReturnUsing(function () use (&$connectionState2) {
               return $connectionState2;
           });
        $t2->shouldReceive('start')
           ->once()
           ->andReturnUsing(function () use (&$connectionState2) {
               if (!$connectionState2) {
                   $connectionState2 = true;
               }
           });
        $t2->shouldReceive('send')
           ->once()
           ->with($message, \Mockery::any())
           ->andReturnUsing(function () use (&$connectionState2) {
               if ($connectionState2) {
                   return 1;
               }
           });

        $transport = $this->getTransport([$t1, $t2]);
        $transport->start();
        $this->assertEquals(1, $transport->send($message));
    }

    public function testZeroIsReturnedIfTransportReturnsZero()
    {
        $message = $this->getMockery('Swift_Mime_SimpleMessage')->shouldIgnoreMissing();
        $t1 = $this->getMockery('Swift_Transport')->shouldIgnoreMissing();

        $connectionState = false;
        $t1->shouldReceive('isStarted')
           ->zeroOrMoreTimes()
           ->andReturnUsing(function () use (&$connectionState) {
               return $connectionState;
           });
        $t1->shouldReceive('start')
           ->once()
           ->andReturnUsing(function () use (&$connectionState) {
               if (!$connectionState) {
                   $connectionState = true;
               }
           });
        $testCase = $this;
        $t1->shouldReceive('send')
           ->once()
           ->with($message, \Mockery::any())
           ->andReturnUsing(function () use (&$connectionState, $testCase) {
               if (!$connectionState) {
                   $testCase->fail();
               }

               return 0;
           });

        $transport = $this->getTransport([$t1]);
        $transport->start();
        $this->assertEquals(0, $transport->send($message));
    }

    public function testTransportsWhichThrowExceptionsAreNotRetried()
    {
        $e = new Swift_TransportException('maur b0rken');

        $message1 = $this->getMockery('Swift_Mime_SimpleMessage');
        $message2 = $this->getMockery('Swift_Mime_SimpleMessage');
        $message3 = $this->getMockery('Swift_Mime_SimpleMessage');
        $message4 = $this->getMockery('Swift_Mime_SimpleMessage');
        $t1 = $this->getMockery('Swift_Transport');
        $t2 = $this->getMockery('Swift_Transport');
        $connectionState1 = false;
        $connectionState2 = false;

        $t1->shouldReceive('isStarted')
           ->zeroOrMoreTimes()
           ->andReturnUsing(function () use (&$connectionState1) {
               return $connectionState1;
           });
        $t1->shouldReceive('start')
           ->once()
           ->andReturnUsing(function () use (&$connectionState1) {
               if (!$connectionState1) {
                   $connectionState1 = true;
               }
           });
        $t1->shouldReceive('send')
           ->once()
           ->with($message1, \Mockery::any())
           ->andReturnUsing(function () use (&$connectionState1, $e) {
               if ($connectionState1) {
                   throw $e;
               }
           });
        $t1->shouldReceive('send')
           ->never()
           ->with($message2, \Mockery::any());
        $t1->shouldReceive('send')
           ->never()
           ->with($message3, \Mockery::any());
        $t1->shouldReceive('send')
           ->never()
           ->with($message4, \Mockery::any());

        $t2->shouldReceive('isStarted')
           ->zeroOrMoreTimes()
           ->andReturnUsing(function () use (&$connectionState2) {
               return $connectionState2;
           });
        $t2->shouldReceive('start')
           ->once()
           ->andReturnUsing(function () use (&$connectionState2) {
               if (!$connectionState2) {
                   $connectionState2 = true;
               }
           });
        $t2->shouldReceive('send')
           ->times(4)
           ->with(\Mockery::anyOf($message1, $message2, $message3, $message4), \Mockery::any())
           ->andReturnUsing(function () use (&$connectionState2) {
               if ($connectionState2) {
                   return 1;
               }
           });

        $transport = $this->getTransport([$t1, $t2]);
        $transport->start();
        $this->assertEquals(1, $transport->send($message1));
        $this->assertEquals(1, $transport->send($message2));
        $this->assertEquals(1, $transport->send($message3));
        $this->assertEquals(1, $transport->send($message4));
    }

    public function testExceptionIsThrownIfAllTransportsDie()
    {
        $e = new Swift_TransportException('b0rken');

        $message = $this->getMockery('Swift_Mime_SimpleMessage');
        $t1 = $this->getMockery('Swift_Transport');
        $t2 = $this->getMockery('Swift_Transport');
        $connectionState1 = false;
        $connectionState2 = false;

        $t1->shouldReceive('isStarted')
           ->zeroOrMoreTimes()
           ->andReturnUsing(function () use (&$connectionState1) {
               return $connectionState1;
           });
        $t1->shouldReceive('start')
           ->once()
           ->andReturnUsing(function () use (&$connectionState1) {
               if (!$connectionState1) {
                   $connectionState1 = true;
               }
           });
        $t1->shouldReceive('send')
           ->once()
           ->with($message, \Mockery::any())
           ->andReturnUsing(function () use (&$connectionState1, $e) {
               if ($connectionState1) {
                   throw $e;
               }
           });

        $t2->shouldReceive('isStarted')
           ->zeroOrMoreTimes()
           ->andReturnUsing(function () use (&$connectionState2) {
               return $connectionState2;
           });
        $t2->shouldReceive('start')
           ->once()
           ->andReturnUsing(function () use (&$connectionState2) {
               if (!$connectionState2) {
                   $connectionState2 = true;
               }
           });
        $t2->shouldReceive('send')
           ->once()
           ->with($message, \Mockery::any())
           ->andReturnUsing(function () use (&$connectionState2, $e) {
               if ($connectionState2) {
                   throw $e;
               }
           });

        $transport = $this->getTransport([$t1, $t2]);
        $transport->start();
        try {
            $transport->send($message);
            $this->fail('All transports failed so Exception should be thrown');
        } catch (Exception $e) {
        }
    }

    public function testStoppingTransportStopsAllDelegates()
    {
        $t1 = $this->getMockery('Swift_Transport');
        $t2 = $this->getMockery('Swift_Transport');

        $connectionState1 = true;
        $connectionState2 = true;

        $t1->shouldReceive('isStarted')
           ->zeroOrMoreTimes()
           ->andReturnUsing(function () use (&$connectionState1) {
               return $connectionState1;
           });
        $t1->shouldReceive('stop')
           ->once()
           ->andReturnUsing(function () use (&$connectionState1) {
               if ($connectionState1) {
                   $connectionState1 = false;
               }
           });

        $t2->shouldReceive('isStarted')
           ->zeroOrMoreTimes()
           ->andReturnUsing(function () use (&$connectionState2) {
               return $connectionState2;
           });
        $t2->shouldReceive('stop')
           ->once()
           ->andReturnUsing(function () use (&$connectionState2) {
               if ($connectionState2) {
                   $connectionState2 = false;
               }
           });

        $transport = $this->getTransport([$t1, $t2]);
        $transport->start();
        $transport->stop();
    }

    public function testTransportShowsAsNotStartedIfAllDelegatesDead()
    {
        $e = new Swift_TransportException('b0rken');

        $message = $this->getMockery('Swift_Mime_SimpleMessage');
        $t1 = $this->getMockery('Swift_Transport');
        $t2 = $this->getMockery('Swift_Transport');

        $connectionState1 = false;
        $connectionState2 = false;

        $t1->shouldReceive('isStarted')
           ->zeroOrMoreTimes()
           ->andReturnUsing(function () use (&$connectionState1) {
               return $connectionState1;
           });
        $t1->shouldReceive('start')
           ->once()
           ->andReturnUsing(function () use (&$connectionState1) {
               if (!$connectionState1) {
                   $connectionState1 = true;
               }
           });
        $t1->shouldReceive('send')
           ->once()
           ->with($message, \Mockery::any())
           ->andReturnUsing(function () use (&$connectionState1, $e) {
               if ($connectionState1) {
                   $connectionState1 = false;
                   throw $e;
               }
           });

        $t2->shouldReceive('isStarted')
           ->zeroOrMoreTimes()
           ->andReturnUsing(function () use (&$connectionState2) {
               return $connectionState2;
           });
        $t2->shouldReceive('start')
           ->once()
           ->andReturnUsing(function () use (&$connectionState2) {
               if (!$connectionState2) {
                   $connectionState2 = true;
               }
           });
        $t2->shouldReceive('send')
           ->once()
           ->with($message, \Mockery::any())
           ->andReturnUsing(function () use (&$connectionState2, $e) {
               if ($connectionState2) {
                   $connectionState2 = false;
                   throw $e;
               }
           });

        $transport = $this->getTransport([$t1, $t2]);
        $transport->start();
        $this->assertTrue($transport->isStarted());
        try {
            $transport->send($message);
            $this->fail('All transports failed so Exception should be thrown');
        } catch (Exception $e) {
            $this->assertFalse($transport->isStarted());
        }
    }

    public function testRestartingTransportRestartsDeadDelegates()
    {
        $e = new Swift_TransportException('b0rken');

        $message1 = $this->getMockery('Swift_Mime_SimpleMessage');
        $message2 = $this->getMockery('Swift_Mime_SimpleMessage');
        $t1 = $this->getMockery('Swift_Transport');
        $t2 = $this->getMockery('Swift_Transport');

        $connectionState1 = false;
        $connectionState2 = false;

        $t1->shouldReceive('isStarted')
           ->zeroOrMoreTimes()
           ->andReturnUsing(function () use (&$connectionState1) {
               return $connectionState1;
           });
        $t1->shouldReceive('start')
           ->twice()
           ->andReturnUsing(function () use (&$connectionState1) {
               if (!$connectionState1) {
                   $connectionState1 = true;
               }
           });
        $t1->shouldReceive('send')
           ->once()
           ->with($message1, \Mockery::any())
           ->andReturnUsing(function () use (&$connectionState1, $e) {
               if ($connectionState1) {
                   $connectionState1 = false;
                   throw $e;
               }
           });
        $t1->shouldReceive('send')
           ->once()
           ->with($message2, \Mockery::any())
           ->andReturnUsing(function () use (&$connectionState1) {
               if ($connectionState1) {
                   return 10;
               }
           });

        $t2->shouldReceive('isStarted')
           ->zeroOrMoreTimes()
           ->andReturnUsing(function () use (&$connectionState2) {
               return $connectionState2;
           });
        $t2->shouldReceive('start')
           ->once()
           ->andReturnUsing(function () use (&$connectionState2) {
               if (!$connectionState2) {
                   $connectionState2 = true;
               }
           });
        $t2->shouldReceive('send')
           ->once()
           ->with($message1, \Mockery::any())
           ->andReturnUsing(function () use (&$connectionState2, $e) {
               if ($connectionState2) {
                   $connectionState2 = false;
                   throw $e;
               }
           });
        $t2->shouldReceive('send')
           ->never()
           ->with($message2, \Mockery::any());

        $transport = $this->getTransport([$t1, $t2]);
        $transport->start();
        $this->assertTrue($transport->isStarted());
        try {
            $transport->send($message1);
            $this->fail('All transports failed so Exception should be thrown');
        } catch (Exception $e) {
            $this->assertFalse($transport->isStarted());
        }
        //Restart and re-try
        $transport->start();
        $this->assertTrue($transport->isStarted());
        $this->assertEquals(10, $transport->send($message2));
    }

    public function testFailureReferenceIsPassedToDelegates()
    {
        $failures = [];

        $message = $this->getMockery('Swift_Mime_SimpleMessage');
        $t1 = $this->getMockery('Swift_Transport');

        $connectionState = false;

        $t1->shouldReceive('isStarted')
           ->zeroOrMoreTimes()
           ->andReturnUsing(function () use ($connectionState) {
               return $connectionState;
           });
        $t1->shouldReceive('start')
           ->once()
           ->andReturnUsing(function () use ($connectionState) {
               if (!$connectionState) {
                   $connectionState = true;
               }
           });
        $t1->shouldReceive('send')
           ->once()
           ->with($message, $failures)
           ->andReturnUsing(function () use ($connectionState) {
               if ($connectionState) {
                   return 1;
               }
           });

        $transport = $this->getTransport([$t1]);
        $transport->start();
        $transport->send($message, $failures);
    }

    public function testRegisterPluginDelegatesToLoadedTransports()
    {
        $plugin = $this->createPlugin();

        $t1 = $this->getMockery('Swift_Transport');
        $t2 = $this->getMockery('Swift_Transport');
        $t1->shouldReceive('registerPlugin')
           ->once()
           ->with($plugin);
        $t2->shouldReceive('registerPlugin')
           ->once()
           ->with($plugin);

        $transport = $this->getTransport([$t1, $t2]);
        $transport->registerPlugin($plugin);
    }

    public function testEachDelegateIsPinged()
    {
        $t1 = $this->getMockery('Swift_Transport');
        $t2 = $this->getMockery('Swift_Transport');
        $connectionState1 = false;
        $connectionState2 = false;

        $testCase = $this;
        $t1->shouldReceive('isStarted')
           ->zeroOrMoreTimes()
           ->andReturnUsing(function () use (&$connectionState1) {
               return $connectionState1;
           });
        $t1->shouldReceive('ping')
           ->once()
           ->andReturn(true);

        $transport = $this->getTransport([$t1, $t2]);
        $this->assertTrue($transport->isStarted());
        $this->assertTrue($transport->ping());
    }

    public function testDelegateIsKilledWhenPingFails()
    {
        $t1 = $this->getMockery('Swift_Transport');
        $t2 = $this->getMockery('Swift_Transport');

        $testCase = $this;
        $t1->shouldReceive('isStarted')
           ->zeroOrMoreTimes()
           ->andReturnUsing(function () use (&$connectionState1) {
               return $connectionState1;
           });
        $t1->shouldReceive('ping')
           ->once()
           ->andReturn(false);

        $t2->shouldReceive('isStarted')
           ->zeroOrMoreTimes()
           ->andReturnUsing(function () use (&$connectionState2) {
               return $connectionState2;
           });
        $t2->shouldReceive('ping')
           ->twice()
           ->andReturn(true);

        $transport = $this->getTransport([$t1, $t2]);
        $this->assertTrue($transport->ping());
        $this->assertTrue($transport->ping());
        $this->assertTrue($transport->isStarted());
    }

    public function XtestTransportShowsAsNotStartedIfAllPingFails()
    {
        $t1 = $this->getMockery('Swift_Transport');
        $t2 = $this->getMockery('Swift_Transport');

        $testCase = $this;
        $t1->shouldReceive('isStarted')
           ->zeroOrMoreTimes()
           ->andReturnUsing(function () use (&$connectionState1) {
               return $connectionState1;
           });
        $t1->shouldReceive('ping')
           ->once()
           ->andReturn(false);

        $t2->shouldReceive('isStarted')
           ->zeroOrMoreTimes()
           ->andReturnUsing(function () use (&$connectionState2) {
               return $connectionState2;
           });
        $t2->shouldReceive('ping')
           ->once()
           ->andReturn(false);

        $transport = $this->getTransport([$t1, $t2]);
        $this->assertFalse($transport->ping());
        $this->assertFalse($transport->isStarted());
        $this->assertFalse($transport->ping());
    }

    private function getTransport(array $transports)
    {
        $transport = new Swift_Transport_FailoverTransport();
        $transport->setTransports($transports);

        return $transport;
    }

    private function createPlugin()
    {
        return $this->getMockery('Swift_Events_EventListener');
    }
}


================================================
FILE: tests/unit/Swift/Transport/LoadBalancedTransportTest.php
================================================
<?php

class Swift_Transport_LoadBalancedTransportTest extends \SwiftMailerTestCase
{
    public function testEachTransportIsUsedInTurn()
    {
        $message1 = $this->getMockery('Swift_Mime_SimpleMessage');
        $message2 = $this->getMockery('Swift_Mime_SimpleMessage');
        $t1 = $this->getMockery('Swift_Transport');
        $t2 = $this->getMockery('Swift_Transport');
        $connectionState1 = false;
        $connectionState2 = false;

        $testCase = $this;
        $t1->shouldReceive('isStarted')
           ->zeroOrMoreTimes()
           ->andReturnUsing(function () use (&$connectionState1) {
               return $connectionState1;
           });
        $t1->shouldReceive('start')
           ->once()
           ->andReturnUsing(function () use (&$connectionState1) {
               if (!$connectionState1) {
                   $connectionState1 = true;
               }
           });
        $t1->shouldReceive('send')
           ->once()
           ->with($message1, \Mockery::any())
           ->andReturnUsing(function () use (&$connectionState1, $testCase) {
               if ($connectionState1) {
                   return 1;
               }
               $testCase->fail();
           });
        $t1->shouldReceive('send')
           ->never()
           ->with($message2, \Mockery::any());

        $t2->shouldReceive('isStarted')
           ->zeroOrMoreTimes()
           ->andReturnUsing(function () use (&$connectionState2) {
               return $connectionState2;
           });
        $t2->shouldReceive('start')
           ->once()
           ->andReturnUsing(function () use (&$connectionState2) {
               if (!$connectionState2) {
                   $connectionState2 = true;
               }
           });
        $t2->shouldReceive('send')
           ->once()
           ->with($message2, \Mockery::any())
           ->andReturnUsing(function () use (&$connectionState2, $testCase) {
               if ($connectionState2) {
                   return 1;
               }
               $testCase->fail();
           });
        $t2->shouldReceive('send')
           ->never()
           ->with($message1, \Mockery::any());

        $transport = $this->getTransport([$t1, $t2]);
        $transport->start();
        $this->assertEquals(1, $transport->send($message1));
        $this->assertEquals(1, $transport->send($message2));
    }

    public function testTransportsAreReusedInRotatingFashion()
    {
        $message1 = $this->getMockery('Swift_Mime_SimpleMessage');
        $message2 = $this->getMockery('Swift_Mime_SimpleMessage');
        $message3 = $this->getMockery('Swift_Mime_SimpleMessage');
        $message4 = $this->getMockery('Swift_Mime_SimpleMessage');
        $t1 = $this->getMockery('Swift_Transport');
        $t2 = $this->getMockery('Swift_Transport');
        $connectionState1 = false;
        $connectionState2 = false;

        $testCase = $this;
        $t1->shouldReceive('isStarted')
           ->zeroOrMoreTimes()
           ->andReturnUsing(function () use (&$connectionState1) {
               return $connectionState1;
           });
        $t1->shouldReceive('start')
           ->once()
           ->andReturnUsing(function () use (&$connectionState1) {
               if (!$connectionState1) {
                   $connectionState1 = true;
               }
           });
        $t1->shouldReceive('send')
           ->once()
           ->with($message1, \Mockery::any())
           ->andReturnUsing(function () use (&$connectionState1, $testCase) {
               if ($connectionState1) {
                   return 1;
               }
               $testCase->fail();
           });
        $t1->shouldReceive('send')
           ->never()
           ->with($message2, \Mockery::any());
        $t1->shouldReceive('send')
           ->once()
           ->with($message3, \Mockery::any())
           ->andReturnUsing(function () use (&$connectionState1, $testCase) {
               if ($connectionState1) {
                   return 1;
               }
               $testCase->fail();
           });
        $t1->shouldReceive('send')
           ->never()
           ->with($message4, \Mockery::any());

        $t2->shouldReceive('isStarted')
           ->zeroOrMoreTimes()
           ->andReturnUsing(function () use (&$connectionState2) {
               return $connectionState2;
           });
        $t2->shouldReceive('start')
           ->once()
           ->andReturnUsing(function () use (&$connectionState2) {
               if (!$connectionState2) {
                   $connectionState2 = true;
               }
           });
        $t2->shouldReceive('send')
           ->once()
           ->with($message2, \Mockery::any())
           ->andReturnUsing(function () use (&$connectionState2, $testCase) {
               if ($connectionState2) {
                   return 1;
               }
               $testCase->fail();
           });
        $t2->shouldReceive('send')
           ->never()
           ->with($message1, \Mockery::any());
        $t2->shouldReceive('send')
           ->once()
           ->with($message4, \Mockery::any())
           ->andReturnUsing(function () use (&$connectionState2, $testCase) {
               if ($connectionState2) {
                   return 1;
               }
               $testCase->fail();
           });
        $t2->shouldReceive('send')
           ->never()
           ->with($message3, \Mockery::any());

        $transport = $this->getTransport([$t1, $t2]);
        $transport->start();

        $this->assertEquals(1, $transport->send($message1));
        $this->assertEquals(1, $transport->send($message2));
        $this->assertEquals(1, $transport->send($message3));
        $this->assertEquals(1, $transport->send($message4));
    }

    public function testMessageCanBeTriedOnNextTransportIfExceptionThrown()
    {
        $e = new Swift_TransportException('b0rken');

        $message = $this->getMockery('Swift_Mime_SimpleMessage');
        $t1 = $this->getMockery('Swift_Transport');
        $t2 = $this->getMockery('Swift_Transport');
        $connectionState1 = false;
        $connectionState2 = false;

        $testCase = $this;
        $t1->shouldReceive('isStarted')
           ->zeroOrMoreTimes()
           ->andReturnUsing(function () use (&$connectionState1) {
               return $connectionState1;
           });
        $t1->shouldReceive('start')
           ->once()
           ->andReturnUsing(function () use (&$connectionState1) {
               if (!$connectionState1) {
                   $connectionState1 = true;
               }
           });
        $t1->shouldReceive('send')
           ->once()
           ->with($message, \Mockery::any())
           ->andReturnUsing(function () use (&$connectionState1, $e, $testCase) {
               if ($connectionState1) {
                   throw $e;
               }
               $testCase->fail();
           });

        $t2->shouldReceive('isStarted')
           ->zeroOrMoreTimes()
           ->andReturnUsing(function () use (&$connectionState2) {
               return $connectionState2;
           });
        $t2->shouldReceive('start')
           ->once()
           ->andReturnUsing(function () use (&$connectionState2) {
               if (!$connectionState2) {
                   $connectionState2 = true;
               }
           });
        $t2->shouldReceive('send')
           ->once()
           ->with($message, \Mockery::any())
           ->andReturnUsing(function () use (&$connectionState2, $testCase) {
               if ($connectionState2) {
                   return 1;
               }
               $testCase->fail();
           });

        $transport = $this->getTransport([$t1, $t2]);
        $transport->start();
        $this->assertEquals(1, $transport->send($message));
    }

    public function testMessageIsTriedOnNextTransportIfZeroReturned()
    {
        $message = $this->getMockery('Swift_Mime_SimpleMessage');
        $t1 = $this->getMockery('Swift_Transport');
        $t2 = $this->getMockery('Swift_Transport');
        $connectionState1 = false;
        $connectionState2 = false;

        $t1->shouldReceive('isStarted')
           ->zeroOrMoreTimes()
           ->andReturnUsing(function () use (&$connectionState1) {
               return $connectionState1;
           });
        $t1->shouldReceive('start')
           ->once()
           ->andReturnUsing(function () use (&$connectionState1) {
               if (!$connectionState1) {
                   $connectionState1 = true;
               }
           });
        $t1->shouldReceive('send')
           ->once()
           ->with($message, \Mockery::any())
           ->andReturnUsing(function () use (&$connectionState1) {
               if ($connectionState1) {
                   return 0;
               }

               return 1;
           });

        $t2->shouldReceive('isStarted')
           ->zeroOrMoreTimes()
           ->andReturnUsing(function () use (&$connectionState2) {
               return $connectionState2;
           });
        $t2->shouldReceive('start')
           ->once()
           ->andReturnUsing(function () use (&$connectionState2) {
               if (!$connectionState2) {
                   $connectionState2 = true;
               }
           });
        $t2->shouldReceive('send')
           ->once()
           ->with($message, \Mockery::any())
           ->andReturnUsing(function () use (&$connectionState2) {
               if ($connectionState2) {
                   return 1;
               }

               return 0;
           });

        $transport = $this->getTransport([$t1, $t2]);
        $transport->start();
        $this->assertEquals(1, $transport->send($message));
    }

    public function testZeroIsReturnedIfAllTransportsReturnZero()
    {
        $message = $this->getMockery('Swift_Mime_SimpleMessage');
        $t1 = $this->getMockery('Swift_Transport');
        $t2 = $this->getMockery('Swift_Transport');
        $connectionState1 = false;
        $connectionState2 = false;

        $t1->shouldReceive('isStarted')
           ->zeroOrMoreTimes()
           ->andReturnUsing(function () use (&$connectionState1) {
               return $connectionState1;
           });
        $t1->shouldReceive('start')
           ->once()
           ->andReturnUsing(function () use (&$connectionState1) {
               if (!$connectionState1) {
                   $connectionState1 = true;
               }
           });
        $t1->shouldReceive('send')
           ->once()
           ->with($message, \Mockery::any())
           ->andReturnUsing(function () use (&$connectionState1) {
               if ($connectionState1) {
                   return 0;
               }

               return 1;
           });

        $t2->shouldReceive('isStarted')
           ->zeroOrMoreTimes()
           ->andReturnUsing(function () use (&$connectionState2) {
               return $connectionState2;
           });
        $t2->shouldReceive('start')
           ->once()
           ->andReturnUsing(function () use (&$connectionState2) {
               if (!$connectionState2) {
                   $connectionState2 = true;
               }
           });
        $t2->shouldReceive('send')
           ->once()
           ->with($message, \Mockery::any())
           ->andReturnUsing(function () use (&$connectionState2) {
               if ($connectionState2) {
                   return 0;
               }

               return 1;
           });

        $transport = $this->getTransport([$t1, $t2]);
        $transport->start();
        $this->assertEquals(0, $transport->send($message));
    }
/*
FIXME: Does not work anymore after upgrading Mockery
    public function testTransportsWhichThrowExceptionsAreNotRetried()
    {
        $e = new Swift_TransportException('maur b0rken');

        $message1 = $this->getMockery('Swift_Mime_SimpleMessage');
        $message2 = $this->getMockery('Swift_Mime_SimpleMessage');
        $message3 = $this->getMockery('Swift_Mime_SimpleMessage');
        $message4 = $this->getMockery('Swift_Mime_SimpleMessage');
        $t1 = $this->getMockery('Swift_Transport');
        $t2 = $this->getMockery('Swift_Transport');
        $connectionState1 = false;
        $connectionState2 = false;

        $testCase = $this;
        $t1->shouldReceive('isStarted')
           ->zeroOrMoreTimes()
           ->andReturnUsing(function () use (&$connectionState1) {
               return $connectionState1;
           });
        $t1->shouldReceive('start')
           ->once()
           ->andReturnUsing(function () use (&$connectionState1) {
               if (!$connectionState1) {
                   $connectionState1 = true;
               }
           });
        $t1->shouldReceive('send')
           ->once()
           ->with($message1, \Mockery::any())
           ->andReturnUsing(function () use (&$connectionState1, $e, $testCase) {
               if ($connectionState1) {
                   throw $e;
               }
               $testCase->fail();
           });
        $t1->shouldReceive('send')
           ->never()
           ->with($message2, \Mockery::any());
        $t1->shouldReceive('send')
           ->never()
           ->with($message3, \Mockery::any());
        $t1->shouldReceive('send')
           ->never()
           ->with($message4, \Mockery::any());

        $t2->shouldReceive('isStarted')
           ->zeroOrMoreTimes()
           ->andReturnUsing(function () use (&$connectionState2) {
               return $connectionState2;
           });
        $t2->shouldReceive('start')
           ->once()
           ->andReturnUsing(function () use (&$connectionState2) {
               if (!$connectionState2) {
                   $connectionState2 = true;
               }
           });
        $t2->shouldReceive('send')
           ->times(4)
           ->with(\Mockery::anyOf($message1, $message3, $message3, $message4), \Mockery::any())
           ->andReturnUsing(function () use (&$connectionState2, $testCase) {
               if ($connectionState2) {
                   return 1;
               }
               $testCase->fail();
           });

        $transport = $this->getTransport([$t1, $t2]);
        $transport->start();
        $this->assertEquals(1, $transport->send($message1));
        $this->assertEquals(1, $transport->send($message2));
        $this->assertEquals(1, $transport->send($message3));
        $this->assertEquals(1, $transport->send($message4));
    }
*/
    public function testExceptionIsThrownIfAllTransportsDie()
    {
        $e = new Swift_TransportException('b0rken');

        $message = $this->getMockery('Swift_Mime_SimpleMessage');
        $t1 = $this->getMockery('Swift_Transport');
        $t2 = $this->getMockery('Swift_Transport');
        $connectionState1 = false;
        $connectionState2 = false;

        $t1->shouldReceive('isStarted')
           ->zeroOrMoreTimes()
           ->andReturnUsing(function () use (&$connectionState1) {
               return $connectionState1;
           });
        $t1->shouldReceive('start')
           ->once()
           ->andReturnUsing(function () use (&$connectionState1) {
               if (!$connectionState1) {
                   $connectionState1 = true;
               }
           });
        $t1->shouldReceive('send')
           ->once()
           ->with($message, \Mockery::any())
           ->andReturnUsing(function () use (&$connectionState1, $e) {
               if ($connectionState1) {
                   throw $e;
               }
           });

        $t2->shouldReceive('isStarted')
           ->zeroOrMoreTimes()
           ->andReturnUsing(function () use (&$connectionState2) {
               return $connectionState2;
           });
        $t2->shouldReceive('start')
           ->once()
           ->andReturnUsing(function () use (&$connectionState2) {
               if (!$connectionState2) {
                   $connectionState2 = true;
               }
           });
        $t2->shouldReceive('send')
           ->once()
           ->with($message, \Mockery::any())
           ->andReturnUsing(function () use (&$connectionState2, $e) {
               if ($connectionState2) {
                   throw $e;
               }
           });

        $transport = $this->getTransport([$t1, $t2]);
        $transport->start();
        try {
            $transport->send($message);
            $this->fail('All transports failed so Exception should be thrown');
        } catch (Exception $e) {
        }
    }

    public function testStoppingTransportStopsAllDelegates()
    {
        $t1 = $this->getMockery('Swift_Transport');
        $t2 = $this->getMockery('Swift_Transport');
        $connectionState1 = true;
        $connectionState2 = true;

        $t1->shouldReceive('isStarted')
           ->zeroOrMoreTimes()
           ->andReturnUsing(function () use (&$connectionState1) {
               return $connectionState1;
           });
        $t1->shouldReceive('stop')
           ->once()
           ->andReturnUsing(function () use (&$connectionState1) {
               if ($connectionState1) {
                   $connectionState1 = false;
               }
           });

        $t2->shouldReceive('isStarted')
           ->zeroOrMoreTimes()
           ->andReturnUsing(function () use (&$connectionState2) {
               return $connectionState2;
           });
        $t2->shouldReceive('stop')
           ->once()
           ->andReturnUsing(function () use (&$connectionState2) {
               if ($connectionState2) {
                   $connectionState2 = false;
               }
           });

        $transport = $this->getTransport([$t1, $t2]);
        $transport->start();
        $transport->stop();
    }

    public function testTransportShowsAsNotStartedIfAllDelegatesDead()
    {
        $e = new Swift_TransportException('b0rken');

        $message = $this->getMockery('Swift_Mime_SimpleMessage');
        $t1 = $this->getMockery('Swift_Transport');
        $t2 = $this->getMockery('Swift_Transport');
        $connectionState1 = false;
        $connectionState2 = false;

        $t1->shouldReceive('isStarted')
           ->zeroOrMoreTimes()
           ->andReturnUsing(function () use (&$connectionState1) {
               return $connectionState1;
           });
        $t1->shouldReceive('start')
           ->once()
           ->andReturnUsing(function () use (&$connectionState1) {
               if (!$connectionState1) {
                   $connectionState1 = true;
               }
           });
        $t1->shouldReceive('send')
           ->once()
           ->with($message, \Mockery::any())
           ->andReturnUsing(function () use (&$connectionState1, $e) {
               if ($connectionState1) {
                   throw $e;
               }
           });

        $t2->shouldReceive('isStarted')
           ->zeroOrMoreTimes()
           ->andReturnUsing(function () use (&$connectionState2) {
               return $connectionState2;
           });
        $t2->shouldReceive('start')
           ->once()
           ->andReturnUsing(function () use (&$connectionState2) {
               if (!$connectionState2) {
                   $connectionState2 = true;
               }
           });
        $t2->shouldReceive('send')
           ->once()
           ->with($message, \Mockery::any())
           ->andReturnUsing(function () use (&$connectionState2, $e) {
               if ($connectionState2) {
                   throw $e;
               }
           });

        $transport = $this->getTransport([$t1, $t2]);
        $transport->start();
        $this->assertTrue($transport->isStarted());
        try {
            $transport->send($message);
            $this->fail('All transports failed so Exception should be thrown');
        } catch (Exception $e) {
            $this->assertFalse($transport->isStarted());
        }
    }

    public function testRestartingTransportRestartsDeadDelegates()
    {
        $e = new Swift_TransportException('b0rken');

        $message1 = $this->getMockery('Swift_Mime_SimpleMessage');
        $message2 = $this->getMockery('Swift_Mime_SimpleMessage');
        $t1 = $this->getMockery('Swift_Transport');
        $t2 = $this->getMockery('Swift_Transport');
        $connectionState1 = false;
        $connectionState2 = false;

        $t1->shouldReceive('isStarted')
           ->zeroOrMoreTimes()
           ->andReturnUsing(function () use (&$connectionState1) {
               return $connectionState1;
           });
        $t1->shouldReceive('start')
           ->twice()
           ->andReturnUsing(function () use (&$connectionState1) {
               if (!$connectionState1) {
                   $connectionState1 = true;
               }
           });
        $t1->shouldReceive('send')
           ->once()
           ->with($message1, \Mockery::any())
           ->andReturnUsing(function () use (&$connectionState1, $e) {
               if ($connectionState1) {
                   $connectionState1 = false;
                   throw $e;
               }
           });
        $t1->shouldReceive('send')
           ->once()
           ->with($message2, \Mockery::any())
           ->andReturnUsing(function () use (&$connectionState1) {
               if ($connectionState1) {
                   return 10;
               }
           });

        $t2->shouldReceive('isStarted')
           ->zeroOrMoreTimes()
           ->andReturnUsing(function () use (&$connectionState2) {
               return $connectionState2;
           });
        $t2->shouldReceive('start')
           ->once()
           ->andReturnUsing(function () use (&$connectionState2) {
               if (!$connectionState2) {
                   $connectionState2 = true;
               }
           });
        $t2->shouldReceive('send')
           ->once()
           ->with($message1, \Mockery::any())
           ->andReturnUsing(function () use (&$connectionState2, $e) {
               if ($connectionState2) {
                   throw $e;
               }
           });
        $t2->shouldReceive('send')
           ->never()
           ->with($message2, \Mockery::any());

        $transport = $this->getTransport([$t1, $t2]);
        $transport->start();
        $this->assertTrue($transport->isStarted());
        try {
            $transport->send($message1);
            $this->fail('All transports failed so Exception should be thrown');
        } catch (Exception $e) {
            $this->assertFalse($transport->isStarted());
        }
        //Restart and re-try
        $transport->start();
        $this->assertTrue($transport->isStarted());
        $this->assertEquals(10, $transport->send($message2));
    }

    public function testFailureReferenceIsPassedToDelegates()
    {
        $failures = [];
        $testCase = $this;

        $message = $this->getMockery('Swift_Mime_SimpleMessage');
        $t1 = $this->getMockery('Swift_Transport');
        $connectionState = false;

        $t1->shouldReceive('isStarted')
           ->zeroOrMoreTimes()
           ->andReturnUsing(function () use (&$connectionState) {
               return $connectionState;
           });
        $t1->shouldReceive('start')
           ->once()
           ->andReturnUsing(function () use (&$connectionState) {
               if (!$connectionState) {
                   $connectionState = true;
               }
           });
        $t1->shouldReceive('send')
           ->once()
           ->with($message, \Mockery::on(function (&$var) use (&$failures, $testCase) {
               return $testCase->varsAreReferences($var, $failures);
           }))
           ->andReturnUsing(function () use (&$connectionState) {
               if ($connectionState) {
                   return 1;
               }
           });

        $transport = $this->getTransport([$t1]);
        $transport->start();
        $transport->send($message, $failures);
    }

    public function testRegisterPluginDelegatesToLoadedTransports()
    {
        $plugin = $this->createPlugin();

        $t1 = $this->getMockery('Swift_Transport');
        $t2 = $this->getMockery('Swift_Transport');

        $t1->shouldReceive('registerPlugin')
           ->once()
           ->with($plugin);
        $t2->shouldReceive('registerPlugin')
           ->once()
           ->with($plugin);

        $transport = $this->getTransport([$t1, $t2]);
        $transport->registerPlugin($plugin);
    }

    public function testEachDelegateIsPinged()
    {
        $t1 = $this->getMockery('Swift_Transport');
        $t2 = $this->getMockery('Swift_Transport');

        $testCase = $this;
        $t1->shouldReceive('isStarted')
           ->zeroOrMoreTimes()
           ->andReturnUsing(function () use (&$connectionState1) {
               return $connectionState1;
           });
        $t1->shouldReceive('ping')
           ->once()
           ->andReturn(true);

        $t2->shouldReceive('isStarted')
           ->zeroOrMoreTimes()
           ->andReturnUsing(function () use (&$connectionState2) {
               return $connectionState2;
           });
        $t2->shouldReceive('ping')
           ->once()
           ->andReturn(true);

        $transport = $this->getTransport([$t1, $t2]);
        $this->assertTrue($transport->isStarted());
        $this->assertTrue($transport->ping());
    }

    public function testDelegateIsKilledWhenPingFails()
    {
        $t1 = $this->getMockery('Swift_Transport');
        $t2 = $this->getMockery('Swift_Transport');

        $testCase = $this;
        $t1->shouldReceive('isStarted')
           ->zeroOrMoreTimes()
           ->andReturnUsing(function () use (&$connectionState1) {
               return $connectionState1;
           });
        $t1->shouldReceive('ping')
           ->twice()
           ->andReturn(true);

        $t2->shouldReceive('isStarted')
           ->zeroOrMoreTimes()
           ->andReturnUsing(function () use (&$connectionState2) {
               return $connectionState2;
           });
        $t2->shouldReceive('ping')
           ->once()
           ->andReturn(false);

        $transport = $this->getTransport([$t1, $t2]);
        $this->assertTrue($transport->ping());
        $this->assertTrue($transport->ping());
        $this->assertTrue($transport->isStarted());
    }

    public function testTransportShowsAsNotStartedIfAllPingFails()
    {
        $t1 = $this->getMockery('Swift_Transport');
        $t2 = $this->getMockery('Swift_Transport');

        $testCase = $this;
        $t1->shouldReceive('isStarted')
           ->zeroOrMoreTimes()
           ->andReturnUsing(function () use (&$connectionState1) {
               return $connectionState1;
           });
        $t1->shouldReceive('ping')
           ->once()
           ->andReturn(false);

        $t2->shouldReceive('isStarted')
           ->zeroOrMoreTimes()
           ->andReturnUsing(function () use (&$connectionState2) {
               return $connectionState2;
           });
        $t2->shouldReceive('ping')
           ->once()
           ->andReturn(false);

        $transport = $this->getTransport([$t1, $t2]);
        $this->assertFalse($transport->ping());
        $this->assertFalse($transport->isStarted());
        $this->assertFalse($transport->ping());
    }

    /**
     * Adapted from Yay_Matchers_ReferenceMatcher.
     */
    public function varsAreReferences(&$ref1, &$ref2)
    {
        if (\is_object($ref2)) {
            return $ref1 === $ref2;
        }
        if ($ref1 !== $ref2) {
            return false;
        }

        $copy = $ref2;
        $randomString = uniqid('yay', true);
        $ref2 = $randomString;
        $isRef = ($ref1 === $ref2);
        $ref2 = $copy;

        return $isRef;
    }

    private function getTransport(array $transports)
    {
        $transport = new Swift_Transport_LoadBalancedTransport();
        $transport->setTransports($transports);

        return $transport;
    }

    private function createPlugin()
    {
        return $this->getMockery('Swift_Events_EventListener');
    }
}


================================================
FILE: tests/unit/Swift/Transport/SendmailTransportTest.php
================================================
<?php

class Swift_Transport_SendmailTransportTest extends Swift_Transport_AbstractSmtpEventSupportTest
{
    protected function getTransport($buf, $dispatcher = null, $addressEncoder = null, $command = '/usr/sbin/sendmail -bs')
    {
        if (!$dispatcher) {
            $dispatcher = $this->createEventDispatcher();
        }
        $transport = new Swift_Transport_SendmailTransport($buf, $dispatcher, 'example.org', $addressEncoder);
        $transport->setCommand($command);

        return $transport;
    }

    protected function getSendmail($buf, $dispatcher = null)
    {
        if (!$dispatcher) {
            $dispatcher = $this->createEventDispatcher();
        }

        return new Swift_Transport_SendmailTransport($buf, $dispatcher);
    }

    public function testCommandCanBeSetAndFetched()
    {
        $buf = $this->getBuffer();
        $sendmail = $this->getSendmail($buf);

        $sendmail->setCommand('/usr/sbin/sendmail -bs');
        $this->assertEquals('/usr/sbin/sendmail -bs', $sendmail->getCommand());
        $sendmail->setCommand('/usr/sbin/sendmail -oi -t');
        $this->assertEquals('/usr/sbin/sendmail -oi -t', $sendmail->getCommand());
    }

    public function testSendingMessageIn_t_ModeUsesSimplePipe()
    {
        $buf = $this->getBuffer();
        $sendmail = $this->getSendmail($buf);
        $message = $this->createMessage();

        $message->shouldReceive('getTo')
                ->zeroOrMoreTimes()
                ->andReturn(['foo@bar' => 'Foobar', 'zip@button' => 'Zippy']);
        $message->shouldReceive('toByteStream')
                ->once()
                ->with($buf);
        $buf->shouldReceive('initialize')
            ->once();
        $buf->shouldReceive('terminate')
            ->once();
        $buf->shouldReceive('setWriteTranslations')
            ->once()
            ->with(["\r\n" => "\n", "\n." => "\n.."]);
        $buf->shouldReceive('setWriteTranslations')
            ->once()
            ->with([]);

        $sendmail->setCommand('/usr/sbin/sendmail -t');
        $this->assertEquals(2, $sendmail->send($message));
    }

    public function testSendingIn_t_ModeWith_i_FlagDoesntEscapeDot()
    {
        $buf = $this->getBuffer();
        $sendmail = $this->getSendmail($buf);
        $message = $this->createMessage();

        $message->shouldReceive('getTo')
                ->zeroOrMoreTimes()
                ->andReturn(['foo@bar' => 'Foobar', 'zip@button' => 'Zippy']);
        $message->shouldReceive('toByteStream')
                ->once()
                ->with($buf);
        $buf->shouldReceive('initialize')
            ->once();
        $buf->shouldReceive('terminate')
            ->once();
        $buf->shouldReceive('setWriteTranslations')
            ->once()
            ->with(["\r\n" => "\n"]);
        $buf->shouldReceive('setWriteTranslations')
            ->once()
            ->with([]);

        $sendmail->setCommand('/usr/sbin/sendmail -i -t');
        $this->assertEquals(2, $sendmail->send($message));
    }

    public function testSendingInTModeWith_oi_FlagDoesntEscapeDot()
    {
        $buf = $this->getBuffer();
        $sendmail = $this->getSendmail($buf);
        $message = $this->createMessage();

        $message->shouldReceive('getTo')
                ->zeroOrMoreTimes()
                ->andReturn(['foo@bar' => 'Foobar', 'zip@button' => 'Zippy']);
        $message->shouldReceive('toByteStream')
                ->once()
                ->with($buf);
        $buf->shouldReceive('initialize')
            ->once();
        $buf->shouldReceive('terminate')
            ->once();
        $buf->shouldReceive('setWriteTranslations')
            ->once()
            ->with(["\r\n" => "\n"]);
        $buf->shouldReceive('setWriteTranslations')
            ->once()
            ->with([]);

        $sendmail->setCommand('/usr/sbin/sendmail -oi -t');
        $this->assertEquals(2, $sendmail->send($message));
    }

    public function testSendingMessageRegeneratesId()
    {
        $buf = $this->getBuffer();
        $sendmail = $this->getSendmail($buf);
        $message = $this->createMessage();

        $message->shouldReceive('getTo')
                ->zeroOrMoreTimes()
                ->andReturn(['foo@bar' => 'Foobar', 'zip@button' => 'Zippy']);
        $message->shouldReceive('generateId');
        $buf->shouldReceive('initialize')
            ->once();
        $buf->shouldReceive('terminate')
            ->once();
        $buf->shouldReceive('setWriteTranslations')
            ->once()
            ->with(["\r\n" => "\n", "\n." => "\n.."]);
        $buf->shouldReceive('setWriteTranslations')
            ->once()
            ->with([]);

        $sendmail->setCommand('/usr/sbin/sendmail -t');
        $this->assertEquals(2, $sendmail->send($message));
    }

    public function testFluidInterface()
    {
        $buf = $this->getBuffer();
        $sendmail = $this->getTransport($buf);

        $ref = $sendmail->setCommand('/foo');
        $this->assertEquals($ref, $sendmail);
    }
}


================================================
FILE: tests/unit/Swift/Transport/StreamBufferTest.php
================================================
<?php

class Swift_Transport_StreamBufferTest extends \PHPUnit\Framework\TestCase
{
    public function testSettingWriteTranslationsCreatesFilters()
    {
        $factory = $this->createFactory();
        $factory->expects($this->once())
                ->method('createFilter')
                ->with('a', 'b')
                ->willReturnCallback([$this, 'createFilter']);

        $buffer = $this->createBuffer($factory);
        $buffer->setWriteTranslations(['a' => 'b']);
    }

    public function testOverridingTranslationsOnlyAddsNeededFilters()
    {
        $factory = $this->createFactory();
        $factory->expects($this->exactly(2))
                ->method('createFilter')
                ->willReturnCallback([$this, 'createFilter']);

        $buffer = $this->createBuffer($factory);
        $buffer->setWriteTranslations(['a' => 'b']);
        $buffer->setWriteTranslations(['x' => 'y', 'a' => 'b']);
    }

    private function createBuffer($replacementFactory)
    {
        return new Swift_Transport_StreamBuffer($replacementFactory);
    }

    private function createFactory()
    {
        return $this->getMockBuilder('Swift_ReplacementFilterFactory')->getMock();
    }

    public function createFilter()
    {
        return $this->getMockBuilder('Swift_StreamFilter')->getMock();
    }
}