Skip to content

Commit e08be8a

Browse files
vanitasvitaevanitasvitae
committed
Add javadoc
1 parent cc5890f commit e08be8a

File tree

2 files changed

+273
-0
lines changed

2 files changed

+273
-0
lines changed

‎pg/src/main/java/org/bouncycastle/openpgp/api/OpenPGPCertificate.java

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1812,6 +1812,16 @@ else if (target instanceof OpenPGPUserAttribute)
18121812
}
18131813
}
18141814

1815+
/**
1816+
* Verify a signature of type {@link PGPSignature#PRIMARYKEY_BINDING}, which is typically embedded as
1817+
* {@link org.bouncycastle.bcpg.sig.EmbeddedSignature} inside a signature of type
1818+
* {@link PGPSignature#SUBKEY_BINDING} for a signing capable subkey.
1819+
*
1820+
* @param contentVerifierBuilderProvider provider for content verifier builders
1821+
* @param policy algorithm policy
1822+
* @param signatureCreationTime creation time of the signature
1823+
* @throws PGPSignatureException if an exception happens during signature verification
1824+
*/
18151825
private void verifyEmbeddedPrimaryKeyBinding(PGPContentVerifierBuilderProvider contentVerifierBuilderProvider,
18161826
OpenPGPPolicy policy, Date signatureCreationTime)
18171827
throws PGPSignatureException
@@ -1893,6 +1903,15 @@ private void verifyEmbeddedPrimaryKeyBinding(PGPContentVerifierBuilderProvider c
18931903
throw exception;
18941904
}
18951905

1906+
/**
1907+
* Verify a signature of type {@link PGPSignature#DIRECT_KEY}, {@link PGPSignature#KEY_REVOCATION},
1908+
* {@link PGPSignature#SUBKEY_BINDING} or {@link PGPSignature#SUBKEY_REVOCATION}.
1909+
*
1910+
* @param issuer issuing component key
1911+
* @param target targeted component key
1912+
* @param contentVerifierBuilderProvider provider for content verifier builders
1913+
* @throws PGPSignatureException if an exception happens during signature verification
1914+
*/
18961915
protected void verifyKeySignature(
18971916
OpenPGPComponentKey issuer,
18981917
OpenPGPComponentKey target,
@@ -1931,6 +1950,17 @@ else if (signature.getSignatureType() == PGPSignature.PRIMARYKEY_BINDING)
19311950
}
19321951
}
19331952

1953+
/**
1954+
* Verify a certification signature over an {@link OpenPGPUserId}.
1955+
* The signature is of type {@link PGPSignature#DEFAULT_CERTIFICATION}, {@link PGPSignature#NO_CERTIFICATION},
1956+
* {@link PGPSignature#CASUAL_CERTIFICATION}, {@link PGPSignature#POSITIVE_CERTIFICATION} or
1957+
* {@link PGPSignature#CERTIFICATION_REVOCATION}.
1958+
*
1959+
* @param issuer issuing component key
1960+
* @param target targeted userid
1961+
* @param contentVerifierBuilderProvider provider for content verifier builders
1962+
* @throws PGPSignatureException if an exception happens during signature verification
1963+
*/
19341964
protected void verifyUserIdSignature(OpenPGPComponentKey issuer,
19351965
OpenPGPUserId target,
19361966
PGPContentVerifierBuilderProvider contentVerifierBuilderProvider)
@@ -1953,6 +1983,17 @@ protected void verifyUserIdSignature(OpenPGPComponentKey issuer,
19531983
}
19541984
}
19551985

