doc/man3/OSSL_CRMF_MSG_set0_validity.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 OSSL_CRMF_MSG_set0_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_set0_validity(OSSL_CRMF_MSG *crm,
  19                                  ASN1_TIME *notBefore, ASN1_TIME *notAfter);
  20
  21  int OSSL_CRMF_MSG_set_certReqId(OSSL_CRMF_MSG *crm, int rid);
  22
  23  int OSSL_CRMF_CERTTEMPLATE_fill(OSSL_CRMF_CERTTEMPLATE *tmpl,
  24                                  EVP_PKEY *pubkey,
  25                                  const X509_NAME *subject,
  26                                  const X509_NAME *issuer,
  27                                  const ASN1_INTEGER *serial);
  28
  29  int OSSL_CRMF_MSG_set0_extensions(OSSL_CRMF_MSG *crm, X509_EXTENSIONS *exts);
  30
  31  int OSSL_CRMF_MSG_push0_extension(OSSL_CRMF_MSG *crm, X509_EXTENSION *ext);
  32
  33  int OSSL_CRMF_MSG_create_popo(int meth, OSSL_CRMF_MSG *crm,
  34                                EVP_PKEY *pkey, const EVP_MD *digest,
  35                                OSSL_LIB_CTX *libctx, const char *propq);
  36
  37  int OSSL_CRMF_MSGS_verify_popo(const OSSL_CRMF_MSGS *reqs,
  38                                 int rid, int acceptRAVerified,
  39                                 OSSL_LIB_CTX *libctx, const char *propq);
  40
  41 =head1 DESCRIPTION
  42
  43 OSSL_CRMF_MSG_set0_validity() sets the I<notBefore> and I<notAfter> fields
  44 as validity constraints in the certTemplate of I<crm>.
  45 Any of the I<notBefore> and I<notAfter> parameters may be NULL,
  46 which means no constraint for the respective field.
  47 On success ownership of I<notBefore> and I<notAfter> is transferred to I<crm>.
  48
  49 OSSL_CRMF_MSG_set_certReqId() sets I<rid> as the certReqId of I<crm>.
  50
  51 OSSL_CRMF_CERTTEMPLATE_fill() sets those fields of the certTemplate I<tmpl>
  52 for which non-NULL values are provided: I<pubkey>, I<subject>, I<issuer>,
  53 and/or I<serial>.
  54 X.509 extensions may be set using OSSL_CRMF_MSG_set0_extensions().
  55 On success the reference counter of the I<pubkey> (if given) is incremented,
  56 while the I<subject>, I<issuer>, and I<serial> structures (if given) are copied.
  57
  58 OSSL_CRMF_MSG_set0_extensions() sets I<exts> as the extensions in the
  59 certTemplate of I<crm>. Frees any pre-existing ones and consumes I<exts>.
  60
  61 OSSL_CRMF_MSG_push0_extension() pushes the X509 extension I<ext> to the
  62 extensions in the certTemplate of I<crm>.  Consumes I<ext>.
  63
  64 OSSL_CRMF_MSG_create_popo() creates and sets the Proof-of-Possession (POPO)
  65 according to the method I<meth> in I<crm>.
  66 The library context I<libctx> and property query string I<propq>,
  67 may be NULL to select the defaults.
  68 In case the method is OSSL_CRMF_POPO_SIGNATURE the POPO is calculated
  69 using the private key I<pkey> and the digest method I<digest>,
  70 where the I<digest> argument is ignored if I<pkey> is of a type (such as
  71 Ed25519 and Ed448) that is implicitly associated with a digest algorithm.
  72
  73 I<meth> can be one of the following:
  74
  75 =over 8
  76
  77 =item * OSSL_CRMF_POPO_NONE       - RFC 4211, section 4, POP field omitted.
  78 CA/RA uses out-of-band method to verify POP. Note that servers may fail in this
  79 case, resulting for instance in HTTP error code 500 (Internal error).
  80
  81 =item * OSSL_CRMF_POPO_RAVERIFIED - RFC 4211, section 4, explicit indication
  82 that the RA has already verified the POP.
  83
  84 =item * OSSL_CRMF_POPO_SIGNATURE  - RFC 4211, section 4.1, only case 3 supported
  85 so far.
  86
  87 =item * OSSL_CRMF_POPO_KEYENC     - RFC 4211, section 4.2, only indirect method
  88 (subsequentMessage/enccert) supported,
  89 challenge-response exchange (challengeResp) not yet supported.
  90
  91 =item * OSSL_CRMF_POPO_KEYAGREE   - RFC 4211, section 4.3, not yet supported.
  92
  93 =back
  94
  95 OSSL_CRMF_MSGS_verify_popo verifies the Proof-of-Possession of the request with
  96 the given I<rid> in the list of I<reqs>. Optionally accepts RAVerified. It can
  97 make use of the library context I<libctx> and property query string I<propq>.
  98
  99 =head1 RETURN VALUES
 100
 101 All functions return 1 on success, 0 on error.
 102
 103 =head1 SEE ALSO
 104
 105 RFC 4211
 106
 107 =head1 HISTORY
 108
 109 The OpenSSL CRMF support was added in OpenSSL 3.0.
 110
 111 =head1 COPYRIGHT
 112
 113 Copyright 2007-2023 The OpenSSL Project Authors. All Rights Reserved.
 114
 115 Licensed under the Apache License 2.0 (the "License").  You may not use
 116 this file except in compliance with the License.  You can obtain a copy
 117 in the file LICENSE in the source distribution or at
 118 L<https://www.openssl.org/source/license.html>.
 119
 120 =cut