From ef2d3588e8d4dea8910ab1f7dfec768403efb265 Mon Sep 17 00:00:00 2001 From: "Dr. David von Oheimb" Date: Fri, 28 Aug 2020 13:28:24 +0200 Subject: [PATCH] apps/cmp.c: Improve documentation of -secret, -cert, and -key options Reviewed-by: Tomas Mraz Reviewed-by: Paul Dale (Merged from https://github.com/openssl/openssl/pull/12825) --- apps/cmp.c | 16 +++++++++------- doc/man1/openssl-cmp.pod.in | 15 ++++++++++----- 2 files changed, 19 insertions(+), 12 deletions(-) diff --git a/apps/cmp.c b/apps/cmp.c index 003c75517d6..d0f3c020c1b 100644 --- a/apps/cmp.c +++ b/apps/cmp.c @@ -378,14 +378,16 @@ const OPTIONS cmp_options[] = { {"ref", OPT_REF, 's', "Reference value to use as senderKID in case no -cert is given"}, {"secret", OPT_SECRET, 's', - "Password source for client authentication with a pre-shared key (secret)"}, + "Prefer PBM (over signatures) for protecting msgs with given password source"}, {"cert", OPT_CERT, 's', - "Client's current certificate (needed unless using -secret for PBM);"}, + "Client's CMP signer certificate; its public key must match the -key argument"}, {OPT_MORE_STR, 0, 0, - "any further certs included are appended in extraCerts field"}, + "This also used as default reference for subject DN and SANs."}, + {OPT_MORE_STR, 0, 0, + "Any further certs included are appended to the untrusted certs"}, {"own_trusted", OPT_OWN_TRUSTED, 's', "Optional certs to verify chain building for own CMP signer cert"}, - {"key", OPT_KEY, 's', "Private key for the client's current certificate"}, + {"key", OPT_KEY, 's', "CMP signer private key, not used when -secret given"}, {"keypass", OPT_KEYPASS, 's', "Client private key (and cert and old cert file) pass phrase source"}, {"digest", OPT_DIGEST, 's', @@ -1479,8 +1481,8 @@ static SSL_CTX *setup_ssl_ctx(OSSL_CMP_CTX *ctx, ENGINE *engine) */ static int setup_protection_ctx(OSSL_CMP_CTX *ctx, ENGINE *engine) { - if (!opt_unprotected_requests && opt_secret == NULL && opt_cert == NULL) { - CMP_err("must give client credentials unless -unprotected_requests is set"); + if (!opt_unprotected_requests && opt_secret == NULL && opt_key == NULL) { + CMP_err("must give -key or -secret unless -unprotected_requests is used"); return 0; } @@ -1507,7 +1509,7 @@ static int setup_protection_ctx(OSSL_CMP_CTX *ctx, ENGINE *engine) return 0; } if (opt_cert != NULL || opt_key != NULL) - CMP_warn("no signature-based protection used since -secret is given"); + CMP_warn("-cert and -key not used for protection since -secret is given"); } if (opt_ref != NULL && !OSSL_CMP_CTX_set1_referenceValue(ctx, (unsigned char *)opt_ref, diff --git a/doc/man1/openssl-cmp.pod.in b/doc/man1/openssl-cmp.pod.in index 44f71b83586..2d484805b3f 100644 --- a/doc/man1/openssl-cmp.pod.in +++ b/doc/man1/openssl-cmp.pod.in @@ -610,10 +610,11 @@ is typically used when authenticating with pre-shared key (password-based MAC). =item B<-secret> I -Source of secret value to use for creating PBM-based protection of outgoing -messages and for verifying any PBM-based protection of incoming messages. +Prefer PBM-based message protection with given source of a secret value. +The secret is used for creating PBM-based protection of outgoing messages +and (as far as needed) for verifying PBM-based protection of incoming messages. PBM stands for Password-Based Message Authentication Code. -This takes precedence over the B<-cert> option. +This takes precedence over the B<-cert> and B<-key> options. For more information about the format of B see the B section in L. @@ -624,13 +625,17 @@ The client's current CMP signer certificate. Requires the corresponding key to be given with B<-key>. The subject of this certificate will be used as sender of outgoing CMP messages, while the subject of B<-oldcert> or B<-subjectName> may provide fallback values. +The issuer of this certificate is used as one of the recipient fallback values. When using signature-based message protection, this "protection certificate" -will be included first in the extraCerts field of outgoing messages. +will be included first in the extraCerts field of outgoing messages +and the signature is done with the corresponding key. In Initialization Request (IR) messages this can be used for authenticating using an external entity certificate as defined in appendix E.7 of RFC 4210. For Key Update Request (KUR) messages this is also used as the certificate to be updated if the B<-oldcert> option is not given. -If the file includes further certs, they are appended to the untrusted certs. +If the file includes further certs, they are appended to the untrusted certs +because they typically constitute the chain of the client certificate, which +is included in the extraCerts field in signature-protected request messages. =item B<-own_trusted> I -- 2.47.3