diff options
author | Richard Levitte <levitte@openssl.org> | 2020-03-10 22:50:22 +0100 |
---|---|---|
committer | Richard Levitte <levitte@openssl.org> | 2020-03-15 19:42:04 +0100 |
commit | 70a7dd6f96c28a1a3059bf3d175bfb24449202ae (patch) | |
tree | bed8cc22e8013b51568f4b8cf3e04bf55891bf6e /doc | |
parent | a5ce329eb496eb7ae17d6198dac51c2ab417550e (diff) |
X509: Rename X509_set0_sm2_id() and friends
- X509_set0_sm2_id() -> X509_set0_distinguishing_id()
- X509_get0_sm2_id() -> X509_get0_distinguishing_id()
- X509_REQ_set0_sm2_id -> X509_REQ_set0_distinguishing_id()
- X509_REQ_get0_sm2_id -> X509_REQ_get0_distinguishing_id()
The reason for this rename is that the SM2 ID isn't really a unique
SM2 data item, but rather a re-use of the Distinguished that is
defined in ISO/IEC 15946-3 as well as in FIPS 196, with no special
attribution toward any algorithm in particular.
Fixes #11293
Reviewed-by: Paul Yang <kaishen.yy@antfin.com>
(Merged from https://github.com/openssl/openssl/pull/11302)
Diffstat (limited to 'doc')
-rw-r--r-- | doc/man3/X509_get0_distinguishing_id.pod | 71 | ||||
-rw-r--r-- | doc/man3/X509_get0_sm2_id.pod | 55 |
2 files changed, 71 insertions, 55 deletions
diff --git a/doc/man3/X509_get0_distinguishing_id.pod b/doc/man3/X509_get0_distinguishing_id.pod new file mode 100644 index 0000000000..2dd06e716d --- /dev/null +++ b/doc/man3/X509_get0_distinguishing_id.pod @@ -0,0 +1,71 @@ +=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 + +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 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 diff --git a/doc/man3/X509_get0_sm2_id.pod b/doc/man3/X509_get0_sm2_id.pod deleted file mode 100644 index d8a85d7f8b..0000000000 --- a/doc/man3/X509_get0_sm2_id.pod +++ /dev/null @@ -1,55 +0,0 @@ -=pod - -=head1 NAME - -X509_get0_sm2_id, X509_set0_sm2_id, -X509_REQ_get0_sm2_id, X509_REQ_set0_sm2_id -- get or set SM2 ID for certificate operations - -=head1 SYNOPSIS - - #include <openssl/x509.h> - - ASN1_OCTET_STRING *X509_get0_sm2_id(X509 *x); - void X509_set0_sm2_id(X509 *x, ASN1_OCTET_STRING *sm2_id); - ASN1_OCTET_STRING *X509_REQ_get0_sm2_id(X509_REQ *x); - void X509_REQ_set0_sm2_id(X509_REQ *x, ASN1_OCTET_STRING *sm2_id); - -=head1 DESCRIPTION - -X509_get0_sm2_id() gets the ID value of an SM2 certificate B<x> by returning an -B<ASN1_OCTET_STRING> object which should not be freed by the caller. - -X509_set0_sm2_id() sets the B<sm2_id> value to an SM2 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_sm2_id() and X509_REQ_set0_sm2_id() have the same functionality -as X509_get0_sm2_id() and X509_set0_sm2_id() except that they deal with -B<X509_REQ> objects instead of B<X509>. - -=head1 NOTES - -SM2 signature algorithm requires an ID value when generating and verifying a -signature. The functions described in this manual provide the user with the -ability to set and retrieve the SM2 ID value. - -=head1 RETURN VALUES - -X509_set0_sm2_id() and X509_REQ_set0_sm2_id() do not return a value. - -=head1 SEE ALSO - -L<X509_verify(3)>, L<SM2(7)> - -=head1 COPYRIGHT - -Copyright 2019 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 |