| OSSL_CMP_CTX_new.pod (1.1.1.2) | OSSL_CMP_CTX_new.pod (1.1.1.3) |
|---|---|
| 1=pod 2 3=head1 NAME 4 5OSSL_CMP_CTX_new, 6OSSL_CMP_CTX_free, 7OSSL_CMP_CTX_reinit, 8OSSL_CMP_CTX_set_option, --- 168 unchanged lines hidden (view full) --- 177 178OSSL_CMP_CTX_free() deallocates an OSSL_CMP_CTX structure. 179 180OSSL_CMP_CTX_reinit() prepares the given I<ctx> for a further transaction by 181clearing the internal CMP transaction (aka session) status, PKIStatusInfo, 182and any previous results (newCert, newChain, caPubs, and extraCertsIn) 183from the last executed transaction. 184It also clears any ITAVs that were added by OSSL_CMP_CTX_push0_genm_ITAV(). | 1=pod 2 3=head1 NAME 4 5OSSL_CMP_CTX_new, 6OSSL_CMP_CTX_free, 7OSSL_CMP_CTX_reinit, 8OSSL_CMP_CTX_set_option, --- 168 unchanged lines hidden (view full) --- 177 178OSSL_CMP_CTX_free() deallocates an OSSL_CMP_CTX structure. 179 180OSSL_CMP_CTX_reinit() prepares the given I<ctx> for a further transaction by 181clearing the internal CMP transaction (aka session) status, PKIStatusInfo, 182and any previous results (newCert, newChain, caPubs, and extraCertsIn) 183from the last executed transaction. 184It also clears any ITAVs that were added by OSSL_CMP_CTX_push0_genm_ITAV(). |
| 185All other field values (i.e., CMP options) are retained for potential re-use. | 185All other field values (i.e., CMP options) are retained for potential reuse. |
| 186 187OSSL_CMP_CTX_set_option() sets the given value for the given option 188(e.g., OSSL_CMP_OPT_IMPLICIT_CONFIRM) in the given OSSL_CMP_CTX structure. 189 190The following options can be set: 191 192=over 4 193 --- 61 unchanged lines hidden (view full) --- 255=item B<OSSL_CMP_OPT_DIGEST_ALGNID> 256 257 The NID of the digest algorithm to be used in RFC 4210's MSG_SIG_ALG 258 for signature-based message protection and Proof-of-Possession (POPO). 259 Default is SHA256. 260 261=item B<OSSL_CMP_OPT_OWF_ALGNID> 262 The NID of the digest algorithm to be used as one-way function (OWF) | 186 187OSSL_CMP_CTX_set_option() sets the given value for the given option 188(e.g., OSSL_CMP_OPT_IMPLICIT_CONFIRM) in the given OSSL_CMP_CTX structure. 189 190The following options can be set: 191 192=over 4 193 --- 61 unchanged lines hidden (view full) --- 255=item B<OSSL_CMP_OPT_DIGEST_ALGNID> 256 257 The NID of the digest algorithm to be used in RFC 4210's MSG_SIG_ALG 258 for signature-based message protection and Proof-of-Possession (POPO). 259 Default is SHA256. 260 261=item B<OSSL_CMP_OPT_OWF_ALGNID> 262 The NID of the digest algorithm to be used as one-way function (OWF) |
| 263 in RFC 4210's MSG_MAC_ALG for PBM-based message protection. | 263 for MAC-based message protection with password-based MAC (PBM). 264 See RFC 4210 section 5.1.3.1 for details. |
| 264 Default is SHA256. 265 266=item B<OSSL_CMP_OPT_MAC_ALGNID> | 265 Default is SHA256. 266 267=item B<OSSL_CMP_OPT_MAC_ALGNID> |
| 267 The NID of the MAC algorithm to be used in RFC 4210's MSG_MAC_ALG 268 for PBM-based message protection. | 268 The NID of the MAC algorithm to be used for message protection with PBM. |
| 269 Default is HMAC-SHA1 as per RFC 4210. 270 271=item B<OSSL_CMP_OPT_REVOCATION_REASON> 272 273 The reason code to be included in a Revocation Request (RR); 274 values: 0..10 (RFC 5210, 5.3.1) or -1 for none, which is the default. 275 276=item B<OSSL_CMP_OPT_IMPLICIT_CONFIRM> --- 168 unchanged lines hidden (view full) --- 445of intermediate CAs that may be useful for path construction for the own CMP 446signer certificate, for the own TLS certificate (if any), when verifying peer 447CMP protection certificates, and when verifying newly enrolled certificates. 448The reference counts of those certificates handled successfully are increased. 449 450OSSL_CMP_CTX_get0_untrusted(OSSL_CMP_CTX *ctx) returns a pointer to the 451list of untrusted certs, which may be empty if unset. 452 | 269 Default is HMAC-SHA1 as per RFC 4210. 270 271=item B<OSSL_CMP_OPT_REVOCATION_REASON> 272 273 The reason code to be included in a Revocation Request (RR); 274 values: 0..10 (RFC 5210, 5.3.1) or -1 for none, which is the default. 275 276=item B<OSSL_CMP_OPT_IMPLICIT_CONFIRM> --- 168 unchanged lines hidden (view full) --- 445of intermediate CAs that may be useful for path construction for the own CMP 446signer certificate, for the own TLS certificate (if any), when verifying peer 447CMP protection certificates, and when verifying newly enrolled certificates. 448The reference counts of those certificates handled successfully are increased. 449 450OSSL_CMP_CTX_get0_untrusted(OSSL_CMP_CTX *ctx) returns a pointer to the 451list of untrusted certs, which may be empty if unset. 452 |
| 453OSSL_CMP_CTX_set1_cert() sets the CMP signer certificate 454related to the private key used for CMP message protection. | 453OSSL_CMP_CTX_set1_cert() sets the CMP signer certificate, also called protection 454certificate, related to the private key for signature-based message protection. |
| 455Therefore the public key of this I<cert> must correspond to 456the private key set before or thereafter via OSSL_CMP_CTX_set1_pkey(). 457When using signature-based protection of CMP request messages 458this CMP signer certificate will be included first in the extraCerts field. 459It serves as fallback reference certificate, see OSSL_CMP_CTX_set1_oldCert(). 460The subject of this I<cert> will be used as the sender field of outgoing 461messages, while the subject of any cert set via OSSL_CMP_CTX_set1_oldCert() 462and any value set via OSSL_CMP_CTX_set1_subjectName() are used as fallback. --- 13 unchanged lines hidden (view full) --- 476Calling this function is optional; by default a chain construction 477is performed on demand that is equivalent to calling this function 478with the I<candidates> and I<own_trusted> arguments being NULL. 479 480OSSL_CMP_CTX_set1_pkey() sets the client's private key corresponding to the 481CMP signer certificate set via OSSL_CMP_CTX_set1_cert(). 482This key is used create signature-based protection (protectionAlg = MSG_SIG_ALG) 483of outgoing messages | 455Therefore the public key of this I<cert> must correspond to 456the private key set before or thereafter via OSSL_CMP_CTX_set1_pkey(). 457When using signature-based protection of CMP request messages 458this CMP signer certificate will be included first in the extraCerts field. 459It serves as fallback reference certificate, see OSSL_CMP_CTX_set1_oldCert(). 460The subject of this I<cert> will be used as the sender field of outgoing 461messages, while the subject of any cert set via OSSL_CMP_CTX_set1_oldCert() 462and any value set via OSSL_CMP_CTX_set1_subjectName() are used as fallback. --- 13 unchanged lines hidden (view full) --- 476Calling this function is optional; by default a chain construction 477is performed on demand that is equivalent to calling this function 478with the I<candidates> and I<own_trusted> arguments being NULL. 479 480OSSL_CMP_CTX_set1_pkey() sets the client's private key corresponding to the 481CMP signer certificate set via OSSL_CMP_CTX_set1_cert(). 482This key is used create signature-based protection (protectionAlg = MSG_SIG_ALG) 483of outgoing messages |
| 484unless a PBM secret has been set via OSSL_CMP_CTX_set1_secretValue(). | 484unless a symmetric secret has been set via OSSL_CMP_CTX_set1_secretValue(). |
| 485The I<pkey> argument may be NULL to clear the entry. 486 | 485The I<pkey> argument may be NULL to clear the entry. 486 |
| 487OSSL_CMP_CTX_set1_secretValue() sets the byte string I<sec> with length I<len> 488as PBM secret in the given I<ctx> or clears it if the I<sec> argument is NULL. 489If present, this secret is used to create PBM-based protection of outgoing 490messages and to verify any PBM-based protection of incoming messages 491(protectionAlg = MSG_MAC_ALG). PBM stands for Password-Based MAC. 492PBM-based protection takes precedence over signature-based protection. | 487OSSL_CMP_CTX_set1_secretValue() sets in I<ctx> the byte string I<sec> of length 488I<len> to use as pre-shared secret, or clears it if the I<sec> argument is NULL. 489If present, this secret is used to create MAC-based authentication and integrity 490protection (rather than applying signature-based protection) 491of outgoing messages and to verify authenticity and integrity of incoming 492messages that have MAC-based protection (protectionAlg = C<MSG_MAC_ALG>). |
| 493 494OSSL_CMP_CTX_set1_referenceValue() sets the given referenceValue I<ref> with 495length I<len> in the given I<ctx> or clears it if the I<ref> argument is NULL. 496According to RFC 4210 section 5.1.1, if no value for the sender field in 497CMP message headers can be determined (i.e., no CMP signer certificate 498and no subject DN is set via OSSL_CMP_CTX_set1_subjectName() 499then the sender field will contain the NULL-DN 500and the senderKID field of the CMP message header must be set. 501When signature-based protection is used the senderKID will be set to 502the subjectKeyIdentifier of the CMP signer certificate as far as present. | 493 494OSSL_CMP_CTX_set1_referenceValue() sets the given referenceValue I<ref> with 495length I<len> in the given I<ctx> or clears it if the I<ref> argument is NULL. 496According to RFC 4210 section 5.1.1, if no value for the sender field in 497CMP message headers can be determined (i.e., no CMP signer certificate 498and no subject DN is set via OSSL_CMP_CTX_set1_subjectName() 499then the sender field will contain the NULL-DN 500and the senderKID field of the CMP message header must be set. 501When signature-based protection is used the senderKID will be set to 502the subjectKeyIdentifier of the CMP signer certificate as far as present. |
| 503If not present or when PBM-based protection is used | 503If not present or when MAC-based protection is used |
| 504the I<ref> value is taken as the fallback value for the senderKID. 505 506OSSL_CMP_CTX_set1_recipient() sets the recipient name that will be used in the 507PKIHeader of CMP request messages, i.e. the X509 name of the (CA) server. 508 509The recipient field in the header of a CMP message is mandatory. 510If not given explicitly the recipient is determined in the following order: 511the subject of the CMP server certificate set using OSSL_CMP_CTX_set1_srvCert(), --- 110 unchanged lines hidden (view full) --- 622needed any more. I<arg> may be NULL to clear the entry. 623 624OSSL_CMP_CTX_get_certConf_cb_arg() gets the argument, respectively the pointer 625to a structure containing arguments, previously set by 626OSSL_CMP_CTX_set_certConf_cb_arg(), or NULL if unset. 627 628OSSL_CMP_CTX_get_status() returns for client contexts the PKIstatus from 629the last received CertRepMessage or Revocation Response or error message: | 504the I<ref> value is taken as the fallback value for the senderKID. 505 506OSSL_CMP_CTX_set1_recipient() sets the recipient name that will be used in the 507PKIHeader of CMP request messages, i.e. the X509 name of the (CA) server. 508 509The recipient field in the header of a CMP message is mandatory. 510If not given explicitly the recipient is determined in the following order: 511the subject of the CMP server certificate set using OSSL_CMP_CTX_set1_srvCert(), --- 110 unchanged lines hidden (view full) --- 622needed any more. I<arg> may be NULL to clear the entry. 623 624OSSL_CMP_CTX_get_certConf_cb_arg() gets the argument, respectively the pointer 625to a structure containing arguments, previously set by 626OSSL_CMP_CTX_set_certConf_cb_arg(), or NULL if unset. 627 628OSSL_CMP_CTX_get_status() returns for client contexts the PKIstatus from 629the last received CertRepMessage or Revocation Response or error message: |
| 630=item B | 630=item B<OSSL_CMP_PKISTATUS_accepted> on successful receipt of a GENP message: |
| 631 632=over 4 633 634=item B<OSSL_CMP_PKISTATUS_request> 635 636if an IR/CR/KUR/RR/GENM request message could not be produced, 637 638=item B<OSSL_CMP_PKISTATUS_trans> --- 87 unchanged lines hidden (view full) --- 726Set up a CMP client context for sending requests and verifying responses: 727 728 cmp_ctx = OSSL_CMP_CTX_new(); 729 OSSL_CMP_CTX_set1_server(cmp_ctx, name_or_address); 730 OSSL_CMP_CTX_set1_serverPort(cmp_ctx, port_string); 731 OSSL_CMP_CTX_set1_serverPath(cmp_ctx, path_or_alias); 732 OSSL_CMP_CTX_set0_trustedStore(cmp_ctx, ts); 733 | 631 632=over 4 633 634=item B<OSSL_CMP_PKISTATUS_request> 635 636if an IR/CR/KUR/RR/GENM request message could not be produced, 637 638=item B<OSSL_CMP_PKISTATUS_trans> --- 87 unchanged lines hidden (view full) --- 726Set up a CMP client context for sending requests and verifying responses: 727 728 cmp_ctx = OSSL_CMP_CTX_new(); 729 OSSL_CMP_CTX_set1_server(cmp_ctx, name_or_address); 730 OSSL_CMP_CTX_set1_serverPort(cmp_ctx, port_string); 731 OSSL_CMP_CTX_set1_serverPath(cmp_ctx, path_or_alias); 732 OSSL_CMP_CTX_set0_trustedStore(cmp_ctx, ts); 733 |
| 734Set up client credentials for password-based protection (PBM): | 734Set up symmetric credentials for MAC-based message protection such as PBM: |
| 735 736 OSSL_CMP_CTX_set1_referenceValue(cmp_ctx, ref, ref_len); 737 OSSL_CMP_CTX_set1_secretValue(cmp_ctx, sec, sec_len); 738 739Set up the details for certificate requests: 740 741 OSSL_CMP_CTX_set1_subjectName(cmp_ctx, name); 742 OSSL_CMP_CTX_set0_newPkey(cmp_ctx, 1, initialKey); --- 64 unchanged lines hidden --- | 735 736 OSSL_CMP_CTX_set1_referenceValue(cmp_ctx, ref, ref_len); 737 OSSL_CMP_CTX_set1_secretValue(cmp_ctx, sec, sec_len); 738 739Set up the details for certificate requests: 740 741 OSSL_CMP_CTX_set1_subjectName(cmp_ctx, name); 742 OSSL_CMP_CTX_set0_newPkey(cmp_ctx, 1, initialKey); --- 64 unchanged lines hidden --- |