Module Specification: Custodians
Introduction
Many online service providers require users to verify that they have authority to claim or act on behalf of a domain name – e.g. Google's Search Console, Microsoft's Office 365 and more. The state of the art is to instruct users to create a specific record in their DNS (usually TXT or CNAME) for each service. This presents a significant barrier to most users and often results in the DNS being bloated by unnecessary records.
The Custodians module enables domain name administrators to list the people that have permission to act as a custodian for a domain name. Custodians are listed by hashed identifier (e.g. an email address), permissions are associated with each custodian.
Domain name registrars could automatically create a custodian record for the domain registrant once the domain is registered, this would automatically grant permission for the domain registrant to claim their domain name on supporting services.
Status
The Custodians module is currently being finalised, we are inviting members of the technical community to provide feedback on the specification.
Conventions in This Document
The key words "must", "must not", "required", "shall", "shall not", "should", "should not", "recommended", "may", and "optional" are to be interpreted as described in RFC2119 
.
Links in This Document
For the benefit of readers, these icons are displayed next to links to indicate where the link leads:
Up the page
Another page
Down the page Another site (new window)Author
The Custodians module was created by Elliott Brown .
Working with Custodian Records
The first step for working with a NUM Contacts record is to create it.
Creating the Object
NUM records are written in MODL and are unpacked into objects by a MODL interpreter with the help of a NUM record configuration file. To successfully unpack the MODL object we must write a MODL string including the record configuration file and the NUM record itself.
Combining the RCF and NUM Record
Your MODL string should start with a *L (load) command for the Record Configuration File (RCF). Retrieve the NUM record from the DNS using a NUM lookup and add the record returned to the MODL string. In this example we've retreived a NUM record for the domain numexample.com.
Interpreting the MODL
Now we can interpret our MODL string and have a developer friendly unpacked object to work with:
The response will always be an array with the key custodians, each object in the array will include a hash and permissions key.
Hashing Identifiers
To check if an identifier, like an email address, has permissions to act on behalf of a domain you must first hash the identifier. All hashes in custodian records use the SHA-1 algorithm.
Valid Identifiers
Valid identifiers are email addresses and domain names. A domain name idenfitier indicates that all email users at that domain have permissions.
Checking Hashes
Work through the object checking the hashed identifier again each hash. An exact match indicates that the user represented by the identifier has permissions to act on behalf of the domain name.
Permissions
Permissions for any hash are provided in an array. There are three types of permissions: administrator, category and domain permissions.
Admin Permissions
Admin permissions grant the user access to all services. Admin is represented by the asterisk *.
Category Permissions
Category permissions grant the user access to services in particular categories. The categories are listed below:
| ID | Name | Explanation |
| m | Marketing | Services that categorise themselves as marketing / advertising related. |
| e | Services that categorise themselves as providing email related services. | |
| s | Storage | Services that categorise themselves as providing online file storage. |
| c | Certificates | Services that categorise themselves as providing certificates. |
Domain Permissions
Domain permissions grant the user access to all services offered at a particular domain or a subdommain of that domain.
Branches
In some circumstances, domain owners do not want to list hashes in the root record. For example, when there's too many custodians to list in one record. In these circumstances, a domain owner can indicate that there are branch records by setting branches=true.
Queries
Branch custodian records are queried by using the hash as the branch name. The resulting NUM record includes a permissions key listing the permissions for the user(s) represented by the hash. The permission types for branch records are the same as for root records, shown above.