1 // Copyright 2015 The Chromium Authors
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 //     https://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14 
15 #ifndef BSSL_PKI_SIGNATURE_ALGORITHM_H_
16 #define BSSL_PKI_SIGNATURE_ALGORITHM_H_
17 
18 #include <stdint.h>
19 
20 #include <optional>
21 
22 #include <openssl/base.h>
23 #include <openssl/evp.h>
24 
25 BSSL_NAMESPACE_BEGIN
26 
27 namespace der {
28 class Input;
29 }  // namespace der
30 
31 // The digest algorithm used within a signature.
32 enum class DigestAlgorithm {
33   Md2,
34   Md4,
35   Md5,
36   Sha1,
37   Sha256,
38   Sha384,
39   Sha512,
40 };
41 
42 // The signature algorithm used within a certificate.
43 enum class SignatureAlgorithm {
44   kRsaPkcs1Sha1,
45   kRsaPkcs1Sha256,
46   kRsaPkcs1Sha384,
47   kRsaPkcs1Sha512,
48   kEcdsaSha1,
49   kEcdsaSha256,
50   kEcdsaSha384,
51   kEcdsaSha512,
52   // These RSA-PSS constants match RFC 8446 and refer to RSASSA-PSS with MGF-1,
53   // using the specified hash as both the signature and MGF-1 hash, and the hash
54   // length as the salt length.
55   kRsaPssSha256,
56   kRsaPssSha384,
57   kRsaPssSha512,
58   kMaxValue = kRsaPssSha512,
59 };
60 
61 // Parses AlgorithmIdentifier as defined by RFC 5280 section 4.1.1.2:
62 //
63 //     AlgorithmIdentifier  ::=  SEQUENCE  {
64 //          algorithm               OBJECT IDENTIFIER,
65 //          parameters              ANY DEFINED BY algorithm OPTIONAL  }
66 [[nodiscard]] OPENSSL_EXPORT bool ParseAlgorithmIdentifier(
67     der::Input input, der::Input *algorithm, der::Input *parameters);
68 
69 // Parses a HashAlgorithm as defined by RFC 5912:
70 //
71 //     HashAlgorithm  ::=  AlgorithmIdentifier{DIGEST-ALGORITHM,
72 //                             {HashAlgorithms}}
73 //
74 //     HashAlgorithms DIGEST-ALGORITHM ::=  {
75 //         { IDENTIFIER id-sha1 PARAMS TYPE NULL ARE preferredPresent } |
76 //         { IDENTIFIER id-sha224 PARAMS TYPE NULL ARE preferredPresent } |
77 //         { IDENTIFIER id-sha256 PARAMS TYPE NULL ARE preferredPresent } |
78 //         { IDENTIFIER id-sha384 PARAMS TYPE NULL ARE preferredPresent } |
79 //         { IDENTIFIER id-sha512 PARAMS TYPE NULL ARE preferredPresent }
80 //     }
81 [[nodiscard]] bool ParseHashAlgorithm(der::Input input, DigestAlgorithm *out);
82 
83 // Parses an AlgorithmIdentifier into a signature algorithm and returns it, or
84 // returns `std::nullopt` if `algorithm_identifier` either cannot be parsed or
85 // is not a recognized signature algorithm.
86 OPENSSL_EXPORT std::optional<SignatureAlgorithm> ParseSignatureAlgorithm(
87     der::Input algorithm_identifier);
88 
89 // Returns the hash to be used with the tls-server-end-point channel binding
90 // (RFC 5929) or `std::nullopt`, if not supported for this signature algorithm.
91 OPENSSL_EXPORT std::optional<DigestAlgorithm>
92 GetTlsServerEndpointDigestAlgorithm(SignatureAlgorithm alg);
93 
94 BSSL_NAMESPACE_END
95 
96 #endif  // BSSL_PKI_SIGNATURE_ALGORITHM_H_
97