[thirdparty/openssl.git] / doc / man3 / OSSL_CMP_SRV_CTX_new.pod

=pod

=head1 NAME

OSSL_CMP_SRV_process_request,
OSSL_CMP_CTX_server_perform,
OSSL_CMP_SRV_CTX_new,
OSSL_CMP_SRV_CTX_free,
OSSL_CMP_SRV_cert_request_cb_t,
OSSL_CMP_SRV_rr_cb_t,
OSSL_CMP_SRV_certConf_cb_t,
OSSL_CMP_SRV_genm_cb_t,
OSSL_CMP_SRV_error_cb_t,
OSSL_CMP_SRV_pollReq_cb_t,
OSSL_CMP_SRV_CTX_init,
OSSL_CMP_SRV_delayed_delivery_cb_t,
OSSL_CMP_SRV_clean_transaction_cb_t,
OSSL_CMP_SRV_CTX_init_trans,
OSSL_CMP_SRV_CTX_get0_cmp_ctx,
OSSL_CMP_SRV_CTX_get0_custom_ctx,
OSSL_CMP_SRV_CTX_set_send_unprotected_errors,
OSSL_CMP_SRV_CTX_set_accept_unprotected,
OSSL_CMP_SRV_CTX_set_accept_raverified,
OSSL_CMP_SRV_CTX_set_grant_implicit_confirm
- generic functions to set up and control a CMP server

=head1 SYNOPSIS

 #include <openssl/cmp.h>

 OSSL_CMP_MSG *OSSL_CMP_SRV_process_request(OSSL_CMP_SRV_CTX *srv_ctx,
                                            const OSSL_CMP_MSG *req);
 OSSL_CMP_MSG *OSSL_CMP_CTX_server_perform(OSSL_CMP_CTX *client_ctx,
                                           const OSSL_CMP_MSG *req);
 OSSL_CMP_SRV_CTX *OSSL_CMP_SRV_CTX_new(OSSL_LIB_CTX *libctx, const char *propq);
 void OSSL_CMP_SRV_CTX_free(OSSL_CMP_SRV_CTX *srv_ctx);

 typedef OSSL_CMP_PKISI *(*OSSL_CMP_SRV_cert_request_cb_t)(
                                                 OSSL_CMP_SRV_CTX *srv_ctx,
                                                 const OSSL_CMP_MSG *req,
                                                 int certReqId,
                                                 const OSSL_CRMF_MSG *crm,
                                                 const X509_REQ *p10cr,
                                                 X509 **certOut,
                                                 STACK_OF(X509) **chainOut,
                                                 STACK_OF(X509) **caPubs);
 typedef OSSL_CMP_PKISI *(*OSSL_CMP_SRV_rr_cb_t)(OSSL_CMP_SRV_CTX *srv_ctx,
                                                 const OSSL_CMP_MSG *req,
                                                 const X509_NAME *issuer,
                                                 const ASN1_INTEGER *serial);
 typedef int (*OSSL_CMP_SRV_genm_cb_t)(OSSL_CMP_SRV_CTX *srv_ctx,
                                       const OSSL_CMP_MSG *req,
                                       STACK_OF(OSSL_CMP_ITAV) *in,
                                       STACK_OF(OSSL_CMP_ITAV) **out);
 typedef void (*OSSL_CMP_SRV_error_cb_t)(OSSL_CMP_SRV_CTX *srv_ctx,
                                         const OSSL_CMP_MSG *req,
                                         const OSSL_CMP_PKISI *statusInfo,
                                         const ASN1_INTEGER *errorCode,
                                         const OSSL_CMP_PKIFREETEXT *errorDetails);
 typedef int (*OSSL_CMP_SRV_certConf_cb_t)(OSSL_CMP_SRV_CTX *srv_ctx,
                                           const OSSL_CMP_MSG *req,
                                           int certReqId,
                                           const ASN1_OCTET_STRING *certHash,
                                           const OSSL_CMP_PKISI *si);
 typedef int (*OSSL_CMP_SRV_pollReq_cb_t)(OSSL_CMP_SRV_CTX *srv_ctx,
                                          const OSSL_CMP_MSG *req,
                                          int certReqId,
                                          OSSL_CMP_MSG **certReq,
                                          int64_t *check_after);
 int OSSL_CMP_SRV_CTX_init(OSSL_CMP_SRV_CTX *srv_ctx, void *custom_ctx,
                           OSSL_CMP_SRV_cert_request_cb_t process_cert_request,
                           OSSL_CMP_SRV_rr_cb_t process_rr,
                           OSSL_CMP_SRV_genm_cb_t process_genm,
                           OSSL_CMP_SRV_error_cb_t process_error,
                           OSSL_CMP_SRV_certConf_cb_t process_certConf,
                           OSSL_CMP_SRV_pollReq_cb_t process_pollReq);
 typedef int (*OSSL_CMP_SRV_delayed_delivery_cb_t)(OSSL_CMP_SRV_CTX *srv_ctx,
                                                   const OSSL_CMP_MSG *req);
 typedef int (*OSSL_CMP_SRV_clean_transaction_cb_t)(OSSL_CMP_SRV_CTX *srv_ctx,
                                                    const ASN1_OCTET_STRING *id);
 int OSSL_CMP_SRV_CTX_init_trans(OSSL_CMP_SRV_CTX *srv_ctx,
                                 OSSL_CMP_SRV_delayed_delivery_cb_t delay,
                                 OSSL_CMP_SRV_clean_transaction_cb_t clean);

 OSSL_CMP_CTX *OSSL_CMP_SRV_CTX_get0_cmp_ctx(const OSSL_CMP_SRV_CTX *srv_ctx);
 void *OSSL_CMP_SRV_CTX_get0_custom_ctx(const OSSL_CMP_SRV_CTX *srv_ctx);

 int OSSL_CMP_SRV_CTX_set_send_unprotected_errors(OSSL_CMP_SRV_CTX *srv_ctx,
                                                  int val);
 int OSSL_CMP_SRV_CTX_set_accept_unprotected(OSSL_CMP_SRV_CTX *srv_ctx, int val);
 int OSSL_CMP_SRV_CTX_set_accept_raverified(OSSL_CMP_SRV_CTX *srv_ctx, int val);
 int OSSL_CMP_SRV_CTX_set_grant_implicit_confirm(OSSL_CMP_SRV_CTX *srv_ctx,
                                                 int val);

