=item B<-secret> I<arg>
-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 validating PBM-based protection of incoming messages.
-PBM stands for Password-Based Message Authentication Code.
+Provides the source of a secret value to use with MAC-based message protection.
This takes precedence over the B<-cert> and B<-key> options.
+The secret is used for creating MAC-based protection of outgoing messages
+and for validating incoming messages that have MAC-based protection.
+The algorithm used by default is Password-Based Message Authentication Code (PBM)
+as defined in RFC 4210 section 5.1.3.1.
For more information about the format of I<arg> see
L<openssl-passphrase-options(1)>.
The issuer of this certificate is used as one of the recipient fallback values
and as fallback issuer entry in the certificate template of IR/CR/KUR messages.
-When using signature-based message protection, this "protection certificate"
+When performing signature-based message protection,
+this "protection certificate", also called "signer certificate",
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
The corresponding private key file for the client's current certificate given in
the B<-cert> option.
-This will be used for signature-based message protection unless
-the B<-secret> option indicating PBM or B<-unprotected_requests> is given.
+This will be used for signature-based message protection unless the B<-secret>
+option indicating MAC-based protection or B<-unprotected_requests> is given.
It is also used as a fallback for the B<-newkey> option with IR/CR/KUR messages.
=item B<-digest> I<name>
Specifies name of supported digest to use in RFC 4210's MSG_SIG_ALG
-and as the one-way function (OWF) in MSG_MAC_ALG.
+and as the one-way function (OWF) in C<MSG_MAC_ALG>.
If applicable, this is used for message protection and
proof-of-possession (POPO) signatures.
To see the list of supported digests, use C<openssl list -digest-commands>.
=item B<-mac> I<name>
-Specifies the name of the MAC algorithm in MSG_MAC_ALG.
+Specifies the name of the MAC algorithm in C<MSG_MAC_ALG>.
To get the names of supported MAC algorithms use C<openssl list -mac-algorithms>
and possibly combine such a name with the name of a supported digest algorithm,
e.g., hmacWithSHA256.
openssl cmp -section insta,kur
-using with PBM-based protection or
+using MAC-based protection with PBM or
openssl cmp -section insta,kur,signature
-newkey cl_key_new.pem -certout cl_cert.pem
cp cl_key_new.pem cl_key.pem
-This command sequence can be repated as often as needed.
+This command sequence can be repeated as often as needed.
=head2 Requesting information from CMP server
=item B<OSSL_CMP_OPT_OWF_ALGNID>
The NID of the digest algorithm to be used as one-way function (OWF)
- in RFC 4210's MSG_MAC_ALG for PBM-based message protection.
+ for MAC-based message protection with password-based MAC (PBM).
+ See RFC 4210 section 5.1.3.1 for details.
Default is SHA256.
=item B<OSSL_CMP_OPT_MAC_ALGNID>
- The NID of the MAC algorithm to be used in RFC 4210's MSG_MAC_ALG
- for PBM-based message protection.
+ The NID of the MAC algorithm to be used for message protection with PBM.
Default is HMAC-SHA1 as per RFC 4210.
=item B<OSSL_CMP_OPT_REVOCATION_REASON>
OSSL_CMP_CTX_get0_untrusted(OSSL_CMP_CTX *ctx) returns a pointer to the
list of untrusted certs, which may be empty if unset.
-OSSL_CMP_CTX_set1_cert() sets the CMP signer certificate
-related to the private key used for CMP message protection.
+OSSL_CMP_CTX_set1_cert() sets the CMP signer certificate, also called protection
+certificate, related to the private key for signature-based message protection.
Therefore the public key of this I<cert> must correspond to
the private key set before or thereafter via OSSL_CMP_CTX_set1_pkey().
When using signature-based protection of CMP request messages
CMP signer certificate set via OSSL_CMP_CTX_set1_cert().
This key is used create signature-based protection (protectionAlg = MSG_SIG_ALG)
of outgoing messages
-unless a PBM secret has been set via OSSL_CMP_CTX_set1_secretValue().
+unless a symmetric secret has been set via OSSL_CMP_CTX_set1_secretValue().
The I<pkey> argument may be NULL to clear the entry.
-OSSL_CMP_CTX_set1_secretValue() sets the byte string I<sec> with length I<len>
-as PBM secret in the given I<ctx> or clears it if the I<sec> argument is NULL.
-If present, this secret is used to create PBM-based protection of outgoing
-messages and to verify any PBM-based protection of incoming messages
-(protectionAlg = MSG_MAC_ALG). PBM stands for Password-Based MAC.
-PBM-based protection takes precedence over signature-based protection.
+OSSL_CMP_CTX_set1_secretValue() sets in I<ctx> the byte string I<sec> of length
+I<len> to use as pre-shared secret, or clears it if the I<sec> argument is NULL.
+If present, this secret is used to create MAC-based authentication and integrity
+protection (rather than applying signature-based protection)
+of outgoing messages and to verify authenticity and integrity of incoming
+messages that have MAC-based protection (protectionAlg = C<MSG_MAC_ALG>).
OSSL_CMP_CTX_set1_referenceValue() sets the given referenceValue I<ref> with
length I<len> in the given I<ctx> or clears it if the I<ref> argument is NULL.
and the senderKID field of the CMP message header must be set.
When signature-based protection is used the senderKID will be set to
the subjectKeyIdentifier of the CMP signer certificate as far as present.
-If not present or when PBM-based protection is used
+If not present or when MAC-based protection is used
the I<ref> value is taken as the fallback value for the senderKID.
OSSL_CMP_CTX_set1_recipient() sets the recipient name that will be used in the
OSSL_CMP_CTX_set1_serverPath(cmp_ctx, path_or_alias);
OSSL_CMP_CTX_set0_trustedStore(cmp_ctx, ts);
-Set up client credentials for password-based protection (PBM):
+Set up symmetric credentials for MAC-based message protection such as PBM:
OSSL_CMP_CTX_set1_referenceValue(cmp_ctx, ref, ref_len);
OSSL_CMP_CTX_set1_secretValue(cmp_ctx, sec, sec_len);
All functions take a populated OSSL_CMP_CTX structure as their first argument.
Usually the server name, port, and path ("CMP alias") need to be set, as well as
-credentials the client can use for authenticating itself to the client.
+credentials the client can use for authenticating itself to the server.
In order to authenticate the server the client typically needs a trust store.
The functions return their respective main results directly, while there are
also accessor functions for retrieving various results and status information
L<OSSL_CMP_CTX_set0_newPkey(3)>, L<OSSL_CMP_CTX_set1_oldCert(3)>, etc.
For P10CR, L<OSSL_CMP_CTX_set1_p10CSR(3)> needs to be used instead.
The enrollment session may be blocked by sleeping until the addressed
-CA (or an intermedate PKI component) can fully process and answer the request.
+CA (or an intermediate PKI component) can fully process and answer the request.
OSSL_CMP_try_certreq() is an alternative to the above functions that is
more flexible regarding what to do after receiving a checkAfter value.
CMP is defined in RFC 4210 (and CRMF in RFC 4211).
-So far the CMP client implementation is limited to one request per CMP message
+The CMP client implementation is limited to one request per CMP message
(and consequently to at most one response component per CMP message).
=head1 RETURN VALUES
projects / openssl.git / commitdiff