163 lines
3.9 KiB
Groff
163 lines
3.9 KiB
Groff
.\" $OpenBSD: PKCS8_pkey_set0.3,v 1.2 2021/10/25 13:48:12 schwarze Exp $
|
|
.\"
|
|
.\" Copyright (c) 2021 Ingo Schwarze <schwarze@openbsd.org>
|
|
.\"
|
|
.\" Permission to use, copy, modify, and distribute this software for any
|
|
.\" purpose with or without fee is hereby granted, provided that the above
|
|
.\" copyright notice and this permission notice appear in all copies.
|
|
.\"
|
|
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
|
|
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
|
|
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
|
|
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
|
|
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
|
|
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
|
|
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
|
.\"
|
|
.Dd $Mdocdate: October 25 2021 $
|
|
.Dt PKCS8_PKEY_SET0 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm PKCS8_pkey_set0 ,
|
|
.Nm PKCS8_pkey_get0 ,
|
|
.Nm PKCS8_pkey_add1_attr_by_NID ,
|
|
.Nm PKCS8_pkey_get0_attrs
|
|
.Nd change and inspect PKCS#8 PrivateKeyInfo objects
|
|
.Sh SYNOPSIS
|
|
.In openssl/x509.h
|
|
.Ft int
|
|
.Fo PKCS8_pkey_set0
|
|
.Fa "PKCS8_PRIV_KEY_INFO *keyinfo"
|
|
.Fa "ASN1_OBJECT *aobj"
|
|
.Fa "int version"
|
|
.Fa "int ptype"
|
|
.Fa "void *pval"
|
|
.Fa "unsigned char *data"
|
|
.Fa "int len"
|
|
.Fc
|
|
.Ft int
|
|
.Fo PKCS8_pkey_get0
|
|
.Fa "const ASN1_OBJECT **paobj"
|
|
.Fa "const unsigned char **pdata"
|
|
.Fa "int *plen"
|
|
.Fa "const X509_ALGOR **palgor"
|
|
.Fa "const PKCS8_PRIV_KEY_INFO *keyinfo"
|
|
.Fc
|
|
.Ft int
|
|
.Fo PKCS8_pkey_add1_attr_by_NID
|
|
.Fa "PKCS8_PRIV_KEY_INFO *keyinfo"
|
|
.Fa "int nid"
|
|
.Fa "int type"
|
|
.Fa "const unsigned char *data"
|
|
.Fa "int len"
|
|
.Fc
|
|
.Ft const STACK_OF(X509_ATTRIBUTE) *
|
|
.Fo PKCS8_pkey_get0_attrs
|
|
.Fa "const PKCS8_PRIV_KEY_INFO *keyinfo"
|
|
.Fc
|
|
.Sh DESCRIPTION
|
|
.Fn PKCS8_pkey_set0
|
|
initializes the
|
|
.Fa keyinfo
|
|
object.
|
|
The algorithm is set to
|
|
.Fa aobj
|
|
with the associated parameter type
|
|
.Fa ptype
|
|
and parameter value
|
|
.Fa pval
|
|
using
|
|
.Xr X509_ALGOR_set0 3 ,
|
|
replacing any previous information about the algorithm.
|
|
Unless
|
|
.Fa data
|
|
is
|
|
.Dv NULL ,
|
|
the encoded private key is set to the
|
|
.Fa len
|
|
bytes starting at
|
|
.Fa data
|
|
using
|
|
.Xr ASN1_STRING_set0 3 ,
|
|
not performing any validation.
|
|
If
|
|
.Fa data
|
|
is
|
|
.Dv NULL ,
|
|
the key data remains unchanged.
|
|
If the
|
|
.Fa version
|
|
argument is greater than or equal to 0, it replaces any existing version;
|
|
otherwise, the version remains unchanged.
|
|
If
|
|
.Fa keyinfo
|
|
contains any attributes, they remain unchanged.
|
|
.Pp
|
|
.Fn PKCS8_pkey_get0
|
|
retrieves some information from the
|
|
.Fa keyinfo
|
|
object.
|
|
Internal pointers to the algorithm OID, the
|
|
.Vt AlgorithmIdentifier ,
|
|
and the encoded private key are stored in
|
|
.Pf * Fa paobj ,
|
|
.Pf * Fa palgor ,
|
|
and
|
|
.Pf * Fa pdata ,
|
|
respectively.
|
|
.Dv NULL
|
|
pointers can be passed for any of these three arguments if the respective
|
|
information is not needed.
|
|
Unless
|
|
.Fa pdata
|
|
is
|
|
.Dv NULL ,
|
|
.Pf * Fa plen
|
|
is set to the number of bytes in
|
|
.Pf * Fa pdata .
|
|
.Pp
|
|
.Fn PKCS8_pkey_add1_attr_by_NID
|
|
creates a new X.501 Attribute object using
|
|
.Xr X509_ATTRIBUTE_create_by_NID 3
|
|
and appends it to the attributes of
|
|
.Fa keyinfo
|
|
using
|
|
.Xr X509at_add1_attr 3 .
|
|
.Sh RETURN VALUES
|
|
.Fn PKCS8_pkey_set0
|
|
and
|
|
.Fn PKCS8_pkey_add1_attr_by_NID
|
|
return 1 for success or 0 for failure.
|
|
.Pp
|
|
.Fn PKCS8_pkey_get0
|
|
always returns 1.
|
|
.Pp
|
|
.Fn PKCS8_pkey_get0_attrs
|
|
returns an internal pointer to the array of attributes associated with
|
|
.Fa keyinfo
|
|
or
|
|
.Dv NULL
|
|
if no attributes are set.
|
|
.Sh SEE ALSO
|
|
.Xr ASN1_STRING_set0 3 ,
|
|
.Xr EVP_PKCS82PKEY 3 ,
|
|
.Xr OBJ_nid2obj 3 ,
|
|
.Xr PKCS8_PRIV_KEY_INFO_new 3 ,
|
|
.Xr STACK_OF 3 ,
|
|
.Xr X509_ALGOR_new 3 ,
|
|
.Xr X509_ATTRIBUTE_create_by_NID 3 ,
|
|
.Xr X509_ATTRIBUTE_new 3 ,
|
|
.Xr X509at_add1_attr 3 ,
|
|
.Xr X509at_get_attr 3
|
|
.Sh HISTORY
|
|
.Fn PKCS8_pkey_set0
|
|
and
|
|
.Fn PKCS8_pkey_get0
|
|
first appeared in OpenSSL 1.0.0 and have been available since
|
|
.Ox 4.9 .
|
|
.Pp
|
|
.Fn PKCS8_pkey_add1_attr_by_NID
|
|
and
|
|
.Fn PKCS8_pkey_get0_attrs
|
|
first appeared in OpenSSL 1.1.0 and have been available since
|
|
.Ox 6.4 .
|