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