1986+
/**
1987+
* Verify a certification signature over an {@link OpenPGPUserAttribute}.
1988+
* The signature is of type {@link PGPSignature#DEFAULT_CERTIFICATION}, {@link PGPSignature#NO_CERTIFICATION},
1989+
* {@link PGPSignature#CASUAL_CERTIFICATION}, {@link PGPSignature#POSITIVE_CERTIFICATION} or
1990+
* {@link PGPSignature#CERTIFICATION_REVOCATION}.
1991+
*
1992+
* @param issuer issuing component key
1993+
* @param target targeted userid
1994+
* @param contentVerifierBuilderProvider provider for content verifier builders
1995+
* @throws PGPSignatureException if an exception happens during signature verification
1996+
*/
19561997
protected void verifyUserAttributeSignature(OpenPGPComponentKey issuer,
19571998
OpenPGPUserAttribute target,
19581999
PGPContentVerifierBuilderProvider contentVerifierBuilderProvider)
@@ -2823,13 +2864,20 @@ private OpenPGPSignatureChain(OpenPGPSignatureChain copy)
28232864
this(copy.chainLinks);
28242865
}
28252866

2867+
/**
2868+
* Return the signature from the leaf of the chain, which directly applies to the
2869+
* {@link OpenPGPCertificateComponent}.
2870+
*
2871+
* @return signature
2872+
*/
28262873
public OpenPGPComponentSignature getSignature()
28272874
{
28282875
return getLeafLink().getSignature();
28292876
}
28302877

28312878
/**
28322879
* Return an NEW instance of the {@link OpenPGPSignatureChain} with the new link appended.
2880+
*
28332881
* @param sig signature
28342882
* @return new instance
28352883
*/
@@ -2847,31 +2895,65 @@ public OpenPGPSignatureChain plus(OpenPGPComponentSignature sig)
28472895
return chain;
28482896
}
28492897

2898+
/**
2899+
* Factory method for creating an {@link OpenPGPSignatureChain} with only a single link.
2900+
*
2901+
* @param sig signature
2902+
* @return chain
2903+
*/
28502904
public static OpenPGPSignatureChain direct(OpenPGPComponentSignature sig)
28512905
{
28522906
return new OpenPGPSignatureChain(Link.create(sig));
28532907
}
28542908

2909+
/**
2910+
* Return the very first link in the chain.
2911+
* This is typically a link that originates from the issuing certificates primary key.
2912+
*
2913+
* @return root link
2914+
*/
28552915
public Link getRootLink()
28562916
{
28572917
return chainLinks.get(0);
28582918
}
28592919

2920+
/**
2921+
* Return the issuer of the root link. This is typically the issuing certificates primary key.
2922+
*
2923+
* @return root links issuer
2924+
*/
28602925
public OpenPGPComponentKey getRootLinkIssuer()
28612926
{
28622927
return getRootLink().getSignature().getIssuer();
28632928
}
28642929

2930+
/**
2931+
* Return the last link in the chain, which applies to the chains target component.
2932+
*
2933+
* @return leaf link
2934+
*/
28652935
public Link getLeafLink()
28662936
{
28672937
return chainLinks.get(chainLinks.size() - 1);
28682938
}
28692939

2940+
/**
2941+
* Return the {@link OpenPGPComponentKey} to which the leaf link applies to.
2942+
* For subkey binding signatures, this is the subkey.
2943+
* For user-id certification signatures, it is the primary key.
2944+
*
2945+
* @return target key component of the leaf link
2946+
*/
28702947
public OpenPGPComponentKey getLeafLinkTargetKey()
28712948
{
28722949
return getSignature().getTargetKeyComponent();
28732950
}
28742951

2952+
/**
2953+
* Return true, if the chain only consists of non-revocation signatures and is therefore a certification chain.
2954+
*
2955+
* @return true if the chain is a certification, false if it contains a revocation link.
2956+
*/
28752957
public boolean isCertification()
28762958
{
28772959
for (Link link : chainLinks)
@@ -2884,6 +2966,11 @@ public boolean isCertification()
28842966
return true;
28852967
}
28862968

2969+
/**
2970+
* Return true, if the chain contains at least one revocation signature.
2971+
*
2972+
* @return true if the chain is a revocation.
2973+
*/
28872974
public boolean isRevocation()
28882975
{
28892976
for (Link link : chainLinks)
@@ -2896,6 +2983,11 @@ public boolean isRevocation()
28962983
return false;
28972984
}
28982985

