PublicKeyCredentialHint.java

1
// Copyright (c) 2018, Yubico AB
2
// All rights reserved.
3
//
4
// Redistribution and use in source and binary forms, with or without
5
// modification, are permitted provided that the following conditions are met:
6
//
7
// 1. Redistributions of source code must retain the above copyright notice, this
8
//    list of conditions and the following disclaimer.
9
//
10
// 2. Redistributions in binary form must reproduce the above copyright notice,
11
//    this list of conditions and the following disclaimer in the documentation
12
//    and/or other materials provided with the distribution.
13
//
14
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
15
// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16
// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
17
// DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
18
// FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19
// DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
20
// SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
21
// CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
22
// OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
23
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
24
25
package com.yubico.webauthn.data;
26
27
import com.fasterxml.jackson.annotation.JsonCreator;
28
import com.fasterxml.jackson.annotation.JsonValue;
29
import com.yubico.webauthn.RelyingParty.RelyingPartyBuilder;
30
import com.yubico.webauthn.StartAssertionOptions;
31
import com.yubico.webauthn.StartAssertionOptions.StartAssertionOptionsBuilder;
32
import com.yubico.webauthn.StartRegistrationOptions;
33
import com.yubico.webauthn.StartRegistrationOptions.StartRegistrationOptionsBuilder;
34
import com.yubico.webauthn.attestation.AttestationTrustSource;
35
import java.util.stream.Stream;
36
import lombok.AccessLevel;
37
import lombok.AllArgsConstructor;
38
import lombok.NonNull;
39
import lombok.Value;
40
41
/**
42
 * Hints to guide the user agent in interacting with the user.
43
 *
44
 * <p>For example, the {@link PublicKeyCredentialHint#SECURITY_KEY} hint may be used to ask the
45
 * client to emphasize the option of using an external security key, or the {@link
46
 * PublicKeyCredentialHint#CLIENT_DEVICE} hint may be used to ask the client to emphasize the option
47
 * of using a built-in passkey provider.
48
 *
49
 * <p>These hints are not requirements, and do not bind the user-agent, but may guide it in
50
 * providing the best experience by using contextual information about the request.
51
 *
52
 * @see StartRegistrationOptions#getHints()
53
 * @see StartAssertionOptions#getHints()
54
 * @see <a
55
 *     href="https://www.w3.org/TR/2023/WD-webauthn-3-20230927/#dom-publickeycredentialcreationoptions-hints">PublicKeyCredentialCreationOptions.hints</a>
56
 * @see <a
57
 *     href="https://www.w3.org/TR/2023/WD-webauthn-3-20230927/#dom-publickeycredentialrequestoptions-hints">PublicKeyCredentialRequestOptions.hints</a>
58
 * @see <a
59
 *     href="https://www.w3.org/TR/2023/WD-webauthn-3-20230927/#enumdef-publickeycredentialhints">§5.8.7.
60
 *     User-agent Hints Enumeration (enum PublicKeyCredentialHints)</a>
61
 */
