-
Notifications
You must be signed in to change notification settings - Fork 8
/
working-with-secrets.md
244 lines (213 loc) · 7.2 KB
/
working-with-secrets.md
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
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
# Working with Secrets
As with most other objects, the REST API can be used to view, create, modify, and delete secrets. However, additional
steps are needed to encrypt or decrypt secret data.
## Generating a Session Key
In order to encrypt or decrypt secret data, a session key must be attached to the API request. To generate a session key,
send an authenticated request to the `/api/plugins/secrets/session-keys/` endpoint with the private RSA key which
matches your [UserKey](../models/userkey.md). Place the private RSA key in a json file.
```no-highlight
$ curl -X POST http://netbox/api/plugins/secrets/session-keys/ \
-H "Authorization: Token $TOKEN" \
-H "Accept: application/json; indent=4" \
-H "Content-Type: application/json" \
--data @<filename>
```
```json
{
"pk": 7,
"id": 7,
"url": "http://netbox/api/plugins/secrets/session-keys/7/",
"display": "admin (RSA)",
"userkey": {
"id": 1,
"url": "http://netbox/api/plugins/secrets/user-keys/1/",
"display": "admin"
},
"session_key": "4H8MCOl98qom7Ug5fQTzsFcH600SRWxe7KlUyIYxJ+A=",
"created": "2023-05-07T20:29:38.089884Z"
}
```
!!! note
To read the private key from a file, use the convention above. Alternatively, the private key can be read from an
environment variable using `--data "{\"private_key\": \"$PRIVATEKEY\"}"`.
Use the following CLI command to convert your PEM RSA key to json:
```no-highlight
jq -sR . <filename>
```
The request uses the provided private key to unlock your stored copy of the master key and generate a temporary
session key, which can be attached in the `X-Session-Key` header of future API requests.
### Depracated!
If you still want to use `application/x-www-form-urlencoded` you can use the **depracated** API endpoint
`http://netbox/api/plugins/secrets/get-session-key/`.
```no-highlight
curl -X POST https://netbox-test.tugraz.at/api/plugins/secrets/get-session-key/ \
-H "Authorization: Token $TOKEN" \
-H "Accept: application/json; indent=4" \
--data-urlencode "private_key@<filename>"
```
```json
{
"session_key": "4H8MCOl98qom7Ug5fQTzsFcH600SRWxe7KlUyIYxJ+A="
}
```
## Retrieving Secrets
A session key is not needed to retrieve unencrypted secrets: The secret is returned like any normal object with its
`plaintext` field set to null.
```no-highlight
$ curl http://netbox/api/plugins/secrets/secrets/2587/ \
-H "Authorization: Token $TOKEN" \
-H "Accept: application/json; indent=4"
```
```json
{
"id": 2587,
"url": "http://netbox/api/plugins/secrets/secrets/2587/",
"display": "admin",
"assigned_object_type": "dcim.device",
"assigned_object_id": 1827,
"assigned_object": {
"id": 1827,
"url": "http://netbox/api/dcim/devices/1827/",
"display": "MyTestDevice",
"name": "MyTestDevice"
},
"role": {
"id": 4,
"url": "http://netbox/api/plugins/secrets/secret-roles/4/",
"display": "Login Credentials",
"name": "Login Credentials",
"slug": "login-creds"
},
"name": "admin",
"plaintext": null,
"hash": "pbkdf2_sha256$1000$G6mMFe4FetZQ$f+0itZbAoUqW5pd8+NH8W5rdp/2QNLIBb+LGdt4OSKA=",
"tags": [],
"custom_fields": {},
"created": "2022-12-30T21:25:17.335575Z",
"last_updated": "2022-12-30T21:25:17.335619Z"
}
```
To decrypt a secret, we must include our session key in the `X-Session-Key` header when sending the `GET` request:
```no-highlight
$ curl http://netbox/api/plugins/secrets/secrets/secrets/2587/ \
-H "Authorization: Token $TOKEN" \
-H "Accept: application/json; indent=4" \
-H "X-Session-Key: dyEnxlc9lnGzaOAV1dV/xqYPV63njIbdZYOgnAlGPHk="
```
```json
{
"id": 2587,
"url": "http://netbox/api/plugins/secrets/secrets/2587/",
"display": "admin",
"assigned_object_type": "dcim.device",
"assigned_object_id": 1827,
"assigned_object": {
"id": 1827,
"url": "http://netbox/api/dcim/devices/1827/",
"display": "MyTestDevice",
"name": "MyTestDevice"
},
"role": {
"id": 4,
"url": "http://netbox/api/plugins/secrets/secret-roles/4/",
"display": "Login Credentials",
"name": "Login Credentials",
"slug": "login-creds"
},
"name": "admin",
"plaintext": null,
"hash": "pbkdf2_sha256$1000$G6mMFe4FetZQ$f+0itZbAoUqW5pd8+NH8W5rdp/2QNLIBb+LGdt4OSKA=",
"tags": [],
"custom_fields": {},
"created": "2022-12-30T21:25:17.335575Z",
"last_updated": "2022-12-30T21:25:17.335619Z"
}
```
Multiple secrets within a list can be decrypted in this manner as well:
```no-highlight
$ curl http://netbox/api/plugins/secrets/secrets/secrets/?limit=3 \
-H "Authorization: Token $TOKEN" \
-H "Accept: application/json; indent=4" \
-H "X-Session-Key: dyEnxlc9lnGzaOAV1dV/xqYPV63njIbdZYOgnAlGPHk="
```
```json
{
"count": 3482,
"next": "http://netbox/api/plugins/secrets/secrets/secrets/?limit=3&offset=3",
"previous": null,
"results": [
{
"id": 2587,
"plaintext": "foobar",
...
},
{
"id": 2588,
"plaintext": "MyP@ssw0rd!",
...
},
{
"id": 2589,
"plaintext": "AnotherSecret!",
...
},
]
}
```
To get a list of secrets from the assigned object
```no-highlight
$ curl http://netbox/api/plugins/secrets/secrets/secrets/?assigned_object_type=dcim.device&assigned_object_id=103 \
-H "Authorization: Token $TOKEN" \
-H "Accept: application/json; indent=4" \
-H "X-Session-Key: dyEnxlc9lnGzaOAV1dV/xqYPV63njIbdZYOgnAlGPHk="
```
```json
{
"count": 2,
"next": "http://netbox/api/plugins/secrets/secrets/secrets/?limit=3&offset=3",
"previous": null,
"results": [...]
}
```
## Creating and Updating Secrets
Session keys are required when creating or modifying secrets. The secret's `plaintext` attribute is set to its
non-encrypted value, and NetBox uses the session key to compute and store the encrypted value.
```no-highlight
$ curl -X POST http://netbox/api/secrets/secrets/ \
-H "Content-Type: application/json" \
-H "Authorization: Token $TOKEN" \
-H "Accept: application/json; indent=4" \
-H "X-Session-Key: dyEnxlc9lnGzaOAV1dV/xqYPV63njIbdZYOgnAlGPHk=" \
--data '{"assigned_object_id": 1827, "assigned_object_type": "dcim.device", "role": 1, "name": "backup", "plaintext": "Drowssap1"}'
```
```json
{
"id": 6194,
"url": "http://netbox/api/plugins/secrets/secrets/9194/",
"display": "admin",
"assigned_object_type": "dcim.device",
"assigned_object_id": 1827,
"assigned_object": {
"id": 1827,
"url": "http://netbox/api/dcim/devices/1827/",
"display": "device43",
"name": "device43"
},
"role": {
"id": 4,
"url": "http://netbox/api/plugins/secrets/secret-roles/4/",
"display": "Login Credentials",
"name": "Login Credentials",
"slug": "login-creds"
},
"name": "admin",
"plaintext": null,
"hash": "pbkdf2_sha256$1000$J9db8sI5vBrd$IK6nFXnFl+K+nR5/KY8RSDxU1skYL8G69T5N3jZxM7c=",
"tags": [],
"custom_fields": {},
"created": "2022-12-30T21:25:17.335575Z",
"last_updated": "2022-12-30T21:25:17.335619Z"
}
```
!!! note
Don't forget to include the `Content-Type: application/json` header when making a POST or PATCH request.