=head1 DESCRIPTION

OSSL_CMP_SRV_process_request() implements the generic aspects of a CMP server.
Its arguments are the B<OSSL_CMP_SRV_CTX> I<srv_ctx> and the CMP request message
I<req>. It does the typical generic checks on I<req>, calls
the respective callback function (if present) for more specific processing,
and then assembles a result message, which may be a CMP error message.
If after return of the function the expression
I<OSSL_CMP_CTX_get_status(OSSL_CMP_SRV_CTX_get0_cmp_ctx(srv_ctx))> yields -1
then the function has closed the current transaction,
which may be due to normal successful end of the transaction or due to an error.

OSSL_CMP_CTX_server_perform() is an interface to
OSSL_CMP_SRV_process_request() that can be used by a CMP client
in the same way as L<OSSL_CMP_MSG_http_perform(3)>.
The B<OSSL_CMP_SRV_CTX> must be set as I<transfer_cb_arg> of I<client_ctx>.

OSSL_CMP_SRV_CTX_new() creates and initializes an B<OSSL_CMP_SRV_CTX> structure
associated with the library context I<libctx> and property query string
I<propq>, both of which may be NULL to select the defaults.

OSSL_CMP_SRV_CTX_free() deletes the given I<srv_ctx>.

OSSL_CMP_SRV_CTX_init() sets in the given I<srv_ctx> a custom server context
pointer as well as callback functions performing the specific processing of CMP
certificate requests, revocation requests, certificate confirmation requests,
general messages, error messages, and poll requests.
All arguments except I<srv_ctx> may be NULL.
If a callback for some message type is not given this means that the respective
type of CMP message is not supported by the server.

