include/git2/cert.h

   1 /*
   2  * Copyright (C) the libgit2 contributors. All rights reserved.
   3  *
   4  * This file is part of libgit2, distributed under the GNU GPL v2 with
   5  * a Linking Exception. For full terms see the included COPYING file.
   6  */
   7 #ifndef INCLUDE_git_cert_h__
   8 #define INCLUDE_git_cert_h__
   9
  10 #include "common.h"
  11 #include "types.h"
  12
  13 /**
  14  * @file git2/cert.h
  15  * @brief Git certificate objects
  16  * @defgroup git_cert Certificate objects
  17  * @ingroup Git
  18  * @{
  19  */
  20 GIT_BEGIN_DECL
  21
  22 /**
  23  * Type of host certificate structure that is passed to the check callback
  24  */
  25 typedef enum git_cert_t {
  26         /**
  27          * No information about the certificate is available. This may
  28          * happen when using curl.
  29          */
  30         GIT_CERT_NONE,
  31         /**
  32          * The `data` argument to the callback will be a pointer to
  33          * the DER-encoded data.
  34          */
  35         GIT_CERT_X509,
  36         /**
  37          * The `data` argument to the callback will be a pointer to a
  38          * `git_cert_hostkey` structure.
  39          */
  40         GIT_CERT_HOSTKEY_LIBSSH2,
  41         /**
  42          * The `data` argument to the callback will be a pointer to a
  43          * `git_strarray` with `name:content` strings containing
  44          * information about the certificate. This is used when using
  45          * curl.
  46          */
  47         GIT_CERT_STRARRAY,
  48 } git_cert_t;
  49
  50 /**
  51  * Parent type for `git_cert_hostkey` and `git_cert_x509`.
  52  */
  53 struct git_cert {
  54         /**
  55          * Type of certificate. A `GIT_CERT_` value.
  56          */
  57         git_cert_t cert_type;
  58 };
  59
  60 /**
  61  * Callback for the user's custom certificate checks.
  62  *
  63  * @param cert The host certificate
  64  * @param valid Whether the libgit2 checks (OpenSSL or WinHTTP) think
  65  * this certificate is valid
  66  * @param host Hostname of the host libgit2 connected to
  67  * @param payload Payload provided by the caller
  68  * @return 0 to proceed with the connection, < 0 to fail the connection
  69  *         or > 0 to indicate that the callback refused to act and that
  70  *         the existing validity determination should be honored
  71  */
  72 typedef int GIT_CALLBACK(git_transport_certificate_check_cb)(git_cert *cert, int valid, const char *host, void *payload);
  73
  74 /**
  75  * Type of SSH host fingerprint
  76  */
  77 typedef enum {
  78         /** MD5 is available */
  79         GIT_CERT_SSH_MD5 = (1 << 0),
  80         /** SHA-1 is available */
  81         GIT_CERT_SSH_SHA1 = (1 << 1),
  82         /** SHA-256 is available */
  83         GIT_CERT_SSH_SHA256 = (1 << 2),
  84         /** Raw hostkey is available */
  85         GIT_CERT_SSH_RAW = (1 << 3),
  86 } git_cert_ssh_t;
  87
  88 typedef enum {
  89         /** The raw key is of an unknown type. */
  90         GIT_CERT_SSH_RAW_TYPE_UNKNOWN = 0,
  91         /** The raw key is an RSA key. */
  92         GIT_CERT_SSH_RAW_TYPE_RSA = 1,
  93         /** The raw key is a DSS key. */
  94         GIT_CERT_SSH_RAW_TYPE_DSS = 2,
  95         /** The raw key is a ECDSA 256 key. */
  96         GIT_CERT_SSH_RAW_TYPE_KEY_ECDSA_256 = 3,
  97         /** The raw key is a ECDSA 384 key. */
  98         GIT_CERT_SSH_RAW_TYPE_KEY_ECDSA_384 = 4,
  99         /** The raw key is a ECDSA 521 key. */
 100         GIT_CERT_SSH_RAW_TYPE_KEY_ECDSA_521 = 5,
 101         /** The raw key is a ED25519 key. */
 102         GIT_CERT_SSH_RAW_TYPE_KEY_ED25519 = 6
 103 } git_cert_ssh_raw_type_t;
 104
 105 /**
 106  * Hostkey information taken from libssh2
 107  */
 108 typedef struct {
 109         git_cert parent; /**< The parent cert */
 110
 111         /**
 112          * A bitmask containing the available fields.
 113          */
 114         git_cert_ssh_t type;
 115
 116         /**
 117          * Hostkey hash. If `type` has `GIT_CERT_SSH_MD5` set, this will
 118          * have the MD5 hash of the hostkey.
 119          */
 120         unsigned char hash_md5[16];
 121
 122         /**
 123          * Hostkey hash. If `type` has `GIT_CERT_SSH_SHA1` set, this will
 124          * have the SHA-1 hash of the hostkey.
 125          */
 126         unsigned char hash_sha1[20];
 127
 128         /**
 129          * Hostkey hash. If `type` has `GIT_CERT_SSH_SHA256` set, this will
 130          * have the SHA-256 hash of the hostkey.
 131          */
 132         unsigned char hash_sha256[32];
 133
 134         /**
 135          * Raw hostkey type. If `type` has `GIT_CERT_SSH_RAW` set, this will
 136          * have the type of the raw hostkey.
 137          */
 138         git_cert_ssh_raw_type_t raw_type;
 139
 140         /**
 141          * Pointer to the raw hostkey. If `type` has `GIT_CERT_SSH_RAW` set,
 142          * this will have the raw contents of the hostkey.
 143          */
 144         const char *hostkey;
 145
 146         /**
 147          * Raw hostkey length. If `type` has `GIT_CERT_SSH_RAW` set, this will
 148          * have the length of the raw contents of the hostkey.
 149          */
 150         size_t hostkey_len;
 151 } git_cert_hostkey;
 152
 153 /**
 154  * X.509 certificate information
 155  */
 156 typedef struct {
 157         git_cert parent; /**< The parent cert */
 158
 159         /**
 160          * Pointer to the X.509 certificate data
 161          */
 162         void *data;
 163
 164         /**
 165          * Length of the memory block pointed to by `data`.
 166          */
 167         size_t len;
 168 } git_cert_x509;
 169
 170 /** @} */
 171 GIT_END_DECL
 172 #endif