From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from gate001.proxmox.com (gate001.proxmox.com [IPv6:2a0f:8001:1:32::40]) by lore.proxmox.com (Postfix) with ESMTPS id 2FE811FF0B6 for ; Thu, 12 Nov 2026 15:13:55 +0100 (CET) Received: from gate001.proxmox.com (localhost.localdomain [127.0.0.1]) by gate001.proxmox.com (Proxmox) with ESMTP id 942082166F; Thu, 12 Nov 2026 15:13:52 +0100 (CET) From: Filip Schauer To: pve-devel@lists.proxmox.com Subject: [PATCH proxmox 09/26] oci: add a registry client Date: Thu, 12 Nov 2026 15:10:36 +0100 Message-ID: <20261112141109.137298-10-f.schauer@proxmox.com> X-Mailer: git-send-email 2.47.3 In-Reply-To: <20261112141109.137298-1-f.schauer@proxmox.com> References: <20261112141109.137298-1-f.schauer@proxmox.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Bm-Milter-Handled: 55990f41-d878-4baa-be0a-ee34c49e34d2 X-Bm-Transport-Timestamp: 1794492826582 X-SPAM-LEVEL: Spam detection results: 0 AWL 0.205 Adjusted score from AWL reputation of From: address DMARC_MISSING 0.1 Missing DMARC policy KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment (newer systems) RCVD_IN_DNSWL_MED -2.3 Sender listed at https://www.dnswl.org/, medium trust SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record SPF_PASS -0.001 SPF: sender matches SPF record Message-ID-Hash: IYOHUGUGWS2CK2WTCIYEJHDVL6X7P52D X-Message-ID-Hash: IYOHUGUGWS2CK2WTCIYEJHDVL6X7P52D X-MailFrom: f.schauer@proxmox.com X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; loop; banned-address; emergency; member-moderation; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; digests; suspicious-header X-Mailman-Version: 3.3.10 Precedence: list List-Id: Proxmox VE development discussion List-Help: List-Owner: List-Post: List-Subscribe: List-Unsubscribe: The client code is inspired by https://github.com/oras-project/rust-oci-client Signed-off-by: Filip Schauer --- proxmox-oci/Cargo.toml | 7 + proxmox-oci/debian/control | 16 + proxmox-oci/src/client.rs | 612 +++++++++++++++++++++++++++++++++++++ proxmox-oci/src/digest.rs | 19 ++ proxmox-oci/src/lib.rs | 2 + 5 files changed, 656 insertions(+) create mode 100644 proxmox-oci/src/client.rs diff --git a/proxmox-oci/Cargo.toml b/proxmox-oci/Cargo.toml index 08c47db5..45248658 100644 --- a/proxmox-oci/Cargo.toml +++ b/proxmox-oci/Cargo.toml @@ -13,12 +13,19 @@ rust-version.workspace = true [dependencies] flate2.workspace = true +http.workspace = true +http-auth = { version = "0.1", default-features = false } oci-spec = "0.8.3" +serde.workspace = true +serde_json.workspace = true sha2 = "0.10" tar.workspace = true thiserror = "1" +url.workspace = true zstd.workspace = true +proxmox-base64.workspace = true +proxmox-http = { workspace = true, features = [ "client-sync" ] } proxmox-io.workspace = true [dev-dependencies] diff --git a/proxmox-oci/debian/control b/proxmox-oci/debian/control index a742b948..9ec73059 100644 --- a/proxmox-oci/debian/control +++ b/proxmox-oci/debian/control @@ -7,11 +7,19 @@ Build-Depends-Arch: cargo:native , rustc:native (>= 1.88) , libstd-rust-dev , librust-flate2-1+default-dev , + librust-http-1+default-dev , + librust-http-auth-0.1-dev , librust-oci-spec-0.8+default-dev (>= 0.8.3-~~) , + librust-proxmox-base64-1+default-dev , + librust-proxmox-http-1+client-sync-dev (>= 1.0.5-~~) , + librust-proxmox-http-1+default-dev (>= 1.0.5-~~) , librust-proxmox-io-1+default-dev (>= 1.2.1-~~) , + librust-serde-1+default-dev , + librust-serde-json-1+default-dev , librust-sha2-0.10+default-dev , librust-tar-0.4+default-dev , librust-thiserror-1+default-dev , + librust-url-2+default-dev (>= 2.2-~~) , librust-zstd-0.13+default-dev Maintainer: Proxmox Support Team Standards-Version: 4.7.2 @@ -26,11 +34,19 @@ Multi-Arch: same Depends: ${misc:Depends}, librust-flate2-1+default-dev, + librust-http-1+default-dev, + librust-http-auth-0.1-dev, librust-oci-spec-0.8+default-dev (>= 0.8.3-~~), + librust-proxmox-base64-1+default-dev, + librust-proxmox-http-1+client-sync-dev (>= 1.0.5-~~), + librust-proxmox-http-1+default-dev (>= 1.0.5-~~), librust-proxmox-io-1+default-dev (>= 1.2.1-~~), + librust-serde-1+default-dev, + librust-serde-json-1+default-dev, librust-sha2-0.10+default-dev, librust-tar-0.4+default-dev, librust-thiserror-1+default-dev, + librust-url-2+default-dev (>= 2.2-~~), librust-zstd-0.13+default-dev Provides: librust-proxmox-oci+default-dev (= ${binary:Version}), diff --git a/proxmox-oci/src/client.rs b/proxmox-oci/src/client.rs new file mode 100644 index 00000000..c6d15cbc --- /dev/null +++ b/proxmox-oci/src/client.rs @@ -0,0 +1,612 @@ +use std::collections::HashMap; +use std::io::{self, Cursor, Read, Write}; +use std::str::FromStr; +use std::time::{Duration, Instant}; + +use http::HeaderValue; +use http::uri::Scheme; +use http::{HeaderMap, StatusCode}; +use http_auth::{ChallengeParser, ChallengeRef}; +use oci_spec::OciSpecError; +use oci_spec::distribution::{ErrorResponse, Reference, TagList}; +use oci_spec::image::{ + Arch, Descriptor, Digest, ImageConfiguration, ImageIndex, ImageManifest, MediaType, Os, +}; +use proxmox_http::client::sync; +use proxmox_http::{HttpClient, HttpOptions, ProxyConfig}; +use serde::Deserialize; +use thiserror::Error; +use url::Url; + +use crate::digest::{DigestError, VerifyingReader, verify_digest}; + +// Inspired by https://github.com/oras-project/rust-oci-client + +#[derive(Deserialize)] +pub enum RegistryAuth { + /// Access the registry anonymously + Anonymous, + /// Access the registry using HTTP Basic authentication + Basic(String, String), + /// Access the registry using Bearer token authentication + Bearer(String), +} + +struct BearerChallenge { + realm: Url, + service: Option, +} + +impl TryFrom<&HeaderValue> for BearerChallenge { + type Error = String; + + fn try_from(value: &HeaderValue) -> Result { + let header = value + .to_str() + .map_err(|e| format!("cannot convert header value to string: {e:?}"))?; + ChallengeParser::new(header) + .filter_map(Result::ok) + .find_map(|c| BearerChallenge::try_from(&c).ok()) + .ok_or_else(|| "Cannot find Bearer challenge".to_string()) + } +} + +impl TryFrom<&ChallengeRef<'_>> for BearerChallenge { + type Error = String; + + fn try_from(value: &ChallengeRef<'_>) -> Result { + if !value.scheme.eq_ignore_ascii_case("Bearer") { + return Err(format!( + "BearerChallenge doesn't support challenge scheme {:?}", + value.scheme + )); + } + + let mut realm = None; + let mut service = None; + + for (k, v) in &value.params { + if k.eq_ignore_ascii_case("realm") { + realm = Some(Url::parse(&v.to_unescaped()).map_err(|err| err.to_string())?); + } + if k.eq_ignore_ascii_case("service") { + service = Some(v.to_unescaped()); + } + } + + if let Some(realm) = realm { + Ok(BearerChallenge { realm, service }) + } else { + Err("missing required parameter realm".to_string()) + } + } +} + +enum RegistryTokenType { + Bearer(String), + Basic(String, String), +} + +struct TokenCacheValue { + token: RegistryTokenType, + expiration: Option, +} + +struct TokenCache(HashMap); + +impl TokenCache { + fn new() -> Self { + Self(HashMap::new()) + } + + fn insert(&mut self, reference: Reference, token: RegistryTokenType) { + let expiration = match token { + RegistryTokenType::Basic(_, _) => None, + RegistryTokenType::Bearer(_) => Instant::now().checked_add(Duration::from_secs(60)), + }; + self.0 + .insert(reference, TokenCacheValue { token, expiration }); + } + + fn get(&self, reference: &Reference) -> Option<&RegistryTokenType> { + let TokenCacheValue { token, expiration } = self.0.get(reference)?; + expiration + .is_none_or(|t| t > Instant::now()) + .then_some(token) + } +} + +#[derive(Error, Debug)] +pub enum OciClientError { + #[error("Authentication failure: {0}")] + AuthenticationFailure(String), + #[error(transparent)] + Digest(#[from] DigestError), + #[error(transparent)] + Io(#[from] io::Error), + #[error("No image manifest found in image index for the requested platform")] + NoMatchingManifest, + #[error("Registry error: url {url}, envelope: {envelope}")] + Registry { + /// List of errors returned by the OCI registry + envelope: ErrorResponse, + /// Request URL + url: Url, + }, + #[error("Transport error: {0}")] + Transport(String), + #[error("Server error: url {url}, code: {code}, message: {message}")] + Server { + code: http::StatusCode, + url: Url, + message: String, + }, + #[error("OCI distribution spec violation: {0}")] + SpecViolation(String), + #[error("Not authorized: url {url}")] + Unauthorized { url: Url }, + #[error(transparent)] + UrlParse(#[from] url::ParseError), + #[error(transparent)] + OciSpec(#[from] OciSpecError), +} + +pub struct DigestedImageManifest { + pub manifest: ImageManifest, + pub raw: Vec, + pub digest: Digest, +} + +pub struct DigestedImageConfig { + pub config: ImageConfiguration, + pub raw: Vec, + pub digest: Digest, +} + +pub struct ImageMetadata { + pub manifest: DigestedImageManifest, + pub config: DigestedImageConfig, +} + +struct OciResponse { + status: StatusCode, + headers: HeaderMap, + url: Url, + body: Box, +} + +impl OciResponse { + fn into_body(self) -> Box { + self.body + } + + fn read_to_end(mut self) -> Result, OciClientError> { + let mut buf = Vec::new(); + self.body.read_to_end(&mut buf)?; + Ok(buf) + } + + fn read_to_string(mut self) -> Result { + let mut s = String::new(); + self.body.read_to_string(&mut s)?; + Ok(s) + } +} + +struct OciRequest { + url: Url, + headers: Vec<(String, String)>, + query_params: Vec<(String, String)>, +} + +impl OciRequest { + fn new(url: Url) -> Self { + Self { + url, + headers: Vec::new(), + query_params: Vec::new(), + } + } + + fn header(mut self, name: &str, value: &str) -> Self { + self.headers.push((name.to_string(), value.to_string())); + self + } + + fn query(mut self, key: &str, value: &str) -> Self { + self.query_params.push((key.to_string(), value.to_string())); + self + } + + fn with_accept(mut self, accept: &[&str]) -> Self { + self.headers.push(("Accept".to_string(), accept.join(", "))); + self + } + + fn with_auth(mut self, token: &RegistryTokenType) -> Self { + let value = match token { + RegistryTokenType::Bearer(token) => format!("Bearer {token}"), + RegistryTokenType::Basic(username, password) => { + let creds = proxmox_base64::encode(format!("{username}:{password}")); + format!("Basic {creds}") + } + }; + self.headers.push(("Authorization".to_string(), value)); + self + } + + fn build_url(&self) -> Url { + let mut url = self.url.clone(); + + for (k, v) in &self.query_params { + url.query_pairs_mut().append_pair(k, v); + } + + url + } +} + +pub struct ClientConfig { + pub protocol: Scheme, + pub timeout: Option, + pub proxy_config: Option, +} + +impl Default for ClientConfig { + fn default() -> Self { + Self { + protocol: Scheme::HTTPS, + timeout: Some(Duration::from_secs(20)), + proxy_config: None, + } + } +} + +pub struct Client { + protocol: Scheme, + auth: RegistryAuth, + tokens: TokenCache, + http_client: sync::Client, +} + +impl Client { + pub fn new(config: ClientConfig, auth: RegistryAuth) -> Self { + let options = HttpOptions { + proxy_config: config.proxy_config, + ..Default::default() + }; + + let http_client = if let Some(timeout) = config.timeout { + sync::Client::new_with_timeout(options, timeout) + } else { + sync::Client::new(options) + } + .with_http_status_as_error(false); + + Self { + tokens: TokenCache::new(), + protocol: config.protocol, + auth, + http_client, + } + } + + fn get_auth_token( + &mut self, + reference: &Reference, + ) -> Result, OciClientError> { + if self.tokens.get(reference).is_none() { + match self.authenticate(reference, &self.auth)? { + Some(token) => self.tokens.insert(reference.clone(), token), + None => return Ok(None), + }; + } + + Ok(self.tokens.get(reference)) + } + + fn authenticate( + &self, + image: &Reference, + authentication: &RegistryAuth, + ) -> Result, OciClientError> { + if let RegistryAuth::Bearer(token) = authentication { + return Ok(Some(RegistryTokenType::Bearer(token.clone()))); + } + + let url = Url::parse(&format!( + "{}://{}/v2/", + self.protocol, + image.resolve_registry() + ))?; + let req = OciRequest::new(url); + let res = self.send(req)?; + let dist_hdr = match res.headers.get(http::header::WWW_AUTHENTICATE) { + Some(h) => h, + None => return Ok(None), + }; + + let challenge = match BearerChallenge::try_from(dist_hdr) { + Ok(c) => c, + Err(_) => { + if let RegistryAuth::Basic(username, password) = authentication { + return Ok(Some(RegistryTokenType::Basic( + username.to_string(), + password.to_string(), + ))); + } + return Ok(None); + } + }; + + let mut auth_req = OciRequest::new(challenge.realm) + .query("scope", &format!("repository:{}:pull", image.repository())); + + if let Some(s) = challenge.service { + auth_req = auth_req.query("service", &s); + } + + if let RegistryAuth::Basic(username, password) = authentication { + let creds = proxmox_base64::encode(format!("{username}:{password}")); + auth_req = auth_req.header("Authorization", &format!("Basic {creds}")); + } + + let auth_res = self.send(auth_req)?; + let status = auth_res.status; + let text = auth_res.read_to_string()?; + + if status != StatusCode::OK { + return Err(OciClientError::AuthenticationFailure(text)); + } + + serde_json::from_str::(&text) + .ok() + .as_ref() + .and_then(|j| j["token"].as_str().or(j["access_token"].as_str())) + .map(|t| Some(RegistryTokenType::Bearer(t.into()))) + .ok_or_else(|| { + OciClientError::AuthenticationFailure("Invalid response or missing token".into()) + }) + } + + pub fn list_tags( + &mut self, + image: &Reference, + n: Option, + last: Option<&str>, + ) -> Result { + let url = self.to_v2_url(image, "tags/list")?; + let mut req = OciRequest::new(url.clone()); + if let Some(num) = n { + req = req.query("n", &num.to_string()); + } + if let Some(l) = last { + req = req.query("last", l); + } + + if let Some(auth_token) = self.get_auth_token(image)? { + req = req.with_auth(auth_token); + } + let res = self.send(req)?; + let status = res.status; + let body = res.read_to_end()?; + validate_registry_response(status, &body, &url)?; + Ok(serde_json::from_slice(&body).map_err(OciSpecError::SerDe)?) + } + + pub fn pull_image_manifest( + &mut self, + image: &Reference, + os: Option<&Os>, + arch: Option<&Arch>, + ) -> Result { + let (body, digest, media_type) = self.pull_manifest_raw( + image, + &[ + MediaType::ImageManifest.as_ref(), + MediaType::ImageIndex.as_ref(), + ], + )?; + + if matches!(media_type, MediaType::ImageIndex) { + let index = ImageIndex::from_reader(Cursor::new(&body))?; + + let manifest_digest = index + .manifests() + .iter() + .find(|m| { + m.platform().as_ref().is_none_or(|p| { + arch.is_none_or(|a| p.architecture() == a) && os.is_none_or(|o| p.os() == o) + }) + }) + .map(|m| m.digest().clone()) + .ok_or(OciClientError::NoMatchingManifest)?; + + let manifest_reference = image.clone_with_digest(manifest_digest.to_string()); + let (manifest_raw, manifest_digest, _) = + self.pull_manifest_raw(&manifest_reference, &[MediaType::ImageManifest.as_ref()])?; + let manifest = ImageManifest::from_reader(Cursor::new(&manifest_raw))?; + + Ok(DigestedImageManifest { + manifest, + raw: manifest_raw, + digest: manifest_digest, + }) + } else { + let manifest = ImageManifest::from_reader(Cursor::new(&body))?; + Ok(DigestedImageManifest { + manifest, + raw: body, + digest, + }) + } + } + + pub fn pull_manifest_raw( + &mut self, + image: &Reference, + accepted_media_types: &[&str], + ) -> Result<(Vec, Digest, MediaType), OciClientError> { + let url = self.to_v2_url( + image, + &format!( + "manifests/{}", + image.digest().or_else(|| image.tag()).unwrap_or("latest") + ), + )?; + + let mut req = OciRequest::new(url).with_accept(accepted_media_types); + if let Some(auth_token) = self.get_auth_token(image)? { + req = req.with_auth(auth_token); + } + let res = self.send(req)?; + + let status = res.status; + let url = res.url.clone(); + let headers = res.headers.clone(); + let body = res.read_to_end()?; + validate_registry_response(status, &body, &url)?; + + let expected_digest = image.digest().map(Digest::from_str).transpose()?; + let digest = verify_digest(&body, expected_digest)?; + + let Some(media_type) = headers + .get(http::header::CONTENT_TYPE) + .and_then(|v| v.to_str().ok()) + .map(MediaType::from) + else { + return Err(OciClientError::SpecViolation("Missing Content-Type".into())); + }; + + Ok((body, digest, media_type)) + } + + pub fn pull_image_manifest_and_config( + &mut self, + image: &Reference, + os: Option<&Os>, + arch: Option<&Arch>, + ) -> Result { + let digested_manifest = self.pull_image_manifest(image, os, arch)?; + + let config_descriptor = digested_manifest.manifest.config(); + let mut config_bytes = Vec::new(); + self.pull_blob(image, config_descriptor, &mut config_bytes)?; + + let config = ImageConfiguration::from_reader(Cursor::new(&config_bytes))?; + let digested_config = DigestedImageConfig { + config, + raw: config_bytes, + digest: config_descriptor.digest().clone(), + }; + + Ok(ImageMetadata { + manifest: digested_manifest, + config: digested_config, + }) + } + + pub fn pull_blob( + &mut self, + image: &Reference, + layer: &Descriptor, + out: &mut W, + ) -> Result<(), OciClientError> { + let mut reader = self.pull_blob_reader(image, layer)?; + io::copy(&mut reader, out).map_err(|err| { + err.downcast::() + .map(OciClientError::Digest) + .unwrap_or_else(OciClientError::Io) + })?; + out.flush()?; + + Ok(()) + } + + pub fn pull_blob_reader( + &mut self, + image: &Reference, + layer: &Descriptor, + ) -> Result>, OciClientError> { + let url = self.to_v2_url(image, &format!("blobs/{}", layer.digest()))?; + + let mut request = OciRequest::new(url); + if let Some(auth_token) = self.get_auth_token(image)? { + request = request.with_auth(auth_token); + } + + let response = self.send(request)?; + let status = response.status; + let url = response.url.clone(); + + if !status.is_success() { + let body = response.read_to_end()?; + return Err(validate_registry_response(status, &body, &url) + .expect_err("non-success status code must produce error")); + } + + Ok(VerifyingReader::new( + response.into_body(), + layer.digest().clone(), + )?) + } + + fn to_v2_url(&self, reference: &Reference, suffix: &str) -> Result { + Url::parse(&format!( + "{}://{}/v2/{}/{suffix}", + self.protocol, + reference.resolve_registry(), + reference.repository(), + )) + } + + fn send(&self, req: OciRequest) -> Result { + let url = req.build_url(); + + let headers = req.headers.into_iter().collect(); + + let res = self + .http_client + .get(url.as_str(), Some(&headers)) + .map_err(|e| OciClientError::Transport(e.to_string()))?; + + let (parts, body) = res.into_parts(); + + Ok(OciResponse { + status: parts.status, + headers: parts.headers, + url, + body, + }) + } +} + +fn validate_registry_response( + status: StatusCode, + body: &[u8], + url: &Url, +) -> Result<(), OciClientError> { + match status { + StatusCode::OK => Ok(()), + StatusCode::UNAUTHORIZED => Err(OciClientError::Unauthorized { url: url.clone() }), + s if s.is_success() => Err(OciClientError::SpecViolation(format!( + "Expected HTTP Status 200 OK, got {status} instead" + ))), + s if s.is_client_error() => match serde_json::from_slice::(body) { + Ok(envelope) => Err(OciClientError::Registry { + envelope, + url: url.clone(), + }), + Err(_) => Err(OciClientError::Server { + code: s, + url: url.clone(), + message: String::from_utf8_lossy(body).into_owned(), + }), + }, + s => Err(OciClientError::Server { + code: s, + url: url.clone(), + message: String::from_utf8_lossy(body).into_owned(), + }), + } +} diff --git a/proxmox-oci/src/digest.rs b/proxmox-oci/src/digest.rs index b2170b87..af264f06 100644 --- a/proxmox-oci/src/digest.rs +++ b/proxmox-oci/src/digest.rs @@ -43,6 +43,25 @@ impl Digester { } } +pub fn verify_digest(body: &[u8], expected_digest: Option) -> Result { + let algorithm = expected_digest + .as_ref() + .map(|d| d.algorithm()) + .unwrap_or(&DigestAlgorithm::Sha256); + + let mut digester = Digester::new(algorithm)?; + digester.update(body); + let actual = digester.finalize(); + + if let Some(expected) = expected_digest + && actual != expected + { + return Err(DigestError::Mismatch { expected, actual }); + } + + Ok(actual) +} + pub struct VerifyingReader { inner: R, digester: Digester, diff --git a/proxmox-oci/src/lib.rs b/proxmox-oci/src/lib.rs index fcb81b03..274563f4 100644 --- a/proxmox-oci/src/lib.rs +++ b/proxmox-oci/src/lib.rs @@ -3,6 +3,8 @@ use std::path::Path; pub use oci_spec::image::{Arch, Config, Os}; use thiserror::Error; +pub mod client; + mod digest; mod extract; -- 2.47.3