StackExchange/dnscontrol
1
1
Fork 0
mirror of https://github.com/StackExchange/dnscontrol.git synced 2025-09-06 21:24:18 +08:00
Code Issues Projects Releases Packages Wiki Activity

NEW FEATURE: DKIM_BUILDER() adds a DKIM record builder (#3627)

Browse source 
Co-authored-by: Tom Limoncelli <tlimoncelli@stackoverflow.com>
This commit is contained in:
Costas Drogos 2025-07-18 16:38:50 +02:00 • committed by GitHub
parent a815bdcf45
commit c842eb26a5
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
5 changed files with 233 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

68
commands/types/dnscontrol.d.ts vendored
View file

@ -819,6 +819,74 @@ declare function DHCID(name: string, digest: string, ...modifiers: RecordModifie
*/
declare const DISABLE_IGNORE_SAFETY_CHECK: DomainModifier;
/**
* DNSControl contains a `DKIM_BUILDER` which can be used to simply create
* DKIM policies for your domains.
*
* ## Example
*
* ### Simple example
*
* ```javascript
* D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER),
* DKIM_BUILDER({
* selector: "s1",
* pubkey: "MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDC5/z4L"
* }),
* );
* ```
*
* This yield the following record:
*
* ```text
* s1._domainkey IN TXT "v=DKIM1; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDC5/z4L"
* ```
*
* ### Advanced example
*
* ```javascript
* D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER),
* DKIM_BUILDER({
* label: "alerts",
* selector: "k2",
* pubkey: "MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDC5/z4L",
* flags: ['y'],
* hashtypes: ['sha256'],
* keytype: 'rsa',
* servicetypes: ['email'],
* ttl: 150
* }),
* );
* ```
*
* This yields the following record:
*
* ```text
*
* k2._domainkey.alerts IN TXT "v=DKIM1; k=rsa; s=email; t=y; h=sha256; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDC5/z4L" ttl=150
*
* ```
*
* ### Parameters
*
* * `label:` The DNS label for the DKIM record (`[selector]._domainkey` prefix is added; default: `'@'`)
* * `selector:` Selector used for the label. e.g. `s1` or `mail`
* * `pubkey:` Public key `p` to be used for DKIM.
* * `keytype:` Key type `k`. Defaults to `'rsa'` if omitted (optional)
* * `flags:` Which types `t` of flags to activate, ie. 'y' and/or 's'. Array, defaults to 's' (optional)
* * `hashtypes:` Acceptable hash algorithms `h` (optional)
* * `servicetypes:` Record-applicable service types (optional)
* * `note:` Note field `n` for admins. Avoid if possible to keep record length short. (optional)
* * `ttl:` Input for `TTL` method (optional)
*
* ### Caveats
*
* * DKIM (TXT) records are automatically split using `AUTOSPLIT`.
*
* @see https://docs.dnscontrol.org/language-reference/domain-modifiers/dkim_builder
*/
declare function DKIM_BUILDER(opts: { label?: string; selector: string; pubkey: string; flags?: string[]; hashtypes?: string[]; keytype?: string; servicetypes?: string[]; note?: string; ttl?: Duration }): DomainModifier;
/**
* DNSControl contains a `DMARC_BUILDER` which can be used to simply create
* DMARC policies for your domains.

1
documentation/SUMMARY.md
View file

@ -42,6 +42,7 @@
* [DNAME](language-reference/domain-modifiers/DNAME.md)
* [DNSKEY](language-reference/domain-modifiers/DNSKEY.md)
* [DISABLE_IGNORE_SAFETY_CHECK](language-reference/domain-modifiers/DISABLE_IGNORE_SAFETY_CHECK.md)
* [DKIM_BUILDER](language-reference/domain-modifiers/DKIM_BUILDER.md)
* [DMARC_BUILDER](language-reference/domain-modifiers/DMARC_BUILDER.md)
* [DS](language-reference/domain-modifiers/DS.md)
* [DefaultTTL](language-reference/domain-modifiers/DefaultTTL.md)

1
documentation/advanced-features/code-tricks.md
View file

@ -5,6 +5,7 @@ Problem: It is difficult to get CAA and other records exactly right.
Solution: Use a "builder" to construct it for you.
* [CAA_BUILDER](../language-reference/domain-modifiers/CAA_BUILDER.md)
* [DKIM_BUILDER](../language-reference/domain-modifiers/DKIM_BUILDER.md)
* [DMARC_BUILDER](../language-reference/domain-modifiers/DMARC_BUILDER.md)
* [M365_BUILDER](../language-reference/domain-modifiers/M365_BUILDER.md)
* [SPF_BUILDER](../language-reference/domain-modifiers/SPF_BUILDER.md)

92
documentation/language-reference/domain-modifiers/DKIM_BUILDER.md Normal file
View file

@ -0,0 +1,92 @@
---
name: DKIM_BUILDER
parameters:
- label
- selector
- pubkey
- flags
- hashtypes
- keytype
- servicetypes
- note
- ttl
parameters_object: true
parameter_types:
label: string?
selector: string
pubkey: string
flags: string[]?
hashtypes: string[]?
keytype: string?
servicetypes: string[]?
note: string?
ttl: Duration?
---
DNSControl contains a `DKIM_BUILDER` which can be used to simply create
DKIM policies for your domains.
## Example
### Simple example
{% code title="dnsconfig.js" %}
```javascript
D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER),
DKIM_BUILDER({
selector: "s1",
pubkey: "MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDC5/z4L"
}),
);
```
{% endcode %}
This yield the following record:
```text
s1._domainkey IN TXT "v=DKIM1; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDC5/z4L"
```
### Advanced example
{% code title="dnsconfig.js" %}
```javascript
D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER),
DKIM_BUILDER({
label: "alerts",
selector: "k2",
pubkey: "MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDC5/z4L",
flags: ['y'],
hashtypes: ['sha256'],
keytype: 'rsa',
servicetypes: ['email'],
ttl: 150
}),
);
```
{% endcode %}
This yields the following record:
```text
k2._domainkey.alerts IN TXT "v=DKIM1; k=rsa; s=email; t=y; h=sha256; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDC5/z4L" ttl=150
```
### Parameters
* `label:` The DNS label for the DKIM record (`[selector]._domainkey` prefix is added; default: `'@'`)
* `selector:` Selector used for the label. e.g. `s1` or `mail`
* `pubkey:` Public key `p` to be used for DKIM.
* `keytype:` Key type `k`. Defaults to `'rsa'` if omitted (optional)
* `flags:` Which types `t` of flags to activate, ie. 'y' and/or 's'. Array, defaults to 's' (optional)
* `hashtypes:` Acceptable hash algorithms `h` (optional)
* `servicetypes:` Record-applicable service types (optional)
* `note:` Note field `n` for admins. Avoid if possible to keep record length short. (optional)
* `ttl:` Input for `TTL` method (optional)
### Caveats
* DKIM (TXT) records are automatically split using `AUTOSPLIT`.

71
pkg/js/helpers.js
View file

@ -1747,6 +1747,77 @@ function CAA_BUILDER(value) {
return r;
}
// DKIM_BUILDER takes an object:
// label: The DNS label for the DKIM record ([selector]._domainkey prefix is added; default: '@')
// selector: Selector used for the label. e.g. s1 or mail
// pubkey: Public key (p) to be used for DKIM.
// keytype: Key type (k). Defaults to 'rsa' if missing (optional)
// flags: Which types (t) of flags to activate, ie. 'y' and/or 's'. Array, defaults to 's' (optional)
// hashtypes: Acceptable hash algorithma (h) (optional)
// servicetypes: Record-applicable service types (optional)
// note: Note field fo admins. Avoid if possible to keep record length short. (optional)
// ttl: The time for TTL, integer or string. (default: not defined, using DefaultTTL)
function DKIM_BUILDER(value) {
if (!value) {
value = {};
}
kvs = [];
if (!value.selector) {
throw 'DKIM_BUILDER selector cannot be empty';
}
if (!value.pubkey) {
throw 'DKIM_BUILDER pubkey cannot be empty';
}
// build the label
if (!value.label) {
value.label = '@';
}
if (value.label !== '@') {
value.label = value.selector + '._domainkey' + '.' + value.label;
} else {
value.label = value.selector + '._domainkey';
}
kvs.push('v=DKIM1');
if (value.keytype) {
kvs.push('k=' + value.keytype);
}
if (value.servicetypes) {
kvs.push('s=' + value.servicetypes);
}
if (value.flags && value.flags.length > 0) {
kvs.push('t=' + value.flags.join(':'));
}
if (value.hashtypes && value.hashtypes.length > 0) {
kvs.push('h=' + value.hashtypes.join(':'));
}
if (value.note) {
kvs.push('n=' + value.note);
}
kvs.push('p=' + value.pubkey);
var DKIM_TTL = function () {};
if (value.ttl) {
DKIM_TTL = TTL(value.ttl);
}
r = []; // The list of records to return.
r.push(
TXT(value.label, kvs.join('\; '), DKIM_TTL)
);
return r;
}
// DMARC_BUILDER takes an object:
// label: The DNS label for the DMARC record (_dmarc prefix is added; default: '@')
// version: The DMARC version, by default DMARC1 (optional)