188 lines
4.4 KiB
Groff
188 lines
4.4 KiB
Groff
.\" $OpenBSD: EVP_PKEY_add1_attr.3,v 1.3 2021/10/26 18:50:38 jmc 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 26 2021 $
|
|
.Dt EVP_PKEY_ADD1_ATTR 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm EVP_PKEY_add1_attr ,
|
|
.Nm EVP_PKEY_add1_attr_by_OBJ ,
|
|
.Nm EVP_PKEY_add1_attr_by_NID ,
|
|
.Nm EVP_PKEY_add1_attr_by_txt ,
|
|
.Nm EVP_PKEY_delete_attr ,
|
|
.Nm EVP_PKEY_get_attr ,
|
|
.Nm EVP_PKEY_get_attr_count ,
|
|
.Nm EVP_PKEY_get_attr_by_OBJ ,
|
|
.Nm EVP_PKEY_get_attr_by_NID
|
|
.Nd X.501 Attributes of private keys
|
|
.Sh SYNOPSIS
|
|
.In openssl/x509.h
|
|
.Ft int
|
|
.Fo EVP_PKEY_add1_attr
|
|
.Fa "EVP_PKEY *key"
|
|
.Fa "X509_ATTRIBUTE *attr"
|
|
.Fc
|
|
.Ft int
|
|
.Fo EVP_PKEY_add1_attr_by_OBJ
|
|
.Fa "EVP_PKEY *key"
|
|
.Fa "const ASN1_OBJECT *obj"
|
|
.Fa "int type"
|
|
.Fa "const unsigned char *data"
|
|
.Fa "int len"
|
|
.Fc
|
|
.Ft int
|
|
.Fo EVP_PKEY_add1_attr_by_NID
|
|
.Fa "EVP_PKEY *key"
|
|
.Fa "int nid"
|
|
.Fa "int type"
|
|
.Fa "const unsigned char *data"
|
|
.Fa "int len"
|
|
.Fc
|
|
.Ft int
|
|
.Fo EVP_PKEY_add1_attr_by_txt
|
|
.Fa "EVP_PKEY *key"
|
|
.Fa "const char *name"
|
|
.Fa "int type"
|
|
.Fa "const unsigned char *data"
|
|
.Fa "int len"
|
|
.Fc
|
|
.Ft X509_ATTRIBUTE *
|
|
.Fo EVP_PKEY_delete_attr
|
|
.Fa "EVP_PKEY *key"
|
|
.Fa "int index"
|
|
.Fc
|
|
.Ft X509_ATTRIBUTE *
|
|
.Fo EVP_PKEY_get_attr
|
|
.Fa "const EVP_PKEY *key"
|
|
.Fa "int index"
|
|
.Fc
|
|
.Ft int
|
|
.Fo EVP_PKEY_get_attr_count
|
|
.Fa "const EVP_PKEY *key"
|
|
.Fc
|
|
.Ft int
|
|
.Fo EVP_PKEY_get_attr_by_OBJ
|
|
.Fa "const EVP_PKEY *key"
|
|
.Fa "const ASN1_OBJECT *obj"
|
|
.Fa "int start_after"
|
|
.Fc
|
|
.Ft int
|
|
.Fo EVP_PKEY_get_attr_by_NID
|
|
.Fa "const EVP_PKEY *key"
|
|
.Fa "int nid"
|
|
.Fa "int start_after"
|
|
.Fc
|
|
.Sh DESCRIPTION
|
|
These functions support associating an array of X.501 Attributes
|
|
with a private key.
|
|
Such attributes can for example be included in PKCS#12 structures.
|
|
.Pp
|
|
.Fn EVP_PKEY_add1_attr
|
|
appends a deep copy of the
|
|
.Fa attr
|
|
using
|
|
.Xr X509at_add1_attr 3 .
|
|
.Pp
|
|
.Fn EVP_PKEY_add1_attr_by_OBJ ,
|
|
.Fn EVP_PKEY_add1_attr_by_NID ,
|
|
and
|
|
.Fn EVP_PKEY_add1_attr_by_txt
|
|
create a new X.501 Attribute object using
|
|
.Xr X509_ATTRIBUTE_create_by_OBJ 3 ,
|
|
.Xr X509_ATTRIBUTE_create_by_NID 3 ,
|
|
or
|
|
.Xr X509_ATTRIBUTE_create_by_txt 3 ,
|
|
respectively, and append it using
|
|
.Xr X509at_add1_attr 3 .
|
|
.Pp
|
|
.Fn EVP_PKEY_delete_attr
|
|
deletes the attribute with the zero-based
|
|
.Fa index
|
|
using
|
|
.Xr X509at_delete_attr 3 .
|
|
.Pp
|
|
.Fn EVP_PKEY_get_attr
|
|
returns the attribute with the zero-based
|
|
.Fa index
|
|
using
|
|
.Xr X509at_get_attr 3 .
|
|
.Pp
|
|
.Fn EVP_PKEY_get_attr_count
|
|
returns the number of attributes currently associated with the
|
|
.Fa key
|
|
using
|
|
.Xr X509at_get_attr_count 3 .
|
|
.Pp
|
|
.Fn EVP_PKEY_get_attr_by_OBJ
|
|
and
|
|
.Fn EVP_PKEY_get_attr_by_NID
|
|
search for an attribute of the type
|
|
.Fa obj
|
|
or
|
|
.Fa nid
|
|
using
|
|
.Xr X509at_get_attr_by_OBJ 3
|
|
or
|
|
.Xr X509at_get_attr_by_NID 3 ,
|
|
respectively.
|
|
.Sh RETURN VALUES
|
|
.Fn EVP_PKEY_add1_attr ,
|
|
.Fn EVP_PKEY_add1_attr_by_OBJ ,
|
|
.Fn EVP_PKEY_add1_attr_by_NID ,
|
|
and
|
|
.Fn EVP_PKEY_add1_attr_by_txt
|
|
return 1 for success or 0 for failure.
|
|
.Pp
|
|
.Fn EVP_PKEY_delete_attr
|
|
and
|
|
.Fn EVP_PKEY_get_attr
|
|
return the deleted or requested attribute or
|
|
.Dv NULL
|
|
if the requested index is negative or greater than or equal to
|
|
the current number of attributes associated with the
|
|
.Fa key .
|
|
.Pp
|
|
.Fn EVP_PKEY_get_attr_count
|
|
returns the current number of attributes.
|
|
.Pp
|
|
.Fn EVP_PKEY_get_attr_by_OBJ
|
|
and
|
|
.Fn EVP_PKEY_get_attr_by_NID
|
|
return the index of the first attribute that has an index greater than
|
|
.Fa start_after
|
|
and a type matching
|
|
.Fa obj
|
|
or
|
|
.Fa nid ,
|
|
respectively, or \-1 on failure.
|
|
In addition,
|
|
.Fn EVP_PKEY_get_attr_by_NID
|
|
returns \-2 if
|
|
.Xr OBJ_nid2obj 3
|
|
fails on the requested
|
|
.Fa nid .
|
|
.Sh SEE ALSO
|
|
.Xr EVP_PKEY_new 3 ,
|
|
.Xr OBJ_nid2obj 3 ,
|
|
.Xr PKCS12_create 3 ,
|
|
.Xr X509_ATTRIBUTE_create_by_OBJ 3 ,
|
|
.Xr X509_ATTRIBUTE_new 3 ,
|
|
.Xr X509at_add1_attr 3 ,
|
|
.Xr X509at_get_attr 3
|
|
.Sh HISTORY
|
|
These functions first appeared in OpenSSL 0.9.8
|
|
and have been available since
|
|
.Ox 4.5 .
|