]>
Commit | Line | Data |
---|---|---|
70a7dd6f RL |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | X509_get0_distinguishing_id, X509_set0_distinguishing_id, | |
6 | X509_REQ_get0_distinguishing_id, X509_REQ_set0_distinguishing_id | |
7 | - get or set the Distinguishing ID for certificate operations | |
8 | ||
9 | =head1 SYNOPSIS | |
10 | ||
11 | #include <openssl/x509.h> | |
12 | ||
13 | ASN1_OCTET_STRING *X509_get0_distinguishing_id(X509 *x); | |
14 | void X509_set0_distinguishing_id(X509 *x, ASN1_OCTET_STRING *distid); | |
15 | ASN1_OCTET_STRING *X509_REQ_get0_distinguishing_id(X509_REQ *x); | |
16 | void X509_REQ_set0_distinguishing_id(X509_REQ *x, ASN1_OCTET_STRING *distid); | |
17 | ||
18 | =head1 DESCRIPTION | |
19 | ||
20 | The Distinguishing ID is defined in FIPS 196 as follows: | |
21 | ||
22 | =over 4 | |
23 | ||
24 | I<Distinguishing identifier>: information which unambiguously distinguishes | |
25 | an entity in the authentication process. | |
26 | ||
27 | =back | |
28 | ||
29 | The SM2 signature algorithm requires a Distinguishing ID value when generating | |
30 | and verifying a signature, but the Ddistinguishing ID may also find other uses. | |
31 | In the context of SM2, the Distinguishing ID is often referred to as the "SM2 | |
32 | ID". | |
33 | ||
34 | For the purpose off verifying a certificate or a certification request, a | |
35 | Distinguishing ID may be attached to it, so functions like L<X509_verify(3)> | |
36 | or L<X509_REQ_verify(3)> have easy access to that identity for signature | |
37 | verification. | |
38 | ||
39 | X509_get0_distinguishing_id() gets the Distinguishing ID value of a certificate | |
40 | B<x> by returning an B<ASN1_OCTET_STRING> object which should not be freed by | |
41 | the caller. | |
42 | ||
43 | X509_set0_distinguishing_id() assigns B<distid> to the certificate B<x>. | |
44 | Calling this function transfers the memory management of the value to the X509 | |
45 | object, and therefore the value that has been passed in should not be freed by | |
46 | the caller after this function has been called. | |
47 | ||
48 | X509_REQ_get0_distinguishing_id() and X509_REQ_set0_distinguishing_id() | |
49 | have the same functionality as X509_get0_distinguishing_id() and | |
50 | X509_set0_distinguishing_id() except that they deal with B<X509_REQ> | |
51 | objects instead of B<X509>. | |
52 | ||
53 | =head1 RETURN VALUES | |
54 | ||
55 | X509_set0_distinguishing_id() and X509_REQ_set0_distinguishing_id() do not | |
56 | return a value. | |
57 | ||
58 | =head1 SEE ALSO | |
59 | ||
60 | L<X509_verify(3)>, L<SM2(7)> | |
61 | ||
62 | =head1 COPYRIGHT | |
63 | ||
64 | Copyright 2019 The OpenSSL Project Authors. All Rights Reserved. | |
65 | ||
66 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
67 | this file except in compliance with the License. You can obtain a copy | |
68 | in the file LICENSE in the source distribution or at | |
69 | L<https://www.openssl.org/source/license.html>. | |
70 | ||
71 | =cut |