001/*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 *   http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing,
013 * software distributed under the License is distributed on an
014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 * KIND, either express or implied.  See the License for the
016 * specific language governing permissions and limitations
017 * under the License.
018 */
019package org.eclipse.aether.spi.checksums;
020
021import java.io.IOException;
022import java.util.List;
023import java.util.Map;
024
025import org.eclipse.aether.RepositorySystemSession;
026import org.eclipse.aether.artifact.Artifact;
027import org.eclipse.aether.metadata.Metadata;
028import org.eclipse.aether.repository.ArtifactRepository;
029import org.eclipse.aether.spi.connector.checksum.ChecksumAlgorithmFactory;
030
031/**
032 * Component able to provide (trusted) checksums for artifacts.
033 * <p>
034 * Note: the "trusted" meaning depends solely on implementation and the user using it. Resolver itself does nothing
035 * for "trust" (like some crypto magic or what not). It all boils down that the source being used by implementation is
036 * "trusted" by user or not.
037 *
038 * @since 1.9.0
039 */
040public interface TrustedChecksumsSource {
041    /**
042     * May return the trusted checksums (for given artifact) from trusted source, or {@code null} if not enabled.
043     * Enabled trusted checksum source SHOULD return non-null (empty map) result, when it has no data for given
044     * artifact. Empty map means in this case "no information", but how that case is interpreted depends on consumer
045     * for trusted checksums.
046     *
047     * @param session                    The repository system session, never {@code null}.
048     * @param artifact                   The artifact we want checksums for, never {@code null}.
049     * @param artifactRepository         The origin repository: local, workspace, remote repository, never {@code null}.
050     * @param checksumAlgorithmFactories The checksum algorithms that are expected, never {@code null}.
051     * @return Map of expected checksums, or {@code null} if not enabled.
052     */
053    Map<String, String> getTrustedArtifactChecksums(
054            RepositorySystemSession session,
055            Artifact artifact,
056            ArtifactRepository artifactRepository,
057            List<ChecksumAlgorithmFactory> checksumAlgorithmFactories);
058
059    /**
060     * May return the trusted checksums (for given metadata) from trusted source, or {@code null} if not enabled
061     * or the implementation does not cover metadata. Semantics are the same as for
062     * {@link #getTrustedArtifactChecksums(RepositorySystemSession, Artifact, ArtifactRepository, List)}, but
063     * covering metadata: metadata like {@code maven-metadata.xml} influences resolution decisions (for example
064     * version range selection), so trusted sources able to attest metadata should expose that here.
065     * <p>
066     * The default implementation returns {@code null} ("not enabled for metadata"), preserving the behavior of
067     * implementations written before this method existed.
068     *
069     * @param session                    The repository system session, never {@code null}.
070     * @param metadata                   The metadata we want checksums for, never {@code null}.
071     * @param artifactRepository         The origin repository: local, workspace, remote repository, never {@code null}.
072     * @param checksumAlgorithmFactories The checksum algorithms that are expected, never {@code null}.
073     * @return Map of expected checksums, or {@code null}.
074     * @since 2.0.23
075     */
076    default Map<String, String> getTrustedMetadataChecksums(
077            RepositorySystemSession session,
078            Metadata metadata,
079            ArtifactRepository artifactRepository,
080            List<ChecksumAlgorithmFactory> checksumAlgorithmFactories) {
081        return null;
082    }
083
084    /**
085     * A writer that is able to write/add trusted checksums to this implementation.
086     */
087    interface Writer {
088        /**
089         * Performs whatever implementation requires to "set" (write/add/append) given map of trusted checksums.
090         * The passed in list of checksum algorithm factories and the map must have equal size and mapping must
091         * contain all algorithm names in list.
092         */
093        void addTrustedArtifactChecksums(
094                Artifact artifact,
095                ArtifactRepository artifactRepository,
096                List<ChecksumAlgorithmFactory> checksumAlgorithmFactories,
097                Map<String, String> trustedArtifactChecksums)
098                throws IOException;
099
100        /**
101         * Performs whatever implementation requires to "set" (write/add/append) given map of trusted checksums,
102         * for given metadata. Semantics are the same as for
103         * {@link #addTrustedArtifactChecksums(Artifact, ArtifactRepository, List, Map)}, but covering metadata.
104         * <p>
105         * The default implementation records nothing, preserving the behavior of implementations written before
106         * this method existed.
107         *
108         * @since 2.0.23
109         */
110        default void addTrustedMetadataChecksums(
111                Metadata metadata,
112                ArtifactRepository artifactRepository,
113                List<ChecksumAlgorithmFactory> checksumAlgorithmFactories,
114                Map<String, String> trustedMetadataChecksums)
115                throws IOException {
116            // no-op: implementations written before this method existed record artifact checksums only
117        }
118    }
119
120    /**
121     * Some trusted checksums sources may implement this optional method: ability to write/add checksums to them.
122     * If source does not support this feature, method should return {@code null}.
123     */
124    Writer getTrustedArtifactChecksumsWriter(RepositorySystemSession session);
125}