1.\" $OpenBSD: X509_keyid_set1.3,v 1.2 2021/07/09 14:41:14 tb 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 9 2021 $ 18.Dt X509_KEYID_SET1 3 19.Os 20.Sh NAME 21.Nm X509_keyid_set1 , 22.Nm X509_keyid_get0 , 23.Nm X509_alias_set1 , 24.Nm X509_alias_get0 25.Nd auxiliary certificate data for PKCS#12 26.Sh SYNOPSIS 27.In openssl/x509.h 28.Ft int 29.Fo X509_keyid_set1 30.Fa "X509 *x" 31.Fa "const unsigned char *data" 32.Fa "int len" 33.Fc 34.Ft unsigned char * 35.Fo X509_keyid_get0 36.Fa "X509 *x" 37.Fa "int *plen" 38.Fc 39.Ft int 40.Fo X509_alias_set1 41.Fa "X509 *x" 42.Fa "const unsigned char *data" 43.Fa "int len" 44.Fc 45.Ft unsigned char * 46.Fo X509_alias_get0 47.Fa "X509 *x" 48.Fa "int *plen" 49.Fc 50.Sh DESCRIPTION 51These functions store non-standard auxiliary data in 52.Fa x 53and retrieve it. 54.Pp 55The 56.Fa len 57bytes of 58.Fa data 59stored using 60.Fn X509_keyid_set1 61will be written to the 62.Sy localKeyID 63attribute of the PKCS#12 structure if 64.Xr PKCS12_create 3 65is later called on 66.Fa x , 67and the 68.Fa data 69stored using 70.Fn X509_alias_set1 71will be written to the 72.Sy friendlyName 73attribute. 74If 75.Fa data 76points to a NUL-terminated string, \-1 can be passed as the 77.Fa len 78argument to let 79.Fa len 80be calculated internally using 81.Xr strlen 3 . 82If a 83.Dv NULL 84pointer is passed as the 85.Fa data 86argument, the respective auxiliary data stored in 87.Fa x , 88if any, is removed from 89.Fa x 90and freed. 91.Pp 92Conversely, 93.Xr PKCS12_parse 3 94retrieves these attributes from a PKCS#12 structure such that they can 95subsequently be accessed with 96.Fn X509_keyid_get0 97and 98.Fn X509_alias_get0 . 99Unless 100.Dv NULL 101is passed for the 102.Fa plen 103argument, these functions store the size of the returned buffer in bytes in 104.Pf * Fa plen . 105After the call, the returned buffer is not necessarily NUL-terminated, 106but it may contain internal NUL bytes. 107.Pp 108API design is very incomplete; given the complexity of PKCS#12, 109that's probably an asset rather than a defect. 110The PKCS#12 standard defines many attributes that cannot be stored in 111.Vt X509 112objects. 113.Pp 114To associate certificates with alternative names and key identifiers, 115X.509 certificate extensions are more commonly used than PKCS#12 116attributes, for example using 117.Xr X509_EXTENSION_create_by_NID 3 118with 119.Dv NID_subject_alt_name 120or 121.Dv NID_subject_key_identifier . 122.Sh RETURN VALUES 123.Fn X509_keyid_set1 124and 125.Fn X509_alias_set1 126return 1 if 127.Fa data 128is 129.Dv NULL 130or if the input 131.Fa data 132was successfully copied into 133.Fa x , 134or 0 if 135.Fa data 136is not 137.Dv NULL 138but could not be copied because 139.Fa x 140is 141.Dv NULL 142or memory allocation failed. 143.Pp 144.Fn X509_keyid_get0 145and 146.Fn X509_alias_get0 147return an internal pointer to an array of bytes or 148.Dv NULL 149if 150.Fa x 151does not contain auxiliary data of the requested kind. 152.Sh SEE ALSO 153.Xr ASN1_STRING_set 3 , 154.Xr X509_CERT_AUX_new 3 , 155.Xr X509_EXTENSION_new 3 , 156.Xr X509_new 3 , 157.Xr X509V3_get_d2i 3 158.Sh HISTORY 159.Fn X509_alias_set1 160and 161.Fn X509_alias_get0 162first appeared in OpenSSL 0.9.5 and have been available since 163.Ox 2.7 . 164.Pp 165.Fn X509_keyid_set1 166first appeared in OpenSSL 0.9.6 and has been available since 167.Ox 2.9 . 168.Pp 169.Fn X509_keyid_get0 170first appeared in OpenSSL 0.9.8 and has been available since 171.Ox 4.5 . 172