security-and-privacy/gnupg
security-and-privacy/gnupg
1
0
Fork 0
mirror of git://git.gnupg.org/gnupg.git synced 2025-01-03 12:11:33 +01:00
Code Activity

Add help strings for all commands

Browse Source
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> 2009-11-04 Werner Koch <wk@g10code.com>
* server.c (register_commands): Add NULL arg to * server.c (register_commands): Add help arg to
assuan_register_command. assuan_register_command. Provide help strings for all commands.
2009-11-02 Marcus Brinkmann <marcus@g10code.de> 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)
} }
static const char hlp_recipient[] =
/* RECIPIENT <userID> "RECIPIENT <userID>\n"
"\n"
Set the recipient for the encryption. <userID> should be the "Set the recipient for the encryption. USERID shall be the\n"
internal representation of the key; the server may accept any other "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 "way of specification [we will support this]. If this is a valid and\n"
trusted recipient the server does respond with OK, otherwise the "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, "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 "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 "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 "client has to take care of this. All RECIPIENT commands are\n"
cumulative until a RESET or an successful ENCRYPT command. */ "cumulative until a RESET or an successful ENCRYPT command.";
static gpg_error_t static gpg_error_t
cmd_recipient (assuan_context_t ctx, char *line) cmd_recipient (assuan_context_t ctx, char *line)
{ {
@ -395,19 +395,21 @@ cmd_recipient (assuan_context_t ctx, char *line)
return rc; return rc;
} }
/* SIGNER <userID>
Set the signer's keys for the signature creation. <userID> should static const char hlp_signer[] =
be the internal representation of the key; the server may accept any "SIGNER <userID>\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, "Set the signer's keys for the signature creation. USERID should\n"
otherwise it returns an ERR with the reason why the key can't be "be the internal representation of the key; the server may accept any\n"
used, the signing will then not be done for this key. If the policy "other way of specification [we will support this]. If this is a\n"
is not to sign at all if not all signer keys are valid, the client "valid and usable signing key the server does respond with OK,\n"
has to take care of this. All SIGNER commands are cumulative until "otherwise it returns an ERR with the reason why the key can't be\n"
a RESET but they are *not* reset by an SIGN command becuase it can "used, the signing will then not be done for this key. If the policy\n"
be expected that set of signers are used for more than one sign "is not to sign at all if not all signer keys are valid, the client\n"
operation. */ "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 static gpg_error_t
cmd_signer (assuan_context_t ctx, char *line) cmd_signer (assuan_context_t ctx, char *line)
{ {
@ -429,19 +431,20 @@ cmd_signer (assuan_context_t ctx, char *line)
} }
/* ENCRYPT static const char hlp_encrypt[] =
"ENCRYPT \n"
Do the actual encryption process. Takes the plaintext from the INPUT "\n"
command, writes to the ciphertext to the file descriptor set with "Do the actual encryption process. Takes the plaintext from the INPUT\n"
the OUTPUT command, take the recipients form all the recipients set "command, writes to the ciphertext to the file descriptor set with\n"
so far. If this command fails the clients should try to delete all "the OUTPUT command, take the recipients form all the recipients set\n"
output currently done or otherwise mark it as invalid. GPGSM does "so far. If this command fails the clients should try to delete all\n"
ensure that there won't be any security problem with leftover data "output currently done or otherwise mark it as invalid. GPGSM does\n"
on the output in this case. "ensure that there won't be any security problem with leftover data\n"
"on the output in this case.\n"
This command should in general not fail, as all necessary checks "\n"
have been done while setting the recipients. The input and output "This command should in general not fail, as all necessary checks\n"
pipes are closed. */ "have been done while setting the recipients. The input and output\n"
"pipes are closed.";
static gpg_error_t static gpg_error_t
cmd_encrypt (assuan_context_t ctx, char *line) cmd_encrypt (assuan_context_t ctx, char *line)
{ {
@ -492,13 +495,14 @@ cmd_encrypt (assuan_context_t ctx, char *line)
} }
/* DECRYPT static const char hlp_decrypt[] =
"DECRYPT\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 "This performs the decrypt operation after doing some check on the\n"
it utilizes the GPG-Agent for the session key decryption, there is "internal state. (e.g. that only needed data has been set). Because\n"
no need to ask the client for a protecting passphrase - GpgAgent "it utilizes the GPG-Agent for the session key decryption, there is\n"
does take care of this by requesting this from the user. */ "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 static gpg_error_t
cmd_decrypt (assuan_context_t ctx, char *line) cmd_decrypt (assuan_context_t ctx, char *line)
{ {
@ -534,15 +538,15 @@ cmd_decrypt (assuan_context_t ctx, char *line)
} }
/* VERIFY static const char hlp_verify[] =
"VERIFY\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 "This does a verify operation on the message send to the input FD.\n"
given, the signed text will be written to that. "The result is written out using status lines. If an output FD was\n"
"given, the signed text will be written to that.\n"
If the signature is a detached one, the server will inquire about "\n"
the signed material and the client must provide it. "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 static gpg_error_t
cmd_verify (assuan_context_t ctx, char *line) cmd_verify (assuan_context_t ctx, char *line)
{ {
@ -580,11 +584,12 @@ cmd_verify (assuan_context_t ctx, char *line)
} }
/* SIGN [--detached] static const char hlp_sign[] =
"SIGN [--detached]\n"
Sign the data set with the INPUT command and write it to the sink "\n"
set by OUTPUT. With "--detached" specified, a detached signature is "Sign the data set with the INPUT command and write it to the sink\n"
created (surprise). */ "set by OUTPUT. With \"--detached\", a detached signature is\n"
"created (surprise).";
static gpg_error_t static gpg_error_t
cmd_sign (assuan_context_t ctx, char *line) cmd_sign (assuan_context_t ctx, char *line)
{ {
@ -622,17 +627,18 @@ cmd_sign (assuan_context_t ctx, char *line)
} }
/* IMPORT [--re-import] static const char hlp_import[] =
"IMPORT [--re-import]\n"
Import the certificates read form the input-fd, return status "\n"
message for each imported one. The import checks the validity of "Import the certificates read form the input-fd, return status\n"
the certificate but not of the entire chain. It is possible to "message for each imported one. The import checks the validity of\n"
import expired certificates. "the certificate but not of the entire chain. It is possible to\n"
"import expired certificates.\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 "With the option --re-import the input data is expected to a be a LF\n"
certificates, meaning that they are made permanent by removing "separated list of fingerprints. The command will re-import these\n"
their ephemeral flag. */ "certificates, meaning that they are made permanent by removing\n"
"their ephemeral flag.";
static gpg_error_t static gpg_error_t
cmd_import (assuan_context_t ctx, char *line) 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 static gpg_error_t
cmd_export (assuan_context_t ctx, char *line) 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 static gpg_error_t
cmd_delkeys (assuan_context_t ctx, char *line) cmd_delkeys (assuan_context_t ctx, char *line)
{ {
@ -791,10 +808,27 @@ cmd_delkeys (assuan_context_t ctx, char *line)
/* MESSAGE FD=<n> static const char hlp_output[] =
"OUTPUT FD[=<n>]\n"
Set the file descriptor to read a message which is used with "\n"
detached signatures */ "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 static gpg_error_t
cmd_message (assuan_context_t ctx, char *line) cmd_message (assuan_context_t ctx, char *line)
{ {
@ -813,11 +847,36 @@ cmd_message (assuan_context_t ctx, char *line)
return 0; return 0;
} }
/* LISTKEYS [<patterns>]
DUMPKEYS [<patterns>]
LISTSECRETKEYS [<patterns>] static const char hlp_listkeys[] =
DUMPSECRETKEYS [<patterns>] "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 static int
do_listkeys (assuan_context_t ctx, char *line, int mode) 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); 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 static gpg_error_t
cmd_genkey (assuan_context_t ctx, char *line) cmd_genkey (assuan_context_t ctx, char *line)
{ {
@ -953,16 +1013,14 @@ cmd_genkey (assuan_context_t ctx, char *line)
/* GETAUDITLOG [--data] [--html] static const char hlp_getauditlog[] =
"GETAUDITLOG [--data] [--html]\n"
!!!WORK in PROGRESS!!! "\n"
"If --data is used, the output is send using D-lines and not to the\n"
If --data is used, the output is send using D-lines and not to the "file descriptor given by an OUTPUT command.\n"
source given by an OUTPUT command. "\n"
"If --html is used the output is formated as an XHTML block. This is\n"
If --html is used the output is formated as an XHTML block. This is "designed to be incorporated into a HTML document.";
designed to be incorporated into a HTML document.
*/
static gpg_error_t static gpg_error_t
cmd_getauditlog (assuan_context_t ctx, char *line) cmd_getauditlog (assuan_context_t ctx, char *line)
{ {
@ -1011,18 +1069,17 @@ cmd_getauditlog (assuan_context_t ctx, char *line)
} }
/* GETINFO <what> static const char hlp_getinfo[] =
"GETINFO <what>\n"
Multipurpose function to return a variety of information. "\n"
Supported values for WHAT are: "Multipurpose function to return a variety of information.\n"
"Supported values for WHAT are:\n"
version - Return the version of the program. "\n"
pid - Return the process id of the server. " version - Return the version of the program.\n"
agent-check - Return success if the agent is running. " pid - Return the process id of the server.\n"
cmd_has_option CMD OPT " agent-check - Return success if the agent is running.\n"
- Returns OK if the command CMD implements the option OPT. " cmd_has_option CMD OPT\n"
" - Returns OK if the command CMD implements the option OPT.";
*/
static gpg_error_t static gpg_error_t
cmd_getinfo (assuan_context_t ctx, char *line) cmd_getinfo (assuan_context_t ctx, char *line)
{ {
@ -1106,33 +1163,35 @@ register_commands (assuan_context_t ctx)
static struct { static struct {
const char *name; const char *name;
assuan_handler_t handler; assuan_handler_t handler;
const char * const help;
} table[] = { } table[] = {
{ "RECIPIENT", cmd_recipient }, { "RECIPIENT", cmd_recipient, hlp_recipient },
{ "SIGNER", cmd_signer }, { "SIGNER", cmd_signer, hlp_signer },
{ "ENCRYPT", cmd_encrypt }, { "ENCRYPT", cmd_encrypt, hlp_encrypt },
{ "DECRYPT", cmd_decrypt }, { "DECRYPT", cmd_decrypt, hlp_decrypt },
{ "VERIFY", cmd_verify }, { "VERIFY", cmd_verify, hlp_verify },
{ "SIGN", cmd_sign }, { "SIGN", cmd_sign, hlp_sign },
{ "IMPORT", cmd_import }, { "IMPORT", cmd_import, hlp_import },
{ "EXPORT", cmd_export }, { "EXPORT", cmd_export, hlp_export },
{ "INPUT", NULL }, { "INPUT", NULL, hlp_input },
{ "OUTPUT", NULL }, { "OUTPUT", NULL, hlp_output },
{ "MESSAGE", cmd_message }, { "MESSAGE", cmd_message, hlp_message },
{ "LISTKEYS", cmd_listkeys }, { "LISTKEYS", cmd_listkeys, hlp_listkeys },
{ "DUMPKEYS", cmd_dumpkeys }, { "DUMPKEYS", cmd_dumpkeys, hlp_listkeys },
{ "LISTSECRETKEYS",cmd_listsecretkeys }, { "LISTSECRETKEYS",cmd_listsecretkeys, hlp_listkeys },
{ "DUMPSECRETKEYS",cmd_dumpsecretkeys }, { "DUMPSECRETKEYS",cmd_dumpsecretkeys, hlp_listkeys },
{ "GENKEY", cmd_genkey }, { "GENKEY", cmd_genkey, hlp_genkey },
{ "DELKEYS", cmd_delkeys }, { "DELKEYS", cmd_delkeys, hlp_delkeys },
{ "GETAUDITLOG", cmd_getauditlog }, { "GETAUDITLOG", cmd_getauditlog, hlp_getauditlog },
{ "GETINFO", cmd_getinfo }, { "GETINFO", cmd_getinfo, hlp_getinfo },
{ NULL } { NULL }
}; };
int i, rc; int i, rc;
for (i=0; table[i].name; i++) 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) if (rc)
return rc; return rc;
} }