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