security-and-privacy/gnupg
security-and-privacy
/
gnupg
mirror of git://git.gnupg.org/gnupg.git
1
0
Fork 0
Code Releases Activity

Add help strings for all commands

This commit is contained in:
Werner Koch 2009-11-04 15:31:52 +00:00
parent 0f4a5db22e
commit 16a8979984
2 changed files with 190 additions and 131 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
sm/ChangeLog
View File

@ -1,7 +1,7 @@
2009-11-04 Werner Koch <wk@g10code.com>
* server.c (register_commands): Add NULL arg to
assuan_register_command.
* server.c (register_commands): Add help arg to
assuan_register_command. Provide help strings for all commands.
2009-11-02 Marcus Brinkmann <marcus@g10code.de>

317
sm/server.c
View File

@ -360,18 +360,18 @@ output_notify (assuan_context_t ctx, char *line)
}
/* RECIPIENT <userID>
Set the recipient for the encryption. <userID> should be the
internal representation of the key; the server may accept any other
way of specification [we will support this]. If this is a valid and
trusted recipient the server does respond with OK, otherwise the
return is an ERR with the reason why the recipient can't be used,
the encryption will then not be done for this recipient. If the
policy is not to encrypt at all if not all recipients are valid, the
client has to take care of this. All RECIPIENT commands are
cumulative until a RESET or an successful ENCRYPT command. */
static const char hlp_recipient[] =
"RECIPIENT <userID>\n"
"\n"
"Set the recipient for the encryption. USERID shall be the\n"
"internal representation of the key; the server may accept any other\n"
"way of specification [we will support this]. If this is a valid and\n"
"trusted recipient the server does respond with OK, otherwise the\n"
"return is an ERR with the reason why the recipient can't be used,\n"
"the encryption will then not be done for this recipient. If the\n"
"policy is not to encrypt at all if not all recipients are valid, the\n"
"client has to take care of this. All RECIPIENT commands are\n"
"cumulative until a RESET or an successful ENCRYPT command.";
static gpg_error_t
cmd_recipient (assuan_context_t ctx, char *line)
{
@ -395,19 +395,21 @@ cmd_recipient (assuan_context_t ctx, char *line)
return rc;
}
/* SIGNER <userID>
Set the signer's keys for the signature creation. <userID> should
be the internal representation of the key; the server may accept any
other way of specification [we will support this]. If this is a
valid and usable signing key the server does respond with OK,
otherwise it returns an ERR with the reason why the key can't be
used, the signing will then not be done for this key. If the policy
is not to sign at all if not all signer keys are valid, the client
has to take care of this. All SIGNER commands are cumulative until
a RESET but they are *not* reset by an SIGN command becuase it can
be expected that set of signers are used for more than one sign
operation. */
static const char hlp_signer[] =
"SIGNER <userID>\n"
"\n"
"Set the signer's keys for the signature creation. USERID should\n"
"be the internal representation of the key; the server may accept any\n"
"other way of specification [we will support this]. If this is a\n"
"valid and usable signing key the server does respond with OK,\n"
"otherwise it returns an ERR with the reason why the key can't be\n"
"used, the signing will then not be done for this key. If the policy\n"
"is not to sign at all if not all signer keys are valid, the client\n"
"has to take care of this. All SIGNER commands are cumulative until\n"
"a RESET but they are *not* reset by an SIGN command becuase it can\n"
"be expected that set of signers are used for more than one sign\n"
"operation.";
static gpg_error_t
cmd_signer (assuan_context_t ctx, char *line)
{
@ -429,19 +431,20 @@ cmd_signer (assuan_context_t ctx, char *line)
}
/* ENCRYPT
Do the actual encryption process. Takes the plaintext from the INPUT
command, writes to the ciphertext to the file descriptor set with
the OUTPUT command, take the recipients form all the recipients set
so far. If this command fails the clients should try to delete all
output currently done or otherwise mark it as invalid. GPGSM does
ensure that there won't be any security problem with leftover data
on the output in this case.
This command should in general not fail, as all necessary checks
have been done while setting the recipients. The input and output
pipes are closed. */
static const char hlp_encrypt[] =
"ENCRYPT \n"
"\n"
"Do the actual encryption process. Takes the plaintext from the INPUT\n"
"command, writes to the ciphertext to the file descriptor set with\n"
"the OUTPUT command, take the recipients form all the recipients set\n"
"so far. If this command fails the clients should try to delete all\n"
"output currently done or otherwise mark it as invalid. GPGSM does\n"
"ensure that there won't be any security problem with leftover data\n"
"on the output in this case.\n"
"\n"
"This command should in general not fail, as all necessary checks\n"
"have been done while setting the recipients. The input and output\n"
"pipes are closed.";
static gpg_error_t
cmd_encrypt (assuan_context_t ctx, char *line)
{
@ -492,13 +495,14 @@ cmd_encrypt (assuan_context_t ctx, char *line)
}
/* DECRYPT
This performs the decrypt operation after doing some check on the
internal state. (e.g. that only needed data has been set). Because
it utilizes the GPG-Agent for the session key decryption, there is
no need to ask the client for a protecting passphrase - GpgAgent
does take care of this by requesting this from the user. */
static const char hlp_decrypt[] =
"DECRYPT\n"
"\n"
"This performs the decrypt operation after doing some check on the\n"
"internal state. (e.g. that only needed data has been set). Because\n"
"it utilizes the GPG-Agent for the session key decryption, there is\n"
"no need to ask the client for a protecting passphrase - GPG-Agent\n"
"does take care of this by requesting this from the user.";
static gpg_error_t
cmd_decrypt (assuan_context_t ctx, char *line)
{
@ -534,15 +538,15 @@ cmd_decrypt (assuan_context_t ctx, char *line)
}
/* VERIFY
This does a verify operation on the message send to the input-FD.
The result is written out using status lines. If an output FD was
given, the signed text will be written to that.
If the signature is a detached one, the server will inquire about
the signed material and the client must provide it.
*/
static const char hlp_verify[] =
"VERIFY\n"
"\n"
"This does a verify operation on the message send to the input FD.\n"
"The result is written out using status lines. If an output FD was\n"
"given, the signed text will be written to that.\n"
"\n"
"If the signature is a detached one, the server will inquire about\n"
"the signed material and the client must provide it.";
static gpg_error_t
cmd_verify (assuan_context_t ctx, char *line)
{
@ -580,11 +584,12 @@ cmd_verify (assuan_context_t ctx, char *line)
}
/* SIGN [--detached]
Sign the data set with the INPUT command and write it to the sink
set by OUTPUT. With "--detached" specified, a detached signature is
created (surprise). */
static const char hlp_sign[] =
"SIGN [--detached]\n"
"\n"
"Sign the data set with the INPUT command and write it to the sink\n"
"set by OUTPUT. With \"--detached\", a detached signature is\n"
"created (surprise).";
static gpg_error_t
cmd_sign (assuan_context_t ctx, char *line)
{
@ -622,17 +627,18 @@ cmd_sign (assuan_context_t ctx, char *line)
}
/* IMPORT [--re-import]
Import the certificates read form the input-fd, return status
message for each imported one. The import checks the validity of
the certificate but not of the entire chain. It is possible to
import expired certificates.
With the option --re-import the input data is expected to a be a LF
separated list of fingerprints. The command will re-import these
certificates, meaning that they are made permanent by removing
their ephemeral flag. */
static const char hlp_import[] =
"IMPORT [--re-import]\n"
"\n"
"Import the certificates read form the input-fd, return status\n"
"message for each imported one. The import checks the validity of\n"
"the certificate but not of the entire chain. It is possible to\n"
"import expired certificates.\n"
"\n"
"With the option --re-import the input data is expected to a be a LF\n"
"separated list of fingerprints. The command will re-import these\n"
"certificates, meaning that they are made permanent by removing\n"
"their ephemeral flag.";
static gpg_error_t
cmd_import (assuan_context_t ctx, char *line)
{
@ -657,10 +663,14 @@ cmd_import (assuan_context_t ctx, char *line)
}
/* EXPORT [--data [--armor|--base64]] [--] pattern
*/
static const char hlp_export[] =
"EXPORT [--data [--armor|--base64]] [--] <pattern>\n"
"\n"
"Export the certificates selected by PATTERN. With --data the output\n"
"is returned using Assuan D lines; the default is to use the sink given\n"
"by the last \"OUTPUT\" command. The options --armor or --base64 encode \n"
"the output using the PEM respective a plain base-64 format; the default\n"
"is a binary format which is only suitable for a single certificate.";
static gpg_error_t
cmd_export (assuan_context_t ctx, char *line)
{
@ -747,6 +757,13 @@ cmd_export (assuan_context_t ctx, char *line)
}
static const char hlp_delkeys[] =
"DELKEYS <patterns>\n"
"\n"
"Delete the certificates specified by PATTERNS. Each pattern shall be\n"
"a percent-plus escaped certificate specification. Usually a\n"
"fingerprint will be used for this.";
static gpg_error_t
cmd_delkeys (assuan_context_t ctx, char *line)
{
@ -791,10 +808,27 @@ cmd_delkeys (assuan_context_t ctx, char *line)
/* MESSAGE FD=<n>
Set the file descriptor to read a message which is used with
detached signatures */
static const char hlp_output[] =
"OUTPUT FD[=<n>]\n"
"\n"
"Set the file descriptor to write the output data to N. If N is not\n"
"given and the operating system supports file descriptor passing, the\n"
"file descriptor currently in flight will be used. See also the\n"
"\"INPUT\" and \"MESSAGE\" commands.";
static const char hlp_input[] =
"INPUT FD[=<n>]\n"
"\n"
"Set the file descriptor to read the input data to N. If N is not\n"
"given and the operating system supports file descriptor passing, the\n"
"file descriptor currently in flight will be used. See also the\n"
"\"MESSAGE\" and \"OUTPUT\" commands.";
static const char hlp_message[] =
"MESSAGE FD[=<n>]\n"
"\n"
"Set the file descriptor to read the message for a detached\n"
"signatures to N. If N is not given and the operating system\n"
"supports file descriptor passing, the file descriptor currently in\n"
"flight will be used. See also the \"INPUT\" and \"OUTPUT\" commands.";
static gpg_error_t
cmd_message (assuan_context_t ctx, char *line)
{
@ -813,11 +847,36 @@ cmd_message (assuan_context_t ctx, char *line)
return 0;
}
/* LISTKEYS [<patterns>]
DUMPKEYS [<patterns>]
LISTSECRETKEYS [<patterns>]
DUMPSECRETKEYS [<patterns>]
*/
static const char hlp_listkeys[] =
"LISTKEYS [<patterns>]\n"
"LISTSECRETKEYS [<patterns>]\n"
"DUMPKEYS [<patterns>]\n"
"DUMPSECRETKEYS [<patterns>]\n"
"\n"
"List all certificates or only those specified by PATTERNS. Each\n"
"pattern shall be a percent-plus escaped certificate specification.\n"
"The \"SECRET\" versions of the command filter the output to include\n"
"only certificates where the secret key is available or a corresponding\n"
"smartcard has been registered. The \"DUMP\" versions of the command\n"
"are only useful for debugging. The output format is a percent escaped\n"
"colon delimited listing as described in the manual.\n"
"\n"
"These \"OPTION\" command keys effect the output::\n"
"\n"
" \"list-mode\" set to 0: List only local certificates (default).\n"
" 1: Ditto.\n"
" 2: List only external certificates.\n"
" 3: List local and external certificates.\n"
"\n"
" \"with-validation\" set to true: Validate each certificate.\n"
"\n"
" \"with-ephemeral-key\" set to true: Always include ephemeral\n"
" certificates.\n"
"\n"
" \"list-to-output\" set to true: Write output to the file descriptor\n"
" given by the last \"OUTPUT\" command.";
static int
do_listkeys (assuan_context_t ctx, char *line, int mode)
{
@ -907,12 +966,13 @@ cmd_dumpsecretkeys (assuan_context_t ctx, char *line)
return do_listkeys (ctx, line, 258);
}
/* GENKEY
Read the parameters in native format from the input fd and write a
certificate request to the output.
*/
static const char hlp_genkey[] =
"GENKEY\n"
"\n"
"Read the parameters in native format from the input fd and write a\n"
"certificate request to the output.";
static gpg_error_t
cmd_genkey (assuan_context_t ctx, char *line)
{
@ -953,16 +1013,14 @@ cmd_genkey (assuan_context_t ctx, char *line)
/* GETAUDITLOG [--data] [--html]
!!!WORK in PROGRESS!!!
If --data is used, the output is send using D-lines and not to the
source given by an OUTPUT command.
If --html is used the output is formated as an XHTML block. This is
designed to be incorporated into a HTML document.
*/
static const char hlp_getauditlog[] =
"GETAUDITLOG [--data] [--html]\n"
"\n"
"If --data is used, the output is send using D-lines and not to the\n"
"file descriptor given by an OUTPUT command.\n"
"\n"
"If --html is used the output is formated as an XHTML block. This is\n"
"designed to be incorporated into a HTML document.";
static gpg_error_t
cmd_getauditlog (assuan_context_t ctx, char *line)
{
@ -1011,18 +1069,17 @@ cmd_getauditlog (assuan_context_t ctx, char *line)
}
/* GETINFO <what>
Multipurpose function to return a variety of information.
Supported values for WHAT are:
version - Return the version of the program.
pid - Return the process id of the server.
agent-check - Return success if the agent is running.
cmd_has_option CMD OPT
- Returns OK if the command CMD implements the option OPT.
*/
static const char hlp_getinfo[] =
"GETINFO <what>\n"
"\n"
"Multipurpose function to return a variety of information.\n"
"Supported values for WHAT are:\n"
"\n"
" version - Return the version of the program.\n"
" pid - Return the process id of the server.\n"
" agent-check - Return success if the agent is running.\n"
" cmd_has_option CMD OPT\n"
" - Returns OK if the command CMD implements the option OPT.";
static gpg_error_t
cmd_getinfo (assuan_context_t ctx, char *line)
{
@ -1106,33 +1163,35 @@ register_commands (assuan_context_t ctx)
static struct {
const char *name;
assuan_handler_t handler;
const char * const help;
} table[] = {
{ "RECIPIENT", cmd_recipient },
{ "SIGNER", cmd_signer },
{ "ENCRYPT", cmd_encrypt },
{ "DECRYPT", cmd_decrypt },
{ "VERIFY", cmd_verify },
{ "SIGN", cmd_sign },
{ "IMPORT", cmd_import },
{ "EXPORT", cmd_export },
{ "INPUT", NULL },
{ "OUTPUT", NULL },
{ "MESSAGE", cmd_message },
{ "LISTKEYS", cmd_listkeys },
{ "DUMPKEYS", cmd_dumpkeys },
{ "LISTSECRETKEYS",cmd_listsecretkeys },
{ "DUMPSECRETKEYS",cmd_dumpsecretkeys },
{ "GENKEY", cmd_genkey },
{ "DELKEYS", cmd_delkeys },
{ "GETAUDITLOG", cmd_getauditlog },
{ "GETINFO", cmd_getinfo },
{ "RECIPIENT", cmd_recipient, hlp_recipient },
{ "SIGNER", cmd_signer, hlp_signer },
{ "ENCRYPT", cmd_encrypt, hlp_encrypt },
{ "DECRYPT", cmd_decrypt, hlp_decrypt },
{ "VERIFY", cmd_verify, hlp_verify },
{ "SIGN", cmd_sign, hlp_sign },
{ "IMPORT", cmd_import, hlp_import },
{ "EXPORT", cmd_export, hlp_export },
{ "INPUT", NULL, hlp_input },
{ "OUTPUT", NULL, hlp_output },
{ "MESSAGE", cmd_message, hlp_message },
{ "LISTKEYS", cmd_listkeys, hlp_listkeys },
{ "DUMPKEYS", cmd_dumpkeys, hlp_listkeys },
{ "LISTSECRETKEYS",cmd_listsecretkeys, hlp_listkeys },
{ "DUMPSECRETKEYS",cmd_dumpsecretkeys, hlp_listkeys },
{ "GENKEY", cmd_genkey, hlp_genkey },
{ "DELKEYS", cmd_delkeys, hlp_delkeys },
{ "GETAUDITLOG", cmd_getauditlog, hlp_getauditlog },
{ "GETINFO", cmd_getinfo, hlp_getinfo },
{ NULL }
};
int i, rc;
for (i=0; table[i].name; i++)
{
rc = assuan_register_command (ctx, table[i].name, table[i].handler, NULL);
rc = assuan_register_command (ctx, table[i].name, table[i].handler,
table[i].help);
if (rc)
return rc;
}