Mini Shell

.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "OSSL_CRMF_MSG_SET0_VALIDITY 3ossl"
.TH OSSL_CRMF_MSG_SET0_VALIDITY 3ossl "2024-09-03" "3.1.7+quic" "OpenSSL"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
OSSL_CRMF_MSG_set0_validity,
OSSL_CRMF_MSG_set_certReqId,
OSSL_CRMF_CERTTEMPLATE_fill,
OSSL_CRMF_MSG_set0_extensions,
OSSL_CRMF_MSG_push0_extension,
OSSL_CRMF_MSG_create_popo,
OSSL_CRMF_MSGS_verify_popo
\&\- functions populating and verifying CRMF CertReqMsg structures
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/crmf.h>
\&
\& int OSSL_CRMF_MSG_set0_validity(OSSL_CRMF_MSG *crm,
\&                                 ASN1_TIME *notBefore, ASN1_TIME *notAfter);
\&
\& int OSSL_CRMF_MSG_set_certReqId(OSSL_CRMF_MSG *crm, int rid);
\&
\& int OSSL_CRMF_CERTTEMPLATE_fill(OSSL_CRMF_CERTTEMPLATE *tmpl,
\&                                 EVP_PKEY *pubkey,
\&                                 const X509_NAME *subject,
\&                                 const X509_NAME *issuer,
\&                                 const ASN1_INTEGER *serial);
\&
\& int OSSL_CRMF_MSG_set0_extensions(OSSL_CRMF_MSG *crm, X509_EXTENSIONS *exts);
\&
\& int OSSL_CRMF_MSG_push0_extension(OSSL_CRMF_MSG *crm, X509_EXTENSION *ext);
\&
\& int OSSL_CRMF_MSG_create_popo(int meth, OSSL_CRMF_MSG *crm,
\&                               EVP_PKEY *pkey, const EVP_MD *digest,
\&                               OSSL_LIB_CTX *libctx, const char *propq);
\&
\& int OSSL_CRMF_MSGS_verify_popo(const OSSL_CRMF_MSGS *reqs,
\&                                int rid, int acceptRAVerified,
\&                                OSSL_LIB_CTX *libctx, const char *propq);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBOSSL_CRMF_MSG_set0_validity()\fR sets the \fInotBefore\fR and \fInotAfter\fR fields
as validity constraints in the certTemplate of \fIcrm\fR.
Any of the \fInotBefore\fR and \fInotAfter\fR parameters may be \s-1NULL,\s0
which means no constraint for the respective field.
On success ownership of \fInotBefore\fR and \fInotAfter\fR is transferred to \fIcrm\fR.
.PP
\&\fBOSSL_CRMF_MSG_set_certReqId()\fR sets \fIrid\fR as the certReqId of \fIcrm\fR.
.PP
\&\fBOSSL_CRMF_CERTTEMPLATE_fill()\fR sets those fields of the certTemplate \fItmpl\fR
for which non-NULL values are provided: \fIpubkey\fR, \fIsubject\fR, \fIissuer\fR,
and/or \fIserial\fR.
X.509 extensions may be set using \fBOSSL_CRMF_MSG_set0_extensions()\fR.
On success the reference counter of the \fIpubkey\fR (if given) is incremented,
while the \fIsubject\fR, \fIissuer\fR, and \fIserial\fR structures (if given) are copied.
.PP
\&\fBOSSL_CRMF_MSG_set0_extensions()\fR sets \fIexts\fR as the extensions in the
certTemplate of \fIcrm\fR. Frees any pre-existing ones and consumes \fIexts\fR.
.PP
\&\fBOSSL_CRMF_MSG_push0_extension()\fR pushes the X509 extension \fIext\fR to the
extensions in the certTemplate of \fIcrm\fR.  Consumes \fIext\fR.
.PP
\&\fBOSSL_CRMF_MSG_create_popo()\fR creates and sets the Proof-of-Possession (\s-1POPO\s0)
according to the method \fImeth\fR in \fIcrm\fR.
The library context \fIlibctx\fR and property query string \fIpropq\fR,
may be \s-1NULL\s0 to select the defaults.
In case the method is \s-1OSSL_CRMF_POPO_SIGNATURE\s0 the \s-1POPO\s0 is calculated
using the private key \fIpkey\fR and the digest method \fIdigest\fR,
where the \fIdigest\fR argument is ignored if \fIpkey\fR is of a type (such as
Ed25519 and Ed448) that is implicitly associated with a digest algorithm.
.PP
\&\fImeth\fR can be one of the following:
.IP "\(bu" 8
\&\s-1OSSL_CRMF_POPO_NONE\s0       \- \s-1RFC 4211,\s0 section 4, \s-1POP\s0 field omitted.
\&\s-1CA/RA\s0 uses out-of-band method to verify \s-1POP.\s0 Note that servers may fail in this
case, resulting for instance in \s-1HTTP\s0 error code 500 (Internal error).
.IP "\(bu" 8
\&\s-1OSSL_CRMF_POPO_RAVERIFIED\s0 \- \s-1RFC 4211,\s0 section 4, explicit indication
that the \s-1RA\s0 has already verified the \s-1POP.\s0
.IP "\(bu" 8
\&\s-1OSSL_CRMF_POPO_SIGNATURE\s0  \- \s-1RFC 4211,\s0 section 4.1, only case 3 supported
so far.
.IP "\(bu" 8
\&\s-1OSSL_CRMF_POPO_KEYENC\s0     \- \s-1RFC 4211,\s0 section 4.2, only indirect method
(subsequentMessage/enccert) supported,
challenge-response exchange (challengeResp) not yet supported.
.IP "\(bu" 8
\&\s-1OSSL_CRMF_POPO_KEYAGREE\s0   \- \s-1RFC 4211,\s0 section 4.3, not yet supported.
.PP
OSSL_CRMF_MSGS_verify_popo verifies the Proof-of-Possession of the request with
the given \fIrid\fR in the list of \fIreqs\fR. Optionally accepts RAVerified. It can
make use of the library context \fIlibctx\fR and property query string \fIpropq\fR.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
All functions return 1 on success, 0 on error.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1RFC 4211\s0
.SH "HISTORY"
.IX Header "HISTORY"
The OpenSSL \s-1CRMF\s0 support was added in OpenSSL 3.0.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2007\-2023 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (the \*(L"License\*(R").  You may not use
this file except in compliance with the License.  You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.