1 /*
2   Copyright 2021 Northern.tech AS
3 
4   This file is part of CFEngine 3 - written and maintained by Northern.tech AS.
5 
6   This program is free software; you can redistribute it and/or modify it
7   under the terms of the GNU General Public License as published by the
8   Free Software Foundation; version 3.
9 
10   This program is distributed in the hope that it will be useful,
11   but WITHOUT ANY WARRANTY; without even the implied warranty of
12   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13   GNU General Public License for more details.
14 
15   You should have received a copy of the GNU General Public License
16   along with this program; if not, write to the Free Software
17   Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA
18 
19   To the extent this program is licensed as part of the Enterprise
20   versions of CFEngine, the applicable Commercial Open Source License
21   (COSL) may apply to this file if you as a licensee so wish it. See
22   included file COSL.txt.
23 */
24 
25 #ifndef CONNECTION_INFO_H
26 #define CONNECTION_INFO_H
27 
28 
29 #include <platform.h>
30 
31 #include <openssl/ssl.h>
32 
33 #include <key.h>
34 
35 
36 /**
37   @brief ConnectionInfo Structure and support routines
38 
39   ConnectionInfo is used to abstract the underlying type of connection from our protocol implementation.
40   It can hold both a normal socket connection and a TLS stream.
41  */
42 
43 
44 /**
45  * @brief Status of the connection, for the connection cache and for
46  *        propagating errors up in function callers.
47  */
48 typedef enum
49 {
50     CONNECTIONINFO_STATUS_NOT_ESTABLISHED,
51     CONNECTIONINFO_STATUS_ESTABLISHED,
52     /* used to propagate connection errors up in function calls */
53     CONNECTIONINFO_STATUS_BROKEN
54     /* TODO ESTABLISHED==IDLE, BUSY, OFFLINE */
55 } ConnectionStatus;
56 
57 struct ConnectionInfo {
58     ProtocolVersion protocol;
59     ConnectionStatus status;
60     int sd;                           /* Socket descriptor */
61     SSL *ssl;                         /* OpenSSL struct for TLS connections */
62     Key *remote_key;
63     socklen_t ss_len;
64     struct sockaddr_storage ss;
65     bool is_call_collect;       /* Maybe replace with a bitfield later ... */
66 };
67 
68 typedef struct ConnectionInfo ConnectionInfo;
69 
70 
71 /**
72   @brief Creates a new ConnectionInfo structure.
73   @return A initialized ConnectionInfo structure, needs to be populated.
74   */
75 ConnectionInfo *ConnectionInfoNew(void);
76 
77 /**
78   @brief Destroys a ConnectionInfo structure.
79   @param info Pointer to the ConectionInfo structure to be destroyed.
80   */
81 void ConnectionInfoDestroy(ConnectionInfo **info);
82 
83 /**
84   @brief Protocol Version
85   @param info ConnectionInfo structure
86   @return Returns the protocol version or CF_PROTOCOL_UNDEFINED in case of error.
87   */
88 ProtocolVersion ConnectionInfoProtocolVersion(const ConnectionInfo *info);
89 
90 /**
91   @brief Sets the protocol version
92 
93   Notice that if an invalid protocol version is passed, the value will not be changed.
94   @param info ConnectionInfo structure.
95   @param version New protocol version
96   */
97 void ConnectionInfoSetProtocolVersion(ConnectionInfo *info, ProtocolVersion version);
98 
99 /**
100   @brief Connection socket
101 
102   For practical reasons there is no difference between an invalid socket and an error on this routine.
103   @param info ConnectionInfo structure.
104   @return Returns the connection socket or -1 in case of error.
105   */
106 int ConnectionInfoSocket(const ConnectionInfo *info);
107 
108 /**
109   @brief Sets the connection socket.
110   @param info ConnectionInfo structure.
111   @param s New connection socket.
112   */
113 void ConnectionInfoSetSocket(ConnectionInfo *info, int s);
114 
115 /**
116   @brief SSL structure.
117   @param info ConnectionInfo structure.
118   @return The SSL structure attached to this connection or NULL in case of error.
119   */
120 SSL *ConnectionInfoSSL(const ConnectionInfo *info);
121 
122 /**
123   @brief Sets the SSL structure.
124   @param info ConnectionInfo structure.
125   @param ssl SSL structure to attached to this connection.
126   */
127 void ConnectionInfoSetSSL(ConnectionInfo *info, SSL *ssl);
128 
129 /**
130   @brief RSA key
131   @param info ConnectionInfo structure.
132   @return Returns the RSA key or NULL in case of error.
133   */
134 const Key *ConnectionInfoKey(const ConnectionInfo *info);
135 
136 /**
137   @brief Sets the key for the connection structure.
138 
139   This triggers a calculation of two other fields.
140   @param info ConnectionInfo structure.
141   @param key RSA key.
142   */
143 void ConnectionInfoSetKey(ConnectionInfo *info, Key *key);
144 
145 /**
146   @brief A constant pointer to the binary hash of the key
147   @param info ConnectionInfo structure
148   @param length Length of the hash
149   @return Returns a constant pointer to the binary hash and if length is not NULL the size is stored there.
150   */
151 const unsigned char *ConnectionInfoBinaryKeyHash(ConnectionInfo *info, unsigned int *length);
152 
153 /**
154   @brief A constant pointer to the binary hash of the key
155   @param info ConnectionInfo structure
156   @return Returns a printable representation of the hash. The string is '\0' terminated or NULL in case of failure.
157   */
158 const char *ConnectionInfoPrintableKeyHash(ConnectionInfo *info);
159 
160 
161 #endif // CONNECTION_INFO_H
162