You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@james.apache.org by bt...@apache.org on 2021/09/15 02:25:20 UTC
[james-project] branch master updated: JAMES-3644 Better document
outgoing email setup (#651)
This is an automated email from the ASF dual-hosted git repository.
btellier pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/james-project.git
The following commit(s) were added to refs/heads/master by this push:
new a2dce7c JAMES-3644 Better document outgoing email setup (#651)
a2dce7c is described below
commit a2dce7c3bd3c88674ae9cd44aefd18e361e525cb
Author: Duc Nguyen <59...@users.noreply.github.com>
AuthorDate: Wed Sep 15 09:24:52 2021 +0700
JAMES-3644 Better document outgoing email setup (#651)
---
src/homepage/howTo/dkim.html | 174 ++++++++++++++++++++++++++++++++++++
src/homepage/howTo/imap-server.html | 33 ++++++-
src/homepage/howTo/index.html | 7 ++
src/homepage/howTo/spf.html | 8 +-
4 files changed, 217 insertions(+), 5 deletions(-)
diff --git a/src/homepage/howTo/dkim.html b/src/homepage/howTo/dkim.html
new file mode 100644
index 0000000..180cf56
--- /dev/null
+++ b/src/homepage/howTo/dkim.html
@@ -0,0 +1,174 @@
+---
+layout: howTo
+---
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+<!-- Main -->
+<div id="main">
+
+ <!-- Introduction -->
+ <section id="intro" class="main special">
+ <div class="">
+ <div class="content align-left">
+ <header class="major">
+ <h1><b>What is a DKIM Record?</b></h1>
+ </header>
+
+ <p>
+ DKIM (DomainKeys Identified Mail) is an email security standard designed to make sure messages aren’t altered in transit between the sending and recipient servers.
+ </p>
+
+ <p>
+ It uses public-key cryptography to sign email with a private key as it leaves a sending server.
+ Recipient servers then use a public key published to a domain’s DNS to verify the source of the message, and that the body of the message hasn’t changed during transit.
+ </p>
+
+ <p>
+ Once the signature is verified with the public key by the recipient server, the message passes the DKIM check and is considered authentic.
+ </p>
+
+ <p>
+ The process of setting up DKIM can be split into the following steps:
+ </p>
+
+ <ul>
+ <li>Choose a DKIM selector.</li>
+ <li>Generate a public-private key pair.</li>
+ <li>Publish the selector and public key by creating a DKIM TXT record.</li>
+ <li>Attach the token to each outgoing email.</li>
+ </ul>
+
+ <p>
+ Before we begin, you might wonder what is a DKIM selector?
+ </p>
+ <p>
+ In short, a selector is specified as an attribute for a DKIM signature and is recorded in the DKIM-Signature header field.
+ A selector can be anything you want, such as a word, number, or a string of letters and numbers.
+ </p>
+ <p>
+ For example, if you choose <code>james3</code> for your selector, the DKIM record name would become <code>james3._domainkey</code>
+ </p>
+
+
+ <header class="major">
+ <h1><b>Generate RSA Key Pair for DKIM</b></h1>
+ </header>
+
+ <p>
+ You can use tools such as <code>openssl</code> or <code>ssh-keygen</code> to generate RSA keys.
+ </p>
+ <p>
+ Please note that 1024 bit DKIM is still the standard. If you want to feel safer with 2048-bit RSA, check with your DNS provider and see what length of DKIM key is supported because they need to match.
+ </p>
+ <p>Generate a 1024 bit RSA Key:</p>
+ <code>$ openssl genrsa -out private.pem 1024</code>
+
+ <p>Export the RSA Public Key to a file:</p>
+ <code>$ openssl rsa -in private.pem -outform PEM -pubout -out public.pem</code>
+ <p>Both generated files are base64-encoded encryption keys in plain text format:</p>
+
+ <pre><code>-----BEGIN RSA PRIVATE KEY-----
+MIICXQIBAAKBgQCxMwUfjQbppE2EK4T2IDuiLRvZ4opSwJwxani/5Ii5VbqMQRfo
+edUMuczK5qKJuIupTnh9AhJfaAsGUSruCVlGYXq6bqfak3XGHGu4s0rAXRM6Y3us
+gy8RyxfWQqtYbEZPIwkLGPbPeIh2t8s3mL9fD9+tpO5H1Kc+9MBTMm7qnQIDAQAB
+AoGATyl52nSIaAyMzMUca1BPE86PKLG6FeoSXUkxlJimNBYGdu4Fnkf/U+YVhXev
+mVMmoYZ68W3hg1nZwwKz6Q+oH7iBk+AJRQlDQmdNuqBS5epKQpIk77w6J+Nd2HCa
+wLXnt5wtDcusIV+HvznKi/yEt+oq29BbyY2CjAUYtR57wEECQQDhs71D4M8su6hv
+bBbif1V/4m62ChkSZRnD7T2rCxzqLoe3Qe6W9hwysDjYMAtq3pA7mjMYyTqrx8sJ
+RWcVSaf5AkEAyPx63vEKS38QPYyiesuJqqrnTeVlnPInedEmJmI6Rz5cWISosvNz
+/QjHzTqOT1fXfskbhutg1/mDarsHnH/oxQJBAJjH/cdUB4nlYehCx978iRjvYzgQ
+79XW4DETiBofhKw1YSM5G1PPN1lMlr4pD6GBFStzf0E4/mFH9nXJKDVtzakCQQCG
+OQ75ijHc31uCL0RnCzzB7GaSf+tPV+yDDukSYzEWWRAk0Vs0Px+r0UxVw5A8bqZs
+dnPas6C2O1zHT2Yy3r0dAkBECZDJaFhADFPSex8UrUrIidJaz8NLdyDiuwXKjc/c
+AmlLQXKntU4M5EIE6jz0Gf1ivw06pvTDOCDWlDxJRvf8
+-----END RSA PRIVATE KEY-----</code></pre>
+ <pre><code>
+-----BEGIN PUBLIC KEY-----
+MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCxMwUfjQbppE2EK4T2IDuiLRvZ
+4opSwJwxani/5Ii5VbqMQRfoedUMuczK5qKJuIupTnh9AhJfaAsGUSruCVlGYXq6
+bqfak3XGHGu4s0rAXRM6Y3usgy8RyxfWQqtYbEZPIwkLGPbPeIh2t8s3mL9fD9+t
+pO5H1Kc+9MBTMm7qnQIDAQAB
+-----END PUBLIC KEY-----
+ </code></pre>
+
+ <p>Beside above steps, online tools such as <a href="https://www.sparkpost.com/resources/tools/dkim-wizard/">DKIM Wizard</a> can help you easily create a public and private key pair to be used for DomainKeys and DKIM signing. </p>
+
+
+ <header class="major">
+ <h1><b>Create DKIM TXT record</b></h1>
+ </header>
+ <p>Log in your Domain Control Panel and create a TXT Record:</p>
+
+ <pre><code>Record Type: TXT Record
+Host Name: james3._domainkey
+Text: v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNAD[...Your Public Key...]
+</code></pre>
+
+<h1><b>Configure DKIMSign mailet</b></h1>
+
+<p>Lastly, you need to add a maillet to the <code>mailetcontainer.xml</code> in the /conf file of Apache James.</p>
+
+
+
+<pre><code>[...]
+<processors>
+ <processor state="relay" enableJmx="true">
+ <mailet match="All" class="org.apache.james.jdkim.mailets.DKIMSign">
+ <signatureTemplate>v=1; s=james3; d=domain.example.com ; h=from : reply-to : subject : date : to : cc : resent-date : resent-from : resent-sender : resent-to : resent-cc : in-reply-to : references : list-id : list-help : list-unsubscribe : list-subscribe : list-post : list-owner : list-archive; a=rsa-sha256; bh=; b=;</signatureTemplate>
+ <privateKey>
+ -----BEGIN RSA PRIVATE KEY-----
+ [Your Private Key]
+ -----END RSA PRIVATE KEY-----
+ </privateKey>
+ <mailet>
+ </processor>
+</processor>
+[...]</code></pre>
+
+<h1><b>Verifying DKIM Record</b></h1>
+<p>To query the DKIM key, you will have to know the DKIM selector:</p>
+
+<pre><code>$ dig txt james3._domainkey.domain.example.com
+; <<>> DiG 9.16.1-Ubuntu <<>> txt james3._domainkey.domain.example.com
+;; global options: +cmd
+;; Got answer:
+;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 39673
+;; flags: qr rd ad; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 0
+;; WARNING: recursion requested but not available
+
+;; QUESTION SECTION:
+;james3._domainkey.domain.example.com IN TXT
+
+;; ANSWER SECTION:
+james3._domainkey.domain.example.com. 0 IN TXT "v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNAD[...Your Public Key...]"
+[...]</code></pre>
+</div>
+
+
+
+</div>
+<footer class="major">
+<ul class="actions align-center">
+ <li><a href="index.html" class="button">go back to other how-tos</a></li>
+</ul>
+</footer>
+</section>
+</div>
+
diff --git a/src/homepage/howTo/imap-server.html b/src/homepage/howTo/imap-server.html
index 16a0b9c..0f976fa 100644
--- a/src/homepage/howTo/imap-server.html
+++ b/src/homepage/howTo/imap-server.html
@@ -37,7 +37,7 @@ layout: howTo
</p>
<ul>
- <li>DNS creation and MX record</li>
+ <li>DNS resolution and essential DNS records for mail delivery</li>
<li>Server components description</li>
<li>Generation of a custom keystore</li>
<li>Starting James</li>
@@ -54,6 +54,15 @@ layout: howTo
</header>
<p>
+ For a public facing mail server to send and receive mail properly,
+ it is necessary to configure your public DNS records so that other mailservers can find and send mail to your users,
+ and for other mailservers to trust and receive your mail.
+ </p>
+ <header class="major">
+ <h2><b>MX Record</b></h2>
+ </header>
+
+ <p>
Someone willing to send you an email will first have to discover which IP your mail server has.
The way this is achieved is through MX (means Mail eXchange) DNS record.
</p>
@@ -69,8 +78,28 @@ layout: howTo
<li>...and can establish a connection to <code>mx.company.com</code> to send an email to Alice</li>
</ol>
- <p>All is needed is a MX entry in domain name resolution pointing to the future IP of your James server.</p>
+ <p>All you need is to create a MX Record in your Domain Control Panel and point it to the IP of your James server.</p>
+
+ <header class="major">
+ <h2><b>PTR Record</b></h2>
+ </header>
+
+ <p>
+ So you want to send an email to friends in another domain.
+ Their mailserver will not trust mail coming from your server unless they can do a reverse DNS lookup.
+ </p>
+
+ <p>That is what PTR Record do - A reverse lookup which maps the mailserver IP address to domain name.</p>
+ <p>PTR Record can only be created by your ISP - So don't hesitate to ask them to create it for you.</p>
+
+ <p>
+ For Security and Spam Protection, please check our other documents <a href="spf.html">SPF Record</a> and <a href="dkim.html">DKIM Record</a>.
+ </p>
+ <p>
+ For testing and checking vulnerabilities, send an email to <a href="https://www.mail-tester.com/">mail-tester</a>.
+ It's a free tool that analyze your message, mail server, sending IP... and show you a detailed report of what's configured properly and what's not.
+ </p>
<header class="major">
<h2><b>JAMES architecture</b></h2>
</header>
diff --git a/src/homepage/howTo/index.html b/src/homepage/howTo/index.html
index e45d1a5..928791b 100644
--- a/src/homepage/howTo/index.html
+++ b/src/homepage/howTo/index.html
@@ -47,6 +47,13 @@ layout: howTo
class="james-schema" >
<span class="fa fa-sitemap"></span>Configuring SPF <span class="fa fa-long-arrow-right"></span>
</a>
+ <a href="dkim.html"
+ data-lightbox="james-schema"
+ data-title="Configuring DKIM"
+ alt="Configuring DKIM"
+ class="james-schema" >
+ <span class="fa fa-sitemap"></span>Configuring DKIM <span class="fa fa-long-arrow-right"></span>
+ </a>
<a href="deleted-messages-vault.html"
data-lightbox="james-schema"
data-title="Deleted Messages Vault"
diff --git a/src/homepage/howTo/spf.html b/src/homepage/howTo/spf.html
index ab2fa74..26c96f8 100644
--- a/src/homepage/howTo/spf.html
+++ b/src/homepage/howTo/spf.html
@@ -150,15 +150,17 @@ layout: howTo
</processor>
[...]</code></pre>
-
+<p>
+ Finished configuring SPF ? Go check our guide for <a href="dkim.html">configuring DKIM Record</a>.
+</p>
</div>
<footer class="major">
<ul class="actions align-center">
- <li><a href="index.html" class="button">go back to other how-tos</a></li>
+ <li><a href="index.html" class="button">go back to other how-adasdasdetos</a></li>
</ul>
</footer>
</div>
- </section>
+
</div>
---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@james.apache.org
For additional commands, e-mail: notifications-help@james.apache.org