OpenDKIM/INSTALL at br-2-0 · newdominic/OpenDKIM

Repository navigation

History

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

256

257

258

259

260

261

262

263

264

265

266

267

268

269

270

271

272

273

274

275

276

277

278

279

280

281

282

283

284

285

286

287

288

289

290

291

292

293

294

295

296

297

298

299

300

301

302

303

304

305

306

307

308

309

310

311

312

313

314

315

316

317

318

319

320

321

322

323

324

325

326

327

328

329

330

331

332

333

334

335

336

337

338

339

340

341

342

343

344

345

346

347

348

349

350

351

352

353

354

355

356

357

358

359

360

361

362

363

364

365

366

367

368

369

370

371

372

373

374

375

376

377

378

379

380

381

382

383

384

385

386

387

388

389

390

INSTALLING OPENDKIM

OVERVIEW

========

In order to install the opendkim as a milter plugin to an MTA you will

need to perform the following steps:

* Compile the opendkim program itself.

* Configure the DKIM subsystem for signing and verification.

* Install the milter and configure your MTA to use it.

Note that there is a difference between "OpenDKIM" and "opendkim".

"OpenDKIM" is a package containing a library, a filter and some tools to

be used in testing your DKIM installation. "opendkim" is the filter

program contained in the "OpenDKIM" package.

libopendkim is a library available as an API for programmers everywhere. That

API is described in a set of HTML files in the OpenDKIM source code

package.

opendkim is a plugin that incorporates the libopendkim library and works

with recent versions of sendmail and Postfix or any other MTA that supports

"milter". For more information about milter, see <http://www.milter.org>.

Sendmail is available at <http://www.sendmail.org> and Postfix is available

at <http://www.postfix.org>.

OPTIONAL PACKAGES

=================

OpenDKIM supports a few optional packages that can be included in the build

to provide additional services. A few of these become mandatory when

enabling certain features above. Specifying only the "--with-xxx" parameter

to the "configure" command (described below) enables the package and makes a

guess at where it might be installed on your system. If the configure script

doesn't find it, you will need to specify the location with

"--with-xxx=location".

--with-db BerkeleyDB include file and library. If enabled without

a specific path, the /usr/local/BerkeleyDB, /usr/local and

/usr directories will be searched for both the required

includes and the required libraries. Required for the

following features: bodylengthdb, query_cache, stats

--with-domainkeys

Sendmail's "libdk" include file and library for verifying

messages signed with the older DomainKeys specification.

--with-lua Lua interpreter library. Enables fine-grained policy control

via Lua script hooks, and also enables building of the

"miltertest" test tool.

--with-milter Sendmail's "milter" include file and library. Required

unless compilation fo the filter is disabled (see below).

Enabled by default.

--with-odbx Location of the OpenDBX installation on your system.

Optional; enables use of a number of SQL and ODBC databases

for configuration information. Version 1.3.7 or later is

required.

--with-openldap Location of the OpenLDAP installation on your system.

--with-openssl Location of the OpenSSL installation on your system.

This is required. If no specific location is provided,

the /usr/local and /usr directories will be searched for

the required includes and libraries.

--with-tre Location of the TRE installation on your system. This

is required if you are using the "diffheaders" feature.

If no specific location is provided, the /usr/local and

/usr directories will be searched for the required includes

and libraries.

--with-unbound The "unbound" asynchronous resolver library and include file.

FEATURES

========

There are several compile-time features you may select. Some of these

are present but unsupported while others are fully-supported. Read the

FEATURES file for a description of the unsupported features.

The supported features are as follows. The can be turned on at compile

time by adding "--enable-xxx" to the "configure" command line (described

below), where "xxx" is the name of the feature.

arlib Use the provided asynchronous resolver library.

debug Produce debug-enabled libraries and executables.

filter Compile the opendkim filter. Requires libmilter (see

"--with-milter" above). This is on by default; if you

don't want the filter, specify "--disable-filter".

popauth Enable POP-before-SMTP support.

query_cache Cache DNS replies in a local database. Requires the

BerkeleyDB database. (See "--with-db" above.)

COMPILING

=========

The opendkim plugin requires either sendmail v8.13.0 or Postfix v2.3 or later

for required milter protocol enhancements.

To build this package you must first have installed or at least have available

the OpenSSL package and libmilter. The former is available from

<http://www.openssl.org> or in package form from your vendor. At a minimum

version 0.9.8 is required to meet DKIM requirements. The application library

libmilter is part of the sendmail Open Source distribution and can be built

