2544c6577526a5b935316ecb5d9e43466cf455b0
[openssl.git] / doc / man3 / OSSL_CRMF_MSG_set_validity.pod
1 =pod
2
3 =head1 NAME
4
5 OSSL_CRMF_MSG_set_validity,
6 OSSL_CRMF_MSG_set_certReqId,
7 OSSL_CRMF_CERTTEMPLATE_fill,
8 OSSL_CRMF_MSG_set0_extensions,
9 OSSL_CRMF_MSG_push0_extension,
10 OSSL_CRMF_MSG_create_popo,
11 OSSL_CRMF_MSGS_verify_popo
12 - functions populating and verifying CRMF CertReqMsg structures
13
14 =head1 SYNOPSIS
15
16  #include <openssl/crmf.h>
17
18  int OSSL_CRMF_MSG_set_validity(OSSL_CRMF_MSG *crm, time_t from, time_t to);
19
20  int OSSL_CRMF_MSG_set_certReqId(OSSL_CRMF_MSG *crm, int rid);
21
22  int OSSL_CRMF_CERTTEMPLATE_fill(OSSL_CRMF_CERTTEMPLATE *tmpl,
23                                  EVP_PKEY *pubkey,
24                                  const X509_NAME *subject,
25                                  const X509_NAME *issuer,
26                                  const ASN1_INTEGER *serial);
27
28  int OSSL_CRMF_MSG_set0_extensions(OSSL_CRMF_MSG *crm, X509_EXTENSIONS *exts);
29
30  int OSSL_CRMF_MSG_push0_extension(OSSL_CRMF_MSG *crm, X509_EXTENSION *ext);
31
32  int OSSL_CRMF_MSG_create_popo(OSSL_CRMF_MSG *crm, EVP_PKEY *pkey,
33                                int dgst, int ppmtd);
34
35  int OSSL_CRMF_MSGS_verify_popo(const OSSL_CRMF_MSGS *reqs,
36                                 int rid, int acceptRAVerified);
37
38 =head1 DESCRIPTION
39
40 OSSL_CRMF_MSG_set_validity() sets B<from> as notBefore and B<to> as notAfter
41 as the validity in the certTemplate of B<crm>.
42
43 OSSL_CRMF_MSG_set_certReqId() sets B<rid> as the certReqId of B<crm>.
44
45 OSSL_CRMF_CERTTEMPLATE_fill() sets those fields of the certTemplate B<tmpl>
46 for which non-NULL values are provided: B<pubkey>, B<subject>, B<issuer>,
47 and/or B<serial>.
48 On success the reference counter of the B<pubkey> (if given) is incremented,
49 while the B<subject>, B<issuer>, and B<serial> structures (if given) are copied.
50
51 OSSL_CRMF_MSG_set0_extensions() sets B<exts> as the extensions in the
52 certTemplate of B<crm>. Frees any pre-existing ones and consumes B<exts>.
53
54 OSSL_CRMF_MSG_push0_extension() pushes the X509 extension B<ext> to the
55 extensions in the certTemplate of B<crm>.  Consumes B<ext>.
56
57 OSSL_CRMF_MSG_create_popo() creates and sets the Proof-of-Possession (POPO)
58 according to the method B<ppmtd> in B<crm>.
59 In case the method is OSSL_CRMF_POPO_SIGNATURE the POPO is calculated
60 using the private B<pkey> and the digest algorithm NID B<dgst>.
61
62 B<ppmtd> can be one of the following:
63
64 =over 8
65
66 =item * OSSL_CRMF_POPO_NONE       - RFC 4211, section 4, POP field omitted.
67 CA/RA uses out-of-band method to verify POP. Note that servers may fail in this
68 case, resulting for instance in HTTP error code 500 (Internal error).
69
70 =item * OSSL_CRMF_POPO_RAVERIFIED - RFC 4211, section 4, explicit indication
71 that the RA has already verified the POP.
72
73 =item * OSSL_CRMF_POPO_SIGNATURE  - RFC 4211, section 4.1, only case 3 supported
74 so far.
75
76 =item * OSSL_CRMF_POPO_KEYENC     - RFC 4211, section 4.2, only indirect method
77 (subsequentMessage/enccert) supported,
78 challenge-response exchange (challengeResp) not yet supported.
79
80 =item * OSSL_CRMF_POPO_KEYAGREE   - RFC 4211, section 4.3, not yet supported.
81
82 =back
83
84 OSSL_CRMF_MSGS_verify_popo verifies the Proof-of-Possession of the request with
85 the given B<rid> in the list of B<reqs>. Optionally accepts RAVerified.
86
87 =head1 RETURN VALUES
88
89 All functions return 1 on success, 0 on error.
90
91 =head1 SEE ALSO
92
93 RFC 4211
94
95 =head1 HISTORY
96
97 The OpenSSL CRMF support was added in OpenSSL 3.0.
98
99 =head1 COPYRIGHT
100
101 Copyright 2007-2019 The OpenSSL Project Authors. All Rights Reserved.
102
103 Licensed under the Apache License 2.0 (the "License").  You may not use
104 this file except in compliance with the License.  You can obtain a copy
105 in the file LICENSE in the source distribution or at
106 L<https://www.openssl.org/source/license.html>.
107
108 =cut