62
@Value
63
@AllArgsConstructor(access = AccessLevel.PRIVATE)
64
public class PublicKeyCredentialHint {
65
66
  @JsonValue @NonNull private final String value;
67
68
  /**
69
   * Indicates that the application believes that users will satisfy this request with a physical
70
   * security key.
71
   *
72
   * <p>For example, an enterprise application may set this hint if they have issued security keys
73
   * to their employees and will only accept those authenticators for registration and
74
   * authentication. In that case, the application should probably also set {@link
75
   * RelyingPartyBuilder#attestationTrustSource(AttestationTrustSource) attestationTrustSource} and
76
   * set {@link RelyingPartyBuilder#allowUntrustedAttestation(boolean) allowUntrustedAttestation} to
77
   * <code>false</code>. See also the <a
78
   * href="https://developers.yubico.com/java-webauthn-server/webauthn-server-attestation/"><code>
79
   * webauthn-server-attestation</code> module</a>.
80
   *
81
   * <p>For compatibility with older user agents, when this hint is used in {@link
82
   * StartRegistrationOptions}, the <code>
83
   * {@link StartRegistrationOptionsBuilder#authenticatorSelection(AuthenticatorSelectionCriteria) authenticatorSelection}.{@link AuthenticatorSelectionCriteria.AuthenticatorSelectionCriteriaBuilder#authenticatorAttachment(AuthenticatorAttachment) authenticatorAttachment}
84
   * </code> parameter SHOULD be set to {@link AuthenticatorAttachment#CROSS_PLATFORM}.
85
   *
86
   * @see StartRegistrationOptionsBuilder#hints(PublicKeyCredentialHint...)
87
   * @see StartAssertionOptionsBuilder#hints(PublicKeyCredentialHint...)
88
   * @see <a
89
   *     href="https://www.w3.org/TR/2023/WD-webauthn-3-20230927/#dom-publickeycredentialhints-security-key">
90
   *     <code>security-key</code> in §5.8.7. User-agent Hints Enumeration (enum
91
   *     PublicKeyCredentialHints) </a>
92
   * @see <a
93
   *     href="https://www.w3.org/TR/2023/WD-webauthn-3-20230927/#enumdef-publickeycredentialhints">§5.8.7.
94
   *     User-agent Hints Enumeration (enum PublicKeyCredentialHints)</a>
95
   */
96
  public static final PublicKeyCredentialHint SECURITY_KEY =
97
      new PublicKeyCredentialHint("security-key");
98
99
  /**
100
   * Indicates that the application believes that users will satisfy this request with an
101
   * authenticator built into the client device.
102
   *
103
   * <p>For compatibility with older user agents, when this hint is used in {@link
104
   * StartRegistrationOptions}, the <code>
105
   * {@link StartRegistrationOptionsBuilder#authenticatorSelection(AuthenticatorSelectionCriteria) authenticatorSelection}.{@link AuthenticatorSelectionCriteria.AuthenticatorSelectionCriteriaBuilder#authenticatorAttachment(AuthenticatorAttachment) authenticatorAttachment}
106
   * </code> parameter SHOULD be set to {@link AuthenticatorAttachment#PLATFORM}.
107
   *
108
   * @see StartRegistrationOptionsBuilder#hints(PublicKeyCredentialHint...)
109
   * @see StartAssertionOptionsBuilder#hints(PublicKeyCredentialHint...)
110
   * @see <a
111
   *     href="https://www.w3.org/TR/2023/WD-webauthn-3-20230927/#dom-publickeycredentialhints-client-device">
112
   *     <code>client-device</code> in §5.8.7. User-agent Hints Enumeration (enum
113
   *     PublicKeyCredentialHints) </a>
114
   * @see <a
115
   *     href="https://www.w3.org/TR/2023/WD-webauthn-3-20230927/#enumdef-publickeycredentialhints">§5.8.7.
116
   *     User-agent Hints Enumeration (enum PublicKeyCredentialHints)</a>
117
   */
118
  public static final PublicKeyCredentialHint CLIENT_DEVICE =
119
      new PublicKeyCredentialHint("client-device");
120
121
  /**
122
   * Indicates that the application believes that users will satisfy this request with
123
   * general-purpose authenticators such as smartphones. For example, a consumer application may
124
   * believe that only a small fraction of their customers possesses dedicated security keys. This
125
   * option also implies that the local platform authenticator should not be promoted in the UI.
126
   *
127
   * <p>For compatibility with older user agents, when this hint is used in {@link
128
   * StartRegistrationOptions}, the <code>
129
   * {@link StartRegistrationOptionsBuilder#authenticatorSelection(AuthenticatorSelectionCriteria) authenticatorSelection}.{@link AuthenticatorSelectionCriteria.AuthenticatorSelectionCriteriaBuilder#authenticatorAttachment(AuthenticatorAttachment) authenticatorAttachment}
130
   * </code> parameter SHOULD be set to {@link AuthenticatorAttachment#CROSS_PLATFORM}.
131
   *
132
   * @see StartRegistrationOptionsBuilder#hints(PublicKeyCredentialHint...)
133
   * @see StartAssertionOptionsBuilder#hints(PublicKeyCredentialHint...)
134
   * @see <a
135
   *     href="https://www.w3.org/TR/2023/WD-webauthn-3-20230927/#dom-publickeycredentialhints-hybrid">
136
   *     <code>hybrid</code> in §5.8.7. User-agent Hints Enumeration (enum PublicKeyCredentialHints)
137
   *     </a>
138
   * @see <a
139
   *     href="https://www.w3.org/TR/2023/WD-webauthn-3-20230927/#enumdef-publickeycredentialhints">§5.8.7.
140
   *     User-agent Hints Enumeration (enum PublicKeyCredentialHints)</a>
141
   */
142
  public static final PublicKeyCredentialHint HYBRID = new PublicKeyCredentialHint("hybrid");
143
144
  /**
145
   * @return An array containing all predefined values of {@link PublicKeyCredentialHint} known by
146
   *     this implementation.
147
   */
148
  public static PublicKeyCredentialHint[] values() {
149 1 1. values : replaced return value with null for com/yubico/webauthn/data/PublicKeyCredentialHint::values → KILLED
    return new PublicKeyCredentialHint[] {SECURITY_KEY, CLIENT_DEVICE, HYBRID};
150
  }
151
152
  /**
153
   * @return If <code>value</code> is the same as that of any of {@link #SECURITY_KEY}, {@link
154
   *     #CLIENT_DEVICE} or {@link #HYBRID}, returns that constant instance. Otherwise returns a new
155
   *     instance containing <code>value</code>.
156
   * @see #valueOf(String)
157
   */
158
  @JsonCreator
159 1 1. of : negated conditional → KILLED
  public static PublicKeyCredentialHint of(@NonNull String value) {
160 1 1. of : replaced return value with null for com/yubico/webauthn/data/PublicKeyCredentialHint::of → KILLED
    return Stream.of(values())
161 2 1. lambda$of$0 : replaced boolean return with false for com/yubico/webauthn/data/PublicKeyCredentialHint::lambda$of$0 → SURVIVED
2. lambda$of$0 : replaced boolean return with true for com/yubico/webauthn/data/PublicKeyCredentialHint::lambda$of$0 → KILLED
        .filter(v -> v.getValue().equals(value))
162
        .findAny()
163 1 1. lambda$of$1 : replaced return value with null for com/yubico/webauthn/data/PublicKeyCredentialHint::lambda$of$1 → KILLED
        .orElseGet(() -> new PublicKeyCredentialHint(value));
164
  }
165
166
  /**
167
   * @return If <code>name</code> equals <code>"SECURITY_KEY"</code>, <code>"CLIENT_DEVICE"</code>
168
   *     or <code>"HYBRID"</code>, returns the constant by that name.
169
   * @throws IllegalArgumentException if <code>name</code> is anything else.
170
   * @see #of(String)
171
   */
172
  public static PublicKeyCredentialHint valueOf(String name) {
173
    switch (name) {
174
      case "SECURITY_KEY":
175 1 1. valueOf : replaced return value with null for com/yubico/webauthn/data/PublicKeyCredentialHint::valueOf → NO_COVERAGE
        return SECURITY_KEY;
176
      case "CLIENT_DEVICE":
177 1 1. valueOf : replaced return value with null for com/yubico/webauthn/data/PublicKeyCredentialHint::valueOf → NO_COVERAGE
        return CLIENT_DEVICE;
178
      case "HYBRID":
179 1 1. valueOf : replaced return value with null for com/yubico/webauthn/data/PublicKeyCredentialHint::valueOf → NO_COVERAGE
        return HYBRID;
180
      default:
181
        throw new IllegalArgumentException(
182
            "No constant com.yubico.webauthn.data.PublicKeyCredentialHint." + name);
183
    }
184
  }
185
}

