1/* $OpenBSD: sshsig.h,v 1.11 2021/11/27 07:14:46 djm Exp $ */ 2/* 3 * Copyright (c) 2019 Google LLC 4 * 5 * Permission to use, copy, modify, and distribute this software for any 6 * purpose with or without fee is hereby granted, provided that the above 7 * copyright notice and this permission notice appear in all copies. 8 * 9 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12 * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16 */ 17 18#ifndef SSHSIG_H 19#define SSHSIG_H 20 21struct sshbuf; 22struct sshkey; 23struct sshsigopt; 24struct sshkey_sig_details; 25 26typedef int sshsig_signer(struct sshkey *, u_char **, size_t *, 27 const u_char *, size_t, const char *, const char *, const char *, 28 u_int, void *); 29 30/* Buffer-oriented API */ 31 32/* 33 * Creates a detached SSH signature for a given buffer. 34 * Returns 0 on success or a negative SSH_ERR_* error code on failure. 35 * out is populated with the detached signature, or NULL on failure. 36 */ 37int sshsig_signb(struct sshkey *key, const char *hashalg, 38 const char *sk_provider, const char *sk_pin, const struct sshbuf *message, 39 const char *sig_namespace, struct sshbuf **out, 40 sshsig_signer *signer, void *signer_ctx); 41 42/* 43 * Verifies that a detached signature is valid and optionally returns key 44 * used to sign via argument. 45 * Returns 0 on success or a negative SSH_ERR_* error code on failure. 46 */ 47int sshsig_verifyb(struct sshbuf *signature, 48 const struct sshbuf *message, const char *sig_namespace, 49 struct sshkey **sign_keyp, struct sshkey_sig_details **sig_details); 50 51/* File/FD-oriented API */ 52 53/* 54 * Creates a detached SSH signature for a given file. 55 * Returns 0 on success or a negative SSH_ERR_* error code on failure. 56 * out is populated with the detached signature, or NULL on failure. 57 */ 58int sshsig_sign_fd(struct sshkey *key, const char *hashalg, 59 const char *sk_provider, const char *sk_pin, 60 int fd, const char *sig_namespace, 61 struct sshbuf **out, sshsig_signer *signer, void *signer_ctx); 62 63/* 64 * Verifies that a detached signature over a file is valid and optionally 65 * returns key used to sign via argument. 66 * Returns 0 on success or a negative SSH_ERR_* error code on failure. 67 */ 68int sshsig_verify_fd(struct sshbuf *signature, int fd, 69 const char *sig_namespace, struct sshkey **sign_keyp, 70 struct sshkey_sig_details **sig_details); 71 72/* Utility functions */ 73 74/* 75 * Return a base64 encoded "ASCII armoured" version of a raw signature. 76 */ 77int sshsig_armor(const struct sshbuf *blob, struct sshbuf **out); 78 79/* 80 * Decode a base64 encoded armoured signature to a raw signature. 81 */ 82int sshsig_dearmor(struct sshbuf *sig, struct sshbuf **out); 83 84/* 85 * Checks whether a particular key/principal/namespace is permitted by 86 * an allowed_keys file. Returns 0 on success. 87 */ 88int sshsig_check_allowed_keys(const char *path, const struct sshkey *sign_key, 89 const char *principal, const char *ns, uint64_t verify_time); 90 91/* Parse zero or more allowed_keys signature options */ 92struct sshsigopt *sshsigopt_parse(const char *opts, 93 const char *path, u_long linenum, const char **errstrp); 94 95/* Free signature options */ 96void sshsigopt_free(struct sshsigopt *opts); 97 98/* Get public key from signature */ 99int sshsig_get_pubkey(struct sshbuf *signature, struct sshkey **pubkey); 100 101/* Find principal in allowed_keys file, given a sshkey. Returns 102 * 0 on success. 103 */ 104int sshsig_find_principals(const char *path, const struct sshkey *sign_key, 105 uint64_t verify_time, char **principal); 106 107/* Find all principals in allowed_keys file matching *principal */ 108int sshsig_match_principals(const char *path, 109 const char *principal, char ***principalsp, size_t *nprincipalsp); 110 111#endif /* SSHSIG_H */ 112