]>
Commit | Line | Data |
---|---|---|
f1f0731d | 1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | EVP_PKEY_get_attr, | |
6 | EVP_PKEY_get_attr_count, | |
7 | EVP_PKEY_get_attr_by_NID, EVP_PKEY_get_attr_by_OBJ, | |
8 | EVP_PKEY_delete_attr, | |
9 | EVP_PKEY_add1_attr, | |
10 | EVP_PKEY_add1_attr_by_OBJ, EVP_PKEY_add1_attr_by_NID, EVP_PKEY_add1_attr_by_txt | |
11 | - EVP_PKEY B<X509_ATTRIBUTE> functions | |
12 | ||
13 | =head1 SYNOPSIS | |
14 | ||
15 | #include <openssl/x509.h> | |
16 | ||
17 | int EVP_PKEY_get_attr_count(const EVP_PKEY *key); | |
18 | int EVP_PKEY_get_attr_by_NID(const EVP_PKEY *key, int nid, int lastpos); | |
19 | int EVP_PKEY_get_attr_by_OBJ(const EVP_PKEY *key, const ASN1_OBJECT *obj, | |
20 | int lastpos); | |
21 | X509_ATTRIBUTE *EVP_PKEY_get_attr(const EVP_PKEY *key, int loc); | |
22 | X509_ATTRIBUTE *EVP_PKEY_delete_attr(EVP_PKEY *key, int loc); | |
23 | int EVP_PKEY_add1_attr(EVP_PKEY *key, X509_ATTRIBUTE *attr); | |
24 | int EVP_PKEY_add1_attr_by_OBJ(EVP_PKEY *key, | |
25 | const ASN1_OBJECT *obj, int type, | |
26 | const unsigned char *bytes, int len); | |
27 | int EVP_PKEY_add1_attr_by_NID(EVP_PKEY *key, | |
28 | int nid, int type, | |
29 | const unsigned char *bytes, int len); | |
30 | int EVP_PKEY_add1_attr_by_txt(EVP_PKEY *key, | |
31 | const char *attrname, int type, | |
32 | const unsigned char *bytes, int len); | |
33 | ||
34 | =head1 DESCRIPTION | |
35 | ||
36 | These functions are used by B<PKCS12>. | |
37 | ||
38 | EVP_PKEY_get_attr_by_OBJ() finds the location of the first matching object I<obj> | |
39 | in the I<key> attribute list. The search starts at the position after I<lastpos>. | |
40 | If the returned value is positive then it can be used on the next call to | |
41 | EVP_PKEY_get_attr_by_OBJ() as the value of I<lastpos> in order to iterate through | |
42 | the remaining attributes. I<lastpos> can be set to any negative value on the | |
43 | first call, in order to start searching from the start of the attribute list. | |
44 | ||
45 | EVP_PKEY_get_attr_by_NID() is similar to EVP_PKEY_get_attr_by_OBJ() except that | |
46 | it passes the numerical identifier (NID) I<nid> associated with the object. | |
47 | See <openssl/obj_mac.h> for a list of NID_*. | |
48 | ||
49 | EVP_PKEY_get_attr() returns the B<X509_ATTRIBUTE> object at index I<loc> in the | |
50 | I<key> attribute list. I<loc> should be in the range from 0 to | |
51 | EVP_PKEY_get_attr_count() - 1. | |
52 | ||
53 | EVP_PKEY_delete_attr() removes the B<X509_ATTRIBUTE> object at index I<loc> in | |
54 | the I<key> attribute list. | |
55 | ||
56 | EVP_PKEY_add1_attr() pushes a copy of the passed in B<X509_ATTRIBUTE> object | |
57 | to the I<key> attribute list. A new I<key> attribute list is created if required. | |
58 | An error occurs if either I<attr> is NULL, or the attribute already exists. | |
59 | ||
60 | EVP_PKEY_add1_attr_by_OBJ() creates a new B<X509_ATTRIBUTE> using | |
61 | X509_ATTRIBUTE_set1_object() and X509_ATTRIBUTE_set1_data() to assign a new | |
62 | I<obj> with type I<type> and data I<bytes> of length I<len> and then pushes it | |
63 | to the I<key> object's attribute list. If I<obj> already exists in the attribute | |
64 | list then an error occurs. | |
65 | ||
66 | EVP_PKEY_add1_attr_by_NID() is similar to EVP_PKEY_add1_attr_by_OBJ() except | |
67 | that it passes the numerical identifier (NID) I<nid> associated with the object. | |
68 | See <openssl/obj_mac.h> for a list of NID_*. | |
69 | ||
70 | EVP_PKEY_add1_attr_by_txt() is similar to EVP_PKEY_add1_attr_by_OBJ() except | |
71 | that it passes a name I<attrname> associated with the object. | |
72 | See <openssl/obj_mac.h> for a list of SN_* names. | |
73 | ||
74 | =head1 RETURN VALUES | |
75 | ||
76 | EVP_PKEY_get_attr_count() returns the number of attributes in the I<key> object | |
77 | attribute list or -1 if the attribute list is NULL. | |
78 | ||
79 | EVP_PKEY_get_attr_by_OBJ() returns -1 if either the list is empty OR the object | |
80 | is not found, otherwise it returns the location of the object in the list. | |
81 | ||
82 | EVP_PKEY_get_attr_by_NID() is similar to EVP_PKEY_get_attr_by_OBJ(), except that | |
83 | it returns -2 if the I<nid> is not known by OpenSSL. | |
84 | ||
85 | EVP_PKEY_get_attr() returns either a B<X509_ATTRIBUTE> or NULL if there is a | |
86 | error. | |
87 | ||
88 | EVP_PKEY_delete_attr() returns either the removed B<X509_ATTRIBUTE> or NULL if | |
89 | there is a error. | |
90 | ||
91 | EVP_PKEY_add1_attr(), EVP_PKEY_add1_attr_by_OBJ(), EVP_PKEY_add1_attr_by_NID() | |
92 | and EVP_PKEY_add1_attr_by_txt() return 1 on success or 0 otherwise. | |
93 | ||
94 | =head1 NOTES | |
95 | ||
96 | A B<EVP_PKEY> object's attribute list is initially NULL. All the above functions | |
97 | listed will return an error unless EVP_PKEY_add1_attr() is called. | |
98 | All functions listed assume that the I<key> is not NULL. | |
99 | ||
100 | =head1 SEE ALSO | |
101 | ||
102 | L<X509_ATTRIBUTE(3)> | |
103 | ||
104 | =head1 COPYRIGHT | |
105 | ||
b6461792 | 106 | Copyright 2023-2024 The OpenSSL Project Authors. All Rights Reserved. |
f1f0731d | 107 | |
108 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
109 | this file except in compliance with the License. You can obtain a copy | |
110 | in the file LICENSE in the source distribution or at | |
111 | L<https://www.openssl.org/source/license.html>. | |
112 | ||
113 | =cut |