/
doc.go
630 lines (495 loc) · 24.3 KB
/
doc.go
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
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
// Copyright 2018 The Vanadium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
// This file was auto-generated via go generate.
// DO NOT UPDATE MANUALLY
/*
Command principal creates and manages Vanadium principals and blessings.
All objects are printed using base64url-vom-encoding.
Usage:
principal [flags] <command>
The principal commands are:
create Create a new principal and persist it into a directory
fork Fork a new principal from the principal that this tool is
running as and persist it into a directory
seekblessings Seek blessings from a web-based Vanadium blessing service
recvblessings Receive blessings sent by another principal and use them as the
default
dump Dump out information about the principal
dumpblessings Dump out information about the provided blessings
dumproots Dump out blessings of the identity providers of blessings
blessself Generate a self-signed blessing
bless Bless another principal
set Mutate the principal's blessings.
get Read the principal's blessings.
recognize Add to the set of identity providers recognized by this
principal
union Merge multiple blessings into one
help Display help for commands or topics
The global flags are:
-alsologtostderr=true
log to standard error as well as files
-log_backtrace_at=:0
when logging hits line file:N, emit a stack trace
-log_dir=
if non-empty, write log files to this directory
-logtostderr=false
log to standard error instead of files
-max_stack_buf_size=4292608
max size in bytes of the buffer to use for logging stack traces
-metadata=<just specify -metadata to activate>
Displays metadata for the program and exits.
-stderrthreshold=2
logs at or above this threshold go to stderr
-time=false
Dump timing information to stderr before exiting the program.
-v=0
log level for V logs
-v23.credentials=
directory to use for storing security credentials
-v23.namespace.root=[/(dev.v.io:r:vprod:service:mounttabled)@ns.dev.v.io:8101]
local namespace root; can be repeated to provided multiple roots
-v23.permissions.file=
specify a perms file as <name>:<permsfile>
-v23.permissions.literal=
explicitly specify the runtime perms as a JSON-encoded access.Permissions.
Overrides all --v23.permissions.file flags
-v23.proxy=
object name of proxy service to use to export services across network
boundaries
-v23.proxy.limit=0
max number of proxies to connect to when the policy is to connect to all
proxies; 0 implies all proxies
-v23.proxy.policy=
policy for choosing from a set of available proxy instances
-v23.tcp.address=
address to listen on
-v23.tcp.protocol=
protocol to listen with
-v23.virtualized.advertise-private-addresses=
if set the process will also advertise its private addresses
-v23.virtualized.disallow-native-fallback=false
if set, a failure to detect the requested virtualization provider will result
in an error, otherwise, native mode is used
-v23.virtualized.dns.public-name=
if set the process will use the supplied dns name (and port) without
resolution for its entry in the mounttable
-v23.virtualized.docker=
set if the process is running in a docker container and needs to configure
itself differently therein
-v23.virtualized.provider=
the name of the virtualization/cloud provider hosting this process if the
process needs to configure itself differently therein
-v23.virtualized.tcp.public-address=
if set the process will use this address (resolving via dns if appropriate)
for its entry in the mounttable
-v23.virtualized.tcp.public-protocol=
if set the process will use this protocol for its entry in the mounttable
-v23.vtrace.cache-size=1024
The number of vtrace traces to store in memory
-v23.vtrace.collect-regexp=
Spans and annotations that match this regular expression will trigger trace
collection
-v23.vtrace.dump-on-shutdown=true
If true, dump all stored traces on runtime shutdown
-v23.vtrace.enable-aws-xray=false
Enable the use of AWS x-ray integration with vtrace
-v23.vtrace.sample-rate=0
Rate (from 0.0 to 1.0) to sample vtrace traces
-v23.vtrace.v=0
The verbosity level of the log messages to be captured in traces
-vmodule=
comma-separated list of globpattern=N settings for filename-filtered logging
(without the .go suffix). E.g. foo/bar/baz.go is matched by patterns baz or
*az or b* but not by bar/baz or baz.go or az or b.*
-vpath=
comma-separated list of regexppattern=N settings for file pathname-filtered
logging (without the .go suffix). E.g. foo/bar/baz.go is matched by patterns
foo/bar/baz or fo.*az or oo/ba or b.z but not by foo/bar/baz.go or fo*az
Principal create - Create a new principal and persist it into a directory
Creates a new principal with a single optional self-blessed blessing and writes
it out to the provided directory. The same directory can then be used to set the
V23_CREDENTIALS environment variable for other vanadium applications.
The operation fails if the directory already contains a principal. In this case
the --overwrite flag can be provided to clear the directory and write out the
new principal.
Usage:
principal create [flags] <directory> [<blessing>]
<directory> is the directory to which the new principal will be persisted.
<blessing> is the optional self-blessed blessing that the principal will be
setup to use by default. If a blessing argument is not provided, the new
principal will have no blessings.
The principal create flags are:
-key-type=ecdsa256
The type of key to be created, allowed values are ecdsa256, ecdsa384,
ecdsa521, ed25519.
-overwrite=false
If true, any existing principal data in the directory will be overwritten
-ssh-public-key=
If set, use the key hosted by the accessible ssh-agent that corresponds to
the specified public key file.
-with-passphrase=true
If true, the user is prompted for a passphrase to encrypt the principal.
Otherwise, the principal is stored unencrypted.
Principal fork - Fork a new principal from the principal that this tool is running as and persist it into a directory
Creates a new principal with a blessing from the principal specified by the
environment that this tool is running in, and writes it out to the provided
directory. The blessing that will be extended is the default one from the
blesser's store, or specified by the --with flag. Expiration on the blessing are
controlled via the --for flag. Additional caveats on the blessing are controlled
with the --caveat flag. The blessing is marked as default and shareable with all
peers on the new principal's blessing store.
The operation fails if the directory already contains a principal. In this case
the --overwrite flag can be provided to clear the directory and write out the
forked principal.
Usage:
principal fork [flags] <directory> <extension>
<directory> is the directory to which the forked principal will be persisted.
<extension> is the extension under which the forked principal is blessed.
The principal fork flags are:
-caveat=
"package/path".CaveatName:VDLExpressionParam to attach to this blessing
-for=0s
Duration of blessing validity (zero implies no expiration)
-key-type=ecdsa256
The type of key to be created, allowed values are ecdsa256, ecdsa384,
ecdsa521, ed25519.
-overwrite=false
If true, any existing principal data in the directory will be overwritten
-require-caveats=true
If false, allow blessing without any caveats. This is typically not advised
as the principal wielding the blessing will be almost as powerful as its
blesser
-ssh-public-key=
If set, use the key hosted by the accessible ssh-agent that corresponds to
the specified public key file.
-with=
Path to file containing blessing to extend
-with-passphrase=true
If true, the user is prompted for a passphrase to encrypt the principal.
Otherwise, the principal is stored unencrypted.
Principal seekblessings - Seek blessings from a web-based Vanadium blessing service
Seeks blessings from a web-based Vanadium blesser which requires the caller to
first authenticate with Google using OAuth. Simply run the command to see what
happens.
The blessings are sought for the principal specified by the environment that
this tool is running in.
The blessings obtained are set as default unless the --set-default flag is set
to false, and are also set for sharing with all peers unless a more specific
peer pattern is provided using the --for-peer flag.
Usage:
principal seekblessings [flags]
The principal seekblessings flags are:
-add-to-roots=true
If true, the root certificate of the blessing will be added to the
principal's set of recognized root certificates
-browser=true
If false, the seekblessings command will not open the browser and only print
the url to visit.
-for-peer=...
If non-empty, the blessings obtained will be marked for peers matching this
pattern in the store
-from=https://dev.v.io/auth/google
URL to use to begin the seek blessings process
-set-default=true
If true, the blessings received will be set as the default blessing in the
store
Principal recvblessings - Receive blessings sent by another principal and use them as the default
Allow another principal (likely a remote process) to bless this one.
This command sets up the invoker (this process) to wait for a blessing from
another invocation of this tool (remote process) and prints out the command to
be run as the remote principal.
The received blessings are set as default unless the --set-default flag is set
to false, and are also set for sharing with all peers unless a more specific
peer pattern is provided using the --for-peer flag.
TODO(ashankar,cnicolaou): Make this next paragraph possible! Requires the
ability to obtain the proxied endpoint.
Typically, this command should require no arguments. However, if the sender and
receiver are on different network domains, it may make sense to use the
--v23.proxy flag:
principal --v23.proxy=proxy recvblessings
The command to be run at the sender is of the form:
principal bless --remote-key=KEY --remote-token=TOKEN ADDRESS EXTENSION
The --remote-key flag is used to by the sender to "authenticate" the receiver,
ensuring it blesses the intended recipient and not any attacker that may have
taken over the address.
The --remote-token flag is used by the sender to authenticate itself to the
receiver. This helps ensure that the receiver rejects blessings from senders who
just happened to guess the network address of the 'recvblessings' invocation.
If the --remote-arg-file flag is provided to recvblessings, the remote key,
remote token and object address of this principal will be written to the
specified location. This file can be supplied to bless:
principal bless --remote-arg-file FILE EXTENSION
Usage:
principal recvblessings [flags]
The principal recvblessings flags are:
-for-peer=...
If non-empty, the blessings obtained will be marked for peers matching this
pattern in the store
-remote-arg-file=
If non-empty, the remote key, remote token, and principal will be written to
the specified file in a JSON object. This can be provided to 'principal bless
--remote-arg-file FILE EXTENSION'
-set-default=true
If true, the blessings received will be set as the default blessing in the
store
Principal dump - Dump out information about the principal
Prints out information about the principal specified by the environment that
this tool is running in.
Usage:
principal dump [flags]
The principal dump flags are:
-s=false
If true, show only the default blessing names
Principal dumpblessings - Dump out information about the provided blessings
Prints out information about the blessings (typically obtained from this tool)
encoded in the provided file.
Usage:
principal dumpblessings [flags] <file>
<file> is the path to a file containing blessings typically obtained from this
tool. - is used for STDIN.
Principal dumproots - Dump out blessings of the identity providers of blessings
Prints out the blessings of the identity providers of the input blessings. One
line per identity provider, each line is a base64url-encoded (RFC 4648, Section
5) vom-encoded Blessings object.
Usage:
principal dumproots [flags] <file>
<file> is the path to a file containing blessings (base64url-encoded
vom-encoded). - is used for STDIN.
Principal blessself - Generate a self-signed blessing
Returns a blessing with name <name> and self-signed by the principal specified
by the environment that this tool is running in. Optionally, the blessing can be
restricted with an expiry caveat specified using the --for flag. Additional
caveats can be added with the --caveat flag.
Usage:
principal blessself [flags] [<name>]
<name> is the name used to create the self-signed blessing. If not specified, a
name will be generated based on the hostname of the machine and the name of the
user running this command.
The principal blessself flags are:
-caveat=
"package/path".CaveatName:VDLExpressionParam to attach to this blessing
-for=0s
Duration of blessing validity (zero implies no expiration)
Principal bless - Bless another principal
Bless another principal.
The blesser is obtained from the runtime this tool is using. The blessing that
will be extended is the default one from the blesser's store, or specified by
the --with flag. Expiration on the blessing are controlled via the --for flag.
Additional caveats are controlled with the --caveat flag.
For example, let's say a principal "alice" wants to bless another principal
"bob" as "alice:friend", the invocation would be:
V23_CREDENTIALS=<path to alice> principal bless <path to bob> friend
and this will dump the blessing to STDOUT.
With the --remote-key and --remote-token flags, this command can be used to
bless a principal on a remote machine. In this case, the blessing is not dumped
to STDOUT but sent to the remote end. Use 'principal help recvblessings' for
details.
When --remote-arg-file is specified, only the blessing extension is required, as
all other arguments will be extracted from the specified file.
Usage:
principal bless [flags] [<principal to bless>] [<extension>]
<principal to bless> represents the principal to be blessed (i.e., whose public
key will be provided with a name). This can be either:
(a) The directory containing credentials for that principal,
OR
(b) The filename (- for STDIN) containing the base64url-encoded public
key or any other blessings of the principal,
OR
(c) The object name produced by the 'recvblessings' command of this tool
running on behalf of another principal (if the --remote-key and
--remote-token flags are specified).
OR
(d) None (if the --remote-arg-file flag is specified, only <extension> should
be provided to bless).
<extension> is the string extension that will be applied to create the blessing.
The principal bless flags are:
-caveat=
"package/path".CaveatName:VDLExpressionParam to attach to this blessing
-for=0s
Duration of blessing validity (zero implies no expiration)
-remote-arg-file=
File containing bless arguments written by 'principal recvblessings
-remote-arg-file FILE EXTENSION' command. This can be provided to bless in
place of --remote-key, --remote-token, and <principal>
-remote-key=
Public key of the remote principal to bless (obtained from the
'recvblessings' command run by the remote principal
-remote-token=
Token provided by principal running the 'recvblessings' command
-require-caveats=true
If false, allow blessing without any caveats. This is typically not advised
as the principal wielding the blessing will be almost as powerful as its
blesser
-with=
Path to file containing blessing to extend
Principal set
Commands to mutate the blessings of the principal.
All input blessings are expected to be serialized using base64url-vom-encoding.
See 'principal get'.
Usage:
principal set [flags] <command>
The principal set commands are:
default Set provided blessings as default
forpeer Set provided blessings for peer
Principal set default - Set provided blessings as default
Sets the provided blessings as default in the BlessingStore specified by the
environment that this tool is running in.
It is an error to call 'set default' with blessings whose public key does not
match the public key of the principal specified by the environment.
Usage:
principal set default [flags] <file>
<file> is the path to a file containing a blessing typically obtained from this
tool. - is used for STDIN.
The principal set default flags are:
-add-to-roots=true
If true, the root certificate of the blessing will be added to the
principal's set of recognized root certificates
Principal set forpeer - Set provided blessings for peer
Marks the provided blessings to be shared with the provided peers on the
BlessingStore specified by the environment that this tool is running in.
'set b pattern' marks the intention to reveal b to peers who present blessings
of their own matching 'pattern'.
'set nil pattern' can be used to remove the blessings previously associated with
the pattern (by a prior 'set' command).
It is an error to call 'set forpeer' with blessings whose public key does not
match the public key of this principal specified by the environment.
Usage:
principal set forpeer [flags] <file> <pattern>
<file> is the path to a file containing a blessing typically obtained from this
tool. - is used for STDIN.
<pattern> is the BlessingPattern used to identify peers with whom this blessing
can be shared with.
The principal set forpeer flags are:
-add-to-roots=true
If true, the root certificate of the blessing will be added to the
principal's set of recognized root certificates
Principal get
Commands to inspect the blessings of the principal.
All blessings are printed to stdout using base64url-vom-encoding.
Usage:
principal get [flags] <command>
The principal get commands are:
default Return blessings marked as default
forpeer Return blessings marked for the provided peer
publickey Prints the public key of the principal.
recognizedroots Return recognized blessings, and their associated public key.
peermap Shows the map from peer pattern to which blessing name to
present.
Principal get default - Return blessings marked as default
Returns blessings that are marked as default in the BlessingStore specified by
the environment that this tool is running in. Providing --names will print the
default blessings' chain names. Providing --rootkey <chain_name> will print the
root key of the certificate chain with chain_name. Providing --caveats
<chain_name> will print the caveats on the certificate chain with chain_name.
Usage:
principal get default [flags]
The principal get default flags are:
-caveats=
Shows the caveats on the provided certificate chain name.
-names=false
If true, shows the value of the blessing name to be presented to the peer
-rootkey=
Shows the value of the root key of the provided certificate chain name.
Principal get forpeer - Return blessings marked for the provided peer
Returns blessings that are marked for the provided peer in the BlessingStore
specified by the environment that this tool is running in. Providing --names
will print the blessings' chain names. Providing --rootkey <chain_name> will
print the root key of the certificate chain with chain_name. Providing --caveats
<chain_name> will print the caveats on the certificate chain with chain_name.
Usage:
principal get forpeer [flags] [<peer_1> ... <peer_k>]
<peer_1> ... <peer_k> are the (human-readable string) blessings bound to the
peer. The returned blessings are marked with a pattern that is matched by at
least one of these. If no arguments are specified, store.forpeer returns the
blessings that are marked for all peers (i.e., blessings set on the store with
the "..." pattern).
The principal get forpeer flags are:
-caveats=
Shows the caveats on the provided certificate chain name.
-names=false
If true, shows the value of the blessing name to be presented to the peer
-rootkey=
Shows the value of the root key of the provided certificate chain name.
Principal get publickey
Prints out the public key of the principal specified by the environment that
this tool is running in.
The key is printed as a base64url encoded bytes (RFC 4648, Section 5) of the
DER-format representation of the key (suitable to be provided as an argument to
the 'recognize' command for example).
With --pretty, a 16-byte fingerprint of the key instead. This format is easier
for humans to read and is used in output of other commands in this program, but
is not suitable as an argument to the 'recognize' command.
Usage:
principal get publickey [flags]
The principal get publickey flags are:
-pretty=false
If true, print the key out in a more human-readable but lossy representation.
Principal get recognizedroots
Shows list of blessing names that the principal recognizes, and their associated
public key. If the principal is operating as a client, contacted servers must
appear on this list. If the principal is operating as a server, clients must
present blessings derived from this list.
Usage:
principal get recognizedroots [flags]
Principal get peermap
Shows the map from peer pattern to which blessing name to present. If the
principal operates as a server, it presents its default blessing to all peers.
If the principal operates as a client, it presents the map value associated with
the peer it contacts.
Usage:
principal get peermap [flags]
Principal recognize - Add to the set of identity providers recognized by this principal
Adds an identity provider to the set of recognized root public keys for this
principal.
It accepts either a single argument (which points to a file containing a
blessing) or two arguments (a name and a base64url-encoded DER-encoded public
key).
For example, to make the principal in credentials directory A recognize the root
of the default blessing in credentials directory B:
principal -v23.credentials=B bless A some_extension |
principal -v23.credentials=A recognize -
The extension 'some_extension' has no effect in the command above.
Or to make the principal in credentials directory A recognize the public key for
the principal in credentials directory B for blessing pattern P:
principal -v23.credentials=A recognize P $(principal -v23.credentials=B get publickey)
Usage:
principal recognize [flags] <blessing pattern|blessing> [<key>]
<blessing> is the path to a file containing a blessing typically obtained from
this tool. - is used for STDIN.
<blessing pattern> is the blessing pattern for which <key> should be recognized.
<key> is a base64url-encoded, DER-encoded public key, such as that printed by
"principal get publickey".
Principal union - Merge multiple blessings into one
Merges multiple blessings into one.
It accepts multiple base64url-encoded blessings. Each argument can be a file
containing a blessing, or the blessing itself. It returns the union of all the
blessings.
For example, to merge the blessings contained in files A and B:
principal union A B, or
principal union $(cat A) $(cat B)
Usage:
principal union [flags] [<blessing> | <blessing file>...]
<blessing> is a base64url-encoded blessing.
<blessing file> is a file that contains a base64url-encoded blessing.
Principal help - Display help for commands or topics
Help with no args displays the usage of the parent command.
Help with args displays the usage of the specified sub-command or help topic.
"help ..." recursively displays help for all commands and topics.
Usage:
principal help [flags] [command/topic ...]
[command/topic ...] optionally identifies a specific sub-command or help topic.
The principal help flags are:
-style=compact
The formatting style for help output:
compact - Good for compact cmdline output.
full - Good for cmdline output, shows all global flags.
godoc - Good for godoc processing.
shortonly - Only output short description.
Override the default by setting the CMDLINE_STYLE environment variable.
-width=<terminal width>
Format output to this target width in runes, or unlimited if width < 0.
Defaults to the terminal width if available. Override the default by setting
the CMDLINE_WIDTH environment variable.
*/
package main