ssh_api.h revision 295367 
1/* $OpenBSD: ssh_api.h,v 1.1 2015/01/19 20:30:23 markus 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
33struct 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 */
43int	ssh_init(struct ssh **, int is_server, struct kex_params *kex_params);
44
45/*
46 * release ssh connection state.
47 */
48void	ssh_free(struct ssh *);
49
50/*
51 * attach application specific data to the connection state
52 */
53void	ssh_set_app_data(struct ssh *, void *);
54void	*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 */
64int	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 */
72int	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 * additinally, 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 */
89int	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 */
96const 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 */
103int	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 */
110int	ssh_input_space(struct ssh *ssh, size_t len);
111
112/*
113 * ssh_input_append() appends data to the input byte-stream.
114 */
115int	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 */
121int	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 */
129const 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 */
135int	ssh_output_consume(struct ssh *ssh, size_t len);
136
137#endif
138