mailauth 4.7.3 → 4.8.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/CHANGELOG.md +14 -0
  2. package/README.md +409 -324
  3. package/bin/mailauth.js +68 -72
  4. package/cli.md +278 -244
  5. package/man/mailauth.1 +1 -1
  6. package/package.json +9 -9
package/cli.md CHANGED
@@ -1,351 +1,355 @@
1
- ![](https://github.com/postalsys/mailauth/raw/master/assets/mailauth.png)
1
+ # mailauth CLI Usage
2
2
 
3
- Command line utility and a [Node.js library](README.md) for email authentication.
3
+ ![mailauth Logo](https://github.com/postalsys/mailauth/raw/master/assets/mailauth.png)
4
4
 
5
- # CLI USAGE
5
+ mailauth provides a command-line utility for email authentication, complementing its [Node.js library](README.md). This guide explains how to use the mailauth CLI to perform various email authentication tasks.
6
6
 
7
- ## TOC
7
+ ## Table of Contents
8
8
 
9
9
  - [Installation](#installation)
10
- - [Help](#help)
11
- - [Available commands](#available-commands)
12
- - [report](#report) – to validate SPF, DKIM, DMARC, ARC
13
- - [sign](#sign) - to sign an email with DKIM
14
- - [seal](#seal) - to seal an email with ARC
15
- - [spf](#spf) - to validate SPF for an IP address and an email address
16
- - [vmc](#vmc) - to validate BIMI VMC logo files
17
- - [bodyhash](#bodyhash) - to generate the signature body hash value for an email
18
- - [license](#license) - display licenses for `mailauth` and included modules
19
- - [DNS cache file](#dns-cache-file)
10
+ - [Getting Help](#getting-help)
11
+ - [Available Commands](#available-commands)
12
+ - [`report`](#report) — Validate SPF, DKIM, DMARC, ARC, and BIMI
13
+ - [`sign`](#sign) — Sign an email with DKIM
14
+ - [`seal`](#seal) — Seal an email with ARC
15
+ - [`spf`](#spf) — Validate SPF for an IP address and email address
16
+ - [`vmc`](#vmc) — Validate BIMI VMC logo files
17
+ - [`bodyhash`](#bodyhash) — Generate the body hash value for an email
18
+ - [`license`](#license) — Display licenses for mailauth and included modules
19
+ - [DNS Cache File](#dns-cache-file)
20
+ - [License](#license)
20
21
 
21
22
  ## Installation
22
23
 
23
- Download `mailauth` for your platform:
24
+ Install the mailauth CLI by downloading the appropriate package for your platform or via npm:
24
25
 
25
- - MacOS
26
+ - **MacOS:**
26
27
  - [Intel processors](https://github.com/postalsys/mailauth/releases/latest/download/mailauth.pkg)
27
28
  - [Apple silicon](https://github.com/postalsys/mailauth/releases/latest/download/mailauth-arm.pkg)
28
- - [Linux](https://github.com/postalsys/mailauth/releases/latest/download/mailauth.tar.gz)
29
- - [Windows](https://github.com/postalsys/mailauth/releases/latest/download/mailauth.exe)
30
- - Or install from the NPM registry: `npm install -g mailauth`
29
+ - **Linux:**
30
+ - [Download mailauth.tar.gz](https://github.com/postalsys/mailauth/releases/latest/download/mailauth.tar.gz)
31
+ - **Windows:**
32
+ - [Download mailauth.exe](https://github.com/postalsys/mailauth/releases/latest/download/mailauth.exe)
33
+ - **NPM Registry:**
31
34
 
32
- ## Help
35
+ - Install globally using npm:
33
36
 
37
+ ```bash
38
+ npm install -g mailauth
39
+ ```
40
+
41
+ ## Getting Help
42
+
43
+ To display help information for the mailauth CLI or any specific command, use the `--help` flag:
44
+
45
+ ```bash
46
+ mailauth --help
47
+ mailauth report --help
48
+ mailauth sign --help
49
+ mailauth seal --help
50
+ mailauth spf --help
34
51
  ```
35
- $ mailauth --help
36
- $ mailauth report --help
37
- $ mailauth sign --help
38
- $ mailauth seal --help
39
- $ mailauth spf --help
40
- ```
41
52
 
42
- ## Available commands
53
+ ## Available Commands
54
+
55
+ The mailauth CLI offers several commands to perform different email authentication tasks:
56
+
57
+ 1. [`report`](#report) — Validate SPF, DKIM, DMARC, ARC, and BIMI.
58
+ 2. [`sign`](#sign) — Sign an email with DKIM.
59
+ 3. [`seal`](#seal) — Seal an email with ARC.
60
+ 4. [`spf`](#spf) — Validate SPF for an IP address and email address.
61
+ 5. [`vmc`](#vmc) — Validate BIMI VMC logo files.
62
+ 6. [`bodyhash`](#bodyhash) — Generate the body hash value for an email.
63
+ 7. [`license`](#license) — Display licenses for mailauth and included modules.
43
64
 
44
65
  ### report
45
66
 
46
- `report` command takes an email message and returns a JSON formatted report for SPF, DKIM, ARC, DMARC and BIMI. Not all reports might make sense for your use case, eg. SPF check for an outbound message usually gives no useful info, so you can ignore the parts you're not interested in.
67
+ The `report` command analyzes an email message and returns a JSON-formatted report detailing the results of SPF, DKIM, DMARC, ARC, and BIMI validations.
47
68
 
48
- ```
49
- $ mailauth report [options] [email]
69
+ #### Usage
70
+
71
+ ```bash
72
+ mailauth report [options] [email]
50
73
  ```
51
74
 
52
- Where
75
+ - **email**: (Optional) Path to the EML-formatted email message file. If omitted, the email is read from standard input.
53
76
 
54
- - **options** are option flags and arguments
55
- - **email** is the path to EML formatted email message file. If not provided then email message is read from standard input
77
+ #### Options
56
78
 
57
- **Options**
79
+ - `--client-ip x.x.x.x`, `-i x.x.x.x`: IP address of the remote client that sent the email. If not provided, it's parsed from the latest `Received` header.
80
+ - `--sender user@example.com`, `-f user@example.com`: Email address from the MAIL FROM command. If not provided, it's parsed from the latest `Return-Path` header.
81
+ - `--helo hostname`, `-e hostname`: Hostname from the HELO/EHLO command. Used in some SPF validations.
82
+ - `--mta hostname`, `-m hostname`: Hostname of the server performing validations. Defaults to the local hostname.
83
+ - `--dns-cache /path/to/dns.json`, `-n /path/to/dns.json`: Path to a DNS cache file. When provided, DNS queries use cached responses.
84
+ - `--verbose`, `-v`: Enables verbose output, displaying debugging information.
85
+ - `--max-lookups number`, `-x number`: Sets the maximum number of DNS lookups for SPF checks. Defaults to `10`.
86
+ - `--max-void-lookups number`, `-z number`: Sets the maximum number of void DNS lookups for SPF checks. Defaults to `2`.
58
87
 
59
- - `--client-ip x.x.x.x` or `-i x.x.x.x` is the IP of the remote client that sent the email. If not provided then it is parsed from the latest `Received` header
60
- - `--sender user@example.com` or `-f address` is the email address from the MAIL FROM command. If not provided then it is parsed from the latest Return-Path header
61
- - `--helo hostname` or `-e hostname` is the client hostname from the HELO/EHLO command. Used in some obscure SPF validation operations
62
- - `--mta hostname` or `-m hostname` is the server hostname doing the validation checks. Defaults to `os.hostname()`
63
- - `--dns-cache /path/to/dns.json` or `-n path` is the path to a file with cached DNS query responses. If this file is provided then no actual DNS requests are performed, only cached values from this file are used.
64
- - `--verbose` or `-v` if this flag is set then mailauth writes some debugging info to standard error
65
- - `--max-lookups nr` or `-x nr` defines the allowed DNS lookup limit for SPF checks. Defaults to 10.
66
- - `--max-void-lookups nr` or `-z nr` defines the allowed DNS lookup limit for SPF checks. Defaults to 2.
88
+ #### Example
67
89
 
68
- **Example**
90
+ ```bash
91
+ mailauth report --verbose --dns-cache examples/dns-cache.json test/fixtures/message2.eml
92
+ ```
93
+
94
+ **Sample Output:**
69
95
 
70
96
  ```
71
- $ mailauth report --verbose --dns-cache examples/dns-cache.json test/fixtures/message2.eml
72
97
  Reading email message from test/fixtures/message2.eml
73
98
  DNS query for TXT mail.projectpending.com: not found
74
99
  DNS query for TXT _dmarc.projectpending.com: not found
75
100
  {
76
101
  "receivedChain": [
77
- ...
102
+ "..."
103
+ ]
104
+ }
78
105
  ```
79
106
 
80
- See full example for DKIM checks [here](https://gist.github.com/andris9/8d4ab527282041f6725a640d80da4872).
107
+ For a detailed example of DKIM checks, refer to [this gist](https://gist.github.com/andris9/8d4ab527282041f6725a640d80da4872).
81
108
 
82
109
  ### sign
83
110
 
84
- `sign` command takes an email message and signs it with a DKIM digital signature.
111
+ The `sign` command signs an email message using a DKIM signature.
85
112
 
86
- ```
87
- $ mailauth sign [options] [email]
113
+ #### Usage
114
+
115
+ ```bash
116
+ mailauth sign [options] [email]
88
117
  ```
89
118
 
90
- Where
119
+ - **email**: (Optional) Path to the EML-formatted email message file. If omitted, the email is read from standard input.
91
120
 
92
- - **options** are option flags and arguments
93
- - **email** is the path to EML formatted email message file. If not provided then email message is read from standard input
121
+ #### Options
94
122
 
95
- **Options**
123
+ - `--private-key /path/to/private.key`, `-k /path/to/private.key`: Path to the private key used for signing.
124
+ - `--domain example.com`, `-d example.com`: Domain name for the DKIM signature (`d=` tag).
125
+ - `--selector selector`, `-s selector`: Selector for the DKIM key (`s=` tag).
126
+ - `--algo algorithm`, `-a algorithm`: Signing algorithm (e.g., `rsa-sha256`). Defaults based on the private key type.
127
+ - `--canonicalization method`, `-c method`: Canonicalization method (e.g., `relaxed/relaxed`). Defaults to `relaxed/relaxed`.
128
+ - `--time timestamp`, `-t timestamp`: Signing time as a Unix timestamp (`t=` tag).
129
+ - `--header-fields "field1:field2"`, `-h "field1:field2"`: Colon-separated list of header fields to include in the signature (`h=` tag).
130
+ - `--body-length length`, `-l length`: Maximum length of the body to include in the signature (`l=` tag).
131
+ - `--headers-only`, `-o`: Outputs only the DKIM signature headers without the entire message.
96
132
 
97
- - `--private-key /path` or `-k /path` is the path to a private key for signing
98
- - `--domain example.com` or `-d example.com` is the domain name for signing (d= tag)
99
- - `--selector xxx` or `-s xxx` is the key selector name for signing (s= tag)
100
- - `--algo rsa-sha256` or `-a rsa-sha256` is the signing algorithm. Defaults either to "rsa-sha256" or
101
- "ed25519-sha256" depending on the private key format (a= tag)
102
- - `--canonicalization algo` or `-c algo` is the canonicalization algorithm, defaults to "relaxed/relaxed" (c= tag)
103
- - `--time 12345` or `-t 12345` is the signing time as a unix timestamp (t= tag)
104
- - `--header-fields "message-id:date"` or `-h keys` is a colon separated list of header field names to sign (h= tag)
105
- - `--body-length 12345` or `-l 12345` is the maximum length of canonicalizated body to sign (l= tag)
106
- - `--headers-only` or `-o` If set return signing headers only. Default is to return the entire message.
133
+ #### Example
107
134
 
108
- **Example**
135
+ ```bash
136
+ mailauth sign /path/to/message.eml --domain example.com --selector s1 --private-key /path/to/private.key --verbose
137
+ ```
138
+
139
+ **Sample Output:**
109
140
 
110
141
  ```
111
- $ mailauth sign /path/message.eml --domain kreata.ee --selector test --privateKey /path/private-rsa.pem --verbose
112
- Reading email message from /path/message.eml
113
- Signing domain: kreata.ee
114
- Key selector: test
142
+ Reading email message from /path/to/message.eml
143
+ Signing domain: example.com
144
+ Key selector: s1
115
145
  Canonicalization algorithm: relaxed/relaxed
116
146
  Hashing algorithm: rsa-sha256
117
- Signing time: 2020-12-03T23:00:14.956Z
147
+ Signing time: 2023-03-15T12:00:00.000Z
118
148
  --------
119
- DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=kreata.ee;
120
- h=MIME-Version: Date: Message-ID: Subject: To: From: Content-Type;
149
+ DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=example.com;
150
+ h=MIME-Version:Date:Message-ID:Subject:To:From:Content-Type;
121
151
  ...
122
152
  ```
123
153
 
124
154
  ### seal
125
155
 
126
- `seal` command takes an email message and seals it with an ARC digital signature.
156
+ The `seal` command adds an ARC (Authenticated Received Chain) seal to an email message.
127
157
 
128
- ```
129
- $ mailauth seal [options] [email]
158
+ #### Usage
159
+
160
+ ```bash
161
+ mailauth seal [options] [email]
130
162
  ```
131
163
 
132
- Where
164
+ - **email**: (Optional) Path to the EML-formatted email message file. If omitted, the email is read from standard input.
133
165
 
134
- - **options** are option flags and arguments
135
- - **email** is the path to EML formatted email message file. If not provided then email message is read from standard input
166
+ #### Options
136
167
 
137
- **Options**
168
+ **Sealing Options:**
138
169
 
139
- As the emails needs to be authenticated before sealing then `seal` command expects in additon to sealing key information also the authentication options from the `report` command.
170
+ - `--private-key /path/to/private.key`, `-k /path/to/private.key`: Path to the private key used for sealing.
171
+ - `--domain example.com`, `-d example.com`: Domain name for the ARC seal (`d=` tag).
172
+ - `--selector selector`, `-s selector`: Selector for the ARC key (`s=` tag).
173
+ - `--algo algorithm`, `-a algorithm`: Sealing algorithm (e.g., `rsa-sha256`). Defaults based on the private key type.
174
+ - `--time timestamp`, `-t timestamp`: Sealing time as a Unix timestamp (`t=` tag).
175
+ - `--header-fields "field1:field2"`, `-h "field1:field2"`: Colon-separated list of header fields to include in the seal (`h=` tag).
176
+ - `--headers-only`, `-o`: Outputs only the ARC seal headers without the entire message.
140
177
 
141
- - `--private-key /path` or `-k /path` is the path to a private key for sealing
142
- - `--domain example.com` or `-d example.com` is the domain name for sealing (d= tag)
143
- - `--selector xxx` or `-s xxx` is the key selector name for sealing (s= tag)
144
- - `--algo rsa-sha256` or `-a rsa-sha256` is the sealing algorithm. Defaults either to "rsa-sha256" or
145
- "ed25519-sha256" depending on the private key format (a= tag)
146
- - `--time 12345` or `-t 12345` is the sealing time as a unix timestamp (t= tag)
147
- - `--header-fields "message-id:date"` or `-h keys` is a colon separated list of header field names to seal (h= tag)
148
- - `--client-ip x.x.x.x` or `-i x.x.x.x` is the IP of the remote client that sent the email. If not provided then it is parsed from the latest `Received` header
149
- - `--sender user@example.com` or `-f address` is the email address from the MAIL FROM command. If not provided then it is parsed from the latest Return-Path header
150
- - `--helo hostname` or `-e hostname` is the client hostname from the HELO/EHLO command. Used in some obscure SPF validation operations
151
- - `--mta hostname` or `-m hostname` is the server hostname doing the validation checks. Defaults to `os.hostname()`
152
- - `--dns-cache /path/to/dns.json` or `-n path` is the path to a file with cached DNS query responses. If this file is provided then no actual DNS requests are performed, only cached values from this file are used.
153
- - `--headers-only` or `-o` If set return signing headers only. Default is to return the entire message.
178
+ **Authentication Options (from `report` command):**
154
179
 
155
- > Canonicalization (c= tag) is always "relaxed/relaxed" when sealing, this can not be changed
180
+ - `--client-ip x.x.x.x`, `-i x.x.x.x`: IP address of the remote client that sent the email.
181
+ - `--sender user@example.com`, `-f user@example.com`: Email address from the MAIL FROM command.
182
+ - `--helo hostname`, `-e hostname`: Hostname from the HELO/EHLO command.
183
+ - `--mta hostname`, `-m hostname`: Hostname of the server performing validations.
184
+ - `--dns-cache /path/to/dns.json`, `-n /path/to/dns.json`: Path to a DNS cache file.
185
+ - `--verbose`, `-v`: Enables verbose output.
156
186
 
157
- **Example**
187
+ **Note:** The canonicalization method (`c=` tag) for ARC sealing is always `relaxed/relaxed` and cannot be changed.
158
188
 
189
+ #### Example
190
+
191
+ ```bash
192
+ mailauth seal /path/to/message.eml --domain example.com --selector s1 --private-key /path/to/private.key --verbose
159
193
  ```
160
- $ mailauth seal /path/message.eml --domain kreata.ee --selector test --privateKey /path/private-rsa.pem --verbose
161
- Reading email message from /path/message.eml
162
- Signing domain: kreata.ee
163
- Key selector: test
194
+
195
+ **Sample Output:**
196
+
197
+ ```
198
+ Reading email message from /path/to/message.eml
199
+ Signing domain: example.com
200
+ Key selector: s1
164
201
  Canonicalization algorithm: relaxed/relaxed
165
202
  Hashing algorithm: rsa-sha256
166
- Signing time: 2020-12-03T23:04:41.082Z
203
+ Sealing time: 2023-03-15T12:05:00.000Z
167
204
  --------
168
- ARC-Seal: i=3; a=rsa-sha256; t=1607036681; cv=pass; d=kreata.ee; s=test;
205
+ ARC-Seal: i=3; a=rsa-sha256; t=1678884300; cv=pass; d=example.com; s=s1;
169
206
  b=Fo3hayVos+J77lzzgmr6J92gsUBKlPt/ZkoQt9ZCi514zy8+1WLvTHmI8CMUXAcegdcqP0NHt
170
207
  ...
171
208
  ```
172
209
 
173
210
  ### spf
174
211
 
175
- `spf` command takes an email address and an IP address and returns a JSON formatted SPF report.
212
+ The `spf` command checks the SPF (Sender Policy Framework) record for a given email address and IP address.
176
213
 
177
- ```
178
- $ mailauth spf [options]
214
+ #### Usage
215
+
216
+ ```bash
217
+ mailauth spf [options]
179
218
  ```
180
219
 
181
- Where
220
+ #### Options
182
221
 
183
- - **options** are option flags and arguments
222
+ - `--sender user@example.com`, `-f user@example.com`: Email address from the MAIL FROM command. **Required.**
223
+ - `--client-ip x.x.x.x`, `-i x.x.x.x`: IP address of the remote client that sent the email. **Required.**
224
+ - `--helo hostname`, `-e hostname`: Hostname from the HELO/EHLO command.
225
+ - `--mta hostname`, `-m hostname`: Hostname of the server performing the SPF check.
226
+ - `--dns-cache /path/to/dns.json`, `-n /path/to/dns.json`: Path to a DNS cache file.
227
+ - `--verbose`, `-v`: Enables verbose output.
228
+ - `--headers-only`, `-o`: Outputs only the SPF authentication header.
229
+ - `--max-lookups number`, `-x number`: Sets the maximum number of DNS lookups. Defaults to `10`.
230
+ - `--max-void-lookups number`, `-z number`: Sets the maximum number of void DNS lookups. Defaults to `2`.
184
231
 
185
- **Options**
232
+ #### Example
186
233
 
187
- - `--sender user@example.com` or `-f address` is the email address from the MAIL FROM command. Required.
188
- - `--client-ip x.x.x.x` or `-i x.x.x.x` is the IP of the remote client that sent the email. Required.
189
- - `--helo hostname` or `-e hostname` is the client hostname from the HELO/EHLO command. Used in some obscure SPF validation operations
190
- - `--mta hostname` or `-m hostname` is the server hostname doing the validation checks. Defaults to `os.hostname()`. Used in authentication headers.
191
- - `--dns-cache /path/to/dns.json` or `-n path` is the path to a file with cached DNS query responses. If this file is provided then no actual DNS requests are performed, only cached values from this file are used.
192
- - `--verbose` or `-v` if this flag is set then mailauth writes some debugging info to standard error
193
- - `--headers-only` or `-o` If set return SPF authentication header only. Default is to return a JSON structure.
194
- - `--max-lookups nr` or `-x nr` defines the allowed DNS lookup limit for SPF checks. Defaults to 10.
195
- - `--max-void-lookups nr` or `-z nr` defines the allowed DNS lookup limit for SPF checks. Defaults to 2.
234
+ ```bash
235
+ mailauth spf --verbose -f user@example.com -i 192.0.2.1
236
+ ```
196
237
 
197
- **Example**
238
+ **Sample Output:**
198
239
 
199
240
  ```
200
- $ mailauth spf --verbose -f andris@wildduck.email -i 217.146.76.20
201
- Checking SPF for andris@wildduck.email
241
+ Checking SPF for user@example.com
202
242
  Maximum DNS lookups: 10
203
243
  --------
204
- DNS query for TXT wildduck.email: [["v=spf1 mx a -all"]]
205
- DNS query for MX wildduck.email: [{"exchange":"mail.wildduck.email","priority":1}]
206
- DNS query for A mail.wildduck.email: ["217.146.76.20"]
244
+ DNS query for TXT example.com: [["v=spf1 include:_spf.example.com -all"]]
245
+ DNS query for TXT _spf.example.com: [["v=spf1 ip4:192.0.2.0/24 -all"]]
207
246
  {
208
- "domain": "wildduck.email",
209
- "client-ip": "217.146.76.20",
210
- ...
247
+ "domain": "example.com",
248
+ "client-ip": "192.0.2.1",
249
+ "result": "pass",
250
+ "..."
251
+ }
211
252
  ```
212
253
 
213
254
  ### vmc
214
255
 
215
- `vmc` command takes either the URL for a VMC file or a file path or both. It then verifies if the VMC resource is a valid file or not and exposes its contents.
256
+ The `vmc` command validates a Verified Mark Certificate (VMC) used in BIMI (Brand Indicators for Message Identification).
216
257
 
217
- ```
218
- $ mailauth vmc [options]
219
- ```
220
-
221
- Where
258
+ #### Usage
222
259
 
223
- - **options** are option flags and arguments
260
+ ```bash
261
+ mailauth vmc [options]
262
+ ```
224
263
 
225
- **Options**
264
+ #### Options
226
265
 
227
- - `--authority <url>` or `-a <url>` is the URL for the VMC resource
228
- - `--authorityPath <path>` or `-p <path>` is the cached file for the authority URL to avoid network requests
229
- - `--domain <domain>` or `-d <domain>` is the sender domain to compare the certificate against
266
+ - `--authority <url>`, `-a <url>`: URL of the VMC resource.
267
+ - `--authorityPath <path>`, `-p <path>`: Path to a local VMC file, used to avoid network requests.
268
+ - `--domain <domain>`, `-d <domain>`: Sender domain to validate against the certificate.
230
269
 
231
- **Example**
270
+ #### Example
232
271
 
233
- ```
234
- $ mailauth vmc -a https://amplify.valimail.com/bimi/time-warner/yV3KRIg4nJW-cnn.pem -d cnn.com
235
- {
236
- "url": "https://amplify.valimail.com/bimi/time-warner/yV3KRIg4nJW-cnn.pem",
237
- "success": true,
238
- "domainVerified": true,
239
- "vmc": {
240
- "mediaType": "image/svg+xml",
241
- "hashAlgo": "sha1",
242
- "hashValue": "ea8c81da633c66a16262134a78576cdf067638e9",
243
- "logoFile": "<2300B base64 encoded file>",
244
- "validHash": true,
245
- "certificate": {
246
- "subject": {
247
- "businessCategory": "Private Organization",
248
- "jurisdictionCountryName": "US",
249
- "jurisdictionStateOrProvinceName": "Delaware",
250
- "serialNumber": "2976730",
251
- "countryName": "US",
252
- "stateOrProvinceName": "Georgia",
253
- "localityName": "Atlanta",
254
- "street": "190 Marietta St NW",
255
- "organizationName": "Cable News Network, Inc.",
256
- "commonName": "Cable News Network, Inc.",
257
- "trademarkCountryOrRegionName": "US",
258
- "trademarkRegistration": "5817930"
259
- },
260
- "subjectAltName": [
261
- "cnn.com"
262
- ],
263
- "fingerprint": "17:B3:94:97:E6:6B:C8:6B:33:B8:0A:D2:F0:79:6B:08:A2:A6:84:BD",
264
- "serialNumber": "0821B8FE0A9CBC3BAC10DA08C088EEF4",
265
- "validFrom": "2021-08-12T00:00:00.000Z",
266
- "validTo": "2022-08-12T23:59:59.000Z",
267
- "issuer": {
268
- "countryName": "US",
269
- "organizationName": "DigiCert, Inc.",
270
- "commonName": "DigiCert Verified Mark RSA4096 SHA256 2021 CA1"
271
- }
272
- }
273
- }
274
- }
272
+ ```bash
273
+ mailauth vmc -a https://example.com/path/to/vmc.pem -d example.com
275
274
  ```
276
275
 
277
- If the certificate verification fails, then the logo contents are not returned.
276
+ **Sample Output:**
278
277
 
279
- ```
280
- $ mailauth vmc -p /path/to/random/cert-bundle.pem
278
+ ```json
281
279
  {
282
- "success": false,
283
- "error": {
284
- "message": "Self signed certificate in certificate chain",
285
- "details": {
286
- "certificate": {
287
- "subject": {
288
- "commonName": "postal.vmc.local",
289
- "organizationName": "Postal Systems OU.",
290
- "countryName": "EE"
291
- },
292
- "subjectAltName": [],
293
- "fingerprint": "CC:49:83:ED:3F:6B:77:45:5B:A5:3B:9E:EC:99:0E:A1:EF:D7:FF:97",
294
- "serialNumber": "B61FBFBA917B15D9",
295
- "validFrom": "2022-07-09T06:13:33.000Z",
296
- "validTo": "2023-07-09T06:13:33.000Z",
297
- "issuer": {
298
- "commonName": "postal.vmc.local",
299
- "organizationName": "Postal Systems OU.",
300
- "countryName": "EE"
280
+ "url": "https://example.com/path/to/vmc.pem",
281
+ "success": true,
282
+ "domainVerified": true,
283
+ "vmc": {
284
+ "mediaType": "image/svg+xml",
285
+ "hashAlgo": "sha256",
286
+ "hashValue": "abc123...",
287
+ "logoFile": "<Base64 encoded SVG>",
288
+ "validHash": true,
289
+ "type": "VMC",
290
+ "certificate": {
291
+ "subject": {
292
+ "commonName": "Example Inc.",
293
+ "markType": "Registered Mark",
294
+ "..."
295
+ },
296
+ "subjectAltName": ["example.com"],
297
+ "fingerprint": "12:34:56:78:9A:BC:DE:F0...",
298
+ "serialNumber": "0123456789ABCDEF",
299
+ "validFrom": "2023-01-01T00:00:00.000Z",
300
+ "validTo": "2024-01-01T23:59:59.000Z",
301
+ "issuer": {
302
+ "commonName": "Trusted CA"
303
+ "..."
304
+ }
301
305
  }
302
- }
303
- },
304
- "code": "SELF_SIGNED_CERT_IN_CHAIN"
305
- }
306
+ }
306
307
  }
307
308
  ```
308
309
 
309
- The embedded SVG file is also validated.
310
+ If validation fails, the output includes error details:
310
311
 
311
- ```
312
- $ mailauth vmc -p /path/to/vmc-with-invalid-svg.pem
312
+ ```json
313
313
  {
314
- "success": false,
315
- "error": {
316
- "message": "VMC logo SVG validation failed",
317
- "details": {
318
- "message": "Not a Tiny PS profile",
319
- "code": "INVALID_BASE_PROFILE"
320
- },
321
- "code": "SVG_VALIDATION_FAILED"
322
- }
314
+ "success": false,
315
+ "error": {
316
+ "message": "Self signed certificate in certificate chain",
317
+ "details": {
318
+ "..."
319
+ },
320
+ "code": "SELF_SIGNED_CERT_IN_CHAIN"
321
+ }
323
322
  }
324
323
  ```
325
324
 
326
325
  ### bodyhash
327
326
 
328
- `bodyhash` command takes an email message and calculates the body hash value for it
327
+ The `bodyhash` command computes the body hash value of an email message, which is used in DKIM signatures.
329
328
 
330
- ```
331
- $ mailauth bodyhash [options] [email]
329
+ #### Usage
330
+
331
+ ```bash
332
+ mailauth bodyhash [options] [email]
332
333
  ```
333
334
 
334
- Where
335
+ - **email**: (Optional) Path to the EML-formatted email message file. If omitted, the email is read from standard input.
335
336
 
336
- - **options** are option flags and arguments
337
- - **email** is the path to EML formatted email message file. If not provided then email message is read from standard input
337
+ #### Options
338
338
 
339
- **Options**
339
+ - `--algo algorithm`, `-a algorithm`: Hashing algorithm (e.g., `sha256`). Defaults to `sha256`. Can also specify DKIM-style algorithms (e.g., `rsa-sha256`).
340
+ - `--canonicalization method`, `-c method`: Body canonicalization method (e.g., `relaxed`). Defaults to `relaxed`. Can use DKIM-style (e.g., `relaxed/relaxed`).
341
+ - `--body-length length`, `-l length`: Maximum length of the body to hash (`l=` tag).
342
+ - `--verbose`, `-v`: Enables verbose output.
340
343
 
341
- - `--algo sha256` or `-a sha256` is the signing algorithm. Defaults to "sha256". Can also use the a= tag format ("rsa-sha256").
342
- - `--canonicalization algo` or `-c algo` is the body canonicalization algorithm, defaults to "relaxed". Can also use the c= tag format ("relaxed/relaxed").
343
- - `--body-length 12345` or `-l 12345` is the maximum length of canonicalizated body to sign (l= tag)
344
+ #### Example
345
+
346
+ ```bash
347
+ mailauth bodyhash /path/to/message.eml -a sha1 --verbose
348
+ ```
344
349
 
345
- **Example**
350
+ **Sample Output:**
346
351
 
347
352
  ```
348
- $ mailauth bodyhash /path/message.eml -a sha1 --verbose
349
353
  Hashing algorithm: sha1
350
354
  Body canonicalization algorithm: relaxed
351
355
  --------
@@ -354,37 +358,67 @@ j+dD7whKXS1yDmyoWtvClYSyYiQ=
354
358
 
355
359
  ### license
356
360
 
357
- Display licenses for `mailauth` and included modules.
361
+ The `license` command displays the licenses for mailauth and its included modules.
358
362
 
359
- ```
360
- $ mailauth licenses
363
+ #### Usage
364
+
365
+ ```bash
366
+ mailauth license
361
367
  ```
362
368
 
363
- ## DNS cache file
369
+ #### Example
364
370
 
365
- In general you would use the `--dns-cache` option only when testing. This way you can provide different kind of DNS responses without actually setting up a DNS server and unlike when using real DNS you do not have to wait for the changes in the DNS server to propagate – whatever is in the provided cache file, is used for the DNS query responses.
371
+ ```bash
372
+ mailauth license
373
+ ```
366
374
 
367
- DNS cache file includes a JSON encoded object where main keys are the domain names (eg. `"_dmarc.example.com"`), sub keys are resource record types (eg. `"TXT"`) and values are the corresponding values as provided by the [dns module](https://nodejs.org/api/dns.html#dns_dns_resolvetxt_hostname_callback).
375
+ **Sample Output:**
368
376
 
369
- ```json
370
- {
371
- "full_domain_name": {
372
- "TXT": [["string1"]]
373
- }
374
- }
375
377
  ```
378
+ mailauth License: MIT License
379
+ Included Modules:
380
+ - module1: MIT License
381
+ - module2: Apache License 2.0
382
+ ...
383
+ ```
384
+
385
+ ## DNS Cache File
386
+
387
+ The `--dns-cache` option allows you to use a JSON-formatted DNS cache file for testing purposes. This avoids the need to set up a DNS server or wait for DNS propagation.
388
+
389
+ ### Format
390
+
391
+ The DNS cache file is a JSON object where:
376
392
 
377
- **Example**
393
+ - **Keys**: Fully qualified domain names (e.g., `"example.com"`).
394
+ - **Values**: Objects with DNS record types as keys (e.g., `"TXT"`, `"MX"`) and their corresponding values.
378
395
 
379
- This example provides SPF and DMARC policy records for "example.com":
396
+ **Example:**
380
397
 
381
398
  ```json
382
399
  {
383
400
  "example.com": {
384
- "TXT": [["v=spf1 include:_spf.google.com include:sendgrid.net", " include:servers.mcsv.net include:servers.outfunnel.com ip4:18.194.223.2 ~all"]]
401
+ "TXT": [["v=spf1 include:_spf.example.com -all"]],
402
+ "MX": [{ "exchange": "mail.example.com", "priority": 10 }]
385
403
  },
386
404
  "_dmarc.example.com": {
387
- "TXT": [["v=DMARC1; p=reject; sp=reject;"]]
405
+ "TXT": [["v=DMARC1; p=reject; rua=mailto:dmarc@example.com;"]]
388
406
  }
389
407
  }
390
408
  ```
409
+
410
+ ### Usage
411
+
412
+ Specify the DNS cache file using the `--dns-cache` option:
413
+
414
+ ```bash
415
+ mailauth report --dns-cache /path/to/dns-cache.json email.eml
416
+ ```
417
+
418
+ When this option is used, mailauth will not perform actual DNS queries but will use the data from the cache file instead.
419
+
420
+ ## License
421
+
422
+ &copy; 2020-2024 Postal Systems OÜ
423
+
424
+ Licensed under the [MIT License](LICENSE).