1.\" $OpenBSD: POLICYINFO_new.3,v 1.11 2023/05/14 08:03:57 tb Exp $ 2.\" 3.\" Copyright (c) 2016 Ingo Schwarze <schwarze@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: May 14 2023 $ 18.Dt POLICYINFO_NEW 3 19.Os 20.Sh NAME 21.Nm POLICYINFO_new , 22.Nm POLICYINFO_free , 23.Nm CERTIFICATEPOLICIES_new , 24.Nm CERTIFICATEPOLICIES_free , 25.Nm POLICYQUALINFO_new , 26.Nm POLICYQUALINFO_free , 27.Nm USERNOTICE_new , 28.Nm USERNOTICE_free , 29.Nm NOTICEREF_new , 30.Nm NOTICEREF_free , 31.Nm POLICY_MAPPING_new , 32.Nm POLICY_MAPPING_free , 33.Nm POLICY_CONSTRAINTS_new , 34.Nm POLICY_CONSTRAINTS_free 35.Nd X.509 certificate policies 36.Sh SYNOPSIS 37.In openssl/x509v3.h 38.Ft POLICYINFO * 39.Fn POLICYINFO_new void 40.Ft void 41.Fn POLICYINFO_free "POLICYINFO *pi" 42.Ft CERTIFICATEPOLICIES * 43.Fn CERTIFICATEPOLICIES_new void 44.Ft void 45.Fn CERTIFICATEPOLICIES_free "CERTIFICATEPOLICIES *pis" 46.Ft POLICYQUALINFO * 47.Fn POLICYQUALINFO_new void 48.Ft void 49.Fn POLICYQUALINFO_free "POLICYQUALINFO *pqi" 50.Ft USERNOTICE * 51.Fn USERNOTICE_new void 52.Ft void 53.Fn USERNOTICE_free "USERNOTICE *usernotice" 54.Ft NOTICEREF * 55.Fn NOTICEREF_new void 56.Ft void 57.Fn NOTICEREF_free "NOTICEREF *noticeref" 58.Ft POLICY_MAPPING * 59.Fn POLICY_MAPPING_new void 60.Ft void 61.Fn POLICY_MAPPING_free "POLICY_MAPPING *pm" 62.Ft POLICY_CONSTRAINTS * 63.Fn POLICY_CONSTRAINTS_new void 64.Ft void 65.Fn POLICY_CONSTRAINTS_free "POLICY_CONSTRAINTS *pc" 66.Sh DESCRIPTION 67X.509 CA and end entity certificates can optionally indicate 68restrictions on their intended use. 69.Pp 70.Fn POLICYINFO_new 71allocates and initializes an empty 72.Vt POLICYINFO 73object, representing an ASN.1 74.Vt PolicyInformation 75structure defined in RFC 5280 section 4.2.1.4. 76It can hold a policy identifier and optional advisory qualifiers. 77.Fn POLICYINFO_free 78frees 79.Fa pi . 80.Pp 81.Fn CERTIFICATEPOLICIES_new 82allocates and initializes an empty 83.Vt CERTIFICATEPOLICIES 84object, which is a 85.Vt STACK_OF(POLICYINFO) 86and represents an ASN.1 87.Vt CertificatePolicies 88structure defined in RFC 5280 section 4.2.1.4. 89It can be used by 90.Vt X509 91objects, both by CA certificates and end entity certificates. 92.Fn CERTIFICATEPOLICIES_free 93frees 94.Fa pis . 95.Pp 96.Fn POLICYQUALINFO_new 97allocates and initializes an empty 98.Vt POLICYQUALINFO 99object, representing an ASN.1 100.Vt PolicyQualifierInfo 101structure defined in RFC 5280 section 4.2.1.4. 102It can be used in 103.Vt POLICYINFO 104and it can hold either a uniform resource identifier of a certification 105practice statement published by the CA, or a pointer to a 106.Vt USERNOTICE 107object, or arbitrary other information. 108.Fn POLICYQUALINFO_free 109frees 110.Fa pqi . 111.Pp 112.Fn USERNOTICE_new 113allocates and initializes an empty 114.Vt USERNOTICE 115object, representing an ASN.1 116.Vt UserNotice 117structure defined in RFC 5280 section 4.2.1.4. 118It can be used in 119.Vt POLICYQUALINFO 120and it can hold either an 121.Vt ASN1_STRING 122intended for display to the user or a pointer to a 123.Vt NOTICEREF 124object. 125.Fn NOTICEREF_free 126frees 127.Fa usernotice . 128.Pp 129.Fn NOTICEREF_new 130allocates and initializes an empty 131.Vt NOTICEREF 132object, representing an ASN.1 133.Vt NoticeReference 134structure defined in RFC 5280 section 4.2.1.4. 135It can be used in 136.Vt USERNOTICE 137and can hold an organization name and a stack of notice numbers. 138.Fn NOTICEREF_free 139frees 140.Fa noticeref . 141.Pp 142.Fn POLICY_MAPPING_new 143allocates and initializes an empty 144.Vt POLICY_MAPPING 145object, representing an ASN.1 146.Vt PolicyMappings 147structure defined in RFC 5280 section 4.2.1.5. 148It can be used in 149.Vt X509 150CA certificates and can hold a list of pairs of policy identifiers, 151declaring one of the policies in each pair as equivalent to the 152other. 153.Fn POLICY_MAPPING_free 154frees 155.Fa pm . 156.Pp 157.Fn POLICY_CONSTRAINTS_new 158allocates and initializes an empty 159.Vt POLICY_CONSTRAINTS 160object, representing an ASN.1 161.Vt PolicyConstraints 162structure defined in RFC 5280 section 4.2.1.11. 163It can be used in 164.Vt X509 165CA certificates to restrict policy mapping and/or to require explicit 166certificate policies in subsequent intermediate certificates in the 167certification path. 168.Fn POLICY_CONSTRAINTS_free 169frees 170.Fa pc . 171.Sh RETURN VALUES 172The constructor functions return a new object of the respective 173type or 174.Dv NULL 175if an error occurs. 176.Sh SEE ALSO 177.Xr BASIC_CONSTRAINTS_new 3 , 178.Xr d2i_POLICYINFO 3 , 179.Xr NAME_CONSTRAINTS_new 3 , 180.Xr X509_EXTENSION_new 3 , 181.Xr X509_get_extension_flags 3 , 182.Xr X509_new 3 183.Sh STANDARDS 184RFC 5280: Internet X.509 Public Key Infrastructure Certificate and 185Certificate Revocation List (CRL) Profile: 186.Bl -dash -compact 187.It 188section 4.2.1.4: Certificate Policies 189.It 190section 4.2.1.5: Policy Mappings 191.It 192section 4.2.1.11: Policy Constraints 193.El 194.Sh HISTORY 195.Fn POLICYINFO_new , 196.Fn POLICYINFO_free , 197.Fn CERTIFICATEPOLICIES_new , 198.Fn CERTIFICATEPOLICIES_free , 199.Fn POLICYQUALINFO_new , 200.Fn POLICYQUALINFO_free , 201.Fn USERNOTICE_new , 202.Fn USERNOTICE_free , 203.Fn NOTICEREF_new , 204and 205.Fn NOTICEREF_free 206first appeared in OpenSSL 0.9.3 and have been available since 207.Ox 2.6 . 208.Pp 209.Fn POLICY_MAPPING_new , 210.Fn POLICY_MAPPING_free , 211.Fn POLICY_CONSTRAINTS_new , 212and 213.Fn POLICY_CONSTRAINTS_free 214first appeared in OpenSSL 0.9.8 and have been available since 215.Ox 4.5 . 216.Sh BUGS 217This is a lot of nested data structures, but most of them are 218designed to have almost no effect. 219