2986+
/**
2987+
* Return true, if the chain contains at least one link that represents a hard revocation.
2988+
*
2989+
* @return true if chain is hard revocation, false if it is a certification or soft revocation
2990+
*/
28992991
public boolean isHardRevocation()
29002992
{
29012993
for (Link link : chainLinks)
@@ -2945,6 +3037,13 @@ public Date getUntil()
29453037
return soonestExpiration;
29463038
}
29473039

3040+
/**
3041+
* Return true if the chain is effective at the given evaluation date, meaning all link signatures have
3042+
* been created before the evaluation time, and none signature expires before the evaluation time.
3043+
*
3044+
* @param evaluationDate reference time
3045+
* @return true if chain is effective at evaluation date
3046+
*/
29483047
public boolean isEffectiveAt(Date evaluationDate)
29493048
{
29503049
if (isHardRevocation())
@@ -2957,6 +3056,12 @@ public boolean isEffectiveAt(Date evaluationDate)
29573056
return !evaluationDate.before(since) && (until == null || !evaluationDate.after(until));
29583057
}
29593058

3059+
/**
3060+
* Return true if the signature chain is valid, meaning all its chain links are valid.
3061+
*
3062+
* @return true if chain is valid
3063+
* @throws PGPSignatureException if an exception occurs during signature verification
3064+
*/
29603065
public boolean isValid()
29613066
throws PGPSignatureException
29623067
{
@@ -2969,6 +3074,14 @@ public boolean isValid()
29693074
return isValid(cert.implementation.pgpContentVerifierBuilderProvider(), cert.policy);
29703075
}
29713076

3077+
/**
3078+
* Return true if the signature chain is valid, meaning all its chain links are valid.
3079+
*
3080+
* @param contentVerifierBuilderProvider provider for content verifier builders
3081+
* @param policy algorithm policy
3082+
* @return true if chain is valid
3083+
* @throws PGPSignatureException if an exception occurs during signature verification
3084+
*/
29723085
public boolean isValid(PGPContentVerifierBuilderProvider contentVerifierBuilderProvider, OpenPGPPolicy policy)
29733086
throws PGPSignatureException
29743087
{
@@ -3056,11 +3169,24 @@ public Link(OpenPGPComponentSignature signature)
30563169
this.signature = signature;
30573170
}
30583171

3172+
/**
3173+
* Return the {@link Date} since when the link is effective.
3174+
* This is the creation time of the signature.
3175+
*
3176+
* @return signature creation time
3177+
*/
30593178
public Date since()
30603179
{
30613180
return signature.getCreationTime();
30623181
}
30633182

3183+
/**
3184+
* Return the {@link Date} until the signature is effective.
3185+
* This is, depending on which event is earlier in time, either the signature expiration time,
3186+
* or the key expiration time.
3187+
*
3188+
* @return time until the link is valid
3189+
*/
30643190
public Date until()
30653191
{
30663192
Date backSigExpiration = getBackSigExpirationTime();
@@ -3078,6 +3204,11 @@ public Date until()
30783204
return backSigExpiration;
30793205
}
30803206

3207+
/**
3208+
* Return the expiration time of the primary key binding signature.
3209+
*
3210+
* @return primary key binding signature expiration time
3211+
*/
30813212
private Date getBackSigExpirationTime()
30823213
{
30833214
if (signature.getSignature().getSignatureType() != PGPSignature.SUBKEY_BINDING)
@@ -3116,6 +3247,14 @@ private Date getBackSigExpirationTime()
31163247
}
31173248
}
31183249

3250+
/**
3251+
* Verify the link signature.
3252+
*
3253+
* @param contentVerifierBuilderProvider provider for content verifier builders
3254+
* @param policy algorithm policy
3255+
* @return true if the signature is valid, false otherwise
3256+
* @throws PGPSignatureException if an exception occurs during signature verification
3257+
*/
31193258
public boolean verify(PGPContentVerifierBuilderProvider contentVerifierBuilderProvider,
31203259
OpenPGPPolicy policy)
31213260
throws PGPSignatureException
@@ -3130,6 +3269,14 @@ public String toString()
31303269
return signature.toString();
31313270
}
31323271

