https://sequoia-pgp.org/blog/2021/01/26/202101-sq-release/ Sequoia logo Sequoia logo sq, Sequoia PGP's CLI, Released - go to homepage Toggle Navigation * News * Code * Docs * Contribute * Projects * Community [ ] sq, Sequoia PGP's CLI, Released By Neal | January 26, 2021 Last month we released version 1.0 of our versatile, low-level OpenPGP library, sequoia-openpgp. Now we have released the first version of sq, version 0.23, which is meant for general use. sq is a command-line tool that intends to expose much (but not all!) of the functionality that the library provides. Although we fully intend for sq to be an OpenPGP swiss army knife, and that the truly arcane should--in general--be possible, we firstly want sq to be usable by humans at the command line. We understand this to mean that it should be possible to use sq to tweak and twiddle OpenPGP data. But, those who have the desire to use Sequoia to frob it will need to use the library. And, they are probably better served by it anyway. sq has a subcommand-style interface similar to git. This has the advantage that every command has its own option name space, which makes it much easier to understand exactly what options influence a given command. In terms of functionality, sq already provides the base operations that any OpenPGP user needs in their day-to-day use: key generation (sq key generate), encryption (sq encrypt) & decryption (sq decrypt), signing (sq sign) & verification (sq verify), key certification (sq certify), and key server (sq keyserver) & web key directory (WKD) (sq wkd) interaction. It also includes some utility functions. It can generate a WKD (sq wkd generate), encode and decode Autocrypt headers (sq autocrypt), manipulate keyrings (sq keyring), inspect OpenPGP-related data like file does (sq inspect), and pretty print an OpenPGP file's contents (sq packet dump). sq is still missing a fair amount of functionality. In particular, there is no public or private key store. (Although prototypes exist.) This means all OpenPGP certificates must be stored in files, which is not scalable. Also, many necessary and useful commands are still missing. For instance, it is not currently possible to add new subkeys to a certificate, or change their expiration date. sq is also not ready to be used from scripts. Although we are unlikely to change the current API, the bigger problem is that sq's output is not machine readable. In the medium term, we plan to add a JSON-output mode to every command. Given the legion of JSON parsers, this should effectively eliminate the need for tools that consume sq's output to have to parse it manually, and will hopefully eliminate an entire class of common security-sensitive bugs. Until now, we haven't published sq on crates.io, and we've discouraged packagers from including it in their distribution. We now think that sq is ready for general use. If you have suggestions, please reach out. A Quick Demo Creating an OpenPGP key is straightforward: $ sq key generate --export /tmp/alice.sec -u 'Alice ' sq saves the key in /tmp/alice.sec and a generic revocation certificate in /tmp/alice.sec.rev. We can use sq inspect to examine the new key's structure: $ sq inspect /tmp/alice.sec /tmp/alice.sec: Transferable Secret Key. Fingerprint: 1191 7C40 2605 5EA3 4980 8877 C7C7 FF13 8025 22BE Public-key algo: EdDSA Edwards-curve Digital Signature Algorithm Public-key size: 256 bits Secret key: Unencrypted Creation time: 2021-01-25 19:17:42 UTC Expiration time: 2024-01-26 12:44:03 UTC (creation time + P1095DT62781S) Key flags: certification Subkey: 0C61 2153 0ACF F0B2 C01E 6E8A 4D4D 029F 2206 7039 Public-key algo: EdDSA Edwards-curve Digital Signature Algorithm Public-key size: 256 bits Secret key: Unencrypted Creation time: 2021-01-25 19:17:42 UTC Expiration time: 2024-01-26 12:44:03 UTC (creation time + P1095DT62781S) Key flags: signing Subkey: F2CA 7FC7 A347 39F7 7CDC C1F0 C599 64AB 43F7 7134 Public-key algo: ECDH public key algorithm Public-key size: 256 bits Secret key: Unencrypted Creation time: 2021-01-25 19:17:42 UTC Expiration time: 2024-01-26 12:44:03 UTC (creation time + P1095DT62781S) Key flags: transport encryption, data-at-rest encryption UserID: Alice Here we see that sq uses ECC by default, and generates a signing subkey and an encryption subkey. (sq key generate has options to tweak both the cipher suite and the key's structure.) sq generates a signing subkey by default to prevent an attacker from repurposing a signature over data as a certification or binding signature. The secret key material is unencrypted by default. Supplying the --with-password option will cause sq to prompt for a password and use it to encrypt the secret key material. We can use sq packet dump to get even more details: $ sq packet dump /tmp/alice.sec Secret-Key Packet, new CTB, 88 bytes ... User ID Packet, new CTB, 25 bytes Value: Alice Signature Packet, new CTB, 212 bytes Version: 4 Type: PositiveCertification Pk algo: EdDSA Edwards-curve Digital Signature Algorithm Hash algo: SHA512 Hashed area: Signature creation time: 2021-01-25 19:17:42 UTC (critical) Key expiration time: P1095DT62781S (critical) Symmetric algo preferences: AES256, AES128 Issuer: C7C7 FF13 8025 22BE Notation: NotationData { flags: , name: "salt@notations.sequoia-pgp.org", value: [209, 99, ...] } Hash preferences: SHA512, SHA256 Primary User ID: true (critical) Key flags: C (critical) Features: MDC Issuer Fingerprint: 1191 7C40 2605 5EA3 4980 8877 C7C7 FF13 8025 22BE Digest prefix: 7E0A Level: 0 (signature over data) ... For the sake of brevity, I've only shown the User ID and the corresponding self signature. An interesting thing to note here is the salt@notations.sequoia-pgp.org notation. This is a random 32-byte value, which Sequoia inserts into every signature by default. Because it is unpredictable, it is harder for an attacker to trick a user into signing a specific message. It is possible to get even more details by supplying the --hex option to sq packet dump. This causes it to print a descriptive map of the packets' contents, which is useful if you are dissecting an OpenPGP message. $ sq packet dump --hex /tmp/alice.sec Secret-Key Packet, new CTB, 2 header bytes + 88 bytes Version: 4 Creation time: 2021-01-25 19:17:42 UTC Pk algo: EdDSA Edwards-curve Digital Signature Algorithm Pk size: 256 bits Fingerprint: 1191 7C40 2605 5EA3 4980 8877 C7C7 FF13 8025 22BE KeyID: C7C7 FF13 8025 22BE Secret Key: Unencrypted 00000000 c5 CTB 00000001 58 length 00000002 04 version 00000003 60 0f 19 56 creation_time 00000007 16 pk_algo 00000008 09 curve_len 00000009 2b 06 01 04 01 da 47 curve 00000010 0f 01 00000012 01 07 eddsa_public_len 00000014 40 7b 06 00 4c 00 63 89 81 95 2f 22 eddsa_public 00000020 5a 35 7c b2 84 45 ce 9f d9 85 8d 55 01 4d aa 76 00000030 f7 bd b2 07 a1 00000035 00 s2k_usage 00000036 00 fe eddsa_secret_len 00000038 30 95 9d a4 ae 95 c3 e4 eddsa_secret 00000040 fc 15 bb ca 5a 67 31 e1 14 1b 2b 0b 2f 1a 4c 6e 00000050 95 a8 cc 63 7c de 19 51 00000058 0f ef checksum ... To turn a key into a certificate (i.e., to remove the secret key material), we can use the sq keyring filter subcommand: $ sq keyring filter --to-certificate /tmp/alice.sec > /tmp/alice.pgp And using sq inspect, we see that we now have a certificate and not a secret key: $ sq inspect /tmp/alice.pgp /tmp/alice.pgp: OpenPGP Certificate. ... sq keyring filter also allows the user to specify a few predicates to actually filter the keyring. sq keyring has other useful functionality. It can split a keyring into individual keys and it can merge multiple keys or keyrings into a single keyring. To sign and encrypt a message, we specify one or more certificates for the recipients, and one or more keys for the signers. $ echo "Hello, woods!" | sq encrypt --recipient-cert /tmp/bob.pgp --signer-key /tmp/alice.sec > /tmp/msg.pgp Decrypting and verifying the signature is similar: $ sq decrypt --recipient-key /tmp/bob.sec --signer-cert /tmp/alice.pgp /tmp/msg.pgp Encrypted using AES with 256-bit key Compressed using ZIP Good signature from 4D4D 029F 2206 7039 Hello, woods! 1 good signature. (If you are interested in examining the structure of the message at the byte level, be sure to try the --hex option.) sq can also fetch keys from key servers: $ sq keyserver get neal@walfield.org -----BEGIN PGP PUBLIC KEY BLOCK----- xsEhBFUjmukBDqCpmVI7Ve+2xTFSTG+mXMFHml63/Yai2nqxBk9gBfQfRFIjMt74 ... And from WKDs: $ sq wkd get neal@walfield.org -----BEGIN PGP PUBLIC KEY BLOCK----- Comment: 8F17 7771 18A3 3DDA 9BA4 8E62 AACB 3243 6300 52D9 Comment: Neal H. Walfield Comment: Neal H. Walfield Comment: Neal H. Walfield Comment: Neal H. Walfield xsEhBFUjmukBDqCpmVI7Ve+2xTFSTG+mXMFHml63/Yai2nqxBk9gBfQfRFIjMt74 ... You can learn more about sq by reading its documentation. Financial Support Currently, six people are paid to work on Sequoia. Since the start of the project 3.5 years ago, they have all been paid by the p[?]p foundation. Additional financial support has come from a one-time donation from the Wau Holland Foundation in 2018. Phil Zimmermann, the creator of PGP, donated 1000 Euros. And, Proton Mail donated 1000 Euros after our interoperability test suite found several issues in OpenPGP.js and GopenPGP, which they maintain. Although the p[?]p foundation's finances are secure for the next half year, it is essential for Sequoia's mid-term health that we obtain addition funding. You don't need to directly use Sequoia to be positively impacted by it. For instance, OpenPGP CA is a new tool for creating federated CAs targeted at simplifying the use of OpenPGP for activists, lawyers, and journalists who can't rely on centralized authentication solutions. So, consider donating. Of course, if your company is using Sequoia, consider sponsoring a developer (or two). Note: if you want to use Sequoia under a license other than the GPLv2+, please contact the foundation. Thanks Sequoia is a team effort. sq includes code contributions from Azul, Igor Matuszewski, Justus Winter, Neal H. Walfield, Nora Widdecke, and Wiktor Kwapisiewicz. Copyright (c) 2018-2020, p[?]p foundation. Creative Commons License This work is licensed under a Creative Commons Attribution 4.0 International License. Template by Bootstrapious. Ported to Hugo by DevCows. Images by Ingo Kleiber, and Robert Anders.