xref: /openssh-portable/ssh_api.h (revision 001aa554)
1 /* $OpenBSD: ssh_api.h,v 1.2 2018/04/10 00:10:49 djm Exp $ */
2 /*
3  * Copyright (c) 2012 Markus Friedl.  All rights reserved.
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 API_H
19 #define API_H
20 
21 #include <sys/types.h>
22 #include <signal.h>
23 
24 #include "openbsd-compat/sys-queue.h"
25 
26 #include "cipher.h"
27 #include "sshkey.h"
28 #include "kex.h"
29 #include "ssh.h"
30 #include "ssh2.h"
31 #include "packet.h"
32 
33 struct kex_params {
34 	char *proposal[PROPOSAL_MAX];
35 };
36 
37 /* public SSH API functions */
38 
39 /*
40  * ssh_init() create a ssh connection object with given (optional)
41  * key exchange parameters.
42  */
43 int	ssh_init(struct ssh **, int is_server, struct kex_params *kex_params);
44 
45 /*
46  * release ssh connection state.
47  */
48 void	ssh_free(struct ssh *);
49 
50 /*
51  * attach application specific data to the connection state
52  */
53 void	ssh_set_app_data(struct ssh *, void *);
54 void	*ssh_get_app_data(struct ssh *);
55 
56 /*
57  * ssh_add_hostkey() registers a private/public hostkey for an ssh
58  * connection.
59  * ssh_add_hostkey() needs to be called before a key exchange is
60  * initiated with ssh_packet_next().
61  * private hostkeys are required if we need to act as a server.
62  * public hostkeys are used to verify the servers hostkey.
63  */
64 int	ssh_add_hostkey(struct ssh *ssh, struct sshkey *key);
65 
66 /*
67  * ssh_set_verify_host_key_callback() registers a callback function
68  * which should be called instead of the default verification. The
69  * function given must return 0 if the hostkey is ok, -1 if the
70  * verification has failed.
71  */
72 int	ssh_set_verify_host_key_callback(struct ssh *ssh,
73     int (*cb)(struct sshkey *, struct ssh *));
74 
75 /*
76  * ssh_packet_next() advances to the next input packet and returns
77  * the packet type in typep.
78  * ssh_packet_next() works by processing an input byte-stream,
79  * decrypting the received data and hiding the key-exchange from
80  * the caller.
81  * ssh_packet_next() sets typep if there is no new packet available.
82  * in this case the caller must fill the input byte-stream by passing
83  * the data received over network to ssh_input_append().
84  * additionally, the caller needs to send the resulting output
85  * byte-stream back over the network. otherwise the key exchange
86  * would not proceed. the output byte-stream is accessed through
87  * ssh_output_ptr().
88  */
89 int	ssh_packet_next(struct ssh *ssh, u_char *typep);
90 
91 /*
92  * ssh_packet_payload() returns a pointer to the raw payload data of
93  * the current input packet and the length of this payload.
94  * the payload is accessible until ssh_packet_next() is called again.
95  */
96 const u_char	*ssh_packet_payload(struct ssh *ssh, size_t *lenp);
97 
98 /*
99  * ssh_packet_put() creates an encrypted packet with the given type
100  * and payload.
101  * the encrypted packet is appended to the output byte-stream.
102  */
103 int	ssh_packet_put(struct ssh *ssh, int type, const u_char *data,
104     size_t len);
105 
106 /*
107  * ssh_input_space() checks if 'len' bytes can be appended to the
108  * input byte-stream.
109  */
110 int	ssh_input_space(struct ssh *ssh, size_t len);
111 
112 /*
113  * ssh_input_append() appends data to the input byte-stream.
114  */
115 int	ssh_input_append(struct ssh *ssh, const u_char *data, size_t len);
116 
117 /*
118  * ssh_output_space() checks if 'len' bytes can be appended to the
119  * output byte-stream. XXX
120  */
121 int	ssh_output_space(struct ssh *ssh, size_t len);
122 
123 /*
124  * ssh_output_ptr() retrieves both a pointer and the length of the
125  * current output byte-stream. the bytes need to be sent over the
126  * network. the number of bytes that have been successfully sent can
127  * be removed from the output byte-stream with ssh_output_consume().
128  */
129 const u_char	*ssh_output_ptr(struct ssh *ssh, size_t *len);
130 
131 /*
132  * ssh_output_consume() removes the given number of bytes from
133  * the output byte-stream.
134  */
135 int	ssh_output_consume(struct ssh *ssh, size_t len);
136 
137 #endif
138