OSSL_CMP_SRV_CTX_init_trans() sets in I<srv_ctx> the optional callback
functions for initiating delayed delivery and cleaning up a transaction.
If the <delay> function is NULL then delivery of responses is never delayed.
Otherwise I<delay> takes a custom server context and a request message as input.
It must return 1 if delivery of the respecive response shall be delayed,
0 if not, and -1 on error.
If the <clean> function is NULL then no specific cleanup is performed.
Otherwise I<clean> takes a custom server context and a transaction ID pointer
as input, where the pointer is NULL in case a new transaction is being started
and otherwise provides the ID of the transaction being terminated.
The <clean> function should reset the respective portions of the state
and free related memory.
It must return 1 on success and 0 on error.

OSSL_CMP_SRV_CTX_get0_cmp_ctx() returns the B<OSSL_CMP_CTX> from the I<srv_ctx>.

OSSL_CMP_SRV_CTX_get0_custom_ctx() returns the custom server context from
I<srv_ctx> that has been set using OSSL_CMP_SRV_CTX_init().

OSSL_CMP_SRV_CTX_set_send_unprotected_errors() enables sending error messages
and other forms of negative responses unprotected.

OSSL_CMP_SRV_CTX_set_accept_unprotected() enables acceptance of requests
without protection of with invalid protection.

OSSL_CMP_SRV_CTX_set_accept_raverified() enables acceptance of ir/cr/kur
messages with POPO 'RAVerified'.

OSSL_CMP_SRV_CTX_set_grant_implicit_confirm() enables granting implicit
confirmation of newly enrolled certificates if requested.

=head1 NOTES

CMP is defined in RFC 4210 (and CRMF in RFC 4211).

So far the CMP server implementation is limited to one request per CMP message
(and consequently to at most one response component per CMP message).

=head1 RETURN VALUES

OSSL_CMP_SRV_CTX_new() returns a B<OSSL_CMP_SRV_CTX> structure on success,
NULL on error.

OSSL_CMP_SRV_CTX_free() does not return a value.

OSSL_CMP_SRV_CTX_get0_cmp_ctx() returns a B<OSSL_CMP_CTX> structure on success,
NULL on error.

OSSL_CMP_SRV_CTX_get0_custom_ctx() returns the custom server context
that has been set using OSSL_CMP_SRV_CTX_init().

All other functions return 1 on success, 0 on error.

=head1 HISTORY

The OpenSSL CMP support was added in OpenSSL 3.0.

OSSL_CMP_SRV_CTX_init_trans()
supporting delayed delivery of all types of response messages
was added in OpenSSL 3.3.

=head1 COPYRIGHT

Copyright 2007-2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License").  You may not use
this file except in compliance with the License.  You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.

=cut
Commit	Line	Data
62dcd2aa DDO	1	=pod
	2
	3	=head1 NAME
	4
	5	OSSL_CMP_SRV_process_request,
	6	OSSL_CMP_CTX_server_perform,
	7	OSSL_CMP_SRV_CTX_new,
	8	OSSL_CMP_SRV_CTX_free,
	9	OSSL_CMP_SRV_cert_request_cb_t,
	10	OSSL_CMP_SRV_rr_cb_t,
	11	OSSL_CMP_SRV_certConf_cb_t,
	12	OSSL_CMP_SRV_genm_cb_t,
	13	OSSL_CMP_SRV_error_cb_t,
	14	OSSL_CMP_SRV_pollReq_cb_t,
	15	OSSL_CMP_SRV_CTX_init,
bedffe17 DDO	16	OSSL_CMP_SRV_delayed_delivery_cb_t,
	17	OSSL_CMP_SRV_clean_transaction_cb_t,
	18	OSSL_CMP_SRV_CTX_init_trans,
