3.1 spkitool.py command reference

spkitool.py [-v][-h [cmd]][-d dir] command [command-options]

This script can be invoked to run any of the commands listed below. It supports several generic options that must be listed before the command. Each command also supports command-specific options, which must be listed after the command name.

The -v option causes verbose output while the command runs.

The -h option prints help. If -h is specified by itself, a list of all commands is printed. If -h is followed by a command name, detailed help for that command is printed. The name 'all' is used as an argument, detailed help is printed for each command.

The -d dir specifies the location of the user's spkitool configuration directory.

The spkitool script supports the following commands:

acl -s/-subject key -p permissions [-o output][-b/-before time][-a/-after time]

[-test URI][-d/-delegate][-db acl]

Creates a certificate for an access control list (Entry). The subject can be a hash of a key or a name. If the subject is a name, the name is interpreted relative to the user's default key.

The permissions should be a text representation of a SPKI sexp. This is a little clunky, but it's hard to come up with a general interface for something that is essentially application-specific.

If the --db option is used, the Entry is added to the database.ACL file at the specified path. If this option is used, it overrides the -o option. Will create a new ACL if one does not exist.

The -d/--delegate option allows permissions to be delegated. By default, delegation is disabled.

The before/after/test modifiers are the same as for the cert command. They affect the validity constraints.

cert -s/-subject -p/-permission permission [-i/-issuer][-b/-before time]

[-a/-after time][-t/-test URI][-d/-delegate][-k/-key]

Create a new certificate. The certificate has the following parts: subject, issuer, validity, and permissions. It may also have a delegation tag. Each of these parts can be specified using a different option; each option has a short name and a long name.

Note: To create a name certificate, use the name command.

The options for the cert command are list below. Each take a single argument following the option name.

optional: --issuer (-i)

The hash or name of the key to use as issuer. Will use the default key as issuer otherwise.

required: --subject (-s)

The hash or name of the key that is the subject of the certificate.

optional: --before (-b)
optional: --after (-a)

These options limit the period of time for which the certificate is valid. The time format is YYYY-MM-DD_HH:MM:SS. You can also use the string "now" to indicate the current time.

optional: --test (-t)

Specify an online validity test for the certificate. The argument should be the URL for the test. This optional currently has no associated implementation; although it can be included in the certificate, the test will not be performed.

required: --permission (-p)

Specify the permissions that are being granted to the subject key. The argument must be an S-expression in human-readable form for the permissions. The permissions will be wrapped in a (tag ...) S-expression.

optional: --delegate (-d)

Allow subject to delegate permission. Default is to disallow delegation.

optional: --key (-k)

Include the key of the issuer with the certificate. By default, the certificate does not include the key itself, only the hash of the key.

create [-b bits][-unsafe][-replace][-dup][-default|name]

Create a key pair with label as specified by user. Add the key pair to the user's key file and add the public key to the user's ACL. The user will be prompted for a pass phrase to encrypt the private key. Currently on the rsa-pkcs1-md5 algorithm is supported.

Options:

--unsafe: use the user's PID as pass phrase

--replace: replace an existing default key

-b NNNN: number of bits for key pair (default 1024)

--dup: create a name cert even if name is already used

Note: The SPKI protocol allows multiple keys to be bound to the same name, which allows the creation of a group. But multiple keys with the same name presents a problem for naming private keys, because the name no longer unambiguously refers to a single key.

export [-o output][-canonical] <hash-or-name>: Export a public key from the store. The key may be specified by its hash or its name. The -o flag can be used to specify a file to place the key; if no file is specified, the key will be printed on stdout.
Keys are output in base64 encoding by default. Use the --canonical flag to specify the canonical (binary) encoding instead.

import [path]

Load a new public key or certificate into the keystore. The object will be loaded from a file containing either the canonical or base64 encoding of the S-expression. If no path is specified, the object will be read from stdin.

For a certificate to be useful in verifying a certificate chain, it must be signed. A public key, however, needs no signature.

list [-public][-private][-name]: List all the keys stored in the KeyStore and all the name certificates issued by the private keys. For private keys, the hash of the corresponding public key is listed. As a result, the same hash should appear in the private and public lists.
Specifying the options, limits the listing to only the specified sections.

name -n/-name name -h/-hash hash [-i/-issuer principal][-o output]

Create a name certificate. Can be used to associate a name with a public key on the key server.

The hash designates the public key that the name will be bound to. The hash can either by the advanced form of a SPKI hash object, or just the base64 encoded digest. Thus, either of the following is allowed: '(hash md5 |hTK6mv8Nbspy9jsljfb2DQ==|)' or 'hTK6mv8Nbspy9jsljfb2DQ=='.

By default, the issuer is the user's default key. To use a different key, the user should specify the name or hash of the key with the --issuer argument.

The -o option can be used to make a local copy of the name cert.

This command needs to be extended with validity handling.

show [-i input][-o output]: Read in an arbitrary SPKI object and display it in human-readable form. The show command will read the object from stdin and display it on stdout. The source and destination can be changed with the -i and -o arguments.

sign [-s/-signer name][-o output] file

Create a digital signature for the contents of the specified file. By default, the signature is placed stored as file.sig, but you can use the -o option to specify a different output location.

The signature is created using the default key, unless the --signer option is used to specify a different key. The --signer option will accept the name or hash of a key.

verify [-i signaturefile] file: Verify a digital signature of a file. The default behavior is to look for the signature in file.sig. The -i option can be used to specify a different path for the signature.