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