and installed from there (ftp://ftp.sendmail.org).

As Postfix currently does not provide milter library, you need to have

sendmail sources or development package installed. See

http://www.postfix.org/MILTER_README.html

You can view the configuration options with the following command:

./configure -help

The commands shown below assume a UNIX system with standard build tools

installed.

Steps to compiling the library and the milter:

(1) Download the source from OpenDKIM (http://www.opendkim.org).

(2) Unpack the tarball:

% tar -xzvf opendkim-$ver.tar.gz

Be sure you set $ver to the version number that you downloaded.

(3) Change directories to the release directory (opendkim-<version>) that

was created in step 2.

% cd opendkim-$ver

(4) Run the "configure" script to configure the package for your operating

system.

% ./configure

(5) Compile the package.

% make

(6) Install the output of the build. You probably need to become the

superuser to run this step.

% make install

INSTALLING AND CONFIGURING OPENDKIM

===================================

(1) Choose a selector name. Current convention is to use a code for the

current month and year, or just the year. However, you are free to

choose any name you wish, especially if you have a selector assignment

scheme in mind.

(2) Create a public/private keypair for signing:

(a) Run the script "opendkim-genkey". (A manual page for this tool is

available and will be installed by the above process if you want to

see the available options.)

This will generate a private key in PEM format and a TXT record

appropriate for insertion into your DNS zone file. Insert the contents

of the TXT record file into your DNS zone file, increment the

serial number, and reload your DNS server so that the new record

is published. This is by far the easiest approach.

(b) If for some reason you cannot use the "opendkim-genkey" script, manually

generate a public and private key. The steps below are exactly what

is performed by the opendkim-genkey script.

(i) Run this command:

% openssl genrsa -out rsa.private 1024

This generates a private key and writes it to the file "rsa.private".

The generated key is in PEM format and is a 1024-bit key, the

minimum required by the DKIM specification.

(ii) Run this command:

% openssl rsa -in rsa.private -out rsa.public -pubout -outform PEM

This reads the private key generated in the previous step and

extracts from it the matching public key. This is written to the

file "rsa.public".

(iii) Add a TXT DNS record containing the base64 encoding of your public

key, which is everything between the BEGIN and END lines in the

rsa.public file generated above, with spaces and newlines removed.

It should be in this form:

"g=*; k=rsa; t=y; p=MFwwDQYJ...AwEAAQ=="

...using, of course, your own public key's base64 data. The name of

the TXT record should be SELECTOR._domainkey.example.com (where

"SELECTOR" is the name you chose and "example.com" is your domain

name). Reload your nameserver so that the record gets published.

If you are running BIND 9 the command is "rndc reload"; for other

nameservers, consult your vendor documentation.

If you are using a large key, you may need to format this record

in a special way in order for it to be used by your nameserver.

See the LARGE KEYS section below.

For a translation of the parameter and value pairs shown here, see

the DKIM specification (RFC4871) section 3.6. The specification

is available in a file in the source code package called

"rfc4871.txt". Basically this key record just announces an RSA

public key and also declares that your site is using this key in

test mode so nobody should take any real action based on success

or failure of the use of this key to verify a message.

(3) Store the private key in a safe place. We generally use a path like

/var/db/dkim/SELECTOR.key.pem (where "SELECTOR" is the name you chose).

The /var/db/dkim directory and the associated .pem file should be owned by

the user that will be executing the filter (preferably not the

superuser) and be mode 0700 and 0600 respectively.

(4) By default, mail will only be signed if it comes from localhost.

If you wish to sign mail that comes from sources other than the localhost

address (127.0.0.1), create a file that contains IP addresses, CIDR

addresses (e.g. 192.168.0.0/24), hostnames, or domain names preceded by

a "." character, one per line.

(5) Start opendkim. You will need at least the "-p" option. (A manual

page for this tool is available and will be installed by the above

process if you want to see the available options.) The current

recommended basic set of command line options is:

-l -p SOCKETSPEC -d DOMAIN -k KEYPATH -s SELECTOR

...where SOCKETSPEC is the socket you want the MTA to use (see below),

DOMAIN is the domain or set of domains for which you want to sign

mail, KEYPATH is the path to the private key file you generated, and

SELECTOR is the selector name you picked. You can tack "-f" on there

if you want it to run in the foreground instead of in the background

as a daemon.

The SOCKETSPEC is a socket where the MTA will attempt to connect

to your filter. The filter must therefore be listening there for

connections from MTAs in order to process messages. See the

documentation in libmilter (available with the open source sendmail

source code) for details on selecting and specifying a socket.

If you created a list of sources in step (4) above, add "-i FILENAME"

to the command line, replacing FILENAME with the file you created there.

Instead of command line options, you can also use a configuration file.

In that case, you only need to tell the filter where the configuration

file is by specifying a command line option of:

-x CONFPATH

...where CONFPATH is the path to the configuration file you wish to

use. A template configuration file can be found in the "opendkim"

directory, named "opendkim.conf.sample".

CONFIGURING AND RESTARTING SENDMAIL

===================================

(1) Configure sendmail to use the new milter:

(a) Choose a socket at which the MTA and the filter will rendezvous

(see the documentation in libmilter for details).

(b) Add a line like this example to your sendmail.mc using your desired

socket specification:

INPUT_MAIL_FILTER(`opendkim', `S=inet:8891@localhost')

(2) Restart sendmail.

% kill -1 `head -1 /var/run/sendmail.pid`

CONFIGURING POSTFIX

(1) Configure postfix to use the new milter:

(a) Choose a socket at which the MTA and the filter will rendezvous

(see the documentation in libmilter for details).

(b) Add a line like this example to your postfix main.cf using your desired

socket specification:

smtpd_milters = inet:localhost:8891

(2) Restart Postfix.

LARGE KEYS

==========

If you wish to use a large key in DNS, there are some limitations of which

you should be aware. A TXT record in the DNS consists of a series of

strings each of which don't exceed 255 bytes. This is a result of the

fact that each string is preceded by a length byte (which, of course,

can't exceed 255). Furthermore, some DNS implementations don't allow

packets larger than 512 bytes. Some RSA keys will exceed the 255 byte

limit once encoded with base64, so some special formatting must be

used to make such a record fit. Failing to do so can cause an incomplete

record to be published or, worse, the nameserver to refuse to serve the

record or even the entire zone.

In the case of the BIND nameserver, there are two syntax rules one can use

to make a large record fit within these boundaries:

1) TXT substrings

Instead of a record like:

recname IN TXT "foobarbazblivitalphabravocharliedelta...zulu"

...one can also do:

recname IN TXT "foobar" "baz" "blivit" "alpha" ... "zulu"

(The "..." is mean to indicate continuation and is not a literal set of

three "." characters.)

You simply have to break up the large record into smaller strings such

that no string exceeds 255 bytes. DKIM implementations will

reassemble TXT records broken down this way into the full original

single string before processing them.

2) Line continuations

It can be difficult for some to edit very long lines of text.

It's therefore desirable to have a mechanism to break very long

TXT records down so that they fit nicely within an editor window.

In BIND, this is done by enclosing the wrapped lines within

parentheses. Continuing with the example above, this:

recname IN TXT "foobar" "baz" "blivit" "alpha" ... "zulu"

...can also be expressed as:

recname IN TXT ( "foobar" "baz" "blivit" "alpha"

"bravo" "charlie" "delta" "echo"

...

"yankee" "zulu" )

So using these two techniques, a very large public key could be encoded

in a DNS zone file as follows:

recname IN TXT ( "v=DKIM1; g=*; k=rsa; "

"p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA1Z4F"

"JEMHjJDuBmt25zvYFVejlARZGt1L8f0s1+rLxIPYkfCogQi+Y8"

"oLEg9vvEKnLx9aogZzuNt6j4Sty3LgXxaIwHnMqk0LldbA/mh3"

"wLZb16Wc6btXHON0o3uDipxqGK2iRLTvcgAnNDegseOS+i0aJE"

"nNSl663ywRBp/QKezhUC7cnbqR/H8dz8pEOjeawNN3nexdHGsk"

"+RaafYvCFvU+70CQORcsk+mxb74SwGT2CGHWxVywQA9yrV+sYk"

"JpxaufZLo6xp0Z7RZmbf1eGlCAdhkEy+KYQpQkw2Cdl7iKIK4+"

"17gr+XZOrfFLJ5IwpVK/a19m3BLxADf0Kh3oZwIDAQAB" )

TESTING

=======

To test, send a piece of e-mail through the MTA doing signing for your

domain to autorespond+dkim@dk.elandsys.com. It should be returned to you

shortly showing your message in the body of a new message, including all of

the header changes that were made in transit. The message you generated

should appear there with a DKIM-Signature: header added, containing

the signature data your opendkim added, and an Authentication-Results:

header which the testing machine's opendkim added after verifying the

signature. The value of this header should indicate a "pass". If it

isn't, something in between has altered your message in a way that

invalidated the signature. Perhaps you have other filters running which

appended or modified a header.

The reply from the test machine will also itself be signed, and in the

headers of the reply you should see its signature and another

Authentication-Results: header, which should also read "pass".

$Id: INSTALL,v 1.13.2.2 2010/05/06 19:37:40 cm-msk Exp $

FilesExpand file tree

INSTALL

Latest commit

History

INSTALL

File metadata and controls