1.\" $OpenBSD: PKCS8_pkey_set0.3,v 1.2 2021/10/25 13:48:12 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: October 25 2021 $ 18.Dt PKCS8_PKEY_SET0 3 19.Os 20.Sh NAME 21.Nm PKCS8_pkey_set0 , 22.Nm PKCS8_pkey_get0 , 23.Nm PKCS8_pkey_add1_attr_by_NID , 24.Nm PKCS8_pkey_get0_attrs 25.Nd change and inspect PKCS#8 PrivateKeyInfo objects 26.Sh SYNOPSIS 27.In openssl/x509.h 28.Ft int 29.Fo PKCS8_pkey_set0 30.Fa "PKCS8_PRIV_KEY_INFO *keyinfo" 31.Fa "ASN1_OBJECT *aobj" 32.Fa "int version" 33.Fa "int ptype" 34.Fa "void *pval" 35.Fa "unsigned char *data" 36.Fa "int len" 37.Fc 38.Ft int 39.Fo PKCS8_pkey_get0 40.Fa "const ASN1_OBJECT **paobj" 41.Fa "const unsigned char **pdata" 42.Fa "int *plen" 43.Fa "const X509_ALGOR **palgor" 44.Fa "const PKCS8_PRIV_KEY_INFO *keyinfo" 45.Fc 46.Ft int 47.Fo PKCS8_pkey_add1_attr_by_NID 48.Fa "PKCS8_PRIV_KEY_INFO *keyinfo" 49.Fa "int nid" 50.Fa "int type" 51.Fa "const unsigned char *data" 52.Fa "int len" 53.Fc 54.Ft const STACK_OF(X509_ATTRIBUTE) * 55.Fo PKCS8_pkey_get0_attrs 56.Fa "const PKCS8_PRIV_KEY_INFO *keyinfo" 57.Fc 58.Sh DESCRIPTION 59.Fn PKCS8_pkey_set0 60initializes the 61.Fa keyinfo 62object. 63The algorithm is set to 64.Fa aobj 65with the associated parameter type 66.Fa ptype 67and parameter value 68.Fa pval 69using 70.Xr X509_ALGOR_set0 3 , 71replacing any previous information about the algorithm. 72Unless 73.Fa data 74is 75.Dv NULL , 76the encoded private key is set to the 77.Fa len 78bytes starting at 79.Fa data 80using 81.Xr ASN1_STRING_set0 3 , 82not performing any validation. 83If 84.Fa data 85is 86.Dv NULL , 87the key data remains unchanged. 88If the 89.Fa version 90argument is greater than or equal to 0, it replaces any existing version; 91otherwise, the version remains unchanged. 92If 93.Fa keyinfo 94contains any attributes, they remain unchanged. 95.Pp 96.Fn PKCS8_pkey_get0 97retrieves some information from the 98.Fa keyinfo 99object. 100Internal pointers to the algorithm OID, the 101.Vt AlgorithmIdentifier , 102and the encoded private key are stored in 103.Pf * Fa paobj , 104.Pf * Fa palgor , 105and 106.Pf * Fa pdata , 107respectively. 108.Dv NULL 109pointers can be passed for any of these three arguments if the respective 110information is not needed. 111Unless 112.Fa pdata 113is 114.Dv NULL , 115.Pf * Fa plen 116is set to the number of bytes in 117.Pf * Fa pdata . 118.Pp 119.Fn PKCS8_pkey_add1_attr_by_NID 120creates a new X.501 Attribute object using 121.Xr X509_ATTRIBUTE_create_by_NID 3 122and appends it to the attributes of 123.Fa keyinfo 124using 125.Xr X509at_add1_attr 3 . 126.Sh RETURN VALUES 127.Fn PKCS8_pkey_set0 128and 129.Fn PKCS8_pkey_add1_attr_by_NID 130return 1 for success or 0 for failure. 131.Pp 132.Fn PKCS8_pkey_get0 133always returns 1. 134.Pp 135.Fn PKCS8_pkey_get0_attrs 136returns an internal pointer to the array of attributes associated with 137.Fa keyinfo 138or 139.Dv NULL 140if no attributes are set. 141.Sh SEE ALSO 142.Xr ASN1_STRING_set0 3 , 143.Xr EVP_PKCS82PKEY 3 , 144.Xr OBJ_nid2obj 3 , 145.Xr PKCS8_PRIV_KEY_INFO_new 3 , 146.Xr STACK_OF 3 , 147.Xr X509_ALGOR_new 3 , 148.Xr X509_ATTRIBUTE_create_by_NID 3 , 149.Xr X509_ATTRIBUTE_new 3 , 150.Xr X509at_add1_attr 3 , 151.Xr X509at_get_attr 3 152.Sh HISTORY 153.Fn PKCS8_pkey_set0 154and 155.Fn PKCS8_pkey_get0 156first appeared in OpenSSL 1.0.0 and have been available since 157.Ox 4.9 . 158.Pp 159.Fn PKCS8_pkey_add1_attr_by_NID 160and 161.Fn PKCS8_pkey_get0_attrs 162first appeared in OpenSSL 1.1.0 and have been available since 163.Ox 6.4 . 164