| =pod | |
| =head1 NAME | |
| X509_get0_distinguishing_id, X509_set0_distinguishing_id, | |
| X509_REQ_get0_distinguishing_id, X509_REQ_set0_distinguishing_id | |
| - get or set the Distinguishing ID for certificate operations | |
| =head1 SYNOPSIS | |
| #include <openssl/x509.h> | |
| ASN1_OCTET_STRING *X509_get0_distinguishing_id(X509 *x); | |
| void X509_set0_distinguishing_id(X509 *x, ASN1_OCTET_STRING *distid); | |
| ASN1_OCTET_STRING *X509_REQ_get0_distinguishing_id(X509_REQ *x); | |
| void X509_REQ_set0_distinguishing_id(X509_REQ *x, ASN1_OCTET_STRING *distid); | |
| =head1 DESCRIPTION | |
| The Distinguishing ID is defined in FIPS 196 as follows: | |
| =over 4 | |
| =item I<Distinguishing identifier> | |
| Information which unambiguously distinguishes | |
| an entity in the authentication process. | |
| =back | |
| The SM2 signature algorithm requires a Distinguishing ID value when generating | |
| and verifying a signature, but the Ddistinguishing ID may also find other uses. | |
| In the context of SM2, the Distinguishing ID is often referred to as the "SM2 | |
| ID". | |
| For the purpose off verifying a certificate or a certification request, a | |
| Distinguishing ID may be attached to it, so functions like L<X509_verify(3)> | |
| or L<X509_REQ_verify(3)> have easy access to that identity for signature | |
| verification. | |
| X509_get0_distinguishing_id() gets the Distinguishing ID value of a certificate | |
| B<x> by returning an B<ASN1_OCTET_STRING> object which should not be freed by | |
| the caller. | |
| X509_set0_distinguishing_id() assigns B<distid> to the certificate B<x>. | |
| Calling this function transfers the memory management of the value to the X509 | |
| object, and therefore the value that has been passed in should not be freed by | |
| the caller after this function has been called. | |
| X509_REQ_get0_distinguishing_id() and X509_REQ_set0_distinguishing_id() | |
| have the same functionality as X509_get0_distinguishing_id() and | |
| X509_set0_distinguishing_id() except that they deal with B<X509_REQ> | |
| objects instead of B<X509>. | |
| =head1 RETURN VALUES | |
| X509_set0_distinguishing_id() and X509_REQ_set0_distinguishing_id() do not | |
| return a value. | |
| =head1 SEE ALSO | |
| L<X509_verify(3)>, L<SM2(7)> | |
| =head1 COPYRIGHT | |
| Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved. | |
| Licensed under the Apache License 2.0 (the "License"). You may not use | |
| this file except in compliance with the License. You can obtain a copy | |
| in the file LICENSE in the source distribution or at | |
| L<https://www.openssl.org/source/license.html>. | |
| =cut |