62dcd2aa DDO	19	OSSL_CMP_SRV_CTX_get0_cmp_ctx,
	20	OSSL_CMP_SRV_CTX_get0_custom_ctx,
	21	OSSL_CMP_SRV_CTX_set_send_unprotected_errors,
	22	OSSL_CMP_SRV_CTX_set_accept_unprotected,
	23	OSSL_CMP_SRV_CTX_set_accept_raverified,
	24	OSSL_CMP_SRV_CTX_set_grant_implicit_confirm
	25	- generic functions to set up and control a CMP server
	26
	27	=head1 SYNOPSIS
	28
	29	#include <openssl/cmp.h>
	30
	31	OSSL_CMP_MSG OSSL_CMP_SRV_process_request(OSSL_CMP_SRV_CTX srv_ctx,
	32	const OSSL_CMP_MSG *req);
	33	OSSL_CMP_MSG OSSL_CMP_CTX_server_perform(OSSL_CMP_CTX client_ctx,
	34	const OSSL_CMP_MSG *req);
b4250010	35	OSSL_CMP_SRV_CTX OSSL_CMP_SRV_CTX_new(OSSL_LIB_CTX libctx, const char *propq);
62dcd2aa DDO	36	void OSSL_CMP_SRV_CTX_free(OSSL_CMP_SRV_CTX *srv_ctx);
	37
	38	typedef OSSL_CMP_PKISI (OSSL_CMP_SRV_cert_request_cb_t)(
	39	OSSL_CMP_SRV_CTX *srv_ctx,
	40	const OSSL_CMP_MSG *req,
	41	int certReqId,
	42	const OSSL_CRMF_MSG *crm,
	43	const X509_REQ *p10cr,
	44	X509 **certOut,
	45	STACK_OF(X509) **chainOut,
	46	STACK_OF(X509) **caPubs);
	47	typedef OSSL_CMP_PKISI (OSSL_CMP_SRV_rr_cb_t)(OSSL_CMP_SRV_CTX *srv_ctx,
	48	const OSSL_CMP_MSG *req,
	49	const X509_NAME *issuer,
	50	const ASN1_INTEGER *serial);
	51	typedef int (OSSL_CMP_SRV_genm_cb_t)(OSSL_CMP_SRV_CTX srv_ctx,
	52	const OSSL_CMP_MSG *req,
	53	STACK_OF(OSSL_CMP_ITAV) *in,
	54	STACK_OF(OSSL_CMP_ITAV) **out);
	55	typedef void (OSSL_CMP_SRV_error_cb_t)(OSSL_CMP_SRV_CTX srv_ctx,
	56	const OSSL_CMP_MSG *req,
	57	const OSSL_CMP_PKISI *statusInfo,
	58	const ASN1_INTEGER *errorCode,
	59	const OSSL_CMP_PKIFREETEXT *errorDetails);
	60	typedef int (OSSL_CMP_SRV_certConf_cb_t)(OSSL_CMP_SRV_CTX srv_ctx,
	61	const OSSL_CMP_MSG *req,
	62	int certReqId,
	63	const ASN1_OCTET_STRING *certHash,
	64	const OSSL_CMP_PKISI *si);
	65	typedef int (OSSL_CMP_SRV_pollReq_cb_t)(OSSL_CMP_SRV_CTX srv_ctx,
	66	const OSSL_CMP_MSG *req,
	67	int certReqId,
	68	OSSL_CMP_MSG **certReq,
	69	int64_t *check_after);
	70	int OSSL_CMP_SRV_CTX_init(OSSL_CMP_SRV_CTX srv_ctx, void custom_ctx,
	71	OSSL_CMP_SRV_cert_request_cb_t process_cert_request,
	72	OSSL_CMP_SRV_rr_cb_t process_rr,
	73	OSSL_CMP_SRV_genm_cb_t process_genm,
	74	OSSL_CMP_SRV_error_cb_t process_error,
	75	OSSL_CMP_SRV_certConf_cb_t process_certConf,
	76	OSSL_CMP_SRV_pollReq_cb_t process_pollReq);
