crypto/openssh/ssh_api.h

   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