[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_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(void);
 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);

 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.
It does the typical generic checks on the given request message, calls
the respective callback function (if present) for more specific processing,
and then assembles a result message, which may be a CMP error message.

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

OSSL_CMP_SRV_CTX_new() creates and initializes an OSSL_CMP_SRV_CTX structure
and returns a pointer to it on success, NULL on error.

OSSL_CMP_SRV_CTX_free() deletes the given B<srv_ctx>.

OSSL_CMP_SRV_CTX_init() sets in the given B<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 B<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_get0_cmp_ctx() returns the B<OSSL_CMP_CTX> from the B<srv_ctx>.

OSSL_CMP_SRV_CTX_get0_custom_ctx() returns the custom server context from
B<srv_ctx> that has been set using B<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 B<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.

=head1 COPYRIGHT

Copyright 2007-2019 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,
	16	OSSL_CMP_SRV_CTX_get0_cmp_ctx,
	17	OSSL_CMP_SRV_CTX_get0_custom_ctx,
	18	OSSL_CMP_SRV_CTX_set_send_unprotected_errors,
	19	OSSL_CMP_SRV_CTX_set_accept_unprotected,
	20	OSSL_CMP_SRV_CTX_set_accept_raverified,
	21	OSSL_CMP_SRV_CTX_set_grant_implicit_confirm
	22	- generic functions to set up and control a CMP server
	23
	24	=head1 SYNOPSIS
	25
	26	#include <openssl/cmp.h>
	27
	28	OSSL_CMP_MSG OSSL_CMP_SRV_process_request(OSSL_CMP_SRV_CTX srv_ctx,
	29	const OSSL_CMP_MSG *req);
	30	OSSL_CMP_MSG OSSL_CMP_CTX_server_perform(OSSL_CMP_CTX client_ctx,
	31	const OSSL_CMP_MSG *req);
	32	OSSL_CMP_SRV_CTX *OSSL_CMP_SRV_CTX_new(void);
	33	void OSSL_CMP_SRV_CTX_free(OSSL_CMP_SRV_CTX *srv_ctx);
	34
	35	typedef OSSL_CMP_PKISI (OSSL_CMP_SRV_cert_request_cb_t)(
	36	OSSL_CMP_SRV_CTX *srv_ctx,
	37	const OSSL_CMP_MSG *req,
	38	int certReqId,
	39	const OSSL_CRMF_MSG *crm,
	40	const X509_REQ *p10cr,
	41	X509 **certOut,
	42	STACK_OF(X509) **chainOut,
	43	STACK_OF(X509) **caPubs);
	44	typedef OSSL_CMP_PKISI (OSSL_CMP_SRV_rr_cb_t)(OSSL_CMP_SRV_CTX *srv_ctx,
	45	const OSSL_CMP_MSG *req,
	46	const X509_NAME *issuer,
	47	const ASN1_INTEGER *serial);
	48	typedef int (OSSL_CMP_SRV_genm_cb_t)(OSSL_CMP_SRV_CTX srv_ctx,
	49	const OSSL_CMP_MSG *req,
	50	STACK_OF(OSSL_CMP_ITAV) *in,
	51	STACK_OF(OSSL_CMP_ITAV) **out);
	52	typedef void (OSSL_CMP_SRV_error_cb_t)(OSSL_CMP_SRV_CTX srv_ctx,
	53	const OSSL_CMP_MSG *req,
	54	const OSSL_CMP_PKISI *statusInfo,
	55	const ASN1_INTEGER *errorCode,
	56	const OSSL_CMP_PKIFREETEXT *errorDetails);
	57	typedef int (OSSL_CMP_SRV_certConf_cb_t)(OSSL_CMP_SRV_CTX srv_ctx,
	58	const OSSL_CMP_MSG *req,
	59	int certReqId,
	60	const ASN1_OCTET_STRING *certHash,
	61	const OSSL_CMP_PKISI *si);
	62	typedef int (OSSL_CMP_SRV_pollReq_cb_t)(OSSL_CMP_SRV_CTX srv_ctx,
	63	const OSSL_CMP_MSG *req,
	64	int certReqId,
65	OSSL_CMP_MSG **certReq,
66	int64_t *check_after);
67	int OSSL_CMP_SRV_CTX_init(OSSL_CMP_SRV_CTX srv_ctx, void custom_ctx,
68	OSSL_CMP_SRV_cert_request_cb_t process_cert_request,
69	OSSL_CMP_SRV_rr_cb_t process_rr,
70	OSSL_CMP_SRV_genm_cb_t process_genm,
71	OSSL_CMP_SRV_error_cb_t process_error,
72	OSSL_CMP_SRV_certConf_cb_t process_certConf,
73	OSSL_CMP_SRV_pollReq_cb_t process_pollReq);
74
75	OSSL_CMP_CTX OSSL_CMP_SRV_CTX_get0_cmp_ctx(const OSSL_CMP_SRV_CTX srv_ctx);
76	void OSSL_CMP_SRV_CTX_get0_custom_ctx(const OSSL_CMP_SRV_CTX srv_ctx);
77
78	int OSSL_CMP_SRV_CTX_set_send_unprotected_errors(OSSL_CMP_SRV_CTX *srv_ctx,
79	int val);
80	int OSSL_CMP_SRV_CTX_set_accept_unprotected(OSSL_CMP_SRV_CTX *srv_ctx, int val);
81	int OSSL_CMP_SRV_CTX_set_accept_raverified(OSSL_CMP_SRV_CTX *srv_ctx, int val);
82	int OSSL_CMP_SRV_CTX_set_grant_implicit_confirm(OSSL_CMP_SRV_CTX *srv_ctx,
83	int val);
84
85	=head1 DESCRIPTION
86
87	OSSL_CMP_SRV_process_request() implements the generic aspects of a CMP server.
88	It does the typical generic checks on the given request message, calls
89	the respective callback function (if present) for more specific processing,
90	and then assembles a result message, which may be a CMP error message.
91
92	OSSL_CMP_CTX_server_perform() is an interface to
93	B<OSSL_CMP_SRV_process_request()> that can be used by a CMP client
94	in the same way as B<OSSL_CMP_MSG_http_perform()>.
95	The B<OSSL_CMP_SRV_CTX> must be set as B<transfer_cb_arg> of B<client_ctx>.
96
97	OSSL_CMP_SRV_CTX_new() creates and initializes an OSSL_CMP_SRV_CTX structure
98	and returns a pointer to it on success, NULL on error.
99
100	OSSL_CMP_SRV_CTX_free() deletes the given B<srv_ctx>.
101
102	OSSL_CMP_SRV_CTX_init() sets in the given B<srv_ctx> a custom server context
103	pointer as well as callback functions performing the specific processing of CMP
104	certificate requests, revocation requests, certificate confirmation requests,
105	general messages, error messages, and poll requests.
106	All arguments except B<srv_ctx> may be NULL.
107	If a callback for some message type is not given this means that the respective
108	type of CMP message is not supported by the server.
109
110	OSSL_CMP_SRV_CTX_get0_cmp_ctx() returns the B<OSSL_CMP_CTX> from the B<srv_ctx>.
111
112	OSSL_CMP_SRV_CTX_get0_custom_ctx() returns the custom server context from
113	B<srv_ctx> that has been set using B<OSSL_CMP_SRV_CTX_init>.
114
115	OSSL_CMP_SRV_CTX_set_send_unprotected_errors() enables sending error messages
116	and other forms of negative responses unprotected.
117
118	OSSL_CMP_SRV_CTX_set_accept_unprotected() enables acceptance of requests
119	without protection of with invalid protection.
120
121	OSSL_CMP_SRV_CTX_set_accept_raverified() enables acceptance of ir/cr/kur
122	messages with POPO 'RAVerified'.
123
124	OSSL_CMP_SRV_CTX_set_grant_implicit_confirm() enables granting implicit
125	confirmation of newly enrolled certificates if requested.
126
127	=head1 NOTES
128
129	CMP is defined in RFC 4210 (and CRMF in RFC 4211).
130
7e765f46 DDO	131	So far the CMP server implementation is limited to one request per CMP message
	132	(and consequently to at most one response component per CMP message).
	133
62dcd2aa DDO	134	=head1 RETURN VALUES
	135
	136	OSSL_CMP_SRV_CTX_new() returns a B<OSSL_CMP_SRV_CTX> structure on success,
	137	NULL on error.
	138
	139	OSSL_CMP_SRV_CTX_free() does not return a value.
	140
	141	OSSL_CMP_SRV_CTX_get0_cmp_ctx() returns a B<OSSL_CMP_CTX> structure on success,
	142	NULL on error.
	143
	144	OSSL_CMP_SRV_CTX_get0_custom_ctx() returns the custom server context
	145	that has been set using B<OSSL_CMP_SRV_CTX_init>.
	146
	147	All other functions return 1 on success, 0 on error.
	148
	149	=head1 HISTORY
	150
	151	The OpenSSL CMP support was added in OpenSSL 3.0.
	152
	153	=head1 COPYRIGHT
	154
	155	Copyright 2007-2019 The OpenSSL Project Authors. All Rights Reserved.
	156
	157	Licensed under the Apache License 2.0 (the "License"). You may not use
	158	this file except in compliance with the License. You can obtain a copy
	159	in the file LICENSE in the source distribution or at
	160	L<https://www.openssl.org/source/license.html>.
	161
	162	=cut