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 Content on another site..

Author

The Custodians module was created by Elliott Brown Content on another site..

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 Content on another site. 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 Content elsewhere on this site. and add the record returned to the MODL string. In this example we've retreived a NUM record for the domain numexample.com.

*LOAD="http://modules.numprotocol.com/4/rcf.txt"; @n=1;c[be165e855fc34cee0cdfd1b68921152132ee9191:[*];8bfa323c01e3a7f0e90f7685d1b0188b7c8db37e:[numserver.com];a548a3b5f8920fac10530f63da8ce63b67cba768:[m;e;s;c]];b=true
Writing the MODL string.

Interpreting the MODL

Now we can interpret our MODL string and have a developer friendly unpacked object to work with:

Loading
An unpacked Custodians record.

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 Email 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.