1 /*
2 * Copyright 2026 The Netty Project
3 *
4 * The Netty Project licenses this file to you under the Apache License,
5 * version 2.0 (the "License"); you may not use this file except in compliance
6 * with the License. You may obtain a copy of the License at:
7 *
8 * https://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
12 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13 * License for the specific language governing permissions and limitations
14 * under the License.
15 */
16 package io.netty.handler.ssl;
17
18 import io.netty.util.ReferenceCounted;
19
20 /**
21 * Represents an OpenSSL/BoringSSL {@code SSL_CREDENTIAL} object.
22 *
23 * <p>SSL credentials provide a more flexible alternative to traditional certificate/key configuration,
24 * supporting features like:
25 * <ul>
26 * <li>Multiple credentials per context (e.g., RSA + ECDSA)</li>
27 * <li>Delegated credentials</li>
28 * <li>OCSP stapling per credential</li>
29 * <li>Signed Certificate Timestamps (SCT)</li>
30 * <li>Trust anchor identifiers</li>
31 * <li>Per-credential signing algorithm preferences</li>
32 * </ul>
33 *
34 * <p>This is a BoringSSL-specific feature. Use {@link #isAvailable()} to check availability.
35 *
36 * <p>Instances are reference counted and must be released when no longer needed.
37 *
38 * @see <a href="https://commondatastorage.googleapis.com/chromium-boringssl-docs/ssl.h.html#SSL_CREDENTIAL_free">
39 * BoringSSL SSL_CREDENTIAL Documentation</a>
40 */
41 public interface OpenSslCredential extends ReferenceCounted {
42 /**
43 * Check if the credentials API is supported.
44 * @return {@code true} if the credentials API is supported, otherwise {@code false}.
45 */
46 static boolean isAvailable() {
47 return OpenSsl.isAvailable() && OpenSsl.isBoringSSL();
48 }
49
50 /**
51 * Returns the type of this credential.
52 *
53 * @return the credential type
54 */
55 CredentialType type();
56
57 @Override
58 OpenSslCredential retain();
59
60 @Override
61 OpenSslCredential retain(int increment);
62
63 @Override
64 OpenSslCredential touch();
65
66 @Override
67 OpenSslCredential touch(Object hint);
68
69 /**
70 * The type of SSL credential.
71 */
72 enum CredentialType {
73 /**
74 * Standard X.509 certificate credential created with {@code SSL_CREDENTIAL_new_x509()}.
75 */
76 X509,
77
78 /**
79 * Delegated credential created with {@code SSL_CREDENTIAL_new_delegated()}.
80 *
81 * @see <a href="https://datatracker.ietf.org/doc/html/rfc9345">RFC 9345 - Delegated Credentials for TLS</a>
82 */
83 DELEGATED
84 }
85 }