3272+
/**
3273+
* Factory method for creating Links from component signatures.
3274+
* Returns either a {@link Certification} in case the signature is a binding,
3275+
* or a {@link Revocation} in case the signature is a revocation signature.
3276+
*
3277+
* @param signature component signature
3278+
* @return link
3279+
*/
31333280
public static Link create(OpenPGPComponentSignature signature)
31343281
{
31353282
if (signature.isRevocation())
@@ -3142,6 +3289,11 @@ public static Link create(OpenPGPComponentSignature signature)
31423289
}
31433290
}
31443291

3292+
/**
3293+
* Return the signature of the link.
3294+
*
3295+
* @return signature
3296+
*/
31453297
public OpenPGPComponentSignature getSignature()
31463298
{
31473299
return signature;
@@ -3218,18 +3370,29 @@ public OpenPGPSignatureChains(OpenPGPCertificateComponent component)
32183370

32193371
/**
32203372
* Add a single chain to the collection.
3373+
*
32213374
* @param chain chain
32223375
*/
32233376
public void add(OpenPGPSignatureChain chain)
32243377
{
32253378
this.chains.add(chain);
32263379
}
32273380

3381+
/**
3382+
* Add all chains to the collection.
3383+
*
3384+
* @param otherChains other chains
3385+
*/
32283386
public void addAll(OpenPGPSignatureChains otherChains)
32293387
{
32303388
this.chains.addAll(otherChains.chains);
32313389
}
32323390

3391+
/**
3392+
* Return true if the collection is empty.
3393+
*
3394+
* @return true if empty
3395+
*/
32333396
public boolean isEmpty()
32343397
{
32353398
return chains.isEmpty();
@@ -3254,6 +3417,12 @@ public OpenPGPSignatureChain getCertificationAt(Date evaluationTime)
32543417
return null;
32553418
}
32563419

3420+
/**
3421+
* Return all {@link OpenPGPSignatureChain} objects, which are valid at the given evaluation time.
3422+
*
3423+
* @param evaluationTime reference time
3424+
* @return valid chains at reference time
3425+
*/
32573426
public OpenPGPSignatureChains getChainsAt(Date evaluationTime)
32583427
{
32593428
OpenPGPSignatureChains effectiveChains = new OpenPGPSignatureChains(targetComponent);
@@ -3269,6 +3438,7 @@ public OpenPGPSignatureChains getChainsAt(Date evaluationTime)
32693438

32703439
/**
32713440
* Return a negative certification chain for the component for the given evaluationTime.
3441+
*
32723442
* @param evaluationTime time for which revocation-ness of the {@link OpenPGPCertificateComponent} is checked.
32733443
* @return negative certification chain or null
32743444
*/
@@ -3301,6 +3471,12 @@ public String toString()
33013471
return b.toString();
33023472
}
33033473

3474+
/**
3475+
* Return all {@link OpenPGPSignatureChain} items which originate from the root {@link OpenPGPComponentKey}.
3476+
*
3477+
* @param root root key
3478+
* @return all chains with root key as origin
3479+
*/
33043480
public OpenPGPSignatureChains fromOrigin(OpenPGPComponentKey root)
33053481
{
33063482
OpenPGPSignatureChains chainsFromRoot = new OpenPGPSignatureChains(root);
@@ -3315,6 +3491,12 @@ public OpenPGPSignatureChains fromOrigin(OpenPGPComponentKey root)
33153491
return chainsFromRoot;
33163492
}
33173493

3494+
/**
3495+
* Return the latest chain, which is valid at the given evaluation time.
3496+
*
3497+
* @param evaluationDate reference time
3498+
* @return latest valid chain
3499+
*/
33183500
public OpenPGPSignatureChain getChainAt(Date evaluationDate)
33193501
{
33203502
OpenPGPSignatureChains atDate = getChainsAt(evaluationDate);

0 commit comments

Comments
 (0)