Mutations

149

1.1
Location : values
Killed by : com.yubico.webauthn.RelyingPartyStartOperationSpec
replaced return value with null for com/yubico/webauthn/data/PublicKeyCredentialHint::values → KILLED

159

1.1
Location : of
Killed by : com.yubico.webauthn.RelyingPartyStartOperationSpec
negated conditional → KILLED

160

1.1
Location : of
Killed by : com.yubico.webauthn.RelyingPartyStartOperationSpec
replaced return value with null for com/yubico/webauthn/data/PublicKeyCredentialHint::of → KILLED

161

1.1
Location : lambda$of$0
Killed by : none
replaced boolean return with false for com/yubico/webauthn/data/PublicKeyCredentialHint::lambda$of$0 → SURVIVED

2.2
Location : lambda$of$0
Killed by : com.yubico.webauthn.RelyingPartyStartOperationSpec
replaced boolean return with true for com/yubico/webauthn/data/PublicKeyCredentialHint::lambda$of$0 → KILLED

163

1.1
Location : lambda$of$1
Killed by : com.yubico.webauthn.RelyingPartyStartOperationSpec
replaced return value with null for com/yubico/webauthn/data/PublicKeyCredentialHint::lambda$of$1 → KILLED

175

1.1
Location : valueOf
Killed by : none
replaced return value with null for com/yubico/webauthn/data/PublicKeyCredentialHint::valueOf → NO_COVERAGE

177

1.1
Location : valueOf
Killed by : none
replaced return value with null for com/yubico/webauthn/data/PublicKeyCredentialHint::valueOf → NO_COVERAGE

179

1.1
Location : valueOf
Killed by : none
replaced return value with null for com/yubico/webauthn/data/PublicKeyCredentialHint::valueOf → NO_COVERAGE

Active mutators

Tests examined


Report generated by PIT 1.15.0