From patchwork Mon Dec 7 22:19:38 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: morganamilo X-Patchwork-Id: 1824 Return-Path: Delivered-To: patchwork@archlinux.org Received: from apollo.archlinux.org (localhost [127.0.0.1]) by apollo.archlinux.org (Postfix) with ESMTP id E2E171C9979B0 for ; Mon, 7 Dec 2020 22:46:37 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on apollo.archlinux.org X-Spam-Level: X-Spam-Status: No, score=-1.1 required=5.0 tests=DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1,DKIM_VALID=-0.1,DKIM_VALID_AU=-0.1, MAILING_LIST_MULTI=-1,SPF_HELO_PASS=-0.001,T_DMARC_POLICY_NONE=0.01 autolearn=ham autolearn_force=no version=3.4.4 X-Spam-BL-Results: Received: from mail.archlinux.org (mail.archlinux.org [IPv6:2a01:4f9:c010:3052::1]) by apollo.archlinux.org (Postfix) with ESMTPS for ; Mon, 7 Dec 2020 22:46:37 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=archlinux.org; s=luna2; t=1607379730; bh=o/d2yeZZJvdeKrHwZqS+ZHTCKiSzHFHCT+3U/Jtff5s=; h=From:To:Date:In-Reply-To:References:Subject:List-Id: List-Unsubscribe:List-Archive:List-Post:List-Help:List-Subscribe: Reply-To; b=qO5FHs+PK23zzfwwxEx1c+k0rRuQ/MxHK4ijKlZDYf7cEwyRWJ5WwY/5oANwpEyXJ WKi+vBZ06e/H7+N3lXCNVASKZb7h6QlA6tyzcepHXc+9fxUVRAGHjgl4ydQ8OAnHHY tam38opXi25U3DTJo8nS23WvlCTyGT5vYmqjyBqeEH5eS1jBWnTxX7+63Hz0Dwjqy/ 2K+NLlK3p/XGqSpsJTRDLQ+2bt6cs/5Erf5xxGWH5JrBpl7NLtbAGnE/t5kLfNfCOv nialnHDnE6PikRUwNEaeEK8xvc0EIVLVaWb/M3NUpyMndLr92UU/L9XO+LR9ymqx/A GzwJeQpoOi8heNhMYEMhq4TIplaXOp8szdX6Htl7BvxBX40D7biBvLFC/7/qxAQf6t FCpbEUMRwBUbAAQv0fi+O1hlmO8hDKT8OemWm1TjLmbBATMARVc2r0rHwww+kC+Jni iwntEVcwDtWB85wUNDhaU5VL0qBqc3eXMvcl6EQQUvCWpO2fSvFPv7qKH0glhOCvDM A5g07tYvAJdxRkzyqsXTJw+KWa7ze6YA2RU+TF2TkR0yqeoV+1TURiOxLJBm+MN1bw qqdr0BZ9LQBr6/XLI+q35zl6ICP5z2ImHOOLM1luNAjKgFsZWIYE5CmiwQq9VjeRB/ VTUaHJZG7g0rPGIZCcFO9pIs= DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=archlinux.org; s=dkim-rsa; t=1607381189; h=from:from:sender:sender:reply-to:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=2T5HW1K5uJRBc/+3D/g9kaE6kQG4n3JnsK7TggMss8o=; b=YpPzT5h4TXbST8lE3JBOrOhCXIQq2kJLE2wbWTIdqyJefGndhZ+o5fQVMczXROHuxYlJxM yPiec+yQpK1Y82NzhVeM2lMvccuu9CJMKsBAvrKnG5CD5W8/1G0KV3CarNVw6nK4ep8Ly3 2Ph4nFpFGGFn8Gwtihc69OHQZyDxCcHpjd/ly7v6GMX33GcNaPG8OQ9CM1dj93un031Eie IQKehirM3ukfyESzrnjyHe+Ry3ChUQSxG9N+9jm8sjOvyJRPPIRml4DbFBhoRrBRoqeg31 8lBBmPjqNZwQLP234kUimeAruyvqT0xWNqi3heSE3W63t7Qums9ADcX7HHwxAOIzo5TQLs goiVpcIZtDW4zoqodgn6xqo99tI2niQP8JsL2GkmmKh+OYuKrGIAI012+lXpl9tyGJ0cS8 tBLkUrcQF/BZs6ttBE0OgadwD6MSVLV4u/ifdjXnVZrG4T8FG6eaKcNG3iQjPXgSr0TmV6 /AeUpmciN7gN+p8+g6zfvhkbVTtvrPIIn9xHAcrsRFX+UoDyijW/obdQqdDna8kjJm3no1 GcUDRS8L2DJlG8/YOdFKfT+c5Ungy/0qfsz4aVl59bl133d+YCBszynM7Ng8XzQ8UrwGBZ byfeVuRyPFKefQgmxYOmSyiEUkTF6YfQOcsxNqRGtBFp4uCtXKxvU= DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=archlinux.org; s=dkim-ed25519; t=1607381189; h=from:from:sender:sender:reply-to:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=2T5HW1K5uJRBc/+3D/g9kaE6kQG4n3JnsK7TggMss8o=; b=Q5NM/dQwzEBDQIHmRtIp7HgiqJ6L24UeqEjQzXjjuDvHylu3Lq8WM4iCYmduxRabz9ji7k GrJuWoQVrcGTNaBA== From: morganamilo DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=archlinux.org; s=dkim-rsa; t=1607379726; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=2T5HW1K5uJRBc/+3D/g9kaE6kQG4n3JnsK7TggMss8o=; b=iyluZ4ShaGHaXxdPEoGE77w98TMQebRWaUbRXMP5Ly1iNxj1dAxn7Y6t2a0qU5zpSBPPZN L55WPKFJSaggMG0AfcR5FA/DsuTUZJ5MxvGTrQi/hpZyokKO+Te0wxPczoeT+zLv6HqU9N WXuluF6j8M/KW2CQX2HvVFxTd1oSbcC4H2/xOcSLwVPG2hv7TSmZYLX0j7uuLpYpE3EFlV 4EjtgEsQCV4h8du4bqNQQh/nHkLmTmxCTYsc4CcQHecgif/7sE0LBotS+bYayITZMu3Deo fPN7K1jzW3zGS3dsD6zD839B3X4P04KAbYYi3ciRSN9jOTvX9KcNzly54s6wdtDah4eFoD AWhu7aHMdWCUupO1hmCOYxvndKPnHFA3mrCICUn8JNvzgfzIwhIy4TGJR3DbIwax9UC45P 0ewelytttZTrU4RNXH5FaKZIIobOjSzHL7hBSi3YXR/algMadrQv4aSKEeQJ1LZNXATw0I +I5DF+Btz7Z+CcTfoyrYce2ff+ZbfHOqnSUBUa7y/fzjJC+2Wc2OdEIJ/7AiUUog3rSxmJ Cm9WnHnS/apnWAWoXFCsWTaLwa3/NJwuweqbrtT37+GDIahIkIxSysjg4mRMIn2iSHf1a+ 9nbQQX+rgI5bK9NxpDznx0zYGRQ/gCF/K+Hz+NvzPjeapxT67WdpQ= DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=archlinux.org; s=dkim-ed25519; t=1607379726; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=2T5HW1K5uJRBc/+3D/g9kaE6kQG4n3JnsK7TggMss8o=; b=0RoCXbJ2mhQN5mdBcSG80/ieRx3b47oPMlzbOjp+ZJMfftXT/kBaBXy9XD3lQOC2at9Z8X yyEVGjNdQQ5P03Dg== To: pacman-dev@archlinux.org Date: Mon, 7 Dec 2020 22:19:38 +0000 Message-Id: <20201207221956.667322-6-morganamilo@archlinux.org> X-Mailer: git-send-email 2.29.2 In-Reply-To: <20201207221956.667322-1-morganamilo@archlinux.org> References: <20201207221956.667322-1-morganamilo@archlinux.org> MIME-Version: 1.0 Subject: [pacman-dev] [PATCH 05/23] doc: document signatures X-BeenThere: pacman-dev@archlinux.org X-Mailman-Version: 2.1.34 Precedence: list List-Id: Discussion list for pacman development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Reply-To: Discussion list for pacman development Errors-To: pacman-dev-bounces@archlinux.org Sender: "pacman-dev" Authentication-Results: mail.archlinux.org; auth=pass smtp.auth=luna smtp.mailfrom=pacman-dev-bounces@archlinux.org --- lib/libalpm/alpm.h | 282 +++++++++++++++++++++++++++------------------ 1 file changed, 167 insertions(+), 115 deletions(-) diff --git a/lib/libalpm/alpm.h b/lib/libalpm/alpm.h index 178c8f6a..43a47d54 100644 --- a/lib/libalpm/alpm.h +++ b/lib/libalpm/alpm.h @@ -265,7 +265,7 @@ alpm_handle_t *alpm_initialize(const char *root, const char *dbpath, * This should be the last alpm call you make. * After this returns, handle should be considered invalid and cannot be reused * in any way. - * @param myhandle the context handle + * @param handle the context handle * @return 0 on success, -1 on error */ int alpm_release(alpm_handle_t *handle); @@ -275,6 +275,172 @@ int alpm_release(alpm_handle_t *handle); typedef int64_t alpm_time_t; +/** @addtogroup alpm_sig Signature checking + * @brief Functions to check signatures + * @{ + */ + +/** PGP signature verification options */ +typedef enum _alpm_siglevel_t { + /** Packages require a signature */ + ALPM_SIG_PACKAGE = (1 << 0), + /** Packages do not require a signature, + * but check packages that do have signatures */ + ALPM_SIG_PACKAGE_OPTIONAL = (1 << 1), + /* Allow packages with signatures that are marginal trust */ + ALPM_SIG_PACKAGE_MARGINAL_OK = (1 << 2), + /** Allow packages with signatues that are unknown trust */ + ALPM_SIG_PACKAGE_UNKNOWN_OK = (1 << 3), + + /** Databases require a signature */ + ALPM_SIG_DATABASE = (1 << 10), + /** Databases do not require a signature, + * but check databases that do have signatures */ + ALPM_SIG_DATABASE_OPTIONAL = (1 << 11), + /** Allow databases with signatures that are marginal trust */ + ALPM_SIG_DATABASE_MARGINAL_OK = (1 << 12), + /** Allow databases with signatues that are unknown trust */ + ALPM_SIG_DATABASE_UNKNOWN_OK = (1 << 13), + + /** The Default siglevel */ + ALPM_SIG_USE_DEFAULT = (1 << 30) +} alpm_siglevel_t; + +/** PGP signature verification status return codes */ +typedef enum _alpm_sigstatus_t { + /** Signature is valid */ + ALPM_SIGSTATUS_VALID, + /** The key has expired */ + ALPM_SIGSTATUS_KEY_EXPIRED, + /** The signature has expired */ + ALPM_SIGSTATUS_SIG_EXPIRED, + /** The key is not in the keyring */ + ALPM_SIGSTATUS_KEY_UNKNOWN, + /** The key has been disabled */ + ALPM_SIGSTATUS_KEY_DISABLED, + /** The signature is invalid */ + ALPM_SIGSTATUS_INVALID +} alpm_sigstatus_t; + + +/** The trust level of a PGP key */ +typedef enum _alpm_sigvalidity_t { + /** The signature is fully trusted */ + ALPM_SIGVALIDITY_FULL, + /** The signature is marginally trusted */ + ALPM_SIGVALIDITY_MARGINAL, + /** The signature is never trusted */ + ALPM_SIGVALIDITY_NEVER, + /** The signature has unknown trust */ + ALPM_SIGVALIDITY_UNKNOWN +} alpm_sigvalidity_t; + +/** A PGP key */ +typedef struct _alpm_pgpkey_t { + /** The actual key data */ + void *data; + /** The key's fingerprint */ + char *fingerprint; + /** UID of the key */ + char *uid; + /** Name of the key's owner */ + char *name; + /** Email of the key's owner */ + char *email; + /** When the key was created */ + alpm_time_t created; + /** When the key expires */ + alpm_time_t expires; + /** The length of the key */ + unsigned int length; + /** has the key been revoked */ + unsigned int revoked; + /** A character representing the encryption algorithm used by the public key + * + * ? = unknown + * R = RSA + * D = DSA + * E = EDDSA + */ + char pubkey_algo; +} alpm_pgpkey_t; + +/** + * Signature result. Contains the key, status, and validity of a given + * signature. + */ +typedef struct _alpm_sigresult_t { + /** The key of the signature */ + alpm_pgpkey_t key; + /** The status of the signature */ + alpm_sigstatus_t status; + /** The validity of the signature */ + alpm_sigvalidity_t validity; +} alpm_sigresult_t; + +/** + * Signature list. Contains the number of signatures found and a pointer to an + * array of results. The array is of size count. + */ +typedef struct _alpm_siglist_t { + /** The amount of results in the array */ + size_t count; + /** An array of sigresults */ + alpm_sigresult_t *results; +} alpm_siglist_t; + +/** + * Check the PGP signature for the given package file. + * @param pkg the package to check + * @param siglist a pointer to storage for signature results + * @return a int value : 0 (valid), 1 (invalid), -1 (an error occurred) + */ +int alpm_pkg_check_pgp_signature(alpm_pkg_t *pkg, alpm_siglist_t *siglist); + +/** + * Check the PGP signature for the given database. + * @param db the database to check + * @param siglist a pointer to storage for signature results + * @return a int value : 0 (valid), 1 (invalid), -1 (an error occurred) + */ +int alpm_db_check_pgp_signature(alpm_db_t *db, alpm_siglist_t *siglist); + +/** + * Clean up and free a signature result list. + * Note that this does not free the siglist object itself in case that + * was allocated on the stack; this is the responsibility of the caller. + * @param siglist a pointer to storage for signature results + * @return 0 on success, -1 on error + */ +int alpm_siglist_cleanup(alpm_siglist_t *siglist); + +/** + * Decode a loaded signature in base64 form. + * @param base64_data the signature to attempt to decode + * @param data the decoded data; must be freed by the caller + * @param data_len the length of the returned data + * @return 0 on success, -1 on failure to properly decode + */ +int alpm_decode_signature(const char *base64_data, + unsigned char **data, size_t *data_len); + +/** + * Extract the Issuer Key ID from a signature + * @param handle the context handle + * @param identifier the identifier of the key. + * This may be the name of the package or the path to the package. + * @param sig PGP signature + * @param len length of signature + * @param keys a pointer to storage for key IDs + * @return 0 on success, -1 on error + */ +int alpm_extract_keyid(alpm_handle_t *handle, const char *identifier, + const unsigned char *sig, const size_t len, alpm_list_t **keys); + +/* End of alpm_sig */ +/** @} */ + + /* * Enumerations * These ones are used in multiple contexts, so are forward-declared. @@ -330,39 +496,6 @@ typedef enum _alpm_fileconflicttype_t { ALPM_FILECONFLICT_FILESYSTEM } alpm_fileconflicttype_t; -/** PGP signature verification options */ -typedef enum _alpm_siglevel_t { - ALPM_SIG_PACKAGE = (1 << 0), - ALPM_SIG_PACKAGE_OPTIONAL = (1 << 1), - ALPM_SIG_PACKAGE_MARGINAL_OK = (1 << 2), - ALPM_SIG_PACKAGE_UNKNOWN_OK = (1 << 3), - - ALPM_SIG_DATABASE = (1 << 10), - ALPM_SIG_DATABASE_OPTIONAL = (1 << 11), - ALPM_SIG_DATABASE_MARGINAL_OK = (1 << 12), - ALPM_SIG_DATABASE_UNKNOWN_OK = (1 << 13), - - ALPM_SIG_USE_DEFAULT = (1 << 30) -} alpm_siglevel_t; - -/** PGP signature verification status return codes */ -typedef enum _alpm_sigstatus_t { - ALPM_SIGSTATUS_VALID, - ALPM_SIGSTATUS_KEY_EXPIRED, - ALPM_SIGSTATUS_SIG_EXPIRED, - ALPM_SIGSTATUS_KEY_UNKNOWN, - ALPM_SIGSTATUS_KEY_DISABLED, - ALPM_SIGSTATUS_INVALID -} alpm_sigstatus_t; - -/** PGP signature verification status return codes */ -typedef enum _alpm_sigvalidity_t { - ALPM_SIGVALIDITY_FULL, - ALPM_SIGVALIDITY_MARGINAL, - ALPM_SIGVALIDITY_NEVER, - ALPM_SIGVALIDITY_UNKNOWN -} alpm_sigvalidity_t; - /* * Structures */ @@ -428,39 +561,6 @@ typedef struct _alpm_backup_t { char *hash; } alpm_backup_t; -typedef struct _alpm_pgpkey_t { - void *data; - char *fingerprint; - char *uid; - char *name; - char *email; - alpm_time_t created; - alpm_time_t expires; - unsigned int length; - unsigned int revoked; - char pubkey_algo; -} alpm_pgpkey_t; - -/** - * Signature result. Contains the key, status, and validity of a given - * signature. - */ -typedef struct _alpm_sigresult_t { - alpm_pgpkey_t key; - alpm_sigstatus_t status; - alpm_sigvalidity_t validity; -} alpm_sigresult_t; - -/** - * Signature list. Contains the number of signatures found and a pointer to an - * array of results. The array is of size count. - */ -typedef struct _alpm_siglist_t { - size_t count; - alpm_sigresult_t *results; -} alpm_siglist_t; - - /* * Hooks */ @@ -1653,54 +1753,6 @@ int alpm_pkg_set_reason(alpm_pkg_t *pkg, alpm_pkgreason_t reason); */ alpm_file_t *alpm_filelist_contains(alpm_filelist_t *filelist, const char *path); -/* - * Signatures - */ - -/** - * Check the PGP signature for the given package file. - * @param pkg the package to check - * @param siglist a pointer to storage for signature results - * @return a int value : 0 (valid), 1 (invalid), -1 (an error occurred) - */ -int alpm_pkg_check_pgp_signature(alpm_pkg_t *pkg, alpm_siglist_t *siglist); - -/** - * Check the PGP signature for the given database. - * @param db the database to check - * @param siglist a pointer to storage for signature results - * @return a int value : 0 (valid), 1 (invalid), -1 (an error occurred) - */ -int alpm_db_check_pgp_signature(alpm_db_t *db, alpm_siglist_t *siglist); - -/** - * Clean up and free a signature result list. - * Note that this does not free the siglist object itself in case that - * was allocated on the stack; this is the responsibility of the caller. - * @param siglist a pointer to storage for signature results - * @return 0 on success, -1 on error - */ -int alpm_siglist_cleanup(alpm_siglist_t *siglist); - -/** - * Decode a loaded signature in base64 form. - * @param base64_data the signature to attempt to decode - * @param data the decoded data; must be freed by the caller - * @param data_len the length of the returned data - * @return 0 on success, -1 on failure to properly decode - */ -int alpm_decode_signature(const char *base64_data, - unsigned char **data, size_t *data_len); - -/** - * Extract the Issuer Key ID from a signature - * @param sig PGP signature - * @param len length of signature - * @param keys a pointer to storage for key IDs - * @return 0 on success, -1 on error - */ -int alpm_extract_keyid(alpm_handle_t *handle, const char *identifier, - const unsigned char *sig, const size_t len, alpm_list_t **keys); /* * Groups