001/*
002 * oauth2-oidc-sdk
003 *
004 * Copyright 2012-2016, Connect2id Ltd and contributors.
005 *
006 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use
007 * this file except in compliance with the License. You may obtain a copy of the
008 * License at
009 *
010 *    http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software distributed
013 * under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
014 * CONDITIONS OF ANY KIND, either express or implied. See the License for the
015 * specific language governing permissions and limitations under the License.
016 */
017
018package com.nimbusds.openid.connect.sdk;
019
020
021import net.jcip.annotations.Immutable;
022
023import com.nimbusds.oauth2.sdk.ResponseType;
024import com.nimbusds.oauth2.sdk.id.Identifier;
025import com.nimbusds.oauth2.sdk.util.StringUtils;
026
027
028/**
029 * Nonce. This is a random, unique string value to associate a user-session 
030 * with an ID Token and to mitigate replay attacks.
031 *
032 * <p>Example generation of a 16 byte random nonce:
033 *
034 * <pre>
035 * Nonce nonce = new Nonce(16);
036 * </pre>
037 *
038 * <p>Related specifications:
039 *
040 * <ul>
041 *     <li>OpenID Connect Core 1.0, section 3.1.2.1. and 15.5.2.
042 * </ul>
043 */
044@Immutable
045public final class Nonce extends Identifier {
046        
047        
048        private static final long serialVersionUID = 1484679928325180239L;
049        
050        
051        /**
052         * Creates a new nonce with the specified value.
053         *
054         * @param value The nonce value. Must not be {@code null} or empty 
055         *              string.
056         */
057        public Nonce(final String value) {
058        
059                super(value);
060        }
061
062
063        /**
064         * Creates a new nonce with a randomly generated value of the specified
065         * byte length, Base64URL-encoded.
066         *
067         * @param byteLength The byte length of the value to generate. Must be
068         *                   greater than one.
069         */
070        public Nonce(final int byteLength) {
071        
072                super(byteLength);
073        }
074        
075        
076        /**
077         * Creates a new nonce with a randomly generated 256-bit (32-byte) 
078         * value, Base64URL-encoded.
079         */
080        public Nonce() {
081
082                super();
083        }
084        
085        
086        @Override
087        public boolean equals(final Object object) {
088        
089                return object instanceof Nonce &&
090                       this.toString().equals(object.toString());
091        }
092        
093        
094        /**
095         * Parses a nonce from the specified string.
096         *
097         * @param s The string to parse, {@code null} or empty if no nonce is
098         *          specified.
099         *
100         * @return The nonce, {@code null} if the parsed string was 
101         *         {@code null} or empty.
102         */
103        public static Nonce parse(final String s) {
104        
105                if (StringUtils.isBlank(s))
106                        return null;
107                
108                return new Nonce(s);
109        }
110        
111        
112        /**
113         * Returns {@code true} if the specified OAuth 2.0 response type
114         * requires a nonce.
115         *
116         * @param responseType The response type. Must not be {@code null}.
117         *
118         * @return {@code true} if a nonce is required, {@code false} if not.
119         */
120        public static boolean isRequired(final ResponseType responseType) {
121                
122                return
123                        // implicit https://openid.net/specs/openid-connect-core-1_0-27.html#ImplicitAuthRequest
124                        responseType.equals(ResponseType.IDTOKEN) || responseType.equals(ResponseType.IDTOKEN_TOKEN)
125                        
126                        ||
127                        
128                        // hybrid https://openid.net/specs/openid-connect-core-1_0-27.html#HybridAuthRequest
129                        responseType.equals(ResponseType.CODE_IDTOKEN) || responseType.equals(ResponseType.CODE_IDTOKEN_TOKEN);
130        }
131}