xref: /netbsd-src/crypto/external/bsd/openssh/dist/ssh_api.h (revision 55a4608bfb28648b44e8cc45a62c0d0da8dfb163)
1 /*	$NetBSD: ssh_api.h,v 1.5 2018/08/26 07:46:36 christos Exp $	*/
2 /* $OpenBSD: ssh_api.h,v 1.2 2018/04/10 00:10:49 djm Exp $ */
3 
4 /*
5  * Copyright (c) 2012 Markus Friedl.  All rights reserved.
6  *
7  * Permission to use, copy, modify, and distribute this software for any
8  * purpose with or without fee is hereby granted, provided that the above
9  * copyright notice and this permission notice appear in all copies.
10  *
11  * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
12  * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
13  * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
14  * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
15  * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
16  * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
17  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
18  */
19 
20 #ifndef API_H
21 #define API_H
22 
23 #include <sys/queue.h>
24 #include <sys/types.h>
25 #include <signal.h>
26 
27 #include "cipher.h"
28 #include "sshkey.h"
29 #include "kex.h"
30 #include "ssh.h"
31 #include "ssh2.h"
32 #include "packet.h"
33 
34 struct kex_params {
35 	char *proposal[PROPOSAL_MAX];
36 };
37 
38 /* public SSH API functions */
39 
40 /*
41  * ssh_init() create a ssh connection object with given (optional)
42  * key exchange parameters.
43  */
44 int	ssh_init(struct ssh **, int is_server, struct kex_params *kex_params);
45 
46 /*
47  * release ssh connection state.
48  */
49 void	ssh_free(struct ssh *);
50 
51 /*
52  * attach application specific data to the connection state
53  */
54 void	ssh_set_app_data(struct ssh *, void *);
55 void	*ssh_get_app_data(struct ssh *);
56 
57 /*
58  * ssh_add_hostkey() registers a private/public hostkey for an ssh
59  * connection.
60  * ssh_add_hostkey() needs to be called before a key exchange is
61  * initiated with ssh_packet_next().
62  * private hostkeys are required if we need to act as a server.
63  * public hostkeys are used to verify the servers hostkey.
64  */
65 int	ssh_add_hostkey(struct ssh *ssh, struct sshkey *key);
66 
67 /*
68  * ssh_set_verify_host_key_callback() registers a callback function
69  * which should be called instead of the default verification. The
70  * function given must return 0 if the hostkey is ok, -1 if the
71  * verification has failed.
72  */
73 int	ssh_set_verify_host_key_callback(struct ssh *ssh,
74     int (*cb)(struct sshkey *, struct ssh *));
75 
76 /*
77  * ssh_packet_next() advances to the next input packet and returns
78  * the packet type in typep.
79  * ssh_packet_next() works by processing an input byte-stream,
80  * decrypting the received data and hiding the key-exchange from
81  * the caller.
82  * ssh_packet_next() sets typep if there is no new packet available.
83  * in this case the caller must fill the input byte-stream by passing
84  * the data received over network to ssh_input_append().
85  * additionally, the caller needs to send the resulting output
86  * byte-stream back over the network. otherwise the key exchange
87  * would not proceed. the output byte-stream is accessed through
88  * ssh_output_ptr().
89  */
90 int	ssh_packet_next(struct ssh *ssh, u_char *typep);
91 
92 /*
93  * ssh_packet_payload() returns a pointer to the raw payload data of
94  * the current input packet and the length of this payload.
95  * the payload is accessible until ssh_packet_next() is called again.
96  */
97 const u_char	*ssh_packet_payload(struct ssh *ssh, size_t *lenp);
98 
99 /*
100  * ssh_packet_put() creates an encrypted packet with the given type
101  * and payload.
102  * the encrypted packet is appended to the output byte-stream.
103  */
104 int	ssh_packet_put(struct ssh *ssh, int type, const u_char *data,
105     size_t len);
106 
107 /*
108  * ssh_input_space() checks if 'len' bytes can be appended to the
109  * input byte-stream.
110  */
111 int	ssh_input_space(struct ssh *ssh, size_t len);
112 
113 /*
114  * ssh_input_append() appends data to the input byte-stream.
115  */
116 int	ssh_input_append(struct ssh *ssh, const u_char *data, size_t len);
117 
118 /*
119  * ssh_output_space() checks if 'len' bytes can be appended to the
120  * output byte-stream. XXX
121  */
122 int	ssh_output_space(struct ssh *ssh, size_t len);
123 
124 /*
125  * ssh_output_ptr() retrieves both a pointer and the length of the
126  * current output byte-stream. the bytes need to be sent over the
127  * network. the number of bytes that have been successfully sent can
128  * be removed from the output byte-stream with ssh_output_consume().
129  */
130 const u_char	*ssh_output_ptr(struct ssh *ssh, size_t *len);
131 
132 /*
133  * ssh_output_consume() removes the given number of bytes from
134  * the output byte-stream.
135  */
136 int	ssh_output_consume(struct ssh *ssh, size_t len);
137 
138 #endif
139