openpgp.js

  1. /*
  2. Copyright 2021 Yarmo Mackenbach
  4. Licensed under the Apache License, Version 2.0 (the "License");
  5. you may not use this file except in compliance with the License.
  6. You may obtain a copy of the License at
  8. http://www.apache.org/licenses/LICENSE-2.0
  10. Unless required by applicable law or agreed to in writing, software
  11. distributed under the License is distributed on an "AS IS" BASIS,
  12. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13. See the License for the specific language governing permissions and
  14. limitations under the License.
  15. */
  16. import axios from 'axios'
  17. import { isUri } from 'valid-url'
  18. import { readKey, PublicKey } from 'openpgp'
  19. import HKP from '@openpgp/hkp-client'
  20. import WKD from '@openpgp/wkd-client'
  21. import { Claim } from './claim.js'
  22. import { ProfileType, PublicKeyEncoding, PublicKeyFetchMethod, PublicKeyType } from './enums.js'
  23. import { Profile } from './profile.js'
  24. import { Persona } from './persona.js'
  26. /**
  27.  * Functions related to OpenPGP Profiles
  28.  * @module openpgp
  29.  */
  31. /**
  32.  * Fetch a public key using keyservers
  33.  * @function
  34.  * @param {string} identifier - Fingerprint or email address
  35.  * @param {string} [keyserverDomain] - Domain of the keyserver
  36.  * @returns {Promise<Profile>} The profile from the fetched OpenPGP key
  37.  * @example
  38.  * const key1 = doip.keys.fetchHKP('alice@domain.tld');
  39.  * const key2 = doip.keys.fetchHKP('123abc123abc');
  40.  * const key3 = doip.keys.fetchHKP('123abc123abc', 'pgpkeys.eu');
  41.  */
  42. export async function fetchHKP (identifier, keyserverDomain = 'keys.openpgp.org') {
  43.   const keyserverBaseUrl = `https://${keyserverDomain ?? 'keys.openpgp.org'}`
  45.   const hkp = new HKP(keyserverBaseUrl)
  46.   const lookupOpts = {
  47.     query: identifier
  48.   }
  50.   const publicKeyArmored = await hkp
  51.     .lookup(lookupOpts)
  52.     .catch((error) => {
  53.       throw new Error(`Key does not exist or could not be fetched (${error})`)
  54.     })
  56.   if (!publicKeyArmored) {
  57.     throw new Error('Key does not exist or could not be fetched')
  58.   }
  60.   const publicKey = await readKey({
  61.     armoredKey: publicKeyArmored
  62.   })
  63.     .catch((error) => {
  64.       throw new Error(`Key could not be read (${error})`)
  65.     })
  67.   const profile = await parsePublicKey(publicKey)
  68.   profile.publicKey.fetch.method = PublicKeyFetchMethod.HKP
  69.   profile.publicKey.fetch.query = identifier
  71.   return profile
  72. }
  74. /**
  75.  * Fetch a public key using Web Key Directory
  76.  * @function
  77.  * @param {string} identifier - Identifier of format 'username@domain.tld`
  78.  * @returns {Promise<Profile>} The profile from the fetched OpenPGP key
  79.  * @example
  80.  * const key = doip.keys.fetchWKD('alice@domain.tld');
  81.  */
  82. export async function fetchWKD (identifier) {
  83.   const wkd = new WKD()
  84.   const lookupOpts = {
  85.     email: identifier
  86.   }
  88.   const publicKeyBinary = await wkd
  89.     .lookup(lookupOpts)
  90.     .catch((/** @type {Error} */ error) => {
  91.       throw new Error(`Key does not exist or could not be fetched (${error})`)
  92.     })
  94.   if (!publicKeyBinary) {
  95.     throw new Error('Key does not exist or could not be fetched')
  96.   }
  98.   const publicKey = await readKey({
  99.     binaryKey: publicKeyBinary
  100.   })
  101.     .catch((error) => {
  102.       throw new Error(`Key could not be read (${error})`)
  103.     })
  105.   const profile = await parsePublicKey(publicKey)
  106.   profile.publicKey.fetch.method = PublicKeyFetchMethod.WKD
  107.   profile.publicKey.fetch.query = identifier
  109.   return profile
  110. }
  112. /**
  113.  * Fetch a public key from Keybase
  114.  * @function
  115.  * @param {string} username - Keybase username
  116.  * @param {string} fingerprint - Fingerprint of key
  117.  * @returns {Promise<Profile>} The profile from the fetched OpenPGP key
  118.  * @example
  119.  * const key = doip.keys.fetchKeybase('alice', '123abc123abc');
  120.  */
  121. export async function fetchKeybase (username, fingerprint) {
  122.   const keyLink = `https://keybase.io/${username}/pgp_keys.asc?fingerprint=${fingerprint}`
  123.   let rawKeyContent
  124.   try {
  125.     rawKeyContent = await axios.get(
  126.       keyLink,
  127.       {
  128.         responseType: 'text'
  129.       }
  130.     )
  131.       .then((/** @type {import('axios').AxiosResponse} */ response) => {
  132.         if (response.status === 200) {
  133.           return response
  134.         }
  135.       })
  136.       .then((/** @type {import('axios').AxiosResponse} */ response) => response.data)
  137.   } catch (e) {
  138.     throw new Error(`Error fetching Keybase key: ${e.message}`)
  139.   }
  141.   const publicKey = await readKey({
  142.     armoredKey: rawKeyContent
  143.   })
  144.     .catch((error) => {
  145.       throw new Error(`Key does not exist or could not be fetched (${error})`)
  146.     })
  148.   const profile = await parsePublicKey(publicKey)
  149.   profile.publicKey.fetch.method = PublicKeyFetchMethod.HTTP
  150.   profile.publicKey.fetch.query = null
  151.   profile.publicKey.fetch.resolvedUrl = keyLink
  153.   return profile
  154. }
  156. /**
  157.  * Get a public key from armored public key text data
  158.  * @function
  159.  * @param {string} rawKeyContent - Plaintext ASCII-formatted public key data
  160.  * @returns {Promise<Profile>} The profile from the armored public key
  161.  * @example
  162.  * const plainkey = `-----BEGIN PGP PUBLIC KEY BLOCK-----
  163.  *
  164.  * mQINBF0mIsIBEADacleiyiV+z6FIunvLWrO6ZETxGNVpqM+WbBQKdW1BVrJBBolg
  165.  * [...]
  166.  * =6lib
  167.  * -----END PGP PUBLIC KEY BLOCK-----`
  168.  * const key = doip.keys.fetchPlaintext(plainkey);
  169.  */
  170. export async function fetchPlaintext (rawKeyContent) {
  171.   const publicKey = await readKey({
  172.     armoredKey: rawKeyContent
  173.   })
  174.     .catch((error) => {
  175.       throw new Error(`Key could not be read (${error})`)
  176.     })
  178.   const profile = await parsePublicKey(publicKey)
  180.   return profile
  181. }
  183. /**
  184.  * Fetch a public key using an URI
  185.  * @function
  186.  * @param {string} uri - URI that defines the location of the key
  187.  * @returns {Promise<Profile>} The profile from the fetched OpenPGP key
  188.  * @example
  189.  * const key1 = doip.keys.fetchURI('hkp:alice@domain.tld');
  190.  * const key2 = doip.keys.fetchURI('hkp:123abc123abc');
  191.  * const key3 = doip.keys.fetchURI('wkd:alice@domain.tld');
  192.  */
  193. export async function fetchURI (uri) {
  194.   if (!isUri(uri)) {
  195.     throw new Error('Invalid URI')
  196.   }
  198.   const re = /([a-zA-Z0-9]*):([a-zA-Z0-9@._=+-]*)(?::([a-zA-Z0-9@._=+-]*))?/
  199.   const match = uri.match(re)
  201.   if (!match[1]) {
  202.     throw new Error('Invalid URI')
  203.   }
  205.   switch (match[1]) {
  206.     case 'hkp':
  207.       return await fetchHKP(
  208.         match[3] ? match[3] : match[2],
  209.         match[3] ? match[2] : null
  210.       )
  212.     case 'wkd':
  213.       return await fetchWKD(match[2])
  215.     case 'kb':
  216.       return await fetchKeybase(match[2], match.length >= 4 ? match[3] : null)
  218.     default:
  219.       throw new Error('Invalid URI protocol')
  220.   }
  221. }
  223. /**
  224.  * Fetch a public key
  225.  *
  226.  * This function will attempt to detect the identifier and fetch the key
  227.  * accordingly. If the identifier is an email address, it will first try and
  228.  * fetch the key using WKD and then HKP. Otherwise, it will try HKP only.
  229.  *
  230.  * This function will also try and parse the input as a plaintext key
  231.  * @function
  232.  * @param {string} identifier - URI that defines the location of the key
  233.  * @returns {Promise<Profile>} The profile from the fetched OpenPGP key
  234.  * @example
  235.  * const key1 = doip.keys.fetch('alice@domain.tld');
  236.  * const key2 = doip.keys.fetch('123abc123abc');
  237.  */
  238. export async function fetch (identifier) {
  239.   const re = /([a-zA-Z0-9@._=+-]*)(?::([a-zA-Z0-9@._=+-]*))?/
  240.   const match = identifier.match(re)
  242.   let profile = null
  244.   // Attempt plaintext
  245.   try {
  246.     profile = await fetchPlaintext(identifier)
  247.   } catch (e) {}
  249.   // Attempt WKD
  250.   if (!profile && identifier.includes('@')) {
  251.     try {
  252.       profile = await fetchWKD(match[1])
  253.     } catch (e) {}
  254.   }
  256.   // Attempt HKP
  257.   if (!profile) {
  258.     profile = await fetchHKP(
  259.       match[2] ? match[2] : match[1],
  260.       match[2] ? match[1] : null
  261.     )
  262.   }
  264.   if (!profile) {
  265.     throw new Error('Key does not exist or could not be fetched')
  266.   }
  268.   return profile
  269. }
  271. /**
  272.  * Process a public key to get a profile
  273.  * @function
  274.  * @param {PublicKey} publicKey - The public key to parse
  275.  * @returns {Promise<Profile>} The profile from the processed OpenPGP key
  276.  * @example
  277.  * const key = doip.keys.fetchURI('hkp:alice@domain.tld');
  278.  * const profile = doip.keys.parsePublicKey(key);
  279.  * profile.personas[0].claims.forEach(claim => {
  280.  *   console.log(claim.uri);
  281.  * });
  282.  */
  283. export async function parsePublicKey (publicKey) {
  284.   if (!(publicKey && (publicKey instanceof PublicKey))) {
  285.     throw new Error('Invalid public key')
  286.   }
  288.   const fingerprint = publicKey.getFingerprint()
  289.   const primaryUser = await publicKey.getPrimaryUser()
  290.   const users = publicKey.users
  291.   const personas = []
  293.   users.forEach((user, i) => {
  294.     if (!user.userID) return
  296.     const pe = new Persona(user.userID.name, [])
  297.     pe.setIdentifier(user.userID.userID)
  298.     pe.setDescription(user.userID.comment)
  299.     pe.setEmailAddress(user.userID.email)
  301.     if ('selfCertifications' in user && user.selfCertifications.length > 0) {
  302.       const selfCertification = user.selfCertifications.sort((e1, e2) => e2.created.getTime() - e1.created.getTime())[0]
  304.       if (selfCertification.revoked) {
  305.         pe.revoke()
  306.       }
  307.       const notations = selfCertification.rawNotations
  308.       pe.claims = notations
  309.         .filter(
  310.           ({ name, humanReadable }) =>
  311.             humanReadable && (name === 'proof@ariadne.id' || name === 'proof@metacode.biz')
  312.         )
  313.         .map(
  314.           ({ value }) =>
  315.             new Claim(new TextDecoder().decode(value), `openpgp4fpr:${fingerprint}`)
  316.         )
  317.     }
  319.     personas.push(pe)
  320.   })
  322.   const profile = new Profile(ProfileType.OPENPGP, `openpgp4fpr:${fingerprint}`, personas)
  323.   profile.primaryPersonaIndex = primaryUser.index
  325.   profile.publicKey.keyType = PublicKeyType.OPENPGP
  326.   profile.publicKey.fingerprint = fingerprint
  327.   profile.publicKey.encoding = PublicKeyEncoding.ARMORED_PGP
  328.   profile.publicKey.encodedKey = publicKey.armor()
  329.   profile.publicKey.key = publicKey
  331.   return profile
  332. }