hiba/extensions.h at main · xw-g/hiba · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
/*
 * Copyright 2021 The HIBA Authors
 *
 * Use of this source code is governed by a BSD-style
 * license that can be found in the LICENSE file or at
 * https://developers.google.com/open-source/licenses/bsd
 */
#ifndef _EXTENSIONS_H
#define _EXTENSIONS_H

#include <sys/types.h>

#include "sshbuf.h"

/* HIBA extensions magic header. */
#define HIBA_MAGIC 0x48494241

/* Base64 encoded HIBA extensions magic header.
 * Result of encoding the HIBA_MAGIC to base64. Marks the begining of a base64
 * encoded extension. */
#define HIBA_B64_MAGIC  0x53456c43

/* Multi HIBA extension magic marker.
 * Used to flag that the extension contains multiple raw HIBA grants. */
#define HIBA_MULTI_EXTS 0x4d554c54

/* HIBA extension types. */
#define HIBA_IDENTITY_EXT 'i'
#define HIBA_GRANT_EXT 'g'

/* HIBA Extensions IDs. */
#define HIBA_IDENTITY_ID "identity@hibassh.dev"
#define HIBA_GRANT_ID "grant@hibassh.dev"

/* HIBA pre defined options. */
#define HIBA_KEY_DOMAIN "domain"
#define HIBA_KEY_ROLE "role"
#define HIBA_KEY_VALIDITY "validity"
#define HIBA_KEY_HOSTNAME "hostname"
#define HIBA_KEY_OPTIONS "options"

/* HIBA key modifier for negative matching constraints. */
#define HIBA_NEGATIVE_MATCHING '!'

/* HIBA extension type. */
struct hibaext;

/* Constructor for hibaext.
 * Result must be freed with hibaext_free. */
struct hibaext *hibaext_new();

/* Init a new hibaext for a given type (grant or identity).
 * The hibaext must already be allocated. */
int hibaext_init(struct hibaext *ext, int type);

/* Destructor for hibaext.
 * This releases all the memory used by the key/pairs as well as the extension
 * structure itself.  */
void hibaext_free(struct hibaext *ext);

/* Decode a serialized HIBA extension contained into a manageable object.
 * The struct hibaext must be already allocated.
 * The sshbuf will be consumed. */
int hibaext_decode(struct hibaext *ext, struct sshbuf *blob);

/* Encode one or more HIBA extensions into a serialized blob to be included in a
 * certificate (either raw or base64 encoded).
 * blob must be already allocated, and will be reset.
 * It is invalid to request encoding of more than 1 identity extension, since a
 * host cannot expose multiple identities.
 *
 * The default hibaext_encode points to the base64 version, uncompressed single
 * extension for backward compatibility. */
int hibaext_encode(const struct hibaext *ext, struct sshbuf *blob);
int hibaext_encode_raw(const struct hibaext **ext, int count, int compress, struct sshbuf *blob);
int hibaext_encode_b64(const struct hibaext **ext, int count, int compress, struct sshbuf *blob);

/* Sanity check a HIBA extension.
 * This verifies the following
 * - extension type is known
 * - extension contains the required 'domain' key/pair
 * - if the extension type is identity, it doesn't contain reserved keys
 *   (validity, hostname, role, options), or negative keys.
 * - if the 'validity' key is set, it must be an integer greated than 0, and
 *   cannot be set as negative matching.
 * - identity extensions don't have duplicate keys
 * - if the 'options' key is set, it must not contain \n or unquoted
 *   whitespaces, and open quotes must be closed, and cannot be set as negative
 *   matching
 */
int hibaext_sanity_check(const struct hibaext *ext);

/* Return the extension ID corresponding to the type:
 * "grant@hibassh.dev"
 * "identity@hibassh.dev" */
const char *hibaext_id(const struct hibaext *ext);

/* Return the extension type. */
u_int32_t hibaext_type(const struct hibaext *ext);

/* Return the extension version and minimum supported version. */
int hibaext_versions(const struct hibaext *ext, u_int32_t *vers,
                     u_int32_t *min_vers);

/* Return the number of key value pairs attached to the hibaext. */
u_int32_t hibaext_pairs_len(const struct hibaext *ext);

/* Return the key and value stored at a given position.
 * If the requested position is out of the key/pair list bounds, HIBA_BAD_PARAMS
 * is returned.
 * Both the returned key and value must be freed. */
int hibaext_key_value_at(const struct hibaext *ext, u_int32_t position,
                         char **key, char **value);

/* Return the value for a given key in an identity extension.
 * This function doesn't apply to extensions with type grant as they can have
 * multiple values with the same key. For grants please use the
 * hibaext_key_value_at() function instead.
 * If the requested key doesn't exist, HIBA_EXT_NOKEY is returned.
 * The returned value must be freed. */
int hibaext_value_for_key(const struct hibaext *ext, const char *key,
                          char **value);

/* Add a key value pair to the hibaext.
 * If the key already exists, HIBA_PAIR_EXISTS is returned. */
int hibaext_add_pair(struct hibaext *ext, const char *key, const char *value);

/* Update an existing key value pair attached to the hibaext. */
int hibaext_update_pair(struct hibaext *ext, const char *key,
                        const char *value);

#endif /* _EXTENSIONS_H */