blob: 04a4c2da99983d6ba83bdc809970656ee714c4e4 [file] [log] [blame]
// Copyright 2015 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.i18n-catalogue=
18n catalogue files to load, comma separated
-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=map[]
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.tcp.address=
address to listen on
-v23.tcp.protocol=wsh
protocol to listen with
-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.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:
-overwrite=false
If true, any existing principal data in the directory will be overwritten
-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=0
Duration of blessing validity (zero implies no expiration caveat)
-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
-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 obtained 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 received 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=0
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=0
Duration of blessing validity (zero implies no expiration caveat)
-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