diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index c933911e..dc03b8f1 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -6,8 +6,9 @@ permissions: on: workflow_dispatch: push: - branches: - - main + branches: ['main', 'rel-*', 'ci/*'] + pull_request: + merge_group: schedule: - cron: '0 18 * * *' @@ -29,9 +30,14 @@ jobs: with: tool: zola@0.19.1 # Matched to rustls repo - - name: Generate API JSON data - run: - cargo run -p rustls-ffi-tools --bin docgen > website/static/api.json + - name: Verify API docs JSON data + run: | + if ! diff website/static/api.json <(cargo run -p rustls-ffi-tools --bin docgen 2>/dev/null); then + echo + echo "ERROR: Generated api.json differs from checked-in version" + echo "Run 'cargo run -p rustls-ffi-tools --bin docgen > website/static/api.json' and commit the changes" + exit 1 + fi - name: Generate site pages run: | @@ -39,13 +45,14 @@ jobs: - name: Package and upload artifact uses: actions/upload-pages-artifact@v3 + if: github.ref == 'refs/heads/main' with: path: ./target/website/ deploy: name: Deploy runs-on: ubuntu-latest - if: github.repository == 'rustls/rustls-ffi' + if: github.repository == 'rustls/rustls-ffi' && github.ref == 'refs/heads/main' needs: generate permissions: pages: write diff --git a/.gitignore b/.gitignore index 7bfcff02..9319a0f4 100644 --- a/.gitignore +++ b/.gitignore @@ -6,5 +6,4 @@ librustls/cmake-build* .vs debian/usr debian/DEBIAN -/website/static/api.json /website/public diff --git a/tools/src/bin/docgen/main.rs b/tools/src/bin/docgen/main.rs index 63bbe1c5..7eaaa87c 100644 --- a/tools/src/bin/docgen/main.rs +++ b/tools/src/bin/docgen/main.rs @@ -27,10 +27,7 @@ fn main() -> Result<(), Box> { // Collect up all items we want to document. Returns an error if any // items we expect to be documented are missing associated block comments. - let mut docs = find_doc_items(root, header_file_bytes)?; - - // Cross-link items in comments. - docs.crosslink_comments()?; + let docs = find_doc_items(root, header_file_bytes)?; // Render JSON data. println!("{}", serde_json::to_string_pretty(&docs)?); @@ -48,57 +45,6 @@ struct ApiDocs { aliases: Vec, } -impl ApiDocs { - fn crosslink_comments(&mut self) -> Result<(), Box> { - // Put all anchors into a set. Error for any duplicates. - let mut anchor_set = HashSet::new(); - for a in self.all_anchors() { - if !anchor_set.insert(a.to_string()) { - return Err(format!("duplicate anchor: {a}").into()); - } - } - - // For each item of each type, crosslink its comment. - for s in &mut self.structs { - s.comment.crosslink(&anchor_set)?; - } - for f in &mut self.functions { - f.comment.crosslink(&anchor_set)?; - } - for cb in &mut self.callbacks { - cb.comment.crosslink(&anchor_set)?; - } - for e in &mut self.enums { - e.comment.crosslink(&anchor_set)?; - for v in &mut e.variants { - if let Some(comment) = &mut v.comment { - comment.crosslink(&anchor_set)?; - } - } - } - for e in &mut self.externs { - e.comment.crosslink(&anchor_set)?; - } - for a in &mut self.aliases { - a.comment.crosslink(&anchor_set)?; - } - - Ok(()) - } - - fn all_anchors(&self) -> impl Iterator { - // return all item anchors as a chained iterator - self.structs - .iter() - .map(|s| s.anchor.as_str()) - .chain(self.functions.iter().map(|f| f.anchor.as_str())) - .chain(self.callbacks.iter().map(|cb| cb.anchor.as_str())) - .chain(self.enums.iter().map(|e| e.anchor.as_str())) - .chain(self.externs.iter().map(|e| e.anchor.as_str())) - .chain(self.aliases.iter().map(|a| a.anchor.as_str())) - } -} - fn find_doc_items(root: Node, source_code: &[u8]) -> Result> { // We document all: // * type definitions @@ -142,8 +88,18 @@ fn find_doc_items(root: Node, source_code: &[u8]) -> Result api.enums.push(e), Item::Struct(s) => api.structs.push(s), @@ -169,49 +125,100 @@ fn process_doc_item(item: Node, src: &[u8]) -> Result, Box process_typedef_item(comment, feat_requirement, item, src)?, - "enum_specifier" => Item::from(EnumItem::new(comment, feat_requirement, item, src)?), - "declaration" => process_declaration_item(comment, feat_requirement, item, src)?, - _ => return Err(format!("unexpected item kind: {}", item.kind()).into()), + "type_definition" => process_typedef_item(metadata, item, src)?, + "enum_specifier" => Item::from(EnumItem::new(metadata, item, src)?), + "declaration" => process_declaration_item(metadata, item, src)?, + _ => return Err(format!("unexpected item kind: {kind}").into()), })) } -fn comment_and_requirement( - node: Node, - src: &[u8], -) -> Result<(Option, Option), Box> { - let mut maybe_comment = Comment::new(node, src).ok(); +/// Metadata common to documented items +#[derive(Debug, Default, Serialize)] +struct ItemMetadata { + /// A comment describing the item + comment: Option, + /// A feature requirement that must be enabled for the item + feature: Option, + /// A deprecation message for the item + deprecation: Option, +} + +impl ItemMetadata { + /// Convert the preceding sibling of a to-be-processed item into associated metadata + /// + /// An item `Node` to be processed for documentation will typically have associated + /// metadata `Node`s preceding it in the parse tree. This function returns the + /// `ItemMetadata` that could be found. + /// + /// The potential cases we care about are: + /// * `prev` is not a comment, and not a feature requirement. + /// * `prev` is a Comment, and has no feature requirement before it. + /// * `prev` is a Comment, and has a feature requirement before it. + /// * `prev` is a Deprecation, and has a comment and feature requirement before it. + /// * `prev` is a Deprecation, and has a comment and no feature requirement before it. + /// * `prev` is a bare feature requirement + /// + /// cbindgen won't create other permutations (e.g. comment before a feature requirement, or + /// a deprecation before a feature requirement) so we don't have to consider those cases. + fn new(prev: Node, src: &[u8]) -> Result> { + let prev_prev = prev.prev_named_sibling(); + + // In the simple case, `prev` is a comment and `prev_prev` may + // be a feature requirement. Deprecations aren't in play. + if let Ok(comment) = Comment::new(prev, src) { + let feature = match prev_prev { + Some(prev_prev) => Feature::new(prev_prev, src).ok(), + None => None, + }; + return Ok(ItemMetadata { + comment: Some(comment), + feature, + deprecation: None, + }); + } - // If node wasn't a comment, see if it was an expression_statement - // that itself was preceded by a comment. This skips over - // expression-like preprocessor attributes on function decls. - if let (None, "expression_statement", Some(prev)) = - (&maybe_comment, node.kind(), node.prev_sibling()) - { - maybe_comment = Comment::new(prev, src).ok(); - } + // `prev` is a deprecation, `prev_prev` may be a comment, and `prev_prev_prev` + // may be a feature requirement. + if let Ok(deprecation) = Deprecation::new(prev, src) { + let comment = match prev_prev { + Some(prev_prev) => Comment::new(prev_prev, src).ok(), + None => None, + }; + let prev_prev_prev = prev_prev.and_then(|prev_prev| prev_prev.prev_named_sibling()); + let feature = match prev_prev_prev { + Some(prev_prev_prev) => Feature::new(prev_prev_prev, src).ok(), + None => None, + }; + return Ok(ItemMetadata { + comment, + feature, + deprecation: Some(deprecation), + }); + } - // If prev wasn't a comment, see if it was a feature requirement. - if maybe_comment.is_none() { - return Ok(match Feature::new(node, src).ok() { - Some(feat_req) => (None, Some(feat_req)), - None => (None, None), - }); + // If `prev` wasn't a comment, or an expression_statement preceded by a comment, + // then it's either a bare feature requirement without a deprecation or we have no + // metadata to return. + Ok(ItemMetadata { + comment: None, + feature: Feature::new(prev, src).ok(), + deprecation: None, + }) } - // Otherwise, check the prev of the comment for a feature requirement - let Some(prev) = node.prev_named_sibling() else { - return Ok((maybe_comment, None)); - }; - - Ok((maybe_comment, Feature::new(prev, src).ok())) + // If the metadata has a comment, update the content with crosslinks using the provided anchors + fn crosslink(&mut self, anchors: &HashSet) -> Result<(), Box> { + match &mut self.comment { + Some(comment) => comment.crosslink(anchors), + None => Ok(()), + } + } } #[derive(Debug, Default, Serialize)] @@ -331,9 +338,41 @@ impl Display for Comment { } } +#[derive(Debug, Default, Serialize)] +struct Deprecation(String); + +impl Deprecation { + fn new(node: Node, src: &[u8]) -> Result> { + require_kind("expression_statement", node, src)?; + + let query_str = r#" + (call_expression + function: (identifier) @func (#eq? @func "DEPRECATED_FUNC") + arguments: (argument_list + (string_literal (string_content) @content) + ) + ) + "#; + + let mut query_cursor = QueryCursor::new(); + let language = tree_sitter_c::LANGUAGE; + let query = Query::new(&language.into(), query_str)?; + + let captures = query_cursor.captures(&query, node, src); + for (mat, _) in captures { + for capture in mat.captures { + if query.capture_names()[capture.index as usize] == "content" { + return Ok(Self(node_text(capture.node, src))); + } + } + } + + Err(node_error("DEPRECATED_FUNC call not found or malformed", node, src).into()) + } +} + fn process_typedef_item( - maybe_comment: Option, - maybe_feature: Option, + mut metadata: ItemMetadata, item: Node, src: &[u8], ) -> Result> { @@ -342,17 +381,19 @@ fn process_typedef_item( let typedef_node = item.child_by_field_name("type").unwrap(); let typedef_kind = typedef_node.kind(); - let comment = match (&maybe_comment, item.prev_named_sibling()) { - // We allow an uncommented type_definition if the previous node was a bare enum_specifier. - // This happens when an enum has a primitive type repr, like rustls_result. The enum - // appears without typedef (but with comment), and then a typedef uint32_t appears (without - // preceding comment). This is OK and doesn't count as an undocumented error. - // - // It's important we use prev_named_sibling() for finding the enum_specifier that precedes - // the typedef. Using prev_sibling() would return an anonymous ';' node. - (None, Some(sib)) if sib.kind() == "enum_specifier" => Comment::default(), - _ => require_documented(maybe_comment, item, src)?, - }; + // We allow an uncommented type_definition if the previous node was a bare enum_specifier. + // This happens when an enum has a primitive type repr, like rustls_result. The enum + // appears without typedef (but with comment), and then a typedef uint32_t appears (without + // preceding comment). This is OK and doesn't count as an undocumented error. + // + // It's important we use prev_named_sibling() for finding the enum_specifier that precedes + // the typedef. Using prev_sibling() would return an anonymous ';' node. + match (metadata.comment.is_none(), item.prev_named_sibling()) { + (true, Some(sib)) if sib.kind() == "enum_specifier" => { + metadata.comment = Some(Comment::default()); + } + _ => require_documented(&metadata, item, src)?, + } // Convert the particular item being typedef'd based on kind(). // We treat function typedefs differently - we want those to be considered callbacks. @@ -368,41 +409,28 @@ fn process_typedef_item( .unwrap_or_default(); Ok(match typedef_kind { // e.g. `typedef enum rustls_handshake_kind { ... } rustls_handshake_kind;` - "enum_specifier" => Item::from(EnumItem::new( - Some(comment), - maybe_feature, - typedef_node, - src, - )?), + "enum_specifier" => Item::from(EnumItem::new(metadata, typedef_node, src)?), // e.g. `typedef uint32_t (*rustls_verify_server_cert_callback)(...);` - "primitive_type" if func_declarator => { - Item::from(CallbackItem::new(comment, maybe_feature, item, src)?) - } + "primitive_type" if func_declarator => Item::from(CallbackItem::new(metadata, item, src)?), // e.g. `typedef rustls_io_result (*rustls_read_callback)(...);` - "type_identifier" if func_declarator => { - Item::from(CallbackItem::new(comment, maybe_feature, item, src)?) - } + "type_identifier" if func_declarator => Item::from(CallbackItem::new(metadata, item, src)?), // e.g. `typedef const struct rustls_certified_key *(*rustls_client_hello_callback)(...);` "struct_specifier" if func_declarator => { - Item::from(CallbackItem::new(comment, maybe_feature, item, src)?) + Item::from(CallbackItem::new(metadata, item, src)?) } // e.g. `typedef struct rustls_accepted rustls_accepted;` - "struct_specifier" => { - Item::from(StructItem::new(comment, maybe_feature, typedef_node, src)?) - } + "struct_specifier" => Item::from(StructItem::new(metadata, typedef_node, src)?), // e.g. `typedef int rustls_io_result;` - "primitive_type" if !func_declarator => { - Item::from(TypeAliasItem::new(comment, maybe_feature, item, src)) - } + "primitive_type" if !func_declarator => Item::from(TypeAliasItem::new(metadata, item, src)), // e.g. ... well, none so far - but something like `typedef rustls_io_result rustls_funtime_io_result;`. "type_identifier" if !func_declarator => { - Item::from(TypeAliasItem::new(comment, maybe_feature, item, src)) + Item::from(TypeAliasItem::new(metadata, item, src)) } _ => return Err(format!("unknown typedef kind: {typedef_kind:?}").into()), @@ -410,30 +438,19 @@ fn process_typedef_item( } fn process_declaration_item( - comment: Option, - maybe_feature: Option, + metadata: ItemMetadata, item: Node, src: &[u8], ) -> Result> { require_kind("declaration", item, src)?; + require_documented(&metadata, item, src)?; - let comment = require_documented(comment, item, src)?; if item.child(0).unwrap().kind() == "storage_class_specifier" { // extern is a storage_class_specifier. - Ok(Item::from(ExternItem::new( - comment, - maybe_feature, - item, - src, - )?)) + Ok(Item::from(ExternItem::new(metadata, item, src)?)) } else { // other non-extern declarations are functions. - Ok(Item::from(FunctionItem::new( - comment, - maybe_feature, - item, - src, - )?)) + Ok(Item::from(FunctionItem::new(metadata, item, src)?)) } } @@ -448,6 +465,31 @@ enum Item { Extern(ExternItem), } +impl Item { + fn anchor(&self) -> &str { + match self { + Item::Enum(item) => &item.anchor, + Item::Struct(item) => &item.anchor, + Item::TypeAlias(item) => &item.anchor, + Item::Callback(item) => &item.anchor, + Item::Function(item) => &item.anchor, + Item::Extern(item) => &item.anchor, + } + } + + fn crosslink(&mut self, anchors: &HashSet) -> Result<(), Box> { + let metadata = match self { + Item::Enum(item) => &mut item.metadata, + Item::Struct(item) => &mut item.metadata, + Item::TypeAlias(item) => &mut item.metadata, + Item::Callback(item) => &mut item.metadata, + Item::Function(item) => &mut item.metadata, + Item::Extern(item) => &mut item.metadata, + }; + metadata.crosslink(anchors) + } +} + impl From for Item { fn from(item: EnumItem) -> Self { Self::Enum(item) @@ -490,20 +532,15 @@ impl From for Item { #[derive(Debug, Serialize)] struct EnumItem { anchor: String, - comment: Comment, - feature: Option, + #[serde(flatten)] + metadata: ItemMetadata, name: String, variants: Vec, } impl EnumItem { - fn new( - comment: Option, - feature: Option, - enum_spec: Node, - src: &[u8], - ) -> Result> { - let comment = require_documented(comment, enum_spec, src)?; + fn new(metadata: ItemMetadata, enum_spec: Node, src: &[u8]) -> Result> { + require_documented(&metadata, enum_spec, src)?; let name = enum_spec .child_by_field_name("name") @@ -521,8 +558,7 @@ impl EnumItem { Ok(Self { anchor: name.replace('_', "-").to_ascii_lowercase(), - comment, - feature, + metadata, name, variants, }) @@ -564,26 +600,20 @@ impl EnumVariantItem { #[derive(Debug, Serialize)] struct StructItem { anchor: String, - comment: Comment, - feature: Option, + #[serde(flatten)] + metadata: ItemMetadata, name: String, text: String, } impl StructItem { - fn new( - comment: Comment, - feature: Option, - struct_node: Node, - src: &[u8], - ) -> Result> { + fn new(metadata: ItemMetadata, struct_node: Node, src: &[u8]) -> Result> { require_kind("struct_specifier", struct_node, src)?; let name = node_text(struct_node.child_by_field_name("name").unwrap(), src); Ok(Self { anchor: name.replace('_', "-").to_ascii_lowercase(), - comment, - feature, + metadata, name, text: markup_text(struct_node, src), }) @@ -596,14 +626,14 @@ impl StructItem { #[derive(Debug, Serialize)] struct TypeAliasItem { anchor: String, - comment: Comment, - feature: Option, + #[serde(flatten)] + metadata: ItemMetadata, name: String, text: String, } impl TypeAliasItem { - fn new(comment: Comment, feature: Option, item: Node, src: &[u8]) -> Self { + fn new(metadata: ItemMetadata, item: Node, src: &[u8]) -> Self { let language = tree_sitter_c::LANGUAGE; let query = Query::new(&language.into(), "(type_identifier) @name").unwrap(); let mut cursor = QueryCursor::new(); @@ -619,8 +649,7 @@ impl TypeAliasItem { // anchors. One for the bare enum, and one for the typedef'd type. anchor: format!("alias-{}", name.replace("_", "-").to_ascii_lowercase()), name, - comment, - feature, + metadata, text: markup_text(item, src), } } @@ -632,26 +661,20 @@ impl TypeAliasItem { #[derive(Debug, Serialize)] struct CallbackItem { anchor: String, - comment: Comment, - feature: Option, + #[serde(flatten)] + metadata: ItemMetadata, name: String, text: String, } impl CallbackItem { - fn new( - comment: Comment, - feature: Option, - typedef: Node, - src: &[u8], - ) -> Result> { + fn new(metadata: ItemMetadata, typedef: Node, src: &[u8]) -> Result> { require_kind("type_definition", typedef, src)?; let name = function_identifier(typedef, src); Ok(Self { anchor: name.replace("_'", "-").to_ascii_lowercase(), - comment, - feature, + metadata, name, text: markup_text(typedef, src), }) @@ -664,26 +687,20 @@ impl CallbackItem { #[derive(Debug, Serialize)] struct FunctionItem { anchor: String, - comment: Comment, - feature: Option, + #[serde(flatten)] + metadata: ItemMetadata, name: String, text: String, } impl FunctionItem { - fn new( - comment: Comment, - feature: Option, - decl_node: Node, - src: &[u8], - ) -> Result> { + fn new(metadata: ItemMetadata, decl_node: Node, src: &[u8]) -> Result> { require_kind("declaration", decl_node, src)?; let name = function_identifier(decl_node, src); Ok(Self { anchor: name.replace('_', "-").to_ascii_lowercase(), - comment, - feature, + metadata, name, text: markup_text(decl_node, src), }) @@ -696,19 +713,14 @@ impl FunctionItem { #[derive(Debug, Serialize)] struct ExternItem { anchor: String, - comment: Comment, - feature: Option, + #[serde(flatten)] + metadata: ItemMetadata, name: String, text: String, } impl ExternItem { - fn new( - comment: Comment, - feature: Option, - decl_node: Node, - src: &[u8], - ) -> Result> { + fn new(metadata: ItemMetadata, decl_node: Node, src: &[u8]) -> Result> { require_kind("declaration", decl_node, src)?; // Query for the first identifier kind child node. @@ -723,8 +735,7 @@ impl ExternItem { Ok(Self { anchor: name.replace('_', "-").to_ascii_lowercase(), - comment, - feature, + metadata, name, text: markup_text(decl_node, src), }) @@ -786,23 +797,24 @@ fn require_kind(kind: &str, node: Node, src: &[u8]) -> Result<(), Box } } -/// Unwrap a required CommentNode or return an error. +/// Return an error if `ItemMetadat` doesn't contain a `Comment` /// /// The error will describe the kind of node that was missing a documentation comment, as well /// as its location (line/col) in the source code. fn require_documented( - comment: Option, + metadata: &ItemMetadata, item: Node, src: &[u8], -) -> Result> { - comment.ok_or( - node_error( +) -> Result<(), Box> { + if metadata.comment.is_none() { + return Err(node_error( format!("undocumented {kind}", kind = item.kind()), item, src, ) - .into(), - ) + .into()); + } + Ok(()) } fn node_error(prefix: impl Display, n: Node, src: &[u8]) -> String { diff --git a/website/static/api.json b/website/static/api.json new file mode 100644 index 00000000..449fef79 --- /dev/null +++ b/website/static/api.json @@ -0,0 +1,2385 @@ +{ + "structs": [ + { + "anchor": "rustls-accepted", + "comment": "A parsed ClientHello produced by a rustls_acceptor.\n\n It is used to check server name indication (SNI), ALPN protocols,\n signature schemes, and cipher suites. It can be combined with a\n [`rustls_server_config`](#rustls-server-config) to build a [`rustls_connection`](#rustls-connection).", + "feature": null, + "deprecation": null, + "name": "rustls_accepted", + "text": "```c\nstruct rustls_accepted\n```" + }, + { + "anchor": "rustls-accepted-alert", + "comment": "Represents a TLS alert resulting from accepting a client.", + "feature": null, + "deprecation": null, + "name": "rustls_accepted_alert", + "text": "```c\nstruct rustls_accepted_alert\n```" + }, + { + "anchor": "rustls-acceptor", + "comment": "A buffer and parser for ClientHello bytes.\n\n This allows reading ClientHello before choosing a rustls_server_config.\n\n It's useful when the server config will be based on parameters in the\n ClientHello: server name indication (SNI), ALPN protocols, signature\n schemes, and cipher suites.\n\n In particular, if a server wants to do some potentially expensive work\n to load a certificate for a given hostname, rustls_acceptor allows doing\n that asynchronously, as opposed to rustls_server_config_builder_set_hello_callback(),\n which doesn't work well for asynchronous I/O.\n\n The general flow is:\n - rustls_acceptor_new()\n - Loop:\n - Read bytes from the network it with rustls_acceptor_read_tls().\n - If successful, parse those bytes with rustls_acceptor_accept().\n - If that returns RUSTLS_RESULT_ACCEPTOR_NOT_READY, continue.\n - Otherwise, break.\n - If rustls_acceptor_accept() returned RUSTLS_RESULT_OK:\n - Examine the resulting rustls_accepted.\n - Create or select a rustls_server_config.\n - Call rustls_accepted_into_connection().\n - Otherwise, there was a problem with the ClientHello data and the\n connection should be rejected.", + "feature": null, + "deprecation": null, + "name": "rustls_acceptor", + "text": "```c\nstruct rustls_acceptor\n```" + }, + { + "anchor": "rustls-certificate", + "comment": "An X.509 certificate, as used in rustls.\n Corresponds to `CertificateDer` in the Rust pki-types API.\n ", + "feature": null, + "deprecation": null, + "name": "rustls_certificate", + "text": "```c\nstruct rustls_certificate\n```" + }, + { + "anchor": "rustls-certified-key", + "comment": "The complete chain of certificates to send during a TLS handshake,\n plus a private key that matches the end-entity (leaf) certificate.\n\n Corresponds to `CertifiedKey` in the Rust API.\n ", + "feature": null, + "deprecation": null, + "name": "rustls_certified_key", + "text": "```c\nstruct rustls_certified_key\n```" + }, + { + "anchor": "rustls-client-cert-verifier", + "comment": "A built client certificate verifier that can be provided to a [`rustls_server_config_builder`](#rustls-server-config-builder)\n with [`rustls_server_config_builder_set_client_verifier`](#rustls-server-config-builder-set-client-verifier).", + "feature": null, + "deprecation": null, + "name": "rustls_client_cert_verifier", + "text": "```c\nstruct rustls_client_cert_verifier\n```" + }, + { + "anchor": "rustls-client-config", + "comment": "A client config that is done being constructed and is now read-only.\n\n Under the hood, this object corresponds to an `Arc`.\n ", + "feature": null, + "deprecation": null, + "name": "rustls_client_config", + "text": "```c\nstruct rustls_client_config\n```" + }, + { + "anchor": "rustls-client-config-builder", + "comment": "A client config being constructed.\n\n A builder can be modified by, e.g. `rustls_client_config_builder_load_roots_from_file`.\n Once you're done configuring settings, call [`rustls_client_config_builder_build`](#rustls-client-config-builder-build)\n to turn it into a *rustls_client_config.\n\n Alternatively, if an error occurs or, you don't wish to build a config,\n call [`rustls_client_config_builder_free`](#rustls-client-config-builder-free) to free the builder directly.\n\n This object is not safe for concurrent mutation. Under the hood,\n it corresponds to a `Box`.\n ", + "feature": null, + "deprecation": null, + "name": "rustls_client_config_builder", + "text": "```c\nstruct rustls_client_config_builder\n```" + }, + { + "anchor": "rustls-connection", + "comment": "A C representation of a Rustls `Connection`.", + "feature": null, + "deprecation": null, + "name": "rustls_connection", + "text": "```c\nstruct rustls_connection\n```" + }, + { + "anchor": "rustls-crypto-provider", + "comment": "A C representation of a Rustls [`CryptoProvider`].", + "feature": null, + "deprecation": null, + "name": "rustls_crypto_provider", + "text": "```c\nstruct rustls_crypto_provider\n```" + }, + { + "anchor": "rustls-crypto-provider-builder", + "comment": "A [`rustls_crypto_provider`](#rustls-crypto-provider) builder.", + "feature": null, + "deprecation": null, + "name": "rustls_crypto_provider_builder", + "text": "```c\nstruct rustls_crypto_provider_builder\n```" + }, + { + "anchor": "rustls-hpke", + "comment": "A collection of supported Hybrid Public Key Encryption (HPKE) suites.\n\n [`rustls_hpke`](#rustls-hpke) can be provided to [`rustls_client_config_builder_enable_ech`](#rustls-client-config-builder-enable-ech) and\n [`rustls_client_config_builder_enable_ech_grease()`](#rustls-client-config-builder-enable-ech-grease) to customize a\n [`rustls_client_config_builder`](#rustls-client-config-builder) to use Encrypted Client Hello (ECH).", + "feature": null, + "deprecation": null, + "name": "rustls_hpke", + "text": "```c\nstruct rustls_hpke\n```" + }, + { + "anchor": "rustls-iovec", + "comment": "An alias for `struct iovec` from uio.h (on Unix) or `WSABUF` on Windows.\n\n You should cast `const struct rustls_iovec *` to `const struct iovec *` on\n Unix, or `const *LPWSABUF` on Windows. See [`std::io::IoSlice`] for details\n on interoperability with platform specific vectored IO.", + "feature": null, + "deprecation": null, + "name": "rustls_iovec", + "text": "```c\nstruct rustls_iovec\n```" + }, + { + "anchor": "rustls-root-cert-store", + "comment": "A root certificate store.\n ", + "feature": null, + "deprecation": null, + "name": "rustls_root_cert_store", + "text": "```c\nstruct rustls_root_cert_store\n```" + }, + { + "anchor": "rustls-root-cert-store-builder", + "comment": "A [`rustls_root_cert_store`](#rustls-root-cert-store) being constructed.\n\n A builder can be modified by adding trust anchor root certificates with\n [`rustls_root_cert_store_builder_add_pem`](#rustls-root-cert-store-builder-add-pem). Once you're done adding root certificates,\n call [`rustls_root_cert_store_builder_build`](#rustls-root-cert-store-builder-build) to turn it into a [`rustls_root_cert_store`](#rustls-root-cert-store).\n This object is not safe for concurrent mutation.", + "feature": null, + "deprecation": null, + "name": "rustls_root_cert_store_builder", + "text": "```c\nstruct rustls_root_cert_store_builder\n```" + }, + { + "anchor": "rustls-server-cert-verifier", + "comment": "A built server certificate verifier that can be provided to a [`rustls_client_config_builder`](#rustls-client-config-builder)\n with [`rustls_client_config_builder_set_server_verifier`](#rustls-client-config-builder-set-server-verifier).", + "feature": null, + "deprecation": null, + "name": "rustls_server_cert_verifier", + "text": "```c\nstruct rustls_server_cert_verifier\n```" + }, + { + "anchor": "rustls-server-config", + "comment": "A server config that is done being constructed and is now read-only.\n\n Under the hood, this object corresponds to an `Arc`.\n ", + "feature": null, + "deprecation": null, + "name": "rustls_server_config", + "text": "```c\nstruct rustls_server_config\n```" + }, + { + "anchor": "rustls-server-config-builder", + "comment": "A server config being constructed.\n\n A builder can be modified by,\n e.g. rustls_server_config_builder_load_native_roots. Once you're\n done configuring settings, call rustls_server_config_builder_build\n to turn it into a *const rustls_server_config.\n\n Alternatively, if an error occurs or, you don't wish to build a config,\n call [`rustls_server_config_builder_free`](#rustls-server-config-builder-free) to free the builder directly.\n\n This object is not safe for concurrent mutation.\n ", + "feature": null, + "deprecation": null, + "name": "rustls_server_config_builder", + "text": "```c\nstruct rustls_server_config_builder\n```" + }, + { + "anchor": "rustls-signing-key", + "comment": "A signing key that can be used to construct a certified key.", + "feature": null, + "deprecation": null, + "name": "rustls_signing_key", + "text": "```c\nstruct rustls_signing_key\n```" + }, + { + "anchor": "rustls-slice-slice-bytes", + "comment": "A read-only view of a slice of Rust byte slices.\n\n This is used to pass data from rustls-ffi to callback functions provided\n by the user of the API. Because Vec and slice are not `#[repr(C)]`, we\n provide access via a pointer to an opaque struct and an accessor method\n that acts on that struct to get entries of type [`rustls_slice_bytes`](#rustls-slice-bytes).\n Internally, the pointee is a `&[&[u8]]`.\n\n The memory exposed is available as specified by the function\n using this in its signature. For instance, when this is a parameter to a\n callback, the lifetime will usually be the duration of the callback.\n Functions that receive one of these must not call its methods beyond the\n allowed lifetime.", + "feature": null, + "deprecation": null, + "name": "rustls_slice_slice_bytes", + "text": "```c\nstruct rustls_slice_slice_bytes\n```" + }, + { + "anchor": "rustls-slice-str", + "comment": "A read-only view of a slice of multiple Rust `&str`'s (that is, multiple\n strings).\n\n Like [`rustls_str`](#rustls-str), this guarantees that each string contains\n UTF-8 and no NUL bytes. Strings are not NUL-terminated.\n\n This is used to pass data from rustls-ffi to callback functions provided\n by the user of the API. Because Vec and slice are not `#[repr(C)]`, we\n can't provide a straightforward `data` and `len` structure. Instead, we\n provide access via a pointer to an opaque struct and accessor methods.\n Internally, the pointee is a `&[&str]`.\n\n The memory exposed is available as specified by the function\n using this in its signature. For instance, when this is a parameter to a\n callback, the lifetime will usually be the duration of the callback.\n Functions that receive one of these must not call its methods beyond the\n allowed lifetime.", + "feature": null, + "deprecation": null, + "name": "rustls_slice_str", + "text": "```c\nstruct rustls_slice_str\n```" + }, + { + "anchor": "rustls-supported-ciphersuite", + "comment": "A cipher suite supported by rustls.", + "feature": null, + "deprecation": null, + "name": "rustls_supported_ciphersuite", + "text": "```c\nstruct rustls_supported_ciphersuite\n```" + }, + { + "anchor": "rustls-web-pki-client-cert-verifier-builder", + "comment": "A client certificate verifier being constructed.\n\n A builder can be modified by, e.g. [`rustls_web_pki_client_cert_verifier_builder_add_crl`](#rustls-web-pki-client-cert-verifier-builder-add-crl).\n\n Once you're done configuring settings, call [`rustls_web_pki_client_cert_verifier_builder_build`](#rustls-web-pki-client-cert-verifier-builder-build)\n to turn it into a [`rustls_client_cert_verifier`](#rustls-client-cert-verifier).\n\n This object is not safe for concurrent mutation.\n\n See \n for more information.", + "feature": null, + "deprecation": null, + "name": "rustls_web_pki_client_cert_verifier_builder", + "text": "```c\nstruct rustls_web_pki_client_cert_verifier_builder\n```" + }, + { + "anchor": "rustls-web-pki-server-cert-verifier-builder", + "comment": "A server certificate verifier being constructed.\n\n A builder can be modified by, e.g. [`rustls_web_pki_server_cert_verifier_builder_add_crl`](#rustls-web-pki-server-cert-verifier-builder-add-crl).\n\n Once you're done configuring settings, call [`rustls_web_pki_server_cert_verifier_builder_build`](#rustls-web-pki-server-cert-verifier-builder-build)\n to turn it into a [`rustls_server_cert_verifier`](#rustls-server-cert-verifier). This object is not safe for concurrent mutation.\n\n See \n for more information.", + "feature": null, + "deprecation": null, + "name": "rustls_web_pki_server_cert_verifier_builder", + "text": "```c\nstruct rustls_web_pki_server_cert_verifier_builder\n```" + }, + { + "anchor": "rustls-str", + "comment": "A read-only view on a Rust `&str`.\n\n The contents are guaranteed to be valid UTF-8.\n\n As an additional guarantee on top of Rust's normal UTF-8 guarantee,\n a [`rustls_str`](#rustls-str) is guaranteed not to contain internal NUL bytes, so it is\n safe to interpolate into a C string or compare using strncmp. Keep in mind\n that it is not NUL-terminated.\n\n The memory exposed is available as specified by the function\n using this in its signature. For instance, when this is a parameter to a\n callback, the lifetime will usually be the duration of the callback.\n Functions that receive one of these must not dereference the data pointer\n beyond the allowed lifetime.", + "feature": null, + "deprecation": null, + "name": "rustls_str", + "text": "```c\nstruct rustls_str {\n const char *data;\n size_t len;\n}\n```" + }, + { + "anchor": "rustls-slice-bytes", + "comment": "A read-only view on a Rust byte slice.\n\n This is used to pass data from rustls-ffi to callback functions provided\n by the user of the API.\n `len` indicates the number of bytes than can be safely read.\n\n The memory exposed is available as specified by the function\n using this in its signature. For instance, when this is a parameter to a\n callback, the lifetime will usually be the duration of the callback.\n Functions that receive one of these must not dereference the data pointer\n beyond the allowed lifetime.", + "feature": null, + "deprecation": null, + "name": "rustls_slice_bytes", + "text": "```c\nstruct rustls_slice_bytes {\n const uint8_t *data;\n size_t len;\n}\n```" + }, + { + "anchor": "rustls-verify-server-cert-params", + "comment": "Input to a custom certificate verifier callback.\n\n See [`rustls_client_config_builder_dangerous_set_certificate_verifier()`](#rustls-client-config-builder-dangerous-set-certificate-verifier).\n\n server_name can contain a hostname, an IPv4 address in textual form, or an\n IPv6 address in textual form.", + "feature": null, + "deprecation": null, + "name": "rustls_verify_server_cert_params", + "text": "```c\nstruct rustls_verify_server_cert_params {\n struct rustls_slice_bytes end_entity_cert_der;\n const struct rustls_slice_slice_bytes *intermediate_certs_der;\n struct rustls_str server_name;\n struct rustls_slice_bytes ocsp_response;\n}\n```" + }, + { + "anchor": "rustls-log-params", + "comment": "Parameter structure passed to a `rustls_log_callback`.", + "feature": null, + "deprecation": null, + "name": "rustls_log_params", + "text": "```c\nstruct rustls_log_params {\n /**\n * The log level the message was logged at.\n */\n rustls_log_level level;\n /**\n * The message that was logged.\n */\n struct rustls_str message;\n}\n```" + }, + { + "anchor": "rustls-slice-u16", + "comment": "A read-only view on a Rust slice of 16-bit integers in platform endianness.\n\n This is used to pass data from rustls-ffi to callback functions provided\n by the user of the API.\n `len` indicates the number of bytes than can be safely read.\n\n The memory exposed is available as specified by the function\n using this in its signature. For instance, when this is a parameter to a\n callback, the lifetime will usually be the duration of the callback.\n Functions that receive one of these must not dereference the data pointer\n beyond the allowed lifetime.", + "feature": null, + "deprecation": null, + "name": "rustls_slice_u16", + "text": "```c\nstruct rustls_slice_u16 {\n const uint16_t *data;\n size_t len;\n}\n```" + }, + { + "anchor": "rustls-client-hello", + "comment": "The TLS Client Hello information provided to a ClientHelloCallback function.\n\n `server_name` is the value of the ServerNameIndication extension provided\n by the client. If the client did not send an SNI, the length of this\n `rustls_string` will be 0.\n\n `signature_schemes` carries the values supplied by the client or, if the\n client did not send this TLS extension, the default schemes in the rustls library. See:\n .\n\n `named_groups` carries the values of the `named_groups` extension sent by the\n client. If the client did not send a `named_groups` extension, the length of\n this [`rustls_slice_u16`](#rustls-slice-u16) will be 0. The meaning of this extension differ\n based on TLS version. See the Rustls documentation for more information:\n \n\n `alpn` carries the list of ALPN protocol names that the client proposed to\n the server. Again, the length of this list will be 0 if none were supplied.\n\n All this data, when passed to a callback function, is only accessible during\n the call and may not be modified. Users of this API must copy any values that\n they want to access when the callback returned.\n\n EXPERIMENTAL: this feature of rustls-ffi is likely to change in the future, as\n the rustls library is re-evaluating their current approach to client hello handling.", + "feature": null, + "deprecation": null, + "name": "rustls_client_hello", + "text": "```c\nstruct rustls_client_hello {\n struct rustls_str server_name;\n struct rustls_slice_u16 signature_schemes;\n struct rustls_slice_u16 named_groups;\n const struct rustls_slice_slice_bytes *alpn;\n}\n```" + } + ], + "functions": [ + { + "anchor": "rustls-acceptor-new", + "comment": "Create and return a new rustls_acceptor.\n\n Caller owns the pointed-to memory and must eventually free it with\n [`rustls_acceptor_free()`](#rustls-acceptor-free).", + "feature": null, + "deprecation": null, + "name": "rustls_acceptor_new", + "text": "```c\nstruct rustls_acceptor *rustls_acceptor_new(void);\n```" + }, + { + "anchor": "rustls-acceptor-free", + "comment": "Free a rustls_acceptor.\n\n Parameters:\n\n acceptor: The rustls_acceptor to free.\n\n Calling with NULL is fine. Must not be called twice with the same value.", + "feature": null, + "deprecation": null, + "name": "rustls_acceptor_free", + "text": "```c\nvoid rustls_acceptor_free(struct rustls_acceptor *acceptor);\n```" + }, + { + "anchor": "rustls-acceptor-read-tls", + "comment": "Read some TLS bytes from the network into internal buffers.\n\n The actual network I/O is performed by `callback`, which you provide.\n Rustls will invoke your callback with a suitable buffer to store the\n read bytes into. You don't have to fill it up, just fill with as many\n bytes as you get in one syscall.\n\n Parameters:\n\n acceptor: The rustls_acceptor to read bytes into.\n callback: A function that will perform the actual network I/O.\n Must be valid to call with the given userdata parameter until\n this function call returns.\n userdata: An opaque parameter to be passed directly to `callback`.\n Note: this is distinct from the `userdata` parameter set with\n [`rustls_connection_set_userdata`](#rustls-connection-set-userdata).\n out_n: An output parameter. This will be passed through to `callback`,\n which should use it to store the number of bytes written.\n\n Returns:\n\n - 0: Success. You should call [`rustls_acceptor_accept()`](#rustls-acceptor-accept) next.\n - Any non-zero value: error.\n\n This function passes through return values from `callback`. Typically\n `callback` should return an errno value. See `rustls_read_callback()` for\n more details.", + "feature": null, + "deprecation": null, + "name": "rustls_acceptor_read_tls", + "text": "```c\nrustls_io_result rustls_acceptor_read_tls(struct rustls_acceptor *acceptor,\n rustls_read_callback callback,\n void *userdata,\n size_t *out_n);\n```" + }, + { + "anchor": "rustls-acceptor-accept", + "comment": "Parse all TLS bytes read so far.\n\n If those bytes make up a ClientHello, create a rustls_accepted from them.\n\n Parameters:\n\n acceptor: The rustls_acceptor to access.\n out_accepted: An output parameter. The pointed-to pointer will be set\n to a new rustls_accepted only when the function returns\n RUSTLS_RESULT_OK. The memory is owned by the caller and must eventually\n be freed\n out_alert: An output parameter. The pointed-to pointer will be set\n to a new rustls_accepted_alert only when the function returns\n a non-OK result. The memory is owned by the caller and must eventually\n be freed with rustls_accepted_alert_free. The caller should call\n rustls_accepted_alert_write_tls to write the alert bytes to the TLS\n connection before freeing the rustls_accepted_alert.\n\n At most one of out_accepted or out_alert will be set.\n\n Returns:\n\n - RUSTLS_RESULT_OK: a ClientHello has successfully been parsed.\n A pointer to a newly allocated rustls_accepted has been written to\n *out_accepted.\n - RUSTLS_RESULT_ACCEPTOR_NOT_READY: a full ClientHello has not yet been read.\n Read more TLS bytes to continue.\n - Any other rustls_result: the TLS bytes read so far cannot be parsed\n as a ClientHello, and reading additional bytes won't help.\n\n Memory and lifetimes:\n\n After this method returns RUSTLS_RESULT_OK, `acceptor` is\n still allocated and valid. It needs to be freed regardless of success\n or failure of this function.\n\n Calling [`rustls_acceptor_accept()`](#rustls-acceptor-accept) multiple times on the same\n [`rustls_acceptor`](#rustls-acceptor) is acceptable from a memory perspective but pointless\n from a protocol perspective.", + "feature": null, + "deprecation": null, + "name": "rustls_acceptor_accept", + "text": "```c\nrustls_result rustls_acceptor_accept(struct rustls_acceptor *acceptor,\n struct rustls_accepted **out_accepted,\n struct rustls_accepted_alert **out_alert);\n```" + }, + { + "anchor": "rustls-accepted-server-name", + "comment": "Get the server name indication (SNI) from the ClientHello.\n\n Parameters:\n\n accepted: The rustls_accepted to access.\n\n Returns:\n\n A rustls_str containing the SNI field.\n\n The returned value is valid until rustls_accepted_into_connection or\n rustls_accepted_free is called on the same `accepted`. It is not owned\n by the caller and does not need to be freed.\n\n This will be a zero-length rustls_str in these error cases:\n\n - The SNI contains a NUL byte.\n - The `accepted` parameter was NULL.\n - The `accepted` parameter was already transformed into a connection\n with rustls_accepted_into_connection.", + "feature": null, + "deprecation": null, + "name": "rustls_accepted_server_name", + "text": "```c\nstruct rustls_str rustls_accepted_server_name(const struct rustls_accepted *accepted);\n```" + }, + { + "anchor": "rustls-accepted-signature-scheme", + "comment": "Get the i'th in the list of signature schemes offered in the ClientHello.\n\n This is useful in selecting a server certificate when there are multiple\n available for the same server name, for instance when selecting\n between an RSA and an ECDSA certificate.\n\n Parameters:\n\n accepted: The rustls_accepted to access.\n i: Fetch the signature scheme at this offset.\n\n Returns:\n\n A TLS Signature Scheme from \n\n This will be 0 in these cases:\n - i is greater than the number of available cipher suites.\n - accepted is NULL.\n - rustls_accepted_into_connection has already been called with `accepted`.", + "feature": null, + "deprecation": null, + "name": "rustls_accepted_signature_scheme", + "text": "```c\nuint16_t rustls_accepted_signature_scheme(const struct rustls_accepted *accepted,\n size_t i);\n```" + }, + { + "anchor": "rustls-accepted-cipher-suite", + "comment": "Get the i'th in the list of cipher suites offered in the ClientHello.\n\n Parameters:\n\n accepted: The rustls_accepted to access.\n i: Fetch the cipher suite at this offset.\n\n Returns:\n\n A cipher suite value from \n\n This will be 0 in these cases:\n - i is greater than the number of available cipher suites.\n - accepted is NULL.\n - rustls_accepted_into_connection has already been called with `accepted`.\n\n Note that 0 is technically a valid cipher suite \"TLS_NULL_WITH_NULL_NULL\",\n but this library will never support null ciphers.", + "feature": null, + "deprecation": null, + "name": "rustls_accepted_cipher_suite", + "text": "```c\nuint16_t rustls_accepted_cipher_suite(const struct rustls_accepted *accepted,\n size_t i);\n```" + }, + { + "anchor": "rustls-accepted-alpn", + "comment": "Get the i'th in the list of ALPN protocols requested in the ClientHello.\n\n accepted: The rustls_accepted to access.\n i: Fetch the ALPN value at this offset.\n\n Returns:\n\n A rustls_slice_bytes containing the i'th ALPN protocol. This may\n contain internal NUL bytes and is not guaranteed to contain valid\n UTF-8.\n\n This will be a zero-length rustls_slice bytes in these cases:\n - i is greater than the number of offered ALPN protocols.\n - The client did not offer the ALPN extension.\n - The `accepted` parameter was already transformed into a connection\n with rustls_accepted_into_connection.\n\n The returned value is valid until rustls_accepted_into_connection or\n rustls_accepted_free is called on the same `accepted`. It is not owned\n by the caller and does not need to be freed.\n\n If you are calling this from Rust, note that the `'static` lifetime\n in the return signature is fake and must not be relied upon.", + "feature": null, + "deprecation": null, + "name": "rustls_accepted_alpn", + "text": "```c\nstruct rustls_slice_bytes rustls_accepted_alpn(const struct rustls_accepted *accepted, size_t i);\n```" + }, + { + "anchor": "rustls-accepted-into-connection", + "comment": "Turn a rustls_accepted into a rustls_connection, given the provided\n rustls_server_config.\n\n Parameters:\n\n accepted: The rustls_accepted to transform.\n config: The configuration with which to create this connection.\n out_conn: An output parameter. The pointed-to pointer will be set\n to a new rustls_connection only when the function returns\n RUSTLS_RESULT_OK.\n out_alert: An output parameter. The pointed-to pointer will be set\n to a new rustls_accepted_alert when, and only when, the function returns\n a non-OK result. The memory is owned by the caller and must eventually\n be freed with rustls_accepted_alert_free. The caller should call\n rustls_accepted_alert_write_tls to write the alert bytes to\n the TLS connection before freeing the rustls_accepted_alert.\n\n At most one of out_conn or out_alert will be set.\n\n Returns:\n\n - RUSTLS_RESULT_OK: The `accepted` parameter was successfully\n transformed into a rustls_connection, and *out_conn was written to.\n - RUSTLS_RESULT_ALREADY_USED: This function was called twice on the\n same rustls_connection.\n - RUSTLS_RESULT_NULL_PARAMETER: One of the input parameters was NULL.\n\n Memory and lifetimes:\n\n In both success and failure cases, this consumes the contents of\n `accepted` but does not free its allocated memory. In either case,\n call rustls_accepted_free to avoid a memory leak.\n\n Calling accessor methods on an `accepted` after consuming it will\n return zero or default values.\n\n The rustls_connection emitted by this function in the success case\n is owned by the caller and must eventually be freed.\n\n This function does not take ownership of `config`. It does increment\n `config`'s internal reference count, indicating that the\n rustls_connection may hold a reference to it until it is done.\n See the documentation for rustls_connection for details.", + "feature": null, + "deprecation": null, + "name": "rustls_accepted_into_connection", + "text": "```c\nrustls_result rustls_accepted_into_connection(struct rustls_accepted *accepted,\n const struct rustls_server_config *config,\n struct rustls_connection **out_conn,\n struct rustls_accepted_alert **out_alert);\n```" + }, + { + "anchor": "rustls-accepted-free", + "comment": "Free a rustls_accepted.\n\n Parameters:\n\n accepted: The rustls_accepted to free.\n\n Calling with NULL is fine. Must not be called twice with the same value.", + "feature": null, + "deprecation": null, + "name": "rustls_accepted_free", + "text": "```c\nvoid rustls_accepted_free(struct rustls_accepted *accepted);\n```" + }, + { + "anchor": "rustls-accepted-alert-write-tls", + "comment": "Write some TLS bytes (an alert) to the network.\n\n The actual network I/O is performed by `callback`, which you provide.\n Rustls will invoke your callback with a suitable buffer containing TLS\n bytes to send. You don't have to write them all, just as many as you can\n in one syscall.\n\n The `userdata` parameter is passed through directly to `callback`. Note that\n this is distinct from the `userdata` parameter set with\n [`rustls_connection_set_userdata`](#rustls-connection-set-userdata).\n\n Returns 0 for success, or an errno value on error. Passes through return values\n from callback. See [`rustls_write_callback`] or [`AcceptedAlert`] for\n more details.", + "feature": null, + "deprecation": null, + "name": "rustls_accepted_alert_write_tls", + "text": "```c\nrustls_io_result rustls_accepted_alert_write_tls(struct rustls_accepted_alert *accepted_alert,\n rustls_write_callback callback,\n void *userdata,\n size_t *out_n);\n```" + }, + { + "anchor": "rustls-accepted-alert-free", + "comment": "Free a rustls_accepted_alert.\n\n Parameters:\n\n accepted_alert: The rustls_accepted_alert to free.\n\n Calling with NULL is fine. Must not be called twice with the same value.", + "feature": null, + "deprecation": null, + "name": "rustls_accepted_alert_free", + "text": "```c\nvoid rustls_accepted_alert_free(struct rustls_accepted_alert *accepted_alert);\n```" + }, + { + "anchor": "rustls-certificate-get-der", + "comment": "Get the DER data of the certificate itself.\n The data is owned by the certificate and has the same lifetime.", + "feature": null, + "deprecation": null, + "name": "rustls_certificate_get_der", + "text": "```c\nrustls_result rustls_certificate_get_der(const struct rustls_certificate *cert,\n const uint8_t **out_der_data,\n size_t *out_der_len);\n```" + }, + { + "anchor": "rustls-certified-key-build", + "comment": "Build a [`rustls_certified_key`](#rustls-certified-key) from a certificate chain and a private key\n and the default process-wide crypto provider.\n\n `cert_chain` must point to a buffer of `cert_chain_len` bytes, containing\n a series of PEM-encoded certificates, with the end-entity (leaf)\n certificate first.\n\n `private_key` must point to a buffer of `private_key_len` bytes, containing\n a PEM-encoded private key in either PKCS#1, PKCS#8 or SEC#1 format when\n using `aws-lc-rs` as the crypto provider. Supported formats may vary by\n provider.\n\n On success, this writes a pointer to the newly created\n [`rustls_certified_key`](#rustls-certified-key) in `certified_key_out`. That pointer must later\n be freed with [`rustls_certified_key_free`](#rustls-certified-key-free) to avoid memory leaks. Note that\n internally, this is an atomically reference-counted pointer, so even after\n the original caller has called [`rustls_certified_key_free`](#rustls-certified-key-free), other objects\n may retain a pointer to the object. The memory will be freed when all\n references are gone.\n\n This function does not take ownership of any of its input pointers. It\n parses the pointed-to data and makes a copy of the result. You may\n free the cert_chain and private_key pointers after calling it.\n\n Typically, you will build a [`rustls_certified_key`](#rustls-certified-key), use it to create a\n [`rustls_server_config`](#rustls-server-config) (which increments the reference count), and then\n immediately call [`rustls_certified_key_free`](#rustls-certified-key-free). That leaves the\n [`rustls_server_config`](#rustls-server-config) in possession of the sole reference, so the\n [`rustls_certified_key`](#rustls-certified-key)'s memory will automatically be released when\n the [`rustls_server_config`](#rustls-server-config) is freed.", + "feature": null, + "deprecation": null, + "name": "rustls_certified_key_build", + "text": "```c\nrustls_result rustls_certified_key_build(const uint8_t *cert_chain,\n size_t cert_chain_len,\n const uint8_t *private_key,\n size_t private_key_len,\n const struct rustls_certified_key **certified_key_out);\n```" + }, + { + "anchor": "rustls-certified-key-build-with-signing-key", + "comment": "Build a [`rustls_certified_key`](#rustls-certified-key) from a certificate chain and a\n [`rustls_signing_key`](#rustls-signing-key).\n\n `cert_chain` must point to a buffer of `cert_chain_len` bytes, containing\n a series of PEM-encoded certificates, with the end-entity (leaf)\n certificate first.\n\n `signing_key` must point to a [`rustls_signing_key`](#rustls-signing-key) loaded using a\n [`rustls_crypto_provider`](#rustls-crypto-provider) and [`rustls_crypto_provider_load_key()`](#rustls-crypto-provider-load-key).\n\n On success, this writes a pointer to the newly created\n [`rustls_certified_key`](#rustls-certified-key) in `certified_key_out`. That pointer must later\n be freed with [`rustls_certified_key_free`](#rustls-certified-key-free) to avoid memory leaks. Note that\n internally, this is an atomically reference-counted pointer, so even after\n the original caller has called [`rustls_certified_key_free`](#rustls-certified-key-free), other objects\n may retain a pointer to the object. The memory will be freed when all\n references are gone.\n\n This function does not take ownership of any of its input pointers. It\n parses the pointed-to data and makes a copy of the result. You may\n free the cert_chain and private_key pointers after calling it.\n\n Typically, you will build a [`rustls_certified_key`](#rustls-certified-key), use it to create a\n [`rustls_server_config`](#rustls-server-config) (which increments the reference count), and then\n immediately call [`rustls_certified_key_free`](#rustls-certified-key-free). That leaves the\n [`rustls_server_config`](#rustls-server-config) in possession of the sole reference, so the\n [`rustls_certified_key`](#rustls-certified-key)'s memory will automatically be released when\n the [`rustls_server_config`](#rustls-server-config) is freed.", + "feature": null, + "deprecation": null, + "name": "rustls_certified_key_build_with_signing_key", + "text": "```c\nrustls_result rustls_certified_key_build_with_signing_key(const uint8_t *cert_chain,\n size_t cert_chain_len,\n struct rustls_signing_key *signing_key,\n const struct rustls_certified_key **certified_key_out);\n```" + }, + { + "anchor": "rustls-certified-key-get-certificate", + "comment": "Return the i-th rustls_certificate in the rustls_certified_key.\n\n 0 gives the end-entity certificate. 1 and higher give certificates from the chain.\n\n Indexes higher than the last available certificate return NULL.\n\n The returned certificate is valid until the rustls_certified_key is freed.", + "feature": null, + "deprecation": null, + "name": "rustls_certified_key_get_certificate", + "text": "```c\nconst struct rustls_certificate *rustls_certified_key_get_certificate(const struct rustls_certified_key *certified_key,\n size_t i);\n```" + }, + { + "anchor": "rustls-certified-key-clone-with-ocsp", + "comment": "Create a copy of the rustls_certified_key with the given OCSP response data\n as DER encoded bytes.\n\n The OCSP response may be given as NULL to clear any possibly present OCSP\n data from the cloned key.\n\n The cloned key is independent from its original and needs to be freed\n by the application.", + "feature": null, + "deprecation": null, + "name": "rustls_certified_key_clone_with_ocsp", + "text": "```c\nrustls_result rustls_certified_key_clone_with_ocsp(const struct rustls_certified_key *certified_key,\n const struct rustls_slice_bytes *ocsp_response,\n const struct rustls_certified_key **cloned_key_out);\n```" + }, + { + "anchor": "rustls-certified-key-keys-match", + "comment": "Verify the consistency of this [`rustls_certified_key`](#rustls-certified-key)'s public and private keys.\n\n This is done by performing a comparison of subject public key information (SPKI) bytes\n between the certificate and private key.\n\n If the private key matches the certificate this function returns `RUSTLS_RESULT_OK`,\n otherwise an error [`rustls_result`](#rustls-result) is returned.", + "feature": null, + "deprecation": null, + "name": "rustls_certified_key_keys_match", + "text": "```c\nrustls_result rustls_certified_key_keys_match(const struct rustls_certified_key *key);\n```" + }, + { + "anchor": "rustls-certified-key-free", + "comment": "\"Free\" a certified_key previously returned from [`rustls_certified_key_build`](#rustls-certified-key-build).\n\n Since certified_key is actually an atomically reference-counted pointer,\n extant certified_key may still hold an internal reference to the Rust object.\n\n However, C code must consider this pointer unusable after \"free\"ing it.\n\n Calling with NULL is fine. Must not be called twice with the same value.", + "feature": null, + "deprecation": null, + "name": "rustls_certified_key_free", + "text": "```c\nvoid rustls_certified_key_free(const struct rustls_certified_key *key);\n```" + }, + { + "anchor": "rustls-root-cert-store-builder-new", + "comment": "Create a [`rustls_root_cert_store_builder`](#rustls-root-cert-store-builder).\n\n Caller owns the memory and may free it with [`rustls_root_cert_store_free`](#rustls-root-cert-store-free), regardless of\n whether [`rustls_root_cert_store_builder_build`](#rustls-root-cert-store-builder-build) was called.\n\n If you wish to abandon the builder without calling [`rustls_root_cert_store_builder_build`](#rustls-root-cert-store-builder-build),\n it must be freed with [`rustls_root_cert_store_builder_free`](#rustls-root-cert-store-builder-free).", + "feature": null, + "deprecation": null, + "name": "rustls_root_cert_store_builder_new", + "text": "```c\nstruct rustls_root_cert_store_builder *rustls_root_cert_store_builder_new(void);\n```" + }, + { + "anchor": "rustls-root-cert-store-builder-add-pem", + "comment": "Add one or more certificates to the root cert store builder using PEM\n encoded data.\n\n When `strict` is true an error will return a `CertificateParseError`\n result. So will an attempt to parse data that has zero certificates.\n\n When `strict` is false, unparseable root certificates will be ignored.\n This may be useful on systems that have syntactically invalid root\n certificates.", + "feature": null, + "deprecation": null, + "name": "rustls_root_cert_store_builder_add_pem", + "text": "```c\nrustls_result rustls_root_cert_store_builder_add_pem(struct rustls_root_cert_store_builder *builder,\n const uint8_t *pem,\n size_t pem_len,\n bool strict);\n```" + }, + { + "anchor": "rustls-root-cert-store-builder-load-roots-from-file", + "comment": "Add one or more certificates to the root cert store builder using PEM\n encoded data read from the named file.\n\n When `strict` is true an error will return a `CertificateParseError`\n result. So will an attempt to parse data that has zero certificates.\n\n When `strict` is false, unparseable root certificates will be ignored.\n This may be useful on systems that have syntactically invalid root\n certificates.", + "feature": null, + "deprecation": null, + "name": "rustls_root_cert_store_builder_load_roots_from_file", + "text": "```c\nrustls_result rustls_root_cert_store_builder_load_roots_from_file(struct rustls_root_cert_store_builder *builder,\n const char *filename,\n bool strict);\n```" + }, + { + "anchor": "rustls-root-cert-store-builder-build", + "comment": "Create a new [`rustls_root_cert_store`](#rustls-root-cert-store) from the builder.\n\n The builder is consumed and cannot be used again, but must still be freed.\n\n The root cert store can be used in several [`rustls_web_pki_client_cert_verifier_builder_new`](#rustls-web-pki-client-cert-verifier-builder-new)\n instances and must be freed by the application when no longer needed. See the documentation of\n [`rustls_root_cert_store_free`](#rustls-root-cert-store-free) for details about lifetime.", + "feature": null, + "deprecation": null, + "name": "rustls_root_cert_store_builder_build", + "text": "```c\nrustls_result rustls_root_cert_store_builder_build(struct rustls_root_cert_store_builder *builder,\n const struct rustls_root_cert_store **root_cert_store_out);\n```" + }, + { + "anchor": "rustls-root-cert-store-builder-free", + "comment": "Free a [`rustls_root_cert_store_builder`](#rustls-root-cert-store-builder) previously returned from\n [`rustls_root_cert_store_builder_new`](#rustls-root-cert-store-builder-new).\n\n Calling with NULL is fine. Must not be called twice with the same value.", + "feature": null, + "deprecation": null, + "name": "rustls_root_cert_store_builder_free", + "text": "```c\nvoid rustls_root_cert_store_builder_free(struct rustls_root_cert_store_builder *builder);\n```" + }, + { + "anchor": "rustls-root-cert-store-free", + "comment": "Free a rustls_root_cert_store previously returned from rustls_root_cert_store_builder_build.\n\n Calling with NULL is fine. Must not be called twice with the same value.", + "feature": null, + "deprecation": null, + "name": "rustls_root_cert_store_free", + "text": "```c\nvoid rustls_root_cert_store_free(const struct rustls_root_cert_store *store);\n```" + }, + { + "anchor": "rustls-supported-ciphersuite-get-suite", + "comment": "Return a 16-bit unsigned integer corresponding to this cipher suite's assignment from\n .\n\n The bytes from the assignment are interpreted in network order.", + "feature": null, + "deprecation": null, + "name": "rustls_supported_ciphersuite_get_suite", + "text": "```c\nuint16_t rustls_supported_ciphersuite_get_suite(const struct rustls_supported_ciphersuite *supported_ciphersuite);\n```" + }, + { + "anchor": "rustls-supported-ciphersuite-get-name", + "comment": "Returns the name of the ciphersuite as a [`rustls_str`](#rustls-str).\n\n If the provided ciphersuite is invalid, the [`rustls_str`](#rustls-str) will contain the\n empty string. The lifetime of the [`rustls_str`](#rustls-str) is the lifetime of the program,\n it does not need to be freed.", + "feature": null, + "deprecation": null, + "name": "rustls_supported_ciphersuite_get_name", + "text": "```c\nstruct rustls_str rustls_supported_ciphersuite_get_name(const struct rustls_supported_ciphersuite *supported_ciphersuite);\n```" + }, + { + "anchor": "rustls-supported-ciphersuite-protocol-version", + "comment": "Returns the [`rustls_tls_version`](#rustls-tls-version) of the ciphersuite.\n\n See also `RUSTLS_ALL_VERSIONS`.", + "feature": null, + "deprecation": null, + "name": "rustls_supported_ciphersuite_protocol_version", + "text": "```c\nenum rustls_tls_version rustls_supported_ciphersuite_protocol_version(const struct rustls_supported_ciphersuite *supported_ciphersuite);\n```" + }, + { + "anchor": "rustls-client-config-builder-new", + "comment": "Create a rustls_client_config_builder using the process default crypto provider.\n\n Caller owns the memory and must eventually call [`rustls_client_config_builder_build`](#rustls-client-config-builder-build),\n then free the resulting [`rustls_client_config`](#rustls-client-config).\n\n Alternatively, if an error occurs or, you don't wish to build a config,\n call [`rustls_client_config_builder_free`](#rustls-client-config-builder-free) to free the builder directly.\n\n This uses the process default provider's values for the cipher suites and key\n exchange groups, as well as safe defaults for protocol versions.\n\n This starts out with no trusted roots. Caller must add roots with\n rustls_client_config_builder_load_roots_from_file or provide a custom verifier.", + "feature": null, + "deprecation": null, + "name": "rustls_client_config_builder_new", + "text": "```c\nstruct rustls_client_config_builder *rustls_client_config_builder_new(void);\n```" + }, + { + "anchor": "rustls-client-config-builder-new-custom", + "comment": "Create a rustls_client_config_builder using the specified crypto provider.\n\n Caller owns the memory and must eventually call [`rustls_client_config_builder_build`](#rustls-client-config-builder-build),\n then free the resulting [`rustls_client_config`](#rustls-client-config).\n\n Alternatively, if an error occurs or, you don't wish to build a config,\n call [`rustls_client_config_builder_free`](#rustls-client-config-builder-free) to free the builder directly.\n\n `tls_version` sets the TLS protocol versions to use when negotiating a TLS session.\n `tls_version` is the version of the protocol, as defined in rfc8446,\n ch. 4.2.1 and end of ch. 5.1. Some values are defined in\n [`rustls_tls_version`](#rustls-tls-version) for convenience, and the arrays\n RUSTLS_DEFAULT_VERSIONS or RUSTLS_ALL_VERSIONS can be used directly.\n\n `tls_versions` will only be used during the call and the application retains\n ownership. `tls_versions_len` is the number of consecutive `uint16_t`\n pointed to by `tls_versions`.\n\n Ciphersuites are configured separately via the crypto provider. See\n [`rustls_crypto_provider_builder_set_cipher_suites`](#rustls-crypto-provider-builder-set-cipher-suites) for more information.", + "feature": null, + "deprecation": null, + "name": "rustls_client_config_builder_new_custom", + "text": "```c\nrustls_result rustls_client_config_builder_new_custom(const struct rustls_crypto_provider *provider,\n const uint16_t *tls_versions,\n size_t tls_versions_len,\n struct rustls_client_config_builder **builder_out);\n```" + }, + { + "anchor": "rustls-client-config-builder-dangerous-set-certificate-verifier", + "comment": "Set a custom server certificate verifier using the builder crypto provider.\n Returns rustls_result::NoDefaultCryptoProvider if no process default crypto\n provider has been set, and the builder was not constructed with an explicit\n provider choice.\n\n The callback must not capture any of the pointers in its\n rustls_verify_server_cert_params.\n If `userdata` has been set with rustls_connection_set_userdata, it\n will be passed to the callback. Otherwise the userdata param passed to\n the callback will be NULL.\n\n The callback must be safe to call on any thread at any time, including\n multiple concurrent calls. So, for instance, if the callback mutates\n userdata (or other shared state), it must use synchronization primitives\n to make such mutation safe.\n\n The callback receives certificate chain information as raw bytes.\n Currently this library offers no functions to parse the certificates,\n so you'll need to bring your own certificate parsing library\n if you need to parse them.\n\n If the custom verifier accepts the certificate, it should return\n RUSTLS_RESULT_OK. Otherwise, it may return any other rustls_result error.\n Feel free to use an appropriate error from the RUSTLS_RESULT_CERT_*\n section.\n\n ", + "feature": null, + "deprecation": null, + "name": "rustls_client_config_builder_dangerous_set_certificate_verifier", + "text": "```c\nrustls_result rustls_client_config_builder_dangerous_set_certificate_verifier(struct rustls_client_config_builder *config_builder,\n rustls_verify_server_cert_callback callback);\n```" + }, + { + "anchor": "rustls-client-config-builder-set-server-verifier", + "comment": "Configure the server certificate verifier.\n\n This increases the reference count of `verifier` and does not take ownership.", + "feature": null, + "deprecation": null, + "name": "rustls_client_config_builder_set_server_verifier", + "text": "```c\nvoid rustls_client_config_builder_set_server_verifier(struct rustls_client_config_builder *builder,\n const struct rustls_server_cert_verifier *verifier);\n```" + }, + { + "anchor": "rustls-client-config-builder-set-alpn-protocols", + "comment": "Set the ALPN protocol list to the given protocols.\n\n `protocols` must point to a buffer of [`rustls_slice_bytes`](#rustls-slice-bytes) (built by the caller) with `len`\n elements.\n\n Each element of the buffer must be a rustls_slice_bytes whose\n data field points to a single ALPN protocol ID.\n\n Standard ALPN protocol IDs are defined at\n .\n\n This function makes a copy of the data in `protocols` and does not retain\n any pointers, so the caller can free the pointed-to memory after calling.\n\n ", + "feature": null, + "deprecation": null, + "name": "rustls_client_config_builder_set_alpn_protocols", + "text": "```c\nrustls_result rustls_client_config_builder_set_alpn_protocols(struct rustls_client_config_builder *builder,\n const struct rustls_slice_bytes *protocols,\n size_t len);\n```" + }, + { + "anchor": "rustls-client-config-builder-set-enable-sni", + "comment": "Enable or disable SNI.\n ", + "feature": null, + "deprecation": null, + "name": "rustls_client_config_builder_set_enable_sni", + "text": "```c\nvoid rustls_client_config_builder_set_enable_sni(struct rustls_client_config_builder *config,\n bool enable);\n```" + }, + { + "anchor": "rustls-client-config-builder-set-certified-key", + "comment": "Provide the configuration a list of certificates where the connection\n will select the first one that is compatible with the server's signature\n verification capabilities.\n\n Clients that want to support both ECDSA and RSA certificates will want the\n ECSDA to go first in the list.\n\n The built configuration will keep a reference to all certified keys\n provided. The client may [`rustls_certified_key_free()`](#rustls-certified-key-free) afterwards\n without the configuration losing them. The same certified key may also\n be used in multiple configs.\n\n EXPERIMENTAL: installing a client authentication callback will replace any\n configured certified keys and vice versa.", + "feature": null, + "deprecation": null, + "name": "rustls_client_config_builder_set_certified_key", + "text": "```c\nrustls_result rustls_client_config_builder_set_certified_key(struct rustls_client_config_builder *builder,\n const struct rustls_certified_key *const *certified_keys,\n size_t certified_keys_len);\n```" + }, + { + "anchor": "rustls-client-config-builder-set-key-log-file", + "comment": "Log key material to the file specified by the `SSLKEYLOGFILE` environment variable.\n\n The key material will be logged in the NSS key log format,\n and is\n compatible with tools like Wireshark.\n\n Secrets logged in this manner are **extremely sensitive** and can break the security\n of past, present and future sessions.\n\n For more control over which secrets are logged, or to customize the format, prefer\n [`rustls_client_config_builder_set_key_log`](#rustls-client-config-builder-set-key-log).", + "feature": null, + "deprecation": null, + "name": "rustls_client_config_builder_set_key_log_file", + "text": "```c\nrustls_result rustls_client_config_builder_set_key_log_file(struct rustls_client_config_builder *builder);\n```" + }, + { + "anchor": "rustls-client-config-builder-set-key-log", + "comment": "Provide callbacks to manage logging key material.\n\n The `log_cb` argument is mandatory and must not be `NULL` or a `NullParameter` error is\n returned. The `log_cb` will be invoked with a `client_random` to identify the relevant session,\n a `label` to identify the purpose of the `secret`, and the `secret` itself. See the\n Rustls documentation of the `KeyLog` trait for more information on possible labels:\n \n\n The `will_log_cb` may be `NULL`, in which case all key material will be provided to\n the `log_cb`. By providing a custom `will_log_cb` you may return `0` for labels you don't\n wish to log, and non-zero for labels you _do_ wish to log as a performance optimization.\n\n Both callbacks **must** be thread-safe. Arguments provided to the callback live only for as\n long as the callback is executing and are not valid after the callback returns. The\n callbacks must not retain references to the provided data.\n\n Secrets provided to the `log_cb` are **extremely sensitive** and can break the security\n of past, present and future sessions.\n\n See also [`rustls_client_config_builder_set_key_log_file`](#rustls-client-config-builder-set-key-log-file) for a simpler way to log\n to a file specified by the `SSLKEYLOGFILE` environment variable.", + "feature": null, + "deprecation": null, + "name": "rustls_client_config_builder_set_key_log", + "text": "```c\nrustls_result rustls_client_config_builder_set_key_log(struct rustls_client_config_builder *builder,\n rustls_keylog_log_callback log_cb,\n rustls_keylog_will_log_callback will_log_cb);\n```" + }, + { + "anchor": "rustls-client-config-builder-enable-ech", + "comment": "Configure the client for Encrypted Client Hello (ECH).\n\n This requires providing a TLS encoded list of ECH configurations that should\n have been retrieved from the DNS HTTPS record for the domain you intend to connect to.\n This should be done using DNS-over-HTTPS to avoid leaking the domain name you are\n connecting to ahead of the TLS handshake.\n\n At least one of the ECH configurations must be compatible with the provided [`rustls_hpke`](#rustls-hpke)\n instance. See [`rustls_supported_hpke()`](#rustls-supported-hpke) for more information.\n\n Calling this function will replace any existing ECH configuration set by\n previous calls to [`rustls_client_config_builder_enable_ech()`](#rustls-client-config-builder-enable-ech) or\n [`rustls_client_config_builder_enable_ech_grease()`](#rustls-client-config-builder-enable-ech-grease).\n\n The provided `ech_config_list_bytes` and [`rustls_hpke`](#rustls-hpke) must not be NULL or an\n error will be returned. The caller maintains ownership of the ECH config list TLS bytes\n and [`rustls_hpke`](#rustls-hpke) instance. This function does not retain any reference to\n `ech_config_list_bytes`.\n\n A `RUSTLS_RESULT_BUILDER_INCOMPATIBLE_TLS_VERSIONS` error is returned if the builder's\n TLS versions have been customized via [`rustls_client_config_builder_new_custom()`](#rustls-client-config-builder-new-custom)\n and the customization isn't \"only TLS 1.3\". ECH may only be used with TLS 1.3.", + "feature": null, + "deprecation": null, + "name": "rustls_client_config_builder_enable_ech", + "text": "```c\nrustls_result rustls_client_config_builder_enable_ech(struct rustls_client_config_builder *builder,\n const uint8_t *ech_config_list_bytes,\n size_t ech_config_list_bytes_size,\n const struct rustls_hpke *hpke);\n```" + }, + { + "anchor": "rustls-client-config-builder-enable-ech-grease", + "comment": "Configure the client for GREASE Encrypted Client Hello (ECH).\n\n This is a feature to prevent ossification of the TLS handshake by acting as though\n ECH were configured for an imaginary ECH config generated with one of the\n [`rustls_hpke`](#rustls-hpke) supported suites, chosen at random.\n\n The provided [`rustls_client_config_builder`](#rustls-client-config-builder) and [`rustls_hpke`](#rustls-hpke) must not be NULL or an\n error will be returned. The caller maintains ownership of both the\n [`rustls_client_config_builder`](#rustls-client-config-builder) and the [`rustls_hpke`](#rustls-hpke) instance.\n\n Calling this function will replace any existing ECH configuration set by\n previous calls to [`rustls_client_config_builder_enable_ech()`](#rustls-client-config-builder-enable-ech) or\n [`rustls_client_config_builder_enable_ech_grease()`](#rustls-client-config-builder-enable-ech-grease).\n\n A `RUSTLS_RESULT_BUILDER_INCOMPATIBLE_TLS_VERSIONS` error is returned if the builder's\n TLS versions have been customized via [`rustls_client_config_builder_new_custom()`](#rustls-client-config-builder-new-custom)\n and the customization isn't \"only TLS 1.3\". ECH may only be used with TLS 1.3.", + "feature": null, + "deprecation": null, + "name": "rustls_client_config_builder_enable_ech_grease", + "text": "```c\nrustls_result rustls_client_config_builder_enable_ech_grease(struct rustls_client_config_builder *builder,\n const struct rustls_hpke *hpke);\n```" + }, + { + "anchor": "rustls-client-config-builder-build", + "comment": "Turn a *rustls_client_config_builder (mutable) into a const *rustls_client_config\n (read-only).", + "feature": null, + "deprecation": null, + "name": "rustls_client_config_builder_build", + "text": "```c\nrustls_result rustls_client_config_builder_build(struct rustls_client_config_builder *builder,\n const struct rustls_client_config **config_out);\n```" + }, + { + "anchor": "rustls-client-config-builder-free", + "comment": "\"Free\" a client_config_builder without building it into a rustls_client_config.\n\n Normally builders are built into rustls_client_config via [`rustls_client_config_builder_build`](#rustls-client-config-builder-build)\n and may not be free'd or otherwise used afterwards.\n\n Use free only when the building of a config has to be aborted before a config\n was created.", + "feature": null, + "deprecation": null, + "name": "rustls_client_config_builder_free", + "text": "```c\nvoid rustls_client_config_builder_free(struct rustls_client_config_builder *config);\n```" + }, + { + "anchor": "rustls-client-config-fips", + "comment": "Returns true if a [`rustls_connection`](#rustls-connection) created from the [`rustls_client_config`](#rustls-client-config) will\n operate in FIPS mode.\n\n This is different from [`rustls_crypto_provider_fips`](#rustls-crypto-provider-fips) which is concerned\n only with cryptography, whereas this also covers TLS-level configuration that NIST\n recommends, as well as ECH HPKE suites if applicable.", + "feature": null, + "deprecation": null, + "name": "rustls_client_config_fips", + "text": "```c\nbool rustls_client_config_fips(const struct rustls_client_config *config);\n```" + }, + { + "anchor": "rustls-client-config-free", + "comment": "\"Free\" a [`rustls_client_config`](#rustls-client-config) previously returned from\n [`rustls_client_config_builder_build`](#rustls-client-config-builder-build).\n\n Since [`rustls_client_config`](#rustls-client-config) is actually an atomically reference-counted pointer,\n extant client connections may still hold an internal reference to the Rust object.\n\n However, C code must consider this pointer unusable after \"free\"ing it.\n\n Calling with NULL is fine. Must not be called twice with the same value.", + "feature": null, + "deprecation": null, + "name": "rustls_client_config_free", + "text": "```c\nvoid rustls_client_config_free(const struct rustls_client_config *config);\n```" + }, + { + "anchor": "rustls-client-connection-new", + "comment": "Create a new client [`rustls_connection`](#rustls-connection).\n\n If this returns `RUSTLS_RESULT_OK`, the memory pointed to by `conn_out` is modified to\n point at a valid [`rustls_connection`](#rustls-connection). The caller now owns the [`rustls_connection`](#rustls-connection)\n and must call [`rustls_connection_free`](#rustls-connection-free) when done with it.\n\n Uses the [`rustls_client_config`](#rustls-client-config) to determine ALPN protocol support. Prefer\n [`rustls_client_connection_new_alpn`](#rustls-client-connection-new-alpn) to customize this per-connection.\n\n If this returns an error code, the memory pointed to by `conn_out` remains\n unchanged.\n\n The `server_name` parameter can contain a hostname or an IP address in\n textual form (IPv4 or IPv6). This function will return an error if it\n cannot be parsed as one of those types.", + "feature": null, + "deprecation": null, + "name": "rustls_client_connection_new", + "text": "```c\nrustls_result rustls_client_connection_new(const struct rustls_client_config *config,\n const char *server_name,\n struct rustls_connection **conn_out);\n```" + }, + { + "anchor": "rustls-client-connection-new-alpn", + "comment": "Create a new client [`rustls_connection`](#rustls-connection) with custom ALPN protocols.\n\n Operates the same as [`rustls_client_connection_new`](#rustls-client-connection-new), but allows specifying\n custom per-connection ALPN protocols instead of inheriting ALPN protocols\n from the `rustls_clinet_config`.\n\n If this returns `RUSTLS_RESULT_OK`, the memory pointed to by `conn_out` is modified to\n point at a valid [`rustls_connection`](#rustls-connection). The caller now owns the [`rustls_connection`](#rustls-connection)\n and must call [`rustls_connection_free`](#rustls-connection-free) when done with it.\n\n If this returns an error code, the memory pointed to by `conn_out` remains\n unchanged.\n\n The `server_name` parameter can contain a hostname or an IP address in\n textual form (IPv4 or IPv6). This function will return an error if it\n cannot be parsed as one of those types.\n\n `alpn_protocols` must point to a buffer of [`rustls_slice_bytes`](#rustls-slice-bytes) (built by the caller)\n with `alpn_protocols_len` elements. Each element of the buffer must be a [`rustls_slice_bytes`](#rustls-slice-bytes)\n whose data field points to a single ALPN protocol ID. This function makes a copy of the\n data in `alpn_protocols` and does not retain any pointers, so the caller can free the\n pointed-to memory after calling.\n\n Standard ALPN protocol IDs are defined at\n .", + "feature": null, + "deprecation": null, + "name": "rustls_client_connection_new_alpn", + "text": "```c\nrustls_result rustls_client_connection_new_alpn(const struct rustls_client_config *config,\n const char *server_name,\n const struct rustls_slice_bytes *alpn_protocols,\n size_t alpn_protocols_len,\n struct rustls_connection **conn_out);\n```" + }, + { + "anchor": "rustls-connection-set-userdata", + "comment": "Set the userdata pointer associated with this connection. This will be passed\n to any callbacks invoked by the connection, if you've set up callbacks in the config.\n The pointed-to data must outlive the connection.", + "feature": null, + "deprecation": null, + "name": "rustls_connection_set_userdata", + "text": "```c\nvoid rustls_connection_set_userdata(struct rustls_connection *conn, void *userdata);\n```" + }, + { + "anchor": "rustls-connection-set-log-callback", + "comment": "Set the logging callback for this connection. The log callback will be invoked\n with the userdata parameter previously set by rustls_connection_set_userdata, or\n NULL if no userdata was set.", + "feature": null, + "deprecation": null, + "name": "rustls_connection_set_log_callback", + "text": "```c\nvoid rustls_connection_set_log_callback(struct rustls_connection *conn, rustls_log_callback cb);\n```" + }, + { + "anchor": "rustls-connection-read-tls", + "comment": "Read some TLS bytes from the network into internal buffers. The actual network\n I/O is performed by `callback`, which you provide. Rustls will invoke your\n callback with a suitable buffer to store the read bytes into. You don't have\n to fill it up, just fill with as many bytes as you get in one syscall.\n The `userdata` parameter is passed through directly to `callback`. Note that\n this is distinct from the `userdata` parameter set with\n [`rustls_connection_set_userdata`](#rustls-connection-set-userdata).\n Returns 0 for success, or an errno value on error. Passes through return values\n from callback. See rustls_read_callback for more details.\n ", + "feature": null, + "deprecation": null, + "name": "rustls_connection_read_tls", + "text": "```c\nrustls_io_result rustls_connection_read_tls(struct rustls_connection *conn,\n rustls_read_callback callback,\n void *userdata,\n size_t *out_n);\n```" + }, + { + "anchor": "rustls-connection-write-tls", + "comment": "Write some TLS bytes to the network. The actual network I/O is performed by\n `callback`, which you provide. Rustls will invoke your callback with a\n suitable buffer containing TLS bytes to send. You don't have to write them\n all, just as many as you can in one syscall.\n The `userdata` parameter is passed through directly to `callback`. Note that\n this is distinct from the `userdata` parameter set with\n [`rustls_connection_set_userdata`](#rustls-connection-set-userdata).\n Returns 0 for success, or an errno value on error. Passes through return values\n from callback. See rustls_write_callback for more details.\n ", + "feature": null, + "deprecation": null, + "name": "rustls_connection_write_tls", + "text": "```c\nrustls_io_result rustls_connection_write_tls(struct rustls_connection *conn,\n rustls_write_callback callback,\n void *userdata,\n size_t *out_n);\n```" + }, + { + "anchor": "rustls-connection-write-tls-vectored", + "comment": "Write all available TLS bytes to the network. The actual network I/O is performed by\n `callback`, which you provide. Rustls will invoke your callback with an array\n of rustls_slice_bytes, each containing a buffer with TLS bytes to send.\n You don't have to write them all, just as many as you are willing.\n The `userdata` parameter is passed through directly to `callback`. Note that\n this is distinct from the `userdata` parameter set with\n [`rustls_connection_set_userdata`](#rustls-connection-set-userdata).\n Returns 0 for success, or an errno value on error. Passes through return values\n from callback. See rustls_write_callback for more details.\n ", + "feature": null, + "deprecation": null, + "name": "rustls_connection_write_tls_vectored", + "text": "```c\nrustls_io_result rustls_connection_write_tls_vectored(struct rustls_connection *conn,\n rustls_write_vectored_callback callback,\n void *userdata,\n size_t *out_n);\n```" + }, + { + "anchor": "rustls-connection-process-new-packets", + "comment": "Decrypt any available ciphertext from the internal buffer and put it\n into the internal plaintext buffer, potentially making bytes available\n for rustls_connection_read().\n ", + "feature": null, + "deprecation": null, + "name": "rustls_connection_process_new_packets", + "text": "```c\nrustls_result rustls_connection_process_new_packets(struct rustls_connection *conn);\n```" + }, + { + "anchor": "rustls-connection-wants-read", + "comment": "", + "feature": null, + "deprecation": null, + "name": "rustls_connection_wants_read", + "text": "```c\nbool rustls_connection_wants_read(const struct rustls_connection *conn);\n```" + }, + { + "anchor": "rustls-connection-wants-write", + "comment": "", + "feature": null, + "deprecation": null, + "name": "rustls_connection_wants_write", + "text": "```c\nbool rustls_connection_wants_write(const struct rustls_connection *conn);\n```" + }, + { + "anchor": "rustls-connection-is-handshaking", + "comment": "Returns true if the connection is currently performing the TLS handshake.\n\n Note: This may return `false` while there are still handshake packets waiting\n to be extracted and transmitted with [`rustls_connection_write_tls()`](#rustls-connection-write-tls).\n\n See the rustls documentation for more information.\n\n ", + "feature": null, + "deprecation": null, + "name": "rustls_connection_is_handshaking", + "text": "```c\nbool rustls_connection_is_handshaking(const struct rustls_connection *conn);\n```" + }, + { + "anchor": "rustls-connection-handshake-kind", + "comment": "Returns a [`rustls_handshake_kind`](#rustls-handshake-kind) describing the [`rustls_connection`](#rustls-connection).", + "feature": null, + "deprecation": null, + "name": "rustls_connection_handshake_kind", + "text": "```c\nenum rustls_handshake_kind rustls_connection_handshake_kind(const struct rustls_connection *conn);\n```" + }, + { + "anchor": "rustls-connection-set-buffer-limit", + "comment": "Sets a limit on the internal buffers used to buffer unsent plaintext (prior\n to completing the TLS handshake) and unsent TLS records. By default, there\n is no limit. The limit can be set at any time, even if the current buffer\n use is higher.\n ", + "feature": null, + "deprecation": null, + "name": "rustls_connection_set_buffer_limit", + "text": "```c\nvoid rustls_connection_set_buffer_limit(struct rustls_connection *conn, size_t n);\n```" + }, + { + "anchor": "rustls-connection-send-close-notify", + "comment": "Queues a close_notify fatal alert to be sent in the next write_tls call.\n ", + "feature": null, + "deprecation": null, + "name": "rustls_connection_send_close_notify", + "text": "```c\nvoid rustls_connection_send_close_notify(struct rustls_connection *conn);\n```" + }, + { + "anchor": "rustls-connection-refresh-traffic-keys", + "comment": "Queues a TLS1.3 key_update message to refresh a connection’s keys.\n\n Rustls internally manages key updates as required and so this function should\n seldom be used. See the Rustls documentation for important caveats and suggestions\n on occasions that merit its use.\n\n ", + "feature": null, + "deprecation": null, + "name": "rustls_connection_refresh_traffic_keys", + "text": "```c\nrustls_result rustls_connection_refresh_traffic_keys(struct rustls_connection *conn);\n```" + }, + { + "anchor": "rustls-connection-get-peer-certificate", + "comment": "Return the i-th certificate provided by the peer.\n Index 0 is the end entity certificate. Higher indexes are certificates\n in the chain. Requesting an index higher than what is available returns\n NULL.\n The returned pointer is valid until the next mutating function call\n affecting the connection. A mutating function call is one where the\n first argument has type `struct rustls_connection *` (as opposed to\n `const struct rustls_connection *`).\n ", + "feature": null, + "deprecation": null, + "name": "rustls_connection_get_peer_certificate", + "text": "```c\nconst struct rustls_certificate *rustls_connection_get_peer_certificate(const struct rustls_connection *conn,\n size_t i);\n```" + }, + { + "anchor": "rustls-connection-get-alpn-protocol", + "comment": "Get the ALPN protocol that was negotiated, if any. Stores a pointer to a\n borrowed buffer of bytes, and that buffer's len, in the output parameters.\n The borrow lives as long as the connection.\n If the connection is still handshaking, or no ALPN protocol was negotiated,\n stores NULL and 0 in the output parameters.\n The provided pointer is valid until the next mutating function call\n affecting the connection. A mutating function call is one where the\n first argument has type `struct rustls_connection *` (as opposed to\n `const struct rustls_connection *`).\n \n ", + "feature": null, + "deprecation": null, + "name": "rustls_connection_get_alpn_protocol", + "text": "```c\nvoid rustls_connection_get_alpn_protocol(const struct rustls_connection *conn,\n const uint8_t **protocol_out,\n size_t *protocol_out_len);\n```" + }, + { + "anchor": "rustls-connection-get-protocol-version", + "comment": "Return the TLS protocol version that has been negotiated. Before this\n has been decided during the handshake, this will return 0. Otherwise,\n the u16 version number as defined in the relevant RFC is returned.\n \n ", + "feature": null, + "deprecation": null, + "name": "rustls_connection_get_protocol_version", + "text": "```c\nuint16_t rustls_connection_get_protocol_version(const struct rustls_connection *conn);\n```" + }, + { + "anchor": "rustls-connection-get-negotiated-ciphersuite", + "comment": "Retrieves the [IANA registered cipher suite identifier][IANA] agreed with the peer.\n\n This returns `TLS_NULL_WITH_NULL_NULL` (0x0000) until the ciphersuite is agreed.\n\n [IANA]: ", + "feature": null, + "deprecation": null, + "name": "rustls_connection_get_negotiated_ciphersuite", + "text": "```c\nuint16_t rustls_connection_get_negotiated_ciphersuite(const struct rustls_connection *conn);\n```" + }, + { + "anchor": "rustls-connection-get-negotiated-ciphersuite-name", + "comment": "Retrieves the cipher suite name agreed with the peer.\n\n This returns \"\" until the ciphersuite is agreed.\n\n The lifetime of the [`rustls_str`](#rustls-str) is the lifetime of the program, it does not\n need to be freed.\n\n ", + "feature": null, + "deprecation": null, + "name": "rustls_connection_get_negotiated_ciphersuite_name", + "text": "```c\nstruct rustls_str rustls_connection_get_negotiated_ciphersuite_name(const struct rustls_connection *conn);\n```" + }, + { + "anchor": "rustls-connection-get-negotiated-key-exchange-group", + "comment": "Retrieves the [IANA registered supported group identifier][IANA] agreed with the peer.\n\n This returns Reserved (0x0000) until the key exchange group is agreed.\n\n [IANA]: ", + "feature": null, + "deprecation": null, + "name": "rustls_connection_get_negotiated_key_exchange_group", + "text": "```c\nuint16_t rustls_connection_get_negotiated_key_exchange_group(const struct rustls_connection *conn);\n```" + }, + { + "anchor": "rustls-connection-get-negotiated-key-exchange-group-name", + "comment": "Retrieves the key exchange group name agreed with the peer.\n\n This returns \"\" until the key exchange group is agreed.\n\n The lifetime of the [`rustls_str`](#rustls-str) is the lifetime of the program, it does not\n need to be freed.", + "feature": null, + "deprecation": null, + "name": "rustls_connection_get_negotiated_key_exchange_group_name", + "text": "```c\nstruct rustls_str rustls_connection_get_negotiated_key_exchange_group_name(const struct rustls_connection *conn);\n```" + }, + { + "anchor": "rustls-connection-get-tls13-tickets-received", + "comment": "Retrieves the number of TLS 1.3 tickets that have been received by a client connection.\n\n This returns 0 if the `conn` is `NULL`, or a server connection.", + "feature": null, + "deprecation": null, + "name": "rustls_connection_get_tls13_tickets_received", + "text": "```c\nuint32_t rustls_connection_get_tls13_tickets_received(const struct rustls_connection *conn);\n```" + }, + { + "anchor": "rustls-connection-write", + "comment": "Write up to `count` plaintext bytes from `buf` into the [`rustls_connection`](#rustls-connection).\n This will increase the number of output bytes available to\n [`rustls_connection_write_tls`](#rustls-connection-write-tls).\n On success, store the number of bytes actually written in *out_n\n (this may be less than `count`).\n ", + "feature": null, + "deprecation": null, + "name": "rustls_connection_write", + "text": "```c\nrustls_result rustls_connection_write(struct rustls_connection *conn,\n const uint8_t *buf,\n size_t count,\n size_t *out_n);\n```" + }, + { + "anchor": "rustls-connection-read", + "comment": "Read up to `count` plaintext bytes from the [`rustls_connection`](#rustls-connection) into `buf`.\n On success, store the number of bytes read in *out_n (this may be less\n than `count`). A success with *out_n set to 0 means \"all bytes currently\n available have been read, but more bytes may become available after\n subsequent calls to rustls_connection_read_tls and\n rustls_connection_process_new_packets.\"\n\n Subtle note: Even though this function only writes to `buf` and does not\n read from it, the memory in `buf` must be initialized before the call (for\n Rust-internal reasons). Initializing a buffer once and then using it\n multiple times without zeroizing before each call is fine.\n ", + "feature": null, + "deprecation": null, + "name": "rustls_connection_read", + "text": "```c\nrustls_result rustls_connection_read(struct rustls_connection *conn,\n uint8_t *buf,\n size_t count,\n size_t *out_n);\n```" + }, + { + "anchor": "rustls-connection-read-2", + "comment": "Read up to `count` plaintext bytes from the [`rustls_connection`](#rustls-connection) into `buf`.\n On success, store the number of bytes read in *out_n (this may be less\n than `count`). A success with *out_n set to 0 means \"all bytes currently\n available have been read, but more bytes may become available after\n subsequent calls to rustls_connection_read_tls and\n rustls_connection_process_new_packets.\"\n\n This experimental API is only available when using a nightly Rust compiler\n and enabling the `read_buf` Cargo feature. It will be deprecated and later\n removed in future versions.\n\n Unlike with [`rustls_connection_read`](#rustls-connection-read), this function may be called with `buf`\n pointing to an uninitialized memory buffer.", + "feature": "read_buf", + "deprecation": null, + "name": "rustls_connection_read_2", + "text": "```c\nrustls_result rustls_connection_read_2(struct rustls_connection *conn,\n uint8_t *buf,\n size_t count,\n size_t *out_n);\n```" + }, + { + "anchor": "rustls-connection-fips", + "comment": "Returns true if the [`rustls_connection`](#rustls-connection) was made with a [`rustls_client_config`](#rustls-client-config)\n or [`rustls_server_config`](#rustls-server-config) that is FIPS compatible.\n\n This is different from [`rustls_crypto_provider_fips`](#rustls-crypto-provider-fips) which is concerned\n only with cryptography, whereas this also covers TLS-level configuration that NIST\n recommends, as well as ECH HPKE suites if applicable.", + "feature": null, + "deprecation": null, + "name": "rustls_connection_fips", + "text": "```c\nbool rustls_connection_fips(const struct rustls_connection *conn);\n```" + }, + { + "anchor": "rustls-connection-free", + "comment": "Free a rustls_connection. Calling with NULL is fine.\n Must not be called twice with the same value.", + "feature": null, + "deprecation": null, + "name": "rustls_connection_free", + "text": "```c\nvoid rustls_connection_free(struct rustls_connection *conn);\n```" + }, + { + "anchor": "rustls-crypto-provider-builder-new-from-default", + "comment": "Constructs a new [`rustls_crypto_provider_builder`](#rustls-crypto-provider-builder) using the process-wide default crypto\n provider as the base crypto provider to be customized.\n\n When this function returns `rustls_result::Ok` a pointer to the [`rustls_crypto_provider_builder`](#rustls-crypto-provider-builder)\n is written to `builder_out`. It returns `rustls_result::NoDefaultCryptoProvider` if no default\n provider has been registered.\n\n The caller owns the returned [`rustls_crypto_provider_builder`](#rustls-crypto-provider-builder) and must free it using\n [`rustls_crypto_provider_builder_free`](#rustls-crypto-provider-builder-free).\n\n This function is typically used for customizing the default crypto provider for specific\n connections. For example, a typical workflow might be to:\n\n * Either:\n * Use the default `aws-lc-rs` or `*ring*` provider that rustls-ffi is built with based on\n the `CRYPTO_PROVIDER` build variable.\n * Call [`rustls_crypto_provider_builder_new_with_base`](#rustls-crypto-provider-builder-new-with-base) with the desired provider, and\n then install it as the process default with\n [`rustls_crypto_provider_builder_build_as_default`](#rustls-crypto-provider-builder-build-as-default).\n * Afterward, as required for customization:\n * Use [`rustls_crypto_provider_builder_new_from_default`](#rustls-crypto-provider-builder-new-from-default) to get a builder backed by the\n default crypto provider.\n * Use [`rustls_crypto_provider_builder_set_cipher_suites`](#rustls-crypto-provider-builder-set-cipher-suites) to customize the supported\n ciphersuites.\n * Use [`rustls_crypto_provider_builder_build`](#rustls-crypto-provider-builder-build) to build a customized provider.\n * Provide that customized provider to client or server configuration builders.", + "feature": null, + "deprecation": null, + "name": "rustls_crypto_provider_builder_new_from_default", + "text": "```c\nrustls_result rustls_crypto_provider_builder_new_from_default(struct rustls_crypto_provider_builder **builder_out);\n```" + }, + { + "anchor": "rustls-crypto-provider-builder-new-with-base", + "comment": "Constructs a new [`rustls_crypto_provider_builder`](#rustls-crypto-provider-builder) using the given [`rustls_crypto_provider`](#rustls-crypto-provider)\n as the base crypto provider to be customized.\n\n The caller owns the returned [`rustls_crypto_provider_builder`](#rustls-crypto-provider-builder) and must free it using\n [`rustls_crypto_provider_builder_free`](#rustls-crypto-provider-builder-free).\n\n This function can be used for setting the default process wide crypto provider,\n or for constructing a custom crypto provider for a specific connection. A typical\n workflow could be to:\n\n * Call [`rustls_crypto_provider_builder_new_with_base`](#rustls-crypto-provider-builder-new-with-base) with a custom provider\n * Install the custom provider as the process-wide default with\n [`rustls_crypto_provider_builder_build_as_default`](#rustls-crypto-provider-builder-build-as-default).\n\n Or, for per-connection customization:\n\n * Call [`rustls_crypto_provider_builder_new_with_base`](#rustls-crypto-provider-builder-new-with-base) with a custom provider\n * Use [`rustls_crypto_provider_builder_set_cipher_suites`](#rustls-crypto-provider-builder-set-cipher-suites) to customize the supported\n ciphersuites.\n * Use [`rustls_crypto_provider_builder_build`](#rustls-crypto-provider-builder-build) to build a customized provider.\n * Provide that customized provider to client or server configuration builders.", + "feature": null, + "deprecation": null, + "name": "rustls_crypto_provider_builder_new_with_base", + "text": "```c\nstruct rustls_crypto_provider_builder *rustls_crypto_provider_builder_new_with_base(const struct rustls_crypto_provider *base);\n```" + }, + { + "anchor": "rustls-crypto-provider-builder-set-cipher-suites", + "comment": "Customize the supported ciphersuites of the [`rustls_crypto_provider_builder`](#rustls-crypto-provider-builder).\n\n Returns an error if the builder has already been built. Overwrites any previously\n set ciphersuites.", + "feature": null, + "deprecation": null, + "name": "rustls_crypto_provider_builder_set_cipher_suites", + "text": "```c\nrustls_result rustls_crypto_provider_builder_set_cipher_suites(struct rustls_crypto_provider_builder *builder,\n const struct rustls_supported_ciphersuite *const *cipher_suites,\n size_t cipher_suites_len);\n```" + }, + { + "anchor": "rustls-crypto-provider-builder-build", + "comment": "Builds a [`rustls_crypto_provider`](#rustls-crypto-provider) from the builder and returns it. Returns an error if the\n builder has already been built.\n\n The [`rustls_crypto_provider_builder`](#rustls-crypto-provider-builder) builder is consumed and should not be used\n for further calls, except to [`rustls_crypto_provider_builder_free`](#rustls-crypto-provider-builder-free). The caller must\n still free the builder after a successful build.", + "feature": null, + "deprecation": null, + "name": "rustls_crypto_provider_builder_build", + "text": "```c\nrustls_result rustls_crypto_provider_builder_build(struct rustls_crypto_provider_builder *builder,\n const struct rustls_crypto_provider **provider_out);\n```" + }, + { + "anchor": "rustls-crypto-provider-builder-build-as-default", + "comment": "Builds a [`rustls_crypto_provider`](#rustls-crypto-provider) from the builder and sets it as the\n process-wide default crypto provider.\n\n Afterward, the default provider can be retrieved using [`rustls_crypto_provider_default`](#rustls-crypto-provider-default).\n\n This can only be done once per process, and will return an error if a\n default provider has already been set, or if the builder has already been built.\n\n The [`rustls_crypto_provider_builder`](#rustls-crypto-provider-builder) builder is consumed and should not be used\n for further calls, except to [`rustls_crypto_provider_builder_free`](#rustls-crypto-provider-builder-free). The caller must\n still free the builder after a successful build.", + "feature": null, + "deprecation": null, + "name": "rustls_crypto_provider_builder_build_as_default", + "text": "```c\nrustls_result rustls_crypto_provider_builder_build_as_default(struct rustls_crypto_provider_builder *builder);\n```" + }, + { + "anchor": "rustls-crypto-provider-builder-free", + "comment": "Free the [`rustls_crypto_provider_builder`](#rustls-crypto-provider-builder).\n\n Calling with `NULL` is fine.\n Must not be called twice with the same value.", + "feature": null, + "deprecation": null, + "name": "rustls_crypto_provider_builder_free", + "text": "```c\nvoid rustls_crypto_provider_builder_free(struct rustls_crypto_provider_builder *builder);\n```" + }, + { + "anchor": "rustls-ring-crypto-provider", + "comment": "Return the [`rustls_crypto_provider`](#rustls-crypto-provider) backed by the `*ring*` cryptography library.\n\n The caller owns the returned [`rustls_crypto_provider`](#rustls-crypto-provider) and must free it using\n [`rustls_crypto_provider_free`](#rustls-crypto-provider-free).", + "feature": "ring", + "deprecation": null, + "name": "rustls_ring_crypto_provider", + "text": "```c\nconst struct rustls_crypto_provider *rustls_ring_crypto_provider(void);\n```" + }, + { + "anchor": "rustls-aws-lc-rs-crypto-provider", + "comment": "Return the [`rustls_crypto_provider`](#rustls-crypto-provider) backed by the `aws-lc-rs` cryptography library.\n\n The caller owns the returned [`rustls_crypto_provider`](#rustls-crypto-provider) and must free it using\n [`rustls_crypto_provider_free`](#rustls-crypto-provider-free).", + "feature": "aws_lc_rs", + "deprecation": null, + "name": "rustls_aws_lc_rs_crypto_provider", + "text": "```c\nconst struct rustls_crypto_provider *rustls_aws_lc_rs_crypto_provider(void);\n```" + }, + { + "anchor": "rustls-default-fips-provider", + "comment": "Return a [`rustls_crypto_provider`](#rustls-crypto-provider) that uses FIPS140-3 approved cryptography.\n\n Using this function expresses in your code that you require FIPS-approved cryptography,\n and will not compile if you make a mistake with cargo features.\n\n See the upstream [rustls FIPS documentation][FIPS] for more information.\n\n The caller owns the returned [`rustls_crypto_provider`](#rustls-crypto-provider) and must free it using\n [`rustls_crypto_provider_free`](#rustls-crypto-provider-free).\n\n [FIPS]: https://docs.rs/rustls/latest/rustls/manual/_06_fips/index.html", + "feature": "fips", + "deprecation": null, + "name": "rustls_default_fips_provider", + "text": "```c\nconst struct rustls_crypto_provider *rustls_default_fips_provider(void);\n```" + }, + { + "anchor": "rustls-crypto-provider-default", + "comment": "Retrieve a pointer to the process default [`rustls_crypto_provider`](#rustls-crypto-provider).\n\n This may return `NULL` if no process default provider has been set using\n `rustls_crypto_provider_builder_build_default`.\n\n Caller owns the returned [`rustls_crypto_provider`](#rustls-crypto-provider) and must free it w/ [`rustls_crypto_provider_free`](#rustls-crypto-provider-free).", + "feature": null, + "deprecation": null, + "name": "rustls_crypto_provider_default", + "text": "```c\nconst struct rustls_crypto_provider *rustls_crypto_provider_default(void);\n```" + }, + { + "anchor": "rustls-crypto-provider-ciphersuites-len", + "comment": "Returns the number of ciphersuites the [`rustls_crypto_provider`](#rustls-crypto-provider) supports.\n\n You can use this to know the maximum allowed index for use with\n [`rustls_crypto_provider_ciphersuites_get`](#rustls-crypto-provider-ciphersuites-get).\n\n This function will return 0 if the `provider` is NULL.", + "feature": null, + "deprecation": null, + "name": "rustls_crypto_provider_ciphersuites_len", + "text": "```c\nsize_t rustls_crypto_provider_ciphersuites_len(const struct rustls_crypto_provider *provider);\n```" + }, + { + "anchor": "rustls-crypto-provider-ciphersuites-get", + "comment": "Retrieve a pointer to a supported ciphersuite of the [`rustls_crypto_provider`](#rustls-crypto-provider).\n\n This function will return NULL if the `provider` is NULL, or if the index is out of bounds\n with respect to [`rustls_crypto_provider_ciphersuites_len`](#rustls-crypto-provider-ciphersuites-len).\n\n The lifetime of the returned [`rustls_supported_ciphersuite`](#rustls-supported-ciphersuite) is equal to the lifetime of the\n `provider` and should not be used after the `provider` is freed.", + "feature": null, + "deprecation": null, + "name": "rustls_crypto_provider_ciphersuites_get", + "text": "```c\nconst struct rustls_supported_ciphersuite *rustls_crypto_provider_ciphersuites_get(const struct rustls_crypto_provider *provider,\n size_t index);\n```" + }, + { + "anchor": "rustls-crypto-provider-load-key", + "comment": "Load a private key from the provided PEM content using the crypto provider.\n\n `private_key` must point to a buffer of `private_key_len` bytes, containing\n a PEM-encoded private key. The exact formats supported will differ based on\n the crypto provider in use. The default providers support PKCS#1, PKCS#8 or\n SEC1 formats.\n\n When this function returns `rustls_result::Ok` a pointer to a [`rustls_signing_key`](#rustls-signing-key)\n is written to `signing_key_out`. The caller owns the returned [`rustls_signing_key`](#rustls-signing-key)\n and must free it with [`rustls_signing_key_free`](#rustls-signing-key-free).", + "feature": null, + "deprecation": null, + "name": "rustls_crypto_provider_load_key", + "text": "```c\nrustls_result rustls_crypto_provider_load_key(const struct rustls_crypto_provider *provider,\n const uint8_t *private_key,\n size_t private_key_len,\n struct rustls_signing_key **signing_key_out);\n```" + }, + { + "anchor": "rustls-crypto-provider-random", + "comment": "Write `len` bytes of cryptographically secure random data to `buff` using the crypto provider.\n\n `buff` must point to a buffer of at least `len` bytes. The caller maintains ownership\n of the buffer.\n\n Returns `RUSTLS_RESULT_OK` on success, or `RUSTLS_RESULT_GET_RANDOM_FAILED` on failure.", + "feature": null, + "deprecation": null, + "name": "rustls_crypto_provider_random", + "text": "```c\nrustls_result rustls_crypto_provider_random(const struct rustls_crypto_provider *provider,\n uint8_t *buff,\n size_t len);\n```" + }, + { + "anchor": "rustls-crypto-provider-fips", + "comment": "Returns true if the [`rustls_crypto_provider`](#rustls-crypto-provider) is operating in FIPS mode.\n\n This covers only the cryptographic parts of FIPS approval. There are also\n TLS protocol-level recommendations made by NIST. You should prefer to call\n [`rustls_client_config_fips`](#rustls-client-config-fips) or [`rustls_server_config_fips`](#rustls-server-config-fips) which take these\n into account.", + "feature": null, + "deprecation": null, + "name": "rustls_crypto_provider_fips", + "text": "```c\nbool rustls_crypto_provider_fips(const struct rustls_crypto_provider *provider);\n```" + }, + { + "anchor": "rustls-crypto-provider-free", + "comment": "Frees the [`rustls_crypto_provider`](#rustls-crypto-provider).\n\n Calling with `NULL` is fine.\n Must not be called twice with the same value.", + "feature": null, + "deprecation": null, + "name": "rustls_crypto_provider_free", + "text": "```c\nvoid rustls_crypto_provider_free(const struct rustls_crypto_provider *provider);\n```" + }, + { + "anchor": "rustls-default-crypto-provider-ciphersuites-len", + "comment": "Returns the number of ciphersuites the default process-wide crypto provider supports.\n\n You can use this to know the maximum allowed index for use with\n [`rustls_default_crypto_provider_ciphersuites_get`](#rustls-default-crypto-provider-ciphersuites-get).\n\n This function will return 0 if no process-wide default [`rustls_crypto_provider`](#rustls-crypto-provider) is available.", + "feature": null, + "deprecation": null, + "name": "rustls_default_crypto_provider_ciphersuites_len", + "text": "```c\nsize_t rustls_default_crypto_provider_ciphersuites_len(void);\n```" + }, + { + "anchor": "rustls-default-crypto-provider-ciphersuites-get", + "comment": "Retrieve a pointer to a supported ciphersuite of the default process-wide crypto provider.\n\n This function will return NULL if the `provider` is NULL, or if the index is out of bounds\n with respect to [`rustls_default_crypto_provider_ciphersuites_len`](#rustls-default-crypto-provider-ciphersuites-len).\n\n The lifetime of the returned [`rustls_supported_ciphersuite`](#rustls-supported-ciphersuite) is static, as the process-wide\n default provider lives for as long as the process.", + "feature": null, + "deprecation": null, + "name": "rustls_default_crypto_provider_ciphersuites_get", + "text": "```c\nconst struct rustls_supported_ciphersuite *rustls_default_crypto_provider_ciphersuites_get(size_t index);\n```" + }, + { + "anchor": "rustls-default-crypto-provider-random", + "comment": "Write `len` bytes of cryptographically secure random data to `buff` using the process-wide\n default crypto provider.\n\n `buff` must point to a buffer of at least `len` bytes. The caller maintains ownership\n of the buffer.\n\n Returns `RUSTLS_RESULT_OK` on success, and one of `RUSTLS_RESULT_NO_DEFAULT_CRYPTO_PROVIDER`\n or `RUSTLS_RESULT_GET_RANDOM_FAILED` on failure.", + "feature": null, + "deprecation": null, + "name": "rustls_default_crypto_provider_random", + "text": "```c\nrustls_result rustls_default_crypto_provider_random(uint8_t *buff, size_t len);\n```" + }, + { + "anchor": "rustls-signing-key-free", + "comment": "Frees the [`rustls_signing_key`](#rustls-signing-key). This is safe to call with a `NULL` argument, but\n must not be called twice with the same value.", + "feature": null, + "deprecation": null, + "name": "rustls_signing_key_free", + "text": "```c\nvoid rustls_signing_key_free(struct rustls_signing_key *signing_key);\n```" + }, + { + "anchor": "rustls-supported-hpke", + "comment": "Returns a pointer to the supported [`rustls_hpke`](#rustls-hpke) Hybrid Public Key Encryption (HPKE)\n suites, or `NULL` if HPKE is not supported.\n\n HPKE is only supported with the `aws-lc-rs` cryptography provider.\n\n The returned pointer has a static lifetime equal to that of the program and does not\n need to be freed.", + "feature": null, + "deprecation": null, + "name": "rustls_supported_hpke", + "text": "```c\nconst struct rustls_hpke *rustls_supported_hpke(void);\n```" + }, + { + "anchor": "rustls-handshake-kind-str", + "comment": "Convert a [`rustls_handshake_kind`](#rustls-handshake-kind) to a string with a friendly description of the kind\n of handshake.\n\n The returned [`rustls_str`](#rustls-str) has a static lifetime equal to that of the program and does\n not need to be manually freed.", + "feature": null, + "deprecation": null, + "name": "rustls_handshake_kind_str", + "text": "```c\nstruct rustls_str rustls_handshake_kind_str(enum rustls_handshake_kind kind);\n```" + }, + { + "anchor": "rustls-error", + "comment": "After a rustls function returns an error, you may call\n this to get a pointer to a buffer containing a detailed error\n message.\n\n The contents of the error buffer will be out_n bytes long,\n UTF-8 encoded, and not NUL-terminated.", + "feature": null, + "deprecation": null, + "name": "rustls_error", + "text": "```c\nvoid rustls_error(unsigned int result, char *buf, size_t len, size_t *out_n);\n```" + }, + { + "anchor": "rustls-result-is-cert-error", + "comment": "Returns true if the `result` is a certificate related error.", + "feature": null, + "deprecation": null, + "name": "rustls_result_is_cert_error", + "text": "```c\nbool rustls_result_is_cert_error(unsigned int result);\n```" + }, + { + "anchor": "rustls-log-level-str", + "comment": "Return a rustls_str containing the stringified version of a log level.", + "feature": null, + "deprecation": null, + "name": "rustls_log_level_str", + "text": "```c\nstruct rustls_str rustls_log_level_str(rustls_log_level level);\n```" + }, + { + "anchor": "rustls-slice-slice-bytes-len", + "comment": "Return the length of the outer slice. If the input pointer is NULL,\n returns 0.", + "feature": null, + "deprecation": null, + "name": "rustls_slice_slice_bytes_len", + "text": "```c\nsize_t rustls_slice_slice_bytes_len(const struct rustls_slice_slice_bytes *input);\n```" + }, + { + "anchor": "rustls-slice-slice-bytes-get", + "comment": "Retrieve the nth element from the input slice of slices.\n\n If the input pointer is NULL, or n is greater than the length\n of the [`rustls_slice_slice_bytes`](#rustls-slice-slice-bytes), returns rustls_slice_bytes{NULL, 0}.", + "feature": null, + "deprecation": null, + "name": "rustls_slice_slice_bytes_get", + "text": "```c\nstruct rustls_slice_bytes rustls_slice_slice_bytes_get(const struct rustls_slice_slice_bytes *input,\n size_t n);\n```" + }, + { + "anchor": "rustls-slice-str-len", + "comment": "Return the length of the outer slice.\n\n If the input pointer is NULL, returns 0.", + "feature": null, + "deprecation": null, + "name": "rustls_slice_str_len", + "text": "```c\nsize_t rustls_slice_str_len(const struct rustls_slice_str *input);\n```" + }, + { + "anchor": "rustls-slice-str-get", + "comment": "Retrieve the nth element from the input slice of `&str`s.\n\n If the input pointer is NULL, or n is greater than the length of the\n rustls_slice_str, returns rustls_str{NULL, 0}.", + "feature": null, + "deprecation": null, + "name": "rustls_slice_str_get", + "text": "```c\nstruct rustls_str rustls_slice_str_get(const struct rustls_slice_str *input, size_t n);\n```" + }, + { + "anchor": "rustls-server-config-builder-new", + "comment": "Create a rustls_server_config_builder using the process default crypto provider.\n\n Caller owns the memory and must eventually call rustls_server_config_builder_build,\n then free the resulting rustls_server_config.\n\n Alternatively, if an error occurs or, you don't wish to build a config, call\n [`rustls_server_config_builder_free`](#rustls-server-config-builder-free) to free the builder directly.\n\n This uses the process default provider's values for the cipher suites and key exchange\n groups, as well as safe defaults for protocol versions.", + "feature": null, + "deprecation": null, + "name": "rustls_server_config_builder_new", + "text": "```c\nstruct rustls_server_config_builder *rustls_server_config_builder_new(void);\n```" + }, + { + "anchor": "rustls-server-config-builder-new-custom", + "comment": "Create a rustls_server_config_builder using the specified crypto provider.\n\n Caller owns the memory and must eventually call rustls_server_config_builder_build,\n then free the resulting rustls_server_config.\n\n Alternatively, if an error occurs or, you don't wish to build a config, call\n [`rustls_server_config_builder_free`](#rustls-server-config-builder-free) to free the builder directly.\n\n `tls_versions` set the TLS protocol versions to use when negotiating a TLS session.\n\n `tls_versions` is the version of the protocol, as defined in rfc8446,\n ch. 4.2.1 and end of ch. 5.1. Some values are defined in\n [`rustls_tls_version`](#rustls-tls-version) for convenience.\n\n `tls_versions` will only be used during the call and the application retains\n ownership. `tls_versions_len` is the number of consecutive `uint16_t` pointed\n to by `tls_versions`.\n\n Ciphersuites are configured separately via the crypto provider. See\n [`rustls_crypto_provider_builder_set_cipher_suites`](#rustls-crypto-provider-builder-set-cipher-suites) for more information.", + "feature": null, + "deprecation": null, + "name": "rustls_server_config_builder_new_custom", + "text": "```c\nrustls_result rustls_server_config_builder_new_custom(const struct rustls_crypto_provider *provider,\n const uint16_t *tls_versions,\n size_t tls_versions_len,\n struct rustls_server_config_builder **builder_out);\n```" + }, + { + "anchor": "rustls-server-config-builder-set-client-verifier", + "comment": "Create a rustls_server_config_builder for TLS sessions that may verify client\n certificates.\n\n This increases the refcount of `verifier` and doesn't take ownership.", + "feature": null, + "deprecation": null, + "name": "rustls_server_config_builder_set_client_verifier", + "text": "```c\nvoid rustls_server_config_builder_set_client_verifier(struct rustls_server_config_builder *builder,\n const struct rustls_client_cert_verifier *verifier);\n```" + }, + { + "anchor": "rustls-server-config-builder-set-key-log-file", + "comment": "Log key material to the file specified by the `SSLKEYLOGFILE` environment variable.\n\n The key material will be logged in the NSS key log format,\n and is\n compatible with tools like Wireshark.\n\n Secrets logged in this manner are **extremely sensitive** and can break the security\n of past, present and future sessions.\n\n For more control over which secrets are logged, or to customize the format, prefer\n [`rustls_server_config_builder_set_key_log`](#rustls-server-config-builder-set-key-log).", + "feature": null, + "deprecation": null, + "name": "rustls_server_config_builder_set_key_log_file", + "text": "```c\nrustls_result rustls_server_config_builder_set_key_log_file(struct rustls_server_config_builder *builder);\n```" + }, + { + "anchor": "rustls-server-config-builder-set-key-log", + "comment": "Provide callbacks to manage logging key material.\n\n The `log_cb` argument is mandatory and must not be `NULL` or a `NullParameter` error is\n returned. The `log_cb` will be invoked with a `client_random` to identify the relevant session,\n a `label` to identify the purpose of the `secret`, and the `secret` itself. See the\n Rustls documentation of the `KeyLog` trait for more information on possible labels:\n \n\n The `will_log_cb` may be `NULL`, in which case all key material will be provided to\n the `log_cb`. By providing a custom `will_log_cb` you may return `0` for labels you don't\n wish to log, and non-zero for labels you _do_ wish to log as a performance optimization.\n\n Both callbacks **must** be thread-safe. Arguments provided to the callback live only for as\n long as the callback is executing and are not valid after the callback returns. The\n callbacks must not retain references to the provided data.\n\n Secrets provided to the `log_cb` are **extremely sensitive** and can break the security\n of past, present and future sessions.\n\n See also [`rustls_server_config_builder_set_key_log_file`](#rustls-server-config-builder-set-key-log-file) for a simpler way to log\n to a file specified by the `SSLKEYLOGFILE` environment variable.", + "feature": null, + "deprecation": null, + "name": "rustls_server_config_builder_set_key_log", + "text": "```c\nrustls_result rustls_server_config_builder_set_key_log(struct rustls_server_config_builder *builder,\n rustls_keylog_log_callback log_cb,\n rustls_keylog_will_log_callback will_log_cb);\n```" + }, + { + "anchor": "rustls-server-config-builder-free", + "comment": "\"Free\" a server_config_builder without building it into a rustls_server_config.\n\n Normally builders are built into rustls_server_configs via [`rustls_server_config_builder_build`](#rustls-server-config-builder-build)\n and may not be free'd or otherwise used afterwards.\n\n Use free only when the building of a config has to be aborted before a config\n was created.", + "feature": null, + "deprecation": null, + "name": "rustls_server_config_builder_free", + "text": "```c\nvoid rustls_server_config_builder_free(struct rustls_server_config_builder *config);\n```" + }, + { + "anchor": "rustls-server-config-builder-set-ignore-client-order", + "comment": "With `ignore` != 0, the server will ignore the client ordering of cipher\n suites, aka preference, during handshake and respect its own ordering\n as configured.\n ", + "feature": null, + "deprecation": null, + "name": "rustls_server_config_builder_set_ignore_client_order", + "text": "```c\nrustls_result rustls_server_config_builder_set_ignore_client_order(struct rustls_server_config_builder *builder,\n bool ignore);\n```" + }, + { + "anchor": "rustls-server-config-builder-set-alpn-protocols", + "comment": "Set the ALPN protocol list to the given protocols.\n\n `protocols` must point to a buffer of [`rustls_slice_bytes`](#rustls-slice-bytes) (built by the caller)\n with `len` elements. Each element of the buffer must point to a slice of bytes that\n contains a single ALPN protocol from\n .\n\n This function makes a copy of the data in `protocols` and does not retain\n any pointers, so the caller can free the pointed-to memory after calling.\n\n ", + "feature": null, + "deprecation": null, + "name": "rustls_server_config_builder_set_alpn_protocols", + "text": "```c\nrustls_result rustls_server_config_builder_set_alpn_protocols(struct rustls_server_config_builder *builder,\n const struct rustls_slice_bytes *protocols,\n size_t len);\n```" + }, + { + "anchor": "rustls-server-config-builder-set-certified-keys", + "comment": "Provide the configuration a list of certificates where the connection\n will select the first one that is compatible with the client's signature\n verification capabilities.\n\n Servers that want to support both ECDSA and RSA certificates will want\n the ECSDA to go first in the list.\n\n The built configuration will keep a reference to all certified keys\n provided. The client may [`rustls_certified_key_free()`](#rustls-certified-key-free) afterwards\n without the configuration losing them. The same certified key may also\n be used in multiple configs.\n\n EXPERIMENTAL: installing a client_hello callback will replace any\n configured certified keys and vice versa.", + "feature": null, + "deprecation": null, + "name": "rustls_server_config_builder_set_certified_keys", + "text": "```c\nrustls_result rustls_server_config_builder_set_certified_keys(struct rustls_server_config_builder *builder,\n const struct rustls_certified_key *const *certified_keys,\n size_t certified_keys_len);\n```" + }, + { + "anchor": "rustls-server-config-builder-build", + "comment": "Turn a *rustls_server_config_builder (mutable) into a const *rustls_server_config\n (read-only). The constructed [`rustls_server_config`](#rustls-server-config) will be written to the `config_out`\n pointer when this function returns `rustls_result::Ok`.\n\n This function may return an error if no process default crypto provider has been set\n and the builder was constructed using [`rustls_server_config_builder_new`](#rustls-server-config-builder-new), or if no\n certificate resolver was set.", + "feature": null, + "deprecation": null, + "name": "rustls_server_config_builder_build", + "text": "```c\nrustls_result rustls_server_config_builder_build(struct rustls_server_config_builder *builder,\n const struct rustls_server_config **config_out);\n```" + }, + { + "anchor": "rustls-server-config-fips", + "comment": "Returns true if a [`rustls_connection`](#rustls-connection) created from the [`rustls_server_config`](#rustls-server-config) will\n operate in FIPS mode.\n\n This is different from [`rustls_crypto_provider_fips`](#rustls-crypto-provider-fips) which is concerned\n only with cryptography, whereas this also covers TLS-level configuration that NIST\n recommends, as well as ECH HPKE suites if applicable.", + "feature": null, + "deprecation": null, + "name": "rustls_server_config_fips", + "text": "```c\nbool rustls_server_config_fips(const struct rustls_server_config *config);\n```" + }, + { + "anchor": "rustls-server-config-free", + "comment": "\"Free\" a rustls_server_config previously returned from\n rustls_server_config_builder_build.\n\n Since rustls_server_config is actually an\n atomically reference-counted pointer, extant server connections may still\n hold an internal reference to the Rust object. However, C code must\n consider this pointer unusable after \"free\"ing it.\n Calling with NULL is fine. Must not be called twice with the same value.", + "feature": null, + "deprecation": null, + "name": "rustls_server_config_free", + "text": "```c\nvoid rustls_server_config_free(const struct rustls_server_config *config);\n```" + }, + { + "anchor": "rustls-server-connection-new", + "comment": "Create a new rustls_connection containing a server connection, and return it.\n\n It is returned in the output parameter `conn_out`.\n\n If this returns an error code, the memory pointed to by `conn_out` remains unchanged.\n\n If this returns a non-error, the memory pointed to by `conn_out` is modified to point\n at a valid rustls_connection\n\n The caller now owns the rustls_connection and must call [`rustls_connection_free`](#rustls-connection-free) when\n done with it.", + "feature": null, + "deprecation": null, + "name": "rustls_server_connection_new", + "text": "```c\nrustls_result rustls_server_connection_new(const struct rustls_server_config *config,\n struct rustls_connection **conn_out);\n```" + }, + { + "anchor": "rustls-server-connection-get-server-name", + "comment": "Returns a [`rustls_str`](#rustls-str) reference to the server name sent by the client in a server name\n indication (SNI) extension.\n\n The returned [`rustls_str`](#rustls-str) is valid until the next mutating function call affecting the\n connection. A mutating function call is one where the first argument has type\n `struct rustls_connection *` (as opposed to `const struct rustls_connection *`). The caller\n does not need to free the [`rustls_str`](#rustls-str).\n\n Returns a zero-length [`rustls_str`](#rustls-str) if:\n\n - the connection is not a server connection.\n - the connection is a server connection but the SNI extension in the client hello has not\n been processed during the handshake yet. Check [`rustls_connection_is_handshaking`](#rustls-connection-is-handshaking).\n - the SNI value contains null bytes.", + "feature": null, + "deprecation": null, + "name": "rustls_server_connection_get_server_name", + "text": "```c\nstruct rustls_str rustls_server_connection_get_server_name(const struct rustls_connection *conn);\n```" + }, + { + "anchor": "rustls-server-config-builder-set-hello-callback", + "comment": "Register a callback to be invoked when a connection created from this config\n sees a TLS ClientHello message. If `userdata` has been set with\n rustls_connection_set_userdata, it will be passed to the callback.\n Otherwise the userdata param passed to the callback will be NULL.\n\n Any existing `ResolvesServerCert` implementation currently installed in the\n [`rustls_server_config`](#rustls-server-config) will be replaced. This also means registering twice\n will overwrite the first registration. It is not permitted to pass a NULL\n value for `callback`.\n\n EXPERIMENTAL: this feature of rustls-ffi is likely to change in the future, as\n the rustls library is re-evaluating their current approach to client hello handling.\n Installing a client_hello callback will replace any configured certified keys\n and vice versa. Same holds true for the set_certified_keys variant.", + "feature": null, + "deprecation": null, + "name": "rustls_server_config_builder_set_hello_callback", + "text": "```c\nrustls_result rustls_server_config_builder_set_hello_callback(struct rustls_server_config_builder *builder,\n rustls_client_hello_callback callback);\n```" + }, + { + "anchor": "rustls-client-hello-select-certified-key", + "comment": "Select a [`rustls_certified_key`](#rustls-certified-key) from the list that matches the cryptographic\n parameters of a TLS client hello.\n\n Note that this does not do any SNI matching. The input certificates should\n already have been filtered to ones matching the SNI from the client hello.\n\n This is intended for servers that are configured with several keys for the\n same domain name(s), for example ECDSA and RSA types. The presented keys are\n inspected in the order given and keys first in the list are given preference,\n all else being equal. However rustls is free to choose whichever it considers\n to be the best key with its knowledge about security issues and possible future\n extensions of the protocol.\n\n Return RUSTLS_RESULT_OK if a key was selected and RUSTLS_RESULT_NOT_FOUND\n if none was suitable.", + "feature": null, + "deprecation": null, + "name": "rustls_client_hello_select_certified_key", + "text": "```c\nrustls_result rustls_client_hello_select_certified_key(const struct rustls_client_hello *hello,\n const struct rustls_certified_key *const *certified_keys,\n size_t certified_keys_len,\n const struct rustls_certified_key **out_key);\n```" + }, + { + "anchor": "rustls-server-config-builder-set-persistence", + "comment": "Register callbacks for persistence of TLS session IDs and secrets. Both\n keys and values are highly sensitive data, containing enough information\n to break the security of the connections involved.\n\n If `builder`, `get_cb`, or `put_cb` are NULL, this function will return\n immediately without doing anything.\n\n If `userdata` has been set with rustls_connection_set_userdata, it\n will be passed to the callbacks. Otherwise the userdata param passed to\n the callbacks will be NULL.", + "feature": null, + "deprecation": null, + "name": "rustls_server_config_builder_set_persistence", + "text": "```c\nvoid rustls_server_config_builder_set_persistence(struct rustls_server_config_builder *builder,\n rustls_session_store_get_callback get_cb,\n rustls_session_store_put_callback put_cb);\n```" + }, + { + "anchor": "rustls-client-cert-verifier-free", + "comment": "Free a [`rustls_client_cert_verifier`](#rustls-client-cert-verifier) previously returned from\n `rustls_client_cert_verifier_builder_build`. Calling with NULL is fine. Must not be\n called twice with the same value.", + "feature": null, + "deprecation": null, + "name": "rustls_client_cert_verifier_free", + "text": "```c\nvoid rustls_client_cert_verifier_free(struct rustls_client_cert_verifier *verifier);\n```" + }, + { + "anchor": "rustls-web-pki-client-cert-verifier-builder-new", + "comment": "Create a [`rustls_web_pki_client_cert_verifier_builder`](#rustls-web-pki-client-cert-verifier-builder) using the process-wide default\n cryptography provider.\n\n Caller owns the memory and may eventually call [`rustls_web_pki_client_cert_verifier_builder_free`](#rustls-web-pki-client-cert-verifier-builder-free)\n to free it, whether or not [`rustls_web_pki_client_cert_verifier_builder_build`](#rustls-web-pki-client-cert-verifier-builder-build) was called.\n\n Without further modification the builder will produce a client certificate verifier that\n will require a client present a client certificate that chains to one of the trust anchors\n in the provided [`rustls_root_cert_store`](#rustls-root-cert-store). The root cert store must not be empty.\n\n Revocation checking will not be performed unless\n [`rustls_web_pki_client_cert_verifier_builder_add_crl`](#rustls-web-pki-client-cert-verifier-builder-add-crl) is used to add certificate revocation\n lists (CRLs) to the builder. If CRLs are added, revocation checking will be performed\n for the entire certificate chain unless\n [`rustls_web_pki_client_cert_verifier_only_check_end_entity_revocation`](#rustls-web-pki-client-cert-verifier-only-check-end-entity-revocation) is used. Unknown\n revocation status for certificates considered for revocation status will be treated as\n an error unless [`rustls_web_pki_client_cert_verifier_allow_unknown_revocation_status`](#rustls-web-pki-client-cert-verifier-allow-unknown-revocation-status) is\n used.\n\n Unauthenticated clients will not be permitted unless\n [`rustls_web_pki_client_cert_verifier_builder_allow_unauthenticated`](#rustls-web-pki-client-cert-verifier-builder-allow-unauthenticated) is used.\n\n This copies the contents of the [`rustls_root_cert_store`](#rustls-root-cert-store). It does not take\n ownership of the pointed-to data.", + "feature": null, + "deprecation": null, + "name": "rustls_web_pki_client_cert_verifier_builder_new", + "text": "```c\nstruct rustls_web_pki_client_cert_verifier_builder *rustls_web_pki_client_cert_verifier_builder_new(const struct rustls_root_cert_store *store);\n```" + }, + { + "anchor": "rustls-web-pki-client-cert-verifier-builder-new-with-provider", + "comment": "Create a [`rustls_web_pki_client_cert_verifier_builder`](#rustls-web-pki-client-cert-verifier-builder) using the specified\n cryptography provider.\n\n Caller owns the memory and may eventually call\n [`rustls_web_pki_client_cert_verifier_builder_free`](#rustls-web-pki-client-cert-verifier-builder-free) to free it, whether or\n not [`rustls_web_pki_client_cert_verifier_builder_build`](#rustls-web-pki-client-cert-verifier-builder-build) was called.\n\n Without further modification the builder will produce a client certificate verifier that\n will require a client present a client certificate that chains to one of the trust anchors\n in the provided [`rustls_root_cert_store`](#rustls-root-cert-store). The root cert store must not be empty.\n\n Revocation checking will not be performed unless\n [`rustls_web_pki_client_cert_verifier_builder_add_crl`](#rustls-web-pki-client-cert-verifier-builder-add-crl) is used to add certificate revocation\n lists (CRLs) to the builder. If CRLs are added, revocation checking will be performed\n for the entire certificate chain unless\n [`rustls_web_pki_client_cert_verifier_only_check_end_entity_revocation`](#rustls-web-pki-client-cert-verifier-only-check-end-entity-revocation) is used. Unknown\n revocation status for certificates considered for revocation status will be treated as\n an error unless [`rustls_web_pki_client_cert_verifier_allow_unknown_revocation_status`](#rustls-web-pki-client-cert-verifier-allow-unknown-revocation-status) is\n used.\n\n Unauthenticated clients will not be permitted unless\n [`rustls_web_pki_client_cert_verifier_builder_allow_unauthenticated`](#rustls-web-pki-client-cert-verifier-builder-allow-unauthenticated) is used.\n\n This copies the contents of the [`rustls_root_cert_store`](#rustls-root-cert-store). It does not take\n ownership of the pointed-to data.", + "feature": null, + "deprecation": null, + "name": "rustls_web_pki_client_cert_verifier_builder_new_with_provider", + "text": "```c\nstruct rustls_web_pki_client_cert_verifier_builder *rustls_web_pki_client_cert_verifier_builder_new_with_provider(const struct rustls_crypto_provider *provider,\n const struct rustls_root_cert_store *store);\n```" + }, + { + "anchor": "rustls-web-pki-client-cert-verifier-builder-add-crl", + "comment": "Add one or more certificate revocation lists (CRLs) to the client certificate verifier\n builder by reading the CRL content from the provided buffer of PEM encoded content.\n\n By default revocation checking will be performed on the entire certificate chain. To only\n check the revocation status of the end entity certificate, use\n [`rustls_web_pki_client_cert_verifier_only_check_end_entity_revocation`](#rustls-web-pki-client-cert-verifier-only-check-end-entity-revocation).\n\n This function returns an error if the provided buffer is not valid PEM encoded content.", + "feature": null, + "deprecation": null, + "name": "rustls_web_pki_client_cert_verifier_builder_add_crl", + "text": "```c\nrustls_result rustls_web_pki_client_cert_verifier_builder_add_crl(struct rustls_web_pki_client_cert_verifier_builder *builder,\n const uint8_t *crl_pem,\n size_t crl_pem_len);\n```" + }, + { + "anchor": "rustls-web-pki-client-cert-verifier-only-check-end-entity-revocation", + "comment": "When CRLs are provided with [`rustls_web_pki_client_cert_verifier_builder_add_crl`](#rustls-web-pki-client-cert-verifier-builder-add-crl), only\n check the revocation status of end entity certificates, ignoring any intermediate certificates\n in the chain.", + "feature": null, + "deprecation": null, + "name": "rustls_web_pki_client_cert_verifier_only_check_end_entity_revocation", + "text": "```c\nrustls_result rustls_web_pki_client_cert_verifier_only_check_end_entity_revocation(struct rustls_web_pki_client_cert_verifier_builder *builder);\n```" + }, + { + "anchor": "rustls-web-pki-client-cert-verifier-allow-unknown-revocation-status", + "comment": "When CRLs are provided with [`rustls_web_pki_client_cert_verifier_builder_add_crl`](#rustls-web-pki-client-cert-verifier-builder-add-crl), and it\n isn't possible to determine the revocation status of a considered certificate, do not treat\n it as an error condition.\n\n Overrides the default behavior where unknown revocation status is considered an error.", + "feature": null, + "deprecation": null, + "name": "rustls_web_pki_client_cert_verifier_allow_unknown_revocation_status", + "text": "```c\nrustls_result rustls_web_pki_client_cert_verifier_allow_unknown_revocation_status(struct rustls_web_pki_client_cert_verifier_builder *builder);\n```" + }, + { + "anchor": "rustls-web-pki-client-cert-verifier-builder-allow-unauthenticated", + "comment": "Allow unauthenticated anonymous clients in addition to those that present a client\n certificate that chains to one of the verifier's configured trust anchors.", + "feature": null, + "deprecation": null, + "name": "rustls_web_pki_client_cert_verifier_builder_allow_unauthenticated", + "text": "```c\nrustls_result rustls_web_pki_client_cert_verifier_builder_allow_unauthenticated(struct rustls_web_pki_client_cert_verifier_builder *builder);\n```" + }, + { + "anchor": "rustls-web-pki-client-cert-verifier-clear-root-hint-subjects", + "comment": "Clear the list of trust anchor hint subjects.\n\n By default, the client cert verifier will use the subjects provided by the root cert\n store configured for client authentication. Calling this function will remove these\n hint subjects, indicating the client should make a free choice of which certificate\n to send.", + "feature": null, + "deprecation": null, + "name": "rustls_web_pki_client_cert_verifier_clear_root_hint_subjects", + "text": "```c\nrustls_result rustls_web_pki_client_cert_verifier_clear_root_hint_subjects(struct rustls_web_pki_client_cert_verifier_builder *builder);\n```" + }, + { + "anchor": "rustls-web-pki-client-cert-verifier-add-root-hint-subjects", + "comment": "Add additional distinguished names to the list of trust anchor hint subjects.\n\n By default, the client cert verifier will use the subjects provided by the root cert\n store configured for client authentication. Calling this function will add to these\n existing hint subjects. Calling this function with an empty `store` will have no\n effect, use [`rustls_web_pki_client_cert_verifier_clear_root_hint_subjects`](#rustls-web-pki-client-cert-verifier-clear-root-hint-subjects) to clear\n the subject hints.", + "feature": null, + "deprecation": null, + "name": "rustls_web_pki_client_cert_verifier_add_root_hint_subjects", + "text": "```c\nrustls_result rustls_web_pki_client_cert_verifier_add_root_hint_subjects(struct rustls_web_pki_client_cert_verifier_builder *builder,\n const struct rustls_root_cert_store *store);\n```" + }, + { + "anchor": "rustls-web-pki-client-cert-verifier-builder-build", + "comment": "Create a new client certificate verifier from the builder.\n\n The builder is consumed and cannot be used again, but must still be freed.\n\n The verifier can be used in several [`rustls_server_config`](#rustls-server-config) instances and must be\n freed by the application when no longer needed. See the documentation of\n [`rustls_web_pki_client_cert_verifier_builder_free`](#rustls-web-pki-client-cert-verifier-builder-free) for details about lifetime.", + "feature": null, + "deprecation": null, + "name": "rustls_web_pki_client_cert_verifier_builder_build", + "text": "```c\nrustls_result rustls_web_pki_client_cert_verifier_builder_build(struct rustls_web_pki_client_cert_verifier_builder *builder,\n struct rustls_client_cert_verifier **verifier_out);\n```" + }, + { + "anchor": "rustls-web-pki-client-cert-verifier-builder-free", + "comment": "Free a `rustls_client_cert_verifier_builder` previously returned from\n `rustls_client_cert_verifier_builder_new`.\n\n Calling with NULL is fine. Must not be called twice with the same value.", + "feature": null, + "deprecation": null, + "name": "rustls_web_pki_client_cert_verifier_builder_free", + "text": "```c\nvoid rustls_web_pki_client_cert_verifier_builder_free(struct rustls_web_pki_client_cert_verifier_builder *builder);\n```" + }, + { + "anchor": "rustls-web-pki-server-cert-verifier-builder-new", + "comment": "Create a [`rustls_web_pki_server_cert_verifier_builder`](#rustls-web-pki-server-cert-verifier-builder) using the process-wide default\n crypto provider. Caller owns the memory and may free it with\n\n Caller owns the memory and may free it with [`rustls_web_pki_server_cert_verifier_builder_free`](#rustls-web-pki-server-cert-verifier-builder-free),\n regardless of whether [`rustls_web_pki_server_cert_verifier_builder_build`](#rustls-web-pki-server-cert-verifier-builder-build) was called.\n\n Without further modification the builder will produce a server certificate verifier that\n will require a server present a certificate that chains to one of the trust anchors\n in the provided [`rustls_root_cert_store`](#rustls-root-cert-store). The root cert store must not be empty.\n\n Revocation checking will not be performed unless\n [`rustls_web_pki_server_cert_verifier_builder_add_crl`](#rustls-web-pki-server-cert-verifier-builder-add-crl) is used to add certificate revocation\n lists (CRLs) to the builder. If CRLs are added, revocation checking will be performed\n for the entire certificate chain unless\n [`rustls_web_pki_server_cert_verifier_only_check_end_entity_revocation`](#rustls-web-pki-server-cert-verifier-only-check-end-entity-revocation) is used. Unknown\n revocation status for certificates considered for revocation status will be treated as\n an error unless [`rustls_web_pki_server_cert_verifier_allow_unknown_revocation_status`](#rustls-web-pki-server-cert-verifier-allow-unknown-revocation-status) is\n used.\n\n This copies the contents of the [`rustls_root_cert_store`](#rustls-root-cert-store). It does not take\n ownership of the pointed-to data.", + "feature": null, + "deprecation": null, + "name": "rustls_web_pki_server_cert_verifier_builder_new", + "text": "```c\nstruct rustls_web_pki_server_cert_verifier_builder *rustls_web_pki_server_cert_verifier_builder_new(const struct rustls_root_cert_store *store);\n```" + }, + { + "anchor": "rustls-web-pki-server-cert-verifier-builder-new-with-provider", + "comment": "Create a [`rustls_web_pki_server_cert_verifier_builder`](#rustls-web-pki-server-cert-verifier-builder) using the specified\n crypto provider. Caller owns the memory and may free it with\n [`rustls_web_pki_server_cert_verifier_builder_free`](#rustls-web-pki-server-cert-verifier-builder-free), regardless of whether\n [`rustls_web_pki_server_cert_verifier_builder_build`](#rustls-web-pki-server-cert-verifier-builder-build) was called.\n\n Without further modification the builder will produce a server certificate verifier that\n will require a server present a certificate that chains to one of the trust anchors\n in the provided [`rustls_root_cert_store`](#rustls-root-cert-store). The root cert store must not be empty.\n\n Revocation checking will not be performed unless\n [`rustls_web_pki_server_cert_verifier_builder_add_crl`](#rustls-web-pki-server-cert-verifier-builder-add-crl) is used to add certificate revocation\n lists (CRLs) to the builder. If CRLs are added, revocation checking will be performed\n for the entire certificate chain unless\n [`rustls_web_pki_server_cert_verifier_only_check_end_entity_revocation`](#rustls-web-pki-server-cert-verifier-only-check-end-entity-revocation) is used. Unknown\n revocation status for certificates considered for revocation status will be treated as\n an error unless [`rustls_web_pki_server_cert_verifier_allow_unknown_revocation_status`](#rustls-web-pki-server-cert-verifier-allow-unknown-revocation-status) is\n used. Expired CRLs will not be treated as an error unless\n [`rustls_web_pki_server_cert_verifier_enforce_revocation_expiry`](#rustls-web-pki-server-cert-verifier-enforce-revocation-expiry) is used.\n\n This copies the contents of the [`rustls_root_cert_store`](#rustls-root-cert-store). It does not take\n ownership of the pointed-to data.", + "feature": null, + "deprecation": null, + "name": "rustls_web_pki_server_cert_verifier_builder_new_with_provider", + "text": "```c\nstruct rustls_web_pki_server_cert_verifier_builder *rustls_web_pki_server_cert_verifier_builder_new_with_provider(const struct rustls_crypto_provider *provider,\n const struct rustls_root_cert_store *store);\n```" + }, + { + "anchor": "rustls-web-pki-server-cert-verifier-builder-add-crl", + "comment": "Add one or more certificate revocation lists (CRLs) to the server certificate verifier\n builder by reading the CRL content from the provided buffer of PEM encoded content.\n\n By default revocation checking will be performed on the entire certificate chain. To only\n check the revocation status of the end entity certificate, use\n [`rustls_web_pki_server_cert_verifier_only_check_end_entity_revocation`](#rustls-web-pki-server-cert-verifier-only-check-end-entity-revocation).\n\n This function returns an error if the provided buffer is not valid PEM encoded content.", + "feature": null, + "deprecation": null, + "name": "rustls_web_pki_server_cert_verifier_builder_add_crl", + "text": "```c\nrustls_result rustls_web_pki_server_cert_verifier_builder_add_crl(struct rustls_web_pki_server_cert_verifier_builder *builder,\n const uint8_t *crl_pem,\n size_t crl_pem_len);\n```" + }, + { + "anchor": "rustls-web-pki-server-cert-verifier-only-check-end-entity-revocation", + "comment": "When CRLs are provided with [`rustls_web_pki_server_cert_verifier_builder_add_crl`](#rustls-web-pki-server-cert-verifier-builder-add-crl), only\n check the revocation status of end entity certificates, ignoring any intermediate certificates\n in the chain.", + "feature": null, + "deprecation": null, + "name": "rustls_web_pki_server_cert_verifier_only_check_end_entity_revocation", + "text": "```c\nrustls_result rustls_web_pki_server_cert_verifier_only_check_end_entity_revocation(struct rustls_web_pki_server_cert_verifier_builder *builder);\n```" + }, + { + "anchor": "rustls-web-pki-server-cert-verifier-allow-unknown-revocation-status", + "comment": "When CRLs are provided with [`rustls_web_pki_server_cert_verifier_builder_add_crl`](#rustls-web-pki-server-cert-verifier-builder-add-crl), and it\n isn't possible to determine the revocation status of a considered certificate, do not treat\n it as an error condition.\n\n Overrides the default behavior where unknown revocation status is considered an error.", + "feature": null, + "deprecation": null, + "name": "rustls_web_pki_server_cert_verifier_allow_unknown_revocation_status", + "text": "```c\nrustls_result rustls_web_pki_server_cert_verifier_allow_unknown_revocation_status(struct rustls_web_pki_server_cert_verifier_builder *builder);\n```" + }, + { + "anchor": "rustls-web-pki-server-cert-verifier-enforce-revocation-expiry", + "comment": "When CRLs are provided with [`rustls_web_pki_server_cert_verifier_builder_add_crl`](#rustls-web-pki-server-cert-verifier-builder-add-crl), and the\n CRL nextUpdate field is in the past, treat it as an error condition.\n\n Overrides the default behavior where CRL expiration is ignored.", + "feature": null, + "deprecation": null, + "name": "rustls_web_pki_server_cert_verifier_enforce_revocation_expiry", + "text": "```c\nrustls_result rustls_web_pki_server_cert_verifier_enforce_revocation_expiry(struct rustls_web_pki_server_cert_verifier_builder *builder);\n```" + }, + { + "anchor": "rustls-web-pki-server-cert-verifier-builder-build", + "comment": "Create a new server certificate verifier from the builder.\n\n The builder is consumed and cannot be used again, but must still be freed.\n\n The verifier can be used in several [`rustls_client_config`](#rustls-client-config) instances and must be\n freed by the application when no longer needed. See the documentation of\n [`rustls_web_pki_server_cert_verifier_builder_free`](#rustls-web-pki-server-cert-verifier-builder-free) for details about lifetime.", + "feature": null, + "deprecation": null, + "name": "rustls_web_pki_server_cert_verifier_builder_build", + "text": "```c\nrustls_result rustls_web_pki_server_cert_verifier_builder_build(struct rustls_web_pki_server_cert_verifier_builder *builder,\n struct rustls_server_cert_verifier **verifier_out);\n```" + }, + { + "anchor": "rustls-web-pki-server-cert-verifier-builder-free", + "comment": "Free a `rustls_server_cert_verifier_builder` previously returned from\n `rustls_server_cert_verifier_builder_new`.\n\n Calling with NULL is fine. Must not be called twice with the same value.", + "feature": null, + "deprecation": null, + "name": "rustls_web_pki_server_cert_verifier_builder_free", + "text": "```c\nvoid rustls_web_pki_server_cert_verifier_builder_free(struct rustls_web_pki_server_cert_verifier_builder *builder);\n```" + }, + { + "anchor": "rustls-platform-server-cert-verifier", + "comment": "Create a verifier that uses the default behavior for the current platform.\n\n This uses [`rustls-platform-verifier`][].\n\n The verifier can be used in several [`rustls_client_config`](#rustls-client-config) instances and must be freed by\n the application using [`rustls_server_cert_verifier_free`](#rustls-server-cert-verifier-free) when no longer needed.\n\n [`rustls-platform-verifier`]: https://github.com/rustls/rustls-platform-verifier", + "feature": null, + "deprecation": null, + "name": "rustls_platform_server_cert_verifier", + "text": "```c\nrustls_result rustls_platform_server_cert_verifier(struct rustls_server_cert_verifier **verifier_out);\n```" + }, + { + "anchor": "rustls-platform-server-cert-verifier-with-provider", + "comment": "Create a verifier that uses the default behavior for the current platform.\n\n This uses [`rustls-platform-verifier`][] and the specified crypto provider.\n\n The verifier can be used in several [`rustls_client_config`](#rustls-client-config) instances and must be freed by\n the application using [`rustls_server_cert_verifier_free`](#rustls-server-cert-verifier-free) when no longer needed.\n\n If the initialization of `rustls-platform-verifier` fails, this function returns\n `NULL`.\n\n [`rustls-platform-verifier`]: https://github.com/rustls/rustls-platform-verifier", + "feature": null, + "deprecation": "prefer to use rustls_platform_server_cert_verifier_try_with_provider", + "name": "rustls_platform_server_cert_verifier_with_provider", + "text": "```c\nstruct rustls_server_cert_verifier *rustls_platform_server_cert_verifier_with_provider(const struct rustls_crypto_provider *provider);\n```" + }, + { + "anchor": "rustls-platform-server-cert-verifier-try-with-provider", + "comment": "Create a verifier that uses the default behavior for the current platform.\n\n This uses [`rustls-platform-verifier`][] and the specified crypto provider.\n\n If the initialization of `rustls-platform-verifier` fails, this function returns\n an error and `NULL` is written to `verifier_out`. Otherwise it fills in `verifier_out`\n (whose ownership is transferred to the caller) and returns `RUSTLS_SUCCESS`.\n\n The verifier can be used in several [`rustls_client_config`](#rustls-client-config) instances and must be freed by\n the application using [`rustls_server_cert_verifier_free`](#rustls-server-cert-verifier-free) when no longer needed.\n\n [`rustls-platform-verifier`]: https://github.com/rustls/rustls-platform-verifier", + "feature": null, + "deprecation": null, + "name": "rustls_platform_server_cert_verifier_try_with_provider", + "text": "```c\nrustls_result rustls_platform_server_cert_verifier_try_with_provider(const struct rustls_crypto_provider *provider,\n struct rustls_server_cert_verifier **verifier_out);\n```" + }, + { + "anchor": "rustls-server-cert-verifier-free", + "comment": "Free a [`rustls_server_cert_verifier`](#rustls-server-cert-verifier) previously returned from\n `rustls_server_cert_verifier_builder_build` or [`rustls_platform_server_cert_verifier`](#rustls-platform-server-cert-verifier).\n\n Calling with NULL is fine. Must not be called twice with the same value.", + "feature": null, + "deprecation": null, + "name": "rustls_server_cert_verifier_free", + "text": "```c\nvoid rustls_server_cert_verifier_free(struct rustls_server_cert_verifier *verifier);\n```" + }, + { + "anchor": "rustls-version", + "comment": "Returns a static string containing the rustls-ffi version as well as the\n rustls version. The string is alive for the lifetime of the program and does\n not need to be freed.", + "feature": null, + "deprecation": null, + "name": "rustls_version", + "text": "```c\nstruct rustls_str rustls_version(void);\n```" + } + ], + "callbacks": [ + { + "anchor": "rustls_read_callback", + "comment": "A callback for [`rustls_connection_read_tls`](#rustls-connection-read-tls).\n\n An implementation of this callback should attempt to read up to n bytes from the\n network, storing them in `buf`. If any bytes were stored, the implementation should\n set out_n to the number of bytes stored and return 0.\n\n If there was an error, the implementation should return a nonzero rustls_io_result,\n which will be passed through to the caller.\n\n On POSIX systems, returning `errno` is convenient.\n\n On other systems, any appropriate error code works.\n\n It's best to make one read attempt to the network per call. Additional reads will\n be triggered by subsequent calls to one of the `_read_tls` methods.\n\n `userdata` is set to the value provided to [`rustls_connection_set_userdata`](#rustls-connection-set-userdata).\n In most cases that should be a struct that contains, at a minimum, a file descriptor.\n\n The buf and out_n pointers are borrowed and should not be retained across calls.", + "feature": null, + "deprecation": null, + "name": "rustls_read_callback", + "text": "```c\ntypedef rustls_io_result (*rustls_read_callback)(void *userdata,\n uint8_t *buf,\n size_t n,\n size_t *out_n);\n```" + }, + { + "anchor": "rustls_write_callback", + "comment": "A callback for [`rustls_connection_write_tls`](#rustls-connection-write-tls) or [`rustls_accepted_alert_write_tls`](#rustls-accepted-alert-write-tls).\n\n An implementation of this callback should attempt to write the `n` bytes in buf\n to the network.\n\n If any bytes were written, the implementation should set `out_n` to the number of\n bytes stored and return 0.\n\n If there was an error, the implementation should return a nonzero `rustls_io_result`,\n which will be passed through to the caller.\n\n On POSIX systems, returning `errno` is convenient.\n\n On other systems, any appropriate error code works.\n\n It's best to make one write attempt to the network per call. Additional writes will\n be triggered by subsequent calls to rustls_connection_write_tls.\n\n `userdata` is set to the value provided to [`rustls_connection_set_userdata`](#rustls-connection-set-userdata). In most\n cases that should be a struct that contains, at a minimum, a file descriptor.\n\n The buf and out_n pointers are borrowed and should not be retained across calls.", + "feature": null, + "deprecation": null, + "name": "rustls_write_callback", + "text": "```c\ntypedef rustls_io_result (*rustls_write_callback)(void *userdata,\n const uint8_t *buf,\n size_t n,\n size_t *out_n);\n```" + }, + { + "anchor": "rustls_verify_server_cert_callback", + "comment": "A callback that is invoked to verify a server certificate.", + "feature": null, + "deprecation": null, + "name": "rustls_verify_server_cert_callback", + "text": "```c\ntypedef uint32_t (*rustls_verify_server_cert_callback)(rustls_verify_server_cert_user_data userdata,\n const struct rustls_verify_server_cert_params *params);\n```" + }, + { + "anchor": "rustls_keylog_log_callback", + "comment": "An optional callback for logging key material.\n\n See the documentation on [`rustls_client_config_builder_set_key_log`](#rustls-client-config-builder-set-key-log) and\n [`rustls_server_config_builder_set_key_log`](#rustls-server-config-builder-set-key-log) for more information about the\n lifetimes of the parameters.", + "feature": null, + "deprecation": null, + "name": "rustls_keylog_log_callback", + "text": "```c\ntypedef void (*rustls_keylog_log_callback)(struct rustls_str label,\n const uint8_t *client_random,\n size_t client_random_len,\n const uint8_t *secret,\n size_t secret_len);\n```" + }, + { + "anchor": "rustls_keylog_will_log_callback", + "comment": "An optional callback for deciding if key material will be logged.\n\n See the documentation on [`rustls_client_config_builder_set_key_log`](#rustls-client-config-builder-set-key-log) and\n [`rustls_server_config_builder_set_key_log`](#rustls-server-config-builder-set-key-log) for more information about the\n lifetimes of the parameters.", + "feature": null, + "deprecation": null, + "name": "rustls_keylog_will_log_callback", + "text": "```c\ntypedef int (*rustls_keylog_will_log_callback)(struct rustls_str label);\n```" + }, + { + "anchor": "rustls_log_callback", + "comment": "A callback that is invoked for messages logged by rustls.", + "feature": null, + "deprecation": null, + "name": "rustls_log_callback", + "text": "```c\ntypedef void (*rustls_log_callback)(void *userdata, const struct rustls_log_params *params);\n```" + }, + { + "anchor": "rustls_write_vectored_callback", + "comment": "A callback for [`rustls_connection_write_tls_vectored`](#rustls-connection-write-tls-vectored).\n\n An implementation of this callback should attempt to write the bytes in\n the given `count` iovecs to the network.\n\n If any bytes were written, the implementation should set out_n to the number of\n bytes written and return 0.\n\n If there was an error, the implementation should return a nonzero rustls_io_result,\n which will be passed through to the caller.\n\n On POSIX systems, returning `errno` is convenient.\n\n On other systems, any appropriate error code works.\n\n It's best to make one write attempt to the network per call. Additional write will\n be triggered by subsequent calls to one of the `_write_tls` methods.\n\n `userdata` is set to the value provided to `rustls_*_session_set_userdata`. In most\n cases that should be a struct that contains, at a minimum, a file descriptor.\n\n The iov and out_n pointers are borrowed and should not be retained across calls.", + "feature": null, + "deprecation": null, + "name": "rustls_write_vectored_callback", + "text": "```c\ntypedef rustls_io_result (*rustls_write_vectored_callback)(void *userdata,\n const struct rustls_iovec *iov,\n size_t count,\n size_t *out_n);\n```" + }, + { + "anchor": "rustls_client_hello_callback", + "comment": "Prototype of a callback that can be installed by the application at the\n [`rustls_server_config`](#rustls-server-config).\n\n This callback will be invoked by a [`rustls_connection`](#rustls-connection) once the TLS client\n hello message has been received.\n\n `userdata` will be set based on rustls_connection_set_userdata.\n\n `hello` gives the value of the available client announcements, as interpreted\n by rustls. See the definition of [`rustls_client_hello`](#rustls-client-hello) for details.\n\n NOTE:\n - the passed in `hello` and all its values are only available during the\n callback invocations.\n - the passed callback function must be safe to call multiple times concurrently\n with the same userdata, unless there is only a single config and connection\n where it is installed.\n\n EXPERIMENTAL: this feature of rustls-ffi is likely to change in the future, as\n the rustls library is re-evaluating their current approach to client hello handling.", + "feature": null, + "deprecation": null, + "name": "rustls_client_hello_callback", + "text": "```c\ntypedef const struct rustls_certified_key *(*rustls_client_hello_callback)(rustls_client_hello_userdata userdata,\n const struct rustls_client_hello *hello);\n```" + }, + { + "anchor": "rustls_session_store_get_callback", + "comment": "Prototype of a callback that can be installed by the application at the\n [`rustls_server_config`](#rustls-server-config) or [`rustls_client_config`](#rustls-client-config).\n\n This callback will be invoked by a TLS session when looking up the data\n for a TLS session id.\n\n `userdata` will be supplied based on rustls_{client,server}_session_set_userdata.\n\n The `buf` points to `count` consecutive bytes where the\n callback is expected to copy the result to. The number of copied bytes\n needs to be written to `out_n`. The callback should not read any\n data from `buf`.\n\n If the value to copy is larger than `count`, the callback should never\n do a partial copy but instead remove the value from its store and\n act as if it was never found.\n\n The callback should return RUSTLS_RESULT_OK to indicate that a value was\n retrieved and written in its entirety into `buf`, or RUSTLS_RESULT_NOT_FOUND\n if no session was retrieved.\n\n When `remove_after` is != 0, the returned data needs to be removed\n from the store.\n\n NOTE: the passed in `key` and `buf` are only available during the\n callback invocation.\n NOTE: callbacks used in several sessions via a common config\n must be implemented thread-safe.", + "feature": null, + "deprecation": null, + "name": "rustls_session_store_get_callback", + "text": "```c\ntypedef uint32_t (*rustls_session_store_get_callback)(rustls_session_store_userdata userdata,\n const struct rustls_slice_bytes *key,\n int remove_after,\n uint8_t *buf,\n size_t count,\n size_t *out_n);\n```" + }, + { + "anchor": "rustls_session_store_put_callback", + "comment": "Prototype of a callback that can be installed by the application at the\n [`rustls_server_config`](#rustls-server-config) or [`rustls_client_config`](#rustls-client-config).\n\n This callback will be invoked by a TLS session when a TLS session\n been created and an id for later use is handed to the client/has\n been received from the server.\n\n `userdata` will be supplied based on rustls_{client,server}_session_set_userdata.\n\n The callback should return RUSTLS_RESULT_OK to indicate that a value was\n successfully stored, or RUSTLS_RESULT_IO on failure.\n\n NOTE: the passed in `key` and `val` are only available during the\n callback invocation.\n NOTE: callbacks used in several sessions via a common config\n must be implemented thread-safe.", + "feature": null, + "deprecation": null, + "name": "rustls_session_store_put_callback", + "text": "```c\ntypedef uint32_t (*rustls_session_store_put_callback)(rustls_session_store_userdata userdata,\n const struct rustls_slice_bytes *key,\n const struct rustls_slice_bytes *val);\n```" + } + ], + "enums": [ + { + "anchor": "rustls-handshake-kind", + "comment": "Describes which sort of handshake happened.", + "feature": null, + "deprecation": null, + "name": "rustls_handshake_kind", + "variants": [ + { + "anchor": "rustls-handshake-kind-unknown", + "comment": "The type of handshake could not be determined.\n\n This variant should not be used.", + "name": "RUSTLS_HANDSHAKE_KIND_UNKNOWN", + "value": "0" + }, + { + "anchor": "rustls-handshake-kind-full", + "comment": "A full TLS handshake.\n\n This is the typical TLS connection initiation process when resumption is\n not yet unavailable, and the initial client hello was accepted by the server.", + "name": "RUSTLS_HANDSHAKE_KIND_FULL", + "value": "1" + }, + { + "anchor": "rustls-handshake-kind-full-with-hello-retry-request", + "comment": "A full TLS handshake, with an extra round-trip for a hello retry request.\n\n The server can respond with a hello retry request (HRR) if the initial client\n hello is unacceptable for several reasons, the most likely if no supported key\n shares were offered by the client.", + "name": "RUSTLS_HANDSHAKE_KIND_FULL_WITH_HELLO_RETRY_REQUEST", + "value": "2" + }, + { + "anchor": "rustls-handshake-kind-resumed", + "comment": "A resumed TLS handshake.\n\n Resumed handshakes involve fewer round trips and less cryptography than\n full ones, but can only happen when the peers have previously done a full\n handshake together, and then remember data about it.", + "name": "RUSTLS_HANDSHAKE_KIND_RESUMED", + "value": "3" + } + ] + }, + { + "anchor": "rustls-result", + "comment": "Numeric error codes returned from rustls-ffi API functions.", + "feature": null, + "deprecation": null, + "name": "rustls_result", + "variants": [ + { + "anchor": "rustls-result-ok", + "comment": null, + "name": "RUSTLS_RESULT_OK", + "value": "7000" + }, + { + "anchor": "rustls-result-io", + "comment": null, + "name": "RUSTLS_RESULT_IO", + "value": "7001" + }, + { + "anchor": "rustls-result-null-parameter", + "comment": null, + "name": "RUSTLS_RESULT_NULL_PARAMETER", + "value": "7002" + }, + { + "anchor": "rustls-result-invalid-dns-name-error", + "comment": null, + "name": "RUSTLS_RESULT_INVALID_DNS_NAME_ERROR", + "value": "7003" + }, + { + "anchor": "rustls-result-panic", + "comment": null, + "name": "RUSTLS_RESULT_PANIC", + "value": "7004" + }, + { + "anchor": "rustls-result-certificate-parse-error", + "comment": null, + "name": "RUSTLS_RESULT_CERTIFICATE_PARSE_ERROR", + "value": "7005" + }, + { + "anchor": "rustls-result-private-key-parse-error", + "comment": null, + "name": "RUSTLS_RESULT_PRIVATE_KEY_PARSE_ERROR", + "value": "7006" + }, + { + "anchor": "rustls-result-insufficient-size", + "comment": null, + "name": "RUSTLS_RESULT_INSUFFICIENT_SIZE", + "value": "7007" + }, + { + "anchor": "rustls-result-not-found", + "comment": null, + "name": "RUSTLS_RESULT_NOT_FOUND", + "value": "7008" + }, + { + "anchor": "rustls-result-invalid-parameter", + "comment": null, + "name": "RUSTLS_RESULT_INVALID_PARAMETER", + "value": "7009" + }, + { + "anchor": "rustls-result-unexpected-eof", + "comment": null, + "name": "RUSTLS_RESULT_UNEXPECTED_EOF", + "value": "7010" + }, + { + "anchor": "rustls-result-plaintext-empty", + "comment": null, + "name": "RUSTLS_RESULT_PLAINTEXT_EMPTY", + "value": "7011" + }, + { + "anchor": "rustls-result-acceptor-not-ready", + "comment": null, + "name": "RUSTLS_RESULT_ACCEPTOR_NOT_READY", + "value": "7012" + }, + { + "anchor": "rustls-result-already-used", + "comment": null, + "name": "RUSTLS_RESULT_ALREADY_USED", + "value": "7013" + }, + { + "anchor": "rustls-result-certificate-revocation-list-parse-error", + "comment": null, + "name": "RUSTLS_RESULT_CERTIFICATE_REVOCATION_LIST_PARSE_ERROR", + "value": "7014" + }, + { + "anchor": "rustls-result-no-server-cert-verifier", + "comment": null, + "name": "RUSTLS_RESULT_NO_SERVER_CERT_VERIFIER", + "value": "7015" + }, + { + "anchor": "rustls-result-no-default-crypto-provider", + "comment": null, + "name": "RUSTLS_RESULT_NO_DEFAULT_CRYPTO_PROVIDER", + "value": "7016" + }, + { + "anchor": "rustls-result-get-random-failed", + "comment": null, + "name": "RUSTLS_RESULT_GET_RANDOM_FAILED", + "value": "7017" + }, + { + "anchor": "rustls-result-no-cert-resolver", + "comment": null, + "name": "RUSTLS_RESULT_NO_CERT_RESOLVER", + "value": "7018" + }, + { + "anchor": "rustls-result-hpke-error", + "comment": null, + "name": "RUSTLS_RESULT_HPKE_ERROR", + "value": "7019" + }, + { + "anchor": "rustls-result-builder-incompatible-tls-versions", + "comment": null, + "name": "RUSTLS_RESULT_BUILDER_INCOMPATIBLE_TLS_VERSIONS", + "value": "7020" + }, + { + "anchor": "rustls-result-no-certificates-presented", + "comment": null, + "name": "RUSTLS_RESULT_NO_CERTIFICATES_PRESENTED", + "value": "7101" + }, + { + "anchor": "rustls-result-decrypt-error", + "comment": null, + "name": "RUSTLS_RESULT_DECRYPT_ERROR", + "value": "7102" + }, + { + "anchor": "rustls-result-failed-to-get-current-time", + "comment": null, + "name": "RUSTLS_RESULT_FAILED_TO_GET_CURRENT_TIME", + "value": "7103" + }, + { + "anchor": "rustls-result-failed-to-get-random-bytes", + "comment": null, + "name": "RUSTLS_RESULT_FAILED_TO_GET_RANDOM_BYTES", + "value": "7113" + }, + { + "anchor": "rustls-result-handshake-not-complete", + "comment": null, + "name": "RUSTLS_RESULT_HANDSHAKE_NOT_COMPLETE", + "value": "7104" + }, + { + "anchor": "rustls-result-peer-sent-oversized-record", + "comment": null, + "name": "RUSTLS_RESULT_PEER_SENT_OVERSIZED_RECORD", + "value": "7105" + }, + { + "anchor": "rustls-result-no-application-protocol", + "comment": null, + "name": "RUSTLS_RESULT_NO_APPLICATION_PROTOCOL", + "value": "7106" + }, + { + "anchor": "rustls-result-bad-max-fragment-size", + "comment": null, + "name": "RUSTLS_RESULT_BAD_MAX_FRAGMENT_SIZE", + "value": "7114" + }, + { + "anchor": "rustls-result-unsupported-name-type", + "comment": null, + "name": "RUSTLS_RESULT_UNSUPPORTED_NAME_TYPE", + "value": "7115" + }, + { + "anchor": "rustls-result-encrypt-error", + "comment": null, + "name": "RUSTLS_RESULT_ENCRYPT_ERROR", + "value": "7116" + }, + { + "anchor": "rustls-result-cert-encoding-bad", + "comment": null, + "name": "RUSTLS_RESULT_CERT_ENCODING_BAD", + "value": "7121" + }, + { + "anchor": "rustls-result-cert-expired", + "comment": null, + "name": "RUSTLS_RESULT_CERT_EXPIRED", + "value": "7122" + }, + { + "anchor": "rustls-result-cert-not-yet-valid", + "comment": null, + "name": "RUSTLS_RESULT_CERT_NOT_YET_VALID", + "value": "7123" + }, + { + "anchor": "rustls-result-cert-revoked", + "comment": null, + "name": "RUSTLS_RESULT_CERT_REVOKED", + "value": "7124" + }, + { + "anchor": "rustls-result-cert-unhandled-critical-extension", + "comment": null, + "name": "RUSTLS_RESULT_CERT_UNHANDLED_CRITICAL_EXTENSION", + "value": "7125" + }, + { + "anchor": "rustls-result-cert-unknown-issuer", + "comment": null, + "name": "RUSTLS_RESULT_CERT_UNKNOWN_ISSUER", + "value": "7126" + }, + { + "anchor": "rustls-result-cert-bad-signature", + "comment": null, + "name": "RUSTLS_RESULT_CERT_BAD_SIGNATURE", + "value": "7127" + }, + { + "anchor": "rustls-result-cert-not-valid-for-name", + "comment": null, + "name": "RUSTLS_RESULT_CERT_NOT_VALID_FOR_NAME", + "value": "7128" + }, + { + "anchor": "rustls-result-cert-invalid-purpose", + "comment": null, + "name": "RUSTLS_RESULT_CERT_INVALID_PURPOSE", + "value": "7129" + }, + { + "anchor": "rustls-result-cert-application-verification-failure", + "comment": null, + "name": "RUSTLS_RESULT_CERT_APPLICATION_VERIFICATION_FAILURE", + "value": "7130" + }, + { + "anchor": "rustls-result-cert-other-error", + "comment": null, + "name": "RUSTLS_RESULT_CERT_OTHER_ERROR", + "value": "7131" + }, + { + "anchor": "rustls-result-cert-unknown-revocation-status", + "comment": null, + "name": "RUSTLS_RESULT_CERT_UNKNOWN_REVOCATION_STATUS", + "value": "7154" + }, + { + "anchor": "rustls-result-cert-expired-revocation-list", + "comment": null, + "name": "RUSTLS_RESULT_CERT_EXPIRED_REVOCATION_LIST", + "value": "7156" + }, + { + "anchor": "rustls-result-cert-unsupported-signature-algorithm", + "comment": null, + "name": "RUSTLS_RESULT_CERT_UNSUPPORTED_SIGNATURE_ALGORITHM", + "value": "7157" + }, + { + "anchor": "rustls-result-message-handshake-payload-too-large", + "comment": null, + "name": "RUSTLS_RESULT_MESSAGE_HANDSHAKE_PAYLOAD_TOO_LARGE", + "value": "7133" + }, + { + "anchor": "rustls-result-message-invalid-ccs", + "comment": null, + "name": "RUSTLS_RESULT_MESSAGE_INVALID_CCS", + "value": "7134" + }, + { + "anchor": "rustls-result-message-invalid-content-type", + "comment": null, + "name": "RUSTLS_RESULT_MESSAGE_INVALID_CONTENT_TYPE", + "value": "7135" + }, + { + "anchor": "rustls-result-message-invalid-cert-status-type", + "comment": null, + "name": "RUSTLS_RESULT_MESSAGE_INVALID_CERT_STATUS_TYPE", + "value": "7136" + }, + { + "anchor": "rustls-result-message-invalid-cert-request", + "comment": null, + "name": "RUSTLS_RESULT_MESSAGE_INVALID_CERT_REQUEST", + "value": "7137" + }, + { + "anchor": "rustls-result-message-invalid-dh-params", + "comment": null, + "name": "RUSTLS_RESULT_MESSAGE_INVALID_DH_PARAMS", + "value": "7138" + }, + { + "anchor": "rustls-result-message-invalid-empty-payload", + "comment": null, + "name": "RUSTLS_RESULT_MESSAGE_INVALID_EMPTY_PAYLOAD", + "value": "7139" + }, + { + "anchor": "rustls-result-message-invalid-key-update", + "comment": null, + "name": "RUSTLS_RESULT_MESSAGE_INVALID_KEY_UPDATE", + "value": "7140" + }, + { + "anchor": "rustls-result-message-invalid-server-name", + "comment": null, + "name": "RUSTLS_RESULT_MESSAGE_INVALID_SERVER_NAME", + "value": "7141" + }, + { + "anchor": "rustls-result-message-too-large", + "comment": null, + "name": "RUSTLS_RESULT_MESSAGE_TOO_LARGE", + "value": "7142" + }, + { + "anchor": "rustls-result-message-too-short", + "comment": null, + "name": "RUSTLS_RESULT_MESSAGE_TOO_SHORT", + "value": "7143" + }, + { + "anchor": "rustls-result-message-missing-data", + "comment": null, + "name": "RUSTLS_RESULT_MESSAGE_MISSING_DATA", + "value": "7144" + }, + { + "anchor": "rustls-result-message-missing-key-exchange", + "comment": null, + "name": "RUSTLS_RESULT_MESSAGE_MISSING_KEY_EXCHANGE", + "value": "7145" + }, + { + "anchor": "rustls-result-message-no-signature-schemes", + "comment": null, + "name": "RUSTLS_RESULT_MESSAGE_NO_SIGNATURE_SCHEMES", + "value": "7146" + }, + { + "anchor": "rustls-result-message-trailing-data", + "comment": null, + "name": "RUSTLS_RESULT_MESSAGE_TRAILING_DATA", + "value": "7147" + }, + { + "anchor": "rustls-result-message-unexpected-message", + "comment": null, + "name": "RUSTLS_RESULT_MESSAGE_UNEXPECTED_MESSAGE", + "value": "7148" + }, + { + "anchor": "rustls-result-message-unknown-protocol-version", + "comment": null, + "name": "RUSTLS_RESULT_MESSAGE_UNKNOWN_PROTOCOL_VERSION", + "value": "7149" + }, + { + "anchor": "rustls-result-message-unsupported-compression", + "comment": null, + "name": "RUSTLS_RESULT_MESSAGE_UNSUPPORTED_COMPRESSION", + "value": "7150" + }, + { + "anchor": "rustls-result-message-unsupported-curve-type", + "comment": null, + "name": "RUSTLS_RESULT_MESSAGE_UNSUPPORTED_CURVE_TYPE", + "value": "7151" + }, + { + "anchor": "rustls-result-message-unsupported-key-exchange-algorithm", + "comment": null, + "name": "RUSTLS_RESULT_MESSAGE_UNSUPPORTED_KEY_EXCHANGE_ALGORITHM", + "value": "7152" + }, + { + "anchor": "rustls-result-message-invalid-other", + "comment": null, + "name": "RUSTLS_RESULT_MESSAGE_INVALID_OTHER", + "value": "7153" + }, + { + "anchor": "rustls-result-message-certificate-payload-too-large", + "comment": null, + "name": "RUSTLS_RESULT_MESSAGE_CERTIFICATE_PAYLOAD_TOO_LARGE", + "value": "7155" + }, + { + "anchor": "rustls-result-peer-incompatible-error", + "comment": null, + "name": "RUSTLS_RESULT_PEER_INCOMPATIBLE_ERROR", + "value": "7107" + }, + { + "anchor": "rustls-result-peer-misbehaved-error", + "comment": null, + "name": "RUSTLS_RESULT_PEER_MISBEHAVED_ERROR", + "value": "7108" + }, + { + "anchor": "rustls-result-inappropriate-message", + "comment": null, + "name": "RUSTLS_RESULT_INAPPROPRIATE_MESSAGE", + "value": "7109" + }, + { + "anchor": "rustls-result-inappropriate-handshake-message", + "comment": null, + "name": "RUSTLS_RESULT_INAPPROPRIATE_HANDSHAKE_MESSAGE", + "value": "7110" + }, + { + "anchor": "rustls-result-general", + "comment": null, + "name": "RUSTLS_RESULT_GENERAL", + "value": "7112" + }, + { + "anchor": "rustls-result-alert-close-notify", + "comment": null, + "name": "RUSTLS_RESULT_ALERT_CLOSE_NOTIFY", + "value": "7200" + }, + { + "anchor": "rustls-result-alert-unexpected-message", + "comment": null, + "name": "RUSTLS_RESULT_ALERT_UNEXPECTED_MESSAGE", + "value": "7201" + }, + { + "anchor": "rustls-result-alert-bad-record-mac", + "comment": null, + "name": "RUSTLS_RESULT_ALERT_BAD_RECORD_MAC", + "value": "7202" + }, + { + "anchor": "rustls-result-alert-decryption-failed", + "comment": null, + "name": "RUSTLS_RESULT_ALERT_DECRYPTION_FAILED", + "value": "7203" + }, + { + "anchor": "rustls-result-alert-record-overflow", + "comment": null, + "name": "RUSTLS_RESULT_ALERT_RECORD_OVERFLOW", + "value": "7204" + }, + { + "anchor": "rustls-result-alert-decompression-failure", + "comment": null, + "name": "RUSTLS_RESULT_ALERT_DECOMPRESSION_FAILURE", + "value": "7205" + }, + { + "anchor": "rustls-result-alert-handshake-failure", + "comment": null, + "name": "RUSTLS_RESULT_ALERT_HANDSHAKE_FAILURE", + "value": "7206" + }, + { + "anchor": "rustls-result-alert-no-certificate", + "comment": null, + "name": "RUSTLS_RESULT_ALERT_NO_CERTIFICATE", + "value": "7207" + }, + { + "anchor": "rustls-result-alert-bad-certificate", + "comment": null, + "name": "RUSTLS_RESULT_ALERT_BAD_CERTIFICATE", + "value": "7208" + }, + { + "anchor": "rustls-result-alert-unsupported-certificate", + "comment": null, + "name": "RUSTLS_RESULT_ALERT_UNSUPPORTED_CERTIFICATE", + "value": "7209" + }, + { + "anchor": "rustls-result-alert-certificate-revoked", + "comment": null, + "name": "RUSTLS_RESULT_ALERT_CERTIFICATE_REVOKED", + "value": "7210" + }, + { + "anchor": "rustls-result-alert-certificate-expired", + "comment": null, + "name": "RUSTLS_RESULT_ALERT_CERTIFICATE_EXPIRED", + "value": "7211" + }, + { + "anchor": "rustls-result-alert-certificate-unknown", + "comment": null, + "name": "RUSTLS_RESULT_ALERT_CERTIFICATE_UNKNOWN", + "value": "7212" + }, + { + "anchor": "rustls-result-alert-illegal-parameter", + "comment": null, + "name": "RUSTLS_RESULT_ALERT_ILLEGAL_PARAMETER", + "value": "7213" + }, + { + "anchor": "rustls-result-alert-unknown-ca", + "comment": null, + "name": "RUSTLS_RESULT_ALERT_UNKNOWN_CA", + "value": "7214" + }, + { + "anchor": "rustls-result-alert-access-denied", + "comment": null, + "name": "RUSTLS_RESULT_ALERT_ACCESS_DENIED", + "value": "7215" + }, + { + "anchor": "rustls-result-alert-decode-error", + "comment": null, + "name": "RUSTLS_RESULT_ALERT_DECODE_ERROR", + "value": "7216" + }, + { + "anchor": "rustls-result-alert-decrypt-error", + "comment": null, + "name": "RUSTLS_RESULT_ALERT_DECRYPT_ERROR", + "value": "7217" + }, + { + "anchor": "rustls-result-alert-export-restriction", + "comment": null, + "name": "RUSTLS_RESULT_ALERT_EXPORT_RESTRICTION", + "value": "7218" + }, + { + "anchor": "rustls-result-alert-protocol-version", + "comment": null, + "name": "RUSTLS_RESULT_ALERT_PROTOCOL_VERSION", + "value": "7219" + }, + { + "anchor": "rustls-result-alert-insufficient-security", + "comment": null, + "name": "RUSTLS_RESULT_ALERT_INSUFFICIENT_SECURITY", + "value": "7220" + }, + { + "anchor": "rustls-result-alert-internal-error", + "comment": null, + "name": "RUSTLS_RESULT_ALERT_INTERNAL_ERROR", + "value": "7221" + }, + { + "anchor": "rustls-result-alert-inappropriate-fallback", + "comment": null, + "name": "RUSTLS_RESULT_ALERT_INAPPROPRIATE_FALLBACK", + "value": "7222" + }, + { + "anchor": "rustls-result-alert-user-canceled", + "comment": null, + "name": "RUSTLS_RESULT_ALERT_USER_CANCELED", + "value": "7223" + }, + { + "anchor": "rustls-result-alert-no-renegotiation", + "comment": null, + "name": "RUSTLS_RESULT_ALERT_NO_RENEGOTIATION", + "value": "7224" + }, + { + "anchor": "rustls-result-alert-missing-extension", + "comment": null, + "name": "RUSTLS_RESULT_ALERT_MISSING_EXTENSION", + "value": "7225" + }, + { + "anchor": "rustls-result-alert-unsupported-extension", + "comment": null, + "name": "RUSTLS_RESULT_ALERT_UNSUPPORTED_EXTENSION", + "value": "7226" + }, + { + "anchor": "rustls-result-alert-certificate-unobtainable", + "comment": null, + "name": "RUSTLS_RESULT_ALERT_CERTIFICATE_UNOBTAINABLE", + "value": "7227" + }, + { + "anchor": "rustls-result-alert-unrecognised-name", + "comment": null, + "name": "RUSTLS_RESULT_ALERT_UNRECOGNISED_NAME", + "value": "7228" + }, + { + "anchor": "rustls-result-alert-bad-certificate-status-response", + "comment": null, + "name": "RUSTLS_RESULT_ALERT_BAD_CERTIFICATE_STATUS_RESPONSE", + "value": "7229" + }, + { + "anchor": "rustls-result-alert-bad-certificate-hash-value", + "comment": null, + "name": "RUSTLS_RESULT_ALERT_BAD_CERTIFICATE_HASH_VALUE", + "value": "7230" + }, + { + "anchor": "rustls-result-alert-unknown-psk-identity", + "comment": null, + "name": "RUSTLS_RESULT_ALERT_UNKNOWN_PSK_IDENTITY", + "value": "7231" + }, + { + "anchor": "rustls-result-alert-certificate-required", + "comment": null, + "name": "RUSTLS_RESULT_ALERT_CERTIFICATE_REQUIRED", + "value": "7232" + }, + { + "anchor": "rustls-result-alert-no-application-protocol", + "comment": null, + "name": "RUSTLS_RESULT_ALERT_NO_APPLICATION_PROTOCOL", + "value": "7233" + }, + { + "anchor": "rustls-result-alert-unknown", + "comment": null, + "name": "RUSTLS_RESULT_ALERT_UNKNOWN", + "value": "7234" + }, + { + "anchor": "rustls-result-cert-revocation-list-bad-signature", + "comment": null, + "name": "RUSTLS_RESULT_CERT_REVOCATION_LIST_BAD_SIGNATURE", + "value": "7400" + }, + { + "anchor": "rustls-result-cert-revocation-list-invalid-crl-number", + "comment": null, + "name": "RUSTLS_RESULT_CERT_REVOCATION_LIST_INVALID_CRL_NUMBER", + "value": "7401" + }, + { + "anchor": "rustls-result-cert-revocation-list-invalid-revoked-cert-serial-number", + "comment": null, + "name": "RUSTLS_RESULT_CERT_REVOCATION_LIST_INVALID_REVOKED_CERT_SERIAL_NUMBER", + "value": "7402" + }, + { + "anchor": "rustls-result-cert-revocation-list-issuer-invalid-for-crl", + "comment": null, + "name": "RUSTLS_RESULT_CERT_REVOCATION_LIST_ISSUER_INVALID_FOR_CRL", + "value": "7403" + }, + { + "anchor": "rustls-result-cert-revocation-list-other-error", + "comment": null, + "name": "RUSTLS_RESULT_CERT_REVOCATION_LIST_OTHER_ERROR", + "value": "7404" + }, + { + "anchor": "rustls-result-cert-revocation-list-parse-error", + "comment": null, + "name": "RUSTLS_RESULT_CERT_REVOCATION_LIST_PARSE_ERROR", + "value": "7405" + }, + { + "anchor": "rustls-result-cert-revocation-list-unsupported-crl-version", + "comment": null, + "name": "RUSTLS_RESULT_CERT_REVOCATION_LIST_UNSUPPORTED_CRL_VERSION", + "value": "7406" + }, + { + "anchor": "rustls-result-cert-revocation-list-unsupported-critical-extension", + "comment": null, + "name": "RUSTLS_RESULT_CERT_REVOCATION_LIST_UNSUPPORTED_CRITICAL_EXTENSION", + "value": "7407" + }, + { + "anchor": "rustls-result-cert-revocation-list-unsupported-delta-crl", + "comment": null, + "name": "RUSTLS_RESULT_CERT_REVOCATION_LIST_UNSUPPORTED_DELTA_CRL", + "value": "7408" + }, + { + "anchor": "rustls-result-cert-revocation-list-unsupported-indirect-crl", + "comment": null, + "name": "RUSTLS_RESULT_CERT_REVOCATION_LIST_UNSUPPORTED_INDIRECT_CRL", + "value": "7409" + }, + { + "anchor": "rustls-result-cert-revocation-list-unsupported-revocation-reason", + "comment": null, + "name": "RUSTLS_RESULT_CERT_REVOCATION_LIST_UNSUPPORTED_REVOCATION_REASON", + "value": "7410" + }, + { + "anchor": "rustls-result-cert-revocation-list-unsupported-signature-algorithm", + "comment": null, + "name": "RUSTLS_RESULT_CERT_REVOCATION_LIST_UNSUPPORTED_SIGNATURE_ALGORITHM", + "value": "7411" + }, + { + "anchor": "rustls-result-client-cert-verifier-builder-no-root-anchors", + "comment": null, + "name": "RUSTLS_RESULT_CLIENT_CERT_VERIFIER_BUILDER_NO_ROOT_ANCHORS", + "value": "7500" + }, + { + "anchor": "rustls-result-inconsistent-keys-keys-mismatch", + "comment": null, + "name": "RUSTLS_RESULT_INCONSISTENT_KEYS_KEYS_MISMATCH", + "value": "7600" + }, + { + "anchor": "rustls-result-inconsistent-keys-unknown", + "comment": null, + "name": "RUSTLS_RESULT_INCONSISTENT_KEYS_UNKNOWN", + "value": "7601" + }, + { + "anchor": "rustls-result-invalid-encrypted-client-hello-invalid-config-list", + "comment": null, + "name": "RUSTLS_RESULT_INVALID_ENCRYPTED_CLIENT_HELLO_INVALID_CONFIG_LIST", + "value": "7700" + }, + { + "anchor": "rustls-result-invalid-encrypted-client-hello-no-compatible-config", + "comment": null, + "name": "RUSTLS_RESULT_INVALID_ENCRYPTED_CLIENT_HELLO_NO_COMPATIBLE_CONFIG", + "value": "7701" + }, + { + "anchor": "rustls-result-invalid-encrypted-client-hello-sni-required", + "comment": null, + "name": "RUSTLS_RESULT_INVALID_ENCRYPTED_CLIENT_HELLO_SNI_REQUIRED", + "value": "7702" + } + ] + }, + { + "anchor": "rustls-tls-version", + "comment": "Definitions of known TLS protocol versions.", + "feature": null, + "deprecation": null, + "name": "rustls_tls_version", + "variants": [ + { + "anchor": "rustls-tls-version-unknown", + "comment": null, + "name": "RUSTLS_TLS_VERSION_UNKNOWN", + "value": "0" + }, + { + "anchor": "rustls-tls-version-sslv2", + "comment": null, + "name": "RUSTLS_TLS_VERSION_SSLV2", + "value": "512" + }, + { + "anchor": "rustls-tls-version-sslv3", + "comment": null, + "name": "RUSTLS_TLS_VERSION_SSLV3", + "value": "768" + }, + { + "anchor": "rustls-tls-version-tlsv1-0", + "comment": null, + "name": "RUSTLS_TLS_VERSION_TLSV1_0", + "value": "769" + }, + { + "anchor": "rustls-tls-version-tlsv1-1", + "comment": null, + "name": "RUSTLS_TLS_VERSION_TLSV1_1", + "value": "770" + }, + { + "anchor": "rustls-tls-version-tlsv1-2", + "comment": null, + "name": "RUSTLS_TLS_VERSION_TLSV1_2", + "value": "771" + }, + { + "anchor": "rustls-tls-version-tlsv1-3", + "comment": null, + "name": "RUSTLS_TLS_VERSION_TLSV1_3", + "value": "772" + } + ] + } + ], + "externs": [ + { + "anchor": "rustls-all-versions", + "comment": "Rustls' list of supported protocol versions. The length of the array is\n given by `RUSTLS_ALL_VERSIONS_LEN`.", + "feature": null, + "deprecation": null, + "name": "RUSTLS_ALL_VERSIONS", + "text": "```c\nextern const uint16_t RUSTLS_ALL_VERSIONS[2];\n```" + }, + { + "anchor": "rustls-all-versions-len", + "comment": "The length of the array `RUSTLS_ALL_VERSIONS`.", + "feature": null, + "deprecation": null, + "name": "RUSTLS_ALL_VERSIONS_LEN", + "text": "```c\nextern const size_t RUSTLS_ALL_VERSIONS_LEN;\n```" + }, + { + "anchor": "rustls-default-versions", + "comment": "Rustls' default list of protocol versions. The length of the array is\n given by `RUSTLS_DEFAULT_VERSIONS_LEN`.", + "feature": null, + "deprecation": null, + "name": "RUSTLS_DEFAULT_VERSIONS", + "text": "```c\nextern const uint16_t RUSTLS_DEFAULT_VERSIONS[2];\n```" + }, + { + "anchor": "rustls-default-versions-len", + "comment": "The length of the array `RUSTLS_DEFAULT_VERSIONS`.", + "feature": null, + "deprecation": null, + "name": "RUSTLS_DEFAULT_VERSIONS_LEN", + "text": "```c\nextern const size_t RUSTLS_DEFAULT_VERSIONS_LEN;\n```" + } + ], + "aliases": [ + { + "anchor": "alias-rustls-result", + "comment": "", + "feature": null, + "deprecation": null, + "name": "rustls_result", + "text": "```c\ntypedef uint32_t rustls_result;\n```" + }, + { + "anchor": "alias-rustls-io-result", + "comment": "A return value for a function that may return either success (0) or a\n non-zero value representing an error.\n\n The values should match socket error numbers for your operating system --\n for example, the integers for `ETIMEDOUT`, `EAGAIN`, or similar.", + "feature": null, + "deprecation": null, + "name": "rustls_io_result", + "text": "```c\ntypedef int rustls_io_result;\n```" + }, + { + "anchor": "alias-rustls-verify-server-cert-user-data", + "comment": "User-provided input to a custom certificate verifier callback.\n\n See [`rustls_client_config_builder_dangerous_set_certificate_verifier()`](#rustls-client-config-builder-dangerous-set-certificate-verifier).", + "feature": null, + "deprecation": null, + "name": "rustls_verify_server_cert_user_data", + "text": "```c\ntypedef void *rustls_verify_server_cert_user_data;\n```" + }, + { + "anchor": "alias-rustls-log-level", + "comment": "Numeric representation of a log level.\n\n Passed as a field of the [`rustls_log_params`](#rustls-log-params) passed to a log callback.\n Use with [`rustls_log_level_str`](#rustls-log-level-str) to convert to a string label.", + "feature": null, + "deprecation": null, + "name": "rustls_log_level", + "text": "```c\ntypedef size_t rustls_log_level;\n```" + }, + { + "anchor": "alias-rustls-client-hello-userdata", + "comment": "Any context information the callback will receive when invoked.", + "feature": null, + "deprecation": null, + "name": "rustls_client_hello_userdata", + "text": "```c\ntypedef void *rustls_client_hello_userdata;\n```" + }, + { + "anchor": "alias-rustls-session-store-userdata", + "comment": "Any context information the callback will receive when invoked.", + "feature": null, + "deprecation": null, + "name": "rustls_session_store_userdata", + "text": "```c\ntypedef void *rustls_session_store_userdata;\n```" + } + ] +} diff --git a/website/static/style.css b/website/static/style.css index a283d351..60408ad1 100644 --- a/website/static/style.css +++ b/website/static/style.css @@ -162,6 +162,27 @@ h3:hover .anchor, border-radius: 0.5em; } +.deprecation-box { + display: flex; + align-items: center; + gap: 0.75rem; + padding: 0.75rem 1rem; + margin: 1rem 0; + background: #8b5a2b; + border-left: 5px solid #f59e0b; + border-right: 1px solid #f59e0b; + border-top: 1px solid #f59e0b; + border-bottom: 1px solid #f59e0b; + border-radius: 0.5em; +} + +.toc-deprecated { + color: #f59e0b; + font-size: 0.8em; + font-weight: normal; + margin-left: 0.5em; +} + a:has(code) { text-decoration: none; } diff --git a/website/templates/_api_section.html b/website/templates/_api_section.html index 153ee945..680bc63d 100644 --- a/website/templates/_api_section.html +++ b/website/templates/_api_section.html @@ -18,6 +18,12 @@ {% endif %} + {% if item.deprecation %} +
+ ⚠️ Deprecated: {{ item.deprecation }} +
+ {% endif %} + {{ item.comment | markdown | safe }} {% if section_id == "enums" %} diff --git a/website/templates/macros.html b/website/templates/macros.html index ef50f1c4..ae107421 100644 --- a/website/templates/macros.html +++ b/website/templates/macros.html @@ -16,7 +16,14 @@