bedffe17 DDO	77	typedef int (OSSL_CMP_SRV_delayed_delivery_cb_t)(OSSL_CMP_SRV_CTX srv_ctx,
	78	const OSSL_CMP_MSG *req);
	79	typedef int (OSSL_CMP_SRV_clean_transaction_cb_t)(OSSL_CMP_SRV_CTX srv_ctx,
	80	const ASN1_OCTET_STRING *id);
	81	int OSSL_CMP_SRV_CTX_init_trans(OSSL_CMP_SRV_CTX *srv_ctx,
	82	OSSL_CMP_SRV_delayed_delivery_cb_t delay,
	83	OSSL_CMP_SRV_clean_transaction_cb_t clean);
62dcd2aa DDO	84
	85	OSSL_CMP_CTX OSSL_CMP_SRV_CTX_get0_cmp_ctx(const OSSL_CMP_SRV_CTX srv_ctx);
	86	void OSSL_CMP_SRV_CTX_get0_custom_ctx(const OSSL_CMP_SRV_CTX srv_ctx);
	87
	88	int OSSL_CMP_SRV_CTX_set_send_unprotected_errors(OSSL_CMP_SRV_CTX *srv_ctx,
	89	int val);
	90	int OSSL_CMP_SRV_CTX_set_accept_unprotected(OSSL_CMP_SRV_CTX *srv_ctx, int val);
	91	int OSSL_CMP_SRV_CTX_set_accept_raverified(OSSL_CMP_SRV_CTX *srv_ctx, int val);
	92	int OSSL_CMP_SRV_CTX_set_grant_implicit_confirm(OSSL_CMP_SRV_CTX *srv_ctx,
	93	int val);
	94
	95	=head1 DESCRIPTION
	96
	97	OSSL_CMP_SRV_process_request() implements the generic aspects of a CMP server.
5a2ba207 DDO	98	Its arguments are the B<OSSL_CMP_SRV_CTX> I<srv_ctx> and the CMP request message
5a2ba207 DDO	99	I<req>. It does the typical generic checks on I<req>, calls
62dcd2aa DDO	100	the respective callback function (if present) for more specific processing,
62dcd2aa DDO	101	and then assembles a result message, which may be a CMP error message.
19f97fe6 DDO	102	If after return of the function the expression
	103	I<OSSL_CMP_CTX_get_status(OSSL_CMP_SRV_CTX_get0_cmp_ctx(srv_ctx))> yields -1
	104	then the function has closed the current transaction,
	105	which may be due to normal successful end of the transaction or due to an error.
62dcd2aa DDO	106
62dcd2aa DDO	107	OSSL_CMP_CTX_server_perform() is an interface to
f5f4fbaa RL	108	OSSL_CMP_SRV_process_request() that can be used by a CMP client
f5f4fbaa RL	109	in the same way as L<OSSL_CMP_MSG_http_perform(3)>.
5a2ba207	110	The B<OSSL_CMP_SRV_CTX> must be set as I<transfer_cb_arg> of I<client_ctx>.
62dcd2aa	111
1a7cd250	112	OSSL_CMP_SRV_CTX_new() creates and initializes an B<OSSL_CMP_SRV_CTX> structure
57cd10dd	113	associated with the library context I<libctx> and property query string
1a7cd250	114	I<propq>, both of which may be NULL to select the defaults.
62dcd2aa	115
5a2ba207	116	OSSL_CMP_SRV_CTX_free() deletes the given I<srv_ctx>.
62dcd2aa	117
5a2ba207	118	OSSL_CMP_SRV_CTX_init() sets in the given I<srv_ctx> a custom server context
62dcd2aa DDO	119	pointer as well as callback functions performing the specific processing of CMP
	120	certificate requests, revocation requests, certificate confirmation requests,
	121	general messages, error messages, and poll requests.
