1.\" $OpenBSD: X509_PURPOSE_set.3,v 1.1 2021/07/23 14:27:32 schwarze Exp $ 2.\" 3.\" Copyright (c) 2021 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: July 23 2021 $ 18.Dt X509_PURPOSE_SET 3 19.Os 20.Sh NAME 21.Nm X509_PURPOSE_set , 22.Nm X509_PURPOSE_get_by_id , 23.Nm X509_PURPOSE_add , 24.Nm X509_PURPOSE_get_count , 25.Nm X509_PURPOSE_cleanup , 26.Nm X509_PURPOSE_get0 , 27.Nm X509_PURPOSE_get_by_sname , 28.Nm X509_PURPOSE_get_id , 29.Nm X509_PURPOSE_get0_name , 30.Nm X509_PURPOSE_get0_sname , 31.Nm X509_PURPOSE_get_trust 32.Nd purpose objects, indices, and identifiers 33.Sh SYNOPSIS 34.In openssl/x509v3.h 35.Ft int 36.Fo X509_PURPOSE_set 37.Fa "int *id_out" 38.Fa "int id_in" 39.Fc 40.Ft int 41.Fn X509_PURPOSE_get_by_id "int identifier" 42.Ft int 43.Fo X509_PURPOSE_add 44.Fa "int identifier" 45.Fa "int trust" 46.Fa "int flags" 47.Fa "int (*check_purpose)(const X509_PURPOSE *, const X509 *, int)" 48.Fa "const char *name" 49.Fa "const char *sname" 50.Fa "void *usr_data" 51.Fc 52.Ft int 53.Fn X509_PURPOSE_get_count void 54.Ft void 55.Fn X509_PURPOSE_cleanup void 56.Ft X509_PURPOSE * 57.Fn X509_PURPOSE_get0 "int index" 58.Ft int 59.Fn X509_PURPOSE_get_by_sname "const char *sname" 60.Ft int 61.Fn X509_PURPOSE_get_id "const X509_PURPOSE *object" 62.Ft char * 63.Fn X509_PURPOSE_get0_name "const X509_PURPOSE *object" 64.Ft char * 65.Fn X509_PURPOSE_get0_sname "const X509_PURPOSE *object" 66.Ft int 67.Fn X509_PURPOSE_get_trust "const X509_PURPOSE *object" 68.Sh DESCRIPTION 69The purposes that an X.509 certificate is intended to be used for 70can be identified in three equivalent ways: 71.Bl -enum 72.It 73By purpose identifiers, which are positive integer constants. 74Standard purpose identifiers lie in the range from 75.Dv X509_PURPOSE_MIN 76to 77.Dv X509_PURPOSE_MAX , 78inclusive, and are listed in the 79.Xr X509_check_purpose 3 80manual page. 81User defined purpose identifiers are larger than 82.Dv X509_PURPOSE_MAX . 83.It 84By purpose indices, which are non-negative integer constants 85but differ from the purpose identifiers for the same purpose. 86Standard purpose indices are smaller than 87.Dv X509_PURPOSE_MAX . 88User defined purpose indices are larger than or equal to 89.Dv X509_PURPOSE_MAX . 90.It 91By purpose objects of the type 92.Vt X509_PURPOSE . 93Standard purpose objects are available in static storage. 94User defined purpose objects can be created with 95.Fn X509_PURPOSE_add . 96.El 97.Pp 98Application programmers cannot choose the way to identify purposes 99that they like best; depending on the circumstances, all three ways 100are needed. 101Be warned that the naming of most functions is misleading. 102.Pp 103Most API functions documented outside the present manual page 104use purpose identifiers rather than purpose indices. 105.Ss Using purpose identifiers 106.Fn X509_PURPOSE_set 107validates the purpose identifier 108.Fa id_in . 109If it is valid, it is copied to 110.Pf * Fa id_out . 111Otherwise, 112.Pf * Fa id_out 113remains unchanged. 114.Pp 115.Fn X509_PURPOSE_get_by_id 116converts the purpose 117.Fa identifier 118to the corresponding purpose index. 119To find the corresponding purpose object, pass the result to 120.Fn X509_PURPOSE_get0 . 121.Pp 122.Fn X509_PURPOSE_add 123defines a purpose with the given 124.Fa identifier 125or modifies its properties if it already exists. 126The purpose 127.Fa identifier , 128the 129.Fa trust 130identifier, the 131.Fa flags , 132the 133.Fa check_purpose 134function, the 135.Fa name , 136the short name 137.Fa sname , 138and the 139.Fa usr_data 140pointer are copied into the 141.Vt X509_PURPOSE 142object. 143When modifying an existing purpose object, previous values of fields are 144overwritten and previous 145.Fa name 146and 147.Fa sname 148strings are freed if they were dynamically allocated. 149When creating a new purpose object, 150it is added to the global array of user-defined purpose objects. 151.Pp 152.Dv X509_PURPOSE_DYNAMIC 153and 154.Dv X509_PURPOSE_DYNAMIC_NAME 155are always ignored in the 156.Fa flags 157argument. 158.Dv X509_PURPOSE_DYNAMIC 159is automatically set if the object was created by the user. 160It is never set for standard objects, not even if they were 161modified by the user. 162.Dv X509_PURPOSE_DYNAMIC_NAME 163is automatically set if the object was created or modified by the user. 164It is only unset for unmodified standard objects. 165The library does not appear to define any other flags, so the 166.Fa flags 167argument is probably useless unless users define their own flags 168and use them in the 169.Fa check_purpose 170function. 171.Pp 172The third and final argument of the 173.Fa check_purpose 174function is the 175.Fa ca 176argument documented in 177.Xr X509_check_purpose 3 . 178.Pp 179.Fn X509_PURPOSE_get_count 180returns the total number of purposes currently defined, 181including both standard and user-defined purposes. 182If no user-defined purposes exist, the returned value is 183.Dv X509_PURPOSE_MAX . 184.Pp 185.Fn X509_PURPOSE_cleanup 186deletes all user-defined purpose objects 187and invalidates their purpose identifiers and purpose indices. 188If any of the standard purpose objects were modified by the user, 189those changes are 190.Em not 191reverted. 192.Ss Using purpose indices 193.Fn X509_PURPOSE_get0 194converts the purpose 195.Fa index 196to a pointer to the corresponding purpose object. 197To find the corresponding purpose identifier, pass the result to 198.Fn X509_PURPOSE_get_id . 199.Pp 200.Fn X509_PURPOSE_get_by_sname 201returns the lowest index of a purpose with the given short name. 202.Ss Using purpose objects 203.Fn X509_PURPOSE_get_id 204converts a pointer to a purpose 205.Fa object 206to the corresponding purpose identifier. 207To find the corresponding purpose index, pass the result to 208.Fn X509_PURPOSE_get_by_id . 209.Pp 210.Fn X509_PURPOSE_get0_name , 211.Fn X509_PURPOSE_get0_sname , 212and 213.Fn X509_PURPOSE_get_trust 214retrieve the name, short name, and trust identifier from the 215.Fa object , 216respectively. 217.Sh RETURN VALUES 218.Fn X509_PURPOSE_set 219returns 1 if 220.Fa id_in 221is valid or 0 otherwise. 222.Pp 223.Fn X509_PURPOSE_get_by_id 224and 225.Fn X509_PURPOSE_get_by_sname 226return the corresponding purpose index 227or \-1 if no matching purpose is found. 228.Pp 229.Fn X509_PURPOSE_add 230returns 1 for success or 0 for failure. 231.Pp 232.Fn X509_PURPOSE_get_count 233returns the total number of purposes currently defined. 234.Pp 235.Fn X509_PURPOSE_get0 236returns a standard or user-defined purpose object or 237.Dv NULL 238if the 239.Fa index 240is invalid. 241.Pp 242.Fn X509_PURPOSE_get_id 243always returns a valid purpose identifier. 244.Pp 245.Fn X509_PURPOSE_get0_name 246and 247.Fn X509_PURPOSE_get0_sname 248return pointers to storage owned by the 249.Fa object . 250.Pp 251.Fn X509_PURPOSE_get_trust 252returns the trust identifier associated with the 253.Fa object . 254.Sh ERRORS 255The following diagnostics can be retrieved with 256.Xr ERR_get_error 3 , 257.Xr ERR_GET_REASON 3 , 258and 259.Xr ERR_reason_error_string 3 : 260.Bl -tag -width Ds 261.It Dv X509V3_R_INVALID_PURPOSE Qq "invalid purpose" 262.Fn X509_PURPOSE_set 263was called with an invalid 264.Fa id_in 265argument. 266.It Dv X509V3_R_INVALID_NULL_ARGUMENT Qq "invalid null argument" 267.Fn X509_PURPOSE_add 268was called with a 269.Fa name 270or 271.Fa sname 272argument of 273.Dv NULL . 274.It Dv ERR_R_MALLOC_FAILURE Qq "malloc failure" 275.Fn X509_PURPOSE_add 276failed to allocate memory. 277.El 278.Pp 279The other functions provide no diagnostics. 280.Sh SEE ALSO 281.Xr X509_check_purpose 3 , 282.Xr X509_new 3 , 283.Xr X509_STORE_set_purpose 3 , 284.Xr X509_VERIFY_PARAM_set_purpose 3 285.Sh HISTORY 286.Fn X509_PURPOSE_set 287first appeared in OpenSSL 0.9.7 and has been available since 288.Ox 3.2 . 289.Pp 290The other functions first appeared in OpenSSL 0.9.5 291and have been available since 292.Ox 2.7 . 293.Sh CAVEATS 294The difference between purpose identifiers and purpose indices provides 295an ideal breeding ground for off-by-one bugs. 296