about-dat-pubkey-file.md

🔐 DatPubkeyFile

An API for libsodium pubkey crypto operations in the Beaker/Dat ecosystem. Includes mechanisms to:

• Sign
• Verify signatures
• Encrypt blobs
• Decrypt blobs
• Validate pubkey ownership

Summary

The premise behind DatPubkeyFile is that the key must be hosted on a dat:// site. All dats are themselves public keys which sign their files, and dat sites will be integrated into PKI and Webs of Trust to verify their identities.

If you have a DatPubkeyFile instance, then you know the key was loaded from and signed by the .origin of the object!

An example DatPubkeyFile would be dat://pfrazee.com/main.key. That object would have a .origin of 'dat://pfrazee.com'. The binding of pfrazee.com to the given dat is verified using an SSL certificate.

Mechanisms

A DatPubKey will be validated any time load() is called by pulling the key material from the target URL. If you want to re-validate the pubkey, you can call checkValidity() which will attempt the load again and compare it against the known key material.

Internally, Beaker will maintain a database of private keys. Any time a DatPubkeyFile is loaded, it will lookup the private key that matches the public key. If it's found, the user will be able to run sign() and decrypt().

dat-pubkey-file.js

// DatPubkeyFile

// constructors
var pk = await DatPubkeyFile.load(url) // read the pubkey-file from the given url
var pk = await DatPubkeyFile.load(archive, path) // alternative usage
var pk = await DatPubkeyFile.generate(url) // create a new pubkey-file at the given url
var pk = await DatPubkeyFile.generate(archive, path) // alternative usage

// properties
pk.url // the url of the pubkey file
pk.origin // the origin of the url (ie for 'dat://foo.com/keys/mykey.key' would be 'dat://foo.com')
pk.buffer // ArrayBuffer containing the key material

// methods
var sig = await pk.sign(value) // generate a signature
var valid = await pk.verify(sig, value) // validate a signature
var cypher = await pk.encrypt(plain) // encrypt some data
var plain = await pk.decrypt(cypher) // decrypt some data
var isValid = await pk.checkValidity() // (re)read the key material from the dat