5a2ba207	122	All arguments except I<srv_ctx> may be NULL.
62dcd2aa DDO	123	If a callback for some message type is not given this means that the respective
	124	type of CMP message is not supported by the server.
	125
bedffe17 DDO	126	OSSL_CMP_SRV_CTX_init_trans() sets in I<srv_ctx> the optional callback
	127	functions for initiating delayed delivery and cleaning up a transaction.
	128	If the <delay> function is NULL then delivery of responses is never delayed.
	129	Otherwise I<delay> takes a custom server context and a request message as input.
	130	It must return 1 if delivery of the respecive response shall be delayed,
	131	0 if not, and -1 on error.
	132	If the <clean> function is NULL then no specific cleanup is performed.
	133	Otherwise I<clean> takes a custom server context and a transaction ID pointer
	134	as input, where the pointer is NULL in case a new transaction is being started
	135	and otherwise provides the ID of the transaction being terminated.
	136	The <clean> function should reset the respective portions of the state
	137	and free related memory.
	138	It must return 1 on success and 0 on error.
192bfec4	139
5a2ba207	140	OSSL_CMP_SRV_CTX_get0_cmp_ctx() returns the B<OSSL_CMP_CTX> from the I<srv_ctx>.
62dcd2aa DDO	141
62dcd2aa DDO	142	OSSL_CMP_SRV_CTX_get0_custom_ctx() returns the custom server context from
f5f4fbaa	143	I<srv_ctx> that has been set using OSSL_CMP_SRV_CTX_init().
62dcd2aa DDO	144
	145	OSSL_CMP_SRV_CTX_set_send_unprotected_errors() enables sending error messages
	146	and other forms of negative responses unprotected.
	147
	148	OSSL_CMP_SRV_CTX_set_accept_unprotected() enables acceptance of requests
	149	without protection of with invalid protection.
	150
	151	OSSL_CMP_SRV_CTX_set_accept_raverified() enables acceptance of ir/cr/kur
	152	messages with POPO 'RAVerified'.
	153
	154	OSSL_CMP_SRV_CTX_set_grant_implicit_confirm() enables granting implicit
	155	confirmation of newly enrolled certificates if requested.
	156
	157	=head1 NOTES
	158
	159	CMP is defined in RFC 4210 (and CRMF in RFC 4211).
	160
7e765f46 DDO	161	So far the CMP server implementation is limited to one request per CMP message
	162	(and consequently to at most one response component per CMP message).
	163
62dcd2aa DDO	164	=head1 RETURN VALUES
	165
	166	OSSL_CMP_SRV_CTX_new() returns a B<OSSL_CMP_SRV_CTX> structure on success,
	167	NULL on error.
	168
	169	OSSL_CMP_SRV_CTX_free() does not return a value.
	170
	171	OSSL_CMP_SRV_CTX_get0_cmp_ctx() returns a B<OSSL_CMP_CTX> structure on success,
	172	NULL on error.
	173
	174	OSSL_CMP_SRV_CTX_get0_custom_ctx() returns the custom server context
f5f4fbaa	175	that has been set using OSSL_CMP_SRV_CTX_init().
62dcd2aa DDO	176
	177	All other functions return 1 on success, 0 on error.
	178
	179	=head1 HISTORY
	180
	181	The OpenSSL CMP support was added in OpenSSL 3.0.
	182
bedffe17 DDO	183	OSSL_CMP_SRV_CTX_init_trans()
	184	supporting delayed delivery of all types of response messages
	185	was added in OpenSSL 3.3.
	186
62dcd2aa DDO	187	=head1 COPYRIGHT
62dcd2aa DDO	188
4333b89f	189	Copyright 2007-2021 The OpenSSL Project Authors. All Rights Reserved.
62dcd2aa DDO	190
	191	Licensed under the Apache License 2.0 (the "License"). You may not use
	192	this file except in compliance with the License. You can obtain a copy
	193	in the file LICENSE in the source distribution or at
	194	L<https://www.openssl.org/source/license.html>.
	195
	196	=cut