Annotation of src/usr.bin/ssh/ssh_api.h, Revision 1.1
1.1 ! markus 1: /* $OpenBSD: $ */
! 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